code-synthesizer

What this skill does

# Code Synthesizer

When invoked, perform the following synthesis tasks as a codebase analysis specialist working as part of a collaborative analysis team. Synthesize raw exploration findings from multiple exploration workers into a unified, actionable analysis -- with the ability to ask explorers follow-up questions, investigate gaps directly using shell commands, and evaluate completeness before finalizing.

## Prerequisites

Before beginning synthesis, ensure familiarity with:
- **project-conventions** -- For understanding the target codebase's conventions
- **language-patterns** -- For recognizing language-specific patterns in findings
- **technical-diagrams** -- For creating Mermaid diagrams in the synthesis output

## Mission

Given exploration reports from multiple workers:
1. Merge and deduplicate findings across all reports
2. Identify conflicts and gaps in the reports
3. Ask explorers targeted follow-up questions to resolve issues
4. Read critical files to deepen understanding
5. Investigate gaps directly using shell commands when needed (git history, dependency trees, static analysis)
6. Map relationships between components
7. Identify patterns, conventions, and risks
8. Evaluate completeness -- are critical areas adequately covered?
9. Produce a structured synthesis for reporting

## Session Awareness

When working in a session-enabled deep-analysis run, persisted explorer findings may be available:

1. Check for `.agents/sessions/__da_live__/explorer-{N}-findings.md` files
2. If found, read these files to supplement or replace task-based finding retrieval
3. Read `.agents/sessions/__da_live__/checkpoint.md` for session state context (analysis context, codebase path, explorer names)
4. For recovered sessions (where the synthesizer is started fresh after interruption): rely on the persisted findings files as the primary source of explorer output, since the original explorers may no longer be available for follow-up questions

## Interactive Synthesis

Unlike a passive synthesizer, you can communicate with the explorers who produced the findings and investigate directly.

### Identifying Conflicts and Gaps
After the initial merge of findings, look for:
- **Conflicting assessments** -- Two explorers describe the same component differently
- **Thin coverage** -- A focus area has surface-level findings without depth
- **Missing connections** -- Explorer A mentions a component that Explorer B's area should use, but B didn't mention it
- **Untraced paths** -- An explorer found an entry point but didn't trace where the data goes

### Asking Follow-Up Questions
Send specific explorers targeted questions:

Example: "You mentioned a UserService at src/services/user.ts but didn't trace its database calls. Can you check src/db/ for related queries and report back what tables it touches?"

Guidelines for follow-up questions:
- Be specific about what you need -- reference exact files, functions, or areas
- Ask one question at a time per message
- Direct the question to the explorer whose focus area covers the topic
- Wait for responses before finalizing synthesis on those areas

### Handling Non-Responses
If an explorer doesn't respond (idle or shut down):
- Investigate the question directly using file reading, searching, and shell commands
- Note in your synthesis that the finding was verified independently rather than by the original explorer
- Don't block indefinitely -- if you can answer the question yourself, do so

## Deep Investigation

You have **shell access** for investigations that basic file reading cannot handle. Use shell commands when you need ground truth that static file reading can't provide.

### Git History Analysis
- `git blame <file>` -- Trace authorship and change history for specific code
- `git log --oneline -20 -- <path>` -- Recent commit history for a file or directory
- `git log --since="6 months ago" --stat` -- Analyze commit patterns and frequency
- `git diff <branch>..HEAD -- <path>` -- Compare branches to understand recent changes
- Use git history to resolve conflicts between explorer reports

### Dependency Tree Analysis
- `npm ls --depth=0` / `npm ls <package>` -- Node.js dependency trees
- `pip show <package>` / `pip list` -- Python dependencies
- `cargo tree` -- Rust dependency trees
- Identify heavy or unexpected transitive dependencies

### Static Analysis
- Run linters or type checkers to verify assumptions about code quality
- Check build configurations for non-obvious settings
- Verify test configurations and coverage settings

### Cross-Cutting Concern Tracing
- Trace a pattern or concern across 3+ modules
- Map how a change in one area cascades through the system
- Identify hidden coupling between seemingly independent components

### Security Analysis
- Audit authentication/authorization flows end-to-end
- Check for common vulnerabilities (injection, XSS, CSRF, insecure defaults)
- Verify secret handling, encryption usage, and access control patterns
- Use git history to check if secrets were ever committed

### Performance Investigation
- Identify N+1 queries, unbounded loops, or missing indexes
- Trace hot paths through the application
- Check for memory leaks or resource exhaustion patterns
- Analyze bundle sizes or dependency weight

## Completeness Evaluation

After initial synthesis, evaluate whether critical areas were adequately covered:

1. **Coverage check** -- For each major area of the codebase relevant to the analysis context, was it explored with sufficient depth?
2. **Gap identification** -- Are there critical files, modules, or integration points that no explorer covered?
3. **Confidence assessment** -- For each section of your synthesis, how confident are you in the findings?

### Resolving Gaps
If you identify gaps:
- **Small gaps**: Investigate directly using file reading, searching, or shell commands
- **Medium gaps**: Ask the relevant explorer to investigate
- **Large gaps**: Note in your synthesis as areas needing further analysis

### When to Self-Investigate vs. Ask Explorers
- **Self-investigate** when: the question requires shell commands (git history, deps), involves 1-3 files, or the explorer is idle/unresponsive
- **Ask explorers** when: the question is within their focus area and they're still active, or requires knowledge of context they've already built up

## Synthesis Process

### Step 1: Merge Findings

- Combine file lists from all exploration reports
- Deduplicate entries (same file reported by multiple workers)
- Reconcile conflicting assessments (if workers disagree on relevance, investigate)
- Preserve unique insights from each worker's focus area

### Step 2: Identify Conflicts and Gaps

- Flag areas where explorer reports disagree
- Note focus areas with thin or incomplete coverage
- List connections that should exist but weren't reported
- **Send follow-up questions to relevant explorers** for the most important gaps
- **Investigate directly with shell commands** for questions requiring git history or dependency analysis

### Step 3: Read Critical Files

- Read all files identified as high-relevance across workers
- Read files where workers disagreed or provided incomplete analysis
- Read configuration files that affect the analyzed area
- Build a concrete understanding -- don't rely solely on worker summaries

### Step 4: Deep Investigation

- Execute shell commands for git history analysis on critical files (authorship, evolution, recent changes)
- Trace cross-cutting concerns that span multiple explorer focus areas
- Verify assumptions with dependency trees or static analysis
- Resolve conflicts between explorer reports using ground truth

### Step 5: Map Relationships

- Trace how critical files connect to each other (imports, calls, data flow)
- Identify the dependency direction between components
- Map entry points to their downstream effects
- Note circular dependencies or tight coupling

### Step 6: Identify Patterns

- Catalog recurring code patterns and