iop/agent-ops/skills/common/refine-local-plans/SKILL.md

name	description
refine-local-plans	현재 plan들 세분화해, 현재 plan 세분화, 기존 plan 더 나눠, local plan 분리해 같은 요청에서 이미 생성된 미착수 PLAN-local-G??/CODE_REVIEW pair를 최대 3개의 작은 local sibling pair로 나누고 같은 task group의 미착수 index를 의존성 순서로 함께 정렬할 때 사용한다.

Refine Local Plans

목표

이미 생성된 미착수 local pair를 로컬 모델이 수행하기 쉬운 응집된 단위로 이번 실행에서 한 단계만 나눈다. Source/test를 다시 조사하거나 검증을 실행하지 않는다.

대상

• 사용자가 지정한 active task group, task path, 또는 PLAN-local-G??.md를 사용한다. 대상을 생략하면 미착수 local pair가 있는 task group이 정확히 하나일 때만 진행한다.
• PLAN-local-G??.md와 matching CODE_REVIEW-*-G??.md가 모두 있고 verdict가 없어야 한다.
• Review의 구현 완료표·구현 체크리스트가 모두 미체크이고, 구현 소유 기록과 검증 출력이 아직 채워지지 않은 pair만 미착수로 본다.
• complete.log 또는 USER_REVIEW.md가 있거나 구현이 시작된 pair는 수정하지 않는다.
• 대상 pair, 같은 task group의 미착수 active sibling pair, active directory basename과 archived sibling directory basename만 읽는다. Archive 내부 파일은 읽지 않는다. 새 구현 조사를 위해 source/test/roadmap/archive 본문을 읽지 않는다.

절차

1. 범위를 고정한다

   • 기존 PLAN의 checklist, plan item, 수정 파일, 검증 명령을 원본 범위로 고정한다.
   • Plan에 없는 구현 범위나 검증을 추가하지 않는다.

2. 유지 또는 분리를 결정한다

   • 서로 독립적으로 구현·검증 가능한 behavior slice가 정확히 2개 또는 3개일 때만 나눈다.
   • 각 child는 하나의 응집된 결과와 필요한 production 변경을 가진다.
   • Production 변경의 PASS에 필요한 기존 PLAN의 테스트는 같은 child에 둔다. 추가 통합/closure 검증만 별도 test child가 될 수 있다.
   • 경계가 불명확하거나 공유 write set·상태·순서 때문에 coordination이 커지면 원본을 유지한다.
   • 원본 유지로 결정하면 파일을 바꾸지 않고 결과만 보고한다.
   • 이번 실행에서 만든 child를 다시 분할하지 않는다.

3. 경로와 dependency를 정한다

   • 이름은 NN_{subtask_name} 또는 NN+PP[,QQ...]_{subtask_name}만 사용하며 모든 predecessor는 NN보다 작아야 한다.
   • Target children과 같은 task group의 active sibling으로 DAG를 만든다. 시작·완료 sibling은 고정 anchor로 두고, 나머지는 producer가 consumer보다 먼저 오도록 topological sort한다.
   • 같은 단계에서는 기존 sibling의 index와 새 child의 원본 PLAN item 순서를 유지하고 basename으로 마지막 tie를 정한다.
   • 검사 시작 시 구현이 시작됐거나 complete.log, USER_REVIEW.md, 기존 *.log가 있는 sibling의 NN은 고정한다. Archived sibling의 NN도 예약된 번호로 취급한다.
   • 나머지 node에는 모든 predecessor보다 크면서 충돌하지 않는 가장 낮은 두 자리 index를 topological 순서대로 배정한다. 고정 predecessor 이하이거나 예약된 번호만 건너뛴다.
   • Reindex 후 각 basename의 predecessor를 새 index로 치환하고 오름차순으로 기록한다. 독립 node는 NN_, dependent node는 NN+PP[,QQ...]_를 사용한다.
   • 기존 dependent의 원래 predecessor를 실제 소비하는 child로 바꾼다. 전체 결과를 필요로 하면 마지막 closure child를 사용하고, 소비 child를 판단할 수 없으면 분리하지 않는다.
   • 고정 index 때문에 dependency 순서를 만들 수 없거나 cycle, 99 초과, 시작된 sibling 이동이 필요하면 분리하지 않는다.
   • 예: 미착수 01_core, 03+01_api, 04+01,03_integration은 01_core, 02+01_api, 03+01,02_integration으로 정렬한다. 기존 03이 시작된 상태면 03은 이동하지 않는다.
   • Reindex되는 sibling은 directory basename과 PLAN/review 안의 기존 task path·index·dependency 참조를 새 값으로 바꾼다. 구현 scope, checklist, 검증, routing은 바꾸지 않는다.

4. 현재 PLAN/CODE_REVIEW 형식을 유지한다

   • 각 child는 기존 PLAN을 복제한 뒤 자신의 scope만 남긴다. Header/task, title, background, 구현 체크리스트, plan item, 수정 파일 요약, 최종 검증을 child 경계에 맞게 갱신한다. 기존 PLAN에 분석 결과가 있으면 읽은 파일·테스트 공백·심볼 참조·분할 판단·범위 결정 근거도 child 범위로 줄인다.
   • Roadmap Targets는 전체 결과를 닫는 closure child 하나에만 둔다. Agent UI Completion도 해당 구현과 PASS evidence를 소유하는 child 하나에만 둔다. 소유 child를 정할 수 없으면 분리하지 않는다.
   • 각 review는 기존 CODE_REVIEW를 복제한 뒤 header/task, 완료표, 구현 checklist, checkpoint, 검증 section을 matching PLAN과 맞춘다. 고정 안내와 review 전용 section의 문구는 유지하되 child task path와 future archive suffix 참조는 갱신한다.
   • PLAN과 review는 입력에 이미 있는 section 구조를 유지하며 없는 section을 새로 만들지 않는다. 첫 task header 외의 HTML metadata comment는 출력에서 제거한다.
   • PLAN과 review의 첫 줄은 동일한 task, plan, tag를 사용한다. Checklist 문구·순서와 검증 명령을 서로 일치시킨다.
   • 기존 build/review lane, G, canonical basename과 최종 라우팅 값을 child에 그대로 유지한다. Strict-subset local refinement에서는 finalize-task-routing을 다시 실행하지 않는다.

5. 최종 pair로 직접 교체한다

   • 모든 child pair, sibling reindex, directory rename map을 먼저 메모리에서 완성하고 최종 경로·archive log 충돌을 확인한다.
   • 원본 active review와 PLAN을 각 파일 basename의 lane/G와 다음 monotonic suffix를 사용해 같은 task directory의 code_review_*.log, plan_*.log로 archive한다.
   • Reindex가 필요한 미착수 directory는 목적지가 비는 순서로 최종 basename으로 이동한다. 임시 directory나 별도 상태 파일이 필요한 충돌이면 분리하지 않는다.
   • Indexed target은 첫 child가 최종 basename으로 재사용한다. Task-group root의 single-plan target은 원본 log를 root에 남기고 모든 child directory를 새로 만든다.
   • 재사용 directory의 plan 번호와 future archive suffix는 원본 pair archive 후 log count를 사용한다. 새 child directory는 기존 log가 없으면 0을 사용한다.
   • Child PLAN/CODE_REVIEW를 최종 routed basename에 직접 쓴다. 임시 상태나 복구용 Markdown을 만들지 않는다.
   • 기존 파일이나 log를 덮어쓰지 않는다. 모든 최종 pair의 header, checklist, 검증 명령과 predecessor NN < consumer NN을 확인한다.

6. Readiness를 보고한다

   • 각 child directory의 encoded predecessor만 확인한다.
   • 모두 충족되면 implementation-ready, 하나라도 미충족이면 dependency-waiting으로 보고한다.
   • Worker, Review, 다음 sibling을 시작하지 않는다.

출력

Local plan refinement
- targets: <원본 PLAN 경로>
- decisions: <유지 | 원본 -> child 목록>
- dependency updates: <변경 내용 또는 없음>
- readiness: <pair path = implementation-ready | dependency-waiting>
- document check: passed

금지

• Source/test 재분석, compile, build, test, lint, formatter, smoke/E2E, live/remote 검증을 실행하지 않는다.
• Package 설치, dependency 다운로드, cache warming을 하지 않는다.
• Child 재귀 분리, cloud pair 분리, 다른 task group 또는 시작·완료 sibling 재인덱싱을 하지 않는다.
• 별도 상태 파일, 임시 pair, repository 밖 복구 파일을 만들지 않는다.