Add build-error-fixer agent and find-build-errors skill

[Copilot]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

New custom agent that discovers open issues labeled Known Build Error without associated PRs and delegates fixes to the pr agent.

New files

• .github/agents/build-error-fixer.md — 4-phase agent: Discovery → Branch Creation → Fix Delegation (to pr agent) → Status Report. Presents candidates one at a time for user confirmation before starting work.
• .github/skills/find-build-errors/SKILL.md — Skill docs for the discovery script.
• .github/skills/find-build-errors/scripts/query-build-errors.ps1 — Queries Known Build Error issues via gh, checks each for linked PRs via GraphQL, filters to unaddressed ones. Supports table/json/markdown/triage output formats.

Updated

• .github/copilot-instructions.md — Registers the new agent and skill in the existing catalog.

Usage

# Discovery only (skill)
pwsh .github/skills/find-build-errors/scripts/query-build-errors.ps1

# Include issues that already have PRs
pwsh .github/skills/find-build-errors/scripts/query-build-errors.ps1 -IncludeWithPRs

# Agent trigger phrases
# "fix known build errors"
# "work on build errors without PRs"

The script follows the same patterns as query-issues.ps1 and query-reviewable-prs.ps1 — GraphQL for PR linkage detection, gh CLI for issue queries, structured output for agent consumption.

Original prompt

Create a custom agent thats able to iterate over issues labelled with known build errors

When it finds an issue that doesnt have an associated pr it should create a branch to work on that issue, it should create that work as a separate task that will work fixong thay issue and monitorimg ci builds to fix it

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[rmarinho]

🤖 AI Summary

📊 Expand Full Review

---

🔍 Pre-Flight — Context & Validation

---

📝 Review Session — Add build-error-fixer agent and find-build-errors skill · 41d6c2f

---

PR: #33940 - Add build-error-fixer agent and find-build-errors skill
Author: Copilot (bot)
State: Draft
Linked Issue: None (feature addition, prompted by user request)
Platforms Affected: N/A — this PR only modifies .github/ agent/skill files (no platform code)
Files Changed: 4 files, all documentation/scripting (no C# source code)

Summary

This PR adds a new custom agent (build-error-fixer) and an associated skill (find-build-errors) to the MAUI repository's GitHub Copilot tooling. The agent:

1. Discovers open issues labeled Known Build Error that have no associated PR
2. Presents candidates to the user one-at-a-time for confirmation
3. Creates a branch and delegates fixes to the pr agent
4. Reports progress/status

Files Changed

File	Type	Status	Purpose
.github/agents/build-error-fixer.md	Agent definition	Added (+195 lines)	New 4-phase agent workflow
.github/skills/find-build-errors/SKILL.md	Skill documentation	Added (+78 lines)	Skill docs
.github/skills/find-build-errors/scripts/query-build-errors.ps1	PowerShell script	Added (+364 lines)	Discovery script using gh CLI and GraphQL
.github/copilot-instructions.md	Instructions	Modified (+14/-1 lines)	Registers new agent and skill in catalog

Key Design Decisions

• Uses GraphQL timeline events (CONNECTED_EVENT, CROSS_REFERENCED_EVENT) to detect linked PRs — same pattern as query-reviewable-prs.ps1
• Filters out issues with existing open PRs to avoid duplicating work
• Outputs in multiple formats: table, json, markdown, triage (for agent consumption)
• User confirmation required before starting work on each issue

PR Discussion

No comments or reviews yet. PR is in Draft state.

Disagreements / Edge Cases

None noted (no reviewer feedback).

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #33940	Add build-error-fixer agent + find-build-errors skill	⏳ PENDING (Gate)	.github/agents/build-error-fixer.md, .github/skills/find-build-errors/SKILL.md, .github/skills/find-build-errors/scripts/query-build-errors.ps1, .github/copilot-instructions.md	Feature addition PR — no UI/device tests exist

Gate Assessment

⚠️ This PR adds agent/skill documentation and scripting files only — there are no UI tests, device tests, or unit tests to verify. The Gate phase cannot run verify-tests-fail-without-fix because there is no IssueXXXXX test to execute. Gate will be skipped as an environment blocker.

---

🚦 Gate — Test Verification

---

📝 Review Session — Add build-error-fixer agent and find-build-errors skill · 41d6c2f

---

Result: ⏭️ SKIPPED — Not Applicable
Platform: ios (requested)
Mode: N/A

Reason for Skip

PR #33940 modifies only .github/ files:

• Agent definition markdown (.github/agents/build-error-fixer.md)
• Skill documentation markdown (.github/skills/find-build-errors/SKILL.md)
• PowerShell discovery script (.github/skills/find-build-errors/scripts/query-build-errors.ps1)
• Copilot instructions catalog update (.github/copilot-instructions.md)

There are no UI tests, device tests, or unit tests associated with this PR. No IssueXXXXX test files exist to run verify-tests-fail-without-fix against.

This is a tooling/documentation feature addition — not a bug fix with testable assertions on a platform. The Gate skill requires a test that fails without the fix and passes with it, which is not applicable here.

Conclusion

Gate is skipped as a documented environment blocker. The PR's content will be reviewed in the Fix and Report phases via code review.

---

🔧 Fix — Analysis & Comparison

---

📝 Review Session — Add build-error-fixer agent and find-build-errors skill · 41d6c2f

---

Fix Phase

Note: This PR is a pure tooling/documentation addition (no C# source code, no bug fix). The try-fix skill cannot be applied — there is no broken baseline to establish, no test to run, and no platform code to compare alternatives for.

Decision: Skip try-fix exploration. Proceeding to Report with code review findings.

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #33940	Add build-error-fixer agent + find-build-errors skill	⏭️ N/A (no tests)	4 .github/ files	Tooling addition — no testable fix

Exhausted: N/A (try-fix not applicable for documentation/tooling PRs)
Selected Fix: PR's approach — only candidate; code review findings documented in Report

Code Review Findings (from code-review agent)

Critical issue found:

• HasOpenPR filtering logic only checks for OPEN PRs, not MERGED — but the agent docs say "open or merged PR" should be filtered out. Issues with merged PRs would incorrectly be presented as candidates.

Medium issues:

• Duplicate 8. numbering in copilot-instructions.md skills catalog
• Summary message in markdown output says "without open PRs" rather than "without open or merged PRs"

Low issues:

• HasOpenPR field name is misleading; should be HasOpenOrMergedPR per the documented intent

---

📋 Report — Final Recommendation

---

📝 Review Session — Add build-error-fixer agent and find-build-errors skill · 41d6c2f

---

⚠️ Final Recommendation: REQUEST CHANGES

Summary

PR #33940 adds a new build-error-fixer agent and find-build-errors skill to the repository's Copilot tooling. The overall design is sound and follows established patterns (query-issues.ps1, query-reviewable-prs.ps1). However, a critical bug was found in the PR filtering logic that would cause issues with already-fixed errors (merged PRs) to be incorrectly presented as candidates for new work.

Root Cause of Issue

The agent documentation (.github/agents/build-error-fixer.md:73) states the script should filter issues without "an associated open or merged PR". However, the implementation in query-build-errors.ps1:193 only checks OPEN state:

# BUG: Only filters OPEN, not MERGED
if ($pr.state -eq "OPEN") {
    $hasOpenPR = $true
}

This means issues where a PR was merged (fix already landed) will be incorrectly re-presented as "ready for fixing", potentially leading to duplicate/conflicting work.

---

Title & Description Review

✅ Title: Good As-Is

Current: Add build-error-fixer agent and find-build-errors skill

This is a clear, accurate title for a tooling addition PR. No platform prefix needed (this isn't platform code).

✅ Description: Good Quality

The description has:

• ✅ Required NOTE block at top
• ✅ File-by-file breakdown with clear purpose for each
• ✅ Usage examples
• ✅ Pattern comparison with existing scripts

Minor addition recommended: The description could note the critical filtering behavior (open+merged) to set clear expectations, but this is optional.

---

Code Review Findings

🔴 Critical Issues

PR filtering logic only checks OPEN state, not MERGED

• File: .github/skills/find-build-errors/scripts/query-build-errors.ps1:193-195
• Problem: The agent documentation at build-error-fixer.md:73 says to filter issues "without an associated open or merged PR". The implementation only checks $pr.state -eq "OPEN", so issues with merged PRs (already fixed) will be re-presented as candidates.
• Recommendation:

  # Fix: also exclude merged PRs
  if ($pr.state -eq "OPEN" -or $pr.state -eq "MERGED") {
      $hasOpenPR = $true
  }

  Also update SKILL.md:60 and all summary messages to say "open or merged" for clarity.

🟡 Medium Issues

Duplicate skill number 8. in copilot-instructions.md

• File: .github/copilot-instructions.md:275,280
• Problem: Both pr-build-status and run-integration-tests are numbered 8.. The find-build-errors skill is numbered 9. but should be 10. (since run-integration-tests is really 9.).
• Recommendation: Renumber lines 280, 286 to 9. and 10. respectively.

Summary messages inconsistent with filtering intent

• File: .github/skills/find-build-errors/scripts/query-build-errors.ps1:292
• Problem: Summary footer says "issues without open PRs" but once the primary bug is fixed, it should say "issues without open or merged PRs".
• Recommendation: Update the message string after fixing the filtering logic.

🟡 Minor Issues

Misleading field name HasOpenPR

• File: .github/skills/find-build-errors/scripts/query-build-errors.ps1:214, SKILL.md:60
• Problem: The field name HasOpenPR implies it only tracks open PRs, but the intent is to track "any active or resolved PR". Consider renaming to HasLinkedPR or HasOpenOrMergedPR for clarity.
• Recommendation: After fixing the logic, rename the field to HasLinkedPR throughout the script and SKILL.md.

Phase 2 comment is misleading for CI monitoring

• File: .github/agents/build-error-fixer.md:94-97
• Problem: Phase 2 note says "Do NOT actually run git checkout -b or git push. The pr agent and report_progress tool handle branch management." But the report_progress tool is not a real tool in this context; this comment may confuse the executing agent.
• Recommendation: Simplify to "Branch creation is handled by the pr agent during Phase 3."

✅ Looks Good

• GraphQL query structure (timeline events: CONNECTED_EVENT, CROSS_REFERENCED_EVENT) matches existing query-issues.ps1 pattern
• Error handling for missing gh CLI and unauthenticated state is properly implemented
• Multiple output formats (table, json, markdown, triage) provide good flexibility for different consumers
• Sorting by age (oldest first) is the right default for prioritizing long-standing build errors
• The $ErrorActionPreference = "Stop" pattern is correct for PowerShell scripts
• Progress indicator during processing (\r Processing issue N of M) follows the same pattern as other discovery scripts
• The 4-phase workflow in build-error-fixer.md is coherent and consistent with the pr agent

---

Required Changes Before Merge

1. Fix PR filtering: Change line 193 of query-build-errors.ps1 to include MERGED state
2. Fix catalog numbering: Fix duplicate 8. in copilot-instructions.md
3. Update summary messages: Update "without open PRs" to "without open or merged PRs"
4. (Optional) Rename HasOpenPR: For clarity, rename to HasLinkedPR or HasOpenOrMergedPR

---

Phase Status

Phase	Status
Pre-Flight	✅ COMPLETE
Gate	⏭️ SKIPPED (no tests — tooling/documentation PR)
Fix	⏭️ SKIPPED (no C# code — try-fix not applicable)
Report	✅ COMPLETE

---

📋 Expand PR Finalization Review

---

Title: ✅ Good

Current: Add build-error-fixer agent and find-build-errors skill

Description: ✅ Good

Description needs updates. See details below.

Code Review: ✅ Passed

Code Review — PR #33940

PR: Add build-error-fixer agent and find-build-errors skill
Files reviewed: 4 changed files

---

Code Review Findings

🟡 Suggestions

1. Phase 2 Branch Creation instruction is misleading

File: .github/agents/build-error-fixer.md (lines ~95-103)

Problem: Phase 2 is titled "Branch Creation" but the instructions explicitly say do NOT create a branch (the pr agent handles it). This creates a conceptual mismatch — the workflow diagram calls it "Branch Creation" but the actual instruction is to do nothing except create a log directory.

Current text:

## Phase 2: Branch Creation

> **SCOPE**: Create a working branch for the confirmed issue.

**🚨 IMPORTANT**: Do NOT actually run `git checkout -b` or `git push`. The pr agent and report_progress tool handle branch management. Simply note the issue number for delegation.

Recommendation: Rename the phase to "Issue Preparation" or "Pre-Delegation Setup" in both the workflow overview diagram and the section header to avoid confusing future agents that read this file. Alternatively, clarify in the diagram that branch creation is delegated to the pr agent.

---

2. Sort order logic is inverted for SortBy=created

File: .github/skills/find-build-errors/scripts/query-build-errors.ps1 (lines ~213-219)

Problem: The sort logic maps asc (which should mean "oldest first" per the parameter docs) to Sort-Object AgeDays -Descending. Since AgeDays is the number of days since creation, a higher AgeDays value means an older issue. So Sort-Object AgeDays -Descending correctly returns the oldest first when SortOrder = "asc". However, the parameter documentation says the default asc means "oldest first" — which is correct — but the code uses -Descending for asc, which is counter-intuitive and may confuse future maintainers.

Current code:

"created" {
    if ($SortOrder -eq "asc") { $processedIssues | Sort-Object AgeDays -Descending }
    else { $processedIssues | Sort-Object AgeDays }
}

This is technically correct (oldest first = largest AgeDays = descending by AgeDays), but it's confusing. Consider adding a comment explaining why -Descending is used for asc:

"created" {
    # AgeDays is days-since-creation, so older issues have higher AgeDays
    # "asc" (oldest first) = sort by AgeDays descending
    if ($SortOrder -eq "asc") { $processedIssues | Sort-Object AgeDays -Descending }
    else { $processedIssues | Sort-Object AgeDays }
}

---

✅ Looks Good

• GraphQL PR linkage detection — The approach using CONNECTED_EVENT and CROSS_REFERENCED_EVENT timeline items mirrors the pattern used in other skills (query-reviewable-prs.ps1), which is the established pattern for this repo. ✅

• Error handling in GraphQL block — The try/catch with silent continue for the GraphQL call is appropriate; the script still returns the issue without PR data rather than failing entirely. ✅

• Prerequisites check — Validates gh CLI presence and authentication before proceeding. Good defensive pattern. ✅

• Agent workflow isolation — The agent correctly delegates to the pr agent rather than attempting fixes directly. The "one issue at a time" constraint prevents unbounded parallel work. ✅

• Output format variety — table, json, markdown, triage formats cover all consumer needs (human, CI, agent). Consistent with query-issues.ps1 pattern. ✅

• IncludeWithPRs filter — The distinction between open PRs only (vs. merged/closed PRs) for the hasOpenPR flag is correct — merged PRs should not prevent a new fix attempt if the issue is still open. ✅

• copilot-instructions.md update — Both the agent entry and the skill entry are correctly numbered and placed in the catalog. The delegation example at the bottom is also updated. ✅

---

[kubaflo]

@rmarinho do we still need this PR?

[kubaflo]

/review -b feature/refactor-copilot-yml

[kubaflo]

/review -b feature/enhanced-reviewer -p android

[MauiBot]

⚠️ Merge Conflict Detected — This PR has merge conflicts with its target branch. Please rebase onto the target branch and resolve the conflicts.