voidlight00/postmortem-claude-skill/postmortem

Postmortem

정체성

삽질 1건을 incident-level 노트 1개로 즉시 기록한다. 세션 전체나 phase 전체를 요약하지 않는다.

발동 2경로

수동 발동

/postmortem [주제]로 발동한다. 인자가 없으면 직전 삽질을 대화 컨텍스트에서 자동 식별한다. 인자가 있으면 해당 주제의 삽질을 지정한다.

자동 제안

실패한 시도가 2회 이상 발생한 뒤 문제가 해결됐거나, 해결됐어도 근본 원인이 자명하지 않은 경우 자동으로 작성한다. 자동 작성 후 사용자에게 경로만 보고하며 승인을 기다리지 않는다. 단순 오타 수정이나 1회 실패처럼 임계값에 미달하는 일은 기록하지 않는다.

실행 절차

1. 산출 경로를 결정한다. git rev-parse --show-toplevel이 성공하면 <root>/docs/postmortems/를 사용하고, 실패하면 ./docs/postmortems/를 사용한다. 디렉토리가 없으면 생성한다.
2. ID를 발급한다. PM-$(date +%Y%m%d)-NN 형식을 사용한다. 같은 날짜의 기존 PM-YYYYMMDD-*.md 파일 수를 세고 NN = count+1로 계산한 뒤 두 자리로 zero-pad한다.
3. 설치된 스킬 디렉터리의 TEMPLATE.md를 읽고 8개 섹션을 모두 채운다. 플러그인 설치 시에는 현재 SKILL.md와 같은 디렉터리의 템플릿을 사용하고, 수동 사용자 스킬 설치의 기본 경로는 ~/.claude/skills/postmortem/TEMPLATE.md다. §2와 §3은 대화 컨텍스트에서 재구성하며, 시도 순서와 실패 관찰을 시간순 그대로 기록하고 미화하지 않는다. §6의 증거는 실제 명령 출력 또는 exit code와 테스트 결과를 코드펜스에 넣는다.
4. 시크릿을 스캔한다. 본문에 sk-, ghp_, AKIA, Bearer 패턴이 들어가면 [REDACTED]로 치환한 뒤 저장한다.
5. 게이트를 실행한다. 설치된 스킬 디렉터리의 gates/verify_postmortem.sh <파일>을 실행한다. 수동 사용자 스킬 설치의 기본 경로는 bash ~/.claude/skills/postmortem/gates/verify_postmortem.sh <파일>이다. exit가 0이 아니면 FAIL[R#] 항목을 수정한 뒤 재실행한다. exit 0 전에는 완료를 보고하지 않는다. 자가보고를 증거로 인정하지 않는다.
6. FAILURE_LOG.md를 연동한다. 프로젝트 루트에 파일이 존재하면 | PM-id | 제목 | 근본원인 1줄 | 재발방지 경로 | 한 줄을 append한다. 파일이 없으면 생성하지 않고 보고에 FAILURE_LOG 없음 — skip을 명시한다.
7. docs/postmortems/README.md 인덱스를 재생성한다. 모든 PM-*.md의 frontmatter와 첫 # 헤딩에서 | ID | 날짜 | 제목 | severity | status | 표를 최신순으로 결정론 생성한다. GitHub에서 폴더를 열었을 때 목차 역할을 한다.
8. git 문서화를 진행한다 (1단계에서 git 리포로 인식된 경우에만). 이번 실행이 만들거나 바꾼 파일만 — 새 PM-*.md, README.md, append한 FAILURE_LOG.md — 명시 경로로 git add하고, git commit -m "docs: postmortem <PM-id> — <제목>" -m "<근본 원인 1줄>" -- <경로들> 형식의 pathspec 커밋을 만든다. origin remote가 설정돼 있으면 push한다. 단, push 전 branch의 unpushed 커밋을 확인해 이번 실행의 커밋 외 다른 unpushed 커밋이 섞여 있으면 push를 건너뛰고 그 사실만 보고한다 — 관련 없는 변경이 함께 나가는 것을 막는다. push가 실패하면 자동 해결을 시도하지 않고 경고만 보고하며 커밋은 로컬에 유지한다. git 리포가 아니면 이 단계 전체를 건너뛴다.
9. 노트 경로, 게이트 PASS 출력, FAILURE_LOG.md append 여부, 커밋 해시와 push 결과를 4줄 이내로 보고한다.

안전 규칙

• 기존 postmortem 노트 본문은 수정하지 않는다. 기록은 append-only이며 잘못 쓴 노트는 새 노트로 supersede한다.
• 시크릿 원문은 기록하지 않는다.
• git 문서화는 이번 실행이 만든 파일(PM-*.md, docs/postmortems/README.md, FAILURE_LOG.md)만 다룬다. git add -A 금지, pathspec 커밋 강제 — 사용자가 스테이징해 둔 다른 변경을 절대 함께 커밋하지 않는다 (2026-07-17 throwaway 리포 실측 검증).
• git add가 ignore 규칙에 거부되면: catch-all exclude(*)로 전체를 막고 화이트리스트하는 리포에서만 해당 파일 한정 git add -f를 쓴다. docs/ 경로가 명시적으로 ignore된 리포에서는 사용자 의도로 보고 커밋을 건너뛰고 보고만 한다.
• push는 origin이 있을 때만, --force 없이 수행한다. push 실패·충돌은 자동 해결하지 않고 보고만 한다. postmortem 자동 커밋·push는 사용자 상시 승인 완료(2026-07-17) — 단 시크릿 백스톱은 R10 게이트 + qa-publish-gate 훅 이중으로 유지한다.

게이트 판정표