From 2b16d4fd8f8b8919c44f8277eab3b6f7d0f245e0 Mon Sep 17 00:00:00 2001 From: "bert.hausmans" Date: Fri, 24 Apr 2026 10:18:44 +0200 Subject: [PATCH] docs(policy): add Form Builder scope discipline policy Deferred-work guidance for Form Builder expansions. Prevents speculative building for hypothetical use cases while preserving the one justified forward-looking investment (polymorphic subject picker in S3b). Based on April 2026 coverage analysis of ~60 practical form use cases. --- dev-docs/FORM_BUILDER_SCOPE_POLICY.md | 132 ++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 dev-docs/FORM_BUILDER_SCOPE_POLICY.md diff --git a/dev-docs/FORM_BUILDER_SCOPE_POLICY.md b/dev-docs/FORM_BUILDER_SCOPE_POLICY.md new file mode 100644 index 00000000..348cd81c --- /dev/null +++ b/dev-docs/FORM_BUILDER_SCOPE_POLICY.md @@ -0,0 +1,132 @@ +# Form Builder — Scope Discipline Policy + +**Status:** Guidance policy. Applies to all Form Builder and adjacent +module work in Crewli until explicitly superseded. + +## Context + +April 2026: analysis of ~60 practical form use cases against the +current Form Builder architecture confirmed that the polymorphic +owner/subject model, the 17 field types, and the event-listener +integration pattern form a generic foundation that scales. Of the +60 use cases surveyed, ~70% fit the existing architecture with +incremental work (new listener or new field type per use case), and +~19% require separate domain architectures outside the Form Builder. + +**This is reassurance, not a work order.** The full coverage of 60 +use cases represents 4-5 months of fulltime solo work. Bert's actual +near-term needs — his own volunteer organisation plus the first +handful of potential SaaS customers — are estimated at 5-8 concrete +form types, not 60. + +## Policy + +### 1. No speculative purpose-specific work + +Do not build listeners, field types, purpose enum values, or UI +flows for form purposes that no current user (Bert's own +organisation or a named prospect) has concretely requested. + +This explicitly includes: + +- Artist advance module — defer until a festival with real tech + riders needs it +- Supplier intake module — defer until a supplier-intensive event + is in the pipeline +- Post-event evaluation module — defer until Bert's own event + actually finishes and needs retrospective tooling +- Compliance flows (W9, insurance claims, GDPR workflows beyond + existing ARCH §13) — these are separate projects, not Form + Builder features +- Real-time operational forms (meal tickets, inventory counts, + live capacity) — these belong to dedicated modules (check-in, + inventory), not Form Builder + +Any prompt that asks to extend the Form Builder for one of these +should be questioned back to Bert with: "Do you have a concrete +user who needs this in the next 8 weeks, or is this speculative?" + +### 2. One architectural exception: polymorphic subject picker in S3b + +The organiser-facing form creation UI in S3b must include a +subject-type picker (dropdown or equivalent) that writes to +`form_schemas.subject_type` when configured, even though only +`person` is functionally wired in S3b. + +Options to surface in the picker: + +- Vrijwilliger / deelnemer (subject_type='person') — functional +- Artiest (subject_type='artist') — disabled / "binnenkort beschikbaar" +- Leverancier (subject_type='company') — disabled / "binnenkort beschikbaar" +- Anoniem publiek (subject_type=null) — functional for PUBLIC_COMPLAINT / PUBLIC_RSVP / POST_EVENT_EVALUATION + +**Why this is the exception:** retrofitting a subject-type picker +later requires touching the create/edit/list views, the schema +configuration form, the binding config UI, and the sibling-endpoint +logic — days of rework. Building the UI shell with disabled options +now is ~2 extra hours in S3b and eliminates that future refactor. + +This is the only forward-looking architectural investment permitted +without a concrete user request. + +### 3. Economic triggers for future Form Builder expansion + +Unlock categories of work only when one of these signals fires: + +| Expansion | Trigger | +|---|---| +| FILE_UPLOAD + IMAGE_UPLOAD + SIGNATURE field types | A required form (VOG upload, minor consent, press accreditation) has a concrete submitter waiting | +| Artist advance module | A festival with >3 booked artists needs digital tech riders | +| Supplier intake module | An event has >3 suppliers where paper/email intake has become painful | +| New purpose enum value | A concrete form use case requires it AND that use case has a named user | +| Shift-swap request flow | Volunteers have asked for it twice in production | + +Explicitly do NOT unlock expansions because: + +- The architecture supports it elegantly +- It would be "nice to have" +- A competitor has it +- It appears on an aspirational feature list + +### 4. When reviewing prompts for Form Builder work + +If a prompt asks Claude Code to extend the Form Builder in ways +not justified by a concrete user or by the S3b subject-picker +exception above, push back before implementing. Ask Bert: + +1. Which concrete user needs this in the next 8 weeks? +2. Is there a simpler path (manual admin action, existing UI, + out-of-scope) that would work for now? +3. If we defer this 6 months, what actually breaks? + +Proceed only when answers are concrete (named person / event / +deadline), not hypothetical ("a customer might want this"). + +### 5. Where this policy does NOT apply + +This policy scopes Form Builder and its direct integrations. It +does NOT apply to: + +- The S3b organiser UI itself (build it well, it unlocks Category A + use cases immediately) +- Bug fixes and polish on shipped Form Builder features +- Documentation of existing behaviour +- Refactors that reduce technical debt in already-shipped code +- Unrelated modules (check-in, accreditation, briefings, + communication, production) — those have their own prioritisation + +### 6. Record of decisions + +When this policy causes a feature to be deferred, record it briefly +in `/dev-docs/BACKLOG.md` with the trigger that would unblock it. +This keeps the deferred list visible without pretending it's +actionable today. + +## Closing note for Claude Chat + +If planning work that would touch Form Builder scope beyond this +policy, flag it at the start of the session: "This touches +scope-deferred Form Builder work; confirming trigger before +proceeding." Then wait for Bert's confirmation. This is a +discipline guardrail, not a veto — but the default answer is "not +yet" until a concrete trigger exists.