gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Drive the ticket skill through the live ticket page

Browse Source
This commit is contained in:
Gabriel Brown
2026-09-22 14:54:05 -04:00
parent fd24b69039
commit 88032490c0
2 changed files with 301 additions and 230 deletions
Download Patch File Download Diff File Expand all files Collapse all files
user/agents/skills/ticket/SITE.md
+145
View File
@@ -0,0 +1,145 @@
# The ticket page
Every ticket this skill works has a **ticket page**, and every epic has an **epic index**. The
page is where Gib follows the work: the ticket as Jira has it, the plan, live progress, proof
beside the mocks, and the review. It updates while you work, so a write you skip is a gap he
sees. It is a personal working file, exempt from the prose bar like the rest of `.claude/docs/`.
```
.claude/docs/epics/
_site/site.css, site.js # shared renderer, refreshed from templates/site/ on every write
<EPIC-KEY>/
index.html, epic.data.js # the epic index, in build order
<TICKET-KEY>/
index.html, ticket.data.js # the ticket page
resources/ proof/ deliverables/ mr.md
tickets/<TICKET-KEY>/ # same shape, for a ticket with no epic, and no index
```
## Write through `ticket-page`, always
`~/.agents/skills/ticket/scripts/ticket-page` is the only writer of the data files. It validates
before every write and refuses a broken one, writes atomically so the open page never reads half
a file, appends each change to the page's live log, and keeps the ticket's row on the epic index
current. Editing a `.data.js` file by hand skips all four. `ticket-page help` lists every
command and its flags.
It finds the ticket by key under the current repo's `.claude/docs/epics/`, so run it from inside
the repo.
## What to record, and when
| Moment | Command |
|---|---|
| Issue fetched to a scratch path | `init <KEY> --issue <issue.raw.json>`. Prints the ticket folder, then any populated Jira fields the page does not show. |
| Attachments downloaded, a video transcribed, frames extracted | `scan <KEY>` |
| Ticket branch resolved, ticket classified | `meta <KEY> --branch <name> --classified bounded` |
| Research notes worth keeping: what a video says, what a spreadsheet holds, a check against prod | `note <KEY> "<Title>" --file notes.html` |
| Plan written | `plan <KEY> --file plan.json`, then one `mock` per artboard |
| Plan approved, Phase 2 begins | `approve <KEY>` |
| Starting a step | `step <KEY> <n> running` |
| A step's commit exists | `step <KEY> <n> done --commit <sha>`, one `--commit` per commit |
| A criterion is met | `criterion <KEY> <ID> done --evidence "<what shows it>"` |
| Proof captured, or dropped from `proof/` | `proof <KEY> --file proof/<name> --proves AC1,AC3 --caption "<test case>" [--mock <id>]`, `proof <KEY> --test "<name>" ...`, `unproof <KEY> <file>` |
| Reviewer finding, and its resolution | `finding <KEY> add "<text>" --severity CONFIRMED --where <file:line>`, then `finding <KEY> F1 fixed --commit <sha>` or `rejected --reason "<why>"` |
| pre-mr-review audit read | `verdict <KEY> <verdict text> --recommendation <R> --head <sha>` |
| A Jira field PUT and verified | `jira <KEY> "<field name>"` |
| `mr.md` written | `mr <KEY>` |
| Anything else Gib would want to see happen: suite green, a surprise, a blocker | `event <KEY> "<text>"` |
A step is done when its commit exists and `ticket-page show <KEY>` lists that commit beside it.
`step done` refuses without `--commit`. A step with nothing to commit, such as a verification
pass, takes `--no-commit`.
## `plan.json`
The plan is one JSON file, written with the Write tool and loaded with `ticket-page plan`. Prose
fields are HTML fragments: `<p>`, `<b>`, `<code>`, `<ul><li>`. `plan` replaces any earlier plan
and clears its progress and proof, because a rewritten plan is a restart. To change a plan
mid-build (a new step, a reworded criterion), print it with `plan-json <KEY> > plan.json`, edit
that, and load it with `plan --amend`: steps whose number and text are unchanged, and
criteria whose id remains, keep their progress, and proof keeps the criteria that still exist.
```json
{
"criteria": [
{ "id": "AC1", "text": "Every company can carry a five character canonical ID.", "steps": [1, 2] },
{ "id": "AC2", "text": "A duplicate canonical ID is rejected with a readable message.", "steps": [3] }
],
"questions": [],
"approach": "<p><b>Company.canonicalId</b> is the only new state. The engagement ID is derived by <code>formatEngagementCanonicalId</code>, so the two cannot drift.</p>",
"decisions": [["Engagement canonical ID", "Derived at read time", "Matches the spreadsheet formula, with no second column to backfill."]],
"steps": [
{ "n": 1, "text": "Add the canonicalId module, tests first.", "tdd": true },
{ "n": 2, "text": "Schema, migration and backfill." },
{ "n": 3, "text": "Map the unique violation to CONFLICT.", "tdd": true },
{ "n": 4, "text": "Canonical ID field on the company form.", "kind": "mock" }
],
"risks": [
{ "risk": "Two companies given the same code", "handling": "The unique index blocks it and step 3 returns a readable CONFLICT.", "criteria": ["AC2"], "fromTicket": true }
],
"tests": [
{ "kind": "integration", "text": "companies.update with a taken code throws CONFLICT.", "criteria": ["AC2"] }
]
}
```
- Steps are numbered 1 to N in order. `kind` is `code` (the default), `mock`, or `deliverable`.
- Every criterion names the steps that satisfy it. Risks and tests name the criteria they cover.
- A risk or test that comes from the ticket's own table carries `"fromTicket": true`. Your own
additions leave it off, so the page shows which rows the ticket asked for.
- `questions` holds only what genuinely needs Gib's answer, each as a direct question. Empty
means none.
## Mocks
When a step changes what a user sees (a new screen, a changed layout, a new control, copy a
user reads), the plan carries mock artboards:
```
ticket-page mock <KEY> <id> --title "<screen>" --criteria AC3,AC8 --note "<what the build will not do>" --file artboard.html
```
- An artboard is a complete small HTML document with its own `<style>`, rendered in a sandboxed
frame beside the proof. Draw the screen state the plan introduces, with the app's real
navigation and density around it rather than a wireframe of boxes.
- One artboard per new screen state. When the direction is Gib's call, draw each candidate as
its own artboard (`option-a`, `option-b`) and ask the choice in `questions`, naming the
artboards. This is how the house rule of several static mocks before touching real components
is met inside the ticket flow.
- `--criteria` names what the artboard illustrates. The Progress tab shows it under those
criteria, and replaces the empty half with the proof once a `proof ... --mock <id>` lands.
- `--note` states what the artboard shows that the implementation will not do.
- A spike deliverable's polished mocks (see **Mocks and datamodel changes**) can start from the
approved artboard. The built screens are still screenshotted for real.
## The epic index
The index lists the epic's stories in build order: the order they should be completed in, which
is not key order and not always the Jira link graph. Each worked ticket keeps its own row current.
The rest of the index is yours to seed and keep true.
- **Seed it** the first time a ticket under the epic is worked, and refresh it on later runs.
Search the epic's children (`parent = <EPIC> ORDER BY rank`). For each, record the title, the
estimate as `--hours`, the Story Risk Level as `--risk`, the stories it is blocked by as
`--after`, and `--status done` if Jira says Done: `ticket-page epic <EPIC> story <KEY> ...`.
Closed spikes go in with `epic <EPIC> closed <KEY> --title T`.
- **Set the order** with `ticket-page epic <EPIC> order <KEY> <KEY> ...`, listing every story. If
the epic already records a build order (a `summary.md` or plan in its folder), that order wins.
Otherwise order by the blocked-by links, then Jira rank. Write the reasons the order is what it
is with `epic <EPIC> why --file reasons.txt`, one reason per line.
- **Gib reorders by asking.** When he does, rerun `order` and update `why`.
- A story is marked done only by `--status done`, once it has merged or Jira says Done. The index
never guesses that.
## Reading it as an agent
`ticket-page md <KEY>` prints the ticket and the plan as markdown. Use it when you resume a
ticket, and hand it to the fresh reviewer as the ticket and plan in its reading order.
## Tickets from before the page
Tickets planned before the page existed have `resources/ticket.md` and `plan.md` and no
`ticket.data.js`. Leave those files alone. When Phase 0 resumes such a ticket, convert it
first: `init` from `resources/issue.raw.json`, `plan` from the plan's content, then `approve` and
`step ... done` for each step `git log` shows committed. From then on the page is the record.
user/agents/skills/ticket/SKILL.md
+154 -228
View File
@@ -1,14 +1,14 @@
--- ---
name: ticket name: ticket
description: End-to-end Jira ticket workflow — fetch a ticket into .claude/docs/epics/, write a plan and its plan.html review page, implement it with clean commits, drive the pre-mr-review audit to convergence (the user runs it themselves from their work Claude account), 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. description: End-to-end Jira ticket workflow — fetch a ticket into a live ticket page under .claude/docs/epics/, plan it, implement it with clean commits, drive the pre-mr-review audit to convergence (the user runs it themselves from their work Claude account), 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 disable-model-invocation: true
--- ---
# Ticket Workflow # Ticket Workflow
Turns a Jira ticket key into: a saved ticket record, a reviewed plan, implemented and Turns a Jira ticket key into: a live ticket page carrying the ticket, a reviewed plan,
committed code, a converged `pre-mr-review` audit, and an MR doc ready to paste into progress, and proof, implemented and committed code, a converged `pre-mr-review` audit, and
GitLab/GitHub. This skill is user-level (`~/.agents/skills/ticket/`) and works the same 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. 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 Invoked as `/ticket KACP-11111`. The ticket key is passed as the skill's arguments. Called
@@ -19,20 +19,33 @@ Jira story, the estimate, risk level, and testing tables, as part of authoring a
before anyone builds it. It has nothing to do with reviewing code. The code review in 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. this skill is Phase 2 step 5 and is performed by a dispatched agent, not by a skill.
## The ticket page
Every ticket gets a **ticket page**, a web page Gib keeps open while you work: the ticket as
Jira has it, the plan with its mocks, live progress, proof beside the mocks, and the review.
Every epic gets an **epic index** listing its stories in build order. Both render from data
files that only `ticket-page` writes, and both update themselves as it writes.
**Read [SITE.md](SITE.md) before the first write of every run.** It holds the command for each
moment the phases below name, the plan's JSON shape, how to draw mocks, and how the epic order
is seeded. Record each moment when it happens, not in a batch at the end, because Gib is
watching the page change.
## Directory layout this skill maintains ## Directory layout this skill maintains
``` ```
.claude/docs/epics/ .claude/docs/epics/
_site/ # the shared renderer, refreshed by ticket-page
<EPIC-KEY>/ <EPIC-KEY>/
epic.md # brief epic context, written once, best-effort index.html, epic.data.js # the epic index
<TICKET-KEY>/ <TICKET-KEY>/
index.html, ticket.data.js # the ticket page
resources/ resources/
ticket.md # title, description, dev review instructions issue.raw.json # the fetched issue, kept for re-imports
<attachments...> # images, videos, other files as downloaded <attachments...> # images, videos, other files as downloaded
<video>.transcript.txt # only for videos that got transcribed <video>.transcript.txt # only for videos that got transcribed
<video>.transcript.srt <video>.transcript.srt
plan.md <video>.frames/
plan.html # the plan as a page, with mocks when a step changes what a user sees
deliverables/ # only for tickets whose output is documents, not code deliverables/ # only for tickets whose output is documents, not code
<deliverable-slug>/ <deliverable-slug>/
<deliverable-slug>.md <deliverable-slug>.md
@@ -41,16 +54,13 @@ this skill is Phase 2 step 5 and is performed by a dispatched agent, not by a sk
proof/ # captured working feature proof, uploaded to Jira by the user 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 mr.md # the MR description only, written once pre-mr-review says Ready to Open MR
tickets/ tickets/
<TICKET-KEY>/ # same shape, for tickets with no epic <TICKET-KEY>/ # same shape, for tickets with no epic, and no index
resources/...
plan.md
plan.html
deliverables/...
mr.md
``` ```
## Scripts this skill uses ## Scripts this skill uses
- `~/.agents/skills/ticket/scripts/ticket-page <command> <KEY> ...` — the only writer of the
ticket page and epic index. See [SITE.md](SITE.md), or `ticket-page help`. Runs under bun.
- `~/.agents/skills/ticket/scripts/jira-fetch-issue.sh <KEY> <OUT.json>` — fetches one - `~/.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` / issue (`fields=*all`, rendered HTML description, field-name map) via `JIRA_BASE_URL` /
`JIRA_CREDENTIALS`. `JIRA_CREDENTIALS`.
@@ -101,8 +111,8 @@ rerun it, and verify the device log instead of accepting the fallback transcript
## House style (applies to everything this skill writes or commits) ## House style (applies to everything this skill writes or commits)
- No code comments unless the user explicitly asks for one in that spot. - 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`, - No em dashes, en dashes, semicolons, or arrow glyphs in commit messages, the ticket page,
`plan.md`, or `mr.md`. Plain punctuation only. or `mr.md`. Plain punctuation only.
- Commits are `git commit -m "<short imperative message>"` only — no body, no - Commits are `git commit -m "<short imperative message>"` only — no body, no
co-author line, no `Claude` / `Codex` / `AI` trailer of any kind. 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 - Never `git push`. Never open an MR/PR. This skill prepares everything needed to open
@@ -161,19 +171,18 @@ the document.** Being aligned first is the point, and the writing should read as
you always were. you always were.
This governs `mr.md`, `customfield_10260` and `10261`, every other Jira field, and PM This governs `mr.md`, `customfield_10260` and `10261`, every other Jira field, and PM
deliverables. It does not govern files only he reads. `plan.md`, `bugs.md`, audits and deliverables. It does not govern files only he reads. The ticket page, `bugs.md`, audits and
working notes can name him and record who decided what, because that history is useful. working notes can name him and record who decided what, because that history is useful.
The House style punctuation rule above is the stricter one where the two overlap. Keep The House style punctuation rule above is the stricter one where the two overlap. Keep
it. Personal working files (`plan.md`, `plan.html`, `ticket.md`) are exempt, nobody else it. The ticket page is a personal working file and exempt, nobody else reads it.
reads them.
## Verification tools available ## Verification tools available
The goal isn't "a plausible-sounding plan" or "code that compiles" — it's a plan and 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 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 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 in question, before writing the plan (Phase 1) and again whenever Phase 2's
implementation makes a claim that's checkable: implementation makes a claim that's checkable:
- **The codebase itself.** Don't take the ticket's description of "how things work - **The codebase itself.** Don't take the ticket's description of "how things work
@@ -199,7 +208,7 @@ implementation makes a claim that's checkable:
about explicitly rather than assume the file's DB credential is fair game by default. 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 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 reach), say so explicitly in the plan's open questions instead of silently skipping
the check. the check.
**How to write what you found, in a deliverable.** State it as a plain confirmed **How to write what you found, in a deliverable.** State it as a plain confirmed
@@ -213,7 +222,7 @@ codebase equally.
Some tickets (spikes, research, migration proposals, the KACP-22764 kind of ticket) 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 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 a plan step produces a document rather than a code change, it becomes its own
subfolder under `<target-dir>/deliverables/<deliverable-slug>/` with three files: subfolder under `<target-dir>/deliverables/<deliverable-slug>/` with three files:
- `<slug>.md` — the source of truth for content. Write this first, get the content - `<slug>.md` — the source of truth for content. Write this first, get the content
@@ -228,11 +237,10 @@ subfolder under `<target-dir>/deliverables/<deliverable-slug>/` with three files
- `<slug>.pdf` — compiled from the `.typ` file. - `<slug>.pdf` — compiled from the `.typ` file.
**Write for the actual audience, not for yourself.** The reader is a PM or another **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 engineer who has never seen `.claude/docs/` or the ticket page, and doesn't have this
`ticket.md` are, and doesn't have this repo (or any other local repo) checked out. repo (or any other local repo) checked out. Never reference `.claude/docs/` or any local
Never reference `.claude/docs/` or any local file path in a deliverable's content. file path in a deliverable's content. Never point the reader at the ticket page or the
Never say "see plan.md" or "see ticket.md", those are personal working files, not plan, those are personal working files, not things a reader can open. Refer to "this ticket" or a plain Jira link, not a local
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 path. If a fact came from another repo on this machine, state the fact, don't cite
the local checkout path it came from. the local checkout path it came from.
@@ -318,7 +326,7 @@ describe it only as a quick UI mockup.
When a ticket calls for mocks or datamodel changes (a spike proposing new screens or a 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. 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`. Build it for real, on the ticket's branch. Give these steps `"kind": "mock"` in the plan.
A mock deliverable is **two artifacts**, not one, and they answer different questions. 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 The code proves the thing is buildable and surfaces the problems a picture hides. The
@@ -351,7 +359,7 @@ what was quick to wire up. Ship both, and don't let either stand in for the othe
feature. Don't chase every edge case and don't fix unrelated pre-existing bugs you 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 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 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 than a static mock would, say so in the plan's approach rather than silently scoping it down
without mentioning the tradeoff. without mentioning the tradeoff.
- **Screenshot the real thing.** Once it's built and running, use the `run` skill to - **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 get the app up and a browser automation tool (e.g. `claude-in-chrome`) to capture
@@ -372,41 +380,6 @@ Reach for it when the spike's real open question is which of several directions
build. Once a direction is settled, the deliverable is the two artifacts above, and both build. Once a direction is settled, the deliverable is the two artifacts above, and both
ship with the ticket. ship with the ticket.
## The plan page (`plan.html`)
`plan.md` is the plan. `plan.html` is the same plan as a page, saved beside it, so Gib
reads the plan in a browser before approving it instead of scrolling a markdown file. It
opens from `file://`, ticks acceptance criteria and steps as he reviews them, and shows
the mocks in place. It is the review artifact, and it exists to be opened.
- **Fill the template.** Copy `~/.agents/skills/ticket/templates/plan.html` to
`<target-dir>/plan.html` and fill every slot its header comment lists, in the order
`plan.md` carries them: the same criteria, the same open questions, the same Approach,
the same steps with the same `(mock)` and `(deliverable)` marks as badges, the same
risks, the same test plan. Fill the slots only. The CSS and script ship as they are, so
every plan page looks and behaves the same. Done when a reader of either file learns
nothing the other omits.
- **Mocks, when a step changes what a user sees.** A new screen, a changed layout, a new
control, or copy a user reads means the page keeps its Mocks section: one artboard per
screen state the plan introduces, drawn in plain HTML and CSS inside its own
`<template>`, with the app's real navigation and density around it rather than a
wireframe of boxes. When the direction is Gib's call, draw each candidate as its own
artboard (Option A, Option B) and name the choice in Open questions, pointing at the
artboards. When the direction is settled, one artboard per screen. Each artboard's
`data-note` states what it shows that the implementation will not do. This is how the
house rule about several static mocks before touching real components is satisfied
inside the ticket flow, so no separate mock server is needed. When no step changes
what a user sees, delete the Mocks section and its nav link.
- **Open it.** After saving, run `xdg-open <target-dir>/plan.html` so it lands in the
browser, and give both paths in the Phase 1 wrap-up.
- **`plan.md` stays the source of truth.** When Phase 0 routes to rewriting the plan,
rewrite `plan.html` with it. Phase 2 checks steps off in `plan.md` only. The page is a
snapshot for the review and is left alone once the plan is approved.
- **Relation to spike mocks.** The plan page's artboards are design intent drawn before
any code exists. A deliverable's polished `mocks/` (see Mocks and datamodel changes)
can start from the approved artboard, and the built screens are still screenshotted
for real.
--- ---
## Branch setup — run this before any repo work in Phase 1 or Phase 2 ## Branch setup — run this before any repo work in Phase 1 or Phase 2
@@ -450,7 +423,7 @@ through, and the branch needs to already exist when that happens.
Once this resolves you're on the correct branch, and Phase 1/Phase 2 work happens 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 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 doesn't affect the ticket page or `mr.md` directly — this is about making sure any
actual code (mockup prototypes, spike code, real implementation) lands in the right actual code (mockup prototypes, spike code, real implementation) lands in the right
place from the start. place from the start.
@@ -460,21 +433,23 @@ place from the start.
correct key. correct key.
2. Look for an existing directory for this ticket without hitting the network: 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>"` `find .claude/docs/epics -mindepth 2 -maxdepth 2 -type d -name "<KEY>"`
(this matches both `epics/<EPIC>/<KEY>` and `epics/tickets/<KEY>`). (this matches both `epics/<EPIC>/<KEY>` and `epics/tickets/<KEY>`). If it holds a
`plan.md` but no `ticket.data.js`, it predates the ticket page: convert it first, as
[SITE.md](SITE.md) describes under **Tickets from before the page**, then continue.
`ticket-page show <KEY>` says where the ticket stands.
3. Branch on what you find: 3. Branch on what you find:
- **Nothing found** — this is a fresh ticket. Go to **Phase 1**. - **Nothing found** — this is a fresh ticket. Go to **Phase 1**.
- **Directory exists, no `plan.md`** — a previous run was interrupted before writing - **A page with no plan** — a previous run was interrupted before writing a plan. Go
a plan. Go to **Phase 1** and regenerate from scratch (re-fetch, overwrite to **Phase 1** and regenerate from scratch (re-fetch, re-import, re-check
`ticket.md`, re-check attachments); it's idempotent and cheap. attachments); it's idempotent and cheap.
- **`plan.md` exists, no `mr.md`** — ask the user (AskUserQuestion) what they want: - **A plan, no `mr.md`** — ask the user (AskUserQuestion) what they want:
- Re-fetch the ticket and rewrite the plan (`plan.md` and `plan.html`) from scratch - Re-fetch the ticket and rewrite the plan from scratch (they want to start over)
(they want to start over) - Proceed to implementing the existing plan as-is (they reviewed and approved it)
- Proceed to implementing the existing `plan.md` as-is (they reviewed and approved it) - Resume implementation (some steps are already done on the page / some commits
- Resume implementation (some plan steps are already checked off / some commits already exist on the ticket branch — pick up from the first open step)
already exist on the ticket branch — pick up from the first unchecked step)
- Move to the pre-mr-review stage (implementation looks done, just need the audit + MR doc; the user runs the audit from their work account, see Phase 2 step 7) - Move to the pre-mr-review stage (implementation looks done, just need the audit + MR doc; the user runs the audit from their work account, see Phase 2 step 7)
Route to **Phase 1** or **Phase 2** accordingly. Route to **Phase 1** or **Phase 2** accordingly.
- **Both `plan.md` and `mr.md` exist** — this ticket looks finished. Tell the user - **A plan and `mr.md`** — this ticket looks finished. Tell the user
`mr.md` already exists at its path and ask whether they want you to refresh it `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 (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 verification/pre-mr-review loop if they say the code changed since `mr.md` was
@@ -485,83 +460,39 @@ place from the start.
## Phase 1 — fetch, scaffold, and plan ## Phase 1 — fetch, scaffold, and plan
1. Do **Branch setup** above first, unconditionally. 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 2. Run `jira-fetch-issue.sh <KEY> <tmp-path>` (a scratch path is fine here — the next
yet know the final directory). Read the resulting JSON. step knows the final directory). Read the resulting JSON.
3. Determine the epic: `fields.parent.key`, if present. If absent, this ticket has no 3. Import it: `ticket-page init <KEY> --issue <tmp-path>`. This files the ticket under its
epic. epic (or `tickets/` without one), imports every rich-text field verbatim as sanitized
4. Resolve the target directory: HTML, writes the page, and prints the ticket folder. Copy the fetched JSON to
- With epic: `.claude/docs/epics/<EPIC-KEY>/<KEY>/` `<target-dir>/resources/issue.raw.json`, which later re-imports and the attachment
- Without epic: `.claude/docs/epics/tickets/<KEY>/` script read. Record the branch from **Branch setup** with `ticket-page meta`, then open
Create it and its `resources/` subdirectory. the page with `ticket-page open <KEY>` so Gib can follow from here on.
5. Move/copy the fetched JSON to `<target-dir>/resources/issue.raw.json` for your own 4. `init` ends by listing populated Jira fields the page does not show. Read each one and
reference while writing `ticket.md` — this raw file is scratch, not part of the add any that bear on implementing or verifying the ticket as a note. This sweep exists
deliverable; feel free to leave it (it's harmless context for later) or delete it because real content sometimes hides in per-project custom fields with unpredictable
once `ticket.md` is written, your call. names, and a name-pattern miss must not silently drop it.
6. If there's an epic and `.claude/docs/epics/<EPIC-KEY>/epic.md` doesn't already exist: 5. Read what the Ticket tab now holds, and treat its tables as the ticket's contract.
best-effort fetch the epic issue too (`jira-fetch-issue.sh <EPIC-KEY> <tmp>`) and - **Test cases** (KACP's "Test Cases & Working Feature Proof") and **risk mitigation**
write a short `epic.md` (title + description, converted to markdown, a couple are imported with every row verbatim. Often a field is just the bare instruction
paragraphs at most). If this fetch fails for any reason, skip it and continue — it's panel and an empty table, which needs no further thought. When it has real rows,
context, not a blocker. those are the scenarios the developer must prove and the mitigations the developer
7. Write `resources/ticket.md` by reading the fetched issue JSON yourself: must implement: the plan names each one (`"fromTicket": true`), Phase 2 proves each
- Title, type, status, priority, assignee, epic key (or "None"), and a link one, and Phase 2 step 9 fills its proof column back into the Jira field. The PM and
(`<JIRA_BASE_URL>/browse/<KEY>`). Lead write the risks. Implementing and proving each is the developer's job.
- Description: convert `renderedFields.description` (HTML) to clean markdown. If - Never substitute your own invented test cases or risks for the ticket's, in the plan
empty, say so. or in the Jira fields. Your own additional cases are welcome alongside the ticket's
- Developer review instructions: the field name varies by project and isn't a fixed rows, never in place of them.
custom field ID. Look at the `names` map in the response for any field whose name 6. If the ticket has an epic, seed or refresh its epic index as [SITE.md](SITE.md)
matches something like "dev review instructions" / "review instructions" describes under **The epic index**. This is best-effort context: if the epic search
(case-insensitive substring match), then render that field's value the same way as fails, say so and continue.
the description. If nothing matches, write "None provided" — don't guess a field. 7. Run `jira-download-attachments.sh <issue.raw.json> <target-dir>/resources/`. For each
- 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 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 like its transcript (same base filename with `.txt`/`.srt`/`.vtt`, or a filename
containing "transcript"). Collect any videos with no matching transcript. containing "transcript"). Collect any videos with no matching transcript.
9. If there are untranscribed videos, ask the user (AskUserQuestion, one question, 8. 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 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` approve, run `transcribe.sh <video-path> <target-dir>/resources/`.
under Attachments which videos have a transcript and which were skipped.
For every video that gets transcribed, also extract frames — ticket videos are For every video that gets transcribed, also extract frames — ticket videos are
almost always screen recordings, and the transcript alone misses what was on 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 screen (the UI being pointed at, the annotation, the row that's wrong). Extract to
@@ -574,6 +505,10 @@ place from the start.
and treat what's visible on screen as part of the ticket's content the same way 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 the transcript is. Skip frame extraction only when the video is confirmed
audio-only or the user says the visuals don't matter. audio-only or the user says the visuals don't matter.
9. Run `ticket-page scan <KEY>` so the page carries the attachments, each video with its
transcript and frames. When a video, spreadsheet, or linked document holds the
ticket's real requirements, write what it says as a note (`ticket-page note`), the
way "What the video says" summarizes a recording point by point.
10. Now actually understand the ticket in the context of this codebase: read whatever 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 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 as needed — this is normal engineering research, not scripted. Use the
@@ -588,54 +523,33 @@ place from the start.
**architectural** is a new subsystem, a schema change other stories depend on, or **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 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 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 "grilling" and resolve its frontier with Gib BEFORE writing the plan — those
questions get answered in conversation, not deferred into the plan's Open questions 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 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 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 flow being changed isn't already there to read, it isn't bounded. In doubt, take the
heavier path. heavier path. Either way, record the classification with `ticket-page meta`.
11. Write `plan.md` in `<target-dir>/plan.md` (a sibling of `resources/`, not inside 11. Write the plan as `plan.json` in a scratch path, in the shape [SITE.md](SITE.md) gives,
it). Structure: and load it with `ticket-page plan <KEY> --file plan.json`. Its parts: acceptance
``` criteria restated precisely from the ticket, each naming the steps that satisfy it;
# Plan: <KEY> — <short title> open questions that genuinely need Gib's answer, empty if there really aren't any
(don't manufacture questions to look thorough); the approach, meaning what you're
going to do and why, which files, modules and functions are involved, and how it fits
the existing patterns; decisions already settled with Gib; steps, each roughly one
commit's worth of work, with `"kind": "deliverable"` for a step that produces a
document via **Deliverable documents** and `"kind": "mock"` for a real schema or UI
change built to demonstrate a mock (see **Mocks and datamodel changes**); risks and
edge cases, each with how the plan handles it; and the test plan, meaning how each
criterion gets verified, the existing suites to run, and any new tests.
## 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 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 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 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 approach. The test plan must name every test case on the Ticket tab and say how
that exact case gets proven, and the Risks section must name every risk that exact case gets proven, and the risks must name every risk on the Ticket tab
`ticket.md` captured and say which code enforces its mitigation. Read the notes and say which code enforces its mitigation. Read the notes column of a ticket test
column of a ticket test case as part of the case, not as commentary: a note like case as part of the case, not as commentary: a note like "confirm the certificate
"confirm the certificate matches the emailed version" is its own thing to prove. matches the emailed version" is its own thing to prove.
**Where the shape is in question, borrow the vocabulary.** When the plan has to **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 decide how deep a module should be, where a seam belongs, or what an interface
@@ -645,7 +559,7 @@ place from the start.
written for real. written for real.
**The Test plan is a design decision, not a formality.** Beyond the cases **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 the ticket already carries, call the Skill tool with "tdd" to decide which
additional tests are worth writing, where the seam under test goes, and whether a 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 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 padded: a test plan listing one case per changed file is slop, and three tests that
@@ -662,13 +576,14 @@ place from the start.
step stays green because the old form still exists until the last one. Say in the 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 Approach that this is what you're doing and why, since the step count looks inflated
otherwise. otherwise.
12. Write `plan.html` beside it, per **The plan page** above, and open it with 12. When a step changes what a user sees, draw its mock artboards with `ticket-page mock`,
`xdg-open`. as [SITE.md](SITE.md) describes under **Mocks**.
13. Stop here. Tell the user `plan.md` and `plan.html` are ready at their paths and that 13. Stop here. Tell the user the plan is on the ticket page, give its path from
the page is open in the browser, summarize the approach in a couple of sentences, and `ticket-page path <KEY>`, summarize the approach in a couple of sentences, and mention
mention any open questions that need their input before you'd implement it. Do not any open questions that need their input before you'd implement it. Do not start
start implementing in this same run — wait for them to review the plan (editing implementing in this same run — wait for them to review the plan and invoke
`plan.md` directly if they want) and invoke `/ticket <KEY>` again. `/ticket <KEY>` again. They change the plan by asking, and you rewrite it with
`ticket-page plan`.
## Phase 2 — implement, verify, and hand off ## Phase 2 — implement, verify, and hand off
@@ -677,14 +592,16 @@ 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 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 for the same ticket earlier, confirm you're still actually on that branch now (the
user may have switched branches between runs). user may have switched branches between runs).
2. Read `plan.md` fresh — the user may have hand-edited it. 2. Read the plan fresh with `ticket-page md <KEY>`, then mark it approved with
3. Work through `plan.md`'s Steps checklist in order. For each step: implement it (a `ticket-page approve <KEY>`.
step marked `(deliverable)` follows the **Deliverable documents** process above 3. Work through the plan's steps in order. For each step: implement it (a
instead of writing code; a step marked `(mock)` follows **Mocks and datamodel `deliverable` step follows the **Deliverable documents** process above instead of
changes** — real schema/UI work, not a static wireframe), then check it off writing code; a `mock` step follows **Mocks and datamodel changes** — real schema/UI work, not a static wireframe), and make one commit for it (or
(`- [x]`) in `plan.md`, then make one commit for it (or a few, if the step a few, if the step naturally splits into independent units). Commit messages are short
naturally splits into independent units). Commit messages are short and imperative, and imperative, describing what changed, following House style above. Mark the step
describing what changed, following House style above. running on the page when you start it and done with its commits when they exist, and
mark each acceptance criterion met the moment it is (SITE.md has the commands). A step
is done when `ticket-page show <KEY>` lists its commit.
**Write the test first for steps that carry real logic**, meaning a router **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 procedure, a derivation, a permission or authorization check, a migration, or a
@@ -696,11 +613,13 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
House style rejects. When unsure whether a step qualifies, ask whether the test could 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. 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 If a step fails in a way the plan didn't predict, and the cause isn't obvious within
a couple of minutes, call the Skill tool with "diagnosing-bugs" rather than trying 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. fixes to see what sticks. Note anything it turns up that changes the plan as an event on
the page. When it changes the steps, amend the plan as [SITE.md](SITE.md) describes, which
keeps the progress already made.
4. Do not run the full verification suite after every commit (checks-at-the-end mode). 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 Once every step is implemented and marked done, find and run this project's standard
verification (check `package.json` scripts for something like `ci:check`, verification (check `package.json` scripts for something like `ci:check`,
`typecheck`, `lint`, `test`, or fall back to whatever the repo's README documents). `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 Fix anything broken, committing fixes as their own commits, until it's clean. If you
@@ -736,8 +655,9 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
change cannot provide it. change cannot provide it.
- **Give the reviewer its reading order explicitly**, or it produces noise about - **Give the reviewer its reading order explicitly**, or it produces noise about
conventions the project already settled: the epic summary if there is one 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 (`.claude/docs/epics/<EPIC-KEY>/summary.md`), then the ticket and plan as
`plan.md`, then `AGENTS.md`, and only then the diff. Give it the exact commit range. `ticket-page md <KEY>` prints them, then this ticket's `resources/`, 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 - **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 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, `file:line` plus a concrete failure scenario. Tell it explicitly not to write,
@@ -748,12 +668,13 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
from checking. from checking.
- **Ask the spec questions explicitly**, or the review only finds bugs in what you - **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 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 the ticket and the plan 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; 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 and what looks implemented but is implemented wrongly. Have it quote the AC ID or
the `plan.md` line each finding traces to. the plan step each finding traces to.
Then respond to the review, in writing: Then respond to the review, in writing, and put each finding on the page as you judge
it: added, then fixed with its commit or rejected with the reason.
- **Findings are not automatically true.** Verify each one against the codebase - **Findings are not automatically true.** Verify each one against the codebase
before acting on it. Reviewers do produce confident wrong answers. Say plainly before acting on it. Reviewers do produce confident wrong answers. Say plainly
@@ -785,7 +706,7 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
skill prints the exact paths). Check the `last_reviewed_head` in the audit skill prints the exact paths). Check the `last_reviewed_head` in the audit
header matches the current HEAD; if the branch moved after their run, say so header matches the current HEAD; if the branch moved after their run, say so
and ask them to rerun before acting on a stale audit. and ask them to rerun before acting on a stale audit.
3. Read the verdict. 3. Read the verdict, and record it on the page with `ticket-page verdict`.
- **Ready to Open MR**: continue to step 8. - **Ready to Open MR**: continue to step 8.
- **Almost Ready / Not Ready Yet**: fix what it flagged (each meaningful fix - **Almost Ready / Not Ready Yet**: fix what it flagged (each meaningful fix
as its own commit), then ask the user to rerun the review from the work as its own commit), then ask the user to rerun the review from the work
@@ -811,8 +732,8 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
Make each one count: Make each one count:
- **Feed it context on the first run.** It reviews the diff, and left alone it - **Feed it context on the first run.** It reviews the diff, and left alone it
re-derives intent from the branch name and re-raises decisions that are re-derives intent from the branch name and re-raises decisions that are
already settled. Ask the user to point it at the ticket's already settled. Ask the user to point it at the ticket's `ticket.data.js`, or give
`resources/ticket.md` and `plan.md`. This is the cheapest thing that reduces them the output of `ticket-page md <KEY>` to paste in. This is the cheapest thing that reduces
repeat findings. repeat findings.
- **Answer its decisions explicitly in the rerun.** When it parks a finding - **Answer its decisions explicitly in the rerun.** When it parks a finding
under "Decide before opening", write the decision and its reasoning into the under "Decide before opening", write the decision and its reasoning into the
@@ -836,7 +757,7 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
- New ENVs: list any env vars actually introduced; "None" if none. - New ENVs: list any env vars actually introduced; "None" if none.
- Additional Notes: a bulleted checklist of the changes you actually made, not a - Additional Notes: a bulleted checklist of the changes you actually made, not a
dumping ground. Between Summary and this section, every acceptance criterion from 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, the plan (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. 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 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 as short bullets. Five bullet points max total, ticket-relevant and incidental
@@ -876,7 +797,8 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
(`customfield_10260`, "For The Engineer: Patch Notes"). Step 9 writes it. (`customfield_10260`, "For The Engineer: Patch Notes"). Step 9 writes it.
Scattered coverage across notes does not count as having answered a named Scattered coverage across notes does not count as having answered a named
requirement, and neither does burying it in the MR description. requirement, and neither does burying it in the MR description.
Save this as `<target-dir>/mr.md` (next to `plan.md`, not under `resources/`). Save this as `<target-dir>/mr.md` (next to `index.html`, not under `resources/`), and
record it with `ticket-page mr <KEY>`.
**`mr.md` is the template plus the pasted handoff, and NOTHING ELSE.** This is a **`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 hard shape, not a starting point. Its only headings are the template's own numbered
@@ -897,7 +819,8 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
9. Fill the Jira ticket fields directly, by issue type. Rich text fields are ADF: 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 markdown with `python3 ~/.agents/skills/review-ticket/scripts/review2adf.py
render <file.md>` and PUT via `{"fields": {...}}` to `/rest/api/3/issue/<KEY>`. 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, After every PUT, re-fetch and verify the field landed, then record it with
`ticket-page jira <KEY> "<field name>"` (compare extracted text,
treating empty `attrs` objects and `localId`/`colwidth`/`width` as noise). The 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 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. a field to a type that doesn't carry it.
@@ -910,7 +833,8 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
yourself wherever possible: run the app (`run` skill) and screenshot the real 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. 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 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" rows they prove, and put each on the page with `ticket-page proof`, naming the
criteria it proves and the mock it answers. A proof cell references its artifact by filename plus "attached"
(Gib uploads every attachment, this skill NEVER uploads files to Jira) or names (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 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 inbox, a flag flip), the cell says exactly what's needed and step 10 lists it for
@@ -920,7 +844,8 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
**Cap the proof at five files, and aim for two or three.** Gib uploads every **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 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 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/`. smallest set that actually carries the evidence, delete the rest from `proof/`, and
drop them from the page with `ticket-page unproof`.
- One screenshot can prove several rows at once. A company page that shows the - 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, navigation, the tabs, and the absent section proves three criteria in one image,
@@ -976,12 +901,13 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
ticket, Drive, or both, per the ticket's instructions). Fill `customfield_10260` ticket, Drive, or both, per the ticket's instructions). Fill `customfield_10260`
only if the spike actually shipped code. only if the spike actually shipped code.
Before moving on, re-read `ticket.md` row by row: every test case and every risk Before moving on, re-read the Ticket tab's test case and risk tables row by row: every
the ticket carries now has its developer column filled in Jira. Leave none test case and every risk the ticket carries now has its developer column filled in
Jira. Leave none
unanswered. unanswered.
10. Tell the user: implementation is committed on `<branch>`, `pre-mr-review` verdict is 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 Ready to Open MR, the Jira fields are filled (name which), `mr.md` is ready at its
its path. Then the manual list, which should only ever be: path, and the ticket page shows the finished work beside its mocks. Then the manual list, which should only ever be:
- push the branch, open the MR, and paste `mr.md` in as the description - 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/`) - upload the named proof or deliverable files (from `proof/` or `deliverables/`)
to the ticket, plus anything flagged as proof only Gib can capture to the ticket, plus anything flagged as proof only Gib can capture
@@ -989,8 +915,8 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved
## Resuming mid-implementation ## Resuming mid-implementation
If Phase 0 routes here because some steps in `plan.md` are already checked off: check If Phase 0 routes here because some steps are already done on the page: check
`git log` on the current branch against the plan's steps to sanity-check they actually `git log` on the current branch against the page's step commits to sanity-check they actually
match reality (a checked-off step should have a corresponding commit), then continue 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 from the first open step. If the plan and the git history disagree, stop and ask
the user rather than guessing which one is right. the user rather than guessing which one is right.