audit-code

name	audit-code
description	Audits each directory in ./src for bugs, security vulnerabilities, and performance issues sequentially. Generates one consolidated issue per directory via /create-issue.
license	BSD 3-Clause
compatibility	Node.js project with ./src directory structure
metadata	{"version":"2.2.0","phase-mode":"sequential","target":"./src","agent":"code-review"}

Audit Code

⚠️ EXECUTION RULE: Every code block in this skill is a shell command to execute. Do not print them as text, explain them, or treat them as examples — run them directly.

Audit the ./src directory tree for bugs, security vulnerabilities, and performance issues. Execute sequentially — process one directory at a time, saving state between steps.

State Management

Use a state file to persist progress across responses. The state file is cleaned at the start of a new audit and at the end when all phases are complete.

State File Location

The state file path is provided in the chain context (the text after /audit-code). If no path is provided, default to an example name like audit-state.md — the agent decides where to place it.

Store the path in a variable:

STATE_FILE="${STATE_FILE_PATH:-audit-state.md}"

State File Format

# Audit State

## Phase Queue
- [x] ./src
- [ ] ./src/agent
- [ ] ./src/utils

## Current Phase
./src/agent

## Completed
- ./src

## Findings
[Current phase findings stored here as markdown table]

State Lifecycle

1. Start of audit — Delete any existing state file at the configured path. Begin fresh.
2. After each directory — Save the current state (completed directories, current phase, findings).
3. On resume — Read the state file to determine where to pick up.
4. End of audit — Delete the state file once all phases are complete.

---

Phase Protocol

Phase 0: Discovery

1. Clean state. Delete any existing state file: rm -f "$STATE_FILE"
2. Enumerate directories. List all directories to audit:

   # List ./src and all immediate subdirectories, excluding common patterns
   find ./src -maxdepth 1 -type d | sort
   

3. Sort them alphabetically (the find | sort above handles this).
4. Build the phase queue: [./src, subdir1, subdir2, ...] in alphabetical order.
5. Save the phase queue to the state file:

   cat > "$STATE_FILE" << EOF
   # Audit State
   
   ## Phase Queue
   - [x] ./src
   EOF
   # Append subdirectories
   find ./src -mindepth 1 -maxdepth 1 -type d | sort | while read dir; do
     echo "- [ ] $dir" >> "$STATE_FILE"
   done
   echo "" >> "$STATE_FILE"
   echo "## Current Phase" >> "$STATE_FILE"
   echo "./src" >> "$STATE_FILE"
   echo "" >> "$STATE_FILE"
   echo "## Completed" >> "$STATE_FILE"
   echo "- ./src" >> 
     >> 
     >> 
   

Sequential Directory Processing

Process directories one at a time in alphabetical order.

Directory Scan Execution

For each directory in the queue:

1. Read state. Read the state file to get the current phase:

   CURRENT_PHASE=$(grep -A1 "^## Current Phase" "$STATE_FILE" | tail -1 | tr -d ' \n')
   echo "Processing: $CURRENT_PHASE"
   

2. Enumerate files. List all files in the target directory:

   # Recurse into subdirectories, excluding common patterns
   find "$CURRENT_PHASE" -type f \
     ! -path '*/node_modules/*' \
     ! -path '*/.git/*' \
     ! -path '*/__tests__/*' \
     ! -path '*/.next/*' \
     ! -path '*/dist/*' \
     ! -path '*/build/*' \
     ! -name '*.test.*' \
     ! -name '*.spec.*' \
     ! -name '*.d.ts' \
     ! -name '*.js.map' \
     \( -name '*.js' -o -name '*.ts' -o -name '*.jsx' -o -name '*.tsx' \)
   

3. Audit each file. For each file, check for issues using concrete patterns:

   Bugs — grep for common anti-patterns:

   # Silent catch blocks
   grep -rn 'catch\s*(' "$file" | grep -v 'err' | grep -v 'error'
   # Unhandled promises (no .catch())
   grep -rn '\.then(' "$file" | grep -v '\.catch('
   # console.log in production code
   grep -rn  
   

---

Execution Rules

1. SEQUENTIAL PROCESSING. Process directories one at a time in alphabetical order.
2. NO PARALLELISM. Do not spawn subagents or process multiple directories concurrently.
3. STATE PERSISTENCE. Always save state after processing each directory. Always read state before starting a new directory.
4. ONE ISSUE PER DIRECTORY. Do not combine multiple directories into a single issue.
5. STOP CONDITION. Terminate when all directories in the phase queue have been processed.

Error Handling

• State file not found: If the state file doesn't exist on resume, begin fresh from Phase 0.
• Directory not found: If a directory in the phase queue doesn't exist, skip it and log a warning.
• gh CLI not authenticated: Suggest running gh auth login.
• Network error: Retry once, then report the failure and skip the current directory.
• create-issue failure: Log the error, skip issue creation for this directory, and continue. Do not abort the audit.
• Partial audit: If some directories succeed and others fail, report what was accomplished. Never leave the audit half-done.
• Rate limit: If GitHub API returns 403 rate limit, wait 60 seconds and retry once.

Gotchas

• Security findings must never include raw secret values. The audit table only reports pattern type and count — never the matched line content. Writing secrets to a GitHub issue exposes them to anyone with repo access.
• State file cleanup is critical. Always delete the state file at the start of a new audit and at the end when complete. Stale state files cause incorrect resume behavior.
• gh CLI must be authenticated before starting. The audit will fail silently at Step 6 if gh is not logged in. Run gh auth login first.

Output Format

Each phase response must include:

## Audit: [directory path]
- **Status:** completed | blocked | no-issues
- **Files Audited:** [count]
- **Issues Found:** [count] (critical: N, high: N, medium: N, low: N)
- **Details:**
  - [key-finding-1]
  - [key-finding-2]
- **Action Items:** [issue created with ID or "No issues detected"]
- **Next Steps:** [next directory name or "All phases complete"]