# Asana Task Creation

## Objective

Create Asana tasks in the right workspace, project, and section from work inside the app.

A server-side path from an in-app record to an Asana task, with workspace, project, section, assignee, and due date mapping.

## 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. Let an administrator choose the workspace, project, section, default assignee, and due-date rule from what the connected account can see, and re-resolve each of those at creation time rather than trusting identifiers captured at setup.
2. Map app users to Asana identities through an explicit administrator-maintained mapping. Do not infer an assignee from a matching email address; the wrong person silently owning a task is worse than an unassigned one.
3. Compose the task on the server with a durable link back to the originating record, and keep private customer detail in the app behind that link rather than pasting it into the task where the whole project can read it.
4. Key each submission by the originating record and check for an existing task reference before creating, so a retry after a timeout reuses the task instead of creating a second one.
5. GitHub Issue Creation, GitLab Issue Creation, Linear Issue Creation, Jira Ticket Creation, and Trello Card Creation are siblings. Capture, redaction, deduplication, and reference storage belong to the shared path; this brief owns only Asana's workspace and project resolution and its user mapping.

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

- Identity mapping between the app and Asana is the highest-risk part of this feature. Maintain it explicitly, leave the assignee unset when no mapping exists, and name the reporter in the task description instead of guessing.
- Projects, sections, and custom fields get removed or renamed by people who do not know the app depends on them. Resolve each at creation time, omit what no longer exists, still create the task, and warn an administrator about the broken mapping.
- A retry must not create a second task. Persist the returned task reference before acknowledging the job and check for it on every attempt, since a timeout usually means the task exists.
- The link back into the app must survive the record being renamed or moved, so link by stable identifier, and never include internal-only identifiers or customer personal data in the task body.
- Tasks get moved between projects, completed, or deleted inside Asana. Reconcile on read rather than assuming the stored reference still points where it was created, and show a clear state in the app when the task can no longer be found.
- Access tokens expire and refresh tokens get revoked when a member leaves. Refresh proactively, treat an authentication failure as terminal for the attempt, hold the queue, and prompt an administrator to reconnect.
- Rate limits require exponential backoff with jitter and a bounded retry count, with a dead-letter path for submissions that never succeed.
- If task events are consumed back into the app, treat them as at-least-once and possibly out of order: dedupe by event identifier and ignore events older than the state already held.

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

- [ ] A record in the app can be sent to Asana as a task in the configured workspace, project, and section.
- [ ] User mapping is explicit and an unmapped reporter yields an unassigned task rather than a guess.
- [ ] Removed projects, sections, or custom fields degrade the task gracefully and warn an administrator.
- [ ] Retried submissions produce exactly one task.
- [ ] Every task links back to the originating record by a stable identifier, with private detail left in the app.
- [ ] Token expiry and revocation queue work and prompt a reconnection instead of dropping submissions.
- [ ] Tasks moved or deleted in Asana are reconciled on read and reflected accurately in the app.
- [ ] 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.