docs(setup): add PR-management welcome guide

[leninworld]

This PR addresses part of issue #1655.

Summary

• Add the first-run welcome guide for the PR-management family: configuration, the queue workflow, example prompts and overrides. Every write it describes stays confirmed, and quick-merge leaves the merge command to the user.
• Link the guide from the family documentation, and cover its first-run sequence and shared footer in test_welcome.py.
• Add the rendered preflight-floor fixture case-11-pr-management-first-run and update the generated case-9 report and case counts. The guide uses the shared welcome section, like the utilities guide (PR #1669); no core logic changes.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other: setup-preflight welcome guide, regression test and preflight-floor fixture

Test plan

Linux ARM64 Docker, Python 3.12, uv 0.11.8, Git 2.47.3.

• prek run --all-files passes (every hook, including workspace pytest and lychee)
• For Python packages touched: uv run pytest / ruff check / mypy passes (setup-preflight: 257 passed; mypy: no issues in 26 source files)
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill
  (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
• Other: render-preflight-fixtures.py --check passes; the new sequence test fails without the guide and passes with it; python -m setup_preflight.welcome show --family pr-management renders the guide and shared footer (69 lines).

Not run: provider-driven skill evals (they need model calls) and hosted CI (not yet run). The container used a child-subreaper wrapper for normal orphan reaping; project code and test assertions are unchanged. A wheel-build probe fails identically on unchanged main and on this branch, because the package config adds setup_preflight/guides/_footer.md twice. No packaging change or successful wheel build is claimed.

RFC-AI-0004 compliance

• HITL — any new mutation is gated on explicit user confirmation
• Sandbox — no new unrestricted host access; network reach declared in the adapter
• Vendor neutrality — placeholders (<PROJECT>, <tracker>, <upstream>, <security-list>) used in all skill / tool prose (the check-placeholders prek hook is the mechanical gate)
• Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
• Write-access discipline — no autonomous outbound messages; drafts only, sent on confirmation
• Privacy LLM — private content does not reach a non-approved LLM; redactor invoked where needed

No new mutation, host access, outbound write or LLM hop; the guide describes the family's existing confirmation gates.

Linked issues

Refs #1655

Notes for reviewers (optional)

• Case 11 follows the requested contiguous numbering on current main. PR #1673 independently adds another case 11; whichever lands second will need renumbering, fixture regeneration and count updates.

• If you would prefer a per-family sections/welcome-pr-management.md (asked on the issue), I can add it.

• Review corrections: explicitly use pr-triage's surface hash in the fixture, provide nine unique skill prompts, match the other guides' heading accents, and rename the shipping test to test_the_rules_section_and_all_guides_ship. The follow-up also repairs invalid JSON in the applied state.json suggestion. A narrow spell-check exclusion covers SHA-256 fixture hash values.

Validation evidence

---

Was generative AI tooling used to co-author this PR?

• Yes — Codex (GPT-6), with independent review by Claude (Opus 5.5)

Generated-by: Codex (GPT-6)

The contributor has read every line of the diff and can answer review questions about it.

[Kaap10]

Thanks @leninworld for putting this together! The structure and test coverage follow the pattern established in #1653 and #1669 well.

Before merge, there are a few fixture state corrections and consistency adjustments needed:

1. surface_hash in eval fixture: report.md quotes sha256:2edc90a1b7f3440d (the hash for list-skills), whereas pr-triage is sha256:54dc4ba1be7b36d4.
2. Fixture sequence numbering: There is no case-11 on main, so naming this case-12 creates an unexpected gap.
3. Full skill prompt coverage: Include prompt examples for all 9 skills under ## Just ask (quick-merge, reviewer-routing, stats).
4. Visual parity: Add standard emoji accents (🐦, 🔄, ⚙️, 💬, 🎨) to match the other family guides.

[leninworld]

Thanks @leninworld for putting this together! The structure and test coverage follow the pattern established in #1653 and #1669 well.

Before merge, there are a few fixture state corrections and consistency adjustments needed:

1. **`surface_hash` in eval fixture**: `report.md` quotes `sha256:2edc90a1b7f3440d` (the hash for `list-skills`), whereas `pr-triage` is `sha256:54dc4ba1be7b36d4`.

2. **Fixture sequence numbering**: There is no `case-11` on `main`, so naming this `case-12` creates an unexpected gap.

3. **Full skill prompt coverage**: Include prompt examples for all 9 skills under `## Just ask` (`quick-merge`, `reviewer-routing`, `stats`).

4. **Visual parity**: Add standard emoji accents (`🐦`, `🔄`, `⚙️`, `💬`, `🎨`) to match the other family guides.

Done. Thank you!

[Kaap10]

LGTM! Thanks @leninworld for addressing all review points so quickly.

Next maintainer will look into it and take it forward!

[potiuk]

Adds the PR-management welcome guide covering all nine skills; the config files it names, the quick-merge "hands you the command" claim and the pr-triage surface hash all check out, every point from the earlier review is addressed, and the .typos.toml pattern is needed (typos flags ba inside the fixture's hash).

I pushed two commits rather than send this round again:

• 50e8af5 — fixup. The bullet for /magpie-setup:setup config was labelled Installed, but config configures the skills you already installed and installs nothing, so it now reads Configure it for yourself. The welcome tests need a skill whose family ships no guide; activity-sweep would have broken as soon as the contributor-growth guide (#1702) lands, so OTHER_SKILL is now ci-runner-audit (repo-health), a family with no guide in flight.
• d39a03c, 961333a — merges of main. The mentoring (#1708), pairing (#1706) and issue (#1709) guides landed first and claimed the same slots, so this fixture is now case-14-pr-management-first-run, the setup case counts go to 134, the test lists carry every family, and the case-9 report is re-rendered.

I also approved the held workflow runs; the PR merges automatically once they are green. Thanks for your first contribution!

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.