Code Doctor

A critical reviewer for any codebase. Its job is to find quality problems and bugs, and it works without a parser, a build, an install, or knowing what language it is looking at.

Today it ships two detectors: repository hygiene (merge markers, oversized files, TODO debt, a committed .env) and committed secrets (key material, recognisable cloud credentials). Everything else in the family's design — duplication, dead-code leads, churn hotspots, a project-toolchain runner — is landing in later plans and is not part of this skill yet.

What this skill is, and is not

It measures quality and bugs. code-visualization explains architecture. If the user wants to understand a codebase, hand off. This skill emits findings, never maps or diagrams.

Reviewer mindset (read this first)

Approach the code as too complex until proven otherwise. The default question is not "is this OK?" but "why isn't this simpler?" Two hard limits keep the criticism honest:

1. Behavior is sacred. Never change what the code does. If it isn't tested, pin current behavior with a characterization test before refactoring.
2. Never assert more than the evidence supports. This skill has no parser. Most of what it observes is heuristic, and saying so is what makes the rest worth reading.

Findings and candidates

Every record is one of two kinds, and the difference is enforced in the schema:

• A finding asserts a defect. It carries a concrete fix.
• A candidate reports a lead needing verification. It carries the specific ways a healthy codebase produces the same observation, and no fix.

Never present a candidate as a defect, and never act on one without checking it first. Recommending an edit on heuristic evidence is how a tool like this talks someone into deleting live code.

Degrade audibly, too: a detector whose evidence can be incomplete (a file it could not read, git being unavailable for a given path) says so in the report rather than staying silent about it. Where a specific record's evidence is incomplete — git could not confirm whether a marker sits in a live conflict, or whether a file is tracked — the detector reports it as a candidate, with the uncertainty named in its also_caused_by, rather than asserting it as a confirmed finding. And it never asserts a negative ("no problems found") from a scan that lost files it could not read.

The three layers

Defer when a specialist exists

Check before reviewing by hand. A specialist sees types and syntax this skill structurally cannot:

This skill also ships scripts/route.py (decides, from the repo's own manifests rather than a filename census, which specialists are justified) and scripts/merge_reports.py (unions several doctors' reports into one attributed envelope). See Routing to the specialists below for the full protocol.

Running the scripts

Let SKILL=/path/to/this/skill — the directory holding this SKILL.md. The commands run from the project being reviewed, so they need that prefix.

Needs Python 3.11+ and nothing else. The detectors are stdlib-only, so there is nothing to install and no build to wait for.

python "$SKILL/scripts/analyze_all.py" .                  # everything, unified report
python "$SKILL/scripts/analyze_all.py" . --format json    # for tooling
python "$SKILL/scripts/analyze_all.py" . --skip secrets   # drop a category
python "$SKILL/scripts/analyze_all.py" . --only hygiene   # run one category alone

python "$SKILL/scripts/find_hygiene_issues.py" .   # merge markers, oversized files, TODO debt, .env
python "$SKILL/scripts/find_secrets.py" .          # key material, cloud credentials

All detectors share one interface: --format text|json, --ignore type1,type2, 🔴/🟡/🟢 severities. They are deliberately conservative — false negatives over false positives — so the output stays trustworthy, and a file that cannot be read is named on stderr rather than counted clean.

Workflow

1. Establish what the repo is. Read the manifest and the entry points. If a specialist covers the bulk of it, load that skill and use this one for the rest.
2. Run the analyzer. Triage deterministic findings before spending judgment.
3. Separate findings from candidates. Act on findings. Verify candidates.
4. Find the hot files. Effort follows change frequency, not line count:

   git log --since="1 year ago" --name-only --pretty=format: \
     | sort | uniq -c | sort -rn | head -30

   Don't refactor cold code.
5. Run the project's own checks — see references/unknown-language-review.md. Never run one without knowing what it does; a lint script may carry --fix.
6. Produce a findings artifact. analyze_all.py's own text output already groups findings ahead of candidates and labels each severity — one smell → one entry → one small PR.

Output & ticketing

The deliverable is always an artifact, never a side effect. Produce a findings list, cards, or JSON. This skill does not create tickets in any system on its own. When the user wants findings filed, ask which tracker or MCP to use and create them through that tool — never assume or fabricate one.

Routing to the specialists

The raw layer works on any repository. Where the project declares a language this repo has a specialist for, that specialist finds things the raw layer cannot, so run it too. Ask the repository, not the filenames:

python "$SKILL/scripts/route.py" <repo> --format json

It answers with the specialists the repo's own manifests justify — python-code-doctor, django-code-doctor, typescript-code-doctor — each with the evidence: a declared dependency, a tsconfig.json, a manage.py beside a settings module defining INSTALLED_APPS. A Go service containing three Python scripts routes nowhere, on purpose — a filename census would send it to python-code-doctor, which would report the missing pyproject.toml it was never supposed to have as a finding.

You are half of this protocol. A Python subprocess cannot load a skill, so route.py only names one and stops — loading it is on you. Run its analyze_all.py over the repository root, never a package subdirectory, where a doctor cannot see the root manifest or the test tree and reports their absence as findings.

Keep every report, then union them:

python "$SKILL/scripts/merge_reports.py" \
  --report code-doctor:$WORK/raw.json \
  --report python-code-doctor:$WORK/py.json \
  --report django-code-doctor:$WORK/dj.json \
  --out $WORK/merged.json --format json

The envelope carries doctors_run, per-doctor analyzers_run, doctor_errors, completeness, and every record stamped with the doctor that produced it — findings and candidates in separate lists. It does not deduplicate: two security detectors flagging one hardcoded key stay two records, because collapsing them changes a count a grader divides by, and that decision belongs to the grader.

Three results are not the same and the envelope keeps them apart:

• A doctor that ran appears in doctors_run with its analyzers_run.
• A doctor that failed appears in doctor_errors. An empty report file is a failure, not a clean result — re-run it, and if you cannot, say which categories now rest on nothing.
• A doctor with no coverage evidence — a bare JSON list, which is what a single detector and a whole analyze_django.py run both emit — appears in coverage_unknown. Nothing in the file distinguishes a full run from one detector that found nothing, so it grants no coverage.

merge_reports.py exits 1 when every report failed. That is not a clean repository; it is a merge with no input.

If a routed specialist is not installed, say so and continue with the raw layer. Correctness is the category that suffers: the only correctness-class defect this skill can prove on its own is a merge marker in a path git reports as unmerged, so a consumer that grades this report should leave Correctness ungraded rather than score it from silence.

Reference index (load on demand)

When NOT to act

• On a candidate you have not verified. That is what the kind means.
• Untested code — write a characterization test first, then refactor.
• Cold code that never changes and blocks nothing.
• Complexity genuinely forced by an external API or a real present requirement.