@neikyun/ciel 6.11.0 → 6.11.2

package/assets/skills/workflow/debug-reasoning-rca/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: debug-reasoning-rca
+description: How to debug systematically — hypothesis-driven root cause analysis methodology. 3 parallel hypotheses, fault-type taxonomy (model/context/orchestration/environment), semantic diff between expected and actual behavior. For bugs, incidents, flaky tests, regressions, production failures.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Systematic Debugging — Root Cause Analysis Methodology
+
+## What this covers
+
+How to find the real cause of a bug, not just patch the symptom. Default LLM failure: jump to the first plausible fix. Proper debugging is hypothesis-driven (Hunt & Thomas) and catches 75% more recurrences (STRATUS 2025).
+
+## Core principle
+
+**Never propose a fix before a hypothesis is SUPPORTED by evidence.** "It might be this, let me fix it" is forbidden.
+
+## Step 1: Gather context
+
+Before hypothesizing, understand the failure:
+
+- **Read the error literally** — stack trace, log line, exit code. What does the system actually say?
+- **Read the failing code** at the exact `file:line` from the trace
+- **Check recent changes** — `git log -p --since="7 days ago" -- <scope>`. A recent bug usually has a recent cause.
+- **Run the repro** once and capture full output
+
+Skip this step = hypotheses based on vibes.
+
+## Step 2: Generate 3 hypotheses
+
+Generate EXACTLY 3 **causally distinct** hypotheses. Not 3 variants of the same theory.
+
+Format:
+```
+H<n>: <cause> → <mechanism> → <observable effect>
+  Evidence for: <what would be true if correct>
+  Evidence against: <what would be true if wrong>
+  Fault-type: [MODEL | CONTEXT | ORCHESTRATION | ENVIRONMENT]
+```
+
+### Fault-type taxonomy
+
+| Type | What it means | Example |
+|------|--------------|---------|
+| **MODEL** | Code logic wrong | Off-by-one, wrong algorithm, wrong assumption |
+| **CONTEXT** | Missing/stale input | Wrong config, race window, state leak |
+| **ORCHESTRATION** | Infrastructure misconfigured | Retry/timeout wrong, queue backlog |
+| **ENVIRONMENT** | External change | Dependency drift, OS change, infra outage |
+
+**Distribution rule**: hypotheses must span AT LEAST 2 fault-types. Three MODEL hypotheses = tunnel vision.
+
+## Step 3: Validate (targeted checks)
+
+For each hypothesis, run ONE targeted check (not fix):
+
+- MODEL → add a log line or unit test asserting the expected invariant
+- CONTEXT → dump actual input/config at failure point; diff vs expected
+- ORCHESTRATION → check retry count, timeout, queue depth at failure time
+- ENVIRONMENT → `<pkg-mgr> list | grep <dep>` vs lockfile; `uname -a`
+
+Record: evidence collected, hypothesis supported/refuted/inconclusive.
+
+## Step 4: Semantic diff
+
+Once supported, write the diff between expected and actual:
+
+```
+EXPECTED: <behavior that should happen>
+ACTUAL:   <behavior that happens>
+GAP:      <precise mechanism>
+ROOT:     <why the gap exists — not "because of the bug", the underlying why>
+```
+
+If ROOT reads like "because the code is buggy" — you've only found the symptom. Ask "why" again.
+
+## Step 5: Fix (two layers)
+
+- **Direct fix** — address the supported hypothesis (the bug itself)
+- **Systemic fix** — address why the bug was possible (missing test, missing alert, missing type)
+
+Systemic fix is the 75% MTTR-reduction lever. Don't skip it on Critical bugs.
+
+## Output format
+
+```
+## RCA VERDICT
+
+### Symptom
+<1 sentence>
+
+### Repro
+<exact command or "flaky — triggers ~1/N runs">
+
+### Hypotheses explored
+H1 [MODEL]: <cause> — <supported|refuted|inconclusive> — <evidence>
+H2 [CONTEXT]: <cause> — <supported|refuted|inconclusive> — <evidence>
+H3 [ORCHESTRATION]: <cause> — <supported|refuted|inconclusive> — <evidence>
+
+### Root cause
+<hypothesis number>: <cause>
+
+### Semantic diff
+EXPECTED/ACTUAL/GAP/ROOT
+
+### Fix
+- Direct: <exact code change>
+- Systemic: <test/alert/process to add>
+
+### Confidence
+HIGH | MEDIUM | LOW — <why>
+```
+
+## Auto-inference (before asking the user)
+
+Exhaust these sources before flagging input as unknown:
+
+- **SYMPTOM** → grep last error in user's prompt; tail service logs; check recent PR descriptions
+- **REPRO** → read `package.json` scripts, `Makefile`, `README.md`, test files, CI workflow
+- **SCOPE** → `git diff HEAD~10 --stat` then rank by overlap with symptom keywords
+- **RECENT_CHANGES** → `git log --since="7 days ago" --oneline -- <scope>`
+
+State inferred values as `[ASSUMED from <source>]`. Only flag as `[UNKNOWN]` if truly blocking.
+
+## How to verify
+
+- [ ] ≥ 3 hypotheses generated (not just 1)?
+- [ ] Each hypothesis has a fault type from the taxonomy?
+- [ ] Semantic diff completed (EXPECTED vs ACTUAL vs GAP)?
+- [ ] Root cause identified with evidence (file:line)?
+- [ ] Fix addresses root cause, not symptom?
+- [ ] Confidence level stated (HIGH/MEDIUM/LOW)?
+
+## Anti-patterns
+
+- **Patch-the-symptom**: add try/catch without understanding WHY it failed
+- **Fix-the-test**: modify assertion to match wrong behavior instead of fixing code
+- **Guess-and-check**: 5 commits titled "try fix" — no hypothesis discipline
+- **First-hypothesis-wins**: commit first theory without validating alternatives
+- **No repro, no RCA**: chasing intermittent bugs without deterministic repro burns hours
+
+## Structured RCA methods (complementary)
+
+The 3-hypothesis method above is the default — fast, hypothesis-driven, good for most bugs. For complex, recurrent, or systemic problems, these structured RCA methods add depth.
+
+### Decision guide
+
+| Problem type | Method | Why |
+|-------------|--------|-----|
+| Linear, single-symptom | **3 hypotheses** (default) | Fastest — parallel hypotheses, minimal overhead |
+| Recurrent incident, process failure | **5 Whys** | Iterative questioning reaches systemic root cause |
+| Multi-factor, need exhaustive exploration | **Ishikawa (Fishbone)** | 6M families (Method/Machine/Manpower/Material/Milieu/Measurement) guide complete coverage |
+| Multi-layer, complex system | **Drill Down / Tree Diagram** | Decompose recursively (build → deploy → runtime → data) into atomic sub-causes; visualize as tree |
+| Interacting causes, feedback loops | **Relations Diagram** | Map causal links, count outbound/inbound arrows to find drivers vs effects |
+
+**When to use the full sequence**: if the problem involves ≥ 3 interacting factors across distinct system layers, use the full chain: Ishikawa (explore) → Relations Diagram (map interactions) → 5 Whys on each promising node → Tree Diagram (document). For simpler problems, pick one method from the guide.
+
+### 5 Whys
+
+Ask "why?" iteratively (5× typical) on the symptom. Each answer becomes the next question. Stop when the cause is systemic/process-level, not technical. **Anti-pattern**: stopping at "error 500" — the real cause may be "no integration test catches this path."
+
+### Ishikawa (Fishbone)
+
+Draw a horizontal spine ending at the problem (fish head). Add diagonal bones for 6 families: Method, Machine, Manpower, Material, Milieu, Measurement (adapt to software: Technology, Data/API). Branch sub-causes off each family. **Anti-pattern**: filling every family superficially — depth > breadth.
+
+### Drill Down / Tree Diagram
+
+Decompose the problem into 2-4 MECE sub-causes at each level, recursing until atomic (directly fixable). Visualize the result as a hierarchical tree with AND/OR logic per branch. These are the same analytical process — decomposition (Drill Down) and visualization (Tree Diagram). **Anti-pattern**: stopping at shallow levels — "module X crashes" isn't actionable, "method Y throws Z when condition W" is.
+
+### Relations Diagram
+
+List all discovered factors. For each pair, ask if causation exists and in which direction. Draw arrows. Count outbound (drivers) vs inbound (effects). Nodes with the most outbound arrows are root cause candidates. **Anti-pattern**: connecting everything — if most factors connect to most others, the diagram is not discriminating; focus on clear causal links only.
+
+## Key insight
+
+The hardest part of debugging is not finding the fix — it's resisting the urge to fix before understanding. The 3-hypothesis discipline forces you to consider alternatives before committing to one.

package/assets/skills/workflow/depth-classifier/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: depth-classifier
+description: Classifies a coding task as Trivial, Standard, or Critical based on mechanical signals (auth paths, security code, DB tables, diff size, route handlers). Use at the start of every Ciel workflow to determine which downstream skills to invoke. Returns a one-word depth + rationale + pipeline recommendation.
+allowed-tools: Read, Grep, Glob
+---
+
+# depth-classifier — Classify task depth
+
+Gatekeeper skill at the entry of every Ciel workflow. Wrong classification = wrong depth = either waste (over-processing trivial) or risk (under-processing critical).
+
+---
+
+## Inputs
+
+- **task**: the task description in natural language (from `/ciel <task>` or user message)
+- **project-root** (optional): absolute path, defaults to CWD
+- **overlay** (optional): `ciel-overlay.md` content if available
+
+---
+
+## Classification signals
+
+### Critical if ANY match:
+
+- Path patterns: `auth/`, `security/`, `Token`, `Password`, `Secret`, `Session`, `Crypto`
+- DB table names: `users`, `sessions`, `tokens`, `accounts`, `credentials`, `2fa`, `api_keys`
+- Code patterns: `.executeQuery`, `.executeUpdate`, raw SQL, `userId` (server-provided vs client-provided), `role`, `permission`
+- Task keywords: "authentication", "authorization", "payment", "migration (DB schema)", "JWT", "OAuth", "encryption", "2FA", "session"
+- Scope: touches user data, money, audit trails
+
+### Standard if ANY match (and not Critical):
+
+- Path patterns: `routes/`, `controllers/`, `services/`, `components/`, `hooks/`
+- **CI/CD & pipeline files**: `.github/workflows/*.yml`, `.gitlab-ci.yml`, `.circleci/`, `Dockerfile`, `docker-compose*.yml`, `Jenkinsfile`, `.buildkite/`, `.drone.yml`
+- **PR-review signals**:
+  - Prompt contains a PR number (`#\d+`, `PR \d+`, `pull request \d+`) OR phrases "open PR", "review PR", "fix PR", "merge PR"
+  - Planned tool calls include `gh pr list`, `gh pr view`, `gh pr checks`, `gh pr review`, `gh pr merge` (any variant: `--auto`, `--squash`, `--merge`, `--rebase`)
+  - Planned edits touch any CI/CD pipeline file (see row above)
+- Diff scope (estimated): > 1 file OR > 50 lines change
+- Code patterns: `validate`, `sanitize`, `rateLimit`, route handlers, state management
+- Task keywords: "add endpoint", "new component", "refactor", "extract helper", "feature", "integration"
+
+**Floor rule**: if ANY PR-review signal OR any CI/CD-file signal is present, depth is **at minimum Standard** — Trivial is disqualified even if the diff is small. PR review plus CI fix is never "just a one-line change".
+
+### Trivial otherwise:
+
+- Rename, typo, 1-line fix, copyright update, README edit
+- Single-file localized change ≤ 10 lines
+- No business logic change
+
+### Default rule
+
+If unsure → **Standard**. If touching user data or auth → **Critical**.
+
+---
+
+## Pipeline recommendations
+
+Return pipeline for each depth:
+
+### Trivial
+`quoi-framer` → `pattern-fitness-check` → `faire-gatekeeper` → `relire-critic` (inline) → push → `meta-critiquer`
+
+### Standard
+`quoi-framer` → `avec-quoi-versioner` → [researcher agent + explorer agent IN PARALLEL] → `evaluer-sizer` → `faire-gatekeeper` → `critic` agent MODE=RELIRE → `prouver-verifier` → `meta-critiquer`
+
+### Critical
+All of Standard + `stride-analyzer` (after `avec-quoi-versioner`) + `security-regression-check` (between FAIRE and RELIRE) + critic agent MANDATORY
+
+---
+
+## Output format
+
+```
+## DEPTH CLASSIFICATION
+
+Depth: **Trivial | Standard | Critical**
+
+Signals detected:
+- [signal 1 with source — e.g. "path matches /auth/"]
+- [signal 2]
+
+Rationale: [1-2 sentences]
+
+Pipeline:
+1. <skill>
+2. <skill>
+...
+
+Agents required:
+- [researcher: yes/no]
+- [explorer: yes/no]
+- [critic: yes/no]
+```
+
+---
+
+## Guardrails
+
+- **Asymmetric bias**: when borderline between Trivial/Standard → Standard wins. When borderline between Standard/Critical → Critical wins. Missing a Critical is worse than over-processing a Standard.
+- **Auth/security override**: any mention of auth, credentials, tokens, or user identity → Critical regardless of diff size
+- **Single-line fix can still be Critical**: e.g. a 1-char fix in an auth check is Critical
+- **Don't infer from filename alone**: `UserService.kt` could be Trivial if the change is a rename. Look at the actual code change being proposed.
+
+---
+
+## How to verify
+
+- [ ] Classification signals checked (Critical, Standard, Trivial)?
+- [ ] Pipeline recommendation provided?
+- [ ] Default rule applied (Unsure → Standard)?
+- [ ] Auth/security files → Critical?
+
+## When triggered
+
+- Automatically at start of `/ciel <task>` via the `ciel` orchestrator
+- By `UserPromptSubmit` hook (light classification hint injected into context)
+- Explicitly when depth is ambiguous after initial assessment

package/assets/skills/workflow/diverge/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: diverge
+description: How to explore 2-3 radically different approaches before choosing one (Ciel v5 etape 5). Used after AVEC QUOI, before RECHERCHE. Prevents single-approach bias and premature convergence. Use when the task is non-trivial and there are multiple valid approaches.
+---
+
+# Divergent Exploration — 2-3 Approaches Before Choosing (Ciel v5)
+
+## What this covers
+
+How to explore multiple approaches before committing to one. In Ciel v5, this is etape 5 (DIVERGE). The goal is to avoid premature convergence on the first viable approach that comes to mind.
+
+## Core principle
+
+**Generate 2-3 approaches before evaluating any of them.** The first approach that works is rarely the best. In v5, DIVERGE happens after AVEC QUOI (versions checked) and before RECHERCHE (external research).
+
+## When to use
+
+- Non-trivial tasks with multiple valid solutions
+- Architectural decisions
+- Library/framework choices
+- Design patterns
+- Database schema design
+- API design
+
+**When NOT to use**: 1-line fix, rename, trivial config change, obvious solution.
+
+## The process
+
+### Step 1: Generate at least 2 approaches
+
+For each approach, describe:
+- What it does (1-2 sentences)
+- Key trade-offs (not "it's better" -- specific pros/cons)
+- Implementation effort (rough estimate)
+- Risk level (low/medium/high)
+
+Approaches should be GENUINELY different. Not "use React vs use React with hooks" -- same approach. Bad:
+- "Use PostgreSQL vs MySQL" (trivial database choice)
+- "Use REST vs GraphQL" (genuinely different)
+
+### Step 2: Let them compete (not you decide)
+
+Generate approaches WITHOUT evaluating them. Evaluation happens in EVALUER (etape 9), after RECHERCHE has gathered external data about each approach.
+
+Common trap: generating 2 approaches but immediately choosing the first one without research.
+
+### Step 3: Document for EVALUER
+
+Pass both approaches (with their trade-offs, effort, risk) to the EVALUER phase. The researcher should check documentation for BOTH approaches.
+
+## Output format
+
+```
+## DIVERGE
+
+### Approach A: <name>
+What: <1-2 sentences>
+Trade-offs:
+  + <pro>
+  - <con>
+Effort: <XS/S/M/L/XL>
+Risk: <low/medium/high>
+
+### Approach B: <name>
+What: <1-2 sentences>
+Trade-offs:
+  + <pro>
+  - <con>
+Effort: <XS/S/M/L/XL>
+Risk: <low/medium/high>
+
+### (Optional) Approach C: <name>
+...
+```
+
+## Common rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I already know the best approach" | You know the first approach that came to mind. That's not the same as the best approach. Generate 2-3 then compare. |
+| "Diverging takes too long" | It takes 5 minutes. Committing to the wrong approach costs days. The math is clear. |
+| "There's only one valid way to do this" | There are almost always 2+ valid approaches. If you can't think of alternatives, you don't understand the problem well enough. |
+
+## How to verify
+
+- [ ] >= 2 genuinely different approaches generated?
+- [ ] Approaches are different in kind, not degree?
+- [ ] Trade-offs documented for each?
+- [ ] Effort estimated?
+- [ ] Risk assessed?
+- [ ] Evaluation deferred to next phase (EVALUER)?

package/assets/skills/workflow/doc-validator-official/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: doc-validator-official
+description: Before generating code that calls an external library, framework, or API, fetches the OFFICIAL documentation for the exact version in use and validates that each proposed API call (function name, signature, parameters, return type) exists as cited. Rejects reliance on Stack Overflow/blog posts when official docs exist. Forces citations for every non-trivial API use. The primary anti-hallucination gate for the RECHERCHE step.
+allowed-tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
+---
+
+# doc-validator-official — Official docs first, blogs never
+
+LLM hallucination of APIs is the #1 coding failure mode (ISSTA 2025). Functions that don't exist, wrong version signatures, parameters invented, return types fabricated. Advanced RAG against official docs eliminates this class of bug.
+
+---
+
+## Inputs (infer before asking — see orchestrator's Autonomy protocol)
+
+```
+TARGET_STACK: [language + framework + version — e.g., "TypeScript 5.5 + React 19"]
+PROPOSED_APIS: [list of function/class/method calls the implementation will use]
+PACKAGE_SOURCES: [paths to package.json / go.mod / requirements.txt / Cargo.toml]
+```
+
+### Auto-inference sources (exhaust BEFORE asking the user)
+
+- **PACKAGE_SOURCES** → `find . -maxdepth 3 -name 'package.json' -o -name 'go.mod' -o -name 'requirements.txt' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'Gemfile'` — pick up every manifest without asking.
+- **TARGET_STACK** → derive from PACKAGE_SOURCES (read the files, extract versions of the key libs). Cross-check with `ciel-overlay.md`.
+- **PROPOSED_APIS** → parse from the user's task description + any referenced code diff. If user said "use stripe to refund X", APIs = `stripe.refunds.create`, `stripe.paymentIntents.retrieve`, etc.
+
+Only BLOCK if no manifest file exists at all (greenfield project with no deps yet) — then ask once "Which package.json / go.mod should I validate against?".
+
+---
+
+## Phase 1 — Extract exact versions
+
+Read package manifests. For each lib in PROPOSED_APIS extract the pinned version:
+
+```bash
+# npm/yarn/pnpm
+jq -r '.dependencies + .devDependencies | to_entries[] | "\(.key) \(.value)"' package.json
+
+# go
+grep -E '^\s*<lib>' go.mod
+
+# python
+grep -E '^<lib>' requirements.txt pyproject.toml
+```
+
+Record as `{lib_name, pinned_version, source_file:line}`.
+
+If version is a range (`^1.2.0`) → resolve the actual installed version from lockfile (`package-lock.json`, `yarn.lock`, `uv.lock`, `Cargo.lock`). Never validate against a range.
+
+---
+
+## Phase 2 — Locate official docs
+
+For each lib, find the CANONICAL doc URL for the exact version. Priority order:
+
+1. **Versioned docs site** — `https://reactjs.org/docs/v19.0.0/` or `https://fastapi.tiangolo.com/release-notes/`
+2. **Repo `/docs/` at the tag** — `https://github.com/org/repo/tree/v1.2.0/docs`
+3. **README at the tag** — `https://github.com/org/repo/blob/v1.2.0/README.md`
+4. **Context7 MCP** (if available) — provides up-to-date official docs for thousands of libs
+
+### Reject these sources
+
+- Stack Overflow answers (even highly upvoted — often stale)
+- Medium/dev.to blog posts (version drift, author may have been wrong)
+- AI-generated tutorials (recursion hazard)
+- Forum posts without corroboration by official docs
+
+These may GUIDE investigation but never JUSTIFY an API claim.
+
+---
+
+## Phase 3 — Validate each proposed API
+
+For each item in PROPOSED_APIS:
+
+1. **Fetch the official doc page** for that function/class.
+2. **Verify the signature matches** — function exists, parameter names and types match, return type matches.
+3. **Verify version availability** — "Added in vX.Y" metadata. If the pinned version < X.Y, the API doesn't exist in this project yet.
+4. **Capture citation** — URL + section header + (if possible) quoted signature.
+
+Output per API:
+```
+[VALID] lib.funcName(a: T1, b: T2): T3
+  Source: <URL>#section
+  Cited: "funcName(a, b) → T3 — Added in 1.4.0"
+  Pinned: 1.5.2 ✓
+```
+
+or:
+```
+[INVALID] lib.funcName — NOT FOUND in v1.5.2 docs
+  Similar: lib.otherFunc (did you mean this?)
+  Action: rename or choose a different lib
+```
+
+or:
+```
+[AMBIGUOUS] lib.funcName exists but signature differs
+  Doc says: funcName(a: string, opts?: Opts) → Promise<T>
+  Proposed: funcName(a, b) — missing opts wrapping
+  Action: rewrite call site to match doc signature
+```
+
+---
+
+## Phase 4 — Citation enforcement
+
+Every non-trivial API use in the final implementation MUST have a citation comment OR be documented in the PR description. Trivial = stdlib builtin (`Array.map`, `str.split`). Non-trivial = third-party lib, framework-specific, version-sensitive stdlib (e.g., `Intl.Segmenter`).
+
+Citation format in code (optional, acceptable if 3+ APIs would clutter):
+```typescript
+// Per react.dev/reference/react/useTransition (v19)
+const [isPending, startTransition] = useTransition();
+```
+
+Citation format in PR description (mandatory for Critical tasks):
+```
+## External APIs used
+- `react.useTransition` — react.dev/reference/react/useTransition (v19)
+- `drizzle-orm.select().from()` — orm.drizzle.team/docs/select (v0.33)
+```
+
+---
+
+## Phase 5 — Training-cutoff awareness
+
+If a lib in PROPOSED_APIS was released or had a major version AFTER your knowledge cutoff (January 2026), explicitly flag:
+
+```
+[CUTOFF-WARNING] lib <name> vX.Y (released 2026-MM-DD)
+  Your training data does not reliably cover this version.
+  MANDATORY: fetch live docs, do not rely on pattern-matching from memory.
+```
+
+---
+
+## Output format
+
+```
+## DOC VALIDATION
+
+### Versions resolved
+- react 19.0.2 (from package-lock.json:1234)
+- drizzle-orm 0.33.1 (from package-lock.json:5678)
+
+### API validation
+[VALID]      react.useTransition — react.dev/.../useTransition (v19)
+[VALID]      drizzle-orm.select — orm.drizzle.team/docs/select (v0.33)
+[INVALID]    drizzle-orm.raw — not in v0.33, renamed to sql.raw in v0.30+
+[AMBIGUOUS]  react.use — signature changed in v19, proposed call uses v18 shape
+
+### Cutoff warnings
+- drizzle-orm 0.33 (released 2026-02) — post-cutoff, relied on live fetch
+
+### Verdict
+BLOCKING: 1 INVALID, 1 AMBIGUOUS — cannot proceed until resolved
+```
+
+---
+
+## Guardrails
+
+- **Never infer an API from "it should exist"** — if you can't cite the doc page, the API doesn't exist for your purposes.
+- **Exact version, never range** — validating against a range produces false positives.
+- **Reject blog/SO as primary source** — they may CONFIRM, never ESTABLISH.
+- **Cutoff-flag everything post-January 2026** — your memory is wrong often enough to require external validation.
+- **If docs don't exist** (tiny lib, no website, just README) → read the source directly at the tag. No README + no source available → replace the lib.
+- **Budget**: 5 APIs × 2 min lookups = 10 min max. Beyond 10 APIs, batch via a single doc-site crawl or ask user to narrow.
+
+---
+
+## How to verify
+
+- [ ] Exact versions extracted from lock files?
+- [ ] Official docs located for each API call?
+- [ ] Each proposed API validated (function name, signature, params, return type)?
+- [ ] Citations enforced (file:line or URL for every API)?
+- [ ] Training-cutoff awareness applied (if lib updated after cutoff)?
+- [ ] VERDICT issued (VALID / INVALID / UNCERTAIN)?
+
+## When triggered
+
+- RECHERCHE step for Standard/Critical tasks using external libs
+- Before any code using a lib published/updated after your knowledge cutoff
+- When `@ciel-researcher` is dispatched for API design
+- When user says "use library X" and you have no strong prior
+- After `ai-failure-modes-detector` flags an invented-API risk
+
+---
+
+## References
+
+- ISSTA 2025 — "LLM Hallucinations in Practical Code Generation: Phenomena, Mechanism, and Mitigation"
+- arxiv 2404.00971 — "Beyond Functional Correctness: Exploring Hallucinations in LLM-Generated Code"
+- Mintlify — AI hallucination prevention via accurate docs
+- Context7 MCP — `@upstash/context7-mcp` for live official-doc retrieval