# Planning > Planning - Skill: `driver-ai/planning` (Agent Skill) - Install (CLI): `npx skillmds@latest add driver-ai/planning` - Raw SKILL.md: https://api.skillmd.com/api/skills/driver-ai/planning/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: driver-ai (https://skillmd.com/u/driver-ai) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/driver-ai/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-.md # The plan └── ... # Additional plans if needed (usually just 1) ``` ### Plan Document Template ```markdown # Plan: ## 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: `` — verifies ### Integration Tests - [ ] Test: `` — verifies ## Implementation Approach _High-level approach, key design decisions, rationale_ ## Scope **In scope (explicitly requested):** ... **In scope (surfaced during planning):** ... **Out of scope (deferred):** ... ## Constraints - ## Task Breakdown ### Task 1: Write tests for **Goal**: Define test expectations (TDD red phase) **Files**: `path/to/test_file.py` (create) **Tests**: **Constraints**: Tests should fail initially — implementation comes in Task 2 ### Task 2: Implement **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. | Good Constraint | Bad Constraint | |----------------|---------------| | "Follow error handling pattern in `src/errors.ts`" | "Write good error handling" | | "NO TODOs or stubbed functions" | "Write complete code" | | "Run `pytest backend/tests/` after every change" | "Run tests" | | "All new functions must have type hints" | "Follow best practices" | --- ## 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-.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