--- name: consult-brd-writer sheetId: "2.12" description: >- Turn a consulting engagement's raw discovery material — consult-discovery summaries, shadowing transcripts / recording notes, process findings — into a client-grade requirements document as a Google Doc in the client's numbered [N] Drive project folder, backlinked to the CRM deal. Two modes: BRD (default — business-facing, zh-TW) and PRD (an SDD-conformant buildable spec with a per-client spec ID, EARS-lite ACs and Verify lines). Trigger on /consult-brd-writer or when Peter says "幫我寫 BRD", "把訪談整理成需求文件", "寫 PRD", "把 shadowing 筆記變成 spec", "draft the BRD", "write the PRD for this client", "make this buildable", or hands over discovery notes or a transcript wanting a requirements document out of it — fire eagerly even if he never says the letters "BRD". Distinct from consult-discovery (CONDUCTS the interviews; this skill consumes their output), from consult-project-specialist (logs ONE meeting as a project + deal, writes no requirements doc), and from consult-uat-writer (runs downstream, consuming THIS skill's PRD to produce UAT scripts). category: sales-consultant project: consult-brd-writer platform: claude status: Done author: Peter Tu input: "Discovery summaries and/or a shadowing transcript (pasted text, Google Doc, or Gemini Notes link) + the client's CRM deal URL or company name; optional mode flag (BRD | PRD)" process: "Acquire sources → extract as-is / to-be / requirements → outline approval gate → generate from the BRD or PRD/SDD template → create the Google Doc in the client's [N] folder → backlink to the CRM deal → report" output: "A client-grade BRD Google Doc, or an SDD-conformant PRD spec Doc (spec ID + D-level + AC/Verify lines) ready for the build and for consult-uat-writer" synergy: - "consult-discovery" - "consult-project-specialist" - "consult-shadowing-scheduler" - "consult-uat-writer" --- # Consult BRD Writer ```bash npx skills add https://github.com/peter-tu-zynkr/zynkr-skill-builder --skill consult-brd-writer ``` By the time discovery is done, an engagement has a pile of raw material — consult-discovery summaries, shadowing transcripts, recording notes, process findings — but nothing a client can sign. This skill turns the pile into the document the engagement runs on: a **BRD** (business-facing, zh-TW) by default, or a **PRD** (SDD-conformant buildable spec with AC/Verify lines) when it's time to build — created in the client's numbered `[N]` Drive folder, backlinked to the deal. It is deliberately **not** autonomous end-to-end: requirements docs get signed by clients, so it stops at an outline gate (step 4) — Peter approves the skeleton first, the prose second. ## How this differs from its neighbours - **consult-discovery** — CONDUCTS the pain-point / vision interviews and produces the discovery summaries. This skill sits downstream and consumes them. - **consult-project-specialist** — documents ONE meeting into a project folder + CRM deal, no requirements doc; it creates the workspace this skill writes INTO. - **consult-uat-writer** — downstream of THIS skill: parses the PRD it produces (spec-ID line, AC/Verify pairs, Out of scope) into UAT scripts. ## Fixed facts (don't re-derive these) - **Supabase project_id**: `uomieoqlkazknjgmfdda` (the shared Zynkr project; CRM tables are `crm_*`) - **Google account** for all Gmail/Drive/Docs tools: `peter_tu@zynkr.ai` - **Drive parent folder** (`[2.2] 業務與顧問部門：專案`, where numbered project folders live): `1hkXPX7OXPFOU0BcloPbJSFp8O0zArM8t` - **CRM deal URL** for the doc/report/backlink: `https://zynkr-crm.vercel.app/deals/{deal_id}` - Over the Supabase MCP, `auth.uid()` is **NULL** — every SQL write carries explicit ids (owner via the `crm_users` lookup, exactly as in consult-project-specialist's `references/deal-insert.sql`); never rely on defaults that read the session user. ## Hard rules 1. **Never create a competing folder.** If the client has no `[N]` folder yet, STOP and route to /consult-intake or /consult-project-specialist (step 1). 2. **Never generate the full document before the step-4 gate is approved.** 3. **Client-facing email is ALWAYS a Gmail draft** — if Peter asks to send the doc to the client, use `mcp__google-workspace__draft_gmail_message`. Never send. --- ## Workflow ### 1 · Acquire the sources and resolve the client workspace Discovery material can arrive three ways: - **Pasted text** — use it directly. - **A Google Doc / Gemini Notes link** — read with `mcp__google-workspace__get_doc_content(user_google_email="peter_tu@zynkr.ai", document_id="")`. Gemini Notes docs have a `Notes` tab (summary + action items) and a `Transcript` tab (verbatim) — read both; the transcript carries the real detail. - **Multiple sources** — read all of them; they cross-validate each other in step 3. **Huge transcripts:** a multi-hour shadowing transcript will not survive one-pass extraction. Read it in sections, summarize each section into *process segments* (actor · step · tool · pain · quote), then merge the segment summaries before step 3. Extract from the merged segments, not from raw text. Then resolve the CRM deal and the Drive folder: - **Deal** — from a `…/deals/{id}` URL, or by company name. Prefer `mcp__zynkr__get_deal` / `mcp__zynkr__list_deals` when the zynkr MCP is connected; fallback SQL via `mcp__supabase__execute_sql`: `SELECT id, name, notes, stage FROM crm_deals WHERE name ILIKE '%%' ORDER BY created_at DESC;` - **Folder** — the deal's `notes` carry a `專案資料夾：` backlink (written by consult-intake / consult-project-specialist); extract the folder id from it. If missing, list the parent (`mcp__google-workspace__list_drive_items`, folder_id `1hkXPX7OXPFOU0BcloPbJSFp8O0zArM8t`) and match `[N] Company（…）` by company name. - **No folder at all** → STOP. Tell Peter this client has no project workspace yet and point at /consult-intake (inbound lead) or /consult-project-specialist (meeting debrief). Hard rule 1: never create a competing folder. ### 2 · Pick the mode - **BRD** (default) — business-facing zh-TW requirements doc. Use when unspecified. - **PRD** — when Peter asks ("寫 PRD", "make this buildable"), or when a `[BRD]` doc already exists in the folder (check via `mcp__google-workspace__list_docs_in_folder(user_google_email="peter_tu@zynkr.ai", folder_id="")` — an existing BRD means the engagement has moved to build; propose PRD mode and confirm at the gate). ### 3 · Extract the skeleton From the merged sources, pull the document's bones — with a source tag on every claim (which interview / transcript section it came from): - **Stakeholders** — who appeared, role, what they own in the process. - **As-Is flow** — the current process step by step; mark manual vs system nodes. - **Pains → numbered requirements** — each pain becomes an `R-n` requirement (title · description · 必要/重要/加分 priority · source). Numbers are permanent: once issued, never reshuffled. - **Scope line** — what's in, and explicitly what's NOT (the 不做什麼 list matters as much as the backlog). - **Success metrics** — baseline → target → how measured. **PRD mode adds:** each requirement becomes an EARS-lite AC — "When , then ." — with a concrete *Verify:* line the CLIENT can watch happen (a click path, a query, a file appearing; never "tests pass"). Size per SDD §2.1 and pick the DoD rung; **client data / schema / auth / money ⇒ D3** — say which trigger fired. ### 4 · GATE — outline approval Present, and then **wait**: 1. The proposed document outline (section by section). 2. The numbered requirement list (or AC list in PRD mode) — one line each. 3. **Open questions** — anything the sources left ambiguous, as explicit asks. 4. The proposed mode + title (and, PRD mode, provisional size/DoD). Peter replies approve / adjust; re-gate only if the requirement list itself changed. Hard rule 2: no full-document prose before this gate clears. ### 5 · PRD mode only — assign the spec ID Per-client spec IDs, format `-NNN` (e.g. `ACME-001`): - **CLIENTSLUG** — a 3–5 letter latinization of the company name (宏宇精密 → `HYP`; ACME Corp → `ACME`). Reuse the slug from the client's existing `[PRD]` docs if any exist — never mint a second slug for the same client. - **NNN** — 1 + the highest existing number, discovered by scanning the client's folder for docs titled `[PRD]`: `mcp__google-workspace__search_drive_files(user_google_email="peter_tu@zynkr.ai", query="'' in parents and name contains '[PRD]'")` - **The Doc titles ARE the registry** — no central file. That's why the title format in step 6 is load-bearing, and why a retired ID is never reused. ### 6 · Generate the Doc into the `[N]` folder Read the matching template — `./references/brd-template.md` or `./references/prd-spec-template.md` — fill every placeholder, delete the placeholder-guide comment block, and create the Doc via the reliable two-step (creating a Doc directly in a folder via `create_drive_file` returns HTTP 400): ``` ## 1. create the doc (lands in My Drive root) mcp__google-workspace__create_doc( user_google_email = "peter_tu@zynkr.ai", title = "[BRD] {{COMPANY}} — {{PROJECT}}", # or "[PRD] {{SPEC_ID}} — {{TITLE}}" content = "" ) ## 2. move it into the client's project folder mcp__google-workspace__update_drive_file( user_google_email = "peter_tu@zynkr.ai", file_id = "", add_parents = "" ) ``` PRD mode: keep the H1 `# {{SPEC_ID}} — {{TITLE}}`, the `Size / DoD` line, the `**AC-n**` + `*Verify:*` pairs, and `## Out of scope` byte-exact to the template shape — consult-uat-writer parses them (the template's top comment is the contract). ### 7 · Backlink the Doc to the CRM deal (+ offer, don't auto, a stage nudge) Append the Doc URL to the deal's notes (the same pattern consult-intake uses): ```sql UPDATE crm_deals SET notes = notes || E'\n\n需求文件：[BRD] {{COMPANY}} — {{PROJECT}}\n' WHERE id = ''; ``` via `mcp__supabase__execute_sql(project_id="uomieoqlkazknjgmfdda", ...)`. Escape single quotes by doubling them (`O'Brien` → `O''Brien`). Then **ask** two optional follow-ups — never do them unprompted: - **Stage nudge** — "A requirements doc exists now; move the deal to `proposal`?" On yes: `mcp__zynkr__move_deal_stage` when connected, else `UPDATE crm_deals SET stage = 'proposal' WHERE id = '';` - **Review task** — "Log a 客戶審閱 follow-up task?" On yes: `mcp__zynkr__create_task` when connected, else the `('task', …)` VALUES row from `./references/deal-insert.sql` (explicit `created_by`/`assignee_id` — auth.uid() is NULL). ### 8 · Report A compact artifact table, then the headline in prose: ``` 需求文件已產出：宏宇精密 — 報價流程自動化 | 產出 | 內容 | |------|------| | 文件 | [BRD] 宏宇精密 — 報價流程自動化（）| | 資料夾 | [4] 宏宇精密（報價流程自動化）| | CRM backlink | — notes 已附文件連結 | | 需求數 | R-1 … R-7（必要 4 · 重要 2 · 加分 1）| | 待 Peter | 2 個 open questions（見上）· stage nudge 未執行 | ``` PRD mode adds a spec-ID + DoD row (e.g. `HYP-002 · M / D2`) and notes the doc is ready for consult-uat-writer. --- ## Why it's built this way - **Gate before prose.** consult-intake runs autonomously because its artifacts are cheap and internal; a requirements doc is client-visible and quasi-contractual — the gate is where a wrong list is still cheap to fix. - **The folder is resolved, never created.** One numbered workspace per engagement is the invariant the whole 2.x suite leans on; a second folder for the same client would fork the record. Hence the hard STOP. - **Doc titles as the spec-ID registry.** A central registry file would need its own home and sync story for a per-client sequence that rarely passes 010. Scanning `[PRD]` titles in the folder is slower but cannot drift from reality. - **PRD structure is a parsing contract, not a style.** consult-uat-writer reads the H1, Size/DoD, AC/Verify pairs, and Out of scope mechanically; the template carries the contract comment so nobody breaks it unknowingly. ## Inference defaults (Peter overrides by just saying so) - **Mode** → BRD; PRD only on request or when a `[BRD]` already exists (step 2). - **Doc language** → zh-TW body for BRD; PRD is English-canonical structure with zh-TW client-facing strings quoted verbatim in 「」. - **Requirement priority** → 必要 only when the client said so or the as-is flow breaks without it; otherwise 重要; 加分 for pure nice-to-haves. - **PRD size/DoD** → when ambiguous, size UP (SDD §2.1); client data / schema / auth / money always ⇒ D3. - **BRD version** → `v0.1（草稿）`; bumps to `v1.0` on client confirmation. - **Stage nudge / review task** → OFF; offered in step 7, executed only on a yes. ## Reference files - `./references/brd-template.md` — the zh-TW client-grade BRD skeleton (fill, then delete its placeholder-guide comment). - `./references/prd-spec-template.md` — the SDD-conformant PRD template; its top comment is the consult-uat-writer parsing contract. - `./references/deal-insert.sql` — the SQL patterns (live owner lookup, quote-escaping, task VALUES row) the step-7 fallbacks reuse; copied from consult-project-specialist so this skill installs self-contained. ## Limitations - Consumes discovery material; it will not interview anyone (consult-discovery) or bootstrap a missing workspace (consult-intake / consult-project-specialist). - Requirements come only from the provided sources — thin discovery yields a thin BRD with more open questions at the gate; it never invents requirements. - The spec-ID scan sees only docs titled `[PRD]` inside the client's `[N]` folder; a spec doc renamed away from that convention escapes the registry. - One document per run. "BRD + PRD both" = two runs (BRD first — the PRD cites it).