atlas-os/patterns/CLUSTER_THEN_POLISH.md

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.

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.