implementation-drift-check
/implementation-drift-check
Use when verifying an implementation still matches its spec or plan — during REVIEW or SHIP, or on demand to check drift, confirm you are still on plan, or run a spec check — surfacing spec deviations, unvalidated assumptions, and untested code paths against Intent Truth
- Author
- dkpapadopoulos ↗
- Repository
- auto-claude-skills ↗
- Licence
- MIT
- Last repository change
- 28.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when verifying an implementation still matches its spec or plan — during REVIEW or SHIP, or on demand to check drift, confirm you are still on plan, or run a spec check — surfacing spec deviations, unvalidated assumptions, and untested code paths against Intent Truth
Original author description
Use when verifying an implementation still matches its spec or plan — during REVIEW or SHIP, or on demand to check drift, confirm you are still on plan, or run a spec check — surfacing spec deviations, unvalidated assumptions, and untested code paths against Intent Truth
How it works
- When to Use
- Auto-Co-Selection Guard
- Step 1: Gather Comparison Material
- Step 2: Analyze Drift (Full Mode)
- Step 3: Surface Assumptions and Gaps (Always Runs)
- Step 4: Report
- Step 5: Persistence
- Verification
SKILL.md preview
--- name: implementation-drift-check description: Use when verifying an implementation still matches its spec or plan — during REVIEW or SHIP, or on demand to check drift, confirm you are still on plan, or run a spec check — surfacing spec deviations, unvalidated assumptions, and untested code paths against Intent Truth --- # Implementation Drift Check Detect spec drift, surface unvalidated assumptions, and identify coverage gaps by comparing the current implementation against its Intent Truth (specs, plans, eval packs). ## When to Use - **Auto-co-selection (REVIEW + SHIP):** Fires automatically during REVIEW phase (parallel) and SHIP phase (sequential) when comparison material exists. - **Explicit invocation (IMPLEMENT):** Invoke directly during implementation with prompts like "check drift", "am I still on plan", "spec check". When no comparison material exists, degrades to assumptions-only mode. ### Comparison Sources (any of these triggers auto-fire) - `openspec/changes/<feature>/specs/` (active OpenSpec change) - `docs/plans/*-design.md`, `docs/plans/*-plan.md`, `docs/plans/*-spec.md` (canonical live intent) - `openspec/specs/<capability>/spec.md` (post-ship canonical) - `docs/superpowers/specs/*-design.md`, `docs/superpowers/plans/*.md` (legacy fallback) - `tests/fixtures/evals/*.json` (eval pack scenarios) ## Auto-Co-Selection Guard The hook enforces an **artifact-presence** gate mechanically before this skill is emitted into the composition chain. This is a cheap filesystem glob check (~5ms) in the post-jq Bash filter. If no artifacts match, the composition entry is suppressed -- the LLM never sees it. **Glob patterns checked (canonical first, legacy fallback):** 1. `openspec/changes/*/` (any active OpenSpec change) 2. `docs/plans/*-design.md` (canonical design artifact) 3. `docs/plans/*-plan.md` (canonical plan artifact) 4. `docs/plans/*-spec.md` (canonical spec artifact) 5. `openspec/specs/*/spec.md` (any canonical spec) 6. `docs/superpowers/specs/*-design.md` (legacy design spec) 7. `docs/superpowers/plans/*.md` (legacy plan) 8. `tests/fixtures/evals/*.json` (any eval pack) **Mode selection is LLM-evaluated.** When the hook emits the entry (artifacts exist), this SKILL.md guides mode selection: - **Full drift mode:** At least one spec or plan artifact is available for cross-referencing against the implementation diff. - **Assumptions-only mode:** No spec/plan artifacts exist (e.g., explicit invocation during implementation without a written spec), or only eval packs are available. Degrades gracefully to surfacing assumptions and gaps without drift analysis. ## Step 1: Gather Comparison Material Read in priority order using canonical retrieval precedence. Stop reading duplicates -- if a source was already consumed at a higher priority level, skip it. ### Priority 1: Active OpenSpec Changes (highest authority) ``` openspec/changes/<feature>/specs/ ``` Active work-in-progress specs from OpenSpec. These represent the most current intent and override all other sources when present. ### Priority 2: Canonical Live Intent ``` docs/plans/*-design.md docs/plans/*-plan.md docs/plans/*-spec.md ``` The canonical location for live design documents, implementation plans, and specifications. These are the primary Intent Truth for features that have not yet shipped. ### Priority 3: OpenSpec Canonical Specs (post-ship) ``` openspec/specs/<capability>/spec.md ``` Post-ship authoritative specifications. These represent the as-built state of shipped capabilities and serve as the baseline for incremental work. ### Priority 4: Archived Intent (optional) ``` docs/plans/archive/ ``` Shipped intent history. Not required for drift analysis, but useful for understanding the evolution of a feature when the current implementation diverges from original intent. ### Priority 5: Legacy Superpowers (deprecated fallback) ``` docs/superpowers/specs/*-design.md docs/superpowers/plans/*.md ``` Legacy location for design specs and plans. These paths are deprecated in favor of `docs/plans/` but are checked as a fallback for older features that have not been migrated. ### Priority 6: Eval Pack Scenarios ``` tests/fixtures/evals/*.json ``` Behavioral eval packs committed as test fixtures. These define example-based behavioral expectations and are cross-referenced for coverage gaps in both modes. ### Determine Mode After gathering, select mode: - If **any** spec or plan artifact was found (Priority 1-5): use **full drift mode** (Steps 2 + 3 + 4 + 5). - If **only** eval packs or **nothing** was found: use **assumptions-only mode** (Steps 3 + 4 + 5, skip Step 2). ## Step 2: Analyze Drift (Full Mode) When comparison material exists, run `git diff` against the relevant base (main branch or last reviewed commit) and cross-reference against gathered material across three drift dimensions. ### Spec Alignment For each requirement or acceptance scenario found in specs, check whether the implementation addresses it. | Flag | Meaning | |------|---------| | `implemented-as-specified` | Implementation matches the spec requirement | | `modified-from-spec` | Implementation addresses the requirement but differs from spec (include evidence of what changed and why) | | `added-without-spec` | Implementation includes behavior not described in any spec | | `specified-not-implemented` | Spec requirement has no corresponding implementation in the diff | ### Scope Conformance (deterministic pre-pass) Before the model-judged Plan Alignment below, run the owned deterministic check (advisory; never blocks): ```bash bash '<PLUGIN_ROOT>/scripts/scope-conformance.sh' <plan-file> ``` Use the newest matching plan from the comparison material gathered in Step 1 (e.g. `docs/plans/*-plan.md`). Map the exit code into the report: | Exit | Verdict | Report as | |------|---------|-----------| | 0 | `clean` | One line: scope conformance clean. Before reporting it, eyeball the plan's `Allow:` entries — an over-broad glob (e.g. a bare `*`) makes a clean verdict meaningless; flag it as a finding instead. | | 1 | `violation` | Surface each listed file as an `added-without-plan` candidate finding with the script output as evidence. The reviewer judges intent — plans legitimately evolve; an out-of-scope file is a finding to explain, not an automatic defect. | | 2 | `unverified` | Note scope conformance unverified (no manifest); proceed with model-judged alignment only. | This is branch-level conformance (whole diff vs the plan's declared scope), not per-agent attribution. ### Plan Alignment For each task in the implementation plan, check whether the git diff includes changes to the expected files and scope. | Flag | Meaning | |------|---------| | `completed-as-planned` | Task completed with expected files and scope | | `modified-from-plan` | Task completed but files or scope differ from plan | | `added-without-plan` | Changes exist that correspond to no planned task | | `planned-not-implemented` | Planned task has no corresponding changes in the diff | ### Review-Induced Drift If code review findings were addressed (check for review-round commits or explicit review feedback in conversation), identify whether fixes changed the behavioral contract -- not just code quality improvements. Flag any scope changes introduced by review feedback. This dimension catches drift that is invisible to spec/plan alignment because it was introduced after the original implementation. ## Step 3: Surface Assumptions and Gaps (Always Runs) This step runs in both full drift mode and assumptions-only mode. ### Assumptions Made What does the implementation assume about inputs, environment, dependencies, or user behavior that is not validated by tests? List each assumption with the file and line range where it appears. ### Untested Paths What code paths in the diff have no test exercise? Cross-reference test files against implementation files. Flag: - Functions/methods with no corresponding test - Conditional branches (error handlers, fallbacks, edge cases) not covered - Integration boundaries (API calls, file I/O, external services) without mocks or integration tests - **Test-weakening (gate-gaming):** if `project-verification` reported `gate_gaming_status: suspect` — or the diff deleted assertions, added skip/xfail/disabled markers, or loosened a fixture to make a previously-failing gate pass — flag it as a blocking drift finding. A path that *was* tested and is now un-tested is drift, not coverage. - **Coverage gap (test-adequacy):** if `project-verification` reported `coverage_adequacy_status: suspect` (new code below the changed-line coverage floor), surface it as a blocking coverage-gap drift signal, mirroring the gate-gaming treatment above — this catches new code shipping untested, whereas gate-gaming catches existing tests getting weaker. `unverified` or an absent status is not itself drift (fail-open, no coverage tooling present) and MUST NOT be surfaced as a finding on that basis alone. ### Edge Cases Identified What boundary conditions does the implementation handle that are not explicitly specified? These represent implicit assumptions that may or may not be correct. ### Eval Pack Gaps If eval packs exist in `tests/fixtures/evals/*.json`, identify: - Scenarios defined in eval packs that have no corresponding test implementation - Implementation behavior not covered by any eval pack scenario - Eval pack scenarios whose `expected` values conflict with the actual implementation ## Step 4: Report Terminal output always. Two report shapes depending on mode. ### Full Drift Mode Report Title: `## Implementation Drift Check` Six sections: ```markdown ## Implementation Drift Check ### Spec Alignment | Requirement | Status | Evidence | |-------------|--------|----------| | [requirement from spec] | [flag] | [file:line or diff reference] | ### Plan Alignment | Task | Status | Notes | |------|--------|-------| | [task from plan] | [flag] | [file changes or scope note] | ### Review-Induced Changes - [behavioral contract changes introduced by review feedback, if any] ### Assumptions - [unvalidated assumption] (file:line) ### Untested Paths - [code path without test coverage] (file:line) ### Recommended Actions - [ ] [actionable item to resolve drift or close gaps] ``` ### Assumptions-Only Mode Report Title: `## Assumptions & Gaps` Three sections: ```markdown ## Assumptions & Gaps ### Assumptions - [unvalidated assumption] (file:line) ### Untested Paths - [code path without test coverage] (file:line) ### Recommended Actions - [ ] [actionable item to close gaps] ``` ## Step 5: Persistence ### Terminal Output Always emit the report to terminal. This is the primary output channel. ### Spec/Design Document Annotation When drift is found (any `modified-from-spec`, `added-without-spec`, `specified-not-implemented`, `modified-from-plan`, `added-without-plan`, `planned-not-implemented` flag, or Review-Induced changes), append a concise **"Post-Implementation Notes"** section to the relevant spec or design document: ```markdown ## Post-Implementation Notes _Added by implementation-drift-check on YYYY-MM-DD_ - [concise summary of each drift finding] - [recommended follow-up actions] ``` Append to the first matching document in priority order: 1. `docs/plans/*-design.md` (canonical) 2. `openspec/changes/<feature>/specs/` (active OpenSpec) 3. `docs/superpowers/specs/*-design.md` (legacy) If the document already has a "Post-Implementation Notes" section, append to it rather than creating a duplicate. ## Verification Before reporting "no drift", confirm: - The comparison ran against the highest-authority source available (active OpenSpec change > canonical live intent > archived), and which source was used is stated. - Each spec/plan requirement was checked against the actual implementation -- not assumed aligned. - Assumptions and untested paths are listed explicitly; an empty list means "verified none", not "did not look".
Versions
The database has no other skills named implementation-drift-check.
Database snapshot: 13.11.2026 · package version 4fbbcc790e56 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100arn-code-review-implementation
This skill should be used when the user says "review implementation", "review the project", "check implementation", "quality review", "validate implementation", "implementation review", or wants a post-execution quality gate to verify that the implementation follows the… - 100testing-implementation
Evaluates test implementation and coverage, identifying gaps, weak assertions, and untested paths. Use when auditing test quality, coverage, or testing strategy. - 95sdd-verify
Use when verifying that an implementation matches a change's SDD artifacts. Triggers: "verify", "check implementation", "did I implement everything", "verify the change", "is implementation complete", "check conformance". - 90spec-to-code-compliance
Use when implementation must be checked against an authoritative specification, or during PR review for spec drift against checked-in specs. Not for spec updates: use spec-driven-implementation. - 100validating-implementations
Use when an implementation is (claimed) complete and must be checked against its plan before shipping. Triggers: validate the implementation, verify it matches the plan, is the implementation correct, check before PR. - 100spec-review
Adversarial review verifying implementation matches its specification — checks completeness (nothing missing) and precision (nothing extra). Distrusts the implementer's self-report. Use after implementation, or when the user says "check against spec", "does this match…