6 Mandatory Protocols for Using GitHub Copilot in Technical Work
6.1 Purpose and Principles
GitHub Copilot is a powerful assistant that can increase productivity, generate boilerplate code quickly, and support experimentation. However, Copilot is not a substitute for engineering judgment, critical thinking, or expertise in R/Stata. Without discipline, Copilot can also introduce inefficiency, unnecessary complexity, hallucinated dependencies, and silent errors. This document establishes:
- Mandatory protocols for how Copilot must be used in all GPID technical work.
- A unified system of Copilot prompt files, named
gpid-proto-*, which encode these protocols into reproducible steps.
- Clear instructions on how to install, update, and use these prompt files across all GPID projects.
Team leads will verify compliance during code reviews.
6.2 GPID Copilot Prompt System
To ensure consistency, the GPID team uses shared Github Copilot prompt files stored in a central repository. These prompt files automate the workflows described in this document.
6.2.1 What Are GPID Prompt Files?
Prompt files are .prompt.md files that define reusable Github Copilot commands.
They appear in VS Code or Positron when you type / in Github Copilot Chat.
Each GPID protocol prompt begins with the prefix gpid-proto-
Examples:
/gpid-proto-start-task
/gpid-proto-explain-code
/gpid-proto-document-code
/gpid-proto-review-efficiency
/gpid-proto-tests-checklist
/gpid-proto-deps-risk
/gpid-proto-self-critique
/gpid-proto-wrap-task
These commands help you follow the mandatory protocols with minimal effort.
6.2.2 Where the Prompt Files Live
The shared prompts are stored in the repository GPID-WB/copilot-prompts. The prompt files for these protocols are in the folder prompts/
prompts/
gpid-proto-start-task.prompt.md
gpid-proto-explain-code.prompt.md
gpid-proto-document-code.prompt.md
gpid-proto-review-efficiency.prompt.md
gpid-proto-tests-checklist.prompt.md
gpid-proto-deps-risk.prompt.md
gpid-proto-self-critique.prompt.md
gpid-proto-wrap-task.prompt.md
These prompts are global tools used in every GPID technical project.
6.2.3 One-Time Installation (Per Developer)
Each team member must clone the prompts repository locally. For the rest of this document, we assume you clone it to:
C:\Users\<USERNAME>\OneDrive - WBG\GPID-team\copilot-prompts6.2.4 Registering Prompt Files in VS Code / Positron
After cloning, you must tell Github Copilot where to find the shared prompts by modifying the user settings. This can by done in multiple ways, but we recommend the following:
- In VS Code/Positron, open settings via the gear icon in the lower left corner or by hitting
Ctrl + ,. - Search for “prompt files location” (without quotes).
- Hit “add item” and add the full path to the
promptsfolder in your local clone of the repository adding theprotocols/subfolder.
- Restart VS Code/Positron.
NOW: Typing / in Github Copilot Chat will show all GPID protocol prompts.
6.2.5 Updating Prompt Files
Whenever a prompt file changes, you will be notified. However, the best practice is to regularly update your local copy. You can do it by opening the copilot-prompts folder in a terminal and running git pull, opening the whole folder in Positron and VScode and sync the changes or by using script similar to this:
cd "C:\Users\USERNAME\OneDrive - WBG\GPID-team\copilot-prompts"
git pull6.3 The GPID Protocol Prompts
The following sections describe each mandatory protocol and the corresponding gpid-proto-* prompt that should be used.
Using the prompts is simple. You just need to type the prompt command in Github Copilot Chat.
Example:
/gpid-proto-start-taskGithub Copilot will ask for the necessary information and then guide you through the protocol.
Protocol 1 — Documenting Your Work With Github Copilot
Prompt:
/gpid-proto-start-taskPurpose
Every Copilot-assisted task must produce a clear, transparent trail of:
- What was done
- Why decisions were made
- What dependencies were added or removed
- How the final code works
What It Does
When you run /gpid-proto-start-task, Github Copilot:
Asks you for:
- Task name
- Short description
Logs these clearly and begins a running summary of:
- key prompts
- major decisions
- assumptions
- dependencies added/removed
Keeps the summary alive throughout the task in the file
copilot_logs/LOG_${TASK_NAME}.md.
You do not need to structure this manually — the prompt enforces consistency.
Latest GPID prompt file
You are assisting a World Bank technical team (R + Stata) following strict Copilot protocols.
We are starting a new Copilot-assisted task.
Follow this protocol:
- Ask me for:
- a short task name (TASK_NAME)
- a one-sentence description of the task (TASK_DESCRIPTION)
- Once I answer, restate both clearly, but do not try to solve the task yet. Use this format:
Task name: ...Description: ...
- Create two files for task tracking:
- Task log file at
copilot_logs/LOG_${TASK_NAME}.mdcontaining:- Task name and description
- Initial context and relevant information you identify
- A timestamp for task initialization
- This log will be used to track progress throughout the task
- Note: As we work, you may add a “To Do List” section to track follow-up tasks, improvements, or issues discovered during the current task
- Current task marker at
.current_taskcontaining only the task name (for quick reference across the session)
- Task log file at
- From that point on, keep a concise running summary of our interaction, including:
- major prompts I send
- important decisions we make
- dependencies added or removed
- assumptions or limitations we identify
- Do not generate the final report yet.
Your role after the initial questions is, only when asked, to:- clarify ambiguities
- help design the approach
- generate and refine code/tests according to our protocols.
Assume that at the end of the task I will call another prompt (/wrap-task) to generate the final Markdown summary under copilot_logs/TASK_NAME.md.
Protocol 2 — Logging progress of the task
Prompt:
/gpid-proto-log-updatePurpose
Keep the copilot_logs/LOG_${TASK_NAME}.md updated with regular progress updates.
What It Does
When you run /gpid-proto-log-update, Github Copilot will append an update to the running summary in copilot_logs/LOG_${TASK_NAME}.md with:
- Timestamp: Include the current date and time in ISO format (YYYY-MM-DD HH:MM:SS)
- Progress summary: Key accomplishments since the last update
- Challenges encountered: Any blockers, issues, or difficulties faced
- Changes to plan: Deviations from the original approach or scope
- Next steps: What will be tackled next
Latest GPID prompt file
We are updating the task progress log for an ongoing Copilot-assisted task.
6.4 Retrieving the task name
Locate the task name you provided at the start of this conversation session. Confirm it by restating: > Task name: [TASK_NAME]
Then proceed to update copilot_logs/LOG_${TASK_NAME}.md where ${TASK_NAME} is that task name.
Fallback: If you cannot locate the task name in the conversation history, read .current_task to retrieve it. If that file doesn’t exist either, ask the user to provide the task name with a single prompt: Please provide the TASK_NAME to update copilot_logs/LOG_TASK_NAME.md.
After confirming the task name, proceed with the update:
6.5 Update the log file copilot_logs/LOG_${TASK_NAME}.md:
Open and review the existing log file to understand its current state and structure.
Append a new update section with:
- Timestamp: Include the current date and time in ISO format (YYYY-MM-DD HH:MM:SS)
- Progress summary: Key accomplishments since the last update
- Challenges encountered: Any blockers, issues, or difficulties faced
- Changes to plan: Deviations from the original approach or scope
- Next steps: What will be tackled next
Update or create the To Do List section:
- Review the conversation since the last log update (or since task initialization)
- Identify potential follow-up tasks, improvements, technical debt, or issues discovered
- Before adding to the log, present your suggested to-do items to the user in a clear list format
- Ask: “I suggest adding these items to the To Do List. Would you like me to include them, or would you like to modify/add others?”
- Only after user confirmation, add/update the “## To Do List” section in the log
- If a To Do List section already exists, preserve completed items and update with new suggestions
Maintain organization by:
- Using clear section headings for each update
- Keeping entries concise but informative
- Ensuring the log remains chronologically ordered
- Using consistent formatting throughout
Preserve all prior content: Do not remove or modify previous updates; only append new information.
Return the updated copilot_logs/LOG_${TASK_NAME}.md file with the new update appended.
Protocol 3 — Making the Code Understandable
Prompts:
/gpid-proto-explain-code
/gpid-proto-document-codePurpose
Github Copilot may generate correct code, but not always readable code. These prompts ensure that the logic, intention, and structure are thoroughly documented.
What They Do
/gpid-proto-explain-code
- Asks what function/file you want explained
- Produces a step-by-step technical explanation
- Lists assumptions
- Identifies failure points
Latest GPID prompt file
You will be asked to explain a function, test file, or script (usually R or Stata).
If the context is ambiguous, first ask me what code or file you should focus on (e.g., current selection, specific function, or file).
Then follow this protocol:
- High-level overview
- In 3–5 sentences, explain what the code does conceptually.
- Step-by-step explanation
- Walk through the major blocks of the code.
- Focus on logic and structure rather than line-by-line commentary.
- Assumptions
- Explicitly list assumptions about:
- input types, shapes, and ranges
- required columns / variables
- expected data structure (e.g., data.table, Stata dataset)
- external dependencies or files
- Explicitly list assumptions about:
- Failure points
- Identify where the code might break or behave incorrectly:
- missing or malformed inputs
- edge cases (empty data, small N, extreme values)
- performance pitfalls on large data
- Identify where the code might break or behave incorrectly:
Return your explanation in clean Markdown with headings:
- High-level overview
- Step-by-step explanation
- Assumptions
- Potential failure points
This text should be ready to paste into the task summary.
/gpid-proto-document-code
- Adds in-code comments (the “what” and the “why”)
- Adds full Roxygen2 documentation (for R code)
- Produces a plain-language explanation for the task summary
Latest GPID prompt file
You will be given one or more functions or scripts, mainly in R (often using data.table, collapse, rlang) and sometimes Stata.
If it is unclear what code to document, first ask me which function/file/selection to use.
Then follow this protocol:
- In-code comments
- Add clear, human-readable comments that explain:
- what each major block does
- why this approach or pattern is appropriate
- important trade-offs or design decisions
- Avoid trivial “this line adds 1” comments. Focus on intent.
- Add clear, human-readable comments that explain:
- Roxygen2 (for R functions)
- For each relevant R function, add or update:
@title@description@param@return@examples(when helpful and not trivial)@import/@importFromonly when truly needed.
- Prefer our usual stack (
data.table,collapse,rlang) when appropriate.
- For each relevant R function, add or update:
- Plain-language explanation
- At the end, write a short, plain-language explanation of how the main function(s) work, suitable for a teammate reading them for the first time.
Return: 1. The updated code (with comments and Roxygen2 tags).
2. The plain-language explanation as a separate Markdown section that can be added to the task summary.
Protocol 4 — Code Review and Efficiency Check
Prompt:
/gpid-proto-review-efficiencyPurpose
Before testing, every piece of Copilot-generated code must undergo an efficiency audit.
What It Does
The prompt reviews code for:
- redundant logic
- unnecessary copies
- over-nested structures
- unused variables
- dependency creep
- overly complex or fragile patterns
And provides clear, actionable improvements.
Latest GPID prompt file
You are reviewing Copilot-assisted code for efficiency, simplicity, and maintainability.
If it is unclear what to review, first ask me which function/file/selection to analyze.
Then:
- Scan for inefficiencies
- redundant or duplicated logic
- unnecessary copies of large objects
- loops that could be vectorized or replaced by
data.table/collapseoperations - deeply nested
if/elseor loops that could be simplified
- Find unused or dead code
- unused variables
- unreachable logic
- old commented-out or experimental blocks that should be removed
- Check dependencies
- identify new or heavy dependencies
- suggest removing or replacing packages that are not truly needed
- prefer our established stack when reasonable
- Propose concrete improvements For each issue:
- describe the problem
- propose a specific improvement
- briefly explain why it matters (performance, clarity, maintainability, robustness)
Return a structured Markdown report with headings like: - Inefficiencies
- Unnecessary complexity
- Dead or unused code
- Dependency issues
- Recommended improvements
Protocol 5 — Testing and Edge Cases
Prompt:
/gpid-proto-tests-checklistPurpose
No Copilot-generated code is accepted without thorough testing.
What It does
- A validation checklist
testthatunit tests (for R)- Stata assertions (if needed)
- Optional performance tests
All structured for direct inclusion in your PR.
Latest GPID prompt file
You will help design validation for a function, module, or script.
If it is unclear what to validate, first ask me which function/file/selection to focus on.
Then follow this protocol:
- Validation checklist
- List:
- expected inputs and outputs
- required dependencies
- main assumptions
- potential failure points
- edge cases that must be tested
- List:
- R unit tests (
testthat)- When the code is in R, generate
testthattests that cover:- normal cases
- edge cases
- wrong input types
- missing values
- extreme or unusual data scenarios
- When the code is in R, generate
- Stata tests
- When the code is in Stata, generate a do-file with assertions/checks for:
- realistic data
- corner cases
- unexpected or malformed inputs
- When the code is in Stata, generate a do-file with assertions/checks for:
- Performance-sensitive checks (optional)
- If the code is performance-critical or uses large data, propose tests that:
- stress memory usage
- expose slow operations or unnecessary copies
- If the code is performance-critical or uses large data, propose tests that:
Return: - the validation checklist (Markdown)
- the test code (R testthat or Stata do-file) ready to be added to the repository
Protocol 6 — Dependencies, Risks, and Safety
Prompt:
/gpid-proto-deps-riskPurpose
Ensure that dependencies are justified, safe, and aligned with team standards.
What It Does
- Lists all dependencies
- Explains why each is needed
- Flags unnecessary packages
- Checks compatibility with
data.table,collapse, andrlang - Identifies unsafe patterns (I/O, file paths, etc.)
Latest GPID prompt file
You are reviewing dependencies and risks for Copilot-assisted code in R or Stata.
If it is unclear what code to inspect, ask me which file/selection to analyze.
Then:
- Dependency analysis
- List all external packages/dependencies used or introduced.
- For each, explain briefly why it is needed.
- Identify dependencies that are:
- unnecessary
- overlapping/redundant
- heavier than needed for the task
- Suggest simplifications or removals where possible.
- Compatibility with our preferred stack (R)
- Check for conflicts or unnecessary overlaps with:
data.tablecollapserlang
- When reasonable, suggest implementations that better fit this stack.
- Check for conflicts or unnecessary overlaps with:
- Security and stability
- Flag any:
- unsafe file I/O patterns
- hard-coded paths, credentials, or URLs
- fragile assumptions about external systems or files
- Provide concrete suggestions to mitigate each risk.
- Flag any:
Return findings in Markdown with sections: - Dependencies and justification
- Opportunities to simplify dependencies
- Compatibility with preferred stack
- Security and stability concerns
- Recommended mitigations
Protocol 7 — Self-Critique and Robustness Review
Prompt:
/gpid-proto-self-critiquePurpose
Github Copilot is surprisingly good at critiquing its own work when prompted correctly.
This step often finds issues humans miss.
What It Does
- Reviews code as if performing a formal code review
- Identifies inefficiencies
- Points out risky assumptions
- Suggests simplifications
- Produces a concise summary of strengths, risks, and recommended improvements
Latest GPID prompt file
You are performing a self-critique of Copilot-assisted code, as if you were a human reviewer.
If it is unclear what code to review, first ask me which function/file/selection to critique.
Then:
- Identify inefficiencies
- redundant code
- unnecessary work
- poor data handling
- operations that will be slow or memory-heavy on large data
- Complexity issues
- over-nested logic
- confusing control flow
- unneeded abstractions or indirection
- Risky assumptions
- fragile expectations about inputs
- poor handling of NA/missing values
- edge cases likely to break the code
- Opportunities to use our preferred stack
- places where
data.table,collapse, orrlang(in R) would lead to clearer or more efficient code, when appropriate for the project.
- places where
- Concrete improvements
- For each issue:
- describe the problem
- propose a specific improvement
- explain its impact (performance, readability, robustness, maintainability)
- For each issue:
End with a short summary: - Key strengths
- Key risks
- Top 3 improvements to implement next
Protocol 8 — Producing the Final Validation Bundle
Prompt:
/gpid-proto-wrap-taskPurpose
Every Copilot-assisted task ends with a final Markdown summary stored under:
copilot_logs/TASK_NAME.mdWhat It Does
- Task overview
- Step-by-step technical explanation
- Plain-language overview
- In-code comments summary
- Roxygen2 documentation summary
- Validation checklist
- Unit tests and edge cases
- Error-handling strategy
- Dependency and risk analysis
- Self-critique findings
- Remaining TODOs
This file must always be included in your PR.
Latest GPID prompt file
We have reached the end of a Copilot-assisted task.
6.6 Retrieving the task name
Locate the task name you provided at the start of this conversation session. Confirm it by restating: > Task name: [TASK_NAME]
Then proceed to work with copilot_logs/TASK_NAME.md and copilot_logs/LOG_${TASK_NAME}.md where ${TASK_NAME} is that task name.
Fallback: If you cannot locate the task name in the conversation history, read .current_task to retrieve it. If that file doesn’t exist either, ask the user to provide the task name with a single prompt: Please provide a short TASK_NAME to save the final report as copilot_logs/TASK_NAME.md.
After confirming the task name, proceed with the task completion:
6.7 Step 1: Review the task log
Before generating the final summary, carefully review the existing task log file at copilot_logs/LOG_${TASK_NAME}.md. This file contains: - The task initialization details - All progress updates recorded throughout the task - Challenges encountered and solutions implemented - Changes made to the original plan
Use this log to ensure that all relevant information, decisions, and important details are captured in the final summary. Verify that no critical information is overlooked.
6.8 Step 2: Generate the final Markdown report
Using our full conversation, your running summary, and the reviewed task log, generate a Markdown report suitable for saving as copilot_logs/TASK_NAME.md. This final report should synthesize all work completed and provide clear documentation for future reference.
Include:
- Executive Summary
- brief overview of what the task accomplished
- primary goals achieved
- overall status (complete, in-progress, blocked, etc.)
- Task Overview
- what the task was about
- main files/functions affected
- major decisions and trade-offs made
- Technical Explanation
- step-by-step description of how the code works
- important algorithmic or design choices
- any performance considerations
- rationale for technical decisions
- Plain-Language Overview
- why the code exists
- how a teammate should use it
- non-technical explanation of the behavior
- Documentation and Comments
- confirmation of in-code comments and Roxygen2 docs (for R)
- any important notes for future maintainers
- known limitations or caveats
- Validation and Testing
- validation checklist with status for each item
- unit tests and edge cases covered (summarize what is tested)
- error-handling strategy (how invalid or unexpected inputs are handled)
- performance-sensitive tests, if applicable
- Dependencies and Risk Analysis
- summary of dependency decisions
- key security/stability considerations
- any external factors that could affect the work
- Self-Critique and Follow-Ups
- main issues uncovered by reviews/self-critique
- remaining TODOs or recommended future improvements
- potential enhancements or optimizations for next iteration
- To Do List: Extract any to-do items from the task log (
copilot_logs/LOG_${TASK_NAME}.md)- Before finalizing, present the compiled to-do list to the user
- Ask: “Here are the to-do items identified during this task. Would you like to add, remove, or modify any items before I include them in the final report?”
- Wait for user confirmation or modifications before proceeding
Return only the Markdown document, and save it as copilot_logs/${input}.md.
This final report, combined with the task log (copilot_logs/LOG_${input}.md), provides a complete record of the task work and can serve as reference material for future similar tasks.
6.9 Step 3: Clean up temporary files
After creating copilot_logs/TASK_NAME.md, ask the user: “May I delete the temporary .current_task marker file to keep the project clean?”
If the user agrees (or does not object), delete .current_task. If they prefer to keep it or it doesn’t exist, proceed without action.
If you’re working in an R package, make sure to include the copilot_logs folder in your .Rbuildignore file to prevent it from being included in the package build.
You can do it by
- executing
usethis::use_build_ignore("copilot_logs")or, - by manually adding the line
^copilot_logs/$to the.Rbuildignorefile.