# Charts and Visual Standards

## Visual principle

The design should combine product-launch clarity, consulting-report credibility, and
the evidence texture of a real startup. “Premium” comes from editing and hierarchy,
not decoration.

## Baseline

- 16:9 landscape.
- White or warm-gray background and one brand accent.
- Dark headline, large conclusion, body text at least 20 pt.
- One dominant visual per page and roughly one-third breathing room.
- Product screenshots, customer scenes, workflows, interview evidence, and orders
  before stock photography.
- Do not stretch logos; align by optical weight, not only bounding boxes.

## Choose the proof, then the chart

| Claim | Recommended visual |
|---|---|
| Process is fragmented | Before workflow / swimlane |
| Product compresses work | Before/after or time-to-outcome bars |
| Category is shifting | Timeline or converging trends |
| Product closes a loop | Circular process with evidence rail |
| Product has depth | Layered architecture with customer consequences |
| Traction has stages | Evidence ladder or funnel |
| Retention is improving | Cohort heatmap or retention curves |
| Revenue expands with value | Value/revenue staircase |
| Market bridges to revenue | Buyer bridge or concentric market with formula |
| Competitive position | 2×2 only when axes are defensible; otherwise comparison table |
| Growth has two entry points | Dual funnel / phased path |
| Financing buys proof | Use-of-funds donut + milestone gates |

## Chart requirements

Every quantitative chart needs:

- title containing the conclusion;
- axes and units when applicable;
- time period and as-of date;
- legend where more than one series exists;
- source or evidence IDs;
- assumptions beside the number, not hidden in notes;
- “illustrative / 示意” label for non-measured conceptual curves.

Avoid 3D charts, gauges, decorative radar charts, dual axes without necessity, and
large coordinate systems with tiny data differences.

## Product screenshots

- Use real current screenshots.
- Crop to the workflow being proved.
- Add 1–3 callouts maximum.
- Keep interface text legible at normal presentation size.
- State what is live, prototype, planned, or illustrative.
- Do not reconstruct a fake UI when the real product exists.

## Cover

A seed BP cover should usually contain only:

- product/company name or logo;
- one investor-readable definition;
- optional financing stage/date.

Use a single centered composition or a strong branded band. Do not fill the cover
with feature tags, funding terms, or multiple logos competing for attention.

## Final page

The final page should answer:

- how much is being raised;
- equity/structure when disclosed;
- runway or time window;
- 2–4 proofs the financing will buy;
- one clear contact action.

If QR codes are present, decode the final rendered image—not only the source asset.

# BP Review Rubric

## Content score (100)

| Dimension | Weight | Pass condition |
|---|---:|---|
| Story structure | 25 | All 12 investor questions are answered in a coherent order |
| Investor readability | 20 | Product is clear in ten seconds; headlines state conclusions |
| Evidence and data hygiene | 25 | Core claims trace to sources; assumptions are labeled |
| Charts and visual specification | 20 | Each page names the right proof and chart, not decoration |
| Financing delivery | 10 | Exact ask, use of funds, runway/window, and milestones connect |

Target: 85+. A high score does not override a blocker.

## Blockers

- Invented or untraceable core metrics.
- Unlabeled market/revenue assumption.
- No clear product definition or buyer.
- No real product or experience proof when one exists.
- No financing amount, use, or validation milestones.
- Placeholder/TODO text.
- Broken source, broken QR code, unreadable slide, or incorrect filename.

## Adversarial review lenses

Review the deck as four people:

1. **Non-technical investor** — what remains unclear after ten seconds?
2. **Category expert** — which claims are technically or competitively naive?
3. **Skeptical partner** — what evidence is missing or overstated?
4. **Design director** — where does layout reduce trust or distort meaning?

For every issue, report page, severity, why it matters, and exact revision.

## Visual QA checklist

- [ ] Contact sheet reviewed at normal size.
- [ ] One claim per slide.
- [ ] Title/body/source hierarchy is consistent.
- [ ] Body text is at least 20 pt.
- [ ] No clipped, overlapping, or off-canvas elements.
- [ ] CJK fonts render correctly.
- [ ] Logos have consistent optical weight.
- [ ] Images are not stretched or low resolution.
- [ ] Charts match evidence ledger and include units/dates/sources.
- [ ] Concept charts are labeled illustrative.
- [ ] Product screenshots are genuine and legible.
- [ ] QR codes decode from the final slide image.
- [ ] Cover and final page are visually calm.
- [ ] PPTX and PDF page counts match.
- [ ] File names contain project, document type, and date/version.

## Report format

Use `assets/templates/bp-review.md`. Lead with verdict and score, then blockers,
page-level findings, evidence gaps, and final delivery checks. Do not begin with a
long description of what the reviewer did.

# 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
"""Deterministic lint for investor BP outlines.

The audit checks structure and evidence hygiene. It intentionally does not pretend
to replace investor judgment or visual inspection.
"""

from __future__ import annotations

import argparse
import datetime as dt
import json
import re
import sys
from pathlib import Path
from typing import Dict, List, Sequence, Tuple


BEATS: Sequence[Tuple[str, Sequence[str]]] = (
    ("product definition", ("product definition", "who you are", "定位", "你是谁", "是什么")),
    ("problem", ("problem", "pain", "用户问题", "具体问题", "痛点")),
    ("solution", ("solution", "how the product solves", "解决方案", "如何解决")),
    ("product demo", ("demo", "core experience", "product experience", "产品演示", "核心体验")),
    ("why now", ("why now", "为什么现在", "时机")),
    ("traction", ("traction", "validation", "proof", "真实验证", "进展", "留存")),
    ("business model", ("business model", "revenue model", "商业模式", "收入模式")),
    ("market", ("market", "tam", "sam", "som", "市场规模", "切入路径")),
    ("competition", ("competition", "competitive", "竞争", "差异化")),
    ("growth", ("growth", "go-to-market", "gtm", "增长计划", "获客")),
    ("team", ("team", "founder", "团队", "创始人")),
    ("financing", ("financing", "fundraise", "raise", "融资", "资金用途")),
)

PLACEHOLDER_RE = re.compile(r"\b(?:TODO|TBD|FIXME|XXX)\b|待补|待确认|missing", re.IGNORECASE)
SLIDE_RE = re.compile(r"^##\s+(?:Slide\s+)?(\d+)(?:\s+of\s+\d+)?\b.*$", re.IGNORECASE | re.MULTILINE)
SLIDE_ZH_RE = re.compile(r"^##\s*第\s*(\d+)\s*页.*$", re.MULTILINE)
HEADLINE_RE = re.compile(r"^(?:Headline|Title|标题|结论)\s*[:：]\s*(.+)$", re.IGNORECASE | re.MULTILINE)
EVIDENCE_RE = re.compile(r"^(?:Evidence|Source|Sources|证据|来源)\s*[:：]\s*(.+)$", re.IGNORECASE | re.MULTILINE)
VISUAL_RE = re.compile(r"^(?:Visual|Chart|图表|视觉)\s*[:：]\s*(.+)$", re.IGNORECASE | re.MULTILINE)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Audit a 12–15 slide investor BP outline.")
    parser.add_argument("--input", required=True, help="outline.md or a workspace containing it")
    parser.add_argument("--output", help="Markdown/JSON report path")
    parser.add_argument("--format", choices=("markdown", "json"), default="markdown")
    parser.add_argument("--min-slides", type=int, default=12)
    parser.add_argument("--max-slides", type=int, default=15)
    parser.add_argument("--strict", action="store_true", help="Exit 1 below 85 or with blockers")
    return parser.parse_args()


def resolve_input(raw: str) -> Path:
    path = Path(raw).expanduser().resolve()
    if path.is_dir():
        path = path / "outline.md"
    if not path.is_file():
        raise SystemExit(f"Outline not found: {path}")
    return path


def parse_slides(text: str) -> List[Dict[str, str]]:
    matches = list(SLIDE_RE.finditer(text))
    if not matches:
        matches = list(SLIDE_ZH_RE.finditer(text))
    slides: List[Dict[str, str]] = []
    for index, match in enumerate(matches):
        start = match.start()
        end = matches[index + 1].start() if index + 1 < len(matches) else len(text)
        block = text[start:end].strip()
        headline = HEADLINE_RE.search(block)
        evidence = EVIDENCE_RE.search(block)
        visual = VISUAL_RE.search(block)
        slides.append(
            {
                "number": match.group(1),
                "block": block,
                "headline": headline.group(1).strip() if headline else "",
                "evidence": evidence.group(1).strip() if evidence else "",
                "visual": visual.group(1).strip() if visual else "",
            }
        )
    return slides


def present(value: str) -> bool:
    return bool(value and not PLACEHOLDER_RE.search(value))


def contains_any(text: str, terms: Sequence[str]) -> bool:
    lowered = text.lower()
    return any(term.lower() in lowered for term in terms)


def audit(text: str, slides: List[Dict[str, str]], minimum: int, maximum: int) -> Dict[str, object]:
    count = len(slides)
    covered = [name for name, terms in BEATS if contains_any(text, terms)]
    missing_beats = [name for name, _ in BEATS if name not in covered]
    headlines = sum(1 for slide in slides if present(slide["headline"]))
    evidence = sum(1 for slide in slides if present(slide["evidence"]))
    visuals = sum(1 for slide in slides if present(slide["visual"]))
    placeholder_count = len(PLACEHOLDER_RE.findall(text))

    structure = min(25, len(covered) * 2 + (1 if minimum <= count <= maximum else 0))
    headline_ratio = headlines / count if count else 0
    readability = round(12 * headline_ratio)
    if contains_any(text, ("investor takeaway", "投资人 takeaway", "投资人结论")):
        readability += 4
    if contains_any(text, ("one-line", "一句话", "product definition", "产品定位")):
        readability += 4
    readability = min(20, readability)

    evidence_ratio = evidence / count if count else 0
    evidence_score = round(14 * evidence_ratio)
    if contains_any(text, ("source", "来源", "evidence", "证据")):
        evidence_score += 4
    if contains_any(text, ("assumption", "假设", "inference", "推断", "fact", "事实")):
        evidence_score += 4
    if contains_any(text, ("as of", "截至", "updated", "更新")):
        evidence_score += 3
    evidence_score = max(0, min(25, evidence_score - min(10, placeholder_count)))

    visual_ratio = visuals / count if count else 0
    visual_score = round(14 * visual_ratio)
    if contains_any(text, ("screenshot", "产品截图", "真实截图", "demo")):
        visual_score += 3
    if contains_any(text, ("chart", "图表", "axis", "坐标轴", "source note", "来源")):
        visual_score += 3
    visual_score = min(20, visual_score)

    delivery = 0
    if contains_any(text, ("financing ask", "融资金额", "raise", "融资")):
        delivery += 4
    if contains_any(text, ("use of funds", "资金用途")):
        delivery += 3
    if contains_any(text, ("milestone", "里程碑", "18–24", "18-24", "runway")):
        delivery += 3

    blockers: List[str] = []
    if not (minimum <= count <= maximum):
        blockers.append(f"Slide count is {count}; expected {minimum}–{maximum}.")
    if missing_beats:
        blockers.append("Missing investor story beats: " + ", ".join(missing_beats) + ".")
    if placeholder_count:
        blockers.append(f"Found {placeholder_count} placeholder or missing markers.")
    if "financing" in missing_beats:
        blockers.append("No clear financing ask.")
    if evidence_ratio < 0.75:
        blockers.append("Fewer than 75% of slides contain a non-placeholder evidence/source field.")

    score = structure + readability + evidence_score + visual_score + delivery
    score = max(0, min(100, score))
    findings: List[str] = []
    if headline_ratio < 1:
        findings.append(f"{count - headlines} slide(s) lack a conclusion headline.")
    if visual_ratio < 1:
        findings.append(f"{count - visuals} slide(s) lack an explicit visual/chart specification.")
    if evidence_ratio < 1:
        findings.append(f"{count - evidence} slide(s) lack an explicit evidence/source field.")
    if score >= 85 and not blockers:
        decision = "investor-ready for visual production"
    elif score >= 70:
        decision = "conditional — revise before rendering"
    else:
        decision = "not ready"

    return {
        "score": score,
        "decision": decision,
        "slide_count": count,
        "scorecard": {
            "story_structure": structure,
            "investor_readability": readability,
            "evidence_hygiene": evidence_score,
            "visual_specification": visual_score,
            "financing_delivery": delivery,
        },
        "coverage": covered,
        "missing_beats": missing_beats,
        "blockers": blockers,
        "findings": findings,
        "placeholder_count": placeholder_count,
    }


def markdown_report(result: Dict[str, object], source: Path) -> str:
    scorecard = result["scorecard"]
    blockers = result["blockers"] or ["None detected by deterministic audit."]
    findings = result["findings"] or ["No structural findings detected."]
    missing = result["missing_beats"] or ["None"]
    lines = [
        "# BP Audit Report",
        "",
        f"- Source: `{source}`",
        f"- Reviewed: {dt.date.today().isoformat()}",
        f"- Score: **{result['score']} / 100**",
        f"- Decision: **{result['decision']}**",
        f"- Slides: {result['slide_count']}",
        "",
        "## Scorecard",
        "",
        "| Dimension | Score | Max |",
        "|---|---:|---:|",
        f"| Story structure | {scorecard['story_structure']} | 25 |",
        f"| Investor readability | {scorecard['investor_readability']} | 20 |",
        f"| Evidence and data hygiene | {scorecard['evidence_hygiene']} | 25 |",
        f"| Charts and visual specification | {scorecard['visual_specification']} | 20 |",
        f"| Financing delivery | {scorecard['financing_delivery']} | 10 |",
        "",
        "## Blockers",
        "",
    ]
    lines.extend(f"- {item}" for item in blockers)
    lines.extend(["", "## Findings", ""])
    lines.extend(f"- {item}" for item in findings)
    lines.extend(["", "## Missing story beats", ""])
    lines.extend(f"- {item}" for item in missing)
    lines.extend(
        [
            "",
            "## Required visual review",
            "",
            "This script cannot validate typography, optical alignment, chart truth, screenshot",
            "legibility, or QR decoding. Review every final rendered page using the visual QA",
            "checklist in `references/review-rubric.md`.",
            "",
        ]
    )
    return "\n".join(lines)


def main() -> int:
    args = parse_args()
    source = resolve_input(args.input)
    text = source.read_text(encoding="utf-8")
    slides = parse_slides(text)
    result = audit(text, slides, args.min_slides, args.max_slides)

    if args.format == "json":
        report = json.dumps(result, ensure_ascii=False, indent=2) + "\n"
    else:
        report = markdown_report(result, source)

    if args.output:
        output = Path(args.output).expanduser().resolve()
        output.parent.mkdir(parents=True, exist_ok=True)
        output.write_text(report, encoding="utf-8")
        print(f"Wrote BP audit report: {output}")
    else:
        print(report, end="" if report.endswith("\n") else "\n")

    if args.strict and (int(result["score"]) < 85 or bool(result["blockers"])):
        return 1
    return 0


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