Write a good requirement

This page shows you what a requirement in Spectrace is made of and how to write one that acceptance criteria, tests, and PR verification can build on.

Prerequisites

• A project you can write to. Members with the viewer role cannot create requirements.

The fields

A requirement is one row in a project. In the web app you create one from Add requirement → Quick add on the project board or list, which asks for:

Quick add stores the type as Functional and leaves tags empty. Set a different type (Functional, Non-functional, Technical, UI / UX, Security, Performance, Integration) or tags through the import wizard, through the spectrace_requirements_create and spectrace_requirements_update MCP tools, or on the plain form at /projects/<project-slug>/requirements/new, which takes title, description, type, priority (its Critical option is labelled "Urgent"), and tags.

On the requirement page you edit the title, the description, and the priority in place, and fill in the structured parts:

• User story — As a … / I want … / so that …. Add or edit it in the User story card.
• Acceptance criteria — the list of checks a change must satisfy. See Acceptance criteria.
• Subtasks — a checklist of implementation steps, each todo, in_progress, or done.
• Assignees — a developer and a QA reviewer. See Contributors and assignment.
• Workflow stage — Backlog, In Dev, In Review, or Done. See Workflow stages and approvals.

A requirement also stores an effort size (xs to xl), dependencies on other requirements, and references (links, mockups, documents). The import wizard fills in effort and dependencies from extraction; the requirement page has no editor for these three fields today.

The reference number

Every requirement gets a reference number when it is inserted, in the form <project key>-<sequence>, for example sss-012. The project key is the project's Short key ("Project Key" in project settings), lower-cased. When a project has no key, Spectrace uses the first three letters of the project name.

The sequence counts up per project and is padded to three digits. Numbers are unique within a project, not across projects. Deleting a requirement leaves a gap unless it held the highest number, in which case the next requirement reuses that number.

The reference number is how the rest of Spectrace addresses a requirement: it is the URL segment of the requirement page, the argument to Slack commands such as /spectrace status sss-012, and the token the PR verifier looks for in a branch name, pull-request title, or pull-request body. See Link a PR to a requirement.

Write for the verifier

When a pull request is linked to a requirement, the verifier reads the title, the description, the user story, each acceptance criterion, and any test cases, then grades each criterion against the diff. A criterion ends up satisfied, partial, not_found, contradicted, or unclear. The description and user story give the model context; the acceptance criteria are what it grades.

That shapes how to write the top of the requirement:

• Put the observable behaviour in the title. A title such as "Improve auth" gives the verifier nothing to look for.
• Use the description for the why and the constraints (rate limits, formats, error copy). Keep opinions about implementation out of it unless the implementation is the requirement.
• Fill in the user story when the audience matters. As a locked-out user tells the verifier which code path is in scope.
• Move every testable statement into an acceptance criterion. Statements that stay in the description are context, not checks.

Vague words hurt in a specific way: a criterion the model cannot map to code lands as unclear, and the review comment lists it as outstanding. "Fast" becomes verifiable when it says "responds within 300 ms at p95"; "secure" becomes verifiable when it says "rejects a reused magic link with HTTP 410".

What AI does with vague input

Two AI steps help with under-specified input, and it matters where each one lives.

Import wizard clarifier. When you import from text, documents, or a URL, the wizard's Clarify step asks up to nine questions before extraction (audience, edge cases, constraints). Your answers are passed to the extractor. If you skip a question, it is left out and the extractor works from the source text alone. See Import requirements.

Ambiguity analysis. The spectrace_requirements_analyze_ambiguity MCP tool scores a requirement's text from 0 to 1 and returns a list of { text, reason, suggestion } issues, and stores the result on the requirement. It is available to connected AI agents only; the web requirement page has no ambiguity panel today. See Tool reference.

The Generate now toggle on the plain /requirements/new form does not start any AI generation, whatever its label says. To generate a user story, acceptance criteria, subtasks, or tests from a title and description, use Add requirement → Quick add on the project board or list, which lets you pick which artefacts to generate in the background.

What done looks like

You have a requirement with a reference number, a title that names a behaviour, a description with the constraints, and at least one acceptance criterion. From there Spectrace can generate Gherkin test cases and verify pull requests against it.

If you save a requirement with no acceptance criteria, it still exists and can move through every workflow stage, because the stage gate only checks the criteria that exist. What you lose: the Generate button on the tests card says "Add acceptance criteria first", test generation skips the requirement, and a linked pull request has nothing to be graded against.

Related

• Acceptance criteria
• Import requirements
• Workflow stages and approvals
• How PR verification works
• Core concepts