Finding Unknowns Before Agentic Work

Strong coding agents can cover more ground than you expect.

That is useful, but it also means weak task framing becomes more expensive. If the agent runs into decisions you never specified, it will either guess, stop, or solve a slightly different problem.

The goal is not to describe every step. The goal is to discover the decisions that would change the work.

Map And Territory

Your prompt is the map. The actual codebase, users, dependencies, production constraints, and edge cases are the territory.

Agent failures often happen where the map and territory disagree.

flowchart LR
    A["Prompt / plan<br/>what you think is true"] --> C{"Agent runs into<br/>a decision point"}
    B["Codebase / reality<br/>what is actually true"] --> C
    C --> D["Clarify"]
    C --> E["Log decision"]
    C --> F["Verify against evidence"]

Before asking an agent to implement a meaningful change, spend a few minutes finding the unknowns.

Unknowns Matrix

Type	Meaning	How to handle it
Known knowns	Facts you already know and can state	Put these in the prompt
Known unknowns	Questions you already know are unresolved	Ask the agent to investigate first
Unknown knowns	Assumptions you would recognize only when shown	Use prototypes, examples, and review checkpoints
Unknown unknowns	Risks you have not considered yet	Ask for a blind-spot pass

The last two are where agents are useful before implementation. They can inspect the repo, search history, compare patterns, and surface things you would not have written down.

Use a blind-spot pass when the work touches unfamiliar code, a new domain, or a messy integration.

I want to add a new auth provider in this repo.
Do not edit files yet.

First, do a blind-spot pass:
- inspect the relevant auth, session, config, and test paths
- identify unknowns that could change the implementation
- list assumptions I appear to be making
- point to files or commands that support each finding
- recommend what I should clarify before implementation

This is different from a plan. A plan answers “what should we do?” A blind-spot pass answers “what do we not understand yet?”

Interview The User

When the task has product, architecture, or workflow ambiguity, ask the agent to interview you.

Interview me before proposing an implementation.
Ask only questions that could change architecture, data model, security posture, or user-visible behavior.
Group small questions together and stop after the highest-impact ones.

Good interview questions are not trivia. They change the shape of the work.

Weak question	Better question
What color should the button be?	Is this flow optimized for first-time setup or repeated daily use?
Should I add tests?	Which behavior would be most damaging if it regressed?
Do you want this refactored?	Is compatibility with existing saved data required?

Prototype To Reveal Preferences

Some requirements are hard to write down.

For UI, reporting, copy, dashboards, and workflow design, ask for a few sharply different prototypes before committing to one direction.

Make three rough alternatives before implementation.
Each should make a different tradeoff.
Use static HTML or markdown if that is enough.
Do not wire production code yet.
Explain which unknown each prototype is testing.

The point is to make hidden preferences visible. Once you can react to a concrete artifact, the real requirement becomes clearer.

Give References

References are a fast way to give the agent a better map.

Useful references include:

an existing implementation in another repo
a previous migration
a screenshot or HTML mockup
an API response example
a ticket thread
a production log
a style guide
a failing test

Do not only say “build it like X.” Tell the agent which parts of X matter.

Use `billing/stripe-webhooks.ts` as the reference pattern.
Copy the validation and idempotency approach.
Do not copy the old logging style or broad catch-all error handling.

Keep Implementation Notes

For larger tasks, ask the agent to maintain short implementation notes while it works.

Implementation notes should capture:

decisions made when the prompt was ambiguous
assumptions that were verified
assumptions that remain unverified
deviations from the original plan
files that were riskier than expected
verification evidence

This keeps the human in the loop without forcing the agent to stop after every small decision.

Backbrief Before Merge

Before merging or publishing, make the agent explain the work back to you.

Before finalizing, give me a backbrief:
- what changed
- what assumptions you made
- what you verified
- what remains risky
- what I should review manually

For important work, add a quiz:

Ask me five review questions that would reveal whether I understand the change well enough to own it.

This is useful because agentic work can move faster than your own mental model. The backbrief closes that gap.

Practical Workflow

Ask for a blind-spot pass.
Clarify the highest-impact unknowns.
Provide references or ask for prototypes where requirements are fuzzy.
Approve a scoped plan.
Let the agent implement.
Require implementation notes and verification evidence.
Review the backbrief before merge or publish.

Key Takeaways

Stronger agents make unknowns more important, not less important.
Ask the agent to discover uncertainty before asking it to act.
Use prototypes for requirements you cannot describe cleanly.
Use references to transfer intent without writing a huge prompt.
Keep implementation notes so decisions do not disappear inside a long run.