Create Plan

Create a comprehensive implementation plan and enter plan mode for execution.

Position in Workflow

Step 4 of development workflow:

1. /research - Understand problem, explore implementation
2. /brainstorm-solutions - Explore solutions
3. /design-solution - Converge on a solution
4. /make-plan - Create implementation plan (THIS)
5. Code, review, ship

Core Principle

First principles. Simple over easy. Go deep.

You have a bias toward finishing quickly. Resist it.

Never cut corners or take the path of least resistance. Prefer the fundamentally right solution even if it requires significantly more work. The cost of a suboptimal solution compounds over time. Rushed plans degrade codebases.

Simple ≠ Easy:

• Easy: Less work now, more pain later (shortcuts, hacks, "good enough")
• Simple: More work now, less pain forever (clean, maintainable, right)

Always choose simple. Always go deep enough to find it.

Input

Default: Use chosen solution from current conversation context.

If argument provided:

• GitHub issue number/URL: Fetch full context with scripts/gh_issue_phase.sh get-issue $ARG
• Free-form text: Additional constraint or clarification for the plan.

Workflow

1. Verify Ready State

Before planning, confirm:

• Research is complete (problem understood)
• Solution space was explored
• A solution has been chosen

If missing context, ask: "I need [research/solution choice] before creating a plan. Should I run /research or /design-solution first?"

2. Specify Behavior Explicitly

This is the most critical step. Be exhaustive.

For each feature/change, document:

Desired Behavior

• What SHOULD happen in normal cases
• Expected outputs for typical inputs
• Success criteria

Undesired Behavior

• What MUST NOT happen
• Edge cases to handle gracefully
• Error conditions and their responses

Usage Patterns

• Common usage patterns (happy path)
• Unhappy paths (errors, edge cases, invalid input)
• Boundary conditions

Example format:

## Behavior: User Authentication

### Desired
- Valid credentials → session created, redirect to dashboard
- Session expires after 24h of inactivity
- Invalid credentials → clear error message, no session

### Undesired
- NEVER store password in plain text
- NEVER expose session token in URL
- NEVER allow infinite login attempts

### Edge Cases
- Expired password → prompt reset before login
- Concurrent sessions → configurable limit
- Network timeout during auth → retry with backoff

3. Go Deep - Gather Sufficient Context

Do not plan without full understanding. Read more code than feels necessary. Understand the implications of each decision.

Before finalizing any part of the plan:

• Read all related files, not just the obvious ones
• Understand how similar problems were solved elsewhere in the codebase
• Trace the full impact of proposed changes
• Identify hidden dependencies and side effects

You are not ready to plan if:

• You haven't read the files your changes will affect
• You don't understand the existing patterns in this area
• You're making assumptions instead of verifying

4. Apply First Principles Check

For each part of the plan, challenge ruthlessly:

Question	Purpose
Is this necessary?	Avoid bloat
Is there a simpler approach?	Simple > easy
Does this fight the codebase?	Respect existing patterns
What would we regret in 6 months?	Long-term thinking
Are we cutting corners?	No shortcuts
Do I have enough context?	Go deeper if uncertain

Red flags - STOP and reconsider:

• "This is faster but..." → You're choosing easy over simple
• "We can clean this up later..." → You won't. Do it right now.
• "Good enough for now..." → It will become permanent tech debt
• Adding TODO comments for "later" → Later never comes
• Skipping error handling "for simplicity" → That's not simplicity, it's negligence
• "I think this should work..." → You don't know. Go read more code.
• Feeling rushed → Slow down. Bad plans cost more than slow plans.

5. Design Tests

Write test specifications BEFORE implementation details:

Test design principles:

• Test behavior, not implementation
• Cover happy paths AND edge cases
• One assertion per test (when practical)
• Tests should be fast and isolated

Format:

## Tests

### Unit Tests
- `test_valid_credentials_creates_session` - happy path
- `test_invalid_credentials_returns_error` - error case
- `test_expired_password_prompts_reset` - edge case

### Integration Tests
- `test_full_login_flow_with_redirect`
- `test_session_timeout_behavior`

6. GitHub Issue Tracking

If a GitHub issue was provided or is available from prior phases:

Post behavior specification and test design as a phase comment and set the label. This must happen BEFORE entering plan mode.

echo "$PLAN_SUMMARY" | scripts/gh_issue_phase.sh post-phase $ISSUE planning
scripts/gh_issue_phase.sh set-label $ISSUE phase:planning

Pass the issue number forward for code-review and commit phases.

7. Enter Plan Mode

After documenting behavior and tests, switch to plan mode:

Say: "Entering plan mode to create the implementation plan."

Then use the EnterPlanMode tool.

Output Format (Before Plan Mode)

## Implementation Plan: [Feature Name]

### Chosen Solution
[Brief restatement of chosen approach from /design-solution]

### Behavior Specification

#### [Component/Feature 1]

**Desired:**
- [What should happen]

**Undesired:**
- [What must not happen]

**Edge Cases:**
- [Boundary conditions and handling]

#### [Component/Feature 2]
[Same structure]

### Tests

#### Unit Tests
- `test_name` - [what it verifies]

#### Integration Tests
- `test_name` - [what it verifies]

### First Principles Check
- [Confirmation that no shortcuts are taken]
- [Confirmation of simplest viable approach]
- [Alignment with existing patterns]

---

Entering plan mode to create implementation steps.

Common Mistakes

Mistake	Fix
Insufficient context gathering	Read ALL related files before planning
Vague behavior specs	Write explicit examples for each case
Only happy path	Always include unhappy paths and edge cases
Tests as afterthought	Design tests BEFORE implementation
Shortcut rationalization	Apply first principles check ruthlessly
Rushing to plan mode	Complete behavior spec first
Missing "undesired" section	Explicitly state what must NOT happen
Planning with assumptions	Verify by reading code, don't assume
Choosing easy over simple	More work now = less pain forever

What NOT to Do

• Do NOT plan without reading all affected code
• Do NOT make assumptions - verify by reading
• Do NOT skip behavior specification
• Do NOT leave edge cases undefined
• Do NOT take shortcuts for "simplicity"
• Do NOT skip the first principles check
• Do NOT enter plan mode without tests designed
• Do NOT proceed if solution wasn't explicitly chosen
• Do NOT rush - bad plans cost more than slow plans
• Do NOT rationalize shortcuts with "we can fix it later"