audit-repo

Overview

Compare the current repository's configuration against the canonical RAE template (templates/pyproject.toml) and report discrepancies. For major structural differences (e.g., no src/ layout in an established repo), ask the user before proposing changes.

This skill does NOT automatically fix everything. It reports what it finds, fixes trivial gaps (missing ruff subsections, missing dev deps), and asks about anything that would be disruptive to change.

Steps

1. Read the Canonical Template

Read templates/pyproject.toml from the RAE plugin directory to get the current source of truth. This template defines the expected configuration for:

• Build system (hatchling)
• Python version constraint (>=3.11)
• Dev dependencies (pytest, pytest-cov, ruff)
• Ruff config (line-length, lint rules, isort, format)
• Pytest config (testpaths, pythonpath, addopts, coverage)
• Coverage config (fail_under = 80)

2. Read the Current Repo

Read the current repository's:

• pyproject.toml (required — if missing, this is a scaffold-repo situation, not an audit)
• CLAUDE.md (optional but recommended)
• Directory structure (src/ vs flat layout)

3. Compare and Categorize

Compare each section and categorize discrepancies:

Auto-fixable (apply without asking):

• Missing [tool.ruff.lint.isort] section
• Missing [tool.ruff.format] section
• Missing [tool.ruff] src key
• Missing ruff lint rules that are in the template
• Missing [tool.pytest.ini_options] section
• Missing [tool.coverage.run] or [tool.coverage.report] sections

Ask the user first:

• No src/ layout (established repos may have good reasons)
• Dev dependencies missing from [project.optional-dependencies] when they're installed some other way (e.g., devcontainer, system-level)
• line-length differs from 120
• Extra ignore rules not in the template (may be project-specific, e.g., F722 for jaxtyping)
• Missing CLAUDE.md (offer to create one)
• Build system differs from hatchling

Informational only (report but don't change):

• No .github/ CI workflows
• No .pre-commit-config.yaml (RAE does not require this)
• Coverage threshold differs from 80 (may be intentionally lower for legacy repos)

4. Report Findings

Present a summary table:

## Audit Results: {repo_name}

### Aligned with RAE
- [x] ruff line-length = 120
- [x] Python >= 3.11
- ...

### Gaps Found
| Gap | Category | Action |
|-----|----------|--------|
| Missing [tool.ruff.format] | Auto-fix | Will add |
| Missing pytest config | Auto-fix | Will add |
| No src/ layout | Ask user | Uses body_models/ directly |
| Extra ignore F722 | Informational | Needed for jaxtyping |

### Recommended additions to CLAUDE.md
- Document F722 exception and why it's needed
- ...

5. Apply Fixes

• Apply all auto-fixable changes to pyproject.toml
• For each "ask user" item, present the discrepancy and ask whether to fix or document as intentional
• Intentional deviations should be noted in the repo's CLAUDE.md under a ## RAE Deviations section so future audits understand why

6. Verify

After applying fixes:

ruff format --check .
ruff check .

Report any issues from the verification step.

Important Notes

• The canonical source of truth is always templates/pyproject.toml in the RAE plugin
• This skill does NOT enforce src/ layout changes on established repos — that's too disruptive
• Extra ignore rules are often legitimate (F722 for jaxtyping, etc.) — ask, don't remove
• The goal is convergence over time, not instant compliance