SKILL.md

PR Plan Skill

Strategic planning for open source contributions.

Overview

Create a contribution plan that bridges research and implementation. Takes

$pr-research output and produces an actionable plan.

Output: .agents/plans/YYYY-MM-DD-pr-plan-{repo-slug}.md

When to Use:

After completing $pr-research

Planning contribution strategy

Before starting implementation

When NOT to Use:

Haven't researched the repo yet

Trivial contributions (fix typos)

Internal project planning (use $plan)

Workflow

0.  Input Discovery     -> Find/load pr-research artifact

1.  Scope Definition    -> What exactly to contribute

2.  Target Selection    -> Which issues/areas to address

3.  Criteria Definition -> Acceptance criteria from research

4.  Risk Assessment     -> What could go wrong

5.  Strategy Formation  -> Implementation approach

6.  Output              -> Write plan artifact

Phase 1: Scope Definition

Scope Questions

Question

Why It Matters

What specific functionality?

Clear deliverable

Which files/packages?

Limits impact surface

What's explicitly out of scope?

Prevents scope creep

Single PR or series?

Sets expectations

Scope Template

## Scope

**Contribution**: [1-2 sentences describing the change]

**Affected Areas**:

- `path/to/file.go` - [what changes]

**Out of Scope**:

- [Related but excluded work]

Phase 3: Acceptance Criteria

Define success from maintainer perspective:

## Acceptance Criteria

### Code Quality

- [ ] Follows project coding style

- [ ] Passes existing tests

- [ ] Adds tests for new functionality

- [ ] No linting warnings

### PR Requirements

- [ ] Title follows convention

- [ ] Body uses project template

- [ ] Size within acceptable range

- [ ] Single logical change

### Project-Specific

- [ ] [Any project-specific requirements from research]

Phase 4: Risk Assessment

Risk

Likelihood

Impact

Mitigation

PR review takes > 2 weeks

Medium

Start small, be responsive

Scope expands during review

Medium

High

Define scope clearly upfront

Breaking change discovered

Low

High

Test against multiple versions

Phase 5: Implementation Strategy

## Implementation Strategy

### Approach

1. **Setup**: Fork repo, configure dev environment

2. **Understand**: Read existing code in affected area

3. **Implement**: Make changes following project patterns

4. **Test**: Run existing tests + add new tests

5. **Document**: Update any affected documentation

6. **Submit**: Create PR following project conventions

### Pre-Implementation Checklist

- [ ] Fork created and up-to-date with upstream

- [ ] Dev environment working

- [ ] Issue claimed or comment posted

- [ ] Recent repo activity reviewed

Output Template

Write to .agents/plans/YYYY-MM-DD-pr-plan-{repo-slug}.md

# PR Plan: {repo-name}

## Executive Summary

{2-3 sentences: what you're contributing, why, expected outcome}

## Scope

**Contribution**: {description}

**Affected Areas**: [list]

**Out of Scope**: [list]

## Target

**Primary Issue**: #{N} - {title}

## Acceptance Criteria

[checklist]

## Risk Assessment

[table]

## Implementation Strategy

[numbered steps]

## Next Steps

1. Claim/comment on target issue

2. Fork and set up development environment

3. Implement following strategy

4. Run `$pr-prep` when ready

Workflow Integration

$pr-research <repo> -> $pr-plan <research> -> implement -> $pr-prep

Examples

Plan a Focused External Contribution

User says: "Create a contribution plan from my PR research artifact."

What happens:

Extract accepted conventions and constraints.

Define scope boundaries and acceptance criteria.

Produce an implementation strategy with risks.

Tighten Scope Before Coding

User says: "Check if this PR plan is too large for one submission."

What happens:

Compare proposed changes to historical PR size patterns.

Split oversized scope into phased contributions.

Emit a revised plan and next-step checklist.

Troubleshooting

Problem

Cause

Solution

Plan has vague acceptance criteria

Criteria not measurable

Convert criteria to concrete behavioral checks

Scope too broad

Multiple concerns mixed

Split by user-visible change or subsystem boundary

Risk section is weak

Missing failure-mode analysis

Add integration, review, and rollback risks explicitly

Plan conflicts with repo norms

Research artifact incomplete

Re-run $pr-research and refresh constraints

pr-plan