document-haness/.agents/skills/deriving-tech-log-root-tree/references/candidate-disposition.md

후보의 처분 — 무엇을 독립 기록으로 만들고 무엇을 만들지 않는가

분석에서 나온 항목마다 처분을 하나 적는다. 처분은 tech-log-tree.json 의 candidates 에 남고, PROMOTE 만 같은 파일의 topics 로 올라간다.

목표 함수

빠짐없이 방출하는 것이 아니라 고르는 것이다. 분석 누락을 검증할 때는 recall 100% 가 맞다. 공개할 글을 정할 때는 아니다. 「분석에서 보존할 가치」와 「독립된 글로 읽을 가치」는 다른 물음이고, 둘을 한 축으로 재면 분석 부산물이 전부 글이 된다.

제외가 0 건인 분해는 선별하지 않은 분해다.

여섯 가지 처분

처분	뜻	어디로
PROMOTE	독립 Tech Log 로 쓴다	tech-log-tree.json 의 노드가 된다
MERGE_INTO	다른 기록의 한 절·표 행으로 흡수한다	흡수한 기록의 slug 를 target 에 적는다
KEEP_IN_SSOT	중요한 분석 결과지만 독립 기록은 아니다	final/document.md 와 analysis/** 에 남는다
NEEDS_EVIDENCE	주장에 아직 검증이 없다	측정한 뒤에 다시 판정한다
NEEDS_DECISION	방향이 그럴듯하지만 프로젝트가 정하지 않았다	정해진 뒤에 다시 판정한다
BLOCKED	원본이 불완전하거나 서로 어긋난다	원본을 고친 뒤에 다시 판정한다

KEEP_IN_SSOT 은 실패가 아니다. 정보를 버리지 않으면서 글로 과분류하지 않는 상태다. 분석 범위, 호출자 수, 미배선 사실, 커버리지 원장, 재현에 쓴 레인 같은 것이 여기 온다 — 분석에는 반드시 남아야 하고 공개 기록으로는 읽을 사람이 없다.

REJECTED 는 쓰지 않는다. 무엇을 버렸는지가 아니라 무엇이 어디에 남았는지를 적는다.

독립성 검사

처분을 정하는 물음은 하나다.

이 기록을 없애고 관련 Case 나 Concept 의 한 절로 넣어도 이해·결정·재사용성이 그대로라면 독립 기록으로 만들지 않는다.

그대로면 MERGE_INTO. 넣을 자리조차 없으면 KEEP_IN_SSOT.

종류마다 독립 기록이 되는 조건

종류	독립 기록이 되는 조건	되지 않는 것
Case	하나의 문제 · 관측·재현 · 진단 · 결론이 닫힌다	단순 정적 카운트, 문구 수정, 같은 원인의 부분 증상
Concept	내부 구조나 동작을 처음부터 설명해야 Case 를 이해할 수 있다. 기준 버전이 있다	분석 범위, 호출자 수, 미배선 사실, 한두 문장으로 Case 안에 설명되는 것
Reference	다음 프로젝트에도 적용할 규칙이며 적용 조건과 예외가 있다	Case 결론을 선언문으로 바꾼 것
Question	답이 아직 없고, 답에 따라 설계가 달라지며, 다음 검증과 종료 기준이 있다	실행하지 않은 테스트 목록, 막연한 "다른 방법은?"
Decision	대안 중 프로젝트가 실제 방향을 정했고 근거와 감수한 비용이 있다	기술이 존재한다는 사실, 권장사항, 아직 정하지 않은 방향
Setup	남이 자기 기계에서 실행할 명령과 구성 값이 있고 프로젝트가 정해져 있다	글쓴이만 다시 돌릴 재현 순서(그 Case 의 재현 조건이다), 명령 없는 구성 설명

Case 를 언제 합치나

같은 질문에서 나와 같은 결론에 닿는 관측이면 한 Case 다. 인과 단위·의미 단위·검증 단위가 셋 다 같아야 합친다는 기준은 너무 좁다 — 그 기준에서는 같은 결함의 다섯 증상이 다섯 편이 된다.

관측이 여럿이면 한 Case 안에 표나 하위 절로 넣는다. 표의 행 하나가 될 것을 기록 하나로 만들지 않는다.

Concept 을 언제 만드나

Case·Decision·Question 을 먼저 고른 뒤 거꾸로 뽑는다. "이 Case 를 읽는 사람이 미리 알아야 하는 구조가 있는가"를 묻고, 있으면 그때 Concept 을 만든다. 메커니즘처럼 보이는 절을 훑어 채우면 어느 Case 도 필요로 하지 않는 개념이 쌓인다.

Concept 에는 basis-version 이 있어야 한다. 무엇을 보고 쓴 글인지 없으면 언제 낡았는지 읽는 사람이 알 방법이 없다.

제목이 이런 꼴이면 Concept 이 아니다.

호출자가 없다                      → 부재는 Case 의 관측이다
프로덕션에서 실행되지 않는다        → 같은 이유
구현 클래스 51개를 전부 읽었다      → 분석 범위. KEEP_IN_SSOT
보류한 항목과 보류한 이유           → 분석 진행 기록. KEEP_IN_SSOT
(8.4) 문서/구현 드리프트 — …       → 분석 문서의 절 제목을 그대로 옮긴 것
Confirmed — …                      → 같은 것. finding 등급이 제목에 남아 있다

대장에 적는 것

{
  "id": "A05-F012",
  "kindCandidate": "CASE",
  "sourceRefs": ["final/document.md#8-3"],
  "summary": "…",
  "disposition": "MERGE_INTO",
  "dispositionReview": "CONFIRMED",
  "target": "case:two-owners-popped-the-evidence-frame",
  "reason": "같은 결함의 두 번째 증상이다. 그 Case 의 재현 절에 행으로 들어간다"
}

dispositionReview 는 CONFIRMED 와 PENDING 둘이다. 사람이 위 물음으로 판정했으면 CONFIRMED, recall 로 자동 방출된 것이면 PENDING 이다. PENDING 이 남아 있는 프로젝트는 글감 선별이 끝나지 않은 것이다.

python3 scripts/verify-tech-log-tree.py <프로젝트> 가 남은 건수를 error 로 센다. 경고가 아니라 error 인 이유는 하나다 — 경고로 두면 재판정하지 않은 트리로 글을 쓰기 시작할 수 있다.