Add agentic workflow unbloat-docs#230
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces an "unbloat-docs" agentic workflow that is designed to automatically review documentation files and reduce verbosity while preserving meaning. It uses the gh-aw (GitHub Agentic Workflow) framework to run a Copilot CLI agent daily and on /unbloat slash commands in PR comments. The workflow scans documentation, picks one file per run, trims bloat, and opens a draft PR with before/after screenshots.
Changes:
- New agentic workflow definition (
.github/workflows/unbloat-docs.md) + compiled workflow (.github/workflows/unbloat-docs.lock.yml) that automates documentation cleanup using Copilot CLI - New shared workflow imports:
shared/mood.md(placeholder),shared/reporting.md(report formatting guide), andshared/docs-server-lifecycle.md(Astro Starlight server startup/teardown instructions)
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/unbloat-docs.md |
Source workflow definition / AI agent prompt; contains build steps and doc-path references ported from github/gh-aw project |
.github/workflows/unbloat-docs.lock.yml |
Auto-compiled GitHub Actions YAML; inherits all issues from the .md source |
.github/workflows/shared/docs-server-lifecycle.md |
Shared server lifecycle instructions for Astro Starlight preview server; contains gh-aw-specific URL path |
.github/workflows/shared/reporting.md |
Shared report formatting guidelines for agentic workflows |
.github/workflows/shared/mood.md |
Placeholder shared file imported by the workflow |
Comments suppressed due to low confidence (2)
.github/workflows/unbloat-docs.md:183
- The exclusion list references
docs/src/content/docs/reference/frontmatter-full.md— an auto-generated file fromscripts/generate-schema-docs.js— but neither this file path nor the script exist in this repository. This instruction in the prompt creates a false constraint that doesn't apply here, andscripts/generate-schema-docs.jsis not part of this codebase. These exclusion rules should be removed or replaced with exclusions applicable to this repository's actual documentation structure.
**NEVER select these directories or code-generated files**:
- `docs/src/content/docs/blog/` - Blog posts have a different writing style and should not be unbloated
- `docs/src/content/docs/reference/frontmatter-full.md` - Auto-generated from JSON schema
- **Files with `disable-agentic-editing: true` in frontmatter** - These files are explicitly protected from automated editing
.github/workflows/unbloat-docs.md:293
- The screenshot step instructs the agent to map a markdown file path to a URL using the Astro Starlight convention: e.g.,
docs/src/content/docs/guides/getting-started.md→http://localhost:4321/gh-aw/guides/getting-started/. This URL structure is specific to thegh-awproject and does not apply to this repository, which has no Astro Starlight documentation site. Since there is no rendered documentation website to screenshot, this entire step will not produce any useful screenshots and will cause the agent to waste significant time trying to start a preview server that cannot run.
After making changes to a documentation file, take screenshots of the rendered page in the Astro Starlight website:
#### Build and Start Documentation Server
Follow the shared **Documentation Server Lifecycle Management** instructions:
1. Start the preview server (section "Starting the Documentation Preview Server")
2. Wait for readiness (section "Waiting for Server Readiness")
3. Optionally verify accessibility (section "Verifying Server Accessibility")
#### Take Screenshots with Playwright
For the modified documentation file(s):
1. Determine the URL path for the modified file (e.g., if you modified `docs/src/content/docs/guides/getting-started.md`, the URL would be `http://localhost:4321/gh-aw/guides/getting-started/`)
2. Use Playwright to navigate to the documentation page URL
3. Wait for the page to fully load (including all CSS, fonts, and images)
4. Take a full-page HD screenshot of the documentation page (1920x1080 viewport is configured)
5. The screenshot will be saved in `/tmp/gh-aw/mcp-logs/playwright/` by Playwright (e.g., `/tmp/gh-aw/mcp-logs/playwright/getting-started.png`)
| - "find docs/src/content/docs -name '*.md'" | ||
| - "wc -l *" | ||
| - "grep -n *" | ||
| - "git" | ||
| - "cat *" | ||
| - "head *" | ||
| - "tail *" | ||
| - "cd *" | ||
| - "node *" | ||
| - "npm *" | ||
| - "curl *" | ||
| - "ps *" | ||
| - "kill *" | ||
| - "sleep *" | ||
| - "echo *" | ||
| - "mkdir *" | ||
| - "cp *" | ||
| - "mv *" | ||
|
|
||
| # Safe outputs configuration | ||
| safe-outputs: | ||
| create-pull-request: | ||
| expires: 2d | ||
| title-prefix: "[docs] " | ||
| labels: [documentation, automation] | ||
| reviewers: [copilot] | ||
| draft: true | ||
| auto-merge: true | ||
| fallback-as-issue: false | ||
| add-comment: | ||
| max: 1 | ||
| upload-asset: | ||
| 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 (increased from 12min after timeout issues; aligns with similar doc workflows) | ||
| timeout-minutes: 30 | ||
|
|
||
| # Build steps for documentation | ||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v6 | ||
| with: | ||
| persist-credentials: false | ||
|
|
||
| - name: Setup Node.js | ||
| uses: actions/setup-node@v6 | ||
| with: | ||
| node-version: '24' | ||
| cache: 'npm' | ||
| cache-dependency-path: 'docs/package-lock.json' | ||
|
|
||
| - name: Install dependencies | ||
| working-directory: ./docs | ||
| run: npm ci | ||
|
|
||
| - name: Build documentation | ||
| working-directory: ./docs | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
| run: npm run build | ||
| source: github/gh-aw/.github/workflows/unbloat-docs.md@852cb06ad52958b402ed982b69957ffc57ca0619 | ||
| --- | ||
|
|
||
| # 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 in the `docs/` directory 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 `docs/` directory for markdown files, excluding code-generated files and blog posts: | ||
| ```bash | ||
| find docs/src/content/docs -path 'docs/src/content/docs/blog' -prune -o -name '*.md' -type f ! -name 'frontmatter-full.md' -print |
There was a problem hiding this comment.
The workflow's AI prompt instructs the agent to find documentation files using find docs/src/content/docs -name '*.md', but this repository's documentation consists of plain Markdown files directly in docs/ (e.g., docs/getting-started.md, docs/cli-reference.md). There is no docs/src/content/docs directory. This find command will return an empty result, causing the agent to be unable to locate any documentation files to improve.
The agent prompt should be updated to use the actual documentation path, e.g., find docs -name '*.md', and all references to docs/src/content/docs/ throughout the prompt should be updated to reflect the actual structure of this repository.
This issue also appears in the following locations of the same file:
- line 180
- line 276
| - name: Setup Node.js | ||
| uses: actions/setup-node@v6 | ||
| with: | ||
| node-version: '24' | ||
| cache: 'npm' | ||
| cache-dependency-path: 'docs/package-lock.json' | ||
|
|
||
| - name: Install dependencies | ||
| working-directory: ./docs | ||
| run: npm ci | ||
|
|
||
| - name: Build documentation | ||
| working-directory: ./docs | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
| run: npm run build |
There was a problem hiding this comment.
The steps section includes three steps that require an npm/Node.js project in the docs/ directory: Setup Node.js, npm ci, and npm run build. However, this repository's docs/ directory contains only plain Markdown files — there is no package.json, package-lock.json, or any npm-based build system. These steps will fail every time the workflow runs.
The build steps should be removed entirely, or replaced with steps appropriate to this repository (e.g., no build step is needed, since the docs are plain Markdown). The cache-dependency-path: 'docs/package-lock.json' cache key and node-version: '24' setup are also unnecessary.
| - name: Setup Node.js | |
| uses: actions/setup-node@v6 | |
| with: | |
| node-version: '24' | |
| cache: 'npm' | |
| cache-dependency-path: 'docs/package-lock.json' | |
| - name: Install dependencies | |
| working-directory: ./docs | |
| run: npm ci | |
| - name: Build documentation | |
| working-directory: ./docs | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: npm run build |
| curl -s http://localhost:4321/gh-aw/ | head -20 | ||
| ``` | ||
|
|
||
| ## Stopping the Documentation Server | ||
|
|
||
| After you're done using the server, clean up the process: | ||
|
|
||
| ```bash | ||
| kill $(cat /tmp/server.pid) 2>/dev/null || true | ||
| rm -f /tmp/server.pid /tmp/preview.log | ||
| ``` | ||
|
|
||
| This will: | ||
| - Kill the server process using the saved PID | ||
| - Remove temporary files | ||
| - Ignore errors if the process already stopped | ||
|
|
||
| ## Usage Notes | ||
|
|
||
| - The server runs on `http://localhost:4321` | ||
| - Documentation is accessible at `http://localhost:4321/gh-aw/` | ||
| - Always clean up the server when done to avoid orphan processes | ||
| - If the server fails to start, check `/tmp/preview.log` for errors |
There was a problem hiding this comment.
The shared docs-server-lifecycle.md file instructs the agent to verify the documentation server by accessing http://localhost:4321/gh-aw/, which is the URL path specific to the github/gh-aw project this workflow was copied from. In this repository, there is no Astro Starlight site and no /gh-aw/ path. The npm run preview command will also fail since there is no npm project in docs/.
If screenshot capture is to be retained, the server URL and the file-to-URL mapping logic in step 9 (e.g., docs/src/content/docs/guides/getting-started.md → http://localhost:4321/gh-aw/guides/getting-started/) need to be updated to match this repository's actual documentation structure. If there is no web-rendered documentation site, the screenshot step and the entire docs-server-lifecycle.md shared file should be reconsidered.
| @@ -0,0 +1 @@ | |||
| . No newline at end of file | |||
There was a problem hiding this comment.
The mood.md shared file (imported by this workflow) contains only a single . character and provides no actual instructions or content to the AI agent. This appears to be a placeholder left over from a template. It should either contain meaningful content describing the desired agent tone/mood, or be removed from the imports list to avoid importing an empty/meaningless file.
| . | |
| # AI Agent Mood and Tone | |
| The AI assistant should follow these mood and style guidelines when responding: | |
| - **Tone:** Warm, respectful, and professional. Be friendly but not overly casual. | |
| - **Directness:** Get to the point quickly. Avoid filler text and unnecessary pleasantries. | |
| - **Honesty:** Be transparent about limitations or uncertainty. Do not invent facts. | |
| - **Verbosity:** Default to concise, information-dense answers. Expand with more detail only when explicitly requested. | |
| - **Formatting:** Use plain text or simple Markdown appropriate to the context. Do not use emojis unless explicitly requested. | |
| - **Clarity:** Prefer simple, straightforward language. Explain acronyms or jargon when they may be unfamiliar. | |
| - **Helpfulness:** Focus on practical, actionable information tailored to the user’s question. |
Add agentic workflow unbloat-docs