audit-code-health

Files (9)

• AGENTS.md
• README.md
• SKILL.md
• metadata.json
• beads-format.md · reference/
• bugs-checklist.md · reference/
• code-health.md · reference/
• examples.md · reference/
• security-issues.md · reference/

SKILL.md (first lines)

# 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](#workflow-overview) 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](reference/security-issues.md) |
| 2        | Bugs        | HIGH     | [bugs-checklist.md](reference/bugs-checklist.md)   |
| 3        | Code Health | MEDIUM   | [code-health.md](reference/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 |

From kyzooghost/skills, MIT.

More from kyzooghost/skills