Planning With Smart

A practical skill for using persistent markdown files as working memory during complex tasks — creating structured planning documents, decision logs, and progress trackers that persist across sessions like a "thinking on disk" approach.

When to Use This Skill

Choose Planning With Smart when you need to:

• Plan complex tasks with persistent, revisitable documents
• Maintain working memory across long sessions
• Create structured decision logs for multi-step projects
• Track progress on tasks too complex to hold in memory
• Build reusable planning templates for recurring workflows

Consider alternatives when:

• You need project management tools (use a PM skill)
• You need quick, one-off plans (use a concise planning skill)
• You need architecture documents (use an architecture skill)

Quick Start

Copy
# Create a planning file for a complex task
claude "Create a planning file for migrating our database from MySQL to PostgreSQL. Track decisions, progress, and blockers."

Copy
# Plan: MySQL to PostgreSQL Migration
# File: .claude/plans/db-migration.md

## Status: IN PROGRESS (Phase 2 of 4)
## Last Updated: 2024-12-15

## Objective
Migrate production database from MySQL 5.7 to PostgreSQL 16
without downtime, preserving all data and application functionality.

## Phases
- [x] Phase 1: Schema conversion and testing (Dec 1-7)
- [ ] Phase 2: Application code changes (Dec 8-15) ← CURRENT
- [ ] Phase 3: Data migration dry run (Dec 16-20)
- [ ] Phase 4: Production cutover (Dec 21-22)

## Decisions Made
| # | Decision | Rationale | Date |
|---|----------|-----------|------|
| D1| Use pgloader for data migration | Best MySQL→PG tool, handles types | Dec 2 |
| D2| Dual-write during transition | Zero-downtime requirement | Dec 3 |
| D3| Keep MySQL as read replica for 7 days post-cutover | Rollback safety | Dec 5 |

## Blockers
- [ ] BLOCKER: MySQL ENUM types need manual mapping (17 tables)
  - Owner: Alice
  - Workaround: CHECK constraints in PG
  - Status: 12/17 tables converted

## Key Files Changed
- db/schema.sql → db/schema.pg.sql (converted)
- src/config/database.ts (dual-write logic)
- src/models/*.ts (query syntax changes)

## Notes
- GROUP_CONCAT → STRING_AGG (7 occurrences)
- IFNULL → COALESCE (23 occurrences)
- Auto-increment → SERIAL (all tables)
- DATE_FORMAT → TO_CHAR (12 occurrences)

Core Concepts

Planning File Types

File Type	Purpose	Lifespan
Task Plan	Track a specific task's progress	Duration of task
Decision Log	Record decisions with rationale	Project lifetime
Discovery Notes	Capture findings during exploration	Research phase
Progress Tracker	Track multi-day task completion	Duration of task
Template	Reusable structure for new plans	Permanent

File Organization

Copy
## Planning File Structure

### Where to Store
.claude/
├── plans/          # Active task plans
│   ├── db-migration.md
│   └── auth-redesign.md
├── decisions/      # Decision logs
│   └── architecture-decisions.md
├── notes/          # Discovery and research
│   └── performance-investigation.md
└── templates/      # Reusable templates
    ├── task-plan.md
    └── decision-record.md

### Naming Convention
{type}-{topic}.md
Examples:
- plan-db-migration.md
- decision-api-design.md
- notes-auth-research.md

Persistent Memory Pattern

Copy
## Using Files as Working Memory

### Write Before Thinking
Before solving a complex problem, write down:
1. What you know
2. What you don't know
3. What you've tried
4. What you'll try next

### Update as You Go
After each significant step:
1. Check off completed items
2. Add new discoveries
3. Update blockers
4. Revise the plan if needed

### Read Before Continuing
When resuming work:
1. Read the plan file first
2. Recall where you left off
3. Check for new information
4. Continue from the current step

### Close When Done
When the task is complete:
1. Mark all items as done
2. Record final outcome
3. Note lessons learned
4. Move to archive

Configuration

Parameter	Description	Example
plans_dir	Directory for planning files	".claude/plans/"
template_dir	Directory for templates	".claude/templates/"
auto_update	Update plan files automatically	true
include_timestamps	Add timestamps to updates	true
archive_on_complete	Move completed plans to archive	true

Best Practices

1. Create the plan file at the start of work, not halfway through — The plan file captures context that you'll need later. Starting without a plan file means losing the early decisions and discoveries that inform later steps.

2. Update the plan file every time you make a decision — Decisions made in code are invisible to future you. "We chose PostgreSQL arrays over junction tables for tags because query performance is 3x better for our read-heavy workload" belongs in the decision log.

3. Keep plan files under 200 lines — Long plan files become unreadable. If a plan exceeds 200 lines, split it into sub-plans or move completed sections to an archive section at the bottom.

4. Use checkboxes for progress, not text descriptions — "Phase 2 is mostly done" is vague. - [x] Convert 12/17 ENUM types is specific. Checkboxes make progress quantifiable and scannable.

5. Read the plan file before asking for help — When you need to brief someone (or a new AI session) on the current state, the plan file should contain everything they need. If it doesn't, update it before sharing.

Common Issues

Plan files become outdated and misleading — A plan file that says "Phase 1 complete" when Phase 1 was reverted is worse than no plan file. Update the plan file every time the situation changes, even if the change is a setback.

Too many plan files create their own management overhead — Five active plan files are manageable. Twenty are not. Limit active plans to tasks currently in progress. Archive completed plans immediately.

Plan files duplicate information from the codebase — Don't copy code into plan files. Reference file paths and line numbers instead. The plan file captures decisions and progress; the code captures implementation.