Requirement Design

---
name: requirement-design
description: Use in a Wakeflow Design window to turn a clarified and confirmed requirement, or a non-bug outcome mismatch that needs redesign, into a controller-intake-ready requirement design with user stories, decisions, tests, non-goals, and acceptance criteria.
---

# Requirement Design

Write a requirement design that the Wakeflow controller can review, schedule,
and dispatch. This skill turns known context into a structured design; it does
not interview endlessly, publish issues, mutate controller state, or implement
product code.

## Source Skills Used

- `mattpocock/skills/engineering/to-prd`: synthesize conversation and codebase
  understanding into problem, solution, user stories, implementation decisions,
  testing decisions, out-of-scope, and notes.
- `vadimcomanescu/codex-skills/.../agile-product-owner`: INVEST-style stories
  and acceptance criteria.
- `planning-with-files`: separate notes from deliverables and keep references
  explicit.
- Industry basis: ISO/IEC/IEEE 29148-style requirement quality and INVEST
  slicing criteria.

## Preconditions

Use this skill only when at least one of these is true:

- the user has confirmed the clarified requirement;
- the controller asked Design for a requirement design;
- the controller or user says the implementation is not buggy but the effect is
  still wrong and needs a real adjustment plan;
- a Design handoff has enough evidence to draft a candidate and clearly mark
  open decisions.

If the goal, scope, or completion evidence is unclear, run
`requirement-clarification` first. If the implementation route is unclear, run
`option-planning` first.

## Interaction First

Default to conversation. Use this skill to draft or review requirement-design
sections with the user, call out gaps, and recommend the next Design or
controller decision before writing any tracked Design artifact.

Do not create or update requirement-design documents, handoff drafts, or board
rows as the first action. Write files only when the user/controller explicitly
asks for a tracked artifact, confirms that the proposed content should be
recorded, or a controller state root assigns a write deliverable. If a write is
justified, state what will be written and why before editing.

## Workflow

1. Gather facts.
   - Conversation and user decisions.
   - Existing Design notes and original plan.
   - Relevant product docs, ADRs, current behavior, and code seams.
   - Current Wakeflow state root or controller document when provided.
2. Respect domain language.
   - Use existing glossary or code vocabulary.
   - Call out conflicts between user language and code/docs.
3. For outcome redesign, classify the mismatch before proposing work.
   - What effect was observed?
   - Why is this not a simple product-code bug or missing evidence?
   - Which point-fix loop should stop?
   - What new behavior or architecture target should replace it?
4. Sketch testing seams before writing the final design.
   - Prefer existing public seams.
   - Use the highest seam that proves observable behavior.
   - If a new seam is needed, justify it.
5. Draft the design as a controller artifact in the conversation.
   - Write a tracked requirement-design document only after explicit
     user/controller confirmation.
6. Mark confirmation status.
   - `confirmed`
   - `candidate`
   - `needs-user-decision`
   - `needs-controller-intake`

## Required Sections

```markdown
# <requirement title>

## Problem

## Goal

## Non-goals

## Primary actors

## User stories

## Proposed behavior

## Implementation decisions

## Outcome gap or redesign trigger

## Testing decisions

## Acceptance criteria

## Risks and open questions

## Controller intake notes

## Source references
```

## Section Rules

- `Problem` is from the user's perspective, not a code-change summary.
- `Goal` must name the observable outcome.
- `Non-goals` must prevent scope drift.
- `User stories` should be extensive enough to cover the meaningful behavior,
  but not padded with duplicate cases.
- `Implementation decisions` may name modules, interfaces, contracts, schema or
  state changes, but avoid brittle file-path inventories unless the path itself
  is part of the decision.
- `Outcome gap or redesign trigger` is required when the work comes from a
  non-bug result mismatch; it must state observed effect, intended effect, why
  product redispatch would be churn, and the real adjustment strategy.
- `Testing decisions` must state what makes a good test for this requirement,
  which seam should be used, and which prior tests or patterns are relevant.
- `Acceptance criteria` must be binary or evidence-backed.
- `Controller intake notes` must state whether Design thinks this is ready for
  task-package planning, user confirmation, option planning, or stop. When this
  design corrects a demand already in progress (the controller chose a `redesign`
  review decision and parked it), name the original demand or state root here so the
  controller resumes that parked demand with `add-task-package`, not a new one.

## Allowed Outputs

- Conversational requirement-design draft or review.
- Wakeflow Design requirement-design documents.
- Requirement-design candidate sections in a handoff.
- Controller intake notes and open questions.

## Forbidden Outputs

- No issue tracker publishing.
- No `ready-for-agent` or equivalent execution label.
- No product code edits.
- No controller state mutation.
- No invented code facts.
- No unconfirmed Design suggestion marked as executable scope.
- No tracked Design document or board update as the first action without an
  explicit write request or confirmation.

## Quality Bar

The design is good when a controller can decide phase order, affected windows,
producer/consumer dependencies, validation strategy, and user-confirmation needs
without guessing. It fails if it reads like a feature wish list, omits testing
decisions, or cannot be traced back to user goals and evidence.