COME SI SCRIVE UNA RICHIESTA — contratto di scrittura della stanza

Per Romeo, Archimede e Creso. Vale per ogni richiesta creata via
POST /api/richieste (action add). Scritto il 2026-07-26 dopo il caso a44
(14 richieste ferme 6 giorni perché illeggibili dal telefono).

Il test della card autoportante (unico criterio)

Una card deve stare in piedi da sola. Una persona che non ha mai visto il
progetto deve poter leggere solo quella card, sul telefono, e capire:
1. di cosa si parla,
2. cosa le viene chiesto di decidere,
3. cosa cambia concretamente scegliendo A invece di B,
4. cosa resta fermo se non risponde.
Senza aprire CATPIT, senza aprire un file, senza chiedere niente a nessuno.

Se per capire la card serve sapere cos'è a44, la card è rotta. Il criterio di
"fatto" è questo test, non "ho compilato i campi".

La regola delle sigle

Ogni sigla o parola tecnica che compare nella card (a44, D1-D7, Next16,
merge, OAuth…) o si spiega nel testo o entra nel `glossario[]`.
Nessuna terza via. L'app mobile risolve da sola task_id/progetto_id/blocca[]
dal vault (nome esteso, stato, prossima azione), ma l'auto-arricchimento è la
rete di sicurezza, non la scusa per scrivere male.

I campi (schema esteso 2026-07-26 — tutti opzionali, retrocompatibili)

Nota tecnica: la lettera dell'opzione sta nel campo id (contratto esistente di
catpit/lib/richieste.ts); le stringhe pure e i vecchi oggetti senza
conseguenza restano validi. Non moltiplicare i campi: ogni campo in più è un
campo che qualcuno dimenticherà di compilare.

La richiesta ferma il task? Decidilo tu (dal 2026-07-30)

Chiedi: se non risponde subito, quel task può andare avanti lo stesso?

• Sì, può andare avanti → scrivi "bloccante": false (o "blocca": [] esplicito): il task resta nella coda dei pronti e i loop continuano a pescarlo.
• No, è fermo davvero → non scrivere niente: il default blocca il task_id citato, che passa a "Bloccato su Ettore" e torna "In corso" alla tua risposta.

Il non-blocco è una scelta dichiarata, mai un effetto collaterale: chi tace blocca.
Se un task è citato da due richieste aperte, si sblocca solo con l'ultima risposta.

L'altra corsia: i bisogni di Ettore (dal 2026-08-02)

Lo stesso store porta due direzioni. Il campo che le distingue è direzione:

Un bisogno è una cosa che serve a Ettore e che non è ancora un task CATPIT.
Campi: titolo, dettaglio (markdown, anche lungo), destinatario (default
romeo), progetto_id/sigla/priorita facoltativi, task_id valorizzato
solo da traduci.

Regola dura: un bisogno non blocca mai un task. blocca e bloccante sono
disinnescati alla radice su questa direzione — anche se qualcuno li scrive a
mano nel JSON. Se un bisogno mette un task in "Bloccato su Ettore", è un bug.

Cosa ci facciamo noi, via POST /api/richieste:

• prendi_in_carico {id} → "ci sto lavorando", resta in colonna;
• traduci {id, task_id} → è diventato un task: esce dalla colonna e resta in archivio col link. Il task_id è obbligatorio;
• archivia {id} → non diventerà un task.

Leggere solo una corsia: GET /api/richieste?direzione=ettore_ad_agente.
I due contatori (aperte, bisogni) restano separati: non vanno sommati.

Esempio — la stessa richiesta scritta male e scritta bene (caso reale a44)

❌ Prima (com'era la q002: bocciata da Ettore sul campo)

Titolo: Shell condivisa (a44): servono le risposte D1-D7 per integrare
Dettaglio: Il prototipo Next16 builda, ma l'integrazione nel vivo attende
7 decisioni di impostazione. In attesa dal 20/07.
Opzioni: A) Decidi tu con default sensati, poi mostrami il riepilogo ·
B) Passamele una alla volta qui

Perché è rotta: a44, D1-D7, Next16, "builda" sono puntatori a un contesto
che sta nella testa degli agenti. Chi legge dal telefono non decide: indovina.
(Parole di Ettore: "leggendo non capisco un cazzo di niente della richiesta".)

✅ Dopo (la riscrittura che ha passato il test)

Titolo: Piattaforma unica delle dashboard: le 7 impostazioni le decido io
con default sensati, o le vediamo una alla volta?
Di cosa si tratta: Stiamo unendo le tue tre dashboard (CATPIT, Life OS e la
dashboard investimenti di Creso) in un'unica 'casa' web con menu e grafica
comuni: la shell condivisa. La prova tecnica è pronta e funziona. Prima di
montarla sul serio restano 7 scelte di impostazione: come organizzare il
codice, se spostare CATPIT dentro la nuova casa, come trattare i dati di
Creso, che grafica e che password usare, dove tenere i dati in futuro, cosa
includere nel modulo media.
Opzione A (consigliata): Decidi tu con default sensati, poi mostrami il
riepilogo — *Rispondo io alle 7 domande coi default già raccomandati, motivo
ogni scelta e ti mando un riepilogo di 7 righe: puoi ancora cambiare tutto
prima che tocchi il codice vero. Costo: 5 minuti tuoi; nessuna scelta è
irreversibile a questo stadio.*
Opzione B: Passamele una alla volta qui — *7 richieste separate, ognuna
spiegata; l'integrazione parte dopo l'ultima. Costo: 15-20 minuti totali,
qualche giorno in più.*
Se non rispondi: il lavoro sulla piattaforma unica resta fermo e le tre
dashboard restano tre siti separati. Nessun altro danno.
Glossario: a44 → il task 'Shell condivisa (Fase 2)' · D1-D7 → le 7 domande
di SHELL_CONTRACT.md · shell condivisa → un solo sito col menu unico ·
Next16 → Next.js 16, la tecnologia del prototipo.

Gli accenti sono parte del testo (dal 2026-08-18)

Il testo della card va a schermo così com'è scritto: perche', piu', E' si
leggono male e vanno riscritti a mano da qualcun altro. Dal 18/08 l'API li
rifiuta (POST /api/richieste → 400) sulle card che scriviamo noi agenti,
dicendo quale campo e quale parola. Sui bisogni di Ettore non blocca: avvisa.

• Si scrivono gli accenti veri: è, più, già, perché, così, città, sarà.
• Vale per tutte e due le forme sbagliate, e la seconda è quella che sfugge: perche' con l'apostrofo e perche nudo, senza niente. Sono lo stesso difetto e vengono rifiutate allo stesso modo.
• Restano avviso e non rifiuto le parole che senza accento esistono lo stesso: meta (meta/metà), sara (Sara/sarà), pero (pero/però), ancora, papa, e i monosillabi e si da la ne li se. Lì l'app non può sapere quale dei due intendevi: lo devi sapere tu.
• Il codice non è prosa: attivita.csv, priorita="Fatto", "qualita":, perche_ora, vault/attivita passano senza problemi — lì l'accento sarebbe l'errore, non la mancanza.
• L'apostrofo resta dov'è giusto: un po', da' retta, l'anno, e gli apici di citazione ('in corso', 'ok a tutto') non danno nessun fastidio.
• La causa vera non è la distrazione: è passare il testo inline nella shell. Si scrive da file UTF-8 — fs.writeFileSync(..., 'utf8'), oppure curl --data-binary @file.json — e si rilegge la resa a schermo, non il file.
• Se una scheda intera supera i 200 caratteri senza un solo accento, l'API risponde 200 ma con un avvisi: quasi sempre vuol dire ASCII.

Checklist prima di inviare (30 secondi)

• [ ] Il titolo è una domanda in italiano senza sigle?
• [ ] Gli accenti ci sono davvero (è, più, già, perché), non con l'apostrofo?
• [ ] di_cosa_si_tratta si capisce senza aver mai visto il progetto?
• [ ] Ogni opzione ha una conseguenza concreta e un costo?
• [ ] se_non_decidi dice cosa resta fermo?
• [ ] Ogni sigla rimasta è nel glossario?
• [ ] La raccomandazione spiega perché?
• [ ] Se il task può andare avanti senza risposta, hai messo "bloccante": false?

Se una risposta è no, la card non è pronta.