spec-kitty-spdd-reasons

# 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):

```python
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 using the drift taxonomy from
   `data-model.md §Drift classification`:
   - `approved` — diff matches canvas exactly.
   - `approved_with_deviation` — small, documented divergence; record in
     the canvas Deviations section.
   - `canvas_update_needed` — implementation is correct, canvas is stale.
   - `glossary_update_needed` — new canonical term surfaced; escalate to
     glossary skill.
   - `charter_follow_up` — divergence touches charter policy; escalate.
   - `follow_up_mission` — divergence is real but out of scope for this
     mission; file a follow-up.
   - `s