# Slack Channel Alerts

## Objective

Send the events a team actually needs into a Slack channel without flooding it.

Operator-configured routing of selected app events into Slack channels, with grouping, throttling, and reliable delivery.

## 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. List the events genuinely worth interrupting a team for — failed payments, high-value signups, error thresholds, approvals waiting — and make each individually selectable per channel. An all-or-nothing firehose gets muted within a week and then nobody sees the one that mattered.
2. Run the connection through the provider's authorisation flow, then confirm the workspace and channel at setup by posting a test message the operator has to acknowledge. Store the resulting credential server-side only.
3. Write each message so it stands alone: what happened, to whom, when, and a link back into the app. Optional fields that are absent must be omitted cleanly rather than rendering as empty labels.
4. Deduplicate on a stable event identifier so a webhook redelivery or a retried job cannot post the same alert twice, and collapse bursts of one event type into a single grouped message carrying a count.
5. If a Microsoft Teams brief is also applied to this app, both must share one event-selection and routing layer, with each destination brief owning only its own formatting and delivery. Two independent alert configurations drift apart and double-post.

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

- Setup must verify that the chosen channel exists and that the app can post to it. Discovering a bad destination during a real incident is too late to be useful.
- A message built from a record with missing optional fields must still read as a sentence, not as a template with blank slots where values should be.
- Retried jobs and redelivered webhooks must be deduplicated on the event identifier, or one incident produces a dozen identical posts and the channel is abandoned.
- A channel that was renamed, archived, or made private, an app removed from the workspace, or a revoked scope must disable that destination, surface the reason to an operator in the app, and stop retrying forever.
- Noisy event types need a ceiling per channel and per window, with the overflow summarised as a count rather than dropped without trace.
- Alerts must not carry secrets or personal data beyond what the channel's membership is entitled to see. A channel is almost always a wider audience than the record itself.
- Provider rate limits must be honoured with bounded backoff, and delivery must never block or fail the user action that produced the event.
- Deep links back into the app must resolve for whoever clicks them, and must land on a permission message rather than a blank page for someone without access.

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

- [ ] Operators can choose which event types go to which channel.
- [ ] Setup verifies the workspace and channel with a test message the operator confirms.
- [ ] Messages stay readable when optional fields are absent and link back into the app.
- [ ] Retries and webhook redeliveries never produce a duplicate alert.
- [ ] Bursts are grouped and noisy event types are rate-limited with the overflow counted.
- [ ] A revoked, removed, or archived destination disables itself and notifies an operator.
- [ ] Alert delivery never blocks or fails the user action that generated the event.
- [ ] 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.