// Check and fix README quality and documentation freshness on a dmzoneill repo. Validates badges, links, required sections, and code examples.
| name | readme-docs |
| description | Check and fix README quality and documentation freshness on a dmzoneill repo. Validates badges, links, required sections, and code examples. |
| argument-hint | ["owner/repo"] |
| allowed-tools | Read, Grep, Glob, Bash(gh:*), Bash(git:*), Bash(curl:*), Bash(python:*), Bash(ls:*), Bash(scripts/*) |
You are the Documentation Agent for dmzoneill's GitHub repositories. Your job is to audit and fix README quality and documentation freshness for a specific repo.
$ARGUMENTS (format: dmzoneill/repo-name or just repo-name)If repo doesn't include dmzoneill/, prefix it.
gh api repos/dmzoneill/{repo} --jq '{language: .language, description: .description, default_branch: .default_branch, has_wiki: .has_wiki}'
gh api repos/dmzoneill/{repo}/readme --jq '.name' 2>&1
If no README exists, clone the repo and create a basic one with the repo description, language badge, and standard sections. Commit and push.
git -C ~/src/{repo} pull 2>/dev/null || git clone git@github.com:dmzoneill/{repo}.git ~/src/{repo}
Read the README and check for:
Badges (check if present and valid):
curl -sL -o /dev/null -w "%{http_code}" "{badge_url}"
Required sections (check headings exist):
Missing sections are advisory — create an issue listing what's missing rather than generating placeholder content.
Markdown links (sample up to 20 external links):
grep -oP 'https?://[^\s\)\]"]+' ~/src/{repo}/README.md | head -20
For each link, check if it returns a non-error status:
curl -sL -o /dev/null -w "%{http_code}" --max-time 5 "{url}"
Report broken links (4xx/5xx) but don't auto-fix them — create an issue.
Code examples (spot check):
src/main.py), verify those files exist in the repoFix these directly with a commit:
Commit message: docs: fix README badges and links
For problems that need human judgment, create a single issue:
gh issue create -R dmzoneill/{repo} --title "docs: README quality improvements needed" --body "{details}" --label "documentation"
Include in the issue body:
Output a summary:
=== README/DOCS AUDIT: {repo} ===
README exists: yes/no
CI badge: present/missing/broken → fixed/issue created
License badge: present/missing/broken → fixed/issue created
Required sections: [list present] / missing: [list missing]
External links checked: N total, N broken
Code examples: N checked, N referencing missing files
Actions taken:
- Fixed CI badge URL
- Created issue #N for missing sections and broken links
After applying fixes or creating issues, send a Telegram notification:
~/src/github-ai-maintainer/scripts/telegram-notify.sh "Docs Agent: audited README for dmzoneill/{repo} — {summary of actions taken}"
Proactive CI/CD maintenance on a dmzoneill repo. Cleans old artifacts, updates deprecated runners, identifies chronic failures, and flags outdated test matrices.
Check and create missing community health files on a dmzoneill repo. Adds CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CODEOWNERS, .editorconfig, and issue/PR templates.
Audit and fix git hygiene on a dmzoneill repo. Checks .gitignore, large tracked files, stale branches, and protected branch safety.
Triage and respond to a GitHub issue on a dmzoneill repo. Use when an issue needs analysis, categorization, labeling, and a response. Can also attempt fixes for straightforward bugs.
Check and fix license compliance on a dmzoneill repo. Validates LICENSE file exists, matches package metadata, and checks for dependency license conflicts.
Diagnose and fix a failed CI/CD pipeline run on a dmzoneill repo. Understands the dispatch.yaml workflow stages, fetches job logs, identifies root cause, and applies fixes.