ctx-consolidate

Analyze entries in LEARNINGS.md and/or DECISIONS.md, group overlapping entries by topic, and (with user approval) merge groups into denser consolidated entries. Originals are archived, not deleted.

Key Distinction

Consolidation != archival. Archival moves old entries to the archive directory. Consolidation replaces verbose entries with tighter ones: the file stays useful, just denser. The originals move to archive as a paper trail.

When to Use

• When ctx drift reports entry counts above threshold (default: 30 learnings, 20 decisions)
• When you notice 3+ entries about the same topic
• When the user asks "clean up learnings", "consolidate context", "reduce noise in decisions"
• Before a release, to keep context lean

When NOT to Use

• When there are fewer than 10 entries (nothing meaningful to group)
• When the user wants to delete entries (offer archival instead)
• Automatically: always require user approval before modifying files
• Mid-task when the user is focused on shipping

Execution

Step 1: Parse Entries

Read the target file(s):

# Check entry counts first
ctx drift --json

Then read the files directly:

• LEARNINGS.md (in the context directory)
• DECISIONS.md (in the context directory)

Parse entries by their ## [YYYY-MM-DD-HHMMSS] Title headers. Each entry extends from its header to the line before the next header or end of file.

Step 2: Extract Keywords and Group

For each entry, extract keywords from its title and body:

1. Split text on whitespace and punctuation
2. Lowercase everything
3. Filter out stop words (the, and, for, with, from, are, was, etc.) and words shorter than 3 characters
4. Deduplicate

Build a keyword-to-entries map. Entries sharing 2 or more non-trivial keywords are candidates for the same group.

Grouping rules:

• Minimum group size: 2 entries (nothing to consolidate with 1)
• Maximum group size: 8 entries (larger groups suggest the topic needs splitting, not merging)
• An entry can only belong to one group (assign to the best match)

Step 3: Present Candidates

Show the user what you found. Format:

Consolidation candidates for LEARNINGS.md:

Group 1: "Hook behavior" (5 entries)
  - [2026-01-15] Hook scripts can lose execute permission
  - [2026-01-20] Two-tier hook output is sufficient
  - [2026-02-03] Claude Code Hook Key Names
  - [2026-02-09] Agent ignores repeated hook output
  - [2026-02-16] Security docs vulnerable after migrations
  -> Proposed: merge into 1 consolidated entry

Group 2: "Path handling" (3 entries)
  - [2026-01-10] Path construction uses stdlib
  - [2026-02-05] G304 gosec false positives
  - [2026-02-16] gosec G301/G306 permissions
  -> Proposed: merge into 1 consolidated entry

Ungrouped: 12 entries (no consolidation needed)

Wait for the user to approve, modify, or reject each group. Do NOT proceed without explicit confirmation.

Step 4: Generate Consolidated Entries

For each approved group, write a consolidated entry that:

• Uses today's timestamp in YYYY-MM-DD-HHMMSS format
• Appends "(consolidated)" to the title
• Lists the date range of originals in a **Consolidated from** line
• Distills each original into 1-2 lines
• Preserves all unique information (nothing is lost)

Format:

## [YYYY-MM-DD-HHMMSS] Hook behavior (consolidated)

**Consolidated from**: 5 entries (2026-01-15 to 2026-02-16)

- Hook scripts can lose execute permission without warning; always
  restore +x after sync operations
- Two-tier output (stdout for AI context, stderr+exit for blocks)
  is sufficient; don't over-engineer severity levels
- Claude Code hook key names are case-sensitive: PreToolUse, not
  pre_tool_use
- Agents develop repetition fatigue: vary hook output phrasing
  across invocations
- After infrastructure migrations, audit security docs first:
  stale paths in security guidance give false confidence

Step 5: Execute Approved Merges

For each approved group:

1. Add the consolidated entry at the top of the file (below the # Learnings or # Decisions header)
2. Remove the original entries from the source file
3. Append originals to archive at archive/learnings-consolidated-YYYY-MM-DD.md in the context directory (or decisions-consolidated-YYYY-MM-DD.md)
4. Rebuild the index:

ctx learning reindex
# or
ctx decision reindex

Step 6: Report Results

Consolidated LEARNINGS.md:
  - Group "Hook behavior": 5 entries -> 1 (originals archived)
  - Group "Path handling": 3 entries -> 1 (originals archived)
  Total: 8 entries consolidated into 2. File reduced from 47 to 41 entries.
  Archive: archive/learnings-consolidated-2026-02-19.md (in context dir)

Archive Format

The archive file uses the same Markdown format as the source file. Each archived entry keeps its original timestamp and content, preceded by a header noting which consolidated entry replaced it:

# Archived Learnings (consolidated 2026-02-19)

Originals replaced by consolidated entries in LEARNINGS.md.

## Group: Hook behavior

## [2026-01-15-120000] Hook scripts can lose execute permission
(original content preserved verbatim)

## [2026-01-20-093000] Two-tier hook output is sufficient
(original content preserved verbatim)

What This Skill Does NOT Do

• Automatic consolidation: always requires user approval
• Cross-file consolidation: learnings stay in LEARNINGS.md, decisions stay in DECISIONS.md
• Delete entries: always archives originals as a paper trail
• Semantic understanding via embeddings: uses keyword matching, which is sufficient for structured entries with consistent formatting
• Consolidate TASKS.md or CONVENTIONS.md: use ctx task archive for tasks; conventions rarely need consolidation

Quality Checklist

Before reporting results:

• Presented all candidate groups before making changes
• Waited for explicit user approval per group
• Each consolidated entry preserves all unique information
• Original entries are archived, not deleted
• Ran ctx reindex after modifications
• Reported what changed and where archives were written