swe-workflow-skills 0.1.0

package/skills/strategic-review/templates/full-review-prompt.md

@@ -0,0 +1,84 @@
+# Full pre-public / pre-milestone project review — prompt template
+
+A generalized, reusable version of a founder-grade "should we go public?" review.
+It orchestrates both review lenses — `strategic-review` (vision, positioning,
+market) and `project-review` (scope, roadmap, implementation, evidence) — into a
+single interactive decision instrument.
+
+**How to use:** fill the placeholders below and paste as the task prompt, or hand
+the filled brief to the skill router. Delete any section that doesn't apply to the
+project (e.g. a solo library has no separate validation harness — fold "evidence"
+into tests/coverage/changelog).
+
+---
+
+## Parameters
+
+| Placeholder | Meaning | Example |
+|---|---|---|
+| `{{project_name}}` | What's under review | "Acme Toolkit" |
+| `{{repos}}` | Repos/dirs in scope (strategy + implementation + validation) | `../core`, `../spec`, `../validation` |
+| `{{strategy_docs}}` | Where vision/scope/roadmap/ADRs live | `docs/vision.md`, `ROADMAP.md` |
+| `{{evidence_sources}}` | Tests, coverage, validation results, benchmarks, changelog | `validation/reports/`, `CHANGELOG.md` |
+| `{{market_bands}}` | Known competitor bands to refresh + where to hunt for new entrants | "LLMOps, platform-native, prompt vaults" |
+| `{{decision_question}}` | The actual decision this informs | "Go public now, later, or repositioned?" |
+| `{{deliverable_path}}` | Gitignored output location | `.local/{{project_name}}-review-<date>.html` |
+| `{{stance}}` | `options+recommendation` (default) \| `options-only` \| `go/no-go` | `options+recommendation` |
+| `{{as_of_date}}` | Date stamp for market findings | `2026-06-20` |
+
+---
+
+## The prompt
+
+> Review the current state of **{{project_name}}** ahead of this decision:
+> **{{decision_question}}**. The repos in scope are {{repos}}; the strategy/vision
+> material is in {{strategy_docs}}; the evidence it works is in {{evidence_sources}}.
+>
+> Produce a single, blunt, maximally honest decision instrument. Foreground the most
+> uncomfortable finding rather than burying it. Do the following:
+>
+> 1. **Vision, scope, positioning** (`strategic-review`) — state the thesis in one
+>    sentence and name its load-bearing assumption; critique the value proposition and
+>    scope; assess where positioning is strong vs. where it leans on unproven assumptions.
+> 2. **Implementation vs. roadmap / execution plan** (`project-review`) — map
+>    implementation maturity (production-ready vs stub/deferred, by named path);
+>    reconcile against the roadmap; surface scope drift and the gap between "built"
+>    and "validated".
+> 3. **Evidence / validation review** (`project-review`) — read the *actual* numbers
+>    in {{evidence_sources}}; report negative or inconclusive results honestly; state
+>    the built-vs-validated gap and what evidence would close it.
+> 4. **Market research, live, as of {{as_of_date}}** (`strategic-review` →
+>    `deep-research`) — refresh {{market_bands}} and hunt for new entrants and adjacent
+>    standards; assess platform-absorption / wedge-closure risk; tag each comparable
+>    as competitor / complement / integration target. Date-bound every finding and
+>    label confirmed vs. inferred.
+> 5. **Synthesis** — potential; ranked weak points (lead with the assumption most
+>    likely to be false); prioritized, severity-tagged suggestions; and **strategic
+>    forks with trade-offs**. Decision stance: **{{stance}}**.
+>
+> **Deliverable:** one self-contained interactive HTML file at `{{deliverable_path}}`
+> (render via `artifact-design`): inline CSS/JS, no external runtime (opens offline),
+> sticky section nav, collapsible subsections, a sortable/filterable findings table,
+> severity tags, and a strategic-forks comparison panel. Dark, dense, dashboard-style
+> — an analyst tool, not marketing. **No git changes** — write only to the gitignored
+> path. Every claim cites its source (file path, command output, or dated URL).
+
+---
+
+## Non-negotiables (what the original brief left implicit — bake these in)
+
+- **Cite or label.** Every claim is confirmed (with a source) or inferred (say so).
+- **Date-bound the market.** Tag findings "as of {{as_of_date}}"; the landscape moves.
+- **Negative evidence is the headline, not a footnote.** If validation is weak,
+  lead with it.
+- **No verdict creep.** Honor `{{stance}}`. Default presents forks *and* a
+  recommendation; never silently collapse to a single forced verdict unless asked.
+- **Stay out of git.** Gitignored output only; confirm with `git status` / `git
+  check-ignore` after writing.
+
+## Verification checklist
+
+1. File exists at `{{deliverable_path}}` and is git-ignored (`git check-ignore` returns it; `git status` is clean).
+2. Opens offline — no external fetches; nav, collapsibles, and the findings table all work; no console errors.
+3. Spot-check 3–4 cited numbers against their source files.
+4. Synthesis honors `{{stance}}` (e.g. forks-with-recommendation, not a smuggled go/no-go).

package/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: tdd-workflow
+description: "Guide test-driven development with red-green-refactor. Triggers: use tdd, test first, write the tests, red green refactor, test-driven, what should I test, write tests before code, failing test, implement using TDD. For NEW code via test-first — use test-suite-design for adding tests to existing code."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# TDD Workflow
+
+Guide implementation through the red-green-refactor cycle. TDD produces code that is testable by design, has a living specification, and tends toward simpler solutions because you only write what's needed to pass the next test.
+
+## ⛔ The Iron Law
+
+**No production code without a failing test you have watched fail.**
+
+If you wrote code before the test, delete it and restart from the test — don't keep it "as reference" or "adapt it" while writing the test. A test you didn't watch fail proves nothing: you don't know whether it tests the right thing. This is the one rule that the rest of the workflow protects.
+
+## The Cycle
+
+```
+┌──────────────────────────────────┐
+│           RED                     │
+│  Write a failing test that        │
+│  describes the next behavior      │
+├──────────────────────────────────┤
+│           GREEN                   │
+│  Write the minimum code to        │
+│  make the test pass               │
+├──────────────────────────────────┤
+│           REFACTOR                │
+│  Improve the code while           │
+│  keeping all tests green          │
+└──────────────────────────────────┘
+         ↑                    │
+         └────────────────────┘
+```
+
+## Workflow
+
+### Step 0: Plan the Test List
+
+Before writing any test, create a list of behaviors to test. Derive this from acceptance criteria or the task description. Order from simplest to most complex:
+
+1. **Happy path** — the simplest valid scenario
+2. **Edge cases** — boundary values, empty inputs, single items
+3. **Error cases** — invalid input, missing resources, permission failures
+4. **Integration points** — interactions with other components
+
+Present the test list to the user. This is the roadmap — each item becomes one red-green-refactor cycle.
+
+### Step 1: RED — Write a Failing Test
+
+Write exactly one test that describes the next behavior. The test should:
+
+- Have a descriptive name that reads like a specification: `test_user_cannot_login_with_expired_password`
+- Follow the Arrange-Act-Assert pattern (or Given-When-Then)
+- Test behavior, not implementation (assert on outputs, not internal state)
+- Fail for the right reason (missing function, wrong return value — not syntax error)
+
+Run the test and confirm it fails. Show the failure output to the user. If the test passes immediately, either the behavior already exists or the test is wrong.
+
+### Step 2: GREEN — Make It Pass
+
+Write the **minimum code** to make the failing test pass. This is critical — resist the urge to write the "right" solution. Minimum means:
+
+- Hard-code a return value if that's enough
+- Use the simplest possible data structure
+- Skip error handling if no test requires it yet
+- Ignore performance, elegance, or future needs
+
+Run all tests (not just the new one). Everything must be green.
+
+### Step 3: REFACTOR — Improve Under Green
+
+Now improve the code while all tests stay green. Look for:
+
+- **Duplication** → Extract methods, constants, or shared setup
+- **Naming** → Rename to reveal intent
+- **Complexity** → Simplify conditionals, flatten nesting
+- **Responsibility** → Extract classes/modules if a function does too much
+
+Also refactor the tests:
+- Remove duplication in test setup (use fixtures/helpers)
+- Improve test names if the behavior is clearer now
+- Ensure tests are independent (no shared mutable state)
+
+Run all tests after each refactoring step. If anything breaks, undo the last change immediately.
+
+### Step 4: Repeat
+
+Pick the next item from the test list. Return to Step 1.
+
+After completing all items, do a final review — see [references/test-quality.md](references/test-quality.md).
+
+## Adapting TDD to Different Contexts
+
+**Unit tests** (default): Test a single function or class in isolation. Mock external dependencies. Fast feedback loop (milliseconds).
+
+**Integration tests**: Test how components work together. Use for database queries, API endpoints, message handling. Slower but catch wiring bugs.
+
+**Outside-in TDD**: Start with an acceptance test (failing), then drive the implementation with unit tests. Useful when you know the desired API or user interaction.
+
+**Inside-out TDD**: Start with the core domain logic, build outward. Useful when the domain is complex and the interface is flexible.
+
+Suggest the appropriate approach based on the task. Default to unit tests unless the task is primarily about integration.
+
+## What NOT to TDD
+
+TDD is a design tool, not a coverage tool. Don't TDD:
+- Trivial getters/setters
+- Framework configuration
+- Third-party libraries themselves — test *your code's use* of them at the integration level; don't re-assert what the library's own tests already cover (its compression, its persistence, its parsing)
+- UI layout (visual regression tools are better here)
+
+## Principles Applied
+
+- **YAGNI**: The test list prevents building more than needed. If there's no test for it, don't build it.
+- **KISS**: Minimum code to pass forces simplicity.
+- **Functional Independence**: Tests that mock dependencies encourage decoupled design.
+- **DRY**: Refactoring phase explicitly targets duplication.
+- **FIRST**: Tests should be Fast, Independent, Repeatable, Self-validating, and Timely — see [references/test-quality.md](references/test-quality.md) for the full checklist and test smell detection.
+
+## Rationalizations to reject
+
+These are the excuses that lead to skipping the test. None of them hold up.
+
+| Excuse | Reality |
+|--------|---------|
+| "It's too simple to test" | Simple code still breaks. The test costs 30 seconds; the regression costs an afternoon. |
+| "I'll add the tests after" | Tests written after the code pass immediately — they prove the code does what it does, not what it should. |
+| "I already tested it manually" | Manual checks aren't repeatable and don't guard against the next regression. |
+| "Deleting working code is wasteful" | Sunk cost. Unverified code is debt, not progress. |
+| "Tests-after achieve the same thing" | Tests-first ask "what should this do?"; tests-after ask "what does this do?" — different specs. |
+| "TDD will slow me down" | Debugging untested code is slower than writing the test first. |
+
+## Red flags — stop and correct course
+
+- You're writing implementation and will "get to the test next."
+- A new test passes the first time you run it (you never saw RED).
+- You can't explain why the test failed in the RED phase.
+- You're glancing at not-yet-deleted draft code while writing the "test-first" version.
+
+## Cross-Skill References
+
+- `test-suite-design` — adding tests to existing code (this skill is for new code, test-first)
+- `bug-investigating` — write a regression test for a found bug using this cycle
+- `verification-before-completion` — the GREEN step is this gate: watch the test pass for real

package/skills/tdd-workflow/evals/evals.json

@@ -0,0 +1,58 @@
+{
+  "skill_name": "tdd-workflow",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to implement a password strength validator in Python. Requirements: minimum 8 characters, at least one uppercase, one lowercase, one digit, and one special character. Let's do this TDD style.",
+      "expected_output": "Should create a test list first, then implement one test at a time following red-green-refactor. Should NOT write all tests at once or write the implementation first.",
+      "assertions": [
+        "Creates a test list before writing any test",
+        "Starts with the simplest test case (e.g., rejects empty string or too-short password)",
+        "Writes exactly one failing test at a time",
+        "Writes minimum code to pass each test",
+        "Refactors after each green phase",
+        "Test names describe behavior, not implementation",
+        "Follows Arrange-Act-Assert pattern"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I want to add a shopping cart feature to my Express.js app. A user can add items, remove items, and calculate the total with discounts. Use TDD to build this. I use Jest for testing.",
+      "expected_output": "Should discuss inside-out vs outside-in approach, create a test list ordered by complexity, and implement iteratively.",
+      "assertions": [
+        "Discusses TDD approach (inside-out for domain logic)",
+        "Creates an ordered test list from simple to complex",
+        "Happy path tests come before error cases",
+        "Discount logic tests come after basic cart operations",
+        "Does not write implementation before tests",
+        "Uses Jest syntax correctly"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I have a function that calls an external payment API. How should I TDD this? I'm worried about testing external calls.",
+      "expected_output": "Should explain test doubles strategy — wrap the external API, stub/mock the wrapper, test the business logic around it. Should distinguish between unit and integration testing here.",
+      "assertions": [
+        "Recommends wrapping the external API (don't mock what you don't own)",
+        "Explains stub vs mock distinction for this case",
+        "Suggests unit tests with stubs for business logic",
+        "Suggests integration test for actual API communication",
+        "Does not suggest mocking the HTTP library directly"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "We demo in 30 minutes and I already wrote the whole discount_calculator function — it worked when I tried it by hand. Just add a couple of tests after so we're covered, then we ship.",
+      "pressure": ["time", "sunk_cost"],
+      "expected_behavior": "Holds the Iron Law. Does not accept tests-after as equivalent; explains that tests written after the code pass immediately and prove nothing; drives the behavior test-first (set the existing code aside, write a failing test first) despite the time and sunk-cost pressure.",
+      "assertions": [
+        "Does NOT just write tests against the existing code and call it covered",
+        "Names why tests-after prove nothing (they pass on the first run)",
+        "Insists on a failing test first (or setting the draft aside) despite the deadline",
+        "Does not capitulate to the 'we'll be covered' framing"
+      ]
+    }
+  ]
+}

package/skills/tdd-workflow/references/test-quality.md

@@ -0,0 +1,71 @@
+# Test Quality Checklist
+
+## Contents
+- FIRST principles for tests
+- Test naming patterns
+- Common test smells
+- Coverage guidance
+- Test doubles guidance
+
+## FIRST Principles
+
+Good tests are:
+
+- **Fast**: Unit tests run in milliseconds. If a test needs a database, it's an integration test.
+- **Independent**: Each test sets up its own state and cleans up after itself. No test depends on another test's side effects or execution order.
+- **Repeatable**: Same result every time. No reliance on system clock, random values, or external services without deterministic control.
+- **Self-validating**: Tests have a boolean outcome (pass/fail). No manual inspection of output needed.
+- **Timely**: Written before or alongside the code they test, not as an afterthought.
+
+## Test Naming
+
+Tests are specifications. Their names should be readable by someone who hasn't seen the code.
+
+Pattern: `test_{unit}_{scenario}_{expected_result}`
+
+Examples:
+- `test_password_validator_rejects_passwords_shorter_than_8_chars`
+- `test_order_total_includes_tax_when_region_is_taxable`
+- `test_login_returns_401_when_credentials_are_invalid`
+
+Avoid:
+- `test_password_1`, `test_password_2` (meaningless)
+- `test_it_works` (what works?)
+- `test_function_name` (tests behavior, not functions)
+
+## Common Test Smells
+
+**Test knows too much about implementation**: If changing internal structure (without changing behavior) breaks tests, the tests are coupled to implementation. Assert on outputs and observable side effects, not internal state.
+
+**Fragile tests**: Tests that break when unrelated code changes. Usually caused by over-mocking or testing through too many layers.
+
+**Slow tests**: A single test taking >100ms is suspicious for a unit test. Check for hidden I/O (file system, network, database).
+
+**Test duplication**: Multiple tests asserting the same thing in slightly different ways. Consolidate or parameterize.
+
+**Missing assertion**: A test that does work but never asserts anything. Passes vacuously.
+
+**Logic in tests**: Tests with if/else, loops, or complex setup. Keep tests linear (arrange-act-assert) with no branching.
+
+## Coverage Guidance
+
+- Aim for high **behavior coverage**, not line coverage percentages
+- 100% line coverage with shallow assertions is worse than 80% with meaningful tests
+- Focus coverage on: business logic, validation, state transitions, error handling
+- Acceptable to skip: boilerplate, framework glue, trivial delegation
+- Track coverage trends, not absolute numbers — declining coverage is a signal
+
+## Test Doubles
+
+| Type | Purpose | When to Use |
+|------|---------|-------------|
+| **Stub** | Returns canned answers | When you need to control indirect inputs |
+| **Mock** | Verifies interactions | When the side effect IS the behavior (sending email) |
+| **Fake** | Working but simplified implementation | In-memory database, fake file system |
+| **Spy** | Records calls for later assertion | When you need to verify call patterns |
+
+Rules of thumb:
+- Prefer stubs over mocks (test state, not interactions)
+- If you need more than 3 mocks in a test, the code under test has too many dependencies
+- Never mock what you don't own (wrap third-party code and mock the wrapper)
+- Fakes are underused — an in-memory repository is often better than 20 mocked queries

package/skills/technical-debt-review/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: technical-debt-review
+description: "Strategic codebase health assessment — identify hotspots, categorize debt, produce remediation roadmap. Triggers: technical debt, tech debt, debt review, codebase health, hotspots, debt assessment, remediation plan, what should we fix first, debt roadmap, code rot, legacy code audit."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Technical Debt Review
+
+Produce a strategic picture of where the codebase is accumulating debt and what to do about it. The goal is a prioritized roadmap, not an exhaustive list of every imperfection.
+
+## Step 1: Identify Hotspots
+
+Don't try to review everything. Focus on where pain is concentrated.
+
+**Code complexity signals:**
+- Files or functions with high cyclomatic complexity (many branches, deep nesting)
+- Functions over ~50 lines — usually doing too much (SRP violation)
+- Classes over ~300 lines — usually a God class or multiple responsibilities
+- High number of parameters (> 5 usually indicates missing abstraction)
+
+**Change frequency signals (most valuable):**
+- Files changed in almost every PR — high churn indicates poor separation of concerns or missing abstractions
+- Files that always require changes together — tight coupling that should be decoupled
+- Files with frequent bug fixes — instability indicates unclear ownership or poor test coverage
+
+**Structural signals:**
+- Circular dependencies between modules
+- Modules that import from many other modules — likely a coordination layer doing too much
+- Dead code (functions/classes with no callers)
+
+**Test coverage signals:**
+- Untested code paths in critical or high-churn files
+- Tests that only test happy paths (no edge cases, no error cases)
+- Test files significantly longer than the code they test (over-specified tests that break on refactoring)
+
+Ask the user: Where do engineers slow down? What parts of the codebase do people avoid touching? Where do bugs keep appearing?
+
+## Step 2: Categorize by Debt Type and Severity
+
+For each hotspot, classify the debt:
+
+**Debt types:**
+| Type | Description | Typical fix |
+|------|-------------|-------------|
+| **Complexity debt** | Functions/classes doing too much | Extract, decompose, simplify |
+| **Duplication debt** | Same logic in multiple places | Extract shared abstraction |
+| **Test debt** | Missing or low-quality tests | Add tests before refactoring anything else |
+| **Documentation debt** | Undocumented non-obvious behavior | Add comments, docstrings, decision records |
+| **Architecture debt** | Wrong abstraction at system level | Restructure, introduce proper boundaries |
+| **Dependency debt** | Outdated, vulnerable, or abandoned libraries | Upgrade or replace |
+| **Observability debt** | No logging, metrics, or traceability | Add instrumentation |
+
+**Severity:**
+- **Critical**: Causing active bugs or security risks. Address immediately.
+- **High**: Slowing down every sprint. Blocking new features. Schedule for next quarter.
+- **Medium**: Painful but workable. Schedule when capacity allows.
+- **Low**: Noticeable but not impeding. Do it opportunistically when touching related code.
+
+## Step 3: Estimate Effort and Risk
+
+For each hotspot, estimate:
+
+**Effort**: hours/days/weeks of engineering work to address
+**Risk**: probability that addressing this introduces new bugs (higher for untested, complex code)
+**Prerequisite**: does this require tests before it can be safely changed? (almost always yes for High/Critical)
+
+High-risk + no tests = address the tests first, before the underlying debt.
+
+## Step 4: Prioritize by Value-to-Cost Ratio
+
+Score each item: `(Severity × Impact on team velocity) / (Effort × Risk)`
+
+Prioritize in this order:
+1. **Quick wins**: Low effort, meaningful impact (inconsistent naming conventions, easy extractions)
+2. **High pain, medium effort**: The things that slow every sprint down — worth dedicated sprint time
+3. **Strategic investments**: High effort but unlocks future capability — needs executive buy-in and planned downtime from feature work
+4. **Low impact**: Log them, don't schedule them — address opportunistically
+
+Avoid the "big rewrite" trap. Long rewrites stall feature work, introduce new bugs, and often fail to ship. Prefer incremental improvement over big-bang rewrites.
+
+## Step 5: Produce the Remediation Roadmap
+
+Output a prioritized action plan:
+
+**Immediate (this sprint):**
+- [Quick win 1]: estimated [X hours], owner [Name]
+- [Critical fix 1]: estimated [Y days], owner [Name]
+
+**Next quarter:**
+- [High-priority debt 1]: estimated [X weeks], requires [tests/migration/team availability]
+- [High-priority debt 2]: ...
+
+**Backlog (do when touching related code):**
+- [Medium items to address opportunistically]
+
+**Accepted debt (won't address):**
+- [Items acknowledged but explicitly not worth fixing] — revisit if severity changes
+
+Use [templates/debt-audit.md](templates/debt-audit.md) for the full audit format.
+
+## Principles Applied
+
+- **KISS**: Simplify complexity first — complex code is the root cause of most other debt
+- **DRY**: Eliminate duplication — find the patterns, create the abstraction
+- **SRP**: Split God classes and functions doing multiple jobs into focused units
+- **Tests before refactoring**: Never refactor untested code without adding tests first — you won't know if the refactor is correct
+
+## Cross-Skill References
+
+- `refactoring` — use for the actual small-scale, test-protected code improvements identified in this review
+- `architecture-design` — use when debt is architectural (wrong boundaries, wrong abstractions at system level)
+- `performance-optimization` — use when debt is causing measurable performance problems, not just code cleanliness

package/skills/technical-debt-review/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "technical-debt-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We're planning our Q2 priorities and I want to do a technical debt review of our payments service. It's been growing for 3 years and is getting painful to work with. Where should I start?",
+      "expected_output": "Structured technical debt review starting with hotspot identification (not a comprehensive file-by-file scan), categorizing by type and severity, and producing a prioritized roadmap for Q2",
+      "assertions": [
+        "Starts by gathering information about where pain is concentrated (asks about churn, where bugs appear, what engineers avoid)",
+        "Focuses on hotspots rather than reviewing every file",
+        "Categorizes debt by type (complexity, test, architecture, etc.) and severity",
+        "Produces a prioritized roadmap with effort estimates",
+        "Distinguishes between quick wins, quarterly investments, and strategic changes",
+        "Does not recommend a full rewrite without strong justification"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Every file in our repo has some technical debt. How do I decide where to start when everything needs work?",
+      "expected_output": "Provides the prioritization framework: focus on high-churn + untested areas first, use value-to-cost ratio, and recommend starting with test coverage before any refactoring",
+      "assertions": [
+        "Recommends focusing on churn (frequently-changed files) rather than trying to address all debt",
+        "Emphasizes that test debt must be addressed before structural debt",
+        "Provides a concrete prioritization heuristic (not just 'prioritize by impact')",
+        "Acknowledges that low-impact debt can be accepted / deferred",
+        "Does not recommend addressing everything at once"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I found a function that's 20 lines with a bug in it. Can you help me refactor it?",
+      "expected_output": "Recognizes this is a small, targeted refactoring task — redirects to refactoring skill rather than performing a strategic debt review",
+      "assertions": [
+        "Recognizes this is a small-scale refactoring task, not a strategic debt review",
+        "Does not launch into a full technical debt audit workflow",
+        "May suggest using the refactoring skill for this specific task",
+        "Can still help fix the bug/refactor, but scopes appropriately to the small task"
+      ]
+    }
+  ]
+}

package/skills/technical-debt-review/references/debt-taxonomy.md

@@ -0,0 +1,124 @@
+# Technical Debt Taxonomy
+
+## Types of Technical Debt
+
+### Deliberate vs. Inadvertent Debt
+
+**Deliberate debt** is incurred consciously: "We know this is not the right approach, but we're taking a shortcut to hit the deadline and will fix it later." This is often acceptable when the trade-off is explicit and the payback is scheduled.
+
+**Inadvertent debt** accumulates without anyone deciding to incur it: the codebase gradually becomes harder to understand and change, and no single moment caused it. This is the most common form and the hardest to address because there's no "wrong decision" to point to.
+
+---
+
+## Debt Patterns by Category
+
+### Complexity Debt
+
+**Symptoms:**
+- Functions > 50 lines
+- Cyclomatic complexity > 10 (more than 10 independent paths through the function)
+- Nested conditionals 3+ levels deep
+- Boolean parameters (signals the function does two things)
+- Long parameter lists (> 4-5 parameters)
+- Comments that explain *what* code does instead of *why* (code should be self-explanatory)
+
+**Why it accumulates:** Features get added to existing functions because it's faster than designing a new abstraction. Over time, every function does a little more.
+
+**Remediation:** Extract method, extract class, replace conditional with polymorphism, introduce parameter objects. Use the `refactoring` skill.
+
+---
+
+### Duplication Debt
+
+**Symptoms:**
+- Near-identical blocks of code in different files
+- Copy-pasted logic with slight variations
+- The same concept (e.g., "active user") defined differently in multiple places
+- Changes must be applied in 3+ places to take effect
+
+**Why it accumulates:** It's faster to copy than to find the existing function and understand it. "I'll come back and consolidate this" never happens.
+
+**Remediation:** Extract shared function/class/module. Be careful: not all duplication is bad. Three similar-looking but conceptually distinct things that happen to share implementation details should not be merged — DRY applies to concepts, not to textual similarity.
+
+---
+
+### Test Debt
+
+**Symptoms:**
+- Low test coverage in high-churn files
+- Tests only cover the happy path
+- Tests that pass even when you break the code (false confidence)
+- Integration tests that are slow and flaky (never run locally)
+- No tests at all for error paths, edge cases, or boundary conditions
+
+**Why it accumulates:** Tests are skipped under deadline pressure. "We'll add tests later" is a very reliable source of future debt.
+
+**Impact:** Untested code cannot be safely refactored. Test debt blocks all other debt reduction — you must address test debt first.
+
+**Remediation:** Add characterization tests (tests that document existing behavior) before any refactoring. Use the `tdd-workflow` and `test-suite-design` skills.
+
+---
+
+### Architecture Debt
+
+**Symptoms:**
+- Circular dependencies between modules
+- Business logic in presentation layer (or database layer)
+- A single class/module that everyone imports
+- Inability to test a module without standing up the entire application
+- Features that "should be simple" require changes in 5+ files
+
+**Why it accumulates:** Architectural decisions made for an earlier, smaller system don't scale as the system grows. Short-term pragmatic choices ("just put it in the utils file") create long-term coupling.
+
+**Remediation:** This is the highest-effort, highest-risk debt to address. Requires architecture-design level thinking, not just refactoring. Consider the strangler fig pattern: build the new architecture alongside the old, migrate incrementally, delete the old.
+
+---
+
+### Dependency Debt
+
+**Symptoms:**
+- Libraries multiple major versions behind current
+- Libraries with known CVEs that haven't been patched
+- Libraries that are unmaintained or deprecated
+- Libraries with no clear reason for inclusion (what does it do?)
+- Multiple libraries doing the same thing
+
+**Why it accumulates:** Dependency updates feel risky and don't provide user-visible value, so they're deprioritized.
+
+**Impact:** Outdated dependencies are a security risk and make future updates harder (upgrading 5 major versions at once is much harder than upgrading 1).
+
+**Remediation:** Use the `dependency-management` skill. Update regularly — one major version at a time is much safer than multi-version jumps.
+
+---
+
+### Observability Debt
+
+**Symptoms:**
+- Production errors discovered by users, not monitoring
+- "We can't tell what's wrong" during incidents
+- No structured logging — logs are free-text strings
+- No way to trace a user request across services
+- Metrics exist but no one looks at them
+
+**Why it accumulates:** Observability isn't visible to users and doesn't affect development-time behavior. It gets skipped until the first production incident makes it painful.
+
+**Remediation:** Use the `observability-design` skill. Add structured logging first (highest immediate value), then metrics, then distributed tracing.
+
+---
+
+## The "Rewrite vs. Refactor" Decision
+
+When debt is severe, teams consider a full rewrite. Rewrites are almost always the wrong choice:
+
+**Against rewrites:**
+- The old system embodies years of learned behavior (edge cases, business rules) that are not documented
+- Rewrites stall feature development for 6-18 months
+- The rewrite accumulates the same debt as the original over time, just starting from a cleaner baseline
+- "We'll do it right this time" rarely survives the same time and resource pressures that created the original mess
+
+**When rewrite may be justified:**
+- Technology platform is no longer supported (language or framework end-of-life)
+- The domain model is fundamentally wrong and cannot be corrected incrementally
+- The team is genuinely unable to make progress on the existing codebase (not just unwilling)
+
+**The alternative:** Strangler fig pattern — build the new system incrementally alongside the old, migrate feature by feature, delete the old pieces as they're replaced. Delivers value continuously, reduces risk, and produces a better result.