try-fix

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

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.

⚠️ 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).

Input	Required	Description
Problem	Yes	Description of the bug/issue to fix
Test command	Yes	Repository-specific script to build and test. Use BuildAndRunHostApp.ps1 for UI tests, Run-DeviceTests.ps1 for device tests, or dotnet test for unit tests. The correct command is determined by the test type detected in the PR. ALWAYS use the appropriate 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)
findings_count	Number of self-review findings recorded (0 = clean self-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
reviewer-findings.json	After Step 6 (Self-Review), refreshed by Step 7.5	JSON array of self-review findings — [] when clean. MUST reflect the final diff.
reviewer-findings.diff	After Step 6 (Self-Review), refreshed by Step 7.5	Snapshot of git diff at the time the self-review was written. Step 7.5 compares this to the post-test-loop diff to detect drift.
result.txt	After Step 7 (Test)	Single word: Pass, Fail, or Blocked
fix.diff	After Step 7 (Test)	Output of git diff showing your changes
test-output.log	After Step 7 (Test)	Full output from test command
analysis.md	After Step 8 (Capture)	Why it worked/failed, insights learned, and a one-line self-review summary

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 restored (working directory clean)
• Results reported to invoker (including findings_count)

🚨 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:

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"

Verify baseline was established:

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

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

R

---

Content truncated.