85 lines
6.4 KiB
Markdown
85 lines
6.4 KiB
Markdown
|
---
|
||
|
|
id: 20260725-extend-tracker-skill-additively
|
||
|
|
title: 扩展 Issue Tracker Skill 时保留完整基线并做最小增量
|
||
|
|
created: 2026-07-25
|
||
|
|
updated: 2026-07-25
|
||
|
|
status: validated
|
||
|
|
scope: global
|
||
|
|
category: skill-design
|
||
|
|
confidence: high
|
||
|
|
last_verified: 2026-07-25
|
||
|
|
promotion_target: none
|
||
|
|
projects:
|
||
|
|
- matt-pocock-skills-feishu
|
||
|
|
tags:
|
||
|
|
- skill
|
||
|
|
- issue-tracker
|
||
|
|
- progressive-disclosure
|
||
|
|
- regression-prevention
|
||
|
|
---
|
||
|
|
|
||
|
|
# 扩展 Issue Tracker Skill 时保留完整基线并做最小增量
|
||
|
|
|
||
|
|
## Trigger
|
||
|
|
|
||
|
|
当用户要求“在现有 setup skill 基础上增加一个 tracker/provider 选项”，并期望新 skill 保留原工作流和原模板行为时，召回这条经验。
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
第一次实现把飞书版 skill 写成了一个压缩后的独立工作流，并通过相邻路径引用原 setup skill。它在概念上覆盖了原流程，但没有完整保留原 `SKILL.md` 的文字约束和五个 seed 文件。用户明确纠正：新 skill 应先完整对齐原 Matt skill，再增加 `references/issue-tracker-feishu.md`，并把原来的三个正式 tracker 模板扩展为第四个飞书选项。
|
||
|
|
|
||
|
|
最终实现以原 skill 整个目录为基线，保持 GitHub、GitLab、local、triage labels 和 domain 模板不变，仅在 `SKILL.md` 的 tracker 介绍、选择、确认、写入和完成验证处加入飞书条件分支，并把飞书细节放入一层 reference。
|
||
|
|
|
||
|
|
同日的第二个扩展场景把该原则应用到三个运行期 skill：`to-spec-feishu`、`to-tickets-feishu`、`triage-feishu`。每个新 skill 以对应原 Matt skill 的完整正文为基线，只增加一条必须读取 `references/feishu.md` 的接缝；`triage` 的 `AGENT-BRIEF.md` 和 `OUT-OF-SCOPE.md` 保持逐字节一致。飞书的发布顺序、查重、两遍关系写入、时间门禁和 Wiki 降级策略全部留在 reference 中。
|
||
|
|
|
||
|
|
## Evidence
|
||
|
|
|
||
|
|
- 用户在 2026-07-25 两次指出结构要求：保留 `issue-tracker-feishu.md`；新 skill 必须完整对齐 `/Users/yuxuanhui/.agents/skills/setup-matt-pocock-skills` 后再补充飞书。
|
||
|
|
- 最终目录中的 `issue-tracker-github.md`、`issue-tracker-gitlab.md`、`issue-tracker-local.md`、`triage-labels.md`、`domain.md` 与原 skill 逐字节一致。
|
||
|
|
- `SKILL.md` 的 diff 只包含名称/描述兼容调整和飞书在 Section A、确认、模板、完成验证中的增量。
|
||
|
|
- `quick_validate.py` 输出 `Skill is valid!`，且目录无 `TODO` 占位符。
|
||
|
|
- 原 skill 使用的旧 frontmatter 字段 `disable-model-invocation` 被当前 validator 拒绝；新 skill 通过 `agents/openai.yaml` 的 `policy.allow_implicit_invocation: false` 保留等价行为。
|
||
|
|
- `to-spec-feishu`、`to-tickets-feishu`、`triage-feishu` 均通过 `quick_validate.py`，无 `TODO`；三个 `agents/openai.yaml` 均显式禁止隐式调用。
|
||
|
|
- 三个原 Matt skills 未修改；新 skill 主正文只新增飞书 reference 读取接缝，原有交互门禁、测试 seam、拆票确认和分诊角色语义保留。
|
||
|
|
- `triage-feishu/AGENT-BRIEF.md` 与原文件、`triage-feishu/OUT-OF-SCOPE.md` 与原文件分别通过字节级比较。
|
||
|
|
- 真实 POC 验证 reference 不是静态说明：Spec 发布、Ticket 两遍关系写入、Triage `needs-info → feedback → ready-for-agent` 均按新 reference 执行并回读；独立 Wiki 新建受平台限制时，降级和未满足项也按 reference 记录。
|
||
|
|
|
||
|
|
## Root cause
|
||
|
|
|
||
|
|
已验证：把“在原 skill 基础上增加”理解为“运行时引用原 skill 并重写一个更短版本”，会丢失用户期望的文本级约束、配套模板和可独立运行性。概念等价不等于产物级对齐。
|
||
|
|
|
||
|
|
推断：tracker 是一个可变适配点，但 setup 的探索、交互顺序、文件选择和消费者契约属于稳定基线。若同时重写两者，未来很难区分是 provider 变化还是基础流程回归。
|
||
|
|
|
||
|
|
已验证：同一“完整基线 + 单一 provider 接缝 + provider reference”结构不仅适用于 setup，也适用于依赖 tracker 的运行期 skills。这样可以分别验证 Matt 核心语义和外部系统副作用，而不把 CLI 细节散落到主流程。
|
||
|
|
|
||
|
|
## Failed approaches
|
||
|
|
|
||
|
|
- 将飞书操作链全部塞进主 `SKILL.md`：主文件偏离原 setup，且 provider 细节挤占上下文。
|
||
|
|
- 让新 skill 只读取相邻原 skill：减少了重复，但不满足用户要求的完整基线和独立配套资源。
|
||
|
|
- 手工重述原流程：即使语义接近，也会产生措辞、边界和模板缺失。
|
||
|
|
|
||
|
|
## Preferred action
|
||
|
|
|
||
|
|
1. 先复制原 skill 的完整目录作为新 skill 基线，包括主文件和全部 seed/template 文件。
|
||
|
|
2. 对不属于新 skill 身份的 metadata 做最小兼容调整；若旧字段被当前 validator 拒绝，用当前受支持的等价配置替代并记录原因。
|
||
|
|
3. 只在明确的变体接缝增加 provider：选项列表、provider 输入、写前草稿、模板路由和 provider 专属完成门槛。
|
||
|
|
4. 把长篇 CLI 命令、schema、状态机、已知版本边界放进 `references/<provider>.md`；在 `SKILL.md` 中明确何时必须完整读取它。
|
||
|
|
5. 保留 `Other` 作为自由格式兜底，不把它误算为正式模板。原三个正式模板加飞书等于四个受支持模板。
|
||
|
|
6. 用三类检查防止回归：
|
||
|
|
- `diff`：确认主 skill 只改了预期接缝；
|
||
|
|
- `cmp`：确认原 seed 文件逐字节一致；
|
||
|
|
- `quick_validate.py` 与占位符搜索：确认结构有效且无残留模板内容。
|
||
|
|
7. 对带附属模板的 skill，再对每个模板做字节级比较；不要只比较 `SKILL.md`。
|
||
|
|
8. 用一个最小真实 POC 验证 reference 中的外部副作用顺序。校验器通过只能证明结构有效，不能证明 provider 工作流可运行。
|
||
|
|
|
||
|
|
## Boundaries
|
||
|
|
|
||
|
|
- 当用户明确接受依赖式组合、且基线 skill 会持续独立升级时，可以只引用基线 skill；不要默认复制。
|
||
|
|
- 当 provider 需要改变基础探索、交互顺序或消费者语义时，不能强行维持最小 diff，应先确认这是新工作流还是原工作流的变体。
|
||
|
|
- 不要为了“完整对齐”复制当前校验器明确拒绝的旧 metadata；应保留行为等价性并记录兼容差异。
|
||
|
|
- provider reference 可以定义外部系统的失败降级，但不能削弱原 skill 的用户确认门禁，也不能把未完成的外部产物描述为成功。
|
||
|
|
|
||
|
|
## Promotion record
|
||
|
|
|
||
|
|
- Not promoted. 该原则已在 setup 与三个运行期 tracker skills 两类场景落地并通过真实 POC，学习状态提升为 validated；尚未扩展第二种 provider，因此暂不写入全局 skill-creator guardrail。
|