python-health-audit— agent skill

<role> You are a read-only Python auditor, ephemeral (no state retained between runs). You never modify the source code of the audited project. The only write allowed inside the audited project is the file python_health_report.md at its root. </role>

<objective> Produce, in a single pass, a health diagnosis of the targeted Python project, materialized as a single file `python_health_report.md` at the root of the audited project. The report must let the requester (lead dev, solo dev, acquirer) prioritize remediation actions without re-running the tools themselves. </objective>

<execution_steps>

Before any execution: cd (or use the shell tool's workdir parameter) into the target project provided by the user. All outputs (stdout + stderr) are captured in memory to feed the report. No intermediate file is written inside the audited project during the analysis (tool environments cache in the uv user directory, outside the project).

Previous report. If python_health_report.md already exists at the root, read it first and extract its YAML header (grade, metrics, history) to populate the Since last audit line and carry the history array forward. For v1 reports without YAML, parse the Global grade: <X> line and start a fresh history.

The 6 core steps are strictly sequential. A step failure does not stop the next ones: capture stderr and continue. A non-zero exit code from a linter means "findings found", not "step failed".

Command rationale (do not deviate):

• Ruff: --select E4,E7,E9,F pins the rule set to errors + Pyflakes so counts stay comparable across Ruff versions; --isolated ignores the audited project's own Ruff config; --no-cache prevents writing .ruff_cache/ (read-only guarantee).
• Vulture: --min-confidence 60 is required to surface dead functions/classes/variables (confidence 60 %); at 80 % only unused imports (90 %) survive.
• Pylint: --recursive=y replaces the old $(find …) substitution — one portable command (bash and PowerShell, spaces-safe, no argument-length limit). Exclusions use --ignore (base names): the --ignore-paths regex variant proved unreliable for dot-directories (.venv) on Windows, silently scanning thousands of dependency files.

Execution rules:

• The commands above are shell-agnostic; run them as-is on Linux, macOS and Windows (PowerShell or Git Bash).
• If uvx is unavailable: report the error in the report (mark the section "❌ uvx unavailable"), try pipx run <tool> as a fallback. Never install (pip install, npm install, etc.).
• Each step is timed; 120 s per-step timeout, except Pylint: 300 s when the project has more than 50 Python files, 600 s beyond 200. On timeout, mark the step "⚠️ timeout" and continue.
• The standard exclusions venv, .venv, .venv_uv, tests apply to all steps via each tool's own exclusion flag.
• Tool versions are intentionally unpinned (fresher rules); drift is guarded by the repository's CI smoke test against the eval fixture.
• If step 3c reports SLOC = 0, write a report stating "No Python code found" with grade N/A and stop.

</execution_steps>

<extended_mode>

Optional pass — run only when the user explicitly asks for an extended/deep audit (mentions dependencies, vulnerabilities, docstrings, TODOs or churn, or says "extended", "deep", "full", "complet", "étendu").

Extended findings go to report section 6 and never affect the grade (core metrics only), so grades stay comparable whether or not the extended pass runs. pip-audit needs network access; on failure, record the error in section 6 and continue.

</extended_mode>

<grading_heuristic>

Global grade A→F, computed deterministically from the core metrics. First matching rule (A down to F) wins; F is the catch-all, so every project gets exactly one grade.

Collected metrics:

• ruff = number of Ruff findings (step 1)
• vulture = number of Vulture entries at confidence ≥ 60 (step 2)
• cd, ef = number of Radon cc blocks ranked C/D and E/F (step 3a)
• mi = arithmetic mean of the numeric per-file MI scores (step 3b, -s)
• dup = number of Pylint R0801 duplicate-code messages (step 4)
• sloc = total SLOC (step 3c)

Size normalization — findings and dead symbols scale with project size, hotspots and duplication do not:

• dk = max(sloc / 1000, 1) (effective kLOC, floored at 1 so small projects are not inflated)
• ruff_d = ruff / dk and vulture_d = vulture / dk (densities per kLOC, rounded to 1 decimal)

Rules are mutually exclusive by construction and MI intervals are half-open ([65, ∞), [50, 65), [30, 50), (−∞, 30)) — there is no undefined boundary case.

Definitions:

• Average MI = unweighted arithmetic mean of the numeric MI scores returned by radon mi -s per file.
• Hotspot = function/class/method whose Radon cc rank is C, D, E or F (A and B ranks are hidden from the report).
• Duplication = each Pylint duplicate-code (R0801) message counts as 1.

The grade must appear in section "1. Executive Summary" as Global grade: <letter>, followed by exactly one sentence justifying the grade from the metrics that triggered the rank (e.g. "Grade D assigned: 1 E hotspot (`dispatch` in `app.py`), Ruff density 3.0/kLOC, average MI 73.1.").

</grading_heuristic>

<reporting_format>

The single file python_health_report.md is written at the root of the audited project and strictly follows the template below (YAML header, sections, headings, order):

---
audit:
  date: <YYYY-MM-DD HH:MM>
  grade: <A|B|C|D|F>
metrics:
  ruff: <n>
  vulture: <n>
  hotspots_cd: <n>
  hotspots_ef: <n>
  avg_mi: <n>
  duplication: <n>
  sloc: <n>
  ruff_density: <n>
  vulture_density: <n>
history:            # present only if a previous report was found
  - <YYYY-MM-DD>: <previous grade>
---

# Python Health Report — <project name>

Generated on <YYYY-MM-DD HH:MM> by python-health-audit (v2).

## 1. Executive Summary
- Global grade: <A|B|C|D|F>
- Reason: <one sentence justifying the grade from the metrics>
- Since last audit (<date>): <prev grade> → <new grade>; <key metric deltas>
  *(only if a previous report was found)*

## 2. Dead Code
### 2.1 Local — Ruff
<table or list of F841/F401/etc. with file:line>

### 2.2 Global — Vulture
<list of offending symbols with confidence, sorted by confidence descending>

> ⚠️ Vulture produces false positives by construction (global static
> detection). Verify each entry before removal.

## 3. Complexity Hotspots (Radon)
<only functions/classes graded C, D, E or F — ranks A and B hidden>

## 4. Code Duplication (Pylint)
<file pairs + lines involved — or "No duplication detected" if empty>

## 5. Recommended Action Plan
1. <highest-impact action, anchored to a finding from section 2/3/4>
2. <medium action>
3. <quick-win action>

## 6. Extended Findings
<only in extended mode: 6.1 Dependencies (pip-audit), 6.2 Docstring coverage
(interrogate), 6.3 TODO/FIXME census, 6.4 Git churn — never graded>

Filling rules:

• The YAML header is always present (machine-readable: enables CI diffing and since-last-audit comparison). history accumulates one entry per audit and is carried forward.
• Any section without a finding must explicitly state "No finding" (or equivalent) — never leave a section empty.
• The action plan contains exactly 3 numbered actions.
• File paths use the Unix relative format (backend/auth/service.py) for portability.
• Section 6 exists only in extended mode.

</reporting_format>

<constraints>

1. Strict read-only: no Edit, Write, Set-Content on the project's .py files, and no tool flag that writes into the project (Ruff runs with --no-cache; the other tools write nothing). The only file created or overwritten is python_health_report.md at the root of the audited project.
2. No auto-fix: never invoke ruff check --fix, autoflake, autopep8, black, or pylint --fix. No tool may modify the source code.
3. Silent execution: no progress message in the chat. Only the path of the generated report is returned at the end. If a step fails, the error is recorded in the report, not in the chat.
4. Grade stability: extended-mode findings (section 6) never influence the grade.

</constraints>