Document Audit

Document Audit — Staleness & Consistency Sweep

Purpose

Performs a systematic audit of any document to catch problems that accumulate during iterative editing — stale placeholders, contradictions between sections, orphaned references, and outdated notes.

When to use:

• After incorporating new information (meeting feedback, design updates, stakeholder decisions)
• After multiple rounds of editing in a single session
• As a final quality gate before sharing a document with stakeholders
• When resuming work on a document after a break

Domain-agnostic. Works on requirements docs, PRDs, meeting notes, specs — any structured document.

Step 1: Read the full document

Read the entire document end-to-end using the Read tool. Do not skim. Build an internal model of:

• All section headings and their hierarchy
• All cross-references between sections (e.g., "see Section 5.3")
• All placeholder markers: [PENDING], [PENDING CONFIRMATION], [PENDING LEGAL], [TBD], [TBD —, [UNKNOWN], [TO BE CONFIRMED], [OPEN]
• All assumption references (numbered assumptions, named assumptions)
• All decision markers (confirmed, resolved, rejected, deferred)
• The document's internal timeline (version history, dates, meeting references)

Step 2: Staleness Check

For every placeholder marker found, check:

Output format for each finding:

STALE: [Section/line reference]
   Marker: "[exact marker text]"
   Evidence: [Where the answer exists — section, line, or conversation reference]
   Recommendation: [Remove marker / Update text / Merge with existing content]
   Confidence: [HIGH — answer is explicit / MEDIUM — answer is implied / LOW — may need user confirmation]

Step 3: Contradiction Check

Scan for statements in one section that conflict with statements in another section:

Output format:

CONTRADICTION: [Brief description]
   Location A: [Section — exact text]
   Location B: [Section — exact text]
   Recommendation: [Which one is correct based on context, or flag for user decision]

Step 4: Cross-Reference Check

Verify all internal references resolve correctly:

Output format:

BROKEN REF: [Section — exact reference text]
   Issue: [Target doesn't exist / Target was renumbered / Content doesn't match]
   Recommendation: [Update reference to Section X / Remove reference / Verify with user]

Step 5: Completeness Check

Step 6: Produce Audit Report

Save the report first — then summarize in chat.

Determine output path (in order of precedence)

1. Parent skill provided a path (e.g., called from /requirements-pipeline Stage 9b with an established [output] folder): save inside that folder as stage_output/Stage9b-Document-Audit.md.

2. No parent path — check for existing reports folder: Look in the same directory as the audited document for a folder named report, Report, reports, or Reports (case-insensitive). If found, use it.

3. No reports folder found: Create a reports/ folder in the same directory as the audited document (mkdir -p), then save there.

File name: Audit-Report-[DocumentName].md (e.g., auditing Feature-Requirements-TimeOff.md → saves as reports/Audit-Report-TimeOff.md)

In chat, present only: File path, total finding count by category, and the top 3 highest-priority findings. Do NOT dump the full report into chat.

Report format:

# Document Audit Report

**Document:** [filename]
**Audit date:** [date]
**Findings:** [N] total — [X] stale markers, [Y] contradictions, [Z] broken references, [W] completeness gaps

## Must Fix (HIGH confidence — clear answer exists)

[List findings with HIGH confidence that can be fixed immediately]

## Review Required (MEDIUM confidence — likely stale but needs user confirmation)

[List findings where the answer is implied but not explicit]

## Informational (LOW priority — minor consistency issues)

[List minor findings]

## Summary

[Table: Category | Count | Findings — followed by recommended fix order]

## Summary of Changes Made

[If auto-fixing was requested: list every change made with before/after]

Step 7: Apply Fixes (if requested)

If the user asks to fix issues (or if running as part of the requirements-pipeline):

1. Fix all HIGH confidence findings automatically
2. Present MEDIUM findings for user confirmation before fixing
3. Leave LOW findings as-is unless user requests

Interactive alternative: Instead of fixing inline, the user can invoke the review-findings skill with the audit report from Step 6. This walks through each finding via structured questions, collects decisions, and produces a resolution summary that can be applied via update-documents in one pass. This is especially useful when there are many MEDIUM findings that need individual decisions.

After fixing, re-run Steps 2-5 to verify no new issues were introduced by the fixes.

Critical Rules

1. Read the FULL document. Staleness is only detectable by cross-referencing the entire document. Never audit from a partial read.
2. Never invent answers. If a [PENDING] marker exists and the answer is NOT in the document or conversation, leave it as-is. Report it as "unresolved — still needs input."
3. Cite evidence. Every finding must reference the specific sections where the conflict or staleness exists.
4. Be conservative on auto-fixes. Only auto-fix when the correct answer is explicitly stated elsewhere in the document. When in doubt, flag for user review.
5. Domain-agnostic. This skill works on any structured document. Do not assume a specific document format.
6. Re-audit after fixes. Editing one section to fix a contradiction can introduce new staleness elsewhere. Always re-verify.