ahmido
acdea41d92
## Summary - add the localized review-pack product story routes at `/platform/review-packs` and `/en/platform/review-packs` with shared page composition, evidence/decision framing, audience sections, trust handoff, and footer/use-case/home/platform discovery - extend `site-copy`, smoke coverage, and Spec Kit artifacts for feature 408 so the public website contract, tests, research, plan, quickstart, and checklist stay aligned - polish the public presentation with a cleaner review-pack comparison surface, a more opaque navbar to remove homepage logo bleed-through, a higher-contrast secondary CTA, unique homepage feature icons, and less repetitive homepage use-case copy ## Validation - `corepack pnpm --filter @tenantatlas/website build` - `corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.ts` - `corepack pnpm --filter @tenantatlas/website test tests/smoke/interaction.spec.ts` - source/dist claim scans plus manual browser comprehension checks are recorded in `specs/408-review-evidence-decision/checklists/requirements.md` - current touched website files are free of editor diagnostics; live browser console check on the homepage returned no errors ## Notes - trust/proof messaging remains intentionally honest; this PR does not add fabricated customer logos, certifications, or unsupported compliance claims - `origin/website-dev` is the review base for this PR Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #405
250 lines
16 KiB
Markdown
250 lines
16 KiB
Markdown
# Tasks: Customer-safe Review, Evidence & Decision Story
|
|
|
|
**Input**: Design documents from `/specs/408-review-evidence-decision/`
|
|
**Prerequisites**: `plan.md` (required), `spec.md` (required), `research.md`, `data-model.md`, `quickstart.md`, `contracts/review-pack-story-routes.openapi.yaml`
|
|
|
|
**Tests**: Runtime behavior changes are in scope for `apps/website`, so browser smoke, route/metadata assertions, and static claim scans are required.
|
|
|
|
## Test Governance Checklist
|
|
|
|
- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
|
|
- [x] New or changed tests stay in the smallest honest family, and any browser addition is explicit.
|
|
- [x] Shared helpers and fixtures stay cheap by default; any widening is isolated or documented.
|
|
- [x] Planned validation commands cover the change without unrelated lane cost.
|
|
- [x] Surface test profile is explicit (`Browser`, `public website`).
|
|
- [x] Any escalation or follow-up spec decision is documented in the feature plan.
|
|
- [x] Test-governance review outcome is explicit: `document-in-feature`.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Confirm repo contracts, identify the exact website surfaces in scope, and keep implementation bounded to `apps/website`.
|
|
|
|
- [x] T001 Confirm active feature scope and selected route family in `specs/408-review-evidence-decision/spec.md` and `specs/408-review-evidence-decision/plan.md`
|
|
- [x] T002 Verify root workspace contracts remain unchanged in `package.json`
|
|
- [x] T003 Verify website validation scripts and package contract in `apps/website/package.json`
|
|
- [x] T004 Map current platform, trust, and use-case entry points in `apps/website/src/pages/platform.astro`, `apps/website/src/pages/en/platform.astro`, `apps/website/src/pages/use-cases/msp.astro`, and `apps/website/src/pages/use-cases/mittelstand.astro`
|
|
- [x] T005 [P] Map current homepage and platform composition surfaces in `apps/website/src/components/pages/HomePage.astro` and `apps/website/src/components/pages/PlatformPage.astro`
|
|
- [x] T006 [P] Map localized routing and smoke helpers in `apps/website/src/i18n.ts` and `apps/website/tests/smoke/smoke-helpers.ts`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Establish the shared route, page scaffold, copy schema, and smoke hooks that every user story depends on.
|
|
|
|
**Critical**: No user story work should begin before this phase is complete.
|
|
|
|
- [x] T007 Create thin localized route shells in `apps/website/src/pages/platform/review-packs.astro` and `apps/website/src/pages/en/platform/review-packs.astro`
|
|
- [x] T008 Create the shared review-pack page scaffold in `apps/website/src/components/pages/ReviewPacksPage.astro`
|
|
- [x] T009 Add localized `reviewPacks` copy schema, metadata, and CTA containers in `apps/website/src/data_files/site-copy.ts`
|
|
- [x] T010 Extend review-pack route inventory and route helpers in `apps/website/tests/smoke/smoke-helpers.ts`
|
|
- [x] T011 Add baseline title/description and forbidden-claim hooks for review-pack routes in `apps/website/tests/smoke/public-routes.spec.ts`
|
|
- [x] T012 Confirm the final route family and keep `specs/408-review-evidence-decision/plan.md` aligned with `specs/408-review-evidence-decision/contracts/review-pack-story-routes.openapi.yaml`
|
|
|
|
**Checkpoint**: Foundation is ready for story implementation.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Buyers Understand The Review-Pack Outcome (Priority: P1)
|
|
|
|
**Goal**: Deliver the core product-story page so a first-time buyer understands Review Packs as decision-ready governance output instead of another export or dashboard.
|
|
|
|
**Independent Test**: Open `/platform/review-packs` and `/en/platform/review-packs`, then confirm the hero, problem framing, workflow, review-pack anatomy, differentiation, and real CTA language explain the outcome within one page.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [x] T013 [P] [US1] Add route title and description assertions for `/platform/review-packs` and `/en/platform/review-packs` in `apps/website/tests/smoke/public-routes.spec.ts`
|
|
- [x] T014 [P] [US1] Add hero, problem, workflow, review-pack anatomy, and differentiation assertions in `apps/website/tests/smoke/interaction.spec.ts`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [x] T015 [US1] Implement hero, problem, workflow, review-pack anatomy, differentiation, and primary/final CTA copy in `apps/website/src/data_files/site-copy.ts`
|
|
- [x] T016 [US1] Render hero, problem, workflow, review-pack anatomy, differentiation, and primary/final CTA sections in `apps/website/src/components/pages/ReviewPacksPage.astro`
|
|
- [x] T017 [US1] Wire localized metadata and shared page props in `apps/website/src/pages/platform/review-packs.astro` and `apps/website/src/pages/en/platform/review-packs.astro`
|
|
|
|
**Checkpoint**: User Story 1 is independently functional and demonstrable.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Buyers Understand Evidence And Decision Context Safely (Priority: P1)
|
|
|
|
**Goal**: Explain Evidence, Decision Summaries, Accepted Risks, and the customer-safe boundary without overclaiming runtime enforcement or exposing internal/operator-only detail.
|
|
|
|
**Independent Test**: Open the review-pack page and confirm the Evidence, Decision Summary, Accepted Risks, and customer-safe boundary sections explain what belongs in a customer-facing review and what does not.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [x] T018 [P] [US2] Add Evidence, Decision Summary, Accepted Risks, and customer-safe boundary assertions in `apps/website/tests/smoke/interaction.spec.ts`
|
|
- [x] T019 [P] [US2] Extend forbidden-detail and overclaim pattern coverage for review-pack routes in `apps/website/tests/smoke/smoke-helpers.ts`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [x] T020 [US2] Implement Evidence cards, Decision Summary facets, Accepted Risks, customer-safe boundary copy, and soft export wording in `apps/website/src/data_files/site-copy.ts`
|
|
- [x] T021 [US2] Render Evidence, Decision Summary, Accepted Risks, customer-safe boundary, and soft-availability messaging in `apps/website/src/components/pages/ReviewPacksPage.astro`
|
|
- [x] T022 [US2] Keep customer-safe copy and forbidden-detail exclusions aligned between `apps/website/src/data_files/site-copy.ts` and `specs/408-review-evidence-decision/contracts/review-pack-story-routes.openapi.yaml`
|
|
|
|
**Checkpoint**: User Story 2 is independently functional and demonstrable.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - MSP And Enterprise IT Buyers Can Map The Story To Their Context (Priority: P2)
|
|
|
|
**Goal**: Show why the same Review Pack story matters to MSP service reviews and to Enterprise IT management, security, audit, and recovery conversations.
|
|
|
|
**Independent Test**: Open the page and verify the MSP, Enterprise IT, and raw-export-versus-review-story sections make the audience-specific value obvious without changing the core product truth.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [x] T023 [P] [US3] Add audience-value and raw-export-versus-review-story assertions in `apps/website/tests/smoke/interaction.spec.ts`
|
|
- [x] T024 [P] [US3] Add MSP and Enterprise IT metadata-intent assertions for the review-pack routes in `apps/website/tests/smoke/public-routes.spec.ts`
|
|
- [x] T025 [P] [US3] Add trust teaser destination and bounded-claim assertions for the review-pack routes in `apps/website/tests/smoke/interaction.spec.ts`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [x] T026 [US3] Implement MSP value, Enterprise IT value, and raw-export comparison copy in `apps/website/src/data_files/site-copy.ts`
|
|
- [x] T027 [US3] Render audience-value and raw-export comparison sections in `apps/website/src/components/pages/ReviewPacksPage.astro`
|
|
- [x] T028 [US3] Add localized trust teaser destinations and audience-specific final CTA copy in `apps/website/src/data_files/site-copy.ts` and `apps/website/src/components/pages/ReviewPacksPage.astro`
|
|
|
|
**Checkpoint**: User Story 3 is independently functional and demonstrable.
|
|
|
|
---
|
|
|
|
## Phase 6: User Story 4 - Visitors Can Discover The Page Through Real IA Entry Points (Priority: P2)
|
|
|
|
**Goal**: Make the page reachable from current public-site entry points without placeholder links, fake destinations, or a heavy IA rewrite.
|
|
|
|
**Independent Test**: Reach the page from the homepage, platform teaser, use-case crosslinks, and footer entry points that are implemented, then confirm the route stays readable on desktop and mobile.
|
|
|
|
### Tests for User Story 4
|
|
|
|
- [x] T029 [P] [US4] Extend localized review-pack route inventory in `apps/website/tests/smoke/smoke-helpers.ts`
|
|
- [x] T030 [P] [US4] Add discovery-link and placeholder-link assertions for review-pack entry points in `apps/website/tests/smoke/public-routes.spec.ts`
|
|
- [x] T031 [P] [US4] Add click-through and mobile readability assertions for review-pack entry points in `apps/website/tests/smoke/interaction.spec.ts`
|
|
|
|
### Implementation for User Story 4
|
|
|
|
- [x] T032 [US4] Add homepage teaser copy and localized route mapping in `apps/website/src/data_files/site-copy.ts` and `apps/website/src/components/pages/HomePage.astro`
|
|
- [x] T033 [US4] Add compact platform teaser and localized route mapping in `apps/website/src/data_files/site-copy.ts` and `apps/website/src/components/pages/PlatformPage.astro`
|
|
- [x] T034 [US4] Add MSP and Mittelstand or Enterprise IT crosslinks in `apps/website/src/data_files/site-copy.ts`, `apps/website/src/pages/use-cases/msp.astro`, `apps/website/src/pages/use-cases/mittelstand.astro`, `apps/website/src/pages/en/use-cases/msp.astro`, and `apps/website/src/pages/en/use-cases/mittelstand.astro`
|
|
- [x] T035 [US4] Add localized footer discovery links without a main-nav refactor in `apps/website/src/data_files/site-copy.ts`
|
|
- [x] T036 [US4] Record any intentionally omitted discovery surface and the final IA decision in `specs/408-review-evidence-decision/plan.md`
|
|
|
|
**Checkpoint**: User Story 4 is independently functional and demonstrable.
|
|
|
|
---
|
|
|
|
## Phase 7: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Run the required validation, record proof, and close out claim-boundary and scope checks.
|
|
|
|
- [x] T037 [P] Run formatting check via `corepack pnpm --filter @tenantatlas/website format:check` using `apps/website/package.json`
|
|
- [x] T038 Run static forbidden-term scans on `apps/website/src` and `apps/website/public` using the command set in `specs/408-review-evidence-decision/plan.md`
|
|
- [x] T039 [P] If `apps/website/dist` is regenerated, run static forbidden-term scans on `apps/website/dist` using the command set in `specs/408-review-evidence-decision/plan.md`
|
|
- [x] T040 Run build validation via `corepack pnpm --filter @tenantatlas/website build` using `apps/website/package.json`
|
|
- [x] T041 Run route smoke via `corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.ts` for `apps/website/tests/smoke/public-routes.spec.ts`
|
|
- [x] T042 Run interaction smoke via `corepack pnpm --filter @tenantatlas/website test tests/smoke/interaction.spec.ts` for `apps/website/tests/smoke/interaction.spec.ts`
|
|
- [x] T043 Perform desktop/mobile 60-second comprehension smoke for `/platform/review-packs` and `/en/platform/review-packs`, then record SC-001 through SC-006 notes in `specs/408-review-evidence-decision/plan.md`
|
|
- [x] T044 Record validation commands, scan outcomes, omitted surfaces, and `apps/platform/**` scope confirmation in `specs/408-review-evidence-decision/plan.md` and `specs/408-review-evidence-decision/checklists/requirements.md`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies; starts immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup completion and blocks all story work.
|
|
- **User Stories (Phases 3-6)**: Depend on Foundational completion.
|
|
- **Polish (Phase 7)**: Depends on all selected user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1 (P1)**: Starts after Phase 2; no dependency on other stories.
|
|
- **US2 (P1)**: Starts after Phase 2; can overlap with US1 once the shared page scaffold exists.
|
|
- **US3 (P2)**: Depends on the core route and section structure from US1; can overlap late US2 copy work.
|
|
- **US4 (P2)**: Depends on the review-pack routes existing and at least one implemented discovery surface from US1-US3.
|
|
|
|
### Within Each User Story
|
|
|
|
- Route and smoke assertions should be added before or alongside implementation and must fail before final pass.
|
|
- Shared page structure comes before route wiring and discovery-link integration.
|
|
- Copy and section rendering complete before build and browser validation.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- Setup tasks marked `[P]` can run in parallel.
|
|
- Foundational smoke-hook work can run in parallel with shared page scaffolding after route selection is fixed.
|
|
- US1 and US2 can proceed in parallel after Phase 2 if file ownership is coordinated.
|
|
- US4 homepage, platform, and footer discoverability tasks can be split across implementers once route copy is stable.
|
|
- Phase 7 scan, build, and smoke tasks can be split once implementation is frozen.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
Task: "T013 [US1] Add route title and description assertions for /platform/review-packs and /en/platform/review-packs in apps/website/tests/smoke/public-routes.spec.ts"
|
|
Task: "T014 [US1] Add hero, problem, workflow, review-pack anatomy, and differentiation assertions in apps/website/tests/smoke/interaction.spec.ts"
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
Task: "T018 [US2] Add Evidence, Decision Summary, Accepted Risks, and customer-safe boundary assertions in apps/website/tests/smoke/interaction.spec.ts"
|
|
Task: "T019 [US2] Extend forbidden-detail and overclaim pattern coverage for review-pack routes in apps/website/tests/smoke/smoke-helpers.ts"
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
Task: "T023 [US3] Add audience-value and raw-export-versus-review-story assertions in apps/website/tests/smoke/interaction.spec.ts"
|
|
Task: "T024 [US3] Add MSP and Enterprise IT metadata-intent assertions for the review-pack routes in apps/website/tests/smoke/public-routes.spec.ts"
|
|
Task: "T025 [US3] Add trust teaser destination and bounded-claim assertions for the review-pack routes in apps/website/tests/smoke/interaction.spec.ts"
|
|
```
|
|
|
|
## Parallel Example: User Story 4
|
|
|
|
```bash
|
|
Task: "T029 [US4] Extend localized review-pack route inventory in apps/website/tests/smoke/smoke-helpers.ts"
|
|
Task: "T030 [US4] Add discovery-link and placeholder-link assertions for review-pack entry points in apps/website/tests/smoke/public-routes.spec.ts"
|
|
Task: "T031 [US4] Add click-through and mobile readability assertions for review-pack entry points in apps/website/tests/smoke/interaction.spec.ts"
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (P1 Slice: User Stories 1 and 2)
|
|
|
|
1. Complete Phase 1 (Setup).
|
|
2. Complete Phase 2 (Foundational).
|
|
3. Complete Phase 3 (US1).
|
|
4. Complete Phase 4 (US2).
|
|
5. Validate the P1 slice independently with route metadata and browser smoke.
|
|
6. Demo or ship the first buyer-facing slice.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Finish Setup plus Foundational once.
|
|
2. Deliver US1 and US2 as the P1 slice, then validate them independently.
|
|
3. Add US3 and validate audience-specific framing.
|
|
4. Add US4 and validate discovery plus mobile readability.
|
|
5. Finish Phase 7 proof and close-out notes.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
1. One implementer completes Setup plus Foundational.
|
|
2. After Phase 2:
|
|
- Implementer A: US1 core route story
|
|
- Implementer B: US2 Evidence and customer-safe boundary
|
|
- Implementer C: US4 discoverability surfaces
|
|
3. Fold US3 audience-value framing in after the shared route story stabilizes.
|
|
4. Run Phase 7 validation together before merge.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- `[P]` tasks touch different files or can be completed without waiting on another incomplete task in the same phase.
|
|
- `[US1]` to `[US4]` labels map directly to the user stories in `spec.md` for traceability.
|
|
- MVP scope is the P1 slice: User Stories 1 and 2. User Stories 3 and 4 layer on the same shared page once the core route story is stable. |