Requirements List Best Practices

This document provides guidance on writing high-quality requirements for Arda’s manufacturing and supply chain operations platform. Follow these practices when creating or reviewing a Requirements List to ensure consistency, completeness, and implementation success.

Core Principles

1. Atomic and Focused

Each requirement should express one testable behavior or constraint. If a requirement contains “and” or “or” joining multiple behaviors, split it into separate requirements.

Avoid:

The system shall validate the order quantity and update the inventory and notify the supplier.

Prefer:

• FR-ORD-001: The system shall validate that order quantity is a positive integer.
• FR-ORD-002: The system shall decrement inventory by the order quantity upon order confirmation.
• FR-ORD-003: The system shall emit an OrderConfirmed event for supplier notification.

2. Unambiguous

Use precise language. Avoid subjective terms like “fast,” “easy,” “intuitive,” or “user-friendly” unless quantified.

Avoid	Prefer
”The system shall respond quickly"	"The system shall respond within 200ms at the 95th percentile"
"The form should be easy to use"	"The form shall complete with no more than 5 user actions"
"Items should be visible"	"Items shall be displayed in a paginated list of 25 per page”

3. Testable and Verifiable

Every requirement must have clear acceptance criteria that can be verified through automated tests, manual testing, or inspection.

Testability checklist:

• Can this be validated with a unit test?
• Can this be validated with an integration/API test?
• Can this be validated with a UI/E2E test?
• Can this be verified through code review or documentation inspection?

4. Traceable

Every requirement must have a unique identifier (e.g., FR-ITM-001) that allows:

• Linking to implementation code and tests
• Tracking status through the development lifecycle
• Referencing in change requests and bug reports

5. Consistent with Domain Language

Use terminology consistent with Arda’s domain model.

Term	Definition	Use Context
Item	A product managed in inventory	Inventory, Supply
ItemSupply	Supply source configuration for an Item	Procurement
Kanban Card	Signal for replenishment	Ordering
Business Affiliate	Vendor, Customer, or other partner	Procurement, Orders

Requirement Categories

Domain Modeling

The conceptual foundation that establishes the business vocabulary and entity relationships before detailed requirements are written.

Writing guidelines:

1. Start with business concepts, not code. The domain model should be understandable by non-technical stakeholders.
2. Use stereotypes to distinguish new vs. existing:
   • <<concept>>: New domain concepts being introduced
   • <<existing>>: References to existing Arda entities
   • <<external>>: External systems not managed by this feature
3. Document relationships in business terms using verb phrases: “contains”, “references”, “triggers”, “depends on”
4. Keep diagrams at analysis level — show 3-7 concepts, omit implementation details.
5. Link each <<concept>> to a corresponding entity in the service implementation requirements.

Functional Requirements (FR)

Writing guidelines:

1. Use “shall” for mandatory requirements, “should” for recommended, “may” for optional.
2. Identify the actor or system component performing the action.
3. Specify the trigger, action, and expected outcome.

Template:

When <trigger/condition>, the <system/component> shall <action> resulting in <outcome>.

Data Requirements (DR)

Writing guidelines:

1. Reference specific entity and field names using code formatting: Item.sku.
2. Specify data types, formats, and valid ranges.
3. Define cardinality (one-to-one, one-to-many, etc.).
4. Document uniqueness constraints and indexes.

Behavioral Requirements (BR)

Writing guidelines:

1. Document valid state transitions explicitly.
2. Identify pre-conditions and post-conditions.
3. List all side effects on related entities or external systems.
4. Map error conditions to AppError subclasses.

Example state transition table:

Current State	Action	Next State	Side Effects
DRAFT	Submit	SUBMITTED	Order lines locked
SUBMITTED	Confirm	CONFIRMED	Notification sent
SUBMITTED	Cancel	CANCELLED	Lines release to Queue

Integration Requirements (IR)

Writing guidelines:

1. Specify the integration direction (inbound/outbound).
2. Reference or link to API specifications or event schemas.
3. Define retry policies and failure handling.
4. Document expected latency and throughput.

UI Requirements (UIR)

Writing guidelines:

1. Use the view taxonomy: List, Detail, Form, Lookup, Action.
2. Separate what the user sees from how it looks (leave styling to design specs).
3. Document available actions and their effects.
4. Define validation feedback visible to users.

Non-Functional Requirements (NFR)

Writing guidelines:

1. Always quantify with measurable targets.
2. Specify the measurement methodology.
3. Define acceptable degradation or fallback behavior.

Review Checklist

Structural Review

• Frontmatter complete: Title, author, version, status are specified.
• Overview clarity: Feature summary explains the “what” and “why.”
• Scope defined: Inclusions and exclusions are explicit.
• Identifiers consistent: All requirements use the <TYPE>-<CODE>-<NUM> format.

Domain Modeling Review

• Concepts defined: All key domain concepts are listed with definitions.
• Relationships mapped: Entity relationships are documented with cardinality.
• Diagram included: Conceptual PlantUML diagram is present.
• Business rules listed: Key business rules are captured.
• Existing entities referenced: Links to existing Arda entities where applicable.

Content Review

• Atomicity: Each requirement expresses one testable behavior.
• Unambiguous language: No subjective or vague terms.
• Complete acceptance criteria: Every FR has at least one measurable criterion.
• Dependencies mapped: Related requirements reference each other.
• Error handling specified: Failure conditions map to AppError types.
• Domain terminology: Uses canonical terms from technical documentation.

Completeness Review

• Happy path covered: Normal operation requirements are defined.
• Edge cases addressed: Boundary conditions and exceptional flows are specified.
• Data lifecycle: Create, read, update, delete behaviors are documented.
• Integration points: All external system interactions are specified.
• Open questions tracked: Unresolved items are captured with owners.

Traceability Review

• Testable: Each requirement can be validated with a specific test type.
• Prioritized: Requirements are classified as Must/Should/Could/Won’t Have.
• Status tracked: Current status is accurate.
• Version history: Changes are documented.

Priority Classification (MoSCoW)

Priority	Definition	Guidance
Must Have	Critical for release. System is unusable without it.	MVP scope. Non-negotiable.
Should Have	Important but workarounds exist.	High-value additions. Defer only under severe constraints.
Could Have	Desirable enhancement.	Nice-to-have. Include if time permits.
Won’t Have	Explicitly out of scope for this release.	Document to prevent scope creep. May be future work.

Common Anti-Patterns

The Vague Requirement

“The system should be fast and reliable.”

Fix: Quantify with specific metrics.

“The API shall respond within 200ms at the 95th percentile under load of 100 concurrent requests.”

The Implementation Specification

“The system shall use PostgreSQL with jsonb columns and GIN indexes.”

Fix: Focus on what, not how. Implementation details belong in design documents.

The Compound Requirement

“The system shall validate the form, save the data, and redirect to the confirmation page.”

Fix: Split into atomic requirements.

The Missing Error Path

“The system shall create an ItemSupply when requested.”

Fix: Document failure conditions explicitly.

The Orphan Requirement

A requirement without context or rationale that makes reviewers ask “why?”

Fix: Always include a rationale explaining the business value or technical necessity.

Integration with Development Workflow

Requirements connect to the development process through:

1. Specification Documents: Link requirements to detailed specifications for implementation guidance.
2. GitHub Issues: Create issues referencing requirement IDs for tracking.
3. Test Cases: Reference requirement IDs in test names and comments.
4. Code Comments: Annotate implementation with requirement IDs for traceability.

Example test name:

@Test
fun `FR-ITM-005 - Item creation with duplicate SKU fails with validation error`() { ... }