SuperAPI AI Directory
Partner中文AI newsFavorites
Skillspython-health-audit

python-health-audit

Coding & development

View repository

Updated 10-16 01:49

About this skill

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, plus the Test Coverage summary line and the one-sentence Overall Score interpretation
  • All 9 detailed sections (Tech Stack, Architecture, API/Interface Design, Data Layer, Testing, Code Quality, Documentation & Operations, CI/CD, AI Harness & Adoption) — Testing carries the verbatim Code Coverage: / Coverage Breakdown: fields from Step 0
  • Additional Metrics (no coverage percentages here — coverage lives only in the scorecard summary line and the Testing section fields)
  • Risks & Opportunities (5-8 bullets)
  • Recommendations (6-10 prioritized actions)
  • Appendix: Evidence Index
  • Appendix: Scoring Methodology (weights table; read-only summary — the authoritative weights live in references/report-generator.md)

Step 11. Export Final Report

Goal: Save the final shareable 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/<YYYY-MM-DD>-<project>-python-health-audit.md

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

Command:

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-python-health-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-audit/step_00_test_coverage.md
agents/version-validator.md cheap version-validator reports/.artifacts/python-health-audit/step_00_version_validation.md
agents/repository-inventory.md cheap repository-inventory reports/.artifacts/python-health-audit/step_01_repository_inventory.md
agents/config-analysis.md cheap config-analysis reports/.artifacts/python-health-audit/step_02_config_analysis.md
agents/cicd-analysis.md cheap cicd-analysis reports/.artifacts/python-health-audit/step_03_cicd_analysis.md
agents/testing-analysis.md mid testing-analysis reports/.artifacts/python-health-audit/step_04_testing_analysis.md
agents/code-quality.md mid code-quality reports/.artifacts/python-health-audit/step_05_code_quality.md
agents/api-design-analysis.md mid api-design-analysis reports/.artifacts/python-health-audit/step_06_api_design_analysis.md
agents/data-layer-analysis.md mid data-layer-analysis reports/.artifacts/python-health-audit/step_07_data_layer_analysis.md
agents/documentation-analysis.md cheap documentation-analysis reports/.artifacts/python-health-audit/step_08_documentation_analysis.md
agents/harness-analyzer.md mid harness-analysis reports/.artifacts/python-health-audit/step_09_harness_analysis.md
agents/report-writer.md frontier report-generator, report-format-enforcer reports/<YYYY-MM-DD>-<project>-python-health-audit.md

Report File Name (MANDATORY)

The report file name is always:

<YYYY-MM-DD>-<project>-python-health-audit.md
  • <YYYY-MM-DD> — the date of this run.
  • <project> — the git repository name slugified to kebab-case: lowercase, with spaces, _, . and / turned into -, every other character dropped, and repeated - collapsed. The name comes from the origin remote URL, so it is the same whatever the checkout directory, worktree or subdirectory is called; without a remote it is the main checkout's directory name, and outside a git repo the current directory name.
  • The trailing segment is this skill's name and never changes.

Derive it once, before writing anything:

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-python-health-audit.md"

Everywhere this skill writes reports/<YYYY-MM-DD>-<project>-python-health-audit.md, it means that resolved path.

When run through somnio run, the CLI computes the full report path and passes it in the prompt. Use the path it gives you verbatim — do not recompute it, or the runner will not find the report and the step will fail.

Report Metadata (MANDATORY)

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

Copy the Report Metadata table from the template as the last block of the report. Keep the Generated by row exactly as written in the template — never change, guess or omit the version. Fill the remaining rows as described.

Include this block at the very end of the report:

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | python-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |