# Shared Reference Docs

The `shared/` folder contains reusable context that multiple feature specs can reference instead of restating common personas, invariants, security expectations, observability expectations, and compatibility guidance.

Use these documents when the content is product-wide or common across many distributed-system features. Keep feature-specific behavior, trade-offs, contracts, rollout details, and edge cases inside the relevant folder under `features/`.

## When to Reference Shared Docs

- Reference shared docs when a feature inherits a common concern without redefining it.
- Reference feature-local content when the behavior is specific to one capability, protocol, or workflow.
- Prefer citing stable IDs from `shared/` instead of copying generic text into each PRD.
- Add feature-local exceptions only when the feature intentionally narrows, extends, or deviates from a shared reference.

## Example Usage in a PRD

### Personas

Use persona IDs (and their description) to identify intended users:

- `Primary personas: PER-001 Data Platform Engineer, PER-003 SRE / Platform Operator`
- `Secondary persona: PER-004 Security / Compliance Reviewer`

Using the description inline with the ID makes this easier for humans to read.

### System Invariants

Reference the global invariants a feature must preserve:

- `This feature must preserve INV-GLOBAL-001, INV-GLOBAL-003, and INV-GLOBAL-008.`

### Security Requirements

Link applicable shared requirements and note any exceptions:

- `Applicable shared security requirements: SEC-001, SEC-003, SEC-005, SEC-008.`
- `Exception: SEC-005 does not apply because the feature has no network endpoint.`

### Observability Requirements

Reuse observability expectations rather than redefining standard telemetry rules:

- `Applicable shared observability requirements: OBS-001, OBS-002, OBS-004, OBS-007.`
- `Feature-specific telemetry: add sink retry counters for downstream publish failures.`

## Maintenance Guidance

- Keep the `shared/` folder small and stable.
- Prefer adding durable reference material over feature-specific detail.
- Update shared docs when a rule is broadly reusable across multiple features.
- Leave one-off behavior, migration steps, and implementation choices in feature folders.