Surface Questions
Definition
Expose the questions everyone already knows are unresolved. This skill helps decide what must be answered now, investigated by the agent, safely assumed, or deferred.
Questions To Ask
- What decisions are still open?
- Which answer would change architecture, scope, UX, data model, debugging strategy, deployment, or implementation?
- What are you unsure about?
- What should I investigate in the codebase, docs, logs, or external references?
- What should I not assume?
- What would make this plan wrong?
Question Rules
- Prioritize questions where the answer changes the shape of the work.
- Ask user-facing questions when project inspection cannot reveal intent.
- Mark mechanical or discoverable questions as
Investigate.
- Mark reversible, low-risk gaps as
Assume for now with a revisit trigger.
- Mark nonblocking curiosity as
Defer.
Existing Project Comparison
- Compare open questions against existing project docs, tests, issues, logs, schemas, routes, and code patterns.
- Convert questions answered by the project into known knowns.
- Keep contradictory or ambiguous evidence in the
Ask now or Investigate buckets.
Suggestive Plan
- Review knowns and current phase target.
- List open questions.
- Classify each question by impact and owner.
- Ask the highest-leverage user question first.
- Update
UNKNOWNS.md.
Example
For a debugging task, ask whether preserving current behavior matters more than a quick fix, which user flow is failing, and whether logs or reproduction steps exist.
Vocabulary
- Known unknown: explicit unresolved question.
- High-leverage question: answer that changes direction or avoids wasted work.
- Investigation item: question Codex can answer by inspecting artifacts.
- Revisit trigger: event that makes an assumption worth checking again.
Expected Outcome
Produce a Known Unknowns section in UNKNOWNS.md with prioritized questions classified as Ask now, Investigate, Assume for now, or Defer.
1---2name: surface-questions3description: Ask question-first prompts to expose known unknowns before software work. Use for any domain when open decisions, ambiguities, missing requirements, uncertain architecture, debugging hypotheses, data choices, UX flows, or risky assumptions could change the next step.4---56# Surface Questions78## Definition910Expose the questions everyone already knows are unresolved. This skill helps decide what must be answered now, investigated by the agent, safely assumed, or deferred.1112## Questions To Ask1314- What decisions are still open?15- Which answer would change architecture, scope, UX, data model, debugging strategy, deployment, or implementation?16- What are you unsure about?17- What should I investigate in the codebase, docs, logs, or external references?18- What should I not assume?19- What would make this plan wrong?2021## Question Rules2223- Prioritize questions where the answer changes the shape of the work.24- Ask user-facing questions when project inspection cannot reveal intent.25- Mark mechanical or discoverable questions as `Investigate`.26- Mark reversible, low-risk gaps as `Assume for now` with a revisit trigger.27- Mark nonblocking curiosity as `Defer`.2829## Existing Project Comparison3031- Compare open questions against existing project docs, tests, issues, logs, schemas, routes, and code patterns.32- Convert questions answered by the project into known knowns.33- Keep contradictory or ambiguous evidence in the `Ask now` or `Investigate` buckets.3435## Suggestive Plan36371. Review knowns and current phase target.382. List open questions.393. Classify each question by impact and owner.404. Ask the highest-leverage user question first.415. Update `UNKNOWNS.md`.4243## Example4445For a debugging task, ask whether preserving current behavior matters more than a quick fix, which user flow is failing, and whether logs or reproduction steps exist.4647## Vocabulary4849- Known unknown: explicit unresolved question.50- High-leverage question: answer that changes direction or avoids wasted work.51- Investigation item: question Codex can answer by inspecting artifacts.52- Revisit trigger: event that makes an assumption worth checking again.5354## Expected Outcome5556Produce a `Known Unknowns` section in `UNKNOWNS.md` with prioritized questions classified as `Ask now`, `Investigate`, `Assume for now`, or `Defer`.
harsh817