---
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

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

| 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.

```sh
# 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.