Our review
Audit and update documentation in the docs/ folder to ensure it accurately reflects the current codebase.
Strengths
- Structured process to cross-reference each document against actual code
- Verification of Mermaid diagrams and code samples
- Identification of undocumented features or outdated content
Limitations
- Requires understanding of both codebase and documentation structure
- Does not automatically fix inconsistencies found
Use this skill after code changes that affect documented features or during periodic documentation audits.
Do not use this skill for writing new documentation from scratch without an existing base, as it focuses on updating rather than creating.
Security analysis
SafeThe skill instructs reading and updating documentation by cross-referencing code and running CLI commands with a specified dataset. No destructive actions, exfiltration, or obfuscated payloads are involved. The commands (git log, npx) are used in a controlled manner.
No concerns found
Examples
Audit the documentation in the docs/ folder against the current codebase. Check each document in subdirectories model/, pathway/, and map/ for accuracy of code samples, diagrams, and feature descriptions. Update any inconsistencies found.I've just refactored the job derivation logic in libraries/libpathway/src/job.js. Please update any documentation that references job derivation to reflect the new code.Review all CLI command examples in the docs/ folder. Run the commands with --data=data/pathway to verify they produce the shown output, and fix any that have drifted.name: update-docs description: Review and update documentation in the docs/ folder. Use when ensuring documentation accurately reflects the current codebase.
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
-
Understand the documentation structure
- Read
docs/index.mdto see the documentation hierarchy - Review each document in
docs/subdirectories (model/, pathway/, map/) - Check
git log --oneline -20for hints about recent changes—but use this only as a starting point, not a substitute for studying the code
- Read
-
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
-
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
-
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
-
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
| Document Topic | Source of Truth |
| ------------------ | ------------------------------------- |
| Skills & Levels | data/pathway/capabilities/ |
| Behaviours | data/pathway/behaviours/ |
| Disciplines | data/pathway/disciplines/ |
| Tracks | data/pathway/tracks/ |
| Levels | data/pathway/levels.yaml |
| Stages | data/pathway/stages.yaml |
| Job Derivation | libraries/libpathway/src/job.js |
| Agent Derivation | libraries/libpathway/src/agent.js |
| CLI Commands | products/pathway/bin/fit-pathway.js |
| Templates | products/pathway/templates/ |
| Agent instructions | AGENTS.md |
CLI Verification
Always use --data=data/pathway to ensure documentation reflects
the canonical dataset.
# List available entities
npx fit-pathway skill --data=data/pathway --list
npx fit-pathway discipline --data=data/pathway --list
npx fit-pathway track --data=data/pathway --list
npx fit-pathway level --data=data/pathway --list
# Generate sample outputs to compare with docs
npx fit-pathway job software_engineering L3 --data=data/pathway
npx 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.
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Documentation Maintenance
Documentation
This skill provides a structured workflow for updating project documentation including CLAUDE.md, README, and CHANGELOG. It walks through phases like inventorying existing docs, analyzing git history for needed changes, optimizing for AI readability, and ensuring cross-document consistency. Use it when synchronizing documentation with code changes or improving documentation effectiveness for AI coding agents.