Stats
Actions
Tags
From claude-skills
Post a tester-facing comment on a YouTrack issue via the pp-youtrack MCP server. Reads the task's Obsidian plan docs (root-cause.md + fix-plan.md for bugs, plan.md for features) and summarizes them in a voice appropriate for QA: plain language, just enough technical detail (URLs, modules, scenarios) to be useful, but no deep internals. Comment is always written in Chinese. Narrow scope — only comment posting. State transitions live in pp-youtrack-state.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claude-skills:pp-youtrack-comment-to-testThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**只做一件事**:把一个已经在 Obsidian vault 里写完设计/计划的任务,以**测试人员能看懂的方式**总结出来,作为评论发布到对应的 YouTrack issue 上。
只做一件事:把一个已经在 Obsidian vault 里写完设计/计划的任务,以测试人员能看懂的方式总结出来,作为评论发布到对应的 YouTrack issue 上。
典型场景:
/code-execute 跑完、review 通过、状态已流转到 自测,紧接着告诉测试这个任务要怎么测不管状态流转(那是 pp-youtrack-state 的事),不管创建 issue,不做代码 review。职责就是:读文档 → 总结 → 让 codex 对照真实仓库逻辑校验 → 发评论。
不适用于 Atlassian Jira 任务。
mcp__pp-youtrack__add_issue_comment MCP 工具已加载obsidian-lookup skill 已加载(用来找 vault 里的任务文件夹)codex:rescue skill 已加载(用于 Step 4.5 的逻辑校验)root-cause.md + fix-plan.md;feature: plan.md)调用方传入:
| 字段 | 必须 | 说明 |
|---|---|---|
task-id | 是 | YouTrack issue id,例如 PP-123。用于定位 vault 文件夹和最终的 add_issue_comment 调用 |
project | 否 | vault 里的 project 名(例如 pp),用来缩小 obsidian-lookup 范围。不传时本 skill 会按 task-id 全 vault 查找 |
不接受其他参数。评论一律用中文,内容格式与写作风格由本 skill 按下面的规则自动决定。
通过 obsidian-lookup skill 按 task-id 找任务文件夹。按 category 读取对应的两份主文档:
root-cause.md(设计/诊断) + fix-plan.md(执行计划)plan.md(设计+计划)如果任一主文件缺失或仍是空骨架(只有模板 header 和未替换的 {{...}} 占位符),停下用 AskUserQuestion 告诉用户:"任务文档还没填完整,无法给测试写一份有意义的总结。请先完成 <列出缺失的文件>。" 绝不基于空文档硬编一个评论。
如果 obsidian-lookup 返回多个候选(task-id 在多个 project 下都存在),停下用 AskUserQuestion 让用户选一个,不默认取第一个。
调 mcp__pp-youtrack__get_issue(task-id) 拿 issue 的 summary 和 web 链接,后续 Step 6 要用。评论语言固定中文,不做语言判断。
核心原则:你是在写给测试看,不是给开发看。
测试关心的 4 件事,按这个顺序从文档里找信息:
为什么发生(why):问题是什么 / 需求是什么
root-cause.md 的"表面现象"和"根本原因"提炼。用一句话说清楚"用户遇到了什么"和"代码层面是什么原因"plan.md 的"背景"和"方案"提炼。用一两句说清楚"这个新功能在干什么"怎么测(how to test):怎么复现或验证
root-cause.md 的"表面现象"里的复现路径 + fix-plan.md 的"验证方式"。写成有序步骤,每一步具体到"点击哪里"、"输入什么"plan.md 的"验证"。描述测试入口、正向用例、反向用例是否影响其他功能(regression surface):可能的回归面
fix-plan.md 的"需要修改的文件和具体改动"看改动涉及的模块/组件。用模块名或功能域表达,例如"改动影响了 Player Career 页的 stats 渲染逻辑,建议同步回归 Player Profile、Squad 列表这类也用 stats 数据的页面"plan.md 的"风险"提炼修复方向(fix direction):开发做了什么
fix-plan.md 的"修复方案"一句话总结"我们怎么修的"。不要贴代码,不要提函数名,最多提"在 X 页 / Y 流程 / Z 接口这块加了空值判断 / 加了 retry / 调整了调用顺序"这种级别plan.md 的"步骤"总结"这次加了什么、改了什么、用了哪些现有机制"## {{title-一句话}}
**发生原因**
{{why-一到两句白话描述 + 必要时的技术点,例如"某个接口返回了空数据,页面没做空判断"}}
**修复方向**
{{fix-direction-一到两句描述修了什么,例如"在 Player Career 页加了 stats 字段的空值兜底,空数据时显示占位 UI"}}
**怎么测**
1. {{step-1,具体到点击/输入/观察}}
2. {{step-2}}
3. {{step-3 验证点}}
{{如果有明显的反向用例,额外加一段 "边界情况" 列表}}
**回归建议**
- {{regression-area-1,例如 "Player Profile 页的 stats 展示"}}
- {{regression-area-2,例如 "Squad 列表里的球员数据"}}
{{如果没有明显的回归面,写一行 "本次改动范围很小,未发现明显回归面" 然后略过}}
fix-plan.md 里有代码 block,也只在模板里描述"做了什么级别"的改动,不贴原文/api/v3/players/{id}/stats)、HTTP 方法、错误码、页面/模块/功能域名字、数据字段名(stats、career.matches)——只要测试能用来定位或验证~/obsidian/... 类绝对路径、projects/<...>/bugs/<...>/root-cause.md 类相对路径、[[wikilink]] 形式的 Obsidian 内链)——这些只在本机可解析,YouTrack 上的测试看不到也找不到,贴上去就是噪声{{...}} 占位符必须被真实内容替换。Regression 部分如果真的没有明显回归面,用 "本次改动范围很小,未发现明显回归面" / "no significant regression surface" 填上,不要删 section评论组装好之后,在给用户确认之前,把整段 comment 草稿连同两份 plan 文档交给 codex:rescue skill,让它对照真实仓库校准逻辑。这一步强制,不允许跳过。
用 Skill 工具调 codex:rescue,绝不用 Agent 工具(同 code-execute 的硬规则)。args 里附上以下内容:
== 任务 ==
你是这条 YouTrack 评论的逻辑校验员。我会给你一段已经写好的 comment 草稿、对应任务的 Obsidian 文档(bug: root-cause.md + fix-plan.md;feature: plan.md),以及当前代码仓库的绝对路径。你的工作是**只读校验**,不要修改任何文件。
== Task ID ==
<task-id>
== Comment 草稿 ==
<把组装好的 comment 完整粘贴进来,不要省略>
== Plan 文档路径 ==
- 设计/诊断: <绝对路径 to root-cause.md 或 plan.md>
- 执行计划: <绝对路径 to fix-plan.md>(仅 bug 场景)
(请用 Read 工具自行读取)
== 仓库路径 ==
<repo 绝对路径>
== 校验项(逐条回答) ==
1. **测试步骤的可操作性**:草稿里"怎么测"section 的每一步,在当前仓库里是否真实存在? 例如它说"打开 Player Career 页",这个页面/路由/Tab 入口在代码里能找到吗? 它说"点击 share 按钮",这个按钮在最新 diff 之后是否真的在那个页面上? 不存在或位置不对的步骤,**列出来并指出实际入口**
2. **问题陈述的准确性**:草稿里"发生原因"是否和 root-cause.md(bug)或 plan.md(feature)文档里描述的一致? 有没有过度简化以至于失真? 有没有添加文档里没有的猜测?
3. **修复方向的准确性**:草稿里"修复方向"是否和 fix-plan.md(bug)或 plan.md(feature)里的实际改动一致? `git diff HEAD` 实际改了什么 vs 草稿里说改了什么——有没有不符? 有没有遗漏关键的改动域?
4. **回归面的真实性**:草稿里"回归建议"列出的每个区域,在仓库里是否真的会被本次改动影响? 用 grep 验证那些模块/页面是否真的依赖被改的代码路径。**列错的回归面比漏列更糟**——会让测试浪费时间
5. **覆盖完整性**:fix-plan/plan 里描述的所有验证点,草稿是否都覆盖到了? 有没有重要的验证场景被漏掉?
6. **本地路径检查**:草稿里有没有出现 `~/obsidian/...`、`projects/.../*.md`、`[[wikilink]]` 这类本地路径(硬规则禁止)? 有就指出来
== 输出格式 ==
按校验项编号回复,每条给一个判定:
- ✅ 通过 — 简短说明为什么没问题
- ⚠️ 有问题 — 详细说明问题,**给出文件路径 + 行号 + 原代码片段**作为证据,以及建议怎么修
- ❓ 信息不足 — 哪里需要更多信息才能判断
最后给一个 overall verdict:
- **PASS**:可以发布
- **NEEDS REVISION**:列出必须修的项
- **BLOCK**:存在严重事实错误,不能在当前内容上小修小补,需要回去重新提炼
只读校验,不要改任何文件,不要 stage,不要 commit。
AskUserQuestion 把 codex 的意见和当前草稿一起贴给用户,让用户决定接管手写还是放弃AskUserQuestion 把 codex 的 BLOCK 原因贴给用户,选项:回去补 Obsidian 文档 / 用户接管手写 / 放弃。不要在 BLOCK 状态下试图自己改这一步不向用户中断(除了 NEEDS REVISION 3 轮上限或 BLOCK 的情况)。codex 校验是后台逻辑工序,只有它通过/卡死时才走用户层。
组装好评论内容后,调用:
mcp__pp-youtrack__add_issue_comment(
issue_id = "<task-id>",
text = "<组装好的 markdown 评论内容>"
)
发布前先把完整评论内容在对话里展示给用户,并用 AskUserQuestion 问一次 "确认发布 / 修改 / 取消",因为评论是外部可见动作,不能静默推送。
add_issue_comment发布失败时把 MCP 错误贴出来,用 AskUserQuestion 让用户决定重试 / 手动到 YouTrack 贴 / 放弃。
发布成功后:
<task-id>pp-youtrack-state skill 的事,调用方决定要不要在本 skill 之后再跑一次状态流转~/obsidian/... 这种 home 路径、projects/spfc/bugs/SPFC-18/root-cause.md 这种 vault 相对路径,还是 [[wikilink]] 这种 Obsidian 内链,一律不允许出现在评论正文里。原因:YouTrack 评论是给团队/客户/测试看的外部内容,这些路径在他们机器上不存在,既无法点击也无法理解。本地文档是写评论的信息源,不是评论的引用目标——把信息提炼进评论里,然后让源文档留在本地code-execute command 可以在 Step 6 之后可选地调用本 skillnpx claudepluginhub sampeng87/skills --plugin claude-skillsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.