plan

Bon Plan

Express your thinking as a bon hierarchy instead of a plan file.

Why this exists: Plan files are orphans. Written once, never synthesized, never updated. understanding.md has /open and /close maintaining it every session. Bon items have tracking, persistence, tactical steps. This skill channels planning into artifacts that are already alive.

What it replaces: Plan mode. Don't call EnterPlanMode — stay in normal conversation mode where writing to understanding.md and creating bon items is natural behavior, not a format conversion.

When to Use

• Multi-session work: features, refactors, new components
• Work that needs handoff to a future Claude
• When you'd normally reach for EnterPlanMode

When NOT to Use

• Quick exploration before a small fix — just read and work
• Single-session tasks — create a bon action directly, or just do it
• Research or investigation — explore first, plan when direction is clear

---

The Calvino Principle

In Calvino's If on a winter's night a traveller, the chapter titles read as a continuous story. The Table of Contents IS a narrative.

Your outcomes work the same way. Read them in sequence — they should tell the implementation story:

1. A shared Yjs document serves a CodeMirror editor
2. Claude reads and edits the document as a Yjs peer
3. Documents are markdown files on disk, not CRDT blobs
4. Comments are a standalone messaging layer
5. Documents export cleanly to Google Docs

Each title is a clause in the story. Each outcome expands into actions with rich --how. The narrative lives in the sequence; the detail lives in the chapters.

---

Phases

Phase 1: Orient

Read the terrain. Same exploration you'd do in plan mode, without entering the mode.

1. Read .bon/understanding.md — the project's soul
2. Read CLAUDE.md — the manual
3. Explore the codebase: relevant source files, tests, existing patterns
4. Run bon list — what work already exists?

Take your time. Planning quality depends on understanding what's already here.

Phase 2: Frame

Seed understanding.md with the architectural context that applies across all outcomes. This is where cross-cutting concerns live — the content that would have been Context, Approach, Gotchas, and Scope in a plan file.

Write to understanding.md:

• Architectural decisions and rationale
• Key technical constraints discovered during orientation
• Scope boundaries — what we're NOT building
• Gotchas from existing code or dependencies
• Patterns to follow or avoid

The sorting question: Does it apply to multiple outcomes? → understanding.md. Does it apply to one action? → that action's --how.

Present the understanding.md update to the user before proceeding.

Phase 3: Narrate

Create outcomes whose titles, read in sequence, tell the implementation story.

For each outcome:

• Title: Achievement language. What's true when this chapter is complete.
• --why: Why this chapter exists in the story.
• --how: Strategy and approach at the outcome level.
• --what: What will be true when achieved.
• --done: Verifiable completion criteria.
• --order: Sequence position in the narrative.

The narrative test: Read all outcome titles in order. Ask the user: "does this read as a story?" Reorder or reword until it does.

Create outcomes sequentially, not in parallel.

Phase 4: Detail

Create actions under each outcome. Each action is a chapter opening — rich enough that a cold-start Claude can pick it up and execute.

For each action:

• --why: Why this action matters for its parent outcome.
• --how: Implementation detail. Reference code patterns by file:line rather than pasting snippets — living references over stale snapshots. Include pitfalls, things to avoid, specific APIs. This is where execution quality lives.
• --what: Numbered steps (these become tactical steps via bon work).
• --done: How to verify completion.
• --order: Sequence within the outcome.

Set waiting_for where real dependencies exist, not just ordering preference.

The self-containment test: For each action, ask: could a Claude with only this brief and understanding.md execute this? If not, the --how needs more detail.

Phase 5: Verify

Present the full hierarchy (capture bon list to a file and Read it). Three checks:

1. The Calvino test: Read outcome titles in sequence. Does it narrate?
2. The cold-start test: Pick the hardest action. Could a fresh Claude execute it from the brief + understanding.md alone?
3. The frame test: Does understanding.md cover everything cross-cutting?

Iterate until the user is satisfied. The hierarchy IS the plan — there's nothing else to write.

---

What Goes Where

Content type	Home	Example
Architecture decisions	understanding.md	"Y.Text not Y.XmlFragment because..."
Cross-cutting constraints	understanding.md	"Don't import Combine anywhere"
Gotchas from spikes	understanding.md	"StickyIndex constructor doesn't work"
Scope boundaries	understanding.md	"Not multi-user beyond Sameer + Claude"
Implementation strategy	Outcome --how	"Redis distributed locks, not file locks"
Per-step approach	Action --how	"Mirror Injector.swift:89-108 pattern"
Deliverables	Action --what	"1. Add middleware 2. Configure limits"
Completion criteria	Action --done	"P99 < 500ms at 500 RPS for 10 min"
The story	Outcome titles in order	Table of Outcomes

---

Quick Corrections

About to do this	Do this instead
Call EnterPlanMode	Stay in normal mode, follow these phases
Write a plan file	Frame → understanding.md, work → bons
Paste code blocks in --how	Reference by file:line
Create one large outcome	Multiple outcomes that narrate a sequence
Skip --how on actions	--how is where execution quality lives
Put cross-cutting context on one action	Put it in understanding.md