Add documentation unbloat workflow for automated cleanup

[Copilot]

This PR adds a new agentic workflow that automatically scans and cleans up documentation bloat in the docs/ directory.

What This Workflow Does

The unbloat-docs workflow uses Claude to identify and remove documentation bloat while preserving all essential information. It focuses on:

• 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 that could be more concise
• Repetitive structure: The same "What it does" / "Why it's valuable" pattern overused
• Complex code samples: Unnecessary complexity in code examples that can be simplified

Workflow Behavior

The workflow is designed to make small, surgical changes:

1. Scans markdown files in the docs/ directory
2. PR-aware: When running in a PR context, prioritizes reviewing documentation files modified in that pull request
3. Selects ONE file at a time for improvement
4. Analyzes the file for bloat patterns
5. Makes targeted edits to improve clarity
6. Creates a draft pull request with the improvements for review

Triggers

• Daily: Runs at 2am PST (10am UTC) via cron schedule
• On-demand: Use /unbloat command in PR comments
• Manual: Via workflow_dispatch for testing

Example Improvement

Before (Bloated):

### 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
- **Benefits**: Gets you benefit A, benefit B, benefit C

After (Concise):

### 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.

Safety Features

• Uses safe-outputs for secure PR creation
• Creates draft PRs for manual review before merging
• Read-only permissions for main job
• Network access restricted to defaults and GitHub
• 15-minute timeout to prevent runaway costs
• Strict mode enabled

Files Changed

• .github/workflows/unbloat-docs.md - Workflow definition
• .github/workflows/unbloat-docs.lock.yml - Compiled GitHub Actions YAML

The workflow is ready to help maintain clean, concise documentation automatically! 📝✨

Original prompt

Create an agentic workflow that unbloats documentation.

The workflow scans documentation updates (markdown under docs) and removes duplicate samples, overly verbose bullet point list, etc...

It works on 1 file at a time to keep changes small.

Creates a pull request with changes and runs daily at 2am pst, or using /unbloat command on pull request comments.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

@copilot draft true

[Copilot]

Changed to draft: true in commit 20e2ecb

[pelikhan]

@copilot update prompt to look at the list of modified docs file in the current branch, if in a PR. Use template region to conditionally insert the text

[Copilot]

Added conditional template region that detects PR context and prioritizes reviewing modified docs files in the current PR. The section uses {{#if ${{ github.event.pull_request.number }}}} to conditionally show instructions for getting changed files from the PR. See commit 20e2ecb

[pelikhan]

@copilot add section on simplifying code sample:

remove complexity from samples unless necessary.

[Copilot]

Added "Simplify code samples" section with guidance on removing unnecessary complexity from examples. See commit 20e2ecb

[github-actions]

Agentic Changeset Generator triggered by this pull request