Consult Brd Writer

---
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"
house-style: bound

---

# 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)

- **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://platform.zynkr.ai/deals/{deal_id}`

## 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="<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`
- **Folder** — the deal's `notes` carry a `專案資料夾：<url>` 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="<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 <trigger>,
then <observable outcome>." — 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 `<CLIENTSLUG>-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="'<folder id>' 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 = "<filled-in template>"
)
## 2. move it into the client's project folder
mcp__google-workspace__update_drive_file(
  user_google_email = "peter_tu@zynkr.ai",
  file_id     = "<doc id from step 1>",
  add_parents = "<the [N] folder id from step 1 of the workflow>"
)
```

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):

`mcp__zynkr__update_deal` REPLACES `notes` wholesale, so append in three steps:

1. `mcp__zynkr__get_deal(id="<deal_id>")` — read the current `notes`
2. build the new value: the existing notes, then a blank line, then the block below
3. `mcp__zynkr__update_deal(id="<deal_id>", notes="<combined>", confirm=true)`

Call it once without `confirm` to preview, then again with `confirm=true`. Never
send `notes` without the existing text in front of it — the field is overwritten,
not appended, and skipping the read loses every earlier backlink.

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(id="<deal_id>", stage="proposal", confirm=true)`.
  **Only this tool moves a stage.** Writing the column directly changes the stage
  but skips the `stage_change` timeline entry and the automation event, so the
  move stops being visible to anyone reading the deal afterwards.
- **Review task** — "Log a 客戶審閱 follow-up task?" On yes:
  `mcp__zynkr__create_task(deal_id="<deal_id>", …, confirm=true)`. It is created
  as you, on your workspace — no owner id to look up and none to hardcode.

### 8 · Report

A compact artifact table, then the headline in prose:

```
需求文件已產出：宏宇精密 — 報價流程自動化

| 產出 | 內容 |
|------|------|
| 文件 | [BRD] 宏宇精密 — 報價流程自動化（<doc url>）|
| 資料夾 | [4] 宏宇精密（報價流程自動化）|
| CRM backlink | <deal url> — 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.

## 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).

## House style

Writing style is **not owned by this file**. The house voice lives in two Google Docs under
`[@] 寫作指南` (`12DBdFz3SK22ie9im_ThFMI7IBRXsTZsV`), read at runtime:

- 《[2.0] Zynkr 通用風格指南 House Voice》 `10bOIQwRm9Pxwgct4hlwCwK_B4Pipai1HqBPZKzyRHSE` —
  the universal core, plus the addendum for this surface
- 《[3.2] 禁用詞清單 Forbidden Words》 `1N5sHLP4qzmmhpCGsi6KElxi1z0MFe4QZ0Q_35T10Uyg`

Read both before producing client- or reader-facing text, and scan the draft against 《[3.2]》
before handing it over. If Drive is unreachable, say so in the output rather than proceeding
unchecked. Never re-implement either list inside this file.