ad-spike

# /ad-spike Implements WORKFLOW.md §14 (Staged Spikes With Golden Fixtures) end-to-end. The skill is for cases where the spec is clear but the *technique* is uncertain across multiple plausible approaches — library choice, CV approach, multi-stage transformation. WORKFLOW §9 (TDG) assumes the path is known and validates end-to-end; §14 assumes the path is unknown and validates per stage. Different uncertainty regimes; this skill is for the unknown one. The skill creates a working directory under `spikes/NNNN-<slug>/` and fills it stage-by-stage. The directory is throwaway by design — when the spike concludes, an ADR records the decision (`/ad-adr`) and the spike directory is deleted. See ADR-0017 for the promote-or-delete lifecycle rationale. ## Step 0 — Confirm uncertainty The skill is for *unknown technique* across multiple plausible approaches, not for *non-trivial work* in general. If a single happy path is obvious, **do not start a spike**. If the *how* is knowable from official docs / implementation references / in-repo patterns / git history, route to `ad-ground` and stop. Concrete tests to run before starting: * Could `ad-ground`'s four-source research surface a single happy path with a defensible deviation gate? If yes, run that instead. * Are there ≥2 candidate techniques with materially different trade-offs that no source resolves? If no, this is not a spike. * Is end-to-end validation against expected outputs feasible without per-stage debug? If yes, this is `ad-task` + `ad-philosophy` Goal-Driven Execution territory, not a spike. If the spike is warranted, confirm with the user the *focus* (the specific surface where uncertainty sits — not the whole feature) and proceed. ## Step 1 — Discovery List canonical approaches grounded in **official docs and real examples**. Pick one (or a small set, ≤3) by an **explicit criterion**. Candidate-listing process: 1. Search official documentation for the language / library / domain in question. Cite URL + version. 2. Search public implementation references (open-source repos, Stack Overflow / forum answers, blog posts, gists) for solutions to the same technical focus. Cite `<source>:<locator>` — `<repo>:<path>:<line-range>` for repos, `<URL>` for Stack Overflow / blog / gist — and fetch via tools; never paraphrase from training memory. 3. Survey in-repo for analogous patterns the codebase already uses. Cite `<file>:<line>` or "no analog found". 4. Survey git history for prior attempts at the same problem. Cite `<commit-sha>` or "no prior attempt". Output format: ```markdown ## Discovery — <focus> ### Candidate techniques 1. **<name>** — <one-line description>. Source: <URL or repo:path>. Trade-offs: <pros / cons>. 2. **<name>** — ... 3. **<name>** — ... ### Selection criterion <one-line criterion: latency / accuracy / readability / dependencies / etc> ### Picked <technique X>, picked by criterion <Y>. Alternatives held in reserve: <list>. ``` The output of this step is **information, not code**. No spike directory is created yet. The user reviews the candidate list and confirms the picked approach (or revises) before Step 2. ## Step 2 — Golden fixture Curate inputs with rich expected outputs. The fixture is the ground truth the staged pipeline validates against; richer fixtures catch more failure modes. Create the spike directory: ```bash mkdir -p spikes/NNNN-<slug>/{fixtures,debug,eval} ``` Get NNNN by running `node .claude/skills/ad-spike/scripts/next-number.mjs spikes` from the consumer root. Use JSON `next`; archived gaps stay unused. Stop until access is resolved when `unreadable` is non-empty, and stop for a numbering decision when `exhausted` is true. If loaded elsewhere, substitute the skill base path. The fixture format is JSON keyed by input path (recommended) or whatever shape the domain demands. For computer vision: bounding boxes, sizes, lighting condition, difficulty tag, edge case markers. For multi-stage transformations: intermediate states. For library choice: representative inputs covering typical and edge cases. For a worked fixture file (`spikes/0001-detect-circles/fixtures/golden.json`) with easy / hard inputs, bounding boxes, difficulty tags, and edge-case markers, see [references/fixture-example.md](references/fixture-example.md). Curation principles: * Include **edge cases** (low light, partial occlusion, malformed inputs, large inputs, empty inputs) — not just "happy path" examples. The fixture's job is to surface *where* a technique fails, not just whether it succeeds on easy cases. * Include **difficulty tags** so per-stage evaluation can report performance segmented by difficulty. * Keep the fixture as data, not code. JSON / YAML / CSV — anything that diffs cleanly and survives a refactor. The fixture is the contract the pipeline validates against. Treat it like spec text — it should not change once the spike runs unless ground truth itself changes. ## Step 3 — Pipeline with gates One technique per stage. Each stage emits a **debug artifact** that makes its output inspectable. Pipeline structure — see the spike directory layout in [references/pipeline-layout.md](references/pipeline-layout.md). Each stage's debug artifact format depends on the domain: * CV pipelines: image saved to `debug/NN-<stage>/<input-name>.png` showing the stage's output. * Multi-stage transformations: intermediate JSON saved to `debug/NN-<stage>/<input-name>.json`. * Library evaluation: log row per (input, library) saved to `debug/NN-<stage>/log.csv`. The discipline: **each stage's output must be inspectable independently**. End-to-end output alone tells you *that* it failed; per-stage debug tells you *where*. Implementation pattern (any language): * Stage takes (input, context) and returns (output, debug-record). Debug-record is written to `debug/NN-<stage>/`. * Pipeline runs stages sequentially. Failure at any stage halts the pipeline and reports the stage where divergence happened. ## Step 4 — Two-layer evaluation Run the pipeline against the fixture and emit two layers of results: * **End-to-end:** how many fixture inputs produced expected outputs? Reported as pass / fail per input, plus aggregate pass rate. * **Per-stage:** for each fixture input, where did the pipeline diverge? Stage NN's output vs the expected intermediate. Reported as pass / fail per (input, stage). Output to `spikes/NNNN-<slug>/eval/results.json` — see the two-layer results shape in [references/eval-format.md](references/eval-format.md). The per-stage layer is what makes the spike actionable. End-to-end says *that* it failed; per-stage + debug artifact says *where* and *why*. ## Step 5 — Conclude (promote or delete) When the spike concludes — either the picked technique works or it does not — record the outcome via `/ad-adr` and delete the spike directory. The ADR is the persistent artifact; the spike code is throwaway. The ADR uses `/ad-adr`'s canonical template and captures the technique picked, the end-to-end pass rate, where failures concentrated and their root cause, and the mitigation; the techniques held in reserve and rejected go under `Alternatives Considered`, each with the spike result that rejected it. After the ADR captures the outcome, delete only the exact `spikes/NNNN-<slug>/` directory and route the ADR plus deletion to `/ad-commit`. That skill owns staging, the Conventional Commit message, and the DCO sign-off; do not commit directly from the spike workflow. Spikes that conclude inconclusively get an ADR too — `Decision: defer; the spike at NNNN inconclusive because Y` — and the directory is deleted. Inconclusive spikes are real signal; preserving the framing in an ADR prevents re-litigation. ## Output contract A spike directory at `spikes/NNNN-<short-slug>/` with the four-stage layout above (discovery README, fixtures, pipeline, debug per stage, eval results). The directory is throwaway by design — promote-or-delete lifecycle. No `Status: shipped` lifecycle; spikes do not "ship" — they conclude with an ADR. When the host exposes `AskUserQuestion`, use it for the Step 1 selection criterion confirmation and the Step 5 promote/delete decision. ## Next - `/ad-prism` when the validated technique must now be evaluated against a product or system decision. - After Step 1 (discovery output reviewed): proceed to Step 2 to create the spike directory + fixture, or abort if the discovery surfaced a single happy path (route to `ad-ground`). - After Step 4 (eval results): `/ad-adr` to record the outcome, then delete the spike directory. - If the spike succeeds and production work follows: `/ad-task` for the work units to apply the spike's findings to production code (Spec ref the original spec if applicable; cite the ADR in the task `Notes`).