teams-deep-analysis

name	teams-deep-analysis
description	Team-based deep exploration and synthesis workflow using Agent Teams with dynamic planning and hub-and-spoke coordination. Use when asked for "teams deep analysis", "team-based analysis", "collaborative analysis", or "teams-deep-analysis".
argument-hint	<analysis-context or focus-area>
model	inherit
user-invocable	true
disable-model-invocation	false
allowed-tools	Read, Glob, Grep, Bash, Task, TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion

Teams 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, workers explore independently, and a deep synthesizer merges findings with Bash-powered investigation.

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

Phase 1: Planning

Goal: Perform codebase reconnaissance, generate dynamic focus areas, create the team, and assign tasks.

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. Load skills for this phase (standalone or within tools plugin only):

   • If invoked standalone or from within the tools plugin:
     • Read ${CLAUDE_PLUGIN_ROOT}/skills/project-conventions/SKILL.md and apply its guidance
     • Read ${CLAUDE_PLUGIN_ROOT}/skills/language-patterns/SKILL.md and apply its guidance
   • If loaded cross-plugin (${CLAUDE_PLUGIN_ROOT} does not contain these skills): Skip this step — the explorer agents load project-conventions and language-patterns automatically via their agent definitions

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

---

Phase 2: Focused Exploration

Goal: Workers explore their assigned areas independently.

• Workers explore their assigned focus areas independently — no cross-worker messaging
• Workers can respond to follow-up questions from the deep synthesizer
• Each worker marks its task as completed when done
• You (the lead) receive idle notifications as workers finish
• Wait for all 3 exploration tasks to be marked complete before proceeding to Phase 3

---

Phase 3: Evaluation and Synthesis

Goal: Verify exploration completeness, launch synthesis with deep investigation.

Step 1: Structural Completeness Check

This is a structural check, not a quality assessment:

1. Use TaskList to verify all 3 exploration tasks are completed
2. Check that each worker produced a report with content (review the messages/reports received)
3. If a worker failed completely (empty or error output):
   • Create a follow-up exploration task targeting the gap
   • Assign it to an idle worker
   • Add the new task to the synthesis task's blockedBy list
   • Wait for the follow-up task to complete
4. If all 3 produced content: proceed immediately to Step 2

Step 2: Launch Synthesis

1. Use TaskUpdate to assign the synthesis task: owner: "synthesizer"
2. Send the deep synthesizer a message with exploration context and recon findings:

   SendMessage type: "message", recipient: "synthesizer",
   content: "All 3 exploration tasks are complete. Your synthesis task is now assigned.
   
   Analysis context: [analysis context]
   Codebase path: [PATH]
   
   Recon findings from planning phase:
   - Project structure: [brief summary of directory layout]
   - Primary language/framework: [what was detected]
   - Key areas identified: [the 3 focus areas and why they were chosen]
   
   The workers are: explorer-1, explorer-2, explorer-3. You can message them with follow-up questions if you find conflicts or gaps in their findings.
   
   You have Bash access for deep investigation — use it for git history analysis, dependency trees, static analysis, or any investigation that Read/Glob/Grep can't handle.
   
   Read the completed exploration tasks via TaskGet to access their reports, then synthesize into a unified analysis. Evaluate completeness before finalizing.",
   summary: "Synthesis task assigned, begin work"
   

3. Wait for the deep synthesizer to mark the synthesis task as completed

---

Phase 4: Completion + Cleanup

Goal: Collect results, present to user, and tear down the team.

1. Collect synthesis output:

   • The deep synthesizer's findings are in the messages it sent and/or the task completion output
   • Read the synthesis results

2. Present or return results:

   • Standalone invocation: Present the synthesized analysis to the user. The results remain in conversation memory for follow-up questions.
   • Loaded by another skill: The synthesis is complete. Control returns to the calling workflow — do not present a standalone summary.

3. Shutdown teammates: Send shutdown requests to all 4 teammates:

   SendMessage type: "shutdown_request", recipient: "explorer-1", content: "Analysis complete"
   SendMessage type: "shutdown_request", recipient: "explorer-2", content: "Analysis complete"
   SendMessage type: "shutdown_request", recipient: "explorer-3", content: "Analysis complete"
   SendMessage type: "shutdown_request", recipient: "synthesizer", content: "Analysis complete"
   

4. Cleanup team:

   • Use TeamDelete to remove the team and its task list

---

Error Handling

Planning Phase Failure

• If reconnaissance fails (errors, empty results, unusual structure): fall back to static focus area templates (Step 4b)
• If the codebase appears empty: inform the user and ask how to proceed

Partial Worker Failure

• If one worker fails: create a follow-up task targeting the missed focus area, assign to an idle worker, add to synthesis blockedBy
• If two workers fail: attempt follow-ups, but if they also fail, instruct the deep synthesizer to work with partial results
• If all workers fail: inform the user and offer to retry or abort

Deep Synthesizer Failure

• If the deep synthesizer fails: present the raw exploration results to the user directly
• Offer to retry synthesis or let the user work with partial results

General Failures

If any phase fails:

1. Explain what went wrong
2. Ask the user how to proceed:
   • Retry the phase
   • Continue with partial results
   • Abort the analysis

---

Agent Coordination

• The lead (you) acts as the planner: performs recon, generates focus areas, assigns work
• Workers explore independently — no cross-worker messaging (hub-and-spoke topology)
• The deep synthesizer can ask workers follow-up questions to resolve conflicts and fill gaps
• The deep synthesizer has Bash access for deep investigation (git history, dependency trees, static analysis)
• Wait for task dependencies to resolve before proceeding
• Handle agent failures gracefully — continue with partial results

When calling Task tool for teammates:

• Use model: "opus" for the deep synthesizer
• Use default model (sonnet) for workers
• Always include team_name parameter to join the team