GitHub Issues

Issue Description Format

Keep issues concise. The default structure has two sections:

### Description

[Context, problem statement, relevant code links, clarifications in flowing prose]

### Acceptance Criteria

[Clear definition of done]

Issue Dependencies

Use GitHub's Issue Dependencies API to track blocking relationships between issues. This enables proper dependency visualization and tracking in GitHub's UI.

Do NOT use text-based dependencies like Depends on #123 in issue bodies. While this convention was common historically, it's not machine-readable and doesn't integrate with GitHub's dependency features.

Adding Dependencies

After creating an issue that depends on another:

# Get the blocking issue's ID (not number)
BLOCKING_ID=$(gh api repos/OWNER/REPO/issues/BLOCKING_NUM --jq '.id')

# Add the dependency
gh api repos/OWNER/REPO/issues/ISSUE_NUM/dependencies/blocked_by \
  -X POST \
  -F issue_id=$BLOCKING_ID

Workflow for Issues with Dependencies

1. •Create the issue (without dependency text in body)
2. •Add dependencies via the API
3. •Dependencies appear in GitHub's UI automatically

See references/api-reference.md for more dependency API operations.

Writing Style

Write in prose paragraphs, not bullet lists. Embed references as inline links within the text rather than listing them in a separate section. See the evidence-based-responses skill for guidance on linking to evidence.

Avoid repetition. Say things once. If context is provided in the description, don't repeat it elsewhere.

Implementation details, when included, are suggestions rather than requirements. The developer who picks up the issue may implement it differently. Frame suggestions with language like "One approach would be..." or "Consider..."

Use proper GitHub markdown formatting. See the markdown-output skill for collapsible sections, code blocks, and alerts.

Additional Sections

Add these only when genuinely needed:

• •Out of Scope: When there's likely confusion about issue boundaries
• •Background: Only if context is complex enough to warrant separation from description

Omit sections that would be empty. Never include "N/A" or "None" placeholders.

Bad Patterns

• •Repeating information across multiple sections
• •Empty sections or "N/A" placeholders
• •Prefixes like WI-# in issue titles
• •Implementation details presented as hard requirements
• •References listed separately instead of linked inline

Issue Types

GitHub supports issue types to categorize work. Common types:

Issue type IDs are repository-specific. Query the repository's available types before creating issues. See references/api-reference.md for the GraphQL query.

The gh issue create CLI does not support setting issue types directly. Use the GraphQL API to create issues with a type, or create via CLI then update the type via GraphQL.

Sub-Issues

Prefer sub-issues over listing tasks in the issue description body. Sub-issues provide:

• •Progress tracking (completed count)
• •Individual assignment and status
• •Proper linking in GitHub's UI

Workflow:

1. •Create the parent issue (Epic or Batch) first
2. •Create child issues
3. •Link children as sub-issues via the API

See references/api-reference.md for REST and GraphQL examples.

Before Creating Issues

Clarify with the user:

• •Desired granularity (how big should each task be?)
• •Whether to include implementation suggestions or keep issues high-level
• •Which issue types are available in the target repository