docs-pipeline

Orchestrates documentation backfill as a cross-cutting pipeline run by leads before handoff. Keeps project-knowledge in sync with the code/artefacts actually produced.

Trigger — when to run

Lead MUST run docs-pipeline if the engagement changed ANY of:

If engagement changed NONE of these, skip — but log "docs: no change" in engagement/docs-diff.md.

Project-knowledge layout

Canonical path: .claude/skills/project-knowledge/references/ in the project working directory.

Design engagements may add: brand.md, design-system.md. Marketing engagements may add: voice.md, semantic-core.md, campaigns-log.md.

Steps

1. Identify required updates

Lead diffs the engagement against existing docs:

• What decisions were made that are NOT in the docs yet?
• What code/pattern is now canonical that wasn't before?
• What operational step was added (new secret, new CI job, new rollback)?

List them in engagement/docs-diff.md under "Proposed updates".

2. Dispatch dev-technical-writer

Via Task tool. Pass:

• Absolute paths to the engagement artefacts (spec, PRs, decisions).
• Absolute path to engagement/docs-diff.md (proposed updates list).
• Absolute path to project-knowledge references directory.
• Engagement domain (dev / design / marketing).

Writer output: edits applied to references/*.md + a changelog section in docs-diff.md showing before/after per file.

3. Verify (lead)

Lead reads the diff. Checks:

• Every proposed update landed in the right file.
• No doc bloat (writer didn't add redundant sections).
• Code blocks contain only canonical snippets, not one-off engagement examples.
• No generic prose padding ("We value clean code. Our architecture is robust.").

If issues: re-dispatch writer with specific fix list. Max 2 writer re-dispatches per iteration.

4. documentation-reviewer pass

Dispatch documentation-reviewer via Task tool to check:

• Document quality against documentation-writing principles.
• No code blocks where prose suffices.
• Operational specifics present (paths, commands, secret names).
• No duplication across files.

Log verdict in engagement/validation-log.md under documentation-reviewer.

5. Record in docs-diff

engagement/docs-diff.md must contain by end of pipeline:

# Docs diff — {engagement-name}

## Files changed
- `references/architecture.md` — added section §3 Service X
- `references/deployment.md` — added secret NEW_API_KEY + rollback for Service X
- `references/patterns.md` — no change (no new pattern introduced)

## Review
- documentation-reviewer verdict: clean (or N findings + resolutions)

## Not yet written
- {if anything was deferred with reason}

Skip rules

Allowed skip scenarios — log in docs-diff:

Director will verify the skip justification matches engagement scope. Do NOT skip to save time if change is user-visible or operationally relevant.

Anti-patterns

• Don't treat docs as optional. Director rejects handoffs where architecture changed but architecture.md doesn't reflect it.
• Don't dump code into docs. Project-knowledge is prose + tables + short canonical snippets, not a code dump.
• Don't write generic prose. "We value clean code" is doc bloat. Write specifics: "Folder src/services/ contains class-per-file, each class exports a single default."
• Don't duplicate across files. If deployment.md lists the pipeline, patterns.md references it — doesn't repeat it.
• Don't skip documentation-reviewer. Cheap check, catches rot.