inkblot-jira-ticket

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Inkblot Jira Ticket Convention

Inkblot Jira工单编写规范

When creating or editing a ticket, structure the description exactly as below. Fixed heading names — do not rename, reorder, or invent sections.

创建或编辑工单时，请严格按照以下结构撰写描述。标题名称固定——请勿重命名、调整顺序或新增章节。

Three hard rules

三条硬性规则

NO PII or PHI in tickets — ever. No patient/client names, emails, phone numbers, health card numbers, diagnoses, session content, or anything identifying a person. Refer to people by role + opaque ID (e.g. "client user_id 12345", "appointment 977096", support ref "ATS-13371"). Redact identifying details from screenshots, logs, and stack traces before attaching. This applies to every section, including Engineering Notes and comments.
Acceptance criteria MUST live in the description body under a
```
## Acceptance criteria
```
heading, as a checklist. Write the description as ADF (
```
contentFormat: "adf"
```
) and render the criteria as a real, tickable
```
taskList
```
— see "Jira specifics" for the how. NEVER put them only in Jira's side-panel "Acceptance criteria" checklist field — QA, exports, PR links, and AI tools miss it there.
```
## Context
```
,
```
## Scope
```
,
```
## Acceptance criteria
```
, and
```
## How to test
```
(when present) MUST use plain, human-friendly language that non-technical readers (QA, PM, support) can understand. Anything that only makes sense to developers — code paths, class/function names, SQL, stack traces, architecture detail — belongs under
```
## Engineering Notes
```
, below the
```
---
```
divider.

严禁在工单中包含任何PII或PHI信息——绝不允许。不得出现患者/客户姓名、邮箱、电话号码、医保卡号码、诊断结果、会话内容或任何可识别个人身份的信息。请以角色+匿名ID指代相关人员（例如："用户user_id 12345"、"预约977096"、支持工单编号"ATS-13371"）。在添加截图、日志和堆栈跟踪前，请先编辑掉可识别身份的信息。此规则适用于所有章节，包括「工程笔记」和评论。
验收标准必须位于描述主体的
```
## Acceptance criteria
```
标题下，以清单形式呈现。请将描述以ADF格式（
```
contentFormat: "adf"
```
）编写，并将标准渲染为可勾选的真实
```
taskList
```
——具体方法请查看「Jira专属说明」。绝对不要仅将验收标准放在Jira侧边栏的「验收标准」清单字段中——QA、导出内容、PR链接和AI工具都无法在该位置获取到这些信息。
```
## Context
```
、
```
## Scope
```
、
```
## Acceptance criteria
```
以及
```
## How to test
```
（如有）必须使用通俗易懂的语言，确保非技术人员（QA、产品经理、支持人员）能够理解。仅对开发人员有意义的内容——如代码路径、类/函数名称、SQL语句、堆栈跟踪、架构细节——应放在
```
---
```
分隔线下方的
```
## Engineering Notes
```
章节中。

Template: Task / Story

模板：任务 / 用户故事

markdown

undefined

markdown

undefined

Context

Why this exists, 2–4 lines, in plain language. If there is a real end user, open with: "As a <user>, I want <goal> so that <value>." Otherwise plain prose — never force a user story.

说明工单存在的原因，2-4行，语言通俗易懂。如果涉及真实终端用户，请以如下格式开头： "作为<用户角色>，我希望<达成目标>，以便<获得价值>。" 否则请使用普通叙述性文字——不要强行套用用户故事格式。

Scope

What's in. What's explicitly out. Described as user/system behavior, not implementation.

包含的内容。明确排除的内容。请以用户/系统行为描述，而非实现细节。

Acceptance criteria

Testable, QA-facing statements written as observable behavior
Include env / feature-flag prerequisites QA needs

可测试、面向QA的陈述，以可观察的行为表述
包含QA所需的环境/功能标志前提条件

How to test

(Optional — include ONLY when the user explicitly asks for it. When present, follow "How to test — writing guidance": numbered steps naming the exact app + URL, dev-tools Network steps, the exact request/host, and the response field + expected values. Omit by default.)

（可选——仅在用户明确要求时添加。若添加，请遵循「测试方法编写指南」：以编号步骤列出具体应用+URL、开发者工具网络步骤、具体请求/主机，以及响应字段+预期值。默认情况下无需添加。）

Engineering Notes

(Optional, ALWAYS last, after the --- divider.) Root cause analysis, code paths, PR/branch links, implementation ideas, migration/rollback steps, log/NewRelic links. Nothing QA needs may live here.

undefined

（可选，始终放在最后，位于---分隔线下方。）根本原因分析、代码路径、PR/分支链接、实现思路、迁移/回滚步骤、日志/NewRelic链接。QA无需查看的内容均应放在此处。

undefined

Template: Bug

模板：Bug

markdown

undefined

markdown

undefined

Steps to reproduce

Expected

What should happen.

预期结果。

Actual

What happens instead (screenshots / errors).

实际发生的情况（截图/错误信息）。

Environment

Env:
Browser / client:
Account / feature flags:

环境：
浏览器/客户端：
账号/功能标志：

Acceptance criteria

The observable behavior that proves the fix

可证明问题已修复的可观察行为

How to test

(Optional — include ONLY when the user explicitly asks for it. When present, follow "How to test — writing guidance": exact app + URL, Network-tab steps, exact request/host, response field + expected values.)

（可选——仅在用户明确要求时添加。若添加，请遵循「测试方法编写指南」：列出具体应用+URL、网络面板步骤、具体请求/主机、响应字段+预期值。）

Engineering Notes

(Optional, last — root cause, suspect code, links.)

undefined

（可选，放在最后——根本原因、疑似代码、相关链接。）

undefined

Bugs a human cannot reproduce (infra / outages / race conditions)

人工无法复现的Bug（基础设施/故障/竞态条件）

If the repro is not something a person can perform on demand (an upstream outage, a server restart, a timing race, corrupted state), do NOT write pseudo-repro steps. Replace

## Steps to reproduce

with

## What happened

— a short plain-language narrative of the incident and its user-visible impact ("During the X outage on <date>, some users experienced …"). Keep

## Expected

## Actual

focused on symptoms.

## How to test

lists only checks QA can actually perform; the technical trigger conditions and any dev-only verification (logs, Redis, metrics) go under

## Engineering Notes

如果Bug无法由人工按需复现（如上游故障、服务器重启、时序竞态、状态损坏），请勿编写虚假的复现步骤。将

## Steps to reproduce

替换为

## What happened

——用简短的通俗语言叙述事件及其对用户可见的影响（例如："在<日期>的X故障期间，部分用户遇到了……"）。

## Expected

## Actual

请聚焦于症状。

## How to test

仅列出QA实际可执行的检查；技术触发条件及仅开发人员可进行的验证（日志、Redis、指标）请放在

## Engineering Notes

中。

Template: Spike

模板：研究任务（Spike）

markdown

undefined

markdown

undefined

Question

What we need to answer.

我们需要解答的问题。

Timebox

e.g. 2 days.

例如：2天。

Deliverable

Doc / decision / prototype / follow-up tickets.

undefined

文档/决策/原型/后续工单。

undefined

How to test — writing guidance

测试方法编写指南

## How to test

is optional (include only when the user asks for it), but when present it MUST be concrete enough that a QA tester who has never seen the code can follow it step-by-step. Write it as a numbered list. Be specific, not vague — never just "open the web app."

For any behavior observable in the UI or an API response, follow this pattern:

Name the exact app the tester opens and its URL (e.g. the Practice app at
```
https://practice.inkblottherapy.com
```
, the client web app, or the mobile app + which build). Say which environment (staging vs prod) and, if it matters, which test account/role.
State any setup: data to pick (by opaque ID), feature flags to toggle, preconditions.
If the check is in a network response, tell them to open browser dev tools (right-click → Inspect / F12) → Network tab and reload.
Identify the exact request — method + full path, and the host it goes to (e.g.
```
https://api.inkblottherapy.com/api/appointments/{id}
```
) — and how to find it (filter box keyword). Then open the Response / Preview tab.
Name the specific field(s) to check and the expected value(s) for each state (e.g.
```
video_provider
```
=
```
vonage
```
when the flag is on,
```
twilio
```
when off).
Give the verify loop: toggle the flag / change the input, reload, confirm the value changes as expected. Add a second independent signal where possible (e.g. a related endpoint returning 200 vs 404).

Keep every step above the

---

in language QA understands; push dev-only verification (logs, Redis, metrics, DB queries) into

## Engineering Notes

## How to test

为可选内容（仅在用户要求时添加），但添加时必须足够具体，确保从未接触过代码的QA测试人员能够一步步遵循操作。请以编号列表形式编写。内容要具体，避免模糊——绝不要只写「打开Web应用」。

对于UI或API响应中可观察到的任何行为，请遵循以下模式：

明确测试人员需打开的具体应用及其URL（例如：Practice应用，地址为
```
https://practice.inkblottherapy.com
```
；客户端Web应用；或移动应用+具体版本）。说明环境（预发布环境vs生产环境），如有必要，说明测试账号/角色。
说明任何前置设置：需选择的数据（通过匿名ID）、需切换的功能标志、前置条件。
如果检查内容在网络响应中，请告知测试人员打开浏览器开发者工具（右键→检查/F12）→网络面板并重新加载页面。
指明具体请求——方法+完整路径，以及请求的主机（例如：
```
https://api.inkblottherapy.com/api/appointments/{id}
```
），并说明如何找到该请求（筛选框关键词）。然后打开响应/预览标签页。
指明需检查的具体字段以及每种状态下的预期值（例如：当功能标志开启时，
```
video_provider
```
=
```
vonage
```
；关闭时，
```
video_provider
```
=
```
twilio
```
）。
说明验证循环：切换标志/更改输入，重新加载页面，确认值按预期变化。尽可能添加第二个独立验证信号（例如：相关端点返回200 vs 404）。

---

分隔线以上的所有步骤请使用QA能理解的语言；仅开发人员可进行的验证（日志、Redis、指标、数据库查询）请放入

## Engineering Notes

中。

Authoring rules

编写规则

QA reads top-down and stops at the
```
---
```
divider. Everything above it must be understandable without reading code or knowing the codebase.
Engineering Notes is the pressure valve: put ALL technical detail there, not interleaved through the ticket. When in doubt whether something is "too technical", move it to Engineering Notes.
Summary (title): concise, imperative, specific. No trailing period.
Do not bulk-backfill old/closed tickets. Reformatting open, not-yet-started tickets is fine when the assignee asks for it.

QA会从上到下阅读工单，读到
```
---
```
分隔线时停止。分隔线以上的所有内容必须无需查看代码或了解代码库即可理解。
工程笔记是技术细节的专属区域：所有技术细节都应放在此处，不要穿插在工单其他部分。若不确定内容是否「过于技术化」，请将其移至工程笔记。
摘要（标题）：简洁、祈使语气、具体。末尾不要加句号。
不要批量回填旧的/已关闭的工单。当经办人要求时，可重新格式化已打开但尚未开始处理的工单。

Jira specifics (inkblottherapy.atlassian.net)

Jira专属说明（inkblottherapy.atlassian.net）

Projects are company-managed / classic (POD2 project id 10013).
POD2 Story Points field is
```
customfield_10033
```
(NOT customfield_10016). Verify the Story Points field per project via createmeta before setting points elsewhere.
Checkboxes (standard): always create/edit the description as ADF (
```
contentFormat: "adf"
```
) and render
```
## Acceptance criteria
```
as a
```
taskList
```
of
```
taskItem
```
nodes (each with
```
attrs.localId
```
and
```
state: "TODO"
```
) — this reliably produces real, tickable Jira checkboxes (verified by write-then-read-back). Do NOT rely on the markdown
```
- [ ]
```
path: it is inconsistent (sometimes a real task list, sometimes literal
```
[ ]
```
text). Only if ADF is truly unavailable, fall back to plain
```
*
```
bullets.
Collapsible Engineering Notes (optional): to keep technical detail tucked away by default,
```
## Engineering Notes
```
may be rendered as an ADF
```
expand
```
node instead of a plain heading —
```
{ "type": "expand", "attrs": { "title": "Engineering Notes" }, "content": [ ...block content... ] }
```
, placed below the
```
---
```
divider. When you do this, the expand's
```
title
```
replaces the heading (don't emit both a
```
## Engineering Notes
```
heading AND an expand titled the same). Requires
```
contentFormat: "adf"
```
: the markdown path silently flattens
```
expand
```
, dropping the collapsible wrapper and hoisting its content inline. The collapse is purely visual in the Jira web UI — the content is always returned in full by the API (verbatim in an ADF fetch, hoisted inline in a markdown fetch), so any AI agent reading the ticket still sees the notes. Verify persistence by re-fetching with
```
responseContentFormat: "adf"
```
(the tool echoes the saved description as markdown, which flattens
```
expand
```
, so the markdown echo alone can't confirm the node saved).

项目为公司管理/经典类型（POD2项目ID为10013）。
POD2的Story Points字段为
```
customfield_10033
```
（而非customfield_10016）。在其他项目设置故事点数前，请通过createmeta验证对应项目的Story Points字段。
复选框（标准）：始终以ADF格式（
```
contentFormat: "adf"
```
）创建/编辑描述，并将
```
## Acceptance criteria
```
渲染为
```
taskList
```
类型的
```
taskItem
```
节点（每个节点包含
```
attrs.localId
```
和
```
state: "TODO"
```
）——这样能可靠生成可勾选的真实Jira复选框（已通过写入后读取验证）。不要依赖markdown的
```
- [ ]
```
格式：该格式表现不一致（有时是真实任务列表，有时是字面意义的
```
[ ]
```
文本）。只有在确实无法使用ADF时，才退而使用普通的
```
*
```
项目符号。
可折叠工程笔记（可选）：若希望默认隐藏技术细节，可将
```
## Engineering Notes
```
渲染为ADF的
```
expand
```
节点，而非普通标题——格式为
```
{ "type": "expand", "attrs": { "title": "Engineering Notes" }, "content": [ ...块内容... ] }
```
，放在
```
---
```
分隔线下方。采用此方式时，expand的
```
title
```
将替代标题（不要同时显示
```
## Engineering Notes
```
标题和同名的expand组件）。此方式需要使用
```
contentFormat: "adf"
```
：markdown格式会自动展开
```
expand
```
节点，丢弃可折叠包装器并将内容直接显示。折叠仅在Jira网页UI中是视觉效果——API始终会返回完整内容（ADF获取时原样返回，markdown获取时内容被直接显示），因此读取工单的AI Agent仍能看到笔记内容。请通过
```
responseContentFormat: "adf"
```
重新获取工单以验证内容是否保存成功（工具会将保存的描述转换为markdown返回，而markdown会展开
```
expand
```
节点，因此仅通过markdown返回结果无法确认节点是否保存）。

Self-check before submitting

提交前自我检查

Is the ticket free of PII/PHI (names, emails, phone numbers, health data, session content) — including screenshots, logs, and Engineering Notes?
Does
```
## Acceptance criteria
```
exist in the description body, written as an ADF
```
taskList
```
(real tickable checkboxes; plain
```
*
```
bullets only as the no-ADF fallback) with ≥1 testable item?
Could a non-technical reader (QA, PM, support) understand everything above the
```
---
```
, including
```
## How to test
```
if present?
If
```
## How to test
```
is present, does each step name the exact app + URL, the exact request/host to inspect, and the response field(s) with expected values (per the "How to test — writing guidance")? Is it omitted unless the user asked for it?
Is all technical detail (code paths, PRs, root cause, dev jargon) below the
```
---
```
in
```
## Engineering Notes
```
?
Task/Story: is a user-story opening line used ONLY if a genuine end user exists?

工单是否完全不含PII/PHI信息（姓名、邮箱、电话号码、健康数据、会话内容）——包括截图、日志和工程笔记？
```
## Acceptance criteria
```
是否存在于描述主体中，以ADF
```
taskList
```
（可勾选的真实复选框；仅在无法使用ADF时退而使用普通
```
*
```
项目符号）形式呈现，且包含至少1条可测试内容？
非技术人员（QA、产品经理、支持人员）是否能理解
```
---
```
分隔线以上的所有内容，包括
```
## How to test
```
（如有）？
若包含
```
## How to test
```
，每个步骤是否明确了具体应用+URL、需检查的具体请求/主机，以及响应字段和预期值（符合「测试方法编写指南」）？是否仅在用户要求时才添加？
所有技术细节（代码路径、PR、根本原因、开发术语）是否都放在
```
---
```
分隔线下方的
```
## Engineering Notes
```
中？
任务/用户故事：是否仅在存在真实终端用户时才使用用户故事格式开头？

Review pass

审核流程

Before creating, run the Self-check as a graded review, not a mental yes/no. This catches the mistakes that quietly slip past a drafter.

Two modes:

Self-review (always). After drafting, walk each Self-check item and grade it.
Independent review (recommended for any non-trivial ticket). Have a SEPARATE agent/context run the same rubric adversarially against the draft. The author who wrote the ticket tends to rubber-stamp it; a fresh pass is where the real defects surface. Give the reviewer this skill's rules plus the draft, and ask for the structured output below.

Review output format:

Compliance checklist — for each of the 6 Self-check items: PASS / FAIL / N/A with a one-line justification.
Issues found — each tagged with severity and, where useful, a concrete suggested rewrite:
- blocker — violates a hard rule (PII/PHI anywhere, acceptance criteria not in the body as a taskList, developer-only detail above the
```
---
```
  ) or is factually wrong. Must fix before creating.
- should-fix — a convention or clarity gap that will mislead QA or misrepresent scope (e.g. the summary promises one thing but the acceptance criteria test another). Fix unless there's a deliberate reason not to.
- nice-to-have — wording/polish. Optional.
Verdict — "ready to create as-is" or the minimal changes needed first.

Recurring misses worth checking explicitly (each has bitten a real ticket):

Hidden PII. A person's name riding along in a branch name, PR/commit link, or pasted log — hard-rule 1 applies to every section, including Engineering Notes.
Title vs acceptance-criteria drift. The summary describes a narrower or wider behavior than the criteria actually verify. Make them agree.
Acceptance criteria that restate implementation ("adds a CI job that runs RuboCop") instead of observable behavior ("the check fails when …").
## How to test
present when nobody asked for it, or too vague for a QA tester who has never seen the code.

创建工单前，请将自我检查作为分级审核执行，而非简单的是/否判断。这样可以发现起草者容易忽略的错误。

两种模式：

自我审核（必须执行）。起草完成后，逐一检查自我检查项并进行分级。
独立审核（建议针对所有非 trivial 工单执行）。请另一个Agent/角色以严格的标准对草稿进行审核。工单作者往往会草率通过自己的作品，而全新的审核才能发现真正的问题。请向审核人员提供本规范规则及草稿，并要求其按照以下结构输出审核结果。

审核输出格式：

合规性清单——针对6项自我检查项，每项标注通过/不通过/不适用，并附上一行理由。
发现的问题——每个问题标注严重程度，如有必要，附上具体的改写建议：
- 阻塞性问题——违反硬性规则（任何位置包含PII/PHI、验收标准未以taskList形式放在主体中、分隔线以上包含仅开发人员能理解的内容）或存在事实错误。必须修复后才能创建工单。
- 应修复问题——违反规范或存在清晰度问题，可能误导QA或错误表述范围（例如：摘要承诺的内容与验收标准实际验证的内容不一致）。除非有明确理由，否则必须修复。
- 建议优化问题——措辞/ polish 问题。可选修复。
结论——「可直接创建」或「需先进行以下最小改动」。

需要重点检查的常见错误（这些错误都曾出现在真实工单中）：

隐藏的PII信息。分支名称、PR/提交链接或粘贴的日志中附带的个人姓名——硬性规则1适用于所有章节，包括工程笔记。
标题与验收标准不一致。摘要描述的行为范围比验收标准实际验证的范围更窄或更宽。请确保两者一致。
验收标准重述实现细节（例如：「添加运行RuboCop的CI任务」）而非可观察行为（例如：「当……时检查失败」）。
无人要求却添加了
## How to test
，或内容过于模糊，从未接触过代码的QA测试人员无法遵循。