knowledge

Files (2)

• CAPTURE.md
• SKILL.md

SKILL.md (first lines)

# Transversal — Knowledge Hygiene (capture + audit + stats)

You manage the project's durable knowledge. Three modes, one domain (the `docs-index`, the repo's documentation truth, and the evidence the build leaves behind):

- **`capture`** — convert ephemeral session knowledge into durable artifacts without polluting the repo with low-signal noise. (Was `/specture:learn`.)
- **`audit`** — detect and report the drift the index accumulates as docs are added/renamed/deleted. (Was `/specture:audit-knowledge`.)
- **`stats`** — read `docs/.specture-meta/build-metrics.jsonl` (one line per epic, tracked) and turn it into the gate's §6.5 reading.

## Shared Iron Rules (all modes)

```
1. NEVER write to Claude's personal memory (~/.claude/projects/*/memory/).
   Personal-preference candidates are LISTED for the user, never written.
2. NEVER create or promote an ADR to Status: Accepted. AI-drafted ADRs are
   always `Proposed — awaiting team confirmation`; Proposed stays Proposed.
3. NEVER promote a docs-index entry `ai_categorized` → `user_confirmed`.
   Only a human does that.
4. Telemetry is FAIL-OPEN: if writing a .jsonl under docs/.specture-meta/
   fails, never fail the skill — note it and continue.
5. Restricted + budgeted: read the minimal artifact set. Capture caps at
   ~30K tokens per invocation.
```

## Mode selection

| Invoked as | Mode |
|---|---|
| `/specture:knowledge capture`, alias `/specture:learn`, "capturemos aprendizajes", build Step 8.5, debug Phase 4.5 exit, `--teach <concept>` | **capture** |
| `/specture:knowledge audit`, alias `/specture:audit-knowledge`, "audita el índice" | **audit** |
| `/specture:knowledge stats`, "¿cómo viene el gate?", "métricas del build" | **stats** |
| `/specture:knowledge reconcile …` / `characterize …` (retired in v3.0.0) | Say so in one line: the living-behaviour files no longer exist — the truth of built behaviour is the code and its tests; `/specture:doctor migrate` offers to delete a leftover `docs/05-specs/_current/` |
| `/specture:knowledge` with no mode | Ask: *"¿capture (guardar lo aprendido), audit (revisar la salud del índice) o stats (métricas del build)?"* |

---

## Where each mode lives (read lazily)

| Mode | File | Open it when |
|---|---|---|
| `capture` | `knowledge/CAPTURE.md` | The selection above resolved to capture |
| `audit` | this file, § "Mode: audit" | — |
| `stats` | this file, § "Mode: stats" | — |

The Shared Iron Rules and the Tone below apply to every mode, wherever its procedure lives.
---

# Mode: audit — periodic docs-index audit

You are an **Index Auditor**. The `docs-index.yml` accumulates drift silently as docs change. Catch it before it pollutes agent dispatches.

## Audit Iron Rules (additional to the shared rules)

```
1. READ-ONLY by default. Report findings; never mutate the index.
2. NEVER delete entries automatically. The user confirms.
```

## Required Inputs

- `.specture/docs-index.yml` (must exist — if not: *"No hay índice que auditar. Para generar uno, corré `/specture:setup-docs-bridge`."* and stop).
- `.specture/conventions.md` §11 `source_of_truth_dir` (fallback to the field inside the index).
- File-system access to walk the source-of-truth dir.

## Phase 1 — Load and Parse the Index

Read `.specture/docs-index.yml` once, full. Build `concept → entry`.

## Phase 2 — Detect Drift (4 checks)

- **Check 1 — Orphan:** `entry.file` missing on disk → **ORPHAN** (moved/renamed/deleted, index not updated).
- **Check 2 — Stale:** age = today − `last_verified`. >180d → **STALE**; >365d → **VERY STALE**. Missing/malformed `last_verified` → **UNKNOWN_AGE**.
- **Check 3 — Duplicate:** group by `tags` (frozenset) AND first 8 words of `read_when`. ≥2 in a group → **DUPLICATE_CANDIDATE** (user confirms).
- **Check 4 — Uncovered:** walk the source-of-truth dir for `.md`; a file matching no `entry.file` → **UNCOVERED**.

## Phase 3 — Severity (fixed)

| Finding | Severity |
|---|---|
| ORPHAN | HIGH (agents may read missing files) |
| DUPLICATE_CANDIDATE | MEDIUM (wastes context budget) |
| VERY STALE (>365d) | MEDIUM |
| STALE (>180d) | LOW |
| UNCOVERED | LOW (invisible to agents) |
| UNKNOWN_AGE | LOW |

## Phase 4 — Generate Reports

**Machine log** — append to `docs/.specture-meta/audit-history.jsonl` (create dir; fail-open):
```json
{"ts":"<ISO-8601>","total_entries":N,"orphans":[{"concept":"...","file":"..."}],"duplicates":[{"group":[...]}],"stale":{"180d":[...],"365d":[...]},"uncovered":["..."],"unknown_age":[...],"health_score":<0..100>}
```
`health_score = 100 − (orphans*10 + duplicates*5 + very_stale*3 + stale*1 + uncovered*2)`, floored at 0.

**Human report** — overwrite `docs/.specture-meta/last-audit.md`: a `# Knowledge Index Audit — YYYY-MM-DD` with the health score, a Resumen (counts per finding type), and an "Acciones sugeridas" section per severity (HIGH orphans → delete entry or fix path; MEDIUM duplicates → consolidate manually with `superseded_by`; stale → re-read, validate `read_when`/`tags`, refresh `last_verified`; uncovered → run `knowledge capture` or add manually; unknown age → add `last_verified`). Close with: if health <70, suggest a `/specture:setup-docs-bridge` refresh; if many uncovered, suggest `knowledge capture`. **Never auto-apply any of these.**

## Phase 5 — Report to User

```
Audit completo. Health: <N>/100.
  Orphans (HIGH):      <K>    Duplicates (MEDIUM): <M>
  Stale:               <S> (<a> >365d, <b> >180d)
  Uncovered:           <U>    Unknown age:        <X>
Reporte: docs/.specture-meta/last-audit.md · Log: audit-history.jsonl
Acción:  >85 "índice saludable, re-correr en 1-3 meses" · 60-85 "limpieza menor (HIGH+MEDIUM)" · <60 "drift significativo → refresh con /specture:setup-docs-bridge"
```

## Audit — Verification Before Exit

- [ ] `last-audit.md` written + `audit-history.jsonl` appended (or fail-open noted).
- [ ] **NO changes to `.specture/docs-index.yml`** (read-only by contract). **NO ADR status changes.**
- [ ] Summary reported with health score.

## Audit — What this mode does NOT do

- ❌ Auto-fix orphans / auto-consolidate duplicates / re-index uncovered (use `knowledge capture` or `setup-docs-bridge`).
- ❌ Promote `ai_categorized` → `user_confirmed` · refresh `last_verified` itself (only humans) · touch source-of-truth files.

---

From FerEscobarDev/Specture, MIT.

More from FerEscobarDev/Specture