Skip to content
Back to search

requirement-to-path

从模糊需求出发,定位 GitHub 上整块匹配的成熟模块(发现与核验走 github 连接器的 MCP 工具),深读代码提取事实并裁决优缺点,反推带验证信号的分步实现路径。触发词:帮我实现某个功能/模块、有没有开源项目可以参考、别人是怎么做这个模块的、需求很模糊想落地成方案。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zxd15978684198--requirement-to-path/badge.svg)](/listings/zxd15978684198--requirement-to-path)

HTML

<a href="/listings/zxd15978684198--requirement-to-path"><img src="/api/listings/zxd15978684198--requirement-to-path/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

前置条件(硬性,不是可选项)

本 skill **强依赖 `github` 连接器**(MCP server)。所有检索与读码都走它的工具:

`search_repositories` · `search_code` · `get_file_contents` · `pull_request_read` · `search_issues`

不自研检索脚本——鉴权托管、限流额度高(未认证直连只有 10 次/分钟)、随官方 server 升级零维护。连接器不可用时会走降级路径,并在交付文档里**显式标注候选质量下降**。

把这个连接器配上

需要做到的事只有一件:让你的 agent 能调到上面那 5 个工具。两条路,任选其一。

**A. 用官方托管端点(最省事)**。GitHub 自己有托管的 MCP server,用 PAT 作为 Bearer 鉴权:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer <你的 PAT>" }
    }
  }
}

把这段放进客户端的 MCP 配置即可:Claude Desktop / Cursor 各有自己的配置文件;DSH 走 MCP 连接器面板的「导入 JSON」。

**B. 本地跑官方 server**。

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<你的 PAT> \
  ghcr.io/github/github-mcp-server

在客户端里把这条命令注册成 `stdio` 类型的 server。不想用 Docker,也可以从 [`github/github-mcp-server`](https://github.com/github/github-mcp-server) 下二进制。

**PAT 权限按需最小化**。只读公开仓库时,fine-grained token 一个权限都不勾也能用;要读私有仓库,就给对应的那几个仓库 `Contents: Read`。本 skill 全程只读:不写、不开 PR、不发评论。

**接好之后怎么确认**。问一句「你现在能调到哪些 github 工具」,看有没有 `search_repositories`、`search_code`、`get_file_contents`、`pull_request_read`、`search_issues` 这 5 个。

**只暴露了一部分会怎样**。缺 `search_code`:定位阶段退化成只用仓库搜索,候选质量下降;缺 `get_file_contents`:读不到代码,「深读代码提取事实」这一整层失效。这两种情况都会在交付文档里显式标注为降级。

全程不需要 `gh` CLI,也不会调用任何 shell 命令。

Claude Code

git clone https://github.com/zxd15978684198/requirement-to-path.git \
  ~/.claude/skills/requirement-to-path

之后在会话里说「**帮我实现 XXX**」或「**有没有开源项目可以参考**」即可触发。

DeepSeek Harness (DSH)

把整个目录放进 `DSH_HOME/skills/requirement-to-path/`,确保 `SKILL.md` 位于该目录根。

其他工具(Cursor / Codex / Gemini CLI / 自建 agent)

本 skill **不绑定任何运行时**:全是 Markdown + 一个只依赖标准库的 Python 脚本。把 `SKILL.md` 作为指令文件喂给你的 agent、把 `references/` 放在它能读到的位置即可。

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 198 lines
  1. ---
  2. name: requirement-to-path
  3. description: 从模糊需求出发,定位 GitHub 上整块匹配的成熟模块(发现与核验走 github 连接器的 MCP 工具),深读代码提取事实并裁决优缺点,反推带验证信号的分步实现路径。触发词:帮我实现某个功能/模块、有没有开源项目可以参考、别人是怎么做这个模块的、需求很模糊想落地成方案。
  4. agent_created: true
  5. version: 1.60.8
  6. last_updated: 2026-10-19
  7. ---
  8. # 需求 → 对标 → 路径重构
  9. > **版本**:见 frontmatter `version:` | **完整账本**见 `references/verification-log.md`。**本行不写版本号与账本区间端点**:值只许出现在唯一权威处——同值写两处、改一处漏另一处,是本 skill 历次翻车的唯一根因。
  10. >
  11. > **改本文件前必读 `references/maintainer-notes.md`**(声明唯一性表 + 两条维护纪律:正文不写会随改版变化的值;改完立刻跑 `--skill`)。跑需求的 agent 不需要读它。
  12. 从一句模糊需求出发,找到 GitHub 上**整块匹配**的成熟模块,读码提取事实、裁决优缺点,反推一条**可照着施工**的实现路径。
  13. **GitHub 检索一律走 `github` 连接器**(MCP 工具),不自研搜索脚本——见 [L1.0](#l10-前置接通-github-连接器硬前置)。
  14. ## 适用性判断(先做这一步)
  15. | 情况 | 处理 |
  16. | --- | --- |
  17. | 需求模糊——只有一句话、缺关键决策 | 走完整流程 |
  18. | 需求已明确,只想立项开工 | **不用本 skill** → `spec-development` |
  19. | 已有方案,只想压测它站不站得住 | **不用本 skill** → `grill-me` |
  20. | 只想讨论方案、不需要找对标 | 直接讨论,不走本流程 |
  21. | **需求明显不会有开源对标**(内部业务逻辑、私有系统) | **开工前就告知**,走 0 候选降级③/④,别耗满轮次(上限见「已知限制」2) |
  22. > 最后一条是**预判**:核心是「某家公司/系统内部的规则」而非「通用机制」。
  23. ## 流程总览
  24. **流程**:L0 三道门禁 → L1 定位 → L2 提取 → 门禁 4 裁决 → L3 分步路径;流程图见 `references/pipeline.md` §一。
  25. **执行序列 11 步**(按序走,每步输入与产出都写死):适用性判断 → 门禁 1 → L1.0 接通 → L1 半程 → 门禁 2 → 门禁 3 → L1 全程 → L2 提取 → 门禁 4 → L3 重构 → **交付前自检(必跑 `references/self_check.py`、贴输出与退出码;没跑=没交付)**;逐行表见 `references/pipeline.md` §二。
  26. > ⚠️ **上表是「做什么的先后」,不是「何时开始落盘」**:交付文档**从第 1 步起笔**(读完需求先建文件写 §0,每写完一节立刻写盘)——**半份能读的交付物远好过零份**。原文与两次回流见 `references/pipeline.md` §二附。
  27. ## 门禁通则(各道门禁共用)
  28. 1. 每道门禁必须产出**明确的产出物**(文档/清单/表),让用户审阅产出物,**不答开放式问题**;
  29. 2. 门禁是**硬阻断**:未放行不得进入下一层;
  30. 3. 用户改答后**必须重跑一致性检查**;未解决项只能以 `[假设]` 显式记录,不得静默通过;
  31. 4. **闸点标记不许跳过**:放行处标 `🛑 STOP`(停下等显式放行),需自查处标 `🔴 CHECKPOINT`;**不许为推进而自行放行**。
  32. ### 统一标注(不得混用、不得自造)
  33. `[代码可读]` 直接可见,必须给文件位置 | `[测试可证]` 有测试覆盖,指出测试函数 | `[推断]` 推测,**必须给验证方法**(以上三者用于 L2 事实表)| `[假设]` 未确认、暂时按此执行(门禁 1–4)| `[待确认]` 需用户裁决(一致性检查)| `[实测-稳定/单次]` 本 skill 自身实测结论的置信度(references 内)。
  34. ## L0 需求澄清
  35. > **输入信息量决定产出重心**:需求自带详尽规格 → 重心是「验证与补充」;只有一句话 → 重心才是「澄清」。两种都要走门禁,**不许因为材料多就跳过**。
  36. **交互硬要求**:**必须用弹窗呈现,禁止把问题写成正文列表**——一弹窗 1–4 题、每题 2–4 选项(开放题改选择题)、显示「第 N / M 题」、**每题标它服务哪道门禁**。细则见 `references/l0-question-bank.md` §六。
  37. ### L0 段门禁(门禁 1–3)
  38. **门 1 → 痛点清单**(现象/触发条件/现在怎么绕/量级;每条带 `[假设]`)|**门 2 → 方案决策表**(带痛点去 L1 找候选做法,回来问「A 做法 vs B 做法选哪个」;选项/代价/推荐与理由)|**门 3 → 需求规格**(做什么、**明确不做什么**、验收标准、约束前提,含 `[假设]` 条目)。逐列问法与呈现要求见 `references/l0-question-bank.md` §十四。
  39. > **门禁 1 之前先判「需求所在的系统是不是就在手边」**——四条判据、本地优先取证顺序、何时才需要去 GitHub,见 §十二——**工作区里的代码就是最强的来源**。
  40. **L0 与 L1 之间存在回流**:门 2 要候选方案当输入,而候选来自 L1 的搜索能力。实际顺序:
  41. ```
  42. 门禁1 → L1.0 接通连接器 → L1 半程(找候选做法)→ 门禁2 → 门禁3 → L1 全程(找最终对标模块)→ …
  43. ```
  44. **必须执行,否则门禁 2 悬空**;本地有代码时**先读本地检索入口、权限过滤、写入路径**再去搜。
  45. **需求方不可达时**(需求来自公开 issue/论坛帖/文档):**不许**跳过 L0 直接开搜,四个门禁各自的降级做法见 §十一。
  46. **提问语言规范 / 止损规则 / 一致性检查**:**门 2 之前只用需求方语言,禁止方案术语**(实测:用方案语言问,用户答「不太明白」,该题作废);模糊需求里唯一确定的是**痛点**,从痛点问起。话术与检查点见 §四/§五。**总问题数达 12 问(硬上限,不许放宽;本行是该数值的唯一权威处)** → **必须**停止提问、强制收敛到门禁 3;未确认项标 `[假设]` 显式列出。
  47. ## L1 定位
  48. ### L1.0 前置:接通 GitHub 连接器(硬前置)
  49. **加载方式**:接通 `github` 连接器即可调用其 MCP 工具;本环境工具名带前缀(`mcp__github__*`),下文写短名,参数与官方一致。**为什么必须走连接器**:鉴权托管、限流额度高(自研未认证仅 10 次/分钟)、零维护——见 `references/l1-search-recipes.md` §零。
  50. **工具映射表**(L1、L2 只用这些工具;完整 8 行表见 §九,**别凭记忆选**):反查 `search_code` + 加引号机制短语 + `repo:`;直搜 `search_repositories` 必须 `minimal_output: false`;核验「已实现」看 `pull_request_read` 的 `merged`;`search_issues` 必带 `owner`+`repo`。
  51. **先探活**:将用到的每个工具各测一次,别只测一个就假定全通;最小调用见 §零,失败按下一节处置。
  52. ### L1.0-fallback 连接器不可用(详见 `references/l1-search-recipes.md` §六)
  53. **先判「半通」还是「全断」**:工具面未注册但资源面能列能读(`ListMcpResources`/`ReadMcpResource`)→ **半通,先不降级**;三条通道同时不可用才走终止分支。**不许退回自研脚本**。
  54. ### 模型型组件的第二搜索面(HuggingFace)
  55. **触发**:子机制是模型能力(识别/检测/标注/分类/预训练模型)——GitHub 搜码对这类组件**漏召回**,漏斗天然半盲。**做法**:`WebFetch` 打 `https://huggingface.co/api/models?search=<≤2 词机制词>&sort=downloads&direction=-1&limit=10`(长短语命中率低);官方域名实测不可达 → 走镜像 `https://hf-mirror.com/api/models?…`(镜像缺 `lastModified`,活跃度改读 `createdAt`)。配方见 §八。
  56. ### 漏斗七步(第 0 步先判需求形状)
  57. **第 0 步:判断需求形状**——**整块匹配型**(需求本身是一件事,如「向量库增量同步」)直接进第 1 步;**组合型任务**(如「竖排古籍→横排+标点+坐标对照」= OCR + 标点 + 版面分析)**先拆子机制,每个各走一遍漏斗**,最后在门禁 4 汇总。**形状判据与深挖配额见 §十**;**深挖 2–3 个子机制**,挑争议最大与完全没做过的,其余只到 L1 定位、不读码。
  58. 1. **关键词构造**——**动词短语 + 机制名词**,禁用领域名;3–5 组、**≤3 词**、`stars:>=100`。见 §一。
  59. 2. **捞候选——直搜为主;反查不是发现路径**:发现靠 `search_repositories`(`minimal_output: false`);`search_code` 只在带 `repo:` 时核验。见 §零、§一 1-C。
  60. 3. **结果分类**——完整模块(🎯 目标)/**参考实现库(📐 读设计抄模式)**/框架(❌)/教程(📎)/平台(❌)。见 §二。
  61. 4. **匹配度矩阵**——逐项打勾;**缺口清单比匹配分数重要**。见 §三。
  62. 5. **元信息与成熟度**——全来自连接器,**两维分开报**。见 §四。
  63. 6. **代码级验证**——`search_code` 带 `repo:` 定位文件,再 `get_file_contents` 读原文;**只读 README 不算数**(实测两条结论读码后被推翻)。见 §五。
  64. 7. **交付**——进入门禁 4。
  65. ### 找不到对标时怎么办(0 候选处置)
  66. 搜索轮次达上限后匹配矩阵仍为空(或只剩教程类)→ 触发本降级,**按顺序走,不许跳级硬凑**。**与第 0 步的分工**:第 0 步**主动**判形状;本降级是**被动**兜底(起初判整块型、搜完才发现是组合型)。级别定义与 ①–④ 的动作见 §十一。
  67. ## L2 提取
  68. **四步走:入口主流程 → 数据结构 → 接口契约 → 测试文件**,每步有停手条件,逐行表见 `references/l2-extraction-protocol.md` §六。**第 4 步必须记「它没断言什么」**(盲区)。
  69. **读取手段**:`get_file_contents` 逐文件读;位置不定时先 `search_code`(机制短语**加引号** + `repo:`)。**产出格式**:每条结论 = 「它怎么做」+「与我的方案差在哪」+ 代码位置,按统一标注打标——**禁止把推断写成事实**。**优先级**:安全边界类最高——跑时不报错、事后才发现丢数据的那类。
  70. ## 门禁 4 对标裁决
  71. 对标模块与需求**必然存在差异**,路径重构前必须先裁决。**需求方不可达时** → 三件套(天花板块照旧给理由+备选,其余打包「默认采纳」,交付文档首行写不可达声明)。细则见 `references/gate4-adjudication.md`。
  72. **产出物 ①:优缺点三分类**——✅ 优于原计划 → 照抄;⚠️ 能用但需改造 → 改造后采纳;❌ 缺陷 → 自己补。
  73. **产出物 ②:待裁决项清单**——**分级征询**:影响天花板的条目逐条问(给理由+备选),其余打包「默认采纳」**显式列出**、不反对即通过——**清单必须完整可见,不许静默略过**。两张表的区分与冲突处置三步见 `references/gate4-adjudication.md`。
  74. 🛑 STOP:清单每条都闭合之前,不得进入 L3——**未闭合条目只能标 `[假设]` 并显式列给用户**,不许自行拍板。
  75. 🔴 CHECKPOINT:进 L3 前复查一次,每条裁决是否都能追溯到 L2 的某段代码或某个坑。产出即 L3 的直接输入(最终设计决策表)。
  76. ## L3 路径重构
  77. **每步必须包含三件套**:**指令模板**(可复制的提示词,含"明确不要做什么")/**通过信号**(必须跑出来的输出;**三条附加要求:①可判;②在目标项目现有测试栈里跑得起来;③贴得出真实输出**)/**翻车信号**(出现什么说明走错了 + 处置)。规格见 `references/l3-mode-map.md` §十三。
  78. **每步标注开发模式**:TDD / Spec / 场景测试,判据与阶段映射见 `references/l3-mode-map.md`。**每步都要能追溯到「L0 的某条裁决」或「L2 的某段代码/某个坑」,禁止无来源步骤**(否则退化为事后合理化)。
  79. 第 7 节(分步实现路径)**每步带来源列**,取值域封闭、不得自造:
  80. | 来源标签 | 含义 |
  81. | --- | --- |
  82. | **本地文件行号** `path/to/file.py:88`(或`:L12-L30`) | 「门禁 1 之前先读本地代码」的产出落点。**必须带行号或行区间**(裸文件名不可核);扩展名限 `py/md/json/toml/sql/yml/yaml/ini/cfg/txt/env/ts/tsx/js/jsx`(与 `references/self_check.py` 的 `_LOCAL_EVIDENCE` 逐项一致);其余标签与 `cfg`/`txt`/`.env` 的来历见 `references/l3-mode-map.md` §七 |
  83. **填不出来源的步骤,删除它**——不要补一个勉强的出处;同一来源可被多步引用。
  84. > **来源格与编号的写法**:`| 步骤 | 来源 |` 的单元格**只放标签,不放说明**(夹带说明会被判违规);否则它**要么被读成标签、要么被悄悄丢掉,两种都不该发生**。编号算「已定义」只有两种形态:①**以它为首格的表行**;②行内定义行(「`L0-P1`:…」)。**封闭域收口**:合法标签的唯一事实来源是 `references/self_check.py` 的 `ALLOWED_SOURCE_PATTERNS`,本文件的枚举只作说明。退出码:`0` 放行/`1` 有硬违规/`2` 有未核项/`64` 用法错误——**`0` 只意味着「脚本没查到问题」**,射程见 `references/delivery-checklist.md` §三、§四。
  85. **文档结构:0 定位与档位 → 1 业务叙事 → 2 决策表+依据 → 3 量级 → 4 契约 → 5 对标结论 → 6 模块全景 → 7 分步路径 → 8 验收 → 9 已知限制**(逐节规格见 `references/l3-mode-map.md` §十四)。
  86. > **本行是章节编号的唯一来源**:「第 N 节/§N」一律指本行编号,不许另立第二套(v1.18.3 曾并存三套,根因是「文档结构」写在多处,见 §6.1)。**两处不独立成章**:对标改动并入第 2 节「决策依据」;`K<n>` 坑清单不单列(原位引用 + 附录纯编号索引)。**§0 必须写清层级与档位**,否则会被用错尺子量。
  87. > **落盘时序(v1.56.18:三次盲跑换来的硬规矩)——§0 先落盘,再进 L1 搜索。** 来历与四条动作见 `references/l3-mode-map.md` §九 与 §6.3;**先落盘的是骨架,不是完整的 §0**。**本行是 `probe_skillref.py` 的锚点,不许改**。
  88. > **体量用质性判据,不设行数上限**:①**读者能否一次读完**并找到要点;②文档里**有没有出现本不该出现的东西**(实测记录、自证、版本对照这类过程噪音);③同类交付是否**持续变长**(看趋势,不看单份)。撤阈值见 §6.4。
  89. **叙事线硬约束**:
  90. > **冻结机制**:本组硬约束**全部列于下,数量即本列表长度**。新增一条必须同时**合并或删除**一条旧约束,禁止只增不减。14 条合并为 9 条的来历与旧→新编号映射见 `references/l3-mode-map.md` §十 与 `references/verification-log.md`。
  91. 1. **必须从一句模糊需求出发**——即使走富信息路径,开头也要展示原始模糊需求原话 + 缺哪些决策 + 为何转向验证。(§十二.1)
  92. 2. **两章前置:业务实现叙事章 + 模块全景**(面向读者,整块一章不是小结,模块全景先行)。(§十二.2)
  93. 3. **交付文档与服务者账本分离**——过程记录一律归 `references/verification-log.md`,**不进交付文档**。(§十二.3)
  94. 4. **标注与表达规范:数字、公式、术语**(旧 ⑩+⑪ 合并)——根因:**模型的严谨性按「内容难度」分配,而不是按「重要性」分配**。**全文/所有数字**都要带标记;本表数字均带四类标记([实测]/[假设]/[外源]/[推导]);编码完成后须回填者见 §9.1。(§十二.4)
  95. 5. **论断必须可核查、可被质疑:契约配断言,设计配反向边界**。(§十二.5)
  96. 6. **决策必须带意图链**——「要什么 → 备选 → 权衡 → 推荐与理由 → 放弃的代价」,代价必须显式写。(§十二.6)
  97. 7. **对标必须附链接 + 逐仓库取舍**——每个仓库给链接,写「为什么参考+为什么不全抄」。(§十二.7)
  98. 8. **交付文档必须自洽:内部交叉引用逐对闭合**——交付前按 `references/delivery-checklist.md` §一 的 ⑭ 矩阵逐对核验。(§十二.8)
  99. 9. **施工路径的写法:三件套 + 提示词可复制 + 步骤从数据流反推**。(§十二.9)
  100. 🛑 STOP:交付前逐条核对第 8 节验收清单——每条都必须带可观察证据,**「看起来对」不算证据**。
  101. ## 资源清单
  102. | 资源 | 何时加载/使用 |
  103. | --- | --- |
  104. | **`github` 连接器** | **L1.0 硬前置**:接通后才能用 `search_repositories`/`search_code`/`get_file_contents`;**不内置自研检索脚本** |
  105. | `references/l0-question-bank.md` | ⚠ **按节读取**(进入 L0 提问前):必读 §一、§四、§五、§十四;再按域读 §二 或 §三 的一类 |
  106. | `references/l1-search-recipes.md` | ⚠ **按节读取**(进入 L1 搜索前):主链 §零→§一→§二→§三→§四→§五→§七;按需 §六、§八–§十一 |
  107. | `references/l2-extraction-protocol.md` | ⚠ **强制前置读取**(进入 L2 读码前,整读) |
  108. | `references/l3-mode-map.md` | ⚠ **强制前置读取**(进入 L3 重构前,整读):模式判据、三件套规格、§五–§十四 细则 |
  109. | `references/gate4-adjudication.md` | ⚠ **强制前置读取**(进入门禁 4 前):不可达形态、与门禁 2 的区分、冲突处置三步 |
  110. | `references/delivery-checklist.md` | **交付前必读**:§一 ⑭ 引用关系矩阵、§二 自检清单、§三 脚本射程、§四 机械举证与容易读错的绿灯 |
  111. | `references/self_check.py` | **交付前必跑**:**十三项机械自检 + 一项提示项**;非交付物可在前 2000 字符内写 `<!-- self_check: genre=reference -->` 跳过交付物专属项 |
  112. | `references/verification-log.md` | **按需查**,不参与执行:完整账本、未验证分支、环境依赖 |
  113. | `references/pipeline.md` | **按需查**:流程图、11 步执行序列表、落盘时序提醒原文 |
  114. | `examples/full-walkthrough.md` | 看一遍端到端产出形态 |
  115. | `.eval/` | 实测证据,执行时不加载 |
  116. | `evals/` | 六题 + `harness.py`;`python evals/harness.py --case NN --doc <文档> --root <项目根>`。**机械分是必要条件不是充分条件**,分数必须连命令一起记 |
  117. > **Windows/PowerShell 跑自检的两个坑**:①控制台默认 GBK,中文输出乱码——先设 `$env:PYTHONIOENCODING="utf-8"`;②**别用内联 `python -c "多行代码"`**(反引号会被 PowerShell 当转义符)——多行写临时 `.py`。
  118. ## 执行后自检清单(交付前硬核对)
  119. > 交付前逐项打勾,**任何一项不过不得交付**。机械部分最低举证=跑脚本并贴输出与退出码——**没有脚本输出现场 = 没跑**。但**退出码 `0` 只等于「机械项没查出问题」**,不等于清单打勾完毕。清单表体、两个容易读错的绿灯(`--skill` 不是能力证明;`[实测]`/`[外源]` 的出处必须真能核,核不到报 ⚠️ 未核而非违规)、证据根声明(施工在副本时原项目与副本都要声明)见 `references/delivery-checklist.md` §二、§四。
  120. ## 验证记录(已外移,见 `references/verification-log.md`)
  121. > 完整账本、**未验证的分支**(🔴 会卡死流程/🟡 仅降低质量)、已实测部分、环境依赖(HF 官方域名不可达、须走镜像,镜像可用性不由本 skill 保证)都在 `references/verification-log.md`。**设计 ≠ 验证**:当卡点对待,卡住如实告知用户。
  122. ## 已知限制
  123. 1. **"用户答不出"的分支尚未实测**——需求方即项目 owner 时止损规则不会被触发;替不懂技术的别人做需求时留意。本 skill 不做代码实现,L3 产出交给 `spec-development` 执行。
  124. 2. **搜索轮次硬上限 3 轮**——满 3 轮**必须**把已有候选摆给用户裁决,**不得**自行死磕;**本行是该数值的唯一权威处**。配套规则见 `references/l1-search-recipes.md` §七。
  125. 3. **强依赖 `github` 连接器**——未授权时只能走降级路径,候选完整性与排序质量都会下降;降级结果必须在交付文档里**显式标注**。
README.md · README · 482 lines
  1. <a id="chinese"></a>
  2. # requirement-to-path · 需求 → 对标 → 路径重构
  3. > **从一句模糊需求,走到一条能照着施工的实现路径。**
  4. **简体中文** | [English ↓](#english)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. [![GitHub stars](https://img.shields.io/github/stars/zxd15978684198/requirement-to-path?style=social)](https://github.com/zxd15978684198/requirement-to-path)
  7. [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](references/self_check.py)
  8. [![零依赖](https://img.shields.io/badge/dependencies-0-brightgreen)](references/self_check.py)
  9. [![CI](https://github.com/zxd15978684198/requirement-to-path/actions/workflows/ci.yml/badge.svg)](https://github.com/zxd15978684198/requirement-to-path/actions/workflows/ci.yml)
  10. 一个给 AI coding agent 用的 **skill**(不是库,不是 CLI)。它把「帮我实现某个模块」这件事拆成五层,每层都有硬门禁,最后交付一份**每步都带通过信号**的施工路径。
  11. ---
  12. ## 它和「直接问 ChatGPT」差在哪
  13. | 常见的做法 | 这个 skill |
  14. | --- | --- |
  15. | 你只说得出一句话,AI 立刻开始写代码 | **先问清**:3 道门禁产出痛点清单 → 方案决策表 → 需求规格 |
  16. | 丢给你十个 GitHub 链接 | 匹配度矩阵 + **逐仓库**「为什么参考 / 为什么不全抄」 |
  17. | 拿 README 当结论 | **读代码**:`get_file_contents` 看实现,`pull_request_read` 看是否真合并 |
  18. | 「方案看起来是对的」 | 每步三件套:**指令模板 / 通过信号 / 翻车信号** |
  19. | 分不清哪句是猜的 | 每条事实标 `[代码可读]` / `[测试可证]` / `[推断]`,推断必须给验证方法 |
  20. 一句话:**它不替你写代码,它给你一条别人已经踩过坑的路。**
  21. ---
  22. ## 什么时候**不该**用它
  23. 诚实地写在最前面,省得你用错:
  24. | 情况 | 该用什么 |
  25. | --- | --- |
  26. | 需求已明确,只想立项开工 | `spec-development` |
  27. | 已有方案,只想压测它站不站得住 | `grill-me` |
  28. | 只想讨论方案,不需要找对标 | 直接聊,别套流程 |
  29. | 需求是**某家公司内部的业务规则** | 开工前就会告诉你不会有开源对标,别耗满搜索轮次 |
  30. ---
  31. ## 流程
  32. ```
  33. L0 澄清(门禁 1–3)→ L1 定位 → L2 提取(读码)→ 门禁 4 裁决 → L3 路径重构 → 交付自检
  34. ```
  35. - **L0**:需求方语言提问(禁用方案术语),三道门禁各产出一份可审阅的文档,⚙ 硬阻断
  36. - **L1**:动词短语 + 机制名词构造关键词 → 直搜捞候选 → 分类打标 → 匹配度矩阵 → 代码级验证
  37. - **L2**:入口主流程 → 数据结构 → 接口契约 → 测试文件,四步都记「它没断言什么」
  38. - **门禁 4**:优点照抄 / 能用但需改造 / 缺陷自己补,三分类后逐条裁决
  39. - **L3**:分步路径,每步都要能追溯到「L0 的某条裁决」或「L2 的某段代码」
  40. 11 步执行序列见 [`references/pipeline.md`](references/pipeline.md),主文件见 [`SKILL.md`](SKILL.md)。
  41. ---
  42. ## 安装
  43. ### 前置条件(硬性,不是可选项)
  44. 本 skill **强依赖 `github` 连接器**(MCP server)。所有检索与读码都走它的工具:
  45. `search_repositories` · `search_code` · `get_file_contents` · `pull_request_read` · `search_issues`
  46. 不自研检索脚本——鉴权托管、限流额度高(未认证直连只有 10 次/分钟)、随官方 server 升级零维护。连接器不可用时会走降级路径,并在交付文档里**显式标注候选质量下降**。
  47. ### 把这个连接器配上
  48. 需要做到的事只有一件:让你的 agent 能调到上面那 5 个工具。两条路,任选其一。
  49. **A. 用官方托管端点(最省事)**。GitHub 自己有托管的 MCP server,用 PAT 作为 Bearer 鉴权:
  50. ```json
  51. {
  52. "mcpServers": {
  53. "github": {
  54. "type": "http",
  55. "url": "https://api.githubcopilot.com/mcp/",
  56. "headers": { "Authorization": "Bearer <你的 PAT>" }
  57. }
  58. }
  59. }
  60. ```
  61. 把这段放进客户端的 MCP 配置即可:Claude Desktop / Cursor 各有自己的配置文件;DSH 走 MCP 连接器面板的「导入 JSON」。
  62. **B. 本地跑官方 server**。
  63. ```bash
  64. docker run -i --rm \
  65. -e GITHUB_PERSONAL_ACCESS_TOKEN=<你的 PAT> \
  66. ghcr.io/github/github-mcp-server
  67. ```
  68. 在客户端里把这条命令注册成 `stdio` 类型的 server。不想用 Docker,也可以从 [`github/github-mcp-server`](https://github.com/github/github-mcp-server) 下二进制。
  69. **PAT 权限按需最小化**。只读公开仓库时,fine-grained token 一个权限都不勾也能用;要读私有仓库,就给对应的那几个仓库 `Contents: Read`。本 skill 全程只读:不写、不开 PR、不发评论。
  70. **接好之后怎么确认**。问一句「你现在能调到哪些 github 工具」,看有没有 `search_repositories`、`search_code`、`get_file_contents`、`pull_request_read`、`search_issues` 这 5 个。
  71. **只暴露了一部分会怎样**。缺 `search_code`:定位阶段退化成只用仓库搜索,候选质量下降;缺 `get_file_contents`:读不到代码,「深读代码提取事实」这一整层失效。这两种情况都会在交付文档里显式标注为降级。
  72. 全程不需要 `gh` CLI,也不会调用任何 shell 命令。
  73. ### Claude Code
  74. ```bash
  75. git clone https://github.com/zxd15978684198/requirement-to-path.git \
  76. ~/.claude/skills/requirement-to-path
  77. ```
  78. 之后在会话里说「**帮我实现 XXX**」或「**有没有开源项目可以参考**」即可触发。
  79. ### DeepSeek Harness (DSH)
  80. 把整个目录放进 `DSH_HOME/skills/requirement-to-path/`,确保 `SKILL.md` 位于该目录根。
  81. ### 其他工具(Cursor / Codex / Gemini CLI / 自建 agent)
  82. 本 skill **不绑定任何运行时**:全是 Markdown + 一个只依赖标准库的 Python 脚本。把 `SKILL.md` 作为指令文件喂给你的 agent、把 `references/` 放在它能读到的位置即可。
  83. ---
  84. ## 一次真实调用长什么样
  85. 需求方原话只有一句:
  86. > 给内部问答机器人加一层语义缓存——重复或近似的问题别再调模型;但近似但不同的问题不能串答案。
  87. 产出物(10 节,约 4 万字符):
  88. ```
  89. 0 定位与档位 1 业务叙事 2 决策表 + 依据 3 量级 4 契约
  90. 5 对标结论 6 模块全景 7 分步路径 8 验收 9 已知限制
  91. ```
  92. 完整的端到端样例见 [`examples/full-walkthrough.md`](examples/full-walkthrough.md)。
  93. 第 7 节每一行长这样:
  94. | 步骤 | 来源 | 指令模板 | 通过信号 | 翻车信号 |
  95. | --- | --- | --- | --- | --- |
  96. | 加法缓存条目 | `src/cache.py:88` | … | 该测试能从 4 变 8 | 命中率不涨但延迟降 |
  97. **来源格填不出来源的步骤,会被删除**——不允许补一个勉强的出处。
  98. ---
  99. ## 质量与成本
  100. ### 成本
  101. | 项 | 量 |
  102. | --- | --- |
  103. | 首次加载 `SKILL.md` | ≈ 10,000 字符 |
  104. | `references/` | **按层读**,不是一次性全读(L0 前只读题池的 4 节,L1 前只读配方的主链 7 节) |
  105. | 运行时依赖 | 0(Python 标准库 + 你的 MCP 连接器) |
  106. ### 可复核的部分
  107. ```bash
  108. # SKILL.md 自身一致性:版本对账 / 哨兵位置 / 禁用形态 / 自述项数
  109. python references/self_check.py --skill SKILL.md # → 0 violations
  110. # 交付物自检:13 项机械检查(来源封闭域、声明唯一、标记与证据配套……)
  111. python references/self_check.py <交付文档.md> # 退出码 0/1/2/64
  112. # 任务级评测:对真实产出物打分,只判「能机械判的那一半」
  113. python evals/harness.py --case 02 --doc <产出物.md> --root <项目根>
  114. ```
  115. | 证据 | 内容 |
  116. | --- | --- |
  117. | 13 项机械自检 | 来源封闭域、声明唯一性、估算数字标记、L3 通过信号可判、引用完整性…… |
  118. | 6 道任务级评测 | [`evals/`](evals/):语义缓存、状态持久化、模糊平台、超时重试、增量重建、设备派发 |
  119. | 135 条版本账本 | [`references/verification-log.md`](references/verification-log.md):每次实测的版本、验证方式、覆盖范围、**以及跑不通的分支** |
  120. | CI | [`.github/workflows/ci.yml`](.github/workflows/ci.yml):在 Python 3.10 与 3.13 上跑自洽检查 + 参考文档检查 + 引用完整性 + 用例校验 |
  121. > **退出码 `0` 只等于「脚本没查到问题」**,不等于交付合格。脚本射程见 [`references/delivery-checklist.md`](references/delivery-checklist.md) §三、§四。这个 skill 对「假绿」有病态般的警惕——账本里记着它自己五次把检查器写成空转的事。
  122. ---
  123. ## 仓库结构
  124. ```
  125. SKILL.md 主文件:五层流程 + 门禁 + 硬约束(≈10K 字符)
  126. README.md 你正在读的这份(中文在上,English 在下)
  127. CHANGELOG.md 只记对外可见的变化
  128. references/
  129. pipeline.md 流程图、11 步执行序列
  130. l0-question-bank.md L0 题池(按域、按门禁)
  131. l1-search-recipes.md L1 检索配方(连接器映射、漏斗、降级)
  132. l2-extraction-protocol.md L2 读码协议
  133. l3-mode-map.md L3 路径规格(三件套、文档结构、叙事线)
  134. gate4-adjudication.md 门禁 4 裁决细则
  135. delivery-checklist.md 交付前自检清单与引用矩阵
  136. maintainer-notes.md **改 SKILL.md 前必读**:声明唯一性表 + 维护纪律
  137. verification-log.md 135 条版本账本(诚实记录,含失败)
  138. self_check.py 13 项机械自检(仅标准库)
  139. examples/full-walkthrough.md 端到端产出样例
  140. evals/ 6 道任务级评测 + harness.py
  141. ```
  142. ---
  143. ## 已知限制
  144. 1. **强依赖 `github` 连接器** — 未接通时只能走降级路径,候选完整性与排序质量都会下降,且降级结果会在交付文档里显式标注。
  145. 2. **搜索轮次硬上限 3 轮** — 满 3 轮必须把已有候选摆给需求方裁决,不允许自行死磕。
  146. 3. **「需求方答不出」的分支尚未实测** — 需求方就是项目 owner 时止损规则不会被触发;替不懂技术的别人做需求时要留意。
  147. 4. **本 skill 不做代码实现** — L3 产出交给 `spec-development` 之类的执行型 skill。
  148. 未验证的分支(🔴 会卡死流程 / 🟡 仅降低质量)逐条记在 [`references/verification-log.md`](references/verification-log.md)。
  149. ---
  150. ## 参与维护
  151. 改 `SKILL.md` 之前**必须**先读 [`references/maintainer-notes.md`](references/maintainer-notes.md),它写着这个仓库最容易翻车的地方:
  152. - **值只许出现在唯一权威处**——同一个数字写在两处、改一处漏另一处,是本 skill 历次翻车的唯一根因
  153. - 正文不写会随改版变化的值(版本号、区间端点、条数)
  154. - 改完立刻跑 `python references/self_check.py --skill SKILL.md`,并**贴出输出与退出码**
  155. - 判据类改动不执行等于没改(账本里记着 5 次同类事故)
  156. 提交 PR 时请说明:改了什么、为什么、以及你**实际跑了哪条命令**。
  157. ---
  158. ## License
  159. [MIT](LICENSE) © 2026 zxd15978684198
  160. ---
  161. <a id="english"></a>
  162. # English · requirement → analogue → reconstruct the path
  163. > **Turn one vague sentence into an implementation path you can build against.**
  164. [简体中文 ↑](#chinese) | **English**
  165. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  166. [![GitHub stars](https://img.shields.io/github/stars/zxd15978684198/requirement-to-path?style=social)](https://github.com/zxd15978684198/requirement-to-path)
  167. [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](references/self_check.py)
  168. [![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](references/self_check.py)
  169. [![CI](https://github.com/zxd15978684198/requirement-to-path/actions/workflows/ci.yml/badge.svg)](https://github.com/zxd15978684198/requirement-to-path/actions/workflows/ci.yml)
  170. A **skill** for AI coding agents — not a library, not a CLI. It splits "build me this module" into five layers, each behind a hard gate, and ends with an implementation path where **every step carries a pass signal**.
  171. > **Language note.** The skill's own instructions — [`SKILL.md`](SKILL.md) and everything under [`references/`](references/) — are written in Chinese, and so are its trigger phrases. This English README exists so you can judge whether the project is worth reading before you open those files.
  172. ---
  173. ## How it differs from "just ask a model"
  174. | The usual thing | This skill |
  175. | --- | --- |
  176. | You can manage one sentence, the model starts writing code | **It asks first**: three gates produce a pain-point list → a decision table → a requirement spec |
  177. | It dumps ten GitHub links on you | A match matrix plus, per repo, "why reference it / why not copy it wholesale" |
  178. | It treats a README as evidence | **It reads the code**: `get_file_contents` for the real implementation, `pull_request_read` to check a claim was actually merged |
  179. | "The plan looks right" | Every step ships as a triple: **instruction template / pass signal / failure signal** |
  180. | Guesswork is indistinguishable from fact | Each fact is tagged `[code-readable]` / `[test-provable]` / `[inference]`, and an inference must come with a way to verify it |
  181. In one line: **it doesn't write the code for you — it hands you a path someone else already walked, potholes included.**
  182. ---
  183. ## When **not** to use it
  184. Written up front so you don't reach for the wrong tool:
  185. | Situation | Use instead |
  186. | --- | --- |
  187. | Requirements are settled; you just want to start building | `spec-development` |
  188. | You have a plan; you want it stress-tested | `grill-me` |
  189. | You only want to discuss a plan; no analogue needed | Just talk — don't run the pipeline |
  190. | The requirement is **one company's internal business rule** | It will tell you there's no open-source analogue before you burn search rounds |
  191. (The two alternatives named above are separate skills in the author's own setup — substitute whatever plays that role in yours.)
  192. ---
  193. ## Pipeline
  194. ```
  195. L0 clarify (gates 1–3) → L1 locate → L2 extract (read the code) → gate 4 adjudicate → L3 reconstruct the path → self-check before delivery
  196. ```
  197. - **L0** — questions phrased in the requester's language (solution jargon banned); each of three gates emits a reviewable document, and ⚙ blocks hard
  198. - **L1** — verb phrase + mechanism noun build the keywords → direct search harvests candidates → classify and tag → match matrix → code-level verification
  199. - **L2** — entry point and main flow → data structures → interface contracts → test files; at every step it records "what this does *not* assert"
  200. - **Gate 4** — copy the strength / usable but needs rework / defect you must fix yourself: three buckets, adjudicated line by line
  201. - **L3** — a step-by-step path where every step traces back to "a decision from L0" or "a piece of code from L2"
  202. The 11-step execution sequence lives in [`references/pipeline.md`](references/pipeline.md); the main file is [`SKILL.md`](SKILL.md).
  203. ---
  204. ## Install
  205. ### Prerequisite (hard, not optional)
  206. This skill **hard-depends on the `github` connector** (an MCP server). All discovery and code reading go through its tools:
  207. `search_repositories` · `search_code` · `get_file_contents` · `pull_request_read` · `search_issues`
  208. It does not roll its own search script — auth is managed for you, the rate-limit budget is far higher (unauthenticated direct calls get 10 requests a minute), and it costs nothing to maintain as the official server evolves. If the connector is unavailable the skill falls back to a degraded path and **flags the drop in candidate quality** in the delivered document.
  209. ### Wiring up the `github` connector
  210. All the skill needs is for your agent to reach those five tools. Two ways, pick either.
  211. **A. Hosted endpoint — least setup.** GitHub runs a hosted MCP server; authenticate with a PAT:
  212. ```json
  213. {
  214. "mcpServers": {
  215. "github": {
  216. "type": "http",
  217. "url": "https://api.githubcopilot.com/mcp/",
  218. "headers": { "Authorization": "Bearer <your PAT>" }
  219. }
  220. }
  221. }
  222. ```
  223. Paste that into your client's MCP configuration: Claude Desktop and Cursor use their own config file, and DSH accepts it through the connectors panel's "import JSON".
  224. **B. Run the official server locally.**
  225. ```bash
  226. docker run -i --rm \
  227. -e GITHUB_PERSONAL_ACCESS_TOKEN=<your PAT> \
  228. ghcr.io/github/github-mcp-server
  229. ```
  230. Register that as a `stdio` server in your client. No Docker? Take a binary from [`github/github-mcp-server`](https://github.com/github/github-mcp-server).
  231. **Token scope — keep it minimal.** For public repositories only, a fine-grained token needs no permissions at all. To read private repositories, grant `Contents: Read` on just those repositories. This skill never writes, never opens pull requests, never comments.
  232. **Verify it took.** Ask your agent which `github` tools it can reach. You should see `search_repositories`, `search_code`, `get_file_contents`, `pull_request_read`, `search_issues`.
  233. **If only some of the tools are exposed:** without `search_code` the discovery stage falls back to repository search and candidate quality drops; without `get_file_contents` the code-reading stage cannot run at all. Both cases are flagged as degraded inside the delivered document.
  234. No `gh` CLI and no shell commands are involved at any point.
  235. ### Claude Code
  236. ```bash
  237. git clone https://github.com/zxd15978684198/requirement-to-path.git \
  238. ~/.claude/skills/requirement-to-path
  239. ```
  240. Then say "**help me build XXX**" or "**is there an open-source project I can reference?**" in a session to trigger it.
  241. ### DeepSeek Harness (DSH)
  242. Drop the whole directory at `DSH_HOME/skills/requirement-to-path/`, keeping `SKILL.md` at the root of that directory.
  243. ### Any other tool (Cursor / Codex / Gemini CLI / your own agent)
  244. This skill **is not tied to any runtime**: it is Markdown plus one Python script that uses only the standard library. Feed `SKILL.md` to your agent as an instruction file and put `references/` somewhere it can read.
  245. ---
  246. ## What a real run looks like
  247. The requester's entire brief was one sentence:
  248. > Add a semantic cache layer to our internal QA bot — stop calling the model for repeated or near-duplicate questions; but near-duplicates that mean different things must not cross answers.
  249. The deliverable (10 sections, roughly 40,000 characters):
  250. ```
  251. 0 framing and mode 1 business narrative 2 decision table + rationale 3 scale
  252. 4 contracts 5 analogue verdict 6 module landscape 7 step-by-step path
  253. 8 acceptance 9 known limitations
  254. ```
  255. A full end-to-end sample is in [`examples/full-walkthrough.md`](examples/full-walkthrough.md).
  256. Each row of section 7 looks like this:
  257. | Step | Source | Instruction template | Pass signal | Failure signal |
  258. | --- | --- | --- | --- | --- |
  259. | Add the cache entry | `src/cache.py:88` | … | that test goes from 4 to 8 | hit rate flat but latency drops |
  260. **A step whose Source cell cannot be filled in gets deleted** — no padding it with a plausible-looking citation.
  261. ---
  262. ## Quality and cost
  263. ### Cost
  264. | Item | Amount |
  265. | --- | --- |
  266. | First load of `SKILL.md` | ≈ 10,000 characters |
  267. | `references/` | **Read layer by layer**, never all at once (before L0 only 4 sections of the question bank; before L1 only the 7-section main chain of the recipes) |
  268. | Runtime dependencies | 0 (Python standard library + your MCP connector) |
  269. ### What you can re-run yourself
  270. ```bash
  271. # SKILL.md internal consistency: version reconciliation / sentinel positions / banned shapes / self-declared item count
  272. python references/self_check.py --skill SKILL.md # → 0 violations
  273. # Deliverable self-check: 13 mechanical checks (closed source domain, claim uniqueness, tag/evidence pairing, …)
  274. python references/self_check.py <deliverable.md> # exit 0/1/2/64
  275. # Task-level evaluation: scores a real deliverable, judging only the half a machine can judge
  276. python evals/harness.py --case 02 --doc <deliverable.md> --root <project root>
  277. ```
  278. | Evidence | What it is |
  279. | --- | --- |
  280. | 13 mechanical self-checks | Closed source domain, claim uniqueness, estimates marked as estimates, L3 pass signals must be decidable, reference integrity… |
  281. | 6 task-level evaluations | [`evals/`](evals/): semantic caching, state persistence, vague platform, timeout-retry, incremental rebuild, device dispatch |
  282. | A 135-row version ledger | [`references/verification-log.md`](references/verification-log.md): every measured run's version, how it was verified, what it covered — **and which branches still fail** |
  283. | CI | [`.github/workflows/ci.yml`](.github/workflows/ci.yml): on every push, self-consistency + reference-doc checks + reference integrity + eval-case validation |
  284. > **Exit code `0` only means "the script found nothing wrong"** — it does not mean the deliverable is good. The script's actual reach is documented in [`references/delivery-checklist.md`](references/delivery-checklist.md) §3–§4. This skill is pathologically wary of false green: the ledger records five separate occasions where it wrote a checker that silently checked nothing.
  285. ---
  286. ## Repository layout
  287. ```
  288. SKILL.md Main file: five-layer pipeline + gates + hard constraints (≈10K characters)
  289. README.md You are reading this (Chinese on top, English below)
  290. CHANGELOG.md User-visible changes only
  291. references/
  292. pipeline.md Flow diagram, 11-step execution sequence
  293. l0-question-bank.md L0 question bank (by domain, by gate)
  294. l1-search-recipes.md L1 search recipes (connector mapping, funnel, degradation)
  295. l2-extraction-protocol.md L2 code-reading protocol
  296. l3-mode-map.md L3 path spec (the triple, document structure, narrative line)
  297. gate4-adjudication.md Gate-4 adjudication rules
  298. delivery-checklist.md Pre-delivery checklist and reference matrix
  299. maintainer-notes.md **Read before editing SKILL.md**: claim-uniqueness table + maintenance discipline
  300. verification-log.md 135-row version ledger (honest, failures included)
  301. self_check.py 13 mechanical self-checks (stdlib only)
  302. examples/full-walkthrough.md End-to-end sample deliverable
  303. evals/ 6 task-level evaluations + harness.py
  304. ```
  305. ---
  306. ## Known limitations
  307. 1. **Hard dependency on the `github` connector** — without it only the degraded path runs; candidate coverage and ranking both drop, and the delivered document says so explicitly.
  308. 2. **Hard cap of 3 search rounds** — at three rounds it must put the candidates it has in front of the requester, not keep grinding on its own.
  309. 3. **The "requester can't answer" branch is untested** — the stop-loss rules never fire when the requester owns the project; be careful when running requirements for a non-technical third party.
  310. 4. **This skill does not implement code** — L3 output is handed to an execution-oriented skill such as `spec-development`.
  311. Unverified branches (🔴 blocks the flow / 🟡 degrades quality only) are listed one by one in [`references/verification-log.md`](references/verification-log.md).
  312. ---
  313. ## Contributing
  314. Before editing `SKILL.md` you **must** read [`references/maintainer-notes.md`](references/maintainer-notes.md). It documents the places this repository fails most often:
  315. - **A value may live in exactly one authoritative place** — the same number written twice and one copy updated is the single root cause behind every past regression here
  316. - Don't put values that move between releases (version numbers, interval endpoints, counts) in the body text
  317. - After any change, run `python references/self_check.py --skill SKILL.md` right away and **paste the output and exit code**
  318. - A change to a predicate that is never executed is not a change (the ledger records five incidents of exactly this)
  319. In a PR, say what you changed, why, and **which command you actually ran**.
  320. ---
  321. ## License
  322. [MIT](LICENSE) © 2026 zxd15978684198

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.