docs-pipeline

name	docs-pipeline
domain	meta
description	[PROTOCOL] Documentation backfill after an engagement changes code, architecture, deployment, or public contracts. Defines when to trigger, which doc files to update, and what the diff artefact must contain. Preloaded by lead agents (dev-lead, design-lead, marketing-lead). Pure reference — no triggers, not invoked by secretary.

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:

Domain	Trigger
dev	architecture (new service, layer, pattern), deployment (new target, env, secret), public API contract, build/CI topology, security posture, data model
design	brand voice/identity doc, design-system tokens/components, accessibility convention
marketing	brand voice/messaging, semantic core, reporting template, campaign pattern

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.

File	Owner content
project.md	project overview, stack, environments, contacts
architecture.md	system topology, services, layers, data flow
patterns.md	code conventions, naming, folder layout, git workflow
deployment.md	deploy targets, CI/CD pipeline, secrets table, rollback steps
ux-guidelines.md	interaction patterns, voice, accessibility standards

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:

Case	Justified because
Pure bugfix with no new pattern	nothing to document
Refactor within existing module, no API change	convention already captured
Copy tweak on existing landing	brand voice doc already lists voice rules

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.