@skill-graph/cli 0.5.6

package/marketplace/skills/test-coverage-strategy/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: test-coverage-strategy
+description: "Use when reasoning about code coverage as a strategic measurement rather than a target: the coverage-criterion hierarchy (function, statement, line, branch, decision, condition, MC/DC, path), Marick's distinction between coverage as a floor signal and coverage as a ceiling target, Goodhart's Law applied to coverage metrics, why 100% line coverage may catch nothing important while 80% well-chosen coverage catches almost everything, the safety-critical industry's MC/DC requirement (DO-178C aviation, ISO 26262 automotive) as the empirical evidence that coverage at the right granularity matters, the difference between covered (lines exercised) and tested (behaviors verified), and how coverage gaps are diagnostic signals about the test suite. Do NOT use for choosing test levels (use testing-strategy), the technique of mutation testing as a stronger signal (use mutation-testing), the construction of test doubles (use test-doubles-design), or specific coverage-tooling configuration (tool docs)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/testing\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"code coverage\\\\\\\",\\\\\\\"line coverage\\\\\\\",\\\\\\\"branch coverage\\\\\\\",\\\\\\\"decision coverage\\\\\\\",\\\\\\\"condition coverage\\\\\\\",\\\\\\\"MC/DC\\\\\\\",\\\\\\\"modified condition decision coverage\\\\\\\",\\\\\\\"path coverage\\\\\\\",\\\\\\\"coverage as target\\\\\\\",\\\\\\\"Goodhart on coverage\\\\\\\",\\\\\\\"covered vs tested\\\\\\\",\\\\\\\"DO-178C\\\\\\\"]\",\"triggers\":\"[\\\\\\\"what coverage target should we set\\\\\\\",\\\\\\\"is 100% coverage the goal\\\\\\\",\\\\\\\"is this line covered or tested\\\\\\\",\\\\\\\"should we add tests for these uncovered lines\\\\\\\",\\\\\\\"branch vs line coverage\\\\\\\"]\",\"examples\":\"[\\\\\\\"set a coverage policy for a service that distinguishes 'covered' from 'tested'\\\\\\\",\\\\\\\"explain why a 100% line coverage gate may be worse than an 80% branch coverage gate\\\\\\\",\\\\\\\"diagnose a high-coverage test suite that still misses bugs — likely a granularity mismatch\\\\\\\",\\\\\\\"decide when to upgrade from branch coverage to MC/DC for safety-critical code\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"choose test levels (unit/integration/e2e) for a project (use testing-strategy)\\\\\\\",\\\\\\\"use mutation testing to evaluate test-suite quality (use mutation-testing)\\\\\\\",\\\\\\\"configure Istanbul, Jest coverage, or JaCoCo (tool documentation)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"mutation-testing\\\\\\\",\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"eval-driven-development\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the question of what to test at which level; this skill owns the measurement of how much of the code those tests actually exercise and at what granularity.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"mutation-testing\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"mutation-testing owns the stronger signal of whether tests would *catch* a defect; this skill owns the structural signal of whether tests *reach* the code at all. Coverage is a necessary-not-sufficient precondition for mutation tests to even apply.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"TDD produces high coverage as a side effect; this skill explains why that coverage is a side effect rather than a target, and why pursuing the metric directly produces worse tests.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"mutation-testing\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Test coverage is to a test suite what cell-phone coverage maps are to a network — a green map on the carrier's website is not the same as actually being able to make a call in your basement; the map measures *where there is theoretical signal*, not *whether the call gets through*. A 100% coverage map with a 30% call-completion rate is the same shape of problem as a 100%-line-coverage suite that misses bugs — the floor is met (no dead zones), but the ceiling is unverified.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Test coverage is the family of structural measurements that report which parts of the production code were exercised by the test suite. Coverage criteria differ in granularity — function, statement, line, branch, decision, condition, modified-condition/decision (MC/DC), path — and each higher criterion subsumes the lower ones. Coverage is a *structural* property: it answers 'did the test reach this code,' not 'did the test verify this behavior.' The strategic discipline of test coverage is using coverage as a diagnostic signal about gaps in the test suite while resisting the Goodhart-Law failure mode of treating the coverage number as the target. Coverage is a floor (below this level, the test suite definitely misses things) not a ceiling (above this level, the test suite is necessarily good).\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/test-coverage-strategy/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/test-coverage-strategy/SKILL.md
+---
+
+# Test-Coverage Strategy
+
+## Coverage
+
+The strategic use of code-coverage measurement as a diagnostic signal about test-suite gaps, without falling into the Goodhart-Law trap of treating the coverage number as the target. Covers the coverage-criterion hierarchy (function → line → branch → decision → condition → MC/DC → path), Marick's distinction between coverage as floor (uncovered code is definitely untested) and coverage as ceiling (covered code is necessarily tested — false), the covered-vs-tested distinction, the safety-critical industry's MC/DC standard (DO-178C aviation, ISO 26262 automotive) as empirical evidence for granularity-matching, and the strategic uses of coverage (diagnostic, floor-gating, diff-based gating, audit artifact).
+
+## Philosophy
+
+Coverage measures execution, not verification. A test that calls every function but asserts nothing has 100% line coverage and zero testing value; a test with rich assertions but missing some branches has lower coverage and may have much higher testing value. The metric's strategic value is in the *floor direction*: uncovered code is definitely untested. The reverse direction — covered code is necessarily tested — is not reliable.
+
+The discipline of coverage strategy is using the metric where it is informative (gap detection, regression signaling, test-effort allocation, audit compliance) and refusing to use it where it is misleading (as a quality target, as a substitute for behavioral verification, as a ceiling claim about test thoroughness). The risk is large because coverage numbers are easy to produce, easy to gate on, and easy to optimize for in ways that degrade the test suite.
+
+Most working test suites should aim for coverage that is *high enough to reveal gaps without becoming the goal*. Where the certification environment mandates a specific criterion (MC/DC for safety-critical), the discipline shifts: the criterion is given; the work is meeting it without coverage-padding.
+
+## The Criterion Hierarchy
+
+| Criterion | What it requires | Test count for `A && B && C` | Typical use |
+|---|---|---|---|
+| Function | Each function called once | 1 | Detects entirely-untested functions |
+| Statement / Line | Each line executed once | 1 | Default in most tools |
+| Branch | Each branch (true/false) taken once | 2 | Catches missed-else-branch bugs |
+| Decision | Each decision evaluated both ways | 2 | Often conflated with branch in tooling |
+| Condition | Each Boolean sub-expression both true and false | 2 | Catches short-circuit-evaluation bugs |
+| MC/DC | Each condition independently affects the decision | 4 (N+1 for N conditions) | DO-178C Level A; ISO 26262 ASIL-D |
+| Multiple condition | All combinations of conditions exercised | 8 (2^N) | Combinatorial; rarely required |
+| Path | Every execution path through the function | Infeasible for loops | Theoretical |
+
+The right criterion depends on where the code's failure modes hide. Straight-line procedural code: line coverage. Complex Boolean conditions (access control, rate limiters, financial logic): branch or condition coverage. Safety-critical: MC/DC by mandate.
+
+## Covered vs Tested
+
+| Aspect | Covered | Tested |
+|---|---|---|
+| What it measures | Test reached the code | Test verified the code's behavior |
+| Detected by | Coverage tool | Assertion presence + correctness |
+| 100% achievable cheaply by | Function/line traversal with no assertions | Real behavioral assertions |
+| Signal direction | Floor (uncovered = untested) reliable | Ceiling (covered = tested) unreliable |
+| Strategic value | Gap detection | Quality assurance |
+
+A test that calls `processOrder()` but asserts nothing covers `processOrder` and tests nothing in it. The coverage report cannot distinguish this from a test with full behavioral assertions. The discipline is to read coverage as one part of a picture that includes assertion review, mutation testing (see `mutation-testing`), and integration test coverage.
+
+## When To Use Each Criterion
+
+| Code character | Recommended criterion | Why |
+|---|---|---|
+| Straight-line procedural; few branches | Line | Adequate; cheap |
+| Branchy business logic | Branch | Catches missed-else cases line misses |
+| Compound Boolean conditions (access checks, rate limiting, financial gates) | Condition or MC/DC | Catches short-circuit-evaluation bugs |
+| Safety-critical (aviation, automotive, medical) | MC/DC | Mandated by DO-178C, ISO 26262 |
+| Algorithmic / mathematical | Branch + mutation testing | Coverage + behavioral signal |
+| Pure utility / value objects | Line | Most failure modes line coverage catches |
+| Error / exception paths | Branch (or accept the gap) | Branch reveals untested error handling |
+
+## Goodhart-Resistant Strategy
+
+Patterns that use coverage strategically without producing Goodhart-pressure:
+
+1. **Diagnostic, not gating.** Report coverage on PRs; don't fail builds on coverage. Reviewers read the report; the team adjusts allocation.
+2. **Diff-based gating at low threshold.** New/changed lines must be covered above (e.g.) 70%, not the codebase as a whole. Lower aggregate target, higher meaningfulness of each test.
+3. **Coverage as part of a panel.** Pair coverage with mutation score, assertion density, and integration test breadth. No single metric is the target.
+4. **Per-module differentiation.** Higher coverage required for high-impact modules (financial calculation, security, data-loss-risk); lower for stable utility code.
+5. **Annual review of gaps.** Walk the uncovered code; decide consciously whether the gap is acceptable (defensive code, logging) or a real test debt.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] The team's coverage criterion is appropriate to the code's failure modes (line for procedural, branch for branchy, MC/DC for safety-critical). The default criterion is not assumed correct without checking what it measures.
+- [ ] Coverage is read as a floor signal (gaps point to untested code), not a ceiling signal (high coverage proves tests are good). The team distinguishes "covered" from "tested" in conversation and in policy.
+- [ ] Coverage gates, if used, are set at a level achievable by real behavioral testing — not a level that forces coverage-padding tests.
+- [ ] Coverage of dead code is excluded or noted. A dropping coverage percentage is interpreted (could be dead-code removal, test deletion, or new untested code), not treated as automatically bad.
+- [ ] Coverage is paired with at least one behavioral measurement (mutation testing, assertion review, integration-test breadth) in any quality conversation about the test suite.
+- [ ] For safety-critical code, the certification standard's coverage criterion is the criterion in use, and the tool's reported number actually matches the standard's definition.
+- [ ] Production observability is treated as a separate verification dimension from coverage. Coverage tells you what tests exercised; observability tells you what production exercises.
+- [ ] The team can explain a coverage gap on any specific module as either "we don't need to test this because [reason]" or "we should test this and have not." Unexplained gaps are test debt.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Deciding which test levels (unit/integration/e2e) to invest in | `testing-strategy` | testing-strategy owns the level/scope question; this skill owns the measurement of structural reach |
+| Measuring whether tests would catch deliberately-introduced defects | `mutation-testing` | mutation owns the behavioral signal; this skill owns the structural signal |
+| Constructing test doubles (mocks, stubs, fakes) | `test-doubles-design` | test-doubles-design owns the stand-in design |
+| Iterating on LLM behavior via an eval suite | `eval-driven-development` | eval-driven-development is the LLM-system analog; this skill is about deterministic-software coverage |
+| Configuring Istanbul, Jest coverage, JaCoCo, Coverlet | tool documentation | tool API choice is tactical detail below this skill's scope |
+
+## Key Sources
+
+- Marick, B. (1999). ["How to Misuse Code Coverage"](http://www.exampler.com/testing-com/writings/coverage.pdf). The canonical practitioner essay on coverage as a strategic signal vs target; defines the floor/ceiling distinction.
+- Cornett, S. ["Code Coverage Analysis"](http://www.bullseye.com/coverage.html). Long-form reference defining the coverage criterion hierarchy and the practical differences between branch, decision, and MC/DC coverage.
+- RTCA. *DO-178C: Software Considerations in Airborne Systems and Equipment Certification* (2011). The aviation certification standard mandating MC/DC for Level A software. Industry benchmark for what coverage criterion safety-critical software requires.
+- ISO. *ISO 26262: Road vehicles — Functional safety* (2018). The automotive safety standard mandating MC/DC for ASIL-D software. Parallel industry benchmark.
+- Hayhurst, K. J., Veerhusen, D. S., Chilenski, J. J., & Rierson, L. K. (2001). ["A Practical Tutorial on Modified Condition/Decision Coverage"](https://ntrs.nasa.gov/citations/20010057789). NASA technical memorandum; the practical reference on MC/DC.
+- Goodhart, C. (1975). "Problems of Monetary Management: The U.K. Experience." The origin of Goodhart's Law as commonly cited; applies sharply to coverage-as-target.
+- Inozemtseva, L., & Holmes, R. (2014). ["Coverage Is Not Strongly Correlated with Test Suite Effectiveness"](https://dl.acm.org/doi/10.1145/2568225.2568271). *ICSE 2014*. Empirical study showing coverage and test-suite effectiveness are weakly correlated; supports the floor-not-ceiling reading.
+- Namin, A. S., & Andrews, J. H. (2009). ["The influence of size and coverage on test suite effectiveness"](https://dl.acm.org/doi/10.1145/1572272.1572284). *ISSTA 2009*. Earlier empirical study with similar findings on coverage's limited correlation with bug-finding effectiveness.

package/marketplace/skills/test-doubles-design/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: test-doubles-design
+description: "Use when designing or reviewing test doubles — the stand-in objects that replace real collaborators in a test: the five-kind taxonomy (dummy, stub, spy, fake, mock) from Meszaros's xUnit Test Patterns, the difference between state verification (Detroit-school, classicist) and interaction verification (London-school, mockist) and how it determines which doubles fit, the cost of doubles (fragility, false confidence, divergence from real behavior), the role of fakes as the under-used middle ground, the verify_with relationship to test-driven-development, and the heuristics for when to use a real collaborator instead of any double. Do NOT use for choosing test levels or what to test (use testing-strategy), the design discipline of writing tests first (use test-driven-development), specific mocking-library API choice (library docs), or general production stubs and feature flags (use feature-gating or domain-specific skills)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/testing\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"test double\\\\\\\",\\\\\\\"mock\\\\\\\",\\\\\\\"stub\\\\\\\",\\\\\\\"spy\\\\\\\",\\\\\\\"fake\\\\\\\",\\\\\\\"dummy\\\\\\\",\\\\\\\"test isolation\\\\\\\",\\\\\\\"interaction verification\\\\\\\",\\\\\\\"state verification\\\\\\\",\\\\\\\"mockist\\\\\\\",\\\\\\\"classicist\\\\\\\",\\\\\\\"in-memory fake\\\\\\\",\\\\\\\"sociable test\\\\\\\",\\\\\\\"solitary test\\\\\\\",\\\\\\\"mocking external API calls\\\\\\\",\\\\\\\"testing code that calls an API\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should this be a mock or a stub\\\\\\\",\\\\\\\"are we using mocks correctly\\\\\\\",\\\\\\\"the test is brittle when I refactor\\\\\\\",\\\\\\\"do we need a fake here\\\\\\\",\\\\\\\"is this test really testing anything\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide between a mock, a stub, and a fake for a database collaborator in a test\\\\\\\",\\\\\\\"explain why over-mocking produces fragile tests that change with every refactor\\\\\\\",\\\\\\\"diagnose a passing test that mirrors the implementation rather than specifying behavior\\\\\\\",\\\\\\\"design an in-memory fake for a repository interface that supports both classicist tests and integration tests\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"decide which test levels (unit/integration/e2e) the project should invest in (use testing-strategy)\\\\\\\",\\\\\\\"set up a production feature flag (use feature-gating)\\\\\\\",\\\\\\\"configure a specific mocking library — Jest, Sinon, Mockito (library docs)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"refactor\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"type-safety\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"test-driven-development owns the design discipline of writing the test before the production code; this skill owns the design of the stand-in objects those tests use. The two compose: TDD prescribes the rhythm; test-doubles-design prescribes the stand-ins.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the strategic question of what to test at which level; this skill owns the tactical construction of the stand-ins that make a given test possible.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor owns behavior-preserving structural change; this skill owns the doubles whose over-use produces refactor-fragile tests. The two skills are read together when a test suite resists refactoring.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the design of an interface as a production contract; this skill owns the doubles that exercise that interface in tests. When test doubles drive interface decisions (London-school TDD), this skill and api-design overlap heavily.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"refactor\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A test double is to a unit under test what a Hollywood stunt-double is to a leading actor — the stunt-double looks like the actor enough that the camera believes the scene, performs the dangerous part the actor cannot or should not perform (slow networks, paid APIs, real emails), but is not the actor. The director's job is choosing the right kind of stunt-double for the scene: a dummy stands in the back of the shot (placeholder); a stub recites canned lines from off-camera (canned answers); a spy records which lines were spoken (call recording); a mock has a script that *fails the take* if the actor deviates (rigid interaction verification); a fake is a body-double trained to actually perform the action in a controlled way (working in-memory substitute). Casting mocks where a fake would do produces takes that pass when the stunt is performed exactly as written and fail catastrophically when the actor improvises a better line.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A test double is a stand-in object that replaces a real collaborator in a test so the test can run without the collaborator's real behavior. The term, from Meszaros's *xUnit Test Patterns*, generalizes a family of stand-ins — dummies, stubs, spies, fakes, and mocks — each defined by what the test expects of it. Doubles exist because real collaborators are often unavailable (external services), nondeterministic (time, network, randomness), slow (databases, file systems), expensive (paid APIs), or have side effects unacceptable in a test (sending email, charging cards). The discipline of test-doubles design is choosing the right kind of double for each test's purpose, recognizing that the choice determines what the test actually verifies — state or interaction — and what the test will reveal under refactoring.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/test-doubles-design/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/test-doubles-design/SKILL.md
+---
+
+# Test-Doubles Design
+
+## Coverage
+
+The discipline of choosing and constructing the stand-in objects that replace real collaborators in tests. Covers the five-kind taxonomy (dummy, stub, spy, mock, fake) from Meszaros's *xUnit Test Patterns*, the state-vs-interaction verification distinction that determines which kinds fit which tests, the solitary-vs-sociable test-shape trade-off, the under-use of fakes as the robust middle ground, the cost ledger of every double (divergence, maintenance, false confidence, fragility), and the heuristics for when to use a real collaborator instead of any double. Includes the connection to London/Detroit-school TDD and to the api-design surface that doubles often pressure.
+
+## Philosophy
+
+A test double is a small lie the test tells the unit under test. The lie is useful — it makes the test fast, isolated, deterministic, and free of side effects — but every lie is also a place where the test's belief about the collaborator may diverge from the collaborator's actual behavior. The discipline of test-doubles design is choosing lies whose costs are worth the tests they enable, and recognizing that the choice of *what kind* of lie shapes what the test actually verifies.
+
+The biggest design decision in test-doubles work is whether the test is verifying state ("after this action, the system looks like this") or interaction ("during this action, these calls were made to collaborators"). The choice is not a matter of preference; it determines the test suite's character, its fragility under refactoring, and its connection to the production design. London-school TDD favors interaction; Detroit-school favors state. Most working test suites mix both, and most working test suites have not chosen the mix consciously.
+
+The under-acknowledged construct is the fake. Discourse about test doubles is dominated by mocks (because they are the most distinctive kind and the most natural fit for interaction verification), but fakes — working implementations with production-unsuitable shortcuts — often produce more robust tests with less long-term maintenance cost. A test suite that uses fakes for collaborators that admit a working stand-in (databases, clocks, HTTP clients) and reserves mocks for true behavioral verification is usually better-aged than the equivalent mock-heavy suite.
+
+## The Five Kinds — A Practical Reference
+
+| Kind | What it is | What it verifies | Fragility under refactor | Best use |
+|---|---|---|---|---|
+| Dummy | Placeholder; never actually used | Nothing | None — it isn't exercised | Parameter slots the test path doesn't touch |
+| Stub | Returns canned answers to calls | State after the action | Low — only the canned answer matters | Providing inputs the unit needs |
+| Spy | Stub + records calls received | State and (post-hoc) which calls happened | Medium — call-shape changes break the spy assertion | Flexible interaction verification |
+| Mock | Pre-programmed with expected calls; double itself fails on deviation | Interaction (built into the double) | High — call-shape changes break the test directly | Verifying a contract with a collaborator |
+| Fake | Working implementation of the interface with production-unsuitable shortcuts | State end-to-end through the fake | Low — behavior is verified through a working substitute | Slow/nondeterministic collaborators with workable in-memory stand-ins |
+
+## State vs Interaction — The Defining Choice
+
+| Property | State verification | Interaction verification |
+|---|---|---|
+| Question the test answers | "After this, what does the system look like?" | "During this, what did the system do?" |
+| Typical doubles | Stubs, fakes | Spies, mocks |
+| Schools | Detroit-school (Beck), classicist | London-school (Freeman & Pryce), mockist |
+| Refactor fragility | Low — internal call shapes can change | High — call shapes are pinned by the test |
+| Design coupling | Loose — test sees the unit's surface | Tight — test sees the unit's collaborations |
+| Failure mode | Coarse assertions; missed interaction bugs | Test mirrors implementation; refactor breaks tests that still produce correct behavior |
+
+A practical heuristic: prefer state verification when the unit's behavior is naturally state-shaped (calculators, parsers, domain logic); prefer interaction verification when the unit's behavior is naturally collaboration-shaped (orchestrators, controllers, services that exist to coordinate other services).
+
+## When To Use A Real Collaborator (Sociable Tests)
+
+| Collaborator | Real-collaborator use? | If not, prefer |
+|---|---|---|
+| Pure functions, value objects, in-process domain logic | Yes — always | n/a |
+| In-process services, repositories with in-memory implementations | Often yes | Fake if the real one has setup cost |
+| Database access | Increasingly yes (containerized real DB in CI) | In-memory DB fake (SQLite/H2) over mock |
+| File system | Usually fake (temp dir or in-memory FS) | Fake over mock |
+| Time, clocks, schedulers | Always fake | Deterministic clock fake |
+| Network (HTTP) | Recorded responses (fake) or real in integration scope | Fake (recorded responder) over mock |
+| External paid APIs | Fake or contract test against recorded responses | Fake over mock |
+| Other services across process boundary | Contract test against; double in unit scope | Fake or stub at unit scope; real in integration scope |
+
+A test suite that mocks pure-function collaborators is over-mocking; a test suite that uses real third-party APIs in every unit test is under-using doubles.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every double in the test suite is identifiable as one of the five kinds (dummy, stub, spy, mock, fake). Tests that say "mock" loosely (when the construct is really a stub or spy) are using the term in dialect, not in the precise sense.
+- [ ] The verification style (state vs interaction) is consistent within a test. A test that mixes both styles is usually testing two things and should be split.
+- [ ] Doubles sit at real seams (service boundaries, external dependencies, true injection points), not at artificial seams introduced just to enable the test.
+- [ ] Where a collaborator admits a working in-memory implementation, a fake is preferred over a mock. Mocks are reserved for genuine interaction verification.
+- [ ] No test mocks the database; database interaction uses an in-memory DB fake, a containerized real DB in CI, or a contract test layer.
+- [ ] The school being practiced (London/Detroit/hybrid) is intentional, not accidental. The mock-to-fake ratio in the test suite is a measurement of which school is in use.
+- [ ] Tests are not over-specified — strict mocks that pin exact call sequences are used only where the contract is genuinely about the call sequence (rare).
+- [ ] Contract tests, integration tests, or production observability close the gap between mock-isolated unit tests and the real collaborator's actual behavior. Mocks alone are not the full verification story.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Choosing what to test, at which level | `testing-strategy` | testing-strategy owns the strategic question; this skill owns the doubles inside chosen tests |
+| Designing the rhythm of test-first development | `test-driven-development` | TDD owns the discipline of writing tests first; this skill owns the doubles those tests use |
+| Configuring a specific mocking library (Jest, Sinon, Mockito) | library documentation | library API choice is tactical detail below this skill's scope |
+| Setting up a production feature flag or runtime alternative | `feature-gating` | feature-gating is about production behavior; this skill is about test-harness behavior |
+| Designing the production interface a double would mimic | `api-design` | api-design owns the production contract; this skill consumes that contract for tests |
+| Performing a behavior-preserving structural change | `refactor` | refactor owns the technique; this skill owns the doubles that may resist or enable the refactor |
+
+## Key Sources
+
+- Meszaros, G. (2007). *xUnit Test Patterns: Refactoring Test Code*. Addison-Wesley. The canonical reference for the five-kind test-double taxonomy (dummy, stub, spy, mock, fake) and the broader patterns of test-code design.
+- Fowler, M. (2007). ["Mocks Aren't Stubs"](https://martinfowler.com/articles/mocksArentStubs.html). The defining practitioner essay distinguishing classicist (Detroit) and mockist (London) TDD and the role of doubles in each.
+- Freeman, S., & Pryce, N. (2009). *Growing Object-Oriented Software, Guided by Tests* (GOOS). Addison-Wesley. The canonical book on London-school TDD; treats mocks as a design tool that drives collaboration interfaces.
+- Beck, K. (2002). *Test-Driven Development: By Example*. Addison-Wesley. The canonical book on Detroit-school TDD; uses doubles sparingly and verifies state.
+- Fowler, M. ["Test Double"](https://martinfowler.com/bliki/TestDouble.html). Short reference page formalizing Meszaros's taxonomy in practitioner vocabulary.
+- de Oliveira Neto, F. G., et al. (2019). ["Evolution of statistical analysis in empirical software engineering research: Current state and steps forward"](https://www.sciencedirect.com/science/article/abs/pii/S0164121219300573). Survey of empirical evidence on test-suite quality including the effects of mock-heavy vs sociable test designs.
+- Spadini, D., Aniche, M., Bruntink, M., & Bacchelli, A. (2019). ["Mock objects for testing Java systems"](https://link.springer.com/article/10.1007/s10664-018-9663-0). *Empirical Software Engineering*. Industrial study on mock usage patterns and their evolution.
+- Mancinelli, F. (2018). ["A Survey on Test Doubles Frameworks"](https://arxiv.org/abs/1801.10306). Comparative review of mocking libraries across languages; useful as a third-party reference for library-specific encodings.

package/marketplace/skills/test-driven-development/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: test-driven-development
+description: "Use when reasoning about Test-Driven Development as a design discipline rather than a workflow: the red-green-refactor cycle as a feedback loop, the difference between London-school (outside-in, interaction-heavy, mock-driven) and Detroit-school (inside-out, state-heavy, classicist) TDD, the role of TDD as a design tool (how tests pressure code into more decomposable shapes), the connection between TDD and emergent design, the boundary between TDD and prior-test-suites, why TDD's failure mode is not 'no tests' but 'tests that mirror implementation', and the empirical record of TDD's effects on defect density, design quality, and development velocity. Do NOT use for the strategy of what to test at which level (use testing-strategy), the construction of test doubles (use test-doubles-design), the discipline of LLM eval iteration (use eval-driven-development), or general-software process workflow (use the obra/superpowers test-driven-development workflow skill — this skill is the concept-shape complement)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/testing\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"test-driven development\\\\\\\",\\\\\\\"TDD\\\\\\\",\\\\\\\"red green refactor\\\\\\\",\\\\\\\"London school\\\\\\\",\\\\\\\"Detroit school\\\\\\\",\\\\\\\"Chicago school\\\\\\\",\\\\\\\"outside-in TDD\\\\\\\",\\\\\\\"inside-out TDD\\\\\\\",\\\\\\\"mockist\\\\\\\",\\\\\\\"classicist\\\\\\\",\\\\\\\"emergent design\\\\\\\",\\\\\\\"test-first\\\\\\\",\\\\\\\"design pressure\\\\\\\",\\\\\\\"GOOS\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should we write tests first\\\\\\\",\\\\\\\"are mocks ruining the design\\\\\\\",\\\\\\\"is TDD worth it\\\\\\\",\\\\\\\"London school vs Detroit school\\\\\\\",\\\\\\\"the tests changed every refactor\\\\\\\"]\",\"examples\":\"[\\\\\\\"explain why writing the test first changes the design of the code under test\\\\\\\",\\\\\\\"decide between London-school (mocks-as-design) and Detroit-school (state-verification) TDD for a new module\\\\\\\",\\\\\\\"diagnose why the test suite is fragile under refactor — likely over-mocked interaction tests\\\\\\\",\\\\\\\"explain why high test coverage with TDD is a side effect, not the goal\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"construct a mock, stub, or spy (use test-doubles-design)\\\\\\\",\\\\\\\"decide what test levels (unit/integration/e2e) to invest in (use testing-strategy)\\\\\\\",\\\\\\\"iterate on LLM behavior using an eval suite (use eval-driven-development)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"test-doubles-design\\\\\\\",\\\\\\\"eval-driven-development\\\\\\\",\\\\\\\"refactor\\\\\\\",\\\\\\\"type-safety\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the question 'what should we test, at which level, with what evidence' for a given change; this skill owns the design discipline of writing the test before the code that satisfies it. The two compose — testing-strategy decides the surface; TDD prescribes the rhythm — but they answer different questions.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"test-doubles-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"test-doubles-design owns mocks/stubs/fakes/spies as a construct; this skill owns the discipline that places them (London-school heavily, Detroit-school lightly). The schools differ on how much test-doubles design matters to the practice.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"eval-driven-development\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"eval-driven-development owns the LLM analog of TDD where the unit of judgment is pass-rate over a sample rather than binary per-test pass/fail. The disciplines share the iteration-first-then-implement spirit but the math underneath differs.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor owns behavior-preserving structural change; this skill prescribes refactor as the third beat of red-green-refactor. The skills compose: TDD calls refactor on every green; refactor owns how to do it without breaking behavior.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"refactor\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"TDD is to code design what a piano teacher's metronome is to a student's playing — the rhythm is not the music, but it surfaces every uneven phrase, every rushed measure, every hesitation, in time to correct it before it ossifies into habit.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Test-Driven Development is a software design discipline in which the test for a behavior is written before the production code that satisfies the test, then production code is written until the test passes, then the code is restructured to improve its shape while the test continues to pass. The cycle — red (failing test), green (passing test), refactor (clean code, still passing) — is the unit of work, and the test suite is the design pressure that shapes the production code. TDD is not 'writing tests first' as a procedural rule; it is using the act of writing a test as the moment to design the interface, decompose the responsibility, and discover what the code should be. The tests are a beneficial side effect of doing design through the test-writing lens; mistaking the side effect for the purpose is the most common failure mode.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/test-driven-development/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/test-driven-development/SKILL.md
+---
+
+# Test-Driven Development
+
+## Coverage
+
+The design discipline of writing the test before the production code that satisfies it, using the test-writing pressure to shape the code's design, and applying the red-green-refactor cycle as the unit of work. Covers the cycle structure (red → green → refactor), the design-pressure mechanism that makes TDD a design discipline rather than just a test-first habit, the London/Detroit/Chicago school distinctions (mockist vs classicist, outside-in vs inside-out, interaction vs state), the relationship between TDD and emergent design, the empirical record (Nagappan 2008 at Microsoft/IBM and meta-analyses since), the boundary between TDD and BDD, and the failure modes (skipping refactor, ignoring design pressure, mock-heavy fragile tests, coverage-as-goal Goodharting).
+
+## Philosophy
+
+TDD is design through the test-writing lens. Every test you sit down to write is a moment of design: what is this unit, what does it own, what does it delegate, what does its interface look like from the outside. The discomfort of writing a hard-to-test piece of code is the same discomfort that will eventually arrive as hard-to-use, hard-to-maintain, hard-to-compose code; TDD makes that discomfort visible at the moment when correcting it is cheap.
+
+The tests are not the point. The tests are an artifact of doing design with a test-shaped tool. A team that "does TDD" by writing tests first without heeding the design pressure has the artifact without the practice; they will conclude TDD doesn't work because they will see only the cost (slower initial development) without the benefit (better-shaped code with lower defect density).
+
+The schools matter. London and Detroit produce different code under the same red-green-refactor cycle, because they apply the design pressure to different surfaces. A practitioner who has not chosen a school has chosen by accident, and the test suite's character — interaction-heavy or state-heavy, mock-rich or mock-sparse, outside-in or inside-out — reveals which they chose without knowing.
+
+## The Cycle In Detail
+
+| Beat | Activity | Stop condition | Common mistake |
+|---|---|---|---|
+| Red | Write one failing test for one increment of desired behavior | The test compiles and fails for the right reason (not a syntax error) | Writing a passing test (no design pressure); writing many tests at once (loses the increment) |
+| Green | Write the smallest production change that makes the test pass | The test passes; no other tests broke | Writing more than needed; "fake it till you make it" abandoned too early |
+| Refactor | Improve the shape of both code and test while keeping all tests passing | The structure is cleaner; tests still pass | Skipping this beat; refactoring into bigger changes that break tests |
+
+Each cycle should fit in a few minutes — long cycles indicate either insufficient test granularity or production complexity that should be decomposed before continuing.
+
+## London School vs Detroit School — A Practical Comparison
+
+| Property | London (mockist, outside-in) | Detroit (classicist, inside-out) |
+|---|---|---|
+| Origin | Freeman & Pryce, *GOOS* (2009) | Beck, *TDD by Example* (2002) |
+| Starting point | Acceptance test or service boundary | A single concrete unit |
+| Test focus | Interactions (who called whom with what) | Observable state changes |
+| Test doubles | Central — every new collaborator becomes a mock | Sparse — used only when needed (DB, external service) |
+| Design pressure | On collaborator interfaces (the mocks shape them) | On units' responsibilities and state shape |
+| Failure mode | Tests mirror implementation; refactor breaks them | State assertions get coarse; design coupling grows |
+| Typical codebase | Many small classes with well-defined collaboration roles | Fewer larger classes with rich state |
+
+A practical heuristic: London-school suits services with rich collaboration (microservices, hexagonal architectures); Detroit-school suits state-rich domains (calculators, domain logic, parsers). Hybrid is the working norm.
+
+## The Empirical Record
+
+Multiple controlled studies and one large industrial study converge on a consistent finding: TDD codebases have lower defect density at the cost of slightly longer initial development time.
+
+| Study | Finding |
+|---|---|
+| Nagappan et al. (2008) at Microsoft and IBM | TDD teams had 40-90% lower defect density; 15-35% longer initial development time |
+| Erdogmus et al. (2005) controlled experiment | TDD subjects had higher external code quality; productivity comparable |
+| Janzen & Saiedian (2008) meta-analysis | Code complexity reduced; cohesion improved; coupling reduced under TDD |
+| Bissi et al. (2016) systematic review | 27 of 39 studies showed TDD improved internal quality; 18 of 23 showed external quality improvement |
+
+The trade is well-documented. Teams abandoning TDD often do so on the visible-cost side (the time spent writing tests) without measuring the invisible-saving side (defects not encountered, rework not required).
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every increment of production code is preceded by a failing test that describes the behavior, not the implementation. If code was written before the test, the test is regression coverage, not TDD-born specification.
+- [ ] Each cycle includes a refactor beat. Cycles that go red → green → next-red are test-first development, not TDD.
+- [ ] The school being practiced (London / Detroit / hybrid) is intentional, not accidental. The test suite's character (mock-rich vs state-rich) reveals which school is in use.
+- [ ] When a test is hard to write, the design is examined. Hard-to-test code is the design-pressure signal; ignoring it (with test-only hooks, exposed internals, or stretched test boundaries) defeats the discipline.
+- [ ] Test names describe behaviors at the unit's natural boundaries — "calculates total with discount applied," not "tests `calculateTotal()` line 17."
+- [ ] Coverage is treated as a side effect, not a target. The discipline is the goal; coverage emerges from doing it.
+- [ ] The cycle's granularity stays small. Cycles that run hours indicate either over-large tests or under-decomposed production code.
+- [ ] For research/spike work where the target is unclear, exploration is allowed before TDD applies. The discipline is not universally appropriate.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Choosing what to test, at which level, with what evidence | `testing-strategy` | testing-strategy owns the strategic-level decision; this skill owns the tactical design discipline |
+| Constructing a mock, stub, fake, or spy | `test-doubles-design` | test-doubles-design owns the constructs; this skill owns the discipline that places them |
+| Iterating on LLM behavior using an eval suite | `eval-driven-development` | eval-driven-development is the LLM analog with statistical (not binary) judgment |
+| Performing a behavior-preserving structural change | `refactor` | refactor owns the technique; this skill calls it as the third beat |
+| Process workflow guidance for a TDD session | the obra/superpowers `test-driven-development` skill on skills.sh | that skill is the workflow-shape complement; this one is concept-shape |
+
+## Key Sources
+
+- Beck, K. (2002). *Test-Driven Development: By Example*. Addison-Wesley. The canonical book on Detroit-school TDD; defines red-green-refactor and the discipline's core form.
+- Freeman, S., & Pryce, N. (2009). *Growing Object-Oriented Software, Guided by Tests* (GOOS). Addison-Wesley. The canonical book on London-school TDD; defines outside-in mock-driven development.
+- Nagappan, N., Maximilien, E. M., Bhat, T., & Williams, L. (2008). ["Realizing quality improvement through test driven development: results and experiences of four industrial teams"](https://link.springer.com/article/10.1007/s10664-008-9062-z). *Empirical Software Engineering*, 13(3), 289-302. The Microsoft/IBM industrial study showing 40-90% defect-density reduction.
+- Erdogmus, H., Morisio, M., & Torchiano, M. (2005). ["On the effectiveness of the test-first approach to programming"](https://ieeexplore.ieee.org/document/1423994). *IEEE Transactions on Software Engineering*, 31(3), 226-237. Controlled experiment on TDD's productivity and quality effects.
+- Janzen, D., & Saiedian, H. (2008). ["Does Test-Driven Development Really Improve Software Design Quality?"](https://ieeexplore.ieee.org/document/4493089). *IEEE Software*, 25(2). Meta-analysis on TDD's effect on code complexity, cohesion, and coupling.
+- Bissi, W., Serra Seca Neto, A. G., & Emer, M. C. F. P. (2016). ["The effects of test driven development on internal quality, external quality and productivity: A systematic review"](https://www.sciencedirect.com/science/article/abs/pii/S0950584916300903). *Information and Software Technology*, 74, 45-54. Systematic review of 27 controlled studies.
+- Fowler, M. (2007). ["Mocks Aren't Stubs"](https://martinfowler.com/articles/mocksArentStubs.html). Practitioner-focused explanation of the London/Detroit school distinction and its consequences.
+- North, D. (2006). ["Introducing BDD"](https://dannorth.net/introducing-bdd/). The origin essay for Behavior-Driven Development as a vocabulary and tooling layer above TDD.

package/marketplace/skills/testing-strategy/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: testing-strategy
+description: "Use when planning tests for a bug fix, feature, or refactor — deciding what deserves a test, at which level, with what evidence. Covers test-scope decisions, test-level selection (unit / integration / contract / e2e), effort-to-risk matching, regression targeting, evidence quality, and failure-case coverage. Do NOT use for chasing a known failure (that is `debugging`), for pure doc writing (that is `documentation`), or for conceptual architecture discussion with no verification target (no dedicated skill — treat as strategy, not testing)."
+license: MIT
+compatibility: "Markdown, Git, any codebase"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-04-18\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-04-18\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"passing\",\"routing_eval\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"testing strategy\\\\\\\",\\\\\\\"what to test\\\\\\\",\\\\\\\"what not to test\\\\\\\",\\\\\\\"which test level\\\\\\\",\\\\\\\"test scope\\\\\\\",\\\\\\\"effort vs risk\\\\\\\",\\\\\\\"regression target\\\\\\\",\\\\\\\"failure case coverage\\\\\\\",\\\\\\\"test plan\\\\\\\",\\\\\\\"do I need a test\\\\\\\",\\\\\\\"should I test this\\\\\\\",\\\\\\\"unit or integration\\\\\\\",\\\\\\\"test coverage\\\\\\\",\\\\\\\"pin this behavior\\\\\\\",\\\\\\\"plan test coverage\\\\\\\",\\\\\\\"plan coverage\\\\\\\",\\\\\\\"needs an automated test\\\\\\\",\\\\\\\"automated test\\\\\\\",\\\\\\\"manual QA coverage\\\\\\\",\\\\\\\"passes manual QA\\\\\\\",\\\\\\\"test level decision\\\\\\\"]\",\"triggers\":\"[\\\\\\\"testing-skill\\\\\\\"]\",\"routing_bundles\":\"[\\\\\\\"quality\\\\\\\"]\",\"examples\":\"[\\\\\\\"do I need a unit test for this pure formatter or is integration enough?\\\\\\\",\\\\\\\"what's the right test level for a webhook handler that talks to Stripe?\\\\\\\",\\\\\\\"the feature passes manual QA — does it need an automated test?\\\\\\\",\\\\\\\"pin this regression so the same bug can't slip through again\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"my existing test is failing — why?\\\\\\\",\\\\\\\"write a testing-patterns guide for the contributor docs\\\\\\\",\\\\\\\"clean up this duplicated test setup across three files\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging chases a specific observed failure; testing-strategy decides what to test BEFORE a failure exists\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor reshapes code (including test setup) while preserving behavior; testing-strategy decides what coverage to author in the first place\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"integration-test-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"integration-test-design owns the design of integration-level tests including their setup and data lifecycle; the 'duplicated test setup across three files' anti_example has token overlap with integration-test setup discipline. testing-strategy decides what level a test should be; integration-test-design owns how to design integration tests once chosen.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"debugging\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/testing-strategy/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/testing-strategy/SKILL.md
+---
+
+# Testing Strategy
+
+## Coverage
+
+- Test scope: deciding what behavior actually needs a test, and what does not earn the maintenance cost
+- Test level selection: choosing between unit, integration, contract, and end-to-end tests based on risk and coupling
+- Effort-to-risk matching: investing verification effort where regressions are most likely and most damaging
+- Regression targeting: writing tests that pin the specific behavior a change risks breaking, not generic coverage
+- Evidence quality: preferring concrete, reproducible verification over assumed or manual checks
+- Failure-case coverage: ensuring boundary conditions and error paths are tested, not only the happy path
+
+## Philosophy
+
+Most test suites fail the effort-to-risk test: they exercise code that will never break and skip code that breaks in production. The correct target is the behavior that ships to users, not the code you happen to have written last. Coverage percentage is a proxy, and every proxy eventually gets gamed — the real signal is regressions caught before release. A test that never fails is noise; a test that fails without isolating the cause is worse than no test at all because it wastes the next engineer's time.
+
+## Test-Level Selection
+
+Pick the test level by the risk of the change and the coupling of the behavior, not by the file you happen to be editing. Unit tests are cheap to write and cheap to pass; integration and contract tests are where real production bugs are actually caught.
+
+| Situation | Test level | Why |
+|---|---|---|
+| Pure function, single-owner, no I/O | **Unit** | Fast, deterministic, zero setup. If you cannot unit-test it, the function is doing too much |
+| Logic that composes multiple units inside one service | **Integration** (in-process) | Unit tests of each piece will miss composition bugs; integration test catches real wiring |
+| Behavior that crosses a service / process / network boundary | **Contract** | Both sides need a shared verifiable agreement; a unit test on either side misses the real failure mode |
+| User-visible flow end-to-end | **E2E** (one or two per critical path) | Proves the full path works at least once; too expensive to run for every code path |
+| Bug fix for a bug that reached production | **Regression** at the level where the bug slipped through | If it slipped past unit tests, a unit test won't catch it next time; write the test at the level the bug exposed |
+| Behavior that is "obviously correct," unchanged for a year, no external pressure | **No new test** | The test would never fail; it would only add maintenance cost. Every test is a liability until it catches a bug |
+
+### Level-selection anti-patterns
+
+- **Unit testing what should be an integration test** — mocking the only thing that could actually break. Fix: test the real integration, or admit the unit test proves nothing.
+- **Integration testing what should be a unit test** — slow setup for a function that has no dependencies. Fix: extract the pure logic and unit-test it.
+- **E2E-testing every code path** — fragile, slow, flaky. Fix: one E2E per critical user journey, unit/integration for the rest.
+- **Adding a test because coverage dropped** — test has no regression target and never fails meaningfully. Fix: either find a real regression to pin, or delete the uncovered code if it has no value.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/testing-strategy.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/testing-strategy.json). The `Verification` checklist below is the authoring gate for a completed test plan; the eval file is how this skill is graded by `scripts/skill-audit.js --graded`. Do not conflate them — the checklist is for the test author, the eval is for the grader.
+
+## Verification
+
+- [ ] The test type matches the change risk
+- [ ] A behavior or regression target is explicit
+- [ ] Verification evidence is concrete, not assumed
+- [ ] Failure cases and boundaries are covered, not only the happy path
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `documentation` | The task structures explanation for a reader, not verification for a change |
+| `debugging` | The task is chasing a known failure — strategy is planned before the failure, not after |
+| `refactor` | The task is restructuring code; any test work is to preserve existing behavior, which belongs to the refactor skill's verification step |

package/marketplace/skills/theme-system-design/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: theme-system-design
+description: "Use when designing a theme system — design tokens, semantic token layering, CSS custom property strategy, runtime theme switching, and theme contract guarantees. Do NOT use for one-off color choices, brand-only palette work, or framework-specific styling-library configuration."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-12\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-12\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"theme token contract\\\\\\\",\\\\\\\"theme semantic layer\\\\\\\",\\\\\\\"theme variables\\\\\\\",\\\\\\\"css custom properties\\\\\\\",\\\\\\\"runtime theme switching\\\\\\\",\\\\\\\"token tiers\\\\\\\",\\\\\\\"theme contract\\\\\\\",\\\\\\\"design tokens community group\\\\\\\",\\\\\\\"theme parity\\\\\\\",\\\\\\\"token naming\\\\\\\",\\\\\\\"reference tokens\\\\\\\",\\\\\\\"system tokens\\\\\\\"]\",\"triggers\":\"[\\\\\\\"theme system\\\\\\\",\\\\\\\"design tokens\\\\\\\",\\\\\\\"theme switching\\\\\\\",\\\\\\\"css variables for theming\\\\\\\",\\\\\\\"token architecture\\\\\\\"]\",\"examples\":\"[\\\\\\\"Design a three-tier token system (reference → system → component) for a multi-brand product\\\\\\\",\\\\\\\"Add a third theme to an existing two-theme system without breaking the component contracts\\\\\\\",\\\\\\\"Move from hard-coded colors to CSS custom properties with runtime switching\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Choose the exact hex value for the brand's primary blue\\\\\\\",\\\\\\\"Configure Tailwind's content array and purge settings\\\\\\\",\\\\\\\"Implement the dark mode toggle interaction\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"color-system-design\\\\\\\",\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"visual-design-foundations\\\\\\\",\\\\\\\"dark-mode-implementation\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"color-system-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"color-system-design produces the palette and the semantic color decisions; this skill structures how those decisions become tokens and reach components.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"dark-mode-implementation\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"dark-mode-implementation handles preference detection, asset swapping, and image handling; this skill defines the token layer that makes dark mode trivial to add.\\\\\\\"}]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/theme-system-design/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/theme-system-design/SKILL.md
+---
+
+# Theme System Design
+
+## Coverage
+A theme system is a contract between design decisions and component code, expressed as named tokens that components consume and themes resolve. The mainstream model uses three tiers — reference tokens (raw values: blue.500 = #1E66F5), system or semantic tokens (intent-named: color.background.surface, color.text.primary), and component tokens (component-specific overrides: button.primary.background). Components consume system and component tokens only; themes provide reference-token-to-system-token mappings. This indirection is what allows a single theme swap to repaint the whole product without component edits.
+
+CSS custom properties are the dominant runtime delivery mechanism for web themes. A theme is a set of custom-property assignments scoped to a selector — typically :root for the default, [data-theme="dark"] for alternates. Custom properties cascade and inherit, so a theme override on a subtree (a dark-on-light landing-page hero inside a light app) is a single attribute change. The W3C Design Tokens Community Group format (design-tokens.org) is the emerging interchange standard, expressed as JSON with $value, $type, and $description; tooling (Style Dictionary, Tokens Studio, Terrazzo) transforms it into platform outputs (CSS variables, iOS catalogs, Android resources).
+
+Runtime switching has three operational pieces: persistence (localStorage or a cookie if SSR-sensitive), application (a class or data attribute on the document root before first paint to avoid flash), and propagation (notify components that read theme imperatively — chart libraries, canvases). The pre-paint application typically requires a small inline script in the document head that runs before the stylesheet loads.
+
+Theme contracts make additive changes safe and breaking changes visible. Adding a new system token is safe; renaming or removing one is a breaking change requiring a deprecation cycle. Components that read tokens by exact name should not be expected to handle missing tokens gracefully — a missing token resolves to the CSS variable's fallback value (or invalid, depending on the property), which is rarely what's wanted in production.
+
+## Philosophy
+The indirection earns its complexity by separating two rates of change: brand decisions change rarely, theme assignments (which brand color means "danger") change occasionally, and components change continuously. A flat token system collapses these into one rate and forces every component to know about every brand value. The three-tier model gives each rate of change its own surface to evolve on.
+
+Semantic names beat descriptive names. color.background.surface tells a component author what to use; color.gray.100 forces them to know that gray.100 happens to be the surface color today and changes meaning when the theme flips. The discipline is to resist convenience names that leak appearance into the contract.
+
+## Verification
+- Components reference only system or component tokens; a grep for raw hex values or reference tokens in component code returns zero matches.
+- Switching themes at runtime triggers no full-page repaint flicker; the theme attribute is set before the first paint.
+- A new theme can be added by providing only a new set of system-token values; no component files are modified.
+- Token definitions live in a single source-of-truth file (JSON, ideally DTCG-format) and are generated into the CSS variable layer by a build step.
+- Removing or renaming a system token causes a build-time or lint-time error in every consuming component, not a silent runtime fallback.
+- Server-rendered pages serialize the chosen theme into the initial HTML so first paint matches user preference.
+- Documentation lists every semantic token with intent, not appearance.
+
+## Do NOT Use When
+- The task is picking specific color values or designing a palette. Use color-system-design.
+- The work is one-off styling of a single component with no system-wide implications. Use design-module-composition.
+- The integration concerns are dark-mode detection, asset variants, and prefers-color-scheme handling. Use dark-mode-implementation.
+- You are configuring a styling library's runtime (Tailwind config, Emotion theme provider setup) without changing the token contract. That is build configuration, not theme architecture.
+- The decision is about typography or spacing scales rather than tokens generally. Use typography-system or visual-design-foundations.