---
name: "kb-wiki-lint"
description: "Health check deterministico della Knowledge Base MUCC: trova note orfane, stale, duplicate, missing wiki-links, candidate alla promozione da inbox/auto/, stack hub mancanti. Usa quando l'utente dice 'lint kb', 'controlla wiki', 'verifica coerenza KB', 'health check', 'audit kb', oppure weekly housekeeping. Zero LLM-call, ~5s su 500 note."
---

# /kb-wiki-lint — Health check Knowledge Base

Scansione deterministica della KB con 6 regole di lint. Genera report markdown + JSON. **Zero LLM-call** (~5s su 500 note).

## 6 regole di lint

| # | Regola | Severità | Cosa rileva |
|---|--------|----------|-------------|
| 1 | `orphan` | 🟡 warning | Note senza wiki-link in/out da >N giorni |
| 2 | `stale` | 🟡 warning | Confidenza "alta" non confermata da >N giorni |
| 3 | `missing_xref` | 🔵 info | Note che citano stack/tech senza `[[wiki-link]]` |
| 4 | `duplicate` | 🟡 warning | Note con titolo simile (Jaccard >0.8) |
| 5 | `promo_candidate` | 🔵 info | Note in `inbox/auto/` pronte per promozione |
| 6 | `stack_entity_missing` | 🔵 info | Stack citati >5 volte ma senza entity page dedicata |

## Input

```
/kb-wiki-lint                            # full lint, report
/kb-wiki-lint --rule promo_candidate     # solo una regola
/kb-wiki-lint --stale-days 60            # custom soglia stale
/kb-wiki-lint --orphan-days 14           # custom soglia orphan
/kb-wiki-lint --top 20                   # top N per regola
/kb-wiki-lint --json                     # output JSON only (per script)
```

## Workflow

### Step 1 — Esegui lint

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

Output esempio:

```
🔍 KB Wiki Lint Report

📊 KB stats:
   Note totali: 483
   Auto-capture: 89
   Findings totali: 399

📋 Per severità:
   🟡 warning: 20
   🔵 info: 379

📐 Per regola:
   missing_xref              267
   promo_candidate           89
   stack_entity_missing      23
   orphan                    11
   duplicate                 9

📄 Report markdown: ~/mucc-knowledge-base/_wiki/_lint-report.md
📄 Report JSON:     ~/mucc-knowledge-base/_wiki/_lint-report.json
```

### Step 2 — Mostra report sintetico all'utente

Leggi il JSON e riassumi top 3 issue critici:

```
🔍 KB Wiki Lint completato (5s)

📊 Stato KB:
   • 483 note totali (89 auto-capture)
   • Cartelle top: pattern/backend (64), decisioni/architettura (37)

🎯 Top issue:
   1. 🔵 missing_xref (267) — opportunità di crosslinking
   2. 🔵 promo_candidate (89) — note auto pronte per promozione
   3. 🟡 orphan (11) — note isolate

💡 Azioni suggerite:
   - Per promuovere le 89 note auto → /kb-wiki-promote
   - Per fixare missing_xref → /kb-wiki-crosslink
   - Per archiviare orphans → review manuale in Obsidian
```

### Step 3 — (Opzionale) Mostra dettaglio regola

Se l'utente chiede una specifica regola:

```bash
npx tsx kb-wiki-lint.ts --rule promo_candidate --top 10 --json
```

Mostra top 10 con suggerimento cartella destinazione.

### Step 4 — Suggerisci next steps

Sulla base del report:

| Issue dominante | Skill correlata |
|----------------|-----------------|
| Tanti `promo_candidate` | `/kb-wiki-process` esistente per nuove note, **`/kb-wiki-promote`** (futura v0.15+) per spostare |
| Tanti `missing_xref` | Aprire Obsidian e fare crosslinking manuale, o Karl in modalità "linker" |
| Tanti `orphan` | Review in Obsidian + decisione: linka o archivia |
| `duplicate` flagged | Decisione manuale di merge |
| `stack_entity_missing` | Crea note hub `decisioni/stack/{stack}.md` |

## Regole spiegate

### 1. ORPHAN
Note in cartelle definitive senza link in/out da >30 giorni. Indica conoscenza isolata che rischia di essere dimenticata. **Eccezioni**: `agenda/`, `meeting/`, `inbox/`.

### 2. STALE
Note con `confidenza: alta` con `data` > 90 giorni fa. La confidenza alta era basata su conferme passate — vale ancora? **Action**: review manuale + downgrade o conferma esplicita.

### 3. MISSING_XREF
Nota cita >=2 stack/tech (postgresql, fastapi, react, ecc.) ma NON ha `[[wiki-link]]` per loro. Riduce densità del grafo Obsidian. **Action**: aggiungere wiki-links nella sezione Wiki-links del body.

### 4. DUPLICATE
Due note con slug del titolo che condividono >=3 termini e Jaccard >=0.8. Possibile duplicazione semantica. **Action**: review + merge o differenziazione titoli.

### 5. PROMO_CANDIDATE
Nota in `inbox/auto/` con:
- `tipo` impostato (decisione/pattern/errore/concept/componente)
- `wikiLinkCount >= 2`
- `bodyLength >= 300 char`

Output include `suggestedFolder` automatica basata su `tipo` + `stack` + `tags`:
- `decisione` + stack DB → `decisioni/database/`
- `decisione` + stack API framework → `decisioni/api/`
- `pattern` + tag frontend → `pattern/frontend/`
- `errore` + tag bug → `errori/bug/`
- ecc.

### 6. STACK_ENTITY_MISSING
Stack citati in `>=5` note ma senza una pagina hub dedicata. Esempio: `postgresql` citato in 24 note ma manca `decisioni/stack/postgresql.md`. **Action**: creare la nota hub.

## Output

- **Console**: summary con count per regola
- **`~/mucc-knowledge-base/_wiki/_lint-report.md`** — markdown report con top 50 finding per regola
- **`~/mucc-knowledge-base/_wiki/_lint-report.json`** — JSON machine-readable per skill consumer

## Performance

- 483 note → ~5s
- 1000+ note → ~10-15s
- Memoria: < 100 MB

## Quando eseguire

| Frequenza | Caso d'uso |
|-----------|-----------|
| **Daily** | Post-`/kb-wiki-process` per validare note appena create |
| **Weekly** | Housekeeping: trovare orphans + missing_xref accumulate |
| **Pre-promozione** | Identifica `promo_candidate` prima di spostare in batch |
| **Pre-merge KB** | Dopo `/kb-ingest` massivo per pulizia |

## Riferimenti

- Script: `dev-methodology/scripts/kb-wiki-lint.ts`
- Skill correlate: `/kb-wiki-process` (cattura), `/kb-recall` (cerca), `/kb-status` (dashboard)
- Pattern Karpathy (lint sezione): https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f