---
name: varick-doc-builder
description: This skill should be used when the user asks to format content for the Varick document builder tool, convert a source document (PDF, case study draft, RFI response, proposal) into the builder's marker syntax, prepare a .txt file to paste into the doc builder, or mentions the Varick doc builder, demo.varickagents.com case studies, or document-builder-one.vercel.app.
---

# Varick Document Builder Formatting

The Varick document builder (document-builder-one.vercel.app, or a local copy of its `index.html`) turns a plain-text file written with a small set of markers into a paginated, styled document — case studies, RFI responses, proposals. The deliverable of this skill is a plain `.txt` file using these markers, ready to paste into the builder.

## Check the tool before relying on this reference

The builder gains new block types over time (a `[[roleimpact]]` block was added between sessions previously). Before finalizing a document, especially after time has passed, confirm the marker list below still matches the live tool:

```bash
curl -s https://document-builder-one.vercel.app/ | grep -A2 "k:'"
```

This prints the tool's block library (`LIBRARY = [...]`) with each block's insertion snippet — the source of truth over this document.

## Marker reference

- `# Title` — numbered section heading. The tool auto-numbers every `#` in document order (1, 2, 3…). Never prefix a manual number ("1. Title", "Section A1: Title") — that double-numbers once the tool adds its own. If a heading exists in the source but isn't one of the "real" numbered sections (e.g. a preamble label before Section 1), use `##` instead so it doesn't consume a number slot.
- `## Sub-head` — unnumbered sub-heading; does not affect section numbering.
- `> Quoted line` (optionally followed by `> — Attribution`) — pull quote.
- `| Label | Value` (exactly 2 columns) — a "data band," a plain two-column strip. Usable for a handful of short facts, but prefer `::` definition rows for anything with more than a couple of rows or any long-form text.
- `| Col1 | Col2 | Col3` (3+ columns) — a real table. Tables can split their rows across a page break, repeating the header on the next page — the safe choice for long lists of structured data.
- `@ value | label` — a stat/chart tile. **Hard-caps at 4 tiles per block** — a 5th `@` line in the same run is silently dropped, not overflowed to a new row. For more than 4 facts, split into separate stat blocks (put a blank line or other content between the groups so they parse separately) or use a table/def-list instead. Reserve stat tiles for short, punchy values (a year, a percentage, a dollar figure) — long sentences crammed into a tile render badly.
- `Label :: Value` (one per line) — a definition-list row. Each `::` row becomes its **own independent block**, so the paginator flows and splits them individually across page breaks. This is the safest default for long lists of fields, especially ones with long-form answers.
- `[[roleimpact]]` … `Label :: Value` rows … `[[/roleimpact]]` — a bordered two-column "role impact" table, visually distinct from a plain `::` list. **This entire block is atomic** — the paginator cannot split it across a page break the way it splits a real table. If it doesn't fit in the remaining space on a page, the whole block (plus its trailing heading) gets pushed to a fresh page; if the block itself is taller than a full page, it overflows. Only use `roleimpact` for short lists (roughly 3–6 short rows) — never for long or multi-paragraph answers, or it forces extra page breaks.
- `!! Callout text` — a highlighted note/callout box.
- `---` — a plain divider rule.
- `===` — a manual page break. The tool auto-paginates content as it flows, so don't insert `===` preemptively — only use it when a break is genuinely intentional.
- `+++ Left header | Right header` … left content … `~~~` … right content … `+++` — a two-column comparison ("in scope / out of scope" style).
- `[[timeline W1 W2 …]]` … rows … `[[/timeline]]` — a Gantt-style timeline.
- `[[sign]]` … `~~~` … `[[/sign]]` — signature blocks.

## Process for converting a source document

1. Read the full source (PDF, doc, deployed demo, etc.) before writing anything — don't rely on partial reads or summaries when fidelity matters. For a deployed demo/SPA, static fetching (curl, WebFetch) often only returns an empty shell; if so, render it with a real browser (e.g. drive Chrome via AppleScript and read `document.body.innerText`) rather than guessing at content.
2. Confirm with the requester up front: should the output be condensed (a short, LinkedIn-length version) or a verbatim 1:1 transcription? These produce very different files, and guessing wrong means a full rewrite.
3. If 1:1 is requested, transcribe exact wording. Don't rephrase sentences, don't invent new group headings or section labels that aren't in the source, and don't add emphasis (stat tiles, callouts, bold) to something that's just plain prose in the source — even if it would look cleaner. "Nothing more, nothing less" means the markers are a formatting layer only, not license to restructure or editorialize.
4. Map the source's own structure to the closest-fitting marker, in this priority order: multi-paragraph or many-row content → `::` definition list (safe, splittable); short factual list (≤4 items, short values) → `@` stat block; a genuine multi-column table in the source → `|` table; a short (≤6 row) role/persona-style list → `[[roleimpact]]`.
5. If asked to fix inconsistencies found in the source (numbers that don't add up, an unanswered question left as a placeholder), don't silently correct them — flag them with a `!!` callout right next to the relevant content so the requester can decide.
6. Never manually number section titles — let `#` handle it. Match the source's own section count and order so the auto-numbering lines up with any lettered/numbered scheme the source already uses (e.g. Section A1 → the first `#`, A2 → the second, etc.).
7. Write the result to a plain `.txt` file — no markdown code fences, no commentary embedded in the file — so it can be copied straight into the builder.

## Key gotchas learned the hard way

- The `@` stat block's 4-item cap fails silently — always count `@` lines per block before finalizing.
- `roleimpact` blocks don't paginate internally — a long one will blow out a page or force extra breaks. Prefer `::` lists for anything long; reserve `roleimpact` for genuinely short lists.
- Manually adding "1.", "2.", or "Section A1:" to a `#` heading double-numbers the section once the tool auto-numbers it.
- When told to preserve content 1:1, resist the urge to add structure (sub-headings, stat emphasis) for pagination convenience — ask first if a restructure is acceptable, since it changes what's on the page beyond pure reformatting.

## Example

```
# Results at a Glance

| MEASURE | AFTER | BEFORE
| Month-end close | 7-9 days | 18-22 days
| AP exceptions at close | <50 | 600-800

## What the Team Saw Each Day

[[roleimpact]]
AP Specialist :: A queue of 40+ items requiring judgment each morning dropped to 4.
Director :: A capacity dashboard showed 280 people operating at the output of 520.
CFO :: A real-time close-cycle tracker across all 14 entities.
[[/roleimpact]]

!! Every agent action is logged with full traceability.
```