Step 1: What is the current branch? Is it main/master or a feature branch? Step 2: What is the total diff size of this branch vs main? Step 3: Are there staged changes? How do they relate to existing branch changes? Step 4: Is there an issue reference for this work? Step 5: Are there tests for the changes? Step 6: Would this merge quickly, or would it stall?

Now proceed with confidence following Nim's contribution patterns.

Nim PR Guide Workflow

Automatic Triggers

This skill activates when:

Pre-Commit Analysis

Before EVERY commit in ~/Development/Nim, analyze whether staged changes belong in this branch.

Step 1: Get Current State

# Get branch name
git rev-parse --abbrev-ref HEAD

# Get merge base with main/devel
git merge-base HEAD devel  # or main

# Get existing branch changes (committed)
git diff $(git merge-base HEAD devel)...HEAD --stat

# Get staged changes
git diff --cached --stat

# Get combined size
git diff $(git merge-base HEAD devel) --stat

Step 2: Analyze Cohesion

Ask these questions about staged changes vs existing branch work:

Step 3: Split Decision

IF staged changes are UNRELATED to existing branch work:
  → Suggest: stash, create new branch, apply stash, commit there

IF staged changes are RELATED but branch would exceed 150 lines:
  → Suggest: commit current work, create continuation PR

IF staged changes are RELATED and branch stays under 150 lines:
  → Proceed with commit

Split Commands Template

# Stash current staged changes
git stash push -m "unrelated-work-for-new-branch"

# Create and switch to new branch from devel
git checkout devel
git checkout -b fix/ISSUE-NUMBER-brief-description

# Apply stashed changes
git stash pop

# Commit in new branch
git add .
git commit -m "fixes #ISSUE; description"

Size Thresholds

Size Check Command

# Check current branch size
git diff $(git merge-base HEAD devel) --stat | tail -1

# Example output: "5 files changed, 47 insertions(+), 12 deletions(-)"
# Total: 47 + 12 = 59 lines → "medium" territory

Issue Reference Requirements

Every PR MUST reference an issue. No exceptions for bug fixes.

If Issue Exists

Title format: fixes #ISSUE; Brief description

Examples:

• fixes #25341; Invalid C code for lifecycle hooks
• fixes #25284; .global initialization inside method hoisted

If No Issue Exists

For bug fixes:

1. Open issue first describing the bug
2. Wait for acknowledgment (even a label is enough)
3. Then submit PR referencing that issue

For new features:

1. Open RFC/discussion issue
2. Get explicit approval before coding
3. Only then submit PR

For docs/minor improvements:

• Can submit without issue, but use descriptive title
• Format: [Docs] Description or component: description

PR Title Formats

Most Successful (use these):

fixes #ISSUE_NUMBER; Brief description of what was fixed

fix COMPONENT: What was wrong and how it's fixed

For Documentation:

[Docs] Clear description of documentation change

Rules:

• Start lowercase UNLESS "Fixes", "Fix", or "[Category]"
• Keep under 72 characters
• Be specific, not generic

PR Description Templates

For Small Fixes (< 50 lines)

fixes #ISSUE_NUMBER

[Optional 1-2 sentence explanation if not obvious from code]

For Larger Changes (50+ lines)

fixes #ISSUE_NUMBER

## Summary
Brief explanation of what was broken and how this fixes it.

## Changes
- Specific change 1
- Specific change 2
- Added tests for X, Y, Z

[Optional: Technical details if complex]

For Refactoring Series

Continuation of #PREVIOUS_PR_NUMBER

## Changes in This PR
- Specific change 1
- Specific change 2

This is part X of Y in the COMPONENT refactoring series.

For Feature PRs (New Capabilities)

Use this format for PRs that introduce new functionality, especially those in a series:

# PR Title: Brief description of feature

**Base:** `devel` (or parent branch if in series)
**Branch:** `feature/branch-name`

---

Brief 1-2 sentence overview of what this PR introduces.

## Summary

1. **Capability 1**: Brief description
2. **Capability 2**: Brief description
3. **Feature detection**: Use `defined(nimHasFeatureName)` to check for this feature

## Example

\`\`\`nim
# Minimal working example demonstrating the feature
type
  Example[T] {.pragma: expression.} = object

static:
  doAssert condition  # Proves it works
\`\`\`

## Use Cases

### Use Case Title

Brief description of the problem this solves.

\`\`\`nim
# Before: the workaround
# After: the clean solution
\`\`\`

## Implementation

**Component** (`file.nim`):
- Change description 1
- Change description 2

**Another Component** (`other.nim`):
- Change description

## Tests

- `tests/path/to/test.nim` - Description of what's tested

## Dependencies

- Requires PRX (`branch-name`) for infrastructure  *(if part of series)*

## Prior Art *(optional)*

Reference related PRs/issues if this is an alternative approach.

For PR Series

When submitting related PRs as a series, include a summary table:

## Series Summary

| PR | Branch | Focus | Lines (net) |
|----|--------|-------|-------------|
| PR1 | `feature/first` | Infrastructure + X | +441 |
| PR2 | `feature/second` | Y functionality | +172 |
| PR3 | `feature/third` | Z functionality | +300 |

Together these PRs enable [combined capability description].

Pre-Submission Checklist

Run this checklist before creating any PR to nim-lang/Nim.

Required for ALL PRs:

• Branch size is under 150 lines (or justified)
• Issue reference exists in title (fixes #ISSUE)
• Title follows format: lowercase unless Fix/Fixes/[Category]
• Tests exist for the change
• All CI passes (or failures are clearly unrelated)
• No unrelated changes mixed in

Additional for 50+ line PRs:

• Description has ## Summary section
• Description has ## Changes bullet points
• Changes are cohesive (single purpose)

Additional for New Features:

• Prior discussion/approval exists
• Documentation added to manual
• Comprehensive test coverage

Additional for UI/Docs:

• Before/after screenshots if visual change

What Maintainers Prioritize

Based on comment analysis of 154 merged PRs:

Dependent PR Chains

When work naturally divides into multiple dependent PRs, the Nim project has implicit patterns based on contributor experience.

The Problem with PR Chains

GitHub does not natively support stacked/dependent PRs. Each subsequent PR in a chain contains all changes from preceding PRs until those are merged. This creates:

• Difficult-to-review diffs (reviewers see accumulated changes)
• Risk of wasted effort (if base PR is rejected, all descendants die)
• Merge conflict complexity when base PRs change during review

Recommended Approach: Sequential Submission

Wait for each PR to merge before submitting the next in a dependency chain.

Why this works:

• Each PR reviewed in isolation with clean diff
• No wasted effort on downstream PRs if base needs changes
• Clear review scope for maintainers
• Avoids confusing "depends on PR #X" gymnastics

Proven pattern (from contributor experience):

PR1: "System cleanup, part 1" → merged
PR2: "System cleanup, part 2" → submitted AFTER PR1 merged

Contributors who waited between submissions had higher merge success rates than those who submitted chains simultaneously.

When Sequential Isn't Possible

If you must have work visible before base merges (e.g., showing direction, getting early feedback):

Option A: Draft PR with explicit dependency

## ⚠️ Draft - Depends on #XXXX

This PR builds on #XXXX and should not be reviewed until that merges.
Once #XXXX merges, I will rebase and mark ready for review.

[Rest of description showing intended changes]

Option B: Combine into single PR (if truly tightly coupled)

• If changes genuinely cannot be separated meaningfully
• Use clear commit structure within the single PR
• Accept longer review time for larger scope

How to Communicate Dependencies

If submitting before base merges, include in PR description:

## Dependencies

- Requires #XXXX (feature/branch-name) to merge first

## Changes Specific to This PR

[List ONLY what this PR adds beyond the dependency]

What NOT to Do

IF work is truly interdependent (A required for B to compile):
  → Submit A first, wait for merge, then submit B

IF work is conceptually related but independently valuable:
  → Submit as separate PRs targeting devel, not as chain

IF you want early feedback on full direction:
  → Submit base PR as ready, subsequent as Draft with explicit dependency note

IF base PR faces resistance:
  → Do NOT submit dependent PRs until base is accepted
  → Consider the chain dead if base is rejected

# Check branch size
git diff $(git merge-base HEAD devel) --stat | tail -1

# Check if branch references an issue (in commit messages)
git log $(git merge-base HEAD devel)..HEAD --oneline | grep -E '#[0-9]+'

# Preview PR title from branch name
echo "fixes #$(echo $(git rev-parse --abbrev-ref HEAD) | grep -oE '[0-9]+')"

# Check which files changed
git diff $(git merge-base HEAD devel) --name-only

# Check test files exist
git diff $(git merge-base HEAD devel) --name-only | grep -E 'tests?/'