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:

   • Check if .agents/agent-alchemy.local.md exists
   • If it exists, read it and look for a deep-analysis section with nested settings
   • If the file does not exist or is malformed, use defaults (see step 4)

2. Determine invocation mode:

   • Direct invocation: The user invoked this skill directly
   • Skill-invoked: Another skill 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

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 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:
   • analysis_context matches the current analysis context (or is a superset)
   • codebase_path matches the current working directory
   • timestamp is within the configured TTL hours of now
   • Config files referenced in config_checksum haven't been modified since the cache was written
3. If cache is valid:
   • Skill-invoked mode: Auto-accept the cache. 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 — Skip to Phase 6 step 2
     • Refresh analysis — Proceed normally
4. 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:
   • Resume from Phase [N+1] — Load checkpoint state, proceed from the interrupted phase
   • Start fresh — Archive the interrupted session and proceed normally
4. 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:

   • If arguments are provided, use them as the analysis context
   • 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"

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

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

   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

4. 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)

5. Checkpoint (if enabled):

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

   • Approve — Proceed to Phase 3 as-is
   • Modify — User describes changes (adjust focus areas, add/remove explorers, change scope)
   • Regenerate — Re-run reconnaissance with user feedback

2. If "Modify" (up to 3 cycles): Apply modifications, re-present for approval

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

2. Delegate exploration work:

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

3. Create tasks for tracking:

   • One exploration task per focus area
   • One synthesis task blocked by all exploration tasks

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