Phase 7: Update all relevant documentation
Create comprehensive feature documentation by updating requirements, design, and test plan files in the target repository's structure, plus README and CHANGELOG.
/plugin marketplace add kenotron-ms/amplifier-setup/plugin install dev-kit@amplifier-setupnew-feature/Create or update all relevant docs, create examples, update CHANGELOG.
This template MUST be followed when creating 07-docs-checklist.md.
# Documentation Updates: [Feature]
**Created**: YYYY-MM-DD
## Updated Files
- [ ] `README.md` - Added feature overview
- [ ] `docs/api.md` - Documented new endpoints/functions
- [ ] `docs/user-guide.md` - Added usage examples
- [ ] `CHANGELOG.md` (or corresponding status reporting file) - Added entry for this version
## New Documentation (Permanent)
Place in repository's documentation structure (from Phase 0 discovery):
- [ ] `[docs-location]/features/[feature-name].md` - Complete feature guide
- [ ] `[docs-location]/examples/[feature-name]/basic.ext` - Basic usage example
- [ ] `[docs-location]/examples/[feature-name]/advanced.ext` - Advanced usage
## Examples Added
- **Basic usage**: [what it demonstrates]
- **Advanced usage**: [what it demonstrates]
- **Integration**: [how to integrate]
## Documentation Quality
- [ ] All code examples tested and working
- [ ] API reference complete
- [ ] Migration guide created (if breaking changes)
- [ ] Follows repository documentation style
ai_working/<feature>-<date>/00-discovery.md (for doc structure)ai_working/<feature>-<date>/01-requirements.md (source for requirements doc)ai_working/<feature>-<date>/02-design.md (source for design doc)ai_working/<feature>-<date>/03-test-plan.md (source for test plan doc)ai_working/<feature>-<date>/06-manual-test-plan.mdprogress.mdRead discovery to find where docs go and infer naming pattern.
Read 00-discovery.md → "Documentation Structure" to get locations:
[path][path][path] (or combined with dev design)Observe existing files to infer naming pattern:
# List existing files in dev design doc location
ls [dev-design-location]/*.md
# Observe pattern (e.g., user-auth.md, canvas-updates.md → lowercase-with-dashes)
Build file paths using observed pattern:
[location]/[feature-name].md[location]/[feature-name].md[location]/[feature-name].md OR section in dev design docRead README files in documentation locations:
# Check for README in each documentation location
ls [requirements-location]/README.md
ls [dev-design-location]/README.md
ls [test-location]/README.md
For EACH README found, read it to understand:
Use this guidance when creating/updating files in those locations.
CRITICAL: Create technical design doc FIRST so there's a clear place for technical content.
2.1. Get dev design doc path (from Step 1)
2.2. Read README in dev design location (if exists from Step 1.4)
2.3. Check if dev design file exists:
ls [dev-design-path]
2.4. If exists:
02-design.md2.5. If doesn't exist:
02-design.md:
2.6. Verify created/updated:
ls [dev-design-path] && wc -l [dev-design-path]
2.7. Verify has full details (not just summary):
Mark complete: Dev design documented at [exact path] with full details
NOW that dev design doc exists, update requirements/user stories.
3.1. Get requirements doc path (from Step 1)
3.2. Check if file exists:
ls [requirements-path]
3.3. If exists: Read file, compare with 01-requirements.md, update with any missing content
3.4. If doesn't exist: Create new file with content from 01-requirements.md
3.5. Verify created/updated:
ls [requirements-path] && echo "✓ Requirements documented"
CRITICAL: User stories should have ONLY end-user details. Technical content goes in dev design doc (Step 2).
Mark complete: Requirements content documented at [exact path]
Check if test doc exists (separate file or section in design doc).
If exists: Update with test list from 03-test-plan.md (strategy + tests, NO results)
If doesn't exist: Create or add section with content from 03-test-plan.md
Mark complete when done.
REQUIRED: Must use content-researcher agent.
Task content-researcher: "Identify all documentation that needs updating for
[feature]. Search for READMEs, API docs, user guides, epics, stories, design docs.
For EACH document found, specify:
- Document name and location
- What specifically needs to be added or updated
- No priority categorization (HIGH/MEDIUM/LOW) - just list what needs updating
Output format:
- [Document path]: [Specific change needed]
- [Document path]: [Specific change needed]
Do NOT categorize by priority. All documentation in this phase should be completed."
Wait for agent to complete. Review list of docs to update.
After content-researcher completes:
ADD specific files to TodoWrite (expand the list), but KEEP the core tasks:
- [ ] Documentation needs identified ✓
- [ ] Requirements content documented in target repo ← KEEP THIS
- [ ] Design/architecture content documented in target repo ← KEEP THIS
- [ ] Test plan content documented in target repo ← KEEP THIS
- [ ] README updated
- [ ] User Story 07-12 ← ADD specifics
- [ ] Epic 02 Canvas ← ADD specifics
- [ ] STATUS.md ← ADD specifics
- [ ] CHANGELOG updated
The 3 core content tasks are MANDATORY - do not remove them.
For each doc file identified, read and update with feature information.
If needed, use insight-synthesizer agent:
Task insight-synthesizer: "Create comprehensive documentation for [feature]
including overview, usage examples, API reference. Follow existing docs style."
Wait for agent to complete if used.
REQUIRED: Ensure ALL 3 types of content are documented in target repository.
CRITICAL: Adapt to repository structure - don't impose rigid format.
First, read 00-discovery.md to understand:
Then, ensure EACH content type is documented:
CRITICAL - "Adapt to repository pattern" means:
MUST DOCUMENT (always, no exceptions):
01-requirements.md)02-design.md)03-test-plan.md)Each gets its own detailed step below.
CONTENT DEPTH - Use FULL details (not just summary):
Dev Design / Technical Design content should include:
Why full details matter:
CRITICAL - Keep User Stories vs Technical Docs Separate:
User Stories / Epics (end-user focused):
Dev-Design Docs (technical focused):
If you add technical details to user stories, you're doing it wrong.
ADAPT TO REPOSITORY PATTERNS:
Pattern A: Single combined document per feature
# Example: docs/features/[feature-name].md
# Contains: requirements, design, tests, deployment all in one doc
Find or create feature document, include ALL sections:
Pattern B: Separate documents
# Example: docs/requirements/[feature].md, docs/design/[feature].md, etc.
Create/update separate docs:
Pattern C: Epic/Story format
# Example: docs/epics/02-canvas.md with user stories
Find epic/story, update sections:
Pattern D: In-code documentation
# Example: src/features/[feature]/README.md alongside code
Create README in feature directory with all content:
FOLLOW THE PATTERN, don't enforce structure.
CRITICAL - What NOT to Include:
Add entry for this feature following repository's CHANGELOG format. CHANGELOG may have a different filename in the target repo.
Track all updates in ai_working/<feature>-<date>/07-docs-checklist.md (following TEMPLATE above).
REQUIRED: Run automated checks before marking phase complete.
Check 1: Required files exist
ls [requirements-path] || echo "❌ Requirements file missing"
ls [dev-design-path] || echo "❌ Dev design file missing"
ls [test-path] || grep -q "Test Strategy" [dev-design-path] || echo "❌ Test content missing"
Check 2: Technical pollution in user stories (AUTOMATED)
# Search for technical keywords in user story files
grep -i "implementation\|architecture\|module\|technical\|code\|class\|function" [user-story-files]
# If ANY found:
if [ $? -eq 0 ]; then
echo "❌ FAILED: Technical content found in user stories"
echo "Technical keywords found. This violates end-user focus."
echo "Action: REMOVE technical content and MOVE to dev design doc"
exit 1
fi
Check 3: Dev design has full details
# Verify key sections present
grep -q "Quick Reference" [dev-design-path] || echo "⚠️ Missing Quick Reference"
grep -q "Alternatives" [dev-design-path] || echo "⚠️ Missing Alternatives"
grep -q "Assumptions" [dev-design-path] || echo "⚠️ Missing Assumptions"
If ANY check fails:
❌ STOP - Phase NOT complete:
Verification FAILED!
Issues:
- [What failed]
Fix required:
1. Missing files → Create them (go back to Steps 2-4)
2. Technical content in user stories → MOVE to dev design doc
3. Missing sections in dev design → Add them
After fixing, re-run Step 6 verification.
Only mark phase complete after ALL automated checks pass.
Update progress.md:
[✓]95% (Phase 8 archiving will complete to 100%)All documentation complete. Changes ready to commit.
Present to user:
✓ Phase 7 Complete - Documentation Updated
Changes ready to commit:
- Implementation code (if not committed yet)
- Tests (if not committed yet)
- Documentation (requirements, design, test plan)
- README, CHANGELOG, and other docs
Recommended: Commit all changes or submit pull request
/git:commit
/git:submit-pr
This may include:
- Just documentation (if you committed code earlier)
- Entire feature (code + tests + docs together)
Or continue to cleanup:
/new-feature:8-cleanup
Note: Phase 8 (Cleanup) will ask you to commit before proceeding.
Committing is optional here - user can batch commits or commit now for safety before cleanup.
ai_working/<feature>-<date>/07-docs-checklist.mdprogress.md (updated)/new-feature:8-cleanup