Docs Sync

Sync docs to a code change

Code moved; the docs should move with it. This skill takes a change set and walks it back to the docs that describe the touched areas, updates those docs, and resolves stale recovery rows the code now fixes. It edits prose only — it does not change behavior.

Follow the docs' existing conventions while editing: GFM, humanized (not journal-like or changelog-y), minimal, no contradictions or duplication, and no model scores or result tallies in any doc.

• Codebase tree (what lives where) → Part B of ../../../docs/components/glossary.md
• Capability → tool mapping for your harness → ../../references/harness-capabilities.md

Flow

1. Get the change set

Take the diff or the list of changed files (e.g. git diff --name-only main..., or the working tree). Group the changes by area — a model provider, a deployer, an agent harness, the CLI, metrics, a task, the bastion scripts, a directory move.

2. Learn where things are documented

Tree-walk docs/ (components/, how-to/, appendix/) and the directory structure in glossary.md Part B. Also read the nearest AGENTS.md to the changed code — the root AGENTS.md or tasks/AGENTS.md — since those route contributors and often need the same edit as the docs.

3. Map changed area → affected docs

A change can touch more than one row (e.g. a new CLI flag that exposes a new metric). Update every doc the change actually affects, and only those.

4. Update the affected docs

Edit in place. Keep edits surgical — change the lines the code change made wrong, don't rewrite the page. Match the page's existing voice and structure. If a code change makes a documented example wrong, fix the example. Never paste a score table or run results into a doc.

5. Resolve rows in the known-issues router

This is the inverse of what the run skills do: they append freshly observed failures to known_issues.md; this skill resolves rows the code now fixes.

For every Section 1 (router) or Section 2 (known hacks) row whose root cause your change set addresses:

• Confirm the fix exists in the code before touching the row. Open the file the row points at and verify the fix is actually there — cite the file and line in your report. A row describes a current failure mode; resolve it only when that failure mode can no longer happen.
• Follow the page's own convention: Section 1 rows carry a Resolved column — flip it (and reword the fix cell to point at the fix) rather than deleting the row outright; a Section 2 hack whose stated removal condition is now met gets its Resolved cell flipped (citing the fix), same as Section 1 — don't delete the row.
• If you're not certain the fix is complete, leave the row and say so — a stale "still broken" row is safer than a wrong "all clear".

6. Verify links + report

Confirm every relative link you touched still resolves (open the target, or check the path exists), and when a link carries a #fragment, confirm the target heading still exists — a path check alone won't catch a renamed heading. Then report: the change-set → doc map you applied, each file edited, and each known-issues row resolved with the file/line that proves the fix.

Wrong tool?

• A new failure to record (not a fix) → that belongs in the run skills, which append to the known-issues router; this skill only resolves verified fixes.
• Authoring brand-new docs for a feature with no home yet → write the page under the matching docs/ subtree (components/ for what a thing is, how-to/ for a workflow), then add it to the tree in glossary.md and the nearest AGENTS.md.

Guardrails

• No model scores, leaderboard standings, or result tallies in any doc — ever.
• Never resolve a known-issues row without citing the code that fixes it.
• Edit prose only; this skill does not change code behavior.
• Keep edits minimal and humanized; don't turn a doc into a changelog.