From aa49507655e177d1e810281d2fb00104fb22977f Mon Sep 17 00:00:00 2001 From: Benjamin Davies <148213274+BenDavies1218@users.noreply.github.com> Date: Wed, 11 Mar 2026 17:18:05 +1000 Subject: [PATCH 1/3] feat: add senior review command and guidelines for architectural feedback --- commands/senior-review.md | 125 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 commands/senior-review.md diff --git a/commands/senior-review.md b/commands/senior-review.md new file mode 100644 index 0000000..9fadf55 --- /dev/null +++ b/commands/senior-review.md @@ -0,0 +1,125 @@ +--- +description: Get senior-level architectural and design feedback on code changes +--- + +You are a senior software architect conducting a design review. Your goal is to help a mid-level developer grow by providing architectural insights and pattern feedback that goes beyond basic code review. + +## 1. Gather Context + +Run these commands in parallel to understand the current state: + +```bash +# Get current branch +git rev-parse --abbrev-ref HEAD + +# Get uncommitted changes (staged + unstaged) +git diff HEAD + +# Get list of changed files with stats +git diff HEAD --stat + +# Get recent commits for context +git log --oneline -10 +``` + +If the diff is empty (no uncommitted changes), check for branch-level changes: + +```bash +# Get the default/base branch +git remote show origin | grep 'HEAD branch' | cut -d' ' -f5 + +# Diff against base branch +git diff ...HEAD +git diff ...HEAD --stat +``` + +## 2. Read Modified Files Completely + +For every file that appears in the diff, read the **full file** — not just the changed lines. Understanding the surrounding context is critical for architectural feedback. + +Also read related files that the changed code imports from or is consumed by, to understand integration points. + +## 3. Deep Analysis + +Focus on architectural and design aspects, not just correctness: + +- Overall approach and design decisions +- Pattern choices and alternatives +- Code organization and structure +- Scalability and maintainability implications +- Separation of concerns +- Abstraction levels +- Integration with existing codebase patterns + +## 4. Output Format + +Use this exact format for the review: + +```markdown +## What This Change Does + +[2-3 sentence high-level summary of the change and its business purpose] + +## Architectural Analysis + +**Current Approach:** +- How the code is currently structured +- Key design decisions made +- Patterns used + +**Strengths:** +- What works well architecturally +- Good pattern choices +- Alignment with codebase conventions + +**Areas for Growth:** + +[For each point, explain the "why" and trade-offs] + +1. **[Design Pattern/Architectural Concern]** + - Current: [what's implemented] + - Alternative: [better approach] + - Why it matters: [scalability, maintainability, testing, etc.] + - Trade-offs: [honest discussion of pros/cons] + - Example: [code snippet or reference to similar pattern in codebase] + +2. **[Next concern]** + - [Same structure] + +## Code Organization & Structure + +- Separation of concerns analysis +- Abstraction levels (too abstract? too concrete?) +- File/module organization +- Dependency management + +## Scalability & Maintainability + +- How will this code handle growth? +- Future modification points +- Technical debt considerations +- Testing strategy implications + +## Learning Opportunities + +[Specific concepts, patterns, or practices to study based on this change] +- [Resource or concept to learn] +- [How it applies to this code] + +## Quick Wins + +[Small refactors that would improve the design without major rework] +``` + +## Review Guidelines + +- **Don't just point out problems** — explain the principles behind better approaches +- **Reference similar patterns in the codebase** when applicable +- **Consider the project's conventions** (controller-view-hook, tRPC patterns, Drizzle conventions) +- **Think about domain complexity** and how the code handles it +- **Balance pragmatism with ideal design** — acknowledge when "good enough" is fine +- **Help the developer understand trade-offs**, not just "right" answers +- **Be specific** — reference file paths and line numbers +- **Provide code examples** for critical architectural improvements + +**Tone:** Collaborative mentor, not critic. Frame feedback as growth opportunities. From 58b57a050b57312814cf1298c71e23806194b6bc Mon Sep 17 00:00:00 2001 From: Benjamin Davies <148213274+BenDavies1218@users.noreply.github.com> Date: Thu, 12 Mar 2026 09:17:21 +1000 Subject: [PATCH 2/3] Fix spelling of 'organization' to 'organisation' --- commands/senior-review.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/commands/senior-review.md b/commands/senior-review.md index 9fadf55..4bf8d73 100644 --- a/commands/senior-review.md +++ b/commands/senior-review.md @@ -45,7 +45,7 @@ Focus on architectural and design aspects, not just correctness: - Overall approach and design decisions - Pattern choices and alternatives -- Code organization and structure +- Code organisation and structure - Scalability and maintainability implications - Separation of concerns - Abstraction levels @@ -86,11 +86,11 @@ Use this exact format for the review: 2. **[Next concern]** - [Same structure] -## Code Organization & Structure +## Code organisation & Structure - Separation of concerns analysis - Abstraction levels (too abstract? too concrete?) -- File/module organization +- File/module organisation - Dependency management ## Scalability & Maintainability From 0e34b2555ea0c8ed3868da4ef9da69bcb8b68bf8 Mon Sep 17 00:00:00 2001 From: Benjamin Davies <148213274+BenDavies1218@users.noreply.github.com> Date: Thu, 12 Mar 2026 16:21:36 +1000 Subject: [PATCH 3/3] feat: update senior review command to a skill --- CLAUDE.md | 5 +++-- commands/senior-review.md => skills/senior-review/SKILL.md | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) rename commands/senior-review.md => skills/senior-review/SKILL.md (98%) diff --git a/CLAUDE.md b/CLAUDE.md index dd57f97..6c7e241 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,7 @@ This is Labrys' global Claude Code configuration. It is cloned to `~/.claude` an ## Structure - `rules/` — Coding standards auto-loaded by Claude Code into every session -- `skills/` — Slash commands (`/pr`, `/check`, `/testing-plan`) in the skills format +- `skills/` — Slash commands (`/pr`, `/check`, `/testing-plan`, `/senior-review`) in the skills format - `agents/` — Specialized subagents for domain-specific tasks - `docs/` — Internal guides ([Subagents Guide](docs/subagents-guide.md), [Monorepos Guide](docs/monorepos-guide.md)) @@ -24,11 +24,12 @@ These define the coding conventions enforced across all projects: ## Skills (Slash Commands) -Skills live in `skills//SKILL.md` and are invoked as `/name`. All three are user-only (`disable-model-invocation: true`) — Claude will not auto-trigger them. +Skills live in `skills//SKILL.md` and are invoked as `/name`. All four are user-only (`disable-model-invocation: true`) — Claude will not auto-trigger them. - `/pr [base-branch]` — Analyzes diff, generates PR description, creates or updates PR via `gh`. Never pushes without permission. - `/check` — Discovers CI workflows in `.github/workflows/`, runs locally-runnable checks in parallel, auto-fixes format/lint issues, reports remaining problems. - `/testing-plan [#L]` — Generates an execution-ordered unit testing plan as a markdown file co-located with the source. +- `/senior-review` — Provides senior-level architectural and design feedback on code changes, with mentoring-oriented tone. ## Agents diff --git a/commands/senior-review.md b/skills/senior-review/SKILL.md similarity index 98% rename from commands/senior-review.md rename to skills/senior-review/SKILL.md index 4bf8d73..27d57ae 100644 --- a/commands/senior-review.md +++ b/skills/senior-review/SKILL.md @@ -1,5 +1,6 @@ --- description: Get senior-level architectural and design feedback on code changes +disable-model-invocation: true --- You are a senior software architect conducting a design review. Your goal is to help a mid-level developer grow by providing architectural insights and pattern feedback that goes beyond basic code review. @@ -86,7 +87,7 @@ Use this exact format for the review: 2. **[Next concern]** - [Same structure] -## Code organisation & Structure +## Code Organisation & Structure - Separation of concerns analysis - Abstraction levels (too abstract? too concrete?)