# Discover Requirements > Turn a refined product or engineering idea into decision-complete behavioral, business, data, security, integration, and non-functional requirements before design and delivery planning. - Skill: `singleton-sd/discover-requirements` (Agent Skill) - Install (CLI): `npx skillmds@latest add singleton-sd/discover-requirements` - Raw SKILL.md: https://api.skillmd.com/api/skills/singleton-sd/discover-requirements/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: singleton-sd (https://skillmd.com/u/singleton-sd) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/singleton-sd/discover-requirements --- # Discover Requirements Use this skill after an idea has been shaped enough that the problem, target users, desired outcome, and broad MVP are understood, but the expected behavior is not yet precise enough to design or implement safely. Normally consume the output of `refine-idea`. If the input is still a raw or contradictory idea, use `refine-idea` first rather than inventing requirements for an unstable premise. ## Goal Produce a **Requirements Discovery Brief** that is complete enough for design/architecture work and later `idea-to-delivery` / `backlog-refinement` without forcing implementation agents to make product decisions. Requirements describe **what must be true and how the capability behaves**. Avoid prematurely prescribing code structure, libraries, database schemas, or deployment details unless an existing architecture constraint makes them mandatory. ## Discovery method Be conversational and risk-driven. Resolve the most consequential ambiguity first rather than asking every possible question. Use available conversation, repository, Architecture Doc, existing GitHub issues, and current system behavior before asking the user for information that can be discovered directly. Typical discovery order: 1. Confirm actors and scope. 2. Walk the primary happy-path scenario end to end. 3. Identify alternate paths and failure states. 4. Extract business rules and decision logic. 5. Define permissions, tenant boundaries, and visibility. 6. Define data captured, retained, exposed, and audited. 7. Identify integrations and external dependencies. 8. Capture relevant non-functional requirements. 9. Define lifecycle/status behavior when applicable. 10. Define observable acceptance outcomes and unresolved questions. Do not manufacture precision. Record assumptions explicitly when the user has not decided something. ## Requirement categories Cover only categories relevant to the feature, but deliberately check each one. ### Actors and permissions Identify: - primary user/actor; - secondary/support/admin/system actors; - anonymous versus authenticated behavior; - tenant boundaries; - ownership and visibility rules; - create/read/update/delete/execute permissions; - privileged/support operations and required auditability. ### User and system scenarios Capture: - happy path; - empty/first-use state; - invalid input; - authorization denial; - dependency/integration failure; - retry/idempotency behavior where relevant; - partial failure; - cancellation/abandonment; - duplicate actions; - concurrent edits/actions when meaningful; - mobile/responsive/accessibility considerations for UI features. ### Business rules Write rules as explicit decisions, for example: ```text BR-01: A tenant administrator may configure X for users in their tenant. BR-02: A support agent must not see Y unless permission Z is granted. ``` Prefer deterministic language: MUST / MUST NOT / SHOULD when appropriate. ### Data and lifecycle Identify: - data required to perform the capability; - source of each important data element; - fields the user can edit versus system-generated values; - lifecycle/status transitions; - retention/deletion expectations; - PII, secrets, credentials, or sensitive technical data; - audit/history requirements; - search/filter/sort/export needs when relevant. Do not invent database tables or schemas during requirements discovery. ### Integrations and events Identify: - upstream/downstream systems; - synchronous versus asynchronous behavior when this is already architecturally constrained; - external provider failure expectations; - inbound/outbound notifications; - domain events or jobs that are behaviorally required; - correlation/tracing needs for supportable workflows. for the target repository, preserve pillar boundaries and architecture decisions already documented in `AGENTS.md` and the Architecture Doc. ### Non-functional requirements Consider only when material: - security and least privilege; - privacy / PII handling; - auditability; - accessibility; - performance and latency expectations; - scale/volume assumptions; - reliability, retry, idempotency, and recovery; - observability and correlation IDs; - browser/device support; - localization/timezone/date behavior; - configurability by tenant/user; - cost constraints; - backward compatibility / migration; - supportability and diagnostics. Avoid fake numerical targets. If a target matters but is unknown, mark it as an open decision. ## Acceptance outcomes Requirements discovery should result in observable outcomes, not detailed test scripts. Use IDs when the capability is substantial: ```text FR-01: ... FR-02: ... NFR-01: ... BR-01: ... ``` Acceptance outcomes should be specific enough that a later design/ticket can turn them into testable acceptance criteria. ## Open questions Separate questions into: - **Blocking** — must be resolved before design or delivery planning; - **Non-blocking** — safe for implementation/design to decide within stated constraints; - **Validation** — requires a spike, prototype, user research, vendor check, or architecture investigation. Never hide a blocking decision inside an assumption. ## Readiness states Finish with one recommendation: ### READY FOR DESIGN / DELIVERY PLANNING Use when behavior, rules, actors, important edge cases, relevant NFRs, and dependencies are sufficiently defined and no blocking product questions remain. Next step depends on the work: - if UX/UI or architecture **solution** design is still needed, stop and ask the user — do not invent screens, schemas, or infra, and do not call a design skill (for example design/product-design); - use `backlog-refinement` for a single existing GitHub issue; - use `idea-to-delivery` for multi-issue feature planning and GitHub execution slicing. ### NEEDS PRODUCT DECISION Use when a blocking behavioral/business decision remains. Ask the smallest set of questions needed to resolve it. If the blocker reveals the underlying idea itself is unclear, hand back to `refine-idea`. ### NEEDS VALIDATION / SPIKE Use when feasibility or an external dependency cannot be safely assumed. Define the exact question the spike/research must answer and the evidence required. ## Requirements Discovery Brief Use this structure as the normal output: ```text Capability Source idea Actors - : In scope - Out of scope - Primary flow 1. 2. Alternate / failure flows - -> Functional requirements - FR-01: Business rules - BR-01: Permissions and tenant boundaries - Data and lifecycle - Integrations / events - Non-functional requirements - NFR-01: Acceptance outcomes - Dependencies - Assumptions - Open questions Blocking: - Non-blocking: - Validation: - Readiness READY FOR DESIGN / DELIVERY PLANNING | NEEDS PRODUCT DECISION | NEEDS VALIDATION / SPIKE Recommended next step ``` Keep the document proportional. A small UI behavior may need only a short brief; cross-cutting support/auth/billing features deserve more detail. ## Persisting the brief Resolve `engineeringHost` from consumer `.skills/profile` or [`../../config/tracker-profiles/`](../../config/tracker-profiles/README.md) (infer from `git remote` when missing). Host issues own engineering discovery — there is no separate pre-host "discovery" queue. When the target repo is known, when the user asks to store the brief: - persist unresolved requirements/discovery as a **host issue** (open a new one, or update the issue the brief originated from); - validation/spike work stays as an open, not-yet-agent-ready issue until its question is answered — do not mark it agent-ready; - do not create delivery-slice issues (`idea-to-delivery` / `backlog-refinement` territory) while blocking requirements remain; - call out a standalone manual validation/setup step explicitly on the relevant issue only when it is a real operational action, not an open question; - browsing/refinement is not claiming. Create: ```bash # GitHub (engineeringHost: github) gh issue create --title "..." --body "..." # GitLab (engineeringHost: gitlab) glab issue create --title "..." --description "..." ``` ## Handoff contract When READY FOR DESIGN / DELIVERY PLANNING: - preserve requirement IDs and explicit non-goals in downstream design/tickets; - downstream skills may add implementation direction but must not silently change product requirements; - if design discovers a conflict requiring a product decision, return to this skill and update the requirements brief. Do not duplicate the responsibilities of: - `refine-idea` — validating and shaping the product idea itself; - design skills — deciding UX/UI or technical solution structure; - `backlog-refinement` — converting known work into an agent-ready host issue; - `idea-to-delivery` — creating parent/tracking issues, independently mergeable delivery-slice issues, dependencies, and parallel lanes.