<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/1.x/2026-01-25-7-research-deliverables-separation/">
  <id>https://docs.spec-kitty.ai/adr/1.x/2026-01-25-7-research-deliverables-separation/</id>
  <title>ADR 7: Separate Research Deliverables from Planning Artifacts</title>
  <updated>2026-01-25T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/1.x/2026-01-25-7-research-deliverables-separation/"/>
  <summary>Sends evidence logs to the Mission&apos;s planning directory and research output to the repository proper, so finished work is no longer stranded in a worktree.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Research missions conflate two distinct types of artifacts:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Spec Kitty planning artifacts&lt;/strong&gt; in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/###/research/&lt;/code&gt; (evidence-log.csv, source-register.csv)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Research deliverables&lt;/strong&gt; (the actual output of the research - component inventories, best practices docs, etc.)&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Currently, agents put research deliverables in &lt;code dir=&quot;auto&quot;&gt;research/&lt;/code&gt; at project root within worktrees. These files:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Exist only in worktree branches&lt;/li&gt;
&lt;li&gt;Never get merged to main&lt;/li&gt;
&lt;li&gt;Result in “done” WPs with work stuck in worktrees&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Research deliverables are the PRODUCT of the mission, not planning metadata&lt;/li&gt;
&lt;li&gt;Worktree-based workflow enables parallelization (like software-dev)&lt;/li&gt;
&lt;li&gt;Planning artifacts must remain in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; for sprint tracking&lt;/li&gt;
&lt;li&gt;Existing merge workflow should work without modification&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-all-research-in-kitty-specs-edit-in-main&quot;&gt;Option 1: All research in kitty-specs/ (edit in main)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pros:&lt;/strong&gt; Simple, no new paths to manage&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cons:&lt;/strong&gt; No parallelization possible, everything in main, merge conflicts likely&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-all-research-in-worktrees&quot;&gt;Option 2: All research in worktrees&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pros:&lt;/strong&gt; Full parallelization&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cons:&lt;/strong&gt; Planning artifacts (evidence-log.csv) can’t be shared across WPs during planning&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-separate-planning-artifacts-from-deliverables-chosen&quot;&gt;Option 3: Separate planning artifacts from deliverables (CHOSEN)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pros:&lt;/strong&gt; Clear separation of concerns, enables parallelization for deliverables while keeping planning artifacts shared&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cons:&lt;/strong&gt; Requires specifying &lt;code dir=&quot;auto&quot;&gt;deliverables_path&lt;/code&gt; during planning&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 - Separate planning artifacts from deliverables”&lt;/p&gt;
&lt;h3 id=&quot;implementation&quot;&gt;Implementation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Planning artifacts remain in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/###/research/&lt;/code&gt; (sparse-excluded, edit in main)&lt;/li&gt;
&lt;li&gt;Research deliverables go in configurable &lt;code dir=&quot;auto&quot;&gt;deliverables_path&lt;/code&gt; (in worktree, merge to main)&lt;/li&gt;
&lt;li&gt;Path stored in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; during planning phase&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;two-types-of-artifacts&quot;&gt;Two Types of Artifacts&lt;/h3&gt;























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Type&lt;/th&gt;&lt;th&gt;Location&lt;/th&gt;&lt;th&gt;Edited Where&lt;/th&gt;&lt;th&gt;Purpose&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Sprint Planning&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/###-feature/research/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Main repo&lt;/td&gt;&lt;td&gt;Evidence/sources for planning THIS sprint&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Research Deliverables&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;deliverables_path&lt;/code&gt; from meta.json&lt;/td&gt;&lt;td&gt;Worktree&lt;/td&gt;&lt;td&gt;Actual research outputs (your work product)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;metajson-schema-change&quot;&gt;meta.json Schema Change&lt;/h3&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;mission&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;research&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;deliverables_path&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;docs/research/001-cancer-cure/&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;2025-01-25T...&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:#FFFFFF;--1:#984E4D&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 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;h3 id=&quot;validation-rules&quot;&gt;Validation Rules&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;deliverables_path&lt;/code&gt; must NOT be inside &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;deliverables_path&lt;/code&gt; should not be at project root (ambiguous)&lt;/li&gt;
&lt;li&gt;Recommended patterns: &lt;code dir=&quot;auto&quot;&gt;docs/research/&amp;#x3C;feature&gt;/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;research-outputs/&amp;#x3C;feature&gt;/&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Clear separation of concerns - planning vs deliverables&lt;/li&gt;
&lt;li&gt;Research workflow matches software-dev (worktree → merge)&lt;/li&gt;
&lt;li&gt;Existing merge command works without modification&lt;/li&gt;
&lt;li&gt;Each project controls where research lives&lt;/li&gt;
&lt;li&gt;Parallelization enabled for research WPs&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Requires specifying &lt;code dir=&quot;auto&quot;&gt;deliverables_path&lt;/code&gt; during planning phase&lt;/li&gt;
&lt;li&gt;Migration needed for existing research features (default path provided)&lt;/li&gt;
&lt;li&gt;Two locations for “research” content may require documentation&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Agents must understand the distinction (documented in implement.md template)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Research WP deliverables appear in main after merge&lt;/li&gt;
&lt;li&gt;No orphaned worktree content&lt;/li&gt;
&lt;li&gt;Agents can work in parallel on research WPs&lt;/li&gt;
&lt;li&gt;Planning artifacts (evidence-log.csv, source-register.csv) remain accessible during planning&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;related-adrs&quot;&gt;Related ADRs&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;ADR 1: Record Architecture Decisions&lt;/li&gt;
&lt;li&gt;ADR 3: Centralized Workspace Context Storage (workspace-per-WP pattern)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;implementation-files&quot;&gt;Implementation Files&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/research/templates/plan-template.md&lt;/code&gt; - Deliverables location section&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/research/command-templates/implement.md&lt;/code&gt; - Two-artifact documentation&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/research/command-templates/specify.md&lt;/code&gt; - Prompt for deliverables_path&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/workflow.py&lt;/code&gt; - Read deliverables_path from meta.json&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/mission.py&lt;/code&gt; - &lt;code dir=&quot;auto&quot;&gt;get_deliverables_path()&lt;/code&gt; helper function&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
