[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74PHFZTYN4BGYEPRCSZ1KAH":3,"skill-same:01M74PHFZTYN4BGYEPRCSZ1KAH":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":31,"ownerHtmlUrl":32,"ownerBlogUrl":33,"ownerDescription":6,"updatedAt":34,"install":35,"resources":48},"01M74PHFZTYN4BGYEPRCSZ1KAH","refine-ticket",null,"Refine a development ticket — or brainstorm a raw idea — into a validated, self-contained REQUIREMENTS document — the \"what\", verified against the codebase. Invoke manually only.","eai-org\u002Fagent-toolkit","eai-org","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F301886321?v=4","01M74PFC3HF57T58MQ14P212BQ","Engineering in the age of AI","01M74PFC46MSKTT9SW5Q437FSD",85,"MIT","https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Frefine-ticket\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: refine-ticket\ndescription: Refine a development ticket — or brainstorm a raw idea — into a validated, self-contained REQUIREMENTS document — the \"what\", verified against the codebase. Invoke manually only.\nlicense: MIT\nmetadata:\n  version: \"1.22\"\n---\n\n# Refine ticket\n\nThe **Refine** phase of Refine → Plan → Act: turn a raw ticket — or an idea to brainstorm — into a\nvalidated requirements document a fresh session can plan from. Analysis only — it defines **what**\nmust be true when the work is done, never **how** to build it, and never touches code.\n\nAn idea is a ticket that doesn't exist yet: treat the user's words as the ticket text, and grill\nto shape the idea itself — goal, in vs out of scope — before closing the branches that block\nimplementation.\n\n## Input\n\nA `.TICKET.md` path, a ticket URL or bare id, or an idea in words. When the harness has subagents\nand fetch-ticket is available (`..\u002Ffetch-ticket\u002FSKILL.md` beside this skill), a URL or id is\nfetched first by a subagent per fetch-ticket's [delegate.md](..\u002Ffetch-ticket\u002Fdelegate.md) — one\nticket per run; several → point at a fetch session instead, which handles sets. A non-empty warn\nlist stops for one question: supply the files now (`\u002Fattach-to-ticket` when available; answered\nby running it → resume with the supplied files once it reports) or refine without them. The\nfetched file is then the local ticket file. No subagents, or fetch-ticket not available → read\nthe ticket from its tracker and refine with no local ticket file.\n\nAn existing `.REQUIREMENTS.md` (a re-run, e.g. once a blocking answer is in): read it and its\nticket file (`.REQUIREMENTS` → `.TICKET`, or its latest `-vN` re-fetch, file or directory) first\n— none for a tracker ticket → re-read it there, asking for its URL or id when the file doesn't\nname it; grill only on what changed since, and update it in place.\n\n## What, not how — but verified against the code\n\nYou cannot define the \"what\" in a vacuum. Every requirement must be checked against the **actual\ncode, config, and design** — a ticket may be stale, ambiguous, contradicted by the codebase, or\ndepend on upstream work that isn't implemented yet (e.g. a prerequisite ticket still open). Reading\nthe code here is for *validating* requirements, not for designing the solution.\n\n## Golden rule: never guess — ask\n\n- Anything determinable by reading the code, resolve by reading the code — never ask the user about\n  it.\n- Anything *not* determinable from ticket + code, ask — never fill the gap with a plausible\n  assumption.\n- Local environment state (config files, DB contents, env vars) describes only the machine it's on\n  — never assume it matches the environment where the reported behaviour occurred; ask the user to\n  confirm such values.\n- Treat \"this probably works like X\" as a question, not a fact. Keep \"I confirmed X\", \"the ticket\n  claims X\", and \"I assume X\" distinct; the latter two never become the first without evidence. A\n  decision marked settled by a ticket or design carries the quote that settles it; no quote, still\n  open.\n- Before declaring something missing, unique or unhandled (\"no X does Y\", \"X's only user\", \"the\n  existing ones don't cover Z\"), search every repo the feature spans for the concept — \"not found\n  under the name the ticket used\" is not \"not present\".\n- Verify both sides of an integration: if a requirement relies on another layer behaving a certain\n  way, open that layer and confirm it.\n\n## Reconcile against the design when one is referenced\n\nWhen a ticket points at a design (mockup, screenshot, prototype, design-tool link), that design is\npart of the spec. Visual decisions made without seeing it lock in wrong defaults.\n\n- If you cannot actually see the referenced design, ask for it before proceeding. A link you can't\n  render is not a design you've read. Prefer a copy already saved with the ticket over re-fetching.\n- Once you can see it, treat visual specifics as contract-level: currency, date, and number\n  formatting, empty and error states, label wording, spacing, alignment, iconography. The default\n  for \"is this in the design?\" is match the design, not do the minimum.\n- Any visual choice you'd otherwise make blind is an Open question, never silently defaulted.\n\n## Read relevant related tickets — context, not scope\n\nWhen the ticket references others that matter to it (BE\u002FFE counterparts, dependencies, follow-ups),\nread them too — they complete the picture and sharpen how this ticket's requirements are meant. A\n`## Ticket set` section in the ticket file lists locally fetched siblings: read every linked\n`.TICKET.md` before grilling; for tracker-only references, judge relevance before fetching, then\nfetch one the way Input does. What a sibling supplies — execution order, contracts it owns,\nsuperseded-spec notes — is context only, never requirements: scope stays this ticket's, and\nanything a sibling suggests changing is a question for the user, never a silent scope change.\n\n## A prior ticket review is leads, never facts\n\nUnless one was passed in, look for a `.TICKET-REVIEW.md` next to the ticket or in its set\ndirectory, preferring the one whose base matches the ticket file's `-vN` base — an earlier\nsession's triage; say which one you use, or that none exists. Challenge and re-verify everything\nin it before relying on it (its citations make that cheap). Its shipped questions are blocking\nitems: grill first whether the owner answered. The defaults it assumed for dropped cheap details\nare decisions to close here — grilled or recorded as Open questions, never adopted silently.\nHandoffs are out-of-scope dependencies; verdict and walkthrough are context only. The ticket file\nand the code always win; a review older than the ticket file has likely been overtaken — say so.\n\n## Existing requirements\n\nBefore the first grill question, look for this ticket's requirements: the `.REQUIREMENTS.md` at\nthe target path (Location below) or, for a ticket with `-vN` versions and none under its own base,\nthe highest earlier version's (down to the unsuffixed base). A tracker ticket with no local file\nhas its slug and target path confirmed before the first grill question, so the check runs there;\nan idea in words has them confirmed once its goal and scope are shaped, before the branch\ngrilling, and the check runs then, at that path only. Found and not the input → say so, name the\n`.PLAN`\u002F`.MANUAL-TEST` of that base that would go stale, and ask once:\n\n- **Update in place** (recommended): read that file and the highest `-vN` ticket first, grill only\n  on what changed, keep settled decisions, update the same file.\n- **Start over**: same base → replace it at write time; an earlier version → fresh requirements\n  under this ticket's base, old file untouched.\n\nNever a `-vN` REQUIREMENTS copy beside a ticket of another base; never asked again at write time.\n\n## Grill to resolve every branch\n\nAfter gathering and code-verifying, **grill** the user — interview relentlessly, never guessing\nwhat they could clarify — to close every remaining decision:\n\n- One question at a time, each with your recommended answer, worded so that \"yes\" accepts it, via\n  `explain-in-simple-language` when available.\n- Facts are yours to find (codebase, docs, tool output): look them up, never ask. Decisions are\n  the user's. Never bundle a code-answerable sub-question into a grill: \"Which name, type, shape,\n  or pattern fits?\" is code-answerable — match the closest existing analogue, and let that\n  verified convention outrank the ticket's contrary suggestion. Grill only on what genuinely\n  remains (product intent, cross-task timing).\n- Walk each branch of the decision tree, resolving dependencies between decisions, until there is\n  shared understanding and no open branch that blocks implementation.\n\nSeparate two kinds of uncertainty:\n- **Blocking** — implementation can't proceed without it (a contradiction, a missing referenced\n  file). Resolve during grilling, before writing the file.\n- **Non-blocking** — a reasonable default exists but a human should confirm. Record under Open\n  questions with your tentative answer.\n\nA blocking question only someone else can answer: write the file anyway, with the question under\nOpen questions marked **blocking**, naming who answers it and the question drafted ready to send\n(via `use-conversational-language` when available). Print no hand-off commands while a blocking\nentry exists, only the one for once the answer is in: `\u002Frefine-ticket \u003Cpath>.REQUIREMENTS.md`.\n\n## Bug tickets\n\nA ticket is a bug when its tracker type says so (a fetched file's `**Type**` header line, else the\ntracker's type field); with no type (an idea, pasted text, a typeless tracker), when its text\nreports existing behaviour breaking what should already work, not a wish to change what works as\nintended. A non-bug type whose text reads like a bug, or a case neither settles, is a grill\nquestion.\n\nFor a bug, try to reproduce it with what the project already provides (running the app, an\nexisting command or test), the smallest that shows it: a unit test before an integration test\nbefore e2e or the running app, a larger one only when the bug lies in how parts connect. No\nscratch script, no source edit, no tracked file written. A run's side outputs (build output,\ncaches, coverage, reports, snapshots) may land only in scratch space or git-ignored paths; a run\nthat would write elsewhere is not made, and the bug counts as not reproduced. A run acting on\nshared or external state (a remote service, a shared database) is a grill question, never made\nunasked.\n\nNot reproduced (the attempt didn't show it, or nothing in the project can try it, e.g. a\nproduction-only or external-integration bug) is a grill question on where it occurred\n(environment, data, version), per the Golden rule's local-environment line; never assume it fixed\nor invalid. Still unreproduced after grilling → the Reproduction part says so and why; that alone\nis not blocking.\n\n## \"Already exists\" \u002F \"reuse X\" is a directive\n\nWhen the ticket says a capability exists or names something to reuse, find what's *behind* it (the\nservice method, query, SP it calls) and anchor the requirement on the smallest extension — relax a\nparameter, widen a filter, lift a guard. \"Not an exact match\" doesn't license a net-new build:\nreuse-vs-build-new is a **blocking** question for the user, never a silent default.\n\n## Output: the REQUIREMENTS file\n\nMust stand alone for a **fresh session** with no memory of this conversation and no access to the\nticket — this is the single most important constraint. No \"as discussed\", \"we agreed\", or \"see\nticket\".\n\nLocation:\n- If the ticket input is a **local file**, write the REQUIREMENTS file in the **same directory**,\n  replacing `.TICKET` with `.REQUIREMENTS` (e.g. `FOO.TICKET.md` → `FOO.REQUIREMENTS.md`); if the\n  input doesn't follow that convention, append `.REQUIREMENTS` before `.md`.\n- If there is **no local ticket file** (a tracker URL\u002FID read without a fetch, pasted text),\n  follow the project's\u002Fuser's convention for where planning documents live (default:\n  `.agents\u002Fplans\u002F`). Propose a kebab-case `\u003Cslug>` (prefix the tracker id when the ticket is bound\n  to one) and the target path, **confirm both with the user** (timing under Existing\n  requirements), then write `\u003Cslug>\u002F\u003Cslug>.REQUIREMENTS.md` there.\n- A REQUIREMENTS input is its own target. An existing target is updated or replaced as settled\n  under Existing requirements — never asked again here.\n\nSix parts (Verified codebase facts, Overrides, and Open questions may be empty — don't pad):\n\n1. **Context** — 1–3 sentences: the feature, what's in scope, what's out. When the work is only\n   a slice of a larger feature, link the big-picture reference (parent story, final-goal\u002Fcontext\n   note, design) so the planner sees how it fits; a self-contained task needs none.\n2. **Verified codebase facts** — the facts confirmed while validating requirements, recorded so\n   the planner builds on them instead of rediscovering: where the relevant code lives, data\n   shapes, existing analogues, integration points. Byproduct only — never explore beyond what\n   refinement itself needs — and only facts a fresh session would need a search to rediscover.\n   Anchor to paths and identifiers; line numbers are hints — they drift. *What is true today*,\n   never *how to change it*. When non-empty, open with one line pinning the commit (short hash,\n   noting uncommitted changes if the tree is dirty) and absolute date, warning the code may have\n   changed since and specifics need re-verifying.\n3. **Requirements** — deduplicated functional + technical list. Tag each item with its source in\n   the input: a ticket field (`(Description)`, `(AC)`, `(Comment)`), the user's idea statement\n   (`(Idea)`), a grilling answer (`(Grilling)`), a review comment by its opening words and\n   `path:line` (`(\"Validate both new option arguments\", install.sh:88)`) — never an answers-sheet\n   row number. Group by area when it aids reading. Cite the concrete file path \u002F identifier inline\n   wherever a requirement touches code; cite a reused pattern as `path:line-range`.\n4. **Overrides** — every deviation from the ticket in what must be true when the work is done: a\n   ticket statement changed or dropped, a requirement added. Rewording and merged duplicates are not\n   deviations; for an idea, only changing or dropping one of the user's own statements is one —\n   requirements shaped while grilling are not. Each entry: what the ticket says or omits, the\n   resulting requirement, and the reason with its source — what the code\u002FAC shows, or the user's\n   decision while grilling.\n5. **Open questions** — non-blocking ambiguities, each with your tentative answer and why it's\n   non-blocking. A blocking question appears here only marked **blocking**: one someone else must\n   answer (above).\n6. **Acceptance criteria** — flat, verifiable checklist the implementation must satisfy. A \"none\n   left\" criterion (a removal, a doc sweep) gives its exact search — each removed name as a whole\n   word, in every form it is written (case and separator variants) — with an allow-list of\n   legitimate hits, and the hits outside that list it finds on the default branch today: like a\n   bug's regression test, it must be seen failing, since a search too narrow passes while stale text\n   remains. A search that finds none is widened to the forms the name is actually written in;\n   still none, the criterion records that nothing is left to remove.\n\nA bug adds a **Reproduction** part right after Context: the steps, what they show now (observed),\nwhat they should show (expected), and whether you reproduced it and how, or why not.\n\nEach requirement is self-contained; user-facing strings that must stay in a given language are\nquoted verbatim.\n\nDone when the six parts, plus Reproduction for a bug, are present and\n`grep -niE \"as discussed|we agreed|see ticket|as mentioned\"` on the file returns nothing.\n\n## Boundaries\n\n- Do **not** write an implementation plan or describe \"how\".\n- Do **not** modify any source files. The only files written, a reproduction run's side outputs\n  aside (Bug tickets), are the REQUIREMENTS document, the ticket file a delegated fetch-ticket\n  writes, and the assets and ticket entries an `\u002Fattach-to-ticket` run in answer to the attachments\n  question writes.\n\nWhen done, state — in **project-relative paths** — that the requirements file is ready, then hand\noff each next phase as its own fenced block under the label quoted below, holding one\ncopy-pasteable launch command — phase-prefixed session name and prompt combined, so one paste starts\nthe session — in the launch syntax of the agent tool in use (vendor-agnostic — `claude` below is\nonly the example), the session named with the phase prefix plus the requirements file's slug; a\nblock only when its skill is available, in either form:\n\n\"Harden the requirements first, so a fresh reviewer challenges them before planning:\"\n\n```\nclaude --name harden-requirements-\u003Cslug> \"\u002Fharden-artifact \u003Cpath>.REQUIREMENTS.md\"\n```\n\n\"Plan the implementation:\" (starting \"or\" when the harden block precedes it)\n\n```\nclaude --name create-plan-\u003Cslug> \"\u002Fcreate-implementation-plan \u003Cpath>.REQUIREMENTS.md\"\n```\n\n\"Write the QA manual test:\"\n\n```\nclaude --name create-manual-test-\u003Cslug> \"\u002Fcreate-manual-test-instructions \u003Cpath>.REQUIREMENTS.md\"\n```\n\nThe phase prefix (`create-plan-`, `execute-plan-`, …) keeps the pipeline phases distinguishable in\nthe session list.\n\nThen offer the alternative: one line offering to clear the current session (vendor-agnostic —\n`\u002Fclear` is only the example; use the clear command of the agent tool in use) and run the next\nphase here, then the same labelled blocks with the bare prompts.\n","# Refine ticket\n\nThe **Refine** phase of Refine → Plan → Act: turn a raw ticket — or an idea to brainstorm — into a\nvalidated requirements document a fresh session can plan from. Analysis only — it defines **what**\nmust be true when the work is done, never **how** to build it, and never touches code.\n\nAn idea is a ticket that doesn't exist yet: treat the user's words as the ticket text, and grill\nto shape the idea itself — goal, in vs out of scope — before closing the branches that block\nimplementation.\n\n## Input\n\nA `.TICKET.md` path, a ticket URL or bare id, or an idea in words. When the harness has subagents\nand fetch-ticket is available (`..\u002Ffetch-ticket\u002FSKILL.md` beside this skill), a URL or id is\nfetched first by a subagent per fetch-ticket's [delegate.md](..\u002Ffetch-ticket\u002Fdelegate.md) — one\nticket per run; several → point at a fetch session instead, which handles sets. A non-empty warn\nlist stops for one question: supply the files now (`\u002Fattach-to-ticket` when available; answered\nby running it → resume with the supplied files once it reports) or refine without them. The\nfetched file is then the local ticket file. No subagents, or fetch-ticket not available → read\nthe ticket from its tracker and refine with no local ticket file.\n\nAn existing `.REQUIREMENTS.md` (a re-run, e.g. once a blocking answer is in): read it and its\nticket file (`.REQUIREMENTS` → `.TICKET`, or its latest `-vN` re-fetch, file or directory) first\n— none for a tracker ticket → re-read it there, asking for its URL or id when the file doesn't\nname it; grill only on what changed since, and update it in place.\n\n## What, not how — but verified against the code\n\nYou cannot define the \"what\" in a vacuum. Every requirement must be checked against the **actual\ncode, config, and design** — a ticket may be stale, ambiguous, contradicted by the codebase, or\ndepend on upstream work that isn't implemented yet (e.g. a prerequisite ticket still open). Reading\nthe code here is for *validating* requirements, not for designing the solution.\n\n## Golden rule: never guess — ask\n\n- Anything determinable by reading the code, resolve by reading the code — never ask the user about\n  it.\n- Anything *not* determinable from ticket + code, ask — never fill the gap with a plausible\n  assumption.\n- Local environment state (config files, DB contents, env vars) describes only the machine it's on\n  — never assume it matches the environment where the reported behaviour occurred; ask the user to\n  confirm such values.\n- Treat \"this probably works like X\" as a question, not a fact. Keep \"I confirmed X\", \"the ticket\n  claims X\", and \"I assume X\" distinct; the latter two never become the first without evidence. A\n  decision marked settled by a ticket or design carries the quote that settles it; no quote, still\n  open.\n- Before declaring something missing, unique or unhandled (\"no X does Y\", \"X's only user\", \"the\n  existing ones don't cover Z\"), search every repo the feature spans for the concept — \"not found\n  under the name the ticket used\" is not \"not present\".\n- Verify both sides of an integration: if a requirement relies on another layer behaving a certain\n  way, open that layer and confirm it.\n\n## Reconcile against the design when one is referenced\n\nWhen a ticket points at a design (mockup, screenshot, prototype, design-tool link), that design is\npart of the spec. Visual decisions made without seeing it lock in wrong defaults.\n\n- If you cannot actually see the referenced design, ask for it before proceeding. A link you can't\n  render is not a design you've read. Prefer a copy already saved with the ticket over re-fetching.\n- Once you can see it, treat visual specifics as contract-level: currency, date, and number\n  formatting, empty and error states, label wording, spacing, alignment, iconography. The default\n  for \"is this in the design?\" is match the design, not do the minimum.\n- Any visual choice you'd otherwise make blind is an Open question, never silently defaulted.\n\n## Read relevant related tickets — context, not scope\n\nWhen the ticket references others that matter to it (BE\u002FFE counterparts, dependencies, follow-ups),\nread them too — they complete the picture and sharpen how this ticket's requirements are meant. A\n`## Ticket set` section in the ticket file lists locally fetched siblings: read every linked\n`.TICKET.md` before grilling; for tracker-only references, judge relevance before fetching, then\nfetch one the way Input does. What a sibling supplies — execution order, contracts it owns,\nsuperseded-spec notes — is context only, never requirements: scope stays this ticket's, and\nanything a sibling suggests changing is a question for the user, never a silent scope change.\n\n## A prior ticket review is leads, never facts\n\nUnless one was passed in, look for a `.TICKET-REVIEW.md` next to the ticket or in its set\ndirectory, preferring the one whose base matches the ticket file's `-vN` base — an earlier\nsession's triage; say which one you use, or that none exists. Challenge and re-verify everything\nin it before relying on it (its citations make that cheap). Its shipped questions are blocking\nitems: grill first whether the owner answered. The defaults it assumed for dropped cheap details\nare decisions to close here — grilled or recorded as Open questions, never adopted silently.\nHandoffs are out-of-scope dependencies; verdict and walkthrough are context only. The ticket file\nand the code always win; a review older than the ticket file has likely been overtaken — say so.\n\n## Existing requirements\n\nBefore the first grill question, look for this ticket's requirements: the `.REQUIREMENTS.md` at\nthe target path (Location below) or, for a ticket with `-vN` versions and none under its own base,\nthe highest earlier version's (down to the unsuffixed base). A tracker ticket with no local file\nhas its slug and target path confirmed before the first grill question, so the check runs there;\nan idea in words has them confirmed once its goal and scope are shaped, before the branch\ngrilling, and the check runs then, at that path only. Found and not the input → say so, name the\n`.PLAN`\u002F`.MANUAL-TEST` of that base that would go stale, and ask once:\n\n- **Update in place** (recommended): read that file and the highest `-vN` ticket first, grill only\n  on what changed, keep settled decisions, update the same file.\n- **Start over**: same base → replace it at write time; an earlier version → fresh requirements\n  under this ticket's base, old file untouched.\n\nNever a `-vN` REQUIREMENTS copy beside a ticket of another base; never asked again at write time.\n\n## Grill to resolve every branch\n\nAfter gathering and code-verifying, **grill** the user — interview relentlessly, never guessing\nwhat they could clarify — to close every remaining decision:\n\n- One question at a time, each with your recommended answer, worded so that \"yes\" accepts it, via\n  `explain-in-simple-language` when available.\n- Facts are yours to find (codebase, docs, tool output): look them up, never ask. Decisions are\n  the user's. Never bundle a code-answerable sub-question into a grill: \"Which name, type, shape,\n  or pattern fits?\" is code-answerable — match the closest existing analogue, and let that\n  verified convention outrank the ticket's contrary suggestion. Grill only on what genuinely\n  remains (product intent, cross-task timing).\n- Walk each branch of the decision tree, resolving dependencies between decisions, until there is\n  shared understanding and no open branch that blocks implementation.\n\nSeparate two kinds of uncertainty:\n- **Blocking** — implementation can't proceed without it (a contradiction, a missing referenced\n  file). Resolve during grilling, before writing the file.\n- **Non-blocking** — a reasonable default exists but a human should confirm. Record under Open\n  questions with your tentative answer.\n\nA blocking question only someone else can answer: write the file anyway, with the question under\nOpen questions marked **blocking**, naming who answers it and the question drafted ready to send\n(via `use-conversational-language` when available). Print no hand-off commands while a blocking\nentry exists, only the one for once the answer is in: `\u002Frefine-ticket \u003Cpath>.REQUIREMENTS.md`.\n\n## Bug tickets\n\nA ticket is a bug when its tracker type says so (a fetched file's `**Type**` header line, else the\ntracker's type field); with no type (an idea, pasted text, a typeless tracker), when its text\nreports existing behaviour breaking what should already work, not a wish to change what works as\nintended. A non-bug type whose text reads like a bug, or a case neither settles, is a grill\nquestion.\n\nFor a bug, try to reproduce it with what the project already provides (running the app, an\nexisting command or test), the smallest that shows it: a unit test before an integration test\nbefore e2e or the running app, a larger one only when the bug lies in how parts connect. No\nscratch script, no source edit, no tracked file written. A run's side outputs (build output,\ncaches, coverage, reports, snapshots) may land only in scratch space or git-ignored paths; a run\nthat would write elsewhere is not made, and the bug counts as not reproduced. A run acting on\nshared or external state (a remote service, a shared database) is a grill question, never made\nunasked.\n\nNot reproduced (the attempt didn't show it, or nothing in the project can try it, e.g. a\nproduction-only or external-integration bug) is a grill question on where it occurred\n(environment, data, version), per the Golden rule's local-environment line; never assume it fixed\nor invalid. Still unreproduced after grilling → the Reproduction part says so and why; that alone\nis not blocking.\n\n## \"Already exists\" \u002F \"reuse X\" is a directive\n\nWhen the ticket says a capability exists or names something to reuse, find what's *behind* it (the\nservice method, query, SP it calls) and anchor the requirement on the smallest extension — relax a\nparameter, widen a filter, lift a guard. \"Not an exact match\" doesn't license a net-new build:\nreuse-vs-build-new is a **blocking** question for the user, never a silent default.\n\n## Output: the REQUIREMENTS file\n\nMust stand alone for a **fresh session** with no memory of this conversation and no access to the\nticket — this is the single most important constraint. No \"as discussed\", \"we agreed\", or \"see\nticket\".\n\nLocation:\n- If the ticket input is a **local file**, write the REQUIREMENTS file in the **same directory**,\n  replacing `.TICKET` with `.REQUIREMENTS` (e.g. `FOO.TICKET.md` → `FOO.REQUIREMENTS.md`); if the\n  input doesn't follow that convention, append `.REQUIREMENTS` before `.md`.\n- If there is **no local ticket file** (a tracker URL\u002FID read without a fetch, pasted text),\n  follow the project's\u002Fuser's convention for where planning documents live (default:\n  `.agents\u002Fplans\u002F`). Propose a kebab-case `\u003Cslug>` (prefix the tracker id when the ticket is bound\n  to one) and the target path, **confirm both with the user** (timing under Existing\n  requirements), then write `\u003Cslug>\u002F\u003Cslug>.REQUIREMENTS.md` there.\n- A REQUIREMENTS input is its own target. An existing target is updated or replaced as settled\n  under Existing requirements — never asked again here.\n\nSix parts (Verified codebase facts, Overrides, and Open questions may be empty — don't pad):\n\n1. **Context** — 1–3 sentences: the feature, what's in scope, what's out. When the work is only\n   a slice of a larger feature, link the big-picture reference (parent story, final-goal\u002Fcontext\n   note, design) so the planner sees how it fits; a self-contained task needs none.\n2. **Verified codebase facts** — the facts confirmed while validating requirements, recorded so\n   the planner builds on them instead of rediscovering: where the relevant code lives, data\n   shapes, existing analogues, integration points. Byproduct only — never explore beyond what\n   refinement itself needs — and only facts a fresh session would need a search to rediscover.\n   Anchor to paths and identifiers; line numbers are hints — they drift. *What is true today*,\n   never *how to change it*. When non-empty, open with one line pinning the commit (short hash,\n   noting uncommitted changes if the tree is dirty) and absolute date, warning the code may have\n   changed since and specifics need re-verifying.\n3. **Requirements** — deduplicated functional + technical list. Tag each item with its source in\n   the input: a ticket field (`(Description)`, `(AC)`, `(Comment)`), the user's idea statement\n   (`(Idea)`), a grilling answer (`(Grilling)`), a review comment by its opening words and\n   `path:line` (`(\"Validate both new option arguments\", install.sh:88)`) — never an answers-sheet\n   row number. Group by area when it aids reading. Cite the concrete file path \u002F identifier inline\n   wherever a requirement touches code; cite a reused pattern as `path:line-range`.\n4. **Overrides** — every deviation from the ticket in what must be true when the work is done: a\n   ticket statement changed or dropped, a requirement added. Rewording and merged duplicates are not\n   deviations; for an idea, only changing or dropping one of the user's own statements is one —\n   requirements shaped while grilling are not. Each entry: what the ticket says or omits, the\n   resulting requirement, and the reason with its source — what the code\u002FAC shows, or the user's\n   decision while grilling.\n5. **Open questions** — non-blocking ambiguities, each with your tentative answer and why it's\n   non-blocking. A blocking question appears here only marked **blocking**: one someone else must\n   answer (above).\n6. **Acceptance criteria** — flat, verifiable checklist the implementation must satisfy. A \"none\n   left\" criterion (a removal, a doc sweep) gives its exact search — each removed name as a whole\n   word, in every form it is written (case and separator variants) — with an allow-list of\n   legitimate hits, and the hits outside that list it finds on the default branch today: like a\n   bug's regression test, it must be seen failing, since a search too narrow passes while stale text\n   remains. A search that finds none is widened to the forms the name is actually written in;\n   still none, the criterion records that nothing is left to remove.\n\nA bug adds a **Reproduction** part right after Context: the steps, what they show now (observed),\nwhat they should show (expected), and whether you reproduced it and how, or why not.\n\nEach requirement is self-contained; user-facing strings that must stay in a given language are\nquoted verbatim.\n\nDone when the six parts, plus Reproduction for a bug, are present and\n`grep -niE \"as discussed|we agreed|see ticket|as mentioned\"` on the file returns nothing.\n\n## Boundaries\n\n- Do **not** write an implementation plan or describe \"how\".\n- Do **not** modify any source files. The only files written, a reproduction run's side outputs\n  aside (Bug tickets), are the REQUIREMENTS document, the ticket file a delegated fetch-ticket\n  writes, and the assets and ticket entries an `\u002Fattach-to-ticket` run in answer to the attachments\n  question writes.\n\nWhen done, state — in **project-relative paths** — that the requirements file is ready, then hand\noff each next phase as its own fenced block under the label quoted below, holding one\ncopy-pasteable launch command — phase-prefixed session name and prompt combined, so one paste starts\nthe session — in the launch syntax of the agent tool in use (vendor-agnostic — `claude` below is\nonly the example), the session named with the phase prefix plus the requirements file's slug; a\nblock only when its skill is available, in either form:\n\n\"Harden the requirements first, so a fresh reviewer challenges them before planning:\"\n\n```\nclaude --name harden-requirements-\u003Cslug> \"\u002Fharden-artifact \u003Cpath>.REQUIREMENTS.md\"\n```\n\n\"Plan the implementation:\" (starting \"or\" when the harden block precedes it)\n\n```\nclaude --name create-plan-\u003Cslug> \"\u002Fcreate-implementation-plan \u003Cpath>.REQUIREMENTS.md\"\n```\n\n\"Write the QA manual test:\"\n\n```\nclaude --name create-manual-test-\u003Cslug> \"\u002Fcreate-manual-test-instructions \u003Cpath>.REQUIREMENTS.md\"\n```\n\nThe phase prefix (`create-plan-`, `execute-plan-`, …) keeps the pipeline phases distinguishable in\nthe session list.\n\nThen offer the alternative: one line offering to clear the current session (vendor-agnostic —\n`\u002Fclear` is only the example; use the clear command of the agent tool in use) and run the next\nphase here, then the same labelled blocks with the bare prompts.\n",{"name":5,"license":15,"metadata":24,"description":7},{"version":25},"1.22","main","12db59437c9d48b9bd62b18888e9974b17adafaf","skills\u002Frefine-ticket",19,"https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit","https:\u002F\u002Feai-org.github.io\u002Fagent-toolkit-docs","https:\u002F\u002Fgithub.com\u002Feai-org","https:\u002F\u002Fmedium.com\u002Fengineering-in-the-age-of-ai","2026-11-14 22:36:21",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add eai-org\u002Fagent-toolkit --skill refine-ticket",{"tool":41,"command":42},"bunx","bunx skills add eai-org\u002Fagent-toolkit --skill refine-ticket",{"tool":44,"command":45},"pnpm","pnpm dlx skills add eai-org\u002Fagent-toolkit --skill refine-ticket","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Frefine-ticket\u002FSKILL.md",true,[],[50,56,63,70,77,84],{"skillNo":51,"name":52,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M74PKAVPTTY5PSSAWHCRVY9T","no-frontmatter","https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit\u002Fblob\u002Fmain\u002Ftest\u002Fcompact-skill-creator\u002Ffixtures\u002Fno-frontmatter\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M74PK8J99W7V3669Y4JG2JKV","other-name","Fixture skill whose name differs from its folder.","https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit\u002Fblob\u002Fmain\u002Ftest\u002Fcompact-skill-creator\u002Ffixtures\u002Fname-mismatch\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M74PK6T9DHVRCNHTEV2ZA4Y3","md-off","A fixture skill whose folder turns the line length off below a root that sets 99.","https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit\u002Fblob\u002Fmain\u002Ftest\u002Fcompact-skill-creator\u002Ffixtures\u002Fmd-off\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M74PK4H4N3D290V4C08M4DGY","long-line","Fixture skill with one prose line of 100 characters, over the fixtures' limit of 99.","https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit\u002Fblob\u002Fmain\u002Ftest\u002Fcompact-skill-creator\u002Ffixtures\u002Flong-line\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M74PK2DJ2MCR5KFPMYVQWNJG","flag-without-flow","Fixture skill with the flag and no type.","https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit\u002Fblob\u002Fmain\u002Ftest\u002Fcompact-skill-creator\u002Ffixtures\u002Fflag-without-flow\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M74PK03XGEBQ986FDAE46WCM","double-backtick","A fixture skill with double-backtick code spans holding a link template and an overrun.","https:\u002F\u002Fgithub.com\u002Feai-org\u002Fagent-toolkit\u002Fblob\u002Fmain\u002Ftest\u002Fcompact-skill-creator\u002Ffixtures\u002Fdouble-backtick\u002FSKILL.md",[],[]]