@neikyun/ciel 6.11.2 → 6.13.0

package/assets/skills/reactive/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: reactive
+description: "Programmation Reactive — observables, streams, RxJS, backpressure, event sourcing, flux de donnees. A charger quand on utilise un paradigme reactif ou des streams."
+---
+
+# Programmation Reactive
+
+**Principe premier :** La programmation reactive n'est pas "utiliser RxJS" — c'est traiter les donnees comme un flux continu plutot que comme des valeurs ponctuelles. Dans un modele imperatif, tu demandes la valeur (`let x = getValue()`). Dans un modele reactif, tu t'abonnes au changement (`stream.subscribe(x => ...)`). La difference fondamentale : le code reactif se declare une fois et reagit a N evenements, le code imperatif repond a chaque evenement individuellement. Le piege : la complexite explose avec le nombre de streams. Sans gestion de la backpressure (producteur plus rapide que le consommateur) et du cycle de vie (unsubscribe), les streams deviennent une source de fuites memoire et de bugs subtils.
+
+## Checklist
+- [ ] Les streams sont unsubscribed proprement (`takeUntil`, `async pipe`, `DisposeBag`) — zero fuite memoire
+- [ ] La backpressure est geree : le consommateur controle le debit (`buffer`, `throttle`, `sample`, `request(n)`)
+- [ ] Les operateurs sont composees en pipeline lisible — pas de callback hell reactive
+- [ ] Les erreurs sont propagees dans le stream — pas de `try/catch` autour de `.subscribe()`
+- [ ] Les streams partages sont multicastes (`share`, `shareReplay`) — pas de side effect par souscripteur
+- [ ] Les valeurs initiales sont definies (`BehaviorSubject`, `startsWith`) — pas de "le stream emet dans 5 secondes"
+- [ ] Le debounce/throttle est utilise pour les evenements frequents (input utilisateur, scroll) — pas de traitement par frappe
+
+## Anti-patterns
+### Nested subscribes
+**Ce qu'on voit :** `stream1.subscribe(x => { stream2.subscribe(y => { stream3.subscribe(z => { doSomething(x,y,z) }) }) })`. Trois niveaux de souscriptions imbriquees.
+**Pourquoi c'est dangereux :** c'est le callback hell version reactive. Chaque subscribe est un effet de bord. Impossible de unsubcribe proprement. La gestion d'erreur est cassee. Si `stream1` emet pendant que `stream2` n'a pas fini → race condition. Le code est illisible et indetachable.
+**Faire plutot :** `combineLatest([stream1, stream2, stream3]).pipe(takeUntil(destroy$)).subscribe(([x,y,z]) => doSomething(x,y,z))`. Un seul subscribe. Flat/compose, never nest.
+
+### Pas de gestion de backpressure
+**Ce qu'on voit :** un stream de clics souris a 1000 events/s. Le consommateur traite chaque event (appel API). La file d'attente memoire explose.
+**Pourquoi c'est dangereux :** le producteur et le consommateur ont des vitesses differentes. Sans backpressure, le consommateur est inonde. Memoire → ∞. L'app freeze. Le comportement est non deterministe (depend de la charge).
+**Faire plutot :** `sampleTime(200)` (prendre un event toutes les 200ms), `debounceTime(300)` (attendre 300ms de silence), `throttleTime(500)` (max 1 emission toutes les 500ms). Le consommateur controle le debit, pas le producteur.
+
+### RxJS partout
+**Ce qu'on voit :** tout est un observable. `Observable.of(42)`, `Observable.from([1,2,3])`. Même les valeurs synchrones passent par des streams.
+**Pourquoi c'est dangereux :** la programmation reactive ajoute de la complexite cognitive et un surcout de performance. Pour des donnees synchrones (un tableau, une variable), un observable est un marteau-piqueur pour ouvrir une noix. Le code devient plus dur a lire sans benefice.
+**Faire plutot :** utiliser les observables la ou l'asynchronisme et le temps sont intrinseques : evenements utilisateur, websockets, reponses serveur, timers. Pour le synchrone, les structures de donnees normales suffisent.
+
+## Patterns
+### takeUntil pour le cleanup
+**Quand :** tout abonnement qui a une duree de vie < l'application (composant Angular, ecran React).
+**Comment :** `destroy$ = new Subject<void>()`. Tous les pipelines se terminent par `.pipe(takeUntil(this.destroy$))`. Dans `ngOnDestroy` / `useEffect` cleanup : `this.destroy$.next(); this.destroy$.complete()`. Tous les abonnements sont nettoyes en une ligne.
+
+### Event bus central
+**Quand :** communication entre composants non relies (pas de parent-enfant).
+**Comment :** un `Subject` ou `EventEmitter` partage. Les producteurs emettent, les consommateurs souscrivent. Chaque message est un type specifique (pas de `any`). Le bus est mockable en test. Alternative a Redux pour les cas simples ou la communication est le seul besoin.

package/assets/skills/release-management/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: release-management
+description: "Release Management — releases as contracts, semver as communication, pre-release channels (alpha/beta/rc), signed provenance, changelog as consumer signal. À charger quand on prépare une release."
+---
+
+# Release Management
+
+**Principe premier :** Une release est un contrat avec les consommateurs. Le numéro de version n'est pas un compteur — c'est un signal. MAJOR veut dire "tu dois migrer, voici comment". MINOR veut dire "nouveau, sans risque, upgrade". PATCH veut dire "sécurité ou bug, fais-le maintenant". Si tes numéros de version ne communiquent pas ça, ils ne servent à rien. Le changelog est la partie visible de ce contrat — sans lui, les consommateurs ne savent pas ce qui a changé et n'upgraderont pas.
+
+## Checklist
+- [ ] La version suit semver strict : MAJOR (breaking API), MINOR (nouveau compatible), PATCH (bug/security)
+- [ ] Chaque breaking change a un guide de migration (pas juste "changed X" — quoi changer, ligne par ligne)
+- [ ] Des pre-release channels existent : alpha (instable, dev), beta (feature-complete, testable), rc (release candidate, plus de bugs connus)
+- [ ] Le changelog est lisible par un humain — pas un dump de commits, pas de jargon interne
+- [ ] Les artefacts sont signés ET vérifiables (Cosign/Sigstore, checksums SHA256, SBOM)
+- [ ] Le tag Git est signé ET correspond exactement au commit du build (pas de tag après coup)
+- [ ] Les releases sont immutables — jamais de repush d'un tag, jamais de republish d'un package
+
+## Anti-patterns
+### Version bloquée
+**Ce qu'on voit :** `"version": "1.0.0"` dans package.json depuis 2 ans. 47 commits, des breaking changes, des nouvelles features — la version n'a jamais bougé.
+**Pourquoi c'est dangereux :** la version ne communique plus rien. Les consommateurs ne savent pas s'ils peuvent upgrade. Certains pinent au commit, d'autres prennent `latest` et cassent. Le projet perd la confiance de son écosystème.
+**Faire plutôt :** version bump à chaque release. Automatiser via conventional commits + semantic-release. Chaque merge sur main → version calculée → changelog mis à jour → release. Zéro intervention humaine.
+
+### Changelog = dump de commits
+**Ce qu'on voit :** CHANGELOG.md copié-collé depuis `git log --oneline`. "fix: bug", "wip", "cleanup", "fix test" — l'utilisateur ne comprend rien.
+**Pourquoi c'est dangereux :** un changelog illisible est pire qu'inexistant. Il donne l'illusion d'information. Le consommateur doit lire le diff pour comprendre ce qui a changé — exactement ce que le changelog devait éviter.
+**Faire plutôt :** changelog structuré : Added, Changed, Deprecated, Removed, Fixed, Security. Chaque entrée est une phrase compréhensible par un utilisateur du projet. Le changelog répond à : "Qu'est-ce que je dois faire pour upgrade ?"
+
+### Pre-release sauté
+**Ce qu'on voit :** `1.0.0-alpha.1` existe, puis directement `1.0.0`. Pas de beta, pas de RC. 6 mois entre alpha et stable.
+**Pourquoi c'est dangereux :** les early adopters sont punis. Ils testent l'alpha, trouvent des bugs, mais n'ont jamais de version stable de leurs retours. Ils arrêtent de tester les pre-releases. La release stable sort sans validation réelle.
+**Faire plutôt :** pipeline de maturité : alpha (semaine 1, cassant) → beta (semaine 2-3, testable, feedback) → rc (semaine 4, gel, uniquement bugfixes) → stable. Chaque étape a des consommateurs différents : devs internes → early adopters → tout le monde.
+
+### Artefact mutable
+**Ce qu'on voit :** `npm publish` puis `npm publish` à nouveau sur la même version parce que "j'ai oublié un fichier". Ou `git tag -d v1.2.3 && git tag v1.2.3`.
+**Pourquoi c'est dangereux :** un artefact mutable détruit la reproductibilité. Le hash que tu as vérifié hier n'est plus valide aujourd'hui. Impossible de faire un audit. Les mirrors de registre ont des versions différentes. C'est un cauchemar de debugging.
+**Faire plutôt :** une version = un artefact = un hash, pour toujours. Si bug → nouvelle version (1.2.4, pas 1.2.3 repush). La plupart des registres permettent de "deprecate" sans "unpublish".
+
+## Patterns
+### Conventional Commits → release automatisée
+**Quand :** tout projet avec plus d'un mainteneur.
+**Comment :** `feat:` → MINOR bump, `fix:` → PATCH bump, `feat!:` ou `BREAKING CHANGE:` → MAJOR bump. `semantic-release` lit l'historique de commits depuis la dernière release, calcule la version, génère le changelog, publie. Configuré une fois, oublié.
+
+### Pre-release channels
+**Quand :** projet avec breaking changes fréquents ou base d'utilisateurs qui teste les versions beta.
+**Comment :** `1.0.0-alpha.1` → tags `alpha` instables. `1.0.0-beta.1` → tag `beta`, feature-complete. `1.0.0-rc.1` → tag `rc`, plus de bugs connus. `1.0.0` → tag `latest`. Les consommateurs choisissent leur niveau de risque : `npm install pkg@beta` ou `npm install pkg@latest`.
+
+### Migration guide
+**Quand :** tout MAJOR bump.
+**Comment :** un fichier `MIGRATION.md` ou section dans le changelog. Format : "Avant → Après" pour chaque breaking change. Exemple de code avant, exemple après. Pourquoi le changement a été fait (pas juste "changed"). Liste des choses à vérifier après migration.

package/assets/skills/research/fact-check-claims/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: fact-check-claims
+description: Before asserting any API/version/behavior claim in code or reports, greps the source code or fetches docs to verify. Guards against "false confidence" — confident assertions without evidence. Invoked before any assertion is committed to final output.
+allowed-tools: Read, Grep, WebFetch
+context: fork
+agent: researcher
+---
+
+# fact-check-claims — Verify before asserting
+
+## What this covers
+Meta-research skill #6 of 6. The guard against false confidence. LLMs routinely state confidently wrong things — DB column names, function signatures, response shapes. This skill demands proof.
+
+## Core principle
+**VERIFIED or not. There is no "probably true."** If you can't point to evidence (file:line or URL), mark it UNVERIFIED.
+
+## Inputs
+
+```
+CLAIM: [the specific assertion to verify]
+CONTEXT: [what's being built that relies on this claim]
+SOURCES_TO_CHECK: [optional list of files/URLs to verify against]
+```
+
+## Process
+
+### 1. Classify the claim type
+
+| Type | Verify against |
+|------|----------------|
+| Code (function signature, import) | `Read` + `Grep` on actual source |
+| DB (table/column exists) | Migration files or `pg_attribute` |
+| API (response shape, status) | `curl` real endpoint or fixtures |
+| Version behavior | WebFetch official changelog |
+| Environment (Node version, etc.) | Workflow / Dockerfile / CI config |
+
+### 2. Verify from authoritative source
+
+Run the appropriate verification command. Record the evidence.
+
+### 3. Produce verification record
+
+```
+VERIFIED   — with evidence (file:line or URL + quote)
+UNVERIFIED — source not available, state explicitly
+CONTRADICTED — evidence says otherwise
+```
+
+Never mark as VERIFIED without evidence.
+
+## Common patterns
+
+### Good fact-check
+
+```
+## FACT CHECK
+
+Claim: "The users table has a 'last_login' column"
+
+Result: VERIFIED
+
+Evidence:
+- migration/20260315_add_last_login.sql:3 — `ALTER TABLE users ADD COLUMN last_login TIMESTAMPTZ`
+- pg_attribute confirms: users.last_login exists (type: timestamptz, notnull: false)
+```
+
+### Bad fact-check
+
+```
+The users table probably has a last_login column. I remember seeing it.
+```
+
+Problems: no evidence, "probably" = UNVERIFIED, no file:line reference.
+
+## Anti-patterns
+
+- **"Probably true"** — VERIFIED or not. Assumed-true = UNVERIFIED.
+- **URL alone as evidence** — weak; include the specific quote/line
+- **Compound claims not broken down** — "users table has id, email, last_login" → 3 claims
+- **Version-specific without version check** — "In Ktor 3.0, X works" → verify in changelog
+- **Memory substitution** — if source isn't accessible, mark UNVERIFIED
+
+## How to verify
+
+- [ ] Claim classified (code/DB/API/version/environment)?
+- [ ] Verification command run (grep/read/curl/webfetch)?
+- [ ] Result is VERIFIED / UNVERIFIED / CONTRADICTED?
+- [ ] VERIFIED claims have file:line or URL + quote?
+- [ ] Compound claims broken into atomic parts?
+- [ ] Version-specific claims include version number?
+
+## When triggered
+
+- Before `synthesize-findings` finalizes any assertion
+- Before code generation asserts behavior the researcher might be wrong about
+- When user says "are you sure?"
+- When `relire-critic` produces a RISQUE questioning an assertion
+- Automatically on assertions about DB schemas, imports, response shapes

package/assets/skills/research/research-forums/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: research-forums
+description: Fallback research source when official docs and GitHub issues are silent — searches StackOverflow, Reddit, Hacker News, and dev.to for community discussion. Lower priority than official sources but valuable for edge cases. Always followed by validate-source-credibility.
+allowed-tools: WebSearch
+context: fork
+agent: researcher
+---
+
+# research-forums — Community discussion fallback
+
+## What this covers
+Meta-research skill #3 of 6. When official docs + GitHub issues don't resolve the question, community forums often have the answer. But quality is uneven — `validate-source-credibility` is mandatory after this.
+
+## Core principle
+**Community knowledge supplements official docs, never replaces them.** If a forum answer contradicts official docs, trust docs.
+
+## Inputs
+
+```
+TECHNOLOGY: [lib name]
+VERSION: [version if relevant]
+QUESTION: [specific question]
+```
+
+## Process
+
+### 1. StackOverflow
+
+Queries:
+- `site:stackoverflow.com <lib> <feature> <version>`
+- `site:stackoverflow.com [<lib>] <question>`
+
+Priority signals:
+- Accepted answer (green checkmark)
+- Answer with > 50 upvotes
+- Answer from recognized maintainer
+
+### 2. Reddit
+
+Subs: `r/programming`, stack-specific (`r/typescript`, `r/golang`, `r/reactjs`, etc.)
+
+Priority signals: upvote ratio > 0.9, top comment explains tradeoffs.
+
+### 3. Hacker News
+
+- `site:news.ycombinator.com <lib> <feature>`
+- Priority: 100+ points + quality discussion
+
+### 4. dev.to, medium, maintainer blogs
+
+- Recent posts (< 18 months) usually more reliable
+- Look for author bio matching lib committer
+
+## Common patterns
+
+### Good forum research
+
+```
+## FORUMS RESEARCH — Vitest 3
+
+### StackOverflow
+- https://stackoverflow.com/q/12345 — 89 upvotes, accepted — vi.hoisted() required for mock variables in Vitest 3
+
+### Reddit
+- https://reddit.com/r/vitest/comments/abc — 45 upvotes, 23 comments — consensus: vi.spyOn > vi.mock for most cases
+
+### CONSENSUS
+- Use vi.hoisted() for variables referenced in vi.mock()
+- Prefer vi.spyOn over vi.mock for testing interactions
+
+### DISAGREEMENTS
+- Whether to use global vs per-test setup: SO says global, Reddit says per-test — depends on test isolation needs
+```
+
+### Bad forum research
+
+```
+Found some stuff on StackOverflow. People say use vi.mock.
+```
+
+Problems: no URLs, no upvote counts, no consensus analysis, no disagreement detection.
+
+## Anti-patterns
+
+- **Credibility not validated** — follow-up with `validate-source-credibility` on any non-official finding
+- **Stale answers accepted** — reject if older than 2 years unless fundamentals unchanged
+- **Forum > docs** — if forum answer contradicts official docs → trust docs
+- **Single-source treated as fact** — one SO answer is a hypothesis, not an answer
+- **No cross-reference** — corroborate with at least one other source before treating as fact
+
+## How to verify
+
+- [ ] ≥ 1 forum source found?
+- [ ] Each source has URL + upvote/engagement signal?
+- [ ] Staleness check performed (< 2 years)?
+- [ ] Consensus and disagreements identified?
+- [ ] validate-source-credibility will be invoked for non-official findings?
+
+## When triggered
+
+- `researcher` agent when `research-web-sources` and `research-github-issues` didn't resolve
+- User asks for "community perspective" or "what do other people do"
+- Niche library with sparse docs

package/assets/skills/research/research-github-issues/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: research-github-issues
+description: Searches GitHub issues for error symptoms and library API usage questions, detecting open issues, closed-with-workaround, or PR-in-progress status. Triggered when task involves an external library with a reported symptom. Invoked by the researcher agent as parallel research to official docs.
+allowed-tools: WebFetch, WebSearch
+context: fork
+agent: researcher
+---
+
+# research-github-issues — GitHub issues prior art
+
+## What this covers
+Meta-research skill #2 of 6. When official docs don't cover an edge case, GitHub issues often have the answer — someone else hit the same problem.
+
+## Core principle
+**Every bug you encounter, someone else encountered first.** GitHub issues are the world's largest debugging knowledge base. Check before investigating from scratch.
+
+## Inputs
+
+```
+TECHNOLOGY: [lib name + repo path, e.g. "ktor" / "ktorio/ktor"]
+VERSION: [exact installed version]
+SYMPTOM: [error message OR unexpected behavior description]
+```
+
+## Process
+
+### 1. Identify the repo
+
+From the lib name, resolve to the GitHub repo. Check `package.json` `repository` field for canonical URL.
+
+### 2. Search issues
+
+Queries (via WebSearch or WebFetch):
+- `site:github.com/<repo>/issues <symptom>`
+- `site:github.com/<repo>/issues <feature> <version>`
+
+Include both `is:open` and `is:closed`.
+
+### 3. Classify each relevant issue
+
+- **Open + active** → known problem, official fix pending → workaround needed now
+- **Closed + merged fix** → version N included fix; check if our version ≥ N
+- **Closed with workaround** → apply workaround (cite link)
+- **Closed as "not a bug"** → our usage is wrong (read the comment)
+- **Closed as duplicate** → follow to the parent issue
+
+### 4. Check linked PRs
+
+If an issue references a PR, check the PR:
+- Merged → fix is in release vX.Y
+- Draft → fix is in progress
+- Closed unmerged → fix abandoned, need workaround
+
+## Common patterns
+
+### Good GitHub issues research
+
+```
+## GITHUB ISSUES RESEARCH — @auth/core
+
+### Relevant issues
+| # | Title | Status | Our impact |
+|---|-------|--------|-----------|
+| #1234 | useSession throws on expired tokens | closed in v4.0.1 | Our version is 4.0.0 — upgrade needed |
+| #5678 | OAuth callback fails with PKCE | open | Matches our symptom — apply workaround |
+
+### Workarounds applicable
+- Add `skipCSRFCheck: true` to OAuth config — source: #5678 comment by maintainer
+
+### Fix version ranges
+- useSession fix in v4.0.1 — our version: v4.0.0 — suggest upgrade
+```
+
+### Bad research
+
+```
+Found some issues. One was closed. Should be fine.
+```
+
+Problems: no issue numbers, no status classification, no version check, no workarounds.
+
+## Anti-patterns
+
+- **No links** — every issue reference needs a URL
+- **Single comment as truth** — check for maintainer response + consensus
+- **Ignoring version ranges** — "fixed in 3.x" could mean 3.0 or 3.5 — read the changelog
+- **Treating community workaround as gospel** — verify it works; prefer official fix
+- **Empty result fabricated** — if no relevant issues found, report "no matches"
+
+## How to verify
+
+- [ ] ≥ 1 GitHub issue found and classified?
+- [ ] Each issue has URL, status, and impact assessment?
+- [ ] Version ranges checked (our version vs fix version)?
+- [ ] Workarounds documented with source links?
+- [ ] Linked PRs checked (merged/draft/closed)?
+
+## When triggered
+
+- `researcher` agent when TASK mentions a symptom / error message
+- Standard/Critical tasks using a library that's not purely internal
+- When `research-web-sources` docs are silent on an edge case
+- User request: "check if this is a known issue"

package/assets/skills/research/research-web-sources/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: research-web-sources
+description: Fetches official documentation via WebFetch and searches best practices via WebSearch for a specific library+version. Produces findings with version-stamped URLs and at least 1 anti-pattern. Invoked in the RECHERCHE step by the researcher agent.
+allowed-tools: WebSearch, WebFetch
+context: fork
+agent: researcher
+---
+
+# research-web-sources — Official docs + best practices
+
+## What this covers
+Meta-research skill #1 of 6. Fetches the primary source (official docs) + best-practice articles for a specific library+version. This is the highest-credibility research step — if official docs answer the question, stop here.
+
+## Core principle
+**Official docs are the source of truth.** If docs exist and answer the question, don't search further. Escalate to GitHub issues and forums only when docs are silent.
+
+## Inputs
+
+```
+TASK: [1-sentence description]
+TECHNOLOGY: [lib name]
+VERSION: [exact installed version — from avec-quoi-versioner]
+QUESTION: [specific question]
+```
+
+## Process
+
+### 1. Fetch official documentation
+
+- Primary: WebFetch the official docs URL
+- If docs for the exact version aren't available, fetch the latest + note the version gap
+- Focus on the specific API/feature in question — don't fetch whole doc site
+
+### 2. WebSearch for best practices
+
+Queries (run at least 2):
+- `[feature] [lib] [version] best practices`
+- `[feature] [lib] idiomatic way`
+
+### 3. Identify framework philosophy
+
+From docs: how does this framework WANT this problem solved? Not just what the API is — the intended approach.
+
+### 4. Extract anti-patterns (MANDATORY — at least 1)
+
+Queries:
+- `[lib] [feature] common mistakes anti-patterns`
+- `[lib] [version] pitfalls avoid`
+
+Cite at least one documented anti-pattern with source URL.
+
+## Common patterns
+
+### Good research output
+
+```
+## RESEARCH — React 19
+
+### FINDINGS
+- Server Components are the default in React 19 — no "use client" needed for static rendering
+- `use()` hook replaces useEffect for data fetching in client components
+- Source: https://react.dev/reference/rsc/server-components (React 19.0)
+
+### ANTI-PATTERNS À ÉVITER
+- useEffect + fetch waterfall — use Server Components instead — official docs
+- "use server" on components — this directive is for Server Functions, not components — react.dev
+
+### PHILOSOPHY DU FRAMEWORK
+React 19 pushes data fetching to the server. Client components handle interactivity only.
+```
+
+### Bad research output
+
+```
+FINDINGS:
+- React is good for UI
+- You can use hooks
+```
+
+Problems: no version, no specific API, no source URLs, no anti-patterns.
+
+## Anti-patterns
+
+- **No version stamp** — every finding must include the version it applies to
+- **Filling gaps with assumptions** — if docs don't cover it, say so explicitly
+- **Preamble** — return only the structured report, no "I found that..."
+- **Fetching entire doc site** — focus on the specific API/feature in question
+- **Minimum output not met** — ≥ 1 WebSearch result + ≥ 1 documented finding required
+
+## How to verify
+
+- [ ] ≥ 1 WebSearch performed?
+- [ ] ≥ 1 finding with version stamp?
+- [ ] ≥ 1 anti-pattern cited?
+- [ ] Source URLs present?
+- [ ] Framework philosophy stated (1-2 sentences)?
+- [ ] No preamble (structured report only)?
+
+## When triggered
+
+- `researcher` agent, RECHERCHE step on Standard/Critical tasks
+- User explicit request: "research <lib> <feature>"
+- When task mentions a library that's not fully understood
+
+## References
+
+- Tier-1 source credibility — validate-source-credibility skill
+- Ciel waterfall: research-web-sources → research-github-issues → research-forums → synthesize-findings

package/assets/skills/research/synthesize-findings/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: synthesize-findings
+description: Merges outputs from research-web-sources, research-github-issues, and research-forums into a single structured report with FINDINGS / ANTI-PATTERNS / PHILOSOPHY / API SURFACE / UNCERTAINTIES sections. Cross-references conflicting claims and deduplicates. Produces the final research deliverable.
+---
+
+# synthesize-findings — Merge research into one report
+
+## What this covers
+Meta-research skill #5 of 6. After parallel research skills have produced raw findings, this skill merges them into the single canonical format that the `researcher` agent returns.
+
+## Core principle
+**Conflicts are signals, not noise.** When two sources disagree, that disagreement is the most valuable finding. Surface it, don't hide it.
+
+## Inputs
+
+```
+WEB_RESULTS: [output of research-web-sources — or "none"]
+GITHUB_RESULTS: [output of research-github-issues — or "none"]
+FORUM_RESULTS: [output of research-forums — or "none"]
+CREDIBILITY_SCORES: [output of validate-source-credibility for low-tier sources]
+```
+
+## Process
+
+### 1. Deduplicate
+
+Same claim from multiple sources → merge, cite all sources ordered by credibility tier (highest first).
+
+### 2. Resolve conflicts
+
+When two sources disagree:
+- Higher credibility tier wins (official docs > forum)
+- Newer wins among same tier
+- Both recent Tier 1 but disagree → flag as uncertainty
+- Version-specific → align to installed version
+
+### 3. Populate canonical sections
+
+- **FINDINGS**: positive statements with version + source
+- **ANTI-PATTERNS À ÉVITER**: what NOT to do, with reason + source
+- **PHILOSOPHY DU FRAMEWORK**: how the framework wants this solved (1-2 sentences)
+- **API SURFACE**: verified imports / signatures / response shapes
+- **INCERTITUDES**: unresolved questions, conflicts, version gaps
+
+### 4. Apply credibility filter
+
+Any finding sourced only from Tier 4/5 without Tier 1/2 cross-reference → demote to INCERTITUDE.
+
+### 5. Enforce minimum gate
+
+Output is incomplete if ANY of:
+- 0 findings
+- 0 anti-patterns
+- No philosophy statement
+- No version stamp on any finding
+
+## Common patterns
+
+### Good synthesis
+
+```
+## FINDINGS
+- React 19 Server Components are the default — no "use client" needed for static rendering [v19.0]
+  Source: https://react.dev/reference/rsc/server-components (Tier 1)
+- `use()` hook replaces useEffect for data fetching [v19.0]
+  Source: react.dev (Tier 1) + SO #12345 89 upvotes (Tier 3)
+
+## ANTI-PATTERNS À ÉVITER
+- useEffect + fetch waterfall — use Server Components instead — react.dev
+- "use server" on components — directive is for Server Functions — react.dev
+
+## PHILOSOPHY DU FRAMEWORK
+React 19 pushes data fetching to the server. Client components handle interactivity only.
+
+## API SURFACE (verified)
+- `use()` — react.dev/reference/react/use
+- Server Components — `async function Component()` without "use client"
+
+## INCERTITUDES
+- Migration path from useEffect-based data fetching: docs show examples but no automated codemod exists
+```
+
+### Bad synthesis
+
+```
+React is good. Use Server Components. Don't use useEffect.
+```
+
+Problems: no version, no sources, no anti-patterns, no uncertainties.
+
+## Anti-patterns
+
+- **Inventing findings** — if research didn't produce a finding, leave it empty
+- **No citations** — every finding has a URL or file:line
+- **Empty INCERTITUDES** — suspicious. Research rarely resolves everything.
+- **Conflicts hidden** — when sources disagree, surface it as INCERTITUDE
+- **Output too long** — ≤ 500 tokens (researcher returns this to main session)
+
+## How to verify
+
+- [ ] All 3 research inputs consumed (or marked "none")?
+- [ ] FINDINGS have version stamps + source URLs?
+- [ ] ≥ 1 anti-pattern documented?
+- [ ] PHILOSOPHY stated (1-2 sentences)?
+- [ ] Conflicts surfaced as INCERTITUDES?
+- [ ] Output ≤ 500 tokens?
+- [ ] Minimum gate passed (findings + anti-patterns + philosophy + versions)?
+
+## When triggered
+
+- By `researcher` agent at the end of its research pipeline
+- User request: "summarize research findings on X"