doc-drift— agent skill

Run qq scripts as ${CLAUDE_PLUGIN_ROOT}/bin/<name>: they are not on PATH, so a bare qq-run-record.py exits 127.

Respond in the user's preferred language (detect from their recent messages, or fall back to the language setting in CLAUDE.md).

Arguments: $ARGUMENTS

• No arguments: scan all modules
• --module <name>: only check the specified module

With --auto, first make sure a pipeline tracks this run, so the handoff at the end can advance it: qq-execute-checkpoint.py pipeline-start --project . --type feature --current-skill "/qq:doc-drift" --branch "$(git branch --show-current)" --if-not-running. It starts one only when none is running here (you were invoked on your own) and leaves a running one alone.

Execution Flow

1. Determine Scope

Discover the project's documentation and code structure:

• Look for design docs in Docs/, Documentation/, or any directory referenced in CLAUDE.md
• Look for code modules under Assets/Scripts/, Assets/Plugins/, src/, or the project's main code directories
• Group related docs and code into module pairs (e.g., "Player" docs ↔ Player code directory)

If the user specified --module, only scan that module. Otherwise, group all discovered modules and dispatch parallel subagents (subagent_type: "general-purpose", model: "opus") — one per group (max 5 groups).

2. Each Subagent's Task

Each subagent prompt must include:

1. The doc paths and code paths for its assigned modules
2. The following review instructions:

You are a document-code consistency auditor. Read all rules, states, enums, and numeric parameters defined in the design documents, then search for corresponding implementations in the code and verify each one.

Focus on:
- Features defined in docs but not implemented in code (entire subsystems or individual features)
- Features implemented in code but not mentioned in docs
- Protections or added restrictions found only in code (a protection is exempt from a rule everything else follows; an added restriction exists to stop or tax a player choice the other rules allow (not how a new thing works, not a gate that prevents a crash or a stuck state)): report them as "Unrequested", not as outdated docs
- Numeric parameter mismatches (doc value vs code value, with exact numbers)
- Enum value / state name mismatches
- Formula inconsistencies (the complete doc formula vs the complete code calculation)
- Architectural model deviations (doc uses model A, code uses model B)

For each inconsistency output:
- Location: doc path vs code path (with line numbers)
- What's inconsistent: what the doc says vs what the code does
- Severity: P0 (missing feature / bug / core formula error / Unrequested), P1 (value deviation / naming mismatch / architecture difference), P2 (outdated doc but no functional impact)

End with a summary table.

3. Aggregate Output

After all subagents return, consolidate into:

## Global Summary
| Module | P0 | P1 | P2 |

## P0 List (by category)
### A. Missing Subsystems (doc has full design, code has nothing)
### B. Functional Bugs
### C. Critical Formula/Value Deviations
### D. Architecture Model Mismatches
### E. Status Effects Not Wired Up
### F. Unrequested Protections / Restrictions (the user's decision)

## Overall Assessment
Distinguish "not yet built" from "built wrong", and highlight items needing immediate attention.

Handoff

After the drift analysis completes, recommend the next step:

• No critical drift found → "Docs and code are in sync. Want to run /qq:commit-push to ship it?"
• Outdated docs found → "Found N docs that need updating to match the code. Want me to update them, then /qq:commit-push?"
• Unrequested protections or restrictions found → ask the user about each by name; put unanswered ones on the design doc's "Needs the user's decision" list (shared/user-decisions.md); never write them into the doc body
• Actual bugs found (code doesn't match design intent) → "Found N discrepancies that look like bugs. Want me to fix the code and re-run /qq:test?"

`--auto` mode: skip asking:

• Outdated docs → auto-update docs
• Actual bugs → fix code
• Unrequested protections or restrictions → "Needs the user's decision" list only; never update the doc body or change the code for them

Record the result

Last, after any doc updates and code fixes, record the check so /qq:go and /qq:commit-push see it. Under hardening they keep routing back to /qq:doc-drift until there is a record of the engine code as it is now. Only a full scan counts: with --module, skip this step and write no record, because one module checked says nothing about the rest of the project.

${CLAUDE_PLUGIN_ROOT}/bin/qq-run-record.py record --project . --stage doc_drift --command qq:doc-drift --status checked --capture-engine-changes --summary "<P0/P1/P2 counts>"

--capture-engine-changes stores the commit and the engine files as they are now. Any engine-file change after that (edited, committed or deleted) makes the record stale; doc edits do not, and neither does committing exactly what was checked. Use --status failed instead when actual bugs are left unfixed (the user declined the fix).

`--auto` mode: then hand off:

• No code was changed → run qq-execute-checkpoint.py pipeline-advance --project . --completed-skill "/qq:doc-drift" --next-skill "/qq:commit-push", then invoke /qq:commit-push
• Code was fixed → run qq-execute-checkpoint.py pipeline-advance --project . --completed-skill "/qq:doc-drift" --next-skill "/qq:test", then invoke /qq:test --auto

Notes

• Design docs represent the vision, code represents reality — many "missing" items may be normal for phased development, don't mark everything as P0
• Distinguish four situations: outdated docs (code is correct, docs need updating), missing features (docs are correct, code not yet built), actual bugs (code behavior is clearly wrong), unrequested protections or restrictions (only in code; the user's decision)