Deep Analysis Workflow

Execute a structured exploration + synthesis workflow using hub-and-spoke coordination. The lead performs rapid reconnaissance to generate dynamic focus areas, composes a team plan for review, workers explore independently, and a synthesizer merges findings with deep investigation.

This skill can be invoked standalone or loaded by other skills as a reusable building block. Approval behavior is configurable.

Settings Check

Goal: Determine whether the team plan requires user approval before execution.

1. Read settings:

   • Check configuration for deep-analysis settings
   • Look for a deep-analysis section with nested settings:
     • direct-invocation-approval: Whether to require plan approval when invoked directly (default: true)
     • invocation-by-skill-approval: Whether to require approval when loaded by another skill (default: false)

2. Determine invocation mode:

   • Direct invocation: The user invoked this skill directly, or it is running standalone
   • Skill-invoked: Another skill (e.g., codebase-analysis, feature-dev, docs-manager) loaded and is executing this workflow

3. Resolve settings:

   • If settings were found, use them as-is
   • If the settings are missing, use defaults
   • If the settings are malformed (unparseable), warn the user and use defaults

4. Set REQUIRE_APPROVAL:

   • If direct invocation: use direct-invocation-approval value (default: true)
   • If skill-invoked: use invocation-by-skill-approval value (default: false)

5. Parse session settings (also under the deep-analysis section):

   • cache-ttl-hours: Number of hours before exploration cache expires. Default: 24. Set to 0 to disable caching entirely.
   • enable-checkpointing: Whether to write session checkpoints at phase boundaries. Default: true.
   • enable-progress-indicators: Whether to display phase progress messages. Default: true.

6. Set behavioral flags:

   • CACHE_TTL = value of cache-ttl-hours (default: 24)
   • ENABLE_CHECKPOINTING = value of enable-checkpointing (default: true)
   • ENABLE_PROGRESS = value of enable-progress-indicators (default: true)

Phase 0: Session Setup

Goal: Check for cached exploration results, detect interrupted sessions, and initialize the session directory.

Skip this phase entirely if CACHE_TTL = 0 AND ENABLE_CHECKPOINTING = false.

Step 1: Exploration Cache Check

If CACHE_TTL > 0:

1. Check if .agents/sessions/exploration-cache/manifest.md exists
2. If found, read the manifest and verify:
   • analysis_context matches the current analysis context (or is a superset)
   • codebase_path matches the current working directory
   • timestamp is within CACHE_TTL hours of now
   • Config files referenced in config_checksum haven't been modified since the cache was written (check mod-times of package.json, tsconfig.json, pyproject.toml, etc.)
3. If cache is valid:
   • Skill-invoked mode: Auto-accept the cache. Set CACHE_HIT = true. Read cached synthesis.md and recon_summary.md. Skip to Phase 6 step 2 (present/return results).
   • Direct invocation: Prompt the user to choose:
     • Use cached results -- Set CACHE_HIT = true, skip to Phase 6 step 2
     • Refresh analysis -- Set CACHE_HIT = false, proceed normally
4. If cache is invalid or absent: Set CACHE_HIT = false

Step 2: Interrupted Session Check

If ENABLE_CHECKPOINTING = true:

1. Check if .agents/sessions/__da_live__/checkpoint.md exists
2. If found, read the checkpoint to determine last_completed_phase
3. Prompt the user to choose:
   • Resume from Phase [N+1] -- Load checkpoint state, proceed from the interrupted phase (see Session Recovery in Error Handling)
   • Start fresh -- Archive the interrupted session to .agents/sessions/da-interrupted-{timestamp}/ and proceed normally
4. If not found: proceed normally

Step 3: Initialize Session Directory

If ENABLE_CHECKPOINTING = true AND CACHE_HIT = false:

1. Create .agents/sessions/__da_live__/ directory
2. Write checkpoint.md:

   ## Deep Analysis Session
   - **analysis_context**: [context from arguments or caller]
   - **codebase_path**: [current working directory]
   - **started**: [ISO timestamp]
   - **current_phase**: 0
   - **status**: initialized
   

3. Write progress.md:

   ## Deep Analysis Progress
   - **Phase**: 0 of 6
   - **Status**: Session initialized
   
   ### Phase Log
   - [timestamp] Phase 0: Session initialized
   

Phase 1: Reconnaissance & Planning

Goal: Perform codebase reconnaissance, generate dynamic focus areas, and compose a team plan.

1. Determine analysis context:

   • Accept the following inputs: an analysis context or focus area
   • If no inputs and this skill was loaded by another skill, use the calling skill's context
   • If no inputs and standalone invocation, set context to "general codebase understanding"
   • Set PATH = current working directory
   • Inform the user: "Exploring codebase at: PATH" with the analysis context

2. Rapid codebase reconnaissance: Quickly map the codebase structure. This should take 1-2 minutes, not deep investigation.

   • Directory structure: Search for top-level directories to understand the project layout
   • Language and framework detection: Read config files (package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod, etc.) to identify primary language(s) and framework(s)
   • File distribution: Search with patterns like src/**/*.ts, **/*.py to gauge the size and shape of different areas
   • Key documentation: Read README.md, CLAUDE.md, or similar docs if they exist for project context
   • For feature-focused analysis: Search file contents for feature-related terms (function names, component names, route paths) to find hotspot directories
   • For general analysis: Identify the 3-5 largest or most architecturally significant directories

   Fallback: If reconnaissance fails (empty project, unusual structure, errors), use the static focus area templates from Step 3b.

3. Generate dynamic focus areas:

   Based on reconnaissance findings, create focus areas tailored to the actual codebase. Default to 3 focus areas, but adjust based on codebase size and complexity (2 for small projects, up to 4 for large ones).

   a) Dynamic focus areas (default):

   Each focus area should include:

   • Label: Short description (e.g., "API layer in src/api/")
   • Directories: Specific directories to explore
   • Starting files: 2-3 key files to read first
   • Search terms: Patterns to find related code
   • Complexity estimate: Low/Medium/High based on file count and apparent structure

   b) Static fallback focus areas (only if recon failed):

   For feature-focused analysis:

   Focus 1: Explore entry points and user-facing code related to the context
   Focus 2: Explore data models, schemas, and storage related to the context
   Focus 3: Explore utilities, helpers, and shared infrastructure
   

   For general codebase understanding:

   Focus 1: Explore application structure, entry points, and core logic
   Focus 2: Explore configuration, infrastructure, and shared utilities
   Focus 3: Explore shared utilities, patterns, and cross-cutting concerns
   

4. Compose the team plan:

   Assemble a structured plan document from the reconnaissance and focus area findings:

   ## Team Plan: Deep Analysis
   
   ### Analysis Context
   [context from Step 1]
   
   ### Reconnaissance Summary
   - **Project:** [name/type]
   - **Primary language/framework:** [detected]
   - **Codebase size:** [file counts, key directories]
   - **Key observations:** [2-3 bullets]
   
   ### Focus Areas
   
   #### Focus Area 1: [Label]
   - **Directories:** [list]
   - **Starting fil