Blog / Technical SEO /
Writing acceptance criteria for an SEO development ticket
“Improve SEO on category pages.”
Picture the developer reading that. What did you see? Which pages? What does “improved” look like? They’re left guessing, and you’ll probably get something back that isn’t what you meant.
Acceptance criteria fix that. They turn a vague request into a shared description of the problem, the behaviour you want and the evidence that shows the work is done.
Separate the problem from the proposed fix
Describe the current behaviour first. Include a representative URL, the page type, what you expected to happen and what actually happened. Say how you observed it: browser rendering, source response, a crawler or a platform report. If the cause is uncertain, label it as a hypothesis rather than writing it as a fact.
Then state the outcome the site needs. A request may require eligible category pages to expose a distinct title and canonical, while paginated or filtered states follow an agreed rule. Those rules must come from the site’s intended behaviour. Do not infer them from another website or a generic checklist.
Make each criterion observable
A criterion should be passable or fail-able. “SEO is correct” isn’t testable. “The listed category URLs return the approved canonical in the rendered page, and the excluded filtered URLs retain the defined behaviour” gives the team something to inspect. Keep criteria focused; bundling metadata, internal links, performance and content changes into one sentence makes review harder.
Use plain language that developers, SEO specialists and content owners can understand. If a technical term is needed, connect it to an example. A ticket should explain why a requirement matters without turning into a lecture on search engines. When I write one, I try to make it readable by the developer and the client in the same sitting.
Define scope and exclusions
List the page types or URL patterns affected and name important exclusions. A change to one template may affect product pages, collection pages, search results or language variants differently. If the request is limited to one group, say so. If the scope is not yet known, make discovery a separate criterion or task.
Include edge cases that are relevant to the issue. For a title change, that might include a long category name or a page with no optional description. For a canonical change, it could involve pagination or a filtered state. Skip the endless list of theoretical cases. Pick examples that could actually change the result.
State how to verify completion
Identify the checks a reviewer should perform after implementation. That may include inspecting the rendered output, checking a set of URLs, validating the template in staging, or confirming that no excluded page changed. Specify the expected evidence, such as a test URL list or a short before-and-after capture.
Don’t make a ranking movement the acceptance criterion. I’d never sign off a ticket on “traffic went up”. Search outcomes depend on more than the code change and may take time to respond. The ticket can require that the technical behaviour is correct and monitored without promising a traffic increase.
Include context the developer needs
Add the relevant CMS, template, plugin or integration context if known. Attach screenshots, source excerpts or report references only when they help reproduce the problem. Don’t dump a full audit into the ticket. I’ve seen this a lot: forty findings pasted in, and the developer fixes the easiest one. Link to supporting documentation and summarise the specific finding so the developer does not have to guess which part matters.
Identify who can answer product or content questions. Sometimes implementation depends on whether a page should remain indexable or which copy is canonical. A technical ticket should not silently decide business intent. Name the decision owner or capture the unresolved question before work begins.
Keep the implementation flexible
Acceptance criteria explain what must be true, not necessarily how to write the code. Unless an architecture decision has already been made, let the developer investigate a suitable approach. If you suggest an implementation, label it as a proposal and explain the constraint behind it.
This separation helps avoid fixing the visible symptom in a way that creates a larger maintenance problem. A developer may find a template-level solution that is safer than editing many pages individually, or may discover that the original assumption was wrong.
Plan the release and review
For changes that affect many URLs, agree whether the work needs a staged release or additional monitoring. Decide who will inspect the live result and when. The plan should match the scope; a small text update does not need the same release process as a sitewide template change.
After release, compare the result to the agreed criteria and record anything deferred. If a criterion fails, the team should know whether to fix, roll back or investigate further. Make that decision with the people responsible for the affected system.
It can help to agree who signs off each part. The requester can confirm that the business need is met, the developer can explain the implementation, and an SEO reviewer can check the search-facing output. One person may fill several roles, but the decision should be explicit. Avoid making the developer responsible for choosing editorial intent or making an SEO reviewer guess how the code works. Acceptance criteria bring people together around the same outcome while leaving each person clear about their responsibility.
If the ticket changes after development begins, update the criteria and record who agreed to the change. Otherwise, the reviewer may use an outdated definition of done and reject work that followed the latest conversation. Keep the decision in the shared task record.
Related reading
- How to document technical assumptions before implementation
- A practical checklist for SEO acceptance before release
- How to assess the impact of a large CMS content cleanup
A clear ticket cuts guesswork and makes review fairer. Take the next SEO ticket you write and ask: could it pass review on observable evidence, rather than on someone’s confidence that it’s finished?