codebase-analysis

Codebase Analysis

Scan, score, and analyze a codebase across three lenses in parallel. Python script does fast deterministic scanning; three agents do deep reasoning concurrently. Produces a persistent report.

Core principle: Numbers first, judgment second. Script finds what's big/complex, agents read the actual code to decide what matters.

---

Agents

This skill orchestrates three agents that run in parallel (they are independent):

Agent	File	Job
file-size-analyzer	agents/file-size-analyzer.md	Read large files, assess KEEP/SPLIT/CONSIDER
scope-organizer	agents/scope-organizer.md	Map directory structure, check cohesion & coupling
pattern-detector	agents/pattern-detector.md	Grep for naming, errors, anti-patterns, good patterns

---

When to Use

• Onboarding to a new/unfamiliar codebase
• "This repo feels messy" — need concrete data
• Pre-refactoring assessment
• Periodic health checks
• After rapid growth phases

Do NOT use for:

• Single file reviews (just read the file)
• Known bugs (use systematic-debugging)
• Style-only issues (use a linter)

---

Step 1: Run the Scanner

Run analyzer.py from this skill's directory. It scans the filesystem, counts lines/keywords/imports, scores files, and groups by scope.

# ASCII overview for the user
python skills/codebase-analysis/analyzer.py --root . --ascii

# JSON data for agents
python skills/codebase-analysis/analyzer.py --root . > /tmp/codebase-scan.json

Flags: --threshold N (min lines, default 200), --scope path/ (focus areas)

Present the ASCII report to the user. Read the JSON output — this is the data you'll feed to agents.

---

Step 2: Spawn 3 Agents in Parallel

From the JSON scan results, prepare the data slices and launch all three agents simultaneously using the Agent tool. All three in a single message — do NOT wait between them.

Agent 1: file-size-analyzer

Input: Top 10 largest files (or all files in urgent/refactor categories) with their paths, line counts, scores, and language. Prompt template:

Analyze these files from a codebase scan. For each, read the file and assess KEEP/SPLIT/CONSIDER.

Project: {project_name} ({project_type})
Files:
{for each file: path, lines, score, language, category}

Follow your agent instructions for process and output format.