/debrief — 사고 복기 리포트#

한마디로#

서비스에 문제(장애·심각한 버그)가 터진 뒤, "누구 탓"이 아니라 "왜 일어났고 어떻게 다시 안 생기게 할지"를 차분히 정리해 주는 사후 분석 도구입니다. 비행기 사고 조사관이 블랙박스를 열어 원인을 찾고 재발 방지책을 적는 것과 같아요.

누가·언제 쓰나요#

• 운영 서비스에 장애가 터진 직후 — 고객에게 영향이 간 실제 사고가 났을 때
• 심각한 버그가 검수 단계를 그냥 통과해 배포된 경우 — "왜 우리가 못 걸렀지?"를 따져봐야 할 때
• 팀 회고(post-mortem)가 필요할 때 — 사고를 교훈으로 남기고 싶을 때

권장: 사고 후 48시간 이내에 진행하는 것이 좋습니다 (기억이 생생할 때).

무엇을 해주나요#

사고 한 건을 처음부터 끝까지 분석해 docs/debriefs/YYYY-MM-DD-{주제}-debrief.md 라는 리포트 파일 한 개로 정리해 줍니다. 리포트 안에는:

• 요약과 타임라인 — 언제 터졌고, 언제 발견했고, 언제 해결했는지 (총 복구 시간 포함)
• 근본 원인 — "왜?"를 다섯 번 파고들어(5 Whys) 진짜 원인까지 추적
• 영향 범위 — 어떤 사용자·서비스·데이터가 영향을 받았는지
• 검수 구멍 분석 — 우리 품질 게이트(스펙·분석·구현·코드 리뷰) 중 어디서 이걸 놓쳤는지
• 개선 액션 — 재발 방지·조기 탐지·대응 개선 항목 (담당자·기한까지)

추가로, 게이트 개선안이 나오면 관련 파일에 메모(TODO)를 남기고 학습 정리(/session:wrap)와도 연동됩니다.

어떻게 쓰나요#

# 인시던트 설명으로 시작
/debrief  " 로그인 서비스 장애 — 소셜 로그인 토큰 만료 미처리 " 

 # 이슈 번호 기반
/debrief --issue 456

# 특정 커밋/PR 기반
/debrief --pr 789

위 셋 중 최소 하나는 반드시 넣어야 합니다(사고 설명, 이슈 번호, PR 번호). 분석 깊이를 조절하려면 --depth quick(빠르게) / standard(기본) / deep(깊게)을, 저장 위치를 바꾸려면 --output 경로를 덧붙이세요.

안에서 무슨 일이 벌어지나요#

크게 다섯 단계로 사고를 파헤치고 마지막에 리포트로 묶습니다.

1. 정보 수집 — 이슈·PR·코드 변경 이력을 모아 사고의 타임라인(발생→감지→대응→해결)과 총 복구 시간을 정리합니다.
2. 근본 원인 분석 — "왜?"를 반복해 진짜 원인까지 파고들고, 영향받은 사용자·코드·데이터 범위를 짚습니다.
3. 검수 구멍 분석 — 스펙·분석·구현·코드 리뷰 각 단계에서 "여기서 막았어야 했는데 왜 못 막았나"를 따집니다.
4. 개선 액션 도출 — 재발 방지, 조기 탐지, 대응 개선으로 나눠 구체적인 할 일을 우선순위와 함께 정리합니다.
5. 문서화·학습 — 결과를 리포트 파일로 저장하고, 팀 학습 정리와 게이트 개선으로 연결합니다.

# 인시던트 설명으로 시작
/debrief  " 로그인 서비스 장애 — 소셜 로그인 토큰 만료 미처리 " 

 # 이슈 번호 기반
/debrief --issue 456

# 특정 커밋/PR 기반
/debrief --pr 789

# Debrief: {incident_title}

**Date**: YYYY-MM-DD
**Severity**: Critical | Major | Minor
**MTTR**: Xh Ym

## Summary
{1-2 paragraph incident summary}

## Timeline
| Time | Event |
|------|-------|
| HH:MM | {event} |

## Impact
- **Users affected**: {scope}
- **Services affected**: {list}
- **Data impact**: {description}

## Root Cause (5 Whys)
1. **Why**: {direct cause}
2. **Why**: {underlying cause}
3. **Why**: {systemic cause}
...

## Gate Gap Analysis
| Gate | Should Have Caught? | Why Missed |
|------|---------------------|------------|
| Specification | Yes/No | {reason} |
| Analysis | Yes/No | {reason} |
| Implementation | Yes/No | {reason} |
| Code Review | Yes/No | {reason} |

## Contributing Factors
- {factor 1}
- {factor 2}

## Action Items

### Prevent (재발 방지)
- [ ] {action} — Owner: {who} — Due: {when}

### Detect (조기 탐지)
- [ ] {action} — Owner: {who} — Due: {when}

### Respond (대응 개선)
- [ ] {action} — Owner: {who} — Due: {when}

## Lessons Learned
{blameless insights}

## References
- Issue: #{number}
- PR: #{number}
- Related commits: {hashes}