ahmido
20b6aa6a32
## Summary - collapse secondary and diagnostic operation-run sections by default to reduce page density - visually emphasize the primary next step while keeping counts readable but secondary - keep failures and other actionable detail available without dominating the default reading path ## Testing - vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Filament/EnterpriseDetailTemplateRegressionTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php - vendor/bin/sail bin pint --dirty --format agent Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #194
58 lines
6.9 KiB
Markdown
58 lines
6.9 KiB
Markdown
# Research: Operation Run Detail Hierarchy, Deduplication, and Decision Guidance Hardening
|
|
|
|
## Decision 1: Introduce an explicit primary decision zone above the current main/supporting split
|
|
|
|
- Decision: Add a first-class decision zone immediately below the page header and before the current main grid, instead of relying on the header, `Run summary`, and `Current state` card together to communicate the operator judgment.
|
|
- Rationale: The current page spreads the decisive meaning across multiple regions. The rendering analysis shows that header badges, `Run summary`, `Artifact truth`, and the dense supporting card currently compete with each other. A dedicated decision zone gives the operator one predictable place to read the outcome, artifact truth, trust meaning, and next step in one pass.
|
|
- Alternatives considered:
|
|
- Keep the current header and only simplify the sidebar. Rejected because it leaves the main decision meaning fragmented across header, main content, and sidebar.
|
|
- Push all decision meaning into the header. Rejected because the current header payload is designed for identity and key facts, not a deeper semantic summary with artifact truth and trust nuance.
|
|
|
|
## Decision 2: Resolve exactly one primary next step from existing guidance sources
|
|
|
|
- Decision: Define a precedence order for the leading next step and surface only that one in the decision zone. Secondary guidance remains available in supporting or diagnostic areas only when it adds context.
|
|
- Rationale: The current page can show `Artifact next step`, `Next step`, blocked guidance, and lifecycle guidance at the same weight. That dilutes operator confidence. The source data already exists in `ArtifactTruthPresenter`, operator explanation payloads, `OperationUxPresenter`, and blocked/lifecycle helpers, so the right solution is selection and prioritization, not new copy systems.
|
|
- Alternatives considered:
|
|
- Continue rendering all next-step variants and rely on wording differences. Rejected because the same operator question still gets multiple simultaneous answers.
|
|
- Remove artifact-specific guidance entirely in favor of generic guidance. Rejected because artifact-heavy runs need artifact-truth-specific follow-up to remain accurate.
|
|
|
|
## Decision 3: Centralize count presentation and treat additional count detail as diagnostics-only
|
|
|
|
- Decision: Keep one primary count representation and allow a second count representation only when it serves a different purpose, such as a detailed breakdown in diagnostics.
|
|
- Rationale: The current page renders count meaning in both the supporting facts card and a dedicated `Counts` section. That redundancy adds noise without improving understanding. The summary-count system is already normalized through `SummaryCountsNormalizer`, so the issue is presentation duplication rather than source inconsistency.
|
|
- Alternatives considered:
|
|
- Remove all count detail from the top half of the page. Rejected because some runs still need a compact quantitative summary to judge scale or completeness.
|
|
- Keep both current count surfaces. Rejected because the spec explicitly forbids identical or effectively identical duplicate count blocks.
|
|
|
|
## Decision 4: Treat lifecycle and reconciliation states as contextual attention, not as equal-priority summary duplication
|
|
|
|
- Decision: Keep mismatch, blocked, stale, and reconciled signals visible through banners or grouped lifecycle context, but stop repeating the same meaning inside neutral summary facts at the same priority level.
|
|
- Rationale: The viewer already has banner helpers in `TenantlessOperationRunViewer` and lifecycle facts inside the supporting card. The issue is not lack of visibility but repeated visibility at the same weight. Contextual attention should sharpen the decision without producing three competing truth surfaces.
|
|
- Alternatives considered:
|
|
- Remove banners and show everything as facts in the supporting area. Rejected because exceptional states deserve a stronger visual emphasis than ordinary metadata.
|
|
- Keep banner, supporting facts, and diagnostic section all equally explicit. Rejected because this is the duplication problem the spec is trying to solve.
|
|
|
|
## Decision 5: Preserve artifact truth and trust as distinct semantics inside the decision zone
|
|
|
|
- Decision: Keep `Outcome`, `Artifact truth`, `Result meaning`, and `Result trust` as separate but adjacent decision signals instead of collapsing them into one generic health message.
|
|
- Rationale: The underlying domain is already strong precisely because execution lifecycle and result usability are distinct. The artifact-truth partial and operator explanation payload already model those dimensions separately, and the spec explicitly forbids semantic collapse.
|
|
- Alternatives considered:
|
|
- Replace the four dimensions with one overall success or warning headline. Rejected because it would hide whether the run completed successfully but produced a weak or unusable artifact.
|
|
- Move artifact truth fully out of the primary decision zone. Rejected because artifact-heavy runs depend on that signal for safe operator action.
|
|
|
|
## Decision 6: Keep type-specific detail after the canonical decision zone and supporting context
|
|
|
|
- Decision: Preserve type-specific sections such as baseline compare evidence, baseline capture evidence, verification report, failures, and reconciliation details, but reorder them below the generic decision-first hierarchy.
|
|
- Rationale: The current `OperationRunResource::enterpriseDetailPage()` already appends type-specific sections after generic sections. The feature should strengthen that ordering contract and ensure future refactors do not let type-specific content dominate the first screen height.
|
|
- Alternatives considered:
|
|
- Fold type-specific detail into the decision zone. Rejected because it would make the canonical top-level summary too wide and operation-type-dependent.
|
|
- Hide type-specific detail behind separate navigation. Rejected because operators still need one canonical page with deeper evidence available in-place.
|
|
|
|
## Decision 7: Extend existing feature and Livewire tests rather than introducing a new UI test harness
|
|
|
|
- Decision: Build on `OperationRunEnterpriseDetailPageTest`, `OperationRunBaselineTruthSurfaceTest`, `TenantlessOperationRunViewerTest`, and the enterprise-detail builder unit tests for regression coverage.
|
|
- Rationale: The relevant seams already have useful test coverage for hierarchy, artifact truth, tenant-safe viewing, and DB-only render behavior. The hardening work is a refinement of the existing canonical page, so extending those tests is lower-risk and keeps the assertions close to the current architecture.
|
|
- Alternatives considered:
|
|
- Add only manual visual verification. Rejected because this spec is explicitly about preventing hierarchy and duplication regressions.
|
|
- Create a separate browser-test suite as the primary guard. Rejected because the current repo already has faster, targeted feature coverage around this page structure, and the required assertions are mostly structural and textual.
|