7.4KB
Diagnostic Intake
Version: 1.0.0 Status: ACTIVE
Purpose
Determine the minimum missing context required to complete a task accurately without producing generic output, asking unnecessary questions, or inventing project facts.
This skill prevents two common agent failures:
ASKING TOO MANY QUESTIONS
and:
GUESSING WHEN THE ANSWER COULD HAVE BEEN DISCOVERED
1. Trigger Conditions
Use this skill when:
- the request is materially ambiguous
- multiple valid implementations depend on unknown constraints
- architecture depends on missing information
- a workflow cannot be safely selected yet
- critical project facts are unknown
- the user asks for a curriculum, architecture, process, or major plan with insufficient context
- a wrong assumption could create substantial rework
Do not use this skill when:
- the answer is already in the repository
- the missing information is noncritical
- a safe reasonable assumption allows progress
- the task is trivial
- the user has already supplied the necessary information
2. Core Rule
Use:
DISCOVER FIRST
ASK SECOND
ASSUME THIRD
not:
ASK FIRST
The agent should exhaust reasonable discovery before asking the user for project information.
3. Intake Process
Start by identifying:
WHAT MUST BE KNOWN
versus:
WHAT WOULD ONLY BE NICE TO KNOW
Classify unknowns as:
CRITICAL
USEFUL
OPTIONAL
4. Critical Information
An unknown is CRITICAL when different answers would materially change:
- architecture
- security
- data handling
- implementation
- compatibility
- cost
- deployment
- irreversible behavior
- requested output
Example:
"What database engine does this application use?"
may be critical for a database migration.
5. Useful Information
Useful information improves the result but does not prevent safe progress.
Example:
"Do you prefer tabs or spaces?"
If the project already has a style, discover it.
If not, follow a reasonable convention.
Do not block the task.
6. Optional Information
Optional information should rarely be asked.
Example:
"What color would you like comments to be?"
when formatting has no effect on the requested outcome.
Do not create unnecessary interaction.
7. Discovery Before Questions
Search available evidence.
Possible sources:
AGENTS.md
CLAUDE.md
README
configuration files
package manifests
project files
source code
tests
database configuration
deployment scripts
existing examples
documentation
If the repository answers the question, use the repository.
8. Question Quality
Ask precise questions.
Avoid:
"Tell me more about the project."
Prefer:
"Should this endpoint preserve the existing Windows Authentication model, or is anonymous access required?"
A good question should clearly affect a decision.
9. Limit Question Count
Prefer:
1–4 targeted questions
over:
10–20 question questionnaire
If several questions depend on the answer to one earlier question, ask the first question only.
10. Progressive Intake
Use:
QUESTION
↓
ANSWER
↓
DO WE NOW HAVE ENOUGH?
/ \
YES NO
↓ ↓
PROCEED NEXT QUESTION
Do not collect unnecessary information in advance.
11. Safe Assumptions
An assumption may be used when:
the risk is low
the assumption follows existing project conventions
the decision is reversible
the user can easily correct it
State important assumptions.
Example:
I'll assume this should follow the same authentication pattern as the existing controllers.
Then proceed.
12. Unsafe Assumptions
Do not silently assume:
production database credentials
destructive intent
security permissions
authentication changes
data-loss tolerance
deployment targets
legal/compliance requirements
irreversible migration behavior
when the assumption materially affects risk.
13. Repository Discovery Example
Task:
Create a new API endpoint.
Unknown:
What authentication does the project use?
Before asking:
SEARCH existing endpoints
INSPECT middleware/configuration
INSPECT authentication configuration
If the answer is found:
PROCEED
Do not ask the user.
14. Architecture Example
Task:
Design a caching layer.
Potential unknowns:
single server or multiple servers?
acceptable stale-data window?
what data is being cached?
existing cache technology?
First inspect:
deployment configuration
dependencies
existing cache code
Ask only what remains critical.
15. Learning Example
Task:
Teach me Kubernetes.
Do not immediately produce a 30-day course.
Ask a diagnostic question such as:
Have you deployed containers with Docker before, or should we start with containers and images?
Then build from the response.
16. Decision Flow
MISSING INFORMATION
↓
CAN IT BE DISCOVERED?
/ \
YES NO
↓ ↓
DISCOVER DOES IT CHANGE CORRECTNESS?
/ \
YES NO
↓ ↓
ASK ASSUME / IGNORE
17. Output Contract
The skill should produce one of two outcomes.
Outcome A — Enough Information Exists
Produce:
Resolved objective
Known constraints
Important assumptions
Next action
Then continue the task.
Outcome B — Critical Information Missing
Ask only the minimal targeted questions required to proceed.
18. Anti-Pattern: Questionnaire Mode
Avoid:
What language?
What framework?
What database?
What OS?
What editor?
What deployment method?
What testing system?
What coding style?
What logging system?
What version control?
when most of this could be discovered from the project.
This wastes user attention.
19. Anti-Pattern: Fake Clarification
Do not ask a question merely to appear careful.
Example:
User:
Create a PowerShell command to list FSMO role holders.
Bad response:
What Windows version are you using?
if the requested command is standard and does not depend materially on that detail.
Proceed.
20. Anti-Pattern: Premature Assumption
Task:
Delete old database records.
Do not silently choose:
older than 30 days
when no age threshold exists.
That variable directly controls destructive behavior.
Ask or discover it.
21. Completion Test
Diagnostic intake is complete when every critical variable has been:
DISCOVERED
ANSWERED
OR
EXPLICITLY AND SAFELY ASSUMED
At that point stop asking questions and continue the work.
22. Self-Improvement
Improve this skill when:
- agents repeatedly ask unnecessary questions
- agents repeatedly make dangerous assumptions
- new discovery sources become available
- a better critical/useful/optional distinction is found
- repeated user feedback reveals poor question design
Do not add project-specific intake questions here.
Project-specific rules belong in project skills or documentation.
23. Changelog
1.0.0
Initial active version.
Introduced:
- discovery-first intake
- critical/useful/optional classification
- progressive questioning
- safe assumption rules
- question-count discipline
- anti-questionnaire guidance