plan-gate

What this skill does

# Plan Gate

Proactively assess task complexity before implementation begins and route to the appropriate planning mechanism. This skill acts as a lightweight decision point that prevents both under-planning (jumping straight into code on a multi-phase effort) and over-planning (running a full `/plan-improvements` cycle for a simple bug fix).

**This skill is read-only. It NEVER modifies files, commits, or pushes.**

## Proactive Triggers

Claude should proactively suggest this skill when ALL of these are true:

1. The user has requested an implementation task (not research, not a question)
2. The task appears non-trivial — any of these signals:
   - Will likely touch more than 3 files
   - Involves architectural decisions or trade-offs
   - Requires phased delivery or has internal dependencies
   - The user's description is ambiguous about scope
   - Multiple valid implementation approaches exist
   - The task mentions "refactor", "redesign", "overhaul", "migrate", "add feature", or similar scope indicators
3. No planning has been done yet (no active IMPLEMENTATION_PLAN.md for this work)

**Do NOT fire when:**
- The task is a single-file fix, typo, or small tweak
- The user has already invoked a planning command
- The user explicitly says "just do it" or "skip planning"
- The task is purely research or exploration

## Instructions

### Step 1: Quick Scope Assessment

Spend no more than 30 seconds on this. Do NOT do a deep codebase analysis — that's what the planning commands are for. Just answer these questions by scanning the request and doing minimal file checks:

**Task Signals:**

| Signal | Check |
|--------|-------|
| Files affected | Will this touch > 3 files? > 10 files? |
| Phasing needed | Can this be done in one pass, or does it need stages? |
| Dependencies | Are there ordering constraints between sub-tasks? |
| Ambiguity | Is the scope clearly defined, or does it need scoping? |
| Requirements docs | Do BRD/PRD/TDD files exist in the repo? |
| Existing plan | Does IMPLEMENTATION_PLAN.md already exist? |
| Codebase familiarity | Has `/prime` been run recently? Is CLAUDE.md comprehensive? |

### Step 2: Check for Existing Artifacts

Quickly check for these files (Glob, not deep reads):

```text
IMPLEMENTATION_PLAN.md    # Existing plan — may just need /implement-plan
RECOMMENDATIONS.md        # Previous analysis — plan may already exist
PROGRESS.md               # Active execution — plan is in flight
PRD*.md, BRD*.md, TDD*.md # Requirements docs — /create-plan is appropriate
docs/requirements/*.md    # Requirements in docs folder
```

### Step 3: Route to the Right Approach

Based on the assessment, recommend ONE of these paths:

#### Path A: Just Do It (No Planning Needed)

**When:** Task is clearly scoped, touches 1-3 files, no ambiguity, single-session work.

```text
This looks straightforward — I'll proceed directly.
```

Do not display the routing table below. Just start working.

#### Path B: Native Plan Mode

**When:** Task is moderate (4-8 files), single feature, fits in one session, no requirements docs to synthesize.

```text
Scope Assessment
================
This task is moderate in scope — it will touch several files but fits within
a single session. I'll enter plan mode to design the approach before coding.

Recommended: Native plan mode (interactive, immediate)
```

Then enter plan mode to design the approach before coding.

#### Path B.5: /batch (Parallel Decomposition)

**When:** Task naturally decomposes into 5–30 independent units that can run concurrently with no ordering constraints between them. Each unit is self-contained — no unit's output feeds another's input. Examples: running the same transformation across many files, migrating multiple independent endpoints, updating 10+ skill frontmatter fields with the same pattern.

Signals: user description contains "each", "all N of", "across all", "for every"; task is essentially the same operation repeated across multiple discrete targets.

```text
Scope Assessment
================
This task decomposes into [N] independent units that can run concurrently.
Sequential execution is unnecessary — there are no ordering constraints
between units.

Recommended: /batch
  - Dispatches one background agent per unit (up to 30)
  - Each agent runs in its own isolated worktree
  - Completes in parallel rather than sequentially
  - Suitable when units are fully independent (no shared state)

Trade-off: /batch loses visibility into per-unit progress in real time.
If you need step-by-step review, use Path B (native plan mode) instead.

Shall I decompose and dispatch via /batch?
```

#### Path C: /plan-improvements

**When:** Task involves improving or refactoring existing code, no formal requirements docs, need to analyze current state first.

```text
Scope Assessment
================
This is a multi-phase effort that needs structured planning. It involves
improving existing code, so I should analyze the codebase first to produce
prioritized recommendations and a phased implementation plan.

Recommended: /plan-improvements
  - Deep investigation of root causes and interrelationships between issues
  - Generates RECOMMENDATIONS.md with integrated, architecturally coherent fixes
  - Generates IMPLEMENTATION_PLAN.md with phased work items
  - Produces cohesive changes, not isolated patches
  - Execute later with /implement-plan

Estimated planning time: [size-based estimate]

Shall I run /plan-improvements now?
```

#### Path D: /create-plan

**When:** Requirements documents (BRD, PRD, TDD) exist in the repo — the task is requirements-driven, not codebase-driven.

```text
Scope Assessment
================
I found requirements documents that should drive this implementation:
  - [list discovered docs]

The right approach is to generate a structured implementation plan from
these requirements.

Recommended: /create-plan
  - Deep investigation of each requirement's impact and dependencies
  - Maps interrelationships between requirements to avoid conflicting changes
  - Synthesizes requirements into integrated, architecturally coherent phases
  - Generates phased IMPLEMENTATION_PLAN.md
  - Execute later with /implement-plan

Shall I run /create-plan now?
```

#### Path D.5: /ultra-plan (Deep Pre-Planning)

**When:** Task needs more than 30 minutes of planning OR involves a high-risk architectural decision where getting the design wrong is expensive. Use when the scope is clear enough to know it's large, but the *approach* is uncertain — competing valid architectures, significant unknowns, or the task will shape work for weeks.

Signals: user says "I'm not sure how to approach", "there are a few ways we could do this", "this needs careful design"; task involves replacing a core system, choosing between fundamentally different architectures, or integrating a new platform/protocol.

```text
Scope Assessment
================
This task involves [architectural complexity / scope / unknowns]. Before
generating an implementation plan, a deep pre-planning pass is warranted
to evaluate competing approaches and surface hidden constraints.

Recommended: /ultra-plan
  - Multi-agent structured analysis of the problem space
  - Evaluates trade-offs across competing approaches
  - Surfaces dependencies and risk factors before committing to a path
  - Produces a design decision record + recommended implementation strategy
  - Run /create-plan or /plan-improvements after /ultra-plan to generate IMPLEMENTATION_PLAN.md

When to skip: If you already know the approach and just need a plan, go
directly to /create-plan or /plan-improvements (Path C or D).

Shall I run /ultra-plan for pre-planning analysis?
```

Note: `/ultra-plan` is the personal-plugin deep pre-planning skill. Anthropic's built-in `/ultraplan` (no hyphen) is a distinct feature.

#### Path E: /implement-plan (Resume)

**When:** IMPLEMENTATION_PLAN.md already exists with incomplete work items.

```text
Scope Assessment
================
An existing