python-health-audit

---
name: "python-health-audit"
description: "This plan executes the Python Project Health Audit through sequential, modular rules. Each step uses a specific rule that can be executed independently and produces output that feeds into the final report."
license: "MIT"
---

# Python Project Health Audit - Modular Execution Plan

This plan executes the Python Project Health Audit through sequential,
modular rules. Each step uses a specific rule that can be executed
independently and produces output that feeds into the final report.

## Agent Role & Context

**Role**: Python Project Health Auditor

## Your Core Expertise

You are a master at:
- **Comprehensive Project Auditing**: Evaluating all aspects of Python
  project health (tech stack, architecture, API/interface design, testing,
  CI/CD, documentation)
- **Evidence-Based Analysis**: Analyzing repository evidence objectively
  without inventing data or making assumptions
- **Modular Rule Execution**: Coordinating sequential execution of 14
  specialized analysis rules
- **Score Calculation**: Calculating section scores (0-100) and weighted
  overall scores accurately
- **Technical Risk Assessment**: Identifying technical risks, technical debt,
  and project maturity indicators
- **Report Integration**: Synthesizing findings from multiple analysis rules
  into unified Markdown reports
- **Python Best Practices**: Deep knowledge of Python packaging (pyproject.toml,
  uv, pip), type annotations, Ruff, mypy/pyright, pytest, and modern Python
  project conventions
- **Backend Architecture**: Understanding of FastAPI, Django, Flask, layered
  architecture, DDD, hexagonal architecture, and microservices patterns

**Responsibilities**:
- Execute technical audits following the plan steps sequentially
- Report findings objectively based on evidence found in the repository
- Stop execution immediately if MANDATORY steps fail
- Never invent or assume information - report "Unknown" if evidence is missing
- Focus exclusively on technical aspects, exclude
  operational/governance recommendations

**Expected Behavior**:
- **Professional and Evidence-Based**: All findings must be supported
  by actual repository evidence
- **Objective Reporting**: Distinguish clearly between critical issues,
  recommendations, and neutral items
- **Explicit Documentation**: Document what was checked, what was found,
  and what is missing
- **Error Handling**: Stop execution on MANDATORY step failures;
  continue with warnings for non-critical issues
- **No Assumptions**: If something cannot be proven by repository
  evidence, write "Unknown" and specify what would prove it

**Critical Rules**:
- **NEVER recommend CODEOWNERS or SECURITY.md files** - these are
  governance decisions, not technical requirements
- **NEVER recommend operational documentation** (runbooks, deployment
  procedures, monitoring) - focus on technical setup only
- **ALWAYS use uv for Python interpreter alignment** - pinning to
  `.python-version` or `requires-python` in `pyproject.toml` is MANDATORY
- **ALWAYS execute comprehensive dependency management** - root plus every
  package/app directory must have dependencies installed via uv

**Execution Discipline (NON-NEGOTIABLE)**:
- **NEVER skip, combine, or abbreviate any step** — each step in this plan
  MUST be executed individually and completely
- **NEVER summarize a reference file instead of executing it** — you MUST
  read each reference file AND follow its instructions fully
- **NEVER take shortcuts** — even if you believe you already know the answer,
  you MUST execute the analysis commands and collect real evidence
- **ALWAYS read the reference file first** — before executing any step, read
  the referenced .md file completely, then follow its instructions
- **ALWAYS log step completion** — after completing each step, output:
  "STEP N COMPLETED: [brief result summary]" before proceeding to the next
- **NEVER proceed to the next step without completing the current one** —
  partial execution of a step is not acceptable
- **If a step fails**: document the failure, attempt recovery, and only skip
  if recovery is impossible (with explicit documentation of what was skipped
  and why)

## REQUIREMENT - PYTHON INTERPRETER ALIGNMENT

**MANDATORY STEP 0**: Before executing any Python project analysis,
ALWAYS verify and align the Python interpreter version with the project's
required version using uv.

**Rule to Execute**: Read and follow the instructions in `references/version-alignment.md`

**CRITICAL REQUIREMENT**: This step MUST configure uv to pin the Python
interpreter matching `.python-version` or `requires-python` in
`pyproject.toml`. This is non-negotiable and must be executed
successfully before any analysis can proceed.

This requirement applies to ANY Python project regardless of versions
found and ensures accurate analysis by preventing interpreter-related
build and test failures.

## Step 0. Python Environment Setup and Test Coverage Verification

Goal: Configure Python environment with MANDATORY uv interpreter alignment
and execute comprehensive dependency management with tests and coverage
verification.

**CRITICAL**: This step MUST align the Python interpreter using uv and
install ALL dependencies (root, packages, apps). Execution stops if uv
interpreter alignment fails.

**Rules to Execute**:
1. Read and follow the instructions in `references/tool-installer.md` (MANDATORY: Installs uv, Ruff, pyright/mypy, pytest+pytest-cov)
2. Read and follow the instructions in `references/version-alignment.md` (MANDATORY - stops if interpreter alignment fails)
3. Read and follow the instructions in `references/version-validator.md`
4. Read and follow the instructions in `references/test-coverage.md` (coverage generation)

**Execution Order**:
1. Execute `references/tool-installer.md` rule first (MANDATORY - stops if fails)
2. Execute `references/version-alignment.md` rule (MANDATORY - stops if fails)
3. Execute `references/version-validator.md` rule to verify uv setup and
   comprehensive dependency management
4. Execute `references/test-coverage.md` rule to generate coverage

**Comprehensive Dependency Management**:
- Root project: `uv sync` (or `uv pip install -e ".[dev]"` if applicable)
- All packages: `find packages/ -name "pyproject.toml" -execdir uv sync \;`
- All apps: `find apps/ -name "pyproject.toml" -execdir uv sync \;`
- Verification: `uv pip list`
- Build artifacts generation (if build step exists):
  - Root: `uv run python -m build` or equivalent build command
  - Apps: `find apps/ -name "pyproject.toml" -execdir uv run python -m build \;`

**Integration**: Save all outputs from these rules for integration into
the final audit report.

**Failure Handling**: If uv interpreter alignment fails, STOP execution and
provide resolution steps.

## Parallel Execution Strategy

Steps 1-8 can be partially parallelized using the Agent tool to launch
multiple analysis agents simultaneously. Use the following wave structure:

**Wave 0 (Sequential - MANDATORY)**: Step 0 — Environment Setup
  Must complete fully before any analysis begins.

**Wave 1 (Parallel)**: Steps 1 + 2 — Repository Inventory + Configuration Analysis
  Launch both as parallel agents. Both read from the filesystem independently.

**Wave 2 (Parallel)**: Steps 3 + 4 + 5 + 9 — CI/CD + Testing + Code Quality + AI Harness & Adoption
  Launch all four as parallel agents. Independent read-only analyses.

**Wave 3 (Parallel)**: Steps 6 + 7 — API Design + Data Layer
  Launch both as parallel agents. Independent framework-specific analyses.

**Wave 4 (Sequential)**: Step 8 — Documentation Analysis
  Can run after all analysis waves complete.

**Wave 5 (Sequential)**: Steps 10 + 11 — Report Generation + Export
  Must run last — requires ALL previous results.

**Agent Launch Pattern**: For each parallel wave, use the Agent tool to
spawn one agent per step. Each agent MUST:
1. Read the referenced .md file completely
2. Execute ALL instructions in that file
3. Return the complete analysis results
4. Never abbreviate or summarize — return full evidence

Example for Wave 1:
- Agent 1: "Read references/repository-inventory.md and execute ALL instructions. Return complete findings."
- Agent 2: "Read references/config-analysis.md and execute ALL instructions. Return complete findings."

## Step 1. Repository Inventory

Goal: Detect repository structure, monorepo packages, module organization,
and project entry points.

**Rule to Execute**: Read and follow the instructions in `references/repository-inventory.md`

**Integration**: Save repository structure findings for Architecture and
Tech Stack sections.

## Step 2. Core Configuration Files

Goal: Read and analyze Python configuration files for version info,
dependencies, Ruff/mypy/pyright setup, and environment configuration.

**Rule to Execute**: Read and follow the instructions in `references/config-analysis.md`

**Integration**: Save configuration findings for Tech Stack and Code
Quality sections.

## Step 3. CI/CD Workflows Analysis

Goal: Read all GitHub Actions workflows and related CI/CD configuration
files including Docker setup.

**Rule to Execute**: Read and follow the instructions in `references/cicd-analysis.md`

**Integration**: Save CI/CD findings for CI/CD section scoring.

## Step 4. Testing Infrastructure

Goal: Find and classify all test files, identify coverage configuration
and test types (unit, integration, e2e).

**Rule to Execute**: Read and follow the instructions in `references/testing-analysis.md`

**Integration**: Save testing findings for Testing section, integrate
with coverage results from Step 0.

## Step 5. Code Quality and Linter

Goal: Analyze Ruff configuration, mypy/pyright setup, type annotation
coverage, and code quality enforcement.

**Rule to Execute**: Read and follow the instructions in `references/code-quality.md`

**Integration**: Save code quality findings for Code Quality section
scoring.

## Step 6. API / Interface Design Analysis

Goal: Analyze REST/GraphQL API design (FastAPI/Django/Flask routes),
Pydantic models, OpenAPI schema, status/error shape, versioning, and
dependency injection patterns. For libraries, analyze public API surface
and `__all__` exports.

**Rule to Execute**: Read and follow the instructions in `references/api-design-analysis.md`

**Integration**: Save API/interface design findings for API Design section
scoring.

## Step 7. Data Layer Analysis

Goal: Analyze ORM/database integration (SQLAlchemy, Django ORM, Tortoise),
Alembic or framework migrations, repository/Unit-of-Work patterns, N+1
risks, and transaction boundaries.

**Rule to Execute**: Read and follow the instructions in `references/data-layer-analysis.md`

**Integration**: Save data layer findings for Data Layer section scoring.

## Step 8. Documentation Analysis

Goal: Review README, docstring coverage, Sphinx/MkDocs setup, type hints
as inline documentation, and build/setup instructions.

**Rule to Execute**: Read and follow the instructions in `references/documentation-analysis.md`

**Integration**: Save documentation findings for Documentation &
Operations section scoring.

## Step 9. AI Harness & Adoption Analysis

Goal: Score the project's AI harness — CLAUDE.md, `.claude/rules/`,
`settings.json` permissions and hooks, `.claude/agents/`,
commands/skills, and the pre-push git hook — on the 10-dimension,
100-point rubric that judges quality, not just presence.

**Rule to Execute**: Read and follow the instructions in `references/harness-analysis.md`

**Integration**: Save harness findings for the AI Harness & Adoption
section scoring.

## Step 10. Generate Final Report

Goal: Generate the final Python Project Health Audit report by
integrating all analysis results.

**Rule to Execute**: Read and follow the instructions in `references/report-generator.md`

**Integration**: This rule integrates all previous analysis results and
generates the final report.

**Report Sections**:
- Executive Summary with overall score
- At-a-Glance Scorecard with all 9 section scores
- All 9 detailed sections (Tech Stack, Architecture, API/Interface Design,
  Data Layer, Testing, Code Quality, Documentation &
  Operations, CI/CD, AI Harness & Adoption)
- Additional Metrics (including verbatim coverage percentages from Step 0)
- Quality Index
- Risks & Opportunities (5-8 bullets)
- Recommendations (6-10 prioritized actions)
- Appendix: Evidence Index

## Step 11. Export Final Report

Goal: Save the final Google Docs-ready Markdown report to the reports
directory.

**Action**: Create the reports directory if it doesn't exist and save
the final Python Project Health Audit report to:
`./reports/python_audit.md`

**Format**: Markdown-formatted report (use proper Markdown syntax,
use # headings, **bold** markers, and `backtick` code references).

**Command**:
```bash
mkdir -p reports
# Save report content to ./reports/python_audit.md
```

**Note**: For security analysis, run the standalone Security Audit (`/somnio:security-audit`).

## Execution Summary

**Total Rules**: 14 rules

**Rule Execution Order**:
1. `references/tool-installer.md` {model: cheap}
2. `references/version-alignment.md` (MANDATORY - stops if interpreter alignment fails) {model: cheap}
3. `references/version-validator.md` {model: cheap}
4. `references/test-coverage.md` {model: cheap}
5. `references/repository-inventory.md` {model: cheap}
6. `references/config-analysis.md` {model: cheap}
7. `references/cicd-analysis.md` {model: cheap}
8. `references/testing-analysis.md` {model: mid}
9. `references/code-quality.md` {model: mid}
10. `references/api-design-analysis.md` {model: mid}
11. `references/data-layer-analysis.md` {model: mid}
12. `references/documentation-analysis.md` {model: cheap}
13. `references/harness-analysis.md` {model: mid}
14. `references/report-generator.md` {model: frontier}

**Wave-Based Parallel Execution**:
- Wave 0 (Sequential): Step 0 — Environment Setup (rules 1-4)
- Wave 1 (Parallel): Steps 1 + 2 — Repository Inventory + Configuration (rules 5-6)
- Wave 2 (Parallel): Steps 3 + 4 + 5 + 9 — CI/CD + Testing + Code Quality + AI Harness & Adoption (rules 7-9, 13)
- Wave 3 (Parallel): Steps 6 + 7 — API Design + Data Layer (rules 10-11)
- Wave 4 (Sequential): Step 8 — Documentation (rule 12)
- Wave 5 (Sequential): Steps 10 + 11 — Report Generation + Export (rule 14)

**Benefits of Modular Approach**:
- Each rule can be executed independently
- Outputs can be saved and reused
- Easier debugging and maintenance
- Wave-based parallelization accelerates analysis using the Agent tool
- Clear separation of concerns
- Strict no-shortcuts enforcement ensures complete, evidence-based analysis
- Comprehensive dependency management for monorepos
- Complete uv interpreter alignment enforcement
- Full project environment setup with all dependencies

## Subagent Dispatch (in-session)

This section describes the **in-session path** where an orchestrator subagent fans out to tiered analysis subagents using the Agent/Task tool. The Rule Execution Order above remains the **CLI path** (`somnio run`) and is unmodified.

### Entry Point

Invoke `agents/orchestrator.md` as the single entry point. The orchestrator handles all wave dispatch, artifact validation, and handoff to the report-writer.

### Wave Plan

| Wave | Mode | Agents | Tier |
|------|------|--------|------|
| Wave 0 | Sequential (MANDATORY gate) | `env-setup` | cheap |
| Wave 1 | Parallel | `repository-inventory`, `config-analysis` | cheap, cheap |
| Wave 2 | Parallel | `cicd-analysis`, `testing-analysis`, `code-quality`, `harness-analyzer` | cheap, mid, mid, mid |
| Wave 3 | Parallel | `api-design-analysis`, `data-layer-analysis` | mid, mid |
| Wave 4 | Sequential | `documentation-analysis` | cheap |
| Wave 5 | Sequential | `report-writer` | frontier |

### Dispatch Table

| Agent File | Tier | Reference(s) Covered | Artifact |
|------------|------|----------------------|----------|
| `agents/orchestrator.md` | mid | — (routing only) | — |
| `agents/env-setup.md` | cheap | tool-installer, version-alignment, test-coverage | `reports/.artifacts/python_health/step_00_test_coverage.md` |
| `agents/version-validator.md` | cheap | version-validator | `reports/.artifacts/python_health/step_00_version_validation.md` |
| `agents/repository-inventory.md` | cheap | repository-inventory | `reports/.artifacts/python_health/step_01_repository_inventory.md` |
| `agents/config-analysis.md` | cheap | config-analysis | `reports/.artifacts/python_health/step_02_config_analysis.md` |
| `agents/cicd-analysis.md` | cheap | cicd-analysis | `reports/.artifacts/python_health/step_03_cicd_analysis.md` |
| `agents/testing-analysis.md` | mid | testing-analysis | `reports/.artifacts/python_health/step_04_testing_analysis.md` |
| `agents/code-quality.md` | mid | code-quality | `reports/.artifacts/python_health/step_05_code_quality.md` |
| `agents/api-design-analysis.md` | mid | api-design-analysis | `reports/.artifacts/python_health/step_06_api_design_analysis.md` |
| `agents/data-layer-analysis.md` | mid | data-layer-analysis | `reports/.artifacts/python_health/step_07_data_layer_analysis.md` |
| `agents/documentation-analysis.md` | cheap | documentation-analysis | `reports/.artifacts/python_health/step_08_documentation_analysis.md` |
| `agents/harness-analyzer.md` | mid | harness-analysis | `reports/.artifacts/python_health/step_09_harness_analysis.md` |
| `agents/report-writer.md` | frontier | report-generator, report-format-enforcer | `reports/python_audit.md` |

## Report Metadata (MANDATORY)

Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.

To resolve the source and version:
1. Look for `.claude-plugin/plugin.json` by traversing up from this skill's directory
2. If found, read `name` and `version` from that file (plugin context)
3. If not found, use `Somnio CLI` as the name and `unknown` as the version (CLI context)

Include this block at the very end of the report:

```
---
Generated by: [plugin name or "Somnio CLI"] v[version]
Skill: python-health-audit
Date: [YYYY-MM-DD]
Somnio AI Tools: https://github.com/somnio-software/somnio-ai-tools
---
```