/kiro-discovery

name: kiro-discovery
description: Entry point for new work. Determines the best action path or work decomposition (update existing spec, create new spec, mixed decomposition, or no spec needed) and refines ideas through structured dialogue.

Discovery

<background_information>

• **Success Criteria**:
• Correct action path or work decomposition identified based on existing project state
• User's intent clarified through questions, not assumptions
• Output is an actionable next step (not just a description)

</background_information>

<instructions>

Step 1: Lightweight Scan

Gather **only metadata** to determine the action path. Do NOT read full file contents yet.

• **Specs inventory**: Scan `{{KIRO_DIR}}/specs/*/spec.json` for `name`, `phase` fields and `approvals` status. Note feature names and their current status.
• **Steering existence**: Check which files exist in `{{KIRO_DIR}}/steering/` (product.md, tech.md, structure.md, roadmap.md). Do NOT read their contents yet.
• **Roadmap check**: If `{{KIRO_DIR}}/steering/roadmap.md` exists, read it. This contains project-level context (approach, scope, constraints, spec list) from a previous discovery session. Use it to restore project context.
• **Top-level structure**: List the project root directory to note key directories and files. Do NOT recurse into subdirectories.

This step should consume minimal context. If `specs/` is empty and no steering exists, note "greenfield project" and move to Step 2.

Step 2: Determine Action Path

Based on the user's request and the metadata from Step 1, determine which path applies:

**Path A: Existing spec covers this**

• The request is an extension, enhancement, or fix within an existing spec's domain
• Every meaningful part of the request fits that same spec boundary
• Any remaining small follow-up work can be handled directly without creating a new spec
• Skip remaining steps

**Path B: No spec needed**

• The request is a bug fix, config change, simple refactor, or trivial addition
• No meaningful part of the request needs a new or updated spec boundary
• The request does not need to update an existing spec either
• Skip remaining steps

**Path C: New single-scope feature**

• The request is new, doesn't overlap with existing specs, and fits in one spec

**Path D: Multi-scope decomposition needed**

• The request spans multiple domains or would produce 20+ tasks in a single spec

**Path E: Mixed decomposition**

• The request contains a mix of: existing spec extensions, one or more new spec candidates, and optional direct-implementation work
• Use this path only when at least one genuinely new spec boundary is needed

For Path C/D/E, present the determined path (or mixed decomposition) to the user and confirm before proceeding. For Path A/B, recommend the next action and stop.

Step 3: Deep Context Loading

**Only for Path C, D, and E.** Now load the context needed for discovery.

**In main context** (essential for dialogue with user):

• **Steering documents**: Read product.md and tech.md (if they exist) for project goals, constraints, and tech stack
• **Relevant specs**: If the request is adjacent to an existing spec, read that spec's requirements.md to understand boundaries and avoid overlap

**Delegate to sub-agent** (keeps exploration out of main context):

• **Codebase exploration**: Spawn a sub-agent to explore the codebase and return a structured summary. Ask it to summarize: (1) tech stack and frameworks, (2) directory structure and key modules, (3) patterns and conventions used, (4) areas relevant to the user's request. The sub-agent returns findings under 200 lines.
• For Path D/E, also ask the sub-agent to identify natural domain boundaries, existing module separation, and which areas look like existing-spec extensions vs new boundaries.
• Skip sub-agent dispatch for small/obvious requests where the top-level directory listing from Step 1 is sufficient.

**Context budget**: Keep total content loaded into main context under ~500 lines. The sub-agent handles the heavy exploration.

Step 4: Understand the Idea

Ask clarifying questions **sequentially** (not all at once), prioritizing boundary discovery over feature detail:

1. **Who and why**: Who has the problem? What pain does it cause? 2. **Desired outcome**: What should be true when this is done? 3. **Boundary candidates**: What are the natural responsibility seams in this work? Where could this be split so implementation can proceed independently? 4. **Out of boundary**: What should this spec explicitly NOT own, even if related? 5. **Existing vs new**: Which parts seem like extensions to existing specs, and which parts look like genuinely new boundaries? 6. **Upstream / downstream**: What existing systems, specs, or components does this depend on? What future work is likely to depend on this? 7. **Constraints**: Are there technology, timeline, or compatibility constraints?

Ask only questions whose answers you cannot infer from the context already loaded. Skip questions that steering documents already answer. If the user already provided a clear description, skip to Step 5. The goal is NOT to assign final owners yet. The goal is to discover the cleanest responsibility boundaries that can later become specs, tasks, and review scopes.

Step 5: Propose Approaches

Propose **2-3 concrete approaches** with trade-offs:

For each approach:

• **Approach name**: One-line summary
• **How it works**: 2-3 sentences on the technical approach
• **Pros**: What makes this approach good
• **Cons**: What are the risks or downsides
• **Scope estimate**: Rough complexity (small / medium / large)

If technical research is needed (unfamiliar framework, library evaluation), spawn a sub-agent to research and return a concise summary. Ask it to compare options, check latest versions, and note known issues. Raw search results never enter the main context.

Recommend one approach and explain why.

**After the user selects an approach