jira-task-done

name	jira-task-done
description	Complete a Jira task — generates a summary, transitions the issue to Done, and posts to Jira. Triggers: jira-task done, complete task; 작업 완료, 태스크 완료.
user-invocable	false
argument-hint	<TASK-ID>
allowed-tools	["Read","Write","Bash","Glob","Grep"]

jira-task-done: Complete a Jira Task

Language Rule: 프로젝트 CLAUDE.md의 Conventions 섹션 참고 (한국어 출력, Jira 코멘트 제목은 영어).

Prerequisites

• A feature branch feature/<TASK-ID> must exist with commits
• Jira 자격증명 설정됨 (skills/_shared/jira-cli.md)

Workflow

Jira 호출은 python3 "<scripts>/jira-cli.py" … (규약: skills/_shared/jira-cli.md). 호출 prompt가 <scripts>/ 절대 경로를 줬으면 그대로 쓰고, 없으면 skills/_shared/script-lookup.md로 SCRIPT_NAME="jira-cli.py" 1회 해석.

Step 1: Verify Context

Check for .jira-context.json to get the active task context. If TASK-ID is provided as argument, use that instead.

completedSteps에 "merge" 또는 "pr"가 있으면 본 단계는 컨텍스트만으로 충분 — git 호출 불필요. 둘 다 없으면 (예외 경로: 사용자가 merge/pr 없이 done을 호출) 그때만 git branch --list "feature/<TASK-ID>"로 브랜치 존재 확인.

Step 2: Fetch Current Issue Status

Cache-first: .jira-context.json의 cachedIssue를 먼저 확인 (CLAUDE.md "Issue Cache" 참고). hit이면 호출 생략하고 캐시된 status만 사용. miss이면 python3 "<scripts>/jira-cli.py" get <TASK-ID> 호출 (압축 JSON의 summary/status/issuetype/assignee) 후 cache 갱신. 단 done 단계는 상태 전이 직전이므로 사용자가 신선도가 의심되면 cache 무시하고 재조회할 수 있음.

Step 3: Summarize Changes

기본 경로 (merge/pr 완료 후 done 호출): git 호출 0회.

merge 단계에서 이미 Jira 코멘트(## Task Merged Locally)에 변경 파일·삽입/삭제 라인 수가 게시되어 있고, plan/design/impl/test 문서에 모든 요약이 있다. Step 2의 cachedIssue 코멘트 또는 PDCA 문서를 그대로 인용한다.

예외 경로 (merge/pr 없이 done 직접 호출): 그때만 squash·merge 형태에 따라 적절한 git 명령으로 stat 1회 조회.

• squash-merged onto base: git show --stat $(git log --grep="<TASK-ID>" -1 --format=%H <base-branch>)
• 일반 merge: git diff --stat <base-branch>..feature/<TASK-ID>
• 판단 기준: <base>..feature/<TASK-ID>가 비어 있으면 squash, 비어있지 않으면 일반.

Step 4: Generate Completion Summary

다음 출처를 우선순위대로 인용해 완료 요약 생성 (git 재조회 금지):

1. .jira-context.json의 cachedIssue 코멘트 중 ## Task Merged Locally 또는 ## Pull Request Created (변경 파일/라인 수)
2. docs/approach/<TASK-ID>.approach.md (기획 + 설계 요약. 없을 때만 legacy docs/plan/<TASK-ID>.plan.md / docs/design/<TASK-ID>.design.md)
3. docs/test/<TASK-ID>.test-report.md (테스트 결과)

Step 5: Post Completion Report to Jira

Step 5의 요약을 scratchpad md 파일로 쓰고 python3 "<scripts>/jira-cli.py" comment <TASK-ID> @<파일>로 게시:

## Task Completed: <TASK-ID>

**브랜치**: feature/<TASK-ID>
**커밋 수**: <count>개
**변경 파일**: <count>개 (+<추가> -<삭제>)

### Summary
- **Plan**: <기획 요약>
- **Design**: <설계 요약>
- **Changes**: <구현 변경사항 요약>

### Key Changes
<구현된 내용 간단 설명>

Step 6: Transition Issue

Use python3 "<scripts>/jira-cli.py" transitions <TASK-ID> to fetch available transitions, then use python3 "<scripts>/jira-cli.py" transition <TASK-ID> "<id|상태명>" to move the issue:

• Try "In Review" first (common for PR-based workflows)
• If "In Review" is not available, try "Done"
• If both fail, inform the user of available transitions
• 코멘트는 comment 서브커맨드로 별도 (전이에 섞지 않음)

Step 6.5: Verify Transition (SSOT)

Read skills/_shared/transition-verify.md — transition 출력의 status가 SSOT이며 별도 재조회는 하지 않는다. <final-jira-status> 결정 규칙, 실패 정책을 그대로 따르고 결과 status를 Step 8의 <final-jira-status> 인자로 전달.

Step 7: Cleanup MCP Config from Worktree Entry

.jira-context.json의 worktreePath를 읽어 ~/.claude.json에서 해당 경로의 mcpServers를 제거한다. entry 전체는 삭제하지 않고 mcpServers 키만 제거하여 Claude Code의 다른 메타데이터는 보존한다.

스크립트 경로 결정은 Read skills/_shared/script-lookup.md 후 lookup 블록 실행:

SCRIPT_NAME="cleanup-worktree-mcp.py" OUT_VAR="CLEANUP_MCP_PY"
# Read skills/_shared/script-lookup.md and execute its lookup block here
[ -n "$CLEANUP_MCP_PY" ] && python3 "$CLEANUP_MCP_PY" "<worktreePath from .jira-context.json>"

• .jira-context.json에 worktreePath가 없으면 스킵
• ~/.claude.json에 해당 경로 entry가 없어도 스킵 (오류 아님)

Step 8: Update Context & Completion Summary

워크트리의 .jira-context.json과 <repoRoot>/.jira-context.json 양쪽을 공용 스크립트로 갱신한다. 한쪽만 갱신하면 dashboard collector가 worktree-local 파일만 읽기 때문에 done step이 누락된 채 표시된다. 스크립트 경로 결정은 Read skills/_shared/script-lookup.md 후 lookup 블록 실행:

SCRIPT_NAME="jira-context-update.py" OUT_VAR="JIRA_CTX_UPDATE_PY"
# Read skills/_shared/script-lookup.md and execute its lookup block here
python3 "$JIRA_CTX_UPDATE_PY" <TASK-ID> done "<final-jira-status>" \
    "<worktreePath>/.jira-context.json" \
    "<repoRoot>/.jira-context.json"

• <final-jira-status>: Step 6.5에서 transition 출력의 status로 확보한 Jira 실제 status명 (예: "완료", "Done"). transition 시도값을 그대로 쓰지 말 것 — Jira workflow에 따라 다른 이름으로 떨어질 수 있음.
• worktree 경로는 aggregate의 tasks[].worktreePath에서 조회. worktree 컨텍스트가 부재하면(이미 cleaned 등) 해당 인자만 빼고 호출 — 스크립트가 missing 파일을 자동 skip

스크립트는 다음을 일괄 처리한다:

• completedSteps에 "done" 추가 (중복 방지)
• status를 <final-jira-status>로 set
• doneAt에 현재 UTC ISO 8601 (Z suffix) 기록
• cachedIssue.status / cachedIssue.fetchedAt도 함께 갱신 (cachedIssue가 있을 때만)
• aggregate vs worktree 형식 자동 감지 — aggregate에서는 해당 태스크 항목을 제거한다 (done = 생명주기 종료; 이력은 docs/run-log·docs/review-log가 보유. worktree-local 파일은 clean이 worktree와 함께 정리)

아래 형식으로 완료 요약 출력:

---
✅ **Task Done** — <TASK-ID>

- Jira 상태: Done (또는 In Review)
- 완료 리포트 Jira에 게시됨
- `.jira-context.json` 업데이트됨
- 워크트리 MCP config 정리됨 (`~/.claude.json`)

**Progress**: init → start → approach → impl → test → review → merge → pr → **done ✓**

🎉 모든 단계가 완료되었습니다!
---