codebase-analysis

What it does

The skill orchestrates a three-phase workflow to analyze a codebase and produce a structured report. It first performs a deep analysis (with optional cache handling), then generates a comprehensive Phase 2 report including architecture, tech stack, critical files, patterns, and a relationship map, and finally proceeds to Phase 3 post-analysis actions (save report, update docs, keep memory, or custom reports). It also supports post-analysis actions: saving reports to a markdown file, updating project documentation, and keeping insights in memory, with configurable file paths and user prompts for locations.

How it works

• Phase 1: Deep Analysis
  • Determine analysis context from provided arguments or set to a general context.
  • Check for an exploration cache at .agents/sessions/exploration-cache/manifest.md and validate codebase_path and timestamp against TTL (default 24 hours).
  • If cache is valid, offer using cached results by reading synthesis from .agents/sessions/exploration-cache/synthesis.md and recon_summary.md, set CACHE_HIT and CACHE_TIMESTAMP accordingly, and skip to Phase 4; otherwise proceed to a fresh analysis.
  • Run the deep-analysis workflow (refer to the deep-analysis skill), passing the analysis context. After completion, set CACHE_TIMESTAMP to null.
  • Verify results, fill gaps if needed, and record metadata: CACHE_HIT, CACHE_TIMESTAMP, and number of explorer agents used.
• Phase 2: Reporting
  • Load Mermaid diagram guidance from the technical-diagrams skill and render Architecture Overview and Relationship Map with Mermaid diagrams.
  • Produce a Markdown report following the template: Executive Summary, Architecture Overview, Tech Stack, Critical Files, Patterns & Conventions, Relationship Map, Challenges & Risks, Recommendations, Analysis Methodology.
  • Phase 3 is triggered automatically after Phase 2 finishes (per workflow).
• Phase 3: Post-Analysis Actions
  • Step 1: Prompt user to choose actions: Save Codebase Analysis Report, Save a custom report, Update project documentation, Keep a condensed summary in memory.
  • Step 2: Execute each chosen action in a fixed order with sub-steps for file location prompts and report generation/saving.
  • Step 3: Actionable Insights Follow-up (always runs): Prompt to Address actionable insights or Skip. If chosen, extract items from Challenges & Risks, Recommendations, and Other Findings with given severity rules, present a prioritized list, and allow user selection for remediation.

The skill relies on the declared tools and dependencies, including claude-code and the deep-analysis and technical-diagrams capabilities, and constrains outputs to a structured report format with explicit sections and a strict content outline.