health-audit

Health Audit Skill

Version: 1.0 Created: 2026-02-11 Purpose: Provide a structured, repeatable methodology for auditing the health of software repositories, generating actionable engineering tasks, and creating a permanent audit trail.

---

I. The Philosophy: Tending the Garden

Health is not merely the absence of bugs; it is the presence of practices that ensure security, sustainability, and alignment with a project's core purpose. A health auditor is a gardener, not a mechanic. The role is to tend the ecosystem, protect the conditions for growth, and ensure the space can fulfill its intended purpose.

This skill codifies a workflow that moves from deep listening to decisive action, ensuring that every intervention is both contextually aware and technically precise. It creates a permanent, auditable trail of health assessments and corrective actions.

The core principle: maintenance is not just fixing what's broken -- it's keeping what works working well. Regular audits compound quality. A single audit is a snapshot; a series of audits reveals a trajectory. That trajectory -- improving or degrading -- is the truest measure of project health.

---

II. When to Use This Skill

• As a scheduled, recurring task (e.g., monthly or quarterly) to maintain regular health monitoring for critical repositories.
• When onboarding to a new codebase to establish a baseline health assessment before making changes.
• After a major release or architectural change to audit the impact on overall system health.
• When a project feels "at risk" due to accumulating technical debt, missing tests, or process gaps.
• Before a sprint planning session to prioritize health improvement tasks alongside feature work.
• When inheriting a project from another team to understand the current state before assuming ownership.

When NOT to use: For a quick code review of a single PR (that's a code review, not a health audit). For understanding what a system does (use semantic clusters instead). For checking a single document (use documentation audit instead).