TRIP-1-plan

Planning Mode

You are now in planning mode for [PROJECT_NAME].

Prerequisites - Read First

Before creating any plan, you MUST read ALL THE LINES of:

1. @docs/ARCHI.md - Understand current system architecture
2. [ADAPT_TO_PROJECT: optional — list additional living docs a plan must respect (e.g. an operations manual, a public API contract), each with the condition under which it must be read ("only if the feature touches X"). Remove this line if the project has none.]

Your Task

Plan the following feature: $ARGUMENTS

YOLO: if the arguments contain --yolo, strip the flag from the feature description and run in YOLO mode — Step 4's approval question is skipped and the plan chains directly into TRIP-2-implement once Codex returns APPROVED. NEEDS_REWORK always cancels YOLO and falls back to the normal Step 4 question. Discovery questions (Step 1) still run — YOLO removes the end gate, not the understanding phase.

Step 1: Discovery & Clarification (Interactive)

Do NOT start writing a plan immediately. First, engage in a discovery conversation to fully understand the user's intent.

1.1 Initial Understanding

After reading the feature request, summarize your understanding in 2-3 sentences, then use the AskUserQuestion tool to present clarifying questions with structured options.

Frame questions around:

• Scope: What's included vs excluded?
• Behavior: How should it work from the user's perspective?
• Constraints: Any technical limitations, deadlines, or dependencies?
• Priority: What's most important if trade-offs are needed?

For each question, provide 2-4 concrete options based on your analysis of the codebase and the feature request. Always let the user provide custom input via the built-in "Other" option.

Every question ships a recommendation. For each question, pick the option you'd choose and mark it — put it first in the options list with (Recommended) appended to its label. If you genuinely have no lean, say so in the option descriptions rather than faking a recommendation.

1.2 Alignment: keep asking until aligned

The goal is a shared understanding of the feature, not a fixed number of questions. Batch up to 4 questions per AskUserQuestion call (one "round"), and keep asking follow-up rounds while genuine blocking ambiguities remain. Stop as soon as none do — do not manufacture questions to fill a quota.

A safety ceiling caps the questioning if you're still finding gaps, scaled by plan size:

When a ceiling is hit, summarize what you know, note open assumptions explicitly, and proceed to Step 2. Don't over-question: the Codex plan review (Step 3) backstops anything discovery misses, so lean toward proceeding rather than squeezing out every edge case.

User escape hatch. From the second round onward, include a standing option worded like "Use your recommendations for everything remaining → write the plan" as one of the choices. If the user picks it, stop asking immediately, adopt your recommended answer for every still-open question, and proceed to Step 2. The user decides when alignment is enough — this option lets them, without waiting for the ceiling.

After discovery ends (aligned, ceiling hit, or escape hatch), proceed directly to writing the plan (Step 2).

Step 2: Plan Document Creation

Once understanding is confirmed, create the plan document.

File Naming

Depending on the feature (major, minor, patch), propose a new version using SemVer (x.y.z) and create: docs/1-plans/F_[version]_[feature-name].plan.md

Required Sections

# [Feature Name] Implementation Plan

## Overview

[2-4 sentences describing the feature and its purpose]

## Problem Statement (if applicable)

[Current limitations/issues this feature addresses]

## Solution Architecture

[High-level design approach]

## Implementation Details

### 1. [Component/Module/File Name]

**File**: `path/to/file`

[Detailed description of changes needed]

**Current state** (if modifying existing):
[Describe what currently exists]

**Modifications**:

- Specific change 1 (around line X)
- Specific change 2 (around line Y)

### 2. [Next Component/Module/File]

[Continue with same pattern]

## Technical Considerations

[ADAPT_TO_PROJECT: Replace with project-specific technical concerns during Init]

- **Pattern Usage**: Which existing patterns to follow (from ARCHI.md)
- **[Concern 1]**: [Description]
- **[Concern 2]**: [Description]
- **Edge Cases**: [Relevant edge cases for this feature]

## Files to Modify/Create

[Comprehensive numbered list with purposes]

1. `path/to/file1` (modify) - Purpose description
2. `path/to/file2` (new) - Purpose description

## Type Definitions (if applicable)

[New types, interfaces, structs, or modifications to existing ones]

## Performance & Cost Impact (if applicable)

[Expected performance implications]

## Backward Compatibility (if applicable)

[Migration strategy if needed]

## Test Impact

[2-5 bullets: which existing tests the change affects, what new logic will need tests, whether an integration/E2E check applies. No test code — the TRIP-2 testing gate consumes this section.]

## Documentation Impact

[Mandatory. List every document OUTSIDE the TRIP docs that this feature will leave outdated, with one line each on what becomes stale. If none are affected, write "None". The TRIP-3 Documentation Sync step consumes this section before the release commit. Always evaluate the candidates below.]

[ADAPT_TO_PROJECT: During Init, replace this block with the project's actual living docs — every non-TRIP document that code changes can leave stale. Typical candidates: `README.md` (quick start, repo structure tree, command reference), module/subdirectory READMEs, operations or user manuals, reference `.md` specs living next to the code, contributor guides (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`). One bullet per doc with when it's affected.]

## To-dos

### Phase 1: [Phase Name] (if multiple phases are needed) or simply skip title if only one phase is needed

- [ ] Task description
- [ ] Another task

### Phase 2: [Phase Name] (if applicable)

- [ ] Task description
- [ ] Another task

**Note**: For simple plans, a single phase is sufficient. Split into multiple phases only for complex features requiring sequential implementation.

**Note — slice vertically, not horizontally**: When a feature needs multiple phases, whenever possible make each phase a **thin end-to-end slice** (e.g. schema → service → minimal UI touch) that is verifiable on its own, so the **first** phase already produces something you can exercise. Do NOT structure phases as one whole layer at a time ("all schema", then "all API", then "all UI") — that leaves nothing testable until the end and makes course-correction expensive. Order phases so the thinnest working path lands first; later phases thicken it (more cases, edge handling, admin views, polish).

**Note**: Do NOT write test code during planning — the Test Impact section above only names what the TRIP-2 testing gate will run and author.

Quality Standards

• Zero Ambiguity: Every step must be clear and actionable
• File-Level Specificity: List exact files and functions to modify
• Architecture Alignment: Must conform to existing patterns in ARCHI.md
• Risk Assessment: Highlight potential failure points

Step 3: Codex Second-Opinion Review

Before the user sees the plan, run the Codex plan review loop. Always run it — no confirmation question. The user gets exactly one decision point in this skill, and it comes after the plan is reviewed (Step 4).

Loop

1. Start: bash .claude/skills/codex-plan-review/scripts/start.sh --prompt-file .claude/skills/codex-plan-review/prompts/start.tpl <plan-path>
2. Parse trailing tag: APPROVED -> Step 4. NEEDS_REWORK -> surface to user. REQUEST_CHANGES -> continue.
3. Address findings critically — quote each P1/P2, push back on incorrect ones, fix legitimate ones by editing the plan in place.
4. Write implementer notes (1-3 sentences): which findings you fixed, which you pushed back on and why, any user decisions that override existing docs or environment limitations that can't be resolved in the plan.
5. Resume with notes:

   bash .claude/skills/codex-plan-review/scripts/resume.sh \
       --prompt-file .claude/skills/codex-plan-review/prompts/resume.tpl \
       --notes "Fixed X. Pushed back on Y because Z. User decided W." \
       <plan-path>
   

   -> back to step 2.
6. No cap — keep iterating until Codex returns APPROVED.

Surface Codex reviews verbatim. Keep edits scoped to findings. Reset thread (reset.sh <plan-path>) only if context is genuinely confused.

Step 4: User Review

After the Codex review converges, present a summary:

• Feature: [name]
• Approach: [1-2 sentences]
• Files affected: [count] files ([list key ones])
• Estimated complexity: [simple/moderate/complex]
• Codex status: [APPROVED after N rounds / NEEDS_REWORK surfaced to you]

YOLO mode: present the summary above (so the record exists), then skip the question and proceed directly into TRIP-2-implement as if the user had answered "Approved — implement now". (A NEEDS_REWORK Codex status always cancels YOLO — ask the question normally.)

Otherwise, one AskUserQuestion — the single decision point of this skill:

• Question: "Review the plan at docs/1-plans/F_x.y.z_feature-name.plan.md. How to proceed?"
• Options:
  • "Approved — implement now" → continue straight into TRIP-2-implement with this plan
  • "Approved — stop here" → plan saved, no implementation
  • "Rework" → the user provides feedback as text

Handle the answer:

• Rework: update the plan from the user's feedback, then re-present. Run another Codex pass if the changes are substantive.
• Other (custom input): handle accordingly.

Approval and the implement-now decision are one question on purpose — approving a plan and choosing when to build it is a single thought, and splitting it into two prompts buys nothing.

IMPORTANT: No Code Implementation

DO NOT write code snippets or implement anything during planning.

This is a high-level planning phase only. Your plan should describe:

• WHAT needs to be done (features, changes, structures)
• WHERE changes will happen (files, modules, functions)
• WHY certain approaches are chosen (trade-offs, rationale)

But NOT:

• Actual code implementations
• Detailed algorithm code

Keep it architectural and descriptive. Code comes in the TRIP-2-implement phase.

[ADAPT_TO_PROJECT: Guidance Sections]