Back to Details

ticket-trace

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ticket Trace

工单追溯

Two operations that share one idea: a commit message is the join key between code and the reason for the code. Writing commits without a ticket number breaks the chain; answering "why" questions without following the chain to the ticket produces guesses.
两项操作共享一个核心理念：提交信息是代码与代码修改原因之间的关联密钥。不包含工单编号的提交会打破这一关联链；不追溯至工单就回答“为什么”的问题只能靠猜测。

The chain

关联链

code line → git blame/log → commit → ticket number in message → ticket in tracker → reason (text + ATTACHED IMAGES)
Real example that motivated this skill: a hardcoded label looked like a naming bug. 
git log -S "Vehicles"
→ commit 
e40eb36 "fix 5887"
→ ADO ticket #5887 → the description was one annotated screenshot saying "Rename Auto to Vehicles / Hide Breakbulk". The hardcode was an explicit requirement. Without opening the image, the answer would have been wrong.
代码行 → git blame/log → 提交 → 提交信息中的工单编号 → 跟踪器中的工单 → 原因（文本 + 附件图片）
催生该技能的真实案例：一个硬编码标签看起来像是命名错误。执行
git log -S "Vehicles"
→ 找到提交
e40eb36 "fix 5887"
→ 查看ADO工单#5887 → 工单描述是一张带注释的截图，内容为“将Auto重命名为Vehicles / 隐藏Breakbulk”。这个硬编码是明确的需求。如果不查看图片，给出的答案就会出错。

Operation A — Commit with a ticket number

操作A — 关联工单编号的提交

Every commit in a ticketed repo must reference its ticket. Resolve the number in this order, and say which source you used:
  1. User said it — "this is for 6084" → use it.
  2. Branch name — 
    bug/6084-cargo-labels
    , 
    feature/4242-x
    → extract the number.
  3. Session context — the task you're working on came from a ticket discussed earlier.
  4. Recent log convention — check 
    git log --oneline -5
    to match the repo's format (
    fix 5887
    , 
    feat: ... (#6084)
    ).
  5. None of the above → ask the user ("Which ticket is this for?"). Do not invent a number, and do not commit without one — a wrong ticket is worse than no commit, because it plants false evidence for future archaeology.
Match the repo's existing message style; don't impose a new one. Skip the requirement for 
Merge
/
Revert
/
fixup!
commits.
工单仓库中的每一次提交都必须关联对应的工单编号。按以下顺序确定编号，并告知用户使用的来源：
  1. 用户明确提及 — 例如“这是为了6084” → 使用该编号。
  2. 分支名称 — 如
    bug/6084-cargo-labels
    、
    feature/4242-x
    → 提取编号。
  3. 会话上下文 — 当前处理的任务来自之前讨论过的工单。
  4. 近期提交日志惯例 — 查看
    git log --oneline -5
    以匹配仓库的格式（如
    fix 5887
    、
    feat: ... (#6084)
    ）。
  5. 以上均不适用 → 询问用户（“这对应哪个工单？”）。不得编造编号，也不得在无编号的情况下提交——错误的工单编号比无编号更糟，因为它会为未来的代码溯源留下虚假证据。
匹配仓库现有的提交信息风格，不要强加新格式。
Merge
/
Revert
/
fixup!
类型的提交可跳过此要求。

Optional: enforcement hook

可选：强制钩子

The skill itself is the enforcement — follow the resolution order above on every commit. A git hook exists as an opt-in extra: install it ONLY when the user explicitly asks for hard enforcement ("install the hook", "reject commits without tickets"). Do not install it proactively — it affects every committer and every tool that touches the repo.
bash
cp <skill-dir>/scripts/commit-msg <repo>/.git/hooks/commit-msg
chmod +x <repo>/.git/hooks/commit-msg   # not needed on Windows
The hook rejects commits whose message has no ticket reference (default pattern 
(#|\b)[0-9]{3,6}\b
, override with 
git config ticket.pattern '<regex>'
; bypass once with 
--no-verify
). It must not clobber an existing 
commit-msg
hook — if one exists, show it to the user and merge manually.
本技能本身就是一种约束——每次提交都遵循上述编号确定规则。作为可选增强功能，提供一个git钩子：仅当用户明确要求强制约束时（如“安装钩子”“拒绝无工单的提交”）才安装。不得主动安装——它会影响所有提交者和所有操作仓库的工具。
bash
cp <skill-dir>/scripts/commit-msg <repo>/.git/hooks/commit-msg
chmod +x <repo>/.git/hooks/commit-msg   # Windows系统无需执行此步
该钩子会拒绝未包含工单引用的提交（默认匹配模式为
(#|\b)[0-9]{3,6}\b
，可通过
git config ticket.pattern '<regex>'
覆盖；可使用
--no-verify
跳过一次检查）。不得覆盖已存在的
commit-msg
钩子——若已有钩子，需展示给用户并手动合并。

Auto commit-log (daily-state 
## Log
)

自动提交日志（每日状态
## Log
）

Separately, dev-workflows ships a PreToolUse hook (
hooks/commit-log.py
, registered in 
hooks/hooks.json
) that fires on every 
git commit
and echoes the commit message into that repo's 
daily-state.md
## Log
(via 
daily-state.py log
). It is active automatically when the plugin is enabled — no install step, "just works" for everyone — and never blocks a commit (best-effort; any failure is swallowed). This is the running-worklog half of the chain: the ticket number keeps a commit traceable to its reason; the daily-state 
## Log
keeps a human-readable record of what happened when, at the repo root, independent of git history. The two are complementary — the commit-log hook does not check or enforce the ticket number (that is this skill's job, above).
此外，dev-workflows还提供了一个PreToolUse钩子（
hooks/commit-log.py
，在
hooks/hooks.json
中注册），每次执行
git commit
时触发，将提交信息写入仓库的
daily-state.md
的
## Log
部分（通过
daily-state.py log
实现）。该钩子在插件启用时自动激活——无需安装步骤，“开箱即用”——且绝不会阻止提交（尽力而为；任何失败都会被静默处理）。这是关联链中工作记录的部分：工单编号让提交可追溯至其修改原因；每日状态
## Log
则在仓库根目录保留了一份人类可读的“事件时间线”记录，独立于git历史。两者互为补充——提交日志钩子不会检查或强制要求工单编号（这是本技能的职责）。

Operation B — Answer "why was this changed?"

操作B — 回答“为什么要修改这个？”

When the user questions a piece of code (a weird label, a hardcode, a removed feature, a magic number), do NOT answer from the code alone. Walk the chain:
  1. Pin the code — find the exact file/line(s) the question is about.
  2. Find the commit(s) — pick the right tool: 
    • git log -S "<literal>" -- <file>
      — when the text was added/removed (best for hardcodes/labels)
    • git log -L <start>,<end>:<file>
      — history of a line range
    • git blame -w -C <file> -L <n>,<n>
      — who last touched the line Follow renames with 
      --follow
      if the file moved.
  3. Extract ticket references from the commit message (
    fix 5887
    , 
    (#6084)
    , 
    JIRA-123
    ). If the message has none, try the merge commit / PR that brought it in (
    git log --merges --ancestry-path <sha>..HEAD | tail
    ), then the PR description.
  4. Fetch the ticket from the tracker. For Azure DevOps read references/ado.md. For GitHub use 
    gh issue view <n> --comments
    . For JIRA use the REST API with the user's configured auth.
  5. Read the attachments. If the description references an image, download it with the same auth and read it through 
    read-picture
     (load that skill via your harness's mechanism, kind 
    requirement
    , which answers from the project's picture record when this attachment has already been read for the same question and opens the image when it has not) — annotated screenshots frequently ARE the requirement, and skipping them flips the conclusion. Read the comments too; decisions often live in the last comment, not the description.
  6. Answer with evidence, in this shape:
    • Verdict first — intentional (requirement) / bug / unknown.
    • The chain: 
      file:line
      → commit sha + message → ticket id + title + state.
    • What the ticket actually says (quote or describe the annotation), and what that means for the user's question ("don't 'fix' it" / "safe to change").
    • Link the ticket URL so the user can verify.
当用户质疑某段代码（如奇怪的标签、硬编码、被移除的功能、魔术数字）时，不得仅通过代码本身回答。需遵循关联链操作：
  1. 定位代码 — 找到问题涉及的具体文件/行。
  2. 查找提交记录 — 选择合适的工具： 
    • git log -S "<literal>" -- <file>
      — 当文本被添加/移除时使用（最适合硬编码/标签）
    • git log -L <start>,<end>:<file>
      — 查看行范围的历史记录
    • git blame -w -C <file> -L <n>,<n>
      — 查看最后修改该行的人 若文件已重命名，需添加
      --follow
      参数。
  3. 从提交信息中提取工单引用（如
    fix 5887
    、
    (#6084)
    、
    JIRA-123
    ）。若提交信息中没有，可尝试查找引入该提交的合并提交/PR（
    git log --merges --ancestry-path <sha>..HEAD | tail
    ），然后查看PR描述。
  4. 从跟踪器获取工单信息。Azure DevOps的读取方式参考references/ado.md。GitHub使用
    gh issue view <n> --comments
    。JIRA使用用户配置的认证信息通过REST API获取。
  5. 读取附件。若工单描述引用了图片，使用相同的认证信息下载并通过
    read-picture
    读取    （通过你的工具机制加载该技能，类型为
    requirement
    ，当该附件已针对同一问题被读取过时，从项目的图片记录中获取答案；未读取过时则打开图片）——带注释的截图通常就是需求本身，跳过它们会导致结论错误。同时也要查看评论；决策往往存在于最后一条评论中，而非描述部分。
  6. 结合证据回答，格式如下：
    • 先给出结论 — 故意为之（符合需求）/ 错误 / 未知。
    • 关联链：
      文件:行号
      → 提交哈希 + 提交信息 → 工单ID + 标题 + 状态。
    • 工单的实际内容（引用或描述注释），以及对用户问题的意义（如“不要‘修复’它”/“可以安全修改”）。
    • 提供工单URL供用户验证。

Traps

注意事项

  • The description may be only an image. An empty-looking HTML body with an 
    <img src=".../_apis/wit/attachments/...">
    is the whole spec. Download and read it — never report "description is empty".
  • Several commits touch the same line. The newest one isn't always the reason; 
    -S
    on the exact string finds the one that introduced it.
  • Ticket numbers vs other numbers. 
    fix 5887
    is a ticket; 
    v2.0.1
    and 
    #region
    are not. Sanity-check the id by fetching it — a 404 means you parsed the wrong thing.
  • Closed ticket ≠ fully implemented. Compare what the ticket asked against the code; surface gaps as findings ("the ticket also says hide X, but X still renders").
  • No ticket found anywhere — say so plainly and fall back to commit message, PR, and asking the author. Don't speculate dressed as evidence.
  • 描述可能仅包含图片。看似空白的HTML主体中带有
    <img src=".../_apis/wit/attachments/...">
    ，这就是完整的规格说明。必须下载并读取图片——绝不能报告“描述为空”。
  • 多个提交修改同一行。最新的提交不一定是原因；使用
    -S
    匹配确切字符串可找到引入该内容的提交。
  • 工单编号与其他数字的区别。
    fix 5887
    是工单编号；
    v2.0.1
    和
    #region
    不是。需通过获取工单信息来验证编号是否正确——返回404说明解析错误。
  • 已关闭工单 ≠ 完全实现。对比工单要求与实际代码；若存在差距需指出（如“工单还要求隐藏X，但X仍在显示”）。
  • 未找到任何工单 — 直接说明情况，然后退而求其次，使用提交信息、PR内容，并询问作者。不得猜测并伪装成证据。

If the output is requested as a document

若需输出为文档

The default output is an evidence-chain answer in chat — no diagrams. But if the user asks for the trace as a Markdown report file, follow the diagram convention in 
${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md
(the overview diagram is the chain itself: 
file:line
→ commit → ticket, as a 
flowchart TD
).
默认输出为聊天形式的关联链证据回答——无图表。但如果用户要求将追溯结果输出为Markdown报告文件，请遵循
${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md
中的图表规范（概览图表即为关联链本身：
文件:行号
→ 提交 → 工单，采用
flowchart TD
格式）。

When NOT to use

不适用场景

Pure code-mechanics questions ("what does this function do") need no ticket. Turning findings into new tickets is 
ado-backlog
/
github-backlog
. Auditing label wording against a system of record is 
naming-audit
(but when naming-audit flags a suspicious hardcode, THIS skill answers whether it was intentional).
纯代码机制问题（如“这个函数做什么”）无需关联工单。将发现转化为新工单属于
ado-backlog
/
github-backlog
的职责。根据记录系统审核标签措辞属于
naming-audit
的职责（但当naming-audit标记可疑硬编码时，本技能负责回答该硬编码是否为故意为之）。