comprehension-check

Comprehension Check

Overview

AI produces code at a pace that outstrips human absorption. Shipping changes you cannot fully explain creates cognitive debt -- the inability to troubleshoot, extend, or reason about what was built.

Core principle: Comprehension precedes commitment. If you cannot articulate every modification in ordinary language, you have not earned the right to commit it.

The Prime Directive

NO COMMIT UNTIL EVERY CHANGE IS UNDERSTOOD

Before any AI-generated or AI-assisted code reaches version control, the developer must grasp what each change accomplishes and why it was implemented that way.

When to Use

Triggered after:

• Any modification touching 3 or more files
• Non-trivial algorithm or data-structure implementations
• Structural shifts (new modules, altered data flow, dependency rewiring)
• Security-adjacent code (authentication, encryption, input sanitization)
• Autonomous agent decisions (changes you did not explicitly dictate)

Skippable for:

• Single-character or typo corrections
• Changes the developer dictated verbatim, line by line
• Pure boilerplate generation (scaffolding configs, lockfiles)

The Process

Phase 1: Produce a Change Walkthrough

After implementation completes, before any commit occurs:

For EVERY modified file, articulate:

1. WHAT: What is different now? (Describe the meaning, not the diff)
2. WHY: What motivated this particular change?
3. CONTEXT: How does this change interact with the broader modification set?
4. HAZARD: What failure modes does this change introduce?

Phase 2: Deliver the Walkthrough

Structure the output as follows:

## Modification Walkthrough

### [path/to/first-file]
**What:** Introduced sliding-window rate limiting that counts requests per IP address.
**Why:** The login endpoint was exposed to brute-force enumeration.
**Context:** Middleware executes ahead of authentication routes; relies on Redis for distributed state.
**Hazard:** If Redis becomes unreachable, the limiter fails open (permits all traffic). Worth discussing: should it fail closed instead?

### [path/to/second-file]
**What:** Login handler now returns HTTP 429 when the rate limiter activates.
**Why:** The middleware flags rate-limited requests via `req.rateLimited`.
**Context:** Early exit occurs before password verification, which also blocks timing-based attacks.
**Hazard:** Negligible -- a simple conditional guard.

## Structural Consequences
- New runtime dependency: Redis (stores rate-limit counters)
- New middleware layer inserted between routing and handler execution
- Login request lifecycle now: rate-check -> authenticate -> respond

## Open Questions
1. Should the rate limiter deny all traffic when Redis is unavailable, or allow it?
2. Should rate limiting extend beyond authentication endpoints?

Phase 3: Obtain Explicit Confirmation

Ask directly: "Do you fully understand these changes and want to proceed with the commit?"

When the developer raises questions:

• Resolve them thoroughly
• Do not gloss over confusion
• Lingering confusion equals accruing cognitive debt

Phase 4: Surface Unsolicited Changes

Whenever a change was not part of the original request:

HEADS UP: I additionally [modified X] because [rationale].
This was NOT part of your original instruction. Keep it or revert?

AI agents frequently make "helpful" supplementary changes. Every one must be disclosed.

Indicators of Genuine Comprehension

The developer should be able to:

• Describe what each altered file does differently now
• Justify why each alteration was necessary
• Predict what would break if a specific change were rolled back
• Enumerate any new dependencies or patterns that were introduced
• Identify where to investigate if a bug surfaces in this code later

Cognitive Traps

Rationalization	Truth
"The test suite passes, so I trust it"	Tests validate behavior, not understanding. You will debug this blind later.
"I will review it when things calm down"	You will not. The context window closes the moment you move on.
"It is mostly boilerplate"	A single incorrect line in boilerplate can open a security hole.
"I grasp the overall concept"	High-level intuition collapses at debugging time. Specific comprehension is required.
"Deep review reduces my velocity"	Deploying code you cannot explain reduces velocity far more when it fails.
"The AI is competent"	AI generates plausible output. Plausible and correct are not the same thing.

Guardrails

Prohibited actions:

• Committing AI-produced code without reading the walkthrough
• Suppressing unsolicited-change disclosures
• Rushing past developer confusion or uncertainty
• Equating green tests with genuine comprehension

Required actions:

• Generate walkthroughs for all multi-file modifications
• Disclose every change that exceeded the original request
• Collect explicit confirmation before committing
• Fully resolve every developer question

Integration

Invoked after:

• godmode:delegated-execution -- Review output from delegated agent implementations
• godmode:test-first -- After code is written and tests pass
• godmode:parallel-execution -- After merging results from parallel agent work

Invoked before:

• godmode:completion-gate -- First understand, then verify
• godmode:merge-protocol -- Understand before merging into the target branch