analyze-codebase

Analyze Codebase Skill

You are performing Phase 1 (Gather Insights) of the Refactor Pilot Framework. Your job is to build a comprehensive understanding of the codebase before any changes are made.

Quick Decision Tree

Is this a new project you haven't analyzed?
├── YES → Start at Step 1
└── NO → Has the code changed since last analysis?
    ├── YES → Re-run steps 3-4 on changed files
    └── NO → Skip to Phase 2 (generate-tests)

Is the codebase sensitive or proprietary?
├── YES → Use local models for code analysis, see references/anonymization.md
└── NO → Proceed normally

Is the codebase large (>500 files)?
├── YES → Scope to one module/feature area first
└── NO → Analyze the whole project

Workflow

Execute these steps in order. Save all outputs to a refactor-notes/ directory in the project root.

Step 1: Extract Project Metadata

Read the project's manifest file (package.json, requirements.txt, Cargo.toml, go.mod, pyproject.toml, or equivalent) and produce a report covering:

• Project name, version, and description
• Runtime and framework (with versions)
• Production vs. dev dependencies (count and key packages)
• Build scripts and their purpose
• Red flags: outdated, deprecated, or conflicting packages

Save as refactor-notes/01-metadata.md.

Step 2: Map File Structure

Generate a categorized file manifest by running a directory listing (excluding node_modules, .git, dist, build, __pycache__, .venv, and similar).

Categorize every file into: Components/Views/Pages, Utilities/Helpers, Services/API clients, State management, Types/Interfaces, Styles, Tests, Configuration, Data/Constants.

Flag orphaned files, naming inconsistencies, and structural concerns.

Save as refactor-notes/02-file-structure.md.

Step 3: Per-File Analysis

If a module directory contains a CONTEXT.md, read it first and validate it against the code — flag stale or wrong entries. Note modules that lack one; creating them is a Phase 3 deliverable (template in skills/refactor-code/references/deep-modules.md).

For each file in the target area (or the most important 10-20 files if the project is large), produce a summary. Use file-type-specific analysis:

• UI Components → Focus on props, state, rendering logic, side effects
• Config files → Focus on build flags, constraints, refactoring implications
• Utilities → Focus on function signatures, purity, performance, type safety
• Stylesheets → Focus on selectors, specificity, !important usage, layout patterns

See references/file-type-prompts.md for detailed analysis templates per file type.

Process files in batches. Save as refactor-notes/03-file-summaries.md.

Step 4: Analyze Code Coverage (if tests exist)

Run a coverage report and assess refactoring risk by coverage level:

• >80% coverage → LOW RISK, safe to refactor
• 50-80% coverage → MEDIUM RISK, some test generation needed
• <50% coverage → HIGH RISK, extensive test generation needed first

Save as refactor-notes/03b-coverage-analysis.md.

Step 5: Capture Baselines

Run ./scripts/capture-baselines.sh against the project to capture quantitative measurements (codebase size, build output, dependencies, code quality indicators).

Save as refactor-notes/baselines.md.

Step 6: Check Build Configuration Flags

Review build config files (tsconfig.json, webpack.config.js, vite.config.ts, Cargo.toml, pyproject.toml, or equivalent) for flags that affect refactoring:

• TypeScript strict mode (enabling strictness can be a refactoring goal)
• Module format (CommonJS vs. ESM affects import/export patterns)
• Target version (constrains what syntax you can use)
• Path aliases (affect how imports are restructured)
• Tree shaking settings (affect dead code decisions)

Use references/file-type-prompts.md (config section) for detailed analysis. Note findings in refactor-notes/03-file-summaries.md alongside the config file analysis.

Step 7: Security-Aware Analysis

Scan the codebase for security concerns that should be addressed during refactoring:

• Deprecated APIs with known vulnerabilities
• Unsafe constructs (raw pointers, unvalidated buffers, deserialization of untrusted data)
• Injection vectors (unsanitized inputs in SQL, shell commands, templates)
• Hardcoded secrets (API keys, passwords, tokens in source files)
• Overly permissive error handling that leaks internal details

Classify each issue as CRITICAL, HIGH, MEDIUM, or LOW. Include file, line, and suggested fix. Feed this into the refactor plan in Phase 2.

Save as refactor-notes/05-security-analysis.md.

Step 8: Identify Design Pattern Opportunities

Scan the analyzed code for structural issues that design patterns can solve. Use the smell → pattern mapping to identify candidates:

Code Smell Found	Candidate Pattern(s)
Giant if/else or switch on type	Strategy, State, Command
Copy-pasted logic with minor variations	Template Method, Strategy
Constructor with 5+ parameters	Builder
new keyword scattered everywhere	Factory Method, Abstract Factory
God class doing too many things	Facade, Mediator, Command
Tight coupling between modules	Observer, Mediator, Bridge
Adding features requires modifying existing code	Decorator, Strategy, Visitor
Complex object creation logic	Builder, Factory Method, Prototype
Need to support undo/history	Memento, Command
Traversing complex structures	Iterator, Composite, Visitor
Different behavior for different states	State
Adapting incompatible interfaces	Adapter, Facade
Controlling access to expensive resources	Proxy, Flyweight

Also scan for the inverse problem — over-abstraction (shallow modules). These cost AI agents tokens and navigation hops on every task, and collapsing them often pays more than adding patterns:

Over-Abstraction Smell	Suggested Fix
Pass-through methods/classes that only relay calls	Inline the layer
Interface with a single implementation and no test seam	Remove the interface
Single-use helpers extracted from one call site	Inline back into the caller
Layer-per-technical-concern, each a few lines thick	Merge into one deep module per domain capability
Deep import chains (A→B→C→D to reach one behavior)	Flatten into a deeper module

For each identified opportunity (pattern or collapse), note:

• The file(s) and code area affected
• The pattern that fits and why — or the layers to collapse and why
• Estimated complexity to apply (LOW / MEDIUM / HIGH)
• Whether to address it in this refactoring cycle or defer

Apply the Depth Test from skills/refactor-code/references/deep-modules.md before recommending any pattern: it must make modules deeper, not just add structure.

Save pattern opportunities to refactor-notes/03c-pattern-opportunities.md.

For detailed pattern descriptions and application guides, see the design-patterns skill and its reference docs (skills/design-patterns/references/).

Step 9: Generate Architecture Diagram

Produce a text-based architecture diagram from the analysis outputs showing how major modules connect. Use arrows for data flow and dependency direction. Group files by feature area or layer.

Include the diagram in the project summary.

Step 10: Project Summary

Synthesize all outputs into a single document covering:

• Executive overview
• Architecture diagram (from Step 8)
• Key data flows
• Dependency health
• Code quality assessment
• Design pattern opportunities (from Step 8)
• Refactoring priority map (ranked by impact and effort)
• Risks and considerations

Save as refactor-notes/04-project-summary.md.

Output

After completing all steps, present the user with:

1. A brief summary of findings (3-5 sentences)
2. The top 3 refactoring priorities with rationale
3. Links to the saved documents for full details

Important Notes

• For large codebases, focus on one module or feature area at a time.
• For sensitive code, see references/anonymization.md for local model strategies.
• Save all outputs — they are required context for subsequent phases.
• Be honest about areas of uncertainty. If a file's purpose is unclear, say so.