# ClickUp Task Creation

## Objective

Turn app events into ClickUp tasks in the right list, with fields and assignees mapped.

A connected ClickUp account, a per-workspace mapping of app events to a target list, and a background job that creates and updates tasks.

## 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 the app events worth pushing outward — a new support ticket, an escalation, an overdue item — and let an administrator choose which of them create tasks, rather than pushing everything.
2. Store the connection against the workspace, not the individual who authorised it, and keep tokens in server-side storage the browser never reads. Refresh expiring credentials in the background and mark the connection as needing re-authorisation when a refresh fails.
3. Let the administrator pick the destination by walking the account's own hierarchy of workspace, space, folder, and list, fetched live at configuration time. Do not ask the user to paste an identifier they have to find in a URL.
4. Persist the mapping between app fields and destination fields by the remote identifier, and re-validate that mapping before each send so a removed field surfaces as a configuration warning rather than a silent drop.
5. Reuse the app's existing background-job system for every send, and record the created task's identifier against the source record so a retried job updates the existing task instead of creating a second 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 destination is four levels deep — workspace, space, folder, list — and a task created in the wrong list is invisible to the team that needed it. Resolve and store the full path, and re-check it exists before each send.
- Custom fields must be mapped by their stable remote identifiers, never by their display names, because names are renamed freely. Each field also has a type, and sending a free-text value into a numeric or dropdown field is rejected outright.
- Available statuses differ from one list to another, so a status that is valid in one destination does not exist in another. Read the destination's own status set at configuration time and refuse a mapping that no longer resolves.
- A job that times out after the remote side has already created the task will create a duplicate on retry. Send a stable idempotency value derived from the source record and reconcile against the stored task identifier before creating anything.
- The connected account's permissions decide who can be assigned and what can be seen. Do not assign a user who is not a member of the destination, and do not copy internal notes or customer data into a task that a wider audience can read.
- Rate limits will be hit during a backfill or a burst of events. Back off and retry on the provider's own signal, and never spin a tight retry loop that makes the limit worse.
- When the provider is unavailable the app's own action must still succeed. Queue the task creation, show the user that it is pending, and surface a failed send in the record's activity rather than as a dead end.
- Revoking the connection in ClickUp gives no notification. Detect repeated authorisation failures, disable the mapping, and tell an administrator instead of retrying forever.

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

- [ ] An administrator connects ClickUp once per workspace and selects a destination by browsing the account's real hierarchy.
- [ ] Field mappings are stored by remote identifier and re-validated before each send, with removed fields reported as configuration warnings.
- [ ] A retried or duplicated job updates the existing task rather than creating a second one.
- [ ] Task creation runs in the background and never blocks or fails the user's own action.
- [ ] Rate limits and provider outages result in backoff and a visible pending state, not lost events.
- [ ] Credentials are never present in client-visible code, and a revoked connection is reported to an administrator.
- [ ] 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.