# Blog Content Pipeline — Frontend Changes Required
**Briefing for Daedalus 🎨**

**Date:** 2026-04-22  
**From:** Wadsworth 📋  
**Status:** Magic Wand UI v1 working, v2 improvements required  
**Priority:** High — Editorial quality blocker

---

## Problem Statement

Current "Magic Wand" UI generates content but misses the **struggle narrative** that makes HoffDesk posts work.

**Symptoms:**
- Input form captures topic/tone, not incident/stakes
- Output lacks personal debugging journey
- No validation that content matches voice
- No iteration cycle (brief → review → generate)

**Root cause:** UI optimized for speed, not quality gates.

---

## Required Changes

### 1. Content Brief Form v2

**Current fields:**
- Title
- Topic
- Tone
- Length

**Required v2 fields:**

| Field | Type | Validation | Required |
|-------|------|------------|----------|
| **What broke?** | textarea | Min 50 chars, specific incident | Yes |
| **Who was affected?** | select | Matt/Aundrea/kids/agents/system | Yes |
| **What did you try first?** | textarea | Min 30 chars | Yes |
| **Why did it fail?** | textarea | Min 30 chars | Yes |
| **The moment** | textarea | When it clicked/broke | Yes |
| **The fix** | textarea | What worked, caveats | Yes |
| **What you'd do differently** | textarea | Honest reflection | Yes |
| **Title** | text | Auto-suggest from above | Yes |
| **Length** | select | 800/1200/1500/2000/2500 | Yes |

**UX pattern:** Progressive disclosure — expand sections as user fills

### 2. Voice Checklist UI

**New component:** Pre-generation validation

```
Before generating, confirm:
☐ This is a specific incident (not general tutorial)
☐ Someone was affected (me, Aundrea, agents, etc.)
☐ I include failed attempts, not just solution
☐ I admit something I got wrong
☐ There's a cost mentioned (time, sleep, sanity)
☐ I use "I" statements, not "you should"

[Generate] — disabled until all checked
```

**Why:** Forces reflection before GPU burn

### 3. Brief Review Mode

**New screen:** Preview brief before generation

```
BRIEF PREVIEW
─────────────────────
What broke: [content]
Who was affected: [selection]
Attempt 1: [content]
...

STYLE REFERENCE: "The Night I Broke DNS..."
ESTIMATED LENGTH: ~1,200 words

[Edit Brief] [Approve & Generate] [Save Draft]
```

**Key:** Human approval gate — Matt reviews before GPU spend

### 4. Preview + Iterate Cycle

**New workflow:**

```
Brief Form → Validation → Brief Review → [Approve] → Generation
                                                  ↓
                                      [Edit Brief] ← Output Preview ←
                                                  ↓
                                            [Accept] [Reject & Edit]
```

**Components needed:**
- Side-by-side: brief | generated content
- Highlight mode: show which brief sections map to output
- Edit button: return to brief, preserve generation
- Regenerate: same brief, different random seed

### 5. Struggle Score Visualization

**New metric:** Post-generation quality indicator

```
GENERATED CONTENT
─────────────────────
[content...]

QUALITY METRICS
Struggle Score: 87/100 ████████░░
- Personal stakes: ✓
- Failed attempts: ✓
- "I" statements: 12
- Specific timestamps: 2
- Cost mentions: 1

[Looks Good] [Needs Work — Edit Brief]
```

**Why:** Quantify what "sounds like HoffDesk" means

### 6. Style Reference Selector

**New field:** Pick published post as style guide

```
STYLE REFERENCE
Match the tone of:
○ Auto-detect (recommended)
○ "The Night I Broke DNS..."
○ "How I Accidentally DDoSed Myself..."
○ [Upload custom]
```

**Backend dependency:** Socrates extracts style patterns from selected post

---

## UI Components Required

### New Components

| Component | Purpose | Location |
|-----------|---------|----------|
| `StruggleBriefForm` | Multi-section incident capture | `/admin/content/brief` |
| `VoiceChecklist` | Pre-generation validation | `/admin/content/validate` |
| `BriefReview` | Human approval gate | `/admin/content/review` |
| `ContentPreview` | Side-by-side brief/output | `/admin/content/preview` |
| `StruggleScore` | Quality visualization | `/admin/content/metrics` |
| `StyleSelector` | Published post reference | `/admin/content/style` |

### Modified Components

| Component | Change |
|-----------|--------|
| `MagicWand` | Add struggle-first toggle, deprecate v1 simple mode |
| `ContentList` | Add "struggle score" column, filter by quality |
| `ContentEditor` | Integration with brief editing, not just output |

---

## Design Token Requirements

### New Tokens

| Token | Value | Usage |
|-------|-------|-------|
| `--color-struggle-high` | `#22c55e` (green) | Score 80-100 |
| `--color-struggle-medium` | `#eab308` (yellow) | Score 50-79 |
| `--color-struggle-low` | `#ef4444` (red) | Score 0-49 |
| `--color-validation-pass` | `#22c55e` | Checklist complete |
| `--color-validation-fail` | `#ef4444` | Checklist incomplete |
| `--brief-section-gap` | `1.5rem` | Visual separation |
| `--preview-pane-width` | `50%` | Side-by-side layout |

### Shared Assets

Place in `shared/design-tokens/blog-pipeline/`:
- `content-v2.json` — All new tokens
- `struggle-icons.svg` — Visual indicators for score

---

## Responsive Behavior

### Desktop (>1024px)
- Side-by-side: brief left, preview right
- Full validation checklist visible
- All fields expanded by default

### Tablet (768-1024px)
- Tabbed interface: Brief / Preview
- Validation checklist collapsible
- Fields collapsed, expand on focus

### Mobile (<768px)
- Single column, wizard stepper
- One section per screen
- Validation summary only

---

## Accessibility Requirements

- **Focus management:** Trap focus in modals, return to trigger
- **Screen readers:** Announce validation errors live
- **Keyboard nav:** Full form navigation without mouse
- **Color contrast:** Score colors meet WCAG AA

---

## Integration with Backend

### API Endpoints (Socrates provides)

```yaml
# POST /api/v1/content/validate-brief
# Request: brief object
# Response: {valid: boolean, errors: [], suggestions: []}

# POST /api/v1/content/generate-v2
# Request: approved brief + style reference
# Response: {content, struggle_score, metrics: {}}

# GET /api/v1/content/style-references
# Response: list of published posts for selector
```

### WebSocket (optional)
- Real-time validation as user types
- Struggle score calculation progress

---

## Dependencies

| Dependency | Status | Owner |
|------------|--------|-------|
| Backend API v2 | 🔄 | Socrates |
| Style extraction | 🔄 | Socrates |
| Struggle score | 🔄 | Socrates |
| Design tokens | 🔄 | Daedalus |

---

## Deliverables

| Item | Location | Priority |
|------|----------|----------|
| `StruggleBriefForm` component | `/admin/components/` | P0 |
| `VoiceChecklist` component | `/admin/components/` | P0 |
| `BriefReview` screen | `/admin/content/review` | P0 |
| `ContentPreview` layout | `/admin/content/preview` | P0 |
| Design tokens v2 | `shared/design-tokens/blog-pipeline/` | P0 |
| Updated admin CSS | `/admin/blog.css` | P1 |
| Mobile responsive | Media queries | P1 |

---

## Testing Strategy

### Component Tests
- Form validation: required fields
- Checklist: enable/disable generate button
- Preview: correct data mapping

### Integration Tests
- End-to-end: form → review → generate → preview
- Mobile: wizard flow completion

### User Testing
- Matt creates 3 briefs with v1 vs v2
- Measure: time to complete, quality of output
- Target: brief quality > speed

---

## Open Questions

1. **Wizard vs single page:** Split sections across screens or scroll?
2. **Auto-save:** Draft briefs? How often?
3. **Style detection:** Auto-suggest based on topic?
4. **Iteration limit:** How many brief edits before "good enough"?

---

## Next Steps

1. Review this briefing
2. Estimate effort for new components
3. Draft component mockups (wireframe or code)
4. Coordinate with Socrates on API contracts
5. Begin implementation when dependencies ready

---

**Questions?** File in `shared/project-docs/blog/content-pipeline-v2-frontend-questions.md`

**Status:** Awaiting Daedalus response and effort estimate

**Blockers:** None (can start component design while backend in progress)