<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/spdd-reasons/">
  <id>https://docs.spec-kitty.ai/architecture/spdd-reasons/</id>
  <title>SPDD and the REASONS Canvas</title>
  <updated>2026-10-08T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/spdd-reasons/"/>
  <summary>Optional set of Spec Kitty built-in artifacts that records change-intent and change-boundary as a structured artifact alongside the spec and plan.</summary>
  <content type="html">&lt;h2 id=&quot;spdd-and-the-reasons-canvas-opt-in-artifact-set&quot;&gt;SPDD and the REASONS Canvas (opt-in artifact set)&lt;/h2&gt;
&lt;p&gt;This is an &lt;strong&gt;optional&lt;/strong&gt; set of built-in Charter Pack artifacts. Projects that do not activate it see no
behavior change. Projects that do select it gain a structured way to capture
the &lt;em&gt;intent&lt;/em&gt; and &lt;em&gt;boundary&lt;/em&gt; of a mission’s changes — separate from, and
additive to, the existing &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Pack scope: paradigm + two tactics + styleguide + directive + template
fragment + skill + this doc. Activation is one change to the active charter. There is
no new artifact kind, no new loader path, and no new template engine.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Mission status:&lt;/strong&gt; the pack ships with mission
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/spdd-reasons-doctrine-pack-01KQC4AX/spec.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spdd-reasons-doctrine-pack-01KQC4AX&lt;/code&gt;&lt;/a&gt;.
See that mission’s &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;quickstart.md&lt;/code&gt; for the
authoritative requirements (FR-001 through FR-020, C-001 through C-007).&lt;/p&gt;
&lt;/blockquote&gt;
&lt;hr&gt;
&lt;h2 id=&quot;why-this-exists&quot;&gt;Why this exists&lt;/h2&gt;
&lt;p&gt;High-risk and multi-WP missions accumulate decisions that the spec captures
as requirements and the plan captures as architecture, but neither captures
in a way a reviewer can use as a &lt;em&gt;boundary&lt;/em&gt; — a thing the implementation is
not supposed to cross without an explicit deviation.&lt;/p&gt;
&lt;p&gt;A REASONS Canvas fills that gap. It is a small, agent-curated record of:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;what the mission is required to do (Requirements),&lt;/li&gt;
&lt;li&gt;what concepts it touches (Entities),&lt;/li&gt;
&lt;li&gt;which approach was selected and which were rejected (Approach),&lt;/li&gt;
&lt;li&gt;which surfaces are inside the change boundary (Structure),&lt;/li&gt;
&lt;li&gt;the ordered steps and tests (Operations),&lt;/li&gt;
&lt;li&gt;the conventions the change must respect (Norms), and&lt;/li&gt;
&lt;li&gt;the safeguards the change must not violate (Safeguards).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;It is not a duplicate of the spec, plan, or code. It is a &lt;em&gt;change-intent
record&lt;/em&gt; and a &lt;em&gt;change boundary&lt;/em&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;spec-kittys-adaptation-of-spdd&quot;&gt;Spec Kitty’s adaptation of SPDD&lt;/h2&gt;
&lt;p&gt;Structured-Prompt-Driven Development (SPDD) in the wider literature treats
prompts and code as co-truth that must stay synchronized as prose mirrors
of one another. &lt;strong&gt;Spec Kitty does not adopt that stance.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;In Spec Kitty:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Code is the source of truth for current behavior.&lt;/strong&gt; What the system
does is determined by the code that runs, not by any document.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The REASONS canvas is the source of truth for &lt;em&gt;change-intent&lt;/em&gt;.&lt;/strong&gt; It
records what we agreed to change, what we agreed not to change, and the
boundary that bounds the change.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;“Sync” means keeping the canvas’s intent record and change boundary
accurate&lt;/strong&gt; as new information arrives — &lt;em&gt;not&lt;/em&gt; mirroring the codebase as
prose.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This distinction is constraint &lt;strong&gt;C-005&lt;/strong&gt; of the SPDD/REASONS mission and
is the philosophical guardrail of every other artifact in this pack. If a
canvas update would require duplicating the codebase as prose, that is a
signal the canvas has slid out of scope; trim it back to intent and
boundary.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;what-the-reasons-canvas-is&quot;&gt;What the REASONS Canvas is&lt;/h2&gt;
&lt;p&gt;A canvas is a markdown file at &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;mission&gt;/reasons-canvas.md&lt;/code&gt;
with seven required sections plus one append-only section:&lt;/p&gt;





































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Section&lt;/th&gt;&lt;th&gt;Captures&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Requirements&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Problem statement, acceptance criteria, definition of done.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Entities&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Domain concepts, relationships, canonical glossary terms.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Approach&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Selected strategy and the tradeoffs of rejected alternatives.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Structure&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Code surfaces affected, components, dependencies, ownership boundaries.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Operations&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Ordered implementation steps and test strategy.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Norms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Coding conventions, observability rules, team rules.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Safeguards&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Hard constraints, invariants, security and performance limits, things not to break.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Plus:&lt;/p&gt;













&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Section&lt;/th&gt;&lt;th&gt;Captures&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Deviations&lt;/strong&gt; &lt;em&gt;(append-only)&lt;/em&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;date&gt; — &amp;#x3C;wp&gt; — &amp;#x3C;description&gt; — &amp;#x3C;rationale&gt;&lt;/code&gt; for each approved deviation from the canvas.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The canvas is per-mission. Per-WP focus is delivered as a &lt;em&gt;summary slice&lt;/em&gt;
of the mission canvas during implement and review prompts — there is no
separate per-WP canvas file.&lt;/p&gt;
&lt;p&gt;The seven-section skeleton lives at
&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/templates/fragments/reasons-canvas-template.md&lt;/code&gt; and is what
the skill renders for new missions.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;activation&quot;&gt;Activation&lt;/h2&gt;
&lt;p&gt;Activation is a charter-time decision and is fully opt-in. Run the
&lt;a href=&quot;/guides/how-to/governance/setup-governance/&quot;&gt;charter interview&lt;/a&gt; and select &lt;strong&gt;any one&lt;/strong&gt; of
the following library items:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;paradigm &lt;code dir=&quot;auto&quot;&gt;structured-prompt-driven-development&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;tactic &lt;code dir=&quot;auto&quot;&gt;reasons-canvas-fill&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;tactic &lt;code dir=&quot;auto&quot;&gt;reasons-canvas-review&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;directive &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_038&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Selecting the paradigm is the typical case. Selecting only the directive is
allowed for teams that want the change-boundary rule without explicit
canvas authoring tooling. Selecting both tactics without the paradigm is
also allowed for teams that want the canvas authoring/review playbooks but
do not want a paradigm-level commitment.&lt;/p&gt;
&lt;p&gt;Verify activation with:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;charter&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;context&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--action&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;specify&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;When the pack is active, the response includes an “SPDD/REASONS Guidance”
subsection. When it is not, the response is byte-or-semantically identical
to a project that never selected the pack (constraint &lt;strong&gt;C-002&lt;/strong&gt;, validated
by the inactive-baseline snapshot tests).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;lifecycle-behavior-when-active&quot;&gt;Lifecycle behavior when active&lt;/h2&gt;
&lt;p&gt;The pack is wired into the charter context machinery so each workflow
action receives a scoped slice of REASONS guidance:&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Action&lt;/th&gt;&lt;th&gt;REASONS guidance the agent receives&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Requirements + Entities authoring guidance.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.plan&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Approach + Structure authoring guidance.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.tasks&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Operations + WP boundary guidance.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.implement&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Full WP-scoped canvas summary in the implement prompt.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.review&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Canvas as comparison surface; drift gate active.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;When the pack is &lt;strong&gt;inactive&lt;/strong&gt;, none of these scopes inject any extra text
and command-template prompts render identically to current Spec Kitty
output.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;generating-and-updating-the-canvas&quot;&gt;Generating and updating the canvas&lt;/h2&gt;
&lt;p&gt;The canvas is authored by the agent skill
&lt;code dir=&quot;auto&quot;&gt;spk-charter-spdd-reasons&lt;/code&gt; (built-in at
&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/skills/spk-charter-spdd-reasons/SKILL.md&lt;/code&gt;). The skill is
triggered by any of the following phrases in user input:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;“use SPDD”&lt;/li&gt;
&lt;li&gt;“use REASONS”&lt;/li&gt;
&lt;li&gt;“generate a REASONS canvas”&lt;/li&gt;
&lt;li&gt;“apply structured prompt driven development”&lt;/li&gt;
&lt;li&gt;“make this mission SPDD”&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;When triggered, the skill:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Detects whether the SPDD/REASONS pack is active for the current
project. If not active and the user demands enforcement, it
&lt;em&gt;escalates&lt;/em&gt; — it does &lt;strong&gt;not&lt;/strong&gt; silently enforce.&lt;/li&gt;
&lt;li&gt;Loads mission context: &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;, per-WP
prompts, charter context, glossary, research notes, contracts, and
relevant code references.&lt;/li&gt;
&lt;li&gt;Renders or updates &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;mission&gt;/reasons-canvas.md&lt;/code&gt; from the
seven-section template fragment.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preserves user-authored content.&lt;/strong&gt; When a section already contains
user prose, the skill merges by appending or refining — never by
silent rewrite.&lt;/li&gt;
&lt;li&gt;On request, compiles a per-WP REASONS summary as a focused slice of
the canvas scoped to a single work package.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Trigger the skill mid-mission to retrofit a canvas onto a mission that
started before the pack was activated; the skill will work from the
existing artifacts without overwriting them.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;the-review-gate&quot;&gt;The review gate&lt;/h2&gt;
&lt;p&gt;When the pack is active, the reviewer agent uses the canvas as a comparison
surface during &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.review&lt;/code&gt;. Each WP review classifies the
implementation against the canvas using the &lt;strong&gt;drift taxonomy&lt;/strong&gt;:&lt;/p&gt;


















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Outcome&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;th&gt;Effect&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Implementation matches the canvas.&lt;/td&gt;&lt;td&gt;WP advances.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;approved_with_deviation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Implementation diverged but the deviation is recorded.&lt;/td&gt;&lt;td&gt;WP advances; canvas Deviations log appended.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;canvas_update_needed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The canvas was wrong; reality is correct.&lt;/td&gt;&lt;td&gt;Canvas updated; WP advances.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;glossary_update_needed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Terminology conflict surfaced.&lt;/td&gt;&lt;td&gt;Glossary updated; WP advances.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter_follow_up&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Charter directive needs revisiting.&lt;/td&gt;&lt;td&gt;Follow-up scheduled; WP advances.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;follow_up_mission&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Out-of-bounds work belongs in a separate mission.&lt;/td&gt;&lt;td&gt;Mission filed; WP advances on what was in-bounds.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;scope_drift_block&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Unrecorded scope drift.&lt;/td&gt;&lt;td&gt;WP rejected.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;safeguard_violation_block&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A canvas Safeguard was violated.&lt;/td&gt;&lt;td&gt;WP rejected.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Charter directives take precedence over canvas content.&lt;/strong&gt; If the canvas
contradicts a charter directive, the charter wins and the canvas should be
updated. The canvas never overrides governance.&lt;/p&gt;
&lt;p&gt;The drift gate &lt;strong&gt;only activates for projects whose charter selected the
pack&lt;/strong&gt; (FR-018). Inactive projects see no review-behavior change.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;how-this-differs-from-prompts-as-truth&quot;&gt;How this differs from prompts-as-truth&lt;/h2&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Concern&lt;/th&gt;&lt;th&gt;Generic SPDD&lt;/th&gt;&lt;th&gt;Spec Kitty SPDD/REASONS&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;What is the source of truth for current behavior?&lt;/td&gt;&lt;td&gt;Prompt + code, kept synchronized.&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Code.&lt;/strong&gt; Always.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;What does “sync” mean?&lt;/td&gt;&lt;td&gt;Mirroring code as prose.&lt;/td&gt;&lt;td&gt;Keeping the change-intent record and change boundary accurate.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;What is a canvas?&lt;/td&gt;&lt;td&gt;A complete prose mirror of the system.&lt;/td&gt;&lt;td&gt;A change-intent record bounded by the current mission.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Can the canvas override code?&lt;/td&gt;&lt;td&gt;Sometimes, by re-generation.&lt;/td&gt;&lt;td&gt;No. Code is reality; the canvas describes intent for one mission.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;What happens when implementation diverges?&lt;/td&gt;&lt;td&gt;Re-sync the prose.&lt;/td&gt;&lt;td&gt;Classify the divergence: deviation, canvas update, glossary update, charter follow-up, follow-up mission, scope drift block, or safeguard violation block.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The short version: the canvas is a &lt;em&gt;change ledger&lt;/em&gt;, not a &lt;em&gt;system mirror&lt;/em&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;when-not-to-use-it&quot;&gt;When NOT to use it&lt;/h2&gt;
&lt;p&gt;The pack adds value when there is meaningful change-boundary risk. It is
overhead in cases where the boundary is obvious or the work is small. Do
&lt;strong&gt;not&lt;/strong&gt; activate (or, if active, do not generate a canvas) for:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Tiny fixes&lt;/strong&gt; — typos, dependency bumps, single-line bug fixes. The
diff &lt;em&gt;is&lt;/em&gt; the canvas.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Throwaway spikes&lt;/strong&gt; you intend to discard. Authoring a canvas for code
you will delete tomorrow is wasted work.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Emergency patches.&lt;/strong&gt; The triage path is “fix now, document later” —
a post-hoc canvas (or a follow-up mission) is more appropriate than
blocking the patch on canvas authoring.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pure visual exploration&lt;/strong&gt; — design experiments, layout iterations,
prototype demos where the value is in the artifact you can show, not
in the boundary you can enforce.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Activating the pack on a project where most missions fall in these
categories will produce friction without payoff. Prefer to leave it
inactive at the project level and trigger the skill &lt;em&gt;ad hoc&lt;/em&gt; on the
specific high-risk missions where it earns its keep.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;example-a--lightweight-mission&quot;&gt;Example A — Lightweight mission&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;“Rename the &lt;code dir=&quot;auto&quot;&gt;foo_v2&lt;/code&gt; API surface to &lt;code dir=&quot;auto&quot;&gt;foo&lt;/code&gt;.”&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;This is a one-WP mission with low architectural risk but real user impact.
A canvas is still useful as a one-page sanity check, but most sections can
be brief.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Requirements&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Problem: callers and docs reference &lt;code dir=&quot;auto&quot;&gt;foo_v2&lt;/code&gt;; we want them on &lt;code dir=&quot;auto&quot;&gt;foo&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Acceptance: every reference to &lt;code dir=&quot;auto&quot;&gt;foo_v2&lt;/code&gt; outside deprecation shims is gone.&lt;/li&gt;
&lt;li&gt;Definition of done: deprecation shim ships with a clear sunset date.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Entities&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;foo_v2&lt;/code&gt; (the deprecated symbol).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;foo&lt;/code&gt; (the canonical symbol).&lt;/li&gt;
&lt;li&gt;Deprecation shim (the temporary forwarder).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Approach&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Add &lt;code dir=&quot;auto&quot;&gt;foo&lt;/code&gt; as the canonical symbol. Re-point internals. Keep &lt;code dir=&quot;auto&quot;&gt;foo_v2&lt;/code&gt; as
a deprecation shim that delegates to &lt;code dir=&quot;auto&quot;&gt;foo&lt;/code&gt; and emits a warning.&lt;/li&gt;
&lt;li&gt;Rejected: hard rename without a shim (breaks downstream).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Structure&lt;/strong&gt; — &lt;em&gt;brief&lt;/em&gt;. Files: &lt;code dir=&quot;auto&quot;&gt;src/foo/api.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/api/foo.md&lt;/code&gt;,
the shim module.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Operations&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Add &lt;code dir=&quot;auto&quot;&gt;foo&lt;/code&gt; symbol mirroring &lt;code dir=&quot;auto&quot;&gt;foo_v2&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Re-point internal callers.&lt;/li&gt;
&lt;li&gt;Convert &lt;code dir=&quot;auto&quot;&gt;foo_v2&lt;/code&gt; to a thin deprecation shim.&lt;/li&gt;
&lt;li&gt;Update docs and the migration note.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Norms&lt;/strong&gt; — &lt;em&gt;brief&lt;/em&gt;. Standard project conventions; no special rules.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Safeguards&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No breaking change to clients on the &lt;code dir=&quot;auto&quot;&gt;foo_v2&lt;/code&gt; name within the
deprecation window (one minor release minimum).&lt;/li&gt;
&lt;li&gt;Deprecation warning must include the sunset version.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This canvas is one screen of markdown. Approach, Structure, and Norms can
remain short. The value is in the explicit Safeguards: a reviewer can
detect a diff that violates the deprecation timeline at a glance.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;example-b--high-risk-multi-wp-mission-directive_038-carries-weight&quot;&gt;Example B — High-risk multi-WP mission (&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_038&lt;/code&gt; carries weight)&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;“Introduce a new auth middleware.”&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;This mission spans WPs that touch session storage, API ingress, and
observability. The canvas pays for itself the first time it catches a
safeguard violation in a diff.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Requirements&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Problem: today the API trusts a header set elsewhere; we need a
middleware that validates tokens, materializes a principal, and gates
protected routes.&lt;/li&gt;
&lt;li&gt;Acceptance: explicit threat model coverage (token theft, session
fixation, replay), SLO targets for the middleware path.&lt;/li&gt;
&lt;li&gt;Definition of done: rollout plan executed, feature flag flipped, old
code path removed.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Entities&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Token&lt;/code&gt; (opaque bearer credential).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Session&lt;/code&gt; (server-side state keyed by &lt;code dir=&quot;auto&quot;&gt;session_id&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Principal&lt;/code&gt; (authenticated identity exposed to handlers).&lt;/li&gt;
&lt;li&gt;All three are linked to canonical glossary terms.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Approach&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Selected: a middleware in the ingress chain that validates the token,
loads the session from encrypted storage, and attaches the principal to
the request.&lt;/li&gt;
&lt;li&gt;Rejected (with rationale): a per-handler decorator (too easy to
forget); a sidecar process (adds an out-of-band dependency we do not
need yet).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Structure&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Surface boundary: middleware owns token validation, session lookup, and
principal materialization.&lt;/li&gt;
&lt;li&gt;Handlers own authorization decisions on the materialized principal.&lt;/li&gt;
&lt;li&gt;Storage layer owns at-rest encryption. Observability owns redaction.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Operations&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;WP01: introduce middleware module and unit tests.&lt;/li&gt;
&lt;li&gt;WP02: add encrypted session store.&lt;/li&gt;
&lt;li&gt;WP03: wire middleware into ingress, gated by feature flag.&lt;/li&gt;
&lt;li&gt;WP04: cut handlers over to the principal.&lt;/li&gt;
&lt;li&gt;WP05: ship rollout — flip the flag, remove the old path.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Norms&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Structured logging keys are fixed (&lt;code dir=&quot;auto&quot;&gt;event&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;principal_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;session_id&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Redaction rules apply to every log line touching credentials.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Safeguards&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;No plaintext token in logs&lt;/strong&gt;, ever.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No &lt;code dir=&quot;auto&quot;&gt;session_id&lt;/code&gt; outside encrypted storage.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No breaking change to OAuth callbacks&lt;/strong&gt; during the rollout.&lt;/li&gt;
&lt;li&gt;Middleware path adds no more than 2ms of p99 latency on the gateway.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This canvas is what the reviewer checks every WP diff against:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;WP02 adds a debug log statement that includes the raw token? &lt;strong&gt;Safeguard
violation block&lt;/strong&gt; — the diff cannot land.&lt;/li&gt;
&lt;li&gt;WP03 changes the OAuth callback contract to add a new required
parameter? &lt;strong&gt;Safeguard violation block.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;WP04 changes the principal type to include an extra field beyond what
the canvas’s Entities described? &lt;strong&gt;Scope drift block&lt;/strong&gt; — either record
a deviation or schedule a canvas update.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_038&lt;/code&gt; is what makes those blocks enforceable: it is the
charter-level rule that says “implementations must stay within the
approved canvas’s Requirements, Operations, Norms, and Safeguards unless
a deviation is explicitly recorded.”&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;related-artifacts&quot;&gt;Related artifacts&lt;/h2&gt;
&lt;p&gt;Data artifacts ship under the built-in pack root &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;; the template fragment and skill stay in the source tree under &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/&lt;/code&gt;:&lt;/p&gt;





































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Kind&lt;/th&gt;&lt;th&gt;Path&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Paradigm&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/paradigms/structured-prompt-driven-development.paradigm.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Tactic — fill&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/tactics/reasons-canvas-fill.tactic.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Tactic — review&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/tactics/reasons-canvas-review.tactic.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Styleguide&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/styleguides/reasons-canvas-writing.styleguide.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Directive&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/directives/038-structured-prompt-boundary.directive.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Template fragment&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/templates/fragments/reasons-canvas-template.md&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Skill&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/skills/spk-charter-spdd-reasons/SKILL.md&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Mission seed material:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/spdd-reasons-doctrine-pack-01KQC4AX/spec.md&quot;&gt;Mission spec&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/spdd-reasons-doctrine-pack-01KQC4AX/data-model.md&quot;&gt;Data model (full canvas semantics)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/spdd-reasons-doctrine-pack-01KQC4AX/quickstart.md&quot;&gt;Quickstart (activation walkthrough)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/spdd-reasons-doctrine-pack-01KQC4AX/research.md&quot;&gt;Research and ADRs&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Related Spec Kitty docs:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/governance/setup-governance/&quot;&gt;How to set up project governance&lt;/a&gt; — the
charter interview is where you opt into this pack.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/spec-driven-development/&quot;&gt;Spec-driven development explained&lt;/a&gt; —
the broader workflow that the canvas slots into.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
