# Pattern: Cluster-then-Polish

> Local 7B-8B models generate volume. Claude / human polishes signal.

## Problem

Open-source LLMs (qwen2.5:7b, llama3.1:8b, hermes3:8b on consumer hardware) are good at:
- Classification / categorization
- Embeddings / RAG retrieval
- Code completion (within trained languages)
- Structured output (JSON, tables)
- Triage of inbox / queues at volume

They are **bad** at:
- Narrative copywriting for clients
- Strategic analysis without grounded data
- Tone / voice consistency
- Factual claims — they will hallucinate numbers, dates, names
- Anything where wrong output sent externally has cost

## Pattern

1. Cluster generates a first draft with explicit `polish_status: pending` YAML frontmatter
2. Output saved as Markdown file with full metadata (node, model, elapsed_s, prompt, draft_id)
3. Polish review queue tracked in `~/.config/atlas/drafts/_registry.json`
4. Operator OR a stronger model (Claude, GPT-4) reviews + edits + flips frontmatter to `polish_status: polished`
5. Only `polished` items are usable externally (sent to clients, published, etc.)

## Reference implementation

`scripts/cluster_then_polish.py` — simple wrapper around any Ollama-compatible HTTP API.

```python
from cluster_then_polish import draft, save_draft

d = draft(
    prompt="Schrijf cold-WhatsApp voor Tilburg lunchroom",
    task='chat',
    node_pref='pc',
    purpose='cold_outreach',
)
save_draft(d, '~/.config/atlas/drafts/lunchroom_outreach_001.md')
# operator reviews -> mark_polished(d['draft_id'])
```

## Real-world data (production)

After 7.5 hours of perpetual loop across 3 nodes:
- 1172 autonomy outputs generated
- ~5-10% immediately useful (operator polishes light)
- ~30% spark a useful follow-up question
- ~60% are noise (still saved for pattern detection later)
- 0% should be sent externally without review

The pattern is not "less work" — it is "different work". Operator becomes editor, not writer. The cluster does the cold-start text generation that's the worst part of writing.

## When NOT to use this pattern

- When you have Claude API access and the task is small enough to just call Claude directly
- When the output must be perfect (legal documents, financial figures, contracts)
- When you don't have a polish step set up — generating drafts you never review is worse than no drafts

## Anti-pattern to avoid

Don't trust cluster output because it "looks confident". 7B models will produce well-formatted Dutch with hallucinated company names, wrong euro amounts, invented words. Production example:

> qwen2.5:7b output: "Bisogno's marktshare neemt toe met €4.578 miljoen, Inbrengking bleef stabiel"
>
> Reality: revenue is €4,578 (not millions), "Inbrengking" is not a Dutch word, "marktshare" was confused with revenue concentration percentage.

The `polish_status: pending` flag exists because of this exact failure mode.