Clarify gate in Jira: intake to a mature ticket

Problem

A requester creates a Jira ticket in free form: "integrate with ERP," "need a sales report," "speed up the catalog." Development and the agent in the IDE receive this text as input — and either go in the wrong direction or spend weeks clarifying in chat threads that never make it into the tracking system.

The root isn't the model: the spec is implicit — no boundaries, no verifiable acceptance criteria, no answer to "what exactly counts as done." Slack clarifications aren't attached to the ticket: they don't scale and don't version alongside the task.

A clarify gate is needed at the process level: a ticket doesn't move to development until Jira records a goal, scope, and acceptance criteria, agreed with the requester.

Methodology

Breakdown scope: the loop requester → Jira → agent to a mature ticket. What the team does after Ready for dev is out of scope.

Clarify gate

The clarify phase lives in the issue: the agent runs a structured dialogue in comments (or a dedicated field) until "spec is ready" criteria are met. This is a gate, analogous to an eval gate before release (#10): bad input doesn't move forward.

Principles

1. 1. One issue — one clarification trail. All dialogue in Jira. History visible to requester, PM, and developer; context isn't lost when ownership changes.
2. 2. Questions along axes. Scope, actors, data, NFR, dependencies, AC — fill gaps, not free-form chat.
3. 3. Explicit readiness criterion. In the description: goal, scope, verifiable AC, flagged risks. Until then — status "Needs clarification," development doesn't start.
4. 4. Human in the loop. The bot proposes a description draft; the requester or PO confirms (approve). No auto-writing "as AI said" to production fields.
5. 5. Output — a mature ticket. Description + AC in Jira — what goes into development; a draft "to copy to Confluence" is not the goal here.

Project context (why the gate is weak without it)

Without context the agent asks generic questions — the requester answers just as abstractly. Project context is a managed substrate: for each round a context pack is assembled (issue + relevant fragments), without dumping all of Confluence into the prompt.

Grounded questions (redacted intake, B2B catalog)

Raw ticket: "B2B catalog report for the quarter, fast if possible, maybe ERP."

Without context pack, often just: "Which systems are involved?"

With context pack (bible + corpus + PROJ-89 fragments):

1. 1. Architecture: catalog is Elasticsearch + B2B storefront in PostgreSQL. Report on the full index or storefront only?
2. 2. Storefront SLA p99 200 ms — hard constraint for batch exports too?
3. 3. PROJ-89 closed the Q3 B2B report — extension or new export?
4. 4. Glossary: ERP is 1C and SAP; is integration in scope for this ticket?
5. 5. No PII policy for reports in documentation — retention period and access level?

Requester gets business language. Citations are in the internal audit log, not in the comment body.

Per-round pipeline

Parse issue → route (which context levels) → retrieve (pack)
→ gap analysis → 3–5 questions → comment reply
→ gap analysis → description draft + AC + diff "was / proposed"
→ approve → transition Ready for dev

Artifact

github.com/dobryakov/jira-clarify-bot — Python, FastAPI, Docker. In git: clarify gate mechanics, webhook contract (openapi.yaml, JSON Schema), and a full run without calls to *.atlassian.net.

The public repo is a reproducible trace of the mechanics and the webhook contract — not a ready-to-run bot for your Jira instance out of the box. What's outside the repo — the parts tied to your specific stack: webhook registration and auth in Jira Cloud; Atlassian REST / ADF client and custom AC field mapping; production corpus pipeline (L2) and its update schedule; multi-tenant setup.

For whom and why

Risk: "speed up the catalog" — and three weeks in the wrong direction. The gap between what's written in Jira and what was discussed in messengers is expensive.

Solution: a task doesn't move to development without a goal, scope, and AC — not bureaucracy, but the place where delivery breaks most often.

Metric: time from task creation to first commit and number of mid-sprint clarifications — both are measurable and both go down.

PO, CTO, Head of AI: delivery input quality improves in Jira, without a new tool for the requester. Architecturally, this is a gate on intake. Unlike breakdown #2 (bots-discuss-spec): internal clarify "business ↔ agent" within one issue, no cross-org API negotiation.