<!-- zibby-template-version: 4 -->
# /zibby-test-write — author a new Zibby test spec

You are helping the user write a new test spec. Specs are plain-language `.txt` files in `test-specs/` (configurable via `.zibby.config.mjs` `paths.specs`). Zibby's runner converts them to Playwright at execution time.

Canonical docs: **https://docs.zibby.app/tests/specs**

## Spec format (informal but conventional)

A spec is mostly imperative English with one action per line. Common shape:

```
Title: <one-line summary>

Setup:
- Open <url>
- Log in as <user>

Steps:
- Click <element>
- Type <value> into <field>
- Wait for <state>

Verify:
- <assertion>
- <assertion>
```

Zibby tolerates loose phrasing — what matters is being unambiguous about WHICH element and WHAT value. Use stable selectors (visible text, ARIA labels) over CSS class names.

## Steps for this command

1. **Ask the user what they want to test.** What's the user flow? What are they verifying? What URL?
2. **Find a similar existing spec to mirror.** `ls test-specs/` and read 1-2 to match the project's conventions.
3. **Write the spec to `test-specs/<kebab-case-name>.txt`** using `Write` tool.
4. **Offer to run it immediately** with `/zibby-test-run` (or just `Bash(zibby test test-specs/<name>.txt)`).

## Naming conventions

- kebab-case: `login-with-sso.txt`, `cart-checkout-happy-path.txt`
- Group by feature: `users-create.txt`, `users-edit.txt`, `users-delete.txt`
- Avoid ambiguous names like `test1.txt`

## When the spec is complex

For multi-page flows or many assertions, split into multiple specs and run them as a collection. Don't pile everything into one spec — Playwright errors are easier to localize when each spec is one user goal.