deepen-plan

Files (1)

• SKILL.md

SKILL.md (first lines)

# Deepen Plan

## Introduction

**Note: The current year is 2026.** Use this when searching for recent documentation and best practices.

`ce:plan` does the first planning pass. `deepen-plan` is a second-pass confidence check.

Use this skill when the plan already exists and the question is not "Is this document clear?" but rather "Is this plan grounded enough for the complexity and risk involved?"

This skill does **not** turn plans into implementation scripts. It identifies weak sections, runs targeted research only for those sections, and strengthens the plan in place.

`document-review` and `deepen-plan` are different:
- Use the `document-review` skill when the document needs clarity, simplification, completeness, or scope control
- Use `deepen-plan` when the document is structurally sound but still needs stronger rationale, sequencing, risk treatment, or system-wide thinking

## Interaction Method

Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.

Ask one question at a time. Prefer a concise single-select choice when natural options exist.

## Plan File

<plan_path> #$ARGUMENTS </plan_path>

If the plan path above is empty:
1. Check `docs/plans/` for recent files
2. Ask the user which plan to deepen using the platform's blocking question tool when available (see Interaction Method). Otherwise, present numbered options in chat and wait for the user's reply before proceeding

Do not proceed until you have a valid plan file path.

## Core Principles

1. **Stress-test, do not inflate** - Deepening should increase justified confidence, not make the plan longer for its own sake.
2. **Selective depth only** - Focus on the weakest 2-5 sections rather than enriching everything.
3. **Prefer the simplest execution mode** - Use direct agent synthesis by default. Switch to artifact-backed research only when the selected research scope is large enough that returning all findings inline would create avoidable context pressure.
4. **Preserve the planning boundary** - No implementation code, no git command choreography, no exact test command recipes.
5. **Use artifact-contained evidence** - Work from the written plan, its `Context & Research`, `Sources & References`, and its origin document when present.
6. **Respect product boundaries** - Do not invent new product requirements. If deepening reveals a product-level gap, surface it as an open question or route back to `ce:brainstorm`.
7. **Prioritize risk and cross-cutting impact** - The more dangerous or interconnected the work, the more valuable another planning pass becomes.

## Workflow

### Phase 0: Load the Plan and Decide Whether Deepening Is Warranted

#### 0.1 Read the Plan and Supporting Inputs

Read the plan file completely.

If the plan frontmatter includes an `origin:` path:
- Read the origin document too
- Use it to check whether the plan still reflects the product intent, scope boundaries, and success criteria

#### 0.2 Classify Plan Depth and Topic Risk

Determine the plan depth from the document:
- **Lightweight** - small, bounded, low ambiguity, usually 2-4 implementation units
- **Standard** - moderate complexity, some technical decisions, usually 3-6 units
- **Deep** - cross-cutting, high-risk, or strategically important work, usually 4-8 units or phased delivery

Also build a risk profile. Treat these as high-risk signals:
- Authentication, authorization, or security-sensitive behavior
- Payments, billing, or financial flows
- Data migrations, backfills, or persistent data changes
- External APIs or third-party integrations
- Privacy, compliance, or user data handling
- Cross-interface parity or multi-surface behavior
- Significant rollout, monitoring, or operational concerns

#### 0.3 Decide Whether to Deepen

Use this default:
- **Lightweight** plans usually do not need deepening unless they are high-risk or the user explicitly requests it
- **Standard** plans often benefit when one or more important sections still look thin
- **Deep** or high-risk plans often benefit from a targeted second pass

If the plan already appears sufficiently grounded:
- Say so briefly
- Recommend moving to `/ce:work` or the `document-review` skill
- If the user explicitly asked to deepen anyway, continue with a light pass and deepen at most 1-2 sections

### Phase 1: Parse the Current `ce:plan` Structure

Map the plan into the current template. Look for these sections, or their nearest equivalents:
- `Overview`
- `Problem Frame`
- `Requirements Trace`
- `Scope Boundaries`
- `Context & Research`
- `Key Technical Decisions`
- `Open Questions`
- `High-Level Technical Design` (optional overview — pseudo-code, DSL grammar, mermaid diagram, or data flow)
- `Implementation Units` (may include per-unit `Technical design` subsections)
- `System-Wide Impact`
- `Risks & Dependencies`
- `Documentation / Operational Notes`
- `Sources & References`
- Optional deep-plan sections such as `Alternative Approaches Considered`, `Success Metrics`, `Phased Delivery`, `Risk Analysis & Mitigation`, and `Operational / Rollout Notes`

If the plan was written manually or uses different headings:
- Map sections by intent rather than exact heading names
- If a section is structurally present but titled differently, treat it as the equivalent section
- If the plan truly lacks a section, decide whether that absence is intentional for the plan depth or a confidence gap worth scoring

Also collect:
- Frontmatter, including existing `deepened:` date if present
- Number of implementation units
- Which files and test files are named
- Which learnings, patterns, or external references are cited
- Which sections appear omitted because they were unnecessary versus omitted because they are missing

### Phase 2: Score Confidence Gaps

Use a checklist-first, risk-weighted scoring pass.

For each section, compute:
- **Trigger count** - number of checklist problems that apply
- **Risk bonus** - add 1 if the topic is high-risk and this section is materially relevant to that risk

From gvkhosla/compound-engineering-pi, MIT.

More from gvkhosla/compound-engineering-pi