reflect

What this skill does

Analyze session transcripts from both Claude Code and OpenCode to identify patterns in corrections and feedback, then generate actionable improvements.

## Arguments

Optional: Number of days to analyze (default: 7)

Example: `/reflect 14` to analyze the past 2 weeks.

## Phase 1: Setup

**1.1 Load previous report** (if exists):
- Check for latest report in `~/.dotfiles/.claude/session-analysis/`
- Extract previous improvements and expected results for comparison
- If no previous report exists, note this is the first run

**1.2 Run indexing** (indexes both Claude Code and OpenCode sessions):
```bash
python3 ~/.dotfiles/.claude/skills/reflect/index-sessions.py --days {N}
```

Use `--source claude` or `--source opencode` to limit to one source. Default indexes both.

**1.3 Query flagged turns** from SQLite database at `~/.dotfiles/.claude/sessions.db`:

```python
import sqlite3
conn = sqlite3.connect(str(Path.home() / '.dotfiles' / '.claude' / 'sessions.db'))

# Get all flagged turns from the past N days
query = '''
SELECT
    s.source, s.project, s.id as session_id, s.source_path, s.initial_prompt_preview,
    t.turn_number, t.type, t.line_start, t.line_end, t.source_path as turn_source_path,
    f.flag_type
FROM flags f
JOIN turns t ON f.turn_id = t.id
JOIN sessions s ON t.session_id = s.id
WHERE s.timestamp > datetime('now', '-{N} days')
ORDER BY s.timestamp DESC
'''
```

## Phase 2: Content Extraction

**2.1 Fetch flagged content** from source files:

- **Claude Code turns** (`s.source = 'claude-code'`): Use `line_start`/`line_end` with `fetch_turn_content()` to read from the source JSONL file.
- **OpenCode turns** (`s.source = 'opencode'`): Use `turn_source_path` (the message JSON file path) with `fetch_opencode_turn_content()` — reads the message file and assembles text from its parts.

Both functions are provided by the indexing script.

**2.2 Apply secret redaction** before agent access:
- API keys (sk-*, ANTHROPIC_API_KEY, etc.)
- GitHub tokens (ghp_*, gho_*)
- AWS credentials
- Passwords and secrets
- Bearer tokens
- Private keys

**2.3 Group by session** for context preservation:
- Include initial_prompt_preview for each session
- Include surrounding turns (1-2 turns before/after flagged turn) for context
- Write to temporary markdown files for agent consumption

## Phase 3: Parallel Agent Analysis

Launch 5 specialized agents **in parallel** using the Task tool:

| Agent | Mandate |
|-------|---------|
| **Mistake Finder** | Find Claude errors that user corrected: wrong file, wrong approach, misunderstood request. Focus on `rejection` and `interrupt` flags. |
| **Preference Learner** | Identify implicit user preferences: formatting, communication style, tool choices, workflow patterns. Look for repeated `clarification` patterns. |
| **Command Repeater** | Find repeated slash commands or multi-step workflows that could become skills. Look for patterns in initial prompts. |
| **Prompt Repeater** | Find similar initial prompts across sessions suggesting a skill opportunity. Use `initial_prompt_preview` from sessions table. |
| **CLAUDE.md Miner** | Find project-specific concepts, patterns, or rules that should be documented. Group findings by project. |

**Agent prompt template**:
```
You are analyzing Claude Code and OpenCode session transcripts to find {AGENT_FOCUS}.

Context: {PREVIOUS_REPORT_SUMMARY}

Here are the flagged turns from the past {N} days:

{FLAGGED_CONTENT_MARKDOWN}

For each pattern you find:
1. Describe the pattern clearly
2. Provide 2-3 specific examples with session IDs
3. Explain the root cause
4. Suggest a concrete improvement (skill, CLAUDE.md update, alias, etc.)

Focus on actionable patterns that appear at least 2-3 times.
```

## Phase 4: Consolidation

After all agents complete:

**4.1 Deduplicate findings**:
- Merge similar patterns identified by multiple agents
- Group by improvement type: skill, CLAUDE.md, alias, agent, prompt change

**4.2 Assess previous improvements** (if previous report exists):
- For each prior improvement with an "expected result", check if current data shows improvement
- Mark as: improved, unchanged, or regressed

**4.3 Rank by frequency and impact**:
- Count how many sessions each pattern appears in
- Prioritize patterns that cause most corrections/interrupts

## Phase 5: Interactive Presentation

Present findings to user for decision:

```
## Pattern: {PATTERN_NAME}
Frequency: {COUNT} sessions
Type: {IMPROVEMENT_TYPE}
Root cause: {ANALYSIS}

Examples:
- Session abc123: "{example_excerpt}"
- Session def456: "{example_excerpt}"

Suggested improvement:
{DETAILED_SUGGESTION}

Options:
1. Implement now
2. Defer (add to next week's list)
3. Dismiss (not actionable)
```

For each pattern, ask the user to choose using the AskUserQuestion tool with options.

## Phase 6: Execute Approved Changes

For each "implement now" decision:

**Skills**: Create new file in `~/.dotfiles/.claude/commands/{skill-name}.md`

**CLAUDE.md updates**:
- Global: Edit `~/.dotfiles/.claude/CLAUDE.md`
- Project-specific: Edit `~/.dotfiles/.claude/project-instructions/{project}/CLAUDE.md`

**Bash aliases**: Add to `~/.dotfiles/bash/aliases.sh`

**Agents**: Create new file in `~/.dotfiles/.claude/agents/{agent-name}.md`

## Phase 7: Generate Report

Save report to `~/.dotfiles/.claude/session-analysis/YYYY-MM-DD.md`:

```markdown
# Session Analysis Report - {DATE}

## Summary
- Sessions analyzed: {COUNT}
- Date range: {START} to {END}
- Projects covered: {PROJECT_LIST}
- Flags detected: {interrupt: N, rejection: N, clarification: N}

## Previous Improvements Assessment
{For each prior improvement: status (improved/unchanged/regressed), evidence}

## Patterns Observed
{For each pattern: frequency, examples, root cause, suggested improvement}

## Improvements Made
{For each implemented change: type, file, reason, expected result}

## Improvements Deferred
{For each deferred: reason, trigger to revisit}

## Notes for Next Analysis
{Context that future runs should consider}
```

## Fallback Handling

- **Empty database**: Run indexing first, report if no sessions found
- **No flags detected**: Report healthy session patterns, no corrections needed
- **Agent failures**: Continue with remaining agents, note failures in report
- **Large data volumes**: If >100 flagged turns, chunk into groups of 30 per agent call

## Done When

1. Report is generated and saved
2. All approved improvements are implemented
3. User has reviewed all significant patterns