@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/skills/distilled/distilled-systematic-debugging.md

@@ -0,0 +1,154 @@
+---
+name: distilled-systematic-debugging
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: systematic-debugging (score 4.5/5)'
+spawn_agent: harness-debug-full
+keywords:
+  - systematic
+  - debugging
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/obra/superpowers.git
+    license: MIT
+    commit: f2cbfbefebbfef77321e4c9abc9e949826bea9d7
+    paths:
+      - systematic-debugging/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - agent-introspection-debugging/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - agent-introspection-debugging/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - agent-introspection-debugging/SKILL.md
+distilled_at: '2026-06-15T00:55:01.895Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 4.5
+it_universal_dims:
+  d1: 1
+  d2: 0.5
+  d3: 1
+  d4: 1
+  d5: 1
+it_universal_rationale: >-
+  Four-phase root-cause methodology (investigate → pattern → hypothesis → implement) with a
+  3+-failures-means-architectural-problem heuristic; language- and toolchain-neutral; directly
+  portable to any debugging session in any codebase.
+---
+
+# Systematic Debugging
+
+## When to use
+- Any test failure, bug report, or unexpected behaviour — before proposing fixes
+- Performance problems, build failures, integration breakage
+- **Especially** when under time pressure, when an "obvious" fix hasn't worked, or when you've already tried multiple fixes
+- **Do not skip** for "simple" bugs — simple bugs have root causes too; the process is fast for them
+
+## Core idea
+
+Random fixes waste time and create new bugs; symptom-level patches mask underlying issues.
+The core principle is: always find the root cause before attempting any fix.
+The methodology gates progress through four sequential phases — Root Cause → Pattern Analysis → Hypothesis Testing → Implementation — so each phase must be complete before the next begins.
+The payoff is measurable: systematic debugging takes 15–30 minutes versus 2–3 hours of guess-and-check thrashing, with a first-time fix rate near 95 % versus ≈ 40 %.
+The single most important escalation heuristic: **if three or more distinct fixes have failed, stop fixing symptoms and question the architecture.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If Phase 1 is incomplete, no fix may be proposed.
+
+## Steps
+
+### Phase 1 — Root Cause Investigation
+
+1. **Read error messages completely.** Do not skim warnings; read stack traces to the bottom; note exact line numbers, file paths, and error codes. They often contain the solution.
+
+2. **Reproduce consistently.** Establish exact reproduction steps. If the issue is not reliably reproducible, gather more data — do not guess.
+
+3. **Check recent changes.** Review git diff, recent commits, new dependencies, config changes, and environment differences. Something changed; find it.
+
+4. **Instrument boundaries in multi-component systems.**  
+   For any system with multiple layers (e.g., API → service → database; build → sign → deploy):
+   - At each component boundary, log what data *enters* and what *exits*
+   - Verify config/environment propagation at every layer
+   - **Run once to collect evidence** showing *where* it breaks
+   - Analyse that evidence to identify the failing component
+   - Only then investigate that specific component in depth
+
+5. **Trace data flow for deep call-stack errors.**  
+   Start at the failing point and trace backwards: what called this with the bad value? Keep tracing up the call chain until you find the origination point. Fix at the source, not at the symptom.
+
+### Phase 2 — Pattern Analysis
+
+1. Find working examples of similar behaviour in the same codebase.
+2. Read the reference implementation **completely** — never skim.
+3. List every difference between working and broken, no matter how small.
+4. Understand all dependencies: required config, environment assumptions, shared state.
+
+### Phase 3 — Hypothesis and Testing
+
+1. **Form one specific hypothesis:** *"I think X is the root cause because Y."* Write it down.
+2. Make the **smallest possible change** to test it — one variable at a time.
+3. Did it work? → proceed to Phase 4. Did not work? → form a **new** hypothesis; do **not** stack additional fixes on top.
+4. When you don't know, say so. Research or ask; do not pretend.
+
+### Phase 4 — Implementation
+
+1. **Create a failing test case first** — the simplest possible automated reproduction. The test must fail before the fix.
+2. **Implement exactly one fix** that addresses the confirmed root cause. No "while I'm here" changes; no bundled refactoring.
+3. **Verify:** test now passes, no regressions introduced, issue is actually resolved.
+4. **If the fix doesn't work:** stop, return to Phase 1 with the new information gathered. Never attempt a fourth fix without re-investigating from scratch.
+5. **If 3 or more fixes have failed — question the architecture.**  
+   Signals of an architectural problem (not a symptom problem):
+   - Each fix reveals a new failure in a different place
+   - Fixes require "massive refactoring" to implement cleanly
+   - Fixing one symptom creates new symptoms elsewhere  
+   
+   At this point: stop, document the pattern, and discuss whether the underlying design needs to change before any more fixes are attempted.
+
+## Anti-patterns
+
+Stop and return to Phase 1 whenever you catch yourself thinking:
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "I'll add multiple changes at once and run tests"
+- "It's probably X, let me fix that" — assumption without evidence
+- "I don't fully understand, but this might work"
+- "Pattern says X but I'll adapt it differently" — without reading it completely
+- Proposing a solution before tracing the data flow
+- "One more fix attempt" when two have already failed
+
+### Common rationalisations
+
+| Excuse | Reality |
+|---|---|
+| "Issue is simple, don't need process" | Simple issues have root causes. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is faster than thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write the test after the fix works" | Untested fixes don't stick. A failing test first proves the fix. |
+| "Multiple fixes at once saves time" | Can't isolate what worked; introduces new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question the design. |
+
+## Quick reference
+
+| Phase | Key activities | Gate to move forward |
+|---|---|---|
+| 1 — Root Cause | Read errors; reproduce; check changes; instrument boundaries | Understand WHAT failed and WHY |
+| 2 — Pattern | Find working examples; read reference completely; list differences | Root difference identified |
+| 3 — Hypothesis | State single specific theory; test minimally | Confirmed or replaced with new hypothesis |
+| 4 — Implementation | Failing test first; one fix; verify; escalate at 3 failures | Bug resolved, tests pass, no regressions |
+
+## References
+- Upstream: https://github.com/obra/superpowers.git

package/dist/skills/distilled/distilled-test-driven-development.md

@@ -0,0 +1,432 @@
+---
+name: distilled-test-driven-development
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: test-driven-development (score 3.5/5)'
+keywords:
+  - test
+  - driven
+  - development
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/obra/superpowers.git
+    license: MIT
+    commit: f2cbfbefebbfef77321e4c9abc9e949826bea9d7
+    paths:
+      - test-driven-development/SKILL.md
+  - upstream: https://github.com/anthropics/skills.git
+    license: Apache-2.0
+    commit: 690f15cac7f7b4c055c5ab109c79ed9259934081
+    paths:
+      - webapp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - ai-regression-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - cpp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - csharp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - django-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - e2e-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - fsharp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - golang-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - kotlin-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - laravel-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - perl-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - python-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - quarkus-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - rust-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - springboot-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - swift-protocol-di-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - tdd-workflow/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - golang-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - tdd-workflow/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - e2e-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - golang-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - kotlin-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - laravel-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - python-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - quarkus-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - rust-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - springboot-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - tdd-workflow/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - ai-regression-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - cpp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - csharp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - django-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - e2e-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - golang-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - kotlin-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - laravel-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - perl-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - python-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - rust-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - springboot-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - swift-protocol-di-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - tdd-workflow/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - golang-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - tdd-workflow/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - ai-regression-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - cpp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - csharp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - django-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - e2e-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - fsharp-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - golang-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - kotlin-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - laravel-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - perl-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - python-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - quarkus-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - rust-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - springboot-tdd/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - swift-protocol-di-testing/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - tdd-workflow/SKILL.md
+distilled_at: '2026-06-15T00:56:21.265Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 3.5
+it_universal_dims:
+  d1: 0.5
+  d2: 0.5
+  d3: 0.5
+  d4: 1
+  d5: 1
+it_universal_rationale: >-
+  Red-Green-Refactor cycle, Iron Law, and anti-pattern taxonomy are fully language- and
+  tool-agnostic; only illustrative code samples and test-runner invocations are
+  TypeScript/npm-specific and trivially substitutable in any codebase.
+---
+
+# Test-Driven Development (TDD)
+
+## When to use
+- Implementing any new feature or behavior
+- Fixing a bug (write a failing test that reproduces it *before* touching production code)
+- Refactoring existing code (existing tests must stay green throughout)
+- Any behavior change where correctness needs to be verifiable and regression-safe
+
+**Exceptions (require explicit partner approval):** throwaway prototypes, generated/scaffolded code, configuration-only files.
+
+## Core idea
+Write the test first, watch it fail, then write the minimal production code to make it pass — no more, no less. If you never saw the test fail, you cannot know it tests the right thing. Tests written *after* passing code answer "what does this do?"; tests written *before* answer "what *should* this do?" and force edge-case discovery before implementation biases your thinking. The **Red → Green → Refactor** loop is the atomic unit of work: one failing test → minimal code to pass → clean up → repeat. Writing code first "just to explore" is test-after in disguise; the remedy is to delete the pre-written code and start over with a test.
+
+## Steps
+
+### 1. RED — Write One Failing Test
+Describe the exact behavior you want in a single test:
+- **One behavior per test** — if "and" appears in the name, split it into two tests
+- **Descriptive name** — the test name should state the expected outcome, not the mechanism
+- **Prefer real code over mocks** — use test doubles only when external I/O is unavoidable
+
+### 2. Verify RED — Watch It Fail *(mandatory, never skip)*
+Run this test in isolation with your project's test runner. Confirm:
+- The test **fails** (not errors on syntax/import)
+- The failure message matches what you expect ("feature missing", not "undefined is not a function")
+- It fails because the feature is absent, not due to a typo in the test itself
+
+If the test **passes immediately** → you are testing already-existing behavior; fix or delete the test.  
+If the test **errors** → fix the error and re-run until it fails cleanly for the right reason.
+
+### 3. GREEN — Write Minimal Code to Pass
+Write the simplest production code that makes the failing test pass:
+- Do not add untested features (YAGNI)
+- Do not refactor other code in the same commit
+- Do not "improve" anything beyond what the single test requires
+
+### 4. Verify GREEN — Watch It Pass *(mandatory)*
+Run your full test suite. Confirm:
+- The new test passes
+- All pre-existing tests still pass
+- Output is clean (no new warnings or errors introduced)
+
+If other tests break → fix them **now**, before proceeding.
+
+### 5. REFACTOR — Clean Up (tests still green)
+With all tests passing, improve the code's internal quality:
+- Remove duplication
+- Improve naming and readability
+- Extract helpers or shared abstractions
+
+Never add new behavior in this phase. Re-run the full suite after every refactor step.
+
+### 6. Repeat
+Write the next failing test for the next unit of behavior and cycle again.
+
+## Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Wrote code before a test? **Delete it. Start fresh.** No "keep as reference", no "adapting" it while writing the test — that is still test-after. Delete means delete.
+
+## Anti-patterns
+
+| Rationalization | Reality |
+|---|---|
+| "Too simple to test" | Simple code breaks too. A focused test takes under a minute. |
+| "I'll add tests after" | Tests that pass immediately on first run prove nothing was verified. |
+| "Already manually tested all edge cases" | Ad-hoc testing has no record and cannot be re-run; automated tests are systematic. |
+| "Deleting X hours of work is wasteful" | Sunk-cost fallacy. Unverified production code is technical debt compounding interest. |
+| "I'll keep it as reference and write tests first" | You will adapt it. That is test-after. Delete it. |
+| "TDD is dogmatic; I'm being pragmatic" | Catching bugs before commit is faster than debugging in production. Test-first *is* pragmatic. |
+| "Tests-after achieve the same goals" | They answer different questions — see Core idea. |
+| "This case is different because…" | It isn't. All of these mean: delete the code, start over. |
+
+**Red flags — stop and restart the TDD cycle from scratch:**
+- You wrote production code before any test
+- The test passed immediately without any implementation
+- You cannot articulate why the test failed
+- You find yourself composing a "just this once" justification
+
+## Verification Checklist (before marking any work complete)
+- [ ] Every new function/method has a test written before its implementation
+- [ ] Each test was observed to fail for the expected reason
+- [ ] Only minimal code was written to pass each test
+- [ ] All tests pass with a clean runner output (no new warnings)
+- [ ] Edge cases and error paths are covered by dedicated tests
+- [ ] Mocks/stubs are used only where real I/O is genuinely unavoidable
+
+## When Stuck
+
+| Problem | Solution |
+|---|---|
+| Don't know how to write the test | Write the API you *wish* existed; start with the assertion, work backwards |
+| Test is overly complicated | Your design is too complicated — simplify the interface first |
+| Must mock everything to test anything | Code is too coupled; introduce dependency injection |
+| Test setup is enormous | Extract shared helpers; if still complex, the design needs simplification |
+| Bug found in existing untested code | Write a failing test reproducing the bug, then follow the TDD cycle to fix it |
+
+## References
+- Upstream: https://github.com/obra/superpowers.git