njdaniel/conch / .claude/skills/issue-writer
issue-writer
UnverifiedWrite or groom GitHub issues to the "executable cold" standard — template sections, testable acceptance criteria, correct labels and blocked-by links. Use when filing issues, promoting stubs, or grooming the backlog.
issue-writer
CLAUDE.md rule 7: every issue must be executable by a fresh session with zero
chat context. The task template (.github/ISSUE_TEMPLATE/task.md) is
normative; this skill is how to fill it so that's actually true. All GitHub
work goes through gh.
The five sections
- Context — why this exists, linking the governing ADR or design doc. The test: could a session with no chat history make the right judgment calls from this section alone? Decisions already made (and by whom) go here, not in chat.
- Files — the files/packages expected to change. This also determines
area/*labeling, which is what makes parallel dispatch safe (disjoint areas only). - Acceptance criteria — testable statements, checkboxed. "Works
correctly" is not a criterion; "
conch approve <id>on a terminal-state approval exits nonzero with one error line" is. - Required tests — the tests the change must ship with. Approval-path changes always include the full request → notify → resolve → audit chain test (rule 3) — say so explicitly.
- Blocked by — links to open issues that must merge first, or the word "nothing". Keep these true: stale blocked-by chains stall the unattended runner.
Labels and milestones
area/*— always, from the Files section; it gates parallel dispatch.approval-path— whenever the approval chain is touched (Nick merges).agent/todois human-only (Nick's approval signal for the unattended runner) — never apply it yourself.agent/readyis machine-managed byconch-agent sync— never touch it. (Two-tag model: agent-dispatch.md.)- Milestone: the phase it belongs to. Stubs stay stubs until their milestone is next (promotion rule, principal-review skill); promote by rewriting to this standard, not by relabeling.
Worked example
gh issue create \
--title "REST: GET /v1/approvals/{id} — single-approval read parity" \
--label area/server --milestone "P2 Hardening" \
--body-file issue.md # the five sections above
Before filing, self-check: cold-executable Context; testable criteria; Files ↔ labels agree; Blocked-by verified against open issues.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |