diff --git a/.claude/agents/docs-updater.md b/.claude/agents/docs-updater.md index a2fdd79..59b8cb7 100644 --- a/.claude/agents/docs-updater.md +++ b/.claude/agents/docs-updater.md @@ -7,28 +7,41 @@ permissionMode: acceptEdits color: blue --- -You are a Documentation Updater for a Python project. After each implementation phase, you update all relevant documentation to reflect the current state. +# Documentation Verifier and Updater -**Documents to Update:** +You are a Documentation Verifier and Updater for a Python project. After each implementation phase, you verify that documentation was written during implementation (per TDD step 4) and finalize status tracking. + +**Your role is verification-first, creation-second.** Documentation should already exist from the implementation step. You check it, fill gaps, and update status. + +**Documents to Verify and Update:** 1. **`docs/IMPLEMENTATION_PLAN.md`** (or wherever the plan lives): - Change phase status from "In Progress" to "Complete" - Update status summary table - Mark all task checkboxes as `[x]` - - Update "Implementation Status Summary" section + - **Verify "Decisions & Trade-offs" table** -- if the phase involved non-trivial choices, this table should have entries. Flag if empty when decisions were clearly made. 2. **`docs/CHANGELOG.md`** (running draft): - - Append user-facing changes for this phase + - Verify changelog entries exist for user-facing changes + - **Check entry quality** -- entries must describe user impact, not just name features + - Bad: "Added date filter" / Good: "Users can now filter results by date range using --since and --until flags" + - If entries are missing or low-quality, add or rewrite them - Use [Keep a Changelog](https://keepachangelog.com/) format - Focus on: Added features, Changed behavior, Bug fixes +3. **Code documentation spot-check:** + - Check that new/modified public API functions have docstrings with parameter descriptions + - Check that non-obvious logic has inline comments explaining WHY + - Report any gaps found (do not fix code -- only report) + **Process:** 1. **Read current documentation** - All relevant plan/status/changelog files 2. **Check git state** - `git log`, `git diff` to understand what changed -3. **Identify discrepancies** - Compare documented status with actual state -4. **Apply updates** - Edit files to reflect reality -5. **Verify consistency** - Cross-check between documents +3. **Verify documentation quality** - Check that docs match the quality standards above +4. **Identify gaps** - Compare documented status with actual state, flag missing docs +5. **Apply updates** - Edit files to reflect reality +6. **Report findings** - List any documentation gaps that need attention **Changelog Format (Keep a Changelog):** @@ -53,3 +66,5 @@ You are a Documentation Updater for a Python project. After each implementation - Always include the date when updating phase status - Cross-reference between documents for consistency - Read each file BEFORE editing to avoid overwriting recent changes +- **Flag low-quality changelog entries** -- "Added X" without user context is not sufficient +- **Verify decision records exist** for phases where trade-offs were made diff --git a/CLAUDE.md b/CLAUDE.md index 305595b..bb3d198 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -92,6 +92,37 @@ Configuration lives in root `pyproject.toml`: --- +## Documentation Requirements + +Documentation is part of the implementation, not an afterthought. Write docs as you code, not after. + +### When Documentation Is Required + +| What | Required Documentation | +|------|----------------------| +| Public API functions/classes | Docstring with parameter descriptions and return type | +| Non-obvious algorithmic decisions | Inline comment explaining WHY, not WHAT | +| Significant trade-offs | Decision record in IMPLEMENTATION_PLAN.md (see template) | +| Changed behavior | CHANGELOG entry describing user impact | + +### Decision Records + +When making a non-trivial architectural or design choice, record it in the current phase's "Decisions & Trade-offs" section of `docs/IMPLEMENTATION_PLAN.md`: + +- **What was decided** -- the choice made +- **Alternatives considered** -- what else was evaluated (at least one) +- **Why this option** -- the reasoning, constraints, or trade-offs that drove the decision + +This captures rationale that would otherwise be lost. Do NOT retroactively fabricate decisions -- only record choices that actually required deliberation. + +### What Does NOT Need Documentation + +- Self-explanatory code (clear variable names, obvious logic) +- Internal helper functions with obvious purpose +- Standard patterns already documented elsewhere in the codebase + +--- + ## Testing - **Framework**: pytest @@ -136,9 +167,10 @@ This ensures continuity and prevents duplicated or missed work. 1. **Create code structure** -- Define classes, functions, constants with proper type annotations 2. **Write unit tests** -- Test the interface and expected behavior before implementation 3. **Write implementation** -- Implement the actual functionality to pass tests -4. **Iterate** -- If not finished, return to step 2 for next increment -5. **Run integration tests** -- Validate complete workflow after unit tests pass -6. **Run Phase Completion Checklist** -- See below. This is NOT optional. +4. **Document as you go** -- Add docstrings to public APIs, inline comments for non-obvious logic, decision records for trade-offs (see Documentation Requirements) +5. **Iterate** -- If not finished, return to step 2 for next increment +6. **Run integration tests** -- Validate complete workflow after unit tests pass +7. **Run Phase Completion Checklist** -- See below. This is NOT optional. **Key Principles:** - Structure first, tests second, implementation third @@ -226,19 +258,24 @@ Spawn the following **three agents in parallel**. Gate on ALL completing success - Update plan document if discrepancies found - Verify all phase deliverables are actually complete -### 5. Documentation Update Agent (`.claude/agents/docs-updater.md`) -- CRITICAL +### 5. Documentation Verification Agent (`.claude/agents/docs-updater.md`) -- CRITICAL + **This step is often missed. Invoke via Task tool: `subagent_type: "general-purpose"` with the docs-updater system prompt.** -The agent should update: +Since documentation should be written during implementation (TDD step 4), this step **verifies and finalizes** rather than creating from scratch: - **`docs/IMPLEMENTATION_PLAN.md`**: - Change phase status from "In Progress" to "Complete" - Update status summary table - Mark all task checkboxes as `[x]` + - Verify "Decisions & Trade-offs" section has entries (if trade-offs were made) - **`docs/CHANGELOG.md`** (running draft): - - Append user-facing changes for this phase + - Verify changelog entries exist for user-facing changes + - Check entries describe user impact, not just name features - Use [Keep a Changelog](https://keepachangelog.com/) format - - Focus on: Added features, Changed behavior, Bug fixes +- **Docstrings and inline docs**: + - Spot-check that public API functions have docstrings + - Flag any non-obvious logic missing a rationale comment **After the agent runs, review its output for accuracy BEFORE committing doc updates.** @@ -337,6 +374,26 @@ If a step fails, follow this decision tree: **DON'T include:** Internal refactoring, CI/CD changes, infrastructure updates (unless they affect API), test improvements. +### Entry Quality + +Changelog entries must describe **user impact**, not just name the change. + +**Good entries** (describe what users can now do or what changed for them): + +```markdown +- Users can now filter search results by date range using the `--since` and `--until` flags +- API responses now include a `total_count` field for paginated endpoints +- Fixed: login no longer fails silently when the session cookie expires +``` + +**Bad entries** (just name the feature or describe implementation): + +```markdown +- Added date filter +- Added total_count to response +- Fixed login bug +``` + --- ## Planning Requirement diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index 639d6a7..407993e 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -27,8 +27,16 @@ - [ ] Task 2 - [ ] Task 3 +**Decisions & Trade-offs:** + + +| Decision | Alternatives Considered | Why This Option | +|----------|------------------------|-----------------| +| _Example: Use SQLite for local storage_ | _PostgreSQL, flat files_ | _No server needed, sufficient for expected data volume, stdlib support_ | + **Phase Completion Steps:** -> After this phase, execute the Phase Completion Checklist (steps 0-10 from CLAUDE.md): sync remote, pre-commit hygiene, commit & push, parallel validation (code-quality-validator + test-coverage-validator + acceptance criteria agents), Plan agent for implementation check, docs-updater agent for documentation + changelog, create PR with pr-writer agent, verify CI, review-responder agent for code review (optional), phase handoff note. Consult the Failure & Rollback Protocol if any step fails. +> After this phase, execute the Phase Completion Checklist (steps 0-10 from CLAUDE.md): sync remote, pre-commit hygiene, commit & push, parallel validation (code-quality-validator + test-coverage-validator + acceptance criteria agents), Plan agent for implementation check, docs-updater agent for documentation verification + changelog, create PR with pr-writer agent, verify CI, review-responder agent for code review (optional), phase handoff note. Consult the Failure & Rollback Protocol if any step fails. --- @@ -42,6 +50,11 @@ **Tasks:** - [ ] Task 1 +**Decisions & Trade-offs:** + +| Decision | Alternatives Considered | Why This Option | +|----------|------------------------|-----------------| + **Phase Completion Steps:** > (Same as Phase 1) @@ -57,6 +70,11 @@ **Tasks:** - [ ] Task 1 +**Decisions & Trade-offs:** + +| Decision | Alternatives Considered | Why This Option | +|----------|------------------------|-----------------| + **Phase Completion Steps:** > (Same as Phase 1) @@ -64,4 +82,5 @@ ## Implementation Notes - +