Skip to content

Tighten docs-review skill severity to reduce review churn #680

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danbarr merged 1 commit into from
Apr 8, 2026
Merged

Tighten docs-review skill severity to reduce review churn #680

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions .claude/skills/docs-review/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,14 +141,12 @@ Structure your review as:
| Issue | Recommendation |
| ----- | -------------- |
| ... | ... |

## Inline Suggestions

[Note any specific line-level edits to suggest]
```

## Severity Guidelines

Before including any finding, apply the **independent reviewer test**: would a different competent tech writer independently flag the same issue? If two phrasings are equally clear and correct, don't flag one as better. The goal is a stable review - running the skill twice on the same document should produce essentially the same findings.

**Primary issues** (address before merge):

- Accuracy: documented behavior contradicts CLI reference, API spec, or upstream source
Expand All @@ -159,17 +157,20 @@ Structure your review as:
- Structure problems that harm navigation
- Missing explanations for confusing design decisions
- Significantly buried or redundant content
- Grammatical errors (sentence fragments, missing articles, subject-verb disagreement)

**Secondary issues** (nice to have):
**Secondary issues** (worth fixing but not blocking):

- Minor wording improvements
- Small redundancies within a document
- Style guide adherence
- Wording that is genuinely confusing, ambiguous, or likely to mislead - not merely "could be rephrased"
- Style guide violations (terminology, capitalization, voice)
- Missing context that forces the reader to leave the page to understand a step

**Skip entirely**:

- Formatting/syntax (let linters handle this)
- Subjective preferences without clear benefit
- Style-neutral alternatives where the current version is clear (e.g., "this sentence could be split in two," "this transition could be cut," imperative vs. declarative phrasing)
- Thin but useful sections - a short section that orients the reader is better than no section; don't flag brevity alone
- Cosmetic rewording that doesn't change clarity or correctness

## Review Checklist

Expand Down