Help us improve
Share bugs, ideas, or general feedback.
From beagle-docs
Detects AI-generated writing patterns in docs, docstrings, commit messages, PR descriptions, and code comments. Scans changed files or full codebase by category for authenticity and clarity.
npx claudepluginhub existential-birds/beagle --plugin beagle-docsHow this skill is triggered — by the user, by Claude, or both
Slash command
/beagle-docs:review-ai-writingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Detect AI-generated writing patterns across developer text artifacts using parallel subagents.
Humanizes AI-generated developer docs and code comments by auto-applying safe fixes from review-ai-writing results. Includes git stash safety, dry-run preview, full scans, and category filtering.
Humanizes AI-generated text in project files, READMEs, docs, and blogs by detecting and fixing 24 documented AI writing patterns. Interactive workflow with input selection, content type, and intensity options.
Avoids AI writing tropes like em dashes, delve, and promotional language when writing or editing PR descriptions, commit messages, documentation, Slack, or de-AI'ing text.
Share bugs, ideas, or general feedback.
Detect AI-generated writing patterns across developer text artifacts using parallel subagents.
/beagle-docs:review-ai-writing [--all] [--category <name>] [path]
Flags:
--all - Scan entire codebase (default: changed files from main)--category <name> - Only check specific category: content|vocabulary|formatting|communication|filler|code_docsExtract flags from $ARGUMENTS:
--all - Full codebase scan--category <name> - Filter to specific categoryLoad required skills:
Skill(skill: "beagle-docs:review-ai-writing")
Skill(skill: "beagle-core:review-verification-protocol")
# Default: changed files from main
git diff --name-only $(git merge-base HEAD main)..HEAD
# If --all flag: scan all text artifacts
find . -type f \( -name "*.md" -o -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.swift" -o -name "*.kt" -o -name "*.ex" -o -name "*.exs" \) ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/vendor/*" ! -path "*/__pycache__/*" ! -path "*/dist/*" ! -path "*/build/*"
If no files found, exit with: "No files to scan. Check your branch has changes or use --all."
# Check if llm-artifacts review exists to avoid double-flagging
if [ -f .beagle/llm-artifacts-review.json ]; then
echo "Found existing llm-artifacts review — will skip overlapping findings"
fi
Parse existing findings from .beagle/llm-artifacts-review.json if present. When consolidating, skip any finding where both the file:line and pattern type match an existing llm-artifacts finding (specifically verbose_comment and over_documentation types).
Partition files into three groups:
| Group | File Types | Patterns to Check |
|---|---|---|
| Prose | *.md | All 6 categories |
| Code Docs | *.py, *.ts, *.tsx, *.js, *.jsx, *.go, *.rs, *.java, *.rb, *.swift, *.kt, *.ex, *.exs | vocabulary, communication, filler, code_docs |
| Git | Commit messages, PR descriptions | content, vocabulary, communication, filler |
For Git artifacts, collect recent commits:
# Commits on current branch not in main
git log --format="%H %s" $(git merge-base HEAD main)..HEAD
If total items >= 4, spawn up to 3 subagents via Task tool. If --category is set, spawn a single agent for that category only.
Scope: Markdown files only Check: All 6 pattern categories Instructions:
beagle-docs:review-ai-writing skillScope: Source code files Check: vocabulary, communication, filler, code_docs categories Instructions:
beagle-docs:review-ai-writing skillScope: Commit messages and PR descriptions Check: content, vocabulary, communication, filler categories Instructions:
beagle-docs:review-ai-writing skillgh pr view --json bodygit:commit:<sha> with line 0, git:pr:<number> with line 0Wait for all subagents to complete, then:
.beagle/llm-artifacts-review.jsonCreate .beagle directory if it doesn't exist:
mkdir -p .beagle
Write findings to .beagle/ai-writing-review.json:
{
"version": "1.0.0",
"created_at": "2025-01-15T10:30:00Z",
"git_head": "abc1234",
"scope": "changed",
"files_scanned": 12,
"commits_scanned": 5,
"findings": [
{
"id": 1,
"category": "vocabulary",
"type": "ai_vocabulary_high",
"file": "README.md",
"line": 15,
"original_text": "This library leverages cutting-edge algorithms to facilitate seamless data processing.",
"description": "High-signal AI vocabulary: leverage, cutting-edge, facilitate, seamless",
"suggestion": "This library uses streaming algorithms for fast data processing.",
"risk": "Low",
"fix_safety": "Safe",
"fix_action": "rewrite"
},
{
"id": 2,
"category": "code_docs",
"type": "tautological_docstring",
"file": "src/auth.py",
"line": 42,
"original_text": "\"\"\"Get the user by ID.\"\"\"",
"description": "Docstring restates function name get_user_by_id without adding value",
"suggestion": "\"\"\"Raises UserNotFound if ID doesn't exist.\"\"\"",
"risk": "Medium",
"fix_safety": "Needs review",
"fix_action": "rewrite"
},
{
"id": 3,
"category": "communication",
"type": "chat_leak",
"file": "git:commit:abc1234",
"line": 0,
"original_text": "Certainly! Here's the updated authentication flow",
"description": "Chat leak in commit message: starts with 'Certainly! Here's'",
"suggestion": "Update authentication flow",
"risk": "Low",
"fix_safety": "Safe",
"fix_action": "rewrite"
}
],
"summary": {
"total": 3,
"by_category": {
"vocabulary": 1,
"code_docs": 1,
"communication": 1
},
"by_risk": {
"Low": 2,
"Medium": 1
},
"by_fix_safety": {
"Safe": 2,
"Needs review": 1
}
}
}
## AI Writing Review
**Scope:** Changed files from main
**Files scanned:** 12 | **Commits scanned:** 5
### Findings by Category
#### Vocabulary (1 issue)
1. [README.md:15] **AI vocabulary** (Low, Safe)
- High-signal AI vocabulary: leverage, cutting-edge, facilitate, seamless
- Suggestion: Rewrite with simple words
#### Code Docs (1 issue)
2. [src/auth.py:42] **Tautological docstring** (Medium, Needs review)
- Docstring restates function name without adding value
- Suggestion: Add meaningful information or delete
#### Communication (1 issue)
3. [git:commit:abc1234:0] **Chat leak** (Low, Safe)
- Commit message starts with "Certainly! Here's"
- Suggestion: Rewrite as imperative commit message
### Summary Table
| Category | Safe | Needs Review | Total |
|----------|------|--------------|-------|
| Vocabulary | 1 | 0 | 1 |
| Code Docs | 0 | 1 | 1 |
| Communication | 1 | 0 | 1 |
| **Total** | **2** | **1** | **3** |
### Next Steps
- Run `/beagle-docs:humanize` to apply fixes
- Run `/beagle-docs:humanize --dry-run` to preview changes first
- Review the JSON report at `.beagle/ai-writing-review.json`
Before completing, verify:
.beagle/ai-writing-review.json exists and is parseablegit_head field is non-empty.beagle/llm-artifacts-review.json if it exists# Verify JSON is valid
python3 -c "import json; json.load(open('.beagle/ai-writing-review.json'))" 2>/dev/null && echo "Valid JSON" || echo "Invalid JSON"
If any verification fails, report the error and do not proceed.
[FILE:LINE] ISSUE_TITLE
- Category: content | vocabulary | formatting | communication | filler | code_docs
- Type: specific_pattern_name
- Original: "the problematic text"
- Suggestion: "the improved text" or "delete"
- Risk: Low | Medium
- Fix Safety: Safe | Needs review
beagle-docs:review-ai-writing and beagle-core:review-verification-protocol firstTask tool for parallel subagents when >= 4 items to scan.beagle/llm-artifacts-review.json.beagle directory if neededDetect patterns characteristic of AI-generated text in developer artifacts. These patterns reduce trust, add noise, and obscure meaning.
| Category | Reference | Key Signals |
|---|---|---|
| Content | references/content-patterns.md | Promotional language, vague authority, formulaic structure, synthetic openers |
| Vocabulary | references/vocabulary-patterns.md | AI word tiers, copula avoidance, rhetorical devices, synonym cycling, commit inflation |
| Formatting | references/formatting-patterns.md | Boldface overuse, emoji decoration, heading restatement |
| Communication | references/communication-patterns.md | Chat leaks, cutoff disclaimers, sycophantic tone, apologetic errors |
| Filler | references/filler-patterns.md | Filler phrases, excessive hedging, generic conclusions |
| Code Docs | references/code-docs-patterns.md | Tautological docstrings, narrating obvious code, "This noun verbs", exhaustive enumeration |
Scan these artifact types:
| Artifact | File Patterns | Notes |
|---|---|---|
| Markdown docs | *.md | READMEs, guides, changelogs |
| Docstrings | *.py, *.ts, *.js, *.go, *.swift, *.rs, *.java, *.kt, *.rb, *.ex | Language-specific docstring formats |
| Code comments | Same as docstrings | Inline and block comments |
| Commit messages | git log output | Use synthetic path git:commit:<sha> |
| PR descriptions | GitHub PR body | Use synthetic path git:pr:<number> |
These patterns are strong indicators of AI-generated text:
Flag when 2+ appear together or pattern is repeated:
Mention but don't flag as issues:
Do NOT flag these as AI-generated:
| Pattern | Why It's Valid |
|---|---|
| "Ensure" in security docs | Standard term for security requirements |
| "Comprehensive" in test coverage discussion | Accurate technical descriptor |
| Formal tone in API reference docs | Expected register for reference material |
| "Leverage" in financial/business domain code | Domain-specific meaning, not AI filler |
| Bold formatting in CLI help text | Standard convention |
| Structured intro paragraphs in RFCs/ADRs | Expected format for these document types |
"This module provides" in Python __init__.py | Idiomatic Python module docstring |
| Rhetorical questions in blog posts | Appropriate for informal content |
beagle-core:review-verification-protocolBefore reporting any finding:
beagle-core:llm-artifacts-detectionCode-level patterns (tautological docstrings, obvious comments) overlap with llm-artifacts-detection's style criteria. When both skills are loaded:
review-ai-writing focuses on writing style (how it reads)llm-artifacts-detection focuses on code artifacts (whether it should exist at all).beagle/llm-artifacts-review.json exists, skip findings already captured thereReport each finding as:
[FILE:LINE] ISSUE_TITLE
- Category: content | vocabulary | formatting | communication | filler | code_docs
- Type: specific_pattern_name
- Original: "the problematic text"
- Suggestion: "the improved text" or "delete"
- Risk: Low | Medium
- Fix Safety: Safe | Needs review