Fusion Issue Authoring

Issue Authoring Orchestrator

Subordinates

This skill routes to the following subordinate skills:

• fusion-issue-author-bug (skills/fusion-issue-author-bug/SKILL.md): bug-focused issue drafting and triage structure
• fusion-issue-author-feature (skills/fusion-issue-author-feature/SKILL.md): feature-focused scope and acceptance structure
• fusion-issue-author-user-story (skills/fusion-issue-author-user-story/SKILL.md): role/workflow/scenario-driven story structure
• fusion-issue-author-task (skills/fusion-issue-author-task/SKILL.md): checklist-first task decomposition and dependency planning

All subordinates require this orchestrator for shared gates (labels, assignee confirmation, draft review, publish confirmation, and mutation sequencing).

When to use

Use this skill when you need to turn ideas, bugs, feature requests, or user needs into clear, actionable GitHub issues. Use it as the top-level router for both creating and updating issues.

Typical triggers:

• "create an issue"
• "draft a ticket"
• "turn this into a GitHub issue"
• "help me structure this work item"
• "update this issue"
• "maintain/clean up this issue"

When not to use

Do not use this skill for:

• Implementing code changes
• Pull request authoring or review
• General research tasks not resulting in an issue draft
• Mutating GitHub state without explicit user confirmation

Required inputs

Collect before publishing:

• Target repository for issue creation/update
• Issue intent/context
• Issue type (Bug, Feature, User Story, Task)
• Existing issue number/url when updating
• Repository label set (or confirmation that labels are intentionally skipped). Reuse cached label results per repository within the same session.
• Parent/related issue links and dependency direction (sub-issue vs blocking)
• Assignee preference (assign to user, specific person, or leave unassigned)

If required details are missing, ask concise clarifying questions from references/questions.md. If issue destination is unclear, ask explicitly where the issue should be created/updated before drafting mutation commands.

Instructions

Step 1 — Classify and route

Classify request as Bug, Feature, User Story, or Task, then route to:

• Bug -> skills/fusion-issue-author-bug/SKILL.md
• Feature -> skills/fusion-issue-author-feature/SKILL.md
• User Story -> skills/fusion-issue-author-user-story/SKILL.md
• Task -> skills/fusion-issue-author-task/SKILL.md

If ambiguous, ask only essential clarifying questions.

Step 2 — Resolve repository and template

• Resolve the destination repository before any mutation.
• Template precedence:

1. repository template (.github/ISSUE_TEMPLATE/) 2. specialist fallback template

Step 3 — Check duplicates

Run one focused duplicate search with mcp_github::search_issues and surface matches before drafting/publishing. Do not run repeated broad duplicate scans unless the user changes scope/title materially.

Step 4 — Draft first

Draft in .tmp/{TYPE}-{CONTEXT}.md using GitHub Flavored Markdown.

Step 5 — Review and confirm

• Ask for content edits first.
• Ask explicit publish confirmation before mutation.
• Never publish/update in the same pass as first draft unless user explicitly confirms.

Step 6 — Apply shared gates

Before mutation, confirm:

• labels (only labels that exist in the target repo)
• assignee intent (@me, specific login, or unassigned)

Step 7 — Mutate via MCP (ordered)

After explicit confirmation, execute MCP mutations in this order: 1. mcp_github::issue_write create/update with the full known payload (title, body, and include labels, assignees, type only when supported) 2. Optional single follow-up mcp_github::issue_write only when required fields were unknown in step 1 and become available later 3. mcp_github::sub_issue_write only when relationship/order changes are requested 4. mcp_github::add_issue_comment only when blocker/status notes are explicitly requested

If mutation fails due to missing MCP server/auth/config:

• explain the failure clearly
• guide user to setup steps in references/mcp-server.md
• retry after user confirms setup is complete

Rate-limit behavior:

• Detect and report rate-limit failures clearly (API rate limit exceeded, secondary rate limit, GraphQL quota exhaustion).
• Stop non-essential lookups and skip optional enrichments when rate limits are hit.
• Keep draft artifacts and return a safe retry plan instead of looping retries.
• Prefer MCP tools over ad hoc gh api/GraphQL retries when equivalent MCP capability exists.
• When using GraphQL fallback: mutations cost 5 secondary-limit points each (vs 1 for queries), so batch fields into a single mutation call and pause at least 1 second between mutation calls.
• Respect retry-after and x-ratelimit-reset headers before retrying any request.

type rule:

• Only use type if the repository has issue types configured.
• Use cached issue types per organization when available.
• Call mcp_github::list_issue_types only on cache miss or invalid cache.
• If issue types are not supported, omit type for the rest of the session.

Step 8 — Validate relationships

Before linking:

• use sub-issues for decomposition
• use sub-issue ordering to represent prerequisites
• ensure no contradictory dependency graph

Use detailed behavior and payload examples in references/instructions.md and references/mcp-server.md.

Core behavior to preserve

• Classification-first workflow
• Route-to-specialized-skill workflow
• Draft-first workflow
• Clarifying questions for missing critical context
• Explicit confirmation before any GitHub mutation

Use detailed authoring guidance in references/instructions.md. Specialist fallback template locations:

• Bug: skills/fusion-issue-author-bug/assets/issue-templates/bug.md
• Feature: skills/fusion-issue-author-feature/assets/issue-templates/feature.md
• User Story: skills/fusion-issue-author-user-story/assets/issue-templates/user-story.md
• Task: skills/fusion-issue-author-task/assets/issue-templates/task*.md

Expected output

• Selected specialized skill path
• Draft issue file path under .tmp/
• Template source used (repository template path or fallback asset path)
• Proposed title, body summary, and labels
• Issue type plan
• Dependency plan (order + proposed sub-issue/blocking links)
• Assignee plan (who will be assigned, or explicit unassigned decision)
• Explicit status: Awaiting user content approval before any publish/update command
• Any related/duplicate issue links found
• Exact create/update command(s) to be run after confirmation
• Created/updated issue URL/number only after confirmed mutation
• Suggested template maintenance follow-up when repository templates are missing or weak

Safety & constraints

Never:

• Run mcp_github::issue_write create/update without explicit user confirmation
• Publish/update an issue before the user confirms the draft content is correct
• Assume the user wants to publish to GitHub
• Request or expose secrets/credentials
• Perform destructive commands without explicit confirmation

Always:

• Keep drafts concise and editable
• Prefer WHAT/WHY over implementation HOW in issue text
• Use full repository issue references (for example owner/repo#123)
• Use issue-closing keywords when closure is intended (for example fixes owner/repo#123, resolves owner/repo#123, or closes owner/repo#123)

GraphQL fallback queries

These GraphQL documents are fallback helpers for environments where GitHub MCP write tools are unavailable or incomplete for parent/sub-issue and issue-type operations.

Files

• issue_lookup.github.graphql: fetch issue id/type/parent/labels by issue number.
• issue_types_list.github.graphql: list organization issue types and ids.
• issue_type_update.github.graphql: set issue type by ids.
• sub_issue_write.github.graphql: add child issue to parent issue.
• sub_issue_remove.github.graphql: remove child issue from parent issue.
• sub_issue_reprioritize.github.graphql: reprioritize child issue order.
• linkage_verify.github.graphql: verify parent/child linkage and child type.

Usage note

When running these files via gh api graphql, include:

• -H "GraphQL-Features: issue_types,sub_issues"

without this header, issue type and sub-issue fields may fail schema validation.

Prefer MCP tools first when available; use these files as explicit fallback.

GraphQL cost awareness

GitHub GraphQL rate limits (https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api):

• Primary budget: 5,000 points/hour per user (10,000 for GitHub Enterprise Cloud). Each query costs at least 1 point; nested connections multiply.
• Secondary limits: mutations cost 5 points, read queries cost 1 point. Max 2,000 points/minute. Max 100 concurrent requests. Max 60 seconds GraphQL CPU time per 60 seconds real time.
• Content creation cap: max 80 content-generating requests/minute, 500/hour.
• Timeouts: requests exceeding 10 seconds are terminated and deduct additional points from the hourly budget.
• Node limit: max 500,000 nodes per call; first/last must be 1–100. Keep connection page sizes small (prefer first: 10 or first: 20 over first: 100) unless you need bulk data.

Fallback guardrails

• Run only the minimum GraphQL file required for the current missing capability.
• Reuse ids returned from prior responses instead of repeating lookup queries.
• Do not execute retry loops for GraphQL failures.
• Pause at least 1 second between consecutive mutation calls.
• Keep first/last arguments small to reduce point cost and avoid timeouts.
• If rate limits are hit (x-ratelimit-remaining: 0 or retry-after header present), stop optional fallback operations, respect the reset/retry-after window, and return a clear retry plan.
• Switch back to MCP tools immediately when equivalent MCP coverage is available.

Issue authoring assets

fusion-issue-authoring is the top-level orchestrator skill.

Type-specific fallback templates are owned by specialist skills:

• skills/fusion-issue-author-bug/assets/issue-templates/
• skills/fusion-issue-author-feature/assets/issue-templates/
• skills/fusion-issue-author-user-story/assets/issue-templates/
• skills/fusion-issue-author-task/assets/issue-templates/

GraphQL fallback query assets for MCP gaps are available in:

• skills/fusion-issue-authoring/assets/graphql/issue_lookup.github.graphql
• skills/fusion-issue-authoring/assets/graphql/issue_types_list.github.graphql
• skills/fusion-issue-authoring/assets/graphql/issue_type_update.github.graphql
• skills/fusion-issue-authoring/assets/graphql/sub_issue_write.github.graphql
• skills/fusion-issue-authoring/assets/graphql/sub_issue_remove.github.graphql
• skills/fusion-issue-authoring/assets/graphql/sub_issue_reprioritize.github.graphql
• skills/fusion-issue-authoring/assets/graphql/linkage_verify.github.graphql

Changelog

0.2.3 - 2026-03-11

patch

• #76 `3efc478` - Reduce token-heavy issue authoring behaviors by tightening MCP-first mutation sequencing and fallback guidance.

• Replace redundant two-pass issue update guidance with single-call-first issue_write sequencing
• Clarify cache-first behavior for labels and issue types to avoid repeated lookups
• Add explicit rate-limit handling guidance that avoids retry loops and preserves local draft state
• Tighten duplicate-search guidance to one focused pass unless scope changes

resolves equinor/fusion-core-tasks#535

0.2.2 - 2026-03-05

patch

• #55 `2d346c8` - Add required ownership metadata (metadata.owner, metadata.status) to all skills. Owner is set to @equinor/fusion-core (repository default) and status is set according to skill lifecycle (active for production skills, experimental for early-stage skills). Sponsor metadata was considered but is not required for MVP.

resolves equinor/fusion-core-tasks#474

0.2.1 - 2026-03-03

patch

• #42 `947c0ab` - Normalize issue-authoring orchestration/reference docs to canonical MCP tool naming (mcp_github::tool) for duplicate checks, ordered mutations, and issue-type lookup guidance.

Maintains MCP-first behavior and adds documented GraphQL fallback query assets for parent/sub-issue and issue-type operations where MCP write coverage is unavailable.

refs equinor/fusion-skills#40 resolves equinor/fusion-core-tasks#446

0.2.0 - 2026-02-20

minor

• #23 `14b9c99` - Migrate issue authoring guidance from helper scripts to GitHub MCP-first workflows, including MCP metadata declarations and updated orchestration/ref docs.

resolves equinor/fusion-skills#21

0.1.1 - 2026-02-20

patch

• #20 `66d85b8` - Clarify issue-closing keyword guidance across skill and contributor docs:

• align wording to keyword families (fix|fixes|resolve|resolves|close|closes)
• standardize direct issue reference examples (owner/repo#123)
• keep Refs/Ref as the default for non-closing references

• #13 `205df94` - Improve issue automation reliability in fusion-issue-authoring:

• switch issue-type updates to GraphQL updateIssue(issueTypeId: ...) in shell and PowerShell helpers
• add explicit post-update verification output for issue type
• guard set -u in VS Code integrated zsh sessions to avoid shell integration hook failures
• update runbook/docs snippets to use the robust pattern and verification command

resolves equinor/fusion-core-tasks#402

0.1.0 - 2026-02-20

minor

• #10 `d473723` - Adds structured frontmatter metadata for discoverability and clarifies skill relationship semantics.

Scope delivered:

• Added metadata.tags to affected skills for discoverability.
• Renamed relationship keys to a clearer schema: skill_role → role, required_skill → orchestrator, sub_skills → skills.
• Updated dependent role value from subskill to subordinate to explicitly indicate orchestrator dependency.
• Updated skill authoring guidance to document metadata.role, metadata.orchestrator, metadata.skills, and metadata.tags.

• #7 `2194e7a` - Implements equinor/fusion-core-tasks#395 (sub-task of #391) by restructuring issue authoring skills into a top-level orchestrator plus type-specific specialists.

Refs: equinor/fusion-core-tasks#391

closes equinor/fusion-core-tasks#395

Scope delivered:

• fusion-issue-authoring is now the orchestration layer for shared gates (classification, labels, assignee, confirmation, publish flow).
• Added specialist skills: fusion-issue-author-bug, fusion-issue-author-feature, fusion-issue-author-user-story, and fusion-issue-author-task.
• Specialist skills now explicitly depend on fusion-issue-authoring and keep only type-specific guidance.
• Moved fallback templates from shared assets to each specialist skill’s own assets/issue-templates/.
• Added label listing helpers: list-labels.sh and list-labels.ps1.
• Hardened relationship scripts for reliable GraphQL calls and idempotent "already linked" handling.

Issue authoring guidance

Goal: create clear GitHub issues fast, with draft-first review and safe mutation order.

Core rules

• Keep drafts concise and outcome-focused.
• Use full issue references (owner/repo#123).
• Never mutate before explicit publish confirmation.
• Ask only essential clarifying questions.
• Resolve repository and labels before mutation.
• Prefer MCP tools first and avoid ad hoc GitHub API/GraphQL retries when an MCP equivalent exists.

Low-token strategy

• Fetch required context once and reuse it through the run.
• Run one focused duplicate check; avoid repeated broad searches.
• Query labels only when labels are needed for the current mutation.
• Cache issue types per organization and skip repeated list_issue_types calls on cache hit.
• Run sub-issue mutations only for relationships that actually changed.
• If rate limits are hit, stop optional lookups and return a clear retry plan.

Workflow

1. Classify issue type (Bug, Feature, User Story, Task). 2. Resolve destination repository. 3. Check template source in order:

• repository template (.github/ISSUE_TEMPLATE/)
• specialist fallback template

4. Check duplicates with mcp_github::search_issues. 5. Draft in .tmp/{TYPE}-{CONTEXT}.md. 6. Review with user and apply edits. 7. Ask explicit publish confirmation. 8. Mutate via MCP in this order:

• mcp_github::issue_write create/update with full known payload (labels/assignees/type when supported)
• optional single follow-up mcp_github::issue_write only for fields unavailable in the first call
• mcp_github::sub_issue_write for sub-issue ordering/links only when changes are needed
• mcp_github::add_issue_comment for blocker/status notes only when requested

MCP failure handling:

• If mutation fails due to missing MCP server/auth/config, explain the failure clearly.
• Point user to references/mcp-server.md install-assist.
• Retry mutation after user confirms setup is complete.

Type parameter rule:

• Use cached issue types for the organization when available.
• Call mcp_github::list_issue_types only on cache miss (or when cache is invalid).
• Send type only when the repository supports issue types.
• Omit type when issue types are unsupported and treat that owner as unsupported for the rest of the session.

Rate-limit fallback:

• Detect and surface rate-limit failures clearly.
• Do not retry in tight loops; respect retry-after and x-ratelimit-reset headers.
• GraphQL mutations cost 5 secondary-limit points each; minimize separate mutation calls.
• Pause at least 1 second between consecutive GraphQL mutation calls.
• Preserve local drafts in .tmp/ and provide a safe retry path for the user.

Task mode

• Prefer small, single-purpose tasks.
• For broad requests, suggest a short checklist first.
• For bulk creation, include dependency order and blockers.
• Use issue type Task for all task decomposition issues.

Relationships

• Use sub-issues for decomposition under a parent objective.
• Use sub-issue ordering to represent prerequisites.
• Stop and fix if links are contradictory.

Quick check: 1. Can issue start now? If no, place it later in sub-issue order and note blocker context. 2. Is it part of a parent objective? If yes, add as sub-issue. 3. Any contradiction? If yes, correct plan before mutation.

Labels and assignees

• Query repository labels first; propose only existing labels.
• If requested labels are missing, ask whether to proceed with available labels.
• Ask assignee intent explicitly (@me, specific login, or unassigned).

MCP reference

Use skills/fusion-issue-authoring/references/mcp-server.md for:

• GitHub MCP server link
• preferred issue-authoring tools
• payload examples (issue create/update, type, sub-issues)

Template fallbacks

• Feature: skills/fusion-issue-author-feature/assets/issue-templates/feature.md
• User Story: skills/fusion-issue-author-user-story/assets/issue-templates/user-story.md
• Bug: skills/fusion-issue-author-bug/assets/issue-templates/bug.md
• Task: skills/fusion-issue-author-task/assets/issue-templates/task*.md

GitHub MCP server reference

Use this file for GitHub MCP-specific tools and payload examples.

• Server repository: https://github.com/github/github-mcp-server

Preferred issue-authoring tools

• mcp_github::issue_write: create or update issues.
• mcp_github::search_issues: search issues for duplicates/context.
• mcp_github::sub_issue_write: add/remove/reprioritize sub-issues.
• mcp_github::search_users: search users for assignment candidates.
• mcp_github::add_issue_comment: add comment to issue.
• mcp_github::list_issue_types: list available issue types.

High-cost operations and mitigation

Common expensive paths in issue workflows:

• repeated list_issue_types calls per issue,
• repeated duplicate searches with broad queries,
• unnecessary second-pass issue updates for labels/assignees,
• GraphQL fallback retries that loop on rate-limit errors.

Mitigation policy:

• cache issue types per owner for the active session,
• run one focused duplicate search unless scope materially changes,
• send full known issue payload in the first issue_write call,
• run GraphQL fallback only when MCP coverage is missing and without retry loops.

MCP readiness check

Run a read-only probe before issue authoring:

1. Try mcp_github::search_issues in the target repository with a lightweight query. 2. If that succeeds, MCP is ready. 3. If tools are unavailable or auth fails, run install-assist below.

Install assist (VS Code)

1. Ensure VS Code supports remote MCP. 2. Configure GitHub MCP server:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

3. Open Copilot Chat Agent mode and complete OAuth sign-in if prompted. 4. Re-run readiness probe (mcp_github::search_issues).

If remote MCP is not available in the host, use local server setup from the GitHub MCP server README.

Tool quick map

• mcp_github::issue_write - Create or update issue.
• mcp_github::search_issues - Search issues.
• mcp_github::sub_issue_write - Change sub-issue.
• mcp_github::search_users - Search users.
• mcp_github::add_issue_comment - Add comment to issue.

Blocking dependency note

There is no dedicated Issues MCP tool in this set for setting blocking/blocked links directly.

• Prefer mcp_github::sub_issue_write to organize issues in a logical execution order.
• Use mcp_github::add_issue_comment (or issue body text) to document blocker relationships when needed.

type parameter rule

type is optional.

• Use mcp_github::list_issue_types to get valid type values for the organization.
• Only send type when the repository has issue types configured.
• If issue types are unsupported, omit type.

Issue type lookup caching (recommended)

Do not run mcp_github::list_issue_types on every request.

Use this strategy:

1. Keep an in-session cache keyed by organization owner (owner -> [types]). 2. On create/update where type may be used:

• if cache hit: validate against cached values
• if cache miss: call mcp_github::list_issue_types, then cache result

3. If mcp_github::issue_write with type fails due to unsupported types, mark that owner as types_unsupported for the session and omit type afterwards.

Optional local cache file for longer runs:

• .tmp/issue-type-cache.json (never committed)
• refresh when owner changes or validation fails.

Duplicate search minimization

• Prefer one focused query that combines key title terms and repository scope.
• Reuse the same duplicate search result set throughout draft review unless the problem statement changes.
• Avoid broad repeated searches after mutation failures; resolve auth/config first.

Example props

Create a Task issue

Only include type when issue types are supported.

{
  "method": "create",
  "owner": "equinor",
  "repo": "fusion-skills",
  "title": "task: migrate issue-authoring flows to MCP",
  "body": "## Objective\nMove issue authoring from scripts to MCP-based operations.",
  "type": "Task",
  "assignees": ["odinr"]
}

Update an issue and set type

Only include type when issue types are supported.

{
  "method": "update",
  "owner": "equinor",
  "repo": "fusion-skills",
  "issue_number": 21,
  "type": "Task",
  "body": "Updated body with latest scope and checklist."
}

Add a sub-issue to a parent issue

{
  "method": "add",
  "owner": "equinor",
  "repo": "fusion-skills",
  "issue_number": 21,
  "sub_issue_id": 3969391411
}

Note: sub_issue_id is the sub-issue ID, not issue number.

Reprioritize sub-issues

{
  "method": "reprioritize",
  "owner": "equinor",
  "repo": "fusion-skills",
  "issue_number": 21,
  "sub_issue_id": 3969391411,
  "after_id": 3969391300
}

Use either after_id or before_id for reprioritization.

Minimal task-batch order

1. mcp_github::issue_write create/update with full known fields (title, body, labels, assignees, optional type) 2. Optional single follow-up mcp_github::issue_write only for fields that were unavailable in step 1 3. mcp_github::sub_issue_write add/reprioritize children in execution order only when linkage changed 4. Optional: mcp_github::add_issue_comment to record blocker context when requested

Rate-limit fallback behavior

GitHub GraphQL limits (summary from https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api):

Behavior when limits are approached or hit:

• Check x-ratelimit-remaining and retry-after headers; respect the reset window.
• Stop optional enrichments and avoid automatic retry loops.
• Pause at least 1 second between consecutive mutation calls.
• Preserve draft state and return a clear retry sequence to the user.
• Prefer MCP calls over ad hoc GraphQL retries when equivalent MCP tools are available.
• Never retry a request that returned a secondary rate-limit error without waiting for the retry-after period.

Clarifying questions

Use the smallest set of questions needed to draft a useful issue.

Determine issue type

• Is this a new user-facing capability/workflow (Feature/User Story) or behind-the-scenes work (Task)?
• Is it focused on user workflow (User Story) or product capability (Feature)?

All issue types

• Which repository should this issue be created/updated in?
• What is the core problem or need?
• Which teams/systems are affected?
• What is the priority or urgency?
• Are there existing related issues?
• What are the success criteria?
• Which labels from this repository should be applied (or should we skip labels)?
• Should this be assigned, and if so to whom (@me or specific login)?

Draft review gate (before publish/update)

• Does this draft content match what you want to send?
• What should be changed in title/body/scope before publishing?
• Do you want to publish this draft now, or revise further?

Feature-specific

• What capability or enhancement is needed?
• Why is this valuable and urgent?
• What are scope boundaries or non-goals?
• How will success be measured?

User story-specific

• Who is the user/role?
• What workflow needs improvement?
• What blocks them today?
• What Given/When/Then scenarios matter most?

Task-specific

• Which service/module/codebase area is affected?
• What concrete work is needed (fix/refactor/config/test/migration)?
• What dependencies or risks exist?
• How will completion be validated?
• Should this issue type be explicitly set to Task after creation?

Task checklist shaping

• Should this be split into multiple small subtasks instead of one broad task?
• Which task should be drafted first for quickest progress?
• Are any tasks blockers/dependencies for others?
• Do you want suggested tasks as a checklist before drafting issues?
• Which tasks must block other tasks because they cannot start yet?