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

description
Task list for Product Knowledge & Contextual Help

Tasks: Product Knowledge & Contextual Help

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/244-product-knowledge-contextual-help/
Prerequisites: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/244-product-knowledge-contextual-help/plan.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/244-product-knowledge-contextual-help/spec.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/244-product-knowledge-contextual-help/checklists/requirements.md (required)

Tests: REQUIRED (Pest) for all runtime behavior changes in this slice. Keep proof in Unit + Feature lanes only.
Operations: This slice must not alter existing OperationRun start, completion, notification, or link UX.
RBAC: Existing onboarding, tenant, and support-diagnostic entitlement checks remain authoritative. No new capability family is introduced.
Organization: Tasks are grouped by user story so onboarding guidance, support-diagnostic guidance, and the internal machine-readable knowledge source remain independently deliverable.

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare the bounded product-knowledge namespace and the narrow validation surfaces.

• T001 Create the feature-local support namespace and test directories under apps/platform/app/Support/ProductKnowledge/, apps/platform/tests/Unit/Support/ProductKnowledge/, apps/platform/tests/Feature/Onboarding/, and apps/platform/tests/Feature/SupportDiagnostics/

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Add the single shared contextual-help catalog and resolver before touching onboarding or support-diagnostic surfaces.

Checkpoint: One bounded product-knowledge path exists before any host surface adopts it.

• T002 Create the code-owned first-slice topic catalog in apps/platform/app/Support/ProductKnowledge/ContextualHelpCatalog.php
• T003 Create the shared resolver in apps/platform/app/Support/ProductKnowledge/ContextualHelpResolver.php so help payloads are derived from PlatformVocabularyGlossary, ReasonPresenter, OperatorExplanationBuilder, and RequiredPermissionsLinks
• T004 Define the minimal machine-readable knowledge-source metadata shape and unresolved-topic fallback contract inside the ProductKnowledge namespace so onboarding and support-diagnostic hosts can adopt the shared resolver before US3 hardens the final knowledge-source and fallback guarantees
• T005 [P] Add unit coverage for all eight canonical topic keys, resolver behavior, and the foundational fallback/export contract in apps/platform/tests/Unit/Support/ProductKnowledge/ContextualHelpCatalogTest.php, apps/platform/tests/Unit/Support/ProductKnowledge/ContextualHelpResolverTest.php, and apps/platform/tests/Unit/Support/ProductKnowledge/ContextualHelpFallbackTest.php
• T006 Run the foundational unit suite with 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

---

Phase 3: User Story 1 - Explain Onboarding Blockers In Context (Priority: P1) 🎯 MVP

Goal: Show registry-backed contextual help directly in the onboarding workflow so operators can interpret the current blocker without founder explanation.

Independent Test: Open onboarding drafts blocked by consent, permission, connection-health, and verification-freshness issues and verify that the wizard renders the matching help payload without changing the underlying readiness truth.

Tests for User Story 1

• T007 [P] [US1] Add onboarding feature coverage for admin-consent-required, required-permissions-missing, connection-unhealthy, verification-stale, verification-failed, and positive/negative authorization behavior in apps/platform/tests/Feature/Onboarding/ProductKnowledgeOnboardingHelpTest.php

Implementation for User Story 1

• T008 [US1] Update apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php to derive contextual-help topic inputs from existing readiness, permission, and verification signals and resolve them through the shared ContextualHelpResolver
• T009 [US1] Render the onboarding help block with native Filament/shared primitives inside apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php, keeping the host workflow's existing action hierarchy and destructive actions unchanged
• T010 [US1] Run the onboarding slice with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/ProductKnowledgeOnboardingHelpTest.php

---

Phase 4: User Story 2 - Reuse The Same Product Knowledge In Support Diagnostics (Priority: P1)

Goal: Reuse the same contextual-help contract inside tenant and operation-context support-diagnostic previews.

Independent Test: Open tenant and operation support diagnostics for the same dominant issue and verify that both previews render the same topic-backed help payload and degrade safely when a topic is missing.

Tests for User Story 2

• T011 [P] [US2] Add support-diagnostic feature coverage for tenant-context and operation-context rendering of admin-consent-required, required-permissions-missing, connection-unhealthy, verification-failed, diagnostic-evidence-incomplete, retryable-provider-failure, and manual-handoff-required in apps/platform/tests/Feature/SupportDiagnostics/ProductKnowledgeSupportDiagnosticHelpTest.php
• T012 [P] [US2] Add authorization and missing-topic fallback coverage for support-diagnostic help in apps/platform/tests/Feature/SupportDiagnostics/ProductKnowledgeAuthorizationTest.php

Implementation for User Story 2

• T013 [US2] Update apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php to attach contextual-help payloads derived from dominant issue, provider state, and existing diagnostic summary inputs through the shared resolver
• T014 [US2] Update the support-diagnostic preview hosts in apps/platform/app/Filament/Pages/TenantDashboard.php and apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php so they render the bundle's contextual-help data without introducing a second host-specific help dialect
• T015 [US2] Run the support-diagnostic slice with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SupportDiagnostics/ProductKnowledgeSupportDiagnosticHelpTest.php tests/Feature/SupportDiagnostics/ProductKnowledgeAuthorizationTest.php

---

Phase 5: User Story 3 - Provide A Safe Machine-Readable Knowledge Source (Priority: P2)

Goal: Harden the scaffolded machine-readable knowledge source and fallback contract so the first-slice catalog stays safe for later internal AI/support reuse without turning the feature into AI execution or a public docs platform.

Independent Test: Export the catalog into its machine-readable knowledge source and verify that it contains only topic metadata and approved links, while missing topics continue to degrade safely.

Tests for User Story 3

• T016 [P] [US3] Extend apps/platform/tests/Unit/Support/ProductKnowledge/ContextualHelpCatalogTest.php and apps/platform/tests/Unit/Support/ProductKnowledge/ContextualHelpResolverTest.php with finalized machine-readable knowledge-source assertions covering all eight canonical topic keys and approved-link metadata
• T017 [P] [US3] Extend apps/platform/tests/Unit/Support/ProductKnowledge/ContextualHelpFallbackTest.php and apps/platform/tests/Feature/SupportDiagnostics/ProductKnowledgeAuthorizationTest.php with finalized unresolved-topic, link-safety, and no-raw-key regressions

Implementation for User Story 3

• T018 [US3] Finalize the machine-readable knowledge-source shape in apps/platform/app/Support/ProductKnowledge/ContextualHelpCatalog.php so all eight canonical topic keys expose only stable topic metadata, troubleshooting steps, glossary-backed copy, and approved links
• T019 [US3] Harden apps/platform/app/Support/ProductKnowledge/ContextualHelpResolver.php so unresolved topics never raise exceptions or leak raw keys into onboarding or support-diagnostic surfaces, building on the foundational contract from T004
• T020 [US3] Run the knowledge-source and fallback slice with 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 tests/Feature/SupportDiagnostics/ProductKnowledgeAuthorizationTest.php

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Lock down vocabulary alignment, formatting, and the narrow validation suite before implementation close-out.

• T021 [P] Confirm that first-slice topic keys, glossary nouns, and approved docs links stay aligned across apps/platform/app/Support/ProductKnowledge/ContextualHelpCatalog.php, apps/platform/app/Support/ProductKnowledge/ContextualHelpResolver.php, and the adopted onboarding/support-diagnostic surfaces
• T022 Run formatting on touched platform files with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
• T023 Run the full narrow validation suite with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ProductKnowledge tests/Feature/Onboarding/ProductKnowledgeOnboardingHelpTest.php tests/Feature/SupportDiagnostics/ProductKnowledgeSupportDiagnosticHelpTest.php tests/Feature/SupportDiagnostics/ProductKnowledgeAuthorizationTest.php

---

Dependencies & Execution Order

User Story Dependency Graph

Phase 1 (Setup)
  ↓
Phase 2 (Catalog + resolver + fallback/export)
  ↓
US1 (onboarding help adoption) ───────────────┐
                                              ├─→ US3 (safe knowledge-source and fallback hardening)
US2 (support-diagnostic help adoption) ───────┘

Parallel Opportunities

• The unit tests in Phase 2 can be authored in parallel once the catalog shape is agreed.
• Onboarding and support-diagnostic feature tests can be authored in parallel because they touch different host surfaces.
• US3 export and fallback hardening can proceed in parallel with late US1/US2 integration cleanup once the shared resolver contract is stable.

---

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and no heavy-governance or browser family is introduced accidentally.
• Shared helpers and fixture setup remain cheap by default.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The adopted surfaces explicitly use standard-native-filament plus the named monitoring-state-page regression where required.
• No material budget or baseline escalation is introduced.