ADR: Plan Concerns To Work Package Traceability
Context
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
WP## work packages generated later by /spec-kitty.tasks.
The result was a vocabulary gap. A reviewer could see architectural intent in
plan.md and executable WPs in tasks.md, but there was no durable,
machine-readable link explaining how the task workflow translated one into the
other.
Decision
-
plan.mduses an Implementation Concern Map for plan-level units of intent. Concern IDs use theIC-##shape. -
Implementation concerns are not executable units. They capture purpose, relevant requirements, affected surfaces, sequencing, and risks. The tasks workflow translates them into executable
WP##work packages. -
wps.yamlis the only machine-readable place that records concern-to-WP traceability. Each work package may listplan_concern_refs, and each value must matchIC-##. -
The mapping is many-to-many. One concern may produce several WPs, and one WP may cover several concerns.
-
Cross-cutting infrastructure WPs may use
cross_cutting: trueinstead of concern refs. This is an advisory marker used to avoid false-positive coverage warnings. -
WP prompt frontmatter must not include
plan_concern_refs. WP prompt frontmatter is parsed byWPMetadatawith unknown fields forbidden; concern traceability belongs inwps.yaml. -
Legacy manifests without
plan_concern_refsorcross_cuttingremain quiet. They must parse and finalize without new warning noise. Once a manifest opts into concern traceability by using either new field,finalize-taskswarns for any WP missing both.
Consequences
- Reviewers can trace plan intent to executable work by reading generated
tasks.mdand the sourcewps.yaml. - The plan phase no longer creates pseudo-WP vocabulary that competes with the real WP lifecycle.
- Existing missions keep backward-compatible finalization behavior.
- The warning check is advisory. It guides newly authored manifests but does not block historical missions or strict migration windows.
Rejected Alternatives
-
Put
plan_concern_refsin WP prompt frontmatter. This was rejected because WP prompt frontmatter is a different schema withextra="forbid". Adding concern refs there would makefinalize-tasks --validate-onlyreject agent-generated WP files. -
Require a one-to-one concern-to-WP mapping. 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.
-
Warn on every legacy manifest missing concern refs. This was rejected because it violates backward compatibility. The new warning only applies after a manifest opts into concern traceability.
References
- Issue: #1730
- User guide:
docs/guides/use-wps-yaml-manifest.md - Plan guide:
docs/guides/create-plan.md - Task guide:
docs/guides/generate-tasks.md - Manifest model:
src/specify_cli/core/wps_manifest.py