OPSX Jira Bug-Fix Workflow

The OpenSpec-flavored version of Jira fixing: keeps jira-fix-workflow's end-to-end fix capability while making OpenSpec the source of behavioral truth.

Output templates: see [reference.md](reference.md) for each stage's format.

Positioning

Use this skill for Jira bug fixes worth persisting: not just fixing the code, but also recording root cause, behavior changes, design trade-offs, task lists, verification evidence, and archive results.

Division of labor:

• Jira: problem source, business context, status transitions, and fix comments.
• openspec/changes/<change-name>/: Jira context, root cause, behavioral contract, solution, tasks, verification, and the final archive.
• PR/MR: code delivery, verification evidence, risk notes, and the review entry point.

Not a replacement for plain jira-fix-workflow:

• Quick fixes with no long-term traceability need — use jira-fix-workflow.
• Behavioral contracts, audits, team collaboration, cross-module impact, or long-term traceability — use this skill.

Invocation conventions

• Triggers: opsx-jira-fix, OpenSpec Jira 修复, 规范化修复 Jira, opsx修复Jira, Jira OpenSpec 修复, opsx自动修复Jira, 用OpenSpec修复Jira, opsx-jira-fix-workflow; ai-proxy 模式, AI 代理模式, 切换 ai-proxy
• Overlay: 「ai-proxy 模式」「AI 代理模式」「切换 ai-proxy」 / "ai-proxy mode" / "switch to ai-proxy" request overlay per workflow-mode-lifecycle (overlay+freeze wins if an auto trigger is also present). Thin freeze then occupy per ai-proxy-discipline.
• Auto mode: else a trigger containing "自动" or --auto enters auto mode.
• Force mode: a trigger containing "强制" or --force may skip the difficulty-based stop, but never skips verification or archive checks.
• Continue fixing: a trigger containing "继续修复", "再次修复", "从上次继续", or --retry first locates the existing OpenSpec change, then recovers context from design.md, tasks.md checkboxes, the current Git branch, and PR/MR status.

Strong-dependency skills (frontmatter dependencies; must pass the "Prerequisite skill check" at startup — abort if any is missing):

• staged-review-flow (stage 4 review orchestration; depends on solution-review and code-design-review)
• hybrid-debug / runtime-evidence-debug / browser-debug-toolkit (delegated via analysis-core; stage 2 + stage 7)
• analysis-core (single source for stage-2 analysis methodology: temporary-change gate / instrumentation debug with runtime-evidence-debug as default entry / analysis step skeleton / analysis gate output block / debug-verify loop)
• node-version-discipline (Node version alignment before stage 6 execution verification)
• workflow-mode-lifecycle (auto/manual mode lifecycle), clarifying-question-discipline (hard active-questioning discipline and investigation-first), known-issue-research (stage 2 research routing / known-issue quick search / industry-wide evaluation)
• test-suite-ensure (stage 6.2.5 test-suite ensure: complete and run tests when infra exists; scaffold with user confirmation when it doesn't)
• test-first-discipline (execution: failing-test-first for behavior changes; distinct from test-suite-ensure)
• design-approval-gate (before execution: no production impl without approval; named auto/hotfix escapes)
• delivery-discipline (stage 8: commit + open/update PR/MR after archive; field map via placeholders)
• feature-branch-closeout (stage 8: closeout menu; merge delegates to merge-discipline)
• decision-fog-discipline (before explore solutions: graduate fog / decision tickets first)
• git-worktree-discipline (before stage 1 — first artifact write: worktree gate + optional isolated workspace)
• domain-language-discipline (clarify/analyze: project glossary / CONTEXT.md when domain terms matter)
• merge-discipline (stage 8 merge discipline — after closeout selects merge)
• opsx-workspace-gate (stage 0 OpenSpec workspace and native-skill gate)
• jira-status-writeback (stage 8 post-merge writeback: status transition + fix-comment SOP, single source)
• learn-and-improve (stage 8 retrospective and knowledge sediment)
• figma-pixel-implement / figma-pixel-verify (Figma export-faithful implement + measured verify; required installed; invoke only when Figma UI work is in scope)

Prerequisite skill check

At startup (before stage 0's prerequisite check), check frontmatter dependencies: any missing → print a structured prompt and abort immediately (format: solve-workflow/reference.md).

No-degradation principle: a missing strong dependency means abort — never fall back to a simplified review or debug flow.

Mode lifecycle

Entry, persistence, and exit rules for auto mode, preventing mode stickiness where the user is unaware the AI is still making automatic decisions. The core rules (revert-to-manual / explicit re-entry / implicit continuation never re-activates / batch scenarios) live in the strong-dependency skill workflow-mode-lifecycle (already guaranteed available by the prerequisite check) — not restated here. This workflow's "full-flow completion" = a normal run through stages 0-8 (closing out at stage 8's archive); a failed termination, user-initiated stop, or a review-cap pause all count as flow interruptions and revert to manual.

OpenSpec-specific notes

• After stage 8 archiving completes, mode auto-reverts to manual.
• --retry (continue fixing): resets to manual mode.
• --resume (checkpoint recovery): keeps the mode from the checkpoint.
• An OpenSpec archive failure counts as a flow interruption — revert to 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).

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 per ai-proxy-discipline when policy is ai-proxy — queue child is sufficient but not required); open with a stop-point forecast (every manual exit × covered-by-frozen-decisions vs will-form-a-new-ticket). The terminal is archive + PR-open: archive the OpenSpec change (native to this model, never deferred), then stop at PR open — merge + Jira writeback are 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; the archive+PR-open queue terminal does not apply; closeout stays this skill's native archive-then-stage path (overlay is not naked auto through merge/writeback). When the card supply includes queue relationship-pass notes, write them as ## Related Issues in this change's design.md.

Stage 0: Prerequisite check

Any key check failing pauses the flow — do not enter the fix:

1. Parse the Jira URL / Jira ID; detect mode (manual / auto / force / retry / overlay). Overlay triggers request thin freeze then occupancy per ai-proxy-discipline.
2. Check Jira data is readable: prefer jira-read {JIRA-ID} --live or mcp-atlassian; fall back to local cache; abort if both fail.
3. Check Git status: auto mode may stash; manual mode prompts the user to handle it.
4. OpenSpec workspace and native-skill gate: load opsx-workspace-gate and run its project-root location, openspec/ check, and exact native-OPSX-skill gate; continue this workflow once it passes.
5. Check OpenSpec commands (run from the project root): prefer openspec list, openspec status, openspec validate.
6. When continuing a fix, locate the OpenSpec change first: prefer inferring it from the current branch name; then search openspec/changes/*/{proposal.md,design.md,tasks.md} for the Jira ID; then check the PR/MR description for an OpenSpec change path; if still not uniquely determined, ask the user exactly 1 question to confirm the change name. Once located, recover progress from openspec status --change <name>, openspec show <change-name>, design.md, tasks.md checkboxes, and the current Git branch.

OpenSpec record model

This skill creates no extra runtime directory. A single Jira bug-fix cycle should stay short and clear; engineering records all land in OpenSpec artifacts:

Never create an extra local runtime directory for an OPSX Jira fix. To continue a fix, recover state from the OpenSpec change, tasks.md checkboxes, the Git branch, and PR/MR status.

Stage tool-constraint table

Mode-difference quick table

Stage 1: Read Jira

Before the first artifact write (design.md Jira context), load git-worktree-discipline (worktree gate + optional isolation).

Read the latest Jira data and write it into OpenSpec artifacts as early as possible — never leave it only in chat context.

• Jira ID, title, priority, status
• Description, repro steps, expected result, actual result
• Attachments, comments, historical context
• Data source (live / cache / user-provided)

Once stage 1 completes, an OpenSpec change must be determined or created:

• Auto mode: create a draft change per stage 3's naming rule, and write the Jira context into design.md.
• Manual mode: output a candidate change name and wait for confirmation; do not enter deep analysis before confirmation.
• Continue fixing: reuse the existing change located in stage 0, and merge the latest Jira context into design.md.

Tool limits: Jira API / jira-read allowed; Edit/Write of business code forbidden; Bash commands that change the implementation forbidden.

Auto-advance to stage 2 on completion.

⚠️ Active questioning: follow clarifying-question-discipline (one question per round, multi-round until clear; clarify first, don't rush to answer). When domain vocabulary is in play, also follow domain-language-discipline.

🚩 Red Flag: dumping several ambiguous points on the user in one message (violates the hard discipline, see clarifying-question-discipline) — ask only the single most critical question each time, then ask the next only after getting an answer.

Scope breakdown (optional, when multiple subsystems are involved)

If the Jira issue spans 2+ subsystems or modules (e.g. frontend + backend + database), break it down before entering stage 2:

1. List the subsystems / modules involved.
2. For each, note: does it have an independent root cause; does it need an independent change; does it depend on the main change.
3. Strongly dependent subsystems → merge into one change; independent subsystems → consider splitting into multiple changes, each running its own fix flow.

Write the breakdown conclusion into design.md's Scope section.

Stage 2: Analyze the problem

Single source for analysis methodology: analysis-core. Fix implementation belongs to the execution stage.

Delegate to analysis-core

Load the strong dependency analysis-core and execute its §§1-3. This workflow's mapping (number + name):

• {next-stage} = Stage 3 "Create the OpenSpec change"
• {root-cause step} = step 5; {impact-assessment step} = step 7; {upstream-eval step} = step 6

The stage output MUST close with the analysis gate output block (analysis-core §5 — red loop / debug entry / scenario supplements / temporary changes); a missing block blocks entry to Stage 3.

This workflow's orchestration (kept)

On top of the analysis-core skeleton, this stage also completes:

• Difficulty grading (easy / medium / hard / very hard) and path selection (lean / incremental / full); upgrade the path if scope expands
• Artifact landing spot: write into design.md's Problem Analysis / Root Cause / Impact (a change must already exist — otherwise go back to stage 1)
• Existence ❌ / description mismatch: pause; get user confirmation before writing a Jira comment

Grading and path table:

🚩 Red Flags: skipped existence check; too-shallow root cause; conclusion not written into design.md; ambiguity present but instrumentation not triggered (analysis-core §3); path not upgraded; violates analysis-core / known-issue-research gates

Stage 3: Create the OpenSpec change

🔌 OPSX skills invocation discipline: before delegating to any native OPSX skill in this or later stages, read that skill's SKILL.md first — never call from memory.

Confirm or create the Jira issue's OpenSpec change. If stage 1 already created or reused a change, this stage only validates and completes the artifacts; manual mode must confirm the change name first; auto mode may generate and continue.

• Naming: fix-<jira-id-lower>-<short-topic> (e.g. fix-proj-12167-ai-summary-button)
• Creation: delegate to openspec-new-change (read its SKILL.md; /opsx:new is an entry alias)
• Jira completeness: design.md must include at least Jira Context / Root Cause / Options / Risk / Verification Notes; proposal / delta-spec field details are in [reference.md](reference.md)「Stage 3 Artifact Field Checklist」

Stage 4: Explore & review solutions

If the path is still foggy, follow decision-fog-discipline before the solution table / proposal. Based on stage 2's root cause and stage 3's artifacts, output 2-3 solutions:

• Core idea
• Files / modules involved
• Coverage of the OpenSpec requirement
• Pros, cons, complexity, risk
• Recommended solution

YAGNI: solutions must stay strictly focused on fixing the Jira root cause and covering the delta specs, stripping non-essential features and over-engineering. Any addition beyond the root-cause scope must be explicitly labeled "extra optimization" with a stated reason for taking on the risk.

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.

In manual mode, output the solution table and pause for the user's pick; auto mode picks the best solution automatically.

Load staged-review-flow and execute its full review contract. This workflow's mapping: {next-stage} = Stage 5 "Make the plan"; {artifact-sink} = openspec/changes/<change-name>/design.md; {extra-dimensions} = spec coverage (requirements/scenarios) and Jira status boundary (transition only to "fixed"); {batch-overcap-behavior} = N/A.

🚩 Red Flags (stage 4):
- Review covers only the root cause, without checking spec coverage or side effects
- Skipping comparison and review just because only 1 solution exists

Stage 5: Make the plan

Use openspec/changes/<change-name>/tasks.md as the single task list.

Task requirements:

• Use checkboxes: - [ ] 1.1 ...
• Each item small enough to verify independently.
• Cover every delta-spec requirement and scenario.
• Include necessary test, verification, rollback, OpenSpec archive, and post-merge Jira-writeback steps.
• No TBD, TODO, "handle appropriately", "similar to above", or other non-actionable descriptions.

In manual mode, output the plan and pause; in auto mode, the normal case auto-advances to stage 6 — difficult or very-difficult cases must pause for confirmation.

🚩 Red Flags (stage 5):
- A task item contains TBD, TODO, "handle appropriately", "similar to above", or other non-actionable text
- Tasks don't cover every delta-spec requirement and scenario
- Missing test, verification, rollback, archive, or post-merge Jira-writeback steps
- A task's granularity is too large to verify independently

Stage 6: Execute the fix & verify

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

6.1 Create the fix branch

Branch naming:

fix/jira-fix-<JIRA-ID>

A multi-repo scenario needs a branch per repo, listing each repo, branch, and corresponding OpenSpec change in the PR/MR description.

6.2 Execute tasks

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.

Work through tasks.md in order:

1. Handle only the current task at a time.
2. Before touching business code, confirm the proposal, specs, design, and tasks already exist.
3. Update the checkbox immediately after finishing a task: use StrReplace to flip the corresponding [ ] to [x] in tasks.md — do not batch this until after a group of tasks. Skipping this makes the stage-7 verifier report a CRITICAL false-incomplete.
4. If a spec or design error is found, update that artifact first, then continue implementing.
5. State the reason for any deviation from the plan; if it affects the behavioral contract, return to stage 3 or 4.

Optional tracking comment:

// fix <JIRA-ID>

If the project's convention doesn't accept fix comments, don't force it — but list the fix points in the execution report.

6.2.5 Test-first then test-suite ensure (mandatory, before entering stage 7)

For behavior-changing work, follow test-first-discipline during implementation. Once every tasks.md checkbox is checked, before entering stage 7 verification, this step is mandatory:

Load and call test-suite-ensure, declaring mode=mandatory, scoped to this fix's logic files; a failure or a declined necessary-scaffolding request blocks entry to stage 7. test-suite-ensure does not satisfy test-first.

Stage 7: Check verification

Must cover:

1. OpenSpec validation:

- If the openspec-verify-change skill is detected → read its SKILL.md and delegate verification to it. - If absent → run openspec validate <change-name> or openspec validate --changes directly (a CLI tool call, not a degradation).

Node version alignment (prerequisite): call node-version-discipline to align to the project's declared Node version before running the verification commands below.

1. Engineering verification: tests, lint, type check, build (under the aligned version)
2. Behavior cross-check: confirm every delta-spec requirement and scenario, one by one
3. Jira cross-check: are the repro steps and expected/actual results closed out
4. Side-effect check: are related modules and platforms affected; the verification report must disclose Node (declared vX) ✅/⚠️ not aligned
5. Debug-verify loop: if stage 2 used a debug skill to locate the root cause, verify the fix using that same skill per analysis-core §4 (not tests alone)
6. Figma pixel verify: when this run implemented from Figma or alignment checking is required, load figma-pixel-verify and follow it for measured pass/fail

Verification execution follows runtime-verification-discipline (strong dependency): the AI executes verification itself in an environment, and a step is listed as a manual-verification item only at a classified true hard boundary, with the reason stated.

Label each result per staged-review-flow's verification-report honesty rule and completion-evidence-discipline (no pass claims without fresh current-turn evidence).

Output format: see [reference.md](reference.md)「Stage 7 Verification Results」.

Do not submit a PR on failed verification. The execution record is tasks.md checkboxes, the PR/MR description, and design.md's Verification Notes.

Stage 8: Archive, submit PR, merge & close out

8.1 OpenSpec archive

Pre-archive sync steps:

1. If delta specs exist: call the openspec-sync-specs skill (if installed) to merge delta specs into the main specs/<capability>/spec.md, or let openspec-archive-change prompt for and handle the sync during archiving.
2. Execute the archive: call the openspec-archive-change skill (read its SKILL.md first, then follow its instructions).

If openspec-archive-change fails, do not manually manipulate the openspec/ directory — stop and tell the user to check the OpenSpec installation.

Before merging or preparing to merge, confirm archiving is complete (consistent with merge-discipline Part A):

• When an active OpenSpec change is associated: must archive first (sync main specs + move into openspec/changes/archive/), confirm the diff, then merge; "archive after merge" is never a normal path.
• A PR with no associated change: Part A passes through, archiving not required.

Default: after verification passes, archive first, confirm the openspec/specs/ update and the openspec/changes/archive/ move are in the diff, then deliver and close out.

8.2 Commit & PR (delivery-discipline)

Before delivery, confirm:

• All relevant tasks.md checkboxes are complete.
• OpenSpec artifacts, code changes, and necessary verification notes are all in the diff or PR/MR description.
• Verification passed, or manual-verification items are explicitly listed.

Load delivery-discipline and follow it. Supply:

• {commit-context}: prefer fix(<scope>): <JIRA-ID> <subject>
• {pr-body-extra}: Jira link, root cause, fix approach, OpenSpec change path, changed-file list, verification evidence, risk & rollback

8.3 Branch closeout

Once archiving, delivery, and the diff check are complete, load feature-branch-closeout for the menu (PR / merge / keep / continue). Never declare completion while verification hasn't passed or archiving isn't complete.

Order constraint: archive (8.1) → delivery-discipline (8.2) → feature-branch-closeout (8.3) → on merge, merge-discipline (8.3.1) → execute the merge → Jira writeback (8.4). Choosing keep/continue skips both merge discipline and Jira writeback.

8.3.1 Merge discipline (merge-discipline skill)

On merge (from closeout or a direct user merge command), load merge-discipline and run Part A → B → C → R → D; the pre-merge checklist is in merge-discipline/reference.md. Never implicitly skip.

8.4 Jira writeback (after the merge completes)

Once the PR/MR has merged and the code is on the main branch, write back the Jira status to reflect that the fix has landed. Load the strong dependency jira-status-writeback and follow its SOP for the status transition and fix comment; this workflow supplies the following field map:

The closeout record is authoritative via the PR/MR, Jira comment, and OpenSpec archive result.

8.5 Retrospective (delegate to learn-and-improve)

Once archiving and branch closeout are complete (and Jira writeback when merge ran), load learn-and-improve and follow its framework. OpenSpec artifacts archived through the normal flow are not subject to its sediment-value gate. AI engineering knowledge (AGENTS.md, rules, skills, etc.) uses that skill's carrier decision tree; writing requires an explicit user request first.

🚩 Red Flags (stage 8):
- Submitting a PR before verification passes
- Passing the Jira comment through jiratransitionissue's comment parameter, or transitioning status beyond authority to "closed" / "verified" (SOP: jira-status-writeback)
- Manually manipulating the openspec/ directory after an archive failure
- PR description missing the OpenSpec change path or verification evidence
- Running the analyzer by default under an ask preference without asking the user (see merge-discipline Part C)
- Triggering merge discipline before archive (8.1) completes (order: 8.1 archive → 8.2 delivery-discipline → 8.3 branch closeout → 8.3.1 merge discipline → merge → 8.4 Jira writeback)

Batch OPSX Jira fixes

Use the opsx-jira-fix-queue skill (thin shell: parses the Jira list and enqueues into goal-driven-queue with Engine: opsx-jira-fix-workflow; does not loop this workflow or merge). Relationship judgments the queue already recorded are written here as ## Related Issues in each change's design.md.

Common mistakes

Only this skill's non-obvious pitfalls are listed here. Merge/coverage/archive → merge-discipline; project-root/openspec//native-skill gates → opsx-workspace-gate; Jira-writeback SOP → jira-status-writeback. Rules already stated in the stage body are not repeated.

Minimum success criteria

One complete run: the OpenSpec change has proposal / delta specs / design / tasks via native skills; the PR/MR is created or updated; Jira has a comment and transitioned to "fixed" (if permitted); OpenSpec has been archived (or the PR states the archive strategy and owner); verification evidence is recorded.