Grill Ticket

Grill ticket

One invocation = one ticket taken from raw to agent-ready. Three parties: YOU research and interview; the USER decides every genuine fork; the EXECUTOR (a consume-tickets run, possibly on another machine, with no access to this conversation) implements later. Write for the executor: it sees ONLY the tracker issue and the committed repo — anything load-bearing lands in the ticket body or committed docs, or it is lost. This skill and /ocakbasi:consume-tickets are one toolchain built on the repo's documentation model — a CONTEXT.md glossary plus docs/adr/ decision records — maintained via the grill-with-docs skill (from mattpocock/skills): a declared dependency, expected installed at user level (~/.claude/skills/) on each machine, invoked at G4; on a fresh project it creates those files lazily.

Project config = .claude/ocakbasi.md (Tracker, Exclusions, Docs & knowledge, Verification policy, Ticket format sections), read first. Missing → copy templates/ocakbasi.template.md from the plugin root (this skill lives at /skills/grill-ticket/; $CLAUDE_PLUGIN_ROOT in a Bash call also resolves it) to .claude/ocakbasi.md, ask the user to complete its SETUP comment, and stop.

No state file. The conversation is the session state: grill sessions are short and attended, and a session that dies is simply restarted — research is cheap to redo. The only writes: the final artifact in .claude/ocakbasi/tickets/, doc edits made during G4, and G0's state-dir self-ignore repair.

Guardrails

1. The tracker is READ-ONLY (view/list/api reads). Applying the final body and the agent-ready label is the USER's sign-off act, never yours — never urge the label.
2. No git mutations; git fetch and read-only log/status are fine. Doc edits stay uncommitted — the user reviews and commits them.
3. Write scope: the artifact dir, G4's doc edits, the state-dir self-ignore repair. Nothing else — no source code, no settings.
4. Every question goes through AskUserQuestion, ONE fork per call — never a plain-text question, never delegated to a subagent (the tool exists only in the main conversation).
5. Agent-brief exception: the collapsed brief is the ONLY place implementation detail (file paths, identifiers, mechanism) may appear in a ticket. Never strip or "fix" an existing brief.
6. Context economy: summarize in ≤3 lines — verbatim bodies/files/outputs never enter the chat. Broad code sweeps go to ONE read-only Explore subagent (≤10-line return); targeted reads stay inline.

Discipline (hard rules)

1. Research before ask: no content question until G1 is done — a question the repo could answer is a defect; never make the user your grep.
2. Every content question quotes the ≤2 lines of evidence (file path or issue ref) that create the fork; no quote → the fork probably doesn't exist → back to research.
3. Priced options: every option states cost / perf / blast radius / reversibility. "Cleaner", "simpler", "more robust" are banned as sole justification.
4. No invented numbers: measured, cited, or tagged ASSUMPTION with a validation plan; a load-bearing number nobody has → §Measurement forks.
5. Third-option check: before asking, construct the option that dissolves the fork (defer / do-nothing / decompose); include it when real, drop the question when it wins outright.
6. One fork per call; trunk before branches — never ask a question whose premise depends on an unanswered one.
7. Push-back-once: an answer contradicting recorded evidence gets the contradiction presented exactly once; the user's second answer is final.
8. Claims audit is ternary — confirmed / false / unverifiable, each cited; unverifiable becomes a question or an Open item with a decision rule, never a silent assumption.
9. Any "faster / cheaper / no regression" acceptance criterion names metric + workload + threshold, or it is not a criterion.
10. Register & self-containment: human sections say what/why — component names and #N refs are fine; paths/identifiers/mechanism live only in the brief. No machine-local paths, no "as discussed"; knowledge that exists only on this machine or in this conversation must be restated in the ticket or already live in committed docs.
11. Guess test at exit: simulate a fresh implementer holding only ticket + repo — every direction-changing guess it would face is an unresolved fork.

Flow

G0 — Intake

Arg: integer/#N → issue mode; an existing file path → §Draft mode; none → cheap open-issue list (numbers/titles/labels only) + one picker question. Then: tracker auth check (gh auth status); fetch title/body/labels/state/comments/updatedAt; CLOSED → procedural question (abort Recommended). Completion-marker check: git fetch, then a (#N)-titled commit on the default branch (resolve it: git symbolic-ref --short refs/remotes/origin/HEAD; unset → git remote set-head origin -a — never assume a name) → record sha+date (G6 reports the REWORK consequence). State dir not self-ignoring → write .claude/ocakbasi/.gitignore containing * (nothing for the user to commit).

G1 — Research (every item done before any content question)

Read the CONTEXT.md glossary (and CONTEXT-MAP.md if present), every ADR in docs/adr/ touching the ticket's area, and any additional docs the config's Docs section lists — note every conflict for G4. Code: explore every component the ticket names — you cannot audit claims about code you have not looked at. Claims audit (Discipline 8) over body + comments, flagging direction-relevant rows. Dependencies: read referenced issues; record DIRECTION per ref (depends-on / unblocks / related — mentions are often beneficiaries, not prerequisites); leaf verdict. Related-issue title sweep for overlaps. Delta grill — the ticket already carries an Agent brief: the brief is the baseline plan; research only what moved since it was written (new comments, body edits, repo/ADR drift); the ledger holds only new or invalidated forks; existing brief Decisions stay settled unless contradicted by evidence; G5's audits still run in full.

G2 — Throwaway plan & ledger

Mechanism-level bullets ONLY — the draft exists to FLUSH OUT forks; polishing wording here means writing G5 early and turning the interview into confirmation theater. Walk it: every fork → a ledger row classed self (repo/docs answer it — resolve now, cite evidence), user (taste, priorities, budgets, user-visible behavior, irreversible formats), or measurement. Third-option check every user fork; order trunk-first.

G3 — Interview loop

Take the highest open trunk fork → ONE AskUserQuestion: ≤3 lines of context ending in the evidence quote; your Recommended option FIRST (≤2-line cited why), then ≤2 priced alternatives, then Skip LAST (the tool adds free-text "Other" itself). After each answer: update the ledger and plan, then re-walk — answers expose new forks and moot pending ones. "Other" free text is first-class: re-derive every dependent row before the next question. Skip on a content fork = parked → an agent-brief Open item; a parked DIRECTION-CHANGING fork fails the G5 autonomy audit (artifact still emitted; report says not-ready). Direction-relevant FALSE claims are questions too; register-level falsehoods are corrected silently and listed in G6. Loop until no open rows, then post a ≤30-line summary (decisions + plan shape).

• §Measurement forks — cheap and runnable now (≲10 min, this machine) → procedural permission question, run it, cite the result. Expensive or wrong machine → make the measurement STEP 1 of the plan with an objective decision rule the implementer applies ("Δ > threshold on → A, else B") — "profile it and use judgment" does not pass the autonomy gate. Neither → the ticket exits NOT-ready; the report names the missing number.
• §Split protocol — the session reveals ≥2 tickets → trunk question ("narrow to X, spin off the rest" Recommended). On narrow: prune the ledger; emit split-offs at G6 as skeleton-only drafts (no brief, explicitly not-refined); record cross-ticket dependencies in the brief and the report.

G4 — Docs grill

Invoke the Skill grill-with-docs with args = the consolidated plan for issue #N (its agenda: challenge terms against the glossary, stress concrete scenarios, cross-reference code, update docs inline). House mechanics stay in force: AskUserQuestion, one fork per call, Recommended-first, evidence-cited. Track every file it edits for the G6 report. New forks → G3 rules; at most ONE abbreviated re-grill limited to changed decisions. If the skill is unavailable on this machine, run the same agenda inline against CONTEXT.md/ADRs and note it in the report.

G5 — Rewrite & exit audits

Build the final ticket (§Skeleton + §Agent brief) from the plan, decisions, and claims audit (register-level corrections applied silently, listed for G6). WRITE the audit table — every row pass/fail + 1-line evidence — BEFORE the finalize question (an unwritten audit is a rubber stamp):

• Autonomy gate (the executor skips tickets where open questions would change direction: architecture; user-visible behavior/policy; irreversible formats; perf-vs-quality tradeoffs with no stated budget; conflicts with committed project docs — CONTEXT.md, ADRs, plus the config's Docs extras) — every clause closed by a Decision or covered by an Open-item decision rule.
• Leaf — every depends-on edge closed or agent-ready-labeled; on-hold dependencies flagged.
• Consumability — platform-eligible on at least one machine (suggest the config's platform labels otherwise); violates no config Exclusion (else: "split that part out").
• Verification — complete per the config's Verification policy; states whether the change has a runtime surface (drives the executor's runtime-check skip).
• Guess test (Discipline 11). Register lint — human sections free of the config's banned tokens. Self-containment lint — no machine-local paths, no state-dir refs, no "as discussed". Format — title sentence-case; the config's CI criterion verbatim and LAST; `` blank-line rules respected.

Any fail → fix in place or back to G3; a parked direction-changing fork stays a fail (proceed only with the not-ready flag). Then the finalize question: "Finalize (Recommended)" / "Revise wording" / "Reopen a decision" / Skip (= park; restart later re-derives cheaply).

G6 — Emit & report

Write .claude/ocakbasi/tickets/-.md (H1 title + full body incl. the brief; plus any split-off skeletons). Report, in order: artifact path(s); final title, marked changed/unchanged (it goes in the tracker's title FIELD, not the body); the BODY in one markdown fence — the paste target; suggested labels from the config's set (agent-ready is the user's sign-off); leaf verdict + on-hold dependency notes; REWORK note when a completion commit exists ("previously completed at ; your body update re-queues it as REWORK"); corrections made; docs touched, then verbatim: "commit AND push these before labeling — the executor pulls the default branch; uncommitted edits don't travel"; not-ready flags, stated plainly: do not label yet.

§Ticket skeleton (human sections — Discipline 10 register)

# 

**This ticket asks for .**  is left to implementation." only for parts genuinely left open via agent-brief Open items.>

## Why it matters

- **** — 

## Scope

**In scope**

- 

**Non-goals:**

- 

## Acceptance criteria

- [ ] 
- [ ] 

§Agent brief (the sole how-location — Guardrail 5; appended after the acceptance criteria)

Rendering rule: keep the blank lines after ` and before `, or the markdown inside will not render.

Agent brief — implementation contract; expand before implementing

_Produced by a grill-ticket session on . Sections above are the human contract; this block is the agent brief. If this block conflicts with committed docs, the docs win — raise the conflict as a question instead of implementing over it._

### Decisions
- D1:  — why:  [user-confirmed | evidence: ]

### Approach

### Constraints & invariants

### Verification
 (drives the executor's runtime-check skip).>

### Dependencies & sequencing

### Open items (deliberately left to implementation)
- O1:  — decision rule: 

### References

§Draft mode (arg = a file path; the ticket is not on the tracker yet)

Artifact: .claude/ocakbasi/tickets/-.md, next-likely = newest issue-or-PR number + 1 (they share the sequence); note inside that the number is provisional. The tracker is used only for the dependency check and that number — failures degrade to "unverified ref" in the claims audit, never a halt. G0's fetch/closed/label steps don't apply; everything else runs unchanged. The report ends: "file it yourself; rename the file and fix the H1 if the number drifted."

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: osman-turan
• Source: osman-turan/skills
• License: MIT

Install and usage instructions live in the source repository linked above.