drift-detect

Drift Detect - reality check and reconstruction planning

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. Without an evidence line, there is 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:

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.

   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}]'