Discovery and the Four Quadrants

Discovery and the Four Quadrants

The agent's context is a map; the repository, its pipeline, and the team's unwritten preferences are the territory. When the map has a gap, an agent doesn't stop — it fills the gap with an industry-average assumption and produces coherent, confidently wrong work. The cost of a wrong assumption grows with how late it's found. Discovery closes the gaps before code is written.

Gaps come in four kinds, and each fails differently — so each gets a different move. Collapsing them all into "ask some clarifying questions" loses the method: you can't ask someone about a preference they've never seen, and you can't ask anyone about a constraint nobody knows exists.

The four quadrants

Quadrant	What it is	The move
Known knowns	Declared standards, APIs, explicit requirements	Prove the map loaded. Enumerate the constraints found, citing the files they came from. If you can't cite it, you assumed it.
Known unknowns	Identified but undecided items (database, schema, auth)	Toggle, don't decide silently. File a decision entry: 2–3 options, tradeoffs, a toggle the user flips, a decide-by point. Block dependent work until toggled.
Unknown knowns	Preferences the user holds but can't articulate until shown	Show, don't ask. Generate 3–4 concrete variants; the user selects elements across them; compile into a written preference spec. Asking questions here fails by construction.
Unknown unknowns	Undocumented constraints, hidden couplings, deprecated behaviors	Scan the territory and interview the human. Read the actual code (not docs about it); interview one question at a time, ordered by blast radius.

The moves in detail

Blindspot scan — for work touching unfamiliar or poorly documented subsystems. Read the real implementation of what the work touches (auth, routing, CI, deploy, migrations). Output is risk cards: the finding, why it bites this project, and a copyable context correction — the sentence that, added to context, would have prevented the wrong assumption. Accepted corrections land in CLAUDE.md (if always-on) or UNKNOWNS.md (if situational). Let the code decide how many cards there are — three real findings beat seven padded ones.

Spec interview — for ambiguous requirements. One question at a time (batched questions get shallow answers); blast-radius order (ask first what would most change the architecture — execution model, data ownership, external boundaries — last what's cosmetic); offer the tradeoffs with each question so the user decides on substance. Answers accumulate into DECISIONS.md (decided) and UNKNOWNS.md (parked with toggles). Stop when remaining questions wouldn't change the plan.

Variant comparison — for genuinely subjective choices (visual design, interaction feel, API ergonomics, CLI shape). Generate 3–4 concrete, distinct variants — real renderings or code sketches, not descriptions. The user reacts, selecting across variants ("layout from B, density from C"); selections compile into a written preference spec. For jargon-heavy domains, pair variants with a short vocabulary ladder so the user learns to articulate the preference.

Reference port map — for porting logic across languages or codebases. Lay matched source and target blocks side by side; flag every semantic divergence — memory model, error handling, numeric behavior, concurrency — before porting. Each flagged divergence becomes a decision entry or a test.

Deviation log — the in-flight discipline that makes phase audits possible. Every divergence from the plan gets a row at the moment it happens: planned → actual → why → tradeoff accepted → lesson. At the audit these rows are the retro's raw material. An empty deviation log after a long phase is itself a finding.

Change quiz & pitch doc (optional, post-implementation, only when human reviewers exist) — comprehension questions generated from the actual diff, and a review summary that pre-answers likely objections with evidence from the code.

Artifact rules

Markdown is the default medium — everything that lives in git and gets diffed. HTML only when the unknown is genuinely visual or comparative, and then it must be self-contained and embed an export mechanism that returns the user's selections as structured markdown/JSON — without export, the loop never closes back into context. Nothing speculative: generate an artifact when a real decision needs it, never pre-build a suite of tools.

Task inception protocol

Installed into the project's CLAUDE.md core rules. Before any non-trivial implementation task, state: victory conditions (the named commands/tests whose passing proves the task done), assumptions and confidence (if low, enumerate what's missing and ask — no file writes until answered), and the top 3 failure modes grounded in this repo's actual files. Scale by blast radius: full protocol for schema/API/infra; a stated victory condition alone for small changes; trivial tasks (single file, no interface change, no new dependency) skip the ceremony.

---

Canonical detail: references/discovery.md.