| name | 1k-jira-qa-handoff |
| description | Generate Chinese product behavior and QA cases from commits, then sync them to a Jira issue while preserving existing context and Slack links. |
Jira QA Handoff
Convert recent git commits on the current branch into a Chinese product-behavior summary + test cases, then sync them to the PM's task-type Jira issue. Designed for product managers who have shipped code changes themselves.
The team's flow: the PR title carries the PM's task-type Jira key → after PR merge, Jira automatically generates a downstream test-type issue for QA → QA reads the PM's task description to get context. So the description written here is what QA will end up reading.
Hard rules
- Output language for Jira content: 中文 (Simplified Chinese) — title, description, test cases. Never include code snippets, file paths, function names, line numbers, or implementation details. QA reads this; QA does not read code.
- Skill instructions stay in English (this file).
- Preserve any pre-existing context in the Jira issue when updating — Slack URLs, linked Jira issues, attached screenshots, @mentions, prior product decisions, and the existing title/description. This is the silent default; never ask "should I preserve this?" and never list what you're "not changing" before posting. Append, don't replace.
- One confirmation gate, then execute. Preview the proposed appended content once in Step 3. After the user approves, call the edit endpoint immediately — do not show a before/after diff, do not re-summarize what you're keeping.
- Trust the diff, but ask for product intent. Code shows what changed; only the PM knows why. If the intent is ambiguous, ask one clarifying question before drafting.
- Convert any relative dates ("today", "this week") to absolute dates (YYYY-MM-DD) before writing them into Jira.
When to skip
- Pure refactor / chore / dependency bump with no user-visible change → tell the user "no QA-visible behavior to hand off" and stop.
- Code-only fixes that already have a QA-owned Jira test issue → confirm with the user before duplicating.
Workflow
Copy this checklist into your reply at the start and tick items off as you go:
- [ ] Step 1: Determine commit range
- [ ] Step 2: Read commits and extract user-visible changes
- [ ] Step 3: Draft Chinese title + description (preview to user)
- [ ] Step 4: Sync to Jira (update existing OR create new)
- [ ] Step 5: Confirm result + return Jira URL
Step 1: Determine commit range
Default: commits unique to the current branch vs origin/x. Same scope as /1k-code-review-pr — if it just ran in this session, reuse its diff output.
git fetch origin x
git log origin/x..HEAD --pretty=format:"%h %s" --no-merges
git diff origin/x...HEAD --stat
Other cases:
- User specifies a commit hash or range → use that exact range.
- User on
x directly with uncommitted changes → use git diff --staged and git diff to capture the in-flight change; warn that nothing is committed yet.
- More than ~10 commits in the range → ask user whether to scope down (e.g., "only the last 3 commits", or "only commits touching
packages/kit/...").
Step 2: Extract user-visible changes
For each commit, read the diff itself (not just the message — messages lie or omit):
git show <hash> --stat
git show <hash> -- '<files of interest>'
For each change ask: what does the user see or do differently? Skip everything else.
| Code-level change | Becomes (in handoff) |
|---|
| Added new UI entry / button / page | New entry point + how to reach it |
| Changed copy / icon / layout | Visible change + before/after if known |
| Added analytics / logger call | "新增埋点" line in QA notes (no event-name code) |
| New i18n key | Confirm it renders in target locales |
| Refactor with same behavior | Skip — not QA-visible |
| Type / lint / build fix | Skip |
| Hidden flag / dev-only path | Skip unless PM says otherwise |
If you only find skip-category items, halt and report "no QA-visible behavior" instead of inventing test cases.
Step 3: Draft Chinese title + description
Use the Output Template below. Show it to the user as a preview block in chat. Wait for approval or edits before any Jira write.
Step 4: Sync to Jira
Branch on whether the user gave a Jira issue URL.
Path A — User gave a Jira issue URL
- Parse the issue key from the URL (e.g.,
https://onekeyhq.atlassian.net/browse/OK-53398 → OK-53398).
- Authenticate Atlassian MCP if needed (see "Atlassian MCP notes" below).
- Fetch the existing issue, then immediately call edit with: original title kept verbatim, description = original verbatim + appended block under
## 更新 YYYY-MM-DD — <brief>. Do not ask the user to re-confirm preservation, do not list "Title 不动 / Type 不动" decisions — these are the silent default.
- Only narrow exception (replace instead of append): existing description is literally empty (zero characters).
- Only ask the user when (a) issue type ≠ task/任务, or (b) the appended content semantically conflicts with PM's existing acceptance criteria.
Path B — No Jira URL given
- First check recent commits and the PR title for an existing
OK-XXXXX key (/1k-create-pr injects one). If found → switch to Path A with that key, do not create a duplicate.
- Authenticate Atlassian MCP if needed.
- Identify the project key. Default for this repo:
OK (verify against recent commits like (OK-53398) in messages). If unsure, ask.
- Confirm issue type with the user. Default: 任务 / Task. Ask before creating any other type (Bug / Story / Epic).
- Create the issue, return the URL.
Step 5: Confirm and return
Reply with the Jira URL + one-sentence summary (e.g., "已在 OK-53398 追加 1 个产品行为变更 + 2 个测试用例"); flag anything skipped.
Output Template (Chinese — copy verbatim)
Title format:
[模块] 一句话功能描述
Examples (real OneKey style):
[接收] 新增「其他交易所」入口和点击埋点[发送] ERC-1155 NFT 信息卡新增 Max 按钮[硬件] 切换系统主题时底部导航栏颜色未跟随
Description format:
## 产品行为变更
1. **<功能点 1>** — 从用户视角的一句话描述（看到什么、能做什么、与之前的差异）
2. **<功能点 2>** — 同上
3. ...
## 测试用例
### 用例 1：<场景名>
**前置条件**：<账户类型 / 网络 / 数据状态等，没有就写「无」>
**测试步骤**：
1. ...
2. ...
3. ...
**预期结果**：
- ...
- ...
**涉及平台**：☐ Desktop ☐ iOS ☐ Android ☐ Web ☐ Extension（勾选适用项）
### 用例 2：<场景名>
（同上结构）
## 关联 PR / Commit
- PR: <URL，如有>
- Commits: <短 hash 列表，如 `a3394702d5`、`daf8d7551d`>
## 备注（可选）
- 已知限制 / 后续待办 / 与其他模块的依赖等。没有就删掉这一节。
Test case rules: 2–4 cases per change. Cover (1) golden path, (2) per-platform branches if behavior differs, (3) visible negative path (precondition unmet). Skip internal-only checks — QA can't observe analytics fields or state machines; if 埋点 verification is required, add a 备注 directing the PM to the data team for Mixpanel event xxx.
Atlassian MCP notes
If unauthenticated, call mcp__atlassian__authenticate and follow its returned OAuth flow. After auth, the real Jira tools become deferred — load their schemas first:
ToolSearch(query="+atlassian jira", max_results=10)
Then call by fully-qualified names (mcp__atlassian__<tool_name>). Look for: get-issue-by-key, create-issue, update-issue, JQL-search.
Cloud ID gotcha: some Atlassian tools require a cloudId. If a call fails for that reason, find a getAccessibleAtlassianResources-like tool to fetch your sites and pick the matching one.
Anti-patterns
- ❌ Quoting commit messages verbatim as the title (commit messages are dev-facing; titles need product framing).
- ❌ Writing test cases that read like unit tests ("verify clickExchangeEntry called with exchangeSource='others'") — QA can't observe internal calls.
- ❌ Listing every locale as a test case ("测试中文", "测试英文", ...) — say "抽样验证 zh_CN / ja_JP / es" instead.
- ❌ Auto-creating a Jira issue without asking project key + type.
- ❌ Overwriting an existing Jira description without showing the diff to the user.
- ❌ Removing Slack thread URLs (or any prior links / @mentions / linked issues) from an existing Jira description when updating — they are upstream context the PM intentionally placed there. Always append, never strip.
- ❌ Asking "should I preserve your title/description?" or listing pre-write decisions like "Title 不动 / Type 不动 / Description 追加" — preservation is the silent default; restating it adds noise. Only flag genuine conflicts (issue type mismatch, semantic conflict with existing acceptance criteria).
Related skills
/1k-create-pr — create the PR before / after this handoff (also injects OK-XXXXX into the PR title)./1k-commit — produce the underlying commits this skill summarizes./1k-dev-commands — branch / commit conventions this skill assumes./1k-code-review-pr — independent diff review; useful before handoff to catch behavior changes you might have missed.
