diff --git a/presets/useblocks-vmodel/README.md b/presets/useblocks-vmodel/README.md new file mode 100644 index 0000000000..c65ddb4b0f --- /dev/null +++ b/presets/useblocks-vmodel/README.md @@ -0,0 +1,119 @@ +# useblocks V-model RST preset + +Switches every spec-kit core command (`/speckit.specify`, `/speckit.plan`, +`/speckit.tasks`, `/speckit.implement`, `/speckit.clarify`, `/speckit.analyze`, +`/speckit.checklist`, `/speckit.constitution`, `/speckit.taskstoissues`) to +emit reStructuredText artefacts with a complete sphinx-needs trace graph: + +User Story → Functional Requirement → Architectural Specification → Implementation Task, +plus optional Risk and Decision records. + +Every artefact is validated by `sphinx-build -b needs -W`. The build is the +oracle, not grep or regex. Open questions live as `[NEEDS CLARIFICATION]` +markers inside directive bodies (the build still passes), and the +`coverage.rst` page lists them for `/speckit.clarify` to resolve. + +## Install + +The preset is not yet listed in the default spec-kit preset catalog. Install from a local checkout of this repository: + +```bash +specify init my-project --integration claude +cd my-project +specify preset add --dev path/to/spec-kit/presets/useblocks-vmodel +``` + +Once the preset is available in your active catalog (set via `SPECKIT_PRESET_CATALOG_URL` or a project-level `.specify/preset-catalogs.yml`), the `--dev` flag is no longer needed: + +```bash +specify preset add useblocks-vmodel +``` + +## First run + +The first command you invoke (typically `/speckit.specify` or +`/speckit.constitution`) detects missing scaffolding and runs the bootstrap +script idempotently: + +```bash +bash .specify/presets/useblocks-vmodel/scripts/bash/bootstrap-vmodel.sh +``` + +PowerShell mirror: + +```powershell +pwsh .specify/presets/useblocks-vmodel/scripts/powershell/bootstrap-vmodel.ps1 +``` + +Bootstrap creates four files at the project root if they are missing: + +- `ubproject.toml`: sphinx-needs schema, link types, ID regex, ubcode config +- `conf.py`: sphinx config wired to `needs_from_toml` +- `coverage.rst`: master document with `:glob:` toctree over `specs/*/` +- `.specify/config.toml`: `format = "rst"` flag consumed by command prompts + +Existing files are left untouched. Bootstrap is safe to re-run. + +## Workflow + +```text +/speckit.constitution # optional: project principles → .specify/memory/constitution.rst +/speckit.specify # → specs//spec.rst with US/REQ/RISK/TC +/speckit.clarify # optional: resolve [NEEDS CLARIFICATION] markers +/speckit.plan # → specs//plan.rst with SPEC/DEC + ancillary docs +/speckit.tasks # → specs//tasks.rst with TASK directives +/speckit.implement # execute tasks while preserving trace links +/speckit.analyze # cross-artefact consistency report +``` + +After each command, `sphinx-build -b needs -W` is the source of truth for +structural completeness. The agent re-runs the build until it is green or +hits the iteration cap (typically 3 attempts). + +## ID conventions + +- `US__`: User Story +- `REQ__`: Functional Requirement +- `SPEC__`: Architectural Specification +- `TASK___`: Implementation Task (for example, `TASK_AUTH_IMPL_001`) +- `TC___`: Test Case (`KIND` ∈ `ACC`, `SYS`, `INT`, `UNIT`) +- `RISK__`: Risk +- `DEC__`: Decision + +ID regex enforced in `ubproject.toml`: +`^[A-Z]+_[A-Z][A-Z0-9_]*$` (digits cannot follow the first underscore). + +## Trace link types + +| Outgoing | Back-link | Direction | +|---|---|---| +| `:traces_to:` | `:traces_from:` | REQ → US, DEC → US | +| `:satisfies:` | `:satisfied_by:` | SPEC → REQ | +| `:implements:` | `:implemented_by:` | TASK → SPEC | +| `:verifies:` | `:verified_by:` | TC → US, TC → SPEC, TC → TASK | +| `:affects:` | `:affected_by:` | RISK → REQ/SPEC/TASK | +| `:motivates:` | `:motivated_by:` | DEC → SPEC | +| `:mitigates:` | `:mitigated_by:` | SPEC/TASK/DEC → RISK | + +## Layout + +``` +.specify/presets/useblocks-vmodel/ +├── preset.yml # 9 command overrides, replaces: speckit.* +├── commands/ # AI prompts (one per replaced command) +├── templates/ # per-feature RST scaffolds +├── scaffold/ # project-root files copied by bootstrap +└── scripts/ + ├── bash/bootstrap-vmodel.sh + └── powershell/bootstrap-vmodel.ps1 +``` + +## Compatibility + +- spec-kit `>=0.8.0` (preset composition strategies) +- sphinx-needs `>=2.0` +- Python `>=3.10` (sphinx-needs requirement) + +## License + +MIT diff --git a/presets/useblocks-vmodel/commands/speckit.analyze.md b/presets/useblocks-vmodel/commands/speckit.analyze.md new file mode 100644 index 0000000000..b676ad5e72 --- /dev/null +++ b/presets/useblocks-vmodel/commands/speckit.analyze.md @@ -0,0 +1,327 @@ +--- +description: Perform a non-destructive cross-artefact consistency and quality analysis across spec.rst, plan.rst, and tasks.rst after task generation, using needs.json as the structured oracle. +handoffs: + - label: Fix Spec Issues + agent: speckit.specify + prompt: Refine the specification to address analysis findings + send: true + - label: Adjust Plan + agent: speckit.plan + prompt: Update the plan to resolve architecture or coverage gaps found during analysis + send: true +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Output Format + +This project is configured for RST output (see `.specify/config.toml` `format = "rst"`). The artefacts under analysis are: + +- `spec.rst` — user stories (`.. user_story::`), functional requirements (`.. req::`), risks (`.. risk::`), decisions (`.. decision::`), acceptance tests (`.. test::`) +- `plan.rst` — architectural specs (`.. spec::`), decisions (`.. decision::`), system tests (`.. test::`) +- `tasks.rst` — implementation tasks (`.. task::`) + +The seven directive types are: `user_story`, `req`, `spec`, `task`, `test`, `risk`, `decision`. + +Link fields that carry traceability: `:traces_to:`, `:satisfies:`, `:verifies:`, `:implements:`, `:affects:`, `:motivates:`, `:mitigates:`. The inverse link names are: `traces_from`, `satisfied_by`, `verified_by`, `implemented_by`, `affected_by`, `motivated_by`, `mitigated_by`. + +Coverage filters (e.g. "requirements with no satisfying spec") are expressed as `.. needtable::` / `.. needflow::` filters in `coverage.rst` — those rendering directives belong there, not in the artefact files being analysed here. + +## Pre-Execution Checks + +**Check for extension hooks (before analysis)**: +- Check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.before_analyze` key. +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally. +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable. + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation. +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Pre-Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Pre-Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + + Wait for the result of the hook command before proceeding to the Goal. + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently. + +## Goal + +Identify inconsistencies, duplications, ambiguities, and coverage gaps across the three core artefacts (`spec.rst`, `plan.rst`, `tasks.rst`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.rst`. + +## Operating Constraints + +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). + +**Constitution Authority**: The project constitution (`.specify/memory/constitution.rst` if present, or `/memory/constitution.rst`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks — not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`. + +**Structured oracle**: The primary source of truth for cross-artefact analysis is `needs.json`, built by `sphinx-build -b needs`. Do NOT grep over `.rst` source files to find requirements or links. The JSON already has all resolved link targets and field values. + +## Execution Steps + +### 1. Initialize Analysis Context + +Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: + +- SPEC = FEATURE_DIR/spec.rst +- PLAN = FEATURE_DIR/plan.rst +- TASKS = FEATURE_DIR/tasks.rst +- NEEDS_JSON = FEATURE_DIR/_build/needs/needs.json (or project-root equivalent) + +Abort with an error message if any required artefact is missing (instruct the user to run the missing prerequisite command). +For single quotes in args like "I'm Groot", use escape syntax: e.g. `'I'\''m Groot'` (or double-quote if possible). + +### 2. Load the Structured Oracle + +Build (or verify) `needs.json`: + +```bash +sphinx-build -b needs -W . _build/needs +``` + +from the project root. If the build fails with errors, report them and abort — a broken sphinx build means the oracle is unreliable. + +Load `_build/needs/needs.json`. The top-level structure is: + +``` +{ + "versions": { + "current": { + "needs": { "": { "type": ..., "links": [...], "links_back": [...], ... }, ... }, + "needs_amount": N + } + } +} +``` + +Iterate the `needs` dict. For each need, extract: +- `id`, `type`, `title`, `description`, `status` +- outgoing link arrays: `links` (traces_to), `satisfies`, `verifies`, `implements`, `affects`, `motivates`, `mitigates` +- incoming link arrays: `links_back` (traces_from), `satisfied_by`, `verified_by`, `implemented_by`, `affected_by`, `motivated_by`, `mitigated_by` +- `docname` (which .rst file the need lives in) + +**Do NOT grep `.rst` files** for requirement text or link resolution. `needs.json` is the oracle. + +### 3. Coverage Gap Detection via Oracle + +The canonical coverage queries — equivalent to what `coverage.rst` renders via its filter expressions — are: + +**a. Unsatisfied requirements** (REQ with no satisfying SPEC): + +```python +gaps = [n for n in needs.values() + if n["type"] == "req" and not n.get("satisfied_by")] +``` + +**b. Unverified user stories** (US with no test verifying them): + +```python +gaps = [n for n in needs.values() + if n["type"] == "user_story" and not n.get("verified_by")] +``` + +**c. Unimplemented specs** (SPEC with no implementing TASK): + +```python +gaps = [n for n in needs.values() + if n["type"] == "spec" and not n.get("implemented_by")] +``` + +**d. Orphaned tasks** (TASK that implements nothing): + +```python +orphans = [n for n in needs.values() + if n["type"] == "task" and not n.get("implements")] +``` + +**e. Unmitigated risks** (RISK with no mitigating TASK or SPEC): + +```python +gaps = [n for n in needs.values() + if n["type"] == "risk" and not n.get("mitigated_by")] +``` + +**f. Dangling link targets**: links pointing to IDs that do not appear as keys in the `needs` dict. + +Alternatively, if a pre-rendered `coverage.html` is available at `_build/html/coverage.html`, you may read its rendered filter tables instead of applying Python-equivalent filters — both paths are acceptable. + +### 4. Build Semantic Models + +Create internal representations (do not include raw artefact content in output): + +- **Requirements inventory**: All `req` needs with IDs, title, `satisfied_by`, `verified_by` fields. +- **User story inventory**: All `user_story` needs with `verified_by` and `traces_from` (linked reqs). +- **Spec inventory**: All `spec` needs with `satisfies` (upstream REQ) and `implemented_by` (downstream TASKs). +- **Task coverage mapping**: All `task` needs with `implements` list. +- **Constitution rule set** (if constitution file present): extract MUST/SHOULD normative statements. + +### 5. Detection Passes (Token-Efficient Analysis) + +Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in an overflow summary. + +#### A. Duplication Detection + +- Identify near-duplicate requirement or spec titles across `spec.rst` and `plan.rst`. +- Mark the lower-quality phrasing for consolidation. + +#### B. Ambiguity Detection + +- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria — look at `description` fields in needs.json. +- Flag unresolved placeholders (TODO, TKTK, ???, ``) in need bodies. + +#### C. Underspecification + +- REQ needs whose description body contains a verb but no measurable outcome. +- User stories missing any acceptance criterion in the body text. +- TASK needs referencing file paths or components not traceable to any SPEC or REQ in the oracle. + +#### D. Constitution Alignment + +- Any requirement or plan element conflicting with a MUST principle from the constitution. +- Missing mandated sections or quality gates from the constitution. + +#### E. Coverage Gaps + +Run the Python-equivalent queries from Step 3. Report: +- REQs with no `satisfied_by` +- User stories with no `verified_by` +- SPECs with no `implemented_by` +- TASKs with no `implements` +- RISKs with no `mitigated_by` +- Dangling link targets + +#### F. Inconsistency + +- Terminology drift: the same concept named differently across `spec.rst`, `plan.rst`, and `tasks.rst` (compare need titles and description text). +- Data entities referenced in plan needs but absent in spec needs (or vice versa). +- Task ordering contradictions: TASK A `implements` SPEC B which `satisfies` REQ C, but TASK A has no dependency on a task implementing a prerequisite SPEC. +- Conflicting requirements (e.g., one REQ mandates technology X while another mandates technology Y). + +### 6. Severity Assignment + +Use this heuristic to prioritise findings: + +- **CRITICAL**: Violates a constitution MUST; REQ with zero coverage that blocks baseline functionality; broken sphinx build; dangling link target. +- **HIGH**: Duplicate or conflicting requirement; ambiguous security/performance attribute; untestable acceptance criterion; SPEC with no implementing task. +- **MEDIUM**: Terminology drift; missing non-functional task coverage; underspecified edge case; unmitigated risk. +- **LOW**: Style or wording improvements; minor redundancy not affecting execution order. + +### 7. Produce Compact Analysis Report + +Output a Markdown report (no file writes) with the following structure: + +``` +## Specification Analysis Report + +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| A1 | Duplication | HIGH | spec.rst REQ_AUTH_001, REQ_AUTH_002 | Two near-identical requirements | Merge; keep clearer wording | +``` + +(One row per finding. Stable IDs prefixed by category initial: A=Duplication, B=Ambiguity, C=Underspec, D=Constitution, E=Coverage, F=Inconsistency.) + +**Coverage Summary Table:** + +| Need ID | Type | Has Downstream Link? | Downstream IDs | Notes | +|---------|------|----------------------|----------------|-------| + +**Constitution Alignment Issues:** (if any) + +**Orphaned Tasks:** (TASKs with no `implements` link) + +**Metrics:** + +- Total needs in oracle (by type breakdown) +- REQ coverage % (REQs with >= 1 `satisfied_by`) +- US verification % (user stories with >= 1 `verified_by`) +- SPEC implementation % (SPECs with >= 1 `implemented_by`) +- Ambiguity count +- Duplication count +- Critical issues count + +### 8. Provide Next Actions + +At end of report, output a concise Next Actions block: + +- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`. +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions. +- Provide explicit command suggestions: e.g., "Run `/speckit.specify` to add missing acceptance tests", "Run `/speckit.plan` to add SPEC covering REQ_FEATURE_003", "Edit `tasks.rst` directly to add `implements` links for orphaned tasks". + +### 9. Offer Remediation + +Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) + +### 10. Check for Extension Hooks + +After reporting, check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.after_analyze` key. +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally. +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable. + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation. +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently. + +## Operating Principles + +### Context Efficiency + +- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation. +- **Progressive disclosure**: Load the oracle incrementally; do not dump the full `needs.json` content into the analysis output. +- **Token-efficient output**: Limit findings table to 50 rows; summarise overflow. +- **Deterministic results**: Re-running without changes should produce consistent IDs and counts. + +### Analysis Guidelines + +- **NEVER modify files** (this is read-only analysis). +- **NEVER hallucinate missing sections** (if absent, report them accurately). +- **Prioritise constitution violations** (these are always CRITICAL). +- **Use examples over exhaustive rules** (cite specific need IDs, not generic patterns). +- **Report zero issues gracefully** (emit success report with coverage statistics). +- **Use the oracle, not the source**: load `needs.json` and apply link-field queries; do not regex-grep over `.rst` prose. + +## Context + +{ARGS} diff --git a/presets/useblocks-vmodel/commands/speckit.checklist.md b/presets/useblocks-vmodel/commands/speckit.checklist.md new file mode 100644 index 0000000000..3124e492bf --- /dev/null +++ b/presets/useblocks-vmodel/commands/speckit.checklist.md @@ -0,0 +1,428 @@ +--- +description: Generate a custom checklist for the current feature based on user requirements. +scripts: + sh: scripts/bash/check-prerequisites.sh --json + ps: scripts/powershell/check-prerequisites.ps1 -Json +--- + +## Output Format + +This command produces **plain RST** — it does NOT emit sphinx-needs directives. + +Checklists are process artefacts. Checklist items are RST list items using the +checkbox syntax `* [ ]` (unchecked) and `* [x]` (checked). The generated file +follows `.specify/presets/useblocks-vmodel/templates/checklist-template.rst`: a title, a `:Purpose:` / `:Created:` +/ `:Feature:` field list, RST section headings for categories, and `* [ ] CHKnnn` +items underneath each heading. + +**Do NOT emit** `.. req::`, `.. spec::`, `.. test::`, `.. task::`, +`.. user_story::`, `.. risk::`, `.. decision::`, or any other sphinx-needs +directive inside a checklist file. Rendering directives such as `.. needtable::`, +`.. needflow::`, `.. needlist::`, etc. are equally forbidden here. + +## Checklist Purpose: "Unit Tests for Requirements Writing" + +**CRITICAL CONCEPT**: Checklists are **unit tests for requirements writing** — +they validate the quality, clarity, and completeness of requirements in a given +domain. + +**NOT for verification/testing**: + +- NOT "Verify the button clicks correctly" +- NOT "Test error handling works" +- NOT "Confirm the API returns 200" +- NOT checking if code or implementation matches the spec + +**FOR requirements quality validation**: + +- "Are visual hierarchy requirements defined for all card types?" (completeness) +- "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) +- "Are hover state requirements consistent across all interactive elements?" (consistency) +- "Are accessibility requirements defined for keyboard navigation?" (coverage) +- "Does the spec define what happens when logo image fails to load?" (edge cases) + +**Metaphor**: If your spec is code written in English, the checklist is its unit +test suite. You are testing whether the requirements are well-written, complete, +unambiguous, and ready for implementation — not whether the implementation works. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Pre-Execution Checks + +**Check for extension hooks (before checklist generation)**: + +- Check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.before_checklist` key. +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally. +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable. + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation. +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Pre-Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Pre-Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + + Wait for the result of the hook command before proceeding to the Execution Steps. + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently. + +## Execution Steps + +1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list. + - All file paths must be absolute. + - 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. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions + (no pre-baked catalog). They MUST: + - Be generated from the user's phrasing + extracted signals from spec/plan/tasks. + - Only ask about information that materially changes checklist content. + - Be skipped individually if already unambiguous in `$ARGUMENTS`. + - Prefer precision over breadth. + + Generation algorithm: + 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk + indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", + "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). + 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. + 3. Identify probable audience and timing (author, reviewer, QA, release) if not explicit. + 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion + boundaries, measurable acceptance criteria. + 5. Formulate questions chosen from these archetypes: + - Scope refinement (e.g., "Should this include integration touchpoints with X and Y + or stay limited to local module correctness?") + - Risk prioritization (e.g., "Which of these potential risk areas should receive + mandatory gating checks?") + - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal + release gate?") + - Audience framing (e.g., "Will this be used by the author only or peers during PR + review?") + - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items + this round?") + - Scenario class gap (e.g., "No recovery flows detected — are rollback / partial + failure paths in scope?") + + Question formatting rules: + - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters. + - Limit to A-E options maximum; omit table if a free-form answer is clearer. + - Never ask the user to restate what they already said. + - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: + "Confirm whether X belongs in scope." + + Defaults when interaction is impossible: + - Depth: Standard + - Audience: Reviewer (PR) if code-related; Author otherwise + - Focus: Top 2 relevance clusters + + Output the questions (label Q1/Q2/Q3). After answers: if two or more scenario classes + (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask + up to TWO more targeted follow-ups (Q4/Q5) with a one-line justification each (e.g., + "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation + if user explicitly declines more. + +3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: + - Derive checklist theme (e.g., security, review, deploy, ux). + - Consolidate explicit must-have items mentioned by user. + - Map focus selections to category scaffolding. + - Infer any missing context from spec/plan/tasks (do NOT hallucinate). + +4. **Load feature context**: Read from FEATURE_DIR: + - `spec.rst` — Feature requirements and scope. + - `plan.rst` (if exists) — Technical details, dependencies. + - `tasks.rst` (if exists) — Implementation tasks. + + **Context Loading Strategy**: + - Load only necessary portions relevant to active focus areas (avoid full-file dumping). + - Prefer summarizing long sections into concise scenario/requirement bullets. + - Use progressive disclosure: add follow-on retrieval only if gaps detected. + - If source docs are large, generate interim summary items instead of embedding raw text. + +5. **Generate checklist** — create "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if it does not exist. + - Generate a unique checklist filename: + - Use a short, descriptive name based on the domain (e.g., `ux.rst`, `api.rst`, + `security.rst`). + - Format: `[domain].rst` + - File handling behavior: + - If file does NOT exist: create new file and number items starting from CHK001. + - If file exists: append new items to the existing file, continuing from the last + CHK ID (e.g., if last item is CHK015, start new items at CHK016). + - Never delete or replace existing checklist content — always preserve and append. + + **Core principle — test the requirements, not the implementation**: + + Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: + - **Completeness**: Are all necessary requirements present? + - **Clarity**: Are requirements unambiguous and specific? + - **Consistency**: Do requirements align with each other? + - **Measurability**: Can requirements be objectively verified? + - **Coverage**: Are all scenarios/edge cases addressed? + + **Category structure** — group items by requirement quality dimensions: + - Requirement Completeness (Are all necessary requirements documented?) + - Requirement Clarity (Are requirements specific and unambiguous?) + - Requirement Consistency (Do requirements align without conflicts?) + - Acceptance Criteria Quality (Are success criteria measurable?) + - Scenario Coverage (Are all flows/cases addressed?) + - Edge Case Coverage (Are boundary conditions defined?) + - Non-Functional Requirements (Performance, Security, Accessibility, etc. — are they specified?) + - Dependencies and Assumptions (Are they documented and validated?) + - Ambiguities and Conflicts (What needs clarification?) + + **How to write checklist items — "Unit Tests for English"**: + + WRONG (testing implementation): + + - "Verify landing page displays 3 episode cards" + - "Test hover states work on desktop" + - "Confirm logo click navigates home" + + CORRECT (testing requirements quality): + + - "Are the exact number and layout of featured episodes specified? [Completeness]" + - "Is 'prominent display' quantified with specific sizing/positioning? [Clarity]" + - "Are hover state requirements consistent across all interactive elements? [Consistency]" + - "Are keyboard navigation requirements defined for all interactive UI? [Coverage]" + - "Is the fallback behavior specified when logo image fails to load? [Edge Cases]" + - "Are loading states defined for asynchronous episode data? [Completeness]" + - "Does the spec define visual hierarchy for competing UI elements? [Clarity]" + + **Item structure**: + + Each item should follow this pattern: + - Question format asking about requirement quality. + - Focus on what is WRITTEN (or not written) in the spec/plan. + - Include quality dimension in brackets `[Completeness/Clarity/Consistency/etc.]`. + - Reference spec section `[Spec §X.Y]` when checking existing requirements. + - Use `[Gap]` marker when checking for missing requirements. + + **Examples by quality dimension**: + + Completeness: + + - "Are error handling requirements defined for all API failure modes? [Gap]" + - "Are accessibility requirements specified for all interactive elements? [Completeness]" + - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" + + Clarity: + + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" + - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" + - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" + + Consistency: + + - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" + - "Are card component requirements consistent between landing and detail pages? [Consistency]" + + Coverage: + + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" + - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" + - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" + + Measurability: + + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" + - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" + + **Scenario classification and coverage** (requirements quality focus): + + - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, and + Non-Functional scenarios. + - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" + - If a scenario class is missing: "Are [scenario type] requirements intentionally excluded or + missing? [Gap]" + - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined + for migration failures? [Gap]" + + **Traceability requirements**: + + - MINIMUM: at least 80% of items MUST include at least one traceability reference. + - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, + `[Ambiguity]`, `[Conflict]`, `[Assumption]`. + - If no ID system exists: "Is a requirement and acceptance criteria ID scheme established? + [Traceability]" + + **Surface and resolve issues** (requirements quality problems): + + Ask questions about the requirements themselves: + - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]" + - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]" + - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" + - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" + - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" + + **Content consolidation**: + + - Soft cap: If raw candidate items exceed 40, prioritize by risk/impact. + - Merge near-duplicates checking the same requirement aspect. + - If more than 5 low-impact edge cases arise, create one item: "Are edge cases X, Y, Z + addressed in requirements? [Coverage]" + + **Absolutely prohibited** — these make it an implementation test, not a requirements test: + + - Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior. + - References to code execution, user actions, system behavior. + - "Displays correctly", "works properly", "functions as expected". + - "Click", "navigate", "render", "load", "execute". + - Test cases, test plans, QA procedures. + - Implementation details (frameworks, APIs, algorithms). + + **Required patterns** — these test requirements quality: + + - "Are [requirement type] defined/specified/documented for [scenario]?" + - "Is [vague term] quantified/clarified with specific criteria?" + - "Are requirements consistent between [section A] and [section B]?" + - "Can [requirement] be objectively measured/verified?" + - "Are [edge cases/scenarios] addressed in requirements?" + - "Does the spec define [missing aspect]?" + +6. **Structure reference**: Generate the checklist following the canonical template in + `.specify/presets/useblocks-vmodel/templates/checklist-template.rst` for title, meta field list, category headings, and ID + formatting. If the template is unavailable, use: RST title (underlined with `=`), a field + list with `:Purpose:`, `:Created:`, `:Feature:` fields, `---`-underlined category sections + containing `* [ ] CHKnnn ` lines with globally incrementing IDs starting + at CHK001. + +7. **Report**: Output the full path to the checklist file, item count, and summarize whether + the run created a new file or appended to an existing one. Summarize: + - Focus areas selected. + - Depth level. + - Actor/timing. + - Any explicit user-specified must-have items incorporated. + +**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist +filename and either creates a new file or appends to an existing one. This allows: + +- Multiple checklists of different types (e.g., `ux.rst`, `test.rst`, `security.rst`). +- Simple, memorable filenames that indicate checklist purpose. +- Easy identification and navigation in the `checklists/` folder. + +To avoid clutter, use descriptive types and clean up obsolete checklists when done. + +## Example Checklist Types and Sample Items + +**UX Requirements Quality**: `ux.rst` + +Sample items (testing the requirements, NOT the implementation): + +- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" +- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" +- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" +- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" +- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" +- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]" + +**API Requirements Quality**: `api.rst` + +Sample items: + +- "Are error response formats specified for all failure scenarios? [Completeness]" +- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" +- "Are authentication requirements consistent across all endpoints? [Consistency]" +- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" +- "Is versioning strategy documented in requirements? [Gap]" + +**Performance Requirements Quality**: `performance.rst` + +Sample items: + +- "Are performance requirements quantified with specific metrics? [Clarity]" +- "Are performance targets defined for all critical user journeys? [Coverage]" +- "Are performance requirements under different load conditions specified? [Completeness]" +- "Can performance requirements be objectively measured? [Measurability]" +- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" + +**Security Requirements Quality**: `security.rst` + +Sample items: + +- "Are authentication requirements specified for all protected resources? [Coverage]" +- "Are data protection requirements defined for sensitive information? [Completeness]" +- "Is the threat model documented and requirements aligned to it? [Traceability]" +- "Are security requirements consistent with compliance obligations? [Consistency]" +- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" + +## Anti-Examples: What NOT To Do + +**WRONG — these test implementation, not requirements:** + +```rst +* [ ] CHK001 Verify landing page displays 3 episode cards [Spec §FR-001] +* [ ] CHK002 Test hover states work correctly on desktop [Spec §FR-003] +* [ ] CHK003 Confirm logo click navigates to home page [Spec §FR-010] +* [ ] CHK004 Check that related episodes section shows 3-5 items [Spec §FR-005] +``` + +**CORRECT — these test requirements quality:** + +```rst +* [ ] CHK001 Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001] +* [ ] CHK002 Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003] +* [ ] CHK003 Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010] +* [ ] CHK004 Is the selection criteria for related episodes documented? [Gap, Spec §FR-005] +* [ ] CHK005 Are loading state requirements defined for asynchronous episode data? [Gap] +* [ ] CHK006 Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001] +``` + +**Key differences:** + +- Wrong: tests if the system works correctly. Correct: tests if the requirements are written correctly. +- Wrong: verification of behavior. Correct: validation of requirement quality. +- Wrong: "Does it do X?" Correct: "Is X clearly specified?" + +## Post-Execution Checks + +**Check for extension hooks (after checklist generation)**: + +Check if `.specify/extensions.yml` exists in the project root. + +- If it exists, read it and look for entries under the `hooks.after_checklist` key. +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally. +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable. + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation. +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently. diff --git a/presets/useblocks-vmodel/commands/speckit.clarify.md b/presets/useblocks-vmodel/commands/speckit.clarify.md new file mode 100644 index 0000000000..0d77b52058 --- /dev/null +++ b/presets/useblocks-vmodel/commands/speckit.clarify.md @@ -0,0 +1,303 @@ +--- +description: Identify underspecified areas in the current feature spec by asking up to 3 highly targeted clarification questions and encoding answers back into the sphinx-needs directives in spec.rst. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... +scripts: + sh: scripts/bash/check-prerequisites.sh --json --paths-only + ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Output Format + +This project is configured for RST output (see `.specify/config.toml` `format = "rst"`). All spec artefacts live in `spec.rst`. The V-model directive types in use are: + +| Directive | ID prefix | Purpose | +|------------------|--------------|--------------------------------------| +| `.. user_story::` | `US_` | User-facing goal | +| `.. req::` | `REQ_` | Normative functional requirement | +| `.. spec::` | `SPEC_` | Technical / design specification | +| `.. task::` | `TASK_` | Implementation work item | +| `.. test::` | `TC_` | Acceptance / verification test | +| `.. risk::` | `RISK_` | Identified risk | +| `.. decision::` | `DEC_` | Architecture or design decision | + +Link types in use: `traces_to`, `satisfies`, `verifies`, `implements`, `affects`, `motivates`, `mitigates`. + +`[NEEDS CLARIFICATION]` markers live **inside directive bodies**, indented under their parent directive. When replacing a marker the indentation of the directive body MUST be preserved. Example: + +```rst +.. req:: Authenticate users + :id: REQ_AUTH_001 + :status: open + + The system MUST [NEEDS CLARIFICATION: which auth method — OAuth2, SAML, or local password?] +``` + +After replacement: + +```rst +.. req:: Authenticate users + :id: REQ_AUTH_001 + :status: open + + The system MUST support OAuth2 for authentication. +``` + +## Pre-Execution Checks + +**Check for extension hooks (before clarification)**: +- Check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.before_clarify` key. +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally. +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable. + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation. +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Pre-Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Pre-Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + + Wait for the result of the hook command before proceeding to the Outline. + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently. + +## Outline + +Goal: Detect and reduce ambiguity or missing decision points in the active feature specification (`spec.rst`) and record the clarifications directly in that file, preserving all sphinx-needs directive syntax. + +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. + +Execution steps: + +1. Run `{SCRIPT}` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: + - `FEATURE_DIR` + - `FEATURE_SPEC` (path to `spec.rst`) + - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) + - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment. + - 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 `spec.rst`. Perform a structured ambiguity and coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output the raw map unless no questions will be asked). + + Functional Scope & Behavior: + - Core user goals and success criteria + - Explicit out-of-scope declarations + - User roles / personas differentiation + + Domain & Data Model: + - Entities, attributes, relationships + - Identity and uniqueness rules + - Lifecycle / state transitions + - Data volume / scale assumptions + + Interaction & UX Flow: + - Critical user journeys / sequences + - Error / empty / loading states + - Accessibility or localization notes + + Non-Functional Quality Attributes: + - Performance (latency, throughput targets) + - Scalability (horizontal/vertical, limits) + - Reliability and availability (uptime, recovery expectations) + - Observability (logging, metrics, tracing signals) + - Security and privacy (authN/Z, data protection, threat assumptions) + - Compliance / regulatory constraints (if any) + + Integration & External Dependencies: + - External services / APIs and failure modes + - Data import / export formats + - Protocol / versioning assumptions + + Edge Cases & Failure Handling: + - Negative scenarios + - Rate limiting / throttling + - Conflict resolution (e.g., concurrent edits) + + Constraints & Tradeoffs: + - Technical constraints (language, storage, hosting) + - Explicit tradeoffs or rejected alternatives + + Terminology & Consistency: + - Canonical glossary terms + - Avoided synonyms / deprecated terms + + Completion Signals: + - Acceptance criteria testability + - Measurable Definition of Done indicators + + Misc / Placeholders: + - `[NEEDS CLARIFICATION]` markers already present in directive bodies + - Ambiguous adjectives ("robust", "intuitive") lacking quantification + + For each category with Partial or Missing status, add a candidate question opportunity unless: + - Clarification would not materially change implementation or validation strategy. + - Information is better deferred to planning phase (note internally). + +3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 3). Do NOT output them all at once. Apply these constraints: + - Maximum of 3 total questions across the whole session. + - Each question must be answerable with EITHER: + - A short multiple-choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short-phrase answer (explicitly constrain: "Answer in <=5 words"). + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. + - Ensure category coverage balance: attempt to cover the highest-impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. + - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). + - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. + - If more than 3 categories remain unresolved, select the top 3 by (Impact × Uncertainty) heuristic. + +4. Sequential questioning loop (interactive): + - Present EXACTLY ONE question at a time. + - For multiple-choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in `spec.rst` + - Present your **recommended option prominently** at the top with clear reasoning (1–2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] — ` + - Then render all options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |