trip-1-plan

name	TRIP-1-plan
description	Plan a new feature following project standards
argument-hint	describe the feature you want to build

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

---

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.

After the user answers, proceed directly to writing the plan (Step 2) — no approach-confirmation question. Ask a follow-up round with AskUserQuestion only if a blocking ambiguity remains (maximum 3 rounds total; if still unclear, summarize what you know and proceed with noted assumptions).

---

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

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





 [ ] Task description
 [ ] Another task



 [ ] Task description
 [ ] Another task

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

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

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