findings-to-ado-backlog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

findings-to-ado-backlog (orchestrator)

findings-to-ado-backlog（编排器）

Run the full pipeline: a source document in, an ADO backlog out. You coordinate six sibling skills; each owns its step and its data contract. Your job is to sequence them, keep the working files together, and enforce the safety gates so nothing irreversible happens without the user seeing it first.

Why an orchestrator: the value is in the gates, not the glue. Creating work items is a write the user cannot easily undo, so the pipeline is deliberately staged: read-only extraction and classification first, a dry run that creates nothing, an explicit human approval, then the real write. Each sub-skill is reusable on its own; this skill is the teachable happy path that ties them together.

运行完整流程：输入源文档，输出ADO待办事项。你需要协调六个子技能；每个子技能负责其对应的步骤和数据契约。你的任务是按顺序执行它们，将工作文件集中管理，并执行安全门机制，确保在用户确认前不会发生任何不可逆转的操作。

为何使用编排器： 核心价值在于安全门，而非简单的流程衔接。创建工作项是用户难以轻易撤销的写入操作，因此流程被特意设计为分阶段执行：先进行只读的提取和分类，然后执行不创建任何内容的试运行，再获取明确的人工批准，最后执行实际写入。每个子技能均可单独复用；本技能是将它们串联起来的便捷最优路径。

Data flow

数据流

Three small JSON files carry state between steps. They share a stable key
per finding (a row number or ID column) so a created ticket can be traced back to its source row. Full shapes live in

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

— read it once; do not duplicate schemas here.

extract-findings      -> findings.json
classify-work-items   -> backlog_input.json   (consumed by create-backlog.cs)
ado-create-work-items -> backlog_result.json  (consumed by tracking.py writeback)

Working directory: create one beside the source (e.g. next to the xlsx) and keep all three JSON files there. This keeps a run self-contained and re-runnable.

三个小型JSON文件在步骤之间传递状态。它们为每个结果共享一个稳定的**

key

**（行号或ID列），以便将创建的工单追溯到其源行。完整的数据结构定义位于

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

中——请阅读一次，不要在此处重复模式定义。

extract-findings      -> findings.json
classify-work-items   -> backlog_input.json   (由create-backlog.cs调用)
ado-create-work-items -> backlog_result.json  (由tracking.py回写调用)

工作目录： 在源文件旁创建一个目录（例如xlsx文件旁边），并将所有三个JSON文件保存在其中。这样可确保每次运行都是独立且可重新执行的。

Process

流程

0. Prereqs + auth (optional but recommended on first run)

0. 先决条件 + 认证（可选，但首次运行建议执行）

Confirm the toolchain is present before you invest in extraction. This is read-only.

powershell

powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check.ps1"

It checks

az login

, .NET >= 10, Python + openpyxl, and the

AZDO_ORG

AZDO_PROJECT

env vars. For auth specifics (Entra token vs

AZDO_PAT

, org/project), delegate to ado-auth. The create script defaults to an Entra token via

az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv

在开始提取之前，先确认工具链已就绪。此步骤为只读操作。

powershell

powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check.ps1"

它会检查

az login

、.NET >= 10、Python + openpyxl，以及

AZDO_ORG

AZDO_PROJECT

环境变量。关于认证细节（Entra令牌 vs

AZDO_PAT

、组织/项目），请委托给ado-auth处理。创建脚本默认通过

az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv

获取Entra令牌。

1. Extract →

findings.json

(delegate to extract-findings)

1. 提取 →

findings.json

（委托给extract-findings）

Have extract-findings read the source (it uses

${CLAUDE_PLUGIN_ROOT}/scripts/read_source.py

for xlsx/csv; docs and pasted text are read directly) and normalize it to

findings.json

. Confirm the column mapping with the user before moving on — which column is the

key

, which are

current

expected

, where

severity

and

status

come from. A wrong mapping silently poisons everything downstream.

让extract-findings读取源文件（对于xlsx/csv，它使用

${CLAUDE_PLUGIN_ROOT}/scripts/read_source.py

；文档和粘贴的文本直接读取）并将其标准化为

findings.json

。在继续之前，请与用户确认列映射——哪一列是

key

，哪些是

current

expected

，

severity

和

status

来自哪里。错误的映射会悄无声息地破坏后续所有流程。

2. Triage → scoped subset (delegate to triage-findings)

2. 分类筛选 → 限定子集（委托给triage-findings）

Don't file everything blindly. Have triage-findings filter

findings.json

to the wave worth creating now. Recommend Critical + confirmed first — it is the smallest defensible batch and proves the pipeline before you fan out. Hold

needs-review

items for a later wave and tell the user you are doing so.

不要盲目创建所有工单。让triage-findings过滤

findings.json

，只保留当前值得创建的部分。建议优先处理严重且已确认的问题——这是最小的可辩护批次，可在扩大范围前验证流程。将

needs-review

的项留到后续批次处理，并告知用户此操作。

3. Classify →

backlog_input.json

(delegate to classify-work-items)

3. 分类 →

backlog_input.json

（委托给classify-work-items）

Have classify-work-items map the scoped findings to ADO work items. It must:

Discover the target project's process (Agile / Scrum / Basic / CMMI) and pick industry-standard types that actually exist on that board — e.g. a defect is
```
Bug
```
on Agile/Scrum/CMMI but Basic has no Bug (use
```
Issue
```
). See the process→types table in
```
data-contracts.md
```
.
Optionally add a Feature
or
Epic
parent to group the batch; every item links under it via
```
System.LinkTypes.Hierarchy-Reverse
```
.
Decide assignment — ask the user who these go to. A fresh backlog is usually created unassigned (assigned later in planning), but ask: leave unassigned, assign to the user themselves, assign the batch to one person, or map a per-row owner. Set
```
System.AssignedTo
```
(a UPN like
```
name@domain
```
) on each item, or assign the whole batch at create time with the
```
AZDO_ASSIGNED_TO
```
env var. The dry run validates the identity before any real write.

Emit raw ADO field reference names (

System.Title

Microsoft.VSTS.Common.Priority

System.Tags

; Bug body

Microsoft.VSTS.TCM.ReproSteps

; Story/PBI body

System.Description

Microsoft.VSTS.Common.AcceptanceCriteria

). HTML fields must be valid HTML.

Estimate time per item and attach it as a child Task (hours in Original/Remaining Work; the detailed breakdown in the Task description) — see
```
classify-work-items
```
.

GATE — estimates. classify proposes the hours per item as a table. Show it and get the user's OK / adjustments before the dry run. Estimates are cheap to fix now, annoying to fix across already-created Tasks.

让classify-work-items将筛选后的结果映射为ADO工作项。它必须：

发现目标项目的流程（Agile / Scrum / Basic / CMMI）并选择该看板上实际存在的行业标准类型——例如，缺陷在Agile/Scrum/CMMI中是
```
Bug
```
，但Basic没有Bug（请使用
```
Issue
```
）。请参阅
```
data-contracts.md
```
中的流程→类型表。
可选添加**
```
Feature
```
或
```
Epic
```
父项**来对批次进行分组；每个项通过
```
System.LinkTypes.Hierarchy-Reverse
```
链接到其下。
确定分配对象——询问用户工单应分配给谁。 新创建的待办事项通常是未分配的（在规划阶段后期分配），但需询问：保持未分配、分配给用户自己、将整个批次分配给一个人，还是按行映射所有者。为每个项设置
```
System.AssignedTo
```
（如
```
name@domain
```
这样的UPN），或在创建时通过
```
AZDO_ASSIGNED_TO
```
环境变量分配整个批次。试运行会在实际写入前验证身份是否有效。

输出原始ADO字段引用名称（

System.Title

、

Microsoft.VSTS.Common.Priority

、

System.Tags

；Bug描述

Microsoft.VSTS.TCM.ReproSteps

；用户故事/PBI描述

System.Description

Microsoft.VSTS.Common.AcceptanceCriteria

）。HTML字段必须是有效的HTML。

估算每个项的时间并将其作为子Task附加（在Original/Remaining Work中填写小时数；详细分解在Task描述中）——请参阅
```
classify-work-items
```
。

安全门——估算。 分类步骤会以表格形式提出每个项的小时数估算。在试运行前展示给用户并获取其确认/调整。 现在修复估算成本低，而在已创建的Task中修改则很麻烦。

4. DRY RUN → validate, create nothing (delegate to ado-create-work-items)

4. 试运行 → 验证，不创建任何内容（委托给ado-create-work-items）

This is the first gate. The create script defaults to dry run, which sends each item to ADO with

validateOnly=true

— it catches a bad type, a missing required field, or a wrong area/iteration path without creating anything.

powershell

$env:AZDO_DRY_RUN = "true"
dotnet run "${CLAUDE_PLUGIN_ROOT}/scripts/create-backlog.cs" -- "<workdir>/backlog_input.json"

Show the user the validated PASS/FAIL list (type, title per

key

). Fix any FAIL in

backlog_input.json

and re-run until clean.

GATE — stop here. Do not proceed to the real run until the user has explicitly approved the validated list. Present the count, the types, and the parent, and wait for a clear yes.

这是第一个安全门。创建脚本默认处于试运行模式，会将每个项发送到ADO并设置

validateOnly=true

——它会捕获错误的类型、缺失的必填字段或错误的区域/迭代路径而不创建任何内容。

powershell

$env:AZDO_DRY_RUN = "true"
dotnet run "${CLAUDE_PLUGIN_ROOT}/scripts/create-backlog.cs" -- "<workdir>/backlog_input.json"

向用户展示验证通过/失败的列表（每个

key

对应的类型和标题）。修复

backlog_input.json

中的任何失败项，重新运行直到全部通过。

安全门——在此暂停。 在用户明确批准验证通过的列表之前，不要继续执行实际运行。向用户展示数量、类型和父项，等待明确的确认。

5. REAL RUN →

backlog_result.json

(delegate to ado-create-work-items)

5. 实际运行 →

backlog_result.json

（委托给ado-create-work-items）

Only after approval. Setting

AZDO_DRY_RUN

false

creates the parent (if any), every child, and a child Task (with the hour estimate) under each item, links them all, and writes

backlog_result.json

powershell

$env:AZDO_DRY_RUN = "false"
dotnet run "${CLAUDE_PLUGIN_ROOT}/scripts/create-backlog.cs" -- "<workdir>/backlog_input.json"

Then verify the created items — confirm each

key

got an

id

and

url

backlog_result.json

, and that any rows logged

FAILED

are surfaced to the user, not buried.

仅在获得批准后执行。将

AZDO_DRY_RUN

设置为

false

会创建父项（如果有）、所有子项、每个项下方带有小时估算的子Task，将它们全部关联起来，并写入

backlog_result.json

。

powershell

$env:AZDO_DRY_RUN = "false"
dotnet run "${CLAUDE_PLUGIN_ROOT}/scripts/create-backlog.cs" -- "<workdir>/backlog_input.json"

然后验证已创建的项——确认每个

key

在

backlog_result.json

中都有对应的

id

和

url

，并向用户展示任何记录为

FAILED

的行，而不是隐藏它们。

6. Write-back tracking — spreadsheets only (delegate to ado-writeback-tracking)

6. 回写跟踪——仅适用于电子表格（委托给ado-writeback-tracking）

Only if the source is a spreadsheet (a row per finding). For docs/pasted text there is no row to write to — skip this step.

GATE — back up the source first. Write-back mutates the user's spreadsheet in place. Copy the file before running it.

Have ado-writeback-tracking drive

${CLAUDE_PLUGIN_ROOT}/scripts/tracking.py

: first ensure the

Ticket ID | Ticket URL | WI State | Created

columns exist (

add-columns

), then match each result

key

to the source key column and fill them (

writeback

). Both subcommands are idempotent — rows that already have a Ticket ID are left as-is — so a re-run is safe. Pass

--key

matching the key column you confirmed in step 1.

仅当源是电子表格时（每行对应一个结果）。对于文档/粘贴的文本，没有可回写的行——跳过此步骤。

安全门——先备份源文件。 回写会直接修改用户的电子表格。在运行前复制文件。

让ado-writeback-tracking调用

${CLAUDE_PLUGIN_ROOT}/scripts/tracking.py

：首先确保

Ticket ID | Ticket URL | WI State | Created

列存在（

add-columns

子命令），然后将每个结果的

key

与源文件的key列匹配并填充内容（

writeback

子命令）。两个子命令都是幂等的——已包含Ticket ID的行将保持不变——因此重新运行是安全的。传入

--key

参数，匹配你在步骤1中确认的key列。

7. Report back

7. 反馈报告

Summarize the run for the user:

Created: count + clickable links (the
```
url
```
per item, and the parent if any).
Held / skipped: the triage wave you deferred (e.g.
```
needs-review
```
), plus any dry-run FAILs or real-run errors and why.
Follow-ups: the obvious next wave (run steps 2–6 again on the deferred subset), and any ambiguous findings that need a human decision before they can be classified.

向用户总结运行情况：

已创建： 数量 + 可点击链接（每个项的
```
url
```
，以及父项（如果有））。
保留/跳过： 你推迟处理的分类批次（例如
```
needs-review
```
），以及任何试运行失败或实际运行错误及其原因。
后续操作： 下一个明显的批次（对推迟的子集重新运行步骤2–6），以及任何需要人工决策才能分类的模糊结果。

Safety gates (the whole point)

安全门（核心价值）

Dry run before real — step 4 always precedes step 5; the script defaults to dry run.
Explicit approval before any write — never jump from validation to creation on your own.
Back up the source before write-back — step 6 edits the user's file in place.

If anything is ambiguous (column mapping, which process, which parent), ask rather than guess — a wrong guess multiplies across every item in the batch.

实际运行前先试运行——步骤4始终在步骤5之前执行；脚本默认处于试运行模式。
写入前需明确批准——永远不要自行从验证直接跳到创建。
回写前备份源文件——步骤6会直接编辑用户的文件。

如果有任何模糊之处（列映射、流程类型、父项选择），请询问用户而非猜测——错误的猜测会影响批次中的每个项。

findings-to-ado-backlog

Original

Translation

findings-to-ado-backlog (orchestrator)

findings-to-ado-backlog（编排器）

Data flow

数据流

Process

流程

0. Prereqs + auth (optional but recommended on first run)

0. 先决条件 + 认证（可选，但首次运行建议执行）

1. Extract →
`findings.json`
(delegate to extract-findings)

1. 提取 →
`findings.json`
（委托给extract-findings）

2. Triage → scoped subset (delegate to triage-findings)

2. 分类筛选 → 限定子集（委托给triage-findings）

3. Classify →
`backlog_input.json`
(delegate to classify-work-items)

3. 分类 →
`backlog_input.json`
（委托给classify-work-items）

4. DRY RUN → validate, create nothing (delegate to ado-create-work-items)

4. 试运行 → 验证，不创建任何内容（委托给ado-create-work-items）

5. REAL RUN →
`backlog_result.json`
(delegate to ado-create-work-items)

5. 实际运行 →
`backlog_result.json`
（委托给ado-create-work-items）

6. Write-back tracking — spreadsheets only (delegate to ado-writeback-tracking)

6. 回写跟踪——仅适用于电子表格（委托给ado-writeback-tracking）

7. Report back

7. 反馈报告

Safety gates (the whole point)

安全门（核心价值）

findings-to-ado-backlog

Original

Translation

findings-to-ado-backlog (orchestrator)

findings-to-ado-backlog（编排器）

Data flow

数据流

Process

流程

0. Prereqs + auth (optional but recommended on first run)

0. 先决条件 + 认证（可选，但首次运行建议执行）

1. Extract → findings.json (delegate to extract-findings)

1. 提取 → findings.json（委托给extract-findings）

2. Triage → scoped subset (delegate to triage-findings)

2. 分类筛选 → 限定子集（委托给triage-findings）

3. Classify → backlog_input.json (delegate to classify-work-items)

3. 分类 → backlog_input.json（委托给classify-work-items）

4. DRY RUN → validate, create nothing (delegate to ado-create-work-items)

4. 试运行 → 验证，不创建任何内容（委托给ado-create-work-items）

5. REAL RUN → backlog_result.json (delegate to ado-create-work-items)

5. 实际运行 → backlog_result.json（委托给ado-create-work-items）

6. Write-back tracking — spreadsheets only (delegate to ado-writeback-tracking)

6. 回写跟踪——仅适用于电子表格（委托给ado-writeback-tracking）

7. Report back

7. 反馈报告

Safety gates (the whole point)

安全门（核心价值）

1. Extract →
`findings.json`
(delegate to extract-findings)

1. 提取 →
`findings.json`
（委托给extract-findings）

3. Classify →
`backlog_input.json`
(delegate to classify-work-items)

3. 分类 →
`backlog_input.json`
（委托给classify-work-items）

5. REAL RUN →
`backlog_result.json`
(delegate to ado-create-work-items)

5. 实际运行 →
`backlog_result.json`
（委托给ado-create-work-items）