name: index description: "Audit repository documentation against the real codebase and reorganize docs into three buckets: implemented, planned, and mismatch. Use this whenever the user asks to review docs for correctness, compare docs with code or git diff, reconcile stale design docs, rewrite project documentation structure, or maintain project-index.yaml as the source of truth for doc-to-code mapping."

Doc Code Consistency

Overview

Use this skill to keep repository documentation aligned with the implementation.

Treat documentation maintenance as a code review task with three outputs:

1. implemented: documents that already match the current code.
2. planned: forward-looking design documents that intentionally describe a target state.
3. mismatch: places where docs and code disagree and must be reconciled before the docs can guide development.

Always ground decisions in the current repository state, not in memory.

Core Rules

• Read the code before trusting the docs.
• Read project-index.yaml before reorganizing documentation.
• Prefer classifying uncertain topics as mismatch rather than overstating implementation status.
• Preserve user changes already in the worktree or index; never revert unrelated edits.
• If old docs are being replaced, create the new canonical docs first, then delete or retire the superseded files.
• Keep the three-bucket structure simple and explicit; avoid mixing current behavior and future design in the same file.

Required Inputs

At minimum, inspect these locations if they exist:

• docs/
• project-index.yaml
• relevant code paths referenced by the docs
• git diff and git diff --cached when the user asks to include pending changes

If the repo uses a different documentation root or index file, adapt to that structure and record the choice in the rewritten docs.

Workflow

1. Build the inventory

Do the following first:

• list the docs under docs/
• read project-index.yaml
• scan old and new docs for code references
• inspect the referenced code, not just filenames
• include staged and unstaged changes when the user asks for a full consistency pass

Use scripts/doc_inventory.py to generate a baseline inventory and stale-reference report, then confirm the findings by reading the actual files.

2. Classify each document or topic

For every meaningful topic, decide which bucket it belongs to:

• implemented: behavior is already visible in the code and safe to treat as current truth
• planned: intentionally future-state, not yet implemented, but still a valid target design
• mismatch: docs and code diverge, or the doc mixes current truth with speculative behavior

Use these heuristics:

• if the code path exists and behavior is observable today, prefer implemented
• if the doc explicitly defines a migration target or vNext shape, prefer planned
• if the doc over-claims capability, references removed structure, or mixes old and new worlds, prefer mismatch

3. Rewrite into canonical docs

Create or update:

• docs/index.md
• docs/implemented/index.md
• docs/planned/index.md
• docs/mismatch/index.md

Then add focused docs under each bucket.

Keep each file narrow and stable:

• implemented docs should describe current behavior only
• planned docs should describe target behavior only
• mismatch docs should explain the exact drift and what needs to be reconciled

4. Update the index source of truth

Update the documentation: section in project-index.yaml so it maps:

• bucket definitions
• document paths
• status
• related code
• notes

If the requirements section also points to docs, refresh those links too.

5. Remove or retire superseded docs

Only after the new canonical docs exist:

• delete obsolete top-level design docs if the user asked for a full migration
• remove stale references to deleted docs
• make sure the new bucket docs are the only authoritative doc set

6. Validate the result

Before finishing, run these checks:

• validate project-index.yaml parses cleanly
• search for references to deleted doc paths
• check that each bucket index only points to existing files
• verify the main implementation claims against the code one more time

Output Expectations

When you finish the task, report:

• what moved into implemented
• what moved into planned
• what moved into mismatch
• which old docs were removed
• whether project-index.yaml was updated successfully
• any residual ambiguity that still needs a product or engineering decision

Suggested Commands

Prefer fast local inspection commands such as:

rg --files docs
rg -n "documentation:|requirements:" project-index.yaml
rg -n "docs/|internal/|cmd/|\.github/workbuddy/" docs project-index.yaml
python .codex/skills/doc-code-consistency/scripts/doc_inventory.py --root .

Reference Material

Read references/doc-model.md before a large rewrite to keep the bucket semantics and migration rules consistent.