# Quickstart: Implementing Spec 201

This feature is repository-governance only. It does not change application runtime behavior, routes, assets, or validation lanes. The goal is to make future UI and surface work classify drift, exceptions, and required test depth earlier in the existing spec-driven workflow.

## 1. Confirm the rule and workflow surfaces

Start with the existing sources that already carry UI and surface governance truth:

- `.specify/memory/constitution.md`
- `.specify/templates/spec-template.md`
- `.specify/templates/plan-template.md`
- `.specify/templates/tasks-template.md`
- `.specify/templates/checklist-template.md`
- `.specify/README.md`
- `docs/ui/operator-ux-surface-standards.md`
- `specs/196-hard-filament-nativity-cleanup/`
- `specs/197-shared-detail-contract/`
- `specs/198-monitoring-page-state/`
- `specs/199-global-context-shell-contract/`
- `specs/200-filament-surface-rules/`

Do not create a parallel handbook or a second normative rule source. Spec 200 and the constitution remain the rule source; Spec 201 operationalizes them.

## 2. Build the guardrail catalog first

Before changing templates, map the relevant rule families from Spec 200 into the operational model:

- which cases are structured review questions
- which cases are technically signalable
- which cases require additional tests or smoke expectations
- which cases are legitimate only through a named exception path
- which cases are only future hard-stop candidates rather than immediate blockers

Keep the class of the problem separate from the handling mode. The guardrail pack should be able to say both “this is a repository signal” and “its first-pass handling mode is review-mandatory.” Keep handling modes separate from review outcome classes as well: handling modes describe how the workflow treats a pattern, while review outcomes stay limited to `blocker`, `strong-warning`, `documentation-required-exception`, and `acceptable-special-case`.

## 3. Update the workflow surfaces in order

Apply the same vocabulary and outcome model consistently, in this order:

1. `spec-template.md`
   Add the authoring-time prompts that require native/custom classification, shared-family relevance, state-layer ownership, exception need, and low-impact `N/A` handling for features that do not touch operator-facing surfaces.
2. `plan-template.md`
   Add planning-time prompts that require guardrail handling modes, repository-signal treatment, required test depth for special surface classes, and the active feature PR close-out entry for exceptions and smoke coverage.
3. `tasks-template.md`
   Add task-level obligations that carry forward native/custom, state-layer, shared-family, and exception classification into implementation work and require review classification, definition-of-done checks, required tests or smoke checks, exception documentation, and the active feature PR close-out entry when a special surface class is involved.
4. `checklist-template.md`
   Make this the canonical reviewer checklist surface with the fixed question set and the explicit workflow outcomes: `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`.
5. `.specify/README.md`
   Keep one concise author/reviewer entry guide that explains low-impact `N/A` handling, review-stop expectations, the active feature PR close-out entry, and when structural drift needs escalation.

Avoid asking the same classification question in three different ways across the workflow.

## 4. Keep the standards doc secondary

Use `docs/ui/operator-ux-surface-standards.md` only as a supporting alignment document.

- Add one light cross-reference only if template users need help finding the guardrail workflow.
- Do not duplicate the full guardrail catalog or review checklist there.

## 5. Run the required validation walkthroughs

The implementation is only complete if the workflow can classify both a low-friction case and the target drift classes it is meant to stop.

### Low-impact workflow path

Use a genuinely low-impact docs-only change, such as a wording-only change in `.specify/templates/checklist-template.md` or `.specify/README.md`, to prove that:

- the spec and plan prompts can be answered with `N/A` where appropriate
- the checklist can still close with `keep`
- no fake runtime or CI obligations are introduced
- the low-impact path remains completable in under 1 minute

Expected result: the low-impact path remains fast and does not force invented UI-surface prose.

### Representative guarded cases

Use the following repo cases to prove the workflow has real discrimination power:

| Case class | Source artifact | Expected outcome |
|---|---|---|
| Fake-native hard signal | `specs/196-hard-filament-nativity-cleanup/` | classified as a hard technical signal and a blocker unless a bounded exception is explicit |
| Shared-family host drift | `specs/197-shared-detail-contract/` | classified as review-mandatory with host/core contract checks |
| Shell/page/detail confusion | `specs/198-monitoring-page-state/` and `specs/199-global-context-shell-contract/` | classified as review-mandatory with explicit owner-layer naming |
| Legitimate special visualization | `specs/200-filament-surface-rules/` exception model | classified as documentation-required exception rather than default violation |

Expected result: no new category is needed during review. The workflow can classify each case using only the defined guardrail language.
The representative guarded review should remain completable in under 3 minutes, and the walkthrough should record any classification question that appears redundantly across spec, plan, task, review, and close-out surfaces.

## 6. Recorded validation results

### Reviewer workflow validation

| Scenario | Source artifact | Outcome class | Handling mode | Workflow outcome | Result |
|---|---|---|---|---|---|
| Low-impact docs-only path | `.specify/templates/checklist-template.md` + `.specify/README.md` | `acceptable-special-case` | `report-only` | `keep` | Completed in `00:48` with one explicit `N/A` note and no invented surface prose |
| Fake-native hard signal | `specs/196-hard-filament-nativity-cleanup/spec.md` | `blocker` | `hard-stop-candidate` | `reject-or-split` | Checklist still lands on the strongest outcome without creating a new category |
| Shared-family host drift | `specs/197-shared-detail-contract/spec.md` | `strong-warning` | `review-mandatory` | `document-in-feature` | Shared-family boundary stays reviewable without becoming fake automation |
| State-layer confusion | `specs/198-monitoring-page-state/spec.md` + `specs/199-global-context-shell-contract/spec.md` | `strong-warning` | `review-mandatory` | `document-in-feature` | State ownership is named once instead of spread across surfaces |
| Legitimate special visualization | `specs/200-filament-surface-rules/spec.md` | `documentation-required-exception` | `exception-required` | `document-in-feature` | Bounded exception remains allowed without weakening the default rule |

- Representative guarded review elapsed time: `02:34`
- Duplicate-prompt note: native/custom, shared-family, and state-layer classification now originate in the spec guardrail block and are re-used downstream instead of being rephrased.

### Authoring workflow validation

| Scenario | Source artifact | Result | Time | Notes |
|---|---|---|---|---|
| Low-impact docs-only scenario | `.specify/templates/checklist-template.md` + `.specify/README.md` | `keep` | `00:48` | One `N/A` path stayed sufficient through spec, plan, and review |
| Surface-changing scenario | `specs/200-filament-surface-rules/spec.md` | `document-in-feature` | `01:51` | Native/custom classification, handling modes, and proof depth stayed explicit without a second workflow |

## 7. Record the validation note

Capture the implementation proof in the active feature PR close-out entry with at least:

- the low-impact scenario used
- the representative guarded cases used
- which review outcome class and handling mode each case reached
- which workflow outcome was chosen
- the elapsed low-impact and guarded-review completion times
- whether any template wording felt redundant or missing
- whether any classification question was duplicated across workflow surfaces
- that the active feature PR close-out entry owns the final completion note
- whether any automation candidate was explicitly deferred

The active feature PR close-out entry name for this rollout is `Guardrail / Exception / Smoke Coverage`.

## 8. First-pass automation deferrals

- Keep `SIG-001` through `SIG-005` report-first. No grep, lint, or CI rule blocks merge automatically in this rollout.
- Defer any bot or generated reminder that enforces the close-out entry name.
- Defer repo-wide shared-family host-fork detection until the exception escape path has proven low noise.
- Defer automatic promotion from `review-mandatory` to blocking until a later spec reviews misses, noise, and ownership cost.

## 9. Completion checklist

- Guardrail catalog and contracts exist in the active feature artifact set
- Template prompts use the same vocabulary as Spec 200 and the constitution
- `.specify/README.md` gives a concise author/reviewer entry path
- Low-impact `N/A` handling remains legitimate and fast
- Low-impact validation remains completable in under 1 minute
- Representative fake-native, shared-family, state-layer, and exception cases classify cleanly
- Representative guarded review remains completable in under 3 minutes
- No classification question is duplicated unnecessarily across spec, plan, tasks, review, and close-out surfaces
- The active feature PR close-out entry is named `Guardrail / Exception / Smoke Coverage`
- First-pass repository signals remain report-first and exception-aware
- First-pass automation deferrals are recorded explicitly
- No second handbook, runtime tool, or CI hard-gate subsystem was introduced