market-sizing

Market Sizing Skill

Help startup founders build credible, defensible TAM/SAM/SOM analysis — the kind that earns investor trust rather than raising eyebrows. Produce a structured, validated market sizing with external sources, sensitivity testing, and a self-check against common pitfalls. The tone is founder-first: a rigorous but supportive coaching session.

Skill Metadata

• Author: lool-ventures
• Version: managed in founder-skills/.claude-plugin/plugin.json
• Compatibility: Python 3.10+ and uv for script execution.
• Exports:
• sizing.json → financial-model-review, ic-sim, fundraise-readiness
• sensitivity.json → financial-model-review
• checklist.json → ic-sim

Skill Execution Model (READ FIRST)

This skill runs inline in the main thread (not as a sub-agent). The main thread has full tool access including Bash and WebFetch, and is responsible for orchestrating the full pipeline: running producer scripts, persisting artifacts, performing web research, and dispatching the market-sizing sub-agent at specific moments.

Two dispatch contexts for the sub-agent:

• Context A — Per-step analytical dispatch (Mitigation 1): Steps 5 and 6 dispatch the market-sizing agent via the Task tool. The key element here is parallel dispatch: Step 5 (methodology calculation) dispatches the agent twice simultaneously — one for TOP_DOWN_METHODOLOGY and one for BOTTOM_UP_METHODOLOGY — in a single assistant turn when the methodology is "both". The sub-agent does deep analysis and returns structured JSON. The main thread captures the JSON and pipes it through the producer script (market_sizing.py --stdin). The sub-agent does NOT write artifacts directly.
• Context B — Post-compose coaching dispatch: The final step dispatches the sub-agent after compose_report.py --write-md has written report.md. The sub-agent reads report.md, appends ## Coaching Commentary, verifies all canonical artifacts on disk, and returns a structured success payload.

Why this model: In Cowork, sub-agents have a restricted tool allowlist (no Bash). By keeping orchestration in the main thread and dispatching sub-agents only for analytical or post-compose tasks that use only Read/Edit/Glob/Grep, the pipeline works correctly in both Claude Code (CLI) and Cowork.

WebFetch-before-dispatch pattern: The main thread performs WebFetch/WebSearch research calls BEFORE dispatching sub-agents. Research data is passed inline in the sub-agent prompts. Sub-agents in Cowork cannot reach the network from inside the dispatch fork (no WebFetch/WebSearch in sub-agent allowlist).

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."

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

Input Formats

Accept any format: pitch deck (PDF, PPTX, markdown), financial model, market data, text descriptions, or verbal description of the business.

Available Scripts

All scripts are at ${CLAUDE_PLUGIN_ROOT}/skills/market-sizing/scripts/:

• market_sizing.py — TAM/SAM/SOM calculator (top-down, bottom-up, or both); accepts --stdin for JSON piping
• sensitivity.py — Stress-test assumptions with low/base/high ranges and confidence-based auto-widening
• checklist.py — Validates 22-item self-check with pass/fail per item
• compose_report.py — Assembles report with cross-artifact validation; --write-md writes report.md; --strict exits 1 on high/medium warnings
• visualize.py — Generates self-contained HTML with SVG charts (not JSON)

Also available from ${CLAUDE_PLUGIN_ROOT}/scripts/ (shared):

• founder_context.py — Per-company context management (init/read/merge/validate)

Run with: python3 ${CLAUDE_PLUGIN_ROOT}/skills/market-sizing/scripts/<script>.py --pretty [args]

Available References

Read as needed from ${CLAUDE_PLUGIN_ROOT}/skills/market-sizing/references/:

• tam-sam-som-methodology.md — Definitions, calculation methods, industry examples, best practices
• pitfalls-checklist.md — Self-review checklist for common mistakes
• artifact-schemas.md — JSON schemas for all analysis artifacts

Artifact Pipeline

Every analysis deposits structured JSON artifacts into a working directory. The final step assembles all artifacts 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) | | 3 | methodology.json | Agent (heredoc) | | 4 | validation.json | Main thread (WebFetch/WebSearch research) | | 5 | sizing.json | Context A dispatch: TOP_DOWN_METHODOLOGY + BOTTOM_UP_METHODOLOGY in parallel → market_sizing.py --stdin | | 6a | sensitivity.json | Context A dispatch: SENSITIVITY_TEST → sensitivity.py | | 6b | checklist.json | Context A dispatch: CHECKLIST → checklist.py | | 7 | Report | compose_report.py --write-md (writes both report.json and report.md) | | 8 | Coaching | Context B dispatch: POST_COMPOSE_COACHING |

Rules:

• Deposit each artifact before proceeding to the next step
• For agent-written artifacts (Steps 2-4), consult references/artifact-schemas.md for the JSON schema
• If a step is not applicable, deposit a stub: {"skipped": true, "reason": "..."}
• Do NOT use isolation: "worktree" for sub-agents — files written in a worktree won't appear in the main $ANALYSIS_DIR

Keep the founder informed with brief, plain-language updates at each step. Never mention file names, scripts, or JSON. After each analytical step (5–6), share a one-sentence finding before moving on.

Workflow

Step 0: Path Setup

Every Bash tool call runs in a fresh shell — variables do not persist. Prefix every Bash call that uses these paths with the variable block below, or substitute absolute paths directly:

SCRIPTS="${CLAUDE_PLUGIN_ROOT}/skills/market-sizing/scripts"
REFS="${CLAUDE_PLUGIN_ROOT}/skills/market-sizing/references"
SHARED_SCRIPTS="${CLAUDE_PLUGIN_ROOT}/scripts"
SHARED_REFS="${CLAUDE_PLUGIN_ROOT}/references"
if ls "$(pwd)"/mnt/*/ >/dev/null 2>&1; then
  ARTIFACTS_ROOT="$(ls -d "$(pwd)"/mnt/*/ | head -1)artifacts"
elif ls "$(pwd)"/sessions/*/mnt/*/ >/dev/null 2>&1; then
  ARTIFACTS_ROOT="$(ls -d "$(pwd)"/sessions/*/mnt/*/ | head -1)artifacts"
else
  ARTIFACTS_ROOT="$(pwd)/artifacts"
fi

If CLAUDE_PLUGIN_ROOT is empty, fall back: Glob for **/founder-skills/skills/market-sizing/scripts/market_sizing.py, strip to get SCRIPTS, derive REFS and SHARED_SCRIPTS.

If ARTIFACTS_ROOT resolves to $(pwd)/artifacts but no artifacts/ directory exists at $(pwd): Use Glob with pattern **/artifacts/founder_context.json to locate existing artifacts, and derive ARTIFACTS_ROOT from the result. If nothing is found, mkdir -p "$ARTIFACTS_ROOT" and proceed.

After Step 1 (when the slug is known):

ANALYSIS_DIR="$ARTIFACTS_ROOT/market-sizing-${SLUG}"
mkdir -p "$ANALYSIS_DIR"
mkdir -p "$ANALYSIS_DIR/.staging"   # for ad-hoc su