Back to Details

plan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: plan

Skill: plan

WHAT

WHAT

Purpose và context

目的与上下文

  • Purpose: Biến SPEC đã duyệt thành văn bản mà một kỹ sư giỏi nhưng không biết gì về codebase này, và gu thì đáng ngờ vẫn thi hành đúng. Trong overstack, "kỹ sư" đó thường là một CLI rẻ chạy headless (
    opencode
    / 
    agy
    / 
    kiro
    ): nó không thừa hưởng context nào của phiên chính, không hỏi lại được, và khi gặp chỗ mơ hồ nó sẽ đoán rồi im lặng. Thực đo bài học 250626: brief mỏng → giao hàng ~1/5.
  • Trigger (when to use):
    • SPEC (
      /propose
      ) đã được user duyệt ở cổng, và sắp dispatch task cho agent.
    • Việc nhiều bước, nhiều file, hoặc chia cho ≥2 agent chạy song song.
  • Non-goals: KHÔNG dùng khi chưa có SPEC duyệt (dùng 
    /propose
    trước), và không dùng cho sửa một dòng. Không dùng để thiết kế hay để hỏi yêu cầu (đó là 
    /propose
    ).
  • 目的： 将已批准的 SPEC 转换为一份文本，使一名技术娴熟却完全不了解这个 codebase、且判断力令人怀疑的工程师仍能正确执行。在 overstack 中，这名“工程师”通常是一个低成本运行的 headless CLI（
    opencode
    / 
    agy
    / 
    kiro
    ）：它不会继承主会话的任何 context、无法再次提问，遇到歧义时会猜测后保持沉默。实测教训 250626：brief 过薄 → 交付量仅约为 1/5。
  • 触发条件（何时使用）：
    • SPEC（
      /propose
      ）已由用户在 gate 处批准，且即将向 Agent dispatch Task。
    • 工作涉及多个步骤、多个文件，或需要分给 ≥2 个 Agent 并行执行。
  • 非目标： 未批准 SPEC 时不要使用（先使用 
    /propose
    ），也不要用于修改一行代码。不要用于设计或询问需求（那应使用 
    /propose
    ）。

Mental model

Mental model

Cái gì không nằm trong PLAN thì agent không có. Đó là toàn bộ nguyên lý của skill này.
SPEC đã duyệt (FR-xxx, Global constraints) → scope check → File structure → task tracer bullet (hoặc expand → migrate → contract) → mỗi task: Thoả + Files + Interfaces + Depends + Verify + Steps TDD → self-review → DDMMYY-<tên>-PLAN.md → orca orchestration task-create/dispatch --inject nguyên văn
.
凡是未写入 PLAN 的内容，Agent 就无从得知。这就是本 skill 的全部原则。
已批准的 SPEC（FR-xxx、Global constraints）→ scope check → File structure → tracer-bullet task（或 expand → migrate → contract）→ 每个 task：Thoả（满足）+ Files + Interfaces + Depends + Verify + TDD Steps → self-review → DDMMYY-<tên>-PLAN.md → orca orchestration task-create/dispatch --inject 原文

Input và output contract

输入与输出契约

FieldRequired?Ý nghĩa
InSPEC đã duyệt 
llmwiki/wiki/sources/draft/DDMMYY-<tên>.md
cólấy nguyên 
## Context
, 
## Global constraints
, 
## Plan
, 
## Agent Task Assignment
Out
llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md
cóđúng khuôn PLAN: frontmatter + 
## Origin
+ Global constraints nguyên văn + File structure + các 
### Task N
Outdòng 
wiki/index.md
+ append 
wiki/log.md
cótheo bước 7
Outbáo cáo chỗ vỡ SPECkhi Cổng ngược kích hoạtgom một lần, mỗi chỗ kèm câu SPEC gây ra
字段必填？含义
输入已批准的 SPEC 
llmwiki/wiki/sources/draft/DDMMYY-<tên>.md
是原样获取 
## Context
、
## Global constraints
、
## Plan
、
## Agent Task Assignment
输出
llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md
是严格采用 PLAN 结构：frontmatter + 
## Origin
+ 原样的 Global constraints + File structure + 各个 
### Task N
输出
wiki/index.md
中的一行 + 向 
wiki/log.md
追加内容		是按步骤 7 执行
输出SPEC 断点报告反向 gate 触发时汇总为一次报告，每个断点附上导致问题的 SPEC 原文

Rules và capabilities

Rules 与 capabilities

  • RULE-01 (MUST): PLAN không cần file 
    .html
    — nó là thứ máy đọc. HTML gắn với SPEC (thứ người xem lúc duyệt), do 
    /propose
    sinh. R7 miễn check diagram cho nhánh 
    -PLAN.md
    .
  • RULE-02 (MUST): Đường dẫn file luôn chính xác, kèm dải dòng khi sửa file có sẵn.
  • RULE-03 (MUST): Bước đổi code thì phải có code đầy đủ — không mô tả suông.
  • RULE-04 (MUST): Lệnh chạy chính xác, kèm output mong đợi (agent cần biết thế nào là fail đúng, thế nào là pass).
  • RULE-05 (MUST): DRY, YAGNI, TDD, commit thường xuyên.
  • RULE-06 (MUST): Trong codebase có sẵn: theo pattern đang có. Đừng nhân tiện refactor thứ ngoài task.
  • Capabilities: đọc SPEC + codebase để khai đường dẫn/chữ ký thật; ghi file PLAN + index + log trong wiki; không dispatch khi chưa xong self-review.
  • RULE-01（MUST）：PLAN 不需要 
    .html
    文件——它是供机器读取的。HTML 与 SPEC 关联（供用户审批时查看），由 
    /propose
    生成。对于 
    -PLAN.md
    分支，R7 免除 diagram 检查。
  • RULE-02（MUST）：文件路径必须始终准确；修改现有文件时还要注明行号范围。
  • RULE-03（MUST）：涉及代码变更的步骤必须包含完整代码——不能只作文字描述。
  • RULE-04（MUST）：运行命令必须准确，并附带预期输出（Agent 需要知道怎样才算正确失败、怎样才算正确通过）。
  • RULE-05（MUST）：遵循 DRY、YAGNI、TDD，并频繁 commit。
  • RULE-06（MUST）：在已有 codebase 中工作时，遵循现有 pattern。不要顺手重构 task 之外的内容。
  • Capabilities：读取 SPEC + codebase，以声明真实路径和签名；写入 wiki 中的 PLAN + index + log；self-review 完成前不得 dispatch。

Failure boundaries

Failure boundaries

  • Chưa có SPEC duyệt → cancelled, chuyển 
    /propose
    .
  • Cổng ngược (yêu cầu không quy được về task, mâu thuẫn, phương án bất khả thi, phải bịa hàm/kiểu/file) → blocked: DỪNG, không viết PLAN nửa vời, gom mọi chỗ vỡ báo một lần, quay về 
    /propose
    duyệt lại.
  • Còn placeholder hoặc 
    FR-xxx
    không task nào nhận → failed (R7/R18 chặn), sửa tại chỗ.
  • Sửa một dòng → không dùng skill.
  • 尚无已批准的 SPEC → cancelled，转而使用 
    /propose
    。
  • 反向 gate（需求无法映射到 task、存在矛盾、方案不可行，或必须臆造函数/类型/文件）→ blocked：立即停止，不得编写半成品 PLAN；将所有断点汇总成一次报告，然后返回 
    /propose
    修复并重新审批。
  • 仍有 placeholder，或存在任何 task 都未认领的 
    FR-xxx
    → failed（由 R7/R18 拦截），必须就地修复。
  • 修改一行代码 → 不使用本 skill。

HOW

HOW

Main workflow

Main workflow

StepTypeInputsActionOutputs/exitFailure/next
W01deterministicSPECĐọc SPEC đã duyệt, lấy nguyên các mụcnội dung SPECkhông có SPEC duyệt → dừng, 
/propose
W02judgmentSPECScope checkmột hoặc nhiều PLANnhiều hệ con → tách
W03judgmentSPEC + codebaseVẽ 
## File structure
trước khi chia task		danh sách file + trách nhiệmfile/API không tồn tại → B01
W04judgmentFile structureChia task tracer bullet (hoặc wide refactor)danh sách taskWIDE REFACTOR → B02
W05judgmenttaskViết từng task theo khuôn (đủ Files + Interfaces + Steps)các 
### Task N
phải bịa hàm/kiểu → B01
W06judgmentPLAN nhápSelf-review 3 mắt lưới, sửa tại chỗPLAN sạch—
W07effectPLANGhi file + index + log
DDMMYY-<tên>-PLAN.md
R7/R18 chặn → sửa, ghi lại
W08effectPLANBàn giao: 
task-create
+ 
dispatch --inject
nguyên văn kèm Global constraints		task đã dispatch—
Chi tiết từng bước (nguồn chân lý cho W01–W08):
  1. Đọc SPEC đã duyệt — 
    llmwiki/wiki/sources/draft/DDMMYY-<tên>.md
    . Lấy nguyên: 
    ## Context
    , 
    ## Global constraints
    , 
    ## Plan
    (các dòng 
    - [ ]
    ), 
    ## Agent Task Assignment
    .
  2. Scope check — SPEC ôm nhiều hệ con độc lập → tách thành nhiều PLAN, mỗi PLAN tự nó ra được phần mềm chạy được và test được. Đừng nhồi.
  3. Vẽ 
    ## File structure
    trước khi chia task     — liệt kê mọi file sẽ tạo/sửa và trách nhiệm của từng file (một file một trách nhiệm; file nào đổi cùng nhau thì ở cùng chỗ). Quyết định phân rã bị chốt ở đây, không phải trong lúc code.
  4. Chia task thành TRACER BULLET — mỗi task là một lát cắt DỌC: một lát mỏng xuyên hết các tầng (data → logic → giao diện/CLI), tự nó chạy được và tự chứng minh được, để lại một deliverable test được độc lập. Không phải "lát ngang" kiểu "làm hết tầng data" rồi task sau "làm hết tầng logic" — lát ngang không cái nào chạy được một mình. Setup, config, scaffolding, docs → gộp vào task cần chúng; chỉ tách khi một reviewer có thể bác task này mà vẫn duyệt task kia.
    Ngoại lệ có tên — WIDE REFACTOR (expand → migrate → contract). Một thay đổi cơ học mà blast radius trải khắp codebase — đổi tên một cột, đổi kiểu một symbol dùng chung — thì không lát cắt dọc nào xanh nổi: một chỗ sửa làm hàng nghìn call-site đỏ cùng lúc. Đừng ép nó vào khuôn tracer bullet. Sequence:
    • expand — thêm dạng MỚI cạnh dạng cũ, chưa xoá gì. Một task. Không làm hỏng gì vì dạng cũ vẫn còn.
    • migrate theo lô — dời call-site sang dạng mới, chia lô theo blast radius (per-package, per-directory). Mỗi lô một task, bị chặn bởi task expand. CI xanh từng lô vì dạng cũ vẫn sống.
    • contract — xoá dạng cũ khi không còn caller nào. Một task, bị chặn bởi mọi lô migrate.
    • Khi ngay cả từng lô cũng không tự xanh nổi: cho chúng chung một nhánh tích hợp, tất cả cùng chặn một task "integrate-and-verify" cuối — xanh chỉ được hứa ở đó.
  5. Viết từng task theo khuôn dưới (bắt buộc đủ Files + Interfaces + Steps).
  6. Self-review (3 mắt lưới, mục 'Self-review' bên dưới), sửa tại chỗ.
  7. Ghi file 
    llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md
    , thêm dòng vào 
    llmwiki/wiki/index.md
    , append 
    llmwiki/wiki/log.md
    .
  8. Bàn giao: mỗi 
    ### Task N
    là một 
    orca orchestration task-create
    ; 
    dispatch --inject
    bơm nguyên văn brief của task đó kèm 
    ## Global constraints
    . Không tóm tắt lại — tóm tắt là chỗ context rụng.
StepTypeInputsActionOutputs/exitFailure/next
W01确定性SPEC读取已批准的 SPEC，原样提取各章节SPEC 内容无已批准的 SPEC → 停止，使用 
/propose
W02判断SPECScope check一个或多个 PLAN涉及多个独立子系统 → 拆分
W03判断SPEC + codebase在拆分 task 前绘制 
## File structure
文件列表 + 职责文件/API 不存在 → B01
W04判断File structure拆分 tracer-bullet task（或 wide refactor）task 列表WIDE REFACTOR → B02
W05判断task按模板编写每个 task（包含 Files + Interfaces + Steps）各个 
### Task N
必须臆造函数/类型 → B01
W06判断PLAN 草稿通过 Self-review 三视角复核并就地修复干净的 PLAN—
W07执行PLAN写入文件 + index + log
DDMMYY-<tên>-PLAN.md
R7/R18 拦截 → 修复后重新写入
W08执行PLAN交接：
task-create
+ 
dispatch --inject
原文，并附带 Global constraints		已 dispatch 的 task—
各步骤的详细信息如下（W01–W08 的事实来源）：
  1. 读取已批准的 SPEC — 
    llmwiki/wiki/sources/draft/DDMMYY-<tên>.md
    。原样获取：
    ## Context
    、
    ## Global constraints
    、
    ## Plan
    （所有 
    - [ ]
    行）、
    ## Agent Task Assignment
    。
  2. Scope check — 如果 SPEC 涵盖多个相互独立的子系统 → 拆分为多个 PLAN，每个 PLAN 都必须能够独立产出可运行、可测试的软件。不要把所有内容塞进同一份计划。
  3. 在拆分 task 前绘制 
    ## File structure
     — 列出所有将创建或修改的文件，以及每个文件的职责（一个文件只承担一个职责；若多个文件总是一起修改，则将它们放在同一组）。分解决策在此锁定，而不是编码时临时决定。
  4. 将 task 拆分为 TRACER BULLET — 每个 task 都应是一个纵向切片：一条贯穿所有层（data → logic → 界面/CLI）的薄切片，能够独立运行和自我证明，并留下可独立测试的交付物。不要采用“先把 data 层全部做完，再把 logic 层全部做完”这样的横向切片——横向切片中没有任何一项能单独运行。Setup、config、scaffolding 和 docs 应并入需要它们的 task；只有当 reviewer 可以否决这个 task 但仍批准另一个 task 时，才应拆分。
    具名的例外——WIDE REFACTOR（expand → migrate → contract）。 对于 blast radius 遍布整个 codebase 的机械式变更——例如重命名某一列，或更改共享 symbol 的类型——不存在能够变绿的纵向切片：修改一个位置会同时让数千个 call-site 变红。不要强行套用 tracer-bullet 模板。执行顺序如下：
    • expand — 在旧形式旁添加新形式，暂不删除任何内容。作为一个 task。由于旧形式仍然存在，因此不会破坏任何功能。
    • 按批次 migrate — 将 call-site 迁移到新形式，按 blast radius 分批（例如按 package、按 directory）。每个批次作为一个 task，且依赖于 expand task。由于旧形式仍然存在，每个批次完成后 CI 都保持绿色。
    • contract — 当旧形式不再有任何 caller 时将其删除。作为一个 task，且依赖于所有 migrate 批次。
    • 如果连每个批次也无法独立变绿，则让它们共用一个 integration branch，并将所有批次统一依赖于最后的 
      integrate-and-verify
      task——只在该 task 处承诺变绿。
  5. 按照下方模板编写每个 task（必须完整包含 Files + Interfaces + Steps）。
  6. Self-review（采用下方“Self-review”章节中的三个视角），并就地修复。
  7. 写入文件 
    llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md
    ，向 
    llmwiki/wiki/index.md
    添加一行，并向 
    llmwiki/wiki/log.md
    追加内容。
  8. 交接：每个 
    ### Task N
    都对应一个 
    orca orchestration task-create
    ；
    dispatch --inject
    必须注入该 task brief 的    原文    ，并附带 
    ## Global constraints
    。不要重新总结——总结正是 context 丢失的地方。

Branches

Branches

IDKindGuardHành viSkip / failureRejoin
B01recoveryCổng ngược: một điều kiện DỪNG trong mục Cổng ngược xảy raDỪNG, gom TẤT CẢ chỗ vỡ thành MỘT lần báo, quay về 
/propose
sửa SPEC + duyệt lại		—W01 (sau khi SPEC duyệt lại)
B02conditional_requiredthay đổi cơ học blast radius khắp codebaseWIDE REFACTOR: task expand → các lô migrate (chặn bởi expand) → contract (chặn bởi mọi lô); lô không tự xanh → nhánh tích hợp + task integrate-and-verify—W05
B03conditional_requiredSPEC ôm nhiều hệ con độc lậptách nhiều PLAN, mỗi PLAN tự chạy được + test được—W03 cho từng PLAN
IDKindGuard行为Skip / failureRejoin
B01recovery反向 gate：“反向 gate”章节中的任一停止条件成立立即停止，将所有断点汇总成一次报告，返回 
/propose
修复 SPEC 并重新审批		—W01（SPEC 重新获批后）
B02conditional_required机械式变更的 blast radius 遍布整个 codebaseWIDE REFACTOR：expand task → 若干 migrate 批次（依赖 expand）→ contract task（依赖所有批次）；如果批次无法独立变绿，则使用 integration branch + 
integrate-and-verify
task		—W05
B03conditional_requiredSPEC 涵盖多个相互独立的子系统拆分为多个 PLAN，每个 PLAN 都可独立运行和测试—分别进入 W03

Validation và stopping

Validation 与 stopping

Tất định: R7 chặn placeholder (write-time + commit), R18 chặn 
FR-xxx
không task nào nhận, R9/R2 chặn thiếu frontmatter/
## Origin
; dòng 
**Verify:**
mỗi task là lệnh rc 0. Cần review: Self-review 3 mắt lưới (phủ SPEC, placeholder, nhất quán kiểu/tên). Dừng sau W08, hoặc ngay tại B01.
确定性检查：R7 阻止 placeholder（写入时 + commit 时），R18 阻止没有任何 task 认领的 
FR-xxx
，R9/R2 阻止缺少 frontmatter/
## Origin
；每个 task 的 
**Verify:**
行必须是一条 rc 0 命令。需要复核：Self-review 三视角（覆盖 SPEC、placeholder、类型/命名一致性）。在 W08 后停止，或在 B01 处立即停止。

Examples

Examples

  • Positive: SPEC 
    DDMMYY-export-csv.md
    đã duyệt có FR-001..FR-003 → PLAN 3 task tracer bullet, mỗi task có 
    **Thoả:**
    , 
    **Files:**
    đường dẫn chính xác, 
    **Interfaces:**
    Consumes/Produces, dòng Verify là 
    pytest tests/test_export.py -q
    , Step 1–5 TDD → ghi 
    DDMMYY-export-csv-PLAN.md
    + index + log → dispatch từng task nguyên văn kèm Global constraints.
  • Boundary/failure: khi khai File structure mới phát hiện API mà 
    ## Approaches
    chọn không tồn tại, và FR-002 mâu thuẫn Global constraints → DỪNG, không viết PLAN nửa vời, báo một lần cả hai chỗ kèm câu SPEC gây ra, quay về 
    /propose
    duyệt lại.
  • 正向： 已批准的 SPEC 
    DDMMYY-export-csv.md
    包含 FR-001..FR-003 → PLAN 包含 3 个 tracer-bullet task，每个 task 都有 
    **Thoả:**
    、准确的 
    **Files:**
    路径、
    **Interfaces:**
    Consumes/Produces、作为 rc 0 命令的 Verify 行以及 Step 1–5 TDD → 写入 
    DDMMYY-export-csv-PLAN.md
    + index + log → 将每个 task 原文连同 Global constraints 一并 dispatch。
  • **边界/失败：**在声明 File structure 时才发现 
    ## Approaches
    选择的 API 并不存在，同时 FR-002 与 Global constraints 矛盾 → 立即停止，不得编写半成品 PLAN；将两个断点及导致它们的 SPEC 原文汇总为一次报告，然后返回 
    /propose
    重新审批。

Reference — Khuôn PLAN

Reference — PLAN 模板

Header bắt buộc (frontmatter và 
## Origin
KHÔNG được bỏ — file nằm trong 
wiki/sources/draft/
nên R9 chặn nếu thiếu frontmatter, R2 chặn nếu thiếu 
## Origin
):
markdown
---
type: draft
title: <tên>-PLAN
status: proposed
timestamp: YYYY-MM-DD
task: T-YYMMDD-NN        # cùng task-id với SPEC
---
必需的 Header（frontmatter 和 
## Origin
绝不能省略——该文件位于 
wiki/sources/draft/
，缺少 frontmatter 会被 R9 阻止，缺少 
## Origin
会被 R2 阻止）：
markdown
---
type: draft
title: <tên>-PLAN
status: proposed
timestamp: YYYY-MM-DD
task: T-YYMMDD-NN        # cùng task-id với SPEC
---

<Tên> — PLAN thi hành

<Tên> — PLAN thi hành

Goal: <một câu: cái này xây ra cái gì> Architecture: <2-3 câu: cách tiếp cận> Tech stack: <ngôn ngữ, lib, test runner, version> SPEC nguồn: 
wiki/sources/draft/DDMMYY-<tên>.md
(đã duyệt <ngày>)
Goal: <một câu: cái này xây ra cái gì> Architecture: <2-3 câu: cách tiếp cận> Tech stack: <ngôn ngữ, lib, test runner, version> SPEC nguồn: 
wiki/sources/draft/DDMMYY-<tên>.md
(đã duyệt <ngày>)

Origin

Origin

  • SPEC: 
    wiki/sources/draft/DDMMYY-<tên>.md
  • Commit: (verify-before-commit điền)
  • SPEC: 
    wiki/sources/draft/DDMMYY-<tên>.md
  • Commit: (verify-before-commit điền)

Global constraints

Global constraints

<chép NGUYÊN VĂN từ SPEC — sàn version, giới hạn dependency, luật đặt tên, gate trước push. Mỗi task ngầm mang theo section này.>
<chép NGUYÊN VĂN từ SPEC — sàn version, giới hạn dependency, luật đặt tên, gate trước push. Mỗi task ngầm mang theo section này.>

File structure

File structure

  • Tạo 
    path/chính/xác.py
    — <trách nhiệm duy nhất của file>
  • Sửa 
    path/có/sẵn.py
    — <đổi gì>

Mỗi task:

````markdown
  • Tạo 
    path/chính/xác.py
    — <trách nhiệm duy nhất của file>
  • Sửa 
    path/có/sẵn.py
    — <đổi gì>

每个 task：

````markdown

Task N: <tên>

Task N: <tên>

Thoả: FR-001, FR-003
Files:
  • Tạo: 
    đường/dẫn/chính/xác.py
  • Sửa: 
    đường/dẫn/có/sẵn.py:123-145
  • Test: 
    tests/đường/dẫn/test_x.py
Interfaces:
  • Consumes: <dùng gì từ task trước — chữ ký chính xác>
  • Produces: <task sau dựa vào cái gì — tên hàm, kiểu tham số, kiểu trả về>
Depends: Task 1, Task 3 <!-- task nào phải DONE trước; không có → ghi `—`. `/orca-graph build` đọc dòng này để dựng đồ thị phụ thuộc; thiếu thì nó SUY từ Consumes/Produces và gắn nhãn gợi-ý --> Verify: 
pytest tests/x.py -q
<!-- lệnh rc 0 = task xong thật; thiếu → node chỉ đạt done_unverified -->
  • Step 1: viết test fail
python
def test_hanh_vi_cu_the():
    assert ham(dau_vao) == ket_qua_mong_doi
  • Step 2: chạy cho THẤY nó fail
Chạy: 
pytest tests/đường/dẫn/test_x.py::test_hanh_vi_cu_the -v
Mong đợi: FAIL — 
NameError: name 'ham' is not defined
  • Step 3: code tối thiểu cho pass
python
def ham(dau_vao):
    return ket_qua_mong_doi
  • Step 4: chạy lại — PASS
Chạy: 
pytest tests/đường/dẫn/test_x.py::test_hanh_vi_cu_the -v
Mong đợi: PASS
  • Step 5: commit
bash
git add tests/đường/dẫn/test_x.py src/đường/dẫn/x.py
git commit -m "feat: <việc cụ thể>"

**Vì sao `**Thoả:**` là bắt buộc:** SPEC đánh id ổn định `FR-001`, `FR-002`… cho từng yêu cầu. Mỗi task khai mình gánh id nào → câu "phủ hết SPEC" ở Self-review thôi làm bằng mắt, nó thành **dữ liệu grep được**, và **R18 chặn** nếu có `FR-xxx` nào không task nào nhận (in ra đúng id bị bỏ rơi). Một yêu cầu trôi mất giữa hai task là lỗi thầm lặng nhất của mọi kế hoạch — nó chỉ lộ ra lúc agent giao hàng thiếu, hoặc tệ hơn, lúc user dùng.

**Vì sao `Interfaces` là bắt buộc khi có ≥2 agent:** agent thi hành **chỉ nhìn thấy task của chính nó**. Không khai chữ ký thì hai agent song song đặt tên hàm lệch nhau và phần ghép vỡ — đây là lỗi *chắc chắn* xảy ra, không phải rủi ro.
Thoả: FR-001, FR-003
Files:
  • Tạo: 
    đường/dẫn/chính/xác.py
  • Sửa: 
    đường/dẫn/có/sẵn.py:123-145
  • Test: 
    tests/đường/dẫn/test_x.py
Interfaces:
  • Consumes: <dùng gì từ task trước — chữ ký chính xác>
  • Produces: <task sau dựa vào cái gì — tên hàm, kiểu tham số, kiểu trả về>
Depends: Task 1, Task 3 <!-- task nào phải DONE trước; không có → ghi `—`. `/orca-graph build` đọc dòng này để dựng đồ thị phụ thuộc; thiếu thì nó SUY từ Consumes/Produces và gắn nhãn gợi-ý --> Verify: 
pytest tests/x.py -q
<!-- lệnh rc 0 = task xong thật; thiếu → node chỉ đạt done_unverified -->
  • Step 1: viết test fail
python
def test_hanh_vi_cu_the():
    assert ham(dau_vao) == ket_qua_mong_doi
  • Step 2: chạy cho THẤY nó fail
Chạy: 
pytest tests/đường/dẫn/test_x.py::test_hanh_vi_cu_the -v
Mong đợi: FAIL — 
NameError: name 'ham' is not defined
  • Step 3: code tối thiểu cho pass
python
def ham(dau_vao):
    return ket_qua_mong_doi
  • Step 4: chạy lại — PASS
Chạy: 
pytest tests/đường/dẫn/test_x.py::test_hanh_vi_cu_the -v
Mong đợi: PASS
  • Step 5: commit
bash
git add tests/đường/dẫn/test_x.py src/đường/dẫn/x.py
git commit -m "feat: <việc cụ thể>"

**为什么 `**Thoả:**` 是必填项：** SPEC 为每项需求分配稳定的 id，例如 `FR-001`、`FR-002`。每个 task 声明自己承担哪些 id → Self-review 中的“覆盖全部 SPEC”不再只能靠肉眼检查，而变成**可通过 grep 检索的数据**；**R18 会阻止**任何未被 task 认领的 `FR-xxx`（并准确打印遗漏的 id）。某项需求在两个 task 之间漂移，是所有计划中最隐蔽的错误——它只会在 Agent 交付不完整时暴露，甚至更糟，直到用户实际使用该功能时才会暴露。

**为什么在 ≥2 个 Agent 时 `Interfaces` 是必填项：** 执行中的 Agent **只能看到自己的 task**。如果不声明签名，两个并行 Agent 会各自给函数起不同的名字，最终集成会损坏——这是*必然*发生的错误，而不是风险。

Reference — Cấm placeholder — đây là plan HỎNG, không phải plan chưa xong

Reference — 禁止 placeholder — 这是损坏的 PLAN，不是尚未完成的 PLAN

R7 chặn ở write-time và commit. Không bao giờ viết:
  • TBD
    , 
    TODO
    , "điền sau", "chi tiết sau"
  • "xử lý lỗi phù hợp" / "thêm validation" / "handle edge cases" — nói làm gì, không nói "làm cho phù hợp"
  • "viết test cho phần trên" mà không có code test thật
  • "tương tự Task N" — chép lại code ra. Agent có thể đọc task không theo thứ tự, và mỗi agent chỉ được bơm task của nó.
  • Bước mô tả phải làm gì mà không chỉ làm thế nào (bước đổi code thì bắt buộc có code)
  • Nhắc tới hàm/kiểu/method không được định nghĩa ở bất kỳ task nào
R7 会在写入时和 commit 时阻止这类内容。绝不要写入：
  • TBD
    、
    TODO
    、“điền sau”（意为“稍后填写”）、“chi tiết sau”（意为“细节稍后补充”）
  • “xử lý lỗi phù hợp”（处理合适的错误）/“thêm validation”（添加 validation）/“handle edge cases”（处理边界情况）——必须说明做什么，而不能只说“让它合适”
  • “viết test cho phần trên”（为上面的部分编写测试）却没有真实的 test code
  • “tương tự Task N”（类似于 Task N）——应复制实际代码。Agent 可能不按顺序阅读 task，而且每个 Agent 只会注入自己的 task。
  • 只描述必须做什么，却没有说明如何做（涉及代码变更的步骤必须包含代码）
  • 提及任何未在 task 中定义的函数、类型或 method

Reference — Self-review

Reference — Self-review

Viết xong, soi lại bằng mắt mới — sửa tại chỗ, không cần vòng hai:
  1. Phủ SPEC — lướt từng yêu cầu trong SPEC, chỉ ra được task nào thực hiện nó. Thiếu → thêm task.
  2. Quét placeholder — dò đúng các mẫu ở mục trên.
  3. Nhất quán kiểu/tên — tên hàm, chữ ký, tên field dùng ở task sau có khớp cái định nghĩa ở task trước không? 
    clearLayers()
    ở Task 3 mà 
    clearFullLayers()
    ở Task 7 là một con bug.
写完后，以新的视角重新审视——就地修复，无需第二轮：
  1. 覆盖 SPEC — 逐一检查 SPEC 中的每项需求，指出由哪个 task 负责。如果缺失 → 添加 task。
  2. 扫描 placeholder — 精确检查上述章节列出的模式。
  3. 类型/命名一致性 — 后续 task 使用的函数名、签名和 field 名，是否与前置 task 中的定义一致？Task 3 中是 
    clearLayers()
    ，Task 7 中却是 
    clearFullLayers()
    ，这就是一个 bug。

Reference — Cổng ngược — 
/plan
được quyền BÁC SPEC

Reference — 反向 gate — 
/plan
有权否决 SPEC

Viết PLAN chính là cách phát hiện SPEC sai: tới lúc phải khai đường dẫn file thật và chữ ký hàm thật thì thiết kế bất khả thi mới lòi ra. Nếu cổng duyệt đã cho qua rồi mà giờ mới lòi, nghĩa là user đã duyệt một thứ không xây được — cổng đã hỏng.
DỪNG, không viết tiếp PLAN nửa vời, khi gặp bất kỳ điều nào:
  • Một yêu cầu trong SPEC không quy được về task nào làm được.
  • Hai mục trong SPEC mâu thuẫn nhau, hoặc mâu thuẫn với 
    ## Global constraints
    .
  • Phương án đã chọn ở 
    ## Approaches
    hoá ra bất khả thi (file không tồn tại, API không có, ràng buộc chặn).
  • Phải bịa một hàm/kiểu/file mà SPEC không hề nhắc, để cho plan "chạy được trên giấy".
Xử lý: gom TẤT CẢ chỗ vỡ thành MỘT lần báo (không ngắt user từng phát một), mỗi chỗ kèm đúng câu trong SPEC gây ra nó, rồi quay về 
/propose
sửa SPEC và duyệt lại. Một PLAN viết trên nền SPEC hỏng còn tệ hơn không có PLAN: nó bơm cái sai vào agent với vẻ mặt tự tin, và agent rẻ sẽ thi hành nguyên xi.
编写 PLAN 正是发现 SPEC 错误的方式：只有到必须声明真实文件路径和真实函数签名时，不可行的设计才会暴露。如果审批 gate 已经放行，而此时才发现问题，则意味着用户批准了一个无法构建的东西——审批 gate 已经失效。
遇到以下任何情况时，立即停止，不得继续编写半成品 PLAN：
  • SPEC 中的某项需求无法映射到任何可执行的 task。
  • SPEC 中的两个章节互相矛盾，或与 
    ## Global constraints
    矛盾。
  • ## Approaches
    中选定的方案实际上不可行（文件不存在、API 不存在或约束无法满足）。
  • 为了让计划“在纸面上可运行”，必须臆造 SPEC 中从未提及的函数、类型或文件。
处理方式：将所有断点汇总成一次报告（不要用多次消息逐个打断用户），每个断点附上导致问题的确切 SPEC 原文，然后返回 
/propose
修复 SPEC 并重新审批。建立在损坏 SPEC 上的 PLAN 比没有 PLAN 更糟：它会把错误内容自信地注入 Agent，而廉价的 Agent 会原样执行。