/document - Documentation Agent

Workflow

/document {ID}
       ↓
1. Resolve task ID → find task document
2. Read task document + test report (pipeline audit)
3. Run git diff — identify pipeline gaps
4. Create/update feature doc (docs/features/{feature}.md)
5. Create/update user guide if user-facing (docs/guides/{feature}.md)
6. Update CLAUDE.md if structural changes detected
7. Write retrospective → update LEARNINGS.md
8. Move task to "Approved" in TASKS.md
       ↓
┌─── Automation Mode? ───┐
│                        │
▼ Manual                 ▼ Auto
Notify user              Output SIGNAL, exit
Ready for /ship

Auto Mode Behavior

When task document has Automation: auto:

≡ SIGNAL
STAGE: document
STATUS: DONE
TASK: {ID}
SUMMARY: Feature doc created
REFERENCE: docs/features/{feature}.md
≡ END

Manual mode: Run /clear then /ship {ID}.

Step 1: Pre-Documentation Checklist — Full Pipeline Audit

Step 1A: Read primary sources

docs/task/{ID}-{task-name}.md        - What was planned + Implementation Notes from /simplify
docs/testing/{ID}-{task-name}.md     - Test results, failures, retry cycles

Step 1B: Get the actual file diff

git diff --name-only main...HEAD

Cross-reference against task doc's ## File Changes. Anything in diff but NOT in the task doc was added by /simplify or a /test retry — these are pipeline gaps to capture.

Step 1C: Classify pipeline gaps

File in diff but not in task doc	Likely source	Action
Same file, significantly refactored	`/simplify` quality fixes	Note pattern changes in CLAUDE.md if new convention emerged
New helper/utility extracted	`/simplify` single-responsibility fix	Add to CLAUDE.md Important File Locations if reusable
New test fixture or seed file	`/test` setup	Note in LEARNINGS.md if it reveals a testing pattern
Additional files changed in retry	`/test` → `/implement` re-run	Document deviation; check if CLAUDE.md needs updating
Migration file added mid-cycle	Any step	Always add to CLAUDE.md — migrations are critical context

Do NOT do broad codebase exploration. Only open files in the gap list or explicitly needed to verify accuracy.

Step 1D: Read /simplify's Implementation Notes

In the task doc ## Implementation Notes:

"What was built" — may differ from original plan
"Deviations from plan" — medium or major deviations surface in documentation
"Standards check" — fixes may have introduced new patterns worth recording in CLAUDE.md

Step 1E: Check /test retry count

In docs/testing/{ID}-{task-name}.md:

0 retries → note what worked well in LEARNINGS.md
1+ retries → root cause of failure is a lesson; always capture in LEARNINGS.md
Multiple retries on same issue → add "Do Not" entry to CLAUDE.md

Step 2: Identify Documentation Needs

Change Type	Documentation Needed
New feature	Feature doc + User guide
Enhancement	Update existing docs
Bug fix	Update troubleshooting sections
API change	Update API reference
Pipeline gap (simplify/test added files)	CLAUDE.md + LEARNINGS.md

Step 3: Documentation Output

Feature doc: docs/features/{FEATURE}.md — technical implementation details for developers. Include overview, user journey, architecture (file structure, schema, API endpoints), key components, technical notes.

User guide: docs/guides/{feature}.md — how to use the feature for end users. Include quick start, step-by-step instructions, tips, FAQ, troubleshooting.

Step 4: CLAUDE.md — Living Project Brain

Read → prune → update (in that order). Never just append.

Bar for an entry: A future agent would make a mistake without it, waste time discovering it, or re-open a decision already made.

Triggers for update after this task:

What happened	What to update
New directory created	Project Structure
File moved or renamed	Important File Locations
Database migration ran	Stack section, schema notes
New package installed	Stack section
/simplify caught a repeated violation	Do Not
Architecture debate resolved	Architecture Decisions
Convention violated and then fixed	Key Conventions
Old pattern replaced	Remove old entry, add new

Skip entirely if: pure logic fix, copy change, or styling tweak with no new files, directories, migrations, routes, or packages.

Never skip if: migration added, new directory created, file moved/renamed, new API route, new env variable required, or pattern replaced.

/implement should have already captured these — verify and fill any gaps.

Step 5: Retrospective & LEARNINGS.md

Task retrospective: docs/learnings/{ID}-{task-name}.md

Covers the entire pipeline — plan vs reality, quality gate findings, test failures, decisions made. Include:

Plan vs Reality (what was planned, what was committed, deviations, files outside plan)
What /simplify caught (patterns flagged and fixed)
What /test revealed (failures and root causes)
Key lessons (specific and actionable)

LEARNINGS.md (project root): Extract the most reusable insight and append to the relevant section.

Where the lesson came from	LEARNINGS.md section
`/simplify` caught a coding pattern violation	Common Mistakes to Avoid
`/simplify` extracted a reusable helper	Established Coding Patterns
`/test` failed due to system behavior not in plan	Tech Stack Notes
`/test` retry revealed an integration gap	Common Mistakes to Avoid
Files in diff not in plan	Tech Stack Notes or Established Coding Patterns
Architecture decision made during pipeline	Architecture & Decisions

Rules for LEARNINGS.md entries:

One entry = one actionable lesson
Credit the pipeline step that caught it
Bold the key phrase, explain in one sentence
Never duplicate — check before appending
If LEARNINGS.md missing, create with sections: Architecture & Decisions, Established Coding Patterns, Common Mistakes to Avoid, Testing Patterns, Tech Stack Notes

Documentation Checklist

Update TASKS.md

Move task to "Approved":

ID	Task	Task Doc	Feature Doc	Test Report	Approved

Handoff to /ship

Manual mode: Output summary of updated files, task moved to "Approved", next step /ship {ID}. Auto mode: Output SIGNAL and exit. The orchestrator handles routing. Do not spawn the next skill.

document