# Plan: SOW Demo Workflow - Legendary Treatment
**Date:** 2026-01-10
**Status:** Ready for Review
**Related Handoffs:**
- `SOW-Document-Ingestion-Validation-Redesign-2026-01-09.md`
- `LEGENDARY_MULTI_LENS_CONTEXT_2026-01-10.md`

---

## Executive Summary

Complete the SOW demo workflow from document upload through multi-lens analysis, ensuring every step meets **LEGENDARY standards (90+ score)**. The workflow must flow seamlessly and make users **EXCLAIM**, not explain.

**The Goal:** Get this signed by end clients.

**The Enemy:** Ignorance, laziness, carelessness, assumptions, claiming "done" without verification, not checking if something exists, overwriting without backup.

**The Standard:** Relief > Anxiety. Anticipate > React. Users tell someone at lunch how amazing it was.

---

## Current State (v2.5.2)

### What Works
| Step | Status | Notes |
|------|--------|-------|
| Upload document | ✅ | Side panel on create page |
| Parse/extract via Claude | ✅ | With confidence scores |
| Validation warnings | ✅ | Past dates, format issues |
| Apply to form | ✅ | All fields mapped |
| Create SOW | ✅ | No 333 errors |
| Redirect to show page | ✅ | Toast with SOW number |

### What Needs LEGENDARY Treatment
| Area | Current Score | Target | Issue |
|------|---------------|--------|-------|
| SOW Detail Page | ~50 (MEH) | 90+ | Too spread out, buttons unclear, no workflow |
| Multi-Lens Analyzer | ~65 (ACCEPTABLE) | 90+ | Basic analysis, not "game-changing" |
| Entity Navigation | ~40 (UNWORTHY) | 90+ | Links unclear, no context preservation |
| SOW Number | N/A | Deferred? | Uses vendor number, not unique |

---

## The LEGENDARY Standards (Reference)

### DAISY Ten Commandments
| # | Commandment | Test Question |
|---|-------------|---------------|
| 1 | **Solves Multitudes** | Does it address 3+ user pain points? |
| 2 | **Anticipates Desire** | Does it offer before being asked? |
| 3 | **Reveals Wisdom** | Does it show insights, not just data? |
| 4 | **Respects Time** | Can users complete in 5 clicks or less? |
| 5 | **Creates Wonder** | Will users say "Wow!" not "How?"? |
| 6 | **Speaks Truth** | Is there ZERO mock/fake data? |
| 7 | **Empowers Completely** | Does it give users superpowers? |
| 8 | **Shows Trajectory** | Does it show past, present, AND future? |
| 9 | **Guards Proactively** | Does it warn BEFORE problems occur? |
| 10 | **Remembers The Y** | Is the page's PURPOSE crystal clear? |

### Hotel Room Philosophy
- **Clean Counter:** Initial view visually quiet, no clutter
- **Intuitive Concealment:** Tools in "drawers" that open when needed
- **Anticipatory Readiness:** System predicts user's next move
- **Cognitive Protection:** Every pixel earns its place

### Verdict Thresholds
| Score | Verdict | Ship? |
|-------|---------|-------|
| **90+** | **LEGENDARY** | Yes - users EXCLAIM |
| 75-89 | WORTHY | Yes - production ready |
| 60-74 | ACCEPTABLE | Fix blockers first |
| 40-59 | MEH | No - needs work |
| 0-39 | UNWORTHY | Blocked |

---

## Implementation Plan

### Phase 1: SOW Detail Page - Legendary Treatment (P0)

**Goal:** Transform show page from MEH to LEGENDARY

**File:** `/root/claude/velocity/integrityinnovation/src/pages/statementofworks/show.tsx` (~1,700 lines)

#### 1.1 Hero Section
Replace sprawling cards with compact, information-dense hero:

```
┌─────────────────────────────────────────────────────────────────┐
│ [SOW ICON] SOW-2026-0001              [QUICK ACTIONS]           │
│ Full Email Indexing Project           [Edit] [Analyze] [+Invoice]
│ Vendor: Data Recovery Systems LLC     Status: ● ACTIVE          │
├─────────────────────────────────────────────────────────────────┤
│ $59,955      │ 0% Invoiced  │ Mar 1-15, 2026  │ 5 Milestones   │
│ Total Value  │ $0 of $59K   │ 14 days         │ Deliverables   │
└─────────────────────────────────────────────────────────────────┘
```

#### 1.2 Workflow Status Indicator
Show where they are and what's next:

```
┌─────────────────────────────────────────────────────────────────┐
│ [Draft] ─→ [Pending] ─→ [●ACTIVE] ─→ [Invoiced] ─→ [Completed] │
│                              ↑                                   │
│                         You are here                             │
│            Next: Create invoice or assign stakeholders           │
└─────────────────────────────────────────────────────────────────┘
```

#### 1.3 Section Redesign with Colored Borders
Match create page pattern:

| Section | Border Color | Content |
|---------|--------------|---------|
| SOW Information | Blue (`border-blue-500/50`) | SOW#, Title, Type, Status (grid, not cards) |
| Assignment | Purple (`border-purple-500/50`) | Contractor, Department (inline) |
| Financial | Green (`border-emerald-500/50`) | Total, Invoiced, Remaining, % (inline metrics) |
| Timeline | Amber (`border-amber-500/50`) | Start, End, Duration, Progress bar |
| Scope | Cyan (`border-cyan-500/50`) | Deliverables, Terms (collapsible) |

#### 1.4 Empty State Collapse Pattern
Don't waste space on empty sections:

```tsx
// BEFORE (wasteful):
<Card className="p-6">
  <CardTitle>Stakeholders</CardTitle>
  <div className="text-center py-8 text-muted">
    No stakeholders assigned yet
  </div>
</Card>

// AFTER (compact):
{stakeholders.length === 0 ? (
  <div className="flex items-center justify-between p-2 border-dashed rounded">
    <span className="text-xs text-muted">No stakeholders assigned</span>
    <Button size="sm" variant="ghost">+ Add</Button>
  </div>
) : (
  <StakeholderSection stakeholders={stakeholders} />
)}
```

#### 1.5 Tooltips on EVERY Action Button
Every button explains:
1. What it does
2. What happens next
3. That it's safe to click

```tsx
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="outline" size="sm">
        <FileText className="h-4 w-4 mr-1" />
        Create Invoice
      </Button>
    </TooltipTrigger>
    <TooltipContent side="bottom" className="max-w-xs">
      <p className="font-semibold">Create Invoice from SOW</p>
      <p className="text-xs text-muted-foreground mt-1">
        Opens invoice form pre-filled with vendor and contract details.
        You'll review before saving.
      </p>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>
```

#### 1.6 New Components to Create

| Component | Purpose | Location |
|-----------|---------|----------|
| `SOWWorkflowIndicator` | Status flow visualization | `/src/components/sow/` |
| `SOWHeroSection` | Compact identity + metrics | `/src/components/sow/` |
| `SOWQuickActions` | Action bar with tooltips | `/src/components/sow/` |
| `SOWRelatedEntities` | Links to invoices, projects | `/src/components/sow/` |

---

### Phase 2: Multi-Lens Analyzer Enhancement (P1)

**Goal:** Make analysis "game-changing" - users EXCLAIM

**Files:**
- `/src/pages/ai/multi-lens-analyzer.tsx` (1,626 lines)
- `/src/utils/multi-lens-analyzer.ts` (994 lines)

#### 2.1 Executive Summary (Hero)
At top of analysis, immediately visible:

```
┌───────────────────────────────────────────────────────────────────┐
│                    OVERALL RISK: 42/100                           │
│                         ████████░░ MEDIUM                         │
│                    [Large amber progress circle]                  │
│                                                                   │
│ ⚠️ CRITICAL (Blocks signing):                                     │
│    Insurance certificate missing                                  │
│                                                                   │
│ ⚠️ WARNING:                                                       │
│    Payment terms unfavorable (15 days vs industry 30)            │
│                                                                   │
│ 💡 INSIGHT:                                                       │
│    Similar contracts had 2-week delays - plan buffer              │
│                                                                   │
│ RECOMMENDED ACTION:                                               │
│ ┌─────────────────────────────────────────────────────────────┐  │
│ │ [Request Insurance Certificate from Vendor]                  │  │
│ └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
```

#### 2.2 Each Lens Card (Enhanced)

```
┌─ LEGAL LENS ─────────────────────────── Risk: 65/100 (MEDIUM) ─┐
│ 🔴 KEY FINDING: 2 critical clauses missing                      │
│                                                                  │
│ ISSUES:                                                          │
│ ├─ ✕ Insurance clause missing        [Request from vendor →]    │
│ ├─ ✕ Termination clause missing      [Flag for legal →]         │
│ └─ ⚠ Liability cap unclear           [Review Section 5.2 →]     │
│                                                                  │
│ 💡 INSIGHT: Similar SOWs typically include 30-day termination   │
│    clause. Recommend adding before execution.                    │
└──────────────────────────────────────────────────────────────────┘
```

#### 2.3 Integration Options

**Option A: Tab on Detail Page (Recommended)**
- New tab alongside Overview / Documents / History
- Always accessible, maintains context
- Shows summary badge on tab: "Analysis ⚠️ 3 alerts"

**Option B: Side Panel**
- Opens on right when clicking "Analyze"
- Can overlay detail page
- Good for comparison

**Option C: Modal**
- Full-screen focused view
- Loses context of detail page

---

### Phase 3: Related Entity Navigation (P1)

**Goal:** Seamless flow between SOW → Invoice → PM → Similar SOWs

#### 3.1 Quick Actions Bar
Persistent at top of detail page:

```tsx
<div className="flex items-center gap-2 p-2 bg-muted/30 rounded-lg">
  <TooltipButton label="Edit SOW" icon={<Pencil />} />
  <TooltipButton label="Analyze with AI" icon={<Brain />} />
  <Separator orientation="vertical" className="h-6" />
  <TooltipButton label="Create Invoice" icon={<Receipt />} />
  <TooltipButton label="Create Project" icon={<Kanban />} />
  <TooltipButton label="Add Stakeholder" icon={<UserPlus />} />
  <Separator orientation="vertical" className="h-6" />
  <TooltipButton label="View Similar SOWs" icon={<Copy />} />
</div>
```

#### 3.2 Related Entities Section

```
┌─ RELATED DOCUMENTS ─────────────────────────────────────────────┐
│                                                                  │
│ 📄 Invoices          0 created    [+ Create Invoice]            │
│ 📋 Projects          0 linked     [+ Create Project Plan]       │
│ 📝 Change Orders     0 submitted  [+ Add Change Order]          │
│ 📊 Similar SOWs      3 found      [View Comparison →]           │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

#### 3.3 Cross-Navigation Pattern
- Invoice detail shows: `Source SOW: SOW-2026-0001` (clickable link)
- Project shows: `Related SOW: SOW-2026-0001` (clickable link)
- Breadcrumbs: `Home > SOWs > SOW-2026-0001 > Create Invoice`

---

### Phase 4: SOW Number (Decision Pending)

**Current:** Uses vendor's SOW number (e.g., "DRS-55025-14.1")
**Problem:** Vendor numbers aren't unique across vendors

#### If Including (adds ~2 hours):
1. DB migration: Add `vendor_sow_number TEXT` column
2. Backend: Auto-generate `SOW-{YEAR}-{SEQUENCE}` on create
3. Display: "SOW-2026-0001 (Vendor Ref: DRS-55025-14.1)"
4. Extraction: Map parsed number to vendor_sow_number field

#### If Deferring:
- Keep current behavior for demo
- Address in post-demo sprint
- Acceptable for single-vendor demo scenario

---

## Files to Modify

### P0 - Must Have for Demo

| File | Changes | Est. Lines |
|------|---------|------------|
| `/src/pages/statementofworks/show.tsx` | Hero, workflow, sections, tooltips | ~400 |
| `/src/components/sow/sow-workflow-indicator.tsx` | NEW - status flow | ~80 |
| `/src/components/sow/sow-hero-section.tsx` | NEW - compact header | ~120 |
| `/src/components/sow/sow-quick-actions.tsx` | NEW - action bar | ~100 |

### P1 - Should Have

| File | Changes | Est. Lines |
|------|---------|------------|
| `/src/pages/ai/multi-lens-analyzer.tsx` | Executive summary, action buttons | ~150 |
| `/src/utils/multi-lens-analyzer.ts` | Recommendations generation | ~100 |
| `/src/components/sow/sow-related-entities.tsx` | NEW - linkage section | ~80 |

### P2 - Nice to Have

| File | Changes | Est. Lines |
|------|---------|------------|
| `/server/routes/sow.cjs` | Internal numbering (if included) | ~30 |
| `/src/pages/invoices/create.tsx` | Pre-fill from SOW context | ~50 |

---

## Verification Plan

### Before Each Phase Ships

1. **Screenshot** - `pnpm screenshot /statements-of-work/show/[id]`
2. **DAISY Audit** - Check all 10 commandments
3. **Hotel Room Test** - Clean counter? Obvious drawers? Bed made?
4. **Role Lens** - View as CPO, PM, Finance Controller
5. **Click Test** - Every button works, has tooltip

### Full Demo Walkthrough

```
1. Upload PDF (DRS-55025-14.1) on /statements-of-work/create
2. Side panel: See extracted data, validation warnings
3. Click "Apply to Form" → Fields populate
4. Select contractor from dropdown (auto-closes)
5. Fill SOW Type (required)
6. Click "Create" → Redirect to show page with toast
7. Show page: See hero section, workflow indicator
8. Click "Analyze" → See multi-lens results
9. See executive summary, critical alerts
10. Click recommended action → Workflow triggered
11. Click "Create Invoice" → Pre-filled form opens
12. Create invoice → Return to SOW → See linkage
```

---

## Success Criteria

### LEGENDARY Checklist (All Must Pass)

**User Experience:**
- [ ] Full demo flow without confusion or hesitation
- [ ] Every button has tooltip explaining outcome
- [ ] Workflow indicator shows current state + next steps
- [ ] Users would tell someone about it at lunch

**Information Density:**
- [ ] Hero section shows identity + key metrics
- [ ] Financial summary visible without scrolling
- [ ] Empty sections collapsed to single line
- [ ] No wasted whitespace

**Anticipatory Design:**
- [ ] Multi-lens analysis provides actionable recommendations
- [ ] Related entities one click away
- [ ] Pre-fills data when creating linked documents
- [ ] Warns before problems occur

**Visual Consistency:**
- [ ] Colored borders match create page
- [ ] Status colors consistent (green/amber/red)
- [ ] Icons communicate meaning
- [ ] Premium, not generic admin panel

---

## Estimated Effort

| Phase | Priority | Effort | Dependencies |
|-------|----------|--------|--------------|
| Phase 1: Detail Page | P0 | 4-6 hours | None |
| Phase 2: Multi-Lens | P1 | 2-3 hours | Phase 1 |
| Phase 3: Navigation | P1 | 2-3 hours | Phase 1 |
| Phase 4: SOW Number | P2/Defer | 1-2 hours | Decision needed |

**Minimum Viable (P0 only):** 4-6 hours
**Full Scope (P0 + P1):** 8-12 hours
**Everything (P0 + P1 + P2):** 10-14 hours

---

## Open Questions

1. **SOW Number:** Include internal numbering now, or defer for post-demo?
2. **Multi-Lens Location:** Tab on detail page (recommended), side panel, or modal?
3. **Timeline:** Hard demo date that affects scope?

---

## Reference Documents

| Document | Purpose | Location |
|----------|---------|----------|
| UI/UX Design Protocol | DAISY, Hotel Room, density standards | `docs/UI_UX_DESIGN_PROTOCOL.md` |
| Hotel Room Philosophy | UX foundation | `docs/THE_HOTEL_ROOM_PHILOSOPHY.md` |
| Page Type Standards | Detail view requirements | `docs/principles/PAGE_TYPE_STANDARDS.md` |
| Page Review Framework | Scoring system | `docs/principles/PAGE_REVIEW_FRAMEWORK.md` |
| Previous Handoff | v2.5.2 status | `agent-handoff/SOW-Document-Ingestion-...2026-01-09.md` |
| Multi-Lens Context | Current implementation | `agent-handoff/LEGENDARY_MULTI_LENS_CONTEXT_...md` |

---

**Plan Status:** Ready for review. Awaiting decision on open questions before implementation.