@diottodev/runic 1.0.0 → 1.1.0

package/research-ops/skills/research-finance/scripts/config_loader.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""config_loader.py - Customization loader for the research-finance skill.
+
+Stdlib-only. Importable from the skill's other scripts. Precedence (highest wins):
+  1. Project config:  <cwd>/.research-ops/research-finance.json
+  2. Global config:   ~/.config/research-ops/research-finance.json
+  3. Built-in DEFAULTS
+
+Onboarding answers (written by onboard.py) live in these files; every tool in this
+skill reads them so the user's customization applies automatically.
+Set RESEARCH_OPS_NO_CONFIG=1 to ignore saved config.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+SKILL = "research-finance"
+
+GLOBAL_CONFIG_DIR = Path.home() / ".config" / "research-ops"
+GLOBAL_CONFIG_PATH = GLOBAL_CONFIG_DIR / f"{SKILL}.json"
+PROJECT_CONFIG_DIRNAME = ".research-ops"
+
+DEFAULTS: dict[str, Any] = {
+    "version": 1,
+    "skill": SKILL,
+    "default_profile": "biotech",
+    "default_fa_rate": None,            # None => use the profile's default F&A rate
+    "runway_threshold_months": 6,
+    "accounting_standard": "ifrs",
+    "finance_owner": None,
+    "setup_completed_at": None,
+}
+
+
+def project_config_path(cwd: Path | None = None) -> Path:
+    cwd = cwd or Path.cwd()
+    return cwd / PROJECT_CONFIG_DIRNAME / f"{SKILL}.json"
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else None
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for k, v in override.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def load_config(cwd: Path | None = None) -> dict[str, Any]:
+    config = dict(DEFAULTS)
+    if os.environ.get("RESEARCH_OPS_NO_CONFIG") == "1":
+        return config
+    global_cfg = _read_json(GLOBAL_CONFIG_PATH)
+    if global_cfg:
+        config = _deep_merge(config, global_cfg)
+    project_cfg = _read_json(project_config_path(cwd))
+    if project_cfg:
+        config = _deep_merge(config, project_cfg)
+    return config
+
+
+def setup_completed() -> bool:
+    cfg = _read_json(GLOBAL_CONFIG_PATH) or _read_json(project_config_path())
+    return bool(cfg and cfg.get("setup_completed_at"))
+
+
+def write_config(config: dict[str, Any], scope: str = "global", cwd: Path | None = None) -> Path:
+    path = project_config_path(cwd) if scope == "project" else GLOBAL_CONFIG_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, sort_keys=True)
+    return path
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=f"Inspect {SKILL} customization config.")
+    p.add_argument("--show", action="store_true", help="Print the effective config")
+    p.add_argument("--status", action="store_true", help="Print setup status + paths")
+    p.add_argument("--sample", action="store_true", help="Print the built-in defaults")
+    args = p.parse_args(argv)
+
+    if args.sample:
+        print(json.dumps(DEFAULTS, indent=2, sort_keys=True))
+    elif args.status:
+        print(json.dumps({
+            "skill": SKILL,
+            "global_config_path": str(GLOBAL_CONFIG_PATH),
+            "global_config_exists": GLOBAL_CONFIG_PATH.exists(),
+            "project_config_path": str(project_config_path()),
+            "project_config_exists": project_config_path().exists(),
+            "setup_completed": setup_completed(),
+        }, indent=2))
+    else:
+        print(json.dumps(load_config(), indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/research-ops/skills/research-finance/scripts/onboard.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""onboard.py - Onboarding questionnaire for the research-finance skill.
+
+Stdlib-only. Asks the user a short set of questions BEFORE they build an R&D program
+budget, then writes the answers to a customization config read by every tool in this
+skill via config_loader.py. The answers become defaults for profile, F&A rate, runway
+threshold, accounting standard, and the named finance owner printed on routing outputs.
+
+Modes: --show | --defaults | --set key=value (repeatable) | --reset | --scope {global,project}
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import config_loader as cfg  # noqa: E402
+
+NUMERIC_KEYS = {"default_fa_rate", "runway_threshold_months"}
+
+QUESTIONS = [
+    ("default_profile",
+     "1. What R&D area is this program?",
+     ["pharma-rd", "biotech", "medtech", "deep-tech", "software-rd", "university-lab"], str),
+    ("default_fa_rate",
+     "2. F&A / indirect rate as a fraction (e.g. 0.55), or blank to use the profile default?",
+     None, float),
+    ("runway_threshold_months",
+     "3. Runway alert threshold in months (warn below this)?",
+     None, float),
+    ("accounting_standard",
+     "4. Which accounting standard governs capitalize-vs-expense?",
+     ["ifrs", "usgaap"], str),
+    ("finance_owner",
+     "5. Named finance/controller owner who signs accounting treatment?",
+     None, str),
+]
+
+
+def _print_questions() -> None:
+    print(f"Onboarding questions — {cfg.SKILL}:\n")
+    for _k, prompt, choices, _c in QUESTIONS:
+        line = f"  {prompt}"
+        if choices:
+            line += f"   [{' / '.join(choices)}]"
+        print(line)
+
+
+def run_interactive(config: dict) -> dict:
+    print(f"Onboarding — {cfg.SKILL}. Press Enter to keep the current/default value.\n")
+    for key, prompt, choices, caster in QUESTIONS:
+        suffix = f" [{'/'.join(choices)}]" if choices else ""
+        cur = f" (current: {config.get(key)})" if config.get(key) is not None else ""
+        raw = input(f"{prompt}{suffix}{cur}: ").strip()
+        if not raw:
+            continue
+        try:
+            config[key] = caster(raw)
+        except ValueError:
+            print(f"   ! invalid value for {key}, keeping current")
+    return config
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=f"Onboarding for the {cfg.SKILL} skill.")
+    p.add_argument("--show", action="store_true")
+    p.add_argument("--defaults", action="store_true", help="write built-in defaults, no prompt")
+    p.add_argument("--set", action="append", default=[], metavar="key=value")
+    p.add_argument("--reset", action="store_true")
+    p.add_argument("--scope", choices=["global", "project"], default="global")
+    args = p.parse_args(argv)
+
+    if args.show:
+        _print_questions()
+        print("\nCurrent effective config:")
+        print(json.dumps(cfg.load_config(), indent=2, sort_keys=True))
+        return 0
+
+    if args.reset:
+        path = cfg.project_config_path() if args.scope == "project" else cfg.GLOBAL_CONFIG_PATH
+        if path.exists():
+            path.unlink(); print(f"removed {path}")
+        else:
+            print(f"no config at {path}")
+        return 0
+
+    config = cfg.load_config()
+
+    if args.set:
+        for item in args.set:
+            if "=" not in item:
+                print(f"error: --set expects key=value, got '{item}'", file=sys.stderr)
+                return 2
+            k, v = item.split("=", 1)
+            if k in NUMERIC_KEYS:
+                try:
+                    v = float(v)
+                except ValueError:
+                    pass
+            config[k] = v
+    elif not args.defaults:
+        if sys.stdin.isatty():
+            config = run_interactive(config)
+        else:
+            print("non-interactive shell: use --defaults or --set key=value. Showing questions:\n")
+            _print_questions()
+            return 0
+
+    config["setup_completed_at"] = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    path = cfg.write_config(config, scope=args.scope)
+    print(f"saved {cfg.SKILL} customization -> {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/research-ops/skills/research-finance/scripts/program_budget_planner.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""program_budget_planner.py - Build a multi-period R&D program budget with F&A split.
+
+Stdlib-only. Deterministic. NO LLM calls. Every output surfaces an explicit assumptions
+block: budget math without disclosed assumptions is theatre.
+
+Takes work-package line items, applies the F&A (indirect) rate to the F&A-eligible base
+(MTDC-style: excludes capital equipment and the portion of subawards over $25k), computes
+fully-loaded cost, and rolls up per period.
+
+Usage:
+    python3 program_budget_planner.py --sample
+    python3 program_budget_planner.py --input program.json --fa-rate 0.55 --periods 4
+    python3 program_budget_planner.py --input program.json --profile biotech --output json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+try:
+    import config_loader as _cfg
+except ImportError:  # pragma: no cover
+    _cfg = None
+
+# Profile default F&A (indirect) rate and escalation assumption when not supplied in input.
+PROFILES = {
+    "pharma-rd": {"default_fa_rate": 0.50, "annual_escalation": 0.03},
+    "biotech": {"default_fa_rate": 0.55, "annual_escalation": 0.04},
+    "medtech": {"default_fa_rate": 0.45, "annual_escalation": 0.03},
+    "deep-tech": {"default_fa_rate": 0.40, "annual_escalation": 0.03},
+    "software-rd": {"default_fa_rate": 0.30, "annual_escalation": 0.04},
+    "university-lab": {"default_fa_rate": 0.585, "annual_escalation": 0.025},
+}
+
+# Categories excluded from the F&A (MTDC) base.
+FA_EXEMPT_CATEGORIES = {"capital_equipment", "subaward_over_25k", "tuition", "patient_care"}
+
+SAMPLE = {
+    "program": "Next-Gen Assay Platform",
+    "periods": 4,
+    "work_packages": [
+        {"name": "Personnel (FTEs)", "category": "personnel", "amounts": [320000, 330000, 340000, 350000]},
+        {"name": "Consumables", "category": "supplies", "amounts": [60000, 65000, 70000, 70000]},
+        {"name": "Sequencer", "category": "capital_equipment", "amounts": [180000, 0, 0, 0]},
+        {"name": "CRO subaward", "category": "subaward_over_25k", "amounts": [100000, 100000, 0, 0]},
+        {"name": "Travel", "category": "travel", "amounts": [12000, 12000, 12000, 12000]},
+    ],
+}
+
+
+def _period_sum(amounts: list, n: int, idx: int) -> float:
+    return float(amounts[idx]) if idx < len(amounts) else 0.0
+
+
+def plan_budget(data: dict, fa_rate: float, periods: int) -> dict:
+    wps = data.get("work_packages", [])
+    direct_by_period = [0.0] * periods
+    fa_base_by_period = [0.0] * periods
+    line_items = []
+
+    for wp in wps:
+        cat = wp.get("category", "other")
+        amounts = wp.get("amounts", [])
+        fa_eligible = cat not in FA_EXEMPT_CATEGORIES
+        wp_total = 0.0
+        for i in range(periods):
+            amt = _period_sum(amounts, periods, i)
+            direct_by_period[i] += amt
+            if fa_eligible:
+                fa_base_by_period[i] += amt
+            wp_total += amt
+        line_items.append({
+            "name": wp.get("name", "UNNAMED"),
+            "category": cat,
+            "fa_eligible": fa_eligible,
+            "total_direct": round(wp_total, 2),
+        })
+
+    fa_by_period = [round(b * fa_rate, 2) for b in fa_base_by_period]
+    loaded_by_period = [round(direct_by_period[i] + fa_by_period[i], 2) for i in range(periods)]
+
+    return {
+        "program": data.get("program", "UNSPECIFIED"),
+        "periods": periods,
+        "fa_rate_applied": fa_rate,
+        "line_items": line_items,
+        "direct_by_period": [round(x, 2) for x in direct_by_period],
+        "fa_base_by_period": [round(x, 2) for x in fa_base_by_period],
+        "fa_by_period": fa_by_period,
+        "fully_loaded_by_period": loaded_by_period,
+        "total_direct": round(sum(direct_by_period), 2),
+        "total_fa": round(sum(fa_by_period), 2),
+        "total_fully_loaded": round(sum(loaded_by_period), 2),
+        "assumptions": [
+            f"F&A (indirect) rate applied: {fa_rate:.1%}. Confirm this is your negotiated NICRA, not an assumption.",
+            f"F&A base excludes: {', '.join(sorted(FA_EXEMPT_CATEGORIES))} (MTDC-style base).",
+            "Amounts are taken as-entered per period; no escalation applied unless baked into inputs.",
+            "This is a planning estimate; a finance owner/controller validates the rate basis and booking.",
+        ],
+    }
+
+
+def _render_human(r: dict) -> str:
+    lines = [f"R&D Program Budget: {r['program']}  ({r['periods']} periods)",
+             f"F&A rate applied: {r['fa_rate_applied']:.1%}", ""]
+    lines.append("Line items:")
+    for li in r["line_items"]:
+        tag = "F&A-eligible" if li["fa_eligible"] else "F&A-EXEMPT"
+        lines.append(f"  {li['name']:24s} {li['category']:20s} {tag:12s} ${li['total_direct']:,.0f}")
+    lines.append("")
+    hdr = "  " + "".join(f"P{i+1:>14}" for i in range(r["periods"]))
+    lines.append("Per-period rollup:" )
+    lines.append(hdr)
+    lines.append("  direct      " + "".join(f"{v:>15,.0f}" for v in r["direct_by_period"]))
+    lines.append("  F&A         " + "".join(f"{v:>15,.0f}" for v in r["fa_by_period"]))
+    lines.append("  loaded      " + "".join(f"{v:>15,.0f}" for v in r["fully_loaded_by_period"]))
+    lines.append("")
+    lines.append(f"Total direct:        ${r['total_direct']:,.0f}")
+    lines.append(f"Total F&A:           ${r['total_fa']:,.0f}")
+    lines.append(f"Total fully-loaded:  ${r['total_fully_loaded']:,.0f}")
+    lines.append("")
+    lines.append("Assumptions (state these alongside the number):")
+    for a in r["assumptions"]:
+        lines.append(f"  - {a}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Build a multi-period R&D program budget with F&A split.")
+    p.add_argument("--input", help="Path to JSON program with work_packages[]")
+    p.add_argument("--profile", default=None, choices=list(PROFILES),
+                   help="overrides onboarding default_profile")
+    p.add_argument("--fa-rate", type=float, default=None, help="Override F&A rate (fraction, e.g. 0.55)")
+    p.add_argument("--periods", type=int, default=None, help="Number of periods")
+    p.add_argument("--output", choices=["human", "json"], default="human")
+    p.add_argument("--sample", action="store_true", help="use the embedded sample")
+    args = p.parse_args(argv)
+
+    conf = _cfg.load_config() if _cfg else {}
+    profile = args.profile or conf.get("default_profile", "biotech")
+    data = SAMPLE if (args.sample or not args.input) else json.load(open(args.input))
+    periods = args.periods or int(data.get("periods", 4))
+    # F&A precedence: CLI flag > onboarding default_fa_rate (if set) > profile default
+    if args.fa_rate is not None:
+        fa_rate = args.fa_rate
+    elif conf.get("default_fa_rate") is not None:
+        fa_rate = float(conf["default_fa_rate"])
+    else:
+        fa_rate = PROFILES[profile]["default_fa_rate"]
+
+    result = plan_budget(data, fa_rate, periods)
+    if args.output == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        print(_render_human(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/research-ops/skills/research-ops-skills/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: research-ops-skills
+description: Use when planning, funding, scoping, or synthesizing enterprise research across workstreams — clinical study design, R&D program finance, market sizing/surveys, or product/user research. Triggers on "design this clinical study", "what sample size", "R&D budget", "burn rate", "capitalize or expense", "TAM SAM SOM", "market sizing", "survey design", "segment the market", "plan user interviews", "usability test", "synthesize research insights". Forks context to route to one of four Research-Operations sub-skills (clinical-research, research-finance, market-research, product-research) and returns a digest. Distinct from ra-qm-team (regulatory submission), finance (corporate close/valuation), research/grants (funding discovery), product-team (persona/journey/live experiments), and marketing-skill (campaign analytics).
+context: fork
+version: 2.9.0
+author: claude-code-skills
+license: MIT
+tags: [research-ops, clinical-research, research-finance, market-research, product-research, rd, orchestrator]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# Research Operations — Domain Orchestrator
+
+The Research Operations surface is **how the enterprise plans, funds, scopes, and synthesizes research** across four workstreams: clinical R&D, R&D finance, market research, and product research. This orchestrator forks its context, routes your inquiry to one of four sub-skills, then returns a digest. Heavy intake (protocol drafts, program ledgers, survey exports, interview transcripts) stays in the forked context.
+
+This is the enterprise counterpart to the academic `research/` domain. If your question is about **finding** literature, grants, or patents, use `research/`. If it is about **planning, funding, scoping, or synthesizing** research as an operational discipline, you are in the right place.
+
+## When to invoke
+
+| Symptom | Sub-skill |
+|---|---|
+| "We're designing a Phase 2 trial — what's the endpoint and sample size?" | `clinical-research` |
+| "What's our R&D program burn, and is this cost CapEx or OpEx?" | `research-finance` |
+| "What's the TAM for this product, and how do we survey the segment?" | `market-research` |
+| "How many users do we interview, and how do we synthesize the findings?" | `product-research` |
+
+## Routing logic (deterministic)
+
+Same two-signal threshold pattern as `commercial-skills`. Single-signal → clarifying question. Mixed signals → highest-confidence first, chain second in a follow-up turn. Never silently chain.
+
+### Signal table
+
+| Signal class | Keywords | Sub-skill |
+|---|---|---|
+| **CLINICAL** | clinical trial, study design, protocol, endpoint, sample size, power, phase 1/2/3, biostatistics, eligibility, feasibility, estimand | `clinical-research` |
+| **RD_FINANCE** | R&D budget, program budget, burn, runway, F&A, indirect rate, overhead, capitalize vs expense, R&D capex, portfolio ROI, rNPV | `research-finance` |
+| **MARKET** | TAM, SAM, SOM, market sizing, survey design, sampling, margin of error, segmentation, competitive intelligence, market research | `market-research` |
+| **PRODUCT** | user interview, JTBD, usability test, concept test, prototype test, discovery research, research repository, insight synthesis, saturation | `product-research` |
+
+## Workflow (Matt Pocock grill discipline)
+
+Derived from Matt Pocock's `grill-with-docs` pattern: **explore-then-ask, one question per turn with a recommended answer, walk the decision tree depth-first, track dependencies, anchor every challenge in the research canon** (`references/` of each sub-skill).
+
+### Step 1 — Explore before asking
+
+Check the user's working directory first:
+- Is there a protocol draft, program ledger, TAM model, or interview guide already in the workspace?
+- Does the inquiry already disambiguate the lane (e.g., "what sample size for a two-arm trial" — that's `clinical-research`, no question needed)?
+- Is there an artifact filename that resolves the lane (`protocol.json` → clinical; `program-budget.json` → finance; `tam-model.json` → market; `interview-guide.md` → product)?
+
+If the workspace resolves the lane, **route silently**.
+
+### Step 2 — If still ambiguous, ONE forcing question with a recommended answer
+
+Matt's rule: never bundle. Always recommend.
+
+Pattern:
+```
+Q1/1: [precise question naming the two candidate lanes]
+Recommended: [Lane X, because <signal-table rationale>]
+
+(Confirm, or override?)
+```
+
+### Step 3 — Decision-tree walk for multi-lane inquiries
+
+If the inquiry legitimately crosses two lanes (e.g., "design this trial AND budget it" = CLINICAL + RD_FINANCE), walk depth-first:
+
+1. Highest-confidence lane first → run sub-skill in forked context → digest
+2. Ask: "Now run [second lane]? Recommended: yes, because [dependency]."
+3. Confirm before chaining.
+
+Never silently chain.
+
+### Step 4 — Invoke sub-skill in forked context
+
+Forward original prompt + structured inputs (protocol JSON, program ledger CSV, market model, observation export).
+
+### Step 5 — Return digest with cited canon challenge
+
+≤ 200 words: analyzed, top 3 findings (anchored to a canon citation), top 3 next actions (named human owner where applicable), artifact path, and **one grill challenge** for the user. Examples:
+
+- "Your power calc assumes a 0.5 effect size with no published anchor. ICH E9 requires a justified, clinically meaningful difference. Where did 0.5 come from?"
+- "Your TAM is a single top-down number (1% of a $40B market). Bessemer market-sizing discipline requires a bottoms-up cross-check. What's units × price × adoption?"
+
+## Forcing-question library (grill-with-docs pattern)
+
+Grill the user on lane-defining decisions before invoking the sub-skill. One per turn, recommended answer, canon citation:
+
+- **CLINICAL lane**: "Is your primary endpoint a clinical outcome or a surrogate — and if surrogate, is it validated for this indication? Recommended: clinical outcome unless the surrogate is on FDA's validated table. Canon: FDA Surrogate Endpoint Table; BEST glossary."
+- **RD_FINANCE lane**: "Is this spend in the research phase or the development phase, and can you evidence technical feasibility? Recommended: research = expense; development = capitalize-candidate only with feasibility evidence, routed to a named finance owner. Canon: IAS 38; ASC 730."
+- **MARKET lane**: "Is your TAM top-down or bottoms-up — and have you computed it both ways to triangulate? Recommended: both; reconcile the delta. Canon: Bessemer / a16z market-sizing; Fermi estimation."
+- **PRODUCT lane**: "Is this study generative (discover problems) or evaluative (test a solution)? Recommended: name it first; the method follows. Canon: Rohrer's landscape of UX research methods (NN/g)."
+
+Never run a sub-skill until the lane-defining decision is locked.
+
+## Onboarding-first (per sub-skill)
+
+Before invoking a sub-skill for the first time in a workspace, point the user at that skill's onboarding questionnaire so the tools run pre-configured to their context:
+
+```bash
+python3 skills/<sub-skill>/scripts/onboard.py          # interactive Q&A
+python3 skills/<sub-skill>/scripts/onboard.py --show    # questions + current config
+```
+
+Each sub-skill has its **own** question set (clinical: area/alpha/power/dropout/owners · finance: area/F&A/runway/standard/owner · market: profile/confidence/MoE/method · product: profile/insight-threshold/method/stakes). Answers persist to `~/.config/research-ops/<sub-skill>.json` (or `./.research-ops/<sub-skill>.json` with `--scope project`) and are consumed automatically by every tool in that skill. Customization is mandatory discipline here, not decoration — surface the onboarding step when a user starts a fresh research workstream.
+
+## Autoresearch handoff (isolated, opt-in)
+
+Each sub-skill ships its own `scripts/ar_evaluator.py` — an **isolated** bridge to `engineering/autoresearch-agent`. Invoke autoresearch **only when the user explicitly asks** to "optimize", "improve", or "run a loop". The handoff is per-skill (no shared coupling): the loop edits the skill's input file and the evaluator scores it (clinical → `feasibility_composite` higher; finance → `runway_months` higher; market → `tam_divergence` lower; product → `validated_insights` higher). Never auto-start a loop; never let the loop edit the evaluator.
+
+## Assumptions
+
+1. User has research authority OR is preparing analysis for someone who does.
+2. User wants **deterministic decision support**, not the final answer — a clinician approves the protocol, a controller books the entry, the human picks the market number.
+3. Inputs may be partial — every sub-skill ships a templated sample so the user can see the shape before filling in their own.
+
+## Non-goals
+
+- Not an EDC, clinical-trial-management system, accounting system, survey platform, or research repository.
+- Does not give clinical, accounting, or legal advice as fact. Every output is **a recommendation + named human owner**.
+- Does not store research history across sessions.
+
+## Distinct from
+
+- **`research/` (academic)** — that domain **finds** literature, grants, and patents. This domain **plans, funds, scopes, and synthesizes** research.
+- **`ra-qm-team`** — that's **regulatory/QM submission** (ISO 13485/14971, MDR, FDA 510(k)/PMA/QSR). clinical-research designs the **study**; it routes submission out to ra-qm-team.
+- **`finance/financial-analysis`** — that's **corporate close + valuation**. research-finance manages **R&D program/portfolio spend**.
+- **`research/grants`** — that's **funding discovery**. research-finance manages **money already won**.
+- **`product-team`** — that's **persona/journey artifacts, discovery sprints, and live A/B experiments**. product-research is the **method + repository discipline**.
+- **`marketing-skill`** — that's **campaign analytics and demand-gen**. market-research is **upstream methodology**.
+
+## Output artifacts
+
+| Sub-skill | Artifact |
+|---|---|
+| clinical-research | `protocol_synopsis.md` + `sample_size.json` |
+| research-finance | `rd_program_budget.md` + `capex_opex_routing.json` |
+| market-research | `market_sizing.md` + `sample_plan.json` |
+| product-research | `research_plan.md` + `insight_synthesis.json` |
+
+## Anti-patterns (do not)
+
+- ❌ Present a clinical power/endpoint output as fact — it is an **estimate** with a named clinical owner
+- ❌ Auto-decide capitalize-vs-expense — route to a **named finance owner**
+- ❌ Report a market size as a single unsourced number — show **method + both-ways triangulation + assumptions**
+- ❌ Assert a product insight from a single participant — flag it as an **anecdote**
+- ❌ Run all 4 sub-skills "to be thorough" — pick one, digest, chain if needed
+
+## References
+
+- Clinical canon: ICH E8(R1)/E9/E9(R1), CONSORT, SPIRIT, FDA Multiple Endpoints
+- R&D finance canon: IAS 38, ASC 730, 2 CFR 200, Cooper stage-gate
+- Market canon: Cochran, Dillman, Kotler, Bessemer market-sizing
+- Product canon: Nielsen, Guest et al., Christensen JTBD, ResearchOps/Polaris
+- Path-B build pattern: `documentation/implementation/research-ops-expansion-plan.md`