[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77XRK6015SZ8TZSGETAYNF6":3,"skill-same:01M77XRK6015SZ8TZSGETAYNF6":61},{"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":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":31,"install":32,"resources":44},"01M77XRK6015SZ8TZSGETAYNF6","vs-to-issues",null,"Use when asked to turn a plan, spec, RFC, or brief into vertical-slice GitHub issues with handoff-ready bodies.","vltansky\u002Fvs","vltansky","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F5851280?v=4","01M77XJAE230PB81N52XJHT5A1","Vlad Tansky","01M77XJAET1CMBAZ2TWTT4ZQT8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-to-issues\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: vs-to-issues\ndescription: \"Use when asked to turn a plan, spec, RFC, or brief into vertical-slice GitHub issues with handoff-ready bodies.\"\ndisable-model-invocation: true\n---\n\n# To Issues\n\nTake a plan, spec, RFC, or brief and turn it into a set of GitHub issues that an agent (or human) can pick up and ship independently. Each issue is a vertical slice with its own acceptance criteria, labeled for human-in-the-loop or AFK execution, and wired into a blocking dependency graph.\n\nThis skill exists because most plans die at the \"now what?\" moment. The plan is solid but the jump from prose to concrete, bounded, assignable work is too high. `\u002Fvs-to-issues` makes that jump mechanical.\n\n\u003CHARD-GATE>\nDo NOT start implementing the plan. Output is a set of GitHub issues (via `gh issue create`) and a short index comment. Code comes later via `\u002Fvs-build-it` or direct agent work on the issues.\n\u003C\u002FHARD-GATE>\n\n## Codex Goal Integration\n\nWhen running in Codex, use\n[`..\u002Fvs-internal-shared\u002Freferences\u002Fcodex-goal.md`](..\u002Fvs-internal-shared\u002Freferences\u002Fcodex-goal.md)\nfor standalone-goal rules.\n\nTo-issues normally contributes handoff material to a larger planning workflow.\nIf invoked as the whole task, it may own a goal to turn the source plan into\ndurable GitHub issues or draft issue files. Complete that goal only after the\ndraft set is approved and created, or after draft files\u002Findex are written when\nGitHub issue creation is unavailable or not approved. Do not treat the later\nimplementation of those issues as part of the to-issues goal.\n\n## When to use\n\n- A plan or spec exists (in chat, in `~\u002F.vs\u002F$PROJECT_ID\u002Fspecs\u002F`, in a doc, or verbally) and the user wants to file it as tickets\n- The user wants to hand off work to async agents and needs durable issue bodies that survive reorg\n- A PRD-shaped doc exists and the implementation is non-trivial (3+ slices worth of work)\n\nIf the plan is still fuzzy on terminology or framing, route to `\u002Fvs-shape-it` first. If the plan hasn't been stress-tested, route to `\u002Fvs-pushback` first.\n\n## Phase 0: Read the plan and the repo\n\nBefore slicing:\n\n1. **Read the source plan.** Full text. Do not skim. If the plan references external docs (linked specs, related issues, ADRs), read those too.\n2. **Read the repo — and verify you're reading the *current* repo.** Skim the modules the plan touches, existing issue labels (`gh label list`), and any `AGENTS.md` \u002F `CLAUDE.md` \u002F `CONTRIBUTING.md` conventions.\n\n   A stale checkout silently produces confident, wrong issues. Before citing any code:\n\n   ```bash\n   git fetch origin -q && git rev-list --count HEAD..origin\u002F\u003Cdefault-branch>\n   ```\n\n   If that number is non-trivial, read via `git show origin\u002F\u003Cbranch>:\u003Cpath>` rather than the working tree. A feature landing after your checkout can move the live code path entirely — the module the plan *sounds* like it touches may be dead code. Confirm the path is live (recent commits, referenced by current callers) before building an issue on it.\n\n   When you find a module that looks right but isn't, **say so in the issue**. A \"don't start here, and here's why\" note is worth more than the correct pointer alone — it pre-empts the same wrong turn by the next reader.\n3. **Read issue tracker conventions.** If `docs\u002Fagents\u002Fissue-tracker.md` exists, follow it. Otherwise, check `AGENTS.md` for an `Agent skills` \u002F issue workflow section. If neither exists:\n   - GitHub remote present → use GitHub issues.\n   - No GitHub remote → draft markdown issues under `~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F` and do not call `gh issue create`.\n4. **Check for existing issues** that overlap. Use `gh issue list --search \"\u003Crelevant keyword>\"`. If GraphQL quota blocks `gh issue list`, parse `REPO` from `git config --get remote.origin.url` and use REST search:\n   ```bash\n   REPO=$(git config --get remote.origin.url | sed -E 's#\\.git$##; s#.*[:\u002F]([^\u002F]+\u002F[^\u002F]+)$#\\1#')\n   gh api \"search\u002Fissues?q=repo:$REPO+is:issue+state:open+\u003Ckeyword>\"\n   ```\n   Do not create duplicates; extend or link instead.\n\nResolve `$PROJECT_ID` per [`..\u002Fvs-internal-shared\u002FSKILL.md`](..\u002Fvs-internal-shared\u002FSKILL.md) so the index file ends up in the right place.\n\n## Label contract\n\nMap canonical roles to the repo's actual labels before drafting issues. Use existing labels when they clearly match; create only missing defaults.\n\n| Role | Default label | Meaning |\n|---|---|---|\n| State: needs review | `needs-review` | Draft or stub, not ready for execution |\n| State: ready for agent | `ready-for-agent` | Self-contained enough for agent work |\n| State: ready for human | `ready-for-human` | Needs human judgment before or during execution |\n| Category: bug | `bug` | Defect \u002F regression work |\n| Category: enhancement | `enhancement` | New or changed behavior |\n| AFK eligibility | `afk-safe` | Safe for unattended agent runs |\n| Human-in-loop note | `hitl` | A specific human decision point remains |\n\nEvery created issue gets exactly one state label and at most one category label. Use `afk-safe` and `hitl` as optional tags, not as replacements for the state label. If a local convention maps these roles to different labels, use the local names consistently.\n\n## Phase 1: Decide slice granularity\n\nA good issue is a **vertical slice**: a small end-to-end change that, when merged, moves the product forward visibly. Horizontal slicing (DB layer issue, then API layer issue, then UI layer issue) is the failure mode — each horizontal slice is un-shippable alone and the integration issue becomes a mega-issue.\n\nRules for slicing:\n\n- Each slice should be mergeable in isolation without breaking the build\n- Each slice should be describable in one sentence ending in a verb (\"User can search orders by date\")\n- If a slice requires another slice's code to exist before it can be tested, add a `blocked by` dependency, don't merge them\n- If you can't describe a slice without listing 6+ sub-tasks, it's too big — split it\n- If two slices share >70% of the same implementation, they're probably one slice with two acceptance criteria\n\nTypical slice count for a medium plan: **3–8 issues.** Fewer than 3 and you don't need this skill. More than 12 and the plan is too big to decompose in one pass — push back and ask the user to pick a Phase 1.\n\n### When the work isn't slice-shaped\n\nSome work can't be sliced yet because it's gated on something outside the repo — a permission, a vendor limit, an approval, a decision someone else owns. Slicing it produces fiction: acceptance criteria for code nobody can run.\n\nRecognize this when the honest status is *\"possible, but not by us, not today.\"* File **one proposal issue** instead of a slice set, and use the [proposal shape](#proposal-issues) in Phase 3. Decompose into slices later, once the gate clears.\n\nDo not disguise a blocked proposal as a ready slice. An issue labeled `ready-for-agent` that cannot be started burns exactly the trust the label exists to protect.\n\n## Phase 2: Tag for execution mode\n\nEvery issue gets one of three execution tags:\n\n| Role | Default label | Use when |\n|---|---|---|\n| State: ready for human | `ready-for-human` + optional `hitl` | Design decisions, UX calls, ambiguous specs, risky migrations |\n| State: ready for agent | `ready-for-agent` + optional `afk-safe` | Clear acceptance criteria, stable interface, no surprises expected |\n| State: needs review | `needs-review` | Use for drafts or stubs that need a second pass |\n\nDefault to `ready-for-human` unless the issue is genuinely afk-safe. If in doubt, the issue is not afk-safe. AFK issues that stall on a design question waste the agent's budget and the human's trust.\n\nAFK-safe checklist (all must be true):\n\n- Acceptance criteria are behavioral and checkable without asking the user\n- No \"we'll figure it out\" clauses\n- No net-new architecture decisions\n- The agent has everything it needs to verify success (test command, eval, or observable state)\n- Failure mode is reversible (branch work, not prod push)\n\n## Phase 3: Write issue bodies as AGENT-BRIEF\n\nEvery issue body follows the AGENT-BRIEF shape from [`.\u002Freferences\u002Fagent-brief.md`](.\u002Freferences\u002Fagent-brief.md). Summary:\n\n- **Context.** One paragraph. Why this slice exists. What the user outcome is.\n- **Behavioral outcome.** What the system does after this is shipped, described as observable behavior (not \"edit file X\"). A future reader should understand the change without knowing the current file layout.\n- **Acceptance criteria.** Bullet list. Each item is checkable by running a command or observing state. No `implements the design`, no `code reviewed`. Phrase as `When \u003Cinput>, then \u003Cobservable output>`.\n- **Out of scope.** Explicit bullets of what this slice does *not* do. Prevents scope creep during execution.\n- **Dependencies.** Blocking issues listed as `Blocked by #\u003Cn>`. GitHub renders these as a task graph.\n\nDurability rules (the whole reason this format exists):\n\n- **No file paths.** The repo reorgs; file paths rot. Describe the change in terms of modules\u002Ffeatures, not paths.\n- **No line numbers.** Same reason.\n- **No \"currently X\" references** unless the current state is documented elsewhere. Describe the target state, not the delta.\n- **No private shorthand.** If the issue references a concept, define it or link to `CONTEXT.md`.\n- **No procedural steps** (\"first do X, then Y\"). Describe the outcome; let the implementer choose the path.\n\nIf the plan has details that *are* procedural or file-specific, they belong in a comment on the issue, a collapsed agent-context block (below), or `~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F\u003Cissue-number>-notes.md` — not in the durable prose.\n\n### Two audiences, one body\n\nAn issue is read by a human deciding *whether* to do this, and by an agent working out *how*. Those need different things, and mixing them serves neither: the human wades through line numbers, the agent gets prose without pointers.\n\nWhen an issue carries real technical context, split the body:\n\n1. **Prose section (default, visible).** Written for the human. Product framing, concrete examples, why it matters, what's blocking. No file paths, no line numbers — the durability rules apply in full.\n2. **Agent section (collapsed).** Everything volatile and precise, fenced in `\u003Cdetails>`:\n\n   ```markdown\n   \u003Cdetails>\n   \u003Csummary>\u003Cb>Agent context\u003C\u002Fb> — technical detail, code references, prior art\u003C\u002Fsummary>\n\n   ...file table, exact functions, permalinks, prior art, unverified list...\n\n   \u003C\u002Fdetails>\n   ```\n\nWhy this works: the durability rules exist because rot is invisible and misleads. Inside a `\u003Cdetails>` block that is **explicitly pinned to a commit SHA**, rot is legible — a reader who checks the SHA knows what they're holding. So the collapsed section may carry what the prose must not: paths, line numbers, code excerpts, \"start here \u002F not there\" pointers.\n\nRules for the agent section:\n\n- **Pin it.** State the SHA or branch the references were read at (`All line references are against origin\u002Fmaster at \u003Csha>`). Unpinned line numbers are the thing the durability rules ban.\n- **Show, don't just cite.** Paste the 5–10 load-bearing lines. A reader who can see the current code in the issue can diff it against reality without a checkout.\n- **Include prior art.** If someone already solved this — in this repo or another — link the file and quote the mechanism. Existing production code is the strongest possible evidence that an approach works.\n- **Keep an `Unverified` list.** Name what you could not confirm and why. This is what separates a brief that can be trusted from one that must be re-derived.\n\nSkip the split entirely for a straightforward slice. Two sections on a 200-word issue is ceremony.\n\n### Proposal issues\n\nFor work gated outside the repo (see Phase 1), replace *Acceptance criteria* with:\n\n- **What \u002F why** — the feature as a product, with **concrete worked examples**. Show the interaction, don't describe it. A two-line before\u002Fafter exchange communicates more than a paragraph of explanation, and it's what makes a proposal forwardable to someone who wasn't in the conversation.\n- **How it would work** — the mechanism, plus the approaches ruled out and *why*. Rejected options carry as much weight as the chosen one; without them the first reviewer re-litigates settled ground.\n- **Known tradeoff** — what this does *not* give you, stated plainly. A proposal that reads as pure upside invites the reviewer to find the catch themselves and distrust everything else.\n- **Blocker** — the single thing standing in the way, who owns it, and what the exact ask is. If everything else is small, say that: *\"this permission is the only thing between us and shipping\"* converts a vague proposal into a decision someone can make.\n- **Scope checklist** — unchecked boxes, with the blocking item first and marked as gating the rest.\n\nLabel these `hitl` (a human decision is required) plus the category label. Do not label them `ready-for-agent`.\n\nWhen the blocker needs a message to another team, **draft that message as an issue comment** rather than sending it. It gets reviewed before it's sent, it's copy-pasteable, and the issue becomes the record of the ask. Include: the likely routing (and any known dead ends — a bot that will refuse, a queue that ignores), the ask framed in terms of the *approver's* interest, the blast radius stated honestly, and a fallback option so a \"no\" still yields a path forward.\n\n## Phase 4: Wire dependencies\n\nAfter drafting issue bodies, build the dependency graph:\n\n- For each issue, list the issues it depends on (must merge first) and the issues it unblocks\n- Use GitHub's native `Blocked by #\u003Cn>` convention in the body — most GitHub UIs render this as a graph\n- If two issues depend on each other, you have one issue; merge them\n- If the graph has a long chain (A → B → C → D → E), flag it: that's a horizontal slice masquerading as verticals\n\nA healthy graph has a shallow root (one or two foundational slices) branching into parallelizable leaves.\n\n## Phase 5: Create the issues\n\nFirst show the **full draft set**: every title, body, label set, dependency edge, and planned creation order. Get one explicit approval for the full set before creating anything. Do not create issues one-by-one while the user is still reviewing later drafts.\n\nUse `gh issue create` for each approved GitHub issue. If GraphQL quota blocks create paths, use REST after deriving `REPO` from `git config --get remote.origin.url`:\n\n```bash\ngh api -X POST \"repos\u002F$REPO\u002Fissues\" \\\n  -f title=\"\u003Cone-sentence slice title>\" \\\n  -f body=@\u002Ftmp\u002Fissue-body.md \\\n  -F labels='[\"ready-for-agent\",\"enhancement\",\"afk-safe\"]'\n```\n\nSuggested flow:\n\n```bash\ngh issue create \\\n  --title \"\u003Cone-sentence slice title>\" \\\n  --body \"$(cat \u003C\u003C'EOF'\n## Context\n...\n\n## Behavioral outcome\n...\n\n## Acceptance criteria\n- When \u003Cinput>, then \u003Cobservable output>\n- ...\n\n## Out of scope\n- ...\n\n## Dependencies\n- Blocked by #\u003Cn>\nEOF\n)\" \\\n  --label \"\u003Cstate-label>,\u003Ccategory-label>,\u003Coptional-tags>\"\n```\n\nRules:\n\n- **Do not auto-create** — show the full draft issue set first, get confirmation, then create\n- Create in dependency order (foundational issues first so their numbers exist before dependents reference them)\n- If the user wants to review all at once, emit the draft as a markdown file under `~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F\u003Cdate>-plan-name.md` and wait for approval\n- Never modify existing issues without confirmation\n\n## Phase 6: Write the index\n\nAfter all issues are created, write an index file to `~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F\u003Cdate>-\u003Cplan-slug>.md`:\n\n```markdown\n# \u003CPlan title> — issues\n\nSource: \u003Clink to plan\u002Fspec\u002FRFC>\nCreated: \u003CYYYY-MM-DD>\n\n## Issues\n\n- [ ] #\u003Cn> \u003Ctitle> — \u003Chuman-in-the-loop|afk> — blocks: #\u003Cm>,#\u003Co>\n- [ ] ...\n\n## Graph\n\n\u003Cascii or mermaid graph of dependencies if the plan warrants it>\n\n## Notes\n\n\u003Canything the agent needs that didn't fit an issue body>\n```\n\nThis index is the single place the user can see the whole plan's state. It's not the source of truth — GitHub is — but it's the human-scale overview.\n\n## Phase 7: Handoff\n\nEmit a handoff block:\n\n```\n## To-Issues Handoff\n\n- Plan source: \u003Cpath or link>\n- Issues created: \u003Ccount> (\u003Cn> human-in-the-loop, \u003Cm> afk)\n- Index: ~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F\u003Cfile>.md\n- Codex Goal: completed \u002F left active because ... \u002F unavailable\n- Dependency depth: \u003Cmax blocked-by chain length>\n- Recommended next step:\n  - AFK: run `\u002Fvs-build-it` or dispatch agents against the afk-labeled issues\n  - HITL: pick up the first unblocked human-in-the-loop issue yourself\n```\n\n## References\n\n- Agent-brief format: [`references\u002Fagent-brief.md`](.\u002Freferences\u002Fagent-brief.md)\n- Shared conventions (project ID, storage): [`..\u002Fvs-internal-shared\u002FSKILL.md`](..\u002Fvs-internal-shared\u002FSKILL.md)\n\n## Output style\n\nApply the [shared output style](..\u002Fvs-internal-shared\u002Freferences\u002Foutput-style.md)\nto every user-facing message.\n\n## Workflow\n\nDirect: emit **Next** only. Composed: return to caller.\n\n**Prev:** `\u002Fvs-shape-it` | `\u002Fvs-pushback`\n**Next:** `\u002Fvs-build-it`\n**Relevant:** `\u002Fvs-improve` | `\u002Fvs-setup-adr`\n","# To Issues\n\nTake a plan, spec, RFC, or brief and turn it into a set of GitHub issues that an agent (or human) can pick up and ship independently. Each issue is a vertical slice with its own acceptance criteria, labeled for human-in-the-loop or AFK execution, and wired into a blocking dependency graph.\n\nThis skill exists because most plans die at the \"now what?\" moment. The plan is solid but the jump from prose to concrete, bounded, assignable work is too high. `\u002Fvs-to-issues` makes that jump mechanical.\n\n\u003CHARD-GATE>\nDo NOT start implementing the plan. Output is a set of GitHub issues (via `gh issue create`) and a short index comment. Code comes later via `\u002Fvs-build-it` or direct agent work on the issues.\n\u003C\u002FHARD-GATE>\n\n## Codex Goal Integration\n\nWhen running in Codex, use\n[`..\u002Fvs-internal-shared\u002Freferences\u002Fcodex-goal.md`](..\u002Fvs-internal-shared\u002Freferences\u002Fcodex-goal.md)\nfor standalone-goal rules.\n\nTo-issues normally contributes handoff material to a larger planning workflow.\nIf invoked as the whole task, it may own a goal to turn the source plan into\ndurable GitHub issues or draft issue files. Complete that goal only after the\ndraft set is approved and created, or after draft files\u002Findex are written when\nGitHub issue creation is unavailable or not approved. Do not treat the later\nimplementation of those issues as part of the to-issues goal.\n\n## When to use\n\n- A plan or spec exists (in chat, in `~\u002F.vs\u002F$PROJECT_ID\u002Fspecs\u002F`, in a doc, or verbally) and the user wants to file it as tickets\n- The user wants to hand off work to async agents and needs durable issue bodies that survive reorg\n- A PRD-shaped doc exists and the implementation is non-trivial (3+ slices worth of work)\n\nIf the plan is still fuzzy on terminology or framing, route to `\u002Fvs-shape-it` first. If the plan hasn't been stress-tested, route to `\u002Fvs-pushback` first.\n\n## Phase 0: Read the plan and the repo\n\nBefore slicing:\n\n1. **Read the source plan.** Full text. Do not skim. If the plan references external docs (linked specs, related issues, ADRs), read those too.\n2. **Read the repo — and verify you're reading the *current* repo.** Skim the modules the plan touches, existing issue labels (`gh label list`), and any `AGENTS.md` \u002F `CLAUDE.md` \u002F `CONTRIBUTING.md` conventions.\n\n   A stale checkout silently produces confident, wrong issues. Before citing any code:\n\n   ```bash\n   git fetch origin -q && git rev-list --count HEAD..origin\u002F\u003Cdefault-branch>\n   ```\n\n   If that number is non-trivial, read via `git show origin\u002F\u003Cbranch>:\u003Cpath>` rather than the working tree. A feature landing after your checkout can move the live code path entirely — the module the plan *sounds* like it touches may be dead code. Confirm the path is live (recent commits, referenced by current callers) before building an issue on it.\n\n   When you find a module that looks right but isn't, **say so in the issue**. A \"don't start here, and here's why\" note is worth more than the correct pointer alone — it pre-empts the same wrong turn by the next reader.\n3. **Read issue tracker conventions.** If `docs\u002Fagents\u002Fissue-tracker.md` exists, follow it. Otherwise, check `AGENTS.md` for an `Agent skills` \u002F issue workflow section. If neither exists:\n   - GitHub remote present → use GitHub issues.\n   - No GitHub remote → draft markdown issues under `~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F` and do not call `gh issue create`.\n4. **Check for existing issues** that overlap. Use `gh issue list --search \"\u003Crelevant keyword>\"`. If GraphQL quota blocks `gh issue list`, parse `REPO` from `git config --get remote.origin.url` and use REST search:\n   ```bash\n   REPO=$(git config --get remote.origin.url | sed -E 's#\\.git$##; s#.*[:\u002F]([^\u002F]+\u002F[^\u002F]+)$#\\1#')\n   gh api \"search\u002Fissues?q=repo:$REPO+is:issue+state:open+\u003Ckeyword>\"\n   ```\n   Do not create duplicates; extend or link instead.\n\nResolve `$PROJECT_ID` per [`..\u002Fvs-internal-shared\u002FSKILL.md`](..\u002Fvs-internal-shared\u002FSKILL.md) so the index file ends up in the right place.\n\n## Label contract\n\nMap canonical roles to the repo's actual labels before drafting issues. Use existing labels when they clearly match; create only missing defaults.\n\n| Role | Default label | Meaning |\n|---|---|---|\n| State: needs review | `needs-review` | Draft or stub, not ready for execution |\n| State: ready for agent | `ready-for-agent` | Self-contained enough for agent work |\n| State: ready for human | `ready-for-human` | Needs human judgment before or during execution |\n| Category: bug | `bug` | Defect \u002F regression work |\n| Category: enhancement | `enhancement` | New or changed behavior |\n| AFK eligibility | `afk-safe` | Safe for unattended agent runs |\n| Human-in-loop note | `hitl` | A specific human decision point remains |\n\nEvery created issue gets exactly one state label and at most one category label. Use `afk-safe` and `hitl` as optional tags, not as replacements for the state label. If a local convention maps these roles to different labels, use the local names consistently.\n\n## Phase 1: Decide slice granularity\n\nA good issue is a **vertical slice**: a small end-to-end change that, when merged, moves the product forward visibly. Horizontal slicing (DB layer issue, then API layer issue, then UI layer issue) is the failure mode — each horizontal slice is un-shippable alone and the integration issue becomes a mega-issue.\n\nRules for slicing:\n\n- Each slice should be mergeable in isolation without breaking the build\n- Each slice should be describable in one sentence ending in a verb (\"User can search orders by date\")\n- If a slice requires another slice's code to exist before it can be tested, add a `blocked by` dependency, don't merge them\n- If you can't describe a slice without listing 6+ sub-tasks, it's too big — split it\n- If two slices share >70% of the same implementation, they're probably one slice with two acceptance criteria\n\nTypical slice count for a medium plan: **3–8 issues.** Fewer than 3 and you don't need this skill. More than 12 and the plan is too big to decompose in one pass — push back and ask the user to pick a Phase 1.\n\n### When the work isn't slice-shaped\n\nSome work can't be sliced yet because it's gated on something outside the repo — a permission, a vendor limit, an approval, a decision someone else owns. Slicing it produces fiction: acceptance criteria for code nobody can run.\n\nRecognize this when the honest status is *\"possible, but not by us, not today.\"* File **one proposal issue** instead of a slice set, and use the [proposal shape](#proposal-issues) in Phase 3. Decompose into slices later, once the gate clears.\n\nDo not disguise a blocked proposal as a ready slice. An issue labeled `ready-for-agent` that cannot be started burns exactly the trust the label exists to protect.\n\n## Phase 2: Tag for execution mode\n\nEvery issue gets one of three execution tags:\n\n| Role | Default label | Use when |\n|---|---|---|\n| State: ready for human | `ready-for-human` + optional `hitl` | Design decisions, UX calls, ambiguous specs, risky migrations |\n| State: ready for agent | `ready-for-agent` + optional `afk-safe` | Clear acceptance criteria, stable interface, no surprises expected |\n| State: needs review | `needs-review` | Use for drafts or stubs that need a second pass |\n\nDefault to `ready-for-human` unless the issue is genuinely afk-safe. If in doubt, the issue is not afk-safe. AFK issues that stall on a design question waste the agent's budget and the human's trust.\n\nAFK-safe checklist (all must be true):\n\n- Acceptance criteria are behavioral and checkable without asking the user\n- No \"we'll figure it out\" clauses\n- No net-new architecture decisions\n- The agent has everything it needs to verify success (test command, eval, or observable state)\n- Failure mode is reversible (branch work, not prod push)\n\n## Phase 3: Write issue bodies as AGENT-BRIEF\n\nEvery issue body follows the AGENT-BRIEF shape from [`.\u002Freferences\u002Fagent-brief.md`](.\u002Freferences\u002Fagent-brief.md). Summary:\n\n- **Context.** One paragraph. Why this slice exists. What the user outcome is.\n- **Behavioral outcome.** What the system does after this is shipped, described as observable behavior (not \"edit file X\"). A future reader should understand the change without knowing the current file layout.\n- **Acceptance criteria.** Bullet list. Each item is checkable by running a command or observing state. No `implements the design`, no `code reviewed`. Phrase as `When \u003Cinput>, then \u003Cobservable output>`.\n- **Out of scope.** Explicit bullets of what this slice does *not* do. Prevents scope creep during execution.\n- **Dependencies.** Blocking issues listed as `Blocked by #\u003Cn>`. GitHub renders these as a task graph.\n\nDurability rules (the whole reason this format exists):\n\n- **No file paths.** The repo reorgs; file paths rot. Describe the change in terms of modules\u002Ffeatures, not paths.\n- **No line numbers.** Same reason.\n- **No \"currently X\" references** unless the current state is documented elsewhere. Describe the target state, not the delta.\n- **No private shorthand.** If the issue references a concept, define it or link to `CONTEXT.md`.\n- **No procedural steps** (\"first do X, then Y\"). Describe the outcome; let the implementer choose the path.\n\nIf the plan has details that *are* procedural or file-specific, they belong in a comment on the issue, a collapsed agent-context block (below), or `~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F\u003Cissue-number>-notes.md` — not in the durable prose.\n\n### Two audiences, one body\n\nAn issue is read by a human deciding *whether* to do this, and by an agent working out *how*. Those need different things, and mixing them serves neither: the human wades through line numbers, the agent gets prose without pointers.\n\nWhen an issue carries real technical context, split the body:\n\n1. **Prose section (default, visible).** Written for the human. Product framing, concrete examples, why it matters, what's blocking. No file paths, no line numbers — the durability rules apply in full.\n2. **Agent section (collapsed).** Everything volatile and precise, fenced in `\u003Cdetails>`:\n\n   ```markdown\n   \u003Cdetails>\n   \u003Csummary>\u003Cb>Agent context\u003C\u002Fb> — technical detail, code references, prior art\u003C\u002Fsummary>\n\n   ...file table, exact functions, permalinks, prior art, unverified list...\n\n   \u003C\u002Fdetails>\n   ```\n\nWhy this works: the durability rules exist because rot is invisible and misleads. Inside a `\u003Cdetails>` block that is **explicitly pinned to a commit SHA**, rot is legible — a reader who checks the SHA knows what they're holding. So the collapsed section may carry what the prose must not: paths, line numbers, code excerpts, \"start here \u002F not there\" pointers.\n\nRules for the agent section:\n\n- **Pin it.** State the SHA or branch the references were read at (`All line references are against origin\u002Fmaster at \u003Csha>`). Unpinned line numbers are the thing the durability rules ban.\n- **Show, don't just cite.** Paste the 5–10 load-bearing lines. A reader who can see the current code in the issue can diff it against reality without a checkout.\n- **Include prior art.** If someone already solved this — in this repo or another — link the file and quote the mechanism. Existing production code is the strongest possible evidence that an approach works.\n- **Keep an `Unverified` list.** Name what you could not confirm and why. This is what separates a brief that can be trusted from one that must be re-derived.\n\nSkip the split entirely for a straightforward slice. Two sections on a 200-word issue is ceremony.\n\n### Proposal issues\n\nFor work gated outside the repo (see Phase 1), replace *Acceptance criteria* with:\n\n- **What \u002F why** — the feature as a product, with **concrete worked examples**. Show the interaction, don't describe it. A two-line before\u002Fafter exchange communicates more than a paragraph of explanation, and it's what makes a proposal forwardable to someone who wasn't in the conversation.\n- **How it would work** — the mechanism, plus the approaches ruled out and *why*. Rejected options carry as much weight as the chosen one; without them the first reviewer re-litigates settled ground.\n- **Known tradeoff** — what this does *not* give you, stated plainly. A proposal that reads as pure upside invites the reviewer to find the catch themselves and distrust everything else.\n- **Blocker** — the single thing standing in the way, who owns it, and what the exact ask is. If everything else is small, say that: *\"this permission is the only thing between us and shipping\"* converts a vague proposal into a decision someone can make.\n- **Scope checklist** — unchecked boxes, with the blocking item first and marked as gating the rest.\n\nLabel these `hitl` (a human decision is required) plus the category label. Do not label them `ready-for-agent`.\n\nWhen the blocker needs a message to another team, **draft that message as an issue comment** rather than sending it. It gets reviewed before it's sent, it's copy-pasteable, and the issue becomes the record of the ask. Include: the likely routing (and any known dead ends — a bot that will refuse, a queue that ignores), the ask framed in terms of the *approver's* interest, the blast radius stated honestly, and a fallback option so a \"no\" still yields a path forward.\n\n## Phase 4: Wire dependencies\n\nAfter drafting issue bodies, build the dependency graph:\n\n- For each issue, list the issues it depends on (must merge first) and the issues it unblocks\n- Use GitHub's native `Blocked by #\u003Cn>` convention in the body — most GitHub UIs render this as a graph\n- If two issues depend on each other, you have one issue; merge them\n- If the graph has a long chain (A → B → C → D → E), flag it: that's a horizontal slice masquerading as verticals\n\nA healthy graph has a shallow root (one or two foundational slices) branching into parallelizable leaves.\n\n## Phase 5: Create the issues\n\nFirst show the **full draft set**: every title, body, label set, dependency edge, and planned creation order. Get one explicit approval for the full set before creating anything. Do not create issues one-by-one while the user is still reviewing later drafts.\n\nUse `gh issue create` for each approved GitHub issue. If GraphQL quota blocks create paths, use REST after deriving `REPO` from `git config --get remote.origin.url`:\n\n```bash\ngh api -X POST \"repos\u002F$REPO\u002Fissues\" \\\n  -f title=\"\u003Cone-sentence slice title>\" \\\n  -f body=@\u002Ftmp\u002Fissue-body.md \\\n  -F labels='[\"ready-for-agent\",\"enhancement\",\"afk-safe\"]'\n```\n\nSuggested flow:\n\n```bash\ngh issue create \\\n  --title \"\u003Cone-sentence slice title>\" \\\n  --body \"$(cat \u003C\u003C'EOF'\n## Context\n...\n\n## Behavioral outcome\n...\n\n## Acceptance criteria\n- When \u003Cinput>, then \u003Cobservable output>\n- ...\n\n## Out of scope\n- ...\n\n## Dependencies\n- Blocked by #\u003Cn>\nEOF\n)\" \\\n  --label \"\u003Cstate-label>,\u003Ccategory-label>,\u003Coptional-tags>\"\n```\n\nRules:\n\n- **Do not auto-create** — show the full draft issue set first, get confirmation, then create\n- Create in dependency order (foundational issues first so their numbers exist before dependents reference them)\n- If the user wants to review all at once, emit the draft as a markdown file under `~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F\u003Cdate>-plan-name.md` and wait for approval\n- Never modify existing issues without confirmation\n\n## Phase 6: Write the index\n\nAfter all issues are created, write an index file to `~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F\u003Cdate>-\u003Cplan-slug>.md`:\n\n```markdown\n# \u003CPlan title> — issues\n\nSource: \u003Clink to plan\u002Fspec\u002FRFC>\nCreated: \u003CYYYY-MM-DD>\n\n## Issues\n\n- [ ] #\u003Cn> \u003Ctitle> — \u003Chuman-in-the-loop|afk> — blocks: #\u003Cm>,#\u003Co>\n- [ ] ...\n\n## Graph\n\n\u003Cascii or mermaid graph of dependencies if the plan warrants it>\n\n## Notes\n\n\u003Canything the agent needs that didn't fit an issue body>\n```\n\nThis index is the single place the user can see the whole plan's state. It's not the source of truth — GitHub is — but it's the human-scale overview.\n\n## Phase 7: Handoff\n\nEmit a handoff block:\n\n```\n## To-Issues Handoff\n\n- Plan source: \u003Cpath or link>\n- Issues created: \u003Ccount> (\u003Cn> human-in-the-loop, \u003Cm> afk)\n- Index: ~\u002F.vs\u002F$PROJECT_ID\u002Fissues\u002F\u003Cfile>.md\n- Codex Goal: completed \u002F left active because ... \u002F unavailable\n- Dependency depth: \u003Cmax blocked-by chain length>\n- Recommended next step:\n  - AFK: run `\u002Fvs-build-it` or dispatch agents against the afk-labeled issues\n  - HITL: pick up the first unblocked human-in-the-loop issue yourself\n```\n\n## References\n\n- Agent-brief format: [`references\u002Fagent-brief.md`](.\u002Freferences\u002Fagent-brief.md)\n- Shared conventions (project ID, storage): [`..\u002Fvs-internal-shared\u002FSKILL.md`](..\u002Fvs-internal-shared\u002FSKILL.md)\n\n## Output style\n\nApply the [shared output style](..\u002Fvs-internal-shared\u002Freferences\u002Foutput-style.md)\nto every user-facing message.\n\n## Workflow\n\nDirect: emit **Next** only. Composed: return to caller.\n\n**Prev:** `\u002Fvs-shape-it` | `\u002Fvs-pushback`\n**Next:** `\u002Fvs-build-it`\n**Relevant:** `\u002Fvs-improve` | `\u002Fvs-setup-adr`\n",{"name":5,"description":7,"disable-model-invocation":24},true,"master","72448991571c9e5f0e76cccf189b8522d442e6eb","skills\u002Fvs-to-issues",1,"https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs","https:\u002F\u002Fgithub.com\u002Fvltansky","2026-11-06 18:47:54",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":24},[34,37,40],{"tool":35,"command":36},"npx","npx skills add vltansky\u002Fvs --skill vs-to-issues",{"tool":38,"command":39},"bunx","bunx skills add vltansky\u002Fvs --skill vs-to-issues",{"tool":41,"command":42},"pnpm","pnpm dlx skills add vltansky\u002Fvs --skill vs-to-issues","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-to-issues\u002FSKILL.md",[45,51,55],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"agents\u002Fopenai.yaml","REFERENCE","参考文档",86,"https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-to-issues\u002Fagents\u002Fopenai.yaml",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fagent-brief.md",6730,"https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-to-issues\u002Freferences\u002Fagent-brief.md",{"path":56,"resourceType":57,"resourceTypeDesc":58,"sizeBytes":59,"sourceHtmlUrl":60},"test\u002Fto-issues.eval.ts","SCRIPT","脚本",2275,"https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-to-issues\u002Ftest\u002Fto-issues.eval.ts",[62,69,75,80,87,92],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M77XSKWFMPKFXM0311QKEJHH","vs-write","Use when asked to write, rewrite, edit, tighten, simplify, or polish prose for clarity, or to put text in STE, ASD-STE100, or controlled language. Produces plain, direct, accessible copy without losing substance or precision.","https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-write\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"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":72,"categories":73,"keywords":74,"publishedAt":19},"01M77XSJNX2V560HSKQKQD67KP","vs-fake-verify","https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-verify\u002Ftest\u002Ffixtures\u002Fpath-end-state\u002Fstub-rejector\u002FSKILL.md",[],[],{"skillNo":76,"name":71,"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":77,"categories":78,"keywords":79,"publishedAt":19},"01M77XSHHBEMMYZ6B4PD384NZH","https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-verify\u002Ftest\u002Ffixtures\u002Fpath-end-state\u002Fstructure-paste\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M77XSE2Y7MW0KP3DTFNEE2E8","vs-verify","Use when asked to verify, prove it works, check completion, or before claiming done. Produces evidence-backed PASS\u002FWARN\u002FFAIL status.","https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-verify\u002Ftest\u002Ffixtures\u002Fpath-end-state\u002Fpublished-pair\u002FSKILL.md",[],[],{"skillNo":88,"name":71,"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":89,"categories":90,"keywords":91,"publishedAt":19},"01M77XSAXFQXNE6VCRC7275Z0X","https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-verify\u002Ftest\u002Ffixtures\u002Fpath-end-state\u002Fphrase-complete-beside\u002FSKILL.md",[],[],{"skillNo":93,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M77XS6R0E9X1E5KKSS00WYSS","https:\u002F\u002Fgithub.com\u002Fvltansky\u002Fvs\u002Fblob\u002Fmaster\u002Fskills\u002Fvs-verify\u002FSKILL.md",[],[]]