Add GitHub Issue Handling Guideline and general communication principles to copilot-instructions.md (#2408)

Copilot · fadidurah · web-flow · commit e6d716a05211 · 2025-11-19T13:39:22.000-05:00
Defines standardized protocols for Copilot agents handling GitHub Issues in this repository, covering triage, response structure, and communication patterns. Also elevates key communication principles to apply to all Copilot interactions. ## Changes - **Section 1 Update: General Communication Principles** added to `ALWAYS` rules in `.github/copilot-instructions.md` - Respond politely, concisely, and helpfully to all user prompts. Avoid jargon unless necessary, and clarify any ambiguous points before proceeding - Reference relevant documentation, previous issues, or code when applicable to provide context and support - **New Section 6: GitHub Issue Handling Guideline** added to `.github/copilot-instructions.md` - General principles: politeness, clarity, documentation references, confirmation of understanding - Triage and classification: labeling conventions, clarification requests, security escalation - Five-step response structure: acknowledge, diagnose, resolve, reference, close - Etiquette and tone: user appreciation, precise language, transparency about limitations - Three response templates: initial request, resolution, clarification - Best practices: leverage historical solutions, consistent terminology, status tracking ## Template Example ``` Thank you for your issue report! To help us resolve this, could you please provide: - [ ] Detailed steps to reproduce - [ ] Error messages/logs - [ ] Screenshots (if applicable) Once we have this information, we'll investigate further. ``` The communication principles now apply universally to all Copilot interactions, while the issue-specific guidelines provide detailed protocols for GitHub issue handling.  <details> <summary>Original prompt</summary> > Add a new section to the .github/copilot-instructions.md file that defines a clear guideline for Copilot agents to follow for answering, triaging, and managing GitHub Issues. The new section should include the following: > - General principles for responding to issue reports (politeness, clarity, referencing docs/code, confirming understanding) > - Labeling and classification practices (requesting clarification, handling severe/security issues) > - Structured response guidance (acknowledgement, diagnosis, resolution, referencing sources, closure) > - Etiquette and tone expectations > - Standard response templates (initial, resolution, clarification) > - Encouragement to use historical solutions from closed/open issues, consistent terminology, and status updates > > You may use this initial draft for insertion: > > ````markdown > ## GitHub Issue Handling Guideline > > This section defines specific instructions Copilot must follow when assisting with GitHub Issues in this repository. > > ### General Principles > - Always respond politely, concisely, and helpfully. Avoid jargon, unless necessary, and clarify any ambiguous points before proceeding. > - Reference relevant documentation, previous issues, or code if applicable. > - For all outgoing messages, confirm understanding and next steps. > > ### Triage and Classification > - Label issues clearly (“bug”, “enhancement”, “question” etc.), and use repository-specific labels if available. > - If further input or clarification is needed, request it explicitly (“Please provide logs/screenshots/steps to reproduce”). > - Escalate severe or security-related issues according to repository policy. > > ### Issue Response Structure > 1. **Acknowledge & Summarize:** Briefly summarize the issue/question as understood. > 2. **Diagnosis/Clarification:** If further information is needed, ask for it. If context is sufficient, proceed to diagnosis. > 3. **Resolution/Next Step:** Supply a relevant answer, workaround, or request for additional action. > 4. **Reference:** Link to documentation, prior issues, or specific code sections, where applicable. > 5. **Closure:** If resolved, confirm with the reporter before closing (for maintainers). Otherwise, indicate that further investigation or input is ongoing. > > ### Etiquette & Tone > - Always thank the user for their report or question. > - Avoid assumptions; use precise language. > - Be transparent about limitations, ongoing work, or next review steps. > > ### Templates > **Initial Response Template:** > ``` > Thank you for your issue report! To help us resolve this, could you please provide: > - [ ] Detailed steps to reproduce > - [ ] Error messages/logs > - [ ] Screenshots (if applicable) > > Once we have this information, we'll investigate further. > ``` > > **Resolution Template:** > ``` > We've reviewed your issue and determined [summary of finding/solution]. Please try the following steps: > 1. [Step or command] > 2. [Link to relevant doc/PR/commit] > > Let us know if this resolves your issue! > ``` > > **Clarification Needed Template:** > ``` > Thank you for raising this. Could you clarify the following points: > - [Specific questions] > ``` > > ### Best Practices From Repository History > - Reference solutions or patterns that worked in previous closed/open issues. > - Use consistent terminology for errors, features, or parts of the codebase. > - Always update issue status and labels to reflect progress. > > --- > > **Copilot should use this guideline for all issue-related conversations and actions in this repository.** > ```` </details> *This pull request was created as a result of the following prompt from Copilot chat.* > Add a new section to the .github/copilot-instructions.md file that defines a clear guideline for Copilot agents to follow for answering, triaging, and managing GitHub Issues. The new section should include the following: > - General principles for responding to issue reports (politeness, clarity, referencing docs/code, confirming understanding) > - Labeling and classification practices (requesting clarification, handling severe/security issues) > - Structured response guidance (acknowledgement, diagnosis, resolution, referencing sources, closure) > - Etiquette and tone expectations > - Standard response templates (initial, resolution, clarification) > - Encouragement to use historical solutions from closed/open issues, consistent terminology, and status updates > > You may use this initial draft for insertion: > > ````markdown > ## GitHub Issue Handling Guideline > > This section defines specific instructions Copilot must follow when assisting with GitHub Issues in this repository. > > ### General Principles > - Always respond politely, concisely, and helpfully. Avoid jargon, unless necessary, and clarify any ambiguous points before proceeding. > - Reference relevant documentation, previous issues, or code if applicable. > - For all outgoing messages, confirm understanding and next steps. > > ### Triage and Classification > - Label issues clearly (“bug”, “enhancement”, “question” etc.), and use repository-specific labels if available. > - If further input or clarification is needed, request it explicitly (“Please provide logs/screenshots/steps to reproduce”). > - Escalate severe or security-related issues according to repository policy. > > ### Issue Response Structure > 1. **Acknowledge & Summarize:** Briefly summarize the issue/question as understood. > 2. **Diagnosis/Clarification:** If further information is needed, ask for it. If context is sufficient, proceed to diagnosis. > 3. **Resolution/Next Step:** Supply a relevant answer, workaround, or request for additional action. > 4. **Reference:** Link to documentation, prior issues, or specific code sections, where applicable. > 5. **Closure:** If resolved, confirm with the reporter before closing (for maintainers). Otherwise, indicate that further investigation or input is ongoing. > > ### Etiquette & Tone > - Always thank the user for their report or question. > - Avoid assumptions; use precise language. > - Be transparent about limitations, ongoing work, or next review steps. > > ### Templates > **Initial Response Template:** > ``` > Thank you for your issue report! To help us resolve this, could you please provide: > - [ ] Detailed steps to reproduce > - [ ] Error messages/logs > - [ ] Screenshots (if applicable) > > Once we have this information, we'll investigate further. > ``` > > **Resolution Template:** > ``` > We've reviewed your issue and determined [summary of finding/solution]. Please try the following steps: > 1. [Step or command] > 2. [Link to relevant doc/PR/commit] > > Let us know if this resolves your issue! > ``` > > **Clarification Needed Template:** > ``` > Thank you for raising this. Could you clarify the following points: > - [Specific questions] > ``` > > ### Best Practices From Repository History > - Reference solutions or patterns that worked in previous closed/open issues. > - Use consistent terminology for errors, features, or parts of the codebase. > - Always update issue status and labels to reflect progress. > > --- > > **Copilot should use this guideline for all issue-related conversations and actions in this repository.** > ````  --- ✨ Let Copilot coding agent [set things up for you](https://github.com/AzureAD/microsoft-authentication-library-for-android/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: fadidurah <88730756+fadidurah@users.noreply.github.com>
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -57,6 +57,8 @@
 - URL encode signature hash in AndroidManifest.xml / Must URL encode in auth_config.json
 
 **ALWAYS:**
+- Respond politely, concisely, and helpfully to all user prompts. Avoid jargon unless necessary, and clarify any ambiguous points before proceeding
+- Reference relevant documentation, previous issues, or code when applicable to provide context and support
 - Use parameters-based APIs from [`snippets/`](../snippets/) directory
 - Default to multiple account mode unless specified
 - Enable broker integration (`broker_redirect_uri_registered: true`)
@@ -183,4 +185,65 @@ Logger.getInstance().setEnablePII(true); // Only for debugging
 **Copy exactly:** Gradle files from golden examples (only change applicationId/namespace)  
 **Resource structure:** Follow golden examples for res/ directory layout
 
-**Remember:** When in doubt, check snippets/ directory first, then golden examples. Never invent patterns.
+**Remember:** When in doubt, check snippets/ directory first, then golden examples. Never invent patterns.
+
+## 6. GitHub Issue Handling Guideline
+
+This section defines specific instructions Copilot must follow when assisting with GitHub Issues in this repository.
+
+### General Principles
+- Always respond politely, concisely, and helpfully. Avoid jargon, unless necessary, and clarify any ambiguous points before proceeding.
+- Reference relevant documentation, previous issues, or code if applicable.
+- For all outgoing messages, confirm understanding and next steps.
+
+### Triage and Classification
+- Label issues clearly ("bug", "enhancement", "question" etc.), and use repository-specific labels if available.
+- If further input or clarification is needed, request it explicitly ("Please provide logs/screenshots/steps to reproduce").
+- Escalate severe or security-related issues according to repository policy.
+
+### Issue Response Structure
+1. **Acknowledge & Summarize:** Briefly summarize the issue/question as understood.
+2. **Diagnosis/Clarification:** If further information is needed, ask for it. If context is sufficient, proceed to diagnosis.
+3. **Resolution/Next Step:** Supply a relevant answer, workaround, or request for additional action.
+4. **Reference:** Link to documentation, prior issues, or specific code sections, where applicable.
+5. **Closure:** If resolved, confirm with the reporter before closing (for maintainers). Otherwise, indicate that further investigation or input is ongoing.
+
+### Etiquette & Tone
+- Always thank the user for their report or question.
+- Avoid assumptions; use precise language.
+- Be transparent about limitations, ongoing work, or next review steps.
+
+### Templates
+**Initial Response Template:**
+```
+Thank you for your issue report! To help us resolve this, could you please provide:
+- [ ] Detailed steps to reproduce
+- [ ] Error messages/logs
+- [ ] Screenshots (if applicable)
+
+Once we have this information, we'll investigate further.
+```
+
+**Resolution Template:**
+```
+We've reviewed your issue and determined [summary of finding/solution]. Please try the following steps:
+1. [Step or command]
+2. [Link to relevant doc/PR/commit]
+
+Let us know if this resolves your issue!
+```
+
+**Clarification Needed Template:**
+```
+Thank you for raising this. Could you clarify the following points:
+- [Specific questions]
+```
+
+### Best Practices From Repository History
+- Reference solutions or patterns that worked in previous closed/open issues.
+- Use consistent terminology for errors, features, or parts of the codebase.
+- Always update issue status and labels to reflect progress.
+
+---
+
+**Copilot should use this guideline for all issue-related conversations and actions in this repository.**
