Refactor code structure for improved readability and maintainability

.qoder/skills/doc-design/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: doc-design
+description: 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 步：文首状态行版本号递增、禁写版本历史表、数值三处同步）。
+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。