Files

T

yuxuanhui 6e0c5c35fc Add documentation for the three-stage development workflow and CLI management strategy; create a new notes file for additional insights.

2026-08-03 16:17:16 +08:00

6.4 KiB

Raw Permalink Blame History

id, title, created, updated, status, scope, category, confidence, last_verified, promotion_target, projects, tags

title

created

updated

status

scope

扩展 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

先复制原 skill 的完整目录作为新 skill 基线，包括主文件和全部 seed/template 文件。
对不属于新 skill 身份的 metadata 做最小兼容调整；若旧字段被当前 validator 拒绝，用当前受支持的等价配置替代并记录原因。
只在明确的变体接缝增加 provider：选项列表、provider 输入、写前草稿、模板路由和 provider 专属完成门槛。
把长篇 CLI 命令、schema、状态机、已知版本边界放进 references/<provider>.md；在 SKILL.md 中明确何时必须完整读取它。
保留 Other 作为自由格式兜底，不把它误算为正式模板。原三个正式模板加飞书等于四个受支持模板。
用三类检查防止回归：
- diff：确认主 skill 只改了预期接缝；
- cmp：确认原 seed 文件逐字节一致；
- quick_validate.py 与占位符搜索：确认结构有效且无残留模板内容。
对带附属模板的 skill，再对每个模板做字节级比较；不要只比较 SKILL.md。
用一个最小真实 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。

6.4 KiB Raw Permalink Blame History