OpenParable
Skip to content
← Back to skills

Documenting Code

Documents

Documenting Code is an Agent Skill for documents published in the CaptainCrouton89/.claude repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Maintain project documentation synchronized with code. Keep feature specs, API contracts, and README current with init-project standards. Use when updating docs after code changes, adding new features, or ensuring documentation completeness.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/CaptainCrouton89/.claude/blob/HEAD/skills.archive/documenting-code/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/documenting-code, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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