TenantAtlas/.agent/skills/repo-contracts/product-surface-gate/SKILL.md

name	description
tenantpilot-product-surface-gate	Checklist gate for TenantPilot Product Surface Contract compliance and no-runtime-framework drift.

Purpose

Use this skill to ensure rendered product-surface changes satisfy the Product Surface Contract without turning the contract into a runtime framework or new semantic layer.

Activate When

• Touching rendered UI, routes, navigation, Filament panels/providers, Livewire/Blade surfaces, tables, forms, modals, drawers, actions, reports, downloads, readiness, evidence, provider state, restore flows, or customer output.
• Preparing or reviewing Product Surface fields in a spec, plan, tasks, checklist, implementation report, or PR close-out.
• Auditing visible complexity, one-primary-action discipline, technical demotion, or canonical product status vocabulary.

Do Not Activate When

• The active spec is genuinely docs-only, tooling-only, template-only, or test-only and records N/A - no rendered UI surface changed.
• The task only reads a completed historical UI spec as context.

Maturity

L3 checklist.

Gate Type

checklist.

Source Evidence

• docs/product/standards/product-surface-contract.md
• .specify/README.md
• .specify/memory/constitution.md
• .specify/templates/spec-template.md
• .specify/templates/plan-template.md
• .specify/templates/tasks-template.md
• specs/395-product-surface-gate/implementation-report.md
• docs/ui/operator-ux-surface-standards.md
• docs/ui/action-surface-contract.md
• docs/ui-ux-enterprise-audit/README.md

External Anchors

Not applicable.

Required Repo Context

• Active spec Product Surface Impact, UI Surface Impact, Browser Verification Plan, Human Product Sanity, and implementation-report target.
• Affected route/page/resource/component/action paths.
• Existing route inventory, design coverage, page reports, and standards where relevant.
• Browser proof plan or justified no-browser rationale.

Execution Checklist

• Confirm no-legacy posture or approved compatibility exception.
• Confirm affected surfaces are named and classified.
• Confirm one page archetype, one primary question, one primary action, and surface budget result.
• Confirm Technical Annex/deep-link demotion for OperationRuns, raw evidence, IDs, source keys, detectors, payloads, and logs.
• Confirm canonical status vocabulary or explicit mapping.
• Confirm Product Surface exceptions are none or fully documented.
• Confirm focused browser proof or N/A - no rendered UI surface changed.
• Confirm Human Product Sanity result or no-surface rationale.
• Confirm visible complexity outcome.
• Confirm implementation report includes Livewire v4, provider registration, global search, destructive/high-impact actions, asset strategy, deployment impact, and completed-spec rewrite assertion.

Stop Conditions

• Runtime UI changes start before the active spec/plan names affected surfaces and Product Surface decisions.
• UI changes introduce competing primary statuses or actions.
• Raw proof, OperationRun links, IDs, payloads, or provider diagnostics are default-visible on product-facing pages.
• Product Surface guidance is implemented as a runtime presenter, enum/status family, persisted taxonomy, component framework, or broad redesign engine.
• A page-local truth resolver duplicates canonical domain truth.
• Completed specs are rewritten to retrofit newer wording.

Required Evidence After Use

• Product Surface decision summary.
• Browser proof or no-browser rationale.
• Human Product Sanity outcome or N/A rationale.
• Visible complexity result.
• Exceptions or explicit none.
• Files changed and no completed-spec rewrite assertion.

Common Failure Modes

• Treating Product Surface as copy-only cleanup while leaving rendered behavior unchanged.
• Adding another readiness/status layer rather than reducing visible complexity.
• Keeping technical proof in default views because it is useful for support.
• Recording No UI surface impact while changing routes/navigation/actions.
• Creating a runtime Product Surface framework.

Quarantined Rules

Full Spec 416 quarantine list applies. Especially quarantined here: Product Surface runtime framework; OperationRun as default customer proof; raw provider/evidence payload default display; stale provider Healthy/Ready semantics; historical audits as current truth.

Review / Expiry

Review whenever the Product Surface Contract, UI standards, Spec Kit templates, or implementation-report close-out fields change. No planned expiry.