Issue Triage

Triage Issue

Issue pipeline: Step 1 of 3 (Triage). See documentation/dev/issue-pipeline.md.

Analyze a SkiaSharp GitHub issue and produce a structured, schema-validated triage JSON.

⛔ MANDATORY FIRST STEPS (do not skip)

1. Read THIS entire SKILL.md before any investigation
2. Read references/schema-cheatsheet.md for required fields and enums
3. Read references/anti-patterns.md for critical rules

These 3 reads are REQUIRED. Do not proceed to Phase 1 until all three are loaded.

Quick flow:

1. Load issue data from GitHub (prefer gh, or GitHub MCP when available)
2. Read references: schema-cheatsheet, labels, triage-examples, anti-patterns
3. Create brief plan (5-10 lines)
4. Investigate code — READ-ONLY, never edit source files
5. Generate JSON
6. Validate with script
7. Persist JSON + Markdown + HTML reports

Data sources

Primary source: GitHub itself. Prefer gh CLI for repeatable issue/PR fetches and searches. If the environment exposes GitHub MCP issue/PR lookup tools, those are also valid. Do not set up or depend on a cache worktree or cache branch for this skill.

Phase 1 (Setup) → Phase 2 (Investigate) → Phase 3 (Analyze) → Phase 4 (Workarounds) → Phase 5 (Validate) → Phase 6 (Persist & Render)

Phase 1 — Setup

Run once per session:

pip3 install -r .agents/skills/issue-triage/scripts/requirements.txt --quiet
python3 --version  # Requires 3.9+
python3 -c "import jinja2; print('jinja2', jinja2.__version__)"  # pip3 install jinja2
gh --version
gh auth status

If gh is unavailable or unauthenticated, use the GitHub MCP issue/PR retrieval and search tools available in the environment.

Phase 2 — Investigate

1. Read the issue

gh issue view {number} --repo mono/SkiaSharp \
  --json number,title,body,labels,comments,state,createdAt,updatedAt,closedAt,author,milestone \
  > /tmp/{number}.issue.json

GitHub MCP issue/PR retrieval tools are equally valid if the environment exposes them.

2. Code Investigation (MANDATORY)

Scope: READ code, don't WRITE code. Grep, read files, trace call chains. Never create files, compile, or execute.

Before ANY classification, search the source code for the types, methods, APIs, or behaviors mentioned in the issue. Read the relevant files. Record every finding in analysis.codeInvestigation as {file, finding, relevance} (with optional lines).

Do NOT classify until you have examined source code. For bugs, include at least one codeInvestigation entry. Close-* actions should include at least two.

Steps:

1. Grep for the types/methods/APIs mentioned in the issue
2. Read the relevant source files (platform handlers, core APIs, etc.)
3. Check if the reported behavior matches current code
4. For bugs: trace the code path — does the issue still exist?
5. For feature requests: has it been implemented since filing?
6. For questions: does the source confirm or contradict the assumption?
7. Search for related issues AND PRs — use gh CLI or GitHub MCP directly:

   # Search issues (finds duplicates, prior reports, related discussions)
   gh search issues "{keywords from issue}" --repo mono/SkiaSharp --limit 10 \
     --json number,title,state,url
   # Search PRs (finds fixes, prior attempts, reverted changes)
   gh pr list --search '{keywords from issue}' --state all --repo mono/SkiaSharp --limit 10 --json number,title,state,mergedAt
   

   Include ALL related issues and PRs in evidence.reproEvidence.repoLinks — both duplicate/related issues AND closed/unmerged PRs, as they reveal prior reports and maintainer decisions. Duplicate issues are especially important for close-as-duplicate classification.

3. Additional Research

Pre-flight — confirm before analyzing:

• Issue data loaded from gh CLI or GitHub MCP
• Read references/schema-cheatsheet.md for required fields and enums
• Read references/labels.md for valid label values
• Read references/triage-examples.md for calibration
• Read references/anti-patterns.md — at least the critical rules
• Created a brief plan (5-10 lines: what to investigate, what type you suspect)

Reminder: Triage is READ-ONLY. Do NOT edit any source files (.cs, .cpp, .csproj, .json).

Phase 3 — Analyze

First triage in session

Read references/labels.md for valid label values and cardinality, references/triage-examples.md for calibration, and references/schema-cheatsheet.md for required fields.

Classify and generate JSON

Write brief internal analysis (3–5 sentences), classify the type, then read references/research-by-type.md for type-specific research. Conduct the research, then generate the JSON. Write to /tmp/{number}.json. Use this exact literal path structure, do NOT substitute $TMPDIR or any other variable. Do NOT use mkdir — write directly to /tmp/.

⚠️ Schema Compliance:

1. Read references/schema-cheatsheet.md — This is the authoritative source for structure, fields, and enums.
2. Review references/labels.md — Use only valid label values.
3. Follow these critical constraints:
   • meta.schemaVersion must be "1.0"
   • Optional fields: OMIT entirely if not applicable. Do NOT set to null.
   • String Arrays: platforms, backends, tenets, perf are simple string arrays (no confidence wrapper). Any perf/* value implies tenet/performance — include it in tenets.
   • Investigation: analysis.codeInvestigation is MANDATORY. At least one entry for bugs, two for close-* actions.
   • Rationale: analysis.rationale is a single summary string (not per-field).
   • Validation: No extra properties allowed (additionalProperties: false).

JSON Groups Overview

Refer to the cheatsheet for the exact field structure and enum values.

Phase 4 — Workarounds

For bugs, questions, and feature requests: actively search for workarounds the reporter can use now. Follow references/workaround-search.md — 9 sources in priority order (existing triages → closed issues → known patterns → source code → docs → web).

• Set proposal category to "workaround" / "fix" / "alternative" / "investigation"
• Include codeSnippet on any proposal with copy-paste-ready code

Skip this phase for duplicates and abandoned issues (omit analysis.resolution).

Validate Code in Proposals

If any proposal includes a codeSnippet or the add-comment comment contains code: you must validate it with 3 parallel agents per references/workaround-validation.md. Do not suggest code that has not been checked.

Agents (parallel explore type, GPT-5.6 Luna model):

1. API correctness — do the SK* types/methods exist with correct signatures?
2. Behavioral correctness — disposal, null-checks, threading, does it solve the problem?
3. Platform safety — will it work on the reporter's platform?

Synthesis: All pass → validated: "yes". Any warn → add caveats to comment, reduce confidence. Any fail → fix or strip code, set validated: "no".

If no proposals contain code, set validated: "untested".

Phase 5 — Validate

🛑 PHASE GATE: You CANNOT proceed to Phase 6 without passing validation. Skipping validation = INVALID triage. The task is incomplete.

python3 .agents/skills/issue-triage/scripts/validate-triage.py /tmp/{number}.json

• Exit 0 = ✅ valid → proceed to Phase 6
• Exit 1 = ❌ fix the errors listed in the output, then re-run. Repeat up to 3 times.
• Exit 2 = fatal error, stop and report

⚠️ NEVER hand-roll your own validation. NEVER assume it passes. RUN THE SCRIPT.

Phase 6 — Persist & Present

🛑 PHASE GATE: Phase 5 validator MUST have printed ✅ before you reach this step. If you have not run the validation script, GO BACK and run it now.

1. Persist

Copy the validated JSON to output/ai-triage/ for collection, then render companion Markdown and HTML reports that wrap the same JSON data.

python3 .agents/skills/issue-triage/scripts/persist-triage.py /tmp/{number}.json

This produces:

• output/ai-triage/{number}/triage.json
• output/ai-triage/{number}/triage.md
• output/ai-triage/{number}/triage.html

2. Present summary

✅ Triage: ai-triage/{number}/triage.json
✅ Report: ai-triage/{number}/triage.md
✅ Viewer: ai-triage/{number}/triage.html

Type:     type/bug (0.98)     Area: area/SkiaSharp
Severity: critical            Action: needs-investigation

Actions:
  labels-1   update-labels   [low]  Add type/bug, area/SkiaSharp
  comment-1  add-comment     [high] ⚠️ requires human edit
  link-1     link-related    [low]  Cross-ref #1234

Pipeline hint:

• If classification.type.value == "type/bug" and output.actionability.suggestedAction == "needs-investigation": next step is issue-repro (ai-repro/{number}/repro.json).
• If classification.type.value is type/enhancement or type/feature-request and suggestedAction == "needs-investigation": next step is also issue-repro, but repro will use confirmed/not-confirmed instead of reproduced/not-reproduced.
• output.actionability.suggestedReproPlatform tells CI which runner to use for reproduction:
  • macos — for os/iOS, os/macOS, os/tvOS, os/watchOS issues
  • windows — for os/Windows-Classic, os/Windows-WinUI, os/Windows-Universal-UWP, os/Windows-Nano-Server issues
  • linux — for everything else (os/Linux, os/WASM, os/Android, os/Tizen, or no platform specified)
  • Note: For platform-independent API bugs (e.g., SVG output, stream handling), prefer linux even if the reporter tests on other platforms.
• If repro already exists and reproduces: next step is issue-fix (consume both JSONs).

If add-comment exists, show comment in a copy-paste block. ⚠️ NEVER post via GitHub API.

Anti-Patterns

See references/anti-patterns.md — read this file on first triage in session.

#0 (CRITICAL): Triage is READ-ONLY. If you edit a source file during triage, you have FAILED. See the anti-patterns reference for the full list.

#1 (CRITICAL): NEVER use store_memory during triage. Triage produces JSON artifacts, not memories. Storing unverified facts pollutes all future sessions.

#2 (CRITICAL): NEVER skip the validation script. You MUST run validate-triage.py and see ✅ before persisting. Mentally checking fields is not validation. If the script isn't run, the triage is invalid.

Scripts

• scripts/validate-triage.py <triage.json> — Validate against schema + rationale coverage + action integrity
• scripts/persist-triage.py <triage.json> — Copy validated JSON to output/ai-triage/{number}/ and invoke renderer
• scripts/render-triage-report.py <triage.json> — Render validated triage JSON → .md + .html (uses Jinja2 template for markdown)
• scripts/triage-report.md.jinja2 — Jinja2 template for the Markdown report
• scripts/viewer.html — Bootstrap 5 HTML template for the interactive viewer