feat(fieldtest): bundle findings into collective issues; document the harvest sweep

Encode the tracker-growth practice ratified in the aura field run:

- fieldtest/SKILL.md — tracker filing defaults to bundling: one
  collective issue per fieldtest for related friction/spec_gap
  findings, consolidate-before-filing ahead of ANY new issue,
  per-issue filing only for real bugs (low-severity may wait in
  the collective issue). The fieldtester's per-finding report is
  unchanged; this is an orchestrator-side filing rule.
- docs/pipeline.md — new § Harvest sweep: the recognised batch
  shape for draining settled single-issue backlog (issue bodies
  as spec source, sequential implementer batches of 2-3, one
  non-removable independent whole-diff review, audit close,
  compact fieldtest under its normal skip rules). Registered as
  the specify/planner exception under § Skip rules.
- specify/SKILL.md, planner/SKILL.md — codify the sweep as a
  named alternative / skip case, per "skipping is codified per
  skill, not ad hoc".
- docs/conventions.md — register the noun in § Vocabulary.

closes #36
This commit is contained in:
2026-07-24 20:33:28 +02:00
parent 0951d1f14c
commit b2c92db725
5 changed files with 82 additions and 3 deletions
+1
View File
@@ -104,6 +104,7 @@ The pipeline's nouns are fixed:
| **cycle** | One round in the pipeline graph (`brainstorm → specify → planner → implement → audit → [fieldtest]`). NOT the top-level container. | | **cycle** | One round in the pipeline graph (`brainstorm → specify → planner → implement → audit → [fieldtest]`). NOT the top-level container. |
| **iteration** | A sub-unit of a cycle. | | **iteration** | A sub-unit of a cycle. |
| **milestone** | Tracker container spanning many cycles; closes only when complete AND functional (see `pipeline.md` § Milestone-close gate). | | **milestone** | Tracker container spanning many cycles; closes only when complete AND functional (see `pipeline.md` § Milestone-close gate). |
| **harvest sweep** | Batch shape draining accumulated settled single-issue backlog in one pass (see `pipeline.md` § Harvest sweep). |
| **contract** | A single design-ledger entry. | | **contract** | A single design-ledger entry. |
When a project declares a glossary (in its CLAUDE.md project facts), When a project declares a glossary (in its CLAUDE.md project facts),
+44 -3
View File
@@ -114,6 +114,43 @@ close stays a deliberate human / orchestrator act — the
tracker's own milestone-close action (on Gitea, `tea milestone tracker's own milestone-close action (on Gitea, `tea milestone
close`); no skill performs it automatically. close`); no skill performs it automatically.
## Harvest sweep
A recognised batch shape for draining settled single-issue
backlog. When small, settled items accumulate on the tracker
(bundled fieldtest findings, absorbed leftovers, mechanical
one-offs), one full pipeline cycle per item is structurally
uneconomical; a harvest sweep drains them in one batch:
- the settled issue bodies stand in for spec and plan — each
item is already ratified and bite-sized, so `specify` and
`planner` are skipped by design (the exception is registered
in § Skip rules);
- the implementer works in sequential batches of 2-3 items —
direct `implementer` dispatches (the `implement-loop` carrier
needs a plan the sweep deliberately lacks), with no per-task
review pair; the whole-diff review below replaces it;
- the sweep closes with one **independent diff review over the
whole sweep** — an ad-hoc fresh-context reviewer over the
sweep's full diff, independent of the orchestrator and the
implementers (the per-task reviewer carriers do not fit a
whole-sweep diff) — then the mandatory `audit` close, and one
compact `fieldtest` under its normal skip rules (a
zero-surface sweep skips it).
The whole-diff review is **not removable**. Unlike a planned
cycle, where the task is the unit of review (`planner`'s
decomposition discipline), the sweep amortises review over the
batch — and in the consumer-project sweep this shape was
ratified from (recorded on issue #36), that one review caught
the only substantive error, which originated from orchestrator
+ fieldtest consensus, not from the implementers.
A sweep is orchestrator-decided at queue selection — a
judgement call like the `fieldtest` / `docwriter` dispatches,
not an arm of the selector cascade; the trigger is observed
accumulation of settled single-issue items.
## Phase descriptions ## Phase descriptions
### brainstorm ### brainstorm
@@ -285,11 +322,15 @@ documents what the skill skips and under what conditions:
gate before `planner`. `brainstorm` is the *optional* discovery stage gate before `planner`. `brainstorm` is the *optional* discovery stage
before it: skipped when the design is already settled in the sources before it: skipped when the design is already settled in the sources
(the work enters through `specify` directly), run when a load-bearing (the work enters through `specify` directly), run when a load-bearing
decision is still open. decision is still open. The one batch exception is the harvest sweep
(§ Harvest sweep): its settled issue bodies are the ratified spec
source, so no new spec is written.
- `planner` is never skipped at iteration start, except for the - `planner` is never skipped at iteration start, except for the
side paths that carry no prose plan: the bug-driven side paths that carry no prose plan: the bug-driven
`debug → implement (mini)` path and the `compiler-driven` path `debug → implement (mini)` path, the `compiler-driven` path
(whose "plan" is the type-checker's enumeration of edit sites). (whose "plan" is the type-checker's enumeration of edit sites),
and the harvest sweep (whose items are already bite-sized —
§ Harvest sweep).
- `implement` is the iteration body; not skippable. - `implement` is the iteration body; not skippable.
- `audit` is mandatory at cycle close. - `audit` is mandatory at cycle close.
- `debug` is mandatory RED-first for any observable bug — first in - `debug` is mandatory RED-first for any observable bug — first in
+27
View File
@@ -165,6 +165,30 @@ The orchestrator drives downstream:
`fieldtest` does NOT self-resolve. `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 ## Cross-references
- **Agent dispatched:** `agents/fieldtester.md` — carries the - **Agent dispatched:** `agents/fieldtester.md` — carries the
@@ -176,6 +200,9 @@ The orchestrator drives downstream:
- **Closing gate it feeds:** `../docs/pipeline.md` - **Closing gate it feeds:** `../docs/pipeline.md`
§ Milestone-close gate — the milestone fieldtest's green § Milestone-close gate — the milestone fieldtest's green
roll-up is the functional leg of that gate. 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* - **Cadence ordering:** fieldtest runs *before*
`../docwriter/SKILL.md`; docwriter happens at a later, `../docwriter/SKILL.md`; docwriter happens at a later,
longer stability window. longer stability window.
+5
View File
@@ -46,6 +46,11 @@ May be skipped when:
design path — `brainstorm`, `specify`, and `planner`. design path — `brainstorm`, `specify`, and `planner`.
- The work is a trivial mechanical edit (per the project's - The work is a trivial mechanical edit (per the project's
CLAUDE.md "trivial mechanical edits" carve-out). CLAUDE.md "trivial mechanical edits" carve-out).
- The work is a harvest sweep — settled single-issue backlog
drained as a batch. The settled issue bodies stand in for the
plan, and the per-task review pair is replaced by one
whole-sweep diff review. See `../docs/pipeline.md`
§ Harvest sweep.
**Never skipped** for a standard iteration within an active **Never skipped** for a standard iteration within an active
cycle. "I know the cycle, plan from memory" is exactly the cycle. "I know the cycle, plan from memory" is exactly the
+5
View File
@@ -35,6 +35,8 @@ the decision as a *source* rather than making it inline.
`specify` is a core pipeline node: it is the gate before `planner` on `specify` is a core pipeline node: it is the gate before `planner` on
every design path that is not a bug fix or a test-specifiable feature. every design path that is not a bug fix or a test-specifiable feature.
The side paths that carry no fresh prose design — `compiler-driven`,
the harvest sweep — bypass it (`../docs/pipeline.md` § Skip rules).
Where `tdd` is one entry path among three (chosen when behaviour is Where `tdd` is one entry path among three (chosen when behaviour is
test-specifiable), `specify` sits on every prose-design path — it is test-specifiable), `specify` sits on every prose-design path — it is
not bypassed for those. not bypassed for those.
@@ -59,6 +61,9 @@ Triggers:
- An observed bug — use `debug` directly (RED-first). - An observed bug — use `debug` directly (RED-first).
- A tidy iteration — use `audit` directly. - A tidy iteration — use `audit` directly.
- A trivial mechanical edit — per the project's CLAUDE.md carve-out. - A trivial mechanical edit — per the project's CLAUDE.md carve-out.
- Settled single-issue backlog drained as a batch — the harvest
sweep's issue bodies are the ratified spec source; no new spec is
written. See `../docs/pipeline.md` § Harvest sweep.
**Skipping a gate is never permitted.** The interview is `brainstorm`'s, **Skipping a gate is never permitted.** The interview is `brainstorm`'s,
and its absence here is the whole point — but the *production gates* and its absence here is the whole point — but the *production gates*