# Design: Duplicate ticket detection + human pause

**Date:** 2026-09-15  
**Status:** Approved (Approach 1) — implementing

## Goal

When Agent Nova starts on a new ticket that looks like an existing one, comment on the new ticket with the original key (assignee @mention via existing `add_comment`), pause for a human decision, then either continue or stop.

## Decisions

| Topic | Choice |
|-------|--------|
| Detection | JQL candidates (same project) + LLM decides |
| On match | Comment + pause (`DUPLICATE_REVIEW`) |
| Continue | Human comment containing `continue` |
| Stop | Human comment with `duplicate` or `close as duplicate` |
| Unassigned | No special case — assignee mention handled by `add_comment` |

## Flow

```
analyze get_issue
  → search JQL candidates (exclude self)
  → LLM: is duplicate of any candidate?
  → no  → normal analyze → …
  → yes → comment (original key) → DUPLICATE_REVIEW → END
resume DUPLICATE_REVIEW:
  → continue → clear flag → re-enter analyze (skip dup check once) → …
  → duplicate / close as duplicate → FAILED (+ closing comment)
```

## Implementation touchpoints

- `WorkflowState.DUPLICATE_REVIEW` + ACTIVE_STATES + alembic if needed
- `JiraClient.search_issues`
- LLM helper / analyst method for duplicate check
- Orchestrator gate + route resume
- Webhook `should_resume_duplicate_review` + decision parser
- API webhook handler
- Tests

## Out of scope

- Auto-linking Jira “duplicates” issue link type
- Closing/transitioning the Jira ticket status on “close as duplicate”