# Requirements Engineer > Create detailed feature PRDs with user stories, acceptance criteria, and edge cases after Visual Companion, optional Frontend Design, and UI Mockup. Use when: (1) an approved concept and optional UI mockups need to become structured PRDs, (2) user stories and acceptance criteria must be written, (3) edge cases must be identified. Not for: UI mockups, writing code, technical design, or debugging. - Skill: `silviobeer/requirements-engineer` (Agent Skill) - Install (CLI): `npx skillmds@latest add silviobeer/requirements-engineer` - Raw SKILL.md: https://api.skillmd.com/api/skills/silviobeer/requirements-engineer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: silviobeer (https://skillmd.com/u/silviobeer) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/silviobeer/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: ```text 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--/1_brainstorm/PROJ--concept.md` 2. UI mockups: `specs/PROJ--/1d_mockups/*.html` 3. Sitemap: `specs/PROJ--/1d_mockups/sitemap.html` 4. UI implementation handoff: `specs/PROJ--/1d_mockups/implementation-handoff.md` 5. Optional Visual Companion decision: `specs/PROJ--/1b_visual-companion/layout-decision.md` 6. Optional design language: `specs/PROJ--/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--/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: ```text specs/PROJ--/2_PRDs/PROJ--PRD--.md ``` Use kebab-case for ``. Template: ```markdown # PROJ--PRD-: 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--PRD- - Cross-PROJ dependency: PROJ--PRD- ## 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: ```bash BASE="specs/PROJ--" GROUND_TRUTH=("$BASE/1_brainstorm/PROJ--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 \ --artifacts "$BASE"/2_PRDs/*.md \ --ground-truth "${GROUND_TRUTH[@]}" \ --author-provider --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 ```text feat(PROJ--PRD-): Add PRD for ``` 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 (``). 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.