diff --git a/docs/conventions.md b/docs/conventions.md index 4232f8d..276935d 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -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. | | **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). | +| **harvest sweep** | Batch shape draining accumulated settled single-issue backlog in one pass (see `pipeline.md` § Harvest sweep). | | **contract** | A single design-ledger entry. | When a project declares a glossary (in its CLAUDE.md project facts), diff --git a/docs/pipeline.md b/docs/pipeline.md index 7d9f2ac..6738ccf 100644 --- a/docs/pipeline.md +++ b/docs/pipeline.md @@ -114,6 +114,43 @@ close stays a deliberate human / orchestrator act — the tracker's own milestone-close action (on Gitea, `tea milestone 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 ### brainstorm @@ -285,11 +322,15 @@ documents what the skill skips and under what conditions: gate before `planner`. `brainstorm` is the *optional* discovery stage before it: skipped when the design is already settled in the sources (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 side paths that carry no prose plan: the bug-driven - `debug → implement (mini)` path and the `compiler-driven` path - (whose "plan" is the type-checker's enumeration of edit sites). + `debug → implement (mini)` path, the `compiler-driven` path + (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. - `audit` is mandatory at cycle close. - `debug` is mandatory RED-first for any observable bug — first in diff --git a/fieldtest/SKILL.md b/fieldtest/SKILL.md index 1b0e381..85d18c7 100644 --- a/fieldtest/SKILL.md +++ b/fieldtest/SKILL.md @@ -165,6 +165,30 @@ The orchestrator drives downstream: `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 @@ -176,6 +200,9 @@ The orchestrator drives downstream: - **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. diff --git a/planner/SKILL.md b/planner/SKILL.md index 8dc7c8f..c381d62 100644 --- a/planner/SKILL.md +++ b/planner/SKILL.md @@ -46,6 +46,11 @@ May be skipped when: design path — `brainstorm`, `specify`, and `planner`. - The work is a trivial mechanical edit (per the project's 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 cycle. "I know the cycle, plan from memory" is exactly the diff --git a/specify/SKILL.md b/specify/SKILL.md index 9868729..f270bae 100644 --- a/specify/SKILL.md +++ b/specify/SKILL.md @@ -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 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 test-specifiable), `specify` sits on every prose-design path — it is not bypassed for those. @@ -59,6 +61,9 @@ Triggers: - An observed bug — use `debug` directly (RED-first). - A tidy iteration — use `audit` directly. - 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, and its absence here is the whole point — but the *production gates*