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

Epic Issue Authoring

Draft a GitHub epic that defines a broad initiative spanning multiple follow-up issues. This is a specialized variant of /issue and should default to an epic shape unless the user explicitly asks for something narrower.

Use this prompt as reduced-scope mode when the target issue is already known to be an epic. If the shape is still unclear, start with /issue; if the work is actually a shared design or one bounded implementation step, use /issue-spec or /issue-slice instead.

User Input

The user's message may include:

• A broad initiative, product capability, or platform change
• A parent strategy, RFC, planning doc, or design note
• Existing related issues that need to be unified under one epic
• Constraints, non-goals, or rollout boundaries
• A request to break a large area into sub-issues or workstreams

Bias

Bias heavily toward:

• Scope decisions and ownership boundaries
• Product or domain model definition
• Lifecycle, workflow, and operating rules
• Authorization, compliance, audit, retention, or connector constraints when relevant
• GitHub-native hierarchy: sub-issues, dependencies, project tracking, milestones
• Clear out-of-scope decisions to stop scope creep

Bias away from:

• API contracts
• Detailed migration mechanics
• File-by-file implementation tasks
• Sprint-level execution detail better suited to follow-up issues

If the request is too small for an epic, say so and recommend /issue-slice or /issue-spec instead of inflating the scope.

Process

1. Establish Epic Boundaries

Before drafting:

1. Read the directly relevant sources named by the user.
2. Identify the initiative outcome in one sentence.
3. Define what is in scope for the epic and what is explicitly deferred.
4. Identify the durable concepts the epic must standardize.
5. Identify likely child issues, blocked-by relationships, and upstream dependencies.
6. Capture GitHub metadata only when justified: issue type, labels, milestone, project, dependencies, and sub-issues.

If the request is still exploratory discussion rather than tracked work, recommend opening a discussion instead of an epic.

2. Shape The Epic

Use this default epic section set:

• Summary
• Scope Decisions
• Decomposition Plan
• Acceptance Criteria
• Out Of Scope For First Implementation
• Related Work

Add these only when the source material makes them material to the epic:

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

Do not emit empty headings. A smaller epic with one clear boundary should stay compact.

3. Epic Writing Rules

1. Start with a decisive title, usually Epic: <outcome>.
2. Lead with the organizational or platform outcome, not the first implementation step.
3. Treat the epic as the coordination boundary, not the implementation ticket.
4. Define stable concepts and authority boundaries before describing child work.
5. Prefer principles, operating rules, and decomposition guidance over low-level detail.
6. Use Suggested sub-issues aggressively when work should split into independent tracks.
7. Use dependency notes when other epics or specs must land first.
8. Include out-of-scope statements that protect the epic from becoming a dumping ground.
9. Prefer 5-8 headings over a long planning artifact unless the domain genuinely needs more structure.

4. Acceptance Criteria

Epic acceptance criteria should verify that the initiative is well-bounded and implementation-ready for decomposition. Criteria should:

• Define what the epic standardizes or coordinates
• Identify required subdomains or use cases it covers
• Require explicit follow-up issue areas when implementation is deferred
• Avoid pretending the whole initiative will ship in one issue

5. Metadata Guidance

Prefer these metadata choices when supported by the source material:

• Issue type: epic
• Labels: epic, planning, architecture, plus domain labels like backend, frontend, or compliance
• Milestone: only when the epic belongs to a real release or phase boundary
• Project: only when the epic should appear in a specific GitHub Project view
• Dependencies: parent epics, required specs, blocking platform work
• Sub-issues: core design, persistence, API, UI, policy, migration, and test slices

Output Format

Title: Epic: <initiative outcome>

Suggested issue type: epic

Suggested labels:
- epic
- planning
- <domain label>

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>
- <child issue title>

Body:
# Epic: <initiative outcome>

## Summary
<1-2 short paragraphs>

## Scope Decisions
<explicit in-scope and out-of-scope boundaries>

## Decomposition Plan
<primary workstreams, dependencies, and suggested sub-issues>

## Product Model
<include only when the epic needs durable concepts or authority boundaries>

## Operating Rules
<include only when lifecycle, policy, or audit rules are central to the epic>

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

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

## Related Work
- Parent/consumer: #<issue>
- Related: #<issue>
- Blocked by: #<issue>

## Technical Notes
<include only when short cross-cutting constraints are needed>

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

Execution Trace Contract

Canonical Prompt Identity: /issue-epic Fallback Prompt Identity: issue-epic

• 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-epic as Prompt when this response came from an actual /issue-epic invocation; use issue-epic only when the response is still part of the same /issue-epic 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.

When Not To Use This Prompt

• The work is a shared design decision rather than a broad initiative -> use /issue-spec
• The work is a bounded build step that should be implemented directly -> use /issue-slice
• The user needs alternatives and tradeoffs before issue writing -> use /architect