adaptive-plan-mode

Files (3)

• EVALUATION.md
• SKILL.md
• SUBAGENT-BRIEF.md

SKILL.md (first lines)

# Adaptive Plan Mode

Read first. Change later.

Goal: highest-confidence solution, least unnecessary **ceremony** — not max analysis, not max speed. Match depth to task: a tiny bug fix earns light reasoning, a cross-service migration earns deep investigation.

Every technical claim traces to evidence — inspected code, logs, tests, docs, tool output, or the user. If a core assumption fails mid-plan, stop, discard the reasoning built on it, and rebuild from what's verified.

Delegate separable investigation (dependency tracing, API research, edge-case exploration) to sub-agents when it keeps the main thread focused — brief template: [SUBAGENT-BRIEF.md](SUBAGENT-BRIEF.md). Don't delegate work small enough to just do yourself.

---

# Phase 1 — Understand the Real Problem

Call `EnterPlanMode` before any investigation or planning begins — switches a Plan/Execute model split (e.g. `opusplan`) onto the planning model, makes the approval gate real. Skip it and every later phase runs on whatever model the session already had.

Before touching tools, work out:

- **What is being asked?** Restate the request in one sentence.
- **What is the real goal?** The visible request may hide a deeper problem ("add retries" → reliability; "slow endpoint" → scaling bottleneck; "refactor module" → maintainability pain).
- **What is out of scope?**
- **What constraints matter?** — latency, throughput, memory, compatibility, migrations, rollback safety, deployment sequencing, cost, observability, developer ergonomics.

Done when: problem, goal, scope, and constraints are stated in your own words. If ambiguity blocks progress, ask one focused clarifying question before moving on.

---

# Phase 2 — Investigate the System

Investigate before proposing implementation: code ownership and structure, callers/consumers, data model and migrations, concurrency, existing conventions, error handling, performance-sensitive paths, tests and fixtures, feature flags, rollout patterns, operational history, third-party constraints.

Before spawning anything, break the investigation into its independent sub-questions (ownership, callers, data model, tests, …) — one broad agent sent to "explore everything" is no different from doing it yourself, so never issue one. Spawn one targeted agent per sub-question, all in a single message so they run concurrently; a task with only one real sub-question earns only one agent. Default `agentType: caveman:cavecrew-investigator` per targeted lookup (read-only, output pre-compressed — keeps the main thread's context cheap). Reach for `agentType: feature-dev:code-explorer` instead when a sub-question needs a full architecture/dependency map before an approach can be chosen.

For a hard bug with several plausible root causes and no way to rule one out from code alone, propose an [agent team](https://code.claude.com/docs/en/agent-teams) to the user instead — teammates test competing hypotheses in parallel and challenge each other's findings, which no sub-agent (report-back-only) can do. Ask before spawning: experimental, needs `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, and costs meaningfully more tokens than sub-agents.

Stop when a new fact could no longer flip the chosen approach. Digging further for its own sake is ceremony too.

---

# Phase 3 — Evaluate Like a Senior Engineer

Go through all seven dimensions — correctness, failure modes, scale & performance, operational safety, maintainability, security, testing — mark each relevant or not, one line why. Full checklist: [EVALUATION.md](EVALUATION.md) — open for security-sensitive, failure-mode-heavy, or unfamiliar-domain work; skip only when every relevant dimension is already obvious from Phase 2 evidence.

Evaluate what the evidence says is actually at risk — not hypothetical bottlenecks or manufactured edge cases nobody will hit.

Done when: all seven dimensions are accounted for and every one marked relevant has been checked against actual evidence, not assumption.

---

# Phase 4 — Compare Alternatives

Generate every approach that's a real fork in the road, investigated, never faked to hit a count. Most tasks have one — say so and move on. When 2-3 genuinely compete, compare them on correctness, implementation complexity, operational cost, blast radius, reversibility, and long-term maintenance burden.

Done when: one approach is chosen and every losing alternative has a one-line reason.

### Decision gate: hand user-owned decisions to `grilling`

Before drafting the plan, audit every decision that affects scope, user-visible behavior, compatibility, rollout, risk tolerance, or a tradeoff between alternatives. Mark each one as either:

- **evidence-settled** — the codebase, tests, docs, or the user's request determines the answer; or
- **user-owned** — more than one reasonable answer remains and the choice depends on the user's priorities, policy, or risk tolerance.

If any decision is **user-owned**, invoke the `grilling` skill now. Pass it the investigated findings and the recommended answer for the first open decision. `grilling` must ask one question at a time and wait for the user's answer; do not draft the plan, call the plan reviewer, or edit files while that interview is pending. Continue the interview until all user-owned decisions have an explicit answer and grilling confirms shared understanding. Record those answers under `Constraints & Assumptions` and `Key Findings` in Phase 5.

If no user-owned decision remains, record `No grilling required: all decisions are evidence-settled` in the plan's `Open Questions` section. Never skip this audit silently and never resolve a user-owned decision by guessing.

If the fork itself is still open after that — an architecture or technology choice, codebase evidence alone can't settle it, and it's hard to revert — spawn `agentType: oryna` here to get an evidence-researched verdict before committing to an approach. This is for the fork, not the plan: oryna is expensive and OSS-research-heavy, wrong tool for reviewing an already-decided plan (that's Phase 6's job).

---

# Phase 5 — Produce the Plan

```md
## Problem
<what is happening and why it matters>

## Constraints & Assumptions
- <verified constraint>

## Key Findings
- <important discoveries>
- <surprises>
- <unknowns>

## Proposed Approach
<recommended solution and rationale>

### Alternatives Considered
- <alternative> — rejected because <reason>

## Risks & Edge Cases
- <risk> — <mitigation>

## Implementation Plan
1. <module/file> — <change>
2. <module/file> — <change>

## Execution Skills
- <skill-name> — <when/why during Phase 7>, or "None" if no other skill applies

## Tests
- <coverage strategy>

## Rollout / Rollback
- <deployment and recovery strategy>

## Open Questions
- <only if genuinely blocking>
```

No ceremony.

Done when: every section has evidence-backed content — no placeholders left.

---

# Trivial Gate

Gates the opus review in both Phase 6 (plan) and Phase 8 (diff). A plan or diff is trivial only if ALL of these hold — any fail means not trivial:

From Rabuno/planship, MIT.

More from Rabuno/planship