Fixed numbering and other clarifications

Author: GeekTrainer

docs/3-custom-instructions.md

@@ -7,7 +7,7 @@ Context is key across many aspects of life, and when working with generative AI.
 
 In this exercise, you will learn how to:
 
-- provide Copilot with project-specific context, coding guidelines and documentation standards using custom instructions (.github/copilot-instructions.md).
+- provide Copilot with project-specific context, coding guidelines and documentation standards using custom instructions `.github/copilot-instructions.md`.
 - use instruction files to guide Copilot for repetitive or templated tasks.
 - implement both repository-wide instructions and task-specific instructions.
 
@@ -17,8 +17,7 @@ As any good dev shop, Tailspin Toys has a set of guidelines and requirements for
 
 - API always needs unit tests.
 - UI should be in dark mode and have a modern feel.
-- Documentation should be added to code in the form of docstrings.
-- All newly created files should have a comment header describing what it does.
+- Documentation should be added to code in the form of docstrings and header comments.
 
 Through the use of instruction files you'll ensure Copilot has the right information to perform the tasks in alignment with the practices highlighted.
 
@@ -50,10 +49,10 @@ There are two types of instructions files:
 
 To see the impact of custom instructions, we will start by sending a prompt with the current version of the files. We'll then make some updates, send the same prompt again, and note the difference.
 
-1. Open the GitHub codespace if not already open.
-2. Close any open files in your codespace from the previous exercises.
+1. Return to your codespace.
+2. Close any open files in your codespace from the previous exercises. This will ensure Copilot has the context we want it to have.
 3. Open **server/routes/publishers.py**, an empty file.
-4. Open **Copilot chat**.
+4. Open **Copilot chat** by selecting the Copilot icon towards the top of your codespace.
 5. Create a new chat session by selecting the **New Chat** button, which will remove any previous context.
 
    ![Screenshot of the New Chat button being highlighted in the Copilot Chat panel](images/copilot-new-chat.png)
@@ -72,26 +71,27 @@ To see the impact of custom instructions, we will start by sending a prompt with
 9. Notice the generated code **is missing** either a docstring or a comment header - or both!
 
 > [!IMPORTANT]
-> As highlighted previously, GitHub Copilot and LLM tools are probabilistic, not deterministic. As a result, the exact code generated may vary, and there's even a chance it'll abide by our rules without us spelling it out! But to help with consistency, we should always document anything we want to ensure Copilot should understand about how we want our code generated.
+> As highlighted previously, GitHub Copilot and LLM tools are probabilistic, not deterministic. As a result, the exact code generated may vary, and there's even a chance it'll abide by our rules without us spelling it out! But to aid consistency in code we should always document anything we want to ensure Copilot should understand about how we want our code generated.
 
 ## Add global standards to copilot-instructions.md
 
 As highlighted previously, `copilot-instructions.md` is designed to provide project-level information to Copilot. Let's ensure global coding standards are documented to improve code suggestions from Copilot chat.
 
-1. Open **.github/copilot-instructions.md**.
-2. Explore the file, noting the brief description of the project and sections for `Code standards`, `Scripts` and `GitHub Actions Workflows`. These are applicable to any interactions we'd have with Copilot, are robust, and provide clear guidance on what we're doing and how we want to accomplish it.
-3. Locate the `###Global language guidance` section, which should be around like 16. Note how it contains a note to use type hints. That's why we saw those in the code generated previously.
-4. Add the following lines below the note about type hints to instruct Copilot to add comment headers to files and docstrings:
+1. Return to your codespace.
+2. Open **.github/copilot-instructions.md**.
+3. Explore the file, noting the brief description of the project and sections for `Code standards`, `Scripts` and `GitHub Actions Workflows`. These are applicable to any interactions we'd have with Copilot, are robust, and provide clear guidance on what we're doing and how we want to accomplish it.
+4. Locate the `### Global language guidance` section, which should be around like 16. Note how it contains a note to use type hints. That's why we saw those in the code generated previously.
+5. Add the following lines of markdown right below the note about type hints to instruct Copilot to add comment headers to files and docstrings:
 
    ```markdown
    - Include a comment block at the top of each new file to describe what it does
    - Every function should have docstrings or the language equivalent
    ```
 
-5. Close **copilot-instructions.md**.
-6. Select **New Chat** in Copilot chat to clear the buffer and start a new conversation.
-7. Return to **server/routes/publishers.py** to ensure focus is set correctly.
-8. Send the same prompt as before to create the endpoint.
+6. Close **copilot-instructions.md**.
+7. Select **New Chat** in Copilot chat to clear the buffer and start a new conversation.
+8. Return to **server/routes/publishers.py** to ensure focus is set correctly.
+9.  Send the same prompt as before to create the endpoint.
 
    ```plaintext
    Create a new endpoint to return a list of all publishers. It should return the name and id for all publishers.
@@ -138,7 +138,7 @@ We want to create a new endpoint to list all publishers, and to follow the same
 5. Review the following entries inside the instruction file, which includes:
 
    - an overview of requirements, including that tests must be created, and endpoints are created in Flask using blueprints.
-   - a link to another the above mentioned **python-tests.instructions.md** file.
+   - a link to another the previously mentioned **python-tests.instructions.md** file.
    - links to two existing files which follow the patterns we want - both the games blueprint and tests. Notice how these are setup as normal markdown links, allowing an instruction file to incorporate additional files for context.
 
 6. Return to **server/routes/publishers.py** to ensure focus is set correctly.
@@ -154,41 +154,41 @@ We want to create a new endpoint to list all publishers, and to follow the same
 > [!TIP]
 > If the list of options is long, you can type **instructions** to filter to the Instructions option then select **Instructions**.
 
-9.  Select **flask-endpoint .github/instructions** to add the instruction file to the context.
+12.  Select **flask-endpoint .github/instructions** to add the instruction file to the context.
 
    ![Screenshot showing the instruction file being added into Copilot Chat](images/copilot-add-instructions-file.png)
 
-10. Send the same prompt as before to generate the desired endpoint:
+13. Send the same prompt as before to generate the desired endpoint:
 
    ```plaintext
    Create a new endpoint to return a list of all publishers. It should return the name and id for all publishers.
    ```
 
-11. Note the **References** section, and how **games.py**, **test_games.py**, and **python-tests.instructions.md** were all included in call to Copilot.
+14. Note the **References** section, and how **games.py**, **test_games.py**, and **python-tests.instructions.md** were all included in call to Copilot.
 
    ![Screenshot of the references section, showing the included files of games.py, test_games.py, and python-tests.instructions.md](./images/copilot-instructions-references.png)
 
-12. Copilot generates the files. Notice how it generates updates across multiple files, like **games.py** and **test_games.py**.
-13. After reviewing the code, select **Keep** and **Done** in Copilot Chat to accept the changes.
-14. Open a terminal window by selecting <kbd>Ctl</kbd>+<kbd>\`</kbd>.
-15. Run the tests by running the script with the following command:
+15. Copilot generates the files. Notice how it generates updates across multiple files, like **games.py** and **test_games.py**
+16. After reviewing the code, select **Keep** and **Done** in Copilot Chat to accept the changes.
+17. Open a terminal window by selecting <kbd>Ctl</kbd>+<kbd>\`</kbd>.
+18. Run the tests by running the script with the following command:
 
    ```sh
    ./scripts/run-server-tests.sh
    ```
 
-16. Ensure all tests pass. If any tests fail, feel free to prompt Copilot Chat as needed, asking it to update the code based on the error messages you see.
+19. Ensure all tests pass. If any tests fail, feel free to prompt Copilot Chat as needed, asking it to update the code based on the error messages you see.
 
 > [!TIP]
-> Copy and paste the error message from the console window into the chat window to provide context!
+> Copy and paste the error message from the console window into the chat window to provide context! You can also use the `@terminal /explain` directive in Copilot Chat to ask Copilot to explain the last messages received in your terminal window.
 
-17. Once correct, and all tests pass, open the **Source Control** panel on the left of the Codespace and review the changes made by Copilot.
-18. Stage the changes by selecting the **+** icon in the **Source Control** panel.
-19. Generate a commit message using the **Sparkle** button.
+20. Once the code is correct, and all tests pass, open the **Source Control** panel on the left of the Codespace and review the changes made by Copilot.
+21. Stage the changes by selecting the **+** icon in the **Source Control** panel.
+22. Generate a commit message using the **Sparkle** button.
 
-   ![Screenshot of the Source Control panel showing the changes made](images/source-control-changes.png)
+    ![Screenshot of the Source Control panel showing the changes made](images/source-control-changes.png)
 
-20. Commit the changes to your repository by selecting **Commit**.
+23. Commit the changes to your repository by selecting **Commit**.
 
 ## Summary