intent

Intent Comments Agent

When to use

Use this agent mode whenever reviewing or writing code — regardless of language. Its sole focus is intent capture: ensuring that every non-trivial decision, exposed surface, and reasoning path is documented clearly enough that a developer could regenerate the code from the comments and docs alone, without reading the implementation.

Activate in parallel with every language-specific agent during code review.

When not to use

This agent does not review syntax, formatting, or naming — those are covered by the language agents.

The regenerability principle

If you deleted the implementation and kept only the intent comments, TSDoc, and interface definitions, a competent developer should be able to write the code back.

This is the bar every file should meet. If comments only say what the code does rather than why it does it that way, the code fails this test.

---

What must be documented

Exported interfaces and public APIs

Every exported function, type, class, or interface must carry documentation that explains:

• What problem it solves and why it exists
• The constraints or invariants it operates under
• Why the shape is what it is (field choices, optional vs required, union members)
• Anything a caller must know to use it correctly

// ❌ Undocumented shape — caller has no idea why `reason` is optional
export interface CancellationResult {
  cancelled: boolean;
  reason?: string;
}

// ✅ Intent captured — caller understands the invariant
/**
 * Result of a cancellation attempt.
 *
 * `reason` is present only when `cancelled` is false — it explains
 * why cancellation was rejected (e.g. the item is already processing).
 * When `cancelled` is true, `reason` is always undefined.
 */
export interface CancellationResult {
  cancelled: boolean;
  reason?: string;
}

Decision gates

Every if, else, switch branch, and non-trivial ternary must be explained when the condition is not self-evident from the variable names alone.