Skip to content

ask.md

Latest commit

 

History

History
158 lines (115 loc) · 7.56 KB

ask.md

File metadata and controls

158 lines (115 loc) · 7.56 KB
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.
handoffs
label agent prompt
Fix an Error
speckit.fix
Fix this error:
label agent prompt
Write a Spec
speckit.specify
Specify the following feature:
scripts
sh ps
scripts/bash/check-prerequisites.sh --json --paths-only
scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly

User Input

$ARGUMENTS

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.

Goal

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.

Phase 0 — Classify the question

Before reading any file, classify the input into one of these categories (zero file I/O):

Category Examples Files to read Format
simple "Reformulate this", "Give me a prompt for X", "What command do I run next?", "Explain Y in simple terms", "What is the order of commands?" none — answer from knowledge plain reply, no structured block, skip Phase 3
spec "Does my spec cover X?", "Is this user story complete?" spec.md (relevant section only) structured block
plan "Is this architecture decision correct?", "Should I use X or Y?" plan.md (relevant section only) structured block
constitution "Does this violate a project principle?", "Is X allowed?" constitution.md structured block
error "Why is X failing?", "What is wrong with my code?" redirect → /speckit.fix immediately redirect only
feature-gap "How do I add X?", "We need a new behavior" redirect → /speckit.specify immediately redirect only
consistency "Are spec and plan aligned?", "Is tasks.md up to date?" spec.md + plan.md + tasks.md structured block
open General question not fitting above constitution.md only structured block

If category = simple: answer immediately with no structured header block (no QUESTION/CATEGORY/GROUNDED IN/CONFIDENCE labels), no Phase 1 file loading, and no Phase 3 routing. The reply is the answer itself — nothing more.

Fast redirects (do not proceed past Phase 0):

  • If the question describes a broken behavior or an error → output redirect block and stop: 
    → This is a correction request, not a question.
  Run: /speckit.fix "[paste your error here]"
  • If the question requests a new feature or behavior → output redirect block and stop: 
    → This is a feature request, not a question.
  Run: /speckit.specify "[describe what you need]"

Phase 1 — Load context

Run {SCRIPT} from repo root only if the question category requires reading a project file (see table above). Parse FEATURE_DIR and AVAILABLE_DOCS.

Load only the files identified in Phase 0 — and only the sections relevant to the question. Do not load artifacts speculatively.

Always read constitution.md when:

  • The question touches a project principle, constraint, or architectural decision
  • The answer would suggest a change to an existing artifact
  • The question category is constitution or consistency

Never read constitution.md proactively for pure workflow questions.

For category open: load constitution.md only. Load additional artifacts only if constitution.md content explicitly points to them. Do not guess which artifact is "closest".

Phase 2 — Answer

If category = simple (set in Phase 0): skip this entire phase. Do not produce the structured block below. Write the answer directly as plain text and stop — do not proceed to Phase 3 or Phase 4.

For all other categories, produce a structured response:

QUESTION     : [restate the question in one line]
CATEGORY     : [spec | plan | constitution | consistency | open]
GROUNDED IN  : [knowledge | constitution.md | spec.md | plan.md | tasks.md | multiple]
CONFIDENCE   : [high — answer is unambiguous | medium — interpretation required | low — insufficient context]

ANSWER
──────
[Direct, precise answer. Reference file:section when quoting a spec or plan.
 If CONFIDENCE = low, state clearly what additional context is needed and why.
 Do not hedge unnecessarily — if you know, say it directly.]

Rules for the answer

  1. Base every answer on evidence — quote the relevant section of the artifact when possible.
  2. Separate fact from recommendation — clearly distinguish "the spec says X" from "best practice suggests Y".
  3. Respect the constitution — if the answer would conflict with a principle, say so explicitly. Do not suggest actions that violate it.
  4. Acknowledge gaps honestly — if the information needed to answer is absent from all artifacts, say so. Do not invent an answer.
  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.

Phase 3 — Route (conditional)

Only produce a routing suggestion if the answer explicitly reveals an actionable gap, inconsistency, or next step. If the question was self-contained (a reformulation, a direct factual answer, a generated prompt, an explanation), skip Phase 3 entirely — do not output a "SUGGESTED NEXT" block.

Ask yourself: "Did my answer uncover something that requires a follow-up command?" If no, stop after Phase 2.

If routing is warranted, output:

SUGGESTED NEXT
──────────────
[command]   [reason — what this command would do given what was just answered]

Use this routing table only when the answer reveals one of these conditions:

What the answer revealed Suggested command
The spec has a gap or ambiguity /speckit.clarify "[the unresolved point]"
A new behavior needs to be defined /speckit.specify "[what the system must do]"
A technical decision needs to be made or revisited /speckit.plan
Artifacts are inconsistent with each other /speckit.analyze
A task is missing or mis-ordered /speckit.tasks
An error or broken behavior was surfaced /speckit.fix "[the error]"
Tasks are ready to execute /speckit.implement
Edge cases should be tracked as issues /speckit.taskstoissues
Cross-feature impact is possible /speckit.analyze (after the fix or change)

Never suggest a command for a question that was fully answered. A complete, self-contained answer requires no routing.

Never suggest a command without a reason. Each suggestion must say why that command is warranted given the answer.

Phase 4 — Confidence check

If CONFIDENCE = low was set in Phase 2:

  • Suppress Phase 3 entirely — do not output any SUGGESTED NEXT block. Missing context must be resolved before a command can be meaningfully suggested.
  • Append:
BEFORE PROCEEDING
─────────────────
To answer this confidently, I need:
  1. [specific missing piece — e.g., "the full stack trace", "the spec.md of feature X", "which architecture was chosen in plan.md"]
  2. [optional second missing piece]

Provide this directly in your next message.

Do not ask more than 2 clarifying questions. Do not ask for information that can be inferred from the artifacts already loaded.