TenantAtlas/specs/408-review-evidence-decision/research.md

# Research: Customer-safe Review, Evidence & Decision Story

## Decision: Use `/platform/review-packs` and `/en/platform/review-packs`

**Rationale**: The current public website already uses `/platform` and `/en/platform` as the product-story entry points, and the route inventory already contains nested platform-facing public routes such as `/platform/evidence-review/`. A nested `platform` route keeps the new page attached to the product narrative without adding a new top-level IA family.

**Alternatives considered**:

- `/review-packs`: clearer in isolation, but weaker IA connection to the platform story and less consistent with existing product routing.
- `/platform/evidence-reviews`: too close to the docs-facing evidence-review route and weaker on the buyer-facing Review Pack framing.
- `/products/review-packs`: conflicts with the current `/product` and `/products` redirect expectations to `/platform`.

## Decision: Reuse the localized page-component pattern instead of duplicating large route files

**Rationale**: Existing product-level routes already support a thin-route plus shared-page-component pattern via `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/pages/platform.astro` and `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/pages/PlatformPage.astro`. The Review Pack page is section-heavy in both German and English, so a shared `ReviewPacksPage.astro` is the narrowest way to avoid duplicating large amounts of localized markup.

**Alternatives considered**:

- Duplicate `de` and `en` route markup like the use-case pages: acceptable, but needlessly repetitive for a dense product-story page.
- MDX/docs content route: mismatched with the current marketing-page CTA and metadata pattern.
- Inline-only platform section: lower route overhead, but weaker SEO, weaker smoke coverage, and weaker discoverability.

## Decision: Keep all localized page copy in `site-copy.ts`

**Rationale**: The website already centralizes public copy, metadata, navigation labels, footer links, homepage copy, platform copy, trust copy, and use-case copy in `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/data_files/site-copy.ts`. Adding a dedicated `reviewPacks` section there keeps the new page aligned with the existing locale strategy and avoids a second content source.

**Alternatives considered**:

- Page-local constants: simpler for one file, but weaker for German/English parity and CTA consistency.
- Separate JSON or YAML content file: splits public copy away from the existing marketing-content source of truth.
- Runtime content source or CMS: out of scope for a website-only spec.

## Decision: Prefer contextual discovery plus footer exposure, but not a main-nav item

**Rationale**: The current nav already contains Start, Plattform, MSPs, Interne IT, Preise, Vertrauen, Docs, and Kontakt. Adding another main-nav entry would over-densify the top bar. The stronger discovery path is contextual: homepage teaser, platform-page teaser, MSP page crosslink, Mittelstand page crosslink, and a footer link for global reachability.

**Alternatives considered**:

- Main-nav item: globally visible, but too expensive for current IA density.
- Footer only: too weak for the commercial importance of this page.
- Homepage/platform only: better than nothing, but weaker for audience-specific discovery.

## Decision: Reuse existing section primitives and card-grid patterns

**Rationale**: The website already has a stable `HeroSection` plus repeated card-grid and section patterns in `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/pages/PlatformPage.astro` and the use-case routes. The new page can stay visually aligned by composing those primitives rather than introducing a new website design language.

**Alternatives considered**:

- New bespoke layout system for this page: unnecessary for one bounded route.
- Fully copy-paste the MSP page structure: workable, but less reusable than a shared page component that maps new content arrays.
- Docs-like narrative layout: weaker for CTA hierarchy and product marketing cadence.

## Decision: Use the existing smoke helpers and route metadata inventory as the narrowest proof

**Rationale**: `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke/public-routes.spec.ts` and `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke/smoke-helpers.ts` already validate route rendering, metadata, placeholder-link bans, forbidden public claims, and layout stability. Extending those tests is the narrowest proof for this feature.

**Alternatives considered**:

- Manual-only browser review: insufficient for metadata and claim-guardrail regressions.
- New unit tests for copy objects: more brittle than public-route smoke for this use case.
- Platform-side tests: wrong layer because `apps/platform` is explicitly out of scope.

## Decision: Validate only with scripts that currently exist in `apps/website/package.json`

**Rationale**: `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/package.json` currently exposes `build`, `test`, `test:smoke`, `format:check`, and `preview`. The plan must not invent `check`; `astro check` already runs inside the `build` script.

**Alternatives considered**:

- `pnpm --filter @tenantatlas/website check`: not present.
- Root script changes: out of scope and would break workspace contracts.
- Platform/Sail validation: wrong scope for a static website-only page.

## Decision: Treat static claim scans as implementation blockers

**Rationale**: The core risk in this feature is overclaiming. Static scans over `apps/website/src`, `apps/website/public`, and optionally `apps/website/dist` should block terms such as `href="#"`, internal architecture jargon, false compliance claims, fake portal/export claims, and unsupported provider language.

**Alternatives considered**:

- Code review only: too easy to miss metadata or generated-output regressions.
- New custom linter: too heavy for one bounded website feature.
- Narrow placeholder-link scan only: insufficient because the main risk is claim language, not just broken links.

## Decision: Link the trust teaser to the existing `/trust` route

**Rationale**: `/trust` and `/en/trust` already exist as public routes and are already covered in smoke tests. They are the safest real destinations for privacy, disclosure, and security follow-up questions from the new page.

**Alternatives considered**:

- Omit the trust teaser: safe, but weaker than the spec goal of connecting review-story claims to trust context.
- Link to docs only: weaker for commercial trust handoff.
- Invent a download/proof route: explicitly forbidden.