🛠️ Design Docs

All authorsBar LevybaruchirorelbnsAll statusesdraftshipped5 / 5

Title	Author	Status	Date ▼
Design Doc: Internal Resident ID Verification	relbns	draft	2026-08-18
Feature Spec — Notify Me & Categories	relbns	draft	2026-07-14
Design Doc: Add to Calendar (superco-consumer)	baruchiro, Bar Levy	shipped	2026-06-18
Design Doc: Withdrawals Report	relbns	draft	2026-06-18
Design Doc: Integration Lifecycle Management	relbns	draft	2026-06-09

What lives here: Engineering Design Documents — R&D's translation of a PRD into implementation. The HOW that complements the PRD's WHAT.

Use vs. siblings: a PRD is product's WHAT/WHY; a Design Doc is engineering's HOW. An ADR records a single decision; a Design Doc is broader, scoped to a whole feature.

Template: Design Doc · filename: docs/designs/<slug>-<cu-id>.md

How it gets written: R&D runs /plan-feature against a PRD that has reached ready-for-rd. The command produces a draft; R&D refines.

Every Design Doc traces back to a PRD via related_prd in frontmatter. Every task in §13 Task Breakdown becomes a GitHub Issue via /breakdown, each labeled with the parent ClickUp task.

Lifecycle

Status	What it means
draft	First pass written, perhaps by /plan-feature. R&D refines.
in-review	Architecture-level review (architect agent + human).
approved	Design is locked. Tasks can be broken out and assigned.
in-progress	Engineering building.
shipped	All §16 Definition of Done items checked.
deprecated	Replaced by a newer Design Doc; linked to its successor.

Active Design Docs

Browse the sidebar.

• Integration Lifecycle Management — operator self-service add/edit of integrations on the existing two-collection layout (v1.5 bridge). draft.
• Add to Calendar (superco-consumer) — the event-page "Add to my calendar" modal: what each button does, supported clients, and the UTC-strict timezone decisions (ICS + the outlook.office.com Office 365 button) that settled the Sonoma bugs (CU-86caajc1e). shipped.
• Internal Resident ID Verification — a second resident-eligibility method for authorities with no API: an encrypted per-organization repository of eligible ID numbers, added as a fourth provider behind the existing /auth/citizen contract (CU-86c9qwda5). draft.
• Withdrawals Report — read-only community-admin finance report (per-event withdrawals for one month) mostly assembled from existing platform parts. draft.
• Feature Spec — Notify Me & Categories — umbrella spec for the whole feature: one notify-categories collection (types × up to 3 levels, aliases embedded), keys on residents (notify_categories) and events (custom_filters_keys), governance (L1/L2 canonical, L3 dynamic), phasing (greenfield POC → conditional Phase 0), and the platform feature-flag. The schema derives from it (CU-86c1p963g). draft.
• Notify-Me — Part Design Docs — the feature split into 8 self-contained part-DRs (ontology/admin, tagging, resident prefs, matching & delivery engine [PR-1], content & channels, See-all page, cron, feature-flags). Design docs with acceptance criteria and open questions (CU-86cafrhcy). draft.

Starting a new Design Doc?

Don't start from scratch. Run /plan-feature docs/prds/<slug>-<cu-id>.md — it reads the PRD, resolves UI Composition against @bewith-dev/design-system's COMPONENTS.md, and produces a Design Doc draft with §5 (API), §6 (Components), §7 (Observability), and §13 (Tasks) populated.