Spec Kit: from testable intent to traceable acceptance
Read Spec Kit prerequisite and resolver entry points: paths are not validation
Follow early exits, required-artifact flags, optional document output and delegated resolution without attributing behavior to code that was not inspected.
What you will learn
- Trace the PowerShell path-only branch first
- Follow validation and inclusion flags independently
- The Python resolver is an adapter, not the whole engine
Before you start
- Basic requirements, Git and testing concepts
- Understanding of local development versus application deployment
Trace a small feature from intent to evidence and distinguish workflow contracts from verified behavior.
Key takeaways
- -PathsOnly returns locations without prerequisite validation.
- Requiring tasks and listing tasks are separate flags.
- An adapter’s source does not prove its imported engine’s full behavior.
Trace the PowerShell path-only branch first
check-prerequisites.ps1 imports common.ps1 and obtains feature paths. In -PathsOnly mode it calls Get-FeaturePathsEnv with -NoPersist, emits path variables and exits before checking required files. The source comment explains that this avoids the feature.json persistence side effect during pure path resolution.
Consequently, a successful path-only response does not prove that the feature directory, plan, spec or tasks exist. Outside that mode, the helper calls the normal path resolver. We inspected this entry point, not the complete imported helper, so we do not claim a full inventory of filesystem effects.
Follow validation and inclusion flags independently
Normal validation checks the feature directory and plan.md, then checks spec.md and tasks.md when -RequireSpec and -RequireTasks are set. -IncludeTasks controls whether an existing tasks file appears in AVAILABLE_DOCS; listing a document and requiring it are separate decisions. Missing required inputs produce an error and nonzero exit.
The helper also lists available optional research, data-model, contracts and quickstart artifacts. With -Template it asks a helper for resolved template content and fails if none is available. Reading a list of available documents cannot substitute for assessing their contents, completeness or consistency.
The Python resolver is an adapter, not the whole engine
resolve_template.py parses a template name and optional --json flag, determines the repository root and calls resolve_template_content. It catches TemplateResolutionError and returns failure; a None result also fails. Successful JSON contains TEMPLATE_NAME and TEMPLATE_CONTENT, preserving non-ASCII text through ensure_ascii=False.
The plain-output branch writes the returned content directly. These details help distinguish missing templates from successful output and explain multilingual JSON, but they do not establish every override rule or security property of common.py. No upstream PowerShell or Python execution was performed; the tested companion is a separate append-contract model.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Read early exits before interpreting a success code.
- 2
Trace required-file checks and optional output separately.
- 3
Identify imported behavior that needs further inspection.
- 4
Keep source observation separate from runtime proof.
Copy-ready example
{
"sourceTrace": true,
"pathsOnly": {
"validatesArtifacts": false,
"requestsNoPersist": true
},
"requireTasks": "existence check",
"includeTasks": "output inclusion",
"upstreamExecuted": false
}Frequently asked questions
Does -PathsOnly prove that plan.md exists?
No. It exits before required-file validation.
Does successful JSON prove the specification is complete?
No. It reports paths, available documents or resolved content, not semantic correctness.
Sources
- Spec Kit / scripts/powershell/check-prerequisites.ps1Source checked 2026-09-14
- Spec Kit / scripts/python/resolve_template.pySource checked 2026-09-14
- Spec Kit / templates/commands/analyze.mdSource checked 2026-09-14