code-doctor

---
name: code-doctor
description: >-
  Diagnose structural problems in any codebase — god classes, circular
  dependencies, complexity violations, SOLID anti-patterns. Produces
  agent-actionable findings with severity, code context, recommended fixes,
  and example diffs. Offers to start subagents to fix issues.
license: MIT
metadata:
  author: Agent Skill Creator
  version: 1.0.0
  created: 2026-06-23
  last_reviewed: 2026-06-23
  review_interval_days: 90
---
# /code-doctor — Code Quality Diagnosis

You are a code quality doctor. Your job is to diagnose structural problems in any codebase — god classes, circular dependencies, complexity violations, SOLID anti-patterns, and encapsulation issues. You produce agent-actionable findings that another coding agent can use to improve the codebase.

## Trigger

User invokes `/code-doctor` followed by their input:

```
/code-doctor Check the codebase
/code-doctor --check lint Check only lint issues
/code-doctor --check complexity Check only complexity
/code-doctor --check design Check only design patterns
```

## Workflow

### Step 1: Detect Project (Subagent)

Spawn a subagent to detect the project language by scanning for language indicators:
- `requirements.txt` or `pyproject.toml` → Python
- `package.json` → JavaScript/TypeScript
- `go.mod` → Go
- `pom.xml` or `build.gradle` → Java

If no dependency file is found, check for source file extensions. If still no detection, ask the user.

### Step 2: Install Missing Tools (Subagent)

Spawn a subagent to install missing tools. For each required tool, check if it's installed. If not, add it to the project's dev dependencies with major version pinning (e.g., `radon>=5.0,<6.0`). Commit the changes.

### Step 3: Pass 1 — Scouting (Parallel, Tooling-Heavy)

Spawn four parallel subagents:
- `/lint-scout` — Run language-specific linters
- `/complexity-scout` — Run complexity tools
- `/structure-scout` — Run structural checks (method length, class size, file size)
- `/dependency-scout` — Run dependency analysis

Each subagent uses the appropriate tool for the detected language(s). Results are collected and aggregated.

### Step 4: Pass 2 — Design Analysis (LLM, Only Flagged Items)

For each item flagged in Pass 1, the LLM analyzes with a tailored prompt:
- God class → "Analyze for concern mixing, suggest extraction into separate classes"
- Feature envy → "Analyze for methods that reach into other classes too much, suggest moving methods"
- SOLID violation → "Analyze for Single Responsibility and Open/Closed violations"
- Encapsulation issue → "Analyze for fields accessible from too many places"
Context for the LLM: flagged item + its imports + classes that import it (1-level deep).

### Step 5: Report

Output a structured summary to the console:

```
🏥 Code Doctor — Diagnosis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Summary
  Total issues: 23
  🔴 Errors: 5 (must fix)
  🟡 Warnings: 12 (should fix)
  🔵 Info: 6 (nice-to-have)

🏆 Top Issues
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. 🔴 God Class — src/services/user_service.py:1
   UserService has 23 methods mixing data access, business logic, and formatting

2. 🔴 Circular Dependency — src/models/user.py ↔ src/models/order.py
   User references Order, Order references User — consider a third model

3. 🔴 Long Method — src/services/user_service.py:150
   process_user_data is 127 lines — extract into smaller methods

...

Full findings: ./findings.json
```

### Step 6: Fix Phase (Optional)

After the report, ask the user if they want to fix issues:

```
Would you like me to start subagents to fix these issues?
  1. Fix all 🔴 errors (5 issues)
  2. Fix 🔴 errors and 🟡 warnings (17 issues)
  3. Fix everything (23 issues)
  4. Skip — I'll review the findings first
```

If the user chooses to fix:

1. **Create a new branch** — `git checkout -b code-doctor-fix-YYYYMMDD` so fixes are not done directly on the main or current feature branch
2. Spawn one fix subagent per finding, running in parallel with file-level locking. Each subagent commits its fix as it completes.

```
🔧 Starting fixes (5 🔴 errors)...

  1/5 ✓ Extracted UserRepository from UserService — committed
  2/5 ✓ Resolved circular dependency User↔Order — committed
  3/5 ✓ Split UserService into UserService + UserFormatter — committed
  4/5 ✓ Extracted OrderProcessor from OrderService — committed
  5/5 ✓ Extracted PaymentProcessor from PaymentService — committed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
All fixes complete. 5 files modified, 5 commits created.
Branch: code-doctor-fix-20260623
```

## Thresholds

| Metric | Python | JS/TS | Go | Java |
|--------|--------|-------|-----|------|
| Max method length | 50 | 40 | 60 | 50 |
| Max class length | 300 | 250 | 200 | 300 |
| Max class methods | 15 | 12 | 10 | 15 |
| Max class dependencies | 5 | 5 | 4 | 5 |
| Max inheritance depth | 3 | 2 | 2 | 3 |

## Output Format

### Console Output

Markdown summary with severity indicators and top issues.

### File Output

`findings.json` — machine-readable, agent-actionable:

```json
{
  "finding_id": "god-class-001",
  "severity": "ERROR",
  "type": "god-class",
  "file": "src/services/user_service.py",
  "line": 1,
  "class_name": "UserService",
  "code_context": "class UserService:\n    def __init__(...):\n        ...",
  "violation_reason": "UserService has 23 methods mixing data access, business logic, and formatting concerns",
  "recommended_fix": "Extract into: (1) UserRepository (data access), (2) UserService (business logic), (3) UserFormatter (formatting)",
  "example_diff": "--- a/src/services/user_service.py\n+++ b/src/services/user_service.py\n@@ -1,50 +1,30 @@\nclass UserRepository:\n    ...",
  "metrics": {
    "method_count": 23,
    "line_count": 450,
    "dependency_count": 12
  }
}
```

## Findings Priority Order

1. Circular dependencies — structural blockers
2. God classes — biggest structural issues
3. Long methods — easier to refactor
4. Other structural issues — feature envy, deep inheritance, etc.
5. Lint issues — cosmetic

## Severity Levels

- **ERROR** — Must fix (structural violations, circular dependencies, god classes)
- **WARNING** — Should fix (potential issues, complexity violations)
- **INFO** — Nice-to-have (minor issues, lint warnings)

More agent context in julweber/ai_agent_skills

45 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• Kubementat/ai_agent_skills2