---
name: run-batch-implementation
description: "Use when: implementing a confirmed batch design, running /run-batch-implementation with a BAT ID, applying code changes for docs/batches/<BAT_ID>, or updating implementation logs and validation evidence for a batch."
version: 0.7.1
author: Justin Ko
license: private
argument-hint: "예: bat-001 또는 docs/batches/bat-001_20260424_scaffold"
user-invocable: true
metadata:
  hermes:
    tags: [stage-pilot, batch, implementation, execution, sdlc]
    related_skills: [draft-batch-planning, draft-batch-design, draft-batch-verification, confirm-req-implemented]
---

# Purpose

This skill executes the implementation work for a batch, updates code, and records the changed files, execution log, validation, and remaining risks in the batch implementation document.

# Inputs

- `BAT-ID` 또는 batch 경로
- `docs/batches/<BAT_ID>/planning.md`
- `docs/batches/<BAT_ID>/design.md`
- `docs/batches/<BAT_ID>/implementation.md`
- 관련 REQ 문서와 실제 코드 경로

# Core Rules

- planning과 design이 없는 batch는 구현하지 않는다.
- 코드 변경 전 `implementation.md`의 Plan Summary와 Changed Files 초안을 먼저 맞춘다.
- 구현 직후 가장 좁은 테스트, lint, typecheck, 또는 동작 검증을 수행한다.
- stateful runtime을 host/PYDEBUG binding으로 검증할 때는 동일 입력 반복 호출이 내부 scan/cache/state를 누적할 수 있음을 먼저 점검한다. deterministic evidence가 필요하면 테스트 전에 reset hook을 추가하거나 초기 상태를 명시적으로 복원한 뒤 비교한다.
- blocker가 생기면 문서에 남기고 범위를 임의 확장하지 않는다.
- 구현을 시작한 batch는 `implementation.md`만 갱신하고 끝내지 말고, batch index와 batch index 문서의 Status도 최소 `in-delivery`로 맞춰 stage 상태가 어긋나지 않게 한다.
- 배치 문서 경로가 아직 없거나 추적 문서가 비어 있으면, 구현 단계에서 `index.md`, `implementation.md`, `verification.md` 기본 뼈대를 함께 정리해 이후 stage가 바로 이어질 수 있게 한다.

# Execution Procedure

1. batch 경로, plan, design, 관련 REQ를 읽는다.
2. 구현 범위와 변경 파일 후보를 요약한다.
3. 실제 코드 변경을 수행한다.
4. `implementation.md`의 Changed Files, Execution Log, Validation, Remaining Risks를 갱신한다.
5. batch index 상태를 필요하면 `in-delivery`로 유지 또는 보정한다.
6. persistence schema, flash migration, 또는 저장 포맷 호환성 이슈를 디버깅할 때는 호스트/PYDEBUG 빌드의 `sizeof(...)` 추정으로 결론내리지 말고, 타깃 펌웨어 쪽에 구조체 크기(`sizeof(struct prop_header)`, 관련 persisted struct), header probe 결과, 첫/둘째 `property_read(...)` 반환값을 직접 로그로 남겨 원인을 분리한다.

# Validation

- `implementation.md`에 실제 변경 파일과 검증 기록이 반영됐는지 확인한다.
- 구현 직후 수행한 가장 좁은 검증 명령 또는 결과가 문서에 남았는지 확인한다.
- persistence/migration 디버깅 변경이라면, 타깃 로그로 ABI 크기와 read rc를 캡처하는 계측 또는 동등한 증거가 남았는지 확인한다.
- batch 문서 `index.md`와 `docs/batches/index.md`의 Status가 구현 진행 상태(`in-delivery` 등)와 일치하는지 확인한다.