starter-workflows/agentic/unbloat-docs.md

---
name: Documentation Unbloat
description: Reviews and simplifies documentation by reducing verbosity while maintaining clarity and completeness
on:
  # Daily (scattered execution time)
  schedule: daily
  
  # Command trigger for /unbloat in PR comments
  slash_command:
    name: unbloat
    events: [pull_request_comment]
  
  # Manual trigger for testing
  workflow_dispatch:

# Minimal permissions - safe-outputs handles write operations
permissions:
  contents: read
  pull-requests: read
  issues: read

# Network access for documentation research
network:
  allowed:
    - defaults
    - github

# Sandbox configuration
sandbox:
  agent: awf

# Tools configuration
tools:
  cache-memory: true
  github:
    toolsets: [default]
  edit:
  bash:
    - "find * -name '*.md'"
    - "wc -l *"
    - "grep -n *"
    - "git"
    - "cat *"
    - "head *"
    - "tail *"
    - "cd *"
    - "echo *"
    - "mkdir *"
    - "cp *"
    - "mv *"

# Safe outputs configuration
safe-outputs:
  create-pull-request:
    expires: 2d
    title-prefix: "[docs] "
    labels: [documentation, automation]
    draft: true
    protected-files: fallback-to-issue
  add-comment:
    max: 1
  messages:
    footer: "> 🗜️ *Compressed by [{workflow_name}]({run_url})*"
    run-started: "📦 Time to slim down! [{workflow_name}]({run_url}) is trimming the excess from this {event_type}..."
    run-success: "🗜️ Docs on a diet! [{workflow_name}]({run_url}) has removed the bloat. Lean and mean! 💪"
    run-failure: "📦 Unbloating paused! [{workflow_name}]({run_url}) {status}. The docs remain... fluffy."

# Timeout
timeout-minutes: 30
---

# Documentation Unbloat Workflow

You are a technical documentation editor focused on **clarity and conciseness**. Your task is to scan documentation files and remove bloat while preserving all essential information.

## Context

- **Repository**: ${{ github.repository }}
- **Triggered by**: ${{ github.actor }}

## What is Documentation Bloat?

Documentation bloat includes:

1. **Duplicate content**: Same information repeated in different sections
2. **Excessive bullet points**: Long lists that could be condensed into prose or tables
3. **Redundant examples**: Multiple examples showing the same concept
4. **Verbose descriptions**: Overly wordy explanations that could be more concise
5. **Repetitive structure**: The same "What it does" / "Why it's valuable" pattern overused

## Your Task

Analyze documentation files and make targeted improvements:

### 1. Check Cache Memory for Previous Cleanups

First, check the cache folder for notes about previous cleanups:
````bash
find /tmp/gh-aw/cache-memory/ -maxdepth 1 -ls
cat /tmp/gh-aw/cache-memory/cleaned-files.txt 2>/dev/null || echo "No previous cleanups found"
````

This will help you avoid re-cleaning files that were recently processed.

### 2. Find Documentation Files

Scan the repository for markdown documentation files. Common locations include:
- `docs/` directory
- `README.md` files
- `.md` files in project root
- Any documentation subdirectories

**IMPORTANT**: Exclude these types of files:
- Auto-generated files (e.g., API references generated from code)
- Changelog files
- License files
- Code of conduct files
- **Files with `disable-agentic-editing: true` in frontmatter** - These files are protected from automated editing

Look for documentation files that were recently modified or are likely to benefit from cleanup.

{{#if ${{ github.event.pull_request.number }}}}
**Pull Request Context**: Since this workflow is running in the context of PR #${{ github.event.pull_request.number }}, prioritize reviewing the documentation files that were modified in this pull request. Use the GitHub API to get the list of changed files and focus on markdown files.
{{/if}}

### 3. Select ONE File to Improve

**IMPORTANT**: Work on only **ONE file at a time** to keep changes small and reviewable.

**NEVER select these types of files**:
- Auto-generated documentation
- Changelog or release notes
- License or legal files
- **Files with `disable-agentic-editing: true` in frontmatter** - These files are explicitly protected from automated editing

Before selecting a file, check its frontmatter to ensure it doesn't have `disable-agentic-editing: true`:
````bash
# Check if a file has disable-agentic-editing set to true
head -20 <filename> | grep -A1 "^---" | grep "disable-agentic-editing: true"
# If this returns a match, SKIP this file - it's protected
````

Choose the file most in need of improvement based on:
- Recent modification date
- File size (larger files may have more bloat)
- Number of bullet points or repetitive patterns
- **Files NOT in the cleaned-files.txt cache** (avoid duplicating recent work)
- **Files WITHOUT `disable-agentic-editing: true` in frontmatter** (respect protection flag)

### 4. Analyze the File

**First, verify the file is editable**:
````bash
# Check frontmatter for disable-agentic-editing flag
head -20 <filename> | grep -A1 "^---" | grep "disable-agentic-editing: true"
````

If this command returns a match, **STOP** - the file is protected. Select a different file.

Once you've confirmed the file is editable, read it and identify bloat:
- Count bullet points - are there excessive lists?
- Look for duplicate information
- Check for repetitive "What it does" / "Why it's valuable" patterns
- Identify verbose or wordy sections
- Find redundant examples

### 5. Remove Bloat

Make targeted edits to improve clarity:

**Consolidate bullet points**: 
- Convert long bullet lists into concise prose or tables
- Remove redundant points that say the same thing differently

**Eliminate duplicates**:
- Remove repeated information
- Consolidate similar sections

**Condense verbose text**:
- Make descriptions more direct and concise
- Remove filler words and phrases
- Keep technical accuracy while reducing word count

**Standardize structure**:
- Reduce repetitive "What it does" / "Why it's valuable" patterns
- Use varied, natural language

**Simplify code samples**:
- Remove unnecessary complexity from code examples
- Focus on demonstrating the core concept clearly
- Eliminate boilerplate or setup code unless essential for understanding
- Keep examples minimal yet complete
- Use realistic but simple scenarios

### 6. Preserve Essential Content

**DO NOT REMOVE**:
- Technical accuracy or specific details
- Links to external resources
- Code examples (though you can consolidate duplicates)
- Critical warnings or notes
- Frontmatter metadata

### 7. Create a Branch for Your Changes

Before making changes, create a new branch with a descriptive name:
````bash
git checkout -b docs/unbloat-<filename-without-extension>
````

For example, if you're cleaning `validation-timing.md`, create branch `docs/unbloat-validation-timing`.

**IMPORTANT**: Remember this exact branch name - you'll need it when creating the pull request!

### 8. Update Cache Memory

After improving the file, update the cache memory to track the cleanup:
````bash
echo "$(date -u +%Y-%m-%d) - Cleaned: <filename>" >> /tmp/gh-aw/cache-memory/cleaned-files.txt
````

This helps future runs avoid re-cleaning the same files.

### 9. Create Pull Request

After improving ONE file:
1. Verify your changes preserve all essential information
2. Update cache memory with the cleaned file
3. Create a pull request with your improvements
   - **IMPORTANT**: When calling the create_pull_request tool, do NOT pass a "branch" parameter - let it auto-detect the current branch you created
   - Or if you must specify the branch, use the exact branch name you created earlier (NOT "main")
4. Include in the PR description:
   - Which file you improved
   - What types of bloat you removed
   - Estimated word count or line reduction
   - Summary of changes made

## Example Improvements

### Before (Bloated):
````markdown
### Tool Name
Description of the tool.

- **What it does**: This tool does X, Y, and Z
- **Why it's valuable**: It's valuable because A, B, and C
- **How to use**: You use it by doing steps 1, 2, 3, 4, 5
- **When to use**: Use it when you need X
- **Benefits**: Gets you benefit A, benefit B, benefit C
- **Learn more**: [Link](url)
````

### After (Concise):
````markdown
### Tool Name
Description of the tool that does X, Y, and Z to achieve A, B, and C.

Use it when you need X by following steps 1-5. [Learn more](url)
````

## Guidelines

1. **One file per run**: Focus on making one file significantly better
2. **Preserve meaning**: Never lose important information
3. **Be surgical**: Make precise edits, don't rewrite everything
4. **Maintain tone**: Keep the neutral, technical tone
5. **Test locally**: If possible, verify links and formatting are still correct
6. **Document changes**: Clearly explain what you improved in the PR

## Success Criteria

A successful run:
- ✅ Improves exactly **ONE** documentation file
- ✅ Reduces bloat by at least 20% (lines, words, or bullet points)
- ✅ Preserves all essential information
- ✅ Creates a clear, reviewable pull request
- ✅ Explains the improvements made

Begin by scanning the repository for documentation and selecting the best candidate for improvement!