requirements-writing
Use when capturing what a feature must do - write testable user-story requirements that state WHAT and WHY, never HOW, with assumptions made explicit
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- requirements-writing
- category
- pm
- description
- Use when capturing what a feature must do - write testable user-story requirements that state WHAT and WHY, never HOW, with assumptions made explicit
03 SKILL.md 正文
Requirements Writing
Overview
A requirement is a promise about behavior, written so QA can later prove it and a developer can build it without guessing. The recurring failures are requirements that specify implementation (HOW), bundle several behaviors into one, or hide assumptions that later surface as defects.
Core principle: State WHAT and WHY. HOW belongs to the architect and developers.
The shape
- User story: As [persona], I want [capability], so that [outcome].
- Context: why now, what problem it solves.
- Constraints: hard limits (locale, performance, compliance) treated as given.
- Assumptions: stated explicitly — an unstated assumption becomes a defect.
Rules
- WHAT/WHY, not HOW — but field-aware.
descriptionandacceptance_criteriastate WHAT and WHY: "Users can export tasks to CSV" — not "add a/exportendpoint using library X." Endpoints, files and tables belong only intechnical_description, only once verified with code tools (get_repo_tree,codebase_search/grep_code), and only for small direct tasks you write yourself. A criterion may name an endpoint only when the API itself is the product surface (see acceptance-criteria-gwt's API-surface example) — not as a stand-in for what a user sees. - Independently testable. If a requirement contains "and", consider splitting.
- No solutioning in
description/acceptance_criteria. Naming a datastore, framework, or endpoint there is an architect/dev decision leaking in, even though the same name is correct intechnical_description.
Worked Example
❌ "Add a Redis cache to the task list endpoint so it's fast."
(HOW — names the tech; "fast" is untestable)
✅ Story: As a project member, I want the task list to load quickly,
so that I can scan my board without waiting.
Context: boards with 500+ tasks feel sluggish today.
Constraint: list renders < 500ms at p95 for 1000 tasks.
Assumption: 1000 tasks is the realistic upper bound per project.
The architect chooses caching vs indexing vs pagination — the requirement fixes only the outcome and the bound.
Common Mistakes
- Prescribing the implementation.
- "Fast/intuitive/robust" with no measurable target.
- One requirement covering three behaviors.
- Assumptions left unstated.
Red Flags
- The requirement names a library, table, or endpoint.
- You can't say how QA would prove it.
- An adjective where a number belongs.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns