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.