From 4cde1f31e7c1545a53d8330bde7d5df71f996f8d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 13:14:42 -0800 Subject: [PATCH] guide: checkpoint the design every third review round, brainstorming alternatives Co-Authored-By: Claude Opus 5.5 --- assets/CONTEXT.md | 5 +++-- src/runner/job.ts | 2 +- test/runner.test.ts | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/assets/CONTEXT.md b/assets/CONTEXT.md index d0b99ced..b394f6e4 100644 --- a/assets/CONTEXT.md +++ b/assets/CONTEXT.md @@ -149,8 +149,9 @@ Where it says nothing, only a record on a PR whose author has write access count Checkpoint the design across review rounds. A review round is one `quest review` round, numbered within the branch's review session. -Every fourth round, stop before fixing more findings and reconsider the approach. -Report that judgment and what remains, recommending to continue, rethink the approach, merge as is, or drop the PR, and let the user decide. +Every third round, stop before fixing more findings and reconsider the approach. +Findings that keep coming usually mean the approach is wrong, not the last fix: brainstorm other designs that would avoid the whole class of findings, favoring simpler ones, and compare them with the current one. +Report the alternatives and what remains, recommending to continue, rethink the approach, merge as is, or drop the PR, and let the user decide; a background agent leaves this under `## Waiting` rather than deciding it. Record each design change, including a rethink the user picks, in a PR comment that starts with `Design change:`, and start the next review with `quest review --new`, which restarts the count. Fix every finding relevant to the PR in the PR: review findings you do not refute, gaps the change exposes, and bugs in the code it touches. diff --git a/src/runner/job.ts b/src/runner/job.ts index 89ec8186..9116a8a1 100644 --- a/src/runner/job.ts +++ b/src/runner/job.ts @@ -502,7 +502,7 @@ export class Attempt { } return { passed: false, - note: `The runner's review of ${short} by ${by} found ${round.findings.length} finding${round.findings.length === 1 ? "" : "s"}.${recorded || " kix recorded it as a failing `quest review` check."} Fix each one or refute it with evidence the reviewer cannot rebut (a path:line, a command's output, or a recorded maintainer decision), then call \`deliver\` again with \`responses\` saying what you did for each. Follow the guide's review rules, including its design checkpoint every fourth round.\n\n${formatFindings(round.findings)}`, + note: `The runner's review of ${short} by ${by} found ${round.findings.length} finding${round.findings.length === 1 ? "" : "s"}.${recorded || " kix recorded it as a failing `quest review` check."} Fix each one or refute it with evidence the reviewer cannot rebut (a path:line, a command's output, or a recorded maintainer decision), then call \`deliver\` again with \`responses\` saying what you did for each. Follow the guide's review rules, including its design checkpoint every third round.\n\n${formatFindings(round.findings)}`, }; } diff --git a/test/runner.test.ts b/test/runner.test.ts index d0c24858..f2c08998 100644 --- a/test/runner.test.ts +++ b/test/runner.test.ts @@ -1053,7 +1053,7 @@ describe("prompts", () => { expect(merge).toContain("Where the workflow says to run `quest wait`, call `wait`"); expect(merge).toContain("# The merge workflow"); // The skill's design checkpoint still reaches the maintainer. - expect(merge).toContain("Every fourth round"); + expect(merge).toContain("Every third round"); }); test("carry earlier summaries and the latest answer", () => {