TenantAtlas/specs/244-product-knowledge-contextual-help/plan.md

Implementation Plan: Product Knowledge & Contextual Help

Branch: 244-product-knowledge-contextual-help | Date: 2026-04-26 | Spec: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/244-product-knowledge-contextual-help/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/244-product-knowledge-contextual-help/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

• Add a bounded ProductKnowledge support namespace with one code-owned contextual-help catalog and one resolver that derive help payloads from existing glossary, reason-translation, operator-explanation, and docs-link helpers.
• Adopt that resolver on two existing high-value surfaces only: ManagedTenantOnboardingWizard and the support-diagnostic bundle used by tenant and operation-context previews.
• Expose the same catalog as a safe machine-readable knowledge source for later internal AI/support use, while keeping the slice read-only, non-persistent, Livewire v4-compatible, and free of panel/provider/global-search/asset changes.

Technical Context

Language/Version: PHP 8.4 (Laravel 12)
Primary Dependencies: Laravel 12 + Filament v5 + Livewire v4 + Pest; existing PlatformVocabularyGlossary, ReasonPresenter, OperatorExplanationBuilder, SupportDiagnosticBundleBuilder, RequiredPermissionsLinks, ProviderReasonTranslator, and ManagedTenantOnboardingWizard
Storage: N/A - no new database or persisted product-knowledge truth
Testing: Pest unit + feature tests only
Validation Lanes: fast-feedback, confidence Target Platform: Sail-backed Laravel admin panel under /admin and existing support-diagnostic previews in tenant and operation contexts Project Type: web
Performance Goals: in-memory topic lookup only, no new remote calls during render, and no extra persistence or background work for the first slice
Constraints: no new database table, no public docs site, no chatbot, no localization overhaul, no new global-search resource, no panel provider changes, no new Filament assets, and no direct feature-level AI execution
Scale/Scope: 8 canonical first-slice help topics across onboarding and support diagnostics, 1 code-owned catalog, 1 resolver, 1 machine-readable knowledge source, and focused adoption on 2 existing operator surface families

First-Slice Topic Inventory

The implementation is locked to these eight canonical topic keys for the first slice:

• admin-consent-required
• required-permissions-missing
• connection-unhealthy
• verification-stale
• verification-failed
• diagnostic-evidence-incomplete
• retryable-provider-failure
• manual-handoff-required

Any change to this topic inventory requires an explicit spec update before implementation expands or swaps the slice.

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Native vs custom classification summary: native Filament + shared diagnostics data
• Shared-family relevance: status messaging, docs links, troubleshooting guidance, support-diagnostic summaries
• State layers in scope: page, workflow step, detail reveal, action preview, diagnostic section detail
• Handling modes by drift class or surface: review-mandatory
• Repository-signal treatment: review-mandatory
• Special surface test profiles: standard-native-filament, monitoring-state-page
• Required tests or manual smoke: functional-core, state-contract
• Exception path and spread control: none
• Active feature PR close-out entry: Guardrail

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: App\Filament\Pages\Workspaces\ManagedTenantOnboardingWizard, App\Support\SupportDiagnostics\SupportDiagnosticBundleBuilder, App\Support\Governance\PlatformVocabularyGlossary, App\Support\ReasonTranslation\ReasonPresenter, App\Support\Ui\OperatorExplanation\OperatorExplanationBuilder, App\Support\Providers\ProviderReasonTranslator, and App\Support\Links\RequiredPermissionsLinks
• Shared abstractions reused: glossary classification, reason envelopes, operator-explanation patterns, support-diagnostic section assembly, and existing provider docs-link helpers
• New abstraction introduced? why?: one bounded contextual-help catalog plus one resolver are justified because the repo has truthful status and glossary primitives already, but it has no shared product-knowledge layer with stable topic keys, troubleshooting guidance, or machine-readable knowledge source
• Why the existing abstraction was sufficient or insufficient: existing abstractions explain current state, but not reusable contextual help. They are sufficient as inputs and insufficient as the final cross-surface help contract.
• Bounded deviation / spread control: no page-local help registries, no second glossary, and no product-knowledge persistence. Provider-specific remediation remains bounded to provider-owned topic entries and existing link helpers only.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no
• Central contract reused: N/A
• Delegated UX behaviors: N/A
• Surface-owned behavior kept local: N/A
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes
• Provider-owned seams: RequiredPermissionsLinks, provider-specific consent/permission guidance, and ProviderReasonTranslator-backed help topics
• Platform-core seams: contextual-help topic IDs, glossary mapping, onboarding help rendering, support-diagnostic help rendering, and the machine-readable catalog export
• Neutral platform terms / contracts preserved: contextual help, help topic, troubleshooting guidance, next action, support diagnostics, readiness guidance
• Retained provider-specific semantics and why: Microsoft admin consent and required-permissions steps remain provider-specific because those remediation paths are concrete current-release truth rather than speculative portability work
• Bounded extraction or follow-up path: document-in-feature for future localization compatibility; no broader follow-up is required for the first slice

Constitution Check

GATE: Must pass before implementation begins. Re-check after design changes.

• Inventory-first / snapshots-second: PASS - contextual help is derived from existing truth only and does not become a new system-of-record
• Read/write separation: PASS - the slice is read-only guidance only and introduces no new mutation flow
• Graph contract path: PASS - the feature adds no new Microsoft Graph calls
• RBAC-UX / workspace isolation / tenant isolation: PASS - existing onboarding, tenant, and operation-view entitlements stay authoritative and contextual help resolves only after host-surface authorization succeeds
• Shared pattern reuse / XCUT-001: PASS - the design explicitly extends glossary, reason, operator-explanation, support-diagnostic, and existing link helpers instead of adding local help prose paths
• Proportionality / PROP-001 and ABSTR-001: PASS - one bounded catalog and one resolver are the narrowest reusable shape that avoids page-local drift
• Persisted truth / PERSIST-001: PASS - no new persistence is introduced
• UI semantics / UI-SEM-001: PASS - the feature adds progressive disclosure help only and does not replace the host surface's truth model
• Filament-native UI / UI-FIL-001: PASS - onboarding and preview hosts remain native Filament/shared surfaces; no bespoke status cards or asset changes are planned
• Livewire v4 / Filament v5: PASS - the feature remains fully within the existing Filament v5 + Livewire v4 stack and requires no provider registration changes beyond the current bootstrap/providers.php location
• Global search rule: N/A - no new resource or global-search configuration is introduced
• Destructive actions: PASS - no new destructive action is introduced; existing confirmations remain unchanged
• Asset strategy: PASS - no new global or on-demand assets are planned, so filament:assets deployment behavior is unchanged
• Test governance / TEST-GOV-001: PASS - proof remains in focused unit + feature tests only

Test Governance Check

• Test purpose / classification by changed surface: Unit for catalog shape, resolver behavior, and fallback/export safety; Feature for onboarding help rendering, support-diagnostic help rendering, and authorization-safe degradation
• Affected validation lanes: fast-feedback, confidence
• Why this lane mix is the narrowest sufficient proof: the feature is server-driven and view-model oriented; browser automation would duplicate what focused unit and feature tests can already prove
• Narrowest proving command(s):
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ProductKnowledge/ContextualHelpCatalogTest.php tests/Unit/Support/ProductKnowledge/ContextualHelpResolverTest.php tests/Unit/Support/ProductKnowledge/ContextualHelpFallbackTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/ProductKnowledgeOnboardingHelpTest.php tests/Feature/SupportDiagnostics/ProductKnowledgeSupportDiagnosticHelpTest.php tests/Feature/SupportDiagnostics/ProductKnowledgeAuthorizationTest.php
• Fixture / helper / factory / seed / context cost risks: reuse existing workspace, onboarding draft, tenant, provider connection, operation run, and support-diagnostic fixtures; avoid new browser or provider-emulator defaults
• Expensive defaults or shared helper growth introduced?: no
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: standard-native-filament relief for onboarding plus one monitoring-state-page regression for the operation-context support-diagnostic host
• Closing validation and reviewer handoff: reviewers should verify registry-backed help only, progressive disclosure, glossary alignment, authorization-safe link resolution, graceful fallback on missing topics, and zero panel/provider/asset/global-search drift
• Budget / baseline / trend follow-up: none expected beyond ordinary feature-local upkeep
• Review-stop questions: did the implementation add page-local help prose, new persistence, or new AI execution; do missing topics fail gracefully; do help links stay entitlement-safe?
• Escalation path: reject-or-split if the implementation grows into a public docs platform, localization rewrite, or AI execution feature; otherwise changes stay inside this feature
• Active feature PR close-out entry: Guardrail
• Why no dedicated follow-up spec is needed: the first slice is intentionally narrow and can land independently before broader localization, support, or AI work

Project Structure

Documentation (this feature)

specs/244-product-knowledge-contextual-help/
├── checklists/
│   └── requirements.md
├── spec.md
├── plan.md
└── tasks.md

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── Operations/TenantlessOperationRunViewer.php
│   │   │   ├── TenantDashboard.php
│   │   │   └── Workspaces/ManagedTenantOnboardingWizard.php
│   │   └── Support/
│   ├── Support/
│   │   ├── Governance/PlatformVocabularyGlossary.php
│   │   ├── Links/RequiredPermissionsLinks.php
│   │   ├── ProductKnowledge/
│   │   │   ├── ContextualHelpCatalog.php
│   │   │   └── ContextualHelpResolver.php
│   │   ├── ReasonTranslation/ReasonPresenter.php
│   │   ├── SupportDiagnostics/SupportDiagnosticBundleBuilder.php
│   │   └── Ui/OperatorExplanation/OperatorExplanationBuilder.php
│   └── Services/
└── tests/
    ├── Unit/Support/ProductKnowledge/
    │   ├── ContextualHelpCatalogTest.php
    │   ├── ContextualHelpResolverTest.php
    │   └── ContextualHelpFallbackTest.php
    └── Feature/
        ├── Onboarding/ProductKnowledgeOnboardingHelpTest.php
        └── SupportDiagnostics/
            ├── ProductKnowledgeAuthorizationTest.php
            └── ProductKnowledgeSupportDiagnosticHelpTest.php

Structure Decision: Single Laravel web application. The implementation adds one small support namespace and adopts it on existing onboarding and support-diagnostic surfaces only.

Complexity Tracking

No constitution violations are required. The only new structure is the explicitly justified code-owned contextual-help catalog plus resolver.

Proportionality Review

• Current operator problem: operators still need founder explanation or scattered docs to interpret onboarding blockers and support-diagnostic dominant issues safely
• Existing structure is insufficient because: the repo has truthful glossary, reason, and diagnostic primitives but no versioned, reusable product-knowledge layer
• Narrowest correct implementation: one code-owned catalog plus one resolver reused by onboarding and support diagnostics only
• Ownership cost created: topic keys, docs-link mappings, fallback behavior, and focused tests
• Alternative intentionally rejected: page-local prose, public docs platform, CMS/editor, or AI execution layer
• Release truth: current-release truth

Rollout & Risk Controls

• Start with onboarding guidance and support diagnostics only. Any third adoption surface requires explicit scope review.
• Keep help blocks progressive and subordinate to the host surface's existing status or diagnostic truth.
• Use only approved docs-link helpers or stable URLs for the first slice. No free-text or user-authored help content is allowed.
• Keep the machine-readable knowledge source internal and code-owned. No runtime AI invocation or customer-facing knowledge export is part of this slice.

Implementation Outline

• Add App\Support\ProductKnowledge\ContextualHelpCatalog and ContextualHelpResolver as the single shared path for first-slice help topics.
• Integrate onboarding help topic selection inside ManagedTenantOnboardingWizard using the existing readiness, permission, and verification signals already present on the page.
• Integrate contextual help into SupportDiagnosticBundleBuilder so tenant and operation-context previews render the same help payload from the same topic keys.
• Expose a safe machine-readable knowledge-source method from the catalog or resolver and add focused unit + feature coverage for rendering, authorization, and fallback.

Constitution Check (Post-Design)

Re-check result: PASS. The plan stays bounded to one code-owned catalog and one resolver, reuses existing glossary/reason/support primitives, adds no new persistence, keeps Filament v5 / Livewire v4 unchanged, leaves provider registration in bootstrap/providers.php untouched, introduces no global-search or asset changes, and keeps proof in narrow unit + feature coverage only.