1k-jira-qa-handoff

name	1k-jira-qa-handoff
description	Generates a Chinese product-behavior summary + test cases from git commits and syncs them to the PM's Jira task issue (update or create), preserving any existing Slack URLs and prior context. Use after the PM commits/PRs code. Triggers on "同步 Jira / 写到 Jira / 给 QA 写测试用例 / PM 交付 / jira QA handoff / 创建 Jira issue / 更新 Jira"; or when the user supplies a Jira URL with "总结改动" / "写测试用例".

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

1. Parse the issue key from the URL (e.g., https://onekeyhq.atlassian.net/browse/OK-53398 → OK-53398).
2. Authenticate Atlassian MCP if needed (see "Atlassian MCP notes" below).
3. 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

1. 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.
2. Authenticate Atlassian MCP if needed.
3. Identify the project key. Default for this repo: OK (verify against recent commits like (OK-53398) in messages). If unsure, ask.
4. Confirm issue type with the user. Default: 任务 / Task. Ask before creating any other type (Bug / Story / Epic).
5. 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-git-workflow — branch / commit conventions this skill assumes.
• /1k-code-review-pr — independent diff review; useful before handoff to catch behavior changes you might have missed.