mcs-lab-fix-pr-filer

mcs-lab-fix-pr-filer (sub-skill)

Apply the audit's suggested corrections to the actual lab files in the active instance's repo ({repo}), then either open a new fix-PR on a run-unique branch or append to the lab's existing open fix-PR — whichever the dedup check resolves — and close (or reference) the audit issue.

PR dedup is scoped to OPEN PRs only. A merged or closed prior PR for the same lab never blocks a new one — each audit run that finds new problems gets its own PR. The only thing that suppresses a new PR is an already-open fix-PR for the same slug, in which case this run's fixes are appended to that PR instead of opening a duplicate. See [[feedback_fresh_branch_per_pr]].

Inputs (assumed present from the orchestrator)

• runs/<run-id>/labs/<slug>/findings.json — same file the issue-filer read.
• runs/<run-id>/labs/<slug>/screenshots/proposed/ — proposed replacement images keyed to findings[*].proposed_screenshot_replacement_for paths.
• <plugin>/config/judge-config.yml — branch conventions:
  • issues.pr_append.pr_branch_pattern (default {branch_prefix}/fix-{slug}-content-audit-{run_id}) — the run-unique branch name to CREATE when no open PR exists.
  • issues.pr_append.pr_match_head_prefix (default {branch_prefix}/fix-{slug}-content-audit) — the head-ref prefix used to find an existing open PR for the slug regardless of its run-id suffix.
• runs/<run-id>/existing-state.yml — the orchestrator's Phase 1.4 probe. labs[<slug>].open_pr is non-null when an open fix-PR already exists for the slug.
• the resolved clone of {repo} (from Resolve-LabRepo.ps1 -Instance).
• issue_number — returned by mcs-lab-issue-filer. Required.
• lab_slug, run_id — passed through.

Outputs

• Either a new run-unique branch {branch_prefix}/fix-<slug>-content-audit-<run-id> on the active instance's repo ({repo}), OR a new commit on the existing open PR's branch — never both.
• New or updated PR titled <slug>: fix audit findings from #<issue-number> with body containing Closes #<issue-number>.
• runs/<run-id>/labs/<slug>/pr-url.txt — convenience file for the orchestrator's summary.
• Updated manifest.yml.labs[<slug>]: status: issue_and_pr_filed, pr_url, pr_action: created | appended | skipped_no_changes.

Procedure

1. Prepare the working tree

cd C:\Users\dewainr\mcs-labs
git fetch origin main

If there are uncommitted changes in the working tree, stash them with a clear label and restore the user's prior HEAD. (Never clobber unrelated in-flight work.)

2. Resolve the PR target — append to an open PR, else open a new one

Dedup is scoped to OPEN PRs only. First find whether an open fix-PR already exists for this slug; if so, append to it; otherwise open a brand-new PR on a run-unique branch. A merged or closed prior PR is irrelevant — it never blocks a new PR.

2a. Find an existing open PR for the slug.

• If the orchestrator's probe wrote runs/<run-id>/existing-state.yml.labs[<slug>].open_pr (non-null), use it directly — it already carries number, branch (the actual head ref, run-id suffix and all), author, and mergeable.
• Otherwise, query directly by head prefix (matches any run's branch for this slug), most-recently-updated first:

  prefix="{branch_prefix}/fix-<slug>-content-audit"   # judge-config.yml.issues.pr_append.pr_match_head_prefix
  gh pr list --repo {repo} --state open --author "@me" \
    --json number,headRefName,author,mergeable,url,updatedAt \
    --search "head:$prefix" | jq 'sort_by(.updatedAt) | reverse | .[0] // empty'
  

  If the head query returns nothing, fall back to a title match: --search "\"<slug>: fix audit findings\" in:title". Only OPEN PRs count.

2b. If an open PR was found → append.

• Verify it's authored by the current gh user (pr_append.require_same_author) and mergeable (pr_append.require_mergeable).
• If guardrails pass: git fetch origin, then gh pr checkout <number> --repo {repo} (checks out the PR's actual branch whatever its name). Confirm with git rev-parse --abbrev-ref HEAD. Set pr_action: appended and remember <branch> = that head ref.
• If guardrails fail (different author, or CONFLICTING): abort the PR step (the orchestrator records this as a soft failure: issue was filed but the open PR could not be appended; the user is told to inspect the PR). Do NOT open a competing second PR for the same lab.

2c. If no open PR exists → open a new one on a run-unique branch.

• Render the create pattern: branch = {branch_prefix}/fix-<slug>-content-audit-<run-id> (from judge-config.yml.issues.pr_append.pr_branch_pattern, substituting {branch_prefix}, {slug}, and {run_id}). The {run_id} suffix guarantees the name can't collide with a leftover branch from a merged/closed prior PR — so there is no need to rename or delete any stale branch.
• git fetch origin main, then git checkout -b <branch> origin/main. Set pr_action: created.

3. Apply markdown corrections

For each finding in findings.json where outcome ∈ {broken, unclear} AND suggested_correction is non-null:

1. Read the lab file _labs/<slug>.md.
2. Apply a literal string replacement:
   • old_string = suggested_correction.original_text
   • new_string = suggested_correction.proposed_text
3. If the old_string is no longer present (the lab has changed since the audit), record {finding_id, applied: false, reason: original_text_not_found} in runs/<run-id>/labs/<slug>/pr-apply-log.json and continue with the next finding.
4. If the replacement would match in multiple places, prefer the location with the line number closest to finding.evidence.line_number if recorded; otherwise apply once at the first match and warn.

Some corrections span multiple lines or require reordering content (new UC, scene swap, etc.). Findings whose suggested_correction.scope == "scene" should NOT be auto-applied — leave them for human review and record {finding_id, applied: false, reason: scope_scene_requires_manual}.

4. Apply screenshot replacements / additions

For each finding with non-null proposed_screenshot_replacement:

1. Resolve source path: runs/<run-id>/labs/<slug>/screenshots/proposed/<proposed_screenshot_replacement> (the audit subagents save replacements here).
2. Resolve destination:
   • If proposed_screenshot_replacement_for is non-null (replacing an existing image): destination is labs/<slug>/<proposed_screenshot_replacement_for> (e.g. labs/<slug>/images/foo.png).
   • If null (adding a new image): destination is labs/<slug>/images/<proposed_screenshot_replacement> and ensure the lab markdown is updated to reference it (the markdown reference should be in the same finding's suggested_correction.proposed_text if the parser caught it).
3. cp <source> <destination>.

Track screenshots_replaced count for the commit message.

4a. Detect missing screenshot replacements for UI-drift findings

Before moving on to step 5, scan applied findings for the case where the audit caught UI drift (a renamed control, moved button, re-organized dialog, changed label) but the finding does NOT have a proposed_screenshot_replacement populated. This is exactly the case where the lab's screenshot will be stale even after the markdown fix lands — the body text says the new label, the picture still shows the old one. See mcs-lab-auditor/references/playwright-cookbook.md → "Screenshot freshness" for the standing rule.

For each such finding, before committing:

1. Identify any image-ref in the same scene as the relabeled instruction line. Most labs put ![...](images/foo.png) one or two paragraphs after the instruction it depicts. Look for image references within the _labs/<slug>.md section being edited.
2. If an image-ref exists within the affected scene and the file at labs/<slug>/images/<file>.png shows the old UI state (i.e. the same surface the audit just observed has been relabeled), the screenshot is stale.
3. The audit driver should already have captured a fresh screenshot for this surface during the run — look for it in runs/<run-id>/labs/<slug>/screenshots/. If found, copy it over labs/<slug>/images/<file>.png.
4. If no fresh screenshot was captured (the driver missed the image-ref → instruction mapping during the run), open a separate audit-loop iteration to capture one before proceeding. Do not skip — record {finding_id, screenshot_refresh: pending_capture, image_path} in pr-apply-log.json and request the screenshot from the orchestrator before commit.
5. If the maintainer's fix PR explicitly defers the image refresh (e.g. an explicit "deferred to follow-up" annotation in the finding), record the deferral in the PR body's Test plan under an unchecked checkbox: - [ ] Refresh \images/.png` to show the current UI`. Never silently ship the markdown-only fix.

Track screenshots_implied_stale and screenshots_refreshed_from_audit_run counts for the commit message and PR body. If screenshots_implied_stale > screenshots_refreshed_from_audit_run + screenshots_deferred, the gap is a process failure — log it loudly so the orchestrator can flag it on the next run.

5. Sanity check

git diff --stat

If the working tree has NO changes after steps 3 and 4 (every correction failed to apply, every screenshot was already current), set pr_action: skipped_no_changes and abort the PR step. Record the reason in pr-apply-log.json.

6. Commit

git add _labs/<slug>.md labs/<slug>/images/
git commit -m "$(cat <<EOF
<slug>: fix audit findings from #<issue-number>

Auto-applied by mcs-lab-fix-pr-filer from audit run <run-id>.

Markdown corrections: <N applied> of <N total> findings.
Screenshot updates: <N replaced> + <N added>.

See issue #<issue-number> for full audit details and per-finding evidence.

Closes #<issue-number>
EOF
)"

Commit author: use the current gh auth status user (e.g. [email protected] / Dewain Robinson) via git -c user.email=... -c user.name=.... Never sign with a Claude / bot identity unless explicitly configured.

7. Push

git push -u origin <branch>

If push fails because the remote branch already exists and is ahead (concurrent run), git pull --rebase origin <branch> then re-push.

8. Open or update the PR

If pr_action: created:

gh pr create \
  --repo {repo} \
  --base main \
  --head <branch> \
  --title "<slug>: fix audit findings from #<issue-number>" \
  --body-file <pr-body.md>

PR body template (runs/<run-id>/labs/<slug>/pr-body.md):

Closes #<issue-number>.

Implements the corrections from the mcs-lab-auditor run on `<slug>` (run id `<run-id>`).

## What changed

<for each applied finding: a 1-2 line bullet describing the fix>

## How it was verified

Every change was driven by the audit run's Playwright execution on a fresh workshop-issued tenant account. Per-finding evidence (screenshots, accessibility snapshots, console + network logs) is stored locally under `~/.claude/plugins/mcs-lab-auditor/runtime/runs/<run-id>/labs/<slug>/`.

<if any findings were NOT auto-applied:>
## Findings deferred to human review

<for each unapplied finding: a bullet with the reason from pr-apply-log.json>

If pr_action: appended:

• Just push (already done in step 7). Then gh pr comment <pr-number> --body "Appended fixes from audit run <run-id>: <N> markdown corrections, <N> screenshot updates.".

Capture the resulting PR URL.

9. Record the outcome

Update runs/<run-id>/manifest.yml:

labs:
  <slug>:
    status: issue_and_pr_filed
    issue_url: <from issue-filer>
    issue_action: created | commented
    pr_url: <captured above>
    pr_action: created | appended | skipped_no_changes
    finished_at: <iso-timestamp>

Append to runtime/audit-history.yml:

- run_id: <run-id>
  lab_slug: <slug>
  status: issue_and_pr_filed
  issue_url: <...>
  pr_url: <...>
  findings_applied: <N>
  findings_deferred: <N>

Write runs/<run-id>/labs/<slug>/pr-url.txt containing just the PR URL for the orchestrator's end-of-run summary.

Important rules

• Never force-push. pr_append.allow_force_push is false and remains so.
• Dedup is OPEN-PR-scoped. Only an open fix-PR for the slug suppresses a new PR. Merged/closed PRs never block a new one — that's the whole point of the run-unique branch name. See [[feedback_fresh_branch_per_pr]].
• One open PR per lab. If an open fix-PR already exists, append to it; never open a second open PR for the same lab in the same breath.
• Never modify a closed/merged PR's branch. Always check open-PR state before pushing. See [[feedback_no_push_to_merged_pr]].
• Respect same-author guardrail. If the current gh user does not match the PR author on an existing open PR, abort the append step and leave the issue-filer's record as the only output for this lab.
• Restore the user's working tree. If you stashed changes at the start, git stash pop (or leave the stash with a clear label and tell the user how to recover) — never silently lose work.
• Defer scene-scope corrections. Anything bigger than a phrase- or step-scope replacement should land in the PR body's "Findings deferred to human review" section, not in the commit. Large rewrites (e.g., adding a whole new use case) should be handled by the orchestrator at audit time, not auto-applied here.

What to do when stuck

• original_text not found in markdown: lab has drifted since the audit. Record in pr-apply-log.json and continue.
• proposed_screenshot_replacement source missing: subagent didn't save the file. Skip the image update and record in pr-apply-log. The PR still ships the markdown corrections; the screenshot finding remains in the issue for human attention.
• Branch is up-to-date with main and no changes apply: still no-op — set pr_action: skipped_no_changes and don't push an empty commit.
• An open PR exists but the author/mergeable guardrail fails: abort the PR step with the reason recorded; do NOT open a competing second PR. The issue-filer's record stands and the user is told to inspect the open PR.
• gh pr create fails: leave the branch pushed (the commits are valuable), record the error in pr-apply-log.json, and tell the user the manual PR-create command they can run.