Document

document - Documentation Stage

Invariants

• Run only after verification passed and the user approved the task.
• Base documentation on the task document, test report, and actual changed files.
• Update LEARNINGS.md for reusable lessons.
• Update AGENTS.md only for stable project-level instructions.
• Ensure the task is in Approved in TASKS.md before handoff. If a prior stage missed the move, reconcile the row to Approved here and re-read the tracker to confirm.

Runtime adapters may expose this stage as a slash command, menu action, or natural-language skill invocation. The portable stage name is document.

Workflow

1. Read AGENTS.md.
2. Resolve the task ID.
3. Read the task document and test report.
4. Review git diff --name-only to identify actual changed files.
5. Create or update feature documentation in docs/features/ when developer-facing documentation is needed.
6. Create or update user guides in docs/guides/ when user-facing behavior changed.
7. Write a retrospective in docs/learnings/{ID}-{task-name}.md.
8. Append reusable lessons to LEARNINGS.md without duplicating existing entries.
9. Update AGENTS.md only if the task established durable project-level behavior.
10. Move the task to Approved in TASKS.md (no-op if test already moved it; reconcile from any earlier section if not).
11. Re-read TASKS.md and verify the task row is in Approved and absent from Planned, In Progress, or Testing. If the row is not in the expected section, the move was missed — perform the edit now before handoff.

Documentation Triggers

Retrospective Template

# Task {ID} Retrospective

## Plan Vs Reality
- {What matched or changed}

## Quality Gate Findings
- {What simplify caught}

## Verification Findings
- {What test found}

## Reusable Lessons
- {Actionable lesson}

Handoff

Documentation complete for task {ID}
Task status: Approved
Next stage: ship {ID}