kyzooghost/audit-code-health

Code Health Auditor

Systematic audit process that scans directories to identify security issues, bugs, and code health problems. Findings are tracked as work items for remediation.

Quick Start

Example: For @native-yield-operations/automation-service/ do /audit-code-health

1. Scan the target directory for issues
2. Document findings in a table (Security → Bugs → Code Health)
3. File work items or create a findings summary

For deeper audits, follow the Workflow below.

When to Apply

Use this skill when:

• Auditing a codebase for security vulnerabilities
• Identifying bugs and edge cases
• Assessing technical debt and code health
• Creating structured work items for remediation
• Running systematic code reviews

When NOT to Apply

Do not use this skill when:

• Developing a new feature
• Writing a new test

Core Principles

1. Audit only, no fixes: Discover and document—never modify code
2. Track everything: All findings become work items
3. Scoped analysis: Stay within the target directory unless context requires external references
4. Prioritize by impact: Security → Bugs → Code Health

Audit Categories by Priority

| Priority | Category | Severity | Reference | | -------- | ----------- | -------- | -------------------------------------------------- | | 1 | Security | CRITICAL | security-issues.md | | 2 | Bugs | HIGH | bugs-checklist.md | | 3 | Code Health | MEDIUM | code-health.md |

Quick Reference

Security Issues (CRITICAL)

• Auth/authz errors
• Injection risks (SQL, command, XSS)
• SSRF, path traversal
• Secrets or insecure defaults
• Broken crypto usage
• Missing input validation
• Dependency vulnerabilities

Bugs (HIGH)

• Edge cases and boundary conditions
• Concurrency / race conditions
• Error handling gaps
• Resource leaks
• Numeric overflow/underflow
• Retry / timeout bugs

Code Health (MEDIUM)

• Oversized or high-complexity modules
• Low test coverage near critical logic
• Duplicated abstractions
• Dead code or unused exports
• Poor documentation
• Misleading names

Related Skills

• Smart Contracts: If you detect *.sol files, use the developing-smart-contracts skill for Solidity-specific security patterns
• Unit Testing: Use the unit-testing-guidelines skill to assess test quality and coverage gaps

Workflow Overview

Audits run in cycles. Choose depth based on scope:

| Scope | Cycles | When to Use | | -------------- | ------ | -------------------------------------- | | Quick scan | 1-2 | Small PRs, single files, targeted review | | Standard audit | 3-5 | Feature modules, API surfaces | | Deep audit | 6-10 | Full codebase, security-critical systems |

Each cycle follows: SCAN → FINDINGS → VERIFY → FILE → TRIAGE

Cycle Process

For each cycle, execute these steps:

Cycle Progress:
- [ ] Step 1: SCAN - Inspect target directory
- [ ] Step 2: FINDINGS - Document issues by category
- [ ] Step 3: VERIFY - Validate findings before filing
- [ ] Step 4: FILE - Create work items
- [ ] Step 5: TRIAGE - Assign priorities

Step 1: SCAN

Analyze the target directory:

• Review code for security issues, bugs, and health problems
• Run read-only tooling: build, tests, lint, typecheck
• Use code-simplifier on hotspots (if available)

Step 2: FINDINGS

Produce a findings table grouped by Security, Bugs, Code Health:

| Severity | Type | File(s) | Description | Confidence | | -------- | -------- | ------------- | ------------------ | ---------- | | P0 | Security | auth/jwt.ts | Token not verified | High |

Step 3: VERIFY

Before filing, validate each finding:

• [ ] Confirmed the issue exists (not a false positive)
• [ ] Identified the correct file and line number
• [ ] Assessed severity accurately
• [ ] Checked if issue is already tracked

Step 4: FILE

Create work items for verified findings.

If using Beads (bd):

• See beads-format.md for epic/issue structure
• Use bd commands to create and link items

If bd is not available:

• Use Markdown task lists for tracking findings
• Format: - [ ] [P0/Security] auth/jwt.ts: Token not verified

Step 5: TRIAGE

• Assign P0/P1/P2 priorities
• Identify quick wins vs deep refactors
• Group related issues under epics (if using bd)

Output Format

Each cycle produces:

## Cycle N Summary

### Findings Table
| Severity | Type | File(s) | Description | Confidence | Status |

### Work Items Created
- [P0] ...
- [P1] ...

### Triage Notes
...

### Backlog Overview
Open items grouped by priority

Constraints

• DO NOT implement code changes
• STAY WITHIN target directory unless minimal external context needed
• PREFER many small issues over large vague ones
• VERIFY findings before filing to avoid false positives

Reference Files

• Security Issues Checklist
• Bugs Checklist
• Code Health Checklist
• Beads Format Guide
• Audit Examples