Deep Analysis Workflow

Execute a structured exploration + synthesis workflow using Agent Teams with 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 Bash-powered investigation.

This skill can be invoked standalone or loaded by other skills as a reusable building block. Approval behavior is configurable via .claude/agent-alchemy.local.md.

Settings Check

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

1. Read settings file:

   • Check if .claude/agent-alchemy.local.md exists
   • If it exists, read it and look for a deep-analysis section with nested settings:

     - **deep-analysis**:
       - **direct-invocation-approval**: true
       - **invocation-by-skill-approval**: false
     

   • If the file does not exist or is malformed, use defaults (see step 4)

2. Determine invocation mode:

   • Direct invocation: The user invoked /deep-analysis directly, or you are running this skill 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 file is missing or the deep-analysis section is absent, use defaults:
     • direct-invocation-approval: true
     • invocation-by-skill-approval: false
   • If the file exists but is 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):

   - **deep-analysis**:
     - **cache-ttl-hours**: 24
     - **enable-checkpointing**: true
     - **enable-progress-indicators**: true
   

   • 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 N/6] 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 .claude/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: Use AskUserQuestion to offer:
     • "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 .claude/sessions/__da_live__/checkpoint.md exists
2. If found, read the checkpoint to determine last_completed_phase
3. Use AskUserQuestion to offer:
   • "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 .claude/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 .claude/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.

If ENABLE_PROGRESS = true: Display "[Phase 1/6] Reconnaissance & Planning — Mapping codebase structure..."

1. Determine analysis context:

   • If $ARGUMENTS is provided, use it as the analysis context (feature area, question, or general exploration goal)
   • If no arguments and this skill was loaded by another skill, use the calling skill's context
   • If no arguments 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: Use Glob, Grep, and Read to quickly map the codebase structure. This should take 1-2 minutes, not deep investigation.

   • Directory structure: List top-level directories with Glob (e.g., */ pattern) 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: Use Glob 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: Use Grep to search 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: Grep patterns to find related code
   • Complexity estimate: Low/Medium/High based on file count and apparent structure

   For feature-focused analysis, focus areas should track the feature's actual footprint:

   Example:
   Focus 1: "API routes and middleware in src/api/ and src/middleware/" (auth-related endpoints, request handling)
   Focus 2: "React components in src/pages/profile/ and src/components/user/" (UI layer for user profiles)
   Focus 3: "Data models and services in src/db/ and src/services/" (persistence and business logic)
   

   For general