Prompt file imported from asolisgi/copilot-agents-issue-37-smoke-test-20260521 (.github/prompts/issue.prompt.md). Copyright stays with the author.

Issue Authoring

Draft a GitHub issue that is ready to paste into the repository. Match the repository's planning style, but choose the smallest section set that fully captures the work. Prefer concise, shape-specific issue bodies over one shared, oversized template.

Use /issue as the general entrypoint when the issue shape is not yet clear. For reduced-scope mode, prefer /issue-epic, /issue-spec, or /issue-slice when the target shape is already known, and use /spec-taskstoissues only when you are converting an approved tasks.md into tracked GitHub issues.

If the repository exposes GitHub-native report and bounded change-request forms, preserve that split. Use those manual forms for lean direct GitHub intake, and use this prompt family for broader planning, design, decomposition, or issue-conversion work that should not start from the manual forms.

User Input

The user's message may include:

• A rough feature or problem statement that should become an issue
• A report or bounded change request that should stay aligned with the repository's GitHub-native issue forms
• A parent epic or design document to decompose
• Notes, requirements, or acceptance criteria
• Links or file paths to related issues, specs, RFCs, or product docs
• A discussion, comment, code reference, or task item that should become a tracked issue
• A request to produce one issue or a set of follow-up issues

Process

1. Gather Context

Before drafting the issue:

1. Read the directly relevant sources named by the user.
2. Check for repository issue template conventions if they exist, preserve any report-versus-change-request split, and route broader planning back to the prompt-driven issue flows instead of inventing a parallel oversized format.
3. Identify the role of the issue:
   • Epic
   • Spec / design issue
   • Implementation slice / follow-up issue
   • Migration / operational issue
4. Extract the controlling constraints:
   • Source of truth and ownership boundaries
   • In-scope and out-of-scope decisions
   • Actors, scopes, permissions, and policy constraints
   • Audit, approval, retention, deletion, or compliance requirements
   • Connector, integration, or migration constraints
   • GitHub tracking metadata that is clearly implied: issue type, labels, milestone, project, assignee, dependency, or sub-issue relationships
5. Find the relationship to existing work:
   • Parent / consumer issue
   • Related issues
   • Blocking or blocked-by issues
   • Candidate sub-issues for deeper decomposition
   • Follow-up implementation work that should be created later

If the request is still open-ended discussion rather than actionable tracked work, say so plainly and recommend a discussion instead of forcing an issue.

If the user supplied example issues, mirror their level of specificity and sectioning. Do not copy irrelevant headings from an example that does not fit the new issue.

2. Choose The Right Shape

Choose the closest issue shape and adapt it to the request.

If the request clearly fits a repository-owned GitHub report form or bounded change-request form, keep the output lean enough to match that manual intake path or recommend using the manual GitHub form instead of inflating it into an epic, spec, or implementation-slice issue.

Every issue should include this lean core unless a repository issue template requires more:

• Summary
• Acceptance Criteria
• Related Work

Add scope boundaries whenever they are not obvious from the title and summary. Add product model, lifecycle, identity/authorization, retention/audit, connector, or architecture sections only when the source material makes them material to review, implementation, or long-term maintenance.

Epic

Use for broad cross-cutting initiatives that will decompose into multiple design and implementation issues.

Default sections:

• Scope Decisions
• Decomposition Plan
• Out Of Scope For First Implementation

Optional when material:

• Product Model
• Operating Rules
• Identity And Authorization
• Retention, Deletion, And Auditability
• External Connector Compatibility
• Architecture Notes
• Technical Notes

Spec / Design Issue

Use for shared abstractions, platform models, or designs that define how multiple subsystems should behave.

Default sections:

• Problem
• Recommendation
• Core Concepts
• Rules or Principles
• How Subsystems Should Use The Model

Optional when material:

• Scope Decisions
• Product Model
• Ownership And Links
• Data Model Direction
• Authorization Principle
• Audit Principle
• Architecture Notes
• Out Of Scope For First Implementation

Implementation Slice / Follow-Up Issue

Use for a bounded implementation step beneath an epic or spec.

Default sections:

• Problem
• Proposed Change

Optional when material:

• Scope Decisions
• Affected Surfaces
• Dependencies
• Risks
• Rollout / Validation Notes
• Out Of Scope For First Implementation

Do not emit empty headings. If a section would only restate the summary, omit it.

3. GitHub-Native Metadata

In addition to the issue body, suggest metadata only when the source material supports it:

• Issue type when the repository or organization uses standardized issue types
• Labels that are justified by the content and likely to exist in the repository
• Milestone only when there is a real release, phase, or date boundary
• Project only when the issue should be tracked in a specific GitHub Project
• Assignee only when ownership is explicit rather than guessed
• Dependencies when one issue is blocked by or blocks another
• Sub-issues when the work should decompose into independently tracked child issues

If a metadata value is unknown, omit it instead of inventing placeholder values.

4. Write The Issue

Apply these rules while drafting:

1. Write a decisive title with the issue type in front when useful:
   • Epic: <outcome>
   • Spec: <shared abstraction or design>
   • Feature: <implementation outcome>
   • Follow-up: <bounded implementation step>
   • Keep the title concise, searchable, and specific enough to stand on its own in an issue list
2. Lead with the user or platform outcome, not the implementation mechanism.
3. Separate problem from recommendation when design work is still being defined.
4. Name important concepts explicitly and define them before relying on them.
5. Record invariants and governing rules as bullets or numbered rules.
6. Prefer one owning authority boundary plus explicit links over vague multi-home ownership when the domain has scopes, contexts, or lifecycle boundaries.
7. Call out what should not be overloaded when terminology could drift.
8. Make relationships explicit using Parent/consumer, Related, dependency notes, sub-issue notes, or discussion/PR references.
9. Cross-reference GitHub-native context with issue numbers like #123 and discussion or PR URLs when those references help the reader navigate the work.
10. State out-of-scope items when they help prevent scope creep.
11. Use task lists only for bounded checklists inside one issue; when an item needs separate ownership, discussion, or lifecycle tracking, promote it to a sub-issue instead.
12. Keep the body proportionate to the work. Narrow implementation or maintenance issues should usually fit in 5-7 headings, not a full planning artifact.

5. Acceptance Criteria

Acceptance criteria must be concrete and reviewable.

Good acceptance criteria:

• Define a model, rule, interface, or decision clearly enough that follow-up work can implement against it
• Explain how edge cases or multi-dimensional contexts are represented
• Identify required follow-up issue areas when implementation is intentionally deferred
• Use one checkbox per independently verifiable expectation

Avoid:

• "Support X" without explaining the behavior or boundary
• Mixing multiple requirements into one checkbox
• Vague statements like "be scalable" or "be flexible"

6. Labels And Follow-Ups

Suggest labels that fit the issue type and domain. Use only labels that are justified by the content, such as:

• epic
• enhancement
• architecture
• backend
• frontend
• planning
• compliance
• copilot

When the issue is planning-level, end by listing the follow-up implementation areas that should become separate issues, for example:

• persistence / migrations
• resolver or service layer
• policy enforcement
• API surface
• UI components
• connector adapters
• tests and audit coverage

When the issue is decomposition-heavy, prefer explicit Suggested sub-issues and Suggested dependencies sections so the draft maps cleanly onto GitHub's issue hierarchies and dependency tracking.

7. Quality Bar

• No filler, hype, or generic project-management language
• No hidden assumptions; state assumptions explicitly
• No code unless a tiny schema or formula is necessary to remove ambiguity
• Keep the body dense, specific, and issue-ready
• Match the repo's tone: architecture-first, constraint-aware, and implementation-oriented
• Prefer metadata and references that GitHub can actually track over prose-only relationship descriptions
• Prefer concise issues over exhaustive issue bodies; remove low-signal headings that add no decision, risk, or boundary information

Output Format

Title: <issue title>

Suggested issue type: <issue type, if applicable>

Suggested labels:
- <label>
- <label>

Suggested assignees:
- <user or team>

Suggested milestone: <milestone, if applicable>

Suggested project:
- <project, if applicable>

Suggested dependencies:
- blocked by #<issue>
- blocks #<issue>

Suggested sub-issues:
- <child issue title>
- <child issue title>

Body:
# <Issue title>

<Use the smallest correct section set for the chosen shape. Prefer one of these
defaults and add optional sections only when they carry real information.>

Epic default:
## Summary
## Scope Decisions
## Decomposition Plan
## Acceptance Criteria
## Out Of Scope For First Implementation
## Related Work

Spec default:
## Summary
## Problem
## Recommendation
## Core Concepts
## Rules or Principles
## How Subsystems Should Use The Model
## Acceptance Criteria
## Related Work

Implementation slice default:
## Summary
## Problem
## Proposed Change
## Acceptance Criteria
## Related Work

Optional sections when material:
- Product Model
- Affected Surfaces
- Dependencies
- Risks
- Data Model Direction
- Identity And Authorization
- Retention, Deletion, And Auditability
- External Connector Compatibility
- Architecture Notes
- Technical Notes

## Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>

## Out Of Scope For First Implementation
- <item>
- <item>

## Related Work
- Parent/consumer: #<issue>
- Related: #<issue>
- Blocked by: #<issue>
- Blocks: #<issue>
- Discussion: <url>
- Pull request: #<pr>

Suggested follow-up issues:
- <follow-up area 1>
- <follow-up area 2>

Execution Trace Contract

Canonical Prompt Identity: /issue Fallback Prompt Identity: issue

• This prompt participates in the issue 18 first-rollout execution-trace contract.
• Supported boundary: this execution-trace contract is prompt-scoped. It applies only to this prompt-driven workflow and does not guarantee a global Markdown footer after arbitrary VS Code or editor actions outside a prompt workflow.
• End the final response with exactly one ## Execution Trace section.
• Report the trace fields in this order: Prompt, Primary Agent, Handoffs, Skills/Subagents, Output Status.
• Use /issue as Prompt when this response came from an actual /issue invocation; use issue only when the response is still part of the same /issue prompt-driven workflow but the slash-command name is unavailable or ambiguous.
• Do not emit ## Captured Output or ## Execution Trace for plain follow-up turns or other non-prompt actions outside this prompt-driven workflow.
• Keep Prompt separate from Primary Agent.
• Include only the actual handoffs, skills, or subagents that materially influenced the run. Do not infer routing from available agents or tools. Report None when absent.
• Emit ## Captured Output on every run. Preserve raw command or tool output there in fenced blocks when practical, use No captured command or tool output was produced in this run. when nothing was captured, and say explicitly when the output is truncated, redacted, or both.

If the user asks for multiple issues, produce one complete issue draft per issue.

When Not To Use This Prompt

• The user needs design alternatives first -> use /architect
• The user already has an approved design and needs implementation planning artifacts -> use /spec-spec, then /spec-plan, then /spec-tasks
• The request is a bug investigation rather than issue authoring -> use /debug