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

# System Map

> The two-way support-to-engineering architecture for bug intake

This system keeps three records connected: the original customer ticket, the engineering issue, and the internal engineering discussion. Workflows own state and synchronization. Agents handle interpretation, communication, and summaries.

## Two-Way Operational Flow

```mermaid theme={null}
flowchart TD
  Customer["Customer bug report"]
  Customer --> Intake["Support ticket deployment"]
  Intake --> Normalize["Bug intake workflow"]
  Normalize --> Context["Customer and product context workflow"]
  Context --> Repro["Repro gathering workflow"]
  Repro --> Readiness["Repro readiness check"]

  Readiness --> FollowUp["Customer follow-up workflow"]
  FollowUp --> OriginalTicket["Original support ticket"]
  OriginalTicket --> CustomerAnswer["Customer answer"]
  CustomerAnswer --> Repro

  Readiness --> BugAgent["Bug intake agent"]
  BugAgent --> Draft["Engineering-ready report draft"]
  Draft --> IssueWorkflow["Engineering issue workflow"]
  IssueWorkflow --> Issue["Linear or Jira issue"]
  IssueWorkflow --> SlackAgent["Engineering Slack agent"]
  SlackAgent --> EngChannel["Engineering triage channel"]

  EngChannel --> Question["Engineering question"]
  Question --> SlackAgent
  SlackAgent --> QuestionWorkflow["Question routing workflow"]
  QuestionWorkflow --> OriginalTicket
  CustomerAnswer --> AnswerWorkflow["Answer sync workflow"]
  AnswerWorkflow --> Issue
  AnswerWorkflow --> EngChannel

  Issue --> IssueUpdate["Issue update deployment"]
  IssueUpdate --> Resolution["Resolution workflow"]
  Resolution --> ResolutionDraft["Customer resolution draft"]
  ResolutionDraft --> OriginalTicket
  OriginalTicket --> Runs["Runs and analytics"]
```

## Reporting and Improvement Loop

```mermaid theme={null}
flowchart TD
  Runs["Runs and analytics"]
  Issues["Linear or Jira issue outcomes"]
  Support["Support ticket outcomes"]

  Runs --> Scheduler["Scheduler deployment"]
  Issues --> Reporting["Duckie Assistant reporting agent"]
  Support --> Reporting
  Scheduler --> Reporting
  Reporting --> Stakeholders["Support and engineering stakeholders channel"]

  Runs --> Feedback["Duckie Assistant feedback agent"]
  Issues --> Feedback
  Support --> Feedback
  Feedback --> Proposals["Improvement proposals"]
  Proposals --> Review["Support operations and engineering review"]
  Review --> Updates["Repro checklist, issue template, routing rules, and tools"]
  Updates --> Testing["Replay and batch testing"]
  Testing --> Deploy["Updated deployments"]
```

## Component Responsibilities

| Component                                 | Responsibility                                                                                     |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Support ticket deployment**             | Starts the system from a customer support ticket, chat, email, or webhook.                         |
| **Bug intake workflow**                   | Normalizes the report, links records, and owns intake state.                                       |
| **Customer and product context workflow** | Fetches account, environment, plan, product usage, incident, and version context.                  |
| **Repro gathering workflow**              | Checks for steps, expected behavior, actual behavior, logs, screenshots, environment, and impact.  |
| **Bug intake agent**                      | Interprets the messy customer report and drafts an engineering-ready summary.                      |
| **Engineering issue workflow**            | Creates or updates Linear or Jira issues with consistent fields and links.                         |
| **Engineering Slack agent**               | Posts summaries and questions to an internal engineering channel and returns structured decisions. |
| **Question routing workflow**             | Sends engineering questions back to the original customer conversation.                            |
| **Answer sync workflow**                  | Sends customer answers back to the Linear or Jira issue and Slack thread.                          |
| **Resolution workflow**                   | Detects issue completion and routes the final customer update through support.                     |
| **Duckie Assistant reporting agent**      | Posts scheduled summaries about bug intake volume, blockers, and resolutions.                      |
| **Duckie Assistant feedback agent**       | Reviews runs and corrections to improve Duckie configuration.                                      |

## Deterministic vs Autonomous

Use deterministic workflows for:

* Record linking between support ticket, issue, and Slack thread
* Required repro checklist checks
* Duplicate detection rules
* Allowed issue field values
* Linear or Jira issue creation and update
* Customer question routing
* Customer answer sync
* Issue status handling
* Final customer follow-up gating

Use autonomous agents for:

* Interpreting unclear customer reports
* Summarizing technical context
* Drafting reproduction steps
* Drafting engineering issue descriptions
* Translating engineering questions into customer-friendly language
* Drafting resolution messages
* Summarizing blocked issues and trends

<Tip>
  The critical design choice is the record map. Store the support ticket ID, engineering issue ID, Slack thread link, customer follow-up status, and current owner in workflow state so every update can route back to the right place.
</Tip>

## Deployment Inventory

| Deployment                          | Trigger                                                             | Target                             | Mode to start |
| ----------------------------------- | ------------------------------------------------------------------- | ---------------------------------- | ------------- |
| **Bug intake**                      | Ticket created, message received, email received, or custom webhook | Bug intake workflow                | Testing       |
| **Engineering issue sync**          | Linear or Jira issue created, updated, completed, or commented      | Resolution or answer sync workflow | Testing       |
| **Engineering Slack collaboration** | Internal Slack channel or workflow escalation request               | Engineering Slack agent            | Testing       |
| **Daily bug intake report**         | Scheduler, such as weekdays at 9 AM                                 | Duckie Assistant reporting agent   | Testing       |
| **Bug intake feedback review**      | Scheduler or manual internal request                                | Duckie Assistant feedback agent    | Testing       |

## Related Docs

<CardGroup cols={2}>
  <Card title="Custom Webhooks" icon="plug" href="/deployments/custom-webhooks">
    Trigger Duckie from issue tracker or internal events.
  </Card>

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

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

  <Card title="Runs" icon="clock-rotate-left" href="/analytics/runs">
    Inspect linked support, engineering, and Slack activity.
  </Card>
</CardGroup>