soreavis/research-entity

Research Entity — Competitive / Due-Diligence Dossier

Generate a board-ready research report on any legal entity. Modular skill: this entrypoint defines the workflow + arguments; segment files contain the heavy reference content (registers, review platforms, mermaid validation, exports, voice rules, persona library, lessons).

Modular skill structure

Core (always or commonly loaded):

File	Loaded when
SKILL.md (this file)	Always — entrypoint
registers.md	Entity is non-US OR has international subsidiaries OR §3.4 Related Entities needs verifying any non-US legal entity
reviews-platforms.md	Step 2 (source gathering) + Step 4 (drafting §11 Community Reception) + §16 negative-review evidence + persona-specific Playbook (talent, customer-renewal, press)
mermaid-validation.md	After Step 4 (Draft) + before any HTML/PDF export + after post-draft edits to mermaid
exports.md	--export=html|pdf|both set OR convert-only mode
voice-and-style.md	Step 4 (Draft) + any post-draft revision
citations.md	Step 4 (Draft) — to know --citations=inline|footnotes|endnotes style + when user asks to convert between styles
playbook-personas.md	Writing §0 Strategic Response Playbook
lessons.md	Reviewing draft for failure-mode patterns + user pushback on aggregator-derived data
confidence-scoring.md	Step 8 — writing the §23 Appendix — Confidence & Methodology section
glossary-catalog.md	Step 4 — writing §22 Glossary; pre-defined catalog of ~100+ canonical entries across funding / standards / security / AI / sales / business-registers categories. Use as a menu against the body scan, not as a literal copy-paste.
risk-scan.md	Always at Step 2 — produces §16.X Red-Flag Scan unless --no-risk-scan. 8 patterns: layoffs, exec departures, lawsuits, breaches, regulatory, Glassdoor, status outages, leadership controversy.

Stage / vertical / template modifiers:

File	Loaded when
stage-templates.md	--stage= set OR auto-detected from /about + funding rows (seed / series-a / series-b / series-c / growth / pe / public)
vertical-templates.md	--vertical= set OR auto-detected from /about keywords (healthcare / fintech / govtech / edtech / legaltech / devtools / consumer / saas / deeptech)

Modes:

File	Loaded when
comparison-mode.md	--compare=A.md,B.md OR --year-over-year set — produces side-by-side or YoY-diff dossier instead of single-entity
stale-detection.md	Convert-only mode (always — to flag freshness before exporting) OR after Step 8 in full-research mode OR user asks "is this still accurate?"
mcp-server.md	--mcp-serve set OR user asks "expose dossiers as MCP" / "make this queryable"

Extended data sources & deep-dives:

File	Loaded when
data-sources-extended.md	--data-sources= set OR auto-activated (US-incorporated → SEC EDGAR; devtool → GitHub; deeptech → USPTO; always cheap → Wayback + LinkedIn + PACER)
benchmarks.md	--benchmark set OR --stage=series-b|growth|pe|public (auto). Adds §X Industry Benchmarks comparing to public cohort medians (Bessemer / OpenView / KeyBanc / ICONIQ / Battery / Sapphire).
audits.md	--audit=pricing|tech-stack|customer-concentration|ai-maturity set (composable) — adds focused deep-dive subsections beyond the default 23

v2.2 Professional methodology layer (gold-standard intelligence-community + Big 4 CDD techniques):

File	Loaded when
analytic-techniques.md	--type=due-diligence|investment (always) OR --analytic-rigor=high set. Implements ACH (Heuer/CIA Analysis of Competing Hypotheses), SATs (Devil's Advocate, Pre-mortem, Key Assumptions Check), and ICD 203 expressed-uncertainty discipline.
source-rating.md	--source-rating=admiralty set OR --type=due-diligence|investment AND --validation=max. Applies the formal NATO/Five Eyes A-F × 1-6 source rating notation alongside our existing ad-hoc labels.
frameworks.md	--framework= set with anything beyond swot (e.g. pestel, porter5, vrio, value-chain, all) OR auto-activated by --vertical= (PESTEL for govtech/healthcare/fintech/edtech/legaltech; Porter5 for consumer; VRIO for devtools/deeptech).
expert-calls.md	--export=expert-call-questions|customer-reference-questions set OR --type=due-diligence|investment AND --depth=deep (auto). Generates Tegus/GLG/Third Bridge expert-call question batteries + 3 variants of customer reference call templates (current, churned, lost-deal-prospect).
competitor-verification.md	MANDATORY for --type=competitive|due-diligence|investment before §10 Market Positioning ships. Pre-publication verification protocol for competitor-row data — lead-investor identity (≥3 sources, named-partner attribution preferred), HQ city (press release dateline canonical), bundled-announcement round structure (Bloomberg/TC primary breakdown), numeric-figure attribution drift (verify cited number is in cited source). Codifies lessons #41-45 from lessons.md into an executable checklist.

v2.6 Public-source verification + ARR triangulation + regulatory overlay layer:

File	Loaded when
source-hierarchy.md	MANDATORY for --type=competitive|due-diligence|investment. Codifies a 4-tier source hierarchy (T1 primary registers/filings/press-release-datelines · T2 named-byline financial press · T3 structured analyst databases · T4 aggregator paraphrase). Adds Wayback Machine forensic source-dating (verify what page said when claim applied) and customer-logo round-trip verification (catch logo-wash). Citations: SPJ Code of Ethics, AICPA AT-C 105, ICIJ standards, Bellingcat handbook, Reuters Handbook of Journalism.
marketplace-signals.md	Auto-load when entity has any marketplace listing (Salesforce AppExchange / HubSpot Marketplace / Atlassian Marketplace / Microsoft AppSource / Slack App Directory / Chrome Web Store / AWS Marketplace / npm / PyPI / GitHub Marketplace). Marketplace install counts are often the only public usage signal for B2B SaaS. Atlassian Marketplace is the gold standard (exact daily-refreshed install counts).
osint-public.md	--depth=deep AND any of: --vertical=security|fintech|govtech (auto-load MITRE ATT&CK / KEV / NVD CVE) OR --data-sources= includes dns, trademark, mitre, linkedin-velocity, job-velocity. Five OSINT layers — job-posting velocity (Greenhouse/Lever/Ashby), MITRE ATT&CK + CISA KEV + NVD, DNS / passive DNS / SSL transparency (crt.sh, SecurityTrails), trademark (USPTO TM Search / EUIPO / WIPO), founder LinkedIn velocity.
arr-triangulation.md	--type=investment|due-diligence AND entity is private SaaS without disclosed audited ARR. ARR-proxy math via Bessemer / OpenView / KeyBanc / ICONIQ / Sapphire $/FTE benchmarks; AE-quota × attainment; marketplace-install conversion; web-traffic conversion.
regulatory-overlay.md	Auto-load when entity has international operations OR --vertical=healthcare|fintech|govtech|legaltech|edtech OR --type=due-diligence. Combines Ghemawat CAGE Distance Framework (HBR 2001) + regulatory exposure (GDPR, EU AI Act, OFAC, HIPAA, PCI DSS, FedRAMP, ISO 27001, etc.).
press-analysis.md	Always for --type=due-diligence|investment and --depth=deep. Three layered analyses: earned-vs-paid press distinction (PRovoke EMI + AMEC Barcelona Principles), conference / event presence (marketing-budget proxy), trust-center auditor verification (Drata/Vanta/Secureframe-hosted vs. self-published; AICPA Peer Review + IAF accreditation lookups).

v2.12 SaaS-CXO layer (NEW — Tier S high-leverage outputs for SaaS executives):

File	Loaded when
win-loss.md	--win-loss flag set OR --type=competitive AND --audience=c-suite|operator|investor (auto-suggest) OR user asks "where do they win?" / "what's their win rate?" / "why do we lose to them?". Codifies public-source win/loss inference (G2/TrustRadius "switched from / switched to" verbatim mining, Reddit thread mining, comparison-page narrative analysis, Glassdoor sales-team commentary) + with-input-data mode (--win-loss=<csv> integrates user's own deal data as ground-truth). Industry validation: Klue, Crayon G2 category, Monetizely. Win-rate benchmarks: 20-35% average / 40-50% high-growth / >50% category-defining. Adds Cat J techniques #73, #83, #89 (win-rate-without-denominator rule, win-driver-needs-3-reviews, verbatim-quote discipline).
saas-economics.md	Auto-load when --audience=board|investor set OR --type=investment|due-diligence AND entity is private B2B SaaS without disclosed audited financials, OR --unit-economics flag set. Multi-method estimation rubrics for NRR / CAC / LTV / CAC Payback. Bessemer canonical tiers (the language SaaS boards speak): 100/110/120 = Good/Better/Best. ICONIQ at-$10M-ARR portfolio: bottom 105% / median 140% / top >145%. Methods: expansion-team inference, case-study upgrade narrative density, investor-disclosure mining, churn-signal inverse-correlation. Adds Cat J techniques #74, #75, #84 (Bessemer-canonical-tier discipline, multi-method estimate band rule, cohort-benchmark citation).
moat-scoring.md	Auto-load when --audience=board|investor OR --type=due-diligence|investment AND --depth=deep, OR --moat=helmer flag set. Implements Hamilton Helmer's 7 Powers framework — the SaaS-investor-class moat lexicon validated by Helmer's 22-year 41.5% CAGR vs 14.9% S&P 500. Each of 7 powers (Scale Economies / Network Economies / Counter-Positioning / Switching Costs / Branding / Cornered Resource / Process Power) scored 0-3 with explicit public-source evidence. Powers don't sum — any single power of 3+ can sustain a business. Adds Cat J techniques #76, #77, #78, #85, #86 (Helmer no-aggregation rule, switching cost friction mechanism, network effect degree-N evidence, counter-positioning incumbent-paralysis, process power 5+ year evidence).
roadmap-inference.md	Auto-load when --depth=deep AND --type=competitive|due-diligence|investment, OR --roadmap flag set. Five-channel public-source inference: job postings (3-9mo horizon), GitHub commits (1-3mo), patents (12-36mo, 40-60% abandonment), conference talks (6-18mo), beta-program leaks (variable). Critical caveat: patent filing ≠ product shipping. Industry validation: Rathvane, Aqute, Visualping. Adds Cat J techniques #79, #80, #81, #82, #87, #88 (patent ≠ product, job-posting horizon, conference ≠ shipping, GitHub ≠ direction, multi-channel convergence, counter-evidence check).

v2.7-v2.11 Internal-consistency + framing-discipline + claim-coverage layer:

File

Loaded when

internal-consistency.md

MANDATORY at Step 5 (Validate) for --type=competitive|due-diligence|investment AND for any dossier edited across multiple revisions. Codifies Cat J anti-hallucination techniques (#50-72) across 23 failure patterns. v2.7 (#50-57): internal-consistency cross-reference scan, version-label sweep, audit-completion-rate honesty, numeric-precision discipline, tier-generosity check, triangulation-independence test, default-outcome probability check, two-dimension confidence rule. v2.9 (#58-60): count-vs-enumeration reconciliation, terminology-rename residue sweep, duplicate-paragraph scan. NEW v2.11 (#61-72) caught by reader-side validation 2026-04-27 on AcmeCRM brief: speaker-vs-founder identity discipline (#61 — press-release quote attributions ≠ founder list), aggregator-data freshness sweep (#62 — T3 citations >12mo need refresh search), parent-network multiplier acknowledgement (#63 — headcount-velocity claims must include parent-network from same source), comprehensive comparison-directory probe (#64 — <entity>/comparison/ is the highest-leverage source for --type=competitive), "not publicly disclosed" verification ladder (#65 — check legal-firm + deal-database + regulatory-filings before claiming privacy), single-feature → category-claim guard (#66 — slot-filling pressure), negation-evidence rule (#67 — "no X" claims need surface + date + searched-strings), quasi-deterministic-claim guard (#68 — "categorically beyond / cannot trivially / will never" → Tetlock-rewrite), comparator-pricing source rule (#69 — competitor prices must link to that competitor's /pricing), subagent-audit blindspot rule (#70 — Step 6 audit shares writer's blindspots; require fresh-fetch sample), load-bearing claim N-source rule (#71 — claim repeated 3+ times needs ≥2 sources), round-number / no-methodology vendor-metric labeling (#72).

v2.8 Skill maintenance + sources-of-record layer:

File	Loaded when
sources-of-record.md	--validate-skill-sources flag set OR maintainer is updating skill citations OR onboarding new maintainer. Central registry of every load-bearing external source cited by the skill — primary URL, backup/mirror, last-verified date, update cadence (frozen / annual / continuous / irregular), decay-risk flag (STABLE / ANNUAL / CONTINUOUS / URL-PRONE / REGULATORY / SHUTDOWN-RISK), cited-in file list, migration notes. Single source of truth for skill maintenance — when a source migrates, update one row instead of search-and-replacing across 39 files. Organized into 11 categories (A-K). Includes monthly/quarterly/annual maintenance protocols.
about.md	--about flag set — print self-documentation (5 methodology layers, 35 anti-hallucination techniques, comparison to Big 4 / Klue / Forrester / Gartner standards, version history, invocation examples, cost/runtime). Mutually exclusive with dossier generation — when --about is set, do NOT run any research/draft steps.
multi-agent.md	--agents= flag set OR auto-activated by --depth=deep (parallel) / --type=due-diligence|investment (max). Defines 4-level parallelism strategy (solo / validation / parallel / max) with which workstreams delegate to subagents at each level. Max-mode adds independent ACH agent (blind to main draft), Devil's Advocate, Pre-mortem, Key Assumptions Check, per-pattern risk-scan, fact-check.

v2.4 Strategic-analysis layer (futures + valuation + strategy classics):

File	Loaded when
scenarios.md	--scenarios=2x2|cone-of-plausibility|both set OR --type=due-diligence|investment AND --depth=deep (auto). Implements Royal Dutch Shell scenario-planning (2x2 axes) + Hancock & Bezold Cone of Plausibility for 3-5 year forward-looking analysis.
valuation.md	--valuation=dcf|comps|public-multiples|lbo|all set OR --type=investment AND --depth=deep (auto). Implements 4 canonical valuation methodologies: DCF, Comparable Transactions, Public-Comp Multiples, LBO Modeling. Required for --export=vc-memo.
strategy-classics.md	--framework= includes christensen|moore|rumelt|jtbd|wardley|classics|all. Implements 5 strategy classics: Christensen Disruption Theory, Moore Crossing the Chasm, Rumelt Strategy Kernel (alternative to SWOT for synthesis), Christensen/Ulwick Job-to-be-Done, Wardley Mapping. Auto-loads JTBD + Christensen for --type=investment; Rumelt Strategy Kernel for --type=due-diligence + --depth=deep.

Output formats & publishing:

File	Loaded when
output-formats.md	--export= includes exec, battle-card, vc-memo, or json — alternate condensed/repurposed views
output-publish.md	--publish=notion|confluence|gdocs|coda set — direct publish to collaborative platforms via API

The model loads each segment via the Read tool when its trigger condition is met. SKILL.md stays lean; segments are loaded on demand.

Arguments

• $1 (required, positional) — Entity name (e.g. "Stripe", "Acme Corp", "Example Co") OR a path to an existing .md dossier to convert. If the positional arg is a path ending in .md and the file exists, the skill switches to convert-only mode and skips all research/draft steps.
• --convert=<path> — explicit convert-only mode: take an existing MD dossier and produce HTML/PDF only.
• --url=<url> — primary company URL if known. Discovered via search if omitted. (Ignored in convert-only mode.)
• --type=<mode> — competitive (default) / due-diligence / partnership / investment / research (neutral self-portrait, e.g., when researching the user's own employer)
• --depth=<quick|standard|deep> — source count + agent parallelism. Default: standard.
• --audience=<audience> — c-suite (default) / technical / investor / board / operator. Determines which Playbook personas appear.
• --stage=<seed|series-a|series-b|series-c|growth|pe|public> — stage modifier; tunes section emphasis + adds stage-specific subsections (load stage-templates.md). Auto-detects from /about + funding rows if not set.
• --vertical=<healthcare|fintech|govtech|edtech|legaltech|devtools|consumer|saas|deeptech> — vertical modifier; surfaces vertical-specific compliance, integrations, regulators, review platforms (load vertical-templates.md). Auto-detects from /about keywords if not set.
• --compare=<A.md,B.md[,C.md]> — side-by-side comparison of 2+ existing dossiers; produces 15-section comparison output rather than single-entity dossier (load comparison-mode.md).
• --year-over-year — auto-detect prior dossier in same directory; generate "what changed" diff after full re-research (load comparison-mode.md).
• --benchmark[=cohort] — add §X Industry Benchmarks comparing to cohort medians (Bessemer / OpenView / KeyBanc / ICONIQ / Battery / Sapphire); cohort defaults to public-saas (load benchmarks.md). Auto-activates for --stage=series-b and later.
• --audit=<scope[,scope]> — focused deep-dive audits beyond the default 23 sections; composable. Scopes: pricing / tech-stack / customer-concentration / ai-maturity (load audits.md).
• --data-sources=<list> — explicit additional source families: sec (EDGAR), wayback (Wayback Machine), github (devtools), linkedin (hiring velocity), uspto (patents), pacer (court records). Auto-activated by entity context (load data-sources-extended.md).
• --no-risk-scan — skip the always-on §16.X Red-Flag Scan (8-pattern automated scan). NOT recommended; risk findings are highest-ROI dossier output (load risk-scan.md).
• --mcp-serve — start the self-MCP server exposing the user's dossier library to future Claude sessions (load mcp-server.md).
• --about — print the skill's self-documentation (load about.md and output its template content). Shows: 5 methodology layers (Foundational / Source-provenance / Strategic-frameworks / IC-tradecraft / Industry-CI / SaaS-CXO), 89 anti-hallucination techniques (organized into 10 categories — A-J), comparison to Big 4 / Klue / Forrester / Gartner / Helmer standards, version history (v1 → v2.0 → v2.1 → v2.2 → v2.3 → v2.4 → v2.5 → v2.6 → v2.7 → v2.8 → v2.9 → v2.10 → v2.11 → v2.12), invocation examples, cost/runtime expectations. Mutually exclusive with dossier generation — when --about is set, do NOT run any research/draft steps; print the about content and exit.
• --validate-skill-sources — maintenance mode (NEW v2.8). Run URL-validation across all skill segment files + cross-reference sources-of-record.md last-verified dates + flag URLs >12 months unverified + flag known-shutdown-risk vendors + flag URL migrations (404 / persistent 5xx). Outputs a remediation plan to terminal — does NOT modify skill files. Mutually exclusive with dossier generation — when set, do NOT run any research/draft steps; run maintenance and exit. Recommended cadence: monthly (via /schedule).
• --framework=<list> — strategic frameworks to apply. Porter-era (load frameworks.md): swot (default in §0) / pestel / porter5 / vrio / value-chain. Strategy classics (load strategy-classics.md): christensen (Disruption) / moore (Crossing the Chasm) / rumelt (Strategy Kernel) / jtbd (Job-to-be-Done) / wardley (Wardley Mapping). Aggregates: classics (loads strategy-classics.md only) / all (loads both files, all 10 frameworks). Composable. Auto-activated by --vertical= (PESTEL for govtech/healthcare/fintech/edtech/legaltech; Porter5 for consumer; VRIO for devtools/deeptech). Auto-loads JTBD + Christensen for --type=investment; Strategy Kernel for --type=due-diligence + --depth=deep.
• --scenarios=<method> — scenario planning: 2x2 (Royal Dutch Shell/GBN matrix) / cone-of-plausibility (Hancock & Bezold futures-fanning) / both. Auto-activated for --type=due-diligence|investment with --depth=deep. Load scenarios.md.
• --valuation=<method> — valuation methodologies for --type=investment: dcf (Discounted Cash Flow) / comps (Comparable Transactions) / public-multiples / lbo (LBO Modeling) / all. Auto-activated for --type=investment AND --depth=deep. Load valuation.md.
• --analytic-rigor=<level> — standard (default) / high. When high, loads analytic-techniques.md and inserts ACH (Analysis of Competing Hypotheses), SATs (Devil's Advocate, Pre-mortem, Key Assumptions Check), and ICD 203 expressed-uncertainty discipline into the dossier. Auto-activated for --type=due-diligence|investment.
• --win-loss[=<csv>] — NEW v2.12. Add §10.X Win/Loss Intelligence subsection (load win-loss.md). With =<csv> argument, integrates user's own deal data as ground-truth alongside public-source inference. Without csv, runs public-source inference only (G2/TrustRadius/Reddit/comparison-page mining). Auto-suggested for --type=competitive + --audience=c-suite|operator|investor.
• --unit-economics — NEW v2.12. Add §X SaaS Economics subsection with NRR / CAC / LTV / CAC-Payback estimates (load saas-economics.md). Multi-method estimation against Bessemer canonical tiers (100/110/120 = Good/Better/Best). Auto-activated for --audience=board|investor and for --type=investment|due-diligence when entity is private B2B SaaS without disclosed audited financials.
• --moat=<framework> — NEW v2.12. Add §17.X Moat Scoring subsection (load moat-scoring.md). helmer applies Hamilton Helmer's 7 Powers framework (the SaaS-investor-class moat lexicon — 41.5% CAGR vs 14.9% S&P 500 over 22 years). Each power scored 0-3 with public-source evidence; powers don't sum. Auto-activated for --audience=board|investor AND --depth=deep.
• --roadmap — NEW v2.12. Add §7.X Roadmap Inference subsection (load roadmap-inference.md). Five-channel public-source inference (job postings, GitHub, patents, conference talks, beta leaks). Auto-activated for --depth=deep AND --type=competitive|due-diligence|investment.
• --source-rating=<scheme> — admiralty applies the formal NATO/Five Eyes A-F × 1-6 source rating notation alongside our existing ad-hoc labels. Load source-rating.md. Auto-activated for --type=due-diligence|investment AND --validation=max.
• --agents=<level> — multi-agent parallelism: solo (1 agent, default for --depth=quick) / validation (2-3 agents, default for --depth=standard) / parallel (5-7 agents, default for --depth=deep) / max (10-12 agents, default for --type=due-diligence|investment). Higher levels = faster wall-clock + higher cost + better independent-perspective quality. max adds INDEPENDENT analytic-technique agents (ACH agent that doesn't see the main draft, Devil's Advocate, Pre-mortem, Key Assumptions Check, per-pattern risk-scan, fact-check) for true confirmation-bias resistance. Load multi-agent.md.
• --output=<path> — MD output path. Default: ./<entity-slug>-research.md (CWD root — the directory the skill was launched from). Do NOT auto-create or write into a ./research/ subfolder unless the user explicitly passes --output=./research/... or asks for a subfolder.
• --export=<format[,format]> — md (default) / html / pdf / both (canonical formats; load exports.md) OR exec (1-page summary) / battle-card (sales card) / vc-memo (investment memo) / json (structured data) (alternate condensed/repurposed views; load output-formats.md). Composable.
• --publish=<destination> — direct publish via API: notion / confluence / gdocs / coda. Requires env-var auth (load output-publish.md).
• --citations=<style> — inline (default) / footnotes / endnotes. See citations.md for format rules and conversion between styles. Default inline is best for digital reading; footnotes is best for source-heavy --depth=deep dossiers (deduplicates the same URL cited many times) and for print.
• --no-wizard — skip the interactive wizard even if no flags were provided. Useful for CLI / scripted invocations.
• --validation=<level> — validation rigor. light (1 agent, 1-source acceptable) / standard (2 agents, 2-source rule, hallucination audit) / max (3 agents, ≥2 sources for §0/§2 + ≥3 for headline claims, full audit, dynamic mermaid render). Default: standard for --depth=standard, max for --depth=deep.
• --no-confidence-score — skip writing §23 Appendix — Confidence & Methodology. Default: include.
• --no-model-warning — suppress the model + effort warning at Step 1. Default: warn if model is not Opus 4.7 OR effort is not max.
• --no-reddit / --no-competitors / --no-glossary / --no-watchlist / --no-cost-math / --no-mermaid / --no-validate-urls / --no-hallucination-audit / --no-cross-validation / --no-revalidate-urls (convert-only) — opt-out flags.
• --language=<code> — output language. Default: en.
• --dry-run — print the plan without writing.

Required tools

The skill prefers Tavily MCP tools when available, falls back to WebSearch + WebFetch:

• mcp__tavily__tavily_search / mcp__tavily__tavily_extract — primary, fall back on HTTP 432 / quota
• WebSearch / WebFetch — always-available fallback
• Bash — URL validation, file writes, mkdir, mermaid validation, pandoc/xelatex for export
• Agent — REQUIRED for --depth=deep; spawn 2–3 parallel cross-validation agents
• Read / Edit / Write — file operations (incl. loading segment files)

Convert-only mode

When $1 is a path to an existing .md file (or --convert=<path> is set), skip Steps 1–4 and 6 entirely. Run mermaid validation + URL revalidation (default ON; --no-revalidate-urls to skip) + Step 7 (Export). Output paths derive from input: /path/to/<entity>-research.{html,pdf}.

Output structure (23 sections — stable numbering)

Front matter: title, subject, research_date, researcher, validation, report_type, depth.

§0 Executive Briefing — BLUF (≤200 words) + Scorecard (15 rows; every Signal cell is a dot PLUS a one-or-two-word label — 🟢 Strong, 🟡 Unverified, 🔴 Absent, ⚪ N/A — never a bare dot, per the signal-label discipline in voice-and-style.md) + SWOT (2×2) + Strategic Position Heat Map + Strategic Response Playbook (load playbook-personas.md) + Monitoring Watchlist (10–12 signals) + framework disclaimer.

§1 Executive Summary · §2 Company Fundamentals (with conflict-flagged sources) · §3 Founders & Senior Leadership (incl. mandatory §3.4 Related Entities mermaid distinguishing founded / employed / contracted relationships) · §4 Funding & Investors · §5 Product Architecture · §6 Technical Architecture · §7 Feature Catalog · §8 Pricing · §9 Customer Base · §10 Market Positioning & Competition (incl. §10.5 [Capability] Adoption Across [Market] for first-mover claims) · §11 Community Reception (load reviews-platforms.md) · §12 Data Asset · §13 Integrations · §14 Security & Trust · §15 Content Marketing & Analyst Coverage · §16 Risks & Weaknesses (incl. mandatory §16.X Data Verifiability subsection) · §17 Strategic Analysis · §18 Full Ecosystem View · §19 Sources · §20 Quote Bank · §21 Final Assessment · §22 Glossary.

Workflow

Step 0 — Early-exit modes (highest priority)

Step 0a — --about early exit

If --about is set, load about.md and print its template content directly to the user. Do NOT run any research, draft, or export steps. The skill is in informational-only mode. Exit cleanly. This check runs before mode detection.

Step 0b — --validate-skill-sources maintenance mode (NEW v2.8)

If --validate-skill-sources is set, run skill-maintenance audit:

1. Load sources-of-record.md — the canonical registry of cited external sources.

2. Extract all URLs from skill files:

grep -rhoE 'https?://[a-zA-Z0-9.-]+(/[a-zA-Z0-9._/?=&%~+#-]*)?' ~/.claude/skills/research-entity/ \
  | sed 's/[.,;)"]*$//' \
  | sort -u > /tmp/skill-urls.txt

3. Run URL validation:

while read -r url; do
  code=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 15 \
    -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36" \
    "$url" 2>/dev/null)
  echo "$code $url"
done < /tmp/skill-urls.txt | sort -n > /tmp/skill-url-check.txt

4. Cross-reference with sources-of-record.md:

   • Parse the registry rows; extract last-verified date and decay-risk for each source
   • Compute "months since last verified" for each
   • Flag any source with >12 months unverified AND risk in [URL-PRONE, REGULATORY, ANNUAL]
   • Flag any source flagged SHUTDOWN-RISK regardless of last-verified date
   • Flag any URL returning HTTP 404 / persistent 5xx
   • Flag any HTTP 301/302 redirects (URL has migrated — registry should be updated)

5. Cross-check skill files for URLs NOT in registry — surfaces newly-added citations that haven't been registered

6. Output remediation plan (to terminal, does NOT modify skill files):

## Skill-source maintenance report — YYYY-MM-DD

### URL validation summary
- ✅ HTTP 200 (resolved): X URLs
- ⚠️ HTTP 301/302 (redirect — update registry): Y URLs
- ❌ HTTP 404 (broken): Z URLs
- ⚠️ HTTP 403/999 (bot-blocked, likely valid): W URLs

### Last-verified staleness
- Sources >12 months unverified: <list with category + remediation note>
- Sources >24 months unverified: <list — high priority>

### Shutdown-risk monitoring
- Confirmed shutdown (already flagged in registry): <list>
- Sustainability concerns: <list>

### Registry drift
- URLs in skill files NOT in sources-of-record.md: <list — need to register>
- URLs in registry NOT in any skill file: <list — may be obsolete>

### Recommended actions (ranked by priority)
1. <Highest priority — broken URLs blocking dossier generation>
2. <Migrated URLs needing registry update>
3. <Stale verifications needing manual review>
4. <Optional clean-up — registry deduplication>

7. Output the report and exit cleanly. The skill is in maintenance-only mode. Do NOT run any research/draft/export steps.

Recommended cadence: Monthly via /schedule:

/schedule "0 9 1 * *" "/research-entity --validate-skill-sources"

This runs the validation on the 1st of each month at 09:00. Adjust cadence as needed:

• Monthly for active maintenance
• Quarterly for low-touch maintenance
• Annually for archived skill

Step 1 — Plan & mode detection

1. Mode detection (first):

   • If $1 matches /\.md$/ AND file exists, OR --convert=<path> is set with existing file → convert-only mode. Announce: "Convert-only: reading {path}. Skipping research; exporting to {format}." Jump to Step 5 (mermaid + URL revalidation) → Step 7 (Export) → Step 8 (Report).
   • Otherwise → full research mode. Continue.

2. Model + effort pre-flight (REQUIRED unless --no-model-warning): This skill produces highest-fidelity output with Claude Opus 4.7 + MAX effort. Lower configurations introduce specific failure modes (see below). At Step 1, check the active model + effort and if the user is below recommended config, surface a clear warning:

   ⚠️ Model & effort check: This skill produces highest-quality output with Claude Opus 4.7 + MAX effort (/effort max).

   Currently detected: <model> with <effort> effort.

   If you're on:

   • Sonnet / Haiku / older Opus — substantially higher hallucination risk on competitive funding figures, founder-exit narratives, and temporal claims ("first mainstream X"). Cross-source corroboration discipline is harder to maintain. Mermaid syntax errors more likely.
   • Effort below max — shorter reasoning chains; multi-step validation may be skipped; subagent cross-validation may not be invoked.
   • /fast mode (Opus 4.6) — slightly faster output; reasoning depth comparable but specifically designed for shorter conversations.

   Recommendation for board / regulated / due-diligence dossiers: Opus 4.7 + /effort max. The composite confidence score will reflect the configuration in §23 Methodology.

   Continue anyway? (User can dismiss with --no-model-warning for repeat invocations.)

   The warning must be:

   • Specific about what fails at lower configs (not generic "results may vary")
   • Tier-mapped so user knows the exact failure modes per tier
   • Dismissable via flag for repeat use
   • Reflected in §23 confidence-score methodology disclosure

3. Wizard check: if user invoked the skill with only the entity name (no --type, --depth, --audience, --export, --citations, --validation, --url, etc.) AND --no-wizard is not set → run the interactive wizard below.

4. Resolve canonical URL via search if --url not provided.

5. Self-research detection: if user's email domain matches entity's domain (per CLAUDE.md), auto-suggest --type=research.

6. Announce plan + dry-run check.

Step 1b — Interactive wizard (when invoked without flags)

When the user runs /research-entity "Some Company" with no other parameters, do NOT silently default everything. Instead, run a friendly Q&A using AskUserQuestion (load via ToolSearch if needed). Present each question as a multiple-choice card with sensible defaults pre-explained.

Question 1 — Research goal (--type):

What's the goal of this research?

• 🎯 Competitive analysis — comparing vs. your business (default for B2B competitive context)
• 🔍 Due-diligence — investment, acquisition, or partnership evaluation
• 💼 Investment thesis — VC / PE / strategic-buyer evaluation
• 🤝 Partnership evaluation — channel, integration, co-sell consideration
• 📚 Neutral research — self-portrait, no directional slant (auto-selected if your email domain matches the entity's)

Question 2 — Audience (--audience):

Who's reading this?

• 👔 C-suite — leads with BLUF, Scorecard, SWOT (default for general-purpose)
• 💰 Investor — leads with funding, ARR signals, exit scenarios
• 🏛️ Board — short BLUF, single-page strategic summary, risk-heavy
• 🔧 Operator — leads with pricing, integrations, tool-consolidation math
• 🛠️ Technical — leads with architecture, stack, security posture

Question 3 — Depth (--depth):

How deep should I go?

• ⚡ Quick (~5–10 minutes, ~500 lines, ~10 sources) — for scoping or quick brief
• 📊 Standard (~20–35 minutes, ~1000 lines, ~30–50 sources) — default; full 23 sections
• 🔬 Deep (~45–75 minutes, ~1500–1800 lines, ~80+ sources, 2–3 parallel cross-validation agents) — board-ready, max accuracy

Question 4 — Export format (--export):

Output format?

• 📝 Markdown only (default) — for editing, sharing as text
• 🌐 HTML — sticky-sidebar TOC + scrollspy + print-ready CSS
• 📄 PDF — pandoc + xelatex (or browser print)
• 📦 All three (MD + HTML + PDF)

Question 5 — Citation style (--citations):

How to handle source citations?

• 🔗 Inline links (default) — every claim links directly; click to jump to source
• 📚 Footnotes — sources at the bottom, referenced by tag; cleaner body for source-heavy dossiers
• 📖 Endnotes — academic style, sources only at §19; minimal body markup

Question 6 — Validation rigor (--validation):

How thorough should the validation pipeline be?

• 🔬 Maximum — 3 parallel cross-validation agents (business-register + reviews + competitor-funding), ≥3 sources for §0 headline claims, ≥2 sources for §2 facts, full hallucination audit, dynamic mmdc mermaid render. Best for board / legal / regulated / due-diligence dossiers. +15–20 min runtime. (Default for --depth=deep.)
• 📊 Standard (default for --depth=standard) — 2 cross-validation agents, ≥2 sources for §0/§2, single-source claims labeled, full hallucination audit, mermaid static render. +5–10 min runtime.
• ⚡ Light — 1 validation agent, ≥1 source acceptable with explicit single-source labels, basic hallucination audit. For quick scoping briefs only. No additional runtime.
• ❌ Off (--no-cross-validation) — skips validation entirely. NOT recommended; downgrades the §23 confidence score significantly.

Question 7 — Skip anything? (opt-out flags):

Anything to skip? (multi-select; defaults to no opt-outs)

• ⬛ Reddit research (--no-reddit)
• ⬛ Competitor landscape (--no-competitors)
• ⬛ Glossary (--no-glossary)
• ⬛ Cost-consolidation math (--no-cost-math)
• ⬛ Confidence-score appendix (--no-confidence-score)
• ⬛ Risk/red-flag scan (--no-risk-scan) — NOT recommended; highest-ROI dossier output
• ⬛ Hallucination audit (--no-hallucination-audit) — NOT recommended
• ⬛ Cross-validation pass (--no-cross-validation) — NOT recommended

Question 8 — Stage (--stage):

What stage is the entity at? (auto-detected if you skip)

• 🌱 Seed — under $5M raised, <15 employees
• 🚀 Series A — $5–20M raised, 10–50 employees
• 📈 Series B — $20–60M raised, 50–200 employees
• 🏢 Series C+ — $60M+ raised, late-stage / pre-IPO
• 💰 Growth — bootstrap + profitable, $20M+ ARR
• 🏦 PE-owned — mature, PE-backed
• 📊 Public — has ticker symbol on a major exchange
• 🤖 Auto-detect (default; reads /about + funding rows)

Question 9 — Vertical (--vertical):

What industry vertical? (auto-detected if you skip)

• 🏥 Healthcare — HIPAA, EHR, hospital, telehealth
• 💳 Fintech — bank, lending, payment, KYC, AML
• 🏛️ GovTech — federal/state agency, FedRAMP, GSA
• 📚 EdTech — K-12, higher ed, LMS, FERPA
• ⚖️ LegalTech — law firm, e-discovery, legal AI
• 🛠️ DevTools — developer, API, SDK, CI/CD
• 🛍️ Consumer — DTC, mobile, subscription, marketplace
• ☁️ SaaS — generic B2B SaaS (default)
• 🔬 DeepTech — AI/ML model, hardware, biotech
• 🤖 Auto-detect (default; reads /about keywords)

Question 10 — Add focused audit modules? (--audit)

Want any deep-dive audits beyond the default 23 sections? (multi-select; default: none)

• ⬛ Pricing audit — vs 5 competitors, hidden costs, Wayback price evolution
• ⬛ Tech-stack audit — BuiltWith + GitHub + job-posting inference
• ⬛ Customer-concentration audit — sample analysis, vertical/geo distribution
• ⬛ AI-maturity audit — model + safety + defensibility (recommended for AI vendors)

Question 11 — Industry benchmarks? (--benchmark)

Compare to public benchmark medians? (Bessemer / OpenView / KeyBanc / ICONIQ — adds §X Industry Benchmarks)

• ✅ Yes — auto for --stage=series-b and later
• ❌ No — skip
• 🎯 Yes, specific cohort: public-saas / growth-stage / early-stage / ai-native / vertical-saas / devtools

Question 12 — Multi-agent parallelism? (--agents)

Higher = faster wall-clock + higher API cost + better independent-perspective quality. Each level adds specific subagents that operate independently from the main session.

• 🤖 Solo (1 agent, sequential) — single Claude session does everything inline. Best for: quick scoping, throwaway research, cost-constrained runs. ~$2-5 cost · 30-60min.
• 👥 Validation (2-3 agents) — spawns subagents for cross-validation (Step 3) + hallucination audit (Step 6). Each gets its own context window so the main session stays clean. Default for --depth=standard. ~$10-20 cost · 20-35min.
• 🚀 Parallel (5-7 agents) — also spawns subagents for source gathering (Step 2) + per-audit-module (Step 4) + per-framework (Step 4). Default for --depth=deep. ~$25-50 cost · 25-45min.
• 🌟 Max (10-12 agents) — adds INDEPENDENT analytic-technique agents: ACH agent that doesn't see the main draft (true confirmation-bias resistance), Devil's Advocate, Pre-mortem, Key Assumptions Check, per-pattern risk-scan (8 patterns × 1 agent), independent fact-check. Default for --type=due-diligence|investment. ~$60-120 cost · 30-60min (parallelism balances against more agent calls).

The "max" mode is the only level that produces genuinely confirmation-bias-resistant analysis (the ACH agent generates competing hypotheses BLIND to the main session, so its hypotheses can't be biased by the draft narrative). For board / IC-grade outputs this is the load-bearing differentiator.

After collecting answers: confirm the resolved config back to the user in one summary line including the model+effort pre-flight result, then proceed to Step 2.

Example confirmation: "✓ Researching Acme Corp | competitive analysis | C-suite audience | standard depth (~30 min) | inline citations | export: HTML + PDF | validation: standard (2 agents, ≥2 sources) | model: Opus 4.7 + max effort (✅ recommended). Starting source gathering now."

Or if model is below recommended: "✓ Researching Acme Corp | ... | ⚠️ model: Sonnet 4.6 + standard effort. Hallucination risk elevated for competitive-funding figures + temporal claims. §23 confidence score will reflect this. Continuing in 5s; press Ctrl-C to abort and switch to Opus + /effort max."

Skip wizard when:

• --no-wizard flag set
• ANY non-default flag was provided (model infers user knows what they want)
• Convert-only mode (different code path)
• User explicitly typed all flags
• --dry-run is set (announce defaults instead)

Step 1c — Stage + Vertical auto-detect (after wizard / before search)

If --stage= or --vertical= not set explicitly, run the auto-detection routines from stage-templates.md (stage detection) and vertical-templates.md (vertical detection) on the canonical /about + /products page. Surface the inference: "Detected --stage=series-b --vertical=fintech from page text. Use flags to override." Load the relevant template files for the rest of the run.

Step 2 — Parallel source gathering

Run searches in parallel (one message). Respect --depth:

1. Extract canonical URL + sub-pages (/about, /team, /careers, /blog, /pricing, /trust, /security, /products, /customers, /integrations, /press)
2. <entity> founder name
3. <entity> funding raised investors
4. <entity> review (skip if --no-reddit) site-scoped to reddit.com
5. <entity> vs alternatives comparison (skip if --no-competitors)
6. <entity> customer case study
7. <entity> site-scoped to g2.com, capterra.com, trustpilot.com, glassdoor.com, gartner.com (load reviews-platforms.md)
8. <entity> podcast interview
9. Risk scan (always-on; load risk-scan.md) — 8 patterns in parallel: layoffs (layoffs.fyi + thelayoff.com), exec departures (LinkedIn role changes), lawsuits (CourtListener + PACER), data breaches (haveibeenpwned + databreaches.net), regulatory actions (SEC + FTC + CFPB + GDPR enforcement tracker), Glassdoor rating delta vs 12 months ago, status-page outage history, leadership controversy. Skip only if --no-risk-scan.
10. Aggregators: sacra.com, crunchbase.com, pitchbook.com, tracxn.com, craft.co, owler.com, cbinsights.com, getlatka.com, leadiq.com, rocketreach.co, zoominfo.com
11. For non-US entities: load registers.md + search the relevant country's free public business register
12. For vertical-specific sources (load vertical-templates.md): per-vertical search additions (e.g., FedRAMP marketplace for govtech, KLAS for healthcare, GSA Schedule for govtech, IL ratings for defense)
13. For extended data sources (load data-sources-extended.md if conditions met): SEC EDGAR (US-incorporated), Wayback Machine (always — cheap), GitHub (devtools), LinkedIn hiring (always — cheap), USPTO (deeptech / regulated), PACER (always — cheap)
14. NEW v2.10 — Competitive comparison-page scan (MANDATORY for --type=competitive when user-employer-domain is known via CLAUDE.md memory). Probe <entity-domain>/comparison/, <entity-domain>/vs/, and <entity-domain>/alternatives/ directories AND specifically <entity-domain>/comparison/<user-employer-slug>-vs-<entity-slug>/ (and the inverse slug ordering) for any page that names the user's employer. Pages found in this probe are T1 self-disclosed competitive-positioning artifacts and become a required §10.X "Active competitive positioning vs. " subsection in the dossier. Per lessons.md #70 — this is the single highest-leverage source-gathering step for users at competing entities; the failure mode is missing it entirely. For --type=competitive without user-employer-domain known, probe still runs against named Tier-A peers (Step 5 §10) — every Tier-A peer's /comparison/<entity>-vs-<peer>/ URL is a high-yield T1 competitive intel source.
15. NEW v2.10 — Parent-organization scale freshness sweep (MANDATORY when entity is a portfolio company / subsidiary / division). When the entity has a known parent (acquirer, holding company, conglomerate division), search the parent's most recent milestone announcement / press release before citing any aggregator (T3) figure for parent scale. T3 aggregator data ages quickly for serial acquirers and fast-moving SaaS — a 2024 figure for a 2026 parent is structurally stale (per lessons.md #68). Confirm: parent ARR, acquisition count, employee count, country count, current AI/operating-strategy initiatives. Cross-check against parent's /about or /leadership page for current founder/leadership identity — never trust the deal-announcement signatory list as the founders list (per lessons.md #67).

For results > 30K chars, delegate extraction to Agent subagent.

Step 3 — Cross-validation pass (REQUIRED)

Two-source rule: every Scorecard / §1 / §2 datapoint needs ≥2 independent sources OR a single-source / aggregator-derived / vendor-claimed / founder-self-reported label.

Aggregator failure modes: see lessons.md. Every aggregator (Latka, RocketReach, PitchBook, Crunchbase, Tracxn, Owler, Craft.co, LeadIQ, ZoomInfo) has known failure modes that must be flagged.

Founder-claim verification: any narrative implying a founder achieved an exit / built a $XXX million company MUST be cross-checked against Wikipedia + acquirer press + investor exit announcement. Don't repeat misframed narratives.

Subagent cross-validation (REQUIRED for --depth=deep): spawn 2–3 parallel agents:

1. Business-register agent — verify legal entities in free public registers (load registers.md for the relevant region)
2. Reviews + community agent — multi-platform review counts, verbatim quotes, lawsuit/breach/layoff search (load reviews-platforms.md)
3. Competitor-validation agent — verify every named competitor's funding/founding/pricing from ≥2 sources. For --type=competitive|due-diligence|investment MUST load competitor-verification.md and run the four-class verification protocol on every Tier B/C/D peer row: (a) lead-investor identity ≥3 sources with named-partner attribution preferred, (b) HQ city per press release dateline, (c) round structure per primary financial press (Bloomberg/TC) when bundled-announced, (d) numeric-figure attribution drift — confirm cited number is in cited source.

Step 4 — Draft

Write to --output path in the 23-section structure (or comparison-mode 15-section if --compare= set; load comparison-mode.md).

Load core voice/style/playbook files:

• voice-and-style.md for voice/tone rules (single source of truth; declarative; no editorial trail) + mermaid portrait-printable rules
• citations.md for citation-style rules; apply per --citations=<style>
• playbook-personas.md for §0 Strategic Response Playbook content (12 personas, audience-mapped)

Load stage / vertical / focused-audit overrides:

• stage-templates.md (if --stage= set or auto-detected) — applies stage-specific section emphasis
• vertical-templates.md (if --vertical= set or auto-detected) — applies vertical-specific compliance / integrations / regulators / review platforms
• audits.md (if --audit= set) — adds focused subsections (pricing / tech-stack / customer-concentration / ai-maturity)
• benchmarks.md (if --benchmark set or --stage=series-b+) — adds §X Industry Benchmarks comparing to Bessemer / OpenView / KeyBanc / ICONIQ medians
• risk-scan.md — adds §16.X Red-Flag Scan from Step 2 findings (8 patterns)
• data-sources-extended.md (if --data-sources= set or auto-activated) — incorporates SEC EDGAR, Wayback, GitHub, LinkedIn hiring, USPTO, PACER findings into relevant sections

Source-backing rule (non-negotiable): every claim that can be backed by a public source MUST have a citation. Numbers, names, dates, quotes, competitor stats, certifications, customer logos — all need a clickable URL trail. The only exceptions: analyst opinion (SWOT/Heat-Map/Playbook content, bucketed under §0 framework disclaimer) and explicit synthesis ("reading these together suggests..."). If you can't find a source for a claim, drop the claim rather than publish unsourced.

Step 5 — Validate (URLs + mermaid + glossary-completeness + depersonalization)

Mermaid validation (load mermaid-validation.md): run static check (no deps) on every mermaid block. Optionally run dynamic mmdc render for higher confidence. Fail the export if any diagram violates portrait-printable rules.

Glossary-completeness scan (load voice-and-style.md Glossary discipline section + glossary-catalog.md for canonical definitions): scan the body for all-caps acronyms and known jargon terms; cross-check against §22 Glossary entries. Report any used-but-undefined terms.

Signal-label scan (REQUIRED, every dossier; load voice-and-style.md Signal-label discipline section): run the bare-dot scan. Any signal cell that is a colour dot with no word label is a hard gate — fix before ship. Also run the repetition check: a label appearing more than ~3× in a 15-row Scorecard means the labels are not differentiating, so re-read those rows and pick dimension-specific words. Reading the Signal column top-to-bottom in isolation must produce a coherent summary of the entity; if it reads as a run of identical words, the column is decorative and has failed.

BARE=$(grep -nE '\|[[:space:]]*(🟢|🟡|🔴|⚪)[[:space:]]*\|' "$OUTPUT")
[ -n "$BARE" ] && { echo "❌ bare signal dots:"; echo "$BARE"; } || echo "✓ all signal cells labelled"
grep -oE '(🟢|🟡|🔴|⚪) [A-Z][A-Za-z/-]+' "$OUTPUT" | sort | uniq -c | sort -rn | awk '$1>3 {print "⚠️  over-used:", $0}'

Depersonalization / leak scan (REQUIRED for --type=competitive|due-diligence; load voice-and-style.md Anti-leak section): run the 12-category leak scan on the dossier. The scan must pass before ship — any HIT is a hard gate, not a soft warning. Common leaks in production runs: lens-qualified labels ("Outsider verdict"), skill-tool references ("/schedule cron", "the skill that produced this"), editorial trail markers ("in this revision"), and lens comparisons ("insider lens scored X"). Substitute the author's identity placeholders (<firstname> / <lastname> / <userhandle> / <entity-domain>) before running, so personal-name patterns hit if the author accidentally name-leaks. Do not ship a competitive/DD dossier with any leak unresolved — the dossier is supposed to read as a third-party external evaluation with no traceable provenance to its author.

Two-pass workflow:

1. Pre-include from catalog (Step 4 / Draft): when writing §22, scan the catalog (glossary-catalog.md) for every entry whose term appears in the body. Add those to §22 with the canonical definition (adapted to the entity where useful).
2. Post-write scan (Step 5): run the bash scan from voice-and-style.md Glossary discipline section. Any term flagged as "used in body, not in glossary" must be added — either from the catalog or hand-written.

Add missing entries before shipping — every term in the body must have a glossary entry. Common gap categories: framework terms (BLUF, SWOT, Heat Map, Scorecard, Watchlist), funding rounds (Seed, Series A/B/C), business-register codes (FN, HRB, ICO, KvK, CVR, RUC, etc.), compliance (FedRAMP, PCI DSS, Schrems II), entity-specific products (placeholder names), and modern AI terminology (agentic, MCP Server, AI agent).

Target: 40+ glossary entries on --depth=deep dossiers. Production runs typically reach 55–75 entries; the canonical catalog has 240+ pre-defined entries spanning all common categories.

URL validation (unless --no-validate-urls):

grep -oE 'https://[][:alnum:]._/?=#&%+:~@-]+' "$OUTPUT" | sed 's/[.,;)"]*$//' | sort -u > /tmp/urls.txt
while read -r url; do
  code=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 15 \
    -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36" \
    "$url" 2>/dev/null); echo "$code $url"
done < /tmp/urls.txt | sort -n > /tmp/url_check.txt

• HTTP 200 → keep
• HTTP 404 → fix or remove
• HTTP 301/302 → update to final
• HTTP 403/999/000 → bot-blocks on valid URLs (LinkedIn, Crunchbase, BusinessWire, Cloudflare-protected); verify visually with WebFetch

Step 6 — Hallucination audit (unless --no-hallucination-audit)

Delegate to Agent:

Read <path>. For every factual claim in §0–§1, verify it is supported by §2–§22. Flag any claim that is (a) new in §0 without body support, (b) a specific number without citation, (c) a competitor stat from a single analyst source not labeled, (d) a temporal claim ("first mainstream X", "earliest", "only") not verified across the market, (e) a founder-exit narrative not cross-checked, (f) an inferred date / metric, (g) a competitor lead-investor identity not cross-validated against ≥3 sources OR not confirmed by named-partner attribution, (h) a competitor HQ city sourced from a single secondary outlet rather than a press release dateline, (i) a bundled-announcement funding figure ($Xm seed) without primary financial press breakdown of the seed-vs-Series-A structure, (j) a specific number cited to a specific article without confirming the number is actually in that article, (k) v2.6 — any T4-only-sourced claim (aggregator paraphrase without T1/T2 corroboration) per source-hierarchy.md, (l) v2.6 — any time-sensitive claim sourced to a current page without Wayback verification of the historical state, (m) v2.6 — any customer-logo cited in §9 without round-trip verification (no customer-side reciprocal evidence), (n) v2.6 — any vendor-claimed customer count contradicted by triangulated ARR-proxy math (per arr-triangulation.md), (o) v2.6 — any forward-looking claim with ICD 203 qualitative term but no Tetlock-compatible point probability, (p) v2.6 — any compliance claim (SOC 2 / ISO / HIPAA / FedRAMP) without auditor name + audit period + scope verification per press-analysis.md §3, (q) NEW v2.7 — pricing / headcount / customer / revenue / year value in one section that contradicts canonical value in another section without explicit reconciliation note (per internal-consistency.md §2), (r) NEW v2.7 — any version reference (vX.Y) in body or closing footer that doesn't match the header / front-matter version, (s) NEW v2.7 — sample-audit headline "X% verified" that bundles partial-evidence items into the rate (must report fully-verified separately from light-evidence + pending), (t) NEW v2.7 — two-decimal numeric precision on synthesized / inferred / estimated values when underlying analysis is text-pattern inference rather than measurement, (u) NEW v2.7 — a tier or label assignment that is at the more-generous end of the plausible range when no evidence supports the higher tier (e.g., press-release-republish outlet labeled as "earned" T2), (v) NEW v2.7 — methods labeled "triangulation" that share >50% of their underlying assumption stack (must relabel as "multi-method estimation" or "plausibility-range bounds"), (w) NEW v2.7 — status-quo persistence forecast (rebrand sticks / exec stays / customer logo remains) at probability materially below the base-rate prior without specific contrary evidence, (x) NEW v2.7 — single composite confidence score for a dossier with single-source / vendor-claimed / aggregator-derived headline metrics (must split into epistemic-discipline + headline-fact-confidence two-dimension framing), (y) NEW v2.9 — **N <label>** paired with parenthesized name list where the count does not match the number of names listed (per internal-consistency.md §10 — within-section count-vs-enumeration mismatch), (z) NEW v2.9 — deprecated terminology surviving a mid-revision rename (e.g., "triangulated" / "triangulating" remaining after a "triangulation" → "multi-method estimation" rename); sweep ALL inflections of the deprecated term per internal-consistency.md §11, (aa) NEW v2.9 — adjacent paragraphs sharing the same lead-in marker (**Note:**, **Important:**, etc.) within 3 lines that contain overlapping content from iterative re-edits (per internal-consistency.md §12), (bb) NEW v2.11 — founder identity inferred from press-release quote attribution rather than entity's own /about / /leadership / /team page (per internal-consistency.md §13 technique #61), (cc) NEW v2.11 — T3 aggregator citation with publication date >12 months old in fast-moving category cited as if current; freshness sweep against entity's most recent milestone announcement was not run (per internal-consistency.md §14 technique #62), (dd) NEW v2.11 — headcount-velocity claim about a portfolio company / subsidiary that doesn't acknowledge parent-network resources disclosed on the same source page (per internal-consistency.md §15 technique #63), (ee) NEW v2.11 — --type=competitive dossier without comprehensive <entity-domain>/comparison/ directory probe AND without <entity-domain>/comparison/<user-employer>-vs-<entity>/ probe when user-employer-domain is known (per internal-consistency.md §16 technique #64), (ff) NEW v2.11 — "not publicly disclosed" / "exact private" / "publicly unavailable" claim without verification ladder (legal firms / PrivSource / Pitchbook / regulatory filings checked before publishing) (per internal-consistency.md §17 technique #65), (gg) NEW v2.11 — single-feature observation extrapolated to category-level claim (e.g., "X has only basic AI") without enumerating entity's full feature surface AND parent / sibling-portfolio context (per internal-consistency.md §18 technique #66), (hh) NEW v2.11 — negation claim ("no X") without specifying surface where absence was observed + snapshot date + strings searched (per internal-consistency.md §19 technique #67), (ii) NEW v2.11 — quasi-deterministic verb usage ("categorically beyond" / "cannot trivially" / "will never" / "must / always / impossible / guaranteed") without Tetlock probability + resolution criterion (per internal-consistency.md §20 technique #68), (jj) NEW v2.11 — competitor pricing in §8 or §10 without inline link to competitor's own /pricing page or Wayback snapshot (per internal-consistency.md §21 technique #69), (kk) NEW v2.11 — Step 6 hallucination audit must include fresh-fetch sample of ≥3 cited URLs (not just citation-existence check); audit shares writer's blindspots and must explicitly probe for source-coverage gaps (per internal-consistency.md §22 technique #70), (ll) NEW v2.11 — claim repeated across 3+ sections of dossier without ≥2 independent underlying sources (amplification illusion — repetition ≠ corroboration) (per internal-consistency.md §23 technique #71), (mm) NEW v2.11 — vendor-claimed metric with suspicious precision (96.4%) or round magnitude (40,000+) without "methodology not disclosed" label (per internal-consistency.md §24 technique #72), (nn) NEW v2.12 — win-rate claim without denominator (N) and source citation (per win-loss.md technique #73), (oo) NEW v2.12 — NRR claim using non-Bessemer terminology ("strong NRR" instead of "Better tier per Bessemer 100/110/120"), or NRR/CAC/LTV/Payback as point estimates rather than multi-method bands (per saas-economics.md techniques #74, #75), (pp) NEW v2.12 — Helmer 7-Powers scores aggregated into a single composite "moat score" (per moat-scoring.md technique #76 — powers don't sum), (qq) NEW v2.12 — Switching Cost / Network Economies / Counter-Positioning / Process Power scored 2+ without specific friction mechanism / degree-N evidence / incumbent-paralysis evidence / 5+ year continuous-improvement evidence (per moat-scoring.md techniques #77, #78, #85, #86), (rr) NEW v2.12 — patent filing presented as " is shipping X" without 12-36mo lag + 40-60% abandonment-rate caveat (per roadmap-inference.md technique #79), (ss) NEW v2.12 — job-posting count → roadmap inference without 3-9mo time-horizon caveat (per roadmap-inference.md technique #80), (tt) NEW v2.12 — conference-talk topic or GitHub-commit pattern presented as future-feature commitment (per roadmap-inference.md techniques #81, #82), (uu) NEW v2.12 — single-channel roadmap inference; "Medium" confidence requires ≥2 channels, "High" ≥3 channels (per roadmap-inference.md technique #87), (vv) NEW v2.12 — counter-evidence ignored (e.g., "5 ML engineers / 0 ML features over 24mo" presented as ML signal — actually LOW signal per technique #88), (ww) NEW v2.12 — win-driver claim from <3 corroborating reviews (anecdote ≠ pattern; per win-loss.md technique #83), (xx) NEW v2.12 — review-quote paraphrased rather than verbatim with attribution (paraphrase = synthesis = loss of source-discipline; per win-loss.md technique #89), (yy) NEW v2.12 — cohort benchmark cited as "industry standard" without naming Bessemer / OpenView / KeyBanc / ICONIQ / Pavilion explicitly (per saas-economics.md technique #84). Return ✅/⚠️/❌ feedback under 500 words.

Special focus: temporal claims — when entity claims "first mainstream X to ship Y", verify by searching Y across top 5 competitors. See lessons.md for examples.

Special focus: competitor-row error classes (g, h, i, j) — these are the 4 highest-frequency post-publication corrections in production runs. Load competitor-verification.md for the full pre-publication checklist; the audit step verifies the checklist was applied.

Apply fixes. Repeat if critical items remain.

Step 7 — Export (load exports.md + output-formats.md + output-publish.md)

If --export=html|pdf|both (or in convert-only mode), follow the export pipeline in exports.md. Pre-flight checks for xelatex / mermaid-filter / Chrome; fall back to HTML-only if PDF deps missing.

If --export= includes exec, battle-card, vc-memo, or json — load output-formats.md and produce the alternate condensed/repurposed views from the canonical MD.

If --publish=notion|confluence|gdocs|coda is set — load output-publish.md and push to the platform via API. Surface the destination URL.

If --mcp-serve is set — load mcp-server.md and start the self-MCP server exposing the user's dossier library.

Step 8 — Report + Confidence Scoring + Freshness

Load confidence-scoring.md to write §23 Appendix — Confidence & Methodology (unless --no-confidence-score).

Load stale-detection.md to add §23.X Freshness Decay (always when prior dossier exists; in convert-only mode this is the primary §23 output). Computes per-source decay using TTL-by-source-type, decays composite confidence, and recommends soft / hard / none refresh. Optionally suggests /schedule cron for auto-refresh.

The §23 section produces a 6-dimension confidence score with date-stamp, methodology version, "what this does NOT mean" disclaimer, comparison-band table, and improvement table. The composite score reflects the active model + effort + validation level:

Configuration	Typical composite (well-executed dossier)
Opus 4.7 + max effort + --validation=max + --depth=deep	85–92
Opus 4.7 + max effort + --validation=standard + --depth=standard	78–88
Sonnet 4.6 + standard effort + --validation=standard	70–82
Lower model OR lower effort OR --validation=light	55–75
--no-cross-validation + --no-hallucination-audit	40–60

Print to user:

• Output paths (MD, HTML, PDF)
• Line count, sections, mermaid count, table count
• URL validation summary (X × 200, Y × 403 bot-protected, 0 × 404)
• Mermaid validation summary
• Cross-validation summary (X facts dual-sourced, Y single-source-flagged)
• Hallucination audit summary (audit pass rate %)
• Composite confidence score from §23 (e.g., "Confidence: 87/100 as of 2026-04-27")
• Active model + effort (so user understands the baseline)
• Any residual warnings

Quality checklist (before ship)

Source-backing (apply regardless of --citations style):

• Every numeric fact (dates, dollar amounts, counts, %) has a citation
• Every proper noun used as a fact (company, person, product) has a citation
• Every quoted statement has attribution + citation
• Every competitor / customer / investor name links to a canonical URL
• Every certification / compliance / regulatory claim has a citation
• If --citations=footnotes|endnotes: same source = same tag (deduplication working); all [^tag] references have matching [^tag]: ... definitions; no orphan footnotes

Voice & format:

• §0 BLUF reads as a single declarative paragraph (no "we corrected this")
• §0 Scorecard: every row has source + signal column
• Every signal cell is <dot> <Label>, never a bare dot — §0 Scorecard, Heat Map, §16 Red-Flag Scan, negative-space scan, benchmarks, freshness decay. Labels are dimension-specific, 1–2 words, ≤14 chars, and consistent with the Assessment cell; ⚪ N/A used where a dimension genuinely does not apply (per voice-and-style.md signal-label discipline). Reading the Signal column alone must yield a coherent summary
• All 23 sections (§0–§22) present and numbered
• Every datapoint in §0–§2: dual-sourced OR labeled single-source / vendor-claimed / founder-self-reported / aggregator-derived
• §3.4 Related Entities mermaid distinguishes founded / employed / contracted
• All mermaid diagrams pass mermaid-validation.md static check (and optional dynamic check)
• §11 includes ≥10 review platforms; Reddit/HN absence flagged; verbatim negative + positive quotes with dates; lawsuit/breach/layoff search result
• §16 includes a Data Verifiability subsection
• No "first mainstream X" claim without market-wide verification
• Founder exit narratives cross-checked against Wikipedia + acquirer press
• No promotional language in analytical voice
• No editorial trail markers in final document

Validation:

• URL validation: 0 × 404
• Hallucination audit run; flagged items addressed
• Cross-validation pass run at the level set by --validation (subagents spawned, findings applied)
• Glossary-completeness scan run; every acronym + jargon term used in body has a §22 entry (no orphaned acronyms; per voice-and-style.md Glossary discipline section). Catalog (glossary-catalog.md) consulted for canonical definitions. Target: ≥40 entries on --depth=deep dossiers.
• Depersonalization / leak scan run for --type=competitive\|due-diligence; ALL 12 categories clean (per voice-and-style.md Anti-leak section). Common leaks: lens-qualified labels (Outsider/Insider), skill-tool refs (/research-entity, /schedule), editorial trail (in this revision), lens comparisons (insider score). Hard gate before ship.
• Competitive dossier voice rules applied for --type=competitive\|due-diligence: neutral verdict labels (Verdict / Observation / Conclusion — NOT Outsider Verdict / Outsider Observation), no lens comparisons, no skill self-references, no editorial trail
• External Verification Penalty (-5) applied to §23 composite for --type=competitive\|due-diligence (per confidence-scoring.md); composite caps in 70–82 band rather than 80–92
• If --export=html|pdf|both: mermaid validation passed, file generated, file opens cleanly
• §23 Confidence & Methodology written (unless --no-confidence-score); per-dimension breakdown + disclaimer + comparison band present
• Model + effort warning shown at Step 1 if config below recommended (or --no-model-warning was set)

Usage examples

Full research mode (with wizard auto-triggered for the first one):

/research-entity "Stripe"                                                     # → wizard asks for type/depth/audience/export/citations/stage/vertical/audits/benchmarks
/research-entity "Acme Corp" --type=due-diligence --audience=investor --depth=deep --export=both --citations=footnotes
/research-entity "Example Co" --type=competitive --audience=operator --depth=deep
/research-entity "<our-own-company>" --type=research --depth=deep
/research-entity "Acme Corp" --no-wizard                                      # uses all defaults silently

Stage + vertical templates:

/research-entity "Healthtech Co" --vertical=healthcare --stage=series-b
/research-entity "DeepTech Inc" --vertical=deeptech --data-sources=uspto,sec --depth=deep
/research-entity "DevTool X" --vertical=devtools --data-sources=github,linkedin --audit=tech-stack
/research-entity "Public SaaS Y" --stage=public --benchmark --data-sources=sec

Comparison / diff mode:

/research-entity --compare=./<entity-A>-research.md,./<entity-B>-research.md
/research-entity "Acme Corp" --year-over-year                                 # auto-finds prior dossier, generates delta

Focused audits:

/research-entity "Acme Corp" --audit=pricing                                  # adds §8.X Pricing Audit subsection
/research-entity "Acme Corp" --audit=ai-maturity                              # adds §7.X AI Maturity Audit
/research-entity "Acme Corp" --audit=pricing,tech-stack,customer-concentration,ai-maturity --depth=deep

Industry benchmarks:

/research-entity "Stripe" --benchmark                                         # auto-cohort by stage
/research-entity "Acme Corp" --benchmark=ai-native --stage=series-b

Alternate output formats:

/research-entity "Acme Corp" --export=md,html,exec                            # full + HTML + 1-page summary
/research-entity "Acme Corp" --export=battle-card                             # sales battle card
/research-entity "Acme Corp" --export=vc-memo --depth=deep --validation=max   # VC investment memo
/research-entity "Acme Corp" --export=json                                    # structured data dump

Direct publish to collaboration platforms:

/research-entity "Acme Corp" --export=md --publish=notion                     # requires NOTION_TOKEN env var
/research-entity "Acme Corp" --export=md,html --publish=confluence            # requires CONFLUENCE_TOKEN + URL + SPACE
/research-entity "Acme Corp" --publish=gdocs                                  # requires GOOGLE_SERVICE_ACCOUNT_JSON

Skill self-MCP server (expose dossier library to future Claude sessions):

/research-entity --mcp-serve                                                  # starts local MCP server

Convert-only mode (existing MD → HTML / PDF):

/research-entity ./<entity>-research.md --export=html
/research-entity ./<entity>-research.md --export=pdf
/research-entity ./<entity>-research.md --export=both
/research-entity --convert=./path/to/dossier.md --export=html
/research-entity ./<entity>-research.md --export=html --no-revalidate-urls

Anti-patterns — see lessons.md for the canonical list

Most-cited:

• ❌ Treat aggregator data as fact without cross-validation
• ❌ Repeat misframed founder-exit narratives
• ❌ Claim "first mainstream X" without market-wide verification
• ❌ Use side-by-side mermaid subgraphs (always portrait, vertical chain)
• ❌ Use **bold** inside mermaid nodes (use <b>...</b>)
• ❌ Use paid business registers when free covers the case
• ❌ Leave editorial trail in final document
• ❌ Skip mermaid validation before export

Notes

• This skill has been refined across multiple real-world vendor-research dossiers.
• Expected runtime on --depth=standard: 20–35 minutes.
• Expected runtime on --depth=deep: 45–75 minutes (with 2–3 parallel cross-validation subagents).
• Convert-only mode: <2 minutes (mermaid + URL re-check + export).
• Expected output size on --depth=deep: 1500–1800 lines, 150+ cited URLs, 9–10 mermaid diagrams.
• HTML export renders perfectly in any modern browser and prints to PDF via the browser's native print dialog with Save as PDF — use this when xelatex/mermaid-filter aren't installed.
• For self-research case (user's email matches entity domain), default to --type=research and save a project-memory note about the affiliation.