test-heuristics

name	test-heuristics
description	Use when reviewing, designing, triaging, or rationalizing test suites — unit, integration, e2e/UI, exploratory, property-based, contract, snapshot, mutation, or performance tests. Trigger for flakiness triage, false-pass risk, brittleness on refactor, suite pruning, test-pyramid/trophy decisions, exploratory charters, and snapshot review. Routes by activity (triage / review / author / strategize / prune) and layer.
license	MIT

Test Heuristics

Practical test-suite review, design, triage, strategy, and pruning for any testing layer a developer writes, runs, debugs, or maintains. Provenance and grounding sources live in skill.json; this file is runtime routing only.

Core principle

A test exists to catch the bugs that ship in this code class — and to be diagnosable when it fails. A test that passes regardless of bug presence, breaks on legitimate refactor, or fails uninformatively is failing at its job.

Activation

• Bare invocation ("use test-heuristics", "test review", "start"): load references/activity-router.csv, show the activity menu, wait. No file inspection, no network calls, no writes.
• Concrete invocation with both activity and layer inferable: skip to step 3 of the workflow.
• Concrete invocation with ambiguous scope: ask one blocker question identifying activity or layer; do not inspect private systems first.

Workflow

1. Pick activity. Load references/activity-router.csv. Match the prompt to: triage, review, author, strategize, prune. Ambiguous → ask once.
2. Pick layer. Load references/activities/<activity>.csv. Match to one or more layers, or all for cross-layer treatment (review fan-out, strategize integrative pass). Ambiguous → ask with the menu.
3. Load grounded context. Load the files in the chosen row's playbook column — most rows reference one playbook; cross-layer rows list many — plus the listed core_refs. For review/all, skip: each spawned layer agent loads its own.
4. Identify the target persona from references/core/personas.md.
5. Handle purpose (spec, regression, characterization, exploration, gate). For review/author/triage/prune, ask which applies (multiple can); heuristics for that purpose apply first. For strategize, skip — the strategy template covers all purposes via its purpose-by-purpose table.
6. Spawn sub-agents in parallel (default for review and prune). Single-layer: one lens per agent. review/all: one layer per agent; each runs the three lenses sequentially inside itself. strategize/all: single integrative pass — no fan-out. See references/subagent-dispatch.md. Fall back to sequential lenses only if the host has no delegation primitive.
7. Apply the playbook. Use heuristics tagged for this activity. For review, score 0–10 using references/core/score-rubric.md. For author, name the good-shaped pattern. For triage, rank hypotheses before fixes. For strategize, produce a per-layer investment recommendation. For prune, produce a deletion list with rationale. Synthesize sub-agent findings here.
8. Apply severity from references/core/severity-rubric.md (0–4) and tag failure modes from references/core/failure-modes.md on every finding.
9. Emit output per the default template in the activity router row.

Modes

• Guided Draft (default): one optionized question at a time, 3–4 likely choices plus a freeform path.
• Autopilot: proceed from available context; state assumptions when the task is clear and low-risk.
• Grill Me: open-ended questions, one at a time, when audience, constraints, or trade-offs materially change the result.

Output requirements

Every output includes:

• Target persona.
• Layer(s) and purpose(s).
• Activity-specific load-bearing section per the template.
• Failure mode(s) tagged on every finding.
• Verification — how to prove the change worked.

Subagent dispatch

Independent perspectives catch issues a single pass misses. Default for review and prune. Preferred for author when comparing approaches. Optional for triage when ranking hypotheses. Skip for tiny edits, deterministic single-step checks, or tasks requiring secrets or production access.

Spawn three sub-agents — one per lens: intent reader, refactor adversary, bug-shape hunter — and run them in parallel. Some hosts do not auto-dispatch; instruct the main agent explicitly ("spawn three agents," "delegate this in parallel"). Load references/subagent-dispatch.md for per-lens prompts, the dispatch template, and the synthesis step. The three lenses each produce a finding list; the synthesizing pass deduplicates, preserves disagreements as open questions, and emits the template-shaped output. Fall back to sequential only when the host has no delegation primitive — the discipline of switching lens between passes matters more than the parallelism.

Reference map

• references/activity-router.csv — level-1 router (activity).
• references/activities/<activity>.csv — level-2 router (layer) per activity.
• references/layers/<layer>.md — layer-specific playbooks (one per layer listed in the activity CSVs).
• references/subagent-dispatch.md — three-lens prompts and synthesis.
• references/core/severity-rubric.md — 0–4 severity scale.
• references/core/score-rubric.md — 0–10 test-quality scale.
• references/core/personas.md — target persona list.
• references/core/failure-modes.md — six-mode test failure taxonomy.
• references/core/oracles.md — SFDIPOT and FEW HICCUPPS oracles for exploratory work and the bug-shape hunter lens.
• templates/*.md — five activity-specific output templates.
• evals/activation-cases.md — activation and behavioral cases (positive and negative).
• evals/run-static-checks.sh — structural and schema gates run in CI.
• evals/trigger-evals.json — queries for the description-optimization loop.
• skill.json — provenance, grounding sources, version, status.