Add polymorphic-parent-resources skill

[OutlawAndy]

Ships a skill for Rolemodel::ResourceFor::ControllerExtension, added to rolemodel_rails in 2.4.0 (#205), so the pattern gets found and adopted instead of sitting in a gem README.

Why cross-links, not just a new skill

The discovery problem is that nobody searches for resource_for — they have never heard of it. Two existing skills are where developers and agents already are when they hit this problem, and both currently point the wrong way:

• routing-patterns already taught the route concern (commentable_type: parent_resource.name.classify) and then stopped at "Controllers can access these via params[:commentable_type]." It taught you to pass the parent type and never said what to do with it. That dead end now points at the controller half.
• controller-patterns actively taught the thing this replaces. Its decision tree routed "Nested under parent resource? → Nested RESTful Controller Pattern", and the example hard-codes Order.find(params[:order_id]) with no note about multiple parents. An agent following it faithfully generates exactly the per-parent duplication the pattern exists to remove.

grep -r "resource_for\|rolemodel_rails" skills/ returned zero hits across all 26 skills before this PR.

What's here

New skill — skills/polymorphic-parent-resources/ (SKILL.md at 195 lines, under the repo's ~200 convention):

• Models → routing → controller → views, with the only:/except: split under shallow nesting
• The rolemodel_rails >= 2.4.0 gate, with bundle info plus a runtime check, and a temporary local concern for projects pinned to an older version
• The type allowlist for cases where a *_type arrives from user input rather than a route default
• A symptom → cause → fix gotchas table
• references/retrofit.md — audit commands, consolidation order (one parent at a time), and verification for apps that already have duplicated per-parent controllers

Cross-links — routing-patterns (dead-end bullet replaced, shallow caveat, checklist item), controller-patterns (decision-tree branch, two Common Mistakes rows, warning on the Nested Resource example, Agent Instructions branch, review checkbox), plus README.md and AGENTS.md listings and the "How skills work together" section.

A routing trap worth a look

Verifying the gem README's own example turned up something it does not document. Applying a concern with member actions to several parents under shallow draws /comments/:id once per parent, and Rails keeps only the first route's name:

name="comment" defaults={commentable_type: "Widget", ...}
name=nil       defaults={commentable_type: "Estimate", ...}   # unreachable

GET /comments/7 -> {commentable_type: "Widget", id: "7"}       # always Widget

So on member actions params[:commentable_type] is present but is always the first-drawn parent, whatever the record's real parent is. That makes scoping the parent before_action to collection actions load-bearing for correctness — the failure mode is either a silent wrong-parent read or a confusing 404 from find(nil), not just an untidy callback. Both the new skill and routing-patterns document it.

The gem README currently explains the split as "member actions carry no parent id," which is true but undersells it. Happy to open a follow-up there if you agree it's worth restating.

Review notes

• Frontmatter validated as parseable YAML across every skill in the repo (an earlier draft had a : inside the plain-scalar description, which would have made the skill fail to load).
• MD013 line-length warnings from markdownlint-cli2 defaults are untouched baseline — the repo has no markdownlint config and existing skills violate it identically.
• Pre-existing and left alone: the README table lists testing-patterns, but the directory is skills/tdd/.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new Rails skill documenting the “polymorphic parent resources” pattern (route concern + resource_for) and updates existing routing/controller skills and repository indexes to reference it.

Changes:

• Introduces polymorphic-parent-resources skill docs plus a retrofit guide for consolidating per-parent controllers.
• Updates routing-patterns and controller-patterns to call out the pattern and the shallow-member-route *_type default trap.
• Adds the new skill to README.md and AGENTS.md.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
skills/routing-patterns/SKILL.md	Adds guidance linking route *_type defaults to the controller-side resource_for pattern and documents a shallow routing caveat.
skills/polymorphic-parent-resources/references/retrofit.md	New retrofit guide with audit/consolidation steps and verification commands.
skills/polymorphic-parent-resources/SKILL.md	New skill documenting the end-to-end pattern, prerequisites, gotchas, and controller template.
skills/controller-patterns/SKILL.md	Updates decision tree/checklists to steer multi-parent child resources to the new skill.
README.md	Adds the new skill to the skills list and cross-skill recommendations.
AGENTS.md	Adds the new skill to the Rails Backend agent list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (4)

skills/polymorphic-parent-resources/SKILL.md:118

• :unprocessable_content is not a valid Rails status symbol for 422 responses; Rails uses :unprocessable_entity. As written, this example will raise (or send an unintended status) in many Rails versions. Update the snippet to use status: :unprocessable_entity (or status: 422).

      render :new, status: :unprocessable_content

skills/polymorphic-parent-resources/references/retrofit.md:42

• These grep commands rely on \\| alternation without enabling extended regex, which is not portable (notably on BSD/macOS grep). Use grep -E (or a single regex like resources :(comments|generated_reports|duplications) / (_comments_path|_comment_path)) so the commands work consistently across environments.

grep -n 'resources :comments\|resources :generated_reports\|resources :duplications' config/routes.rb

skills/polymorphic-parent-resources/references/retrofit.md:112

• These grep commands rely on \\| alternation without enabling extended regex, which is not portable (notably on BSD/macOS grep). Use grep -E (or a single regex like resources :(comments|generated_reports|duplications) / (_comments_path|_comment_path)) so the commands work consistently across environments.

grep -rn '_comments_path\|_comment_path' app spec | grep -v 'polymorphic'

skills/routing-patterns/SKILL.md:57

• The new lines change list structure/formatting: the prior controller note was nested under the custom-parameters bullet, but line 55 is now a top-level item and line 57 breaks out of the list entirely. If this section is intended to keep the controller guidance tied to the metadata bullet, consider nesting line 55 (and optionally the 'Read...' note) under line 54, or format the note as a consistent callout (e.g., blockquote) to avoid accidental outline breakage.

- Use `parent_resource.name.classify` to dynamically pass the parent context type to controllers
- Specify `only:` or `except:` to limit actions when appropriate
- Custom parameters (like `commentable_type`, `resource_type`) are passed as metadata to controllers
- Controllers turn that metadata back into the parent record with `resource_for(:commentable_type)`, provided by the `rolemodel_rails` gem (>= 2.4.0)

**Read the `polymorphic-parent-resources` skill before writing the controller.** Passing a `*_type` default is only half the pattern — that skill covers the controller side, the required `before_action` scoping under shallow nesting (member routes inherit the wrong `*_type`), and how to consolidate existing per-parent controllers.