deep-analysis

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 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
4. If the file does not exist or is malformed, use defaults (see step 4)

1. Determine invocation mode:
2. Direct invocation: The user invoked this skill directly
3. Skill-invoked: Another skill 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

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):
2. cache-ttl-hours: Number of hours before exploration cache expires. Default: 24. Set to 0 to disable caching entirely.
3. enable-checkpointing: Whether to write session checkpoints at phase boundaries. Default: true.
4. enable-progress-indicators: Whether to display [Phase N/6] progress messages. 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 is 0 AND checkpointing is disabled.

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 the configured TTL hours of now
6. Config files referenced in config_checksum haven't been modified since the cache was written
7. If cache is valid:
8. Skill-invoked mode: Auto-accept the cache. 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 — Skip to Phase 6 step 2
11. Refresh analysis — Proceed normally
12. If cache is invalid or absent: Proceed normally

Step 2: Interrupted Session Check

If checkpointing is enabled:

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
5. Start fresh — Archive the interrupted session and proceed normally
6. If not found: proceed normally

Step 3: Initialize Session Directory

If checkpointing is enabled and no cache hit:

1. Create .agents/sessions/__da_live__/ directory
2. Write a checkpoint.md with session metadata (analysis context, codebase path, start timestamp, current phase)
3. Write a progress.md to track phase completions

Phase 1: Reconnaissance & Planning

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

1. Determine analysis context:
2. If arguments are provided, use them as the analysis context
3. If no arguments and this skill was loaded by another skill, use the calling skill's context
4. If no arguments and standalone invocation, set context to "general codebase understanding"

1. Rapid codebase reconnaissance:

Search for files, read config files, and map the codebase structure. This should take 1-2 minutes, not deep investigation.

• Directory structure: Find top-level directories to understand the project layout
• Language and framework detection: Read config files (package.json, tsconfig.json, pyproject.toml, etc.) to identify primary language(s) and framework(s)
• File distribution: Search for file 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 for feature-related terms 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 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).

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

1. Compose the team plan:

Assemble a structured plan document:

• Analysis context
• Reconnaissance summary (project name, primary language/framework, codebase size, key observations)
• Focus areas with directories, starting files, search patterns, and complexity estimates
• Agent composition table (N explorers using a balanced model, 1 synthesizer using a high-reasoning model)
• Task dependencies (exploration tasks are parallel, synthesis is blocked by all exploration tasks)

1. Checkpoint (if enabled):
2. Update session checkpoint, write team plan and recon summary, append to progress log

Phase 2: Review & Approval

Goal: Present the team plan for user review and approval before allocating resources.

If approval is not required

Skip to Phase 3 with a brief note: "Auto-approving team plan (skill-invoked mode). Proceeding with N explorers and 1 synthesizer."

If approval is required

1. Present the team plan, then prompt the user to choose:
2. Approve — Proceed to Phase 3 as-is
3. Modify — User describes changes (adjust focus areas, add/remove explorers, change scope)
4. Regenerate — Re-run reconnaissance with user feedback

1. If "Modify" (up to 3 cycles): Apply modifications, re-present for approval
2. If "Regenerate" (up to 2 cycles): Re-run Phase 1 Step 2 with feedback, re-compose and re-present

Phase 3: Team Assembly

Goal: Create the team, delegate to agents, create tasks, and assign work using the approved plan.

1. Set up the team for the analysis session

1. Delegate exploration work:
2. Assign N independent explorer agents (one per focus area), each using a balanced-reasoning model
3. Each explorer receives: the codebase path, analysis context, and their specific focus area details
4. Assign 1 synthesizer agent using a high-reasoning model
5. The synthesizer receives: the codebase path, analysis context, and instructions to wait for exploration results

1. Create tasks for tracking:
2. One exploration task per focus area
3. One synthesis task blocked by all exploration tasks

1. Assign exploration tasks with status guards — only assign if status is pending and unowned. Never re-assign a completed or in-progress task.

Phase 4: Focused Explo