# PRD — Rosewood Master Client Questionnaire (Drupal Webform)

**Status:** Draft for review
**Owner:** Rosewood Marketing
**Last updated:** 2026-06-17
**Platform:** Drupal 11.3 · Webform · DDEV (`questionnaire.ddev.site`)

---

## 1. Purpose

Rosewood uses seven separate client questionnaires. Many questions repeat across
them. Today a client who engages in multiple services answers the same question
several times, and staff re-collect data they already have.

This project consolidates all seven into **one master web form** with **seven
variants**. Each variant shows only the questions relevant to that service, in
that questionnaire's familiar order. Because shared questions are backed by a
single underlying field, **an answer entered in one variant is automatically
present when the same client record is opened in another variant** — answer once,
reuse everywhere.

A staff-facing page lists, for any single client record, one link per variant —
all pointing at the **same result**, each rendering a **different variant**.

---

## 2. Goals & Non-Goals

### Goals
- One master webform containing every unique question across the 7 source docs.
- One submission = one "client questionnaire result" (a single client/engagement).
- 7 variants, each a filtered + reordered view of that one form.
- Shared questions prefill across variants automatically (same submission, same key).
- A page that, for a given result, links to all 7 variants of that same result.
- Clients fill variants via secure links; no client login accounts required.
- Built and configured entirely with Drush + config (no MCP/extra tooling).

### Non-Goals (v1)
- No client-facing account system / login.
- No automated email/notification workflows (revisit with ECA later if wanted).
- No reporting/BI dashboards beyond Webform's built-in submission views/exports.
- Not migrating any historical/legacy submissions.

---

## 3. Source Material

Seven source questionnaires plus a pre-built analysis spreadsheet
(`questionnaires/rosewood_question_matrix.xlsx`). The matrix has already
deduplicated the content: **173 raw questions → 47 canonical clusters**
(26 shared across 2+ docs, 21 unique to one doc).

| # | Variant name (this project)                    | Code | Source doc                              | Qs | % overlap |
|---|------------------------------------------------|------|-----------------------------------------|----|-----------|
| 1 | Marketing Strategy Consultation Questionnaire  | MSC  | Silver MSC Questionnaire                 | 66 | 33%       |
| 2 | Core Messaging Questionnaire                    | CMQ  | Core Messaging Template                  | 39 | 49%       |
| 3 | Naming Questionnaire                            | Name | Naming Creative Brief                    | 16 | 69%       |
| 4 | Branding Questionnaire                          | BI   | Brand Identity Questionnaire             | 17 | 76%       |
| 5 | Website Questionnaire — Client                  | WPQ  | Website Project Questionnaire            | 13 | 38%       |
| 6 | Website Questionnaire — Marketing Guide         | MGW  | Marketing Guide Website Project Q.       | 9  | 56%       |
| 7 | CRM Questionnaire                               | CRM  | Client Questionnaire for CRM             | 13 | 62%       |

The matrix's **Master Intake Form** and **Cluster Matrix** tabs are the
authoritative source for: which cluster appears in which variant, the original
per-doc question number/wording, and the canonical merged wording.

---

## 4. Key Decisions (confirmed)

| Topic | Decision | Implication |
|-------|----------|-------------|
| **Respondents / access** | Clients fill via **secure links** (anonymous, per-submission secure token). The links page sits behind staff login. | Use Webform's secure-token submission editing. No client accounts. Each variant link carries the submission's token + variant code. |
| **Shared-question wording** | **MSC-priority original**: use the MSC question's original wording where the cluster exists in MSC; otherwise the wording from the first source questionnaire that contains it (per the build order below). | A shared element has exactly one label. Wording is sourced literally from a questionnaire, not the merged "canonical" rewrite. |
| **Compound questions / field types** | **Hybrid, leaning structured** — driven by each PDF's actual layout. Where a structured widget improves UX (multiple choice, number, rating), use it. The competitor comparison must use a **format that's easy to compare** (table/grid). Some sub-question groups stay a **single textarea with the sub-questions listed inside**. | Per-question field types determined from PDF review → **Appendix A** (separate reviewable spec). |
| **Per-variant question order** | **Original questionnaire order** — each variant displays its questions in that source doc's own Q# sequence. | Variant rendering reorders elements per variant; master storage order is independent. |

---

## 5. Architecture

### 5.1 Single master webform, single submission
- One webform, machine name e.g. `master_questionnaire`.
- Every one of the 47 canonical clusters becomes one or more elements with
  **stable machine keys** (e.g. `mission_statement`, `target_audience`,
  `competitors`). Compound clusters may expand to several keys per Appendix A.
- One submission (`sid`) = one client questionnaire result. All variants read and
  write that same submission, so shared answers are inherently consistent — this
  satisfies the "answer once, prefilled elsewhere" requirement with no custom
  sync logic.

### 5.2 Master element ordering (storage)
Built by **accretion in the project's stated order**: start with all MSC
questions in MSC order; then append CMQ's not-yet-present questions in CMQ order;
then Naming; Branding; Website–Client; Website–Marketing Guide; CRM. Duplicates
reuse the already-created element. This defines the element array; **visual order
per variant is overridden separately** (see 5.3).

### 5.3 Variant subsetting + reordering
Webform's built-in *Variants* feature is geared to A/B testing and can hide
elements but does not cleanly reorder them. Because we need **both** a per-variant
subset **and** a per-variant order, we use a **small custom module**
(`rosewood_questionnaire`):

- A data map (config or PHP) lists, per variant code, its member element keys **in
  that variant's display order** — generated directly from the matrix.
- A form alter (keyed on the `variant` query parameter, e.g. `?variant=cmq`):
  - sets `#access = FALSE` on elements not in the variant,
  - assigns `#weight` to member elements to enforce the variant's order.
- Default (no/unknown `variant`) renders the full master form (staff use).

This is reliable, fully under our control, and keeps everything in one webform/one
submission.

### 5.4 Access model — secure links
- Enable Webform's **secure-token submission update** so an anonymous client can
  open and edit a specific submission via a tokenized URL.
- Variant URL shape:
  `…/form/master_questionnaire/{sid}/edit?token={SECURE_TOKEN}&variant={code}`
- Submission create + token management stays staff-side. Clients only ever receive
  the tokenized links.

### 5.5 The links page (staff-facing)
- For a chosen submission, render the **7 variant links** (same `sid` + token,
  different `variant`).
- Implementation: a lightweight route/controller (or Views) provided by the custom
  module, listed behind a staff permission. No ECA required.

### 5.6 Why not alternatives
- *Seven separate webforms*: separate submissions ⇒ no shared prefill. Rejected.
- *ECA for the links*: links are just computed strings from `sid`/token/variant;
  ECA adds dependency without need. Deferred to future automation only.

---

## 6. Field-Type Strategy

Default to a **textarea** per cluster (sub-questions listed in the element's
description), and **upgrade to a structured widget where the PDF shows discrete
structure and it improves UX**. Representative mappings (final list in Appendix A):

| Cluster / question | Proposed widget |
|--------------------|-----------------|
| Most free-text questions | Textarea (sub-parts in help text) |
| Competitor listing (top 3: strengths, weaknesses, pricing tier, differentiation) | **Table/grid** (3 rows × comparison columns) for easy side-by-side comparison |
| 12-month financials (gross sales, COGS, gross profit, fixed expenses, net income) | Group of **number** fields |
| Marketing-channel effectiveness (22 channels: Good/Fair/Poor) | **Likert/rating matrix** |
| Paired-adjective brand scale (Formal–Casual, etc.) | **Likert/scale** rows |
| Current logo feeling (Embarrassed → Very Inspired) | **Radios / scale** |
| "Do you use a CRM? / email platform?" (yes-no + which) | **Radios** + conditional text |
| Website main purpose (a–f options) | **Checkboxes/radios** + "Other" |
| Design tier (Bronze / Silver / Gold) | **Radios** |
| Quality / Service / Price ranking | **Rank / ordered** widget |

Appendix A will lock the widget, machine key, required-state, and options list for
every element, sourced from the PDFs.

---

## 7. Build Plan (phased)

1. **Install** — `composer require drupal/webform`; `drush en webform webform_ui`;
   confirm secure-token submission editing is available.
2. **Element spec (Appendix A)** — review all 7 PDFs; produce the per-cluster
   element table (key, label [MSC-priority wording], widget, options, variant
   membership, per-variant order). **You review this before build.**
3. **Master webform** — generate `webform.webform.master_questionnaire.yml` from
   Appendix A; import via `drush config:import --partial` (or a `drush php:script`).
4. **Custom module** `rosewood_questionnaire` — variant map + form alter
   (subset/reorder) + links page route + staff permission.
5. **Access** — configure secure-token editing; verify anonymous tokenized edit.
6. **Verify** — for a test submission: each variant shows the right subset in the
   right order; a value entered in one variant prefills in another; the links page
   produces 7 working links to the same `sid`.
7. **Export config** — `drush config:export -y`; commit.

---

## 8. Tooling

- **Drush 13.7** + direct config/YAML authoring is sufficient; no MCP server or
  extra CLI needed. Webform definitions are config entities (`elements` is one YAML
  block), which we generate from the matrix and load via config import / php script.
- Config managed per repo conventions (`config/sync`, partial imports).
- Module config that ships with the build lives in the module's `config/install`.

---

## 9. Open Questions / Risks

1. **Appendix A is the real work.** Field-type fidelity depends on PDF review and
   your sign-off; the competitor-comparison and matrix-style widgets are the most
   layout-sensitive. (All 7 PDFs confirmed text-extractable via `pdftotext`,
   including the Marketing Guide doc — no screenshots needed.)
2. **Variant order ties** — where a variant's source doc and the matrix disagree on
   a shared question's position, we follow the **source doc** (decision §4).
3. ~~**Token lifecycle**~~ — **Resolved:** secure links **do not expire**. The
   links page is visible to **all logged-in (authenticated) users** for now
   (revisit with a dedicated permission/role later if needed).
4. ~~**Required fields**~~ — **Resolved:** all questions **optional**, with **draft
   save** enabled so clients can save partial progress and return later.
5. ~~**One submission per client**~~ — **Resolved:** **one result spans all of a
   client's variants** (one submission, all seven variants read/write it).

---

## 10. Appendix A — Element Specification (to be produced)

A complete table of all elements: machine key · label (MSC-priority wording) ·
widget type · options/sub-fields · required · variant membership · per-variant
order. Generated from the 7 PDFs + matrix, delivered for review before Phase 3.