Requirements Engineer

Requirements Engineer

Turn the approved concept into structured Product Requirements Documents. Focus on what the feature must do, not how it will be implemented.

Never write code or technical architecture in this skill. Architecture and implementation happen later in the chain.

PROJ vs. PRD

• PROJ-X is the initiative or feature theme, for example PROJ-1-auth. Brainstorming assigns it and creates the folder.
• PRD-Y is one testable, deployable feature inside the PROJ. Number PRDs from 1 within each PROJ.

Feature Granularity

Each PRD should describe one testable, deployable unit.

Split into a separate PRD when:

1. It can be tested independently.
2. It can be deployed independently.
3. It serves a different user role.
4. It is a separate UI component, screen, API capability, or workflow.

Prefer several focused files inside the same PROJ over one large PRD:

specs/PROJ-1-auth/2_PRDs/
  PROJ-1-PRD-1-user-signup.md
  PROJ-1-PRD-2-login.md
  PROJ-1-PRD-3-password-reset.md

Document dependencies between PRDs, including cross-PROJ dependencies, inside each PRD.

Delivery Track

Detect how this PROJ will be delivered before writing PRDs. The concept's Handoff Readiness section (written by concept-sync) sets Delivery track; if it is absent, infer from context and confirm with the user.

• Full chain (in-repo build): Steps 3–7 follow in this repo. Write PRDs normally, including the UI Implementation Notes section with component reuse and file-path hints.
• Discovery / Linear handoff: There is no codebase here. You are producing a developer handoff that goes to Linear (https://linear.app). The developer who picks it up owns architecture and implementation. In this mode:
  • Write the same PRDs (user stories, acceptance criteria, edge cases) — these are the contract.
  • Do not invent in-repo file paths or component locations. Replace UI Implementation Notes component-path hints with mockup references and design intent only.
  • Do not recommend architecture (3); the chain stops at Step 2 for this PROJ.

Decomposed PROJ Handling

Requirements run one PROJ at a time. If the concept contains Decomposition Context:

• Write PRDs only for the current PROJ.
• Do not absorb sibling PROJ scope into user stories.
• Document cross-PROJ dependencies explicitly under ## Dependencies.
• If a sibling PROJ is a blocker, do not write stories that assume its behavior except as a dependency or precondition.
• A shared design language from a sibling PROJ may be referenced, but it does not expand the current product scope.

Input

Read these inputs:

1. Concept: specs/PROJ-<X>-<theme>/1_brainstorm/PROJ-<X>-concept.md
2. UI mockups: specs/PROJ-<X>-<theme>/1d_mockups/*.html
3. Sitemap: specs/PROJ-<X>-<theme>/1d_mockups/sitemap.html
4. UI implementation handoff: specs/PROJ-<X>-<theme>/1d_mockups/implementation-handoff.md
5. Optional Visual Companion decision: specs/PROJ-<X>-<theme>/1b_visual-companion/layout-decision.md
6. Optional design language: specs/PROJ-<X>-<theme>/1c_design/design-language.md
7. Optional shared sibling design language referenced by the concept, layout decision, or mockup handoff

For UI features, mockups and implementation-handoff.md are required inputs. They define screens, flows, states, component reuse, new component candidates, design tokens, the interaction contract, and implementation tolerance.

If a UI feature has no mockups, stop and run visual-companion -> optional frontend-design -> ui-mockup first. Pure backend/API features may proceed directly from the concept.

Workflow

1. Check Existing PRDs

Before creating a PRD, inspect specs/PROJ-<X>-<theme>/2_PRDs/.

Use the next available PRD-Y number inside the PROJ, starting at 1 and avoiding gaps where practical. Do not duplicate existing PRDs.

2. Understand The Feature

For UI features, read mockups and sitemap first:

• Which screens exist?
• Which user flows are clickable or linked?
• Which states are visible?
• Which assumptions or source references are marked?
• Which Project Mode applies?
• Which components and tokens must be reused?
• Which new component candidates did the user accept?
• Which interactions are implementation contract vs. demo-only?

Ask the user focused questions only when needed:

• Who are the primary users?
• What is MVP scope vs. nice-to-have?
• What constraints exist?

Ask one question at a time and follow up based on the answer.

3. Clarify Edge Cases

Identify and prioritize edge cases:

• Unexpected inputs
• Empty or missing data
• Permission and role boundaries
• Failure and retry behavior
• Security-relevant scenarios
• Limits, quotas, and performance-sensitive paths

4. Write PRDs

Save PRDs under:

specs/PROJ-<X>-<theme>/2_PRDs/PROJ-<X>-PRD-<Y>-<short-description>.md

Use kebab-case for <short-description>.

Template:

# PROJ-<X>-PRD-<Y>: Feature Name

## Status: Planned

## User Stories

### US-1: As a [user type], I want [action] so that [goal]
**Given** [starting condition]
**When** [action]
**Then** [expected result]
**And** [additional expected result, if needed]

**Acceptance Criteria:**
- [ ] AC-1: Testable criterion derived from the Then/And clauses
- [ ] AC-2: Another testable criterion for this story

### US-2: As a [user type], I want ...
**Given** ...
**When** ...
**Then** ...

**Acceptance Criteria:**
- [ ] AC-3: ...

## Edge Cases
- What happens when...?

## Dependencies
- Requires: PROJ-<X>-PRD-<Y>
- Cross-PROJ dependency: PROJ-<A>-PRD-<B>

## Technical Requirements
- Performance, security, compatibility, or operational constraints.

## UI Implementation Notes
- Project mode:
- Reuse:
- New component candidates:
- Design tokens:
- Interaction contract:
- Implementation tolerance:

Each user story owns its own acceptance criteria. Do not create one global acceptance-criteria section. Derive ACs directly from the story's Given/When/Then/And clauses and make them testable.

5. Review With The User And Opposite Provider

Ask the user to review the PRDs. If changes are requested, update the PRDs and present them again.

After incorporating the user's first review, run the required opposite-provider cross-review before handoff. Do not ask the user to copy PRDs into another model manually. Review the complete PRD set; omitting one PRD makes dependency and consistency findings unreliable.

Build the ground-truth list from files that exist. Always include the concept. For UI work, add the compact UI contracts (implementation-handoff.md, sitemap.html, layout decision, and design language) rather than every mockup HTML file unless a disputed detail requires it:

BASE="specs/PROJ-<X>-<theme>"
GROUND_TRUTH=("$BASE/1_brainstorm/PROJ-<X>-concept.md")
for candidate in \
  "$BASE/1d_mockups/implementation-handoff.md" \
  "$BASE/1d_mockups/sitemap.html" \
  "$BASE/1b_visual-companion/layout-decision.md" \
  "$BASE/1c_design/design-language.md"; do
  [ ! -f "$candidate" ] || GROUND_TRUTH+=("$candidate")
done
bash scripts/cross-review.sh requirements <X> <theme> \
  --artifacts "$BASE"/2_PRDs/*.md \
  --ground-truth "${GROUND_TRUTH[@]}" \
  --author-provider <current-writer> --round 1

The review must test concept/UI traceability, missing or contradictory stories, acceptance-criteria testability, edge and permission behavior, cross-PRD consistency, scope drift, and premature architecture.

Follow cross-review's automatic loop: reconcile findings of any severity within approved scope and run --round 2, then --round 3 while findings remain. Stop early with no findings; exit 0 may still contain Medium/Low. Ask the user only for unresolved product decisions. After round 3, remaining Critical/High findings block handoff; report or defer remaining Medium/Low. Exit 1 means the review did not run: fix infrastructure before handoff.

Three rounds is the automatic maximum; additional manually requested rounds have no limit. The review is read-only and does not replace final product-owner approval.

6. Handoff

• Full chain: recommend architecture (3) for PROJ-level technical design. For UI features, the mockups and implementation handoff remain visual references for architecture.
• Discovery / Linear handoff: do not recommend architecture. If the work goes to people outside this repo (an external UI/UX expert, an external dev team) and a single standalone deliverable is wanted, recommend handoff-package (2b) to assemble a self-contained, zippable package. The chain ends here for this PROJ.

Completion Checklist

• Existing PRDs checked for duplicates and next PRD number
• Necessary user questions answered
• UI mockups and sitemap read for UI features
• implementation-handoff.md read for UI features
• At least 3-5 user stories defined where feature size warrants it
• Every user story has its own acceptance criteria
• At least 3-5 edge cases documented where feature size warrants it
• PRD ID assigned and file saved in the correct folder
• Delivery track determined (full chain vs. discovery / Linear handoff)
• Required opposite-provider PRD cross-review completed
• No unresolved Critical/High cross-review finding remains
• User reviewed and approved the PRD

Git Commit Format

feat(PROJ-<X>-PRD-<Y>): Add PRD for <feature-name>

Git is optional on the discovery track. If the workspace is not a git repository, skip the commit; the PRD files are the durable artifacts.

Legacy Folder Layout

PROJ folders created before the layout rename use different subfolder names. Mapping, old → current:

2_visual-companion/ → 1b_visual-companion/ · 4_design/ → 1c_design/ · 5_mockups/ → 1d_mockups/ · 3_PRDs/ → 2_PRDs/ · 8_handoff/ → 2b_handoff/ · 6_plan/ → 3-4_plan/ · 7_progress/ → 5_progress/

If an expected folder is missing but its legacy twin exists, read from the legacy one and keep writing where the existing files already are. Never create a second folder next to it — a split PROJ is worse than an old name. Say it once, then continue either way:

"This PROJ uses the old folder layout (<old>). Rename the folders to the current names, or continue with the existing layout?"

Renaming is a git mv per folder plus a search for the old paths in the PROJ's own documents. It is never a precondition for this skill.