cap-table
/cap-table
Use for any cap-table number, mechanic, or date before a founder signs, from a single SAFE, note or warrant described in chat or a quick 'is this dilution reasonable?' check to any draft or signed SAFE, note, term sheet, option plan, AoA, Carta XLSX, or spreadsheet. A single question gets a short cited answer in about 2–3 minutes; the full report, about 5–10 minutes, runs only when the founder shares documents or asks for it. Source-cited deterministic math (YC, NVCA, Cooley GO) for SAFE/note conversion, priced-round dilution, anti-dilution, option pools, warrants, MFN chains, dual-class votin
- Author
- lool-ventures ↗
- Repository
- founder-skills ↗
- Licence
- Apache-2.0
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 91
- Scripts
- 67
- HTML comments
- 7
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 67 scripts in this package. Review them before installing, as Claude may execute them.
- SKILL.md zawiera komentarze HTML (7). Nie widać ich w podglądzie Markdown, a model je czyta.
Scripts: scripts/_artifact_io.py, scripts/_artifact_writer.py, scripts/_cap_table_schema_validator.py, scripts/_compose_result.py, scripts/_confidence.py, scripts/_coverage_registry.py, scripts/_ct_gates.py, scripts/_dispatch_json.py
What it does and when to use it
Use for any cap-table number, mechanic, or date before a founder signs, from a single SAFE, note or warrant described in chat or a quick 'is this dilution reasonable?' check to any draft or signed SAFE, note, term sheet, option plan, AoA, Carta XLSX, or spreadsheet. A single question gets a short cited answer in about 2–3 minutes; the full report, about 5–10 minutes, runs only when the founder shares documents or asks for it. Source-cited deterministic math (YC, NVCA, Cooley GO) for SAFE/note conversion, priced-round dilution, anti-dilution, option pools, warrants, MFN chains, dual-class votin
Triggers from the description
Original author description
Use for any cap-table number, mechanic, or date before a founder signs, from a single SAFE, note or warrant described in chat or a quick 'is this dilution reasonable?' check to any draft or signed SAFE, note, term sheet, option plan, AoA, Carta XLSX, or spreadsheet. A single question gets a short cited answer in about 2–3 minutes; the full report, about 5–10 minutes, runs only when the founder shares documents or asks for it. Source-cited deterministic math (YC, NVCA, Cooley GO) for SAFE/note conversion, priced-round dilution, anti-dilution, option pools, warrants, MFN chains, dual-class votin
How it works
- Reliance Boundary (mandatory)
- Skill Execution Model (READ FIRST)
- Input Formats — Four Lanes
- Artifact Pipeline
- Coverage & Disclosure
- Workflow
- Gotchas
- Main-Thread Return
- Feedback
SKILL.md preview
---
name: cap-table
description: "Use for any cap-table number, mechanic, or date before a founder signs, from a single SAFE, note or warrant described in chat or a quick 'is this dilution reasonable?' check to any draft or signed SAFE, note, term sheet, option plan, AoA, Carta XLSX, or spreadsheet. A single question gets a short cited answer in about 2–3 minutes; the full report, about 5–10 minutes, runs only when the founder shares documents or asks for it. Source-cited deterministic math (YC, NVCA, Cooley GO) for SAFE/note conversion, priced-round dilution, anti-dilution, option pools, warrants, MFN chains, dual-class voting, QSBS and Israeli §102 dates, and Israeli ↔ Delaware flips. NOT for waterfall modeling, cumulative dividends, RSUs, 83(b), 409A, SPAC, warrant repricing, or pure term definitions."
when_to_use: >
Cap-table questions carry known miscalculation and reliance traps, so run the
math rather than answer from memory. Do NOT use for a pure definition with
nothing numeric, dated, or eligibility-related at stake ('what is a SAFE?'),
fundraising strategy ('how much should I raise?'), or financial-model review
(use financial-model-review).
user-invocable: true
---
# Cap-Table Skill
Model cap-table mechanics for founders so they understand what their term sheets, SAFEs, and convertible notes actually do to their ownership — before they sign. Produce rule-pack-cited math for SAFE conversion, convertible-note conversion, priced-round dilution, option-pool top-ups, anti-dilution, and Israeli ↔ Delaware flips. Every counsel-review item links back to a primary source (YC SAFE primer, NVCA model docs, Israeli Companies Law / Income Tax Ordinance, etc.). Tone is founder-first: a candid coach who's read the documents you can't be expected to read.
## Reliance Boundary (mandatory)
For any eligibility, qualification, or status determination that turns on tax or legal facts the cap-table data cannot settle — QSBS (IRC §1202), Israeli §102 track / holding period, IIA obligations, or any rule carrying `counsel_review` — state the **cited fact** (the date window, threshold, or clock) and stop there. **Never conclude that the founder does or will qualify** ("yes, you qualify", "you're eligible", "strong eligibility posture"). The date or threshold is a fact you may assert with its citation; the *conclusion* is a counsel determination — present it as such and emit a counsel item. This holds whether the engagement runs the full pipeline, fast-assess, or a one-line directional answer: the boundary is about what you may *conclude*, not how deep the analysis went.
## Skill Execution Model (READ FIRST)
> See `founder-skills/references/skill-execution-model.md` for the full inline-skill execution model (3 dispatch contexts, Mitigation 1+2, producer contract, Cowork quirks, per-symptom triage).
This skill runs **inline in the main thread**, not as a sub-agent — see the reference above ("Why Inline (Not Forked Sub-Agent)") for the rationale. Sub-agents are deliberately shell-free, so orchestration (producer scripts, artifact persistence) stays in the main thread.
**Two dispatch contexts for the sub-agent:**
- **Context A — Per-step analytical dispatch (Mitigation 1):** Used ONLY for document-extraction lanes. Cap-table math is fully deterministic and rule-driven — the reference's Context A section carries this as cap-table's dedicated exception (no analytical/judgment work in the math layer requires a sub-agent) — so Context A is reserved for tasks that genuinely need semantic extraction from natural-language documents:
- `INSTRUMENT_EXTRACTION` — extract terms from a PDF/DOCX SAFE, note, term sheet, or option plan
- `SPREADSHEET_STRUCTURE_DETECTION` — identify which cells encode founders / preferred / options / convertibles in a freeform spreadsheet that doesn't match the Carta schema
The sub-agent returns structured JSON. The main thread pipes the JSON through the validation producer (`extract_instrument.py` / `extract_cap_table.py`), which enforces the anti-hallucination gate. The sub-agent does NOT write artifacts directly.
- **Context B — Post-compose coaching dispatch (POST_COMPOSE_COACHING):** After `compose_report.py` writes `report.md` + `report.json`, the sub-agent Reads the staged `coaching_payload.json` from the hand-off dir (Mitigation 2) — it does NOT read the full `report.md` — composes the coaching commentary, WRITES it to the `OUTPUT_PATH` hand-off file, and returns a small receipt. The main thread gates the file (`check_handoff.py`) and inserts it via the shared `insert_coaching.py` script (idempotency matrix, uuid-marker replacement, run_id-parity verification — all deterministic). See the reference above for the full Context B contract.
**Tolerant JSON extraction protocol (Context A):** After dispatching the sub-agent, capture its final assistant message. The sub-agent should return raw JSON, but may wrap it in ` ```json ... ``` ` fences or add a prose preamble. Extract JSON tolerantly:
1. If the message is wrapped in a ` ```json ... ``` ` (or plain ` ``` ... ``` `) fence, strip the fence first.
2. Try to parse the stripped text directly as JSON.
3. If that fails, walk through the text looking for the first `{` character and try `json.JSONDecoder().raw_decode(text[i:])` — this is brace-aware and handles nested objects correctly (unlike regex, which truncates on the first `}`).
4. If extraction fails entirely, re-prompt the sub-agent with: "Your previous reply could not be parsed as JSON. Return ONLY the JSON object — no markdown fences, no prose preamble."
## Input Formats — Four Lanes
Each lane produces normalized `instruments.json` and/or `cap_state.json` plus an `extraction_audit.json` trail. The main thread picks the lane from the founder's input type. **Founder-facing:** lanes, grids, and structure-detection are internal — to the founder this is just "reading your cap table" (or "reading your spreadsheet"); never announce the lane number, "the grid", "structure detection", or a script/flag as you work through the steps below.
- **Lane 1 — Single instrument (PDF / DOCX).** Typical: 5–15 page SAFE, term sheet, convertible note, option plan, **or Articles of Association**. Main thread reads via the Read tool (native PDF support, up to 20 pages per call; longer docs use `pages` parameter). For SAFEs/notes/term-sheets/option-plans: dispatch Context A `INSTRUMENT_EXTRACTION`; pipe returned JSON through `extract_instrument.py`. For AoAs: dispatch Context A `ARTICLES_OF_ASSOCIATION_EXTRACTION` (see `${CLAUDE_PLUGIN_ROOT}/skills/cap-table/references/lanes/lane-1-pdf-docx.md`, section *Dispatch Context A — ARTICLES_OF_ASSOCIATION_EXTRACTION*); pipe returned JSON through `extract_aoa.py` which validates + merges preferred-series terms into `inputs.json.preferred_series[]`. User confirmation via `AskUserQuestion` before math runs — present the extracted terms in the question body and confirm with the Gate Catalog's *Cap-base confirmation* labels (the same confirm-or-correct pair); never put document values in an option label.
- **Image-only PDF guard (any `.pdf` source).** Before you rely on a cap-table read from a `.pdf` by the Read tool (vision), run `python3 "$SCRIPTS/pdf_probe.py" "<path>"`. Text PDFs (`image_only: false`) read normally. If `image_only: true` (no text layer — dense tables are under-read by vision), prefer OCR over vision:
- **Try OCR first** (the full-parity agent image ships `tesseract` + `pdftoppm`): `python3 "$SCRIPTS/extract_pdf_tables.py" "<path>"` rasterizes + OCRs the pages into a `--mode=grid` payload (same shape Lane 3 consumes). Paste that grid into the Lane-3 `SPREADSHEET_STRUCTURE_DETECTION` dispatch and run `--mode=freeform-emit` (the normal Lane-3 path). Set `metadata.extraction_mode = "ocr_image_pdf"`. **A3:** if the OCR grid shows a printed grand fully-diluted total (a "Total"/"Fully Diluted" row), copy it into `inputs.json` `stated_totals` so `cap_state.py` cross-foots it (`W_FD_RECONCILE_DELTA`). OCR is lossy — confirm the cap base with the founder before math.
- **If OCR is unavailable or fails** (binaries absent / `extract_pdf_tables` errors): fall back to vision — set `metadata.extraction_mode = "vision_image_pdf"` (so `cap_state.py` emits `W_VISION_EXTRACTION_LOW_CONFIDENCE` and the artifacts carry the caveat), tell the founder the cap table is LOW-CONFIDENCE / directional, and PROCEED (degraded-but-honest — never silently present vision numbers as authoritative).
- **RTL / reversed-Hebrew text layer.** `pdf_probe.py` also reports an `rtl` block; when `rtl.rtl_suspect` is true (a Hebrew-locale export — common in this corpus — even one that HAS a text layer), do not transcribe tables from a vision read alone: extract the raw text (pdfplumber), check line direction, and if `rtl.rtl_reversed_likely` reverse each line before reading labels (digits inside an RTL line usually stay LTR — verify against a printed total / `stated_totals` before math). Warning only; lane routing is unchanged.
- **Tracked-changes DOCX guard (any `.docx` source).** Before relying on a `.docx` read, run `python3 "$SCRIPTS/_docx_text.py" "<path>" --detect`. If `has_tracked_changes: true`, the file is a **redline / unsigned draft under negotiation** — the operative terms are ambiguous (struck vs inserted). Do NOT silently extract. Open `ct_docx_tracked_changes` (`python3 "$SHARED_SCRIPTS/record_gate_answer.py" open --run-id "$RUN_ID" --artifacts-root "$ARTIFACTS_ROOT" --gate ct_docx_tracked_changes`) and record the reply; `extract_instrument.py` refuses a tracked-changes `.docx` until it is recorded, and refuses the file on the clean-version answer. Raise an `AskUserQuestion` BEFORE extraction: "This document has tracked changes — it's a redline / unsigned draft, not a final executed version. How should I proceed?" Options: `Upload the clean / final executed version` / `Proceed on the accepted (final-proposed) terms — I understand it's a draft`. **This gate message is the PRIMARY draft caveat** (it reaches the founder even for a standalone instrument that never builds a cap base). On "proceed": get the accepted-view text with `python3 "$SCRIPTS/_docx_text.py" "<path>" --extract` and (a) paste **that** output as the document text in the Context-A `INSTRUMENT_EXTRACTION` dispatch — NOT the raw Read-tool view — so the extractor and `evidence_verifier` read the SAME accepted-revisions view (else a correct inserted-term extraction can't be verified); and (b) set `inputs.metadata.source_markup = "tracked_changes_accepted"` so `cap_state.py` emits `W_REDLINE_DRAFT` and the report persists the caveat. (`_docx_text` reads the accepted view stdlib-only — works in the sandbox, which omits `office_convert`.)
- **Lane 2 — Carta XLSX export.** Typical: multi-sheet XLSX (Securities, Convertibles, Stakeholders). `extract_cap_table.py --mode=carta` reads the sheet-name fingerprint and maps known columns → canonical schema. User confirms ambiguous mappings. See `${CLAUDE_PLUGIN_ROOT}/skills/cap-table/references/carta-pulley-mapping.md` for the column-mapping table. Pulley is not yet supported end-to-end (`--mode=pulley` is a stub that returns a structured blocker pointing to Lane 3 / `--mode=freeform-emit`); restore when a real Pulley XLSX is available to verify against. **Carta exports carry no founder identities or pool structure — Lane 2 writes `instruments.json` + `extraction_audit.json` ONLY; always build `inputs.json` from founder answers (one batched `AskUserQuestion`: founders + share counts, pool authorized/issued/unallocated).** When offering founder candidate options, EXCLUDE obvious investor vehicles — names containing `Ventures`/`Capital`/`Fund` (founders are natural persons or a clearly personal holding entity). A holder also appearing as a SAFE/note investor MAY still be a legit founder co-investor — ASK rather than auto-exclude on that alone. Present an investor vehicle as context labeled "(investor — not a founder)", never as a founder option. (`cap_state.py` emits `W_FOUNDER_LOOKS_LIKE_INVESTOR` as a backstop.) **Reconciliation:** if the carta receipt's `summary.fully_diluted` is present (Carta's printed grand total — independent of the rows you rebuild), copy it into `inputs.json` `stated_totals` `{ "fully_diluted": <n>, "source": "carta_summary" }`. `cap_state.py` cross-foots the rebuilt cap base against it and emits `W_FD_RECONCILE_DELTA` if they diverge > 0.1% — catching a holder/class dropped during the manual rebuild.
- **Lane 3 — Freeform spreadsheet (founder's Excel).** Arbitrary structure — no fixed schema, unlike Lanes 1/2/4.
1. `extract_cap_table.py --mode=auto` confirms the workbook is freeform (prints `detected_format` + sheet names; exits non-zero for freeform by design).
2. `extract_cap_table.py --mode=grid --xlsx "$XLSX_PATH"` dumps all sheets as a cell-value grid (per sheet: dimensions, cell values, merged ranges) to stdout as JSON, compacted under a byte budget so it fits the dispatch control-frame cap (large sheets are trimmed/rounded/row-elided — see `${CLAUDE_PLUGIN_ROOT}/skills/cap-table/references/lanes/lane-3-freeform.md`; a `grid_too_large` blocker means split the workbook per-sheet or fall back to Lane 4).
3. The main thread pastes that JSON into the Context A `SPREADSHEET_STRUCTURE_DETECTION` dispatch prompt to identify cell semantics (block types + column roles from the closed `references/schemas/freeform-role-map.json` vocabulary).
4. Pipe the returned blocks through `extract_cap_table.py --mode=freeform-emit`, which deterministically maps them to schema-valid `inputs.json` (equity, merged into Step 2's file) + `instruments.json` and writes both.
5. Fields the sheet can't supply (e.g. a note's `interest_rate_type`) come back as **blockers** (a human-in-the-loop gate); resolve them with the founder and re-run with `--answer BLOCK.FIELD=VALUE`.
See `${CLAUDE_PLUGIN_ROOT}/skills/cap-table/references/lanes/lane-3-freeform.md` for the full invocation sequence.
**`SPREADSHEET_STRUCTURE_DETECTION` stated-total requirement:** alongside `blocks`, the structure sub-agent must also report a top-level `stated_total` field = the sheet's printed grand fully-diluted total for the current/most-recent snapshot column (the cell the sheet itself labels "Total Fully Diluted", "TFD", or equivalent — pool-inclusive, as-converted basis).
- Report it **only** when such a cell is unambiguously present.
- Omit the field entirely if the sheet's grand total is labeled "Issued"/"Outstanding" (pool-excluded), is as-issued rather than as-converted, or the basis is ambiguous — an issued-only total diverges from the fully-diluted count by the whole unallocated pool, so a wrong-basis stamp would fire a false `W_FD_RECONCILE_DELTA` on a correct sheet.
- Use only a total the sheet itself prints; never report a sum the skill computed (non-circularity).
- **Lane 4 — Structured JSON paste / conversational.** Founder pastes pre-built JSON or describes their cap-table in chat. Direct heredoc into `inputs.json` / `instruments.json`; still flows through `extract_cap_table.py --mode=validate` for schema enforcement.
**Lane 4 has no document to fall back on, so a field the founder did not state must NOT be invented.**
Lanes 1–3 have the absent-field protocol (leave `null`, `confidence.level: "absent"`, an `ambiguities`
entry, `completeness: "partial"`) precisely because a document can be silent on a field. A conversation
can be silent too, and the same rule applies with more force: there is no source to re-read later.
Concretely — a SAFE or note **`issuance_date` the founder never gave**. Do not fill in a plausible date:
it flows into the date-sensitive watchlist and a founder-facing status table, where it is
indistinguishable from one they supplied. Instead **ask** — the date is one `AskUserQuestion` away, shaped
per the Gate Catalog's *Founder-only fact gates* row (a stated-value option plus an explicit defer), and it
changes QSBS, §102 and maturity math — or record it absent per the protocol above and say in the report
that the timing rows are unresolved pending that date. The same holds for any relaxable field:
`purchase_amount` / `principal` / `investor_name` / `maturity_date`.
A fabricated date is worse than a missing one. A missing one stops the founder; a fabricated one gives
them a QSBS clock that is wrong by however far you guessed.
- **Anything not matching a lane above** (e.g. a multi-page PDF export of a pro-forma cap table, a scanned ledger, an unfamiliar tool export). No dedicated lane exists yet — reconstruct via **Lane 4** from the document + founder confirmation: read/transcribe what you can, hand-build `inputs.json` / `instruments.json`, and flow through `--mode=validate`. This is a **sanctioned fallback** (see Coverage & Disclosure), not an improvisation — stamp `metadata.cap_base_provenance = "model_reconstructed"` and apply the cap-base confirmation gate as normal.
## Artifact Pipeline
Every cap-table engagement deposits structured JSON artifacts into a working directory. The final step assembles them into a report and validates consistency. This is not optional.
| Step | Artifact | Producer |
|------|----------|----------|
| 1 | founder context | `founder_context.py` read/init |
| 2 | `inputs.json` | Agent heredoc or `extract_*.py` (Lane 4 / Lanes 1–3) |
| 3 | `instruments.json` | `extract_instrument.py` (Lane 1) or `extract_cap_table.py` (Lane 2/3/4) |
| 4 | `cap_state.json` | `cap_state.py` |
| 5 | `extraction_audit.json` | `extract_*.py` trail |
| 6 | `rule_audit.json` (gating block) | `rule_audit.py --phase=pre_math` |
| 7 | `scenarios.json` | `run_scenario.py` (solver; consumes gating block from Step 6) |
| 8 | `rule_audit.json` (watchlist + counsel items) | `rule_audit.py --phase=post_math` |
| 9 | `counsel_packet.json` + `counsel_packet.md` | `counsel_packet.py` |
| 10 | `comparisons.json` (when ≥2 scenarios) | `compose_report.py` |
| 11 | `report.md` + `report.json` (with `coaching_payload` block) | `compose_report.py --write-md` |
| 12 | `report.html` | `visualize.py` |
| 13 | `sweep.json` (optional — priced rounds only) | `sweep.py` |
| 14 | `explorer.html` | `explore.py` |
| 15 | `## Coaching Commentary` appended to `report.md` | Context B sub-agent (POST_COMPOSE_COACHING) |
**Rules:**
- Deposit each artifact before proceeding to the next step.
- Math producers consume `rule_audit.json.gating[R][I]` for rule-applicability decisions — NOT the rule pack directly. The two-phase split is what makes this work.
- For producer-script artifacts, the agent supplies JSON on stdin where applicable; the script schema-validates against `references/schemas/<artifact>.schema.json`. Never write artifacts directly via `Write` or `Edit` — always pipe through the producer script so `metadata.run_id` is injected and schemas are enforced.
- `compose_report.py` enforces that all required artifacts share the same `run_id` and emits `STALE_ARTIFACT` warnings on mismatch.
Keep the founder informed with brief, plain-language updates at each step. **Narrate the founder-visible OUTCOME, never the internal step.** That is the test to apply, and it catches more than a word list can: the forbidden thing is not a syntax, it is talking about the machinery. Bad — "Gating and piping the extraction through the producer, then staging the coaching hand-off"; good — "I've checked your numbers and I'm writing up what stood out." Bad — "schema-drift warning on `coaching_payload`"; good — nothing, because the founder has no stake in it. **Never name an internal artifact, field, or token** (a payload key, a marker name, an artifact filename, a hand-off dir) even in plain prose with no backticks — a detector keyed on syntax cannot see "gated", "hand-off" or "canonical artifacts", but the founder still reads them and they still mean nothing to them. **The between-step progress lines are the primary leak vector, not the final summary.** They feel internal — you are narrating what you are about to do — but the founder reads every one of them, and this is where the leaks actually appear: *"Now gating the hand-off before piping through the checklist producer"*, *"Gate 1 passes"*, *"Running the final verification gate"*. Rewrite each pipeline transition as the founder-visible outcome: *"Checking your numbers against the 46-point review"*, *"Your inputs look consistent — moving on to unit economics"*, *"Finishing up and putting the report together"*. If a progress line would mean nothing to someone who has never seen this skill's internals, it does not belong in the channel. Also excluded, as before: file/script names, paths, `*.py`, `--flags`, `$vars`, exit codes ("Exit N", "not found"), `W_`/`E_` codes, JSON, and step/route labels ("Lane N", "Context A/B", "Phase N", "structure detection", "the grid", any `ALL_CAPS_TOKEN`). After each major step (extraction, scenarios, counsel), share a one-sentence finding before moving on. **The task tracker is founder-visible too — the same rule governs its labels.** "Gate the inputs review handoff", "Validate inputs.json", "resolve agent namespace paths", "Initialize founder context" are leaks even though each names a real step, and even when the prose around them is clean. Label each task by the founder-visible outcome — "Check your inputs", "Score against the review", "Write up what I found" — never by a file, directory, script, or pipeline stage.
## Coverage & Disclosure
Before running cap-table math in a full-pipeline engagement, determine whether the deal structure falls within the validated engine's coverage. **Never substitute mental arithmetic for a covered script path** — the fixed-point solver enforces rule-pack gotchas that hand-rolled estimates miss silently.
### Detect coverage after instruments are committed
After `instruments.json` and `cap_state.json` are written (Steps 3–4), run:
```bash
python3 "$SCRIPTS/detect_structure.py" \
--inputs "$REVIEW_DIR/inputs.json" \
--instruments "$REVIEW_DIR/instruments.json" \
--run-id "$RUN_ID" \
-o "$REVIEW_DIR/coverage_result.json" --pretty
```
The script emits:
- `required_primitives` — mechanics the deal requires
- `covered` (bool) — whether the deterministic pipeline covers all required primitives
- `uncovered_parts` — any primitives the pipeline cannot handle
- `route.scenario_requests` — a ready-to-run scenario list (populated only when `covered: true`)
### If `covered: true` — use the deterministic pipeline
Populate `scenario_requests.json` from `route.scenario_requests` (the detection output) instead of authoring it by hand. **The route gives you the scenario SHAPE, not a runnable request** — ids, types, chaining order, and whatever parameters are derivable from the artifacts. It CANNOT supply terms that live with the founder rather than in `inputs.json`/`instruments.json`: a `priced_round` comes back needing `pre_money` and `new_money`, a `flip` needing the IIA / §102 answers (each request names its own gaps in `parameters_required`). Fill those in from the founder's stated deal at Step 5 — see the confirm/extend instruction there — and never run a request with them missing: `run_scenario.py` returns a `E_MISSING_PARAMETER` blocker rather than a result. This is about ROUND TERMS only; the hand-rolled-math ban below is unaffected and still absolute. Proceed to Step 4.5 and Step 5 as normal. **Never hand-roll or mentally estimate a covered deal** — not as a sanity check, not as a directional figure alongside the solver result. The solver is the authoritative source; any hand-rolled estimate will diverge from the fixed-point result.
For covered deals, `compose_report.py` writes `coverage_disclosure.json` (with `covered: true`, `computation_method: deterministic_pipeline`) and any reconciliation banner automatically — no agent action required.
### If `covered: false` — hand-roll with mandatory disclosure
When `uncovered_parts` is non-empty, the deal combines primitives the engine does not fully handle. You may produce numbers manually, but:
1. **Build manually from rule-pack formulas** — cite each `rule_id` explicitly so the math is traceable.
2. **Write `coverage_disclosure.json` through `write_coverage_disclosure.py`** — stage the JSON in `$STAGING_DIR` (the `/tmp` scratch dir from Step 0), then:
```bash
cat "$STAGING_DIR/disclosure.json" | python3 "$SCRIPTS/write_coverage_disclosure.py" \
-o "$REVIEW_DIR/coverage_disclosure.json" --run-id "$RUN_ID" --pretty
```
**`uncovered_parts` is an array of STRINGS, not the raw detection objects.** The detection
output gives you `{"combination": [...], "reason": "..."}` entries; flatten each to
`"<a> + <b>: <reason>"` as shown. The schema is closed and the producer rejects a list of
objects (`uncovered_parts[0]: expected type string, got dict`).
**Do NOT heredoc it straight into `$REVIEW_DIR`.** The disclosure form is CLOSED: the producer rejects an unknown key, because the failure it exists to catch is a hand-authored *richer* schema than the template, not a missing field. If it rejects, the pipe fails and `$REVIEW_DIR` is untouched — fix the staged JSON. The payload:
```json
{
"schema_version": "v0.1-coverage-disclosure",
"covered": false,
"computation_method": "manual_outside_pipeline",
"required_primitives": ["<from detection output>"],
"uncovered_parts": ["note_conversion + acquisition_consideration: declared incompatible"],
"counsel_review": true
}
```
3. **Prepend the provisional banner** to the report:
`> ⚠️ **Computed outside the validated cap-table engine.** This deal combines primitives the deterministic pipeline does not fully cover; figures are provisional — confirm with counsel.`
4. **Emit a counsel item** for every uncovered primitive, regardless of confidence in the manual calculation.
Never present hand-rolled figures without the banner and the `coverage_disclosure.json` artifact.
**Input-format fallback (document matched no lane).** The `covered:` axis above is about MATH primitives. Input FORMAT is a separate axis: when the document is genuinely readable but matches none of the four lanes and you hand-rebuild the cap base from it, that is a sanctioned fallback, not an improvisation — set `metadata.cap_base_provenance = "model_reconstructed"` (fires `W_CAP_BASE_RECONSTRUCTED`), apply the cap-base confirmation gate as normal, and note the unmatched source format in the report's methodology line. Math coverage stays whatever `detect_structure.py` reports; there is no `coverage_disclosure.json` schema change for the input-format axis.
**Scripts that require `cap_state.json`.** `rule_audit.py --phase=pre_math`, `run_scenario.py`, and `compose_report.py` all require `cap_state.json` and are unusable when no cap state can be produced (e.g. the no-cap-base fork above, or a hand-roll before cap state exists). To cite a rule-pack constant for a hand-rolled figure without running the pipeline, use `verify_one.py --rule-lookup <rule_id>` against `cap-table-rules.json`.
### Acquisition inputs (`inputs.acquisition`) — counsel-reviewable
When the deal includes a negotiated-% share acquisition concurrent with or immediately prior to a priced round, populate `inputs.acquisition` in `inputs.json`:
```json
"acquisition": {
"acquired_entity": "Target Co",
"consideration_pct": 0.05,
"consideration_form": "shares",
"acquisition_timing": "concurrent_with_round"
}
```
`acquisition_timing` enum:
- `concurrent_with_round` — consideration shares are excluded from the YC SAFE Company Capitalization denominator; they dilute the SAFE via post-close fully-diluted only.
- `pre_round_closed` — acquisition stock is outstanding immediately prior; included in Company Capitalization (protects the SAFE from consideration dilution).
All three acquisition rules (`acquisition.consideration_shares`, `acquisition.pool_consideration_basis`, `acquisition.timing`) carry `counsel_review: true` — the consideration formula, pool-denominator treatment, and timing classification each require counsel confirmation before the founder relies on the computed figures. `detect_structure.py` automatically detects the acquisition block and includes `acquisition_consideration` and `priced_round` in `required_primitives`.
### Priced-round scenario parameters — counsel-reviewable
Two parameters on a `priced_round` scenario require counsel confirmation before applying:
- **`pre_money_basis`** — whether converting SAFE shares count toward the pre-money denominator. Enum: `includes_safe_conversion` (default) | `excludes_safe_conversion`. A negotiated term; do not silently apply the default and present it as the only valid convention.
- **`pool_consideration_basis`** — when a concurrent acquisition is present, whether consideration shares count toward the post-money pool-sizing denominator. Enum: `include` (default) | `exclude`. Negotiable per Cooley pricing conventions (`acquisition.pool_consideration_basis` rule).
When neither the term sheet nor the AoA settles these questions, batch them into the founder confirm gate and emit a counsel item for each.
## Workflow
### Step 0: Path Setup
**EVERY BASH CALL IS A FRESH SHELL — no variable set here survives into the next block.** This is the single most likely place a run silently drifts, because `$SCRIPTS`, `$REVIEW_DIR`, `$RUN_ID` and `$HANDOFF_DIR` do not error when they are unset: they expand to the empty string, so a path quietly becomes `/inputs.json` and a `--run-id` quietly becomes blank (which then fails compose's run_id-parity check, several steps and one sub-agent dispatch later, far from the cause). Two lines below already say this individually for `ARTIFACTS_ROOT` and `HANDOFF_AGENT`; it is true of all of them.
**So: read the printed values out of Step 0's output and paste them as literals into every later block that uses them.** Do not carry a variable forward and assume it survived. `$PLUGIN_ROOT` — and everything derived from it (`$SCRIPTS`, `$SHARED_SCRIPTS`) — is resolved via `select_plugin_root.py` exactly ONCE, below: re-running that self-heal search in a later block can land on a DIFFERENT candidate mount than Step 0 picked when more than one is present (see why in the block's comments), so paste the printed `PLUGIN_ROOT` literal rather than re-deriving it. `$ARTIFACTS_ROOT` stays fine to recompute from a pasted `$SHARED_SCRIPTS` literal — once the plugin root is fixed it is a deterministic filesystem lookup with no state. `$RUN_ID` is the `run_id` the run's record prints below, and must stay constant for the whole engagement (compose enforces parity): paste that literal, and never start the record again in a later block. Every producer refuses an empty `--run-id` (`RUN_ID_REQUIRED`); after a context reset, re-read this skill from its base directory and take the id from the run status. What is NOT fine, either way, is referencing `$REVIEW_DIR` in Step 6 because Step 0 set it.
Optional, best-effort, and via the **Read tool** (not a shell command): before the block below, Read `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` and note its `version` field as `EXPECT_VERSION`. Passing it to `select_plugin_root.py` below lets an exact version match win over an arbitrary first hit. If the Read fails, skip it and omit `--expect-version` — selection is still deterministic without it. Skip it if that path still begins with `$`.
Run the block below with `${CLAUDE_PLUGIN_ROOT}` exactly as it appears.
```bash
IFS= read -r TEXT_ROOT_RAW <<'EOF'
${CLAUDE_PLUGIN_ROOT}
EOF
SCRIPTS="${CLAUDE_PLUGIN_ROOT}/skills/cap-table/scripts"
case "$TEXT_ROOT_RAW" in *'$'*|'') SCRIPTS="" ;; esac # text arrived unfilled: ignore any exported value
if [ ! -d "$SCRIPTS" ]; then
# In Cowork, CLAUDE_PLUGIN_ROOT substitutes to a host-side path absent inside
# the session VM — self-heal by collecting EVERY candidate mount (a session can
# have more than one at once: a stale host-side cache, a test marketplace, even
# a symlink into a different session's tree) and handing them to
# select_plugin_root.py, which picks ONE deterministically and names the
# rejects — never trust `find`'s arbitrary first hit, which can silently mix
# scripts across plugin versions mid-pipeline.
ours() { python3 -c 'import json, sys
for c in sys.stdin.read().splitlines():
try: n = json.load(open(c.rsplit("/skills/", 1)[0] + "/.claude-plugin/plugin.json"))["name"]
except Exception: n = "founder-skills"
if n == "founder-skills": print(c)'; }
CANDIDATES="$(find /sessions -type d -path '*/skills/cap-table/scripts' 2>/dev/null | ours)"
[ -n "$CANDIDATES" ] || CANDIDATES="$(find /root/.claude/plugins -type d -path '*/skills/cap-table/scripts' 2>/dev/null | ours)"
[ -n "$CANDIDATES" ] || CANDIDATES="$(find / -type d -path '*/skills/cap-table/scripts' 2>/dev/null | ours)"
PROVISIONAL_ROOT="$(printf '%s\n' "$CANDIDATES" | head -1)"
PROVISIONAL_ROOT="${PROVISIONAL_ROOT%/skills/*}"
# Bootstrap order: $SHARED_SCRIPTS isn't known until a root is chosen, so use the
# provisional root's OWN copy of the selector; an older plugin copy without one
# falls back to the provisional root unchanged.
SELECTOR="$PROVISIONAL_ROOT/scripts/select_plugin_root.py"
if [ -f "$SELECTOR" ]; then
if [ -n "$EXPECT_VERSION" ]; then
PLUGIN_ROOT="$(printf '%s\n' "$CANDIDATES" | python3 "$SELECTOR" --expect-version "$EXPECT_VERSION")"
else
PLUGIN_ROOT="$(printf '%s\n' "$CANDIDATES" | python3 "$SELECTOR")"
fi
else
PLUGIN_ROOT="$PROVISIONAL_ROOT"
fi
SCRIPTS="$PLUGIN_ROOT/skills/cap-table/scripts"
fi
PLUGIN_ROOT="${SCRIPTS%/skills/*}"
echo "PLUGIN_ROOT=$PLUGIN_ROOT" # resolved ONCE, here — paste this literal into every later block; never re-run this resolution. PLUGIN_ROOT is the shell's path: never Read from it or put it in a sub-agent prompt. Exception: a READ_ROOT= printed below goes in Reads and prompts.
SHARED_SCRIPTS="$PLUGIN_ROOT/scripts"
# PREFLIGHT: the run STOPS if this prints (the skill was served without its plugin). Test for
# check_handoff.py, never a /mnt/skills path: a working first-message session shows that path too.
[ -f "$SHARED_SCRIPTS/check_handoff.py" ] || echo "UNSUPPORTED_ENVIRONMENT: the plugin's shared scripts are not reachable from here"
[ -f "$SHARED_SCRIPTS/check_handoff.py" ] && case "$TEXT_ROOT_RAW" in
*'$'*|'') echo "PATH_STATE=literal"; echo "READ_ROOT=$PLUGIN_ROOT" ;;
/sessions/*) echo "PATH_STATE=local" ;;
*) if [ -d "$TEXT_ROOT_RAW" ]; then echo "PATH_STATE=substituted"; else echo "PATH_STATE=local"; fi ;;
esac
# Resolve the canonical artifacts root via a SCRIPT, not inline bash. An inline path computation is
# guidance the agent paraphrases — it lands outputs/ in one run and outputs/artifacts/ in another,
# desyncing cross-skill find_artifact.py and breaking path-based checks. The script computes the root
# deterministically (under the promoted outputs/ dir in Cowork, ./artifacts in the CLI) and creates it.
python3 "$SHARED_SCRIPTS/resolve_artifacts_root.py" # prints ARTIFACTS_ROOT — use the printed path verbatim as ARTIFACTS_ROOT in every later block (a captured var dies in the next fresh shell)
```
**If the preflight line printed `UNSUPPORTED_ENVIRONMENT`, stop here.** This environment serves the
skill without the rest of its plugin: the shared scripts are missing and sub-agents cannot be
dispatched, so the gates, the hand-off checks and the independent review steps below cannot run.
Tell the founder, in one sentence, that this skill needs Claude Cowork or Claude Code and that you
have not run it — then stop. Do not improvise the missing steps: an analysis that grades itself and
reviews itself reads exactly like one that was checked, which is the failure this stop exists to
prevent.
**Then start the run's record, once**, copying every `FS_HOST_` line of the request between the markers byte for byte; never reformat or wrap a line. `RUN_ID` is the `run_id` it prints. Any non-zero exit here or from `bind` below: say in one sentence that the review could not start, and stop. Exit 12 from any script: ask nothing; say what the run is waiting for, and stop.
```bash
python3 "<printed PLUGIN_ROOT>/scripts/run_status.py" start --skill cap-table --artifacts-root "<printed ARTIFACTS_ROOT>" <<'FS_HOST_EOF'
<each FS_HOST_ line of the request>
FS_HOST_EOF
```
If the request carries no `FS_HOST_` lines, leave the heredoc body empty.
**A resume** (`resume: 1`) continues at the question `waiting_on` names: Steps 0 and 1 run again, then ask that question from its `needs_input`, record the reply and re-run the step that stopped. Never redo an extraction or re-ask a question already recorded.
Plugin folder for Reads and prompts (as loaded): `${CLAUDE_PLUGIN_ROOT}` — this skill's references are in `${CLAUDE_PLUGIN_ROOT}/skills/cap-table/references/`. If Step 0 printed `READ_ROOT=`, use that value instead.
**Plugin paths.** If Step 0 printed `READ_ROOT=`, this skill's text arrived without its plugin folder filled in. Use that value in place of `${CLAUDE_PLUGIN_ROOT}` in every Read and sub-agent prompt, including where a later step says to leave that path literal. If it did not print `READ_ROOT=`, use the paths as shown. The folder comes from Step 0's filesystem search, not from a skill file or the "Base directory" line, which can name a folder that does not exist. These are setup details: updates to the founder are about their company, not file locations, printed paths or plugin versions.
**Outputs mount is append-only.** Everything under the promoted outputs mount (`.../mnt/outputs/`, not just `$REVIEW_DIR`) is write-allowed; by this skill's rule, not a platform limit, nothing there is deleted, since a removed file may be one the founder or a later step still needs: never `rm`, move away, or empty anything under it — **including files you created yourself**. Never create ad-hoc scratch anywhere under the outputs mount (no `_src/` copies, no run-state note files); scratch belongs in `$STAGING_DIR` (a `/tmp` dir, defined below). Do not "clean up" the outputs folder before delivering — extra working files there are expected and harmless. The uploaded document is already readable in place from the uploads mount; never copy it under outputs to make it readable.
After Step 1 (when the company slug is known), derive `REVIEW_DIR`. **Four modes** — pick exactly one:
- **Full pipeline** (default — when the founder shared a document, asked for the full review, counsel packet, or interactive explorer, OR when there's no existing full review for this slug): `REVIEW_DIR="$ARTIFACTS_ROOT/cap-table-$SLUG"`.
- **Fast-assess mode** (Phase O — short directional answer to a conversational question, no document attached, no explicit "full review" request): `REVIEW_DIR="$ARTIFACTS_ROOT/cap-table-$SLUG-fastassess"`. Run `quick_assess.py` (Step 5-fast) instead of Steps 2–11. Usually about 2–3 minutes.
- **Rule-lookup mode** (a bare eligibility/date question — QSBS, Israeli §102, IIA — with **no instruments to model and no document**): answer straight from the rule pack — no `REVIEW_DIR`, no pipeline. Run `verify_one.py --rule-lookup <rule_id>` (Step 5-lookup) and present its cited constant + the reliance boundary (state the date/threshold; never conclude eligibility — emit a counsel item). If it returns `lookup_status: "escalate"` (the rule carries no stored constant — e.g. the §102 capital-gains clock, which runs from a plan/trustee-specific date the pack does not hold), ask the founder for the specific fact it names (e.g. the trustee-deposit date) and treat as a counsel determination — never state a default like `grant_date`.
- **Concise mode** (a single quick **math** question that `quick_assess` can't shape and that isn't a pure eligibility lookup — a fully-diluted warrant count, an as-converted snapshot, a standalone anti-dilution adjustment, one note/SAFE outside a priced round): run the deterministic math, then render a short cited answer with `concise_report.py` (Step 5-concise) — **skip** `visualize`, `explore`, `counsel_packet`, the full `compose_report`, and the Context-B coaching sub-agent. The numbers are identical to the full pipeline's (it reads the same `run_scenario` output); only the production weight is dropped. Offer the full review as a follow-up. `REVIEW_DIR="$ARTIFACTS_ROOT/cap-table-$SLUG-concise"`.
**Slug discipline:** Use the slug returned by `founder_context.py` VERBATIM in directory names — never invent ad-hoc suffixes (e.g. appending `-seed`, `-round`, or any other qualifier). Downstream `find_artifact.py` lookups resolve by that slug; a mismatched directory is invisible to the cross-skill layer.
```bash
# Choose ONE based on the routing decision above. These are the ONLY permitted
# values — the slug-discipline rule above forbids inventing any other suffix, so
# every mode that needs a REVIEW_DIR must appear here or it cannot be built.
REVIEW_DIR="${REVIEW_DIR:-$ARTIFACTS_ROOT/cap-table-$SLUG}" # full pipeline
# REVIEW_DIR="${REVIEW_DIR:-$ARTIFACTS_ROOT/cap-table-$SLUG-fastassess}" # fast-assess
# REVIEW_DIR="${REVIEW_DIR:-$ARTIFACTS_ROOT/cap-table-$SLUG-concise}" # concise
# Rule-lookup mode has NO REVIEW_DIR and writes no artifact — skip this block entirely.
RUN_ID="<the run_id start printed>"
mkdir -p "$REVIEW_DIR" && python3 "$SHARED_SCRIPTS/run_status.py" bind --run-id "$RUN_ID" \
--artifacts-root "$ARTIFACTS_ROOT" --run-dir "$REVIEW_DIR" --slug "$SLUG" || exit 1
# Context A hand-off dir — PER RUN: sub-agents WRITE their raw extraction JSON here (the audit
# trail — raw sub-agent output as returned, before validator gating). Permanent by rule
# (nothing under outputs/ is ever deleted, by this skill's rule); nothing in it is ever a canonical artifact.
# The $RUN_ID segment is load-bearing: it prevents a stale prior-run file from silently passing
# the hand-off gate when a dispatch fails to write.
HANDOFF_DIR="$REVIEW_DIR/handoff/$RUN_ID"
mkdir -p "$HANDOFF_DIR"
# FILE-TOOL PATHS (Cowork only; skip when ARTIFACTS_ROOT does not start with /sessions/). File tools
# refuse a RELATIVE path and cannot open /sessions/... paths. FIRST, with the Write tool, write
# "<HOST_OUTPUTS>/artifacts/.host-outputs-probe" containing exactly <HOST_OUTPUTS>: the file-tool path
# your context maps to /sessions/<id>/mnt/outputs/ (the "Paths in bash differ from what file tools
# see" list; no such list -> that /sessions/.../mnt/outputs path itself). Then prove it (quoted; it may
# contain spaces). Exit 0 = proven. 2/4/5 -> fix per its JSON, retry once, then STOP:
python3 "$SHARED_SCRIPTS/resolve_artifacts_root.py" --set-host-outputs-dir "<HOST_OUTPUTS>"
# Sub-agents address the SAME dir by a different path (the absolute file-tool path
# proven above). Resolve the FULL agent-namespace path via the script — never hand-splice the
# printed root with a literal skill-name/slug/run-id string yourself (that string-splicing is
# exactly the non-determinism the resolver script exists to remove):
python3 "$SHARED_SCRIPTS/resolve_artifacts_root.py" --handoff-dir-agent \
--dir-name "cap-table-$SLUG" --run-id "$RUN_ID" # prints HANDOFF_AGENT verbatim
HANDOFF_AGENT="<printed value>" # use verbatim in OUTPUT_PATH lines
# Ad-hoc scratch (NOT sub-agent hand-off) lives OUTSIDE the promoted outputs/ tree, in a temp dir
# that is safe to both create and clean up.
# Scratch output (a redirect or a temp file) goes in $STAGING_DIR, never a fixed /tmp/<name>: /tmp is shared across sessions.
STAGING_DIR="$(mktemp -d "${TMPDIR:-/tmp}/cap-table-${SLUG}.staging.XXXXXX")"
```
**Context A hand-off protocol (file transport + gate).** Every Context A dispatch is a
`Task(subagent_type="founder-skills:cap-table", …)` call — the `subagent_type` is **REQUIRED** on the
original AND on every corrective dispatch below; omitting it silently downgrades to the wildcard,
shell-capable `general-purpose` agent (a containment defect). Every Context A dispatch prompt carries an
`OUTPUT_PATH:` line built from `$HANDOFF_AGENT` (the lane references show the exact `Task(...)`
templates). The sub-agent WRITES its extraction JSON to that path with its Write tool and returns only a
small receipt: `{"status": "complete", "output_path": "<echo of OUTPUT_PATH>"}`. The payload leaves the
model exactly once (into the Write call) — never re-type sub-agent JSON into a heredoc.
**`$HANDOFF_AGENT` and `$HANDOFF_DIR` name the SAME directory by two different paths — they are not
interchangeable.** `$HANDOFF_DIR` is the absolute VM path your shell uses (`python3`,
`check_handoff.py`, producer pipes). `$HANDOFF_AGENT` is the absolute file-tool path of the same
directory (proven at Step 0), and it is the ONLY one that goes in a dispatch prompt. Putting
`$HANDOFF_DIR` in an `OUTPUT_PATH` line hands the sub-agent an absolute `/sessions/...` path the
host-loop gate denies; putting `$HANDOFF_AGENT` in a shell command resolves it against the wrong cwd.
Rule of thumb: **agent namespace in prompts, shell namespace in bash.**
**The receipt is the ONE exemption from the never-re-type rule.** "Never re-type" governs the
*payload* — the extraction JSON, the coaching commentary, anything the founder's numbers pass
through. The receipt is a two-field acknowledgement the sub-agent returns in its final message, and
reading `output_path` out of it to pass to `check_handoff.py --agent-path` is expected, not a
violation. If it were forbidden, the hand-off could not be gated at all.
**Path idiom for dispatch prompts (host-loop path gate):** `OUTPUT_PATH` and any under-outputs artifact
READ path a sub-agent is given are **absolute file-tool paths**, never relative ones (a relative
file-tool path is refused) —
built from the `resolve_artifacts_root.py --agent` namespace (`$HANDOFF_AGENT`, or the equivalent
agent-namespace path for any other under-outputs artifact a dispatch prompt reads). Never hand a
sub-agent an absolute `/sessions/...` path for a file-tool Read/Write — the host-loop path gate denies
it (steering shell work to the `bash` tool instead). Bundled `references/*.md` are the one exception:
pass them as the literal `${CLAUDE_PLUGIN_ROOT}/skills/cap-table/references/...` token (it is
pre-resolved to a host-readable path), never the shell's path to the plugin folder.
After EVERY Context A dispatch, gate before piping (`<step>` = the dispatch's file stem):
```bash
printf '%s' '<agent final message verbatim>' | \
python3 "$SHARED_SCRIPTS/check_handoff.py" "$HANDOFF_DIR/<step>_output.json" \
--agent-path "$HANDOFF_AGENT/<step>_output.json" --receipt-json -
```
<!-- skill-quality-ci: bash-after-subagent-ok -->
Branch on the exit code (complete state machine — do not improvise). *Every corrective **redo-dispatch**
/ **repair-dispatch** below is a full `Task(subagent_type="founder-skills:cap-table", …)` — a "fresh
Task, same prompt" must carry the `subagent_type`; dropping it on a retry is the same containment defect
as omitting it originally:*
- **Exit 0** → pipe the file through the validator (`cat "$HANDOFF_DIR/<step>_output.json" | python3 "$SCRIPTS/<validator>.py" ...`).
- **Exit 3** (missing/empty file — receipt may be fabricated) → **redo-dispatch**: fresh Task, same prompt plus one line: "your receipt claimed a file at `<path>` but none exists; use Write to create exactly that path."
- **Exit 4** (file exists, invalid JSON) → **repair-dispatch**: fresh Task: "Read `<OUTPUT_PATH>`; it fails JSON parsing with `<verbatim detail>`; fix and rewrite it; return the receipt."
- **Exit 5** (receipt echoes a different path) → **repair-dispatch** with the exact expected OUTPUT_PATH.
- **Exit 6** (receipt unparseable / no `output_path` key) → **redo-dispatch** with "return ONLY the receipt JSON — no fences, no prose."
- **Validator schema rejection** (the pipe fails next) → **repair-dispatch** with the validator's stderr verbatim. (Evidence-verifier rejections keep their OWN lane-specific protocol — `retry_hint` re-dispatch — which is a content correction, not a transport correction, and does not consume the transport retry budget.)
- **Exit 8** (`path_namespace_mismatch`) → the sub-agent **complied**; the agent-namespace prefix was wrong. Its relative `OUTPUT_PATH` resolved against the outputs mount instead of the session root, so the file landed at the doubled path reported in `found_at`. Only a RELATIVE agent path can do this, so the Step 0 proof did not run: run it. Do NOT treat this as a fabricated receipt (that is exit 3), and do NOT read the hand-off from `found_at` — it is diagnostic only. Re-run `resolve_artifacts_root.py --agent`, rebuild the agent-namespace prefix from the printed value, and re-dispatch. Counts against the same 2-dispatch retry budget.
- **Blocked `write_refused`** (the sub-agent's Write was refused — its path was relative or a `/sessions/...` path) → run the Step 0 proof if it did not run, rebuild the agent-namespace paths from the resolver, re-dispatch ONCE. A second `write_refused` STOPs with both details quoted.
- **Any other exit** (script crash etc.) → STOP with the stderr.
- **After ANY corrective dispatch, resume from `check_handoff.py`** — never pipe unchecked.
**Retry budget:** max **2 corrective transport dispatches per step, of any kind** (max 3 total).
After the second corrective dispatch fails any gate: STOP and report the exact diagnostic. The main
thread MUST NOT author or patch extraction content itself — that is the fabrication failure mode
this architecture exists to prevent. A `status: "blocked"` return is bounded separately: at most
ONE input-fix re-dispatch per step; a second blocked return STOPs with both reasons quoted.
**Graceful degrade (fleet heterogeneity):** if the FIRST corrective dispatch also exits 3 while the
agent's receipt claims `complete` with the correctly echoed path, treat the host's filesystem
topology as hand-off-incompatible: fall back to message-channel transport for the REST of this run
(sub-agent returns full JSON in its final message; apply the tolerant JSON extraction protocol;
stage to `$STAGING_DIR/<step>_input.json`; same validator pipe), and tell the founder in one plain sentence that this run's working files were passed
directly instead of through `outputs/`, so its audit trail is incomplete (the results are unaffected).
A refused write is NOT this case: it returns `write_refused` (above).
Retries overwrite the same OUTPUT_PATH (nothing under the outputs mount is deleted, by this skill's rule — never `rm`
under `$REVIEW_DIR`). Hand-off files are not canonical artifacts: validators consume them only via
the explicit pipe, and `compose_report.py` never reads `handoff/`.
**Routing heuristics.** In order: (1) a **bare eligibility/date question** (QSBS, §102, IIA) with no instruments and no document → **rule-lookup** (Step 5-lookup) — a cited fact, not a pipeline run. (2) A **single quick math question** that `quick_assess` can't shape (warrant fully-diluted count, as-converted snapshot, standalone anti-dilution, a lone note/SAFE outside a priced round) → **concise mode** (Step 5-concise) — the real math, short answer, no heavy tail. (3) A **priced-round gut-check** / first-touch conversational answer (no document, no "full review"/"counsel packet"/"report"/"explorer"/"deep dive") → **fast-assess**. (4) Otherwise → **full pipeline**. If an existing `cap-table-$SLUG/report.json` is present, ask via `AskUserQuestion` whether to use it or start fresh. **Extraction-only is NOT a route you select here.** A single uploaded instrument still routes to (4) full pipeline; the extraction-only path is entered ONLY via the Step-2 no-cap-base fork, after extraction has confirmed there is genuinely no equity base. Never choose extraction-only at Step 0 — nothing has been extracted yet, so "no base" cannot be known, and routing to it here would skip the fork that lets the founder supply a base they do have.
**Existing review.** On the full route, the question above is a recorded gate: after `bind`, open `ct_existing_review` (`python3 "$SHARED_SCRIPTS/record_gate_answer.py" open --run-id "$RUN_ID" --artifacts-root "$ARTIFACTS_ROOT" --gate ct_existing_review`; `not_owed`: no earlier review) and ask it from its `needs_input`; record the reply with the `answer_command` it printed (none: `default --reason start_fresh_by_default`). `Start fresh`: write this run's own `inputs.json` (Step 2) and an empty `instruments.json` with this run's id before Step 3 — the extraction refuses to append to an earlier run's. `Use existing review`: send the earlier review's files as they are; nothing is recomputed, and this run stops there.
**Artifact-worthy boundary (write the sentinel).** If your answer presents a founder-facing ownership/dilution **table** or a **post-financing ownership %**, you MUST run a script-backed path — `quick_assess` (fast-assess; writes the `fast_assess_only.json` sentinel + `report_fast_assess.md`), `concise_report` (concise mode; writes the real `cap_state.json` + `scenarios.json` + `report_concise.md`), or the full pipeline — do NOT hand-build such an answer in chat. A one-line directional aside while gathering inputs (e.g. "≈20% to new investors") is fine in chat and writes no artifact. This keeps any quantitative ownership answer backed by the script + sentinel, so downstream consumers can detect that cap-table ran.
### Step 1: Read or Create Founder Context
If the founder's message or the attached materials name the company, add `--expect-company "<that name>"` to this read (never a file name); a context stored for another company then asks which (Exit 10).
```bash
python3 "$SHARED_SCRIPTS/founder_context.py" read --artifacts-root "$ARTIFACTS_ROOT" --run-id "$RUN_ID" \
--skill cap-table --pretty
```
**Exit 0 (found):** Use the company slug and pre-filled fields. Proceed to Step 2.
**`W_SECTOR_TYPE_UNKNOWN` is benign for cap-table engagements.** If `founder_context.py` emits a `W_SECTOR_TYPE_UNKNOWN` warning (triggered by free-text sectors such as "technology"), proceed — `sector_type` is not read by any cap-table rule or script, so this warning has no effect on cap-table math or counsel-review gating. Do not re-prompt the founder just to resolve it.
**Exit 1 (not found: no `code`, or `CONTEXT_NOT_FOUND`):** Open the questions (the block below) first. Do NOT mention this check or its exit status to the founder; if you narrate anything first, say only "Let me grab a few basics about the company." Use `AskUserQuestion` (NOT plain chat) to ask for company name, stage, sector, and geography — the Gate Catalog rows *Company name*, *Company stage*, *Sector*, *Geography* below give the phrasing and option shape for each (stage is a fixed 4-label set; name/sector/geography are runtime-labelled — an affirmative option carrying whatever was derived from the conversation or materials, a stated-value fallback, and an explicit defer so the question still renders at 2 options when nothing was derived). **Carry the stage into `inputs.metadata.stage`** — stage-scoped benchmarks read it there, and withhold rather than guess when it is absent.
**Each question is a recorded gate: open, ask, answer.** Ask from the printed `needs_input`, then record each reply with its `answer_command`. A value the request or the materials give is recorded unasked: `python3 "$SHARED_SCRIPTS/record_gate_answer.py" default --run-id "$RUN_ID" --artifacts-root "$ARTIFACTS_ROOT" --gate <gate> --reason stated_in_request --answer-id <option>` (or `derived_from_materials` / `inferred` with `--answer-id use_derived --value "<value>"`; a stage: its id, no `--value`). A `Series B+` reply opens `ctx_stage_detail`, recorded the same way. <!-- gate: ctx_stage_detail -->
```bash
python3 "$SHARED_SCRIPTS/record_gate_answer.py" open --run-id "$RUN_ID" --artifacts-root "$ARTIFACTS_ROOT" \
--gate ctx_basics.company_name --gate ctx_basics.stage --gate ctx_basics.sector --gate ctx_basics.geography
```
Then create (exit 10 names a question not yet recorded: ask it, record it, run `init` again):
```bash
python3 "$SHARED_SCRIPTS/founder_context.py" init \
--company-name "Acme Corp" \
--stage <pre-seed | seed | series-a | series-b | series-c | series-d | later> \
--sector "B2B SaaS" \
--geography "US" --artifacts-root "$ARTIFACTS_ROOT" \
--run-id "$RUN_ID" --skill cap-table
```
**Exit 10 (which company):** ask which from the printed `needs_input`, record it with its `answer_command`, then re-read with `--slug`; `A different company` → as Exit 1. <!-- gate: ctx_select_company --> Exit 1 with another `code`: report it and stop.
#### Execution checkpoint — END OF STEP 1, READ BEFORE CONTINUING
You now have enough to route. **Invoking this skill is not the same as running it.** Cap-table has the
sharpest version of that risk in the fleet, because the arithmetic here looks easy. Post-money is pre plus raise;
the investor's share is the raise over post. A model can produce a confident dilution answer in one turn
without opening a single script — and a founder will take that number into a negotiation.
**Every number that reaches the founder comes out of a producer.** There are four modes and all four run
something:
- **Full pipeline** — `run_scenario.py` and the rest.
- **Fast-assess** — `quick_assess.py`. Under 60 seconds, still a real calculation.
- **Concise** — the real solver, then `concise_report.py`.
- **Rule-lookup** — `verify_one.py --rule-lookup`, which returns the cited constant and its reliance
boundary.
There is no fifth mode where you do the arithmetic yourself. If a question seems too small for any of
these, it is a **rule-lookup** or a **fast-assess**, not a mental calculation.
- **Never compute a figure in chat.** Not ownership, not dilution, not a post-money, not a share count,
not a price per share — not even the one-line ones. A hand-computed cap-table number has no rule citation, no gotcha check, no
audit trail, and no artifact — and it is indistinguishable, to the founder, from one that has all four.
- **Never benchmark against a figure you recalled.** And never state a cap-table rule from memory. Every rule has an id in the rule pack and `verify_one.py`
will cite it. "Pools are usually carved out pre-money" is exactly the kind of usually that is wrong for
a specific term sheet.
- **Splitting an aggregate the producer emitted is still computing in chat.** Apportioning the founders'
block by pre-round ratios to give each founder a post-round number is arithmetic you did, not output you
read, and a disclosure like *"(split proportionally within the founders' 63.3% block)"* does not convert
it into one. It is also the number a founder is most likely to quote in a partner conversation.
**You no longer have to decline the question.** A priced round now emits per-holder post-round ownership
at `scenarios[n].computed_outputs.aggregate_ownership_by_class.founders_by_holder` (keyed by
`founder_id`, carrying `name`, `common_shares`, and `pct`), and `report.md` renders it under
*"each founder, post-round"*. **Read those figures; never derive them.** Two boundaries still hold: the
map is absent on a scenario the solver rejected (say so rather than reconstructing it), and it covers
`founders[]` only — a holder whose shares sit in `common_batches[]` is in the totals but not broken out,
so do not present the list as every shareholder.
- **A what-if, a sensitivity illustration, or "roughly what would X give" is NOT an exemption.** This is
the most natural request in cap-table — *"what if the pool were 15%?"*, *"what if we raised 3M
instead?"* — and it is where the temptation is strongest, because the delta feels like small
arithmetic on a number you already produced properly. It is not: the same solver coupling that makes
the first number non-trivial applies to the second. **re-run the producer with the alternate input**
and quote its outpu
[…] pełny plik w paczce .zip
Files in this package (91)
- SKILL.md 153 KB
- data/cap-table-rules.json 145 KB
- references/cap-table-reference.md 14 KB
- references/cap-table-rules.schema.json 11 KB
- references/carta-pulley-mapping.md 16 KB
- references/coverage.json 1 KB
- references/inputs-skeleton.md 12 KB
- references/sentinel-schema.md 6 KB
- references/lanes/lane-1-pdf-docx.md 27 KB
- references/lanes/lane-2-carta-pulley.md 2 KB
- references/lanes/lane-3-freeform.md 11 KB
- references/lanes/lane-4-structured.md 2 KB
- references/schemas/cap_state.schema.json 13 KB
- references/schemas/counsel_packet.schema.json 1 KB
- references/schemas/coverage-disclosure.schema.json 3 KB
- references/schemas/coverage.schema.json 1 KB
- references/schemas/extraction_only.schema.json 3 KB
- references/schemas/fast_assess_only.schema.json 4 KB
- references/schemas/freeform-role-map.json 8 KB
- references/schemas/inputs.schema.json 12 KB
- references/schemas/instruments.schema.json 9 KB
- references/schemas/rule_audit.schema.json 3 KB
- references/schemas/scenarios.schema.json 23 KB
- references/schemas/sweep.schema.json 2 KB
- scripts/_artifact_io.py 10 KB
- scripts/_artifact_writer.py 2 KB
- scripts/_cap_table_schema_validator.py 11 KB
- scripts/_compose_result.py 11 KB
- scripts/_confidence.py 2 KB
- scripts/_coverage_registry.py 3 KB
- scripts/_ct_gates.py 14 KB
- scripts/_dispatch_json.py 2 KB
- scripts/_docx_text.py 6 KB
- scripts/_emit.py 2 KB
- scripts/_founder_text_keep.py 2 KB
- scripts/_labels.py 4 KB
- scripts/_normalize.py 6 KB
- scripts/_out_guard.py 6 KB
- scripts/_palette.py 2 KB
- scripts/_pool_sizing_claims.py 18 KB
- scripts/_pool_text.py 31 KB
- scripts/_rule_pack.py 1 KB
- scripts/_rules.py 8 KB
- scripts/_run_ref.py 16 KB
- scripts/_theme.py 3 KB
- scripts/_ui.py 38 KB
- scripts/_warning_callouts.py 25 KB
- scripts/anti_dilution.py 7 KB
- scripts/backward_verifier.py 20 KB
- scripts/cap_state.py 66 KB
- scripts/cap_state_after_round.py 10 KB
- scripts/compose_extraction_report.py 32 KB
- scripts/compose_report.py 111 KB
- scripts/concise_report.py 15 KB
- scripts/counsel_packet.py 9 KB
- scripts/cross_checker.py 6 KB
- scripts/detect_structure.py 6 KB
- scripts/evidence_verifier.py 24 KB
- scripts/explore.py 91 KB
- scripts/extract_aoa.py 30 KB
- scripts/extract_cap_table.py 63 KB
- scripts/extract_instrument.py 63 KB
- scripts/extract_pdf_tables.py 6 KB
- scripts/flip_scenario.py 11 KB
- scripts/freeform_mapper.py 41 KB
- scripts/invariant_checker.py 13 KB
- scripts/note_conversion.py 25 KB
- scripts/option_pool.py 9 KB
- scripts/pdf_probe.py 6 KB
- scripts/pool_check_release.py 5 KB
- scripts/pool_claims_check.py 13 KB
- scripts/pool_clause.py 5 KB
- scripts/priced_round.py 110 KB
- scripts/quick_assess.py 37 KB
- scripts/rule_audit.py 66 KB
- scripts/run_scenario.py 54 KB
- scripts/safe_conversion.py 34 KB
- scripts/sweep.py 8 KB
- scripts/verify_one.py 7 KB
- scripts/visualize.py 43 KB
- scripts/warrant_exercise.py 15 KB
- scripts/write_coverage_disclosure.py 10 KB
- scripts/extractors/__init__.py 1 KB
- scripts/extractors/types.py 4 KB
- scripts/extractors/safe/__init__.py 1 KB
- scripts/extractors/safe/discount_multiplier.py 7 KB
- scripts/extractors/safe/investor_name.py 1 KB
- scripts/extractors/safe/issuance_date.py 3 KB
- scripts/extractors/safe/purchase_amount.py 3 KB
- scripts/extractors/safe/valuation_cap.py 6 KB
- scripts/vendor/chart.min.js 202 KB
Versions
The database has no other skills named cap-table.
Database snapshot: 13.11.2026 · package version 0da69794f458 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90cap-table-manager
Use when a founder needs to understand or model ownership and dilution. Triggers on "model my cap table", "how much will I be diluted", "option pool", "SAFE conversion", "post-money vs pre-money", "what do I own after this round", "pro rata". Turns equity from a black box into a… - 100safe-vs-priced-round
Use when a founder is choosing how to structure a raise. Triggers on "SAFE vs priced round", "should I use a SAFE", "valuation cap vs discount", "post-money SAFE", "convertible note", "when to do a priced round", "MFN clause". Explains the instruments and their real dilution consequences. - 87seed-terms
Term Sheet Reader. Reads a SAFE or a term sheet in plain English, does the dilution math and flags the clauses to ask a lawyer about. Works out what a post-money SAFE owns at its cap and what it converts into at a priced round (cap price vs discount price, whichever is lower),… - 100model-cap-table-and-dilution
Model a startup cap table and the dilution a round causes — including option-pool shuffle, pro-rata, and post-money SAFE conversion — with worked arithmetic. Produces a post-round ownership table and surfaces the post-money-cap dilution gotcha. Reach for this when the user asks… - 100cap-table-waterfall
Model cap table dilution, SAFE conversion, and exit waterfall across scenarios. Triggered by: "/venture-capital-intelligence:cap-table-waterfall", "model my cap table", "simulate dilution", "SAFE conversion math", "exit waterfall", "how much do I own after Series A",… - 95cap-table-analyst
Works through dilution and ownership on a cap table using only the share counts, valuations, and round terms actually supplied — showing the arithmetic for every calculation and flagging option-pool timing, conversion order, or preference terms that were not specified rather…