# Jira Ticket Creation

## Objective

Create Jira work items in the right project and type, with the fields that project requires.

A server-side path from an in-app record to a Jira work item, with per-project field discovery, mapping, and a stored ticket reference.

## 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. Discover the destination project's issue types and their required fields at configuration time and again before creating, and present the administrator with a mapping screen. Do not hardcode a field set; every Jira instance is configured differently and a hardcoded schema fails on the second customer.
2. Make the deployment type and site part of the connection so hosted and supported self-managed instances are handled deliberately, and keep the credential and site details server-side only.
3. Map app users to Jira identities through an explicit, administrator-maintained mapping, and fall back to leaving the field unset with the reporter named in the description rather than guessing an account from an email address.
4. Key each submission by the originating record and check for an existing ticket reference before creating, because Jira requests time out often enough that blind retries are the main source of duplicates.
5. GitHub Issue Creation, GitLab Issue Creation, Linear Issue Creation, Trello Card Creation, and Asana Task Creation are siblings. Capture, redaction, deduplication, and reference storage belong to the shared path; this brief owns only Jira's field discovery, user mapping, and rich-text handling.

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

- Required custom fields differ per project and per issue type and change without notice. Fetch the field metadata for the chosen project and type, validate the mapping against it before submitting, and tell the administrator exactly which required field is unmapped instead of failing at creation.
- Hosted and self-managed deployments differ in authentication, available capabilities, and description formatting. Detect the deployment at setup, exercise each path explicitly, and refuse to run against a deployment that has not been verified.
- User identity is the most dangerous mapping. Never infer a Jira account from an email match alone, and never surface Jira account identifiers back to end users, since they can expose an organisation's directory.
- A request that times out has usually succeeded. Store the idempotency key before the call, check for an existing ticket on retry, and reconcile from the app's own record rather than searching Jira by title.
- Descriptions are rich text with a provider-specific structure, and attachments have size and type limits. Convert content safely, truncate over-long descriptions with a link back to the full detail in the app, and skip attachments that exceed the limit with a note rather than failing the ticket.
- Tokens and OAuth grants expire and get revoked. Treat an authentication failure as terminal for the attempt, keep submissions queued, and prompt an administrator to reconnect.
- Rate limits and instance-level throttling need exponential backoff with jitter and a bounded retry count, with a dead-letter path for submissions that never succeed.
- When the Jira instance is unavailable, record the request in the app and create the ticket later, so the user's report is not lost to someone else's outage.

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

- [ ] Required fields are discovered per project and issue type and mapped before any ticket is created.
- [ ] Hosted and supported self-managed deployments are configured and exercised deliberately, not assumed identical.
- [ ] User mapping is explicit, with a safe fallback that never guesses an account.
- [ ] A timed-out request followed by a retry produces exactly one ticket.
- [ ] Descriptions convert cleanly and oversized attachments are skipped with a recorded reason.
- [ ] Credentials live only on the server, and expiry queues work while alerting an administrator.
- [ ] An outage preserves the request in the app and creates the ticket when the instance returns.
- [ ] 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.