---
name: "kb-wiki-process"
description: "Processa la queue di eventi KB Wiki accumulati durante lo sviluppo: spawna l'agente Karl (kb-llm-analyzer, Sonnet 4.6) che legge ogni evento, analizza semanticamente il file modificato, decide se contiene una decisione tecnica significativa, e scrive nota strutturata in inbox/auto/ del vault Obsidian. Usa quando l'utente dice 'kb process', 'processa wiki', 'analizza decisioni', 'wiki llm', oppure all'apertura di una sessione di sviluppo per smaltire la queue accumulata."
---

# /kb-wiki-process — Processa queue KB Wiki via LLM

Architettura **LLM-via-subagent Claude-native** (v0.11.0+):
- Hook `PostToolUse` accumula eventi in `~/mucc-knowledge-base/_queue/{id}.json` (zero costo)
- Quando lanci `/kb-wiki-process`, la skill spawna **Karl** (`kb-llm-analyzer`, Sonnet 4.6)
- Karl analizza ogni evento e scrive note semantiche in `inbox/auto/`
- **Niente API key**, **niente costo marginale** (sfrutta subscription Pro/Max)

## Input

```
/kb-wiki-process                    # processa tutti gli eventi pending (max 20 per batch)
/kb-wiki-process --limit 5          # solo i primi 5 eventi
/kb-wiki-process --dry-run          # mostra cosa verrebbe processato senza spawnare Karl
/kb-wiki-process --cleanup          # cleanup processed/ > 30 giorni
```

## Prerequisiti

- KB inizializzata (`~/mucc-knowledge-base/` esiste)
- Almeno 1 evento in queue (`~/mucc-knowledge-base/_queue/*.json`)
- Plugin dev-methodology v0.11.0+ installato (per agente `kb-llm-analyzer`)

## Workflow

### Step 1 — Verifica queue

Esegui:

```bash
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/kb-queue.ts count --kb-dir ~/mucc-knowledge-base
```

Output esempio:
```
Pending: 8
Processed: 47
```

Se `Pending = 0`:
```
✨ Queue vuota — nulla da processare.
```
Termina.

Se `Pending >= 1`, prosegui.

### Step 2 — Mostra preview eventi

```bash
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/kb-queue.ts list --limit 20 --kb-dir ~/mucc-knowledge-base
```

Mostra all'utente:
```
📋 8 eventi in queue (ordine FIFO):

  1. 2026-04-28T10:15  [Write]  backend/src/db/connection.py        (presenta)
  2. 2026-04-28T10:23  [Edit]   package.json                          (presenta)
  3. 2026-04-28T10:31  [Write]  backend/src/middleware/rate_limit.py  (iridia)
  ...

🤖 Karl (kb-llm-analyzer, Sonnet 4.6) processera questi eventi.
   Tempo stimato: ~80-120s per batch di 8.
   Output: note in ~/mucc-knowledge-base/inbox/auto/

Procedere? (sì/no/dry-run)
```

In modalita `--auto` o se non c'e prompt utente, procedi senza chiedere conferma.

### Step 3 — Dequeue batch

```bash
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/kb-queue.ts dequeue --batch-size 20 --kb-dir ~/mucc-knowledge-base
```

Output: array JSON di eventi (ID + file_path + content_snippet + project + tool).

Salva l'output in una variabile o file temp per passarlo al subagent.

### Step 4 — Spawna l'agente Karl

Usa il tool `Agent` con `subagent_type="kb-llm-analyzer"`.

Prompt da passare a Karl:

```
Sei stato chiamato da /kb-wiki-process per analizzare un batch di eventi KB Wiki.

KB path: ~/mucc-knowledge-base/
Queue helper: npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/kb-queue.ts
Plugin scripts: ${CLAUDE_PLUGIN_ROOT}/scripts/

Eventi da processare ({N} totali, IDs):
- {id1}
- {id2}
- ...

Per ogni evento:

1. Leggi /Users/.../mucc-knowledge-base/_queue/{id}.json
2. Decidi: significativo SI/NO (segui euristiche del tuo prompt principale)
3. Se NO → mark-processed e skip
4. Se SI:
   a. **Anti-duplicazione (NEW v0.12.0+)**: prima di scrivere, cerca duplicati con strategia in cascata:
      i. **Cerca in KB esistente**: npx tsx kb-core.ts search "termini" --tipo X --limit 5 --kb-dir ~/mucc-knowledge-base
      ii. **Cerca nel codice (se /dev-codesearch è installato)**:
          - Estrai keyword dal titolo proposto (es. "FastAPI batte Flask" → "FastAPI Flask")
          - Invoca `/dev-codesearch --query "<keyword>" --json --limit 3`
          - Se ritorna file con `score > 0.8` E gli stessi pattern sono già documentati in KB → la nota è ridondante, skip
          - Se il MCP non è disponibile o /dev-codesearch non installato, salta questa sotto-step (backward compat)
   b. Se NO duplicato → genera nota e scrivi in ~/mucc-knowledge-base/inbox/auto/{slug}.md
   c. Se duplicato esistente → npx tsx kb-core.ts confirm <path> --progetto <name>
5. Mark-processed: npx tsq kb-queue.ts mark-processed --id {id} --kb-dir ~/mucc-knowledge-base

Al termine, restituisci report nel formato:

✅ Processati: {N} eventi
   - WRITE: {X} note create:
     • inbox/auto/{slug1}.md
     • inbox/auto/{slug2}.md
   - SKIP: {Y} (motivi: {breakdown})
   - DEDUP: {Z} duplicati
   - ERRORS: {E} (eventuali)

⏱️ Tempo: {ms}s

Non dimenticare: confidenza sempre bassa, tag mucc/auto + mucc/llm,
auto_capture: true, source_event_id: {id}.
```

### Step 5 — Mostra report al user

Quando Karl restituisce il report, presentalo all'utente con un cappello informativo:

```
🤖 Karl ha processato {N} eventi:

   ✅ {X} note scritte in inbox/auto/
   ⏭️  {Y} eventi skippati (rumore)
   🔁 {Z} eventi confermano decisioni esistenti
   ❌ {E} errori (vedi log)

📂 Vault Obsidian: ~/mucc-knowledge-base/
   → Le nuove note appaiono automaticamente in Obsidian (file watcher)
   → Tag #mucc/auto #mucc/llm filtrabili nel grafo

💡 Per promuoverle a confidenza media/alta:
   1. Apri Obsidian → vai su inbox/auto/
   2. Review note rilevanti
   3. Sposta in decisioni/, pattern/, errori/ (cartella appropriata)
   4. Aggiusta `confidenza` nel frontmatter
```

Se ci sono ancora eventi pending dopo il batch:
```
📥 Queue residua: {N} eventi pending
   → Esegui di nuovo /kb-wiki-process per il prossimo batch
```

### Step 6 — (Opzionale) Cleanup processed

Se `--cleanup` o se sono passati > 30 giorni dall'ultima cleanup:

```bash
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/kb-queue.ts cleanup --days 30 --kb-dir ~/mucc-knowledge-base
```

Mostra:
```
🗑️  Rimossi {N} eventi processed > 30 giorni (housekeeping)
```

## Modalita dry-run

Se l'utente passa `--dry-run`:

1. Mostra preview eventi (Step 2)
2. NON chiamare Karl
3. Esegui solo grep euristico su content_snippet per dare stima:
   - Eventi con file `.test.*` → SKIP probabile (ma sono già esclusi dalla queue)
   - Eventi con file `package.json`/`requirements.txt` → WRITE probabile
   - Eventi con commenti `DECISION/CHOSE/WHY` → WRITE probabile
   - Altri → 50/50
4. Stima: "{X} probabili WRITE, {Y} probabili SKIP, {Z} ambigui"
5. Termina senza modifiche.

Utile per debugging o per decidere se vale la pena processare il batch.

## Esempi

### Esempio 1: queue piccola

```
Utente: /kb-wiki-process

Claude:
  📊 Pending: 3 eventi, Processed: 12

  📋 Eventi:
    1. backend/src/db/connection.py   (presenta)
    2. package.json                    (presenta)
    3. src/components/Login.tsx        (iridia)

  Procedere? sì

  🤖 Spawno Karl (kb-llm-analyzer)...

  [Karl processa]

  ✅ Karl report:
     - WRITE 2:
       • inbox/auto/asyncpg-preferito-psycopg-fastapi.md
       • inbox/auto/redis-cache-layer-aggiunto.md
     - SKIP 1: edit cosmetico Login.tsx
     - 0 duplicati

  ⏱️ 38s

  📂 Note in ~/mucc-knowledge-base/inbox/auto/
     Apri Obsidian per review.
```

### Esempio 2: queue grossa

```
Utente: /kb-wiki-process

Claude:
  📊 Pending: 47 eventi, Processed: 89

  ⚠️ Queue grande. Processo i primi 20.

  [Karl processa batch di 20]

  ✅ 7 WRITE, 11 SKIP, 2 DEDUP
  ⏱️ 187s

  📥 Queue residua: 27 pending
     → /kb-wiki-process per processare i prossimi 20
     → /kb-wiki-process --dry-run per stima velocità
```

### Esempio 3: dry-run

```
Utente: /kb-wiki-process --dry-run

Claude:
  📊 Pending: 15 eventi

  🔍 Stima euristica (no LLM call):
     - Probabile WRITE: 4 (deps changes + DECISION comments)
     - Probabile SKIP: 8 (refactor cosmetici, file di stile)
     - Ambigui: 3

  💡 Esegui /kb-wiki-process per processare effettivamente.
```

## Quando viene chiamata automaticamente

(Roadmap futura, non in v0.11.0)

- **SessionStart hook**: se queue >= 5 eventi all'apertura sessione, suggerisci `/kb-wiki-process`
- **Post-`/dev-validate`**: dopo fine sprint, processa coda accumulata
- **Post-`/bs-handoff`**: nuove decisioni dal brainstorming

Per ora **invocazione manuale** è il pattern raccomandato — ti tieni il controllo su quando spendere tempo nell'analisi LLM.

## Performance attesa

| Batch size | Tempo Karl | Note tipiche scritte |
|-----------|------------|----------------------|
| 5 eventi  | 30-60s     | 1-2                  |
| 10 eventi | 60-120s    | 2-4                  |
| 20 eventi | 2-4 min    | 4-8                  |

Tasso medio: ~25-40% degli eventi diventa nota. Il resto è rumore filtrato.

## Output

- Numero eventi processati (write/skip/dedup/error)
- Path delle note create in `inbox/auto/`
- Eventi residui in queue (se batch incompleto)
- Suggerimento: aprire Obsidian per review

## Multi-Query Reformulation per anti-dup (NEW v0.25.0)

Karl, in fase di anti-duplicazione (Step 4.a del proprio prompt), può attivare il pattern **multi-query reformulation** (max 3 passi: `search → open → reformulate`) condiviso con `/kb-recall` e `/dev-codesearch`.

**Quando attivare**:
- L'evento queue contiene una decisione tecnica con keyword ambigue (es. "auth", "cache", "queue") che potrebbero matchare note esistenti con nomi diversi
- Flag `--iterative` esplicito al comando `/kb-wiki-process`

**Loop in Karl** (Step 4.a esteso):

1. Search prima: `kb-core.ts search "<estratto principale>" --tipo X --limit 5`
2. Se `0` hit O hit con titolo molto diverso dal proposto: apri top-3 note KB simili (anche di altra `tipo`) → estrai tag dal frontmatter
3. Reformula: combina estratto + tag estratti → re-search
4. Se trova match → confirm (no nuova nota); altrimenti procedi con write in `inbox/auto/`

**Razionale**: Karl può perdere duplicati quando l'utente ha già documentato lo stesso concept con keyword diverse (es. "FastAPI batte Flask" vs "async API server choice"). Multi-query reformulation cattura questi casi a costo di +1-2 LLM call per evento (trascurabile su batch da 20).

Proposta skill-evolution chiusa: #3.

## Riferimenti

- Pattern Karpathy LLM Wiki: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
- Agente: `dev-methodology/agents/kb-llm-analyzer.md` (Karl)
- Queue helper: `dev-methodology/scripts/kb-queue.ts`
- Skill correlate: `/kb-recall`, `/kb-write`, `/kb-status`, **`/dev-codesearch` (v0.12.0+ anti-dup)**
- Vault Obsidian: `~/mucc-knowledge-base/` (path invariato)
- Protocollo condiviso (v0.25.0): `dev-methodology/references/tool-decision-protocol.md` (per subagent fratelli Karl/Sofia)