introspect-reference-notes

name

introspect-reference-notes

description

List, search, and reference prior reasoning sessions to build on previous work Use when: (1) asked to reference or build on prior reasoning sessions, (2) At the start of `/reason` or `/reason-session` to check for relevant prior work, (3) When the user mentions something they worked on before, (4) When you need context about past decisions in this repository, (5) Before starting work that might duplicate prior reasoning, (6) When synthesizing insights across multiple reasoning sessions

Reference Notes

Access and search through prior reasoning sessions to find relevant context, continue previous work, or learn from past decisions.

Instructions

When referencing prior notes:

1. List recent sessions to see what reasoning work exists in this repository. The last 10 sessions are shown by default, sorted by most recent.

2. Search for relevant sessions when you have a specific topic in mind. Search looks through session content for keyword matches.

3. Read a session's content to understand what was explored, decided, and learned in that session.

4. Offer to continue when you find a relevant prior session. Creating a continuation preserves the original while letting you build on its insights.

Usage Patterns

At the start of a reasoning session

Before beginning new reasoning work, check if relevant prior sessions exist:

List sessions to see recent reasoning work in this repository.
If any seem related to the current problem, read their content.
Offer to continue from a relevant session rather than starting fresh.

When the user mentions prior work

If the user references something they worked on before:

Search sessions for keywords from their description.
Show matching sessions with their dates and summaries.
Let them choose which to continue or reference.

Finding the latest in a lineage

Sessions can be continued, creating a chain. When looking for a session by name, find the most recent in its lineage (the latest --continued-* version).

Scripts

list_sessions.ts

List the most recent sessions with metadata.

Usage:

bun {baseDir}/scripts/list_sessions.ts [--count <n>]

Options:

• --count, -n: Number of sessions to show (default: 10)

Output: A formatted table showing session names, creation dates, and entry counts, sorted by most recent first. Continuations are marked with (cont.).

search_sessions.ts

Search session content for keywords.

Usage:

bun {baseDir}/scripts/search_sessions.ts --keyword <term>

Options:

• --keyword, -k: Search term (required, case-insensitive)

Output: A formatted table of matching sessions sorted by number of matches, showing session names, creation dates, and match counts.

read_session.ts

Read a specific session's full content.

Usage:

bun {baseDir}/scripts/read_session.ts --session <name>

Options:

• --session, -s: Session name to read (required)

Output: Full session content in human-readable format, including metadata (creation time, lineage) and all entries with timestamps. Automatically finds the latest in a session's lineage.

Examples

Checking for relevant prior work

"Before we start planning this API refactor, let me check if there's any prior reasoning work on this topic."

# List recent sessions
bun {baseDir}/scripts/list_sessions.ts

# Search for related work
bun {baseDir}/scripts/search_sessions.ts --keyword "api"
bun {baseDir}/scripts/search_sessions.ts --keyword "refactor"

Continuing a prior session

"I found a session called 'api-design-decisions' from last week that covers related ground. Would you like me to continue from that session, or start fresh?"

If continuing:

# Read the prior session content
bun {baseDir}/scripts/read_session.ts --session "api-design-decisions"

# New notes will use --continue flag to create a continuation
bun {keep-notes-baseDir}/scripts/save_notes.ts --session "api-design-decisions" --data '{"phase": "frame", ...}' --continue

Finding session lineage

"Looking for the most recent work on 'auth-refactoring'..."

The read_session.ts script automatically finds auth-refactoring--continued-1732550000 if that's more recent than auth-refactoring.