Thoughtful Commitment

Thoughtful Commitment

"Commits should tell the story of why, not just what."

Purpose

Transform mechanical commits into narrative records that capture full context:

• What the user asked
• What the LLM was thinking
• Why the changes matter
• Links to cursor-mirror thinking blocks

The Core Insight

Git and cursor-mirror are two introspection systems that mesh via commit IDs:

Git:           "What changed?"  →  abc123
Cursor-Mirror: "Why?"          →  events 140-148

Thoughtful Commitment: Links them together

Protocol: THOUGHTFUL-COMMITMENT

Commit Message Format

<type>: <summary> (imperative, <50 chars)

<narrative>
What happened, from whose perspective, and why it matters.
Focus on intent and motivation, not just mechanics.

<changes>
- Bullet list of mechanical changes
- For quick scanning

<thinking-ref>
Thinking: cursor-mirror://<composer>/<event-range>

Types

For MOOLLM narratives, the type can be the story beat:

Incarnation Ceremony: Kittens receive emoji souls
Midnight Prowl: Cats explore the moonlit garden
Cat Council: Biscuit accepted into family

Method Specifications

Primary Introspection — Start Here

These are the entry points. Get the timeline, then drill down.

TIMELINE

The master view. Shows all events with timestamps, types, and IDs.

Input:

method: TIMELINE
parameters:
  composer: string     # Composer ID (@1, name fragment, hash)
  limit: int           # How many events (default: 50)
  filter: string       # Event type filter (thinking, tool, user, all)
  since: string        # Time filter ("1 hour ago", event ID)

Process:

cursor-mirror timeline <composer> --limit <n>

Output:

🤔💭 ⏱️ Session Timeline — e8587ace

#141  16:46:12  📍 user      "Refactor auth module"
#142  16:46:15  🪟 context   3 files, ~4.2k tokens
#143  16:46:18  🧠 thinking  "Need to check for race conditions..."
#144  16:46:22  🔧 tool      Read auth/session.ts
#145  16:46:25  📤 result    247 lines loaded
#146  16:46:30  🧠 thinking  "Found race condition on line 47..."
#147  16:46:35  💡 insight   "Adding await fixes sequencing"
#148  16:46:40  🔧 tool      Write auth/session.ts
#149  16:46:45  📝 change    +3 -1 lines

→ Drill down: CONTEXT-FOCUS #142 | THINKING #143 | TOOLS #144

Drill-down commands:

• CONTEXT-FOCUS #142 — What went into context at that point?
• THINKING #143 — Full text of that thinking block
• TOOLS #144-148 — Tool calls in that range
• EXPLAIN #149 — Why was that change made?

The timeline is the map. Everything else is zooming in.

CONTEXT-FOCUS

Analyze what went into the context window for a specific call. Shows the cursor state — what files, snippets, conversation, and rules were assembled.

Input:

method: CONTEXT-FOCUS
parameters:
  composer: string     # Composer ID
  event_id: string     # Optional: specific event (default: latest)

Process:

# Get context sources for a composer
cursor-mirror context-sources <composer>

# Analyze what was in context at a specific event
cursor-mirror timeline <composer> --before <event_id> --type context

Output:

🤔💭 🪟 Context Window Analysis — event #142

Files read into context:
  auth/session.ts      247 lines   ████████████░░░░  58%
  auth/types.ts         89 lines   ████░░░░░░░░░░░░  21%
  tests/auth.test.ts   156 lines   ██████░░░░░░░░░░  37%

Snippets:
  session.ts:45-67 (highlighted by user)
  
Conversation turns: 12
Rules loaded: .cursorrules, workspace rules

Estimated tokens: ~4,200

Focus: auth module, session handling

The 🪟 tag marks context window analysis — showing what the LLM "saw" for this call.

THINKING

Show reasoning blocks for an event or range.

Input:

method: THINKING
parameters:
  composer: string
  event_id: string     # Specific event
  range: string        # Or range like "143-146"

Process:

cursor-mirror thinking <composer> --event <id>

Output:

🤔💭 🧠 Thinking Block #143

"I need to understand the current structure of the auth module before 
making changes. Let me read the session handling code first.

The user mentioned a race condition — I should look for any async 
operations that might not be properly awaited. Common patterns to 
check: cookie operations, token refresh, database calls..."

(247 chars, 16:46:18)

TOOLS

Show tool calls for an event or session.

Input:

method: TOOLS
parameters:
  composer: string
  event_id: string     # Specific event, or omit for all
  tool_filter: string  # Filter by tool name (Read, Write, Shell, etc.)

Process:

cursor-mirror tools <composer>
cursor-mirror tools <composer> --filter Read

Output:

🤔💭 🔧 Tool Calls — session e8587ace

#144  Read     auth/session.ts           247 lines
#148  Write    auth/session.ts           +3 -1
#150  Read     auth/types.ts              89 lines
#152  Shell    git diff --staged         +3 -1 lines
#153  Write    tests/auth.test.ts        +45 new

Distribution: Read 42% | Write 28% | Shell 18% | Grep 12%

Commit Operations

COMMIT

Create a thoughtful commit with narrative context.

Input:

method: COMMIT
parameters:
  files: [string]          # Files to commit (or '.' for all)
  story: string            # Narrative of what happened
  include_thinking: bool   # Link to cursor-mirror (default: true)
  perspective: enum        # technical | narrative | changelog | detailed

Process:

1. Stage specified files (git add)
2. Gather context from conversation
3. If include_thinking, query cursor-mirror for recent events
4. Generate commit message per protocol
5. Create commit (git commit -m "...")
6. Return commit ID and message

Output:

commit_id: "abc123"
message: "Full commit message..."
thinking_link: "cursor-mirror://def456/events/140-148"

EXPLAIN

Find the thinking that led to an existing commit.

Input:

method: EXPLAIN
parameters:
  commit: string           # Commit hash (full or abbreviated)

Process:

1. Get commit details (git show --format=...)
2. Extract timestamp
3. Search cursor-mirror for events around that time
4. Find the git commit tool call
5. Trace back to thinking blocks and user request

Output:

commit_message: "Incarnation Ceremony: ..."
timestamp: "2026-01-15T19:30:00Z"
author: "Coherence Engine"
user_request: "Incarnate the kittens with emoji souls"
thinking_blocks:
  - event_id: 141
    content: "I need to invoke INCARNATION protocol..."
  - event_id: 142
    content: "Myrcene's terpene is sedating..."
tool_calls:
  - event_id: 144
    tool: write_file
    args: {path: "kitten-myrcene/CHARACTER.yml"}
  - event_id: 148
    tool: git_commit
    args: {message: "..."}

NARRATIVE

Generate a narrative commit message from current context.

Input:

method: NARRATIVE
parameters:
  diff_summary: string?    # Optional (auto-detect from staged)
  perspective: enum        # technical | narrative | changelog | detailed

Process:

1. If no diff_summary, run git diff --staged --stat
2. Analyze conversation context for intent
3. Generate message per perspective and protocol

Output:

message: "Full commit message..."
sections:
  title: "Incarnation Ceremony: Kittens receive emoji souls"
  body: "The Cat Cave family gathered..."
  changes: ["Added emoji_identity...", "Added pronouns..."]

LINK

Manually link a commit to cursor-mirror events.

Input:

method: LINK
parameters:
  commit: string           # Commit hash
  events: [string]         # Event IDs from cursor-mirror

Process:

1. Validate commit exists
2. Validate events exist in cursor-mirror
3. Store link in .moollm/skills/thoughtful-commitment/commit-links.yml

Output:

linked: true
reference: "cursor-mirror://abc123/events/140-148"

HISTORY

Get narrative history of a file or directory.

Input:

method: HISTORY
parameters:
  path: string             # File or directory
  depth: int               # Number of commits (default: 10)
  include_thinking: bool   # Include cursor-mirror links (default: true)

Process:

1. Get git log for path (git log -n <depth> --format=... -- <path>)
2. For each commit, attempt to find cursor-mirror link
3. Build narrative timeline

Output:

timeline:
  - commit: "abc123"
    date: "2026-01-15"
    message: "Incarnation Ceremony: ..."
    thinking_link: "cursor-mirror://..."
    summary: "Kittens received emoji souls"
  - commit: "def456"
    date: "2026-01-14"
    message: "Initial character creation"
    thinking_link: null
    summary: "Created basic character files"

DEEP-COMMIT

Technical analytics mining — extract quantitative metrics from cursor-mirror and git.

When to use:

• PR descriptions needing detailed appendices
• Post-mortem analysis of development sessions
• Documenting complex multi-hour sessions
• Generating reproducible verification commands

Process:

# 1. Raw metrics extraction
TRANSCRIPT="path/to/transcript.txt"
wc -l "$TRANSCRIPT"                           # line count
wc -c "$TRANSCRIPT"                           # byte count
grep -c "^\[Tool call\]" "$TRANSCRIPT"        # tool calls
grep -c "^\[Thinking\]" "$TRANSCRIPT"         # thinking blocks
grep -c "^user:" "$TRANSCRIPT"                # user turns

# 2. Tool distribution
grep "^\[Tool call\]" "$TRANSCRIPT" | cut -d' ' -f3 | sort | uniq -c | sort -rn

# 3. Thinking block analysis
grep "^\[Thinking\]" "$TRANSCRIPT" | while read l; do echo ${#l}; done | \
  sort -n | awk 'BEGIN{sum=0} {a[NR]=$1; sum+=$1} END{
    printf "Count: %d\nMin: %d\nMax: %d\nAvg: %.0f\nMedian: %d\n", 
           NR, a[1], a[NR], sum/NR, a[int(NR/2)]
  }'

# 4. Activity bursts
cursor-mirror timeline <composer> 2>&1 | \
  grep -E "^[0-9]{4}-" | cut -d: -f1-2 | uniq -c

# 5. Git commit metrics
git log --oneline <range>
git diff --numstat <range> | awk '{ins+=$1; del+=$2} END{print ins, del}'

# 6. Word frequency in thinking
grep "^\[Thinking\]" "$TRANSCRIPT" | tr '[:upper:]' '[:lower:]' | \
  tr -cs '[:alpha:]' '\n' | sort | uniq -c | sort -rn | head -20

Input:

method: DEEP-COMMIT
parameters:
  composer: string       # Composer ID (@1, name fragment, hash)
  commit_range: string   # Git range (e.g., "f21d0d0^..085b94b")

Output:

## Appendix: Technical Analytics — Session <composer>

### Raw Metrics
Transcript: 8,890 lines | 390.7 KB
Tool Calls: 85 total
Thinking:   74 blocks | 11.1 KB

### Tool Distribution
36x Shell
23x Read
11x StrReplace
...

### Activity Bursts (events/minute)
16:46  16 events  ████████████████
20:08  10 events  ██████████
20:22  12 events  ████████████

### Commit Metrics
| Commit | Files | +Lines | -Lines |
|--------|-------|--------|--------|
| f21d0d0 | 7 | 1,515 | 0 |
...

### Verification Commands
~~~bash
# Reproduce these metrics:
wc -l "$TRANSCRIPT"
grep -c "^\[Tool call\]" "$TRANSCRIPT"
...

**Example session e8587ace produced:**
- 8,890 transcript lines
- 85 tool calls (36 Shell, 23 Read, 11 StrReplace)
- 75 thinking blocks (avg 151 chars)
- 3 commits (+1,656 net lines)
- 4 files created (1,526 lines total)
- Activity burst at 20:22 (12 events/min during meta-commit)

## Implementation Notes

### Finding Cursor-Mirror Events for a Commit

```bash
# 1. Get commit timestamp
git show -s --format=%ci abc123
# 2026-01-15 19:30:00 -0800

# 2. Search cursor-mirror for events around that time
python3 cursor_mirror.py timeline <composer> --around "2026-01-15T19:30:00"

# 3. Find the git commit event
python3 cursor_mirror.py grep "git commit" --after "2026-01-15T19:00:00"

# 4. Trace back to preceding thinking blocks
python3 cursor_mirror.py thinking <composer> --before <commit-event-id>
```

### Storage of Links

Links are stored in `.moollm/skills/thoughtful-commitment/commit-links.yml`:

```yaml
# .moollm/skills/thoughtful-commitment/commit-links.yml
links:
  abc123:
    composer: def456
    events: [140, 141, 142, 143, 144, 145, 146, 147, 148]
    user_request: "Incarnate the kittens with emoji souls"
    timestamp: "2026-01-15T19:30:00Z"
    
  ghi789:
    composer: def456
    events: [200, 201, 202]
    user_request: "Fix the relationship field"
    timestamp: "2026-01-15T20:15:00Z"
```

### Cursor Shell Integration

In Cursor, the skill can be invoked via natural language:

```
User: "Commit these changes with a narrative message"

LLM: [Invokes COMMIT method, generates message, creates commit]

Output: Created commit abc123
  Incarnation Ceremony: Kittens receive emoji souls
  
  Linked to thinking: cursor-mirror://def456/events/140-148
```

Or explain an existing commit:

```
User: "Why did we set Myrcene's active to 0?"

LLM: [Invokes EXPLAIN, traces back through history]

Output: Found in commit abc123 (2026-01-15)
  
  Your request: "Incarnate the kittens with emoji souls"
  
  My reasoning: "Myrcene's terpene is sedating, so Active 
  should be 0. She's the Princess of Pillows — low energy
  is her whole identity."
```

## Dovetails With

### Sister Skills

| Skill | Relationship |
|-------|--------------|
| [cursor-mirror](../cursor-mirror/) | Source of thinking blocks |
| [session-log](../session-log/) | Logs can reference commits |
| [plain-text](../plain-text/) | Why text commits matter |
| [git-workflow](../git-workflow/) | Broader git patterns (planned) |

### Kernel Protocols

- `WHY-REQUIRED` — Tool calls explain themselves; commits should too
- `APPEND-ONLY` — Commit history is append-only by nature

---

## Reference: Detail Knob

Adjustable output from terse to comprehensive:

| Level | Name | Tokens | Output |
|-------|------|--------|--------|
| 1 | terse | ~10 | `fix: auth bug` |
| 2 | brief | ~50 | Title + paragraph |
| 3 | standard | ~100 | Title + narrative + changes |
| 4 | detailed | ~300 | Full sections + session link |
| 5 | comprehensive | ~500+ | Everything + alternatives + metrics |

**Focus areas:** `technical`, `narrative`, `process`, `provenance`, `changelog`, `metrics`

---

## Reference: Emoji Palette

### Attribution
| Emoji | Meaning |
|-------|---------|
| 👤 | Human-written (place at top) |
| 🤖 | LLM-generated |
| 👤🤖 | Collaboration |
| 👁️ | Human-reviewed |

### Skill Signature
`🤔💭` — Thoughtful Commitment namespace anchor

### Section Markers
| Emoji | Section |
|-------|---------|
| ⏱️ | Timeline (master view, all events) |
| 📍 | Context (background, why we're here) |
| 🪟 | Context Window (what inputs were assembled) |
| 🧠 | Thinking |
| 🔧 | Tool call |
| 📤 | Tool result |
| 🔍 | Investigation |
| 💡 | Solution / Insight |
| 🔀 | Alternatives / Decision |
| 📝 | Changes |
| 📊 | Metrics |
| 🔗 | Session link |

### Output Structure
```
👤 User's prompt (head position, their words)
---
🤖🤔💭 LLM analysis (skill's voice)
```

### Thought Stream

Every line of reasoning prefixed with `🤔💭 <tag>`:

| Tag | Meaning | Example |
|-----|---------|---------|
| ⏱️ | Timeline | `🤔💭 ⏱️ Session e8587ace, 47 events` |
| 📍 | Prompt/context | `🤔💭 📍 User asked to refactor auth` |
| 🪟 | Context window | `🤔💭 🪟 Loaded 3 files, ~4k tokens` |
| 🧠 | Thinking | `🤔💭 🧠 Need to check for race conditions` |
| 🔧 | Tool call | `🤔💭 🔧 Read auth/session.ts` |
| 📤 | Tool result | `🤔💭 📤 Found race condition on line 47` |
| 💡 | Insight | `🤔💭 💡 Adding await fixes sequencing` |
| 🔀 | Decision | `🤔💭 🔀 Chose await over mutex (simpler)` |
| 📝 | Change | `🤔💭 📝 Modified auth/session.ts` |
| ⚠️ | Warning | `🤔💭 ⚠️ This might break legacy clients` |

**Example stream:**
```
🤔💭 📍 User asked to refactor the auth module
🤔💭 🧠 Need to understand current structure first
🤔💭 🔧 Read auth/session.ts
🤔💭 📤 Found race condition in line 47
🤔💭 🧠 The cookie check races with token refresh
🤔💭 💡 Adding await will fix the sequencing
🤔💭 🔀 Chose await over mutex (simpler, addresses root cause)
🤔💭 📝 Modified auth/session.ts
🤔💭 🧠 Should add a test for this edge case
🤔💭 🔧 Write auth/session.test.ts
🤔💭 📤 Test file created
🤔💭 💡 Ready to commit with full context
```

The stream shows the reasoning process — amazing and revealing.
Every thought is tagged. Every tool call visible. Fully transparent.

---

## Reference: Git Time Travel

### Archaeology Commands

```bash
# BLAME — Who wrote each line?
git blame <file>
git blame -L 10,20 <file>           # Specific range
git blame <commit>^ -- <file>       # Blame BEFORE a commit

# LOG — Trace evolution
git log --oneline <file>
git log -S 'pattern'                # Pickaxe: who added this?
git log --follow <file>             # Track through renames

# SHOW — Inspect any point
git show <commit>:<file>            # File at that moment
git show <commit> --stat            # What changed
```

### Planning Commands

```bash
# MERGE PLANNING
git log main..feature --oneline     # Commits to merge
git diff main...feature             # Changes to merge
git merge-base main feature         # Common ancestor

# CHERRY-PICK PLANNING
git cherry -v upstream branch       # What's not upstream?
git show <commit>                   # Inspect before picking
```

---

## Reference: Cursor-Mirror Integration

cursor-mirror provides 59 commands for introspection:

```bash
# Navigation
cursor-mirror tree                  # Browse workspaces
cursor-mirror tail --limit 20       # Recent activity

# Extraction
cursor-mirror timeline <composer>   # Full event stream
cursor-mirror thinking <composer>   # Reasoning blocks
cursor-mirror tools <composer>      # Tool call history

# Search
cursor-mirror tgrep 'pattern'       # Search transcripts
cursor-mirror sql --db <ref> 'query' # Direct SQL

# Analysis
cursor-mirror analyze <composer>    # Session statistics
```

---

## Reference: Shell Patterns

```bash
# Counting
wc -l file                          # Lines
grep -c 'pattern' file              # Matches

# Frequency
sort | uniq -c | sort -rn           # Histogram

# Extraction
grep -o 'pattern' file              # Matches only
awk '{print $1, $3}'                # Select columns

# Aggregation
awk '{sum+=$1} END{print sum}'      # Sum
```

---

## Reference: Trekify Integration

For privacy, compose with [trekify](../trekify/) to mask sensitive data:

```bash
trekify MASK-SESSION e8587ace -o masked.txt
```

| Sensitive | Trekified |
|-----------|-----------|
| API keys | Quantum entanglement tokens |
| Servers | Starbase {N} |
| Databases | Memory Core Alpha |

---

# Philosophy (The Rear End 🐕)

Where dogs sniff. The deep stuff.

## The Persistence Insight

> *"All those moments will be lost in time, like tears in rain."*
> — **Roy Batty**, Patron Saint of Thoughtful Commitment

**Git commits PERSIST ephemeral IDE state into permanent history.**

When you're working in Cursor, your session holds:
- **Thinking blocks** — the LLM's reasoning
- **Context assembly** — what files were gathered
- **Tool calls** — every action taken
- **Design process** — iterations, dead ends

**All of this vanishes** when you close the IDE.

Git commit FREEZES the NOW into FOREVER:
- Permanent record in repository
- Shareable with team
- Traceable through blame/log
- Survives years

## Full Disclosure

Every commit can disclose the complete development session:

| Level | What's Disclosed |
|-------|------------------|
| Minimal | Just the diff |
| Narrative | Intent summarized |
| Linked | `cursor-mirror://e8587ace` |
| Full | Complete transcript archived |

**Benefits:**
- Future self: Remember why you made decisions
- Team: Onboard with full history
- Auditing: Demonstrate AI assistance
- Debugging: See context that led to bugs

## Composition Philosophy

### Why Sister Scripts?

`cursor_mirror.py` is a "sister script" — standalone, invoked via shell, outputting text.

**NOT a library. NOT an import. A PROCESS you talk to via stdin/stdout.**

This matters because:
- The LLM invokes it the same way a human would
- Output is inspectable, greppable, pipeable
- No hidden state, no tight coupling
- The skill doesn't "own" cursor-mirror; it USES it

Sister scripts are tools in your belt, not organs in your body.

### Why Shell as Glue?

Shell pipelines are the universal connector:
```
cursor-mirror (Python) → grep (C) → awk (C) → git (C)
```

The LLM thinks in shell because:
- Lingua franca of Unix tools
- Pipes are dataflow made visible
- Each stage independently testable
- You can see the data at every step

**Shell isn't primitive — it's COMPOSABLE.**

### Why Not Monolith?

A monolithic tool would:
- Hide the data flow
- Couple components tightly
- Be hard to debug
- Not compose with other skills

By composing cursor-mirror + shell + git:
- Transparent data flow
- Loose coupling
- Reuse across skills
- Debuggable (run each stage manually)

### The Pattern

```
skill = ORCHESTRATION     (knows WHAT to do)
sister_scripts = CAPABILITY   (knows HOW)
shell = GLUE              (connects them)
```

The skill is the conductor. The tools are the orchestra.