---

name: ask-deep description: This skill should be used for interactive clarification with smart HIL question flows. Triggers include "ask me questions", "help me think through", "what should we consider", session start ("what are we working on"), scope definition ("what's in/out"), or review checkpoints ("does this look right"). Auto-detects context and adapts question depth. Override with explicit mode (ask-deep start, ask-deep scope, ask-deep review).

ask-deep

Context-first HIL questions using OARS technique. Auto-detects mode or accepts explicit override.

when to use

Note: This skill is for gathering human input when tools can't answer the question. If the answer is discoverable via outline, layer, git log, or Linear - use tools first.

modes

auto-detection

CopyWhat mode should I use?
├── User explicitly requests mode? ("ask-deep start", "use explore mode")
│   └── use requested mode (explicit override wins)
├── Session just started? (no prior context)
│   └── mode: start
├── User asks about scope/boundaries?
│   └── mode: scope
├── User asks "which" or presents options?
│   └── mode: choose
├── Task nearly complete?
│   └── mode: review
└── Default
    └── mode: explore

Precedence: explicit override > session state > keyword detection > default

decision tree: depth calibration

CopyHow deep should questioning go?
├── User seems impatient? (short answers, "just do it")
│   └── shallow: 1-2 rounds, confirm and proceed
├── Simple/familiar task? (similar to past work)
│   └── shallow: 1-2 rounds, single question → confirm
├── New feature? (clear goal, some unknowns)
│   └── medium: 3-4 rounds, broad → narrow → edge cases → confirm
├── Architecture/design? (system-level, many stakeholders)
│   └── deep: 5-8 rounds, problem → constraints → options → trade-offs → meta
└── User explicitly requests depth?
    └── match requested depth

decision tree: tool before question

CopyShould I use a tool before asking?
├── Question is about preferences, priorities, or intent?
│   └── NO tools: ask directly (tools can't discover human intent)
├── User mentions a file/module?
│   └── YES: outline --callers=X or outline --search=X
├── User mentions "similar to" or "like before"?
│   └── YES: git log --oneline -10, outline --diff=HEAD~5
├── User mentions current work/task?
│   └── YES: linear issue list --assignee me
└── Could I discover the answer myself?
    └── YES: run tool first, then ask sharper question

Note: Intent questions (preferences, priorities, trade-offs) always go direct to user. Factual questions (what exists, what changed) go to tools first.

decision tree: archetype selection

CopyWhat question archetype fits?
├── Ambiguity in the request?
│   └── clarification
├── Multiple valid approaches?
│   └── preference or trade-off
├── Need to confirm an assumption?
│   └── confirmation
├── Scope is unclear or expanding?
│   └── scope
├── Multiple systems involved?
│   └── integration
├── Order of operations matters?
│   └── sequence
├── Core path known, need boundaries?
│   └── edge case
├── After 3-4 questions or drifting?
│   └── meta (synthesis)
└── Early-stage discovery?
    └── exploration

decision tree: mode transition

CopyShould I switch modes mid-conversation?
├── Started in explore, now have clear options?
│   └── transition to choose
├── Started in start, scope expanding?
│   └── transition to scope
├── Task implementation complete?
│   └── transition to review
├── User says "wait, let me think about..."?
│   └── pause, let them speak (OARS: affirm)
└── Confusion or frustration detected?
    └── meta question: "Should we step back?"

OARS technique

Adapted from motivational interviewing (Miller & Rollnick, 2012):

Question stems to prefer (NN/g):

• "Tell me about..."
• "What do you think about..."
• "How would you..."
• "What's the most important..."

Question stems to avoid (NN/g):

• Leading: "Don't you think..."
• Binary when open needed: "Is it X?" (vs "What is it?")
• Compound: "What about X and also Y?"

mode: start

Session initiation - before loop or deep work.

Copyround 1 (Open):
- "Which project?" (detect from cwd, offer recent)
- "What's the goal?" (detect from Linear in-progress)
- Affirmation: "That's a clear target."

round 2 (Reflective + Probe):
- "So the priority is [X] over [Y]?" (reflect back goal)
- "Is this the issue?" (if Linear detected)
- "Any constraints?" (time, scope, dependencies)
- "What does 'done' look like?" (definition of done)

round 3 (Summary + confirm):
- For monorepos: "Which package/subpath?" (e.g., packages/web vs packages/mobile)
- "Design considerations?" (trigger emil-kowalski if UI)
- Summary: "So we're doing X in Y with constraints Z. Ready to proceed?"

mode: scope

Define boundaries - prevent scope creep.

Copyround 1 (Open):
- "What's the minimum viable version?"
- "What's explicitly out of scope?"
- Affirmation: "Good boundary to draw."

round 2 (Reflective + Summary):
- "So the MVP is [X] and we're skipping [Y]?" (reflect back)
- "What's the success criteria?"
- "Any non-obvious constraints?"

mode: explore

The classic deep-ask - Socratic elenchus pattern.

Socratic structure (Vlastos, 1983):

1. Elicit initial position
2. Probe with "what if" / edge cases
3. Surface contradictions or gaps
4. Guide toward refined understanding
5. Reach aporia (productive confusion) or clarity

Depth based on complexity:

• Simple: 1-2 rounds, single question → confirm
• Feature: 3-4 rounds, broad → narrow → edge cases → confirm
• Architecture: 5-8 rounds, problem → constraints → options → trade-offs → meta

Funnel technique (NN/g):

• Start broad: "What problem are you solving?"
• Narrow: "Which of these matters most?"
• Specific: "How should X handle Y?"

decision tree: continue or stop

CopyShould I keep asking?
├── User says "let's do it" or gives short answers?
│   └── stop and synthesize
├── Answers repeat the same theme?
│   └── stop and summarize
├── New dimensions or contradictions appear?
│   └── continue with targeted follow-up
├── 3-4 questions asked already?
│   └── ask a meta question, then decide
├── User engages deeply, long answers?
│   └── continue (change talk signal)
└── Otherwise
    └── continue one more round

mode: choose

Quick decision between valid options.

Copysingle question:
- Present 2-4 options
- First is recommended (add "(Recommended)")
- Descriptions show trade-offs, not definitions
- Done in 1 round

mode: review

Pre-completion validation.

Copyround 1 (Open + Reflect):
- "Is this the behavior you expected?"
- Affirmation: "Good catch" or "Makes sense"
- "So you're seeing [X] and expecting [Y]?" (reflect discrepancy if any)
- "Any edge cases I should handle?"

round 2 (Closing):
- "Ready to commit/merge?"
- "Anything else before we ship?"

context gathering (when applicable)

Before asking about facts (not preferences), understand the landscape:

Copylayer .                           # architecture
outline --callers=X src/          # who uses X
git log --oneline -10             # recent activity
outline --diff=HEAD~3             # recent changes
linear issue list --assignee me   # current work

Never ask about things you could discover. But don't delay preference/priority questions waiting for tool output.

tool → question mapping

Use tool output to sharpen questions:

Copy# "auth module" mentioned
outline --callers=authenticate src/auth/

# "similar pattern" mentioned
outline --search=patternName src/

# "recent changes" mentioned
outline --diff=HEAD~5 --search=auth

question design

• headers: 12 char max, tight chips ("auth method" not "authentication methodology")
• options: 2-4, first is recommended, describe implications not definitions
• multi-select: when choices aren't mutually exclusive
• meta questions: "does this feel right?", "what am I missing?"

concrete values

Legend: "primary" = grounded in cited research; "heuristic" = practical guideline, adjust based on context

synthesis checkpoint

After each round, summarize in 2-4 bullets and confirm (OARS: Summarizing):

Copyso far:
- [signal 1]
- [signal 2]
- [constraint or preference]

ready to proceed, or dig deeper?

handoff schema

When ask-deep completes, output structured context using the standard output contract:

Copy{
  "mode": "explore",
  "status": "success",
  "summary": "Clarified auth requirements through 3 rounds of questions. Key decisions: JWT with refresh tokens, offline-first, minimal dependencies.",
  "confidence": 8,
  "inputs": {
    "task": "clarify auth approach for mobile + web",
    "constraints": ["existing Clerk integration"]
  },
  "artifacts": [
    {
      "type": "analysis",
      "content": {
        "ask_deep_mode": "start",
        "rounds": 3,
        "signals": [
          "priority: speed over flexibility",
          "constraint: must work offline"
        ],
        "decisions": [
          {"question": "auth approach?", "answer": "JWT with refresh tokens"}
        ],
        "open_questions": ["exact error handling TBD"],
        "assumptions": ["user has network on first login"],
        "risks": ["offline-first may complicate sync"],
        "definition_of_done": "user can log in via email OTP and see dashboard",
        "repo_subpath": "packages/mobile"
      }
    }
  ],
  "sources": {
    "prompts": [],
    "files_read": ["convex/auth.ts"]
  },
  "assumptions": ["user has network on first login", "existing sessions remain valid"],
  "next_steps": ["loop skill for implementation"],
  "blockers": []
}

See ~/Developer/skills/.system/output-contract.md for full schema.

Downstream skills should:

1. Check open_questions in artifact before proceeding
2. Validate assumptions early
3. Monitor risks during execution

anti-patterns

primary sources

tool integration

trails integration

persist question flows for pattern analysis:

Copy# record ask-deep session
trails trail record --agent claude --new-trace --action completed \
  --task "ask-deep: $MODE - $TOPIC" --confidence $CONFIDENCE --json -q

trails enables:

• tracking question patterns over time
• identifying frequently unclear areas
• measuring clarification effectiveness

references

• references/question-archetypes.md - question types
• references/conversation-patterns.md - multi-turn flows
• references/cli-context-gathering.md - tool integration