Template usage: this is the required artifact before writing implementation code on work in "unexplored space" (per CLAUDE.md § Design Gate). Copy this file to docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md, fill every section, and get user sign-off before any code.

Every section is mandatory. If a section does not apply, write "n/a — <reason>" rather than deleting it. The empty-but-present rule is what makes the artifact a forcing function.

Delete this blockquote before submitting.

---

1. Problem distillation

<3–5 bullets restating what this work actually solves, in your own words, distilled from the US text — not a paste of the US>

Success criteria (observable behavior that proves this works): - <…>

Non-goals (in-scope-shaped things this iteration is explicitly not doing): - <…>

---

2. Patterns survey

Enumerate every existing module, spec, or chapter that solves an analogous problem. Minimum 3 rows. Each row must include a real link to a file in this repo — git grep and docs/REFERENCE.md §4 module map are the starting points.

Analogous module/spec	What we'd borrow	What doesn't fit
<src/<module>/ or docs/superpowers/specs/<file>.md>

---

3. Architecture mapping

How this work lands on existing primitives. Every row must be filled — write "n/a — <why>" rather than skip.

Primitive	Apply?	How	Justify
Tenant scope	yes / no	tenantId is enforced, or platform-preset exception>
Academic-year scope	yes / no	academicYearId is filtered on reads/writes>
RBAC entity key		<src/common/constants/entity-keys.ts delta>
Scopes
Actions		read and update are implicit>
Service base	BaseTenantedCrudService / custom
queries.ts shape
Error codes		ErrorCode entries + params shape>
DTO conventions		dto/>
File-backed sub-resources	single-slot / collection / n/a	<FileUsage entry, owner type, metadata fields>
Custom fields	yes / no	pickCustomFields plugs in, or n/a>
Profile completeness	yes / no	src/common/constants/completion-required-fields.ts>

---

4. Data model plan

Schema deltas

Migration shape

• Additive / destructive / renaming:
• Data backfill:
• Hazards from chapter 12 checklist:

Indexes and uniqueness

---

5. API surface

Verb	Path	Decorators	Request DTO	Response DTO
		@RequireScopes(...), @RequireAction(...)

Swagger considerations

• oneOf shapes, anything Scalar autoinspection won't pick up>

---

6. RBAC seed plan

Seed file	Delta
PermissionScope (rbac-catalogue.ts)
PermissionAction (rbac-catalogue.ts)
ScopeFieldMapping (rbac-catalogue.ts)
Role grants (roles.ts)
*_SCOPES runtime constant	src/common/constants/scope-fields.ts to match seed>

---

7. Divergence ledger

Where this design departs from an existing pattern. Must exist. If nothing diverges, write a single row stating "None — fits <pattern> end-to-end".

Pattern	We diverge by	Reason	Tradeoff accepted

---

8. Pushback log

Where the US text (ClickUp Gherkin, user description, or prototype) conflicts with patterns, architecture, or prior decisions. Must exist. If no pushback, write a single row stating "None — US fits patterns as written".

US says	Conflicts with	Proposed instead	Status
			Open / Resolved

---

9. Deferrals

What this iteration explicitly does NOT do, and where the follow-up lives.

• — — follow-up:

---

10. Open questions

Blockers requiring user resolution before code starts. Must be empty (all resolved) before sign-off.

---

11. Verification plan

• Unit specs: *.spec.ts files, what each asserts>
• E2E specs: *.e2e-spec.ts files, which Gherkin scenarios from the US they cover>
• Manual verification:

Patterns: chapter 09 (testing), and feedback_e2e_isolation_patterns.md for E2E discipline.

---

12. Sign-off

• Approved by:
• Date:
• Chat reference:

Until this section is filled, no implementation code is written.