Add shared component for asset upload and discussion creation pattern

.github/workflows/shared/asset-discussion-pattern.md

@@ -0,0 +1,224 @@
+---
+# Asset Upload and Discussion Creation Pattern
+# Standardized workflow for uploading charts/assets and embedding in discussions
+---
+
+# Asset Upload and Discussion Creation Pattern
+
+This shared component provides a standardized pattern for workflows that generate visualizations or other assets and publish them in GitHub Discussions.
+
+## Prerequisites
+
+Your workflow must have safe-outputs configured:
+
+```yaml
+safe-outputs:
+  upload-asset:
+  create-discussion:
+    category: "General"  # or "audits", "reports", etc.
+    max: 1
+    close-older-discussions: true  # Optional: close previous reports
+    expires: 3d  # Optional: auto-close after 3 days
+```
+
+## Standard Workflow Pattern
+
+### Phase 1: Generate Assets
+
+Generate your charts, images, or other assets:
+
+```bash
+# Example: Generate charts with Python
+python3 /tmp/gh-aw/python/generate_charts.py
+
+# Verify assets exist
+ls -lh /tmp/gh-aw/python/charts/*.png
+```
+
+**Chart Quality Standards** (for image assets):
+- **DPI**: 300 minimum
+- **Figure Size**: 12x7 inches (or appropriate for content)
+- **Format**: PNG with transparent or white background
+- **File Size**: < 5MB recommended
+
+### Phase 2: Upload Assets
+
+Upload each asset and collect the returned URLs:
+
+```bash
+# Upload assets using the upload asset tool
+# The tool returns a URL for each uploaded file
+
+# For each chart/asset:
+# 1. Call: upload asset with path /tmp/gh-aw/python/charts/chart1.png
+# 2. Collect the returned URL (e.g., https://raw.githubusercontent.com/...)
+# 3. Store URL for use in discussion markdown
+
+# Example workflow:
+# - Upload chart1.png → Get URL1
+# - Upload chart2.png → Get URL2
+# - Upload chart3.png → Get URL3
+```
+
+**Important Notes**:
+- Asset URLs are published to an orphaned git branch
+- URLs become accessible after workflow completion
+- Assets persist indefinitely (no expiration)
+- Use descriptive filenames (e.g., `issue_activity_trends.png` not `chart1.png`)
+
+### Phase 3: Create Discussion with Embedded Assets
+
+Create a discussion with embedded asset URLs:
+
+```markdown
+# Example Discussion Body
+
+Brief 2-3 paragraph summary of key findings.
+
+## 📊 Visualizations
+
+### Chart 1: Descriptive Title
+![Chart 1](URL_FROM_UPLOAD_ASSET_1)
+
+[2-3 sentence analysis of what the chart shows]
+
+### Chart 2: Descriptive Title
+![Chart 2](URL_FROM_UPLOAD_ASSET_2)
+
+[Analysis of second chart]
+
+## Summary
+
+Key takeaways and action items.
+
+---
+*Report generated by [Workflow Name] workflow*
+*Run: [${{ github.run_id }}](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*
+```
+
+## Discussion Configuration Best Practices
+
+### Title Formatting
+
+Use descriptive, dated titles:
+- **Good**: `Daily Code Metrics Report - 2026-01-20`
+- **Good**: `[daily-issues] Issue Analysis - 2026-01-20`
+- **Avoid**: `Report`, `Analysis` (too generic)
+
+### Category Selection
+
+Choose appropriate categories:
+- **`General`**: Informational reports, summaries
+- **`audits`**: Security, compliance, health checks
+- **`reports`**: Data analysis, metrics, trends
+- **`Q&A`**: Question-based reports requiring response
+
+### Close Older Discussions
+
+For daily/weekly reports, use `close-older-discussions: true`:
+- Keeps discussions clean (only latest visible)
+- Previous reports remain accessible via search
+- Reduces notification noise
+
+### Expiration
+
+Set `expires` for time-sensitive reports:
+- **`expires: 3d`**: Daily reports (closed after 3 days)
+- **`expires: 7d`**: Weekly reports
+- **No expiration**: Permanent reference reports
+
+## Common Patterns
+
+### Pattern 1: Multiple Charts with Analysis
+
+```markdown
+## 📊 Visualizations
+
+### Chart Title 1
+![Chart 1](URL_1)
+[Analysis]
+
+### Chart Title 2  
+![Chart 2](URL_2)
+[Analysis]
+
+## Summary
+Key findings and recommendations.
+```
+
+### Pattern 2: Single Hero Chart + Details
+
+```markdown
+## Overview
+
+![Main Chart](URL_1)
+
+[2-3 paragraph analysis of the main chart]
+
+## Details
+
+Additional context and findings.
+```
+
+### Pattern 3: Comparison Charts
+
+```markdown
+## Comparison Analysis
+
+| Metric | Current | Previous | Change |
+|--------|---------|----------|--------|
+| X      | 100     | 90       | ⬆️ +11% |
+
+### Trend Visualization
+![Trend Chart](URL_1)
+
+### Distribution Comparison
+![Distribution Chart](URL_2)
+```
+
+## Troubleshooting
+
+### Asset URLs Not Working
+
+**Problem**: Markdown shows broken image icon
+**Solution**: 
+- Verify upload asset tool returned success
+- Check URL format (should be `https://raw.githubusercontent.com/...`)
+- Wait for workflow to complete (assets publish at end)
+- Verify file exists at uploaded path
+
+### Discussion Not Created
+
+**Problem**: Workflow completes but no discussion appears
+**Solution**:
+- Check safe-outputs.create-discussion is configured
+- Verify category exists in repository
+- Check max limit not exceeded
+- Review workflow logs for errors
+
+### Charts Not Displaying Correctly
+
+**Problem**: Charts too small, blurry, or distorted
+**Solution**:
+- Use DPI 300 minimum
+- Set appropriate figure size (12x7 recommended)
+- Save with `bbox_inches='tight'`
+- Use PNG format, not JPEG
+
+## Examples
+
+See these workflows for complete implementations:
+- `daily-code-metrics.md` - 6 charts with trend analysis
+- `daily-issues-report.md` - 2 charts with clustering
+- `copilot-session-insights.md` - Session activity charts
+
+## Migration Checklist
+
+To adopt this pattern in an existing workflow:
+
+- [ ] Configure `safe-outputs.upload-asset` and `safe-outputs.create-discussion`
+- [ ] Generate assets to standard path (e.g., `/tmp/gh-aw/python/charts/`)
+- [ ] Upload each asset and collect URLs
+- [ ] Create discussion body with embedded image markdown
+- [ ] Test workflow to verify assets display correctly
+- [ ] Verify old discussions close if `close-older-discussions: true`