thkt/issue

/issue - GitHub Issue Generator

Input

• Issue description: $ARGUMENTS
• If $ARGUMENTS is empty → prompt for description via AskUserQuestion
• Type is inferred from description (bug / feature / docs / chore)

Execution

| Step | Action | | ---- | --------------------------------------------------------------------------------- | | 0 | Read .claude/OUTCOME.md; if absent, stub generation (see rules/core/OUTCOME.md) | | 1 | Detect type from description (see Type Detection) | | 2 | Read template: ${CLAUDE_SKILL_DIR}/templates/<type>.md | | 3 | Generate title + body following template | | 4 | Filter drafted claims via premise check (see Premise Check) | | 5 | Refine body inline via prose review (see below) | | 6 | Challenge body via critic-design, feature/bug only (see Adversarial Challenge) | | 7 | Preview issue + unverified premises → AskUserQuestion: "Create this issue?" | | 8 | Execute via body-file (sandbox-compatible) | | 9 | Capture issue URL from command output |

A body supplied verbatim by the user skips steps 4-6 and posts unchanged.

Type Detection

| Type | Prefix | When to use | | ------- | --------- | ------------------------------------------------------- | | bug | [Bug] | Something existing is broken or not working as expected | | feature | [Feature] | New capability or enhancement request | | docs | [Docs] | Documentation additions or corrections | | chore | [Chore] | Maintenance, config, or dependency updates |

Default to feature if unclear.

Language

Read language from ${CLAUDE_SKILL_DIR}/../../settings.json and translate the issue body into that language. If unset, default to English. Keep technical terms, code, and identifiers untranslated.

Templates

| Type | Template | | ------- | ---------------------------------------- | | bug | ${CLAUDE_SKILL_DIR}/templates/bug.md | | feature | ${CLAUDE_SKILL_DIR}/templates/feature.md | | docs | ${CLAUDE_SKILL_DIR}/templates/docs.md | | chore | ${CLAUDE_SKILL_DIR}/templates/chore.md |

Labels

| Type | Labels | | ------- | -------------------- | | Bug | bug, priority:* | | Feature | enhancement, feature | | Task | task, chore |

Priority

| Label | Meaning | | ----------------- | ------------------ | | priority:critical | Production down | | priority:high | Significant impact | | priority:medium | Normal | | priority:low | Nice to have |

Premise Check

Filters claims already drafted into the body. Not a discovery phase: no agent spawns inside this check (the skill's only spawn is critic-design at the challenge step), no cross-codebase audit, no digging beyond the drafted claims themselves. A claim either resolves within 2-3 targeted probes or gets downgraded to provisional; never investigate to rescue it.

| Claim type | Action | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Current-code claim ("X currently does Y") | Verify with 2-3 targeted Read/ugrep probes; annotate in body ("grep-confirmed") | | Claim still ambiguous after the probes | Downgrade to provisional: state under Premises with a recheck marker, never as fact | | Claim contradicted by the source | Rewrite the body to match the source. If the mismatch matters (user report vs code), state it under Premises with the verification ask | | External design ref (Figma, design doc, spec) | Always unverified, since the skill cannot know the source is current. Link + "confirm latest before starting" | | Target file list | Annotate "candidates as of writing; recheck on pickup" | | Code example in body | Annotate as illustrative, not the implementation: "reference shape; final form decided at pickup" |

Prose Review

Write for a teammate who shares context and can open the linked docs, not a zero-context reader. The issue carries the delta; links carry the background.

Structure (Issue-specific)

| Check | Question | | ----------------- | ---------------------------------------------------------------------------------------- | | Problem stated | Is the problem or request in 1-3 lines at the top? | | Reproducible | Bug: are reproduction steps concrete? Feature: is the use case concrete? | | Expected outcome | Is the expected behavior explicit, not left for the reader to infer? | | Reader action | Is the ask specific ("review spec", "investigate cause", "decide by X")? | | Scope | Is the issue focused on one problem, not a dump of related concerns? | | Outcome alignment | Does this advance the outcome state? If it steps into Non-goals, flag explicitly in body |

Anti-AI-pattern

| Pattern | Signal | Fix | | ------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Boilerplate opener | This issue describes/reports/proposes... | Start with the problem, not self-description | | Empty intensifier | comprehensive, robust, seamless, thorough | Drop or replace with specifics (counts, names) | | Filler verb | leverage, utilize, facilitate | Use use, do, let | | Vague quantifier | various issues, multiple concerns, several bugs | Enumerate or count | | Hedge stacking | might potentially, could possibly, may perhaps | One hedge maximum, or commit | | Filler phrase | It should be noted that..., Looking forward to your thoughts, Any feedback welcome | Delete. State the fact or ask directly | | Doc transcription | Restating linked design-doc content in the issue | Link + one-line takeaway; write only the delta | | Repeated rationale | Same design reason explained twice in one issue | State once, where the decision lands | | Bold overuse | Bold scattered on every other line | Headings carry structure; bold only warnings | | Over-specified AC | AC spelling out authoring details (story names, addon config) | Keep the criterion, drop authoring details. UI component issues keep Storybook/a11y as DoD | | Compulsive section | Optional section filled with nothing to say | Omit empty optional sections |

Adversarial Challenge

feature/bug only; docs/chore skip it. Spawn one critic-design Task directly with the drafted body (not via /challenge). The critic argues against the issue (hidden premises, missed dependencies, scope contradictions); it does not gate it. Final judgment stays with the user at confirm time.

| Input field | Mapping | | ---------------- | ----------------------------------- | | source | /issue | | artifact_type | spec | | approach | What & Why section | | decisions | Scope (In/Out) + Constraints | | trade-offs | Stated trade-offs, if any | | referenced_files | Target files + external design refs |

| Verdict | Handling | | -------------- | --------------------------------------------------------------------------------------- | | confirmed | Proceed to preview | | weakened | Fold accepted findings into the body; present the rest at preview as ephemeral critique | | needs_revision | Revise the body once; do not re-spawn |

Critic findings never enter the issue body. They are confirm-time review material: fold or dismiss at preview. The body's Premises section stays reserved for genuinely unverifiable dependencies (design refs, provisional claims), matching how humans write it.

Sandbox-Compatible Create

cat > /tmp/claude/issue-body.md << 'EOF'
<body>
EOF
gh issue create --title "<title>" --body-file /tmp/claude/issue-body.md
mv /tmp/claude/issue-body.md ~/.Trash/ 2>/dev/null || true

Error Handling

| Error | Action | | ------------------ | ----------------------- | | No description | Prompt for description | | Template not found | Use default format | | No git repository | Report "Not a git repo" | | gh auth failure | Report auth error |

Display Format

Preview

## Issue Preview

> <title>

### Body

<body content>

### Unverified premises (N)

- <claim>: <what the reader must confirm>

### Critic findings (not posted)

- <finding>: fold into body or dismiss

The unverified block mirrors the body's Premises section (no new content at preview time): external design refs and provisional claims only. Verified claims keep their annotation in the body and do not repeat here. Zero unverified items: omit the block. Keep it short.

Critic block: omit when empty (docs/chore, or verdict confirmed).

Success

Created: #<number> <title> <issue URL>