Tweak prompts

Author: johanfive

.github/prompts/extract-xmapi-endpoint-documentation.prompt.md

@@ -7,26 +7,29 @@ description: 'Extract and format documentation for a specific xmAPI endpoint fro
 
 # Extract xmAPI Endpoint Documentation
 
-You are tasked with extracting and formatting documentation for a specific xmAPI endpoint from the official xMatters API documentation website.
+You are tasked with extracting and formatting documentation for a specific xmAPI endpoint from the
+official xMatters API documentation website.
 
 ## Input
 
 You will be provided with:
-1. A URL to a specific section of the xMatters API documentation (e.g., `https://help.xmatters.com/xmapi/#services`)
+
+1. A URL to a specific section of the xMatters API documentation (e.g.,
+   `https://help.xmatters.com/xmapi/#services`)
 2. The endpoint name (e.g., "services", "people", "groups", etc.)
 
 ## Output Format
 
 Generate a markdown file that follows this exact structure and formatting:
 
 ### Header Block
+
 ```markdown
-> This file's content is copy-pasted straight from the
-> [online doc here](ACTUAL_URL_PROVIDED), mistakes, typos and all. This is
-> meant to be used as a starting point to build the endpoint, and then as a reference to generate
-> validation scenarios in the sandbox. Once the documentation is confirmed accurate or proving to be
-> inaccurate, the relevant code implementation is rectified to match the reality of the API, but
-> this markdown file here will be left untouched.
+> This file's content is copy-pasted straight from the [online doc here](ACTUAL_URL_PROVIDED),
+> mistakes, typos and all. This is meant to be used as a starting point to build the endpoint, and
+> then as a reference to generate validation scenarios in the sandbox. Once the documentation is
+> confirmed accurate or proving to be inaccurate, the relevant code implementation is rectified to
+> match the reality of the API, but this markdown file here will be left untouched.
 ```
 
 ### Main Content Structure
@@ -58,18 +61,24 @@ Generate a markdown file that follows this exact structure and formatting:
 
 ## Requirements
 
-- **Preserve all original text exactly**: Copy all content verbatim, including any typos, formatting inconsistencies, or errors from the source
-- **Include complete descriptions**: For each API operation, copy the main description AND all additional explanatory paragraphs that follow
+- **Preserve all original text exactly**: Copy all content verbatim, including any typos, formatting
+  inconsistencies, or errors from the source
+- **Include complete descriptions**: For each API operation, copy the main description AND all
+  additional explanatory paragraphs that follow
 - **Maintain formatting**: Keep the same markdown structure, code block formatting, and indentation
 - **Include all examples**: Copy all curl commands and JSON responses exactly as shown
 - **Preserve parameter details**: Include all parameter descriptions, valid values, and constraints
-- **Keep structure consistent**: Follow the same heading hierarchy and section organization as shown in the reference
+- **Keep structure consistent**: Follow the same heading hierarchy and section organization as shown
+  in the reference
+- **Avoid markdown tables**: because `deno fmt` will break them, do NOT create tables.
 
 ## Quality Checklist
 
 Before submitting, ensure:
+
 - [ ] The header block is present with the correct URL
-- [ ] All HTTP operations are documented with complete descriptions (including all explanatory paragraphs)
+- [ ] All HTTP operations are documented with complete descriptions (including all explanatory
+      paragraphs)
 - [ ] Parameter tables are complete with types and descriptions
 - [ ] JSON examples are properly formatted in code blocks
 - [ ] The object definition section is included at the end
@@ -78,4 +87,11 @@ Before submitting, ensure:
 
 ## Example Reference
 
-Use the structure and formatting shown in the services endpoint documentation as your template for consistency across all endpoint documentation files.
+Use the structure and formatting shown in the services endpoint documentation as your template for
+consistency across all endpoint documentation files.
+
+### Out of Scope
+
+- **Actual implementation**: Do not create or modify any `.ts` file. This task is strictly for
+  documentation extraction. Writing the `index.ts`, `types.ts` and testing files will be handled in
+  a separate process.

.github/prompts/new-endpoint.prompt.md

@@ -26,7 +26,8 @@ Adhere to the development guidelines in the project's
 3. **Define Types**:
    - In the new `types.ts` file, draft the necessary TypeScript interfaces based on the provided API
      documentation.
-   - Leverage the reusable, common types available in `src/core/types/` whenever possible.
+   - Leverage the reusable, common types available in the `src/core/types/` directories whenever
+     possible.
    - Use an existing endpoint's `types.ts` file (e.g., `src/endpoints/services/types.ts`) as a
      reference to ensure a consistent style for properties and naming conventions.
 
@@ -77,15 +78,19 @@ Adhere to the development guidelines in the project's
      ```
 
    - **Common Methods**:
-     - While not a strict rule, most standard endpoints should implement the following core methods
-       if the API supports them:
+     - While not a strict rule, most standard endpoints should implement the following default
+       methods if the API supports them:
      - `get()`: To fetch a list of resources (paginated).
      - `getByIdentifier(id)`: To fetch a single resource by its ID or name.
      - `save(payload)`: Creates a new resource or updates an existing one. The payload determines
        the action: provide an `id` to update, or omit the `id` and provide a `targetName` (usually)
        to create.
      - `delete(id)`: To remove a resource.
 
+   - **type and lint check**:
+     - Ensure the new endpoint compiles without type errors and passes lint checks.
+     - Run `deno check` and `deno lint` to verify.
+
 5. **Export New Endpoint**:
    - Finally, open `src/index.ts` and add the new endpoint to the `XmApi` class.
    - Import the new endpoint class.

README.maintainers.md

@@ -63,40 +63,46 @@ pattern:
 
 To streamline endpoint creation, use these AI assistant prompts in sequence:
 
-1. **`/extract-xmapi-endpoint-documentation`** - Extract and format official API documentation into a markdown file for reference in subsequent prompts.
+1. **`/extract-xmapi-endpoint-documentation`** - Extract and format official API documentation into
+   a markdown file for reference in subsequent prompts.
 
-2. **`/new-endpoint`** - Generate the initial endpoint implementation (types, class, and exports) based on the extracted documentation.
+2. **`/new-endpoint`** - Generate the initial endpoint implementation (types, class, and exports)
+   based on the extracted documentation.
 
-3. **`/docs-vs-irl`** - Create validation scenarios that test the endpoint against real API responses, then update the endpoint code based on the observed real behavior to fix any discrepancies with the documentation.
+3. **`/docs-vs-irl`** - Create validation scenarios that test the endpoint against real API
+   responses, then update the endpoint code based on the observed real behavior to fix any
+   discrepancies with the documentation.
 
 #### ✨ The `/extract-xmapi-endpoint-documentation` prompt
 
 1. **Initiate the process**:
 
-    In VS Code, start a new chat with your A.I. assistant and type:
-    ```sh
-    /extract-xmapi-endpoint-documentation <endpoint-online-doc>
-    # e.g.: /extract-xmapi-endpoint-documentation https://help.xmatters.com/xmapi/#shifts 
-    ```
+   In VS Code, start a new chat with your A.I. assistant and type:
+   ```sh
+   /extract-xmapi-endpoint-documentation <endpoint-online-doc>
+   # e.g.: /extract-xmapi-endpoint-documentation https://help.xmatters.com/xmapi/#shifts
+   ```
 
 2. **Verify the output**
 
-    The LLM will be spinning its wheels for a short while but usually does a really good job in 1 shot. Still, proof-read a little.
+   The LLM will be spinning its wheels for a short while but usually does a really good job in 1
+   shot. Still, proof-read a little.
 
 #### ✨ The `/new-endpoint` prompt
 
 1. **Initiate the process**:
-   
-    In VS Code, start a new chat with your A.I. assistant and type `/new-endpoint` to begin.
+
+   In VS Code, start a new chat with your A.I. assistant and type `/new-endpoint` to begin.
 
 2. **Provide details**:
 
-    The assistant will guide you through creating the necessary files and code, asking for the endpoint name and its official documentation if you didn't provide them in the prompt.
+   The assistant will guide you through creating the necessary files and code, asking for the
+   endpoint name and its official documentation if you didn't provide them in the prompt.
 
-    ```sh
-    /new-endpoint <endpoint-name> <endpoint-doc-file>
-    # e.g.: /new-endpoint shifts #file:xmapi-official-documentation.md
-    ```
+   ```sh
+   /new-endpoint <endpoint-name> <endpoint-doc-file>
+   # e.g.: /new-endpoint shifts #file:xmapi-official-documentation.md
+   ```
 
 #### ❌✨ `xm-endpoint` VS Code Snippet