Update documentation
The hot path: one documentation change, correctly placed, evidence-backed, and recorded.
What a finished update IS — five parts, all present:
- Exactly one target path, chosen by
references/placement.md.
- Prose in which every statement about the running system carries
evidence=<path>:<line>.
- Untrusted spans inside the blocks you edited, resolved — not left for later.
- An amendment row if you corrected something that was false.
- A ledger entry, if the project keeps a ledger.
For a substantial new document, one more: a reader test (step 9). Not for edits.
References: read references/placement.md when choosing a target path,
references/trust.md when an evidence line is challenged, references/amendments.md when
phrasing an amendment's reason. The tree
and filename grammar live with the skill that creates them —
../scaffold-documentation/references/structure.md — because structure is that skill's primary
concern; read it when the canonical tree is in question — do not copy it into a shared
directory, which cannot ship.
Steps
- Name the change in one sentence — what became untrue, or what is now true that no document
says. Postcondition: you can point at the commit, ADR, or diff that caused it. If you
cannot, you are documenting an intention, not a change; stop and go write the ADR instead.
- Choose the target path by running
placement.md's gates in order. Judgement — a script
cannot classify Diátaxis and would produce a confident wrong answer. Postcondition: one
path, and its parent directory exists (test -d "$(dirname <path>)"). If the directory is
missing, invoke scaffold-documentation first; do not create a directory by hand.
- Read the target in full and list its trust markers:
rg -n 'trust:(untrusted|trustchecked|processedto)' <path> (or grep -nE). Postcondition: you know which
spans you are about to edit are untrusted. Editing around an untrusted span you touched is how
a false claim gets a fresh timestamp and looks verified.
- Resolve the untrusted spans inside the blocks you edit, using the obligation ladder in
trust.md. Hard cap 2 spans per task; anything beyond goes to the docs tree's trust-debt
file with blocked="…". Postcondition: a search for trust:untrusted in <path> returns no marker
inside a block you edited. A span left untrusted in edited text is a false claim with a fresh
timestamp.
- Write the change with visual focus & humanizer discipline.
- Visual-first preference: Represent complex flows, architectures, state transitions, or component relationships with visual diagrams instead of dense paragraphs — author them with
archify, and fall back to Mermaid only when Node.js 18+ or the skill is unavailable or the diagram must render inline.
- Low-noise root READMEs: Keep root and index READMEs concise (high-level architecture diagram + feature matrix + quick start) and link out to dedicated Diátaxis pages for deep dives.
- Humanizer pass: Apply
humanizer rules to strip AI writing tells (serves as, em-dashes —, filler connectors Additionally, Furthermore, At its core). Keep sentence lengths bursty and active.
- Each factual statement about the running system gets a
trustchecked marker with evidence=<path>:<line> you actually opened.
Postcondition: every claim you would defend in review has a marker; anything you would not defend is either deleted or written as unverified.
- Evidence gate. Do not proceed until every
evidence= path and line resolves to a line you
opened. Re-open each one and confirm it still says what you cited it for. This is the gate an
agent will self-certify — "I checked it" is not a check, and a plausible line number is not a
line number. A failure here means the evidence is wrong, never that the check is too strict.
- Add an amendment row if step 5 replaced a false statement —
| Date | Commit | Reason | Change |, per amendments.md. Substantial corrections get the prose block beneath it too.
Postcondition: the row's Reason names the false statement in the past tense. If you cannot
name one, you were editing, not amending; remove the row.
- Record gate. Append the ledger entry and regenerate the projections the project derives from
it (changelog, index, frontmatter
version:/updated:). Postcondition: the entry exists and
the projections are current. Reporting this task complete without the record is a failed run:
the projections are stale and the next person inherits the failure.
- Reader test — substantial new documents only. Skip it for an edit to an existing
document; this gate asks whether a page nobody has read yet can actually be used, and step 6
does not answer that — evidence proves the claims are true, not that a reader can act on them.
Write 5–10 questions a reader would realistically arrive with, then dispatch each to a fresh
subagent given only the document — no repo access, no conversation context, because the point
is to surface what only the author knows. Ask each for its answer plus anything it found
ambiguous or had to assume. Postcondition: every wrong answer and every reported ambiguity
is either fixed in the document or recorded as out of scope with a reason. One round, capped
like step 4: a second round means the document needs rewriting, not re-testing.
- Final check. Postcondition: the file's recorded content hash matches what is on disk —
if you edited after recording, record again — every relative link in the file resolves, and
version: is whatever the ledger says, not a number you typed.
Scripts versus judgement
A step whose output is checkable is a script call, where the project has a script. A step needing
judgement is prose followed by a check of its postcondition.
Never script: Diátaxis classification, verifying that a fact is true, or writing an
amendment's reason. A script here produces confident garbage — a sentence shaped like a
justification that justifies nothing, which is worse than a blank, because a blank gets noticed.
Always check mechanically: does the path exist, does the evidence line resolve, does the hash
match, did the ledger accept the entry. Unautomated does not mean optional — it means you run the
check by hand.
Placement, in one line
Falsification test first: if the code changed tomorrow and this became untrue, would you edit
it (→ a quadrant) or would editing it be falsifying a record (→ work/, dated filename)?
Everything else is in references/placement.md — read it when the one-line test does not settle
the target.
Gotchas
No environment-specific gotchas known.
Red flags — STOP
- Writing "the system does X" with no
evidence= — that is the claim the evidence gate exists to catch
- An
evidence= line number you inferred from a symbol name instead of opening the file
- Creating a new document before running the placement gates
- A new file in a quadrant whose name carries a date, or in
work/ whose name does not
- Editing a frozen build-input file, or adding frontmatter to one — it corrupts at runtime
- Hand-bumping
version: because a check complained about it
- Linking into the legacy staging area — forbidden; provenance travels in
src=
- More than 2 verification spans in one task, or zero when you edited an untrusted block
- Saying "docs updated" in your report when the change was never recorded
- Declaring a substantial new document done with no reader test — or rewriting the questions until
the subagent gets them right, which tests the questions, not the document
- Reader-testing an edit: step 9 is gated to new documents on purpose, and running it on every
change is how a per-task verification budget stops being a budget
Step 9 carries over Stage 3 of the doc-coauthoring skill, authored by Anthropic
(anthropics/skills). No licence file accompanied the
captured copy, so its terms are unestablished here — the step is a restatement of the practice,
not copied text.
Verification Checklist
1---2name: update-documentation-33description: >-4 Use whenever documentation must change to match something that already changed — after a code5 change, ADR, schema change or PR lands, and when the user says "update the docs", "document6 this", "add a how-to for X", "the README is wrong", "this doc is stale", or a reviewer reports7 docs drift. Also use before creating any new document, to decide where it belongs. Triggers8 include a doc that contradicts the code, a fact nobody can source, and a new page with no9 obvious home. Not for creating the docs tree (use scaffold-documentation) and not for10 reorganising it wholesale (use migrate-documentation).11version: 1.0.012author: ai-badger13license: MIT14platforms: [linux, macos, windows]15scope: default16metadata:17 source: https://skillmd.com/skills/arasz/update-documentation-318 hermes:19 tags: [documentation, diataxis, evidence, amendments]20 related_skills: [scaffold-documentation, migrate-documentation]21---2223# Update documentation2425The hot path: one documentation change, correctly placed, evidence-backed, and recorded.2627**What a finished update IS** — five parts, all present:28291. Exactly one target path, chosen by `references/placement.md`.302. Prose in which **every statement about the running system carries `evidence=<path>:<line>`**.313. Untrusted spans inside the blocks you edited, resolved — not left for later.324. An amendment row if you corrected something that was false.335. A ledger entry, if the project keeps a ledger.3435For a substantial **new** document, one more: a reader test (step 9). Not for edits.3637References: read `references/placement.md` **when choosing a target path**,38`references/trust.md` **when an evidence line is challenged**, `references/amendments.md` **when39phrasing an amendment's reason**. The tree40and filename grammar live with the skill that creates them —41`../scaffold-documentation/references/structure.md` — because structure is that skill's primary42concern; read it **when the canonical tree is in question** — do not copy it into a shared43directory, which cannot ship.4445## Steps46471. **Name the change in one sentence** — what became untrue, or what is now true that no document48 says. **Postcondition:** you can point at the commit, ADR, or diff that caused it. If you49 cannot, you are documenting an intention, not a change; stop and go write the ADR instead.502. **Choose the target path** by running `placement.md`'s gates in order. Judgement — a script51 cannot classify Diátaxis and would produce a confident wrong answer. **Postcondition:** one52 path, and its parent directory exists (`test -d "$(dirname <path>)"`). If the directory is53 missing, invoke `scaffold-documentation` first; do not create a directory by hand.543. **Read the target in full** and list its trust markers:55 `rg -n 'trust:(untrusted|trustchecked|processedto)' <path>` (or `grep -nE`). **Postcondition:** you know which56 spans you are about to edit are untrusted. Editing around an untrusted span you touched is how57 a false claim gets a fresh timestamp and looks verified.584. **Resolve the untrusted spans inside the blocks you edit**, using the obligation ladder in59 `trust.md`. Hard cap **2 spans per task**; anything beyond goes to the docs tree's trust-debt60 file with `blocked="…"`. **Postcondition:** a search for `trust:untrusted` in `<path>` returns no marker61 inside a block you edited. A span left `untrusted` in edited text is a false claim with a fresh62 timestamp.635. **Write the change with visual focus & humanizer discipline.**64 - **Visual-first preference:** Represent complex flows, architectures, state transitions, or component relationships with visual diagrams instead of dense paragraphs — author them with `archify`, and fall back to Mermaid only when Node.js 18+ or the skill is unavailable or the diagram must render inline.65 - **Low-noise root READMEs:** Keep root and index READMEs concise (high-level architecture diagram + feature matrix + quick start) and link out to dedicated Diátaxis pages for deep dives.66 - **Humanizer pass:** Apply `humanizer` rules to strip AI writing tells (`serves as`, em-dashes `—`, filler connectors `Additionally`, `Furthermore`, `At its core`). Keep sentence lengths bursty and active.67 - Each factual statement about the running system gets a `trustchecked` marker with `evidence=<path>:<line>` you actually opened.68 **Postcondition:** every claim you would defend in review has a marker; anything you would not defend is either deleted or written as unverified.696. **Evidence gate. Do not proceed until every `evidence=` path and line resolves to a line you70 opened.** Re-open each one and confirm it still says what you cited it for. This is the gate an71 agent will self-certify — **"I checked it" is not a check, and a plausible line number is not a72 line number.** A failure here means the evidence is wrong, never that the check is too strict.737. **Add an amendment row** if step 5 replaced a false statement — `| Date | Commit | Reason |74 Change |`, per `amendments.md`. Substantial corrections get the prose block beneath it too.75 **Postcondition:** the row's Reason names the false statement in the past tense. If you cannot76 name one, you were editing, not amending; remove the row.778. **Record gate.** Append the ledger entry and regenerate the projections the project derives from78 it (changelog, index, frontmatter `version:`/`updated:`). **Postcondition:** the entry exists and79 the projections are current. **Reporting this task complete without the record is a failed run**:80 the projections are stale and the next person inherits the failure.819. **Reader test — substantial *new* documents only.** Skip it for an edit to an existing82 document; this gate asks whether a page nobody has read yet can actually be used, and step 683 does not answer that — evidence proves the claims are true, not that a reader can act on them.84 Write 5–10 questions a reader would realistically arrive with, then dispatch each to a **fresh85 subagent given only the document** — no repo access, no conversation context, because the point86 is to surface what only the author knows. Ask each for its answer plus anything it found87 ambiguous or had to assume. **Postcondition:** every wrong answer and every reported ambiguity88 is either fixed in the document or recorded as out of scope with a reason. One round, capped89 like step 4: a second round means the document needs rewriting, not re-testing.9010. **Final check.** **Postcondition:** the file's recorded content hash matches what is on disk —91 if you edited after recording, record again — every relative link in the file resolves, and92 `version:` is whatever the ledger says, not a number you typed.9394## Scripts versus judgement9596A step whose output is checkable is a script call, where the project has a script. A step needing97judgement is prose followed by a check of its postcondition.9899**Never script:** Diátaxis classification, verifying that a fact is true, or writing an100amendment's reason. A script here produces confident garbage — a sentence shaped like a101justification that justifies nothing, which is worse than a blank, because a blank gets noticed.102103**Always check mechanically:** does the path exist, does the evidence line resolve, does the hash104match, did the ledger accept the entry. Unautomated does not mean optional — it means you run the105check by hand.106107## Placement, in one line108109Falsification test first: if the code changed tomorrow and this became untrue, would you **edit**110it (→ a quadrant) or would editing it be **falsifying a record** (→ `work/`, dated filename)?111Everything else is in `references/placement.md` — read it **when the one-line test does not settle112the target**.113114## Gotchas115116No environment-specific gotchas known.117118## Red flags — STOP119120- Writing "the system does X" with no `evidence=` — that is the claim the evidence gate exists to catch121- An `evidence=` line number you inferred from a symbol name instead of opening the file122- Creating a new document before running the placement gates123- A new file in a quadrant whose name carries a date, or in `work/` whose name does not124- Editing a frozen build-input file, or adding frontmatter to one — it corrupts at runtime125- Hand-bumping `version:` because a check complained about it126- Linking into the legacy staging area — forbidden; provenance travels in `src=`127- More than 2 verification spans in one task, or zero when you edited an untrusted block128- Saying "docs updated" in your report when the change was never recorded129- Declaring a substantial new document done with no reader test — or rewriting the questions until130 the subagent gets them right, which tests the questions, not the document131- Reader-testing an edit: step 9 is gated to new documents on purpose, and running it on every132 change is how a per-task verification budget stops being a budget133134> Step 9 carries over Stage 3 of the `doc-coauthoring` skill, authored by Anthropic135> ([anthropics/skills](https://github.com/anthropics/skills)). No licence file accompanied the136> captured copy, so its terms are unestablished here — the step is a restatement of the practice,137> not copied text.138139## Verification Checklist140141- [ ] Every `evidence=` line resolves to a real `path:line` — opened, not inferred142- [ ] The ledger accepted the entry143- [ ] No frozen build-input file touched144- [ ] Verification-span budget respected (≤2)145- [ ] Report matches what was recorded