From dd8f098c339c9d6e7d3e23004527ca15196e3839 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 18 Feb 2026 02:45:40 +0000 Subject: [PATCH] Add Documentation Unbloat workflow Add high-value workflow from Peli's Agent Factory to automatically simplify documentation by removing verbosity while maintaining clarity. This workflow achieved an 85% merge rate (88 merged out of 103 PRs) in the gh-aw repository, demonstrating strong practical value. Key features: - Removes duplicate content and excessive bullet points - Consolidates redundant examples and verbose descriptions - Preserves all essential information and technical accuracy - Works one file at a time for easy review - Tracks cleaned files in cache memory to avoid duplication - Supports slash command /unbloat in PR comments Source: https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/unbloat-docs.md Documented merge rate: 88/103 PRs merged (85%) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 1 + docs/unbloat-docs.md | 178 ++++++++++++++++++++++++ workflows/unbloat-docs.md | 286 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 465 insertions(+) create mode 100644 docs/unbloat-docs.md create mode 100644 workflows/unbloat-docs.md diff --git a/README.md b/README.md index 51ef548..cf0a4fb 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ You can use the "/plan" agent to turn the reports into actionable issues which c - [📖 Daily Documentation Updater](docs/daily-doc-updater.md) - Automatically update documentation based on recent code changes and merged PRs - [📖 Glossary Maintainer](docs/glossary-maintainer.md) - Automatically maintain project glossary based on codebase changes - [🔗 Link Checker](docs/link-checker.md) - Daily automated link checker that finds and fixes broken links in documentation +- [🗜️ Documentation Unbloat](docs/unbloat-docs.md) - Automatically simplify documentation by reducing verbosity while maintaining clarity - [✨ Code Simplifier](docs/code-simplifier.md) - Automatically simplify recently modified code for improved clarity and maintainability - [🔍 Duplicate Code Detector](docs/duplicate-code-detector.md) - Identify duplicate code patterns and suggest refactoring opportunities - [⚡ Daily Progress](docs/daily-progress.md) - Automated daily feature development following a structured roadmap diff --git a/docs/unbloat-docs.md b/docs/unbloat-docs.md new file mode 100644 index 0000000..8704c65 --- /dev/null +++ b/docs/unbloat-docs.md @@ -0,0 +1,178 @@ +# 🗜️ Documentation Unbloat + +> For an overview of all available workflows, see the [main README](../README.md). + +The [Documentation Unbloat workflow](../workflows/unbloat-docs.md?plain=1) automatically reviews and simplifies documentation by removing verbosity while maintaining clarity and completeness. + +## Installation + +````bash +# Install the 'gh aw' extension +gh extension install github/gh-aw + +# Add the workflow to your repository +gh aw add-wizard githubnext/agentics/unbloat-docs +```` + +This walks you through adding the workflow to your repository. + +You can start a run of this workflow immediately by running: + +````bash +gh aw run unbloat-docs +```` + +Or trigger it in a pull request comment with: + +```` +/unbloat +```` + +## What It Does + +The Documentation Unbloat workflow runs daily and can be triggered via `/unbloat` command in PR comments. It: + +1. **Scans Documentation** - Reviews markdown files in the repository for bloat +2. **Identifies Verbosity** - Finds duplicate content, excessive bullet points, redundant examples, and verbose descriptions +3. **Removes Bloat** - Makes targeted edits to improve clarity and conciseness +4. **Preserves Accuracy** - Maintains all essential information, links, and technical details +5. **Creates Pull Requests** - Proposes documentation improvements one file at a time for easy review + +## How It Works + +### What Gets Removed + +The workflow identifies and removes: + +- **Duplicate content**: Same information repeated in different sections +- **Excessive bullet points**: Long lists that could be condensed into prose or tables +- **Redundant examples**: Multiple examples showing the same concept +- **Verbose descriptions**: Overly wordy explanations +- **Repetitive structure**: Overused "What it does" / "Why it's valuable" patterns + +### What Gets Preserved + +The workflow never removes: + +- Technical accuracy or specific details +- Links to external resources +- Code examples (though duplicates may be consolidated) +- Critical warnings or notes +- Frontmatter metadata + +### One File at a Time + +The workflow improves exactly **one file per run** to keep changes small, focused, and easily reviewable. This incremental approach makes it easier to: + +- Review and approve changes quickly +- Understand what was modified +- Revert changes if needed +- Track improvements over time + +### Protected Files + +Files can be protected from automatic editing by adding `disable-agentic-editing: true` to their frontmatter. The workflow automatically skips: + +- Auto-generated documentation +- Changelog or release notes +- License or legal files +- Files marked with `disable-agentic-editing: true` + +### Memory and Tracking + +The workflow uses cache memory to track previously cleaned files, avoiding duplicate work and ensuring efficient coverage of documentation over time. + +## Trigger Options + +### Daily Schedule + +Runs automatically once per day at a scattered execution time to continuously improve documentation. + +### Slash Command + +Trigger on-demand in pull request comments: + +```` +/unbloat +```` + +This analyzes documentation files modified in the PR and proposes improvements. + +### Manual Trigger + +Run manually via GitHub Actions UI or CLI: + +````bash +gh aw run unbloat-docs +```` + +## 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 + +## Benefits + +**Improved Readability**: Concise documentation is easier to scan and understand, helping users find information faster. + +**Reduced Maintenance**: Shorter documentation is easier to keep up-to-date as the project evolves. + +**Better User Experience**: Clear, focused content reduces cognitive load and improves comprehension. + +**Continuous Improvement**: Daily runs ensure documentation stays lean as new content is added. + +## 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) +```` + +## Customization + +You can customize the workflow by editing the [`unbloat-docs.md`](../workflows/unbloat-docs.md) file: + +- Adjust which directories or file patterns to scan +- Modify the success criteria (e.g., minimum bloat reduction percentage) +- Change the PR labeling and auto-merge behavior +- Add project-specific exclusion patterns +- Customize the tone or style guidance + +After making changes, recompile the workflow: + +````bash +gh aw compile unbloat-docs +```` + +## Complementary Workflows + +This workflow pairs well with: + +- [Daily Documentation Updater](daily-doc-updater.md) - Ensures accuracy and completeness +- [Glossary Maintainer](glossary-maintainer.md) - Keeps terminology consistent +- [Link Checker](link-checker.md) - Validates all documentation links + +Together, these workflows maintain comprehensive, accurate, and readable documentation. diff --git a/workflows/unbloat-docs.md b/workflows/unbloat-docs.md new file mode 100644 index 0000000..9dc8daa --- /dev/null +++ b/workflows/unbloat-docs.md @@ -0,0 +1,286 @@ +--- +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 + +strict: true + +# AI engine configuration +engine: + id: claude + max-turns: 90 + +# 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 + fallback-as-issue: false + 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 | 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 | 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- +```` + +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: " >> /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!