Document safe output patterns and multi-output workflow design

.github/aw/actions-lock.json

@@ -100,7 +100,7 @@
       "version": "v5.6.0",
       "sha": "a26af69be951a213d495a4c3e4e4022e16d87065"
     },
-    "actions/upload-artifact@v4": {
+    "actions/upload-artifact@v4.6.2": {
       "repo": "actions/upload-artifact",
       "version": "v4.6.2",
       "sha": "ea165f8d65b6e75b540449e92b4886f43607fa02"

AGENTS.md

@@ -1037,6 +1037,151 @@ tools:
 - Accessibility analysis and visual testing
 - Multi-browser support (Chromium, Firefox, Safari)
 
+## Safe Outputs Best Practices
+
+Safe outputs are the primary mechanism for workflows to create GitHub issues, discussions, pull requests, and comments. Understanding when and how to use each output type is critical for creating effective workflows.
+
+### Quick Output Type Selection
+
+**Decision Guide:**
+- **Action required?** → `create-issue`
+- **Automated fix possible?** → `create-pull-request`
+- **Report/analysis only?** → `create-discussion`
+- **Updating existing item?** → `add-comment`
+
+### Output Types and When to Use Them
+
+**Create Issue (`create-issue`)** - Use when:
+- Action is required (task tracking, assignment needed)
+- Status tracking required (open/closed)
+- Needs labels, milestones, or project boards
+- Time-sensitive action items need visibility
+
+**Create Discussion (`create-discussion`)** - Use when:
+- Sharing analysis, reports, or insights
+- No specific action required
+- Community conversation welcome
+- Long-term reference material needed
+- Regular status reports or summaries
+
+**Create Pull Request (`create-pull-request`)** - Use when:
+- Automated fix can be proposed
+- Code changes are ready to review
+- Changes are non-breaking and safe
+- Tests can validate the changes
+
+**Add Comment (`add-comment`)** - Use when:
+- Updating existing issue/PR/discussion
+- Providing progress updates
+- Responding to triggers
+- Linking related items created by the workflow
+
+**Update Issue (`update-issue`)** - Use when:
+- Need to modify existing issue content, labels, or assignees
+- Changing status or milestones
+- Use sparingly - prefer comments for updates
+
+### Multi-Output Patterns
+
+74.8% of agentic workflows use multiple safe output types. Common patterns:
+
+**Pattern 1: Conditional Outputs** - Route by severity/priority
+```yaml
+safe-outputs:
+  create-issue:      # Critical findings only
+    max: 5
+  create-discussion: # Summary of all findings
+    max: 1
+```
+
+**Pattern 2: Hierarchical Outputs** - Parent summary + child tasks
+```yaml
+safe-outputs:
+  create-discussion: # Overall analysis
+    max: 1
+  create-issue:      # Individual actionable items
+    max: 10
+  add-comment:       # Link discussion and issues
+    max: 1
+```
+
+**Pattern 3: Fix-or-Report** - Attempt automation, fallback to manual
+```yaml
+safe-outputs:
+  create-pull-request: # If fix is safe
+    max: 1
+  create-issue:        # If manual review needed
+    max: 1
+```
+
+**Pattern 4: Comment-First** - Update-focused with escalation
+```yaml
+safe-outputs:
+  add-comment:       # Always provide status
+    hide-older-comments: true
+    max: 1
+  create-issue:      # Only for persistent problems
+    max: 1
+```
+
+### Best Practices
+
+**Avoid Duplication:**
+```yaml
+# ❌ BAD - Creates both issue and discussion for same finding
+safe-outputs:
+  create-issue: {max: 10}
+  create-discussion: {max: 1}
+# Agent duplicates content in both
+
+# ✅ GOOD - Conditional based on severity
+safe-outputs:
+  create-issue: {max: 5}      # Critical only
+  create-discussion: {max: 1}  # Summary with all findings
+```
+
+**Cleanup Transient Items:**
+```yaml
+safe-outputs:
+  create-issue:
+    expires: 7d  # Auto-close when condition resolves
+  create-discussion:
+    close-older-discussions: true  # Keep only latest
+```
+
+**Limit Output Volume:**
+```yaml
+safe-outputs:
+  create-issue:
+    max: 5  # Top 5 priorities, not all 50 findings
+```
+
+**Consistent Titles:**
+```yaml
+safe-outputs:
+  create-issue:
+    title-prefix: "[security-critical] "
+  create-discussion:
+    title-prefix: "[Security Scan] "
+```
+
+### Documentation References
+
+- **[Safe Outputs Guide](docs/safe-outputs-guide.md)** - Decision tree, patterns, best practices
+- **[Example Workflows](docs/examples/safe-outputs/)** - Conditional, multi-output, fix-or-report, comment patterns
+- **[Technical Deep-Dive](scratchpad/safe-outputs-patterns.md)** - Implementation details, advanced patterns
+- **[System Specification](scratchpad/safe-outputs-specification.md)** - Formal specification
+- **[Environment Variables](scratchpad/safe-output-environment-variables.md)** - Configuration reference
+
+### Statistics
+
+Based on 147 agentic workflows (2026-01):
+- 76.9% use `create-issue` (113 workflows)
+- 73.5% use `create-discussion` (108 workflows)
+- 36.7% use `create-pull-request` (54 workflows)
+- 23.1% use `add-comment` (34 workflows)
+- 74.8% use 2+ output types (110 workflows)
+
 ## Testing Strategy
 
 **⚠️ IMPORTANT: Prefer selective testing over running all tests.**

docs/examples/safe-outputs/README.md

@@ -0,0 +1,74 @@
+# Safe Output Examples
+
+This directory contains example workflows demonstrating safe output patterns and best practices for GitHub Agentic Workflows.
+
+## Examples
+
+### [Conditional Output Pattern](./conditional-output.md)
+Dynamic output type selection based on analysis results, specifically for security vulnerability scanning.
+
+**Pattern:** Route findings by severity
+- Critical vulnerabilities → Individual issues
+- Medium/low vulnerabilities → Summary discussion
+- All findings → Comment on PR
+
+**Use Cases:** Security scanning, code quality analysis, compliance checking
+
+### [Multi-Output Analysis Pattern](./multi-output-analysis.md)
+Hierarchical output strategy where a parent discussion contains the overall analysis, with child issues for actionable sub-items.
+
+**Pattern:** Parent summary + child tasks
+- Discussion → Comprehensive analysis
+- Issues → Individual actionable items
+- Comment → Links between items
+
+**Use Cases:** Code quality reports, audit findings, multi-item analysis
+
+### [Fix-or-Report Pattern](./fix-or-report.md)
+Progressive approach where the workflow attempts an automated fix first, and falls back to creating an issue if the fix cannot be automated.
+
+**Pattern:** Attempt automation, fallback to manual
+- Automated fix possible → Pull request
+- Manual intervention needed → Issue
+- Always → Summary comment
+
+**Use Cases:** Dependency updates, automated refactoring, configuration fixes
+
+### [Comment Pattern](./comment-pattern.md)
+Comment-first approach for status updates with escalation to issues only when necessary.
+
+**Pattern:** Update-focused with escalation
+- Always → Add comment with status
+- Persistent failure (3+ runs) → Create issue
+- Hide older comments → Clean thread
+
+**Use Cases:** CI status reporting, progress updates, monitoring
+
+## Common Patterns
+
+All examples demonstrate:
+- ✅ Clear decision logic for output type selection
+- ✅ Proper use of `max` limits
+- ✅ Cross-referencing between outputs
+- ✅ Appropriate use of expiration and cleanup
+- ✅ Comprehensive documentation in outputs
+
+## Pattern Selection
+
+| Goal | Pattern | Example |
+|------|---------|---------|
+| Route by severity/priority | Conditional Output | Security scan results |
+| Parent summary + sub-tasks | Multi-Output Analysis | Code quality report |
+| Try automated fix first | Fix-or-Report | Dependency updates |
+| Status updates + escalation | Comment Pattern | CI status reporting |
+
+## Related Documentation
+
+- **[Safe Outputs Guide](../safe-outputs-guide.md)** - Complete decision tree and best practices
+- **[Technical Deep-Dive](../../scratchpad/safe-outputs-patterns.md)** - Implementation details
+- **[System Specification](../../scratchpad/safe-outputs-specification.md)** - Formal specification
+
+---
+
+**Last Updated:** 2026-01-31  
+**Related Issues:** [#12407](https://github.com/githubnext/gh-aw/issues/12407)