القائمة
Use when changing any retikz apps/docs content, route data, i18n, demo, SourceLinks, or schema reference before loading the matching page-type skill.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when retikz needs multiple independent LLMs to review the same fixed code, ADR, implementation plan, test contract, commit, or working-tree snapshot before a gate or delivery decision.
Use when an Alpha ADR needs a pre-implementation capability gate, or a Beta milestone needs code-based completeness and package-boundary auditing.
Use when planning a retikz architecture direction, version roadmap, or alpha feature that may need a long-lived ADR before implementation.
Use when retikz work is primarily refactoring, reorganization, renaming cleanup, modularization, or internal simplification and should start from a reviewed implementation plan before code changes.
Use when retikz implementation, adversarial testing, and docs are complete, and an ADR or beta TODO needs changelog, contract consistency review, roadmap status updates, or final human acknowledgement.
Use when retikz alpha-stage work needs to execute an ADR-backed feature through long-lived design, reviewed implementation planning, code, adversarial testing, documentation, and wrapup.
| name | docs-doc-principle |
| description | Use when changing any retikz apps/docs content, route data, i18n, demo, SourceLinks, or schema reference before loading the matching page-type skill. |
本 skill 只保留所有文档任务都需要的共享契约。页型结构、controls、Reference 和预览源码规则按任务动态加载，不在这里重复。
apps/docs/AGENTS.md 与本 skilldocs-doc-component；Standard Tier 2 composite 组件页继续读 docs-doc-standard-compositedocs-doc-extensiondocs-doc-exampledocs-doc-groupdocs-doc-conceptdocs-doc-blogdocs-doc-control<ComponentPreview> 的源码视图、多文件或数据文件：references/component-preview.mdreferences/demo-visual-language.md<ZodSchema>：references/reference-pages.mddocs-figure-contract；解释实现流程再读 docs-figure-logicdocs-doc-review不要为“可能用到”预读所有资源；按页面真实内容加载。
一个普通页面通常同时涉及：
apps/docs/src/modules/docs/
contents/<moduleId>/<sectionId>/<pageId>/index.{zh,en}.mdx
data/<moduleId>.ts
apps/docs/src/i18n/locales/{zh,en}.json
URL 段、data 节点 id 与 contents 目录段必须一致。新增或移动页面时同步正文、data、i18n 和全仓站内链接；不要只移动文件。
docs-doc-blog 拥有label 使用完整 i18n pathindex.{zh,en}.mdx，不默认重定向首个 child默认读者会 React / TypeScript，但不熟 TikZ、IR、几何术语和项目历史。先讲场景和行为，再命名概念；先给用户路径，再放可跳过的内部机制。
写作前从当前实现、测试和能力域 completeness 文档确认：
正文按能力语义组织，不按 prop 或视觉变体数量组织。边框色、背景色、线宽、透明度、字号等通用视觉属性只简要说明，并收进 API 表或一个 controls playground；只有改变语义、结构、组合、所有权、错误或编译机制的差异才值得独立章节或静态 demo。
# 标题frontmatter.description 要能脱离页面独立说明根问题、核心职责或使用入口，不写“本页介绍”<Comparison>，隐藏后正文仍自洽docs-doc-blog 定义用户正文优先展示 DSL（如 <Layout>、<Node>、<Path>、<Draw>）。普通用法页不为了“完整”重复 IR JSON 或编译器内部；IR 只在架构、持久化、AI 接入或必须用它解释公开行为时出现。
所有功能 demo 和叙述图都用 retikz 自绘：同级 demo + <ComponentPreview>。不使用截图、PNG/JPG/GIF、Mermaid、Excalidraw 或 draw.io 代替功能展示。叙述图默认 hideCode；可复制用法保留源码。
关系、流程或架构图的具体画法由 docs-figure-contract 拥有，本 skill 只决定是否需要图。
API 参考按需使用“公开导出概览 → 核心契约 → 重要闭合集合”：
文档里的函数、类型和常量名必须是从所属包公开入口可导入的真实标识符。不要把概念简称、内部类型或 owner 深层 export 冒充公共 API。写 API 表前沿着“组件 Props / schema → owner barrel → package root”核对；宿主组件页还要检查同 owner barrel 的 Provider、Context、hook 与 helper，避免漏掉用户完成任务所需的伴随导出。
共享或继承 props 不在每页复制完整字段表：用一行说明公开共享契约及其职责，并链接到唯一权威页；本页只展开新增或重定义的字段。
手写 API 表遇到对象类型时：
- field?: Type；描述列第一行写整体语义，后续逐行与属性同序、同数、一一对应| 边界换行，不把整条类型包成跨行灰块<ApiValues name="PublicConstant" /> 显示常量名并在悬浮、聚焦时列出具体值；注册表直接引用公开常量，MDX 不手写重复值，描述列仍说明该集合的语义机制说明先写用户可观察行为，再用 <SourceLinks> 给直接实现入口。每项 path 使用仓库相对路径，行号范围最小且必须仍支撑正文结论；源码链接不能替代解释。
正文最大宽度 800px，表格单元格默认不换行。表格优先 3 列以内；过长内容用 <br /> 或拆出正文。MDX 表格中的 union | 写成 \|，同一字段的多个类型放在同一行内用 <br /> 分隔。
新增叶子页时同步：
apps/docs/src/i18n/locales/{zh,en}.jsonapps/docs/src/modules/docs/contents/.../index.{zh,en}.mdxapps/docs/src/modules/docs/data/<moduleId>.ts分组落地页、扩展页和 blog 的额外元数据由对应页型 skill 定义。
introduction / get-start 等入口页按读者任务组织，不强套组件或示例页结构，但仍服从本 skill 的三处协同、双语、写作权重与验证规则。
先运行机械一致性检查，再做页面语义和视觉判断：
node .agents/skills/docs-doc-principle/scripts/check-doc-integrity.mjs --scope <module-or-subtree>
脚本检查普通页面双语配对、双语标题层级、站内路由与锚点、SourceLinks 文件/行号、ComponentPreview 主 demo 文件；它不能判断 API 描述是否符合实现、SourceLinks 是否真正支撑结论、demo 是否可读，因此不能替代源码核对和浏览器检查。
按改动范围选择最小有效验证：
| 改动 | 最小验证 |
|---|---|
| 纯 MDX 正文、表格、站内链接 | 完整性脚本 + Prettier + git diff --check + 关键页面/链接 |
| frontmatter、标题、MDX 组件、LinkedCard | 上述检查 + 浏览器确认 zh/en、TOC、菜单 |
| demo、data、helper、MDX import | 上述检查 + docs tsc --noEmit + 浏览器确认 demo |
| docs data、i18n、schema registry | 上述检查 + docs tsc --noEmit + 对应路由/Schema |
| CI 或产物等价验证 | docs build |
新建 *.demo.tsx 时按 ComponentPreview 按需契约 的新文件规则验证，不依赖旧 dev session 的热更新状态。
命中任一条件即视为文档大改：新增页面；重写页面主线或章节顺序；新增或替换 demo、controls、API 表；同时对多个小节或页面做语义调整。纯错字、链接、格式和局部措辞修改不触发。
docs-doc-review完成前还要人工确认：
Demo ... not found 或 Unknown schema