Keeping the spec, manual, demos and tests in sync

08 Jul, 2026

When shipping a feature, there is often a checklist of things you should do to keep the docs / user manual / product demos up to date. Sometimes it is a wiki page, more often in my experience it ends up being in a notepad on your local machine.

I built a procedure & skill for this instead, and an agent runs it end to end 🤖

TLDR

• We have a /sync skill in frontend repo at GScan: after a feature lands, one command reads what changed and brings five artefacts back into agreement - the acceptance-criteria spec, the user manual (in three languages), the training-video scripts, the release notes, and the Playwright e2e suite.
• It scopes its own work by finding the last "ran sync" commit and diffing from there, and finishes with a single commit carrying that same marker, so the last sync point is always one git log --grep away.
• A companion triage-sync skill decides whether a change even needs a sync, so the full run only fires when something user-facing actually moved.
• It's a fairly new addition - the "ran sync" marker turns up on about eight commits so far - but each has moved every affected artefact in one commit, and the chore now costs one command instead of living on a page nobody opens.

Five views of the same product

Five artefacts in the frontend repo describe the same product from different angles, and every feature change can pull them out of agreement:

The failure mode is gradual drift of components over many iterations: a button gets renamed in the UI and the manual still tells the German user to click the old label; a criterion in the spec gets implemented but no e2e test asserts it; a feature ships and the release notes never mention it. None of these break the build, so nothing flags them. The supporting documents rot until someone happens to notice.

What one run looks like

Before anything, a companion skill decides whether a sync is warranted at all. triage-sync reads the git diff, classifies the changes as user-facing or not, and recommends whether to run the full workflow. A refactor that changes no behaviour shouldn't drag five documents behind it, and this gate is what stops it from trying.

When it does run, the first thing it does is find the last sync point:

git log --oneline --grep="ran sync" -1
git diff <that-commit> HEAD --stat

That scopes the work to what changed since the docs and tests were last reconciled, rather than re-auditing 852 lines of spec from scratch every time. From there it builds a traceability chain for the changed area - which criterion maps to which manual section, which training video, which test - and looks for the gaps: a criterion with no test, a manual section with no video, a test that traces back to nothing.

Then it walks the five artefacts in order, updating each in place and showing me the diff before it moves on, and finishes with a single commit whose message starts "ran sync". The marker is useful because the last time everything was brought into agreement is always one git log --grep away.

A run I can point at

When a "rerun a single pipeline step" feature landed, one sync commit moved the spec, the manual, the demo script, and the tests together:

• three new lines in the UAC document
• the overview demo script
• the "overview" manual page in all three languages (en_gb, de_de, ja_jp)
• 107 new lines in the test spec for the scan overview page

213 insertions across 11 files, in one commit, from one command. (Release notes joined the skill's remit later, which is why this earlier commit doesn't touch them.) Before the skill, that was four separate chores, each depending on someone remembering the other three.

Why a file beats a wiki page

The content barely changed when it moved from the wiki into the repo; it's the same procedure written down. What changed is who runs it and where it lives.

A checklist a person has to remember gets skipped when moving fast, if it's done at all - that has been my experience, at least. As an executable file sitting next to the code and versioned in the same history, the procedure travels with the thing it describes: check out an old commit and the sync process comes with it, as it was then. And because each run ends in a "ran sync" commit, the process keeps its own record - "when were the docs and tests last reconciled?" is answerable with git log, instead of a question you put to a colleague who may not remember.

Caveats

A couple of caveats, because a write-up like this makes things sound more finished than they are :)

It hasn't been going for long: those eight-or-so "ran sync" commits are relatively recent, not something that has had years of battled hardening. The skill updates the training-video scripts, but the workflow that would turn a script into a rendered video on its own isn't built yet, more on that when it's finished.

Encoding a checklist as an agent-run skill might be overengineering, and a few bullet points in the PR template could arguably do the same job. For a small documentation surface I'd probably agree. With a detailed spec, a long manual in three languages, 15 Playwright specs and a set of video scripts, the remembering part might be easy but the work involved in updating is burdensome. So writing the procedure down and making it runnable does indeed save us time & effort.

What it's changed for us

Keeping the docs and tests current stopped being a background worry once the procedure became something we could run instead of something we had to remember. A team process that might have once been parked on a wiki now lives in the repo, versioned with the code it describes, and leaves its own trail of when it last ran.

#agents #ai #thoughts #writing