Add workflow health monitoring runbook

[Copilot]

Documents systematic investigation and resolution of workflow failures based on the DeepReport incident response findings (Discussion #7277).

Changes

• Created .github/aw/runbooks/workflow-health.md - Operational runbook covering:

  • Common failure patterns: missing-tool errors, authentication failures, safe-input/output issues
  • Investigation procedures: log analysis, MCP server verification, permission checks
  • Resolution workflows with configuration examples
  • DeepReport case study: Weekly Issue Summary, Dev workflow, Daily Copilot PR Merged failures

• Documentation integration:

  • Linked from AGENTS.md Quick Reference (for AI agents)
  • Linked from docs/src/content/docs/troubleshooting/common-issues.md (for users)

Example Usage

When a workflow fails with missing-tool errors:

# 1. Download and analyze logs
gh aw logs --start-date -1d -o /tmp/logs

# 2. Verify MCP configuration
gh aw mcp inspect <workflow-name>

# 3. Fix by adding GitHub MCP server

---
tools:
  github:
    mode: remote
    toolsets: [default]
---

The runbook follows Diátaxis how-to guide format with actionable procedures, real incident analysis, and quick reference commands.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Document workflow health monitoring runbook</issue_title>
<issue_description>## Objective

Create a runbook documenting how to investigate and resolve workflow health issues, based on learnings from the DeepReport incident response.

Context

The DeepReport identified several workflow issues (failures, missing-tool errors) that needed investigation. A documented runbook will help future agents and maintainers quickly diagnose and fix similar problems.

Approach

1. Create a new documentation file (e.g., docs/runbooks/workflow-health.md)
2. Document common workflow failure patterns:
   • Missing tool configurations
   • Authentication/permission errors
   • Input/secret validation failures
3. Add investigation steps:
   • How to analyze workflow logs
   • How to identify missing-tool errors
   • How to verify MCP server configurations
4. Include resolution procedures:
   • Adding GitHub MCP server to workflows
   • Configuring safe-inputs/safe-outputs
   • Testing workflow fixes
5. Link to relevant documentation and examples

Files to Create

• docs/runbooks/workflow-health.md (or similar location)

Acceptance Criteria

• Runbook covers common workflow failure types
• Investigation steps are clear and actionable
• Resolution procedures include code examples
• Document references the DeepReport findings as case study
• Runbook is linked from main documentation
• Format follows repository documentation standards (Diátaxis framework)
  Related to [plan] Address workflow health and issue triage findings from DeepReport 2025-12-22 #7280

AI generated by Plan Command for discussion #7277

Comments on the Issue (you are @copilot in this section)

@pelikhan Place run books in .github/aw/runbooks

• Fixes [plan] Document workflow health monitoring runbook #7285

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.