Wizard dialogues — end-to-end examples¶

Three full conversations showing how the wizard runs. Use these as the model for tone and pacing: the workflow talks like a colleague, not a form.

Example 1 — Golden path, user knows what they want¶

User: Creá un ticket en el board de Onboarding: cuando el usuario tiene MFA expirado y entra a /dashboard, debería redirigir a /mfa-setup.

Workflow (precheck — silent if both MCPs are loaded; here they are): (no output)

Workflow (Phase 0 — team is explicit):

Got it — Onboarding team, project ON. Let me check the issue types available there.

(queries issue types)

Suggested type: Bug (sounds like a defect: current behavior is wrong, expected is the redirect). Other types available in ON: Task, Story, Epic, Design Task, Automation Task.

Confirm Bug, or pick another?

User: Bug está bien.

Workflow (Phase A — General description):

Quick summary for the General description. I'd phrase it as:

When a user's MFA token is expired (>24h) and they navigate to /dashboard, they currently see broken UI because protected API calls return 401. Expected: redirect to /mfa-setup so MFA can be re-established.

Want me to keep that, or rewrite?

User: Sumá que tiene que preservar la URL original como query param.

Workflow:

Updated:

When a user's MFA token is expired (>24h) and they navigate to /dashboard, they currently see broken UI because protected API calls return 401. Expected: redirect to /mfa-setup so MFA can be re-established. The original target URL must be preserved as a query parameter so the user lands back where they intended after re-auth.

OK?

User: Sí.

Workflow:

Any tags for the title? E.g. [BE], [FE], [bug]. Skip to omit.

User: [BE]

Workflow:

Title (auto-generated from the description, max 60–70 chars):

[BE] Redirect to /mfa-setup when MFA token is expired

Confirm or rewrite?

User: Confirm.

Workflow (AC, assisted mode):

Now Acceptance Criteria. From your original description I'd write one scenario:

Scenario 1: MFA-expired user is redirected to setup¶

Given a logged-in user whose MFA token expired more than 24h ago

When the user navigates to /dashboard

Then the user is redirected to /mfa-setup

And the original target URL is preserved as a query param

Want me to add scenarios for related cases (e.g. exactly at the 24h boundary, user without MFA devices)?

User: Sí, agregá uno para el caso del usuario sin dispositivos MFA registrados.

Workflow:

Added:

Scenario 2: User without MFA devices sees the error message¶

Given a logged-in user with expired MFA and no registered MFA devices

When the user navigates to /dashboard

Then the user is redirected to /mfa-setup

And the page shows the "no MFA devices registered" message

Add another scenario, or move on to the optional sections?

User: Move on.

Workflow (Phase B):

How to test — want to add QA tips? Test data per env, accounts, flags, edge cases.

User: Sí, dev: usuario qa+mfa-expired@securitize.io, flag mfa-enforce tiene que estar en on (default).

Workflow:

Got it. Figma URL?

User: Skip.

Workflow: Screenshots?

User: Skip.

Workflow:

Technical notes? Implementation hints, libs, related tickets.

User: Sí: la lógica del redirect tiene que vivir en apps/dashboard/src/middleware/auth-guard.ts. Hay un redirect similar para usuarios no verificados — mantener consistencia. Relacionado: ON-1102.

Workflow (Phase C — batched in one turn):

Assignee (name / email or unassigned), labels (or none), priority (Highest / High / Medium / Low / Lowest, default Medium)?

User: unassigned, no labels, default priority.

Workflow (Phase D — loads references/jira-boards.md to fetch the board URL, then renders preview):

Here's the full preview before I create it:

Project: ON · Type: Bug · Assignee: unassigned · Board: https://securitize.atlassian.net/jira/software/projects/ON/boards/99

Title: [BE] Redirect to /mfa-setup when MFA token is expired

General description¶

When a user's MFA token is expired (>24h) and they navigate to /dashboard, they currently see broken UI because protected API calls return 401. Expected: redirect to /mfa-setup so MFA can be re-established. The original target URL must be preserved as a query parameter so the user lands back where they intended after re-auth.

Acceptance Criteria¶

Scenario 1: MFA-expired user is redirected to setup¶

Given a logged-in user whose MFA token expired more than 24h ago

When the user navigates to /dashboard

Then the user is redirected to /mfa-setup

And the original target URL is preserved as a query param

Scenario 2: User without MFA devices sees the error message¶

Given a logged-in user with expired MFA and no registered MFA devices

When the user navigates to /dashboard

Then the user is redirected to /mfa-setup

And the page shows the "no MFA devices registered" message

How to test¶

dev¶

User: qa+mfa-expired@securitize.io

Flag mfa-enforce must be on (default).

Technical notes¶

Redirect logic should live in apps/dashboard/src/middleware/auth-guard.ts. A similar redirect exists for unverified users — keep them consistent.

Related: ON-1102.

Confirm to create, or tell me what to change?

User: Dale, creá.

Workflow: (creates the issue)

Created: ON-1234 — https://securitize.atlassian.net/browse/ON-1234

Example 2 — From scratch, non-technical user (product)¶

User: Necesito abrir un ticket.

Workflow (Phase 0 — no team mentioned, no repo inference triggered):

Sure. Which team / Jira board should this go to? Pick one:

ON (Onboarding) — investor onboarding, KYC, Cash Account, Fundraise, Securitize ID

ISR2 (Issuer Experience) — Control Panel for issuers, token configuration & deployment

TA (Transfer Agent) — transfer agent functionality

BC (Blockchain) — smart contracts, blockchain abstraction

AO (BlackOps) — architecture & cross-cutting ops (may not allow ticket creation for your user)

OPS (DevOps) — infrastructure, CI/CD, deployments

CTD (Cross Tech Debt) — for cross-team initiatives, no specific owner

User: ISR.

Workflow:

ISR2 it is.

(queries issue types in ISR2)

What kind of ticket is this? Quick guide: - Bug — something is broken / wrong. - Task — small, distinct piece of work. - Story — new capability for an end user. - Epic — large initiative spanning multiple tickets. - Also available in ISR2: Spike, Deployment Issue, Design task, Automation Task, Dependency.

User: Story. Quiero que cuando el issuer suba un nuevo logo, se valide que sea PNG o JPG y máximo 2 MB.

Workflow (Phase A — General description, taking the user's framing):

Got it. For the General description I'd write:

When an issuer uploads a logo via the Control Panel, the system should validate the file format (PNG or JPG) and size (≤ 2 MB) before accepting it. Currently any file is accepted, which causes problems downstream when non-image files reach the rendering pipeline.

OK or want to adjust?

User: Sumale que si falla, mostrar un error claro al issuer.

Workflow:

Updated:

When an issuer uploads a logo via the Control Panel, the system should validate the file format (PNG or JPG) and size (≤ 2 MB) before accepting it. Currently any file is accepted, which causes problems downstream when non-image files reach the rendering pipeline. If validation fails, show a clear error message to the issuer indicating the requirement.

Tags for the title? Optional.

User: [FE]

Workflow:

Title:

[FE] Validate issuer logo upload (PNG/JPG, max 2 MB)

Confirm?

User: Sí.

Workflow (AC, assisted):

Acceptance Criteria, structured from what you described:

Scenario 1: Valid logo is accepted¶

Given an issuer on the logo upload screen

When the issuer selects a PNG or JPG file under 2 MB

Then the upload succeeds

And the new logo is shown in the preview

Scenario 2: Wrong format is rejected¶

Given an issuer on the logo upload screen

When the issuer selects a non-PNG / non-JPG file

Then the upload is rejected

And an error message tells the issuer the allowed formats

Scenario 3: Oversized file is rejected¶

Given an issuer on the logo upload screen

When the issuer selects a PNG or JPG larger than 2 MB

Then the upload is rejected

And an error message tells the issuer the size limit

Want to add anything (e.g. extension vs. MIME-type validation, super-admin override) or move on?

User: Está bien así.

(continues with optional sections — user skips Figma, adds a "How to test" with a sample file, skips Screenshots and Technical notes)

(Phase D — preview shown, user confirms, ticket created in ISR2)

Example 3 — Edge case: user lacks permissions¶

User: Creá un ticket en AO para revisar el rate limiting de la pasarela.

Workflow (Phase 0 — team explicit):

AO (BlackOps). Let me check the issue types.

(queries issue types — receives the error "You cannot create issues in this project")

Heads up — your account doesn't have permission to create issues in AO (BlackOps). The Atlassian API returned: "You cannot create issues in this project".

Options: 1. Contact the BlackOps team to file the ticket on your behalf — Team Leader: Gil Hadad (Slack U02S7A0EJ9W / gil.hadad@securitize.io). 2. File it in CTD (Cross Tech Debt) if it's cross-team work. 3. Pick a different board.

User: Dale, lo paso a CTD.

Workflow:

Switching to CTD.

(queries issue types in CTD, continues normally)

Notes on tone¶

Talk like a colleague helping, not like a form. Short sentences, explicit choices, never overwhelming with all options at once.
Always confirm before applying inferences. "Looks like X — confirm?" beats "X." every time.
Show, don't tell. When the workflow auto-generates content (title, AC), show the result and ask for confirmation, not "I will generate the title now".
Match the user's language in chat, but always write the ticket body in English. Conversational replies (questions, confirmations) follow the user's language. The Title, General description, Acceptance Criteria, How to test, and Technical notes are always English — that is the Securitize convention regardless of the chat language. If the user speaks Spanish, draft in English and show for confirmation; do not transcribe verbatim.