codebase-analysis

What it does

Produce a structured codebase analysis report with architecture overview, critical files, patterns, and actionable recommendations. Use when asked to analyze codebase, explore codebase, understand this codebase, map the codebase, give me an overview of this project, what does this codebase do, codebase report, project analysis, audit this codebase, or how is this project structured.

How it works

Phase 1: Deep Analysis

• Determine analysis context from provided arguments or default to "general codebase understanding".
• Check for a cache manifest at .agents/sessions/exploration-cache/manifest.md; if valid and user chooses, use cached results from .agents/sessions/exploration-cache/synthesis.md and recon_summary.md, set CACHE_HIT and CACHE_TIMESTAMP, skip to Phase 4. Otherwise proceed to Phase 3.
• Run deep-analysis workflow via the deep-analysis skill, passing the analysis context. After completion, set CACHE_TIMESTAMP to null.
• Verify results, fill gaps by searching the codebase if needed, and record metadata: whether results were cached (CACHE_HIT), the timestamp (CACHE_TIMESTAMP), and number of explorer agents used.

Phase 2: Reporting

• Load diagram guidance from the technical-diagrams skill and use Mermaid diagrams in Architecture Overview and Relationship Map.
• Present the analysis in sections: Executive Summary, Architecture Overview, Tech Stack, Critical Files, Patterns & Conventions, Relationship Map, Challenges & Risks, Recommendations, Analysis Methodology.

Phase 3: Post-Analysis Actions

• Prompt user to select actions: Save Codebase Analysis Report, Save a custom report, Update project documentation, Keep a condensed summary in memory.
• Execute actions in fixed order per Step 2a/2b/2c; generate and save reports, update docs, or store memory as requested.
• Optionally proceed to Step 3: Actionable Insights Follow-up, where you extract actionable items from Challenges & Risks, Recommendations, and Other findings, present them by severity, and allow user to apply changes (Apply/Skip/Modify) followed by a summary.

When to use it

The skill is intended to be invoked when the user asks to analyze, explore, understand, map, or audit a codebase, or requests an overview or architecture-focused report.

What it can touch

The workflow uses the deep-analysis and technical-diagrams capabilities to gather, synthesize, and diagram the analysis. It references deletion of cache manifest if running fresh analysis and uses synthesis outputs for reporting.

Caveats

Possible limitations include reliance on the deep-analysis workflow and diagram conventions, and conditional caching behavior based on manifest validity and user choice. The license is MIT.