gistfile1.txt

                                                                                                 16:25:49
---
description: Session orchestrator - work on next task or new request
---

# /next - Session Orchestrator

Determine what to work on next, manage plans, execute through FSM workflows.

---

## ⚠️ CRITICAL: STATE 2 APPROVAL GATE

**❌ FORBIDDEN** (task FAILS if violated):
- Proceeding to STATE 3 (execution) without STATE 2 approval
- Interpreting silence as approval
- Writing/editing code before user says an APPROVED_WORD

**✅ REQUIRED** (task INCOMPLETE without):
- Wait for APPROVED_WORD before any code execution
- APPROVED_WORDS: `yes`, `ok`, `go ahead`, `proceed`, `do it`, `approved`, `y`
- Any response NOT in APPROVED_WORDS = STOP and clarify

**VERIFICATION before STATE 3:**
- [ ] User message contains an APPROVED_WORD (exact match, case-insensitive)
- [ ] Approval was for THIS specific plan (not previous conversation)

⚠️ DO NOT EXECUTE CODE UNTIL BOTH BOXES CHECKED

---

## Invocation

```
/next                    # Find natural next or present options
/next continue           # Next task from plan (skip approval only if prior approval covers it)
/next phase 2            # Work on specific phase
/next task-2-1           # Work on specific task
/next status             # Show plan/todo status (read-only, no execution)
/next <natural language> # New ad-hoc request
```

---

## Command Reference

### `/next` (no arguments)
**Purpose:** Find the natural next action based on current state.
**Behavior:** Checks active plans, todos, git status, test failures in priority order.
**Example:**
```
User: /next
Agent: [Checks state] You have 3 pending todos from the auth refactor plan.
       Next task: "Migrate login endpoint to new auth pattern"
       Resume this task? (say 'yes' to continue)
```

### `/next continue`
**Purpose:** Resume work on the current plan without re-presenting options.
**Behavior:** Picks up where you left off. Only skips approval if prior approval covers remaining work.
**Example:**
```
User: /next continue
Agent: [Marks next todo in_progress, continues execution]
```

### `/next phase N` / `/next task-X-Y`
**Purpose:** Jump to a specific phase or task in a multi-phase plan.
**Behavior:** Locates the specified phase/task and presents it for approval.
**Example:**
```
User: /next phase 2
Agent: Phase 2: Migrate existing usages to new pattern
       Tasks: [list of phase 2 tasks]
       Proceed with Phase 2? (say 'yes' to continue)
```

### `/next status`
**Purpose:** Display current plan/todo status without taking any action.
**Behavior:** READ-ONLY. Shows what's complete, in-progress, pending. Does NOT execute anything.
**Example:**
```
User: /next status
Agent: ## Plan Status: Auth Refactor

       ✅ Completed (2/5):
       - Add new AuthService class
       - Write unit tests for AuthService

       🔄 In Progress (1/5):
       - Migrate login endpoint

       ⏳ Pending (2/5):
       - Migrate logout endpoint
       - Remove old auth helpers

       No action taken. Use `/next continue` to resume.
```

### `/next <natural language>`
**Purpose:** Start a new ad-hoc request or task.
**Behavior:** Interprets your request, determines work type, enters STATE 1 (Planning).
**Example:**
```
User: /next add rate limiting to the API
Agent: [Investigates codebase, drafts implementation plan, presents for approval]
```

---

## Finding Natural Next

Check in order:

1. **Active plan with in_progress task** → Resume it
2. **Active plan with pending tasks** → Start next task
3. **Plan complete** → All todos marked complete + tests pass + no pending items
4. **Uncommitted git changes** → Continue, review, or commit
5. **Recent test failures** → Fix or acknowledge
6. **No obvious next** → Ask user what to work on

---

## FSM States (All Workflows)

```
STATE 1: PLANNING     → Define approach, present to user
STATE 2: APPROVAL     → ⚠️ BLOCKING GATE - wait for APPROVED_WORD
STATE 3: EXECUTION    → Do the work (ONLY after STATE 2 approval)
STATE 4: VALIDATION   → Verify complete
```

### STATE 2: Approval Gate (CRITICAL)

| User Response | Action |
|---------------|--------|
| APPROVED_WORD (`yes`, `ok`, `go ahead`, `proceed`, `do it`, `approved`, `y`) | → STATE 3 |
| `no`, `wait`, `stop`, `hold` | STOP - ask what to change |
| Silence / No response | WAIT - do not proceed |
| Anything else | ASK: "Should I proceed? Please say 'yes' or 'go ahead' to confirm." |

❌ WRONG:
```
User: "That looks interesting"
Agent: [proceeds to implement]
```
Why wrong: "interesting" is NOT an APPROVED_WORD. Agent must ask for explicit approval.

✅ CORRECT:
```
User: "That looks interesting"
Agent: "Should I proceed with this plan? Please confirm with 'yes' or 'go ahead'."
User: "yes"
Agent: [proceeds to implement]
```

**⚠️ REMINDER: NEVER proceed to STATE 3 without APPROVED_WORD.**

---

## Work Type Detection

| Indicators | Type |
|------------|------|
| "How does...", "Where is...", "Find...", "What is..." | Investigation |
| "Add...", "Implement...", "Create...", "Build..." | Implementation |
| "Refactor...", "Migrate...", "Change X to Y", "Rename..." | Refactor |
| "Remove...", "Delete...", "Clean up...", "Drop..." | Cleanup |
| Ambiguous | ASK USER before proceeding |

---

## Investigation Workflow

### STATE 1: Plan
- Identify question to answer
- Choose strategy: Task/Explore (broad) vs Grep (specific) vs Read (known file)

### STATE 2: Approval
```
Research Plan: [question]
Strategy: [approach]
Scope: [files/modules]
Proceed? (say 'yes' or 'go ahead')
```
⚠️ WAIT for APPROVED_WORD

### STATE 3: Execute
- Run searches
- Document findings with `file:line` references
- Capture actual code, not summaries

### STATE 4: Validate
- [ ] Question answered with code references
- [ ] No assumptions without evidence

---

## Implementation Workflow

### STATE 1: Plan

**Priority order (REQUIRED):**
1. Can we DELETE to achieve this? → prefer
2. Can we MODIFY existing code? → next best
3. Must we ADD new code? → only if 1-2 impossible

Checklist:
- [ ] Read refactor_plan.json if exists
- [ ] Research current architecture (use Task/Explore for broad search)
- [ ] Check CLAUDE.md for patterns
- [ ] Draft approach with delete > modify > add options

### STATE 2: Approval
```
Implementation Plan: [feature]

Option A (DELETE + modify): [approach] → Net: -X lines
Option B (MODIFY only): [approach] → Net: +Y lines
Option C (ADD new): [approach] → Net: +Z lines

Recommendation: Option [X]
Files affected: [list]
Completion criteria: [list]

Proceed with Option [X]? (say 'yes' or 'go ahead')
```
⚠️ WAIT for APPROVED_WORD - do NOT proceed without it

### STATE 3: Execute

**❌ FORBIDDEN:**
- Editing file without reading it first
- Having >1 todo as `in_progress`
- Batching todo completions

**✅ REQUIRED:**
- Read file → Edit file (this order always)
- Use Edit tool (not bash sed/awk)
- Run tests after each change
- Mark todo complete IMMEDIATELY after finishing (same turn)
- Max 1 todo `in_progress` at any time

### STATE 4: Validate
- [ ] All tests pass
- [ ] Build succeeds
- [ ] All completion criteria from STATE 2 met
- [ ] refactor_plan.json updated if applicable

---

## Refactor Workflow

Same FSM as Implementation, with multi-phase approach:

1. **Add new pattern** alongside old → tests pass → commit
2. **Migrate usage** to new pattern → tests pass → commit
3. **Remove old pattern** → tests pass → commit

Present in STATE 2:
- Breaking changes identified
- Rollback plan defined
- Each phase as separate approval if large

---

## Cleanup Workflow

Same FSM as Implementation. Before STATE 2:

- Grep to find ALL usages (include count)
- Verify safe to remove
- List affected files

Present in STATE 2:
```
Cleanup: [what's being removed]
Usage search: [X references found in Y files]
Why safe: [justification - e.g., "0 remaining usages after migration"]
⚠️ Deletions are irreversible. Proceed? (say 'yes' or 'go ahead')
```

---

## Tool Selection

| Task | ✅ Use | ❌ NOT |
|------|--------|--------|
| Broad codebase search | Task/Explore agent | Manual grep loops |
| Specific pattern | Grep tool | bash grep/rg |
| Read file | Read tool | bash cat/head/tail |
| Edit file | Edit tool | bash sed/awk |
| Track progress (>3 steps) | TodoWrite | Mental tracking |

---

## Todo Management

**❌ FORBIDDEN:**
- >1 todo with status `in_progress`
- Completing multiple todos in one batch
- Skipping TodoWrite for tasks with >3 steps

**✅ REQUIRED:**
- Exactly 1 todo `in_progress` at any time
- Mark complete IMMEDIATELY after task done (not at end of session)
- Create todos BEFORE starting multi-step work

❌ WRONG:
```
[completes task 1]
[completes task 2]
[completes task 3]
[marks all three complete at once]
```

✅ CORRECT:
```
[marks task 1 in_progress]
[completes task 1]
[marks task 1 complete, marks task 2 in_progress]
[completes task 2]
[marks task 2 complete, marks task 3 in_progress]
...
```

---

## Anti-Patterns Summary

| ❌ Don't | ✅ Do Instead | Consequence |
|----------|---------------|-------------|
| Code without STATE 2 approval | Wait for APPROVED_WORD | Task fails, restart required |
| Interpret "interesting" as approval | Ask: "Should I proceed? Say 'yes' to confirm" | Unwanted changes |
| Create new files when could edit | Edit existing files | Unnecessary complexity |
| Skip tests after changes | Run tests after each change | Broken code undetected |
| Batch todo completions | Mark complete immediately | Stale state |
| Have >1 todo in_progress | ONE at a time | Progress unclear |
| Assume architecture | Investigate first with Task/Explore | Wrong approach |
| Leave half-finished refactors | Complete phase or rollback | Broken codebase |

---

## Completion Checklist

Before reporting task complete:

- [ ] STATE 2 approval was received (APPROVED_WORD in user message)
- [ ] All todos marked complete
- [ ] Tests pass
- [ ] Build succeeds (if applicable)
- [ ] No in_progress todos remaining

⚠️ DO NOT REPORT COMPLETION UNTIL ALL BOXES CHECKED