Plan

---
name: 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 in Codex.
argument-hint: "[feature description or ticket reference]"
---

# Plan

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.

Codex is the primary planner in this workflow. If you also have a separate
Claude workflow available, treat it as an optional second-opinion lane rather
than the source of truth.

## 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
- 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

Use `./plan_base.md` in this skill directory as the template.

### Critical Context to Include

The AI agent only gets the context in the plan plus codebase access. Include:
- Intent / Why
- Verified Repo Truths
- Evidence with exact `file:line-line`
- Locked Decisions
- Documentation URLs when needed
- Code Examples from the codebase
- Gotchas
- Patterns to follow
- Known Mismatches / Assumptions
- Critical Codebase Anchors

### Plan Guidelines

- Required sections are: Summary, Intent / Why, Source Artifacts, Verified Repo
  Truths, Locked Decisions, Known Mismatches / Assumptions, Critical Codebase
  Anchors, Files Being Changed, Reconciliation Notes, Delta Design,
  Architecture Overview, Key Pseudocode, Tasks, Validation, and Open Questions.
- `Verified Repo Truths` contains facts only.
- Every fact needs `Fact`, `Evidence`, and `Implication`.
- Negative or absence-based claims also need `Search Evidence`.
- If it is not proven, it is not a fact.
- Every `MODIFY` path must already exist.
- Do not leak placeholder/example paths into the final plan.
- Keep repo facts separate from proposed changes.
- Mirror current codebase patterns rather than inventing approximate examples.
- Do not add compatibility layers unless the user explicitly asks.
- Do not add unit or integration tests by default.
- Use `[NEEDS CLARIFICATION]` markers instead of guessing.

### Step 2b: Create a Normalized Brief / Intent Artifact

Save a normalized brief / intent artifact at:
`./tmp/plan-artifacts/YYYY-MM-DD-description-brief.md`

This is a compact intent capsule for downstream implementation and review.
Include:
- Problem / outcome summary
- Who this matters for
- Locked decisions already made
- Non-goals / what must not be optimized away
- Success criteria
- Explicit user constraints

The final plan must record this path in `Source Artifacts`.

### Step 2c: Create a Research Dossier

Save a supporting dossier at:
`./tmp/plan-artifacts/YYYY-MM-DD-description-research-dossier.md`

The dossier should:
- behave like a PRP-style supporting artifact, not the final plan
- focus on critical codebase anchors, patterns to reuse, gotchas, external docs,
  and a suggested implementation shape
- use exact `file:line-line` references for repo claims
- include external docs only when they materially reduce risk
- avoid placeholder text and generic examples

## Step 3: Reconcile the Dossier into the Final Plan

Before saving the user-facing plan, compare the provisional plan against the
research dossier and reconcile them.

### Reconciliation Goals
- Import missing anchors from the dossier into the final plan
- Import missing docs, gotchas, and load-bearing constraints
- Preserve the brief's why, locked decisions, and non-goals as first-class
  constraints in the final plan
- Surface factual conflicts between the draft and dossier
- Remove duplicated or low-value sections
- Preserve a clean separation between verified facts, settled decisions, and
  proposed changes

### Reconciliation Rules
- The final plan is authoritative
- The brief / intent artifact is authoritative for why
- Do not paste the dossier wholesale into the plan
- If the plan and dossier disagree, re-check the repo before choosing a side
- If a simplification weakens the brief's intent, surface it rather than hide it
- Do not import unsupported dossier claims into `Verified Repo Truths`
- Keep only the highest-value anchors, patterns, docs, and gotchas
- Add concise `Reconciliation Notes`

### Pre-Save Reality Check

Before saving the plan, verify all of the following:
- Every `MODIFY` path exists
- No placeholder/example paths remain
- Every line anchor was checked in the current checkout
- Every `Verified Repo Truths` bullet includes `Fact`, `Evidence`, and
  `Implication`
- Every negative claim includes `Search Evidence`
- No future/proposal language appears inside `Verified Repo Truths`
- Entry points and integration points match the repo audit
- Code examples match current helper patterns
- The dossier has been compared against the provisional plan
- Any plan-vs-dossier conflicts were resolved or surfaced explicitly

## Step 4: Save the Final Plan and Supporting Artifacts

Save the final reconciled plan as:
`./tmp/ready-plans/YYYY-MM-DD-description.md`

Save the supporting research dossier as:
`./tmp/plan-artifacts/YYYY-MM-DD-description-research-dossier.md`

Save the normalized brief / intent artifact as:
`./tmp/plan-artifacts/YYYY-MM-DD-description-brief.md`

Only the reconciled plan belongs in `ready-plans`.

## Step 5: Review and Present

After saving the plan, run the review gates.

1. Run a skeptical review against the standards in `plan-reviewer`.
2. If you can run a fresh second review context, do it and compare results.
3. If you are operating alongside a separate Claude workflow, you may use that
   as the parallel second-opinion lane, but Codex remains the primary planner.
4. Split findings into:
   - Auto-fixable
   - Needs user input
5. Apply all auto-fixable changes silently.
6. Do not surface questions until all active review lanes are complete and their
   findings are merged.

### Present to the User

- Plan Summary: 3-5 bullets
- Questions for You: only genuine decisions or unresolved ambiguity
- Plan Link: `./tmp/ready-plans/[filename]`
- Optional links:
  - Brief / intent artifact
  - Research dossier
- End with: `Want to run another review pass, or is this ready to implement?`

If the user wants changes or another review pass, apply the changes and rerun a
fresh review.

Do not treat the plan as ready if factual blockers remain unresolved.

## Step 6: Return the Plan — Do Not Implement

Once the user confirms the plan is ready, tell them:

```text
Plan finalized! To implement, run:

/implement ./tmp/ready-plans/[filename]
```

Your job ends here. Do not start implementing the plan in the same step.

## Quality Checklist

- [ ] Supporting research dossier created
- [ ] Supporting brief / intent artifact created
- [ ] Existing file paths verified in-session
- [ ] No placeholder/example paths leaked from the template
- [ ] Plan includes `Intent / Why` and `Source Artifacts`
- [ ] Verified Repo Truths contains facts only
- [ ] Every verified fact has exact evidence
- [ ] Every negative claim has search evidence
- [ ] High-value anchors/docs/gotchas from the dossier were reconciled into the
      plan or intentionally dropped
- [ ] The brief's why, locked decisions, and non-goals survived reconciliation
- [ ] Validation gates are executable by AI
- [ ] References existing patterns
- [ ] Clear implementation path
- [ ] Error handling documented