outlinedriven/refactor-break-bw-compat
skills/refactor-break-bw-compat/SKILL.md
Refactor by removing backward compatibility and legacy layers. Use when modernizing APIs, cleaning up migration debt, removing compat shims, or eliminating stale feature flags.
$ install --global
skillsauthnpx skillsauth add outlinedriven/odin-codex-plugin refactor-break-bw-compatInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 30, 2026, 5:21 PM11.4s1 file scanned
SKILL.md
- name:
- refactor-break-bw-compat
- description:
- Refactor by removing backward compatibility and legacy layers. Use when modernizing APIs, cleaning up migration debt, removing compat shims, or eliminating stale feature flags.
Breaking Refactors — Freedom Through Structure
Compatibility layers are coupling debt with interest. Every compat shim is a decision deferred, not a decision avoided. Break cleanly, break once, break with evidence.
Principles
- No half-measures. A partial migration is worse than no migration — it doubles the surface area and confuses every reader.
- One migration direction. Old-to-new only. Never add new-to-old adapters; that entrenches the old path.
- Blast radius awareness. Map every consumer before removing anything. Surprise breakage is a planning failure, not a courage signal.
- Dead code is a lie. "Just in case" code is not dead — it actively misleads readers about what the system does.
- Compat shims are temporary. If a shim has no removal date, it is permanent. If it is permanent, it is architecture. Decide which.
Reconnaissance Checklist
Before breaking anything, find and catalog:
@deprecated/#[deprecated]/warnings.warnmarkers — especially ones without removal versions- Version-gated code paths (
if version >= X, feature flags,#[cfg(feature = "legacy")]) - Adapter / shim / bridge / wrapper layers that translate between old and new interfaces
- Dual serialization formats (v1/v2 JSON schemas, protobuf
oneofwith legacy fields) - Tests that exist solely to validate backward-compatible behavior
- Configuration keys that toggle between old and new behavior
- Re-export / forwarding modules that alias old paths to new locations
- Changelog entries promising deprecation timelines
Decision: Break or Not?
| Signal | Break | Do NOT Break | |--------|-------|--------------| | Zero external consumers | Yes | — | | Single internal consumer, you own it | Yes | — | | Well-tested, high coverage | Yes | — | | Clear new path exists | Yes | — | | External/public API with unknown consumers | — | Not without migration plan | | No tests covering the boundary | — | Write tests first, then break | | Multiple consumers, unclear ownership | — | Map consumers first | | Compat layer under active use by migration-in-progress | — | Finish migration first |
Execution Strategy
- Map blast radius. List every file, module, and external consumer that references the old API. Use
ast-grep,rg, or equivalent — not guesswork. - Snapshot current behavior. Ensure tests cover the old path. If coverage is missing, add characterization tests before removal.
- Remove the old path. Delete the compat layer, adapter, or legacy code. Do not comment it out.
- Update all call sites. Migrate every reference found in step 1 to the new API. Compile/typecheck after each batch.
- Delete orphaned tests. Tests that validated the old path are now dead weight. Remove them.
- Search for ghosts. Grep for string references, config keys, environment variables, documentation links, and error messages that mention the old API.
- Verify no dead imports/deps. Check for unused imports, packages, or dependencies that only the old path required.
Anti-patterns
- "Just in case" paths — keeping old code "in case someone needs it." That is what version control is for.
- Partial migration — half the codebase on new API, half on old. Worse than either alone.
- Commenting out instead of deleting — commented code is invisible debt that greps cannot find.
- Compat-of-compat — wrapping a compat layer in another compat layer. Two wrongs do not make an abstraction.
- Deprecated without removal date — a deprecation warning without a deadline is a suggestion, not a plan.
- Stale feature flags — flags that are always on (or always off) in every environment. Delete the flag, keep the winning path.
Validation Gates
| Gate | Condition |
|------|-----------|
| Blast radius mapped | Every consumer of old API identified and listed |
| Tests green pre-removal | Existing tests pass before any deletion begins |
| Zero references post-removal | ast-grep / rg for old API names returns zero hits |
| No dead imports/deps | No unused imports, packages, or type declarations remain |
Exit Codes
| Code | Meaning | |------|---------| | 0 | Clean break — old API fully removed, all consumers migrated, tests pass | | 1 | Partial — old references remain in code, docs, or config | | 2 | Tests broken — removal caused test failures not yet resolved | | 3 | External consumers found — need migration plan before proceeding |
Related Skills
outlinedriven/tidy
testing
VerifiedTrustedCommunity
ODIN's compress-operations dispatcher under the Compressor/Extender role. Invoke on "tidy", "clean up", "tidy this file/memory/workspace/git/docs", or when active context (current file, diff, stack, memory directory) has structural rot to resolve before touching behavior. Detects target domain from context and routes to the sibling skill. Requires explicit target or clear active-context signal — do not invoke speculatively.
12SKILL.mdUpdated May 7, 2026
outlinedriven/taste
development
VerifiedTrustedCommunity
Cross-domain taste skill — apply distinctive judgment to any artifact (prose, code, design, decisions) instead of converging to AI defaults. Two modes — `audit` (judge work against the two-sided charter and portable anchors) and `anchor` (load register before producing). Auto-detects by phrasing; override via `/taste audit | anchor`. Trigger on "is this slop?", "overkill?", "elegant?", "taste-test this".
12SKILL.mdUpdated May 4, 2026
outlinedriven/strict-validation-setup
tools
VerifiedTrustedCommunity
One-shot bootstrap of strict-mode tooling per ecosystem plus per-task GOALS.md scaffolding so an agentic loop can self-verify. Writes typechecker/linter/schema-validator config for TS (strict + noUncheckedIndexedAccess + exactOptionalPropertyTypes), Python (Pyright strict, Ruff strict), Rust (Clippy deny-correctness), Go (golangci-lint with staticcheck), OCaml (dune --release); establishes `.agent-tasks/<id>/GOALS.md` per-task convention distinct from project-stable AGENTS.md. C++/Java/Kotlin and framework specifics (Spring Boot, Nest, React-strict) are out of scope. Trigger on new project bootstrap, agentic-task setup, "make this self-verifying", "set the loop's goal", "scaffold goals for this issue". Pairs with `llm-self-loop` runtime.
12SKILL.mdUpdated May 4, 2026
outlinedriven/setup-pre-commit
tools
VerifiedTrustedCommunity
Install git pre-commit hooks via the project's hook tool — Husky+lint-staged (JS), pre-commit (Python/OCaml), lefthook (Go), cargo-husky (Rust). Use when the user wants commit-time formatting, linting, type-checking, or test gates. Detects ecosystem first.
12SKILL.mdUpdated May 4, 2026