<?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-02-25-1-repurpose-verify-and-doctor-command-taxonomy/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-25-1-repurpose-verify-and-doctor-command-taxonomy/</id>
  <title>Repurpose `verify` and Move Setup Checks Under `doctor`</title>
  <updated>2026-02-25T00: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-02-25-1-repurpose-verify-and-doctor-command-taxonomy/"/>
  <summary>Reassigns verify to checking delivered implementation against artifacts and relocates setup diagnostics under doctor setup, matching what users expect each verb to mean.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;In current CLI behavior, &lt;code dir=&quot;auto&quot;&gt;spec-kitty verify-setup&lt;/code&gt; is the setup diagnostics entrypoint and the root command function name (&lt;code dir=&quot;auto&quot;&gt;verify_setup&lt;/code&gt;) maps to &lt;code dir=&quot;auto&quot;&gt;spec-kitty verify-setup&lt;/code&gt;.
Current command registration still binds &lt;code dir=&quot;auto&quot;&gt;verify_setup&lt;/code&gt; at top level, and the only existing &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; surface is nested under &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status doctor&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;For 2.x, product intent is that &lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; should represent implementation-vs-artifact validation (post-merge mission audit), not environment diagnostics.&lt;/p&gt;
&lt;p&gt;This creates a namespace and semantic conflict that blocks a clean audit UX.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Align command semantics with mission-oriented 2.x behavior.&lt;/li&gt;
&lt;li&gt;Keep top-level command names intuitive for humans and agents.&lt;/li&gt;
&lt;li&gt;Minimize migration pain for existing users and automation.&lt;/li&gt;
&lt;li&gt;Preserve deterministic CLI contracts during rollout.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Keep &lt;code dir=&quot;auto&quot;&gt;verify-setup&lt;/code&gt; as-is and introduce &lt;code dir=&quot;auto&quot;&gt;audit&lt;/code&gt; as a separate command.&lt;/li&gt;
&lt;li&gt;Repurpose &lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; for mission audit and move diagnostics to &lt;code dir=&quot;auto&quot;&gt;doctor setup&lt;/code&gt; (chosen).&lt;/li&gt;
&lt;li&gt;Keep &lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; for diagnostics and introduce a new audit-only name.&lt;/li&gt;
&lt;/ol&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; “Repurpose &lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; for mission audit and move diagnostics to &lt;code dir=&quot;auto&quot;&gt;doctor setup&lt;/code&gt;”, because it best matches user expectation and 2.x mission verification direction.&lt;/p&gt;
&lt;h3 id=&quot;command-contract&quot;&gt;Command Contract&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty verify&lt;/code&gt; runs mission audit for the selected/current feature context.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor setup&lt;/code&gt; runs environment/setup diagnostics.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty verify-setup&lt;/code&gt; remains as a compatibility alias to &lt;code dir=&quot;auto&quot;&gt;doctor setup&lt;/code&gt; with deprecation warning.&lt;/li&gt;
&lt;li&gt;Deprecation period is explicit and versioned in release notes.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Command names match user mental model (&lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; = validation, &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; = diagnostics).&lt;/li&gt;
&lt;li&gt;Clean base for mission-native audit UX.&lt;/li&gt;
&lt;li&gt;Reduced ambiguity in prompt templates and agent instructions.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Existing scripts using &lt;code dir=&quot;auto&quot;&gt;verify-setup&lt;/code&gt; must migrate.&lt;/li&gt;
&lt;li&gt;Requires docs, onboarding, and template updates.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Short-term alias support adds temporary command redundancy.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is correct when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;doctor setup&lt;/code&gt; both operate with stable CLI behavior.&lt;/li&gt;
&lt;li&gt;New user guidance references &lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; for post-merge audit without confusion.&lt;/li&gt;
&lt;li&gt;Alias usage trends downward across release telemetry.&lt;/li&gt;
&lt;/ol&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-verify-setup-add-separate-audit&quot;&gt;Option 1: Keep &lt;code dir=&quot;auto&quot;&gt;verify-setup&lt;/code&gt;, add separate &lt;code dir=&quot;auto&quot;&gt;audit&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Use a new command family while leaving diagnostics untouched.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Minimal immediate migration work.&lt;/li&gt;
&lt;li&gt;Lower risk of breaking old scripts.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Preserves semantic confusion around &lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; naming.&lt;/li&gt;
&lt;li&gt;Increases command-surface complexity.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-2-repurpose-verify-move-diagnostics-to-doctor-setup&quot;&gt;Option 2: Repurpose &lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt;, move diagnostics to &lt;code dir=&quot;auto&quot;&gt;doctor setup&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Adopt clear command taxonomy with explicit diagnostics namespace.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Strong semantic alignment.&lt;/li&gt;
&lt;li&gt;Better long-term command design.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Requires migration and deprecation handling.&lt;/li&gt;
&lt;li&gt;Requires broad docs/template updates.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-3-keep-verify-for-diagnostics-create-new-audit-only-verb&quot;&gt;Option 3: Keep &lt;code dir=&quot;auto&quot;&gt;verify&lt;/code&gt; for diagnostics, create new audit-only verb&lt;/h3&gt;
&lt;p&gt;Retain old behavior and avoid touching existing verify paths.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Least churn for legacy CLI behavior.&lt;/li&gt;
&lt;li&gt;Straightforward short-term implementation.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Conflicts with product expectation that verification means artifact validation.&lt;/li&gt;
&lt;li&gt;Leaves 2.x mission audit UX less discoverable.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;PRD reference:
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-planning-repo&gt;/product-ideas/mission-collaboration-platform-ddd/prd-mission-post-merge-audit-and-verify-repurpose-v1.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Existing command registration:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/__init__.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Existing diagnostics command implementation:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/verify.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
