Workaround Search Strategy

Systematic procedure for finding workarounds during triage. Called from research-by-type.md after classifying the issue type.

Goal: Find something the reporter can use RIGHT NOW — even if a proper fix is needed later.

Source Priority Order

Search in this order. Stop as soon as you find a viable workaround, but always check sources 1–3.

Priority	Source	Why first	When to skip
1	Existing triages (`output/ai-triage/`)	Already analyzed, has `analysis.workarounds` and `analysis.resolution.proposals`	On a clean checkout this directory won't exist — the grep commands below use `2>/dev/null` so they'll return empty results gracefully. Always run the check.
2	Closed issues with comments (GitHub via `gh` or MCP)	Reporters post "I solved it by..."	Never — always check
3	Known patterns (`references/skia-patterns.md`, `documentation/dev/packages.md`)	Curated heuristics for common traps	Never — always check
4	SkiaSharp source code (`binding/SkiaSharp/*.cs`)	Alternative APIs visible in the class	Skip if issue is deployment/packaging
5	API docs (`docs/SkiaSharpAPI/SkiaSharp/*.xml`)	Method docs mention alternatives	Skip if issue is deployment/packaging
6	Tutorials (`.docs/docs/docs/`)	Step-by-step examples of correct usage	Skip if not a usage/how-to issue
7	Samples (`samples/`)	Working code for specific platforms	Skip if not a platform integration issue
8	GitHub closed issues (broader search)	Broader search when earlier targeted checks found nothing	Only if targeted search found nothing
9	Web search (Stack Overflow, MS Learn)	Community solutions, framework-side fixes	Only if all local sources exhausted

Step 1 — Extract Search Terms

From the issue body, title, and stack traces, extract:

API/class names: SKCanvas, SKImage, DrawText, FromEncodedData
Error messages: DllNotFoundException, AccessViolationException, EntryPointNotFoundException
Platform/framework: Android, iOS, WASM, Docker, MAUI, Blazor, Avalonia
Package/version: NativeAssets.Linux, NoDependencies, 3.x, 2.88.x

Use both C# names (SKImage) and C API names (sk_image) since issues may reference either.

Step 2 — Search Existing Triages

bash

# Find triages with workarounds
grep -rl '"workarounds"' output/ai-triage/ 2>/dev/null

# Keyword search across triage files
grep -rli "SKImage\|FromEncoded\|DllNotFound" output/ai-triage/*/triage.json 2>/dev/null

# Extract workaround details from matching triages
python3 -c "
import json, glob
for f in glob.glob('output/ai-triage/*/triage.json'):
    with open(f) as fh:
        d = json.load(fh)
    blob = json.dumps(d).lower()
    if not any(kw in blob for kw in ['KEYWORD1', 'KEYWORD2']):
        continue
    analysis = d.get('analysis', {})
    workarounds = analysis.get('workarounds', [])
    res = analysis.get('resolution') or {}
    print(f'#{d[\"meta\"][\"number\"]}: {d.get(\"summary\",\"\")}')
    for w in workarounds:
        print(f'  Workaround: {w}')
    for p in (res.get('proposals') or []):
        print(f'  Proposal: {p.get(\"title\", \"(untitled)\")} - {p[\"description\"][:120]}')
    print()
"

Key JSON paths: analysis.workarounds[] (string array of known workarounds), analysis.resolution.proposals[] (structured proposals with title, description, category, codeSnippet), analysis.resolution.recommendedProposal (suggested pick).

Step 3 — Search Closed Issues

GitHub issue comments are available directly from gh issue view --json comments or GitHub MCP issue/PR tools.

bash

gh search issues "repo:mono/SkiaSharp state:closed KEYWORD1 KEYWORD2" --limit 20 \
  --json number,title,url

python

import json, subprocess

KEYWORDS = ['KEYWORD1', 'KEYWORD2']
SIGNALS = ['workaround', 'solved', 'fixed it', 'i resolved', 'as a workaround',
           'the fix is', 'what worked', 'try using', 'instead of', 'turned out']

search = subprocess.check_output([
    'gh', 'search', 'issues',
    f"repo:mono/SkiaSharp state:closed {' '.join(KEYWORDS)}",
    '--limit', '20', '--json', 'number,title'
], text=True)

for d in json.loads(search):
    detail = subprocess.check_output([
        'gh', 'issue', 'view', str(d['number']),
        '--repo', 'mono/SkiaSharp',
        '--json', 'comments'
    ], text=True)
    comments = json.loads(detail).get('comments', [])
    for c in comments:
        body = (c.get('body') or '').lower()
        if any(sig in body for sig in SIGNALS):
            print(f"#{d['number']}: {d['title'][:60]}")
            author = (c.get('author') or {}).get('login', '?')
            print(f"  By: {author}  {c.get('body','')[:300]}\n")

What to look for: OP says "I solved it by..." (high-value), maintainer suggests alternative (high-value), "closing because fixed in vX.Y.Z" (upgrade workaround), "this is by design" (no workaround — clarify usage).

Direct GitHub search:

bash

gh search issues "SKImage FromEncoded crash" --repo mono/SkiaSharp --state closed --limit 10
gh issue view {N} --repo mono/SkiaSharp --json comments \
  --jq '.comments[] | select(.body | test("workaround|solved|fixed"; "i")) | {author: .author.login, body: .body[:300]}'

Step 4 — Check Known Patterns

bash

grep -n "DllNotFound\|NoDependencies\|container\|Docker\|Alpine\|ARM64" documentation/dev/packages.md
grep -n "KEYWORD" .agents/skills/issue-triage/references/skia-patterns.md

Common instant workarounds:

DllNotFoundException in container → NativeAssets.Linux + install fontconfig
DllNotFoundException in publish → add direct PackageReference in app project
Alpine → use linux-musl-* RID
EntryPointNotFoundException → version mismatch, align managed + native versions
AccessViolationException → check disposal patterns, threading

Step 5 — Search Source Code

bash

# Public methods on a class (find alternatives)
grep -n "public " binding/SkiaSharp/{CLASS}.cs | grep -v "private\|internal\|protected" | head -30

# Factory methods (alternative construction)
grep -n "public static" binding/SkiaSharp/{CLASS}.cs

# Find related implementations across classes
grep -rln "{METHOD}\|{CONCEPT}" binding/SkiaSharp/*.cs

Common API-level workarounds

Problem	Alternative
`SKBitmap` memory issues	Use `SKImage` (immutable, shareable)
`SKCanvas.DrawText` limitations	Use `SKShaper` (HarfBuzz) for complex text
GPU surface issues	Fall back to CPU: `SKSurface.Create()` instead of `SKSurface.CreateAsRenderTarget()`
`SKTypeface` not finding fonts	Use `SKTypeface.FromFile()` or `SKTypeface.FromData()` directly
Color space problems	Explicitly set `SKColorSpace.CreateSrgb()`
`SKImage.FromEncodedData` returns null	Check codec with `SKCodec.Create()` first

Step 6 — Search API Docs

bash

grep -rn "FromEncodedData\|FromEncoded" docs/SkiaSharpAPI/SkiaSharp/{CLASS}.xml
grep -rln "thread\|dispose\|alternative" docs/SkiaSharpAPI/SkiaSharp/

Look for: <remarks> mentioning alternatives, <returns> mentioning null (factory-null-on-failure), <see cref="..."/> cross-references.

Step 7 — Search Tutorials and Samples

bash

grep -rln "KEYWORD" .docs/docs/docs/
grep -rln "KEYWORD" samples/ --include="*.cs" | head -10

Step 8 — Web Search (Last Resort)

Use only when local sources (steps 1–7) are exhausted. Target framework-interaction issues, .NET runtime errors, or platform SDK problems.

web_search: "SkiaSharp {ERROR_MESSAGE} workaround site:stackoverflow.com"
mslearn/microsoft_docs_search: "{FRAMEWORK} SkiaSharp {PROBLEM}"

Trust: GitHub issues (high), MS Learn (high), SO accepted answers (medium-high), blog posts (check version), AI answers (low — often hallucinate APIs).

Search Patterns by Issue Type

Crash/exception: triages for same exception → closed GitHub issues for error message → skia-patterns.md common traps → source code for the method in stack trace. Workaround: null check, try-catch, or alternative API.

Wrong output/rendering: triages for the API → tutorials for correct usage → source for parameter validation → samples for working examples. Workaround: minimal working example showing correct approach.

Deployment/DllNotFoundException: documentation/dev/packages.md FIRST (almost always has the answer) → skia-patterns.md native loading → closed GitHub issues for same platform combo. Workaround: package swap, direct PackageReference, or system dependency install.

Question (how to do X): tutorials → API docs → samples → closed GitHub issues (many questions repeat) → web search MS Learn. Workaround: assemble code snippet from docs + source.

Feature request (API doesn't exist): source code for partial solutions → Skia C++ headers for upstream capability → triages for similar requests. Workaround: show existing APIs that achieve the result, even if verbose.

Constructing a Workaround from Scratch

When no existing workaround is found:

Identify failure boundary — What specific call fails? API call itself, or setup/teardown?

Find nearest working path:

bash

grep "public " binding/SkiaSharp/{CLASS}.cs | grep -v "private\|internal\|protected"
grep "public static" binding/SkiaSharp/{CLASS}.cs
grep -rln "{METHOD}\|{CONCEPT}" binding/SkiaSharp/*.cs

Draft the workaround — format as: one-sentence summary, copy-pasteable code, limitations, and what a proper fix would look like.
Validate — Does it avoid the crash path? Produce correct output? Work on the reporter's platform? Reasonable burden?