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

name, description, disable-model-invocation

name	description	disable-model-invocation
ticket	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.	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.

    Then classify the ticket before drafting anything, and say the classification out loud so Gib can override it. Borrowing the grilling skill's paths: bounded is a well-scoped change to a flow that already exists in this repo, and architectural is a new subsystem, a schema change other stories depend on, or anything that alters an interface neighbouring work relies on. Bounded is the common case and goes straight to step 11. For architectural, call the Skill tool with "grilling" and resolve its frontier with Gib BEFORE writing plan.md — those questions get answered in conversation, not deferred into the plan's Open questions section, because an architectural plan built on a wrong assumption is the expensive one to discover in Phase 2. Bounded measures the repo, not your familiarity: if the flow being changed isn't already there to read, it isn't bounded. In doubt, take the heavier path.

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.

    Where the shape is in question, borrow the vocabulary. When the plan has to decide how deep a module should be, where a seam belongs, or what an interface exposes — not merely which file to edit — call the Skill tool with "codebase-design" and use its terms in the Approach section. review-ticket already does this when it writes the dev review; this is the same judgment made again, with code about to be written for real.

    The Test plan is a design decision, not a formality. Beyond the cases ticket.md already captured, call the Skill tool with "tdd" to decide which additional tests are worth writing, where the seam under test goes, and whether a mock is warranted. That judgment is what keeps this section focused instead of padded: a test plan listing one case per changed file is slop, and three tests that can actually fail beat twelve that can't. If the ticket carries automated-test subtasks from its dev review, name them here as the tests Phase 2 writes first.

    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.

   Write the test first for steps that carry real logic, meaning a router procedure, a derivation, a permission or authorization check, a migration, or a state machine. For those, call the Skill tool with "tdd" and get a failing test before the implementation. A step covered by an automated-test subtask from the ticket's dev review is always one of these, and that subtask names the behavior the test has to demonstrate. Do NOT do this for UI wiring, a grid column, a copy change, or a styling fix — a test-first cycle there produces exactly the smoke-test padding House style rejects. When unsure whether a step qualifies, ask whether the test could ever fail for a reason worth knowing about. If it couldn't, skip it.

   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.

   Before saving, call the Skill tool with "unslop" and apply its pattern detection to the Summary and Additional Notes ONLY: puffery, superficial -ing phrases, "not just X but Y", vague attributions, rule-of-three padding. The pasted handoff is generated output and is never edited, per the rule above. Skip unslop's "Adding soul" section too — an MR description wants plain and factual, not voice. Henry reads every one of these, and prose that reads as machine-generated costs the MR its credibility before anyone looks at the diff.

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.

   Same prose bar as mr.md. Every field authored here is read by the Lead and the PM. Run the unslop skill's pattern detection over the markdown before rendering it to ADF, skipping its "Adding soul" section — Jira fields want plain, factual, and specific. This does not apply to proof cells, which are references to artifacts and test names rather than prose.

   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.