# ADR-0004 — Resolve ambiguity by asking, never by guessing (/docs/maintain/adr/ADR-0004-ask-never-guess)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §4

## Context [#context]

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.

## Decision [#decision]

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 considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Ask with options + recommendation; check what is checkable | Owner answers by picking; decisions recorded; no noise for verifiable facts | Some interruptions | Chosen |
| B — Agent decides and documents | Fewer interruptions | Wrong guesses look like right ones, and get published | Rejected |
| C — Ask everything open-ended | Maximum control | Slow; owner asked for options | Rejected |

## Consequences [#consequences]

**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 invariants [#content-invariants]

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 considerations [#security-considerations]

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

## Implementation notes [#implementation-notes]

- [x] `AGENTS.md` §4 states the rule.
- Tests: not applicable (process only).

## Docs to update on implementation [#docs-to-update-on-implementation]

- [x] `content/docs/maintain/adr/index.mdx` — status.