# xqa-spec

## When to use

- User runs `/xqa-spec` with a flow description
- User implies spec authoring intent: "I want to test X", "write a spec for Y", "update the Z spec"

Detect implied intent and self-activate without requiring explicit slash command.

## Process

```
Explore → Detect mode → Interview (one question at a time) → Draft → Review → Write
```

IMPORTANT: Never generate a draft before the interview is complete. The user describes the spec; you transcribe it.

### 1. Explore

Silently scan `.xqa/specs/*.test.md`. Learn:

- Naming conventions
- Tag vocabulary
- Level of detail and step granularity

Also read `.xqa/app.md` if it exists for app context.

### 2. Detect mode

| Condition                | Mode                                            |
| ------------------------ | ----------------------------------------------- |
| Matching spec file found | Edit — read it, ask which sections to change    |
| No match                 | Create — derive kebab-case filename from intent |

In **edit mode**: ask which sections to change before doing anything. Modify only those sections; preserve everything else verbatim.

### 3. Interview (create mode only)

Ask one question at a time. Wait for the answer before asking the next. Prefer multiple choice when options are known.

**Question sequence:**

1. **What flow?** — Confirm what's being tested if not already clear. Suggest a filename and `feature` name.
2. **Entry point** — "What's the navigation path to reach this flow?" (e.g., `App launch`, `Home > Wallet`) → becomes `entry:` frontmatter
3. **Starting state** — "What's already set up? What state is the device/app in?" → becomes `## Setup`
4. **Steps** — "Walk me through the steps, one at a time. I'll ask for the next when you're done." → collect each step, then ask "What should happen?" for the assertion (optional)
5. **Global assertions** — "Any overall things that should be true at the end of the flow?" → becomes `## Assertions` (skip if none)
6. **Timeout** — "Set a timeout in seconds? (optional, for long-running specs)" → becomes `timeout:` frontmatter (offer to skip)

IMPORTANT: Ask each question in its own message. Never batch questions.

### 4. Draft

Assemble using ONLY these frontmatter fields: `feature`, `entry`, `timeout`. Do not add any other frontmatter field. `feature` MUST be present. `timeout` MUST be a positive number (seconds) if included.

Steps and assertions come from the user — never invent them. Present the full draft for review.

### 5. Review

Show the draft. Ask: "Does this look right, or anything to change?"

Iterate until approved. One round of changes per message.

### 6. Write

Save to `.xqa/specs/<name>.test.md` only after explicit approval.

## File format

```md
---
feature: <string>
entry: <string>
timeout: <seconds>
---

## Setup

<preconditions and starting state>

## Steps

1. <action> → <expected outcome>
2. <action>

## Assertions

- <global flow-level check>
```

Omit `entry` and `timeout` lines if not provided. Omit `## Assertions` section if none.

## Rules

- `## Setup` and `## Steps` are required; `## Assertions` is optional
- Inline assertion syntax: `action → outcome` using the → character
- Steps come from the user — never invent them
- Write file only after explicit approval
- In edit mode, ask before touching anything
