ahmido 3c3daae405 feat: normalize operator outcome taxonomy (#186 )

## Summary
- introduce a shared operator outcome taxonomy with semantic axes, severity bands, and next-action policy
- apply the taxonomy to operations, evidence/review completeness, baseline semantics, and restore semantics
- harden badge rendering, tenant-safe filtering/search behavior, and operator-facing summary/notification wording
- add the spec kit artifacts, reference documentation, and regression coverage for diagnostic-vs-primary state handling

## Testing
- focused Pest coverage for taxonomy registry and badge guardrails
- operations presentation and notification tests
- evidence, baseline, restore, and tenant-scope regression tests

## Notes
- Livewire v4.0+ compliance is preserved in the existing Filament v5 stack
- panel provider registration remains unchanged in bootstrap/providers.php
- no new globally searchable resource was added; adopted resources remain tenant-safe and out of global search where required
- no new destructive action family was introduced; existing actions keep their current authorization and confirmation behavior
- no new frontend asset strategy was introduced; existing deploy flow with filament:assets remains unchanged

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #186

2026-03-22 12:13:34 +00:00

12 KiB

Raw Permalink Blame History

Operator UX & Surface Standards

This document defines the binding audience-and-surface contract for TenantPilot.

It establishes:

who each product surface is primarily built for
what type of language is allowed on that surface
how technical detail must be progressively disclosed
how operator-facing pages must communicate status, scope, and actions

This document is normative for new operator-facing UI work and for major UI refactors.

1. Purpose

TenantPilot is not a generic admin UI. It is an enterprise operator product for managed Microsoft tenant governance, backup, restore, monitoring, drift detection, and review workflows.

The product must not expose internal implementation structure as if it were product UX.

The default experience must be optimized for the primary working audience. Technical truth may remain available, but it must be progressively disclosed.

2. Product Audience Model

TenantPilot serves four distinct audiences. Every page must have exactly one primary audience.

2.1 Primary Persona: Operator / Engineer

Focus:

day-to-day execution
monitoring
triage
safe action-taking

Typical tasks:

onboarding tenants
configuring providers
running syncs
reviewing inventory state
running backup / restore workflows
baseline capture / compare
findings triage
exceptions / risk acceptance
operations monitoring

UI requirements:

clear operator language
strong scanability
explicit scope
safe defaults
actionable next steps
minimal ambiguity
no unnecessary internal field leakage

2.2 Secondary Persona: Senior Engineer / Troubleshooter

Focus:

diagnosis
validation
escalation handling
deep technical analysis

Typical needs:

raw payloads
provider error details
UUIDs / external IDs
technical context
low-level diagnostic traces

UI requirements:

access to raw truth
no removal of diagnostic power
diagnostics available on-demand, never as default-visible content

2.3 Tertiary Persona: Service Manager / CISO / Customer Reviewer

Focus:

proof
reporting
trends
governance posture
SLA / audit communication

Typical needs:

dashboards
summaries
evidence-backed reporting
accepted risks
review readiness
exported review packs

UI requirements:

aggregated, outcome-oriented surfaces
low operational noise
no dependence on operator-level detail pages

2.4 Platform Persona: Platform Admin / System Operator

Focus:

platform administration
internal platform management
break-glass operations
platform-wide controls

Typical surface:

/system

UI requirements:

technically capable
administratively precise
still intentionally designed
not a dumping ground for unresolved /admin UX

3. Surface Ownership by Persona

3.1 `/admin` operator surfaces

/admin is operator-first.

This includes:

onboarding
integrations used for tenant operations
tenant management
inventory
policy views
baselines
findings
evidence
monitoring / operations
backup / restore
governance actions

Default-visible UX on these surfaces must be optimized for the Operator / Engineer persona.

3.2 `/admin` diagnostics surfaces

Diagnostics within /admin belong to the Senior Engineer / Troubleshooter persona.

They are:

available where appropriate
secondary
collapsed, tabbed, or otherwise intentionally disclosed
never the primary content hierarchy

3.3 Reporting / review surfaces

Reports, review packs, customer read-only views, and similar proof-oriented surfaces are optimized for the Service Manager / CISO / Customer Reviewer persona.

These surfaces prioritize:

summary
evidence-backed conclusions
trends
risk posture
review readiness

3.4 `/system` platform surfaces

/system is reserved for platform-only administration.

Rules:

/system may expose more technical administrative detail than /admin
/system must not be used to avoid fixing weak operator UX in /admin
product operator workflows belong in /admin, not /system

4. Default vs Diagnostics Rule

Gold rule

Default = Operator Language Expanded = Diagnostic Truth

4.1 Default-visible content must avoid:

raw JSON blobs
raw internal field names
raw DB timestamps without product meaning
raw enum / reason codes
raw provider error bodies unless translated
UUIDs or IDs as primary visual content
implementation-specific field semantics

4.2 Diagnostics content may include:

raw JSON
provider error details
raw IDs / UUIDs
internal field values
stacktrace-adjacent diagnostic summaries
payload sizes
created_at / updated_at / internal audit metadata where relevant

4.3 Diagnostics placement

Diagnostics must be secondary and intentionally placed, for example:

collapsed diagnostics section
dedicated diagnostics tab
advanced technical panel
expandable system detail area

Diagnostics must not dominate the primary page hierarchy.

5. Operator-Language Glossary

Internal or technical terminology must not appear in operator-facing default surfaces without translation.

Internal / Technical Term	Operator-Facing UI Term	Notes
`dry_run`, `is_dry_run`	Simulation Mode / Simulate Only	Indicates no live Microsoft mutation
`metadata_only`	Incomplete Capture / Configuration Unavailable	Use based on context
`reason_code`	Blocked Reason / Failure Reason	Humanized mapping required
`provider_consent_missing`	Missing Admin Consent	Example translated reason
`scope_jsonb.policy_types`	Included Policy Types	Never expose DB path syntax
`scope_jsonb.foundation_types`	Included Foundation Types	Never expose DB path syntax
`evidenceGaps`	Missing Inventory Data / Incomplete Sync Data	Use operator meaning
`fidelity`	Match Confidence	Only show if actionable
`role_definition_id`	Assigned Role	Prefer display name over raw ID

This glossary should expand over time and be treated as a product vocabulary source of truth.

6. Status Taxonomy

UI surfaces must not collapse all state into one ambiguous status.

TenantPilot must distinguish at least four status dimensions where relevant.

6.1 Execution Outcome

Question:

Did the operation execute successfully?

Examples:

Queued
Running
Succeeded
Blocked
Failed
Cancelled

6.2 Data Completeness

Question:

Do we have the full data required for reliable interpretation?

Examples:

Complete
Incomplete
Stale
Unavailable

6.3 Governance Result

Question:

Is the tenant or object aligned with expected governance state?

Examples:

Aligned
Drift Detected
Exception Applied
Risk Accepted
Review Needed

6.4 Lifecycle / Readiness State

Question:

What lifecycle or publication state is the object in?

Examples:

Draft
Active
Archived
Review Ready
Published
Expired

These dimensions must remain semantically distinct in labels, badges, summaries, and workflows.

7. Mutation Scope Rule

Every action that changes state must communicate its mutation scope before execution.

Allowed mutation-scope categories:

TenantPilot only
Microsoft tenant
Simulation only

Examples:

Archive local record -> TenantPilot only
Restore configuration to Intune -> Microsoft tenant
Dry-run / simulation -> Simulation only

This must be understandable from the action label, preview, confirmation step, or surrounding UI copy.

8. Canonical Detail-Page Layout

Every operator-facing detail page should follow this hierarchy unless there is a strong documented reason not to.

8.1 Header

Must show:

object identity
subtle identifier if needed
1-2 primary status indicators

8.2 Action Bar

Rules:

maximum 2 primary actions
destructive or uncommon actions belong in a secondary group
action labels must reflect real outcome and mutation scope

8.3 Summary / Health

Top-of-page summary should answer the primary operator question quickly.

Typical examples:

last sync / last run
completeness state
governance state
current baseline / current assignment
current blocked reason
recommended next step

8.4 Primary Content

This is the main working surface:

related records
findings
relations
scoped data
actionable tables
interpreted content

8.5 Diagnostics

Diagnostics belong at the bottom or in a secondary surface:

raw JSON
raw IDs
payloads
internal timestamps
provider response detail

9. Safe Execution Standard

Actions with meaningful blast radius must follow a consistent pattern.

Required sequence

Configuration
Safety checks / simulation
Preview
Hard confirmation where required
Execute

Applies to:

restore
baseline enforce
high-impact bulk actions
delete actions with tenant impact
tenant-wide mutation flows

Rules

no dangerous one-click actions for high-blast-radius operations
confirmation language must match actual action semantics
preview must clearly indicate mutation scope

10. Workspace vs Tenant Context Rules

Operators must never have to infer scope from memory.

10.1 Tenant-scoped surfaces

If the operator is inside a tenant surface:

actions must be tenant-safe
workspace-wide actions must not silently appear
show all tenants or similar context escapes must not behave like normal in-flow actions

10.2 Workspace-scoped surfaces

Workspace surfaces may aggregate:

dashboards
review views
multi-tenant monitoring
fleet-level rollouts
cross-tenant summaries

But they must still communicate that they are workspace-level, not tenant-level.

10.3 Context clarity requirements

Every page must make clear:

current scope
object scope
whether actions are local or cross-scope
whether current data is tenant-specific or workspace-aggregated

11. Page Contract Requirement

Every new or materially refactored page must define the following before implementation:

primary persona
surface type
primary operator question
default-visible information
diagnostics-only information
status dimensions used
mutation scope
primary actions
dangerous actions

A page that cannot answer these questions is not ready for implementation.

12. Surface Types

Recommended surface categories:

operator execution surface
operator monitoring surface
diagnostic detail surface
reporting / review surface
customer read-only surface
platform admin surface

These categories help determine hierarchy, language, action model, and diagnostics visibility.

13. What Good Looks Like

A strong operator-facing page lets the primary persona understand within a few seconds:

what this page represents
what scope they are in
whether something is healthy, blocked, incomplete, or risky
what they should do next
whether any action changes TenantPilot only, Microsoft tenant state, or nothing live

A strong diagnostics surface lets the troubleshooting persona access raw truth quickly without polluting the primary operator experience.

A strong reporting surface avoids operational noise and emphasizes proof, posture, and readiness.

14. Adoption Rules

This document applies to:

new operator-facing resources
new dashboards and detail pages
new action-heavy flows
major refactors of existing surfaces
new specs that materially affect operator UX

Specs should explicitly reference this document where relevant.

Recommended spec fields:

primary persona
surface type
diagnostics boundary
status taxonomy used
mutation scope
action safety model

15. Non-Goals

This document does not define:

color palette
visual branding
CSS-level implementation details
pixel-level layout choices
complete component library design

This document is about audience, semantics, surface structure, diagnostics boundaries, and safe operator UX.

16. Summary

TenantPilot must behave like a product, not a raw schema browser.

That means:

operator-first default surfaces
diagnostics available, but secondary
distinct status dimensions
explicit mutation scope
safe execution for dangerous actions
explicit workspace / tenant context
page-level audience and surface contracts

12 KiB Raw Permalink Blame History

Operator UX & Surface Standards

1. Purpose

2. Product Audience Model

2.1 Primary Persona: Operator / Engineer

2.2 Secondary Persona: Senior Engineer / Troubleshooter

2.3 Tertiary Persona: Service Manager / CISO / Customer Reviewer

2.4 Platform Persona: Platform Admin / System Operator

3. Surface Ownership by Persona

3.1 /admin operator surfaces

3.2 /admin diagnostics surfaces

3.3 Reporting / review surfaces

3.4 /system platform surfaces

4. Default vs Diagnostics Rule

Gold rule

4.1 Default-visible content must avoid:

4.2 Diagnostics content may include:

4.3 Diagnostics placement

5. Operator-Language Glossary

6. Status Taxonomy

6.1 Execution Outcome

6.2 Data Completeness

6.3 Governance Result

6.4 Lifecycle / Readiness State

7. Mutation Scope Rule

8. Canonical Detail-Page Layout

8.1 Header

8.2 Action Bar

8.3 Summary / Health

8.4 Primary Content

8.5 Diagnostics

9. Safe Execution Standard

Required sequence

Applies to:

Rules

10. Workspace vs Tenant Context Rules

10.1 Tenant-scoped surfaces

10.2 Workspace-scoped surfaces

10.3 Context clarity requirements

11. Page Contract Requirement

12. Surface Types

13. What Good Looks Like

14. Adoption Rules

15. Non-Goals

16. Summary

12 KiB

Raw Permalink Blame History

3.1 `/admin` operator surfaces

3.2 `/admin` diagnostics surfaces

3.4 `/system` platform surfaces