Executing Plans

Executing Plans

Overview

Load plan, review critically, execute all tasks task-by-task, with strict per-edit discipline that captures before/after code and risk annotations into -implementation-plan.md change-history.

Announce at start: "executing-plans skill 로 본 계획을 task-by-task 실행하겠습니다."

Note (subagent path): This skill is the inline execution mode. If subagents are available (Claude Code, Codex) AND the user wants to preserve main context for large features, the recommended subagent path is subagent-driven (slim 2-stage: implementer + spec reviewer + main post-processing for RISK / 변경이력 / atomic commit). The original upstream subagent-driven-development (3-stage: + quality reviewer) is also available for compatibility but duplicates governance intent-locked-workflow already provides via verifying-spec + TDD + RISK + 변경이력.

When to Use

• A -implementation-plan.md exists in docs/features/<date>-<slug>/
• Inline (single-session) execution preferred over per-task subagents
• Each task in the plan follows TDD bite-sized steps

Task 이름 가이드 (FR-6 / v1.1.15+): 구현계획서 §1 의 각 Task 이름은 사용자 친화 한국어로 작성되어야 합니다 (TaskCreate 시 그대로 노출). 내부 용어 (Invoke ... skill, Gate #N, 영어 식별자) 는 TaskCreate 이름에 노출하지 말 것. CLAUDE.md TaskCreate 명칭 룰 참조.

Checklist

• Step 1 — Plan 로드 + 비판적 검토 (Plan Loading)
• Step 2 — Code Edit Discipline (git-fast / memory-fallback 모드 선택)
• Per-edit — risk-annotation 3-checklist + RISK comments
• Per-task — 코드만 커밋 (git-fast) / Per-run — Phase 3 에서 batch entry 1개 (change-history)
• Step 3 — Complete Development (테스트 + finishing-a-development-branch)

Plan Loading

Step 1: Load and Review Plan

1. Read docs/features/<date>-<slug>/<slug>-implementation-plan.md
2. Review critically — list any gaps or concerns
3. If concerns exist: raise them with the user before starting
4. If clean: create TaskCreate tasks (one per plan task) and proceed

Code Edit Discipline (REQUIRED — intent-locked-workflow extension)

Two execution modes

This skill picks ONE mode at task start based on git availability + plan policy:

1. Run mode-check helper (v1.1.14+ deterministic):

source .venv/bin/activate && python -c "
import sys
from pathlib import Path
from scripts.preflight import execute_plan_mode_check
result = execute_plan_mode_check(Path('<PLAN_PATH>'))
print(f'ok={result.ok} reason={result.reason}')
sys.exit(0 if result.ok else 1)
"

이 helper 가 plan frontmatter 의 commit_policy 를 deterministic 으로 읽어 반환.

exit code 분기 (v1.1.15 user-gate):

• exit 0 → reason 에 commit_policy=per-task 형식. 메인은 policy 값으로 모드 분기:
  • per-task → candidate mode = git-fast
  • single → candidate mode = memory-fallback (all tasks → one commit at end)
  • none → candidate mode = memory-fallback (no commits during run)
• exit 1 (semantic fail — plan not found) → human_reason 노출 후 AskUserQuestion 게이트:
  • "수정 후 재시도" (사용자가 plan 경로 확인) / "강제 진행 (위험)" (사용자가 입력한 plan 경로 직접 사용 — 메인이 추가 안내) / "스킵 (이번만)" (executing-plans 종료).
• exit ≠ 0,1 (invocation 실패) → stderr 노출 + AskUserQuestion 게이트:
  • "직접 디버깅" / "skill 단계 스킵".

기존 LLM 산문 추론 단계 제거 (v1.1.14). frontmatter 파싱 결과를 그대로 신뢰. 자세한 룰은 scripts/preflight.py:execute_plan_mode_check.

2. Check git availability: git rev-parse --git-dir (Bash). If git unavailable, force mode = memory-fallback regardless of frontmatter.

3. Final mode decision:

   • Both checks point to git-fast → mode = git-fast
   • Either check forces memory-fallback → mode = memory-fallback. If frontmatter requested single/none (i.e., user-intentional), proceed silently. If git was unavailable but frontmatter said per-task, WARN the user once: "⚠️ git repo 미초기화 → memory-fallback 모드로 진행합니다. 변경 전 코드 보존 비용이 큽니다."

The chosen mode applies to the whole /executing-plans run. Do not switch mid-run.

Why a frontmatter field, not prose detection: Prose scanning ("commit 생략" 등 키워드 매칭) is unreliable. The frontmatter field is unambiguous, machine-checkable, and lives next to the plan it governs.

git-fast mode (default)

Phase 1 — Per code edit (repeat for each edit in the task):

1. Risk check: Run risk-annotation 3-checklist on the planned change.
2. Apply edit: Edit/Write the file (insert # ⚠️ RISK(...) comments above risky lines as needed). Trust the Edit tool's success/failure return — do NOT re-Read just to confirm the comment landed.

(Repeat 1-2 for every code edit. Track (file:line, risk_categories) tuples in memory — before/after code is recovered from git later, no in-memory snapshot needed.)

Phase 2 — Once per task, AFTER all task edits + tests pass (commit happens LAST):

Per task: code-only commit (plan.md untouched). Footer entry is deferred to end-of-run consolidator (v1.1.7+). This batches N tasks into a single consolidated [코드-수정] entry, drastically reducing footer noise + Read/Edit cost.

3. Capture diff for accumulator (NOT for footer): git diff HEAD -- <code files only> — parse hunks. Append (task_id, file:line_range, summary, risk_categories, planned_commit_msg) to in-memory accumulator. Do NOT touch -implementation-plan.md here.
4. Commit (scoped, code only): git add <explicit list of code files touched in this task> then git commit -m "<task summary>". NEVER use git add -A or git add .. The code-file list MUST come from the in-memory (file:line, ...) tuples tracked during Phase 1. plan.md is NOT included in this commit — it gets its own single [log] all tasks commit at end-of-run.

Phase 3 — End-of-Run Consolidator (v1.1.7+, runs ONCE after final task):

5. Render "구현 요약" message to the user: planned tasks vs actual commits (incl. follow-ups), RISK triggers by category, 누락/초과 list, code-zero-change tasks (→ separate [검증] entry).
6. Build consolidated batch entry: from in-memory accumulator → ONE [코드-수정] (batch: tasks N..M) entry per change-history slim schema (코드 블록 생략, 연관 commit SHA 참조). For any code-zero-change task, build a separate [검증] entry.
7. Single footer append + log commit: Read -implementation-plan.md once → Edit (append batch entry + 검증 entries) → git add <slug>-implementation-plan.md → git commit -m "[log] all tasks: <one-line summary>".
8. Cleanup: nothing for inline mode (no buffer dir). Subagent path cleans .intent-locked/changelog-buffer/<slug>/ separately — see subagent-driven skill §2-4.

This Phase 3 ordering is the single source of truth for inline mode. Subagent mode uses the same Phase 3 logic but reads manifests from the buffer directory instead of in-memory accumulator (per subagent-driven §1 — 매니페스트 종합. §2 는 구현 요약 메시지다).

memory-fallback mode

Phase 1 — Per code edit:

1. Before-snapshot: Read the target file → capture the original code for the affected line range. Hold in memory.
2. Risk check: Run risk-annotation 3-checklist.
3. Apply edit: Edit/Write (with RISK comments).

(Repeat. Track (file:line, before, after, risk_categories) tuples in memory.)

Phase 2 — Once per task, AFTER all edits + tests pass: 4. Batched log: Read plan ONCE, append ONE consolidated [코드-수정] entry, Edit ONCE. Use in-memory snapshots for 변경 전 / 변경 후. 5. Commit if possible (some plans skip).

Trivial-Edit Exception (skip full discipline for tiny changes)

For changes that meet ALL of the following criteria, you MAY substitute a "trivial" path:

• Edit affects ≤ 3 lines
• No logic change (comments / docstrings / typos / unused-import cleanup / import reordering / whitespace only)
• risk-annotation 3-checklist returns 0/3 triggers (no side-effect / breaking / race signal)

When trivial:

1. Skip before-snapshot — irrelevant in both modes (git-fast doesn't need it; memory-fallback skips because no full block will be logged)
2. Risk check still runs to confirm 0/3
3. Apply edit runs as usual (typically no RISK comment needed since 0/3)
4. Log writes a trivial entry (no git diff extraction needed) instead of the full schema:

### [YYYY-MM-DD HH:MM] [코드-수정] (trivial)
- **id**: CH-YYYYMMDD-NNN
- **이유**: <one-line reason, e.g. "타이포 수정 (witdraw → withdraw)">
- **무엇이**: <file:line>

No 영향범위, no 위험 카테고리, no before/after code blocks.

git-fast mode: trivial 편집이라도 task당 1 commit은 반드시 유지. 다음 task의 git diff HEAD -- <code> 가 깨끗하게 이번 task만 포함하려면 이번 task가 commit으로 닫혀야 함. "trivial이니 commit 생략"은 다음 task의 변경이력 정확성을 깨뜨림. (memory-fallback 모드는 commit 선택사항 그대로.)

If ANY criterion is uncertain → fall back to full discipline. Trivial is a fast path, not a shortcut for "anything that looks small".

Process Flow

digraph exec_flow {
    "Load <slug>-implementation-plan.md" [shape=box];
    "Critical review,\nraise concerns?" [shape=diamond];
    "Discuss with user" [shape=box];
    "Mode check\n(git-fast vs memory-fallback)" [shape=box];
    "Create TaskCreate" [shape=box];
    "Pick next [ ] task" [shape=box];
    "TDD: write failing test" [shape=box];
    "Run test → FAIL" [shape=box];
    "More edits in task?" [shape=diamond];
    "[memory-fallback]\nRead target file\n(before-snapshot)" [shape=box];
    "risk-annotation 3-checklist" [shape=box];
    "Apply Edit (with RISK comments)" [shape=box];
    "Run tests for this task" [shape=box];
    "All pass?" [shape=diamond];
    "[git-fast] git diff HEAD -- <code>\n→ extract before/after" [shape=box];
    "BATCHED LOG: ONE [코드-수정] entry\nfor whole task\n(Read+Edit 구현계획서.md once)" [shape=box];
    "[git-fast] accumulate entry\nIN MEMORY (plan.md untouched)" [shape=box];
    "[git-fast] git add <code> ONLY\n+ git commit (code-only task commit)" [shape=box];
    "[git-fast] Phase 3 (all tasks done):\nONE batch entry → append plan.md once\n→ [log] commit" [shape=box];
    "[memory-fallback] Commit if possible" [shape=box];
    "Mark task [x]\n(TaskCreate list — NOT plan.md)" [shape=box];
    "All tasks done?" [shape=diamond];
    "Fix and retry" [shape=box];
    "Use finishing-a-development-branch" [shape=doublecircle];

    "Load <slug>-implementation-plan.md" -> "Critical review,\nraise concerns?";
    "Critical review,\nraise concerns?" -> "Discuss with user" [label="yes"];
    "Discuss with user" -> "Mode check\n(git-fast vs memory-fallback)";
    "Critical review,\nraise concerns?" -> "Mode check\n(git-fast vs memory-fallback)" [label="no"];
    "Mode check\n(git-fast vs memory-fallback)" -> "Create TaskCreate";
    "Create TaskCreate" -> "Pick next [ ] task";
    "Pick next [ ] task" -> "TDD: write failing test";
    "TDD: write failing test" -> "Run test → FAIL";
    "Run test → FAIL" -> "More edits in task?";
    "More edits in task?" -> "[memory-fallback]\nRead target file\n(before-snapshot)" [label="yes\n(memory-fallback)"];
    "More edits in task?" -> "risk-annotation 3-checklist" [label="yes\n(git-fast — skip Read)"];
    "[memory-fallback]\nRead target file\n(before-snapshot)" -> "risk-annotation 3-checklist";
    "risk-annotation 3-checklist" -> "Apply Edit (with RISK comments)";
    "Apply Edit (with RISK comments)" -> "More edits in task?";
    "More edits in task?" -> "Run tests for this task" [label="no — task edits done"];
    "Run tests for this task" -> "All pass?";
    "All pass?" -> "[git-fast] git diff HEAD -- <code>\n→ extract before/after" [label="yes (git-fast)"];
    "[git-fast] git diff HEAD -- <code>\n→ extract before/after" -> "[git-fast] accumulate entry\nIN MEMORY (plan.md untouched)";
    "[git-fast] accumulate entry\nIN MEMORY (plan.md untouched)" -> "[git-fast] git add <code> ONLY\n+ git commit (code-only task commit)";
    "All pass?" -> "BATCHED LOG: ONE [코드-수정] entry\nfor whole task\n(Read+Edit 구현계획서.md once)" [label="yes (memory-fallback)"];
    "All pass?" -> "Fix and retry" [label="no"];
    "Fix and retry" -> "Apply Edit (with RISK comments)";
    "BATCHED LOG: ONE [코드-수정] entry\nfor whole task\n(Read+Edit 구현계획서.md once)" -> "[memory-fallback] Commit if possible";
    "[git-fast] git add <code> ONLY\n+ git commit (code-only task commit)" -> "Mark task [x]\n(TaskCreate list — NOT plan.md)";
    "[memory-fallback] Commit if possible" -> "Mark task [x]\n(TaskCreate list — NOT plan.md)";
    "Mark task [x]\n(TaskCreate list — NOT plan.md)" -> "All tasks done?";
    "All tasks done?" -> "Pick next [ ] task" [label="no"];
    "All tasks done?" -> "[git-fast] Phase 3 (all tasks done):\nONE batch entry → append plan.md once\n→ [log] commit" [label="yes (git-fast)"];
    "All tasks done?" -> "Use finishing-a-development-branch" [label="yes (memory-fallback)"];
    "[git-fast] Phase 3 (all tasks done):\nONE batch entry → append plan.md once\n→ [log] commit" -> "Use finishing-a-development-branch";
}

When to Stop and Ask for Help

STOP executing immediately when:

• Hit a blocker (missing dependency, test fails repeatedly, instruction unclear)
• Plan has critical gaps preventing the next task
• A 위험 카테고리 is genuinely ambiguous AND the trigger seems significant
• Verification fails after two retries

Ask the user rather than guessing.

When to Revisit Earlier Steps

Return to Step 1 (Load and Review Plan) when:

• The user updates the plan based on your feedback
• A fundamental approach in the plan needs rethinking (e.g., chosen library doesn't fit, an FR was misread)
• Mid-execution discoveries invalidate later tasks

Don't force through blockers — stop and ask. The plan can be wrong. If it is, route the change through change-propagation so -implementation-plan.md is updated coherently before resuming.

Anti-Patterns

Red Flags

Step 3: Complete Development

After all tasks complete and verified:

• Final step: invoke finishing-a-development-branch — 테스트 자동 검증 + 종료 메시지 (v1.1.14 슬림화). AskUserQuestion 게이트 X, 사용자가 직접 git/gh 명령 실행.

Remember

• Review plan critically before starting
• Pick mode (git-fast vs memory-fallback) at task-start mode-check; do not switch
• Follow plan steps exactly
• Per-edit discipline: risk-check → apply (memory-fallback adds before-snapshot Read upfront)
• Per-task discipline (git-fast): tests pass → git diff → accumulate in memory → commit code only → mark task done. The batched log is appended and committed once in Phase 3, not per task
• Per-task discipline (memory-fallback): tests pass → batched log → commit if possible → mark task done
• Don't skip verifications — if a step says "run X, expect Y", run X and confirm Y
• Reference skills when the plan says to (e.g., "use risk-annotation here")
• Never start implementation on main/master without explicit user consent
• Ask when blocked

Related Skills

• risk-annotation — invoked on every code edit for the 3-checklist
• change-history — invoked on every code edit for the [코드-수정] entry
• change-propagation — invoked when an in-flight insight requires plan/spec edits
• subagent-driven — recommended subagent path (slim 2-stage + main post-processing)
• subagent-driven-development — upstream original subagent path (3-stage, kept for compatibility)
• finishing-a-development-branch — final wrap-up after all tasks

Critical / Non-critical 판정 룰 (v2.3.5+)

execute-plan 실행 흐름의 핵심 UX 룰. 사용자가 모드 (inline / subagent) 를 선택한 시점부터 메인은 진행 위임으로 간주하고, critical 케이스만 재질문 한다.

룰 1: Critical 케이스 — 사용자 재질문 mandatory (AskUserQuestion 강제)

룰 2: Non-critical 최적화 — 자율 진행 (게이트 X)

룰 3: 모드 선택 = 사용자 위임 신호

사용자가 inline / subagent 모드를 선택한 시점부터, 그 모드에 내포된 진행 방식 (병렬 / 묶음 / 자동 진입) 은 묵시 동의로 간주한다. 사용자는 모드 선택 후 백그라운드 작업으로 이동할 수 있어야 한다. 모드 진행 중 추가 게이트는 룰 1 (critical) 에 해당하지 않으면 차단.

룰 4: BLOCKED 자가 복구 우선

inline mode 의 task 실행 중 의도 모호 발견 시:

• plan 재독 + self-correct 시도 (최대 3회)
• 3회 실패 시에만 룰 1 의 마지막 케이스로 사용자 재질문 (AskUserQuestion fire)

→ 안전성은 보존, non-critical 결정 자체를 안 만든다.

사용자 질문 = AskUserQuestion 도구 (v2.3.5+)

룰 1 (critical 7 케이스) 재질문은 반드시 AskUserQuestion 도구 로 호출. prose 자연어 질문 금지.

• yes/no 도 choices: [yes, no] AskUserQuestion
• 다중 옵션은 choices enum
• 자유 응답 필요 시 dummy choice [알겠음] + question 본문에 "자유 응답" 명시
• 알람 시스템 (repeat-alert.sh 4-layer) 의 Notification.elicitation_dialog 매처 fire — 사용자 백그라운드 작업 시 OS 알람 catch

prose 질문 좁은 예외:

• 자유 텍스트 / 긴 응답 요구 (brainstorming open question)
• 사용자 응답 직후 확인용 단순 ack (그래도 AskUserQuestion yes/no 권장)
• 질문 아닌 상태 보고 / 진행 알림

본 룰은 프로젝트 CLAUDE.md 의 글로벌 "AskUserQuestion 도구 우선 (v2.3.5+)" 룰의 skill body 측 cross-reference.

--no-ask 플래그 (v2.5+) — 짧은 reference

본 skill 흐름은 AskUserQuestion 호출이 본문에 명시 X (clarifying Q 자체가 prose default). --no-ask 플래그 진입 시 추가 분기 없음 — 본문 그대로 도구 호출 0 보장.

단 내부 escalation (BLOCKED 자가복구 실패 / critical 7 재질문 / Other 모호 응답) 에서도 도구 호출 0 보장. 자세한 룰은 skills/brainstorming/SKILL.md 의 ### 예외 — \--no-ask` 플래그 (v2.5+)` 답습.

Anti-Patterns (v2.3.5)