Discovery

Discovery: Approach → Domain-Aware Requirements

Philosophy: The gap between "we picked an approach" (brainstorm) and "we have formal requirements" (PRD) is where complex features fail. Discovery fills that gap with domain-specific depth — mapping every actor, walking every workflow, surfacing every integration point and security concern. Discovery is a working process — the PRD is the authoritative document. Discovery produces a brief that feeds into PRD; the PRD absorbs and formalises discovery's findings.

Target duration: 2-4 hours for a typical COMPREHENSIVE discovery. If it's taking longer, you're likely designing instead of discovering — stay at the requirements level.

Why This Matters

Complex features fail when requirements are discovered during implementation instead of before it. A missing actor, an overlooked integration, or an unidentified compliance requirement can force expensive rework weeks into development. Discovery prevents this by systematically walking through the problem domain before a single line of code is written. The cost of discovery is hours; the cost of missed requirements is weeks.

---

Trigger Conditions

Run this skill when:

• Brainstorm scope classifier says COMPREHENSIVE
• User says "discover requirements", "deep dive requirements", "requirements elicitation"
• Feature touches auth, multiple user roles, external integrations, or complex UI
• After brainstorm, before PRD, for any non-trivial feature

Do NOT run when:

• Simple CRUD or config change (go straight to PRD or plan)
• Brainstorm scope classifier says BRIEF
• Pure technical refactor with no new requirements

Stage Gates — AskUserQuestion

At every PAUSE point in this skill, call the AskUserQuestion tool to present structured options to the user. Do not present options as plain markdown text — use the tool. The YAML blocks at each PAUSE point show the exact parameters to pass.

For pattern details and examples: ../_shared/references/stage-gates.md

> Fallback: Only if AskUserQuestion is not available as a tool (check your tool list), fall back to presenting options as markdown text and waiting for freeform response.

---

Collaborative Model

Phase 1: Actor & Workflow Mapping
  ── Pre-mortem: "Imagine this failed. Why?" ──
  ── PAUSE 1: "Here are the actors, workflows, and early risks. Complete?" ──
Phase 2: Domain Requirements Elicitation
  ── PAUSE 2: "Here are the domain requirements. Scope right?" ──
Phase 3: Integration & UI Analysis
Phase 3b: Security, Compliance, Feasibility & Risk
Phase 4: Synthesis & Brief
  ── PAUSE 3: "Discovery complete. Ready for PRD?" ──
Phase 5: Output (save discovery-brief.md + glossary.md)

---

Prerequisites

Step 0 — Import Upstream Artifacts:

Check for existing work before starting fresh:

• Brainstorm (primary input) — docs/brainstorm/{feature}/brainstorm.md (problem statement, chosen approach, boundaries, scope classification, kill criteria)
• Research brief (if /research was run) — docs/research/{feature}/research-brief.md (findings tagged [CONSTRAINT], [OPTION], [RISK], [PRIOR-ART], [UNKNOWN])
• ADRs — docs/adr/ (existing architecture decisions that constrain discovery — tag as [CONSTRAINT])
• Patterns — docs/patterns/ (established conventions that inform what's already solved — tag as [PRIOR-ART])
• Learnings — docs/learnings/ (relevant gotchas, patterns, and context gaps from past features)
• Existing codebase — similar features or patterns already in use

Create the output directory: docs/discovery/{feature}/

Extract from brainstorm: problem statement, chosen approach, boundaries, scope classification, kill criteria.

Import research findings by tag:

• [CONSTRAINT] → note for boundaries
• [RISK] → seed for risk register
• [PRIOR-ART] → inform domain requirements
• [UNKNOWN] → flag for investigation during discovery

If no brainstorm exists, ask user for: feature name, problem statement, chosen approach, key constraints.

Start the glossary — create the glossary file at docs/discovery/{feature}/glossary.md with initial terms from the brainstorm. Update it throughout all phases as new terms emerge. The glossary is a standalone file (not a section in the brief) so downstream skills (PRD, technical-design) can import and extend it.

# Glossary — {Feature Name}

> Defines terms that have specific or overloaded meanings in this feature.
> Updated throughout discovery. Inherited by PRD and technical design.

## {Ambiguous Term}

| Meaning | Context | Example |
|---------|---------|---------|
| {meaning 1} | {when this meaning applies} | {concrete example} |
| {meaning 2} | {when this meaning applies} | {concrete example} |

When unqualified, "{term}" means {default meaning} in this project.

## Key Entities

| Entity | What It Represents | Not To Be Confused With |
|--------|--------------------|------------------------|
| {entity} | {definition} | {common confusion} |

## Abbreviations

| Abbreviation | Full Form |
|-------------|-----------|
| {abbrev} | {expansion} |

For simple features with few terms, a flat table is fine:

# Glossary — {Feature Name}

| Term | Definition |
|------|-----------|
| {term} | {what it means in this feature's context} |

---

Critical Sequence

Phase 1: Actor & Workflow Mapping

Step 1.1 — Identify ALL Actors:

Not just "users" — enumerate every distinct entity that interacts with this feature.

Ask: "Who or what interacts with this feature? Think about: human roles, external systems, background processes, other products."

| Actor | Type | Key Actions | Frequency |
|-------|------|-------------|-----------|
| {role} | Human / System / Automated | {what they do} | {how often} |

Types:

• Human: Named roles from the actual organisation (Tenant Admin, Inspector, Auditor)
• System: External systems (Identity Provider, Email Service, Payment Gateway)
• Automated: Background jobs, schedulers, event handlers

For each human actor, capture a Jobs-to-be-Done statement:

| Actor | Job-to-be-Done |
|-------|----------------|
| {role} | When {situation}, I want to {motivation}, so I can {outcome} |

Step 1.2 — Map Current-State Workflow:

Ask: "How does this work TODAY? Walk me through the current process step by step."

Three starting points:

• Existing process: Full workflow exists — map it with ⚠ pain point annotations
• Partial process: Workaround, manual process, or related feature exists — map what exists, note where it breaks down
• Greenfield: No current process — note this and skip to desired state

( Current Trigger )
       |
       v
+------------------+
|  Current Step 1  |  ⚠ pain point
+------------------+
       |
       v
  
   /         \
  Yes         No
  ...         ...

A current-state workflow that shows no pain points is either wrong or the feature doesn't need building.

Step 1.3 — Map Desired-State Workflow:

Create ASCII workflow diagram showing how the feature SHOULD work:

( New Trigger )
       |
       v
+------------------+
|  New Step 1      |  ✓ improvement
+------------------+

Step 1.4 — Gap Analysis:

| Gap | Current | Desired | Impact |
|-----|---------|---------|--------|
| {what changes} | {how it works now} | {how it should work} | {benefit} |

Step 1.5 — Pre-Mortem:

Ask the user NOW, before domain requirements: "Imagine this feature shipped and was considered a failure 6 months later. What are the top 3 reasons it failed?"

Capture responses as early risks. These shape which domain areas to investigate deeply in Phase 2 — a pre-mortem answer about "users couldn't figure out the UI" means UI/UX needs deep investigation, while "the integration was unreliable" means integrations need depth.

PAUSE 1: Guided Review Workflow (Pattern 5) — walk the user through actors, workflows, and risks in three focused steps.

Step 1 — Actors: Present the Actor table and JTBD statements as formatted markdown, then:

AskUserQuestion:
  question: "Are all actors accounted for? Any roles or systems missing?"
  header: "Actors"
  multiSelect: false
  options:
    - label: "Complete (Recommended)"
      description: "All human roles, systems, and automated actors are mapped."
    - label: "Missing actors"
      description: "I'll specify who's missing."
    - label: "Revise roles"
      description: "Some actors need different responsibilities or types."

If "Missing actors" or "Revise roles": collect details, update the actor table, and re-present.

Step 2 — Workflows: Present Current-State and Desired-State workflows plus Gap Analysis as formatted markdown, then:

AskUserQuestion:
  question: "Do the workflows match reality?"
  header: "Workflows"
  multiSelect: false
  options:
    - label: "Accurate (Recommended)"
      description: "Current-state and desired-state workflows are correct."
    - label: "Needs correction"
      description: "Workflows have errors — I'll explain what's wrong."
    - label: "Partial"
      description: "Some steps are missing or wrong."

If "Needs correction" or "Partial": collect details, update workflows, and re-present.

Step 3 — Risks: Present Pre-mortem risks and Gap Analysis as formatted markdown, then:

AskUserQuestion:
  question: "Do the pre-mortem risks resonate? Anything else that could cause failure?"
  header: "Risks"
  multiSelect: false
  options:
    - label: "Risks captured (Recommended)"
      description: "The failure scenarios and gaps are complete."
    - label: "Add risks"
      description: "I have additional failure scenarios."
    - label: "Reprioritize"
      description: "The risks are right but the priorities need adjusting."

If "Add risks" or "Reprioritize": collect details, update risk register, and re-present.

---

Phase 2: Domain Requirements Elicitation

Step 2.1 — Identify and Prioritize Domain Areas:

Based on the feature description, brainstorm, and pre-mortem risks, identify which domain areas need investigation. Common areas include:

• Authentication and authorisation
• Data model and persistence
• User interface and navigation
• Integrations and external systems
• Background processing and async workflows
• Reporting and analytics
• Notifications and communications
• Configuration and administration
• Multi-tenancy and isolation

Prioritize depth based on the chosen approach: Which domain areas does the selected approach most affect? Go deep on those. Go shallow (existence check only) on tangential areas.

Present to user: "This feature primarily affects {deep areas}. I'll also check {shallow areas} for completeness. Any others?"

Step 2.2 — Walk Domain Checklist:

If the project has domain reference files, load the relevant checklist.

If no reference files exist, generate questions grounded in the brainstorm boundaries and chosen approach — not from general knowledge. Every question should trace back to a specific aspect of the chosen approach, a boundary from the brainstorm, or a risk from the pre-mortem. Do not generate generic domain questions that aren't connected to this specific feature.

Batch mode (preferred): Present an entire category at once:

## {Category} — mark each item:

  [ ] Item 1: {description}
  [ ] Item 2: {description}
  [ ] Item 3: {description}

For each item, reply with:
  IN — in scope (Must Have)
  SHOULD — in scope (Should Have)
  DEF — deferred to v2+
  OUT — excluded
  Or use shortcuts: "all IN", "1-3 IN, 4-5 DEF, rest OUT"

For each IN SCOPE item, follow up with:

• What are the business rules?
• What are the constraints or limits?
• What edge cases should we handle?

Step 2.3 — Example Mapping (complex requirements):

For high-priority or complex requirements, capture concrete examples:

**Rule:** {business rule}
**Example:** {scenario that follows the rule}
**Counter-example:** {scenario that must fail}
**Question:** {open question about edge cases}

This surfaces hidden assumptions and edge cases that abstract descriptions miss.

Step 2.4 — Document Domain Requirements:

Group by domain area:

### {Domain Area}

#### Must Have
DR-{MODULE}-{DESCRIPTIVE-NAME}: {Requirement title}
  Description: {what it does}
  Business rules: {specific rules with parameters}
  Constraints: {limits, validation rules}
  Edge cases: {what happens when...}
  Evidence: {Direct / Indirect / Assumption}

#### Should Have
DR-{MODULE}-{DESCRIPTIVE-NAME}: ...

#### Deferred (v2+)
- {Requirement} — Reason: {why deferred}

#### Excluded
- {Requirement} — Reason: {why excluded}

Evidence quality:

• Direct — user interview data, support tickets, analytics
• Indirect — analogous features, competitor analysis, expert opinion
• Assumption — needs validation (flag for PRD)

PAUSE 2: Batch Review (Pattern 3) — review domain requirements area by area.

For each domain area that has requirements, present the full detail (DR IDs, descriptions, business rules, constraints, edge cases, evidence) as formatted markdown, then ask via multi-select:

AskUserQuestion:
  question: "Which {domain area} requirements need revision? (Unselected are approved)"
  header: "{Area}"       # max 12 chars
  multiSelect: true
  options:
    - label: "DR-{MODULE}-{NAME-1}"
      description: "{title} — {priority}"
    - label: "DR-{MODULE}-{NAME-2}"
      description: "{title} — {priority}"
    - label: "DR-{MODULE}-{NAME-3}"
      description: "{title} — {priority}"
    # Up to 4 DRs per batch. If more, use multiple sequential AskUserQuestion calls.

For items flagged for revision, ask follow-up questions or read the user's "Other" notes to understand what needs changing. Iterate until approved.

After all domain areas reviewed, present the summary counts:

| Domain Area | Must Have | Should Have | Deferred | Excluded |
|-------------|----------|------------|----------|----------|
| {area}      | {count}  | {count}    | {count}  | {count}  |
| Total       | {total}  | {total}    | {total}  | {total}  |

---

Phase 3: Integration & UI Analysis

Step 3.1 — UI/UX Flow Mapping (skip if no UI):

| Screen | Purpose | Entry Point | Key Actions |
|--------|---------|-------------|-------------|
| {name} | {what user does} | {how they get here} | {buttons/forms} |

ASCII navigation flow:

[Screen A] ──"action"──> [Screen B] ──"action"──> [Screen C]

Screen states for each: Loading, Populated, Empty, Error, Saving.

Step 3.2 — External System Touchpoints:

| System | Direction | Data | Protocol | Auth |
|--------|-----------|------|----------|------|
| {name} | In/Out/Both | {what data} | REST/gRPC/events | {how} |

ASCII data flow diagram (context level) showing data movement across system boundaries.

---

Phase 3b: Security, Compliance, Feasibility & Risk

Step 3b.1 — Security Analysis:

Apply STRIDE only to threat categories relevant to this feature's actual attack surface. Do not mechanically fill in all 6 categories — identify which threats are plausible given the feature's architecture and data flows, and focus on those.

For features touching auth, PII, or sensitive operations:

| Threat | Specific Risk | Mitigation |
|--------|---------------|------------|
| {applicable STRIDE category} | {concrete threat for THIS feature} | {mitigation} |

For non-security features, note "No significant security implications — {reasoning}" and move on. A single sentence explaining why is more valuable than a table of "No" entries.

Step 3b.2 — Compliance Checkpoints:

If regulatory requirements apply:

| Regulation | Requirement | How Addressed | Status |
|-----------|-------------|---------------|--------|
| {regulation} | {specific requirement} | {approach} | Addres

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dirkkok101](https://github.com/dirkkok101)
- **Source:** [dirkkok101/skills](https://github.com/dirkkok101/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.