---
name: "reality-fit-gate"
version: "1.0.0"
origin: "captured"
generation: 0
parent_skill_ids: []
status: "trial"
description: "Use when: validating whether design documents and page requirements fit real user work scenarios before architecture or implementation. Produces Scenario Evidence Matrix, Pain-To-Feature Traceability, and Real-World Exception Matrix."
trigger_phases: ["design-review", "architecture", "planning"]
applicable_agents: ["Copilot Orchestrator", "Copilot Product Manager", "Copilot UX Architect", "Copilot Architect"]
priority: 9
---

# Reality Fit Gate

## Purpose

Reality Fit Gate closes the gap between structurally complete design documents and real operational scenes. It runs before Architecture for medium/high business slices, especially user-facing modules, stateful orders, workflow-heavy flows, CRM/SCM/FICO/MOM/EAM/QMS/PLM workcenters, and DomainCompletion runs.

This skill does not replace `design-doc-completeness-check`. It runs after structural completeness and before architecture contracts so downstream agents receive realistic user scenarios, not only complete prose.

## Trigger

Apply this gate when any condition is true:

- user asks for design check, design completion, or production-grade delivery
- the slice creates or refactors a user-facing business page
- the module has multiple roles, status changes, approvals, follow-up tasks, exception handling, or SLA pressure
- the slice is medium/high complexity or part of DomainCompletion

Skip or simplify this gate only for:

- pure technical fixes
- single-field copy or style fixes
- internal utility pages with fewer than 5 fields and no state transition

## Owners

| Agent | Responsibility |
|---|---|
| Copilot Product Manager | scenario evidence, role goals, pain inventory, acceptance realism |
| Copilot UX Architect | workcenter mapping, task frequency, page-entry and field-order implications |
| Copilot Architect | downstream contract impact, rule ownership, integration and audit consequences |
| Copilot Orchestrator | gate verdict, routing, and blocker recording |

## Required Artifact: Scenario Evidence Matrix

| Field | Required Content |
|---|---|
| actor | concrete business role, not generic user |
| workcenterEntry | menu, workbench, task, or notification entry used by the actor |
| scenarioTrigger | real trigger such as call, inquiry, expiry, approval rejection, or exception alert |
| taskGoal | result the actor needs to complete |
| frequency | high / medium / low, with evidence if available |
| interruptionPattern | likely interruption, handoff, pause, retry, or waiting state |
| exceptionPath | what happens when the normal flow fails |
| timingPressure | SLA, protection period, shipment window, settlement cutoff, audit deadline, etc. |
| dataNeededFirst | fields or signals that must be visible before the actor opens detail |
| decisionSupport | data, rules, history, document, or relation info required for the decision |
| auditConsequence | consequence of wrong or missing action |
| pageImplication | list/filter/inspector/form/paper/action requirement derived from the scene |

## Required Artifact: Pain-To-Feature Traceability

| Pain Point | Evidence Source | Proposed Feature / Page Block | Acceptance Signal |
|---|---|---|---|
| users cannot identify urgent leads before opening detail | design doc / interview / current code gap | inspector protection status + near-expiry timeline | near-expiry records visible from list click |

Rules:

- every new major page block must map to at least one pain point or operational need
- decorative blocks without traceability are removed or deferred
- if a pain point requires cross-track data, register it as blocker or PendingTask instead of inventing data locally

## Required Artifact: Real-World Exception Matrix

| Scenario | Failure / Exception | Owner | System Behavior | User Message / Recovery | Backend Guard Required |
|---|---|---|---|---|---|

Minimum count:

- normal user-facing CRUD module: at least 5 realistic exceptions
- stateful business module: at least 10 exceptions, aligned with `constraint-first-protocol`
- cross-module chain: include at least 3 upstream/downstream mismatch cases

## Verdict Rules

PASS when:

- Scenario Evidence Matrix covers all primary roles and core workcenter entries
- top high-frequency tasks have visible UI implications
- exception paths are explicit and do not rely only on happy path
- pain-to-feature traceability exists for each major page block
- cross-track dependencies are declared instead of silently filled by local guesses

WARNING when:

- low-frequency scenes are incomplete but core delivery is unaffected
- evidence source is inferred from current design/code but not yet confirmed by user
- optional analytics / AI / dashboard needs are deferred with owner and trigger

BLOCKED when:

- primary actor or core workcenter entry is missing
- the design has state transitions but no real exception handling
- page design cannot justify its main fields/actions from real scenarios
- cross-track required data is assumed without contract or PendingTask

## Output Format

```markdown
## Reality Fit Gate Result

- module: <moduleCode or page>
- designDoc: <path>
- verdict: PASS / WARNING / BLOCKED
- owner: Product Manager + UX Architect

### Scenario Evidence Matrix
| actor | workcenterEntry | scenarioTrigger | taskGoal | frequency | interruptionPattern | exceptionPath | timingPressure | dataNeededFirst | decisionSupport | auditConsequence | pageImplication |
|---|---|---|---|---|---|---|---|---|---|---|---|

### Pain-To-Feature Traceability
| Pain Point | Evidence Source | Proposed Feature / Page Block | Acceptance Signal |
|---|---|---|---|

### Real-World Exception Matrix
| Scenario | Failure / Exception | Owner | System Behavior | User Message / Recovery | Backend Guard Required |
|---|---|---|---|---|---|

### Verdict Notes
- blockers:
- warnings:
- deferred:
```

## Integration

Recommended routing:

```text
Discovery / Product Manager
  -> design-doc-completeness-check
  -> reality-fit-gate
  -> cross-doc-consistency-check when applicable
  -> Architect
```

## Token Policy

- Use current design doc and current code only.
- Do not scan git history.
- Prefer reading the latest domain digest or slice summary before full design documents.
- Store the matrices as reusable handoff so Architect and Frontend Developer do not rebuild the same scenario analysis.