Skip to main content

Jira Ticket Templates — Ghasi Melmastoon

Companion: JIRA_PROJECT_SETUP.md · REQUIREMENTS_GUARD_RAILS.md · DEFINITION_OF_DONE.md · docs/07-epics-and-user-stories.md

This file is the canonical content template for every Jira issue type in project MEL. The commands/jira-create-from-spec.md playbook (Wave 2) writes new tickets in exactly these shapes. PMs and engineers manually creating tickets must paste from here.

The shapes match the spec story format in docs/07-epics-and-user-stories.md so that every Jira ticket can be round-tripped to/from the spec without information loss.

1. Epic template​

Title format: EP-MEL-NN — <Title> (matches spec).

Description (Markdown / Atlassian wiki, render in either):

## Spec
- Spec ID: **EP-MEL-NN** — link to `docs/07-epics-and-user-stories.md#NN-EP-MEL-NN-<slug>`
- Wave: **R<n>**
- Primary persona: <persona>
- Primary services: `<service-1>`, `<service-2>`, ...
- Frontend surfaces: <web-meta | web-tenant-booking | mobile | desktop | none>

## Outcome
<one paragraph: the user-visible outcome this epic delivers>

## Journeys served
- J-NN — <journey title>
- J-NN — <journey title>

## Workflows served
- W-NN — <workflow title>

## Done definition (epic level)
- Every child story is **Done**.
- Linked journeys (J-NN) are green in `docs/journeys/01-core-user-journeys.md` validation.
- Telemetry from `docs/01-product-overview.md §10` is wired and emitting.
- Owning service's `SERVICE_READINESS.md` signed off.

## Risks
- <risk> → linked register entry in `docs/12-risks-and-tradeoffs.md`

## Cross-references
- `services/<service-1>/SERVICE_OVERVIEW.md`
- `docs/04-event-driven-architecture.md` (events involved)
- `docs/architecture/ADR-NNNN-*.md` (if any)

Required fields: Spec ID, Wave, Primary component, Description, Linked Journey ID(s), Linked Workflow ID(s).

2. Story template​

Title format: MEL-<n>: <Spec story title verbatim> — once Jira assigns the number, the prefix MEL-<n> becomes implicit; the displayed title is the spec story title verbatim. Example: Confirm a reservation with payment outcome.

Description (Markdown):

## Spec
- Spec ID: **US-MEL-NNNN** → see [`docs/07-epics-and-user-stories.md`](https://github.com/.../docs/07-epics-and-user-stories.md#us-mel-nnnn) line `<n>`
- Parent epic: **EP-MEL-NN** — `<epic title>`
- Wave: **R<n>**
- Personas: `<persona>` (primary), `<persona>` (secondary)
- Services: `<service-1>`, `<service-2>`, ...
- Frontend surfaces: `<surface-1>`, `<surface-2>`
- Linked journeys: `J-NN`, `J-NN`
- Linked workflows: `W-NN`

## User story
**As a** <persona>,
**I want** <outcome>,
**so that** <value>.

## Acceptance criteria (Gherkin — 2–5 clauses; QA executes verbatim)

**Scenario:** <happy path label>
- **Given** <precondition>
- **And** <precondition>
- **When** <action>
- **Then** <observable outcome>
- **And** <observable outcome>

**Scenario:** <failure or alternate path label>
- **Given** ...
- **When** ...
- **Then** ...

(Repeat scenarios as needed, max 5.)

## Definition of Done applicability
Tick the groups in the PR template that this story touches:
- [ ] Universal (always)
- [ ] Data / domain
- [ ] API
- [ ] Events
- [ ] Security
- [ ] AI
- [ ] Frontend
- [ ] Observability

## Test types required
- [ ] Unit
- [ ] Integration (Testcontainers; tenant-isolation, outbox, inbox if relevant)
- [ ] Contract (Pact / JSON-Schema)
- [ ] E2E (Playwright / Detox; reference workflow `W-NN`)
- [ ] Offline (only if the story has an offline path)
- [ ] AI eval (only if the story uses an AI capability)
- [ ] Performance (only if the story affects a budgeted screen / endpoint)
- [ ] Security (only if the story touches auth / payment / lock / secrets)

## Complexity & estimate
- Complexity: **S | M | L** (XL forbidden — split)
- Story points: **2 | 5 | 8**

## Out of scope (so we don't accidentally expand)
- <thing 1>
- <thing 2>

## Cross-references
- `services/<service>/API_CONTRACTS.md` (route to add or modify)
- `services/<service>/EVENT_SCHEMAS.md` (event to add or modify)
- `services/<service>/DATA_MODEL.md` (table to add or modify)
- `docs/frontend/05-frontend-workflows.md#w-nn-<slug>` (UI step)
- `docs/architecture/ADR-NNNN-*.md` (if any)

## Risks
- <risk>: <mitigation>

## Notes
<optional engineering notes; don't pollute the AC>

Required fields: Spec ID, Wave, Service(s), Surface(s) (or none), Acceptance Criteria, DoD applicability, Test types, Complexity, Linked Epic, Linked Journey ID(s), Linked Workflow ID(s).

Auto-populated fields after first commit/PR: Branch name, PR URL.

3. Task template (engineering work without a US-MEL-NNNN)​

Title format: <verb in present tense>: <object>. Examples:

  • Refactor: extract idempotency key handling into shared interceptor
  • Tooling: add openapi-diff CI workflow
  • Infra: provision Pub/Sub topics for reservation service

Description (Markdown):

## Why
<1–3 sentences: the problem this task solves; link to the symptoms or the request>

## Scope
- <bullet>
- <bullet>

## Out of scope
- <bullet>

## Acceptance criteria
- [ ] <observable outcome>
- [ ] <observable outcome>

## Affected
- Components: `<component-1>`, `<component-2>`
- Specs: `<doc#section>` (if any)

## Test plan
<what we run to prove this is done>

## Cross-references
- <link>

Required fields: Components, Acceptance Criteria, Complexity. Spec ID is optional (use a synthetic TASK-<n> if your team prefers; Jira automation accepts TASK-\d+).

4. Bug template​

Title format: Bug: <observable symptom in plain English>. Example: Bug: confirming a reservation twice creates two folios.

Description (Markdown):

## Symptom
<one paragraph in user terms>

## Steps to reproduce
1. ...
2. ...
3. ...

## Expected
<what should happen>

## Actual
<what does happen>

## Environment
- App / surface: <web-meta | web-tenant-booking | mobile | desktop>
- Build / commit: <SHA or version>
- Tenant ID (sanitized): `tnt_<prefix>...`
- Browser / OS / device: <details>
- Locale: <BCP-47>

## Telemetry references
- Trace ID: `<traceparent value>`
- Request ID: `<X-Request-Id>`
- Time window (UTC): `<from>` → `<to>`
- Logs: <link to log query>
- Errors: <error code(s) observed>

## Root cause (filled during triage)
<concise analysis>

## Acceptance criteria
- [ ] Failing regression test added under the affected service (`test/integration/...` or `test/unit/...`).
- [ ] Fix lands; regression test goes green.
- [ ] All other tests still green.
- [ ] Telemetry shows the symptom is gone in staging within 24 h.
- [ ] If user-visible: customer-facing release note added.

## Risk
- Severity: **S1 (data loss / outage) | S2 (functional bug, no workaround) | S3 (functional bug, workaround) | S4 (cosmetic)**
- Reachability: <how many tenants / what % of traffic>

## Cross-references
- Linked Story: `MEL-<n>` (the story whose AC this violates)
- Linked Journey: `J-NN` (if relevant)

Required fields: Components, Acceptance Criteria, Severity (custom), Linked Story (if regression of a known story).

Hard rule: every Bug ships with a regression test in the same PR. The DoD bullet regression test added must be ticked.

5. Spike template​

Title format: Spike: <question to answer>. Example: Spike: which Wiegand fallback flow do we use when the encoder is offline?.

Description (Markdown):

## Question
<one-sentence question>

## Why now
<context that motivates the spike>

## Time-box
<hours or days; max 5 dev-days>

## Inputs
- <doc / spec / code reference>
- <vendor doc / external link>

## Expected output
- One of:
  - An ADR draft proposing a decision.
  - A sized story (or set of stories) ready for refinement.
  - A negative result (we tried and it doesn't work) with rationale.

## Out of scope
<what we will not investigate, even if related>

## Cross-references
- <link>

Required fields: Components, Acceptance Criteria (the "expected output" bullets), Complexity (always S or M; XL forbidden — split into multiple spikes).

Hard rule: a Spike that overruns its time-box closes as Won't Do and a follow-up Spike or Story is created. No silent extension.

6. ADR template (Jira issue + git artifact)​

Title format: ADR-NNNN: <decision in plain English>. Example: ADR-0011: Use Drizzle (not TypeORM, not Prisma) for all services.

Description (Markdown):

## Context
<2–4 paragraphs: the problem, constraints, history>

## Decision
<one sentence: the decision>

## Rationale
- <reason>
- <reason>

## Consequences
- Positive: <bullet>
- Negative: <bullet>
- Neutral: <bullet>

## Alternatives considered
- <alternative> — rejected because <reason>
- <alternative> — rejected because <reason>

## Status
- **Proposed | Accepted | Superseded by ADR-NNNN | Deprecated**

## Affected
- Services: <list>
- Specs: <docs to update in same PR>

## Linked
- Epic / Story: `EP-MEL-NN`, `MEL-<n>`
- Risks: <register entry>
- ADRs: <prior ADRs this supersedes or builds on>

Required fields: Components (cross-cutting plus any affected service), Acceptance Criteria, Linked ADR file path. The Jira ticket links to the markdown file under docs/architecture/ADR-NNNN-*.md. The ADR file is the source of truth; the Jira ticket is the workflow artifact.

Hard rule: an ADR moves to Done only when the markdown file is merged into develop AND every service's affected spec is updated in the same PR.

7. Sub-task template (used sparingly)​

Title format: <verb>: <thin slice>. Example: Add: outbox table migration for reservation-service.

Description (Markdown):

## Parent
- MEL-<n> — <parent story or task title>

## Slice
<what this sub-task delivers in isolation>

## Acceptance
- [ ] <thin observable outcome>

Sub-tasks exist only to enable parallelism. They never escape DoR/DoD; the parent ticket carries the spec linkage.

8. Comment templates (used by automation + agents)​

These exact comment shapes are written by commands/jira-sync-status.md (Wave 2). They are copy-pasteable for humans too.

Stage transition (multi-agent workflow):

**Stage:** <stage-name> (e.g., `spec-review`, `architect`, `tests`, `dev`, `qa`, `audit`, `pr`)
**Status:** <pass | block | warning>
**Run:** `planning/ghasi-multi-agent/runs/<slug>/`
**Artifacts:**
- <path 1>
- <path 2>
**Findings:**
- <bullet>
**Next:** <next stage or merge>

PR opened:

**PR opened:** <url>
**Branch:** `features/MEL-<n>-<slug>`
**Affected services:** <list>
**Affected surfaces:** <list>
**DoD checklist:** <link to PR template>

Audit-close-loop iteration:

**Audit iteration:** <n>
**Spec:** `docs/...`
**Deviations remaining:** <count>
**Next action:** <action>

Spec drift detected:

**SPEC DRIFT** — code does not match spec at `<doc#section>`.
**Resolution:** <update code | update spec via ADR>
**Owner:** @<assignee>
**Deadline:** <date>

9. Anti-patterns (auto-flagged in QA / retro)​

  • A Story whose title is "Implement X" (not user-facing). Use the spec story title verbatim instead.
  • A Story whose AC list contains technical implementation steps (e.g., "Create a confirm-reservation.use-case.ts file"). AC describes observable outcomes; design lives in the architect stage.
  • A Bug whose AC says only "fix the bug". AC must include the regression test.
  • A Task whose scope spans multiple sprints (split into one Task per sprint or convert to an Epic).
  • A Spike whose acceptance criteria is "investigate". Acceptance must be the form of the output (ADR draft, sized story, negative result).
  • An ADR whose rationale is < 3 sentences. The point of an ADR is the rationale.
  • A Sub-task that introduces scope absent from the parent.

10. Cross-references​

11. Versioning​

Same governance as CODING_STANDARDS.md §19. Material changes to a template (added required field, changed AC format) require an ADR + a one-time migration of in-flight tickets.