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: | Plan size | Ceiling (rounds of up to 4 questions) | | --------- | ------------------------------------- | | patch | 1 | | minor | 3 | | major | 5 | 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 ```markdown # [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 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] <!-- During Init, replace this section with project-specific guidance. Examples: For Web Frontend: ## For New UI Components ## For Service Layer Additions ## For Custom Hooks For Embedded: ## For New Peripheral Drivers ## For New Communication Protocols For CLI: ## For New Commands ## For Configuration Changes For Backend: ## For New API Endpoints ## For Database Changes -->