report-to-issues

Workflow

Phase 1: Locate Report

1. If the user specifies a file path, use it directly.
2. Otherwise, list available reports:
   • docs/evaluation/ — software-evaluation reports
   • docs/security-audit/ — vulnerability-scan reports, and sakuda-triage reports (sakuda-triage.*.md, same format — only confirmed findings have ### V-XX sections)
   • docs/dependency-audit/ — dependency-audit reports (same security-audit format; one ### V-XX per package upgrade, P0/P1 only). Treat them as security-audit reports, including the security-audit label. A report whose status is not run yields no tasks — say so and point at its Coverage reasons instead of reporting "nothing to file"
   • Skip docs/security-audit/rule-proposals.*.md — those are rule proposals from rule-proposer, not findings
   • If multiple exist, ask the user to select one.
3. Detect report type by content:
   • Contains ## Improvement Roadmap → evaluation report
   • Contains ## Remediation Priority → security-audit report

Phase 2: Extract Tasks

Evaluation report — extract rows from ## Improvement Roadmap tables (P0–P3):

Each row yields:

• priority: P0 / P1 / P2 / P3
• title: Problem column (first sentence or file:line prefix)
• problem: full Problem cell
• solution: Solution cell
• expected_outcome: Expected Outcome cell

Security-audit report — extract from ## Remediation Priority table AND individual ## Findings sections:

Each row yields:

• priority: P0 / P1 from Priority column
• title: Finding column
• action: Action column
• body: full finding detail from the matching ### V-XX section (Vulnerable Code, Attack Path, Risk Assessment, Recommended Fix)

Phase 3: Present Tasks for Selection

Display all extracted tasks before creating any issue:

Extracted tasks from <report file>:

  1. [P0] <title> (<file:line if present>)
  2. [P1] <title>
  3. [P1] <title>
  ...

Which tasks would you like to register as GitHub Issues?
Enter numbers (e.g. 1 3 5), a range (e.g. 1-3), "all", or "none":

Wait for the user's response before proceeding.

Phase 4: Duplicate Detection

Before creating issues, check for existing issues that may overlap with the selected tasks.

4.1 Fetch existing open issues:

gh issue list --state open --json number,title,labels --limit 200

4.2 For each selected task, check for duplicates:

Compare the task title/problem against existing issue titles using keyword overlap. Flag a potential duplicate when:

• 3+ significant keywords match between the task and an existing issue title/body
• The same file:line location is referenced
• The same label combination exists (e.g., both P0 + security-audit)

4.3 Present duplicates to the user:

⚠ Potential duplicates detected:

  Task 2: [P1] No timeouts on external HTTP calls
    → May overlap with #34: "[P1] Add timeout to fetch calls in src/lib/http.ts"

  Task 5: [P0] SQL Injection in user search
    → May overlap with #12: "[P0] Parameterize DB queries in src/api/"

Create anyway? Enter task numbers to skip (e.g. 2 5), or "proceed" to create all:

Wait for the user's response. Remove confirmed duplicates from the creation list.

Phase 5: Ensure Labels Exist

Before creating issues, verify required labels exist. Required labels:

Check and create missing labels:

gh label list --json name | jq -r '.[].name'
gh label create "<label>" --color "<hex>" --description "<desc>"

Phase 6: Create Issues

For each selected task (after duplicate filtering), create the issue using the gh CLI --body flag with the formatted content:

gh issue create --title "<title>" --body "<body>" --label "<label1>" --label "<label2>"

Title format:

• Evaluation: [<Priority>] <problem summary>
• Security: [<Priority>] <finding title>

Body format — evaluation task:

## Problem
<problem>

## Solution
<solution>

## Expected Outcome
<expected_outcome>

---
*Source: <report file path>*

Body format — security finding:

## Finding
<full finding detail: Vulnerable Code, Attack Path, Risk Assessment>

## Recommended Fix
<recommended fix>

## Action
<action from Remediation Priority table>

---
*Source: <report file path>*

Labels per issue:

• Always add report-type label: software-evaluation or security-audit
• Always add priority label: P0, P1, P2, or P3
• Security findings: also add severity label (critical, high, medium, low)

Check exit code after each gh issue create. If non-zero, report the error and continue with remaining tasks.

Phase 7: Summary

After all issues are created, output:

Registered N / M issues:
  #<number>  <title>  <URL>
  #<number>  <title>  <URL>
  ...

Skipped: <any that failed with reason>

Quality Gate

• Report file exists and type is correctly detected
• All extracted tasks shown to user before any issue is created
• User selection confirmed
• Duplicate detection run against existing open issues
• Duplicate conflicts resolved by user before creation
• Labels verified / created before issue creation
• Each gh issue create exit code checked
• Final summary lists all created issue URLs