good-sleep

name	good-sleep
description	Read JOURNAL.md and reorganize its contents into semantically separate long-term memory documents under .agents/docs/LTM/. Use when you want to consolidate accumulated journal entries into reusable, topic-organised reference files.
user-invocable	true
allowed-tools	Bash, Read, Write, Edit, Grep, Glob

Good Sleep: Reorganize JOURNAL.md into Long-Term Memory

This skill reads .agents/docs/JOURNAL.md, identifies semantically related sections, and reorganizes them into topic-based documents under .agents/docs/LTM/. This mirrors how the brain consolidates episodic memories into structured long-term knowledge during sleep.

Use this skill when: JOURNAL.md has accumulated multiple entries and you want to distill them into organised, reusable reference documents.

Overview

JOURNAL.md is an append-only chronological log. Over time it grows unwieldy. This skill extracts knowledge from it and organises it by topic (not by date) into separate files under .agents/docs/LTM/.

Step 1: Read and Analyze JOURNAL.md

Read the full contents of .agents/docs/JOURNAL.md.

First, identify and extract any to-do items (tasks, action items, follow-ups, open issues, "TODO", "FIXME", "next steps", etc.) from all journal entries. These must NOT go into LTM — they go into .agents/docs/TODO.md (see Step 3 below).

Identify semantically distinct topics. A "topic" is a cohesive area of knowledge that an agent would want to look up as a unit. Examples of good topic boundaries for imbh:

• A specific subsystem or crate (e.g., "WAL and recovery", "Parquet segment lifecycle", "Tantivy↔Parquet RowSelection bridge", "DataFusion providers and typed plans", "OTLP normalization")
• A cross-cutting concern (e.g., "footprint budgets and dependency trimming", "canonical JSON attribute storage", "metric temporality handling")
• A category of fixes sharing a common mechanism

Do NOT split by date. Multiple journal entries about the same topic should be merged into a single LTM document.

Step 2: Plan the LTM Documents

Before writing, list out the planned documents with:

• Filename (kebab-case, descriptive, e.g., wal-and-recovery.md)
• One-line summary of what knowledge it captures
• Which JOURNAL.md sections (by heading) feed into it

Present this plan to the user for confirmation before proceeding.

Step 3: Extract To-Dos to TODO.md

Before writing LTM documents, collect all to-do items found in JOURNAL.md entries:

• Items explicitly marked as TODO, FIXME, or "next steps"
• Action items or follow-ups described as pending work
• Open issues or unresolved investigations flagged for future attention

Append them to .agents/docs/TODO.md. If the file does not exist, create it with this structure:

# Project To-Dos

Items extracted from JOURNAL.md during good-sleep consolidation. Each item should be resolved or removed once addressed.

## Open Items

- [ ] <task description> — *source: <JOURNAL.md section heading>*

If the file already exists, append new items under the existing ## Open Items section (or add the section if missing). Do not duplicate items that are already listed.

Step 4: Create LTM Documents

Create the directory .agents/docs/LTM/ if it doesn't exist.

For each planned document, create .agents/docs/LTM/<filename>.md with:

Document Structure

# <Topic Title>

## Summary

<2-3 sentence overview of the topic — what it is, why it matters>

## Key Facts

<Bulleted list of the most important facts an agent needs to know>

## Details

<Reorganized, deduplicated content from JOURNAL.md entries>
<Merge overlapping sections, remove redundant context>
<Keep tables, code snippets, and file path references intact>

## Files

<List of relevant source files/crates with brief descriptions>

## Test Coverage

<Summary of test cases and how to run them, if applicable>

## Pitfalls

<Known gotchas, edge cases, and warnings>

Writing Guidelines

• Merge, don't copy-paste. If multiple journal entries cover the same topic, synthesize them into a coherent narrative. Remove chronological framing ("On 2026-07-18 we discovered...") and write in a timeless reference style.
• Preserve precision. Keep exact file paths, commands, type/function names, table data, and code snippets. These are high-value reference material.
• Keep tables. Tables from JOURNAL.md should be preserved or consolidated.
• Follow the documentation style rules in AGENTS.md: half-width parentheses and half-width colons with surrounding spaces.

Step 5: Create an Index

Create or refresh .agents/docs/LTM/INDEX.md that lists all LTM documents with one-line descriptions:

# Long-Term Memory Index

| Document | Summary |
|----------|---------|
| [wal-and-recovery.md](wal-and-recovery.md) | How imbh's WAL, LSN watermark, and crash recovery work |
| ... | ... |

Step 6: Record the Consolidation in JOURNAL.md

After creating LTM documents, do NOT delete existing JOURNAL.md content (per AGENTS.md: never edit existing sections). Instead, append a note at the end of JOURNAL.md:

---

## LTM Consolidation Record

The following sections have been consolidated into long-term memory documents under `.agents/docs/LTM/`:

| Section | LTM Document |
|---------|-------------|
| <original heading> | <LTM filename> |
| ... | ... |

See `.agents/docs/LTM/INDEX.md` for the full index.

Notes

• This skill is idempotent: running it again should detect already-consolidated sections and only process new JOURNAL.md entries added since the last consolidation.
• LTM documents are meant to be edited and refined over time, unlike JOURNAL.md which is append-only.
• If a JOURNAL.md section doesn't fit neatly into any topic, create a miscellaneous.md catch-all or ask the user.