---
name: dream
description: Knowledge base maintenance — organize, deduplicate, cross-reference the datarim/ directory. Flags contradictions, archives stale content.
model: inherit
current_aal: 1
target_aal: 2
---

# Dream — Knowledge Base Maintenance

> "The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping."

Dream handles the bookkeeping: cross-references, deduplication, organization, staleness checks, and structural consistency of the `datarim/` directory. It runs periodically or on demand, keeping the knowledge base healthy as it grows.

---

## Three Operations

### 1. Ingest (process new items)

New documents, notes, and artifacts land in the knowledge base through tasks. Over time, some end up misplaced, unnamed inconsistently, or disconnected from related content.

**Ingest checks:**
- Files in wrong directories (e.g., a PRD outside `prd/`, a reflection outside `reflection/`)
- Files missing task ID in filename (required by datarim-system rules)
- Files without frontmatter or metadata
- Files that reference other files using wrong paths (broken links)
- Archives in `documentation/archive/` without matching reflection in `datarim/reflection/`
- Archive files in wrong area subdirectory (prefix doesn't match area per Archive Area Mapping in `datarim-system.md`)

**Actions:**
- Propose moving misplaced files to correct directories
- Propose renaming files to follow naming conventions
- Add missing cross-references between related documents
- Add cross-references between `datarim/reflection/` and `documentation/archive/`

### 2. Lint (health check)

Periodic review of the entire knowledge base for structural problems.

**Lint checks:**

| Check | What it detects |
|-------|----------------|
| **Contradictions** | Two documents making conflicting claims about the same topic |
| **Stale content** | Documents referencing completed/archived tasks as "in progress" |
| **Orphan files** | Documents with no inbound references from any other document |
| **Missing pages** | Concepts or entities referenced but never given their own document |
| **Broken links** | Internal references pointing to files that don't exist |
| **Duplicate content** | Two documents covering the same topic with >70% overlap |
| **Empty directories** | Subdirectories with no files |
| **Oversized files** | Documents over 500 lines that should be split |
| **Inconsistent naming** | Files not following the `[type]-[task_id]-[name].md` pattern |
| **Cross-reference symmetry** | If doc A links to doc B, does B link back to A? |
| **Archive-reflection symmetry** | Archive in `documentation/archive/` exists without matching reflection in `datarim/reflection/`, or vice versa |
| **Archive area mismatch** | Archive file in wrong subdirectory per prefix→area mapping in `datarim-system.md` |

**Output:** A lint report listing all issues found, grouped by severity (critical → warning → info).

### 3. Consolidate (reorganize and merge)

Deep maintenance that restructures the knowledge base for clarity and efficiency.

**Consolidation actions:**

| Action | Description |
|--------|-------------|
| **Merge duplicates** | Combine two documents covering the same topic into one |
| **Extract patterns** | Find recurring themes across reflections and create a patterns page in `documentation/` |
| **Build index** | Create or update `datarim/index.md` — a catalog of all documents (from both `datarim/` and `documentation/archive/`) with one-line summaries |
| **Update progress** | Reconcile `tasks.md`, `backlog.md` and the per-task description files with the actual state of tasks and archives |
| **Archive stale** | Move completed/obsolete documents to `archive/` with proper metadata |
| **Cross-reference** | Add bidirectional links between related documents (PRD ↔ task ↔ reflection ↔ archive) |
| **Tag extraction** | Identify common themes and add tags to document frontmatter |

---

## Document Frontmatter Standard

When Dream processes documents, it ensures this frontmatter exists:

<!-- gate:history-allowed -->
```yaml
---
title: Document Title
task_id: TASK-0042
type: prd | task | reflection | creative | qa | archive | report
status: active | completed | archived | superseded
created: 2026-04-11
updated: 2026-04-11
tags: [tag1, tag2]
related: [path/to/related-doc.md]
---
```
<!-- /gate:history-allowed -->

**Fields:**
- `title` — human-readable title
- `task_id` — link to originating task
- `type` — document category (matches directory)
- `status` — lifecycle state
- `created` / `updated` — dates
- `tags` — topic tags for cross-cutting concerns
- `related` — explicit links to related documents

Not all fields are required for all documents. Dream adds missing fields where it can infer the value.

---

## Index File

Dream maintains `datarim/index.md` — a navigable catalog of the knowledge base:

<!-- gate:history-allowed -->
```markdown
# Knowledge Base Index

**Last updated:** 2026-04-11
**Total documents:** 42

## By Type
### PRDs (5)
-(prd/PRD-0001-auth-system.md) — Authentication system requirements
-(prd/PRD-0002-export-pipeline.md) — Data export pipeline

### Tasks (8)
-(tasks/TASK-0001-setup.md) — Project setup and configuration
...

### Reflections (6)
...

## By Tag
### authentication
-(prd/PRD-0001-auth-system.md)
-(tasks/TASK-0005-jwt-implementation.md)
- [reflection-TASK-0005](reflection/reflection-TASK-0005.md)

## Recent Activity
| Date | Action | Document |
|------|--------|----------|
| 2026-04-11 | Created | tasks/TASK-0042-dream-system.md |
| 2026-04-10 | Archived | archive/archive-TASK-0041.md |
```
<!-- /gate:history-allowed -->

---

## Activity Log

Dream appends to `datarim/history/activity-log.md`:

```markdown
# Activity Log

## [2026-04-11] dream | Full maintenance
- Lint: 3 issues found (1 orphan, 1 broken link, 1 stale reference)
- Fixed: renamed 2 files to match naming convention
- Consolidated: merged duplicate reflection notes
- Updated: index.md, tasks.md
- Duration: ~2 minutes

## [2026-04-08] dream | Quick lint
- Lint: 0 issues found
- Knowledge base is healthy
```

---

## Contradiction Handling

When Dream finds two documents making conflicting claims:

1. **Do NOT silently overwrite.** Both claims may be valid in different contexts.
2. Add a `[!contradiction]` callout to both documents:
   ```markdown
   > [!contradiction]
   > This document states X, but [other-doc.md](path) states Y.
   > Added by Dream on 2026-04-11. Needs human resolution.
   ```
3. Log the contradiction in the lint report.
4. The human resolves it — Dream does not pick sides.

---

## When to Run

| Trigger | Operation | Depth |
|---------|-----------|-------|
| `/dr-dream` (no args) | Full: ingest + lint + consolidate | Deep |
| `/dr-dream lint` | Lint only | Quick |
| `/dr-dream index` | Rebuild index only | Quick |
| After `/dr-archive` | Auto-suggest if >5 unindexed docs | Suggestion only |
| After every 10 tasks | Auto-suggest full maintenance | Suggestion only |

---

## What Dream Does NOT Do

- Modify source code files. Dream works with `datarim/` and `documentation/archive/` contents only.
- Delete documents without approval. All removals are proposed, never automatic.
- Resolve contradictions. It flags them for human judgment.
- Create new knowledge. It organizes existing knowledge — writing new content is the writer's job.
- Run automatically. It suggests when maintenance is needed but never runs without the user's explicit command.