> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Engineering Issue Workflow

> Create and sync Linear or Jira issues from support bug reports

The engineering issue workflow turns a repro-ready intake case into a Linear or Jira issue. It should be deterministic because issue fields, labels, links, and sync behavior need to stay consistent.

## What It Does

The engineering issue workflow:

* Receives a repro-ready bug intake record
* Checks for duplicate or related engineering issues
* Drafts a concise engineering issue description
* Sets team, project, labels, priority, severity, and customer impact fields
* Links the issue to the original support ticket and Duckie run
* Posts a summary to an engineering Slack channel when review is needed
* Syncs issue comments, questions, status changes, and resolution back to the workflow

## Recommended Components

| Need                    | Duckie component                                           |
| ----------------------- | ---------------------------------------------------------- |
| Create or update issues | Linear or Jira app tools                                   |
| Enforce field values    | Engineering issue workflow                                 |
| Draft issue content     | Bug intake agent called by workflow                        |
| Detect duplicates       | Issue tracker search tool and deterministic matching rules |
| Notify engineering      | Slack engineering agent                                    |
| Sync issue updates      | Issue tracker deployment or custom webhook                 |

## Flow

```mermaid theme={null}
flowchart TD
  Intake["Repro-ready bug intake case"]
  Intake --> Duplicate["Duplicate issue check"]
  Duplicate --> Existing["Link to existing issue"]
  Duplicate --> Draft["Draft issue description"]
  Draft --> Validate["Validate required issue fields"]
  Validate --> Create["Create Linear or Jira issue"]
  Existing --> Link["Update support ticket with issue link"]
  Create --> Link
  Create --> Slack["Post engineering summary to Slack"]
  Slack --> Review["Engineering triage review"]
  Review --> Sync["Record issue and thread links"]
```

## Issue Content

The created issue should include:

* Short title with product area and observed failure
* Customer impact and severity
* Affected customer or account link when allowed
* Reproduction steps
* Expected behavior
* Actual behavior
* Environment details
* Logs, screenshots, recordings, or trace links
* Known incident or duplicate references
* Original support ticket link
* Duckie run link
* Support owner or follow-up owner

## Suggested Issue Contract

```json theme={null}
{
  "title": "[Dashboard] Blank state after login for priority customer",
  "description": "Customer can log in, but the dashboard loads as a blank page.",
  "product_area": "dashboard",
  "severity": "high",
  "priority": "urgent",
  "labels": ["customer_reported", "dashboard"],
  "team": "web app",
  "customer_impact": "Priority customer cannot view project metrics.",
  "steps_to_reproduce": ["log in as affected user", "open dashboard"],
  "expected_behavior": "dashboard loads project metrics",
  "actual_behavior": "dashboard is blank",
  "support_ticket_url": "https://helpdesk.example/tickets/123",
  "duckie_run_url": "https://duckie.example/runs/run_123"
}
```

## Sync Fields

Store the relationship between systems in workflow state or a durable record.

| Field                          | Purpose                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------ |
| `support_ticket_id`            | Routes customer updates back to the original conversation.                     |
| `engineering_issue_id`         | Updates the correct Linear or Jira issue.                                      |
| `engineering_issue_url`        | Links support and stakeholder updates.                                         |
| `engineering_slack_thread_url` | Keeps engineering discussion tied to the issue.                                |
| `customer_follow_up_status`    | Tracks whether Duckie is waiting on the customer.                              |
| `engineering_question_status`  | Tracks whether engineering is waiting on support or customer input.            |
| `resolution_status`            | Tracks whether the fix is shipped, workaround-only, duplicate, or not planned. |

<Warning>
  Do not let the issue workflow invent severity, priority, or customer commitments outside the team's rules. Let agents recommend values, then let the workflow enforce allowed fields and approval gates.
</Warning>

## Related Docs

<CardGroup cols={2}>
  <Card title="Linear" icon="code-branch" href="/integrations/issues/linear">
    Connect Duckie to Linear issues.
  </Card>

  <Card title="Jira" icon="code-branch" href="/integrations/issues/jira">
    Connect Duckie to Jira issues.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    Build deterministic issue creation and sync logic.
  </Card>

  <Card title="Custom Webhooks" icon="plug" href="/deployments/custom-webhooks">
    Trigger sync from issue tracker events.
  </Card>
</CardGroup>