ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9e435ea91f
TenantAtlas/specs/351-review-output-resolve-actions-v1/artifacts/review-output-resolve-actions-browser-flow-audit.md
ahmido d4e4d2d109 feat: review output resolve actions v1 (spec 351) (#422) 
Implemented the first version of review output resolve actions. Included a ReviewOutputResolveActionMapper, commands to seed browser fixtures, updated CustomerReviewWorkspace, EnvironmentReviewResource, UI enforcement, and related views. Also added extensive unit, feature, and browser tests, and updated the design coverage matrix.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #422
2026-06-04 00:55:02 +00:00

20 KiB
Raw Blame History

Spec 351 Browser Flow Audit — Review Output Resolve Actions

Executive Summary

  • Overall readiness: not ready
  • Main flow result: Create next review is browser-verifiziert and scope-safe on environment_id=38, but the operator loop does not close cleanly because the workspace loses the released-review entry once a draft exists.
  • Top issues:
    • P1: Workspace does not surface Open draft review or any successor action once a draft exists; both environment_id=39 and the post-create state for environment_id=38 fall back to an empty released-review state.
    • P1: Publish review is visible on draft review 14 while the same page still says Publication blocked / Output not customer-ready and points to Refresh review as the next step.
    • P2: Refresh review confirms cleanly but gives no browser-verifizierte success toast or obvious state delta, so the operator cannot tell whether anything changed.
  • Recommendation: fix before close

Repo State

  • Branch: 351-review-output-resolve-actions-v1
  • Dirty tracked files: 26
  • Untracked files: 7
  • Spec 351 active/uncommitted: yes
  • App code already changed: yes
  • Browser flow ran against the current uncommitted working tree: yes
  • Relevant Spec 351 files in the dirty tree:
    • apps/platform/app/Support/ResolutionGuidance/ResolutionAction.php
    • apps/platform/app/Support/ResolutionGuidance/ResolutionCase.php
    • apps/platform/app/Support/ResolutionGuidance/Adapters/ReviewPackOutputResolutionAdapter.php
    • apps/platform/app/Support/ResolutionGuidance/ReviewOutputResolveActionMapper.php
    • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
    • apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
    • apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php
    • apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
    • apps/platform/resources/views/components/resolution-guidance-card.blade.php
    • apps/platform/tests/Unit/ResolutionGuidance/Spec351ReviewOutputResolveActionMapperTest.php
    • apps/platform/tests/Feature/Filament/Spec351CustomerReviewWorkspaceResolveActionTest.php
    • apps/platform/tests/Feature/EnvironmentReview/Spec351EnvironmentReviewResolveActionTest.php
    • apps/platform/tests/Browser/Spec351ReviewOutputResolveActionsSmokeTest.php
  • Tests executed during this audit: no

Repo-Verified Action Inventory

Repo-backed resolve actions

  • create_next_review
    • type: mutating / operation-backed
    • browser surface: Customer Review Workspace and Environment Review detail
    • confirmation: yes
    • capability: Capabilities::ENVIRONMENT_REVIEW_MANAGE
    • audit / operation backing: AuditActionId::EnvironmentReviewSuccessorCreated, OperationRunType::EnvironmentReviewCompose
  • refresh_review
    • type: mutating / operation-backed
    • browser surface: Environment Review detail only
    • confirmation: yes
    • capability: Capabilities::ENVIRONMENT_REVIEW_MANAGE
    • audit / operation backing: AuditActionId::EnvironmentReviewRefreshed, OperationRunType::EnvironmentReviewCompose
  • publish_review
    • type: mutating / domain action
    • browser surface: Environment Review detail only
    • confirmation: yes
    • capability: Capabilities::ENVIRONMENT_REVIEW_MANAGE
    • audit backing: AuditActionId::EnvironmentReviewPublished
  • open_successor_review
    • type: navigation
    • browser surface: detail action when superseded_by_review_id resolves to a same-scope review
    • confirmation: no

Fallback / navigation actions

  • resolve_review_blockers
  • open_evidence_basis
  • open_operation_proof
  • open_review
  • download actions such as download_review_pack_with_limitations

Actions intentionally not offered as executable in workspace

  • refresh_review
  • publish_review
  • generic “fix automatically”
  • generic “make customer-ready”

Browser Environment

  • Base URL: http://localhost
  • User: authenticated workspace manager; resulting compose operations were initiated by Ahmed Darrazi (repo-verifiziert after mutation)
  • Workspace: wp / workspace 3
  • Environments used:
    • 38 — Spec342 Demo Evidence Incomplete
    • 39 — Spec342 Demo Ready
  • Reviews used:
    • 3 — published review for environment 38, later superseded by 14
    • 14 — draft created during this audit for environment 38
    • 4 — superseded released review for environment 39
    • 13 — existing draft for environment 39
  • Review / pack state:
    • environment 38 pre-action: published blocked output, review pack 4, operation 24
    • environment 38 post-create: draft 14, operation 47, previous review 3 now superseded_by_review_id=14
    • environment 39: released review 4 already superseded by draft 13

Flow Walkthrough

Step 0 — Existing-draft workspace state (environment_id=39)

  • Step: reload current Customer Review Workspace
  • URL: http://localhost/admin/reviews/workspace?environment_id=39
  • Visible title: Customer Review Workspace - TenantPilot
  • Primary guidance state: not present
  • Primary action: not present
  • Secondary actions: not present
  • Clicked action: none
  • Expected result: if an existing draft is the next repo-backed step, the workspace should guide to it
  • Actual result:
    • browser-verifiziert: workspace shows No released customer reviews match the active environment filter.
    • repo-verifiziert: environment 39 has superseded review 4 plus draft 13
    • nicht vorhanden: Open draft review
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none
  • State changed? no
  • Operator clarity: low; the workspace gives no next step for an environment that already has a draft successor
  • Issue: successor/draft flow is unreachable from the workspace once the released review is superseded
  • Severity: P1
  • Screenshot: 00-workspace-env39-no-released-review.png

Step 1 — Published blocked workspace (environment_id=38)

  • Step: open blocked released-review workspace state
  • URL: http://localhost/admin/reviews/workspace?environment_id=38
  • Visible title: Customer Review Workspace - TenantPilot
  • Primary guidance state: Output not customer-ready / Requires review
  • Primary action: Create next review
  • Secondary actions:
    • Inspect review blockers
    • Download review pack with limitations
    • Open evidence basis
    • Open operation proof
  • Clicked action: none
  • Expected result: one dominant real next step with secondary supporting actions
  • Actual result:
    • browser-verifiziert: one dominant Create next review CTA
    • browser-verifiziert: supporting actions are visually subordinate
    • browser-verifiziert: acknowledgement copy distinguishes consumption from customer-ready status
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none
  • State changed? no
  • Operator clarity: high on first screen
  • Issue: none at this step
  • Severity: none
  • Screenshot: 01-customer-review-workspace-output-not-ready.png

Step 2 — Create next review confirmation

  • Step: click Create next review
  • URL: http://localhost/admin/reviews/workspace?environment_id=38
  • Visible title: Customer Review Workspace - TenantPilot
  • Primary guidance state: unchanged beneath modal
  • Primary action: Create next review
  • Secondary actions: unchanged beneath modal
  • Clicked action: Create next review
  • Expected result: confirmation before mutation
  • Actual result:
    • browser-verifiziert: confirmation modal appears with Create next review?
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: modal only
  • State changed? not yet
  • Operator clarity: high
  • Issue: none
  • Severity: none
  • Screenshot: 02-create-next-review-primary-action.png

Step 3 — Result after create-next-review confirmation

  • Step: confirm Create next review
  • URL: http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/environment-reviews/14?source_surface=customer_review_workspace&tenant_filter_id=38
  • Visible title: View Review - TenantPilot
  • Primary guidance state: draft review detail, initially Internal only, then Publication blocked / Output not customer-ready after refresh interactions
  • Primary action: Refresh review
  • Secondary actions:
    • Inspect review blockers
    • Open evidence basis
    • Open operation proof
  • Clicked action: confirmed Create next review
  • Expected result: new draft is created and opened in the correct environment scope
  • Actual result:
    • browser-verifiziert: detail page for review 14 opens
    • repo-verifiziert: review 14 exists as draft and review 3 is now superseded by 14
    • browser-verifiziert: tenant_filter_id=38 and environment scope are preserved in the URL
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none clearly visible at landing time
  • State changed? yes
  • Operator clarity: medium; the draft opens correctly, but the route is a normal detail route rather than a suppressed customer-workspace detail route
  • Issue: no direct break, but the operator has already left the calm workspace surface
  • Severity: P2
  • Screenshot: 03-after-create-next-review-draft.png

Step 4 — Draft review guidance

  • Step: inspect the newly opened draft detail
  • URL: http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/environment-reviews/14?source_surface=customer_review_workspace&tenant_filter_id=38
  • Visible title: View Review - TenantPilot
  • Primary guidance state: Output not customer-ready / Publication blocked
  • Primary action: Refresh review
  • Secondary actions:
    • Inspect review blockers
    • Open evidence basis
    • Open operation proof
  • Clicked action: none
  • Expected result: next action should align with missing inputs / stale evidence
  • Actual result:
    • browser-verifiziert: detail guidance points to Refresh review
    • browser-verifiziert: boundary copy remains non-customer-safe
    • browser-verifiziert + repo-verifiziert: Publish review is still visible in the header on this not-ready draft
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none
  • State changed? no
  • Operator clarity: medium; the guidance is clear, but the visible Publish review header CTA competes with it
  • Issue: readiness and publish availability are contradictory on the same screen
  • Severity: P1
  • Screenshot: 04-draft-review-guidance.png

Step 5 — Refresh review inputs

  • Step: open and confirm Refresh review
  • URL: http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/environment-reviews/14?source_surface=customer_review_workspace&tenant_filter_id=38
  • Visible title: View Review - TenantPilot
  • Primary guidance state: remains blocked / refresh-oriented
  • Primary action: Refresh review
  • Secondary actions: unchanged
  • Clicked action: Refresh review
  • Expected result: obvious success feedback or visible state transition
  • Actual result:
    • browser-verifiziert: confirmation opens
    • browser-verifiziert: confirm completes without console errors
    • browser-verifiziert: no obvious success toast, no clear state delta, no new operator-facing completion cue
    • plausibel: refresh may have run, but the UI does not make that outcome legible
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none browser-verifiziert
  • State changed? not obvious
  • Operator clarity: low after confirmation
  • Issue: refresh feedback is too weak for an action that is supposed to move the draft forward
  • Severity: P2
  • Screenshot: 05-refresh-review-inputs-if-available.png, 06-after-refresh-result.png

Step 6 — Evidence basis target

  • Step: click View evidence snapshot
  • URL: http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/evidence/5
  • Visible title: View Evidence Snapshot - TenantPilot
  • Primary guidance state: evidence page
  • Primary action: none in scope for this audit
  • Secondary actions: page-local
  • Clicked action: View evidence snapshot
  • Expected result: correct environment-scoped evidence detail
  • Actual result:
    • browser-verifiziert: correct evidence detail opens
    • browser-verifiziert: environment scope remains Spec342 Demo Evidence Incomplete
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none
  • State changed? navigated
  • Operator clarity: good
  • Issue: none
  • Severity: none
  • Screenshot: 08-evidence-basis-target.png

Step 7 — Operation proof target

  • Step: click visible Open operation for the current draft
  • URL: http://localhost/admin/workspaces/3/operations/47
  • Visible title: Operation #47 - TenantPilot
  • Primary guidance state: operation detail
  • Primary action: none in scope for this audit
  • Secondary actions: page-local
  • Clicked action: Open operation
  • Expected result: operation proof opens for the current review/compose context
  • Actual result:
    • browser-verifiziert: operation page opens
    • browser-verifiziert: operation shows compose context and succeeded outcome
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none
  • State changed? navigated
  • Operator clarity: good
  • Issue: none
  • Severity: none
  • Screenshot: 09-operation-proof-target.png

Step 8 — Customer-workspace detail context

  • Step: open released review 3 directly in customer-workspace detail mode
  • URL: http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/environment-reviews/3?customer_workspace=1&source_surface=customer_review_workspace&tenant_filter_id=38
  • Visible title: View Review - TenantPilot
  • Primary guidance state: released review detail with customer-workspace context note
  • Primary action: suppressed
  • Secondary actions: suppressed in the guidance card
  • Clicked action: direct route open
  • Expected result: no duplicate CTA rail and clear context note
  • Actual result:
    • browser-verifiziert: context note You are already on the review detail for this output.
    • browser-verifiziert: no visible Create next review, Publish review, or Refresh review buttons in the guidance surface
    • browser-verifiziert: review status, output readiness, publication/sharing state, and limitations remain visible
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none
  • State changed? navigated
  • Operator clarity: good
  • Issue: none
  • Severity: none
  • Screenshot: 10-review-detail-customer-workspace-context.png

Step 9 — Final workspace state after create-next-review

  • Step: return to Customer Review Workspace filtered to environment 38
  • URL: http://localhost/admin/reviews/workspace?environment_id=38
  • Visible title: Customer Review Workspace - TenantPilot
  • Primary guidance state: not present
  • Primary action: not present
  • Secondary actions: not present
  • Clicked action: direct workspace return
  • Expected result: show current draft / successor review as the next repo-backed step
  • Actual result:
    • browser-verifiziert: workspace now shows No released customer reviews match the active environment filter.
    • repo-verifiziert: environment 38 has draft 14 and released review 3 is superseded by it
    • nicht vorhanden: Open draft review
  • Scope preserved? yes
  • Console errors? no
  • Network/server errors? no visible server error page
  • Toast/notification: none
  • State changed? yes, but the state is not actionable from the workspace
  • Operator clarity: low
  • Issue: the main operator loop breaks after the successful creation of a next review
  • Severity: P1
  • Screenshot: 11-final-customer-review-workspace-state.png

Screenshot Index

Step Screenshot Notes
Extra 00-workspace-env39-no-released-review.png Existing-draft environment filtered to an empty released-review state
1 01-customer-review-workspace-output-not-ready.png Good first-screen blocked-output hierarchy
2 02-create-next-review-primary-action.png Confirmation modal present
3 03-after-create-next-review-draft.png Draft detail opened after mutation
4 04-draft-review-guidance.png Draft detail shows refresh-first guidance
5 05-refresh-review-inputs-if-available.png Refresh confirmation
5 result 06-after-refresh-result.png No clear operator-facing success cue
4 / 6 07-publish-review-if-available.png Publish review visible on not-ready draft
6 08-evidence-basis-target.png Evidence target correct
7 09-operation-proof-target.png Operation target correct
8 10-review-detail-customer-workspace-context.png CTA suppression works in explicit customer-workspace mode
9 11-final-customer-review-workspace-state.png Final workspace loses actionable successor/draft state

Findings

P0 Blockers

  • none confirmed

P1 High

  • Workspace successor flow is broken once a draft exists.
    • browser-verifiziert: environment_id=39 and post-create environment_id=38 both end in No released customer reviews match the active environment filter.
    • repo-verifiziert: both environments have a draft successor (13 for env 39, 14 for env 38).
    • impact: the operator cannot return to the workspace and continue with Open draft review or equivalent successor guidance.
  • Publish review is visible on non-ready draft review 14.
    • browser-verifiziert: draft detail shows Publication blocked / Output not customer-ready and still surfaces a visible Publish review header CTA.
    • repo-verifiziert: publish_review is only hidden when the review is not mutable; it is not readiness-gated in the page action.
    • impact: the UI offers a competing high-impact mutation while the guidance says the draft is not yet publishable.

P2 Medium

  • Refresh confirmation lacks clear operator feedback.
    • browser-verifiziert: confirming Refresh review produced no visible success toast or obvious page-state transition.
    • impact: the operator cannot tell whether the action succeeded, retried, or no-op’d.
  • Create-next-review leaves the calm workspace surface immediately and opens a normal detail surface.
    • browser-verifiziert: redirect URL is a normal review detail route with source_surface and tenant_filter_id, not customer_workspace=1.
    • impact: the flow is technically correct, but it weakens the “resolve from workspace” productization story and makes the return path more dependent on detail behavior.

P3 Polish

  • None worth separating from the medium issues in this slice.

Productization Assessment

  • Guidance quality: good on the first blocked workspace surface; mixed once the flow moves into mutable review detail.
  • Next-action clarity: good before mutation, weak after mutation because successor/draft state disappears from the workspace and Publish review competes with Refresh review.
  • Scope correctness: good; workspace 3, environment scope, tenant_filter_id=38, evidence target, and operation target all stayed in the right tenant/environment.
  • Customer-safe boundary: good on the workspace and customer-workspace detail surfaces; no false customer-ready claim was shown while blocked.
  • UI density: improved on the workspace; draft detail is denser and mixes blocked guidance with broad lifecycle controls.
  • Resolve vs Diagnose: partially successful; the flow resolves into a real draft, but the loop back to the workspace does not remain actionable.

Recommended Fix Scope

Must be fixed before closing Spec 351

  • Restore a workspace-visible successor/draft action once a released review is superseded.
  • Align Publish review visibility with actual readiness, or clearly demote/gate it when the draft is blocked.

Can be deferred

  • Stronger success feedback for Refresh review if the refresh semantics are otherwise correct.

Should not be changed

  • Keep the single dominant primary CTA and subordinate supporting actions on the blocked workspace surface.
  • Keep the customer-workspace detail CTA suppression behavior.
  • Keep the evidence-basis and operation-proof targets as repo-backed supporting actions.

Final Recommendation

  • Close Spec 351? no
  • Continue polish? no, fix the P1 workflow issues first
  • Next suggested spec? none until the Spec 351 operator loop is closed end-to-end