show-me-your-work

Files (2)

• SKILL.md
• log.sh · scripts/

SKILL.md (first lines)

# show-me-your-work

사람이 자리를 비운 뒤 결과만 검토하는 작업은, 트랜스크립트 전체를 읽지 않아도 "무엇을 왜 결정했고 근거가 뭔지" 재구성할 수 있는 결정 트레일을 남긴다. 로그는 하나의 canonical 파일로 유지해 이후 에이전트도 찾을 수 있게 한다.

## 포맷

TSV 파일 하나, 결정당 한 행. TSV인 이유: GitHub이 정렬 가능한 표로 렌더링하고, `column -s$'\t' -t`와 스프레드시트로 바로 읽히며, 한 명령으로 append된다.

컬럼 6개:

| 컬럼 | 내용 |
|---|---|
| `ts` | ISO8601 UTC 타임스탬프 |
| `phase` | 단계 또는 워크스트림 이름 |
| `decision` | 무엇을 선택/수행했는지 한 줄 |
| `why` | 이유를 평문으로. 원칙명 태그가 아니라 실제 이유 |
| `evidence` | 증명하는 포인터: 커밋 SHA, PR 번호, `file:line`, 아티팩트 경로. 문단 금지 |
| `result` | 결과 상태: `tests green`, `reverted`, `INCONCLUSIVE`, `open` 등 |

예시 (illustration only, 실제 로그에 복사하지 않는다):

```
ts	phase	decision	why	evidence	result
2026-05-24T09:02:00Z	frame	작업 규모 먼저 계산, 약 100개 컴포넌트	장기 실행 전에 크기를 알아야 해서	commit 3a9f1c2	시작 전 확인할 blocker 5개 발견
2026-05-24T11:15:00Z	widget	위젯 스타일 이관, 외형 변화 없음	변경을 작게 유지하고 결과를 동일하게	commit 7c21e0a	pixel-diff 0, tests green
2026-05-24T12:30:00Z	widget	helper 작업물 폐기, 스크린샷이 빈 화면	요약 대신 실제 파일을 확인해서	worktree reset	reverted, 지시 강화 후 재시도
```

## 기록 규칙

- **결정 포인트와 체크포인트만 기록한다.** 갈림길 선택, 유닛 완료+검증 결과, 피벗/revert와 그 트리거, blocker 발견, 게이트 수정. 모든 액션을 다 적지 않는다. 루프 실행은 iteration당 한 행.
- **append-only.** 잘못된 판단은 새 행으로 대체(supersede)한다. 기존 행을 수정·삭제하지 않는다.
- 한 행에 안 들어가면 결정이 아직 명확하지 않은 것이다.
- 로그 문체도 팀원에게 말하듯 평문으로. AI 상투어·추상 은유 금지.
- evidence는 가능하면 커밋된 스크립트가 만든 산출물을 가리킨다. 리뷰어가 재실행할 수 있어야 한다.

행 추가는 helper를 사용한다 (탭/개행 제거, 헤더 자동 생성, 스프레드시트 formula injection 방지 처리):

```bash
bash <skill-dir>/scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>
```

## 위치와 커밋 여부

- 기본 위치: 작업 디렉터리의 `decisions.tsv`. 동시 다발 작업이면 `.audit/<task-slug>.tsv`.
- **기본은 커밋하지 않는다.** 로컬 로그만으로도 실행이 정직해진다.
- 커밋은 리뷰어가 트레일 없이는 결과를 신뢰할 수 없는 규모(대형 포팅, 수 주짜리 마이그레이션)일 때만 한다. 커밋된 TSV는 PR에서 표로 렌더링된다.

## 종료 전 감사

핸드백 전에 로그가 사실을 말했는지 확인한다:

1. 모든 행이 실제 수행한 액션에 대응하는가. 지어낸·희망사항 행은 삭제 대상(새 로그에서 제외).
2. 각 행의 evidence가 실제로 열리고 주장 내용을 보여주는가.
3. 작업 방향을 바꾼 피벗·폐기 접근이 로그에 없으면 공백이다. 추가한다.
4. 아무도 감사하지 않을 행은 자리를 차지할 자격이 없다. 뺀다.

작업이 행의 주장과 달라졌으면 **로그를 고치지 말고 행이 틀린 것이다.** 스토리가 아니라 로그를 사실에 맞춘다.

## 교차 리뷰와 Attention 섹션

핸드백 전에 작업을 수행하지 않은 별도 에이전트에게 트레일 검토를 맡긴다. 자기 검토는 대체재가 아니다.

```text
subagent({ command: "subagent run reviewer --isolated -- <logfile 경로>의 결정 로그를 읽고, 근거가 약한 결정·증거 없이 완료 주장된 검증·사후에 위험해 보이는 선택·사용자가 놓칠 공백을 찾아줘. 작업 재수행이 아니라 트레일 스캔이다." })
```

트레일을 만든 실행의 최종 응답은 **Attention 섹션**으로 끝낸다: 리뷰어가 플래그한 항목을 특정 행을 가리키며 나열한다. "No flags"도 유효한 값이다.

## 다른 스킬과의 연결

- `pickle`·`dynamic-workflow`의 장기 실행은 이 스킬의 포맷을 그대로 쓴다. 컬럼을 재정의하지 않는다.
- 검증 증거 기준은 `prove-it-works` 스킬을 따른다. 자기 보고는 evidence가 아니다.

From Jonghakseo/my-pi, MIT.

More from Jonghakseo/my-pi