diff --git a/user/agents/skills/ticket/SITE.md b/user/agents/skills/ticket/SITE.md new file mode 100644 index 0000000..09c52ca --- /dev/null +++ b/user/agents/skills/ticket/SITE.md @@ -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 + / + index.html, epic.data.js # the epic index, in build order + / + index.html, ticket.data.js # the ticket page + resources/ proof/ deliverables/ mr.md + tickets// # 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 --issue `. Prints the ticket folder, then any populated Jira fields the page does not show. | +| Attachments downloaded, a video transcribed, frames extracted | `scan ` | +| Ticket branch resolved, ticket classified | `meta --branch --classified bounded` | +| Research notes worth keeping: what a video says, what a spreadsheet holds, a check against prod | `note "" --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. diff --git a/user/agents/skills/ticket/SKILL.md b/user/agents/skills/ticket/SKILL.md index 0b923a2..864a1e0 100644 --- a/user/agents/skills/ticket/SKILL.md +++ b/user/agents/skills/ticket/SKILL.md @@ -1,14 +1,14 @@ --- 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 --- # 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 +Turns a Jira ticket key into: a live ticket page carrying the ticket, a reviewed plan, +progress, and proof, 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 @@ -19,38 +19,48 @@ 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 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 ``` .claude/docs/epics/ + _site/ # the shared renderer, refreshed by ticket-page <EPIC-KEY>/ - epic.md # brief epic context, written once, best-effort + index.html, epic.data.js # the epic index <TICKET-KEY>/ + index.html, ticket.data.js # the ticket page 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 <video>.transcript.txt # only for videos that got transcribed <video>.transcript.srt - plan.md - 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 + <video>.frames/ + 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 + 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 - plan.html - deliverables/... - mr.md + <TICKET-KEY>/ # same shape, for tickets with no epic, and no index ``` ## 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 issue (`fields=*all`, rendered HTML description, field-name map) via `JIRA_BASE_URL` / `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) - 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. +- No em dashes, en dashes, semicolons, or arrow glyphs in commit messages, the ticket page, + 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 @@ -161,19 +171,18 @@ the document.** Being aligned first is the point, and the writing should read as you always were. 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. 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 -reads them. +it. The ticket page is a personal working file and exempt, nobody else reads it. ## 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 +in question, before writing the plan (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 @@ -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. 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. **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) 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: - `<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. **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 +engineer who has never seen `.claude/docs/` or the ticket page, 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 point the reader at the ticket page or the +plan, 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. @@ -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 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. 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 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 + than a static mock would, say so in the plan's approach 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 @@ -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 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 @@ -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 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 place from the start. @@ -460,21 +433,23 @@ place from the start. 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>`). + (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: - **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 (`plan.md` and `plan.html`) 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) + - **A page with no plan** — a previous run was interrupted before writing a plan. Go + to **Phase 1** and regenerate from scratch (re-fetch, re-import, re-check + attachments); it's idempotent and cheap. + - **A plan, 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 as-is (they reviewed and approved it) + - Resume implementation (some steps are already done on the page / some commits + already exist on the ticket branch — pick up from the first open 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) 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 (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 @@ -485,83 +460,39 @@ place from the start. ## 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 +2. Run `jira-fetch-issue.sh <KEY> <tmp-path>` (a scratch path is fine here — the next + step knows the final directory). Read the resulting JSON. +3. Import it: `ticket-page init <KEY> --issue <tmp-path>`. This files the ticket under its + epic (or `tickets/` without one), imports every rich-text field verbatim as sanitized + HTML, writes the page, and prints the ticket folder. Copy the fetched JSON to + `<target-dir>/resources/issue.raw.json`, which later re-imports and the attachment + script read. Record the branch from **Branch setup** with `ticket-page meta`, then open + the page with `ticket-page open <KEY>` so Gib can follow from here on. +4. `init` ends by listing populated Jira fields the page does not show. Read each one and + add any that bear on implementing or verifying the ticket as a note. This sweep exists + because real content sometimes hides in per-project custom fields with unpredictable + names, and a name-pattern miss must not silently drop it. +5. Read what the Ticket tab now holds, and treat its tables as the ticket's contract. + - **Test cases** (KACP's "Test Cases & Working Feature Proof") and **risk mitigation** + are imported with every row verbatim. Often a field is just the bare instruction + panel and an empty table, which needs no further thought. When it has real rows, + those are the scenarios the developer must prove and the mitigations the developer + must implement: the plan names each one (`"fromTicket": true`), Phase 2 proves each + one, and Phase 2 step 9 fills its proof column back into the Jira field. The PM and + Lead write the risks. Implementing and proving each is the developer's job. + - Never substitute your own invented test cases or risks for the ticket's, in the plan + or in the Jira fields. Your own additional cases are welcome alongside the ticket's + rows, never in place of them. +6. If the ticket has an epic, seed or refresh its epic index as [SITE.md](SITE.md) + describes under **The epic index**. This is best-effort context: if the epic search + fails, say so and continue. +7. 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, +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 - approve, run `transcribe.sh <video-path> <target-dir>/resources/`. Note in `ticket.md` - under Attachments which videos have a transcript and which were skipped. + approve, run `transcribe.sh <video-path> <target-dir>/resources/`. 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 @@ -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 the transcript is. Skip frame extraction only when the video is confirmed 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 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 @@ -588,54 +523,33 @@ place from the start. **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 + "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 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> + heavier path. Either way, record the classification with `ticket-page meta`. +11. Write the plan as `plan.json` in a scratch path, in the shape [SITE.md](SITE.md) gives, + 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; + 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 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. + approach. The test plan must name every test case on the Ticket tab and say how + that exact case gets proven, and the risks must name every risk on the Ticket tab + 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 @@ -645,7 +559,7 @@ place from the start. 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 + 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 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 @@ -662,13 +576,14 @@ place from the start. 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. Write `plan.html` beside it, per **The plan page** above, and open it with - `xdg-open`. -13. Stop here. Tell the user `plan.md` and `plan.html` are ready at their paths and that - the page is open in the browser, 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 - `plan.md` directly if they want) and invoke `/ticket <KEY>` again. +12. When a step changes what a user sees, draw its mock artboards with `ticket-page mock`, + as [SITE.md](SITE.md) describes under **Mocks**. +13. Stop here. Tell the user the plan is on the ticket page, give its path from + `ticket-page path <KEY>`, 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 and invoke + `/ticket <KEY>` again. They change the plan by asking, and you rewrite it with + `ticket-page plan`. ## 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 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. +2. Read the plan fresh with `ticket-page md <KEY>`, then mark it approved with + `ticket-page approve <KEY>`. +3. Work through the plan's steps in order. For each step: implement it (a + `deliverable` step follows the **Deliverable documents** process above instead of + 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 + a few, if the step naturally splits into independent units). Commit messages are short + and imperative, describing what changed, following House style above. Mark the step + 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 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 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 - 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). - 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`, `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 @@ -736,8 +655,9 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved 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. + (`.claude/docs/epics/<EPIC-KEY>/summary.md`), then the ticket and plan as + `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 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, @@ -748,12 +668,13 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved 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 + 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; 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 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 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. - 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. - **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 @@ -811,8 +732,8 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved Make each one count: - **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 - already settled. Ask the user to point it at the ticket's - `resources/ticket.md` and `plan.md`. This is the cheapest thing that reduces + already settled. Ask the user to point it at the ticket's `ticket.data.js`, or give + them the output of `ticket-page md <KEY>` to paste in. This is the cheapest thing that reduces repeat findings. - **Answer its decisions explicitly in the rerun.** When it parks a finding 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. - 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, + 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. 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 @@ -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. 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/`). + 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 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: 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, + 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 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. @@ -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 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" + 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 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 @@ -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 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/`. + 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 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` 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 + Before moving on, re-read the Ticket tab's test case and risk tables 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: + Ready to Open MR, the Jira fields are filled (name which), `mr.md` is ready at its + 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 - upload the named proof or deliverable files (from `proof/` or `deliverables/`) 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 -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 +If Phase 0 routes here because some steps are already done on the page: check +`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 -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.