@diottodev/runic 1.0.0 → 1.1.0

package/research-ops/skills/product-research/scripts/insight_synthesizer.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""insight_synthesizer.py - Cluster coded observations into candidate insights; flag anecdotes.
+
+Stdlib-only. Deterministic. NO LLM calls. NEVER fabricates an insight: it counts evidence,
+clusters by tag, ranks by cross-participant recurrence, and flags any candidate supported by
+fewer than --min-sources independent participants as an ANECDOTE, not an insight.
+
+Input: a list of observations, each with {participant, tag, note}. The synthesizer groups by
+tag, counts distinct participants per tag, and ranks. This is the atomic-research discipline:
+an observation is evidence; an insight requires recurrence across independent sources.
+
+Usage:
+    python3 insight_synthesizer.py --sample
+    python3 insight_synthesizer.py --input observations.json --min-sources 3
+    python3 insight_synthesizer.py --input observations.json --output json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections import defaultdict
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+try:
+    import config_loader as _cfg
+except ImportError:  # pragma: no cover
+    _cfg = None
+
+SAMPLE = {
+    "study": "Onboarding discovery (mid-market HR)",
+    "observations": [
+        {"participant": "P1", "tag": "import-confusion", "note": "Couldn't find CSV import."},
+        {"participant": "P2", "tag": "import-confusion", "note": "Expected import on the dashboard."},
+        {"participant": "P3", "tag": "import-confusion", "note": "Gave up looking for bulk upload."},
+        {"participant": "P1", "tag": "permissions-unclear", "note": "Unsure who could see reports."},
+        {"participant": "P4", "tag": "permissions-unclear", "note": "Worried about data visibility."},
+        {"participant": "P2", "tag": "wants-slack", "note": "Asked for a Slack integration."},
+    ],
+}
+
+
+def synthesize(data: dict, min_sources: int) -> dict:
+    obs = data.get("observations", [])
+    by_tag_participants = defaultdict(set)
+    by_tag_notes = defaultdict(list)
+    for o in obs:
+        tag = o.get("tag", "untagged")
+        part = o.get("participant", "UNKNOWN")
+        by_tag_participants[tag].add(part)
+        by_tag_notes[tag].append({"participant": part, "note": o.get("note", "")})
+
+    candidates = []
+    for tag, parts in by_tag_participants.items():
+        n_sources = len(parts)
+        is_insight = n_sources >= min_sources
+        candidates.append({
+            "tag": tag,
+            "distinct_participants": n_sources,
+            "observation_count": len(by_tag_notes[tag]),
+            "classification": "INSIGHT" if is_insight else "ANECDOTE (single/low-source — do not generalize)",
+            "evidence": by_tag_notes[tag],
+        })
+    candidates.sort(key=lambda c: (c["distinct_participants"], c["observation_count"]), reverse=True)
+
+    total_participants = len({o.get("participant") for o in obs})
+    return {
+        "study": data.get("study", "UNSPECIFIED"),
+        "min_sources_for_insight": min_sources,
+        "total_participants": total_participants,
+        "candidates": candidates,
+        "note": "An observation is evidence; an insight requires recurrence across independent participants. "
+                "Anecdotes are surfaced, never promoted to insights.",
+    }
+
+
+def _render_human(r: dict) -> str:
+    lines = [f"Insight Synthesis: {r['study']}",
+             f"  total participants: {r['total_participants']}   insight threshold: >= {r['min_sources_for_insight']} sources", ""]
+    for c in r["candidates"]:
+        lines.append(f"[{c['classification']}] {c['tag']}  "
+                     f"({c['distinct_participants']} participants, {c['observation_count']} observations)")
+        for e in c["evidence"]:
+            lines.append(f"      {e['participant']}: {e['note']}")
+        lines.append("")
+    lines.append(f"note: {r['note']}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Cluster coded observations into insights; flag anecdotes.")
+    p.add_argument("--input", help="Path to JSON with observations[]")
+    p.add_argument("--min-sources", type=int, default=None,
+                   help="min distinct participants to call it an insight (overrides onboarding)")
+    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 {}
+    min_sources = args.min_sources if args.min_sources is not None else int(conf.get("insight_min_sources", 3))
+    data = SAMPLE if (args.sample or not args.input) else json.load(open(args.input))
+    result = synthesize(data, min_sources)
+    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/product-research/scripts/onboard.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""onboard.py - Onboarding questionnaire for the product-research skill.
+
+Stdlib-only. Asks the user a short set of questions BEFORE they plan a study, 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, the insight source-threshold,
+the default saturation method, and the high-stakes flag.
+
+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
+
+INT_KEYS = {"insight_min_sources"}
+BOOL_KEYS = {"stakes_high"}
+
+QUESTIONS = [
+    ("default_profile",
+     "1. What kind of product is this?",
+     ["b2b-saas", "consumer-app", "enterprise", "marketplace", "hardware", "platform"], str),
+    ("insight_min_sources",
+     "2. How many independent participants must support a finding before it counts as an insight (not an anecdote)?",
+     None, int),
+    ("default_method",
+     "3. Default sample-saturation method?",
+     ["usability", "thematic", "evaluative-coverage"], str),
+    ("stakes_high",
+     "4. Is this high-stakes / high-heterogeneity research (raise sample sizes)?",
+     ["true", "false"], str),
+]
+
+
+def _coerce(key: str, value: str):
+    if key in INT_KEYS:
+        return int(value)
+    if key in BOOL_KEYS:
+        return str(value).strip().lower() in ("true", "yes", "y", "1")
+    return value
+
+
+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] = _coerce(key, 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)
+            try:
+                config[k] = _coerce(k, v)
+            except ValueError:
+                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/product-research/scripts/saturation_planner.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""saturation_planner.py - Method-based participant/sample guidance with a confidence label.
+
+Stdlib-only. Deterministic. NO LLM calls. NEVER fabricates insight: it gives method-based
+sample guidance and an explicit confidence level, surfacing limits.
+
+Models:
+  - usability (Nielsen): ~5 users per segment uncovers ~85% of problems at typical p=0.31;
+    problems found = 1 - (1 - p)^n.
+  - thematic saturation (Guest et al.): ~12 interviews per homogeneous group typically
+    reaches saturation; >5 (Faulkner) when stakes/heterogeneity are high.
+  - evaluative coverage: detectable-problem coverage for a chosen per-problem detection rate.
+
+Usage:
+    python3 saturation_planner.py --sample
+    python3 saturation_planner.py --method usability --segments 2 --detection-rate 0.31
+    python3 saturation_planner.py --method thematic --segments 3 --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
+
+METHODS = ["usability", "thematic", "evaluative-coverage"]
+
+
+def usability_plan(segments: int, p: float, target_coverage: float) -> dict:
+    # n per segment to reach target coverage: n = ln(1 - target) / ln(1 - p)
+    import math
+    if not 0.0 < p < 1.0:
+        raise ValueError("detection-rate must be in (0,1).")
+    n = math.ceil(math.log(1 - target_coverage) / math.log(1 - p))
+    coverage_at_5 = 1 - (1 - p) ** 5
+    return {
+        "method": "usability",
+        "per_problem_detection_rate": p,
+        "target_coverage": target_coverage,
+        "n_per_segment": n,
+        "segments": segments,
+        "total_participants": n * segments,
+        "coverage_at_5_per_segment": round(coverage_at_5, 3),
+        "confidence": "MODERATE" if n >= 5 else "LOW (small-n usability finds problems, not rates)",
+        "limits": "Usability tests surface problems, not their population prevalence. Do not report percentages.",
+    }
+
+
+def thematic_plan(segments: int, stakes_high: bool) -> dict:
+    base = 12  # Guest et al. typical saturation for a homogeneous group
+    per_segment = base if not stakes_high else max(base, 15)
+    return {
+        "method": "thematic",
+        "n_per_segment": per_segment,
+        "segments": segments,
+        "total_participants": per_segment * segments,
+        "confidence": "MODERATE-HIGH" if per_segment >= 12 else "LOW",
+        "limits": "Saturation is observed, not guaranteed; track new-theme rate and stop when it flattens. "
+                  "Faulkner (2003): more than 5 when heterogeneity or stakes are high.",
+    }
+
+
+def evaluative_coverage_plan(segments: int, n_per_segment: int, p: float) -> dict:
+    coverage = 1 - (1 - p) ** n_per_segment
+    return {
+        "method": "evaluative-coverage",
+        "per_problem_detection_rate": p,
+        "n_per_segment": n_per_segment,
+        "segments": segments,
+        "expected_problem_coverage": round(coverage, 3),
+        "confidence": "MODERATE" if coverage >= 0.8 else "LOW",
+        "limits": "Coverage is for the assumed detection rate; rarer problems need more participants.",
+    }
+
+
+def plan(method: str, segments: int, p: float, target: float, stakes_high: bool, n: int) -> dict:
+    if method == "usability":
+        out = usability_plan(segments, p, target)
+    elif method == "thematic":
+        out = thematic_plan(segments, stakes_high)
+    elif method == "evaluative-coverage":
+        out = evaluative_coverage_plan(segments, n, p)
+    else:
+        raise ValueError(f"method must be one of {METHODS}.")
+    out["disclaimer"] = "Method-based guidance with explicit confidence. This is not a power calculation; " \
+                        "it never claims an insight the data cannot support."
+    return out
+
+
+def _render_human(r: dict) -> str:
+    lines = [f"Saturation / Sample Plan  (method: {r['method']})", ""]
+    for k, v in r.items():
+        if k in ("method",):
+            continue
+        lines.append(f"  {k:32s} : {v}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Method-based product-research sample guidance with confidence.")
+    p.add_argument("--method", choices=METHODS, default=None, help="overrides onboarding default_method")
+    p.add_argument("--segments", type=int, default=1)
+    p.add_argument("--detection-rate", type=float, default=0.31, help="per-problem detection rate (usability)")
+    p.add_argument("--target-coverage", type=float, default=0.85, help="target problem coverage (usability)")
+    p.add_argument("--stakes-high", action="store_true", help="raise thematic n for high heterogeneity/stakes")
+    p.add_argument("--n-per-segment", type=int, default=8, help="n per segment (evaluative-coverage)")
+    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 {}
+    method = args.method or conf.get("default_method", "usability")
+    stakes_high = args.stakes_high or bool(conf.get("stakes_high", False))
+
+    if args.sample:
+        try:
+            result = plan("usability", 2, 0.31, 0.85, False, 8)
+        except ValueError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+    else:
+        try:
+            result = plan(method, args.segments, args.detection_rate,
+                          args.target_coverage, stakes_high, args.n_per_segment)
+        except ValueError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+
+    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/product-research/scripts/study_designer.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""study_designer.py - Select a product-research method from goal + stage, emit a plan skeleton.
+
+Stdlib-only. Deterministic. NO LLM calls.
+
+Maps (research goal x product stage) to an appropriate method and emits a method-matched
+plan skeleton (objective framing, participant criteria, task/guide structure, success
+criteria). The core discipline: GENERATIVE goals (discover problems) and EVALUATIVE goals
+(test a solution) demand different methods — picking the wrong one is the most common error.
+
+Usage:
+    python3 study_designer.py --sample
+    python3 study_designer.py --goal discovery --stage concept --profile b2b-saas
+    python3 study_designer.py --goal evaluative --stage live --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
+
+PROFILES = ["b2b-saas", "consumer-app", "enterprise", "marketplace", "hardware", "platform"]
+
+# (goal, stage) -> method. goal in {discovery, evaluative, validation}; stage in {concept, prototype, beta, live}
+METHOD_MAP = {
+    ("discovery", "concept"): "generative interviews (semi-structured)",
+    ("discovery", "prototype"): "contextual inquiry",
+    ("discovery", "beta"): "diary study + follow-up interviews",
+    ("discovery", "live"): "behavioral analytics review + generative interviews",
+    ("evaluative", "concept"): "concept test (comprehension + desirability)",
+    ("evaluative", "prototype"): "moderated usability test",
+    ("evaluative", "beta"): "unmoderated usability test + task-success metrics",
+    ("evaluative", "live"): "benchmark usability study (SUS / task time)",
+    ("validation", "concept"): "survey (desirability + willingness signals)",
+    ("validation", "prototype"): "prototype A/B preference test",
+    ("validation", "beta"): "fake-door / feature-demand test",
+    ("validation", "live"): "live A/B experiment (route to product-team/experiment-designer)",
+}
+
+GUIDE_SKELETONS = {
+    "generative": ["Warm-up + context", "Recent relevant experience (story, not opinion)",
+                   "Workarounds + frustrations", "Jobs-to-be-done probe", "Magic-wand / wrap"],
+    "evaluative": ["Pre-task context", "Task 1 (representative)", "Task 2 (edge)",
+                   "Observation: where do they hesitate/err?", "Post-task SUS / debrief"],
+    "validation": ["Screener", "Stimulus exposure", "Comprehension + desirability items",
+                   "Trade-off / preference items", "Behavioral-intent item"],
+}
+
+
+def design(goal: str, stage: str, profile: str) -> dict:
+    if profile not in PROFILES:
+        raise ValueError(f"Unknown profile '{profile}'. Choose from {PROFILES}.")
+    key = (goal, stage)
+    if key not in METHOD_MAP:
+        raise ValueError(f"No method for goal={goal}, stage={stage}. "
+                         f"goal in [discovery,evaluative,validation]; stage in [concept,prototype,beta,live].")
+    method = METHOD_MAP[key]
+    family = "generative" if goal == "discovery" else ("evaluative" if goal == "evaluative" else "validation")
+    redirect = None
+    if "experiment-designer" in method:
+        redirect = "Live A/B is a product experiment — use product-team/experiment-designer, not this skill."
+    return {
+        "goal": goal,
+        "stage": stage,
+        "profile": profile,
+        "method": method,
+        "method_family": family,
+        "objective_framing": f"A {family} study at the {stage} stage to {('discover unmet needs' if family=='generative' else 'evaluate the solution' if family=='evaluative' else 'validate demand/desirability')}.",
+        "participant_criteria": [
+            "Recruit to the target segment (screen for the job, not a job title).",
+            "Exclude internal/biased participants and prior-study repeats unless longitudinal.",
+            "Recruit per-segment if results will be reported per-segment.",
+        ],
+        "guide_skeleton": GUIDE_SKELETONS[family],
+        "success_criteria": [
+            "Generative: themes recur across independent participants (saturation).",
+            "Evaluative: task-success rate + severity-rated problem list.",
+            "Validation: pre-registered desirability / preference threshold.",
+        ],
+        "redirect": redirect,
+        "note": "Method must match the goal. A usability test cannot discover unmet needs; an interview cannot measure task success.",
+    }
+
+
+def _render_human(r: dict) -> str:
+    lines = [f"Study Design: goal={r['goal']}, stage={r['stage']}, profile={r['profile']}", "",
+             f"  Recommended method: {r['method']}  (family: {r['method_family']})",
+             f"  Objective: {r['objective_framing']}", "", "  Participant criteria:"]
+    for c in r["participant_criteria"]:
+        lines.append(f"    - {c}")
+    lines.append("  Guide skeleton:")
+    for i, g in enumerate(r["guide_skeleton"], 1):
+        lines.append(f"    {i}. {g}")
+    lines.append("  Success criteria:")
+    for s in r["success_criteria"]:
+        lines.append(f"    - {s}")
+    if r["redirect"]:
+        lines += ["", f"  !! {r['redirect']}"]
+    lines += ["", f"note: {r['note']}"]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Select a product-research method from goal + stage.")
+    p.add_argument("--goal", choices=["discovery", "evaluative", "validation"], default="discovery")
+    p.add_argument("--stage", choices=["concept", "prototype", "beta", "live"], default="prototype")
+    p.add_argument("--profile", default=None, choices=PROFILES,
+                   help="overrides onboarding default_profile")
+    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_default = conf.get("default_profile", "b2b-saas")
+    goal, stage, profile = ("discovery", "prototype", profile_default) if args.sample \
+        else (args.goal, args.stage, args.profile or profile_default)
+    try:
+        result = design(goal, stage, profile)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    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-finance/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: research-finance
+description: Use when managing the money for an internal R&D program or portfolio — building a multi-period program budget with the F&A (indirect) split, tracking burn rate and runway against value-inflection milestones, or routing R&D cost items to a capitalize-vs-expense determination. Every budget output surfaces its assumptions block; capitalize-vs-expense is decision-support only and routes to a named finance owner — it never books an entry or decides accounting treatment. Distinct from finance/financial-analysis (corporate DCF, close, valuation) and research/grants (funding discovery — this manages money already won).
+version: 2.9.0
+author: claude-code-skills
+license: MIT
+tags: [research-ops, research-finance, rd-budget, burn-rate, runway, fa-rate, capitalize-vs-expense, portfolio]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# research-finance
+
+Financial management of internal R&D programs and portfolios: program budgeting with F&A, burn/runway tracking, and capitalize-vs-expense routing. Every number ships with its **assumptions block**, and accounting-treatment calls **route to a named finance owner** — this skill never books an entry.
+
+## Purpose
+
+R&D finance partners, program controllers, and operations leads manage money that has already been allocated or raised — not the corporate close, not the next funding round, not finding a grant. This skill structures three recurring decisions:
+
+Three deterministic tools:
+
+1. `program_budget_planner.py` — Builds a multi-period budget from work-package line items, applies the F&A (indirect) rate to an MTDC-style eligible base, and rolls up direct / F&A / fully-loaded cost per period with an explicit assumptions block.
+2. `burn_runway_tracker.py` — Computes average + trailing burn, runway in periods/months, and whether each value-inflection milestone is reachable before cash runs out. Flags accelerating burn and below-threshold runway.
+3. `capex_vs_opex_router.py` — Scores each R&D cost item against the IAS 38 development-phase criteria (or flags US GAAP ASC 730 expense-as-incurred) and routes it to **CAPITALIZE-CANDIDATE / EXPENSE / FINANCE-OWNER-REVIEW** with a named owner. Never auto-decides.
+
+## When to use
+
+Invoke this skill when:
+
+- You are building or revising an R&D program budget and need the F&A split made explicit.
+- A program's runway is in question and you need a milestone-vs-cash read.
+- Finance asks whether a development cost can be capitalized and you need a defensible first routing.
+- You are preparing a portfolio review and need per-program burn consistency.
+
+**Do NOT use this skill to**: run corporate DCF / valuation / close (use `finance/financial-analysis`), discover or position grants (use `research/grants`), or make the final accounting determination (that is the controller's + auditor's call — this tool only routes).
+
+## Workflow
+
+1. **Lay out the program** — Fill `assets/rd_program_budget_template.md` with work-package lines, categories, and per-period amounts.
+2. **Build the budget** — Run `program_budget_planner.py --input program.json --profile {pharma-rd|biotech|medtech|deep-tech|software-rd|university-lab} --fa-rate <negotiated rate>`. Read direct / F&A / fully-loaded rollups + assumptions.
+3. **Track burn & runway** — Run `burn_runway_tracker.py --input ledger.json --threshold-months 6`. Read runway + milestone verdicts + flags.
+4. **Route accounting treatment** — Run `capex_vs_opex_router.py --input costs.json --standard {ifrs|usgaap}`. Read the per-item routing; send CAPITALIZE-CANDIDATE and FINANCE-OWNER-REVIEW items to the named owner.
+5. **Assemble the review** — Combine into a program-finance packet. Every number carries its assumptions; treatment calls carry a named owner.
+
+## Scripts
+
+| Script | Purpose | Profiles |
+|---|---|---|
+| `scripts/program_budget_planner.py` | Multi-period budget + F&A split + assumptions | pharma-rd, biotech, medtech, deep-tech, software-rd, university-lab |
+| `scripts/burn_runway_tracker.py` | Burn, runway, milestone-vs-cash alignment | n/a (ledger-driven) |
+| `scripts/capex_vs_opex_router.py` | IAS 38 / ASC 730 routing to named finance owner | pharma-rd, biotech, medtech, deep-tech, software-rd, university-lab |
+
+All three: stdlib-only, `--help`, `--sample`, `--output {human,json}`.
+
+## Onboarding & customization
+
+Run the onboarding questionnaire **once before you start** — it captures your defaults so every tool in this skill is pre-configured. Customization is the point: the answers actually change tool behavior.
+
+```bash
+python3 scripts/onboard.py            # interactive (also: --defaults, --set key=value, --reset)
+python3 scripts/onboard.py --show     # see the questions + current effective config
+```
+
+Answers are saved to `~/.config/research-ops/research-finance.json` (global) or `./.research-ops/research-finance.json` (`--scope project`) and are read automatically by `config_loader.py`. They set the default R&D-area **profile**, the default **F&A rate**, the **runway alert threshold**, the **accounting standard**, and the named **finance owner** printed on capitalize-vs-expense routing. CLI flags always override saved config; `RESEARCH_OPS_NO_CONFIG=1` ignores it.
+
+**The five questions:** R&D area · F&A rate · runway threshold · accounting standard · finance owner.
+
+## Optimize with autoresearch (opt-in)
+
+This skill ships an **isolated, opt-in** bridge to `engineering/autoresearch-agent`. Only when you ask to "optimize" / "extend runway" / "run a loop" does an autoresearch experiment iteratively improve a program plan against this skill's runway metric. `scripts/ar_evaluator.py` is the ground-truth evaluator; it prints `runway_months: <float>` (higher is better).
+
+```bash
+/ar:setup --domain custom --name extend-runway \
+  --target ledger.json \
+  --eval "python3 ar_evaluator.py --target ledger.json" \
+  --metric runway_months --direction higher
+/ar:loop custom/extend-runway
+```
+
+Isolated: no hard dependency — autoresearch runs only on demand, and the loop edits `ledger.json`, never the evaluator.
+
+## References
+
+- `references/rd_program_finance_canon.md` — IAS 38 (research vs development); ASC 730 + ASC 985-20; Uniform Guidance 2 CFR 200 (F&A); FASB/IFRS capitalization criteria; NICRA basics.
+- `references/burn_and_portfolio.md` — Cooper stage-gate; rNPV / real-options for R&D; risk-adjusted portfolio ROI; burn-rate / runway frameworks; milestone-based budgeting.
+- `references/indirect_rate_modeling.md` — F&A pool composition (facilities + administration); MTDC base; de minimis 10%; fringe/overhead loading; CAS primer.
+
+## Assumptions
+
+- The F&A rate is the most error-prone input. The planner applies whatever rate you pass; it warns you to confirm it is a negotiated NICRA, not a guess.
+- Burn/runway uses the trailing (recent-weighted) burn as the forward run-rate and assumes flat forward spend unless your ledger encodes a ramp.
+- The capex router asserts criteria from your input; asserting "technical feasibility" does not make it true — the named finance owner and auditor validate it.
+- Profiles annotate context (e.g., "most drug R&D is expensed") but do not change the accounting test.
+
+## Anti-patterns
+
+- **Stating a budget number without its assumptions.** F&A rate, escalation, and base must travel with the number.
+- **Auto-deciding capitalize-vs-expense.** This tool routes; the controller (and auditor where required) decides.
+- **Using lifetime-average burn for runway.** Recent burn is the honest forward run-rate; averages hide a slowdown or a ramp.
+- **Applying F&A to the full base.** Capital equipment, large subaward portions, and certain categories are MTDC-exempt.
+- **Confusing this with corporate finance.** Valuation, close, and fundraising live in `finance/`.
+
+## Distinct from
+
+| Sibling / neighbor | Scope | Difference |
+|---|---|---|
+| `finance/financial-analysis` | Corporate DCF, ratios, close, rolling forecast, SaaS metrics | That is **company-level**; this is **R&D-program-level** |
+| `research/grants` | NIH funding discovery + positioning | That **finds funding**; this **manages money already won** |
+| `clinical-research` (sibling) | Study design + feasibility + budget gate-check | That **scopes** the study; this **funds + tracks** the program |
+| `ra-qm-team` | Regulatory/QM submission | Unrelated — no financial scope |
+
+## Quick examples
+
+```bash
+python3 scripts/program_budget_planner.py --sample
+python3 scripts/program_budget_planner.py --input program.json --profile university-lab --fa-rate 0.585
+python3 scripts/burn_runway_tracker.py --sample --output json
+python3 scripts/capex_vs_opex_router.py --sample --standard ifrs
+```
+
+The sample budget excludes the sequencer (capital equipment) and CRO subaward from the F&A base; the capex router routes exploratory screening to EXPENSE, a fully-criteria'd pilot line to CAPITALIZE-CANDIDATE, and a partial-criteria software build to FINANCE-OWNER-REVIEW.
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+Walked one at a time by `/cs:grill-research-ops` or the orchestrator. Recommended answer + canon citation per question. Never bundled.
+
+1. **"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.54-57; ASC 730.
+
+2. **"What F&A / indirect rate are you applying, and is it your negotiated NICRA, a de minimis 10%, or an assumption?"**
+   Recommended: use the negotiated rate; if assumed, flag it explicitly.
+   Canon: 2 CFR 200 (Uniform Guidance); NICRA basics.
+
+3. **"What's runway in months at current burn, and does it clear the next value-inflection milestone?"**
+   Recommended: runway must cover the milestone plus a buffer; surface the gap.
+   Canon: Cooper stage-gate; SaaS/startup efficiency frameworks (a16z, Bessemer).
+
+4. **"Is portfolio ROI risk-adjusted (rNPV / probability-of-success weighted) or raw NPV?"**
+   Recommended: risk-adjusted; raw NPV overstates R&D value.
+   Canon: rNPV drug-development valuation; real-options literature.
+
+5. **"Who is the named finance / controller owner who signs the capitalize-vs-expense treatment?"**
+   Recommended: name them — this tool recommends, it never books the entry.
+   Canon: ASC 730 / IAS 38 governance; auditor sign-off requirements.
+
+Walk depth-first. Lock 1-2 before opening 3-5. After all are answered, invoke `program_budget_planner.py` → `burn_runway_tracker.py` → `capex_vs_opex_router.py`.