Skills/fieldtest/SKILL.md

name, description

name

description

fieldtest

Orchestrator-dispatched only, after audit closes clean (or with ratified drift only), when the orchestrator judges the iteration is complete and wants a field test. Picks 2-4 real-world tasks within the cycle's scope, implements each as a downstream consumer of the project, runs them, and writes a friction-and-bug spec. The spec feeds the next plan as a reference. Implementer simulates a downstream user who has only the public interface — never the project's implementation source.

fieldtest — usability field test for a shipped cycle

Violating the letter of these rules is violating the spirit.

Overview

audit measures drift between the design ledger and what the codebase claims to do. fieldtest measures something audit cannot: whether the project, as it now ships, is usable by a downstream consumer who has only the public interface to work from. If a freshly shipped feature is awkward to reach for, or if the public docs leave a corner ambiguous that real usage immediately exercises, the cycle has shipped a latent debt — even when audit reports clean.

The skill produces a friction-and-bug spec that the next iteration's planner consumes as a reference. The spec sits next to cycle-design specs under docs/specs, with a fieldtest- prefix in the slug.

The substantive process — read the design ledger + cycle spec

• recent iter/audit commit bodies, pick 2-4 real-world tasks per cycle axis, implement each as a downstream consumer, run the result, classify findings, write the spec — lives in agents/fieldtester.md. That file also carries the spec template, the source-isolation discipline (no reading under the project's code roots or its benchmark directory, if it has one — its CLAUDE.md project facts), and the per-finding classification rules. This skill file only governs trigger, dispatch, and handoff.

Two scopes: per-cycle and milestone

fieldtest runs at two scopes, both using the same fieldtester agent — the carrier picks the scope:

• Per-cycle fieldtest (the default this file otherwise describes): dispatched after a surface-touching cycle's audit, carrier scoped to that cycle (cycle_id / cycle_scope). Catches cycle-local friction early. Optional / orchestrator judgement, as below.
• Milestone fieldtest: the closing gate for a tracker milestone. Carrier scoped to the milestone's promise (milestone_id / milestone_promise); the fieldtester derives curated end-to-end scenarios top-down from that promise and proves the shipped implementation delivers it. Its green status roll-up is required before a surface-touching milestone may be closed.

Both carriers are defined authoritatively under Carrier contract in agents/fieldtester.md (the milestone variant under its Milestone-scope variant sub-heading). The gate the milestone fieldtest feeds is defined once in ../docs/pipeline.md § Milestone-close gate — not restated here. The milestone fieldtest is skippable on the same terms as the per-cycle one, lifted to milestone level: a milestone whose entire scope is internal (no user-visible surface) is exempt.

When to Use / Skipping

Triggers:

• Orchestrator-dispatched after audit closes cleanly, when the orchestrator believes the iteration is correct and wants a field test. The pre-condition is a clean (or ratified) audit; the trigger is the orchestrator's judgment-call that the iteration is complete.
• A shipped feature is suspected of being awkward in some way the earlier brainstorm could not foresee.
• A user-facing surface change has just landed.

Findings cluster around two shapes — simple bugs (route via debug → implement mini) or catastrophic architecture problems (route via next brainstorm). Friction and spec-gap items are also possible; the routing table below applies in all cases.

Skipping is permitted only for:

• Bug-fix iterations (use debug).
• Tidy iterations whose scope is purely internal cleanup with zero surface impact.
• Iterations whose entire scope is documentation.

Skipping is not permitted for:

• A cycle that introduced or changed surface syntax, schema, effects, API, configuration format, or any user-visible diagnostic.
• A cycle whose commit body or backlog issue claims "users can now do X". fieldtest is the gate that empirically substantiates such claims; an unverified claim is drift.

The Iron Law

THE FIELDTESTER WORKS FROM THE PUBLIC INTERFACE ONLY — NOT FROM THE IMPLEMENTATION SOURCE.
EVERY EXAMPLE IS WRITTEN IN THE PROJECT'S CANONICAL AUTHORING / CONSUMER FORM.
EVERY FRICTION POINT AND BUG IS RECORDED. NONE IS WORKED AROUND.

The first clause is load-bearing: the whole point of the field test is to simulate a downstream consumer who has only the public interface. The agent file enforces this with a hard path allowlist (computed from the project's public interface, if it has one — its CLAUDE.md project facts); the orchestrator must trust that contract and not feed the agent implementation-internal hints in the carrier.

Dispatch

Dispatch fieldtester with the carrier from the Handoff Contract below. The agent picks 2-4 examples (one per axis the cycle touched; fewer loses the signal on variation, more overflows one readable report), implements them as downstream consumers, runs them, classifies findings, and writes the spec. The two artefact kinds part ways at commit: the fixtures are committed as normal code (they are consumer test assets — suggested subject fieldtest: <cycle> — <N> examples, <K> findings), while the fieldtest spec is a git-ignored working file that is never committed.

The fieldtest spec is written after cycle N's audit-close (fieldtest runs only once audit is clean), so N's cycle-close sweep has already run and cannot touch it — it survives naturally as an input to the next cycle's planner. It is shell-rm'd at N+1's audit-close, whose sweep removes every working-tree spec and plan (N+1's own, plus this spent fieldtest spec). The fieldtest- prefix only marks it in the working tree as the next cycle's input; it plays no part in the delete decision (the sweep removes everything present).

Handoff Contract

fieldtest consumes (from orchestrator at cycle close) the carrier fields cycle_id, cycle_scope, axis_hints, and commit_range, defined authoritatively under Carrier contract in agents/fieldtester.md (which also specifies the empty-axis_hints fallback).

fieldtest produces, for the orchestrator, the fields spec_path, examples_added, and findings, defined authoritatively under Output format in agents/fieldtester.md — single-sourced in the agent file, deliberately not restated here so the two files cannot drift.

It additionally reports one skill-level status roll-up — one of clean / friction_found / bugs_found / infra_blocked. This field is owned here (it is not part of the agent's per-run status protocol), so it is defined in this file only.

The orchestrator drives downstream:

• bug → debug (RED-first; GREEN via implement mini-mode)
• friction → next brainstorm or a tidy iteration via planner
• spec_gap → ratify by updating the design ledger (and naming the gap in the closing commit body), or tighten the design ledger
• working → carry-on (worth recording, no follow-up)

fieldtest does NOT self-resolve.

Tracker filing — bundle by default. A fieldtest typically yields more findings than a cycle closes issues (3-5 vs 1-2 in the field evidence on issue #36), so filing each finding as its own issue grows the tracker structurally with every fieldtested cycle. When findings are filed onto the tracker rather than routed inline:

• Consolidate before filing: before creating any new issue, check whether an open issue on the same line of work can carry the scope — absorb via a comment there instead.
• Related friction / spec_gap findings of one fieldtest go into one collective issue, not one issue per finding.
• A real bug keeps its own issue — it is a forward-queue work item. A low-severity bug may wait in the collective issue instead.
• The fieldtester's report stays per-finding — classification is the agent's contract and does not change. Bundling is this orchestrator-side filing rule only. The writes themselves follow ../issue/SKILL.md, as every tracker write does.

When settled single-issue items accumulate anyway, the orchestrator drains them as a harvest sweep — the batch shape defined in ../docs/pipeline.md § Harvest sweep.

Cross-references

• Agent dispatched: agents/fieldtester.md — carries the five-phase process, the Iron Law in operational form, the spec template, the per-finding classification rules, the Common Rationalisations table, and the Red Flags list.
• Upstream gate: ../audit/SKILL.md runs first; fieldtest comes after a clean (or ratified) audit.
• Closing gate it feeds: ../docs/pipeline.md § Milestone-close gate — the milestone fieldtest's green roll-up is the functional leg of that gate.
• Batch drain it feeds: ../docs/pipeline.md § Harvest sweep — the batch shape that drains accumulated settled single-issue items (bundled findings included).
• Cadence ordering: fieldtest runs before ../docwriter/SKILL.md; docwriter happens at a later, longer stability window.
• Downstream targets:
  • ../debug/SKILL.md — for each bug finding
  • ../brainstorm/SKILL.md or ../planner/SKILL.md — for friction and spec_gap findings worth a follow-up iteration