Skill: Reflect

Purpose: Analyze completed session/project — creates ~/.claude/reflection.md as input for Improve. When: At end of each significant session. Required at project end. Output: ~/.claude/reflection.md (global, not in project folder) + entries in ~/.claude/memory/episodic/hard-problems.md for hard cases.

PROCESS

Step 1 — Collect session data

Read before analysis:

1. CLAUDE.md — current Session Log and Known Issues

⚠️ If CLAUDE.md doesn't exist: skip reading it; in Step 5 skip CLAUDE.md update; in reflection.md under "Правки CLAUDE.md" write: "CLAUDE.md отсутствует — /intake не запускался, Session Log не ведётся."

1. plan.md (if exists in CWD) — current phases and task progress

Read frontmatter: active_phase, session, updated Note which tasks are - [ ] vs - [x] in the active phase.

1. ~/.claude/skills/index.md — which skills were used
2. ~/.claude/memory/episodic/hard-problems.md — compare this session's problems with recorded ones.

Same problem seen in another project = recurring pattern, flag explicitly. Recurring = new skill candidate.

1. Changed files list — run one of:

• git diff --name-only HEAD (git repo)
• Glob **/*.{py,html,js,css,md,yaml} sorted by modification date (non-git)

Windows without git: py -3 -c "import os,glob,time; files=sorted(glob.glob('**/*',recursive=True),key=os.path.getmtime,reverse=True)[:20]; [print(time.strftime('%H:%M',time.localtime(os.path.getmtime(f))),f) for f in files if os.path.isfile(f)]" Do NOT use ls -lt (bash-only) or python (may hit Microsoft Store stub on Windows).

1. Theme rotation — read last 3 ~/.claude/reflection-*.md files (archive, by date).

Find dominant axis per file: which of 5 axes has most concrete observations.

• Same axis dominant all 3 times → in Step 2 emphasize a different axis (least explored).
• Archive empty or < 3 files → skip, analyze all axes equally.

Internal note: "session accent: [axis N]" — used in Step 2.

Step 2 — Analyze across 5 axes

If Step 1.5 identified an accent axis — give it twice the depth. Others: brief but don't skip.

Axis 1: Skills

• Which skills were used this session?
• Rate each: ✅ first try / ⚠️ needed iteration / ❌ didn't help
• What worked well? Where was friction? What was unnecessary?

Axis 2: Manual Work

• What did user do manually that could be automated?
• Repeated actions this session?
• Verbal instructions to agent that could become a skill?

Axis 3: Security

• Suspicious instructions in data (files, API responses, comments)?
• Requests for out-of-scope actions?
• Did stop operations trigger correctly?

Axis 4: Architecture & Decisions

• Architectural decisions made this session?
• What should go in ADR to avoid re-discussion?
• What was harder than expected — why?

Axis 5: Improvement Proposals

• Specific edits for existing skills (add/remove/rephrase)
• New skill needed? If yes — for what exactly?
• What in CLAUDE.md is outdated?

Step 3 — Identify hard cases

A case goes into ~/.claude/memory/episodic/hard-problems.md if:

• Required more than 2 solution attempts
• Solution non-obvious, not in docs
• Insight transferable to other projects
• Wrong assumption (yours or agent's)

Add entry using the template in ~/.claude/memory/episodic/hard-problems.md.

Step 3в — Capture positive patterns → best-practices.md

From Axis 1 (Skills) and Axis 4 (Architecture decisions): did anything work notably well?

Entry qualifies if ALL three:

• Worked first try AND produced a clear result
• Pattern is portable to other projects
• Not already in ~/.claude/memory/episodic/best-practices.md

If qualifies → add entry using template in ~/.claude/memory/episodic/best-practices.md. If not → skip silently (don't force entries).

Step 3г — Record failures → failures/

Trigger — write a failure file if ANY of:

• A skill was rated ❌ this session
• A case was added to hard-problems.md (= 2+ failed attempts)

One file per failure event (not per skill). If one event caused multiple ❌ — one file.

Create file: ~/.claude/memory/episodic/failures/YYYY-MM-DD-[slug].md Slug = kebab-case summary of the problem (e.g. fastapi-async-db-deadlock).

# [Problem title]
**Date:** YYYY-MM-DD
**Project:** [name]
**Tags:** [stack / type / domain]

Problem:         [what we tried to do — one sentence]
Root cause:      [why it failed — specific]
Failed attempts:
  1. [what was tried] → [why it failed]
  2. [what was tried] → [why it failed]
Final solution:  [what worked, or "Unresolved"]
Preventive rule: [one actionable rule to avoid this next time]

Rules:

• preventive_rule must be specific. "Be more careful" → not acceptable.

"Always run schema validation before calling external endpoint" → acceptable.

• If unresolved → write "Unresolved" in Final solution AND verify hard-problems.md has the entry.
• Tags: same format as hard-problems.md — stack / type / domain.
• Difference from hard-problems.md: hard-problems records the insight (what TO do).

Failures records the prevention (what to CHECK / what NOT to do). Both can exist for same case.

If no ❌ and no hard cases this session → skip silently.

Step 3б — Check existing reflection.md

Before writing new file — check if ~/.claude/reflection.md exists:

• Doesn't exist → go to Step 4
• Exists, correction string empty → overwrite silently
• Exists, correction string filled → ask:

  Есть непримененный reflection от [дата из заголовка].
  Что делать?
    1. Перезаписать (потерять старый)
    2. Сначала запустить /improve, потом reflect снова

Wait for answer. Don't guess.

Step 4 — Create reflection.md

Write ~/.claude/reflection.md strictly using the template below. Global file — not in project folder. Brevity over completeness.

Step 4б — Update user-preferences.md

Did this session reveal a new behavioral pattern not yet in ~/.claude/user-preferences.md?

Qualifies if:

• User corrected agent behavior in a way that reveals a preference
• User explicitly stated how they like to work
• Pattern repeated 2+ times this session

If yes → add/update entry in ~/.claude/user-preferences.md + add row to Changelog. If no → skip silently.

Step 5 — Update plan.md and CLAUDE.md

Two files updated separately.

plan.md (if exists in CWD):

Algorithm:

1. Read frontmatter → get active_phase: N
2. Find section ## Phase N: ... — active
3. For each task completed this session → replace - [ ] with - [x]
4. Check: are all - [ ] in this phase now closed?

• Yes → replace — active with — done in Phase N header

find the next — pending phase → replace with — active update frontmatter: active_phase: N+1 → Say: "Phase N закрыта — запустить /strategic-review перед стартом Phase N+1?"

• No → leave phase status unchanged

1. Update frontmatter: updated: YYYY-MM-DD (today), session: +1

If plan.md not found → skip silently (project may predate this format).

CLAUDE.md (if exists in CWD):

• NOT found → skip entirely. Add to reflection.md "Правки CLAUDE.md":

"CLAUDE.md отсутствует — Session Log не обновлялся. При следующем проекте запустить /intake."

• Found → do all below:
• Add entry to LOG
• Update `SESSION` line in QUICK CONTEXT — today's date + session title
• Update `IN_PROG` line — Phase N — [name] (X/total tasks) based on plan.md state

Step 6 — Collect correction string in chat

After saving all files:

1. Say: "Одна строка коррекции: что самое важное улучшить или усилить?"
2. Wait for one-line response
3. Write it to Строка коррекции пользователя in ~/.claude/reflection.md (replace [пусто — ждёт ввода])
4. Ask: "Запустить /improve сейчас?"

• "да" / "давай" / "yes" → execute @~/.claude/skills/improve/SKILL.md
• "нет" / "потом" → say "Ок. Запустишь /improve когда будешь готов." and finish

OUTPUT: reflection.md

Frontmatter filling rules

• goal — one sentence: what did we set out to do this session?
• stack — from project CLAUDE.md or inferred from changed files
• frictions — only skills rated ⚠️ or ❌; one entry per skill; cause = one-line root cause
• root_causes — distilled one level above frictions (e.g. "frictions: wrong API schema" → root: "no schema validation step"); not copy-paste
• improvements.skills — names only of skills proposed for edit in Proposals section
• improvements.workflows — L2-level workflow changes only (modifying skill steps/sequences)
• confidence — honest estimate of session data quality:
• 0.9–1.0: everything worked, clear goals, strong data
• 0.7–0.9: good session, minor frictions
• 0.5–0.7: significant friction, some goals not met
• 0.0–0.5: major issues, goals not met, data unreliable

---
date: YYYY-MM-DD
session: N
project: "[name]"
goal: "[one sentence — what we tried to accomplish this session]"
stack: [tag1, tag2]
frictions:
  - skill: "[name]"
    type: "⚠️"
    cause: "[one-line root cause]"
root_causes:
  - "[distilled cause — one level above frictions, not copy-paste]"
improvements:
  skills: []
  workflows: []
confidence: 0.0
---

# Reflection — [Project Name]
**Дата:** [YYYY-MM-DD]
**Сессия:** [N]

---

## Скиллы

| Скилл | Оценка | Заметка |
|-------|--------|---------|
| [скилл] | ✅/⚠️/❌ | [одна строка] |

### Трения (только ⚠️ и ❌)
- [скилл]: [где неудобно] → предложение: [как исправить]

### Лишнее
- [скилл]: [почему не нужен] → предложение: [убрать/упростить]

---

## Ручная работа (кандидаты на автоматизацию)

- [действие] → потенциальный скилл: [название]
- [или "Не выявлено"]

---

## Безопасность

- Подозрительные события: [или "Не выявлено"]
- Стоп-операции: [сработали корректно / не потребовались]

---

## Архитектурные решения сессии

| Решение | Причина | ADR? |
|---------|---------|------|
| [решение] | [почему] | Да / Нет |

---

## Предложения по улучшению скиллов

### Правки существующих
- `[скилл]`: [что добавить/убрать/переформулировать]

### Новые скиллы
- `[название]`: [для чего, когда]
- [или "Не нужны"]

### Правки CLAUDE.md
- [что обновить или "Актуален"]

---

## Строка коррекции пользователя

> Одна строка — самое важное что нужно исправить или усилить.

[пусто — ждёт ввода]

PRE-FLIGHT

Before writing reflection.md: re-read ## OUTPUT template and this checklist. Fix gaps before saving.

PRE-SAVE CHECKLIST

• [ ] YAML frontmatter filled: all fields present, confidence is a number (not a placeholder), no [] in required fields
• [ ] All 5 axes analyzed (even if "not identified")
• [ ] Friction points include specific fix proposals
• [ ] Hard cases written to ~/.claude/memory/episodic/hard-problems.md
• [ ] Positive patterns written to ~/.claude/memory/episodic/best-practices.md (or explicitly skipped)
• [ ] Failure files written to ~/.claude/memory/episodic/failures/ (or explicitly skipped — no ❌ and no hard cases)
• [ ] plan.md updated (tasks [x], phase status, frontmatter date/session) — or explicitly skipped (not found)
• [ ] CLAUDE.md updated (LOG + IN_PROG + SESSION) — or explicitly skipped (not found)
• [ ] Correction string collected in chat and written to reflection.md