Docs sync
Compare a change, or the whole repository, with the committed prose, and report each page the code
makes wrong or leaves incomplete. The trigger table in
AGENTS.md says which surface maps to which page, and
this skill applies it.
How this differs from docs-audit. The audit assesses one page end to end: accuracy, placement,
and voice. This skill starts from the code instead. It walks the surfaces a diff touches and finds
the pages that no longer agree. Use docs-sync to decide which pages a change owes. Use
docs-audit to decide what is wrong with one page.
Inputs
- Scope: a diff (the default is
git diff main...HEAD, plus git diff, git diff --staged,
and new files in git status --short), or all for the whole repository.
- Fix: report only (the default), or fix each gap.
Process
Step 1: List the surfaces the change touches
Read the diff and list each thing an operator or a consumer can observe. Group them by the trigger
table's rows:
- A CLI verb, a flag, a short form, or a default in
crates/box/src/command/cli.rs.
- A
box.toml top-level key, or a field in [agent], [tool.<name>], [egress.<name>],
[mcp.<name>], [telemetry.<label>], or [experimental-features].
- A filesystem list, or what a list grants.
- A policy action id, an attribute a rule reads, or what
when temporal observes.
- A refusal, a denial, a warning, a startup disclosure line, or an exit status that an operator
reads.
- A path the box owns: the box directory and its children, a socket, an alias name, or the records
file.
- A record field, or
RECORD_VERSION, LIVE_VERSION, and PROTOCOL_VERSION.
- An environment name the box reserves or composes.
- A crate's
pub use facade.
- A build, test, or debug command, or a gate.
For all, list the current surface from the code instead of from a diff.
Classify each one as ships or in flux. A surface the freeze in AGENTS.md names always
ships.
Step 2: Walk the trigger table
For each surface, find its row and the page the row names. Record the row you used, because the
report must show which rows you walked.
A surface with no row and no page is in flux. The pre-1.0 valve in the AGENTS.md Docs section
covers it, so it is not doc debt. Say so and move on.
Step 3: Check the user guide
For each surface that ships, open the page the row names and give it one status:
- wrong: the page states something the diff falsifies. Quote the sentence and name the symbol it
disagrees with.
- missing: no page states the surface.
- ok: the page and the code agree.
Run a command only for a surface Step 1 recorded. Most runs of this skill need none.
-
A CLI verb, a flag, or a box.toml key needs no command here.
crates/box/tests/documented_commands.rs and documented_inputs.rs already hold
crates/box/README.md to the parser, and continuous integration runs both. A diff that moves one
gets a failing test, which is a louder signal than this sweep.
-
A policy action or a field does need a command, because no test pins the page to the schema:
cargo run -p strands-box -- policy generate-schema
Each action id and each field the schema emits is in docs/user/policy/actions.md, and the page
names no action the schema omits. Check the count of actions that docs/user/policy.md and
docs/user/policy/actions.md state against ACTION_IDS.
When you fix a page, run .agents/skills/docs-reviewer/check-prose.sh <page> on it.
Step 4: Check the design guide
Report a docs/design/ page whose parts, order, process boundary, or table the diff makes false.
docs/design/README.md maps each page to the question it answers, so use it to find the owner.
Hold each claim to claim-verification.md: a test backs
each claim about behaviour, and the page names no test.
Step 5: Check the crate README and the crate AGENTS.md
A crate whose pub use facade or purpose moved owns a README.md that a consumer reads. Report the
section the change makes wrong. Report a crate AGENTS.md whose frozen surface, premise, or gate
the diff moved, and the root AGENTS.md when the change moves a gate or a frozen surface it lists.
Step 6: Check docs/design/decisions.md for regression only
- Report an entry the diff regresses, and name the anchor. The diff rewrites that entry, or it
does not ship.
- Report two entries that answer the same question in two ways.
- Never report a missing entry, and never report an aged one. An entry enters only through
/kd,
and only after the user decides. A code change owes no entry, and the code is the authority where
an entry and the code already disagree.
Step 7: Report
## Docs sync: <scope>
| Page | Section | Status | What is wrong | Fix |
|---|---|---|---|---|
| ... | ... | wrong / missing | ... | ... |
### Trigger-table rows walked
- <row> -> <page> -> <status>
### In flux, so not doc debt
- <surface> (no row, no page)
### Checks run
List each command you ran, with its result. Name the command you did not run and the surface it
bears on, so a reader can see it was a choice. "None, because the diff touched no policy action" is
a complete answer.
When there is nothing to fix, say so, and still list the rows you walked. Silence reads as "not
checked".
Fixing
When asked to fix, use docs-writer for a page in docs/user/ or docs/design/, and the
voice-guide.md layers for a crate README.md. Use /kd for docs/design/decisions.md, and only
when the user decides the question.
Rules
- Report only what the trigger table requires. A longer page is not a better page.
- Never change code to make a page true. Report the mismatch, and name the symbol.
- The code is the authority. Where a page and the code disagree, the page is wrong.
- Falsified or missing, or it is not a finding. A page that reads as thin or old is work for
docs-planner, not for this skill.
What this skill does not do
- Review a draft's voice. That is
docs-reviewer.
- Plan the docs backlog. That is
docs-planner.
- Commit, or open a pull request.