# Planning

> Creates and updates structured plan documents with agent-verified execution strategy. Use when establishing an implementation plan after a discussion, or when breaking work into steps before ticketing. Invoke with /planning "topic" to create, or /planning P001 to update. Not for direct execution — create tickets first.

- Skill: `zipperbagcoffee/planning` (Agent Skill)
- Install (CLI): `npx skillmds add zipperbagcoffee/planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zipperbagcoffee/planning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ZipperBagCoffee (https://skillmd.com/u/zipperbagcoffee)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/zipperbagcoffee/planning

---


# Plan Document Skill

## Modes

- **Create mode:** `/planning "title"` — creates a new plan document
- **Update mode:** `/planning P001` — appends a log entry to an existing plan

---

## Create Mode

When argument is a title string (not a P-prefixed ID):

### Step 1: Ensure folder exists

Check if `.crabshell/plan/` exists.

- **Folder does not exist:** Create it and create `.crabshell/plan/INDEX.md` with content below.
- **Folder exists but INDEX.md does NOT exist:** Pre-existing files detected. Create `.crabshell/plan/backup/`, move ALL existing files into it, then create INDEX.md. Report to user: "Moved N existing files to .crabshell/plan/backup/"
- **Folder exists and INDEX.md exists:** Already managed. Proceed.

INDEX.md content:
```
# Plan Index

| ID | Title | Status | Created | Related | Tickets |
|----|-------|--------|---------|---------|---------|
```

### Step 2: Determine next ID

Glob `.crabshell/plan/P*.md` (exclude files matching `P\d{3}_T` pattern to avoid tickets in wrong folder).
Extract numeric part. Next ID = max + 1, zero-padded to 3 digits.
If no files exist, start at 001.

### Step 3: Create plan document

Ask the user:
1. **Intent:** What is this plan's purpose? What are the success conditions?
2. **Scope:** What's included / excluded?
3. **Plan steps:** What are the high-level steps?
4. **Verification criteria:** How do we know the plan succeeded? (Observable behavior, not "file contains X")

Then create `.crabshell/plan/P{NNN}-{slug}.md`:

```
---
type: plan
id: P{NNN}
title: "{title}"
status: draft
created: {YYYY-MM-DD}
tags: []
---

# P{NNN} - {title}

## Intent
{user's answer}

## Scope
Included: {included}
Excluded: {excluded}

## Plan
- [ ] Step 1: {step}
- [ ] Step 2: {step}
...

## Plan Execution

The parent owns plan analysis, intent fidelity, and approval. Delegation is optional and bounded by independent value or material risk.

### Step A: Parent — Analysis + Plan Writing
- Analyze related code/system
- **Scope Note (from project RULES):** Conciseness applies to communication style, not to verification steps. P/O/G tables and evidence citations are required work product, not verbose output. Evidence IS the answer — "verified" without tool output is not verification. Fill Prediction before looking; fill Observation only from tool output.
- Identify dependencies and impact scope
- Write concrete execution plan
- **Document-first rule:** Write analysis results to `## Analysis Results` in the P document FIRST using Write/Edit tool. After the document is updated, provide a brief summary to the user. The document update is the primary output; the conversation summary is secondary.

### Step B: Optional Independent Review — Risk Based
- Use independent review only when scope, shared contracts, security, data loss, or user-visible risk warrants it. Reviewer count never follows worker count.
- **Independence Protocol:** When review is used, the prompt MUST NOT include prior conclusions as its observation source. Provide only: (1) Plan Intent, Scope, and Verification Criteria, (2) the P/O/G template below. The parent later cross-references findings against direct evidence.
- Verify completeness and accuracy of the plan
- **Scope Note (from project RULES):** Conciseness applies to communication style, not to verification steps. P/O/G tables and evidence citations are required work product, not verbose output. Evidence IS the answer — "verified" without tool output is not verification. Fill Prediction before looking; fill Observation only from tool output.
- Review feasibility against codebase reality
- Identify risks and missing items
- **Review output MUST use Prediction/Observation/Gap format:**
  ```
  For each plan element, provide ALL THREE fields:
  | Plan Element | Prediction (from Intent + Scope) | Observation (from independent analysis) | Gap |
  |-------------|-------------------------------|-----------------------------------|-----|

  Rules:
  - Prediction: derive from Intent and Scope — what SHOULD the plan address?
  - Observation: independently verify — read the relevant code/system, trace dependencies
  - Gap: where Prediction ≠ Observation, this is a finding. If Gap is always "none", you are confirming, not reviewing.
  - Evidence MUST be cited (file path, function name, specific observation from reading the code)
  ```
- **Document-first rule:** Write review results to `## Review Results` in the P document FIRST using Write/Edit tool. After the document is updated, provide a brief summary to the user. The document update is the primary output; the conversation summary is secondary.

### Step C: Parent — Intent Check (Critical Evaluation)
- Compare against D document's Intent Anchor (IA)
- Confirm plan has not deviated from original intent
- Verify plan coherence: do the plan steps work together as a whole? Individual steps may each be sound, but combined they may have ordering issues, dependency conflicts, or scope gaps. The plan must be coherent as a system, not just individually valid steps.
  **Coherence verification methods (minimum 2 of the following):**
  - **Cross-file sync check:** When the same concept appears across planned target files, grep for the concept and confirm consistent wording/semantics.
  - **Reference integrity:** When plan steps reference content across files, verify the reference targets will hold after changes.
  - **Contradiction scan:** Check for conflicting plan steps or contradictory instructions between planned changes.
  - **Pipeline contradiction scan:** Check whether this change contradicts logic in related pipelines. Level 1: within the changed files. Level 2: in files that interact with the changed component (imports, callers, shared state). Level 3: against project rules/philosophy (CLAUDE.md, SKILL.md principles). A change that works locally but contradicts a related pipeline is not coherent.
  "Coherent" one-liner without method execution = INVALID.
- **Evidence Gate (when delegation/review was used):**
  Independent-looking text is not evidence by itself. The parent applies this gate before using delegated findings.
  □ Does each plan element review have Prediction, Observation, AND Gap fields?
  □ Does Observation contain evidence from independent analysis? (file paths, function names, specific code observations)
  □ Is Prediction ≠ Observation check performed? (rubber-stamp detection)
  □ For items where Gap = "none": is the justification substantive?
  → If ANY check fails: reject that evidence and perform or request a fresh observation. If no review was used, the parent performs the same reference and coherence checks directly.
- Identify at least ONE risk, gap, or concern in the plan (even if approving). "No concerns" requires 3+ sentences of justification referencing specific aspects examined.
- Decide to approve or reject with substantive reasoning
- **Document-first rule:** Write intent check results to `## Intent Check` in the P document FIRST using Write/Edit tool. After the document is updated, provide a brief summary to the user. The document update is the primary output; the conversation summary is secondary.

## Tickets
(Automatically recorded when tickets are created)

## Analysis Results
(placeholder — parent writes inspected evidence and plan reasoning here)

## Review Results (if used)
(optional — record independent findings and the parent's disposition when review was warranted)

## Intent Check
(placeholder — parent writes final intent and scope check here)

## Verification Criteria
{user's answer — must describe observable behavior}

## Log

---
### [{YYYY-MM-DD HH:MM}] Created
{background/motivation for this plan}
```

### Step 4: Update INDEX.md

Append row to `.crabshell/plan/INDEX.md`:

```
| [[P{NNN}-{slug}|P{NNN}]] | {title} | draft | {YYYY-MM-DD} | | |
```

### Step 5: Confirm

Tell user: "Created P{NNN} in draft status. Review and approve before creating tickets."

---

## Update Mode

When argument matches `P\d{3}` pattern:

### Step 1: Read existing document

Glob `.crabshell/plan/P{NNN}-*.md`. If not found, stop.

### Step 2: Append log entry

Append to end of document:

```

---
### [{YYYY-MM-DD HH:MM}] {entry_type}
{content}
```

Entry types:
- General update (default)
- `Approved` — user approved the plan
- `Status change: {old} → {new}`
- `Ticket added: P{NNN}_T{NNN}` — when a ticket is created (auto-appended by ticketing skill)

### Step 3: Update INDEX.md if needed

Update status column and/or Tickets column in `.crabshell/plan/INDEX.md`.

### Status Transitions

- `draft` → `approved` (user approves — REQUIRED before tickets)
- `approved` → `in-progress` (first ticket starts work)
- `in-progress` → `done` (all tickets verified)
- any → `abandoned`

---

## Rules

1. **NEVER modify existing content.** Only append to Log section, Tickets section, and agent result sections (Analysis Results, Review Results, Intent Check).
2. **Tickets section:** Only receives appended lines like `- [[P{NNN}_T{NNN}-{slug}|P{NNN}_T{NNN}]]: {title}` when ticketing skill creates a ticket.
3. **Plan checkboxes:** Never modify. Progress is tracked in Log entries.
4. **INDEX.md** is the only file where status may be modified.
5. When plan comes from a discussion/investigation, note `[[D{NNN}-{slug}|D{NNN}]]` or `[[I{NNN}-{slug}|I{NNN}]]` in INDEX.md Related column and add to first log entry. Use bare ID (e.g., `D{NNN}`) as a forward reference if the filename is not yet known.
6. **No parent transition while children incomplete:** P can only transition to `done` when ALL related tickets are `verified`. If any ticket is incomplete, refuse `done` transition.
7. **Auto-conclude parent on completion:** When P becomes `done` → automatically update D/I in Related column to `concluded` and append log to those documents. (Triggered by ticketing cascade)
8. **Mandatory work log:** After performing any work related to this document, append a log entry to the Log section using the existing format (`### [{YYYY-MM-DD HH:MM}] {entry_type}`). This applies regardless of whether this skill was explicitly invoked — if the work touched or advanced this plan's purpose, log it.
9. **Mandatory result append:** The parent MUST append analysis and final intent-check evidence to the P document. If delegation/review was used, its findings and the parent's disposition MUST also be recorded. Verbal reporting alone is insufficient. Before proceeding, the parent reads the P document and confirms the required parent sections no longer contain `placeholder`; the optional review section is not a completion gate when review was unnecessary.
10. **Exhaustive verification standard:** Verification follows the VERIFICATION-FIRST principle in RULES (Predict → Execute → Compare). When no project verification tool exists, invoke the 'verifying' skill. Direct → indirect → explicitly "unverified".
11. **Anti-partitioning (regressing context):** When this plan is part of a regressing cycle, it MUST plan work for the current cycle only. Plans that reference or pre-allocate work for future cycles (e.g., "Cycle 2 will handle X") are INVALID and must be rejected by the parent; an optional reviewer may provide additional independent evidence.
12. **Regressing state update:** If `.crabshell/memory/regressing-state.json` exists and is active, update it after plan creation using: `"{NODE_PATH}" -e "const f='{PROJECT_DIR}/.crabshell/memory/regressing-state.json';const s=JSON.parse(require('fs').readFileSync(f,'utf8'));s.planId='{P-ID}';s.lastUpdatedAt=new Date().toISOString();require('fs').writeFileSync(f,JSON.stringify(s,null,2))"`. Phase transition is handled automatically by the PostToolUse hook. Only applies when regressing-state.json exists — standalone planning usage is unaffected.