Cognitive debt audit

What this audit answers

The cognitive debt audit asks whether the system’s intent, constraints, decisions, and expected behavior can be recovered from durable evidence. It looks for the cost and risk created when important knowledge is missing, stale, contradictory, scattered, or dependent on one person.

This is not a general documentation-volume score. More prose does not help when it is obsolete or disconnected from executable behavior. The audit treats cognitive debt as proxy evidence and states confidence because a repository cannot prove everything people know.

What Guard inspects

Guard follows entry points into product, architecture, domain, onboarding, decision, task, issue, pull-request, handoff, and agent-facing artifacts. It compares those sources with tests, examples, configuration, and observable code behavior. History and external links can supply rationale when accessible.

An external system is not penalized merely because Guard cannot open it. The repository-side bridge is still scoreable: a strong bridge names the authority, explains what belongs there, gives an access path or owner, and summarizes the boundary. A bare “see Jira” reference is weak accessible evidence, while the unreadable Jira content itself remains unknown.

The five dimensions

Each dimension is scored 0–10: intent clarity; executable intent; understanding recoverability; agent intent context; and alignment between accessible intent, tests, docs, decisions, and behavior. Strong scores mean context is current, findable, and usable. Partial scores reflect scattered or important gaps. Low scores require accessible absence, contradiction, or misleading evidence—not speculation about a closed system.

If a dimension demonstrably lives only in an inaccessible external authority, it may be left unscored. Fewer than three scored dimensions makes overall confidence low.

How the score works

Intent clarity and alignment each carry 25%; executable intent and understanding recoverability each carry 20%; agent intent context carries 10%. The weighted 0–10 result becomes a rounded 0–100 score. When a dimension is legitimately unscored, the remaining weights are renormalized rather than treating the unknown as zero.

Evidence-backed caps use accessible facts only. Critical contradictions between product constraints and executable evidence can cap the result below 40. Empty or misleading expected artifacts can cap it below 50; mostly implicit goals with clear dependence on tribal knowledge can cap it below 70; very weak executable intent for critical behavior can cap it below 75; and unavailable history or provider context can cap it below 80 when current documentation is too thin to establish rationale.

Limitations and boundaries

The audit does not rescore formatting, broad maintainability, security, dependency health, test coverage, CI quality, or AI tooling setup. Those surfaces matter only when they support or contradict recoverable intent. Unreadable external context lowers coverage or leaves a dimension unscored; it does not create a finding by itself.

Improvements and reruns

Useful improvements restore a durable bridge: state a product constraint near the code it governs, record a decision and alternatives, connect a critical behavior to an executable example, repair a stale onboarding path, link repository entry points to the authoritative external system, or add product and safety boundaries to agent instructions.

Rerun after the artifact is merged and linked from a discoverable path. The goal is quicker and safer understanding recovery, not a larger docs directory.