name: try-fix description: Attempts ONE alternative fix for a bug, tests it empirically, and reports results. ALWAYS explores a DIFFERENT approach from existing PR fixes. Use when CI or an agent needs to try independent fix alternatives. Invoke with problem description, test command, target files, and optional hints.

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

1. Always run - 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 - All information provided upfront; don't search for additional context

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

Inputs

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

Outputs

Results reported back to the invoker:

Output Structure

Save artifacts to CustomAgentLogsTmp/PRState/<PRNumber>/try-fix/attempt-<N>/ with files: approach.md, fix.diff, test-output.log, result.txt, analysis.md.

See references/output-structure.md for setup commands and directory structure details.

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

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.

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. If state_file provided, review prior attempts:

   • Read the Fix Candidates table
   • Note which approaches failed and WHY (the Notes column)
   • 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 additional context. Work with what's provided.

Step 2: Establish Baseline (MANDATORY)

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

pwsh .github/scripts/EstablishBrokenBaseline.ps1

The script auto-detects and reverts fix files to merge-base state while preserving test files. Will fail fast if no fix files detected - you must be on the actual PR branch. Optional flags: -BaseBranch main, -DryRun.

If the script fails with "No fix files detected": You're likely on the wrong branch. Checkout the actual PR branch with gh pr checkout <PR#> and try again.

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.

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

pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform <platform> -TestFilter "<filter>"

Testing Loop (Iterate until SUCCESS or exhausted):

1. Run the test command - It will build, deploy, and test automatically
2. 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
3. Maximum 3 iterations - If still failing after 3 attempts, analyze if approach is fundamentally flawed
4. 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

Before reverting, save all artifacts to $OUTPUT_DIR/:

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

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:**
```diff
[The actual changes made]

Exhausted: Yes/No Reasoning: [Why you believe there are/aren't more viable approaches]

**Determining Exhaustion:** Set `exhausted=true` when you've tried the same fundamental approach multiple times, all hints have been explored, failure analysis reveals the problem is outside target files, or no new ideas remain. Set `exhausted=false` when this is the first attempt, failure analysis suggests a different approach, hints remain unexplored, or the approach was close but needs refinement.

### Step 10: Update State File (if provided)

If `state_file` input was provided and file exists:

1. **Read current Fix Candidates table** from state file
2. **Determine next attempt number** (count existing try-fix rows + 1)
3. **Append new row** with this attempt's results:

| # | Source | Approach | Test Result | Files Changed | Notes |
|---|--------|----------|-------------|---------------|-------|
| N | try-fix #N | [approach] | ✅ PASS / ❌ FAIL | [files] | [analysis] |

4. **Set exhausted status** based on your determination above
5. **Commit state file:**
```bash
git add "$STATE_FILE" && git commit -m "try-fix: attempt #N (exhausted=$EXHAUSTED)"

If no state file provided: Skip this step (results returned to invoker only).

Ownership rule: try-fix updates its own row AND the exhausted field. Never modify:

• Phase status fields
• "Selected Fix" field
• Other try-fix rows

Error Handling

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 for a complete example with sample inputs.