drift-detect

What this skill does

# Drift Detect - reality check and reconstruction planning

Run an `extend` op-cell: add a temporary evidence layer over the repo, compare stated intent with actual implementation, then synthesize the next repair plan. This is read-only unless the caller explicitly asks to apply follow-up fixes.

The invariant: every drift claim cites a concrete source - issue number, PR, milestone, doc line, file path, symbol, test/CI signal, or git-history signal. No evidence line, no finding.

## When to Apply / NOT

Apply when the user asks whether a roadmap, PLAN, README, milestone, issue backlog, or project memory still matches the code. Also apply before restarting an abandoned project, cutting a release from stale plans, or deciding what to rebuild after scope changed.

Do NOT apply to one local test failure, a known bug with a single repro, a branch-quality audit, or greenfield planning with no existing docs/issues/code to compare. Do not mutate docs, close issues, or edit code during this pass.

## Inputs and Flags

Default invocation shape:

```text
drift-detect --sources=github,docs,code --depth=thorough
```

- `--sources=github,docs,code` - comma list; omit a source only when unavailable or irrelevant.
- `--depth=quick|thorough` - `quick` samples active surfaces; `thorough` follows related docs, symbols, and history.
- Optional output artifact: `.outline/drift-detect/reality-check-YYYYMMDD-HHMM.md` when the report is too long for chat.

## Workflow

1. **Scope the scan.**
   - Restate the user's target: whole repo, named plan file, named milestone, release branch, or feature area.
   - Resolve sources from flags. If no flags are given, use all three.
   - Create a scratch evidence bundle in memory or `.outline/drift-detect/evidence.json` only when needed for long synthesis. Keep it minimal: `{github, docs, code, signals, generatedAt}`.

2. **Collect GitHub reality (`--sources=github`).** Use `gh` JSON output; never scrape web HTML.

   ```bash
   gh issue list --state open --limit 200 --json number,title,labels,state,assignees,createdAt,updatedAt,milestone,url
   gh pr list --state open --limit 100 --json number,title,state,isDraft,labels,createdAt,updatedAt,mergeStateStatus,reviewDecision,changedFiles,additions,deletions,files,url
   gh api repos/{owner}/{repo}/milestones --paginate --jq '[.[] | {number,title,state,open_issues,closed_issues,due_on,updated_at,description}]'
   ```

   Extract:
   - stale issues: `updatedAt` older than 90 days; high-priority stale threshold = 60 days.
   - issue categories from labels/title: `security`, `bug`, `feature`, `docs`, `infra`, `tech-debt`.
   - PR risk: draft PRs older than 30 days, merge-conflicted PRs, PRs attached to promised milestones.
   - overdue milestones: due date older than today with `open_issues > 0`; critical if due >30 days ago and release-labeled.
   - already-done candidates: issue title terms that semantically match implemented files/symbols found in Phase 4.

   If `gh` is unavailable or unauthenticated, mark GitHub as `unavailable` and continue with docs/code. Do not invent issue state.

3. **Collect documentation intent (`--sources=docs`).** Use `find` for doc file names, then `read` only candidate files/sections.

   Candidate files:
   - root: `README*`, `PLAN*`, `ROADMAP*`, `TODO*`, `CHANGELOG*`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING*`.
   - directories: `docs/**`, `documentation/**`, `.github/ISSUE_TEMPLATE/**`, `.github/PULL_REQUEST_TEMPLATE*`.

   Search patterns:

   ```text
   ^\s*[-*]\s+\[[ xX]\]\s+(.+)$          # checklist state
   ^\s{0,3}#{1,4}\s+(Phase|Milestone|Roadmap|Plan|Status|TODO|Features?)\b
   \b(feature|supports?|implements?|planned|roadmap|phase|milestone|done|complete|ship|release)\b
   ```

   For each document, record:
   - headings and nearby sections naming goals, phases, release targets, features, non-goals.
   - checkboxes: `total`, `checked`, `unchecked`, completion percentage = `checked / total`.
   - completion claims: headings or prose containing `complete`, `done`, `shipped`, `ready`, `implemented`, `v1`, `release`.
   - feature list items: bullets under Features/Roadmap/Plan/API sections; strip marketing adjectives before matching.
   - stale-doc hints: no recent git change in 180+ days, old version numbers, removed symbol references, examples importing nonexistent paths.

   Git history snippets for doc freshness:

   ```bash
   git --no-pager log -1 --format='%cs%x09%an%x09%h%x09%f' -- README.md PLAN.md docs 2>/dev/null
   git --no-pager log --since='180 days ago' --name-only --format='' -- README.md PLAN.md docs 2>/dev/null
   ```

   If no docs exist, classify as a **documentation gap**, not drift.

4. **Collect code reality (`--sources=code`).** Prefer indexed native codegraph when available; otherwise use ODIN file/search tools plus `ast-grep` and `git grep` fallback commands.

   Framework and project sniff:
   - Node: read `package.json`; detect `react`, `next`, `vue`, `angular`, `express`, `fastify`, `nestjs`, `hono`, `jest`, `vitest`, `mocha`, `playwright`, `cypress`.
   - Python: read `pyproject.toml`, `requirements*.txt`, `setup.cfg`; detect `django`, `flask`, `fastapi`, `pytest`, `unittest`.
   - Rust: read `Cargo.toml`; detect bins, workspaces, tests, benches, `axum`, `actix`, `rocket`.
   - Go: read `go.mod`; detect `gin`, `echo`, `chi`, `_test.go` files.
   - CI: check `.github/workflows/**`, `.gitlab-ci.yml`, `circle.yml`, `Jenkinsfile`, `buildkite/**`.

   File-name lookups use ODIN `find`, e.g.:

   ```text
   find package.json pyproject.toml requirements*.txt Cargo.toml go.mod .github/workflows/**/* "**/*.{test,spec}.{js,jsx,ts,tsx}" "**/*_test.go" "tests/**"
   ```

   Symbol / dependency reality:
   - If codegraph is indexed: use `codegraph_explore` for the target area, `codegraph_search` for symbols, `codegraph_callers` / `codegraph_callees` for wiring, and `codegraph_impact` for blast radius.
   - Fallback commands when codegraph is absent:

   ```bash
   ast-grep --pattern 'export $X' --lang ts src
   ast-grep --pattern 'def $NAME($$$ARGS): $$$BODY' --lang python .
   ast-grep --pattern 'func $NAME($$$ARGS) $$$BODY' --lang go .
   git grep -nE '\b(auth|login|session|payment|route|controller|handler|model|migration|schema)\b' -- ':!node_modules' ':!dist' ':!build'
   ```

   Native drift signals to collect:
   - **doc-drift with zero coupling**: doc files whose recent changes do not co-change with related source. Compute from git when no graph signal exists:

     ```bash
     git --no-pager log --name-only --format='commit %H' -- README.md PLAN.md docs
     git --no-pager log --name-only --format='commit %H' -- src lib app packages
     ```

     Docs with repeated doc-only commits and no matching source commits for referenced terms are MEDIUM; exact removed symbol references are HIGH.
   - **at-risk areas**: directories with high bug-fix churn and stale/low ownership:

     ```bash
     git --no-pager log --since='180 days ago' --format='%H%x09%an%x09%s' --name-only
     git shortlog -sn --since='365 days ago' -- src lib app packages
     ```

     Mark HIGH when a planned feature maps to an area with high bug-fix density and no recent owner activity.
   - **stale docs**: docs older than 180 days that describe active or changed code paths.
   - **orphan exports / dead starts**: exported symbols or public endpoints not called/imported. Use codegraph impact when available; fallback to `ast-grep` export list + `git grep -n <symbol>` count. Orphan + documented feature = HIGH drift; orphan without docs = LOW cleanup signal.
   - **test gap**: implementation exists for documented critical behavior but no matching test file, no test script, or CI never runs tests.

5. **Normalize evidence.** Build a compact bundle, not a transcript dump.

   ```json
   {
     "github": {"issues": [], "prs": [], "milestones": [], "stale": [], "themes": []},
     "docs": {"files": {}, "features": [], "plans": [], "checkboxes": {"total": 0, "checked