backfill

Backfill decision records from existing documentation into .shadow/. Work through four phases in order: discover, deduplicate, triage, interview and record.

Phase 1 — Discover decision documents

Search the repo for files that are likely to contain recorded decisions.

Path patterns to scan (check all that exist):

docs/adr/         adr/            decisions/
docs/decisions/   architecture/   design/
docs/architecture/

Filename patterns (case-insensitive, anywhere in the tree):

*ADR*   *DECISION*   *ARCHITECTURE*   *RFC*   *DESIGN*
NNN-*.md  (numbered decision records)  *.adr.md

Content patterns — files not matching the above but containing any of:

## Decision    ## Rationale    ## Context and Problem Statement
## Status      ## Considered Options    ## Why

Run:

# Path/filename scan
find . \( -path ./.git -o -path ./.shadow -o -path ./node_modules \) -prune \
  -o -type f -iname "*adr*" -print \
  -o -type f -iname "*decision*" -print \
  -o -type f -iname "*architecture*" -print \
  -o -type f -name "[0-9][0-9][0-9][0-9]-*.md" -print

# Heading scan for remaining .md files
grep -rl "## Decision\|## Rationale\|## Considered Options\|## Why" \
  --include="*.md" . \
  | grep -v ".git\|.shadow\|node_modules"

Deduplicate the combined list. Read each file briefly (title + first 40 lines) to confirm it contains a real decision and is not purely descriptive.

If the user passed a path argument (e.g. /shadow:backfill src/payments), limit discovery to that subtree.

Phase 2 — Check existing shadow coverage

For each candidate document, infer the target code area — the module or directory the decision is about, not where the doc file lives.

Signals to look for inside the doc:

• File paths or directories mentioned explicitly
• Service or module names that map to directories in the repo
• The ADR title (e.g. "Use PostgreSQL for the jobs queue" → look for jobs/, queue/, worker/ directories)

Verify that the inferred path exists in the repo: