Requirements capture the intent for a product. They define what the product must do and why it exists. When requirements are clear and thorough, everyone working on the product shares the same understanding of what they're building and why.
Software Factory organizes requirements into two types: Product Overview Documents and Feature Requirements Documents.
Product Overview Documents capture the high-level *why* and *what* for the entire product. The *why* is the business motivation: the problems being solved, the KPIs not being met, the North Star goals the business is pursuing. The *what* is the product description: what the product is and how its parts fit together. These documents give anyone—executive, product manager, or engineer—the context they need before looking at specific features.
Feature Requirements Documents (FRDs) capture the localized *why* and *what* for individual features. The *why* is the user story: as a user, I need this capability so I can accomplish a specific goal. The *what* is the acceptance criteria: the specific behaviors the system must exhibit. FRDs are what engineers use to build the product. They can be nested: a parent FRD can contain child FRDs when a feature is large enough to break into sub-features.
Every Software Factory project is initialized with a set of default Product Overview Documents. Users can create additional Product Overview Documents as needed.
Business Problem — The pain points the product addresses and why they matter.
Current State — The status quo the product improves upon.
Personas — The users, their goals, and what success looks like for them.
Product Description — What the product is and how its parts fit together.
Success Metrics — The key metrics that will be used to measure the success of the product.
Technical Requirements — The technical constraints and requirements that the product must meet.
Write in plain language. These documents should be understandable by anyone in the company.
Focus on motivation. A Business Problem document should make the reader feel why this problem matters. A Personas document should make the users feel real.
Software Factory projects are not initialized with any default Feature Requirements Documents. Users can use the "Getting Started" tool to work with the agent to create the initial set of features. Users can calibrate how many features to create in the first pass depending on the desire to work in an agile manner or to work in a more waterfall manner.
When a Feature Requirements Document is created, it uses a default template with an opinionated structure. The template is defined in Project Settings > Refinery > Feature Requirements Template.
Feature Requirements Documents follow a consistent structure with three sections: Overview, Terminology, and Requirements.
Write 1–2 narrative paragraphs explaining what the feature does and why users need it. A stakeholder should understand the feature's purpose in under a minute. Focus on the problem being solved and the value delivered—not mechanisms or implementation.
Example: The Checkout module handles the purchase flow from cart review through payment confirmation. Customers need a clear path from deciding to buy to completing their purchase, with immediate feedback if something goes wrong. This module integrates with the product catalog for pricing and inventory validation, and with the notification system to confirm successful orders.
Define terms specific to this feature that might be ambiguous. Use brief, precise definitions. Only include terms directly relevant to understanding this feature—do not define obvious industry-standard terms.
Example:
Cart: The working collection of items a customer intends to purchase.
Order: A finalized purchase record created when checkout completes.
Fulfillment Hold: A temporary block on order processing pending manual review.
Each requirement represents one cohesive capability and must be independently testable. A requirement has three parts:
ID and title: `REQ-[PREFIX]-NNN: Requirement Name` — a unique identifier with a short prefix derived from the feature name (e.g., `CHK` for "Checkout") and a zero-padded sequence number. Child features append their own suffix (e.g., `REQ-AUTH-PR-001` for Password Reset under Auth).
User story: A single sentence in the format *As a [role], I want to [action], so that I can [outcome].*
Acceptance criteria: One or more criteria using format `AC-[PREFIX]-NNN.N`. Each criterion begins with "When [condition], the system shall [behavior]."
Use shall for mandatory behavior, should for recommended, and may for optional.
Requirements should be:
User-centered — Describe what users need, not how the system is built internally.
Testable — Every acceptance criterion should be clear enough to write a test for.
Atomic — Each acceptance criterion covers one behavior. Split compound behaviors into separate criteria.
Good Example:
REQ-CHK-003: Payment Confirmation
User Story: As a customer, I want to receive confirmation after my payment is processed, so that I can know my order was placed successfully.
Acceptance Criteria:
AC-CHK-003.1: When payment processing succeeds, the system shall display a confirmation page with the order number and estimated delivery date.
AC-CHK-003.2: When payment processing fails, the system shall return the user to the payment form with an error message describing the failure reason.
AC-CHK-003.3: When the user navigates away during processing, the system shall complete the transaction and display the confirmation on their next visit.
Bad Example:
REQ-CHK-003: Payment Confirmation
User Story: As a user, I want payment to work.
Acceptance Criteria:
AC-CHK-003.1: The system should show a message.
AC-CHK-003.2: Errors should be handled appropriately.
This is bad because the user story has no outcome and uses a generic role. The acceptance criteria are untestable—"show a message" and "handled appropriately" don't describe specific behaviors.
Large features can be broken into sub-features. A parent feature delivers complete value on its own. A child feature extends that value but is not required for the parent to function. The parent works without the child; the child is meaningless without the parent.
Example: "Search" finds items by keyword—complete on its own. "Search Filters" adds faceted filtering. Search works without filters; filters need search.
When to Split, Merge, or Nest:
Split into separate features when each passes the feature unit definition independently, or when different roles own different parts.
Keep in one feature / Merge features when requirements break without each other, they complete one task together, or they're describable in one sentence.
Create a nested child feature when the parent already delivers value, the child enhances but is not required, and the child is meaningless without the parent.
Example:
Parent Feature: User Management
User Management lets administrators create, view, edit, and deactivate user accounts. Admins can reset passwords and manage basic profile information. This core functionality delivers value on its own—organizations can manage their users without any of the child features below.
Sub-Features
User Roles: Lets admins assign roles to control what users can access. User management works without roles; roles are meaningless without users.
User Groups: Lets admins organize users into groups for bulk operations. User management works without groups; groups are meaningless without users.
User Audit Log: Tracks changes to user records for compliance reporting. User management works without audit logs; audit logs are meaningless without users.
