Handbook

Prompt 02 — Product IA, RBAC, data visibility, and implementation plan

Run in Cursor Plan mode. Do not implement UI or change schemas. ADR and wiki changes are expected.

Updated 2026-07-17

Required context

Prompt 00 baseline
Prompt 01 dual wiki
03-route-and-navigation-map.md
05-role-permission-and-data-visibility-model.md
Existing authentication, tenancy, database, and encryption code

Prompt

Produce the approved target architecture and migration plan for Capablio's public surfaces and five authenticated workspaces.

1. Define the target information architecture

Reconcile existing routes with the target route map. For each target destination, specify:

Workspace
Stable feature ID
Primary persona
Required permission
Tenant and org scope
Data class
Existing route/component to reuse or migrate
Planned route
Release phase
Documentation page

Create a redirect/deprecation map for route changes. Do not break existing invite or saved-link flows without a compatibility plan.

Design a unified shell with a workspace switcher for:

My workspace
Manager workspace
HR workspace
Organization settings
Platform operations

Specify:

Visibility rules
Active tenant/scope presentation
Navigation groups and maximum depth
Cross-workspace return behavior
Mobile behavior
Command search scope
Contextual documentation behavior
Privileged-session indicator

Avoid the term “console” in normal user navigation unless it is an explicit product decision.

3. Formalize authorization

Create a resource/action/scope permission model mapped to existing code. Include:

Role assignments with effective dates and source
Org-unit scopes and descendant behavior
Data-class restrictions
Export permissions
Campaign/program/content administration
Private/shared PDP permissions
Completion metadata versus answer visibility
Platform support access
Global catalog publishing
Billing and security administration

Produce a matrix and negative-test plan. Identify any current is_admin or client-only checks that must be replaced.

4. Formalize data visibility and anonymity

Document exact default visibility for:

Participation status
Individual ratings
Relationship aggregates
Qualitative comments
Imported reports
PDP private notes
PDP shared goals/actions
Organization analytics
Support diagnostics

Define minimum-threshold and suppression behavior, including protections against differencing across filters or periods.

5. Decide encryption and recovery architecture

Inspect the current client-side envelope implementation and write ADR options for:

Subject-private mode
Tenant recovery, if legally/product-approved
Customer-managed keys, if technically/contractually planned
Device registration and key backup
Lost key and leaver flows
Key rotation and resealing
Import processing and plaintext lifetime
Support diagnostics

Do not promise modes that will not be implemented. Select the current supported mode or mark the ADR proposed with a blocking decision.

6. Produce implementation architecture

Document:

Application boundaries: marketing, docs, product, API, workers
Shared design-system package
Shared content source and generation path
API/BFF boundaries
Tenant-aware data-access layer
Audit-event service
Entitlement service
Notification/job architecture
Analytics event boundary
Search strategy
File/import processing
Observability and correlation IDs

Adapt to the existing stack; do not rewrite the application merely to fit a preferred framework.

7. Produce a phased backlog

Group work into:

Critical security/privacy corrections
Design-system and shell foundations
Public marketing/docs
Authentication/onboarding
Individual workspace
Manager/HR/admin/operator workspaces
Adaptive program and campaign workflows
Results/PDP
Integrations/billing/governance
Hardening and migration

For each epic list dependencies, feature IDs, acceptance tests, and migration risk. Avoid hour estimates unless the user specifically asks.

Required outputs

wiki/shared/route-map.md
wiki/shared/role-permission-matrix.md
wiki/shared/data-classification.md
wiki/shared/entitlement-matrix.md
wiki/internal/architecture/target-system-map.md
wiki/internal/security/authorization-model.md
wiki/internal/security/data-visibility-and-anonymity.md
wiki/internal/security/encryption-and-recovery.md
wiki/internal/product/workspace-navigation.md
wiki/internal/product/uplift-backlog.md
wiki/internal/adr/ADR-*.md as required

Exit gate

Do not recommend starting prompt 03 until tenant resolution, permission semantics, encryption promise, workspace map, and migration boundaries are documented with owners and unresolved decisions clearly identified.

Capablio