[workflow-style] Normalize report formatting for daily-file-diet

[github-actions]

Workflow to Update

Workflow File: .github/workflows/daily-file-diet.md
Issue: This workflow generates GitHub issues but doesn't include markdown style guidelines

Required Changes

Update the workflow prompt to include these formatting guidelines:

1. Header Levels

Add instruction after line 100 (before "Phase 4"):

## Report Formatting Guidelines

**CRITICAL**: Follow these formatting guidelines to create well-structured, readable reports:

### 1. Header Levels
**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**

The issue title serves as h1, so all content headers should start at h3:
- Use `###` for main sections (e.g., "### Analysis Summary", "### Refactoring Recommendations")
- Use `####` for subsections (e.g., "#### Suggested File Splits", "#### Testing Requirements")
- Never use `##` (h2) or `#` (h1) in the report body

### 2. Progressive Disclosure
**Wrap long sections in `<details><summary><b>Section Name</b></summary>` tags to improve readability and reduce scrolling.**

Use collapsible sections for:
- Full file contents or large code snippets
- Detailed function-by-function breakdown
- Complete list of all functions to move
- Verbose analysis of dependencies

Example:
``````markdown
<details>
<summary><b>Full Function List</b></summary>

[Long list of functions to refactor...]

</details>

3. Report Structure Pattern

Your issue should follow this structure for optimal readability:

1. Analysis Summary (always visible): Brief overview of the file size issue and impact
2. Key Recommendations (always visible): Top 2-3 file split suggestions with rationale
3. Detailed Refactoring Plan (in <details> tags): Complete function-by-function breakdown
4. Implementation Checklist (always visible): Step-by-step actions to complete the refactoring

Design Principles

Create reports that:

• Build trust through clarity: Most important info (summary, top recommendations) immediately visible
• Exceed expectations: Add helpful context like complexity analysis, dependency graphs
• Create delight: Use progressive disclosure to reduce overwhelm for detailed breakdowns
• Maintain consistency: Follow the same patterns as other reporting workflows

#### 4. Update Report Template

Modify the issue template around line 140 to demonstrate proper formatting:

``````markdown
### 🏋️ File Diet Recommendation

Brief 1-2 paragraph summary explaining why this file needs refactoring and the overall strategy.

### 📊 File Analysis

- **Current Size**: [NUMBER] lines
- **Threshold**: 800 lines
- **Recommended Splits**: [NUMBER] files
- **Complexity**: [HIGH/MEDIUM/LOW]

### 🎯 Refactoring Recommendations

#### Suggested File Splits

1. **`pkg/workflow/[new_file_1].go`**
   - Purpose: [Brief description]
   - Functions to move: [3-5 key function names]

2. **`pkg/workflow/[new_file_2].go`**
   - Purpose: [Brief description]
   - Functions to move: [3-5 key function names]

<details>
<summary><b>Detailed Refactoring Plan</b></summary>

### Complete Function Breakdown

#### New File: `[new_file_1].go`

**Functions to move:**
- `FunctionName1()` - [description]
- `FunctionName2()` - [description]
- [... full list ...]

**Shared dependencies:**
- [List of types, interfaces, or utilities needed]

#### New File: `[new_file_2].go`

[Similar detailed breakdown...]

</details>

### ✅ Implementation Checklist

- [ ] Create new file `pkg/workflow/[new_file_1].go`
- [ ] Move functions and add tests
- [ ] Create new file `pkg/workflow/[new_file_2].go`
- [ ] Move functions and add tests
- [ ] Update imports in affected files
- [ ] Run `make test` to verify all tests pass
- [ ] Run `make lint` to ensure code quality

Example Reference

See workflows like daily-repo-chronicle, daily-issues-report, or weekly-issue-summary for good examples of structured reporting with proper header levels and progressive disclosure.

Agent Task

Update the workflow file .github/workflows/daily-file-diet.md to include the formatting guidelines above. Position them before the "Phase 4: Create Issue" section so they're applied when generating the issue content.

AI generated by Workflow Normalizer

• expires on Feb 8, 2026, 12:29 PM UTC