From 14a623da08e77c90b186fed112af6c716dd0de98 Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Wed, 18 Nov 2026 18:41:50 +0000 Subject: [PATCH] :books: Apply plan review improvements automatically Apply clear review improvements to the plan and resolve consequential decisions through the walkthrough before updating the plan metadata. AI-assisted-by: gpt-6.1-terra --- .agents/README.md | 10 +- .agents/skills/make-a-plan/SKILL.md | 9 +- .agents/skills/plan-review-criteria/SKILL.md | 7 ++ .agents/skills/planner/SKILL.md | 10 +- .agents/skills/review-code/SKILL.md | 3 +- .agents/skills/review-plan/SKILL.md | 110 +++++++++---------- 6 files changed, 73 insertions(+), 76 deletions(-) diff --git a/.agents/README.md b/.agents/README.md index 1741c8e12f..05722cff38 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -346,8 +346,9 @@ small. To delegate without switching models, delegate to `general`. `@make-a-plan delegate to @engineer-glm`. 3. **Iterate on the plan.** The plan is saved to `.agents/plans/`, so you never depend on LLM memory: read the file directly, or invoke `@review-plan` - for a second opinion (delegation works here too). Complex plans deserve a - review; simple ones can skip it. + for a second opinion (delegation works here too). It applies clear plan + improvements and discusses consequential decisions one by one before + applying them. Complex plans deserve a review; simple ones can skip it. 4. **Execute.** Invoke `@implement-plan`. It first prints the full picture — whether it will create an issue and a branch, the execution style, and a task checklist — and waits for your go-ahead. Say "step by step" to stop @@ -405,9 +406,8 @@ Every plan carries `Status: draft | reviewed | done` plus an append-only `Review Log` (UTC ISO 8601, one line per entry): - `draft` — fresh from `@make-a-plan`. -- `reviewed` — review feedback incorporated. `@review-plan` stays - read-only; only your explicit "apply" makes `@make-a-plan` apply - the changes, flip the status, and log one line. +- `reviewed` — review feedback incorporated. `@review-plan` applies clear + improvements and agreed decisions, then updates the status and log. - `done` — `@implement-plan` closes it on completion, logging the issue URL when one exists (never commit hashes). diff --git a/.agents/skills/make-a-plan/SKILL.md b/.agents/skills/make-a-plan/SKILL.md index 3c549d272a..7a46cd9261 100644 --- a/.agents/skills/make-a-plan/SKILL.md +++ b/.agents/skills/make-a-plan/SKILL.md @@ -24,11 +24,10 @@ stop — this skill needs the build agent to save the plan. `@review-code` findings on committed work), write a new derived plan file instead — never rewrite the executed plan. The `planner` skill defines the derived naming (`--review-NN`, `--task-NN`). -- The user says to apply `review-plan` findings to a still-unimplemented - plan: apply the agreed changes, flip `Status` to `reviewed`, and - append one UTC ISO 8601 line to `Review Log` describing what changed. - This apply step is the only pre-implementation write to those fields — - `review-plan` itself stays read-only and never writes. +- The user says to apply additional review feedback to a still-unimplemented + plan: apply the agreed changes, flip `Status` to `reviewed`, and append one + UTC ISO 8601 line to `Review Log`. `review-plan` can also update the plan + and its metadata as part of its own review flow. Do not use it to execute a plan — that is the `implement-plan` flow. diff --git a/.agents/skills/plan-review-criteria/SKILL.md b/.agents/skills/plan-review-criteria/SKILL.md index 649bd1118f..8b75cde394 100644 --- a/.agents/skills/plan-review-criteria/SKILL.md +++ b/.agents/skills/plan-review-criteria/SKILL.md @@ -11,6 +11,13 @@ Multi-dimensional plan review with quality gates. Every plan gets reviewed befor **The approval standard:** Approve a plan when it is specific enough that a skilled implementer could execute it without guessing, the task ordering is sound, and risks are acknowledged. Perfect plans don't exist — the goal is confidence that implementation won't derail. Don't block a plan because it isn't exactly how you would have structured it. If it's executable and well-organized, approve it. +In the `review-plan` flow, apply clear improvements within the plan's existing +goal, scope and decisions. Flag consequential choices for the user instead of +choosing them. Report applied changes and unresolved decisions with evidence, +options and a recommendation; the parent conducts the walkthrough. Recheck the +plan after answers are applied and never approve while required decisions or +changes remain unresolved. Only the plan file may be edited. + ## When to Use - The reviewer subagent of the `review-plan` flow loads this skill to perform diff --git a/.agents/skills/planner/SKILL.md b/.agents/skills/planner/SKILL.md index c57cafa383..7059189596 100644 --- a/.agents/skills/planner/SKILL.md +++ b/.agents/skills/planner/SKILL.md @@ -223,16 +223,16 @@ Review Log: log. `reviewed` never means "a review was emitted" — it means "review feedback was incorporated". A plan approved with no changes goes `draft` → `done` without passing through `reviewed`. -- Only a user-triggered apply step writes them before implementation: - when the user says to apply `review-plan` findings, `make-a-plan` - applies the changes, flips to `reviewed`, and appends one UTC - ISO 8601 line describing what changed. +- Before implementation, `review-plan` applies clear review feedback and + agreed decisions, flips to `reviewed` and appends one UTC ISO 8601 entry + when the plan changed. `make-a-plan` can also do this for additional + feedback when the user asks. - `implement-plan` flips to `done` on completion and appends one line with the issue URL when one exists (standalone mode); otherwise just `done`. Never record commit hashes — they rot on amend/rebase and git already links the commit. - The log is append-only: never rewrite or delete lines. -- `review-plan` and `review-code` never write these fields. +- `review-code` never writes these fields. Omit empty sections only when they do not apply. Every implementation task still requires acceptance criteria, verification, dependencies, likely files, diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index f67c40537d..f09f084a6c 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -51,7 +51,8 @@ Act as a senior software engineer and perform a thorough code review. - **Substantive findings:** suggest `@make-a-plan` to make a plan to address them. - If the user wants to discuss findings one by one, use `@issue-walkthrough` - on request; do not start it automatically. + on request; do not start it automatically. The walkthrough returns its + decisions to `@make-a-plan`, not to automatic code editing. ### Follow-up after implementation diff --git a/.agents/skills/review-plan/SKILL.md b/.agents/skills/review-plan/SKILL.md index c286eeded0..b4beb20641 100644 --- a/.agents/skills/review-plan/SKILL.md +++ b/.agents/skills/review-plan/SKILL.md @@ -1,70 +1,60 @@ --- name: review-plan -description: Plan review flow — evaluate an implementation plan before it is executed, delegating the review to a subagent that follows the plan-review-criteria skill. Use it when the user asks to review a plan, in any phrasing. +description: Review an implementation plan with a subagent, apply clear improvements and resolve consequential decisions with the user. slash: true --- # Review Plan -Act as a senior software engineer and perform a thorough review of an -implementation plan. +Review an unimplemented plan with a subagent and improve the plan without +implementing it. Use this flow when the user asks for a plan review or invokes +`@review-plan`. -## When to use +## Flow -- The user asks to review a plan, in any phrasing: "review this plan", - "does this plan look right?", "second opinion on the plan" — or invokes - `@review-plan`. -- A plan was just produced (typically by `@make-a-plan`) and the user - wants it evaluated before executing it. +1. Identify and read the complete plan and its file. If the target or path is + ambiguous, ask. If no saved file exists, ask for a path or have the user save + it first. Do not edit a completed plan: propose a derived plan instead. +2. Delegate to `general`, unless the user specifies a different subagent or + model. Supply the plan path, relevant session context and these instructions: + - Load `plan-review-criteria`, read `AGENTS.md` and the relevant module and + testing memories, and review the plan against the criteria. + - Apply clear, evidence-based improvements directly to that plan file only. + Preserve the goal, scope, agreed decisions and intended behavior. Examples: + clarify tasks, add missing tests, correct dependencies and specify actual + verification commands. Do not guess commands or invent findings. + - A change that affects the goal, user-visible behavior, scope, tradeoffs or + an existing decision needs the user's decision. Leave it unresolved; report + concrete options, consequences and a recommendation. Do not ask questions + from the subagent. + - Return a concise summary of applied changes, remaining decisions with + stable IDs, evidence and recommendations, and an honest provisional + verdict. Retain the subagent session ID for follow-up if available. + - Do not change source files, other plans or documents, run state-changing + checks, commit, or implement the plan. If the plan is not writable, report + this and return the proposed edits instead. +3. Show the summary. If decisions remain, start `@issue-walkthrough` immediately + in the parent session with those questions and their IDs. Follow its one + question per turn and read-only rules. Do not ask questions that the code or + existing decisions settle. Wait for every answer. +4. Resume the same subagent with the decision table and plan path. It applies + the decisions to the plan, rechecks consistency and reports changes and any + newly discovered consequential decisions. Repeat the walkthrough for new + decisions, then apply those answers. If the original session cannot be + resumed, tell the user and apply the changes in the parent or delegate a new + subagent with the full context. If the reviewer cannot write, apply its + proposed edits in the parent only if the plan file is writable; otherwise + explain the blocker and stop. +5. Once all decisions are resolved and the plan is coherent, update its + metadata: when review feedback changed the plan, set `Status: reviewed` and + append one UTC ISO 8601 `Review Log` entry for this review, summarizing the + changes. Preserve prior log entries. If no feedback changed the plan, leave + status and log unchanged. Never record commit hashes. If decisions or + required changes remain unresolved, do not claim the plan is ready or mark + it reviewed. +6. Show the final summary, plan path and verdict. Suggest `@implement-plan` only + when the plan is ready. Never execute the plan automatically. -## Instructions - -1. **Determine the plan under review** from the session context (for example, a - plan just produced by `@make-a-plan`) or from a plan file path given by the - user (typically under `.agents/plans/`). If a file path is given, read the - file first so the complete plan is in context. -2. Delegate the review to the `general` subagent (via the task tool), unless the - user specifies another agent. Include in the prompt the - **`plan-review-criteria`** skill name and all user context. -3. When the subagent returns, output the review to the user verbatim. Do not - summarize it and do not act on its findings. -4. Right after the review, suggest the next step based on the verdict. These - are suggestions — the user decides, and any instruction overrides them: - - **Approve** → suggest `@implement-plan` to execute it. - - **Request changes** → suggest `@make-a-plan` to make a plan to address the - findings. - -### Hard rule — read-only while reviewing - -This flow is read-only **for the duration of the review**: from the moment it -starts until the user considers the review finished (including any feedback, -questions, or clarifications about it). During that period, never fix, -implement, edit files or create commits — not even "obvious" fixes derived from -the findings. Once the user explicitly states the review is done (or moves on to -a different task), this rule no longer applies and you act as a normal build -agent again. - -## Instructions for the subagent - -1. Load the **`plan-review-criteria`** skill and follow its process and output - format. -2. Read `AGENTS.md` (if present) and follow its instructions for finding and - reading all related documentation and testing memories before reviewing. -3. Return in your final message the COMPLETE review, verbatim, exactly as the - skill instructs it to be produced. Do not summarize it — include the full - structured review. - -### Strong rules for the subagent - -1. Do not invent problems. Every finding must be real and actionable. -2. Read-only: do not modify any file and do not create a commit — reviewing - never writes. -3. Be specific and constructive. "This could be better" is not helpful — explain - why and how. -4. Prioritize by impact. One structural issue outweighs ten nits. -5. Judge the plan as the implementer would: every task executable without - guessing, ordering follows the dependency graph, risks named. - -## User input, overrides and additional context - -$ARGUMENTS +The only permitted write in this flow is the specified local plan file, +including its status and log. Do not stage or commit it. If a user instruction +overrides automatic editing, respect it and report findings without editing.