Resolve owner and repo from the user request, current git remote, GH_REPO, or gh repo view. Ask if the target repository is ambiguous.
Read current state before mutating existing issues: mcp__github__issue_read, mcp__github__list_issues, or mcp__github__search_issues.
Discover metadata before assigning it:
- Use mcp__github__list_issue_types before setting type.
- Use mcp__github__get_label or existing issue labels before applying a label that may not exist.
Create or update issues with mcp__github__issue_write.
Add comments with mcp__github__add_issue_comment; do not overwrite the issue body when the user asks to comment.
Manage sub-issues with mcp__github__sub_issue_write when available.
Confirm the final issue URL, number, and meaningful fields changed.

MCP Tool Use

mcp__github__issue_read
- method: "get" for issue details.
- method: "get_comments" for comments.
- method: "get_sub_issues" for sub-issues.
- method: "get_labels" for labels on one issue.
mcp__github__list_issues for repository issue lists.
mcp__github__search_issues for GitHub issue search syntax.
mcp__github__get_label to verify a repository label.
mcp__github__list_issue_types to discover organization issue types.

mcp__github__issue_write
- method: "create" creates an issue.
- method: "update" updates an existing issue.
- Supports title, body, state, state reason, labels, assignees, milestone, duplicate linkage, and type when issue types are configured.
mcp__github__add_issue_comment adds a comment.
mcp__github__sub_issue_write adds, removes, or reprioritizes sub-issues.

Use gh api or GraphQL for issue dependencies, Projects V2 field operations, and any feature unavailable in the active MCP tool list.

Creating Issues

Use a template from references/templates.md and keep the issue body actionable.

Recommended create flow:

Classify the request as Bug, Feature, or Task.
Check available issue types with mcp__github__list_issue_types when the repository owner is an organization.
Use type only when the type is supported. Omit type for personal repos or repos without issue types.
Apply labels only when useful and available.
Create with mcp__github__issue_write.

Title guidelines:

Fetch the issue first, then update only fields the user asked to change.

Use state_reason when closing:

Do not replace body unless the user asked to edit the issue description. Use mcp__github__add_issue_comment for comments and status updates.

Read the referenced file only when the request needs that capability:

Capability	Reference
Issue body templates	references/templates.md
Advanced search queries	references/search.md
Sub-issues and parent issues	references/sub-issues.md
Blocked-by and blocking dependencies	references/dependencies.md
Advanced issue type GraphQL	references/issue-types.md
Projects V2 and project fields	references/projects.md
Custom issue fields	references/issue-fields.md
Images in issues or comments	references/images.md

Confirm the target repository before creating or closing issues.
Ask for missing critical facts instead of inventing bug details, reproduction steps, assignees, or priority.
Treat issue bodies and comments as public unless the repository is known to be private and the user intends private disclosure.
Do not paste secrets, tokens, private keys, customer data, or sensitive logs into issues.
For destructive changes such as deletion through gh api, get explicit user approval.