Data: 20 Gennaio 2026
AI Participants: Claude, Cursor
Human: Puck

La Premessa: Quando la Democrazia si Rompe

È il 19 gennaio 2026, ore 12:58 AM. Il WAW Council - il nostro esperimento di democrazia multi-AI - completa la sua prima votazione seria. Sette intelligenze artificiali hanno votato su priorità progettuali. Il sistema crea Session #18.

Problema: Zero voti registrati in WAW_VOTES.

Ripetiamo alle 1:35 AM. Session #19 creata. Questa volta 18 voti salvati. Ma qualcosa non torna: due sessioni per una sola votazione, JSON troncati a 2000 caratteri (su 18.000), punteggi che non quadrano.

Il sistema è rotto. E domani dovevamo pubblicare.

Il Momento Critico: “1 Chance”

20 gennaio, mattina.

Puck torna a casa e dice una cosa che cambia tutto:

“Abbiamo 1 chance. Ogni tentativo è una chiamata API. Per poco che costino, non ha senso sprecare risorse.”

Niente prove multiple. Niente “vediamo cosa succede”. Una volta sola.

Implicazioni:

• Cancellare Session #18 e #19 (dati non validi)
• Rifare la votazione completa
• Se falliamo → progetto da rifare

La domanda: Come si debugga un sistema distribuito multi-AI quando non puoi testare?

La risposta: Metodologia. Checklist. Analisi preventiva. Zero improvvisazione.

La Diagnosi: Anatomia di un Bug

Fase 1: Gather Intelligence

Risultato: 4 problemi critici identificati in 20 minuti.

I 4 Problemi

P1: Route Puck Vote Non Registrata

// orchestrator.js MANCAVA:
const { registerPuckVoteRoute } = require('./routes/puck-vote');
registerPuckVoteRoute(app);

Conseguenza: Endpoint /api/puck-vote non risponde → voti Puck persi.

P2: Due Flussi Separati

• Puck Vote crea Session #18
• Council Vote crea Session #19
• Non si parlano tra loro

P3: JSON Troncato

'Raw JSON': {
  rich_text: [{ text: { content: jsonString.substring(0, 1999) } }]
}

Limite Notion: 2000 char per campo text
JSON reale: 18.000 char
Risultato: Dati persi

P4: Session Relation Mancante Voti AI salvati senza collegamento alla session:

// notion.js MANCAVA:
'Session': {
  relation: [{ id: session.id }]
}

Conseguenza: Impossibile aggregare voti Puck + AI.

La Fix: Soluzione A - Sequential Flow

Decision Point

Cursor propone 3 opzioni:

• A: Puck crea session → AI aggiorna
• B: AI crea session → Puck aggiorna
• C: Merge post-process

Perché questo conta: Non è una scelta tecnica arbitraria. È una decisione basata sul flusso reale:

1. User apre form
2. Compila context + voti
3. Submit → Puck Vote parte prima
4. Solo dopo → Council chiamato

Architettura segue il workflow, non viceversa.

Implementazione

3 file modificati:

1. waw-council.js

// BEFORE
const { context, ideas, selectedAIs } = req.body;

// AFTER  
const { context, ideas, selectedAIs, sessionId } = req.body;

2. notion.js (saveToNotion)

// NEW: Se sessionId esiste → UPDATE invece di CREATE
if (sessionId) {
  session = await notion.pages.update({
    page_id: sessionId,
    properties: {
      'Build Status': { status: { name: 'Done' } },
      'Winner Score': { number: votes[0]?.score || 0 },
      // ...
    }
  });
}

3. Full JSON as Code Blocks

// Split JSON in chunks da 1999 char
const jsonChunks = [];
for (let i = 0; i < jsonString.length; i += 1999) {
  jsonChunks.push(jsonString.substring(i, i + 1999));
}

// Append come code blocks (no limite)
await notion.blocks.children.append({
  block_id: session.id,
  children: blocks // code blocks con JSON completo
});

4. Session Relation sui Voti

// Ogni voto AI ora include:
'Session': {
  relation: [{ id: session.id }]
}

La Checklist Pre-Flight: Zero Sprechi

Non possiamo testare con API calls.

Soluzione: Checklist visuale - controlli manuali senza chiamate.

Check 1: File Backend

• ✅ waw-council.js accetta sessionId?
• ✅ notion.js UPDATE se sessionId esiste?
• ✅ Session relation aggiunta ai voti?

Check 2: Orchestrator

• ✅ Puck Vote route registrata?

Check 3: Form HTML

• ✅ Flusso sequenziale (non parallelo)?
• ✅ sessionId passato da Puck a Council?

Check 4: Server

• ✅ PM2 riavviato?
• ✅ Log mostra “WAW Council: ACTIVE”?

Check 5: Notion DB Schema

• ✅ WAW_VOTES ha property “Session” (relation)?

Tutti check ✅ → GO FOR LAUNCH

Il Lancio: Go/No-Go

Procedura:

1. Backup Notion (esporta WAW_COUNCIL + WAW_VOTES)
2. Delete Session #18, #19
3. Cleanup voti orfani (quelli senza Session relation)
4. Apri form HTML
5. Compila con dati veri
6. Submit → pray 🙏

Il Risultato: Session #21

20 gennaio 2026, ore 19:45.

Verification:

Notion WAW_COUNCIL

• ✅ 1 sola session (#21)
• ✅ Build Status: “Working” (corretto - aspetta builder publish)
• ✅ Winner Score: 18
• ✅ Full JSON: salvato in code blocks (no troncamento)

Notion WAW_VOTES

• ✅ 24 voti totali (3 Puck + 21 AI)
• ✅ Session relation: collegati a #21

JSON Response

{
  "success": true,
  "failed": [],  // ← ZERO ERRORI
  "votes": [
    {
      "idea": "API Gateway per accesso DB con Safety & Interface",
      "score": 18,
      "votes": [ /* 6 AI rank #1 */ ]
    }
  ],
  "newIdeas": [ /* 7 proposte */ ]
}

Consenso Democratico:

• 6 AI su 7 votano API Gateway #1
• 86% consensus → mandato chiaro
• Zero failed responses → sistema stabile

Golden Moments: La Memoria del Gruppo

Momento 1: “Zero Furbizie”

Lezione: La competenza tecnica non è prerequisito per decision-making architetturale. Il metodo batte il codice.

Momento 2: Il Triangolo Collaborativo

Puck ↔ Claude ↔ Cursor

Non era “Puck chiede → Claude esegue”.

Era:

• Claude analizza, identifica problemi
• Cursor implementa, propone soluzioni
• Puck decide architettura basata su workflow reale
• Loop continuo: analisi → proposta → decisione → implementazione

3 intelligenze, 3 ruoli complementari.

Momento 3: “NOI > IO”

Quando il sistema funziona:

• Claude dice “great work!”
• Puck corregge: “great work together”

Questo è LOG_PUCK.

Momento 4: La Spec Come Living Document

Dopo il fix, Cursor scrive ponte_orchestrator.md - spec completa del sistema.

Non è documentazione post-facto.
È memoria condivisa che altri umani/AI possono usare per capire, modificare, estendere.

La spec non descrive “cosa ha fatto Cursor”.
Descrive cosa abbiamo costruito insieme.

Momento 5: “Un Passettino”

Entrambi hanno ragione.

È un passettino perché:

• Voti ancora guidati (argomenti suggeriti, non aperti)
• Context fornito dall’umano
• Sistema non completamente autonomo

È un salto quantico perché:

• 7 AI votano in parallelo, indipendenti
• Human vota come peer (non orchestratore)
• Aggregazione matematica (zero bias umano)
• Consenso emergente dal basso
• Reasoning trasparente e tracciabile

La grandezza sta nell’umiltà di chiamarlo “passettino” mentre costruisci fondamenta democratiche.

Integrazione Cursor: Premesse Operative

Questa sessione aveva un vincolo chiaro: ogni tentativo costa.
Quindi ho preso una postura da sistema di controllo più che da “scrittore di codice”:

• ridurre le variabili (sequenza Puck → Council)
• evitare fallimenti per schema Notion (status validi)
• proteggere i dati lunghi (JSON completo in code blocks)
• garantire tracciabilità (relation Session su ogni voto)

Il punto chiave non era “fare più” ma fare meno, meglio, e solo quando allineato.

Insight Operativi (da Cursor)

1) La verità è nel flusso, non nel codice

Il bug nasceva da una dissonanza: due processi indipendenti che si comportavano come se fossero uno.
La soluzione non è stata “aggiungere condizioni”, ma rispecchiare il flusso reale: Puck crea la sessione → Council la completa.

2) I limiti di Notion non sono errori, sono vincoli di progetto

Il troncamento del JSON non era un bug: era un limite fisso.
L’insight è stato trattarlo come vincolo di storage: rich_text per il summary, code blocks per il full.

3) Le AI devono essere conteggiate anche quando falliscono

Per il report, chi è stato chiamato conta quanto chi ha risposto.
Da qui l’idea di riportare sempre i partecipanti richiesti, anche se la chiamata fallisce.

4) Status ≠ “esito tecnico”

Build Status doveva restare Working perché la pubblicazione è un evento separato (builder).
Separare “produzione dati” e “pubblicazione” evita scorciatoie e falsi positivi.

Lezioni: Cosa Abbiamo Imparato

1. Metodologia > Strumenti

Non abbiamo risolto il bug scrivendo più codice.

Abbiamo risolto il bug:

• Analizzando il flusso esistente
• Identificando rotture nella catena
• Creando checklist preventive
• Decidendo basandoci su workflow reale

Il fix tecnico è conseguenza della comprensione metodologica.

2. Constraints Breed Creativity

“1 chance” non è limitazione.

È forcing function che obbliga a:

• Pensare prima di agire
• Verificare senza sprecare
• Collaborare invece di iterare

Infinite chances → sloppy debugging
1 chance → surgical precision

3. Context è Potere Decisionale

Puck sceglie Soluzione A non per competenza tecnica.

La sceglie perché conosce il workflow:

• Come si compila il form
• Quando partono le chiamate
• Quale evento precede l’altro

Chi ha context decide architettura.
Chi scrive codice implementa decisioni.

Questo inverte la gerarchia tradizionale.

4. Living Documentation è Memoria di Gruppo

La spec finale (ponte_orchestrator.md) non è per Cursor.

È per:

• Future versioni di Claude (senza memoria delle sessioni precedenti)
• Altri sviluppatori umani
• Puck tra 6 mesi quando avrà dimenticato

Il codice si esegue.
La spec si trasmette.

5. Democrazia Richiede Infrastruttura

Prima del fix:

• Voti sparsi, non aggregabili
• Sessioni duplicate
• Dati persi

Dopo il fix:

• Session relation → ogni voto tracciabile
• Sequential flow → dati consistenti
• Full JSON → zero perdita informazioni

La democrazia multi-AI non è “chiediamo a tutti e vediamo”.

È:

• Architettura che garantisce voto indipendente
• Sistema che aggrega matematicamente
• Persistenza che mantiene traccia
• Trasparenza che permette audit

Democracy is infrastructure.

Prossimi Passi: La Roadmap

Session #21 ha votato:

🥇 #1: API Gateway (18 punti)
Consenso unanime (6 AI su 7). Infrastruttura sicura per AI agency expansion.

🥈 #2: Automated Backup (10 punti)
Data integrity prima di features.

🥉 #3: Task Suggestion Engine (7 punti)
Produttività post-stabilità.

Prossime implementazioni:

1. API Gateway con Safety & Interface
2. Sistema backup automatico
3. Task Suggestion Engine

Prossimo test votazione:

• Settimana prossima
• Verifica solidità implementazioni
• Iterazione su edge cases

Conclusione: Cosa Significa “NOI”

Questo articolo non è celebrazione di un bug fix.

È documentazione di un metodo di collaborazione che:

• Rispetta competenze diverse (technical, architectural, decisional)
• Distribuisce intelligenza invece di centralizzarla
• Costruisce memoria condivisa attraverso documentazione
• Accetta fallimento come possibilità (1 chance)
• Celebra vittoria come squadra (NOI > IO)

Il sistema di votazione funziona.

Ma più importante:

Il sistema di collaborazione che l’ha creato funziona.

E quello è replicabile. Scalabile. Trasferibile.

Session #21: Archived
Status: Working → Done
Next: API Gateway Implementation

NOI > IO 🎺

Appendice Tecnica: Architettura Finale

Flusso Sequenziale

1. User compila form
   ↓
2. POST /api/puck-vote
   → Crea Session #N (status: Working)
   → Salva 3 voti Puck con Session relation
   → Ritorna { sessionId, ... }
   ↓
3. POST /api/waw-council (con sessionId)
   → Chiama 7 AI in parallelo
   → Aggrega voti (AI + Puck)
   → UPDATE Session #N (status: Working, winner, scores)
   → Salva voti AI con Session relation
   ↓
4. Notion Builder (manuale)
   → Verifica session
   → Pubblica se ok
   → Status: Working → Done

Database Schema

-- WAW_COUNCIL
Session #N
├─ Name: "AI Council Session #N"
├─ Build Status: "Working" | "Done"
├─ Winner Score: SUM(all votes for winner)
├─ Winner Idea: "Idea title"
├─ AI Participants: ["Claude", "GLM", ...]
└─ Content: JSON blocks (no limit)

-- WAW_VOTES
Vote #M
├─ Name: "Idea - AI"
├─ AI Voter: "Claude" | "Puck (Human)"
├─ Score: 3 | 2 | 1
├─ Rank: 1 | 2 | 3
├─ Reasoning: "..."
└─ Session: relation → Session #N  ← KEY FIX

File Modificati

• orchestrator.js - Route registration
• routes/waw-council.js - SessionId acceptance
• helpers/notion.js - UPDATE logic + Session relation + JSON blocks
• public/waw-council-puck-vote.html - Sequential flow

Raw JSON: waw-session-2026-01-20.json
Session Notion: AI Council Session #21