/spec-kitty-spdd-reasons

name: spec-kitty-spdd-reasons
description: >-
  Drive REASONS Canvas authoring and review for Spec Kitty missions that
  opted in to Structured-Prompt-Driven Development (SPDD) via charter
  selection.
  Triggers: "use SPDD", "use REASONS", "generate a REASONS canvas",
  "apply structured prompt driven development", "make this mission SPDD".
  Does NOT handle: enforcing SPDD on projects whose charter has not
  selected the doctrine pack (escalate to charter workflow instead). Does
  NOT mirror code as prose; code remains the source of truth for current
  behavior.

spec-kitty-spdd-reasons

Drive REASONS Canvas authoring and review for missions that opted in to Structured-Prompt-Driven Development (SPDD) via charter selection. The canvas is a thin, agent-curated reasoning layer that sits next to the spec, plan, and tasks; it is **not** a duplicate system mirror.

This skill is documentation for the agent. It assumes the SPDD/REASONS doctrine pack (paradigm, tactics, styleguide, directive, template) has already been shipped under `src/doctrine/` and that activation can be detected via the helper described below.

---

What this skill does

• Detects whether the SPDD/REASONS pack is active for the current project.
• Loads mission context: `spec.md`, `plan.md`, `tasks.md`, per-WP prompts,

charter context, glossary, research notes, contracts, and relevant code.

• Generates or updates `kitty-specs/<mission>/reasons-canvas.md` from the

seven-section template fragment.

• Compiles per-WP REASONS summaries when an implementer or reviewer asks

for one (a focused slice of the canvas scoped to a single work package).

• Runs comparison-mode review: traces a diff against the canvas and

classifies divergences using the drift taxonomy.

What this skill does NOT do

• It does NOT mirror the code as prose. The canvas references source

artifacts; it does not duplicate them. Code remains the source of truth for current behavior.

• It does NOT overwrite user-authored mission artifacts. When a canvas

section already contains user content, the skill **merges** by appending or refining, never by silent rewrite.

• It does NOT silently enforce SPDD on projects that did not opt in via

charter. If the user demands enforcement and the charter is not configured, escalate to the charter workflow.

Activation rules

Three branches:

1. **Active** — charter selected the SPDD/REASONS pack (paradigm `structured-prompt-driven-development`, tactic `reasons-canvas-fill`, tactic `reasons-canvas-review`, or directive `DIRECTIVE_038`). Proceed with canvas authoring or review using the seven-section template at `src/doctrine/templates/fragments/reasons-canvas-template.md`. 2. **Inactive + ad-hoc request** — user asked to "use REASONS" once, without charter opt-in. Proceed, but stamp the canvas header with a "not formally opted in via charter" note so reviewers know the canvas is advisory only. 3. **Inactive + enforcement demand** — user wants REASONS enforced as a gate but the charter has not selected the pack. Do NOT enforce. Escalate to the charter workflow: suggest running the charter interview to add the paradigm or directive, then return to this skill.

How to detect activation

Programmatic (preferred):

from doctrine.spdd_reasons.activation import is_spdd_reasons_active

active = is_spdd_reasons_active(repo_root)

The helper inspects `.kittify/charter/governance.yaml` and `.kittify/charter/directives.yaml` and returns `True` iff any of the four selectors is present:

• paradigm `structured-prompt-driven-development`
• tactic `reasons-canvas-fill`
• tactic `reasons-canvas-review`
• directive `DIRECTIVE_038`

Manual fallback: read `.kittify/charter/governance.yaml` directly and look for the same selectors under `doctrine.selected_paradigms`, `doctrine.selected_tactics`, or `doctrine.selected_directives`.

How to author the canvas

1. **Read mission artifacts**: `kitty-specs/<mission>/spec.md`, `plan.md`, `tasks.md`, per-WP prompts, `research/*`, `contracts/*`, the project glossary, and any source files the spec or plan calls out. 2. **Map content to the seven sections** using the template at `src/doctrine/templates/fragments/reasons-canvas-template.md`:

• **Requirements** — problem statement, acceptance criteria, DoD.
• **Entities** — domain concepts, relationships, canonical glossary

terms.

• **Approach** — selected strategy and tradeoffs considered.
• **Structure** — code surfaces affected, components, dependencies,

ownership boundaries.

• **Operations** — ordered implementation steps, test strategy.
• **Norms** — coding/style conventions, observability and team rules.
• **Safeguards** — hard constraints, security rules, performance limits,

things not to break. 3. **Link, don't duplicate**: prefer `[see spec.md §X](../spec.md#x)` over inlining spec content. The canvas is a reasoning layer, not a copy. 4. **Preserve user content**: if the canvas already exists, read it before writing. Merge new content into existing sections; never blow away user-authored prose. 5. **Append-only Deviations**: the `## Deviations` section is append-only. New entries go at the bottom in the form `- <date> — <wp> — <description> — <rationale>`. Never rewrite or re-order existing entries.

Output path: `kitty-specs/<mission>/reasons-canvas.md`.

How to review with the canvas

Comparison-mode review pairs an implementation diff against the canvas:

1. **Trace** every changed file in the diff to a Requirement and an Operation step in the canvas. Unmapped changes are signal. 2. **Detect** uninvented entities — files, functions, modules, or domain terms that appear in the diff but not in the canvas, the spec, the plan, or the glossary. 3. **Verify** the diff respects the canvas Norms and Safeguards (style/observability/security/performance/invariants). 4. **Classify** every divergence