[workflow-style] Normalize report formatting for grumpy-reviewer

[github-actions]

Workflow to Update

Workflow File: .github/workflows/grumpy-reviewer.md

Issue: This workflow creates PR comments but doesn't include markdown style guidelines in its prompt instructions.

Required Changes

Update the workflow prompt to include these formatting guidelines in the "Step 4: Write Review Comments" section:

1. Header Levels

Add instruction for comment structure:

Markdown Formatting: When creating summary comments with multiple sections, use h3 (###) or lower for all headers to maintain proper document hierarchy.

2. Progressive Disclosure

Add instruction for handling many issues:

Progressive Disclosure: When you find many issues and need to create a summary comment, wrap detailed findings in <details><summary><b>Section Name</b></summary> tags to improve readability.

Example structure for summary comments:

### Code Review Summary

**Issues Found**: X issues across Y files

#### Critical Issues
1. [Always visible - most important problems]
2. ...

<details>
<summary><b>View All Issues by Category</b></summary>

#### Performance Issues
- [Detailed list...]

#### Security Concerns
- [Detailed list...]

#### Code Smells
- [Detailed list...]

</details>

### What You Should Fix First
[Always visible - prioritized action items]

3. Comment Type Guidance

Clarify when to use each approach:

• Individual review comments: Single-issue feedback on specific lines (no headers needed)
• Summary comments: When you need to provide overall feedback (use proper headers and progressive disclosure)

Design Principles (Airbnb-Inspired)

The updated workflow should create comments that:

1. Build trust through clarity: Critical issues immediately visible
2. Exceed expectations: Add context about severity and priority
3. Create delight: Use progressive disclosure for long reviews
4. Maintain consistency: Follow patterns from other review workflows

Example Reference

See workflows like security-review or pr-triage-agent for good examples of structured PR comments.

Verification

After updating, test by:

1. Triggering the workflow with /grumpy on a PR with many changes
2. Verifying summary comments use h3+ headers
3. Checking that long lists use <details> tags
4. Confirming the grumpy tone is preserved while structure improves

AI generated by Workflow Normalizer

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