Interactive Implementation Planner

Implementation Planner

Overview

Create detailed implementation plans through an interactive, iterative process. Be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications with proper separation of working notes from deliverables.

Language-Agnostic Approach: This skill is language-agnostic and delegates to language-specific guidelines skills (e.g., go-dev-guidelines for Go projects) for all coding standards, testing patterns, naming conventions, and architectural decisions. Always detect the project language and activate the appropriate guidelines skill at the start of planning.

Agent-First Strategy: This skill uses the Task tool extensively to spawn parallel research agents for maximum efficiency:

• GitHub Issue Analysis - Invoke github-issue-reader skill immediately when issue number provided
• Parallel Research - Launch 4-6 Task agents concurrently (using Explore or general-purpose subagent types)
• Verification - Spawn Task agents to verify user corrections and validate findings
• Optional Draft Generation - For complex plans, spawn agent to generate initial structure
• Optional Validation - Spawn agent to cross-check plan accuracy before presenting

Task agents handle all information gathering, while the main context handles user interaction and decision-making.

Note: Use the built-in agent types (Explore for codebase searches, general-purpose for complex tasks) via the Task tool. No custom agent definitions needed.

Quick Start

Use the init_plan.py script to quickly set up the plan structure:

For GitHub issue-based plans (recommended):

scripts/init_plan.py <issue-number> --type issue

Example: scripts/init_plan.py 123 --type issue

For ad-hoc plans:

scripts/init_plan.py <plan-name> --type adhoc

Example: scripts/init_plan.py refactor-auth --type adhoc

This creates a complete plan directory with all template files ready for customization.

Workflow Decision Tree

Start by determining what information is available and launching agents immediately:

1. Check for GitHub Issue:

   • If issue number provided → Launch github-issue-reader agent immediately (don't wait!)
   • If no issue exists → Prompt user to create one for history tracking
   • If user wants ad-hoc plan → Proceed with ad-hoc workflow

2. Detect language and activate guidelines:

   • Identify project language (Go, Python, TypeScript, etc.)
   • Activate appropriate guidelines skill (e.g., go-dev-guidelines)
   • Use throughout planning for coding patterns and architecture

3. Launch parallel research tasks:

   • While waiting for user input, launch 4-6 Task tool invocations concurrently:
     • Codebase exploration (Explore subagent)
     • Pattern discovery (Explore subagent)
     • Testing strategy (Explore subagent)
     • Architecture analysis (general-purpose subagent)
     • Guidelines verification (Explore subagent)
   • Task agents gather information in parallel for maximum efficiency

4. Parameters provided (file path, ticket reference)?

   • YES → Read files immediately after agents return results
   • NO → Request task description and context from user

5. After gathering context:

   • Create TodoWrite task list to track planning process
   • Review Task agent findings and read identified files
   • Present comprehensive findings with focused questions

6. After alignment on approach:

   • Optionally use Task tool to generate draft for complex plans
   • Create plan structure outline
   • Get feedback on structure
   • Generate the four structured files following language guidelines
   • Optionally use Task tool to validate accuracy before presenting

Step 1: Context Gathering & Initial Analysis

Activate Language-Specific Guidelines

BEFORE STARTING: Determine the project's primary language and activate the appropriate guidelines skill:

1. Detect Project Language:

   • Look at the codebase structure and file extensions
   • Check for language-specific files (go.mod, package.json, requirements.txt, etc.)
   • If unclear, ask the user

2. Activate Guidelines Skill:

   • Go projects → Use go-dev-guidelines skill for all coding standards, testing patterns, and architecture decisions
   • Other languages → Use appropriate language-specific guidelines if available
   • These skills provide the coding standards, testing patterns, and architectural patterns to follow

3. Apply Throughout Planning:

   • Reference the guidelines skill when making architectural decisions
   • Follow testing patterns from the guidelines (e.g., TDD with testify/require for Go)
   • Use naming conventions and project structure from guidelines
   • Include guidelines-compliant code examples in the plan

Determine Plan Type and GitHub Issue

NEXT: Determine if this is an issue-based or ad-hoc plan:

1. Check for GitHub Issue Number:

   • Look for issue number in parameters (e.g., "123", "#123", "issue 123")
   • If found, launch github-issue-reader agent immediately to gather comprehensive issue information
   • Plans for issues are stored in .docs/issues/<issue-number>/

2. If No Issue Number Provided:

   • Ask user: "Is this related to a GitHub issue? If so, please provide the issue number, or I can help you create one for tracking purposes."
   • If user provides issue number: Launch github-issue-reader agent
   • If user wants to create an issue: Help create it first with gh issue create
   • If user wants ad-hoc plan: Proceed without issue, store in .docs/adhoc/<plan-name>/

3. GitHub Issue Analysis:

   • Invoke the github-issue-reader skill using Skill tool to gather:
     • Issue title, description, and labels
     • All comments and discussion threads
     • Linked PRs and cross-references
     • Assignees and milestones
     • Related issues and context
   • Skill returns comprehensive analysis to main context
   • Don't wait for user confirmation - start codebase research immediately after skill completes

4. Benefits of Issue-Based Plans:

   • Provides history and tracking
   • Links plan to code changes and PRs
   • Enables team visibility and discussion
   • Recommended for all non-trivial features

Check for Provided Parameters

When the skill is invoked:

• If a file path or ticket reference was provided, skip requesting information
• Immediately read any provided files FULLY using the Read tool
• Begin the research process without delay

Read All Mentioned Files

CRITICAL: Read files completely in the main context:

• Use the Read tool WITHOUT limit/offset parameters
• DO NOT spawn sub-tasks before reading files in main context
• NEVER read files partially - if mentioned, read completely

Create Task Tracking

Create a TodoWrite task list to track the planning process and ensure nothing is missed.

Spawn Initial Research Tasks

Before asking the user questions, launch multiple Task tool invocations in parallel. Launch ALL these concurrently in a single message for maximum efficiency:

1. GitHub Issue Analysis (if issue-based plan)

• Invoke github-issue-reader skill using Skill tool
• Gathers: title, description, comments, linked PRs, labels, related issues
• Returns: Full context and discussion history

2. Codebase Exploration (Task tool - Explore subagent, medium thoroughness)

• Prompt: "Find all files related to [feature/task]. Identify relevant directories, modules, and entry points. Return file paths with brief descriptions of their purpose."
• Returns: Relevant file paths and structure

3. Pattern Discovery (Task tool - Explore subagent, medium thoroughness)

• Prompt: "Search for similar implementations to [feature/task] in the codebase. Identify patterns that should be followed, reusable utilities, and existing approaches. Return code examples with file:line references."
• Returns: Code patterns and examples

4. Testing Strategy Research (Task tool - Explore subagent, medium thoroughness)

• Prompt: "Research existing test patterns in this project. Find test utilities, fixtures, mocks, and integration test setup patterns. Map the testing infrastructure and conventions. Return examples with file:line references."
• Returns: Test patterns and infrastructure

5. Architecture Analysis (Task tool - general-purpose subagent)

• Prompt: "Analyze the architecture for [feature/task]. Trace data flow, map integration points and dependencies, identify shared interfaces and contracts. Find configuration and deployment patterns. Return detailed explanations with file:line references."
• Returns: Architecture overview and integration points

6. Guidelines Verification (Task tool - Explore subagent, quick thoroughness)

• Prompt: "Find examples of [language]-specific patterns currently used in the codebase. Identify coding standards, naming conventions, and architectural patterns being followed. Return code examples with file:line references."
• Returns: Existing code patterns

IMPORTANT: Launch all Task tool calls in a single message (parallel execution) for maximum efficiency.

Read Research Results

After research tasks complete:

• Read ALL files identified as relevant
• Read them FULLY into the main context
• Ensure complete understanding before proceeding

Present Informed Understanding

After research, present findings with specific questions:

Based on the ticket and research of the codebase, the task requires [accurate summary].

Found:
- [Current implementation detail with file:line reference]
- [Relevant pattern or constraint discovered]
- [Potential complexity or edge case identified]

Questions that research couldn't answer:
- [Specific technical question requiring human judgment]
- [Business logic clarification]
- [Design preference affecting implementation]

Only ask questions that cannot be answered through code investigation.

Step 2: Research & Discovery

Verify User Corrections

If the user corrects any misunderstanding:

• DO NOT just accept the correction
• Spawn verification Task agents immediately to confirm the correct information
• Launch multiple Task tool invocations in parallel to research specific areas mentioned
• Read the specific files/directories identified by Task agents
• Only proceed once facts are verified through code

Update Task Tracking

Update TodoWrite list to track exploration tasks and Task agent launches.

Spawn Follow-Up Research Tasks

Based on initial findings and user input, launch additional Task tool invocations in parallel:

Deep Dive Research (Task tool - as needed):

• Dependency Impact - "Map all affected systems and dependencies for [feature]. Find all integration points and impacted code. Return file:line references."
• Migration Strategy - "Research data migration patterns in the codebase. Find examples of previous migrations. Return patterns with file:line references."
• Performance Analysis - "Find performance-critical code paths related to [feature]. Identify bottlenecks and optimization patterns. Return file:line references."
• Security Pattern - "Identify security patterns currently used for [related feature]. Find authentication, authorization, and validation patterns. Return examples with file:line references."
• Error Handling - "Research existing error handling patterns in the codebase. Find how errors are created, wrapped, and handled. Return examples with file:line references."

For each Task agent:

• Use Explore subagent for codebase searches (specify thoroughness level)
• Use general-purpose subagent for complex analysis
• Each should return specific file:line references and code examples
• Launch all in a single message for parallel execution
• Wait for ALL to complete before proceeding