ado-writeback-tracking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ado-writeback-tracking

Closes the loop: once items exist in ADO, stamp their IDs and URLs back onto the spreadsheet the findings came from, so every row shows which ticket it became. This makes the source self-tracking — anyone reopening the sheet sees status without cross-referencing ADO. The link between a row and its ticket is the key
field (see

${CLAUDE_PLUGIN_ROOT}/references/data-contracts.md

), carried from [[extract-findings]] (

keyColumn

) through

backlog_result.json

完成闭环：一旦项在ADO中创建，就将其ID和URL标记回发现项来源的电子表格，这样每一行都能显示它对应的工单。这使得源文件具备自我追踪能力——任何人重新打开表格时，无需交叉引用ADO即可查看状态。行与其工单之间的链接是**

key

**字段（参见

${CLAUDE_PLUGIN_ROOT}/references/data-contracts.md

），从[[extract-findings]]（

keyColumn

）传递到

backlog_result.json

。

When this applies

适用场景

Spreadsheet sources only (
```
.xlsx
```
/
```
.csv
```
/
```
.tsv
```
). There must be one row per finding to write back to.
Doc / pasted-text sources have no rows — skip the script entirely and just report the created ticket links (parent + per-item URLs) from
```
backlog_result.json
```
in chat. Don't fabricate a spreadsheet to write to.
You need
```
backlog_result.json
```
from [[ado-create-work-items]] (which runs
```
create-backlog.cs
```
). Each
```
items[].id
```
is the created work item; rows whose key has no matching created
```
id
```
are simply skipped.

仅适用于电子表格源（
```
.xlsx
```
/
```
.csv
```
/
```
.tsv
```
）。必须每行对应一个可写回的发现项。
文档/粘贴文本源无行结构——完全跳过脚本，只需在聊天中报告
```
backlog_result.json
```
中的创建工单链接（父链接+每个项的URL）。不要虚构电子表格进行写入。
你需要来自[[ado-create-work-items]]（运行
```
create-backlog.cs
```
）的
```
backlog_result.json
```
。每个
```
items[].id
```
是已创建的工作项；键与已创建
```
id
```
不匹配的行将被跳过。

Before you write

写入前准备

Back up the user's source file first —

tracking.py

edits it in place and overwrites it. A quick copy keeps you safe if a key mismatch or wrong

--key

sends links to the wrong rows:

powershell

Copy-Item "<file>.xlsx" "<file>.bak.xlsx"

首先备份用户的源文件——

tracking.py

会原地编辑并覆盖它。快速复制一份可以避免因键不匹配或错误的

--key

参数导致链接写入错误行的情况：

powershell

Copy-Item "<file>.xlsx" "<file>.bak.xlsx"

Step 1 — add tracking columns (idempotent)

步骤1 — 添加追踪列（幂等操作）

Appends

Ticket ID

Ticket URL

WI State

Created

after the last used column. Safe to run repeatedly — columns that already exist are not duplicated. Run this once before the first writeback so the target columns exist:

powershell

python "${CLAUDE_PLUGIN_ROOT}/scripts/tracking.py" add-columns --source "<file>" --key "#"

It prints which columns map to which letters (xlsx) or confirms they're ensured (csv).

--key

defaults to

if omitted, but pass it explicitly to match.

在最后一列后追加

Ticket ID

、

Ticket URL

、

WI State

、

Created

列。重复运行是安全的——已存在的列不会被重复添加。在首次写回前运行一次，确保目标列存在：

powershell

python "${CLAUDE_PLUGIN_ROOT}/scripts/tracking.py" add-columns --source "<file>" --key "#"

它会打印哪些列对应哪个字母（xlsx格式），或确认列已确保存在（csv格式）。如果省略

--key

，默认值为

，但建议显式传递以匹配设置。

Step 2 — write the ticket links back (idempotent)

步骤2 — 写回工单链接（幂等操作）

Matches each

backlog_result.json

item's

key

to the value in the source's key column and fills the four tracking columns. Rows that already hold a Ticket ID are left as-is, so re-running after a partial create only fills the new rows:

powershell

python "${CLAUDE_PLUGIN_ROOT}/scripts/tracking.py" writeback --source "<file>" --result "<path>/backlog_result.json" --key "#"

Per row it writes:

```
Ticket ID
```
←
```
items[].id
```

Ticket URL

←

https://dev.azure.com/{org}/{project}/_workitems/edit/{id}

(built from the

org

project

backlog_result.json

)

```
WI State
```
←
```
New
```
(the state freshly created items land in)
```
Created
```
← a
```
YYYY-MM-DD HH:MM
```
timestamp

It logs each

key -> #id

, prints the parent link if one exists, and ends with

wrote N ticket links back to source

将每个

backlog_result.json

项的

key

与源文件键列中的值匹配，并填充四个追踪列。已包含Ticket ID的行将保持不变，因此在部分创建后重新运行只会填充新行：

powershell

python "${CLAUDE_PLUGIN_ROOT}/scripts/tracking.py" writeback --source "<file>" --result "<path>/backlog_result.json" --key "#"

每行写入的内容：

```
Ticket ID
```
←
```
items[].id
```

Ticket URL

←

https://dev.azure.com/{org}/{project}/_workitems/edit/{id}

（由

backlog_result.json

中的

org

project

构建）

```
WI State
```
←
```
New
```
（新创建项的初始状态）
```
Created
```
←
```
YYYY-MM-DD HH:MM
```
格式的时间戳

它会记录每个

key -> #id

，如果存在父链接则打印，并以

wrote N ticket links back to source

结尾。

The

--key

must line up across all three files

--key

必须在三个文件中保持一致

This is the single most common failure. The

--key

you pass here must be the same column name as:

```
keyColumn
```
chosen in [[extract-findings]] (e.g.
```
#
```
,
```
ID
```
,
```
Row
```
), and

the

key

value carried in

backlog_input.json

and

backlog_result.json

Values are compared as strings. If the script prints

warn: key <x> not found in source

, the

key

in the result doesn't match any value in that column — re-check

--key

(right column?) and that the source hasn't been re-sorted or had rows removed since extraction. If it raises

missing column '<name>' — run add-columns first

, you skipped Step 1 (or pointed

--key

at a column that isn't in the sheet).

这是最常见的失败原因。你在此处传递的

--key

必须与以下内容的列名称相同：

[[extract-findings]]中选择的
```
keyColumn
```
（例如
```
#
```
、
```
ID
```
、
```
Row
```
），以及

backlog_input.json

和

backlog_result.json

中携带的

key

值。

值将作为字符串进行比较。如果脚本打印

warn: key <x> not found in source

，说明结果中的

key

与该列中的任何值都不匹配——重新检查

--key

（是否为正确的列？）以及自提取以来源文件是否被重新排序或删除了行。如果提示

missing column '<name>' — run add-columns first

，说明你跳过了步骤1（或

--key

指向的列不在表格中）。

Tiny example

小示例

backlog_result.json

(abridged):

json

{ "org": "Cartagena365", "project": "GlassHull",
  "items": [ { "key": "1", "id": 6073, "type": "Bug", "title": "..." } ] }

After writeback, the source row whose

column is

gains:

Ticket ID=6073

Ticket URL=https://dev.azure.com/Cartagena365/GlassHull/_workitems/edit/6073

WI State=New

Created=2026-06-02 14:05

backlog_result.json

（节选）：

json

{ "org": "Cartagena365", "project": "GlassHull",
  "items": [ { "key": "1", "id": 6073, "type": "Bug", "title": "..." } ] }

写回后，

列值为

的源行将添加：

Ticket ID=6073

、

Ticket URL=https://dev.azure.com/Cartagena365/GlassHull/_workitems/edit/6073

、

WI State=New

、

Created=2026-06-02 14:05

。

Notes

注意事项

No ADO auth or network call happens here — this step only reads the JSON result and edits the local file. (Auth lives in [[ado-auth]] / the create step.)
The bundled Python forces UTF-8, so accented/Thai text survives even on a cp1252 PowerShell console.
This is the final stage of the [[findings-to-ado-backlog]] pipeline: [[extract-findings]] → [[triage-findings]] → [[classify-work-items]] → [[ado-create-work-items]] → ado-writeback-tracking.

此步骤不涉及ADO认证或网络调用——仅读取JSON结果并编辑本地文件。（认证在[[ado-auth]] / 创建步骤中处理。）
捆绑的Python强制使用UTF-8编码，因此即使在cp1252编码的PowerShell控制台中，带重音的字符/泰文文本也能保留。
这是[[findings-to-ado-backlog]]流程的最后阶段：[[extract-findings]] → [[triage-findings]] → [[classify-work-items]] → [[ado-create-work-items]] → ado-writeback-tracking。

ado-writeback-tracking

Original

Translation

ado-writeback-tracking

ado-writeback-tracking

When this applies

适用场景

Before you write

写入前准备

Step 1 — add tracking columns (idempotent)

步骤1 — 添加追踪列（幂等操作）

Step 2 — write the ticket links back (idempotent)

步骤2 — 写回工单链接（幂等操作）

The
`--key`
must line up across all three files

`--key`
必须在三个文件中保持一致

Tiny example

小示例

Notes

注意事项

ado-writeback-tracking

Original

Translation

ado-writeback-tracking

ado-writeback-tracking

When this applies

适用场景

Before you write

写入前准备

Step 1 — add tracking columns (idempotent)

步骤1 — 添加追踪列（幂等操作）

Step 2 — write the ticket links back (idempotent)

步骤2 — 写回工单链接（幂等操作）

The --key must line up across all three files

--key必须在三个文件中保持一致

Tiny example

小示例

Notes

注意事项

The
`--key`
must line up across all three files

`--key`
必须在三个文件中保持一致