Finding Unknowns

Finding Unknowns

Overview

The request is a map; the codebase and real-world constraints are the territory. Every gap between them gets filled with a guess — cheap to surface before implementation, expensive to discover after delivery.

Core principle: spend minutes surfacing unknowns before spending hours building on them.

The Four Quadrants

| Quadrant | What it is | How to eliminate | |---|---|---| | Known knowns | Stated in the request | Already on the map | | Known unknowns | Questions noticed but unanswered | Interview: ask, one at a time | | Unknown knowns | Obvious to the requester, never stated — house templates, client standards, contract formats | Prototype/mockup (seeing it exposes the standard); ask for a reference example | | Unknown unknowns | Questions nobody thought to ask | Blind spot pass |

The Rule

Before writing any plan or implementation code, your FIRST output is an Unknowns Inventory:

## Unknowns Inventory
- [known unknown]  → resolve by: ask / reference / conservative default (logged)
- [unknown known]  → resolve by: mockup / example / ask
- [blind spot]  → resolve by: blind spot pass

Every item gets a resolution route: ask the user, request a reference, build a cheap prototype/mockup, or — only when the user is unreachable — take the conservative default and log it as a deviation.

An unreachable user makes the inventory MORE important, not less: it decides which defaults are safe and becomes the assumption log delivered with the work.

Scale the inventory to the ambiguity, not the ritual. When the request names its exact targets and leaves no format, convention, or scope choice open (a rename, a typo fix, a version bump), the whole inventory is one verification action — confirm the stated scope (e.g. a repo-wide grep), then do the work. The printed block earns its length only when items genuinely route to different resolutions.

Phase Routing

| You are... | Read | |---|---| | Starting a task (no code written yet) | [references/pre-implementation.md](references/pre-implementation.md) | | Mid-implementation, plan didn't cover this case | [references/during-implementation.md](references/during-implementation.md) | | Done, preparing handoff / review / sign-off | [references/post-implementation.md](references/post-implementation.md) |

From Inventory to Plan

The inventory is not a report — it drives what happens next:

• It is the question list for whatever design discussion follows; work through it with the user before committing to a direction.
• When the plan gets written, resolved items feed it as requirements; unresolved items enter it as documented assumptions, never as silent guesses.

Rationalizations

| Excuse | Reality | |---|---| | "User is offline and the deadline is now" | The inventory takes two minutes and changes what you build. Do it, pick conservative defaults, log every one. | | "Waiting for clarification costs more than delivering on assumptions" | Unlogged assumptions cost the most — the user finds them after delivery. Speed and surfacing unknowns are not in conflict. | | "The request is clear enough" | Clear requests still hide the requester's unstated standards. One mockup exposes them. | | "I'll list my assumptions at the end" | By then the work is already shaped by them. Surface them first. | | "Asking questions looks incompetent" | Shipping the wrong thing looks worse. |

Red Flags — STOP and build the inventory

• About to write code for a one-sentence task description
• Choosing a format, library, or convention the user never mentioned
• Thinking "they probably want..."
• A client-facing or sign-off deliverable with no example of what the recipient expects
• Three unstated decisions made in a row

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SanQianQVQ
• Source: SanQianQVQ/Finding-unknowns
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.