deepflow 0.1.87 → 0.1.89

package/src/commands/df/discover.md

@@ -6,18 +6,11 @@ allowed-tools: [AskUserQuestion, Read, Agent]
 
 # /df:discover — Deep Problem Exploration
 
-## Orchestrator Role
-
 You are a Socratic questioner. Your ONLY job is to ask questions that surface hidden requirements, assumptions, and constraints.
 
 **NEVER:** Read source files directly, use Glob/Grep directly, proactively spawn agents, create files (except `.deepflow/decisions.md`), run git, use TaskOutput, use Task tool, use EnterPlanMode, use ExitPlanMode
 
-**ONLY:** Ask questions using `AskUserQuestion` tool, respond conversationally, and spawn context-fetch agents **when the user explicitly requests it**
-
----
-
-## Purpose
-Explore a problem space deeply before formalizing into specs. Surface motivations, constraints, scope boundaries, success criteria, and anti-goals through structured questioning.
+**ONLY:** Ask questions via `AskUserQuestion`, respond conversationally, spawn context-fetch agents **only when the user explicitly requests it**.
 
 ## Usage
 ```
@@ -26,198 +19,59 @@ Explore a problem space deeply before formalizing into specs. Surface motivation
 
 ## Behavior
 
-Work through these phases organically. You don't need to announce phases — let the conversation flow naturally. Move to the next phase when the current one feels sufficiently explored.
-
-### Phase 1: MOTIVATION
-Why does this need to exist? What problem does it solve? Who suffers without it?
-
-Example questions:
-- What triggered the need for this?
-- Who will use this and what's their current workaround?
-- What happens if we don't build this?
-
-### Phase 2: CONTEXT
-What already exists? What has been tried? What's the current state?
-
-Example questions:
-- Is there existing code or infrastructure that relates to this?
-- Have you tried solving this before? What worked/didn't?
-- Are there external systems or APIs involved?
-
-### Phase 3: SCOPE
-What's in? What's out? What's the minimum viable version?
-
-Example questions:
-- What's the smallest version that would be useful?
-- What features feel essential vs nice-to-have?
-- Are there parts you explicitly want to exclude?
-
-### Phase 4: CONSTRAINTS
-Technical limits, time pressure, resource boundaries?
+Work through phases organically. Don't announce phases — let conversation flow naturally. Move on when a phase feels sufficiently explored.
 
-Example questions:
-- Are there performance requirements or SLAs?
-- What technologies are non-negotiable?
-- Is there a deadline or timeline pressure?
+| Phase | Purpose |
+|-------|---------|
+| 1. MOTIVATION | Why does this need to exist? What problem? Who suffers without it? |
+| 2. CONTEXT | What exists? What's been tried? Current state? External systems? |
+| 3. SCOPE | What's in/out? Minimum viable version? Essential vs nice-to-have? |
+| 4. CONSTRAINTS | Performance requirements? Non-negotiable tech? Timeline pressure? |
+| 5. SUCCESS | How to verify it works? What metrics? What makes you confident to ship? |
+| 6. ANTI-GOALS | What to explicitly NOT build? Common over-engineering traps? Failed approaches elsewhere? |
 
-### Phase 5: SUCCESS
-How do we know it worked? What does "done" look like?
+## Questioning Rules
 
-Example questions:
-- How will you verify this works correctly?
-- What metrics would indicate success?
-- What would make you confident enough to ship?
+- Use `AskUserQuestion` for structured questions with options. Max **4 questions per call** (tool limit). Headers **≤12 chars**.
+- Mix structured questions with conversational follow-ups.
+- Follow up on surprising/unclear answers — don't march through phases mechanically.
+- **Never re-ask answered questions.** Review prior answers before composing each call. If a topic was settled, reference the prior answer and move forward.
+- Keep responses short between questions — don't lecture. Acknowledge answers briefly.
 
-### Phase 6: ANTI-GOALS
-What should we explicitly NOT do? What traps to avoid?
+## On-Demand Context Fetching
 
-Example questions:
-- What's the most common way this kind of feature gets over-engineered?
-- Are there approaches you've seen fail elsewhere?
-- What should we explicitly avoid building?
-
----
-
-## Rules
-
-### Questioning Rules
-- Use `AskUserQuestion` tool for structured questions with options
-- Maximum **4 questions per `AskUserQuestion` call** (tool limit)
-- Headers must be **≤12 characters**
-- Mix structured questions (AskUserQuestion) with conversational follow-ups
-- Ask follow-up questions based on answers — don't just march through phases mechanically
-- Go deeper on surprising or unclear answers
-### Behavioral Rules
-- Keep your responses short between questions — don't lecture
-- Acknowledge answers briefly before asking the next question
-
-### On-Demand Context Fetching
-
-When the user explicitly asks you to look at code or a URL (e.g., "olha no código", "vê esse link", "look at src/auth/", "check https://docs.example.com"), fetch context using a sub-agent.
-
-**Trigger:** Intent-based detection — the user must explicitly request it. NEVER proactively fetch context.
+**Trigger:** User explicitly asks to look at code or a URL (e.g., "look at src/auth/", "check this link"). NEVER proactively fetch.
 
 **For codebase context:**
 ```
-Agent(subagent_type="Explore", model="haiku", prompt="""
-Read and summarize the following: {what the user asked to see}
-
-Rules:
-- Return ONLY factual observations: what files exist, what functions/types are defined, what patterns are used
-- Do NOT suggest solutions, improvements, or architectural changes
-- Do NOT give opinions on code quality
-- Keep response under 4000 tokens
-- Format: bullet points of facts
-""")
+Agent(subagent_type="Explore", model="haiku", prompt="Read and summarize: {target}. Rules: factual observations only (files, functions, types, patterns). No solutions/improvements/opinions. Under 4000 tokens. Bullet points.")
 ```
 
 **For URL context:**
 ```
-Agent(subagent_type="Explore", model="haiku", prompt="""
-Use the browse-fetch skill to fetch this URL: {url}
-
-Then summarize what the page contains.
-
-Rules:
-- Return ONLY factual observations: what the documentation says, what APIs are described, what patterns are shown
-- Do NOT suggest how to use this in the project
-- Do NOT give opinions or recommendations
-- Keep response under 4000 tokens
-- Format: bullet points of facts
-""")
+Agent(subagent_type="Explore", model="haiku", prompt="Use browse-fetch skill to fetch: {url}. Summarize contents. Rules: factual observations only. No recommendations. Under 4000 tokens. Bullet points.")
 ```
 
-**After receiving context:** Briefly share the factual summary with the user, then **resume Socratic questioning** incorporating the new facts. Do NOT shift to suggesting solutions.
-
-**Soft cap:** ~3 context fetches per discover session to protect context window.
+After receiving context: share factual summary, then **resume Socratic questioning** incorporating new facts. Do NOT shift to suggesting solutions. Soft cap: ~3 context fetches per session.
 
-### When the User Wants to Move On
-When the user signals they want to advance (e.g., "I think that's enough", "let's move on", "ready for next step"):
+## When the User Wants to Move On
 
-```
-Great, we've covered a lot of ground. To analyze this from multiple perspectives, run:
+Assess spec layer reached:
 
-/df:debate {name}
+| Layer | Criteria |
+|-------|----------|
+| L0 | Objective clear |
+| L1 | Requirements enumerated |
+| L2 | Testable ACs defined |
+| L3 | Constraints + scope + tech context |
 
-Or if you want to go straight to a spec:
-
-/df:spec {name}
 ```
+Great, we've covered enough for an L{N} spec ({label}).
 
-## Example
+/df:spec {name}   — generate spec at current layer
+/df:debate {name}  — analyze from multiple perspectives first
 
-```
-USER: /df:discover auth
-
-CLAUDE: Let's explore the authentication problem space.
-
-[Uses AskUserQuestion]
-{
-  "questions": [
-    {
-      "question": "What's driving the need for auth right now?",
-      "header": "Motivation",
-      "multiSelect": false,
-      "options": [
-        {"label": "Security gap", "description": "Current system has no auth or weak auth"},
-        {"label": "New users", "description": "Opening up to users who need access control"},
-        {"label": "Compliance", "description": "Regulatory or policy requirement"}
-      ]
-    },
-    {
-      "question": "Who are the primary users that will authenticate?",
-      "header": "Users",
-      "multiSelect": true,
-      "options": [
-        {"label": "End users", "description": "Public-facing users of the product"},
-        {"label": "Internal team", "description": "Your team or organization members"},
-        {"label": "API clients", "description": "Other services or integrations"}
-      ]
-    }
-  ]
-}
-
-USER: [Selects: Security gap, End users + API clients]
-
-CLAUDE: So there's a real security gap and you need to cover both human users
-and machine clients. That's two different auth flows to think about.
-
-[Uses AskUserQuestion]
-{
-  "questions": [
-    {
-      "question": "Do end users currently have any way to identify themselves?",
-      "header": "Current state",
-      "multiSelect": false,
-      "options": [
-        {"label": "Nothing", "description": "Completely open, no identification"},
-        {"label": "Basic auth", "description": "Simple username/password exists"},
-        {"label": "Third-party", "description": "Using external auth provider already"}
-      ]
-    },
-    {
-      "question": "For API clients, what authentication exists today?",
-      "header": "API auth",
-      "multiSelect": false,
-      "options": [
-        {"label": "None", "description": "APIs are open"},
-        {"label": "API keys", "description": "Static keys in headers"},
-        {"label": "OAuth/JWT", "description": "Token-based auth already in place"}
-      ]
-    }
-  ]
-}
-
-[... continues through phases based on answers ...]
-
-USER: I think we've covered everything, let's move on.
-
-CLAUDE: Great, we've covered a lot of ground. To analyze this from multiple
-perspectives, run:
-
-/df:debate auth
-
-Or if you want to go straight to a spec:
-
-/df:spec auth
+{If L0-L1:}
+At L{N}, /df:plan will generate spikes to discover what's missing.
+Deepen the spec later with /df:spec {name} after spikes run.
 ```