pr-split-advisor

Files (1)

• SKILL.md

SKILL.md (first lines)

# PR Split Advisor

Analyzes an approved implementation plan and recommends whether to keep work as a single PR or split into multiple PRs using vertical slices or stacked PRs.

## Configuration

Uses the **production API** by default. No configuration needed for read operations.

**Defaults (no setup required):**

- API URL: `https://api-gateway-856475788601.us-central1.run.app`
- Read-only endpoints at `/public/*` require no authentication

**For write operations** (state transitions), set:

```bash
export PIPELINE_API_KEY="..."  # Get from GCP Secret Manager or ask admin
```

## When to Use

- After `plan-generator` produces an approved `plan.md`
- When starting implementation of a multi-file change
- When asked "should I split this into multiple PRs?"
- Before creating branches/worktrees for implementation

## Workflow

### 0. Verify Pipeline Ticket Exists

Before proceeding, confirm a ticket exists in the pipeline API. If not, run `ticket-intake` first.

```typescript
const ticket = await client.getTicket(ticketId)
if (!ticket) {
  throw new Error('❌ No pipeline ticket found. Run ticket-intake first to register this ticket in the pipeline API.')
}
```

If no `ticketId` is available, search by Notion page ID or list recent tickets:

```typescript
const ticket = await client.findByNotionId(notionPageId)
if (!ticket) {
  console.error('❌ No pipeline ticket found for this Notion page. Run ticket-intake first.')
  process.exit(1)
}
const ticketId = ticket.id
```

### 1. Load and Parse the Plan

Fetch ticket context via the Pipeline API and extract plan details:

```typescript
import { PipelineClient } from '@pipeline/client'

const client = new PipelineClient({
  apiUrl: process.env.PIPELINE_API_URL || 'https://api-gateway-856475788601.us-central1.run.app',
  agentId: process.env.AGENT_ID,
})

const ticket = await client.getTicket(ticketId)
// Use ticket.plan for split analysis
```

From the plan, extract:

- Files to modify (with estimated LoC changes)
- Files to create (with estimated LoC)
- Layers touched (components, stores, utils, types, tests)
- Dependencies between changes

### 2. Analyze Scope

Calculate metrics:

| Metric              | How to Assess                                        |
| ------------------- | ---------------------------------------------------- |
| Total estimated LoC | Sum of all file estimates                            |
| File count          | Number of files affected                             |
| Layer count         | Distinct layers (component, store, util, type, test) |
| Coupling            | Can changes be tested independently?                 |

### 3. Apply Decision Rules

```
IF estimated LoC < 200:
  → Single PR (unless changes are completely unrelated)

IF estimated LoC 200-400 AND changes are tightly coupled:
  → Single PR (review burden is acceptable)

IF estimated LoC > 300 AND changes span multiple layers:
  → Consider splitting

IF changes have no dependencies on each other:
  → Vertical Slices (independent PRs, any merge order)

IF changes have logical dependencies (e.g., types → utils → components):
  → Stacked PRs (ordered merge using Graphite)
```

### 4. Generate Recommendation

Produce analysis in this format:

```markdown
# PR Split Analysis

## Scope Summary

- **Estimated LoC:** {number}
- **Files affected:** {count}
- **Layers touched:** {list}

## Recommendation: {Single PR / Vertical Slices / Stacked PRs}

### Rationale

From DrJKL/ticket-to-pr-pipeline, MIT.

More from DrJKL/ticket-to-pr-pipeline