Dossier Builder

---
name: dossier-builder
description: Use to generate a printed market-research dossier (8-page HTML + PDF) the buyer brings to the dealer at test drive, summarizing buyer profile, regional comps, target OTD, and cross-bid anchors. Triggers include "build dossier", "generate market research PDF", "dealer dossier", "decision document", "make dossier for dealer", "生成 dossier", "制作 PDF", and Spanish phrases "generar el dossier para el concesionario", "crear el PDF de investigacion de mercado".
---

# Decision Dossier Builder

> **Caveat**: this skill is one author's playbook + 5-scenario stress test. Verify state fees / CPO terms / EV credits / dealer practices against current sources before quoting numbers to a dealer or making financial decisions. Not tax, legal, or financial advice.
> **last_verified**: 2026-05-18 (Phase 3C sub-skill split from orchestrator)

Narrow helper: drive `generate_dossier.py` to produce the 8-page HTML + PDF
dossier the buyer hands the salesperson at test drive. Defers the script,
templates, and YAML schema to the orchestrator's `scripts/` and `assets/`.

## When To Use

- Buyer is ready for the in-store visit and wants a printable evidence packet
- Need EN or CN version (CJK template available)
- Buyer has comp anchors collected (XHS / Reddit / cross-bids) and wants
  them formalized into a single document

## When NOT To Use

- Still in Phase 1 (criteria not locked) - too early; orchestrator first
- Quote evidence not yet collected - delegate to `quote-evidence-collector`
- Just need an OTD calculation - delegate to `otd-calculator`

## 3-Step Workflow

1. Copy `../orchestrator/assets/dossier_config_template.yaml` to a working
   file (e.g. `my_dossier.yaml`) and fill in 8-15 fields.
2. Run:
   ```
   python ../orchestrator/scripts/generate_dossier.py \
     --config my_dossier.yaml \
     --output dossier.html \
     --to-pdf dossier.pdf
   ```
3. (Optional) Chinese template:
   ```
   python ../orchestrator/scripts/generate_dossier.py \
     --config my_dossier.yaml \
     --template ../orchestrator/assets/dossier_template_cn.html \
     --output dossier_cn.html \
     --to-pdf dossier_cn.pdf
   ```
4. (Optional) Spanish (US) template:
   ```
   python ../orchestrator/scripts/generate_dossier.py \
     --config my_dossier.yaml \
     --template ../orchestrator/assets/dossier_template_es.html \
     --output dossier_es.html \
     --to-pdf dossier_es.pdf
   ```

## Required YAML Fields

- `BUYER_NAME`, `BUYER_ADDRESS`, `DATE`
- `YEAR`, `MAKE_MODEL`, `TRIM`, `MSRP`
- `TARGET_OTD`, `TARGET_SALE`
- `STATE`, `TAX_RATE`
- At least 2 `COMP_VEH_N` entries (other dealer listings as comp anchors)

## Optional YAML Fields

- `WALK_AWAY_CEILING` - recommended; gives the buyer a clear stop number
- `REGIONAL_AVERAGE` - Edmunds / TrueCar reference price
- `REDDIT_OTD_REPORT_1`, `_2`, `_3` - real buyer-reported OTDs (up to 3)
- `CPO_PROGRAM` - if vehicle is CPO; populates p3 with program benefits
- `INCENTIVE_STACK` - manufacturer rebates + state credits (EV, loyalty, etc.)

## 8-Page Dossier Structure

| Page | Contents |
|---|---|
| 1 | Buyer profile + target summary + close-timing claim |
| 2 | Regional market average (Edmunds / TrueCar) |
| 3 | Trim / option breakdown + MSRP anchors |
| 4 | Competing OTD quotes - first 2-3 cross-bid evidence rows |
| 5 | Competing OTD quotes - continued, plus Reddit reports |
| 6 | Internal anchor analysis (dealer's own concurrent inventory) |
| 7 | Proposed OTD with structured paths (best / target / walk) |
| 8 | Conditions of sale (CARFAX request, PPI booked, plate transfer decision) |

## Script Behaviors

From `../orchestrator/scripts/generate_dossier.py`:

- Cross-platform Chrome / Edge auto-detection (Windows / macOS / Linux); uses
  headless Chrome for HTML-to-PDF
- Placeholder validation: scans template for ALL `{{KEY}}` tokens BEFORE
  substitution, fails loudly if any required key is missing
- `--allow-missing` opt-out for incomplete configs (PDF will render
  `{{KEY}}` literal text for missing keys - useful for drafts)
- Auto-detects `CHROME_BIN` environment variable as override

## Template Variants

- EN (default): `../orchestrator/assets/dossier_template.html`
- CN: `../orchestrator/assets/dossier_template_cn.html` (CJK glyph support)
- ES (US): `../orchestrator/assets/dossier_template_es.html` (US-market Spanish)

The CN and ES templates are field-for-field equivalent (identical `{{KEY}}`
placeholder set); the same YAML config drives all three. CN is useful when the
buyer is Chinese-American and wants to share with parents / spouse before
signing; ES when the buyer or a co-signer is more comfortable in Spanish, or
for a Spanish-speaking dealer. The ES template uses verified US-Latino
automotive-finance terminology (precio final / OTD, cargo por documentacion =
doc fee, vehiculo a cuenta = trade-in, cheque de caja = cashier's check,
vehiculo usado certificado = CPO, titulo de salvamento = salvage title);
pending a native-speaker / Codex review pass before high-stakes use.

## Common Errors and Fixes

| Error | Cause | Fix |
|---|---|---|
| `Chrome not found` | Headless renderer can't locate browser | Install Chrome OR set `CHROME_BIN=/path/to/chrome` env var |
| `Missing required field: TARGET_OTD` | YAML key missing | Add to YAML; re-run |
| PDF blank / missing CSS | Chrome version too old | Upgrade Chrome to >= 90 |
| Garbled CJK glyphs in CN PDF | Font missing | Install Noto Sans CJK or use system font |
| YAML parse error at line N | Quoting issue | Wrap value in double quotes; commas need quoting |

## Use Case

Bring the printed dossier to the test drive. Hand the salesperson page 1
(buyer profile + target) at the start. Show pages 4-5 (cross-bid evidence)
when the dealer counters. Show page 8 (conditions of sale) when negotiating
the final deal sheet. Signals to the dealer:

- You've done your market research
- Your target OTD is anchored to comps, not pulled from thin air
- You will close fast if the terms match (close-timing claim on page 1)
- You will walk if the conditions of sale (CARFAX, PPI) are denied

Per orchestrator Critical Rule #3: never leave the dossier behind. Take it
back to your car. The dealer can photograph but cannot keep the physical
copy.

## Cross-References

- `../orchestrator/scripts/generate_dossier.py` - the renderer
- `../orchestrator/assets/dossier_template.html` - EN template
- `../orchestrator/assets/dossier_template_cn.html` - CN template
- `../orchestrator/assets/dossier_template_es.html` - ES (US) template
- `../orchestrator/assets/dossier_config_template.yaml` - YAML template
  starter (copy and fill)
- `../orchestrator/SKILL.md` Phase 8 - dossier-prep phase in the master flow
- `../orchestrator/SKILL.md` Critical Rule #3 - never leave dossier behind
- `../quote-evidence-collector/SKILL.md` - upstream step that produces the
  `COMP_VEH_N` and `REDDIT_OTD_REPORT_N` raw inputs
- `../otd-calculator/SKILL.md` - upstream step that produces `TARGET_OTD`
  and `WALK_AWAY_CEILING`

## Sample Artifacts (Phase 0 / 5 test run, CT Outback example)

- `<working-dir>/skill-test/p0_p5_execution/sample_dossier.html`
- `<working-dir>/skill-test/p0_p5_execution/sample_dossier.pdf`

These are the reference outputs to diff against when changing templates.

## Output Contract

After every dossier build, return to the operator:

```
Dossier build - <timestamp>
  Vehicle: <year make model trim>
  Config YAML: <path>
  Template: EN / CN
  Required fields supplied: <n>/<n>
  Optional fields supplied: <n>
  Output HTML: <path>
  Output PDF: <path>
  Pages rendered: 8
  Placeholder validation: PASS / FAIL <missing keys>
  Chrome used: <version>
```