tkersey/simplify-and-refactor-code-isomorphically

Simplify and Refactor Code Isomorphically

The One Rule: Prove behavior identical, then remove lines. No proof → no delete. The goal is net-negative LOC with a test suite still green and a golden-output diff still empty.

Table of Contents

One Rule · The Loop · Pre-Flight · Phase 0 (jsm bootstrap) · Vibe-Coded Pathology Triggers · Duplication Taxonomy · Opportunity Matrix · Isomorphism Proof · Pattern Tiers · Language Cheatsheet · Metrics Dashboard · Agent Coordination · Anti-Patterns · Checklist · Hand-off · Reference Index

In a hurry? Open references/QUICK-REFERENCE.md — one-screen card with the rule, loop, score formula, clone taxonomy, and every commit gate. Then return here for depth.

New to this skill? Skim references/GLOSSARY.md first, then references/FAQ.md. Version: see CHANGELOG.md.

This skill is the mirror image of extreme-software-optimization: same discipline, different axis. Optimization trades structure for speed; simplification trades nothing — it just removes accidental complexity while behavior stays bit-identical. It consumes the same kind of baseline artifacts (golden outputs, test suites, invariants) and emits a LOC ledger, a duplication map, and a series of small isomorphic commits.

The Loop (mandatory)

0. BOOTSTRAP   → check installed sibling skills; offer jsm install for the missing ones; subscription-gated
1. BASELINE    → test suite green, golden outputs captured, LOC snapshot, typecheck clean
2. MAP         → duplication scan (jscpd/similarity-ts/scc/rg/ast-grep) + callsite census + AI-slop scan
3. MATRIX      → score each candidate: (LOC_saved × Confidence) / Risk ≥ 2.0
4. PROVE       → Isomorphism card per change BEFORE editing (not after); property tests for unknown rows
5. COLLAPSE    → one lever per commit; Edit only, no file rewrites; no script-based codemods
6. VERIFY      → tests green · goldens bit-identical · typecheck clean · LOC delta recorded · lints not grown
7. LEDGER      → metrics dashboard · rejection log · per-candidate row
8. REPEAT      → re-scan (new duplicates surface once noise clears)

Each phase emits an artifact under refactor/artifacts/<run-id>/. No artifact → phase isn't done. The artifacts are the handoff to reviewers; without them a "this is cleaner" PR is indistinguishable from a drive-by rewrite.

---

Pre-Flight Checklist

Run through this before touching any file. The most common way a simplification PR destroys value is skipping one of these.

• [ ] Tests baseline is green — cargo test / pnpm test / pytest / go test ./... clean on the commit you're starting from. If tests are red, the refactor will be blamed for breakage that already existed. Fix or quarantine first.
• [ ] Golden outputs captured — run the program against a representative input set and sha256sum the outputs. See ISOMORPHISM.md.
• [ ] LOC snapshot — tokei / scc / cloc before. You must be able to cite "before → after" per path.
• [ ] Typecheck / lints baseline — tsc --noEmit, cargo clippy -- -D warnings, mypy, go vet. Count warnings. The delta after must not grow.
• [ ] Duplication scan run — jscpd, similarity-ts, scc --dup, or ast-grep structural patterns. Map is an artifact, not a memory.
• [ ] One lever per commit — pick exactly one pattern (e.g. "collapse three send_* functions into one enum-dispatched fn"). Don't stack unrelated cleanups.
• [ ] No file proliferation, no rewrites — per AGENTS.md, revise in place. Never v2/_new/_improved. Never use a script to rewrite many files — make the edits manually or via parallel subagents, not regex.
• [ ] No file deletion without permission — per AGENTS.md Rule Number 1. A helper that becomes empty gets asked about before it goes away.

If any box is empty, stop and resolve it first. A simplification PR under a broken precondition is worse than no PR — it poisons trust in the whole technique.

---

Phase 0 — bootstrap sibling skills (jsm)

This skill composes many siblings. Before Phase A, check which are installed; offer to jsm install the missing ones. Every referenced skill has an inline fallback — none are prerequisites. Details: JSM-BOOTSTRAP.md.

# 1. Detect state
./scripts/check_skills.sh refactor/artifacts/<run-id>
# writes skill_inventory.json; prints a table

# 2. If jsm missing and user wants premium skills:
./scripts/install_jsm.sh      # curl-to-bash, user-consent-gated

# 3. Auth (user-gated; opens browser OAuth or API key)
jsm login

# 4. Install missing siblings (idempotent; graceful on subscription errors)
./scripts/install_missing_skills.sh refactor/artifacts/<run-id>

Sibling siblings used

• cass — mine prior refactor precedent
• ubs — surface bug-smells while mapping
• multi-pass-bug-hunting — depth bug-hunt after a major pass
• testing-golden-artifacts / testing-metamorphic / testing-fuzzing — property & golden patterns
• multi-model-triangulation — second opinion on Risk/Confidence
• ntm + agent-mail + br + bv + vibing-with-ntm — multi-agent swarm
• codebase-archaeology — model unfamiliar code first
• mock-code-finder — find orphan stubs/mocks
• cc-hooks — block sed/codemod via PreToolUse hooks
• extreme-software-optimization + profiling-software-performance — when refactor reveals perf regressions

Do not block on missing siblings. Scripts exit 0, log, proceed with inline fallbacks. Full matrix in JSM-BOOTSTRAP.md §Sibling-skill matrix.

---

Quick Triggers

| User says | First move | |-----------|------------| | "remove duplication" / "DRY it up" | Run the duplication scan first; don't eyeball. Many "duplicates" have divergent invariants. | | "simplify the data types" | Callsite census of every field / variant actually touched; kill what isn't read. | | "reuse this component" | Extract props schema from all callers; merge by variant discriminant, not by inheritance. | | "remove lines" / "reduce LOC" | Score by Δ LOC × Confidence / Risk; stop at Score < 2.0. Don't chase the last 5%. | | "create helper functions" | Rule of 3 — two callsites means note it, three means extract. Two means leave it. | | "better abstraction" | Resist until you have three concrete cases. One abstraction fits one shape; two fits coincidence; three fits reality. | | "this file is too long" | Length is a symptom, not a bug. Measure cyclomatic complexity and coupling before splitting. | | "unify these two implementations" | First prove they have the same contract — invariants match, error semantics match, ordering matches. Otherwise leave both. |

---

Vibe-Coded Pathology Triggers (AI-generated code smells)

Projects grown via Claude Code / Codex / Cursor / Gemini sessions accumulate a characteristic set of refactor surfaces. These are NOT classic legacy spaghetti — they're the artifacts of plausible autocomplete at scale. Catalogued fully in VIBE-CODED-PATHOLOGIES.md; 40 named patterns total (P1-P40). Most common:

| Pathology | Smell | Detection | |-----------|-------|-----------| | P1 over-defensive try/catch | 3+ nested try blocks per 10 LOC, swallowed exceptions | rg 'except Exception' -t py -c | | P2 nullish chain sprawl | a?.b?.c?.d?.() ?? e ?? f ?? 'default' | rg '\?\..*\?\..*\?\.' -t ts | | P3 orphan _v2 / _new / _improved files | two similarly-named files; one is live, others drifted | rg --files \| rg -i '_v[0-9]\|_new\|_old\|_improved\|_copy' | | P4 utils.ts / helpers.py dumping ground | 1000+ LOC "common" module imported everywhere | long files + high fan-in | | P5 BaseXxxManager<T> hierarchy | abstract class, 60–90% overrides in concrete classes | rg 'extends (Base\|Abstract)' | | P6 dead feature flags | if FEATURE_X_ENABLED that's been true in prod for 12+ months | audit config + telemetry | | P7 re-export webs | 4+ levels of export * from './index' | rg '^export \* from' -t ts -c | | P8 pass-through wrappers | fn a() { b() }; fn b() { c() } hops with no real body | ast-grep structural match | | P9 parameter-sprawl helpers | 8+ optional params, 200 lines of flag-conditionals | eyeball long signatures | | P10 swallowed Promise rejections | catch { return null } | rg 'catch\s*\{\s*return null' | | P11 comment-driven programming | # Step 1: ...; # Step 2: ...; ... literal task comments | rg '^\s*(#\|//) (Step\|Phase)' | | P12 dead imports | import { useMemoized } (doesn't exist); unused imports | knip, ts-unused-exports, linter | | P13 stale type exports | interface declares fields never used; or used-fields not declared | type vs runtime audit | | P14 dead mocks | __mocks__/api.ts from prototyping; real API has shipped | mock-code-finder skill | | P15 any that compounds | one boundary any → every downstream variable is any | rg ':\s*any\b\|as any' | | P19 N+1 from autocomplete | for x in xs: await fetch(x.id) | rg 'for .* await' | | P17 prop drilling for singletons | user/theme/locale drilled 5 levels deep | manual scan | | P18 "everything hook" swamp | useEverything() returning 30 fields | fat hook scan |

Run ./scripts/ai_slop_detector.sh before Phase B — it emits slop_scan.md with all these. Full detection recipes + collapse recipes + per-pathology isomorphism pitfalls in VIBE-CODED-PATHOLOGIES.md. A recommended attack order (cheap wins first) is given there as "The AI-slop refactor playbook."

Why these emerge: session amnesia + prompt-level goals + autocomplete momentum + addition bias. This skill is the direct antidote. See VIBE-CODED-PATHOLOGIES.md §Why these emerge specifically from AI workflows.

---

Duplication Taxonomy (know what you're merging)

Not all duplication is equal. Merging the wrong kind introduces bugs and costs lines.

| Type | Name | Description | Merge? | |------|------|-------------|--------| | I | Exact clone | Byte-identical spans (often copy-paste) | Yes — extract function | | II | Parametric clone | Same shape, different literals/identifiers | Yes — parameterize | | III | Gapped clone | Same shape, small additions/removals | Maybe — use enum/strategy dispatch, only if variance is bounded | | IV | Semantic clone | Different code, same behavior | Stop — different code often encodes different invariants. Prove equivalence before merging. | | V | Accidental rhyme | Looks similar, evolves independently | Don't merge — you'd couple two unrelated lifecycles |

The hardest bugs from "DRY" come from merging Type IV or V. The second-hardest come from merging Type III too eagerly — the shared function accumulates parameters until it's less readable than the originals.

Full examples and decision tree: DUPLICATION-TAXONOMY.md.

---

Opportunity Matrix

Score = (LOC_saved × Confidence) / Risk

LOC_saved  (1-5): 5 = ≥200 lines, 4 = 50-200, 3 = 20-50, 2 = 5-20, 1 = <5
Confidence (1-5): 5 = duplication scanner + golden diff confirms equivalent
                  3 = looks the same, scanner agrees, but only one callsite tested
                  1 = "these feel similar"
Risk       (1-5): 5 = crosses async/ordering/error-semantics boundary
                  3 = crosses module boundary, shared state
                  1 = single file, single function, pure

Only implement Score ≥ 2.0. Below that you're likely paying a coupling cost greater than the LOC savings.

| Candidate | LOC | Conf | Risk | Score | Decision | |-----------|-----|------|------|-------|----------| | 3× near-identical send_* → send(kind, ...) | 4 | 5 | 2 | 10.0 | ✅ | | Merge <PrimaryButton> + <SecondaryButton> → <Button variant> | 3 | 4 | 1 | 12.0 | ✅ | | Unify OrderV1 and OrderV2 types | 4 | 2 | 5 | 1.6 | ❌ (different invariants) | | Collapse two parse_* functions used by one CLI flag each | 2 | 4 | 1 | 8.0 | ✅ |

Full worked example: METHODOLOGY.md §Phase C — Score the candidates.

---

Isomorphism Proof (per change, written BEFORE the edit)

Every simplification commit must carry this card in its body, filled in before the diff:

## Change: [one-line description]

### Equivalence contract
- **Inputs covered:**      [which callers / test cases]
- **Ordering preserved:**  [yes/no + why — e.g. iteration order deterministic since inputs are Vec]
- **Tie-breaking:**        [unchanged / N/A]
- **Error semantics:**     [same Error variants, same thrown types, same panic conditions]
- **Laziness:**            [unchanged / forced — e.g. was Iterator, now materialized to Vec]
- **Short-circuit eval:**  [unchanged — booleans still short-circuit in same order]
- **Floating-point:**      [bit-identical / N/A]
- **RNG / hash order:**    [unchanged / N/A]
- **Observable side-effects:** [logs, metrics, span names, DB writes — identical order + payload]
- **Type narrowing:**      [TS/Rust — discriminant checks still narrow in the same places]
- **Rerender behavior:**   [React — same memo keys, same hook order, same Suspense boundary]

### Verification
- [ ] `sha256sum -c refactor/artifacts/<run>/golden.sha256`  ✓
- [ ] `<test command>`  ✓
- [ ] `./scripts/loc_delta.sh <base> HEAD <path>` shows source-line delta as scored
- [ ] Typecheck / lints: zero new warnings (`tsc --noEmit` / `cargo clippy -- -D warnings`)

If you can't fill every row, you don't understand the change well enough to make it safely. Full axis guide: ISOMORPHISM.md.

---

Pattern Tiers (Quick Reference)

Tier 1: Mechanical (low risk, high LOC yield)

| Pattern | Shape | Typical Δ LOC | Isomorphism note | |---------|-------|---------------|------------------| | Extract constant | Magic number/string at ≥3 sites | small | Zero behavior change | | Extract function (Rule of 3) | 3+ near-identical spans | 10–50 | Verify all callers still build | | Parameterize (Type II clone) | Same shape, different literals | 15–80 | Confirm each literal still reachable | | Enum dispatch | send_foo / send_bar / send_baz | 40–150 | One arm per original fn; exhaustiveness checked | | Collapse wrapper | fn foo(x) { bar(x) } called once | 5–10 | Inline; kill the hop | | Replace conditional with polymorphism / match | Long if-else chain on type tag | 20–60 | Total match guarantees parity | | Remove dead branches | Flag permanently off / feature shipped | varies | Grep for the flag first | | Collapse type alias chain | A = B, B = C, C = concrete | small | Pure rename, no runtime change |

Tier 2: Structural (medium risk, high payoff)

| Pattern | Shape | Typical Δ LOC | Isomorphism note | |---------|-------|---------------|------------------| | Unify data model | UserDTO + UserRow + UserAPI | 50–300 | Only merge if every field means the same thing — check nullability + units | | Hoist to higher-order fn | Same control flow wrapping different bodies | 40–120 | Callbacks must not rely on captured scope from outer fn | | Component variants | PrimaryButton, SecondaryButton, DangerButton | 30–200 | Extract variant prop; one style map | | Custom hook (React) | Same useEffect + useState pair in ≥3 components | 20–80 | Confirm dep arrays stay the same | | Generic function | 4× same logic for i32, i64, u32, u64 | 30–100 | Trait bounds must encode the actual ops used | | Remove boilerplate via derive / macro | Hand-rolled PartialEq/Display/Serialize | 10–40 | Derived impl must match the hand-rolled semantics exactly | | Middleware / decorator extraction | Logging/retry/tracing at every handler | 30–100 | Order of middleware composition matters |

Tier 3: Architectural (high risk; require a plan doc)

| Pattern | When | Where it bites | |---------|------|----------------| | Collapse two services into one module | Services share 80%+ of logic, same deploy | DB migrations, routing, observability | | Replace inheritance with composition | Deep hierarchy with diamond / mixin | Implicit super() ordering, LSP violations | | Replace ORM with typed query builder | Reams of scaffolded boilerplate | Query plan changes silently | | Monorepo consolidation | 3+ packages re-publishing same utils | Build graph, CI caching, breaking release cadence |

Full catalog with code: TECHNIQUES.md.

---

Abstraction Ladder (don't climb too fast)

Rung 0: Copy-paste            ← two callsites. Leave it.
Rung 1: Extract function      ← three callsites, same shape.
Rung 2: Parameterize          ← three callsites, one axis of variance.
Rung 3: Enum/strategy         ← two+ axes of variance, bounded set.
Rung 4: Trait / interface     ← open set of implementors.
Rung 5: Generic + trait bound ← type-parametric, used across crates.
Rung 6: DSL / macro           ← you've done this exact refactor ≥3 times.

Never skip rungs. Jumping from rung 0 to rung 4 produces the AbstractFactoryBeanFactory nightmare. Rules:

• Rule of 3 — don't abstract until the third case. One is a unique. Two is a coincidence. Three is a pattern.
• One axis of variance per rung — if a shared function takes kind: Enum, mode: Enum, mode2: Enum, flags: u32, you climbed too fast.
• The cost of the abstraction is the sum of the variance it carries — when variance exceeds shape, the abstraction is worse than the duplication.

Full discussion, with failure case studies: ABSTRACTION-LADDER.md.

---

Language Cheatsheet

| Lang | Duplication scan | Common shrink | Grep for sloppiness | |------|------------------|---------------|---------------------| | Rust | similarity-rs · tokei · ast-grep -l Rust -p 'fn $N($$$A) { $$$B }' | enum dispatch, From/TryFrom, generics over 2+ identical fns, derive macros, ? for match-on-Result ladders | rg 'match .* Err\(e\) => Err\(e\)' -t rust (reinvented ?); rg 'impl.*for.*\{' -A20 -t rust (hand-rolled boilerplate) | | TypeScript/React | jscpd --min-lines 5 · similarity-ts · ts-morph refactors | discriminated unions, component variant prop, custom hooks, satisfies, narrow generic helpers instead of any | rg 'as any\|as unknown as' -t ts; rg 'const.*= \(.*\) =>.*useState' -t tsx (hook dupes) | | Python | pylint --disable=all --enable=duplicate-code · radon cc · vulture | @dataclass, TypedDict, functools.singledispatch, list/dict/set comprehensions, context managers | rg 'try:\s*\n\s*.*\s*\n\s*except .*:\s*\n\s*pass' -U -t py (swallowed exceptions copied) | | Go | dupl -threshold 50 · staticcheck -checks U1000 | generics (1.18+), interface embedding, table-driven tests, errors.Join | rg 'func.*Err\(\) error' -t go (near-identical error types) | | C++ | clang-tidy --checks='modernize-*,readability-*' · simian | CRTP for static polymorphism, std::variant over class hierarchy, templates, concepts (C++20), auto return | rg 'typedef .* \*.*_t' -t cpp (C-style, replace with using); rg '#define' --type cpp (macro sprawl) |

Full language guides, including false-positive patterns per tool: LANGUAGE-GUIDES.md.

---

Metrics You Report (not optional)

LOC:          net delta per-file and per-directory, via tokei/scc
duplication:  clone count + total cloned LOC, via jscpd / similarity-*
complexity:   cyclomatic (radon/gocyclo/lizard) — per-function, before/after
coupling:     imports-in + imports-out per module, before/after
test suite:   pass count before = pass count after (NOT just "green")
typecheck:    warning count before ≥ warning count after
bundle:       (frontend) gzipped JS bytes before/after — a refactor that grows the bundle is suspect

Variance envelope: if tests are flaky, lock a seed and re-run 5×. A refactor that's passing 4/5 vs. 3/5 was already broken before you touched it.

Ledger template: ARTIFACTS.md. Full dashboard template (post-pass reviewer summary): METRICS-DASHBOARD.md.

---

Metrics Dashboard (the post-pass report)

After the loop terminates, emit DASHBOARD.md — the single artifact reviewers and the user consume to know the pass succeeded. Full template and computation recipes: METRICS-DASHBOARD.md.

## Summary
| Metric              | Before | After | Δ       | Direction |
|---------------------|--------|-------|---------|-----------|
| LOC                 | 28,413 | 28,062| **−351**| ↓ ✅      |
| Duplication index   | 6.2%   | 3.8%  | −2.4 pp | ↓ ✅      |
| Cyclomatic mean     | 4.2    | 3.9   | −0.3    | ↓ ✅      |
| Test pass count     | 342    | 342   | 0       | = ✅      |
| Typecheck warnings  | 0      | 0     | 0       | = ✅      |
| Bundle (gz)         | 142 KB | 138 KB| −4 KB   | ↓ ✅      |
| Property tests      | 14     | 22    | +8      | ↑ (bonus) |
| Goldens identical   | —      | ✓     | —       | ✅        |

The goal: most metrics improve, others stay flat, none regress.

Metric tension signals

| Pattern | Meaning | |---------|---------| | LOC down, complexity up | you inlined helpers into a conditional. Re-extract. | | LOC up, duplication down | new abstraction is bigger than the dup it replaces. Audit. | | LOC down, test count up | added property tests — virtuous ratio. | | All improved, perf regressed | watch for .clone() introduction or collected iterators. Profile. |

---

Agent Coordination (multi-agent swarm)

For ≥5 independent candidates across distinct directories, running a swarm finishes in ~N minutes what serial does in ~8N. Requires ntm + agent-mail + br (all optional; fall back to solo sequential if missing).

| Element | Role | |---------|------| | br beads | own "what to do next"; one bead per accepted candidate; deps between beads | | agent-mail | file reservations (paths=[...], exclusive=true) prevent collision | | ntm panes | one agent per candidate; each runs the full loop autonomously | | bv | graph-aware triage picks the right order | | vibing-with-ntm | orchestrator loop + stuck-pane recovery |

Full architecture, launch recipe, collision policy, and recovery playbook: AGENT-COORDINATION.md.

Thread-id convention (AGENTS.md Agent Mail pattern):

• Mail thread_id: refactor-<bead-id>
• Commit trailer: Beads: <bead-id>
• File-reservation reason: refactor-<bead-id>

---

Anti-Patterns (never do these)

| ✗ | Why | |---|-----| | Refactor without a baseline test run | "Still green" means nothing if you didn't check before | | Collapse two functions with different error types into one | Callers now handle a wider error set than they used to | | Unify two data models by any \| null fields | You just moved the branching to every caller | | Extract helper from two callsites | That's rung 0 → rung 1 with no third data point. Wait. | | Replace if chain with polymorphism at rung 4 | Jumped past parameterize + enum dispatch. Likely over-engineered | | Use a script / sed / codemod to "fix all 200 call sites" | Forbidden by AGENTS.md — use parallel subagents or manual edits | | Create utils.ts / helpers.py dumping ground | Cross-cutting concern is a package, not a junk drawer | | Rename during refactor | Two levers per commit; reviewers can't tell what changed | | Introduce a new abstraction while removing duplication | Climbs the ladder on the same commit — bisect-hostile | | Delete the "obsolete" old file | NEVER — ask first (Rule Number 1 in AGENTS.md). And often the old file still has unique invariants. Run DEAD-CODE-SAFETY.md gauntlet BEFORE even proposing deletion. | | Claim "this is more readable" without measuring | Readability is a group judgment, not yours alone. Show LOC / complexity / coupling delta | | Rewrite the whole module "while we're here" | The only legitimate output is an Edit diff — if you find yourself wanting a Write, stop |

---

Checklist (before any commit)

• [ ] Baseline captured (tests green, goldens hashed, LOC + complexity + typecheck counts)
• [ ] Duplication map exported (jscpd/similarity-* report path cited)
• [ ] Candidate scored ≥ 2.0 on Opportunity Matrix
• [ ] Isomorphism card filled in, every row answered (no blanks)
• [ ] One lever only (no rename + extract + rewrite in same commit)
• [ ] Edits via Edit tool only; no Write to existing files; no script-based codemod
• [ ] Tests still pass (same count, not just "green")
• [ ] Golden outputs bit-identical (sha256sum -c)
• [ ] Typecheck / clippy / lint warnings did not grow
• [ ] LOC ledger updated — before→after delta per path
• [ ] Commit message contains the isomorphism card verbatim
• [ ] Rollback plan: git revert <sha> + any stateful side-effect to undo (DB migration, config)

---

Hand-off

When the ledger shows no Score ≥ 2.0 candidates left, stop. Say:

Simplification pass complete. Net Δ LOC: -X (Y%); duplication index -Z%; complexity mean -W; all goldens identical; tests still green; typecheck warnings unchanged. Next reviewer can re-open the loop by re-running the duplication scan — most remaining clones are Type IV/V and should be left alone.

Further passes happen after real feature work shifts the surface. New duplicates surface once noise clears, but scanning on the same commit twice is theater.

Sibling skills (who consumes what):

| Want to … | Use | |-----------|-----| | Identify performance hotspots to target | profiling-software-performance | | Apply an optimization after measuring | extreme-software-optimization | | Deep audit for latent bugs before/after refactor | multi-pass-bug-hunting, ubs | | Mine your own prior solutions for a particular shape | cass + /flywheel | | Review the resulting PR with multiple models | multi-model-triangulation |

Full cross-skill map: CROSS-SKILL.md.

---

Reference Index

Quick access (start here)

| Need | File | |------|------| | One-screen dense card — rule, loop, score formula, clone taxonomy, all gates | QUICK-REFERENCE.md | | Glossary — every term used across the skill with one-line definition | GLOSSARY.md | | FAQ — 20+ agent-friction Q&As (flaky tests, no goldens, "just delete it", etc.) | FAQ.md | | Decision trees — ASCII flowcharts for ambiguous calls (collapse/leave, rescue/main, stage/keep) | DECISION-TREES.md | | Visual diagrams — ASCII loop, score matrix quadrants, defense-in-depth layers | VISUAL-DIAGRAMS.md | | Cookbook — worked before/after examples per lever (9 recipes across 5 languages) | COOKBOOK.md | | Formulas — copy-paste templates for ledger rows, commit messages, PR bodies, subagent prompts | FORMULAS.md | | Selection — when to use THIS skill vs. siblings (simplify / optimization / archaeology / etc.) | SELECTION.md | | Testing — how to PROVE a refactor is isomorphic (unit / golden / property / replay) | TESTING.md | | Validation — runnable self-checks for this skill package | VALIDATION.md | | Structure — folder layout and artifact map | STRUCTURE.md |

Per-phase and situational guides

| Need | File | |------|------| | Exit criteria + time-boxes — precise "done" gate per phase and per pass | EXIT-CRITERIA.md | | Benchmarks — what a good pass looks like (LOC deltas, ship/reject ratios, timings) | BENCHMARKS.md | | Cold-start — applying this skill to a project with no baseline | COLD-START.md | | Rollback playbook — what to do when a shipped collapse breaks prod | ROLLBACK-PLAYBOOK.md | | Reviewer quickstart — 10-min audit of a skill-produced PR | REVIEWER-QUICKSTART.md | | Team adoption — L0 → L3 maturity ladder for rolling out the discipline | TEAM-ADOPTION.md |

Guardrail integration (defense-in-depth)

| Need | File | |------|------| | cc-hooks — Claude Code hooks (PreToolUse / PostToolUse / Stop) | HOOKS.md | | git hooks — native pre-commit / commit-msg / pre-push | GIT-HOOKS.md | | CI/CD integration — GitHub Actions / GitLab / CircleCI full workflows | CI-CD-INTEGRATION.md | | Skill self-validation — frontmatter, links, kernel, corpus, operator cards, script syntax | VALIDATION.md |

Core methodology

| Need | File | |------|------| | Phase-by-phase method (BASELINE → HAND-OFF) with worked examples | METHODOLOGY.md | | Full pattern catalog (Tier 1/2/3) with code in Rust/TS/Python/Go/C++ | TECHNIQUES.md | | 80+ named micropatterns with exact before/after | MICROPATTERNS.md | | Rust / TS / Python / Go / C++ specifics + tool invocations | LANGUAGE-GUIDES.md | | Clone types, decision tree, false-positive gallery | DUPLICATION-TAXONOMY.md | | Abstraction ladder, Rule of 3, over-abstraction autopsies | ABSTRACTION-LADDER.md | | Full isomorphism axis guide — ordering, errors, laziness, FP, FFI, async, React | ISOMORPHISM.md |

Vibe-coded / AI-generated code

| Need | File | |------|------| | 40 canonical AI-generated pathologies (P1-P40) + detection + collapse recipes | VIBE-CODED-PATHOLOGIES.md | | Dead-code safety gauntlet — the 12-step check to prevent the "deleted as dead code" horror story | DEAD-CODE-SAFETY.md | | Rescue missions for already-broken vibe-coded codebases (stabilize before refactoring) | RESCUE-MISSIONS.md | | Continuous-refactor cadence (hooks / CI gates / weekly / monthly) | CONTINUOUS-REFACTOR.md | | Property-based tests as the refactor safety net | PROPERTY-TESTS.md | | Citations from real indexed agent sessions — pathology evidence + horror stories + user vocabulary | REAL-SESSION-EVIDENCE.md | | Quote bank — every rule anchored to a specific verbatim source | CORPUS.md | | Triangulated kernel — the 30 operational rules, marker-delimited for extraction | TRIANGULATED-KERNEL.md | | Prompt engineering — how to write prompts that get the skill's benefits | PROMPT-ENGINEERING.md | | Anti-patterns II — swarm / long-session / rescue / cross-skill / orchestrator anti-patterns | ANTI-PATTERNS-2.md | | Flywheel integration — feed session observations back into the skill | FLYWHEEL-INTEGRATION.md |

Kickoff prompts (role library)

| Need | File | |------|------| | Ready-to-paste session kickoffs for solo / orchestrator / worker / reviewer / rescue / weekly / monthly / audit / post-incident / handoff | KICKOFF-PROMPTS.md |

Language deep-dives (beyond LANGUAGE-GUIDES.md)

| Need | File | |------|------| | Rust: borrow checker, lifetimes, trait bounds, Drop impls, unsafe, workspaces | RUST-DEEP.md | | Python: async split, dataclass/Protocol, decorators, contextvars, metaclasses, mypy strict | PYTHON-DEEP.md | | Go: interface composition, generics, goroutine ownership, channel idioms, context propagation | GO-DEEP.md | | C++: RAII, Rule of 0/3/5, std::variant, concepts, ranges, constexpr, sanitizers | CPP-DEEP.md | | Advanced micropatterns (M41-M80) — second-tier collapses across all languages | ADVANCED-MICROPATTERNS.md |

Cross-cutting concerns

| Need | File | |------|------| | Monorepo refactors (Turborepo/Nx/pnpm/Cargo-workspace/Bazel) | MONOREPO.md | | Security-aware refactors (auth, validation, secrets, RLS, CORS) | SECURITY-AWARE-REFACTOR.md | | Performance-aware refactors + hand-off to optimization skill | PERF-AWARE-REFACTOR.md |

Domain-specific deep dives

| Need | File | |------|------| | React-specific isomorphism axes, hook extraction, Suspense, RSC | REACT-DEEP.md | | DB schema + query + migration refactors | DB-SCHEMAS.md | | Type-system shrinks (generics, unions, branded types, phantom types) | TYPE-SHRINKS.md |

Orchestration

| Need | File | |------|------| | Install jsm + sibling skills; graceful degradation | JSM-BOOTSTRAP.md | | Multi-agent swarm via NTM + agent-mail + beads | AGENT-COORDINATION.md | | The seven metrics; dashboard template; CI integration | METRICS-DASHBOARD.md |

Operators, prompts, and artifacts

| Need | File | |------|------| | Operator algebra (⊘ Split, ⊞ Merge, 𝓡 Parameterize, 🛡 Isomorphism, …) | OPERATOR-CARDS.md | | Copy-paste prompts for each operator + end-to-end runs | PROMPTS.md | | LOC ledger, duplication map, isomorphism card templates | ARTIFACTS.md | | Real agent session case studies (Rust / React / Python / Go) | CASE-STUDIES.md | | Anti-patterns expanded with failure autopsies | ANTI-PATTERNS.md | | How to compose with other skills + agent mail + beads | CROSS-SKILL.md |

Ready-to-copy templates (assets/)

| Need | File | |------|------| | Isomorphism card template | assets/isomorphism_card.md | | Ledger header + scoreboard template | assets/ledger_header.md | | Rejection-log entry template | assets/rejection_log.md | | Per-pass dashboard skeleton | assets/dashboard_skeleton.md | | PR description body | assets/pr_description.md | | Beads (br) workflow cheat-commands | assets/bead_commands.md |

Role-specialized subagents (subagents/)

| Role | File | |------|------| | Proposes an Edit-tool plan for a candidate; never executes | subagents/refactor-extractor.md | | Audits a refactor diff against its isomorphism card | subagents/refactor-reviewer.md | | Scans the repo and produces a scored duplication_map.md | subagents/duplication-scanner.md | | Stress-tests a filled isomorphism card for completeness | subagents/isomorphism-auditor.md | | Runs the 12-step dead-code safety gauntlet on a target | subagents/dead-code-checker.md |

Scripts (zero context cost, run directly)

| Need | File | |------|------| | Bootstrap — check siblings + jsm state; emit inventory JSON | scripts/check_skills.sh | | Bootstrap — run jsm official installer (user-consent-gated) | scripts/install_jsm.sh | | Bootstrap — bulk jsm install for missing siblings | scripts/install_missing_skills.sh | | Capture baseline: tests + goldens + LOC + complexity + warnings | scripts/baseline.sh | | Run duplication scanners per language and emit unified JSON map | scripts/dup_scan.sh | | AI-slop detector — scan for P1-P40 vibe-code pathologies | scripts/ai_slop_detector.sh | | Compute source-line delta for a path between two git refs (--net-only for CI) | scripts/loc_delta.sh | | Verify goldens + tests + typecheck + LOC match isomorphism card | scripts/verify_isomorphism.sh | | Emit the per-commit isomorphism card template | scripts/isomorphism_card.sh | | Rank candidates via Opportunity Matrix from a JSON duplication map | scripts/score_candidates.py | | Property-test scaffold — emit language-appropriate skeleton | scripts/property_test_scaffold.sh | | Metrics snapshot — compute the 7 dashboard metrics | scripts/metrics_snapshot.sh | | Swarm launcher — NTM panes + marching orders | scripts/multi_agent_swarm.sh | | Dead-code safety gauntlet — automated 12-step check | scripts/dead_code_safety_check.sh | | Callsite census — enumerate every reference to a symbol | scripts/callsite_census.sh | | Boundary validator scaffold — emit zod/pydantic/serde template to eliminate any propagation | scripts/boundary_validator_scaffold.sh | | Ledger row — emit a LEDGER.md row from current git state | scripts/ledger_row.sh | | Lint ceiling — enforce warning-count ceiling (R-013) | scripts/lint_ceiling.sh | | Rescue gate check — validate rescue-mission exit criterion | scripts/rescue_phase_check.sh | | Unpinned deps — flag floating dependency versions (P37) | scripts/unpinned_deps.sh | | One-shot session setup — run check_skills + baseline + dup_scan + slop_detector + metrics | scripts/session_setup.sh | | Kernel extractor — print the marker-delimited triangulated kernel | scripts/extract_kernel.sh | | Operator-card validator — enforce definition/triggers/failures/prompt-module shape | scripts/validate_operators.py | | Corpus validator — enforce quote-bank source/tag/verbatim/rule/usage fields | scripts/validate_corpus.py | | Skill contract validator — top-level read-only validation gate | scripts/validate_skill_contract.py |

---

Self-Test

Trigger tests: SELF-TEST.md.