Supabase pm-the-docs：文档创作 Frame/Shape 阶段的决策支持技能——受众、产品阶段与跨仓库范围判定

本文基于 Supabase 仓库中的 pm-the-docs 技能定义 及其两个参考文件 write-the-docs-checklist.md 和 universe-lookup.md 展开，讲解这个面向 AI Agent 的 "Docs-PM 决策支持" 技能如何工作：它负责在正式动笔写文档之前，替作者完成受众定位、产品阶段（alpha/beta/GA）、内容类型与信息架构位置的判断，以及在功能横跨多个产品仓库（CLI、Auth、migrations、platform 等）时如何跨仓库查证事实。读完本文，你将理解 Supabase 仓库如何用一套结构化的六阶段清单和"能力门控"（capability gate）机制，把"产品负责人会做的判断"沉淀为可被 Agent 复用的流程，并能判断何时该自行决策、何时必须升级给文档 PM。

pm-the-docs 在文档创作流水线中的定位

Supabase 仓库为文档创作流程提供了一组 Agent 技能，分别对应 Write the docs 清单 的六个阶段。CONTRIBUTING.md 中的技能总表说明了分工：

技能	清单阶段	用途
pm-the-docs	Frame / Shape	受众、产品阶段、跨切面范围判定（有 Supabase 组织权限时用 universe，否则走 OSS 路径）
ask-the-docs	Frame / Shape	apps/docs 架构、IA 布局、内容落位
write-the-docs	Draft	基于代码起草全新内容
edit-the-docs	Edit	重构与改进已有页面
test-the-docs	Draft / Self-review	在 Docker 隔离的本地栈中执行文档片段并产出验证报告
review-the-docs	Self-review / PR review	草稿自查与 PR 分诊/验证

pm-the-docs 的定位是"背稿前的 PM"：它不写内容。技能定义中的 "Not for" 部分明确划界——起草内容本身用 write-the-docs，重构现有页面用 edit-the-docs，运行代码片段用 test-the-docs，文档应用架构/IA 布局机制用 ask-the-docs。它专门回答的是 Frame（定位）和 Shape（塑形）两个阶段的问题：产品阶段是什么、给谁看、为什么做、内容类型怎么定、放在 IA 的哪个位置、前置知识是什么、这次发布是否横跨多个产品仓库。

调用时机

技能定义的 "When to invoke" 列出四类场景：

• 开始一个新的文档页面或一次发布，需要在动笔前说清楚产品阶段、受众和 "why"（Frame）；
• 需要为某个页面决定内容类型、IA 位置或前置条件（Shape）；
• 判断一次发布是否横跨多个产品仓库（CLI、Auth、migrations、platform……），此时要遵循 universe-lookup.md 的跨仓库查证流程；
• 不确定一个文档问题应该自行解决还是升级给文档 PM 签核。

回答范围/阶段/受众问题的六步流程

技能定义给出了一个明确的回答流程，每一步都可直接操作：

1. 读对应阶段的清单。打开 write-the-docs-checklist.md，找到 Frame 或 Shape 小节——那里的复选框精确列出了需要决定什么。
2. 读完该功能存在的所有上下文：关联的 issue/项目、PRD、已发布的代码或 PR。规则很硬：当代码和 PRD 不一致时，以代码为准（针对行为类论断）。
3. 涉及多服务时先过能力门控。当范围可能横跨服务（CLI、Auth、migrations、Dashboard、platform……）时，在敲定 Frame/Shape 之前必须先执行 universe-lookup.md 的 capability gate；universe 可访问就用它，否则走 OSS 路径，并记录你搜索过哪些仓库。
4. 直接回答清单问题：产品阶段、受众与 job-to-be-done、一句话 "why"、内容类型、IA 位置、前置条件。
5. 区分"确认的事实"与"推断"。事实是工单/PRD/代码中明确写出的；推断是你自己的最佳解读——必须显式标注，不能伪装成已定论。
6. 组织级悬而未决的决定，直说。如果某个决定在组织层面本来就开放（而非文档创作层面的判断），要说出来并指明该由谁决定，而不是编一个答案来"显得完整"。

六阶段清单镜像：What good looks like 与 Frame/Shape 详解

write-the-docs-checklist.md 是 "Write the docs" 清单的完整镜像，角色标注为 P = 产品、E = 工程、Docs = 文档团队。清单开篇即声明质量底线（"What good looks like"）：

• why 必须显式：读者能知道这篇文档解决什么问题、何时该用它，而不只是步骤；
• 内容类型是刻意选择的，且单页内保持一致；
• 受众和前置条件在开头就写明；
• 示例可运行且经过实测（命令、代码、预期结果）——用 /test-the-docs 对着 Docker 隔离的本地栈验证，而不是对着生产环境；
• 正确的阶段（如 GA）被明确声明，局限性诚实命名；
• 页面位于 IA 的正确位置，与相关页面双向链接；
• 术语和格式与现有文档一致。

阶段 1：Frame

对应技能是 /ask-the-docs（了解文档表面现状）与 /pm-the-docs（受众、阶段、跨切面范围，含 universe 查证）。Frame 阶段的复选框：

• [ ] P：陈述产品阶段（private/public alpha、beta、GA）
• [ ] P：点名受众及其正在完成的 job
• [ ] P：用一句话写清楚功能为什么存在（它解决的问题），而不只是它做什么

阶段 2：Shape

对应技能是 /ask-the-docs（IA 位置、架构、内容落位）。复选框：

• [ ] P：选择内容类型：tutorial（学习）、how-to（任务）、reference（查阅）、explanation（为什么）——不要在一页上混合类型（参考 Diátaxis 框架）
• [ ] P：决定页面在现有 IA 中的位置、哪些链接进出（避免孤儿页面）
• [ ] P：在开头列出前置条件和默认知识

清单的后续阶段 3（Draft，/write-the-docs）、4（Self-review，/review-the-docs + /test-the-docs）、5（PR review，/review-the-docs）、6（Keep it honest——保持发布清单中 "start on day 1" 文档门禁在上线过程中持续诚实）不属于 pm-the-docs 的职责，但该镜像文件将它们完整保留，使 Frame/Shape 的决定能与后三个阶段衔接。值得注意的一个交叉引用：Draft 阶段要求"跨仓库行为在可访问时经 universe 确认，否则走公开 gh search/具名产品仓库，且查证入口是 /pm-the-docs 而非 /ask-the-docs"——这与技能定义中"跨仓库产品查证属于 pm-the-docs，跨仓库文档应用架构才属于 ask-the-docs"的划界完全一致。

Ask the Docs PM：自行处理还是升级

镜像文件中的 "Ask the Docs PM" 小节与技能定义的 "Self-serve vs. escalate" 呼应：

自行处理（self-serve）：清单清晰、标准存在、你已知道产品阶段和受众。

升级（escalate）：范围或阶段不明确、需要评审路径、标准模糊、或发布文档触及跨切面表面（quickstarts、API keys、tutorials、onboarding、platform concepts）。

跨仓库产品查证：capability gate、universe 加速器与 OSS 路径

这是 pm-the-docs 最具操作性的部分，完整规则在 universe-lookup.md。核心前提：跨仓库确认对所有人都必需；私有元仓库 supabase/universe 只是一个"可选加速器"（有 Supabase 组织权限且最好有本地 clone 时使用），没有该权限的贡献者走 OSS 路径——那是成功结局，不是失败。

能力门控流程

在任何 universe clone 或 submodule 命令之前，先跑这个门控：

flowchart TD
  start[需要跨仓库事实依据]
  clone{"本地 universe 根目录存在?"}
  ghApi{"gh api repos/supabase/universe 成功?"}
  useUniverse[使用 universe clone + 在 repos/ 中 rg]
  ossPath[OSS 路径: 公开 gh search + 关联的产品仓库]
  start --> clone
  clone -->|是| useUniverse
  clone -->|否| ghApi
  ghApi -->|是, 有 Supabase 组织权限| useUniverse
  ghApi -->|否, 404/403| ossPath

第 1 步：检查本地 clone？ 按顺序解析 universe 根目录（不要在提交的文件中硬编码机器相关的绝对路径）：

1. $SUPABASE_UNIVERSE_ROOT（若已设置）
2. $HOME/GitHub/supabase/universe

UNIVERSE_ROOT="${SUPABASE_UNIVERSE_ROOT:-$HOME/GitHub/supabase/universe}"
[[ -d "$UNIVERSE_ROOT/.git" || -f "$UNIVERSE_ROOT/.git" ]] && echo "local universe ok"

该 checkout 存在 → 走加速器路径（跳过 gh api 探测）。

第 2 步：否则探测组织权限（只读，不 clone）：

gh api repos/supabase/universe -q .full_name

结果	下一步
成功（返回 supabase/universe）	加速器路径：可以 --recurse-submodules clone（或请用户代做），然后搜索
404、403 或其他失败	仅 OSS 路径——不要对 universe 执行 git clone 或 git submodule update

OSS 路径（永远有效）

当门控判定 universe 不可用时：

• 搜索公开代码：gh search code --owner supabase '<query>'（加上工单中点名的其他公开 owner）；
• 阅读已 checkout 的、或从 Linear/PR 链接过来的任何产品仓库；
• 足够时在树内（supabase/supabase）源码中查找优先；
• 在 Frame/Shape 总结中记录 universe: unavailable (OSS) 并列出用到的公开来源。

规则最后强调：永远不要把 universe 不可用当作阻塞项或不完整的 Frame/Shape。

加速器路径：在 universe 可访问时

优先使用已有本地 clone，只在门控通过后才 init/update submodule：

cd "$UNIVERSE_ROOT"
git submodule update --init --recursive

私有 submodule（platform、branching）可能需要 PAT；失败时记录缺口，用公开 submodule 加 OSS 搜索路径继续。从 universe README 的 "Finding your way around" 表出发，然后在相应 submodule 内用 rg 搜索，定位表如下：

找什么	从哪开始
Schema、扩展、RLS	repos/postgres/、repos/postgrest/、repos/pg-toolbelt/
Auth 流程	repos/auth/、repos/supabase-js/ 下的 auth-js
Realtime / Storage / Edge Functions	repos/realtime/、repos/storage/、repos/edge-runtime/
Dashboard / Studio	repos/supabase/apps/studio
Management API / 托管基础设施	repos/platform/（私有）
CLI、本地开发、config.toml	repos/cli/
文档与自托管 Compose	repos/supabase/（apps/docs、docker/）

范围不明时，用紧密的正则在已初始化的 repos/** 中搜索，而不是通读整棵目录树。

在 Frame/Shape 中的使用方式

1. 点名发布可能触及的产品表面（CLI、Auth、migrations、Dashboard……）；
2. 跑能力门控；
3. 把表面解析到仓库（universe submodule 或 公开搜索/关联 checkout）；
4. 用一次简短搜索确认行为在一个仓库还是多个仓库中；
5. 在 Frame/Shape 总结中记录：门控结果（universe: available 或 universe: unavailable (OSS)）、查阅过的仓库、跨切面还是单仓库、以及缺口。

并且始终区分确认事实与推断。

与相邻技能的协作边界

从源码结构看，六个文档技能构成一条有明确交接点的流水线，pm-the-docs 处于最前端：

• write-the-docs 的 Phase 1（Gather）明确写着：当 Linear 工单缺失且没有既有 Frame/Shape 产品意图输出时，停止起草，交接给 pm-the-docs（Frame）和 ask-the-docs（Shape/IA 未定时），"产品意图存在之后才恢复"——即 Draft 技能内部不允许自己跑 Frame/Shape；行为横跨服务时，它同样要求走 pm-the-docs → universe-lookup 的能力门控，而不是 ask-the-docs。
• test-the-docs 的 "When to invoke" 与 Core rules 表明它消费 Draft 产出、在 Docker 隔离沙箱中执行片段并产出验证报告，与 pm-the-docs 无职责重叠，仅在 "Related skills" 中互为索引。
• ask-the-docs 专注于 apps/docs 应用本身（MDX 管线、federated docs、build pipeline、GraphQL 端点等），"产品"层面的跨仓库查证被刻意留在 pm-the-docs 一侧，避免两个技能的知识域互相污染。

适用前提与实践要点小结

• 这套流程适用于使用 AI 编码代理（Claude Code、Codex 或任何读取 .agents/skills/ 的 agent）的 Supabase 文档贡献场景；技能规范文件位于 .agents/skills/，apps/docs/CONTRIBUTING.md 说明 .claude/skills 是指向该目录的 Git 符号链接，Claude Code 中可用作 /pm-the-docs 等斜杠命令。
• 三条硬性规则值得单独记住：代码与 PRD 冲突时以代码为准；universe 权限缺失不是失败，OSS 路径是永远有效的完整方案；组织级未决问题不要代答，指名该由谁决定。
• 若要在当前仓库中继续深入，可对照阅读：write-the-docs-checklist.md（六阶段清单与 "What good looks like" 全文）、universe-lookup.md（门控与查证规则全文）、write-the-docs 技能（Draft 阶段的四个输入与内容类型门控）、test-the-docs 技能 及其 sandbox/run.sh（验证沙箱的生命周期驱动），以及 apps/docs/CONTRIBUTING.md 中的技能总表与文档写作规范。