- When planning a phase, you are writing the prompt that will execute it.
- The quality degradation curve:
- 0-30% context: Peak quality (comprehensive, thorough, no anxiety)
- 30-50% context: Good quality (engaged, manageable pressure)
- 50-70% context: Degrading quality (efficiency mode, compression)
- 70%+ context: Poor quality (self-lobotomization, rushed work)
- Critical insight:
- Claude doesn't degrade at 80% - it degrades at ~40-50% when it sees context mounting and enters "completion mode." By 80%, quality has already crashed.
- Solution:
- Aggressive atomicity - split phases into many small, focused plans.
- Examples:
- 01-01-PLAN.md
- - Phase 1, Plan 1 (2-3 tasks: database schema only)
- 01-02-PLAN.md
- - Phase 1, Plan 2 (2-3 tasks: database client setup)
- 01-03-PLAN.md
- - Phase 1, Plan 3 (2-3 tasks: API routes)
- 01-04-PLAN.md
- - Phase 1, Plan 4 (2-3 tasks: UI components)
- Each plan is independently executable, verifiable, and scoped to
- 2-3 tasks maximum
- .
- Atomic task principle:
- Better to have 10 small, high-quality plans than 3 large, degraded plans. Each commit should be surgical, focused, and maintainable.
- Autonomous execution:
- Plans without checkpoints execute via subagent with fresh context - impossible to degrade.
- See: references/scope-estimation.md
- Checkpoint types:
- checkpoint:human-verify
- - Human confirms Claude's automated work (visual checks, UI verification)
- checkpoint:decision
- - Human makes implementation choice (auth provider, architecture)
- Rarely needed:
- checkpoint:human-action
- - Only for actions with no CLI/API (email verification links, account approvals requiring web login with 2FA)
- Critical rule:
- If Claude CAN do it via CLI/API/tool, Claude MUST do it. Never ask human to:
- Deploy to Vercel/Railway/Fly (use CLI)
- Create Stripe webhooks (use CLI/API)
- Run builds/tests (use Bash)
- Write .env files (use Write tool)
- Create database resources (use provider CLI)
- Protocol:
- Claude automates work → reaches checkpoint:human-verify → presents what was done → waits for confirmation → resumes
- See: references/checkpoints.md, references/cli-automation.md
- During execution, deviations are handled automatically via 5 embedded rules:
- Auto-fix bugs
- - Broken behavior → fix immediately, document in Summary
- Auto-add missing critical
- - Security/correctness gaps → add immediately, document
- Auto-fix blockers
- - Can't proceed → fix immediately, document
- Ask about architectural
- - Major structural changes → stop and ask user
- Log enhancements
- - Nice-to-haves → auto-log to ISSUES.md, continue
- No user intervention needed for Rules 1-3, 5.
- Only Rule 4 (architectural) requires user decision.
- All deviations documented in Summary
- with: what was found, what rule applied, what was done, commit hash.
- Result:
- Flow never breaks. Bugs get fixed. Scope stays controlled. Complete transparency.
- See: workflows/execute-phase.md (deviation_rules section)
- Milestone-driven:
- Ship v1.0 → mark milestone → plan v1.1 → ship → repeat.
- Milestones mark shipped versions and enable continuous iteration.
- Purpose:
- Historical record in MILESTONES.md (what shipped when)
- Greenfield → Brownfield transition marker
- Git tags for releases
- Clear completion rituals
- Default approach:
- Extend existing roadmap with new phases.
- v1.0 ships (phases 1-4) → add phases 5-6 for v1.1
- Continuous phase numbering (01-99)
- Milestone groupings keep roadmap organized
- Archive ONLY for:
- Separate codebases or complete rewrites (rare).
- See: references/milestone-management.md
- If it sounds like corporate PM theater, delete it.
- At 25% remaining
-
- Mention context getting full
- At 15% remaining
-
- Pause, offer handoff
- At 10% remaining
- Auto-create handoff, stop
Never start large operations below 15% without user confirmation.
Mandatory gates:
Before writing PLAN.md (confirm breakdown)
After low-confidence research
On verification failures
After phase completion with issues
Before starting next phase with previous issues
See: references/user-gates.md
Check for repo on invocation, offer to initialize
Commit only at: initialization, phase completion, handoff
Intermediate artifacts (PLAN.md, RESEARCH.md, FINDINGS.md) NOT committed separately
Git log becomes project history
See: references/git-integration.md
Run on every invocation to understand current state:
Check git status
git rev-parse --git-dir 2
/dev/null || echo "NO_GIT_REPO"
Check for planning structure
ls -la .planning/ 2
/dev/null ls -la .planning/phases/ 2
/dev/null
Find any continue-here files
find . -name ".continue-here.md" -type f 2
/dev/null
Check for existing artifacts
[
-f
.planning/BRIEF.md
]
&&
echo
"BRIEF: exists"
[
-f
.planning/ROADMAP.md
]
&&
echo
"ROADMAP: exists"
If NO_GIT_REPO detected:
Inline question: "No git repo found. Initialize one? (Recommended for version control)"
If yes:
git init
Present findings before intake question.
/dev/null This reveals available domain expertise (e.g., macos-apps, iphone-apps, unity-games, nextjs-ecommerce). If no domain skills found: Proceed without domain expertise (graceful degradation). The skill works fine without domain-specific context.
If user's request contains domain keywords, INFER the domain: Keywords Domain Skill "macOS", "Mac app", "menu bar", "AppKit", "SwiftUI desktop" expertise/macos-apps "iPhone", "iOS", "iPad", "mobile app", "SwiftUI mobile" expertise/iphone-apps "Unity", "game", "C#", "3D game", "2D game" expertise/unity-games "MIDI", "MIDI tool", "sequencer", "MIDI controller", "music app", "MIDI 2.0", "MPE", "SysEx" expertise/midi "Agent SDK", "Claude SDK", "agentic app" expertise/with-agent-sdk "Python automation", "workflow", "API integration", "webhooks", "Celery", "Airflow", "Prefect" expertise/python-workflow-automation "UI", "design", "frontend", "interface", "responsive", "visual design", "landing page", "website design", "Tailwind", "CSS", "web design" expertise/ui-design If domain inferred, confirm: Detected: [domain] project → expertise/[skill-name] Load this expertise for planning? (Y / see other options / none) If no domain obvious from request, present options: What type of project is this? Available domain expertise: 1. macos-apps - Native macOS with Swift/SwiftUI 2. iphone-apps - Native iOS with Swift/SwiftUI 3. unity-games - Unity game development 4. swift-midi-apps - MIDI/audio apps 5. with-agent-sdk - Claude Agent SDK apps 6. ui-design - Stunning UI/UX design & frontend development [... any others found in expertise/] N. None - proceed without domain expertise C. Create domain skill first Select: When domain selected, use intelligent loading: Step 1: Read domain SKILL.md cat ~/.claude/skills/expertise/ [ domain ] /SKILL.md 2 /dev/null This loads core principles and routing guidance (~5k tokens). Step 2: Determine what references are needed Domain SKILL.md should contain a
section that maps planning contexts to specific references. Example: < references_index ** For database/persistence phases: ** references/core-data.md, references/swift-concurrency.md ** For UI/layout phases: ** references/swiftui-layout.md, references/appleHIG.md ** For system integration: ** references/appkit-integration.md ** Always useful: ** references/swift-conventions.md </ references_index
Step 3: Load only relevant references Based on the phase being planned (from ROADMAP), load ONLY the references mentioned for that type of work.
Example: Planning a database phase
cat
~/.claude/skills/expertise/macos-apps/references/core-data.md
cat
~/.claude/skills/expertise/macos-apps/references/swift-conventions.md
Context efficiency:
SKILL.md only: ~5k tokens
SKILL.md + selective references: ~8-12k tokens
All references (old approach): ~20-27k tokens
Announce: "Loaded [domain] expertise ([X] references for [phase-type])."
If domain skill not found:
Inform user and offer to proceed without domain expertise.
If SKILL.md doesn't have references_index:
Fall back to loading all references with warning about context usage.