How to Write a Web Change Specification

Tomohiro Iida · Published August 2, 2026 · Updated August 2, 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 change 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 a change 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

Field	What to record
Issue ID	A unique identifier reused in discussions, tickets, and release notes
Target URL	The full URL to change; split multiple pages into separate issues
Observed symptom	The result visible in data or on screen, without the cause mixed in
Confirmed fact	The state confirmed in the page, HTML, settings, or measurement data, with the date and source
Implementation root cause	The implementation-side reason for the symptom; label it as a hypothesis when unproven
Target component or setting	The file, template, CMS field, or tag-manager setting to touch
Change	The new copy, structure, or code, written as work instructions
Reason for the change	Why the change addresses the symptom, connecting fact and root cause
Priority	High, medium, or low, based on business impact and confidence
Recommended owner	Business, editorial, design, development, analytics, or mixed
Estimated effort	S, M, or L as relative weight rather than an hour estimate
Completion criteria	A state observable after release; not a change in a metric
Verification at release	The checks performed on release day, including regression checks
Evaluation metric after 28 days	The metrics and comparison window, with the baseline recorded

The Mini ChangeSpec issued with our free diagnosis uses almost the same fields: priority, target URL, target surface, observed facts, root-cause type, change steps, completion criteria, validation steps, recommended owner, estimated effort, success metrics, and the internal access required.

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

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.

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

Pattern	What happens	How to fix it
The target is written only as “the service page”	A round trip is needed to identify the page	Split into one URL per issue
Symptom and cause share one field	A failed change cannot be diagnosed	Separate the fields and classify the cause
The change stops at a direction	The implementer has to produce the copy	Write the exact replacement wording
Completion criteria use metric improvement	Completion cannot be judged	Restate as an observable published state
No verification steps	Regressions are missed on release day	List the URLs and checks
No baseline saved	No comparison is possible after 28 days	Capture it the day before release
Permissions unassigned	Work stops just before it starts	Name the required permissions and performer
Everything marked high priority	The order of work is undecided	Rescore by business impact and confidence

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

Key takeaways

Write one sheet per issue with all fourteen fields.
Keep symptom, confirmed fact, and root cause in separate fields.
Base completion criteria on an observable published state.
Separate release-day verification from the 28-day evaluation.
Confirm permissions, environment, and release unit before handover.

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

Public information only, covering target URL, confirmed facts, root cause, the change, completion criteria, and verification steps.