[KatalKavya96]

Summary

• Add a first-run welcome guide for the pairing family, covering self-review and multi-agent-review, so newcomers can understand the review workflow and get started with plain-language requests.
• Document optional configuration, personal installation versus project adoption, read-only safety boundaries, and workflow customization. Link the guide from docs/pairing/README.md.
• Add welcome regression tests and a preflight-floor evaluation fixture using the actual self-review surface hash. Regenerate the general welcome report and update evaluation case counts.

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 tests, and generated evaluation fixture

Test plan

• prek run --all-files passes
• For Python packages touched: uv run pytest / ruff check / mypy passes
• 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:
  • pytest tests/test_welcome.py — 51 tests passed before the additional family assertion.
  • render-preflight-fixtures.py --check — passed.
  • Welcome guide rendered successfully with the shared footer.
  • git diff --cached --check — passed.
  • Workspace pytest, Ruff check, Ruff format, mypy, documentation checks, and validators passed through prek.

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 runtime behavior, external write permissions, or security controls are changed. Both pairing skills remain read-only.

Linked issues

Closes #1661

Refs #1654

Notes for reviewers (optional)

• Follows the established first-run welcome guide pattern from feat(setup): first-run welcome guides, general and for the security skills #1653 and merged feat(setup): first-run welcome guide for the utilities family (#1663) #1669.
• Reuses the existing shared sections/welcome.md rules and generated footer; no additional per-family rules section or production logic changes are needed.
• The new evaluation fixture uses self-review with surface_hash: sha256:ea0a2e29bb2aa0e0.
• Covers both pairing skills in family discovery tests and validates first-run ordering, guide rendering, and footer substitution.
• The generated fixture and documentation counts are updated consistently.

AI tooling disclosure: AI assistance was used for repository analysis, patch drafting, and review. Changes were applied and validated locally by the contributor.

[KatalKavya96]

Hi @potiuk,

I've implemented the Pairing family welcome guide for #1661, following the established pattern from #1653 and the merged #1669.

I've included both pairing skills, the README link, first-run evaluation fixture, and regression tests. All repository-wide checks passed locally with prek run --all-files.

Thanks!

[Kaap10]

Thanks @KatalKavya96 for putting this together!

Tested locally — the welcome guide content is crisp, the surface hash matches self-review accurately, and both regression tests and preflight fixture checks pass cleanly.

Left one inline suggestion on docs/pairing/README.md regarding layout consistency with other family READMEs (security, utilities, contributor-growth). Other than that, everything looks solid!

[potiuk]

Adds the pairing-family first-run welcome guide for self-review and multi-agent-review, matching the utilities guide file for file; the scope options it lists exist in both skills and the fixture's self-review surface hash is correct.

I pushed two commits rather than send this round again:

• d788b60 — wording. "Install for yourself with /magpie-setup:setup config" now reads "Configure it for yourself …": config configures the skills you already installed and installs nothing. I also dropped the "Adversarial reviewers" bullet: neither pairing skill reads adversarial-review.md, and "three independent review passes" holds only for multi-agent-review (self-review is a single pass), so it would have pointed newcomers at a file this family never uses.
• 2c1c66f — merge of main. #1708 (the mentoring guide) landed first and claimed the same slots, so the pairing fixture moves to case-12-pairing-first-run, the setup case counts go to 132, the test lists carry both families, and the case-9 report is re-rendered with both guides in its "More guides" list.

Thanks for the guide!

---

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.