@cleocode/skills 2026.5.84 → 2026.5.86

package/skills/ct-documentor/references/style-coordination.md

@@ -0,0 +1,195 @@
+# Style Coordination
+
+The CLEO documentation style guide lives at
+`packages/skills/skills/_shared/cleo-style-guide.md` and is referenced
+by both `ct-docs-write` and `ct-docs-review`. As coordinator, the
+documentor's role is to ensure the style guide is enforced consistently
+across the chain — write applies it; review verifies it. This reference
+covers the parts of the style guide most commonly violated and how the
+documentor enforces them.
+
+## Tone Pillars
+
+The CLEO style is **conversational, clear, user-focused**. Three pillars
+the documentor must enforce across the chain.
+
+### 1. Conversational
+
+Write the way you would explain to a colleague — not the way a corporate
+press release would. This shows up at the word level.
+
+| Avoid | Prefer |
+|-------|--------|
+| utilize | use |
+| reference | see / look at |
+| offerings | products / features |
+| we will / we can | CLEO does / CLEO can |
+| cannot, do not | can't, don't |
+| people are able to | people can |
+
+The contraction rule is real and unusual — CLEO docs USE contractions.
+Many style guides ban them; CLEO does the opposite.
+
+### 2. Clear
+
+Lead with the action; explain after. Headings state the point.
+
+| Vague heading | Clear heading |
+|---------------|---------------|
+| "Environment variables" | "Use environment variables for configuration" |
+| "Authentication" | "Authenticate with API tokens" |
+| "Configuration" | "Configure release pipeline before first ship" |
+| "Performance considerations" | "Set timeout to 30s on slow networks" |
+
+Vague headings force the reader to scan the body to learn the point.
+Clear headings let the reader skip the section if it's not what they
+need.
+
+### 3. User-Focused
+
+Use "people" or "companies", not "users". The first refers to humans;
+the second to a system construct. The CLEO docs are for humans.
+
+| Avoid | Prefer |
+|-------|--------|
+| users can | people can |
+| our users | our customers / the companies using CLEO |
+| user input | what people type |
+| user experience | what people see |
+
+This is jarring at first — many docs are full of "users". Once you
+switch, the writing reads more concretely.
+
+## Forbidden Phrases
+
+These never appear in CLEO docs. The review child rejects them on sight.
+
+- "easy" / "simple" / "just" — patronizing; the reader doesn't know if
+  it's easy until they try
+- "obviously" / "of course" — same problem
+- "for free" / "out of the box" — vague
+- "click here" / "read more here" — link text must be descriptive
+- "and so on" / "etc." — be specific or cut the sentence
+- "as mentioned above" — use a stable cross-reference
+
+The forbidden list is the most common reason a draft fails review.
+Pass the list to ct-docs-write as part of the input contract so it
+knows what to avoid.
+
+## Link Discipline
+
+Link text must describe the destination. Never link bare words like
+"here", "this", "read more".
+
+```markdown
+GOOD: See the [release pipeline ADR](../.cleo/adrs/ADR-065.md) for the gate set.
+
+BAD: See ADR-065 [here](../.cleo/adrs/ADR-065.md) for the gate set.
+
+BAD: For more info, [click here](../.cleo/adrs/ADR-065.md).
+```
+
+The full link text MUST make sense out of context — a reader scanning
+just the link list should understand each destination.
+
+## Code Block Discipline
+
+Code blocks include their language tag for syntax highlighting and
+their working-directory context.
+
+````markdown
+GOOD:
+```bash
+# In the project root
+pnpm run test
+```
+
+GOOD:
+```typescript
+// packages/cleo/src/foo.ts
+import { bar } from "@cleocode/contracts";
+```
+
+BAD:
+```
+pnpm run test
+```
+(no language tag)
+
+BAD:
+```ts
+import { bar } from "@cleocode/contracts";
+```
+(use `typescript`, not `ts`)
+````
+
+The full language tags are `bash`, `typescript`, `tsx`, `python`,
+`rust`, `json`, `yaml`, `markdown`. Avoid abbreviations.
+
+## Table Discipline
+
+Tables compress information that would otherwise sprawl. Use them
+liberally — they signal "look up data" mode.
+
+| Use a table when... | Don't use when... |
+|---------------------|-------------------|
+| You have parallel structured items | You have unstructured prose |
+| Each row has the same columns | Each "row" has different fields |
+| The reader will scan, not read | The reader needs narrative |
+
+Keep tables narrow — three to five columns is the sweet spot. Wider
+tables overflow on mobile and look like data dumps.
+
+## Image Discipline
+
+Images are scoped — they show one specific UI element with relevant
+context. They never show full-window screenshots.
+
+| Scope | When to use |
+|-------|-------------|
+| UI element + label | Annotating a feature |
+| Specific dialog | Showing a flow step |
+| Code in editor | Showing syntax highlighting |
+| Whole window | Almost never |
+
+Add alt text that describes what the image conveys, not what the image
+is of. "Screenshot of the release pipeline dashboard showing three
+green checks" rather than "Dashboard screenshot".
+
+## Cross-Skill Drift Detection
+
+Documentor MUST check that write's output and review's checks agree.
+If they disagree, the style guide reference is the tiebreaker.
+
+```text
+write_output = ct-docs-write(input)
+review_findings = ct-docs-review(write_output)
+
+# Possible drift case:
+# write produced "users" (it should have used "people")
+# review didn't flag it (its rule list was outdated)
+# → file a sync task; passing the style guide explicitly to write
+#   on next iteration
+
+# Possible drift case:
+# write produced "click here"
+# review flagged "click here" with high confidence
+# → no drift; write just made a mistake; iterate
+```
+
+When drift is detected, surface it in `needs_followup` so the next
+session updates the shared style guide or the child skill's rules.
+
+## Pre-PR Style Pass
+
+Before opening a PR with documentation changes, the documentor MUST
+run review one more time on the diff:
+
+```bash
+# Review the diff for style violations
+gh pr diff <PR_NUMBER> | ct-docs-review --mode=diff
+```
+
+PR-mode review uses the `mcp__github__*` tools when available;
+otherwise local mode is fine. The pre-PR pass catches drift that
+sneaked in during integration.

package/skills/ct-research-agent/SKILL.md

@@ -239,3 +239,12 @@ This skill binds to the **research** LOOM lifecycle stage. Governing ADRs:
 - [ADR-070 — three-tier orchestration](../../../../.cleo/adrs/ADR-070-three-tier-orchestration.md) — defines the Orchestrator → Phase Lead → Worker tiers; research runs as a leaf Worker.
 
 LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/triggers-and-routing.md` — when to use ct-research-agent and what downstream skill consumes the output
+- `references/source-strategy.md` — codebase + Context7 + web hierarchy, query patterns, time-boxing
+- `references/citation-and-evidence.md` — evidence ladder, citation format, confidence labels
+- `references/anti-patterns.md` — ten failure modes observed in past CLEO sessions and how to avoid them

package/skills/ct-research-agent/references/anti-patterns.md

@@ -0,0 +1,154 @@
+# Anti-Patterns
+
+Common failure modes for research tasks. Each pattern below has been
+observed in real CLEO sessions (some recorded in BRAIN as patterns
+`P-b2e59bf4`, `P-75035d53`, and others). Avoid them by following the
+detection cue and applying the remediation.
+
+## 1. The Hallucinated Citation
+
+**Symptom.** A finding cites a URL, function signature, or API that does
+not actually exist. The agent inferred its existence from naming
+conventions and a plausible domain.
+
+**Detection cue.** Citation has not been retrieved during this session.
+URL was not produced by a tool call; signature was not read from a file.
+
+**Remediation.** Every citation MUST come from a tool call output in this
+session — `WebFetch`, `WebSearch`, `Grep`, `Read`, `ctx7 docs`, or
+`gitnexus_*`. If the source cannot be re-shown by a tool call, it is
+hallucinated. Strip it and either re-fetch or downgrade the finding to
+`hypothesis`.
+
+## 2. The Stale Authority
+
+**Symptom.** A finding cites the official docs for library X — but the
+project uses version Y, and the cited page describes version Z which has
+different semantics.
+
+**Detection cue.** No version qualifier on the citation. The
+`package.json` or `Cargo.toml` for the project specifies a version that
+differs from the doc page version.
+
+**Remediation.** Always pin Context7 queries to the project's actual
+version. Use the `/org/project/version` form when available. Read the
+project's lockfile before citing version-dependent behavior.
+
+## 3. The Single-Blog Cascade
+
+**Symptom.** A blog post made an interesting claim; the research output
+cited it as fact; downstream the spec writer baked it into requirements;
+the implementation fails because the claim was wrong.
+
+**Detection cue.** A finding sourced to a single blog post or Medium
+article is labeled `verified` or `documented` in the output.
+
+**Remediation.** Blog posts are at most `reported` rung-3 evidence.
+Promote to `documented` only after corroborating with the canonical
+source (official docs, source code, or RFC). If no canonical source
+exists, label `anecdotal` and put it under `## Hypotheses`.
+
+## 4. The Boil-the-Ocean
+
+**Symptom.** The research task is "investigate JavaScript build tools".
+The agent spends 90 minutes producing a 50-page survey of every tool from
+Browserify to Bun, exhausts its token budget, and never answers the
+question the orchestrator actually had.
+
+**Detection cue.** Output exceeds 30 KB without a `## Recommendations`
+section in the first 20% of the file.
+
+**Remediation.** Before opening any source, restate the question in one
+sentence and pick the success criterion. "Boil the ocean" tasks SHOULD be
+split into multiple narrower research tasks via the orchestrator — return
+a `needs_followup` list rather than producing one giant document.
+
+## 5. The Confirmation Loop
+
+**Symptom.** The user (or the calling task) implied a preferred answer in
+the question. The agent finds that preferred answer immediately, stops
+searching, and reports it as if it had explored alternatives.
+
+**Detection cue.** The output lists fewer than 2 alternatives even when
+the task description used comparative language ("compare", "evaluate",
+"options"). All findings support a single direction.
+
+**Remediation.** For comparative tasks, mandate one paragraph per
+alternative with stated pros and cons, even if the agent expects to
+recommend one. The reader needs to see the tradeoff space.
+
+## 6. The Ungrounded Recommendation
+
+**Symptom.** The recommendations section contains imperative statements
+("use library X", "adopt pattern Y") that are not tied to any specific
+finding above.
+
+**Detection cue.** Recommendations cannot be traced back to a numbered
+finding or cited source.
+
+**Remediation.** Each recommendation MUST reference at least one finding
+by name or section heading. Use this format:
+
+```markdown
+1. Adopt `defineRelations` for the new schema work.
+   - Based on finding: "Drizzle v1 deprecates `relations()` in favor of
+     `defineRelations` (verified, 0.95)"
+   - Tradeoff: minor migration cost; offset by ergonomics + future-proof.
+```
+
+## 7. The Forgotten Codebase
+
+**Symptom.** Research output cites web sources extensively but never
+references the existing codebase, ADRs, or BRAIN memory. The
+recommendation contradicts a decision already recorded in ADR-XXX.
+
+**Detection cue.** No `.cleo/adrs/`, `packages/`, or `cleo memory find`
+references in the citations.
+
+**Remediation.** ALWAYS run a codebase + BRAIN sweep before opening the
+web. Even when the topic is "external", the project has likely already
+made related decisions that constrain the answer space. ADRs are
+canonical — overriding them requires explicit consensus, not silent
+research recommendation.
+
+## 8. The Manifest Stuffer
+
+**Symptom.** The pipeline_manifest entry's `key_findings` array contains
+20+ items, half of which are minor or duplicative. The orchestrator's
+briefing surface chokes on the noise.
+
+**Detection cue.** `key_findings` length > 7 or contains items shorter
+than 8 words.
+
+**Remediation.** `key_findings` is for the orchestrator's roll-up — 3-7
+sentence-length, action-oriented items only. Detail belongs in the
+output file. If a finding cannot be summarized in one sentence, it is
+two findings.
+
+## 9. The Premature Completion
+
+**Symptom.** Task is marked complete; the output file says "research
+complete" but the recommendations are vague ("further investigation
+needed", "more work required") with no specific followup IDs.
+
+**Detection cue.** Manifest status is `complete` but the file contains
+phrases like "TBD", "future work", or "to be determined".
+
+**Remediation.** If research cannot reach actionable recommendations,
+the manifest status MUST be `partial` or `blocked`, NOT `complete`.
+Specific gaps belong in `needs_followup` as concrete task descriptions,
+not as soft prose in the file body.
+
+## 10. The Format Drift
+
+**Symptom.** Output file does not match the template in SKILL.md.
+Sections are renamed, the manifest entry uses old field names, or the
+file location is wrong.
+
+**Detection cue.** Validator script fails or the orchestrator reports
+"could not parse manifest entry".
+
+**Remediation.** Re-read SKILL.md's "Output File Format" and "Manifest
+Entry Format" sections before writing. The downstream consumers are
+brittle by design — they trust the format and will reject anything
+unexpected.

package/skills/ct-research-agent/references/citation-and-evidence.md

@@ -0,0 +1,140 @@
+# Citation and Evidence
+
+Research is only useful if it is verifiable. This reference defines the
+evidence ladder, citation format, and confidence labels that every research
+finding in CLEO MUST carry. The downstream consumers — `ct-spec-writer`,
+`ct-consensus-voter`, the orchestrator's HITL gates — rely on these signals
+to weight findings correctly.
+
+## Evidence Ladder
+
+Findings sit on a five-rung ladder. Each finding in the output file MUST be
+marked with the strongest rung that applies.
+
+| Rung | Label | Meaning | Citable? |
+|------|-------|---------|----------|
+| 5 | `verified` | Reproduced locally or confirmed in two independent canonical sources | Yes |
+| 4 | `documented` | Confirmed in one canonical source (official docs, RFC, source code) | Yes |
+| 3 | `reported` | Stated in a credible community source (named blog, conference talk, well-cited GitHub issue) | Yes, with caveat |
+| 2 | `anecdotal` | Stated in an uncredentialed source (random blog, forum post) | No — needs corroboration |
+| 1 | `hypothesis` | Inferred but not verified | Never |
+
+Findings at rung 1-2 MUST live in a separate `## Hypotheses` section, never
+mixed with verified findings. The spec writer downstream will silently treat
+all findings as verified facts unless the rung labels are explicit.
+
+## Canonical Sources by Domain
+
+| Domain | Canonical source |
+|--------|------------------|
+| HTTP/REST semantics | IETF RFCs (RFC 7230-7235, RFC 9110) |
+| TLS/crypto | RFC + IANA registries + NIST publications |
+| JavaScript language | ECMAScript spec (tc39.es) + MDN |
+| TypeScript | typescript-go source or microsoft/TypeScript |
+| Node.js APIs | nodejs.org/api/* + Node source code |
+| Library X | github.com/<owner>/<repo> README + docs + release notes |
+| CLEO architecture | `.cleo/adrs/ADR-*.md` (project-internal canon) |
+| CLEO past decisions | `cleo memory find` + `.cleo/agent-outputs/` |
+| Cloud platforms (AWS/GCP/Azure) | Vendor's "what's new" page + product docs |
+
+Blog posts and Medium articles are NOT canonical — they are interpretive
+layer that may have drifted from the source.
+
+## Citation Format Standards
+
+Every citable finding includes at minimum: source identifier, retrieval
+location, and (where relevant) retrieval date.
+
+### Web Source
+
+```markdown
+According to the [Next.js 15 caching docs](https://nextjs.org/docs/app/building-your-application/caching),
+the default fetch cache behavior changed from `force-cache` to `no-store`.
+Retrieved 2026-05-19.
+```
+
+### Official Repository
+
+```markdown
+The `defineRelations` API was introduced in
+[drizzle-team/drizzle-orm@e2b9c1a](https://github.com/drizzle-team/drizzle-orm/commit/e2b9c1a)
+and replaces the legacy `relations()` helper.
+```
+
+### Project-Internal (ADR)
+
+```markdown
+ADR-065 §3 establishes the PR-gated release pipeline — direct pushes to
+`main` are prohibited (`.cleo/adrs/ADR-065-release-pipeline.md`).
+```
+
+### Project-Internal (Code)
+
+```markdown
+The current implementation in `packages/core/src/store/openCleoDb.ts:42-78`
+routes all DB opens through a single chokepoint per Decision D003.
+```
+
+### Project-Internal (BRAIN)
+
+```markdown
+BRAIN observation `O-mpd07uma-0` records that pub1-diagnoser correctly
+refused under broken dispatcher — confirming the protocol-correct refusal
+pattern is exercising at agent-level.
+```
+
+### Context7 Fetch
+
+```markdown
+Context7 query `/vercel/next.js/v15` against the question "how do I set
+revalidation interval" returns the `revalidate` segment-config option as
+the canonical mechanism.
+```
+
+## Conflict Handling
+
+When two canonical sources disagree, the research output MUST surface the
+conflict rather than silently picking one. Recommended pattern:
+
+```markdown
+### Finding: Default cache behavior in Next.js 15
+
+- The [official caching docs](https://nextjs.org/docs/app/.../caching)
+  state the default is `no-store`.
+- The [release notes for 15.0](https://nextjs.org/blog/next-15) describe
+  the change but also mention a `staleTimes` config that softens it.
+- Resolution: the default IS `no-store`, but `staleTimes` can restore
+  per-segment caching when explicitly configured.
+```
+
+Conflict surfaces are the most valuable research output — they prevent
+downstream consumers from making decisions on partial information.
+
+## Confidence Labels
+
+In addition to the evidence rung, each `key_findings` entry in the manifest
+SHOULD carry a confidence band when the rung is below 4. The orchestrator
+uses this for HITL gating in `ct-consensus-voter`.
+
+| Confidence | Meaning |
+|------------|---------|
+| 0.9–1.0 | Verified — multiple canonical sources agree |
+| 0.7–0.9 | High — one canonical source, no conflicts |
+| 0.5–0.7 | Medium — community sources agree, no canonical |
+| 0.3–0.5 | Low — single source or conflicting evidence |
+| 0.0–0.3 | Speculation — hypothesis only, not citable |
+
+The manifest entry MUST reflect these in `key_findings`:
+
+```json
+{
+  "key_findings": [
+    "Next.js 15 default cache is no-store (verified, 0.95)",
+    "staleTimes config can restore caching (documented, 0.85)",
+    "Migration path for existing apps requires per-route audit (reported, 0.6)"
+  ]
+}
+```
+
+Downstream skills filter by confidence — `ct-spec-writer` ignores findings
+below 0.5 unless the user explicitly opts in.

package/skills/ct-research-agent/references/source-strategy.md

@@ -0,0 +1,116 @@
+# Source Strategy
+
+How to pick sources, what order to query them in, and how to bound the search
+so that the research task completes within its token budget. The skill has
+three primary source channels — web, Context7, and the local codebase — and
+each carries different reliability and currency trade-offs.
+
+## Source Hierarchy
+
+| Tier | Source | Strength | Weakness |
+|------|--------|----------|----------|
+| 1 | Local codebase | Ground truth for the project | Reflects past decisions, not future ones |
+| 2 | Context7 (`ctx7 docs`) | Current official library docs | Limited to libraries published to Context7 |
+| 3 | Web search | Breadth, recency, community wisdom | Variable signal-to-noise |
+| 4 | LLM general knowledge | Conceptual framing | Stale, hallucination-prone |
+
+Always query top-down. Codebase first — the answer may already exist as
+prior art. Context7 second when a specific library or framework is named.
+Web third when the question is open-ended. LLM general knowledge SHOULD be
+used only to frame the question, never as a citable source.
+
+## Codebase Search Patterns
+
+The skill operates in a worktree; the entire repository is reachable via
+`Grep`, `Glob`, and `Read`. Use these patterns to find prior art quickly.
+
+```bash
+# Find existing ADRs on the topic
+Grep: pattern="<keyword>" path=".cleo/adrs/" output_mode="files_with_matches"
+
+# Find prior research notes
+Grep: pattern="<keyword>" path=".cleo/agent-outputs/" output_mode="files_with_matches"
+
+# Find BRAIN decisions/patterns/observations on the topic
+cleo memory find "<keyword>"
+
+# Find related tasks
+cleo find "<keyword>"
+```
+
+When the topic touches code symbols, also use the GitNexus tools — they
+return execution flows, callers, and impact rings that grep cannot surface.
+
+```bash
+gitnexus_query({query: "<concept>"})        # process-grouped flows
+gitnexus_context({name: "<symbol>"})        # 360 view of a symbol
+gitnexus_impact({target: "<symbol>"})       # blast radius
+```
+
+## Context7 (ctx7) Workflow
+
+For any question that names a library, framework, SDK, or CLI tool, use the
+`ctx7` CLI before the open web. The workflow is two-step.
+
+```bash
+# Step 1 — resolve the library ID
+npx ctx7@latest library "<library-name>" "<user-question>"
+
+# Step 2 — fetch docs for the resolved ID
+npx ctx7@latest docs <libraryId> "<user-question>"
+
+# Optional — retry with sandboxed agents pulling source + web
+npx ctx7@latest docs <libraryId> "<user-question>" --research
+```
+
+The official library name is required — pass `"Next.js"` not `"nextjs"`.
+Version-specific docs use the `/org/project/version` form (e.g.
+`/vercel/next.js/v14.3.0`). Pass the user's full question as the query —
+specific queries return better matches than single words.
+
+## Web Search Tactics
+
+Web search is the most variable channel. Apply these filters to keep the
+signal high.
+
+- Prefer the canonical source (official docs, GitHub README, RFC) over
+  blog posts, Medium, StackOverflow.
+- Prefer recent results — append `2026`, `2025`, or the current year when
+  the topic is moving fast (LLM APIs, build tools, framework migrations).
+- Cross-check at least two sources before stating a fact. A single blog
+  post is a lead, not a finding.
+- Avoid AI-generated content farms — sites that publish hundreds of
+  thin "guides" daily are not citable.
+- Strip tracking parameters from URLs when citing — they break and they
+  leak provenance.
+
+## Time-Boxing
+
+Research is unbounded by nature; the skill MUST self-limit. Use this
+schedule when the task does not specify otherwise.
+
+| Topic complexity | Time budget | Sources to query |
+|------------------|-------------|------------------|
+| Single library/API question | 5 min | Context7 only |
+| "What is the current best practice for X" | 15 min | Web + Context7 |
+| "Compare options A, B, C for use-case Y" | 30 min | Web + Context7 + codebase |
+| "Audit current implementation against state of the art" | 60 min | All sources |
+
+When the budget is exhausted, write up what was found with `status: partial`
+and list remaining questions in `needs_followup`. Partial research is more
+useful than abandoned research.
+
+## Citation Format
+
+Every finding MUST carry a source. Acceptable formats:
+
+```markdown
+- According to [the Next.js routing docs](https://nextjs.org/docs/app), ...
+- Context7 (`/vercel/next.js/v15`) confirms that ...
+- See `.cleo/adrs/ADR-065-release-pipeline.md` §3 for prior decision on ...
+- The current implementation at `packages/cleo/src/commands/release.ts:42` ...
+- BRAIN observation `O-mpd07uma-0` records the pub1-diagnoser refusal pattern.
+```
+
+Unsourced claims SHOULD be flagged with `[unsourced]` or moved to a
+`Hypotheses` section. The reader must always be able to verify.