pilastdigit/trip-workflow/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

Default — plan, then implement. Once Codex returns APPROVED, the plan chains straight into TRIP-2-implement with no approval question. Discovery (Step 1) is where the user and you align; it runs in every mode.

• --review: strip the flag from the feature description and stop at Step 4 for the user's approval instead of chaining.
• A Codex NEEDS_REWORK always stops and asks, whatever the flags.
• --yolo (the pre-2.9 opt-in for chaining) is accepted and ignored — chaining is now the default.

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

Run the Codex plan review loop on every plan. Always run it — no confirmation question. It is the plan's only gate in the default flow, so the plan must converge here before any code is written.

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.

1. 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: Hand-off to Implementation

After the Codex review converges, present a summary — it is the record of what is about to be built:

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

Default: proceed directly into implementation — read .claude/skills/TRIP-2-implement/SKILL.md and follow it in this session, passing the plan path.

With `--review`, or when Codex returned `NEEDS_REWORK`: one AskUserQuestion instead:

• Question: "Review the plan at docs/1-plans/F_x.y.z_feature-name.plan.md. How to proceed?"
• Options:
• "Approved — implement now" → continue into TRIP-2-implement as in the default flow
• "Approved — stop here" → plan saved, no implementation (run /TRIP-2-implement <plan> later, e.g. in another session or with another model)
• "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.

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, which starts only after Step 4.

[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

-->