iru-draft-github-issue
Invoke as `/iru-draft-github-issue [functional|documentation] [<short description>]`. Interviews the user and writes a complete spec-style GitHub issue, auto-reviewed with `iru-review-github-issue`, o
SKILL.md.claude/skills/iru-draft-github-issue/SKILL.md
GitHubDraft GitHub Issue
Write a fully specified GitHub issue the way a specify-style spec is written: grounded in the codebase, complete,
reviewed for gaps before it exists, and split into dependency-ordered sub-issues when it is too large. Nothing is
created on GitHub until the user confirms in Step 9 (the split skill, if accepted in Step 8, asks its own
confirmation before creating anything). Body templates are in reference/issue-templates.md (relative to this
skill's directory); read it before Step 4.
Never guess. A missing, doubtful or inconsistent point is put to the user as a question.
Use this skill for detailed, spec-style issues; iru-create-github-issue remains the quick path for a simple issue. It is
not for issues that already exist — use iru-review-github-issue or iru-split-github-issue for those.
Step 1 — Confirm this repository is hosted on GitHub
- If
iru-explorealready ran in this conversation, reuse itsRepository host: ...finding. - Otherwise run
git remote get-url origin(fall back togit remote -v) and check it matchesgithub.comor a GitHub Enterprise Server domain. - If the host is something else or there is no remote, say this skill only drafts GitHub issues and stop.
Step 2 — Explore the codebase
Run Skill({skill: "iru-explore"}) with no argument (general orientation, no ticket yet). Skip it when general
exploration already happened in this conversation and looks current. Use the findings to cite real files, modules
and conventions in the draft.
Step 3 — Decide the kind
Parse the arguments: an optional first word functional or documentation, the rest being a short description.
- Kind given: use it.
- Kind not given: infer only when unambiguous (writing pages, guides, diagrams or a bibliography means
documentation; changing behaviour meansfunctional) and otherwise ask viaAskUserQuestion: Functional (feature, enhancement or bug fix) / Documentation (pages, guides, diagrams).
A short description is a starting point: ask only for what it leaves unclear.
Step 4 — Interview
Open-ended questions (purpose, requirements, page contents) are asked as plain conversational text; fixed choices
(technical vs. non-technical, importance, label) use AskUserQuestion. Ask in small batches, wait for each answer,
and do not move on while a required item is unanswered.
Functional
- Context: what problem or capability, who is affected, why it matters now. Add what exploration shows exists today.
- Functional requirements: observable, testable behaviours. Challenge vague wording ("fast", "nice") and ask for a measurable form.
- Acceptance criteria: one or more verifiable criteria per requirement; propose candidates derived from the requirements and let the user accept or change them.
- Technical details: offer only when the task is highly technical (classes, files, lines to change); verify every
artifact exists with
Read/grep before writing it. - Out of scope, and dependencies or related issues (confirm each
#Nwithgh issue view <n> --json number,title,url,state).
Documentation
- Context and audience: why, who reads it, what they should be able to do afterwards.
- Type via
AskUserQuestion: Technical / Non-technical (learning guide). - Page structure. Technical: which of architecture, data model, use cases, configuration properties, metrics, algorithms apply, with each page's content. Non-technical: ordered pages from basics to advanced and the sections (one per concept) under each, with learning outcomes.
- Diagrams: for each flow, architecture, data model or state machine, the diagram kind (Mermaid, or SVG when Mermaid cannot express it) and what it shows.
- Bibliography and official documentation: books, specifications, library and class references for every documented
technology. Fetch each URL with
WebFetchto confirm it resolves and matches the subject. - Acceptance criteria (pages exist, build has no warnings, links resolve, diagrams render), out of scope.
If the user has no answer to a required point, record it as a question to resolve in Step 7, not as a placeholder.
Step 5 — Optional context, due date, importance, label
Ask (plain text, all optional): linked URLs, local files or documents to attach, related issues.
- URLs: fetch with
WebFetchand fold material points into the draft. - Related issues: confirm with
gh issue view <n> --json number,title,url,state. - Files:
Readeach for context, then attach it. GitHub's API has no direct issue-attachment endpoint, so: small text files (under about 200 lines) are embedded in References inside a<details><summary>name</summary>block with a fenced code block of the full content; images, PDFs, large or binary files are uploaded as assets of a release namedissue-attachments(gh release view issue-attachments --json tagNameto check; if missing, ask viaAskUserQuestionbefore creating it withgh release create issue-attachments --title "Issue attachments" --notes "Storage for files attached to issues."; upload withgh release upload issue-attachments <path>; link images asand others as[name](url)). If the user declines orghis unavailable (try GitHub MCP tools viaToolSearch"github release"), describe the file in the body and say it was not attached. This upload is the only GitHub write allowed before Step 9, and only after the explicit approval above. - Due date: plain-text question; normalize to an absolute date; omit if none.
- Importance:
AskUserQuestionwith trivial / minor / important / blocking; "not specified" if declined. - Estimated difficulty: your own judgement from the exploration (very easy, easy, medium, hard, very hard, extreme, impossible) with a one-line rationale.
- Label: run
gh label list --json name,description; choosebug,enhancementordocumentationonly if it exists in that list (documentation kind maps todocumentation; a defect tobug; otherwiseenhancement). If none fits or it is ambiguous, ask viaAskUserQuestionfrom the actual list. Never invent a label.
Step 6 — Write the draft file
Fill the matching template from reference/issue-templates.md. Write it to a temp file in the scratchpad directory
if the system prompt lists one, otherwise to a fresh mktemp -d directory, as issue-draft.md: first line # <title>
(concise, imperative), then the body. Keep the path; every later step uses it.
Step 7 — Review loop (maximum 5 rounds)
Repeat:
- Invoke
Skill({skill: "iru-review-github-issue", args: "draft:<path>"})(addkind: <kind>after the path on a new line only if the kind is known). Receive its block exactly as emitted:
Do not reformat, summarise or reorder it; read theVerdict: ready | needs-work Kind: functional | documentation Findings: - [gap|pending|inconsistency|doubt] <section> — <what is wrong> — Question: <exact question for the user> Suggestions: <optional improvements that are not blockers>Verdictand each finding from it as-is. Verdict: ready: leave the loop.- Otherwise resolve each finding in this order:
- first from the codebase and conversation (read the file, grep, re-read an earlier answer, fetch the URL); apply the fix to the draft only when the evidence is unambiguous;
- otherwise ask the user the finding's own
Question:(plain text for open answers,AskUserQuestionfor choices) and apply their answer verbatim. Group several questions into one message. Never fill a gap with an invented answer.
- Rewrite the draft file and go to 1.
After round 5 with needs-work still reported, stop looping and show the user the remaining findings; they decide
to fix, accept them as known gaps in the draft, or abort. Do not create the issue while findings the user has not
seen remain.
Keep the last block's Suggestions: for Step 8.
Step 8 — Size check and split offer
Judge whether the issue is large using the same signals as the review (more than about 7 requirements or criteria,
more than one independently deliverable capability, more than one module or area, estimated difficulty hard or
above), and use the review's Suggestions: hint. If any fires, ask via AskUserQuestion:
- Split it (recommended): run
Skill({skill: "iru-split-github-issue", args: "draft:<path>\nlabel: <label>"})(omit thelabel:line when Step 5 chose none), so the root and sub-issues carry the label chosen here. The split skill proposes the sub-issues, asks its own confirmation and then creates the root issue, sub-issues and milestone together from the draft. If it completes, skip Steps 9-10 (everything is created) and go to Step 11 with the root number it reports. If the user declines inside it, return here and offer Step 9 for the single issue. - Keep it as one issue: continue to Step 9.
If no signal fires, continue without asking.
Step 9 — Show the draft and confirm
Show the full title and body of the final draft, the label, and any remaining accepted findings. Filing an issue is
visible to everyone with repository access, so nothing is created before the user answers via AskUserQuestion:
- Create the issue now
- Edit the draft first: take their edits, update the file, and re-run the review loop (Step 7) before asking again
- Do not create it: stop; the draft file is the deliverable (give its path)
Step 10 — Create the issue
Only after "Create the issue now":
gh issue create --title "<title>" --body-file <path-to-body-without-the-title-line> --label "<label>"
--body-file takes the body only, so write the draft minus its first line to a second file. Omit --label when
Step 5 chose none. Add --milestone only if the user asked for one. If gh is missing or unauthenticated, search
for GitHub MCP tools (ToolSearch "github issue") and create the issue with the same title, body and label.
Capture the number and URL from the output (or gh issue view --json number,url).
Step 11 — Report
Give the issue number and URL (for a split, the root and the sub-issues with their dependency groups), note that the
issue is ready to be picked up with /iru-issue <number> (or /iru-plan <number> for a plan only), and mention any
issue-attachments release created in Step 5, since it is a repository-visible artifact.
Verification
gh label list --json name,description, gh issue view <n> --json number,title,url,state and the read-only
gh api calls were exercised against albertoirurueta/ai-catalog. gh issue create, gh release create/upload
and the create paths of the split skill are written from the GitHub CLI and REST documentation and are unverified (no
scratch repository was available).