/create-plan

name: create-plan
description: Creates a reconciled implementation plan by combining a structured plan draft with a normalized intent brief and a PRP-style research dossier, then auto-reviews the final plan. Use when planning a new feature or significant change.
argument-hint: "[feature description or ticket reference]"
allowed-tools: Read, Grep, Glob, WebFetch, WebSearch, Write, Task

Create Plan Agent

Feature: $ARGUMENTS

Generate a complete plan for feature implementation with thorough research. The plan must contain enough context for an AI agent to implement the feature in a single pass.

Step 1: Mandatory Repo Audit

Do not start drafting until you have verified the current repo shape for the feature area.

Verify These Facts In-Repo

• Primary entrypoint(s) and integration surfaces relevant to this feature
• Exact module names and singular/plural usage
• Validator/controller/service directory layout in the affected area
• Actual data-model/schema/type source of truth used by this codebase
• Existing user-facing or operator-facing surface(s) this feature extends
• Shared type/export hubs if cross-app types are needed
• Actual validation/build/typecheck workflow used by this repo

Repo Audit Rules

• Do not assume any specific stack or layout. Discover the actual routing,

validation, schema, frontend, and build patterns used by the current repo.

• Every existing file path cited in the final plan must have been opened in this

session.

• Mark every path in the final plan as either `existing` or `new`.
• Never cite a line number unless it was verified in the current checkout.
• Never let template/example paths leak into the final plan.
• If the brief or user request conflicts with repo reality, add a `Known

Mismatches / Assumptions` section that states the conflict and how the plan resolves it.

Step 1b: Clarify Requirements (Only If Needed)

If, after the repo audit, the approach is **genuinely unclear**, ask the user 1-3 targeted design questions. Otherwise, proceed directly.

Step 1c: External Research (Only If Needed)

• Library documentation (include specific URLs)
• Implementation examples
• Best practices and common pitfalls
• Prefer primary documentation when researching external behavior

Step 2: Draft the Plan, Intent Artifact, and Research Dossier

Produce **three artifacts** from the same brief:

1. A **provisional implementation plan** using `./plan_base.md` 2. A **normalized brief / intent artifact** that preserves the why, locked decisions, non-goals, and success criteria in a compact downstream-friendly form 3. A **supporting research dossier** that behaves like a PRP: anchor-dense, selective, and focused on context transfer

The final output shown to the user is the **reconciled plan**, not the dossier.

Step 2a: Draft the Provisional Plan

Using `./plan_base.md` (in this skill's directory) as template.

Critical Context to Include

The AI agent only gets the context in the plan plus codebase access. Include:

• **Intent / Why**: the essence of the brief, including the user outcome,

business/product reason, and what must not be optimized away

• **Verified Repo Truths**: checked facts only, grouped by area
• **Evidence**: exact `file:line-line` support for factual claims, plus search evidence for negative claims
• **Locked Decisions**: product/design choices already settled by the brief or user
• **Documentation**: URLs with specific sections
• **Code Examples**: Real snippets from codebase
• **Gotchas**: Library quirks, version issues
• **Patterns**: Existing approaches to follow
• **Known Mismatches / Assumptions**: brief-vs-repo conflicts, or explicit assumptions
• **Critical Codebase Anchors**: the highest-value repo anchors that an implementer should keep open while coding

Implementation Blueprint

• Start with pseudocode showing approach
• Reference real files for patterns
• Include error handling strategy
• List tasks in implementation order

Plan Guidelines

• **Required Sections** (never leave empty): Summary, Intent / Why, Source Artifacts, Verified Repo Truths, Locked Decisions, Known Mismatches / Assumptions, Critical Codebase Anchors, Files Being Changed (tree with ← NEW / ← MODIFIED markers), Reconciliation Notes, Delta Design, Architecture Overview (proportional to complexity), Key Pseudocode (hot spots and tricky logic only), Tasks (concrete file-level steps in order), Validation, and Open Questions.

• **Verified Repo Truths Are Facts Only**: This section may contain only facts checked in the current repo. No proposed files, pseudocode, or speculative guidance.
• **Evidence Contract**: Every bullet in `Verified Repo Truths` must use this shape:
• `Fact: ...`
• `Evidence: path:line-line`
• `Implication: ...`
• `Search Evidence: ...` is required for absence-based or negative claims such as "does not exist", "is never used", or "no X today".
• **If It Is Not Proven, It Is Not A Fact**: Unsupported claims move to `Delta Design`, `Known Mismatches / Assumptions`, or `Open Questions`.
• **Files Being Changed Must Be Realistic**: Every `MODIFY` path must already exist. Every `CREATE` path must fit the repo's current directory conventions.
• **No Placeholder Paths**: Final plans must not contain `<feature>`, `path/to/example.ts`, `existing-service.ts`, or any other illustrative template path that was not verified in the current repo.
• **Facts vs Proposals Must Be Separated**: Keep repo reality in `Verified Repo Truths`; keep proposed work in `Delta Design`, `Tasks`, and pseudocode.
• **No Proposal Language In Fact Sections**: `Verified Repo Truths` must not contain "we add", "we extend", "this plan", "for this feature", "will", or other future/proposed wording.
• **Code Examples Must Match Current Patterns**: If you include schema/validator/type/code snippets, mirror the helper and naming patterns already used in the repo rather than inventing approximate shapes.

• **No Backwards Compa