codebase-analysis

Codebase Analysis Workflow

Execute a structured 3-phase codebase analysis workflow to gather insights.

Phase Overview

1. Deep Analysis — Explore and synthesize codebase findings via the deep-analysis skill
2. Reporting — Present structured analysis to the user
3. Post-Analysis Actions — Save, document, or retain analysis insights

Phase 1: Deep Analysis

Goal: Explore the codebase and synthesize findings.

1. Determine analysis context:
2. If arguments are provided, use them as the analysis context
3. If no arguments, set context to "general codebase understanding"

1. Check for cached results:
2. Check if .agents/sessions/exploration-cache/manifest.md exists
3. If found, read the manifest and verify: codebase_path matches the current working directory, and timestamp is within the configured cache TTL (default 24 hours)
4. If cache is valid, prompt the user:
5. Use cached results (show the formatted cache date) — Read cached synthesis from .agents/sessions/exploration-cache/synthesis.md and recon from recon_summary.md. Set CACHE_HIT = true and CACHE_TIMESTAMP to the cache's timestamp. Skip step 3 and proceed directly to step 4.
6. Run fresh analysis — Remove the cache manifest file, set CACHE_HIT = false, and proceed to step 3
7. If no valid cache: set CACHE_HIT = false and proceed to step 3

1. Run deep-analysis workflow:
2. Refer to the deep-analysis skill and follow its workflow
3. Pass the analysis context from step 1
4. This handles reconnaissance, team planning, approval (auto-approved when skill-invoked), team creation, parallel exploration (code-explorer agents), and synthesis (code-synthesizer agent)
5. After completion, set CACHE_TIMESTAMP = null (fresh results, no prior cache)

1. Verify results and capture metadata:
2. Ensure the synthesis covers the analysis context adequately
3. If critical gaps remain, search the codebase directly to fill them
4. Record analysis metadata for Phase 2 reporting: whether results were cached (CACHE_HIT), cache timestamp if applicable (CACHE_TIMESTAMP), and the number of explorer agents used (from the deep-analysis team plan, or 0 if cached)

Phase 2: Reporting

Goal: Present a structured analysis to the user.

1. Load diagram guidance:
2. Refer to the technical-diagrams skill for Mermaid diagram syntax and styling rules
3. Use Mermaid diagrams in the Architecture Overview and Relationship Map sections

1. Present the analysis using the report template below:

Structure the report with these sections:

• Executive Summary — Lead with the most important finding
• Architecture Overview — How the codebase is structured
• Tech Stack — Core technologies, frameworks, and tools detected
• Critical Files — The 5-10 most important files with details
• Patterns & Conventions — Recurring patterns and coding conventions
• Relationship Map — How components connect to each other
• Challenges & Risks — Technical risks and complexity hotspots
• Recommendations — Actionable next steps, each citing the challenge it addresses
• Analysis Methodology — Agents used, cache status, scope, and duration

1. Proceed immediately to Phase 3.

Do NOT stop here. Do NOT wait for user input. The report is presented, but the workflow requires Post-Analysis Actions. Continue directly to Phase 3 now.

Report Template

# Codebase Analysis Report

**Analysis Context**: {What was analyzed and why}
**Codebase Path**: {Path analyzed}
**Date**: {YYYY-MM-DD}

{If the report exceeds approximately 100 lines, add a **Table of Contents** here linking to each major section.}

---

## Executive Summary

{Lead with the most important finding. 2-3 sentences covering: what was analyzed, the key architectural insight, and the primary recommendation or risk.}

---

## Architecture Overview

{2-3 paragraphs describing:}
- How the codebase is structured (layers, modules, boundaries)
- The design philosophy and architectural style
- Key architectural decisions and their rationale

{Include a Mermaid architecture diagram (flowchart or C4 Context) showing the major layers/components. Use `classDef` with `color:#000` for all node styles.}

---

## Tech Stack

| Category | Technology | Version (if detected) | Role |
|----------|-----------|----------------------|------|
| Language | {e.g., TypeScript} | {e.g., 5.x} | Primary language |
| Framework | {e.g., Next.js} | {e.g., 16} | Web framework |

{Include only technologies actually detected in config files or code. Omit categories that don't apply.}

---

## Critical Files

{Limit to 5-10 most important files}

| File | Purpose | Relevance |
|------|---------|-----------|
| `path/to/file` | Brief description | High/Medium |

### File Details

#### `path/to/critical-file`
- **Key exports**: What this file provides to others
- **Core logic**: What it does
- **Connections**: What depends on it and what it depends on

---

## Patterns & Conventions

### Code Patterns
- **Pattern**: Description and where it's used

### Naming Conventions
- **Convention**: Description and examples

### Project Structure
- **Organization**: How files and directories are organized

---

## Relationship Map

{Describe how key components connect — limit to 15-20 most significant connections. Use Mermaid flowcharts for both data flows and dependency maps.}

---

## Challenges & Risks

| Challenge | Severity | Impact |
|-----------|----------|--------|
| {Description} | High/Medium/Low | {What could go wrong} |

---

## Recommendations

1. **{Recommendation}** _(addresses: {Challenge name})_: {Brief rationale}
2. **{Recommendation}** _(addresses: {Challenge name})_: {Brief rationale}

---

## Analysis Methodology

- **Exploration agents**: {Number} agents with focus areas: {list}
- **Synthesis**: Findings merged and critical files read in depth
- **Scope**: {What was included and what was intentionally excluded}
- **Cache status**: {Fresh analysis / Cached results from YYYY-MM-DD}
- **Config files detected**: {List of config files found during reconnaissance}
- **Gap-filling**: {Whether direct investigation was needed after synthesis, and what areas were filled}

Report Section Guidelines

Executive Summary: Lead with the most important finding, not a generic overview. Keep to 2-3 sentences. Include at least one actionable insight.

Critical Files: Limit to 5-10 files — these should be the files someone must understand. Include both the "what" (purpose) and "why" (relevance).

Patterns & Conventions: Only include patterns that are consistently applied (not one-off occurrences). Note deviations from patterns.

Relationship Map: Focus on the most important connections, not an exhaustive dependency graph. Use directional language (calls, depends on, triggers, reads from). Cap at 15-20 connections.

Challenges & Risks: Rate severity based on likelihood and impact combined. Include specific details, not vague warnings.

Recommendations: Make recommendations actionable. Each recommendation must reference the specific challenge it addresses using the format: _(addresses: {Challenge name})_. Limit to 3-5 recommendations.

Adapting the Report

For Feature-Focused Analysis: Emphasize integration points and files that would need modification. Include a "Feature Implementation Context" section before Recommendations. Focus Challenges on implementation risks.

For General Codebase Understanding: Broader Architecture Overview with layer descriptions. More extensive Patterns & Conventions section. Focus Recommendations on areas for improvement.

For Debugging/Investigation: Emphasize the execution path and data flow. Include a "Relevant Execution Paths" section. Focus Critical Files on the suspected problem area.

Phase 3: Post-Analysis Actions

Goal: Let