Plan

Intent

Plan breaks multi-step work into documented steps with observable done-checks, estimates as ranges, and risk-driven depth. Use it when work has dependencies or irreversible steps (deploy, migrate, delete, send), success criteria are fuzzy, estimates would be guesses, execution has drifted from a prior plan, a one-shot attempt failed, or the user explicitly asks to plan, scope, break down, or estimate. Skip it for personal time blocking or portfolio management (both live in productivity and projects respectively). The skill decides depth based on irreversibility and scope, not comfort: one irreversible step anywhere forces at least a bullet plan shared with you, even if the work is quick.

Inputs

Local filesystem:

• ~/Clawic/data/plan/ (required): stores active plans, outcomes log, and config. create on first use (see setup.md). if you have data at ~/plan/ or ~/clawic/plan/, move it here.
• ~/Clawic/data/plan/config.yaml (optional): user preferences. defaults apply if absent.
• ~/Clawic/data/plan/active/ (L3+): milestone plans and long-horizon work.
• ~/Clawic/data/plan/outcomes.md (all L2+): append-only log of every plan outcome, streaks, learned per-type defaults.

Configuration (in config.yaml):

• quick_task_minutes (number, default 30): sets L1/L2 boundary. tasks ≤ this can be L1 (think-through, no doc) if reversible; > this triggers L2 (bullet plan).
• plan_artifact (chat | file, default chat): where L2 plans land. chat keeps them inline; file writes to ~/Clawic/data/plan/active/ like L3+.
• always_validate (list, default [migration/, external-send/]): task types where human validation never skips, regardless of success streaks. auto-execute is never proposed for these.
• stale_after_days (number, default 7): plans idle longer than this require re-validation of the riskiest assumption before resuming. 4x this forces full replan.

External integrations (none required):

• plan works entirely offline. no API keys, OAuth, or external service dependencies.

User context:

• prior plan outcome log (learnings on what depth and strategies work for your task types).
• current task description, goal, and any constraints or dependencies.

Procedure

Step 1: Scan for Planning Signals

Read the task. check against the Planning Decision table (see decision points below) for any signal that requires a plan. record which signal(s) fired.

observable output: one or more signals identified, or "no signals, execute directly".

Step 2: Make the Risk Decision

Force the irreversibility question first, before committing to depth. ask: "does this task have any step that cannot be undone or recovered from without cost?" classify each irreversible step (delete, deploy, send, mutation without backup, schema change). if the answer is yes, plan at least L2. if reversible and single deliverable and ≤ quick_task_minutes, L1 is ok (think, no doc). otherwise go to step 3.

observable output: risk classification (reversible | recoverable-at-cost | irreversible), list of irreversible steps if any, depth trigger identified.

Step 3: Determine Plan Depth

cross-reference the highest signal triggered against the Depth Levels table. depth equals the highest single trigger, never an average. if novel task type and high stakes, bump to L4 and require approval before step 1. check outcomes.md for learned per-type defaults (these override the table once evidence accumulates). if estimate ratio is >3x (e.g., 2-8h), propose a spike instead of a plan.

observable output: depth level assigned (L0, L1, L2, L3, or L4), justification (which signal triggered it), reference to any learned default if applied.

Step 4: Sketch the Approach (L2+)

list steps in order. order by information, not convenience: the step most likely to invalidate the whole approach goes as early as dependencies allow. rollback steps (if needed) go before the irreversible step they protect, not after. group >7 steps into milestones; plan only the first milestone in step detail.

for each step, write activity verb + observable done-check. "investigate X" is not a step; "decision doc: X vs Y, pick and document choice" is. check the hidden-steps checklist: rollback, backup, restore-verify, post-change verification, comms, cleanup, monitoring. if a step has no attachable check, convert it to a decision or spike.

observable output: step list (3-7 steps, or milestones), each with observable output named.

Step 5: Identify the Riskiest Assumption

name the single assumption that, if false, invalidates the whole approach. this is usually a dependency, a third-party behavior, a data assumption, or a performance assumption. flag which step tests it first. if that test is not already in the plan, add it or reorder to bring it forward.

observable output: riskiest assumption named (one sentence), step number that tests it.

Step 6: Estimate as a Range (L2+)

provide low and high estimates in the same unit (hours, days, etc.). if high/low ratio exceeds 3x, do not plan; propose a spike instead. name the driver of the high end: "high end fires if we discover X" or "if the API is slow". do not use per-step buffers; the plan-level range is the buffer.

observable output: range (e.g., "3-6h"), high-end driver (e.g., "database is slow"), ratio check (OK if ≤3x, otherwise "spike first").

Step 7: Identify Irreversible Steps and Rollback (L2+)

list which steps are irreversible. for each, write a rollback procedure (itself a tested step, placed before the irreversible step). if rollback is not feasible, name the mitigation (e.g., "no rollback; mitigation: staging test run before production, with approval gate"). test the rollback in a step before crossing the line.

observable output: step numbers of irreversible steps, rollback procedure (or "none" + mitigation), step number that tests rollback.

Step 8: Validate Approval Gate (L3+)

if depth is L3 or L4, or if task type is in always_validate, prepare a specific approval question. not "ready to start?" but something that proves the plan was read and risks understood. example: "approve proceeding to step 3, which tests rollback? or should we spike on recovery windows first?"

observable output: specific approval question (L3+), or "no validation required" (L0-L2).

Step 9: Share the Plan (L2+)

format the plan as:

📋 Plan: [goal]

Why planned: [the signal(s) that triggered planning]

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

Riskiest assumption: [one sentence] ,  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]

[Specific question, not "Ready to start?"]

if plan_artifact is chat, deliver inline. if file, write to ~/Clawic/data/plan/active/[task-slug].md and reference the path.

observable output: formatted plan document or inline message, ready for approval or execution.

Step 10: Execute and Log Deviations (All Depths)

proceed with step 1. after each step, check output against plan. record any deviation (step skipped, reordered, output differs). one deviation is noise. two consecutive deviations trigger immediate replan (do not patch step-by-step). after task completion, append a record to ~/Clawic/data/plan/outcomes.md with: goal, depth assigned, signals triggered, strategy used, outcome (success/failure), deviations observed, and the reason if failure occurred.

observable output: completion status, deviation log, outcome record appended to outcomes.md.

Decision Points

Should I plan or execute directly (L0)?

• If the task is done before successfully, fully reversible, and single deliverable: execute directly. no plan.
• Otherwise, continue.

Is the task short and reversible enough for L1 (think-through, no doc)?

• If all signals point to reversible, single deliverable, and estimated work is ≤ quick_task_minutes: L1 is ok. think through the steps in your head; do not write a plan doc.
• If any irreversible step or dependency exists, or work exceeds quick_task_minutes: skip L1, go to L2+.

Does this task need a bullet plan (L2)?

• If reversible, multi-step or >30 min, or single irreversible step with clear rollback: write and share a bullet plan (3-7 steps with done-checks). approval may not be needed for L2 unless the task type is in always_validate.
• If dependencies span components or work spans >1 day: go to L3 (milestone plan).
• If novel task type and high-stakes: go to L4 (full plan, approve before step 1).

Is the estimate wildly uncertain (ratio >3x)?

• If low-high ratio exceeds 3x (e.g., 1-4h is a 4x spread): the high end is not an estimate, it is an unknown. propose a spike (a small effort to narrow the range) before planning the full task. spikes often take 30 min to a few hours and focus on the driver of uncertainty (e.g., "test API latency under load" or "read the legacy schema").
• If ratio is ≤3x: proceed with the plan.

Does this task type have a learned depth default?

• Check ~/Clawic/data/plan/outcomes.md for the Current Defaults block. if your task type (e.g., refactor/small, migration/data, api/integration) has a logged streak or learned default, apply it instead of the table.
• Example: if refactor/small has logged 7 consecutive successes at L2 with auto-execute waived, start L2 without validation.
• If no entry, use the Depth Levels table.

Should I require approval before starting (L3+)?

• If depth is L3 (milestone plan) or L4 (high-stakes, novel), or if task type is in always_validate, prepare a specific approval gate. the gate is a question that proves the plan was read and risks understood, not a generic "ready to start?"
• If the user says "just do it" or approves instantly, mark approval as covered and proceed.
• If approval is silent (e.g., no response after 1 business day), never cross an irreversible boundary without explicit confirmation. reversible prep is ok; irreversible steps wait.

Do I replan or patch the current plan?

• After each execution step, check output against the plan. one deviation (skipped, reordered, or different output) is expected noise.
• Two consecutive deviations mean the model of the task is wrong. stop, do not continue patching step-by-step. replan the remaining work using the replanning protocol in replanning.md (re-validate riskiest assumption, re-check dependencies, identify what changed).
• If a step is blocked (dependency not met, external wait), use the block protocol in replanning.md (document the blocker, estimate wait time, decide to proceed in parallel or pause).

Should I promote depth after a failure?

• If a task of type T failed because the assigned depth was too shallow to catch the failure, promote the per-type default one level up. document what deeper depth would have caught (specific step, decision, or rollback).
• Example: if api/integration failed at L2 because API rate limits were not tested upfront, promote api/integration to L3 for next time.
• If you cannot name what deeper depth would have caught, the failure was not a planning failure; do not promote.

Should I demote depth after successes?

• If three consecutive L2+ plans of type T completed successfully and the plan sections were never consulted during execution (all sections were speculative), demote one level and propose running the next instance at the lower depth.
• Log the demotion with the streak evidence in outcomes.md.

Should I auto-execute (skip validation)?

• After five consecutive successful validated runs of a plan type, ask the user: "Should I auto-start [type] plans without validation going forward?" one failure resets the streak and restores validation.
• Never auto-execute task types listed in always_validate (e.g., migration/, external-send/), regardless of streaks.
• This removes a human safety net, so the bar is higher than demotion.

How do I resume a stale plan (L3+)?

• If a plan has been idle longer than stale_after_days (default 7), re-validate the riskiest assumption first before resuming. run the test that validates it again; the world may have moved (dependencies, backups, assumptions changed).
• If the plan has been idle longer than 4x stale_after_days (default 28 days), do a full replan instead of resume. too much time has passed to trust the forecast.
• See long-horizon.md for the full resume protocol.

Output Contract

L0 (Execute Directly)

• No output artifact. work proceeds to execution immediately.

L1 (Think-Through, No Doc)

• No output artifact. the thinking happens, no record is kept unless the task later fails (then append a brief outcome to outcomes.md).

L2 (Bullet Plan)

• Format: markdown document, 200-400 words, with sections: goal, why planned (signals), steps (3-7 with done-checks), riskiest assumption, irreversible steps + rollback, estimate range, validation gate or "none".
• Location: if plan_artifact: chat, display inline in conversation. if plan_artifact: file, write to ~/Clawic/data/plan/active/[slug-or-date].md.
• Approval: unless task type is in always_validate, approval is optional for L2. if asked "ready to start?", answer yes/no or request clarification. if approval is required, the plan includes a specific question, not "ok to go?"
• Before sharing: verify riskiest assumption is named, every step has an observable output, irreversible steps have rollback (or "none" + mitigation), estimate ratio is ≤3x, depth matches the highest signal triggered.

L3 (Milestone Plan)

• Format: markdown document, 400-800 words, with sections: goal, context, milestone 1 (steps with done-checks), milestone 2-N (high-level only, detail only for milestone 1), riskiest assumption, irreversible steps + rollback, estimate range by milestone, checkpoints (where you pause to re-validate), approval question.
• Location: write to ~/Clawic/data/plan/active/[slug].md. reference the path in chat.
• Approval: required. the plan includes a specific checkpoint question. approval is conditional on that question being answered clearly. once approved, execution proceeds to the first checkpoint; at each checkpoint, re-validate before crossing to the next milestone.
• Stale check: if resuming after > stale_after_days, re-validate riskiest assumption first (step before milestone 1). if > 4x stale_after_days, full replan instead.

L4 (Full Plan, High-Stakes)

• Format: markdown document, 800-1200 words, with sections: goal, context, assumption map (what could break, how to test), strategy (why this approach over alternatives), steps for milestone 1 (detailed), steps for milestone 2+ (milestones, not steps), riskiest assumption, irreversible steps + rollback (tested first), estimates with calibration history (reference prior tasks of the same type), external dependencies and escalation paths, approval question.
• Location: write to ~/Clawic/data/plan/active/[slug].md.
• Approval: required before step 1. approval response must address the specific question and confirm understanding of riskiest assumption and rollback. no silent approval; if no response, do not start.
• Validation gates: L4 plans often include checkpoints after step 2 or 3 (the first major irreversible step). re-approval may be needed if world has changed.

Outcome Log (All L2+)

• Location: ~/Clawic/data/plan/outcomes.md (append-only).
• Entry format per task:
  • date, goal, depth assigned, signals that triggered it, strategy, outcome (success/failure/blocked), deviations (0/1/2+), reason (if failure or blocked), learned default update (if applicable).
  • Example: "2025-03-15 | Migrate user table | L3 | irreversible + dependencies | sequential | success | 0 deviations | rollback tested step 1, all good | api/migration: promote to L4 on next irreversible schema change."
• Streaks and learning: maintain per-type streak counts (successes, failures, promotion/demotion candidates). review every 10 outcomes or monthly.

Outcome Signal

Plan worked if:

1. **Task completed with zero