crewli/dev-docs/FORM_BUILDER_SCOPE_POLICY.md

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.