deep-analysis

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 shell-powered investigation.

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

Accept the following inputs:

• analysis-context (optional): The focus area, feature, or question to analyze. Defaults to "general codebase understanding" if not provided.

Settings Check

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

1. Read settings file:
2. Check if .agents/agent-alchemy.local.md exists
3. If it exists, read it and look for a deep-analysis section with nested settings:

```markdown

• 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)

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

1. Resolve settings:
2. If settings were found, use them as-is
3. If the file is missing or the deep-analysis section is absent, use defaults:
4. direct-invocation-approval: true
5. invocation-by-skill-approval: false
6. If the file exists but is malformed (unparseable), warn the user and use defaults

1. Set REQUIRE_APPROVAL:
2. If direct invocation: use direct-invocation-approval value (default: true)
3. If skill-invoked: use invocation-by-skill-approval value (default: false)

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

```markdown

• 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.

1. Set behavioral flags:
2. CACHE_TTL = value of cache-ttl-hours (default: 24)
3. ENABLE_CHECKPOINTING = value of enable-checkpointing (default: true)
4. 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:
3. analysis_context matches the current analysis context (or is a superset)
4. codebase_path matches the current working directory
5. timestamp is within CACHE_TTL hours of now
6. 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.)
7. If cache is valid:
8. 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).
9. Direct invocation: Prompt the user to choose:
10. "Use cached results" — Set CACHE_HIT = true, skip to Phase 6 step 2
11. "Refresh analysis" — Set CACHE_HIT = false, proceed normally
12. 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:
4. "Resume from Phase [N+1]" — Load checkpoint state, proceed from the interrupted phase (see Session Recovery in Error Handling)
5. "Start fresh" — Archive the interrupted session to .agents/sessions/da-interrupted-{timestamp}/ and proceed normally
6. 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:

```markdown ## Deep Analysis Session

• analysis_context: [context from arguments or caller]
• codebase_path: [current working directory]
• started: [ISO timestamp]
• current_phase: 0
• status: initialized

```

1. Write progress.md:

```markdown ## 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:
2. If analysis-context input is provided, use it as the analysis context (feature area, question, or general exploration goal)
3. If no input and this skill was loaded by another skill, use the calling skill's context
4. If no input and standalone invocation, set context to "general codebase understanding"
5. Set PATH = current working directory
6. Inform the user: "Exploring codebase at: PATH" with the analysis context

1. Rapid codebase reconnaissance:

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

• Directory structure: Search for top-level directories (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: Search for files matching 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.

1. 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: Search 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 ser