Requirements Engineering

Requirements Engineering

Why this skill exists. Good architecture is a byproduct of good requirements — you do not design it directly, you clarify the requirements until the modules, boundaries, and contracts they imply become obvious. This skill produces the WHAT (the specification and the contracts to honor); the ios-architecture-expert skill turns it into the HOW. Every artifact here starts from a conversation that eliminates assumptions — see references/clarifying-questions.md.

Agent Behavior Contract

When this skill is active, follow these rules strictly:

1. Include the artifacts the feature warrants — the full set (BDD Narrative, Acceptance Criteria, Use Cases, Model Specs, Payload Contract, Flowchart, Architecture Diagram) for a non-trivial networked feature, but omit ones that don't apply: an online-only feature needs no offline narrative, cache use case, or Cancel course; a feature reusing a model needs no new Model Spec. The architecture diagram is one shared app-level graph, not one per feature.
2. Never accept vague requirements without asking clarifying questions first — Who are the user types? What happens offline? What are the error cases?
3. Use domain-specific language consistently across all artifacts — if the domain says "image feed" not "feed items", use "image feed" everywhere.
4. Every use case must have a Data section listing ALL inputs, a Primary course, at least one Error course, and a Cancel course where applicable.
5. Model Specs must use Property/Type tables — not prose descriptions.
6. Payload Contracts must show HTTP method, path, status code, and example JSON — including optional fields demonstrated by omission.
7. Requirements are living specifications — iterate and refine as understanding evolves, do not treat as one-time documents.

Requirements Diagnostic Table

Gotchas

• BDD's value is the conversation, not the Gherkin. If you wrote Given/When/Then scenarios without asking a single clarifying question, you almost certainly encoded your own assumptions. Crush the assumptions first — What is a "feed"? What does "load" mean? From where? See references/clarifying-questions.md.
• Dependency-arrow notation carries two facts, not one. Head fill = "is-a/conforms-to" (open) vs. "depends-on" (filled); line style on a filled head = strong (solid, a stored let) vs. weak (dashed, a method parameter). Four meanings, easy to get wrong — always include a legend. See references/diagrams.md.
• A query that mutates state is the smell. Load is a side-effect-free query; deleting the cache is a command — split them (CQS). The case study briefly put a delete on the Load path, then extracted Validate Cache. See references/use-cases.md.
• Collection-empty ≠ single-resource-empty. An empty/expired collection cache is an empty success ("delivers no images"); an empty single keyed resource (image data by URL) is a not-found error.
• Optionality is shown by omission, not prose. In payload-contract JSON, include the optional field in some example items and omit it from others — never write "(optional)" only in prose or use null.
• The canonical domain term is the domain experts' word, not the team's preference (ubiquitous language). "Images" replaced "Items" because that's what the experts call them.
• Artifact count follows behavior, not a quota. Don't pad an online-only feature with offline narratives and Cancel courses to "complete the seven".

Feature Specification Artifacts

A feature draws from this catalog of artifacts — use the ones its behavior warrants (the full set for a non-trivial networked feature; fewer for online-only or model-reusing features):

The 6-Step Process

1. Identify — Recognize vague requirements ("susceptible to personal interpretation")
2. Clarify — Run the lousy-ticket teardown; ask Who / What / Where / When / Why / How to eliminate assumptions -> references/clarifying-questions.md
3. Specify BDD — Write narratives and acceptance criteria -> references/bdd-narratives.md
4. Define Use Cases — Write procedural steps with cancel courses -> references/use-cases.md
5. Model & Contract — Create model specs and payload contracts -> references/model-specs-and-contracts.md
6. Visualize & Document — Generate diagrams, compile feature spec -> references/diagrams.md, references/feature-specification-workflow.md

End-to-end guide: feature-specification-workflow.md

Guardrails

• Do not accept "As a user, I want X, So I can X" — always specify concrete user types
• Do not write use cases without a Data section listing all inputs
• Do not omit Cancel courses for operations involving network or async work
• Do not mix domain terms — if BDD says "image feed", use case must say "image feed", not "feed items"
• Do not create architecture diagrams without showing module dependencies and protocol boundaries
• Do not treat requirements as a one-time document — they evolve with the code
• Do not include implementation details in BDD narratives — keep them behavioral
• Do not describe models as prose — use Property/Type tables

Verification Checklist

When reviewing a feature specification:

1. Every BDD narrative specifies a concrete user type (not just "user")
2. Every acceptance criterion has Given/When/Then with specific preconditions
3. Every use case has Data, Primary course, and at least one Error course
4. Cancel courses exist for all cancellable operations
5. Model Specs have Property/Type tables for every domain entity
6. Payload Contract shows HTTP method, path, status code, and example JSON
7. Flowchart includes error/fallback branches (not just happy path)
8. Architecture diagram shows module dependencies (not generic boxes)
9. Domain terminology is consistent across every artifact
10. Feature specification is self-contained (could be understood independently)

Reference Router

Open the smallest reference that matches the question:

• Clarification
  • clarifying-questions.md — lousy-ticket teardown, question bank, answer-to-artifact mapping, BDD-as-conversation
• Narratives & Criteria
  • bdd-narratives.md — BDD stories, user narratives, acceptance criteria, scenario patterns
• System Behavior
  • use-cases.md — use case structure, courses, separation of concerns
• Data Contracts
  • model-specs-and-contracts.md — model specs, payload contracts, JSON examples
• Visual Communication
  • diagrams.md — flowcharts, architecture, sequence, state diagrams
• Domain Consistency
  • domain-language.md — terminology alignment, renaming patterns
• Workflow
  • feature-specification-workflow.md — end-to-end feature spec, traceability, prototyping to validate a requirement
• Worked example
  • worked-example.md — a complete, assembled requirements set for a two-feature system: every artifact type in context. Read it when you need to see the target output at full fidelity, not one format at a time.