82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
---
|
|
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`
|
|
- `.opencode/skills/semantics-core/SKILL.md` — §VIII Attention Architecture for spec density rules
|
|
- `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`
|