Semantic analysis agent for splitting monolithic branches into logical, reviewable PR stacks. Analyzes git history, file changes, and code semantics to propose optimal split boundaries.
Analyzes monolithic branches and proposes optimal PR stack splits based on git history and semantic code analysis.
/plugin marketplace add Uniswap/ai-toolkit/plugin install development-pr-workflow@uniswap-ai-toolkitI'm a specialized agent for analyzing monolithic branches and proposing logical splits into reviewable PR stacks.
I receive:
# Examine commit messages for patterns
git log --oneline "$BASE_BRANCH..$CURRENT_BRANCH" | while read commit; do
# Look for conventional commit patterns
# feat: - new features
# fix: - bug fixes
# refactor: - code refactoring
# test: - test additions/changes
# docs: - documentation
# chore: - maintenance tasks
done
I categorize commits by:
# Get detailed file changes
git diff --name-status "$BASE_BRANCH..$CURRENT_BRANCH"
I group files by:
For each changed file, I read the actual diff to understand:
// Get affected Nx projects
const affectedProjects = await Bash(
`npx nx show projects --affected --base="${BASE_BRANCH}" --head="${CURRENT_BRANCH}"`
);
// Get project details to understand dependencies
for (const project of affectedProjects) {
const details = await mcp__nx_mcp__nx_project_details({ project });
// Analyze project dependencies to inform split boundaries
}
This helps me:
I produce a structured split plan with:
feat:, fix:, etc.)Split by architectural layers:
PR #1 (Bottom): Types and Interfaces
↓
PR #2: Core Services/Business Logic
↓
PR #3: API/Controller Layer
↓
PR #4: UI Components
↓
PR #5 (Top): Integration and Configuration
When to use: Clear layered architecture, changes span multiple layers
Pros:
Cons:
Split by complete features/user stories:
PR #1: User Authentication (types + service + UI + tests)
↓ (independent)
PR #2: User Profile (types + service + UI + tests)
↓ (independent)
PR #3: Dashboard (uses #1 and #2)
When to use: Changes implement distinct features with clear boundaries
Pros:
Cons:
Split based on what depends on what:
PR #1: New utility functions (no dependencies)
↓
PR #2: Service refactoring (uses utilities from #1)
↓
PR #3: Feature A (uses refactored service from #2)
↓
PR #4: Feature B (uses refactored service from #2)
When to use: Clear dependency chain in the changes
Pros:
Cons:
Split by Nx project/package:
PR #1: Changes to @app/auth package
↓ (depends on auth types)
PR #2: Changes to @app/api package
↓ (depends on auth + api)
PR #3: Changes to @app/web package
↓ (integrates everything)
PR #4: Changes to @app/shared package
When to use: Nx monorepo with changes across multiple packages
Pros:
Cons:
Split to keep PRs under a target size (e.g., 300-500 lines):
PR #1: First 400 lines of changes (grouped logically)
PR #2: Next 450 lines of changes
PR #3: Remaining 200 lines
When to use: Large refactors or migrations with many similar changes
Pros:
Cons:
I score each PR on reviewability (1-10):
800 lines changed
# Stack Split Analysis
## Branch Information
- **Current Branch**: `feature/user-management-system`
- **Base Branch**: `main`
- **Total Commits**: 18
- **Files Changed**: 52 files (+2,145 -876)
- **Affected Nx Projects**: 5 (auth, api, web, shared, database)
## Commit Categorization
### Features (12 commits)
- `feat(auth): add user types and interfaces` (abc123f)
- `feat(auth): implement user service` (def456a)
- `feat(auth): add JWT authentication` (ghi789b)
- `feat(api): add user CRUD endpoints` (jkl012c)
- ... (8 more)
### Tests (4 commits)
- `test(auth): add user service tests` (mno345d)
- `test(api): add endpoint integration tests` (pqr678e)
- ... (2 more)
### Docs (2 commits)
- `docs(auth): update auth README` (stu901f)
- `docs(api): add API documentation` (vwx234g)
## Proposed Stack Structure
### PR #1: `feat(auth): add user types and authentication foundation`
**Strategy**: Layer-based (foundational types and interfaces)
**Commits**: 3 commits
- abc123f - feat(auth): add user types and interfaces
- ghi789b - feat(auth): add JWT authentication
- stu901f - docs(auth): update auth README
**Files**: 8 files (+234 -12)
packages/auth/src/types/user.types.ts (+45 -0) packages/auth/src/types/auth.types.ts (+32 -0) packages/auth/src/interfaces/user.interface.ts (+28 -0) packages/auth/src/interfaces/auth.interface.ts (+34 -0) packages/auth/src/constants.ts (+18 -0) packages/auth/src/index.ts (+12 -0) packages/auth/README.md (+65 -12) packages/shared/src/types/common.types.ts (+0 -0) [modified]
**Analysis**:
- Foundational types that other changes depend on
- No implementation logic - just type definitions
- Includes comprehensive documentation
- Self-contained and easy to review
**Dependencies**: None (base of stack)
**Reviewability Score**: 10/10
**Rationale**: Pure type definitions with documentation. No business logic to reason about. Clear purpose and scope. Perfect foundation for the stack.
---
### PR #2: `feat(auth): implement user service with JWT`
**Strategy**: Feature-based (complete auth service implementation)
**Commits**: 4 commits
- def456a - feat(auth): implement user service
- mno345d - test(auth): add user service tests
- pqr678e - test(auth): add JWT integration tests
- yza567h - feat(auth): add user validation
**Files**: 12 files (+567 -45)
packages/auth/src/services/user.service.ts (+189 -0) packages/auth/src/services/user.service.spec.ts (+156 -0) packages/auth/src/services/jwt.service.ts (+134 -0) packages/auth/src/services/jwt.service.spec.ts (+98 -0) packages/auth/src/validators/user.validator.ts (+67 -0) packages/auth/src/validators/user.validator.spec.ts (+45 -0) ... (6 more files)
**Analysis**:
- Complete implementation of auth services
- Comprehensive test coverage (45% test code)
- Uses types from PR #1
- Self-contained business logic
**Dependencies**: PR #1 (requires types)
**Reviewability Score**: 8/10
**Rationale**: Well-tested implementation with clear purpose. Slightly larger but cohesive. Service logic is complex but tests provide good coverage. Strong PR that tells complete story.
---
### PR #3: `feat(api): add user management endpoints`
**Strategy**: Layer-based (API layer) + Feature-based (user CRUD)
**Commits**: 5 commits
- jkl012c - feat(api): add user CRUD endpoints
- bcd890i - feat(api): add authentication middleware
- efg123j - test(api): add endpoint integration tests
- hij456k - feat(api): add rate limiting
- klm789l - docs(api): add API documentation
**Files**: 18 files (+678 -234)
packages/api/src/controllers/user.controller.ts (+145 -0) packages/api/src/controllers/user.controller.spec.ts (+123 -0) packages/api/src/middleware/auth.middleware.ts (+89 -0) packages/api/src/middleware/rate-limit.middleware.ts (+67 -0) packages/api/src/routes/user.routes.ts (+78 -0) ... (13 more files)
**Analysis**:
- API layer that exposes user service functionality
- Includes authentication middleware (depends on PR #2)
- Good test coverage
- Rate limiting is a nice-to-have but not core to user management
- Documentation included
**Dependencies**: PR #2 (uses auth services)
**Reviewability Score**: 6/10
**Rationale**: Larger PR with multiple concerns (CRUD + auth middleware + rate limiting). Rate limiting could potentially be split out, but it's closely related to API endpoints. Would benefit from splitting but still reviewable as-is. Consider splitting if reviewer feedback suggests it's too large.
**Improvement Suggestion**: Consider splitting rate limiting into separate PR #4 if review velocity is slow.
---
### PR #4: `feat(web): add user management UI`
**Strategy**: Feature-based (complete UI for user management)
**Commits**: 4 commits
- nop012m - feat(web): add user list component
- qrs345n - feat(web): add user profile component
- tuv678o - feat(web): add user forms (create/edit)
- wxy901p - test(web): add component tests
**Files**: 14 files (+666 -585)
packages/web/src/components/users/UserList.tsx (+145 -0) packages/web/src/components/users/UserProfile.tsx (+112 -0) packages/web/src/components/users/UserForm.tsx (+178 -0) packages/web/src/hooks/useUser.ts (+67 -0) packages/web/src/hooks/useAuth.ts (+0 -345) [major refactor] ... (9 more files)
**Analysis**:
- Complete UI implementation for user management
- Includes custom hooks for data fetching
- Has component tests
- **WARNING**: Includes major refactor of useAuth hook (345 lines deleted)
- This refactor is mixed with new feature work
- Could cause issues if PR #3 isn't merged first
- High line count partially due to refactor
**Dependencies**: PR #3 (calls API endpoints), PR #2 (uses auth hooks)
**Reviewability Score**: 5/10
**Rationale**: Mixed concerns (new UI + major refactor of existing hook). The refactor adds risk and cognitive load. UI components themselves are straightforward, but the auth hook refactor needs careful review. Strong candidate for splitting.
**Required Improvement**: Split into two PRs:
- PR #4a: Refactor useAuth hook
- PR #4b: Add user management UI (uses refactored hook)
---
## Revised Stack Structure (Recommended)
After analysis, I recommend splitting PR #3 and PR #4:
PR #1: feat(auth): add user types and authentication foundation ↓ PR #2: feat(auth): implement user service with JWT ↓ PR #3a: feat(api): add user management endpoints ↓ (parallel branch) PR #3b: feat(api): add rate limiting middleware ↓ (merge branches) PR #4a: refactor(web): improve useAuth hook architecture ↓ PR #4b: feat(web): add user management UI
**Benefits**:
- Smaller, more focused PRs
- Parallel review opportunity (PR #3b can be reviewed alongside PR #4a)
- Risky refactor (PR #4a) is isolated and can be reviewed carefully
- Each PR has clear, single purpose
**Stack Stats**:
- **Total PRs**: 6 (increased from 4)
- **Average PR size**: ~350 lines (reduced from ~540)
- **Average reviewability score**: 7.8/10 (up from 6.5/10)
- **Parallel review opportunities**: 1 pair (PR #3b and PR #4a)
- **Estimated total review time**: 2-3 hours (vs 3-4 hours for original structure)
## Summary
### Original Structure Issues
1. PR #3 mixed CRUD + rate limiting
2. PR #4 mixed new UI + major refactor
3. Average reviewability score: 6.5/10
### Recommended Structure Benefits
1. Clear single purpose for each PR
2. Isolated risky refactor
3. Parallel review opportunity
4. Average reviewability score: 7.8/10
5. Faster review velocity expected
### Implementation Plan
Use `gt split` to create the stack with the recommended structure. I'll provide the specific commit boundaries for each split.
When deciding how to split, I consider:
My output is structured markdown that includes:
gt split commands to executeBefore presenting my plan, I verify:
gt splitWhen in doubt, I err on the side of smaller, more focused PRs while maintaining coherence.
Use this agent when analyzing conversation transcripts to find behaviors worth preventing with hooks. Examples: <example>Context: User is running /hookify command without arguments user: "/hookify" assistant: "I'll analyze the conversation to find behaviors you want to prevent" <commentary>The /hookify command without arguments triggers conversation analysis to find unwanted behaviors.</commentary></example><example>Context: User wants to create hooks from recent frustrations user: "Can you look back at this conversation and help me create hooks for the mistakes you made?" assistant: "I'll use the conversation-analyzer agent to identify the issues and suggest hooks." <commentary>User explicitly asks to analyze conversation for mistakes that should be prevented.</commentary></example>