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

Add a plan.html review page to the ticket skill

Browse Source
This commit is contained in:
Gabriel Brown
2026-09-22 12:54:32 -04:00
parent 9b06e9e24b
commit 9022847971
2 changed files with 471 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
user/agents/skills/ticket/SKILL.md
+49 -7
View File
@@ -1,6 +1,6 @@
---
name: ticket
description: End-to-end Jira ticket workflow — fetch a ticket into .claude/docs/epics/, write a plan, 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 .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.
disable-model-invocation: true
---
@@ -32,6 +32,7 @@ this skill is Phase 2 step 5 and is performed by a dispatched agent, not by a sk
<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
<deliverable-slug>/
<deliverable-slug>.md
@@ -43,6 +44,7 @@ this skill is Phase 2 step 5 and is performed by a dispatched agent, not by a sk
<TICKET-KEY>/ # same shape, for tickets with no epic
resources/...
plan.md
plan.html
deliverables/...
mr.md
```
@@ -163,7 +165,8 @@ deliverables. It does not govern files only he reads. `plan.md`, `bugs.md`, audi
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`, `ticket.md`) are exempt, nobody else reads them.
it. Personal working files (`plan.md`, `plan.html`, `ticket.md`) are exempt, nobody else
reads them.
## Verification tools available
@@ -369,6 +372,41 @@ 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
@@ -429,7 +467,8 @@ place from the start.
a plan. Go to **Phase 1** and regenerate from scratch (re-fetch, overwrite
`ticket.md`, re-check attachments); it's idempotent and cheap.
- **`plan.md` exists, no `mr.md`** — ask the user (AskUserQuestion) what they want:
- Re-fetch the ticket and rewrite the plan from scratch (they want to start over)
- 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)
@@ -623,10 +662,13 @@ 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. Stop here. Tell the user `plan.md` is ready at its path, summarize the approach in
a couple of sentences, and mention any open questions that need their input before
you'd implement it. Do not start implementing in this same run — wait for them to
review the plan (editing it directly if they want) and invoke `/ticket <KEY>` again.
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.
## Phase 2 — implement, verify, and hand off