# 12–15 Slide Investor Deck Architecture

## Base 12-slide sequence

| # | Investor question | Required proof | Strong visual |
|---:|---|---|---|
| 1 | What are you? | Product definition + company/brand | Clean cover or one visual metaphor |
| 2 | What hurts? | Concrete user moment, frequency, cost | Before workflow, quote, or pain funnel |
| 3 | What changes? | Specific product response | Before/after or solution flow |
| 4 | Does it work? | Real product or experience | Product screenshot / demo sequence |
| 5 | Why now? | 2–3 structural changes | Timeline or converging trend chart |
| 6 | What is proven? | Usage, retention, revenue, speed, or pilots | Evidence ladder / cohort / verified metrics |
| 7 | How do you make money? | Buyer, offer, price, sales motion | Value/revenue staircase |
| 8 | How large can it be? | Source-backed TAM/SAM/SOM + wedge | Market bridge / rings with methodology |
| 9 | Why you vs. alternatives? | Honest competitor dimensions | Matrix, table, or value-chain map |
| 10 | How will you grow? | Channels, milestones, economics | Funnel, flywheel, or phased roadmap |
| 11 | Why this team? | Founder-market/product fit | Evidence timeline, not résumé wall |
| 12 | What are you raising? | Ask, use, runway, 18–24 month proof | Use-of-funds chart + milestone gates |

## When to expand to 13–15 slides

Add a page only when it carries evidence that cannot fit cleanly elsewhere:

- a second product-demo page for a complex workflow;
- a technology/moat page with measurable defensibility;
- a dedicated go-to-market wedge page;
- a regulated/B2B deployment model;
- a financial model when revenue complexity materially affects the investment case.

Do not add generic mission, feature grids, long roadmaps, or “thank you” pages merely
to reach a page count.

## Slide contract

Each outline entry should contain:

```markdown
## Slide 06 — Real validation

Headline: One conclusion, not a topic label
Investor takeaway: What uncertainty this page removes
Evidence: Exact facts and source IDs
Visual: Chart type and field mapping
Speaker purpose: Why this page exists in the spoken story
Gap: Missing evidence or “none”
```

## Page discipline

- One page, one argument.
- The headline contains the conclusion.
- A viewer should understand the page in 8–12 seconds.
- Keep only the numbers needed for the conclusion.
- Put methodology and source notes at the bottom, not in the speaker's memory.
- 8–10 minutes means roughly 35–50 seconds per page; demo pages may take longer.

## Executive summary rule

For a long-form business plan, write the executive summary last. It must include:

1. what the company does;
2. problem and buyer;
3. solution and difference;
4. market opportunity with a traceable number;
5. exact ask and what it unlocks.

The pitch deck's first and last pages should make the same promise and ask, from
opposite ends of the argument.

# Evidence and Market Sizing

## Evidence classes

Every material claim belongs to one class:

| Class | Meaning | How to present |
|---|---|---|
| Fact | Directly supported by a reliable source | State with source and as-of date |
| Inference | Reasoned conclusion from facts | Label as inference and show bridge |
| Assumption | Planning input not yet verified | Label and sensitivity-test |
| Missing | Necessary evidence not yet available | Keep as a named gap, never fill by intuition |

## Source hierarchy

Prefer sources in this order:

1. Product database, payment processor, analytics, contracts, repository history.
2. Direct customer interviews, support conversations, signed pilots, orders.
3. Official government, company, exchange, standards, or research data.
4. Reputable analyst/research reports with disclosed methodology.
5. Quality secondary reporting.
6. Search snippets, social posts, and unsourced aggregations only as leads.

Time-sensitive facts must be checked live. Capture the date and exact URL. If a
source is inaccessible, say so in the report.

## Evidence ledger format

| ID | Claim | Status | Source | As of | Slide | Notes / next action |
|---|---|---|---|---|---|---|
| E-001 | ... | fact | URL or dashboard export | YYYY-MM-DD | 6 | ... |

Use stable IDs in the outline so charts and slide copy can be traced back.

## TAM / SAM / SOM methodology

Do not paste a broad “AI will be worth $X trillion” forecast into a deck. Build a
bridge from actual buyer to price.

### TAM

All plausible buyers × annual value of the complete category.

```text
TAM = global buyer count × realistic annual spend per buyer
```

Use a top-down source only as a cross-check.

### SAM

The part of TAM reachable by current product scope, geography, regulation, and sales
motion.

```text
SAM = target buyer count in reachable segments × current annual contract value
```

### SOM

A three-to-five-year operating plan, not a percentage chosen for visual symmetry.

```text
SOM = acquired accounts × annual price × expected retention
```

Show the channel capacity or sales capacity that makes acquired accounts credible.

## Scenario model

Use at least two scenarios:

- conservative: slower conversion, lower price, longer sales cycle;
- base: management plan;
- upside: only if named leading indicators improve.

Never present the upside case as a forecast. Put assumptions next to the chart.

## Metric hygiene

- Distinguish downloads, clones, activated users, active users, retained users, and
  paid users.
- Distinguish trial, activation, conversion, renewal, and revenue.
- Use cohorts for retention; do not infer retention from cumulative installs.
- Define the period, denominator, timezone, duplicates, bots, and internal usage.
- Put “as of YYYY-MM-DD” on changing metrics.
- When the number is zero, say zero; the honest gap can define the financing thesis.

# Investor Story

## The investor's reading order

An investor does not read a BP like a product manual. The sequence is closer to:

1. Can I understand what this is in ten seconds?
2. Is the pain real, frequent, and expensive enough?
3. Is the product response specific and demonstrable?
4. Why can this become large now?
5. What has already been de-risked?
6. How does money enter the system?
7. Why will this team win?
8. What exactly does this financing buy?

Every slide should reduce one uncertainty in that order.

## Three layers of positioning

### Layer 1: Product definition

State the category or the completed job. It should be repeatable, not poetic.

- Chinese: ideally 14–20 characters.
- English: ideally 8–12 words.
- One subject, one category/job, one clear beneficiary.
- Do not lead with architecture, protocols, model names, or number of Agents.

Draft three alternatives:

1. **Literal category** — “面向 X 的 Y”。
2. **Comparator** — “X 版的 Y” or “X for Y”.
3. **Category creation** — a new category with an immediate plain-language gloss.

Choose the line a non-technical investor can repeat accurately after ten seconds.

### Layer 2: Market wedge

Name the first buyer and the urgent use case. A credible wedge is narrower than the
vision but large enough to prove demand.

```text
Core wedge → adjacent users → long-term market
```

Do not confuse the wedge with the final market, or describe the final market as the
current customer base.

### Layer 3: Vision

Explain the structural change that makes the company matter. Vision earns its place
after the product and wedge are clear.

## Product vs. implementation

Ask: “If this mechanism changed tomorrow, would the customer still buy the result?”

- If yes, it is implementation and should not define the company.
- If no, it may be the category or moat.

Examples of implementation-heavy framing:

- number of Agents;
- local vs. cloud runtime without explaining user benefit;
- branch/worktree selection;
- model/provider list;
- architecture components.

Translate them into the user consequence: continuity, control, trust, speed, cost,
collaboration, or creative freedom.

## Before / after test

| Weak | Better |
|---|---|
| “We integrate many models and Agents.” | “One workspace keeps AI work controllable from idea to delivery.” |
| “Local-first multi-Agent orchestration.” | “Your work, context, and choices stay portable while AI does the execution.” |
| “Everyone can command an Agent team.” | “Creators can reliably turn intent into finished digital products.” |

The “better” line is still a hypothesis. It must match the actual product and buyer.

## Narrative red flags

- The first three slides require a glossary.
- The one-liner is a slogan with no product noun or job.
- The company is defined by a feature available in every model vendor.
- The market slide appears before the buyer is clear.
- The deck claims “no competitors” or makes strong competitors look foolish.
- Vision, TAM, and product roadmap describe three different businesses.
- The financing ask does not connect to the key risks still unproven.

# User Configuration

This skill follows the portable agent skill profile contract. It must not
assume a private workspace, personal absolute paths, or private brand assets.

## Resolution Order

1. Explicit CLI flags.
2. Environment variables.
3. Shared profile JSON.
4. Safe defaults such as the current working directory or `$HOME/Documents`.
5. Ask the user once for missing required fields.

## Shared Profile

Default profile path:

```bash
${SKILL_PROFILE_PATH:-$HOME/.skill-publisher/skills/profile.json}
```

Example:

```json
{
  "user": {
    "name": "Your Name",
    "language": "zh-CN",
    "timezone": "Asia/Shanghai"
  },
  "workspace": {
    "root": "$HOME/projects",
    "output_dir": "$HOME/Documents/lov-skill-output"
  },
  "brand": {
    "name": "Your Brand",
    "site": "https://example.com",
    "profile": "$HOME/.skill-publisher/skills/brand.json",
    "design_guide": "$HOME/.skill-publisher/skills/design-guide.md"
  }
}
```

Environment variable overrides:

| Variable | Meaning |
|----------|---------|
| `SKILL_PROFILE_PATH` | Path to the shared profile JSON |
| `SKILLS_CONFIG_DIR` | Shared Skill Publisher skills config/data directory |
| `SKILL_WORKSPACE_ROOT` | User workspace root |
| `SKILL_OUTPUT_DIR` | Default generated output directory |
| `SKILL_PROFILE_PATH` | Brand profile JSON or Markdown |
| `SKILL_DESIGN_GUIDE` | Design guide path |

BP-specific overrides take precedence over shared values:

| Variable | Meaning |
|----------|---------|
| `SKILL_BP_OUTPUT_DIR` | Default output directory for BP workspaces |
| `SKILL_BP_BRAND_PROFILE` | Brand profile used by the deck |
| `SKILL_BP_DESIGN_GUIDE` | Visual design guide used by the deck |

If none are set, use an explicit `--output` path or a project-local
`business-plan/` directory. Never assume an author's private workspace.

## Implementation Notes

- Store source descriptions in `evidence-ledger.md`; do not copy secrets into the
  BP workspace.
- Prefer relative paths inside the workspace so it can be moved or shared.
- Brand files remain user-owned inputs. The public Yoda assets are an example, not
  a default theme.

- Scripts should accept explicit paths via CLI flags.
- Missing profile fields should produce actionable errors.
- Skill Publisher maintainer defaults belong in an optional profile, not in the workflow.

#!/usr/bin/env python3
"""Create a portable investor-BP workspace without overwriting existing work."""

from __future__ import annotations

import argparse
import datetime as dt
import json
import os
import re
import sys
from pathlib import Path
from typing import Any, Dict, Optional


def expand_path(value: str) -> Path:
    return Path(os.path.expandvars(os.path.expanduser(value))).resolve()


def slugify(value: str) -> str:
    normalized = re.sub(r"[^\w\u4e00-\u9fff]+", "-", value.strip().lower(), flags=re.UNICODE)
    return normalized.strip("-_") or "project"


def load_profile(path: Path) -> Dict[str, Any]:
    if not path.exists():
        return {}
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise SystemExit(f"Cannot read profile {path}: {exc}") from exc
    if not isinstance(data, dict):
        raise SystemExit(f"Profile must be a JSON object: {path}")
    return data


def nested(data: Dict[str, Any], *keys: str) -> Optional[str]:
    current: Any = data
    for key in keys:
        if not isinstance(current, dict):
            return None
        current = current.get(key)
    return current if isinstance(current, str) and current.strip() else None


def resolve_output(args: argparse.Namespace, profile: Dict[str, Any]) -> Path:
    if args.output:
        return expand_path(args.output)
    skill_output = os.environ.get("SKILL_BP_OUTPUT_DIR")
    if skill_output:
        return expand_path(skill_output) / f"{slugify(args.name)}-business-plan"
    shared_output = os.environ.get("SKILL_OUTPUT_DIR")
    if shared_output:
        return expand_path(shared_output) / f"{slugify(args.name)}-business-plan"
    profile_output = nested(profile, "workspace", "output_dir")
    if profile_output:
        return expand_path(profile_output) / f"{slugify(args.name)}-business-plan"
    return (Path.cwd() / "business-plan").resolve()


def resolve_optional(explicit: Optional[str], env_name: str, profile: Dict[str, Any], key: str) -> str:
    value = explicit or os.environ.get(env_name) or nested(profile, "brand", key)
    return str(expand_path(value)) if value else "not configured"


def render_template(template: Path, destination: Path, values: Dict[str, str]) -> None:
    text = template.read_text(encoding="utf-8")
    for key, value in values.items():
        text = text.replace("{{" + key + "}}", value)
    destination.write_text(text, encoding="utf-8")


def ensure_safe_destination(output: Path) -> None:
    home = Path.home().resolve()
    if output in {Path("/").resolve(), home}:
        raise SystemExit(f"Refusing to use broad destination: {output}")
    if output.exists() and any(output.iterdir()):
        raise SystemExit(
            f"Destination already contains files: {output}\n"
            "Continue in that workspace manually or choose a new --output path."
        )


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Create a source-backed 12–15 slide investor-BP workspace."
    )
    parser.add_argument("--name", required=True, help="Project or company name")
    parser.add_argument(
        "--stage",
        default="seed",
        choices=("pre-seed", "seed", "angel", "pre-a", "series-a", "growth", "other"),
        help="Financing stage (default: seed)",
    )
    parser.add_argument("--output", help="Exact workspace directory")
    parser.add_argument("--profile", help="Shared Skill Publisher skills profile JSON")
    parser.add_argument("--brand-profile", help="Brand profile file")
    parser.add_argument("--design-guide", help="Design guide file")
    parser.add_argument("--json", action="store_true", help="Print machine-readable result")
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    profile_path = expand_path(
        args.profile
        or os.environ.get("SKILL_PROFILE_PATH")
        or "$HOME/.skill-publisher/skills/profile.json"
    )
    profile = load_profile(profile_path)
    output = resolve_output(args, profile)
    ensure_safe_destination(output)

    skill_root = Path(__file__).resolve().parent.parent
    template_root = skill_root / "assets" / "templates"
    required_templates = {
        "brief.md": template_root / "brief.md",
        "evidence-ledger.md": template_root / "evidence-ledger.md",
        "outline.md": template_root / "outline.md",
    }
    missing = [str(path) for path in required_templates.values() if not path.exists()]
    if missing:
        raise SystemExit("Missing templates:\n- " + "\n- ".join(missing))

    output.mkdir(parents=True, exist_ok=True)
    (output / "assets").mkdir(exist_ok=True)
    (output / "assets" / ".gitkeep").touch()

    today = dt.date.today().isoformat()
    values = {
        "PROJECT_NAME": args.name.strip(),
        "STAGE": args.stage,
        "DATE": today,
        "VERSION": "draft-0.1",
    }
    created = []
    for relative, template in required_templates.items():
        destination = output / relative
        render_template(template, destination, values)
        created.append(str(destination))

    brand_profile = resolve_optional(
        args.brand_profile, "SKILL_BP_BRAND_PROFILE", profile, "profile"
    )
    design_guide = resolve_optional(
        args.design_guide, "SKILL_BP_DESIGN_GUIDE", profile, "design_guide"
    )
    source_note = output / "source-config.md"
    source_note.write_text(
        "# BP Source Configuration\n\n"
        f"- Project: {args.name.strip()}\n"
        f"- Stage: {args.stage}\n"
        f"- Created: {today}\n"
        f"- Brand profile: {brand_profile}\n"
        f"- Design guide: {design_guide}\n\n"
        "Do not store credentials or private customer data in this file.\n",
        encoding="utf-8",
    )
    created.append(str(source_note))

    result = {
        "project": args.name.strip(),
        "stage": args.stage,
        "workspace": str(output),
        "created": created,
    }
    if args.json:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        print(f"Created investor-BP workspace: {output}")
        for path in created:
            print(f"  - {path}")
        print("Next: replace missing/TODO items, pass the evidence gate, then use bp-deck.")
    return 0


if __name__ == "__main__":
    sys.exit(main())