[workflow-style] Normalize report formatting for ci-doctor

[github-actions]

Workflow to Update

Workflow File: .github/workflows/ci-doctor.md
Issue: This workflow investigates CI failures and creates diagnostic issues, but doesn't include markdown style guidelines.

Required Changes

Update the workflow prompt to include these formatting guidelines:

1. Header Levels

Add instruction: "Use h3 (###) or lower for all headers in your issue report to maintain proper document hierarchy."

Example:

### Diagnosis Summary
#### Root Cause Analysis

2. Progressive Disclosure

Add instruction: "Wrap verbose logs and stack traces in <details><summary><b>Section Name</b></summary> tags to improve readability."

Example:

<details>
<summary><b>Full Error Logs</b></summary>

[Complete stack traces and error logs here...]

</details>

3. Report Structure

Suggest a structure like:

• Summary (always visible): Failure type, affected jobs, severity
• Root Cause (always visible): Primary error identified
• Full Diagnostics (in <details> tags): Complete logs, stack traces, historical patterns
• Recommended Fix (always visible): Clear action items and next steps

Design Principles (Airbnb-Inspired)

The updated workflow should create reports that:

1. Build trust through clarity: Primary failure cause immediately visible
2. Exceed expectations: Add context like similar past failures, success rate trends
3. Create delight: Use progressive disclosure to hide overwhelming log details
4. Maintain consistency: Follow the same patterns as other diagnostic workflows

Example Reference

See workflows like audit-workflows that import shared/reporting.md for good examples of structured reporting.

Agent Task

1. Update .github/workflows/ci-doctor.md to include an import: - shared/reporting.md in the frontmatter imports section
2. Reference the style guidelines in the workflow instructions
3. Test the updated workflow to ensure it produces well-formatted diagnostic reports

AI generated by Workflow Normalizer

• expires on Feb 11, 2026, 3:23 AM UTC