plan-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Check a Dev Plan

检查开发计划

What To Check

检查内容

$ARGUMENTS

names the plan to check. It may be a single ticket file or a whole plan folder. Read

docs/agents/issue-tracker.md

for where plans live and what the files look like. If

$ARGUMENTS

is empty or matches nothing there, ask the user which plan to check before you start.

Read the whole plan first —

spec.md

, then the tickets in

01-

02-

order. Every check below is judged against the current code, so open the files and classes the tickets name as you go.

$ARGUMENTS

指定要检查的计划。它可以是单个工单文件，也可以是整个计划文件夹。读取

docs/agents/issue-tracker.md

，了解计划的存放位置以及文件格式。如果

$ARGUMENTS

为空，或在其中没有匹配项，请在开始前询问用户要检查哪个计划。

先完整读取整个计划——先读

spec.md

，再按

01-

、

02-

的顺序读取工单。下面的每项检查都要根据当前代码进行判断，因此请在检查过程中打开工单中提到的文件和类。

Run Flow

执行流程

1. Check the risk

1. 检查风险

Could the changes in the plan break a feature that already works?
Are there missing edge cases or missing error handling?
Are there hidden risks in speed or safety?
Drift: do the files, classes, and namespaces in each ticket's Files touched really exist in the current code, and do they still look the way the ticket says?

计划中的改动会不会破坏已经可用的功能？
是否遗漏了边界情况或错误处理？
在执行速度或安全性方面是否存在隐患？
Drift（漂移）：每个工单的 Files touched 中提到的文件、类和 namespace 是否确实存在于当前代码中，并且其状态是否仍与工单描述一致？

2. Check that it is runnable

2. 检查可执行性

A runnable plan can be handed to

plan-run

and done as written, with nothing left to decide.

Does each ticket hold all four parts — what to build, check items, files touched, run steps — plus its
```
Blocked by
```
and
```
Status
```
lines?
Are the check items there, and can each one really be tested?
```
plan-run
```
starts its tests from them, so a ticket without them cannot be run.
Can each run step be done as written — the action, the tech detail, and the wanted result all specific enough to act on right away?
Open items: does the plan still carry "option A/B", "suggest XXX", "may consider", or any other undecided wording? A plan is made to be run, not to be talked over. Settle each one in step 6.
Does the plan describe the work in prose only? A code block in a ticket is a finding — ask for it to be written back as prose.
Where it fits, does the plan use PHP Attribute and Laravel Attribute in place of the old way?
Does
```
spec.md
```
carry a file path or a class name anywhere? Paths belong in Files touched and nowhere else.
Is the folder and every file named the way
```
issue-tracker.md
```
says, with zero-padded numbers?

可执行的计划应当可以原样交给

plan-run

并完成，不留下任何需要决定的事项。

每个工单是否都包含全部四个部分——构建内容（what to build）、检查项（check items）、涉及文件（files touched）、运行步骤（run steps）——以及
```
Blocked by
```
和
```
Status
```
行？
检查项是否齐全，而且每一项是否真的都能测试？
```
plan-run
```
会从这些检查项开始执行测试，因此没有检查项的工单无法运行。
每个运行步骤是否可以按原文执行——操作、技术细节和期望结果是否都具体到可以立即动手？
未决事项（Open items）：计划中是否仍有 “option A/B”、“suggest XXX”、“may consider” 或其他尚未决定的措辞？计划是用来执行的，不是用来讨论的。请在步骤 6 中逐一确定。
计划是否仅以文字描述工作？工单中出现代码块就是一个问题——应要求将其改写为文字说明。
在适用场景中，计划是否使用 PHP Attribute 和 Laravel Attribute 代替旧做法？
```
spec.md
```
中是否在任何位置包含文件路径或类名？路径只能出现在 Files touched 中，不能出现在其他地方。
文件夹及其中每个文件的命名是否都符合
```
issue-tracker.md
```
的规定，并使用零填充数字？

3. Check the slicing

3. 检查切片方式

The tickets should be tracer bullets — thin slices that each prove the whole path works.

Is each ticket a vertical slice through every layer, or a horizontal slice of one layer?
```
01-migration
```
,
```
02-model
```
,
```
03-controller
```
is the shape to catch.
Is each ticket demoable or verifiable on its own?
Does any ticket hold more than one fresh context window of work? Ask for it to be split, and set the blocking edges again.
Does every
```
Blocked by
```
entry really gate the ticket, or is it just the order someone imagined? A blocker that does not gate costs parallel work.
Is any blocking edge missing — a ticket that would land red because something it needs has not been built yet?
Is a wide refactor hiding inside a ticket? A mechanical change with a wide blast radius cannot land green as one slice; ask for it to be sequenced as expand–contract.

工单应当是 tracer bullets——每一片都很精简，并能证明完整路径可行。

每个工单都是贯穿各层的纵向切片，还是只覆盖某一层的横向切片？类似
```
01-migration
```
、
```
02-model
```
、
```
03-controller
```
的结构需要警惕。
每个工单是否都可以独立演示或验证？
某个工单的工作量是否超过一个全新 context window 所能承载的范围？如果是，要求将其拆分，并重新设置阻塞关系。
每个
```
Blocked by
```
条目是否确实会阻塞该工单，还是仅仅体现了某种想象中的顺序？不能形成实际阻塞的依赖会妨碍并行工作。
是否遗漏了阻塞关系——某个工单是否会因为所需内容尚未实现而落地即失败？
是否有大范围重构（wide refactor）隐藏在工单中？影响范围很广的机械式修改无法作为一个切片单独以绿色状态落地；应要求按照 expand–contract 的方式安排实施顺序。

4. Check the SOLID/IoC rules

4. 检查 SOLID/IoC 规则

Call the

solid-check

skill for this part, so the design rules live in one place.

Pull out every class, namespace, or file path the plan will touch, and pass them to
```
solid-check
```
as its scope. If the plan touches scopes that are far apart, call it once for each scope.
If the plan makes a class that is not in the code yet, pass the closest parent namespace or folder, and judge the planned design by the same rules.
Paste the report that comes back into section 4 of your own report, as it came.
A break here is a plan edit: fold the fix into the ticket. The code stays untouched until
```
plan-run
```
.

Done when: every ticket in scope carries an explicit verdict on all four checks, and every class or path the plan names has been looked up in the current code. A check you did not mention is a check you did not run.

这一部分应调用

solid-check

skill，让设计规则集中维护在同一处。

提取计划将要涉及的所有类、namespace 或文件路径，并将它们作为 scope 传给
```
solid-check
```
。如果计划涉及相距较远的多个 scope，则每个 scope 分别调用一次。
如果计划会创建当前代码中尚不存在的类，则传入最接近的父 namespace 或文件夹，并按照相同规则评判计划中的设计。
将返回的报告原样粘贴到你自己报告的第 4 节中。
这里发现的问题意味着需要修改计划：将修复内容并入工单。在
```
plan-run
```
之前不要改动代码。

完成标准：范围内的每个工单都要对四项检查给出明确结论，并且计划提到的每个类或路径都已在当前代码中查找过。没有提及的检查，就等于没有执行。

5. Make a report, then set the status

5. 生成报告，然后设置状态

Scope: the tickets you checked, in the plan order.
One section per check — risk, runnable, slicing, SOLID/IoC — each listing
- Where it is: the ticket plus the step it sits in, and the code path it clashes with
- What is wrong, and which way to change the ticket
Status: write the
```
Status:
```
line of each ticket, using the state machine in
```
issue-tracker.md
```
.
- ```
ready-for-agent
```
  — can be handed to
```
plan-run
```
  as written
- ```
needs-info
```
  — waiting on the user to settle something in step 6
- ```
needs-triage
```
  — must be rewritten before it runs
- ```
ready-for-human
```
  — sound, but an agent should not run it: it needs judgment, external access, or manual testing

范围：按计划顺序列出检查过的工单。
每项检查单独一节——风险、可执行性、切片、SOLID/IoC——每节列出：
- 问题所在位置——对应工单及其所在步骤，以及发生冲突的代码路径
- 问题是什么，以及应如何修改工单
状态：按照
```
issue-tracker.md
```
中的状态机，写入每个工单的
```
Status:
```
行。
- ```
ready-for-agent
```
  ——可以原样交给
```
plan-run
```
  执行
- ```
needs-info
```
  ——等待用户在步骤 6 中确定某项内容
- ```
needs-triage
```
  ——运行前必须重写
- ```
ready-for-human
```
  ——方案合理，但不应由 Agent 执行：需要人工判断、外部访问权限或手动测试

6. Settle the open items

6. 确定未决事项

Every open item steps 1-4 turned up — vague, undecided, or at odds with the current code — is settled with the user here, before the plan is handed back.

Call the
```
grilling
```
skill and walk through each open item, one question at a time, until you both hold the same understanding.
Call the
```
domain-modeling
```
skill while you grill. Put each settled term into
```
CONTEXT.md
```
, and record a hard-to-undo decision as an ADR under
```
docs/adr/
```
.
Write the answers back into the ticket, then move its
```
Status:
```
line if the verdict changed.

Done when: every ticket is left with clear run steps, no open items, and a

Status:

line that matches what you found.

步骤 1～4 发现的每个未决事项——无论表述模糊、尚未决定，还是与当前代码不一致——都要在这里与用户共同确定，之后才能将计划交回。

调用
```
grilling
```
skill，每次只讨论一个未决事项并提出一个问题，直到双方理解一致。
在 grilling 过程中调用
```
domain-modeling
```
skill。将每个已确定的术语写入
```
CONTEXT.md
```
；对于难以撤销的决策，在
```
docs/adr/
```
下记录为 ADR。
将答案写回工单；如果结论发生变化，再调整其
```
Status:
```
行。

完成标准：每个工单最终都应具备清晰的运行步骤、不再包含未决事项，并且

Status:

行与检查结果一致。