Document safe output patterns and multi-output workflow design

[Copilot]

74.8% of workflows (110/147) use multiple safe output types, but selection criteria and composition patterns were undocumented, leading to inconsistent output strategies and suboptimal routing decisions.

Changes

Core Documentation

• docs/safe-outputs-guide.md - Decision tree, 4 workflow patterns, best practices
  • When to use each output type (create-issue, create-discussion, create-pull-request, add-comment, update-issue)
  • Multi-output patterns: Conditional (severity routing), Hierarchical (parent-child), Fix-or-Report (progressive), Comment-First (update-focused)
  • Anti-patterns and hygiene rules (expiration, deduplication, volume limits)

Example Workflows

• docs/examples/safe-outputs/ - 4 complete patterns with decision logic
  • conditional-output.md - Security scanning with CVSS-based routing
  • multi-output-analysis.md - Code quality with discussion + child issues
  • fix-or-report.md - Dependency updates with automated/manual paths
  • comment-pattern.md - CI status with escalation thresholds

Technical Reference

• scratchpad/safe-outputs-patterns.md - Implementation details
  • Job dependency coordination and temporary ID cross-referencing
  • API rate limiting and performance considerations
  • Advanced patterns (idempotent operations, batch processing, progressive escalation)

Integration

• AGENTS.md - Added "Safe Outputs Best Practices" section with quick decision guide
• scratchpad/README.md - Cross-reference to new documentation

Pattern Example

# Conditional: Route by severity
safe-outputs:
  create-issue:          # Critical only (CVSS ≥ 7.0)
    title-prefix: "[security-critical] "
    expires: 7d
    max: 5
  create-discussion:     # All findings summary
    category: "Security"
    close-older-discussions: true
    max: 1
  add-comment:           # PR status + links
    target: triggering
    max: 1

Decision logic: Critical findings → individual issues for tracking; all findings → discussion for audit; PR → comment with summary and links.

Statistics Referenced

Analysis of 147 production workflows:

• 76.9% use create-issue
• 73.5% use create-discussion
• 36.7% use create-pull-request
• 74.8% use 2+ output types

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Document safe output patterns and multi-output workflow design best practices</issue_title>
<issue_description>## Description

74.8% of agentic workflows (110 out of 147) support multiple safe output types (issues, discussions, pull requests, comments). However, there's no documented guidance on when to use each output type or how to design multi-output workflows effectively.

Current State

Safe Output Usage (from Lock File Statistics #12946):

Output Type	Workflows	Percentage
create-issue	113	76.9%
create-discussion	108	73.5%
create-pull-request	54	36.7%
add-comment	34	23.1%
update-issue	4	2.7%

Multi-Output Workflows: 110 workflows (74.8%) support 2+ output types

Problem

Without clear documentation, developers must:

• Guess when to use issues vs discussions
• Figure out multi-output workflow patterns by example
• Risk creating inconsistent output strategies across workflows
• Miss opportunities for sophisticated output routing

This leads to:

• Inconsistent UX: Similar workflows use different output types
• Redundancy: Creating both issue and discussion when one would suffice
• Confusion: Users don't know where to find workflow results
• Technical debt: Workflows evolved ad-hoc without design principles

Suggested Documentation

1. Safe Output Decision Tree

Create a decision tree for output type selection:

### When to Use Each Output Type

**Create Issue** - Use when:
- Action is required (task tracking)
- Assignment to developer/agent needed
- Status tracking required (open/closed)
- Needs labels, milestones, projects
- Example: Security vulnerability found, test failure, code quality issue

**Create Discussion** - Use when:
- Sharing analysis, reports, insights
- No specific action required
- Community conversation welcome
- Long-term reference material
- Example: Performance report, security scan summary, trend analysis

**Create Pull Request** - Use when:
- Automated fix can be proposed
- Code changes are ready to review
- Changes are non-breaking and safe
- Example: Dependency updates, code formatting, documentation fixes

**Add Comment** - Use when:
- Updating existing issue/PR/discussion
- Providing progress updates
- Responding to triggers
- Example: CI results, approval status, analysis updates

2. Multi-Output Workflow Patterns

Document patterns for workflows that produce multiple outputs:

Pattern 1: Conditional Outputs

# Create issue if critical, discussion if informational
- If critical security finding → create issue
- If low severity finding → create discussion

Pattern 2: Hierarchical Outputs

# Discussion for report, issues for sub-tasks
- Create discussion with analysis summary
- Create issues for each actionable finding

Pattern 3: Fix-or-Report

# Try to fix, report if unable
- If fixable → create pull request
- If needs human → create issue
- Always → add summary comment to discussion

3. Best Practices Guide

## Safe Output Best Practices

### Output Hygiene
- Expire discussions after 7-14 days for time-sensitive reports
- Close auto-generated issues when conditions resolve
- Link related outputs (issue to discussion, PR to issue)

### Avoiding Noise
- Don't create both issue and discussion for same finding
- Use comments to update existing items instead of creating new ones
- Aggregate multiple findings into single output when appropriate

### User Experience
- Consistent output types for similar workflow categories
- Clear titles that indicate workflow source
- Standard sections in output bodies (Summary, Details, Action Items)

### Error Handling
- Always produce at least one output (even if just error report)
- Use discussion for error reports (not issues for workflow failures)
- Include workflow run link for debugging

4. Examples Repository

Create /docs/examples/safe-outputs/ with:

• conditional-output.md - Workflow that chooses output type dynamically
• multi-output-analysis.md - Workflow creating discussion + issues
• fix-or-report.md - Workflow attempting PR, falling back to issue
• comment-pattern.md - Workflow adding comments to trigger source

Files to Create

1. docs/safe-outputs-guide.md - Main decision tree and patterns
2. docs/examples/safe-outputs/ - Example workflow directory
3. AGENTS.md - Add "Safe Outputs Best Practices" section
4. scratchpad/safe-outputs-patterns.md - Deep-dive technical guide

Success Criteria

• Safe output decision tree documented
• At least 3 multi-output patterns documented with examples
• Best practices guide covering common pitfalls
• 4+ example workflows demonstrating patterns
• Documentation linked from ...

• Fixes [Code Quality] Document safe output patterns and multi-output workflow design best practices #12983

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.