deck-review

Deck Review Skill

Help startup founders strengthen their pitch decks before sending them to investors. Produce a structured, scored review with specific, actionable recommendations grounded in current best practices from Sequoia, DocSend, YC, a16z, and Carta data. The tone is founder-first: a candid coaching session, not a VC evaluation.

Skill Metadata

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

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 is responsible for orchestrating the full pipeline: running producer scripts, persisting artifacts, and dispatching the deck-review sub-agent at specific moments.

Two dispatch contexts for the sub-agent:

• Context A — Per-step analytical dispatch (Mitigation 1): Steps 4 and 5 dispatch the deck-review agent via the Task tool. The agent does deep analysis and returns structured JSON. The main thread captures the JSON and pipes it through the producer script (slide_reviews.py or checklist.py). The sub-agent does NOT write artifacts directly.
• Context B — Post-compose coaching dispatch: Step 7 dispatches the sub-agent after compose_report.py writes 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.

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: PDF, PowerPoint (PPTX), markdown, or text descriptions of slides.

Available Scripts

All scripts are at ${CLAUDE_PLUGIN_ROOT}/skills/deck-review/scripts/:

• checklist.py — Scores 35 criteria across 7 categories (pass/fail/warn/not_applicable)
• compose_report.py — Assembles artifacts into final report with cross-artifact validation; --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/deck-review/scripts/<script>.py --pretty [args]

Available References

Read as needed from ${CLAUDE_PLUGIN_ROOT}/skills/deck-review/references/:

• deck-best-practices.md — Full best practices: slide frameworks, stage-specific guidelines, design rules, AI-company requirements
• checklist-criteria.md — Definitions for all 35 criteria with pass/fail/warn thresholds
• artifact-schemas.md — JSON schemas for all artifacts

Artifact Pipeline

Every review 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 | deck_inventory.json | deck_inventory.py (agent provides JSON via stdin) | | 3 | stage_profile.json | stage_profile.py (agent provides JSON via stdin) | | 4 | slide_reviews.json | slide_reviews.py (agent provides JSON via stdin) | | 5 | checklist.json | checklist.py | | 6 | Report | compose_report.py (writes both report.json and report.md) |

Rules:

• Deposit each artifact before proceeding to the next step
• For producer-script artifacts (Steps 2-4), the agent supplies JSON on stdin and 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 the schema is enforced.
• If a step is not applicable, deposit a stub: {"skipped": true, "reason": "..."}

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

Workflow

Step 0: Path Setup

SCRIPTS="${CLAUDE_PLUGIN_ROOT}/skills/deck-review/scripts"
REFS="${CLAUDE_PLUGIN_ROOT}/skills/deck-review/references"
SHARED_SCRIPTS="${CLAUDE_PLUGIN_ROOT}/scripts"
ARTIFACTS_ROOT="${ARTIFACTS_ROOT:-$(pwd)/artifacts}"
mkdir -p "$ARTIFACTS_ROOT"

# Preliminary RUN_ID — used by Step 1 (founder_context init) before slug-aware
# setup_run.py runs. Will be reused by setup_run via --run-id, OR overwritten
# by gate_state.json on re-invocation (see below).
RUN_ID="${RUN_ID:-$(date -u +%Y%m%dT%H%M%SZ)}"

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

After Step 1 (when the slug is known) — call setup_run.py to resolve REVIEW_DIR and clean stale state in one atomic step. Re-invocation special case: if the caller's task prompt indicated this is a resume (it includes REVIEW_DIR=... and / or RUN_ID=..., or $REVIEW_DIR/gate_state.json already exists with a non-empty answer), rehydrate RUN_ID from gate_state.json's metadata.run_id and skip the --clean flag:

# Resolve REVIEW_DIR (from prompt if provided, else derive)
if [ -z "$REVIEW_DIR" ]; then
  REVIEW_DIR="$ARTIFACTS_ROOT/deck-review-$SLUG"
fi
mkdir -p "$REVIEW_DIR"
mkdir -p "$REVIEW_DIR/.staging"   # for ad-hoc sub-agent JSON staging (v0.4.2)

IS_RESUMING=""
if [ -f "$REVIEW_DIR/gate_state.json" ]; then
  GATE_ANSWER="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("answer",""))' "$REVIEW_DIR/gate_state.json")"
  if [ -n "$GATE_ANSWER" ]; then
    IS_RESUMING=1
    RUN_ID="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("metadata",{}).get("run_id",""))' "$REVIEW_DIR/gate_state.json")"
  fi
fi

if [ -z "$IS_RESUMING" ]; then
  SETUP_JSON="$(python3 "$SCRIPTS/setup_run.py" \
    --artifacts-root "$ARTIFACTS_ROOT" \
    --slug "$SLUG" \
    --run-id "$RUN_ID" \
    --clean \
    --pretty)"
  REVIEW_DIR="$(echo "$SETUP_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["review_dir"])')"
  # RUN_ID stays the preliminary value passed via --run-id; setup_run echoes it back.
fi

Pass RUN_ID to every producer script via --run-id. Producer scripts inject it into metadata.run_id automatically. compose_report.py enforces that all required artifacts share the same run_id and emits a MISSING_METADATA (high) warning for any artifact without one. **The rehydration