Requirement Seed Content

OpenSpec Guidance

This document describes the minimum necessary information to initiate an OpenSpec change proposal. A requirement seed is the starting point that triggers the specification-driven development workflow.

Problem Statement

AI agents can help generate specifications, designs, and code, but output quality depends on input quality. Common problems:

Problem	Symptom	Consequence
Vague intent	"Make login better"	Agent guesses requirements, output diverges from expectations
Missing boundaries	Undefined scope	Scope creep, over-engineering
No verification criteria	No success definition	Cannot determine completion
Ignored context	No reference to existing specs	Conflicts or duplicates with existing system

A requirement seed is the minimum viable input that solves these problems.

Requirement Seed Structure

A requirement seed is filled in two phases:

1. PM Input: Business context, filled by PM
2. Technical Elaboration: Verifiable scenarios, collaboratively filled by technical team during kickoff meeting

About Success Criteria

Poorly thought-out WHEN/THEN scenarios are worse than no scenarios at all. Non-technical PMs SHOULD NOT force themselves to write technical scenarios. Instead, they should focus on describing business context and expected outcomes. Specific verifiable scenarios SHOULD be produced collaboratively with the technical team during kickoff meetings.

Part 1: PM Input (Required)

Filled by PM, focusing on business context and business value.

1. Problem Statement (Why)

Clearly describe the problem or opportunity to be solved.

Required content (MUST):

• Who encounters the problem (role/user type)
• Under what circumstances
• Current pain points or limitations
• Why solve it now

Example:

## Problem Statement

Administrators must manually enter devices one by one when bulk adding.
Importing 100 devices takes 2 hours. This creates significant time costs
in large deployment projects and is prone to human input errors.

2. Definition of Done

Describe in plain language what the feature looks like when complete. WHEN/THEN format is NOT REQUIRED.

Required content (MUST):

• What users will be able to do
• Expected outcomes or improvements

Example:

## Definition of Done

- Administrators can upload CSV files to bulk add devices
- System displays import results including success and failure counts
- Failed rows have clear error descriptions

3. Scope Boundaries (Scope)

Explicitly define what is included and excluded.

Required content (MUST):

• In Scope
• Out of Scope

Example:

## Scope

### In Scope
- CSV file format support
- Field validation and error reporting
- Import progress display

### Out of Scope
- Excel format support (future iteration)
- Scheduled import functionality
- Auto-sync with third-party systems

4. Known Constraints (Constraints)

List business or technical constraints known to PM.

Should include (SHOULD):

• Business constraints (timeline, budget, customer requirements)
• Known technical constraints (if any)

Example:

## Known Constraints

- Must support IE11 (enterprise customer requirement)
- Must be completed before Q2

Part 2: Technical Elaboration (Filled During Kickoff)

Collaboratively filled by technical team with PM during kickoff meeting. This part transforms PM's definition of done into verifiable technical scenarios.

5. Success Criteria

Transform the definition of done into specific WHEN/THEN scenarios.

Required content (MUST):

• At least one measurable acceptance criterion
• Use WHEN/THEN format to describe expected behavior
• Cover both happy path and error handling

Example:

## Success Criteria

#### Scenario: Bulk import success
- **WHEN** administrator uploads CSV file containing 100 device records
- **THEN** system completes import within 30 seconds and displays success/failure summary

#### Scenario: Import error handling
- **WHEN** CSV file contains malformed data rows
- **THEN** system marks error rows and continues processing valid data

#### Scenario: File format validation
- **WHEN** administrator uploads a non-CSV format file
- **THEN** system displays error message and rejects processing

6. Technical Constraints

Supplement additional constraints discovered by technical team.

Should include (SHOULD):

• Existing architecture constraints
• Dependency requirements
• Performance requirements

Example:

## Technical Constraints

- Must use existing device API endpoints
- Single import limited to 1000 records (database transaction limit)
- Need to consider existing validation logic

7. Related Context

Reference existing related information.

Should include (SHOULD):

• Related existing specs (verify with openspec show)
• Related change proposals (verify with openspec list)
• External references

Example:

## Related Context

- Existing spec: `specs/device-management/spec.md`
- Related proposal: `changes/device-api-v2/` (must wait for completion)
- Reference: Vendor API documentation in `artifacts/vendor-api-notes.md`

Minimum Viable Seed

If time is constrained, here is the absolute minimum that PM MUST provide:

## Problem
[One sentence describing the problem]

## Definition of Done
- [What users will be able to do]
- [Expected outcome]

## Scope
- In: [key functionality]
- Out: [explicitly not doing]

TIP

Technical scenarios (WHEN/THEN) will be supplemented by the technical team during kickoff.

From Requirement Seed to Proposal

Once the requirement seed is ready, the flow is:

PM Input → Kickoff Meeting (Technical Elaboration) → Complete Requirement Seed
                                                      ↓
                                             proposal.md (Why, What Changes, Impact)
                                             specs/[capability]/spec.md (ADDED/MODIFIED)
                                             tasks.md (Implementation Checklist)

Transformation Example

PM Input (Before Kickoff):

## Problem
Administrators bulk adding devices must enter manually one by one, time-consuming and error-prone.

## Definition of Done
- Administrators can upload CSV to bulk create devices
- System displays import results

## Scope
- In: CSV import, error reporting
- Out: Excel, scheduling

After Kickoff Meeting:

## Success Criteria

#### Scenario: Bulk import success
- **WHEN** administrator uploads CSV file containing 100 device records
- **THEN** system completes import within 30 seconds and displays success/failure summary

#### Scenario: Import error handling
- **WHEN** CSV file contains malformed data rows
- **THEN** system marks error rows and continues processing valid data

## Technical Constraints
- Single import limited to 1000 records (database transaction limit)
- Must use existing device API endpoints

Generated proposal.md:

## Why
Administrators must manually enter devices one by one when bulk adding, creating significant time costs in large deployment projects.

## What Changes
- Add CSV file upload interface
- Add bulk device creation API endpoint
- Add import error reporting functionality

## Impact
- Affected specs: device-management
- Affected code: DeviceController, DeviceService, DeviceImportPage

Anti-Patterns

1. Solution Disguised as Requirement

Problem:

## Problem
We need a CSV upload component implemented in React.

Why it fails: This is a solution, not a problem. Constrains the design space.

Alternative: Describe the user's pain point, let the design process determine implementation.

2. Forcing Technical Scenarios

Problem:

## Success Criteria
- **WHEN** user clicks button
- **THEN** system does something

Why it fails: Non-technical PMs force themselves to write WHEN/THEN, producing vague and unverifiable scenarios. This is worse than no scenarios at all because it creates an illusion that requirements are "already defined."

Alternative: PMs SHOULD describe definition of done in plain language. Let the technical team transform it into verifiable scenarios during kickoff.

3. Unverifiable Success Criteria

Problem:

## Success Criteria
- System should be faster
- User experience should be better

Why it fails: Cannot objectively determine achievement.

Alternative: Use specific WHEN/THEN scenarios with measurable conditions.

4. Missing Exclusion Scope

Problem:

## Scope
- Bulk import functionality

Why it fails: Without explicit exclusions, scope expands infinitely.

Alternative: Explicitly list "what not to do."

Related Documents

• Change Artifacts - Managing supporting documents for requirement seeds

References

• OpenSpec - Specification-driven development framework
• Gherkin Syntax - WHEN/THEN scenario format reference