good-sleep

name	good-sleep
description	Read JOURNAL.md and reorganise 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: Reorganise JOURNAL.md into Long-Term Memory

This skill reads .agents/docs/JOURNAL.md, identifies semantically related sections, and reorganises 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 distil 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 Analyse 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 this crate:

• A specific subsystem (e.g., "cache-key construction", "singleflight locking", "scoreboard subsystem")
• A specific behaviour or rule (e.g., "rustc argument filtering", "extern_basename_key normalisation")
• A category of integration concerns sharing a common mechanism (e.g., "RUSTC_WRAPPER bypass for the wrapper itself")

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., cache-key-construction.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

<Reorganised, 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 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, synthesise them into a coherent narrative. Remove chronological framing ("On 2026-02-22 we discovered...") and write in a timeless reference style.
• Preserve precision. Keep exact file paths, command lines, regex patterns, table data, and code snippets. These are high-value reference material.
• Keep tables. Tables from JOURNAL.md (test cases, data patterns, etc.) should be preserved or consolidated.
• Use British English spellings per CLAUDE.md (e.g., "behaviour", "normalise", "organise"). Technical programming terms that are conventionally American (e.g., serialize in Rust/serde context) are exempt.
• Use half-width parentheses with spaces before/after when adjacent to non-whitespace (per CLAUDE.md rules).
• Use half-width colons followed by a space (per CLAUDE.md rules).
• No full-width colons or parentheses in the LTM documents.

Step 5: Create an Index

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

# Long-Term Memory Index

| Document | Summary |
|----------|---------|
| [cache-key-construction.md](cache-key-construction.md) | How the wrapper builds path-normalised cache keys for rustc invocations |
| ... | ... |

Step 6: Trim JOURNAL.md

After creating LTM documents, do NOT delete existing JOURNAL.md content (per CLAUDE.md: never edit existing entries in place). 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.

(For deeper cleanup that removes already-consolidated journal entries, see the reconcile-journal-ltm skill — that workflow is the explicit exception to the append-only rule.)

Step 7: Update CLAUDE.md Reference (if needed)

If .agents/docs/LTM/ is not already referenced in any project documentation, suggest adding a reference to the project's CLAUDE.md or OVERVIEW.md so that agents know to consult LTM documents.

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.