[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M759X33HC1XRDFEAR684GWPC":3,"skill-same:01M759X33HC1XRDFEAR684GWPC":50},{"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":28,"commitSha":29,"skillDirectory":30,"forksCount":27,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":33,"ownerDescription":34,"updatedAt":35,"install":36,"resources":49},"01M759X33HC1XRDFEAR684GWPC","write-an-issue",null,"Render and create the canonical design-of-record GitHub issue — the two-reader decision-surface template, density tiers (chore \u002F standard \u002F PRD), scratchpad drafting, labels, and Projects board placement. Use whenever any issue is created — from brainstorming's terminus, once per break-into-subissues slice, or from the development gate's chore-tier auto-create.","harmoniqs\u002Famicode","harmoniqs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F199011497?v=4","01M759PQCJ9Y093EC5HC3344DW","Harmoniqs","01M759PQD5S85W68FZKV3XD1X0",7,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Fskills\u002Fwrite-an-issue\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: write-an-issue\ndescription: Render and create the canonical design-of-record GitHub issue — the two-reader decision-surface template, density tiers (chore \u002F standard \u002F PRD), scratchpad drafting, labels, and Projects board placement. Use whenever any issue is created — from brainstorming's terminus, once per break-into-subissues slice, or from the development gate's chore-tier auto-create.\nagents: []\nsurface: public\nsource: amicode\nrevision: 2\n---\n\n# Write an Issue\n\nOwns the **canonical GitHub issue**: the two-reader decision-surface template, the density tiers, the scratchpad drafting convention, label management, and Projects board placement. Every issue-creation path funnels here — `brainstorming`'s terminus (design-of-record), `break-into-subissues` (TDD-ready slices), and the **development gate** (chore-tier auto-create when package work starts without an issue).\n\nThis skill owns *format and creation*, not content: `brainstorming` owns the design, `break-into-subissues` owns slicing, the gate owns the trigger. The body this skill writes is what `implement-issue` parses on pickup — the section names below are a contract; do not drift them.\n\n## The template (two-reader decision-surface layout)\n\nA `> [!IMPORTANT]` decision surface for the reader who only needs the *why*, over execution detail for the reader who implements. Rules across all tiers: **no file paths, no code** (the implementer reads current code; Prior Art points at modules), decision-complete, testable criteria, **include-if-present** (a section with no content is omitted, never left as an empty heading).\n\n```markdown\n> [!IMPORTANT]\n> **Problem** — \u003Cwhat's broken \u002F wanted, and why it matters>\n> **Approach** — \u003Cthe chosen direction, one paragraph>\n> **Approaches considered** — \u003Calternatives + why rejected>          (PRD tier)\n> **Scope** — in: \u003C…> · out: \u003C…>\n> **Assumptions** — \u003Cwhat we're taking as true>\n\n## Acceptance Criteria\n- [ ] \u003Ca testable behavior — a failing test can be written for it directly>\n\n## Testing Decisions\n\u003Cwhich existing suites to extend (reuse-first); create new only for genuinely new surface>\n\n## Key Decisions\n\u003Cdecision-complete, slice-local when rendered as a sub-issue>\n\n### Data Contracts                                                     (PRD tier, when interfaces change)\n\u003Cshapes, invariants, ownership>\n\n## Constraints & Invariants\n\u003Cwhat must remain true>\n\n## Prior Art\n\u003Cmodules \u002F demos \u002F pulses to read first>\n\n## Source\n\u003CPart of #N · durable-record link · Blocked by #N — human-readable mirrors of native edges>\n\n## Notes\n\u003Ceverything else>\n```\n\n## Density tiers\n\n| Tier | When | Body |\n|---|---|---|\n| **chore** | localized fix, small ask, **development-gate auto-create** | title + one-paragraph `**Problem**` + optional short Acceptance Criteria — the issue IS the whole record |\n| **standard** | a single-slice feature or fix | decision surface + Acceptance Criteria + Testing Decisions + Key Decisions + Constraints & Invariants |\n| **PRD** | multi-slice design-of-record (the input `break-into-subissues` decomposes) | the full layout, incl. Approaches Considered + Data Contracts |\n\n## Procedure\n\n### 1. Gather the content\n- From `brainstorming`: the approved design-of-record.\n- From `break-into-subissues`: one slice spec per call (Acceptance Criteria, Testing Decisions, Key Decisions, Source lines).\n- From the development gate: the user's ask, verbatim enough to title faithfully.\n\n### 2. Choose the density tier\nGate auto-creates are always **chore**. A single deliverable is **standard**. A design that will be decomposed is **PRD**. When in doubt, drop a tier — ceremony on a small issue is waste; a missing why on a big one is churn.\n\n### 3. Draft locally (scratchpad)\nRender the body to the **personal vault's `scratchpad\u002F`** (the `rw`\u002F`kind=personal` mount — resolve it via the `amico-vault` rules, never hardcode the mount name). Nothing outward-facing exists yet: no issue, no branch, no PR.\n\n### 4. Resolve repo + labels\nThe code-owning repo is the target. Ensure the `afk` and `hitl` labels exist there (`gh label create \u003Cname> -R \u003Cowner>\u002F\u003Crepo>` if absent). Apply the label the caller supplied; the gate's auto-create defaults to `hitl` (safe default — an unlabelled issue is treated as HITL by `implement-issue`).\n\n### 5. Approval gate\n- **standard \u002F PRD** — present the local draft and publish only on explicit user approval (\"nothing outward-facing before approval\", per `brainstorming`). Present it **rendered, not raw**: decision surface as a skimmable card, Acceptance Criteria as a checklist, and mathematical content typeset — inline LaTeX for symbols ($\\hat H$, $\\Omega_{\\max}$), display equations for objectives and derivations, quantities in the researcher's notation (`F = 0.9982`, `2.1e-4`, tabular-nums where digits align). This is the **same render `implement-issue` shows at pickup** (its Step 1.5) — the approver and the implementer see the same brief.\n- **chore** — **auto-publish**. The chore tier exists to unblock development the moment the gate fires; an approval prompt would defeat it. Say what you created in one line and proceed.\n- **standing directive** — a standing AFK directive recorded in the ledger (the user's words + date) is the explicit approval for the arc's filings within its named scope; every filing under it is reported in the loop record (see `develop`'s Standing-directives section — outward-publishing acts always need the word).\n\n### 6. Create the issue\n```bash\ngh issue create -R \u003Cowner>\u002F\u003Crepo> --title \"\u003Ctitle>\" --body-file \u003Cscratchpad-draft> [--label afk|hitl]\n```\nCapture the issue number from the printed URL. Creating the issue creates **no** branch and **no** PR — the branch is born at `implement-issue` pickup, the draft PR at its first commit.\n\n### 7. Board placement\nThe org Projects board is the source of truth for status. Columns: Backlog, Ready, In Progress, In Review, Blocked, Done.\n\n- **a. Read the Status options** — `gh project field-list \u003CN> --owner \u003Corg> --format json`, take the `Status` field's options.\n- **b. Read assignable users** — `gh api repos\u002F\u003Cowner>\u002F\u003Crepo>\u002Fassignees --jq '.[].login'`.\n- **c. Add the card** — `gh project item-add \u003CN> --owner \u003Corg> --url \u003Cissue-url> --format json` → the item id.\n- **d. Set assignee** — `gh issue edit \u003Cn> --add-assignee \u003Clogin>` (when resolved).\n- **e. Set the Status column** — `gh project item-edit --project-id \u003CprojectNodeId> --id \u003CitemId> --field-id \u003CstatusFieldId> --single-select-option-id \u003CoptionId>`. This is the mechanism every other skill references for board moves (`implement-issue`'s In Progress \u002F In Review \u002F Blocked transitions, `break-into-subissues`' initial Blocked mirroring).\n\n**Degraded path (external contributor):** if the user's `gh` auth has no access to the org board, **skip Step 7 silently** — the issue and PR still happen; only the card is absent. Never block issue creation on board access.\n\n**Batched callers:** when `break-into-subissues` passes a status\u002Fassignee resolved once for the whole slice set, apply it without prompting — don't ask N times for N slices.\n\n### 8. Return\n```yaml\nnumber: \u003Cn>\nurl: \u003Cissue-url>\nnode_id: \u003CI_kwDO…>    # gh issue view \u003Cn> --json id --jq .id — break-into-subissues needs it for native edge wiring\n```\n\n## Invariants\n\n- Nothing outward-facing before approval — the **chore tier is the sole exception** (it auto-publishes to unblock the development gate).\n- No file paths, no code in issue bodies.\n- Body-text references (`Part of #N`, `Blocked by #N`) are **human-readable mirrors** of native GraphQL edges — never the source of truth; `break-into-subissues` Step 6 wires the real edges.\n- An unlabelled issue is treated as HITL downstream — label deliberately.\n- Never create a branch or PR at issue-creation time.\n- Never block on board access — degrade to silent skip.\n\n## Composition\n\n- **Called by** `brainstorming` (standard\u002FPRD design-of-record), `break-into-subissues` (once per slice, chore tiers excluded), and the **development gate** in `AGENTS.md` (chore tier, auto-publish).\n- **Consumed by** `implement-issue`, which parses the sections this skill writes (Acceptance Criteria → the RED list; Testing Decisions → the reuse map), and by `develop`, which reads the native edges rather than the body.\n\n## Related skills\n\n- **brainstorming** — produces the design this skill renders.\n- **break-into-subissues** — decomposes a published PRD-tier parent into slices rendered through this skill.\n- **implement-issue** — implements the issues this skill creates.\n","# Write an Issue\n\nOwns the **canonical GitHub issue**: the two-reader decision-surface template, the density tiers, the scratchpad drafting convention, label management, and Projects board placement. Every issue-creation path funnels here — `brainstorming`'s terminus (design-of-record), `break-into-subissues` (TDD-ready slices), and the **development gate** (chore-tier auto-create when package work starts without an issue).\n\nThis skill owns *format and creation*, not content: `brainstorming` owns the design, `break-into-subissues` owns slicing, the gate owns the trigger. The body this skill writes is what `implement-issue` parses on pickup — the section names below are a contract; do not drift them.\n\n## The template (two-reader decision-surface layout)\n\nA `> [!IMPORTANT]` decision surface for the reader who only needs the *why*, over execution detail for the reader who implements. Rules across all tiers: **no file paths, no code** (the implementer reads current code; Prior Art points at modules), decision-complete, testable criteria, **include-if-present** (a section with no content is omitted, never left as an empty heading).\n\n```markdown\n> [!IMPORTANT]\n> **Problem** — \u003Cwhat's broken \u002F wanted, and why it matters>\n> **Approach** — \u003Cthe chosen direction, one paragraph>\n> **Approaches considered** — \u003Calternatives + why rejected>          (PRD tier)\n> **Scope** — in: \u003C…> · out: \u003C…>\n> **Assumptions** — \u003Cwhat we're taking as true>\n\n## Acceptance Criteria\n- [ ] \u003Ca testable behavior — a failing test can be written for it directly>\n\n## Testing Decisions\n\u003Cwhich existing suites to extend (reuse-first); create new only for genuinely new surface>\n\n## Key Decisions\n\u003Cdecision-complete, slice-local when rendered as a sub-issue>\n\n### Data Contracts                                                     (PRD tier, when interfaces change)\n\u003Cshapes, invariants, ownership>\n\n## Constraints & Invariants\n\u003Cwhat must remain true>\n\n## Prior Art\n\u003Cmodules \u002F demos \u002F pulses to read first>\n\n## Source\n\u003CPart of #N · durable-record link · Blocked by #N — human-readable mirrors of native edges>\n\n## Notes\n\u003Ceverything else>\n```\n\n## Density tiers\n\n| Tier | When | Body |\n|---|---|---|\n| **chore** | localized fix, small ask, **development-gate auto-create** | title + one-paragraph `**Problem**` + optional short Acceptance Criteria — the issue IS the whole record |\n| **standard** | a single-slice feature or fix | decision surface + Acceptance Criteria + Testing Decisions + Key Decisions + Constraints & Invariants |\n| **PRD** | multi-slice design-of-record (the input `break-into-subissues` decomposes) | the full layout, incl. Approaches Considered + Data Contracts |\n\n## Procedure\n\n### 1. Gather the content\n- From `brainstorming`: the approved design-of-record.\n- From `break-into-subissues`: one slice spec per call (Acceptance Criteria, Testing Decisions, Key Decisions, Source lines).\n- From the development gate: the user's ask, verbatim enough to title faithfully.\n\n### 2. Choose the density tier\nGate auto-creates are always **chore**. A single deliverable is **standard**. A design that will be decomposed is **PRD**. When in doubt, drop a tier — ceremony on a small issue is waste; a missing why on a big one is churn.\n\n### 3. Draft locally (scratchpad)\nRender the body to the **personal vault's `scratchpad\u002F`** (the `rw`\u002F`kind=personal` mount — resolve it via the `amico-vault` rules, never hardcode the mount name). Nothing outward-facing exists yet: no issue, no branch, no PR.\n\n### 4. Resolve repo + labels\nThe code-owning repo is the target. Ensure the `afk` and `hitl` labels exist there (`gh label create \u003Cname> -R \u003Cowner>\u002F\u003Crepo>` if absent). Apply the label the caller supplied; the gate's auto-create defaults to `hitl` (safe default — an unlabelled issue is treated as HITL by `implement-issue`).\n\n### 5. Approval gate\n- **standard \u002F PRD** — present the local draft and publish only on explicit user approval (\"nothing outward-facing before approval\", per `brainstorming`). Present it **rendered, not raw**: decision surface as a skimmable card, Acceptance Criteria as a checklist, and mathematical content typeset — inline LaTeX for symbols ($\\hat H$, $\\Omega_{\\max}$), display equations for objectives and derivations, quantities in the researcher's notation (`F = 0.9982`, `2.1e-4`, tabular-nums where digits align). This is the **same render `implement-issue` shows at pickup** (its Step 1.5) — the approver and the implementer see the same brief.\n- **chore** — **auto-publish**. The chore tier exists to unblock development the moment the gate fires; an approval prompt would defeat it. Say what you created in one line and proceed.\n- **standing directive** — a standing AFK directive recorded in the ledger (the user's words + date) is the explicit approval for the arc's filings within its named scope; every filing under it is reported in the loop record (see `develop`'s Standing-directives section — outward-publishing acts always need the word).\n\n### 6. Create the issue\n```bash\ngh issue create -R \u003Cowner>\u002F\u003Crepo> --title \"\u003Ctitle>\" --body-file \u003Cscratchpad-draft> [--label afk|hitl]\n```\nCapture the issue number from the printed URL. Creating the issue creates **no** branch and **no** PR — the branch is born at `implement-issue` pickup, the draft PR at its first commit.\n\n### 7. Board placement\nThe org Projects board is the source of truth for status. Columns: Backlog, Ready, In Progress, In Review, Blocked, Done.\n\n- **a. Read the Status options** — `gh project field-list \u003CN> --owner \u003Corg> --format json`, take the `Status` field's options.\n- **b. Read assignable users** — `gh api repos\u002F\u003Cowner>\u002F\u003Crepo>\u002Fassignees --jq '.[].login'`.\n- **c. Add the card** — `gh project item-add \u003CN> --owner \u003Corg> --url \u003Cissue-url> --format json` → the item id.\n- **d. Set assignee** — `gh issue edit \u003Cn> --add-assignee \u003Clogin>` (when resolved).\n- **e. Set the Status column** — `gh project item-edit --project-id \u003CprojectNodeId> --id \u003CitemId> --field-id \u003CstatusFieldId> --single-select-option-id \u003CoptionId>`. This is the mechanism every other skill references for board moves (`implement-issue`'s In Progress \u002F In Review \u002F Blocked transitions, `break-into-subissues`' initial Blocked mirroring).\n\n**Degraded path (external contributor):** if the user's `gh` auth has no access to the org board, **skip Step 7 silently** — the issue and PR still happen; only the card is absent. Never block issue creation on board access.\n\n**Batched callers:** when `break-into-subissues` passes a status\u002Fassignee resolved once for the whole slice set, apply it without prompting — don't ask N times for N slices.\n\n### 8. Return\n```yaml\nnumber: \u003Cn>\nurl: \u003Cissue-url>\nnode_id: \u003CI_kwDO…>    # gh issue view \u003Cn> --json id --jq .id — break-into-subissues needs it for native edge wiring\n```\n\n## Invariants\n\n- Nothing outward-facing before approval — the **chore tier is the sole exception** (it auto-publishes to unblock the development gate).\n- No file paths, no code in issue bodies.\n- Body-text references (`Part of #N`, `Blocked by #N`) are **human-readable mirrors** of native GraphQL edges — never the source of truth; `break-into-subissues` Step 6 wires the real edges.\n- An unlabelled issue is treated as HITL downstream — label deliberately.\n- Never create a branch or PR at issue-creation time.\n- Never block on board access — degrade to silent skip.\n\n## Composition\n\n- **Called by** `brainstorming` (standard\u002FPRD design-of-record), `break-into-subissues` (once per slice, chore tiers excluded), and the **development gate** in `AGENTS.md` (chore tier, auto-publish).\n- **Consumed by** `implement-issue`, which parses the sections this skill writes (Acceptance Criteria → the RED list; Testing Decisions → the reuse map), and by `develop`, which reads the native edges rather than the body.\n\n## Related skills\n\n- **brainstorming** — produces the design this skill renders.\n- **break-into-subissues** — decomposes a published PRD-tier parent into slices rendered through this skill.\n- **implement-issue** — implements the issues this skill creates.\n",{"name":5,"agents":24,"source":25,"surface":26,"revision":27,"description":7},[],"amicode","public",2,"main","bf84fdd4c1494800695bd5881702b3118dbf98be","packages\u002Fextension\u002Fskills\u002Fwrite-an-issue","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode","https:\u002F\u002Fgithub.com\u002Fharmoniqs","harmoniqs.ai","research tools, for researchers, by reseachers","2026-11-12 14:46:24",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add harmoniqs\u002Famicode --skill write-an-issue",{"tool":42,"command":43},"bunx","bunx skills add harmoniqs\u002Famicode --skill write-an-issue",{"tool":45,"command":46},"pnpm","pnpm dlx skills add harmoniqs\u002Famicode --skill write-an-issue","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Fskills\u002Fwrite-an-issue\u002FSKILL.md",true,[],[51,58,65,71,78,85],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M759XGHEQRJ1GWZTPRFF9Z1W","malformed","Frontmatter that parses as YAML but is missing the required name field.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fmalformed\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M759XDVQ1PYPMT876X8J21TQ","duplicated","Second skill carrying the duplicated frontmatter name.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fdup-two\u002FSKILL.md",[],[],{"skillNo":66,"name":60,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M759XBZYBHF38JDWSRHAC6E1","First skill carrying the duplicated frontmatter name.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fdup-one\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M759XAQBSP29BKTTXR1WF2D7","drifted","A skill whose API claims have drifted from the fixture packages.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fdrifted\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M759X8CNBPVK98C6M45D0QMB","clean","A clean skill whose every extracted claim resolves against the fixture packages.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fclean\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"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},"01M759X73H6N2G0VDH8CJ5TF11","broken-paths","A skill with a broken relative link and a broken cited package path.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fbroken-paths\u002FSKILL.md",[],[]]