<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-03-20-1-remove-clarify-slash-command/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-03-20-1-remove-clarify-slash-command/</id>
  <title>Remove the Clarify Slash Command</title>
  <updated>2026-03-20T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-03-20-1-remove-clarify-slash-command/"/>
  <summary>Deletes the clarify slash command outright and ships a destructive upgrade migration, folding its value back into stronger specification work up front.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.clarify&lt;/code&gt; currently exists as a distinct public workflow step and as a
generated prompt file across every supported agent directory. That command adds
product surface area, docs, upgrade complexity, and dedicated maintenance code.
At the same time, its value is not meaningfully distinct from stronger
specification work inside &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; and the direct transition into
&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.plan&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;We want the command gone completely. That means removing it from packaged
templates, generated agent prompts, project-local &lt;code dir=&quot;auto&quot;&gt;.kittify&lt;/code&gt; copies, and
current product documentation. Existing initialized projects also need an
upgrade path that deletes stale prompt files rather than leaving them behind.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Reduce the public slash-command surface area.&lt;/li&gt;
&lt;li&gt;Simplify the default workflow from &lt;code dir=&quot;auto&quot;&gt;specify -&gt; plan&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Eliminate clarify-specific maintenance code and migration repair logic.&lt;/li&gt;
&lt;li&gt;Prevent stale generated prompt files from surviving upgrades.&lt;/li&gt;
&lt;li&gt;Keep current product documentation aligned with the shipped command set.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Option 1: Keep &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.clarify&lt;/code&gt; as-is&lt;/li&gt;
&lt;li&gt;Option 2: Deprecate &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.clarify&lt;/code&gt; first, then remove it later&lt;/li&gt;
&lt;li&gt;Option 3: Remove &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.clarify&lt;/code&gt; immediately with a destructive upgrade migration&lt;/li&gt;
&lt;/ul&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: Remove &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.clarify&lt;/code&gt; immediately with a destructive upgrade migration”, because it satisfies the goal of making the command disappear completely while keeping existing projects clean after upgrade.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The public workflow becomes simpler and easier to teach.&lt;/li&gt;
&lt;li&gt;Spec Kitty ships one fewer slash command across every supported agent.&lt;/li&gt;
&lt;li&gt;Upgrade logic stops repairing a command we no longer want.&lt;/li&gt;
&lt;li&gt;Current docs, examples, and init output become easier to keep consistent.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Existing users lose a named clarification phase.&lt;/li&gt;
&lt;li&gt;Upgrade must delete already-generated prompt files and project-local templates.&lt;/li&gt;
&lt;li&gt;Users who relied on the old command must move that behavior into stronger spec review before planning.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Historical records such as changelog entries and archived &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; artifacts remain unchanged.&lt;/li&gt;
&lt;li&gt;Clarification still happens as part of specification quality work, but not as a dedicated slash command.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We will validate this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Ensuring fresh &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; output and generated agent prompts contain no &lt;code dir=&quot;auto&quot;&gt;clarify&lt;/code&gt; command.&lt;/li&gt;
&lt;li&gt;Ensuring &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; deletes stale &lt;code dir=&quot;auto&quot;&gt;spec-kitty.clarify.*&lt;/code&gt; prompt files and &lt;code dir=&quot;auto&quot;&gt;.kittify&lt;/code&gt; template copies from existing projects.&lt;/li&gt;
&lt;li&gt;Ensuring current product docs and examples describe a 13-command surface and a direct &lt;code dir=&quot;auto&quot;&gt;specify -&gt; plan&lt;/code&gt; flow.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-keep-spec-kittyclarify-as-is&quot;&gt;Option 1: Keep &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.clarify&lt;/code&gt; as-is&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No migration work required&lt;/li&gt;
&lt;li&gt;Existing users keep the familiar named step&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preserves command-surface bloat&lt;/li&gt;
&lt;li&gt;Keeps docs, templates, and migrations more complex than necessary&lt;/li&gt;
&lt;li&gt;Conflicts with the explicit goal to remove the command completely&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-deprecate-first-remove-later&quot;&gt;Option 2: Deprecate first, remove later&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Gives users a softer transition path&lt;/li&gt;
&lt;li&gt;Allows warning-based rollout&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires compatibility shims we do not want&lt;/li&gt;
&lt;li&gt;Extends the lifetime of command-specific code and docs&lt;/li&gt;
&lt;li&gt;Leaves the repo in a half-removed state for at least one more release&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-remove-immediately-with-a-destructive-upgrade-migration&quot;&gt;Option 3: Remove immediately with a destructive upgrade migration&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Delivers the cleanest end state in one step&lt;/li&gt;
&lt;li&gt;Keeps upgrade behavior explicit and deterministic&lt;/li&gt;
&lt;li&gt;Removes stale artifacts instead of preserving them accidentally&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;More work in a single PR&lt;/li&gt;
&lt;li&gt;Requires coordinated updates across templates, migrations, tests, and docs&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Upgrade cleanup implementation: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_2_0_11_remove_clarify_command.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Current-source template removals: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/templates/command-templates/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/software-dev/command-templates/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Current-product doc updates: &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/reference/&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;examples/&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
