agentleFS
kohj1018kohj1018/agentic-dev-harness/.claude/skills/repair-workitem/SKILL.md

repair-workitem

Skill2 starsChanged 48 days agoMITView on GitHub

Apply fixes for failed validation report items, scoped to the documented workitem.

The file

Files
SKILL.md

이 skill은 직전 /validate-workitem이 남긴 report의 실패 항목을 비판적으로 재점검한 뒤, 진짜 결함만 수정한다. 메인 세션에서 실행되므로 풀 프로젝트 컨텍스트로 판단한다. 새 기능 추가, 범위 밖 변경, 자동 커밋은 금지한다.

입력:

  • $ARGUMENTS에는 task ID와 (선택) 부분 지정 메모가 들어온다.
    • 예: T-001
    • 예: T-001 "P0 #1, P1 #3만" — report의 일부 항목만 대상
  • task-id sanitization 강제: T-[0-9]+ 패턴만 허용. /, 공백, glob 메타문자(*, ?, [) 포함 시 즉시 종료(rm 경로에 들어가므로 안전 전제 — validate-plan M[0-9]+/repair-milestone M[0-9]+ 가드와 대칭).

반드시 먼저 할 일:

  1. 관련 task 문서를 읽는다 (## 6 AC, ## 8 메모(HTML 주석 밖)의 기존 해석 확정·해석 잠정/repair 결정 이력 포함).
    • 메인 세션 연쇄 실행으로 직전 단계가 같은 task 문서를 메인 컨텍스트에 올렸고 그 뒤 갱신되지 않았으면 ## 6 AC 재독은 생략(ADR-019). 단 이전 repair 라운드가 ## 8. 메모를 append(mutate)했다면 그 메모는 반드시 재독한다 — 직전 라운드의 4-판정 이력을 보고 같은 항목 재출현을 판단해야 하므로. 2-G. 상태별 입구 게이트 (ADR-068 D1 — 마일스톤 층에서만 done 재개방 폐지): 아래 수행 2(report 읽기)보다 먼저 판정한다 — 폐쇄된 마일스톤에서 report 분기가 먼저 걸리면 /validate-workitem·/finalize-workitem을 잘못 처방하게 된다(둘 다 폐쇄 상태에서 각각 종료·no-op이라 실행 불가한 처방이다). task ## 0. Status를 확인한다.
    • draft/ready(아직 구현 전) → repair를 거부하고 "먼저 /implement-workitem으로 착수" 안내 후 종료.
    • in-progress → 상태를 쓰지 않는 일반 repair로 계속한다.
    • done → 부모 마일스톤의 «층»을 먼저 판정한다. 그 마일스톤 산하 task를 전수 조회해:
      • 산하에 done이 아닌 task가 하나라도 있으면 (아직 task 층) → 기존대로 진행한다. 아래 수행 2의 report 판정(또는 finding-mode 근거)이 검증된 결함을 가리킬 때만 아래 "수행"의 done 재개방 절차를 따른다. /repair-workitem만이 done task를 재개방하는 유일한 writer라는 규율은 이 구간에서 유효하다.
      • 산하 task가 전부 done이면 (마일스톤 층) → 거부하고 종료한다. 파일·git index·status를 전혀 건드리지 않고 안내한다: "이 마일스톤은 산하 전 task가 done이라 마일스톤 층입니다(ADR-068 D1). 수리는 /repair-milestone <M>(stabilize finding) 또는 /repair-acceptance <M>(수용 finding)이 재개방 없이 직접 수행합니다."
    • done → in-progress 역전이는 «폐쇄 전»에만 존재한다. ADR-057#amend-3 결정 5의 그 전이를 ADR-068 D1이 부분 supersede한 범위가 정확히 그것이다.
  2. docs/40-validation/reports/<task-id>.md를 읽는다 (report는 매 validate phase 새로 쓰이므로 항상 새로 읽는다 — 캐시 대상 아님).
    • 파일이 없거나 stale(파일 mtime이 task 문서/구현 파일보다 오래됨)하면 /validate-workitem 선행을 안내하고 종료한다.
    • 파일 판정이 Pass 또는 Pending Acceptance(ADR-065 D6)면 /finalize-workitem을 안내하고 종료한다(repair 대상 없음). Pending Acceptance는 «사람이 볼 것만 남았다»는 뜻이라 코드로 고칠 것이 없다 — /accept-milestone <M>으로 보내지도 않는다(그것은 마일스톤 층 단계다).
    • 실패 항목이 전부 [P0] 감사 미완(unavailable)이면 즉시 종료한다 — 코드로 고칠 것이 없으므로 4-판정에 들어가지 않고 /validate-workitem <task-id> 재실행을 안내한 뒤 종료한다(report를 삭제하지 않는다). 다른 실패 항목이 섞여 있으면 이 가드에 걸리지 않고 정상 진행하되, 감사 미완 항목은 4-판정 대상에서 제외한다.
    • 단, 인자에 finding 요약이 있으면 위 종료 조건 전부에 걸리지 않고 그 finding을 대상으로 진행한다(finding-mode) — 호출 주체는 사용자, /implement-workitem 3-R (1)의 «선행 task 산출 누락» 경로를 따르는 메인 세션, 또는 /run-milestone(이번 라운드 계약 P1 · done task 소유 P0/P1 finding · 사용자가 요청한 AC 재해석 — ADR-076 D3·D5·D10)이다. /repair-milestone·/repair-acceptance는 더 이상 위임하지 않는다(ADR-068 D1). 이 모드는 폐쇄 전 task 층에서만 성립한다 — 2-G가 마일스톤 층 진입을 이미 막는다. 즉 report가 Pass·Pending Acceptance·stale·부재여도, 실패 항목이 전부 감사 미완이어도 종료하지 않는다. stale을 여기 명시하는 것이 중요하다 — 호출 시점에 이미 다른 파일이 바뀌어 있는 것이 정상이라 report는 stale이고, 앞의 stale 가드가 먼저 걸리면 이 경로가 첫 고리에서 죽는다. 아래 "비판적 재점검"을 그 finding에 적용해 코드를 수정하고 task ## 8. 메모에 결정 이력을 남긴다. finding-mode에서는 (a) Pass·Pending Acceptance report를 삭제하지 않고(실패 report가 아님), (b) QA_FINDINGS·IMPROVEMENT_GUIDE는 건드리지 않으며(원장 status 종료는 본 skill의 책임이 아니다 — "다른 산출물 미접근" 계약 유지), (c) 마지막 출력에 "/validate-workitem <task-id> 재실행으로 수정 확인" 안내를 포함한다. 그 재실행과 이어지는 /finalize-workitem을 누가 돌리는지는 호출 주체로 갈린다 — 메인 세션이 /implement-workitem 3-R (1) 경로 또는 /run-milestone으로 호출했으면 그 세션이 이어서 실행하고, 사용자가 직접 호출했으면 사용자가 실행한다(그 경우 마지막 출력에 두 단계를 순서대로 명시한다).
  3. 사용자가 인자로 부분 지정을 줬으면 그 부분만 대상으로 한다. 3-A. AC 재해석 finding (ADR-076 D5 — 폐쇄 전 task 층에서 사용자가 즉시 변경을 원할 때): finding 요약이 AC-N 재해석: <선택> 형식이면, 수정 전에 task ## 8에 해석 확정: AC-N = <선택> (사용자 확인 <YYYY-MM-DD>, 잠정 해석 변경)을 append하고 그 해석으로 코드·테스트를 고친다(이 기록은 아래 3의 결정 이력과 별개다). 마일스톤 층의 잠정 해석 확인은 /repair-milestone이 한다.
  4. 실패 항목을 우선순위(P0 > P1 > P2)로 정렬한다.

비판적 재점검 (수정 전 1회 — validator가 틀리거나 맥락을 놓쳤을 수 있다): 각 실패 항목마다 실제 코드·문서·task AC를 직접 확인해 4가지 중 하나로 판정하고 한 줄 근거를 남긴다 (repair-plan과 동형):

  • Adopt — 진짜 결함. report 제안대로 수정.
  • Adopt-modified — 결함은 맞지만 더 나은 방식으로 수정 (다른 수정 + 사유).
  • Reject-false-positive — validator가 잘못 봄 (예: 이미 충족됨 / 자연어 매핑 휴리스틱 오탐 / placeholder 오인). 수정하지 않는다.
  • Reject-context — validator가 task 범위·상위 제약을 놓침 (예: task ## 4. 제외 항목·charter 비목표상 의도된 동작). 수정하지 않는다.

자기 판단을 신뢰하되, 애매하면 Adopt 쪽으로 보수적으로. Reject는 근거가 코드/문서로 확인될 때만.

수행:

  1. Adopt / Adopt-modified 항목을 우선순위(P0 > P1 > P2) 순으로 수정한다. 대상 task가 done이었던 경우(2-G가 «아직 task 층»으로 통과시킨 경우에만 여기 도달한다): Adopt/Adopt-modified가 하나 이상이면 첫 코드 수정 직전에 task ## 0. Status를 done → in-progress로 갱신·기록한다(전부 Reject면 코드·status 무변경 — 고친 것이 없으므로 마지막 출력은 validate 재실행 대신 /finalize-workitem <task-id>를 안내한다. finalize가 아래 3의 결정 줄을 status 변경 없이 커밋한다 — «결정 기록 잔존», ADR-076 D10). 재개방 뒤 이 라운드가 중단되거나 실패하면 in-progress로 유지한다(임의로 done으로 되돌리지 않는다) — 수정 완료 후 fresh /validate-workitem을 거쳐 /finalize-workitem이 다시 done으로 커밋한다. 마일스톤 층에서는 이 경로에 도달하지 않는다(2-G에서 종료).
  2. 한 라운드에 P0/P1/P2를 모두 4-판정으로 완결한다(repair-plan과 동형). report를 삭제하므로 defer 금지 — 미처리 항목을 남기면 삭제 시 정보가 사라진다. 작업량을 줄이려면 사용자가 인자로 부분 범위를 지정한다(T-001 "P0 #1, P1 #3만"). 2-E. 실행 증거 갱신 (ADR-064 D4 — 외부 경계 코드를 고쳤을 때만): 본 라운드의 Adopt/Adopt-modified 수정이 (a) 영속 저장소 쓰기 · (b) 외부 네트워크 호출 · (c) 실행 진입점 코드를 건드렸으면, 그 경계의 실행 증거를 다시 확보하고 task ## 8에 - exec-evidence 줄을 새로 append한다(기존 줄은 지우지 않는다 — 이력이다). 증거 등급·안전 규정·waiver 규정은 implement 6-E와 동일하다. 확보하지 못하면 Needs Execution Evidence: <경계 종류> — <사유>를 출력에 남긴다. 등급 1 증거로 새 파일을 만들었으면 task ## 4-1에도 그 경로를 추가한다(finalize 의 add 목록 누락 방지 — 본 skill 은 단독 실행이라 ## 4-1 단일 writer 규율과 충돌하지 않는다). 확보하지 못하면 task ## 8에 - exec-evidence <날짜> <경계 종류>: 미확보 — <사유> (repair-workitem)을 append한다(옛 줄은 지우지 않는다). 이 줄이 다음 validate의 판정 입력이다. 이 책임이 repair에 있는 이유: receipt writer를 implement 단독으로 두면 validate(Needs Fix) → repair(코드 수정) → 재validate 에서 증거가 낡은 채 남고 그것을 갱신할 주체가 없어 루프가 닫힌다. 코드를 고친 주체가 그 자리에서 증거를 갱신하는 것이 이 계약의 신선도 유지 방식이다. 본 skill이 ## 8에 쓰는 시점은 /validate-workitem 재실행 이전이고 아래 4에서 report를 삭제하므로, task 문서 mtime 갱신이 report를 stale로 만드는 문제는 발생하지 않는다.

2-F. AC acceptance 무효화 (ADR-065 D3): 본 라운드의 Adopt/Adopt-modified 수정이 어떤 AC의 동작 경로를 건드렸고 그 AC의 modality가 [사용자 관측]·[플랫폼 관측]이면, task ## 8에 - invalidated <날짜> <AC-N>: repair-workitem 수정으로 재확인 필요 한 줄을 append한다(기존 - ac-acceptance 줄은 지우지 않는다 — 이력이다). 그 AC는 다음 validate에서 미충족이 되고 receipt 재발급이 필요하다. 에이전트가 새 receipt를 쓰지 않는다.

2-H. 동일 패턴 전수 검색 (ADR-066 D6): Adopt/Adopt-modified한 각 결함에 대해 같은 패턴의 다른 출현을 저장소 전체에서 읽기 전용으로 검색한다(Grep). 결과를 task ## 8에 - pattern-scan <날짜> <패턴 1줄>: 범위 내 N건 수정 / 범위 밖 M건 <경로 목록>으로 append하고 마지막 출력에도 한 줄 남긴다. 범위 밖 출현은 고치지 않는다(task 범위 계약 유지 — 읽기는 범위 제한 대상이 아니다). 범위 밖 항목은 /stabilize-milestone·/repair-milestone이 회수한다. 검색으로 아무것도 안 나왔으면 범위 밖 0건으로 적는다(검색 사실 자체가 기록이다).

  1. 결정 이력 영속화 (ADR-047 D7) — 본 라운드의 P0/P1 항목 전부에 대해 task 문서 ## 8. 메모에 한 줄씩 append(P2는 cap 보호로 미영속): - repair-workitem <YYYY-MM-DD> <severity> <category> <file:line|AC-N>: <Adopt|Adopt-modified|Reject-FP|Reject-context> — <근거 ≤80자> (위치 칸은 같은 지적의 재등장을 판정하는 입력이다 — 파일 부분 또는 AC-N만 비교한다, ADR-076 D3) (P0/P1은 Adopt·Reject 모두 기록 — 다음 validate가 같은 항목을 다시 올릴 때 사람이 판단 이력을 본다. P2는 미영속 — 재출현해도 finalize의 AC 게이트를 막지 않아 무해.)
  2. report 삭제 — 대상 항목 전부(P0/P1/P2)를 수정 또는 Reject로 완결한 뒤 삭제한다. 감사 미완(unavailable) 항목이 남아 있어도 삭제한다 — 그것은 미처리가 아니라 재validate로만 해소되는 항목이라 삭제가 오히려 정확한 처방이다. 사용자가 인자로 부분 범위를 지정해 진짜 결함이 미처리로 남은 경우에만 삭제하지 않는다:
    • 삭제 전 echo 강제: 메인 세션 출력에 삭제 대상 경로를 명시 (예: 삭제 예정: docs/40-validation/reports/T-001.md) — 사용자가 눈으로 확인.
    • rm docs/40-validation/reports/<task-id>.md 1개를 정확히 삭제한다 (다른 task의 report는 건드리지 않는다).
    • 삭제 후, 다음 /validate-workitem <task-id>가 새 report를 생성한다는 안내를 출력에 포함.
  3. 자체 검증 — 즉시 파손 감지 (위 1~4를 전부 마친 뒤 1회): 통합 검증 명령이 --changed를 지원하면 validate --changed를 1회 실행한다. 이것은 전체 검증이 아니다 — 「방금 한 수정이 즉시 깨졌는가」만 본다. full validate·AC 스코프 정합·diff 추적성은 /validate-workitem 책임이다.
    • 고치는 대상은 본 라운드 수정이 만든 실패로 한정한다. baseline은 report의 ## 통합 명령 실행 결과 섹션 값이며, 위 「반드시 먼저 할 일 2」에서 report를 읽을 때 그 값을 메모리에 보관해 둔다(4에서 report를 삭제하므로 여기서 다시 읽을 수 없다 — 경로·값을 미리 회수하는 기존 규율과 동형). baseline에 이미 있던 실패는 고치지 않고 출력에 명시한다.
    • 실패를 고치면 다시 실행한다. 최대 3회. 초과하면 Needs Follow-up: <실패 목록>으로 출력에 명시하고 종료한다(조용히 넘기지 않는다).
    • --changed 미지원이거나 통합 명령이 없으면 이 단계를 skip한다 — 별도 hardstop을 만들지 않는다(/validate-workitem이 받는다). skip 사유를 출력에 한 줄 남긴다.
  4. ## 4-1 갱신 (ADR-076 D13 — 1~5를 모두 마친 뒤 마지막에): 본 라운드에 고치거나 새로 만든 파일 중 task ## 4-1에 없는 것을 추가한다 — 수행 5에서 고친 파일과 아래 ## 봉인 후 새 결정 등재의 docs/10-charter/DECISION_REGISTER.md append도 포함한다(task 문서 자신, .gitignore 대상, finalize가 자동 add하는 lock 파일 제외 — 2-E의 증거 파일 규칙을 모든 수정 파일로 넓힌 것이다). 빠지면 /finalize-workitem이 Needs Review로 끝나 validate가 한 번 더 돌고, /run-milestone에서는 validate 전 대조가 그 task를 빼둔다.

봉인 후 새 결정 등재 (ADR-060 D11)

수정 중 기존 task·AC가 약속하지 않은 기획 결정이 새로 드러나면(사용자가 정하거나 승인해야 할 것), 임의로 확정하지 말고 docs/10-charter/DECISION_REGISTER.md에 status: open + - 발견: 봉인 후 (M<N>) 줄로 등재하고 사용자에게 보고한다. 이 등재는 착수·구현을 막지 않는다 — 라우팅은 (a) 기존 약속 결함이면 본 skill이 계속 수정, (b) 새 범위면 다음 마일스톤 후보, (c) 불명확하면 사용자 결정 대기(ADR-057#amend-3 결정 6). 원장 파일이 없으면 등재를 건너뛰고 보고만 한다.

책임 경계:

  • 새 기능을 추가하지 않는다.
  • task 범위 밖 파일을 수정하지 않는다.
  • 자동 커밋하지 않는다 — 결과만 반환하고 커밋은 /finalize-workitem 또는 사용자가 별도로.
  • 본 task-id의 report만 삭제. 다른 산출물(QA_FINDINGS / IMPROVEMENT_GUIDE / 다른 report)은 건드리지 않는다. 예외 1가지: 위 ## 봉인 후 새 결정 등재의 docs/10-charter/DECISION_REGISTER.md append(status: open + - 발견: 봉인 후 (M<N>)) — ADR-060 D11 writer로 지정된 책임이며, 기존 항목의 상태는 바꾸지 않는다.

마지막 출력:

  • 4-판정 카운트: Adopted M / Adopt-modified K / Reject-FP I / Reject-context J
  • 수정 파일 목록 + 어떤 실패 항목을 어떻게 해소했는지
  • Reject한 항목 + 근거 (있으면)
  • ## 8. 메모 append 줄 수
  • 삭제한 report 경로
  • 미해결 항목 (있으면)
  • 실행 증거 갱신 (ADR-064 D4): 갱신 N건(경계 종류) / 해당없음(외부 경계 코드 미수정) / Needs Execution Evidence
  • AC acceptance 무효화 (ADR-065 D3): N건(AC-N 목록) / 해당없음
  • 동일 패턴 전수 검색: 범위 내 N건 / 범위 밖 M건(경로) — 범위 밖은 미수정
  • 자체 검증 (즉시 파손 감지): pass / skip(사유) / Needs Follow-up: <목록>
  • 다음 권장 액션: /validate-workitem <task-id> 재실행 (새 report 생성 → Pass·Pending Acceptance면 /finalize-workitem)

정책 근거: 비판적 재점검·전 severity 완결·report 삭제는 ADR-050 D3 / repair-plan(ADR-038) 대칭. 결정 이력 영속은 ADR-047 D7. 동일 패턴 전수 검색은 ADR-066 D6. 판정값 3종은 ADR-065 D6. done 재개방 폐지는 ADR-068 D1.

Context 정책 (ADR-019)

반드시 먼저 읽을 파일은 최소 충분. 추가 ADR/architecture 섹션은 task 본문에서 발화 시 인용 — 사전 fork-load 금지. 메인 세션 연쇄 실행(validate→repair, ADR-050) 시 직전 단계가 메인 컨텍스트에 올린 task ## 6 AC는 갱신되지 않았으면 재독 생략. 단 직전 repair 라운드가 mutate한 ## 8. 메모와 매 phase 새로 쓰이는 report는 항상 재독.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.