# 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: ```text ASKING TOO MANY QUESTIONS ``` and: ```text 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: ```text DISCOVER FIRST ASK SECOND ASSUME THIRD ``` not: ```text ASK FIRST ``` The agent should exhaust reasonable discovery before asking the user for project information. --- # 3. Intake Process Start by identifying: ```text WHAT MUST BE KNOWN ``` versus: ```text WHAT WOULD ONLY BE NICE TO KNOW ``` Classify unknowns as: ```text 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: ```text "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: ```text "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: ```text "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: ```text 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: ```text "Tell me more about the project." ``` Prefer: ```text "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: ```text 1–4 targeted questions ``` over: ```text 10–20 question questionnaire ``` If several questions depend on the answer to one earlier question, ask the first question only. --- # 10. Progressive Intake Use: ```text 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: ```text the risk is low the assumption follows existing project conventions the decision is reversible the user can easily correct it ``` State important assumptions. Example: ```text I'll assume this should follow the same authentication pattern as the existing controllers. ``` Then proceed. --- # 12. Unsafe Assumptions Do not silently assume: ```text 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: ```text Create a new API endpoint. ``` Unknown: ```text What authentication does the project use? ``` Before asking: ```text SEARCH existing endpoints INSPECT middleware/configuration INSPECT authentication configuration ``` If the answer is found: ```text PROCEED ``` Do not ask the user. --- # 14. Architecture Example Task: ```text Design a caching layer. ``` Potential unknowns: ```text single server or multiple servers? acceptable stale-data window? what data is being cached? existing cache technology? ``` First inspect: ```text deployment configuration dependencies existing cache code ``` Ask only what remains critical. --- # 15. Learning Example Task: ```text Teach me Kubernetes. ``` Do not immediately produce a 30-day course. Ask a diagnostic question such as: ```text Have you deployed containers with Docker before, or should we start with containers and images? ``` Then build from the response. --- # 16. Decision Flow ```text 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: ```text 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: ```text 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: ```text Create a PowerShell command to list FSMO role holders. ``` Bad response: ```text 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: ```text Delete old database records. ``` Do not silently choose: ```text 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: ```text 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