# AI Next Best Action

## Objective

Suggest the most useful next step on a record, drawn only from actions the user can take.

A suggestion panel on a record or workflow that proposes a next step, cites the facts behind it, and links to the action.

## 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. Build the candidate list first, in ordinary code: enumerate the actions that are valid for this record in its current state and permitted for this user, then let the model choose and rank from that list only. A suggestion the user cannot perform is worse than no suggestion.
2. Assemble a compact, explicit fact set for the record — status, dates, owner, recent activity, outstanding obligations — and send only that. Do not send the whole record, unrelated customer data, or free-text notes that may contain personal information the feature does not need.
3. Require the model to return the chosen action identifier plus the specific facts that support it, and render those facts beside the suggestion. A suggestion the user cannot audit will be ignored or, worse, trusted blindly.
4. Present every suggestion as a proposal the user clicks to perform. Do not execute the suggested action automatically, and mark destructive, irreversible, or externally visible actions so they route through the app's existing confirmation step rather than a one-click accept.
5. Recompute when the record's state materially changes, and invalidate the cached suggestion at the same moment. Do not recompute on every page view; that turns a modest per-record cost into an unbounded one.

## 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

- The model may name an action that does not exist or that this user lacks permission for. Validate the returned identifier against the candidate list and drop anything that does not match, rather than surfacing a dead control.
- When the supporting evidence is thin, the correct output is no recommendation. Give the model an explicit way to decline and show a plain empty state instead of manufacturing a weak suggestion to fill the panel.
- Suggesting an irreversible or high-risk action — deleting, cancelling, charging, notifying a customer — must never be a single click from the suggestion panel. Route it through the same review the app already requires.
- A record whose state changed after the suggestion was generated must not keep showing the stale advice. Tie the cached suggestion to a version of the record state and discard it when that version moves on.
- If the model times out, refuses, or returns output that does not parse into a known action, hide the panel entirely. A broken or apologetic suggestion box on every record erodes trust in the whole screen.
- Per-record generation multiplied across a list view can be ruinously expensive. Generate on the detail view or on explicit request, and cap how many suggestions a workspace can generate in a period.
- The explanation must describe observed facts, not invent history. Suggestions citing events that are not in the fact set are a defect, not a wording problem.
- When the model is unavailable, the surrounding record page must render normally with the panel absent, not blocked behind a pending request.

## 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

- [ ] Every suggestion resolves to an action that exists, is valid for the record's current state, and is permitted for the viewing user.
- [ ] Each suggestion displays the specific facts that support it.
- [ ] No suggested action is performed without an explicit user click, and high-risk actions still pass through the app's confirmation step.
- [ ] Weak evidence produces an explicit no-recommendation state rather than a speculative suggestion.
- [ ] A suggestion is invalidated and regenerated when the record's state changes, and is not regenerated on every view.
- [ ] Model failure, refusal, or unparseable output leaves the record page fully usable with no suggestion shown.
- [ ] Only the assembled fact set is sent to the provider, and generation volume is capped per workspace.
- [ ] 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.