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

Content truncated.