📚 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
This commit is contained in:
Andrey Antukh 2026-11-18 18:41:50 +00:00
parent e7732541c3
commit 14a623da08
6 changed files with 73 additions and 76 deletions

View File

@ -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).

View File

@ -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.

View File

@ -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

View File

@ -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,

View File

@ -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

View File

@ -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.