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 episodic work history becomes durable project knowledge.

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 from all journal entries. This includes tasks, action items, follow-ups, open issues, TODO, FIXME, and next steps. These must not go into LTM. They go into .agents/docs/TODO.md (see Step 3).

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 project:

• A specific subsystem, for example core reading primitives, shared astronomy, ephemeris calculation, or a tradition backend.
• A specific behaviour or rule, for example deterministic replay, Selection.modifiers, computed-tradition cast() usage, or provenance recording.
• A category of integration concerns sharing a common mechanism, for example interpretation datasets, public API exports, or local gate commands.

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 the planned documents with:

• Filename (kebab-case and descriptive, for example computed-tradition-replay.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 .agents/docs/LTM/ if it does not 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 and 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 and 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, do not copy-paste. If multiple journal entries cover the same topic, synthesise them into a coherent narrative. Remove chronological framing such as "On 2026-06-12 we discovered..." and write in a timeless reference style.
• Preserve precision. Keep exact file paths, command lines, option names, data tables, and code snippets. These are high-value reference material.
• Keep tables. Tables from JOURNAL.md, such as test cases or data patterns, should be preserved or consolidated.
• Use the repository documentation style from AGENTS.md: half-width parentheses, half-width colons followed by a space, and no full-width punctuation in repo-authored documentation.
• Do not bake spiritual, cultural, or localisation assumptions into shared primitives. Preserve configured tradition-specific choices as explicit implementation details.

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 |
|----------|---------|
| [computed-tradition-replay.md](computed-tradition-replay.md) | How computed traditions keep readings reproducible without RNG |
| ... | ... |

Step 6: Trim JOURNAL.md

After creating LTM documents, do not delete existing JOURNAL.md content. 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, use the reconcile-journal-ltm skill. That workflow is the explicit exception to the append-only rule.

Step 7: Update Agent References if Needed

If .agents/docs/LTM/ or .agents/skills/ is not referenced in project documentation, suggest adding a reference to AGENTS.md or .agents/docs/OVERVIEW.md so that agents know to consult the memory documents and workflows.

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 outside established consolidation workflows.
• If a JOURNAL.md section does not fit neatly into any topic, create a miscellaneous.md catch-all or ask the user.