/drift-check

name: drift-check
description: Pre-PR advisory check for deviations from the project spec. Read-only analysis.

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.