health-audit

Health Audit Skill

Use this skill when the user wants a deep audit of a codebase's health, quality, maintainability, UX implications, architecture, duplication, testing, or long-term fitness. The skill may audit the whole system or focus on a user-specified area, workflow, module, or risk surface.

Mission

Perform a rigorous, evidence-backed codebase health audit from multiple perspectives: engineering quality, architecture, maintainability, duplication/DRY, UX and product signals, performance, security, reliability, testing quality, consistency, documentation/DX, technical debt, and strategic product fitness.

Do not produce vague "best practices" fluff. Do not invent problems. Do not nitpick style unless it causes real confusion, defects, or maintenance cost.

Focus Prompt Support

This skill can take an optional prompt that describes the area of the system to focus on.

Examples:

• "Focus on the billing pipeline"
• "Review auth/session management"
• "Audit the admin reporting flow"
• "Look at the sync worker and retry logic"
• "Review the checkout path from cart to payment confirmation"

When a focus prompt is provided:

• Treat it as the primary audit scope
• Resolve it into concrete files, modules, routes, jobs, tests, and shared dependencies
• Audit out-of-scope code only when it is required to explain an in-scope finding
• Keep findings, scores, and recommendations scoped to that area instead of pretending to grade the entire repository
• State assumptions, included areas, and excluded areas explicitly in the output

If the prompt is ambiguous, infer the most likely scope from the repository structure and naming, then state the assumption instead of silently widening the audit.

---

Core Rules

The Evidence Rule (NON-NEGOTIABLE)

You must PROVE every finding before reporting it. For each issue you surface, provide:

1. Concrete file paths and line numbers where the problem exists
2. The specific code or pattern that demonstrates the issue (include snippets)
3. A clear articulation of real-world harm — who is affected and how
4. A second instance or a corroborating signal (a reproduction, a failing test, a call path traced end to end) that confirms the problem is real. A one-off defect qualifies once you have reproduced or traced it; it does not need a twin