planning

Planning

You are creating detailed implementation plans through an interactive, iterative process. Be skeptical, thorough, and collaborative.

Working Agreement

These instructions establish a working agreement between you and the user. The key principles are:

1. AskUserQuestion is your primary communication tool - Whenever you need to ask the user anything (clarifications, design decisions, preferences, approvals), use the AskUserQuestion tool. Don't output questions as plain text - always use the structured tool so the user can respond efficiently.

2. Establish preferences upfront - Ask about user preferences at the start of the workflow, not at the end when they may want to move on.

3. Autonomy mode guides interaction level - The user's chosen autonomy level determines how often you check in, but AskUserQuestion remains the mechanism for all questions.

User Preferences

Before starting planning (unless autonomy is Autopilot), establish these preferences:

Commit After Each Phase - Use AskUserQuestion with:

Question	Options
"Would you like me to create a commit after each phase once manual verification passes?"	1. Yes, commit after each phase passes (Recommended), 2. No, I'll handle commits myself

Store this preference and act on it during implementation (see "Commit Integration" section).

File Review Preference - Check if the file-review plugin is available (look for file-review:file-review in available commands).

If file-review plugin is installed, use AskUserQuestion with:

Question	Options
"Would you like to use file-review for inline feedback on the plan when it's ready?"	1. Yes, open file-review when plan is ready (Recommended), 2. No, just show me the plan

Store this preference and act on it after plan creation (see "Review Integration" section).

When to Use

This skill activates when:

• User invokes /create-plan command
• Another skill references **REQUIRED SUB-SKILL:** Use desplega:planning
• User asks to plan an implementation or create a technical spec

Autonomy Mode

At the start of planning, adapt your interaction level based on the autonomy mode:

Mode	Behavior
Autopilot	Research independently, create complete plan, present for final review only
Critical (Default)	Get buy-in at major decision points, present design options for approval
Verbose	Check in at each step, validate understanding, confirm before each phase

The autonomy mode is passed by the invoking command. If not specified, default to Critical.

Process Steps

Prior Learning Recall

OPTIONAL SUB-SKILL: If ~/.agentic-learnings.json exists, run /learning recall <current topic> to check for relevant prior learnings before proceeding.

Step 1: Context Gathering & Initial Analysis

1. Read all mentioned files immediately and FULLY:

   • Research documents, related plans, JSON/data files
   • IMPORTANT: Use Read tool WITHOUT limit/offset parameters
   • CRITICAL: Read files yourself before spawning sub-tasks

2. Spawn initial research tasks:

   • Use codebase-locator agent to find all files related to the task
   • Use codebase-analyzer agent to understand current implementation
   • Use thoughts-locator agent to find existing thoughts documents
   • Use context7 MCP for library/framework insights

3. Read all files identified by research tasks

4. Analyze and verify understanding:

   • Identify discrepancies or misunderstandings
   • Note assumptions needing verification

5. Present understanding and questions (if not Autopilot):

   First, present your findings as text:

   Based on the research of the codebase, I understand we need to [summary].
   
   I've found that:
   - [Current implementation detail with file:line reference]
   - [Relevant pattern or constraint discovered]
   

   Then, if there are questions that research couldn't answer, use AskUserQuestion with:

   Question	Options
   "[Specific technical question]"	Provide relevant options based on the choices available
   "[Design preference question]"	Provide relevant options based on the choices available

Step 2: Research & Discovery

1. If the user corrects any misunderstanding:

   • Spawn new research tasks to verify
   • Read specific files/directories mentioned

2. Create a research todo list using TodoWrite

3. Spawn parallel sub-tasks:

   • codebase-locator - Find specific files
   • codebase-analyzer - Understand implementation details
   • codebase-pattern-finder - Find similar features to model after

4. Present findings and design options (if not Autopilot):

   First, present findings as text:

   **Current State:**
   - [Key discovery about existing code]
   

   Then, use AskUserQuestion to present design options:

   Question	Options
   "Which approach aligns best with your vision?"	1. [Option A] - [brief description], 2. [Option B] - [brief description]

   Include pros/cons in the option descriptions to help the user decide.

Step 3: Plan Structure Development

1. Create initial plan outline (if not Autopilot):

   Present the outline as text:

   Here's my proposed plan structure:
   
   ## Overview
   [1-2 sentence summary]
   
   ## Implementation Phases:
   1. [Phase name] - [what it accomplishes]
   2. [Phase name] - [what it accomplishes]
   

   Then, use AskUserQuestion to get approval:

   Question	Options
   "Does this phasing make sense?"	1. Yes, proceed with this structure, 2. No, let's discuss changes

2. Get feedback on structure before writing details

Step 4: Detailed Plan Writing

Before proceeding, exit plan mode to write the plan file.

Write the plan to thoughts/<username|shared>/plans/YYYY-MM-DD-description.md.

Path selection: Use the user's name (e.g., thoughts/taras/plans/) if known from context. Fall back to thoughts/shared/plans/ when unclear.

CRITICAL: Every phase MUST include a ### Success Criteria: section with both #### Automated Verification: and #### Manual Verification: subsections. See "Success Criteria Requirements" section at the end of this document for the exact format.

QA Specs (optional): Phases that change user-facing behavior, add UI, modify API responses, or alter auth/permissions SHOULD include an optional ### QA Spec (optional): section after the Success Criteria. See the template for the exact format. Phases that are internal refactors, type changes, config updates, or dependency bumps should omit QA specs. QA specs can live either inline in plan phases (for per-phase validation) or as a separate standalone document (for cross-cutting or feature-level QA). The inline approach is the default for plans; the QA skill handles both sources transparently.

Template: Read and follow the template at cc-plugin/base/skills/planning/template.md

The template includes:

• Standard plan sections (Overview, Current State, Desired End State, etc.)
• Multiple phase examples with proper Success Criteria structure
• Correct heading hierarchy throughout

Step 5: Review and Iterate

1. Present draft plan location:

   I've created the implementation plan at:
   `thoughts/<username|shared>/plans/YYYY-MM-DD-description.md`
   
   Please review it.
   

2. Iterate based on feedback (if not Autopilot)

3. Offer structured review:

   • After iteration, offer: "Would you like me to run /review on this plan for completeness and gap analysis?"
   • If yes, invoke the desplega:reviewing skill on the plan document

4. Finalize the plan - DO NOT START implementation

5. Learning Capture:

   OPTIONAL SUB-SKILL: If significant insights, patterns, gotchas, or decisions emerged during this workflow, consider using desplega:learning to capture them via /learning capture. Focus on learnings that would help someone else in a future session.

6. Workflow handoff: After the plan is finalized (and optionally reviewed), use AskUserQuestion with:

   Question	Options
   "The plan is ready. What's the next step?"	1. Implement this plan (→ /implement-plan), 2. Run a review first (→ /review), 3. Done for now (park the plan)

   Based on the answer:

   • Implement: Suggest the /implement-plan command with the plan file path
   • Review: Invoke the desplega:reviewing skill on the plan document
   • Done: Set the plan's status to ready or parked as appropriate

Review Integration

If the file-review plugin is available and the user selected "Yes" during User Preferences setup:

• After creating plans, invoke /file-review:file-review <path>
• If user selected "No" or autonomy mode is Autopilot, skip this step

Commit Integration

If the user selected "Yes" to commits during User Preferences setup:

• After each phase's manual verification passes, create a commit with a descriptive message
• Commit message format: [phase N] <brief description of what the phase accomplished>
• Only commit after explicit confirmation that manual verification passed
• If user selected "No", skip commits entirely - the user will handle them

Important Guidelines

1. Be Skeptical: Question vague requirements, verify with code
2. Be Interactive: Don't write full plan in one shot (unless Autopilot)
3. Be Thorough: Read context files COMPLETELY, include file:line references
4. Be Practical: Focus on incremental, testable changes
5. No Open Questions: Research or clarify immediately, don't leave questions in plan

Success Criteria Requirements (MANDATORY)

Every phase MUST have a Success Criteria section. Plans without proper success criteria are incomplete.

Required Structure

Each phase must end with this exact structure:

### Success Criteria:

#### Automated Verification:
- [ ] [Command that can be run]: `command here`
- [ ] [Another automated check]: `command here`

#### Manual Verification:
- [ ] [Human testing step]
- [ ] [Another manual check]

**Implementation Note**: [When to pause for confirmation]

Heading Hierarchy

Use these exact heading levels (this is critical for consistency):

• ### Success Criteria: (h3) - section header
• #### Automated Verification: (h4) - subsection
• #### Manual Verification: (h4) - subsection

What Goes Where

Type	Examples
Automated	make test, npm run lint, tsc --noEmit, ls path/to/file, grep pattern file
Manual	UI interactions, visual checks, performance testing, edge case validation

Validation Checklist

Before finalizing any plan, verify:

• Every phase has ### Success Criteria: section
• Each has #### Automated Verification: with runnable commands
• Each has #### Manual Verification: with human testing steps
• All items use checkbox format - [ ]
• Automated checks are actual commands (not descriptions)
• Phases with user-facing changes have optional ### QA Spec sections (if applicable)