<?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-01-29-14-explicit-metadata-fields-over-implicit-defaults/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-01-29-14-explicit-metadata-fields-over-implicit-defaults/</id>
  <title>Explicit Metadata Fields Over Implicit Defaults</title>
  <updated>2026-01-29T00: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-01-29-14-explicit-metadata-fields-over-implicit-defaults/"/>
  <summary>Requires meta.json to spell out target branch and version control system rather than lean on hidden defaults, so configuration is readable without running code.</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 is a &lt;strong&gt;Specification-Driven Development&lt;/strong&gt; tool where “specification” means &lt;strong&gt;explicit, visible, and unambiguous&lt;/strong&gt;. However, feature metadata was relying on implicit defaults:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Before (0.13.7 and earlier):&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;json&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:#D6DEEB;--1:#403F53&quot;&gt;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;feature_number&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;001&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;slug&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;001-my-feature&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;created_at&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;2026-01-29T00:00:00Z&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5D6376&quot;&gt;// target_branch: missing → implicit default &quot;main&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5D6376&quot;&gt;// vcs: missing → implicit default &quot;git&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Problems discovered during ~/tmp testing:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Cannot debug by reading meta.json (configuration invisible)&lt;/li&gt;
&lt;li&gt;Cannot grep for 2.x features: &lt;code dir=&quot;auto&quot;&gt;grep -r &apos;&quot;target_branch&quot;: &quot;2.x&quot;&apos;&lt;/code&gt; finds nothing&lt;/li&gt;
&lt;li&gt;Violates SDD principle: “Specification should be explicit, not implicit”&lt;/li&gt;
&lt;li&gt;When get_feature_target_branch() defaults to “main”, users don’t know if it’s explicit or fallback&lt;/li&gt;
&lt;li&gt;VCS fallback logic is invisible&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Question:&lt;/strong&gt; Should configuration fields ALWAYS be set explicitly in meta.json, even if they match defaults?&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;SDD Principles&lt;/strong&gt; - Specification-Driven Development requires explicit configuration&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Debugging&lt;/strong&gt; - Should be able to see config by reading meta.json&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Transparency&lt;/strong&gt; - No hidden defaults or magic behavior&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Dual-branch routing&lt;/strong&gt; - Need to distinguish “explicitly main” vs “defaulted to main”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;VCS locking&lt;/strong&gt; - Need to know if VCS choice was explicit or auto-detected&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User expectations&lt;/strong&gt; - Developers expect config files to show configuration&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;&lt;strong&gt;Option 1:&lt;/strong&gt; Always set target_branch and vcs explicitly in meta.json&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Keep implicit defaults, add —show-config command to display them&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Hybrid: Set only if non-default (target_branch if not “main”)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Status quo (implicit defaults, documentation in code)&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 1: Always set explicitly”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Aligns with SDD principles (specification is visible)&lt;/li&gt;
&lt;li&gt;Debugging-friendly (cat meta.json shows config)&lt;/li&gt;
&lt;li&gt;Self-documenting (no hidden defaults)&lt;/li&gt;
&lt;li&gt;Prevents ambiguity (explicit “main” vs missing field)&lt;/li&gt;
&lt;li&gt;Enables grepping for features by config&lt;/li&gt;
&lt;/ul&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;&lt;strong&gt;Debugging&lt;/strong&gt; - &lt;code dir=&quot;auto&quot;&gt;cat meta.json&lt;/code&gt; shows complete configuration&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clarity&lt;/strong&gt; - No hidden defaults or magic behavior&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Dual-branch&lt;/strong&gt; - &lt;code dir=&quot;auto&quot;&gt;grep -r &apos;&quot;target_branch&quot;: &quot;2.x&quot;&apos;&lt;/code&gt; finds SaaS features&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;SDD compliance&lt;/strong&gt; - Specification is explicit and visible&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;VCS transparency&lt;/strong&gt; - Can see the VCS choice explicitly&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Audit trail&lt;/strong&gt; - Git history shows when fields were added/changed&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Verbosity&lt;/strong&gt; - meta.json slightly larger (two extra fields)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Migration required&lt;/strong&gt; - Must add fields to existing features&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Template complexity&lt;/strong&gt; - Agents must set fields during /spec-kitty.specify&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Redundancy&lt;/strong&gt; - Default values (“main”, “git”) appear in every meta.json&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Defaults still exist&lt;/strong&gt; - get_feature_target_branch() returns “main” if field missing (backward compat)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Validation not enforced&lt;/strong&gt; - Missing fields don’t cause errors (safe fallback)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Schema expansion&lt;/strong&gt; - Meta.json schema now has 8 fields instead of 6&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We validated this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;✅ 13 integration tests proving explicit fields work&lt;/li&gt;
&lt;li&gt;✅ ~/tmp Feature 001 fixed with explicit fields&lt;/li&gt;
&lt;li&gt;✅ All future features created with /spec-kitty.specify have fields&lt;/li&gt;
&lt;li&gt;✅ Template updated in all 12 agent directories (source of truth)&lt;/li&gt;
&lt;li&gt;✅ No performance impact (fields are lightweight)&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-always-set-explicitly-chosen&quot;&gt;Option 1: Always set explicitly (CHOSEN)&lt;/h3&gt;
&lt;p&gt;meta.json always includes target_branch and vcs, even if they match defaults.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Visible: cat meta.json shows configuration&lt;/li&gt;
&lt;li&gt;Debuggable: No guessing about defaults&lt;/li&gt;
&lt;li&gt;SDD-compliant: Specification is explicit&lt;/li&gt;
&lt;li&gt;Greppable: Can find features by config&lt;/li&gt;
&lt;li&gt;Self-documenting: New developers see config immediately&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;Verbose: Two extra lines per meta.json&lt;/li&gt;
&lt;li&gt;Migration: Must update existing features&lt;/li&gt;
&lt;li&gt;Template: Agents must set fields&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-show-config-command&quot;&gt;Option 2: —show-config command&lt;/h3&gt;
&lt;p&gt;Keep implicit defaults, add command to display them.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No migration needed&lt;/li&gt;
&lt;li&gt;Smaller meta.json files&lt;/li&gt;
&lt;li&gt;No template changes&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 running command to see config&lt;/li&gt;
&lt;li&gt;Not visible in git history&lt;/li&gt;
&lt;li&gt;Cannot grep for features by config&lt;/li&gt;
&lt;li&gt;Violates SDD (config not in specification)&lt;/li&gt;
&lt;li&gt;Debugging requires extra step&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-hybrid-set-only-if-non-default&quot;&gt;Option 3: Hybrid (set only if non-default)&lt;/h3&gt;
&lt;p&gt;Set target_branch only if not “main”, vcs only if not “git”.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Smaller meta.json for most features&lt;/li&gt;
&lt;li&gt;Explicit when overriding defaults&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;Ambiguous: Is “main” explicit or implicit?&lt;/li&gt;
&lt;li&gt;Cannot distinguish explicit from fallback&lt;/li&gt;
&lt;li&gt;Debugging still requires checking code&lt;/li&gt;
&lt;li&gt;Partial SDD compliance only&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-status-quo-implicit&quot;&gt;Option 4: Status quo (implicit)&lt;/h3&gt;
&lt;p&gt;Keep current behavior, document defaults in code comments.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No changes needed&lt;/li&gt;
&lt;li&gt;Minimal meta.json&lt;/li&gt;
&lt;li&gt;No migration&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;Violates SDD principles&lt;/li&gt;
&lt;li&gt;Not debuggable from meta.json&lt;/li&gt;
&lt;li&gt;Cannot grep for features by config&lt;/li&gt;
&lt;li&gt;Hidden behavior (magic defaults)&lt;/li&gt;
&lt;li&gt;User confusion: “Why did it use main?”&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Implementation:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/software-dev/command-templates/specify.md&lt;/code&gt; (template updated)&lt;/li&gt;
&lt;li&gt;Deployed to all 12 agent directories (&lt;code dir=&quot;auto&quot;&gt;.claude/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.codex/&lt;/code&gt;, etc.)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/feature_detection.py::get_feature_target_branch()&lt;/code&gt; (safe default fallback)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Tests:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_specify_metadata_explicit.py&lt;/code&gt; (13 tests)&lt;/li&gt;
&lt;li&gt;All tests validate explicit fields are set, never null, and readable&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Migration:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;m_0_13_8_target_branch.py&lt;/code&gt; adds target_branch to existing features&lt;/li&gt;
&lt;li&gt;Auto-detects Feature 025 as 2.x (from spec.md content)&lt;/li&gt;
&lt;li&gt;Defaults to “main” for all others&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ADR-12: Two-Branch Strategy (establishes need for target_branch)&lt;/li&gt;
&lt;li&gt;ADR-13: Target Branch Routing (uses target_branch for status commits)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Version:&lt;/strong&gt; 0.13.8 improvement (template fix)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;SDD Principle:&lt;/strong&gt; “Specification should be explicit, visible, and unambiguous”&lt;/p&gt;</content>
</entry>
