Brummel
0b969838c0
Apply the debug-skill pattern (commits 6410732..de42974) to the remaining skills: the agent file is the single source for each interface field's semantics; the SKILL.md copy is reduced to field names plus a pointer, marking the agent's contract table authoritative. Because SKILL.md loads into orchestrator context and agents/*.md into the subagent's fresh system prompt with no transclusion, duplicated field tables drift apart over time. - brainstorm: carrier (spec_path/iteration_scope) -> grounding-check; the absolute-path requirement now lives only in the agent. - planner: carrier (spec_path/iteration_scope/focus_hint) -> plan-recon, including the mandatory/optional markers and the BLOCKED-on-missing rule SKILL.md had omitted. - fieldtest: carrier + produced fields -> fieldtester; the skill-level `status` roll-up (clean/friction_found/bugs_found/infra_blocked), which is not part of the agent's run-status protocol, stays defined in SKILL.md only. - docwriter: carrier + produced fields -> docwriter agent. - implement: carrier (iter_id scratch-dir/stats/not-a-branch semantics) -> implement-orchestrator; per-task sub-status vocabulary moved into the orchestrator-agent (it runs the loop in a fresh context and could not read SKILL.md at runtime, yet referenced "the sub-status table" by name); task_text_path single-sourced in implementer with spec-reviewer cross-referencing. audit was already the reference implementation (pointers, no restated contracts) and is unchanged. closes #2 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
149 lines
6.1 KiB
Markdown
149 lines
6.1 KiB
Markdown
---
|
|
name: fieldtest
|
|
description: 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 `paths.spec_dir`, 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
|
|
`paths.code_roots` or `paths.bench_dir`), and the per-finding
|
|
classification rules. This skill file only governs trigger,
|
|
dispatch, and handoff.
|
|
|
|
## 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 `paths.public_interface`
|
|
in the profile); 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), implements them as downstream consumers,
|
|
runs them, classifies findings, and writes the spec. All
|
|
artefacts (fixtures + spec) stay in the working tree as
|
|
unstaged changes; the orchestrator commits them after
|
|
reviewing the report (suggested commit subject:
|
|
`fieldtest: <cycle> — <N> examples, <K> findings`).
|
|
|
|
Two to four examples is the right size. One is too few (no
|
|
signal on variation); five is too many for one report to
|
|
stay readable.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
- **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
|