extract-findings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

extract-findings

Turn whatever the user has — a spreadsheet, a doc, or pasted text — into a clean

findings.json

. This is the entry point of the ADO-backlog pipeline: every later step (triage, classify, create, write-back) keys off the fields you produce here, so the value is a faithful, lossless normalization, not interpretation.

Output contract:

findings.json

shape #1 in

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

. Read it before writing — the field names are load-bearing and the bundled scripts depend on them.

将用户提供的任何内容——电子表格、文档或粘贴的文本——转换为规范的

findings.json

文件。这是ADO待办事项流程的入口点：后续的每一步（分类、归类、创建、回写）都依赖于此处生成的字段，因此关键在于忠实、无损耗地标准化输入内容，而非进行解读。

输出约定：需遵循

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

中的

findings.json

格式#1。编写前请先阅读该文档——字段名称至关重要，配套脚本依赖这些字段运行。

Schema (target)

目标 Schema

Each finding normalizes to these fields (full table in data-contracts.md):

```
key
```
— required. Stable id per finding; carried through every later file so the created ticket can be written back to the right source row.
```
current
```
/
```
expected
```
— required. Observed value vs the canonical/correct one.
```
section
```
,
```
recommendation
```
,
```
notes
```
— optional context; carried into the work item.
```
kind
```
— optional:
```
rename | disambiguation | missing | other
```
. Helps the classifier pick a work-item type.
```
severity
```
— optional:
```
Critical | High | Medium | Low
```
. Drives Priority + triage.
```
status
```
— optional free text (
```
confirmed
```
,
```
needs-review
```
, ...). A useful triage filter.

Top level also records

source

(a human-readable origin) and

keyColumn

(which source column became

key

Tiny example:

json

{
  "source": "Downloads/CRM_Portal_Naming_Audit.xlsx (sheet 'CRM-Portal Audit')",
  "keyColumn": "#",
  "findings": [
    { "key": "1", "section": "Cargo Classification", "current": "Auto",
      "expected": "Automotive Cargo", "kind": "rename", "severity": "Critical",
      "status": "confirmed", "recommendation": "Rename to: Automotive Cargo",
      "notes": "'Auto' loses the word 'Cargo'." }
  ]
}

每条问题记录需标准化为以下字段（完整表格见data-contracts.md）：

```
key
```
— 必填。每条问题记录的稳定ID；会贯穿后续所有文件，以便将创建的工单回写到对应的源数据行。
```
current
```
/
```
expected
```
— 必填。观测值与标准/正确值。
```
section
```
、
```
recommendation
```
、
```
notes
```
— 可选上下文信息；会带入工作项中。
```
kind
```
— 可选值：
```
rename | disambiguation | missing | other
```
。帮助分类器选择工作项类型。
```
severity
```
— 可选值：
```
Critical | High | Medium | Low
```
。决定优先级与分类处理顺序。
```
status
```
— 可选自由文本（如
```
confirmed
```
、
```
needs-review
```
等）。是实用的分类筛选条件。

顶层还需记录

source

（人类可读的来源描述）和

keyColumn

（哪个源列被用作

key

）。

小型示例：

json

{
  "source": "Downloads/CRM_Portal_Naming_Audit.xlsx (sheet 'CRM-Portal Audit')",
  "keyColumn": "#",
  "findings": [
    { "key": "1", "section": "Cargo Classification", "current": "Auto",
      "expected": "Automotive Cargo", "kind": "rename", "severity": "Critical",
      "status": "confirmed", "recommendation": "Rename to: Automotive Cargo",
      "notes": "'Auto' loses the word 'Cargo'." }
  ]
}

1. Get the content in front of you

1. 获取可查看的内容

Spreadsheets (

.xlsx

.xlsm

.csv

.tsv

) are binary or crash the Windows cp1252 console, so don't open them blind — dump them to UTF-8 text first. The helper forces UTF-8 so the rows survive intact:

powershell

python "${CLAUDE_PLUGIN_ROOT}/scripts/read_source.py" "<path-to-file>"

Then read the printed dump. For a big sheet, write it to a file and Read that (default cap is 200 rows; pass

--max-rows 0

for everything):

powershell

python "${CLAUDE_PLUGIN_ROOT}/scripts/read_source.py" "<path-to-file>" --out "<workdir>/source-dump.txt" --max-rows 0

The dump prefixes each row with its index —

[0]

is usually the header row,

[1]

onward the data. Multiple sheets are emitted under

=== SHEET: ... ===

markers; if several look relevant, ask the user which sheet holds the findings.

Non-tabular input (

.docx

.pdf

.md

.txt

, or text pasted into the chat) needs no helper — read it directly with the Read tool, or just use the pasted text.

read_source.py

only handles tabular types and will reject the rest by design.

电子表格（

.xlsx

、

.xlsm

、

.csv

、

.tsv

）是二进制文件，或会导致Windows cp1252控制台崩溃，因此不要盲目打开——先将其转储为UTF-8文本。辅助工具会强制使用UTF-8，确保数据行完整保留：

powershell

python "${CLAUDE_PLUGIN_ROOT}/scripts/read_source.py" "<path-to-file>"

然后查看打印出的转储内容。对于大型表格，可将内容写入文件后再查看（默认上限为200行；传入

--max-rows 0

可导出所有内容）：

powershell

python "${CLAUDE_PLUGIN_ROOT}/scripts/read_source.py" "<path-to-file>" --out "<workdir>/source-dump.txt" --max-rows 0

转储内容会在每行前添加索引——

[0]

通常是表头行，

[1]

及以后是数据行。多个工作表会以

=== SHEET: ... ===

标记分隔；若有多个工作表看起来相关，请询问用户哪个工作表包含问题记录。

非表格输入（

.docx

、

.pdf

、

.md

、

.txt

或粘贴到聊天中的文本）无需使用辅助工具——直接用Read工具读取，或直接使用粘贴的文本。

read_source.py

仅处理表格类型，会主动拒绝其他类型的文件。

2. Map source columns to schema fields

2. 将源列映射到Schema字段

Look at the header row / structure and decide which column means

current

, which means

expected

, etc. The mapping is the one genuinely ambiguous step, and a wrong guess corrupts every downstream ticket — so when a column's meaning is unclear, ask the user rather than guess silently. Typical traps: a single "Issue" column that mixes current+expected; "Comment"/"Notes" vs "Recommendation"; a "Status" column that's really severity.

```
key
```
: prefer an existing stable column (a
```
#
```
,
```
ID
```
, or row-number column). If none exists, assign
```
"1","2","3",...
```
in row order. Record your choice in
```
keyColumn
```
(use the column header, or
```
"row-index"
```
when you assigned them).
```
kind
```
and
```
severity
```
: infer only if the source actually supports it. If the sheet has no severity signal, leave
```
severity
```
off — do not invent one. Same for
```
kind
```
: only set it when the row clearly reads as a rename/disambiguation/missing item; otherwise omit or use
```
other
```
.
Keep
```
current
```
/
```
expected
```
verbatim. Don't summarize away the exact strings — later steps put them in the ticket body and write them back beside the source row.

查看表头行/结构，确定哪一列对应

current

，哪一列对应

expected

等。映射是唯一真正存在歧义的步骤，错误的猜测会破坏所有下游工单——因此当某列的含义不明确时，请询问用户，不要自行猜测。常见陷阱：单个“Issue”列混合了current和expected值；“Comment”/“Notes”与“Recommendation”混淆；“Status”列实际表示的是严重程度。

```
key
```
：优先使用现有的稳定列（如
```
#
```
、
```
ID
```
或行号列）。如果没有，则按行顺序分配
```
"1","2","3",...
```
。将你的选择记录在
```
keyColumn
```
中（使用列标题，若为自行分配则使用
```
"row-index"
```
）。
```
kind
```
和
```
severity
```
：仅在源数据实际支持时才进行推断。如果表格没有严重程度相关信息，请不要添加
```
severity
```
字段——不要自行编造。
```
kind
```
同理：只有当该行明确表示为重命名/消歧义/缺失项时才设置，否则省略或使用
```
other
```
。
```
current
```
/
```
expected
```
需保留原文。不要概括或修改确切字符串——后续步骤会将这些内容放入工单正文，并回写到源数据行旁。

3. Write findings.json

3. 编写findings.json

Write it to a working directory next to the source (e.g. the source's folder, or a

backlog/

subfolder there) so the whole pipeline's artefacts —

findings.json

, later

backlog_input.json

backlog_result.json

— stay together with the data they came from. Tell the user the exact path you wrote.

将文件写入源文件旁的工作目录（例如源文件所在文件夹，或该文件夹下的

backlog/

子文件夹），以便整个流程的产物——

findings.json

、后续的

backlog_input.json

、

backlog_result.json

——与原始数据保存在一起。告知用户你写入的具体路径。

4. Summarize and confirm before handoff

4. 移交前进行总结与确认

Show the user a short recap so they can catch a bad mapping now, not after tickets exist:

the column → field mapping you used (and what
```
key
```
came from),
counts: total findings, and a breakdown by
```
severity
```
/
```
kind
```
if you set them,
the first 3–5 normalized findings.

Once the user confirms the mapping looks right, hand off to triage-findings (which filters/prioritizes before classify-work-items turns findings into

backlog_input.json

). If the user is running the findings-to-ado-backlog orchestrator, it will carry the confirmed

findings.json

forward automatically.

向用户展示简短的摘要，以便他们在工单创建前发现映射错误：

你使用的列→字段映射关系（以及
```
key
```
的来源），
统计信息：问题记录总数，若设置了
```
severity
```
/
```
kind
```
则按其分类统计，
前3–5条标准化后的问题记录。

一旦用户确认映射正确，即可移交至triage-findings（该步骤会进行筛选/优先级排序，之后由classify-work-items将问题记录转换为

backlog_input.json

）。如果用户正在运行findings-to-ado-backlog编排器，它会自动将确认后的

findings.json

带入后续流程。

Notes

注意事项

```
key
```
uniqueness matters — duplicate keys break write-back. If the chosen column has dupes, fall back to assigned
```
"1","2",...
```
and say so.
Write-back to the source only works for spreadsheets (there's a row to write into). For docs/pasted text, assigned keys are fine but
```
tracking.py
```
write-back won't apply.
One finding per actionable discrepancy. Don't merge unrelated rows; don't split a single row into several findings unless it genuinely lists multiple distinct issues.

```
key
```
的唯一性至关重要——重复的key会破坏回写功能。若所选列存在重复值，请改用自行分配的
```
"1","2",...
```
并告知用户。
仅电子表格支持回写到源文件（因为有对应的行可以写入）。对于文档/粘贴的文本，自行分配的key是可行的，但
```
tracking.py
```
的回写功能无法适用。
每个可处理的差异对应一条问题记录。不要合并无关的行；除非某一行确实列出了多个不同的问题，否则不要将单行拆分为多条问题记录。