# Powertoys Dashboard Update

> Reliable resumable PowerToys triage-dashboard updater. Exhaustively inventories freshness, processes bounded normal updates or uncapped drain-mode work, checkpoints completed work, and republishes periodically so finished work survives crashes. Does not post upstream reviews/comments or open upstream PRs without explicit approval.

- Skill: `gabrielmoreira/powertoys-dashboard-update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/powertoys-dashboard-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/powertoys-dashboard-update/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/powertoys-dashboard-update

---


# PowerToys Dashboard Update

Use this skill for the scheduled or manual daily refresh of the public
PowerToys triage board:

- "update my PowerToys dashboard"
- "run the daily dashboard update"
- "refresh the PowerToys triage queue"
- "check old work and find new issues/PRs"

The skill is an **orchestrator**, not a replacement for the three execution
skills:

- `powertoys-pr-review` — review a community PR in the fork until the Copilot
  review loop is clean, then draft proposed upstream review actions.
- `powertoys-issue-to-design` — triage a bug, investigate it, run the
  investigator/adversary loop, and stop at the design gate.
- `powertoys-design-to-pr` — turn an approved fork design into a reviewed,
  build-verified fork PR and stop before opening upstream.

## Safety rules

1. Read upstream freely, but never post an upstream review/comment, open an
   upstream PR, close/label/assign upstream, or create a cross-reference
   without explicit user approval.
2. Fork-side mirrors, branches, Copilot review loops, and local builds are
   allowed. Preserve each sub-skill's approval gates.
3. Never duplicate existing fork work. Resume the existing mirror issue or
   fork PR after checking its current state.
4. Do not publish PATs, tokens, local paths, or private notes to the artifact
   repository.
5. Every run must regenerate and publish `data/index.json`, `data/index.js`, and
   `data/items/<number>.json` before heavy agent work and after each completed
   batch. A non-empty stale queue is valid when deferred items remain explicit.
6. PowerToys Pulse is the user-facing dashboard. After publishing artifacts,
   synchronize and validate Pulse, then deploy only an approved Pulse branch or
   workflow. Do not substitute the artifact repository's Pages site as the
   final preview.
7. The only canonical skill and action-data repository is
   `MuyuanMS/powertoys-pulse-actions`. Before reading or writing checkpoints,
   generating data, or publishing, run
   `scripts/Assert-CanonicalDashboardTarget.ps1`. Never update or push
   `MuyuanMS/powertoys-triage-board`; it is a retired standalone prototype.
8. Dashboard publication and fork review writes are separate permissions.
   Workers must not emit, sanitize, commit, or push the dashboard repository,
   but they are allowed and expected to push `pr-iterate/<number>` branches,
   update fork review PRs, and resolve comments in the configured writable
   PowerToys fork. Never give a worker an unqualified "do not push" instruction.
9. Report checkpoint progress separately from concluded reviews. "Updated" or
   "processed" means only that durable state advanced. A PR is "concluded" only
   when it has a current allowed review action, is justified as waiting on the
   author, or has a published unrecoverable blocker that names the exact manual
   remediation. Do not tell the user that reviews are finished merely because
   every selected artifact was rewritten.

## Configuration

```powershell
$Upstream = 'microsoft/PowerToys'
$Dashboard = if ($env:POWERTOYS_DASHBOARD_PATH) {
  (Resolve-Path $env:POWERTOYS_DASHBOARD_PATH).Path
} else {
  (git rev-parse --show-toplevel).Trim()
}
$SkillRoot = Join-Path $Dashboard '.github\skills\powertoys-dashboard-update'
$ForkOwner = if ($env:POWERTOYS_FORK_OWNER) {
  $env:POWERTOYS_FORK_OWNER
} else {
  (gh api user --jq '.login').Trim()
}
$Fork = if ($env:POWERTOYS_FORK_REPO) {
  $env:POWERTOYS_FORK_REPO
} else {
  "$ForkOwner/PowerToys"
}
$Board = 'MuyuanMS/powertoys-pulse-actions'
$Since = (Get-Date).AddDays(-2).ToUniversalTime().ToString('o')
$IssueWindowDays = 30
$DrainReviewQueue = $env:POWERTOYS_DASHBOARD_DRAIN_QUEUE -eq '1'
$DesignBatchSize = if ($env:POWERTOYS_DESIGN_BATCH_SIZE) { [int]$env:POWERTOYS_DESIGN_BATCH_SIZE } elseif ($DrainReviewQueue) { [int]::MaxValue } else { 4 }
$PrReviewBatchSize = if ($env:POWERTOYS_PR_REVIEW_BATCH_SIZE) { [int]$env:POWERTOYS_PR_REVIEW_BATCH_SIZE } elseif ($DrainReviewQueue) { [int]::MaxValue } else { 16 }
$PrReviewConcurrency = if ($env:POWERTOYS_PR_REVIEW_CONCURRENCY) { [int]$env:POWERTOYS_PR_REVIEW_CONCURRENCY } elseif ($DrainReviewQueue) { 6 } else { 3 }
$RunBudgetMinutes = if ($env:POWERTOYS_DASHBOARD_RUN_BUDGET_MINUTES) { [int]$env:POWERTOYS_DASHBOARD_RUN_BUDGET_MINUTES } elseif ($DrainReviewQueue) { 0 } else { 50 }
$RunStartedAt = (Get-Date).ToUniversalTime().ToString('o')
$ProjectOwner = if ($env:POWERTOYS_PROJECT_OWNER) { $env:POWERTOYS_PROJECT_OWNER } else { 'microsoft' }
$ProjectNumber = if ($env:POWERTOYS_PROJECT_NUMBER) { [int]$env:POWERTOYS_PROJECT_NUMBER } else { 2445 }
$BoardOwner, $BoardName = $Board -split '/', 2
$ArtifactBaseUrl = if ($env:POWERTOYS_ARTIFACT_BASE_URL) {
  $env:POWERTOYS_ARTIFACT_BASE_URL.TrimEnd('/')
} else {
  "https://raw.githubusercontent.com/$BoardOwner/$BoardName/main/data"
}
$Pulse = if ($env:POWERTOYS_PULSE_REPO) { $env:POWERTOYS_PULSE_REPO } else { 'gim-home/powertoys-pulse' }
$PulsePreview = if ($env:POWERTOYS_PULSE_PREVIEW_REPO) { $env:POWERTOYS_PULSE_PREVIEW_REPO } else { 'MuyuanMS/powertoys-pulse-action-private' }
$NotifyOutlook = if ($env:POWERTOYS_DASHBOARD_NOTIFY) { $env:POWERTOYS_DASHBOARD_NOTIFY -ne 'none' } else { $true }
```

On the first run, verify:

```powershell
gh auth status
gh repo view $Fork
pwsh -NoProfile -File `
  "$SkillRoot\scripts\Assert-CanonicalDashboardTarget.ps1" `
  -Dashboard $Dashboard
```

Run this skill from the `MuyuanMS/powertoys-pulse-actions` repository root, or
set `POWERTOYS_DASHBOARD_PATH` to a checkout of that exact repository. The
other three skills must be present beside it under `.github\skills`. The target
repository is intentionally not overrideable.

The configured repository is both the reusable skill suite and canonical
artifact feed. Generated files belong only in its root `data/` directory, not
inside `.github\skills`. Never place secrets or information that must remain
private in the public feed.

### Dashboard action taxonomy

Pulse action proposals are maintainer-facing actions only. Status, freshness,
queue state, validation gaps, and "wait/do nothing" choices remain metadata and
must not appear as clickable action proposals.

Update this table when a new action type is intentionally introduced, then
update `emit.ps1`, `Sanitize-ActionData.ps1`, Pulse's triage action filter, and
the dashboard artifact validators in the same change.

| Item | Allowed action type | Dashboard meaning | Must contain | Not allowed as an action |
| --- | --- | --- | --- | --- |
| PR | `approve` | Submit/choose approval for a review-clean PR. | Current `head_sha`, covered `source_updated_at`, no unresolved agent findings. | Native validation still pending, queued review, re-run prompt. |
| PR | `post_review` | Post selected code suggestions or non-blocking review comments. | Proposed comments pinned to the current head; inline comments use current RIGHT-side ranges when possible. Event must be `COMMENT`; inline-only reviews omit the overall review body. | `REQUEST_CHANGES`, a generic overall message for inline-only suggestions, general "keep checking", "complete validation", or product-direction reminders without a publishable review body. |
| PR | `request_changes` | Post selected blocking review comments as a request-changes review. | Same evidence and current-head requirements as `post_review`. | A standalone request to run the review loop again. |
| PR | `trigger_ci` | Post `/azp run` to request an Azure Pipelines run when live checks are failed, cancelled, timed out, stale, or missing. | Exact comment body `/azp run`; current live head/check state displayed to the maintainer; explicit confirmation before posting. | Posting while all checks pass, treating CI as a substitute for review/build evidence, or auto-posting without a maintainer click. |
| PR | `merge_pr` | Squash-merge an approved PR after review and CI are complete. | Current live head, at least one current approval, passing checks, clean GitHub merge state, and explicit confirmation immediately before merging. | Automatic merging, merging a draft, merging stale data, or merging without revalidating approval, CI, and mergeability. |
| Issue | `request_info` | Ask the reporter for specific missing evidence. | An issue-specific upstream comment that summarizes the relevant facts already supplied, explains why they are insufficient, asks for exact missing evidence, and gives the established collection method when one exists (for example, `/bugreport` for a fresh PowerToys diagnostic ZIP). | "Not now", wait, monitor, a generic checklist, or "send logs/more information" without explaining the gap. |
| Issue | `approve_design` | Approve/start a fork-side fix plan after design convergence. Pulse also derives a local-agent implementation prompt from the same public artifact. | Detailed design artifact and fork issue/trace for the fix workflow. | A speculative or incomplete design. |
| Issue | `post_comment` | Post a close, duplicate, handled, out-of-scope, or maintainer-direction comment. | Specific rationale and linked duplicate/fix/ownership evidence when applicable. | Silent close, vague "won't fix", or no-op status comments. |
| Issue | `open_upstream_pr` | Open the completed fork fix upstream. | Fork PR/head, implementation evidence, and approval gate. | Opening without explicit approval or without a reviewed fork fix. |

Forbidden action types in public artifacts include `hold`, `rerun`,
`continue_review`, `review_summary`, `monitor`, `start_review`, and
`start_triage`. These may be retained as internal workflow/status metadata, but
Pulse must not render them as executable action proposals.

### Reliability contract

Normal runs are bounded and resumable. They must finish within the 50-minute
default run budget instead of trying to drain an arbitrarily large review queue:

- inventory every eligible PR and changed bug, but select at most
  `$PrReviewBatchSize` PRs and `$DesignBatchSize` full designs for execution;
- run at most `$PrReviewConcurrency` PR workers at once;
- select up to sixteen PRs by default so workers that checkpoint an external
  Copilot wait release their slots to additional queued PRs while still capping
  active heavy local work;
- treat cloud-review waiting as a persisted queue stage, not an active worker:
  request the review, checkpoint `waiting_copilot`, return the worker slot, and
  inspect the result on the next scheduler pass;
- never let a PR worker launch another subagent; the worker performs its review
  directly and may use external GitHub Copilot review as required;
- give each worker the exact UTC deadline from the run plan and require it to
  stop cleanly with durable `review_in_progress` state before that deadline;
- publish the refreshed inventory before launching workers, then publish each
  completed artifact without waiting for the full queue;
- checkpoint every durable transition locally and publish after two transitions,
  after eight minutes, or at run completion, whichever comes first;
- leave unselected or unfinished items explicitly queued for the next run;
- count and report `checkpointed`, `concluded`, and `still_in_progress`
  separately; a successful worker batch is not equivalent to concluded review
  coverage;
- ensure every open, non-draft PR that is not waiting on the author is either
  backed by an allowed PR action from the taxonomy above, explicitly marked as
  pending author feedback, or shown as queued/internal status without a
  clickable Pulse action.

`POWERTOYS_DASHBOARD_DRAIN_QUEUE=1` is an exceptional operator-requested mode.
Drain mode intentionally removes the PR selection limit, issue design cap, and
run deadline. It selects every stale PR, runs up to six PR workers at once by
default, processes all actionable issue designs, and continues until the stale
queue is empty or an unrecoverable blocker is published. Drain mode still must
checkpoint every durable fork/mirror/review transition immediately and publish
after two transitions, after five minutes, or after any completed artifact,
whichever comes first, so completed work and resumable fork traces survive a
frozen or crashed session. Do not use drain mode in scheduled or ordinary manual
runs unless the operator explicitly requested it.

### Scheduled-run status notifications

Scheduled runs are hard to observe from the CLI, so send compact status
notifications through Outlook when M365/WorkIQ tools are available.
`POWERTOYS_DASHBOARD_NOTIFY=none` disables these emails; all other values send
Outlook mail to the signed-in user.

Read `/me?$select=mail,userPrincipalName` and send to
`mail ?? userPrincipalName` via `/me/sendMail`. The first message is the run's
status thread. After sending it, look it up in Sent Items by subject and
timestamp so later updates can reply to the original message with
`/me/messages/{message-id}/reply`. If the original message id cannot be found,
send a new message with the same subject prefixed by `Re:`. If M365 tools are
unavailable or delivery fails, record that in the final report and continue the
dashboard run.

Keep messages brief and clear. Send:

1. **Started** — after the live queue and bounded run plan are enumerated.
   Include selected PRs, deferred PR count, changed/new bug issues, selected
   full-design issues, the concurrency cap, and the UTC deadline. In drain
   mode, state that the deadline, PR selection limit, and issue design cap are
   disabled, and include the higher worker count.
2. **30-minute checkpoint** — if the run is still active 30 minutes after the
   started email, reply to the original with completed PRs/issues, currently
   running PRs/issues, remaining queue count, and next expected milestone.
3. **Completed** — reply to the original after validation and deployment
   verification, with commit, PR/issue coverage, stale queue count, artifact
   count, and whether any upstream public action occurred.
4. **Blocked/failed** — reply to the original before stopping on an
   unrecoverable failure, with the failing phase and the next manual action
   needed.

For incremental publishes before the 30-minute checkpoint, do not send noisy
extra mail unless it materially changes the user's action needed; roll those
details into the checkpoint or completed reply.

Keep notification bodies public-safe: no PATs, local checkout paths, fork-only
implementation provenance, private evidence, or internal worktree details.
These notifications are status messages only and do not authorize posting
reviews/comments to `microsoft/PowerToys`.

## Phase 0 — Sync and load prior state

1. Check the fork's divergence and sync `main` with upstream when behind:

```powershell
gh api "repos/$Upstream/compare/main...${ForkOwner}:main" `
  --jq '{behind_by,ahead_by,status}'
gh api --method POST "repos/$Fork/merge-upstream" `
  --input (@{branch='main'} | ConvertTo-Json)
```

2. Read the latest board index and all existing artifacts. Treat these fields
   as the durable freshness contract:

   - `generated_at` — when the artifact file was emitted;
   - `evaluated_at` — when an agent last made a substantive judgment;
   - `source_updated_at` — upstream `updatedAt` covered by that judgment;
   - `head_sha` — exact upstream PR head covered by the latest code review;
   - `judgment.status` — the latest lightweight issue classification.

   Do not use `generated_at` alone as evidence that an item was reviewed. An
   unchanged artifact copied by the emitter keeps its old `evaluated_at`,
   `source_updated_at`, and `head_sha`.
3. Inventory fork traces:

```powershell
gh pr list -R $Fork --state all --json number,title,state,headRefName,updatedAt,url --limit 200
gh issue list -R $Fork --state all --json number,title,state,updatedAt,url --limit 200
```

Map `[PR N]`, `[Issue N]`, `(Issue N)`, `pr-iterate/N`, and
`copilot/issue-N-...` back to upstream numbers.
For PR reviews, also run `Get-ReviewResumeState.ps1` and preserve durable
branches, review PRs, worktrees, round counts, and unresolved-thread state.

4. Synchronize the PowerToys project board with
   `$SkillRoot\scripts\Sync-PowerToysProject.ps1`. The script is safe to run with
   `-DryRun` while project permissions are being configured. It adds open,
   non-draft PRs that are not already in project 2445 and updates
   existing items:

   - agent-produced review artifacts with suggested comments → `To manually review`;
   - a recognized member's upstream review/comment → `In Review` or the named
     option (`In Review: MuyuanMS`, `In Review: LegendaryBlair`, or
     `In Review: moooyu`) when that option exists;
   - closed or merged items → `Done`.

   Items with no recognized decision remain in their current project status,
   normally `To triage`. Project synchronization never posts upstream content.

## Phase 1 — Build the complete freshness queue

Every run must enumerate **all** open upstream items before selecting work.
Do not limit PR discovery to `$Since`; `$Since` is only an optimization for
activity queries. Join the live list to artifacts and fork traces by upstream
number.

### PR freshness

Every open, non-draft PR must end the run in exactly one state:

- **current clean review** — artifact `head_sha` exactly matches the live head,
  the latest freshly requested Copilot pass has zero new comments and zero
  unresolved threads, required builds/context checks passed, and
  `source_updated_at` covers the latest relevant PR activity;
- **queued/running review** — no current clean result exists;
- **waiting on author** — a posted/requested change is still outstanding and
  the author has not pushed or replied;
- **excluded** — draft or closed.

A **full re-review is mandatory** when the live head SHA differs from
`head_sha`, `head_sha` is missing, or there is no clean artifact. If the head is
unchanged but comments/reviews changed after `source_updated_at`, perform a
focused context revalidation. Rerun the full review only when that activity
changes requirements, reveals a concern, resolves author-waiting state, or
invalidates the prior decision. Otherwise advance `evaluated_at` and
`source_updated_at` without pretending a new code review occurred.

Do not classify a PR as waiting on author from "who commented last" or from a
generic maintainer comment alone. Preserve `pending_author` only when current
live evidence supports it: a needs-author-feedback label, a current
changes-requested review after the author's latest activity, or posted Pulse
review comments that have not been followed by an author commit/comment/review.
For a specific upstream maintainer request that is not represented by one of
those signals, record `author_wait_evidence` with the comment author, URL,
`created_at`, and the exact requested evidence. A draft `post_review` or
`request_changes` action is still owed by the maintainer and must never be
treated as though it were already posted.
If the author has pushed or replied after the author-wait signal, clear
`pending_author`, mark the artifact `needs_revalidation`, and put the PR back
in the review queue so the update agent makes a fresh decision.

Never skip an eligible PR merely because it is old or absent from the recent
activity query. Never re-review an unchanged, converged head with no newer
relevant activity.

### Mandatory stale-review queue gate

Before publishing, run the stale-review queue check:

```powershell
pwsh -NoProfile -File `
  "$SkillRoot\scripts\Get-StalePrReviewQueue.ps1" `
  -Dashboard $Dashboard -Upstream $Upstream -AsJson
```

The queue contains every open, non-draft PR that is not explicitly waiting on
the author, does not have a current terminal blocker, and that either:

- has no dashboard artifact with a current review action for the live upstream
  head (`post_review` for drafted findings, or `review_ready`/no-comment action
  for a clean looped review); or
- has a prior proposed review, but the live head SHA differs from the artifact
  or review action head SHA.

A terminal blocker must be pinned to the live upstream head, use
`stage: review_blocked`, and include one or more `blockers[]` entries whose
`detail` explains the exact failure and whose `remediation` names the concrete
manual step needed to resume. Generic checkpoints, missing validation, or a
bare "blocked" label do not clear the queue.

The queue is exhaustive. Build the run plan:

```powershell
$runPlanArgs = @(
  '-NoProfile', '-File', "$SkillRoot\scripts\Get-PrReviewRunPlan.ps1",
  '-Dashboard', $Dashboard, '-Upstream', $Upstream,
  '-BatchSize', $PrReviewBatchSize,
  '-MaxConcurrency', $PrReviewConcurrency,
  '-RunBudgetMinutes', $RunBudgetMinutes,
  '-AsJson'
)
if ($DrainReviewQueue) { $runPlanArgs += '-DrainQueue' }
pwsh @runPlanArgs
```

In normal mode, send only `selected_prs` through or resume them in
`powertoys-pr-review`; publish `deferred_prs` as queued work for later runs. In
drain mode, `selected_prs` is the full stale queue and `deferred_prs` must be
empty unless an unrecoverable blocker is published. A metadata-only refresh is
still insufficient: every run must either advance its selected work or honestly
retain durable in-progress state. Use `-FailOnStale` only in explicit drain
mode after all selected work has either completed or reached a durable blocked
state.

### Fast issue judgment

Before selecting issue work, enumerate the contract/freshness queue:

```powershell
pwsh -NoProfile -File `
  "$SkillRoot\scripts\Get-StaleIssueTriageQueue.ps1" `
  -Dashboard $Dashboard -AsJson
```

Every returned issue must receive the lightweight correction pass during the
run. Re-run the command before publication and report any remaining entries as
explicitly deferred; do not count them as updated or action-ready.

Every open `Issue-Bug` issue with no `judgment`, with live `updatedAt` newer
than `source_updated_at`, or whose artifact fails the complete current
schema-v5 contract receives a lightweight judgment during the run. Contract
failure includes missing issue context, an invalid fix-assessment status,
missing proposed fixes, missing confidence, a proposed fix without
`approve_design`, or a yellow/red fix without matching `request_info` and
information gaps. Recently generated timestamps never exempt these bugs from
re-triage. This pass is deliberately cheaper than `powertoys-issue-to-design`:
inspect the body, latest comments, labels, assignees, linked PRs/issues, and
obvious repository ownership signals, then emit one of:

| `judgment.status` | Dashboard result |
| --- | --- |
| `actionable_design` | Confidence-scored proposed fix plan and `Design fix` action; candidate for the bounded full-design batch |
| `reproducible` | `Reproduce` action with maintainer-ready local verification steps |
| `needs_information` | Draft a specific `request_info` action describing exactly what evidence is missing |
| `duplicate_or_handled` | Link the duplicate/fix/owned work; no duplicate agent work |
| `waiting_on_author` | Preserve the requested evidence and waiting-since timestamp |
| `not_actionable` | Explain feature/by-design/external/hardware/insufficient-scope reason |

Each judgment must contain `rationale`, concrete `evidence`, a
`recommended_action`, `evaluated_at`, and `source_updated_at`. The fast pass
may describe a root-cause hypothesis, but must distinguish it from confirmed
evidence and score it honestly.

Every open bug must use `schemaVersion: 5` and include `fix_assessment`.
Legacy artifacts without this coverage are stale and must not remain
actionable; queue them for re-triage even when upstream activity is unchanged:

- `status: proposed` when no existing fix attempt is present and a repository
  change is applicable. Include at least one `proposed_fixes[]` entry with a
  concrete root-cause hypothesis, ordered implementation plan, verification
  steps, and numeric confidence.
- `status: existing_fix` when an open/merged PR, active fork implementation, or
  other concrete fix attempt already covers the issue. Include the public URLs
  and explain the coverage; do not invent a competing plan.
- `status: not_applicable` only when a PowerToys code fix is genuinely not
  applicable, such as duplicate/handled work, expected behavior, unsupported
  hardware/external ownership, or insufficiently scoped non-bug reports.

Confidence is `0..100` and the level must match the score:

- `green` (`85..100`) — the evidence almost certainly identifies the root
  cause and fix.
- `yellow` (`51..84`) — the plan is more likely than not, but targeted
  reproduction or specific additional evidence would materially improve it.
- `red` (`0..50`) — the best current hypothesis, with no more than even odds
  that it is the correct root cause/fix.

For a red plan, the updater may run a short investigator/adversary loop of one
or two iterations before publication. Use it when focused code/history review
can cheaply test the hypothesis. Stop after two iterations, keep the red score
if uncertainty remains, and pair the plan with a targeted `request_info` or
`reproduce` action when that evidence would distinguish competing causes. Do
not force a full implementation-grade design or fabricate confidence merely to
turn the plan yellow.

Before defaulting to a request for logs or `/bugreport`, perform a focused
initial investigation using the issue body, discussion, labels, linked issues,
linked PRs, likely owning code area, and recent history/duplicates that can be
checked without a full implementation pass. If that investigation can identify
a plausible root cause or fix plan with useful confidence, emit that as a
design/fix path instead of only pushing the reporter for more information.

Every new or substantively refreshed issue artifact that exposes an action must
use `schemaVersion: 5` and include display-only `issue_context`:

- `summary` — a concise synthesis of the report and discussion, not a copy of
  the title or issue body;
- `known_information` — concrete facts already supplied by the reporter,
  commenters, labels, attachments, linked work, or live repository state;
- `inferences` — only conclusions supportable from those facts, phrased with
  uncertainty and never presented as confirmed root cause;
- `analysis` — the Copilot triage reasoning that connects the evidence to the
  proposed maintainer action;
- `initial_investigation` — focused code, history, duplicate, ownership, or
  diagnostic findings gathered during the lightweight pass;
- `information_gaps` — for each missing item, record `information`,
  `why_needed`, and, when known, `how_to_collect`.

This context is public, read-only decision support for the Pulse action window.
It is not part of `actions[].comment.body`, is not editable, and must never be
appended to the upstream comment automatically. Keep facts and inferences
separate. Do not publish private notes, unsupported speculation, local paths,
credentials, or sensitive diagnostic contents.

For `needs_information`, read the entire issue body and discussion before
drafting. The comment must acknowledge the useful issue-specific information
already present, identify the exact ambiguity or decision it cannot resolve,
then request only evidence that would change triage or implementation. Reuse
established PowerToys collection conventions instead of inventing generic
instructions:

- label the action with the evidence being requested, such as
  `Request activation trace` or `Confirm affected shortcut`; never use a
  generic label such as `Request information`;
- make the request itself immediately scannable: state the exact evidence,
  explain which decision it resolves, and give the collection method;
- when requesting multiple items, use a short numbered or bulleted list rather
  than hiding the asks inside a long paragraph;
- use a direct request such as `Please provide`, `Could you confirm`, or
  `Please reproduce and run /bugreport`; do not leave the reporter to infer
  what response is needed from background analysis alone;

- when a fresh PowerToys diagnostic archive is needed, ask the reporter to
  submit a comment containing `/bugreport`; explain that the generated ZIP
  should be captured immediately after reproducing the problem;
- ask for recordings, screenshots, Event Viewer entries, installer logs,
  configuration exports, versions, or numbered reproduction steps only when
  they address a specific recorded gap;
- if an attachment or prior answer already supplies an item, do not ask for it
  again;
- do not paste a standard multi-item checklist into unrelated issues.

The editable `request_info` comment and display-only context must agree:
`actions[].comment.body` asks for the same gaps recorded under
`issue_context.information_gaps`, and any gap whose `how_to_collect` names
`/bugreport` must use `/bugreport` in the proposed comment.

Every `fix_assessment.status=proposed` artifact must include an
`approve_design` action so the maintainer can either approve the fork-side
workflow or copy an artifact-specific implementation prompt for a local
Copilot agent. Pulse derives that prompt from the issue identity,
`issue_context`, `proposed_fixes`, and the implementation-grade `design` when
present. Copying the prompt is display-only: it requires no PAT and performs no
GitHub write.

Every yellow or red proposed fix must additionally include a targeted
`request_info` action and one or more matching
`issue_context.information_gaps`. The request asks only for evidence that would
materially improve or disprove the current plan. A green plan may omit
`request_info` only when no material uncertainty remains. The display-only
`proposed_fixes[].confidence` is the canonical score shown by Pulse.

The emitter must apply this complete contract before marking an open bug
artifact as publishable. A timestamped but partial artifact is not a valid
result: hide its actions, mark it for re-triage, and keep it out of
`artifact_numbers` until it passes schema-v5 context, fix-assessment, confidence,
and paired-action validation.

When an issue is already clearly reproducible from the public report or
attachments but does not yet justify a fix design, emit a `reproduce` action
instead of asking the reporter for more logs. The action must include the
PowerToys module, version/build requirement when relevant, prerequisites,
numbered reproduction steps, expected result, and any setup requirements. If
the repro needs external assets (for example, a file over a threshold size or a
specific file shape), include `reproduce.setup_prompt` so Pulse can copy a
prompt the maintainer can paste into a local agent to prepare those files, or
link public issue attachments in `reproduce.attachments`.

Older unchanged bugs with valid schema-v5 fix coverage do not need to be
re-read every run. Older schema-v4 or unversioned bugs must be migrated through
the fast judgment pass before their actions can be shown again. The 30-day
window controls full-design priority, not whether an open bug receives fix
coverage.

Issue action freshness is anchored to the latest upstream issue activity, with
latest comments being the decisive signal. A proposed issue action is current
only when `source_updated_at` covers the live issue `updatedAt`/latest comment
time. If a newer comment exists, do not expose the old request-info, close, or
fix action as actionable; mark the item for triage revalidation and publish
that queued state instead.

Do not emit placeholder issue controls. Issue artifacts should only include
concrete maintainer actions that can be executed from Pulse: request a specific
piece of information, post a close/dedupe/out-of-scope comment, approve/start a
fix design, guide a maintainer through a local reproduction, or open an
upstream PR from a completed fork fix. Do not include `hold`/`Not now` actions,
and do not publish issue artifacts whose only action is to wait.

For every artifact and mapped fork trace, also detect:

- upstream PR/issue closed, merged, superseded, or linked work appeared;
- labels, assignee, author response, or reproduction evidence changed;
- a fork mirror/PR was closed, merged, or replaced.

For open PRs, query the current head's check runs when permissions allow.
Classify the aggregate as passed, pending, failed, or unavailable/missing.
Pulse may synthesize a `trigger_ci` action from this live state when the checks
failed, were cancelled/timed out/stale, or no check run exists. Do not offer a
rerun while checks are already pending, and never post `/azp run`
automatically.

Use focused API calls rather than downloading the whole repository:

```powershell
gh pr view $Number -R $Upstream --json state,isDraft,headRefName,commits,reviews,comments,updatedAt
gh issue view $Number -R $Upstream --json state,labels,assignees,comments,body,updatedAt
```

Classify unfinished workflow state:

- **still current** — artifact can remain actionable;
- **needs re-review** — rerun `powertoys-pr-review` against the new PR head;
- **needs re-triage/design** — rerun `powertoys-issue-to-design`;
- **author action** — do not rerun; show waiting-on-author;
- **closed/superseded** — retain history but remove from the open backlog;
- **duplicate/handled** — record the linked upstream work and do not duplicate it.

## Phase 2 — Resume or rerun workflows

PR inventory is exhaustive. Normal execution is bounded to the run plan:
process only the selected batch, with at most three active workers by default.
The default batch contains sixteen PRs so cloud waits can release slots and let
other PRs advance without increasing local build concurrency. Drain mode is the
only mode that may select every stale PR in one conversation; it runs up to six
active workers by default and relies on checkpointed fork branches plus
incremental publication instead of a time cap. Prioritize resumable in-progress
reviews, stale proposed reviews, stale artifact heads, then missing artifacts.
Do not re-review an unchanged head that already has a current clean fork result
and no relevant newer activity.
Do not call a PR review complete, approval-ready, or "clean" unless the latest
freshly requested Copilot review has zero new comments, zero unresolved threads,
and the required local build has passed. A Copilot-clean result with a pending
build, context review, spelling check, or timed-out fresh request remains
`review_in_progress` and must get a `Re-run review`/`Continue review` action.

In normal mode, each worker receives the run-plan deadline and must stop
initiating new review rounds or builds 10 minutes before it. If it cannot
converge, it writes durable `review_in_progress` state and returns. In drain
mode, workers do not receive a stop deadline; they still must checkpoint every
fork, mirror, review-request, finding, and build transition so a later run can
resume from the fork branch or dashboard artifact after a crash. Do not keep
polling simply to make the current run look complete. Do not launch nested
agents from a PR worker.

Every worker prompt must explicitly say that fork-side commits, pushes, fork PR
updates, and fork thread resolution are allowed. Prohibit only dashboard
emission/commit/push and all writes to `microsoft/PowerToys`.

Use `Set-PrReviewCheckpoint.ps1` after each durable transition:

```powershell
pwsh -NoProfile -File `
  "$SkillRoot\scripts\Set-PrReviewCheckpoint.ps1" `
  -Dashboard $Dashboard -Number $Number -HeadSha $LiveHead `
  -SourceUpdatedAt $LiveUpdatedAt -Phase waiting_copilot `
  -Detail "Fresh fork review requested; the next run will inspect the result." `
  -ForkPr $ForkPr -ForkBranch $ForkBranch -Fork $Fork
```

Required checkpoint phases are: selected/`queued`, fork setup/`mirroring`,
review request/`review_requested`, external wait/`waiting_copilot`, finding
work/`reviewing_findings`, and local validation/`building`. A worker waiting on
GitHub Copilot performs one immediate status check only; if the result is not
ready, it checkpoints and returns instead of polling.

### Incremental publication during long PR loops

Long-running PR reviews must not block fresh dashboard data. Before launching
workers, regenerate and publish the inventory with `-AllowStaleReviewQueue`.
Checkpoint every stage transition locally immediately. In normal mode, after
two checkpoint transitions, eight elapsed minutes, or any completed artifact,
regenerate, sanitize, validate, commit, and push without waiting for remaining
selected PRs. In drain mode, use the same transition/completion triggers and a
five-minute maximum publish interval.
Regenerate and sanitize the feed, validate the completed PR numbers, run the
stale-review queue check without `-FailOnStale`, and commit/push the completed
artifacts plus index updates. The dashboard must show still-running PRs as
queued/running review, not as current.

At the normal-mode run deadline, publish completed/in-progress state and stop
cleanly. In drain mode, continue through additional work until the stale queue
is empty or a published blocker remains. Report selected, completed,
in-progress, and deferred counts. Run the `-FailOnStale` gate only in explicit
drain mode after the drain attempt finishes.

Issue **judgment and fix coverage** are exhaustive for every open bug lacking a
fully valid current schema-v5 artifact, as well as new/changed bugs. Build and
report this invalid-artifact re-triage queue separately from the bounded
full-design queue. The lightweight correction pass is not limited by
`$DesignBatchSize`; only implementation-grade design expansion is bounded.
Normal-mode full design work is bounded: rank `actionable_design` judgments by confidence,
reproducibility, scope, recency, and lack of existing ownership, then run at
most `$DesignBatchSize` (default 4) through `powertoys-issue-to-design`; leave
the rest queued with explicit `Design fix` actions. Drain mode removes this
design cap and processes every actionable issue design, still checkpointing and
publishing after each durable transition or completed artifact. Prefer issues
updated in the last `$IssueWindowDays`, then consume older actionable issues as
capacity allows.

For each queued item, invoke the corresponding skill with the upstream number
and complete its fork-side loop. Do not bypass its gates:

The retired custom `pr-iterate` agent must not be launched. `pr-iterate/<N>`
remains the durable fork branch naming convention used by
`powertoys-pr-review`; the current execution path is the `powertoys-pr-review`
skill itself, using a general-purpose worker when parallel background execution
is needed. That worker must not delegate to another agent.

- PR: `powertoys-pr-review` must reach zero new Copilot comments and zero
  unresolved Copilot threads before a new artifact is emitted. For stale-review
  queue items, the emitted artifact must include `head_sha` and any
  `post_review` action `review.head_sha` pinned to the live upstream head.
- Issue: `powertoys-issue-to-design` must reach a converged adversary-reviewed
  implementation-grade design and stop at approval.
- Approved design: `powertoys-design-to-pr` may build/review the fork PR but
  stops before opening the upstream PR unless separately approved.

If a workflow is waiting on an author or user approval, do not rerun it just to
make activity; preserve that status. A queued item must retain an explicit
fork trace or dashboard action even when its execution is deferred.
Draft every supported, current-head review finding as a proposed upstream
review comment. When the finding targets a current RIGHT-side diff range, emit
an `inline`/`in_diff: true` comment even when the author-facing text is
explanatory and has no apply-ready replacement. Add one `suggestion` block only
when the proposed edit is localized and safe to apply directly. Architectural,
cross-file, out-of-diff, validation, or coordination findings belong in
separate normal PR conversation comments and must still produce a pinned
`post_review` action.

Emit `post_review` with review event `COMMENT`. When every proposed comment is
inline, omit `review.body

…(truncated)