Comprehensive Automation Audit

Version: 2.5 Last Updated: 2026-04-03 Status: ACTIVE

This audit covers 16 automation types across 12 audit categories using a 7-stage approach with parallel agent execution.

When to Use

• Tasks related to audit-process
• User explicitly invokes /audit-process

When NOT to Use

• When the task doesn't match this skill's scope -- check related skills
• When a more specialized skill exists for the specific task

Quick Reference

Total: 22 parallel agents across 6 stages + 1 synthesis stage

CRITICAL: Persistence Rules

EVERY agent MUST write outputs directly to files. NEVER rely on conversation context.

1. Agent outputs go to files, not conversation -- each agent prompt MUST include: Write findings to: ${AUDIT_DIR}/[filename].jsonl
2. Verify after each stage -- check all output files exist and are non-zero. If any file is 0 bytes, apply the Windows output fallback before declaring the stage complete.
3. Why this matters -- context compaction can happen at any time; only files persist
4. Windows output fallback (MUST): Background agent output files may be 0 bytes on Windows (anthropics/claude-code#39791). After each stage completes, check each agent's JSONL output file size. If 0 bytes, capture the task-notification <result> text and write it to the expected stage JSONL file using the Write tool. Do NOT proceed to the next stage until all current stage output files are non-empty. Empty results must never be silently accepted -- report failure to user if no output available via any channel.

Scope: 16 Automation Types

Audit Categories: 12 Dimensions

Standard Audit Procedures

Read .claude/skills/_shared/AUDIT_TEMPLATE.md for standard audit procedures.

Agent Prompts

Read .claude/skills/audit-process/prompts.md for full agent prompt specifications.

Agent Summary

Pre-Audit Setup

Step 0: Episodic Memory Search

Search for context from past sessions before running:

mcp__plugin_episodic -
  memory_episodic -
  memory__search({
    query: ["process audit", "automation", "hooks"],
    limit: 5,
  });

Step 1: Check Thresholds

npm run review:check

Step 2: Create Audit Directory

AUDIT_DATE=$(date +%Y-%m-%d)
AUDIT_DIR="docs/audits/single-session/process/audit-${AUDIT_DATE}"
mkdir -p "${AUDIT_DIR}"

Step 3: Verify Output Directory Variable (CRITICAL)

echo "AUDIT_DIR is: ${AUDIT_DIR}"
ls -la "${AUDIT_DIR}" || echo "ERROR: AUDIT_DIR does not exist"

AUDIT_PATH=$(realpath "${AUDIT_DIR}" 2>/dev/null || echo "${AUDIT_DIR}")
REPO_ROOT=$(realpath "." 2>/dev/null || echo ".")
if [ -z "${AUDIT_DIR}" ] || [ "${AUDIT_PATH}" = "/" ] || [ "${AUDIT_PATH}" = "${REPO_ROOT}" ]; then
  echo "FATAL: AUDIT_DIR must be a proper subdirectory under the repo, not root"
  exit 1
fi

Step 4: Load False Positives

Read docs/technical-debt/FALSE_POSITIVES.jsonl and note patterns to exclude.

Stage Execution

Stage 1: Inventory & Dependency Mapping (6 parallel agents)

Run agents 1A-1F in parallel. After completion, merge into stage-1-inventory.md, build dependency graph, identify orphans. No JSONL findings yet -- discovery only.

Stage 1 Verification (MANDATORY)

STAGE1_FILES="stage-1a-hooks.md stage-1b-scripts.md stage-1c-skills.md stage-1d-ci-config.md stage-1e-firebase.md stage-1f-mcp.md"
for f in $STAGE1_FILES; do
  if [ ! -s "${AUDIT_DIR}/$f" ]; then
    echo "ERROR: Missing or empty: ${AUDIT_DIR}/$f"
    exit 1
  fi
done

Stages 2-6: Analysis (3-4 parallel agents each)

Each stage follows the same pattern:

1. Launch parallel agents (see prompts.md for specifications)
2. Verify all output files exist and are non-zero
3. Merge sub-stage files into canonical rollup (e.g., stage-2-redundancy.jsonl)
4. Run TDMS intake: node scripts/debt/intake-audit.js ${AUDIT_DIR}/stage-N-*.jsonl

Stage verification template (run before proceeding to next stage):

# Check for misplaced files in root (context compaction recovery)
ROOT_AUDIT_FILES=$(ls *.jsonl 2>/dev/null | grep -E "stage-N" | wc -l)
if [ "$ROOT_AUDIT_FILES" -gt 0 ]; then
  echo "WARNING: Found stage files in root directory!"
  mv stage-N*.jsonl "${AUDIT_DIR}/" 2>/dev/null || true
fi

Stage 7: Synthesis & Prioritization (sequential)

1. Merge canonical rollup files into all-findings-raw.jsonl
2. Deduplicate findings
3. Cross-reference with MASTER_DEBT.jsonl
4. Generate priority action plan (Immediate S0-S1, Short-term S2, Backlog S3)
5. Generate AUTOMATION_AUDIT_REPORT.md

MASTER_DEBT Cross-Reference (MANDATORY -- before Interactive Review)

Do NOT present findings for review until cross-referenced against MASTER_DEBT.jsonl. Classify each finding as: Already Tracked (skip), New Finding (review), or Possibly Related (flag). Present only New and Possibly Related findings.

Interactive Review (MANDATORY -- after cross-reference, before TDMS intake)

Present findings in batches of 3-5 items, grouped by severity (S0 first). Each item shows: title, severity, effort, confidence, current state, suggested fix, acceptance tests, counter-argument, and recommendation.

Create ${AUDIT_DIR}/REVIEW_DECISIONS.md after first batch to track decisions. Process: ACCEPTED -> TDMS intake, DECLINED -> remove, DEFERRED -> keep as NEW.

Post-Audit (MANDATORY)

1. Validate: node scripts/validate-audit.js ${AUDIT_DIR}/all-findings-raw.jsonl
2. Update AUDIT_TRACKER.md with date, session, findings count, validation status
3. Reset threshold: node scripts/reset-audit-triggers.js --type=single --category=process --apply
4. Reconcile TDMS: node scripts/debt/validate-schema.js docs/technical-debt/MASTER_DEBT.jsonl
5. Regenerate views: node scripts/debt/generate-views.js
6. Commit: git add docs/audits/single-session/process/ docs/technical-debt/

Running Individual Stages

• /audit-process stage 1 - Run only Stage 1 (Inventory)
• /audit-process stage 2 - Run only Stage 2 (Redundancy)
• /audit-process stage 3-4 - Run Stages 3 and 4
• /audit-process full - Run all 7 stages (default)

Note: Stages 2-6 depend on Stage 1 inventory.

Threshold System

Process audit triggers: ANY CI/hook/script file changed since last audit, OR 75+ commits since last audit.

Evidence Requirements

All findings MUST include: file, line, title, description, recommendation, severity, category. S0/S1 require HIGH or MEDIUM confidence, dual-pass verification, and tool validation where possible.

Context Recovery

If the session is interrupted:

1. Check state file: .claude/state/audit-process-<date>.state.json
2. If < 24 hours old: resume from last completed stage
3. If stale: start fresh
4. Check root for misplaced files and move to ${AUDIT_DIR}/
5. Identify completed vs missing stages and resume

for stage in 1 2 3 4 5 6; do
  count=$(ls ${AUDIT_DIR}/stage-${stage}*.* 2>/dev/null | wc -l)
  if [ "$count" -gt 0 ]; then
    echo "Stage $stage: FOUND ($count files)"
  else
    echo "Stage $stage: MISSING"
  fi
done

Version History

Documentation References

TDMS Integration (Required)

• PROCEDURE.md - Full TDMS workflow
• MASTER_DEBT.jsonl - Canonical debt store

Documentation Standards (Required)

• JSONL_SCHEMA_STANDARD.md - Output format requirements and TDMS field mapping
• DOCUMENTATION_STANDARDS.md - 5-tier doc hierarchy
• CODE_PATTERNS.md - Anti-patterns to check