@cleocode/skills 2026.5.84 → 2026.5.86

package/skills/ct-docs-review/references/pr-review-mode.md

@@ -0,0 +1,270 @@
+# PR Review Mode
+
+When the GitHub MCP tools are available, ct-docs-review uses the
+pending-review workflow to post all findings as one cohesive GitHub
+review. This reference codifies the workflow, the comment format,
+and the integration with `gh` CLI for the cases where MCP tools are
+not available.
+
+## Mode Detection
+
+The mode is determined by tool availability:
+
+| Available | Mode | Output target |
+|-----------|------|---------------|
+| `mcp__github__create_pending_pull_request_review` | PR mode | GitHub PR review |
+| Not available | Local mode | Conversation / file |
+
+The skill MUST check tool availability before review starts. If a
+review is conducted in the wrong mode, the findings won't reach the
+reader.
+
+## PR Mode Workflow
+
+### Step 1: Start a Pending Review
+
+```text
+Tool: mcp__github__create_pending_pull_request_review
+Args: { owner, repo, pull_number }
+```
+
+This creates a draft review that doesn't appear on the PR until
+submitted. The draft accumulates comments without spamming the PR.
+
+### Step 2: Fetch the Diff
+
+```text
+Tool: mcp__github__get_pull_request_diff
+Args: { owner, repo, pull_number }
+```
+
+The diff tells you which file paths and line numbers to use for each
+inline comment. Comments tied to lines that don't appear in the diff
+are rejected by GitHub.
+
+### Step 3: Collect All Findings First
+
+Read through the entire diff. Identify every violation worth flagging.
+Number them sequentially: Issue 1, Issue 2, Issue 3, etc.
+
+Do NOT post comments as you find them. Collect first, post second.
+
+### Step 4: Add Comments in Parallel
+
+```text
+Tool: mcp__github__add_pull_request_review_comment_to_pending_review
+Args: { owner, repo, pull_number, path, line, body }
+```
+
+CRITICAL: Post ALL comments in a SINGLE response, in parallel tool
+calls. Posting them one-at-a-time across multiple responses creates
+visual flicker and may cause GitHub to throttle.
+
+Each comment body starts with:
+
+```text
+**Issue N: [Brief title]**
+```
+
+Followed by the description and suggested fix.
+
+### Step 5: Submit the Review
+
+```text
+Tool: mcp__github__submit_pending_pull_request_review
+Args: { owner, repo, pull_number, event: "COMMENT" }
+```
+
+Use `event: "COMMENT"` (non-blocking) — NOT `REQUEST_CHANGES`. The
+non-blocking event lets the author address comments without
+forcing a re-review.
+
+Do NOT include a `body` parameter. The pending-review workflow
+already attaches each finding inline; a summary body just clutters
+the PR.
+
+## Comment Format
+
+### Standard Comment
+
+```text
+**Issue 1: Formal tone**
+
+Line 15 uses "cannot" — CLEO docs prefer the contraction "can't" for
+conversational tone.
+
+Suggested fix:
+
+```diff
+-You cannot run this command on a dirty tree.
++You can't run this command on a dirty tree.
+```
+```
+
+### Comment with Multiple Examples
+
+```text
+**Issue 3: Vague headings**
+
+The headings "Setup" (line 8) and "Configuration" (line 47) don't
+tell the reader what each section is for.
+
+Suggested fixes:
+
+- "Setup" → "Install dependencies and run init"
+- "Configuration" → "Configure release pipeline before first ship"
+```
+
+### Comment with Diff Suggestion
+
+GitHub supports rendered diff suggestions when the comment is on a
+specific line. Use this format:
+
+````text
+**Issue 5: User-construct**
+
+Line 22 uses "users" — CLEO docs say "people".
+
+```suggestion
+people can configure the cache by setting `cacheTimeout`.
+```
+````
+
+The `suggestion` block becomes a "Commit suggestion" button for the
+author. Use sparingly — only when the fix is a one-line replacement.
+
+## Local Mode Workflow
+
+When MCP tools aren't available, output the same findings in the
+conversation using numbered markdown:
+
+```markdown
+## Issues
+
+**Issue 1: Formal tone**
+Line 15: This could be more conversational. Consider: "You can't..."
+instead of "You cannot..."
+
+**Issue 2: Vague heading**
+Line 8: The heading could be more specific. Try stating the point
+directly: "Run migrations before upgrading" vs "Upgrade process"
+
+**Issue 3: Patronizing qualifier**
+Line 23: Remove "easy" — it patronizes the reader. Let the steps
+speak for themselves.
+```
+
+### gh CLI Fallback
+
+If MCP tools aren't available but `gh` CLI is, you can still post a
+PR review via shell:
+
+```bash
+gh pr review <PR_NUMBER> --comment --body "$(cat <<'EOF'
+## Issues
+
+**Issue 1: Formal tone**
+Line 15: This could be more conversational...
+
+**Issue 2: Vague heading**
+Line 8: The heading could be more specific...
+EOF
+)"
+```
+
+The shell route uses a single overall comment rather than inline
+comments. Less precise but still useful when MCP isn't an option.
+
+## Numbering Discipline
+
+Every issue MUST be numbered sequentially starting from Issue 1.
+
+```text
+GOOD:
+Issue 1: ...
+Issue 2: ...
+Issue 3: ...
+
+BAD (skipping numbers):
+Issue 1: ...
+Issue 3: ...
+
+BAD (random labels):
+Issue A: ...
+Issue 2: ...
+Issue Important: ...
+```
+
+Sequential numbering lets the author say "fix issues 1, 3, and 5"
+unambiguously. It also lets them track which feedback they've
+addressed.
+
+## Materiality Before Numbering
+
+Before assigning Issue numbers, run the materiality filter (see
+`style-violations.md` §Materiality Filter). Issues that would not
+make a meaningful difference to the reader are SKIPPED, not numbered
+and labeled "minor".
+
+The materiality filter exists because flooding the author with low-
+value flags trains them to ignore the review. Be selective up front;
+flag only what matters.
+
+## Review Length Guidelines
+
+| Doc size | Typical issue count |
+|----------|---------------------|
+| Small (< 100 lines) | 0-3 issues |
+| Medium (100-300 lines) | 0-8 issues |
+| Large (300+ lines) | 0-15 issues |
+
+A review with 30 issues on a 200-line doc signals one of:
+
+- The doc is genuinely in bad shape (needs deep rewrite, not nits)
+- The reviewer is over-flagging low-value stuff
+
+If you find yourself at 20+ issues on a medium doc, step back and
+ask: is the materiality filter being applied? Are these the issues
+that matter?
+
+## Workflow Discipline
+
+| Step | Anti-pattern | Correct |
+|------|--------------|---------|
+| Start | Begin posting comments immediately | Start pending review first |
+| Identify | Post issues one-by-one as found | Collect ALL, then post in parallel |
+| Format | Plain text bodies | `**Issue N: [Title]**` prefix |
+| Submit | `event: REQUEST_CHANGES` blocks PR | `event: COMMENT` is non-blocking |
+| Body | Long summary body on submit | Empty body — let inline comments speak |
+
+## Re-Review After Fix
+
+When the author addresses feedback and pushes new commits, run the
+review again on the updated diff. Don't re-flag issues that are
+already fixed; do flag new issues introduced in the fix.
+
+For re-reviews, start the comment with a status line:
+
+```text
+**Issue 2 (UPDATED): Vague heading**
+
+The previous fix changed "Setup" to "Setup Steps" — still vague.
+Try "Install dependencies, then run init".
+```
+
+The "(UPDATED)" tag signals to the author that this is iteration,
+not a brand-new flag.
+
+## When Review Should Block
+
+The default event is `COMMENT` (non-blocking). Use `REQUEST_CHANGES`
+only when the PR contains issues that, if shipped, would actively
+harm readers:
+
+- Broken code examples that would fail when copy-pasted
+- Outdated security guidance
+- Links to deprecated APIs in setup instructions
+- Patronizing language to vulnerable audiences
+
+For everything else, use COMMENT. Trust the author to take feedback
+seriously without being forced.

package/skills/ct-docs-review/references/style-violations.md

@@ -0,0 +1,341 @@
+# Style Violations
+
+The taxonomy of style violations that ct-docs-review catches. Each
+violation type carries a detection pattern, an issue title format,
+and a remediation message. The numbering scheme below (V-NNN) is
+informational — issues in reviews are numbered sequentially per
+review, not by global ID.
+
+## Violation Categories
+
+| Category | Examples | Severity |
+|----------|----------|----------|
+| Forbidden phrases | "easy", "simple", "just", "click here" | High |
+| Tone and voice | "we" referring to CLEO, formal language | Medium |
+| Structure | Buried lead, vague heading, no clear purpose | Medium |
+| Links | Bare-word links, link-in-heading | High |
+| Formatting | Missing language tag, full-width screenshot | Low |
+| Code examples | Don't run, out of order | High |
+| Sentence construction | Pronoun overuse, missing serial comma | Low |
+
+Severity drives prioritization but not categorical filtering — review
+flags everything worth fixing. The final filter is the materiality
+test: "would fixing this make a meaningful difference to the reader?"
+
+## Forbidden Phrases
+
+The hardest-to-shake violations. They sneak into drafts because they
+feel natural — and they're banned because they're patronizing.
+
+### "easy" / "simple" / "just"
+
+**Detection pattern.**
+
+```bash
+grep -inE '\b(easy|simple|just|easily|simply)\b' <file>
+```
+
+**Issue title.** `Patronizing qualifier: "<word>"`
+
+**Remediation message.**
+
+> Line X uses "<word>" — this assumes the reader's context. Remove it
+> and let the steps speak for themselves.
+
+**Examples.**
+
+| Before | After |
+|--------|-------|
+| Setting up SAML is easy. | Set up SAML by following these steps. |
+| Just run `cleo init`. | Run `cleo init`. |
+| The CLI makes this simple. | Use the CLI: `cleo verify`. |
+
+### "obviously" / "of course"
+
+**Detection pattern.**
+
+```bash
+grep -inE '\b(obviously|of course|clearly|naturally)\b' <file>
+```
+
+**Issue title.** `Condescending qualifier: "<word>"`
+
+**Remediation message.**
+
+> Line X uses "<word>" — patronizing the reader. If it's truly obvious,
+> the doc doesn't need to say so; if it's not, calling it obvious feels
+> condescending.
+
+### "click here" / "read more here"
+
+**Detection pattern.**
+
+```bash
+grep -inE '\[(click here|here|read more here|this|more info)\]\(' <file>
+```
+
+**Issue title.** `Non-descriptive link text: "<text>"`
+
+**Remediation message.**
+
+> Line X uses "<text>" as the link text. Link text MUST describe the
+> destination. Replace with descriptive text such as
+> "the [SAML configuration guide]".
+
+### "etc." / "and so on"
+
+**Detection pattern.**
+
+```bash
+grep -inE '\b(etc\.|and so on|and more)\b' <file>
+```
+
+**Issue title.** `Trailing list: "<phrase>"`
+
+**Remediation message.**
+
+> Line X ends a list with "<phrase>" — this signals incomplete thinking.
+> Either enumerate the items completely, or restate the sentence
+> without the trailing phrase.
+
+## Tone and Voice Violations
+
+### "we" referring to CLEO
+
+**Detection pattern.**
+
+```bash
+# Tricky — "we" + verb usually means CLEO
+grep -inE '\bwe (will|can|use|do|have|are|provide|deliver|run|build|deploy)' <file>
+```
+
+**Issue title.** `First-person plural referring to CLEO`
+
+**Remediation message.**
+
+> Line X uses "we" — when talking about CLEO features, say "CLEO" or
+> "it". "We" is for the human team; "CLEO" is for the system.
+
+### Formal language
+
+**Detection pattern.**
+
+```bash
+grep -inE '\b(utilize|leverage|reference|offerings|provisions|delineate)\b' <file>
+```
+
+**Issue title.** `Formal/corporate language: "<word>"`
+
+**Remediation message.**
+
+> Line X uses "<word>" — too formal. Use the everyday word: "<replacement>".
+
+| Formal | Everyday |
+|--------|----------|
+| utilize | use |
+| leverage | use |
+| reference (verb) | see, look at |
+| offerings | products, features |
+| provisions | settings |
+| delineate | describe, list |
+
+### Missing contractions
+
+**Detection pattern.**
+
+```bash
+grep -inE '\b(cannot|do not|will not|is not|are not|does not|did not)\b' <file>
+```
+
+**Issue title.** `Missing contraction: "<phrase>"`
+
+**Remediation message.**
+
+> Line X uses "<phrase>" — CLEO docs USE contractions. Change to
+> "<contracted form>" for the conversational tone.
+
+This is the one rule that surprises writers most often. CLEO is opposite
+to many style guides on this point.
+
+### "users" instead of "people"
+
+**Detection pattern.**
+
+```bash
+# Standalone "users" — careful not to match "end-users" or "user-agent"
+grep -inE '(?<!end-)\busers?\b(?!-)' <file>
+```
+
+**Issue title.** `User-construct instead of human: "<word>"`
+
+**Remediation message.**
+
+> Line X uses "<word>" — CLEO docs say "people" or "companies", not
+> "users". "User" is a system construct; "people" centers the human.
+
+Note: compound terms keep "user" — "end-user", "user-agent", "user-space".
+
+## Structure Violations
+
+### Buried lead
+
+**Detection pattern.** (Manual — no regex.)
+
+Read the first paragraph of each section. Does the action / definition
+appear in the first sentence? If not, the lead is buried.
+
+**Issue title.** `Buried lead in §<section>`
+
+**Remediation message.**
+
+> The action / definition is not stated until line X. Lead with it.
+> Move the explanation after.
+
+### Vague heading
+
+**Detection pattern.** (Manual — needs semantic reading.)
+
+Read each heading. Does it state the point or just the topic?
+
+| Vague | Specific |
+|-------|----------|
+| Configuration | Configure release pipeline before first ship |
+| Authentication | Authenticate with API tokens |
+| Notes | Use environment variables for secrets |
+| Setup | Install dependencies and run init |
+| Performance | Set timeout to 30s on slow networks |
+
+**Issue title.** `Vague heading: "<heading>"`
+
+**Remediation message.**
+
+> Heading "<heading>" doesn't tell the reader what the section is for.
+> State the action or claim: e.g., "<specific replacement>".
+
+### Paragraph without purpose
+
+**Detection pattern.** (Manual.)
+
+For each paragraph, ask "what does this contribute?" If the answer is
+"none — it restates the previous paragraph or sets up the next one
+without adding information", flag it.
+
+**Issue title.** `Paragraph without clear purpose at line X`
+
+**Remediation message.**
+
+> The paragraph at line X restates / sets up without adding new
+> information. Cut it or merge with adjacent content.
+
+## Link Violations
+
+### Link in heading
+
+**Detection pattern.**
+
+```bash
+grep -inE '^#+ .*\[.*\]\(' <file>
+```
+
+**Issue title.** `Link inside heading: "<heading>"`
+
+**Remediation message.**
+
+> Line X has a link inside the heading. Headings should be plain text;
+> move the link to the body. Exception: if the entire heading is the
+> link (no surrounding text), it's allowed.
+
+### Ampersands
+
+**Detection pattern.**
+
+```bash
+grep -inE ' & ' <file>
+```
+
+**Issue title.** `Ampersand instead of "and"`
+
+**Remediation message.**
+
+> Line X uses "&" — spell out "and" unless the ampersand is part of a
+> proper noun (e.g., "AT&T").
+
+## Formatting Violations
+
+### Missing language tag
+
+**Detection pattern.**
+
+```bash
+# Find fenced blocks with no language tag
+grep -inP '^```$' <file>
+```
+
+**Issue title.** `Code block without language tag`
+
+**Remediation message.**
+
+> Code block at line X has no language tag. Add `bash`, `typescript`,
+> `python`, `json`, etc., for syntax highlighting.
+
+### Abbreviated language tag
+
+**Detection pattern.**
+
+```bash
+grep -inE '^```(ts|js|py|rs|md)\s*$' <file>
+```
+
+**Issue title.** `Abbreviated language tag: "<tag>"`
+
+**Remediation message.**
+
+> Code block at line X uses "<tag>" — use the full name. Mapping:
+> ts → typescript, js → javascript, py → python, rs → rust,
+> md → markdown.
+
+## Code Example Violations
+
+### Example doesn't run
+
+**Detection pattern.** (Manual + tool.)
+
+For TypeScript/JavaScript/Python code blocks that contain runnable
+snippets, attempt to dry-run them (TS: `tsc --noEmit`; Python: `python
+-c`). For shell snippets, sanity-check the syntax.
+
+**Issue title.** `Example at line X doesn't compile / run`
+
+**Remediation message.**
+
+> The code at line X has <error>. Either fix the example to compile/run,
+> or mark it as pseudocode with a comment.
+
+### Commands out of order
+
+**Detection pattern.** (Manual.)
+
+In a sequence of shell commands, check that each command's
+prerequisites are stated before it.
+
+**Issue title.** `Commands out of dependency order at line X`
+
+**Remediation message.**
+
+> Command at line X depends on output of command at line Y, but appears
+> before it. Reorder, or split into separate code blocks with prose
+> between.
+
+## Materiality Filter
+
+After collecting all detected violations, apply the materiality filter:
+"Would fixing this make a meaningful difference to the reader?"
+
+- High-severity violations always pass the filter.
+- Medium-severity: pass if the doc is end-user-facing or the violation
+  appears in a prominent location (heading, intro, summary).
+- Low-severity: pass if there are several together (signals a quality
+  problem); otherwise SKIP.
+
+Flag only what passes the filter. A flood of low-severity flags
+overwhelms the reviewer — be selective.