Deep Planner

Deep Planner

Deep Planner turns a complex objective into a grounded execution plan before edits begin. It prioritizes current project evidence over assumptions.

Trigger Conditions

Use this skill when:

• The task affects multiple files, modules, packages, or APIs.
• The work could break user workflows, data, public contracts, or build/test infrastructure.
• The user asks for deep planning, investigation, architecture, impact analysis, or risk analysis.
• $project-commander classifies the task as complex.

Do Not Trigger

Do not use this skill when:

• The user explicitly asks for a quick direct change and the blast radius is tiny.
• The task is purely explanatory and does not depend on project structure.
• A current plan already exists in .agent/PLAN.md and the user asks only to execute the next listed task.

Investigation Rules

1. Read .agent/ memory first.
2. If the project root contains .codegraph/ and CodeGraph MCP/CLI is available, use CodeGraph first for symbols, call chains, impact scope, and architecture relationships.
3. If CodeGraph is missing, stale, incomplete, or not relevant, inspect concrete files with fast local search and targeted reads.
4. Do not initialize CodeGraph unless the user explicitly asks.
5. Confirm current file contents before editing files that may have changed recently.

Planning Workflow

1. Define the objective, non-goals, and success criteria.
2. Map relevant files, modules, commands, entry points, and data flows.
3. Identify risk categories:

• behavior changes
• compatibility/API changes
• data migration or persistence
• security/privacy
• performance
• test coverage
• deployment/runtime assumptions

1. Break the work into phases with a verification gate after each meaningful phase.
2. Mark the first concrete implementation step.
3. Record assumptions and questions. Ask the user only when a reasonable assumption would be risky.

Required .agent/ Updates

Always update:

• .agent/PLAN.md: phases, success criteria, verification gates.
• .agent/TASKS.md: tasks derived from the plan.
• .agent/LOG.md: investigation summary and files/tools inspected.
• .agent/HANDOFF.md: the current plan and first next action.

Update when relevant:

• .agent/DECISIONS.md: accepted architecture choices or rejected alternatives.
• .agent/PROJECT_BRIEF.md: newly discovered constraints or project conventions.

Other Skills

• Use $persistent-memory first if .agent/ is missing or malformed.
• Return control to $project-commander after producing the plan.
• Use $subagent-orchestrator only if independent research/work streams are allowed and useful.

Subagents

Subagents are optional. Use explorer/architect/reviewer agents only when the user or runtime policy permits delegation. Otherwise, perform role passes locally and log that no real subagents were launched.

Verification Commands

Deep planning itself does not require build/test commands unless the investigation needs a baseline. If a baseline is useful, run cheap read-only checks such as package script discovery, existing test command discovery, or current failing test reproduction.

Output Format

DEEP PLAN
Objective:
Non-goals:
Evidence inspected:
Relevant files/symbols:
Risks:
Phases:
Verification gates:
First implementation step:
Open questions:

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fengsihao23-eng
• Source: fengsihao23-eng/shen-hua
• License: MIT

Install and usage instructions live in the source repository linked above.