PM 操作手册

你是谁 / 本手册范围

你是 PM（产品经理）：接业务需求、把它转成一份合约 / 后台 / 前端 / QA 都能照做的结构化文档，推到 docs-site 供团队拉取。本手册只讲 PM 专属的 skill 流程（需求收集 → 分析 → 拆分 → 角色文档 → 每日看板）。全员通用的环境准备、代码提交、文档推送、团队通知、Bug 管理等请先读 common.md，再回这里看专属流程。

本手册假设你已按 common.md 跑过 /docs-init + /skills-install。

首次配置

1. 初始化 `.docs.env`

跑 /docs-init，把管理员通过安全渠道发给你的配置整段粘贴进 .docs.env。管理员会用 /member-token-gen 为你签发。PM 角色必须包含以下字段（完整字段表见 common.md 的「环境准备」章节）：

# 顶层（monorepo 迁移后统一单 token）
GITLAB_BASE_URL=https://gitlab.ironetwork.com
GITLAB_DOCS_BRANCH=main
GITLAB_DOCS_PROJECT_ID=213              # docs-site 仓库，所有项目共用
GITLAB_DOCS_WRITE_TOKEN=glpat-xxxx      # 读 + 写 content/{project}/**

# daily-log / daily-board 用（写 content/manage/**）
DOCS_SITE_PROJECT_ID=213
GITLAB_DOCS_SITE_WRITE_TOKEN=glpat-xxxx

# 你的身份
MEMBER_NAME=your_name
MEMBER_TG=@your_tg

# Skills 安装用
SKILLS_ROLE=pm
SKILLS_COMMON_TOKEN=glpat-xxxx
SKILLS_PM_TOKEN=glpat-xxxx

# Telegram 通知（bot token 全局一个；chat id 按项目）
TELEGRAM_BOT_TOKEN=bot123:xxx
# 成员名单已迁移到 docs-site/content/manage/team.md 单一真相源（本地不再保留 TEAM_MEMBERS）

# 图床（bug-add 截图上传用）
LSKY_BASE_URL=https://bugs.ironetwork.com
LSKY_TOKEN=xxx

# 按项目一段
[pay-fi]
GITLAB_PROJECT_ID=101                   # notify 场景引用
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=1

[fomo-pad]
GITLAB_PROJECT_ID=102
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=2

2. 安装 PM 角色 skill 包

/skills-install

SKILLS_ROLE=pm 会自动拉 skills-common + skills-pm 两个仓库
完成后按提示重启 Claude Code

3. 自检 PM 必需字段

PM 特有的必填项：顶层 GITLAB_DOCS_WRITE_TOKEN + DOCS_SITE_PROJECT_ID + GITLAB_DOCS_SITE_WRITE_TOKEN（写成员日志 / 每日看板）+ 至少一个项目段的 TELEGRAM_CHAT_ID（通知团队） + LSKY_BASE_URL / LSKY_TOKEN / LSKY_STRATEGY_ID（/bug-add 上传截图）。缺任一项，对应 skill 会在 HARD-GATE 阶段拦下来并指名缺什么。

日常工作流

PM 日常只需记住一个入口：/pm（中文菜单，会路由到具体 skill）。下面六个场景覆盖 95% 的工作。

场景 A：接到新需求（完整流程）

什么时候用：从零接一个新需求，走全套流程。

触发命令：

/req-collect         # 对话收集，AI 逐步引导
/req-analyze <id>    # 业务可行性 + 数据流 + 角色检测
/req-split <id>      # 拆 INVEST 用户故事（涉合约 FEAT 标 contract_pending）
/role-split <id>     # 生成各角色 business 需求文档
/req-changelog       # 记录本次文档变更
/docs-push-gitlab    # 推到 docs-site（选 1. requirements）
/notify              # 选场景 1 「需求文档已更新」

关键输入：

/req-collect：业务描述（自然语言即可）、项目选择（多项目时）、优先级 P0-P3、AI 逐项追问边界值 / 异常时逐条答
/req-analyze：确认可行性六维（价值 / 资源 / 时间 / 影响 / 依赖 / 风险），确认数据流，确认涉及角色 involves: [contract, backend, frontend, qa]
/req-split：确认故事拆分建议；financial 类故事触发 Hard Gate，公式 / 边界值 / 异常三项全部 ✅ 才能写文件
/role-split：所有 story 的 harness_gates_passed: true 才能继续；按 involves 过滤，只生成涉及角色的文档

产出结果：

docs/{project}/requirements/FEAT-{NNN}-{name}/
  overview.md              # /req-collect + /req-analyze 产出
  story-01.md  story-02.md # /req-split 产出
  contract.md              # /role-split 产出（涉合约时，复用 contract-req-gen 结果）
  backend.md  frontend.md  # /role-split 产出（按 involves 过滤）
  qa.md                    # 始终生成

docs/{project}/progress/
  backend.md  frontend.md  SUMMARY.md   # /req-split 第 5.8 步自动初始化

docs/CHANGELOG.md          # /req-changelog 追加一条

/docs-push-gitlab 把本地 docs/{project}/** 推到 docs-site content/{project}/**，约 30 秒后 https://team-docs.pages.dev/{project}/requirements/... 可见。

场景 B：一键串全流程（推荐）

什么时候用：不想一条条记命令 / 中途中断需要续跑。

触发命令：

/pm-docs-gen

关键输入 + 断点续跑机制：

/pm-docs-gen 扫 docs/{project}/requirements/*/overview.md 的 frontmatter status 字段，按状态自动路由：

当前 status	下一步	说明
`draft`	`/req-analyze`	已收集未分析
`analyzed`	角色重确认 → `/req-split`	进入 split 前可调整 involves，进 split 就不能再调了
`split`	`/role-split`	已拆故事，未生成角色文档
`roles_done`	增量更新模式	见场景 C

中途中断（如 AI 发现边界值需要重问 PM）后，重跑 /pm-docs-gen 会自动接着上次停下的地方继续，不需要重新开始。

产出结果：同场景 A，但所有步骤由一条命令自动串联。PM 只在确认点回答 Y/N 或修改建议。

场景 C：增量更新已有需求

什么时候用：需求 status=roles_done 后，某个角色文档需要重生成（业务规则变了 / 故事改了 / QA 发现 contract.md 漏了事件）。

触发命令：

/pm-docs-gen
# 在列表里选中 roles_done 的 FEAT，自动进入增量更新模式

关键输入：从 6 个选项中选更新范围：

1. 只重新生成前端文档（frontend.md）
2. 只重新生成后台文档（backend.md）
3. 只重新生成合约文档（contract-req-gen 完整流程）
4. 只重新生成 QA 文档（qa.md）
5. 重新生成所有角色文档
6. 从需求拆分重跑（用户故事有变化时选此项）

不在 involves 里的角色选项会显示灰色「不在本次需求范围内」。

产出结果：只有被选中的 {role}.md 被重写，其他文件不动。完成后 AI 会问「是否立即推送 + 通知」，选 1 直接串 /docs-push-gitlab + /notify。

场景 D：每日下班生成看板

什么时候用：每日 PM 收工前跑一次，聚合全团队当日产出供第二天早会 / 复盘用。

触发命令：

/daily-board              # 生成今日看板
/daily-board 2026-04-18   # 补跑指定日期（月末补档）

关键输入：

无必填参数。skill 会自动：
1. 从 docs-site content/manage/team.md 拉 team-roster（校验当前 MEMBER_NAME 的 role 为 pm）
2. 对 roster 里每个成员 GET content/manage/members/{name}/{date}.md，提取「今日完成 / 明日计划 / 阻塞」
3. 对每个项目扫当日新增 FEAT / Bug 状态变化
4. 按 6 节结构生成 markdown（功能分配 / 今日新增需求 / 进行中 / 完成项 / 阻塞项 / 成员日志链接 / 毛选三论复盘）
第 7 节「毛选三论复盘」留骨架，PM 线上填充

产出结果：

docs-site: content/manage/daily/{YYYY-MM-DD}.md
在线地址：https://team-docs.pages.dev/manage/daily/{YYYY-MM-DD}

写入走乐观锁 PUT-refetch-retry（3 次重试，冲突时按 section 做 deep_merge，不整文件覆盖），避免多 PM 补跑同日文件互相冲掉。不发 Telegram。

场景 E：多人协作拉最新需求

什么时候用：团队有多个 PM，PM B 要拉 PM A 刚推的最新需求继续编辑；或 PM 切换多项目想同步一批项目的 requirements。

触发命令：

/pm-docs-pull                    # 交互选项目
/pm-docs-pull --project pay-fi   # 指定单项目
/pm-docs-pull --all              # 全量同步所有项目

关键输入：多项目时选要拉的项目；对于「远程已更新」的文件，按编号或 all / skip 选是否覆盖本地。

产出结果：

目标是 docs/{project}/requirements/（PM 生产目录，不是 .docs/ 缓存）
差异拉取：新增文件直接下载；远程更新的文件询问覆盖；本地新建还没推的保留不动
输出摘要：📥 新增 N / 🔄 覆盖 M / ⏭️ 跳过 K / 📝 保留 J

场景 F：补记 silent-day 日志

什么时候用：当天没推文档 / 没部署 / 没修 bug（研究日、开会日、阻塞等待日），/notify 不会被触发自然也不会自动追加日志。或者想补一条漏记的工作。

触发命令：

/daily-log add   "{今日完成描述}"   # 追加一行
/daily-log plan  "{明日计划}"       # 覆盖「## 明日计划」小节
/daily-log block "{阻塞描述}"       # 覆盖「## 阻塞与问题」
/daily-log                          # 无参数 → 交互式三连问

产出结果：通过 GitLab Files API 写 docs-site content/manage/members/{MEMBER_NAME}/{YYYY-MM-DD}.md，乐观锁 + 409 最多 3 次重试。不发 Telegram。第二天 /daily-board 会自动把这条日志聚合进看板。

状态追踪你这边能做什么：`/story-status` + 首次启用

PM 是状态追踪的”终点拍板者”，也是首次启用 / 历史回填的触发者。

你的命令：

/story-status FEAT-002 US-01           # 把该 story 的 PM 列推到「已完成」（最常用）
/story-status FEAT-002 all             # 该 FEAT 你能拍板的所有 story 一并推

你的权限： 推进「PM」列 未开始 → 已完成。前置：QA 列 = 已完成 或 QA 列 = —。QA 缺位兜底：当 QA 仍未推进时，PM 仍可强推 PM 列；skill 在确认 diff 中显式标注 ⚠️ QA 仍未开始；请确认 PM 已亲自验收。仅前进、不回退、不旁路。

首次启用 / 历史回填（每个项目一次）：

在该项目目录跑一次 /role-split <任一 FEAT-id>。role-split 检测到远程 content/{project}/status.md 不存在时会自动扫描本地全部 FEAT 一次性 bootstrap，所有 story 初始 未开始，PM 列每个 story 默认就有（不依赖 involves）。后续日常 role-split 进入”单 FEAT 增量”模式。详细列结构见 common.md 状态追踪节。

查看： team-docs.pages.dev/{project}/status（项目侧边栏 📊 项目进度）

通用 skill 速查

全员通用 skill 的详细规则看 common.md，PM 本地最常用三个：

命令	PM 的典型使用场景
`/docs-push-gitlab`	每次生成 / 更新完需求文档都要推一次，选 `1. requirements`。推 bug 则选 `5. bugs`。推送前会并发冲突检测，发现 72h 内他人修改会逐文件询问。门控（仅 requirements）：推送前自动扫描每个 FEAT `overview.md` 的 `status` 字段——只有 `roles_done` 才能推；其他状态（draft / analyzed / split）的 FEAT 全部文件被自动剔除并报告，其余 FEAT 正常推送。先跑完 `/role-split` 再回来推
`/notify`	推完 requirements 选场景 1；推完 bugs 选场景 5；不主动发 `/notify` 也会触发日志自动追加，但团队看不到更新，建议每次推完都发一次
`/bug-add` + `/bug-update`	PM 在早会 / 复盘发现问题时当场录 bug；要追进度时改状态（`/bug-update BUG-XXX status=in-progress`）。录完记得 `/docs-push-gitlab` 选 `5. bugs` + `/notify` 选场景 5

常见问题 / 故障排查

Q1：/pm-docs-gen 读不到需求，或刚建好的 FEAT 列表里不显示？

检查 docs/{project}/requirements/FEAT-{NNN}-{name}/overview.md 是否存在且 frontmatter 有 id / status 字段。skill 靠扫这个目录和 status 字段列出选项。如果是刚做完 /pm-docs-pull，也可能是本地缓存没刷新 — 重跑一次 /pm-docs-gen 即可。

Q2：/req-split 卡在 Hard Gate 写不了文件？

只有 formula_type: financial 的故事会触发 Hard Gate，且要求三项全 ✅：formulas_confirmed + boundary_values_confirmed + exceptions_confirmed。回到 Step 4.2 / 4.3 / 4.4 把「⚠️ 待确认」改成 Y 或直接填修改内容即可。business 类可以 skip 边界值；none 类整个跳过。

Q3：/role-split 报 [HARNESS GATE] 拦住不让生成？

某个 story 的 harness_gates_passed: false（大多是老格式 story 缺字段）。按提示 /req-split <requirement_id> 重跑一次审阅流程，PM 会再被问一轮公式 / 边界值 / 异常，三项确认后 gates 会自动翻 true。

Q4：/daily-board 第 7 节「毛选三论复盘」为啥留空？

这一节要求 PM 主观复盘当日主要矛盾（矛盾论）、实践验证（实践论）、长期坚持（持久战），不由 AI 填。骨架生成后 PM 直接在 https://team-docs.pages.dev/manage/daily/{date} 对应 GitLab 源文件上编辑，或本地改完重跑 /daily-board 覆盖（走 deep_merge，保留 AI 生成部分）。

Q5：多项目切换时，/pm 菜单没问项目就直接走了？

/pm 在 .docs.env 只有一个 [project] 段时自动使用该项目；多项目段会在菜单前先问。如果你手动新增了一个 [project] 段还没生效，检查是否在 PM skill 启动的项目目录下（.docs.env 跟随项目根目录）。

PM 操作手册

PM 操作手册

你是谁 / 本手册范围

首次配置

1. 初始化 .docs.env

2. 安装 PM 角色 skill 包

3. 自检 PM 必需字段

日常工作流

场景 A：接到新需求（完整流程）

场景 B：一键串全流程（推荐）

场景 C：增量更新已有需求

场景 D：每日下班生成看板

场景 E：多人协作拉最新需求

场景 F：补记 silent-day 日志

状态追踪你这边能做什么：/story-status + 首次启用

通用 skill 速查

常见问题 / 故障排查

相关文档链接

1. 初始化 `.docs.env`

状态追踪你这边能做什么：`/story-status` + 首次启用