Helix router

Show the menu and route to the correct workflow skill. The command commands/helix.md loads this skill; the rules live here only.

Contents

• Opening · Discipline · Refusal-first
• Proactive suggestion · Routing · QA closing · MUST / NEVER
• Must-read files · Dependencies

Opening (always, unless the user already chose a mode)

Respond in the user's language (see user-communication.md) — menus, questions, and replies follow the language the user writes in; keep technical terms, file names, and ticket keys as written. Be concise.

Decide what to show in this order — the first step that applies wins:

1. Named workflow. If the user's message already names a workflow (Thai, informal, or mixed input included), map it via intent-shortcuts.md, extract any issue key or URL from the same message, skip the menu, and go to Routing.
2. Issue key with no mode (/helix {ISSUE_KEY}). Infer the workflow only when the same message also contains a phrase from intent-shortcuts.md (e.g. {ISSUE_KEY} API test cases from Swagger → 2). A bare key or URL alone never picks a workflow: show the menu and ask which option applies to that key.
3. Proactive suggestion. Otherwise apply Proactive suggestion; if it yields one suggestion, show that instead of the menu.
4. Menu. Otherwise show the menu from menu-text.md (Opening block, in the user's language as that file says).

🔴 STOP — wait for the user's choice before starting a workflow.

Discipline

Follow shared-preamble.md.

Refusal-first (precondition gate)

This skill only routes — it does not run tests or post to Jira (see MUST / NEVER). When the goal is already clear, the menu is skipped (Opening step 1) because an extra menu round wastes time.

Refuse, say why in one line, and route instead when:

Proactive suggestion (suggest-only, opt-out)

Apply the trigger table in proactive-qa-triggers.md to the session context (git branch, linked Jira ticket, defects mentioned in chat):

• If HELIX_PROACTIVE=0 is set, or no trigger row matches, make no suggestion — show the menu.
• If one row matches, offer exactly one suggestion instead of the menu. When more than one row matches, apply that file's only tie-break — ticket type wins over branch; if rows still tie, the signal is ambiguous, so follow its last row and show the menu.
• Suggest only — never auto-run a workflow: the user did not ask for it, so starting one is an unrequested side effect (proactive-qa-triggers.md § Hard guardrails).
• 🔴 STOP — one suggestion per turn, then wait for the user to pick (number/name) before loading anything.
• No Jira MCP? Infer from branch + last commit and say so, so the user can correct.
• Wording: use proactive-qa-triggers.md § Suggestion wording exactly — it is the only copy.

Routing

Route by the single table in skill-routing.md § Primary menu: the user's number, option name, or intent-shortcuts phrase picks one row. Do not keep a routing table anywhere else.

The first routed response does these three things in this order, once each:

1. Announce the route. Before loading anything, tell the user in one line, in their language, which workflow you are routing to: the menu number, option name, skill, and command — e.g. Routing to 3 · Retest Bug → retest-bug-workflow (/retest-bug) for {ISSUE_KEY}. No workflow starts without this line. This is the router's own line; it does not replace the shared announce in step 3.
2. Recite the constraints: helix-session-constraints.md once (All Helix block; add the Testing ticket block when routing to 4). The router owns this recital; the child workflow does not recite it again in the same session.
3. Load and follow that row's skills/{name}/SKILL.md completely, opening with the shared announce Using **{skill}** to {purpose}. once (shared-must-never.md, skill-invocation-discipline.md), and passing on what the row says (issue key, URL, TC document, audit target).

When routing cannot proceed:

Handoffs after a workflow ends: skill-routing.md § Handoffs.

QA closing (mandatory before "done")

Follow qa-closing-shared.md + router-specific:

• [ ] User selected a workflow (1–12 or named skill).
• [ ] Child workflow skill is loaded (not just described).
• [ ] No Jira post or issue create happened in this router skill.

If routing only, hint the command from the Command column of skill-routing.md § Primary menu for the chosen row.

MUST / NEVER

Shared rules: shared-must-never.md. Router-specific:

Must-read files

The router itself reads only the first group. The second group is required by the shared rules this skill follows (shared-preamble.md, qa-closing-shared.md, shared-must-never.md); the router never reaches those steps — the routed workflow reads each one at the point its line names. Both groups stay one hop from here so no required rule is two links away.

Read while routing:

• Read agent-rationalizations.md when tempted to skip a step; each excuse has its correct action.
• Read helix-session-constraints.md once at session start.
• Read proactive-qa-triggers.md at Opening step 3, before showing the menu.
• Read session-closing.md at session end.
• Read skill-invocation-discipline.md before invoking or switching skills.
• Read skill-routing.md when choosing which skill handles a request.
• Read skill-rules-style.md before asking the user or stopping on a missing input.

Read only when the routed workflow reaches that step:

• Read bug-priority-matrix.md before setting any priority or a PWMI / FAILED verdict.
• Read customer-escape-prevention.md before any QA run; the gates that stop shipped defects.
• Read defect-report-completeness.md before writing up any defect or non-pass.
• Read figma-design-comparison.md before judging any UI or visual result against the design.
• Read jira-comment-post-review.md after posting a Jira comment, before saying done.
• Read jira-linebreak-conversion.md before posting a Jira table with multi-line cells.
• Read long-workflow-todos.md when the workflow has many steps; keep the todo list.
• Read non-pass-challenge-gate.md before recording any result that is not PASSED.
• Read playwright-preflight.md before any Playwright run.
• Read qa-debug-discipline.md when a test is flaky or a tool errors.
• Read qa-evidence-gates.md before any completion claim.
• Read resilient-selectors.md when writing or fixing Playwright selectors.
• Read result-quality-gate.md before any verdict leaves the round.
• Read root-cause-investigation.md before naming a cause for any failure.
• Read round-time-contract.md when a round starts and before reporting times.
• Read test-through-real-steps.md before testing an action; no API shortcut for the action under test.
• Read verify-closing-checklist.md before reporting a verify or retest done.

Dependencies

Check these before routing — check commands and install hints are in dependencies.md:

• Atlassian MCP (ticket lookup while routing) — optional; without it, ask the user to paste the ticket text (see Routing)
• each routed skill lists its own dependencies in its ## Dependencies section and re-checks them when it starts

If a check fails, do not stop routing: name the failed dependency in one line, give its install hint or fallback from the dependencies.md row, and still show the menu (or route a named workflow). The routed skill re-checks its own dependencies and stops there if a missing one is required.