Skip to content

Commit e3b4fc6

Browse files
omgbwa-yasseomgbwa-yasse
committed
feat: add /speckit.ask command — grounded Q&A with workflow routing
1 parent 342b74e commit e3b4fc6

1 file changed

Lines changed: 157 additions & 0 deletions

File tree

‎templates/commands/ask.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
description: Answer any question about the current feature, project, or Spec Kit workflow — grounded in the constitution, existing specs, and best practices — and route to the right next command.
3+
handoffs:
4+
- label: Write a Spec
5+
agent: speckit.specify
6+
prompt: "Specify the following feature: "
7+
- label: Clarify the Spec
8+
agent: speckit.clarify
9+
prompt: Clarify the current spec
10+
send: true
11+
- label: Build a Plan
12+
agent: speckit.plan
13+
prompt: Create a plan for the spec
14+
send: true
15+
- label: Fix an Error
16+
agent: speckit.fix
17+
prompt: "Fix this error: "
18+
- label: Analyze Consistency
19+
agent: speckit.analyze
20+
prompt: Analyze the current feature artifacts
21+
send: true
22+
scripts:
23+
sh: scripts/bash/check-prerequisites.sh --json --paths-only
24+
ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly
25+
---
26+
27+
## User Input
28+
29+
```text
30+
$ARGUMENTS
31+
```
32+
33+
You **MUST** consider the user input before proceeding (if not empty). This may be any question: conceptual, technical, workflow-related, or about a specific feature.
34+
35+
---
36+
37+
## Goal
38+
39+
Answer questions about the current Spec Kit project with grounded, actionable responses — and route to the right command when further action is needed. You are a knowledgeable guide, not an executor. You read before you answer. You route before you act.
40+
41+
---
42+
43+
## Phase 0 — Classify the question
44+
45+
Before reading any file, classify the input into one of these categories (zero file I/O):
46+
47+
| Category | Examples | Files to read |
48+
|---|---|---|
49+
| **workflow** | "What command do I run next?", "What is the order of commands?" | none — answer from knowledge |
50+
| **spec** | "Does my spec cover X?", "Is this user story complete?" | `spec.md` (relevant section only) |
51+
| **plan** | "Is this architecture decision correct?", "Should I use X or Y?" | `plan.md` (relevant section only) |
52+
| **constitution** | "Does this violate a project principle?", "Is X allowed?" | `constitution.md` |
53+
| **error** | "Why is X failing?", "What is wrong with my code?" | redirect → `/speckit.fix` immediately |
54+
| **feature-gap** | "How do I add X?", "We need a new behavior" | redirect → `/speckit.specify` immediately |
55+
| **consistency** | "Are spec and plan aligned?", "Is tasks.md up to date?" | `spec.md` + `plan.md` + `tasks.md` |
56+
| **open** | General question not fitting above | `constitution.md` + closest artifact |
57+
58+
**Fast redirects (do not proceed past Phase 0):**
59+
- If the question describes a broken behavior or an error → output redirect block and stop:
60+
```
61+
→ This is a correction request, not a question.
62+
Run: /speckit.fix "[paste your error here]"
63+
```
64+
- If the question requests a new feature or behavior → output redirect block and stop:
65+
```
66+
→ This is a feature request, not a question.
67+
Run: /speckit.specify "[describe what you need]"
68+
```
69+
70+
---
71+
72+
## Phase 1 — Load context
73+
74+
Run `{SCRIPT}` from repo root only if the question category requires reading a project file (see table above). Parse `FEATURE_DIR` and `AVAILABLE_DOCS`.
75+
76+
Load only the files identified in Phase 0 — and only the sections relevant to the question. Do not load artifacts speculatively.
77+
78+
**Always read `constitution.md` when:**
79+
- The question touches a project principle, constraint, or architectural decision
80+
- The answer would suggest a change to an existing artifact
81+
- The question category is `constitution` or `consistency`
82+
83+
**Never read `constitution.md` proactively** for pure workflow questions.
84+
85+
---
86+
87+
## Phase 2 — Answer
88+
89+
Produce a structured response:
90+
91+
```
92+
QUESTION : [restate the question in one line]
93+
CATEGORY : [workflow | spec | plan | constitution | consistency | open]
94+
GROUNDED IN : [knowledge | constitution.md | spec.md | plan.md | tasks.md | multiple]
95+
CONFIDENCE : [high — answer is unambiguous | medium — interpretation required | low — insufficient context]
96+
97+
ANSWER
98+
──────
99+
[Direct, precise answer. Reference file:section when quoting a spec or plan.
100+
If CONFIDENCE = low, state clearly what additional context is needed and why.
101+
Do not hedge unnecessarily — if you know, say it directly.]
102+
```
103+
104+
### Rules for the answer
105+
106+
1. **Base every answer on evidence** — quote the relevant section of the artifact when possible.
107+
2. **Separate fact from recommendation** — clearly distinguish "the spec says X" from "best practice suggests Y".
108+
3. **Respect the constitution** — if the answer would conflict with a principle, say so explicitly. Do not suggest actions that violate it.
109+
4. **Acknowledge gaps honestly** — if the information needed to answer is absent from all artifacts, say so. Do not invent an answer.
110+
5. **One question at a time** — if the input contains multiple questions, answer them in order, each with its own block. Do not merge unrelated answers.
111+
112+
---
113+
114+
## Phase 3 — Route
115+
116+
After the answer, produce a routing suggestion based on what the question revealed:
117+
118+
```
119+
SUGGESTED NEXT
120+
──────────────
121+
[command] [reason — what this command would do given what was just answered]
122+
```
123+
124+
Use this routing table:
125+
126+
| What the answer revealed | Suggested command |
127+
|---|---|
128+
| The spec has a gap or ambiguity | `/speckit.clarify "[the unresolved point]"` |
129+
| A new behavior needs to be defined | `/speckit.specify "[what the system must do]"` |
130+
| A technical decision needs to be made or revisited | `/speckit.plan` |
131+
| Artifacts are inconsistent with each other | `/speckit.analyze` |
132+
| A task is missing or mis-ordered | `/speckit.tasks` |
133+
| An error or broken behavior was surfaced | `/speckit.fix "[the error]"` |
134+
| Everything looks correct | No action needed — state this explicitly |
135+
| Cross-feature impact is possible | `/speckit.analyze` (after the fix or change) |
136+
137+
**Multiple suggestions are allowed** — rank them by urgency (most blocking first).
138+
139+
**Never suggest a command without a reason.** Each suggestion must say *why* that command is warranted given the answer.
140+
141+
---
142+
143+
## Phase 4 — Confidence check
144+
145+
If `CONFIDENCE = low` was set in Phase 2, append:
146+
147+
```
148+
BEFORE PROCEEDING
149+
─────────────────
150+
To answer this confidently, I need:
151+
1. [specific missing piece — e.g., "the full stack trace", "the spec.md of feature X", "which architecture was chosen in plan.md"]
152+
2. [optional second missing piece]
153+
154+
You can provide this directly in the next message, or run the suggested command above to generate it.
155+
```
156+
157+
Do not ask more than 2 clarifying questions. Do not ask for information that can be inferred from the artifacts already loaded.

0 commit comments

Comments
 (0)