| name | requirements |
| description | Interview-driven requirements definition. Resolves a Linear ticket, URL, or free-text request, investigates the codebase, asks only human-decidable questions in dependency-ordered rounds until the frontier is empty, and writes docs/requirements/<YYYY-MM-DD-topic>/requirements.md reviewed by belt:spec-reviewer. The result feeds /belt:feature-dev as input. |
| user-invocable | true |
| argument-hint | <linear-id | url | free-text> |
requirements
Belt pipeline for the requirements stage. Structure, gates, and done
criteria live in pipeline.yml; this file defines how to execute each
phase. By default, question rounds continue until nothing is left
silently assumed.
Phase: interview
This phase has no invoke — execute these steps directly:
1 — Resolve input
Apply the first matching rule to the argument text:
- Matches
^[A-Z]+-[0-9]+$ → run linear issue view <id> and collect
title, description, comments, and linked URLs.
- Starts with
http and contains slack.com → fetch the thread via
the slackcli skill.
- Starts with
http (other) → fetch the page via WebFetch.
- Anything else → treat the text itself as the request.
If the fetched content links to further tickets/PRs, fetch at most 2 of
them (the most directly referenced). Do not crawl deeper.
2 — Investigate the codebase
Grep/Read every identifier, module, and feature name in the resolved
input. For unfamiliar areas spanning 10+ files, dispatch
belt-agent:explorer subagents in parallel (focus: flow or patterns).
A question answerable here MUST NOT be asked to the user.
3 — Frontier interview
Ask the remaining human-decidable points (business goals, scope
boundaries, priorities, non-functional targets) via the frontier
interview per authoring-principles.md §4: map the decisions as a design
tree, each round ask the frontier — the questions whose prerequisites
are settled — in ONE AskUserQuestion call (up to 4, recommended option
first), and defer any question that depends on an answer still open
this round. Points the user explicitly defers are recorded under Open
decisions.
4 — Write the document
Create docs/requirements/<YYYY-MM-DD-topic>/requirements.md (topic
slug rules follow
plugins/belt/skills/design/references/path-convention.md) with
exactly these sections, none empty (write "(none)" only under Open
decisions):
# Requirements: <topic>
## Background — why now, current pain
## Goals — measurable outcomes
## Functional requirements — numbered; each verifiable
## Non-functional requirements — performance / security / operability targets
## Acceptance criteria — numbered; each verifiable by a command, test, or observable behavior
## Out-of-scope — explicit exclusions
## Open decisions — defaulted choices + known unknowns
Config: [requirements] rounds (belt.toml)
[requirements]
rounds = 0 # default; 0 = until the frontier is empty
- Absent belt.toml or key → 0 (no cap; nothing left silently assumed).
rounds = N (N ≥ 1) — cap at N rounds; unresolved points default to
the recommended option and are recorded under Open decisions.
Phase: review
The invoke is declared in pipeline.yml; pass the requirements.md
path as the review target. Complete the review's batched triage.
Hand the file path to /belt:feature-dev (or /belt:goal) to start
development from it.
Red flags
- Never ask a question the codebase can answer.
- Never end the interview while frontier questions remain, unless a
non-zero
[requirements] rounds cap was hit.
- Never ask a question in the same round as a question it depends on.
- Never write requirements as implementation instructions — state
outcomes, not designs.
