document（文档处理）

/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

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

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:

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.

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

• git diff --name-only main...HEAD run — full file list captured
• Pipeline gaps identified and classified
• /simplify Implementation Notes read — deviations noted
• /test retry count checked — root cause of failures identified
• Feature doc created/updated with accurate file paths
• User guide created/updated (if user-facing)
• CLAUDE.md read → pruned → updated (or skipped if no structural changes)
• docs/learnings/{ID}-{task-name}.md written
• Key lesson(s) appended to LEARNINGS.md
• No duplicate entries in LEARNINGS.md
• Task moved to "Approved" in TASKS.md

Update TASKS.md

Move task to "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.