Skip to content

process: the packet is complete before review — state inventory, no new mechanism mid-review, resolutions name their kind - #28

Merged
jussi-modernpath merged 5 commits into
mainfrom
process/packet-complete-before-review
Sep 28, 2026
Merged

jussi-modernpath merged 5 commits into
mainfrom
process/packet-complete-before-review

Conversation

@jussi-modernpath

@jussi-modernpath jussi-modernpath commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Why

Cold review on recent epics ran four to ten rounds (EPIC-ANALYSIS-009: 10, EPIC-CLI-022: 9, EPIC-OBAN-001: 8) although PROCESS.md bounds it at two. The rounds were not wasteful: each one found real problems in the packet. Two causes, from the finding history and the EPIC-ANALYSIS-009 trial on 2026-09-25/26:

  1. The packet never stated the state model the change touches — writers, readers that branch on it, crash mid-write, staleness, recovery — so every round re-derived it and found a different gap.
  2. Findings were resolved by disposition edits that added mechanisms (a retry, a guard, a task link) the packet had never reconnoitred; the next round faulted those. Rounds 3, 4 and 6 on EPIC-ANALYSIS-009 found defects only in mechanisms the previous round's resolutions introduced.

With a state inventory in the packet, rounds 5 to 8 found nothing new about the stated state and only faulted late mechanisms or a row the inventory lacked. The reviewer of round 5 wrote that the inventory turned the review into a diff against a stated set.

The remedy therefore makes the packet complete before review rather than limiting rounds.

What changes

  • PROCESS.md §Entry packet, item 3 — reconnaissance carries a state inventory whenever the change adds or touches persisted or shared state; every mitigation cell ends closed, residual or decided.
  • PROCESS.md §Planning and readiness — a packet is complete before its review starts: a row the inventory lacks is a finding, a cell closed with "backlog" while a criterion asserts it is a finding, a mechanism the packet does not name is not part of the change. A RESOLVED disposition names its kind (packet edit, scope action with its record, decision with its USER: source). No new mechanism enters a packet during a review cycle; a finding whose fix needs one is a scope question. A round whose material findings fall on mechanisms an earlier resolution introduced is evidence the packet was reviewed incomplete.
  • rdd-plan step 4 — how to write the inventory (join rows as much as entities) and the self-audit against it before handoff. A value the packet states is read at the call site that applies it, not at its definition — taken from PR 22 (@paveq), the one hunk there that raises packet completeness rather than managing rounds. Step 7 — a mechanism a review needs later goes back through scope and reconnaissance, never into the packet.
  • rdd-cold-review step 2 — enumerate the inventory's cells and the transitions between concurrent writers in both directions; a missing inventory on a state-touching change is the first material finding. Step 6 — the three resolution kinds; a resolution that adds a criterion, widens a boundary or adds a hop is a scope question returned to rdd-plan. Report — name the findings that fall on late mechanisms.

Not changed

The two-round paragraph in PROCESS.md and rdd-cold-review step 8 stay as they are; this PR adds no caps. rdd-deliver, rdd-build, rdd-start and file-state/ are untouched.

Relation to earlier PRs

Supersedes #13 (closed 2026-09-26) and #22. From #13 it keeps the idea that a finding introduced by a remediation is a distinct fact, as prose in the report rather than a classification enum, and leaves out the plan-subject fingerprint, coverage rubric, continuation gates and CRF- records. From #22 it keeps the call-site rule only.

The CLI half — a required resolution kind on process findings disposition, a per-round widening count in process findings list, and a plan-phase check for the inventory section — is a separate epic in modernpath-v1 (BACKLOG-TOOL-218).

Validation

  • git diff --check
  • node --check skills/rdd-audit/audit-citations.mjs
  • node skills/rdd-audit/audit-citations.mjs PROCESS.md file-state README.md (no citations in these documents, as before)

🤖 Generated with Claude Code

2026-09-27 — after the first trial (modernpath-v1 EPIC-CLI-027, two cold-review rounds): four rules added. Reconnaissance starts from the ledger (the delivered requirement that owns each touched surface, its acceptance carried as a constraint); generated system documentation is read before the code and cited; an inventory row lists each write shape it admits; a resolution edit re-enters reconnaissance for what it names and a reviewer's proposed fix is a claim. Each would have caught one of the round-2 findings.

2026-09-28 — after EPIC-CLI-027 was built and its pull request reviewed: two rules added. A review of the built change is not a round of the packet's review: it runs from its own independent context and numbers its own rounds, outside the packet's round history and the two-round bound, and an open material finding on it stops delivery (rdd-completion-review step 2 now names it). A RESOLVED finding on the change names the commit that resolved it, a fourth kind beside the three, and the commit only brings the code to what the approved change already contained. A migration or a schema change is production and lands with the GREEN it serves (PROCESS.md RED paragraph, rdd-plan step 5). The CLI half — the commit kind and a review context for built work — is filed in modernpath-v1 as BACKLOG-TOOL-274 and BACKLOG-TOOL-279.

…ew mechanism mid-review, resolutions name their kind

Cold review rounds on recent epics ran four to ten deep because the packet
never stated its state model, so every round re-derived it, and because
findings were resolved by adding mechanisms the packet had not reconnoitred,
which the next round then faulted. The trial on EPIC-ANALYSIS-009
(2026-09-25/26): before a state inventory, rounds one to four re-derived the
model; with it, later rounds found nothing new about the stated state and
only faulted mechanisms added during review.

- PROCESS.md: entry-packet item 3 carries a state inventory whenever the
  change touches persisted or shared state; a packet is complete before its
  review starts; a RESOLVED disposition names its kind, and no new mechanism
  enters a packet during a review cycle.
- rdd-plan: how to write the inventory and self-audit against it; a value the
  packet states is read at the call site that applies it (from PR 22); a
  mechanism a review needs later returns through scope and reconnaissance.
- rdd-cold-review: enumerate the inventory's cells and writer transitions; a
  missing inventory on a state-touching change is the first material finding;
  the three resolution kinds; report findings that fall on late mechanisms.

Supersedes PR 13 and PR 22. Source: BACKLOG-TOOL-218.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@jussi-modernpath
jussi-modernpath force-pushed the process/packet-complete-before-review branch from 8cc7731 to e9ff7b2 Compare September 27, 2026 11:04
…nventory; a resolution edit re-enters reconnaissance

Found on the first trial of this text (modernpath-v1 EPIC-CLI-027, two
cold-review rounds): a delivered requirement's acceptance the change
contradicted surfaced only in round 2; a fix the reviewer proposed was
adopted without reading the symbol it named; test names were added without
the command that runs them. Four rules: the packet names the delivered
requirement that owns each touched surface and carries its acceptance as a
constraint; generated system documentation is read before the code and
cited; an inventory row lists each write shape it admits; a resolution edit
re-enters reconnaissance for what it names, and a reviewer's proposed fix
is a claim.
…es its answer

Found on the EPIC-CLI-027 trial: a review finding whose fix preserved a
delivered acceptance was put to the owner as a decision, bundled with
bookkeeping and written in record ids, and the owner could not tell what
was being asked. The rule: a question is put only when no rule, record or
earlier answer already implies it; what remains is one plain sentence about
what changes for the product, and bookkeeping is never bundled with it.
@jussi-modernpath
jussi-modernpath force-pushed the process/packet-complete-before-review branch from 8a59a02 to f9343a1 Compare September 27, 2026 20:07
…ound by searching the records

Found on the EPIC-CLI-027 and EPIC-CLI-028 trials. The packets carried the
shell commands and -run patterns that would run each RED case, and the third
review round blocked on the pattern's regex syntax; each round a reviewer
found a gap in that detail and the author added more of it. The rule: a RED
strategy names the test file, the behaviour the case asserts and why it fails
at the revision, and no command, pattern or test name — the command is
evidence at the RED commit, where running it is the verification; a review
finding about such a line is a note that the line is dropped.

Both trials also missed a delivered owner of a touched surface that a search
of the records for the touched verb found at once. The rule: the ledger sweep
is a search of the records for every verb, symbol and path the change
touches, and an owner recalled rather than found is a surprise for review.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
pasilastbot added a commit that referenced this pull request Sep 28, 2026
…nge lane

Brings the seven packet-complete rules into the lane branch so one
process revision carries both. The small change keeps its four-field
packet: its SR record is its complete packet, it carries no state
inventory (the lane's excluded areas keep persisted and shared state out),
and its ledger search covers the files its boundary names
(USER:2026-09-28, Pasi: "go ahead with combining").

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…es by a commit; a migration lands at GREEN

Found building EPIC-CLI-027 on its reviewed packet. Its pull-request review
produced a finding fixed by a code change, which fits none of the three
resolution kinds, and its four notes were recorded in the packet's last
review round, because nothing said a review of the built change is a
different review. Read literally, the two-round bound forbade that review.
The rule: a review of the built change runs from its own independent
context and numbers its own rounds, outside the packet's round history and
the two-round bound; an open material finding on it stops delivery; and a
RESOLVED finding on the change names the commit, which only brings the code
to what the approved change already contained.

The same packet planned its migration into the first RED commit, and the
RED commit gate refused it. The rule: a migration or a schema change is
production and lands with the GREEN it serves; a case that needs it fails
at the revision because it is absent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jussi-modernpath
jussi-modernpath merged commit dc1eb83 into main Sep 28, 2026
pasilastbot added a commit that referenced this pull request Sep 29, 2026
#30's wording is kept everywhere it rewrote #28 (owner's choice,
USER:2026-09-29); the lane adds only its own lines on top.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant