| name | design-rationale |
| description | Use when proposing new features, reviewing code changes, evaluating integration requests, or onboarding to KoNote — checks proposals against Design Rationale Records (DRRs) to identify conflicts with established architectural decisions, rejected anti-patterns, and privacy/security constraints before implementation begins. |
Design Rationale Review
Review proposed features and code changes against KoNote's Design Rationale Records (DRRs) — expert-vetted architectural decisions that govern privacy, security, data modelling, and feature design. Prevents re-introducing designs that were already evaluated and rejected.
When to Use
- A client, stakeholder, or developer proposes a new feature or integration
- A PR or code change touches areas governed by DRRs (auth, data access, AI, reporting, encryption, data export)
- Onboarding a new developer who needs to understand why things are designed a certain way
- Evaluating whether a "Parking Lot" feature is ready to build
- Someone asks "why can't we just...?" about an architectural constraint
Workflow
digraph review_flow {
rankdir=TB;
"Describe the proposal" [shape=box];
"Match keywords to DRR index" [shape=box];
"Read each relevant DRR" [shape=box];
"Any anti-pattern matches?" [shape=diamond];
"CONFLICT: Report with DRR citations" [shape=box, style=filled, fillcolor="#ffcccc"];
"Any graduated paths triggered?" [shape=diamond];
"CAUTION: Conditions may now be met" [shape=box, style=filled, fillcolor="#ffffcc"];
"CLEAR: No conflicts found" [shape=box, style=filled, fillcolor="#ccffcc"];
"Describe the proposal" -> "Match keywords to DRR index";
"Match keywords to DRR index" -> "Read each relevant DRR";
"Read each relevant DRR" -> "Any anti-pattern matches?";
"Any anti-pattern matches?" -> "CONFLICT: Report with DRR citations" [label="yes"];
"Any anti-pattern matches?" -> "Any graduated paths triggered?" [label="no"];
"Any graduated paths triggered?" -> "CAUTION: Conditions may now be met" [label="yes"];
"Any graduated paths triggered?" -> "CLEAR: No conflicts found" [label="no"];
}
Step 1: Identify the Proposal
Get a clear description of what's being proposed. This can come from:
- The user's message (e.g., "a client wants a live API for participant data")
- A PR diff (e.g., code adding a new endpoint or model)
- A feature request or TODO item
If the proposal is vague, ask: "What data does this touch? Who initiates the action? Does it cross the boundary of a single KoNote instance?"
Step 2: Find Relevant DRRs
Read @.claude/skills/design-rationale/drr-index.md and match the proposal's keywords to the topic index. Cast a wide net — a "webhook notification" proposal touches API, data export, AND privacy DRRs, not just the obvious one.
Always start with the relevant Foundation Principle:
- Participant-facing, note design, bilingual, or accessibility changes ->
foundation-collaborative-practice.md
- Data sharing, cross-agency, community data, demographics ->
foundation-data-sovereignty.md
- Auth, permissions, encryption, exports, logging ->
foundation-security-by-default.md
- New dependencies, hosting, cost, deployment, evaluation ->
foundation-nonprofit-sustainability.md
Then check implementation-level DRRs:
- Any data leaving a KoNote instance ->
no-live-api-individual-data.md
- Any new permission or visibility logic ->
access-tiers.md, phipa-consent-enforcement.md
- Any new entity or relationship type ->
circles-family-entity.md, fhir-informed-modelling.md
- Any AI/LLM feature ->
ai-feature-toggles.md, self-hosted-llm-infrastructure.md
- Any reporting or aggregate data ->
reporting-architecture.md, cids-privacy-architecture.md
- Any infrastructure change ->
ovhcloud-deployment.md, data-access-residency-policy.md
Step 3: Read and Assess Each DRR
For each relevant DRR, read the full file from tasks/design-rationale/ and check:
- Anti-Patterns section: Does the proposal match any explicitly rejected design? Quote the specific anti-pattern.
- Expert Panel Findings: What were the reasons for the current design? Do they still apply?
- Graduated Complexity Path: Did the DRR say "reconsider when X happens"? Has X happened?
- Status: Is this Decided (enforce), Draft (read but flexible), or Parking Lot (don't build)?
Step 4: Produce the Review
Structure your output as follows:
Proposal: [one-line summary]
DRRs Consulted: [list of files read]
Verdict: CONFLICT / CAUTION / CLEAR
Findings:
For each relevant DRR:
- [DRR name] — [Conflict | Caution | Clear]
- What the DRR says (quote the anti-pattern or decision)
- How the proposal relates
- What to do instead (if conflict)
Recommendation: [approve / modify / reject, with specific guidance]
Review Depth by Context
| Context | Depth |
|---|
| Client feature request | Full review — check all keyword matches |
| PR code review | Targeted — focus on DRRs related to changed files |
| Quick "can we do X?" question | Index scan — cite the relevant DRR and its verdict |
| New developer onboarding | Explain the reasoning, not just the rule |
Common Proposals and Their DRR Verdicts
These come up repeatedly. The answers are settled:
| Proposal | Verdict | Key DRR |
|---|
| Live API for individual PII | Rejected | no-live-api-individual-data.md |
| Webhook/push notifications with PII | Rejected | no-live-api-individual-data.md |
| Bidirectional CRM sync | Rejected | no-live-api-individual-data.md |
| FHIR server or FHIR API | Rejected | fhir-informed-modelling.md |
| Row-level multi-tenancy | Rejected | multi-tenancy.md |
| Per-agency LLM deployment | Rejected | self-hosted-llm-infrastructure.md |
| Person-to-person global relationships | Rejected | circles-family-entity.md |
| Executives seeing individual data in reports | Rejected | reporting-architecture.md, access-tiers.md |
| AI features accessing PII without toggle | Rejected | ai-feature-toggles.md |
| PWA for offline field work | Rejected | offline-field-collection.md |
| Translation as optional/toggleable | Rejected | bilingual-requirements.md |
| Hosting outside Canada | Rejected | data-access-residency-policy.md |
| English-only UI (no French) | Rejected | foundation-collaborative-practice.md, bilingual-requirements.md |
| Inaccessible portal features | Rejected | foundation-collaborative-practice.md |
| Cross-agency individual data combination | Rejected | foundation-data-sovereignty.md, multi-tenancy.md |
| Staff-initiated JSON/PDF export | Approved | no-live-api-individual-data.md |
| Aggregate cross-agency reporting | Approved with constraints | cids-privacy-architecture.md (k>=5) |
| FHIR-informed model naming | Approved | fhir-informed-modelling.md |
When a DRR Needs Updating
If you find that:
- A "reconsider when" condition has been met
- New information invalidates the original reasoning
- A client need genuinely can't be met by the approved alternatives
Do not override the DRR. Instead:
- Document the new evidence
- Flag for GK (subject matter expert) review
- If approved, update the DRR file before implementing the change
