Try Fix Skill

Attempts ONE fix for a given problem. Receives all context upfront, tries a single approach, tests it, and reports what happened.

Core Principles

• Always run - Never question whether to run. The invoker decides WHEN, you decide WHAT alternative to try

• Single-shot - Each invocation = ONE fix idea, tested, reported

• Alternative-focused - Always propose something DIFFERENT from existing fixes (review PR changes first)

• Empirical - Actually implement and test, don't just theorize

• Context-driven - All information provided upfront; don't search for additional context

Every invocation: Review existing fixes → Think of DIFFERENT approach → Implement and test → Report results

⚠️ CRITICAL: Sequential Execution Only

🚨 Try-fix runs MUST be executed ONE AT A TIME - NEVER in parallel.

Why: Each try-fix run:

• Modifies the same source files (SafeAreaExtensions.cs, etc.)

• Uses the same device/emulator for testing

• Runs EstablishBrokenBaseline.ps1 which reverts files to a known state

If run in parallel:

• Multiple agents will overwrite each other's code changes

• Device tests will interfere with each other

• Baseline script will conflict, causing unpredictable file states

• Results will be corrupted and unreliable

Correct pattern: Run attempt-1, wait for completion, then run attempt-2, etc.

Inputs

All inputs are provided by the invoker (CI, agent, or user).

Input Required Description

Problem Yes Description of the bug/issue to fix

Test command Yes Repository-specific script to build, deploy, and test (e.g., pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform android -TestFilter "Issue12345" ). ALWAYS use this script - NEVER manually build/compile.

Target files Yes Files to investigate for the fix

Platform Yes Target platform (android , ios , windows , maccatalyst )

Hints Optional Suggested approaches, prior attempts, or areas to focus on

Baseline Optional Git ref or instructions for establishing broken state (default: current state)

Outputs

Results reported back to the invoker:

Field Description

approach

What fix was attempted (brief description)

files_changed

Which files were modified

result

Pass , Fail , or Blocked

analysis

Why it worked, or why it failed and what was learned

diff

The actual code changes made (for review)

Output Structure (MANDATORY)

FIRST STEP: Create output directory before doing anything else.

Set issue/PR number explicitly (from branch name, PR context, or manual input)

$IssueNumber = "<ISSUE_OR_PR_NUMBER>" # Replace with actual number

Find next attempt number

$tryFixDir = "CustomAgentLogsTmp/PRState/$IssueNumber/PRAgent/try-fix" $existingAttempts = (Get-ChildItem "$tryFixDir/attempt-*" -Directory -ErrorAction SilentlyContinue).Count $attemptNum = $existingAttempts + 1

Create output directory

$OUTPUT_DIR = "$tryFixDir/attempt-$attemptNum" New-Item -ItemType Directory -Path $OUTPUT_DIR -Force | Out-Null

Write-Host "Output directory: $OUTPUT_DIR"

Required files to create in $OUTPUT_DIR :

File When to Create Content

baseline.log

After Step 2 (Baseline) Output from EstablishBrokenBaseline.ps1 proving baseline was established

approach.md

After Step 4 (Design) What fix you're attempting and why it's different from existing fixes

result.txt

After Step 6 (Test) Single word: Pass , Fail , or Blocked

fix.diff

After Step 6 (Test) Output of git diff showing your changes

test-output.log

After Step 6 (Test) Full output from test command

analysis.md

After Step 6 (Test) Why it worked/failed, insights learned

Example approach.md:

Approach: Geometric Off-Screen Check

Skip RequestApplyInsets for views completely off-screen using simple bounds check: viewLeft >= screenWidth || viewRight <= 0 || viewTop >= screenHeight || viewBottom <= 0

Different from existing fix: Current fix uses HashSet tracking. This approach uses pure geometry with no state.

Example result.txt:

Pass

Completion Criteria

The skill is complete when:

• Problem understood from provided context

• ONE fix approach designed and implemented

• Fix tested with provided test command (iterated up to 3 times if errors/failures)

• Either: Tests PASS ✅, or exhausted attempts and documented why approach won't work ❌

• Analysis provided (success explanation or failure reasoning with evidence)

• Artifacts saved to output directory

• Baseline restored (working directory clean)

• Results reported to invoker

🚨 CRITICAL: What counts as "Pass" vs "Fail"

Scenario Result Explanation

Test command runs, tests pass ✅ Pass Actual validation

Test command runs, tests fail ❌ Fail Fix didn't work

Code compiles but no device available ⚠️ Blocked Device/emulator unavailable - report with explanation

Code compiles but test command errors ❌ Fail Infrastructure issue is still a failure

Code doesn't compile ❌ Fail Fix is broken

NEVER claim "Pass" based on:

• ❌ "Code compiles successfully" alone

• ❌ "Code review validates the logic"

• ❌ "The approach is sound"

• ❌ "Device was unavailable but fix looks correct"

Pass REQUIRES: The test command executed AND reported test success.

If device/emulator is unavailable: Report result.txt = Blocked with explanation. Do NOT manufacture a Pass.

Exhaustion criteria: Stop after 3 iterations if:

• Code compiles but tests consistently fail for same reason

• Root cause analysis reveals fundamental flaw in approach

• Alternative fixes would require completely different strategy

Never stop due to: Compile errors (fix them), infrastructure blame (debug your code), giving up too early.

Workflow

Step 1: Understand the Problem and Review Existing Fixes

MANDATORY: Review what has already been tried:

Check for existing PR changes:

git diff origin/main HEAD --name-only

• Review what files were changed

• Read the actual code changes to understand the current fix approach

Review prior attempts if any are known:

• Note which approaches failed and WHY

• Note which approaches partially succeeded

Identify what makes your approach DIFFERENT:

• Don't repeat the same logic/pattern as existing fixes

• Think of alternative approaches: different algorithm, different location, different strategy

• If existing fix modifies X, consider modifying Y instead

• If existing fix adds logic, consider removing/simplifying instead

Examples of alternatives:

• Existing fix: Add caching → Alternative: Change when updates happen

• Existing fix: Fix in handler → Alternative: Fix in platform layer

Review the provided context:

• What is the bug/issue?

• What test command verifies the fix?

• What files should be investigated?

• Are there hints about what to try or avoid?

Do NOT search for additional context. Work with what's provided.

Step 2: Establish Baseline (MANDATORY)

🚨 ALWAYS use EstablishBrokenBaseline.ps1 - NEVER manually revert files.

Capture baseline output as proof it was run

pwsh .github/scripts/EstablishBrokenBaseline.ps1 *>&1 | Tee-Object -FilePath "$OUTPUT_DIR/baseline.log"

The script auto-detects and reverts fix files to merge-base state while preserving test files. Will fail fast if no fix files detected - the PR's changes must be present in the current branch (the Review-PR.ps1 script handles this by merging the PR before the agent runs). Optional flags: -BaseBranch main , -DryRun .

Verify baseline was established:

baseline.log should contain "Baseline established" and list of reverted files

Select-String -Path "$OUTPUT_DIR/baseline.log" -Pattern "Baseline established"

If the script fails with "No fix files detected": The PR changes are not present on the current branch. Report this as Blocked — do NOT switch branches.

If something fails mid-attempt: pwsh .github/scripts/EstablishBrokenBaseline.ps1 -Restore

Step 3: Analyze Target Files

Read the target files to understand the code.

Key questions:

• What is the root cause of this bug?

• Where should the fix go?

• What's the minimal change needed?

Step 4: Design ONE Fix

Based on your analysis and any provided hints, design a single fix approach:

• Which file(s) to change

• What the change is

• Why you think this will work

If hints suggest specific approaches, prioritize those.

IMMEDIATELY create approach.md in your output directory:

@"

Approach: [Brief Name]

[Description of what you're changing and why]

Different from existing fix: [How this differs from PR's current approach] "@ | Set-Content "$OUTPUT_DIR/approach.md"

Step 5: Apply the Fix

Implement your fix. Use git status --short and git diff to track changes.

Step 6: Test and Iterate (MANDATORY)

🚨 CRITICAL: ALWAYS use the provided test command script - NEVER manually build/compile.

For .NET MAUI repository: Use BuildAndRunHostApp.ps1 which handles:

• Building the project

• Deploying to device/simulator

• Running tests

• Capturing logs

Capture output to test-output.log while also displaying it

pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform <platform> -TestFilter "<filter>" *>&1 | Tee-Object -FilePath "$OUTPUT_DIR/test-output.log"

Testing Loop (Iterate until SUCCESS or exhausted):

• Run the test command - It will build, deploy, and test automatically

• Check the result:

• ✅ Tests PASS → Move to Step 7 (Capture Artifacts)

• ❌ Compile errors → Fix compilation issues (see below), go to step 1

• ❌ Tests FAIL (runtime) → Analyze failure, fix code, go to step 1

• Maximum 3 iterations - If still failing after 3 attempts, analyze if approach is fundamentally flawed

• Document why - If exhausted, explain what you learned and why the approach won't work

Behavioral constraints:

• ⚠️ NEVER blame "test infrastructure" - assume YOUR fix has a bug

• Compile errors mean "work harder" - not "give up"

• DO NOT manually build - always rerun the test command script

See references/compile-errors.md for error patterns and iteration examples.

Step 7: Capture Artifacts (MANDATORY)

Before reverting, save ALL required files to $OUTPUT_DIR :

1. Save result (MUST be exactly "Pass", "Fail", or "Blocked")

"Pass" | Set-Content "$OUTPUT_DIR/result.txt" # or "Fail"

2. Save the diff

git diff | Set-Content "$OUTPUT_DIR/fix.diff"

3. Save test output (should already exist from Step 6)

Copy-Item "path/to/test-output.log" "$OUTPUT_DIR/test-output.log"

4. Save analysis

@"

Analysis

Result: Pass/Fail/Blocked

What happened: [Description of test results]

Why it worked/failed: [Root cause analysis]

Insights: [What was learned that could help future attempts] "@ | Set-Content "$OUTPUT_DIR/analysis.md"

Verify all required files exist:

@("baseline.log", "approach.md", "result.txt", "fix.diff", "analysis.md", "test-output.log") | ForEach-Object { if (Test-Path "$OUTPUT_DIR/$") { Write-Host "✅ $" } else { Write-Host "❌ MISSING: $_" } }

Analysis quality matters. Bad: "Didn't work". Good: "Fix attempted to reset state in OnPageSelected, but this fires after layout measurement. The cached value was already used."

Step 8: Restore Working Directory (MANDATORY)

ALWAYS restore, even if fix failed.

pwsh .github/scripts/EstablishBrokenBaseline.ps1 -Restore git checkout HEAD -- .

Step 9: Report Results

Provide structured output to the invoker:

Try-Fix Result

Approach: [Brief description of what was tried]

Files Changed:

• path/to/file.cs (+X/-Y lines)

Result: ✅ PASS / ❌ FAIL

Analysis: [Why it worked, or why it failed and what was learned]

Diff:

[The actual changes made]

This Attempt's Status: Done/NeedsRetry
Reasoning: [Why this specific approach succeeded or failed]

**Determining Status:** Set `Done` when you've completed testing this approach (whether it passed or failed). Set `NeedsRetry` only if you hit a transient error (network timeout, flaky test) and want to retry the same approach.

## Error Handling

| Situation | Action |
|-----------|--------|
| Problem unclear | Report "insufficient context" - specify what's missing |
| Test command fails to run | Report build/setup error with details |
| Test times out | Report timeout, include partial output |
| Can't determine fix approach | Report "no viable approach identified" with reasoning |
| Git state unrecoverable | Run `git checkout HEAD -- .` and `git clean -fd` if needed |

---

## Guidelines for Proposing Fixes

### Good Fix Approaches

✅ **Null/state checks** - Guard against unexpected null or state
✅ **Lifecycle timing** - Move code to correct lifecycle event
✅ **Cache invalidation** - Reset stale cached values

### Approaches to Avoid

❌ **Massive refactors** - Keep changes minimal
❌ **Suppressing symptoms** - Fix root cause, not symptoms
❌ **Multiple unrelated changes** - ONE focused fix per invocation

---

See [references/example-invocation.md](references/example-invocation.md) for a complete example with sample inputs.