Ln 53 Documentation Auditor

4. Verify Facts and Examples

• Extract material claims about paths, files, symbols, versions, counts, commands, flags, environment variables, configuration keys, ports, endpoints, schemas, and defaults.
• Build a normalized claim ledger before verification and group repeated claims by subject so one repository check can expose both stale copies and cross-document contradictions.
• Verify each claim against current repository evidence or a safe command; record the exact source and scope of the check.
• Resolve installed versions from manifests and lockfiles before consulting external documentation or claiming current support.
• Use official sources for external APIs, deprecations, security standards, platform limits, and compatibility statements.
• Execute examples only in a safe local or disposable context; otherwise inspect parsing, tests, and expected output and mark them statically verified.
• Check examples for missing imports, placeholders presented as real values, invalid paths, unsafe secrets, obsolete syntax, and output that no longer matches behavior.
• Interpret examples, templates, future plans, and external references in their declared context. Verify conditional guidance for supported prerequisites even when currently disabled; do not judge a hypothetical example as deployed behavior.
• Verify numeric counts with a reproducible query and documented exclusions; avoid preserving aggregate counts that will drift without automation.
• Recommend moving change-prone versions, paths, defaults, inventories, generated output, and status snapshots to authoritative code, configuration, or generated sources where practical; otherwise identify the source, scope, and owner or generation/update trigger needed to prevent silent staleness.
• Apply the research-to-action gate: external guidance becomes a finding only when it proves a concrete in-repository defect or risk.

5. Review Comments and Produce the Report

• Check comments and docstrings for useful rationale, invariants, contracts, side effects, failure behavior, and non-obvious constraints.
• For documented deliberate simplifications with material limits, verify supported bounds, an observable revisit trigger, and what to reconsider. Report missing bounds or triggers, exceeded limits, and overdue reviews with evidence and impact; require no special marker and do not label undocumented routine code as debt.
• Match docstrings for public or non-obvious interfaces against the current signature, parameters, return value, raised errors, side effects, nullability, and lifecycle obligations.
• Flag syntax narration, obsolete history, dead code, false promises, and information better expressed by names or types; preserve historical rationale that still explains a constraint or prevents a known regression.
• Check public interfaces for documentation required by the language or ecosystem and for examples that match the actual contract.
• Filter intentional audience simplification, framework convention, generated prose, and accepted legacy constraints before reporting.
• Classify every in-scope document or comment surface as KEEP, ADD, UPDATE, DELETE, or MERGE; recommend deletion or consolidation only when canonical coverage preserves every required audience task and contract.
• Apply the materiality gate: require concrete reader error, blocked task, unsafe action, contradiction, or recurring maintenance cost at evidenced scale. Reject taste, theoretical purity, generic practice, hypothetical scale, and reasonable alternatives; require the outcome or constraint, not a preferred implementation.
• External correction evidence: Ground external corrections in version-matched official contracts, using primary engineering sources for unresolved tradeoffs. Cite the supported mechanism; local evidence suffices for local defects.
• For each accepted finding, identify the owning documentation surface, affected reader outcome, and evidence that a correction would restore trust; do not turn recommendations into authorized edits.
• Classify findings as P0-P3 based on the harm caused by wrong action, inability to operate, maintenance drift, or minor friction.
• Use BLOCKED when a safety-critical claim, required audience journey, or authoritative source cannot be verified without a credible fallback; use FAIL when evidence proves unsafe guidance, an inoperable required journey, or an unresolved P0/P1; use CONCERNS only for material non-blocking trust gaps, and PASS only when required claims and journeys are verified with no material finding.

Self-Check

• Reconcile before returning. Check item-level evidence, requirement coverage, contradictions, scope, verdict, and applicable cleanup. Correct the report or authorized artifacts. Reuse valid evidence; do not automatically rescan the repository or rerun successful commands. Repeat checks only for relevant changes, failures, or unresolved evidence. Disclose remaining gaps.

Output Contract

Report in the user's language, in this order; label all five fields and state each fact once. Use controlled plain language: one fact per sentence, usually under 20 words, active voice, and one term per concept, with no synonyms for verdicts, IDs, or states. Small results may use one line per field; omit empty tables and do not copy linked artifacts:

1. Result: The exact skill-specific verdict token first, then the supported outcome.
2. Scope: Reviewed/changed scope, exclusions, baseline, and material assumptions.
3. Evidence: Skill-specific fields below; distinguish facts, inferences, and unverified claims. Link artifacts; use tables when useful.
4. Verification: Checks/results, unavailable evidence, and applicable cleanup/external state.
5. Completion: Checklist: X/Y complete; Incomplete: None or each UNPROVEN item's reason, outcome impact, and exact next action; residual risks and required decisions.

Skill-specific evidence: Documentation audiences and journeys; structure, coverage, accuracy, durability/SSOT, and comment trust. Record KEEP / ADD / UPDATE / DELETE / MERGE per in-scope surface. Findings need priority, document location, verifying evidence, affected audience, material impact, unacceptable tradeoff, and minimal correction or canonical owner; allow equivalent structures. Distinguish unverified claims from proven defects.