From 994c0c3e5da8b89835deed845a7b4bd88e7841a6 Mon Sep 17 00:00:00 2001 From: busya Date: Fri, 30 Jan 2026 12:31:19 +0300 Subject: [PATCH] feat(speckit): integrate ux reference into workflows Introduce a UX reference stage to ensure technical plans align with user experience goals. Adds a new template, a generation step in the specification workflow, and mandatory validation checks during planning to prevent technical compromises from degrading the defined user experience. --- .kilocode/workflows/speckit.plan.md | 6 +- .kilocode/workflows/speckit.specify.md | 25 +++++++- .specify/templates/spec-template.md | 1 + .specify/templates/ux-reference-template.md | 67 +++++++++++++++++++++ 4 files changed, 96 insertions(+), 3 deletions(-) create mode 100644 .specify/templates/ux-reference-template.md diff --git a/.kilocode/workflows/speckit.plan.md b/.kilocode/workflows/speckit.plan.md index 60cc4ce..cc621bc 100644 --- a/.kilocode/workflows/speckit.plan.md +++ b/.kilocode/workflows/speckit.plan.md @@ -22,7 +22,7 @@ You **MUST** consider the user input before proceeding (if not empty). 1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). -2. **Load context**: Read FEATURE_SPEC, `semantic_protocol.md` and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied). +2. **Load context**: Read FEATURE_SPEC, `ux_reference.md`, `semantic_protocol.md` and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied). 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to: - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION") @@ -64,6 +64,10 @@ You **MUST** consider the user input before proceeding (if not empty). **Prerequisites:** `research.md` complete +0. **Validate Design against UX Reference**: + - Check if the proposed architecture supports the latency, interactivity, and flow defined in `ux_reference.md`. + - **CRITICAL**: If the technical plan requires compromising the UX defined in `ux_reference.md` (e.g. "We can't do real-time validation because X"), you **MUST STOP** and warn the user. Do not proceed until resolved. + 1. **Extract entities from feature spec** → `data-model.md`: - Entity name, fields, relationships - Validation rules from requirements diff --git a/.kilocode/workflows/speckit.specify.md b/.kilocode/workflows/speckit.specify.md index 49abdcb..1aaa1cd 100644 --- a/.kilocode/workflows/speckit.specify.md +++ b/.kilocode/workflows/speckit.specify.md @@ -70,7 +70,22 @@ Given that feature description, do this: 3. Load `.specify/templates/spec-template.md` to understand required sections. -4. Follow this execution flow: +4. **Generate UX Reference**: + + a. Load `.specify/templates/ux-reference-template.md`. + + b. **Design the User Experience**: + - **Imagine you are the user**: Visualize the interface and interaction. + - **Persona**: Define who is using this. + - **Happy Path**: Write the story of the perfect interaction. + - **Mockups**: Create concrete CLI text blocks or UI descriptions. + - **Errors**: Define how the system guides the user out of failure. + + c. Write the `ux_reference.md` file in the feature directory. + + d. **CRITICAL**: This UX Reference is now the source of truth for the "feel" of the feature. The technical spec MUST support this experience. + +5. Follow this execution flow: 1. Parse user description from Input If empty: ERROR "No feature description provided" @@ -115,6 +130,12 @@ Given that feature description, do this: - [ ] Focused on user value and business needs - [ ] Written for non-technical stakeholders - [ ] All mandatory sections completed + + ## UX Consistency + + - [ ] Functional requirements fully support the 'Happy Path' in ux_reference.md + - [ ] Error handling requirements match the 'Error Experience' in ux_reference.md + - [ ] No requirements contradict the defined User Persona or Context ## Requirement Completeness @@ -190,7 +211,7 @@ Given that feature description, do this: d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status -7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`). +7. Report completion with branch name, spec file path, ux_reference file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`). **NOTE:** The script creates and checks out the new branch and initializes the spec file before writing. diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md index c67d914..8419175 100644 --- a/.specify/templates/spec-template.md +++ b/.specify/templates/spec-template.md @@ -1,6 +1,7 @@ # Feature Specification: [FEATURE NAME] **Feature Branch**: `[###-feature-name]` +**Reference UX**: `[ux_reference.md]` (See specific folder) **Created**: [DATE] **Status**: Draft **Input**: User description: "$ARGUMENTS" diff --git a/.specify/templates/ux-reference-template.md b/.specify/templates/ux-reference-template.md new file mode 100644 index 0000000..61e3145 --- /dev/null +++ b/.specify/templates/ux-reference-template.md @@ -0,0 +1,67 @@ +# UX Reference: [FEATURE NAME] + +**Feature Branch**: `[###-feature-name]` +**Created**: [DATE] +**Status**: Draft + +## 1. User Persona & Context + +* **Who is the user?**: [e.g. Junior Developer, System Administrator, End User] +* **What is their goal?**: [e.g. Quickly deploy a hotfix, Visualize complex data] +* **Context**: [e.g. Running a command in a terminal on a remote server, Browsing the dashboard on a mobile device] + +## 2. The "Happy Path" Narrative + +[Write a short story (3-5 sentences) describing the perfect interaction from the user's perspective. Focus on how it *feels* - is it instant? Does it guide them?] + +## 3. Interface Mockups + +### CLI Interaction (if applicable) + +```bash +# User runs this command: +$ command --flag value + +# System responds immediately with: +[ spinner ] specific loading message... + +# Success output: +✅ Operation completed successfully in 1.2s + - Created file: /path/to/file + - Updated config: /path/to/config +``` + +### UI Layout & Flow (if applicable) + +**Screen/Component**: [Name] + +* **Layout**: [Description of structure, e.g., "Two-column layout, left sidebar navigation..."] +* **Key Elements**: + * **[Button Name]**: Primary action. Color: Blue. + * **[Input Field]**: Placeholder text: "Enter your name...". Validation: Real-time. +* **States**: + * **Default**: Clean state, waiting for input. + * **Loading**: Skeleton loader replaces content area. + * **Success**: Toast notification appears top-right: "Saved!" (Green). + +## 4. The "Error" Experience + +**Philosophy**: Don't just report the error; guide the user to the fix. + +### Scenario A: [Common Error, e.g. Invalid Input] + +* **User Action**: Enters "123" in a text-only field. +* **System Response**: + * (UI) Input border turns Red. Message below input: "Please enter text only." + * (CLI) `❌ Error: Invalid input '123'. Expected text format.` +* **Recovery**: User can immediately re-type without refreshing/re-running. + +### Scenario B: [System Failure, e.g. Network Timeout] + +* **System Response**: "Unable to connect. Retrying in 3s... (Press C to cancel)" +* **Recovery**: Automatic retry or explicit "Retry Now" button. + +## 5. Tone & Voice + +* **Style**: [e.g. Concise, Technical, Friendly, Verbose] +* **Terminology**: [e.g. Use "Repository" not "Repo", "Directory" not "Folder"]