From feec04e6d7a067914bf699b8dbcb37104345a539 Mon Sep 17 00:00:00 2001 From: bigsmartben <30429295+bigsmartben@users.noreply.github.com> Date: Mon, 6 Jul 2026 14:18:50 +0800 Subject: [PATCH 1/2] Integrate discovery interface contract extension --- extensions/catalog.community.json | 21 +-- extensions/catalog.json | 18 ++- extensions/discovery/.gitignore | 20 --- extensions/discovery/CATALOG-SUBMISSION.md | 33 ++-- extensions/discovery/CHANGELOG.md | 16 +- extensions/discovery/README.md | 144 ++++------------- .../discovery/commands/codebase-api-imp.md | 68 -------- extensions/discovery/commands/codebase.md | 85 ---------- extensions/discovery/commands/decision.md | 95 ----------- extensions/discovery/commands/discovery.md | 102 ++++++++++++ extensions/discovery/commands/feasibility.md | 68 -------- extensions/discovery/commands/poc.md | 106 ------------ extensions/discovery/commands/techselect.md | 65 -------- extensions/discovery/docs/usage.md | 152 +++++------------- extensions/discovery/extension.yml | 41 ++--- .../templates/api-integration-discovery.md | 37 ----- .../discovery/templates/codebase-api-imp.md | 82 ---------- .../templates/compatibility-discovery.md | 37 ----- .../templates/data-migration-discovery.md | 37 ----- extensions/discovery/templates/feasibility.md | 25 --- .../discovery/templates/interface-contract.md | 114 +++++++++++++ .../legacy-codebase-risk-assessment.md | 87 ---------- .../templates/performance-discovery.md | 37 ----- extensions/discovery/templates/poc-plan.md | 21 --- extensions/discovery/templates/poc-result.md | 15 -- .../templates/tech-selection-matrix.md | 25 --- .../discovery/templates/ux-discovery.md | 37 ----- 27 files changed, 352 insertions(+), 1236 deletions(-) delete mode 100644 extensions/discovery/commands/codebase-api-imp.md delete mode 100644 extensions/discovery/commands/codebase.md delete mode 100644 extensions/discovery/commands/decision.md create mode 100644 extensions/discovery/commands/discovery.md delete mode 100644 extensions/discovery/commands/feasibility.md delete mode 100644 extensions/discovery/commands/poc.md delete mode 100644 extensions/discovery/commands/techselect.md delete mode 100644 extensions/discovery/templates/api-integration-discovery.md delete mode 100644 extensions/discovery/templates/codebase-api-imp.md delete mode 100644 extensions/discovery/templates/compatibility-discovery.md delete mode 100644 extensions/discovery/templates/data-migration-discovery.md delete mode 100644 extensions/discovery/templates/feasibility.md create mode 100644 extensions/discovery/templates/interface-contract.md delete mode 100644 extensions/discovery/templates/legacy-codebase-risk-assessment.md delete mode 100644 extensions/discovery/templates/performance-discovery.md delete mode 100644 extensions/discovery/templates/poc-plan.md delete mode 100644 extensions/discovery/templates/poc-result.md delete mode 100644 extensions/discovery/templates/tech-selection-matrix.md delete mode 100644 extensions/discovery/templates/ux-discovery.md diff --git a/extensions/catalog.community.json b/extensions/catalog.community.json index 77ff767d94..25e6fd4ee5 100644 --- a/extensions/catalog.community.json +++ b/extensions/catalog.community.json @@ -1041,10 +1041,10 @@ "discovery": { "name": "Spec Kit Discovery Extension", "id": "discovery", - "description": "Run technical discovery commands for feasibility, technology selection, scenario-specific technical decisions, legacy codebase assessment, implementation understanding, and proof-of-concept validation.", + "description": "Validate pre-development interface feasibility by finding the key interface design from uc.md, spec.md, or arch.md and producing one verified interface contract artifact.", "author": "bigsmartben", - "version": "0.2.0", - "download_url": "https://github.com/bigsmartben/spec-kit-discovery/archive/refs/tags/v0.2.0.zip", + "version": "0.3.0", + "download_url": "https://github.com/bigsmartben/spec-kit-discovery/archive/38f660c815f3ef95d80f143dac6c6411b12a9f04.zip", "repository": "https://github.com/bigsmartben/spec-kit-discovery", "homepage": "https://github.com/bigsmartben/spec-kit-discovery", "documentation": "https://github.com/bigsmartben/spec-kit-discovery/blob/main/docs/usage.md", @@ -1056,21 +1056,24 @@ "speckit_version": ">=0.1.0" }, "provides": { - "commands": 6, + "commands": 1, "hooks": 0 }, "tags": [ "discovery", - "workflow", - "validation", - "feasibility", - "decision" + "interface-contract", + "api", + "event", + "webhook", + "technical-validation", + "pre-development", + "validation" ], "verified": false, "downloads": 0, "stars": 0, "created_at": "2026-06-23T00:00:00Z", - "updated_at": "2026-06-23T00:00:00Z" + "updated_at": "2026-07-06T00:00:00Z" }, "docguard": { "name": "DocGuard — CDD Enforcement", diff --git a/extensions/catalog.json b/extensions/catalog.json index 7a6ec3df24..494dd64f35 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -120,8 +120,8 @@ "discovery": { "name": "Spec Kit Discovery Extension", "id": "discovery", - "version": "0.2.0", - "description": "Run technical discovery commands for feasibility, technology selection, scenario-specific technical decisions, legacy codebase assessment, implementation understanding, and proof-of-concept validation", + "version": "0.3.0", + "description": "Validate pre-development interface feasibility by finding the key interface design from uc.md, spec.md, or arch.md and producing one verified interface contract artifact", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-discovery", "license": "MIT", @@ -130,15 +130,17 @@ "speckit_version": ">=0.1.0" }, "provides": { - "commands": 6 + "commands": 1 }, "tags": [ "discovery", - "feasibility", - "selection", - "codebase", - "poc", - "decision" + "interface-contract", + "api", + "event", + "webhook", + "technical-validation", + "pre-development", + "validation" ] }, "repository-governance": { diff --git a/extensions/discovery/.gitignore b/extensions/discovery/.gitignore index 2380a9307f..84ffb1d8ee 100644 --- a/extensions/discovery/.gitignore +++ b/extensions/discovery/.gitignore @@ -1,12 +1,5 @@ .DS_Store Thumbs.db -__pycache__/ -*.py[cod] -.pytest_cache/ -.mypy_cache/ -.ruff_cache/ -.coverage -htmlcov/ # Local editor state .idea/ @@ -14,23 +7,10 @@ htmlcov/ *.swp *.swo -# Python environments and builds -.venv/ -venv/ -dist/ -build/ -*.egg-info/ -*.zip -.env -.env.* -!.env.example - # Spec Kit local-only config generated by installed extensions .specify/extensions/**/*-config.local.yml # Logs and temporary files *.log -.tmp/ tmp/ temp/ -.worktrees/ diff --git a/extensions/discovery/CATALOG-SUBMISSION.md b/extensions/discovery/CATALOG-SUBMISSION.md index ab166d2828..9841c70261 100644 --- a/extensions/discovery/CATALOG-SUBMISSION.md +++ b/extensions/discovery/CATALOG-SUBMISSION.md @@ -2,31 +2,32 @@ Extension ID: discovery Name: Spec Kit Discovery Extension -Version: 0.2.0 -Description: Run technical discovery commands for feasibility, technology selection, scenario-specific technical decisions, legacy codebase assessment, implementation understanding, and proof-of-concept validation. +Version: 0.3.0 +Description: Validate pre-development interface feasibility by finding the key interface design from uc.md, spec.md, or arch.md, validating that design with non-persistent evidence, and producing one verified interface contract artifact. Author: bigsmartben Repository URL: https://github.com/bigsmartben/spec-kit-discovery -Download URL: https://github.com/bigsmartben/spec-kit-discovery/archive/refs/tags/v0.2.0.zip +Source commit SHA: 38f660c815f3ef95d80f143dac6c6411b12a9f04 +Download URL: https://github.com/bigsmartben/spec-kit-discovery/archive/38f660c815f3ef95d80f143dac6c6411b12a9f04.zip Documentation URL: https://github.com/bigsmartben/spec-kit-discovery#readme License: MIT Required Spec Kit version: >=0.1.0 -Commands count: 6 +Commands count: 1 Hooks count: 0 -Tags: discovery, feasibility, selection, codebase, poc, decision +Tags: discovery, interface-contract, api, event, webhook, technical-validation, pre-development, validation ## Key Features -- Adds `speckit.discovery.feasibility`, `speckit.discovery.techselect`, and `speckit.discovery.codebase`. -- Adds `speckit.discovery.codebase-api-imp` for source-backed implementation overviews. -- Adds `speckit.discovery.poc` for bounded proof-of-concept planning and validation. -- Adds `speckit.discovery.decision` with `type: api|performance|migration|ux|compatibility` routing. -- Keeps outputs focused on evidence, assumptions, unknowns, planning decisions, and validation scope before formal implementation planning. +- Adds `/speckit.discovery` as the single public discovery command. +- Extracts candidate interface designs from `uc.md`, `spec.md`, or `arch.md`. +- Selects the key source-backed interface design to validate before formal development. +- Produces one persistent artifact: `interface-contract.md`. +- Keeps validation evidence non-persistent and embedded in the contract. ## Testing Performed -- Validated the bundled manifest with `ExtensionManifest`. -- Ran `uv run pytest tests/integrations/test_cli.py -k "community_extensions_and_workflow_preset_auto_installed or no_git_keeps_community_defaults"`. -- Ran `uv run pytest tests/test_arch_templates.py tests/test_presets.py -k "community_smoke_checks_wheel_assets_and_extension_dev_reinstall or init_next_steps_do_not_list_arch_as_core_workflow"`. -- Built the CLI wheel with `uv build --wheel` and verified `specify_cli/core_pack/extensions/discovery/extension.yml` and representative command/template files were included. -- Smoke-tested `specify init`, `specify extension remove discovery --force`, and `specify extension add discovery` in a temporary project. -- Verified release `v0.2.0` installs with `Commands: 6`. +- Confirmed source `commands/` contains only `discovery.md`. +- Confirmed source `templates/` contains only `interface-contract.md`. +- Confirmed source `extension.yml` registers `speckit.discovery` with `commands/discovery.md`. +- Checked old command/template naming residuals with `rg`; no matches. +- Ran `git diff --check`; passed. +- Checked Markdown/YAML trailing whitespace with `rg`; no matches. diff --git a/extensions/discovery/CHANGELOG.md b/extensions/discovery/CHANGELOG.md index 41a0e90bf3..de8e274ead 100644 --- a/extensions/discovery/CHANGELOG.md +++ b/extensions/discovery/CHANGELOG.md @@ -1,12 +1,22 @@ # Changelog +## [0.3.0] - 2026-07-06 + +### Changed + +- Refocused the extension on pre-development interface feasibility validation. +- Replaced the broad six-command discovery surface with `/speckit.discovery`. +- Added `templates/interface-contract.md` as the core verified interface contract artifact. +- Updated documentation and manifest metadata to describe key interface design discovery from `uc.md`, `spec.md`, or `arch.md`, selected-design validation, and non-persistent validation evidence. +- Tightened the workflow so `interface-contract.md` is the only persistent output artifact. + ## [0.2.0] - 2026-06-23 ### Changed -- Consolidated API integration, performance, data migration, UX workflow, and compatibility discovery into `speckit.discovery.decision` with type-specific routing. -- Updated documentation to describe the six-command public interface. -- Replaced references to the old API integration command with `/speckit.discovery.decision type: api`. +- Introduced an intermediate legacy decision-routing surface for API integration, performance, data migration, UX workflow, and compatibility discovery. +- Updated documentation for the then-current multi-command public interface. +- Replaced earlier API integration references with that legacy decision route. ## [0.1.0] - 2026-06-23 diff --git a/extensions/discovery/README.md b/extensions/discovery/README.md index 599db126b8..b618ae69ea 100644 --- a/extensions/discovery/README.md +++ b/extensions/discovery/README.md @@ -1,24 +1,29 @@ # Spec Kit Discovery Extension -`spec-kit-discovery` provides a `discovery` extension for Spec Kit. It adds scope-bounded commands for the technical discovery phase: +`spec-kit-discovery` provides a focused `discovery` extension for one pre-development job: find the key interface design implied by `uc.md`, `spec.md`, or `arch.md`, validate that design, then produce one verified interface contract artifact. ```text -/speckit.discovery.feasibility [goal or idea] [constraints] [success criteria] -/speckit.discovery.techselect [decision to make] [candidate options] [criteria or constraints] -/speckit.discovery.decision type: api|performance|migration|ux|compatibility [scenario] [constraints or risks] -/speckit.discovery.codebase [target area or fuzzy scope] [planned change or integration] [known concerns] -/speckit.discovery.codebase-api-imp [API route, SDK method, topic, command, or capability] [known concern] [source scope] -/speckit.discovery.poc [user stories] [use cases] [core design idea] +/speckit.discovery [source docs or feature scope] [interface design focus] [constraints] ``` -The extension helps teams complete technical discovery before formal planning. `feasibility`, `techselect`, and `codebase` produce decision documents; `decision` evaluates scenario-specific API, performance, migration, UX, and compatibility risks; `codebase-api-imp` explains existing interface implementations from source facts; `poc` creates a bounded-scope experiment that supports feasibility, selection, scenario decision, or legacy-codebase risk decisions. +Use it before `/speckit.specify`, `/speckit.plan`, or implementation work when the main uncertainty is an API, event, command, SDK method, webhook, batch job, or cross-system service boundary. -Internally, the commands are organized into four capability types: +## Output -- `feasibility`: support a go/no-go continuation decision. -- `techselect`: compare general technology choices. -- `decision`: evaluate scenario-specific API, performance, migration, UX, and compatibility decisions with type-specific risks. -- `codebase`, `codebase-api-imp` (API implementation overview), and `poc`: locate relevant source scope, gather source-backed evidence, record evidence levels and unknowns, explain implemented interface behavior, or run executable validation. +The command creates or updates only one persistent artifact: + +- `interface-contract.md` + +The contract records: + +- source-backed candidate interface designs extracted from `uc.md`, `spec.md`, or `arch.md` +- the selected key interface design and validation route +- request, response, event, error, auth, retry, timeout, observability, versioning, and compatibility contract details +- static or executable validation evidence +- blocker codes and remaining gaps +- `Contract Status`: `validated`, `validated-with-risks`, `blocked`, or `inconclusive` + +Validation evidence must be embedded in `interface-contract.md`. The command does not create separate PoC files, validation directories, logs, fixtures, screenshots, or generated payload artifacts. ## Installation @@ -36,99 +41,25 @@ specify extension add --dev . --force After installation, restart or refresh your AI coding agent if the new command does not appear immediately. -## Commands - -### `speckit.discovery.feasibility` - -Produces an evidence-backed feasibility study. - -Typical output: - -- `feasibility.md` -- decision: `feasible`, `feasible-with-risks`, `not-feasible`, or `inconclusive` - -### `speckit.discovery.techselect` - -Builds a technology selection matrix for candidate tools, libraries, platforms, or architectures. - -Typical output: - -- `tech-selection-matrix.md` -- recommendation, shortlist, or evidence gap - -### `speckit.discovery.decision` - -Evaluates a scenario-specific technical decision before formal planning. Use `type: api`, `type: performance`, `type: migration`, `type: ux`, or `type: compatibility` to select the decision frame and output template. +## Command -Typical output: +### `speckit.discovery` -- `api-integration-discovery.md` -- `performance-discovery.md` -- `data-migration-discovery.md` -- `ux-discovery.md` -- `compatibility-discovery.md` -- type-specific `Planning Decision` +Finds the key interface design from the input material, validates feasibility with source refs, existing commands, existing tests, read-only probes, or temporary snippets, and renders `templates/interface-contract.md`. -### `speckit.discovery.codebase` +Minimum useful input: -Assesses legacy codebase risks, reusable assets, constraints, and integration hazards. When the target area is fuzzy, it first narrows likely source areas before using files, symbols, tests, configuration, and observed behavior as evidence for planning. - -Typical output: - -- `legacy-codebase-risk-assessment.md` -- scoped source areas or inspected paths -- source facts with file references -- evidence level per finding -- unknowns and unresolved questions -- risks rated as `low`, `medium`, `high`, or `unknown` - -### `speckit.discovery.codebase-api-imp` - -Explains how an already implemented API or interface works from repository facts. Use it for an HTTP/RPC route, SDK method, message topic, scheduled job, CLI command, or internal capability when engineers need implementation understanding or defect-localization guidance. - -Typical output: - -- `codebase-api-imp.md` -- interface match and source-backed entrance evidence -- service/system-level and module/component-level Mermaid sequence diagrams when evidence supports them -- repository-fact-backed business implementation flowcharts for key branches, dependencies, exceptions, and return paths -- evidence levels: `Proven`, `Framework inferred`, `Runtime dependent`, or `Unknown` - -### `speckit.discovery.poc` - -Creates a bounded-scope PoC plan and, when static evidence is insufficient and execution preconditions are met, a minimum runnable validation plus evidence report and conclusion. - -Minimum input: - -- User stories -- Use cases -- Core design idea +- Source docs or feature scope: explicit paths, a feature directory, or a feature name. +- Interface design focus: API, event, command, SDK method, internal service boundary, webhook, batch job with an explicit input/output boundary, or cross-system interface. +- Constraints: runtime, protocol, framework, auth, data, performance, compatibility, migration, rollout, or operational constraints. Example: ```text -/speckit.discovery.poc US: Readers can search notes by title and body. UC: Search while typing and open a result. Core design idea: Use SQLite FTS5 with a small local index. +/speckit.discovery Source: specs/payments/spec.md and specs/payments/arch.md. Focus: Stripe webhook ingestion contract. Constraints: idempotent retries, signature verification, no duplicate invoice updates. ``` -The command produces: - -- `poc-plan.md` -- `poc-result.md` -- `discovery//poc/` minimum validation code or scripts when executable evidence is required -- evidence logs or outputs -- result: `passed`, `failed`, or `inconclusive` - -## Scenario-Specific Technical Decisions - -Use `/speckit.discovery.decision` when the unknown is already tied to a common technical decision situation. The command creates a single-decision discovery document with a type-specific `Planning Decision`, and sets `Evaluation Mode` to either `comparison` or `single-approach-readiness`. - -| Decision type | Use for | Typical output | -|---|---|---| -| `api` | Third-party API, SDK, webhook, service, SaaS platform, or partner integration decisions. | `api-integration-discovery.md` | -| `performance` | Latency, throughput, scalability, resource, capacity, or cost decisions. | `performance-discovery.md` | -| `migration` | Data model, storage, schema, backfill, import/export, or migration decisions. | `data-migration-discovery.md` | -| `ux` | Complex interaction, stateful workflow, accessibility, responsive behavior, or frontend/backend handoff decisions. | `ux-discovery.md` | -| `compatibility` | Browser, OS, device, runtime, framework, API version, or deployment compatibility decisions. | `compatibility-discovery.md` | +When source docs are not passed explicitly, the command looks for `uc.md`, `spec.md`, or `arch.md` in the active feature directory or repository. ## Repository Structure @@ -136,24 +67,9 @@ Use `/speckit.discovery.decision` when the unknown is already tied to a common t . ├── extension.yml ├── commands/ -│ ├── codebase-api-imp.md -│ ├── codebase.md -│ ├── decision.md -│ ├── feasibility.md -│ ├── poc.md -│ └── techselect.md +│ └── discovery.md ├── templates/ -│ ├── api-integration-discovery.md -│ ├── codebase-api-imp.md -│ ├── compatibility-discovery.md -│ ├── data-migration-discovery.md -│ ├── feasibility.md -│ ├── legacy-codebase-risk-assessment.md -│ ├── performance-discovery.md -│ ├── poc-plan.md -│ ├── poc-result.md -│ ├── tech-selection-matrix.md -│ └── ux-discovery.md +│ └── interface-contract.md ├── docs/ │ └── usage.md ├── CHANGELOG.md @@ -163,7 +79,7 @@ Use `/speckit.discovery.decision` when the unknown is already tied to a common t ## Development -Validate the extension from a Spec Kit project with: +Validate manifest references before release: ```bash specify extension add --dev /path/to/spec-kit-discovery --force diff --git a/extensions/discovery/commands/codebase-api-imp.md b/extensions/discovery/commands/codebase-api-imp.md deleted file mode 100644 index c94478a864..0000000000 --- a/extensions/discovery/commands/codebase-api-imp.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: speckit.discovery.codebase-api-imp -description: Explain an implemented API or interface from repository facts for implementation understanding and defect localization. -argument-hint: "[API route, SDK method, topic, command, or capability] [known concern or suspected defect] [source scope]" ---- - - -You are a codebase API implementation discovery facilitator for Spec Kit projects. Your job is to explain how an already implemented API or interface works from repository facts, so engineers can understand the business flow, identify important branches, and continue defect localization. - - - -Use this command during the Discovery extension workflow when the user needs a source-backed implementation overview for an existing interface, such as an HTTP/RPC route, SDK method, message topic, scheduled job, CLI command, or internal capability entrypoint. - - - -Raw user input: - -```text -$ARGUMENTS -``` - -The user may provide: -- Interface target: route, API name, SDK method, message topic, command, job, or capability description. -- Known concern: suspected defect, failing scenario, confusing branch, dependency concern, or runtime behavior to localize. -- Source scope: repository, module, directory, service, package, or cross-repository roots when known. - -Infer optional fields only from repository context and conversation, and label inferred values as assumptions. If the interface target is absent or too ambiguous to identify candidate entrances, inspect repository structure and search likely entrances before asking one concise clarifying question. - - - -1. Establish the interface target: - - Normalize the target name, route/address/topic/command/method, functional description, known concern, and source scope. - - Treat the current repository as the default analysis scope. - - If multiple candidate entrances match, list up to five candidates with evidence and choose the strongest source-backed match before writing the final overview. - - If a downstream repository or external system is mentioned but source is unavailable, document it only as an external dependency, runtime-dependent boundary, or unknown. - -2. Gather repository facts: - - Locate entrances such as HTTP/RPC handlers, route declarations, public SDK methods, message consumers, scheduled jobs, CLI commands, or internal capability entrypoints. - - Trace only planning-relevant implementation facts: framework wiring, middleware/interceptors, direct calls, async/event edges, data reads/writes, external clients, retries, transactions, exception handling, state transitions, and return mapping. - - Separate repository-proven facts from framework inference, runtime-dependent behavior, assumptions, and unknowns. - - Use lightweight file and line references for important entrances, branches, dependencies, exception paths, and runtime boundaries. - - Do not claim business behavior, callers, branches, DTO fields, tables, downstream internals, retries, exceptions, or return shapes unless repository evidence supports them. - -3. Build the defect-localization hierarchy: - - Use a service/system-level sequence diagram for externally observable interaction among caller/actor, interface boundary, analyzed system, and contract-visible external systems. - - Use a module/component-level sequence diagram for source-backed boundary-crossing collaboration among handlers, middleware, application/domain components, repositories/gateways/clients, brokers, or external systems. - - Use repository-fact-backed flowcharts only when a module/component message needs concrete branch, exception, data/dependency, async, transaction, fallback, runtime-boundary, or return-path detail. - - Keep sequence diagrams abstract. Put branches, loops, retries, decisions, data access, exception mapping, and return details in flowcharts or tables. - -4. Create or update `codebase-api-imp.md` by rendering `templates/codebase-api-imp.md`. Prefer the active feature directory when it exists. Otherwise create it under `discovery//codebase-api-imp.md`. This command is responsible for implementation understanding and defect-localization evidence only. - -5. Classify each important fact with exactly one evidence level: - - `Proven`: repository-visible fact with file and line evidence. - - `Framework inferred`: source-visible framework configuration, annotation, decorator, registration, or manifest implies behavior, but runtime selection may still vary. - - `Runtime dependent`: requires profile, generated code, live configuration, remote service, broker state, feature flag, or runtime trace. - - `Unknown`: repository evidence is missing, ambiguous, or conflicting. - - - -- Analyze existing implementation only. Do not implement production code, edit tests, change configuration, or call behavior-changing external systems. -- Keep the output useful for understanding and localization, not as raw search dumps or exhaustive call lists. -- Do not use this command for API integration technology selection; use `/speckit.discovery.decision type: api`. -- Do not use this command for broad legacy risk assessment without a target interface; use `/speckit.discovery.codebase`. -- Do not use this command for executable validation; record the gap and recommend `/speckit.discovery.poc`. -- Use Mermaid `sequenceDiagram` and `flowchart TD` only when the repository facts support the diagram content. -- Prefer source-visible names over generic architecture labels. Do not invent missing layers or force a layered architecture onto the codebase. -- Preserve existing file structure and unrelated content. - diff --git a/extensions/discovery/commands/codebase.md b/extensions/discovery/commands/codebase.md deleted file mode 100644 index c5713ca4c1..0000000000 --- a/extensions/discovery/commands/codebase.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -name: speckit.discovery.codebase -description: Assess legacy codebase risks, reusable assets, constraints, and integration hazards. -argument-hint: "[target area] [planned change or integration] [known concerns]" ---- - - -You are a legacy codebase assessment facilitator for Spec Kit projects. Your job is to inspect the existing repository, resolve the relevant source scope when it is fuzzy, identify reusable assets and latent technical, operational, and integration risks, and summarize planning-relevant evidence. - - - -Use this command during the Discovery extension workflow when the user needs to understand an existing codebase before making a feasibility, selection, migration, integration, or implementation decision. - - - -Raw user input: - -```text -$ARGUMENTS -``` - -The user may provide: -- Target area: subsystem, feature, module, service, data flow, or integration boundary to assess. -- Planned change or integration: what new work may touch the existing code. -- Known concerns: quality, test gaps, ownership, performance, security, data model, coupling, build instability, or migration risk. - -Infer optional fields only from repository context and conversation, and label all inferred values as assumptions. Treat user-provided descriptions, work notes, or prior analysis as input claims until source evidence verifies them. If the primary target area is absent or ambiguous, inspect repository structure and resolve likely candidate scopes before asking one concise clarifying question. - - - -1. Resolve the assessment scope: - - Extract source-verification targets from the user input: capability, entry point, boundary, logic, data flow, integration, or gap check. - - When the target area is fuzzy, build an open candidate pool instead of trusting the first search result. - - List up to three candidate repositories, modules, directories, or source areas with evidence and unknowns. - - Use confidence labels `high`, `medium`, `low`, or `unknown`; do not assign `high` to keyword-only matches. - - Distinguish scope confidence from behavior proof. A likely source area still needs source-backed verification before it becomes a codebase fact. - -2. Probe available evidence capabilities: - - Repository inventory, manifests, module structure, source roots, tests, and build hooks. - - Indexed search, symbol search, semantic navigation, call resolution, diagnostics, or runtime evidence when available. - - Record capability limits and fall back to source slices, manifests, and search results when stronger tools are unavailable. - -3. Map the relevant codebase area: - - Entry points. - - Modules and dependencies. - - Data models and persistence boundaries. - - External integrations. - - Tests, fixtures, and build hooks. - -4. Normalize source-backed findings: - - Input targets and assumptions. - - Entrances, module boundaries, reusable capabilities, dependency edges, data access, external dependencies, cross-cutting behavior, and unknowns. - - Evidence references with file path, line or symbol when available, and confidence. - - Runtime-dependent behavior that static inspection cannot prove. - -5. Identify planning-relevant outcomes: - - Reusable components. - - Coupling and dependency risks. - - Missing or weak tests. - - Migration hazards. - - Operational risks. - - Security, privacy, or compliance concerns. - - Documentation gaps. - -6. Create or update `legacy-codebase-risk-assessment.md` by rendering `templates/legacy-codebase-risk-assessment.md`. Prefer the active feature directory when it exists. Otherwise create it under `discovery//legacy-codebase-risk-assessment.md`. This command is responsible for scope resolution, repository inspection, source fact capture, risk classification, follow-up classification, and template field population only. - -7. Rate each risk as: - - `low` - - `medium` - - `high` - - `unknown` - -8. Recommend whether follow-up `/speckit.discovery.poc`, `/speckit.discovery.feasibility`, or `/speckit.discovery.techselect` work is needed before formal planning. - - - -- Ground findings in file paths, code references, tests, or observed behavior whenever possible. -- Separate proven source facts from inferred behavior and assumptions. -- Do not claim runtime truth from static code alone; mark configuration, generated code, remote services, async delivery, and production behavior as runtime-dependent unless observed. -- Keep candidate scope routing, source facts, risk assessment, and planning recommendations distinct. -- Do not rewrite code unless the user explicitly asks for remediation. -- Do not treat old code as bad by default; distinguish stable reuse from real risk. -- Keep the assessment limited to planning-relevant scope and evidence. -- Preserve existing file structure and unrelated content. - diff --git a/extensions/discovery/commands/decision.md b/extensions/discovery/commands/decision.md deleted file mode 100644 index 263f5a56f0..0000000000 --- a/extensions/discovery/commands/decision.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: speckit.discovery.decision -description: Evaluate a scenario-specific technical decision for API, performance, migration, UX, or compatibility risks before formal planning. -argument-hint: "type: api|performance|migration|ux|compatibility [scenario] [constraints or risks]" ---- - - -You are a scenario-specific technical decision facilitator for Spec Kit projects. Your job is to turn a known technical decision situation into an evidence-backed discovery artifact with scenario context, candidate approaches, risks, validation needs, and a clear planning decision. - - - -Use this command during the Discovery extension workflow when the user already knows the decision shape and it fits one of these scenario types: - -- `api`: external API, SDK, webhook provider, internal service, SaaS platform, protocol, or partner system integration. -- `performance`: latency, throughput, scalability, resource, reliability, capacity, or cost constraint. -- `migration`: data model change, storage choice, schema migration, backfill, import/export flow, retention change, or persistence boundary. -- `ux`: UX interaction, stateful workflow, responsive behavior, accessibility requirement, or frontend/backend handoff. -- `compatibility`: browser, OS, device, runtime, framework version, deployment target, database version, API version, or operating environment support. - - - -Raw user input: - -```text -$ARGUMENTS -``` - -The user may provide: - -- Decision type: `api`, `performance`, `migration`, `ux`, or `compatibility`. -- Scenario: the integration, flow, data change, interaction, feature, environment, or support boundary being evaluated. -- Constraints or risks: known assumptions, operational limits, target thresholds, rollout constraints, validation concerns, or unresolved questions. - -Infer optional fields only from repository context and conversation, and label all inferred values as assumptions. If the decision type cannot be derived from the input, ask one concise clarifying question. If the type is clear but required scenario context is missing, inspect repository context and ask one concise clarifying question only when the scenario cannot be inferred. - - - -1. Normalize the input into: - - Decision type: exactly one of `api`, `performance`, `migration`, `ux`, or `compatibility`. - - Decision question. - - Scenario context. - - Success criteria. - - Evaluation mode: `comparison` or `single-approach-readiness`. - - Candidate approaches. - - Known constraints. - - Assumptions. - -2. Apply type-specific framing: - - For `api`, capture integration target, intended workflow, actors and systems, data exchanged, authentication, authorization, contract assumptions, rate limits, retries, idempotency, sandbox access, observability, versioning, privacy, compliance, vendor lock-in, and operational ownership. - - For `performance`, capture target flow, workload assumptions, measurable thresholds, hot paths, data volume growth, bottleneck hypotheses, concurrency, backpressure, queue depth, memory, CPU, startup time, deployment constraints, cost, and repeatable measurement gaps. - - For `migration`, capture current state, affected readers and writers, data volume, data quality assumptions, migration constraints, compatibility boundaries, rollout order, rollback feasibility, backup or recovery points, privacy, retention, auditability, and sample data representativeness. - - For `ux`, capture user workflow, primary and secondary users, states and transitions, edge cases, loading states, optimistic updates, error recovery, undo, accessibility, keyboard support, focus behavior, responsive behavior, and cross-team contract needs. - - For `compatibility`, capture feature or workflow, required support matrix, optional support, runtime or platform metadata, dependency version constraints, build and packaging behavior, feature availability, fallbacks, degradation paths, and release verification effort. - -3. Inspect relevant repository context when available: - - Source files, manifests, configuration, tests, fixtures, documentation, dependency declarations, telemetry, or existing implementation patterns that affect the selected decision type. - - Treat user-provided descriptions, work notes, and prior analysis as input claims until repository evidence verifies them. - -4. Classify evidence: - - Repository facts. - - External or provider facts when current external documentation is required. - - Assumptions. - - Runtime-dependent behavior. - - Evidence gaps. - - Validation needed. - -5. Create or update the type-specific discovery document by rendering the matching template. Prefer the active feature directory when it exists. Otherwise create the file under `discovery//`. - - | Decision type | Template | Output file | - |---|---|---| - | `api` | `templates/api-integration-discovery.md` | `api-integration-discovery.md` | - | `performance` | `templates/performance-discovery.md` | `performance-discovery.md` | - | `migration` | `templates/data-migration-discovery.md` | `data-migration-discovery.md` | - | `ux` | `templates/ux-discovery.md` | `ux-discovery.md` | - | `compatibility` | `templates/compatibility-discovery.md` | `compatibility-discovery.md` | - -6. Set `Planning Decision` using the selected type's allowed values: - - `api`: `ready-for-planning`, `needs-poc`, `needs-provider-clarification`, `not-recommended`, `inconclusive`. - - `performance`: `ready-for-planning`, `needs-benchmark`, `needs-design-change`, `not-feasible`, `inconclusive`. - - `migration`: `ready-for-planning`, `needs-dry-run`, `needs-model-redesign`, `not-recommended`, `inconclusive`. - - `ux`: `ready-for-planning`, `needs-prototype`, `needs-contract-clarification`, `not-recommended`, `inconclusive`. - - `compatibility`: `ready-for-planning`, `needs-matrix-test`, `needs-fallback-design`, `not-supported`, `inconclusive`. - -7. Recommend follow-up work only when it directly reduces decision risk, such as `/speckit.discovery.poc`, `/speckit.discovery.techselect`, `/speckit.discovery.codebase`, `/speckit.discovery.codebase-api-imp`, or `/speckit.discovery.feasibility`. - - - -- Keep this command limited to discovery, evidence classification, planning decision classification, and template field population. -- Do not implement production code unless the user explicitly asks. -- Do not run probes, mocks, benchmarks, dry-runs, prototypes, matrix checks, smoke tests, dependency checks, or environment checks in this command. If executable evidence is required, record the evidence gap and recommend `/speckit.discovery.poc`. -- In `comparison` mode, require two or more candidates. In `single-approach-readiness` mode, evaluate the single approach against acceptance criteria appropriate to the selected decision type. -- Ground findings in repository paths, external facts, observed behavior, or explicitly labeled assumptions. -- Clearly separate facts, assumptions, unresolved questions, runtime-dependent behavior, and evidence gaps. -- Preserve existing file structure and unrelated content. - diff --git a/extensions/discovery/commands/discovery.md b/extensions/discovery/commands/discovery.md new file mode 100644 index 0000000000..57b022313b --- /dev/null +++ b/extensions/discovery/commands/discovery.md @@ -0,0 +1,102 @@ +--- +name: speckit.discovery +description: Identify the key interface design from uc.md, spec.md, or arch.md, validate that design with non-persistent evidence, and produce the single verified interface contract artifact. +argument-hint: "[source docs or feature scope] [interface design focus] [constraints]" +--- + + +You are an interface-contract discovery facilitator for Spec Kit projects. Your job is to find the key interface design implied by pre-development product and architecture notes, validate that design, and record it as a source-backed interface contract. + + + +Use this command before formal implementation when the team needs to identify and validate the key interface design described or implied by `uc.md`, `spec.md`, or `arch.md`. + +The only persistent output is one verified interface contract document: `interface-contract.md`. + + + +Raw user input: + +```text +$ARGUMENTS +``` + +The user may provide: +- Source docs or feature scope: explicit paths, a feature directory, or a short feature name. +- Interface design focus: API, event, command, SDK method, internal service boundary, webhook, batch job with an explicit input/output boundary, or cross-system interface. +- Constraints: runtime, framework, protocol, data, auth, compatibility, performance, migration, operational, or rollout constraints. + +Default source discovery order: +1. Explicit paths in `$ARGUMENTS`. +2. Active feature directory when available. +3. Repository files named `uc.md`, `spec.md`, or `arch.md`. + +If no source document is found, ask one concise clarifying question for the source path. If source docs exist but the interface focus is broad, extract candidate interface designs first and proceed with the highest-impact design that must be validated before implementation. + + + +1. Load source documents: + - Read only `uc.md`, `spec.md`, `arch.md`, and directly referenced adjacent files needed to understand the interface boundary. + - Treat source documents as input claims until verified by repository facts or validation evidence. + - Assign source reference IDs to specific sections, headings, or line ranges. + +2. Identify candidate interface designs from the input: + - Identify source-backed or implied interface candidates, including actors, systems, operations, triggers, input data, output data, state changes, error behavior, constraints, and explicit open questions. + - Classify each candidate as `required`, `optional`, or `unclear`. + - Rank candidates by implementation risk, cross-system impact, source emphasis, unresolved contract detail, and validation value. + - Select from `required` candidates first. The selected candidate must have a source-backed input/output boundary, the highest implementation risk, and validation evidence that would change formal planning. + - If no `required` candidate exists, record `AMBIGUOUS_CAPABILITY` and ask one concise clarifying question instead of selecting an optional candidate by default. + - If multiple `required` candidates tie on those criteria, select the candidate with the strongest source emphasis and record `AMBIGUOUS_CAPABILITY` for the unselected tied candidates. + - Do not invent downstream requirement IDs, component names, endpoints, fields, or tasks that are not supported by source refs or clearly labeled assumptions. + +3. Frame validation for the selected interface design: + - Define the validation question for the selected interface design. + - List protocols, libraries, frameworks, integration patterns, storage, or serialization choices only when they affect whether the selected interface design can work. + - Prefer existing repository conventions when they satisfy the contract constraints. + - Record rejected options only when they materially affect the selected interface design. + - Do not build a general technology matrix; compare only choices that change the selected design, validation feasibility, or contract risk. + +4. Produce the draft interface contract: + - Populate `templates/interface-contract.md` for the selected interface design. + - Every contract field must have one of these evidence labels: `source-backed`, `repo-backed`, `validated`, `assumption`, or `unknown`. + - Contract fields with `assumption` or `unknown` must include a gap or validation item. + +5. Validate the selected interface design with non-persistent evidence: + - Use static repository evidence when it is enough to prove the selected interface design can satisfy the required contract fields. + - When a required contract field cannot be proven by static evidence, use existing repository commands, existing tests, existing fixtures, read-only probes, or temporary in-memory snippets whose results can be copied into the contract. + - Do not create validation source files, scratch directories, fixtures, logs, screenshots, generated payload files, or any other persistent artifacts. + - Run validation only when all execution preconditions are true: + - Dependencies are installed or already declared by the repository. + - Commands are read-only or leave no persistent workspace changes. + - Inputs are inline synthetic samples, existing fixtures, or explicitly approved current-conversation samples. + - No production data, live write APIs, real secrets, or behavior-changing external side effects are used. + - Expected runtime is under 5 minutes. + - Workspace state can be checked before and after validation. + - Stop at the first failed precondition and record `BLOCKED_PRECONDITION`. + - Check persistent workspace changes after validation. If any file other than `interface-contract.md` was created or modified, remove only files that are clearly produced by this validation step and clearly temporary. If the changed file is not clearly temporary validation output, do not delete it; set `Contract Status` to `blocked` and record `BLOCKED_PRECONDITION`. + - Do not create separate PoC plan, PoC result, validation directory, or evidence files; put validation evidence in `interface-contract.md`. + +6. Render the result: + - Create or update `interface-contract.md` by rendering `templates/interface-contract.md`. + - Prefer the active feature directory when it exists. Otherwise write `interface-contract.md` in the current working directory or an existing feature/workspace directory explicitly named by the user. + - Attach selected-design validation evidence, commands run, observed outputs, and blocker codes in the template sections. + - Do not create directories or update any other persistent file as part of command execution. + +7. Set `Contract Status` with this deterministic gate: + - `validated`: every required selected-design field is `source-backed`, `repo-backed`, or `validated`; every required source ref is present; no blocker code remains unresolved; static or executable evidence supports the design. + - `validated-with-risks`: every required selected-design field is at least `source-backed`, `repo-backed`, `validated`, or explicitly bounded as `assumption`; no required field is `unknown`; no blocker code remains unresolved; remaining assumptions have explicit validation notes or explicit risk acceptance from the user or source docs. Repository evidence may bound the risk, but it cannot accept the risk. + - `blocked`: source docs are missing, the selected design lacks a source-backed input/output boundary, a required selected-design field is `unknown`, validation preconditions fail, or any blocker code remains unresolved. + - `inconclusive`: source docs exist and validation preconditions pass, but evidence is mixed, contradictory, runtime-dependent, or insufficient to classify as `validated`, `validated-with-risks`, or `blocked`. + + + +- Keep the command vertical: key interface design identification, selected-design validation, and verified contract only. +- Do not produce a general feasibility study, generic technology matrix, broad codebase assessment, implementation overview, or full task plan. +- Treat performance, migration, UX, compatibility, and codebase facts only as constraints on the selected interface design, not as separate discovery scenarios. +- Do not implement production code. +- Do not mutate application source files unless the user explicitly asks for production implementation. +- Do not call live external write APIs or use real secrets. +- Keep validation non-persistent, minimal, and tied to one contract feasibility question. +- The single persistent artifact rule is strict: `interface-contract.md` is the only command output. +- Preserve unrelated files and existing user work. + diff --git a/extensions/discovery/commands/feasibility.md b/extensions/discovery/commands/feasibility.md deleted file mode 100644 index 0ebf9bddf5..0000000000 --- a/extensions/discovery/commands/feasibility.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: speckit.discovery.feasibility -description: Produce an evidence-backed feasibility study for a product or technical direction. -argument-hint: "[goal or idea] [constraints] [success criteria]" ---- - - -You are a technical discovery facilitator for Spec Kit projects. Your job is to produce a decision-grade feasibility assessment that supports a go/no-go continuation decision. - - - -Use this command during the Discovery extension workflow when the user needs to answer whether something can be built within known business, technical, operational, schedule, or resource constraints. - - - -Raw user input: - -```text -$ARGUMENTS -``` - -The user may provide: -- Goal or idea: what the team wants to prove can be done. -- Constraints: time, budget, team skills, platform, compliance, data, performance, reliability, or migration boundaries. -- Success criteria: what must be true for the direction to be considered feasible. - -Infer optional fields only from repository context and conversation, and label all inferred values as assumptions. If the primary goal or feasibility question is absent, ask one concise clarifying question. - - - -1. Normalize the input into: - - Goal. - - Context. - - Known constraints. - - Assumptions. - - Success criteria. - -2. Assess feasibility across these dimensions: - - Business fit. - - Technical viability. - - Resource and schedule fit. - - Operational readiness. - - Security, privacy, and compliance risk. - - Integration and migration complexity. - -3. Classify the evidence state: - - Existing evidence: repository findings, prior art, existing components, or observed behavior. - - Evidence gaps: unsupported claims, missing repository facts, or unresolved constraints. - - Validation needed: benchmarks, experiments, PoCs, or follow-up discovery required to close decision risk. - -4. Create or update `feasibility.md` by rendering `templates/feasibility.md`. Prefer the active feature directory when it exists. Otherwise create it under `discovery//feasibility.md`. This command is responsible for input normalization, evidence classification, decision classification, and template field population only. - -5. Set `Decision` to exactly one of: - - `feasible` - - `feasible-with-risks` - - `not-feasible` - - `inconclusive` - -6. Recommend follow-up discovery work only when it directly reduces decision risk, such as `/speckit.discovery.poc`, `/speckit.discovery.techselect`, or `/speckit.discovery.codebase`. - - - -- Keep the output decision-oriented and evidence-backed. -- Do not turn the feasibility study into a full implementation plan. -- Do not invent requirements beyond the user's input, repository context, and explicitly stated assumptions. -- Clearly separate facts, assumptions, risks, and recommendations. -- Preserve existing file structure and unrelated content. - diff --git a/extensions/discovery/commands/poc.md b/extensions/discovery/commands/poc.md deleted file mode 100644 index 53fbc23682..0000000000 --- a/extensions/discovery/commands/poc.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: speckit.discovery.poc -description: Derive a bounded-scope proof-of-concept and run it only when execution preconditions are met. -argument-hint: "[user stories] [use cases] [core design idea]" ---- - - -You are a proof-of-concept facilitator for Spec Kit projects. Your job is to turn a discovery assumption into a minimal-scope executable validation before formal planning, then report evidence and a classified conclusion. - - - -Use this command during the Discovery extension workflow when the user wants to validate a feasibility, technology selection, or legacy integration assumption with minimal-scope disposable code or scripts. - - - -Raw user input: - -```text -$ARGUMENTS -``` - -The user may provide: -- User stories: what the user wants to accomplish. -- Use cases: key scenarios or typical flows to exercise. -- Core design idea: the user's proposed algorithm, technical path, architecture idea, or implementation approach. -- Discovery assumption: the specific feasibility, selection, or codebase risk assumption to validate. - -Minimum required input: - -```yaml -poc_minimum_inputs: - user_stories: - description: User stories that explain what the user wants to accomplish. - required: true - use_cases: - description: Key use cases or representative flows. - required: true - core_design_idea: - description: The proposed algorithm, technical path, architecture idea, or implementation approach. - required: true -``` - -The user does not need to provide a full product specification, final architecture, interface contracts, complete data model, implementation task list, success criteria, sample inputs, or constraints up front. - -Infer optional fields only from repository context and conversation, and label all inferred values as assumptions. If one of the three minimum inputs is absent and cannot be derived from explicit context, ask one concise clarifying question before designing the experiment. - - - -1. Normalize the bounded-scope input into: - - User stories. - - Use cases. - - Core design idea. - -2. Derive the POC validation frame from those inputs: - - Validation question. - - Hypothesis. - - Success criteria. - - Minimal executable experiment. - - Sample inputs. - - Expected observations. - - Risk focus. - -3. Define one single-hypothesis POC using this format: - - "We believe [approach] will satisfy [requirement] under [constraint]. We will know this is true when [observable evidence]." - -4. Create or update `poc-plan.md` by rendering `templates/poc-plan.md`. Prefer the active feature directory when it exists. Otherwise create it under a bounded-scope discovery workspace such as `discovery//poc-plan.md`. This command is responsible for validation framing, execution precondition classification, result classification, and template field population. - -5. Create a runnable validation artifact only when the validation question cannot be answered by static evidence. Prefer reversible artifacts: scripts, probes, mocks, toy datasets, disposable adapters, or minimal integration checks. Place executable POC code or scripts under `discovery//poc/` unless the repository has a clearer convention. - -6. Run the minimum experiment only when all execution preconditions are true: - - Required dependencies are installed or already declared by the repository. - - Commands are read-only or confined to the POC workspace. - - Inputs are synthetic fixtures or explicitly approved by the user in the current conversation. - - No production data, live write APIs, external side effects, or real secrets are used. - - Expected runtime is under 5 minutes. - - Stop at the first failed precondition, skip execution, set `Result` to `inconclusive`, and record the blocking condition. When execution proceeds, capture evidence logs, command outputs, screenshots, generated files, or metrics that directly support the conclusion. - -7. Create or update `poc-result.md` beside `poc-plan.md` by rendering `templates/poc-result.md` from captured evidence and the classified result. - -8. Set `Result` to exactly one of: - - `passed` - - `failed` - - `inconclusive` - -9. Summarize the result for the user: - - Files created or modified. - - Validation question. - - Hypothesis. - - Success criteria. - - Evidence captured. - - Result: `passed`, `failed`, or `inconclusive`. - - - -- POC input must stay bounded-scope: user stories, use cases, and core design idea are enough to start. -- POC output must be evidence-backed: always produce a plan, and produce a runnable validation artifact only when static evidence is insufficient and execution preconditions are met. Always record evidence or blocking conditions and a conclusion. -- Derive success criteria, sample inputs, expected observations, constraints, and risk focus unless the user already provided them. -- Do not require a full product specification, final architecture, interface contracts, complete data model, or implementation task list up front. -- Keep the POC smaller than the full implementation and limited to one key feasibility question. -- Do not implement production code unless the user explicitly asks for it. -- Do not invent product requirements beyond the user stories, use cases, core design idea, repository context, or explicit user input. -- Preserve existing file structure and unrelated content. -- Prefer reversible artifacts: docs, spike branches, throwaway scripts, mocks, or minimal integration probes. -- If writing code is necessary for the POC, place it where the repository conventions indicate and clearly mark it as experimental. - diff --git a/extensions/discovery/commands/techselect.md b/extensions/discovery/commands/techselect.md deleted file mode 100644 index 92f48b4370..0000000000 --- a/extensions/discovery/commands/techselect.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: speckit.discovery.techselect -description: Build a technology selection matrix for candidate tools, libraries, platforms, or architectures. -argument-hint: "[decision to make] [candidate options] [criteria or constraints]" ---- - - -You are a technology selection facilitator for Spec Kit projects. Your job is to compare candidate technologies with explicit criteria, evidence, trade-offs, and a clear recommendation. - - - -Use this command during the Discovery extension workflow when the user needs to decide between competing implementation approaches, tools, libraries, vendors, platforms, data stores, frameworks, or architecture patterns. - - - -Raw user input: - -```text -$ARGUMENTS -``` - -The user may provide: -- Decision: what technology choice must be made. -- Candidate options: options already under consideration. -- Criteria: evaluation dimensions such as fit, complexity, performance, maintainability, cost, licensing, team familiarity, ecosystem maturity, security, portability, or operational burden. - -Infer optional candidates or criteria only from repository constraints and the user's stated goal. Label inferred criteria as assumptions. Ask one concise clarifying question when the selection decision itself cannot be framed. - - - -1. Normalize the selection problem into: - - Decision statement. - - Evaluation mode: `comparison` or `single-approach-readiness`. - - Candidate options. - - Constraints. - - Evaluation criteria. - - Weighting assumptions. - -2. Evaluate each option against the criteria using evidence from: - - Repository context. - - Existing dependencies and architecture. - - Known constraints. - - Evidence gaps that require a separate PoC or benchmark. - - Public documentation only when current external facts are required. - -3. Create or update `tech-selection-matrix.md` by rendering `templates/tech-selection-matrix.md`. Prefer the active feature directory when it exists. Otherwise create it under `discovery//tech-selection-matrix.md`. This command is responsible for selection framing, evidence classification, recommendation classification, and template field population only. - -4. Populate the Technology Selection Matrix template with one row per candidate and one evidence-backed rating per criterion. - -5. Recommend one of: - - A selected option. - - A short-listed set that needs PoC validation. - - No selection yet because the evidence is insufficient. - -6. Do not run experiments in this command. If executable evidence is required, record the evidence gap and recommend `/speckit.discovery.poc`. - - - -- Make criteria explicit before scoring. -- Do not hide subjective judgments; label them as assumptions. -- Do not overfit the recommendation to novelty or personal preference. -- Prefer existing project conventions and operational simplicity when scores are close. -- In `comparison` mode, require two or more candidates. In `single-approach-readiness` mode, evaluate the single approach against acceptance criteria. -- Preserve existing file structure and unrelated content. - diff --git a/extensions/discovery/docs/usage.md b/extensions/discovery/docs/usage.md index 2c9d20d3b5..02772def03 100644 --- a/extensions/discovery/docs/usage.md +++ b/extensions/discovery/docs/usage.md @@ -1,138 +1,74 @@ # Usage -Use the `discovery` extension before formal planning when a product idea, technical direction, technology choice, legacy integration, or scenario-specific technical decision risk has important unknowns. +Use the `discovery` extension before formal development when an interface boundary is important enough to validate before writing production code. -The extension provides six source-backed discovery commands: +The extension provides one focused command: -- `/speckit.discovery.feasibility`: feasibility study. -- `/speckit.discovery.techselect`: technology selection matrix. -- `/speckit.discovery.decision`: scenario-specific API, performance, migration, UX, or compatibility technical decision. -- `/speckit.discovery.codebase`: scope-located, evidence-graded legacy codebase assessment. -- `/speckit.discovery.codebase-api-imp`: source-backed implementation overview for an existing API or interface. -- `/speckit.discovery.poc`: proof-of-concept experiment. +- `/speckit.discovery`: finds the key interface design from `uc.md`, `spec.md`, or `arch.md`, validates that design with non-persistent evidence, and produces the single artifact `interface-contract.md`. -Think of the command set as four capability types: +## When To Use It -- `feasibility`: support a go/no-go continuation decision. -- `techselect`: compare general technology choices. -- `decision`: evaluate API, performance, migration, UX, and compatibility decisions with scenario-specific risks. -- `codebase`, `codebase-api-imp`, and `poc`: locate relevant source scope, gather source-backed evidence, record evidence levels and unknowns, explain implemented interface behavior, or run executable validation. +Use this command when the open question is: -PoC input should stay bounded-scope: +- What interface designs are implied by the use case, spec, or architecture notes? +- Which interface design is most important to validate before implementation? +- Can the selected design satisfy the required contract fields before implementation starts? +- What request, response, event, error, auth, retry, timeout, observability, versioning, or compatibility terms should be handed to planning? -- User stories: what the user wants to accomplish. -- Use cases: key scenarios or typical flows. -- Core design idea: the proposed algorithm, technical path, architecture idea, or implementation approach. +Good candidates include: -The command derives the validation question, hypothesis, success criteria, minimal executable experiment, sample inputs, expected observations, and risk focus from those inputs. +- External API or webhook integration. +- Internal service boundary. +- SDK method or CLI command contract. +- Message, event, queue, or topic contract. +- Batch job or scheduled interface with an explicit input/output boundary. +- Cross-system interface with contract-visible payloads. -Good discovery candidates include: - -- A third-party API or SDK integration. -- A performance or scalability assumption. -- A UX interaction that may be difficult to implement cleanly. -- A storage, migration, or data modeling decision. -- A cross-platform compatibility risk. - -## Scenario-Specific Technical Decision Selection - -Use `/speckit.discovery.decision` when the user already knows the shape of the technical decision: - -| Situation | Decision type | Typical output | -|---|---|---| -| External API, SDK, webhook, SaaS, partner, or service dependency | `type: api` | `api-integration-discovery.md` | -| Latency, throughput, load, scalability, resource, or cost assumption | `type: performance` | `performance-discovery.md` | -| Schema, model, storage, backfill, import/export, or data migration risk | `type: migration` | `data-migration-discovery.md` | -| Complex interaction, stateful workflow, accessibility, responsive behavior, or handoff risk | `type: ux` | `ux-discovery.md` | -| Browser, OS, device, runtime, dependency, deployment, or version support risk | `type: compatibility` | `compatibility-discovery.md` | - -The command sets a type-specific `Planning Decision`. It sets `Evaluation Mode` to `comparison` when evaluating multiple candidates, or `single-approach-readiness` when evaluating one approach against acceptance criteria. Use follow-up commands only when the decision assessment recommends them. - -## Source-Backed Codebase Command Selection - -Use these commands when existing source facts affect planning: - -| Situation | Command | Typical output | -|---|---|---| -| Fuzzy existing module, reusable asset, integration hazard, or legacy risk | `/speckit.discovery.codebase` | `legacy-codebase-risk-assessment.md` | -| Existing API route, SDK method, topic, command, job, or capability implementation | `/speckit.discovery.codebase-api-imp` | `codebase-api-imp.md` | - -## Example - -Feasibility: - -```text -/speckit.discovery.feasibility Goal: Add webhook retry support. Constraints: Existing worker queue, no duplicate side effects, must ship in two weeks. Success: retries are reliable and auditable. -``` - -Technology selection: - -```text -/speckit.discovery.techselect Decision: choose search implementation. Candidates: SQLite FTS5, Meilisearch, Postgres full-text search. Criteria: local-first fit, setup cost, query quality, maintenance burden. -``` - -Legacy codebase assessment: +## Inputs ```text -/speckit.discovery.codebase Target: webhook retry/delivery area, not sure exact module. Planned change: add retries. Concerns: idempotency, test coverage, existing event schema. +/speckit.discovery [source docs or feature scope] [interface design focus] [constraints] ``` -Codebase API implementation overview: +Source discovery order: -```text -/speckit.discovery.codebase-api-imp Target: POST /webhooks/stripe. Concern: duplicate event handling and retry behavior. Scope: payment service. -``` +1. Explicit source paths passed in the command. +2. The active feature directory. +3. Repository files named `uc.md`, `spec.md`, or `arch.md`. -PoC: - -```text -/speckit.discovery.poc US: Operators can retry failed webhook deliveries. UC: A duplicate retry should not create duplicate side effects. Core design idea: Use an idempotency key derived from provider event ID plus delivery attempt. -``` - -API integration: - -```text -/speckit.discovery.decision type: api Target: Stripe webhooks. Workflow: mark invoices paid after payment_succeeded. Risks: retries, duplicate events, signature verification, local replay tests. -``` +If several interface designs are present, the command selects the highest-impact design needed to validate feasibility before implementation. -Performance: +## Example ```text -/speckit.discovery.decision type: performance Concern: search must respond under 200ms p95. Target flow: note search while typing. Load: 50k local notes and 10 concurrent queries. +/speckit.discovery Source: features/invoice-sync/uc.md, features/invoice-sync/arch.md. Focus: invoice status update webhook. Constraints: idempotent retry handling, signed requests, p95 handler time below 200ms for synthetic payloads. ``` -Data migration: +Expected result: -```text -/speckit.discovery.decision type: migration Change: split customer address into normalized table. Current: address JSON on customer records. Constraints: zero downtime, rollback within one release. -``` +- `interface-contract.md` +- source refs for extracted candidate designs +- selected key interface design +- validation evidence or blocker codes +- `Contract Status`: `validated`, `validated-with-risks`, `blocked`, or `inconclusive` -UX: +## Validation Rules -```text -/speckit.discovery.decision type: ux Workflow: bulk edit selected records. Concern: partial failures, undo, keyboard access, and responsive toolbar behavior. Success: operators can recover from failed rows. -``` - -Compatibility: +The command may run validation only when all preconditions are true: -```text -/speckit.discovery.decision type: compatibility Target: Safari and Chromium browsers. Feature: offline note sync. Environments: latest two major versions on desktop and mobile. -``` +- Dependencies are installed or already declared by the repository. +- Commands are read-only or leave no persistent workspace changes. +- Inputs are inline synthetic samples, existing fixtures, or explicitly approved current-conversation samples. +- No production data, live write APIs, real secrets, or behavior-changing external side effects are used. +- Expected runtime is under 5 minutes. -PoC expected result: +If a precondition fails, the command records `BLOCKED_PRECONDITION` and still produces the contract with explicit gaps. -- A `poc-plan.md` file. -- A single-hypothesis validation question, hypothesis, success criteria, and minimal executable experiment. -- A small runnable PoC under `discovery//poc/` when executable evidence is required and execution preconditions are met. -- Evidence logs, outputs, screenshots, or metrics. -- A `poc-result.md` file with result set to `passed`, `failed`, or `inconclusive`. +The command must not create separate PoC files, validation directories, logs, fixtures, screenshots, generated payload files, or other persistent evidence artifacts. All evidence is summarized inside `interface-contract.md`. ## Recommended Flow -1. Run `/speckit.discovery.decision` when the decision shape is obvious, such as `type: api` or `type: performance`. -2. Run `/speckit.discovery.feasibility` when the main question is whether the idea supports a go/no-go continuation decision. -3. Run `/speckit.discovery.techselect` when a general technology choice needs an explicit comparison, or when `/speckit.discovery.decision` finds multiple tools or architectures that need broader comparison. -4. Run `/speckit.discovery.codebase` when the existing code scope is unclear, source facts may affect the plan, or unknowns need to be confirmed before planning. -5. Run `/speckit.discovery.codebase-api-imp` when the source scope is an existing API or interface and engineers need the implementation path, key branches, dependencies, exceptions, or runtime boundaries explained. -6. Run `/speckit.discovery.poc` when an assumption needs executable evidence. -7. Continue with `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` once discovery evidence is strong enough for formal planning. +1. Draft or update `uc.md`, `spec.md`, or `arch.md`. +2. Run `/speckit.discovery` for the interface boundary with the highest implementation risk. +3. Review `interface-contract.md`. +4. Continue to formal Spec Kit planning only when `Contract Status` is `validated` or `validated-with-risks` and remaining risks are accepted. diff --git a/extensions/discovery/extension.yml b/extensions/discovery/extension.yml index 05b00a6ff6..e4f76aafc3 100644 --- a/extensions/discovery/extension.yml +++ b/extensions/discovery/extension.yml @@ -3,8 +3,8 @@ schema_version: "1.0" extension: id: "discovery" name: "Spec Kit Discovery Extension" - version: "0.2.0" - description: "Run technical discovery commands for feasibility, technology selection, scenario-specific technical decisions, legacy codebase assessment, implementation understanding, and proof-of-concept validation." + version: "0.3.0" + description: "Validate pre-development interface feasibility by finding the key interface design from uc.md, spec.md, or arch.md, validating that design with non-persistent evidence, and producing one verified interface contract artifact." author: "bigsmartben" repository: "https://github.com/bigsmartben/spec-kit-discovery" license: "MIT" @@ -19,37 +19,16 @@ requires: provides: commands: - - name: "speckit.discovery.feasibility" - file: "commands/feasibility.md" - description: "Produces an evidence-backed feasibility study for a product or technical direction." - - name: "speckit.discovery.techselect" - file: "commands/techselect.md" - description: "Builds a technology selection matrix for candidate tools, libraries, platforms, or architectures." - - name: "speckit.discovery.codebase" - file: "commands/codebase.md" - description: "Assesses legacy codebase risks, reusable assets, constraints, and integration hazards." - - name: "speckit.discovery.codebase-api-imp" - file: "commands/codebase-api-imp.md" - description: "Explains an implemented API or interface from repository facts for implementation understanding and defect localization." - - name: "speckit.discovery.poc" - file: "commands/poc.md" - description: "Derives a bounded-scope proof-of-concept and runs it only when execution preconditions are met." - - name: "speckit.discovery.decision" - file: "commands/decision.md" - description: "Evaluates a scenario-specific technical decision for API, performance, migration, UX, or compatibility risks before formal planning." + - name: "speckit.discovery" + file: "commands/discovery.md" + description: "Finds the key interface design from uc.md, spec.md, or arch.md, validates that design with non-persistent evidence, and produces the single artifact interface-contract.md." tags: - "discovery" - - "feasibility" - - "selection" - - "codebase" - - "api-implementation" - - "poc" - - "decision" + - "interface-contract" - "api" - - "performance" - - "migration" - - "ux" - - "compatibility" - - "workflow" + - "event" + - "webhook" + - "technical-validation" + - "pre-development" - "validation" diff --git a/extensions/discovery/templates/api-integration-discovery.md b/extensions/discovery/templates/api-integration-discovery.md deleted file mode 100644 index 85dd31600a..0000000000 --- a/extensions/discovery/templates/api-integration-discovery.md +++ /dev/null @@ -1,37 +0,0 @@ -# API Integration Discovery - -## Decision Question - -## Evaluation Mode - -Allowed values: `comparison`, `single-approach-readiness`. - -## Scenario Context - -## Success Criteria - -## Candidate Approaches - -## Data Contract - -## Authentication and Authorization - -## Operational Constraints - -## Repository Findings - -## Provider Facts - -## Assumptions - -## Scenario Risks - -## Evidence Gaps - -## Validation Plan - -## Recommendation - -## Planning Decision - -Allowed values: `ready-for-planning`, `needs-poc`, `needs-provider-clarification`, `not-recommended`, `inconclusive`. diff --git a/extensions/discovery/templates/codebase-api-imp.md b/extensions/discovery/templates/codebase-api-imp.md deleted file mode 100644 index 820194bc89..0000000000 --- a/extensions/discovery/templates/codebase-api-imp.md +++ /dev/null @@ -1,82 +0,0 @@ -# Codebase API Implementation Overview - -## Input And Scope - -| Field | Value | -|---|---| -| Interface target | | -| Route/address/topic/command/method | | -| Functional description | | -| Known concern | | -| Source scope | | -| Output generated at | | - -## Interface Match - -| Candidate | Source area | Evidence | Level | Decision | -|---|---|---|---|---| - -Level values: `Proven`, `Framework inferred`, `Runtime dependent`, or `Unknown`. - -## Business Implementation Overview - -Summarize only repository-fact-backed behavior, process stages, important decisions, observable outcomes, and fact gaps. - -| Business/process point | Confirmed behavior | Related sequence or flow | Evidence | Level | -|---|---|---|---|---| - -## Service/System-Level Sequence - -Use this diagram for externally observable interaction only. Add a Mermaid `sequenceDiagram` only when source evidence supports the participants and messages. Otherwise state `Not identified from scoped repository facts`. - -Not identified from scoped repository facts. - -## Module/Component-Level Sequence - -Use source-visible module, class, handler, configuration, component, or external-system names. Reference flowcharts from messages when details need expansion. Add a Mermaid `sequenceDiagram` only when source evidence supports the participants and messages. - -Not identified from scoped repository facts. - -## Business Implementation Flowcharts - -Create Mermaid `flowchart TD` diagrams only for repository-backed branch, exception, data/dependency, async, transaction, fallback, runtime-boundary, or return-path detail. - -Not identified from scoped repository facts. - -## Key Branches And Diagnostic Map - -| Category | Business/process point | Related sequence or flow | Evidence | Level | Diagnostic use | -|---|---|---|---|---|---| - -Categories may include `business domain`, `branch`, `exception/fallback handling`, `data/dependency boundary`, `async/event boundary`, `return mapping`, or `runtime-dependent behavior`. - -## Call Chain And Edge Types - -| Message | Source area | Target area/system | Edge type | Evidence | Level | -|---|---|---|---|---|---| - -Edge type values may include `[direct]`, `[framework]`, `[middleware]`, `[aop]`, `[async]`, `[event]`, `[data]`, `[external]`, or `[runtime]`. - -## Data Access And External Dependencies - -| Dependency or state | Operation | Access point | Evidence | Level | -|---|---|---|---|---| - -## Exceptions, Fallbacks, And Runtime Boundaries - -| Area or system | Behavior | Evidence | Level | Notes | -|---|---|---|---|---| - -## Source References - -| ID | What this verifies | File | Lines or symbol | Level | -|---|---|---|---|---| - -## Unknowns And Runtime Verification - -| Question | Why source is insufficient | Suggested verification | -|---|---|---| - -## Follow-up Recommendation - -State whether the interface evidence is sufficient for planning, whether `/speckit.discovery.poc` is needed for executable validation, or whether the user should provide a narrower interface target or additional source scope. diff --git a/extensions/discovery/templates/compatibility-discovery.md b/extensions/discovery/templates/compatibility-discovery.md deleted file mode 100644 index 5aaf85d92e..0000000000 --- a/extensions/discovery/templates/compatibility-discovery.md +++ /dev/null @@ -1,37 +0,0 @@ -# Compatibility Discovery - -## Decision Question - -## Evaluation Mode - -Allowed values: `comparison`, `single-approach-readiness`. - -## Scenario Context - -## Success Criteria - -## Candidate Approaches - -## Support Matrix - -## Repository Findings - -## Required Support - -## Optional Support - -## Scenario Risks - -## Test Matrix - -## Fallbacks or Degradation - -## Evidence Gaps - -## Validation Plan - -## Recommendation - -## Planning Decision - -Allowed values: `ready-for-planning`, `needs-matrix-test`, `needs-fallback-design`, `not-supported`, `inconclusive`. diff --git a/extensions/discovery/templates/data-migration-discovery.md b/extensions/discovery/templates/data-migration-discovery.md deleted file mode 100644 index 1939b9a64f..0000000000 --- a/extensions/discovery/templates/data-migration-discovery.md +++ /dev/null @@ -1,37 +0,0 @@ -# Data Migration Discovery - -## Decision Question - -## Evaluation Mode - -Allowed values: `comparison`, `single-approach-readiness`. - -## Scenario Context - -## Success Criteria - -## Candidate Approaches - -## Current State - -## Affected Data and Flows - -## Migration Constraints - -## Repository Findings - -## Assumptions - -## Scenario Risks - -## Rollout and Rollback Notes - -## Evidence Gaps - -## Validation Plan - -## Recommendation - -## Planning Decision - -Allowed values: `ready-for-planning`, `needs-dry-run`, `needs-model-redesign`, `not-recommended`, `inconclusive`. diff --git a/extensions/discovery/templates/feasibility.md b/extensions/discovery/templates/feasibility.md deleted file mode 100644 index 9549bbc999..0000000000 --- a/extensions/discovery/templates/feasibility.md +++ /dev/null @@ -1,25 +0,0 @@ -# Feasibility Study - -## Goal - -## Context - -## Constraints - -## Assumptions - -## Existing Evidence - -## Evidence Gaps - -## Validation Needed - -## Risk Assessment - -## Open Questions - -## Recommendation - -## Decision - -Allowed values: `feasible`, `feasible-with-risks`, `not-feasible`, `inconclusive`. diff --git a/extensions/discovery/templates/interface-contract.md b/extensions/discovery/templates/interface-contract.md new file mode 100644 index 0000000000..ed617b5c35 --- /dev/null +++ b/extensions/discovery/templates/interface-contract.md @@ -0,0 +1,114 @@ +# Verified Interface Contract + +## Source Intake + +| Source ID | File | Section or lines | Contract relevance | Evidence status | +|---|---|---|---|---| + +Evidence status values: `source-backed`, `repo-backed`, `validated`, `assumption`, or `unknown`. + +## Candidate Interface Designs + +| Candidate interface design | Classification | Actors or systems | Trigger | Input data | Output data | Constraint or risk | Source refs | +|---|---|---|---|---|---|---|---| + +Classification values: `required`, `optional`, or `unclear`. + +Selection rule: choose from `required` candidates first. The selected candidate must have a source-backed input/output boundary, the highest implementation risk, and validation evidence that would change formal planning. If no `required` candidate exists, record `AMBIGUOUS_CAPABILITY` and ask one concise clarifying question instead of selecting an optional candidate by default. If candidates tie, select the one with the strongest source emphasis and record `AMBIGUOUS_CAPABILITY` for the others. + +## Key Interface Design Under Validation + +State the selected interface design and why it is the key design to validate before implementation. + +| Field | Value | Evidence | Source refs | +|---|---|---|---| +| Interface name | | | | +| Boundary | | | | +| Direction | | | | +| Transport or invocation style | | | | +| Caller or producer | | | | +| Callee or consumer | | | | +| Primary operation | | | | +| Why this design is key | | | | + +## Design Validation Route + +Include only choices that change the selected interface design, validation feasibility, or contract risk. Do not create a general technology matrix. + +| Option | Fit for selected design | Evidence | Route status | +|---|---|---|---| + +Route status values: `used`, `rejected`, `needs-validation`, or `unknown`. + +Selected validation route: + +Rationale: + +Rejected validation routes: + +## Contract Definition + +### Operation + +| Field | Value | Evidence | +|---|---|---| +| Method, topic, command, or function | | | +| Path, channel, queue, or entry point | | | +| Sync or async behavior | | | +| Auth or trust boundary | | | +| Idempotency or retry behavior | | | +| Timeout, rate, or size constraints | | | +| Versioning or compatibility rule | | | +| Observability expectations | | | + +### Request Or Event Payload + +| Field | Type | Required | Meaning | Evidence | Validation notes | +|---|---|---|---|---|---| + +### Response, Result, Or Emitted Event + +| Field | Type | Required | Meaning | Evidence | Validation notes | +|---|---|---|---|---|---| + +### Errors And Edge Cases + +| Code or condition | Trigger | Contract behavior | Evidence | Validation notes | +|---|---|---|---|---| + +## Validation Evidence + +Validation question: + +Hypothesis: + +Scope: selected interface design feasibility only. Do not summarize an unrelated PoC, benchmark, prototype, or implementation plan. + +Persistence rule: evidence must come from source refs, existing commands, existing tests, read-only probes, or temporary snippets. Do not reference generated validation files. + +| Check | Method | Command or evidence ref | Result | Notes | +|---|---|---|---|---| + +Result values: `passed`, `failed`, `blocked`, or `inconclusive`. + +## Blockers And Gaps + +| Code | Gap or blocker | Impact on contract | Required resolution | +|---|---|---|---| + +Suggested blocker codes: `MISSING_SOURCE_DOC`, `AMBIGUOUS_CAPABILITY`, `UNSUPPORTED_FIELD`, `BLOCKED_PRECONDITION`, `VALIDATION_FAILED`, `RUNTIME_DEPENDENT`, `EXTERNAL_CLARIFICATION_NEEDED`. + +## Contract Handoff + +| Item | Value | +|---|---| +| Contract status | | +| Ready for formal planning | | +| Unresolved validation gaps | | +| Persistent artifact | `interface-contract.md` | +| Commands run | | +| Workspace cleanliness check | | + +Contract Status allowed values: `validated`, `validated-with-risks`, `blocked`, or `inconclusive`. + +Status gate: `validated` requires all required selected-design fields to be `source-backed`, `repo-backed`, or `validated`, all required source refs present, and no unresolved blocker codes. `validated-with-risks` allows bounded assumptions but no `unknown` required fields; risk acceptance must come from the user or source docs, while repository evidence may only bound the risk. `blocked` applies when source docs, input/output boundary, required fields, validation preconditions, blocker resolution, or workspace cleanliness checks fail. `inconclusive` applies only when available evidence is mixed, contradictory, runtime-dependent, or insufficient after allowed validation. diff --git a/extensions/discovery/templates/legacy-codebase-risk-assessment.md b/extensions/discovery/templates/legacy-codebase-risk-assessment.md deleted file mode 100644 index ee174b95fd..0000000000 --- a/extensions/discovery/templates/legacy-codebase-risk-assessment.md +++ /dev/null @@ -1,87 +0,0 @@ -# Legacy Codebase Risk Assessment - -## Scope - -## Input Targets - -| ID | Input claim or concern | Verification question | Source hints | Status | -|---|---|---|---|---| - -Status values: `confirmed`, `partially-confirmed`, `not-found`, `runtime-dependent`, or `unknown`. - -## Scope Candidates - -Use this section when the target area is ambiguous. - -| Rank | Candidate area | Confidence | Evidence | Unknowns | -|---:|---|---|---|---| - -Confidence values: `high`, `medium`, `low`, or `unknown`. - -## Evidence Capabilities - -| Capability | Available evidence | Limitations | -|---|---|---| - -## Codebase Map - -## Source Facts - -### Entrances - -| Type | Trigger or route | Handler or source area | Evidence | Confidence | -|---|---|---|---|---| - -### Module Boundaries - -| Module or area | Responsibility | Upstream | Downstream | Evidence | Confidence | -|---|---|---|---|---|---| - -### Dependency Edges - -| Kind | Source | Target | Evidence | Confidence | -|---|---|---|---|---| - -### Data Access - -| Data or state | Operation | Access point | Evidence | Confidence | -|---|---|---|---|---| - -### External Dependencies - -| Dependency | Call point | Protocol or method | Failure handling | Evidence | -|---|---|---|---|---| - -## Reusable Assets - -## Risks - -Rate each risk as `low`, `medium`, `high`, or `unknown`. - -| Risk | Rating | Source facts | Impact | Mitigation or follow-up | -|---|---|---|---|---| - -## Test Coverage - -## Integration Notes - -## Migration Notes - -## Source Boundary Notes - -| Boundary | Source-visible fact | Not proven | Downstream suggestion | -|---|---|---|---| - -## Recommendations - -## Evidence Gaps - -| Gap | Why it remains unknown | Evidence needed | -|---|---|---| - -## Evidence Index - -| Claim | Evidence | Confidence | -|---|---|---| - -## Follow-up Validation diff --git a/extensions/discovery/templates/performance-discovery.md b/extensions/discovery/templates/performance-discovery.md deleted file mode 100644 index a6adf54c0b..0000000000 --- a/extensions/discovery/templates/performance-discovery.md +++ /dev/null @@ -1,37 +0,0 @@ -# Performance Discovery - -## Decision Question - -## Evaluation Mode - -Allowed values: `comparison`, `single-approach-readiness`. - -## Scenario Context - -## Success Criteria - -## Candidate Approaches - -## Target Flow - -## Workload Assumptions - -## Repository Findings - -## Current Evidence - -## Bottleneck Hypotheses - -## Measurement Plan - -## Evidence Gaps - -## Follow-up Validation Decision - -## Scenario Risks - -## Recommendation - -## Planning Decision - -Allowed values: `ready-for-planning`, `needs-benchmark`, `needs-design-change`, `not-feasible`, `inconclusive`. diff --git a/extensions/discovery/templates/poc-plan.md b/extensions/discovery/templates/poc-plan.md deleted file mode 100644 index cc6ed1fe72..0000000000 --- a/extensions/discovery/templates/poc-plan.md +++ /dev/null @@ -1,21 +0,0 @@ -# Proof of Concept - -## Input - -## Validation Question - -## Hypothesis - -Use: `We believe [approach] will satisfy [requirement] under [constraint]. We will know this is true when [observable evidence].` - -## Success Criteria - -## Minimal Executable Experiment - -## Execution Preconditions - -## Sample Inputs - -## Expected Observations - -## Risk Focus diff --git a/extensions/discovery/templates/poc-result.md b/extensions/discovery/templates/poc-result.md deleted file mode 100644 index d904af92ad..0000000000 --- a/extensions/discovery/templates/poc-result.md +++ /dev/null @@ -1,15 +0,0 @@ -# POC Result - -## Experiment Run - -## Evidence - -## Observations - -## Blocking Conditions - -## Conclusion - -## Result - -Allowed values: `passed`, `failed`, `inconclusive`. diff --git a/extensions/discovery/templates/tech-selection-matrix.md b/extensions/discovery/templates/tech-selection-matrix.md deleted file mode 100644 index 15b75fec57..0000000000 --- a/extensions/discovery/templates/tech-selection-matrix.md +++ /dev/null @@ -1,25 +0,0 @@ -# Technology Selection Matrix - -## Decision - -## Evaluation Mode - -Allowed values: `comparison`, `single-approach-readiness`. - -## Candidates - -## Criteria - -## Matrix - -Use one row per candidate and one evidence-backed rating per criterion. - -## Trade-offs - -## Risks - -## Recommendation - -## Evidence Gaps - -## Follow-up Validation diff --git a/extensions/discovery/templates/ux-discovery.md b/extensions/discovery/templates/ux-discovery.md deleted file mode 100644 index 904e69e273..0000000000 --- a/extensions/discovery/templates/ux-discovery.md +++ /dev/null @@ -1,37 +0,0 @@ -# UX Discovery - -## Decision Question - -## Evaluation Mode - -Allowed values: `comparison`, `single-approach-readiness`. - -## Scenario Context - -## Success Criteria - -## Candidate Approaches - -## User Scenarios - -## States and Transitions - -## Edge Cases - -## Accessibility and Responsiveness - -## Repository Findings - -## Assumptions - -## Scenario Risks - -## Evidence Gaps - -## Validation Plan - -## Recommendation - -## Planning Decision - -Allowed values: `ready-for-planning`, `needs-prototype`, `needs-contract-clarification`, `not-recommended`, `inconclusive`. From b37c28d799d529d43f19942c74556f1e53d77e65 Mon Sep 17 00:00:00 2001 From: bigsmartben <30429295+bigsmartben@users.noreply.github.com> Date: Mon, 6 Jul 2026 14:35:42 +0800 Subject: [PATCH 2/2] Use canonical discovery command name Assisted-by: OpenAI Codex (model: GPT-5, autonomous) --- .github/workflows/community-smoke.yml | 9 ++++----- extensions/discovery/CATALOG-SUBMISSION.md | 4 ++-- extensions/discovery/CHANGELOG.md | 2 +- extensions/discovery/README.md | 6 +++--- extensions/discovery/commands/discovery.md | 2 +- extensions/discovery/docs/usage.md | 8 ++++---- extensions/discovery/extension.yml | 2 +- tests/integrations/community_defaults.py | 7 +------ tests/test_presets.py | 4 ++-- 9 files changed, 19 insertions(+), 25 deletions(-) diff --git a/.github/workflows/community-smoke.yml b/.github/workflows/community-smoke.yml index 06720d89e6..9dfe27d3bf 100644 --- a/.github/workflows/community-smoke.yml +++ b/.github/workflows/community-smoke.yml @@ -116,7 +116,7 @@ jobs: speckit-preview-high-html; do test -f ".claude/skills/$preview_skill/SKILL.md" done - test -f .claude/skills/speckit-discovery-feasibility/SKILL.md + test -f .claude/skills/speckit-discovery-contract/SKILL.md test -f .claude/skills/speckit-intake-visual-design/SKILL.md test -f .claude/skills/speckit-intake-prd/SKILL.md test -f .claude/skills/speckit-intake-test-cases/SKILL.md @@ -190,8 +190,8 @@ jobs: done ;; discovery) - test -f .claude/skills/speckit-discovery-feasibility/SKILL.md - grep -q "evidence-backed feasibility study" .claude/skills/speckit-discovery-feasibility/SKILL.md + test -f .claude/skills/speckit-discovery-contract/SKILL.md + grep -q "interface-contract discovery facilitator" .claude/skills/speckit-discovery-contract/SKILL.md ;; intake) test -f .claude/skills/speckit-intake-visual-design/SKILL.md @@ -208,8 +208,7 @@ jobs: /tmp/specify-community-smoke-venv/bin/specify extension remove discovery --force /tmp/specify-community-smoke-venv/bin/specify extension add discovery - test -f .claude/skills/speckit-discovery-feasibility/SKILL.md - test -f .claude/skills/speckit-discovery-decision/SKILL.md + test -f .claude/skills/speckit-discovery-contract/SKILL.md /tmp/specify-community-smoke-venv/bin/specify preset resolve plan-template | tee resolve-plan-template.txt grep -q "workflow-preset" resolve-plan-template.txt diff --git a/extensions/discovery/CATALOG-SUBMISSION.md b/extensions/discovery/CATALOG-SUBMISSION.md index 9841c70261..d72971aa74 100644 --- a/extensions/discovery/CATALOG-SUBMISSION.md +++ b/extensions/discovery/CATALOG-SUBMISSION.md @@ -17,7 +17,7 @@ Tags: discovery, interface-contract, api, event, webhook, technical-validation, ## Key Features -- Adds `/speckit.discovery` as the single public discovery command. +- Adds `/speckit.discovery.contract` as the single public discovery command. - Extracts candidate interface designs from `uc.md`, `spec.md`, or `arch.md`. - Selects the key source-backed interface design to validate before formal development. - Produces one persistent artifact: `interface-contract.md`. @@ -27,7 +27,7 @@ Tags: discovery, interface-contract, api, event, webhook, technical-validation, - Confirmed source `commands/` contains only `discovery.md`. - Confirmed source `templates/` contains only `interface-contract.md`. -- Confirmed source `extension.yml` registers `speckit.discovery` with `commands/discovery.md`. +- Confirmed source `extension.yml` registers `speckit.discovery.contract` with `commands/discovery.md`. - Checked old command/template naming residuals with `rg`; no matches. - Ran `git diff --check`; passed. - Checked Markdown/YAML trailing whitespace with `rg`; no matches. diff --git a/extensions/discovery/CHANGELOG.md b/extensions/discovery/CHANGELOG.md index de8e274ead..13f5ef03a6 100644 --- a/extensions/discovery/CHANGELOG.md +++ b/extensions/discovery/CHANGELOG.md @@ -5,7 +5,7 @@ ### Changed - Refocused the extension on pre-development interface feasibility validation. -- Replaced the broad six-command discovery surface with `/speckit.discovery`. +- Replaced the broad six-command discovery surface with `/speckit.discovery.contract`. - Added `templates/interface-contract.md` as the core verified interface contract artifact. - Updated documentation and manifest metadata to describe key interface design discovery from `uc.md`, `spec.md`, or `arch.md`, selected-design validation, and non-persistent validation evidence. - Tightened the workflow so `interface-contract.md` is the only persistent output artifact. diff --git a/extensions/discovery/README.md b/extensions/discovery/README.md index b618ae69ea..f2d7d86974 100644 --- a/extensions/discovery/README.md +++ b/extensions/discovery/README.md @@ -3,7 +3,7 @@ `spec-kit-discovery` provides a focused `discovery` extension for one pre-development job: find the key interface design implied by `uc.md`, `spec.md`, or `arch.md`, validate that design, then produce one verified interface contract artifact. ```text -/speckit.discovery [source docs or feature scope] [interface design focus] [constraints] +/speckit.discovery.contract [source docs or feature scope] [interface design focus] [constraints] ``` Use it before `/speckit.specify`, `/speckit.plan`, or implementation work when the main uncertainty is an API, event, command, SDK method, webhook, batch job, or cross-system service boundary. @@ -43,7 +43,7 @@ After installation, restart or refresh your AI coding agent if the new command d ## Command -### `speckit.discovery` +### `speckit.discovery.contract` Finds the key interface design from the input material, validates feasibility with source refs, existing commands, existing tests, read-only probes, or temporary snippets, and renders `templates/interface-contract.md`. @@ -56,7 +56,7 @@ Minimum useful input: Example: ```text -/speckit.discovery Source: specs/payments/spec.md and specs/payments/arch.md. Focus: Stripe webhook ingestion contract. Constraints: idempotent retries, signature verification, no duplicate invoice updates. +/speckit.discovery.contract Source: specs/payments/spec.md and specs/payments/arch.md. Focus: Stripe webhook ingestion contract. Constraints: idempotent retries, signature verification, no duplicate invoice updates. ``` When source docs are not passed explicitly, the command looks for `uc.md`, `spec.md`, or `arch.md` in the active feature directory or repository. diff --git a/extensions/discovery/commands/discovery.md b/extensions/discovery/commands/discovery.md index 57b022313b..989ce2054a 100644 --- a/extensions/discovery/commands/discovery.md +++ b/extensions/discovery/commands/discovery.md @@ -1,5 +1,5 @@ --- -name: speckit.discovery +name: speckit.discovery.contract description: Identify the key interface design from uc.md, spec.md, or arch.md, validate that design with non-persistent evidence, and produce the single verified interface contract artifact. argument-hint: "[source docs or feature scope] [interface design focus] [constraints]" --- diff --git a/extensions/discovery/docs/usage.md b/extensions/discovery/docs/usage.md index 02772def03..c3537f0a66 100644 --- a/extensions/discovery/docs/usage.md +++ b/extensions/discovery/docs/usage.md @@ -4,7 +4,7 @@ Use the `discovery` extension before formal development when an interface bounda The extension provides one focused command: -- `/speckit.discovery`: finds the key interface design from `uc.md`, `spec.md`, or `arch.md`, validates that design with non-persistent evidence, and produces the single artifact `interface-contract.md`. +- `/speckit.discovery.contract`: finds the key interface design from `uc.md`, `spec.md`, or `arch.md`, validates that design with non-persistent evidence, and produces the single artifact `interface-contract.md`. ## When To Use It @@ -27,7 +27,7 @@ Good candidates include: ## Inputs ```text -/speckit.discovery [source docs or feature scope] [interface design focus] [constraints] +/speckit.discovery.contract [source docs or feature scope] [interface design focus] [constraints] ``` Source discovery order: @@ -41,7 +41,7 @@ If several interface designs are present, the command selects the highest-impact ## Example ```text -/speckit.discovery Source: features/invoice-sync/uc.md, features/invoice-sync/arch.md. Focus: invoice status update webhook. Constraints: idempotent retry handling, signed requests, p95 handler time below 200ms for synthetic payloads. +/speckit.discovery.contract Source: features/invoice-sync/uc.md, features/invoice-sync/arch.md. Focus: invoice status update webhook. Constraints: idempotent retry handling, signed requests, p95 handler time below 200ms for synthetic payloads. ``` Expected result: @@ -69,6 +69,6 @@ The command must not create separate PoC files, validation directories, logs, fi ## Recommended Flow 1. Draft or update `uc.md`, `spec.md`, or `arch.md`. -2. Run `/speckit.discovery` for the interface boundary with the highest implementation risk. +2. Run `/speckit.discovery.contract` for the interface boundary with the highest implementation risk. 3. Review `interface-contract.md`. 4. Continue to formal Spec Kit planning only when `Contract Status` is `validated` or `validated-with-risks` and remaining risks are accepted. diff --git a/extensions/discovery/extension.yml b/extensions/discovery/extension.yml index e4f76aafc3..e854e17728 100644 --- a/extensions/discovery/extension.yml +++ b/extensions/discovery/extension.yml @@ -19,7 +19,7 @@ requires: provides: commands: - - name: "speckit.discovery" + - name: "speckit.discovery.contract" file: "commands/discovery.md" description: "Finds the key interface design from uc.md, spec.md, or arch.md, validates that design with non-persistent evidence, and produces the single artifact interface-contract.md." diff --git a/tests/integrations/community_defaults.py b/tests/integrations/community_defaults.py index 8b49da1e1b..6b0d1d4596 100644 --- a/tests/integrations/community_defaults.py +++ b/tests/integrations/community_defaults.py @@ -23,12 +23,7 @@ "speckit.arch.process-reverse", "speckit.arch.development-reverse", "speckit.arch.physical-reverse", - "speckit.discovery.feasibility", - "speckit.discovery.techselect", - "speckit.discovery.codebase", - "speckit.discovery.codebase-api-imp", - "speckit.discovery.poc", - "speckit.discovery.decision", + "speckit.discovery.contract", "speckit.intake.visual-design", "speckit.intake.prd", "speckit.intake.test-cases", diff --git a/tests/test_presets.py b/tests/test_presets.py index d35f9361fe..73be077bb7 100644 --- a/tests/test_presets.py +++ b/tests/test_presets.py @@ -4789,7 +4789,7 @@ def test_community_smoke_checks_wheel_assets_and_extension_dev_reinstall(self): in verify_run ) assert ( - 'test -f .claude/skills/speckit-discovery-feasibility/SKILL.md' + 'test -f .claude/skills/speckit-discovery-contract/SKILL.md' in verify_run ) assert ( @@ -4802,7 +4802,7 @@ def test_community_smoke_checks_wheel_assets_and_extension_dev_reinstall(self): ) assert "specify extension add discovery" in verify_run assert ( - 'test -f .claude/skills/speckit-discovery-decision/SKILL.md' + 'test -f .claude/skills/speckit-discovery-contract/SKILL.md' in verify_run ) assert (