Audit Process

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
3. Why this matters -- context compaction can happen at any time; only files persist

Scope: Automation Types

Audit Categories: 12 Dimensions

Standard Audit Procedures

Read CANON/templates/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-backend.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