Backend Change Doc

Turns backend changes into a short Markdown document that a developer on the frontend or mobile team can skim and understand quickly. Avoid long explanations; use bullet points and code blocks.

Use Cases

When the user wants to communicate backend changes to the frontend/mobile team. Usually in contexts like:

• End-of-sprint release notes
• PR description / share note
• An announcement saying “I did these things, the frontend side needs to update accordingly”

What Gets Produced?

• A short summary of added, updated, and removed endpoints
• Request and response DTO definitions
• Changed enum values
• Breaking change and migration notes
• Changes the frontend or mobile team needs to apply

---
name: backend-change-doc
description: "Produces a short, developer-friendly change document (Markdown) to announce API and model changes made on the backend (ASP.NET Core / C#) to frontend or mobile teams. Use for — 'explain the backend changes I made to the frontend/mobile team', 'prepare an API change document at the end of the sprint', 'document for a new endpoint added/updated/removed', 'release notes for backend changes', 'controller/DTO/enum change summary'. Can be triggered via commit/diff/PR or by user narration. Use only when a change document is requested specifically for backend-frontend communication, not for general technical documentation."
---

# Backend Change Doc

Turns backend changes into a short Markdown document that a developer on the frontend or mobile team can skim and understand quickly. Avoid long explanations; use bullet points and code blocks.

## Use Cases

When the user wants to communicate backend changes to the frontend/mobile team. Usually in contexts like:
- End-of-sprint release notes
- PR description / share note
- An announcement saying "I did these things, the frontend side needs to update accordingly"

## What Gets Produced?

- A short summary of added, updated, and removed endpoints
- Request and response DTO definitions
- Changed enum values
- Breaking change and migration notes
- Changes the frontend or mobile team needs to apply

## Gathering information

Gather the necessary material before writing. Look at these in order:
1. The user's message narrative (the most reliable source — what they say is the truth)
2. `git diff`, `git log`, open PR links if available — focus on controller, DTO, Enum files
3. Controller files: `*Controller.cs` — route, method, `[HttpGet/Post/Put/Delete]`, `[Authorize]`, parameter types
4. DTO/Model folders: request/response classes, property types and names
5. Enum files: new enum values or removal of old values

If information about an endpoint is missing (e.g. whether auth is required, what's returned on success), check the code first; if still unsure, ask the user a single consolidated question — not one per field.

## Document rules

A developer will read this. Goal: they should grasp what changed at a glance.

- Keep it short. No intro paragraph, no "Hello team" style greeting.
- Give the title in this format: `# Backend Changes — YYYY-MM-DD` (get the date from `date +%Y-%m-%d` in bash).
- 3 main categories in this order: **Added**, **Updated**, **Removed**. Include the empty category too and write `_None_` underneath it — so the developer doesn't think something's missing.
- The top section is just the endpoint list + a one-sentence change summary. Details go at the bottom of the document.
- Request/Response/DTO/Enum definitions go in **separate sections at the bottom of the document**. The endpoint list above should reference these by DTO name as plain text — don't use anchor links.

### Required fields for endpoint info

Each endpoint line must have:

- **HTTP method** and **path (with controller)** — e.g. `POST /api/auth/login` and `(AuthController.Login)` in parentheses
- **Request** — DTO name if there's a body (plain text, no link), otherwise a list of query/path params
- **Success response** — HTTP status + returned DTO name
- **Error statuses** — meaningful ones like 400/401/403/404/409 (not all of them, just the ones specific to the endpoint)

### Special rule for the "Updated" section

Just listing the endpoint isn't enough — **what changed** must be clear. Give a short list under a "Change:" label for each update item. Example:

```
- `PUT /api/users/{id}` (UsersController.Update)
  - **Change:**
    - `phoneNumber` field is now required (was optional before)
    - `updatedAt` added to the response
    - 409 status is now returned on phone number conflict
```

If there's a breaking change, prefix it with `⚠️ BREAKING:` — this is the one exception where using an emoji is useful, because it needs to catch the frontend's attention.

### Special rule for the "Removed" section

Add a **migration note** for each removed endpoint: what to use instead or why it was removed.

```
- `GET /api/legacy/profile` (LegacyController.GetProfile) — Use instead: `GET /api/users/me`
```

### DTO / Model / Enum definitions

Use a table for each DTO at the end of the document. Columns: **Property**, **Type**, **Description**, **Required?**

- **Description** should be a short but contextual sentence — not just a word, explain the field's role in the system.
- **Required?** column: `Yes` for required fields, `No` for optional fields.

```
### LoginRequest

| Property | Type | Description | Required? |
|---|---|---|---|
| patientId | string | Patient verification and `ReportNumber` generation for new records are based on this patient. | Yes |
| email | string | The user's email address registered in the system; used as unique identifier for the user. | Yes |
| deviceId | string? | Identifies the mobile device sending the request; used for notification routing. | No |
```

Same structure for enums:

```
### OrderStatus

| Value | Numeric | Description |
|---|---|---|
| Pending | 0 | Order received, awaiting payment |
| Paid | 1 | Payment completed, to be prepared |
| Shipped | 2 | Handed off to courier |
| Cancelled | 3 | Cancelled (by user or system) |
```

Only write DTO/Enums that are **newly added or changed**. Don't rewrite existing ones — don't bloat the document. For a changed DTO, write the whole DTO instead of just showing the changed properties (so the developer isn't confused), but add a note above it: "Changed fields: `phoneNumber`, `updatedAt`".

## Format template

Always use this skeleton:

```markdown
# Backend Changes — YYYY-MM-DD

> Scope: <Sprint X / Release Y.Z / PR #NNN> — <one-sentence summary>

## Added

- `<METHOD> <path>` (ControllerName.ActionName)
  - Request: DTOName _or_ Query: `param1: type, param2: type`
  - Response: `200 OK` → DTOName
  - Errors: `400`, `404`

## Updated

- `<METHOD> <path>` (ControllerName.ActionName)
  - **Change:**
    - <item 1>
    - <item 2>
  - Request: DTOName
  - Response: `200 OK` → DTOName

## Removed

- `<METHOD> <path>` (ControllerName.ActionName) — Use instead: `<new endpoint or description>`

---

## DTOs

### DTOName

| Property | Type | Description | Required? |
|---|---|---|---|
| ... | ... | ... | Yes / No |

## Enums

### EnumName
...table...
```

If a category is empty, keep the heading and write `_None_` underneath.

## Writing tips

- Don't artificially pad it out. Don't add sentences like "This change improves X" — the developer will look at the code anyway.
- If the path has a placeholder, write it with curly braces: `/api/users/{id}`.
- Show nullable C# types in Markdown with `?`: `string?`, `int?`, `Guid?`.
- Write collections as `List<Foo>` or `Foo[]`, don't use `IEnumerable<Foo>` — confusing for the frontend side.
- Mark `DateTime` fields in the table as `string (ISO8601)`, since they go over JSON as strings.
- Mark enum properties in the table as `string (EnumName)` and link to the Enum section.

## Example and template files

- For an empty skeleton to copy and fill in: `references/template.md`
- For a completed, realistic example: `references/example.md`

Before producing each new document, glance at `references/example.md` — match its tone and level of detail.

## Saving the output

File name: `YYYY-MM-DD-backend-changes.md` (per the user's CLAUDE.md rule).

Unless the user specifies a different location, write it to the user's selected workspace folder. After writing the file, give a short summary: how many endpoints were added/updated/removed and the number of breaking changes if any.