Panama/user/agents/skills/ticket/SKILL.md

---
name: ticket
description: End-to-end Jira ticket workflow — fetch a ticket into .claude/docs/epics/, write a plan, implement it with clean commits, run pre-mr-review to convergence, and write the MR doc. Use when the user gives you a Jira ticket key (e.g. KACP-11111) to work, or asks to plan/implement/wrap up a ticket.
disable-model-invocation: true
---

# Ticket Workflow

Turns a Jira ticket key into: a saved ticket record, a reviewed plan, implemented and
committed code, a converged `pre-mr-review` audit, and an MR doc ready to paste into
GitLab/GitHub. This skill is user-level (`~/.agents/skills/ticket/`) and works the same
way in any repo that has a `.claude/docs/` directory and a `pre-mr-review` skill.

Invoked as `/ticket KACP-11111`. The ticket key is passed as the skill's arguments. Called
again later with the same key, it resumes wherever it left off — see **Phase 0**.

Not to be confused with `/review-ticket`. That skill writes the *developer review* on a
Jira story, the estimate, risk level, and testing tables, as part of authoring a ticket
before anyone builds it. It has nothing to do with reviewing code. The code review in
this skill is Phase 2 step 5 and is performed by a dispatched agent, not by a skill.

## Directory layout this skill maintains

```
.claude/docs/epics/
  <EPIC-KEY>/
    epic.md                      # brief epic context, written once, best-effort
    <TICKET-KEY>/
      resources/
        ticket.md                # title, description, dev review instructions
        <attachments...>         # images, videos, other files as downloaded
        <video>.transcript.txt   # only for videos that got transcribed
        <video>.transcript.srt
      plan.md
      deliverables/                # only for tickets whose output is documents, not code
        <deliverable-slug>/
          <deliverable-slug>.md
          <deliverable-slug>.typ
          <deliverable-slug>.pdf
      proof/                       # captured working feature proof, uploaded to Jira by the user
      mr.md                      # the MR description only, written once pre-mr-review says Ready to Open MR
  tickets/
    <TICKET-KEY>/                # same shape, for tickets with no epic
      resources/...
      plan.md
      deliverables/...
      mr.md
```

## Scripts this skill uses

- `~/.agents/skills/ticket/scripts/jira-fetch-issue.sh <KEY> <OUT.json>` — fetches one
  issue (`fields=*all`, rendered HTML description, field-name map) via `JIRA_BASE_URL` /
  `JIRA_CREDENTIALS`.
- `~/.agents/skills/ticket/scripts/jira-download-attachments.sh <issue.json> <resources-dir>`
  — downloads every attachment on that issue into the given directory, printing
  `filename<TAB>mimeType<TAB>bytes` per file.
- `~/.agents/skills/ticket/scripts/transcribe.sh <media-file> <output-dir> [model]` —
  transcribes via whisper.cpp in podman, auto-detecting NVIDIA/AMD/Vulkan acceleration
  and falling back to CPU on failure. Requires `podman`; uses host `ffmpeg` if present.

Both Jira scripts require `JIRA_CREDENTIALS` (`[email protected]:api-token`, Basic auth)
to already be exported in the environment. `JIRA_BASE_URL` defaults to
`https://ksense-tech.atlassian.net` if unset.

Each Bash tool call runs in a fresh shell that does not inherit state from previous
calls, so a plain `export` the user ran earlier in their own terminal will not show up
here. Before calling either Jira script, always run `source ~/.bashrc 2>/dev/null` in
the same Bash call (chained with `&&` or on the line before), then check the var is
actually set. Only if it's still missing after that should you stop and tell the user
to export it (or point you at wherever it's actually set, e.g. a dotfiles repo) rather
than guessing or prompting for a token inline.

### AMD Vulkan acceleration

`transcribe.sh` uses the whisper.cpp Vulkan image when `/dev/dri` and `vainfo` are
available. On a host with more than one AMD or Intel GPU, select the intended render
node explicitly instead of exposing every DRI device and trusting enumeration order:

1. Identify the GPU PCI address with `lspci | rg -i 'vga|display|3d'`.
2. Map it to a render node with `ls -l /dev/dri/by-path` and resolve the matching
   `pci-<address>-render` symlink with `readlink -f`.
3. Run the helper with the resolved node, for example:
   `WHISPER_VULKAN_DEVICE=/dev/dri/renderD128 ~/.agents/skills/ticket/scripts/transcribe.sh <media-file> <output-dir> [model]`.
4. Verify the runtime log. `Selected acceleration: vulkan` only confirms the intended
   path. Require `ggml_vulkan: Found ...`, the exact requested GPU name, and
   `use gpu = 1` before claiming hardware acceleration worked.

The current whisper.cpp images declare `bash -c` as their container entrypoint. The
helper overrides it with `/app/build/bin/whisper-cli`. An older helper without this
override can fail before Whisper starts with `-f: line 1: /models/...: Permission
denied` and then fall back to CPU.

The accelerated paths remain best-effort on other hosts. The helper falls back to the
CPU image after an accelerated runtime failure. If the user explicitly requested GPU
acceleration, CPU fallback does not satisfy the request. Diagnose the accelerated path,
rerun it, and verify the device log instead of accepting the fallback transcript.

## House style (applies to everything this skill writes or commits)

- No code comments unless the user explicitly asks for one in that spot.
- No em dashes, en dashes, semicolons, or arrow glyphs in commit messages, `ticket.md`,
  `plan.md`, or `mr.md`. Plain punctuation only.
- Commits are `git commit -m "<short imperative message>"` only — no body, no
  co-author line, no `Claude` / `Codex` / `AI` trailer of any kind.
- Never `git push`. Never open an MR/PR. This skill prepares everything needed to open
  one by hand; opening it is the user's call.
- Don't check a checklist box (in `mr.md` or anywhere else) unless you actually verified
  it. Leave it unchecked and say why in the notes rather than guessing.

## Verification tools available

The goal isn't "a plausible-sounding plan" or "code that compiles" — it's a plan and
an implementation that are actually correct, checked against the real system rather
than assumed from the ticket text. Use whichever of these actually verify the thing
in question, before writing `plan.md` (Phase 1) and again whenever Phase 2's
implementation makes a claim that's checkable:

- **The codebase itself.** Don't take the ticket's description of "how things work
  today" at face value. Read the actual models, routes, and components involved and
  reconcile any mismatch. If the ticket says a field works one way and the code says
  otherwise, say so in the plan rather than silently trusting either source.
- **Jira, beyond the single ticket.** Many tickets assume Jira's own data model (custom
  fields, issue types, workflow states) or context that lives on linked issues,
  comments, or the epic rather than on the ticket itself. Search related issues
  (`searchJiraIssuesUsingJql`, issue links, other children of the same epic) and check
  the real field list (the `names` map `jira-fetch-issue.sh` already pulls, or
  `/rest/api/3/field` for the full set) instead of guessing at a custom field's shape.
- **Staging**, via Infisical (see the `infisical-api` / `infisical-user-setup-guide`
  skills for pulling secrets). Staging is fair game to probe directly whenever it
  would settle something real, no need to ask first, that's what it's for.
- **Prod and CI env vars**, at `.claude/docs/env/prod/.env` and
  `.claude/docs/env/ci/.env`. Ask the user for permission before every use, even if
  they granted it last time, say what you want to verify and why. Once granted: use
  the values (e.g. source them for a one-off read-only command) without printing the
  raw file contents or individual secret values into your output. Read-only, always —
  never run anything that writes, mutates, or deletes against prod or CI. If what you
  actually need is a prod database query, that's exactly the kind of thing to ask
  about explicitly rather than assume the file's DB credential is fair game by default.

If something would need access you don't have (a different repo, a system you can't
reach), say so explicitly in `plan.md`'s Open questions instead of silently skipping
the check.

**How to write what you found, in a deliverable.** State it as a plain confirmed
fact: "Confirmed in prod: 67 of 70 companies have `hourlyRate` set." Never describe
the verification method itself, no "a read-only pull," "a read-only pass," "read-only
query," or similar plumbing language. The reader doesn't know or care that you ran a
SQL query, they care what's true. This applies to prod, staging, Jira, and the
codebase equally.

## Deliverable documents (spikes, proposals, anything whose output is a document)

Some tickets (spikes, research, migration proposals, the KACP-22764 kind of ticket)
don't produce code, they produce documents for a PM or another engineer to read. When
a `plan.md` Step produces a document rather than a code change, it becomes its own
subfolder under `<target-dir>/deliverables/<deliverable-slug>/` with three files:

- `<slug>.md` — the source of truth for content. Write this first, get the content
  right before worrying about layout.
- `<slug>.typ` — a Typst version of the same content, laid out for an actual printed
  or PDF-read document, not a mechanical markdown-to-typst conversion. Real headings,
  `table()` for tabular data, and a diagram (via the `cetz` package,
  `#import "@preview/cetz:VERSION"`) wherever a diagram would genuinely communicate
  faster than prose — entity relationships, hierarchies, flows. Don't force a diagram
  in where a bullet list would do. Style is engineering-oriented and readable: nothing
  colorful or flashy, this goes to a technical PM and other engineers.
- `<slug>.pdf` — compiled from the `.typ` file.

**Write for the actual audience, not for yourself.** The reader is a PM or another
engineer who has never seen `.claude/docs/`, doesn't know what `plan.md` or
`ticket.md` are, and doesn't have this repo (or any other local repo) checked out.
Never reference `.claude/docs/` or any local file path in a deliverable's content.
Never say "see plan.md" or "see ticket.md", those are personal working files, not
things a reader can open. Refer to "this ticket" or a plain Jira link, not a local
path. If a fact came from another repo on this machine, state the fact, don't cite
the local checkout path it came from.

**Structure mirrors the ticket, not a narrative.** The PM reads a deliverable to
verify that everything they asked for is in it, and to come back later and re-find
one specific answer. Build the document from the ticket's own structure:

- If the ticket asks direct questions (a spike's "Questions to Answer" table), the
  first section is `Questions and answers`: every ticket question in ticket order,
  each with its priority, a direct two or three sentence answer, and a pointer to
  the section holding the detail. This page is how the reader checks all
  acceptance criteria without reading the rest.
- One section per named deliverable or requested topic, titled with the ticket's
  own words. If the ticket says "status-weighting approach" there is a section
  called "Status weighting"; if it asks how the datamodel changes, the section is
  "Datamodel". Plain flat headings, one level below the title, in roughly the
  ticket's order of importance (schema and calculations early).
- Each section is the artifact, not prose about it: schema changes as real schema
  code in the repo's conventions (e.g. Prisma model blocks), math as formula code
  blocks, mappings as tables, UI as the real mockup screenshots. Current-state
  context earns a sentence or two inside the section that needs it; the section
  states the decision, not the investigation that produced it.
- Sections are short. Cover every question and requirement, spend few words each.
  Depth lives in the code blocks and tables, not in longer paragraphs.
- The voice is a dry engineering spec. Plain declarative sentences, no scene
  setting, no flourishes ("the heart of the model", "the honest story"). A
  correct document that reads glossy costs the reader's trust in it.

**State final decisions, don't narrate the journey.** A deliverable answers "what
goes where and why," not "here's what we used to think, here's what turned out to be
wrong, here's what's resolved now versus still open." No "Corrections made" section
listing earlier mistakes, no "Resolved" / "Still open" split, no "first draft said
X, that was wrong" asides. Figure out the right answer (including asking the user
directly, mid-task, for anything you can't determine yourself) before or while
writing the deliverable, then write the resolved shape as plain fact, the same way
the very first version of a proposal document should read: a clean "stays here,
moves there, and why" description, nothing else. If something genuinely can't be
resolved without more input and truly must ship as an open question, keep it to the
smallest possible list, phrase it as a direct question, and ask the user about it
directly (don't just leave it sitting in the document) rather than defaulting to
"flag everything as open" as a way to look thorough.

**Describe the mock, not how far the implementation went.** A mockup deliverable
should say that a quick UI mockup was made by updating the relevant screens, then
explain what the mock demonstrates. A schema deliverable should present the proposed
schema and migration direction. Never tell the deliverable's audience that the mock
was fully coded, built as a real feature, production-ready, implemented end to end,
or created on a working branch. The code-based mock workflow below is an internal
method for producing accurate screenshots, not part of the deliverable's story.

Process, per deliverable:

1. Write `<slug>.md`.
2. Write `<slug>.typ` from it, per the styling notes above.
3. Compile: `typst compile <slug>.typ <slug>.pdf`. `typst` should already be on PATH;
   if it isn't, tell the user rather than silently skipping the PDF.
4. Actually look at the compiled PDF using the Read tool (it reads PDFs directly, page
   by page for longer documents). Check every page for real layout problems: text or
   a table overflowing a page, an awkward page break splitting a table or diagram,
   cramped or excessive spacing, a diagram that rendered wrong. A successful compile
   only means valid Typst, not that it looks right — actually look.
5. If anything looks wrong, fix `<slug>.typ` and go back to step 3. Repeat until the
   PDF genuinely looks right, not just until it compiles without erroring.

If `.claude/docs/` is tracked by git in this repo (check with
`git check-ignore .claude/docs` — no output means it's tracked), commit a
deliverable's three files together as one commit, same as any other step. If it's
gitignored (as in command-center), these files never show up in git at all, which is
expected and fine — they're meant to be shared manually (Slack, attached to the Jira
ticket, however this team actually hands off docs), not through the MR. Don't try to
force-add gitignored files to work around this without asking first, that's an
existing deliberate house rule, not an oversight.

If a deliverable is a UI mock, capture the UI mock described in **Mocks and datamodel
changes** below rather than drawing a separate wireframe. In the deliverable itself,
describe it only as a quick UI mockup.

## Mocks and datamodel changes: build them for real

When a ticket calls for mocks or datamodel changes (a spike proposing new screens or a
new schema, for instance), don't stop at wireframes or a schema proposal document.
Build it for real, on the ticket's branch. Mark these steps `(mock)` in `plan.md`.

A mock deliverable is **two artifacts**, not one, and they answer different questions.
The code proves the thing is buildable and surfaces the problems a picture hides. The
visual mocks show what it should look like once it's built properly, unconstrained by
what was quick to wire up. Ship both, and don't let either stand in for the other.

- **Datamodel changes**: make the actual schema change (e.g. edit
  `packages/db/prisma/schema.prisma` and generate a migration the normal way for this
  repo) rather than only describing it in a document. The proposal document from
  Deliverable documents above can and should still exist, but it now describes
  something that's actually in the branch, not just a plan for something that might
  be built later.
- **UI mocks**: build the actual screens/components in the app, wired up enough to
  navigate to and look real, not a static image or a markdown wireframe. Where it
  isn't much more work, prefer making it an actually working proof of concept (real
  data flowing through, not a placeholder-filled shell) over a purely cosmetic mock —
  that's almost always more informative for close to the same effort.
  MVP quality is the bar for this half, not polish: real data flowing and a screen you
  can navigate to is what matters, and rough or ugly is fine, because the visual mocks
  below are what carry the intended look.
- **Visual mocks alongside the code, one or two of them.** The built version is
  deliberately rough, so on its own it under-sells the idea to anyone reviewing it.
  Produce one or two polished mocks that aren't constrained by what was cheap to build:
  the layout, spacing, and density as they should actually be. In Claude Code the
  `design` skill produces a canvas of artboards for exactly this; in a harness without
  it, a self-contained HTML page does the same job. These are design intent, not
  implementation promises, so call out anything a mock shows that the code doesn't do
  yet.
- **Scope discipline still applies.** This is a proof of concept, not a production
  feature. Don't chase every edge case and don't fix unrelated pre-existing bugs you
  happen to notice along the way, just implement enough of the real thing to be
  screenshotted and evaluated. If doing it for real would take significantly longer
  than a static mock would, say so in `plan.md` rather than silently scoping it down
  without mentioning the tradeoff.
- **Screenshot the real thing.** Once it's built and running, use the `run` skill to
  get the app up and a browser automation tool (e.g. `claude-in-chrome`) to capture
  the actual screens, instead of drawing a wireframe. Save screenshots under
  `deliverables/<slug>/screenshots/` and the visual mocks under
  `deliverables/<slug>/mocks/`, and embed both in `<slug>.typ` via `image()` when
  building the mockups deliverable. Label which is which. A reader who can't tell a
  built screen from a design mock will read the mock as a promise of what already
  works.
- **Same rigor as any other code.** This is real work on the ticket branch like any
  other implementation step: same commit discipline, included in Phase 2's
  verification pass, and not exempt from `pre-mr-review` just because the ticket is a
  spike.

The `prototype` skill is a different job, not this one. It makes throwaway code for
settling which direction to take, parked on a branch out of main and thrown away after.
Reach for it when the spike's real open question is which of several directions to
build. Once a direction is settled, the deliverable is the two artifacts above, and both
ship with the ticket.

---

## Branch setup — run this before any repo work in Phase 1 or Phase 2

Every ticket gets its own branch, prefixed with the ticket key
(`<KEY>-Title-Case-Hyphenated-summary`, matching this org's existing convention, e.g.
`KACP-22823-Fix-Invalid-Date-In-Retainer-Datagrid`). Do this unconditionally as the
first thing in Phase 1, before fetching or writing anything, not just in Phase 2 —
spikes and plans can turn into real code (prototypes, mockup components) partway
through, and the branch needs to already exist when that happens.

1. Determine the repo's default branch (`main` here; if genuinely unsure, check
   `git symbolic-ref refs/remotes/origin/HEAD`).
2. Find candidate branches for this ticket, local and remote:
   `git branch --list "<KEY>-*"` and `git branch -r --list "origin/<KEY>-*"`.
3. **No matches** — fresh ticket branch:
   - Run `git status`. If there are uncommitted changes, stop and ask before doing
     anything — don't risk carrying unrelated work onto a new branch.
   - If not already on the default branch, check it out.
   - Update it: `git pull --ff-only`. If that fails (local default branch has
     diverged from `origin`), stop and ask rather than forcing anything.
   - Create the new branch off the now up-to-date default branch, named from the
     ticket title (2-6 words, Title-Case-Hyphenated, prefixed with `<KEY>-`).
     `git checkout -b <name>`.
4. **Exactly one match** — this ticket already has a branch:
   - If not already on it: check `git status` first. If there are uncommitted changes
     that don't look like they belong to this ticket, stop and ask before switching.
     Otherwise check it out (`git checkout <branch>`, or
     `git checkout -t origin/<branch>` if it only exists remotely).
   - Compare it to the default branch: `git merge-base <branch> <default>` vs
     `git rev-parse <default>`. If they match, the branch is current off the default
     branch — proceed normally.
   - If the default branch has moved on since the branch's merge-base, don't silently
     merge or rebase anything. Tell the user how many commits the branch is behind
     (and how many commits of ticket work are already on it), then ask
     (AskUserQuestion) what they want: merge the default branch in, rebase onto it,
     proceed as-is, or abandon it and cut a fresh branch instead. Do whichever they
     pick.
5. **More than one match** — don't guess which one is "the" branch. List them (last
   commit date and subject each) and ask the user which to use.

Once this resolves you're on the correct branch, and Phase 1/Phase 2 work happens
there. `.claude/docs/` itself is gitignored in this repo, so which branch you're on
doesn't affect `ticket.md`/`plan.md`/`mr.md` directly — this is about making sure any
actual code (mockup prototypes, spike code, real implementation) lands in the right
place from the start.

## Phase 0 — figure out where this ticket stands

1. Validate the ticket key looks like `[A-Z]+-[0-9]+`. If not, ask the user for a
   correct key.
2. Look for an existing directory for this ticket without hitting the network:
   `find .claude/docs/epics -mindepth 2 -maxdepth 2 -type d -name "<KEY>"`
   (this matches both `epics/<EPIC>/<KEY>` and `epics/tickets/<KEY>`).
3. Branch on what you find:
   - **Nothing found** — this is a fresh ticket. Go to **Phase 1**.
   - **Directory exists, no `plan.md`** — a previous run was interrupted before writing
     a plan. Go to **Phase 1** and regenerate from scratch (re-fetch, overwrite
     `ticket.md`, re-check attachments); it's idempotent and cheap.
   - **`plan.md` exists, no `mr.md`** — ask the user (AskUserQuestion) what they want:
     - Re-fetch the ticket and rewrite the plan from scratch (they want to start over)
     - Proceed to implementing the existing `plan.md` as-is (they reviewed and approved it)
     - Resume implementation (some plan steps are already checked off / some commits
       already exist on the ticket branch — pick up from the first unchecked step)
     - Run `pre-mr-review` now (implementation looks done, just need the audit + MR doc)
     Route to **Phase 1** or **Phase 2** accordingly.
   - **Both `plan.md` and `mr.md` exist** — this ticket looks finished. Tell the user
     `mr.md` already exists at its path and ask whether they want you to refresh it
     (e.g. they made more changes since) or leave it alone. Only re-enter Phase 2's
     verification/pre-mr-review loop if they say the code changed since `mr.md` was
     written. Also fetch the ticket and check whether its type's Jira fields (Phase 2
     step 9) are actually filled; an `mr.md` from before this skill filled Jira
     directly may mean the fields were never written, offer to fill them.

## Phase 1 — fetch, scaffold, and plan

1. Do **Branch setup** above first, unconditionally.
2. Run `jira-fetch-issue.sh <KEY> <tmp-path>` (a scratch path is fine here — you don't
   yet know the final directory). Read the resulting JSON.
3. Determine the epic: `fields.parent.key`, if present. If absent, this ticket has no
   epic.
4. Resolve the target directory:
   - With epic: `.claude/docs/epics/<EPIC-KEY>/<KEY>/`
   - Without epic: `.claude/docs/epics/tickets/<KEY>/`
   Create it and its `resources/` subdirectory.
5. Move/copy the fetched JSON to `<target-dir>/resources/issue.raw.json` for your own
   reference while writing `ticket.md` — this raw file is scratch, not part of the
   deliverable; feel free to leave it (it's harmless context for later) or delete it
   once `ticket.md` is written, your call.
6. If there's an epic and `.claude/docs/epics/<EPIC-KEY>/epic.md` doesn't already exist:
   best-effort fetch the epic issue too (`jira-fetch-issue.sh <EPIC-KEY> <tmp>`) and
   write a short `epic.md` (title + description, converted to markdown, a couple
   paragraphs at most). If this fetch fails for any reason, skip it and continue — it's
   context, not a blocker.
7. Write `resources/ticket.md` by reading the fetched issue JSON yourself:
   - Title, type, status, priority, assignee, epic key (or "None"), and a link
     (`<JIRA_BASE_URL>/browse/<KEY>`).
   - Description: convert `renderedFields.description` (HTML) to clean markdown. If
     empty, say so.
   - Developer review instructions: the field name varies by project and isn't a fixed
     custom field ID. Look at the `names` map in the response for any field whose name
     matches something like "dev review instructions" / "review instructions"
     (case-insensitive substring match), then render that field's value the same way as
     the description. If nothing matches, write "None provided" — don't guess a field.
   - Test cases: same approach for any field whose name matches something like
     "test cases" / "test table" / "working feature proof" / "qa" (case-insensitive
     substring match), e.g. KACP's "Test Cases & Working Feature Proof" field. This
     is part of the ticket's testing section and MUST be captured into `ticket.md`
     whenever it holds anything beyond an empty template. Often it's just the bare
     instruction panel and empty table, note that and move on. But when it has real
     content, that content is part of the implementation and has to be known from
     the start: render every row verbatim as a markdown table under its own
     `## Test cases and working feature proof` heading, keeping the ticket's own
     column headers, and carry any prose or instructions in the field alongside the
     table. These are the scenarios the developer must prove, so Phase 1's plan must
     already say how each row gets proven, Phase 2's verification must actually
     prove each row, and Phase 2 step 9 fills the proof column back into the Jira
     field itself. If nothing matches, write "None provided".
   - Risk mitigation: same approach for any field whose name matches something like
     "risk mitigation" / "risk management" / "risks" (case-insensitive substring
     match), e.g. KACP's "Risk Mitigation" field. Same rule as test cases: an empty
     template gets noted, real content gets captured in full because it shapes the
     implementation from the start. Render it as a markdown table under its own
     `## Risk mitigation` heading, keeping the ticket's own column headers and
     every row verbatim. The PM and Lead Developer write the risks and mitigation
     strategies; implementing those strategies and proving each one is the developer's
     job, so every row needs a real mitigation in the code and its proof filled into
     the Jira field in Phase 2 step 9. If nothing matches, write "None provided".
   - Developer fill-in tables, in general: any ticket table with a column the developer
     is meant to complete (Working Feature Proof, Mitigation Proof, and the like) is
     copied into `ticket.md` in full, with that column left showing where its answer
     goes rather than dropped. `ticket.md` is the record of what the ticket actually
     asks for. Never substitute your own invented test cases or risks for the ticket's,
     in `ticket.md` or in the Jira fields. Your own additional cases are welcome, but
     they go alongside the ticket's rows, clearly marked as additional, never in place
     of them.
   - Sweep for anything else populated: list every key in the `names` map whose field
     actually has a non-null, non-empty value on this issue (jq over `.fields` joined
     with `.names`), and skim any populated field not already captured above. Capture
     the ones relevant to implementing or verifying the ticket; ignore workflow
     plumbing (ranks, sprints boards, reviewer assignments, rich-field duplicates).
     This exists because real content sometimes hides in per-project custom fields
     with unpredictable names — a name-pattern miss must not silently drop content.
   - Any other fields on the ticket that look clearly relevant to implementing it
     (acceptance criteria field, story points, labels, components) are worth a short
     line each; don't dump every custom field verbatim.
8. Run `jira-download-attachments.sh <issue.raw.json> <target-dir>/resources/`. For each
   attachment with a `video/*` mime type, check whether another attachment already looks
   like its transcript (same base filename with `.txt`/`.srt`/`.vtt`, or a filename
   containing "transcript"). Collect any videos with no matching transcript.
9. If there are untranscribed videos, ask the user (AskUserQuestion, one question,
   multiSelect if more than one video) whether to transcribe them now. For each they
   approve, run `transcribe.sh <video-path> <target-dir>/resources/`. Note in `ticket.md`
   under Attachments which videos have a transcript and which were skipped.
   For every video that gets transcribed, also extract frames — ticket videos are
   almost always screen recordings, and the transcript alone misses what was on
   screen (the UI being pointed at, the annotation, the row that's wrong). Extract to
   `<target-dir>/resources/<video-basename>.frames/` with scene detection plus a time
   floor, for example:
   `mkdir -p <frames-dir> && ffmpeg -i <video> -vf "select='gt(scene,0.1)+isnan(prev_selected_t)+gte(t-prev_selected_t\,15)'" -fps_mode vfr <frames-dir>/frame-%03d.png`
   Tune the scene threshold or floor so a typical video yields tens of frames, not
   hundreds (raise the floor for long recordings). Then actually look at the frames
   with the Read tool during research, cross-referencing the transcript's timestamps,
   and treat what's visible on screen as part of the ticket's content the same way
   the transcript is. Skip frame extraction only when the video is confirmed
   audio-only or the user says the visuals don't matter.
10. Now actually understand the ticket in the context of this codebase: read whatever
    source files, tests, or docs are relevant to what's being asked. Use Explore/grep
    as needed — this is normal engineering research, not scripted. Use the
    **Verification tools available** above to check the ticket's own claims against
    reality (codebase, Jira, staging, and prod/CI env with permission) rather than
    taking the ticket's description at face value — this is what makes the plan
    trustworthy instead of just plausible-sounding.
11. Write `plan.md` in `<target-dir>/plan.md` (a sibling of `resources/`, not inside
    it). Structure:
    ```
    # Plan: <KEY> — <short title>

    ## Acceptance criteria
    - [ ] <criterion from the ticket, restated precisely>
    ...

    ## Open questions
    <Anything genuinely blocking or ambiguous that needs the user's answer before or
    during implementation. "None" if there really aren't any — don't manufacture
    questions to look thorough.>

    ## Approach
    <Narrative: what you're going to do and why, which files/modules/functions are
    involved, how it fits the existing patterns in this codebase.>

    ## Steps
    - [ ] <step 1, roughly one commit's worth of work — mark it `(deliverable)` if it
      produces a document via the Deliverable documents process instead of code, or
      `(mock)` if it's a real schema/UI change built to demonstrate a mock rather than
      ship a finished feature, see Mocks and datamodel changes>
    - [ ] <step 2>
    ...

    ## Risks and edge cases considered
    - <edge case> — <how the plan handles it>
    ...

    ## Test plan
    - <how you'll verify each acceptance criterion, including existing test suites to
      run and any new tests to add>
    ```
    Be thorough: address every acceptance criterion, resolve as many open questions as
    you reasonably can by reading the code first, and don't leave logic gaps. Steps
    should be concrete enough that Phase 2 can execute them without re-deriving the
    approach. The Test plan must name every test case `ticket.md` captured and say how
    that exact case gets proven, and the Risks section must name every risk
    `ticket.md` captured and say which code enforces its mitigation. Read the notes
    column of a ticket test case as part of the case, not as commentary: a note like
    "confirm the certificate matches the emailed version" is its own thing to prove.

    **Wide refactors are the exception to one-commit steps.** A wide refactor is a single
    mechanical change whose blast radius fans across the codebase (renaming a column,
    retyping a shared symbol), so one edit breaks thousands of call sites at once and no
    single step can land green. Don't force it into one. Sequence it as expand, then
    migrate, then contract: first add the new form beside the old so nothing breaks, then
    migrate the call sites in batches sized by blast radius (per package, per directory)
    with each batch its own step, then delete the old form once no caller remains. Every
    step stays green because the old form still exists until the last one. Say in the
    Approach that this is what you're doing and why, since the step count looks inflated
    otherwise.
12. Stop here. Tell the user `plan.md` is ready at its path, summarize the approach in
    a couple of sentences, and mention any open questions that need their input before
    you'd implement it. Do not start implementing in this same run — wait for them to
    review the plan (editing it directly if they want) and invoke `/ticket <KEY>` again.

## Phase 2 — implement, verify, and hand off

Entered only when the user has confirmed (per Phase 0) that the plan is approved.

1. Do **Branch setup** above first, unconditionally — even if Phase 1 already did this
   for the same ticket earlier, confirm you're still actually on that branch now (the
   user may have switched branches between runs).
2. Read `plan.md` fresh — the user may have hand-edited it.
3. Work through `plan.md`'s Steps checklist in order. For each step: implement it (a
   step marked `(deliverable)` follows the **Deliverable documents** process above
   instead of writing code; a step marked `(mock)` follows **Mocks and datamodel
   changes** — real schema/UI work, not a static wireframe), then check it off
   (`- [x]`) in `plan.md`, then make one commit for it (or a few, if the step
   naturally splits into independent units). Commit messages are short and imperative,
   describing what changed, following House style above.

   If a step fails in a way `plan.md` didn't predict, and the cause isn't obvious within
   a couple of minutes, call the Skill tool with "diagnosing-bugs" rather than trying
   fixes to see what sticks. Note anything it turns up that changes the plan.
4. Do not run the full verification suite after every commit (checks-at-the-end mode).
   Once every step is implemented and checked off, find and run this project's standard
   verification (check `package.json` scripts for something like `ci:check`,
   `typecheck`, `lint`, `test`, or fall back to whatever the repo's README documents).
   Fix anything broken, committing fixes as their own commits, until it's clean. If you
   can't find any verification command at all, say so explicitly later in `mr.md`
   rather than claiming a build/lint/test pass that never happened. Beyond the standard
   suite, use the **Verification tools available** above for anything the suite
   wouldn't actually catch, e.g. confirming behavior against real staging data via
   Infisical, or a specific prod/CI config question, when that's genuinely what it
   takes to be confident the change works as intended rather than just "looks right."
5. Get an independent code review, from a FRESH agent, before running `pre-mr-review`.

   This step exists because `pre-mr-review` cannot do it. That skill is constitutionally
   read-only: it may not run tests, execute code, probe a database, or run any
   experiment, and its own rules tell it to mark anything unprovable as "Needs
   verification" rather than proving it. So it cannot catch a claim that is plausible on
   the page and false in reality. A reviewer that can actually run things can. It has
   already caught a mitigation that was proven by construction to be wrong, on a branch
   whose own audit had blessed it.

   Order matters and is not just convenience. `pre-mr-review`'s output is a readiness
   verdict that gets pasted verbatim into `mr.md`. Anything that runs after it
   invalidates that verdict by construction, and you end up rerunning it and rewriting
   the handoff. Review first, fix, commit, and only then run `pre-mr-review` over the
   final tree.

   - **Skip this step for genuinely trivial changes**: a copy tweak, a styling fix, a
     one line correction with no logic in it. Run it whenever the change adds or
     modifies a procedure, touches schema or migrations, touches permissions or
     auth, involves concurrency, or has a risk table in its ticket. When unsure, run it.
   - **Always dispatch a NEW agent.** Never reuse an agent from earlier in this ticket
     and never review your own work in your own context. The value here is entirely in
     the reviewer not being the author, so an agent that helped implement or plan the
     change cannot provide it.
   - **Give the reviewer its reading order explicitly**, or it produces noise about
     conventions the project already settled: the epic summary if there is one
     (`.claude/docs/epics/<EPIC-KEY>/summary.md`), then this ticket's `resources/` and
     `plan.md`, then `AGENTS.md`, and only then the diff. Give it the exact commit range.
   - **Tell it to verify rather than suspect**, to try to refute its own findings before
     reporting them, to mark each finding CONFIRMED or PLAUSIBLE, and to give exact
     `file:line` plus a concrete failure scenario. Tell it explicitly not to write,
     commit, push, or run anything destructive.
   - **Point it at the claims already made.** Every "proven by X" already written into
     the ticket's risk or test tables must be re-derived, not taken on trust. A false
     proof claim in Jira is worse than an unproven one, because it stops anyone else
     from checking.
   - **Ask the spec questions explicitly**, or the review only finds bugs in what you
     did write and never notices what you didn't. Three questions, each answered against
     `ticket.md` and `plan.md` rather than the diff alone: what the ticket asked for that
     is missing or only partly done; what behavior is in the diff that nothing asked for;
     and what looks implemented but is implemented wrongly. Have it quote the AC ID or
     the `plan.md` line each finding traces to.

   Then respond to the review, in writing:

   - **Findings are not automatically true.** Verify each one against the codebase
     before acting on it. Reviewers do produce confident wrong answers. Say plainly
     which findings you rejected and why, rather than quietly accepting all of them.
   - **Fix everything real**, each meaningful fix as its own commit. Do not defer a
     known hole to a follow-up ticket unless the user decides that.
   - **When a fix changes a mechanism rather than a line**, write a test that fails
     against the old behavior and passes against the new one, and actually confirm it
     fails by reverting the fix. A test that passes either way proves nothing.
   - **If a finding invalidates something already written into Jira or a deliverable,
     correct it there too.** The code being fixed does not fix the false claim.
   - **Terminate deliberately.** Run the reviewer ONCE on the branch. `pre-mr-review`
     then reviews the whole diff including your fixes and serves as the second pass.
     Only dispatch a second reviewer if a fix changed a mechanism, not for line level
     fixes, and never loop "review until clean."

6. Confirm this project actually has a `pre-mr-review` skill (`.claude/skills/pre-mr-review/`
   in the current repo). If it doesn't, stop here, tell the user implementation and
   local verification are done but this repo has no `pre-mr-review` skill to run, and
   let them decide how to proceed.
7. Invoke the `pre-mr-review` skill. Read its verdict.
   - **Ready to Open MR**: continue to step 8.
   - **Almost Ready / Not Ready Yet**: fix what it flagged (each meaningful fix as its
     own commit), then invoke `pre-mr-review` again. Repeat until the verdict is Ready
     to Open MR. Don't write `mr.md` before that verdict is reached.
8. Read `~/.agents/skills/ticket/templates/mr.md` — this is the org's MR template,
   copied into this skill so it still works even though the original
   `.claude/docs/mr/template.md` no longer exists in the command-center repo. `mr.md`
   is ONLY the MR description: the filled template plus the pasted pre-MR handoff.
   Jira ticket fields are not written here, they go straight into Jira in step 9.
   Fill it in for real:
   - H1: from the ticket and the actual work done, not the ticket title verbatim if the
     real change ended up narrower/broader.
   - Summary: one short paragraph max. High level only, what changed, not how. This
     is not the place for a list of every file touched.
   - Issue Link: `<JIRA_BASE_URL>/browse/<KEY>`.
   - New ENVs: list any env vars actually introduced; "None" if none.
   - Additional Notes: a bulleted checklist of the changes you actually made, not a
     dumping ground. Between Summary and this section, every acceptance criterion from
     `plan.md` (or, for a bug ticket, the bug itself) needs to be directly addressed,
     not just gestured at. If there's genuinely unrelated work worth mentioning (e.g.
     an incidental fix along the way), it goes after everything ticket-relevant, still
     as short bullets. Five bullet points max total, ticket-relevant and incidental
     combined. If it doesn't fit in five, it's too much detail for this section, trim
     it rather than running long.
   - Checklist: check only boxes you actually verified (e.g. only check "Build
     verified" if you actually ran a build and it passed).
   - Replace `<!-- Paste the Pre-MR handoff here -->` with the exact content of the
     latest `pre-mr-review` handoff file (the one with verdict Ready to Open MR) —
     paste it verbatim, don't summarize it.

     The handoff section of `mr.md` is GENERATED OUTPUT, not something you author.
     It is the block that states whether the branch is ready to merge, so it must be
     the audit's own words, not a retelling of them. Concretely:

     - Never hand-write a handoff section, and never edit one in place. If it is
       wrong, thin, or stale, fix the handoff file by rerunning `/pre-mr-review`,
       then re-paste.
     - On EVERY rerun, replace the whole existing handoff block with the whole
       regenerated one. Do not patch the copy sitting in `mr.md` to match the new
       head — that is how the two silently diverge, and the version the reviewer
       reads stops being the version the audit actually produced.
     - After pasting, verify the tail of `mr.md` is byte-identical to the handoff
       file. If it isn't, you edited it.
     - The handoff file itself must follow `templates/handoff.md` in the repo's
       `pre-mr-review` skill. If real content doesn't fit that structure, the fix is
       to write it into the handoff file under the right heading, not to bolt an
       extra section onto `mr.md`.
   - Developer responsibilities: if the ticket's dev review instructions impose their
     own deliverables on the developer (e.g. KACP's standing "document three to five
     additional edge cases discovered during implementation, each with its handling
     and test, or its deferral and follow-up story"), satisfy them EXPLICITLY, under a
     heading that uses the requirement's own words, in the JIRA FIELD that owns them —
     not in `mr.md`. In command-center that is the engineer-facing patch notes field
     (`customfield_10260`, "For The Engineer: Patch Notes"). Step 9 writes it.
     Scattered coverage across notes does not count as having answered a named
     requirement, and neither does burying it in the MR description.
   Save this as `<target-dir>/mr.md` (next to `plan.md`, not under `resources/`).

   **`mr.md` is the template plus the pasted handoff, and NOTHING ELSE.** This is a
   hard shape, not a starting point. Its only headings are the template's own numbered
   sections and the handoff's. Do not add narrative sections, however well justified
   they feel: no "how I built it", no per-ticket deep dives, no edge-case writeups, no
   "Jira Ticket Fields" section, no test tables, no root cause analysis. Those live in
   Jira and step 9 puts them there.

   Anything you are tempted to add as a section belongs in **Additional Notes**, as one
   tight bullet. If it will not compress to a bullet, it is Jira content, not MR
   content. A reviewer should be able to read the whole file in about a minute; if it
   has grown past roughly 120 lines including the handoff, it has drifted.
9. Fill the Jira ticket fields directly, by issue type. Rich text fields are ADF:
   render markdown with `python3 ~/.agents/skills/review-ticket/scripts/review2adf.py
   render <file.md>` and PUT via `{"fields": {...}}` to `/rest/api/3/issue/<KEY>`.
   After every PUT, re-fetch and verify the field landed (compare extracted text,
   treating empty `attrs` objects and `localId`/`colwidth`/`width` as noise). The
   field-to-type map below is verified against the project's edit screens, don't PUT
   a field to a type that doesn't carry it.

   **Proof first.** Before filling any proof column, capture working feature proof
   yourself wherever possible: run the app (`run` skill) and screenshot the real
   feature with browser automation, or capture test output for behavior with no UI.
   Save artifacts under `<target-dir>/proof/` with names that match the test-case
   rows they prove. A proof cell references its artifact by filename plus "attached"
   (Gib uploads every attachment, this skill NEVER uploads files to Jira) or names
   the passing test. When proof genuinely can't be captured here (needs prod, a real
   inbox, a flag flip), the cell says exactly what's needed and step 10 lists it for
   Gib. A row with no proof and no named gap is missing work, not a documentation
   gap: go run the check first.

   **Cap the proof at five files, and aim for two or three.** Gib uploads every
   attachment by hand, so each file has a real cost and a wall of near-duplicate
   screenshots buries the two that matter. Before filling the proof column, pick the
   smallest set that actually carries the evidence and delete the rest from `proof/`.

   - One screenshot can prove several rows at once. A company page that shows the
     navigation, the tabs, and the absent section proves three criteria in one image,
     so prefer it over three separate captures.
   - Prefer text over images wherever the evidence is textual. Command output, a
     config diff, a grep result, or a list of rendered labels all belong in a single
     `.txt` file, which is cheaper to attach and easier to read than a screenshot of
     the same thing. Fold what a dropped screenshot proved into that file rather than
     losing the evidence.
   - Capture as many as you like while working. The cap applies to what survives in
     `proof/` when you fill the Jira fields, not to what you take along the way.
   - Never reference a file in a proof cell that is not in `proof/`, and never leave a
     file in `proof/` that no proof cell references. The two lists match exactly.

   **Bug** (fields on the Bug edit screen):
   - `customfield_10259` For the Engineer: Root Cause Analysis: the actual diagnosed
     cause as a short narrative naming the real files and mechanism, not the ticket's
     theory.
   - `customfield_10263` Precipitating Event: what introduced or exposed the bug and
     when (the commit, upgrade, or change that made it start happening).
   - `customfield_10260` For The Engineer: Patch Notes: changelog-style statement of
     the fix.
   - `customfield_10142` Working Feature Proof: the test-case table (Summary, Steps,
     Expected Results, Working Feature Proof, Notes) with the real scenarios verified
     and the proof column filled.

   **Story** (fields on the Story edit screen):
   - `customfield_10253` Test Cases & Working Feature Proof: ALWAYS fetch and read
     this field, whoever wrote the dev review, and no matter what state it's in.
     Whatever rows it carries are the scenarios to prove: fill the empty Working
     Feature Proof cells of the existing rows in place, never duplicate rows. If the
     field is still a bare template with no rows, add the real scenarios verified as
     new rows. New rows go through `review2adf.py tables <field.json> <rows.md>`,
     which preserves the instruction panels and headers.
   - `customfield_10129` Risk Mitigation: same in-place treatment for the Mitigation
     Proof column.
   - `customfield_10260` Engineer Patch Notes: changelog-style, what changed. This is
     also where the dev review instructions' own developer deliverables go, under a
     heading in the requirement's own words. For KACP that is the standing "three to
     five additional edge cases discovered during implementation", each with how it was
     handled and what covers it. Deliver the number asked for, not more, and pick the
     ones a reviewer most benefits from. This field, not `mr.md`.
   - `customfield_10261` User Story Patch Notes: the same change in user-facing words.
   - `customfield_10142` Working Feature Proof: ALWAYS fill this on a Story, never
     leave it empty. It renders as its own panel in the ticket's testing section, so
     an empty field reads as unfilled testing even when every test-table cell is
     complete (this happened on KACP-23143). At minimum it lists the files staged in
     `proof/` for Gib to attach, one line each saying what the artifact shows, plus a
     pointer that per-row proof lives in the Test Cases table. A headline artifact (a
     demo capture, a before/after pair) leads the list when one exists.

   **Spike** (deliverables, not code): no test or proof fields to fill. The output is
   the deliverables directory, and step 10 tells Gib which files to upload where (the
   ticket, Drive, or both, per the ticket's instructions). Fill `customfield_10260`
   only if the spike actually shipped code.

   Before moving on, re-read `ticket.md` row by row: every test case and every risk
   the ticket carries now has its developer column filled in Jira. Leave none
   unanswered.
10. Tell the user: implementation is committed on `<branch>`, `pre-mr-review` verdict is
   Ready to Open MR, the Jira fields are filled (name which), and `mr.md` is ready at
   its path. Then the manual list, which should only ever be:
   - push the branch, open the MR, and paste `mr.md` in as the description
   - upload the named proof or deliverable files (from `proof/` or `deliverables/`)
     to the ticket, plus anything flagged as proof only Gib can capture
   Remind them nothing was pushed, no MR was opened, and no attachments were uploaded.

## Resuming mid-implementation

If Phase 0 routes here because some steps in `plan.md` are already checked off: check
`git log` on the current branch against the plan's steps to sanity-check they actually
match reality (a checked-off step should have a corresponding commit), then continue
from the first unchecked step. If the plan and the git history disagree, stop and ask
the user rather than guessing which one is right.