[Code Quality] Document safe output patterns and multi-output workflow design best practices

[github-actions]

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 AGENTS.md
• Reviewed by 2+ experienced workflow authors

Expected Impact

• Consistency: Workflows follow established patterns
• Efficiency: Developers make faster decisions
• Quality: Better UX through standardized output strategies
• Maintainability: Clear patterns reduce technical debt

Priority

Medium-High - This is foundational documentation that improves all future workflow development. High-impact but not urgent.

Source

Extracted from Lock File Statistics discussion #12946 - "Documentation of Safe Output Patterns" recommendation.

Key Finding: 110 workflows (74.8%) support multiple output types, but patterns are undocumented.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 14, 2026, 5:10 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster