brain-reflect - SKILL.md Agent Skill

name: brain-reflect model: claude-opus-4-6 context: forked description: AI self-review - analyzes recent sessions, patterns, and proposes improvements. Use when the user says "reflect", "self-review", "analyze patterns", "how are we doing", "review sessions", "meta-analysis", or wants insight into recurring themes and AI performance.

Analyze recent session logs, corrections, and vault activity to identify recurring patterns, frequent mistakes, the user's working habits, and opportunities for rule improvements. Generate a reflection report with actionable proposals.

Step 1: Determine Time Range

If the user specified a time range (e.g., "7 days", "30 days", "this week"), use that. If no range specified, default to the last 7 days.

Calculate the date range and identify which session logs and daily notes fall within it.

Step 2: Gather Data

Read the following within the time range:

Session logs (Machine/Session-Logs/): All logs within the date range.
Corrections (Machine/Memory/corrections.md): All corrections, noting dates.
Decisions (Machine/Memory/decisions.md): Recent decisions.
Daily notes (Human/Daily/): Notes within the date range.
Active rules (Machine/Rules/active-rules.md): Current rules for comparison.
Rule changelog (Machine/Rules/rule-changelog.md): Recent rule changes.

Step 3: Analyze Patterns

Session Patterns

Frequency: How many sessions in the period? Average per day?
Duration: How long are sessions typically?
Topics: What subjects come up most often?
Productivity: What is the ratio of accomplishments to open items?

Correction Patterns

Frequency: How many corrections in the period?
Categories: Group corrections by type (formatting, tone, process, content, etc.)
Repeats: Are the same corrections being given multiple times? This indicates a rule that is not being followed or a missing rule.
Promotion rate: How many corrections have been promoted to rules?

Task Patterns

Completion rate: Of tasks that appear in daily notes, how many get checked off?
Carryover frequency: How often do tasks carry over between days?
Eat-the-frog items: Tasks that have persisted the longest
Peak productivity: Any patterns in when tasks get completed (time of day, day of week)?

Decision Patterns

Volume: How many decisions in the period?
Reversals: Any decisions marked as superseded?
Decision domains: What areas are decisions being made in?

User Working Patterns

Session timing: When does the user typically start sessions?
Focus areas: What projects or topics get the most attention?
Workflow style: Does the user prefer long deep sessions or short bursts?
Common requests: What types of tasks does the user most often ask for?

Step 4: Generate Proposals

Based on the analysis, propose specific improvements:

Rule Proposals

New rules derived from repeated corrections
Rule modifications based on observed drift
Rules to remove if they are consistently irrelevant

Process Proposals

Workflow improvements based on session patterns
Suggestions for recurring tasks that could be templated
Eat-the-frog interventions for chronically deferred tasks

Memory Proposals

Entities that should be added or updated
Context cache improvements
Stale information that should be cleaned up

Step 5: Generate Reflection Report

Write the report to Machine/reflection-{YYYY-MM-DD}.md:

---
date: YYYY-MM-DD
tags: [reflection, meta]
type: reflection
period: {start-date} to {end-date}
---

# Reflection: {start-date} to {end-date}

## Overview
- **Sessions:** {count} ({avg}/day)
- **Corrections:** {count}
- **Decisions:** {count}
- **Tasks completed:** {count}/{total} ({percent}%)

## Session Patterns
{analysis of session frequency, duration, topics}

## Recurring Themes
1. **{theme}** -- appeared in {N} sessions
   {description}

## Correction Analysis
- **Total corrections:** {N}
- **Repeated corrections:** {list of corrections given 2+ times}
- **Categories:** {breakdown}
- **Promoted to rules:** {N}/{total}

### Corrections Needing Rules
{corrections that keep recurring but have not been promoted to rules}

## User Working Patterns
{observations about the user's work style}

## Eat the Frog
{tasks that have been deferred repeatedly}

## Proposals

### Rule Changes
1. **Add rule:** "{rule}" -- based on {N} corrections about {topic}
2. **Modify rule:** "{rule}" -- current wording does not match practice
3. **Remove rule:** "{rule}" -- not applicable based on {N} sessions

### Process Improvements
1. {suggestion}

### Memory Cleanup
1. {suggestion}

## Meta
This reflection was generated by the reflect skill on {date}.
Previous reflection: {link to last reflection or "None found"}

Step 6: Present and Discuss

Present the key findings and proposals to the user. Ask:

"Should I apply any of these rule proposals to active-rules.md?"
"Any of these observations surprise you or seem off?"
"Want me to act on any of the process improvement suggestions?"

- This is primarily a read-and-analyze operation. Do not modify rules without user approval. - The reflection report file is always saved to `Machine/` (AI zone). - Be honest about patterns, even uncomfortable ones (like task avoidance). - Frame observations constructively -- identify the pattern and suggest a solution. - If there are not enough session logs for meaningful analysis, say so and suggest a minimum data threshold (at least 5 sessions). - Compare against previous reflection reports if they exist, to track improvement over time. - Never fabricate patterns -- if the data does not support a conclusion, do not make one. - All session logs within the time range are analyzed - Recurring correction patterns are identified - User working patterns are observed - Concrete rule improvement proposals are generated - Reflection report is saved to Machine/ - Proposals are presented for user review, not auto-applied - Comparison with previous reflections if available