Agent Skills: /document - Documentation Agent

/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

• [ ] 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":

| 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.