codebase-analysis

What it does

The skill runs a structured, three-phase workflow to analyze a codebase. It first performs a deep analysis (with optional context and cache checks), then generates a formal report using a provided template and diagram guidance, and finally offers post-analysis actions (save reports, update docs, or store a memory summary) with a multi-step, user-driven flow.

How it works

• Phase 1: Deep Analysis
  • Determine analysis context from input arguments or default to a general codebase understanding.
  • Check for a cached exploration manifest at .agents/sessions/exploration-cache/manifest.md; if valid, offer to use cached results or run a fresh analysis. If using cache, read synthesis from .agents/sessions/exploration-cache/synthesis.md and recon_summary.md, set CACHE_HIT and CACHE_TIMESTAMP accordingly, and skip to Phase 4 metadata capture.
  • If no valid cache, proceed to run the deep-analysis workflow (refer to the deep-analysis skill) with the given context. After completion, set CACHE_TIMESTAMP to null.
  • Verify results and capture metadata: ensure synthesis covers the context, fill gaps if possible, and record CACHE_HIT, CACHE_TIMESTAMP, and number of explorer agents used.
• Phase 2: Reporting
  • Load diagram guidance from the technical-diagrams skill and render Mermaid diagrams in Architecture Overview and Relationship Map sections.
  • Load a Report Template and structure the presentation into sections: Executive Summary, Architecture Overview, Tech Stack, Critical Files, Patterns & Conventions, Relationship Map, Challenges & Risks, Recommendations, and Analysis Methodology.
  • After presenting Phase 2, proceed to Phase 3.
• Phase 3: Post-Analysis Actions
  • Step 1: Prompt user for actions (save report, save custom report, update documentation, keep a condensed summary in memory).
  • Step 2: Execute chosen actions in a fixed order with sub-steps for file path prompts and draft generation (for codebase analysis report, custom report, and docs).
  • Step 3: Actionable Insights Follow-up (always after Step 2). Prompt user to address insights, extract actionable items from the Phase 2 report, present them ordered by severity, and allow user choice to apply, skip, or modify. For high/medium/low items, determine complexity and assign tasks to code-architect or code-explorer agents if needed, else propose direct fixes. Summarize results with modified files and status.
  • Step 4: Complete workflow by summarizing executed actions and confirming completion.
• Error Handling and Agent Coordination
  • If any phase fails, provide options to retry, skip, or abort. Documentation updates failures allow retry or manual apply. Agent delegation failures fall back to direct file investigation.

When to use it

• Use when you need a structured, report-driven analysis of a codebase, including architecture overview, critical files, patterns, and actionable recommendations. Trigger the workflow to leverage deep-analysis coordination and generate a formal report with diagrams and a structured template.

What it can touch

• Tools: claude-code is used as part of the workflow for deep-analysis and synthesis coordination.
• Artifacts: exploration cache at .agents/sessions/exploration-cache/, synthesis.md, recon_summary.md, Mermaid diagrams, and a markdown-formatted Codebase Analysis Report following the provided template.

Caveats

• Requires access to the deep-analysis and technical-diagrams capabilities. Cache validity depends on TTL (default 24 hours). If cache is valid, results may be reused; otherwise, a fresh analysis is performed. The workflow delegates complex fixes to code-architect or code-explorer agents when necessary, with fallback to direct file investigation if delegation fails.