Issue Pipeline Guide

This repo has a 3-step issue pipeline designed to minimize duplicated work:

1. Triage → classify + collect evidence + investigate code + propose actions
2. Repro → produce factual reproduction results + version matrix + minimal repro source
3. Fix → root-cause, minimal fix, regression test, PR

The skills are meant to be run in order (often by different people / at different times). Data is handed off via JSON files stored on the docs-data-cache branch.

Data cache layout (handoff mechanism)

All three skills should prefer the local cache worktree when available:

[ -d ".data-cache" ] || git worktree add .data-cache docs-data-cache
git -C .data-cache pull --rebase origin docs-data-cache
CACHE=".data-cache/repos/mono-SkiaSharp"

Expected artifact locations:

• "$CACHE/ai-triage/{n}.json"
• "$CACHE/ai-repro/{n}.json"
• "$CACHE/ai-fix/{n}.json"

Role boundaries (what each skill owns)

issue-triage (Step 1 of 3)

Owns (exclusive):

• Classification: type, area, platform labels, severity, actionability
• Evidence extraction: steps, snippets, attachments, environment info
• Source code investigation: analysis.codeInvestigation with file:line citations
• Workaround search: actionable options for the reporter now
• Suggested action: whether the issue should proceed to repro/fix

Does not own:

• Building/running code to confirm (that’s repro)
• Root-cause debugging/fixes (that’s issue-fix)

issue-repro (Step 2 of 3)

Owns (exclusive):

• Factual reproduction (no judgment): did the reported symptoms occur?
• Version matrix: reporter → latest stable → main (source) when feasible
• Platform dispatch: select platform-specific playbook (references/platform-*.md) based on issue signals and triage data
• Cross-platform verification: test on alternative platform to determine scope (universal vs platform-specific)
• Minimal repro source: capture text source files via reproductionSteps[].filesCreated[].content (Program.cs, .csproj, etc.)

Does not own:

• Root-cause analysis or proposing fixes
• Primary label/closure decisions (triage owns initial classification, but repro may update labels when reproduction confirms or contradicts platform scope)

issue-fix (Step 3 of 3)

Owns (exclusive):

• Root-cause analysis and minimal code change
• Regression tests and verifying the fix
• PR authoring, review readiness

Does not own:

• Re-triaging/classifying when ai-triage exists (only update if evidence contradicts)
• Rebuilding a repro project from scratch when ai-repro exists (reuse it)

Handoff contract (fields consumers should rely on)

triage → repro

Repro consumes triage for platform selection and hints:

• classification.platforms[] → informs platform file selection (e.g., ["os/Linux"] → Docker)
• classification.* (type/area/backends)
• evidence.reproEvidence.* (steps/snippets/attachments)
• evidence.bugSignals.* (severity, errorType, errorMessage, stackTrace)
• analysis.codeInvestigation[] (entry points / suspected code paths)
• analysis.workarounds[] (workarounds to validate)
• analysis.nextQuestions[] (what's still unknown)
• output.actionability.* + output.missingInfo

repro → fix

Fix should treat repro JSON as the baseline execution record:

• conclusion + notes
• versionResults[] (especially whether main (source) reproduces)
• reproProject (packages + tfm)
• reproductionSteps[] including source file content in filesCreated[].content
• environment (os/arch/dotnetVersion/skiaSharpVersion/dockerUsed)
• artifacts[] (binary inputs and where to get them)
• feedback.corrections[] (where repro corrected triage)

Reproduction strategy alignment (NuGet vs Docker)

• Default: reproduce using a standalone NuGet-based console/test project.
• Docker: use only when the reported platform is unavailable on the host (or when the repro explicitly requires Linux/Android/etc.).
• issue-fix should start from ai-repro:
  • Rehydrate the repro project from ai-repro source files.
  • Re-run after applying the fix to verify it is resolved.
  • Only run a separate Docker-based repro if the issue is platform-only and cannot be exercised otherwise.

Pipeline gates (when to run the next step)

• If triage suggests request-info or close-*: do not run repro/fix unless a human overrides.
• If repro concludes not-reproduced / inconclusive: issue-fix generally should not start; instead update triage actions (request more info / close / document).
• If repro concludes reproduced: proceed to issue-fix.
• If repro concludes confirmed with assessment: "feature-request": proceed to add-api skill (not issue-fix).
• If repro concludes confirmed with assessment: "docs-gap": proceed to api-docs skill.
• If repro concludes not-confirmed: close or request more info (feature already exists or docs are correct).

PR integration (issue-fix)

When ai-triage/ai-repro exist, the issue-fix PR should copy in:

• A short triage summary (type/area/platform/severity + key codeInvestigation entries)
• Reproduction matrix from versionResults[]
• The minimal repro commands (from reproductionSteps[].command) and any required artifacts

Feedback loop (downstream corrections)

Each step records corrections to upstream findings in its OWN JSON — never edit upstream files directly.

Each correction has:

• topic — what category (classification, scope, root-cause, affected-platforms, etc.)
• upstream — what the upstream step said
• corrected — what this step actually found
• source — which upstream step is being corrected ("triage" or "repro" for fix; always "triage" for repro)

Rules:

• Corrections are additive — never edit upstream JSON files
• Future triage/repro runs can read downstream corrections to improve
• Corrections help identify systematic triage/repro weaknesses

Progress tracking

Pipeline progress per issue can be determined by checking which artifacts exist:

To check pipeline status for an issue:

CACHE=".data-cache/repos/mono-SkiaSharp"
N=1234
[ -f "$CACHE/ai-triage/$N.json" ] && echo "✅ Triaged"
[ -f "$CACHE/ai-repro/$N.json" ] && echo "✅ Reproduced" && python3 -c "import json; print('  conclusion:', json.load(open('$CACHE/ai-repro/$N.json'))['conclusion'])"
[ -f "$CACHE/ai-fix/$N.json" ] && echo "✅ Fix" && python3 -c "import json; print('  status:', json.load(open('$CACHE/ai-fix/$N.json'))['status']['value'])"