Fusion Issue Authoring

Issue Authoring

Agent modes

This skill uses internal agent modes for type-specific drafting logic:

• agents/bug.agent.md: bug-focused issue drafting and triage structure
• agents/feature.agent.md: feature-focused scope and acceptance structure
• agents/user-story.agent.md: role/workflow/scenario-driven story structure
• agents/task.agent.md: checklist-first task decomposition and dependency planning
• agents/devils-advocate.agent.md: always-on quality collaborator that raises key concerns after classification (moderate mode) and runs a full structured interview when explicitly asked, when scope/criteria gaps are significant, or when invoked from fusion-issue-task-planning with two or more architecture-ambiguity signals present (interrogator mode)

Agent modes are activated internally based on issue type classification. Users never reference agent files directly. Shared gates (labels, assignee confirmation, draft review, publish confirmation, and mutation sequencing) remain in this skill.

When to use

Use when turning ideas, bugs, feature requests, or user needs into clear, actionable GitHub issues, and as top-level router for 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 / maintain / clean up this issue"
• "add this as a sub-issue / set parent issue / link as child"

When not to use

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

Required inputs

Collect before publishing:

• Target repository
• Issue intent/context and type (Bug, Feature, User Story, Task)
• Existing issue number/URL when updating
• Repository label set (or confirmation labels are intentionally skipped). Cache full label set per repo for session; filter locally. Prefer host session memory; otherwise .tmp/ cache file (never committed).
• Parent/related issue links and dependency direction (sub-issue vs blocking)
• Assignee preference (@me, specific person, or unassigned). Reuse cached assignee-candidate results; skip searches when user gave @me or exact login.

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 activate the matching agent mode:

• Bug -> agents/bug.agent.md
• Feature -> agents/feature.agent.md
• User Story -> agents/user-story.agent.md
• Task -> agents/task.agent.md

If ambiguous, ask only essential clarifying questions.

Devil's advocate pass: agents/devils-advocate.agent.md is always active in moderate mode — it surfaces the 2–3 most important concerns after classification without interrupting flow. When the user asks to be "grilled", says "stress-test this", when scope/criteria gaps are significant, or when invoked from fusion-issue-task-planning with two or more architecture-ambiguity signals present, escalate to interrogator mode for a full structured interview before the type-specific agent. The devil's advocate returns confirmed decisions and noted risks, then hands off to the type-specific drafting agent.

Step 2 — Resolve repository and template

• Resolve the destination repository before any mutation.
• When no explicit repository is given, check the active workspace for contributor guides (CONTRIBUTING.md, contribute/) that define default issue routing by type. Apply any routing rules found there before asking the user.
• If no routing guidance exists in the repo, ask explicitly where the issue should be created.
• 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

Before writing, check user preferences and session memory for a preferred draft location. If a stored preference exists, use it. If no preference is found and the intent is ambiguous, ask once and remember the answer for the session. Default to .tmp/{TYPE}-{CONTEXT}.md when no preference is found and there is nothing to ask about. Write the draft 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)

Shared gate cache policy:

• On the first label lookup for owner/repo, fetch the repository label set once and cache it for the active session. Prefer /memories/session/<owner>-<repo>-labels.json when the host exposes session memory; otherwise use .tmp/issue-authoring-labels-<owner>-<repo>.json.
• On cache hit, validate requested labels locally. Do not repeat point lookups for each requested label.
• If the host only exposes point label lookups and no cached label set exists yet, do not loop through labels one by one. Ask whether to skip optional labels or include only user-confirmed labels in the first mcp_github::issue_write call and handle a single rejection path.
• Skip mcp_github::search_users when the user already gave @me or an exact GitHub login.
• When assignee lookup is needed, cache candidate results for the active session keyed by owner/repo (or owner) and query. Prefer /memories/session/<owner>-<repo>-assignee-candidates.json or /memories/session/<owner>-assignee-candidates.json; otherwise use .tmp/issue-authoring-assignee-candidates-<owner>-<repo>.json.
• If rate limits block optional label or assignee enrichment, ask whether to continue without them instead of looping retries.

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-agent-mode workflow
• Draft-first workflow
• Clarifying questions for missing critical context
• Explicit confirmation before any GitHub mutation

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

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

Expected output

• Selected agent mode 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)

Author Bug Issue

When to use

Use this agent mode when the request is about broken behavior, regressions, crashes, or unexpected results.

When not to use

Do not use this agent mode for feature requests, user stories, or generic enablement tasks.

Required inputs

• Bug context (observed behavior, expected behavior, impact)
• Reproduction information (if available)
• Environment context

Instructions

1. Confirm routed type is Bug. 2. Draft locally in .tmp/BUG-<context>.md. 3. Structure draft with:

• Description
• Steps to reproduce
• Expected behavior
• Actual behavior
• Environment
• Impact

4. Validate the draft has enough reproduction detail for triage. 5. Return the draft summary for orchestrator review/publish flow.

Template fallback:

• assets/issue-templates/bug.md

Expected output

• Draft file path in .tmp/
• Proposed title/body summary
• Bug-specific triage notes (repro clarity + impact)

Safety & constraints

Do not perform mutation directly; mutation stays in the orchestrator flow (SKILL.md).

Devil's Advocate

When to use

Always-on quality collaborator for issue authoring. Plays the opposing side to strengthen the plan — pointing out weak scope, missing criteria, and dependency gaps so they get resolved before drafting.

Moderate mode (default): Active during normal authoring. Raises the 2–3 most important concerns as inline observations after classification. Does not interrupt flow or force a separate interview.

Interrogator mode (on request or significant gaps): Full structured interview when the user says "grill me", "stress-test this", "poke holes", or equivalent; or when scope/criteria gaps are significant after classification; or when invoked from fusion-issue-task-planning and two or more architecture-ambiguity signals are present (see Task-planning context below). Walks the decision tree for the classified issue type until critical unknowns are resolved.

When not to use

• The issue intent is already clear with well-defined scope, criteria, and dependencies
• Post-draft content review (that stays in the review gate of SKILL.md)
• The user has explicitly said they don't want pushback on this iteration

Required inputs

• Issue context: what the user wants to create or update
• Issue type (Bug, Feature, User Story, Task) — already classified by orchestrator
• Any partial draft or prior conversation context

Instructions

Moderate mode

Weave into the authoring flow without a separate interview:

1. Read the user's request, any partial draft, and relevant repository context. 2. Identify the top 2–3 concerns for the classified issue type:

• Bug: reproduction gaps, unclear severity, missing environment detail
• Feature: vague scope boundaries, untestable success criteria, hidden dependencies
• User Story: unclear role, incomplete scenarios, non-testable acceptance criteria
• Task: missing decomposition, circular blockers, no validation approach; in a task-planning context also probe for premature decomposition (splitting implementation before design is settled), implicit cross-task contracts (backend/frontend API shape not yet agreed), and tasks that look actionable but hide unresolved architecture assumptions

3. Resolve what you can from the codebase silently. 4. Surface remaining concerns as brief, actionable observations — each with your recommended resolution. 5. Let the user accept, adjust, or dismiss. Hand off to the type-specific agent.

Interrogator mode

Structured interview for thorough plan stress-testing:

Step 1: Triage what matters

1. Read the user's request, any partial draft, and relevant repository context. 2. Identify unresolved decision branches for the classified issue type. 3. Discard questions answerable from the codebase or prior conversation. 4. Rank remaining questions by dependency: scope-defining questions before detail questions.

Task-planning context (User Story decomposition)

When the classified type is derived from a User Story task-planning pass, prioritize these unresolved decision branches in the interview:

• Premature decomposition: Are we splitting implementation before critical design or architecture decisions are settled? Could the proposed split be invalidated by unresolved choices?
• Implicit contracts: Do tasks assume a backend/frontend API shape, data model, or ownership boundary that is not yet agreed? Surface the assumed contracts explicitly.
• Sequencing pressure: Should more tasks stay blocked behind a discovery, research, or contract-alignment task? Are implementation tasks safe to start in parallel, or do they share hidden dependencies?
• Hidden assumptions: Do tasks look concrete but depend on answers absent from the story, comments, or ancestor issues?

Auto-escalate to interrogator mode (without user trigger) if two or more of the following concrete signals are detected after reading the User Story and its context:

• Unresolved design or architecture decisions mentioned in the story, comments, or ancestor issues
• Backend and frontend tasks that share an implicit API, data model, or ownership contract not yet agreed
• A discovery, research, or alignment task alongside concrete implementation tasks with no explicit blocking relationship
• Dependency statements that are vague or circular ("after backend is done", "when design is ready")
• Component, API, or data-model ownership that is unclear or contested

Step 2: Interview — one question at a time

For each unresolved decision:

1. Ask one clear question. 2. Include your recommended answer and a short rationale. 3. Wait for the user's response before continuing.

Pacing rules:

• Stop after resolving critical unknowns. Do not keep going for completeness.
• If an answer implicitly resolves downstream questions, skip those — acknowledge what was settled.
• If the user signals "good enough" or wants to move on, wrap up immediately.
• Cap at ~6 questions. After that, summarize remaining gaps as noted risks.

Step 3: Decision summary

Return:

• Confirmed decisions: choices the user made or accepted
• Derived answers: things resolved from the codebase without asking
• Noted risks: unresolved items the user chose to defer
• Ready to draft: explicit signal that the type-specific agent can proceed

Keep the summary scannable — bullet lists, not paragraphs.

Expected output

• Observations (moderate) or decision summary (interrogator)
• Routing recommendation back to the type-specific agent (bug/feature/user-story/task)
• Draft file path is not produced here — drafting stays in the type-specific agent

Safety & constraints

• Do not perform mutation; mutation stays in the orchestrator flow (SKILL.md).
• Do not re-raise concerns the user already addressed.
• Respect the user's time: every observation or question must earn its place.
• Prefer codebase evidence over asking.
• Include a recommended answer or resolution for every concern raised.
• Keep tone direct and constructive — play the opposing side, not the adversary.
• In moderate mode, be brief. In interrogator mode, be thorough but never tedious.
• If the plan is already solid, say so and move on.

Author Feature Issue

When to use

Use this agent mode when the request is for a new capability or enhancement.

When not to use

Do not use this agent mode for bugs, user stories centered on role narratives, or generic technical tasks.

Required inputs

• Feature intent and value
• Scope and non-goals
• Success criteria

Instructions

1. Confirm routed type is Feature. 2. Draft locally in .tmp/FEATURE-<context>.md. 3. Structure draft with:

• Story/problem statement
• Scope (in/out)
• Functional requirements
• Acceptance criteria
• Dependencies/risks

4. Check that scope boundaries and non-goals are explicit. 5. Return draft summary for orchestrator review/publish flow.

Template fallback:

• assets/issue-templates/feature.md

Expected output

• Draft file path in .tmp/
• Proposed title/body summary
• Feature-specific scope and acceptance summary

Safety & constraints

Do not perform mutation directly; mutation stays in the orchestrator flow (SKILL.md).

Author Task Issue

When to use

Use this agent mode for planning, research, specification, migration, testing, documentation, or other enablement work.

When not to use

Do not use this agent mode when the request is clearly a bug, feature, or user-story issue.

Required inputs

• Task objective and scope
• Dependency and ordering constraints

Instructions

1. Confirm routed type is Task. 2. Start with a concise checklist of small tasks when request is broad. 3. For multi-issue requests, define logical order and blockers before drafting. 4. Draft locally in .tmp/TASK-<context>.md. 5. Use appropriate task template variant (planning/research/spec/testing/documentation/ux/generic). 6. Include dependency notes and blocker mapping in the draft. 7. Return draft summary for orchestrator review/publish flow.

Template fallback:

• assets/issue-templates/task.md
• assets/issue-templates/task.planning.md
• assets/issue-templates/task.research.md
• assets/issue-templates/task.spec.md
• assets/issue-templates/task.ux.md
• assets/issue-templates/task.testing.md
• assets/issue-templates/task.documentation.md

Expected output

• Checklist (for broad task requests)
• Draft file path in .tmp/
• Dependency plan (order + blockers)
• Task-specific decomposition summary

Safety & constraints

Never create contradictory dependency links. Always model sequencing before adding blockers. Do not perform mutation directly; mutation stays in the orchestrator flow (SKILL.md).

Author User Story Issue

When to use

Use this agent mode when the request is primarily about user workflow and behavior from a specific role perspective.

When not to use

Do not use this agent mode for pure bug reports, generic feature specs without user narrative, or technical enablement tasks.

Required inputs

• User role and workflow context
• Story goal (As a... I want... so that...)
• Key scenarios and success criteria

Instructions

1. Confirm routed type is User Story. 2. Draft locally in .tmp/USER-STORY-<context>.md. 3. Structure draft with:

• Story statement
• Context/pain points
• Functional requirements
• Scenarios (Given/When/Then)
• Validation approach

4. Ensure scenarios are testable and role-centered. 5. Return draft summary for orchestrator review/publish flow.

Template fallback:

• assets/issue-templates/user-story.md

Expected output

• Draft file path in .tmp/
• Proposed title/body summary
• Story-specific scenario and validation summary

Safety & constraints

Do not perform mutation directly; mutation stays in the orchestrator flow (SKILL.md).

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.

Description

Describe the bug from the user perspective.

Steps to reproduce

1. 2. 3.

Expected behavior

Describe what should happen.

Actual behavior

Describe what currently happens.

Environment

• App/service:
• Environment (dev/test/prod):
• Browser/runtime/version:

Impact

Who is affected and how severe is the impact?

Notes

Related issues:

Story

As a <role>, I want <capability>, so that <outcome>.

Problem / opportunity

What problem are we solving, or what opportunity are we addressing?

Scope

In scope

-

Out of scope

-

Functional requirements

-

Acceptance criteria

• [ ] Given ... When ... Then ...

Dependencies and risks

• Dependencies:
• Risks:

Notes

Related issues:

Objective

Describe what documentation needs to be created or updated.

Audience

Who is this documentation for?

Scope

• In scope:
• Out of scope:

Outline

-

Done when

• [ ] Documentation is published/updated
• [ ] Links and examples are verified

Notes

Related issues:

Objective

Describe the concrete work to be completed.

Scope

• In scope:
• Out of scope:

Deliverables

-

Done when

• [ ]

Notes

Dependencies/related issues:

Objective

Define the planning goal.

Scope

In scope

-

Out of scope

-

Planning output

• Work breakdown
• Estimates
• Milestones / rollout approach

Done when

• [ ] Plan is documented and reviewed
• [ ] Dependencies and risks are identified

Notes

Related issues:

Objective

State the question this research should answer.

Key questions

-

Approach

• Methods/sources:
• Timebox:

Deliverables

• Findings summary
• Recommendation(s)
• Open questions

Done when

• [ ] Findings are documented
• [ ] Decision support is shared

Notes

Related issues:

Objective

Define the specification outcome.

Background

Provide context and constraints.

Decisions needed

-

Proposed design

• Architecture/API/data model changes
• Alternatives considered

Scope

• In scope:
• Out of scope:

Done when

• [ ] Spec is documented
• [ ] Stakeholder review is completed

Notes

Related issues:

Objective

Describe what testing this task covers.

Scope

• Components/features under test:
• Environments:

Test cases

• [ ]

Verification criteria

• [ ] Expected behavior validated
• [ ] Regressions checked

Notes

Related issues:

Objective

Describe the UX problem to solve.

Context

What user workflow, screen, or interaction is affected?

Scope

• In scope:
• Out of scope:

UX deliverables

• User flow and interaction notes
• Wireframes/mockups/prototypes
• UX acceptance criteria

Validation

• [ ] User journey is validated against the target workflow
• [ ] Accessibility and usability considerations are documented

Notes

Related issues:

Story

As a <role>, I want <action>, so that <value>.

Context

Describe the user workflow and current pain points.

Functional requirements

-

Scenarios

• [ ] Given ... When ... Then ...

Non-goals

-

Validation

How do we verify this story is complete?

Notes

Related issues:

Issue authoring assets

fusion-issue-authoring contains all issue-type templates and GraphQL fallback queries.

Issue templates

Type-specific fallback templates are in issue-templates/:

• issue-templates/bug.md
• issue-templates/feature.md
• issue-templates/user-story.md
• issue-templates/task.md
• issue-templates/task.documentation.md
• issue-templates/task.planning.md
• issue-templates/task.research.md
• issue-templates/task.spec.md
• issue-templates/task.testing.md
• issue-templates/task.ux.md

GraphQL fallback queries

GraphQL fallback query assets for MCP gaps are available in:

• graphql/issue_lookup.github.graphql
• graphql/issue_types_list.github.graphql
• graphql/issue_type_update.github.graphql
• graphql/sub_issue_write.github.graphql
• graphql/sub_issue_remove.github.graphql
• graphql/sub_issue_reprioritize.github.graphql
• graphql/linkage_verify.github.graphql

Changelog

0.3.5 - 2026-05-07

patch

• #170 `5e43223` - Apply caveman-compress prose style to SKILL.md and references.

• Drop articles, filler, hedging from SKILL.md activation body
• Compress instructions, mcp-server, questions references

0.3.4 - 2026-05-04

patch

• #153 `3911da5` - Clarify sub_issue_id requires object ID, not issue number

• Promote the ID vs number distinction to a prominent warning block above the example
• Add a gh api command showing how to retrieve the object ID
• Add a troubleshooting table covering 404, invalid input, and silent-failure modes
• Clarify that after_id/before_id in reprioritize are also object IDs
• Add sub-issue linking activation cues to SKILL.md triggers

resolves equinor/fusion-skills#79

• #156 `3ed5296` - Strengthen devil's-advocate agent for task-planning context

Expands the devil's advocate with:

• Auto-escalation to interrogator mode when a task-planning pass surfaces two or more architecture-ambiguity signals (no user trigger required)
• Extended Task concerns in moderate mode: premature decomposition, implicit cross-task contracts, and tasks that hide unresolved architecture assumptions
• New "Task-planning context" section in interrogator mode with four targeted decision branches: premature decomposition, implicit contracts, sequencing pressure, and hidden assumptions

resolves equinor/fusion-skills#132

0.3.3 - 2026-04-06

patch

• #135 `5fa9384` - Make draft location flexible — check user preferences and session memory before defaulting to .tmp/

• Step 4 now checks user preferences and session memory for a preferred draft location
• Asks once when intent is ambiguous and remembers the answer for the session
• Falls back to .tmp/{TYPE}-{CONTEXT}.md only when no preference is found

0.3.2 - 2026-03-23

patch

• #121 `831f8ee` - Add devil's advocate agent for issue authoring

• Always-on moderate mode raises 2-3 key concerns after classification
• Interrogator mode runs full structured interview on explicit user request or when scope/criteria gaps are significant
• Wired into SKILL.md agent modes section

Refs: equinor/fusion-core-tasks#847

0.3.1 - 2026-03-21

patch

• #112 `e90fb97` - Add contributor-guide-aware repository routing to issue authoring

• SKILL.md Step 2: read active workspace CONTRIBUTING.md / contribute/ for routing rules before asking the user
• references/instructions.md: add Repository routing note pointing to SKILL.md Step 2 as authoritative flow

0.3.0 - 2026-03-18

minor

• #98 `6bb9cdc` - Consolidate issue-authoring capability into a single skill with agent modes

• Merge type-specific drafting logic from 4 subordinate skills into agent mode files (agents/*.agent.md)
• Move all 10 issue templates into assets/issue-templates/ within this skill
• Update orchestrator to route to internal agent modes instead of external subordinate skills
• Retain full 8-step workflow, shared gates, caching strategy, and MCP mutation sequencing

Resolves equinor/fusion-core-tasks#802

0.2.4 - 2026-03-17

patch

• #85 `c8ba3df` - Make all GitHub-API-consuming skills more conservative with token usage.

• fusion-issue-authoring: concrete session-cache flow for labels and assignee candidates; per-session budget table
• fusion-issue-solving: expanded low-token strategy with session-cache references and budget awareness
• fusion-github-review-resolution: token budget guidance for thread-heavy reviews; cache PR metadata once
• fusion-issue-task-planning: session-cache delegation rules and batch-size warning for large task plans
• fusion-dependency-review: explicit data-reuse rules across parallel advisor fan-out
• fusion-discover-skills: tighter GraphQL budget and call-count cap for discovery sessions

resolves equinor/fusion-core-tasks#797

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: fast, clear GitHub issues. Draft-first, safe mutation order.

Core rules

• Drafts concise, outcome-focused
• Full issue refs (owner/repo#123)
• Never mutate before explicit publish confirmation
• Ask only essential clarifying questions
• Resolve repo and labels before mutation
• MCP tools first; avoid ad hoc GitHub API/GraphQL retries when MCP equivalent exists

Low-token strategy

• Fetch context once, reuse
• One focused duplicate check; no repeated broad searches
• Labels: query only when needed; cache repo label set, filter locally
• Skip assignee-candidate lookups on @me or exact login; cache ambiguous results
• Cache issue types per org; skip repeated list_issue_types on cache hit
• Sub-issue mutations only for changed relationships
• Rate limits hit: stop optional lookups, return retry plan

Repository routing

Repo-specific. No explicit repo given: read workspace CONTRIBUTING.md and contribute/ docs, apply routing rules. See SKILL.md Step 2. Never hardcode destinations.

Workflow

1. Classify (Bug, Feature, User Story, Task) 2. Resolve destination repo (apply contributor guide routing) 3. Check template: repo first (.github/ISSUE_TEMPLATE/), then specialist fallback 4. Duplicate check via mcp_github::search_issues 5. Draft in .tmp/{TYPE}-{CONTEXT}.md 6. Review with user, apply edits 7. Explicit publish confirmation 8. Mutate via MCP in order:

• mcp_github::issue_write — full known payload (labels/assignees/type)
• single follow-up mcp_github::issue_write only for fields unavailable in first call
• mcp_github::sub_issue_write — only when ordering/links changed
• mcp_github::add_issue_comment — only when requested

MCP failure handling:

• Mutation fails (missing MCP server/auth/config): explain failure, point to references/mcp-server.md, retry after user confirms setup

Type param rule:

• Use cached issue types; call mcp_github::list_issue_types only on cache miss
• Send type only when repo supports issue types; omit otherwise, mark owner unsupported for session

Rate-limit fallback:

• Surface failures clearly; no tight retry loops
• Respect retry-after and x-ratelimit-reset headers
• GraphQL mutations: 5 secondary-limit points each; minimize calls
• Pause ≥1s between consecutive GraphQL mutations
• Preserve .tmp/ drafts and session cache; give user safe retry path

Task mode

• Small, single-purpose tasks preferred
• Broad requests: suggest checklist first
• Bulk creation: include dependency order and blockers
• Issue type Task for all task decomposition

Relationships

• Sub-issues for decomposition under parent objective
• Sub-issue ordering = prerequisites
• Stop and fix contradictory links before mutation

Quick check: 1. Start now? If no → later in sub-issue order, note blocker 2. Part of parent objective? If yes → add as sub-issue 3. Contradiction? If yes → correct before mutation

Labels and assignees

• First label lookup for owner/repo: fetch label set once, write session cache
• Prefer /memories/session/{owner}-{repo}-labels.json; fallback .tmp/issue-authoring-labels-{owner}-{repo}.json
• Later checks: filter from cache, no point lookups
• Only point lookups available + no cache: ask whether to skip optional labels or use user-confirmed labels only; no per-label loop
• Labels missing from cache: ask to proceed with available labels
• Ask assignee intent: @me, specific login, or unassigned
• @me or exact login → skip mcp_github::search_users
• Assignee search needed: cache by owner/repo+query
• Prefer /memories/session/{owner}-{repo}-assignee-candidates.json; fallback .tmp/issue-authoring-assignee-candidates-{owner}-{repo}.json
• Contributors/members available: hydrate cache once, reuse; otherwise reuse first search_users result

MCP reference

See references/mcp-server.md for server link, preferred tools, payload examples.

Template fallbacks

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

GitHub MCP server reference

GitHub MCP tools and payload examples. Server: https://github.com/github/github-mcp-server

Preferred tools

• mcp_github::issue_write — create/update issues
• mcp_github::search_issues — duplicates/context search
• mcp_github::sub_issue_write — add/remove/reprioritize sub-issues
• mcp_github::search_users — assignment candidates
• mcp_github::add_issue_comment — add comment
• mcp_github::list_issue_types — list issue types

High-cost paths and mitigation

Expensive: repeated label lookups, repeated assignee searches, repeated list_issue_types, broad duplicate searches, second-pass updates for labels/assignees, GraphQL retry loops.

Mitigation:

• cache labels per owner/repo for session
• cache assignee candidates per owner/repo+query for session
• cache issue types per owner for session
• one focused duplicate search
• full payload in first issue_write
• GraphQL fallback only when MCP missing, no retry loops

MCP readiness check

1. Try mcp_github::search_issues with lightweight query in target repo 2. Succeeds → MCP ready 3. Fails → run install-assist

Install assist (VS Code)

1. Ensure VS Code supports remote MCP 2. Add to MCP config:

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

3. Open Copilot Chat Agent mode, complete OAuth if prompted 4. Re-run readiness probe

No remote MCP available: use local server setup from GitHub MCP server README.

Blocking dependency note

No dedicated blocking/blocked links tool. Use mcp_github::sub_issue_write for execution order; mcp_github::add_issue_comment or body text for blocker context.

type parameter rule

Optional. Get valid values with mcp_github::list_issue_types. Send only when repo has issue types configured; omit otherwise.

Label caching

Never one point lookup per label.

1. First label request for owner/repo: bulk fetch, cache for session

• prefer /memories/session/<owner>-<repo>-labels.json
• fallback: .tmp/issue-authoring-labels-<owner>-<repo>.json (never committed)

2. Cache hit: filter locally, send surviving set in first issue_write 3. Only point lookups + no cache: ask to skip optional labels or use user-confirmed only; no per-label loop 4. Refresh cache only on repo change or explicit user request

Assignee caching

Never repeat same lookup per session.

1. @me or exact login → skip mcp_github::search_users 2. Lookup needed: cache by owner/repo+query

• prefer /memories/session/<owner>-<repo>-assignee-candidates.json or <owner>-assignee-candidates.json
• fallback: .tmp/issue-authoring-assignee-candidates-<owner>-<repo>.json (never committed)

3. Contributors/members available: hydrate cache once, reuse; otherwise reuse first search_users result 4. Rate limits block enrichment: ask to continue unassigned or with @me

Issue type caching

Never call mcp_github::list_issue_types every request.

1. In-session cache: owner → [types] 2. Cache hit: validate locally. Cache miss: call, then cache 3. issue_write fails on type → mark owner types_unsupported for session, omit type

Optional: .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

`sub_issue_id` is the GitHub object ID, NOT the issue number.

>

| Format | Example | Used in URLs / UI? |

|---|---|---|

| Issue number | #79, 79 | Yes |

| Object ID | 3969391411 | No — internal only |

>

Always retrieve the object ID before calling `sub_issue_write`.

>

```bash

# Get the object ID for a sub-issue by its number

gh api repos/OWNER/REPO/issues/NUMBER -q '.id'

# Example: gh api repos/equinor/fusion-skills/issues/79 -q '.id'

# Output: 3969391411

```

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

Troubleshooting sub-issue linking

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. Both sub_issue_id and after_id/before_id are object IDs, not issue numbers.

Minimal task-batch order

1. mcp_github::issue_write create/update with full known fields (title, body, labels, assignees, optional type) using cache-backed label/assignee data when available 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 label/assignee 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.

Per-session budget estimate

A typical multi-issue authoring session with cache-first behavior:

Stay under ~30 MCP calls per session for a typical 3-issue run. If the running total approaches this threshold, stop optional enrichment (extra label checks, assignee searches, duplicate re-scans) and proceed with the data already cached.

Clarifying questions

Use minimum 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?