Zero Tech Debt
Build toward the intended product shape — not the historical sequence of patches, migrations, wrappers, aliases, and temporary decisions that created the current implementation.
The goal is not "minimal diff."
The goal is a cleaner, more coherent system with fewer moving parts, fewer hidden assumptions, and lower long-term operational cost.
Core Principle
Treat the current implementation as evidence, not authority.
Preserve only the parts that still serve the intended architecture, UX, reliability model, and operational constraints. Everything else is eligible for deletion.
Operating Mode (read this section every invocation)
- Confirm scope —
Read references/01-when-to-use.md. If the request smells like a hotfix, security backport, or time-boxed patch, stop and recommend a targeted change instead.
- Pre-flight — walk
references/02-preflight-checklist.md. Every box must be checked before touching code. Tests, callers, rollback path, single-paragraph end-state description, no in-flight migration, telemetry accounted for. Use Glob to locate test files and Grep / Bash(rg:*) to enumerate external callers of the surface being changed.
- Run the 7-step workflow —
references/03-workflow.md. Define end state → audit reality → delete before adding → optimize around final shape → collapse duplicate decision logic → remove historical leakage → validate.
- Use the audit patterns —
references/04-audit-patterns.md lists the concrete Grep / Bash(rg:) / Bash(fd:) targets (TODO/DEPRECATED markers, v2/old suffixes, stale feature flags, dual-mode forks, etc.). Each match is a candidate, not an automatic deletion.
- Apply decision filters when choices tie —
references/05-decision-filters.md covers tiebreakers and named anti-patterns to avoid.
- Apply edits with
Edit — once a deletion / rename / consolidation is approved, use Edit to apply the change atomically. Stage with Bash(git:*) so the operator can review per commit before push.
- Report back in shape-change terms —
references/06-outcomes-and-reporting.md. The diff lists every line; the summary makes the architectural delta legible.
Scope Discipline (this is the most common failure mode)
A zero-tech-debt refactor wil