@cleocode/skills 2026.5.84 → 2026.5.86

package/skills/ct-documentor/references/anti-patterns.md

@@ -0,0 +1,216 @@
+# Anti-Patterns
+
+Failure modes specific to documentation coordination. Each is detectable
+during the documentor's workflow and has a concrete remediation. Several
+have been observed in past CLEO sessions and are recorded in BRAIN.
+
+## 1. The Phantom Documentation
+
+**Symptom.** Manifest reports "documentation complete" but no file
+exists at the claimed path.
+
+**Detection cue.** `cat <claimed-path>` returns "no such file". Or
+`git log --follow <claimed-path>` returns nothing.
+
+**Root cause.** The documentor described work it didn't actually
+delegate. Common when the orchestrator stuffed a doc task into a
+larger PR and the documentor coordinator didn't get triggered.
+
+**Fix.** After every chain, the documentor MUST verify the file
+exists and contains the claimed content. Use `Read` to confirm before
+appending the manifest entry.
+
+## 2. The Duplicate Page
+
+**Symptom.** Two pages cover the same topic with similar but
+non-identical content. Readers find one or the other depending on
+search keywords; updates land on one and not the other.
+
+**Detection cue.** Glob + grep during Discovery turns up a prior
+page on the same topic; documentor proceeded to create a new one
+anyway.
+
+**Root cause.** Skipped Discovery, or treated "I prefer this path
+name" as justification to duplicate.
+
+**Fix.** When prior coverage exists, UPDATE it. The MAINTAIN, DON'T
+DUPLICATE rule is in SKILL.md for this reason. Add a section to the
+existing page; do not create a sibling.
+
+## 3. The Stale Library Citation
+
+**Symptom.** A how-to or reference cites a library API that has been
+renamed, deprecated, or removed.
+
+**Detection cue.** `ct-docs-lookup` was NOT invoked for the topic.
+
+**Root cause.** Documentor coordinator skipped lookup because "I know
+the API" or assumed training data was current.
+
+**Fix.** Always invoke `ct-docs-lookup` when documenting external
+library behavior. Training data is stale by definition — Context7 is
+the current source.
+
+## 4. The Type Confusion
+
+**Symptom.** Document uses tutorial framing for what should be a
+reference, or vice versa. Reader confused.
+
+**Detection cue.** A "how-to" doc spends 5 paragraphs explaining
+concepts before any imperative step. Or a "reference" doc reads
+like a narrative.
+
+**Root cause.** Skipped Classification; documentor didn't pick a type
+up front.
+
+**Fix.** Always assign the Diátaxis type (or CLEO-native type) before
+invoking write. The type determines the template; the template
+prevents drift.
+
+## 5. The Infinite Review Loop
+
+**Symptom.** Review keeps finding issues; write keeps fixing; review
+keeps finding new issues. The loop never converges.
+
+**Detection cue.** Iteration count exceeds 3.
+
+**Root cause.** Either (a) the topic is mis-scoped (the audience is
+unclear, the type is wrong), or (b) the style guide and the writer's
+defaults conflict.
+
+**Fix.** After 3 iterations, escalate to HITL with:
+- Original input
+- Each draft
+- Each review's findings
+- The pattern across iterations (e.g., "review keeps flagging tone,
+  write keeps producing the same tone")
+
+HITL can override or re-scope. Don't burn tokens on convergence the
+loop won't reach.
+
+## 6. The Orphan Cross-Reference
+
+**Symptom.** Updated doc links to a page that no longer exists, or to
+a section that was renamed.
+
+**Detection cue.** `markdown-link-check` flags the link as broken.
+Or the index/TOC contains entries for files that have been deleted.
+
+**Root cause.** Documentor consolidated content but didn't update
+inbound references.
+
+**Fix.** When consolidating or moving content:
+1. Find all inbound links: `grep -r "<old-path>" docs/`
+2. Update each link or add a redirect
+3. Add a deprecation notice at the old path that explains the move
+4. Only delete the old path after a deprecation period
+
+## 7. The Voice Drift
+
+**Symptom.** Same doc switches between "you", "we", "the user", and
+"people" within a few paragraphs.
+
+**Detection cue.** Grep for pronouns in the new file; count occurrences
+of each voice marker.
+
+**Root cause.** Either write produced inconsistent voice, OR the doc
+was assembled from multiple sources without normalization.
+
+**Fix.** CLEO style is "you" (second person) for how-tos and tutorials;
+"CLEO" (third person) for explanations and references. Apply
+consistently. Pass the choice explicitly to ct-docs-write as input.
+
+## 8. The Forbidden Word Sneak-In
+
+**Symptom.** Doc ships with "easy", "simple", "just", "obviously",
+or other forbidden phrases.
+
+**Detection cue.** Review didn't catch it. Grep for the forbidden
+list in the new file.
+
+**Root cause.** Review's rule list drifted from the canonical style
+guide. Or the words appeared inside a code block (where review may
+skip).
+
+**Fix.** Run grep yourself before completing:
+
+```bash
+for word in easy simple just obviously "click here" "read more here"; do
+  grep -n "$word" <new-file> && echo "FAIL: $word"
+done
+```
+
+If review missed something, also file a task to sync the rule list.
+
+## 9. The Imperative Confusion
+
+**Symptom.** A tutorial uses "you can", "you might", "the user can",
+when the contract is "the reader DOES this step now".
+
+**Detection cue.** Modal verbs (can, might, would) appear in tutorial
+step bodies.
+
+**Root cause.** Writer hedged when the doc required imperatives.
+
+**Fix.** Tutorials and how-tos use imperative voice — "Run the
+command", "Open the file", "Set the value". Pass that constraint
+explicitly to ct-docs-write.
+
+## 10. The Lost Manifest
+
+**Symptom.** Documentation work shipped but the orchestrator's rollup
+shows no manifest entry. Subsequent agents redo the same work.
+
+**Detection cue.** `cleo find <topic>` returns no manifest entries
+for the documentation work. The doc file exists but the manifest
+doesn't link to it.
+
+**Root cause.** Documentor skipped the manifest append step (or one
+of the children appended in a wrong format).
+
+**Fix.** The manifest append is mandatory. The documentor — not its
+children — owns the entry. Run:
+
+```bash
+cleo manifest append <(cat <<EOF
+{"id":"docs-<topic>-<date>", "file":"<path>", "title":"...", ...}
+EOF
+)
+```
+
+After append, verify with:
+
+```bash
+cleo find "<topic>" | head -3
+```
+
+The new entry should appear.
+
+## 11. The Audience Whiplash
+
+**Symptom.** Doc switches audience mid-page — opens for end-users,
+shifts into maintainer-level detail, returns to end-user framing.
+Readers from neither group are well-served.
+
+**Detection cue.** Page mixes "people who use CLEO" framing with
+"contributors to CLEO" framing.
+
+**Root cause.** Documentor didn't pin audience in Classification.
+
+**Fix.** One audience per page. If both audiences need coverage, split
+into two pages — `guide.md` for end-users and `internals.md` for
+contributors — and cross-link.
+
+## 12. The Skipped Pre-PR Pass
+
+**Symptom.** PR opens with documentation; reviewer finds style
+violations the local review didn't catch.
+
+**Detection cue.** PR comments contain style-guide flags.
+
+**Root cause.** Documentor ran review on the draft, but not on the
+PR diff. Integration introduced drift (rebase fixups, merge prose).
+
+**Fix.** Always run `ct-docs-review --mode=pr` on the PR's diff
+before requesting merge. Catches drift that slipped through during
+integration.

package/skills/ct-documentor/references/chain-orchestration.md

@@ -0,0 +1,194 @@
+# Chain Orchestration
+
+`ct-documentor` is a coordinator skill — it does not produce documentation
+directly. Its job is to orchestrate three child skills (`ct-docs-lookup`,
+`ct-docs-write`, `ct-docs-review`) in the right sequence with the right
+inputs. This reference defines when to invoke each child, what to pass,
+and how to handle returns.
+
+## The Three Children
+
+| Child | Purpose | Owns |
+|-------|---------|------|
+| `ct-docs-lookup` | Library/framework API lookup via Context7 | Current external docs |
+| `ct-docs-write` | Drafts content following CLEO style guide | New content |
+| `ct-docs-review` | Reviews against style guide; supports PR mode | Quality validation |
+
+A complete documentation task usually invokes write + review. Lookup is
+optional — only when the doc must cite a library's actual current API.
+
+## Decision Sequence
+
+For every documentation task, run this sequence before invoking any child.
+
+```text
+1. DISCOVERY
+   - Glob: docs/**/*.md to map the existing tree
+   - Grep: <topic-keywords> across docs/ to find prior coverage
+   - Decision: is there already a canonical location for this content?
+
+2. CLASSIFICATION
+   - Type: tutorial | how-to | reference | explanation (Diátaxis grid)
+   - Audience: end-user | agent | maintainer
+   - Lifecycle: new file | update existing | consolidate scattered
+
+3. CHAIN
+   - If type touches library APIs → ct-docs-lookup first
+   - Always → ct-docs-write
+   - Always → ct-docs-review
+
+4. REPORT
+   - Manifest entry with "Files NOT Created (Avoided Duplication)" section
+   - Cross-references updated
+```
+
+The Discovery step is mandatory. Skipping it produces duplicate
+documentation — the dominant failure mode of past documentation tasks.
+
+## Invoking ct-docs-lookup
+
+Use when the task touches a specific library, framework, or external
+API. Pass the library name, the user's actual question (full sentence,
+not a single word), and any version qualifier.
+
+**Invoke when:**
+
+- Documenting a setup or migration that depends on a specific
+  framework version.
+- Writing reference docs that cite a library's exported API.
+- Answering "how do I X with library Y" in a guide.
+
+**Do NOT invoke when:**
+
+- The doc describes CLEO's own internal architecture (use BRAIN + code
+  reading, not external lookup).
+- The user asks a conceptual question that does not name a library.
+
+**Input shape:**
+
+```json
+{
+  "library": "Next.js",
+  "version": "15",
+  "query": "how do I configure middleware to inject auth headers"
+}
+```
+
+**Return.** Documentation excerpts with citations. Do not paste blindly —
+synthesize into the doc body, citing the library version.
+
+## Invoking ct-docs-write
+
+The write child owns content production. Its frontmatter (under
+`packages/skills/skills/ct-docs-write/SKILL.md`) describes the style
+guide it enforces. Always invoke for any new or updated content.
+
+**Input shape:**
+
+```json
+{
+  "file_path": "docs/guides/auth-setup.md",
+  "content_topic": "configure SAML before adding users",
+  "audience": "end-user",
+  "type": "how-to",
+  "outline": [
+    "Why SAML must precede user addition",
+    "Step-by-step config",
+    "Common errors and fixes"
+  ]
+}
+```
+
+The outline guides the writer — without it, the draft tends to drift
+into tutorial mode when reference was needed (and vice versa).
+
+**Return.** A drafted markdown file. The documentor does not edit it
+directly — the next step is review.
+
+## Invoking ct-docs-review
+
+The review child owns quality validation. It checks against the CLEO
+style guide and is the gate before the documentation task can complete.
+
+**Input shape:**
+
+```json
+{
+  "file_path": "docs/guides/auth-setup.md",
+  "mode": "local"
+}
+```
+
+For PR-mode review (when reviewing a GitHub PR rather than a local
+file):
+
+```json
+{
+  "pr_url": "https://github.com/kryptobaseddev/cleocode/pull/315",
+  "mode": "pr"
+}
+```
+
+**Return.** A numbered list of issues with line refs and suggested
+fixes. If the issue count is 0, the doc passes. If non-zero, the
+documentor MUST loop — pass the issues back to `ct-docs-write` for
+revision, then re-review.
+
+## The Review Loop
+
+The contract is: documentation does not ship with open review issues.
+The documentor MUST loop until review returns zero issues OR escalates
+to HITL.
+
+```text
+draft = ct-docs-write(input)
+issues = ct-docs-review(draft)
+while issues != [] and iteration < 3:
+  draft = ct-docs-write(input + issues)
+  issues = ct-docs-review(draft)
+if issues != []:
+  escalate_to_HITL("3 review iterations did not converge")
+```
+
+Three iterations is the convergence budget. If review keeps finding
+issues, the task is mis-scoped (audience confusion, style guide
+conflict with content) — escalate rather than burning more tokens.
+
+## Cross-Skill Output Conventions
+
+All three children return to the documentor. The documentor aggregates
+into ONE manifest entry. Children do NOT each append their own — that
+would inflate the manifest.
+
+```json
+{
+  "id": "docs-auth-setup-2026-05-19",
+  "file": "2026-05-19_docs-auth-setup.md",
+  "title": "Documentation Update: SAML Setup Guide",
+  "status": "complete",
+  "agent_type": "documentation",
+  "topics": ["documentation", "auth", "saml"],
+  "key_findings": [
+    "Created docs/guides/auth-setup.md (how-to, end-user audience)",
+    "Cited Next.js 15 middleware API via ct-docs-lookup",
+    "Review converged in 2 iterations (8 issues → 3 → 0)",
+    "Updated docs/index.md to reference new guide"
+  ],
+  "actionable": false,
+  "needs_followup": [],
+  "linked_tasks": ["{{TASK_ID}}"]
+}
+```
+
+The `key_findings` MUST report the iteration count and the chain that
+ran. This lets the orchestrator confirm the contract was honored.
+
+## Failure Modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Doc duplicates existing content | Skipped Discovery | Always Glob + Grep before write |
+| Doc cites stale API | Skipped ct-docs-lookup | Invoke lookup for any library API claim |
+| Doc fails review repeatedly | Audience or type mismatch | Re-classify; pass corrected to write |
+| Review iteration count >3 | Mis-scoped task | Escalate to HITL with summary |
+| Manifest missing iteration data | Children appended their own entries | Children MUST return to documentor; one entry only |

package/skills/ct-documentor/references/doc-types-and-templates.md

@@ -0,0 +1,301 @@
+# Doc Types and Templates
+
+CLEO documentation follows the Diátaxis grid (tutorial, how-to,
+reference, explanation) plus three CLEO-native types (ADR,
+agent-output, skill). Each type has a distinct shape — using the
+wrong template confuses the reader. This reference defines each
+type's purpose, audience, and skeleton.
+
+## Diátaxis Grid
+
+| Type | Purpose | When user is | Cognitive mode |
+|------|---------|--------------|----------------|
+| Tutorial | Learning by doing | New, exploring | Acquisition |
+| How-to | Solving a problem | Working, blocked | Application |
+| Reference | Looking up details | Working, knows what | Lookup |
+| Explanation | Understanding | Reflecting, curious | Cognition |
+
+The four types are NOT interchangeable. A how-to written as a tutorial
+is too slow for working users; a reference written as explanation
+hides the lookup data behind prose. Identify the type up front.
+
+## Tutorial Template
+
+```markdown
+# {Tutorial Title}: Build a {thing} with {tech}
+
+This tutorial walks you through building {thing} from scratch using
+{tech}. By the end, you'll have a working {thing} and understand
+{key concepts}.
+
+## What you'll build
+
+{Screenshot or output of finished thing}
+
+## Prerequisites
+
+- {Required tool / knowledge}
+- {Required tool / knowledge}
+
+## Step 1: {action verb + noun}
+
+{1-3 sentences setting up the step.}
+
+```bash
+{exact command}
+```
+
+You should see {expected output}.
+
+## Step 2: ...
+
+...
+
+## What you learned
+
+- {concept 1}
+- {concept 2}
+
+## Next steps
+
+- See [{how-to}](../how-to/...) to do {related task}.
+- See [{reference}](../reference/...) for the full {API} surface.
+```
+
+Tutorials are linear. They never branch. They never ask the reader
+to choose. Every step results in observable progress.
+
+## How-to Template
+
+```markdown
+# How to {accomplish task}
+
+When you need to {accomplish task}, follow these steps.
+
+## Prerequisites
+
+- {Required state / config}
+
+## Steps
+
+1. {Action verb + noun}.
+   ```bash
+   {exact command}
+   ```
+
+2. {Action verb + noun}.
+
+3. {Action verb + noun}.
+
+## Verify
+
+Check that {observable outcome}.
+
+```bash
+{verification command}
+```
+
+## Troubleshooting
+
+- **{Symptom}**: {Cause + fix}
+- **{Symptom}**: {Cause + fix}
+
+## Related
+
+- [{Reference page}]
+- [{Similar how-to}]
+```
+
+How-tos assume the reader knows the basics. They do not explain why —
+they instruct.
+
+## Reference Template
+
+```markdown
+# {API/command/feature} Reference
+
+{One-sentence definition.}
+
+## Synopsis
+
+```bash
+{command-syntax} [OPTIONS] <ARGS>
+```
+
+## Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `<arg1>` | string | {what it is} |
+| `<arg2>` | number | {what it is} |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--flag` | false | {effect} |
+| `--opt <v>` | (none) | {effect} |
+
+## Output
+
+```json
+{ "schema": "..." }
+```
+
+## Errors
+
+| Exit | Code | Cause |
+|------|------|-------|
+| 0 | — | Success |
+| 1 | E_VALIDATION | Bad input |
+
+## Examples
+
+```bash
+{example 1}
+```
+
+```bash
+{example 2}
+```
+```
+
+References are dense and exhaustive. They do not include narrative.
+Tables are preferred over prose.
+
+## Explanation Template
+
+```markdown
+# {Concept or System Name}: Why {it matters}
+
+## Context
+
+{Why this exists; what problem it solves.}
+
+## Mental model
+
+{2-3 paragraphs framing the concept.}
+
+```mermaid
+{diagram if useful}
+```
+
+## How it works
+
+{Walk through the structure.}
+
+## Trade-offs
+
+- **{trade-off 1}**: {what gives, what gains}
+- **{trade-off 2}**: {what gives, what gains}
+
+## Comparisons
+
+| Alternative | Why we didn't pick it |
+|-------------|-----------------------|
+| {Alt A} | {reason} |
+| {Alt B} | {reason} |
+
+## Related
+
+- [{ADR-NNN}]: the decision record
+- [{Reference}]: the surface
+- [{How-to}]: practical recipe
+```
+
+Explanations are essays. They have a thesis. They argue.
+
+## CLEO-Native: ADR
+
+Architecture Decision Record. Lives in `.cleo/adrs/`. Strictly templated.
+
+```markdown
+# ADR-NNN: {Short title}
+
+**Status**: proposed | accepted | superseded | deprecated
+**Date**: YYYY-MM-DD
+**Decider(s)**: {names or "council vote ID"}
+**Supersedes**: {ADR-MMM} or "(none)"
+**Superseded by**: {ADR-PPP} or "(none)"
+
+## Context
+
+{Why this decision is needed now.}
+
+## Decision
+
+We will {state the decision}.
+
+## Alternatives Considered
+
+1. **{Alt A}**: {description, why rejected}
+2. **{Alt B}**: {description, why rejected}
+
+## Consequences
+
+- **Positive**: {what improves}
+- **Negative**: {what costs}
+- **Neutral**: {what changes without strong direction}
+
+## Implementation Notes
+
+{Pointers to follow-up tasks, specs, code.}
+```
+
+ADRs are immutable once accepted. Changes go in a new ADR that
+supersedes the old one.
+
+## CLEO-Native: Agent-Output
+
+Outputs of agent work, recorded in `.cleo/agent-outputs/`. Templated
+to support `cleo docs add` registration and rollup.
+
+```markdown
+---
+date: YYYY-MM-DD
+agent: <agent-id>
+task: T####
+status: complete | partial | blocked
+topics: [topic1, topic2]
+---
+
+# {Output Title}
+
+## Summary
+
+{2-3 sentences.}
+
+## Findings / Deliverables
+
+{Body.}
+
+## Manifest Entry
+
+```json
+{ ... }
+```
+```
+
+The frontmatter is mandatory. The CI lint (`agent-outputs-registration`
+job per T1617) rejects any new `.md` in this directory that lacks it
+or that wasn't registered via `cleo docs add` / `cleo memory observe`.
+
+## CLEO-Native: Skill
+
+Lives in `packages/skills/skills/<name>/SKILL.md`. The ct-skill-creator
+skill is the canonical template — see its references/.
+
+## When to Pick Which Type
+
+| Question | Type |
+|----------|------|
+| "How do I do X?" — and the reader is learning | Tutorial |
+| "How do I do X?" — and the reader is working | How-to |
+| "What does X do?" / "What's the syntax?" | Reference |
+| "Why does X work this way?" | Explanation |
+| "Why did we pick X over Y?" | ADR |
+| "What did this agent produce?" | Agent-output |
+| "Add a new agent skill" | Skill |
+
+When in doubt: pick how-to. It is the type most users want most of the
+time, and the easiest to convert to reference later.