Plan

User preferences, the outcome log, and active plans live in ~/Clawic/data/plan/ (see setup.md on first use). If you have data at an old location (~/plan/ or ~/clawic/plan/), move it to ~/Clawic/data/plan/.

When To Use

• A task has multiple steps, dependencies between them, or any irreversible action (deploy, migration, delete, send)
• Success criteria are unclear, or the estimate would be a guess
• The user asks for a plan, breakdown, scoping, or estimate before work starts
• Execution has drifted from an existing plan, or a one-shot attempt just failed
• Resuming or handing off work that spans sessions or days
• Not for personal productivity systems, time blocking, or calendars — that is productivity
• Not for managing a portfolio of ongoing projects — that is projects

Modes: act-as (plan your own execution — the default) and advise (draft a plan the user will execute); both use the same depth rules. Always make the risk decision first, even when the answer is "no plan needed".

Quick Reference

Depth on demand: decomposition.md steps, altitude, done-checks · estimation.md ranges, spikes, calibration · risk.md irreversibility, rollback, blast radius · strategies.md sequential, parallel, iterative, spike, checkpoint · replanning.md deviations, blocks, abandonment · approval.md validation, checkpoints, scope changes · long-horizon.md multi-day, resume, handoff · outcomes.md logging and learning · setup.md first use.

Core Rules

1. A plan's value is the risk decision, not the step list. Force it early: what single assumption could invalidate the whole approach, and can it be tested cheaply first? A to-do list with no risk ordering adds ceremony, not safety (risk.md).
2. Depth = the highest level any single signal triggers, never an average. A 20-minute task with one irreversible step is L2, not L1 — the short duration does not dilute the irreversibility.
3. Irreversibility dominates. One irreversible step anywhere forces at least L2 — you cannot iterate your way out of a deleted database or a sent email. Classification and blast radius in risk.md.
4. Every step carries an observable done-check. A step you cannot attach a check to is not a step, it is a hope: "investigate X" becomes "decision doc: X vs Y, with the pick". Check catalog in decomposition.md.
5. Order by information, not convenience. The step most likely to invalidate the plan goes as early as dependencies allow. Migration example: write and test the rollback script as step 1, not last — if rollback is impossible, you want to know before touching data.
6. Estimates are ranges; ratio >3x means spike first. If the high/low ratio exceeds 3x, that is not an estimate, it is an unknown. 2-8h (4x) → spike; 3-6h (2x) → plan. Building and calibrating ranges in estimation.md.
7. Detail decays past the first unknown. Steps written beyond it are speculation you will rewrite. Plan in steps to the first checkpoint; milestones beyond (long-horizon.md).
8. When uncertain, plan — the cost is asymmetric. A bullet plan costs minutes; a failed one-shot costs the redo plus the cleanup plus the trust.

The Planning Decision

Before executing, scan for signals:

Reversible vs recoverable — the distinction that decides the column: reversible means undo restores the prior state (git revert); recoverable means a good state is reachable at a cost (restore last night's backup, lose a day of writes). Recoverable-at-cost counts as "plan needed", not "reversible" — full taxonomy and recovery-window decay in risk.md.

Plan Depth Levels

Depth = highest single signal (Core Rule 2). Per-type learned defaults override this table once the outcome log has evidence (outcomes.md, Current Defaults).

Plan Format (L2-L4)

📋 Plan: [goal]

Why planned: [the signal that triggered planning — one line]

Steps:
1. [step] — [observable output that proves it is done]
2. [step] — [observable output]
3. [step] — [observable output]

Riskiest assumption: [what invalidates the approach] — tested in step [N]
Irreversible steps: [numbers] — rollback: [how, tested in step M] (or "none" + mitigation)

Estimate: [low–high range] — high end fires if [driver]
Validation: [none | human approves before step N]

[The specific question, not "Ready to start?" — approval.md]

Rules that make the format work:

• 3-7 steps. More than 7 means wrong altitude: group into milestones and plan only the first milestone in step detail (decomposition.md).
• Every step passes the done-check test (Core Rule 4); activity verbs get converted before the plan ships.
• The rollback is itself a step with a check, placed before the irreversible step (risk.md, Rollback Design).
• Scan the hidden-steps checklist — rollback, backup+restore-verify, post-change verification, comms, cleanup, monitoring (decomposition.md, The Steps Nobody Writes).

Executing Against The Plan

• Approval covers what is written. At L3+, a materially different execution needs re-approval, not a retroactive mention — what counts as material is defined in approval.md.
• Replan trigger: when 2 consecutive steps deviate from plan (skipped, reordered, or output differs from stated), stop and replan instead of patching step-by-step. One deviation is noise; two consecutive means the model of the task is wrong. Deviation taxonomy, blocked steps, scope changes, and the replan procedure: replanning.md.
• Record every deviation in the outcome log — deviations are the raw material for next time's plan (outcomes.md).

Learning Loop

Learning rates are asymmetric because evidence costs are asymmetric:

• Promote depth after ONE failure attributable to plan depth — and name what the deeper level would have caught. If you cannot name it, it was not a planning failure and no promotion happens.
• Demote depth after 3 consecutive successes where the extra depth went unused. Observable signal: plan sections never consulted during execution.
• Auto-execute after 5 consecutive successful validated runs of a plan type: ask "Should I auto-start [type] plans without validation?" One failure resets the streak and restores validation. The bar is higher than demotion because this removes a human safety net, not just ceremony. Types in always_validate never auto-execute.

Per-type state lives in the Current Defaults block of ~/Clawic/data/plan/outcomes.md:

### Auto-Execute (validation waived by human)
- refactor/small: L2 [streak: 7]

### Validate First
- migration/data: L4 [always — in always_validate]

### Learning
- api/integration: L2, streak 3/5 toward auto-execute proposal

Logging: append a record after every L2+ task; L0/L1 only when they failed (a failed "trivial" task is evidence the type needs promotion). Strategy verdicts need a why — "Parallel → merge conflicts" teaches; "Parallel → didn't work" does not. Record format, last-5 analysis, and review cadence: outcomes.md.

Output Gates

Before sharing a plan (L2+), verify:

• Riskiest assumption named, with the step number that tests it?
• Every step has an observable output — no bare activity verbs?
• Irreversible steps listed with a tested rollback, or "none" plus a mitigation?
• Estimate is a range with ratio ≤3x — otherwise did I propose a spike instead?
• Depth equals the highest signal triggered, and always_validate types have validation on?
• The closing question is specific enough that its answer proves the plan was read (L3+)?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/plan/config.yaml.

Preference areas to record as the user reveals them:

• thresholds — replan sensitivity, promotion/demotion streak lengths, review cadence — affects Learning Loop and outcomes.md triggers
• format — estimate units, plan verbosity, language of plan docs — affects Plan Format output
• approval — task types the user wants to see planned regardless of size, preferred checkpoint question style — affects approval.md conduct
• scope — domains where the user prefers one-shot execution (bias one level down, irreversibility floor stays) — affects per-type depth defaults

Traps

Where Experts Disagree

• The plan document vs the planning act. "Plans are worthless, planning is everything" (Eisenhower) is half right: the act is always worth it; the artifact pays only at boundaries — human validation, multi-session resume, handoff. Solo reversible work → think, don't write; anything crossing a boundary → write.
• Estimate in time vs relative size. Relative sizing (points) pays only with a stable velocity to convert it — a team asset. An agent's equivalent is the per-type calibration multiplier from its own outcome log; with that log, time ranges are strictly more informative.
• Upfront depth vs iterate-and-see. Iterate when feedback is cheap and steps are reversible; plan upfront when feedback is expensive or steps are irreversible. The depth table IS that frontier — the disagreement dissolves once irreversibility is priced.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/plan (install if the user confirms):

• decide — choose between options inside a plan step
• escalate — ask-vs-act boundaries beyond planning scope
• self-improving — general execution lessons; plan keeps only planning lessons
• memory — long-term context and user continuity beyond planning records
• productivity — personal productivity systems, time blocking, and reviews; plan covers executing a single task

Feedback

• If useful, star it: https://clawic.com/skills/plan
• Latest version: https://clawic.com/skills/plan

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/plan.