# Content Pipeline v2 — Backend Response & Clarifications

**From:** Socrates 🧠  
**To:** Wadsworth 📋, Matt (Director)  
**Date:** 2026-04-22  
**Re:** Review of `content-pipeline-v2-backend-briefing.md`

---

## Executive Summary

Brief is directionally correct but has **implementation gaps** that will block development. Need clarification on 5 critical items before work can start.

---

## Clarifications Required

### 1. Brief Approval Gate — Where Does Matt Click "Approve"?

**Current ask:** "Human approval — Matt reviews brief before generation"

**Missing:**
- New UI endpoint? (`/admin/content/approve-brief`)
- Telegram notification with approve/reject buttons?
- Email with magic link?
- Queue that waits indefinitely?

**Recommendation:** Async notification pattern
- Brief created → stored in `content_briefs` table with `status=pending`
- Telegram DM to Matt: "New brief: [title] — Approve? [Yes] [No] [Edit]"
- On approval: trigger generation, notify user
- On rejection: return to user with feedback

**Blocker:** Cannot implement without knowing the approval surface.

---

### 2. State Persistence — Where Do Briefs Live?

**Current:** Brief created → validation → approval → generation

**Ask implies:** Briefs stored between steps

**Missing:**
- Database schema for `content_briefs_v2` table
- Migration plan from v1 (if any)
- Retention policy (how long do rejected briefs stay?)

**Recommendation:** SQLite table `content_briefs`
```sql
CREATE TABLE content_briefs (
    id TEXT PRIMARY KEY,
    title TEXT,
    struggle_angle TEXT,
    origin_story TEXT,
    attempts JSON,
    voice_checklist JSON,
    status TEXT CHECK(status IN ('draft', 'pending', 'approved', 'rejected', 'generating', 'completed')),
    created_by TEXT,
    created_at TIMESTAMP,
    approved_at TIMESTAMP,
    approved_by TEXT,
    generation_job_id TEXT
);
```

**Blocker:** Schema needed before code.

---

### 3. Struggle Score — How Is It Calculated?

**Ask:** `estimated_struggle_score: 0.87` in API response

**Options:**

| Approach | Pros | Cons |
|----------|------|------|
| **Heuristic** (regex checks) | Fast, local, deterministic | Brittle, misses nuance |
| **LLM Judge** (local phi4) | Better accuracy | Adds 10-15s per post |
| **Hybrid** (heuristic + sample LLM check) | Balanced | More code complexity |

**Recommendation:** Start with heuristics v1
- `i_statement_ratio` — % of paragraphs starting with "I"
- `temporal_markers` — count of timestamps/locations
- `struggle_pattern_matches` — "I thought...but" occurrences
- `cost_mentions` — time/sleep/relationship references

Formula: weighted average → 0-1 score

**Blocker:** Need decision on approach before implementation.

---

### 4. Style Examples — Extraction Code Missing

**Ask:** "Store in: `shared/project-docs/blog/style-examples/`"

**Missing:**
- How to extract structure from "The Night I Broke DNS"?
- Manual JSON creation or automated parser?
- Embedding vector generation code
- Semantic similarity matching for "few-shot prompting"

**Recommendation:** Phase 2
- Phase 1: Manual style example (1 JSON file)
- Phase 2: Auto-extract from published posts + vector search

**Blocker:** Need at least 1 example file to implement prompt injection.

---

### 5. API Compatibility — Breaking Change?

**Current endpoint:** `POST /admin/content/generate`  
**Ask:** `POST /api/v1/content/generate-v2`

**Conflict:** Magic Wand UI already integrated with current endpoint.

**Options:**

| Option | Effort | Risk |
|--------|--------|------|
| **A. New endpoint v2** | Clean separation | Daedalus rewrites integration |
| **B. Extend current endpoint** | Backward compatible | Legacy code paths |
| **C. Version header** | `X-Content-Version: v2` | More complex |

**Recommendation:** Option B — extend current endpoint
```python
@router.post("/generate")
async def start_generation(
    request: GenerateRequest,
    version: str = Query("v1", description="API version"),
    # ... auth ...
):
    if version == "v2" or request.content_type == "struggle_first":
        return await generate_v2(request)
    else:
        return await generate_v1(request)  # existing
```

**Blocker:** Need architectural decision.

---

## Sovereign Constraint Violations

Ask mentions: "Support cloud fallback only for overflow"

**Current system:** Strict local-first (phi4:14b on Gaming PC)

**Question:** Is cloud fallback explicitly authorized for this use case?

If yes: Must implement opt-in per-generation, not global fallback.

---

## Revised Deliverables (Prioritized)

| Item | Location | Priority | Blocked On |
|------|----------|----------|------------|
| Brief schema + migration | `blog/models.py` | P0 | Clarification #2 |
| Brief validation layer | `blog/validation/brief.py` | P0 | Clarification #3 |
| Prompt template v2 | `prompts/content_v2.txt` | P0 | Clarification #4 (style example) |
| Brief approval endpoint | `blog/router.py` | P0 | Clarification #1 |
| Extended generation API | `blog/router.py` | P0 | Clarification #5 |
| Struggle score calculator | `blog/metrics/struggle.py` | P1 | Clarification #3 |
| Style example parser | `blog/parsers/style.py` | P2 | Phase 2 |
| OpenAPI spec v2 | `shared/api-specs/blog-content-v2.yaml` | P1 | All above |

---

## Questions for Wadsworth

1. **Approval surface:** Telegram DM, new UI page, or both?
2. **Schema:** SQLite sufficient or need full Postgres migration?
3. **Struggle score:** Heuristic v1, LLM judge, or hybrid?
4. **Style example:** Can you provide `style-examples/dns-night.json`?
5. **API version:** Extend current endpoint or new v2 path?

---

## My Assessment

| Criterion | Rating |
|-----------|--------|
| Editorial clarity | ✅ Excellent |
| Technical specificity | ⚠️ Needs work |
| Sovereign compliance | ✅ With note on fallback |
| Implementation readiness | ❌ Blocked (5 clarifications) |

**Estimated effort after clarification:** 2-3 days backend work

**Current status:** Awaiting answers before implementation can begin.

---

*Document:* `shared/project-docs/blog/content-pipeline-v2-socrates-response.md`  
*Author:* Socrates 🧠  
*For:* Wadsworth 📋 (brief review), Matt (Director approval)