ADR-0004 — Resolve ambiguity by asking, never by guessing

• Status: Approved
• Date: 2026-10-31
• Deciders: P@puncoz
• Approved by: P@puncoz
• Approved on: 2026-11-01
• Supersedes: —
• Superseded by: —
• Design documents: AGENTS.md §4

ContextCopy Anchor Link

The cheapest failure for an agent is to pick something plausible and move on. The assumption looks finished, gives no signal it was made, and is found late. On a documentation site the damage is public: a plausible guess about an install command, a function signature, a default option or a supported runtime is published as fact and copied into other people's code. A guess about whether a project is private publishes it.

The owner prefers to be questioned with selectable options, not open-ended prompts.

DecisionCopy Anchor Link

1. Classify the question first.
   • Verifiable (framework API, library behaviour, existing code, config, what a documented package exports or requires): check it in node_modules/next/dist/docs/, the installed Fumadocs source and types, the config, or the documented package's own source and manifest. Don't assert from memory and don't ask the owner.
   • Undetermined (product behaviour, scope, priority, naming, content structure, public versus private, trade-offs): ask.
2. Every question carries the decision in one line and why it can't be settled from the code or documents; two to four concrete options with their consequences; a recommendation listed first and marked; and what each option builds, costs and forecloses. Use a selectable options tool where available.
3. No silent assumptions. Work that proceeds on an assumption states it in the response and in the ADR or design document it shapes.
4. Ask at ADR time, in Options considered. Mid-implementation: finish what doesn't depend on the answer, then ask.

Options consideredCopy Anchor Link

ConsequencesCopy Anchor Link

Positive

• Content, structure and privacy decisions stay with the owner and are written down.
• Published facts about packages are read from their source, not recalled.

Negative / accepted trade-offs

• More questions at ADR time. Accepted: that is the cheapest moment for them.

Content invariantsCopy Anchor Link

Protects all of AGENTS.md §6 by routing any ambiguity about them to the owner; directly enforces §6.2 (documentation is checked against the code).

Security considerationsCopy Anchor Link

Security, privacy and visibility questions are always undetermined and always asked (ADR-0005).

Implementation notesCopy Anchor Link

• AGENTS.md §4 states the rule.
• Tests: not applicable (process only).

Docs to update on implementationCopy Anchor Link

• content/docs/maintain/adr/index.mdx — status.