Skip to content

existential-birds/beagle / plugins/beagle-docs/skills/review-ai-writing

review-ai-writing

Verified

Detect AI-generated writing patterns in developer text — docs, docstrings, commit messages, PR descriptions, and code comments. Use when reviewing any text artifact for authenticity and clarity, or when the user mentions ai writing, ai-generated or robotic writing, text that sounds like AI or ChatGPT, or writing quality. Builds on the docs-style core writing principles.

references/communication-patterns.md

View on GitHub
# Communication Patterns

Detection criteria for conversational AI artifacts that leak into developer-facing text: documentation, commit messages, PR descriptions, and code comments.

## 1. Chat Leaks

### What to Look For

Conversational phrases from AI chat sessions copy-pasted into committed text. These read as one side of a dialogue rather than authored documentation.

### Detection Patterns

```markdown
# BAD - Chat openers leaked into docs/PRs/comments
Certainly! Here's how to configure the database connection.
Great question! The middleware stack processes requests in order.
I'd be happy to help explain the authentication flow.

# GOOD
Configure the database connection with the following environment variables.
The middleware stack processes requests in order.
```

```python
# BAD - Chat phrasing in code comments or commit messages
# Here's the implementation for the retry logic
# Let me explain what this does
# As requested, this handles the edge case
# Sure thing! This validates the token format

# GOOD
# Retry with exponential backoff, max 3 attempts
# Handles empty input by returning early
```

### fix_safety: Safe

Removing chat preambles does not change technical meaning.

---

## 2. Cutoff Disclaimers

### What to Look For

Training cutoff disclaimers or knowledge-limitation hedges in docs or comments. These expose AI-generated origin and erode reader confidence.

### Detection Patterns

```markdown
# BAD
As of my last update, the API supports cursor-based pagination.
Based on current knowledge, PostgreSQL 16 introduced merge joins.
I cannot guarantee this behavior will remain consistent.

# GOOD
The API supports cursor-based pagination (v2.3+).
PostgreSQL 16 introduced merge joins (see release notes).
This behavior may change; pin your dependency version.
```

### fix_safety: Safe

Replace disclaimers with versioned references or remove entirely.

---

## 3. Sycophantic Tone

### What to Look For

Excessive praise or enthusiasm in code review comments, PR descriptions, and documentation that reads as flattery rather than technical assessment.

### Detection Patterns

```markdown
# BAD
Excellent approach! The factory pattern here is wonderful.
Great implementation! This is a really elegant solution.
This is a brilliant way to handle the race condition!

# GOOD
The factory pattern decouples instantiation from the handler logic.
The mutex prevents the race condition identified in #247.
Consider a read-write lock since reads outnumber writes 10:1.
```

```python
# BAD
# This is a really nice pattern for dependency injection

# GOOD
# Dependency injection via constructor allows test doubles
```

### fix_safety: Safe

Replace praise with neutral technical descriptions. No semantic meaning is lost.

---

## 4. Apologetic Errors

### What to Look For

Over-apologizing in error messages, log output, or documentation. Error handling should be informative and actionable, not socially polite.

### Detection Patterns

```python
# BAD
raise ValueError("I apologize for any inconvenience, but the input is invalid.")
logger.error("Sorry for the confusion, but the config could not be loaded.")
print("Unfortunately, we regret to inform you that the connection failed.")

# GOOD
raise ValueError(f"Invalid input: expected ISO 8601 date, got {value!r}")
logger.error("Failed to load config from %s: %s", config_path, err)
print(f"Connection failed: {host}:{port} (timeout after {timeout}s)")
```

```markdown
# BAD
We're sorry, but this feature is not available in the free tier.

# GOOD
This feature requires a paid plan. See pricing for details.
```

### fix_safety: Needs review

Error message rewording must preserve all diagnostic information (codes, paths, values). Verify the replacement includes the same actionable details.

---

## Review Questions

1. Does the text read like one side of a conversation or like authored documentation?
2. Are there hedges or disclaimers that reference AI knowledge limitations?
3. Does review feedback contain praise without specific technical substance?
4. Do error messages apologize instead of providing actionable remediation steps?
5. Would the text make sense if the reader had no context of an AI interaction?
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall