<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-03-09-1-prompts-do-not-discover-context-commands-do/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-03-09-1-prompts-do-not-discover-context-commands-do/</id>
  <title>Prompts Do Not Discover Context, Commands Do</title>
  <updated>2026-03-09T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-03-09-1-prompts-do-not-discover-context-commands-do/"/>
  <summary>Command-layer context resolution becomes canonical: prompt templates may no longer infer mission, work package, or base branch from cwd, branch name, or repo scans.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty currently has two overlapping execution models:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt;, which is runtime-driven and already knows mission state and feature context.&lt;/li&gt;
&lt;li&gt;Legacy slash commands (&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.tasks&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.implement&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.review&lt;/code&gt;, and related generated prompt files), which are static templates rendered once and then interpreted by an LLM at runtime.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This split has created context drift and contradictory behavior.&lt;/p&gt;
&lt;h3 id=&quot;observed-failures&quot;&gt;Observed failures&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.tasks&lt;/code&gt; in a multi-feature repository instructed the model to detect feature context from repo state, then called &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; without an explicit feature slug. The command correctly rejected the request with &lt;code dir=&quot;auto&quot;&gt;FEATURE_CONTEXT_UNRESOLVED&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.implement&lt;/code&gt; called &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent workflow implement&lt;/code&gt; without a resolved work package or base. The command auto-selected the first planned WP, then immediately failed because the selected WP had a dependency and required &lt;code dir=&quot;auto&quot;&gt;--base&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Review prompts instructed agents to approve a WP by moving it directly to &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, while the task command now treats &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; as a merge-verified state and blocks that transition until merge ancestry is confirmed.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;These failures are not random prompt mistakes. They are symptoms of an architectural mismatch:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Runtime-backed flows already know context.&lt;/li&gt;
&lt;li&gt;Static prompts do not.&lt;/li&gt;
&lt;li&gt;Prompt templates are compensating by asking the model to rediscover context from cwd, branch name, feature directories, and heuristics.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;That design is fragile in multi-feature repositories, dependency-heavy work package graphs, and workflows where review approval and merge completion are distinct states.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Deterministic agent behavior in multi-feature repositories.&lt;/li&gt;
&lt;li&gt;Single source of truth for feature, WP, dependency, and branch context.&lt;/li&gt;
&lt;li&gt;Elimination of prompt drift between &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and legacy slash-command flows.&lt;/li&gt;
&lt;li&gt;Better compatibility across agent hosts where generated prompt files are static.&lt;/li&gt;
&lt;li&gt;Testable action resolution without depending on LLM prompt interpretation.&lt;/li&gt;
&lt;li&gt;Clear separation between review approval state and merge/integration state.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-keep-prompt-level-discovery-as-is&quot;&gt;Option 1: Keep prompt-level discovery as-is&lt;/h3&gt;
&lt;p&gt;Legacy slash commands continue asking the model to inspect cwd, branch, repo contents, and command errors to infer what to do.&lt;/p&gt;
&lt;h3 id=&quot;option-2-add-richer-static-placeholder-injection-to-generated-slash-command-files&quot;&gt;Option 2: Add richer static placeholder injection to generated slash-command files&lt;/h3&gt;
&lt;p&gt;Extend prompt rendering with more placeholders such as &lt;code dir=&quot;auto&quot;&gt;{FEATURE_SLUG}&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;{WP_ID}&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;{TARGET_BRANCH}&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;{RESOLVED_BASE}&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;option-3-introduce-a-canonical-action-context-resolver-command-and-make-prompts-consume-it&quot;&gt;Option 3: Introduce a canonical action-context resolver command and make prompts consume it&lt;/h3&gt;
&lt;p&gt;Add a single command-level contract that resolves feature/WP/base/workspace/review context for each action. &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and legacy slash commands both use this resolver.&lt;/p&gt;
&lt;h3 id=&quot;option-4-deprecate-legacy-slash-commands-entirely-and-require-spec-kitty-next-for-all-agent-loops&quot;&gt;Option 4: Deprecate legacy slash commands entirely and require &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; for all agent loops&lt;/h3&gt;
&lt;p&gt;Make &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; the only supported agent loop and stop investing in direct slash-command execution.&lt;/p&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; Option 3, “Introduce a canonical action-context resolver command and make prompts consume it.”&lt;/p&gt;
&lt;h3 id=&quot;core-decision&quot;&gt;Core decision&lt;/h3&gt;
&lt;p&gt;Prompts do not discover context. Commands do.&lt;/p&gt;
&lt;p&gt;This means:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Prompt templates MUST NOT ask the model to infer feature context from current branch, cwd, or repository scans when command-layer context can be resolved directly.&lt;/li&gt;
&lt;li&gt;Prompt templates MUST treat command JSON output as canonical execution context.&lt;/li&gt;
&lt;li&gt;Legacy slash commands remain supported, but they become thin wrappers around command-owned context resolution instead of free-form workflow guides.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; remains the canonical mission loop, but it MUST share the same context-resolution backend as legacy slash commands.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;canonical-contract&quot;&gt;Canonical contract&lt;/h3&gt;
&lt;p&gt;Spec Kitty SHALL expose a single action-context resolver command, for example:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;context&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;resolve&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--action&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;tasks&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;tasks_finalize&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;implement&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;review&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;accept&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;merge&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The resolver SHALL return, as applicable:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;feature_slug&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_key&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;wp_id&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;wp_file&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;dependencies&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;resolved_base&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;workspace_path&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;exact_command&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;blocked_reason&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;remediation&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;If ambiguity remains after command-owned resolution, the command SHALL return structured remediation or a decision-required response. The prompt MUST NOT be responsible for inventing the missing context.&lt;/p&gt;
&lt;h3 id=&quot;state-model-decision&quot;&gt;State-model decision&lt;/h3&gt;
&lt;p&gt;Review approval and merge completion SHALL be treated as separate concepts.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; SHALL mean merge/integration-complete, not merely “review passed”. Review approval SHALL be represented separately, either by:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;an explicit &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; lane, or&lt;/li&gt;
&lt;li&gt;an equivalent gate-backed intermediate state that is not conflated with &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The current model, where prompts instruct “approve by moving to done” while the command guard interprets &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; as merge-verified, is explicitly rejected.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;No prompt-level feature discovery in multi-feature repositories.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and legacy slash commands use the same context rules and exact commands.&lt;/li&gt;
&lt;li&gt;Implement flows stop failing immediately after auto-selecting a dependent WP without a base.&lt;/li&gt;
&lt;li&gt;Review prompts stop instructing actions that command guards forbid.&lt;/li&gt;
&lt;li&gt;Action selection becomes unit-testable and integration-testable without relying on LLM interpretation.&lt;/li&gt;
&lt;li&gt;Generated prompt files remain simple and portable across agent hosts.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Requires a non-trivial refactor across prompt templates, runtime bridge code, and workflow commands.&lt;/li&gt;
&lt;li&gt;Introduces a new context-resolution surface that must be maintained as a stable JSON contract.&lt;/li&gt;
&lt;li&gt;Requires migration of existing slash-command templates and likely regeneration of prompt files in downstream repos.&lt;/li&gt;
&lt;li&gt;May require a lane/state migration if &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; is introduced explicitly.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Existing simple placeholders such as &lt;code dir=&quot;auto&quot;&gt;{ARGS}&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;{SCRIPT}&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;{AGENT_SCRIPT}&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;__AGENT__&lt;/code&gt; can remain for static generation.&lt;/li&gt;
&lt;li&gt;Legacy slash commands can remain available during migration, but they are no longer allowed to own workflow discovery logic.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; remains the preferred top-level loop for long-lived agent execution.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;rejected-approaches&quot;&gt;Rejected Approaches&lt;/h2&gt;
&lt;h3 id=&quot;static-placeholder-expansion-as-the-primary-fix&quot;&gt;Static placeholder expansion as the primary fix&lt;/h3&gt;
&lt;p&gt;Adding more static placeholders to rendered command files does not solve the core problem. Generated slash-command files are created before runtime action context is known. They cannot safely encode live feature/WP/base choices in repositories with multiple active features and evolving task graphs.&lt;/p&gt;
&lt;h3 id=&quot;prompt-heuristics-plus-better-wording&quot;&gt;Prompt heuristics plus better wording&lt;/h3&gt;
&lt;p&gt;Improving prompt instructions without moving context resolution into commands would reduce some failures, but it would still leave action correctness dependent on LLM reasoning over repo state, command errors, and conventions. That is not a stable execution model.&lt;/p&gt;
&lt;h3 id=&quot;redefining-done-to-mean-both-approved-and-merged&quot;&gt;Redefining &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; to mean both approved and merged&lt;/h3&gt;
&lt;p&gt;One lane should not carry both review approval and merge ancestry semantics. That conflation is the source of the current review/done contradiction.&lt;/p&gt;
&lt;h2 id=&quot;migration-plan&quot;&gt;Migration Plan&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Add a shared context-resolution module in CLI core and expose it through &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent context resolve&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Route &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; action planning and prompt generation through the shared resolver wherever action context is needed.&lt;/li&gt;
&lt;li&gt;Update software-dev command templates for &lt;code dir=&quot;auto&quot;&gt;tasks&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks-outline&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks-packages&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks-finalize&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt; to call the resolver first and use its JSON output as canonical.&lt;/li&gt;
&lt;li&gt;Unify top-level &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent workflow implement&lt;/code&gt; so single-parent dependency handling is identical.&lt;/li&gt;
&lt;li&gt;Introduce an explicit review-approved state that is distinct from &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, then update prompts, lane logic, and mission guards accordingly.&lt;/li&gt;
&lt;li&gt;Add migrations for generated prompt files and any lane/state transition docs affected by the new contract.&lt;/li&gt;
&lt;li&gt;Add regression tests proving that &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and legacy slash-command flows resolve identical context for the same repository state.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;verification&quot;&gt;Verification&lt;/h2&gt;
&lt;p&gt;This ADR will be considered implemented when all of the following are true:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;No software-dev slash command instructs agents to detect feature context from branch or cwd.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tasks-finalize&lt;/code&gt; is always invoked with canonical feature context.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; resolves a safe base strategy before presenting the execution command.&lt;/li&gt;
&lt;li&gt;Review prompts do not instruct direct &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; transitions that violate merge ancestry guards.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; transitions reflect merge-complete state, not just review approval.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; and legacy slash-command execution resolve the same &lt;code dir=&quot;auto&quot;&gt;feature_slug&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;wp_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;resolved_base&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;workspace_path&lt;/code&gt; for the same repository state.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;related-adrs&quot;&gt;Related ADRs&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/2.x/2026-02-17-1-canonical-next-command-runtime-loop/&quot;&gt;2026-02-17-1-canonical-next-command-runtime-loop.md&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/2.x/2026-02-17-2-runtime-owned-mission-discovery-loading/&quot;&gt;2026-02-17-2-runtime-owned-mission-discovery-loading.md&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;Key current seams this ADR is intended to remove:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Static slash-command rendering only injects a small fixed placeholder set.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; already has runtime-owned feature context.&lt;/li&gt;
&lt;li&gt;Legacy prompt templates still contain branch/cwd/context rediscovery instructions.&lt;/li&gt;
&lt;li&gt;Review prompts and &lt;code dir=&quot;auto&quot;&gt;move-task --to done&lt;/code&gt; guards currently disagree on what &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; means.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
