Recommended Jira Story Format for AI Test Generation

Why structure matters

When you click Generate from Jira Epic, TestCaseAI fetches the epic and all of its child stories, then runs two AI passes: one to plan the testing strategy (scope, risks, test areas), and a second to generate suites and cases per area.

The quality of those outputs scales directly with how concrete the source stories are. A story with one sentence in the description produces generic, low-signal tests. A story with explicit acceptance criteria, dependencies, and risks produces tests that read like they were written by someone who knows the system.

The template

Five short sections. Paste this into the Jira description (or split across description + a custom Acceptance Criteria field).

**Story**
As a <role>, I want <capability>, so that <benefit>.

**Acceptance Criteria**
- Given <context>, when <action>, then <observable outcome>.
- Given <context>, when <invalid action>, then <error / fallback>.
- …

**Technical Notes**
- Auth: <e.g. requires authenticated session, role X>
- Data: <e.g. new column on users table, default null>
- API: <e.g. new POST /api/x endpoint>
- Out of scope: <e.g. mobile app changes>

**Dependencies**
- Story <KEY-123> must ship first.
- Feature flag <name> must be on.
- Third-party service <name> must be configured.

**Risks**
- <e.g. legacy login flow may break for users with stale sessions>
- <e.g. rate-limit on external API may surface as 429 during burst tests>

What each section contributes

• Story

  The standard As-a / I-want / So-that frame. Gives the model the user role and the goal so generated cases are written from the right perspective.

• Acceptance Criteria

  The single highest-value section. Each AC becomes one or more concrete test cases. Use Given/When/Then form — it maps cleanly to test steps and expected results.

• Technical Notes

  Auth requirements, data shape changes, API contracts, and what's intentionally out of scope. Prevents the model from over-generating cases for tangents.

• Dependencies

  Other stories, feature flags, or services that must be in place. Drives the Dependencies section of the generated Test Plan and shapes the regression-impact analysis.

• Risks

  What might break, and what's fragile about the change. Becomes input for the Risks and Regression Impact sections of the plan; pushes the model to generate targeted edge and regression cases.

A quick before / after

User should be able to reset password.

**Story**
As a returning user who forgot their password, I want to request a reset link, so that I can regain access without contacting support.

**Acceptance Criteria**
- Given a registered email, when I submit the reset form, then I receive an email with a single-use link valid for 1 hour.
- Given an unregistered email, when I submit the form, then I see a generic success message (no enumeration).
- Given an expired link, when I open it, then I see an expired-link page and can request a new one.

**Technical Notes**
- New endpoint POST /api/auth/password-reset.
- Reuses existing email service (SendGrid template id pwd_reset_v2).
- Out of scope: SSO users (separate flow).

**Dependencies**
- Story AUTH-118 (rate limiting middleware) must be merged first.

**Risks**
- Reset email may land in spam for some Outlook tenants — verify DKIM.
- Existing reset-via-support flow should keep working until this is live.

The “After” version produces a plan with explicit test areas (request flow, error states, expiry, deliverability), maps suites to specific story keys, and surfaces the Outlook-DKIM risk as a regression-impact bullet.

Privacy

Jira ticket content is processed transiently and is not permanently stored unless explicitly saved by the customer. We retain only issue keys, URLs, and the test artifacts you choose to save. OAuth tokens are stored encrypted; you can disconnect any time from Settings → Integrations.