Plan

Implementation Planning Skill

Purpose

Design implementation approach with human-in-the-loop architectural decisions based on exploration findings.

Usage

/plan

(Must be run after /explore)

Note: Plan updates based on review feedback are handled by the /review skill.

What This Skill Does

1. Verify Prerequisites: Confirm exploration-summary.md and current-issue.md exist
2. Spawn Planning Agent: Generate 2-3 architectural options with trade-offs
3. Present Options: Display architectural approaches to user with pros/cons
4. User Selection: User selects preferred approach via AskUserQuestion
5. Generate Plan: Create implementation-plan.md with chosen approach
6. Report Summary: Display plan metrics and next steps

Instructions

You are coordinating the creation of an implementation plan for a JIRA issue. This skill receives exploration context from /explore and generates a detailed implementation plan with architectural choices.

CRITICAL: Your ONLY job is to:

1. Verify prerequisites (exploration-summary.md exists)
2. Spawn planning agent using the Task tool
3. Present architectural choices to user
4. Generate final plan with selected approach
5. Report results to the user

DO NOT:

• Perform exploration yourself (use /explore first)
• Generate the plan yourself
• If sub-agent fails, DO NOT retry the work yourself - report the failure to the user

Step 1: Verify Prerequisites

Verify that exploration context exists:

JIRA_DIR=$(ls -td workflow/jira-to-github/*/ 2>/dev/null | head -1)
if [ ! -f "$JIRA_DIR/current-issue.md" ]; then
  echo "❌ No JIRA analysis found. Run /pull first."
  exit 1
fi
if [ ! -f "$JIRA_DIR/exploration-summary.md" ]; then
  echo "❌ No exploration context found. Run /explore first."
  echo "The /plan skill requires exploration context to design the implementation approach."
  exit 1
fi
JIRA_KEY=$(basename "$JIRA_DIR")
echo "✓ Found JIRA issue: $JIRA_KEY"
echo "✓ Found exploration context"

Step 2: Spawn Planning Agent with Architectural Options

Use the Task tool to spawn a Plan agent that generates architectural options:

Task Tool Parameters:

• subagent_type: "Plan"
• description: "Generate architectural options"
• model: "sonnet" (complex planning task)

Agent Prompt:

You are the Planning Agent. Your job is to design 2-3 architectural approaches for implementing the JIRA issue, present them to the user for selection, then generate a detailed implementation plan for the chosen approach.

CONTEXT FILES PROVIDED (read in this order):
1. Target repo: workflow/jira-to-github/*/target-repo.md
2. Repo profile: context/repos/<repo>.md (path from target-repo.md)
3. Repo CLAUDE.md: <repo-path>/CLAUDE.md (coding patterns, architecture)
4. Module context: <repo-path>/<primary-module-path> (as specified in profile, README.md or MODULE.md)
5. Exploration context: workflow/jira-to-github/*/exploration-summary.md (READ THIS NEXT)
6. Original issue: workflow/jira-to-github/*/current-issue.md

CRITICAL - Exploration Already Completed:
You have been provided with comprehensive exploration context in `exploration-summary.md` including:
- External documentation (Figma designs, Confluence specs)
- Codebase patterns and reference implementations
- Human input, clarifications, and preferences
- Consolidated constraints and critical files

Your job is to DESIGN ARCHITECTURAL OPTIONS AND GENERATE AN IMPLEMENTATION PLAN, NOT gather more context.
Reference the exploration findings and repo context files when making decisions.

WORKFLOW:
1. Read target-repo.md, repo profile, repo CLAUDE.md, and module context file
2. Read exploration-summary.md and current-issue.md
3. Design 2-3 architectural approaches (different technical strategies)
4. Use AskUserQuestion to present options and get user selection
5. Generate detailed implementation plan for ONLY the chosen approach
6. Save plan to implementation-plan.md

Tasks:

PHASE 1: READ CONTEXT

1. Read target-repo.md to find the repo path and profile path. Then:
   - Read the repo profile (e.g., `context/repos/esperanto.md`) for context file pointers
   - Read the repo's own CLAUDE.md at `<repo-path>/CLAUDE.md` for architecture patterns, coding rules, and conventions
   - Read the module context file at `<repo-path>/<primary-module-path>` (if specified) for module structure and key files
   - If target-repo.md is not found, skip this step and rely on exploration-summary.md

2. Read exploration-summary.md FIRST to understand:
   - External context (Figma, Confluence)
   - Codebase patterns and reference implementations
   - Human input and clarifications
   - Constraints and critical files

3. Read current-issue.md to understand:
   - Requirements and acceptance criteria
   - Technical context and dependencies

PHASE 2: DESIGN ARCHITECTURAL OPTIONS

4. Based on the issue requirements and exploration findings, design 2-3 distinct architectural approaches.

   **What makes a good architectural option:**
   - Represents a fundamentally different technical strategy or pattern
   - Has clear trade-offs (complexity vs maintainability, performance vs simplicity, etc.)
   - Is viable given the constraints from exploration-summary.md
   - Aligns with at least some of the codebase patterns identified

   **Examples of architectural choices:**
   - State management: Redux vs Context API vs Zustand
   - Component architecture: Monolithic vs Composition vs Compound Components
   - Data flow: Props drilling vs Render props vs Hooks
   - Error handling: Try-catch locally vs Error boundaries vs Global error handler
   - Testing strategy: Unit + Integration vs E2E focused vs Snapshot + Unit
   - API integration: REST vs GraphQL vs tRPC
   - Code organization: Feature-based vs Layer-based vs Module-based

   **For each approach, document:**
   - Name (concise, descriptive, e.g., "Redux with Thunks")
   - Description (2-3 sentences explaining the approach)
   - Pros (2-4 bullet points on benefits)
   - Cons (2-4 bullet points on drawbacks)
   - Complexity (Low/Medium/High)
   - Files affected (estimated count or key files)
   - Alignment with exploration findings (how well it fits codebase patterns)

5. Format architectural options for user presentation:

   Create a structured table format like this:

   ```markdown
   ## Architectural Options

   ### Option 1: [Approach Name]
   **Description**: [2-3 sentences]

   **Pros**:
   - [Pro 1]
   - [Pro 2]
   - [Pro 3]

   **Cons**:
   - [Con 1]
   - [Con 2]

   **Complexity**: [Low/Medium/High]
   **Files Affected**: [Count or key files]
   **Alignment**: [How it fits exploration findings]

   ### Option 2: [Approach Name]
   [Same structure as Option 1]

   ### Option 3: [Approach Name] (if applicable)
   [Same structure as Option 1]

PHASE 3: PRESENT OPTIONS TO USER AND GATHER FEEDBACK

6. Use the AskUserQuestion tool to present the architectural options to the user AND invite their own suggestions:

   CRITICAL: You MUST use AskUserQuestion to get the user's architectural preference. Do NOT proceed to plan generation without user selection.

   COLLABORATIVE APPROACH: The goal is to collaborate with the user, not quiz them.

   • Explicitly invite alternative architectural approaches
   • Encourage feedback and suggestions on presented options
   • Use "Other" option to capture user's custom architecture
   • Present this as a discussion starter, not a final decision

   Format the question like this:

   {
     "questions": [
       {
         "question": "Which architectural approach do you prefer for this implementation? If you have a different approach in mind or suggestions to improve these options, please select 'Other' and describe your preferred architecture.",
         "header": "Approach",
         "multiSelect": false,
         "options": [
           {
             "label": "Option 1: [Approach Name]",
             "description": "Pros: [key pros] | Cons: [key cons] | Complexity: [level]"
           },
           {
             "label": "Option 2: [Approach Name]",
             "description": "Pros: [key pros] | Cons: [key cons] | Complexity: [level]"
           },
           {
             "label": "Option 3: [Approach Name]",
             "description": "Pros: [key pros] | Cons: [key cons] | Complexity: [level]"
           }
         ]
       },
       {
         "question": "Do you have any concerns, suggestions, or modifications for the selected approach?",
         "header": "Feedback",
         "multiSelect": false,
         "options": [
           {
             "label": "No concerns, proceed as described",
             "description": "The selected approach looks good as-is"
           },
           {
             "label": "Minor adjustments needed",
             "description": "Small tweaks or clarifications needed (describe in 'Other')"
           },
           {
             "label": "Significant changes needed",
             "description": "Major modifications or hybrid approach preferred (describe in 'Other')"
           }
         ]
       }
     ]
   }
   

   Keep the descriptions concise in the AskUserQuestion options (fit within description field limits). Reference the full architectural options markdown you created above for complete details.

7. Handle user feedback and alternatives:

   • If user selects "Other" for approach: Carefully review their custom architecture description
   • If user provides suggestions/concerns: Incorporate into the final plan
   • If user wants hybrid approach: Combine elements from multiple options as described
   • If user's alternative is unclear: Ask follow-up clarification questions before generating plan

8. Validation: Ensure you generated at least 2 options (minimum).

   • If only 1 viable approach exists, explain why and ask user to confirm
   • If unable to generate options, ask user for requirements clarification
   • If user provides alternative approach, validate it aligns with exploration constraints

PHASE 4: GENERATE IMPLEMENTATION PLAN

9. After user selects their preferred approach AND provides feedback/suggestions, generate a TOKEN-OPTIMIZED implementation plan with ONLY the chosen/modified approach.

   CRITICAL:

   • Do NOT include all options in the plan - only the selected one
   • INCORPORATE user's feedback, suggestions, and modifications
   • If user provided custom architecture via "Other", use that as the approach
   • If user requested hybrid approach, combine elements as they described

TOKEN OPTIMIZATION RULES (CRITICAL): ✅ DO:

• Use tables for file changes (60% more efficient than paragraphs)
• Reference files: "See: path/file.ts:functionName()" instead of code blocks
• Use bullet points and brief descriptions
• Keep testing strategy brief (detailed tests go in /test skill)
• Single source of truth (no duplicate info across sections)
• Reference exploration-summary.md sections instead of repeating info

❌ DO NOT:

• Include full code examples (use file references instead)
• Write verbose paragraph explanations for each file
• Duplicate information across sections
• Re-search for patterns (already in exploration-summary.md)
• Add generic team knowledge (already in exploration-summary.md)
• Include all architectural options (only include chosen approach)
• Append full revision histories (use brief changelog instead)

10. Generate the plan with this structure:

---

Implementation Plan: <JIRA-KEY>

Generated: <timestamp>

---

Summary

<1-2 sentence summary of the implementation approach>

Architectural Approach Selected

Chosen Approach: [Name of selected option or "Custom" if user provided alternative]

[Copy the full description, pros, cons from the selected option OR user's custom architecture description]

User Feedback Incorporated:

• [List any suggestions, modifications, or concerns the user provided]
• [Note if this is a hybrid approach combining multiple options]
• [Note if user provided completely custom architecture]

Rationale: [Why this approach fits the requirements and exploration findings, including how user feedback shaped the decision]

Exploration Findings Applied

<Reference key findings from exploration-summary.md that inform this plan>

External Context:

• Figma: [1 sentence on design approach]
• Confluence: [1 sentence on technical specs]

Codebase Patterns:

• Reference implementations: [file references]
• Utilities to leverage: [file references]

Human Decisions:

• [Key decision 1 from human input]
• [Key decision 2 from human input]

Technical Approach

<2-3 sentences describing implementation approach for CHOSEN option> <Reference exploration-summary.md for patterns>

Files to Change

New Files

File Path	Purpose	Pattern Reference
path/to/new-file.ts	Brief purpose	Follow: exploration-summary.md → [section]
path/to/test.spec.ts	Test coverage	Follow: exploration-summary.md → Testing Patterns

Modified Files

File	Changes	Key Details	Reference
path/file.ts	Add enum value, new field	Brief details	See: exploration-summary.md → Codebase Patterns
path/component.tsx	Add cardType prop	Brief details	Follow: path/reference.tsx:123

Code Reference Format (NO full code blocks):

• See: src/utils/wallet.ts:isBankCard() for pattern to follow
• Follow: AddCardForm.tsx prop pattern (from exploration-summary.md)
• Reuse: existing addCard() method in walletService
• Apply: Design tokens from exploration-summary.md → Figma Designs

Implementation Steps

1. Type definitions → files: wallet.ts, types.ts
2. UI components → files: CardList.tsx, AddCardForm.tsx (apply Figma specs)
3. State management → files: walletSlice.ts, useCardActions.ts (using CHOSEN approach)
4. Testing → files: *.test.tsx (follow patterns from exploration-summary.md)

Key Decisions

• Architectural Pattern: [Chosen approach name and brief rationale]
• Dependencies: <list if adding new packages>
• Human Preferences: <decisions from exploration-summary.md → Human Input>

Testing (Brief Overview)

• Unit tests: [components/utils to test]
• Integration: [flows to test]
• Manual: [browser/UI testing]

Detailed test specs will be in /test skill output Follow testing patterns from: exploration-summary.md → Testing Patterns

Risks & Mitigations

Risk	Mitigation	Source
Risk 1	Brief solution	[From exploration constraints or chosen approach cons]
Risk 2	Brief solution	[From technical analysis]

Security Considerations:

• [PCI/eProtect considerations if applicable]
• [From exploration-summary.md → Confluence → Security]

Acceptance Criteria

AC	Implementation	Verification	Notes
AC1: <criterion>	Files: x.ts, y.tsx	Test: test-name.spec.ts	[From human input]
AC2: <criterion>	Files: a.ts, b.tsx	Test: test-name.spec.ts	[From Confluence]

External References

• Figma: [Link and key components]
• Confluence: [Link and key specs]
• Codebase: See exploration-summary.md → Critical Files Identified
• Architectural Options Considered: [List the 2-3 options that were presented]

Revision History

First revision - keep this section minimal

IMPORTANT: Plan revisions are handled by the /review skill. If the user provides feedback during review, the /review skill will update this plan.

---

Plan generated: <timestamp> Based on exploration-summary.md findings Architectural approach: [Chosen option name]

10. Save the implementation plan to: workflow/jira-to-github/<JIRA-NUMBER>/implementation-plan.md

TARGET METRICS:

• Target plan size: 15-20 KB (vs previous 30+ KB)
• Target lines: 250-350 lines (vs previous 700+ lines)
• Token reduction: 40-50% compared to verbose format
• Exploration context reuse: Reference exploration-summary.md instead of re-searching

11. Display summary to user showing:
    • Plan file location
    • Plan file size (KB)
    • Exploration summary size (KB)
    • Architectural approach selected
    • Count of files to modify
    • Count of new files to create
    • 1-sentence summary of technical approach
    • Key exploration findings applied
    • Next step: Run /review to review and potentially revise the implementation plan

ERROR HANDLING:

• If exploration-summary.md not found: Exit with error (exploration must complete first)
• If unable to generate 2+ architectural options: Explain constraints and ask for user guidance
• If user declines to select an option: Ask for clarification or additional requirements
• If user selects "Other": Carefully review and incorporate their custom approach description into the plan
• If user's alternative approach is unclear: Ask follow-up questions before proceeding
• If user requests hybrid approach: Combine elements from multiple options as they described
• If user's feedback requires significant changes: Incorporate modifications while maintaining plan structure
• Log all errors to: workflow/jira-to-github/<JIRA-NUMBER>/errors.log

### Step 3: Handle Agent Result

**If the agent succeeds:**
- Read the output from the Task tool result
- The agent will have already presented options and generated the plan
- Report the summary to the user as provided by the agent

**If the agent fails:**
- Report the error to the user with the agent's error message
- Suggest the user check:
  - Exploration context exists (run /explore if missing)
  - JIRA issue analysis exists (run /pull if missing)
- DO NOT attempt to do the planning yourself
- DO NOT proceed with the workflow

### Step 4: Monitor and Report

After planning agent completes:

Display summary to user:

✓ Implementation plan generated

• Location: workflow/jira-to-github/<JIRA-NUMBER>/implementation-plan.md
• Size: [X KB] ([X lines])
• Architectural approach: [Chosen option name]
• Files to modify: [N]
• New files: [N]
• Approach: [1-sentence summary]

Architectural options considered:

• [Option 1 name]: [Brief description]
• [Option 2 name]: [Brief description]
• [Option 3 name]: [Brief description] (if applicable)

Selected approach: [Chosen option name or "Custom architecture"]

User feedback incorporated:

• [User suggestion 1 if provided]
• [User modification 2 if provided]
• [Note: "No modifications requested" if user approved as-is]

Key findings applied:

• [Key finding 1 from exploration]
• [Key finding 2 from exploration]

Next step: Run /review to review the plan and provide feedback

## Error Handling

If errors occur during any phase:

### Prerequisite Errors
- **current-issue.md not found**: Exit with message "Run /pull first"
- **exploration-summary.md not found**: Exit with message "Run /explore first - planning requires exploration context"

### Planning Errors
- **Planning agent fails**: Report failure to user, DO NOT retry yourself
- **Unable to generate multiple options**: Agent should explain why and ask user for guidance
- **User declines all options**: Agent should ask for additional requirements or constraints

### User Feedback Handling
- **No exploration context**: Run `/explore` before `/plan`
- **User confusion about options**: Agent provides more details on trade-offs
- **Custom approach requested**: Agent captures user's custom approach description and generates plan with it
- **User provides alternative architecture**: Agent validates it against exploration constraints and incorporates
- **User requests hybrid approach**: Agent combines elements from multiple options as described by user
- **User feedback is unclear**: Agent asks follow-up clarification questions before generating plan
- **User suggests modifications**: Agent incorporates suggestions while maintaining plan structure and token optimization

## Token Optimization Summary

This planning approach optimizes tokens through:

1. **Leverage exploration context** (saves 20-30k tokens):
   - Planning agent references exploration-summary.md instead of re-searching
   - Single source of truth for patterns and constraints

2. **Efficient plan format** (saves 15-20k tokens):
   - Tables instead of paragraphs
   - File references instead of code blocks
   - No duplicate information
   - Only include chosen architectural approach in final plan

3. **Focused architectural decision-making**:
   - Present 2-3 options (not exhaustive list)
   - User selects preferred approach
   - Plan includes only selected approach

**Token budget**:
- Planning phase: ~15-20 KB (references exploration, no re-searching)
- Output: 15-20 KB implementation-plan.md
- **Total with exploration**: 45-55 KB (exploration + planning)

## Examples

*Examples section can be added after testing with real JIRA issues*