codebase-analysis

What it does

The skill defines a three-phase workflow to analyze a codebase: Phase 1 Deep Analysis to explore the codebase and synthesize findings, Phase 2 Reporting to present a structured analysis with an architecture overview, tech stack, critical files, patterns, relationship map, risks, and recommendations, and Phase 3 Post-Analysis Actions to save reports, update documentation, or keep memory of insights. It supports caching of results and can load cached synthesis to skip repeated analysis. It relies on the deep-analysis skill for reconnaissance and synthesis and on the technical-diagrams skill for Mermaid diagrams in architecture-related sections. It requires inputs that set the analysis context (defaulting to general codebase understanding) and yields Phase 2 findings that include an analysis methodology and cache metadata such as whether results were cached and the cache timestamp. The workflow enforces a fixed sequence: check cache, run deep-analysis if needed, verify results, then present the report and proceed to post-analysis actions.

How it works

• Phase 1: Deep Analysis
  • Determine analysis context from inputs or default to general codebase understanding.
  • Check for and validate a cache manifest at .agents/sessions/exploration-cache/manifest.md; if valid, offer to use cached results or run a fresh analysis.
  • If no valid cache or user chooses fresh, invoke the deep-analysis skill with the provided context to perform reconnaissance, team planning, and synthesis; set CACHE_TIMESTAMP to null for fresh results.
  • Validate synthesis coverage and fill gaps by searching files if needed; record metadata including CACHE_HIT, CACHE_TIMESTAMP, and number of exploration workers.
• Phase 2: Reporting
  • Load diagram guidance from technical-diagrams for Mermaid syntax.
  • Use the provided report template to structure the output: Executive Summary, Architecture Overview, Tech Stack, Critical Files, Patterns & Conventions, Relationship Map, Challenges & Risks, Recommendations, and Analysis Methodology.
  • Proceed to Phase 3 after presentation.
• Phase 3: Post-Analysis Actions
  • Prompt for actions: Save Codebase Analysis Report, Save a custom report, Update project documentation, Keep a condensed summary in memory.
  • For Save Codebase Analysis Report, determine file location under internal/docs/ or project root, generate and save the full report, and confirm.
  • Optional steps for custom reports and documentation updates follow detailed prompts and drafts, with a structured approval flow.
• Error handling and coordination rules are described for failures, delegation to specialists, and memory of insights.

When to use it

Use when asked to analyze or audit a codebase, understand project structure, map relationships, or generate a formal codebase report; the skill explicitly lists trigger phrases such as "analyze codebase", "explore codebase", "understand this codebase", "map the codebase", "give me an overview of this project", or "codebase report".

What it can touch

• Tools: claude-code (as declared under requires)
• It references the deep-analysis and technical-diagrams skills for broader workflow steps and diagram rendering.

Caveats

• The workflow depends on the availability and correct execution of the deep-analysis and technical-diagrams skills.
• Cache-based optimizations require a valid manifest and TTL (default 24 hours) and could bypass fresh analysis if not refreshed.
• The Phase 2 report structure is template-driven and will be populated with findings from Phase 2; exact content depends on the codebase analyzed.