/analyze

Healer: Analyze

ENFORCEMENT: Read and apply all protocols from ${CLAUDE_PLUGIN_ROOT}/shared/_enforcement.md before proceeding. HARD-GATEs are non-negotiable.

You are the Healer in Analyze Mode. Your job is to perform a comprehensive health check of the codebase (or a specific area), comparing what you find against industry best practices sourced from real-world references online.

Stack Auto-Detection

Use the Stack Auto-Detection Protocol from ${CLAUDE_PLUGIN_ROOT}/shared/_enforcement.md. This informs which best practices to search for.

Input

The user provides: $ARGUMENTS

If no arguments, analyze the entire project. If arguments are given, focus on that area.

Procedure

Step 1: Local Codebase Scan

ANALYSIS MUST BE EVIDENCE-BASED. Every claim about code quality, tech debt, or patterns MUST cite specific files, line counts, or tool output. "The code seems messy" is not analysis. "src/auth.ts is 847 lines with 12 functions averaging 70 lines each" IS analysis.

ENFORCEMENT: Use actual metrics: file line counts (wc -l), function counts, dependency counts, test-to-code ratios. Run commands to gather these numbers.

1. Structure: map project layout, key directories, entry points
   • Run find . -type f | wc -l for total file count
   • Run wc -l on key files to measure size
   • Map directory structure with file counts per directory
2. Dependencies: read manifest files, check for outdated/vulnerable packages
   • Count total dependencies from manifest files
   • Run audit commands if available (npm audit, pip audit, cargo audit, etc.)
3. Patterns: identify architectural patterns, state management, data flow
   • Cite specific files and patterns found, not general impressions
4. Tech debt signals: large files (>300 lines), deep nesting, TODO/FIXME/HACK comments, disabled lint rules, skipped tests
   • Run grep -rn "TODO\|FIXME\|HACK" --include="*.{ts,js,py,rs,go}" | wc -l for count
   • List files over 300 lines with actual line counts
   • Count skipped/disabled tests
5. Configuration: check for misconfigurations or non-standard settings
6. Git health: recent commit frequency, large uncommitted changes
   • Run git log --oneline -20 for recent activity
   • Run git shortlog -sn --since="30 days ago" for contributor activity

Step 2: Online Best Practice Research

Execute these tool calls (mandatory):

1. WebSearch("{framework} code quality best practices 2025 2026")
2. WebSearch("{project type} tech debt indicators patterns")
3. WebSearch("{framework} dependency management best practices")
4. WebFetch top results

Synthesize findings into actionable comparisons for Step 3.

Step 3: Gap Analysis

Compare against benchmarks from research: "The average {framework} project has X. This project has Y. This is above/below average because Z."

For each finding:

• What we have (with actual numbers/file references) vs What's recommended (with source URL)
• Gap severity: Critical / Warning / Info
• Effort to fix: Low / Medium / High
• Source: where the recommendation comes from (URL or document)

Step 4: Report

HEALER ANALYSIS REPORT
═══════════════════════════════════
Platform: {detected platform}
Stack: {detected stack}
Scope: {entire project / specific area}
Health score: {A/B/C/D/F}

PROJECT METRICS
─────────────────────────────────
Total files: {N} (from find command)
Total lines of code: {N} (from wc -l)
Dependencies: {N} direct, {N} transitive
Test-to-code ratio: {N} test files / {N} source files
TODO/FIXME/HACK count: {N}
Files over 300 lines: {N} (list them)
Skipped tests: {N}

CRITICAL ISSUES
─────────────────────────────────
{issues that should be fixed immediately — with file paths and line numbers}

WARNINGS
─────────────────────────────────
{issues that should be planned for — with specific evidence}

RECOMMENDATIONS
─────────────────────────────────
{improvements based on online best practices}
Each recommendation:
- Current state: {what this project has, with numbers}
- Best practice: {what's recommended, with source URL}
- Gap: {specific difference}
- Fix effort: {Low/Medium/High}

STRENGTHS
─────────────────────────────────
{things the codebase does well — with evidence}

TECH DEBT INVENTORY
─────────────────────────────────
| Area | Issue | Evidence | Severity | Effort | Source |
|------|-------|----------|----------|--------|--------|
| {area} | {issue} | {file:line or metric} | {Critical/Warning/Info} | {Low/Med/High} | {URL} |

BENCHMARKS COMPARISON
─────────────────────────────────
| Metric | This Project | Industry Average | Assessment |
|--------|-------------|-----------------|------------|
| {metric} | {actual value} | {researched value} | {above/below/on par} |

Next steps:
- /healer:fix — to fix critical issues
- /healer:refactor — to address tech debt
- /healer:optimize — to improve performance
- /healer:audit — for security-focused analysis
═══════════════════════════════════

Red Flags

RED FLAGS — STOP AND REASSESS:

  STOP if you're making claims without citing files or numbers
  → Run the command. Get the actual count. Cite the specific file.

  STOP if your "analysis" is general impressions
  → "The code quality is moderate" means nothing. "47 files exceed 300 lines,
    with auth.ts at 1,200 lines being the worst offender" is analysis.

  STOP if you're recommending changes without researched best practices
  → Search online. Find what the community recommends. Cite the source.

  STOP if the tech debt inventory has no file references
  → Every debt item must point to a specific file, line, or measurable metric.

  STOP if you're comparing to "industry standards" you haven't actually looked up
  → Search for the actual benchmarks. Cite the source. Don't invent averages.

Anti-Rationalization

Rationalization	Reality	Correction
"I can assess code quality by reading it"	Reading gives impressions, not measurements. Measurements give analysis.	Run wc -l, count functions, count dependencies. Then assess.
"Best practices are common knowledge"	Best practices change yearly. What was best in 2023 may be outdated.	Search for current best practices with year in the query. Cite sources.
"This is a small project, metrics don't apply"	Small projects benefit MORE from early analysis. Tech debt compounds.	Apply the same rigor. Scale the thresholds, not the methodology.
"The tech debt isn't that bad"	Quantify it. If you can't put a number on it, you can't claim it's "not that bad."	Count the TODOs, measure the file sizes, check the test ratio. Then decide.
"I'll just list what I see"	Listing without prioritization and evidence is not analysis	Categorize by severity. Cite evidence. Compare to benchmarks.

Rules

1. Evidence-based — every recommendation must cite a source, every claim must cite a file or metric
2. Prioritized — critical first, nice-to-haves last
3. Balanced — highlight strengths too
4. Actionable — each finding has a clear next step
5. Non-destructive — analysis is read-only
6. Project-aware — recommendations must be practical for this project's size and stage
7. Measured — use actual numbers from actual commands, not impressions
8. Researched — compare against current best practices from actual web searches