Jira Bug-Fix Workflow

End-to-end Jira bug-fix flow; stages 1-6 are read-only. Manual mode (default) requires confirmation between stages.

Prerequisites: PAT/auth follows the jira-read credential contract (env JIRAPERSONALTOKEN, alias JIRA_PAT, or ~/.config/jira-certs/jira-pat.txt); mcp-atlassian is optional. The Git environment is healthy.
Format reference: output templates, the state directory, commit format, and exit scripts are in [reference.md](reference.md).

Triggers and Modes

Mode detection: overlay triggers (「ai-proxy 模式」「AI 代理模式」「切换 ai-proxy」 / "ai-proxy mode" / "switch to ai-proxy") request overlay per workflow-mode-lifecycle — if both auto and overlay appear, overlay+freeze wins. Else contains "自动" / --auto → auto; contains "强制" / "跳过分级" → skip grading (auto); contains "继续修复" / "再次修复" / --retry → re-enter at stage 3; contains "从上次继续" / "恢复" / --resume → resume from checkpoint; otherwise manual.

Unattended proxy exits

When this-run contract or task card records Stage-exit policy: ai-proxy (auto carrier; queue child is sufficient but not required), each manual stop point becomes a proxy checkpoint per ai-proxy-discipline. Thin freeze (verbal trigger ≠ occupancy) lives there. Merge, irreversible, protected-branch, and Jira writeback stay human-only (park + ticket). Any other policy value or none → today's non-proxy behavior.

Stop-point forecast: if this run starts with a frozen contract (queue child with problem + frozen decisions, or independent thin freeze already written), open with a forecast table before analysis — every manual exit × covered-by-frozen-decisions vs will-form-a-new-ticket. If overlay is requested mid-run, after thin freeze output a forecast of remaining exits, then continue the current stage (do not restart from analysis).

Strong Dependencies & Prerequisite Check

Strong dependencies are listed in frontmatter dependencies. After stage 0 passes and before stage 1, scan available skills; any missing → print a structured notice and abort immediately (format in solve-workflow/reference.md). No degradation.

Mode Lifecycle

Core rules live in workflow-mode-lifecycle. "Full flow complete" means stages 0-10 finished normally (including any stage's final termination); failure abort / 🔴 extremely-hard termination / user stop / review-cap intervention-termination all revert to manual. Re-entering auto requires an explicit trigger; implicit continuation ("继续修复", "再改一下") does not reactivate it.

Workflow-specific differences: stage 9 complete / stage 10 merge complete / 🔴 extremely-hard termination (auto) → revert to manual; stage 8 under-threshold rollback keeps the current mode (auto, capped at 2 rollbacks); --retry → reset to manual; --resume → keep the checkpoint's mode.

Queue-child mode (goal-driven-queue dispatch)

When dispatched by goal-driven-queue (explicit queue-child context flag in the invocation — never guessed from ambient signals), this flow adapts: the card's goal condition carries the Jira issue link; its frozen-decisions block supplies stage 0–1; Stage-exit policy rides along (occupancy is the Unattended pointer above, not unique to this flag); open with a stop-point forecast (every manual exit × covered-by-frozen-decisions vs will-form-a-new-ticket). The terminal is PR-open: stop after stage 9 with a record-only closeout — stage 10 (merge + Jira writeback) is deferred to the human (merge authority and external-tracker writebacks are never proxied); the queue's acceptance package carries them as pending follow-ups. Independent use (no flag): overlay/occupancy still follow Stage-exit policy and the Unattended pointer; the PR-open terminal does not apply; closeout stays this skill's stage 9–10 (overlay is not naked auto through merge/writeback).

⚡ Quick Reference (read before executing)

Stage 7: create the branch first; call node-version-discipline before build/lint/tsc. Stage 10 Part C decides whether to run the coverage analyzer per preference/ask.

Auto/manual per-stage differences: [reference.md](reference.md) § Mode Differences Quick Reference.

General Principles

• Investigate before speaking: no verdict without code evidence
• Active questioning: follow clarifying-question-discipline (one question per turn; multi-round until clear; clarify first, do not rush to answer). When domain vocabulary is in play, also follow domain-language-discipline.
• Jira status boundary: engineering only transitions the issue to "已修复" (Fixed); closing / marking verified belongs to QA

Path Selection

Chosen after stage 4's grading; may upgrade, never downgrade.

Upgrading in manual mode requires user confirmation.

State Persistence (interruption recovery)

Resume: when state.json exists, 🤖 auto continues from currentphase; 👤 manual asks whether to resume. Cleanup: on completion set currentphase: "completed". Directory layout and schema: [reference.md](reference.md) § State Directory and state.json.

--retry (stage-3 re-entry): skip 0/1; read the existing 01-jira-info.md; ask once "what was fixed last time / what's the new symptom"; write "this iteration's context" into 02-analysis.md; reset state (currentphase: 3, completedphases: [0,1], clear grade/selectedoption/review*); append -v2/-v3… to the branch name; if root cause is still unclear, prefer instrumentation debugging.

Stage 0: Prerequisite Check

Any failure aborts the flow.

1. Detect the mode (including --force / --resume / overlay). Overlay triggers request thin freeze then occupancy per ai-proxy-discipline. Before the first persistent write (state.json, docs, or code), load git-worktree-discipline (worktree gate + optional isolation); then write the mode to state.json
2. Resolve credentials per jira-read (do not abort solely because mcp-atlassian is missing). Prefer MCP jiragetissue for a connectivity check when that tool exists; if it does not, degrade to local jira-read cache. Abort only when issue data cannot be obtained at all.
3. P0 interception (auto only): P0 → abort, switch to manual
4. Git: 🤖 dirty→stash; 👤 dirty→prompt to handle

Output: [reference.md](reference.md) § Stage 0. On success, proceed directly to stage 1.

Stage 1: Read Jira Info

Call jira-read {JIRA-ID} --live after the jira-read credential chain (degrade to cache → degrade further to manual/abort). Save 01-jira-info.md. Extract: ID, title, priority, status, description, repro steps, expected/actual result, attachments, comments. Output: reference.md § Stage 1. Tools: ✅ mcp / jira-read; ❌ Edit/Write/Bash. Proceed directly to stage 2.

Performance-domain issue (slow / jank / resource growth): run the analysis, optimization, and verification work under perf-optimize-workflow's evidence-gated paradigm (benchmark baseline → evidence gate → one-target iteration → A/B verdict) and fold its conclusions back into this workflow's stages; the Jira orchestration (branch, MR, writeback) stays here. Note: its campaigns create per-project artifacts in the repo (benchmark log + harness, and seeded code-insight/code-optimizer skills) — commit them alongside the fix; the optimize-verify loop additionally requires an environment loop runner (analysis stages always run). Informational reference, not a dependency.

Stage 2: Understanding Alignment

Restate the understanding from stage 1 and surface ambiguities; reading code is forbidden. 🤖 skip→3. 👤 must confirm before →3.

Output: problem restatement (no technical judgment) / key elements / ambiguities (one question per turn) / scope breakdown (if applicable, still no code exploration). Format: reference.md § Stage 2; save 02-alignment.md.

Stage 3: Analyze the Problem

Load analysis-core §§1-3; the stage output MUST close with the analysis gate output block (analysis-core §5 — red loop / debug entry / scenario supplements / temporary changes; missing block blocks stage 4). Mapping: {next-stage} = stage 4 "difficulty grading"; {root-cause step} = root-cause analysis; {impact-assessment step} = impact scope; {upstream-eval step} = upstream-dependency fix evaluation.

Workflow-specific differences: ① the industry-wide-issue evaluation is a gate; ② 🚫 no viable fix → report + stop, do not enter stage 5 + write a Jira comment (template in reference.md); ③ existence check ❌ → stop + Jira comment + wait for the user; ④ artifact 02-analysis.md (includes a difficulty pre-assessment).

👤 continue directly into stage 4, append the grading to the end of the output, then ⏸️ pause for confirmation before →5. 🤖 → stage 4.

Stage 4: Difficulty Grading + Mode Decision Gateway

🔴 Extremely hard (any one qualifies)

Root cause unknown | architectural change | data migration | API-protocol change | estimated files >10 or lines >500 | cross-repo / cross-service

Other grades

Files ≤3 and root cause clear → 🟢; 4-10 and mostly clear → 🟡; ≤10 but less clear with a larger change → 🟠

Mode × Grade

Write the grade to 04-grade.md and state grade; declare the path. Template: reference.md § Stage 4. 👤 no separate stop for non-extremely-hard cases; the 🔴 choose-B script is in reference.md. 🤖 non-extremely-hard →5.

Stage 5: Explore & Review Solutions

If the path is still foggy, follow decision-fog-discipline before the solution table. Offer 2-3 solutions (YAGNI). 🤖 auto-select (priority: thorough > best-practice > code quality > smallest change) → review. 👤 ask once if preference is missing, then present the comparison table.

Architecture-boundary precheck (decision order): when a candidate solution crosses process or layer boundaries, answer the precheck before short-term costs (change size / reuse / single-repo) are weighed — (1) runtime initialization location: which process/layer initializes the called capability; (2) boundary legality: would a cross-layer import pull the callee's dependency tree into the caller's bundle graph (bundler static pre-scanning defeats dynamic require/import as a workaround); (3) ownership classification: system vs data/product capability vs the calling layer's positioning. The boundary verdict surfaces with the comparison table and gates auto-mode selection. Methodology: code-design-review Layer A dependency-direction dimension. Single-layer solutions do not trigger this precheck.

Output: list → expanded detail → one comparison table (see reference.md § Stage 5 Solution Comparison) → 03-options.md. 👤 stop after the comparison table.

Review: load staged-review-flow. Mapping: {next-stage} = stage 6; {artifact-sink} = 03-options.md; {extra-dimensions} = none; {batch-overcap-behavior} = mark "review failed (cap)" and move to the next issue. ✅ Read; ❌ Edit/Write/Bash.

Stage 6: Make a Plan

Must include: root-cause/solution recap, architecture (optional Mermaid), file change table, order, test scenarios, impact scope, rollback. Save 04-plan.md.

Exit script: reference.md.

Stage 7: Execute the Plan

Before production edits, follow design-approval-gate (manual: user pass; auto/force: named escape + 留痕).

Figma pixel fidelity: When the issue/plan includes a Figma URL/node or pixel-restore / design-faithful UI intent, load figma-pixel-implement and follow it. Do not restate its methodology here.

Branch: naming and single-/multi-repo flow are in [reference.md](reference.md) § Stage 7 Branch-Creation Details; write 00-branch.md.

Execute strictly per the plan; check off TodoWrite / plan checkboxes item by item as completed. Tag every change // fix [JIRA-ID]. Quality gate: node-version-discipline → ReadLints → typescript-check when a tsconfig exists. 🤖 multi-repo changes and lints per repo, write reports/[JIRA-ID]-analysis.md.

After execution: 🤖 normal→8, 🟠 pause for review; 👤 normal wait for confirmation→8, 🔴 chose B pause without auto-committing. Report → 05-execution.md. For behavior changes follow test-first-discipline; when business logic lacks tests, call test-suite-ensure (mode=advisory) — test-suite-ensure does not satisfy test-first. Exit script: reference.md.

Stage 8: Check & Verify

Output the result only — do not change code. Compare against the Jira repro/expected result, stage 6's plan, tests, side effects, and root cause; use analysis-core §4 for the debug-verify loop. Verification execution follows runtime-verification-discipline (the AI executes verification itself in an environment, and hands a step to the user only at a classified true hard boundary, with the reason stated). When this run implemented from Figma or alignment checking is required, load figma-pixel-verify and follow it for measured pass/fail. Verification-report honesty per staged-review-flow and completion-evidence-discipline. Template: reference.md § Stage 8.

🤖 auto-rolls back on under-threshold results, capped at 2, then pauses. 👤 waits for "通过" (pass) / "返回修复" (return to fix) / "重选方案" (reselect solution). Save 06-verification.md.

Stage 9: Submit PR/MR

Load delivery-discipline and follow it. Supply:

• {commit-context}: type/scope/subject/jira_id (message format in reference.md § Commit Message Format — must include the Jira ID)
• {pr-body-extra}: root cause, solution, files, verification scenarios (≥2 each of functional/boundary/regression), and the Jira link

👤 stop after presenting the delivery plan; the AI executes once confirmed. 🤖 executes directly. Completion output: reference.md § Stage 9 → 07-report.md.

Stage 10: Review & Merge

Present the PR/MR URL (from stage 9). Load feature-branch-closeout for the closeout menu (PR already open → typically merge / keep / continue). Both auto and manual require user confirmation before merging.

Once merge is selected:

1. feature-branch-closeout loads merge-discipline (Part A→B→C→R→D; checklist in that skill's reference.md)
2. Merge (gh pr merge --merge / glab mr merge) → delete the remote fix branch → sync the default branch → delete the local branch
3. Load jira-status-writeback (field map: branch, commit, PR URL, root cause, solution, files, report, verification scenarios); a writeback failure does not block completion

Write 08-merge.md; state current_phase: "completed".

Retrospective (delegate to learn-and-improve)

After stage 10 closeout (merge + writeback, or keep/continue), load learn-and-improve and follow its framework. Do not restate retrospective methodology inline.

Safety Mechanisms (auto mode)

Stash before changing; warn at >10 files or >500 lines; block at >20 files or >1000 lines (requires --force); block on linter errors; review loop capped at 3 rounds; log every automatic decision.

Common Mistakes

Only non-obvious pitfalls are listed here. Merging → merge-discipline; writeback → jira-status-writeback; industry-wide/upstream issues → known-issue-research / upstream-dependency-debug. Rules already stated in the stage body are not repeated.

Batch Fix

Use the jira-fix-queue skill (thin shell: parses the Jira list and enqueues into goal-driven-queue with Engine: jira-fix-workflow; does not loop this workflow or merge).