@intentsolutionsio/zero-tech-debt 1.0.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "zero-tech-debt",
+  "version": "1.0.0",
+  "description": "Rebuild a feature as if the correct product architecture existed from day one. Removes compatibility cruft, dead abstractions, and historical compromises instead of preserving them. Methodology-only — no destructive actions without operator approval.",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io"
+  },
+  "repository": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills",
+  "license": "MIT",
+  "keywords": [
+    "refactoring",
+    "tech-debt",
+    "architecture",
+    "cleanup",
+    "modernization",
+    "code-quality"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intent Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# zero-tech-debt
+
+> Build toward the intended product shape — not the historical sequence of patches.
+
+A methodology skill for Claude Code that guides structural refactors: rebuild the feature as if the correct architecture existed from day one. Removes compatibility cruft, dead abstractions, and historical compromises instead of preserving them.
+
+## When to invoke
+
+Strong signals from the operator:
+
+- "refactor properly" / "clean up" / "rewrite" / "modernize"
+- "remove legacy" / "simplify" / "rethink" / "pay down tech debt"
+- Frustration with accumulated complexity
+- Multiple parallel implementations for the same logical operation
+- New features keep routing around old scaffolding instead of through it
+
+## When NOT to invoke
+
+- Production hotfixes (minimize diff, preserve blast radius)
+- Security backports (preserve audit clarity)
+- Time-boxed patches before a release cut
+- Code owned by another team without prior coordination
+- Anywhere the cost of being wrong exceeds the cost of staying messy
+
+## How it loads (progressive disclosure)
+
+The main `SKILL.md` is short. The deep methodology lives in `references/`:
+
+| File | What's in it |
+|---|---|
+| [`01-when-to-use.md`](skills/zero-tech-debt/references/01-when-to-use.md) | Trigger signals + non-triggers |
+| [`02-preflight-checklist.md`](skills/zero-tech-debt/references/02-preflight-checklist.md) | Pre-flight requirements before touching code |
+| [`03-workflow.md`](skills/zero-tech-debt/references/03-workflow.md) | The 7-step refactor workflow |
+| [`04-audit-patterns.md`](skills/zero-tech-debt/references/04-audit-patterns.md) | Concrete grep targets for finding debt |
+| [`05-decision-filters.md`](skills/zero-tech-debt/references/05-decision-filters.md) | Tiebreakers + anti-patterns |
+| [`06-outcomes-and-reporting.md`](skills/zero-tech-debt/references/06-outcomes-and-reporting.md) | Success criteria + how to summarize the result |
+
+Claude reads `SKILL.md` first, then pulls the references it needs as the work unfolds. You don't have to read them all up front.
+
+## Scope discipline
+
+A zero-tech-debt refactor will tempt unbounded scope. The skill explicitly:
+
+- Holds to **one coherent end state per refactor** — not three loosely related ones
+- Stops and documents deeper rot rather than chaining refactors mid-flight
+- Refuses "while I'm here" additions unrelated to the deletion path
+- Splits oversized work along ownership boundaries, never along file counts
+
+If the operator wants a hotfix, this skill is the wrong tool — recommend a targeted patch instead.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@intentsolutionsio/zero-tech-debt",
+  "version": "1.0.2",
+  "description": "Rebuild a feature as if the correct product architecture existed from day one. Removes compatibility cruft, dead abstractions, and historical compromises instead of preserving them. Methodology-only —",
+  "keywords": [
+    "refactoring",
+    "tech-debt",
+    "architecture",
+    "cleanup",
+    "modernization",
+    "code-quality",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/skill-enhancers/zero-tech-debt"
+  },
+  "homepage": "https://tonsofskills.com/plugins/zero-tech-debt",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install zero-tech-debt\\\\n  or /plugin install zero-tech-debt@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}

package/skills/zero-tech-debt/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: zero-tech-debt
+description: |
+  Rebuild a feature as if the correct product architecture existed from day one — remove compatibility cruft, dead abstractions, and historical compromises instead of preserving them. Use when the operator says "refactor properly," "clean up," "rewrite," "modernize," "remove legacy," "simplify," "rethink," "pay down tech debt," or signals frustration with accumulated complexity. Do NOT use for hotfixes, bug repros, surgical patches, or security backports — blast-radius minimization wins there. Trigger with "/zero-tech-debt", "do it right this time", "the way it should have been built", "refactor toward intent".
+allowed-tools: Read, Edit, Glob, Grep, Bash(git:*), Bash(rg:*), Bash(fd:*)
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatibility: Designed for Claude Code
+tags: [refactoring, tech-debt, architecture, cleanup, modernization, code-quality]
+user-invocable: true
+---
+
+# 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)
+
+1. **Confirm scope** — `Read` [`references/01-when-to-use.md`](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.
+2. **Pre-flight** — walk [`references/02-preflight-checklist.md`](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.
+3. **Run the 7-step workflow** — [`references/03-workflow.md`](references/03-workflow.md). Define end state → audit reality → delete before adding → optimize around final shape → collapse duplicate decision logic → remove historical leakage → validate.
+4. **Use the audit patterns** — [`references/04-audit-patterns.md`](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.
+5. **Apply decision filters when choices tie** — [`references/05-decision-filters.md`](references/05-decision-filters.md) covers tiebreakers and named anti-patterns to avoid.
+6. **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.
+7. **Report back in shape-change terms** — [`references/06-outcomes-and-reporting.md`](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 will tempt unbounded scope. Hold the line:
+
+- **One coherent end state per refactor** — not three loosely related ones
+- If deletion reveals deeper rot, document it and stop; do not chain refactors mid-flight
+- Resist "while I'm here" additions unrelated to the deletion path
+- New features wait for a separate change
+- If the work cannot fit in a single reviewable unit, split along ownership boundaries — never along file counts
+
+## Final Rule
+
+Do not optimize for preserving the past.
+
+Optimize for making the next 2 years of development simpler.
+
+---
+
+See [`references/`](references/) for the full methodology — each file is a single concern, loadable on demand.

package/skills/zero-tech-debt/references/01-when-to-use.md

@@ -0,0 +1,33 @@
+# When to Use (and Not Use) zero-tech-debt
+
+The most expensive failure mode of this skill is misclassification: applying a structural refactor where a surgical patch was wanted, or applying a hotfix where rot needed to be removed at the root. Get this judgment right *before* anything else.
+
+## Strong signals — proceed with zero-tech-debt
+
+- Operator explicitly names tech debt, legacy code, or accumulated complexity
+- Operator says "do it right this time" / "the way it should have been built" / "rethink this" / "refactor properly" / "modernize"
+- **Multiple parallel implementations exist** for the same logical operation (two routes that do the same thing, two state containers holding overlapping fields, two functions whose only difference is one was added later)
+- **Naming no longer matches what the code actually does** — the function called `processOrder` now handles refunds, subscriptions, and gift cards because nobody renamed it
+- **Onboarding requires explaining "why we have both X and Y"** — a near-perfect tech-debt detector
+- **Feature work keeps routing around old scaffolding** instead of through it — every new ticket has a "but first, work around this" step
+
+## Weak signals — clarify intent before invoking
+
+- Generic "improve this code" with no scope — ask: *what specific shape do you want the end state to have?*
+- Bug reports that merely touch legacy paths — usually a targeted patch is the right answer
+- Performance work where structural cleanup is incidental — split the work; performance fix lands first, structural cleanup separately
+- "Refactor" used loosely — could mean rename-only, could mean rebuild — disambiguate before committing scope
+
+## Hard non-triggers — recommend a surgical patch instead
+
+- **Production hotfixes** — minimize diff, preserve blast radius, ship the fix, log the rot for later
+- **Security backports** — preserve audit clarity and reviewer focus; reviewers need to see exactly what changed and nothing else
+- **Time-boxed patches before a release cut** — the cost of being wrong exceeds the cost of staying messy
+- **Code owned by another team without prior coordination** — you can write the refactor; you can't make it land
+- **Anywhere blast-radius matters more than long-term coherence** — payments, auth, anything with a regulatory or contractual surface
+
+## The escape valve
+
+If any non-trigger condition applies, the right move is to **stop and recommend a targeted patch**. Document the rot you noticed in a follow-up ticket so it doesn't get lost — but don't expand the current change to fix it.
+
+This is the discipline that keeps zero-tech-debt from becoming "every change is a giant refactor."

package/skills/zero-tech-debt/references/02-preflight-checklist.md

@@ -0,0 +1,42 @@
+# Pre-Flight Checklist
+
+Refactoring without these creates the next generation of tech debt. Every box must be checked **before** touching code. If any item is unchecked, resolve it before proceeding — even if that means asking the operator to write a test, identify a caller, or confirm a rollback path.
+
+## The six checks
+
+- [ ] **Tests exist (or can be written) for behavior worth preserving**
+  Without tests, you can't tell the difference between "I removed a bug" and "I removed a load-bearing accident." Don't refactor a system whose tests assert the historical bug shape — fix those tests first, against intended behavior, then refactor.
+
+- [ ] **Every external caller of the surface being changed has been identified**
+  Use `rg` / `grep` / IDE call-graph tools across the whole repo. For library exports, also check downstream consumers if you can reach them. A refactor that breaks an unknown caller is worse than no refactor.
+
+- [ ] **A rollback path exists** — branch, feature flag, or staged rollout
+  If the change ships and breaks something subtle in production, what's the un-stuck plan? "Revert the merge commit" only works if the merge commit is reachable and the code that depended on the new shape hasn't shipped on top of it. For larger refactors, prefer a feature flag with a clean off-position.
+
+- [ ] **The intended end state fits in 1-3 paragraphs**
+  See workflow step 1 ([`03-workflow.md`](03-workflow.md)). If you can't describe the end state in plain prose, the refactor is not yet well-defined — and an under-defined refactor will drift into unbounded scope. Stop and clarify.
+
+- [ ] **No active migration is in flight against the same code**
+  Two simultaneous structural changes on overlapping surface area produce merge conflicts you can't resolve and behavior changes you can't attribute. If a migration is already running, defer the refactor or coordinate with the migration owner.
+
+- [ ] **Telemetry, logging, and alerts tied to deleted code are accounted for**
+  Dashboards, alert rules, log queries, and on-call runbooks may reference function names, log strings, or metric keys you're about to delete. Identify these *first*. Either update them in the same change or document the breakage explicitly and notify the on-call.
+
+## Why this checklist is hard rules, not advice
+
+Each item is the missing-step from a failure pattern that's already happened. The checklist exists because skipping any of them *predictably* produces:
+
+- a refactor that ships against an unknown caller and breaks production
+- a "successful" refactor whose tests passed because they were asserting the wrong behavior
+- a refactor with no rollback path that has to be hot-patched at 2 AM
+- a refactor that grows from "clean up one flow" to "rewrite three subsystems" mid-PR
+- a refactor that merge-conflicts with someone else's in-flight migration
+- a refactor whose deletion silently broke the on-call alerting
+
+If you skip a check and the failure happens anyway, you don't get to claim it was unforeseeable.
+
+## When the operator pushes to skip
+
+If the operator says "we don't have tests for this, just refactor it" — that's a signal to write the characterization tests first, *as part of this work*, then refactor against them. The cost of writing one test is much lower than the cost of an undetected behavior change.
+
+If the operator says "no time for a rollback path" — that's a signal that this isn't actually a zero-tech-debt refactor; it's a time-boxed patch, and you should switch tools.

package/skills/zero-tech-debt/references/03-workflow.md

@@ -0,0 +1,122 @@
+# The 7-Step Workflow
+
+This is the operational core of zero-tech-debt. Walk the steps in order. Don't skip step 1.
+
+## 1. Define the Intended End State
+
+Before touching code, describe in 1-3 concise paragraphs:
+
+- **What the final UX should feel like** — what the user / operator / caller sees and does
+- **What the clean architecture should look like** — one coherent flow, one source of truth, one ownership boundary
+- **What the public surface area actually needs to be** — every other function/route/export is private
+- **What developers should intuitively expect** — what a new hire would guess without reading the code
+
+If the intended end state is unclear, **stop and clarify before refactoring**. Code is the wrong medium for thinking through architecture; prose is faster and revisable.
+
+## 2. Audit Reality Against Intent
+
+Identify everything in the current implementation that doesn't serve the end state:
+
+- Compatibility shims, legacy wrappers, route aliases, duplicate flows
+- Feature flags that became permanent architecture
+- State duplicated across layers
+- "Just in case" abstractions that turned out never to be needed
+- Dead props, modes, handlers, and APIs
+- Historical naming that no longer reflects product intent
+
+Document, for each candidate for removal:
+
+- **Why it exists** — what problem was it solving when it was written?
+- **Who currently calls it** — is anyone still using it, or is it cargo-culted?
+- **Whether it still provides real value** — does the user-visible behavior change if it's gone?
+
+See [`04-audit-patterns.md`](04-audit-patterns.md) for concrete grep targets.
+
+## 3. Delete Before Adding
+
+Before introducing **a new abstraction / hook / config layer / flag / adapter / state container**, attempt to:
+
+- Remove obsolete logic
+- Collapse duplicated paths
+- Simplify ownership boundaries
+- Unify flows
+- Flatten unnecessary indirection
+
+**Prefer subtraction over architecture theater.** A refactor that adds three new abstractions to "fix" tech debt has not paid down debt — it has moved it.
+
+Important: don't introduce a new abstraction in the *same change* that removes an old one. Split into two reviewable steps so the reviewer can evaluate the deletion separately from the addition.
+
+## 4. Optimize Around the Final Shape
+
+Refactor toward the system that **should exist today**, not the system that minimizes diff.
+
+Do not preserve bad boundaries simply because:
+
+- They existed historically
+- They reduced diff size
+- They avoided touching multiple files
+- They were once needed during migration
+
+Prefer:
+
+- One coherent flow
+- One authoritative source of truth
+- One obvious ownership boundary
+- One naming system
+- One predictable state model
+
+## 5. Collapse Duplicate Decision Logic
+
+Rules should exist in one place. Don't duplicate:
+
+- Permission checks
+- Feature gating
+- Route logic
+- URL parsing
+- State derivation
+- Validation rules
+- Retry behavior
+- Command naming
+- Orchestration logic
+
+**View components should not secretly own domain policy.** If your React component has a permission check inline, that policy is now duplicated wherever else the resource is accessed. Lift it to one authoritative location.
+
+## 6. Remove Historical Leakage
+
+The codebase should describe **current product intent**, **current domain language**, **current operational reality** — not old implementation history.
+
+Rename:
+
+- Legacy terminology that no longer matches the product
+- Migration-oriented naming (`*_v2`, `*_new`, `Legacy*`)
+- Implementation-leaked concepts (e.g., a class called `MongoOrderStore` when Mongo was replaced with Postgres last year)
+- Misleading abstractions whose names suggest one responsibility but implement another
+
+Prefer names aligned with:
+
+- User behavior
+- Domain intent
+- System responsibility
+
+A rename without redirecting callers leaves a search-and-find trail of broken references. Always update every caller in the same commit as the rename.
+
+## 7. Validate the New Shape
+
+After refactoring, verify:
+
+- **Deleted paths truly have no callers** — re-grep, including in test files, config files, docs, and CI
+- **Navigation still works** — for UI work, click through the affected flows manually, don't rely on snapshot tests
+- **Persisted state still behaves correctly** — for storage refactors, migrate-up then migrate-down then migrate-up again on a real database snapshot
+- **Permission boundaries remain correct** — re-walk the auth flow with a non-admin account
+- **APIs remain coherent** — for public surfaces, run any contract tests; for internal APIs, walk the call graph
+- **Tests validate intended behavior** rather than historical quirks — if a test references a deleted concept, the test was probably wrong, not the refactor
+
+Add regression coverage for:
+
+- Removed assumptions
+- State transitions
+- Orchestration boundaries
+- Routing behavior
+- Migration-sensitive logic
+
+The new tests should describe the *intended shape*, not the historical shape. If you find yourself writing a test that asserts the old behavior, stop and ask whether the old behavior was actually correct.

package/skills/zero-tech-debt/references/04-audit-patterns.md

@@ -0,0 +1,126 @@
+# Audit Patterns — Concrete Things to Grep For
+
+This is the hands-on toolkit for step 2 of the workflow (Audit Reality Against Intent). Each pattern below is a *candidate* for deletion, not an automatic delete. Examine the context, then decide.
+
+## Marker comments
+
+The most reliable signal of intentional debt: someone already flagged it.
+
+```
+rg -n "TODO: remove after|DEPRECATED|legacy|temp:|hack:|XXX:|FIXME"
+```
+
+Look especially for `// TODO: remove after <date>` where the date is past, and `// temporary` comments that have been there for over a year.
+
+## Versioned identifiers
+
+Functions, files, classes, types, or modules whose name encodes a version or generation:
+
+```
+rg -n "_v2|_v3|_new|_old|_legacy|V2$|V3$|Legacy[A-Z]"
+fd -e ts -e tsx -e py -e go -e rs "(_v2|_new|_old|_legacy)"
+```
+
+These are usually one of three things:
+1. A successful migration where the `_old` should be deleted
+2. A failed migration where the `_new` should be deleted
+3. An in-flight migration — confirm with the owner before touching
+
+## Stale feature flags
+
+Feature flags older than ~6 months that still default to a single branch:
+
+- Check the flag-management system's "default value never changed" view
+- Grep for `if (flags.<flagName>)` and check how many code paths each side has
+- A flag with a one-line `else` branch (or no `else` at all) is a candidate for inlining
+
+## Pass-through wrappers
+
+Wrappers whose only job is renaming arguments or repackaging return values:
+
+```python
+def get_user(user_id):
+    return fetch_user(user_id)
+
+def fetch_user(user_id):
+    return _user_repo.find(user_id)
+```
+
+Three layers, one operation. Collapse to one.
+
+## Delegating route handlers
+
+Route handlers that only delegate to other route handlers (often a legacy URL alias kept "just in case"):
+
+```js
+app.get('/api/v1/users', (req, res) => app._router.handle({...req, url: '/api/users'}, res))
+```
+
+Either kill the alias or document why it's load-bearing.
+
+## Dual-mode forks
+
+`if (env === 'old' || env === 'legacy')` or `if (clientVersion < N)` branches:
+
+- The "old mode" path is rarely tested
+- It accumulates new bugs because nobody exercises it
+- Killing it requires confirming all consumers are off the old mode — but the data to confirm is usually accessible
+
+## Duplicate config keys
+
+Config keys with near-identical names that diverged over time:
+
+- `database_url` and `db_url`
+- `retry_count` and `max_retries`
+- `enabled` and `is_enabled`
+
+Pick one, alias the other for one release, then remove.
+
+## Naming-vs-behavior mismatches
+
+Comments explaining why a name is "actually" different from its behavior:
+
+```js
+// note: getUser actually returns a UserProfile, not a User
+```
+
+The comment is telling you to rename the function.
+
+## Tests asserting historical bugs
+
+Tests whose assertions describe behavior the operator/user never wanted:
+
+```js
+it('returns null when input is empty (legacy behavior)', () => { ... })
+```
+
+Either the legacy behavior was correct (then drop the parenthetical) or it wasn't (then the test is wrong, not the candidate refactor).
+
+## Indirection without callers
+
+Abstract classes / interfaces / factories with exactly one implementation. Often introduced "in case we need to swap implementations later" — and we never did. Inline them.
+
+## Configuration-driven chaos
+
+Code shaped like:
+
+```python
+HANDLERS = {
+    "type_a": handle_a,
+    "type_b": handle_b,
+    "type_c": handle_c,  # only used by one old code path
+}
+```
+
+If `type_c` has one caller and no plans to grow, inline it and delete the registry entry.
+
+## What to do with each match
+
+For each candidate:
+
+1. **Find every caller** (workflow step 2)
+2. **Decide**: keep / delete / rename
+3. **If deleting**: confirm no telemetry references the names you're removing (workflow pre-flight)
+4. **Document** in the PR summary as one line: `deleted: <name> — <one-sentence reason>`
+
+A clean audit produces a punch list. The workflow turns that punch list into commits.

package/skills/zero-tech-debt/references/05-decision-filters.md

@@ -0,0 +1,54 @@
+# Decision Filters + Anti-Patterns
+
+When the audit has produced candidates and the workflow is in motion, choices accumulate fast. These filters resolve them. The anti-patterns at the bottom name the failure modes to refuse on sight.
+
+## Decision Filters — when choosing between implementations
+
+Prefer the option that:
+
+- **Removes more complexity** — fewer concepts to memorize
+- **Reduces future branching** — fewer `if (mode === ...)` paths
+- **Reduces special cases** — fewer "this is true except when"
+- **Improves discoverability** — a new hire finds it without being told where to look
+- **Eliminates hidden behavior** — no surprise side effects, no shared mutable state
+- **Centralizes ownership** — one module owns one concept
+- **Lowers operational ambiguity** — on-call can act on the alert without paging the author
+- **Makes intent obvious from structure** — the directory layout tells you what's where
+
+## Tiebreakers — when the filters above are equal
+
+- **Prefer the option a new hire would understand without a meeting.**
+- **Prefer the option that fails loudly over one that fails silently.** Silent fallbacks are how production gets weirder over time.
+- **Prefer the option with fewer configuration knobs.** Every config key is a future bug surface.
+- **Prefer the option that does not need a comment to justify its existence.** Comments are a code smell when they're load-bearing.
+- **Prefer the option that survives unchanged when the next adjacent feature ships.** Tight coupling to the next feature means you'll be back here in two months.
+
+## Anti-Patterns — refuse on sight
+
+These appear under different names but are the same shape: complexity preserved as an end in itself.
+
+### Architectural anti-patterns
+
+- **Preserving dead compatibility paths forever** — "we might need it" without a concrete caller is not a reason
+- **"Safe" wrappers that hide bad architecture** — moving the smell behind a facade doesn't remove it
+- **Generic frameworks for single-use problems** — the YAGNI principle, lived
+- **Feature flags that became permanent architecture** — a flag with no plan to remove it is a config knob in disguise
+- **Duplicated state ownership** — two stores believing they own the same field is a recipe for divergence
+- **Configuration-driven chaos** — when every value is in a YAML, refactoring the code doesn't help; the YAML *is* the code
+- **Indirection without operational value** — if removing the abstraction doesn't make anything worse, the abstraction wasn't doing work
+- **Abstractions created solely to avoid touching old code** — the abstraction is the debt
+
+### Process anti-patterns specific to this skill
+
+- **Treating `git blame` as architectural authority.** *Who wrote this* is not *why it should stay*. The original author may have been correcting an even worse decision that's since been undone.
+- **Refactoring tests to match the new code instead of validating intended behavior.** If the test breaks, the test might be right and the refactor wrong. Don't assume.
+- **Introducing a new abstraction in the same change that removes an old one** — split into two reviewable steps. Reviewers cannot evaluate "remove A and add B" as cleanly as "remove A" then "add B".
+- **Renaming without redirecting callers** — leaving a search-and-find trail of broken references. Every rename updates every caller in the same commit.
+- **Deleting telemetry, metrics, or alerts along with the code they instrumented** without acknowledging it. The dashboard breaks silently and on-call learns about it the hard way.
+- **Confusing "fewer lines" with "simpler."** Density is not clarity. A 200-line function can be simpler than ten 20-line ones that pass state through a chain.
+
+## When the operator pushes back on a filter
+
+The filters are heuristics, not laws. If the operator has context you don't have — a regulatory requirement, a contract with a downstream consumer, a known-bug they're tracking — the operator wins. Document the deviation in the PR summary so the next reader doesn't undo it.
+
+But: if the operator's pushback amounts to "this is how we've always done it," that's not context, that's inertia. Push back politely with the filter that resolves the choice and let them decide.

package/skills/zero-tech-debt/references/06-outcomes-and-reporting.md

@@ -0,0 +1,101 @@
+# Preferred Outcomes + Reporting Back
+
+This file describes what a successful zero-tech-debt refactor looks like, and how to summarize the result so reviewers and future readers can evaluate the *shape change* rather than re-reading the diff.
+
+## What success looks like
+
+A successful refactor produces:
+
+- **Fewer files** — collapsed wrappers, deleted dead modules
+- **Fewer modes** — `if (legacyMode)` branches removed, one path through the code
+- **Fewer flags** — feature flags that became permanent are inlined
+- **Fewer state transitions** — the state machine has fewer arrows on the diagram
+- **Fewer routing paths** — aliases removed, one URL per resource
+- **Fewer adapters** — pass-through layers flattened
+- **Fewer abstractions** — single-implementation interfaces inlined
+- **Fewer concepts developers must memorize** — fewer "you also need to know about X" caveats
+
+...while improving:
+
+- **Clarity** — a new hire reads the code and understands the intent
+- **Reliability** — fewer paths means fewer untested paths means fewer bugs
+- **Maintainability** — the next change is cheaper because there's less to navigate around
+- **Onboarding speed** — measured in "minutes to first useful PR," not "weeks to feel comfortable"
+- **Operational confidence** — on-call can act on alerts without paging the original author
+- **Implementation velocity** — features land faster because there's less scaffolding to route around
+
+If the refactor produced more of any of the first list and didn't improve any of the second list, it wasn't a zero-tech-debt refactor — it was reshuffling.
+
+## How to summarize the result
+
+The diff lists every line. The summary exists to make the architectural delta legible to reviewers and future readers. A good summary fits in five sections:
+
+### 1. Deleted
+
+Counts, not lists. The reviewer can `git log` for the names.
+
+```
+Deleted:
+- 12 files
+- 47 functions
+- 3 feature flags (NEW_USER_FLOW, ENABLE_V2_PRICING, USE_OLD_AUTH)
+- 5 route aliases (/api/v1/users → /api/users, etc.)
+- 8 config keys (consolidated into `service.retry`)
+```
+
+### 2. Unified
+
+Before/after shape, not before/after diff. One line per consolidated flow.
+
+```
+Unified:
+- 3 user-lookup paths → 1 (UserService.findById is the single entry point)
+- 2 retry implementations → 1 (utils/retry.ts; the http/retry.ts and queue/retry.ts variants are gone)
+- 4 permission checks scattered across UI components → 1 (PolicyService.canUserAccess)
+```
+
+### 3. Renamed
+
+Old name → new name, with the domain reason. The reason matters more than the names.
+
+```
+Renamed:
+- MongoOrderStore → OrderRepository
+  (we replaced Mongo with Postgres in 2024; the class name leaked the old infra)
+- processOrder → fulfillOrder
+  (function handles fulfillment, payment is now in PaymentService)
+```
+
+### 4. Intentionally Left Alone
+
+Things the audit flagged but you chose not to touch, with the reason. This prevents the next refactor from re-noticing the same items.
+
+```
+Intentionally left alone:
+- LegacyExportAdapter — still has 3 enterprise customers on the old schema; sunset is on the Q3 roadmap
+- the `mode` parameter on Search — used by the analytics pipeline, removal would require a coordinated change with that team
+```
+
+### 5. Deferred
+
+Scoped as separate follow-up tickets, not buried in this change. This is the single most important section — it's where you preserve the rot you noticed but chose not to fix.
+
+```
+Deferred (filed as separate tickets):
+- #1234 — consolidate notification dispatch (3 paths, but each has independent retry/dedup logic)
+- #1235 — remove DUAL_WRITE flag (still needed until the Postgres backfill completes Q1)
+- #1236 — rename ProductCatalog (now handles services + bundles + products)
+```
+
+## Why this format
+
+Reviewers reading a 2,000-line diff need to understand the *shape* of the change in 60 seconds. The summary is that 60-second read. If it doesn't fit on one screen, the refactor was too big — split it.
+
+Future readers (including future you) come back to figure out "why did we have X and now we have Y?" The summary is the answer. Make it good.
+
+## The thing that does NOT belong in the summary
+
+- Apologies for breaking changes ("sorry, this was unavoidable") — if it's unavoidable, just say what broke and how to migrate; no apology
+- A diff narrative ("first I deleted X, then I noticed Y, so I refactored Z") — the diff has the history; the summary has the shape
+- Marketing language ("dramatically improves," "industry-leading," "significantly cleaner") — the reviewer can evaluate; don't editorialize
+- Speculation about future benefits ("this will make adding new features easier") — sometimes true, often not; prove it with the next feature, don't promise it in the summary