feat(ux): add requirements validation and architecture constraints to UX workflow

Improve UX design workflow for ISO 29148 compliance:
- Update step-01-init to discover and load Architecture document
  and StRS (Enterprise track) in addition to PRD
- Report architecture constraints and StRS user profiles in init
- Add step-13b: Requirements Validation & Handoff Checklist
  - Validates UX design covers all PRD functional requirements
  - Creates FR → UX element coverage matrix
  - Checks architecture constraint alignment
  - Generates downstream handoff checklists for Architecture
    and Epics workflows
  - Documents design decision rationale
- Wire step-13 → step-13b → step-14 (was step-13 → step-14)

Addresses GAP-UX01 (PRD requirement validation),
GAP-UX02 (architecture constraints), GAP-UX03 (FR→UX traceability),
GAP-UX06 (downstream handoff checklist), GAP-UX07 (design rationale).

Part of ISO 29148 compliance initiative (Wave 2).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Tolga Karatas 2026-02-16 01:13:49 +03:00
parent f7fd90297e
commit a351874068
No known key found for this signature in database
GPG Key ID: C8389C243D70C4C9
3 changed files with 184 additions and 4 deletions

View File

@ -64,7 +64,9 @@ Also - when searching - documents can be a single markdown file, or a folder wit
Try to discover the following: Try to discover the following:
- Product Brief (`*brief*.md`) - Product Brief (`*brief*.md`)
- Research Documents (`*prd*.md`) - PRD (`*prd*.md`) - PRIMARY input: contains FRs and NFRs the UX must address
- Architecture Document (`*architecture*.md`) - Contains technical constraints that affect UX decisions (API limits, platform requirements, performance budgets)
- StRS (`*strs*.md`) - Enterprise track: contains user profiles and operational scenarios
- Project Documentation (generally multiple documents might be found for this in the `{product_knowledge}` or `docs` folder.) - Project Documentation (generally multiple documents might be found for this in the `{product_knowledge}` or `docs` folder.)
- Project Context (`**/project-context.md`) - Project Context (`**/project-context.md`)
@ -98,8 +100,10 @@ Report what was found:
**Documents Found:** **Documents Found:**
- PRD: {number of PRD files loaded or "None found"} - PRD: {number of PRD files loaded or "None found"} ← Key: FRs define what UX must address
- Product brief: {number of brief files loaded or "None found"} - Product brief: {number of brief files loaded or "None found"}
- Architecture: {found or "None found"} ← Key: Technical constraints that affect UX
- StRS: {found or "None found"} ← Enterprise: User profiles and scenarios
- Other context: {number of other files loaded or "None found"} - Other context: {number of other files loaded or "None found"}
**Files loaded:** {list of specific file names or "No additional documents found"} **Files loaded:** {list of specific file names or "No additional documents found"}

View File

@ -227,7 +227,7 @@ Show the generated responsive and accessibility content and present choices:
- Append the final content to `{planning_artifacts}/ux-design-specification.md` - Append the final content to `{planning_artifacts}/ux-design-specification.md`
- Update frontmatter: append step to end of stepsCompleted array - Update frontmatter: append step to end of stepsCompleted array
- Load `./step-14-complete.md` - Load `./step-13b-requirements-validation.md`
## APPEND TO DOCUMENT: ## APPEND TO DOCUMENT:
@ -259,6 +259,6 @@ When user selects 'C', append the content directly to the document using the str
## NEXT STEP: ## NEXT STEP:
After user selects 'C' and content is saved to document, load `./step-14-complete.md` to finalize the UX design workflow. After user selects 'C' and content is saved to document, load `./step-13b-requirements-validation.md` to finalize the UX design workflow.
Remember: Do NOT proceed to step-14 until user explicitly selects 'C' from the A/P/C menu and content is saved! Remember: Do NOT proceed to step-14 until user explicitly selects 'C' from the A/P/C menu and content is saved!

View File

@ -0,0 +1,176 @@
# Step 13b: Requirements Validation & Handoff Checklist
## MANDATORY EXECUTION RULES (READ FIRST):
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
- 🎯 This step validates UX design completeness against PRD requirements
- 📋 YOU ARE A VALIDATION FACILITATOR for this step
## EXECUTION PROTOCOLS:
- 🎯 Load PRD and validate requirements coverage
- 🎯 Load Architecture document and check constraint alignment
- ⚠️ Present findings with A/P/C menu
- 💾 ONLY save when user chooses C (Continue)
- 📖 Update output file frontmatter, adding this step to stepsCompleted
- 🚫 FORBIDDEN to load next step until C is selected
## CONTEXT BOUNDARIES:
- Complete UX design specification from all previous steps is available
- PRD (if loaded at init) contains FRs/NFRs that UX must address
- Architecture (if loaded at init) contains technical constraints
- Focus on validating coverage and creating handoff artifacts
## YOUR TASK:
Validate that the UX design addresses PRD requirements, respects architecture constraints, and prepare handoff artifacts for downstream workflows (Architecture, Epics & Stories).
## VALIDATION & HANDOFF SEQUENCE:
### 1. Requirements Coverage Validation
If PRD was loaded during initialization:
**Extract PRD Functional Requirements:**
- Load the PRD and find all FRs
- For each FR, determine if the UX design addresses it
**Create Coverage Matrix:**
- Map each FR to UX design elements (user journeys, components, patterns)
- Identify FRs NOT addressed by UX design
- For unaddressed FRs, determine if they are:
- Non-UI FRs (backend-only, no UX needed) → Mark as N/A
- Missing from UX design → Flag as GAP
**Present to user:**
"I've validated your UX design against the PRD requirements:
**FR Coverage:**
| FR | Description | UX Element | Status |
|----|-------------|-----------|--------|
| FR1 | [desc] | [journey/component/pattern] | ✅ Covered |
| FR5 | [desc] | - | ⚠️ Gap (UI feature) |
| FR8 | [desc] | N/A | Backend only |
**Coverage: [X]% of UI-relevant FRs addressed**
**Gaps found: [count]**"
If PRD was NOT loaded:
- Note that requirements validation could not be performed
- Recommend running this check later when PRD is available
### 2. Architecture Constraint Alignment
If Architecture document was loaded:
**Check for conflicts:**
- API constraints vs. UX interaction patterns (e.g., real-time updates vs. REST-only API)
- Platform constraints vs. responsive strategy
- Performance budgets vs. animation/interaction complexity
- Data model constraints vs. information architecture
**Present any conflicts found:**
- Conflict description
- UX design assumption
- Architecture constraint
- Suggested resolution
If Architecture was NOT loaded:
- Note that constraint validation could not be performed
### 3. Downstream Handoff Checklist
Create handoff information for downstream workflows:
**For Architecture Workflow (Winston):**
- [ ] UX interaction patterns that require specific API design
- [ ] Real-time requirements identified in UX (WebSocket, SSE, polling)
- [ ] Data requirements from form designs and user flows
- [ ] Performance requirements from animation/interaction specs
**For Epics & Stories Workflow (John):**
- [ ] User journey → FR mapping (which journeys implement which FRs)
- [ ] Component complexity estimates (simple, moderate, complex)
- [ ] Design dependencies between components
- [ ] Phasing recommendations (what can be MVP vs. later)
**Design Decision Rationale:**
- Key design decisions and WHY they were made
- Alternatives considered and rejected (with reasons)
- Assumptions made during design
### 4. Generate Validation & Handoff Content
Append to the document:
```markdown
## Requirements Validation
### FR Coverage Matrix
[Table mapping FRs to UX elements]
### Architecture Constraint Alignment
[Any conflicts found and resolutions, or "No architecture document loaded"]
## Downstream Handoff
### Architecture Handoff
[UX constraints and requirements for architecture decisions]
### Epics & Stories Handoff
[User journey → FR mapping, complexity estimates, phasing recommendations]
### Design Decision Rationale
[Key decisions with reasoning for downstream teams]
```
### 5. Present MENU OPTIONS
Present the validation findings and handoff checklist, then display menu:
- Show coverage matrix highlights
- Show any architecture conflicts
- Show handoff readiness
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Complete Workflow (Step 14)"
#### Menu Handling Logic:
- IF A: Read fully and follow Advanced Elicitation, process, ask acceptance, update or keep, redisplay
- IF P: Read fully and follow Party Mode, process, ask acceptance, update or keep, redisplay
- IF C: Append to output document, update frontmatter, then read fully and follow: `./step-14-complete.md`
- IF Any other: help user respond, then redisplay menu
## APPEND TO DOCUMENT:
When user selects 'C', append the content directly to the document.
## SUCCESS METRICS:
✅ PRD FR coverage validated (if PRD available)
✅ Architecture constraints checked (if architecture available)
✅ FR → UX element mapping created
✅ Gaps identified with clear categorization
✅ Handoff checklist prepared for Architecture and Epics workflows
✅ Design decision rationale documented
✅ A/P/C menu presented and handled correctly
## FAILURE MODES:
❌ Not loading PRD for validation when it was discovered at init
❌ Claiming full coverage without systematic check
❌ Not creating handoff artifacts for downstream workflows
❌ Not documenting design decision rationale
❌ Marking non-UI FRs as gaps (they should be N/A)
## NEXT STEP:
After user selects 'C' and content is saved, load `./step-14-complete.md` to complete the workflow.
Remember: Do NOT proceed to step-14 until user explicitly selects 'C'!