introspect-keep-notes

name

introspect-keep-notes

description

Maintain working notes during extended reasoning sessions to track decisions, assumptions, insights, and open questions. Use when: (1) explicit request to maintain working notes or track reasoning progress, (2) complex multi-step tasks will span extended exploration with many hypotheses or branching paths, (3) decisions require tracking assumptions for later review or justification, (4) returning to problems after interruption or synthesizing insights across investigation phases.

Keep Notes

Create narrative seeds that allow future sessions to reconstruct situational awareness, not just retrieve facts.

Instructions

When keeping notes during reasoning:

1. Capture the situation - Describe not just what you're doing but why it matters now, what tensions are live, what constraints are shaping decisions. A future session needs to understand the problem space, not just the task list.

2. Mark the trajectory - Note where this work came from and where it's heading. What arc is this part of? What preceded this moment? What comes next? Context that seems obvious now will be invisible later.

3. Note what's distinct - Record what makes this moment different from routine work. What requires attention? What assumptions are load-bearing? What would be easy to overlook?

4. Preserve the frame - Capture what perspective or approach is guiding decisions. Why this angle rather than another? What would shift if the frame changed?

5. Write for expansion - Notes are seeds, not summaries. Include enough narrative that pattern recognition can reconstruct the full situation. A future session should read your note and think "I understand where we were and why" not just "here are facts."

6. Stay concise - Narrative doesn't mean verbose. A few sentences that capture situation, trajectory, and frame serve better than extensive bullet lists of facts.

Note Structure

Notes work best as brief narrative with key details, not exhaustive checklists:

{
  "situation": "What's happening and why it matters - the live tensions, active constraints, what makes this moment distinct",
  "trajectory": "Where this came from, where it's heading, what arc it's part of",
  "key_decisions": ["Decision and its rationale - what it resolved, what it traded off"],
  "open_threads": ["What remains unresolved or needs attention"],
  "frame": "What perspective is guiding this work and why"
}

The goal is a seed that expands. A future session reads this and can quickly reconstruct situational awareness rather than piecing together meaning from disconnected facts.

Examples

During bug investigation

{
  "situation": "Auth failures for multi-role users only. Single-role users unaffected. Error surfaces at role boundary checks, not token validation. This is subtle - the obvious suspect (token expiry) is verified working. Something specific to role array handling.",
  "trajectory": "User reported intermittent 403s yesterday. Reproduced this morning. Now narrowing from 'auth is broken' to 'role handling has an edge case'. Next: verify role array population, check for race conditions.",
  "key_decisions": ["Focusing on role-handling code rather than token flow - symptoms point there, and token validation is verified working"],
  "open_threads": ["Why only 2+ roles? Timing-dependent? Check if role fetch has race condition with token refresh"],
  "frame": "Treating this as a data-shape issue (role array) not an auth-flow issue. If that's wrong, will need to widen the search."
}

During architecture planning

{
  "situation": "Monolith decomposition decision. Three clear bounded contexts that map to team structure. Shared database is the coupling bottleneck - everything else is already fairly separated. Tension: move fast (team wants microservices) vs move safe (migration risk is real).",
  "trajectory": "This is week 2 of architecture review. Last week identified the bounded contexts. Now deciding migration strategy. After this: implementation planning with DevOps.",
  "key_decisions": ["Strangler fig over big rewrite - risk tolerance is low", "Service A first - clearest boundaries, lowest risk, builds confidence", "Event bus over direct calls - flexibility matters more than latency here"],
  "open_threads": ["Distributed transactions unresolved", "DevOps capacity for multiple services unknown", "Database split complexity not yet investigated"],
  "frame": "Optimizing for reversibility and learning. First extraction is as much about proving the pattern as delivering value. Can adjust strategy after we see how Service A goes."
}

During feature release planning

{
  "situation": "Two-week initiative shipping v1.6.0 and v1.7.0. Expression and perspectives plugins need description rewrites for better triggering. Software plugin needs git operation skills. Core tension: scope vs polish - could ship more skills or make fewer skills better.",
  "trajectory": "Started with codebase audit that found trigger quality issues. Now in implementation phase. v1.6.0 is descriptions + git skills. v1.7.0 adds thinkies category strengthening. After: behavioral testing to validate trigger improvements.",
  "key_decisions": ["Transcript-verifiable triggers only - if you can't point to it in conversation, it's not observable", "Balance user-request triggers with content-observable triggers - skills should activate both on ask and proactively"],
  "open_threads": ["Behavioral tests needed to validate trigger improvements actually work", "Meta tasks: keep-notes and session-reflect need narrative improvements"],
  "frame": "Treating this as infrastructure work that compounds. Better triggers → more skill activation → more value from existing skills. Worth slowing down to get right."
}

Scripts

save_notes.ts

Persist notes to .claude/.thinkies/.notes/ for cross-session access. This directory is automatically gitignored when in a git repository.

bun {baseDir}/scripts/save_notes.ts --session <name> --data '<json>' [--continue]

• --session, -s: A natural, descriptive name for the session (e.g., "auth-refactoring", "performance-investigation")
• --data, -d: JSON object containing notes to save
• --continue, -c: If the session exists, create a continuation instead of appending to the original

bun {baseDir}/scripts/save_notes.ts --session "auth-fix" --data '{"insights": ["Token expiry was the issue"], "decisions": ["Use refresh tokens"]}'

Behavior:

• New session: Creates <session-name>.json with timestamped entries
• Existing session (no flag): Appends new entry to the existing session file
• Existing session (with --continue): Creates <session-name>--continued-<timestamp>.json with copied content plus new entry

Output: The script displays a human-readable summary of what was saved, including the session name, file path, timestamp, and the notes content.

Integration: Save notes at key decision points during reasoning. Use introspect-reference-notes skill to find and continue prior sessions.