safe-extraction

Safe Extraction Protocol

Follow every step in order. Do not skip steps.

When to use this skill

• A source file exceeds team-agreed size thresholds (this repo uses <2000 lines per file per FR-005) and needs splitting
• A subsystem (destructive-command, worktree-isolation, etc.) is being extracted to its own file
• Code is being moved from one module to another without changing behavior

Benefit: Prevents the three most common extraction failure modes:

1. CI invariant check failures (new file paths not in allowlists)
2. Broken _internals DI seams (test mocks stop working)
3. Cross-file test regressions (other test files that consume the module)

Step 0 — Pre-extraction audit

Before moving ANY code, inventory every path-scoped artifact that references the source file:

0a. CI invariant scripts

grep -rn "<source-file-path>" scripts/ .github/workflows/

Check:

• LEGACY_EXEMPTS arrays (e.g., check-invariants.sh)
• Path-scoped lint/scan configurations
• GitHub Actions path filters

0b. Mock allowlists

grep -rn "<source-file-path>" scripts/mock-allowlist.txt

0c. Test file inventory

grep -rln "from.*<source-module>" src/ tests/ --include="*.test.ts"
grep -rln "vi.spyOn.*<source-module>" src/ tests/ --include="*.test.ts"
grep -rln "_internals.*<source-module>" src/ tests/ --include="*.test.ts"

Record EVERY test file that imports or spies on the source module. These must all pass after extraction.

Prefer the imports tool or repo_map action for comprehensive consumer discovery. Grep catches direct string matches but misses require() imports, dynamic import(), and re-exports through intermediate modules. Use grep as a secondary cross-check.

0d. Import graph

Use the imports tool or repo_map to find all consumers of exports from the source file.

Step 1 — Create the extracted module

1. Move the code block(s) to the new file(s)
2. Move all supporting types, constants, and helper functions used exclusively by the extracted code
3. Add necessary imports to the new file (from external dependencies)