---
name: kb-reflect
description: Synthesize why the wiki is shaped the way it is — decision records, evolution critique, structural bias detection
title: KB Reflect — Structural Self-Awareness
category: core
status: active
metadata:
  triggers:
  - reflect on wiki
  - wiki reflection
  - decision record
  - why does the wiki
---
## Purpose

The wiki knows what's in it. This skill makes it know **why** it's shaped the way it is.

Every knowledge change carries a decision. This skill surfaces those decisions as first-class pages — not buried in logs, but standing alongside the knowledge they shaped.

## The Reflect Step

Pipeline: `ingest → compile → **reflect** → query → lint`

After compilation produces or updates articles, reflect asks:

1. **What changed?** — which articles were created, updated, merged, or restructured
2. **What decision was made?** — why this framing, this categorization, this structure
3. **What alternatives existed?** — what other framings were possible, what was rejected
4. **What reasoning held?** — what evidence or logic drove the choice
5. **What bias might this introduce?** — did early ingestion skew the graph? Is a thread being over-represented?

## Decision Records

Stored as first-class wiki pages in `wiki/decisions/`:

```markdown
---
title: "Decision: {what was decided}"
entity_type: decision_record
status: active
date: "{YYYY-MM-DD}"
affects: ["article-slug-1", "article-slug-2"]
supersedes: ""
author: agent
---

## Decision
{What was decided and what changed}

## Context
{What triggered this — new source, contradiction, restructuring}

## Alternatives Considered
{What other approaches were possible}

## Reasoning
{Why this choice was made over alternatives}

## Consequences
{What this means for the wiki's structure going forward}
```

## Evolution Critiques

Periodic (weekly or after significant changes), produce an evolution page in `wiki/decisions/evolution/`:

- **Hub analysis** — which concepts became central and why. Was it because they're genuinely important, or because early sources happened to mention them?
- **Blind spots** — topics that should be covered based on the domain but aren't
- **Structural debt** — areas where the taxonomy doesn't match the actual content clustering
- **Reframing candidates** — articles whose fundamental framing might be wrong based on newer evidence

## Triggering

- **In pipeline**: runs as step 4 of `run_wiki_job` — only when something actually changed (ingested > 0 or compiled > 0)
- **Via watcher**: fires after auto-compile for batches of 3+ files (throttled to avoid trivial records)
- **Standalone**: `POST /kb/{slug}/reflect` or via chat ("reflect on wiki")
- **Skippable**: `run_wiki_job` accepts `skip_reflect=true`

## Rules

- Decision records are never deleted — they form the wiki's institutional memory
- If a decision is reversed, create a new record that `supersedes` the old one
- Don't create trivial records — only for structural decisions (new categories, merges, reframings, major reclassifications)
- The LLM is explicitly told to output `no_decisions` for routine additions — no record is created
- Link decision records to affected articles via `affects` field
- Evolution critiques should be brutally honest — the point is to catch biases, not confirm them

## System Prompt

You are a knowledge base structural analyst. The wiki must understand its own shape — not just what it knows, but WHY it knows things that way.

WHAT JUST CHANGED:
- Articles created: {articles_created}
- Files ingested: {files_ingested}

RECENTLY CREATED/MODIFIED ARTICLES (full content):
{recent_articles}

FULL WIKI STATE (titles and types):
{existing_articles}

KB SCHEMA:
{schema}

Analyze with these questions:
1. **Why were these articles created this way?** — What framing was chosen? Was "bowtie analysis" categorized as a concept rather than a process? Was a person filed globally rather than under a project? What alternatives existed?
2. **What got connected and what didn't?** — Which sources drove which articles? Are there obvious connections the compile missed?
3. **Ingestion bias** — Are early sources over-represented as hubs? Is the wiki shaped by what was ingested first rather than what matters most?
4. **Blind spots** — Topics the domain clearly requires but the wiki lacks. Questions the wiki should answer but can't.
5. **Structural debt** — Taxonomy mismatches, concepts that should be merged, entities that should be split.

RULES:
- Only create decision records for SIGNIFICANT structural choices — not routine additions.
- Each decision record must explain what ALTERNATIVE framing was possible and WHY this one was chosen.
- Be brutally honest. The point is to catch biases, not confirm choices.
- If nothing significant happened, say so.

Output format — ONLY if there are significant decisions:
```decision
title: Short decision title
decision: What was decided
context: What triggered this
alternatives: What other approaches were possible
reasoning: Why this choice
consequences: What this means going forward
affects: article-slug-1, article-slug-2
```

If no significant decisions were made, output:
```no_decisions
Routine update — no structural decisions to record.
```