用途:捕获“消费方视角”的摩擦点——即外部使用者也会遇到的意外失败模式、未文档化行为、自己写的变通方法,或与 CLI/运行时/文档不一致的心智模型。适用于编写扩展、跑示例应用、复现客户报告、跑集成测试等消费公开接口的场景;不适用于修复本团队维护代码中的普通缺陷、主观偏好或第三方工具自身的问题。
主要能力:判断当前属于产品团队仓库还是其他仓库;在产品团队仓库中向操作者暴露摩擦点并提供三条路径(记录为 gotcha、提交普通缺陷、记录后跳过),其他仓库则静默记录;在对应 Linear 项目中搜索重复工单;按模板起草条目并追加到 gotchas.md 或按产品分文件;提交 Triage 状态、无优先级、无标签的 Linear 工单并与文件条目互相链接;最后按约定提交一次 commit。
使用方式:需先安装并认证 Linear MCP 插件(plugin-linear-linear);若不可用则停止,不写文件条目不建工单。然后确认产品(Prisma Next→pn-gotchas、Prisma Compute→compute-gotchas、Prisma Postgres→ppg-gotchas),确定升级模式,查重,选择本地记录文件,按模板写 10–25 行条目,建工单,回填 Filed upstream,提交。提交信息形如 docs(gotcha): record <one-line title>。
限制:技能仅覆盖上述三个 Prisma 产品;跨产品时只在一处记录并在正文提及另一个;第三方工具问题走其自己的跟踪器(例外:仅因 Prisma 产品结构才暴露的问题记在 Prisma 侧并链接第三方跟踪器);文档已覆盖的误解不记录;工单与文件条目必须同时存在,缺一不可。