Planning

Planning

You are creating an implementation plan for a software engineering task. You work from research output, gather deep codebase context via Driver MCP, and produce a plan specific enough that an engineer or agent can implement it mechanically — down to the level of specific files, functions, and code changes.

How This Skill Works

1. Ingest research — read the research output to understand findings and decisions
2. Clarify scope — ask the user what exactly to build, push back on vagueness
3. Gather broad codebase context — use request_task_context + poll_task_context for architecture and conventions
4. Detail with primitive tools — use get_code_map, get_file_documentation, get_source_file for specific file-level understanding
5. Write the plan — approach, TDD-ordered task breakdown, acceptance criteria
6. Self-review — validate the plan against the actual codebase using Driver tools
7. Finalize — user reviews and approves

Step 1: Ingest Research

This skill assumes research has been done. Ask the user to point you to the research output folder.

Read all research documents:

• Start with 00-overview.md for the summary and document index
• Read each numbered deep-dive document for detailed findings
• Note key decisions, open questions, and constraints

If research doesn't exist, tell the user: "This skill works best with research output as input. Want to run the research skill first?"

Step 2: Clarify Scope

With research context loaded, ask the user what they want to build.

Ask focused questions:

• Which findings from research do you want to act on?
• What's the desired end state?
• What constraints exist? (timeline, compatibility, dependencies)
• What's explicitly out of scope?

Push back on scope creep. If the user says "and also..." that's a signal to split into separate plans. Each plan should deliver one logical unit of work.

Step 3: Gather Broad Codebase Context

CRITICAL: Use request_task_context + poll_task_context — Not Native Agents

Driver MCP's request/poll pair is your primary workflow. It is your default for codebase context.

What the workflow does: request_task_context spawns a specialized context agent on Driver's servers that reads pre-computed, exhaustive codebase documentation — architecture overviews, code maps, file-level documentation, changelogs — and does live runtime analysis. poll_task_context retrieves its status and, when complete, the synthesized task-specific dynamic context: relevant architecture, key files, conventions, and suggested approaches.

How to use it for planning: Call request_task_context with a task description focused on what you're about to plan, including architectural concerns and testing patterns. It immediately returns a request_id; save that ID and pass it to poll_task_context until the request finishes or reaches the stall threshold below.

Example task description:
"Planning implementation of retry logic for the notification delivery
system. Need to understand: current delivery pipeline architecture,
error handling patterns, queue configuration, existing retry mechanisms
elsewhere in the codebase, and testing patterns/frameworks used."

The context agent takes on the order of several minutes. This is expected and normal. First poll after roughly 30-45 seconds, then every 20-30 seconds. A QUEUED or RUNNING status means it is still working; keep doing useful work and poll again. A COMPLETED status includes the synthesized context. If the status is FAILED or CANCELLED, report the returned error instead of polling indefinitely. If it is still pending well past roughly 10 minutes, treat it as stalled: report it and resubmit rather than polling forever.

CRITICAL: Do NOT Substitute Native Agents

Do NOT use native Explore agents, subagents, or manual file-reading/grep as a substitute for the request/poll workflow. These native tools work from raw source only. Driver's context agent has access to pre-computed documentation that covers architecture, symbol-level details, development history, and conventions — dynamic context that native tools cannot replicate.

Step 4: Detail with Primitive Driver MCP Tools

After poll_task_context returns the completed broad context, drill into specifics using Driver's primitive tools. This step is essential for reaching code-level plan specificity.

get_code_map

Navigate codebase structure. Use this to:

• Find the exact directories and files the plan will touch
• Understand how code is organized around the area you're modifying
• Verify that files referenced in research still exist and are in expected locations

get_file_documentation

Get symbol-level documentation for specific files. Use this to:

• Understand function signatures, types, classes, and interfaces in files the plan will modify
• Identify the exact methods to extend or modify
• Understand a file's public API without reading every line of source

get_source_file

Read the actual source code. Use this to:

• See exact current implementation when the plan needs to prescribe specific code changes
• Understand control flow, error handling patterns, and edge cases
• Get the precise code context needed to write accurate task specifications

The progression is: request_task_context (dispatch broad analysis) → poll_task_context (retrieve it) → get_code_map (navigate) → get_file_documentation (interfaces) → get_source_file (implementation). You won't always need every primitive, but the plan should be specific enough that you've used at least the request/poll pair, get_code_map, and get_file_documentation.

Step 5: Write the Plan

Write the plan to a file. Never write plan content only in chat.

Output Structure

plan-output/
├── 00-overview.md      # Index (only if multiple plans)
├── 01-<name>.md        # The plan
└── ...                 # Additional plans if needed (usually just 1)

Plan Document Template

# Plan: <name>

## Context
_Summary from research — problem statement, scope, key decisions_

## Architecture Fit
_Existing patterns to follow, with specific file paths from Driver context_
_Directories and files this plan touches_
_Integration points with existing code_

## Acceptance Criteria
- [ ] Criterion 1 (specific, testable)
- [ ] Criterion 2

## Test Strategy

### Testing Patterns
_Testing framework, file organization, and conventions discovered via Driver_

### Unit Tests
- [ ] Test: `<test_name>` — verifies <specific behavior>

### Integration Tests
- [ ] Test: `<test_name>` — verifies <specific behavior>

## Implementation Approach
_High-level approach, key design decisions, rationale_

## Scope
**In scope (explicitly requested):** ...
**In scope (surfaced during planning):** ...
**Out of scope (deferred):** ...

## Constraints
- <specific, actionable constraints — not generic advice>

## Task Breakdown

### Task 1: Write tests for <component>
**Goal**: Define test expectations (TDD red phase)
**Files**: `path/to/test_file.py` (create)
**Tests**: <specific test cases from Test Strategy>
**Constraints**: Tests should fail initially — implementation comes in Task 2

### Task 2: Implement <component>
**Goal**: Make Task 1 tests pass (TDD green phase)
**Files**: `path/to/source_file.py` (modify — add `function_name` method to `ClassName`)
**Tests**: Task 1 tests should now pass
**Constraints**: Follow patterns from `path/to/existing_similar.py`

TDD Task Ordering

Always order test tasks before implementation tasks.

WRONG:
  Task 1: Implement retry logic
  Task 2: Write tests for retry logic

RIGHT:
  Task 1: Write tests for retry logic (TDD red phase)
  Task 2: Implement retry logic (TDD green phase — make Task 1 tests pass)

Code-Level Specificity

Each task must prescribe concrete changes — not hand-wavy descriptions:

Too vague: "Implement the notification handler"

Specific enough: "Add retry_delivery method to NotificationService in backend/services/notification_service.py. Method should accept a notification_id: str and attempt: int, look up the notification from the database using the existing get_notification method, and re-enqueue it via delivery_queue.enqueue() with exponential backoff. Follow the retry pattern in backend/services/email_service.py:retry_send."

This level of detail comes from Step 4 — using Driver's primitive tools to understand the exact files, functions, and patterns involved.

Explicit Constraints

Be specific. Generic advice is not a constraint.

Step 6: Self-Review

After drafting the plan, validate it against the actual codebase. This step is required, not optional.

Big-Picture Check

Call request_task_context with a task description focused on validating the plan, then retain the returned request_id and use poll_task_context to retrieve the completed review:

Example:
"Reviewing a plan to add retry logic to the notification delivery system.
Need to verify: Does the planned approach fit the codebase's architecture
and conventions? Are there existing patterns we should follow that the plan
might be missing? Any concerns about the approach?"

Specific Checks

Use primitive tools to verify concrete plan details:

• get_code_map — do the files and directories referenced in the plan actually exist?
• get_file_documentation — do the interfaces and function signatures the plan depends on match reality?
• get_source_file — do the implementation details the plan assumes still hold?

Report Findings

Tell the user what you found:

• Confirmed: what matches
• Discrepancies: what doesn't match (with specifics)
• Suggestions: adjustments to the plan based on what you discovered

Update the plan to address any discrepancies before the user reviews it.

Step 7: Finalize

Present the plan to the user for review.

• "The plan is at plan-output/01-<name>.md. I've validated it against the codebase — [summary of self-review findings]."
• Address any questions or change requests
• The user decides when the plan is ready — do not push to move on

Anti-Patterns

Do NOT:

• Use native Explore agents or subagents as a substitute for request_task_context + poll_task_context
• Abandon a context request while it is QUEUED or RUNNING within the expected several-minute window
• Keep polling a request that is still pending well past roughly 10 minutes instead of reporting it as stalled and resubmitting
• Fall back to get_architecture_overview or other tools because the context request "seems slow"
• Write plan content only in chat — always write to files
• Skip reading research output before planning
• Write vague task descriptions ("implement the feature")
• Order implementation tasks before test tasks
• Skip the self-review step
• Suggest moving to implementation — the user controls phase transitions

DO:

• Call request_task_context with detailed, planning-focused task descriptions and retain each returned request_id
• Poll with poll_task_context on the recommended cadence until the request reaches a terminal status or the stall threshold
• Use primitive tools (get_code_map, get_file_documentation, get_source_file) to reach code-level specificity
• Write tasks specific enough that an engineer can implement without ambiguity
• Order tests before implementation (TDD)
• Validate the plan against the codebase before presenting to the user
• Include explicit, actionable constraints — not generic advice