From patinaproject-skills
Find deepening opportunities scoped to the current branch's changes and the radius that can fold into them, delivered as in-conversation markdown. Use when the user wants an architecture review of this branch or current changes, wants to deepen shallow modules before finishing a PR, or says "improve the architecture of my branch / current changes". For a whole-codebase audit, use improve-codebase-architecture instead.
How this skill is triggered — by the user, by Claude, or both
Slash command
/patinaproject-skills:improve-branch-architectureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones — scoped to **the current branch's changes** and the radius that can reasonably fold into this branch. The aim is testability and AI-navigability.
Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones — scoped to the current branch's changes and the radius that can reasonably fold into this branch. The aim is testability and AI-navigability.
This skill is the branch-scoped sibling of improve-codebase-architecture. It runs that skill's entire approach — the same three phases, the same vocabulary, the same deepening discipline, the same inline CONTEXT.md/ADR side effects — changed in exactly two ways:
For a whole-codebase audit, use improve-codebase-architecture. For a correctness/bug review of the branch, use review-code.
Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in LANGUAGE.md.
Key principles (see LANGUAGE.md for the full list):
This skill is informed by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
Read the project's domain glossary (CONTEXT.md, if any) and any ADRs in docs/adr/ for the area you're touching first, so recommendations use the project's domain language and do not re-litigate recorded decisions.
Resolve branch scope exactly as review-code does:
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name or git rev-parse --abbrev-ref origin/HEAD, stripping any leading origin/.git merge-base origin/<default-branch> HEAD.HEAD, plus staged, unstaged, and untracked changes. Include deleted files.Then use the Agent tool with subagent_type=Explore to walk the change set and gather context. The exploration is bounded by the branch, but you must read past the diff hunks to judge architecture honestly:
Degrade to running inline if subagents are unavailable. This is an advisory skill, not a hard gate — do not halt when no Explore subagent surface exists.
Explore organically and note where you experience friction:
Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
The candidate filter is "anything foldable into this branch." Surface friction whose fix could plausibly ride along in this branch:
Bound recommendations by keeping the change set reasonable — do not hand the contributor a sprawling refactor of unrelated, unchanged code. That is the job of improve-codebase-architecture.
Present candidates directly in the conversation as markdown cards. Write no HTML file and open nothing. Markdown renders in any surface, including a terminal where HTML and Mermaid do not.
For each candidate, a card with these fields:
Strong, Worth exploring, Speculative.End with a Top recommendation: which candidate to tackle first and why.
Use CONTEXT.md vocabulary for the domain, and LANGUAGE.md vocabulary for the architecture. If CONTEXT.md defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. "contradicts ADR-0007 — but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.
Do NOT propose interfaces yet. After presenting the cards, ask the user: "Which of these would you like to explore?"
Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
Classify the candidate's dependencies (in-process, local-substitutable, remote-but-owned, true-external) and recommend the matching seam/adapter/testing strategy so the deepened module is testable through its interface. See DEEPENING.md.
Side effects happen inline as decisions crystallize:
CONTEXT.md? Add the term to CONTEXT.md using CONTEXT-FORMAT.md. Create the file lazily if it doesn't exist.CONTEXT.md right there.docs/adr/README.md), follow the repo over the default in ADR-FORMAT.md.This skill mirrors the improve-codebase-architecture and grill-with-docs skills in mattpocock/skills. Its bundled reference files are copied verbatim from those skills:
improve-codebase-architecture.grill-with-docs.The parent's HTML-REPORT.md is intentionally not copied — this skill emits in-conversation markdown, never HTML.
npx claudepluginhub patinaproject/skills --plugin patinaproject-skillsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.