Add custom instructions for using C++ language service tools

docs/README.instructions.md

@@ -57,6 +57,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
 | [Convert Spring JPA project to Spring Data Cosmos](../instructions/convert-jpa-to-spring-data-cosmos.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fconvert-jpa-to-spring-data-cosmos.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fconvert-jpa-to-spring-data-cosmos.instructions.md) | Step-by-step guide for converting Spring Boot JPA applications to use Azure Cosmos DB with Spring Data Cosmos |
 | [Copilot Process tracking Instructions](../instructions/copilot-thought-logging.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-thought-logging.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-thought-logging.instructions.md) | See process Copilot is following where you can edit this to reshape the interaction or save when follow up may be needed |
 | [Copilot Prompt Files Guidelines](../instructions/prompt.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fprompt.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fprompt.instructions.md) | Guidelines for creating high-quality prompt files for GitHub Copilot |
+| [Cpp Language Service Tools](../instructions/cpp-language-service-tools.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcpp-language-service-tools.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcpp-language-service-tools.instructions.md) | Tool specific coding standards and best practices |
 | [Custom Agent File Guidelines](../instructions/agents.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagents.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagents.instructions.md) | Guidelines for creating custom agent files for GitHub Copilot |
 | [Custom Instructions File Guidelines](../instructions/instructions.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Finstructions.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Finstructions.instructions.md) | Guidelines for creating high-quality custom instruction files for GitHub Copilot |
 | [Dart and Flutter](../instructions/dart-n-flutter.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdart-n-flutter.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdart-n-flutter.instructions.md) | Instructions for writing Dart and Flutter code following the official recommendations. |

instructions/cpp-language-service-tools.instructions.md

@@ -0,0 +1,346 @@
+---
+description: You are an expert at using C++ language service tools (GetSymbolReferences_CppTools, GetSymbolInfo_CppTools, GetSymbolCallHierarchy_CppTools). Instructions for calling C++ Tools for Copilot. When working with C++ code, you have access to powerful language service tools that provide accurate, IntelliSense-powered analysis. **Always prefer these tools over manual code inspection, text search, or guessing.**
+applyTo: **/*.cpp, **/*.h, **/*.hpp, **/*.cc, **/*.cxx, **/*.c
+---
+## Available C++ Tools
+
+You have access to three specialized C++ tools:
+
+1. **`GetSymbolInfo_CppTools`** - Find symbol definitions and get type details
+2. **`GetSymbolReferences_CppTools`** - Find ALL references to a symbol
+3. **`GetSymbolCallHierarchy_CppTools`** - Analyze function call relationships
+
+---
+
+## Mandatory Tool Usage Rules
+
+### Rule 1: ALWAYS Use GetSymbolReferences_CppTools for Symbol Usages
+
+**NEVER** rely on manual code inspection, `vscode_listCodeUsages`, `grep_search`, or `read_file` to find where a symbol is used.
+
+**ALWAYS** call `GetSymbolReferences_CppTools` when:
+- Renaming any symbol (function, variable, class, method, etc.)
+- Changing function signatures
+- Refactoring code
+- Understanding symbol impact
+- Finding all call sites
+- Identifying usage patterns
+- Any task involving "find all uses/usages/references/calls"
+
+**Why**: `GetSymbolReferences_CppTools` uses C++ IntelliSense and understands:
+- Overloaded functions
+- Template instantiations
+- Qualified vs unqualified names
+- Member function calls
+- Inherited member usage
+- Preprocessor-conditional code
+
+Text search tools will miss these or produce false positives.
+
+### Rule 2: ALWAYS Use GetSymbolCallHierarchy_CppTools for Function Changes
+
+Before modifying any function signature, **ALWAYS** call `GetSymbolCallHierarchy_CppTools` with `callsFrom=false` to find all callers.
+
+**Examples**:
+- Adding/removing function parameters
+- Changing parameter types
+- Changing return types
+- Making functions virtual
+- Converting to template functions
+
+**Why**: This ensures you update ALL call sites, not just the ones you can see.
+
+### Rule 3: ALWAYS Use GetSymbolInfo_CppTools to Understand Symbols
+
+Before working with unfamiliar code, **ALWAYS** call `GetSymbolInfo_CppTools` to:
+- Find where a symbol is defined
+- Understand class/struct memory layout
+- Get type information
+- Locate declarations
+
+**NEVER** assume you know what a symbol is without checking.
+
+---
+
+## Parameter Usage Guidelines
+
+### Symbol Names
+- **ALWAYS REQUIRED**: Provide the symbol name
+- Can be unqualified (`MyFunction`), partially qualified (`MyClass::MyMethod`), or fully qualified (`MyNamespace::MyClass::MyMethod`)
+- If you have a line number, the symbol should match what appears on that line
+
+### File Paths
+- **STRONGLY PREFERRED**: Always provide absolute file paths when available
+  - ✅ Good: `C:\Users\Project\src\main.cpp`
+  - ❌ Avoid: `src\main.cpp` (requires resolution, may fail)
+- If you have access to a file path, include it
+- If working with user-specified files, use their exact path
+
+### Line Numbers
+- **CRITICAL**: Line numbers are 1-based, NOT 0-based
+- **MANDATORY WORKFLOW** when you need a line number:
+  1. First call `read_file` to search for the symbol
+  2. Locate the symbol in the output
+  3. Note the EXACT line number from the output
+  4. VERIFY the line contains the symbol
+  5. Only then call the C++ tool with that line number
+- **NEVER** guess or estimate line numbers
+- If you don't have a line number, omit it - the tools will find the symbol
+
+### Minimal Information Strategy
+Start with minimal information and add more only if needed:
+1. **First attempt**: Symbol name only
+2. **If ambiguous**: Symbol name + file path
+3. **If still ambiguous**: Symbol name + file path + line number (after using `read_file`)
+
+---
+
+## Common Workflows
+
+### Renaming a Symbol
+
+```
+CORRECT workflow:
+1. Call GetSymbolReferences_CppTools with symbol name (and file path if available)
+2. Review ALL references returned
+3. Update symbol at definition location
+4. Update symbol at ALL reference locations
+
+INCORRECT workflow:
+❌ Using vscode_listCodeUsages or grep_search to find usages
+❌ Manually inspecting a few files
+❌ Assuming you know all the usages
+```
+
+### Changing a Function Signature
+
+```
+CORRECT workflow:
+1. Call GetSymbolInfo_CppTools to locate the function definition
+2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to find all callers
+3. Call GetSymbolReferences_CppTools to catch any additional references (function pointers, etc.)
+4. Update function definition
+5. Update ALL call sites with new signature
+
+INCORRECT workflow:
+❌ Changing the function without finding callers
+❌ Only updating visible call sites
+❌ Using text search to find calls
+```
+
+### Understanding Unfamiliar Code
+
+```
+CORRECT workflow:
+1. Call GetSymbolInfo_CppTools on key types/functions to understand definitions
+3. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to understand what a function does
+4. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to understand where a function is used
+
+INCORRECT workflow:
+❌ Reading code manually without tool assistance
+❌ Making assumptions about symbol meanings
+❌ Skipping hierarchy analysis
+```
+
+### Analyzing Function Dependencies
+
+```
+CORRECT workflow:
+1. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to see what the function calls (outgoing)
+2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to see what calls the function (incoming)
+3. Use this to understand code flow and dependencies
+
+INCORRECT workflow:
+❌ Manually reading through function body
+❌ Guessing at call patterns
+```
+
+---
+
+## Error Handling and Recovery
+
+### When You Get an Error Message
+
+**All error messages contain specific recovery instructions. ALWAYS follow them exactly.**
+
+#### "Symbol name is not valid" Error
+```
+Error: "The symbol name is not valid: it is either empty or null. Find a valid symbol name. Then call the [tool] tool again"
+
+Recovery:
+1. Ensure you provided a non-empty symbol name
+2. Check that the symbol name is spelled correctly
+3. Retry with valid symbol name
+```
+
+#### "File could not be found" Error
+```
+Error: "A file could not be found at the specified path. Compute the absolute path to the file. Then call the [tool] tool again."
+
+Recovery:
+1. Convert relative path to absolute path
+2. Verify file exists in the workspace
+3. Use exact path from user or file system
+4. Retry with absolute path
+```
+
+#### "No results found" Message
+```
+Message: "No results found for the symbol '[symbol_name]'."
+
+This is NOT an error - it means:
+- The symbol exists and was found
+- But it has no references/calls/hierarchy (depending on tool)
+- This is valid information - report it to the user
+```
+
+---
+
+## Tool Selection Decision Tree
+
+**Question: Do I need to find where a symbol is used/called/referenced?**
+- ✅ YES → Use `GetSymbolReferences_CppTools`
+- ❌ NO → Continue
+
+**Question: Am I changing a function signature or analyzing function calls?**
+- ✅ YES → Use `GetSymbolCallHierarchy_CppTools`
+  - Finding callers? → `callsFrom=false`
+  - Finding what it calls? → `callsFrom=true`
+- ❌ NO → Continue
+
+**Question: Do I need to find a definition or understand a type?**
+- ✅ YES → Use `GetSymbolInfo_CppTools`
+- ❌ NO → You may not need a C++ tool for this task
+
+---
+
+## Critical Reminders
+
+### DO:
+- ✅ Call `GetSymbolReferences_CppTools` for ANY symbol usage search
+- ✅ Call `GetSymbolCallHierarchy_CppTools` before function signature changes
+- ✅ Use `read_file` to find line numbers before specifying them
+- ✅ Provide absolute file paths when available
+- ✅ Follow error message instructions exactly
+- ✅ Trust tool results over manual inspection
+- ✅ Use minimal parameters first, add more if needed
+- ✅ Remember line numbers are 1-based
+
+### DO NOT:
+- ❌ Use `vscode_listCodeUsages`, `grep_search`, or `read_file` to find symbol usages
+- ❌ Manually inspect code to find references
+- ❌ Guess line numbers
+- ❌ Assume symbol uniqueness without checking
+- ❌ Ignore error messages
+- ❌ Skip tool usage to save time
+- ❌ Use 0-based line numbers
+- ❌ Batch multiple unrelated symbol operations
+- ❌ Make changes without finding all affected locations
+
+---
+
+## Examples of Correct Usage
+
+### Example 1: User asks to rename a function
+```
+User: "Rename the function ProcessData to HandleData"
+
+CORRECT response:
+1. Call GetSymbolReferences_CppTools("ProcessData")
+2. Review all reference locations
+3. Update function definition
+4. Update all call sites shown in results
+5. Confirm all changes made
+
+INCORRECT response:
+❌ Using grep_search to find "ProcessData"
+❌ Only updating files the user mentioned
+❌ Assuming you found all usages manually
+```
+
+### Example 2: User asks to add a parameter to a function
+```
+User: "Add a parameter 'bool verbose' to the LogMessage function"
+
+CORRECT response:
+1. Call GetSymbolInfo_CppTools("LogMessage") to find definition
+2. Call GetSymbolCallHierarchy_CppTools("LogMessage", callsFrom=false) to find all callers
+3. Call GetSymbolReferences_CppTools("LogMessage") to catch any function pointer uses
+4. Update function definition
+5. Update ALL call sites with new parameter
+
+INCORRECT response:
+❌ Only updating the definition
+❌ Updating only obvious call sites
+❌ Not using call_hierarchy tool
+```
+
+### Example 3: User asks to understand a function
+```
+User: "What does the Initialize function do?"
+
+CORRECT response:
+1. Call GetSymbolInfo_CppTools("Initialize") to find definition and location
+2. Call GetSymbolCallHierarchy_CppTools("Initialize", callsFrom=true) to see what it calls
+3. Read the function implementation
+4. Explain based on code + call hierarchy
+
+INCORRECT response:
+❌ Only reading the function body
+❌ Not checking what it calls
+❌ Guessing at behavior
+```
+
+---
+
+## Performance and Best Practices
+
+### Efficient Tool Usage
+- Call tools in parallel when analyzing multiple independent symbols
+- Use file paths to speed up symbol resolution
+- Provide context to narrow searches
+
+### Iterative Refinement
+- If first tool call is ambiguous, add file path
+- If still ambiguous, use `read_file` to find exact line
+- Tools are designed for iteration
+
+### Understanding Results
+- **Empty results are valid**: "No results found" means the symbol has no references/calls
+- **Multiple results are common**: C++ has overloading, templates, namespaces
+- **Trust the tools**: IntelliSense knows C++ semantics better than text search
+
+---
+
+## Integration with Other Tools
+
+### When to use read_file
+- **ONLY** for finding line numbers before calling C++ tools
+- **ONLY** for reading implementation details after locating symbols
+- **NEVER** for finding symbol usages (use `GetSymbolReferences_CppTools` instead)
+
+### When to use vscode_listCodeUsages/grep_search
+- Finding string literals or comments
+- Searching non-C++ files
+- Pattern matching in configuration files
+- **NEVER** for finding C++ symbol usages
+
+### When to use semantic_search
+- Finding code based on conceptual queries
+- Locating relevant files in large codebases
+- Understanding project structure
+- **Then** use C++ tools for precise symbol analysis
+
+---
+
+## Summary
+
+**The golden rule**: When working with C++ code, think "tool first, manual inspection later."
+
+1. **Symbol usages?** → `GetSymbolReferences_CppTools`
+2. **Function calls?** → `GetSymbolCallHierarchy_CppTools`
+3. **Symbol definition?** → `GetSymbolInfo_CppTools`
+
+These tools are your primary interface to C++ code understanding. Use them liberally and often. They are fast, accurate, and understand C++ semantics that text search cannot capture.
+
+**Your success metric**: Did I use the right C++ tool for every symbol-related task?