---
name: create-requirements
description: Draft a requirements document with functional and non-functional requirements from a feature brief or issue.
argument-hint: "[feature-brief or issue-url]"
---

# Create Requirements

Drafts a structured requirements document from a feature brief, user story, or GitHub issue, capturing functional requirements, non-functional requirements, constraints, and acceptance criteria.

## Prerequisites

- Apply the shared SDLC conventions in `skills/sdlc/references/shared.md`.
- If no argument is provided, use `$ISSUE_TITLE` and `$ISSUE_BODY` as the feature brief (and `$ISSUE_NUMBER` to link the feature).
- A feature brief, user story, or issue description provided in context or as `$1`
- Stakeholder goals and constraints, if known

## Steps

1. Read and understand the input (feature brief, issue, or user story).
2. Identify the goal: what problem is being solved and for whom.
3. List functional requirements: behaviors the system must exhibit.
4. List non-functional requirements: quality attributes (performance, security, availability, etc.).
5. Identify constraints: technology choices, regulatory requirements, compatibility needs.
6. Write acceptance criteria: testable conditions that confirm each requirement is met.
7. Flag any open questions where requirements are unclear or missing.
8. Derive the feature directory name `N-<slug>` following the Feature Directory Naming convention in `skills/sdlc/references/shared.md`: use the issue number as `N` when one is available, otherwise a `p`-prefixed sequence number (`p1`, `p2`, ...) marking the feature as pending a placeholder issue. Record the related issue number in the frontmatter `issue` field only when an issue exists.
9. Write the output to `.sdlc/features/N-<slug>/requirements.md`, creating the directory if it does not exist.

## Output Format

Use the template at `skills/sdlc/templates/features/requirements.md` (copied to `.sdlc/templates/features/requirements.md` by `/initialize-sdlc-directory`; use the project's customized copy if present). Write the result to the artifact path named in the steps above.

Use MoSCoW priority for functional requirements: **Must** (essential), **Should** (important), **May** (nice-to-have).

Functional requirements state *what* the system shall do; acceptance criteria state *how you verify* it is done.
Do not restate an FR as its acceptance criterion.
Write concrete, scenario-based criteria (happy path, edge cases, error states), usually several per requirement, each independently checkable and translatable into a test case.
Write each criterion as a fenced `gherkin` block tagged with its requirement ID (`@FR-N` / `@NFR-N`), so the criteria are parseable and later executable via BDD tooling (pytest-bdd, cucumber).
The Gherkin grammar is fixed: `Scenario:` with a short name, then `Given` / `When` / `Then` steps (`And` to continue a step kind); keep one action per `When`.

## Outcome

If `$OUTCOME_YAML` is set, emit your verdict there per `skills/sdlc/references/shared.md`:

| Verdict | When |
|---|---|
| `approved` | Requirements drafted (artifact written with `status: draft`, ready for `/review-requirements`) |
| `needs-info` | Issue lacks the detail needed to derive requirements |

## Example Usage

**Scenario 1: Feature brief in context**
User describes "we need users to reset their passwords via email."
Draft FR for the email flow, NFR for token expiry and security, and acceptance criteria for each step.

**Scenario 2: GitHub issue as input**
```
/create-requirements https://github.com/owner/repo/issues/42
```
Fetch the issue, extract the described behavior, and produce a requirements document.

**Scenario 3: Incomplete brief**
User gives a vague description.
List open questions and draft requirements for the parts that are clear.

## Completion Checklist

Before handing off to review, confirm:

- [ ] Each functional requirement has testable, scenario-based acceptance criteria that do not just restate the FR
- [ ] Every acceptance criterion is a fenced `gherkin` block whose tag matches its requirement ID

Self-check the draft against the [`review-requirements` checklist](../review-requirements/SKILL.md) and fix what you can, so review finds less to flag.

## Next Step

A review subagent is dispatched automatically to run `/review-requirements` to audit the document for clarity, completeness, testability, and conflicts before moving on.
Once approved, continue with `/create-existing-solutions` to survey prior art.

## Useful Commands Reference

For document-only input, no CLI commands are required.
If given an issue URL, fetch it with:

| Command | Description |
|---|---|
| `ghx issue view <url> --comments` | Fetch issue details and comments (cached) |