1. Open the Chat view (Ctrl+Alt+I) and make sure you are in Ask Mode

2. Paste the following prompt and review the response:

   I'm new to the ODrive firmware project. Please answer the following:
   
   1. **Project overview** — What is this project, what hardware does it
      target, and what is the overall architecture (RTOS, control loops,
      communication layers)?
   
   2. **Dependencies** — List every external dependency the firmware relies
      on (RTOS, HAL libraries, driver ICs, third-party libs, build tools).
      For each, note the version or source if visible in the repo.
   
   3. **Project layout** — Describe the directory structure. What lives in
      Firmware/MotorControl/, Firmware/Drivers/, Firmware/Board/,
      Firmware/communication/, tools/, and docs/? How do they relate?
   
   4. **Adding a new module** — If I wanted to add a new control module
      (e.g., a thermal protection module), which files and build
      configuration would I need to create or modify? Are there
      registration steps, header includes, or build-system entries
      (Tup/Makefile) that must be updated?
   
   #codebase

3. Read through the response. Verify the information by spot-checking a few of the directories and files mentioned.

4. Ask a follow-up to go deeper on anything that surprised you, for example:

   Which third-party libraries are vendored directly in the repo versus
   pulled in during the build? #codebase

Success Criteria:

• ✅ Can describe the ODrive firmware architecture in one paragraph
• ✅ Know at least 4 external dependencies and where they live
• ✅ Understand which files to touch when adding a new module

Key things the response should cover:

Good follow-up prompts:

Show me an example of how an existing module (e.g., Thermistor or
Encoder) is wired into the Axis class. I want to follow the same
pattern for my new module. #codebase

1. Open Firmware/MotorControl/utils.cpp (or any .cpp file)
2. Position your cursor at the end of the file
3. Type a comment, then start the function signature:

   // Clamp a float value between min and max bounds
   float clamp_float(

4. Observe the inline suggestion — press Tab to accept
5. Try another: type a comment describing an ISR-safe ring buffer, then start the struct

Tips for better suggestions:

• Write a descriptive comment before the code
• Use meaningful names: calculate_torque not calc
• Have related files open in editor tabs for context

Success Criteria:

• ✅ Received and accepted an inline suggestion
• ✅ Comment-driven suggestion matched your intent
• ✅ Understand how to accept (Tab) or reject (Escape)

Comments that produce good inline completions:

// Calculate motor torque from phase current using the torque constant Kt
// Input: phase_current in amps, torque_constant in Nm/A
// Returns: torque in Nm
float calculate_torque(float phase_current, float torque_constant) {

// Convert encoder counts to radians
// encoder_cpr: counts per revolution
float counts_to_radians(int32_t counts, uint32_t encoder_cpr) {

The more specific your comment, the better the suggestion. Including parameter names, units, and constraints guides Copilot effectively.

Part A — Templates:

1. Open Chat view (Ctrl+Alt+I) in Ask Mode
2. Ask:

   Explain the C++ templates used in #file:Firmware/communication/can/can_helpers.hpp.
   What are the template parameters and how does template specialization
   work here? Explain it as if I'm coming from a C or Ada background.

Part B — Macros:

3. Ask:

   Find all preprocessor macros (#define) in #file:Firmware/Board/v3/Inc/main.h.
   Explain each macro — what does it control, and what are the risks
   of changing its value on a live motor controller?

Part C — Pointers & Memory:

4. Select a function that uses raw pointers (e.g., in low_level.cpp or motor.cpp)
5. Press Ctrl+I and type: /explain
6. Follow up: “What are the pointer ownership semantics here? Could this cause a dangling pointer or use-after-free?”

Success Criteria:

• ✅ Can explain what a template parameter does in plain English
• ✅ Understand at least 3 macros and their effects
• ✅ Identified pointer ownership in one function

Effective prompts for C++ constructs:

For templates:

What does `template<typename T>` mean in this context? Show me a
concrete example with actual types substituted in.

For macros:

List every #define in this file. For each, tell me:
1. What it controls
2. Default value
3. What breaks if I change it

For pointers:

This function takes a raw pointer parameter. Explain:
- Who owns the pointed-to memory?
- When is it allocated and freed?
- Is it safe to cache this pointer across function calls?

Large C++ codebases (common in aerospace and embedded) are hard to navigate. Use Copilot to map them quickly.

1. Open Chat view (Ctrl+Alt+I)

2. Trace an error code:

   Where is ERROR_PHASE_RESISTANCE_OUT_OF_RANGE defined in this project?
   Trace every file where it is raised or checked. Show me the full
   call chain from detection to user notification. #codebase

3. Map class relationships:

   Explain the relationship between the Axis, Motor, Encoder, and
   Controller classes in #file:Firmware/MotorControl. How are they
   composed? Draw a Mermaid class diagram.

4. Find patterns:

   Find all interrupt handlers (functions ending with _IRQHandler) in
   the firmware. For each, list what peripheral it handles and which
   file it's in. #codebase

Success Criteria:

• ✅ Traced an error code from definition to every usage
• ✅ Understand the class hierarchy in MotorControl
• ✅ Found interrupt handlers across the codebase

Effective navigation prompts:

Show me every file that #includes axis.hpp. What does each file
use from it? #codebase

Trace the data flow of a position setpoint from USB input through
the control loop to PWM output. List every function it passes
through. #codebase

What state machine controls the motor startup sequence? Show me the
states, transitions, and which file implements each. #codebase

Part A — /explain:

1. Open Firmware/MotorControl/foc.cpp
2. Select the FieldOrientedController::update function or AlphaBetaFrameController::on_measurement
3. Press Ctrl+I and type: /explain
4. Read the explanation, then ask a follow-up:

   What is the Clarke transform doing here? Explain the math
   in simple terms with the actual variable names from this code.

Part B — /fix:

1. Open Firmware/MotorControl/controller.cpp
2. Select a section of code
3. Press Ctrl+I and type:

   /fix Check this code for:
   - Integer overflow on arithmetic operations
   - Missing null checks on pointer dereferences
   - Race conditions if called from ISR context

4. Review the suggested fix — does it make sense for embedded?

Success Criteria:

• ✅ Got a clear explanation of a complex function
• ✅ /fix identified at least one real or potential issue
• ✅ Understand the difference between /explain (read-only) and /fix (suggests changes)

Targeted /explain prompts:

/explain Focus on the control theory: what algorithm is this
implementing, what are the inputs/outputs, and what are the units?

Targeted /fix prompts for embedded C++:

/fix This code runs in a high-priority ISR. Check for:
- Dynamic memory allocation (malloc/new)
- Blocking calls (mutexes, printf)
- Shared variable access without volatile or atomics

/fix Refactor this to use static allocation instead of dynamic.
This runs on a microcontroller with 128KB RAM.

1. Open Firmware/MotorControl/motor.cpp
2. Introduce a deliberate error — for example, change a variable type:

   // Change a float to int to cause a narrowing conversion error
   // Or remove a semicolon, break a template parameter, etc.

3. Save the file — observe the squiggly error underlines
4. Hover over the error to see the compiler message
5. Select the line with the error, press Ctrl+I and type: /fix
6. Alternatively, paste the compiler error into Chat:

   I got this compiler error:
   error: cannot convert 'int' to 'float*' in assignment
   
   Explain what this means, why it happened, and how to fix it.
   The code is in #file:Firmware/MotorControl/motor.cpp

7. Undo your deliberate error after the exercise (Ctrl+Z)

Real-World Scenario: Try asking about a template error:

Explain this error message:
error: no matching function for call to 'std::tuple<int, float>::get<2>()'
note: candidate template ignored: invalid explicitly-specified argument

What does "candidate template ignored" mean and how do I fix it?

Success Criteria:

• ✅ Copilot correctly explained a compiler error
• ✅ /fix generated a valid correction
• ✅ Understand how to paste terminal error output into Chat for diagnosis

For cryptic template errors:

This template error is 50 lines long. Summarize:
1. What is the root cause (first error only)?
2. Which line of MY code caused it?
3. What's the fix?
Ignore the template instantiation backtrace.

For linker errors:

I'm getting "undefined reference to `Motor::update()'".
This is a linker error, not a compile error. Explain the difference
and show me how to check that motor.cpp is included in the build.

1. Open Chat view in Ask Mode

2. Null pointer analysis:

   Analyze #file:Firmware/MotorControl/axis.cpp for potential null
   pointer dereferences. Which pointers are used without null checks?
   For each, show the line number and suggest a safe alternative.

3. Memory issue analysis:

   Search for all uses of malloc, new, or free in the Firmware/ directory.
   Are any of these in ISR context or time-critical loops?
   Suggest replacements using static allocation. #codebase

4. Undefined behavior:

   Check #file:Firmware/MotorControl/controller.cpp for potential
   undefined behavior:
   - Signed integer overflow
   - Uninitialized variables
   - Out-of-bounds array access
   - Strict aliasing violations

Success Criteria:

• ✅ Identified at least one potential null pointer issue
• ✅ Found dynamic allocation usage (if any) and understand why it’s risky in embedded
• ✅ Understand what “undefined behavior” means in C++ and why it matters

Memory-focused prompts:

Is there any stack overflow risk in this function? Estimate the
stack usage and compare it to a typical FreeRTOS task stack size
of 1024 words.

This code stores a pointer to a local variable. Explain why this
is a dangling pointer bug and how to fix it.

Find all global mutable variables in #file:motor.cpp. Which ones
are accessed from both ISR and task context? Are they protected
with volatile, atomics, or critical sections?

1. Ask @terminal about the build system:

   @terminal What is the exact command to build the ODrive firmware
   for the v3.6-56V board? What does each flag mean?

2. If you have build errors in the terminal, select the error text, then:

   • Right-click → “Copilot” → “Explain This”
   • Or copy-paste into Chat:

     I ran the build and got this terminal output. Explain the errors
     and suggest fixes:
     
     [paste terminal output here]

3. Use @terminal for tool commands:

   @terminal How do I run the Python test suite for ODrive?
   Show me the command and explain how to run just one test file.

4. Chain the workflow — fix and rebuild:

   The build error says "undefined reference to Motor::check_timing".
   Use /fix to add the missing function definition, then show me
   the command to rebuild.

Success Criteria:

• ✅ Used @terminal to get a build command
• ✅ Can explain a build error using Chat
• ✅ Understand the fix → rebuild workflow

@terminal examples:

@terminal Show me how to use arm-none-eabi-objdump to disassemble
a specific function from the firmware .elf file

@terminal I see "region 'FLASH' overflowed by 1234 bytes" in my
build output. What does this mean and how do I reduce firmware size?

@terminal Generate a one-liner to find all .cpp files in Firmware/
that have been modified in the last 24 hours

1. Open Chat view (Ctrl+Alt+I)
2. Ask: “Explain this project in simple, layman’s terms. What is the high-level functionality?”
3. Follow up: “What are the key external dependencies?”
4. Follow up: “Show me the main entry point and explain the startup sequence”

Success Criteria:

• ✅ Understand the project’s purpose
• ✅ Know the folder structure
• ✅ Identify key dependencies

Sample prompts that work well:

Explain this project in simple, layman's terms. What is the high-level 
functionality? Provide a tour of the folder structure.

What are the external dependencies in this project? List them with 
a brief description of what each provides.

Where is the main entry point? Walk me through the startup sequence 
from power-on to ready state.

1. Open a C++ source file (e.g., motor.cpp)
2. Find a function without documentation
3. Select the function signature
4. Press Ctrl+I and type: /doc
5. Review and accept the generated Doxygen comments

Success Criteria:

• ✅ Function has @brief description
• ✅ Parameters are documented with @param
• ✅ Return value documented with @return

Alternative approaches:

Add Doxygen-style comments to this function, including @brief, 
@param for each parameter, and @return.

You can also be more specific:

Document this function for embedded developers. Include:
- Purpose and when to call it
- Parameter ranges and units
- Return value meaning
- Thread-safety notes
- Example usage

1. Find code with a known issue or warning
2. Select the problematic code
3. Press Ctrl+I and type: /fix
4. Review the suggested fix
5. Accept or refine the solution

Success Criteria:

• ✅ Issue is correctly identified
• ✅ Fix is appropriate and complete
• ✅ Code compiles without warnings

For more context-aware fixes:

/fix This code has a race condition when accessed from ISR context. 
Suggest a thread-safe alternative.

For embedded-specific fixes:

/fix This uses dynamic allocation. Refactor to use static allocation 
appropriate for embedded systems.

1. Open a file with a utility function
2. Select the function you want to test
3. In Chat, type: /tests
4. Review the generated test cases
5. Ask for additional edge cases if needed

Success Criteria:

• ✅ Tests cover normal cases
• ✅ Tests cover edge cases
• ✅ Tests follow project testing framework

For comprehensive test generation:

/tests Generate doctest unit tests for this function. Include:
- Normal operation with typical inputs
- Edge cases (zero, max values, boundaries)
- Error conditions and invalid inputs
- Performance-sensitive cases if applicable

Follow-up for more tests:

Add tests for thread-safety: what happens if this function is 
called from multiple threads simultaneously?

1. In Chat, ask: @workspace How does the motor control loop work?
2. Follow up: @workspace Show me the relationship between Axis, Motor, and Encoder classes
3. Ask: @workspace Where are errors defined and how are they propagated?

Success Criteria:

• ✅ Understand control loop architecture
• ✅ See class relationships
• ✅ Understand error handling patterns

Effective @workspace queries:

@workspace Explain the high-level architecture of Firmware/MotorControl. 
How do the Axis, Motor, and Encoder classes interact during the control loop?

@workspace Create a Mermaid diagram showing the state machine in axis.cpp

@workspace What error codes are defined and where are they raised? 
Show me the error propagation pattern.