# AI Dashboard Insights

## Objective

Explain what actually changed on a dashboard, in the viewer's own filters and period.

A short generated commentary attached to a dashboard, describing the movements that matter under the filters currently applied.

## 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. Compute the numbers first, in the app, using the dashboard's existing queries with the viewer's active filters. Pass the model the computed figures and let it write the wording, never the raw rows to add up itself.
2. State the period and the comparison period explicitly in every insight. A sentence saying signups are up is meaningless without saying up against what.
3. Filter the input to metrics the viewer is permitted to see before it reaches the model. A commentary that mentions revenue to someone whose dashboard hides revenue is a permissions leak.
4. Show the commentary as a distinct, labelled block that is clearly generated and carries the time it was produced. Do not weave generated sentences into the dashboard's own labels where a reader cannot tell what came from a model.
5. This feature owns the narrative paragraph for a whole dashboard. Per-metric findings with their own supporting query belong to AI Insight Cards; if that feature is present, generate the summary from its cards rather than running a second analysis pass.

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

- Every figure quoted must come from the app's own aggregation under the viewer's current filters. If the filters changed after the commentary was produced, mark it stale and offer a regenerate rather than showing numbers that no longer match the charts above them.
- Each statement must name its window and its comparison, such as the last 30 days against the previous 30. Without both, a reader will assume whichever comparison flatters the number.
- The model will reach for causes it cannot know. Constrain output to what moved and by how much, and forbid explanations of why unless the dashboard actually contains the driver as a dimension.
- Run the permission filter on the inputs, not the outputs. Generating commentary across all metrics and then trying to strip the forbidden sentences afterwards will eventually miss one.
- An uneventful period should produce nothing. Say that nothing material changed rather than padding the block with generic observations about steady performance.
- Cap the tokens and the spend per generation, and cache the result against the exact filter set and period so that reloading the dashboard does not bill for a fresh run.
- On a timeout, refusal, or truncated response, hide the block entirely and leave the dashboard fully usable. This is commentary on top of the real data, never a prerequisite for it.
- Partial data, a metric still backfilling, or a period that has not closed must be called out, or the commentary will report a drop that is only late-arriving data.

## 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 number in the commentary matches the dashboard under the viewer's current filters.
- [ ] Each statement names its period and comparison period.
- [ ] Metrics the viewer cannot access are excluded before generation, not after.
- [ ] Uneventful periods produce an explicit no-material-change result rather than filler.
- [ ] Results are cached per filter set and marked stale when filters change.
- [ ] A model failure hides the block and leaves the dashboard fully functional.
- [ ] The block is visibly labelled as generated and timestamped.
- [ ] 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.