# Communication Guide

## At a glance

- **Purpose:** Keep public communication warm, efficient, and trust-building.
- **Use when:** You are about to draft a public response (issue/PR comment, close note, duplicate consolidation).
- **Gate:** Before *any* public-facing text, load this file and follow its constraints.
- **Output:** A draft message ready for human approval (clear status + next step, no vague promises).

## Principles

1. **Warm but efficient** - Appreciate contributions without being effusive
2. **Clear expectations** - Say what's needed, don't leave ambiguity
3. **Honest about status** - Don't promise timelines; acknowledge constraints
4. **Graceful declines** - Reject work without discouraging future contribution
5. **Project-first** - Communicate like a steward focused on long-term success

## Tone Adaptation

Check `.github/maintainer/context.md` for project-specific tone. Default: professional and friendly.

## Response Templates

### Acknowledging a Good Issue

```
Thanks for the detailed report! I can reproduce this.

[Brief analysis of the issue]

I'll look into a fix. No ETA, but it's on my radar.
```

### Requesting More Information

```
Thanks for reporting! To help investigate, could you share:
- Steps to reproduce
- Expected vs actual behavior
- Environment (OS, Node version, etc.)

This will help track down the issue.
```

### First-Time Contributor Welcome

```
Welcome, and thanks for your first contribution to [project]!

[Substantive feedback on their PR/issue]
```

### Acknowledging a PR (Before Review)

```
Thanks for the PR! I'll review this when I can.

[Any initial observations or questions]
```

### Requesting Clarification on a PR

```
Thanks for the PR! A couple questions to help me extract the intent:

- [Specific question 1]
- [Specific question 2]

This helps me implement the fix directly while crediting your insights.
```

### Declining a PR Gracefully

```
Thanks for taking the time to contribute this! I appreciate the effort.

After reviewing, I've decided to take a different approach because [reason].

[If applicable: I've opened #XX which incorporates your core idea of [extracted value].]

Your contribution helped clarify the problem - thank you.
```

### Closing a PR After Implementing the Fix

```
Thanks for the PR! I implemented a fix based on your insights in [commit/PR link].

Closing this to keep the implementation in the mainline. Your contribution was very helpful.
```

### Closing as Duplicate

```
This appears to be a duplicate of #XX, which tracks the same issue.

I'm closing this to consolidate discussion. Please add any additional context to the original issue.
```

### Closing as Stale

```
Closing this due to inactivity. If this is still relevant, please reopen with any additional context and I'll take another look.
```

### Closing as Out of Scope

```
Thanks for the suggestion! After consideration, this doesn't fit the current direction of the project because [reason].

[If applicable: You might want to check out [alternative] for this use case.]
```

### Deferring an Issue

```
This is a good idea, but it's not something I can prioritize right now.

I'm labeling this as [label] for future consideration. Feel free to contribute a PR if you'd like to move it forward.
```

### Responding to Frustration

```
I understand the frustration - I wish I could move faster on this too.

[If applicable: Here's what's blocking progress: [reason]]

I appreciate your patience.
```

## Anti-Patterns

Avoid:
- **Empty promises**: "I'll get to this soon" (when you won't)
- **Over-apologizing**: Focus on what happens next
- **Vague rejections**: Always give a reason
- **Ignoring emotions**: Acknowledge frustration when present
- **Template spam**: Personalize responses to the specific situation

## Handling Difficult Situations

### Contributor Submitted Multiple Duplicate PRs
- Review the best one, reference it in closing others
- Thank them for the effort on all of them
- Explain why you chose the one you did

### Frustrated Contributor
- Acknowledge their frustration
- Explain constraints honestly
- Offer what you can (even if it's just visibility)

### Low-Quality Contribution
- Be specific about what needs improvement
- Offer to help if they're stuck
- Don't merge out of guilt - maintain standards

### Competing PRs for Same Issue
- Evaluate on technical merit
- Be transparent about selection criteria
- Thank all contributors