# ADR-0003: Localization is 10 mandatory questions; defaults inform but never skip

- **Date:** 2026-04-28
- **Status:** superseded by ADR-0004 (2026-05-01)
- **Reversibility:** medium (count and mandatory-ness can be tuned in V1.x based on landing telemetry; structural change to the question shape is a breaking change for the deploy skill)
- **Deciders:** practitioner@example.com (operator)
- **Scope:** kit (V1 localization protocol)
- **Superseded by:** ADR-0004 (recursive question discipline; the V1 fixed-10 framing was the right discipline at the wrong altitude; the V1.1 framing carries the discipline forward as recursive base set + follow-ups + rescaffold-mode patterns)

## Context

The kit's polymorphic architecture (locked in ADR-0001) requires a localization mechanism: a way for each deployment to capture environment-specific answers that drive template population, ADR stub generation, and validation rubric scoping.

The localization question count and the defaults policy are real design choices with multiple options:

- **Question count:** few (3 to 5), balanced (5 to 10), thorough (10 to 15), or interview (15+)
- **Defaults policy:** defaults-as-skip-shortcuts (operator can skip a question and the kit fills with default), defaults-as-suggestions (defaults are visible but operator must explicitly accept), or no-defaults (every question must be answered from scratch)

Operator constraint locked 2026-04-28: "10 is fine. the questions must be answered though, the previous kits were very lax about this."

The "lax" reference is to prior kit attempts where operators waved past questions, the kit guessed, and the deployed instance landed weak. Two failure modes followed: the instance treated guessed values as locked decisions and the operator relitigated them session-by-session; or the instance flagged everything as "TBD," producing a stubbed landing that looked deployed but operated like none. Both are forms of overclaimed completeness from `BOOTSTRAP-BRIEF.md` Section XI.

## Decision

The kit ships 10 localization questions, every one mandatory. Defaults are sensible-shape suggestions that the operator must explicitly accept; defaults are never silent skip-shortcuts. Honest unknowns are captured as `unknown - {reason}` and the corresponding layer lands as **none** with the unknown surfaced in the audit; honest unknowns are acceptable, silent skips are not.

## Options considered

### Option A: 10 mandatory, defaults as suggestions [CHOSEN]

- **Summary:** 10 questions; each has acceptance criteria; defaults are visible but require explicit accept; honest unknowns allowed but flagged; the deploy skill enforces the gate.
- **Pros:** Eliminates the "lax" failure mode by structural enforcement, not operator discipline; enough surface area to populate eight layers, the relationship topology, and ADR scope; honest unknowns are first-class and surface in the audit so they get scheduled rather than ignored.
- **Cons:** ~10 to 20 minutes of operator interview at landing; cannot land instantly; some questions will feel premature for early-stage deployments where the answer is genuinely "we have not decided."

### Option B: 5 to 7 mandatory, defaults-as-skip-shortcuts

- **Summary:** Smaller question set; defaults fire automatically on skip; faster landing.
- **Pros:** Lands in 3 to 5 minutes; lower friction; suits exploratory deployments.
- **Cons:** Recreates the prior failure mode the operator named; the defaults that fire on skip become locked decisions the operator did not consciously approve; relitigation follows; this is the option being explicitly rejected.

### Option C: 15+ thorough interview

- **Summary:** Larger question set covering every layer in detail; landing becomes a structured interview.
- **Pros:** Captures more nuance; reduces post-landing surprises.
- **Cons:** Operator fatigue; landing takes 30 to 60 minutes; many questions yield "we do not know yet" answers that 10 questions also produce; the marginal question rarely changes the landing's shape.

## Rationale

Option B is the named failure mode; rejection is mechanical. Option C inflates the friction without proportional landing-quality gain; the operator's experience is that questions 11+ produce "we do not know" at the same rate as questions 8 to 10, so the marginal question yields little.

Option A balances coverage and friction. Ten questions is enough surface to populate L0 through L7 and the cross-cutting concerns; mandatory-ness defeats the laxness failure mode; defaults-as-suggestions preserves the speed advantage of having defaults without converting them into silent skips.

The tradeoff explicitly accepted: 10 to 20 minutes of operator interview at landing time. Mitigation: the deploy skill writes the captured answers to `LOCALIZATION-ANSWERS.md` so future sessions inherit them without re-asking; revisions trigger a new ADR rather than re-running the entire interview.

## Consequences

### Positive

- Defeats the "lax landing" failure mode by structural enforcement
- Captured-answers artifact (`LOCALIZATION-ANSWERS.md`) becomes the single source of truth for the deployed instance's localized values
- Honest unknowns become first-class: surfaced in the audit, scheduled in the backlog, not silently filled
- The deploy skill's behavior around the gate is unambiguous: 10 captured answers or no landing

### Negative

- 10 to 20 minute operator interview at every fresh deployment
- Deployments under exploratory pressure cannot land in seconds; the kit will not optimize for that case
- Question revisions force a supersession event (new ADR or LOCALIZATION-ANSWERS.md revision) rather than silent edits

### Followups

- Chunk D's `skills/deploy/SKILL.md` enforces the gate: 10 captured answers before any template population happens
- Chunk E's `skills/validate/SKILL.md` cross-checks `LOCALIZATION-ANSWERS.md` for completeness as part of the audit; flags any layer landing that traces back to an unknown answer
- After 3 deployments, review whether any question consistently produces "unknown - same reason"; if so, that question may need redesign or splitting (track in `BACKLOG.md`)
- If V2's recursive engine eventually ships, this question set becomes the engine's environment-profile schema (named in `BACKLOG.md` Recursive Engine entry)
