/test-author

name: test-author
description: Test authoring framework for items carrying the needs-test-author trait. Defines scenario derivation from acceptance criteria, the oracle-derivation and blindness rules that keep test authorship independent of implementation, the adversarial probe catalog, forbidden patterns, and the test-plan/test-manifest note formats. Referenced by trait note guidance during queue-phase test-plan and work-phase test-manifest filling. Use when filling test-plan or test-manifest notes, or when asked to author or review tests independently of an implementation.
user-invocable: false

Test Authoring Framework

This skill defines how test authorship is separated from implementation. It exists because an agent that writes both the code and its tests has no adversary in the loop — the tests confirm what was built, not what was intended. The trend record backing this trait names the recurring cost directly: vacuous positive assertions with `|| isEmpty()` escapes, a test oracle computed from the implementation's own formula, `assumeTrue` wrapped around three real production bugs so they never turned the suite red, and coverage claimed in notes that didn't exist in the test tree. `review-quality` already names the bias — "the agent that wrote the tests has an inherent bias toward believing they're correct" — this skill is the structural fix upstream of review: an independent authorship step, gated at the point where an oracle can still be frozen before implementation exists to copy from.

Everything below applies whether the test author is a separate dispatch or, in a degraded mode, the same agent operating at a different, declared point in time. The separation is the point — follow it exactly even when it feels redundant with work you can already see.

When `query_rules(get, rootId, key:"test-author")` succeeds, the served text is authoritative for §3–§10; this skill is the fallback and the Claude-specific addendum.

---

1. When This Applies — The Two Seats

The trait `needs-test-author` puts two seats on an item, occupied at different phases:

• **The plan author**, at queue phase, fills `test-plan` — scenarios, oracle sources, and probes,

frozen before any implementation exists. This is the structural lever: an oracle written before code exists cannot be derived from that code, no matter who writes it later.

• **The test author**, at work phase, fills `test-manifest` — the actual test files, written

after implementation has landed so they compile against the real signatures, but without reading the implementation's reasoning or its own tests.

**Same-agent exception (Direct tier, temporal-only):** for a single-item Direct-tier dispatch there is no second agent to send the work to. The same agent may occupy both seats, but only under a *temporal-only* degraded mode — see §11. The gate still applies: `test-plan` must exist and be frozen before implementation begins, and the manifest must declare the single-actor mode explicitly rather than silently reusing the plan author's context. This is a narrower guarantee than true two-agent separation, and `test-independence-audit` records it as such (`independent-degraded`), never as `independent`.

Outside Direct tier — Delegated and Parallel — the two seats are two dispatches. Never collapse them to save a round-trip; the whole value of this trait is in the second agent's blindness.

---

2. Deriving Numbered Scenarios From Acceptance Criteria

Start from the acceptance criteria in the item's planning note (`task-scope`, `feature-summary`, or `diagnosis`) or the queue-phase spec these criteria live in. Every criterion maps to at least one scenario; a criterion with zero scenarios is a coverage gap, not an implicit pass.

**Partition each criterion into happy / failure / edge**, mirroring the `spec-quality` Test Strategy discipline this note composes with — `test-plan` gives each scenario an oracle and a probe list; `task-scope`'s Test Strategy section should already have named the scenarios themselves, so this step should feel like formalizing, not inventing from scratch. If it feels like inventing from scratch, the queue-phase spec's test strategy was too thin — flag it rather than filling the gap silently.

• **Happy** — the criterion's primary intended behavior under normal input.
• **Failure** — what happens when the criterion's preconditions are violated (invalid input,

missing dependency, disallowed state transition).

• **Edge** — boundary values and structural extremes: empty vs. absent vs. null, exact limit

values, duplicate entries, ordering sensitivity, maximum depth or size.

A criterion that only yields a happy-path scenario has not been fully partitioned — go back and ask what could violate it or sit at its boundary before treating it as covered.

**Name the modules the scenarios touch.** Give `test-plan` a `declarationModules:` line (a comma-separated list of repo-relative paths) covering every module a scenario's oracle or harness depends on, including modules the implementer will not edit. The declarations extractor covers the union of this list and the implementer's changed files; a test-author dispatch naming a module the extractor did not cover is refused with `missingDeclaration:`.

**Stable S-ids.** Number scenarios `S1, S2, S3…` in the `test-plan` note and never renumber once written test code refers to them — the `test-manifest`'s S-id→test mapping is only auditable if the ids are stable across the plan/manifest boundary. If a scenario is dropped, mark it `S4 — dropped: <reason>` rather than closing the numbering gap.

**Label every scenario `EXISTING-SURFACE` or `NEW-SURFACE`.** Red-proof is obtained by reverting the fix and running the item's tests. That works only where the scenario binds to a surface that already existed: when the fix *introduces* the type, parameter, seam or enum constant a test references, reverting it produces a **compile** failure rather than a behavioral red.