[workflow-style] Normalize report formatting for breaking-change-checker

[github-actions]

Workflow to Update

Workflow File: .github/workflows/breaking-change-checker.md

Issue: This workflow creates breaking change reports but doesn't include markdown style guidelines in its prompt instructions.

Required Changes

Update the workflow prompt to include formatting guidelines for the breaking change report:

1. Header Levels

Add instruction in the report generation section:

Markdown Formatting: Use h3 (###) or lower for all headers in your breaking change report to maintain proper document hierarchy.

Example structure:

### Breaking Changes Summary
- Total breaking changes: X
- Severity: 🔴 Critical | 🟡 Medium | 🟢 Low
- Status: ⚠️ Action Required

### Critical Breaking Changes
[Always visible - changes that will break existing code]

1. **Change description**
   - **Impact**: What breaks
   - **Migration**: How to fix

<details>
<summary><b>View All Breaking Changes by Category</b></summary>

#### API Changes
- [Detailed list with examples...]

#### Configuration Changes
- [Detailed list with examples...]

#### Behavior Changes
- [Detailed list with examples...]

</details>

<details>
<summary><b>View Migration Examples</b></summary>

[Code examples showing before/after...]

</details>

### Migration Guide
[Always visible - step-by-step instructions]

2. Progressive Disclosure

Add instruction for handling many breaking changes:

Progressive Disclosure: Wrap detailed change descriptions and migration examples in <details><summary><b>Section Name</b></summary> tags. Keep the summary, critical changes, and migration guide visible.

3. Report Structure

Suggest consistent structure:

• Summary: Count and severity (always visible)
• Critical Changes: Most impactful changes (always visible)
• All Changes by Category: Complete breakdown (in <details> tags)
• Migration Examples: Code samples (in <details> tags)
• Migration Guide: Step-by-step instructions (always visible)

Design Principles (Airbnb-Inspired)

The updated workflow should create reports that:

1. Build trust through clarity: Critical breaking changes immediately visible
2. Exceed expectations: Include migration examples and step-by-step guides
3. Create delight: Easy to understand impact and fix path
4. Maintain consistency: Follow patterns from other checker workflows

Example Reference

See workflows like cli-version-checker or schema-consistency-checker for good examples of structured checker reports.

Verification

After updating, test by:

1. Running the workflow on a PR with breaking changes
2. Verifying the report uses h3+ headers
3. Checking that detailed changes use <details> tags
4. Confirming the migration guide is clear and actionable

AI generated by Workflow Normalizer

• expires on Feb 7, 2026, 12:24 PM UTC