<?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-06-06-1-plan-concerns-to-work-package-traceability/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-06-1-plan-concerns-to-work-package-traceability/</id>
  <title>ADR: Plan Concerns To Work Package Traceability</title>
  <updated>2026-06-06T00: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-06-06-1-plan-concerns-to-work-package-traceability/"/>
  <summary>Plans carry `IC-##` Implementation Concerns, and `wps.yaml` alone records the many-to-many concern-to-work-package mapping — never work-package prompt frontmatter.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The software-development planning flow used to describe plan-level slices with
work-package-shaped language such as “Parallel Work Analysis”, “Work
Distribution”, and “Agent assignments”. That made plan sections look
executable, even though implementation and review machinery only operates on
&lt;code dir=&quot;auto&quot;&gt;WP##&lt;/code&gt; work packages generated later by &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.tasks&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The result was a vocabulary gap. A reviewer could see architectural intent in
&lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; and executable WPs in &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;, but there was no durable,
machine-readable link explaining how the task workflow translated one into the
other.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; uses an &lt;strong&gt;Implementation Concern Map&lt;/strong&gt; for plan-level units of
intent. Concern IDs use the &lt;code dir=&quot;auto&quot;&gt;IC-##&lt;/code&gt; shape.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Implementation concerns are not executable units. They capture purpose,
relevant requirements, affected surfaces, sequencing, and risks. The tasks
workflow translates them into executable &lt;code dir=&quot;auto&quot;&gt;WP##&lt;/code&gt; work packages.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;wps.yaml&lt;/code&gt; is the only machine-readable place that records concern-to-WP
traceability. Each work package may list &lt;code dir=&quot;auto&quot;&gt;plan_concern_refs&lt;/code&gt;, and each value
must match &lt;code dir=&quot;auto&quot;&gt;IC-##&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;The mapping is many-to-many. One concern may produce several WPs, and one WP
may cover several concerns.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Cross-cutting infrastructure WPs may use &lt;code dir=&quot;auto&quot;&gt;cross_cutting: true&lt;/code&gt; instead of
concern refs. This is an advisory marker used to avoid false-positive
coverage warnings.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;WP prompt frontmatter must not include &lt;code dir=&quot;auto&quot;&gt;plan_concern_refs&lt;/code&gt;. WP prompt
frontmatter is parsed by &lt;code dir=&quot;auto&quot;&gt;WPMetadata&lt;/code&gt; with unknown fields forbidden; concern
traceability belongs in &lt;code dir=&quot;auto&quot;&gt;wps.yaml&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Legacy manifests without &lt;code dir=&quot;auto&quot;&gt;plan_concern_refs&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;cross_cutting&lt;/code&gt; remain quiet.
They must parse and finalize without new warning noise. Once a manifest opts
into concern traceability by using either new field, &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; warns
for any WP missing both.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Reviewers can trace plan intent to executable work by reading generated
&lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; and the source &lt;code dir=&quot;auto&quot;&gt;wps.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The plan phase no longer creates pseudo-WP vocabulary that competes with the
real WP lifecycle.&lt;/li&gt;
&lt;li&gt;Existing missions keep backward-compatible finalization behavior.&lt;/li&gt;
&lt;li&gt;The warning check is advisory. It guides newly authored manifests but does
not block historical missions or strict migration windows.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;rejected-alternatives&quot;&gt;Rejected Alternatives&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Put &lt;code dir=&quot;auto&quot;&gt;plan_concern_refs&lt;/code&gt; in WP prompt frontmatter.&lt;/strong&gt; This was rejected
because WP prompt frontmatter is a different schema with &lt;code dir=&quot;auto&quot;&gt;extra=&quot;forbid&quot;&lt;/code&gt;.
Adding concern refs there would make &lt;code dir=&quot;auto&quot;&gt;finalize-tasks --validate-only&lt;/code&gt; reject
agent-generated WP files.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Require a one-to-one concern-to-WP mapping.&lt;/strong&gt; This was rejected because
architectural concerns and executable work units have different granularity.
Large concerns often need several WPs, while small concerns may safely merge
into one implementation WP.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Warn on every legacy manifest missing concern refs.&lt;/strong&gt; This was rejected
because it violates backward compatibility. The new warning only applies
after a manifest opts into concern traceability.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Issue: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1730&quot;&gt;#1730&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;User guide: &lt;a href=&quot;/guides/how-to/missions/use-wps-yaml-manifest/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/guides/use-wps-yaml-manifest.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Plan guide: &lt;a href=&quot;/guides/how-to/missions/create-plan/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/guides/create-plan.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Task guide: &lt;a href=&quot;/guides/how-to/missions/generate-tasks/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/guides/generate-tasks.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Manifest model: &lt;a href=&quot;../../../src/specify_cli/core/wps_manifest.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/wps_manifest.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
