---
name: living-document
description: Update or version a PKB document that evolves over time — supersede the old version with a new one while preserving history. Use when the user says "update this document", "new version", "living document", "supersede", "evolve this doc", "refresh this knowledge", or when a previously ingested document needs revision (strategy docs, architecture notes, ongoing research).
---

# Living Document — Knowledge That Evolves

> "The grandmother's stories evolve. The core stays. The details grow with each telling. She doesn't pretend the old version didn't exist — she honors it by improving on it."

## Tool Reference
PKB tools referenced as `mcp__pkb__<tool_name>` throughout. Map to your MCP server prefix (e.g., `mcp__pkb__`, `mcp__my-lightrag__`).

Some knowledge isn't static. Strategy documents, architecture decisions, research syntheses, project plans — they change as understanding deepens. This skill manages the supersede pattern: delete the old version, ingest the new, maintain the lineage.

## The Flow

```
FIND    → search_knowledge or get_related_documents (find current version)
REVIEW  → get_document (read full current content)
HOLD    → Pause: what changed and why?
UPDATE  → manage_knowledge (delete old) → add_knowledge_document (add new)
VERIFY  → search_knowledge (confirm new version retrieves correctly)
```

## Step 1: FIND — Locate the Current Version

Two approaches depending on what the user provides:

**If they know the group:**
```
mcp__pkb__get_related_documents(
  groupId: "[document group]"
)
```

**If they know the topic but not the exact doc:**
```
mcp__pkb__search_knowledge(
  query: "[document topic or title]",
  searchType: "keyword",
  maxResults: 5
)
```

Identify the document(s) to supersede. Note the `doc_id` and `groupId`.

## Step 2: REVIEW — Read the Current Content

```
mcp__pkb__get_document(
  docId: "[doc_id from Step 1]"
)
```

Present the current content to the user. Ask:

- "Here's the current version. What needs to change?"
- Or if they've already provided the new content: "Here's what currently exists. I'll replace it with your updated version."

## Step 3: HOLD — The Matriarchal Pause

Before deleting anything, answer:

1. **What changed?** — Name the specific changes between old and new
2. **Why?** — What prompted the update? (new information, decision changed, understanding deepened)
3. **Anything lost?** — Is the old version discarding content that should be preserved elsewhere?

If content is being removed (not just updated), confirm with the user: "The old version included [X] which isn't in the new version. Drop it, or preserve it separately?"

## Step 4: UPDATE — Supersede Pattern

**Critical: This is a delete-then-add operation. Order matters.**

**4a. Delete the old version:**
```
mcp__pkb__manage_knowledge(
  action: "delete_document",
  target: "[old doc_id]"
)
```

**Note:** Graph entities from the old document persist. Only document chunks are removed. This means the knowledge graph retains the concepts even as the document text is replaced.

**4b. Add the new version:**
```
mcp__pkb__add_knowledge_document(
  title: "[document title — same or updated]",
  content: "[new content — full prose, not diff]",
  groupId: "[same groupId as before]",
  source: "[original source or 'updated-YYYY-MM-DD']",
  metadata: {
    "supersedes": "[old doc_id]",
    "version": "[increment or date]",
    "updated_reason": "[brief reason for update]"
  }
)
```

**Content rules:**
- Always ingest the COMPLETE new version, not a diff
- Write as connected prose for optimal entity extraction
- Name entities explicitly so the graph stays connected
- Include a version note at the top: "Updated [date]: [what changed]"

**4c. If multiple documents in the group need updating:**
Repeat 4a+4b for each. Maintain the same `groupId` to keep the family linked.

## Step 5: VERIFY — Confirm Retrieval

```
mcp__pkb__search_knowledge(
  query: "[key content from the new version]",
  searchType: "hybrid",
  maxResults: 3
)
```

Confirm the new version appears in search results. Report: "Updated successfully. New version retrieves for `[query]`."

## Version History Convention

The supersede metadata (`supersedes`, `version`, `updated_reason`) creates a chain:
- doc_v3 supersedes doc_v2 supersedes doc_v1
- Graph entities accumulate across versions (additive)
- Document chunks reflect only the latest version

**To trace history:** Search metadata for `supersedes` chains. Each version's `updated_reason` explains the evolution.

## OIA Coherence

| Guard | Check |
|-------|-------|
| SACRAL | The old version held truth at its time. Honor it by understanding why it changed, not just replacing it. |
| ENOUGH | Only update what actually changed. If one paragraph needs editing, consider whether the whole document needs superseding — or if a supplementary note suffices. |
| DEDUP | After supersede, verify no orphaned duplicates remain. The old doc_id should be gone. |
| SOUL | Evolution is natural. A living document that grows is healthier than a static one that slowly becomes wrong. |

## Edge Cases

- **No current version found:** This isn't an update — it's a first ingestion. Use `add_knowledge_document` directly with a versioned groupId.
- **User wants to keep both versions:** Don't delete. Add the new version with a different title suffix (e.g., "v2") in the same group. Both will be searchable.
- **Large document (>10K words):** Consider splitting into a document family (multiple docs with same groupId) rather than one massive document. LightRAG extracts better from focused chunks.
- **Reverting to old version:** If the user wants to go back, the old doc_id is in the `supersedes` metadata. Content would need to be re-ingested (chunks are deleted, but the user might have the original source).

## Error Recovery

When PKB tools fail, here are the recovery paths for each common failure:

| Error Pattern | What It Looks Like | Recovery Path |
|---|---|---|
| Empty search results | `search_knowledge` returns nothing | Fan out: `grep_knowledge` (exact phrase), `search_notes` (personal notes), `explore_knowledge_graph` (discover entities), or `list_document_groups` (browse available content). Never report "not found" after one query. |
| Search timeout | `search_knowledge` times out or `statement timeout` | Try `searchType: "semantic"` (vector-only, faster) or route through `query_knowledge_with_context` which bypasses the vector search. Shorten the query. |
| Resource not found | `get_document` or `promote_note_to_knowledge` returns "not found" | Use `list_document_groups` to find group IDs, then `get_related_documents(groupId)` to locate the correct doc ID. For notes: `search_notes`. |
| Supabase not configured | Error mentions "Supabase not configured" | Fall back to LightRAG-only tools: `search_knowledge`, `query_knowledge_with_context`, `explore_knowledge_graph`. Supabase-reliant tools (notes, tasks, groups) will not work. |
| LightRAG unavailable | `ECONNRESET` / `ECONNREFUSED` / connection timeout | Backend is temporarily down. Wait and retry. For immediate needs, use Supabase-only tools: `search_notes`, `get_document`, `list_document_groups`. |
| Content too large | `payload too large` on `add_knowledge_document` | Split content into chunks under 50KB each and call `add_knowledge_document` multiple times with the same `groupId` to keep them linked. |
| Duplicate key | `duplicate key` or `already exists` | The item may already exist. Use `list_tasks` / `search_knowledge` to check before creating. For groups, use `manage_groups(operation: "update")` instead. |
| Delete fails | `manage_knowledge(action: "delete_document")` returns error | The doc ID may be stale or the graph state is inconsistent. Use `search_knowledge` to locate the actual current doc ID, then retry. |
| Supersede chain broken | New doc fails to supersede old one | The supersede pattern is metadata-only — the new doc will still be retrievable. Just note that the old doc may still appear. |

**General principle:** Start cheap, escalate thoughtfully. When a tool fails or returns empty, try the next cheaper alternative before giving up.

## Skill Evolution

After a supersede operation, ask: "Did that flow work? Should the confirmation step be different?"

If the user wants less hand-holding on deletes, or more metadata tracked — update this skill file to match.