docs(projects): add Magpie's own pr-management-code-review criteria - #1042
Open
potiuk wants to merge 1 commit into
Open
docs(projects): add Magpie's own pr-management-code-review criteria#1042potiuk wants to merge 1 commit into
potiuk wants to merge 1 commit into
Conversation
`pr-management-code-review` resolves its rule sources from `<project-config>/pr-management-code-review-criteria.md`, but Magpie — which self-adopts the framework — never carried that file. Only `projects/_template/` had it, so running the skill against apache/magpie silently fell back to a smaller default rule set instead of the project's own rules. Found while running a review pass over the open-PR queue. This is a navigation map, not a rule set: every row points at a section that already exists in AGENTS.md, PRINCIPLES.md, CONTRIBUTING.md, or docs/editorial-guidelines.md, so the skill can quote the source rule verbatim. No rule text is duplicated and nothing moves out of AGENTS.md — per the framework's own guidance that summaries drift while links do not. Notable choices: - Architecture-boundary and generated-file findings route to the numbered PRINCIPLES entries (§12 project-agnosticism, §13 snapshot-plus-override) since that is where those rules live. - Categories that do not apply to this repository (database/query correctness, UI React/TypeScript) have no row: Magpie ships neither a database layer nor a UI, so a finding in either category would be a mis-classification rather than something to link. - A Magpie-specific block adds the categories this repo's reviews actually need — placeholder convention, external-content-as-data, privacy-LLM routing, labelling, vendor neutrality, and the inline-comment review default. - Backports are recorded as not applicable: Magpie releases from a single `main` and keeps no release-train branches. Every link and `#anchor` is verified — lychee and markdownlint pass, and the full `prek run --all-files` suite is green. Generated-by: Claude Code (Opus 5)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
pr-management-code-reviewresolves its rule sources from<project-config>/pr-management-code-review-criteria.md, but Magpie — which self-adopts the framework — never carried that file. Onlyprojects/_template/had it, so running the skill againstapache/magpiesilently fell back to a smaller default rule set instead of the project's own rules.projects/magpie/pr-management-code-review-criteria.mdas a navigation map, not a rule set: every row points at a section that already exists inAGENTS.md,PRINCIPLES.md,CONTRIBUTING.md, ordocs/editorial-guidelines.md. No rule text is duplicated and nothing moves out ofAGENTS.md— per the framework's own guidance that summaries drift while links don't.Type of change
.claude/skills/<name>/) — eval fixtures updated belowtools/<system>/*.md)tools/*/withpyproject.toml)docs/,README.md,CONTRIBUTING.md)projects/_template/)prek, workflows, validators)projects/magpie/(the live config, not the template)Test plan
prek run --all-filespassesuv run pytest/ruff check/mypypasses — no Python touched#anchorin the new file is verified by thelycheeandmarkdownlint(MD051) hooks — this was the main correctness risk, since the file is almost entirely cross-references intoAGENTS.mdandPRINCIPLES.mdanchors.RFC-AI-0004 compliance
Linked issues
None — the gap was found during a review session rather than reported. Happy to file a tracking issue retroactively if that's preferred.
Notes for reviewers (optional)
Three notes worth a second opinion:
Two canonical categories have no row.
Database / query correctnessandUI (React/TypeScript)don't apply — Magpie ships neither, so a finding in either would be a mis-classification rather than something to link. Worth knowing the trade-off:criteria.mdsays a category with no anchor row makes the skill "fall back to a plain reference and surface the missing anchor as a one-line warning at the top of the review". If that warning turns out to be noisy in practice, the fix belongs in the framework — the skill arguably shouldn't warn about categories an adopter has deliberately declined — rather than in this file.Navigation map vs. moving text out of
AGENTS.md. I read the intent as "point at the criteria that already exist" rather than "relocate them", since the template calls this file a navigation map andcriteria.mdexplicitly says to link rather than summarise.AGENTS.mdis unchanged. If you'd rather the review-specific rules physically moved here, that's a different (larger) refactor and I'd do it separately.Anchor targets for the vaguer categories.
Code quality→AGENTS.md#before-submittingandAPI correctness→AGENTS.md#reusable-skillsare the best fits I found, but they're the two I'm least sure about; Magpie has no standalone review-instructions doc to anchor into. Architecture-boundary and generated-file findings route to the numberedPRINCIPLESentries (§12, §13), which I'm confident about.Also adds a Magpie-specific anchor block for categories this repo's reviews actually need but the canonical list doesn't have: placeholder convention, external-content-as-data, privacy-LLM routing, labelling, vendor neutrality, and the inline-comment review default.