code-docs-align

Code-Docs Alignment: Documentation Accuracy Investigation

Verify that documentation matches code. Find stale, misleading, or phantom docs.

This skill is purely noetic — it discovers mismatches between documentation and code. It does NOT fix anything. The output (findings, goals, unknowns) feeds into the Empirica workflow for praxic remediation.

Why this matters: For AI-based workflows and enterprise evaluation, stale documentation is worse than missing documentation — it actively misleads. /code-audit checks code quality. docs-assess checks doc coverage. This skill checks the gap: do the docs match the code?

---

How to Run

/code-docs-align                              # Check entire project
/code-docs-align --target src/handlers/       # Check specific directory
/code-docs-align --focus docstrings           # Focus on one dimension
/code-docs-align --focus todos                # Focus on TODO/FIXME audit
/code-docs-align --focus ref-docs             # Focus on ref-doc accuracy

---

Phase 0: PREFLIGHT

Open a transaction before investigating.

empirica preflight-submit - << 'EOF'
{
  "work_type": "docs",
  "task_context": "Code-docs alignment audit on <target>",
  "vectors": { "...": "YOUR OWN assessment across the 13 vectors" },
  "reasoning": "What you actually know about this codebase's docs right now"
}
EOF

No canned vector values. This skill used to print a fixed block — know: 0.2, uncertainty: 0.7 and so on — for you to submit verbatim. That teaches the one habit the whole measurement layer exists to prevent: reporting numbers you did not assess. A pasted vector set is not a low reading, it is a fabricated one, and it corrupts the calibration record more than skipping the transaction would.

Assess where you genuinely are. If you have already read the docs you are about to audit, know is not 0.2, and saying so is the point.

If you were already grounded before opening — you read the target first — declare claims in PREFLIGHT with grounding read (or ran with scope and count) and proceed straight to praxic. No CHECK needed; see /epistemic-transaction.