fable-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fable Plan

Turn grounded evidence into an executable change strategy with explicit dependencies, risk boundaries, acceptance proof, and integration ownership.

将已有证据转化为可执行的变更策略，明确依赖关系、风险边界、验收证明和集成责任归属。

Mission

使命

A plan is not a list of files to edit. It is a set of decisions that makes implementation boring enough to execute safely.

The planner should remove architectural uncertainty, expose order constraints, define what "done" means, and separate work only where the pieces can genuinely be reasoned about and verified independently.

计划并非一份待编辑文件清单，而是一组决策，用于让实施过程足够确定，从而能够安全执行。

规划者应消除架构不确定性，揭示顺序约束，定义“完成”的含义；只有当各部分确实能够独立推理和验证时，才应拆分工作。

Activate When

满足以下情况时启用

the task spans multiple files/components or introduces a new contract;
a migration, schema change, public API change, or cross-package refactor is required;
implementation requires sequencing or rollback reasoning;
parallel workers may help but ownership/integration must be designed;
requirements are understood but not yet decomposed into verifiable work.

任务跨越多个文件/组件，或引入新的契约；
需要进行迁移、schema 变更、公共 API 变更或跨 package 重构；
实施过程需要考虑执行顺序或回滚；
并行 Worker 可能有助于推进任务，但必须设计所有权与集成方式；
需求已经明确，但尚未拆分为可验证的工作项。

Do Not Activate When

满足以下情况时不要启用

load-bearing facts are still unknown (
```
fable-discover
```
/
```
fable-research
```
);
the change is truly bounded to one obvious edit with clear acceptance (
```
fable-execute
```
);
the immediate job is to reproduce a behavior in a test (
```
fable-tdd
```
).

关键事实仍不明确（
```
fable-discover
```
/
```
fable-research
```
）；
变更确实仅限于一处显而易见的修改，且验收标准清晰（
```
fable-execute
```
）；
当前任务只是要在测试中复现某种行为（
```
fable-tdd
```
）。

Change Classification

变更分类

Classify before decomposing.

Change type	Main planning concern
Bounded behavior	acceptance and regression surface
Cross-module feature	contracts + integration points
Refactor	invariant preservation + staged compatibility
Data/schema migration	forward/backward compatibility + rollback
Public API/CLI	compatibility + versioning + docs/tests
Dependency upgrade	behavior delta + transitive risk
Security-sensitive	trust boundaries + fail-closed behavior
Release/distribution	artifact boundaries + external verification

在拆分之前先进行分类。

变更类型	主要规划关注点
范围明确的行为变更	验收与回归影响范围
跨模块功能	契约 + 集成点
重构	不变量保持 + 分阶段兼容
数据/schema 迁移	前向/后向兼容 + 回滚
公共 API/CLI	兼容性 + 版本管理 + 文档/测试
依赖升级	行为差异 + 传递性风险
安全敏感变更	信任边界 + fail-closed 行为
发布/分发	产物边界 + 外部验证

Planning Protocol

规划协议

Stage 1 — Restate the contract

阶段 1 — 重述契约

Capture:

requested outcome;
non-goals;
evidence already established;
externally visible behavior that must not regress;
unresolved items and why they are non-blocking.

If a blocking unknown remains, stop and route back to discovery/research.

明确：

要求达成的结果；
非目标；
已确认的证据；
不得回归的外部可见行为；
尚未解决的事项及其不构成阻塞的原因。

如果仍存在阻塞性未知项，请停止并返回探索/研究阶段。

Stage 2 — Map the change graph

阶段 2 — 梳理变更图谱

Identify:

components touched;
contracts between them;
data/state transitions;
migration or compatibility edges;
shared integration hotspots;
generated artifacts and their sources;
verification surfaces.

Represent ordering as dependencies, not just numbered tasks.

识别：

需要改动的组件；
组件之间的契约；
数据/状态转换；
迁移或兼容性关联；
共享集成热点；
生成产物及其来源；
验证范围。

应使用依赖关系表示执行顺序，而不只是给任务编号。

Stage 3 — Choose seams for decomposition

阶段 3 — 选择分解边界

A card should have one coherent reason to change and one clear acceptance story.

Do not require disjoint files as a universal rule. Two cards may touch one integration file sequentially if ownership/order is explicit. Conversely, two cards touching different files may still be unsafe to parallelize if they change one shared invariant or contract.

每个工作卡都应具有单一、内聚的变更原因，以及一条清晰的验收路径。

不要将文件互不重叠作为通用规则。只要所有权和顺序明确，两个工作卡可以依次修改同一个集成文件。反之，两个工作卡即使修改不同文件，只要它们变更了同一个共享不变量或契约，仍可能无法安全并行执行。

Stage 4 — Plan risk-first

阶段 4 — 优先规划风险

Move high-uncertainty or irreversible decisions earlier where possible:

prove migration shape before broad data rewrite;
prove compatibility adapter before deleting legacy path;
prove third-party API contract before wiring all call sites;
introduce observability before risky runtime changes.

尽可能将高不确定性或不可逆的决策提前：

在大规模数据重写前验证迁移方案；
在删除旧路径前验证兼容性适配器；
在连接所有调用点前验证第三方 API 契约；
在进行高风险运行时变更前引入可观测性。

Stage 5 — Define each card

阶段 5 — 定义每个工作卡

Each card must state:

objective and user-visible effect;
owned scope and prohibited scope;
dependencies/preconditions;
implementation notes only where they constrain correctness;
acceptance evidence/commands;
rollback or recovery note when failure is costly;
handoff/integration expectation.

每个工作卡都必须说明：

目标及用户可见的效果；
负责范围和禁止修改范围；
依赖关系/前置条件；
仅在会约束正确性时提供实施说明；
验收证据/命令；
失败代价较高时提供回滚或恢复说明；
交接/集成预期。

Stage 6 — Define integration ownership

阶段 6 — 明确集成责任归属

Name who/what proves the combined result. Worker-local green is not enough for cross-card behavior.

明确由谁或用什么来证明组合后的结果。对于跨工作卡行为，仅凭各 Worker 局部测试通过并不足够。

Stage 7 — Check the plan against failure

阶段 7 — 用失败情形检验计划

Ask:

What if card 2 fails after card 1 lands?
Can old and new formats coexist during migration?
Is any step irreversible?
Does rollback preserve data/contracts?
Are tests capable of detecting the main regression?
Does parallel execution create merge or semantic conflicts?

询问：

如果工作卡 1 已落地，而工作卡 2 失败，会发生什么？
迁移期间旧格式和新格式能否共存？
是否有任何步骤不可逆？
回滚是否能保留数据/契约？
测试能否检测到主要回归？
并行执行是否会造成合并冲突或语义冲突？

Decision Rules

决策规则

Unknown architecture →
```
fable-discover
```
; unknown external contract →
```
fable-research
```
.
Behavior change with a testable contract → route the first implementation card through
```
fable-tdd
```
.
Parallelize only when dependencies, ownership, shared invariants, and integration points make concurrency safe.
Prefer staged compatibility over flag-day replacement when old/new callers or persisted data may coexist.
If a card cannot name falsifiable acceptance evidence, it is not ready.
If planning produces more than roughly 5 tightly interdependent cards, consider milestone boundaries or a different architecture rather than mechanically splitting more.
Generated files belong to the card that changes their source/generator, not as independent manual edits.

架构尚不明确 →
```
fable-discover
```
；外部契约尚不明确 →
```
fable-research
```
。
具有可测试契约的行为变更 → 让首个实施工作卡通过
```
fable-tdd
```
执行。
仅当依赖关系、所有权、共享不变量和集成点确保并发安全时，才并行执行。
当旧/新调用方或持久化数据可能共存时，优先采用分阶段兼容，而不是 flag-day 一次性替换。
如果工作卡无法指出可证伪的验收证据，它就尚未准备好。
如果规划产生约 5 个以上紧密相互依赖的工作卡，应考虑设置里程碑边界或采用不同架构，而不是机械地继续拆分。
生成文件应归入修改其源文件或生成器的工作卡，而不应成为独立的手工修改项。

Invariants

不变量

Every card traces back to a requirement or necessary enabling constraint.
No blocking architectural unknown is hidden inside an execution card.
Acceptance checks prove behavior, not merely file existence.
Integration verification has an owner.
Destructive/irreversible steps have explicit safeguards or rollback reasoning.
Parallelism is justified by dependency analysis, not by file count alone.

每个工作卡都能追溯到某项需求或必要的前置约束。
执行工作卡中不得隐藏阻塞性的架构未知项。
验收检查应证明实际行为，而不只是证明文件存在。
集成验证有明确的负责人。
破坏性/不可逆步骤具有明确的安全措施或回滚论证。
并行执行的合理性由依赖分析支撑，而不是仅由文件数量决定。

Failure Taxonomy

失败分类

Hidden dependency

隐藏依赖

A card unexpectedly requires another component. Update the dependency graph; do not let execution silently broaden scope.

某个工作卡意外需要另一个组件。应更新依赖图，不要让执行过程悄然扩大范围。

False independence

独立性误判

Cards touch disjoint files but share one invariant/contract. Serialize or define a compatibility seam.

工作卡修改的文件互不重叠，却共享同一个不变量/契约。应串行执行，或定义兼容性边界。

Acceptance weakness

验收条件薄弱

A proposed check can pass while behavior is still broken. Strengthen the acceptance condition before execution.

拟议的检查可能通过，但实际行为仍然错误。执行前应强化验收条件。

Migration hazard

迁移隐患

Old/new states can coexist in production but plan assumes atomic cutover. Add compatibility, backfill, or staged rollout.

生产环境中的旧/新状态可能共存，但计划却假设能够原子切换。应增加兼容机制、回填或分阶段发布。

Scope explosion

范围膨胀

A card keeps discovering architectural work. Stop, return to discovery/plan, and redraw boundaries.

执行某个工作卡时不断发现新的架构工作。应停止执行，返回探索/规划阶段，并重新划定边界。

Anti-Patterns

反模式

one card per file;
requiring disjoint files even when sequential integration is safer;
parallelizing based only on "different files";
acceptance such as "tests pass" without naming relevant behavior;
hiding migrations/rollbacks inside implementation prose;
treating documentation/generated output as separate cards when they are part of one behavior change;
producing a long task list with no dependency model;
over-specifying code line-by-line before execution evidence exists.

每个文件对应一个工作卡；
即使顺序集成更安全，仍要求文件互不重叠；
仅凭“文件不同”就决定并行执行；
验收标准仅写“测试通过”，却未指明相关行为；
将迁移/回滚隐藏在实施说明中；
当文档/生成输出属于同一行为变更的一部分时，仍将其视为独立工作卡；
生成一份没有依赖模型的长任务清单；
在尚无执行证据时，逐行过度规定代码。

Work Card Template

工作卡模板

text

Card: <outcome>
Why: <requirement/risk>
Depends on:
Owns:
Must not change:
Behavior/invariant:
Implementation constraints:
Acceptance evidence:
Rollback/recovery:
Integration handoff:
Parallel-safe with:

text

Card: <outcome>
Why: <requirement/risk>
Depends on:
Owns:
Must not change:
Behavior/invariant:
Implementation constraints:
Acceptance evidence:
Rollback/recovery:
Integration handoff:
Parallel-safe with:

Completion Criteria

完成标准

Planning is complete when:

blocking unknowns are gone;
dependency/order constraints are explicit;
cards are coherent and bounded by behavior, not arbitrary file slicing;
each card has falsifiable acceptance evidence;
migration/compatibility/rollback concerns are addressed where relevant;
parallel work, if proposed, has explicit semantic ownership and integration proof.

满足以下条件时，规划即已完成：

阻塞性未知项已消除；
依赖关系/顺序约束已明确；
工作卡内聚且以行为为边界，而不是任意按文件切分；
每个工作卡都有可证伪的验收证据；
在相关场景中已处理迁移/兼容性/回滚问题；
如提出并行工作，其语义所有权和集成证明均已明确。

Progressive Resources

渐进式资源

Deep decomposition guide:

references/risk-and-dependency-decomposition.md

Existing decomposition rules:
```
references/decomposition-rules.md
```
Template:
```
templates/work-card.template.md
```
Example:
```
examples/multi-file-migration-plan.md
```

深度分解指南：

references/risk-and-dependency-decomposition.md

现有分解规则：
```
references/decomposition-rules.md
```
模板：
```
templates/work-card.template.md
```
示例：
```
examples/multi-file-migration-plan.md
```