# AI Release Note Generator

## Objective

Turn the work that actually shipped into release notes a person can read.

A drafting step that assembles internal and public release notes from the change records the app already tracks.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Find where the app already records completed work — merged changes, closed tickets, deploy records — and build the input set from those, scoped to a release or a date range. Do not ask the user to paste a changelog the system could assemble itself.
2. Send only what the summary needs: change titles, descriptions, labels, and the area of the product affected. Never send full diffs, configuration files, credentials, customer names, or the contents of a private record the eventual reader is not entitled to see.
3. Generate two detail levels from the same input set: an internal note that keeps identifiers, caveats, and rollback notes, and a public note written for someone who has never seen the codebase.
4. Present the result as an editable draft with every line traceable to the change it came from, and require a human to publish it. Do not publish generated notes automatically; a wrong release note becomes a support queue, not a typo.
5. Set a token and cost ceiling per generation, and split a large release into batches that are summarised and then merged. If the model refuses, times out, or returns a truncated draft, fall back to a plain grouped list of change titles and say the summary could not be generated.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Work that is merged but sitting behind a disabled flag has not shipped. Filter on what is actually enabled in the target environment, or the notes will announce features nobody can find.
- Every generated line needs a link back to the change or ticket it came from, so a reviewer can check a claim without rereading the whole release.
- Dependency bumps, formatting passes, and internal refactors are noise in a public note. Exclude them unless they change something the user can observe, and keep them in the internal version.
- A change that was reverted, or deployed to only some regions or tenants, must not appear as shipped. Reconcile against the deploy record rather than the merge history alone.
- Internal and public audiences need different detail. A note that names internal services, incident numbers, or customer accounts must never be publishable without an explicit edit.
- A release with no user-visible changes should produce an honest empty state, not an invented summary of minor work.
- Regenerating a note must not discard edits a human already made. Offer the new draft alongside the edited one and let the user choose.
- If the release spans more changes than the cost ceiling allows, say which range was summarised rather than silently truncating the input.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Release notes are drafted from the app's own change and deploy records with no manual paste step.
- [ ] Each generated line links to the source change that produced it.
- [ ] Internal and public versions exist separately and the public version excludes internal identifiers and non-user-visible work.
- [ ] Changes behind a disabled flag or subsequently reverted do not appear as shipped.
- [ ] Nothing publishes without a human approving the draft.
- [ ] A model refusal, timeout, or truncated response degrades to a plain list of change titles with an explanation.
- [ ] Each generation runs within a defined token and cost ceiling.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.