health-audit

name	health-audit
model	opus
description	Produces engineering commissions — structured implementation prompts stored in `docs/audits/` and `prompts/` — by auditing repositories for critical issues, security gaps, and sustainability risks. Use when: 'audit this repo', 'what are the blockers', 'run a full health check', 'identify technical debt before a sprint', 'onboarding to a new codebase'.
category	system-health
triggers	["audit this repo","what are the blockers","run a full health check","identify technical debt before a sprint","onboarding to a new codebase"]
tier	1
agents	["primary"]
tool_dependencies	["file_system"]
inputs	[{"name":"repo_path","type":"string","description":"Path to the repository to audit for critical issues and technical debt","required":true}]
outputs	[{"name":"engineering_commissions","type":"ref","format":"cas-ref","description":"Structured implementation prompts stored in docs/audits/ and prompts/ covering critical issues, security gaps, and sustainability risks"}]

Health Audit Skill

I. Philosophy

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 audit is a gardener's walk, not a mechanic's checklist — the role is to tend the ecosystem, protect the conditions for growth, and ensure the space can fulfill its intended purpose.

This skill produces two types of artifacts that distinguish it from repo-status (which writes status documents) and documentation-audit (which logs documentation drift): a permanent audit log recording what was found, and actionable engineering commissions that give implementation agents everything they need to fix the issues autonomously.

II. When to Use This Skill

• As a scheduled, recurring task (e.g., on the first day of each month) for critical repositories.
• When onboarding to a new set of repositories: to establish a baseline health assessment.
• After a major release or architectural change: to audit the impact on the system's overall health.
• When a project feels "at risk" due to technical debt or process gaps.

Do not use this skill to write status documents (use repo-status) or to audit documentation accuracy (use documentation-audit). Health audit is specifically about generating engineering commissions.

III. The Health Supervision Workflow

Phase 1: Grounding

Objective: Understand what the repository is for before evaluating how well it works.

1. Use repo-context-sync to extract directory structure, recent diffs, and file patterns.
2. Read core philosophy, architecture, and purpose documents (README.md, PHILOSOPHY.md, ARCHITECTURE.md, etc.).
3. Identify the tech stack, active branches, and CI/CD status before assessing anything.

Phase 2: Health Audit and Logging

Objective: Systematically assess the repository's health and create a permanent record.

1. Ensure docs/audits/ directory exists. Create it if not.
2. Create a new audit log: docs/audits/YYYY-MM-DD_health_audit.md.
3. Conduct assessment using the Health Assessment Framework (Section IV):
   • Critical Issues: blockers, build failures, critical dependency vulnerabilities.
   • Security Issues: encryption gaps, secret management flaws, authentication vulnerabilities.
   • Sustainability Issues: technical debt, manual processes, documentation drift, testing gaps, paused development.