codebase-analysis

Codebase Analysis Workflow

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

CRITICAL: Complete ALL 3 phases. The workflow is not complete until Phase 3: Post-Analysis Actions is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

Phase Overview

1. Deep Analysis — Explore and synthesize codebase findings via 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 is provided, use it as the analysis context
3. If no arguments, set context to "general codebase understanding"

1. Check for cached results:
2. Check if .claude/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, use AskUserQuestion:
5. Use cached results (show the formatted cache date) — Read cached synthesis from .claude/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. Read ${CLAUDE_PLUGIN_ROOT}/skills/deep-analysis/SKILL.md 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, use Glob/Grep to fill them directly
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. Read ${CLAUDE_PLUGIN_ROOT}/skills/technical-diagrams/SKILL.md
3. Use Mermaid diagrams in the Architecture Overview and Relationship Map sections

1. Load report template:
2. Read ${CLAUDE_PLUGIN_ROOT}/skills/codebase-analysis/references/report-template.md
3. Use it to structure the presentation

1. Present the analysis:

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. IMPORTANT: 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.

Phase 3: Post-Analysis Actions

Goal: Let the user save, document, or retain analysis insights from the report through a multi-step interactive flow.

Step 1: Select actions

Use AskUserQuestion with multiSelect: true to present all available actions:

• Save Codebase Analysis Report — Write the structured report to a markdown file
• Save a custom report — Generate a report tailored to your specific goals (you'll provide instructions next)
• Update project documentation — Add/update README.md, CLAUDE.md, or AGENTS.md with analysis insights
• Keep a condensed summary in memory — Retain a quick-reference summary in conversation context

If the user selects no actions, the workflow is complete. Thank the user and end.

Step 2: Execute selected actions

Process selected actions in the following fixed order. Complete all sub-steps for each action before moving to the next.

Action: Save Codebase Analysis Report

Step 2a-1: Prompt for file location

• Check if an internal/docs/ directory exists in the project root
• If yes, suggest default path: internal/docs/codebase-analysis-report-{YYYY-MM-DD}.md
• If no, suggest default path: codebase-analysis-report-{YYYY-MM-DD}.md in the project root
• Use AskUserQuestion to let the user confirm or customize the file path

Step 2a-2: Generate and save the report

• Use the report template already loaded in Phase 2 Step 1
• Generate the full structured report using the Phase 2 analysis findings and the template structure
• Write the report to the confirmed path using the Write tool
• Confirm the file was saved

Action: Save Custom Report

Step 2b-1: Gather report requirements

• Use AskUserQuestion to ask the user to describe the goals and requirements for their custom report — what it should focus on, what questions it should answer, and any format preferences

Step 2b-2: Prompt for file location

• Check if an internal/docs/ directory exists in the project root
• If yes, suggest default path: internal/docs/custom-report-{YYYY-MM-DD}.md
• If no, suggest default path: custom-report-{YYYY-MM-DD}.md in the project root
• Use AskUserQuestion to let the user confirm or customize the file path

Step 2b-3: Generate and save the custom report

• Generate a report shaped by the user's requirements from Step 2b-1, drawing from the Phase 2 analysis data — this is a repackaging of existing findings, not a re-analysis
• Write the report to the confirmed path using the Write tool
• Confirm the file was saved

Action: Update Project Documentation

Step 2c-1: Select documentation files and gather directions

Use AskUserQuestion with multiSelect: true:

• README.md — Add architecture, structure, and tech stack information
• CLAUDE.md — Add patterns, conventions, critical files, and architectural decisions
• AGENTS.md — Add agent descriptions, capabilities, and coordination patterns

Then use a single AskUserQuestion to gather update directions for all selected files: "What content from the analysis should be added or updated? Provide general directions or specific sections to focus on (applies across all selected files, or specify per-file directions)."

Step 2c-2: Generate and approve documentation drafts

For each selected file, read the existing file and generate a draft based on the user's directions and Phase 2 analysis data:

• README.md: Read existing file at project root. If no README.md exists, skip and inform the user. Draft updates focusing on architecture, project structure, and tech stack.
• CLAUDE.md: Read existing file at project root. If none exists, ask if one should be created (if declined, skip). Draft updates focusing on patterns, conventions, critical files, and architectural decisions.
• AGENTS.md: Read existing file at project root (create new if none exists). Draft content focusing on agent inventory (name, model, purpose), capabilities and tool access, coordination patterns, skill-agent mappings, and model tiering rationale.

Present all drafts together in a single output, clearly labeled by file