@vextlabs/theron-cli 0.3.0 → 0.4.0

package/skills/business-case.md

@@ -0,0 +1,77 @@
+---
+name: business-case
+description: Build a rigorous business case for a decision or investment: size the problem and opportunity, model costs/benefits/risks across options including do-nothing, surface assumptions explicitly, and deliver a single prioritized recommendation with leading indicators and the strongest counterargument pre-empted.
+allowed-tools: Read, WebSearch, Write
+---
+
+═══ HARD RULES ═══
+1. NEVER present a figure as fact without labeling its source or derivation (own estimate, cited source, or stakeholder-stated).
+2. NEVER omit do-nothing as a named option — it is always a valid baseline with an explicit trajectory, not an absence.
+3. NEVER let the recommendation appear before the options analysis; the evidence must earn it.
+4. NEVER conflate revenue with profit, cost savings with cash, or one-time with recurring — label each row explicitly.
+5. NEVER fabricate market data, citations, or benchmarks; flag data gaps and state exactly what evidence would close them.
+6. NEVER recommend without naming the single strongest counterargument and giving a direct, specific rebuttal — no strawmen.
+7. NEVER present a single-point estimate where input uncertainty exceeds 20% — use base / downside / upside columns.
+8. ALL assumptions must be numbered, listed in one block before any model, and referenced inline as [A3], etc.
+9. NEVER count sunk costs as a reason to proceed — they are gone; only incremental future costs and benefits are decision-relevant.
+10. STOP and ask the user only when a missing input would structurally invalidate the model (e.g., unknown discount rate policy, regulatory constraint that changes option set); otherwise estimate, label [estimate], and proceed.
+
+═══ PHASE A — PROBLEM DEFINITION & DECISION FRAMING ═══
+A1. State: (a) the exact decision to be made in one sentence, (b) who must authorize it, and (c) the hard deadline — a date or event trigger — after which the window closes or costs escalate.
+A2. Write a two-sentence problem statement: (a) current state with a quantified pain or gap in concrete units (time, dollars, error rate, customer count, market share), (b) consequence of inaction stated in the same units over a defined time horizon.
+A3. Articulate the timing rationale — WHY is this decision available or urgent NOW and not in 12 months? Identify the specific change: regulatory window, competitive move, technology unlock, expiring contract, market inflection point, internal capacity becoming available. If the timing driver is weak, flag that urgency may be manufactured.
+A4. Define scope boundaries explicitly: what this business case does NOT analyze and why (prevents scope creep in the model and in the presentation).
+A5. Surface the decision criteria the authorizing audience actually uses. Executives optimizing for quarterly EPS weight payback period differently from founders optimizing for market position. If criteria are unstated, ask once; otherwise infer from context and state your inference. Common hard thresholds: IRR floor, payback cap (e.g., <24 months), minimum NPV hurdle, headcount freeze constraints, risk appetite (avoid any single point of failure exceeding X% revenue).
+A6. Calibrate the audience: identify whether the primary reader is a Board (strategic fit, risk, not the model details), CFO (NPV, cash timing, capex vs. opex treatment), operational sponsor (implementation realism, headcount, dependencies), or a mix — the emphasis and level of quantitative detail in subsequent phases must match.
+
+═══ PHASE B — OPTIONS GENERATION ═══
+B1. Generate a minimum of three options:
+    - Option 0 (Do Nothing): Describe the status quo TRAJECTORY — revenue decline, cost drift, competitive erosion — not just a frozen snapshot. Quantify where Option 0 lands at the end of the analysis horizon.
+    - Active options (minimum two): Apply the BUILD / BUY / PARTNER decision matrix below BEFORE naming options:
+        * BUILD if: the capability is a core differentiator, build cost < 2× buy cost over 3 years, and internal team has or can rapidly acquire the competency.
+        * BUY (acquire product/vendor) if: time-to-value is critical, the market has mature solutions with proven references, and switching cost is manageable.
+        * PARTNER / LICENSE if: the capability is non-core, volume does not justify owning the asset, or regulatory/IP risk makes ownership unattractive.
+        * Eliminate any quadrant that fails first-principles and document why — do not silently drop it.
+    - Option MV (Minimum Viable): A reduced-scope entry into the leading active option. Define "minimum viable" as the smallest investment that produces a measurable signal within 90 days and keeps the full option open.
+B2. For each option write one sentence: exactly HOW it closes the gap quantified in A2. If you cannot write this sentence, the option does not belong in the analysis.
+B3. Screen remaining options on three dimensions — feasibility (can we execute?), strategic fit (does it reinforce or dilute our position?), time-to-value (when does the first benefit dollar appear?) — and eliminate options failing any dimension. Record the reason; do not silently remove.
+B4. For each surviving active option, identify the PRIMARY COMPETITIVE RESPONSE expected from the market or from internal opponents. A business case that ignores how competitors or stakeholders will react to the decision is incomplete.
+
+═══ PHASE C — COST & BENEFIT QUANTIFICATION ═══
+C1. List ALL numbered assumptions before building any model. Each assumption must state: (a) its value or range, (b) source category — own estimate / benchmark / stated by stakeholder / data needed, and (c) confidence — High (within 10%) / Medium (within 30%) / Low (>30% uncertain). Low-confidence assumptions are automatically flagged for sensitivity testing in D4.
+C2. For each surviving option, build a cost/benefit table. These row categories are mandatory where material; add domain-specific rows as needed:
+    - One-time costs: capital expenditure, implementation labor (internal hours at fully-loaded rate), migration, integration, training, license setup, decommissioning of displaced systems.
+    - Recurring costs / run-rate delta vs. Option 0: operating expense, incremental headcount (FTEs × loaded cost), licensing, maintenance, support.
+    - Quantified benefits (each labeled as revenue uplift, cost avoidance, risk reduction, or productivity gain): state the mechanism, not just the number. "Reduces churn by 2pp" is better than "increases revenue by $X."
+    - Time horizon: minimum 3 years for operational decisions, 5 years for capital-intensive or strategic decisions. State the horizon and justify it.
+    - Discount rate: use the organization's WACC or hurdle rate if known; otherwise use 10% for well-established businesses, 15–20% for startups or high-uncertainty environments. State the rate and its source.
+    - NPV / 3-year net benefit per option.
+    - Break-even point in months.
+C3. Use ranges (base / downside / upside) for any input with confidence rated Medium or Low. A model built entirely on point estimates for uncertain inputs is not a business case — it is a forecast dressed as analysis.
+C4. Identify the top 3 cost drivers and top 3 benefit drivers by absolute magnitude — these are the model's load-bearing beams. Sensitivity analysis in Phase D will stress-test these specifically.
+C5. Cross-check: benefit-minus-cost math must tie to summary NPV/net-benefit figures. Disclose any rounding. Confirm that one-time costs are not counted as recurring or vice versa.
+C6. Sunk cost check: strip any already-spent investment from the incremental model. Sunk costs may appear in narrative context ("we already spent $X on Platform Y") but must not appear as a cost or a benefit in the decision model.
+
+═══ PHASE D — RISK ANALYSIS ═══
+D1. Risk register format: [R-ID] Description | Likelihood (H/M/L) | Impact (H/M/L, in $ or % revenue) | Mitigant | Residual exposure after mitigant.
+D2. Classify each risk by type: execution (can we deliver?), market (will demand materialize?), regulatory/compliance, technical (will it work at scale?), dependency (vendor, partner, internal team), reputational, or financial (FX, rate, liquidity).
+D3. Kill condition: identify the SINGLE scenario that makes the recommended option worse than Option 0 on the primary decision criterion. State: (a) what must be true for this to occur, (b) your estimated probability, (c) the earliest observable tripwire metric and its threshold, (d) the exit or pivot action if the tripwire is hit.
+D4. Sensitivity spine: for each active option, identify the ONE assumption from C1 that, if wrong in the unfavorable direction by its uncertainty band, most damages the NPV or net benefit. Run the model with that assumption at its downside value and report the delta. This is the load-bearing assumption that should be stress-tested in any pre-mortem.
+D5. Competitive response risk: for each active option, revisit the response identified in B4. What is the worst-case reaction, and does the business case still hold under that scenario?
+
+═══ PHASE E — OPTIONS COMPARISON & RECOMMENDATION ═══
+E1. Side-by-side comparison table (one row per option):
+    Option | NPV (base) | NPV (downside) | Payback (months) | Risk rating | Strategic fit (H/M/L) | Verdict
+    The table must be readable by an executive who has not read Phases A–D.
+E2. Recommendation in one sentence: "Recommend [Option X] because [primary financial rationale, with number] and [primary strategic rationale, with specific mechanism]." Vague rationales ("best overall value") are not permitted.
+E3. Counterargument: state the strongest honest case for a different option or for inaction (this is the argument that WILL be made in the room). Then rebut it with a specific, direct response — cite a number, a risk mitigant, or a structural reason the counterargument does not hold in this context. No dismissal without substance.
+E4. Leading indicators: define 3–5 metrics the decision-maker should track in the first 90 days to confirm the case is on track. Each must be: (a) measurable with existing or easily established instrumentation, (b) leading (predicts future outcome) not lagging (describes past outcome), (c) assigned a specific target value and a "flag" value that triggers a review. Example: "Pilot conversion rate ≥ 18% by day 60 (flag if <12%)."
+E5. Reversibility: state whether the organization can exit this decision cleanly within 12 months and at what cost (financial and operational). High reversibility increases the risk-adjusted case for acting; low reversibility demands a higher evidence bar before commitment.
+
+═══ PHASE F — ASSUMPTIONS REGISTER & NEXT STEPS ═══
+F1. Reproduce the full numbered assumptions list from C1, now with: (a) confidence rating, (b) sensitivity rank (High / Medium / Low impact on the recommendation if wrong), and (c) the specific action and data source that would upgrade a Low-confidence assumption to Medium or High. Sort by sensitivity rank descending.
+F2. Pre-mortem actions — 3–5 concrete things to do BEFORE committing spend that would catch the kill condition early: a time-boxed pilot, a technical spike, a reference call with a customer or vendor who has done this, a regulatory pre-submission, a competitive-response war-game. Each action must have an owner role, a timeline, and a pass/fail criterion.
+F3. Reopen threshold: state the minimum evidence that, if obtained, would change the recommendation — either toward a different option or toward reversal. This defines when it is legitimate to re-examine the decision without undermining commitment.
+F4. Executive summary (write last, place here): one paragraph — problem with quantified gap → opportunity and timing → recommended option and primary financial case → top risk and mitigant → first action and owner. Written for a non-technical sponsor with no prior context; no jargon, no model details, no assumption IDs.
+
+KEY PRINCIPLE: A business case is only as strong as its weakest assumption. Every number must be earned — labeled by source, stress-tested at its uncertainty band, and tied to a mechanism. The recommendation does not lead; the evidence does. The model's job is to make the best-available decision visible, not to sell a predetermined answer.

package/skills/causal-inference.md

@@ -0,0 +1,77 @@
+---
+name: causal-inference
+description: Identify causal effects, not correlations — define the estimand, draw the DAG, pick an identification strategy (RCT/IV/RDD/DiD/matching), and run falsification tests.
+allowed-tools: Read, Bash, Write, Grep
+---
+
+## Phase 0 — State the Estimand Before Touching Data
+
+1. Write the estimand in one sentence: target population (treated units / full population / subgroup), treatment contrast (T=1 vs T=0, or dose shift), outcome, and time horizon. ATE = E[Y(1)−Y(0)]; ATT = E[Y(1)−Y(0)|T=1]; CATE = E[Y(1)−Y(0)|X=x].
+2. Declare the unit of analysis (individual, firm, market, day) and the causal horizon (short-run vs long-run effects may differ).
+3. Write down what the ideal randomised experiment would look like. If you cannot describe it, you do not yet have a clear estimand.
+
+## Phase 1 — Draw the DAG (Do This on Paper First)
+
+4. List every variable: treatment T, outcome Y, pre-treatment covariates X, potential mediators M, potential colliders C, instruments Z.
+5. Draw directed edges encoding your domain knowledge. An arrow A→B means "A directly causes B holding everything else fixed."
+6. Mark confounders: common causes of T and Y that are NOT on the causal path T→...→Y.
+7. Mark mediators: variables on the causal path T→M→Y. Conditioning on M blocks the path and biases total-effect estimates — do NOT adjust for mediators when estimating total effect.
+8. Mark colliders: common effects of two causes (e.g. A→C←B). Conditioning on a collider OPENS a non-causal path — never condition on colliders.
+9. Apply the backdoor criterion: a valid adjustment set blocks every backdoor path (paths into T) without opening any new paths via colliders.
+10. Apply the frontdoor criterion only when all backdoor paths are unblockable but a measured mediator M captures the full T→Y path.
+11. Run `dagitty` (R) or `pgmpy` (Python) to enumerate all d-separation statements and verify your proposed adjustment set is valid.
+
+## Phase 2 — Choose the Identification Strategy
+
+12. **RCT**: If treatment was randomised, check balance (t-tests / standardised mean differences < 0.1). Estimate via OLS with pre-specified covariates (Lin estimator) for efficiency. Watch for non-compliance → use ITT; if compliance < 100% use IV with assignment as instrument.
+13. **Regression adjustment / backdoor**: Use when all confounders are measured. Run OLS or doubly-robust AIPW (combine propensity model + outcome model — consistent if either is correct). Use cross-fitting to avoid regularisation bias.
+14. **Instrumental Variables**: Instrument Z must satisfy (a) relevance: Cov(Z,T)≠0 — report first-stage F > 10 (Stock-Yogo); (b) exclusion: Z affects Y only through T — this is untestable, argue it structurally; (c) independence: Z ⊥ unmeasured confounders. Use 2SLS. LATE = effect on compliers only; report that scope honestly.
+15. **Regression Discontinuity**: Assignment determined by a running variable crossing a cutoff. Estimate local ATE at the cutoff only. Use local linear regression, not polynomials (overfitting). Optimal bandwidth via Imbens-Kalyanaraman or `rdrobust`. Check: (a) no manipulation of running variable (McCrary density test); (b) no jump in covariates at cutoff; (c) continuity of potential outcomes.
+16. **Difference-in-Differences**: Requires (a) parallel trends in pre-period — test visually and with event-study regression; (b) no anticipation — treatment effect is zero before treatment; (c) stable unit treatment values (SUTVA). Use staggered DiD via Callaway-Sant'Anna or Sun-Abraham estimators (not TWFE, which is biased under heterogeneous effects). Report pre-trend coefficients explicitly.
+17. **Matching / Propensity Score**: Estimate propensity score P(T=1|X) via logistic regression or gradient boosting. Match 1:1 nearest-neighbour with caliper 0.2×SD(logit(p)). Check post-match balance on ALL covariates. Prefer doubly-robust AIPW over PS-weighting alone (IPW is sensitive to extreme weights; trim weights at 99th percentile).
+18. **Synthetic Control**: Use when N=1 treated unit and many pre-periods. Construct a convex combination of control units that matches pre-treatment outcomes (and covariates). Report the ratio of post-treatment MSPE to pre-treatment MSPE; run permutation tests across control units for inference.
+
+## Phase 3 — Assumption Checks and Falsification Tests
+
+19. **Balance check**: For every adjustment strategy, report standardised mean differences before and after adjustment for all covariates. SMD < 0.1 is the threshold.
+20. **Pre-trend test (DiD/SC)**: Regress outcome on leads of treatment (event-study). Joint F-test of all pre-period coefficients = 0. Visualise the event study plot.
+21. **Placebo outcome test**: Apply the same estimator to an outcome that the treatment logically cannot affect. A significant effect signals model misspecification or confounding.
+22. **Negative control**: Find a negative control exposure (shares confounders with T but cannot cause Y) and a negative control outcome (shares confounders with Y but cannot be caused by T). Both should return null effects under a correct model.
+23. **Manipulation test (RDD)**: Run McCrary density test on the running variable at the cutoff. A discontinuity in density signals sorting.
+24. **Covariate continuity test (RDD)**: Regress each pre-treatment covariate on the running variable with the same bandwidth and estimator as the main spec. No covariate should jump at the cutoff.
+25. **Placebo cutoff test (RDD)**: Re-estimate the main spec at fake cutoffs away from the true cutoff. Effects should be null.
+26. **First-stage strength (IV)**: Kleibergen-Paap F-statistic > 10 for single instrument; use conditional F in the weak-instrument-robust Anderson-Rubin confidence set.
+27. **Exclusion restriction plausibility (IV)**: Argue structurally why Z→Y paths other than Z→T→Y are closed. Cannot be tested directly; report honest threats.
+28. **Overidentification test (IV)**: If you have multiple instruments, run Sargan-Hansen J-test. Rejection means at least one instrument violates exclusion.
+
+## Phase 4 — Estimation and Inference
+
+29. Use heteroskedasticity-robust (HC2/HC3) standard errors by default. Cluster at the level of treatment assignment. Never use non-clustered SEs when treatment is clustered.
+30. For DiD, use cluster-robust SEs at the group level. With few clusters (< 30), use wild cluster bootstrap.
+31. Report point estimate, 95% CI, and p-value. Report the effect size in natural units, not just statistical significance.
+32. For CATE estimation, use causal forests (`grf` in R or `econml` in Python). Report heterogeneity via best linear projection of CATE on covariates.
+33. Pre-register your specification. If you run multiple specs, report all of them and correct for multiple testing (Benjamini-Hochberg).
+
+## Phase 5 — Sensitivity to Unmeasured Confounding
+
+34. Compute the **E-value**: the minimum strength (on the risk ratio scale) an unmeasured confounder would need to have with both T and Y to fully explain away the observed effect. Report it alongside your main estimate. Formula: E = RR + sqrt(RR×(RR−1)) for RR > 1.
+35. Run **Rosenbaum sensitivity analysis** (for matched studies): find the gamma at which the inference breaks. Report the range of gamma consistent with your conclusions.
+36. For DiD, conduct **Rambachan-Roth sensitivity analysis**: how much would parallel trends need to fail (in units of the pre-trend) to reverse the sign?
+37. State explicitly which threats could reverse the sign of the effect and how plausible they are given domain knowledge.
+
+## Phase 6 — Reporting
+
+38. Report: estimand, design, identification assumptions, falsification results, point estimate + CI + E-value, and a one-sentence plain-English causal claim scoped to the identified population.
+39. Never write "X causes Y" without specifying: in what population, under what contrast, identified by what strategy, conditional on what assumptions holding.
+40. Separate what is identified (the causal claim your design licenses) from what is extrapolation (generalization beyond the support of your design).
+41. If the design cannot identify the estimand of interest, say so and propose what data or design would be needed. A credible null is more valuable than a spurious positive.
+
+## Hard Rules (Never Violate)
+
+- NEVER condition on a post-treatment variable when estimating total effect — this opens collider bias or blocks causal paths.
+- NEVER interpret a regression coefficient as causal without stating the identification assumption that licenses it.
+- NEVER report TWFE DiD with staggered treatment timing without heterogeneity-robust estimators.
+- NEVER use propensity score weighting without trimming extreme weights and checking overlap.
+- NEVER claim IV identifies ATE — it identifies LATE (the complier subpopulation) unless you have strong monotonicity + homogeneity arguments.
+- NEVER skip the falsification phase — one failed placebo invalidates the design.
+- ALWAYS report the E-value; a p < 0.05 with E-value of 1.2 is not credible evidence of causation.

package/skills/clinical-guideline.md

@@ -0,0 +1,98 @@
+---
+name: clinical-guideline
+description: Summarize clinical practice guidelines for a disease/condition/intervention — extracting evidence grades (GRADE/strength), target populations, contraindications, and cross-body conflicts — with primary source citations and a mandatory educational-use disclaimer; invoke when the user asks what guidelines say about a clinical topic, drug, screening threshold, treatment protocol, or diagnostic criterion.
+allowed-tools: Read, WebSearch, WebFetch, Write
+---
+
+═══ HARD RULES ═══
+
+1. NEVER fabricate a guideline, recommendation strength, evidence grade, citation, trial name, drug dose, threshold value, or population qualifier — if you cannot verify it, label it [UNVERIFIED] and exclude it from the summary table.
+2. NEVER present this output as professional medical advice, a substitute for clinical judgment, or a basis for patient management decisions.
+3. ALWAYS close every output with the mandatory disclaimer block defined in Phase F — no exceptions, no truncation.
+4. Cite only PRIMARY guideline sources (issuing society + year + document title + URL/DOI where retrievable). Do NOT cite secondary summaries (UpToDate, Medscape, Wikipedia) as authoritative — use them only to triangulate, then trace back to the primary document.
+5. When recommendations conflict across bodies (e.g., USPSTF vs. ACS vs. ESC), surface the conflict explicitly — never silently adopt one and suppress the other.
+6. Distinguish CURRENT from SUPERSEDED guidance: flag any guideline older than 5 years as potentially outdated and note whether a newer version exists. When a newer version from the same body exists, use the newer version and note the supersession.
+7. Do not extrapolate: if a guideline applies to adults ≥18, do not infer pediatric applicability. Population scope must be stated exactly as the issuing body states it.
+8. Risk escalation: if the query involves acute/life-threatening presentations (acute MI, sepsis, anaphylaxis, stroke, suicidality, airway compromise), prepend the acute safety note from Phase A4 before any guideline content and do not omit it.
+9. Never invent GRADE labels. Use only the grading system the issuing body itself uses (GRADE, Oxford CEBM, ACC/AHA Class I–III/LOE A–C, SIGN 1++–4, USPSTF A–D/I, NCCN Category 1/2A/2B/3, etc.) — name the system used and display a brief key in your output header so every strength label is interpretable without external lookup.
+10. Living and interim guidelines (e.g., WHO rapid guidance, NICE evidence reviews marked "in development", CDC interim recommendations) must be labeled [LIVING — subject to update] and re-checked at the source for currency.
+11. When no guideline from any identified body addresses the specific topic: state "No current guideline identified from [bodies checked]" — do not synthesize de novo clinical advice as a substitute. Note relevant systematic reviews or consensus statements only if clearly distinguished from formal society guidelines.
+
+═══ PHASE A — SCOPE LOCK ═══
+
+A1. Parse the user's query into: (a) clinical condition/topic, (b) intervention or decision node (screening / diagnosis / treatment / monitoring / prevention), (c) implied population (age, sex, comorbidities, pregnancy status, clinical setting — ICU vs. outpatient vs. community), (d) geographic/system scope (US, EU, UK, global, etc.). State each dimension explicitly before proceeding; flag any that are ambiguous and state your working assumption.
+A2. Identify the 3–6 authoritative guideline-issuing bodies most relevant to the topic. Examples by domain:
+    - Cardiology: ACC/AHA, ESC, NICE, CCS, Heart Failure Society of America
+    - Oncology: NCCN, ESMO, ASCO, NICE (cancer pathways)
+    - Primary care/prevention: USPSTF, Canadian Task Force on Preventive Health Care, WHO
+    - Endocrinology: ADA, Endocrine Society, AACE
+    - Infectious disease: IDSA, ESCMID, CDC, WHO
+    - Psychiatry: APA, NICE, CANMAT, BAP
+    - Nephrology: KDIGO, ERA
+    List the bodies selected and the reason each is relevant to this query.
+A3. For each body, state the grading taxonomy it uses and display a compact key in your output header:
+    - GRADE: Strong / Conditional (Weak), with evidence quality High/Moderate/Low/Very Low
+    - ACC/AHA: Class I (benefit>>risk) / IIa / IIb / III (no benefit or harm); LOE A (multiple RCTs/meta-analyses) / B-R / B-NR / C-LD / C-EO
+    - SIGN: 1++ (high-quality meta-analysis/SR/RCT with very low risk of bias) → 4 (expert opinion); A/B/C/D recommendation grades
+    - USPSTF: A (high certainty, substantial net benefit) / B / C / D (recommend against) / I (insufficient evidence)
+    - NCCN: Category 1 (high-level evidence, uniform consensus) / 2A / 2B / 3 (major disagreement)
+    - Other: name the system and its hierarchy
+A4. Acute safety gate: if the topic involves a potential emergency (acute MI, sepsis, anaphylaxis, stroke, suicidality, airway compromise, DKA, massive hemorrhage), begin ALL output with:
+    "⚠ ACUTE SAFETY NOTE: The following is an educational summary only. For any acute or life-threatening presentation, activate emergency services and follow local emergency protocols immediately. No guideline summary substitutes for real-time clinical assessment."
+
+═══ PHASE B — GUIDELINE RETRIEVAL ═══
+
+B1. Run targeted WebSearch queries for each issuing body from A2, e.g.: "[Society] [condition] guideline [year]", "[Society] [condition] clinical practice recommendation site:[society-domain].org". Prioritize the most recent published version; also search for in-progress living guidance.
+B2. For each hit, WebFetch the primary document or its executive summary / key-recommendations table. Extract: (a) exact publication year and version number, (b) full document title, (c) issuing society, (d) DOI or canonical URL, (e) whether the document is a full guideline, focused update, rapid guidance, or consensus statement — these carry different epistemic weight.
+B3. If a guideline is paywalled, retrieve the freely available executive summary, key-recommendations table, or press release from the same issuing body — note the access limitation and that only the accessible portion was reviewed.
+B4. Record retrieval failures explicitly: "Could not verify [Body] guidance — primary document not publicly accessible at time of retrieval." Never fill a gap with inference or secondary-source extrapolation.
+B5. Living/interim flag: if a document is marked as living, interim, or in development, tag it [LIVING] in every table row sourced from it. Note the expected next review date if stated.
+B6. Supersession check: if an older version is found first, search explicitly for "[Society] [condition] guideline update [current year–1 year]" to confirm no newer version exists before using the older document.
+
+═══ PHASE C — RECOMMENDATION EXTRACTION ═══
+
+C1. For each retrieved guideline, extract each discrete recommendation into a structured row:
+    | Recommendation | Grade/Class | LOE/Evidence Quality | Population Scope | Contraindications/Exceptions | Source (Society, Year) |
+C2. Map grades faithfully to the issuing body's own system. Never convert between systems without explicit labeling (e.g., "GRADE Strong ≈ ACC/AHA Class I — rough analog only, systems are not equivalent").
+C3. Capture population qualifiers at the finest granularity the guideline states: age range (e.g., 50–75 years), biological sex where specified, pregnancy/lactation status, renal function cutoff (eGFR threshold), hepatic function (Child-Pugh class), prior treatment history, validated risk-score thresholds (e.g., ASCVD 10-year risk ≥7.5%, CHA₂DS₂-VASc ≥2 in men/≥3 in women, FIB-4 ≥2.67).
+C4. Extract absolute contraindications, relative contraindications, and documented exceptions for each recommendation separately. Never omit the contraindication column; enter "None documented in this guideline" if applicable.
+C5. Note where a guideline is silent on a sub-population or scenario — silence is not endorsement and must not be treated as implicit permission.
+C6. No-guideline fallback: if Phase B yields no guideline for a key decision node, enter a row: "No guideline identified | — | — | — | — | [bodies checked]" and do not substitute clinical opinion.
+
+═══ PHASE D — CONFLICT ANALYSIS ═══
+
+D1. Compare recommendations across bodies side by side. Flag any conflict where: (a) grade or strength differs for the same intervention in the same population, (b) population thresholds differ (e.g., mammography start age 40 per ACS vs. 50 per USPSTF 2016 vs. 40 per USPSTF 2024), (c) one body recommends for while another explicitly recommends against, (d) dosing, monitoring intervals, or treatment duration differ.
+D2. For each conflict, provide the documented reason if available: different underlying evidence base (name the key RCTs), different modeling assumptions (absolute vs. relative risk, QALYs vs. life-years), health-system context (resource constraints, test availability), different population endpoint definitions. Do not editorialize about which body is correct.
+D3. Rate conflict severity:
+    - MAJOR: opposite directions — one body issues a recommendation FOR, another recommends AGAINST the same intervention in the same population
+    - MODERATE: same direction, meaningfully different thresholds, risk-score cutoffs, or recommendation strength (e.g., one strong/Class I, another conditional/Class IIb)
+    - MINOR: wording nuance, monitoring interval, or administrative detail only
+D4. Where a landmark RCT or meta-analysis drives the divergence, name it (trial acronym + year + primary endpoint result), e.g., "SPRINT (2015): SBP <120 mmHg reduced primary CV events 25% vs. <140 target; drove ACC/AHA 2017 threshold shift." Never invent trial names or results.
+D5. If the user's query references a specific trial by name, cross-check whether that trial's results have been incorporated into a subsequent guideline update — and state which bodies have or have not done so.
+
+═══ PHASE E — SYNTHESIS OUTPUT ═══
+
+E1. Open with a one-paragraph plain-language summary of the consensus position (where one exists) and the principal areas of disagreement. If no consensus exists, state that explicitly rather than constructing a false median.
+E2. Render the full recommendation table from Phase C, grouped by clinical decision node: Screening / Diagnosis / First-line treatment / Second-line / Escalation / Monitoring / Special populations.
+E3. Render a conflict table from Phase D: Conflict description | Bodies involved | Direction | Severity (MAJOR/MODERATE/MINOR) | Known reason for divergence.
+E4. Add a "Special Populations" section covering any guideline-specific guidance for: pregnancy and lactation, pediatrics (<18), older adults (≥75 or ≥65 as the body defines), chronic kidney disease (eGFR-stratified where available), hepatic impairment (Child-Pugh A/B/C where available), immunocompromised status, and rare/genetic subgroups — or state "No specific guidance identified in retrieved documents" for each category that applies.
+E5. Add a "Gaps and Research Frontiers" section: note only where issuing bodies themselves acknowledge insufficient evidence (GRADE low/very-low, LOE C-EO, USPSTF I, SIGN 4) and where active trials or scheduled guideline updates are noted in the retrieved documents. Do not speculate beyond what the documents state.
+E6. No-guideline conclusion: if Phase B found no guideline for the queried topic, conclude: "No formal clinical practice guideline from the bodies checked addresses [topic] at the specificity requested. Relevant systematic reviews or consensus statements, if found, are listed below and clearly distinguished from society guidelines. A clinician or specialist librarian should be consulted."
+E7. List all primary sources in a numbered reference list: [N] Society. Title. Version/Year. URL/DOI. Guideline type (full / focused update / living / consensus statement). Retrieved: [date].
+
+═══ PHASE F — MANDATORY DISCLAIMER ═══
+
+F1. Close EVERY output — without exception, without truncation — with this exact block (fill in bracketed fields):
+
+---
+**EDUCATIONAL USE ONLY — NOT MEDICAL ADVICE**
+
+This summary was generated by an AI agent for educational and informational purposes. It does not constitute professional medical advice, a clinical diagnosis, a treatment recommendation, or a substitute for the judgment of a licensed healthcare provider.
+
+- Guidelines change. Verify currency at the issuing body's official website before applying any recommendation. Living guidelines may have been updated since this retrieval.
+- Individual patient circumstances, comorbidities, contraindications, preferences, and local formulary/resource constraints must be evaluated by a qualified clinician.
+- If you or someone you care for is experiencing a medical emergency, call emergency services (e.g., 911 in the US / 999 in the UK / 112 in the EU) immediately.
+- Sources retrieved: [date of retrieval]. Issuing bodies checked: [list bodies from Phase A2].
+---
+
+KEY PRINCIPLE: Surface what the evidence actually says — grades, populations, conflicts, gaps, and the grading system used — exactly as the issuing bodies state it, never smoother or more certain than the underlying evidence warrants. When guidelines are absent, say so; when they conflict, show both sides.

package/skills/code-review.md

@@ -0,0 +1,98 @@
+---
+name: code-review
+description: Review a diff like a senior engineer — correctness first, then security, tests, API/compat, perf, readability; every comment file:line + concrete fix + severity tag.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+## PHASE 0 — ORIENT (do this before reading a single line of diff)
+
+1. Run `git diff main...HEAD --stat` to see the full scope: files changed, insertions, deletions.
+2. Run `git log main...HEAD --oneline` to read the commit message(s). Extract the stated intent.
+3. For each changed file, read the surrounding 40–80 lines of context that the diff does NOT show — the caller, the type definitions, the existing tests. Use Read with offset/limit. Never judge a patch in isolation.
+4. If the PR touches a public API, interface, or exported symbol, grep the entire codebase for existing callers: `grep -rn "symbolName" --include="*.ts" .` — understand the blast radius before forming any opinion.
+5. Hold a mental model: *what problem was this trying to solve, and what is the simplest correct solution?* Everything you find is measured against that baseline.
+
+## PHASE 1 — CORRECTNESS (blocking by default)
+
+6. Trace the happy path end-to-end through the changed code. Write it out in one sentence. If you cannot, the code is not readable enough — flag it.
+7. Enumerate inputs: zero, one, many, null/undefined/empty, max-size, malformed. For each, step through the logic manually. Does it handle them?
+8. Check every error path. Are errors caught, logged, surfaced, or swallowed silently? Silent swallow = blocking bug.
+9. Verify every conditional: off-by-one in loop bounds, `<` vs `<=`, `===` vs `==`, index into potentially-empty array.
+10. Check async/concurrent paths: unguarded shared state, missing `await`, Promise not returned, race between two async calls on the same resource.
+11. Check resource lifecycle: files, connections, locks — are they closed/released on ALL code paths including error paths?
+12. If the logic is non-trivial, mentally run a concrete example with real values through it. Does the output match the stated intent?
+13. If you are unsure whether a function exists or behaves as assumed, grep for it: `grep -n "functionName" path/to/file.ts`. Never trust the description.
+
+## PHASE 2 — SECURITY (blocking if relevant)
+
+14. Injection: any user-supplied string interpolated into SQL, shell, eval, innerHTML, URL, regex, or log sink without sanitization = blocking.
+15. AuthZ: every new route/endpoint/function that touches data — is ownership/permission checked *before* the query, not after?
+16. Secrets: `grep -rn "sk-\|api_key\|password\|secret\|token" --include="*.ts" .` on changed files. Hardcoded credential = blocking.
+17. Input validation: is there a schema/type guard at the trust boundary (HTTP handler, IPC, file read)? Trusting internal callers is fine; trusting network/user input is not.
+18. Cryptography: no hand-rolled crypto, no MD5/SHA1 for security, no fixed IV/nonce, no ECB mode. If crypto is touched, flag for specialist review.
+19. Dependency: if a new package is added, check it is not a typosquat and has a non-zero maintenance signal.
+
+## PHASE 3 — TESTS
+
+20. Run `grep -rn "describe\|it(\|test(" --include="*.test.*" .` scoped to the changed feature. Do tests exist?
+21. For each test, verify it exercises the *changed* code path, not just the pre-existing behavior. A test that passes before the PR is not a test for this PR.
+22. Check that edge cases from Phase 1 (empty input, error path, concurrency) have corresponding test cases.
+23. Check test assertions are meaningful: `expect(result).toBeDefined()` is not a meaningful assertion. `expect(result.id).toBe(42)` is.
+24. If tests are missing for a correctness-critical path, tag it **blocking**. If they exist but are thin, tag **should-fix**.
+
+## PHASE 4 — API / CONTRACT / BACKWARD COMPAT
+
+25. If a public function/type/route signature changed, grep for all callers: `grep -rn "oldFunctionName\|OldTypeName" . --include="*.ts"`. Every caller must be updated or the old signature kept as a shim.
+26. Check serialized formats (JSON keys, DB column names, URL paths, event names). Renaming a key in a stored/transmitted payload is a breaking change even if TypeScript compiles.
+27. Check version numbers: if the package exposes a public API and the signature changed, the semver bump must be at least minor (new feature) or major (breaking).
+28. Check migration files if DB schema changed. Is the migration reversible? Does it lock tables on large datasets?
+
+## PHASE 5 — PERFORMANCE (only real hot paths)
+
+29. Skip this phase for code that runs once at startup or on human-triggered actions. Apply it only to: hot loops, per-request middleware, stream processors, rendering paths.
+30. For hot paths: N+1 query (DB call inside a loop), unbounded array growth, synchronous I/O blocking the event loop, missing index on a WHERE clause column.
+31. Do not flag micro-optimizations (string concatenation, object spread) unless profiling data shows they matter.
+
+## PHASE 6 — READABILITY / MAINTAINABILITY / NAMING
+
+32. Names: does the name describe *what it is* (noun for data, verb for action)? Would a new engineer understand it without reading the implementation?
+33. Function length: if a function exceeds ~40 lines or has more than 3 levels of nesting, flag it as a should-fix candidate for extraction.
+34. Comments: comments should explain *why*, not *what*. A comment that restates the code is noise. A comment explaining a non-obvious invariant or workaround is gold.
+35. Dead code: flag any commented-out block, unreachable branch, or unused import.
+36. Consistency: does the new code follow the existing conventions in the file (naming, error handling, logging style)? Tag inconsistencies as nit.
+
+## PHASE 7 — REUSE
+
+37. Grep for similar logic already in the codebase before flagging duplication: `grep -rn "keyPhrase" --include="*.ts" .`. If a utility already exists, the new code should use it.
+38. If a new utility is introduced, check it is placed where other utilities live and is actually generic (not secretly coupled to one caller).
+
+## COMMENT FORMAT (every finding, no exceptions)
+
+```
+**[SEVERITY] file/path.ts:LINE**
+_Issue:_ One sentence describing the problem concretely.
+_Why it matters:_ One sentence on the consequence if unfixed.
+_Suggested fix:_
+```suggestion
+// concrete code replacement here
+```
+```
+
+Severity levels:
+- **blocking** — must be resolved before merge; correctness, security, or data-loss risk.
+- **should-fix** — strong recommendation; likely to cause a bug or maintenance burden; merge only with explicit acknowledgment.
+- **nit** — style, naming, minor cleanup; author may take or leave; do not block merge on nits alone.
+
+## HARD RULES
+
+39. Never approve if any **blocking** finding is open.
+40. Never approve if correctness-critical paths have zero test coverage.
+41. Separate objective correctness from personal style preference. "I would have written it differently" is not a blocking comment.
+42. If you are uncertain whether something is a bug, say so explicitly: "I believe this is a bug because X — please confirm or correct my reading."
+43. Do not trust the PR description. Verify behavior by reading the code. If the description says "this is safe" but you cannot confirm from the code, treat it as unverified.
+44. Be direct. "This will panic if `items` is empty" is better than "Consider whether items could be empty."
+45. Be kind. Assume competence and good intent. The goal is a better codebase, not a score.
+46. End the review with one of three verdicts:
+    - **APPROVE** — correctness and tests satisfied, no blocking findings.
+    - **REQUEST CHANGES** — one or more blocking or should-fix findings open.
+    - **COMMENT** — observations only, no change required; used for informational notes on approved PRs.