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:

   • If $ARGUMENTS is provided, use it as the analysis context
   • If no arguments, set context to "general codebase understanding"

2. Run deep-analysis workflow:

   • Check if $ARGUMENTS contains --teams flag
   • If --teams is present:
     • Read ${CLAUDE_PLUGIN_ROOT}/skills/teams-deep-analysis/SKILL.md and follow its workflow
     • Remove --teams from the analysis context
   • Otherwise:
     • Read ${CLAUDE_PLUGIN_ROOT}/skills/deep-analysis/SKILL.md and follow its workflow (default)
   • Pass the analysis context from step 1
   • This handles exploration (parallel code-explorer agents) and synthesis (codebase-synthesizer agent)

3. Verify results:

   • Ensure the synthesis covers the analysis context adequately
   • If critical gaps remain, use Glob/Grep to fill them directly

Phase 2: Reporting

Goal: Present a structured analysis to the user.

1. Load report template:

   • Read ${CLAUDE_PLUGIN_ROOT}/skills/codebase-analysis/references/report-template.md
   • Use it to structure the presentation

2. Present the analysis: Structure the report with these sections:

   • Executive Summary — Lead with the most important finding
   • Architecture Overview — How the codebase is structured
   • 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

3. 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.

1. Present action menu:

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

   • Save report as Markdown file — Write the full report to a file
   • Update README.md with analysis insights — Add architecture/structure info to README
   • Update CLAUDE.md with analysis insights — Add patterns/conventions to CLAUDE.md
   • Keep a condensed summary in memory — Retain a quick-reference summary in conversation context
   • Address actionable insights — Fix challenges and implement recommendations from the report

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

2. Execute selected actions in the following fixed order:

   Action: Save Report as Markdown File

   • Check if a docs/ directory exists in the project root
     • If yes, suggest default path: docs/codebase-analysis.md
     • If no, suggest default path: codebase-analysis.md in the project root
   • Use AskUserQuestion to let the user confirm or customize the file path
   • Write the full report content (same as Phase 2 output) to the confirmed path using the Write tool
   • Confirm the file was saved

   Action: Update README.md

   • Read the existing README.md at the project root
     • If no README.md exists, skip this action and inform the user
   • Draft updates based on analysis insights — focus on:
     • Architecture overview
     • Project structure
     • Tech stack summary
   • Present the draft to the user for approval using AskUserQuestion with options:
     • Apply — Apply the drafted updates
     • Modify — Let the user describe what to change, then re-draft
     • Skip — Skip this action entirely
   • If approved, apply updates using the Edit tool

   Action: Update CLAUDE.md

   • Read the existing CLAUDE.md at the project root
     • If no CLAUDE.md exists, use AskUserQuestion to ask if one should be created
     • If user declines, skip this action
   • Draft updates based on analysis insights — focus on:
     • Key patterns and conventions discovered
     • Critical files and their roles
     • Important dependencies
     • Architectural decisions and constraints
   • Present the draft to the user for approval using AskUserQuestion with options:
     • Apply — Apply the drafted updates
     • Modify — Let the user describe what to change, then re-draft
     • Skip — Skip this action entirely
   • If approved, apply updates using the Edit tool (or Write tool if creating new)

   Action: Keep Insights in Memory

   • Present a condensed Codebase Quick Reference inline in the conversation:
     • Architecture — 1-2 sentence summary of how the codebase is structured
     • Key Files — 3-5 most critical files with one-line descriptions
     • Conventions — Important patterns and naming conventions
     • Tech Stack — Core technologies and frameworks
     • Watch Out For — Top risks or complexity hotspots
   • No file is written — this summary stays in conversation context for reference during the session

   Action: Address Actionable Insights

   IMPORTANT: This action always executes last among all selected actions. Code changes could invalidate analysis if documentation is generated after, and this is the most interactive action — it should not block simpler actions.

   Step 1: Extract actionable items from the report

   Parse the Phase 2 report (in conversation context) to extract items from:

   • Challenges & Risks table rows — title from Challenge column, severity from Severity column, description from Impact column
   • Recommendations section — each numbered item; infer severity from linked challenges (High if linked to a High challenge, otherwise Medium)
   • Other findings with concrete fixes — default to Low severity

   If no actionable items are found, inform the user and skip this action.

   Step 2: Present severity-ranked item list

   • Load reference template from ${CLAUDE_PLUGIN_ROOT}/skills/codebase-analysis/references/actionable-insights-template.md
   • Present items sorted High → Medium → Low, each showing:
     • Title
     • Severity (High / Medium / Low)
     • Source section (Challenges & Risks, Recommendations, or Other)
     • Brief description
   • Use AskUserQuestion with multiSelect: true for the user to select which items to address
   • If no items selected, skip this action

   Step 3: Process each selected item in priority order (High → Medium → Low)

   For each item:

   1. Assess complexity:

      • Simple — Single file, clear fix, localized change
      • Complex — Multi-file, architectural impact, requires investigation

   2. Plan the fix:

      • Simple: Read the target file, propose changes directly
      • Complex (architectural): Launch claude-alchemy-tools:code-architect agent with model: "opus" to design the fix
      • Complex (needs investigation): Launch claude-alchemy-tools:code-explorer agent to investigate before proposing

   3. Present proposal: Show files to modify, specific changes, and rationale

   4. User approval via AskUserQuestion:

      • Apply — Execute changes with Edit/Write tools, confirm success
      • Skip — Record the skip, move to next item
      • Modify — User describes adjustments, re-propose the fix (max 3 revision cycles, then must Apply or Skip)

   Step 4: Summarize results

   Present a summary covering:

   • Items addressed (with list of files modified per item)
   • Items skipped
   • Total files modified table

3. Complete the workflow: Summarize which actions were executed and confirm the workflow is complete.

Error Handling

If any phase fails:

1. Explain what went wrong
2. Ask the user how to proceed:
   • Retry the phase
   • Skip to next phase (with partial results)
   • Abort the workflow

Agent Coordination

Exploration and synthesis agent coordination is handled by the deep-analysis skill in Phase 1. See that skill for agent model tiers and failure handling details.

Additional Resources

• For report structure, see references/report-template.md
• For actionable insights format, see references/actionable-insights-template.md