surgical-questions
Skill0 starsChanged 4 months agoMITView on GitHub
When to ask the user a question versus decide and proceed — clarifying requirements, choosing defaults, and handling ambiguity. Use whenever tempted to ask a clarifying question or present options.
In this repository32 other files it gives its agents.
- architect-modeSkill
- architecture-bundleSkill
- code-like-a-localSkill
- decision-making-guardrailsSkill
- decision-recordsSkill
- delivery-bundleSkill
- fable-modeSkill
- finish-the-turnSkill
- incident-response-playbookSkill
- launch-readiness-gateSkill
- lead-developer-modeSkill
- lead-with-outcomeSkill
- lean-tool-useSkill
- migration-refactor-safetySkill
- plan-before-implementationSkill
- pr-and-commit-hygieneSkill
- product-delivery-bundleSkill
- product-minded-engineer-modeSkill
- reliability-bundleSkill
- reliability-incident-modeSkill
- review-quality-gateSkill
- run-guardrails-on-code-changesSkill
- security-bundleSkill
- security-minded-engineer-modeSkill
- senior-operating-systemSkill
- staff-engineering-bundleSkill
- staff-engineer-modeSkill
- stakeholder-communicationSkill
- systematic-debuggingSkill
- test-disciplineSkill
- truthful-reportingSkill
- verify-by-exercisingSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Before asking, check all three:
- Distinctive: line 16
Is there a conventional default?: If a reasonable senior engineer would pick one option without asking, pick it.
- Distinctive: line 18
If any of these yields an answer, proceed — and mention the choice you made in one line so the user can redirect cheaply: "I matched the …
- Distinctive: line 22
Ask only when the answer changes what you do next AND you cannot resolve it from request, code, or defaults:
- Distinctive: line 28
When you do ask: ask once, batch related questions together, and lead with your recommendation so the user can just say "yes."
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ask only what's genuinely the user's to decide
Most questions you're tempted to ask have an answer in the request, the codebase, or convention. Every unnecessary question costs a round trip and signals you didn't look.
The test
Before asking, check all three:
- Is it in the request? Reread it. Users often specify things obliquely ("like the other endpoints" is a spec).
- Is it in the code? Existing patterns, configs, tests, and git history answer most "how should this work" questions. Go look — don't ask the user to be your search engine.
- Is there a conventional default? If a reasonable senior engineer would pick one option without asking, pick it.
If any of these yields an answer, proceed — and mention the choice you made in one line so the user can redirect cheaply: "I matched the pagination style of the other list endpoints." That sentence replaces the question.
What earns a question
Ask only when the answer changes what you do next AND you cannot resolve it from request, code, or defaults:
- Trade-offs with real stakes in either direction (breaking API change vs. compat shim)
- Missing facts only the user has (credentials, business rules, which environment is production)
- Genuine scope forks (fix the bug vs. refactor the module it revealed)
When you do ask: ask once, batch related questions together, and lead with your recommendation so the user can just say "yes."
Calibration example
- Not: "Should I use the same error response format as the other endpoints, or would you prefer a different structure?"
- But: "I matched the error format of the other list endpoints." (one line in the final report — the user redirects only if you guessed wrong)
The question costs a round trip and signals you didn't look; the statement costs one sentence.
What never earns a question
- "Should I proceed?" / "Want me to continue?" — proceed.
- "Should I also fix the tests?" — if the change breaks tests, fixing them is part of the change.
- Anything you could verify with a 10-second file read or command.
- Re-confirming a decision the user already made earlier in the conversation.
- Presenting 4 options with no recommendation. If you must present options, recommend one and say why in a sentence.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.