drift-check

Drift Check

Pre-PR deviation check against the project spec. Run this before /create-pr to verify alignment between implementation and documentation.

Reference: See ~/.claude/docs/prd-workflow/spec-driven-development.md §2–§4 for the deviation threshold, workflow, and checkpoint cadence that this skill operationalizes.

Not the same as /code-review — that inspects the diff for correctness bugs and cleanups; this checks the diff against the spec and docs for deviations. They run at the same pre-PR moment and complement each other.

Your task

Perform a lightweight, advisory review of the current branch's changes against the project's spec and living documents. This is a read-only check — do not modify any files.

Step 1: Identify scope

• Determine the default branch first — don't assume main. Run git rev-parse --abbrev-ref origin/HEAD; it prints e.g. origin/main or origin/master, and the part after origin/ is the base branch for the commands below. If it errors (no origin/HEAD set locally), fall back to git remote show origin (read its "HEAD branch:" line) or default to main. Use this detected base wherever <base> appears below. (Run the detection as a plain command and substitute the result literally — don't wrap it in $(...), which triggers a permission prompt.)
• Run git log <base>..HEAD --oneline to see all commits on this branch
• Run git diff <base>...HEAD --stat to see all files changed
• Determine which feature area this work relates to (from branch name, commit messages, or changed files)

Step 2: Identify the relevant spec

• Check for docs/prd/ROADMAP.md — if it exists, identify which phase or item this work relates to
• Check for docs/prd/ files that cover the feature area
• Check for living documents (domain model, integration guides, runbooks) that describe the current state of the affected models or features
• If no spec exists for this work (e.g., a bug fix or chore with no PRD entry), note that and skip to Step 4

Step 3: Scan for deviation signals

Review git diff <base>...HEAD (the base branch detected in Step 1) for changes that cross the deviation threshold:

Flag if present:

• New or removed database migrations (new models, columns, associations)
• Changes to model validations or lifecycle (status enums, state transitions)
• New or changed URL patterns (routes file changes)
• Changes to authorization rules (policy files)
• New or altered mailer actions or notification triggers
• API contract changes (new endpoints, changed request/response shapes)

For each flagged change, check whether the relevant spec or living document already describes it. If it does, no action needed. If it doesn't, this is a potential deviation.

Step 4: Check documentation gaps

• If docs/prd/CHANGELOG.md exists, check whether any deviations found in Step 3 have already been logged
• If docs/prd/ROADMAP.md exists and this work corresponds to a checkbox item, check whether the checkbox is marked [x]
• Check whether the branch's linked issue (from branch name gh-<N>) has closing keywords in any commit or is ready to be referenced in a PR description

Step 5: Report findings

Present a concise report with these sections:

## Drift Check — [branch name]

### Spec Reference
[Which PRD section or living document this work relates to, or "No spec found"]

### Deviation Signals
[List any changes that cross the threshold but aren't in the spec]
[Or: "No deviations detected"]

### Documentation Status
- CHANGELOG: [entry exists / entry needed / not applicable]
- ROADMAP: [checkbox marked / checkbox not marked / not applicable]
- Issue linking: [ready / needs attention]

### Recommended Actions
[Bulleted list of any actions needed before creating the PR]
[Or: "Clear to proceed with /create-pr"]

Important

• This is advisory, not blocking. The developer decides what needs action.
• Do not modify any files — no CHANGELOG entries, no ROADMAP updates, no code changes.
• Do not re-read files you've already seen in this session unless needed for the deviation check.
• Keep it fast. Target: under 30 seconds for a typical PR. Don't exhaustively read every PRD file — focus on the one or two that are relevant.
• If no PRD exists for the project, check against living documents (domain model, README, CLAUDE.md architectural guardrails). The deviation threshold still applies — it just measures against whatever the authoritative reference is.