doc-drift
Compare design documents against actual code/config, find inconsistencies, and output a prioritized attention list.
Install
npx skills add https://github.com/tykisgod/quick-question/tree/main/skills/doc-drift
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install tykisgod-quick-question@llmmart
git clone https://github.com/tykisgod/quick-question.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole tykisgod/quick-question collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Run qq scripts as
${CLAUDE_PLUGIN_ROOT}/bin/<name>: they are not on PATH, so a bareqq-run-record.pyexits 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 inCLAUDE.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:
- The doc paths and code paths for its assigned modules
- 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-pushto 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)
Files (quick-question)
-
SKILL.md 6.1 KB
--- description: "Compare design documents against actual code/config, find inconsistencies, and output a prioritized attention list." --- > 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`](../../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. ```bash ${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)
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.