vanara 0.1.0 → 0.2.0

package/catalog/skills/sql-index-tuning/scripts/suggest-index.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// suggest-index.mjs
+// Propose a composite B-tree index from a query's WHERE / ORDER BY columns,
+// honoring two rules from this skill:
+//   1. equality-before-range  -- equality columns first, then a single range column
+//   2. leftmost-prefix        -- the proposed order is what the index can seek on
+// Equality columns are ordered most-selective-first when a "cardinality" hint is
+// given (higher distinct-count => more selective => leads). ORDER BY columns not
+// already in the key are appended so the sort can be served from the index.
+//
+// Zero dependencies. Node built-ins only.
+//
+// Usage:
+//   node suggest-index.mjs '<json-spec>'            # propose from a literal JSON spec
+//   echo '<json-spec>' | node suggest-index.mjs     # propose from stdin
+//   node suggest-index.mjs --selftest               # run built-in assertions (exit 0/1)
+//
+// Spec shape:
+//   {
+//     "table": "orders",
+//     "predicates": [
+//       { "column": "tenant_id",  "op": "eq",    "cardinality": 5000 },
+//       { "column": "status",     "op": "eq",    "cardinality": 5 },
+//       { "column": "created_at", "op": "range" }
+//     ],
+//     "orderBy": [ { "column": "created_at", "direction": "desc" } ]
+//   }
+// op is one of: "eq" (equality) | "range" (>, <, BETWEEN, LIKE 'x%').
+
+const RANGE_OPS = new Set(['range', 'gt', 'lt', 'gte', 'lte', 'between', 'like_prefix']);
+const EQ_OPS = new Set(['eq', 'equals', '=']);
+
+export function suggestIndex(spec) {
+  const warnings = [];
+  if (!spec || typeof spec !== 'object') throw new Error('spec must be an object');
+
+  const table = typeof spec.table === 'string' && spec.table ? spec.table : 'my_table';
+  const predicates = Array.isArray(spec.predicates) ? spec.predicates : [];
+  const orderBy = Array.isArray(spec.orderBy) ? spec.orderBy : [];
+
+  const equality = predicates.filter((p) => EQ_OPS.has(p.op));
+  const ranges = predicates.filter((p) => RANGE_OPS.has(p.op));
+  const unknown = predicates.filter((p) => !EQ_OPS.has(p.op) && !RANGE_OPS.has(p.op));
+  for (const p of unknown) warnings.push(`predicate on "${p.column}" has unknown op "${p.op}"; ignored`);
+
+  // 1. Equality columns first, most-selective (highest cardinality) first.
+  //    Stable: ties and missing cardinality preserve input order.
+  const eqSorted = equality
+    .map((p, i) => ({ p, i }))
+    .sort((a, b) => {
+      const ca = num(a.p.cardinality);
+      const cb = num(b.p.cardinality);
+      if (ca !== cb) return cb - ca; // higher cardinality leads
+      return a.i - b.i;
+    })
+    .map((x) => x.p.column);
+
+  // 2. At most ONE range column is useful in the seek; the rest become filters.
+  let rangeCol = null;
+  if (ranges.length > 0) {
+    rangeCol = ranges[0].column;
+    for (let i = 1; i < ranges.length; i++) {
+      warnings.push(
+        `multiple range predicates; only "${rangeCol}" can seek -- "${ranges[i].column}" becomes a filter`,
+      );
+    }
+  }
+
+  // 3. ORDER BY columns not already present, appended so the sort is index-served.
+  const columns = [...eqSorted];
+  if (rangeCol) columns.push(rangeCol);
+  for (const o of orderBy) {
+    const col = typeof o === 'string' ? o : o && o.column;
+    if (col && !columns.includes(col)) columns.push(col);
+  }
+
+  if (columns.length === 0) {
+    warnings.push('no usable equality/range/order-by columns found; nothing to index');
+    return { table, columns, ddl: null, warnings };
+  }
+
+  // Carry ORDER BY direction onto matching trailing columns (DESC needs it stated).
+  const dir = new Map();
+  for (const o of orderBy) {
+    if (o && typeof o === 'object' && o.column && o.direction) {
+      dir.set(o.column, String(o.direction).toLowerCase() === 'desc' ? 'DESC' : 'ASC');
+    }
+  }
+  const rendered = columns.map((c) => (dir.get(c) === 'DESC' ? `${c} DESC` : c));
+
+  const indexName = `ix_${table}_${columns.join('_')}`.slice(0, 63);
+  const ddl = `CREATE INDEX CONCURRENTLY ${indexName}\n    ON ${table} (${rendered.join(', ')});`;
+
+  if (rangeCol && eqSorted.length === 0) {
+    warnings.push('no equality columns -- a leading range column limits selectivity; verify it pays off');
+  }
+
+  return { table, columns, ddl, warnings };
+}
+
+function num(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : -1; // missing cardinality sorts last (-1)
+}
+
+function run(json) {
+  let spec;
+  try {
+    spec = typeof json === 'string' ? JSON.parse(json) : json;
+  } catch {
+    console.error('✗ invalid JSON spec');
+    return false;
+  }
+  let result;
+  try {
+    result = suggestIndex(spec);
+  } catch (e) {
+    console.error(`✗ ${e.message}`);
+    return false;
+  }
+  console.log(`Proposed index columns: (${result.columns.join(', ')})`);
+  if (result.ddl) console.log(result.ddl);
+  for (const w of result.warnings) console.log(`! ${w}`);
+  return true;
+}
+
+function selftest() {
+  const cases = [
+    {
+      name: 'equality-before-range + selectivity ordering',
+      spec: {
+        table: 'orders',
+        predicates: [
+          { column: 'status', op: 'eq', cardinality: 5 },
+          { column: 'tenant_id', op: 'eq', cardinality: 5000 },
+          { column: 'created_at', op: 'range' },
+        ],
+        orderBy: [{ column: 'created_at', direction: 'desc' }],
+      },
+      // tenant_id (higher cardinality) leads, then status, then the range/sort col
+      expectColumns: ['tenant_id', 'status', 'created_at'],
+      expectDdlIncludes: 'created_at DESC',
+    },
+    {
+      name: 'order-by column appended when not already in key',
+      spec: {
+        table: 'events',
+        predicates: [{ column: 'user_id', op: 'eq' }],
+        orderBy: [{ column: 'occurred_at', direction: 'asc' }],
+      },
+      expectColumns: ['user_id', 'occurred_at'],
+    },
+    {
+      name: 'preserve input order when no cardinality hints',
+      spec: {
+        table: 'memberships',
+        predicates: [
+          { column: 'tenant_id', op: 'eq' },
+          { column: 'role', op: 'eq' },
+        ],
+      },
+      expectColumns: ['tenant_id', 'role'],
+    },
+    {
+      name: 'second range predicate warns and becomes a filter',
+      spec: {
+        table: 'orders',
+        predicates: [
+          { column: 'tenant_id', op: 'eq' },
+          { column: 'created_at', op: 'range' },
+          { column: 'total_cents', op: 'range' },
+        ],
+      },
+      expectColumns: ['tenant_id', 'created_at'],
+      expectWarningIncludes: 'total_cents',
+    },
+    {
+      name: 'empty predicates yields no index',
+      spec: { table: 'orders', predicates: [], orderBy: [] },
+      expectColumns: [],
+      expectNullDdl: true,
+    },
+  ];
+
+  let allOk = true;
+  for (const c of cases) {
+    const r = suggestIndex(c.spec);
+    let ok = arrEq(r.columns, c.expectColumns);
+    if (ok && c.expectDdlIncludes) ok = !!r.ddl && r.ddl.includes(c.expectDdlIncludes);
+    if (ok && c.expectWarningIncludes) ok = r.warnings.some((w) => w.includes(c.expectWarningIncludes));
+    if (ok && c.expectNullDdl) ok = r.ddl === null;
+    allOk = allOk && ok;
+    console.log(
+      `${ok ? '✓' : '✗'} ${c.name}: got (${r.columns.join(', ')})` +
+        (ok ? '' : ` -- expected (${c.expectColumns.join(', ')})`),
+    );
+  }
+  console.log(allOk ? 'All selftests passed.' : 'Selftest FAILURES present.');
+  process.exit(allOk ? 0 : 1);
+}
+
+function arrEq(a, b) {
+  return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => v === b[i]);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(run(arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(run(buf) ? 0 : 1));
+}

package/catalog/skills/test-plan-design/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: test-plan-design
+description: How to design a test plan — scope and risk-based prioritization, the test pyramid, case-design techniques (equivalence partitioning, boundary values, decision tables), entry/exit criteria, coverage and requirement traceability, test data and environments. Deep reference with a runnable coverage-gap check.
+type: skill
+version: 2.0.0
+updated: 2026-06-29
+---
+# Test Plan Design
+
+A test plan is a **budget**: finite effort spent where it prevents the most expensive failures. The goal
+is never "test everything" — that is impossible and economically illiterate. The goal is to make a
+defensible decision about *what* to test, *at which layer*, *with which cases*, and *when you are done*.
+This skill is the deep reference for that decision. Heavy detail lives in `references/`; copy-paste
+material in `examples/`; a runnable traceability check in `scripts/`.
+
+## Mental model
+
+You are allocating scarce attention across a feature. Four questions drive every plan:
+
+| Question | Answer comes from |
+|---|---|
+| What matters most? | risk = impact × likelihood (scope & prioritization) |
+| At which layer do I test it? | the test pyramid (unit / integration / E2E) |
+| Which concrete cases? | case-design techniques (partitions, boundaries, decision tables) |
+| When am I done? | exit criteria + coverage traced to requirements |
+
+Skip any one of these and the plan degrades: no risk ranking and you over-test trivia; no case design and
+you write five tests that all exercise the same path; no traceability and you ship a requirement nobody
+verified.
+
+## 1. Scope and risk-based prioritization
+
+Start by listing what the feature must do, then rank each item by **risk = impact × likelihood**.
+
+- **Impact**: what does failure cost? Money movement, data loss, security, and legal/compliance are
+  top-tier; cosmetic glitches are bottom-tier.
+- **Likelihood**: how probable is a defect? New code, complex logic, many integrations, and unclear
+  requirements raise it; stable, simple, well-understood code lowers it.
+
+Spend the most rigor at the top of the ranked list and explicitly decide to *under*-test the bottom.
+Writing down "we are not testing X because it is low-risk" is a feature of a good plan, not a gap. The
+full scoring rubric and a worked heat-map live in [references/risk-prioritization.md](references/risk-prioritization.md).
+
+## 2. The test pyramid — choosing a layer
+
+Each behavior should be tested at the **lowest layer that can meaningfully verify it**. Lower layers are
+faster, cheaper, and more precise about *where* a defect is.
+
+```
+        /\        E2E        few   — full user journeys, real-ish stack, slow & flaky
+       /  \       Integration some — module + its collaborators (DB, gateway, queue)
+      /____\      Unit         many — one function/class, no I/O, milliseconds
+```
+
+- **Unit**: pure logic — pricing math, validation, state machines. No network, no DB. Run in ms.
+- **Integration**: a module talking to a real (or faithfully faked) collaborator — a repository hitting a
+  test DB, a client calling a mocked gateway with success/decline/timeout responses.
+- **E2E**: a thin layer covering only critical journeys end to end (e.g. "add to cart → pay → confirm").
+
+The classic anti-pattern is the **inverted pyramid** (an "ice-cream cone"): many slow E2E tests and few
+units. It is slow, flaky, and tells you *that* something broke but not *where*. Layer-selection heuristics
+and the integration/contract-test distinction are in [references/test-pyramid.md](references/test-pyramid.md).
+
+## 3. Case-design techniques
+
+For each unit under test, do not invent cases ad hoc — derive them. Three techniques cover the vast
+majority of input-space reasoning:
+
+- **Equivalence partitioning**: split the input domain into classes that should behave identically, then
+  test *one* representative per class. If ages 18–65 are all "standard", you need one value from that
+  band, not forty.
+- **Boundary value analysis**: bugs cluster at edges. For a valid range `[18, 65]`, test `17, 18, 19` and
+  `64, 65, 66` — just-below, on, and just-above each boundary. Off-by-one errors live here.
+- **Decision tables**: when output depends on a combination of conditions, enumerate the combinations so
+  no rule is missed.
+
+```text
+Discount rules (decision table)
+Member? | Cart ≥ $100 | Coupon valid | → Discount
+  no    |    no       |    no         |   0%
+  no    |    yes      |    no         |   5%
+  yes   |    no       |    no         |  10%
+  yes   |    yes      |    yes        |  25%   ← interaction case, easy to miss
+```
+
+A worked example combining all three on one function is in [references/case-design.md](references/case-design.md),
+and a ready-to-fill case template is in `examples/test-case-template.md`.
+
+## 4. Entry and exit criteria
+
+Make "ready to test" and "ready to ship" explicit so the plan ends on data, not vibes.
+
+- **Entry criteria** (can we start?): code merged to the test branch, build green, test environment and
+  seed data available, dependencies/stubs deployed.
+- **Exit criteria** (can we stop?): all planned cases executed; all CRITICAL/HIGH-risk requirements have a
+  passing test; coverage target met (e.g. 80% line on changed code); zero open Sev-1/Sev-2 defects; known
+  issues triaged and accepted by the owner.
+
+Exit criteria are the contract that prevents both premature shipping and endless gold-plating.
+
+## 5. Coverage and traceability to requirements
+
+Coverage has two distinct meanings — track both:
+
+1. **Code coverage** (line/branch): a *necessary* signal, not a *sufficient* one. 100% line coverage with
+   zero assertions proves nothing.
+2. **Requirement coverage**: every requirement maps to at least one test that verifies it. This is the one
+   that catches "we built it but nobody tested it."
+
+Maintain a traceability matrix (requirement ↔ test case). The runnable check
+`scripts/coverage-gaps.mjs` takes your requirements and test cases as JSON and lists any requirement with
+**no** covering test — run it in CI so an untested requirement fails the build. See
+`examples/test-plan.md` for a filled matrix.
+
+## 6. Test data and environments
+
+- **Data**: prefer small, purpose-built fixtures over a copy of production. Cover the equivalence classes
+  and boundaries from §3. Never use real PII in test data — synthesize it. Make data setup deterministic
+  and self-cleaning so tests are independent and order-free.
+- **Environments**: keep a dedicated, reproducible test environment (containers/IaC) so "works on my
+  machine" is not a defense. Pin external dependencies via fakes/contract tests; do not let a flaky
+  third-party sandbox gate your pipeline.
+
+## Common pitfalls (failure modes)
+
+- **Testing everything equally** — no risk ranking, so trivial getters get the same attention as the
+  payment path. Rank first.
+- **Inverted pyramid** — leaning on slow, flaky E2E for logic that a unit test would pin precisely.
+- **Coverage theater** — chasing a line-coverage number with assertion-free tests; green bar, no safety.
+- **Redundant cases** — five tests in the same equivalence class, zero at the boundary where the bug is.
+- **No traceability** — a requirement ships with no test because nothing connected the two.
+- **Non-deterministic data/time** — tests depend on "today" or shared mutable rows and fail intermittently.
+- **Vague exit criteria** — "looks good" instead of measurable gates, so testing ends by exhaustion.
+
+## When NOT to use / trade-offs
+
+A heavyweight, document-driven test plan is overkill for a one-line bug fix or a throwaway spike — there,
+a couple of targeted tests and a green CI run are the proportionate response. Formal test plans earn their
+cost on high-risk, multi-team, regulated, or long-lived features. Likewise, exhaustive case enumeration is
+wasteful on low-risk surfaces; reserve decision tables and full boundary analysis for logic where a defect
+is expensive. The plan should be *proportional to risk* — a plan that costs more than the failures it
+prevents is itself a failure. For ongoing change to an existing suite (what to re-run after a change, how
+to fight flakiness over time), that is a different discipline — see the pairing below.
+
+## Files in this package
+
+- `references/risk-prioritization.md` — risk scoring rubric, impact/likelihood matrix, worked heat-map
+- `references/test-pyramid.md` — layer-selection heuristics, integration vs contract tests, anti-patterns
+- `references/case-design.md` — equivalence partitioning, boundary analysis, decision tables, worked example
+- `examples/test-plan.md` — a complete, filled-in test plan with a traceability matrix
+- `examples/test-case-template.md` — a reusable single-test-case template
+- `scripts/coverage-gaps.mjs` — runnable check: lists requirements with no covering test (`--selftest`)
+
+Pairs with the `qa-strategist` agent, the `test-author` agent, and the `regression-strategy` skill.

package/catalog/skills/test-plan-design/examples/test-case-template.md

@@ -0,0 +1,45 @@
+# Test Case Template
+
+A reusable shape for a single test case. Keep one per case; the `id` is what the traceability matrix and
+`scripts/coverage-gaps.mjs` reference.
+
+```yaml
+id: coupon_min_5000
+requirement: R3            # links back to a requirement in the test plan
+title: Coupon applies exactly at the $50 minimum
+layer: unit               # unit | integration | e2e
+technique: boundary       # partition | boundary | decision-table | exploratory
+priority: high            # from risk ranking
+
+preconditions:
+  - a valid, non-expired coupon "SAVE10" exists
+
+# Arrange / Act / Assert
+arrange:
+  cartTotal: 50.00        # the boundary value (min is inclusive)
+  coupon: "SAVE10"
+act:
+  call: validateCoupon(coupon, cartTotal)
+assert:
+  result: applied
+  discountPercent: 10
+
+notes: paired with coupon_min_4999 (just below) and coupon_min_5001 (just above)
+```
+
+## Filled boundary trio
+
+The same requirement R3 needs three cases to pin the `$50` edge — copy the block above per row:
+
+| id | cartTotal | expected |
+|---|---|---|
+| `coupon_min_4999` | `49.99` | `min_not_met` |
+| `coupon_min_5000` | `50.00` | `applied` |
+| `coupon_min_5001` | `50.01` | `applied` |
+
+## Why this shape
+
+- `id` + `requirement` make traceability machine-checkable.
+- `technique` documents *why* this case exists, so reviewers can spot a partition or boundary that is
+  missing.
+- Arrange/Act/Assert keeps each case focused on one behavior with one reason to fail.

package/catalog/skills/test-plan-design/examples/test-plan.md

@@ -0,0 +1,57 @@
+# Test Plan — Checkout v2
+
+A filled-in example you can copy and adapt. Keep it short; a plan nobody reads is wasted effort.
+
+## 1. Scope
+
+In scope: cart pricing, tax, coupon validation, payment capture/refund, order confirmation.
+Out of scope: marketing emails (covered by the comms team), the static footer.
+
+## 2. Risk ranking
+
+| Area | Impact | Likelihood | Risk | Primary layer |
+|---|---|---|---|---|
+| Payment capture/refund | 5 | 4 | 20 | integration + E2E |
+| Price & tax math | 5 | 3 | 15 | unit |
+| Coupon validation | 3 | 4 | 12 | unit (decision table) |
+| Inventory decrement | 4 | 3 | 12 | integration |
+| Confirmation email | 2 | 2 | 4 | integration (fake mailer) |
+| Footer year | 1 | 1 | 1 | not tested (accepted by PO) |
+
+## 3. Entry criteria
+
+- Feature branch merged to `test`, CI build green.
+- Test environment provisioned; seed catalog + test cards loaded.
+- Payment gateway sandbox reachable OR contract fakes deployed.
+
+## 4. Exit criteria
+
+- All planned cases executed.
+- Every CRITICAL/HIGH requirement has ≥1 passing test (see matrix).
+- Line coverage ≥ 80% on changed files.
+- Zero open Sev-1/Sev-2 defects; remaining issues triaged and accepted.
+
+## 5. Requirement → test traceability matrix
+
+This is the data `scripts/coverage-gaps.mjs` consumes (as JSON) to fail the build on any uncovered
+requirement.
+
+| Req ID | Requirement | Covering test(s) | Layer |
+|---|---|---|---|
+| R1 | Totals include tax for the buyer's region | `tax_us`, `tax_eu_boundary` | unit |
+| R2 | Expired coupons are rejected | `coupon_expired` | unit |
+| R3 | Coupon needs cart ≥ $50 | `coupon_min_4999`, `coupon_min_5000` | unit |
+| R4 | Declined card shows a retry message | `pay_declined` | integration |
+| R5 | Gateway timeout does not double-charge | `pay_timeout_idempotent` | integration |
+| R6 | Successful pay → confirmation screen | `e2e_happy_checkout` | E2E |
+
+## 6. Test data & environment
+
+- Cards: `4242…` (success), `4000…0002` (decline), a sandbox timeout trigger.
+- Cart fixtures hit each coupon partition (below-min, at-min, above-min) and tax boundary.
+- Data is seeded per-run and torn down after; no shared mutable rows.
+
+## 7. Notes
+
+- Confirmation email asserted via a fake mailer, not the real provider (avoids flaky external dep).
+- Footer year explicitly out of scope — recorded so it reads as a decision, not a miss.

package/catalog/skills/test-plan-design/references/case-design.md

@@ -0,0 +1,79 @@
+# Case-Design Techniques
+
+Do not invent test cases ad hoc — derive them. These three techniques cover most input-space reasoning
+and stop you from writing many tests that all hit the same path while missing the one that breaks.
+
+## 1. Equivalence partitioning
+
+Split the input domain into classes whose members *should* behave identically, then test **one
+representative per class**. Testing forty values from the same class adds cost, not confidence.
+
+Example — a shipping-cost function by weight (kg):
+
+| Partition | Range | Representative |
+|---|---|---|
+| invalid (negative) | `w < 0` | `-1` |
+| light | `0 ≤ w ≤ 5` | `2` |
+| medium | `5 < w ≤ 20` | `12` |
+| heavy | `20 < w ≤ 50` | `35` |
+| over-limit (rejected) | `w > 50` | `60` |
+
+Five tests cover the whole domain's behavior classes.
+
+## 2. Boundary value analysis
+
+Defects cluster at edges (off-by-one, `<` vs `<=`). For each boundary test **just-below, on, and
+just-above**. For the light/medium boundary at `5`:
+
+```text
+w = 4.99  → light
+w = 5.00  → light   (boundary is inclusive)
+w = 5.01  → medium
+```
+
+Repeat at every partition edge (`0`, `5`, `20`, `50`). Boundaries are where equivalence partitioning and
+real bugs intersect, so this is the highest-yield technique per test.
+
+## 3. Decision tables
+
+When output depends on a **combination** of conditions, enumerate the combinations so no rule — and no
+interaction between rules — is missed.
+
+```text
+Loan approval
+Credit ≥ 700 | Income ≥ 50k | Existing debt | → Decision
+   no        |    no         |    -          |  reject
+   no        |    yes        |    yes        |  reject
+   yes       |    no         |    no         |  review
+   yes       |    yes        |    no         |  approve
+   yes       |    yes        |    yes        |  review   ← interaction, easy to miss
+```
+
+For N independent booleans there are 2^N rows; collapse with "don't care" (`-`) entries where a condition
+cannot change the outcome, and keep the interaction rows that ad-hoc testing skips.
+
+## Worked example — combining all three
+
+Function: `validateCoupon(code, cartTotal)` returns `applied | min_not_met | expired | invalid`.
+
+1. **Partition** `cartTotal`: invalid (`< 0`), below-min (`0..49.99`), at-or-above-min (`>= 50`).
+2. **Boundaries** on the `50` minimum: `49.99`, `50.00`, `50.01`.
+3. **Decision table** over `code` state × threshold:
+
+```text
+code state | cartTotal ≥ 50 | → result
+ valid     |    yes          |  applied
+ valid     |    no           |  min_not_met
+ expired   |    yes          |  expired      (expiry checked before threshold)
+ unknown   |    -            |  invalid
+```
+
+Result: ~8 deliberate cases that cover the domain, the edges, and the rule interactions — versus a dozen
+random inputs that would likely all land in the same partition.
+
+## Pitfalls
+
+- **All cases in one partition** — many "valid" inputs, none invalid, none at a boundary.
+- **Skipping interaction rows** — testing each condition alone but never the combination that flips the
+  result.
+- **Boundary blindness** — testing `2` and `35` but never `5` or `50`, exactly where off-by-one hides.

package/catalog/skills/test-plan-design/references/risk-prioritization.md

@@ -0,0 +1,58 @@
+# Risk-Based Prioritization
+
+You cannot test everything, so test what matters most first. Rank each feature area by
+**risk = impact × likelihood** and let that ranking drive where rigor goes.
+
+## Scoring rubric
+
+Score each axis 1–5, multiply, and sort descending.
+
+### Impact (cost of failure)
+
+| Score | Meaning | Examples |
+|---|---|---|
+| 5 | Catastrophic | money moved wrongly, data loss, security breach, legal/compliance breach |
+| 4 | Severe | core flow blocked for all users, corrupted records |
+| 3 | Moderate | feature broken for a segment, recoverable with effort |
+| 2 | Minor | inconvenient, easy workaround |
+| 1 | Cosmetic | visual glitch, no functional effect |
+
+### Likelihood (probability of a defect)
+
+| Score | Meaning | Signals that raise it |
+|---|---|---|
+| 5 | Very likely | brand-new code, complex logic, vague requirements, many integrations |
+| 4 | Likely | recently changed, moderate complexity |
+| 3 | Possible | some history, average complexity |
+| 2 | Unlikely | stable code, simple logic, well understood |
+| 1 | Rare | trivial, unchanged for a long time, heavily exercised in production |
+
+## Worked heat-map (checkout feature)
+
+| Area | Impact | Likelihood | Risk | Rigor |
+|---|---|---|---|---|
+| Payment capture / refund | 5 | 4 | 20 | exhaustive: unit + integration (success/decline/timeout) + E2E |
+| Price & tax calculation | 5 | 3 | 15 | unit-heavy: partitions + full boundary analysis + decision table |
+| Inventory decrement | 4 | 3 | 12 | integration with concurrency case |
+| Coupon validation | 3 | 4 | 12 | decision table over rule combinations |
+| Order confirmation email | 2 | 2 | 4 | one integration test with a fake mailer |
+| Footer copyright year | 1 | 1 | 1 | not tested — documented as accepted |
+
+The bottom rows matter as much as the top: writing "footer year — not tested, low risk" is an explicit,
+defensible decision, not an oversight.
+
+## Turning risk into a budget
+
+1. Sort areas by risk score.
+2. Allocate effort top-down until the budget (time, people) runs out.
+3. For anything below the cut line, record the decision to under-test and who accepted it.
+4. Re-rank when the system changes — risk is not static; a quiet module becomes high-risk the moment it
+   is rewritten.
+
+## Anti-patterns
+
+- **Flat prioritization** — every area gets equal attention, so the payment path and a tooltip compete
+  for the same hour.
+- **Gut-feel only** — skipping the score and "just knowing" what is risky; the matrix forces the
+  conversation and creates an auditable record.
+- **Set-and-forget** — never re-scoring after a refactor moves the risk.

package/catalog/skills/test-plan-design/references/test-pyramid.md

@@ -0,0 +1,58 @@
+# The Test Pyramid — Choosing a Layer
+
+Test each behavior at the **lowest layer that can meaningfully verify it**. Lower is faster, cheaper, and
+more precise about *where* a defect lives.
+
+```
+        /\        E2E         few   — full journeys, real-ish stack, slow, flakiest
+       /  \       Integration some  — module + collaborators (DB, gateway, queue)
+      /____\      Unit          many — one function/class, no I/O, milliseconds
+```
+
+## The three layers
+
+### Unit
+- Scope: a single function/class with no I/O.
+- Verifies: pure logic — pricing, validation, parsing, state machines.
+- Speed: milliseconds; run thousands on every commit.
+- Rule of thumb: if it needs a network, a DB, or the clock, it is not a unit test (inject those).
+
+### Integration
+- Scope: a module talking to a real or faithfully faked collaborator.
+- Verifies: wiring — does the repository persist correctly against a test DB? Does the payment client
+  handle success, decline, and timeout from a mocked gateway?
+- Speed: tens to hundreds of ms; run on every push.
+
+### End-to-end (E2E)
+- Scope: the whole system through its real entry point (HTTP, UI).
+- Verifies: critical user journeys only — login, checkout, the one flow whose failure is unacceptable.
+- Speed: seconds; the slowest and flakiest. Keep this layer thin.
+
+## Layer-selection heuristics
+
+| If you are verifying... | Prefer |
+|---|---|
+| a calculation or branch in logic | unit |
+| that two components talk correctly | integration |
+| that a third-party contract holds | contract test (a focused integration test) |
+| that a user can complete a journey | E2E (one happy path + key failure) |
+
+Push tests down whenever possible. A bug findable by a unit test should not be left for E2E to catch
+slowly and vaguely.
+
+## Integration vs contract tests
+
+A **contract test** pins the shape of the boundary with an external service (request/response schema) so
+you catch drift without depending on the live service in CI. Use it instead of hitting a flaky vendor
+sandbox on every build; run the real integration on a slower cadence.
+
+## Anti-patterns
+
+- **Ice-cream cone (inverted pyramid)** — many E2E, few units. Slow, flaky, and tells you *that*
+  something broke but not *where*.
+- **Testing the framework** — asserting that the ORM saves a row or the HTTP library sends a header; test
+  *your* logic, not the dependency's.
+- **Integration tests that are secretly E2E** — spinning up the entire stack to check one function;
+  collapse it to a unit.
+- **No E2E at all** — every layer green, yet the assembled product is broken because nothing exercised
+  the seams.