document — Phase 10 orchestrator

This skill does not write docs directly. It surveys the diff, decides what kinds of doc work are needed, and delegates via the Skill tool.

Delegate skill	Kind	Runs on
technical-writer	A page on a documentation surface	docs-site pages, docs/** guides — anything a reader navigates to as documentation
prose	Prose body — any English writing that needs humanizing	inline docs, README surface, user-facing copy, summary/narrative sections
documentation	Technical reference	API docs, architecture notes, operational runbooks
technical-tutorials	Step-by-step narrative	quickstarts, walkthroughs, code tutorials

The key shift: prose is the sole channel for prose-shaping work. It owns the humanizer pass so every word we ship is filtered. The other two are technical specialists that produce structured reference material; when they output prose paragraphs that matter, they invoke prose themselves.

Prereq

integrate in completed (or exceptions).

When each delegate fires

• technical-writer — the diff adds or changes a page on a documentation surface (a docs site, a docs/** guide). It runs the full SOP: source-gathering, technical-writing, reader-level, humanizer, then gates on measure.mjs and score.mjs. Prefer it over documentation whenever the deliverable is a page rather than a section of reference material.
• documentation — diff touches a public API, config surface, module architecture, or adds runbook-worthy operational behavior. Reference material a future engineer will look up.
• technical-tutorials — diff adds a feature a first-time user must learn by doing. Hands-on-learning, not lookup-reference.
• prose — when prose needs to be written or revised:
  • Narrative sections inside docs the above two skills produce.
  • README surface updates.
  • User-facing marketing/product copy on landing, pricing, feature pages.
  • One-paragraph summaries, migration narratives, release notes.

Multiple can fire on one diff. A feature that ships an API, needs a quickstart, and updates the pricing page triggers all three.

Steps

1. Verify prereq. integrate is in completed or exceptions. Otherwise stop and say which phase is missing.

2. Classify each surface from config, not from judgment. Run the gate in preview to get the required surface → delegate map:

   node .claude/skills/document/document-gate.mjs --slug <slug>
   

   Its punch list IS this phase's to-do list. The map comes from project.json → document.surfaces (glob → requires[] + reader_target), so routing is a config lookup rather than a per-run decision. This exists because the prose rule below was correct and got skipped anyway: a sentence in a SKILL.md cannot fail a build.

   After running each delegate, record a receipt so the gate can verify it:

   node .claude/skills/document/cli.mjs receipt --slug <slug> --surface <path> --delegate <technical-writer|copywriting|prose|documentation|technical-tutorials>   # wraps receipts.mjs -> recordReceipt
   

   Never hand-write a receipt for work that was not done. The receipt asserts the delegate ran; forging one converts the gate into decoration.

2a. Survey the diff for anything the config does not cover. git diff --name-status <merge-base>..HEAD, then git status --porcelain -uall for the uncommitted and untracked work. The first command sees only what is already committed, so a file this change created is invisible to it. Classify touched files:

• A page on a documentation surface → technical-writer candidate (takes precedence over the two below for that page).
• Public API / CLI / contract surfaces → documentation candidate.
• New capability a user learns by doing → technical-tutorials candidate.
• Marketing / pricing / feature / landing pages (site-src/**) → BOTH registers (see 2.5).
• README surface or prose anywhere in the diff → prose candidate.
• Internal-only refactor with no external surface → just inline docstrings + the README sanity check.

2.5 Reflective public-site check (do NOT rely on file-presence alone). The public site (site-src/**/*.njk) describes the harness's behavior; a behavior change can require a description update even when no site-src/** file is in the diff. Anchoring on "no site file changed → no site work" gets the direction backwards (backlog 5e07). So always run the reflective check:

node .claude/skills/document/cli.mjs surfaces --touched <comma,separated,diff,paths> --json   # wraps public-site-reflect.mjs -> findDescribedSurfaces

findDescribedSurfaces derives the skill/hook/command tokens the diff touches and returns the public pages that name them. For each returned page, route it through TWO registers (per the canonical user feedback, backlog 7b3e — "on public website we need to describe features not just the behavior"):

• documentation (reference register) — update WHAT/HOW the page states, so the mechanism description stays accurate.
• prose in the persuasive / feature-value register (name copywriting as the conditional skill) — frame the user-facing FEATURE VALUE, not just the mechanism. A _thread.md row that says "shelves the active thread and surfaces a resume summary" describes behavior; the feature value is "never lose your train of thought across a pivot, /clear, or flush."

A site-src/** file that IS in the diff gets the same two-register treatment. If the reflective check returns nothing and no site-src/** file is in the diff, there is genuinely no public surface — say so.

3. Always: inline docs. For every changed public symbol — module-level docstring / header comment / doc comment appropriate to the language. Short. If you need a comment to explain what, the abstraction is wrong; comments are for non-obvious why.

4. Delegate. For each matched category, invoke the delegate skill with a scoped brief:

   • technical-writer: invoke via Skill(technical-writer) with the page path, its Diátaxis type, and the source material. It owns its own gates; do not declare the page done until both scorers exit 0.
   • documentation / technical-tutorials: invoke via Skill(...). Include the diff slice, upstream spec/intake, and the specific deliverable (e.g., "API reference for the new retry endpoint"). Read its output and incorporate it.
   • prose: invoke via Skill(prose) with brief, source material (diff slice, spec excerpt), audience, register, and output target (file path or section). The prose skill applies humanizer always, plus the conditional skill you name.

5. README surface check. If the root README.md or any top-level doc claims behavior the diff changed, update it — route through prose so the copy gets humanized.

6. Scrub. No TODO / FIXME / HACK / XXX in files this phase touched. Seed.md forbids them; humanizer doesn't catch them.

6a. Run the gate. It decides whether this phase is done.

node .claude/skills/document/document-gate.mjs --slug <slug>

Exit 0 → every required delegate left a receipt; proceed to step 7. Exit 1 → the phase is not complete: run the named delegate for the named surface, or correct project.json → document.surfaces if the obligation is genuinely wrong. Correcting the config is a legitimate outcome — a false obligation trains people to override the gate, which destroys it — but it is a config edit with a reason, never a hand-written receipt.

Do not append "document" to completed while the gate exits 1.

7. Append "document" to .claude/state/workflow.json → completed.

8. Tell the user: "Documentation pass complete. Invoked: <list of delegates>. Next: /archive."

Constraints

• Delegation is mandatory. You do not write prose here; prose does. You do not write documentation pages here; technical-writer does. You do not write API reference here; documentation does. You do not write tutorials here; technical-tutorials does. This skill decides who writes what and stitches the result.
• Do not skip the humanizer pass. Everything in prose runs it. If you find yourself tempted to write a README paragraph inline to save a hop, don't — route it through prose.
• Do not invoke delegates that don't apply. Internal refactor with no external surface? Don't fire prose (persuasive register) just because the skill is available. Step 2's survey gates the invocations.
• Keep this skill lightweight. The body is mostly "decide → delegate → verify → mark done". Heavy lifting lives in the delegates.
• YAGNI on docs. A doc exists because the code change made it necessary. No speculative documentation.