optimization

Author or revise a public documentation guide under documentation/guides/ for the Optimization SDK Suite. Covers the guide archetypes (integration, decision, supplemental recipe), the teach-first quick-start-then-deepen structure, the copy-vs-adapt example labels, the guides directory routing index, and the self-review checklist that keeps guides consistent. Use when writing a new integration guide, rewriting an existing one, adding a decision or recipe guide, editing the guides README index, reviewing a guide for structure and voice, or editing any file under documentation/guides/. Triggers on "write a guide", "integration guide", "getting started guide", "documentation/guides", "choosing-the-right-sdk", "guide archetype", "quick start", "rewrite the guide", "guide TOC", "Copy this / Adapt this". Not for concept docs under documentation/concepts (those own deeper mechanics), not for package or implementation READMEs, and not for generated TypeDoc under docs/.

Maintain the internal SDK knowledge base under documentation/internal/sdk-knowledge/ — the layer of verified SDK behavioral facts (defaults, fallbacks, ownership, lifecycle, cross-runtime semantics) that each carry a source pointer into packages/**/src. Covers the three-artifact split (guides teach, this KB records verified facts, the authoring skill holds principles — facts never go in a skill), the _template.md skeleton every per-SDK file copies, and capturing shared facts once in shared/ so guide families reuse one canonical wording. Use when adding or editing a per-SDK knowledge file, recording an SDK API you just verified against source while doing other work, reading the KB before re-grepping the SDK, keeping it in sync after the SDK changes, or editing any file under documentation/internal/sdk-knowledge/. Triggers on "sdk knowledge", "internal knowledge base", "record verified facts", "source pointer". Not guide prose and not the authoring skill.

Verify a documentation guide's load-bearing SDK claims — the technical-foundation review role — splitting each into interface vs. behavior. Interface claims (symbol existence, signature, prop names/types, optionality, unions, return shape, import path) are checked directly against the types in packages/**/src — a cheap, self-verifying lookup. Behavioral claims (fallback contracts, dynamic-render forcing, batching, defaults, identifier ownership, cross-SDK semantics) are checked against verified facts in documentation/internal/sdk-knowledge/ and must NOT be re-traced from source; a behavioral claim with no backing fact is escalated to sdk-knowledge-authoring. Use as the third authoring role (writer → newcomer reviewer → technical-foundation reviewer), after a guide is drafted or refreshed, or to fact-check a specific claim. Triggers on "technical review", "verify against source", "fact-check the guide", "is this API real", "foundation review". Not reader-experience review (guide-newcomer-review) and not prose

Derive verified SDK facts from source into the internal knowledge base under documentation/internal/sdk-knowledge/ — the comprehension step of the docs pipeline. This is the one expensive step that reads packages/**/src; the knowledge base memoizes it so guides and reviews read facts instead of re-comprehending code. Two modes: BOOTSTRAP (read an SDK's whole public surface into a new KB file, once) and INCREMENTAL (a source change → re-verify only the facts whose pointers hit the changed files, plus capture new/removed exports in that area). Use when a source PR touches packages/**/src, when a new SDK needs a KB file, or when a guide/review escalates a missing fact. Triggers on "update the knowledge base from source", "source changed", "bootstrap KB", "which facts changed", "capture new exports". Not guide prose (optimization-guide-authoring), not the format rules (sdk-knowledge-maintenance), not reader review (guide-newcomer-review).

Review a documentation guide under documentation/guides/ as an average developer with little or no personalization background — the guide's actual target reader. Catches undefined jargon, skim-mode triggers, unperformable verify steps, and forward references that assume knowledge the reader does not have yet. Reports reader-experience findings; it does not verify SDK facts against source (that is guide-source-verification) and does not restructure prose (that is optimization-guide-authoring). Use when reviewing a new or rewritten guide before it ships, as the second of the three authoring roles (writer → newcomer reviewer → technical-foundation reviewer). Triggers on "newcomer review", "review this guide", "read it cold", "average developer review", "docs reviewer".