# AI Smart Defaults

## Objective

Suggest sensible starting values for a form instead of leaving every field blank.

Pre-filled but fully editable default values on the app's forms, derived from the current user, workspace, and related records.

## 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. Identify the forms where users repeatedly type the same value, then assemble the context that would predict it: the acting user's recent entries, the workspace's conventions, and the parent record the form was opened from.
2. Render every suggestion as a normal editable field value that is visibly marked as suggested, and clear that marking the moment the user edits it. Never write a suggested value into a record the user has not submitted.
3. Build the deterministic default first and keep it in place. The model layer only overrides it when it returns a well-formed value the field would accept and its own stated confidence clears a threshold you configure.
4. Give the user a way to see why a value was suggested in plain language, and a single control that clears all suggestions on the form back to the deterministic defaults.
5. Do not learn from the user's corrections by silently feeding their edits back as training or long-term memory. Correction data is only reused where the user has agreed to it, and never across tenant boundaries.

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

- A suggestion is a default, not a decision. If the user submits without looking, they must still get a value they could have arrived at themselves, so a suggestion must never populate a field with legal, financial, or destructive consequences.
- The context assembled for one workspace must never include another tenant's records. Scope every lookup to the acting user's permissions before the request is composed, not after the response comes back.
- Sensitive attributes about a person must not be part of the context or the reasoning, even when they correlate well with the right answer. Exclude them at the point the context is built.
- A surprising suggestion with no explanation reads as a bug. If the app cannot say in one sentence where a value came from, do not show it as a suggestion.
- When the model is slow, unavailable, or returns something the field cannot parse, the form must render immediately with deterministic defaults rather than blocking on the suggestion.
- A suggestion that arrives after the user has already started typing in that field must be discarded, not applied over their input.
- Suggestions must respect field-level validation and permissions. A value the user is not allowed to set must never be offered.
- Cap the spend: a form opened repeatedly in a loop must not issue a request every time. Reuse a recent result for the same context and enforce a per-workspace ceiling on suggestion calls.

## 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 suggested value is editable, visibly marked as a suggestion, and unmarked once edited.
- [ ] Deterministic defaults render immediately and remain in place when the model is slow, unavailable, or returns unusable output.
- [ ] No suggestion is derived from another tenant's data or from sensitive personal attributes.
- [ ] Each suggestion can be explained in one sentence in the interface.
- [ ] Nothing is written to a record until the user submits the form.
- [ ] Suggestion calls are rate limited and capped per workspace, with reuse of recent results for identical context.
- [ ] 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.