failure-writer

name	failure-writer
description	머지된 코드가 이후에 잘못된 설계·구현으로 판명되어 되돌리거나 다시 고칠 때 자동으로 docs/failures/에 실패 기록을 남긴다. 버그 수정·롤백 대화에서, 지금 고치는 코드가 과거의 의도적인 결정(특히 기존 ADR)을 뒤집는 것인지 git 히스토리로 확인하고 사용. 결정과 실패 판명이 서로 다른 세션에서 벌어지는 경우가 대부분이므로, 대화 기억이 아니라 git 로그·docs/adr를 근거로 판단한다.

failure-writer — 실패 판명 시점 자동 기록 (크로스 세션)

adr-writer가 "결정이 내려지는 순간"을 대화 안에서 잡는다면, 이 Skill은 "그 결정이 틀렸다고 판명되는 순간"을 잡는다. 이 판명은 결정이 내려진 세션과 다른, 훨씬 나중의 세션에서 벌어지는 게 보통이다. 그래서 이 Skill은 현재 대화 기억이 아니라 git 로그와 docs/adr/를 증거로 삼는다 — 어느 세션에서 트리거되든 같은 결론에 도달할 수 있도록.

입력 (트리거 조건 — 스킬 실행 시 판단 기준)

명시적 파라미터 없이, 아래 신호가 나타나는 대화·작업에서 자동으로 판단한다. 강도·가치 순으로 3단계이며, 마지막 안티-트리거를 반드시 함께 확인한다.

1. 되돌림·폐기 신호 — 가장 강함

• 채택했던 결정이 뒤집힘 — 기존 ADR이 Superseded/Deprecated로 바뀌는 순간. 이때 대체 ADR과는 별개로 "왜 이전 게 실패했는지"를 남길 가치가 있다.
• git revert, 커밋 원복, "원복하자 / 되돌리자 / 이전으로 돌아가자"
• 여러 턴에 걸쳐 시도한 접근을 결국 버림 ("이 방향 접자", "이건 안 되겠다")

2. 막다른 길(dead-end) 신호

• "안 되네 / 이 방법 안 통함 / 막혔다 / 삽질했다"
• 라이브러리·API·설정을 시도했으나 벽에 부딪혀 다른 길로 우회
• 같은 툴 호출·빌드·테스트가 반복 실패하다 원인을 뒤늦게 파악

3. 잘못된 전제 신호 — 가장 가치 큼

• 버그·실패의 근본 원인이 틀린 가정/멘탈 모델이었을 때 (단순 오타가 아니라)
• "아 이게 원인이었네", "그렇게 동작하는 게 아니었구나" — 코드만 봐선 안 드러나는 함정
• 직렬화 opt-in 경고 ADR처럼 "정상인데 실패처럼 보이는" false-positive를 규명한 경우

4. 안티-트리거 — 반드시 제외 (노이즈 방지)

실패 기록은 ADR보다 노이즈에 더 취약하다(개발 중 실패는 수시로 나므로). 아래는 남기지 않는다.

• 사소한 오타·문법 오류, 일시적 오류(네트워크 flake, 캐시)
• 그 실패가 결국의 커밋/수정으로 이미 다 설명되는 경우 — git이 SSOT
• 일회성 로컬 환경 문제
• 원인이 자명해서 "왜"를 남길 게 없는 실패

작업 순서

1. 증거 수집 (대화 기억에 의존하지 않는다)

   git log --oneline -- <이번에 고치는 파일 경로>
   

   지금 고치는 파일·모듈의 히스토리를 살펴 이 코드가 언제, 어떤 의도로 만들어졌는지 확인한다. 커밋 메시지에서 관련 이슈 번호·ADR 언급을 찾는다.
2. docs/adr/README.md 인덱스를 Read해, 지금 되돌리는 코드와 연관된 Accepted ADR이 있는지 확인한다. 있으면 그 ADR 파일을 근거로 쓴다. 없으면 "문서화되지 않은 결정"으로 진행한다 — ADR이 없었다는 사실 자체도 실패 기록에 남긴다.
3. failure-format.md를 먼저 Read해 파일명·상태 값·템플릿 형식을 확인한다. 이 Skill 안에서 형식을 재정의하지 않는다.
4. failure-format.md의 템플릿에 맞춰 아래 내용을 채워 새 실패 기록 파일을 작성한다.
   • 상태: 대체 방법까지 적용됐으면 Resolved, 원인만 기록된 상태면 Open
   • 발생일자: 문제를 발견/수정한 날짜
   • 작성자: 대화에서 알 수 없으므로 git config user.name 값으로 채운다
   • 관련 ADR: 2번에서 찾은 ADR 링크, 없으면 "없음 — 문서화되지 않은 결정"
   • 관련 커밋/PR: 1번에서 확인한 원본 커밋, 이번 수정 커밋/PR
   • 무엇을 시도했는가: 원래 결정/구현
   • 무엇이 잘못됐는가: 실제로 어떤 문제가 발생했는가
   • 어떻게 발견했는가: 이번 대화·이슈·버그 리포트 등
   • 무엇으로 대체했는가: 지금 적용하는 수정
5. 관련 ADR이 있었다면 adr-format.md의 상태 규칙에 따라 해당 ADR의 상태를 갱신한다(docs/adr/README.md 인덱스의 상태 셀 포함, 새 ADR이 필요하면 adr-writer를 이어서 사용).
6. docs/failures/README.md 인덱스 표에 새 줄을 추가한다.

작성 규칙

• 트리거 여부는 "의도적인 과거 결정을 뒤집는가"가 기준이다 — 세부 판단은 입력 섹션의 안티-트리거를 따른다.
• git 로그에서 증거를 못 찾겠으면 억지로 추측하지 않고, 사용자에게 "이 코드가 왜 이렇게 짜여 있었는지 아는 게 있나요?"로 확인한다.
• 실패 기록과 새 ADR은 짝을 이루는 경우가 많다: 실패 원인을 docs/failures/에, 새로운 방향을 docs/adr/에 남기고 서로 링크한다.

산출물 핸드오프

• 산출물: 새 실패 기록 파일 + docs/failures/README.md 인덱스 갱신, 필요 시 관련 ADR의 상태 갱신.
• 생성/수정한 파일을 사용자에게 요약해 알린다.
• 커밋은 이 Skill의 범위가 아니다 — /done에서 다른 변경사항과 함께 처리한다.