Work Order QMS Module — User Experience & Journey Architecture

Classification: Internal — Product & Design
Date: 2026-02-13
Artifact: 68 of WO System Series
Status: Proposed
Source Artifacts: 09-go-to-market-strategy.md §4, 12-sdd.md §1, 22-rbac-permissions-matrix.md, 28-quick-start-guide.md

1. Persona-Journey Matrix

1.1 Persona Definitions

Persona	Role (RBAC)	Daily Context	Technical Skill	Primary Value	Frequency
Sam — System Owner	SYSTEM_OWNER	Manages 5–20 validated systems, coordinates change control, accountable to QA	Moderate (domain expert, not developer)	Compliance confidence, reduced paperwork	Daily
Priya — QA Manager	QA	Reviews WOs for regulatory compliance, approves with e-signature, prepares for audits	Low–Moderate (regulatory expert)	Audit readiness, first-pass approval rate	Daily
Marco — IT Technician	ASSIGNEE	Executes work: installs software, calibrates instruments, configures systems	High (technical hands-on)	Clear task scope, no ambiguity	Daily
Dr. Chen — Compliance Director	AUDITOR + QA	Executive oversight of compliance posture, reviews audit trends, manages FDA interactions	Low (reads reports, not creates them)	Risk visibility, audit preparation time	Weekly
Aisha — Vendor Technician	VENDOR	External contractor: performs IQ/OQ, installs equipment, submits evidence	Variable	Self-service access, clear deliverables	Per-WO
Jordan — Lab Manager	ORIGINATOR + ASSIGNER	Creates change requests, plans work, assigns to team members	Moderate	Speed of request creation, visibility into status	Daily
AI Agent	AGENT (system)	Autonomously plans, assigns, executes, validates WO tasks	N/A	Accuracy, compliance, speed	Continuous

1.2 Critical Journey Maps

Journey 1: Sam Creates a Master WO for HPLC Firmware Upgrade

Sam's Goal: Upgrade firmware on 3 HPLCs with minimal production downtime

Step 1: CREATE CHANGE REQUEST                    [5 min]
  ├─ Sam opens WO module → "New Work Order"
  ├─ Selects: Type=Preventive, Regulatory=Yes, System=HPLC-Lab-A
  ├─ AI agent suggests: "Based on similar upgrades, recommend Master WO 
  │   with 3 linked WOs (one per HPLC) + 1 OQ validation WO"
  ├─ Sam accepts suggestion → Master WO + 4 linked WOs auto-created
  └─ FRICTION POINTS: system category selection, regulatory flag uncertainty

Step 2: PLAN THE WORK                            [15 min]
  ├─ Agent pre-populates Job Plans from template library
  ├─ Sam reviews: tools needed, experience requirements, estimated hours
  ├─ Sam adjusts schedule: HPLC-1 Monday, HPLC-2 Tuesday, HPLC-3 Wednesday
  ├─ Agent checks resource availability → flags: "Marco unavailable Tuesday"
  ├─ Sam reassigns HPLC-2 to alternative technician
  └─ FRICTION POINTS: template doesn't match exactly, need to customize

Step 3: SUBMIT FOR APPROVAL                      [2 min]
  ├─ Sam clicks "Submit for Approval"
  ├─ System routes to: Sam (System Owner approval) + Priya (QA approval)
  ├─ E-signature prompt: Sam re-authenticates, signs with meaning
  └─ FRICTION POINTS: re-authentication interrupts flow

Step 4: MONITOR PROGRESS                         [Ongoing, 1 min/check]
  ├─ Dashboard shows: Master WO progress bar, linked WO status cards
  ├─ Real-time updates as Marco completes tasks
  ├─ Notification: "HPLC-2 blocked — calibration tool unavailable"
  ├─ Sam acknowledges block, coordinates resolution
  └─ FRICTION POINTS: notification noise (too many updates)

Step 5: CLOSE AND DOCUMENT                       [10 min]
  ├─ All linked WOs completed → Master WO auto-advances to COMPLETED
  ├─ Agent generates compliance evidence package
  ├─ Sam reviews, signs final closure
  ├─ Audit trail + evidence archived automatically
  └─ FRICTION POINTS: reviewing auto-generated evidence, trusting agent output

Total time: ~35 minutes active + monitoring
Without CODITECT: ~4–8 hours (manual WO creation, paper job plans, email coordination, manual evidence compilation)

Journey 2: Priya Reviews and Approves a Regulatory WO

Priya's Goal: Verify compliance and approve WO within SLA

Step 1: REVIEW QUEUE                             [1 min]
  ├─ Priya opens "My Approvals" → sorted by deadline
  ├─ Badge shows: 3 pending, 1 urgent (deadline today)
  ├─ Clicks urgent WO → full context loads
  └─ DESIGN: Approval queue is Priya's landing page (role-based default)

Step 2: COMPLIANCE REVIEW                        [5–8 min]
  ├─ Compliance summary card: all guards passed ✅, no violations
  ├─ Linked documents: Job Plan, tool requirements, experience verification
  ├─ Audit trail: timeline of all actions, actors, timestamps
  ├─ AI compliance assistant: "This WO follows the same pattern as WO-2023-087 
  │   which passed FDA audit. Key difference: new firmware version."
  ├─ Priya clicks "View Differences" → highlighted delta from template
  └─ FRICTION POINTS: information overload, trust in AI summary accuracy

Step 3: APPROVE WITH E-SIGNATURE                 [1 min]
  ├─ Priya clicks "Approve"
  ├─ Re-authentication modal (password or biometric)
  ├─ Signature meaning displayed: "QA Approval of WO-2024-0042"
  ├─ Priya confirms → cryptographic signature generated
  ├─ WO advances to ASSIGNED (both approvals collected)
  └─ FRICTION POINTS: re-auth feels slow; meaning text sometimes generic

Step 4: REJECTION PATH (ALTERNATE)               [3 min]
  ├─ Priya clicks "Reject" → required: select reason category + free text
  ├─ Categories: Incomplete documentation, Missing approval, Compliance gap,
  │   Scope concern, Resource inadequacy
  ├─ WO returns to DRAFT with rejection reason visible to originator
  ├─ Notification to Sam with specific remediation guidance
  └─ DESIGN: Rejection is constructive, not punitive; clear path to resubmit

Journey 3: Marco Executes a Work Order Task

Marco's Goal: Complete assigned task correctly and on time

Step 1: VIEW ASSIGNMENTS                         [30 sec]
  ├─ Marco opens "My Work" → active assignments sorted by priority
  ├─ Each card shows: WO title, system, location, deadline, job plan summary
  └─ DESIGN: Mobile-friendly cards; Marco may be on lab floor with tablet

Step 2: START WORK                               [1 min]
  ├─ Marco taps "Start" → WO transitions IN_PROGRESS
  ├─ Timer starts (actual hours tracking)
  ├─ Job Plan checklist loads: step-by-step instructions
  ├─ Required tools displayed with location/availability status
  └─ DESIGN: Checklist is the primary work interface, not a form

Step 3: EXECUTE AND DOCUMENT                     [Variable]
  ├─ Marco checks off steps as completed
  ├─ For evidence-required steps: camera button → photo upload
  ├─ For measurement steps: numeric input with range validation
  ├─ If blocked: "Report Issue" → selects reason → WO transitions BLOCKED
  │   → Notification to Sam + agent evaluates alternative resolution
  └─ FRICTION POINTS: photo upload on slow lab WiFi, measurement formatting

Step 4: COMPLETE                                 [2 min]
  ├─ All checklist items checked → "Complete Task" enabled
  ├─ Marco reviews summary of actual work performed
  ├─ Time entry auto-calculated from start/stop (manual override available)
  ├─ Marco submits → task completes → linked WO updates
  └─ FRICTION POINTS: time entry rounding, forgotten photo uploads

Journey 4: Aisha (Vendor) Completes IQ/OQ Documentation

Aisha's Goal: Submit qualification evidence through vendor portal

Step 1: RECEIVE ASSIGNMENT                       [1 min]
  ├─ Email notification with secure portal link
  ├─ Aisha clicks link → SSO or one-time-password login
  ├─ Sees only her assigned WOs (scoped vendor view per RBAC)
  └─ DESIGN: No app installation required; web-based portal

Step 2: REVIEW SCOPE                             [5 min]
  ├─ WO details: what to qualify, acceptance criteria, deadline
  ├─ Job Plan with vendor-specific steps
  ├─ Required deliverables list: IQ protocol, IQ report, OQ protocol, OQ report
  └─ FRICTION POINTS: acceptance criteria ambiguity, template format confusion

Step 3: UPLOAD EVIDENCE                          [10 min]
  ├─ Drag-and-drop file upload (PDF, DOCX, images)
  ├─ File automatically scanned: size, type, virus, PHI detection
  ├─ Each upload mapped to a specific deliverable in the checklist
  ├─ Version tracking: re-uploads create new version, old version preserved
  └─ FRICTION POINTS: file size limits, format rejection, slow upload

Step 4: SUBMIT FOR REVIEW                        [1 min]
  ├─ Aisha clicks "Submit" → evidence package sent to QA review queue
  ├─ Status visible in portal: "Submitted — Awaiting Review"
  ├─ Notification to Priya (QA) with evidence package link
  └─ DESIGN: Vendor can see status but cannot see internal discussions

Journey 5: Dr. Chen Prepares for FDA Audit

Dr. Chen's Goal: Confidence that all compliance records are audit-ready

Step 1: OPEN COMPLIANCE DASHBOARD                [30 sec]
  ├─ Role-based landing: compliance overview with KPIs
  ├─ Cards: Open WOs, Overdue WOs, Compliance Score, Recent Violations
  └─ DESIGN: Executive-level summary, not detail

Step 2: RUN AUDIT READINESS CHECK                [2 min]
  ├─ Click "Audit Readiness" → system scans all WOs from selected period
  ├─ Report: signature completeness, audit trail integrity, training currency
  ├─ Traffic lights: 🟢 All signatures valid, 🟡 2 training gaps, 🔴 1 overdue WO
  └─ FRICTION POINTS: scan takes time for large date ranges; results need context

Step 3: DRILL INTO FINDINGS                      [5 min]
  ├─ Click yellow/red items → detailed finding with remediation path
  ├─ "2 training gaps" → shows persons, required training, expiry dates
  ├─ "1 overdue WO" → shows WO, current state, assignee, escalation history
  ├─ One-click: "Generate WO to remediate" → auto-creates corrective action WO
  └─ DESIGN: Every finding has an action; no dead-end screens

Step 4: GENERATE EVIDENCE PACKAGE                [1 min]
  ├─ Select date range + system scope → "Generate Package"
  ├─ Agent compiles: all WOs, audit trails, signatures, training records
  ├─ Output: PDF evidence package + machine-readable JSON
  ├─ Package includes table of contents, cross-reference matrix
  └─ FRICTION POINTS: package generation time (async; notification when ready)

2. Information Architecture

WO System — Global Navigation

┌─────────────────────────────────────────────────────────────┐
│  [Logo]  Home  Work Orders  Compliance  Reports  Admin  [?] │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Role-Based Landing:                                        │
│  ┌─────────────────┐                                        │
│  │ System Owner:    │ → My Systems (WO list filtered)       │
│  │ QA Manager:      │ → Approval Queue                      │
│  │ IT Technician:   │ → My Assignments                      │
│  │ Compliance Dir:  │ → Compliance Dashboard                │
│  │ Vendor:          │ → Vendor Portal (scoped view)         │
│  │ Lab Manager:     │ → Team Queue                          │
│  └─────────────────┘                                        │
│                                                             │
│  Work Orders ─┬─ My Assignments                             │
│               ├─ Team Queue                                 │
│               ├─ All Work Orders (role-filtered)            │
│               ├─ Master WO Tracker                          │
│               └─ Create New                                 │
│                                                             │
│  Compliance ──┬─ Audit Trail Search                         │
│               ├─ Compliance Dashboard                       │
│               ├─ Audit Readiness Check                      │
│               ├─ Evidence Library                           │
│               └─ Policy Management                          │
│                                                             │
│  Reports ─────┬─ WO Metrics (cycle time, throughput)        │
│               ├─ Resource Utilization                       │
│               ├─ Compliance Score Trend                     │
│               ├─ Agent Performance                          │
│               └─ Export / Schedule Reports                  │
│                                                             │
│  Admin ───────┬─ Users & Roles                              │
│               ├─ Teams & Vendors                            │
│               ├─ Systems & Assets                           │
│               ├─ Approval Chain Config                      │
│               ├─ Job Plan Templates                         │
│               ├─ Integrations                               │
│               ├─ Tenant Settings                            │
│               └─ Security & Audit                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.2 Design Principles

Principle	Implementation	Rationale
Role-based default views	Each persona lands on their highest-value page after login	Reduces time-to-action; QA doesn't need to navigate to approval queue
Progressive disclosure	Summary → detail on demand; never show everything at once	Lab managers on tablets need quick views; detail available on click
Contextual actions	Relevant buttons appear where the user needs them (approve button on approval screen, not in a menu)	Reduces click count for primary actions
Consistent patterns	Every list: filter bar → sortable table → detail panel; every form: inline validation → summary → confirm	Reduces learning curve across WO types
Deep linking	Every WO, approval, audit entry has a shareable URL	Enables email/Slack references: "see WO-2024-0042"
Breadcrumbs	Always show: Home > Work Orders > WO-2024-0042 > Job Plan	Users never feel lost; back navigation always available

3. Onboarding Architecture

3.1 First-Run Experience

Account Activation → Role Selection → Guided Setup → First Real Task

Step 1: ROLE SELECTION
  "Welcome to CODITECT WO. What's your primary role?"
  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  │ System Owner │ │ QA / Quality │ │ IT / Ops     │
  │ I manage     │ │ I review and │ │ I execute    │
  │ validated    │ │ approve      │ │ work orders  │
  │ systems      │ │ changes      │ │              │
  └──────────────┘ └──────────────┘ └──────────────┘
  
  Sets: default landing page, notification preferences, dashboard layout

Step 2: GUIDED SETUP (role-specific, 5-10 minutes)
  System Owner path:
    → Register your first validated system (name, type, criticality)
    → Create a sample WO for that system (pre-filled template)
    → See: state machine visualization, approval chain, audit trail
    → Milestone: "You created your first compliant change request"

  QA Manager path:
    → Review a sample WO (pre-populated)
    → Practice e-signature (real auth, demo WO)
    → See: audit trail generated, compliance summary
    → Milestone: "You approved your first work order"

  IT Technician path:
    → View your sample assignment
    → Walk through job plan checklist
    → Mark steps complete, upload sample evidence
    → Milestone: "You completed your first task"

Step 3: FIRST REAL TASK (contextual prompt within 24 hours)
  "Ready to create your first real work order?"
  → Offers to convert guided setup learnings into production use
  → Measures: Time to First Value (TTFV)

3.2 Time-to-Value Metrics

Metric	Target	Measurement	Alert Threshold
TTFV (System Owner)	< 30 min from login to first real WO created	Timestamp delta: account_activated → first_wo_created	> 2 hours
TTFV (QA Manager)	< 15 min from login to first real approval	Timestamp delta: account_activated → first_approval_signed	> 1 hour
TTFV (IT Technician)	< 10 min from login to first task started	Timestamp delta: account_activated → first_task_started	> 30 min
Onboarding completion	> 85% complete guided setup	Steps completed / total steps	< 60%
7-day retention	> 90% of users active at day 7	Users with activity in days 1–7 / total onboarded	< 75%
Feature discovery (30d)	> 60% of key features used	Distinct features used / key feature list	< 40%

3.3 Progressive Disclosure Schedule

Week	Features Revealed	Trigger
Week 1	WO creation, approval, basic checklist, notifications	Account activation
Week 2	Master/linked WOs, dependency tracking, resource matching	First WO completed
Week 3	Agent automation, PM scheduling, compliance dashboard	5+ WOs completed
Week 4	Custom templates, webhook integrations, API access	Admin requests or power user signals

4. Accessibility Requirements (WCAG 2.1 AA)

4.1 Standards Compliance

WCAG Principle	Requirement	WO System Implementation	Testing
Perceivable	Text alternatives for non-text content	All icons have `aria-label`; status indicators use color + text + icon	axe-core automated
Perceivable	Color is not sole conveyor of info	Status: 🟢 Ready + "Ready" text, 🟡 Partial + "Partial" text, 🔴 Gap + "Gap" text	Manual review
Perceivable	Contrast ratio ≥ 4.5:1 (normal text), ≥ 3:1 (large text)	Per JSX design system: text ≥ #374151 on white (#FFFFFF) = 5.7:1	Contrast checker
Operable	All functionality keyboard accessible	Tab order follows visual layout; Enter/Space activate; Escape closes modals	Manual keyboard testing
Operable	Focus visible on all interactive elements	2px solid blue outline on focus; never `outline: none` without replacement	Manual testing
Operable	No time-based content without control	Session timeout: 2-minute warning with extend option; no auto-advancing carousels	Manual testing
Understandable	Error identification with suggestion	Inline validation: "WO title is required" next to field; not just red border	axe-core + manual
Understandable	Consistent navigation across pages	Same nav bar, same patterns, same icons across all views	Design review
Robust	ARIA landmarks for screen readers	`<main>`, `<nav>`, `<aside>`, `role="search"`, `aria-live` for status updates	NVDA/VoiceOver testing

4.2 Specific WO System Accessibility

Component	Accessibility Feature	Implementation
State machine visualization	Text alternative describing current state and available transitions	`aria-label="Work order WO-2024-0042 is in APPROVED state. Available transitions: ASSIGNED."`
Approval e-signature modal	Focus trapped in modal; keyboard-operable authentication; screen reader announces required action	`role="dialog"`, `aria-modal="true"`, focus management
Job Plan checklist	Checkbox states announced; progress announced on change	`aria-checked`, `aria-label="Step 3 of 7: Install firmware. Not completed."`
Audit trail timeline	Timeline readable as ordered list; timestamps in human-readable format	`<ol>` structure; `<time>` elements; `aria-label` per entry
Dashboard KPI cards	Values announced with context	`aria-label="Open work orders: 12. 3 overdue."`
File upload (vendor portal)	Drag-and-drop has keyboard alternative; upload progress announced	Fallback file input; `aria-live="polite"` for progress

4.3 Accessibility Testing Plan

Test Type	Tool	Frequency	Scope
Automated scan	axe-core (CI integration)	Every PR	All pages
Keyboard navigation	Manual (QA)	Per feature	All interactive elements
Screen reader	NVDA (Windows), VoiceOver (macOS)	Monthly	Critical paths (create WO, approve, complete)
Contrast verification	Automated (Lighthouse)	Every PR	All text elements
Mobile accessibility	Manual (iOS VoiceOver, Android TalkBack)	Per release	Core flows on tablet

5. Error Experience Design

5.1 Error Categories & User Experience

Category	User Sees	Technical Detail	Recovery Action
Validation	Inline field-level message with specific fix	422 + field error array	Fix the specific field; no page reload
Permission denied	"You need [specific role] to [action]. Contact [admin name]."	403 + required_permission + admin_contact	Clear escalation path; no guessing
Compliance block	"This transition requires [specific approval/condition]. [Action link]"	403 + compliance_rule + resolution_steps	Link directly to resolution (e.g., "Request QA Approval")
Conflict	"This WO was updated by [person] [time ago]. Review changes and retry."	409 + diff + current_version	Side-by-side diff; merge or override option
Agent failure	"AI assistant encountered an issue. You can proceed manually or retry."	500 + agent_error + fallback_option	Manual fallback always available; never blocked by agent
Network	"Connection lost. Your changes are saved locally. Reconnecting..."	Network timeout + offline queue	Auto-retry with progress; manual retry button
System error	"Something unexpected happened. Reference: [ID]. Our team has been notified."	500 + correlation_id + auto-alert	Reference ID for support; auto-notified engineering

5.2 Error Design Principles

Principle	Implementation
Never show raw errors	Every error maps to a human-readable message via error code catalog
Always provide next action	Every error message includes what the user can do (not just what went wrong)
Preserve work	Auto-save every 30 seconds; error states never lose user input
Correlate for support	Every error generates a unique reference ID; one-click "Report Issue" button
Compliance errors are special	Compliance blocks explain the specific regulation, the specific rule, and the specific remediation — never vague "compliance issue"
Agent transparency	When AI agents fail, show what the agent was trying to do and offer manual alternative

5.3 Error Message Catalog Structure

interface ErrorDefinition {
  code: string;                    // e.g., 'WO_INVALID_TRANSITION'
  httpStatus: number;
  userTitle: string;               // "Invalid State Transition"
  userMessage: string;             // Template with {variables}
  recoveryAction: string;          // "Review the required approval chain..."
  complianceRelevant: boolean;
  auditTrailEntry: boolean;        // Whether to log in audit trail
  notifyEngineering: boolean;      // Whether to auto-alert
}

// Example catalog entry
const WO_ERRORS = {
  WO_INVALID_TRANSITION: {
    code: 'WO_INVALID_TRANSITION',
    httpStatus: 422,
    userTitle: 'Cannot Change Status',
    userMessage: 'This work order cannot move from {current_state} to {target_state}. The next valid step is {valid_transitions}.',
    recoveryAction: 'Complete the required steps for {current_state} before advancing.',
    complianceRelevant: true,
    auditTrailEntry: true,
    notifyEngineering: false,
  },
  WO_APPROVAL_MISSING: {
    code: 'WO_APPROVAL_MISSING',
    httpStatus: 403,
    userTitle: 'Approval Required',
    userMessage: 'This work order requires approval from {missing_approvers} before it can proceed.',
    recoveryAction: 'Request approval from {missing_approvers} or contact your System Owner.',
    complianceRelevant: true,
    auditTrailEntry: true,
    notifyEngineering: false,
  },
};

6. Notification Architecture

6.1 Notification Types

Type	Channel	Urgency	Example
Approval request	In-app + email + Slack (optional)	High	"WO-2024-0042 requires your QA approval by Friday"
Status update	In-app	Medium	"WO-2024-0042 moved to IN_PROGRESS by Marco"
Assignment	In-app + email	High	"You've been assigned to WO-2024-0042: HPLC Firmware Upgrade"
Blocked	In-app + email + Slack	High	"WO-2024-0042 is BLOCKED: calibration tool unavailable"
Deadline warning	In-app + email	Medium	"WO-2024-0042 due in 2 days — currently IN_PROGRESS"
Completion	In-app	Low	"Master WO-2024-0040 completed: all linked WOs closed"
Compliance alert	In-app + email + Slack	Critical	"Training expired for Marco — cannot assign to regulatory WOs"
Agent action	In-app	Low	"Agent created 4 linked WOs for Master WO-2024-0040"

6.2 Notification Preferences

Users configure per channel and per type:

Notification Preferences:

In-App:     [All notifications — not configurable, always on]
Email:      ☑ Approval requests  ☑ Assignments  ☑ Blocked
            ☐ Status updates     ☑ Deadlines   ☐ Agent actions
Slack:      ☑ Approval requests  ☐ Assignments  ☑ Blocked
            ☐ Status updates     ☐ Deadlines   ☐ Agent actions

Quiet hours: 8 PM – 7 AM (critical compliance alerts override)
Digest mode: ☐ Individual  ☑ Hourly digest for low-priority

6.3 Notification Delivery Architecture

Event (NATS) → Notification Service → Route:
  ├─ In-App: WebSocket push to connected clients
  │         Stored in notification table (read/unread tracking)
  ├─ Email: Queue → Email adapter (SendGrid/SES) → Delivery tracking
  ├─ Slack: Queue → Slack webhook adapter → Delivery tracking
  └─ SMS:   Queue → SMS adapter (Twilio) → Delivery tracking (critical only)
  
  Preferences checked before each channel delivery.
  Quiet hours enforced (except P0 compliance alerts).
  All delivery attempts logged (per 67-integration-api-strategy.md §4).

7. Cross-Reference to Other Artifacts

Topic	Primary Artifact	UX Section
RBAC role definitions	22-rbac-permissions-matrix.md	§1.1 (persona ↔ role mapping)
State machine (user sees transitions)	19-state-machine-with-guards.md	§1.2 Journey 1 (create + approve flow)
E-signature flow	17-e-signature-architecture.md	§1.2 Journey 2 (approval signing)
Agent orchestration (user sees agent actions)	25-agent-orchestration-spec.md	§1.2 Journey 1 (agent suggestions)
API error responses	67-integration-api-strategy.md §2.2	§5 (error experience mapping)
Vendor portal scope	22-rbac-permissions-matrix.md	§1.2 Journey 4 (vendor scoped view)
Compliance dashboard	40-comprehensive-compliance-dashboard.jsx	§1.2 Journey 5 (audit readiness)
Onboarding (quick start)	28-quick-start-guide.md	§3 (first-run experience)

The system doesn't exist in a vacuum — it exists in front of humans who have deadlines, frustrations, and compliance auditors breathing down their necks. Every architectural decision that ignores the user experience is a decision that increases support tickets, reduces adoption, and ultimately threatens revenue. The journeys in this document are acceptance criteria — if a release breaks a critical journey, it doesn't ship.

1. Persona-Journey Matrix​

1.1 Persona Definitions​

1.2 Critical Journey Maps​

Journey 1: Sam Creates a Master WO for HPLC Firmware Upgrade​

Journey 2: Priya Reviews and Approves a Regulatory WO​

Journey 3: Marco Executes a Work Order Task​

Journey 4: Aisha (Vendor) Completes IQ/OQ Documentation​

Journey 5: Dr. Chen Prepares for FDA Audit​

2. Information Architecture​

2.1 Navigation Model​

2.2 Design Principles​

3. Onboarding Architecture​

3.1 First-Run Experience​

3.2 Time-to-Value Metrics​

3.3 Progressive Disclosure Schedule​

4. Accessibility Requirements (WCAG 2.1 AA)​

4.1 Standards Compliance​

4.2 Specific WO System Accessibility​

4.3 Accessibility Testing Plan​

5. Error Experience Design​

5.1 Error Categories & User Experience​

5.2 Error Design Principles​

5.3 Error Message Catalog Structure​

6. Notification Architecture​

6.1 Notification Types​

6.2 Notification Preferences​

6.3 Notification Delivery Architecture​

7. Cross-Reference to Other Artifacts​