From ae504171f58a9b1c307076f9dc7ad0c55eb472f7 Mon Sep 17 00:00:00 2001 From: Paavo Pokkinen Date: Wed, 16 Sep 2026 10:21:19 +0300 Subject: [PATCH] process: the orchestrator holds the review bound, the packet is finished before the verdict, progress is evidence, and a report names what the store does not yet hold MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A delivery-session retrospective (2026-09-16) found four habits the skills stated only where the wrong reader would see them, or not at all: - rdd-deliver step 4 read "repeat until TODO" with no round bound, while the bound lived only in rdd-cold-review and PROCESS.md — the reviewer's text, not the orchestrator's. The session ran a third round on its own call. The loop now carries the bound and the stop. - rdd-plan step 4 asked that claims be verified by reading the code, but a packet still stated a stale-bound constant from its definition while the agent path applied a different value. A stated value is read at the call site that applies it. - rdd-plan step 7 and rdd-build step 9: a bookkeeping push after the cold-review verdict moved the packet fingerprint twice and voided the review. The packet is finished before the verdict, and build progress is recorded as evidence, never as an edit to the reviewed packet. - rdd-start discipline: the human had to ask "what is not yet in the store?" to learn that two items were being held back. A pass report now names what the session holds that the store does not. No PROCESS.md rule changes; each line applies a rule that already exists. Co-Authored-By: Claude Fable 5.1 --- skills/rdd-build/SKILL.md | 6 +++++- skills/rdd-deliver/SKILL.md | 5 ++++- skills/rdd-plan/SKILL.md | 14 ++++++++++---- skills/rdd-start/SKILL.md | 3 +++ 4 files changed, 22 insertions(+), 6 deletions(-) diff --git a/skills/rdd-build/SKILL.md b/skills/rdd-build/SKILL.md index 52de3ce..96a34f8 100644 --- a/skills/rdd-build/SKILL.md +++ b/skills/rdd-build/SKILL.md @@ -31,7 +31,11 @@ code, tests, and current records. 8. Move the SR to `IN_REVIEW` when its lower trace passes. An affected UR moves to `IN_REVIEW` only when its upper trace passes and every required SR is `IN_REVIEW` or `DONE`. -9. Reconcile the affected graph and derived views. Return remaining approved +9. Reconcile the affected graph and derived views. Progress is recorded as + evidence — a result, a trace, the code and test links on the evidence + record — never as an edit to the reviewed packet's content: a built-at + note or a citation added to a requirement record moves the packet + fingerprint and stales the cold review it passed. Return remaining approved trace failures to `rdd-deliver` for another AI iteration. Hand fully eligible `IN_REVIEW` scope to `rdd-completion-review`; do not deliver or solicit completion here. diff --git a/skills/rdd-deliver/SKILL.md b/skills/rdd-deliver/SKILL.md index dd447da..5b50aab 100644 --- a/skills/rdd-deliver/SKILL.md +++ b/skills/rdd-deliver/SKILL.md @@ -19,7 +19,10 @@ all semantics; this skill owns phase order and continuation. 3. If input is not authoritative or is `DERIVED`, apply `rdd-discover` and its confirmation gate. Continue only with confirmed requirements and relations. 4. Apply `rdd-plan`, then `rdd-cold-review`, then `rdd-entry-review`. Repeat from - the earliest stale or failed pass until the exact selected scope is `TODO`. + the earliest stale or failed pass until the exact selected scope is `TODO`, + inside the review bound: cold review runs at most two rounds on one change, + and a third round is never this loop's call. After a second `FAIL`, stop + and hand what is known to the human (`PROCESS.md` §Planning and readiness). 5. Run the AI TDD inner loop below. Apply `rdd-build` to changed SRs and `rdd-verify` to human-confirmed as-built URs or SRs. Continue until every selected requirement satisfies its applicable trace and is `IN_REVIEW`. diff --git a/skills/rdd-plan/SKILL.md b/skills/rdd-plan/SKILL.md index efbd66e..3a13a15 100644 --- a/skills/rdd-plan/SKILL.md +++ b/skills/rdd-plan/SKILL.md @@ -29,9 +29,11 @@ scope, Item ownership, and Planning and readiness sections of `PROCESS.md`. callers of the module that owns it, and judge each break per call site against the post-change invariants — one file can hold call sites of both kinds. Verify every claim about existing code by reading it at that - revision; a reconnaissance sentence is a citation, not a memory. Keep the - packet within the bound in `PROCESS.md`: a single-requirement packet is at - most one page. + revision; a reconnaissance sentence is a citation, not a memory. A value + the packet states — a limit, a timeout, a constant — is read at the call + site that applies it, not at its definition: a defined value may be unused, + or one of several the code selects between. Keep the packet within the + bound in `PROCESS.md`: a single-requirement packet is at most one page. 5. Enrich every selected SR with its implementation context, explicit change boundary, and lower-RED strategy. Define a separate upper-RED strategy for every selected UR. Every planned RED case must fail today for the stated @@ -44,7 +46,11 @@ scope, Item ownership, and Planning and readiness sections of `PROCESS.md`. trace prerequisites pass. Record blockers, conflicts, gaps, and deferrals rather than guessing. 7. Assemble Entry-packet items 1–6 and the product-language brief. Reconcile - planning records, then hand off to `rdd-cold-review` for item 7. + planning records — every citation, link and note the packet will carry is + in it now — then hand off to `rdd-cold-review` for item 7. Which edits move + the packet fingerprint is decided by the store, not by the editor's intent: + an edit after the verdict is recorded, however small, stales that verdict + and returns the scope to cold review. ## Report diff --git a/skills/rdd-start/SKILL.md b/skills/rdd-start/SKILL.md index 44a3098..b3d07c1 100644 --- a/skills/rdd-start/SKILL.md +++ b/skills/rdd-start/SKILL.md @@ -84,6 +84,9 @@ These rules bind every subsequent phase in the session: Never mutate a shared store to test a hypothesis; - a direction the human has given twice is a decision: record its `USER:` source and proceed on it rather than re-planning around it; +- a pass report names what the session holds that the store does not yet — a + finding not recorded, a note held back, an item left unwritten on purpose — + so the human never has to ask what is not yet in the store; - commit at waypoints — specification, expected RED, GREEN, cleanup, reconciliation — with RED evidence committed before the change that satisfies it, so red-first is auditable in history;