mirror of
https://github.com/penpot/penpot.git
synced 2026-11-19 00:20:35 +00:00
📚 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:
parent
e7732541c3
commit
14a623da08
@ -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).
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user