⚠️ This is a supporting reference module, not the command definition. The canonical /dev:batch entry point (Epic branch → Story branch → Sub-task branch, per branch-hierarchy) is commands/dev/batch.md. That file references this one specifically for the Stall Budget ladder and Error Recovery sections below — it is not a competing implementation. @sequential-workflow may still be invoked directly for a single-Story sequential cycle outside of a full Epic batch.

Sequential Workflow Agent#

A supporting workflow module detailing the per-issue processing cycle, stall-budget ladder, and error recovery used by /dev:batch.

Triggers#

• @sequential-workflow (direct invocation for a single-Story sequential cycle)
• Referenced internally by /dev:batch (commands/dev/batch.md) for Stall Budget / Error Recovery detail

Workflow Cycle#

Phase 1: Issue Selection#

1. Query Story children under the Epic (each Story ' s own Sub-tasks are
   discovered and processed within that Story ' s own cycle — see
   branch-hierarchy: Sub-task ' s parent is Story, not Epic)
2. Filter issues in the New Issues pipeline
3. Sort by priority and issue number
4. Select the first issue

Phase 2: Start Work#

1. Move the issue to the  " In Progress "   pipeline
2. Create branch: feature/{issue}-{slug}
3. Analyze issue requirements (title, body, acceptance criteria)

Phase 3: Implementation#

1. Analyze existing codebase
2. Implement code matching the requirements
3. Write tests (as needed)
4. Verify build and analysis pass

Phase 4: PR Creation#

1. Commit changes (include Closes #{issue})
2. Push branch
3. Create PR (gh pr create)
4. Move issue to  " Review/QA "   pipeline

Phase 5: Code Review Response#

1. Check review feedback
2. ⭐ 변경 요청(CHANGES_REQUESTED) 또는 CI 실패 시: 이슈를 Review/QA →  " In Progress "   로 되돌린다
   (재작업 중임을 보드에 반영). fail-closed find() 로 pipelineId 해석.
3. Add fix commits → re-push → 다시  " Review/QA "   로 이동
4. Wait for approval

Phase 6: Completion and Next Issue#

1. Squash merge PR
2. ⭐ 명시적 Close + 검증 (필수 — auto-close 의존 금지):
   PR base 가 `development`(저장소 기본 브랜치가 아닐 수 있음)면 `Closes #N` 이 발화하지 않는다.
   - STATE=$(gh issue view {N} --json state -q .state); [  " $STATE "   != CLOSED ]  & &   gh issue close {N} --reason completed
   - mcp__zenhub__searchClosedIssues({query: " #{N} " }) 에 없으면 → updateIssue({issueId, state: " CLOSED " })
3. Return to development + git pull --ff-only origin development + submodule sync/update
4. Go back to Phase 1

⚠️ Phase 6 는 GitHub Closes #N 자동 닫힘에 의존하지 않는다. 비-default base 머지는 자동으로 닫히지 않아 이슈가 Review/QA 에 영구 잔류하므로, GitHub state 를 source of truth 로 직접 닫고 ZenHub 동기화를 검증한다(/dev:run Step 8 과 동일 패턴).

ZenHub MCP Usage#

Workspace Info Query (once at session start)#

const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const pipelines = workspace.pipelines;
const repos = workspace.githubRepositories;   // ⚠️ 필드명은 githubRepositories (repositories 아님)

// fail-closed 해석 — 못 찾으면 throw (rename/오타 시 undefined.id 무음 누락 방지)
const pid = (n) = >   { const p = pipelines.find(p = >   p.name === n); if (!p) throw new Error(` ' ${n} '   없음. 라이브: ${pipelines.map(p = >   p.name).join( " ,  " )}`); return p; };
const newIssues = pid( " New Issues " );
const inProgress = pid( " In Progress " );
const reviewQA = pid( " Review/QA " );

Issue Search#

mcp__zenhub__searchLatestIssues({ query:  " SALES-001 "   })

// Query issues by pipeline
mcp__zenhub__getIssuesInPipeline({
  pipelineId: newIssues.id,
  repositoryIds: [repos[0].id]
})

Pipeline Move#

// In Progress
mcp__zenhub__moveIssueToPipeline({
  issueId:  " {graphql_id} " ,
  pipelineId: inProgress.id
})

// Review/QA
mcp__zenhub__moveIssueToPipeline({
  issueId:  " {graphql_id} " ,
  pipelineId: reviewQA.id
})

Note: Pipeline ID and Repository ID differ per workspace. Do not hardcode them.

Branch Strategy#

# Create issue work branch
git checkout development
git pull origin development
git checkout -b feature/{issue_number}-{short-slug}

# Example
git checkout -b feature/1415-sales-kpi-summary

Commit Rules#

# Korean commit message + Gitmoji
feat(console): ✨ 매출 KPI 요약 카드 구현 (#1415)

- 총 결제액 표시
- 총 판매량 표시
- 전월 대비 증감률 표시

Closes #1415
Co-Authored-By: Claude Opus 4.5  < noreply@anthropic.com >

PR Creation Rules#

gh pr create \
  --base development \
  --title  " feat(console): ✨ 매출 KPI 요약 카드 구현 (#1415) "   \
  --body  " $(cat  < < ' EOF ' 
 ## Summary
- Implement sales KPI summary card component
- Display total payment amount and sales volume
- Calculate month-over-month growth rate

## Related Issue
Closes #1415

## Test Plan
- [ ] Verify KPI card rendering
- [ ] Verify data binding
- [ ] Validate growth rate calculation

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
) "

Stop Conditions#

The workflow automatically stops when:

1. Build failure: melos run analyze or flutter build failure
2. Test failure: Unit test or widget test failure
3. Code review issue: Major fix request raised
4. User request: Explicit stop request

Per-story scope, not Epic scope. A single Story getting stuck must NOT halt the whole Epic. When a Story exhausts the stall ladder below, it is marked BLOCKED('unstuck_exhausted') and the batch continues to the next Story (idempotent resume covers it later — see batch.md Phase 0).

Stall Budget — 3-Rung Ladder#

On repeated failure within one Story, climb the ladder rung by rung. Do not loop rung 1 forever.

Rung 1 — Same-strategy retry (existing):
  Re-run the same fix at most a small bounded number of times
  (e.g. lint/format/build auto-fix as in Error Recovery below).

Rung 2 — Lateral reframe (on repeated IDENTICAL failure):
  When the SAME failure repeats (judged SEMANTICALLY, not by string
  diff — see note), escalate to /dev:unstuck solo with an affinity
  persona from the symptom table below. A reframe ≠ a retry: the next
  move must differ in KIND from what already failed.

Rung 3 — BLOCKED + CONTINUE (보드 반영 포함):
  횡적 reframe 도 소진되고 Story 가 여전히 안 풀리면 BLOCKED( ' unstuck_exhausted ' )
  표시 후 배치를 CONTINUE 한다(Epic 전체 중단 금지). 동시에 차단을 보드에 반영한다:
    - 차단 의존이 있으면 createBlockage({blockedIssueId, blockingIssueId}) 로 기록
    - 활성 작업과 구분되도록 holding 컬럼(Sprint Backlog)으로 이동 — In Progress 에 방치 금지
    - blocked→unblocked 계약은 rules/zenhub-conventions.md  " Blocked Issue Contract "   참조
  (BLOCKED Story 는 Phase 0 멱등 resume 으로 나중에 재시도된다.)

Rung 2 — Affinity Symptom Table#

Pick the starting persona by the meaning of the stuck state (default CONTRARIAN). Persona definitions live in plugins/cc-spec-clarity/references/LATERAL_PERSONAS.md — do not restate them here.

LLM-SEMANTIC, never lexical. "Is this the SAME failure again?" and "which symptom is this?" are judged by meaning, not whitespace/token overlap of error text. The audience is Korean-first: Korean has no word boundaries and attaches 조사, so two log lines describing one blocker can share almost no tokens ("빌드가 실패" vs "빌드는 또 실패"). Match by what is actually stuck, not by characters.

/dev:unstuck returns options, not a verdict — it does not decide for the workflow. If a reframed next move is actionable, the workflow may try it (that counts as Rung 2, still bounded); if none unblocks the Story, proceed to Rung 3.

Error Recovery#

On Build Failure (Rung 1)#

# Analyze error
melos run analyze 2 > & 1 | head -50

# Common fixes
melos run format
melos run build

Tooling degradation (GD-01): melos 부재 시 dart analyze / dart format / flutter test 를 직접 호출하는 것으로 폴백한다(= /dev:run "Step 0 Degradation Contract"). 빌드 도구 미설치는 안전 위반이 아니라 degrade + 경고 대상 — command -v melos 로 먼저 확인하고 분기하라.

On Repeated Identical Failure (Rung 2)#

# Same failure (semantically) after Rung 1 retries → lateral reframe
/dev:unstuck solo  < affinity-persona >     # see Affinity Symptom Table

On Stall Exhausted (Rung 3)#

# Reframe didn ' t unblock → mark BLOCKED and move on
mark Story BLOCKED( ' unstuck_exhausted ' ); CONTINUE to next Story  # Epic NOT halted

On Merge Conflict#

git fetch origin development
git rebase origin/development
# After resolving conflicts
git rebase --continue

Checklist#

Verification items for each issue:

• Understand issue requirements
• Create branch
• Implement code
• Pass build/analysis
• Create commit (include Closes #)
• Create PR
• Move pipeline (In Progress → Review/QA)
• Address review feedback
• Switch to next issue

Related Agents#

• @console-feature - Console feature patterns
• @bloc - BLoC state management
• @flutter-ui - UI component implementation
• @test - Test writing