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.

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

Change Classification

Classify before decomposing.

Planning Protocol

Stage 1 — Restate the contract

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

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

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

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.

Stage 5 — Define each card

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

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

Stage 7 — Check the plan against failure

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?

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.

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

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