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

Scan the target directory for issues
Document findings in a table (Security → Bugs → Code Health)
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

Audit only, no fixes: Discover and document—never modify code
Track everything: All findings become work items
Scoped analysis: Stay within the target directory unless context requires external references
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