Skip to content

Conversation

@fadidurah
Copy link
Collaborator

@fadidurah fadidurah commented Sep 5, 2025

Settings up copilot instructions to facilitate app generation and general calling pattern debugging

This is to get the file into dev. Will probably need to tweak it once i've validated things, from a general perspective in dev, without existing context with the agent.

#2370

@github-actions
Copy link

github-actions bot commented Sep 5, 2025

❌ Work item link check failed. Description does not contain AB#{ID}.

Click here to Learn more.

…nsive warnings and enhanced debugging guidance (#2370)

This PR significantly optimizes the `.github/copilot-instructions.md`
file to be more effective for GitHub Copilot when generating Android
applications with MSAL integration. The changes reduce the file size by
44% while maintaining all critical knowledge, adding comprehensive
warning coverage, new debugging capabilities, and preserving essential
raw URLs for AI agent access.

## Key Improvements

### Comprehensive Warning Coverage
Enhanced the initial warning section to provide complete coverage for AI
agents and code generation tools:

- **Single source of truth** declaration for Copilot, AI agents, and
code generation tools
- **Explicit instruction** to read entirety of instructions
- **Legacy documentation warnings** against conflicting MSAL Android
docs
- **External pattern restrictions** for GitHub repos and Stack Overflow
answers
- **Training data cutoff** enforcement (2025-09-01)
- **Official documentation guidelines** with conflict resolution rules
- **Cross-reference requirements** with instruction precedence
- **User instruction handling** with deviation warnings

### Conciseness & Structure
- **Reduced from 274 to 154 lines** (44% reduction) while preserving all
essential information
- **Reorganized into 5 numbered priority sections** for better AI agent
scanning:
  1. Critical Rules (Read First)
  2. Authoritative Sources  
  3. API Patterns & Validation
  4. Debugging & Pattern Detection (NEW)
  5. Quick Reference

### Enhanced Debugging Capabilities
Added a comprehensive debugging section that helps Copilot detect and
prevent common MSAL integration issues:

- **Configuration error detection** (URL encoding, account mode
mismatches, missing broker config)
- **Code smell identification** (arrays vs Lists, missing UI thread
handling, unvalidated PCA calls)
- **Debug logging setup** with proper Logger configuration examples
- **UI logic validation rules** for both multiple and single account
mode applications

### Preserved AI Agent Resources
Maintained all critical raw URLs while optimizing presentation:
- **Authoritative source raw URLs**: Ai.md, msal-cline-rules.md,
auth_config.template.json
- **Direct example URLs**: Multiple and single account golden apps
- **Concise format**: Scannable by AI agents without verbose
explanations

### Improved GitHub Copilot Effectiveness
- **Visual scanning aids**: ✅/❌ code examples, emoji section headers,
clear formatting
- **Side-by-side API comparison table** for single vs multiple account
modes
- **NEVER/ALWAYS format** for critical rules that AI can quickly parse
- **Consolidated reference tables** instead of scattered information

## What's Preserved

All critical knowledge from the original file remains intact:
- Snippets directory references and usage patterns
- Golden example app locations and copying instructions  
- URL encoding rules for AndroidManifest.xml vs auth_config.json
- Deprecated API warnings and correct parameter-based alternatives
- Required dependencies, SDK versions, and AndroidX setup
- Validation checklists and configuration templates

This change provides faster scanning for AI agents, better error
prevention through debugging guidance, clearer decision-making with
comparison tables, comprehensive warning coverage, and reduced cognitive
load while preserving all essential resources for effective MSAL
integration.

<!-- START COPILOT CODING AGENT SUFFIX -->



<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: fadidurah <[email protected]>
@fadidurah fadidurah marked this pull request as ready for review September 5, 2025 18:07
Copilot AI review requested due to automatic review settings September 5, 2025 18:07
@fadidurah fadidurah requested review from a team as code owners September 5, 2025 18:07
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR sets up GitHub Copilot instructions to facilitate app generation and improve debugging capabilities for the Microsoft Authentication Library for Android (MSAL). It updates the minimum required MSAL version from 6.+ to 7.+ across documentation and establishes comprehensive AI guidance.

  • Creates comprehensive Copilot instructions with critical rules, API patterns, and debugging guidance
  • Updates minimum MSAL version requirement from 6.+ to 7.+ in documentation and guidelines
  • Updates the common subproject commit reference

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File Description
.github/copilot-instructions.md New comprehensive AI instructions file with MSAL patterns, validation rules, and debugging guidance
Ai.md Updates MSAL version requirement from 6.+ to 7.+ in dependency examples and documentation
.clinerules/msal-cline-rules.md Updates minimum MSAL version requirement from 6.+ to 7.+ for Cline tool guidance
common Updates subproject commit reference

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@fadidurah fadidurah added No-Changelog This change does not update the changelog. skip AB ID validation labels Sep 5, 2025
@fadidurah fadidurah merged commit dc5375f into dev Sep 9, 2025
13 of 14 checks passed
@fadidurah fadidurah deleted the fadi/copilot-1 branch October 1, 2025 02:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

No-Changelog This change does not update the changelog.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants