How to Write a Web Improvement Specification

Tomohiro Iida · Published August 2, 2026 · Updated September 7, 2026

Receiving an analysis does not mean a production partner or internal engineer can start the same day. In many cases the document stops at describing the current state, and it is not clear which file or setting to change, or what the new wording should be. A web improvement specification is the document that connects analysis to implementation: one sheet per issue, covering everything from the target URL to completion criteria and evaluation metrics.

What this article covers and what it does not

• Covered: the fourteen fields of an improvement specification and how to write each one.
• Covered: a worked example with every field completed.
• Covered: how to set completion criteria and verification timing.
• Covered: the prerequisites to confirm before handing the sheet to a production partner.
• Not covered: the organizational reasons improvements stall, which are handled in the article on why SEO reports do not get implemented.
• Not covered: the scope and delivery approach of Netsujo SIGNAL, which are described on the service page.

A report and a specification differ in whether the next action is unambiguous

The dividing line is not length or the number of charts. It is whether the implementer can decide the next action without asking a question. A report explains rankings, impressions, traffic, competitor gaps, and technical errors. A specification states the target URL, the place to change, the new copy or code, the owner, the completion criteria, and the verification steps.

This test is our own operating guideline, not a universal rule. Where an in-house implementation team already shares the context, some fields can be shortened.

The fourteen fields

The free diagnosis returns confirmed facts from public information, the hypothesis most likely blocking enquiries, the target URL, the first correction instruction, completion criteria, validation steps, recommended owner, and estimated effort as one trace.

Classify the root cause before describing it

Free-text root causes make ownership inconsistent. We select one of eight categories first, then write the explanation. These categories are our operating guideline.

• Content gap
• Information architecture
• Rendering
• Structured data
• Internal links
• Conversion path
• Measurement
• Inconsistent wording

Before implementing, check whether the issue still exists

Do not implement every finding as issued. Check each one against the published page and the code at the moment work starts. What was an issue at diagnosis time may already have been resolved by another change. Do not rebuild a condition that is already met; record the evidence instead.

Keep the original finding as history and add the judgement made at the point of checking. The reasoning is not “this finding is old, so skip it” but “this acceptance criterion is currently met here”. Skipping this re-check produces work that rebuilds problems that were already fixed.

Worked example: a service page title that does not match search intent

The following is a generic example written to explain the format. It is not a client engagement. For a service page whose title remains the template default, the sheet records the target URL, the impressions-versus-clicks gap as the symptom, the current title as the confirmed fact, inconsistent wording as the root cause, the metadata generation in the service template as the target component, the exact replacement title and description as the change, a high priority with mixed ownership and S effort, completion criteria based on the published HTML, release-day verification of the production HTML and other service pages, and a 28-day comparison of impressions, clicks, click-through rate, and average position against a baseline saved before release.

Why symptom, fact, and root cause are written separately

• The observed symptom explains to management or the requester why the work matters.
• The confirmed fact lets the implementer reproduce the current state and compare before and after.
• The implementation root cause determines which place to touch.

Separating them also allows diagnosis when a change does not work: it becomes possible to review whether the fact was observed correctly or the interpretation of the cause was wrong, instead of discarding the whole initiative. Record confirmed evidence as fact and inference as inference, and attach a way to test each hypothesis.

How to set completion criteria

Write completion criteria as a state that any reviewer would judge identically after release, and do not use a change in a metric. Rankings, clicks, and enquiry counts move for reasons outside the change, so using them makes correct implementations look incomplete and incomplete ones look finished.

• The published HTML on the production URL contains the new wording.
• No unintended change appears on pages outside the scope.
• The target element is visible and operable at smartphone width.
• Structured data matches the visible content.
• Measurement events fire once with the expected name and parameters.
• Factual statements match between the Japanese and English versions.

Why release-day verification and 28-day evaluation are separate

Release-day verification confirms that the implementation is correct and that nothing else broke, so a problem can be reverted the same day. The 28-day evaluation observes the demand side, where recrawling, ranking movement, and user behaviour take time to appear.

The 28-day window is our operating guideline, not a universal rule; sites updated infrequently or with strong seasonality need a longer comparison window. Save the baseline before release, and record any other changes released in the same period. Without measured causality, do not state that a change caused a metric to move.

Separate implementation, production release, the tracking record, and effect

That a change exists in the code, that it has reached production, that the tracking record shows it as done, and that an effect has been observed are four separate states. Do not collapse them into one “complete”.

If the issue tracker still shows an item as not started, do not immediately re-implement the same code. First find out which of implementation, production, and record is out of step. When correcting a record, name only the items you hold evidence for, and do not relax the normal update procedure wholesale.

Attach an acceptance record to the fourteen fields

There is no need to keep adding fields. Attach a short supporting record that links the existing issue ID to the evidence for implementation and release.

• Issue ID and specification version
• Judgement before starting: outstanding, already met, partly met, premise changed, or unconfirmed
• Implementation evidence: the target version of code, CMS, or settings
• Production check: URL, served version, time verified, verification result
• Tracking record: issue ID, implementation timestamp, and evidence reference all agreeing
• Remaining checks: missing permissions and unverified items
• Effect observation: period, metric, concurrent changes — or “not observed”
• Acceptance decision-maker and decision date

Pick one item that currently shows as not started and confirm the four states separately. If it is implemented, move to checking the evidence; if it was never released, check the delivery; if only the record disagrees, apply a narrowly scoped correction. The aim is a trail linking acceptance criteria to evidence, not a count of completed items.

Handing the sheet to a production partner

Confirm permissions, environment, and release unit before handing over. Permissions include CMS and template editing, repository access and deployment, tag-manager publishing, analytics configuration, and domain settings when redirects are involved. State who performs each step when permissions are split between the client and the partner.

For environment, share whether the change belongs in the CMS or the code, where metadata is generated, whether the content appears in the initial HTML or after JavaScript execution, whether languages must stay in sync, whether existing measurement tags overlap, and what can be checked in a staging environment.

Keep one specification to one release. Bundling several issues into a single release makes it impossible to attribute the 28-day result. When several changes ship on the same day, record the release date and scope and note them together during evaluation.

Common gaps that stop implementation

When a field cannot be completed, recording that it is unconfirmed and how it will be confirmed moves implementation further than leaving it blank.

Summary

Writing one specification for your own site is the fastest way to see which information is missing. The Netsujo SIGNAL free diagnosis returns the first correction instruction in this format, based on public information.

See the Netsujo SIGNAL service

See a Netsujo SIGNAL free diagnosis report example

Why SEO reports fail to become implemented improvements

How to diagnose low B2B website enquiries

How to improve a site without replacing the production company