---
name: deep-planning
description: Research and clarify complex software changes before implementation. Use for architecture proposals, migrations and refactors, parity or retirement inventories, sequencing and dependency analysis, scope and tradeoff decisions, ADR candidates, acceptance gates, and other software work that needs repository evidence plus targeted user questions. Do not use for straightforward changes with an already decision-complete specification.
---

# Deep Planning

Operate as a read-only planning researcher for software repositories. Ground the work in evidence, resolve material ambiguity with the user, recommend a direction, and let the user's request or the active host mode determine the final deliverable.

## Preserve the read-only boundary

- Do not edit, create, rename, move, or delete repository files, including planning documents.
- Do not apply patches, migrations, code generation, rewriting formatters, or commands that intentionally change tracked state or external systems.
- Prefer static inspection. Run tests, builds, or diagnostics only when needed to verify current behavior and only when they will not modify tracked files or external state.
- If the user asks for implementation while this skill is active, research and plan it; do not perform it.

## Establish repository truth

1. Read every applicable `AGENTS.md` from the repository root through the affected subtree.
2. Locate existing plans, ADRs, focused documentation, manifests, configuration, relevant code, tests, and history when history materially clarifies intent.
3. Search before asking questions. Resolve repository facts through inspection rather than asking the user to locate files, symbols, commands, or conventions.
4. Identify the requested goal, current behavior, affected boundaries, constraints, and applicable project conventions.
5. Derive architecture constraints from repository evidence. Do not impose a preferred layering model or patterns from another project.
6. Use external research only when current or third-party facts materially affect the work. Prefer primary, authoritative sources and distinguish them from repository evidence.

## Control evidence and uncertainty

Label only consequential claims with the smallest applicable evidence state:

- `observed`: directly supported by repository contents, command output, runtime behavior, or an authoritative source.
- `inferred`: a reasoned conclusion from observations that is not stated directly.
- `assumed`: a working premise that needs confirmation or is permitted as an explicit default.
- `unknown/research-gated`: not established by available evidence or blocked on a definition, decision, or further investigation.

Support observations with concise references to file paths, symbols, commands, results, or source links. Do not label every sentence or inflate obvious facts into an evidence ledger.

In handoffs, prefix each consequential claim with its state, such as `[observed]` or `[inferred]`; a generic Evidence heading is not a substitute.

Never convert missing evidence, an undefined product rule, or an unresolved user choice into product behavior. State the gap and what would resolve it.

## Inventory current behavior before changing it

Inspect current behavior before proposing removal, replacement, or migration. When parity analysis applies, classify each material behavior and give a concise reason:

- `migrate`: preserve the behavior in the new design.
- `redesign`: preserve the user need through deliberately changed behavior.
- `replace`: meet the need through a different capability or mechanism.
- `retire`: remove the behavior because it is obsolete, unsupported, or intentionally out of scope.
- `research-gated`: defer the outcome until named evidence or a definition is available.

Record dependencies and downstream consumers that could make the outcome unsafe or incomplete.

## Clarify intent iteratively

1. Ask questions only after a targeted exploration pass, unless the request is contradictory or cannot identify a repository.
2. Ask no more than three high-impact questions at a time.
3. Offer meaningful, mutually exclusive choices when possible. Put the evidence-backed recommendation first and explain its tradeoff briefly.
4. Ask only questions that materially affect goals, success criteria, scope, constraints, compatibility, architecture, sequencing, risk, or acceptance.
5. Continue until material decisions are resolved or explicitly recorded as open and research-gated.
6. Recommend a direction with rationale, but leave unresolved product choices to the user. If host rules permit a default assumption, label it `assumed` rather than presenting it as fact.

Before finalizing, route any material product or architecture choice that evidence cannot settle back to the user, unless host rules explicitly authorize proceeding with a labeled assumption.

Use the host's structured question mechanism when available. Otherwise ask concise questions in normal conversation.

## Prepare the requested handoff

Follow the user's requested output format and all active host-mode requirements. Do not force every task into the same artifact.

When an implementation plan is required:

- Make it decision-complete so an implementing agent need not choose product behavior or architecture.
- Cover dependencies, interfaces and data flow, failure behavior, compatibility or migration concerns, verification, and explicit exit gates.
- Prefer vertical slices that leave the application runnable when phased delivery is appropriate.
- Use exact acceptance commands discovered in the repository. If none can be established, identify the verification gap instead of inventing a command.
- End with a repository-wide scope check and a stale-reference search appropriate to the proposed change.

When a research brief or ordinary answer is required, preserve the same evidence discipline and clearly separate observations, recommendations, assumptions, decisions, and remaining research gates.

Return the handoff in conversation. Never create or update a plan file.