documenting-code

Documenting Code

Standards Reference

All documentation follows init-project conventions:

• IDs: F-## (features), US-### (user stories) - unique and traceable across docs
• Files: docs/feature-specs/F-##-slug.yaml, docs/user-stories/US-###-slug.yaml
• Front-matter: Required title, status, last_updated fields
• Traceability: Every F-## links to PRD, every US-### links to F-##

Reference /file-templates/init-project/CLAUDE.md for full conventions.

Documentation Inventory

Required docs (from init-project template):

• docs/product-requirements.yaml - Project goals, scope, features, success metrics
• docs/feature-specs/F-##-*.yaml - One per F-## feature
• docs/user-stories/US-###-*.yaml - One per user story
• docs/user-flows/*.yaml - Primary user flows
• docs/api-contracts.yaml - API endpoints
• docs/system-design.yaml - Architecture
• docs/data-plan.yaml - Metrics and data storage
• docs/design-spec.yaml - UI/UX specifications

Workflow

1. Check Current State

Before making changes, understand what exists:

• Read docs/product-requirements.yaml for feature list and current status
• Check docs/feature-specs/ for existing feature documentation
• Review docs/api-contracts.yaml for API coverage
• Scan for broken links, outdated examples, or missing documentation

2. Update Documentation

For feature changes:

• Update corresponding docs/feature-specs/F-##-*.yaml with new requirements
• Add/update API endpoints in docs/api-contracts.yaml
• Update docs/product-requirements.yaml if scope changed
• Add JSDoc comments in code for complex logic

For new features:

• Create docs/feature-specs/F-##-slug.yaml following init-project template
• Add F-## entry to PRD feature table
• Create API endpoint entries in docs/api-contracts.yaml if applicable
• Create user stories in docs/user-stories/US-###-slug.yaml if needed

3. Verify Standards Compliance

Checklist before finalizing:

• All F-## IDs in PRD have corresponding feature specs
• All US-### stories link to valid F-## features
• API contracts match feature spec endpoints
• Code examples work and are current
• Links between docs are valid
• Front-matter includes required fields (title, status, last_updated)
• IDs are properly linked across documents

4. Update README

Keep main README current:

• Update feature list to match PRD F-## features
• Refresh installation/setup instructions if changed
• Update API reference links
• Add new usage examples as needed
• Verify all links work

Project Management Commands

Update specific documentation:

/manage-project/update/update-feature      # Update feature specs
/manage-project/add/add-api                # Add API endpoints
/manage-project/update/update-design       # Update system design
/manage-project/update/update-requirements # Update success metrics

Validation commands:

/manage-project/validate/check-consistency # Verify all IDs linked correctly
/manage-project/validate/check-coverage    # Verify no orphaned docs
/manage-project/validate/check-api-alignment # Verify API alignment

Bash utilities (from docs/ directory):

./check-project.sh    # Full validation
./list-features.sh    # Show all features
./list-stories.sh     # Show all stories
./list-apis.sh        # Show all API endpoints

Quick Fixes

• Broken links: Update with correct paths and verify
• Outdated examples: Test code samples and update
• Missing feature docs: Create F-##-slug.yaml following template
• API changes: Update api-contracts.yaml and corresponding feature specs
• Status updates: Mark features as completed after implementation

When to Escalate

• Missing required docs from init-project template
• Broken traceability (orphaned IDs)
• Documentation conflicts with implementation
• User complaints about outdated docs