---
description: "After-action review for AI-assisted development sessions"
short_desc: "Analyze thought process and workflow to extract process-level lessons"
category: "learning"
agent: "build"
---

# Reflect Command — After-Action Review for AI-Assisted Development

현재 세션의 **사고 과정과 워크플로우**를 분석하여 재발 방지 가능한 교훈을 추출합니다: $ARGUMENTS

> `/learn`은 코드 패턴을 추출하고, `/reflect`는 **프로세스와 의사결정**을 분석합니다.

## Procedure

### Phase 1: Timeline Reconstruction (타임라인 재구성)

대화 히스토리와 git log를 기반으로 작업 타임라인을 재구성합니다.

1. 이번 세션에서 수행한 **주요 작업 단계**를 시간순으로 나열합니다
2. 각 단계에서 소요된 **상대적 시간/노력**을 추정합니다 (tool call 수 기준)
3. **전환점** (접근법 변경, 오류 발견, 방향 수정)을 표시합니다
4. git log로 실제 커밋 히스토리와 대조합니다

```bash
# 세션 중 커밋 히스토리 확인
git log --oneline --since="$(date -v-8H +%Y-%m-%dT%H:%M:%S)" --format="%h %s (%ar)" 2>/dev/null || \
git log --oneline -20 --format="%h %s (%ar)"
```

**Output:**
```
## Timeline
| # | 단계 | Tool Calls (추정) | 전환점 |
|---|------|-------------------|--------|
| 1 | ... | ~N calls | - |
| 2 | ... | ~N calls | 방향 전환: ... |
```

### Phase 2: Bottleneck Analysis (병목 분석)

각 전환점과 지연 구간을 4가지 유형으로 분류합니다.

**A. LLM 상호작용 품질**
- 모호한 프롬프트로 인한 오해
- Hallucination 기반 제안을 추종
- 부정확한 정보로 시간 낭비
- 검증 없이 LLM 출력을 신뢰

**B. 문제 해결 전략**
- 비최적 접근법 선택 (더 나은 방법이 존재)
- 탐색 부족 (바로 구현에 돌입) 또는 과잉 (분석 마비)
- 무계획 구현 (plan 없이 코딩 시작)
- 실패한 접근법에 집착 (sunk cost)

**C. 지식 격차**
- 몰랐던 API, 도구, 라이브러리 기능
- 문서를 먼저 확인하지 않음
- 프레임워크/런타임 동작에 대한 잘못된 가정

**D. 도구 활용**
- 부적절한 도구 선택 (수동으로 할 수 있는 것을 자동화, 또는 그 반대)
- 기존 커맨드/스킬 미활용 (예: `/search-first`, `/tdd` 등)
- MCP 도구, LSP 등 사용 가능한 도구를 간과

**Output:**
```
## Bottleneck Analysis
| 유형 | 해당 단계 | 설명 | 영향도 (H/M/L) |
|------|-----------|------|----------------|
| B | #2 | plan 없이 바로 구현 시작 | H |
| C | #3 | API X의 Y 옵션을 몰랐음 | M |
```

### Phase 3: Root Cause (근본 원인)

Phase 2에서 영향도가 가장 높은 **1~3개 핵심 원인**을 도출합니다.

각 원인에 대해:
1. **왜 발생했는가?** (5 Whys 축약)
2. **얼마나 자주 반복될 수 있는가?** (일회성 vs 구조적)
3. **방지할 수 있었는가?** (어떤 시점에 어떤 행동으로)

**Output:**
```
## Root Causes
### 1. [원인 제목]
- **Why**: ...
- **재발 가능성**: 높음/중간/낮음
- **방지 가능 시점**: [단계 #N에서 X를 했다면]
```

### Phase 4: Lessons Learned (교훈 추출)

각 근본 원인에서 **"상황 → 행동 → 이유"** 규칙을 생성합니다.

규칙 형식:
```
WHEN [구체적 상황]
DO [구체적 행동]
BECAUSE [이번에 배운 이유]
```

추가로 **Counterfactual Path (이상적 경로)**를 작성합니다:
```
## Ideal Path (이상적 경로)
만약 처음부터 다시 한다면:
1. [최적 첫 단계]
2. [최적 두번째 단계]
...
예상 소요: 현재의 ~N% 수준
```

### Phase 5: Memory Persistence (메모리 저장)

추출된 교훈을 3-tier 저장소에 영속화합니다.

#### Tier 1: Feedback Memory (필수)

프로젝트 메모리 디렉토리에 feedback 타입으로 저장합니다.

```markdown
---
name: reflect-{topic}
description: {한줄 설명 — 향후 관련성 판단에 사용}
type: feedback
---

{Phase 4의 WHEN/DO/BECAUSE 규칙}

Source: /reflect session on {date}
```

- 파일: `~/.claude/projects/{project}/memory/reflect-{topic}.md`
- MEMORY.md 인덱스에 포인터를 추가합니다

#### Tier 2: Instinct (선택 — 구조적 교훈인 경우)

재발 가능성이 "높음"인 교훈을 instinct로 저장합니다.

```yaml
---
id: reflect-{id}
trigger: "{WHEN 조건}"
confidence: 0.6
domain: "workflow"
source: "reflect-session"
---

# {제목}

## Action
{DO 행동}

## Evidence
- {이번 세션에서의 구체적 증거}
- Reflected on {date}
```

- 파일: `~/.claude/homunculus/instincts/personal/reflect-{id}.md`
- 디렉토리가 없으면 생성합니다

#### Tier 3: mem-mesh (선택 — 크로스 프로젝트 교훈인 경우)

프로젝트에 국한되지 않는 범용 교훈은 mem-mesh MCP에도 저장합니다.

## Output Template

최종 리포트는 아래 구조로 출력합니다:

```
# Reflection Report — {날짜}

## Session Summary
{1~2문장 요약}

## Timeline
{Phase 1 테이블}

## Bottleneck Analysis
{Phase 2 테이블}

## Root Causes
{Phase 3 분석}

## Lessons Learned
{Phase 4 WHEN/DO/BECAUSE 규칙들}

## Ideal Path
{Phase 4 Counterfactual}

## Saved Items
- [x] Feedback memory: `reflect-{topic}.md`
- [ ] Instinct: `reflect-{id}.md` (해당시)
- [ ] mem-mesh: {키워드} (해당시)
```

---

**TIP**: 장시간 세션(100+ tool calls) 후에 실행하면 가장 효과적입니다. `/learn`과 함께 사용하여 코드 패턴과 프로세스 교훈을 모두 캡처하세요.
