From a2edfbddc843bac08ac084dc77a2fe45f0099079 Mon Sep 17 00:00:00 2001 From: Lenin Mookiah Date: Mon, 19 Oct 2026 01:47:35 +0000 Subject: [PATCH 1/6] docs(setup): add PR-management welcome guide Add the first-run family guide, link it from the documentation and cover the welcome sequence with a regression test and rendered fixture. Refs: #1655 Generated-by: Codex (GPT-6) --- docs/pr-management/README.md | 2 + .../setup_preflight/guides/pr-management.md | 58 +++++++++++++++++++ tools/setup-preflight/tests/test_welcome.py | 21 +++++-- tools/skill-evals/README.md | 2 +- tools/skill-evals/evals/setup/README.md | 4 +- .../case-meta.json | 1 + .../expected.json | 1 + .../case-12-pr-management-first-run/report.md | 37 ++++++++++++ .../state.json | 23 ++++++++ .../case-9-first-magpie-run/report.md | 2 +- 10 files changed, 142 insertions(+), 9 deletions(-) create mode 100644 plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/case-meta.json create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/expected.json create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/report.md create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json diff --git a/docs/pr-management/README.md b/docs/pr-management/README.md index c1adc9810..e74938095 100644 --- a/docs/pr-management/README.md +++ b/docs/pr-management/README.md @@ -84,6 +84,8 @@ wording, CI-check → doc-URL map, review-criteria source files). ## Install & first runs +New to this family? Read the [one-minute welcome guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md). + Install just this family — one plugin, 9 skills. Maintainer-facing PR-queue management. Once you have [added the marketplace](../setup/marketplace-install.md): diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md new file mode 100644 index 000000000..f4557670f --- /dev/null +++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md @@ -0,0 +1,58 @@ + + +# Magpie here — your PR-management sidekick + +A one-minute tour, then straight back to what you asked for. + +## Configure it + +Start with ``, the project's review criteria and its area labels. +`pr-management-code-review-criteria.md` names the criteria sources; +`pr-management-config.md` carries the labels and queue rules. +`reviewer-roster.md` tells reviewer routing who covers each area. + +- **Installed** — just for you: personal configuration, nothing committed — `/magpie-setup:setup config` +- **Adopted** — for your project: shared configuration committed to the repo — `/magpie-setup:setup adopt` (a maintainers' decision) + +On a pinned-snapshot install, use `/magpie-setup config` or `/magpie-setup adopt`. + +Optional companion: roborev reviews your own branch before it becomes a PR; +this family helps you review and manage other people's PRs. +Neither requires the other. + +## The typical flow + +1. **Triage the queue** — propose a disposition for each PR — *"triage the open PRs"* +2. **Route reviewers** — use the roster to suggest the right people — *"who should review this PR?"* +3. **Review** — inspect the diff and draft inline feedback — *"review this PR against our criteria"* +4. **Quick-merge** — screen easy candidates and propose the command for you to run — *"which PRs are ready for quick-merge?"* +5. **Mentor** — help a contributor through the next step — *"draft helpful feedback for this contributor"* +6. **Stale sweep** — propose follow-ups for inactive PRs — *"show me the stale PRs"* +7. **Stats** — see where the queue needs attention — *"summarise the PR backlog by area"* + +Nothing is written, posted, labelled or closed without your explicit confirmation. +Quick-merge never merges for you: it hands you the command. + +## Just ask + +Plain language works: + +- *"check my branch before I open my first PR"* +- *"triage the PRs waiting for review"* +- *"review this PR stack in dependency order"* +- *"draft a review, but do not post it"* +- *"help this contributor understand the requested change"* +- *"what changed in the queue since the last sweep?"* + +## Make it yours + +Change a workflow by describing the change: + +- *"from now on, group the backlog by our area labels"* +- *"use our review criteria when drafting feedback"* + +Each becomes an override for the PR-management skill it changes. +Useful to other maintainers? *"Upstream this change to Magpie"* prepares a generic PR for you to review before it opens. + + diff --git a/tools/setup-preflight/tests/test_welcome.py b/tools/setup-preflight/tests/test_welcome.py index 4e0d2a77c..f3c72e1d1 100644 --- a/tools/setup-preflight/tests/test_welcome.py +++ b/tools/setup-preflight/tests/test_welcome.py @@ -34,7 +34,7 @@ REPO_ROOT = Path(__file__).resolve().parents[3] SECURITY_SKILL = "issue-sync" -OTHER_SKILL = "pr-triage" +OTHER_SKILL = "activity-sweep" def stamp(root: Path) -> dict: @@ -87,6 +87,14 @@ def test_the_utilities_family_guide_comes_on_the_next_run(project: Path, version assert due(project, "list-skills") == [("general", "again")] +def test_the_pr_management_family_guide_comes_on_the_next_run(project: Path, version) -> None: + assert due(project, "pr-triage") == [("general", "first-run")] + welcome.record(project, "general", "seen") + assert due(project, "pr-triage") == [("pr-management", "first-run")] + welcome.record(project, "pr-management", "seen") + assert due(project, "pr-triage") == [("general", "again")] + + def test_at_most_one_guide_per_run(project: Path, version) -> None: for _ in range(8): found = welcome_findings(project, SECURITY_SKILL) @@ -110,7 +118,7 @@ def test_a_hidden_general_guide_does_not_hold_back_the_family_one(project: Path, def test_a_skill_of_a_family_without_a_guide_gets_only_the_general_one(project: Path, version) -> None: - assert welcome.family_of(OTHER_SKILL) == "pr-management" + assert welcome.family_of(OTHER_SKILL) == "contributor-growth" assert due(project, OTHER_SKILL) == [("general", "first-run")] welcome.record(project, "general", "never") assert due(project, OTHER_SKILL) == [] @@ -384,11 +392,11 @@ def test_show_without_color_prints_the_markdown(capsys) -> None: def test_the_rules_section_and_both_guides_ship() -> None: assert welcome.SECTION in sections.available() - assert {"general", "security", "utilities"} <= set(welcome.guides()) + assert {"general", "pr-management", "security", "utilities"} <= set(welcome.guides()) assert welcome.family_guides() == [g for g in welcome.guides() if g != "general"] -@pytest.mark.parametrize("name", ["general", "security", "utilities"]) +@pytest.mark.parametrize("name", ["general", "pr-management", "security", "utilities"]) def test_each_guide_is_short_and_ends_with_the_way_back(name: str) -> None: text = welcome.guide(name) or "" assert not text.startswith(" + +There is no `.apache-magpie.lock`, no `.apache-magpie-overrides/` and no +`.apache-magpie-local/` at the repo root. The running agent is Claude Code +with magpie-setup 0.4.0 and magpie-pr-management 0.4.0 installed. + +The user has already seen the initial general welcome guide on an earlier run. +The invoked skill's own frontmatter reads `name: pr-triage` and +`surface_hash: sha256:2edc90a1b7f3440d`; it belongs to the pr-management family. +This is the first time a pr-management skill has run here. +The user asked it to "triage the open PRs". + +The pre-flight command printed: + +```json +{ + "findings": [ + { + "code": "welcome", + "facts": { + "family": "pr-management", + "guide": "# Magpie here \u2014 your PR-management sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## Configure it\n\nStart with ``, the project's review criteria and its area labels.\n`pr-management-code-review-criteria.md` names the criteria sources;\n`pr-management-config.md` carries the labels and queue rules.\n`reviewer-roster.md` tells reviewer routing who covers each area.\n\n- **Installed** \u2014 just for you: personal configuration, nothing committed \u2014 `/magpie-setup:setup config`\n- **Adopted** \u2014 for your project: shared configuration committed to the repo \u2014 `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install, use `/magpie-setup config` or `/magpie-setup adopt`.\n\nOptional companion: roborev reviews your own branch before it becomes a PR;\nthis family helps you review and manage other people's PRs.\nNeither requires the other.\n\n## The typical flow\n\n1. **Triage the queue** \u2014 propose a disposition for each PR \u2014 *\"triage the open PRs\"*\n2. **Route reviewers** \u2014 use the roster to suggest the right people \u2014 *\"who should review this PR?\"*\n3. **Review** \u2014 inspect the diff and draft inline feedback \u2014 *\"review this PR against our criteria\"*\n4. **Quick-merge** \u2014 screen easy candidates and propose the command for you to run \u2014 *\"which PRs are ready for quick-merge?\"*\n5. **Mentor** \u2014 help a contributor through the next step \u2014 *\"draft helpful feedback for this contributor\"*\n6. **Stale sweep** \u2014 propose follow-ups for inactive PRs \u2014 *\"show me the stale PRs\"*\n7. **Stats** \u2014 see where the queue needs attention \u2014 *\"summarise the PR backlog by area\"*\n\nNothing is written, posted, labelled or closed without your explicit confirmation.\nQuick-merge never merges for you: it hands you the command.\n\n## Just ask\n\nPlain language works:\n\n- *\"check my branch before I open my first PR\"*\n- *\"triage the PRs waiting for review\"*\n- *\"review this PR stack in dependency order\"*\n- *\"draft a review, but do not post it\"*\n- *\"help this contributor understand the requested change\"*\n- *\"what changed in the queue since the last sweep?\"*\n\n## Make it yours\n\nChange a workflow by describing the change:\n\n- *\"from now on, group the backlog by our area labels\"*\n- *\"use our review criteria when drafting feedback\"*\n\nEach becomes an override for the PR-management skill it changes.\nUseful to other maintainers? *\"Upstream this change to Magpie\"* prepares a generic PR for you to review before it opens.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the pr-management welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide pr-management`\n(`/magpie-setup-welcome-guide pr-management` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family pr-management --color=always\n```\n", + "max_shown": 3, + "reason": "first-run", + "shown": 0 + }, + "scope": "family", + "section": "welcome" + } + ], + "rules": { + "welcome": "## welcome \u2014 a first-run welcome guide is due\n\nA welcome guide is due on this run: `facts.family` names it\n(`general`, for the first Magpie skill this user runs here, or the skill's own family),\nand `facts.reason` says why (`first-run`, `again`, or `upgraded` after a dismissal).\n`facts.guide` is the guide. The checker shows at most one guide per run and has already picked it.\n\n1. **Show `facts.guide` to the user verbatim**, as Markdown, before the work they asked for.\n Do not summarise, reword, trim, or add to it, and substitute nothing in it:\n its placeholders (``, ``, ``, \u2026) are meant to be read as written.\n2. **Offer the three choices in one line**:\n **Continue** (show again next time) \u00b7 **Dismiss** (hide until the next Magpie upgrade) \u00b7 **Don't show again**.\n3. **Record `seen` at once**, which is what no answer means, then carry on with the user's request in the same turn.\n Never block the requested work on the guide, and never wait for an answer before starting it.\n4. **When the user picks Dismiss or Don't show again** \u2014 now or later in the session \u2014 record that choice;\n it replaces `seen`. Continue needs nothing further.\n\n```bash\nPYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" \\\n python3 -m setup_preflight.welcome record --family --choice \n```\n\n`seen` brings the guide back on a later run, `facts.max_shown` recorded showings in all (`facts.shown` so far);\n`dismiss` hides it until the framework version changes; `never` hides it until re-enabled.\nEvery write merges into the personal layer's `reconciled.json` under `welcome.`, keeping every other key;\nnever write it by hand.\nIf the command exits non-zero, say nothing more about it and carry on.\n\nAny guide can be shown again on request with `/magpie-setup:welcome-guide []`,\nwhich also turns a hidden one back on." + }, + "verdict": "action" +} +``` diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json new file mode 100644 index 000000000..e0938d47a --- /dev/null +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json @@ -0,0 +1,23 @@ +{ + "lock": null, + "plugins": [ + [ + "magpie-setup", + "0.4.0" + ], + [ + "magpie-pr-management", + "0.4.0" + ] + ], + "reconciled": { + "welcome": { + "general": { + "choice": "seen", + "shown": 1 + } + } + }, + "skill": "pr-triage", + "welcome": true +} diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md index 32584a3eb..cd7a3aa64 100644 --- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md @@ -20,7 +20,7 @@ The pre-flight command printed: "code": "welcome", "facts": { "family": "general", - "guide": "# \ud83d\udc26 Hello from Magpie \u2014 your project's maintainer sidekick\n\nOne minute, then straight back to what you asked for.\n\n## \ud83d\ude80 Getting started\n\n- \ud83d\udce6 **Install** from your agent's marketplace (Claude Code shown):\n `/plugin marketplace add apache/magpie`,\n then `/plugin install magpie-setup@apache-magpie` and one `/plugin install magpie-@apache-magpie` per family you want\n- \ud83d\ude4b **Configure it for yourself** \u2014 personal settings, nothing committed \u2014 `/magpie-setup:setup config`\n- \ud83d\udc65 **Adopt it for your project** \u2014 the configuration is committed to your repo and shared with every contributor \u2014\n `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install the commands are shorter: `/magpie-setup config`, `/magpie-setup adopt`.\n\n## \ud83d\udd04 Staying current\n\n- \u270b **By hand:** `claude plugin marketplace update apache-magpie`, then `claude plugin update @apache-magpie`\n- \ud83e\udd16 **Automatically (Claude Code):** `/plugin` \u2192 **Marketplaces** \u2192 **apache-magpie** \u2192 **Enable auto-update** \u2014\n it is off by default for third-party marketplaces like this one\n- \ud83e\udde9 Gemini CLI takes `--auto-update` at install time; Codex has no auto-update, so run `codex plugin marketplace upgrade`\n\nAfter an update, the next skill you run checks your configuration against it and proposes any fixes;\n`/magpie-setup:setup reconcile` checks everything at once\n(on a pinned snapshot, `/magpie-setup upgrade` does the update).\n\n## \ud83d\udcac Just ask\n\nTalk to Magpie in plain language \u2014 no syntax to learn.\nNothing is written, posted, or sent without your OK.\nInterrupt at any time, say no, or change your mind halfway through.\n\n## \ud83c\udfa8 You are the creator\n\nDescribe what you want a skill to do for you:\n\n- *\"from now on, always ask me before closing a stale issue\"*\n- *\"when you triage PRs, leave the bot-authored ones alone\"*\n\nMagpie records it as an override for that skill (`/magpie-setup:setup override `).\nWorth sharing? Say *\"upstream this change to Magpie\"* \u2014\nit makes the change generic and opens a PR to `apache/magpie` for you to review (`/magpie-setup:override-upstream`).\n\n## \ud83d\udcda More guides\n\nEach family can bring its own short guide, shown the first time you use it:\n\n- `security` \u2014 `/magpie-setup:welcome-guide security`\n- `utilities` \u2014 `/magpie-setup:welcome-guide utilities`\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the Magpie welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide []`\n(`/magpie-setup-welcome-guide []` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family general --color=always\n```\n", + "guide": "# \ud83d\udc26 Hello from Magpie \u2014 your project's maintainer sidekick\n\nOne minute, then straight back to what you asked for.\n\n## \ud83d\ude80 Getting started\n\n- \ud83d\udce6 **Install** from your agent's marketplace (Claude Code shown):\n `/plugin marketplace add apache/magpie`,\n then `/plugin install magpie-setup@apache-magpie` and one `/plugin install magpie-@apache-magpie` per family you want\n- \ud83d\ude4b **Configure it for yourself** \u2014 personal settings, nothing committed \u2014 `/magpie-setup:setup config`\n- \ud83d\udc65 **Adopt it for your project** \u2014 the configuration is committed to your repo and shared with every contributor \u2014\n `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install the commands are shorter: `/magpie-setup config`, `/magpie-setup adopt`.\n\n## \ud83d\udd04 Staying current\n\n- \u270b **By hand:** `claude plugin marketplace update apache-magpie`, then `claude plugin update @apache-magpie`\n- \ud83e\udd16 **Automatically (Claude Code):** `/plugin` \u2192 **Marketplaces** \u2192 **apache-magpie** \u2192 **Enable auto-update** \u2014\n it is off by default for third-party marketplaces like this one\n- \ud83e\udde9 Gemini CLI takes `--auto-update` at install time; Codex has no auto-update, so run `codex plugin marketplace upgrade`\n\nAfter an update, the next skill you run checks your configuration against it and proposes any fixes;\n`/magpie-setup:setup reconcile` checks everything at once\n(on a pinned snapshot, `/magpie-setup upgrade` does the update).\n\n## \ud83d\udcac Just ask\n\nTalk to Magpie in plain language \u2014 no syntax to learn.\nNothing is written, posted, or sent without your OK.\nInterrupt at any time, say no, or change your mind halfway through.\n\n## \ud83c\udfa8 You are the creator\n\nDescribe what you want a skill to do for you:\n\n- *\"from now on, always ask me before closing a stale issue\"*\n- *\"when you triage PRs, leave the bot-authored ones alone\"*\n\nMagpie records it as an override for that skill (`/magpie-setup:setup override `).\nWorth sharing? Say *\"upstream this change to Magpie\"* \u2014\nit makes the change generic and opens a PR to `apache/magpie` for you to review (`/magpie-setup:override-upstream`).\n\n## \ud83d\udcda More guides\n\nEach family can bring its own short guide, shown the first time you use it:\n\n- `pr-management` \u2014 `/magpie-setup:welcome-guide pr-management`\n- `security` \u2014 `/magpie-setup:welcome-guide security`\n- `utilities` \u2014 `/magpie-setup:welcome-guide utilities`\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the Magpie welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide []`\n(`/magpie-setup-welcome-guide []` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family general --color=always\n```\n", "max_shown": 3, "reason": "first-run", "shown": 0 From 6c03f0d8859c4689b582af8ef8a989badd12a683 Mon Sep 17 00:00:00 2001 From: Lenin Mookiah Date: Sun, 18 Oct 2026 22:11:24 -0700 Subject: [PATCH 2/6] Update plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md Co-authored-by: Vardhman Gupta <112063624+Kaap10@users.noreply.github.com> --- .../skills/setup/setup_preflight/guides/pr-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md index f4557670f..61c44a460 100644 --- a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md +++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md @@ -1,7 +1,7 @@ -# Magpie here — your PR-management sidekick +# 🐦 Magpie here — your PR-management sidekick A one-minute tour, then straight back to what you asked for. From 0b52709aac8d78db0ac0bda143f25cd4937023d1 Mon Sep 17 00:00:00 2001 From: Lenin Mookiah Date: Sun, 18 Oct 2026 22:11:42 -0700 Subject: [PATCH 3/6] Update plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md Co-authored-by: Vardhman Gupta <112063624+Kaap10@users.noreply.github.com> --- .../skills/setup/setup_preflight/guides/pr-management.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md index 61c44a460..63616bd05 100644 --- a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md +++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md @@ -43,7 +43,15 @@ Plain language works: - *"review this PR stack in dependency order"* - *"draft a review, but do not post it"* - *"help this contributor understand the requested change"* +- *"check my branch before I open my first PR"* +- *"triage the PRs waiting for review"* +- *"who should review this PR?"* +- *"review this PR against our criteria"* +- *"review this PR stack in dependency order"* +- *"which PRs are ready for quick-merge?"* +- *"help this contributor understand the requested change"* - *"what changed in the queue since the last sweep?"* +- *"summarise the PR backlog by area"* ## Make it yours From 400ac75c40c58c39fb47c9cd2bac7b3631318284 Mon Sep 17 00:00:00 2001 From: Lenin Mookiah Date: Sun, 18 Oct 2026 22:29:36 -0700 Subject: [PATCH 4/6] Update tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json Co-authored-by: Vardhman Gupta <112063624+Kaap10@users.noreply.github.com> --- .../fixtures/case-12-pr-management-first-run/state.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json index e0938d47a..64360a56d 100644 --- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json @@ -20,4 +20,7 @@ }, "skill": "pr-triage", "welcome": true + "hash": "sha256:54dc4ba1be7b36d4", + "skill": "pr-triage", + "welcome": true } From 6c378914c2c46def1d4d9e864165b78e1e34237e Mon Sep 17 00:00:00 2001 From: Lenin Mookiah Date: Mon, 19 Oct 2026 05:37:27 +0000 Subject: [PATCH 5/6] docs(setup): address PR-management guide review Use the pr-triage surface hash in the fixture state and report prose, provide all nine skill prompts, match the family guide headings, and rename the shipping test to describe all guides. Renumber the fixture as requested and narrowly exclude generated JSON hashes from spelling. Preserve the three accepted suggestion commits and repair the invalid JSON introduced by the applied state.json suggestion. Refs: #1655 Generated-by: Codex (GPT-6) --- .typos.toml | 2 + .../setup_preflight/guides/pr-management.md | 15 ++------ tools/setup-preflight/tests/test_welcome.py | 2 +- .../case-meta.json | 0 .../expected.json | 0 .../case-11-pr-management-first-run/report.md | 37 +++++++++++++++++++ .../state.json | 6 +-- .../case-12-pr-management-first-run/report.md | 37 ------------------- 8 files changed, 46 insertions(+), 53 deletions(-) rename tools/skill-evals/evals/setup/preflight-floor/fixtures/{case-12-pr-management-first-run => case-11-pr-management-first-run}/case-meta.json (100%) rename tools/skill-evals/evals/setup/preflight-floor/fixtures/{case-12-pr-management-first-run => case-11-pr-management-first-run}/expected.json (100%) create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/report.md rename tools/skill-evals/evals/setup/preflight-floor/fixtures/{case-12-pr-management-first-run => case-11-pr-management-first-run}/state.json (74%) delete mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/report.md diff --git a/.typos.toml b/.typos.toml index d297490a5..e390cb435 100644 --- a/.typos.toml +++ b/.typos.toml @@ -40,6 +40,8 @@ extend-ignore-re = [ "`[0-9a-f]{7,40}`", "surface_hash: sha256:[0-9a-f]+", + # Fixture state stores the invoking skill's generated surface digest as JSON. + '"hash": "sha256:[0-9a-f]+"', "FRAMEWORK_FINGERPRINT = \"sha256:[0-9a-f]+\"", ] diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md index 63616bd05..d2e0cd107 100644 --- a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md +++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md @@ -5,7 +5,7 @@ A one-minute tour, then straight back to what you asked for. -## Configure it +## ⚙️ Configure it Start with ``, the project's review criteria and its area labels. `pr-management-code-review-criteria.md` names the criteria sources; @@ -21,7 +21,7 @@ Optional companion: roborev reviews your own branch before it becomes a PR; this family helps you review and manage other people's PRs. Neither requires the other. -## The typical flow +## 🔄 The typical flow 1. **Triage the queue** — propose a disposition for each PR — *"triage the open PRs"* 2. **Route reviewers** — use the roster to suggest the right people — *"who should review this PR?"* @@ -34,15 +34,8 @@ Neither requires the other. Nothing is written, posted, labelled or closed without your explicit confirmation. Quick-merge never merges for you: it hands you the command. -## Just ask +## 💬 Just ask -Plain language works: - -- *"check my branch before I open my first PR"* -- *"triage the PRs waiting for review"* -- *"review this PR stack in dependency order"* -- *"draft a review, but do not post it"* -- *"help this contributor understand the requested change"* - *"check my branch before I open my first PR"* - *"triage the PRs waiting for review"* - *"who should review this PR?"* @@ -53,7 +46,7 @@ Plain language works: - *"what changed in the queue since the last sweep?"* - *"summarise the PR backlog by area"* -## Make it yours +## 🎨 Make it yours Change a workflow by describing the change: diff --git a/tools/setup-preflight/tests/test_welcome.py b/tools/setup-preflight/tests/test_welcome.py index f3c72e1d1..8e07f8d6a 100644 --- a/tools/setup-preflight/tests/test_welcome.py +++ b/tools/setup-preflight/tests/test_welcome.py @@ -390,7 +390,7 @@ def test_show_without_color_prints_the_markdown(capsys) -> None: # --- what ships ----------------------------------------------------------------------- -def test_the_rules_section_and_both_guides_ship() -> None: +def test_the_rules_section_and_all_guides_ship() -> None: assert welcome.SECTION in sections.available() assert {"general", "pr-management", "security", "utilities"} <= set(welcome.guides()) assert welcome.family_guides() == [g for g in welcome.guides() if g != "general"] diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/case-meta.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/case-meta.json similarity index 100% rename from tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/case-meta.json rename to tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/case-meta.json diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/expected.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/expected.json similarity index 100% rename from tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/expected.json rename to tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/expected.json diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/report.md new file mode 100644 index 000000000..379b05fa4 --- /dev/null +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/report.md @@ -0,0 +1,37 @@ + + +There is no `.apache-magpie.lock`, no `.apache-magpie-overrides/` and no +`.apache-magpie-local/` at the repo root. The running agent is Claude Code +with magpie-setup 0.4.0 and magpie-pr-management 0.4.0 installed. + +The user has already seen the initial general welcome guide on an earlier run. +The invoked skill's own frontmatter reads `name: pr-triage` and +`surface_hash: sha256:54dc4ba1be7b36d4`; it belongs to the pr-management family. +This is the first time a pr-management skill has run here. +The user asked it to "triage the open PRs". + +The pre-flight command printed: + +```json +{ + "findings": [ + { + "code": "welcome", + "facts": { + "family": "pr-management", + "guide": "# \ud83d\udc26 Magpie here \u2014 your PR-management sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \u2699\ufe0f Configure it\n\nStart with ``, the project's review criteria and its area labels.\n`pr-management-code-review-criteria.md` names the criteria sources;\n`pr-management-config.md` carries the labels and queue rules.\n`reviewer-roster.md` tells reviewer routing who covers each area.\n\n- **Installed** \u2014 just for you: personal configuration, nothing committed \u2014 `/magpie-setup:setup config`\n- **Adopted** \u2014 for your project: shared configuration committed to the repo \u2014 `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install, use `/magpie-setup config` or `/magpie-setup adopt`.\n\nOptional companion: roborev reviews your own branch before it becomes a PR;\nthis family helps you review and manage other people's PRs.\nNeither requires the other.\n\n## \ud83d\udd04 The typical flow\n\n1. **Triage the queue** \u2014 propose a disposition for each PR \u2014 *\"triage the open PRs\"*\n2. **Route reviewers** \u2014 use the roster to suggest the right people \u2014 *\"who should review this PR?\"*\n3. **Review** \u2014 inspect the diff and draft inline feedback \u2014 *\"review this PR against our criteria\"*\n4. **Quick-merge** \u2014 screen easy candidates and propose the command for you to run \u2014 *\"which PRs are ready for quick-merge?\"*\n5. **Mentor** \u2014 help a contributor through the next step \u2014 *\"draft helpful feedback for this contributor\"*\n6. **Stale sweep** \u2014 propose follow-ups for inactive PRs \u2014 *\"show me the stale PRs\"*\n7. **Stats** \u2014 see where the queue needs attention \u2014 *\"summarise the PR backlog by area\"*\n\nNothing is written, posted, labelled or closed without your explicit confirmation.\nQuick-merge never merges for you: it hands you the command.\n\n## \ud83d\udcac Just ask\n\n- *\"check my branch before I open my first PR\"*\n- *\"triage the PRs waiting for review\"*\n- *\"who should review this PR?\"*\n- *\"review this PR against our criteria\"*\n- *\"review this PR stack in dependency order\"*\n- *\"which PRs are ready for quick-merge?\"*\n- *\"help this contributor understand the requested change\"*\n- *\"what changed in the queue since the last sweep?\"*\n- *\"summarise the PR backlog by area\"*\n\n## \ud83c\udfa8 Make it yours\n\nChange a workflow by describing the change:\n\n- *\"from now on, group the backlog by our area labels\"*\n- *\"use our review criteria when drafting feedback\"*\n\nEach becomes an override for the PR-management skill it changes.\nUseful to other maintainers? *\"Upstream this change to Magpie\"* prepares a generic PR for you to review before it opens.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the pr-management welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide pr-management`\n(`/magpie-setup-welcome-guide pr-management` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family pr-management --color=always\n```\n", + "max_shown": 3, + "reason": "first-run", + "shown": 0 + }, + "scope": "family", + "section": "welcome" + } + ], + "rules": { + "welcome": "## welcome \u2014 a first-run welcome guide is due\n\nA welcome guide is due on this run: `facts.family` names it\n(`general`, for the first Magpie skill this user runs here, or the skill's own family),\nand `facts.reason` says why (`first-run`, `again`, or `upgraded` after a dismissal).\n`facts.guide` is the guide. The checker shows at most one guide per run and has already picked it.\n\n1. **Show `facts.guide` to the user verbatim**, as Markdown, before the work they asked for.\n Do not summarise, reword, trim, or add to it, and substitute nothing in it:\n its placeholders (``, ``, ``, \u2026) are meant to be read as written.\n2. **Offer the three choices in one line**:\n **Continue** (show again next time) \u00b7 **Dismiss** (hide until the next Magpie upgrade) \u00b7 **Don't show again**.\n3. **Record `seen` at once**, which is what no answer means, then carry on with the user's request in the same turn.\n Never block the requested work on the guide, and never wait for an answer before starting it.\n4. **When the user picks Dismiss or Don't show again** \u2014 now or later in the session \u2014 record that choice;\n it replaces `seen`. Continue needs nothing further.\n\n```bash\nPYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" \\\n python3 -m setup_preflight.welcome record --family --choice \n```\n\n`seen` brings the guide back on a later run, `facts.max_shown` recorded showings in all (`facts.shown` so far);\n`dismiss` hides it until the framework version changes; `never` hides it until re-enabled.\nEvery write merges into the personal layer's `reconciled.json` under `welcome.`, keeping every other key;\nnever write it by hand.\nIf the command exits non-zero, say nothing more about it and carry on.\n\nAny guide can be shown again on request with `/magpie-setup:welcome-guide []`,\nwhich also turns a hidden one back on." + }, + "verdict": "action" +} +``` diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/state.json similarity index 74% rename from tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json rename to tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/state.json index 64360a56d..92deb91c0 100644 --- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/state.json +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/state.json @@ -19,8 +19,6 @@ } }, "skill": "pr-triage", - "welcome": true - "hash": "sha256:54dc4ba1be7b36d4", - "skill": "pr-triage", - "welcome": true + "welcome": true, + "hash": "sha256:54dc4ba1be7b36d4" } diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/report.md deleted file mode 100644 index 306306acc..000000000 --- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-12-pr-management-first-run/report.md +++ /dev/null @@ -1,37 +0,0 @@ - - -There is no `.apache-magpie.lock`, no `.apache-magpie-overrides/` and no -`.apache-magpie-local/` at the repo root. The running agent is Claude Code -with magpie-setup 0.4.0 and magpie-pr-management 0.4.0 installed. - -The user has already seen the initial general welcome guide on an earlier run. -The invoked skill's own frontmatter reads `name: pr-triage` and -`surface_hash: sha256:2edc90a1b7f3440d`; it belongs to the pr-management family. -This is the first time a pr-management skill has run here. -The user asked it to "triage the open PRs". - -The pre-flight command printed: - -```json -{ - "findings": [ - { - "code": "welcome", - "facts": { - "family": "pr-management", - "guide": "# Magpie here \u2014 your PR-management sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## Configure it\n\nStart with ``, the project's review criteria and its area labels.\n`pr-management-code-review-criteria.md` names the criteria sources;\n`pr-management-config.md` carries the labels and queue rules.\n`reviewer-roster.md` tells reviewer routing who covers each area.\n\n- **Installed** \u2014 just for you: personal configuration, nothing committed \u2014 `/magpie-setup:setup config`\n- **Adopted** \u2014 for your project: shared configuration committed to the repo \u2014 `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install, use `/magpie-setup config` or `/magpie-setup adopt`.\n\nOptional companion: roborev reviews your own branch before it becomes a PR;\nthis family helps you review and manage other people's PRs.\nNeither requires the other.\n\n## The typical flow\n\n1. **Triage the queue** \u2014 propose a disposition for each PR \u2014 *\"triage the open PRs\"*\n2. **Route reviewers** \u2014 use the roster to suggest the right people \u2014 *\"who should review this PR?\"*\n3. **Review** \u2014 inspect the diff and draft inline feedback \u2014 *\"review this PR against our criteria\"*\n4. **Quick-merge** \u2014 screen easy candidates and propose the command for you to run \u2014 *\"which PRs are ready for quick-merge?\"*\n5. **Mentor** \u2014 help a contributor through the next step \u2014 *\"draft helpful feedback for this contributor\"*\n6. **Stale sweep** \u2014 propose follow-ups for inactive PRs \u2014 *\"show me the stale PRs\"*\n7. **Stats** \u2014 see where the queue needs attention \u2014 *\"summarise the PR backlog by area\"*\n\nNothing is written, posted, labelled or closed without your explicit confirmation.\nQuick-merge never merges for you: it hands you the command.\n\n## Just ask\n\nPlain language works:\n\n- *\"check my branch before I open my first PR\"*\n- *\"triage the PRs waiting for review\"*\n- *\"review this PR stack in dependency order\"*\n- *\"draft a review, but do not post it\"*\n- *\"help this contributor understand the requested change\"*\n- *\"what changed in the queue since the last sweep?\"*\n\n## Make it yours\n\nChange a workflow by describing the change:\n\n- *\"from now on, group the backlog by our area labels\"*\n- *\"use our review criteria when drafting feedback\"*\n\nEach becomes an override for the PR-management skill it changes.\nUseful to other maintainers? *\"Upstream this change to Magpie\"* prepares a generic PR for you to review before it opens.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the pr-management welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide pr-management`\n(`/magpie-setup-welcome-guide pr-management` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family pr-management --color=always\n```\n", - "max_shown": 3, - "reason": "first-run", - "shown": 0 - }, - "scope": "family", - "section": "welcome" - } - ], - "rules": { - "welcome": "## welcome \u2014 a first-run welcome guide is due\n\nA welcome guide is due on this run: `facts.family` names it\n(`general`, for the first Magpie skill this user runs here, or the skill's own family),\nand `facts.reason` says why (`first-run`, `again`, or `upgraded` after a dismissal).\n`facts.guide` is the guide. The checker shows at most one guide per run and has already picked it.\n\n1. **Show `facts.guide` to the user verbatim**, as Markdown, before the work they asked for.\n Do not summarise, reword, trim, or add to it, and substitute nothing in it:\n its placeholders (``, ``, ``, \u2026) are meant to be read as written.\n2. **Offer the three choices in one line**:\n **Continue** (show again next time) \u00b7 **Dismiss** (hide until the next Magpie upgrade) \u00b7 **Don't show again**.\n3. **Record `seen` at once**, which is what no answer means, then carry on with the user's request in the same turn.\n Never block the requested work on the guide, and never wait for an answer before starting it.\n4. **When the user picks Dismiss or Don't show again** \u2014 now or later in the session \u2014 record that choice;\n it replaces `seen`. Continue needs nothing further.\n\n```bash\nPYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" \\\n python3 -m setup_preflight.welcome record --family --choice \n```\n\n`seen` brings the guide back on a later run, `facts.max_shown` recorded showings in all (`facts.shown` so far);\n`dismiss` hides it until the framework version changes; `never` hides it until re-enabled.\nEvery write merges into the personal layer's `reconciled.json` under `welcome.`, keeping every other key;\nnever write it by hand.\nIf the command exits non-zero, say nothing more about it and carry on.\n\nAny guide can be shown again on request with `/magpie-setup:welcome-guide []`,\nwhich also turns a hidden one back on." - }, - "verdict": "action" -} -``` From 50e8af58e2df2757f0122a41ee0075ff02602b89 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Mon, 19 Oct 2026 21:55:09 +0200 Subject: [PATCH 6/6] docs(setup): pr-management guide configures, not installs; stable OTHER_SKILL `/magpie-setup:setup config` configures the skills already installed and installs nothing, so the guide's bullet now reads "Configure it for yourself" rather than "Installed". The welcome tests need a skill whose family ships no guide. Moving it to `activity-sweep` would break as soon as the contributor-growth guide lands, so it is `ci-runner-audit` (repo-health), a family with no guide in flight. The fixture that embeds the guide is re-rendered. Generated-by: Claude Opus 5 --- .../skills/setup/setup_preflight/guides/pr-management.md | 2 +- tools/setup-preflight/tests/test_welcome.py | 4 ++-- .../fixtures/case-11-pr-management-first-run/report.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md index d2e0cd107..5b0a85fd6 100644 --- a/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md +++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/pr-management.md @@ -12,7 +12,7 @@ Start with ``, the project's review criteria and its area labels. `pr-management-config.md` carries the labels and queue rules. `reviewer-roster.md` tells reviewer routing who covers each area. -- **Installed** — just for you: personal configuration, nothing committed — `/magpie-setup:setup config` +- **Configure it for yourself** — personal configuration, nothing committed — `/magpie-setup:setup config` - **Adopted** — for your project: shared configuration committed to the repo — `/magpie-setup:setup adopt` (a maintainers' decision) On a pinned-snapshot install, use `/magpie-setup config` or `/magpie-setup adopt`. diff --git a/tools/setup-preflight/tests/test_welcome.py b/tools/setup-preflight/tests/test_welcome.py index 8e07f8d6a..c551a68fb 100644 --- a/tools/setup-preflight/tests/test_welcome.py +++ b/tools/setup-preflight/tests/test_welcome.py @@ -34,7 +34,7 @@ REPO_ROOT = Path(__file__).resolve().parents[3] SECURITY_SKILL = "issue-sync" -OTHER_SKILL = "activity-sweep" +OTHER_SKILL = "ci-runner-audit" def stamp(root: Path) -> dict: @@ -118,7 +118,7 @@ def test_a_hidden_general_guide_does_not_hold_back_the_family_one(project: Path, def test_a_skill_of_a_family_without_a_guide_gets_only_the_general_one(project: Path, version) -> None: - assert welcome.family_of(OTHER_SKILL) == "contributor-growth" + assert welcome.family_of(OTHER_SKILL) == "repo-health" assert due(project, OTHER_SKILL) == [("general", "first-run")] welcome.record(project, "general", "never") assert due(project, OTHER_SKILL) == [] diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/report.md index 379b05fa4..bb0c73671 100644 --- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/report.md +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-11-pr-management-first-run/report.md @@ -20,7 +20,7 @@ The pre-flight command printed: "code": "welcome", "facts": { "family": "pr-management", - "guide": "# \ud83d\udc26 Magpie here \u2014 your PR-management sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \u2699\ufe0f Configure it\n\nStart with ``, the project's review criteria and its area labels.\n`pr-management-code-review-criteria.md` names the criteria sources;\n`pr-management-config.md` carries the labels and queue rules.\n`reviewer-roster.md` tells reviewer routing who covers each area.\n\n- **Installed** \u2014 just for you: personal configuration, nothing committed \u2014 `/magpie-setup:setup config`\n- **Adopted** \u2014 for your project: shared configuration committed to the repo \u2014 `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install, use `/magpie-setup config` or `/magpie-setup adopt`.\n\nOptional companion: roborev reviews your own branch before it becomes a PR;\nthis family helps you review and manage other people's PRs.\nNeither requires the other.\n\n## \ud83d\udd04 The typical flow\n\n1. **Triage the queue** \u2014 propose a disposition for each PR \u2014 *\"triage the open PRs\"*\n2. **Route reviewers** \u2014 use the roster to suggest the right people \u2014 *\"who should review this PR?\"*\n3. **Review** \u2014 inspect the diff and draft inline feedback \u2014 *\"review this PR against our criteria\"*\n4. **Quick-merge** \u2014 screen easy candidates and propose the command for you to run \u2014 *\"which PRs are ready for quick-merge?\"*\n5. **Mentor** \u2014 help a contributor through the next step \u2014 *\"draft helpful feedback for this contributor\"*\n6. **Stale sweep** \u2014 propose follow-ups for inactive PRs \u2014 *\"show me the stale PRs\"*\n7. **Stats** \u2014 see where the queue needs attention \u2014 *\"summarise the PR backlog by area\"*\n\nNothing is written, posted, labelled or closed without your explicit confirmation.\nQuick-merge never merges for you: it hands you the command.\n\n## \ud83d\udcac Just ask\n\n- *\"check my branch before I open my first PR\"*\n- *\"triage the PRs waiting for review\"*\n- *\"who should review this PR?\"*\n- *\"review this PR against our criteria\"*\n- *\"review this PR stack in dependency order\"*\n- *\"which PRs are ready for quick-merge?\"*\n- *\"help this contributor understand the requested change\"*\n- *\"what changed in the queue since the last sweep?\"*\n- *\"summarise the PR backlog by area\"*\n\n## \ud83c\udfa8 Make it yours\n\nChange a workflow by describing the change:\n\n- *\"from now on, group the backlog by our area labels\"*\n- *\"use our review criteria when drafting feedback\"*\n\nEach becomes an override for the PR-management skill it changes.\nUseful to other maintainers? *\"Upstream this change to Magpie\"* prepares a generic PR for you to review before it opens.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the pr-management welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide pr-management`\n(`/magpie-setup-welcome-guide pr-management` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family pr-management --color=always\n```\n", + "guide": "# \ud83d\udc26 Magpie here \u2014 your PR-management sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \u2699\ufe0f Configure it\n\nStart with ``, the project's review criteria and its area labels.\n`pr-management-code-review-criteria.md` names the criteria sources;\n`pr-management-config.md` carries the labels and queue rules.\n`reviewer-roster.md` tells reviewer routing who covers each area.\n\n- **Configure it for yourself** \u2014 personal configuration, nothing committed \u2014 `/magpie-setup:setup config`\n- **Adopted** \u2014 for your project: shared configuration committed to the repo \u2014 `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install, use `/magpie-setup config` or `/magpie-setup adopt`.\n\nOptional companion: roborev reviews your own branch before it becomes a PR;\nthis family helps you review and manage other people's PRs.\nNeither requires the other.\n\n## \ud83d\udd04 The typical flow\n\n1. **Triage the queue** \u2014 propose a disposition for each PR \u2014 *\"triage the open PRs\"*\n2. **Route reviewers** \u2014 use the roster to suggest the right people \u2014 *\"who should review this PR?\"*\n3. **Review** \u2014 inspect the diff and draft inline feedback \u2014 *\"review this PR against our criteria\"*\n4. **Quick-merge** \u2014 screen easy candidates and propose the command for you to run \u2014 *\"which PRs are ready for quick-merge?\"*\n5. **Mentor** \u2014 help a contributor through the next step \u2014 *\"draft helpful feedback for this contributor\"*\n6. **Stale sweep** \u2014 propose follow-ups for inactive PRs \u2014 *\"show me the stale PRs\"*\n7. **Stats** \u2014 see where the queue needs attention \u2014 *\"summarise the PR backlog by area\"*\n\nNothing is written, posted, labelled or closed without your explicit confirmation.\nQuick-merge never merges for you: it hands you the command.\n\n## \ud83d\udcac Just ask\n\n- *\"check my branch before I open my first PR\"*\n- *\"triage the PRs waiting for review\"*\n- *\"who should review this PR?\"*\n- *\"review this PR against our criteria\"*\n- *\"review this PR stack in dependency order\"*\n- *\"which PRs are ready for quick-merge?\"*\n- *\"help this contributor understand the requested change\"*\n- *\"what changed in the queue since the last sweep?\"*\n- *\"summarise the PR backlog by area\"*\n\n## \ud83c\udfa8 Make it yours\n\nChange a workflow by describing the change:\n\n- *\"from now on, group the backlog by our area labels\"*\n- *\"use our review criteria when drafting feedback\"*\n\nEach becomes an override for the PR-management skill it changes.\nUseful to other maintainers? *\"Upstream this change to Magpie\"* prepares a generic PR for you to review before it opens.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the pr-management welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide pr-management`\n(`/magpie-setup-welcome-guide pr-management` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family pr-management --color=always\n```\n", "max_shown": 3, "reason": "first-run", "shown": 0