dream · git:20261004.8dfccd1 · 2026-10-04 · sha256 49ae7a5cbe8cc095
dream git:20261004.8dfccd1A
Immutable. This exact content never changes and is served at /api/v1/blob/49ae7a5cbe8cc095.
--- 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.