Skip to content

Review procedures: severity, delta re-review, defer criteria (closes #3795) - #3806

Merged
malibio merged 2 commits into
mainfrom
issue-3795-review-proportionality
Oct 13, 2026
Merged

malibio merged 2 commits into
mainfrom
issue-3795-review-proportionality

Conversation

@malibio

@malibio malibio commented Oct 13, 2026

Copy link
Copy Markdown
Collaborator

Reviewing a Task gains a third pass over the change itself (security, performance, simplification), severity per finding with a principle line, suggestions recorded as non-checkbox text nodes (no decision, no hold on review), delta re-review, and defer needing a size note. Addressing Review Findings ends with a re-review note (behaviour-changing findings, recommended depth). No Play change: a suggestion is not a checkbox opening with Finding. ADR-092 rows already describe this.

Tests: new workflow_seeds test; agent crate and test:changed pass. eval:tasks not run here (needs the model).

🤖 Generated with Claude Code

@malibio

malibio commented Oct 13, 2026

Copy link
Copy Markdown
Collaborator Author

Code Review: PR #3806 (Initial Review)

Requirements Check (issue #3795)

  • ✅ Finding states severity and one-line principle (finding rules, agent and skill-md; step 8)
  • ✅ Suggestion-tier finding is a non-checkbox text node, needs no decision, no Play change needed (verified: core_plays.rs:519/525 match only - [ ] Finding ( / - [x] Finding (; covered by the new integration test)
  • ✅ Third pass (security, performance, simplification) with source change, kept apart
  • 🟡 Delta re-review scoped to commits since last review and names met findings: present, but the anchor is fragile (see below)
  • ✅ Addressing step 5 writes a re-review note with depth; task still returns to in_review
  • ✅ defer requires size note; fix-now criteria stated
  • ❌ ADR-092 rows and seeded-nodes.md: not in this PR (companion nodespace-docs edit still owed; issue lists it as an AC)
  • ❌ Confusion matrix / eval:tasks: not run (needs live model; acknowledged)
  • ➖ quality:fix: not verifiable from diff

Findings

🟡 Important reviewing-a-task.md (delta re-review / STEP 9): the re-review anchor is "the title of the last commit you reviewed through". Commit titles are not unique and do not survive amend or rebase, which is exactly what happens to branches in this repo's queue. Principle: use a stable identifier. Record the commit SHA (plus title for humans). Also, the implementer already records commits via task-implement-links; say the reviewer reads "commits recorded after" the SHA.

🟡 Important addressing-review-findings.md STEP 5 / reviewing-a-task.md delta paragraph: the implementer's re-review note is "a text node directly under the issue" with no distinguishing prefix, and the reviewer's outcome note is also a plain text node. The reviewer is told to find "the implementer's note under the task" with nothing to find it by. Principle: make the contract explicit. Give it an opening like Re-review note ( (mirroring Suggestion () and reference it in the reviewer paragraph. Same applies to identifying "a review note of an earlier round".

🟡 Important Rule variants: task-review-decide and task-review-note (agent and skill-md) are unchanged and do not mention the defer size note or the last-reviewed-commit requirement; the finding rule gains severity but the decide rule's Reason: <why> is the only place a size note lands. Consider changing the decide rule to Reason: <why> plus size <small|medium|large> so the format is mechanical and checkable, rather than prose-only in the skill. The skill-md variant is otherwise coherent with the agent variant (suggestion text creation is generic node create --type text, fine).

🟢 Nit Suggestions are recorded as text with no rule include, so the model-facing command for creating one exists only as prose in step 8. Acceptable, but a one-line rule would make the two variants symmetrical.

🟢 Nit STEP 8 is long (record + severity + dedupe + suggestion + decide). Splitting "suggestions" into its own short paragraph would help the small local model that follows these procedures.

🟢 Nit Test: the defer reason ("size small, but needs its own investigation") contradicts the new fix-now rule only superficially; fine, but "size medium" would model the intended case better and avoid teaching the contradiction.

Checked and fine

  • Step renumbering 1-10 is consistent; no external references to old step numbers found.
  • Size: reviewing-a-task.md 7097 bytes, addressing 3552, well under caps. No golden/snapshot contains the changed text, so no regeneration is evident.
  • Attribution lines updated as a source of ideas, not a licence line, as specified.
  • New test asserts the right thing: a suggestion does not block, a severity-bearing finding still does.

Recommendation

COMMENT (leaning APPROVE after the two anchor/prefix improvements). No blockers; the core design (suggestion as non-checkbox text, no Play change) is sound. Before merge: land the nodespace-docs ADR-092 / seeded-nodes.md edit and run eval:tasks / skill-retrieval matrix, both required by the issue's acceptance criteria.

@malibio malibio left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pragmatic review verdict: COMMENT (no blockers; see the full report in the comment above). Remaining: stable commit anchor, prefix for the re-review note, docs rows, eval:tasks.

@malibio

malibio commented Oct 13, 2026

Copy link
Copy Markdown
Collaborator Author

Addressed: re-review anchor is now the commit hash (Review note prefix); implementer note opens with 'Re-review note ('; defer reason must open with 'size small|medium|large' in both rule variants and both skills; test uses size medium. Skipped: splitting STEP 8 and a Suggestion rule include (marginal; wording kept in the skill). Docs: ADR-092 rows and seeded-nodes.md in nodespace-docs main already describe these procedures, so no docs edit was needed. eval:tasks / retrieval matrix need a live model and were not run.

🤖 Generated with Claude Code

malibio and others added 2 commits October 13, 2026 23:46
…d defer criteria (closes #3795)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…er reason

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@malibio
malibio force-pushed the issue-3795-review-proportionality branch from d1bbeaa to d3bdf2e Compare October 13, 2026 21:46
@malibio
malibio merged commit 374aaee into main Oct 13, 2026
@malibio
malibio deleted the issue-3795-review-proportionality branch October 13, 2026 21:47
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