inkblot-jira-ticket

Inkblot Jira 工单规范

创建或编辑工单时，请严格按照以下结构编写描述。 固定的标题名称——不得重命名、调整顺序或自行添加章节。

三条硬性规则

1. 工单中绝不包含 PII 或 PHI。不得包含患者/客户姓名、电子邮件、电话号码、健康卡号、诊断信息、会话内容或任何可识别个人身份的信息。 请用角色 + 不透明 ID 指代人员（例如“客户 user_id 12345”、“预约 977096”、支持参考号“ATS-13371”）。附加截图、日志和堆栈跟踪之前，请先涂除可识别身份的信息。这适用于所有章节，包括 Engineering Notes 和评论。
2. 验收标准必须放在描述正文的 ## Acceptance criteria 标题下，并以清单形式编写。描述必须采用 ADF 格式（contentFormat: "adf"），验收标准必须渲染为真正可勾选的 taskList——具体方法请参阅“Jira 特定说明”。绝不能只将验收标准放在 Jira 侧边栏的“Acceptance criteria”清单字段中——QA、导出内容、PR 链接和 AI 工具都无法在该处获取这些信息。
3. ## Context、## Scope、## Acceptance criteria，以及（如有）## How to test 必须使用通俗易懂的语言，让非技术读者（QA、PM、支持人员）也能理解。只有开发人员才能理解的内容——代码路径、类/函数名称、SQL、堆栈跟踪、架构细节——应放在 ## Engineering Notes 下方的 --- 分隔线之后。

模板：任务 / 故事

## 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.

## 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

## 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.)

---

## 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.

模板：缺陷

## Steps to reproduce
1. ...

## 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.)

---

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

人无法复现的缺陷（基础设施 / 服务中断 / 竞争条件）

如果复现方式不是人可以随时执行的操作（例如上游服务中断、服务重启、时序竞争、状态损坏），请勿编写伪造的复现步骤。 将 ## Steps to reproduce 替换为 ## What happened——用简短、通俗易懂的叙述描述事件及其对用户可见的影响（“在 发生 X 服务中断期间，部分用户遇到了……”）。让 ## Expected / ## Actual 专注于症状。## How to test 只列出 QA 实际能够执行的检查；技术触发条件和任何仅供开发人员使用的验证（日志、Redis、指标）应放在 ## Engineering Notes 下。

模板：Spike

## Question
What we need to answer.

## Timebox
e.g. 2 days.

## Deliverable
Doc / decision / prototype / follow-up tickets.

如何编写 How to test

## How to test 为可选项（仅在用户要求时填写），但如有此项，必须具体到从未接触过代码的 QA 测试人员也能按步骤操作。 请用编号列表编写。内容要具体，不能含糊——绝不能只写“打开 Web 应用”。

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

1. 指明测试人员要打开的确切 应用 及其 URL（例如 Practice 应用 https://practice.inkblottherapy.com、客户端 Web 应用，或移动应用 + 对应构建版本）。说明使用哪个环境（staging 还是 prod），以及（如有必要）使用哪个测试账号/角色。
2. 说明任何准备工作：要选择的数据（按不透明 ID 指定）、要切换的功能标志、前置条件。
3. 如果需要检查网络响应，请告知测试人员打开浏览器开发者工具（右键单击 → 检查 / F12）→ Network 标签页，然后重新加载页面。
4. 指明确切请求——方法 + 完整路径，以及请求发送到的主机（例如 https://api.inkblottherapy.com/api/appointments/{id}）——并说明如何找到该请求（筛选框关键词）。然后打开 Response / Preview 标签页。
5. 指明要检查的具体字段及各状态下的预期值（例如，功能标志开启时 video_provider = vonage，关闭时 = twilio）。
6. 提供验证循环：切换功能标志 / 更改输入、重新加载，并确认值按预期变化。尽可能增加第二个独立信号（例如相关端点返回 200 而非 404）。

以上每个步骤都应放在 --- 之前，并使用 QA 能理解的语言；仅供开发人员使用的验证内容（日志、Redis、指标、数据库查询）应放入 ## Engineering Notes。

编写规则

• QA 从上往下阅读，并在 --- 分隔线处停止。分隔线以上的所有内容都必须易于理解，无需阅读代码或了解代码库。
• Engineering Notes 是存放技术细节的地方：所有技术细节都放在那里，不要穿插在工单其他部分。如果不确定某项内容是否“太技术”，就把它移到 Engineering Notes。
• Summary（标题）：简洁、使用祈使句、具体明确。末尾不要加句号。
• 不要批量补填旧工单或已关闭工单。对于尚未开始的未关闭工单，如果负责人提出要求，可以重新排版。

Jira 具体说明（inkblottherapy.atlassian.net）

• 项目采用公司管理型／经典配置（POD2 项目 ID 为 10013）。
• POD2 的 Story Points 字段是 customfield_10033（不是 customfield_10016）。在其他项目设置点数前，通过 createmeta 核实其 Story Points 字段。
• 复选框（标准做法）：始终以 ADF 格式（contentFormat: "adf"）创建或编辑描述，并将 ## Acceptance criteria 渲染为由 taskItem 节点组成的 taskList（每个节点都要包含 attrs.localId 和 state: "TODO"）——这样可以可靠地生成真正可勾选的 Jira 复选框（已通过先写入再读回验证）。不要依赖 Markdown 的 - [ ] 方式：其表现不一致（有时会生成真正的任务列表，有时只会显示字面文本 [ ]）。只有在 ADF 确实不可用时，才退而使用普通的 * 项目符号。
• 可折叠的 Engineering Notes（可选）：如需默认收起技术细节，可以将 ## Engineering Notes 渲染为 ADF expand 节点，而非普通标题——{ "type": "expand", "attrs": { "title": "Engineering Notes" }, "content": [ ...block content... ] }，并放在 --- 分隔线下方。这样做时，expand 的 title 会取代标题（不要同时输出 ## Engineering Notes 标题和同名 expand 标题）。这要求使用 contentFormat: "adf"：Markdown 方式会静默扁平化 expand，移除可折叠的包装并将其内容提升为内联内容。此折叠效果仅影响 Jira 网页界面的显示——API 始终会完整返回内容（ADF 获取结果会原样返回；Markdown 获取结果会将内容提升为内联内容），因此任何读取工单的 AI Agent 仍能看到这些备注。通过使用 responseContentFormat: "adf" 重新获取内容来验证是否持久化成功（该工具会将已保存的描述回显为 Markdown，而 Markdown 会扁平化 expand，因此仅凭 Markdown 回显无法确认节点是否已保存）。

提交前自查

1. 工单是否不含 PII/PHI（姓名、电子邮件、电话号码、健康数据、会话内容）——包括截图、日志和 Engineering Notes 中的内容？
2. 描述正文中是否存在 ## Acceptance criteria，并将其写为 ADF taskList（真正可勾选的复选框；只有在无法使用 ADF 时才用普通 * 项目符号），且至少包含 1 项可测试内容？
3. 非技术读者（QA、PM、支持人员）能否理解 --- 分隔线以上的所有内容，包括（如有）## How to test？
4. 如果包含 ## How to test，每个步骤是否都写明了要检查的准确应用和 URL、确切的请求／主机，以及预期值对应的响应字段（参见“How to test — writing guidance”）？除非用户要求，否则是否省略了该部分？
5. 所有技术细节（代码路径、PR、根本原因、开发术语）是否都放在 --- 分隔线下方的 ## Engineering Notes 中？
6. 对于 Task／Story：只有在确实存在最终用户时，才使用用户故事开篇句？

审核环节

创建前，请将 Self-check 作为评分审核来执行，而不是只在脑中判断是或否。这样可以发现起草者容易忽略的错误。

两种模式：

• 自我审核（始终执行）。 起草后，逐项检查 Self-check 并评分。
• 独立审核（建议用于任何非简单工单）。 让另一个独立的 Agent／上下文针对草稿，按同一套标准进行对抗性审核。撰写工单的人往往会敷衍了事；真正的缺陷通常会在新一轮审核中暴露。向审核者提供此技能的规则和草稿，并要求其按以下格式输出。

审核输出格式：

1. 合规清单 — 对 6 项 Self-check 条目分别标记：PASS / FAIL / N/A，并附上一句理由。
2. 发现的问题 — 为每项标注严重程度，并在适当时给出具体的改写建议：
   • 阻塞问题 — 违反硬性规则（任何位置出现 PII／PHI、验收标准未在正文中以 taskList 的形式呈现、开发者专属细节出现在 --- 之前），或存在事实错误。创建前必须修复。
   • 应该修复 — 约定或清晰度方面的缺漏，可能误导 QA 或歪曲范围（例如，摘要承诺一项内容，但验收标准测试的是另一项）。除非有意为之，否则应修复。
   • 锦上添花 — 措辞／润色问题。可选。
3. 结论 —“可以按原样创建”或需要先进行的最小改动。

值得明确检查的常见疏漏（真实工单中都曾出现过）：

• 隐藏的 PII。 人名出现在分支名称、PR／提交链接或粘贴的日志中 — 硬性规则 1 适用于所有部分，包括 Engineering Notes。
• 标题与验收标准不一致。 摘要描述的行为范围比标准实际验证的更窄或更宽。两者必须一致。
• 验收标准复述实现方式（“添加一个运行 RuboCop 的 CI 作业”），而不是描述可观察行为（“当……时，检查会失败”）。
• 在无人要求时添加 ## How to test， 或内容过于含糊，未接触过代码的 QA 测试人员无法据此测试。