microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
.github/instructions/github/community-interaction.instructions.md
334lines · modecode
| 1 | --- |
| 2 | description: 'Community interaction voice, tone, and response templates for GitHub-facing agents and prompts' |
| 3 | applyTo: '**/.github/instructions/github-backlog-*.instructions.md' |
| 4 | --- |
| 5 | |
| 6 | # Community Interaction Guidelines |
| 7 | |
| 8 | Voice, tone, and response templates for community-facing interactions on GitHub. Apply these conventions when agents or prompts post comments on issues, pull requests, or discussions visible to external contributors. |
| 9 | |
| 10 | ## Voice Foundation |
| 11 | |
| 12 | Community interactions build on the conventions in `writing-style.instructions.md` at the Community formality level: warm, appreciative, and scope-focused. |
| 13 | |
| 14 | Every comment posted via `mcp_github_add_issue_comment` is public and permanent. Write with the awareness that contributors, maintainers, and future readers will see the message in the issue timeline. |
| 15 | |
| 16 | Pronoun conventions for community interactions: |
| 17 | |
| 18 | * Use "we" when speaking for the project or making organizational decisions. |
| 19 | * Use "you" when addressing or acknowledging a specific contributor. |
| 20 | |
| 21 | ## Core Principles |
| 22 | |
| 23 | * Thank first: open every interaction with acknowledgment, even when declining or closing. |
| 24 | * Scope, not quality: frame rejections around project direction, not the contribution's merit. |
| 25 | * Leave doors open: include a path to re-engagement in every closure message. |
| 26 | * Be specific: name what the contributor did. Generic thanks feels hollow. |
| 27 | * Be concise: target 2-4 sentences per response. Longer responses invite negotiation. |
| 28 | * Match CONTRIBUTING.md warmth: align with the "First off, thanks for taking the time to contribute!" energy established in the project's contributor guide. |
| 29 | |
| 30 | ## Tone Calibration Matrix |
| 31 | |
| 32 | Select tone characteristics based on the scenario category. This matrix guides template authoring and agent response generation. |
| 33 | |
| 34 | | Scenario Category | Primary Tone | Secondary Tone | Emoji Use | Response Length | |
| 35 | |---------------------|-------------------------|--------------------------------|--------------------------------|-------------------------| |
| 36 | | Welcoming/thanking | Warm, genuine | Specific, encouraging | Permitted (brief, celebratory) | 2-3 sentences | |
| 37 | | Celebrating | Warm, celebratory | Specific, encouraging | Permitted (brief, celebratory) | 2-3 sentences | |
| 38 | | Closing (scope) | Respectful, direct | Scope-focused, door-open | None | 2-3 sentences | |
| 39 | | Closing (completed) | Warm, confirming | Specific, closure-giving | Permitted (brief) | 2-3 sentences | |
| 40 | | Closing (inactive) | Neutral, informational | Reopening-friendly | None | 2 sentences | |
| 41 | | Declining PRs | Appreciative, honest | Criteria-focused, constructive | None | 3-4 sentences | |
| 42 | | Requesting info | Constructive, specific | Actionable, time-bounded | None | 3-4 sentences with list | |
| 43 | | Redirecting | Helpful, brief | Clear next steps | None | 2 sentences | |
| 44 | | De-escalating | Calm, empathetic | Boundary-setting, process | None | 2-3 sentences | |
| 45 | | Security | Urgent, reassuring | Process-focused, confidential | None | 2-3 sentences | |
| 46 | | Onboarding | Encouraging, supportive | Mentoring, context-providing | Permitted (brief) | 3-4 sentences | |
| 47 | |
| 48 | ## Scenario Catalog |
| 49 | |
| 50 | Each scenario includes a trigger condition, a response template with `{{placeholder}}` syntax, a tone annotation, and the tool sequence for execution. |
| 51 | |
| 52 | Template placeholders used across scenarios: |
| 53 | |
| 54 | * `{{contributor}}` - GitHub username of the contributor |
| 55 | * `{{original_number}}` - original issue number (for duplicate closures) |
| 56 | * `{{pr_number}}` - pull request number (for completed issue closures) |
| 57 | * `{{specific_area}}` - description of the code area affected |
| 58 | * `{{specific_reason}}` - explanation for the action taken |
| 59 | * `{{specific_outcome}}` - impact of the contribution |
| 60 | * `{{criteria}}` - specific contribution criteria not met |
| 61 | * `{{time_period}}` - inactivity duration |
| 62 | * `{{question_1}}`, `{{question_2}}` - specific information requests |
| 63 | * `{{redirect_url}}` - URL for redirection targets |
| 64 | |
| 65 | ### Welcoming and Acknowledging |
| 66 | |
| 67 | #### Scenario 1: Welcoming a First-Time Contributor |
| 68 | |
| 69 | Triggered when a contributor opens their first issue or PR in the repository. Tone is warm and genuine, encouraging first engagement. |
| 70 | |
| 71 | > Welcome to the project, @{{contributor}}! 🎉 Thank you for your first contribution. Please review our [CONTRIBUTING.md](https://github.com/{{owner}}/{{repo}}/blob/main/CONTRIBUTING.md) for guidelines and expectations. A maintainer will review your submission within the next few business days. |
| 72 | |
| 73 | Post via: |
| 74 | |
| 75 | 1. `mcp_github_add_issue_comment` with the welcome message. |
| 76 | |
| 77 | #### Scenario 2: Thanking for a Contribution (Code) |
| 78 | |
| 79 | Triggered when a code PR is merged or a significant code contribution is acknowledged. Tone is warm and genuine with specific acknowledgment of technical impact. |
| 80 | |
| 81 | > Thank you for this contribution, @{{contributor}}! Your changes to {{specific_area}} improve {{specific_outcome}}. We appreciate the time and care you put into this. |
| 82 | |
| 83 | Post via: |
| 84 | |
| 85 | 1. `mcp_github_add_issue_comment` with the thank-you message. |
| 86 | |
| 87 | #### Scenario 3: Thanking for a Contribution (Documentation) |
| 88 | |
| 89 | Triggered when a documentation PR is merged or a documentation improvement is acknowledged. Tone is warm and genuine, explicitly valuing documentation work. |
| 90 | |
| 91 | > Thank you for improving the documentation, @{{contributor}}! Your updates to {{specific_area}} make the project more accessible for everyone. Documentation contributions are as valuable as code. |
| 92 | |
| 93 | Post via: |
| 94 | |
| 95 | 1. `mcp_github_add_issue_comment` with the thank-you message. |
| 96 | |
| 97 | #### Scenario 4: Thanking for a Contribution (Issue) |
| 98 | |
| 99 | Triggered when a contributor files a well-structured issue report. Tone is warm and appreciative, acknowledging the effort in a clear report. |
| 100 | |
| 101 | > Thank you for filing this issue, @{{contributor}}. The clear description and reproduction steps help us investigate efficiently. We'll follow up as we work through the backlog. |
| 102 | |
| 103 | Post via: |
| 104 | |
| 105 | 1. `mcp_github_add_issue_comment` with the thank-you message. |
| 106 | |
| 107 | #### Scenario 5: Acknowledging a Security Report |
| 108 | |
| 109 | Triggered when a contributor reports a security vulnerability through any channel. Tone is urgent and reassuring, process-focused with confidentiality emphasis. |
| 110 | |
| 111 | > Thank you for reporting this security concern, @{{contributor}}. We take security seriously and will investigate promptly. Please review our [SECURITY.md](https://github.com/{{owner}}/{{repo}}/blob/main/SECURITY.md) for next steps on the responsible disclosure process. We ask that further details remain confidential until the issue is resolved. |
| 112 | |
| 113 | Post via: |
| 114 | |
| 115 | 1. `mcp_github_add_issue_comment` with the acknowledgment. |
| 116 | |
| 117 | #### Scenario 6: Celebrating a Milestone Contribution |
| 118 | |
| 119 | Triggered when a contributor reaches a meaningful milestone (multiple merged PRs, sustained engagement, significant impact). Tone is warm and celebratory with specific recognition tied to impact. |
| 120 | |
| 121 | > Congratulations, @{{contributor}}! 🎉 Your contributions to {{specific_area}} have made a real impact on the project. Thank you for your sustained engagement and the quality of your work. |
| 122 | > |
| 123 | > The community benefits from contributors like you. |
| 124 | |
| 125 | Post via: |
| 126 | |
| 127 | 1. `mcp_github_add_issue_comment` with the celebration message. |
| 128 | |
| 129 | ### Closing and Declining |
| 130 | |
| 131 | #### Scenario 7: Closing a Duplicate Issue |
| 132 | |
| 133 | Triggered when an issue is identified as a duplicate of an existing tracked issue. Tone is respectful and direct, linking to the original and inviting further contribution. |
| 134 | |
| 135 | > Thank you for reporting this. This is tracked in #{{original_number}}, which has additional context and discussion. |
| 136 | > |
| 137 | > Closing as duplicate. Please add any additional details to the original issue to help prioritize it. |
| 138 | |
| 139 | Post via: |
| 140 | |
| 141 | 1. `mcp_github_add_issue_comment` with the duplicate explanation. |
| 142 | 2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'duplicate'`, `duplicate_of: {{original_number}}`. |
| 143 | |
| 144 | #### Scenario 8: Closing a Completed Issue |
| 145 | |
| 146 | Triggered when a fix merges and the tracked issue is resolved. Tone is warm and confirming, thanking the reporter and confirming the resolution. |
| 147 | |
| 148 | > This issue has been resolved in #{{pr_number}}. Thank you for reporting this, @{{contributor}}. Your report helped us identify and address the problem. |
| 149 | > |
| 150 | > Closing as completed. If you encounter further issues, feel free to open a new issue. |
| 151 | |
| 152 | Post via: |
| 153 | |
| 154 | 1. `mcp_github_add_issue_comment` with the resolution message. |
| 155 | 2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'completed'`. |
| 156 | |
| 157 | #### Scenario 9: Closing a Won't-Fix Issue |
| 158 | |
| 159 | Triggered when an issue is closed because it falls outside the project's current scope or direction. Tone is respectful and direct, framing the decision around scope. Leaves the door open for reconsideration. |
| 160 | |
| 161 | > Thank you for raising this. After review, this falls outside the current project scope because {{specific_reason}}. |
| 162 | > |
| 163 | > Closing as not planned. If you believe this should be reconsidered, please share additional context about the use case and community impact, and we can revisit. |
| 164 | |
| 165 | Post via: |
| 166 | |
| 167 | 1. `mcp_github_add_issue_comment` with the scope explanation. |
| 168 | 2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. |
| 169 | |
| 170 | #### Scenario 10: Closing a Stale Issue |
| 171 | |
| 172 | Triggered when an issue has had no activity for an extended period and lacks sufficient information to act on. Tone is neutral and informational with no blame and a clear reopen path. |
| 173 | |
| 174 | > Closing this issue due to inactivity over the past 74 days. If this is still relevant, please reopen with any additional context and we'll be happy to revisit. |
| 175 | |
| 176 | Post via: |
| 177 | |
| 178 | 1. `mcp_github_add_issue_comment` with the stale notice. |
| 179 | 2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. |
| 180 | |
| 181 | #### Scenario 11: Closing a Stale PR |
| 182 | |
| 183 | Triggered when a PR has had no activity for an extended period and has fallen behind the base branch. Tone is neutral and informational, suggesting rebase with a clear reopen path. |
| 184 | |
| 185 | > Closing this PR due to inactivity over the past 21 days. If you'd like to continue this work, feel free to reopen and rebase onto the latest base branch. We're happy to resume the review. |
| 186 | |
| 187 | Post via: |
| 188 | |
| 189 | 1. `mcp_github_add_issue_comment` with the stale notice. |
| 190 | 2. `mcp_github_update_pull_request` with `state: 'closed'`. |
| 191 | |
| 192 | #### Scenario 12: Declining a PR (Contribution Criteria Not Met) |
| 193 | |
| 194 | Triggered when a PR does not meet the project's contribution guidelines and cannot be merged in its current form. Tone is appreciative and honest, criteria-focused and constructive with a clear revision path. |
| 195 | |
| 196 | > Thank you for taking the time to submit this PR, @{{contributor}}. We appreciate the effort. |
| 197 | > |
| 198 | > This PR doesn't currently meet our contribution guidelines: {{criteria}}. Please review our [CONTRIBUTING.md](../../../CONTRIBUTING.md) for the full requirements. |
| 199 | > |
| 200 | > You're welcome to revise and resubmit. If you'd like guidance before making changes, please comment here or open a discussion. |
| 201 | |
| 202 | Post via: |
| 203 | |
| 204 | 1. `mcp_github_add_issue_comment` with the explanation. |
| 205 | |
| 206 | #### Scenario 13: Declining a Feature Request |
| 207 | |
| 208 | Triggered when a feature request does not align with the project's current direction. Tone is respectful and direct, scope-focused with a path to community advocacy. |
| 209 | |
| 210 | > Thank you for the feature suggestion, @{{contributor}}. After review, this doesn't align with the project's current direction because {{specific_reason}}. |
| 211 | > |
| 212 | > If there is broader community interest, please open a Discussion thread to gather feedback. We revisit priorities as the community's needs evolve. |
| 213 | |
| 214 | Post via: |
| 215 | |
| 216 | 1. `mcp_github_add_issue_comment` with the explanation. |
| 217 | 2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. |
| 218 | |
| 219 | ### Requesting and Redirecting |
| 220 | |
| 221 | #### Scenario 14: Requesting More Information on an Issue |
| 222 | |
| 223 | Triggered when an issue lacks sufficient detail for investigation or reproduction. Tone is constructive and specific with actionable questions and a time-bounded expectation. |
| 224 | |
| 225 | > Thank you for filing this. To investigate further, we need some additional details: |
| 226 | > |
| 227 | > * {{question_1}} |
| 228 | > * {{question_2}} |
| 229 | > |
| 230 | > If we don't hear back within 14 days, this issue will be closed automatically. You can always reopen it with the requested information. |
| 231 | |
| 232 | Post via: |
| 233 | |
| 234 | 1. `mcp_github_add_issue_comment` with the information request. |
| 235 | 2. Apply `needs-info` label if available. |
| 236 | |
| 237 | #### Scenario 15: Requesting Changes on a PR |
| 238 | |
| 239 | Triggered when a PR review identifies specific changes needed before the PR can be merged. Tone is constructive and collaborative with specific actionable items and an offer to discuss. |
| 240 | |
| 241 | > Thank you for this PR, @{{contributor}}. After review, we have a few suggested changes: |
| 242 | > |
| 243 | > * {{question_1}} |
| 244 | > * {{question_2}} |
| 245 | > |
| 246 | > These adjustments will help align the PR with the project's conventions. Please comment if you have questions about any of the suggestions, and we can discuss further. |
| 247 | |
| 248 | Post via: |
| 249 | |
| 250 | 1. `mcp_github_add_issue_comment` with the change request. |
| 251 | |
| 252 | #### Scenario 16: Redirecting to Discussions |
| 253 | |
| 254 | Triggered when an issue is better suited for the Discussions forum (questions, brainstorming, open-ended topics). Tone is helpful and brief, pointing to the correct forum with a reopen path. |
| 255 | |
| 256 | > Thank you for raising this. This topic is better suited for our [Discussions]({{redirect_url}}) forum, where the community can weigh in. Closing here, but feel free to reopen if this turns into an actionable issue. |
| 257 | |
| 258 | Post via: |
| 259 | |
| 260 | 1. `mcp_github_add_issue_comment` with the redirect message. |
| 261 | 2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. |
| 262 | |
| 263 | #### Scenario 17: Redirecting to Another Repository |
| 264 | |
| 265 | Triggered when an issue or PR belongs in a different repository within the organization. Tone is helpful and brief with a clear redirect and reopen path. |
| 266 | |
| 267 | > Thank you for reporting this. This belongs in {{redirect_url}}, which manages that area of the project. Closing here, but please reopen if you believe this was miscategorized. |
| 268 | |
| 269 | Post via: |
| 270 | |
| 271 | 1. `mcp_github_add_issue_comment` with the redirect message. |
| 272 | 2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. |
| 273 | |
| 274 | ### Managing Conflict |
| 275 | |
| 276 | #### Scenario 18: De-escalating a Heated Discussion |
| 277 | |
| 278 | Triggered when a conversation becomes unproductive, personal, or heated, but has not yet crossed Code of Conduct lines. Tone is calm and empathetic, setting boundaries through process rather than authority. |
| 279 | |
| 280 | > We appreciate everyone's engagement on this topic. To keep this discussion productive, let's focus on specific technical requirements and use cases. |
| 281 | > |
| 282 | > Our [Code of Conduct](https://github.com/{{owner}}/{{repo}}/blob/main/CODE_OF_CONDUCT.md) applies to all interactions. Contributions that focus on constructive solutions move the conversation forward. |
| 283 | |
| 284 | Post via: |
| 285 | |
| 286 | 1. `mcp_github_add_issue_comment` with the de-escalation message. |
| 287 | |
| 288 | #### Scenario 19: Locking a Conversation |
| 289 | |
| 290 | Triggered when a conversation has crossed Code of Conduct boundaries or de-escalation has been insufficient. Tone is calm and empathetic, stating the reason and duration with an alternative channel. |
| 291 | |
| 292 | > This conversation is being locked for {{time_period}} to allow a cooling-off period. Our [Code of Conduct](https://github.com/{{owner}}/{{repo}}/blob/main/CODE_OF_CONDUCT.md) outlines the expectations for all community interactions. |
| 293 | > |
| 294 | > If you need to continue this discussion, please reach out to the maintainers through the channels listed in [SUPPORT.md](https://github.com/{{owner}}/{{repo}}/blob/main/SUPPORT.md). |
| 295 | |
| 296 | Post via: |
| 297 | |
| 298 | 1. `mcp_github_add_issue_comment` with the lock notice. |
| 299 | 2. Conversation locking requires a direct GitHub REST API call (`PUT /repos/{owner}/{repo}/issues/{issue_number}/lock`) or manual maintainer action. No MCP tool is currently available for this operation. |
| 300 | |
| 301 | ### Onboarding and Engagement |
| 302 | |
| 303 | #### Scenario 20: Welcoming a Good-First-Issue Pickup |
| 304 | |
| 305 | Triggered when a contributor picks up an issue labeled `good-first-issue`. Tone is encouraging and supportive, providing context and offering mentoring. |
| 306 | |
| 307 | > Welcome, @{{contributor}}! 🎉 Thank you for picking up this issue. Here is some context to get you started: {{specific_area}}. |
| 308 | > |
| 309 | > If you have questions during implementation, feel free to comment here. A maintainer will be available to help guide you through the process. |
| 310 | |
| 311 | Post via: |
| 312 | |
| 313 | 1. `mcp_github_add_issue_comment` with the welcome and context. |
| 314 | |
| 315 | ## Escalation Guidance |
| 316 | |
| 317 | Agents should involve human maintainers when: |
| 318 | |
| 319 | * Code of Conduct violations require judgment calls beyond template responses. |
| 320 | * De-escalation templates (Scenarios 18-19) prove insufficient to resolve the situation. |
| 321 | * Security reports require confidential triage and coordination. |
| 322 | * Contributor disputes involve technical direction decisions that need maintainer consensus. |
| 323 | * The agent cannot determine the appropriate response or scenario template. |
| 324 | |
| 325 | Escalation follows the role hierarchy defined in [GOVERNANCE.md](../../../GOVERNANCE.md): Triage Contributor escalates to Maintainer, Maintainer escalates to Admin. Reference [CODE_OF_CONDUCT.md](../../../CODE_OF_CONDUCT.md) for behavioral standards. |
| 326 | |
| 327 | ## Integration Instructions |
| 328 | |
| 329 | Community-facing agents and prompts reference these guidelines through the instruction file inheritance system: |
| 330 | |
| 331 | * Instruction files reference via `#file:./community-interaction.instructions.md`. |
| 332 | * Agents inherit guidelines transitively through their instruction file references. |
| 333 | * Templates are self-contained. Agents select the appropriate scenario and fill placeholders with values from the issue or PR context. |
| 334 | * Always post comments via `mcp_github_add_issue_comment` before or alongside closure API calls so the contributor sees the explanation in the issue timeline. |
| 335 | |