Discover

Discover Skill

Read Docs/ folder, understand the project, and help create PRODUCT.md.

Overview

This skill guides the discovery phase where you:

1. Read all documents in the Docs/ folder (recursively)
2. Understand the project vision and context
3. Ask clarifying questions
4. Help the user create a well-structured Docs/PRODUCT.md

Usage

/discover

Prerequisites

• Access to project documentation (Docs/ or fallback locations).

Purpose

Human-guided discovery - Don't assume, ask questions.

The goal is to build shared understanding before any code is written. By the end of this phase, both you and the user should have a clear picture of:

• What problem we're solving
• What success looks like
• Key constraints and requirements
• Technical approach (high-level)

Workflow Steps

Step 1: Find and Read Documents

Look for documentation in these locations (in order of priority):

Primary (preferred):

• Docs/ folder - Primary documentation folder

Fallbacks (legacy):

• Documents/ folder - Legacy naming convention
• docs/ folder - Lowercase alternative
• README.md - If no docs folder exists
• Any .md files in the root

Flexible Structure: The Docs/ folder can have ANY structure. The only requirement is that PRODUCT.md exists somewhere in Docs/ (usually at the root). All other documentation can be organized however makes sense for the project.

How to search:

Glob: Docs/**/*.md

This finds all .md files in Docs/ and all subfolders, regardless of structure.

If Docs/ doesn't exist, check fallback locations. List all found documents and read each one.

Step 2: Summarize Understanding

After reading, present a summary:

## What I Understand

### Project Purpose
[Brief summary of what the project does]

### Current State
[Is this greenfield or existing code? What exists?]

### Feature/Goal
[What we're trying to build or achieve]

### Key Constraints
[Technical, timeline, compatibility requirements]

### Stakeholders
[Who will use this? Who needs to approve?]

Step 3: Ask Clarifying Questions

Present 3-5 targeted questions. Examples:

• "What's the MVP scope vs. nice-to-haves?"
• "Are there existing patterns I should follow?"
• "What's the testing strategy preference?"
• "Are there any hard deadlines?"
• "Who needs to review before merge?"

Important: Wait for answers before proceeding.

Step 4: Capture Context

Create or update CONTEXT.md with:

• Decisions made during discussion
• User preferences
• Constraints confirmed
• Out-of-scope items

Step 5: Draft Docs/PRODUCT.md

When ready, propose a Docs/PRODUCT.md draft:

# Feature Name
[Clear, specific name]

## Summary
[50-500 characters describing what it does]

## Problem Statement
[Why this feature is needed - minimum 100 characters]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
[Minimum 3 criteria]

## Example Inputs/Outputs

### Example 1

// Input {example input} // Output {expected output}

### Example 2

// Input {example input} // Output {expected output}

## Technical Constraints
[Performance, security, compatibility requirements]

## Testing Strategy
[How to test this feature]

## Definition of Done
- [ ] All acceptance criteria met
- [ ] Tests passing
- [ ] Code reviewed
- [ ] Documentation updated
- [ ] No security issues

Step 6: Get Approval

Ask: "Should I save this as Docs/PRODUCT.md?"

Only save after user confirms. Create the Docs/ folder if it doesn't exist.

Key Behaviors

DO

• Read ALL available documents before asking questions
• Present your understanding for validation
• Ask targeted, specific questions
• Wait for answers before proceeding
• Offer to create PRODUCT.md when ready
• Be explicit about what you don't know

DON'T

• Assume requirements not explicitly stated
• Skip to planning without understanding
• Create PRODUCT.md without approval
• Make architectural decisions without discussion
• Rush through discovery

Document Locations

Check these paths (in priority order):

1. Docs/ - Primary documentation folder (preferred)
2. Documents/ - Legacy documentation folder (fallback)
3. docs/ - Lowercase alternative (fallback)
4. README.md - Project readme (minimal fallback)
5. ./*.md - Any markdown files in root (last resort)

Output Files

Note: PRODUCT.md should be created inside Docs/ folder, not in project root.

State Update

After completing discovery:

• Create/update workflow_state in SurrealDB
• Set phase_status.discussion = "completed"
• Set current_phase = 1 (ready for planning)

Transition

When Docs/PRODUCT.md is created and approved:

Discovery complete! Docs/PRODUCT.md created.

Next steps:
  /plan - Create task breakdown from this specification

Or if you want to review the spec again:
  Read Docs/PRODUCT.md and let me know any changes needed.

Example Session

User: /discover

Claude: I'll explore your project documentation to understand what we're building.

Let me check for documents...

Searching: Docs/**/*.md

Found:
  - Docs/product-vision.md
  - Docs/design/overview.md
  - Docs/design/api-design.md

Reading each document...

## What I Understand

### Project Purpose
This is a task management API that allows teams to track work items with assignments, priorities, and due dates.

### Current State
Greenfield project. No existing code yet. Using TypeScript + Express + PostgreSQL stack.

### Feature/Goal
Building the core task CRUD operations with user assignment.

### Key Constraints
- REST API design (from Docs/architecture/api-design.md)
- Must support bulk operations
- Auth handled separately (OAuth assumed)

## Questions

1. Should tasks support subtasks, or keep it flat for MVP?
2. What's the priority model - numeric (1-5) or labels (high/medium/low)?
3. Are there any rate limiting requirements?
4. Who will be calling this API - web app, mobile, or both?

User: Keep flat for MVP. Use labels. No rate limits yet. Web app only for now.

Claude: Got it. Let me capture that in CONTEXT.md...

Based on our discussion, here's a draft Docs/PRODUCT.md:

[Shows draft]

Should I save this as Docs/PRODUCT.md?

User: Yes, looks good.

Claude: Created Docs/PRODUCT.md

Discovery complete! You can now:
  /plan - Create task breakdown from this specification

Outputs

• Docs/PRODUCT.md created or updated with validated structure.

Error Handling

• If required documentation is missing, stop and request sources before drafting PRODUCT.md.

Related Skills

• /plan - Next step after discovery
• /status - Check current progress
• /orchestrate - Full automated workflow (alternative)