---
description: Create or update the feature specification from a natural-language feature description for the ss-tools project (Python backend + Svelte frontend).
handoffs:
  - label: Build Technical Plan
    agent: speckit.plan
    prompt: Create a Python/Svelte implementation plan for the active feature
  - label: Clarify Spec Requirements
    agent: speckit.clarify
    prompt: Clarify specification requirements
    send: true
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

The feature description is the text passed to `/speckit.specify`.

1. Generate a concise short name (2-4 words) for the feature branch.
2. Check existing branches/spec directories and run `.specify/scripts/bash/create-new-feature.sh --json ...` exactly once.
   - This step is the source of truth for the feature lifecycle.
   - It MUST create and checkout the git branch `NNN-short-name` when git is available.
   - It MUST create `specs/NNN-short-name/` and initialize `spec.md` there.
   - Treat the returned `SPEC_FILE` path as authoritative and derive `FEATURE_DIR` from it.
3. Load these sources before writing the spec:
   - `.specify/templates/spec-template.md`
   - `.specify/templates/ux-reference-template.md`
   - `.specify/memory/constitution.md`
   - `README.md`
   - relevant `docs/adr/*` when the feature clearly touches an existing architectural lane
4. Create or update the following artifacts inside `FEATURE_DIR` only:
   - `spec.md`
   - `ux_reference.md`
   - `checklists/requirements.md`
5. Generate `ux_reference.md` as an **interaction reference** for operators, API callers, and (when applicable) browser-based UI flows. Capture result envelopes, warnings, and recovery behavior.
6. Write `spec.md` focused on **what** the user/operator needs and **why**, not how Python or Svelte will implement it.
7. Validate the spec against a requirements-quality checklist and iterate until major issues are resolved.

## Specification Rules

- Use domain language appropriate for this repository: Superset dashboards, datasets, migrations, Git operations, tasks, plugins, RBAC, WebSocket logging.
- Avoid leaking implementation details such as module names, file-level refactors, Pydantic schemas, or Svelte component names.
- Use `[NEEDS CLARIFICATION: ...]` only for truly blocking product ambiguities. Maximum 3 markers.
- Prefer informed defaults grounded in repository context over unnecessary clarification.
- Feature may be backend-only (Python/FastAPI), frontend-only (Svelte/Tailwind), or fullstack (both).
- Do not write feature outputs to `.kilo/plans/`, `.kilo/reports/`, or any path outside `specs/<feature>/...`.

## UX / Interaction Reference Rules

- `ux_reference.md` is mandatory.
- For backend/API features: capture caller persona, happy-path invocation flow, result envelope expectations, warning/degraded states, failure recovery guidance, and canonical terminology.
- For frontend features: additionally capture UI states, navigation flows, WebSocket feedback expectations, and browser-verifiable behavior.
- Only include `@UX_*` guidance when the feature has a user interface component.

## Quality Validation

Generate `FEATURE_DIR/checklists/requirements.md` and ensure it validates:
- no implementation leakage into `spec.md`
- compatibility with the Python/Svelte ss-tools stack
- measurable success criteria
- explicit edge cases and recovery paths
- decision-memory readiness for downstream planning

If unresolved clarification markers remain, present them in a compact, high-impact format and stop for user input.

## Completion Report

Report:
- branch name
- feature directory under `specs/`
- `spec.md` path
- `ux_reference.md` path
- checklist path and status
- readiness for `/speckit.clarify` or `/speckit.plan`