git:20260421.bcc041b to git:20260422.d71693a

- 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]"

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

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