Cognitive debt audit: how Guard measures whether system intent can be recovered

What question does the Cognitive debt audit answer?

The audit begins with one exact question: Can a future human or AI agent recover what this system is for, which constraints matter, why important decisions were made, and how expected behavior is proven without guessing?

That question is narrower than measuring everything a team knows. Guard cannot interview the people who designed the system or inspect memories that never became durable evidence. It reads the current repository, bounded provider context when available, and external authorities that the task or repository links directly. The result is therefore an evidence-backed proxy for knowledge recovery at one commit, not a claim that organizational knowledge is complete.

Cognitive debt appears when a maintainer has to reconstruct purpose, constraints, rationale, or expected behavior through guesswork. The directly auditable form is intent debt: repository evidence is missing, stale, incomplete, contradictory, disconnected, or misleading. A rule that exists only in someone's memory may be important, but the audit can say only that it was not present in the evidence it could inspect. It cannot say the rule does not exist.

Recurring checks make this distinction useful over time. A new feature can add behavior without adding its decision record; an updated agent guide can preserve commands while dropping the product boundary behind them. Guard surfaces that drift so a person can decide what to make explicit. The audit itself remains read-only and does not rewrite the repository or decide product intent for the team.

What Guard inventories before scoring

Guard first resolves one unambiguous provider-neutral repository. It records the complete repository path, default branch, full audited commit, available history depth, and safe browser links when the hosting platform makes them derivable. It also records what could actually be inspected: code, default-branch metadata, Git history, issue and review metadata, and explicitly linked external context can each be available, limited, or unavailable in different ways.

Repository shape guides discovery without changing the scoring model. An application, service, CLI, library, plugin, worker, monorepo, or docs/config repository will place intent in different surfaces, but each is judged through the same five dimensions. The inventory identifies languages, frameworks, package managers, source and test roots, docs, runtime and infrastructure files, generated roots, and important entry points before interpreting any one artifact.

• Intent-bearing documents: README and documentation indexes, architecture and product overviews, domain glossaries, onboarding guides, runbooks, feature specifications, acceptance criteria, ADRs, RFCs, design proposals, migrations, roadmaps, incident reviews, release notes, traces, and handoff material.
• Discoverability paths: the human and agent start points, links from those starts to product context, decisions, specifications, examples, and behavior checks, plus orphaned, broken, stale, or misleading routes.
• Executable intent: contract tests, end-to-end flows, BDD features, golden files, API fixtures, examples, regression cases, protocol tests, migration checks, and validation rules tied to an outcome or recorded decision.
• Bounded rationale: roughly 10-20 recent or directly linked high-signal issues and review requests when authorized provider metadata is available, chosen for decisions, tradeoffs, acceptance signals, and reasons behavior changed.
• Agent-facing context: repository guidance, agent instructions, skills, prompts, commands, and tool registries only where they carry or link goals, constraints, domain rules, rationale, intended behavior, or safe-change boundaries.

A test matters here only when it expresses intended behavior. A high coverage percentage does not establish why a rule exists, while a small contract test linked to an ADR can be strong evidence. The Test quality audit owns adequacy, coverage, and flakiness. Cognitive debt uses executable artifacts only to connect observable behavior to the intent the repository claims.

External product systems are optional positive evidence, and Guard follows them only when the task or repository names them directly. A repository-side link can still be useful when its body is closed if it identifies the authority, owner, access expectation, and a short description of what belongs there. Guard does not search arbitrary sites, bypass authentication, ask for credentials, or infer the contents of a page it could not read.

What the audit deliberately does not claim

Cognitive debt is an analysis-only audit. It does not install dependencies, run package manager commands, execute project scripts, build or test the code, start applications, run migrations or seeds, contact production, deploy, scan the repository broadly, or browse unrelated websites. It creates no issue, comment, account, branch, commit, pull request, tag, release, fix, or external-system edit.

The score does not measure code cleanliness, documentation volume, or AI-tool sophistication. Code smells and broad maintainability belong to Codebase hygiene; dependency freshness and install paths belong to Dependency hygiene; secrets and exploitability belong to Security; coverage and test quality belong to Test quality; and pipeline enforcement belongs to CI/CD. Those surfaces enter this audit only when they carry or contradict intent. A release constraint in a workflow can be relevant; a generic judgment about the pipeline cannot.

An inaccessible external system is not evidence of missing intent or contradiction. It limits what can be compared. A weak, stale, or absent repository bridge is an accessible gap and may lower a dimension; the unreadable body itself does not. Guard also does not make product or architecture decisions, prescribe a broad documentation rewrite, or authorize migration of a team's external knowledge system.

Some failures prevent a result altogether. If the target is ambiguous, access or clone fails, the full audited revision cannot be established, or required inventory and analysis evidence is missing, Guard produces a diagnostic instead of a typed report. It does not turn an unsuccessful audit into a synthetic zero or a reassuring N/A score. By contrast, one legitimately unscored dimension still permits a bounded result over the dimensions that could be judged.

How the three-stage audit works

1. Establish the revision and inventory intent evidence

   Guard proves access, fixes the full commit, records capabilities and repository shape, then maps intent artifacts, entry paths, executable intent, bounded provider rationale, agent guidance, and directly linked external authorities. It does not fetch an earlier Cognitive debt result during this pass.

2. Evaluate the current revision independently

   The current inventory and repository evidence support five dimension scores, findings, confidence, any evidence-backed cap, and bounded improvement candidates. Project scripts and scanners are not run to manufacture evidence. An old score is still unavailable, so it cannot pull a weak current judgment toward a familiar number.

3. Draft the current result, then compare when possible

   Guard completes the direct answer, scorecard, calculation, confidence, findings, limitations, and checklist before locating a prior result. It then validates the exact previous report and summary references and reconciles only the files it could read. No usable prior leaves the current result unchanged and makes it the new baseline.

Root repository guidance is read independently as optional, untrusted evidence. It can explain a current convention or point to a product source, but it cannot expand access, force a command or score, suppress a finding, weaken verification, or change the output language. Missing or unusable guidance is neutral. If guidance changes between comparable runs, the report explains the substantive change in ordinary language rather than treating file mechanics as a cause by themselves.

The current-first order protects the comparison. A previous score is an anchor for checking consistency, not truth. Repository changes, corrected evidence, material changes in scope or limitations, changed applicable guidance, and scoring-method changes can justify movement. Cosmetic wording or unrelated code cannot.

How evidence becomes findings and confidence

Evidence is interpreted by state, not by file count. An accessible gap means a required answer is missing, stale, implicit, or hard to reach in evidence Guard could inspect. An accessible contradiction means two readable layers materially disagree. An unreadable external authority creates a coverage limit, while a clear repository-side bridge to that authority is positive evidence about discoverability even though the closed body cannot be judged.

Findings describe concrete problems such as missing or stale intent, an implicit constraint, weak executable proof, brittle agent context, concentrated knowledge, or drift between behavior and intent. An external-context limitation remains informational unless accessible evidence reveals a repository-side defect. Every dimension scored from 0 through 6 needs at least one finding that explains the score. A dimension from 7 through 10 still needs a concise positive reason tied to actual evidence.

Impact can be High, Medium, Low, or Info; confidence can be high, medium, or low. Only non-informational findings with high or medium confidence affect dimension judgments or establish a cap. There is no second subtraction step. Confidence reflects code access, history depth, default-branch and provider metadata, evidence freshness and quality, repository size, and optional external coverage.

High confidence means the relevant repository and supporting sources were sufficiently available and consistent for a firm judgment. Medium confidence means the conclusion is useful but bounded by a material coverage or freshness limitation. Low confidence means the accessible view is narrow enough that the report must lead with that fact. If fewer than three dimensions are scoreable, overall confidence must be low and the score must be described as covering accessible evidence only, even though renormalization can still produce a number.

A finding and an improvement candidate serve different jobs. The finding records the observed gap. A candidate is admitted only when evidence supports a bounded repository-side action, a next step, and a verifiable acceptance signal. Information-only and low-confidence findings stay out of the executable queue. If no safe bounded action can be inferred, the finding remains report-only; an empty candidate list is valid.

The five dimensions behind the score

Each dimension receives an integer from 0 through 10 when accessible evidence supports a fair judgment. Scores of 9-10 are explicit, current, executable, and aligned; 7-8 are strong with manageable gaps; 4-6 are partial with important gaps; 2-3 are weak, scattered, implicit, or stale; and 0-1 are absent or materially contradictory. The checklist then maps 7-10 to pass, 4-6 to warn, and 0-3 to fail.

1. 1

   Goals and constraints 25%

   This dimension asks whether purpose, important constraints, domain rules, major-decision rationale, and their entry paths are explicit, current, and reachable. A strong result lets a reader move from the repository entry point to the rules that shape the system. A partial result means the intent exists but is scattered or implicit. A weak result means accessible evidence is absent, materially incomplete, or contradictory.

2. 2

   Proven behavior 20%

   Contracts, specifications, examples, behavior-linked tests, fixtures, and regression cases count when they prove a product outcome, protocol, user journey, or domain rule. A strong result covers important intended behavior with executable evidence. A partial result leaves meaningful paths in prose or code alone. A weak result leaves critical behavior with little proof. This is not a test-coverage score.

3. 3

   Knowledge recovery 20%

   Guard follows the route a newcomer or coding agent would take to build a useful mental model. Clear starts, working links, domain terms, decision rationale, and bounded history make recovery manageable. Searching through disconnected files or provider discussions earns a partial result. Dependence on hidden knowledge, one person, or inaccessible unrecorded decisions is weak evidence.

4. 4

   Agent context 10%

   Agent-facing guidance earns credit when it carries or links product intent, domain constraints, and safe-change boundaries. Commands and setup mechanics can be useful, but they do not explain what must remain true. A file with some intent but weak links is partial; command-only or misleading guidance is weak. The dimension does not grade model choice, prompt style, or AI-tool maturity.

5. 5

   Evidence alignment 25%

   Accessible documentation, specifications, examples, behavior-linked tests, provider rationale, and observable repository behavior should tell the same story. Minor or localized mismatches are partial evidence; material contradictions are weak. This dimension can be Not scored only when an explicit inaccessible authority is known to hold the missing comparison and accessible repository evidence cannot support a fair judgment.

The weights reflect the audit's question: goals and alignment each carry 25 percent, proven behavior and knowledge recovery each carry 20 percent, and agent context carries 10 percent. Confidence remains a report judgment rather than a sixth dimension. A closed authority may make one dimension Not scored, but weak accessible documentation must still receive the low or partial numeric score its evidence supports.

How the Cognitive debt score is calculated and capped

With all five dimensions scored, Guard multiplies each 0-10 value by its weight, adds the weighted terms, converts the result to 0-100, and rounds to the nearest integer.

score = round((
  0.25 × Goals and constraints
  + 0.20 × Proven behavior
  + 0.20 × Knowledge recovery
  + 0.10 × Agent context
  + 0.25 × Evidence alignment
) × 10)

A dimension is excluded only under the external-only rule: an explicit task or repository source proves that a relevant answer belongs to an inaccessible authority, and accessible repository evidence is insufficient for a fair score. Guard removes both that value and its weight, then renormalizes the scored terms. A missing, thin, stale, or contradictory accessible answer remains scoreable and cannot use Not scored as shelter.

score before caps = round(
  (scored weighted sum / scored weight total) × 10
)

Findings explain the dimension judgments and can establish a cap, but they do not subtract another set of points. Evidence-backed caps are applied after weighting, and the lowest applicable maximum wins. A cap never raises a score that is already lower.

• The maximum is 39 when accessible executable evidence or documentation contradicts critical product constraints.
• The maximum is 49 when accessible repository artifacts are expected to carry purpose or behavior but are empty, contradictory, or misleading, with no known inaccessible authority owning the missing context.
• The maximum is 69 when main goals are mostly implicit and accessible evidence suggests dependence on one person or unrecorded decisions. Unreadable external context alone cannot trigger it.
• The maximum is 74 when executable intent is very weak for documented critical behavior.
• The maximum is 79 when issue, review, or history access is unavailable and current repository documentation is too thin to establish rationale.

Scores from 70 through 100 have good severity, 40 through 69 are warning results, and 0 through 39 are bad. These product bands do not replace the dimension states. The fictional score below is 59 and therefore warning/yellow, while its failing Agent context dimension still drives the metric card's reconciled outer state to red.

A worked example: 59 out of 100

The fictional repository has Goals and constraints 6, Proven behavior 8, Knowledge recovery 5, and Agent context 3. Evidence alignment is legitimately Not scored because a clearly identified product authority owns the acceptance rationale, that authority is inaccessible, and the repository alone cannot support a fair comparison.

No cap applies. Accessible evidence does not contradict a critical constraint; the repository's purpose and primary behavior evidence are partial rather than empty or misleading; goals are not mostly implicit or dependent on one person; the documented critical flow has strong executable proof; and provider history plus issue and review evidence are available. The inaccessible authority changes coverage and medium confidence, not the cap.

The previous fictional run scored 53 at a validated earlier revision. The current six-point increase follows clearer goals and constraints plus stronger primary contract evidence. The older 43-to-53 movement follows a product-context index, a structured external bridge, a contract specification for the primary flow, a corrected onboarding link, and a product boundary in agent guidance. Those relations belong to the reports, not the chart alone. Another manual run becomes available only after repository changes; it audits and archives the new revision instead of rewriting this result.

How to read the result in Guard

The repository card is an orientation surface. Its score ring and badge use the final score bands, so 59 appears yellow with Some issues. The card border reconciles the worst visible checklist signal; Agent context at 3 is a fail, so the fictional card's outer state is red. Those two signals answer different questions and are not contradictory.

The four card counts summarize the five dimension states: one Problem, two Watch, one Healthy, and one Skipped. They are not counts of report findings. Skipped means Guard inspected the audit scope but deliberately did not grade Evidence alignment under the external-only rule. It marks lost coverage, not an audit that never ran and not five free points.

Audit details opens the evidence behind the card. The detailed view carries the audit-specific score label Intent is partial, while the dashboard uses the score-tone badge Some issues. The current report appears first under Reports with its score, Current badge, target revision, direct answer, confidence, five-row scorecard, calculation, findings, evidence, limitations, and improvement checklist. Copy and Download preserve the Markdown report for handoff.

Completed earlier reports remain archived below the current one. The history chart plots completed scores on a 0-100 scale and can open a past report, but the line cannot prove why the number moved. A supported explanation comes from the relation between the exact revisions and evidence in those reports. A historical run is read-only.

The dashboard action is Rerun; the detailed management action isRerun audit. After a successful run has already checked the current repository version, manual Rerun is disabled until new changes exist. Automatic runs also wait for a changed commit. Cognitive debt currently has no paired Autofix action, so Guard shows no Autofix button, Autofix report, or finding-level Improvement steps panel for this audit.

Where the audit ends and human-approved improvement begins

A useful finding can suggest a small intent artifact, executable specification, decision record, alignment correction, agent-context improvement, external-context bridge, or onboarding route. Those categories describe bounded work, not a command to rewrite every document. The fictional report, for example, can propose two concise decision records and a product-overview link with two named safe-change constraints in agent guidance.

A candidate is complete only when it retains the observed evidence, a bounded next action, and a verifiable acceptance signal. An affected area is named only when evidence supports one; Guard does not invent a target to make the queue look complete. Information-only and low-confidence findings remain in the report, and a finding with no safe bounded action stays report-only. A run with no candidates is valid.

1. Observe the gap. The report preserves the exact revision, evidence, impact, confidence, and limitation behind the finding.
2. Bound a possible action. The candidate names the smallest supported repository-side change and what would demonstrate completion.
3. Revalidate and decide. A future consumer checks the current target and revision again; a person approves any repository edit or external product decision.
4. Audit the changed revision. A later run evaluates whether recoverability improved without assuming the candidate caused a higher score.

Candidate context is not write permission and does not prove the recommendation still applies after the repository changes. Choosing a product constraint, recording sensitive external rationale, or changing behavior requires owner judgment. Since no paired Cognitive debt improvement action is published today, these candidates remain human-reviewed report guidance rather than an Autofix control or promised pull request.

Limits, reruns, and maintained intent

The result describes accessible evidence at one exact commit. It cannot prove what people remember, exhaustively recover every historical decision, or inspect a private product authority that current access cannot read. Provider evidence is deliberately sampled, not excavated without limit. Shallow history, disabled issues, unavailable review requests, rate limits, repository size, stale links, and inaccessible external context lower confidence or become explicit limitations rather than hidden assumptions.

Missing prior data is a normal baseline. Guard keeps the independently drafted current score and findings, omits the previous value and relation section, and says that the run will anchor the next comparison. If only one prior file is usable, the report compares only what that file supports and discloses the missing counterpart. A previous score appears in the current summary only when the validated previous summary itself was read.

When a usable comparison exists, movement must have a source-backed cause: a substantive repository change, corrected prior evidence, a material change in scope or accessible evidence, a relevant repository-guidance change, or a scoring-method change. Cosmetic prose churn and unrelated code do not justify a new interpretation. The chart can display 43, 53, and 59; the report must explain which revised artifacts support each relation.

Rerun evaluates a new exact revision and archives a new report. It may rise when decisions, constraints, examples, or entry paths become clearer; stay flat when the relevant evidence is unchanged; or fall when a feature outruns the records that explain it. An archived report is never rewritten to make the history smoother. Current UI prevents another manual run on the same already-checked repository version and enables it after new changes.

Maintained intent is the practical outcome. Product goals, architecture, domain rules, agent boundaries, and executable examples all drift as teams ship. Recurring audits make the recoverability gap visible; people choose the smallest supported corrections; the next revision is judged again. Coding agents can then build new features on a codebase whose purpose and constraints remain discoverable instead of layering more behavior on top of old guesses.