Knowledge base

La knowledge base raccoglie quello che il team sa di un progetto: appunti, decisioni prese, guide. Le pagine si cercano anche per significato, non solo per parole esatte, e compaiono come suggerimento accanto a ticket ed errori.

La trovi nel menu sotto Conoscenza. La pagina d'ingresso porta a tre posti, nell'ordine d'uso: Revisione, le pagine, le Raccolte.

Scrivere una pagina

1. Apri le pagine e premi Nuova pagina.
2. Scegli il Tipo: Nota, Decisione o Guida.
3. Scegli i Progetti o i Gruppi a cui appartiene. Una pagina può stare in più progetti.
4. Scrivi il Contenuto in markdown, in parole semplici. I dettagli tecnici vanno nella Sezione tecnica, che è facoltativa.
5. Premi Salva. Poco dopo la pagina entra nella ricerca e l'assistente può usarla per rispondere.

Chi legge vede due schede: Semplice e Tecnico. Ogni modifica crea una versione: da Cronologia versioni rileggi le versioni vecchie e ne riporti una con Ripristina. Quella attuale resta nella cronologia.

Senza progetti né gruppi la pagina vale per tutta l'organizzazione. Solo chi ha accesso completo può crearla, e solo chi ha accesso completo la vede.

Collegare le pagine

Per rimandare a un'altra pagina, scrivi il suo titolo tra doppie parentesi quadre: [[Deploy Kamal]]. Mentre scrivi, l'app ti suggerisce i titoli che esistono. Al salvataggio diventa un collegamento.

• Nel riquadro Collegamenti di ogni pagina trovi Collegate (le pagine a cui rimanda) e Citata da (le pagine che la citano).
• Se rinomini la pagina di arrivo, il collegamento continua a funzionare.
• Se il titolo non esiste ancora, resta testo normale. Niente collegamenti rotti.

Le raccolte

Una raccolta mette in fila più pagine, come un manuale: a sinistra l'indice, a destra la pagina aperta.

1. Apri Raccolte e premi Nuova raccolta.
2. Dai un titolo e scegli progetti o gruppi.
3. In Pagine della raccolta scegli le pagine. L'ordine in cui le scegli è l'ordine dell'indice.

Una raccolta può tenere insieme pagine di progetti diversi. Una pagina sta in una sola raccolta. Se elimini la raccolta, le pagine restano.

Cercare

Scrivi nella ricerca dell'elenco. Di base cerchi per significato: trovi la pagina giusta anche se usa altre parole. Per cercare le parole esatte, in tutto il testo, premi Cerca invece per parole esatte.

La ricerca per significato richiede un servizio AI collegato (vedi AI). Se manca o non risponde, la ricerca usa le parole esatte e lo dice.

Fare una domanda

Apri Fai una domanda, scrivi la domanda e premi Chiedi. La risposta usa solo le pagine dei progetti che puoi vedere e cita le pagine da cui viene. Se le pagine non bastano, lo dice invece di inventare.

Nella stessa pagina trovi esempi da cui partire (Prova a chiedere) e le Domande recenti del team.

Dal terminale fai lo stesso con la CLI:

cyi kb search rollback del deploy      # cerca per significato
cyi kb ask come si torna indietro da un deploy
cyi kb show <id> --related             # una pagina e quelle da leggere dopo

Le pagine proposte da un assistente

Mentre lavora, un assistente può accorgersi di qualcosa da conservare: un errore risolto, una decisione, una trappola. Non lo pubblica: lo propone e aspetta una persona.

Una proposta in attesa non compare nella ricerca, nelle risposte e nei suggerimenti accanto ai ticket.

1. Apri Revisione. In cima vedi quante proposte aspettano.
2. Leggi titolo, motivo e testo della proposta.
3. Premi Accetta per tenerla: diventa visibile a tutti ed entra nella ricerca e nelle risposte.
4. Premi Scarta se non serve. Non si cancella: resta da parte, e un assistente non ti ripropone la stessa nota.

Per accettare o scartare serve il permesso di modificare la knowledge base. Decide sempre una persona: un accesso automatico viene respinto.

Dal terminale, con il tuo accesso personale:

cyi kb approve <id>
cyi kb reject <id>

Un assistente (o tu) propone una pagina con --in-review. --review-note è la riga che spiega perché vale la pena tenerla:

cyi kb create -p acme-api --title "Rollback" --body-file ./nota.md \
  --in-review --review-note "Successo oggi, non si capisce dal codice"

Una proposta deve avere il testo in parole semplici. Se il testo è tecnico, i dettagli vanno nella sezione tecnica (--tech-spec-file), altrimenti la proposta viene rifiutata.

Il revisore automatico

Se è acceso, un revisore automatico legge ogni pagina prima di salvarla. Se la pagina non rispetta le regole della knowledge base, non si salva e un messaggio dice cosa correggere. Una proposta che il revisore rimanda resta in Revisione con il segno Rimandate dal revisore: correggila, salvala, poi accettala.

Chi ha scritto la pagina

Le pagine scritte da un assistente portano il segno Assistente, anche dopo che le hai accettate. Il filtro Scritta da dell'elenco le ritrova. Il segno sparisce quando una persona riscrive davvero il testo: correggere una virgola o cambiare i tag non basta.

Rileggere le pagine vecchie

Decisioni e guide invecchiano. Ognuna ha una data entro cui va riletta: sei mesi per una decisione, un anno per una guida. Le note non scadono.

Passata la data, la pagina si trova ancora ma è segnata Da rivedere. In Revisione, sezione Da rileggere, premi È ancora vera se lo è. Se invece correggi la pagina, la data riparte da sola.