# GitHub Issue Creation

## Objective

Turn in-app feedback and errors into GitHub issues that already carry the useful context.

A server-side path from a report, error, or internal request to an issue in a configured GitHub repository, with the issue reference stored on the originating record.

## 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. Add an admin-level connection holding the organization, repository, default labels, and default assignee, and validate it at setup by performing a real read against the repository. Store the credential server-side only; it must never reach the browser, an environment file shipped to the client, or the issue body.
2. Assemble the issue body on the server from what the app already knows: the originating record, the acting user's role, the app version or release, and a deep link back into the app. Redact tokens, session identifiers, and personal data from any log excerpt or screenshot before it is attached.
3. Derive a stable idempotency key from the originating record and check for an existing issue reference before creating anything, so a retry, a double click, or a timed-out request that actually succeeded does not open a second issue.
4. Persist the returned issue reference and its last known state on the record, and update that state from GitHub's webhooks. Treat webhook deliveries as at-least-once and possibly out of order: dedupe by delivery identifier and ignore an event older than the state you already hold.
5. GitLab Issue Creation, Linear Issue Creation, Jira Ticket Creation, Trello Card Creation, and Asana Task Creation are siblings of this brief. Put the shared half — capturing the report, redacting it, deduplicating, and storing the external reference — in one place, and let each provider own only its authentication, field mapping, and error translation.

## 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 connection's organization, repository, labels, and assignee must be chosen from what the connected account can actually see, and re-validated when used. A repository renamed, transferred, or archived since setup has to surface a clear configuration error to an administrator rather than silently dropping reports.
- Logs, stack traces, and screenshots routinely contain access tokens, email addresses, and customer data. Redact server-side before upload, and where a screenshot cannot be inspected, require the reporter to confirm it contains nothing private.
- Repeated reports of the same problem must not produce dozens of issues. Fingerprint on the error signature or the originating record, and comment on or link to the existing issue instead of opening a new one.
- The reporting user usually has no GitHub account and no access to the repository. Create the issue through the app's own connection, attribute the reporter in the body, and never expose the repository or the issue's private contents back to a user who should not see them.
- Store the issue reference immediately so status can be synchronised later. Without it, a closed issue never gets reflected back to the person who reported the problem.
- The stored credential will expire, be revoked, or lose a scope. Detect authentication failures distinctly from other errors, queue the affected reports, and notify an administrator to reconnect rather than discarding the submissions.
- Rate limiting and secondary abuse limits need exponential backoff with jitter and a bounded retry window, with the reports held in the queue meanwhile.
- When GitHub is unavailable, accept the report into the app first and create the issue asynchronously. The user should see that their feedback was received, not an error from 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

- [ ] A report submitted in the app becomes an issue in the configured repository with a link back to the originating record.
- [ ] The repository credential exists only on the server and never appears in client code, responses, or issue content.
- [ ] Retries and duplicate submissions reuse the existing issue rather than creating another.
- [ ] Attached logs and screenshots are redacted before they leave the app.
- [ ] The issue reference and its current state are stored on the record and updated from webhooks idempotently.
- [ ] Expired or revoked credentials queue the reports and alert an administrator instead of failing silently.
- [ ] A GitHub outage still records the user's report, which is created once the service 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.