Planning

---
name: planning
description: Use when you need to plan technical solutions that are scalable, secure, and maintainable.
license: MIT
---

# Planning

Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.

## When to Use

Use this skill when:
- Planning new feature implementations
- Architecting system designs
- Evaluating technical approaches
- Creating implementation roadmaps
- Breaking down complex requirements
- Assessing technical trade-offs

## Core Responsibilities & Rules

Always honoring **YAGNI**, **KISS**, and **DRY** principles.
**Be honest, be brutal, straight to the point, and be concise.**

### 1. Research & Analysis
Load: `references/research-phase.md`
**Skip if:** Provided with researcher reports

### 2. Codebase Understanding
Load: `references/codebase-understanding.md`
**Skip if:** Provided with scout reports

### 3. Solution Design
Load: `references/solution-design.md`

### 4. Plan Creation & Organization
Load: `references/plan-organization.md`

### 5. Task Breakdown & Output Standards
Load: `references/output-standards.md`

### 6. Predictive Planning · Forecasting Outcomes
Load: `references/forecasting-outcomes.md`
**When**: estimating timelines from team velocity, risk-scoring an architectural decision, predicting bottlenecks from a dependency graph. Use historical metrics, not gut feel. Distinct from solution design — predictive planning quantifies uncertainty rather than choosing among approaches.

## Workflow Process

1. **Initial Analysis** → Read codebase docs, understand context
2. **Research Phase** → Spawn researchers, investigate approaches
3. **Synthesis** → Analyze reports, identify optimal solution
4. **Design Phase** → Create architecture, implementation design
5. **Plan Documentation** → Write comprehensive plan
6. **Review & Refine** → Ensure completeness, clarity, actionability

## Output Formats

- **Default: Markdown** — `plan.md` + `phase-*.md` (the structure below). Always the single source of truth; `/ck:cook` consumes these.
- **`-o html` (opt-in):** ADDITIONALLY render one self-contained `plan.html` view, derived from the markdown. Markdown stays primary; html is a one-directional snapshot. Also supports **convert mode** — `/ck:plan <existing-plan.md> -o html` re-renders `plan.html` from an existing plan without re-planning. Full template + fill procedure: `references/html-output.md` (single source — do not duplicate HTML guidance elsewhere).

## Output Requirements

- DO NOT implement code - only create plans
- Respond with plan file path and summary
- Ensure self-contained plans with necessary context
- Include code snippets/pseudocode when clarifying
- Provide multiple options with trade-offs when appropriate
- Fully respect the `./docs/development-rules.md` file.

**Plan Directory Structure**
**Plan dir name:** `YYMMDD-HHmm-<slug>` — 6-digit date, from `bash -c 'date +%y%m%d-%H%M'` (PowerShell: `Get-Date -UFormat "%y%m%d-%H%M"`), never from model knowledge. `/ck:cook` resolves plan paths on this form; an 8-digit `YYYYMMDD` dir is a different name and will not be found.

```
plans/
└── 260805-1430-plan-name/
    ├── research/
    │   ├── researcher-XX-report.md
    │   └── ...
    ├── reports/
    │   ├── XX-report.md
    │   └── ...
    ├── scout/
    │   ├── scout-XX-report.md
    │   └── ...
    ├── plan.md
    ├── phase-XX-phase-name-here.md
    └── ...
```

## Plan Rigor (mandatory blocks — every `plan.md`)

Plans are executed by fresh per-phase implementers and resumed by sessions with no memory of this one; these five blocks are what make that safe. Details: `references/output-standards.md`.

1. **Global Constraints block** — project-wide requirements with **values copied verbatim** (limits, versions, naming, paths). Implicitly part of every phase; a phase implementer sees only its own phase, so constraints must not live in prose elsewhere.
2. **Interfaces per phase** — `Consumes:` / `Produces:` with exact signatures and types, so a fresh implementer that reads only its phase still learns neighboring names. This is also what keeps per-phase dispatch (cook Implement) from losing cross-phase knowledge.
3. **No Placeholders** — "TBD", "add appropriate error handling", "similar to Phase N", "write tests for the above" are **plan failures**, not shorthand. Every task names its files, values, and behavior.
4. **Exit gate per phase** — every phase declares its gate as an **executable check**: a command, a test id, or a query **with the expected result stated**. This is what lets a resumed run (`run-state` skill) re-derive true state instead of trusting status claims.
5. **Scope options table** — when the task *could* span >1 repo/layer: the **(A) minimal-surface vs (B) thorough** table (repos/layers touched + conventions followed/broken per option, recommendation marked). Produced by cook's scope lock; the plan records which option was picked and why.

6. **Plan Completeness block** — the plan's own explicit sign-off, the last section of `plan.md`. Six ticked items; the plan is not finished until it declares itself finished. Exact block: `references/output-standards.md`.

### Hand-over gate (hard) — `plan-lint`

A self-attested checklist is attested by the same agent that wrote the plan, so the checkable half is machine-checked instead:

```
node .claude/scripts/ck/plan-lint.cjs <plan-dir>      # 0 = PASS · 1 = violations · 2 = no plan.md
```

Verifies: `## Global Constraints` present and non-empty · every phase has a gate stating `<command> → <expected>` (`**Exit gate:**`, `**Acceptance:**` and `**Exit criteria:**` all count) · every phase declares `**Interfaces**` (or `**Interfaces:** none — no cross-phase surface`, a recorded decision rather than silence) · no banned placeholders outside code fences and quotations · the `## Plan Completeness` block exists with all six items ticked. Warns when the plan spans >1 top-level dir with no scope options table.

**Exit 1 ⇒ the plan does not leave the planner.** Do not present it for review, do not implement against it. The two items no script can settle — spec coverage and cross-phase type agreement — stay attestation-only and the tool says so rather than implying it checked them.

Why hard: without `## Global Constraints`, `.claude/scripts/ck/phase-brief.cjs` emits a "plan declares no Global Constraints" comment and **exits 0**, so every per-phase implementer works without the verbatim values and the violation only surfaces at review, three gates later. Run against this repo's own flagship plan the gate returns 11 violations — the failure mode is the normal case, not a hypothetical.

**Self-review checklist before handing the plan over:** spec coverage (every requirement maps to a phase) · placeholder scan (grep for TBD/appropriate/similar to) · type/name consistency across phases (Interfaces blocks agree) · every phase gate runnable · Global Constraints verbatim. Then run `plan-lint` — the checklist is the intent, the linter is the gate.

## Quality Standards

- Be thorough and specific
- Consider long-term maintainability
- Research thoroughly when uncertain
- Address security and performance concerns
- Make plans detailed enough for junior developers
- Validate against existing codebase patterns

**Remember:** Plan quality determines implementation success. Be comprehensive and consider all solution aspects.