---
name: ck-planning
description: Plan feature implementations, design system architectures, create technical roadmaps. Use for implementation planning, system design, solution architecture, phase documentation, evaluating technical trade-offs.
---

# ck-planning

Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation. Embeds the `planner` agent role.

## Core Principles

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

## When to Use

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

## Don't Use When

- A plan already exists and just needs execution — use `ck-cook` instead
- The task is trivial and doesn't require multi-phase planning
- You need research only, without creating a full plan — use `ck-research`

## Core Process

### 1. Research & Analysis
Dispatch parallel `ck-research` agents to investigate relevant technical topics. Skip if researcher reports are already provided.

### 2. Codebase Understanding
Search the codebase for relevant files, read docs in `./docs`. Skip if scout reports are already provided.

### 3. Solution Design
Evaluate multiple approaches, apply mental models:
- **Decomposition**: Break the epic into concrete stories
- **Working Backwards**: Start from desired outcome, identify every step
- **Second-Order Thinking**: Ask "And then what?" for hidden consequences
- **The 80/20 Rule**: Identify the 20% of features delivering 80% of value
- **Risk & Dependency Management**: What could go wrong? What does this depend on?

### 4. Plan Creation
Save plans to `./plans` directory using the naming pattern from the `## Naming` section injected by the context system. Pattern includes the full path and computed date.

**Plan directory structure:**
```
plans/
└── {date}-plan-name/
    ├── research/
    ├── reports/
    ├── plan.md
    └── phase-XX-phase-name.md
```

**Every `plan.md` must start with YAML frontmatter:**
```yaml
---
title: "{Brief title}"
description: "{One sentence for card preview}"
status: pending
priority: P2
effort: {sum of phases}
branch: {current git branch}
tags: [relevant, tags]
created: {YYYY-MM-DD}
---
```

### 5. Phase Files

Each phase file must contain:
- Context Links
- Overview (priority, status, description)
- Key Insights
- Requirements (functional + non-functional)
- Architecture
- Related Code Files
- Implementation Steps (detailed, numbered)
- Todo List (checkbox)
- Success Criteria
- Risk Assessment
- Security Considerations
- Next Steps

## Active Plan State

Check the `## Plan Context` section in injected context:
- **"Plan: {path}"**: Active plan — ask "Continue with existing plan? [Y/n]"
- **"Suggested: {path}"**: Branch-matched hint — inform user, ask to activate or create new
- **"Plan: none"**: No active plan — create new using `## Naming` pattern

After creating plan folder, update session state so subsequent agents receive correct context.

## Output Requirements

- DO NOT implement code — only create plans
- Respond with plan file path and summary
- Ensure self-contained plans with all necessary context
- Include code snippets/pseudocode when clarifying architecture
- Provide multiple options with trade-offs when appropriate
- Make plans detailed enough for junior developers

**IMPORTANT:** Sacrifice grammar for concision. List unresolved questions at end if any.