# Quickstart: Operator Explanation Layer

## Goal

Implement and verify a shared operator explanation layer so degraded, partial, suppressed, and missing-input governance results become understandable without opening diagnostics.

## Implementation sequence

1. Add the shared explanation-pattern builder in the support layer.
2. Extend reason translation outputs with trust-impact and next-action semantics where missing.
3. Define count-role taxonomy and wire it into baseline compare stats or presenters.
4. Refactor Baseline Compare to render the explanation pattern before diagnostics.
5. Refactor governance-oriented Operation Run detail and Baseline Snapshot result presentation to render the same reading order.
6. Apply the pattern to Tenant Review detail and Review Register to prove reuse.
7. Add focused regression coverage for degraded, suppressed, absent-output, and authorization-preservation cases.
8. Run focused tests and format changed files.

## Focused verification commands

Start services if needed:

```bash
vendor/bin/sail up -d
```

Run the most relevant focused suites:

```bash
vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Unit/Badges/OperatorOutcomeTaxonomyTest.php
vendor/bin/sail artisan test --compact tests/Unit/Badges/GovernanceArtifactTruthTest.php
```

Run any new focused explanation or reason-translation tests added during implementation:

```bash
vendor/bin/sail artisan test --compact --filter=Explanation
vendor/bin/sail artisan test --compact --filter=ReasonTranslation
```

Format changed files:

```bash
vendor/bin/sail bin pint --dirty --format agent
```

## Manual smoke checklist

1. Open Baseline Compare with a case that has `0 findings` and evidence gaps, and verify the page reads as incomplete or limited rather than healthy.
2. Open a Baseline Snapshot result surface after capture and verify the primary explanation, trustworthiness statement, and next action appear before low-level truth details.
3. Open a governance Operation Run detail page for a technically successful but limited-confidence result, and verify run completion and result trust are clearly separated.
4. Open a case with missing input or suppressed output and verify the primary explanation says why no normal result exists before diagnostics.
5. Confirm raw JSON, raw reason codes, and low-level counters are still reachable but visually secondary.
6. Confirm Tenant Review detail and Review Register reuse the same explanation family and next-action wording.