git:20260827.1dfdffc to git:20260828.3fc9197

5 added, 0 removed. Audit A to A.

---

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.

+ When the feature has a CLI surface, it delegates to `/create-cli-design` so the commands and options are designed alongside the requirements they serve.

## 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.

+ 10. Detect a CLI surface: when the feature adds or changes CLI commands or options, load the `create-cli-design` skill with the `skill` tool and run it to design the interface from the requirements just drafted, producing `.sdlc/features/N-<slug>/cli-design.md`.

## 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 |

+ In the same emission, list the artifact under `artifacts:` (`.sdlc/features/N-<slug>/requirements.md`, plus `.sdlc/features/N-<slug>/cli-design.md` when step 10 delegated to `create-cli-design`); omit the key when nothing was written (needs-info).

## 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.

+ When the feature has a CLI surface and step 10 has not run yet, `/create-cli-design` runs first so the review covers the interface too.

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) |