[bkudiess]

What Problem This Solves

Agents need one discoverable workflow for preparing a truthful Windows PR draft without mistaking stale evidence or implementation permission for publication readiness.

User Impact

No product behavior changes. Contributors get a consistent local preparation path that keeps evidence limits and publication authority explicit.

Why This Change Was Made

Adds one skill with six steps: establish the claim and authority, select validation, inspect actual results, review the intended scope, fill the current template, and report readiness before stopping. A root AGENTS.md row, a related-guidance link and a task decision checklist row in docs/AGENT_WORKFLOWS.md make it discoverable. The proof skill's PR proof package still owns evidence requirements and now links to this skill for assembling them. Step 4 accounts for both source review and the required independent rubber-duck review; a missing required review is reported as blocked. Existing validation, proof and review guidance remains authoritative; no runner, renderer or CI change.

Evidence

Post-commit documentation and skill checks pass. Static walkthroughs cover the completed prose and nonvisual C# authoring pilots plus stale/blocked evidence. One independent Copilot code-review task covered P0-P3, all three files, 13 links/anchors and the template contract with no actionable findings or optional suggestions. Its reviewed precommit bytes match the first commit, 1ddaedf5; the review was not rerun or restamped. Later commits address a follow-up review: 82cd10cf adds the rubber-duck gate, the proof-skill back-link and the checklist row, clarifies wording and removes unsupported statements; maintainer commit 6cb0b601 removes the personal-fork sentence from step 6. Neither later commit was covered by that Copilot review. Model identity is unverified. This is narrative/static review, not shared-helper isolation, dual-model review or end-to-end agent qualification.

Change Type

• Bug fix
• Feature
• Refactor
• Docs or instructions
• Tests or validation
• Security hardening
• Chore or infrastructure

Scope

• Tray or WinUI UX
• Windows node capability
• Local MCP or winnode
• Gateway, connection, or pairing
• Setup or onboarding
• Permissions, privacy, or security
• Tests, CI, or docs

Required proof pools

• none: prose-only skill and routing links; no capacity-dependent native behavior changed.

Validation

Current head 6cb0b601041ff29e38557c049abb4065cd783114, hosted CI (fast-validation on merge 114d8286 with main at 1b4d325e):

Check	Result
./scripts/validate-docs.ps1	PASS: 64 Markdown files; proof-pool validation 7 named pools
./scripts/validate-agent-skills.ps1	PASS: 12 skills, 21 Markdown files
CI Gate	PASS

The local commands below ran only at the first commit and were not rerun locally on 82cd10cf or 6cb0b601. git diff --check passed locally on the 6cb0b601 change.

At 1ddaedf5eff3b3e3aa57b814bd0b7423e9526384:

Command	Result
.\scripts\validate-docs.ps1	PASS, exit 0: 64 Markdown files; 7 proof pools through both schema paths; documentation-flow regression passed
.\scripts\validate-agent-skills.ps1	PASS, exit 0: 12 skills, 21 Markdown files
git diff --check HEAD^ HEAD	PASS, exit 0
git diff --check	PASS, exit 0; working tree clean

On the identical reviewed precommit content, .\scripts\test-agent-skills-validator.ps1 passed 27 fixtures plus repository skills (exit 0, conversation-output evidence). Source correspondence is verified, not a claim of a new fixture run. Full build, Shared/Tray and native runtime proof were not run for this prose-only change.

Real Behavior Proof

• Environment tested: hosted CI fast-validation for the current head; earlier Windows task-owned worktree for the first commit; static documentation validation.
• PR head or commit tested: 6cb0b601041ff29e38557c049abb4065cd783114 in hosted CI; local commands at 1ddaedf5eff3b3e3aa57b814bd0b7423e9526384 only.
• Exact steps or command run: commands in Validation; source/template and routing inspection.
• Evidence after fix: Agent skill validation passed: 12 skills and 21 Markdown files checked. (CI, current head)
• Observed result: new skill metadata and local links/anchors validate; all 12 template headings, 8 comments and 16 checklist items are retained in this body.
• Screenshot or artifact links verified? (Yes/No/N/A) N/A, no external artifacts.
• Not verified or blocked: runtime proof is not applicable; no live UI/MCP/Gateway proof or end-to-end agent-compliance claim. Shared-helper review was unavailable; independent narrative review is described above. Hosted CI is reported separately by GitHub.

Security Impact

• New permissions or capabilities? (Yes/No) No
• Secrets or tokens handling changed? (Yes/No) No
• New or changed network calls? (Yes/No) No
• Command or tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any answer is Yes, explain the risk and mitigation: N/A

Compatibility and Migration

• Backward compatible? (Yes/No) Yes
• Config or environment changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, list the exact upgrade steps: N/A

Review Conversations

• I replied to or resolved every bot review conversation addressed by this PR.
• I left unresolved only conversations that still need maintainer judgment.

N/A at preparation: no bot review conversations were addressed.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

Adds a six-step Windows PR preparation skill and links it from the repository’s agent guidance.

Example: An agent prepares a prose-only PR at commit 1ddaedf.

• Before: The agent must assemble preparation steps from separate validation, proof, review, and template references.
• After: One workflow guides the agent through those references, produces a local draft, and stops before publication without explicit authority.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, source-consistent documentation patch with appropriate static validation and no actionable findings; observed agent compliance is not established or claimed.
Proof confidence	🐚 platinum hermit (4/6)	This prose-only skill changes preparation guidance; supplied static validation and passing exact-head documentation checks fit that contract, without claiming end-to-end agent compliance.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Contributors lack one discoverable path from a selected change and its evidence to a truthful local PR draft.
Reason: The collaborator-authored direction is authorized, and the guide supplies useful orchestration without changing existing contracts.

Merge readiness

✅ Ready for maintainer review

This PR adds useful, scoped preparation guidance that is absent from current main. No actionable defects were found, and the collaborator-authored item remains open under the maintainer guard.

Priority: P3
Reviewed head: 1ddaedf5eff3b3e3aa57b814bd0b7423e9526384

Before merge

None.

Findings

None.

Agent review details

How this fits together

Repository agent instructions route contributors into this skill, which combines the selected change, existing validation guidance, evidence, and PR template into a local draft and readiness handoff.

flowchart TD
A[Agent task routing] --> B[PR preparation skill]
B --> C[Validation and proof owners]
B --> D[Scoped review guidance]
C --> E[Current PR template]
D --> E
E --> F[Local draft and readiness handoff]

Loading

Technical review

Best possible solution:

Land the focused preparation skill while retaining the existing validation, proof, review, and template owners.

Do we have a high-confidence way to reproduce the issue?

No runtime bug is claimed; source inspection confirms that current main lacks the proposed consolidated preparation workflow.

Is this the best way to solve the issue?

The six-step guide addresses the discoverability gap through existing owners and avoids adding runners, duplicated review implementations, or publication authority.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 2dfb4c78ef05.

Provenance checked

• Agent task routing and workflow references keeps the original intent (3977f82: Route agents to authoritative owners and distinguish incomplete or stale validation from completed proof.)

Security

None.

Evidence

What I checked:

• Pinned introduced change: The introduced patch adds only the new skill and two routing links; the verified test merge preserves that same scope. (.agents/skills/windows-pr-prepare/SKILL.md:8, 1ddaedf5eff3)
• Existing owners remain authoritative: The skill delegates validation selection, proof admission, scoped review, and template requirements to their existing owners rather than introducing executable machinery. (.agents/skills/windows-pr-prepare/SKILL.md:29, 1ddaedf5eff3)
• Exact-head checks: Fast validation, proof-pool contracts, change classification, and CI Gate passed for the reviewed head; the workflow includes documentation, skill, and skill-validator checks. (.github/workflows/ci.yml:150, 1ddaedf5eff3)
• Prior intent and feature ownership: The merged guidance in improve: make agent guidance and validation more reliable #1724 established task routing and truthful evidence handling; docs: make local review scope and outcomes explicit #1804 refined review scope and outcomes. This PR preserves both directions. (docs/AGENT_WORKFLOWS.md:3, 2dfb4c78ef05)
• Discussion and live PR state: The complete discussion contains only review-status bot comments, with no opposing direction or unresolved contributor discussion; GitHub reports the reviewed head as non-draft and mergeable. (1ddaedf5eff3)
• Not already implemented: The preparation skill is absent from the fetched default branch, so an implemented-on-main close is unsupported. (.agents/skills/windows-pr-prepare/SKILL.md, 2dfb4c78ef05)

Likely related people:

• Barbara Kudiess: Raw commit 3977f82 adds docs/AGENT_WORKFLOWS.md:3 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 3977f8206ed4; files: docs/AGENT_WORKFLOWS.md)

Labels

Label changes:

• add P3: This is contributor-workflow documentation with no product runtime change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P3: This is contributor-workflow documentation with no product runtime change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 21, 2026, 11:43 PM ET / October 22, 2026, 03:43 UTC.