@cleocode/skills 2026.5.84 → 2026.5.87

package/skills/ct-docs-lookup/references/version-specific-docs.md

@@ -0,0 +1,220 @@
+# Version-Specific Docs
+
+Library APIs drift across versions — sometimes silently (default value
+changes), sometimes loudly (renames, removals). This reference covers
+how to lock the docs lookup to the version the user actually runs,
+and how to handle migrations and deprecated APIs.
+
+## Why Version Pinning Matters
+
+The cost of citing the wrong version is high.
+
+- Drizzle ORM v1.0.0-beta renamed `relations()` to `defineRelations()`.
+  A 0.x user given a v1 example will copy code that doesn't import.
+- Next.js 15 changed default `fetch` cache from `force-cache` to
+  `no-store`. A user on 14 reading a 15 doc will not see the behavior
+  they expect.
+- React 19 introduced new hooks. A React 18 user copying a React 19
+  example gets `useActionState is not defined`.
+
+In each case, the failure mode is "confidently wrong answer". The
+remedy is always: pin to the user's actual version before fetching.
+
+## Finding the User's Version
+
+The skill SHOULD detect the user's installed version before opening
+Step 2.
+
+```bash
+# Node.js projects
+jq -r '.dependencies.next, .devDependencies.next | select(.)' package.json
+
+# Cargo projects
+cargo tree -p drizzle 2>/dev/null  # if applicable
+grep -A 1 '^drizzle-orm =' Cargo.toml
+
+# Python projects
+grep '^next' requirements.txt
+pip show next 2>/dev/null | grep '^Version'
+
+# Generic — search for any lockfile entry
+grep -A 1 'next:' pnpm-lock.yaml | head -3
+```
+
+If detection fails (no lockfile, version not pinned), ask the user
+or default to the project's stated version.
+
+## Version Format Matching
+
+Context7 IDs accept several version forms:
+
+```text
+/vercel/next.js                    # all versions; unspecified
+/vercel/next.js/v15                # latest within v15.x
+/vercel/next.js/v15.0.0            # exactly v15.0.0
+/vercel/next.js/v15.0.0-canary.7   # specific canary
+```
+
+Match the granularity of the user's question:
+
+- General "how do I do X with library" → unversioned or major-pinned.
+- Migration "from N to M" → both major-pinned: `/lib/vN` and `/lib/vM`.
+- Bug investigation "in 15.0.3 specifically X happens" → exact pin.
+
+## Major-Version Migrations
+
+When the user is upgrading from major N to major N+1, run two fetches.
+
+```bash
+# From-version: what works today
+npx ctx7@latest docs /drizzle-team/drizzle-orm/v0.36 "how do I define relations"
+
+# To-version: what they will move to
+npx ctx7@latest docs /drizzle-team/drizzle-orm/v1.0.0-beta "how do I define relations"
+
+# Compose the migration story:
+# 1. Show the current API
+# 2. Show the new API
+# 3. Show the mapping
+```
+
+The migration story has THREE parts. Skipping any of them produces
+confusion:
+
+- **Current API.** What the user has now.
+- **New API.** What it becomes.
+- **Mapping.** Mechanical translation between them.
+
+Documenting only the new API leaves the user wondering "but my code
+uses X — what does that become?"
+
+## Deprecated APIs
+
+When a fetched doc mentions an API as deprecated:
+
+1. Surface the deprecation explicitly. Don't bury it.
+2. Show the recommended replacement, fetched from the same docs.
+3. Cite when deprecation began and when removal is planned (if stated).
+
+Example output:
+
+```markdown
+The `relations()` helper in Drizzle ORM 0.x is deprecated as of v1.0.0-beta.
+Use `defineRelations` instead.
+
+| Drizzle 0.x | Drizzle 1.x (beta) |
+|-------------|--------------------|
+| `relations(table, (helpers) => ({ ... }))` | `defineRelations(schema, (t) => ({ ... }))` |
+
+Deprecation announced: v1.0.0-beta (2025-Q4).
+Planned removal: TBD (the 0.x line is still supported through 2026).
+```
+
+## Version Drift Detection
+
+Run a sanity check before answering — does the user's installed
+version match what they think they're using?
+
+```bash
+# User says "I'm on Next.js 15".
+$ jq -r '.dependencies.next' package.json
+"14.3.0"
+
+# Drift! Surface it:
+# > Your package.json says Next.js 14.3.0, not 15. Are you planning
+# > to upgrade, or did you mean 14? I'll fetch docs for what's
+# > installed unless you confirm 15 is the target.
+```
+
+This catches the common case where the user's mental model is ahead
+of (or behind) their actual install.
+
+## Multi-Library Lookups
+
+A single question may span multiple libraries. Resolve each
+independently with the right version pin.
+
+```bash
+# Question: "How do I integrate Better-Auth with Drizzle ORM in a
+#  Svelte 5 SvelteKit project?"
+
+# Three libraries; resolve each with project's actual version
+npx ctx7@latest library "Better-Auth" "..."
+npx ctx7@latest library "Drizzle ORM" "..."
+npx ctx7@latest library "SvelteKit" "..."
+
+# Then three fetches:
+npx ctx7@latest docs /better-auth/better-auth        "integration with drizzle"
+npx ctx7@latest docs /drizzle-team/drizzle-orm/v1    "integration with better-auth"
+npx ctx7@latest docs /sveltejs/kit/v2                "hooks for auth middleware"
+```
+
+Compose the answer from the three. Cite each library's version
+explicitly so the user knows what works with what.
+
+## When Versioned Docs Aren't Available
+
+Context7's catalog doesn't always have per-version slices. When a
+version pin returns "no matches":
+
+1. Drop one granularity level (e.g., `/v15.0.0-canary.7` → `/v15`).
+2. Drop another (`/v15` → `/vercel/next.js` unversioned).
+3. Add a note that version-specific data may be missing — recommend
+   the user verify against the official release notes.
+
+## Reading Release Notes
+
+When the question is "what changed in version X", release notes are
+often a better source than API docs. Two routes:
+
+```bash
+# Route 1 — Context7 may have it indexed
+npx ctx7@latest docs /vercel/next.js "release notes for v15"
+
+# Route 2 — WebFetch the official release notes page
+# (use when Context7 doesn't have release notes specifically)
+WebFetch: https://nextjs.org/blog/next-15  "summarize the breaking changes"
+```
+
+Release notes are more concise than docs and explicitly call out
+deprecations and removals — exactly what migration questions need.
+
+## Citing Versions
+
+Every code example produced from a version-pinned fetch MUST cite the
+version.
+
+```markdown
+GOOD:
+Use `defineRelations` (Drizzle ORM v1.0.0-beta and later):
+
+```typescript
+import { defineRelations } from "drizzle-orm";
+// ...
+```
+
+BAD:
+Use `defineRelations`:
+
+```typescript
+import { defineRelations } from "drizzle-orm";
+// ...
+```
+(no version context — reader doesn't know if their version supports it)
+```
+
+When the user copies the code and it doesn't work, the version citation
+is the first thing they check. Give it to them up front.
+
+## Skill Boundary
+
+This reference covers version handling within docs-lookup. It does NOT
+cover:
+
+- Migration code generators (out of scope; that's task-executor work).
+- Upgrade plan authoring (out of scope; that's spec-writer work).
+- Pinning the user's project to a new version (out of scope; that's a
+  task for the human or the executor).
+
+Docs-lookup just produces the version-accurate documentation. The
+downstream skills act on it.

package/skills/ct-docs-review/SKILL.md

@@ -20,6 +20,75 @@ license: MIT
 
 @skills/_shared/cleo-style-guide.md
 
+## Through SDK (preferred)
+
+Read the doc through the docs SSoT — not the filesystem. Reviews that grep
+loose files miss every doc that lives only as a blob, and miss the version
+history that makes "what changed?" reviews possible.
+
+### Fetch the doc to review
+
+```bash
+# By slug (preferred — stable handle survives renames):
+cleo docs fetch saml-setup-draft
+
+# By attachment ID (when the slug is unknown):
+cleo docs fetch att_01HXYZ...
+
+# By SHA-256 (when reviewing a specific version):
+cleo docs fetch 7a3f9b...
+```
+
+`cleo docs fetch` returns the full attachment envelope: metadata, slug,
+type, owner, refCount, and the bytes (base64-inline for files ≤ 1 MB,
+storage path for larger blobs).
+
+### Diff two versions of the same doc
+
+CLEO doesn't ship a dedicated `cleo docs diff` verb. Use version listing
+plus two fetches to compose the diff:
+
+```bash
+cleo docs versions --for T1234 --name saml-setup-draft
+# Returns every SHA-256 version with timestamps.
+
+cleo docs fetch <sha-v1> > /tmp/v1.md
+cleo docs fetch <sha-v2> > /tmp/v2.md
+diff -u /tmp/v1.md /tmp/v2.md
+```
+
+Reviewers SHOULD anchor every issue to a specific SHA so the author can
+reproduce the exact state being flagged.
+
+### List candidate docs by type
+
+```bash
+cleo docs list --type spec --project          # all specs in this project
+cleo docs list --task T1234 --type research   # research notes attached to T1234
+```
+
+### PR review mode — still SDK-grounded
+
+When reviewing a GitHub PR that touches a published doc, fetch the SSoT
+copy alongside the diff so you can compare the on-disk file in the PR
+against the canonical blob. Drift between the two is its own review
+finding — flag it as Issue N: docs SSoT drift.
+
+```bash
+gh pr diff <pr-number> -- docs/saml-setup.md
+cleo docs fetch saml-setup-draft     # SSoT canonical
+cleo docs status                     # full drift report
+```
+
+## Deprecated: Direct filesystem reads
+
+The legacy "open the .md file in the working tree and review it"
+pattern is deprecated. The on-disk file may lag the SSoT, the slug-
+based linkage to the originating task is invisible, and the version
+history needed for "what changed?" reviews is missing. Migrate to
+`cleo docs fetch <slug>` for every review — and run `cleo docs status`
+to surface drift before commenting.
+
 ## Review mode detection
 
 **IMPORTANT: Before starting the review, determine which mode to use:**
@@ -172,4 +241,67 @@ This could be more conversational. Consider: "You can't..." instead of "You cann
 1. Remove any issues from your assessment that won't make a material difference to the reader if addressed. Only flag issues worth the author's time to fix.
 2. **Verify all issues are numbered sequentially** starting from Issue 1 with no gaps in numbering.
 3. Confirm the format exactly matches: `**Issue N: [Brief title]**` where N is the issue number.
-4. **In PR mode**: Verify each issue was posted as a separate GitHub comment (not output to conversation).
+4. **In PR mode**: Verify each issue was posted as a separate GitHub comment (not output to conversation).
+
+## Issue length guidelines
+
+| Doc size | Typical issue count | Red flag |
+|----------|---------------------|----------|
+| Small (< 100 lines) | 0-3 issues | 10+ issues |
+| Medium (100-300 lines) | 0-8 issues | 20+ issues |
+| Large (300+ lines) | 0-15 issues | 30+ issues |
+
+A flood of low-value flags trains the author to ignore reviews. Apply
+the materiality filter aggressively — be selective up front; flag only
+what matters.
+
+## Workflow discipline
+
+| Step | Anti-pattern | Correct |
+|------|--------------|---------|
+| Start | Post comments immediately | Start pending review first |
+| Identify | Post issues one-by-one | 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 |
+
+## 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.
+
+## 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 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 iteration, not a brand-new flag.
+
+---
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/style-violations.md` — taxonomy of violations with detection patterns, issue titles, and remediation messages
+- `references/pr-review-mode.md` — pending-review workflow, comment format, gh CLI fallback, materiality filter
+- `references/inline-comment-patterns.md` — comment anatomy, single-line/multi-line/pattern fixes, anti-patterns

package/skills/ct-docs-review/__tests__/skill-docs-review.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Regression test for ct-docs-review/SKILL.md (T9642 / Epic T9629 / Saga T9625).
+ *
+ * Pins the SDK-first review contract: reviewers MUST read docs through
+ * `cleo docs fetch <slug>` rather than the working-tree file. Documents
+ * the version-diff recipe (`versions` + two `fetch`es) since the CLI has
+ * no dedicated `cleo docs diff` verb yet, and forces the Deprecated
+ * direct-filesystem section to stay in the file.
+ *
+ * @task T9642
+ * @epic T9629
+ * @saga T9625
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const thisFile = fileURLToPath(import.meta.url);
+const skillRoot = resolve(dirname(thisFile), '..');
+const skillPath = join(skillRoot, 'SKILL.md');
+const skillContent = readFileSync(skillPath, 'utf-8');
+
+describe('ct-docs-review SKILL.md — SDK-first contract (T9642)', () => {
+  it('teaches `cleo docs fetch` as the canonical read path', () => {
+    expect(skillContent).toContain('cleo docs fetch');
+  });
+
+  it('documents fetch by slug, attachment ID, AND SHA-256', () => {
+    expect(skillContent).toMatch(/By slug/i);
+    expect(skillContent).toMatch(/By attachment ID/i);
+    expect(skillContent).toMatch(/By SHA-256/i);
+  });
+
+  it('documents the version-diff recipe (no dedicated `cleo docs diff` verb yet)', () => {
+    expect(skillContent).toContain('cleo docs versions');
+    // The diff recipe MUST show two fetches piped to `diff`
+    expect(skillContent).toMatch(/cleo docs fetch[\s\S]+cleo docs fetch[\s\S]+diff/);
+  });
+
+  it('teaches `cleo docs list --type` for candidate discovery', () => {
+    expect(skillContent).toMatch(/cleo docs list\s+--type/);
+  });
+
+  it('shows `cleo docs status` for SSoT drift detection in PR review mode', () => {
+    expect(skillContent).toContain('cleo docs status');
+  });
+
+  it('marks the old direct-filesystem read path as deprecated', () => {
+    expect(skillContent).toContain('Deprecated: Direct filesystem');
+  });
+});

package/skills/ct-docs-review/references/inline-comment-patterns.md

@@ -0,0 +1,268 @@
+# Inline Comment Patterns
+
+How to construct individual review comments that are concrete,
+actionable, and respectful. Each pattern below covers a common
+review situation with a template and a worked example.
+
+## Anatomy of a Good Comment
+
+A review comment has four parts:
+
+1. **Title line.** `**Issue N: [Brief title]**` — always.
+2. **Location.** Line number or "throughout the file".
+3. **Description.** What's wrong, one sentence.
+4. **Suggestion.** Concrete fix, copy-paste-ready when possible.
+
+Skipping any part degrades the comment. Skipping the title makes
+issues unfindable; skipping location makes the fix scope unclear;
+skipping description makes the rule arbitrary; skipping suggestion
+makes the comment unactionable.
+
+## Pattern: Single-Line Fix
+
+When the fix is a one-line replacement, use the GitHub `suggestion`
+block.
+
+````text
+**Issue 1: Missing contraction**
+
+Line 15: CLEO docs use contractions. Change "cannot" to "can't".
+
+```suggestion
+You can't run this command on a dirty tree.
+```
+````
+
+The suggestion block renders as a one-click "Commit suggestion"
+button. Author applies it without leaving the PR view.
+
+## Pattern: Multi-Line Fix
+
+When the fix spans multiple lines, use a diff fence.
+
+````text
+**Issue 2: Buried lead**
+
+Lines 14-18: The action is buried in the third sentence. Lead with it.
+
+Suggested fix:
+
+```diff
+-Configuration files in CLEO support various format options including
+-JSON, YAML, and TOML. When choosing a format, consider readability,
+-merge-conflict friendliness, and editor support. Use JSON for the
+-primary config file because it's the project default.
++Use JSON for the primary CLEO config file (the project default).
++CLEO also supports YAML and TOML if your team prefers them.
+```
+````
+
+The diff fence shows before and after side-by-side. No one-click apply,
+but the structure is clear.
+
+## Pattern: Pattern Issue (Throughout File)
+
+When the same issue appears in multiple places, flag once with
+representative examples — not once per occurrence.
+
+```text
+**Issue 4: "Users" instead of "people"**
+
+The word "users" appears throughout the file (lines 8, 14, 22, 37, 51,
+68). CLEO docs say "people" or "companies".
+
+Examples to fix:
+- Line 8: "users can configure" → "people can configure"
+- Line 22: "our users expect" → "our customers expect"
+- Line 51: "user input" → "what people type"
+
+Apply the same pattern to remaining instances.
+```
+
+This compresses a 6-comment flood into a 1-comment summary. The author
+gets the message without scrolling through duplicates.
+
+## Pattern: Question (Clarification Needed)
+
+Sometimes the issue is "I don't understand the intent". Phrase as a
+question, not a demand.
+
+```text
+**Issue 5: Ambiguous step**
+
+Line 33: "Configure the cache before deployment."
+
+The step doesn't say HOW to configure the cache or WHERE to deploy.
+Is this the production cache or the dev cache? Should it reference
+the `cacheTimeout` config or the `cacheStore` setting?
+
+Suggested expansion:
+"Set `cacheTimeout` to 30000 (30s) in `cleo.config.json` before
+deploying to production."
+```
+
+Questions are respectful — they assume the author had a reason and
+you're inviting them to make it visible.
+
+## Pattern: Code-Example Failure
+
+When a code example wouldn't run, show the error.
+
+````text
+**Issue 6: Code example doesn't compile**
+
+Lines 42-46: The TypeScript example imports `defineRelations` from
+`drizzle-orm`, but the function isn't exported from the top-level
+package in v0.x — it's in `drizzle-orm/relations`.
+
+Tested:
+```bash
+$ npx tsc --noEmit example.ts
+example.ts:1:10 - error TS2305: Module '"drizzle-orm"' has no
+exported member 'defineRelations'.
+```
+
+Either:
+- Import from the subpath: `import { defineRelations } from "drizzle-orm/relations";`
+- Or cite the version that has the top-level export (v1.0.0-beta and later)
+````
+
+The error excerpt gives the author proof. Without it, the author may
+push back ("works on my machine"); with it, the issue is unambiguous.
+
+## Pattern: Style Choice with Rationale
+
+When flagging style violations, cite the rule. Don't enforce personal
+preference disguised as style.
+
+```text
+**Issue 7: Formal language**
+
+Line 27 uses "utilize" — too formal for CLEO docs. Use "use".
+
+Source: CLEO style guide §Conversational Pillar — "utilize" is on
+the avoid-list because it's just "use" wearing a suit.
+
+```suggestion
+Use the orchestrator to dispatch wave 3.
+```
+```
+
+The source line lets the author verify the rule. Without it, the
+flag feels arbitrary.
+
+## Pattern: Praise (Sometimes)
+
+When the doc does something particularly well, a short positive note
+can be valuable feedback. Keep them sparse — too much praise reads as
+performative.
+
+```text
+**Issue 8 (note, not a fix): Excellent structure**
+
+The migration table at lines 60-75 is exactly the right pattern for
+a v0.x → v1.x guide — current API, new API, mapping. Consider
+extracting this table format into a shared template for future
+migration docs.
+```
+
+Note: even praise gets a number — sequential numbering throughout.
+
+## Anti-Patterns
+
+### "This is wrong" (no fix)
+
+```text
+BAD:
+**Issue 9: Wrong**
+Line 22 is wrong.
+```
+
+No location specificity, no description, no fix. Useless.
+
+### "Maybe consider perhaps"
+
+```text
+BAD:
+**Issue 10: Possibly an issue**
+Line 33: This might be slightly suboptimal, maybe consider...
+```
+
+Hedging tells the author you don't trust your own judgment. Either
+flag it confidently or skip it.
+
+### "Bikeshedding"
+
+```text
+BAD:
+**Issue 11: Two spaces**
+Line 18 has two spaces after the period — CLEO docs use one.
+```
+
+If the rule isn't material to readers, don't flag it. Whitespace
+between sentences is invisible in rendered markdown.
+
+### "Personal preference disguised as rule"
+
+```text
+BAD:
+**Issue 12: I'd write this differently**
+Line 41 isn't how I'd phrase it — I'd say...
+```
+
+Style preference is not a rule. Either it's in the style guide (cite
+it) or it's not (skip the flag).
+
+### "Compound issue"
+
+```text
+BAD:
+**Issue 13: Multiple problems**
+Line 22 has formal tone, a vague heading, and a missing serial comma.
+Also lines 30-35 have user-construct issues.
+```
+
+Split into separate numbered issues. The author may want to fix one
+but not the others; combined flags can't be resolved partially.
+
+## Length Discipline
+
+Keep each comment short. 3-6 lines for the description; 3-10 lines
+for the suggestion block.
+
+Long comments lose the author. If the explanation needs 20 lines, you
+might be over-explaining — trust the author to understand the rule
+after the suggestion.
+
+## Tone
+
+Comments are feedback, not judgment. Aim for:
+
+- **Specific** — "line 22 uses X" not "the writing feels wrong"
+- **Concrete** — show the fix, don't describe it
+- **Respectful** — assume the author had a reason; don't assume bad faith
+- **Time-respecting** — short over long; one issue per comment
+
+## Comment Lifecycle
+
+After the author addresses feedback, the comment can be:
+
+- **Resolved** — author marks the conversation resolved when fixed
+- **Unresolved** — left as historical record if not addressed
+- **Updated** — reviewer adds follow-up after author's fix
+
+The skill doesn't need to track resolution — that's GitHub's job. But
+when re-reviewing, scan unresolved threads to see what's still pending.
+
+## Cross-Reference to Other Comments
+
+When two issues are related, reference the prior issue's number:
+
+```text
+**Issue 14: Related to Issue 3**
+
+Line 47 has the same "users" problem as Issue 3. Apply the same fix
+here too.
+```
+
+This compresses the review and shows the author the pattern.