Back to Details

findings-to-github-issues

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

findings-to-github-issues (orchestrator)

findings-to-github-issues（编排器）

Run the full pipeline: a source document in, a GitHub Issues 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. Creating issues is a write the user cannot easily undo (close is manual; notifications already fired), so the pipeline is deliberately staged: read-only extraction and classification first, a visual dry-run that creates nothing, an explicit human approval, then the real write.
运行完整流程：输入一份源文档，输出GitHub Issues待办事项。你需要协调六个相关技能；每个技能负责其对应的步骤和数据约定。你的任务是按顺序执行这些步骤，整理工作文件，并强制执行安全闸门，确保在用户确认前不会发生不可逆转的操作。
**为何使用编排器：**核心价值在于安全闸门。创建议题是用户无法轻松撤销的操作（关闭需手动进行；通知已发送），因此流程被特意设计为分阶段执行：先进行只读的提取和分类，再进行不创建任何内容的可视化试运行，接着需要明确的人工批准，最后才执行实际的写入操作。

Data flow

数据流

extract-findings         -> findings.json
classify-github-issues   -> github_backlog_input.json  (consumed by create_github_issues.py)
github-create-issues     -> github_backlog_result.json (consumed by github_tracking.py)
Working directory: create one beside the source and keep all JSON files there.
extract-findings         -> findings.json
classify-github-issues   -> github_backlog_input.json  (被create_github_issues.py调用)
github-create-issues     -> github_backlog_result.json (被github_tracking.py调用)
**工作目录：**在源文件旁创建一个目录，用于存放所有JSON文件。

Process

流程

0. Prereqs + auth (recommended on first run)

0. 前置条件与认证（首次运行推荐执行）

powershell
powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check_github.ps1"
Checks gh CLI, Python + requests + openpyxl, 
GH_OWNER
/ 
GH_REPO
, and repo reachability. For auth specifics, delegate to github-auth.
powershell
powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check_github.ps1"
检查gh CLI、Python + requests + openpyxl、
GH_OWNER
/ 
GH_REPO
，以及仓库的可达性。关于认证的具体细节，委托给github-auth处理。

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

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

Have extract-findings read the source 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.
让extract-findings读取源文件并将其标准化为
findings.json
。在继续之前，请与用户确认列映射——哪一列是
key
，哪些是
current
/ 
expected
，
severity
和
status
来自哪一列。

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

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

Have triage-findings filter 
findings.json
to the wave worth creating now. Recommend Critical + confirmed first. Hold 
needs-review
for a later wave.
让triage-findings过滤
findings.json
，筛选出当前需要创建议题的批次。建议优先处理严重且已确认的问题。将“需要评审”的问题留到后续批次处理。

3. Classify → 
github_backlog_input.json
(delegate to classify-github-issues)

3. 分类映射 → 
github_backlog_input.json
（委托给classify-github-issues）

Have classify-github-issues map the scoped findings to GitHub Issues with labels, milestone, body, and size estimate. It will show an estimates table.
GATE — estimates. Show the table and get the user's OK / adjustments before the visual dry-run.
让classify-github-issues将筛选后的发现映射为带有标签、里程碑、正文和规模估算的GitHub议题。它会展示一份估算表格。
安全闸门——估算结果。在可视化试运行前，展示表格并获取用户的确认/调整意见。

4. VISUAL DRY-RUN → validate, create nothing (delegate to github-create-issues)

4. 可视化试运行 → 验证，不创建任何内容（委托给github-create-issues）

Have github-create-issues render 
github_backlog_input.json
as a formatted table — title, labels, milestone, assignee per item. Nothing is created.
GATE — stop here. Do not proceed until the user has explicitly approved the list. Present the count, the milestone, and the labels, and wait for a clear yes.
让github-create-issues将
github_backlog_input.json
渲染为格式化表格——包含每个议题的标题、标签、里程碑、经办人。此步骤不会创建任何实际内容。
安全闸门——在此暂停。在用户明确批准列表前，请勿继续。告知用户议题数量、里程碑和标签，等待明确的确认。

5. REAL RUN → 
github_backlog_result.json
(delegate to github-create-issues)

5. 实际运行 → 
github_backlog_result.json
（委托给github-create-issues）

Only after approval. The script creates labels, the milestone, each issue, then the tracking issue:
powershell
$env:GH_OWNER = "Cartagena365"
$env:GH_REPO  = "GlassHull"
python "${CLAUDE_PLUGIN_ROOT}/scripts/create_github_issues.py" `
  --input  "<workdir>/github_backlog_input.json" `
  --output "<workdir>/github_backlog_result.json"
Then verify the created items — confirm each 
key
got a 
number
and 
url
in 
github_backlog_result.json
, and surface any that failed.
仅在获得批准后执行。脚本会创建标签、里程碑、每个议题，以及跟踪议题：
powershell
$env:GH_OWNER = "Cartagena365"
$env:GH_REPO  = "GlassHull"
python "${CLAUDE_PLUGIN_ROOT}/scripts/create_github_issues.py" `
  --input  "<workdir>/github_backlog_input.json" `
  --output "<workdir>/github_backlog_result.json"
然后验证已创建的项目——确认
github_backlog_result.json
中每个
key
都对应一个
number
和
url
，并指出创建失败的项目。

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

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

Only if the source is a spreadsheet.
GATE — back up the source first.
Have github-writeback-tracking drive 
github_tracking.py
: first 
add-columns
, then 
writeback
. Both subcommands are idempotent.
仅当源文件是电子表格时执行此步骤。
安全闸门——先备份源文件。
让github-writeback-tracking驱动
github_tracking.py
：先执行
add-columns
（添加列），再执行
writeback
（回写）。这两个子命令都是幂等的。

7. Report back

7. 反馈报告

Summarize the run:
  • Created: count + clickable links + tracking issue link.
  • Held / skipped: the triage wave deferred, plus any real-run errors.
  • Follow-ups: the obvious next wave.
总结运行情况：
  • **已创建：**议题数量 + 可点击链接 + 跟踪议题链接。
  • **保留/跳过：**分类筛选中延迟处理的批次，以及实际运行中的任何错误。
  • **后续建议：**下一批次的明显候选内容。

Safety gates (non-negotiable)

安全闸门（不可协商）

  1. Visual dry-run before real run — step 4 always precedes step 5.
  2. Explicit approval before any write — never jump from classification to creation.
  3. Back up the source before write-back — step 6 edits the file in place.
  1. 实际运行前必须进行可视化试运行——步骤4始终在步骤5之前执行。
  2. 任何写入操作前必须获得明确批准——绝不能从分类直接跳转到创建。
  3. 回写前必须备份源文件——步骤6会直接编辑源文件。