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.

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.