Prompt file imported from chikamsoachumsft/octocat_supply-fantastic-happiness (.github/prompts/analyze-for-docs.prompt.md). Copyright stays with the author.

Analyze Commit and Create Documentation Issue

Analyze commit {COMMIT_SHA} in repository {REPOSITORY} using the GitHub MCP server to determine if documentation needs to be added or updated.

Your Task

1. Examine the commit using MCP to access:

   • Commit diff and all changed files
   • Current documentation structure in docs/
   • Existing TSDoc and Swagger JSDoc in changed source files

2. Decide if documentation is needed based on:

   ✅ Document These

   • New or modified public repository methods without TSDoc (@param, @returns, @throws, @example)
   • New or modified route handlers without Swagger @openapi JSDoc blocks
   • New API endpoints or changes to existing request/response contracts
   • Changes to error handling behavior (new error classes, changed status codes)
   • New database schema (migrations) that changes the public data model
   • New dependencies or integrations added to the API
   • Breaking changes or renamed fields

   ❌ Skip These

   • Changes only to test files (*.test.ts)
   • Changes only to api/sql/seed/ files
   • Minor refactoring with no behavioral change
   • Internal helper functions not exposed via route or repository interface
   • Config-only changes (tsconfig.json, eslint.config.mjs)
   • Trivial renaming or formatting

3. If documentation is needed:

   Create a GitHub issue using MCP with:

   Title: 📚 Documentation needed: [brief description of changes]

   Body:

   ## Documentation Analysis
   
   **Commit:** {COMMIT_SHA}
   
   ### Files Needing Documentation
   
   | File | Type | Gap |
   |---|---|---|
   | `api/src/repositories/fooRepo.ts` | TSDoc | Missing `@throws`, `@example` on `getFooById` |
   | `api/src/routes/foo.ts` | Swagger JSDoc | No `@openapi` block on `POST /foo` |
   
   ### What Needs to Be Added
   
   #### `fooRepo.ts` — TSDoc
   - `getFooById`: add `@throws {NotFoundError}`, add `@example`
   - `createFoo`: add `@param data` description, add `@example`
   
   #### `foo.ts` — Swagger JSDoc
   - `POST /foo`: add `@openapi` block with `requestBody`, `201`, `400`, `422`, `500` responses
   - `DELETE /foo/:id`: add `404` response code
   
   ### Documentation Standard
   
   **TSDoc** (repository files): every public method needs `@param`, `@returns`, `@throws`, `@example`
   Reference: `api/src/repositories/suppliersRepo.ts`
   
   **Swagger JSDoc** (route files): every handler needs an `@openapi` block with all response codes
   Reference: `api/src/routes/order.ts`
   
   ### Breaking Changes / Migration Notes
   
   [Describe any breaking changes to the API contract, or "None" if not applicable]
   
   ---
   *Auto-generated by: agentic-workflow-generate-docs*

   • Add labels: documentation, automated
   • Use assign_copilot_to_issue tool to assign @copilot to the issue

4. If documentation is NOT needed:

   • Briefly explain why (e.g., "only test files and seed data changed — no public API surface modified")
   • No issue needed

Important Guidelines

• Focus on the public surface: routes and repository methods that callers depend on
• A missing @example or @throws on an existing method counts as a documentation gap if that method was changed
• Be specific about which file, which method, and which tag is missing