[workflow-style] Normalize report formatting for pr-nitpick-reviewer

[github-actions]

Workflow to Update

Workflow File: .github/workflows/pr-nitpick-reviewer.md

Issue: This workflow creates discussions and 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 instructions section:

1. Header Levels

Add instruction after the "Your Mission" section:

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

2. Progressive Disclosure

Add instruction for handling long content:

Progressive Disclosure: When creating discussions with many nitpicks, wrap long sections in <details><summary><b>Section Name</b></summary> tags to improve readability and reduce scrolling.

Example structure:

### Nitpick Summary
- Total nitpicks found: X
- Critical: Y
- Minor: Z

<details>
<summary><b>View All Nitpicks by File</b></summary>

[Detailed breakdown of each file and nitpick...]

</details>

<details>
<summary><b>View Patterns Across PR</b></summary>

[Common patterns and themes...]

</details>

### Key Recommendations
[Always visible - most important suggestions]

3. Report Structure Guidance

Suggest a consistent structure:

• Brief summary (always visible)
• Critical nitpicks (always visible)
• Detailed file-by-file analysis (in <details> tags)
• Common patterns (in <details> tags)
• Recommendations (always visible)

Design Principles (Airbnb-Inspired)

The updated workflow should create reports that:

1. Build trust through clarity: Most important nitpicks immediately visible
2. Exceed expectations: Add helpful context about patterns and trends
3. Create delight: Use progressive disclosure to reduce overwhelm
4. Maintain consistency: Follow the same patterns as other reporting workflows

Example Reference

See workflows like auto-triage-issues or daily-repo-chronicle for good examples of structured reporting with proper header levels and progressive disclosure.

Verification

After updating, test by:

1. Triggering the workflow with /nit on a PR
2. Verifying the discussion uses h3+ headers
3. Checking that long sections use <details> tags
4. Confirming the report is easy to scan and navigate

AI generated by Workflow Normalizer

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