Try Fix Alternative Approach

Try Fix Skill

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

Activation Guard

🚨 This skill is ONLY for proposing and testing code fixes. Do NOT activate for:

• Code review requests ("review this PR", "check code quality")
• PR summaries or descriptions ("what does this PR do?")
• Test-only requests ("run tests", "check CI status")
• General questions about code or architecture

If the prompt does not include a problem to fix and a test command to verify, this skill should not run.

Core Principles

1. Always run once activated - Never question whether to run. The invoker decides WHEN, you decide WHAT alternative to try
2. Single-shot - Each invocation = ONE fix idea, tested, reported
3. Alternative-focused - Always propose something DIFFERENT from existing fixes (review PR changes first)
4. Empirical - Actually implement and test, don't just theorize
5. Context-driven - Work with what's provided and git history; don't search external sources
6. Script-only restoration - The ONLY permitted cleanup command is pwsh .github/scripts/EstablishBrokenBaseline.ps1 -Restore. Never use git checkout, git clean, git restore, git reset, or git stash to revert or clean changes, including after artifacts have been captured.
7. Baseline-file boundary - After Step 2, modify ONLY files listed in .github/.baseline-state.json under RevertedFiles. The restore script tracks only those original fix files; editing any other tracked file makes restoration incomplete. If the state file is absent, or its NewFiles array is non-empty, report Blocked before editing: added production files are not safely restorable. If the approach requires another tracked file, report Blocked instead of editing it.
8. Preserve pre-existing untracked paths - Never modify or delete an untracked file or directory that existed before the attempt. Evaluators may inject the loaded skill as an untracked directory such as try-fix/; leave it exactly as found even when git status --short lists it. It is harness-owned input, not attempt-created drift. The restore script is the only cleanup step; do not use rm, Remove-Item, or another filesystem command to make the worktree appear clean.
9. Wait for command completion - If a shell tool reports that a command is still running and returns a shellId, call read_bash with that exact shellId and wait for the completed result. Never proceed, report, or end the session while baseline, test, artifact, self-review, or restore work is still running.
10. Contain attempt artifacts - Create every log, snapshot, state marker, and scratch file under $OUTPUT_DIR. Never persist $OUTPUT_DIR or other shell state in .github/, the repository root, or another workspace path. Shell variables do not persist between tool calls, so redeclare the same literal $OUTPUT_DIR at the start of each later shell command instead of writing a repository marker file.

Every invocation runs all 11 Workflow steps below. Step 6 (Expert Self-Review) is performed inline against .github/agents/maui-expert-reviewer.md — do NOT spawn the @maui-expert-reviewer sub-agent. Step 7.5 refreshes the self-review if the test loop modified code so the recorded findings reflect the final diff. Step 8 enforces this via a file-existence gate on reviewer-findings.json. Before returning the final report, verify that Step 9 ran with the exact script-only restore command above; if it did not, run it before responding.

⚠️ 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 target source files
• 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).

Outputs

Results reported back to the invoker:

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"

Keep this path from the command output and redeclare it in each subsequent shell invocation, for example:

$OUTPUT_DIR = "CustomAgentLogsTmp/PRState/<ISSUE_OR_PR_NUMBER>/PRAgent/try-fix/attempt-1"

Do not create .github/.try-fix-output-dir, .try-fix-output-dir, or any equivalent repository marker. The only attempt artifacts belong under $OUTPUT_DIR.

Required files to create in $OUTPUT_DIR:

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 ❌
• Expert self-review performed inline (Step 6) and reviewer-findings.json written — [] if clean. Refreshed by Step 7.5 if the test loop modified code, so the saved findings reflect the final diff.
• Analysis provided (success explanation or failure reasoning with evidence)
• Artifacts saved to output directory (verified by Step 8 file-existence gate)
• Baseline target files restored with no attempt-created changes; pre-existing untracked harness inputs remain untouched
• Results reported to invoker (including findings_count)

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

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:

1. Code compiles but tests consistently fail for same reason
2. Root cause analysis reveals fundamental flaw in approach
3. Alternative fixes would require completely different strategy

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

Session limits: Each try-fix invocation allows up to 3 compile/test iterations. The calling orchestrator controls how many invocations (attempts) to run per session (typically 4-5 as part of pr-review Phase 3).

Workflow

Step 1: Understand the Problem and Review Existing Fixes

MANDATORY: Review what has already been tried:

1. 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

2. Review prior attempts if any are known:

   • Note which approaches failed and WHY
   • Note which approaches partially succeeded

3. 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 external context. Work with what's provided and the git history.

Step 2: Establish Baseline (MANDATORY)

🚨 ONLY use EstablishBrokenBaseline.ps1 — NEVER use git checkout, git restore, or git reset to revert fix files.

The script auto-restores any previous baseline, tracks state, and prevents loops. Manual git commands bypass all of this and WILL cause infinite loops in CI.

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

If this command continues in the background, wait for its matching shellId with read_bash until it completes. The baseline is not established merely because the initial shell invocation returned.

Verify baseline was established:

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

Read .github/.baseline-state.json after this command. Its RevertedFiles array is the complete modification allow-list for the attempt. Target files outside that array may be inspected but MUST NOT be edited. If the state file was not created, or NewFiles contains any path, report Blocked immediately and proceed to Step 9 without modifying tracked files; the restore script does not safely restore added production files.

If the script fails with "No fix files detected": Report 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.

Verify the platform code path before implementing. Check which platform-specific file actually executes for the target scenario:

• Files named .iOS.cs compile for both iOS AND MacCatalyst
• Files named .Android.cs only compile for Android
• Some platforms use Legacy implementations (e.g., iOS NavigationPage uses NavigationPage.Legacy.cs, not MauiNavigationImpl) If unsure which code path runs, check AppHostBuilderExtensions or handler registration to confirm.

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

"Different" means different ROOT CAUSE hypothesis, not just different code location.

• ❌ Bad: PR checks adapter == null in OnMeasure; you check adapter == null in OnLayout (same root cause assumption — just a different call site)
• ✅ Good: PR checks adapter == null; you prevent disposal from happening during measure (different root cause hypothesis)

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]

**Prior approach avoided:** [Name every relevant existing/prior approach, their shared failure mechanism, and why they failed, or N/A]

**Mechanism-level difference:** [Explain the full cause-to-effect chain showing why the new mechanism avoids that failure, not merely the code location]
"@ | 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: Expert Self-Review (MANDATORY — runs BEFORE testing)

🚨 You perform this self-review yourself. Do NOT spawn the @maui-expert-reviewer sub-agent. Step 8's file-existence gate enforces that reviewer-findings.json is written every attempt.

This step runs BEFORE testing so you can catch design flaws before spending time on build+test cycles.

Procedure:

1. Read the rules. View these specific sections of .github/agents/maui-expert-reviewer.md:

   • ## Overarching Principles (8 numbered principles, near the top of the file) — apply to every fix
   • ## Dimension Routing + ### Always-Active Dimensions — pick the dimensions that match your changed files
   • For each routed dimension, jump to its CHECK list under ## Review Dimensions (e.g., ### 1. Layout Measure-Arrange Correctness)

   You only need the dimensions that match the files you actually touched plus the always-active ones — typically 3–6 sections, not all 30.

2. Identify your changed files:

   git diff --name-only HEAD

   If you have NO code changes (e.g., Blocked because no device available before any fix was applied), still proceed to step 4 and write '[]' — the artifact gate is the enforcement mechanism.

3. Walk your diff against the rules:

   • For each Overarching Principle → does your diff violate it?
   • For each routed dimension → walk every CHECK rule against the relevant hunks
   • Always-Active dimensions (Logic and Correctness, Regression Prevention, Complexity Reduction) → apply regardless of file paths
   • Be honest. If unsure, flag it.

4. Write findings to $OUTPUT_DIR/reviewer-findings.json. Always write the file, even when there are zero findings. Use the same JSON format as the @maui-expert-reviewer agent (matches the GitHub Pull Request Review API):

   # No findings — clean self-review (or no diff to review):
   '[]' | Set-Content "$OUTPUT_DIR/reviewer-findings.json"
   
   # With findings — JSON array of {path, line, body}:
   @'
   [
     {
       "path": "src/Core/src/Handlers/ScrollView/ScrollViewHandler.iOS.cs",
       "line": 42,
       "body": "**[major] Layout Measure-Arrange** — Content measured with unconstrained height but arranged with bounded height. Concrete scenario: ScrollView inside a Grid with Star row height."
     }
   ]
   '@ | Set-Content "$OUTPUT_DIR/reviewer-findings.json"

   Each entry has exactly 3 fields:

   • path (string) — file relative to repo root, must be a file present in your diff
   • line (integer ≥ 1) — line number on the changed (right) side of the diff. The line MUST appear in your diff — picking an unchanged line is wrong. Use 1 only as a fallback for file-level concerns where no single line captures the issue (e.g., missing import, structural concern).
   • body (string) — format **[severity] Dimension** — description. Severity is one of critical/major/moderate/minor.

5. Validate the JSON parses and capture the count:

   try {
       $findings = @(Get-Content "$OUTPUT_DIR/reviewer-findings.json" -Raw | ConvertFrom-Json)
       $findingsCount = $findings.Count
       Write-Host "✅ reviewer-findings.json: $findingsCount findings"
   } catch {
       Write-Host "❌ reviewer-findings.json is invalid JSON: $_"
       throw
   }
   
   # Snapshot the diff that was reviewed — Step 7.5 uses this to detect whether the test loop mutated code.
   # Use Set-Content -Value with Out-String so the file is created even when the diff is empty
   # (a bare `git diff | Set-Content` does NOT create the file when the pipe is empty).
   Set-Content -Path "$OUTPUT_DIR/reviewer-findings.diff" -Value (git diff | Out-String) -NoNewline

   Remember $findingsCount — you will report it as findings_count in Step 10 and summarize it in analysis.md (Step 8).

6. Fix critical/major findings BEFORE testing:

   • If there are any [critical] or [major] findings → apply fixes for them in a single batch and rewrite reviewer-findings.json to reflect the new diff.
   • All [moderate] and [minor] findings → note in analysis.md (Step 8); do NOT iterate.
   • Only ONE correction round. Then proceed to Step 7 (Test).

Threshold guidance. Only record findings with a concrete failing scenario. Stylistic preferences and bikeshedding (see the ## What NOT to Flag table in maui-expert-reviewer.md) are not findings. An empty [] is the correct output for a clean fix — do not invent findings to fill the file.

Why before testing? Self-review catches design flaws (wrong null check, missing platform guard, thread safety issue) before you spend 5-15 minutes on a build+test cycle. It also runs when context is lightest — before test output floods the context window.