incidents-to-rule

Skill: incidents-to-rule

목적

반복되는 실수와 실패 패턴을 분석해 AGENTS.md에 추가할 규칙 후보를 생성한다.

입력

• trail/incidents/{target}.md 또는 trail/incidents/ 전체

운영 archive (plugins/rein-core/policy/cleanup-archive-ignore.txt 의 4 path) 는 분석 대상에서 제외한다.

입력 포맷

신규 자동 생성 포맷 (auto-*.md)

---
status: "pending"
pattern_hash: "3f4a8b2c9d1e5f6a"
hook: "pre-bash-safety-guard"
reason: "파이프 쉘 실행"
count: "5"
first_seen: "2026-04-10T14:23:10"
last_seen_at: "2026-04-15T09:17:45"
agent_eligible: unknown      # true | false | unknown — 분류 후 기록 (선택)
root_cause: unknown           # bug | missing_rule | missing_agent | tooling | user_error | unknown (선택)
---

# Incident: pre-bash-safety-guard / 파이프 쉘 실행

## 예시 (최근 최대 5건)
...

처리 규칙:

• auto-*.md 파일은 frontmatter status: pending 인 것만 처리
• status: processed 또는 status: declined 는 건너뜀
• 처리 완료 후 해당 파일의 frontmatter status 를 processed 또는 declined 로 갱신
• 분석 중에 분류 필드 (agent_eligible, root_cause) 를 함께 기록하면 /incidents-to-agent 가 이를 기준으로 에이전트 승격 후보에서 제외할 수 있다 (아래 "분류 가이드" 참조)

분류 가이드 (agent_eligible / root_cause)

incident 를 분석하면서 아래 기준으로 분류한다. 확신이 없으면 unknown 유지 (보수적 기본값).

상황	agent_eligible	root_cause
hook 소스의 regex/pattern false-positive — 코드 수정으로 해결	false	bug
특정 workflow 에서 반복되는 순서 위반 — AGENTS.md 규칙 추가로 해결	true	missing_rule
여러 스킬 조합으로 해결 가능한 패턴 — 에이전트 후보	true	missing_agent
외부 도구/MCP 설정 부재	false	tooling
사용자가 일회성으로 실수한 패턴 (반복 아님)	false	user_error
분류 불명	unknown	unknown

• agent_eligible: false 로 분류된 건은 /incidents-to-agent 의 Step 1 필터에서 제외된다 — 사람이 hook 소스 수정이나 다른 대응으로 해결해야 할 대상
• 기존 incident 파일 (필드 없음) 은 unknown 으로 해석되어 기존 동작 (count >= 3 이면 후보 생성) 을 유지한다 — backfill 불필요

분류 기록 명령 (status 갱신과 동시 적용 가능):

Helper path 는 plugin install 환경에서는 plugin root 의 scripts/, 메인테이너 dogfood 에서는 repo scripts/ 가 fallback 으로 사용된다. 본문 예시는 아래 resolver block 으로 $REIN_PLUGIN_ROOT 를 먼저 정해두고 그 뒤 "$REIN_PLUGIN_ROOT/scripts/..." 형태로 호출한다 (Claude Bash 도구 환경에서는 plugin root env 가 unset 일 수 있으므로 매 호출 직전에 다시 해소). 메인테이너 환경에서는 hook 호출 시 RES-1 resolver 가 자동 fallback 하고, 수동 Bash 호출이라면 scripts/rein-mark-incident-processed.py 로 그대로 가능.

# plugin root 해소 (Claude Bash 도구 환경에서는 ${CLAUDE_PLUGIN_ROOT} 가 unset)
REIN_PLUGIN_ROOT="$(claude plugin path rein-core 2>/dev/null || echo "$HOME/.claude/plugins/marketplaces/rein/plugins/rein-core")"

# status 는 바꾸지 않고 분류만 기록
python3 "$REIN_PLUGIN_ROOT/scripts/rein-mark-incident-processed.py" \
  trail/incidents/auto-<hook>-<hash>.md \
  --set-agent-eligible false \
  --set-root-cause bug \
  --reason "pre-bash-safety-guard regex false positive — hook 소스 수정으로 해결"

# status 갱신 + 분류 동시
python3 "$REIN_PLUGIN_ROOT/scripts/rein-mark-incident-processed.py" \
  trail/incidents/auto-<hook>-<hash>.md \
  declined \
  --set-agent-eligible false \
  --set-root-cause bug \
  --reason "..."

레거시 포맷 (INC-NNN.md)

# INC-001: [제목]
...

처리 규칙:

• 레거시 INC-NNN.md 는 trail/incidents/legacy/ 디렉토리에 있을 때만 처리 (opt-in)
• 루트 trail/incidents/ 의 frontmatter 없는 .md 파일은 무시 (gate 영구 발동 방지)
• 레거시 파일을 처리하려면 trail/incidents/legacy/ 로 이동 후 스킬 호출

실행 절차

Step 1: Incident 수집

[ ] trail/incidents/ 전체 파일 목록 확인
[ ] 최신 순 정렬
[ ] 미처리(규칙 미생성) incident 필터링

Step 2: 패턴 분석

[ ] 동일 유형의 incident 그룹화
[ ] 2회 이상 반복된 패턴 식별
[ ] 각 패턴의 근본 원인 분석

Step 3: 규칙 후보 생성

## 규칙 후보: [패턴 이름]
- 근거: INC-NNN, INC-MMM (반복: N회)
- 추가 위치: AGENTS.md §[섹션] 또는 [언어]/AGENTS.md
- 규칙 초안: > [AGENTS.md에 추가할 규칙 문장]
- 우선순위: HIGH / MEDIUM / LOW

Step 4: 사람 결정 수집 + status 갱신 (필수)

각 pending auto-*.md 에 대해:

1. AskUserQuestion 으로 "승격/거부/보류" 결정을 받는다
2. 결정이 "승격" 인 경우: 프로젝트 루트(git root) AGENTS.md 에 규칙을 추가한 뒤 아래 helper 로 processed 마킹. AGENTS.md 가 부재하면 규칙 추가 전에 먼저 starter 템플릿으로 생성한다 — 아래 "AGENTS.md 부재 시" 분기 참조
3. 결정이 "거부" 인 경우: 이유만 기록하고 declined 마킹
4. 결정이 "보류" 인 경우: status 는 그대로 두고 다음 세션으로 이월 (gate 는 계속 차단됨)

AGENTS.md 부재 시 — starter 생성 분기

plugin 사용자 프로젝트는 bootstrap 이 AGENTS.md 를 만들지 않는다 (rein-bootstrap-project.py 는 .rein/·trail/·.claude/security/profile.yaml·.rein/project.json 만 생성). 따라서 승격 결정 시 프로젝트 루트에 AGENTS.md 가 없을 수 있고, 이때 규칙을 쓸 곳이 없어 승격이 사실상 no-op 이 된다.

승격 대상 규칙이 있는데 AGENTS.md 가 부재하면, 규칙을 추가하기 전에 아래 최소 starter 템플릿으로 파일을 먼저 생성한다. 파일이 이미 존재하면 절대 덮어쓰지 않고 규칙만 append 한다.

# AGENTS.md — 프로젝트 실행 규칙

> AI 에이전트가 이 저장소에서 작업할 때 따르는 규칙을 모은다.
> rein 의 `incidents-to-rule` 이 반복 incident 를 규칙으로 승격할 때 갱신된다.

## 규칙

<!-- incidents-to-rule 이 승격한 규칙이 이 섹션에 누적된다 -->

생성 후 Step 3 의 규칙 초안을 ## 규칙 섹션에 추가한다.

helper 호출 (Bash):

# plugin root 해소 (Claude Bash 도구 환경에서는 ${CLAUDE_PLUGIN_ROOT} 가 unset)
REIN_PLUGIN_ROOT="$(claude plugin path rein-core 2>/dev/null || echo "$HOME/.claude/plugins/marketplaces/rein/plugins/rein-core")"

python3 "$REIN_PLUGIN_ROOT/scripts/rein-mark-incident-processed.py" \
  trail/incidents/auto-<hook>-<hash>[-N].md \
  <processed|declined> \
  --reason "<사람이 승인한 규칙 요약 or 거부 이유>"

plugin root 환경 변수는 /plugin install rein@rein 활성 세션에서 자동 주입된다. unset 인 메인테이너 dogfood 환경 또는 Claude Bash 도구 환경에서는 위 resolver block 으로 $REIN_PLUGIN_ROOT 를 해소하거나, scripts/rein-mark-incident-processed.py 로 직접 호출한다 (RES-1 resolver 가 fallback 으로 동일 파일 가리킴).

helper 는 frontmatter 의 status 만 atomic 하게 갱신하고 ## 승격 이력 섹션에 timestamp + reason 한 줄을 append 한다. 수동으로 frontmatter 를 편집하지 말고 반드시 이 helper 를 사용한다 (incident 파일은 trail/ 경로에 있어 DoD gate 면제이지만, format drift 방지).

Step 4b: "보류" 선택 시 deferred stamp 생성 (필수)

사용자가 특정 pending 에 대해 "보류" 를 선택한 경우, 현재 세션 내 재차단을 방지하기 위해 즉시 stamp 를 생성:

touch trail/dod/.incident-decision-deferred

stamp 는 세션 스코프. session-start-load-trail.sh 가 다음 세션 시작 시 무조건 삭제하므로 다음 세션에서 재질문됨.

보류가 여러 건이어도 stamp 1개로 충분. 여러 번 touch 는 noop.

Step 5: 검증

--count-pending 이 감소했는지 확인:

# plugin root 해소 (Claude Bash 도구 환경에서는 ${CLAUDE_PLUGIN_ROOT} 가 unset)
REIN_PLUGIN_ROOT="$(claude plugin path rein-core 2>/dev/null || echo "$HOME/.claude/plugins/marketplaces/rein/plugins/rein-core")"
python3 "$REIN_PLUGIN_ROOT/scripts/rein-aggregate-incidents.py" --count-pending

메인테이너 환경 (plugin root env unset) 에서는 scripts/rein-aggregate-incidents.py 로 직접 호출 가능.

모두 처리되어 0 이 나오면 다음 source 편집 시 pre-edit-dod-gate.sh 의 self-heal 이 .incident-review-pending stamp 를 자동 제거한다.

Step 5b: processed / declined 파일 삭제 (정책)

결정이 processed (rule 승격) 또는 declined 로 종료된 auto-*.md 파일은 삭제한다. 이유는 두 가지:

1. AGENTS.md 에 rule 로 승격된 건은 이미 source of truth 에 반영됨 → incident 파일은 기록용 중복
2. declined 건이 blocks.jsonl 에 남아 있으면 aggregate 가 다음 세션에서 동일 pattern_hash 로 다시 pending 을 만드는 "stale-surfacing" 현상을 재유발함. 파일 삭제가 가장 단순한 해소 수단

Bash:

rm trail/incidents/auto-<hook>-<hash>[-N].md

보류(status=pending 유지) 건은 삭제하지 않는다 — 다음 세션에서 재질문 대상.

agent 로도 승격해야 할 후보(count ≥ 3)는 Step 6 /incidents-to-agent 가 먼저 처리하고, 그 결과로 승격/거부가 확정된 뒤에 동일 정책으로 삭제. 즉 이 Step 5b 는 /incidents-to-agent 가 결정을 마친 뒤에 일괄 수행해도 된다.

Step 6: /incidents-to-agent 스킬 호출 (필수)

--count-pending 결과와 무관하게, 본 스킬 완료 후 반드시 /incidents-to-agent 스킬을 호출한다. 이유:

• rule 로 승격된 건 중 일부는 agent 로도 올려야 할 수 있음 (3회↑ 반복 패턴)
• Stop hook 이 양쪽 스킬 체인 실행을 전제로 block 하므로, 본 스킬만으로는 loop 해소 불가

체인 호출 방법:

/incidents-to-agent

출력

1. 규칙 후보 목록 (우선순위 순)
2. AGENTS.md 수정 초안 (승격된 규칙만)
3. trail/index.md 업데이트

완료 기준

[ ] 모든 미처리 incident 검토 완료
[ ] 규칙 후보 생성됨 (패턴 발견 시)
[ ] 사람이 검토/승인하도록 AskUserQuestion 으로 결정 수집
[ ] 승인된 규칙은 즉시 AGENTS.md 에 추가
[ ] 각 pending incident 의 status 를 helper 로 processed/declined 갱신
[ ] --count-pending 결과가 0 이거나, 남은 건은 의식적 "보류"
[ ] Step 6 /incidents-to-agent 스킬 호출 완료
[ ] 보류 건이 있었다면 .incident-decision-deferred stamp 생성 확인
[ ] processed/declined 로 종결된 auto-*.md 파일은 /incidents-to-agent 완료 후 일괄 삭제 (Step 5b 정책)