issue-authoring

Issue Authoring

Purpose: Ensure consistent, high-quality issues with verified fields Adapter: See _adapters/ for platform-specific configuration

Wrong skill? Updating existing issues → issue-editing. Verifying issue identifiers → issue-verify. Adding comments → issue-comment-debunker.

---

When to Use

• Creating new tickets in your configured issue tracker (shipped adapters: GitHub Issues, Jira; custom adapters supported via skills/issue-tracking/_adapters/platform-template.md)
• When user requests a ticket for a bug, feature, or task
• Converting conversation discussion into a trackable ticket
• When acceptance criteria need to be formalized

Configuration

Before using this skill, configure your issue tracker:

1. Set ISSUE_TRACKER_TYPE to your configured issue-tracker adapter key
2. See skills/issue-tracking/_adapters/ for platform-specific setup
3. Ensure required MCP tools are available for your platform

---

Pre-Creation Checklist (MANDATORY)

Before calling your adapter's create_issue operation:

• Search for duplicates — Use adapter's search operation
• Validate labels exist — Query label IDs for your platform
• Validate assignee exists — Query user IDs for your platform
• Verify issue cross-references — For issue identifiers or issue URLs in the description (e.g., Related: [IDENTIFIER], Closes: [URL]), run issue-verify first:
  • entityType: "issue" + exists: true → proceed
  • entityType: "pull_request" or "other" → HARD BLOCK — do not create the issue with a broken cross-reference
  • entityType: "unknown" → WARN — stop and require explicit user confirmation (silence, unclear, off-topic, echo, and partial responses do not count as approval) before including the reference
  • exists: false → HARD BLOCK — do not reference a non-existent issue
  • PR links, wiki links, repo URLs, and external references do not go through this check — use issue-link-verification's type-specific policy for those.
• Title follows format — See Title Standards below
• Description has required sections — See Description Template

---

Title Standards

<EXTREMELY_IMPORTANT>

Pattern	Example	Status
[Type]: Brief description	Bug: Phone call drops after 30s on slow networks	✅ GOOD
Specific, actionable title	Add retry logic to webhook handler	✅ GOOD
Fix bug	—	❌ TOO VAGUE
Update thing	—	❌ TOO VAGUE
Issue with X	—	❌ TOO VAGUE

Title must be:

• Specific enough to understand without reading description
• Max 80 characters (Some trackers truncate longer titles in views)
• No tracker-managed identifier prefix (added automatically by the tracker)

</EXTREMELY_IMPORTANT>

---

Description Template

## Context
[What problem are we solving? Why does this matter?]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Technical Notes
[Optional: Implementation hints, constraints, related code]

## References
- PR: [link if exists]
- Wiki: [link if exists]
- Related: [IDENTIFIER]

---

Label Taxonomy

Query labels first using your adapter's API.

Category	Example Labels	When to Use
Type	bug, enhancement, feature	Every issue needs a type
Severity	critical, high, medium, low	For bugs affecting production
Source	support, internal, customer	Where request originated
Area	backend, frontend, infrastructure	Technical domain

---

Workflow States

Configure workflow states for your platform. Common patterns:

State	Use When
Triage / New	New issues needing review
Backlog	Prioritized but not scheduled
Ready / Todo	Ready for current sprint
In Progress	Actively being worked
Done / Closed	Completed
Canceled / Won't Fix	Will not be done

---

Duplicate Detection

<EXTREMELY_IMPORTANT>

Before creating ANY issue, search for duplicates using your adapter's search operation.

If potential duplicate found:

1. STOP — do not create new issue
2. Report to user: "Found existing issue [IDENTIFIER] with similar title"
3. Ask: "Should I add a comment to the existing issue instead?"

</EXTREMELY_IMPORTANT>

---

Pre-Flight Checklist

Before creating issue:
1. SEARCH — Check for duplicates
2. VALIDATE — Labels and assignee exist
3. VERIFY REFS — Run issue-verify for issue identifiers/URLs in description
4. FORMAT — Title follows standards
5. STRUCTURE — Description has required sections
6. CREATE — Only then call adapter's create operation

---

Companion Skills

• issue-editing: Fetch-before-edit workflow

• issue-link-verification: Verify URLs before posting

• issue-comment-debunker: Evidence-based comments only

• issue-verify: Post-creation verification

Related Tools

For formal acceptance criteria documents with adversarial review, use docforge-ai acceptance-criteria — Claude drafts, Gemini critiques, Claude synthesizes.

Example

# Create a well-structured issue in your configured tracker
# Required: title, description with acceptance criteria, team assignment
node ~/.codex/superpowers-augment/superpowers-augment.js use-skill issue-authoring

Failure Modes

• Vague titles: "Fix bug" or "Update thing" — titles must be specific and actionable (max 80 chars)
• Missing acceptance criteria: Issue created without clear definition of done
• Unverified links: Including URLs in description without checking they resolve (see link-verification skill)