lythoskill-dreaming

Files (3)

• SKILL.md
• drift-detection.md · references/
• hermes-dreaming-field-notes.md · references/

SKILL.md (first lines)

# Dreaming — 夜有所梦 ("night dreams": consolidate the day into long-term memory)

> By day, thought (日有所思 — daily + weekly gather raw experience); by night,
> dreams (夜有所梦 — dreaming consolidates it into the SSOT).
> Scan → Consolidate → ZK Validate. Extract the "currently true" from scattered docs.

> **Invocation.** `arena <cmd>` mentions below mean
> `bunx @lythos/skill-arena@{{PACKAGE_VERSION}} <cmd>` (no install). `arena` is
> not a registered bin — in-repo alias convention in the lythoskill monorepo only.
> Want it? `alias arena='bunx @lythos/skill-arena@latest'` — optional.

## The Project's Memory System

Project documentation works like human memory:

| Layer | Tool | What it does |
|-------|------|-------------|
| **By day — experience** (日有所思) | `scribe daily` | Raw session capture: what was done, what was decided, what went wrong |
| **By day — review** (日有所思) | `scribe weekly` | Cross-session pattern extraction: core threads, anomalies, docs now stale |
| **By night — consolidation** (夜有所梦) | `dreaming` | Memory consolidation: extract "currently true" from accumulated docs → SSOT |

Daily is a raw-experience log, not a ledger replay; weekly is cross-session pattern
recognition (core_thread, anomaly, docs_now_stale) — essentially anti-corruption work:
detect drift, mark rot, track gap closure. Dreaming is the next layer: once enough
daily + weekly has accumulated, extract everything still-true scattered across
wiki/ADR/daily into the SSOT — the way a sleeping brain consolidates short-term memory
into long-term memory.

## First Principles

The layering: daily captures raw experience; weekly extracts cross-session
patterns and flags rot (docs_now_stale, anomalies); dreaming consolidates what
still holds into the SSOT. Each layer feeds the next — weekly finds what is
rotting, dreaming solidifies what hasn't rotted yet.

The mechanism has an external precedent: the Hermes Curator dreaming mechanism
converges on the same idea independently. The transfer of that mechanism to
project documentation is what this skill implements. Field notes:
[`references/hermes-dreaming-field-notes.md`](./references/hermes-dreaming-field-notes.md).

**Core insight: maintenance should be a standalone cycle, not embedded in every task.**

## Three-Phase Flow

### Phase 1: Scan — Start from weekly, not from raw

**Primary index: the weekly chain.** Weeklies (W17 onward) are pre-built importance-ranked summaries. Each weekly carries:

- `core_thread` — the 1-2 most important clusters per week (most weeklies)
- `decisions_accepted` — which ADRs landed when (every weekly)
- `docs_now_stale` — ADRs/wiki that became outdated (**a minority** — mostly the W17–W24 era, plus W25-v2 and W28; later weeklies record stalls as `quests_paused` / `parked_threads` instead, which appear throughout)
- Anomalies surfaced — CLI renames, missing ADRs, build-then-reject cycles

Start from weekly, not from raw scan:

```bash
ls weekly/ | sort                          # Read all weeklies
cat weekly/*.md | grep "docs_now_stale"    # Stale-doc index, W17–W24 era
cat weekly/*.md | grep "decisions_accepted" # Build ADR timeline from weekly
cat weekly/*.md | grep "quests_paused\|parked_threads"  # Stalls in later weeklies
```

**Why this is better**: the corpus (100+ ADRs, 100+ wiki pages, 50+ dailies) is impossible to scan cold. The weekly chain tells you *what mattered and what's outdated*. Weekly is dreaming's pre-built index — like Obsidian's map of content.

**Fallback** (only when weeklies are missing or incomplete):
```bash
bun packages/lythoskill-project-cortex/src/cli.ts probe
ls -lt cortex/adr/02-accepted/ | head -20
git log --since="30 days ago" --oneline -- cortex/wiki/ cortex/adr/
```

Agent reads weekly chain → identifies:
- **Already stale**: flagged in `docs_now_stale` across any weekly
- **Superseded**: ADR mentioned in a later weekly's `decisions_accepted` that contradicts an earlier one
- **Duplicate**: same insight appearing in multiple wiki entries
- **Orphaned**: references to tasks/epics that no longer exist

### Phase 2: Consolidate

Write to `cortex/wiki/04-ssot/`. One file per major topic area. Each SSOT file is:

- **Short** (< 500 lines) — a fresh agent can read it in one pass
- **Self-contained** — links to source ADRs/wiki for detail, but doesn't require reading them
- **Current** — reflects what's TRUE NOW, not what was true at some point in history
- **Dated** — frontmatter `last_consolidated: 2026-05-28` so reader knows freshness

Example SSOT topics:
- `architecture.md` — current system architecture (not design history)
- `conventions.md` — active code/doc conventions (not deprecated ones)
- `key-decisions.md` — ADRs that still hold (superseded ones noted but not replayed)
- `pitfalls.md` — recurring failure modes and their fixes

**Update `cortex/wiki/01-patterns/INDEX.md`** (ADR-20260613190449007 maintenance loop — a stale index is more misleading than none). Judgment rules (from ADR-20260613190449007, verbatim; the ADR text is Chinese):

- 被 ≥2 个 weekly 的 `decisions_accepted` 或 `project_lesson_candidates` 引用 → P0
  (cited by ≥2 distinct weeklies' `decisions_accepted` or `project_lesson_candidates` → P0)
- 已被 `04-ssot/*.md` 引用的模式 → P1
  (already referenced by a `04-ssot/*.md` file → P1)
- 其他 → P2 (everything else → P2)

When this phase absorbs a pattern into an SSOT file, move its INDEX entry to P1 and name the absorbing file in its TL;DR. When a weekly newly cites a pattern for the second time (≥2 distinct weeklies), promote it to P0.

### Phase 3: ZK Validate

After writing SSOT, spawn a **zero-knowledge subagent**:

```
ZK subagent prompt:
  "You have NO prior context about this project. Read these SSOT files:
   - cortex/wiki/04-ssot/architecture.md
   - cortex/wiki/04-ssot/conventions.md
   Self-report: what do you understand? What is unclear? What seems contradictory?"

Agent evaluates the ZK subagent's self-report:
  - Misunderstood sections → SSOT needs revision (writing assumed context that doesn't exist)
  - "Where is X?" questions → SSOT is missing a topic
  - Contradictions flagged → SSOT inherited stale info from source docs
```

From lythos-labs/lythoskill, MIT.

More from lythos-labs/lythoskill