Spec drift check

Skill QBall-Inc/the-bulwark/skills/spec-drift-check

Development workflow enforcement plugin for Claude Code

Install

npx -y skills add QBall-Inc/the-bulwark --skill spec-drift-check

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Audits a WP brief for drift against current code — extracts claims, verifies each, emits PROCEED/STOP verdict. Use when starting a new WP, before consuming a spec as binding, or when a doc references paths/lines/functions.

SKILL.md

17.6 KB, as published. Nobody here has run it

spec-drift-check

Audits a Work Package brief (or any spec document) for drift against the current code state. The skill extracts every verifiable factual claim from the subject spec — file paths, line refs, function and type names, constants, sequence-of-events claims, dependency claims, state claims — verifies each against current code via Grep / Read / Bash, categorizes findings (CONFIRMED, drift variants, AC re-interpretation, GAP) at LOW / MEDIUM / HIGH severity, rewrites the implementation plan based on findings, and emits a structured verdict (PROCEED, PROCEED_ADJUSTED, STOP_USER_APPROVAL). The verified plan supersedes the original spec for the rest of the work package.

When to Use This Skill

Load this skill when the user request matches ANY of these patterns:

Trigger Pattern	Example User Request
Pre-WP verification	"Run spec drift check on the P10.16 brief", "Verify this brief before I start the WP"
Drift audit	"Check for drift between the spec and current state", "Audit this brief for stale claims"
Claim verification	"Extract claims from this brief and verify them", "Are the file refs in this doc still valid?"

DO NOT use for:

Implementing a brief (use the relevant implementer skill / agent — this skill is verification only)
General code review or PR review (use code-review)
Test audit (use test-audit)
Debugging issues (use issue-debugging)

This skill is READ-ONLY with respect to the subject spec. It does NOT modify the input brief or any code referenced by it. The skill DOES write its own outputs — verification log under $PROJECT_DIR/logs/spec-verify-*.md and diagnostic YAML under $PROJECT_DIR/logs/diagnostics/ — those are not "modifications" of the subject. To FIX issues found in the subject spec, the user invokes a separate skill (manual edits, fix-bug, or an implementer agent). The skill's value is the audit + adjusted plan, not the fix. The frontmatter lists Edit under disallowed-tools, which removes it from the available tool pool while the skill runs, preventing accidental subject-spec modification at the permission layer.

This skill follows the Reviewer archetype with the standalone, multi-source, and pipeline-stage sub-patterns. It runs in Main Context Orchestration (no sub-agent fork) by deliberate design — the verifier needs to read across the full claimed scope and the orchestrator must absorb the verdict directly to make scope-expansion decisions.

Dependencies

Category	Files	Requirement	When to Load
Step 1 guide	`references/step-1-claim-extraction.md`	REQUIRED	Before Stage 1
Step 2 guide	`references/step-2-verification-methods.md`	REQUIRED	Before Stage 2
Step 3 guide	`references/step-3-categorization.md`	REQUIRED	Before Stage 3
Step 4 guide	`references/step-4-plan-adjustment.md`	REQUIRED	Before Stage 4
Step 5 guide	`references/step-5-log-template.md`	REQUIRED	Before Stage 5
Step 6 guide	`references/step-6-decision-matrix.md`	REQUIRED	Before Stage 6
Anti-patterns	`references/anti-patterns.md`	REQUIRED	Throughout
Output template	`references/output-template.md`	REQUIRED	When writing the verification log
Findings schema	`templates/findings-output.yaml`	REQUIRED	When emitting structured YAML output

Usage

/spec-drift-check <spec-path> [<additional-context>]

Arguments:

<spec-path> — Required. Path to the brief or spec document to audit (e.g., plans/task-briefs/P10.16-statusline-lock-cleanup-observability.md).
<additional-context> — Optional. Free-text context the orchestrator should consider (e.g., "WP was authored 5 sessions ago", "previous attempt blocked at AC-3").

Examples:

/spec-drift-check plans/task-briefs/P10.16-statusline-lock-cleanup-observability.md
/spec-drift-check plans/task-briefs/P10.18-spec-drift-check-skill.md "drafted in S119; verify before implementing"

Mandatory Execution Checklist (BINDING)

Every item below is mandatory. No deviations. No substitutions. No skipping. Skipping items violates SC1-SC3 (Skill Compliance Rules in Rules.md).

This skill is a read-only Reviewer using Main Context Orchestration. The subject artifact MUST NOT be modified. Findings MUST be severity-classified per the rubric. Follow every item in order:

Workflow

The skill executes the canonical 7-step methodology developed by clear-Claude (CLEAR framework). Each stage has a dedicated reference doc with full procedure detail; the summaries below are orchestration only.

Stage 0 — Pre-Flight

Verify <spec-path> exists and is readable. Load all 8 reference docs (references/step-1-claim-extraction.md through references/output-template.md plus references/anti-patterns.md) and templates/findings-output.yaml. STOP if the spec is missing or malformed.

Stage 1 — Claim Extraction

Read the spec end-to-end. Enumerate every concrete factual claim into a numbered checklist, in priority order (load-bearing first). Cover: file paths, line refs, function/method/class/type names, constants/schema versions/enum values, sequence-of-events claims, dependency claims, state claims. See references/step-1-claim-extraction.md for full claim taxonomy and the checklist scaffold.

Stage 2 — Verification

For each claim from Stage 1, run the matching verification recipe (Grep / Read at offset / git log --grep / source-of-truth artifact read). MUST grep + verbatim quote rather than recall — recall hallucinates. Capture the actual current state alongside the claim. See references/step-2-verification-methods.md for per-claim-type recipes.

Stage 3 — Categorization

For each verified claim, assign a category (CONFIRMED / DRIFT — line-ref / DRIFT — wrong file / DRIFT — missing scope / DRIFT — undeclared scope / AC re-interpretation / GAP) and a severity (LOW / MEDIUM / HIGH). Severity drives the verdict and the plan adjustment. See references/step-3-categorization.md for the category table and severity decision tree.

Stage 4 — Plan Adjustment

Rewrite the spec's plan section based on the findings: drop deliverables that are now no-ops, add deliverables for undeclared-scope HIGHs, re-target paths for wrong-file DRIFTs, resolve AC re-interpretations explicitly with rationale, re-estimate the token budget if scope changed. See references/step-4-plan-adjustment.md for the rewrite procedure and a before/after example.

Stage 5 — Log

Write the verification log to $PROJECT_DIR/logs/spec-verify-{session}-{topic}.md using the canonical YAML schema (findings, ac_reinterpretations, adjusted_plan, verification_checklist, proceed_decision, roi). See references/step-5-log-template.md for the full template and field-by-field guidance; references/output-template.md is the schema reference.

Stage 6 — Decide

Emit a verdict from the finding mix per the decision matrix:

All CONFIRMED → PROCEED
Only LOW + MEDIUM → PROCEED_ADJUSTED
Any HIGH → STOP_USER_APPROVAL

When STOP_USER_APPROVAL fires, surface the HIGH findings + proposed adjusted scope to the user via AskUserQuestion before any implementation. See references/step-6-decision-matrix.md for the AskUserQuestion template.

Stage 7 — Bind

The verified plan in the log SUPERSEDES the original spec for the rest of this WP. Implementation work follows the verified plan; deviations require explicit user approval. The implementer is expected to consume the log, not the original spec.

Sub-Patterns Documented

This skill exhibits three sub-patterns from the Reviewer archetype's catalog. Sub-patterns are additive — all three apply.

`standalone`

Definition: Reviewer is invoked directly by the user as a primary action.

When to use: The review is the user's goal — they're auditing something specifically.

How it shapes this skill:

User-facing CLI invocation (/spec-drift-check <spec-path>).
Verdict is presented prominently; STOP_USER_APPROVAL surfaces via AskUserQuestion.
The verification log is a deliverable the implementer (or next session) consumes — written to $PROJECT_DIR/logs/spec-verify-{session}-{topic}.md.

`multi-source`

Definition: Reviewer reads multiple prior artifacts (logs, prior-stage outputs, external context) and synthesizes a verdict ACROSS all of them.

When to use: The review's value is the cross-artifact analysis (gap detection, consistency check, holistic verdict).

How it shapes this skill:

Stage 0 Pre-Flight explicitly loads ALL inputs (the subject spec + every claim's referenced source-of-truth artifact). Lazy loading would miss cross-artifact inconsistency.
Findings include cross-references between sources (e.g., "D-04: Spec claims active_tasks.yaml shows P10.18 status=in_progress, but actual yaml shows status=pending").
Verdict reflects holistic judgment across spec + code + state artifacts, not per-source pass/fail.

`pipeline-stage`

Definition: Reviewer operates as a single stage within a larger orchestrating Pipeline skill.

When to use: The review is one step in a multi-stage workflow (audit → adjust → implement, or scan → classify → report).

How it shapes this skill:

Once SD1 ships (per P10.20-drift-enforcement-bundle.md), this skill is mandated as Stage 0 of every WP implementation flow. SD1's binding contract: orchestrator must invoke /spec-drift-check <brief> before any implementation work, and consume the resulting verification log (not the original spec) for the rest of the WP.
The verification log at $PROJECT_DIR/logs/spec-verify-{session}-{topic}.md is the canonical machine-readable output the next stage reads. Schema is locked in references/output-template.md so downstream consumers can parse it deterministically.
When invoked as a pipeline stage (vs user-direct via standalone), the verdict still surfaces to the user via AskUserQuestion when STOP_USER_APPROVAL fires — the user is the explicit decision point on scope-changing HIGH findings, not the orchestrator. The pipeline does NOT auto-proceed past a STOP verdict.
The downstream stage (implementer or implementer agent) is contractually expected to read proceed_decision, adjusted_plan, and verification_checklist from the log; deviations from the verified plan require fresh user approval.
See references/step-6-decision-matrix.md for the orchestrator-vs-user decision boundary in pipeline-stage mode.

Severity Rubric

Full rubric: references/step-3-categorization.md. Compact summary:

Severity	Definition	Verdict Implication
CRITICAL	Reserved — escalates to HIGH for verdict purposes	STOP_USER_APPROVAL
HIGH	Wrong-file DRIFT, undeclared-scope DRIFT, GAP — scope-changing or block-level	STOP_USER_APPROVAL
MEDIUM	Missing-scope DRIFT, AC re-interpretation — adjustable without scope expansion	PROCEED_ADJUSTED
LOW	Line-ref DRIFT — file correct, line off	PROCEED_ADJUSTED (doc fix in implementation comments)

Do NOT invent severities. Each finding maps to exactly one tier.

Verdict Decision Matrix

Full matrix: references/step-6-decision-matrix.md. Compact summary:

Finding mix	Verdict
All CONFIRMED	PROCEED with original plan
Only LOW + MEDIUM findings	PROCEED_ADJUSTED with adjusted plan; flag in summary
Any HIGH finding (esp. scope changes)	STOP_USER_APPROVAL — surface to user via AskUserQuestion before implementing

Anti-Patterns

Full catalog (with examples + remediation): references/anti-patterns.md. Five anti-patterns:

Skipping Step 1 — embedded claims missed, drift caught late
Verifying after implementation starts — drift caught late = wasted work
Treating handoff/memory as immutable truth — they are snapshots in time
Recalling claims rather than grep-quoting verbatim — recall hallucinates
Auto-applying drift fixes without user sign-off when scope changes (HIGH)

Anti-Thought Trap

If you find yourself thinking "I'll just spawn a sub-agent to do this faster" — STOP. That violates the Main Context Orchestration design intent. The verifier must read across the entire claimed scope and the orchestrator must absorb the verdict directly to make scope-expansion decisions. Sub-agent fork would force a context split.

Error Handling

Scenario	Action
Subject spec file not found	Report path; STOP — no audit possible
Subject spec file unreadable / parse error	Report; STOP — do NOT proceed on malformed input
Reference doc missing	Report which `references/*.md` is missing; STOP — cannot audit without methodology
Modification accidentally made to subject spec	Revert immediately via git; report violation; STOP
Verification command (Grep/Read/Bash) fails	Note in finding as `verification_error`; do NOT auto-classify as CONFIRMED
Log write fails	Retry once; if still failing, surface to user — do NOT silently drop the log

Token Budget

Stage	Bound	Notes
Stage 1 (Claim extraction)	Bounded by spec size, not project size	One full read of the subject spec; enumeration is linear in claim count
Stage 2 (Verification)	Per-claim grep / read — efficient	Each claim runs one or two targeted commands; no full-project scans
Stage 3-4 (Categorize + adjust)	Bounded by finding count	Single pass over Stage 2 output
Stage 5 (Log)	Bounded by finding count	Single Write call
Stage 6-7 (Decide + bind)	Constant	Verdict + handoff to next action

The ROI section in the log captures actual cost vs estimated savings. Initial runs may show negative ROI; aggregate ROI across many invocations is what matters.

Output Format

The verification log is written to $PROJECT_DIR/logs/spec-verify-{session}-{topic}.md. Compact YAML schema preview (full schema + field docs in references/output-template.md; YAML template in templates/findings-output.yaml):

findings:
  - id: D-01
    category: drift-line-ref | drift-wrong-file | drift-missing-scope | drift-undeclared-scope | ac-reinterpretation | gap | confirmed
    severity: LOW | MEDIUM | HIGH
    spec_claim: "<verbatim quote from spec>"
    actual_state: "<what current code/state shows>"
    resolution: "<doc fix | plan adjustment | scope expansion | ask user>"

ac_reinterpretations:
  - ac: AC-N
    ambiguity: "<what's unclear>"
    resolution: "<chosen interpretation + rationale>"

adjusted_plan:
  deliverables: [...]
  estimated_token_delta: "+5K | -10K | 0"

verification_checklist:
  - "<item 1 for implementer to confirm at end>"

proceed_decision: PROCEED | PROCEED_ADJUSTED | STOP_USER_APPROVAL

roi:
  spent_tokens_estimate: "~5K"
  estimated_savings: "~15-25K"
  net: positive | break-even | negative

One thing to look at

What its author says it does

SKILL.md

spec-drift-check

When to Use This Skill

Dependencies

Usage

Mandatory Execution Checklist (BINDING)

Workflow

Stage 0 — Pre-Flight

Stage 1 — Claim Extraction

Stage 2 — Verification

Stage 3 — Categorization

Stage 4 — Plan Adjustment

Stage 5 — Log

Stage 6 — Decide

Stage 7 — Bind

Sub-Patterns Documented

standalone

multi-source

pipeline-stage

Severity Rubric

Verdict Decision Matrix

Anti-Patterns

Anti-Thought Trap

Error Handling

Token Budget

Output Format

Keep looking

`standalone`

`multi-source`

`pipeline-stage`