Jasonmichaelbell78 Creator Sonash V0 Audit Documentation

Single-Session Documentation Audit

When to Use

• User explicitly invokes /audit-documentation

When NOT to Use

• When a more specialized skill exists for the specific task

Execution Mode Selection

Overview

6-stage parallel audit analyzing documentation quality, accuracy, and lifecycle. Each stage produces JSONL output for synthesis.

Total Agents: 18 across 5 stages + 1 synthesis stage Output: docs/audits/single-session/documentation/audit-[YYYY-MM-DD]/

Agent prompts and templates: See prompts.md for all agent prompt text, JSONL schemas, and report templates.

Pre-Audit Validation

1. Episodic Memory Search — past documentation audit findings
2. Read False Positives — docs/technical-debt/FALSE_POSITIVES.jsonl
3. Check Prior Audits — docs/audits/single-session/documentation/
4. Verify Output Directory — mkdir -p "$AUDIT_DIR"
5. Check Thresholds — npm run review:check

Stage 1: Inventory & Baseline (3 Parallel Agents)

Dependencies: 1A, 1B, 1C are fully independent. Stage 2 depends on 1C's link graph.

Completion: Verify all 3 files exist and are non-empty.

Stage 2: Link Validation (4 Parallel Agents)

Completion: Validate JSONL schemas: node scripts/debt/validate-schema.js ${AUDIT_DIR}/stage-2-*.jsonl

Stage 3: Content Quality (4 Parallel Agents)

Stage 4: Format & Structure (3 Parallel Agents)

Stage 5: Placement & Lifecycle (3+1 Agents)

5A, 5B, 5C run in parallel. 5D runs after 5B completes.

Stage 6: Synthesis & Prioritization (Sequential)

6.1 Merge All Findings

cat ${AUDIT_DIR}/stage-2-*.jsonl ${AUDIT_DIR}/stage-3-*.jsonl \
    ${AUDIT_DIR}/stage-4-*.jsonl ${AUDIT_DIR}/stage-5-*.jsonl \
    > ${AUDIT_DIR}/all-findings-raw.jsonl

6.2 Deduplicate

Remove duplicates by file:line. Keep higher severity/confidence/evidence count.

6.3 Cross-Reference FALSE_POSITIVES.jsonl

Filter by file pattern, title pattern, expiration dates.

6.4 Priority Scoring

priority = (severityWeight * categoryMultiplier * confidenceWeight) / effortWeight

Weights: severity S0=100/S1=50/S2=20/S3=5, category links=1.5/accuracy=1.3/ freshness=1.0/format=0.8, confidence HIGH=1.0/MEDIUM=0.7/LOW=0.4, effort E0=1/E1=2/E2=4/E3=8.

6.5 Generate Action Plan

Three queues: Immediate Fixes (S0/S1, E0/E1), Archive Queue, Delete/Merge Queue.

6.6 Generate Final Report

Output ${AUDIT_DIR}/FINAL_REPORT.md. See prompts.md for template.

MASTER_DEBT Cross-Reference (MANDATORY)

Before presenting findings, cross-reference against MASTER_DEBT.jsonl by file path, title similarity, root cause. Classify: Already Tracked (skip) | New (review) | Possibly Related (flag). Only New and Possibly Related proceed to Interactive Review.

Interactive Review (MANDATORY)

Present in batches of 3-5 by severity. Each shows: title, severity, effort, confidence, current state, suggested fix, acceptance tests, counter-argument, recommendation. Track decisions in ${AUDIT_DIR}/REVIEW_DECISIONS.md. See prompts.md for format.

Post-Audit Validation

node scripts/validate-audit.js ${AUDIT_DIR}/all-findings.jsonl

Check: required fields, no FALSE_POSITIVES matches, no duplicates, S0/S1 have HIGH/MEDIUM confidence.

TDMS Intake & Commit

1. Verify all stage files saved
2. Run schema validation
3. npm run validate:canon (if CANON files updated)
4. Update AUDIT_TRACKER.md
5. Reset triggers: node scripts/reset-audit-triggers.js --type=single --category=documentation --apply
6. TDMS Intake: node scripts/debt/intake-audit.js ${AUDIT_DIR}/all-findings.jsonl --source "audit-documentation-$(date +%Y-%m-%d)"
7. Ask: "Fix any issues now?"

Category Mapping

Context Recovery

If interrupted: check .claude/state/audit-documentation-<date>.state.json. If < 24h old, resume from last stage. If stale, start fresh. Preserve partial findings in output directory.

State file tracks: audit_type, date, stage_completed, partial_findings_path, last_updated.

Stage failures: Re-run specific agent. Empty output: Check for errors. Context compaction: Re-read ${AUDIT_DIR}/ and resume.

Update Dependencies

Version History

Documentation References

• PROCEDURE.md - Full TDMS workflow
• JSONL_SCHEMA_STANDARD.md - Output format
• DOCUMENTATION_STANDARDS.md - 5-tier hierarchy

Converted and distributed by TomeVault — claim your Tome and manage your conversions.