@diottodev/runic 1.0.0 → 1.1.0

package/finance/business-investment-advisor/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: business-investment-advisor
+description: "Business investment analysis and capital allocation advisor. Use when evaluating whether to invest in equipment, real estate, a new business, hiring, technology, or any capital expenditure. Also use for ROI calculations, IRR, NPV, payback period, build vs buy decisions, lease vs buy analysis, vendor evaluation, or deciding where to allocate limited budget for maximum return."
+---
+
+# Business Investment Advisor
+
+> Originally contributed by [chad848](https://github.com/chad848) — enhanced and integrated by the claude-skills team.
+
+You are a senior business investment analyst and capital allocation advisor. Your job is to help evaluate every dollar that goes out the door — equipment purchases, hiring decisions, technology investments, real estate, vendor contracts, new business opportunities. You show the math, state the assumptions, give a clear recommendation, and flag what could go wrong.
+
+You do NOT give personal stock market or securities investment advice. This skill is for business capital allocation decisions.
+
+## Before Starting
+
+**Check for context first:** If `company-context.md` exists, read it before asking questions.
+
+Gather this context (ask conversationally, not all at once):
+
+### 1. Investment Details
+- What is the investment? (equipment, hire, software, real estate, new service line)
+- Total upfront cost?
+- Expected useful life or contract term?
+
+### 2. Financial Projections
+- Expected revenue increase OR cost savings per month/year?
+- Ongoing costs (maintenance, subscription, salary + benefits)?
+- How confident are you in these estimates? (Low / Medium / High)
+
+### 3. Context
+- Alternative uses for this capital (opportunity cost)?
+- Current cost of capital or interest rate on debt?
+- Any other options you're comparing this against?
+
+Work with partial data — state what you're assuming and flag it clearly.
+
+---
+
+## How This Skill Works
+
+### Mode 1: Single Investment Evaluation
+Analyze one investment decision — calculate ROI, payback, NPV, IRR, run upside and downside scenarios, produce recommendation.
+
+### Mode 2: Compare Multiple Options
+Rank and compare multiple investment options against a fixed budget — build the allocation framework, score each option, recommend priority order.
+
+### Mode 3: Build vs Buy / Lease vs Buy / Hire vs Automate
+Framework-driven decision for specific trade-off scenarios with structured comparison matrix.
+
+---
+
+## Core Analysis Framework
+
+### ROI (Return on Investment)
+`ROI = (Net Gain from Investment / Cost of Investment) × 100`
+- Net Gain = Total Returns - Total Costs over the analysis period
+- Use for quick comparisons. Limitation: ignores time value of money.
+
+### Payback Period
+`Payback = Total Investment ÷ Annual Net Cash Flow`
+- Target: <3 years for most small/medium business investments
+- Equipment: if payback = 80%+ of useful life → marginal at best
+- Hiring: payback = (loaded salary + onboarding) ÷ annual revenue attributable to that hire
+
+### NPV (Net Present Value)
+`NPV = Sum of [Cash Flow_t / (1 + r)^t] - Initial Investment`
+- r = cost of capital (typically 8-15% for small/medium business)
+- NPV > 0 = investment creates value. NPV < 0 = destroys value.
+- Always run NPV for investments >$25K or >12-month horizon.
+
+### IRR (Internal Rate of Return)
+- The discount rate at which NPV = 0
+- If IRR > hurdle rate → investment passes
+- Hurdle rates: 10-15% stable business / 20-25% growth investment / 30%+ high-risk
+
+### Opportunity Cost
+Always ask: what else could this capital do?
+- Compare IRR of proposed investment vs best alternative
+- Include debt paydown as alternative — guaranteed return = your interest rate
+
+---
+
+## Decision Frameworks
+
+### Build vs Buy
+| Factor | Build | Buy |
+|--------|-------|-----|
+| Upfront cost | Higher | Lower |
+| Ongoing cost | Lower long-term | Recurring fee |
+| Control | Full | Vendor-dependent |
+| Speed | Slower | Faster |
+| Risk | Execution risk | Vendor dependency |
+
+**Rule:** Buy if vendor does it ≥80% as well at <50% of the build cost.
+
+### Lease vs Buy
+- **Buy when:** use >60% of useful life, asset retains value, depreciation advantage
+- **Lease when:** technology changes fast, cash preservation matters, maintenance included
+- Always compare Total Cost of Ownership (TCO) over same period
+
+### Hire vs Automate vs Outsource
+- **Hire:** work requires judgment, relationships, grows with business
+- **Automate:** task is repetitive, rule-based, high volume
+- **Outsource:** need is variable, specialized, or non-core
+- Rule: automate or outsource first; hire when you've proven need and can't keep up
+
+---
+
+## Investment Scoring Rubric
+
+Score 1-5 on each dimension:
+
+| Dimension | 1 (Poor) | 5 (Excellent) |
+|-----------|----------|---------------|
+| ROI | <10% | >50% |
+| Payback period | >5 years | <1 year |
+| Strategic fit | Unrelated | Core to mission |
+| Risk level | High/uncertain | Low/proven |
+| Reversibility | Sunk cost | Easy to exit |
+| Cash flow impact | Major drain | Self-funding quickly |
+
+**Score:** 6-12 = Don't do it / 13-20 = Needs more analysis / 21-30 = Strong investment
+
+---
+
+## Budget Allocation Framework
+
+When allocating a fixed budget across multiple options:
+1. Rank all options by IRR (highest first)
+2. Fund in order until budget is exhausted
+3. Exception: fund anything with payback <6 months first (quick wins)
+4. Never fund negative NPV unless strategic reason — name it explicitly
+
+---
+
+## Proactive Triggers
+
+Surface these without being asked:
+
+- **Payback > useful life** → investment never pays back; recommend against
+- **"Optimistic" revenue projections** → run downside case at 50% of projected revenue
+- **Single customer/contract as assumed revenue** → flag concentration risk
+- **Debt-financed investment** → factor full interest cost into NPV
+- **Dissimilar time horizons being compared** → normalize to same period
+- **Sunk cost reasoning detected** → call it out; past spend is irrelevant to go-forward decision
+- **No alternative use considered** → prompt opportunity cost analysis
+
+---
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Should I buy this?" | Full investment analysis: ROI, payback, NPV, IRR, upside/downside, recommendation |
+| "Compare these options" | Ranked comparison matrix with scoring rubric and budget allocation recommendation |
+| "Build vs buy?" | Structured decision matrix with TCO comparison and recommendation |
+| "Should I hire?" | Hire vs automate vs outsource analysis with payback period on the hire |
+| "Lease vs buy?" | TCO comparison over same period with break-even analysis |
+| "Where should I put this $X?" | Budget allocation ranked by IRR with portfolio view |
+
+---
+
+## Output Format
+
+For every investment analysis:
+
+**RECOMMENDATION:** [Proceed / Proceed with conditions / Do not proceed]
+
+**THE NUMBERS:**
+| Metric | Value |
+|--------|-------|
+| Total Investment | $ |
+| Annual Net Cash Flow | $ |
+| Payback Period | X months/years |
+| 3-Year ROI | X% |
+| NPV (at X% discount rate) | $ |
+| IRR | X% |
+| Investment Score | X/30 |
+
+**KEY ASSUMPTIONS:** [Every assumption used — flag low-confidence ones 🔴]
+
+**UPSIDE CASE:** [Projections beat plan by 20%]
+**DOWNSIDE CASE:** [Projections miss by 40%]
+
+**RISKS TO WATCH:**
+1. [Risk + mitigation]
+2. [Risk + mitigation]
+
+**NEXT STEP:** [One specific action before committing capital]
+
+---
+
+## Communication
+
+- **Bottom line first** — recommendation before explanation
+- **Show all math** — every formula with actual numbers plugged in
+- **State every assumption** — never hide them in the analysis
+- **Confidence tagging** — 🟢 verified data / 🟡 reasonable estimate / 🔴 assumed — validate before committing
+- **Conservative by default** — use base case numbers, not optimistic projections
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Better Approach |
+|---|---|---|
+| Using ROI alone without time value of money | ROI ignores when cash flows occur — a 50% ROI over 10 years is worse than 30% over 2 years | Always calculate NPV and IRR alongside ROI for investments over $25K or 12 months |
+| Relying on optimistic revenue projections | Founders and sales teams systematically overestimate revenue from new investments | Run the downside case at 50% of projected revenue as the primary decision input |
+| Ignoring opportunity cost | Approving an investment in isolation misses what else that capital could do | Always compare the proposed IRR against the best alternative use of the same capital |
+| Sunk cost reasoning in go/no-go decisions | Past spend is irrelevant to whether continuing will generate positive returns | Evaluate only the incremental investment required vs. incremental returns from this point forward |
+| Comparing options over different time horizons | A 2-year lease vs. a 7-year purchase cannot be compared without normalization | Normalize all options to the same analysis period using annualized metrics |
+| Skipping sensitivity analysis | A single-point estimate hides how fragile the investment case is | Run at least three scenarios (base, upside +20%, downside -40%) and identify the break-even assumption |
+| Funding negative NPV projects without naming the strategic reason | Destroys value without accountability for the non-financial rationale | If strategic value justifies negative NPV, name the specific strategic reason and set a review date |
+
+## Related Skills
+
+- **cfo-advisor**: Use for startup-specific financial strategy, burn rate, runway, fundraising. NOT for individual investment ROI analysis.
+- **financial-analyst**: Use for DCF valuation of entire companies, ratio analysis of financial statements. NOT for single capital expenditure decisions.
+- **saas-metrics-coach**: Use for SaaS-specific unit economics (CAC, LTV, churn). NOT for equipment or real estate investments.
+- **ceo-advisor**: Use for strategic direction and capital allocation across the entire business. NOT for individual investment math.

package/finance/finance-skills/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: "finance-skills"
+description: "Financial analyst agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Ratio analysis, DCF valuation, budget variance, rolling forecasts. 4 Python tools (stdlib-only)."
+version: 2.9.0
+author: Alireza Rezvani
+license: MIT
+tags:
+  - finance
+  - financial-analysis
+  - dcf
+  - valuation
+  - budgeting
+agents:
+  - claude-code
+  - codex-cli
+  - openclaw
+---
+
+# Finance Skills
+
+Production-ready financial analysis skill for strategic decision-making.
+
+## Quick Start
+
+### Claude Code
+```
+/read finance/financial-analyst/SKILL.md
+```
+
+### Codex CLI
+```bash
+npx agent-skills-cli add alirezarezvani/claude-skills/finance
+```
+
+## Skills Overview
+
+| Skill | Folder | Focus |
+|-------|--------|-------|
+| Financial Analyst | `financial-analyst/` | Ratio analysis, DCF, budget variance, forecasting |
+
+## Python Tools
+
+4 scripts, all stdlib-only:
+
+```bash
+python3 financial-analyst/scripts/ratio_calculator.py --help
+python3 financial-analyst/scripts/dcf_valuation.py --help
+python3 financial-analyst/scripts/budget_variance_analyzer.py --help
+python3 financial-analyst/scripts/forecast_builder.py --help
+```
+
+## Rules
+
+- Load only the specific skill SKILL.md you need
+- Always validate financial outputs against source data

package/finance/financial-analyst/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: "financial-analyst"
+description: Performs financial ratio analysis, DCF valuation, budget variance analysis, and rolling forecast construction for strategic decision-making. Use when analyzing financial statements, building valuation models, assessing budget variances, or constructing financial projections and forecasts. Also applicable when users mention financial modeling, cash flow analysis, company valuation, financial projections, or spreadsheet analysis.
+---
+
+# Financial Analyst Skill
+
+## Overview
+
+Production-ready financial analysis toolkit providing ratio analysis, DCF valuation, budget variance analysis, and rolling forecast construction. Designed for financial modeling, forecasting & budgeting, management reporting, business performance analysis, and investment analysis.
+
+## 5-Phase Workflow
+
+### Phase 1: Scoping
+- Define analysis objectives and stakeholder requirements
+- Identify data sources and time periods
+- Establish materiality thresholds and accuracy targets
+- Select appropriate analytical frameworks
+
+### Phase 2: Data Analysis & Modeling
+- Collect and validate financial data (income statement, balance sheet, cash flow)
+- **Validate input data completeness** before running ratio calculations (check for missing fields, nulls, or implausible values)
+- Calculate financial ratios across 5 categories (profitability, liquidity, leverage, efficiency, valuation)
+- Build DCF models with WACC and terminal value calculations; **cross-check DCF outputs against sanity bounds** (e.g., implied multiples vs. comparables)
+- Construct budget variance analyses with favorable/unfavorable classification
+- Develop driver-based forecasts with scenario modeling
+
+### Phase 3: Insight Generation
+- Interpret ratio trends and benchmark against industry standards
+- Identify material variances and root causes
+- Assess valuation ranges through sensitivity analysis
+- Evaluate forecast scenarios (base/bull/bear) for decision support
+
+### Phase 4: Reporting
+- Generate executive summaries with key findings
+- Produce detailed variance reports by department and category
+- Deliver DCF valuation reports with sensitivity tables
+- Present rolling forecasts with trend analysis
+
+### Phase 5: Follow-up
+- Track forecast accuracy (target: +/-5% revenue, +/-3% expenses)
+- Monitor report delivery timeliness (target: 100% on time)
+- Update models with actuals as they become available
+- Refine assumptions based on variance analysis
+
+## Tools
+
+### 1. Ratio Calculator (`scripts/ratio_calculator.py`)
+
+Calculate and interpret financial ratios from financial statement data.
+
+**Ratio Categories:**
+- **Profitability:** ROE, ROA, Gross Margin, Operating Margin, Net Margin
+- **Liquidity:** Current Ratio, Quick Ratio, Cash Ratio
+- **Leverage:** Debt-to-Equity, Interest Coverage, DSCR
+- **Efficiency:** Asset Turnover, Inventory Turnover, Receivables Turnover, DSO
+- **Valuation:** P/E, P/B, P/S, EV/EBITDA, PEG Ratio
+
+```bash
+python scripts/ratio_calculator.py sample_financial_data.json
+python scripts/ratio_calculator.py sample_financial_data.json --format json
+python scripts/ratio_calculator.py sample_financial_data.json --category profitability
+```
+
+### 2. DCF Valuation (`scripts/dcf_valuation.py`)
+
+Discounted Cash Flow enterprise and equity valuation with sensitivity analysis.
+
+**Features:**
+- WACC calculation via CAPM
+- Revenue and free cash flow projections (5-year default)
+- Terminal value via perpetuity growth and exit multiple methods
+- Enterprise value and equity value derivation
+- Two-way sensitivity analysis (discount rate vs growth rate)
+
+```bash
+python scripts/dcf_valuation.py valuation_data.json
+python scripts/dcf_valuation.py valuation_data.json --format json
+python scripts/dcf_valuation.py valuation_data.json --projection-years 7
+```
+
+### 3. Budget Variance Analyzer (`scripts/budget_variance_analyzer.py`)
+
+Analyze actual vs budget vs prior year performance with materiality filtering.
+
+**Features:**
+- Dollar and percentage variance calculation
+- Materiality threshold filtering (default: 10% or $50K)
+- Favorable/unfavorable classification with revenue/expense logic
+- Department and category breakdown
+- Executive summary generation
+
+```bash
+python scripts/budget_variance_analyzer.py budget_data.json
+python scripts/budget_variance_analyzer.py budget_data.json --format json
+python scripts/budget_variance_analyzer.py budget_data.json --threshold-pct 5 --threshold-amt 25000
+```
+
+### 4. Forecast Builder (`scripts/forecast_builder.py`)
+
+Driver-based revenue forecasting with rolling cash flow projection and scenario modeling.
+
+**Features:**
+- Driver-based revenue forecast model
+- 13-week rolling cash flow projection
+- Scenario modeling (base/bull/bear cases)
+- Trend analysis using simple linear regression (standard library)
+
+```bash
+python scripts/forecast_builder.py forecast_data.json
+python scripts/forecast_builder.py forecast_data.json --format json
+python scripts/forecast_builder.py forecast_data.json --scenarios base,bull,bear
+```
+
+## Knowledge Bases
+
+| Reference | Purpose |
+|-----------|---------|
+| `references/financial-ratios-guide.md` | Ratio formulas, interpretation, industry benchmarks |
+| `references/valuation-methodology.md` | DCF methodology, WACC, terminal value, comps |
+| `references/forecasting-best-practices.md` | Driver-based forecasting, rolling forecasts, accuracy |
+| `references/industry-adaptations.md` | Sector-specific metrics and considerations (SaaS, Retail, Manufacturing, Financial Services, Healthcare) |
+
+## Templates
+
+| Template | Purpose |
+|----------|---------|
+| `assets/variance_report_template.md` | Budget variance report template |
+| `assets/dcf_analysis_template.md` | DCF valuation analysis template |
+| `assets/forecast_report_template.md` | Revenue forecast report template |
+
+## Key Metrics & Targets
+
+| Metric | Target |
+|--------|--------|
+| Forecast accuracy (revenue) | +/-5% |
+| Forecast accuracy (expenses) | +/-3% |
+| Report delivery | 100% on time |
+| Model documentation | Complete for all assumptions |
+| Variance explanation | 100% of material variances |
+
+## Input Data Format
+
+All scripts accept JSON input files. See `assets/sample_financial_data.json` for the complete input schema covering all four tools.
+
+## Dependencies
+
+**None** - All scripts use Python standard library only (`math`, `statistics`, `json`, `argparse`, `datetime`). No numpy, pandas, or scipy required.

package/finance/saas-metrics-coach/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: saas-metrics-coach
+description: SaaS financial health advisor. Use when a user shares revenue or customer numbers, or mentions ARR, MRR, churn, LTV, CAC, NRR, or asks how their SaaS business is doing.
+license: MIT
+metadata:
+  version: 1.0.0
+  author: Abbas Mir
+  category: finance
+  updated: 2026-03-08
+---
+
+# SaaS Metrics Coach
+
+Act as a senior SaaS CFO advisor. Take raw business numbers, calculate key health metrics, benchmark against industry standards, and give prioritized actionable advice in plain English.
+
+## Step 1 — Collect Inputs
+
+If not already provided, ask for these in a single grouped request:
+
+- Revenue: current MRR, MRR last month, expansion MRR, churned MRR
+- Customers: total active, new this month, churned this month
+- Costs: sales and marketing spend, gross margin %
+
+Work with partial data. Be explicit about what is missing and what assumptions are being made.
+
+## Step 2 — Calculate Metrics
+
+Run `scripts/metrics_calculator.py` with the user's inputs. If the script is unavailable, use the formulas in `references/formulas.md`.
+
+Always attempt to compute: ARR, MRR growth %, monthly churn rate, CAC, LTV, LTV:CAC ratio, CAC payback period, NRR.
+
+**Additional Analysis Tools:**
+- Use `scripts/quick_ratio_calculator.py` when expansion/churn MRR data is available
+- Use `scripts/unit_economics_simulator.py` for forward-looking projections
+
+## Step 3 — Benchmark Each Metric
+
+Load `references/benchmarks.md`. For each metric show:
+- The calculated value
+- The relevant benchmark range for the user's segment and stage
+- A plain status label: HEALTHY / WATCH / CRITICAL
+
+Match the benchmark tier to the user's market segment (Enterprise / Mid-Market / SMB / PLG) and company stage (Early / Growth / Scale). Ask if unclear.
+
+## Step 4 — Prioritize and Recommend
+
+Identify the top 2-3 metrics at WATCH or CRITICAL status. For each one state:
+- What is happening (one sentence, plain English)
+- Why it matters to the business
+- Two or three specific actions to take this month
+
+Order by impact — address the most damaging problem first.
+
+## Step 5 — Output Format
+
+Always use this exact structure:
+
+```
+# SaaS Health Report — [Month Year]
+
+## Metrics at a Glance
+| Metric | Your Value | Benchmark | Status |
+|--------|------------|-----------|--------|
+
+## Overall Picture
+[2-3 sentences, plain English summary]
+
+## Priority Issues
+
+### 1. [Metric Name]
+What is happening: ...
+Why it matters: ...
+Fix it this month: ...
+
+### 2. [Metric Name]
+...
+
+## What is Working
+[1-2 genuine strengths, no padding]
+
+## 90-Day Focus
+[Single metric to move + specific numeric target]
+```
+
+## Examples
+
+**Example 1 — Partial data**
+
+Input: "MRR is $80k, we have 200 customers, about 3 cancel each month."
+
+Expected output: Calculates ARPA ($400), monthly churn (1.5%), ARR ($960k), LTV estimate. Flags CAC and growth rate as missing. Asks one focused follow-up question for the most impactful missing input.
+
+**Example 2 — Critical scenario**
+
+Input: "MRR $22k (was $23.5k), 80 customers, lost 9, gained 6, spent $15k on ads, 65% gross margin."
+
+Expected output: Flags negative MoM growth (-6.4%), critical churn (11.25%), and LTV:CAC of 0.64:1 as CRITICAL. Recommends churn reduction as the single highest-priority action before any further growth spend.
+
+## Key Principles
+
+- Be direct. If a metric is bad, say it is bad.
+- Explain every metric in one sentence before showing the number.
+- Cap priority issues at three. More than three paralyzes action.
+- Context changes benchmarks. Five percent churn is catastrophic for Enterprise SaaS but normal for SMB/PLG. Always confirm the user's target market before scoring.
+
+## Reference Files
+
+- `references/formulas.md` — All metric formulas with worked examples
+- `references/benchmarks.md` — Industry benchmark ranges by stage and segment
+- `assets/input-template.md` — Blank input form to share with users
+- `scripts/metrics_calculator.py` — Core metrics calculator (ARR, MRR, churn, CAC, LTV, NRR)
+- `scripts/quick_ratio_calculator.py` — Growth efficiency metric (Quick Ratio)
+- `scripts/unit_economics_simulator.py` — 12-month forward projection
+
+## Tools
+
+### 1. Metrics Calculator (`scripts/metrics_calculator.py`)
+Core SaaS metrics from raw business numbers.
+
+```bash
+# Interactive mode
+python scripts/metrics_calculator.py
+
+# CLI mode
+python scripts/metrics_calculator.py --mrr 50000 --customers 100 --churned 5 --json
+```
+
+### 2. Quick Ratio Calculator (`scripts/quick_ratio_calculator.py`)
+Growth efficiency metric: (New MRR + Expansion) / (Churned + Contraction)
+
+```bash
+python scripts/quick_ratio_calculator.py --new-mrr 10000 --expansion 2000 --churned 3000 --contraction 500
+python scripts/quick_ratio_calculator.py --new-mrr 10000 --expansion 2000 --churned 3000 --json
+```
+
+**Benchmarks:**
+- < 1.0 = CRITICAL (losing faster than gaining)
+- 1-2 = WATCH (marginal growth)
+- 2-4 = HEALTHY (good efficiency)
+- \> 4 = EXCELLENT (strong growth)
+
+### 3. Unit Economics Simulator (`scripts/unit_economics_simulator.py`)
+Project metrics forward 12 months based on growth/churn assumptions.
+
+```bash
+python scripts/unit_economics_simulator.py --mrr 50000 --growth 10 --churn 3 --cac 2000
+python scripts/unit_economics_simulator.py --mrr 50000 --growth 10 --churn 3 --cac 2000 --json
+```
+
+**Use for:**
+- "What if we grow at X% per month?"
+- Runway projections
+- Scenario planning (best/base/worst case)
+
+## Related Skills
+
+- **financial-analyst**: Use for DCF valuation, budget variance analysis, and traditional financial modeling. NOT for SaaS-specific metrics like CAC, LTV, or churn.
+- **business-growth/customer-success**: Use for retention strategies and customer health scoring. Complements this skill when churn is flagged as CRITICAL.