--- name: discovery description: "Scope a new project, feature, migration, or public seam through codebase-first exploration and a dependency-ordered interview, then produce an approved Scratchpad backlog without implementing product code. Use for 'interview me', discovery sessions, scope clarification, milestone and issue breakdown, tracer-bullet planning, or expand-contract migration planning." argument-hint: "[interview | outline | materialize] []" --- # Discovery Turn ambiguity into approved, executable work through three phases: **interview**, **outline**, and **materialize**. Discovery decides whether work is AFK-ready; `delivery` decides how to execute it. ## Plan, do not implement Discovery produces decisions, scope, and backlog content. Read-only exploration and writes under `.scratchpad/` are in scope; product-code edits, migrations, deploys, and implementation are not. After materialization, stop and point to `delivery`. If the user requests a phase, start there only when its prerequisites exist: - `interview`: explore and resolve decisions. - `outline`: synthesize an existing discovery record without creating backlog files. - `materialize`: require an approved outline, then invoke the `scratchpad` skill in `backlog` mode to write it. ## Preflight Inspect the exact target before asking questions: ```bash git status --short --branch git log --oneline --decorate -10 fd . .scratchpad -t f 2>/dev/null | head -40 ``` Read repo rules, active Scratchpad indexes, relevant code, tests, and docs. Use bounded read-only explorers only for independent code areas when the surface is broad. Never ask the user for a fact the repo can answer. For code orientation, use `ast-grep outline --items exports --view names` to map candidate modules, then `--view digest` on large files before opening them. Use `ast-grep run` for structural code questions, `rg` for text and configuration, and `fd` for paths. Keep every search rooted at the smallest relevant package or subtree. When earlier sessions may contain an unresolved decision, use `cass` to discover a bounded set and inspect the exact session. Treat transcripts and Scratchpad notes as context, then reconcile them against current code, Git, trackers, and live-service state. ## Phase 1: Interview ### Choose interview breadth Infer breadth from the request or ask through the harness's structured question tool: - **Milestone interview** — make the next coherent milestone executable; preserve later uncertainty as fog. - **Upfront interview** — traverse decisions across the complete requested scope so the planned backlog can become AFK-ready. Breadth does not change question ordering. Follow the decision-tree spine and ask dependent decisions serially; batch only independent leaf choices. ### Explore, then ask - Recommend the decision you would choose and state the tradeoff briefly. - Use the harness's structured question tool for every user choice or clarification. - Challenge vague terms and confirm one canonical meaning. - Check user claims against code and surface contradictions with evidence. - Cover destination, observable success, scope, non-goals, constraints, edge cases, risks, public seams, and validation. - Never answer a user-owned decision yourself. Record undecided areas as fog. Maintain `.scratchpad/research/discovery-.md` with: ```markdown # Discovery: ## Interview breadth ## Destination and success criteria ## Decisions so far ## Not yet specified (fog) ## Out of scope ## Evidence and interview log ## Delivery readiness ``` Use the fog-or-ticket test: a precise open question may become a research or interview issue. If the question itself is unclear, keep it as fog rather than creating executable work. ## Phase 2: Outline Synthesize the smallest backlog that reaches the destination. Do not create issue or milestone files yet. ### Expand, then contract 1. List locked decisions, fog, non-goals, seams, risks, and validation targets. 2. Propose work units with interaction mode, dependencies, and completion evidence. 3. Identify the first end-to-end tracer when behavior crosses boundaries. 4. Remove speculative or duplicate work. 5. Keep one independently verifiable outcome per issue and leave unresolved fog outside the executable sequence. Default to vertical tracer slices. For a wide migration that cannot land atomically, use a bounded expand → migrate → contract sequence. Represent ordering with `depends_on` and an explicit prerequisite completion condition. ### Classify readiness | Work type | Default interaction | Completion evidence | | --------- | ----------------------------- | ------------------------------------------------------------- | | Research | AFK | Cited findings and a decision or explicit unresolved question | | Prototype | HITL | Runnable probe plus recorded user feedback | | Interview | HITL | User-owned decisions and remaining fog | | Task | AFK only when fully specified | Acceptance criteria and exact validation pass | An AFK issue contains every product, design, and architecture decision needed for safe execution. Otherwise classify it HITL or split out an interview issue first. Classify the backlog: - **Fully AFK-ready** — every runnable implementation issue is AFK. - **Mixed** — intentional HITL boundaries remain; name each one and its required decision. ### Present and approve Show: - destination, decisions, fog, and out-of-scope boundary; - interview breadth and backlog readiness; - proposed milestones and issues with outcomes, interaction modes, dependencies, and completion evidence; - validation targets and any tracer or expand-contract sequence; - recommended `delivery` interaction mode. For a new or changed public seam, read [references/seam-stack-template.md](references/seam-stack-template.md) and include its seam stack and tracer sequence. Use the harness's structured question tool to approve the outline or request revisions. Do not materialize without approval. ## Phase 3: Materialize Invoke the `scratchpad` skill in `backlog` mode after outline approval. That skill owns directory layout, frontmatter, issue and milestone shapes, indexes, relationship validation, and lifecycle state. Pass the approved: - destination, decisions, fog, scope, and non-goals; - issue outcomes, work types, and HITL/AFK boundaries; - milestone grouping, dependencies, and blockers; - acceptance criteria, entry points, and validation; - seam/tracer additions when applicable; - backlog readiness and recommended delivery mode. Follow an existing repository convention when it is stronger than Scratchpad's default contract. After materialization, use the same `backlog` mode to validate the graph and active index. ## Completion gate Discovery is complete when the user has approved the outline and the `scratchpad` skill's `backlog` validation passes on the materialized graph. Report the created paths, readiness, remaining fog, and first runnable issue, then stop.