Update Documentation

Review and update documentation in the docs/ folder to ensure it accurately reflects the current codebase.

When to Use

• After making code changes that affect documented features
• During periodic documentation audits
• When adding new features that need documentation
• When removing features that are still documented

Process

1. Understand the documentation structure

   • Read docs/index.md to see the documentation hierarchy
   • Review each document in docs/ subdirectories (model/, pathway/, map/)
   • Check git log --oneline -20 for hints about recent changes—but use this only as a starting point, not a substitute for studying the code

2. Audit against the current codebase

   • For each document, examine the actual code it describes
   • Check products/map/src/ for data structures and validation
   • Check libraries/libpathway/src/ for derivation logic
   • Check products/pathway/ for CLI commands, templates, and formatters
   • Run CLI commands mentioned in docs to verify accuracy

3. Verify diagrams

   • Mermaid diagrams must reflect actual data flow and relationships
   • Compare entity diagrams against actual YAML structures in data/pathway/
   • Compare derivation flowcharts against code in libraries/libpathway/src/
   • Update or add diagrams where they clarify concepts

4. Verify code samples

   • All code samples must be runnable or valid
   • YAML examples should match actual schema structure
   • CLI examples should produce the shown output
   • Update samples that have drifted from implementation

5. Check for gaps

   • New features in code that lack documentation
   • Documented features that no longer exist
   • Cross-references that point to moved or deleted content

Key Files to Cross-Reference

CLI Verification

Always use --data=data/pathway to ensure documentation reflects the canonical dataset.

sh
1# List available entities
2npx fit-pathway skill --data=data/pathway --list
3npx fit-pathway discipline --data=data/pathway --list
4npx fit-pathway track --data=data/pathway --list
5npx fit-pathway level --data=data/pathway --list
6
7# Generate sample outputs to compare with docs
8npx fit-pathway job software_engineering L3 --data=data/pathway
9npx fit-pathway agent software_engineering --data=data/pathway --track=platform

Commit

After making updates, commit with:

docs: update [topic] documentation

Use separate commits for distinct documentation areas.