gplan-2/.zcode/skills/doc-design/SKILL.md

name, description

name	description
doc-design	g-plan2（Dungeon Sweeper）五段流水线第二段的文档设计入口。当用户要求做某事项的文档设计、发起系统设计讨论、把设计定稿写进 GDD、或要求处理迭代反哺点清单（落反哺点/反哺点裁决写入）时使用。流程：从待办清单取条目校验所属设计线与状态→用户主导的设计讨论（待裁点全案并列、禁代裁）→待裁点清零＋用户点头后定稿写入 GDD→待办清单状态推进「文档设计已闭合」→跑流水线闸。兼任反哺点写入与 design/engineering/ 规约类文档修订。仓库在 D:/code/g-plan2。

doc-design——文档设计段入口（g-plan2 五段流水线）

你在五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 design/engineering/process-conventions.md §2）的第二段做文档线设计：把一件登记在册的事，经用户主导的设计讨论，定稿成 GDD 文档（或 design/engineering/ 规约修订）。条目格式与状态机权威=design/engineering/doc-conventions.md §12，动笔前先读它。

批性质与共同纪律（先读）

• 仓库路径：项目在 D:/code/g-plan2，本文路径相对它。
• 本技能属工程/文档改动批（直改类）：可写 design/ 目录与 roadmap.md（这正是本批产出）；禁跑 tools/run_all_gates.sh 全套（不带参数档）与任何游戏测试；收尾＝手动跑 --docs（文档域闸），全绿后按车道合回，合回落地 post-merge 钩子推送触发远端 CI 验证（文档批＝文档域秒级闸），结果不等待、不落地，随时用 tools/ci_check.sh <合并提交> 现查（合回零等待，process-conventions §1 第 3 条）。tracked 改动默认只许落在 design/ 与 roadmap.md；规约修订批（用户发令改流程规约时）写面可含 AGENTS.md、design/engineering/ 规约与 tools/ 闸件，按批列明写面，闸仍跑 --docs。
• 车道铁律：本技能写面全是 tracked 文档面——一切改动走独立 worktree（建区粒度＝回合，会话单区等细则见 design/engineering/process-conventions.md §1），收口＝冻结→件核→并 master→主区 git merge --no-ff→删区；.zcode/ 与 .qoder/ 技能文件不入 git，主区直改。触及代码面（game/ 下非 .md）的改动不属本技能面。
• 特批两段式：只有用户明示才能跳过本技能流程中的某步（如跳过设计讨论直接落定稿）。对象（待办清单条目/roadmap 格）已有内容 → 直接写入标记 〔用户特批 YYYY-MM-DD 跳过××〕；对象没有任何内容 → 必须回呈实况、经用户再次确认后才写标记。标记必须带日期，无日期=非法（doc-conventions §12.4）。
• 禁自援特权：执行中你自己觉得某步该跳，只能呈报后停，禁自己援引特批。
• 闸过渡期口径：现行待办清单与 roadmap 还是旧格式，python tools/pipeline_gate.py 对它们整体红属预期。红项若全部来自旧格式存量、与本次操作对象无关，注明即可；本次操作对象自身的格式必须合规。pipeline_gate 注册进 run_all_gates 文档域归数据整改批，此前 --docs 的回执不含它，属正常。
• 本技能只固化本段特有条款；车道铁律、会话落记等仓库级纪律按 design/engineering/process-conventions.md 现行文本执行。

主流程（文档线设计）

第 1 步：取条目并校验

1. 判来源：用户点名某条在册事项 → 从 待办清单.md 取该条目，取不到就回报「清单内无此事项」并停，禁自造条目凑流程；本次会话新提出的事项 → 无条目直接进第 2 步（条目记的是进度，不是讨论的开工前置）。
2. 校验两件事：
   • 所属设计线：状态行含文档线段（待文档设计／文档设计中／文档设计已闭合）。
   • 状态：为「待文档设计」或「文档设计中」。
3. 状态不对 → 停工呈报，禁硬做。典型：已闭合（设计已完，重开须用户明示并说明理由）；需求性工程条目（状态整行无设计线段，走 req-card）或直改类条目（状态＝待执行，不走写卡）；已写卡/已编迭代（下游已动，改动=回退流程，归用户裁）。
4. 条目是旧格式存量（标题缺登记元数据）→ 先向用户确认其来源与所属设计线、改动面，再按 doc-conventions §12.1 模板补齐标题元数据与四属性（实况／缺口／改动面／状态）（这属「本次操作对象格式合规」动作），然后回到第 2 步校验。确认中若答案已注定校验不过（如状态整行无设计线段＝需求性工程条目或直改类条目），直接停工呈报，禁补格式硬做。

第 2 步：设计讨论（用户主导）

1. 开题先用一句 ≤50 字大白话概览：这个系统/事项是什么、为什么现在做。
2. 先高抽象后具体：方向、骨架、边界未定前，禁铺具体条目（数值表、条目清单、字段细节都是具体层）。
3. 每个待裁点呈全部备选方案与代价，禁代裁——设计权归用户。零待裁点也要向用户报明「本讨论零待裁点」，同样等用户点头。
4. 讨论中冒出的新待裁点随时入册（记在会话内呈报的待裁点清册，不写进 GDD 正文——doc-conventions §5：正文只写现行规则）。
5. 会话内进行、禁无监管自跑（process-conventions §2 段铁律）。

第 3 步：闭合与写入 GDD

闭合判据=待裁点清零＋用户点头，二者缺一不可；带未裁点的产出是讨论稿，禁写入。闭合后才动笔：

1. 定稿写入 GDD 系统文档（design/gdd/systems/<域>/<系统>.md），骨架按 doc-conventions §6 系统文档骨架（文首引言／设计目的／系统范围／核心循环位置／核心规则／依赖与输出／P0 与后置／调参表／验收标准／待办指路存根）。
2. 新系统同步根索引 design/gdd/02-系统清单.md（文档增删必须同步根索引，doc-conventions §5）。
3. 新数值进 game/data/tables/*.tres，且 owner GDD 正文表格同步；涉术语规范名时同步 design/gdd/术语表.md——三处之一未更新即视为变更未完成（doc-conventions §5 数值纪律）。
4. 文首状态行版本号递增（「现行为 vX.Y」）——禁写版本历史表，改动明细只进 git 提交信息（doc-conventions §5 禁写变更记录、gdd_lint R4 拦截）。
5. 画面类需求另出预览图（2026-11-05 立）：触碰画面呈现规格的需求（新增画面要素／布局／配色／动效），定稿写入前先出目标画面的 HTML/SVG 效果图（diagram-design 通道），经用户人审通过才算本线闭合；预览图内嵌对应 ux/ 规格文档并随附像素级视觉判据句（process-conventions §7 第 2 条同款写法）——写卡段引它、实现批基线冻结时用户对照它（test-conventions §8.2）。缺陷修复以现行规格与在库基线为准，不触发新预览。

第 4 步：待办清单状态推进

按 doc-conventions §12.1 状态机改写条目状态属性：

• 只走文档线：改「文档设计已闭合（凭据=文档路径+版本号，例：design/gdd/systems/排雷循环/排雷玩法.md v1.3）」，并删除「缺口」属性（本线全闭合，状态里已无未闭合态词）。
• 文档线与美术线并列：改两段并列，文档侧闭合、美术侧保持原状态（例：文档设计已闭合（…v0.6）＋美术设计中）。「缺口」属性此步保留，改写为美术侧还差什么——状态里只要还有 待美术设计/待文档设计 等未闭合态词，缺口属性就必须在（流水线闸判据：四态必须有缺口、其余状态不得有）；待美术侧也闭合、条目转入 待写卡 时才删。
• 「已闭合」不带凭据不算合法状态词。
• 若经特批跳过本段某步，标记写在本条目状态处。

第 5 步：跑流水线闸

python tools/pipeline_gate.py，核对与本次条目相关的判据零红。过渡期存量红注明即可（见批性质）；本次操作对象自身的格式必须合规，对象自身有红就改到绿再收尾。

收尾

python tools/run_all_gates.sh --docs（文档域闸），全绿后按车道合回 master（独立 worktree→主区 git merge --no-ff→删区）。

反哺点写入模式（同技能第二触发）

本技能两个入口：用户说「做文档设计／系统设计讨论／定稿进 GDD」走上面的主流程；用户说「落反哺点／处理反哺点清单／反哺点裁决写入」直接走本节，不进主流程（反哺点专条走的是另一套状态词，主流程第 1 步对它必然停工）。本节流程：

1. 读 reports/iter<N>-反哺点-<日期>.md（反哺点清单由实现批产出，每条写明哪个文件哪一节、改成什么、依据是什么）。
2. 逐条呈用户裁决。禁未裁决直接写入——清单写着什么改法不等于已裁决。
3. 裁决通过的，写入对应 GDD/art-bible 章节（写入纪律同第 4 步：文首状态行版本号递增、禁写版本历史表、数值三处同步）。架构文档不在反哺落点内（2026-11-07 用户裁：架构文档只写约束面、写权限＝用户专属）——反哺点涉架构事实时只呈报，由用户裁决后亲自落文。
4. 待办清单对应反哺点专条（状态取待裁决／已写入）状态改「已写入（落点=文档+版本）」，落成实例形态 已写入（design/gdd/systems/…/xxx.md v1.4）——凭据须为真实文档路径＋版本号（流水线闸判据）。
5. 清单条目按「吸收即死」退役（doc-conventions §11）：全部条目落文后核对引用面、改写指路句，再退役清单文件（实现报告内的清单按「证据只留最新」口径随批退役）。

兼任范围注记

design/engineering/ 规约类文档（process-conventions / doc-conventions / code-conventions 等）的修订也走本技能：同样经用户主导讨论、待裁点清零＋用户点头后才落笔，落笔后按对应文档自身的版本/头注惯例记录修订。

纪律

• 平实简体中文，禁自造黑话；流水线词汇（登记/文档设计/美术设计/改动面/特批标记/流水线闸/需求性工程条目/待执行/已写卡/已编迭代）按 doc-conventions §12 用法一致使用。
• 白话写作规则（doc-conventions §2）与表达分工（§3）对写入 GDD 的内容全程生效。
• 本技能不写需求卡片、不编迭代、不碰代码——下游各归其段：写卡=req-card，编排=iter-plan。