# Claude Skills — Aider Conventions > Auto-generated from claude-skills. Do not edit manually. > Generated: 2026-06-07 --- ## business-growth-skills > 4 business growth agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Customer success (health scoring, churn), sales engineer (RFP), revenue operations (pipeline, GTM), contract & proposal writer. Python tools (stdlib-only). # Business & Growth Skills 4 production-ready skills for customer success, sales, and revenue operations. ## Quick Start ### Claude Code ``` /read business-growth/customer-success-manager/SKILL.md ``` ### Codex CLI ```bash npx agent-skills-cli add alirezarezvani/claude-skills/business-growth ``` ## Skills Overview | Skill | Folder | Focus | |-------|--------|-------| | Customer Success Manager | `customer-success-manager/` | Health scoring, churn prediction, expansion | | Sales Engineer | `sales-engineer/` | RFP analysis, competitive matrices, PoC planning | | Revenue Operations | `revenue-operations/` | Pipeline analysis, forecast accuracy, GTM metrics | | Contract & Proposal Writer | `contract-and-proposal-writer/` | Proposal generation, contract templates | ## Python Tools 9 scripts, all stdlib-only: ```bash python3 customer-success-manager/scripts/health_score_calculator.py --help python3 revenue-operations/scripts/pipeline_analyzer.py --help ``` ## Rules - Load only the specific skill SKILL.md you need - Use Python tools for scoring and metrics, not manual estimates --- ## contract-and-proposal-writer > Generate professional, jurisdiction-aware business documents: freelance contracts, project proposals, SOWs, NDAs, and MSAs. Structured Markdown output with docx conversion instructions. Covers US (Delaware), EU (GDPR), UK, and DACH (German law) jurisdictions. Not a substitute for legal counsel — use as strong starting points. Use when drafting a freelance contract, preparing a client proposal, writing an SOW for a new engagement, or producing an NDA before sharing sensitive material. # Contract & Proposal Writer **Tier:** POWERFUL **Category:** Business Growth **Domain:** Legal Documents, Business Development, Client Relations --- ## Overview Generate professional, jurisdiction-aware business documents: freelance contracts, project proposals, SOWs, NDAs, and MSAs. Outputs structured Markdown with docx conversion instructions. Covers US (Delaware), EU (GDPR), UK, and DACH (German law) jurisdictions. **Not a substitute for legal counsel.** Use these templates as strong starting points; review with an attorney for high-value or complex engagements. --- ## Core Capabilities - Freelance development contracts (fixed-price & hourly) - Project proposals with timeline/budget breakdown - Statements of Work (SOW) with deliverables matrix - NDAs (mutual & one-way) - Master Service Agreements (MSA) - Jurisdiction-specific clauses (US/EU/UK/DACH) - GDPR Data Processing Addenda (EU/DACH) --- ## Key Clauses Reference | Clause | Options | |--------|---------| | Payment terms | Net-30, milestone-based, monthly retainer | | IP ownership | Work-for-hire (US), assignment (EU/UK), license-back | | Liability cap | 1x contract value (standard), 3x (high-risk) | | Termination | For cause (14-day cure), convenience (30/60/90-day notice) | | Confidentiality | 2-5 year term, perpetual for trade secrets | | Warranty | "As-is" disclaimer, limited 30/90-day fix warranty | | Dispute resolution | Arbitration (AAA/ICC), courts (jurisdiction-specific) | --- ## When to Use - Starting a new client engagement and need a contract fast - Client asks for a proposal with pricing and timeline - Partnership or vendor relationship requiring an MSA - Protecting IP or confidential information with an NDA - EU/DACH project requiring GDPR-compliant data clauses --- ## Workflow ### 1. Gather Requirements Ask the user: 1. Document type? (contract / proposal / SOW / NDA / MSA) 2. Jurisdiction? (US-Delaware / EU / UK / DACH) 3. Engagement type? (fixed-price / hourly / retainer) 4. Parties? (names, roles, business addresses) 5. Scope summary? (1-3 sentences) 6. Total value or hourly rate? 7. Start date / end date or duration? 8. Special requirements? (IP assignment, white-label, subcontractors) ### 2. Select Template | Type | Jurisdiction | Template | |------|-------------|----------| | Dev contract fixed | Any | Template A | | Consulting retainer | Any | Template B | | SaaS partnership | Any | Template C | | NDA mutual | US/EU/UK/DACH | NDA-M | | NDA one-way | US/EU/UK/DACH | NDA-OW | | SOW | Any | SOW base | ### 3. Generate & Fill Fill all [BRACKETED] placeholders. Flag missing data as "REQUIRED". ### 4. Convert to DOCX ```bash # Install pandoc brew install pandoc # macOS apt install pandoc # Ubuntu # Basic conversion pandoc contract.md -o contract.docx \ --reference-doc=reference.docx \ -V geometry:margin=1in # With numbered sections (legal style) pandoc contract.md -o contract.docx \ --number-sections \ -V documentclass=article \ -V fontsize=11pt # With custom company template pandoc contract.md -o contract.docx \ --reference-doc=company-template.docx ``` --- ## Jurisdiction Notes ### US (Delaware) - Governing law: State of Delaware - Work-for-hire doctrine applies (Copyright Act 101) - Arbitration: AAA Commercial Rules - Non-compete: enforceable with reasonable scope/time ### EU (GDPR) - Must include Data Processing Addendum if handling personal data - IP assignment requires separate written deed in some member states - Arbitration: ICC or local chamber ### UK (post-Brexit) - Governed by English law - IP: Patents Act 1977 / CDPA 1988 - Arbitration: LCIA Rules - Data: UK GDPR (post-Brexit equivalent) ### DACH (Germany / Austria / Switzerland) - BGB (Buergerliches Gesetzbuch) governs contracts - Written form requirement for certain clauses (para 126 BGB) - IP: Author always retains moral rights; must explicitly transfer Nutzungsrechte - Non-competes: max 2 years, compensation required (para 74 HGB) - Jurisdiction: German courts (Landgericht) or DIS arbitration - DSGVO (GDPR implementation) mandatory for personal data processing - Kuendigungsfristen: statutory notice periods apply --- ## Template A: Web Dev Fixed-Price Contract ```markdown # SOFTWARE DEVELOPMENT AGREEMENT **Effective Date:** [DATE] **Client:** [CLIENT LEGAL NAME], [ADDRESS] ("Client") **Developer:** [YOUR LEGAL NAME / COMPANY], [ADDRESS] ("Developer") --- ## 1. SERVICES Developer agrees to design, develop, and deliver: **Project:** [PROJECT NAME] **Description:** [1-3 sentence scope] **Deliverables:** - [Deliverable 1] due [DATE] - [Deliverable 2] due [DATE] - [Deliverable 3] due [DATE] ## 2. PAYMENT **Total Fee:** [CURRENCY] [AMOUNT] | Milestone | Amount | Due | |-----------|--------|-----| | Contract signing | 50% | Upon execution | | Beta delivery | 25% | [DATE] | | Final acceptance | 25% | Within 5 days of acceptance | Late payments accrue interest at 1.5% per month. Client has [10] business days to accept or reject deliverables in writing. ## 3. INTELLECTUAL PROPERTY Upon receipt of full payment, Developer assigns all right, title, and interest in the Work Product to Client as a work made for hire (US) / by assignment of future copyright (EU/UK). Developer retains the right to display Work Product in portfolio unless Client requests confidentiality in writing within [30] days of delivery. Pre-existing IP (tools, libraries, frameworks) remains Developer's property. Developer grants Client a perpetual, royalty-free license to use pre-existing IP as embedded in the Work Product. ## 4. CONFIDENTIALITY Each party keeps confidential all non-public information received from the other. This obligation survives termination for [3] years. ## 5. WARRANTIES Developer warrants Work Product will substantially conform to specifications for [90] days post-delivery. Developer will fix material defects at no charge during this period. EXCEPT AS STATED, WORK PRODUCT IS PROVIDED "AS IS." ## 6. LIABILITY Developer's total liability shall not exceed total fees paid under this Agreement. Neither party liable for indirect, incidental, or consequential damages. ## 7. TERMINATION For Cause: Either party may terminate if the other materially breaches and fails to cure within [14] days of written notice. For Convenience: Client may terminate with [30] days written notice and pay for all work completed plus [10%] of remaining contract value. ## 8. DISPUTE RESOLUTION US: Binding arbitration under AAA Commercial Rules, [CITY], Delaware law. EU/DACH: ICC / DIS arbitration, [CITY]. German / English law. UK: LCIA Rules, London. English law. ## 9. GENERAL - Entire Agreement: Supersedes all prior discussions. - Amendments: Must be in writing, signed by both parties. - Independent Contractor: Developer is not an employee of Client. --- CLIENT: _________________________ Date: _________ [CLIENT NAME], [TITLE] DEVELOPER: _________________________ Date: _________ [YOUR NAME], [TITLE] ``` --- ## Template B: Monthly Consulting Retainer ```markdown # CONSULTING RETAINER AGREEMENT **Effective Date:** [DATE] **Client:** [CLIENT LEGAL NAME] ("Client") **Consultant:** [YOUR NAME / COMPANY] ("Consultant") --- ## 1. SERVICES Consultant provides [DOMAIN, e.g., "CTO advisory and technical architecture"] services. **Monthly Hours:** Up to [X] hours/month **Rollover:** Unused hours [do / do not] roll over (max [X] hours banked) **Overflow Rate:** [CURRENCY] [RATE]/hr for hours exceeding retainer ## 2. FEES **Monthly Retainer:** [CURRENCY] [AMOUNT], due on the 1st of each month. **Payment Method:** Bank transfer / Stripe / SEPA direct debit **Late Payment:** 2% monthly interest after [10]-day grace period. ## 3. TERM AND TERMINATION **Initial Term:** [3] months starting [DATE] **Renewal:** Auto-renews monthly unless either party gives [30] days written notice. **Immediate termination:** For material breach uncured after [7] days notice. On termination, Consultant delivers all work in progress within [5] business days. ## 4. INTELLECTUAL PROPERTY Work product created under this Agreement belongs to [Client / Consultant / jointly]. Advisory output (recommendations, analyses) are Client property upon full payment. ## 5. EXCLUSIVITY [OPTION A - Non-exclusive:] This Agreement is non-exclusive. Consultant may work with other clients. [OPTION B - Partial exclusivity:] Consultant will not work with direct competitors of Client during the term and [90] days thereafter. ## 6. CONFIDENTIALITY AND DATA PROTECTION EU/DACH: If Consultant processes personal data on behalf of Client, the parties shall execute a Data Processing Agreement (DPA) per Art. 28 GDPR. ## 7. LIABILITY Consultant's aggregate liability is capped at [3x] the fees paid in the [3] months preceding the claim. --- Signatures as above. ``` --- ## Template C: SaaS Partnership Agreement ```markdown # SAAS PARTNERSHIP AGREEMENT **Effective Date:** [DATE] **Provider:** [NAME], [ADDRESS] **Partner:** [NAME], [ADDRESS] --- ## 1. PURPOSE Provider grants Partner [reseller / referral / white-label / integration] rights to Provider's [PRODUCT NAME] ("Software") subject to this Agreement. ## 2. PARTNERSHIP TYPE [ ] Referral: Partner refers customers; earns [X%] of first-year ARR per referral. [ ] Reseller: Partner resells licenses; earns [X%] discount off list price. [ ] White-label: Partner rebrands Software; pays [AMOUNT]/month platform fee. [ ] Integration: Partner integrates Software via API; terms in Exhibit A. ## 3. REVENUE SHARE | Tier | Monthly ARR Referred | Commission | |------|---------------------|------------| | Bronze | < $10,000 | [X]% | | Silver | $10,000-$50,000 | [X]% | | Gold | > $50,000 | [X]% | Payout: Net-30 after month close, minimum $[500] threshold. ## 4. INTELLECTUAL PROPERTY Each party retains all IP in its own products. No implied licenses. Partner may use Provider's marks per Provider's Brand Guidelines (Exhibit B). ## 5. DATA AND PRIVACY Each party is an independent data controller for its own customers. Joint processing requires a separate DPA (Exhibit C - EU/DACH projects). ## 6. TERM Initial: [12] months. Renews annually unless [90]-day written notice given. Termination for Cause: [30]-day cure period for material breach. ## 7. LIMITATION OF LIABILITY Each party's liability capped at [1x] fees paid/received in prior [12] months. Mutual indemnification for IP infringement claims from own products. --- Signatures, exhibits, and governing law per applicable jurisdiction. ``` --- ## GDPR Data Processing Addendum (EU/DACH Clause Block) ```markdown ## DATA PROCESSING ADDENDUM (Art. 28 GDPR) Controller: [CLIENT NAME] Processor: [CONTRACTOR NAME] ### Subject Matter Processor processes personal data on behalf of Controller solely to perform services under the main Agreement. ### Categories of Data Subjects [e.g., end users, employees, customers] ### Categories of Personal Data [e.g., names, email addresses, usage data] ### Processing Duration For the term of the main Agreement; deletion within [30] days of termination. ### Processor Obligations - Process data only on Controller's documented instructions - Ensure persons authorized to process have committed to confidentiality - Implement technical and organizational measures per Art. 32 GDPR - Assist Controller with data subject rights requests - Not engage sub-processors without prior written consent - Delete or return all personal data upon termination ### Sub-processors (current as of Effective Date) | Sub-processor | Location | Purpose | |--------------|----------|---------| | [AWS / GCP / Azure] | [Region] | Cloud hosting | | [Other] | [Location] | [Purpose] | ### Cross-border Transfers Data transfers outside EEA covered by: [ ] SCCs [ ] Adequacy Decision [ ] BCRs ``` --- ## Common Pitfalls 1. **Missing IP assignment language** - "work for hire" alone is insufficient in EU; need explicit assignment of Nutzungsrechte in DACH 2. **Vague acceptance criteria** - Always define what "accepted" means (written sign-off, X days to reject) 3. **No change order process** - Scope creep kills fixed-price projects; add a clause for out-of-scope work 4. **Jurisdiction mismatch** - Choosing Delaware law for a German-only project creates enforcement problems 5. **Missing limitation of liability** - Without a cap, one bug could mean unlimited damages 6. **Oral amendments** - Contracts modified verbally are hard to enforce; always require written amendments --- ## Best Practices - Use **milestone payments** over net-30 for projects >$10K - reduces cash flow risk - For EU/DACH: always check if a DPA is needed (any personal data = yes) - For DACH: include a **Schriftformklausel** (written form clause) explicitly - Add a **force majeure** clause for anything over 3 months - For retainers: define response time SLAs (e.g., 4h urgent / 24h normal) - Keep templates in version control; track changes with `git diff` - Review annually - laws change, especially GDPR enforcement interpretations - For NDAs: always specify the return/destruction of confidential materials on termination --- ## customer-success-manager > Monitors customer health, predicts churn risk, and identifies expansion opportunities using weighted scoring models for SaaS customer success. Use when analyzing customer accounts, reviewing retention metrics, scoring at-risk customers, or when the user mentions churn, customer health scores, upsell opportunities, expansion revenue, retention analysis, or customer analytics. Runs three Python CLI tools to produce deterministic health scores, churn risk tiers, and prioritized expansion recommendations across Enterprise, Mid-Market, and SMB segments. # Customer Success Manager Production-grade customer success analytics with multi-dimensional health scoring, churn risk prediction, and expansion opportunity identification. Three Python CLI tools provide deterministic, repeatable analysis using standard library only -- no external dependencies, no API calls, no ML models. --- ## Table of Contents - [Input Requirements](#input-requirements) - [Output Formats](#output-formats) - [How to Use](#how-to-use) - [Scripts](#scripts) - [Reference Guides](#reference-guides) - [Templates](#templates) - [Best Practices](#best-practices) - [Limitations](#limitations) --- ## Input Requirements All scripts accept a JSON file as positional input argument. See `assets/sample_customer_data.json` for complete schema examples and sample data. ### Health Score Calculator Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, and nested objects `usage` (login_frequency, feature_adoption, dau_mau_ratio), `engagement` (support_ticket_volume, meeting_attendance, nps_score, csat_score), `support` (open_tickets, escalation_rate, avg_resolution_hours), `relationship` (executive_sponsor_engagement, multi_threading_depth, renewal_sentiment), and `previous_period` scores for trend analysis. ### Churn Risk Analyzer Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, `contract_end_date`, and nested objects `usage_decline`, `engagement_drop`, `support_issues`, `relationship_signals`, and `commercial_factors`. ### Expansion Opportunity Scorer Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, and nested objects `contract` (licensed_seats, active_seats, plan_tier, available_tiers), `product_usage` (per-module adoption flags and usage percentages), and `departments` (current and potential). --- ## Output Formats All scripts support two output formats via the `--format` flag: - **`text`** (default): Human-readable formatted output for terminal viewing - **`json`**: Machine-readable JSON output for integrations and pipelines --- ## How to Use ### Quick Start ```bash # Health scoring python scripts/health_score_calculator.py assets/sample_customer_data.json python scripts/health_score_calculator.py assets/sample_customer_data.json --format json # Churn risk analysis python scripts/churn_risk_analyzer.py assets/sample_customer_data.json python scripts/churn_risk_analyzer.py assets/sample_customer_data.json --format json # Expansion opportunity scoring python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json --format json ``` ### Workflow Integration ```bash # 1. Score customer health across portfolio python scripts/health_score_calculator.py customer_portfolio.json --format json > health_results.json # Verify: confirm health_results.json contains the expected number of customer records before continuing # 2. Identify at-risk accounts python scripts/churn_risk_analyzer.py customer_portfolio.json --format json > risk_results.json # Verify: confirm risk_results.json is non-empty and risk tiers are present for each customer # 3. Find expansion opportunities in healthy accounts python scripts/expansion_opportunity_scorer.py customer_portfolio.json --format json > expansion_results.json # Verify: confirm expansion_results.json lists opportunities ranked by priority # 4. Prepare QBR using templates # Reference: assets/qbr_template.md ``` **Error handling:** If a script exits with an error, check that: - The input JSON matches the required schema for that script (see Input Requirements above) - All required fields are present and correctly typed - Python 3.7+ is being used (`python --version`) - Output files from prior steps are non-empty before piping into subsequent steps --- ## Scripts ### 1. health_score_calculator.py **Purpose:** Multi-dimensional customer health scoring with trend analysis and segment-aware benchmarking. **Dimensions and Weights:** | Dimension | Weight | Metrics | |-----------|--------|---------| | Usage | 30% | Login frequency, feature adoption, DAU/MAU ratio | | Engagement | 25% | Support ticket volume, meeting attendance, NPS/CSAT | | Support | 20% | Open tickets, escalation rate, avg resolution time | | Relationship | 25% | Executive sponsor engagement, multi-threading depth, renewal sentiment | **Classification:** - Green (75-100): Healthy -- customer achieving value - Yellow (50-74): Needs attention -- monitor closely - Red (0-49): At risk -- immediate intervention required **Usage:** ```bash python scripts/health_score_calculator.py customer_data.json python scripts/health_score_calculator.py customer_data.json --format json ``` ### 2. churn_risk_analyzer.py **Purpose:** Identify at-risk accounts with behavioral signal detection and tier-based intervention recommendations. **Risk Signal Weights:** | Signal Category | Weight | Indicators | |----------------|--------|------------| | Usage Decline | 30% | Login trend, feature adoption change, DAU/MAU change | | Engagement Drop | 25% | Meeting cancellations, response time, NPS change | | Support Issues | 20% | Open escalations, unresolved critical, satisfaction trend | | Relationship Signals | 15% | Champion left, sponsor change, competitor mentions | | Commercial Factors | 10% | Contract type, pricing complaints, budget cuts | **Risk Tiers:** - Critical (80-100): Immediate executive escalation - High (60-79): Urgent CSM intervention - Medium (40-59): Proactive outreach - Low (0-39): Standard monitoring **Usage:** ```bash python scripts/churn_risk_analyzer.py customer_data.json python scripts/churn_risk_analyzer.py customer_data.json --format json ``` ### 3. expansion_opportunity_scorer.py **Purpose:** Identify upsell, cross-sell, and expansion opportunities with revenue estimation and priority ranking. **Expansion Types:** - **Upsell**: Upgrade to higher tier or more of existing product - **Cross-sell**: Add new product modules - **Expansion**: Additional seats or departments **Usage:** ```bash python scripts/expansion_opportunity_scorer.py customer_data.json python scripts/expansion_opportunity_scorer.py customer_data.json --format json ``` --- ## Reference Guides | Reference | Description | |-----------|-------------| | `references/health-scoring-framework.md` | Complete health scoring methodology, dimension definitions, weighting rationale, threshold calibration | | `references/cs-playbooks.md` | Intervention playbooks for each risk tier, onboarding, renewal, expansion, and escalation procedures | | `references/cs-metrics-benchmarks.md` | Industry benchmarks for NRR, GRR, churn rates, health scores, expansion rates by segment and industry | --- ## Templates | Template | Purpose | |----------|---------| | `assets/qbr_template.md` | Quarterly Business Review presentation structure | | `assets/success_plan_template.md` | Customer success plan with goals, milestones, and metrics | | `assets/onboarding_checklist_template.md` | 90-day onboarding checklist with phase gates | | `assets/executive_business_review_template.md` | Executive stakeholder review for strategic accounts | --- ## Best Practices 1. **Combine signals**: Use all three scripts together for a complete customer picture 2. **Act on trends, not snapshots**: A declining Green is more urgent than a stable Yellow 3. **Calibrate thresholds**: Adjust segment benchmarks based on your product and industry per `references/health-scoring-framework.md` 4. **Prepare with data**: Run scripts before every QBR and executive meeting; reference `references/cs-playbooks.md` for intervention guidance --- ## Limitations - **No real-time data**: Scripts analyze point-in-time snapshots from JSON input files - **No CRM integration**: Data must be exported manually from your CRM/CS platform - **Deterministic only**: No predictive ML -- scoring is algorithmic based on weighted signals - **Threshold tuning**: Default thresholds are industry-standard but may need calibration for your business - **Revenue estimates**: Expansion revenue estimates are approximations based on usage patterns --- **Last Updated:** February 2026 **Tools:** 3 Python CLI tools **Dependencies:** Python 3.7+ standard library only --- ## revenue-operations > Analyzes sales pipeline health, revenue forecasting accuracy, and go-to-market efficiency metrics for SaaS revenue optimization. Use when analyzing sales pipeline coverage, forecasting revenue, evaluating go-to-market performance, reviewing sales metrics, assessing pipeline analysis, tracking forecast accuracy with MAPE, calculating GTM efficiency, or measuring sales efficiency and unit economics for SaaS teams. # Revenue Operations Pipeline analysis, forecast accuracy tracking, and GTM efficiency measurement for SaaS revenue teams. > **Output formats:** All scripts support `--format text` (human-readable) and `--format json` (dashboards/integrations). --- ## Quick Start ```bash # Analyze pipeline health and coverage python scripts/pipeline_analyzer.py --input assets/sample_pipeline_data.json --format text # Track forecast accuracy over multiple periods python scripts/forecast_accuracy_tracker.py assets/sample_forecast_data.json --format text # Calculate GTM efficiency metrics python scripts/gtm_efficiency_calculator.py assets/sample_gtm_data.json --format text ``` --- ## Tools Overview ### 1. Pipeline Analyzer Analyzes sales pipeline health including coverage ratios, stage conversion rates, deal velocity, aging risks, and concentration risks. **Input:** JSON file with deals, quota, and stage configuration **Output:** Coverage ratios, conversion rates, velocity metrics, aging flags, risk assessment **Usage:** ```bash python scripts/pipeline_analyzer.py --input pipeline.json --format text ``` **Key Metrics Calculated:** - **Pipeline Coverage Ratio** -- Total pipeline value / quota target (healthy: 3-4x) - **Stage Conversion Rates** -- Stage-to-stage progression rates - **Sales Velocity** -- (Opportunities x Avg Deal Size x Win Rate) / Avg Sales Cycle - **Deal Aging** -- Flags deals exceeding 2x average cycle time per stage - **Concentration Risk** -- Warns when >40% of pipeline is in a single deal - **Coverage Gap Analysis** -- Identifies quarters with insufficient pipeline **Input Schema:** ```json { "quota": 500000, "stages": ["Discovery", "Qualification", "Proposal", "Negotiation", "Closed Won"], "average_cycle_days": 45, "deals": [ { "id": "D001", "name": "Acme Corp", "stage": "Proposal", "value": 85000, "age_days": 32, "close_date": "2025-03-15", "owner": "rep_1" } ] } ``` ### 2. Forecast Accuracy Tracker Tracks forecast accuracy over time using MAPE, detects systematic bias, analyzes trends, and provides category-level breakdowns. **Input:** JSON file with forecast periods and optional category breakdowns **Output:** MAPE score, bias analysis, trends, category breakdown, accuracy rating **Usage:** ```bash python scripts/forecast_accuracy_tracker.py forecast_data.json --format text ``` **Key Metrics Calculated:** - **MAPE** -- mean(|actual - forecast| / |actual|) x 100 - **Forecast Bias** -- Over-forecasting (positive) vs under-forecasting (negative) tendency - **Weighted Accuracy** -- MAPE weighted by deal value for materiality - **Period Trends** -- Improving, stable, or declining accuracy over time - **Category Breakdown** -- Accuracy by rep, product, segment, or any custom dimension **Accuracy Ratings:** | Rating | MAPE Range | Interpretation | |--------|-----------|----------------| | Excellent | <10% | Highly predictable, data-driven process | | Good | 10-15% | Reliable forecasting with minor variance | | Fair | 15-25% | Needs process improvement | | Poor | >25% | Significant forecasting methodology gaps | **Input Schema:** ```json { "forecast_periods": [ {"period": "2025-Q1", "forecast": 480000, "actual": 520000}, {"period": "2025-Q2", "forecast": 550000, "actual": 510000} ], "category_breakdowns": { "by_rep": [ {"category": "Rep A", "forecast": 200000, "actual": 210000}, {"category": "Rep B", "forecast": 280000, "actual": 310000} ] } } ``` ### 3. GTM Efficiency Calculator Calculates core SaaS GTM efficiency metrics with industry benchmarking, ratings, and improvement recommendations. **Input:** JSON file with revenue, cost, and customer metrics **Output:** Magic Number, LTV:CAC, CAC Payback, Burn Multiple, Rule of 40, NDR with ratings **Usage:** ```bash python scripts/gtm_efficiency_calculator.py gtm_data.json --format text ``` **Key Metrics Calculated:** | Metric | Formula | Target | |--------|---------|--------| | Magic Number | Net New ARR / Prior Period S&M Spend | >0.75 | | LTV:CAC | (ARPA x Gross Margin / Churn Rate) / CAC | >3:1 | | CAC Payback | CAC / (ARPA x Gross Margin) months | <18 months | | Burn Multiple | Net Burn / Net New ARR | <2x | | Rule of 40 | Revenue Growth % + FCF Margin % | >40% | | Net Dollar Retention | (Begin ARR + Expansion - Contraction - Churn) / Begin ARR | >110% | **Input Schema:** ```json { "revenue": { "current_arr": 5000000, "prior_arr": 3800000, "net_new_arr": 1200000, "arpa_monthly": 2500, "revenue_growth_pct": 31.6 }, "costs": { "sales_marketing_spend": 1800000, "cac": 18000, "gross_margin_pct": 78, "total_operating_expense": 6500000, "net_burn": 1500000, "fcf_margin_pct": 8.4 }, "customers": { "beginning_arr": 3800000, "expansion_arr": 600000, "contraction_arr": 100000, "churned_arr": 300000, "annual_churn_rate_pct": 8 } } ``` --- ## Revenue Operations Workflows ### Weekly Pipeline Review Use this workflow for your weekly pipeline inspection cadence. 1. **Verify input data:** Confirm pipeline export is current and all required fields (stage, value, close_date, owner) are populated before proceeding. 2. **Generate pipeline report:** ```bash python scripts/pipeline_analyzer.py --input current_pipeline.json --format text ``` 3. **Cross-check output totals** against your CRM source system to confirm data integrity. 4. **Review key indicators:** - Pipeline coverage ratio (is it above 3x quota?) - Deals aging beyond threshold (which deals need intervention?) - Concentration risk (are we over-reliant on a few large deals?) - Stage distribution (is there a healthy funnel shape?) 5. **Document using template:** Use `assets/pipeline_review_template.md` 6. **Action items:** Address aging deals, redistribute pipeline concentration, fill coverage gaps ### Forecast Accuracy Review Use monthly or quarterly to evaluate and improve forecasting discipline. 1. **Verify input data:** Confirm all forecast periods have corresponding actuals and no periods are missing before running. 2. **Generate accuracy report:** ```bash python scripts/forecast_accuracy_tracker.py forecast_history.json --format text ``` 3. **Cross-check actuals** against closed-won records in your CRM before drawing conclusions. 4. **Analyze patterns:** - Is MAPE trending down (improving)? - Which reps or segments have the highest error rates? - Is there systematic over- or under-forecasting? 5. **Document using template:** Use `assets/forecast_report_template.md` 6. **Improvement actions:** Coach high-bias reps, adjust methodology, improve data hygiene ### GTM Efficiency Audit Use quarterly or during board prep to evaluate go-to-market efficiency. 1. **Verify input data:** Confirm revenue, cost, and customer figures reconcile with finance records before running. 2. **Calculate efficiency metrics:** ```bash python scripts/gtm_efficiency_calculator.py quarterly_data.json --format text ``` 3. **Cross-check computed ARR and spend totals** against your finance system before sharing results. 4. **Benchmark against targets:** - Magic Number (>0.75) - LTV:CAC (>3:1) - CAC Payback (<18 months) - Rule of 40 (>40%) 5. **Document using template:** Use `assets/gtm_dashboard_template.md` 6. **Strategic decisions:** Adjust spend allocation, optimize channels, improve retention ### Quarterly Business Review Combine all three tools for a comprehensive QBR analysis. 1. Run pipeline analyzer for forward-looking coverage 2. Run forecast tracker for backward-looking accuracy 3. Run GTM calculator for efficiency benchmarks 4. Cross-reference pipeline health with forecast accuracy 5. Align GTM efficiency metrics with growth targets --- ## Reference Documentation | Reference | Description | |-----------|-------------| | [RevOps Metrics Guide](references/revops-metrics-guide.md) | Complete metrics hierarchy, definitions, formulas, and interpretation | | [Pipeline Management Framework](references/pipeline-management-framework.md) | Pipeline best practices, stage definitions, conversion benchmarks | | [GTM Efficiency Benchmarks](references/gtm-efficiency-benchmarks.md) | SaaS benchmarks by stage, industry standards, improvement strategies | --- ## Templates | Template | Use Case | |----------|----------| | [Pipeline Review Template](assets/pipeline_review_template.md) | Weekly/monthly pipeline inspection documentation | | [Forecast Report Template](assets/forecast_report_template.md) | Forecast accuracy reporting and trend analysis | | [GTM Dashboard Template](assets/gtm_dashboard_template.md) | GTM efficiency dashboard for leadership review | | [Sample Pipeline Data](assets/sample_pipeline_data.json) | Example input for pipeline_analyzer.py | | [Expected Output](assets/expected_output.json) | Reference output from pipeline_analyzer.py | --- ## sales-engineer > Analyzes RFP/RFI responses for coverage gaps, builds competitive feature comparison matrices, and plans proof-of-concept (POC) engagements for pre-sales engineering. Use when responding to RFPs, bids, or proposal requests; comparing product features against competitors; planning or scoring a customer POC or sales demo; preparing a technical proposal; or performing win/loss competitor analysis. Handles tasks described as 'RFP response', 'bid response', 'proposal response', 'competitor comparison', 'feature matrix', 'POC planning', 'sales demo prep', or 'pre-sales engineering'. # Sales Engineer Skill ## 5-Phase Workflow ### Phase 1: Discovery & Research **Objective:** Understand customer requirements, technical environment, and business drivers. **Checklist:** - [ ] Conduct technical discovery calls with stakeholders - [ ] Map customer's current architecture and pain points - [ ] Identify integration requirements and constraints - [ ] Document security and compliance requirements - [ ] Assess competitive landscape for this opportunity **Tools:** Run `rfp_response_analyzer.py` to score initial requirement alignment. ```bash python scripts/rfp_response_analyzer.py assets/sample_rfp_data.json --format json > phase1_rfp_results.json ``` **Output:** Technical discovery document, requirement map, initial coverage assessment. **Validation checkpoint:** Coverage score must be >50% and must-have gaps ≤3 before proceeding to Phase 2. Check with: ```bash python scripts/rfp_response_analyzer.py assets/sample_rfp_data.json --format json | python -c "import sys,json; r=json.load(sys.stdin); print('PROCEED' if r['coverage_score']>50 and r['must_have_gaps']<=3 else 'REVIEW')" ``` --- ### Phase 2: Solution Design **Objective:** Design a solution architecture that addresses customer requirements. **Checklist:** - [ ] Map product capabilities to customer requirements - [ ] Design integration architecture - [ ] Identify customization needs and development effort - [ ] Build competitive differentiation strategy - [ ] Create solution architecture diagrams **Tools:** Run `competitive_matrix_builder.py` using Phase 1 data to identify differentiators and vulnerabilities. ```bash python scripts/competitive_matrix_builder.py competitive_data.json --format json > phase2_competitive.json python -c "import json; d=json.load(open('phase2_competitive.json')); print('Differentiators:', d['differentiators']); print('Vulnerabilities:', d['vulnerabilities'])" ``` **Output:** Solution architecture, competitive positioning, technical differentiation strategy. **Validation checkpoint:** Confirm at least one strong differentiator exists per customer priority before proceeding to Phase 3. If no differentiators found, escalate to Product Team (see Integration Points). --- ### Phase 3: Demo Preparation & Delivery **Objective:** Deliver compelling technical demonstrations tailored to stakeholder priorities. **Checklist:** - [ ] Build demo environment matching customer's use case - [ ] Create demo script with talking points per stakeholder role - [ ] Prepare objection handling responses - [ ] Rehearse failure scenarios and recovery paths - [ ] Collect feedback and adjust approach **Templates:** Use `assets/demo_script_template.md` for structured demo preparation. **Output:** Customized demo, stakeholder-specific talking points, feedback capture. **Validation checkpoint:** Demo script must cover every must-have requirement flagged in `phase1_rfp_results.json` before delivery. Cross-reference with: ```bash python -c "import json; rfp=json.load(open('phase1_rfp_results.json')); [print('UNCOVERED:', r) for r in rfp['must_have_requirements'] if r['coverage']=='Gap']" ``` --- ### Phase 4: POC & Evaluation **Objective:** Execute a structured proof-of-concept that validates the solution. **Checklist:** - [ ] Define POC scope, success criteria, and timeline - [ ] Allocate resources and set up environment - [ ] Execute phased testing (core, advanced, edge cases) - [ ] Track progress against success criteria - [ ] Generate evaluation scorecard **Tools:** Run `poc_planner.py` to generate the complete POC plan. ```bash python scripts/poc_planner.py poc_data.json --format json > phase4_poc_plan.json python -c "import json; p=json.load(open('phase4_poc_plan.json')); print('Go/No-Go:', p['recommendation'])" ``` **Templates:** Use `assets/poc_scorecard_template.md` for evaluation tracking. **Output:** POC plan, evaluation scorecard, go/no-go recommendation. **Validation checkpoint:** POC conversion requires scorecard score >60% across all evaluation dimensions (functionality, performance, integration, usability, support). If score <60%, document gaps and loop back to Phase 2 for solution redesign. --- ### Phase 5: Proposal & Closing **Objective:** Deliver a technical proposal that supports the commercial close. **Checklist:** - [ ] Compile POC results and success metrics - [ ] Create technical proposal with implementation plan - [ ] Address outstanding objections with evidence - [ ] Support pricing and packaging discussions - [ ] Conduct win/loss analysis post-decision **Templates:** Use `assets/technical_proposal_template.md` for the proposal document. **Output:** Technical proposal, implementation timeline, risk mitigation plan. --- ## Python Automation Tools ### 1. RFP Response Analyzer **Script:** `scripts/rfp_response_analyzer.py` **Purpose:** Parse RFP/RFI requirements, score coverage, identify gaps, and generate bid/no-bid recommendations. **Coverage Categories:** Full (100%), Partial (50%), Planned (25%), Gap (0%). **Priority Weighting:** Must-Have 3×, Should-Have 2×, Nice-to-Have 1×. **Bid/No-Bid Logic:** - **Bid:** Coverage >70% AND must-have gaps ≤3 - **Conditional Bid:** Coverage 50–70% OR must-have gaps 2–3 - **No-Bid:** Coverage <50% OR must-have gaps >3 **Usage:** ```bash python scripts/rfp_response_analyzer.py assets/sample_rfp_data.json # human-readable python scripts/rfp_response_analyzer.py assets/sample_rfp_data.json --format json # JSON output python scripts/rfp_response_analyzer.py --help ``` **Input Format:** See `assets/sample_rfp_data.json` for the complete schema. --- ### 2. Competitive Matrix Builder **Script:** `scripts/competitive_matrix_builder.py` **Purpose:** Generate feature comparison matrices, calculate competitive scores, identify differentiators and vulnerabilities. **Feature Scoring:** Full (3), Partial (2), Limited (1), None (0). **Usage:** ```bash python scripts/competitive_matrix_builder.py competitive_data.json # human-readable python scripts/competitive_matrix_builder.py competitive_data.json --format json # JSON output ``` **Output Includes:** Feature comparison matrix, weighted competitive scores, differentiators, vulnerabilities, and win themes. --- ### 3. POC Planner **Script:** `scripts/poc_planner.py` **Purpose:** Generate structured POC plans with timeline, resource allocation, success criteria, and evaluation scorecards. **Default Phase Breakdown:** - **Week 1:** Setup — environment provisioning, data migration, configuration - **Weeks 2–3:** Core Testing — primary use cases, integration testing - **Week 4:** Advanced Testing — edge cases, performance, security - **Week 5:** Evaluation — scorecard completion, stakeholder review, go/no-go **Usage:** ```bash python scripts/poc_planner.py poc_data.json # human-readable python scripts/poc_planner.py poc_data.json --format json # JSON output ``` **Output Includes:** Phased POC plan, resource allocation, success criteria, evaluation scorecard, risk register, and go/no-go recommendation framework. --- ## Reference Knowledge Bases | Reference | Description | |-----------|-------------| | `references/rfp-response-guide.md` | RFP/RFI response best practices, compliance matrix, bid/no-bid framework | | `references/competitive-positioning-framework.md` | Competitive analysis methodology, battlecard creation, objection handling | | `references/poc-best-practices.md` | POC planning methodology, success criteria, evaluation frameworks | ## Asset Templates | Template | Purpose | |----------|---------| | `assets/technical_proposal_template.md` | Technical proposal with executive summary, solution architecture, implementation plan | | `assets/demo_script_template.md` | Demo script with agenda, talking points, objection handling | | `assets/poc_scorecard_template.md` | POC evaluation scorecard with weighted scoring | | `assets/sample_rfp_data.json` | Sample RFP data for testing the analyzer | | `assets/expected_output.json` | Expected output from rfp_response_analyzer.py | ## Integration Points - **Marketing Skills** - Leverage competitive intelligence and messaging frameworks from `../../marketing-skill/` - **Product Team** - Coordinate on roadmap items flagged as "Planned" in RFP analysis from `../../product-team/` - **C-Level Advisory** - Escalate strategic deals requiring executive engagement from `../../c-level-advisor/` - **Customer Success** - Hand off POC results and success criteria to CSM from `../customer-success-manager/` --- **Last Updated:** February 2026 **Status:** Production-ready **Tools:** 3 Python automation scripts **References:** 3 knowledge base documents **Templates:** 5 asset files --- ## business-operations-skills > Use when running, diagnosing, or designing internal business operations — process documentation, vendor SLAs, capacity planning, internal comms, SOP/runbook authoring, procurement spend. Triggers on "BizOps review", "where's the bottleneck", "vendor health", "internal SOP", "all-hands deck", "spend categorization", "capacity for Q3", "process mapping". Forks context to route to one of six BizOps sub-skills (process-mapper, vendor-management, capacity-planner, internal-comms, knowledge-ops, procurement-optimizer) and returns a digest. Distinct from business-growth (external sales motion) and c-level-advisor (strategic, not operational). # Business Operations — Domain Orchestrator The BizOps surface is **internal**: how the company actually runs. This orchestrator forks its conversation context, routes your inquiry to one of six sub-skills, then returns a tight digest to the parent thread. The heavy ingestion (vendor catalogs, process interviews, multi-doc SOP intake) stays in the forked context. ## When to invoke | Symptom | Sub-skill to route to | |---|---| | "Where does the work spend most of its time waiting?" | `process-mapper` | | "Is this vendor delivering against the SLA?" | `vendor-management` | | "Do we have enough people to ship in Q3?" | `capacity-planner` | | "I need to brief the company on a re-org" | `internal-comms` | | "Write me a runbook for the incident response process" | `knowledge-ops` | | "Why is our software spend up 40% YoY?" | `procurement-optimizer` | ## Routing logic (deterministic) The orchestrator classifies the inquiry by **signals** detected in the prompt. Two-signal threshold for confident routing; one-signal triggers a clarifying question. ### Signal table | Signal class | Keywords | Sub-skill | |---|---|---| | **PROCESS** | bottleneck, cycle time, waiting, handoff, BPMN, process map, workflow | `process-mapper` | | **VENDOR** | vendor, supplier, SLA, contract, third-party, MSA, SaaS subscription, renewal | `vendor-management` | | **CAPACITY** | headcount, capacity, utilization, planning, hiring sequence, FTE | `capacity-planner` | | **COMMS** | all-hands, internal newsletter, announcement, change management, FAQ, town hall | `internal-comms` | | **KNOWLEDGE** | SOP, runbook, knowledge base, wiki, playbook, documentation, onboarding doc | `knowledge-ops` | | **PROCUREMENT** | spend, procurement, purchase, supplier rationalization, software audit, SaaS sprawl | `procurement-optimizer` | If signals are mixed (e.g., "vendor SLA + spend audit"), run the **highest-confidence sub-skill first**, then chain into the second one in a follow-up forked turn. ### Fallback If no signal class scores ≥ 2, ask **one** clarifying question naming the two most likely candidates. Do NOT guess silently. ## Workflow (Matt Pocock grill discipline) Derived from Matt Pocock's `grill-with-docs` pattern: **explore-then-ask, one question per turn with a recommended answer, walk the decision tree depth-first, track dependencies, anchor every challenge in the documented canon** (`references/`). ### Step 1 — Explore before asking Before any clarifying question, check: - Does the user's working directory already contain a process map, vendor catalog, SOP, or org chart we can grep? - Does the inquiry already disambiguate the lane (e.g., "vendor SLA review" — that's `vendor-management`, no question needed)? - Is the lane unambiguous from filenames mentioned (`procurement-Q3.csv` → procurement)? If the codebase resolves the lane, **route silently**. Don't ask. ### Step 2 — If still ambiguous, ONE forcing question with a recommended answer Matt's rule: never bundle questions. Never default to "what do you think?". Always offer your recommendation. Pattern: ``` Q1/1: [precise question naming the two candidate lanes] Recommended: [Lane X, because ] (Confirm, or override?) ``` Wait for the user's response. **Then** route. Never guess silently after a turn that asked a question. ### Step 3 — Forking decision-tree walk (only if the inquiry crosses lanes) If the user's inquiry legitimately crosses two lanes (e.g., "vendor SLA + spend audit" = VENDOR + PROCUREMENT), walk the tree **depth-first**: 1. Resolve the higher-confidence lane first → run that sub-skill in forked context → return digest 2. Ask: "Should we now run [second lane]? My recommendation: yes, because [dependency reason]." 3. Only after explicit user confirmation, run the second sub-skill Do NOT chain silently. Each fork is an explicit user-confirmed step. ### Step 4 — Invoke sub-skill in forked context Each sub-skill is invoked with the original prompt + a digest of any structured inputs (file paths, JSON inputs). The fork keeps heavy ingestion (vendor catalog, process transcripts, SOP source documents) out of the parent context. ### Step 5 — Return digest with cited canon challenge When the sub-skill completes, return a **≤ 200-word digest** to the parent thread: - What was analyzed - Top 3 findings (each anchored in a reference doc citation — e.g., "Goldratt's Theory of Constraints: optimize the bottleneck, not the non-constraint") - Top 3 next actions (named owners if possible) - Path to the artifact(s) produced - **One grill challenge** for the user, cited: "Your value-add ratio is 12%. Lean canon (Womack & Jones 1996) classifies <15% as waste-heavy. What's blocking process redesign — political, technical, or budget?" The parent agent can then ask follow-ups (each triggering new forked invocations). ## Forcing-question library (grill-with-docs pattern) When the user has provided enough context to enter a lane, the orchestrator may grill them on the **decisions inside that lane** before invoking the sub-skill. One question per turn, each with a recommended answer + canon citation. Examples: - **PROCESS lane**: "Before mapping: do you have measured cycle times per stage, or only estimates? Recommended: insist on measured data for the top-3 longest stages. Anti-pattern (Goldratt 1984): map estimates, optimize the wrong constraint." - **VENDOR lane**: "Before scoring: what's your tier-1 criticality threshold — by spend ($X/year), or by operational dependency (revenue-blocking if vendor fails)? Recommended: operational dependency. Anti-pattern (Gartner TPRM): spend-only tiering misses critical low-spend vendors like the HVAC vendor in the Target breach." - **CAPACITY lane**: "Before modeling: are you planning for utilization or throughput? Recommended: throughput (Little's Law). Anti-pattern (DORA): planning for utilization > 80% destroys throughput via queueing." Never run a sub-skill until the lane-defining decision is locked. ## Assumptions 1. The user is acting on behalf of an organization with ≥ 10 employees (smaller orgs don't need this surface). 2. The user has access to the data the sub-skill needs (process docs, vendor list, spend export, etc.) — or accepts the skill's templated dummy data. 3. The user wants **deterministic, repeatable analysis** over LLM-flavored prose. Every sub-skill ships stdlib-only Python tools. ## Non-goals - Not a substitute for an ERP, vendor management platform (Vendr, Tropic), or capacity-planning SaaS (Float, Runn). - Does not store state across sessions — every invocation is self-contained. - Does not call external APIs from Python tools (stdlib only, by design). ## Distinct from - **`business-growth/*`** — that's the **external sales motion** (CSM, sales engineering, RevOps). BizOps is **internal**. - **`c-level-advisor/coo-advisor`** — that's strategic COO judgment ("should we restructure?"). BizOps is tactical ("here's the process map with bottlenecks"). - **`engineering/slo-architect`** — that's system reliability with SLO/SLI/error budgets. `process-mapper` is **business process** reliability, not system reliability. - **`engineering/llm-wiki`** — that's a **personal** PKM (Karpathy's pattern). `knowledge-ops` is **company-wide** SOP authoring. ## Output artifacts Every sub-skill produces at least one artifact (markdown, CSV, or JSON) saved to the user's working directory. The orchestrator surfaces the file path in the digest. ## Anti-patterns (do not) - ❌ Run all 6 sub-skills "to be thorough" — pick one based on signal, return digest, let user chain - ❌ Auto-approve a vendor or process change — surface findings; the human decides - ❌ Edit production process docs without asking — write to a new file, propose the diff - ❌ Skip the digest step — parent context needs ≤ 200-word digest, not the full sub-skill output ## References - See `c-level-advisor/coo-advisor` for strategic COO framing - Path-B build pattern: `documentation/implementation/bizops-commercial-expansion-plan.md` --- ## capacity-planner > Use when an ops leader (Director of CX, Head of Support, VP Ops, Head of BizOps, Head of IT ops, Head of Finance ops) is sizing ops capacity, building a headcount plan, modeling utilization risk, planning Q3 capacity or annual support capacity, or designing CS coverage — and needs Erlang-C queueing math, P90 demand sizing, shrinkage-adjusted FTE, manager-trigger thresholds, and a quarterly hiring sequence with ramp + attrition. Apply when sustained team utilization is above 80% or when the team is growing >50% in 12 months. Run before committing the headcount budget. This is NOT engineering capacity (see vpe-advisor for DORA + cycle time) and NOT strategic 3-year workforce planning (see chro-advisor). # capacity-planner Sizing tool for **ops teams that handle queued work** — Support, CX, Customer Success, BizOps, IT ops, Finance ops. Built on Erlang-C queueing theory, Little's Law, and the operational-leadership canon (Fournier, Larson, Cleveland, Reinertsen). Deterministic, stdlib-only, no LLM calls. ## Purpose You are an ops leader sized 15 → 35 with no idea how the 35-person org will actually behave at peak load. Or you are at 88% utilization and SLA is starting to slip. Or you have a hiring budget approved and need to sequence it across four quarters without burning out the existing team. This skill answers those questions with arithmetic, not vibes. It produces three artifacts: 1. **Capacity sizing** at 70/80/90% utilization against P50/P90/P99 demand, with P(SLA breach) at each point and a SAFE/WATCH/AT_RISK/CRITICAL risk band. 2. **Utilization health** at the per-member traffic-light level plus a team verdict (HEALTHY/SQUEEZED/OVERLOADED/UNBALANCED). 3. **12-month quarterly hiring plan** accounting for ramp curves, attrition, QoQ demand growth, and span-of-control manager triggers. ## When to use - **Annual ops capacity planning** (October-November for the following fiscal year). - **Quarterly re-sizing** if demand changed >15% or attrition spiked. - **Pre-budget defense** — the math that justifies the headcount ask to your CFO. - **Diagnostic** when an ops team is missing SLA and you need to know whether it's a sizing problem, a process problem, or a bottleneck problem. - **M&A / new-segment launch** modeling — sizing a new team or combined org. ## Workflow 1. **Intake demand**. Pull P50/P90/P99 daily ticket/case volume from your work system (Zendesk, Intercom, JSM, ServiceNow, Salesforce). If you only have averages, stop and pull the distribution. Single- point demand estimates are the most expensive anti-pattern in ops. 2. **Model throughput**. Run `capacity_modeler.py` with your demand, AHT, SLA target, current FTE, and shrinkage. Use `--profile` for your function (support / cx / bizops / finance-ops / it-ops). Read the 80%-utilization row — that's your sizing point. 3. **Flag utilization risk**. Run `utilization_analyzer.py` against your current team's actual utilization data. Anyone >85% sustained is a throughput-collapse risk per Reinertsen. Spread >30 percentage points across team means UNBALANCED — fix that before hiring. 4. **Sequence hiring**. Run `hiring_sequencer.py` with current FTE, target EOY, ramp time, attrition, and growth. It will front-load hires (Q1 35%, Q4 15%), apply ramp curves, and trigger a manager hire when span of control crosses 7 ICs/manager. 5. **Walk the Forcing-question library** (see below). One question at a time. Do not skip ahead. Answers must be written down before you commit the plan. ## Scripts - `scripts/capacity_modeler.py` — Erlang-C sizing with shrinkage adjustment and P50/P90/P99 breach probabilities. `--profile` for industry defaults. - `scripts/utilization_analyzer.py` — per-member traffic-light + team-level health verdict with variance detection. - `scripts/hiring_sequencer.py` — 12-month quarterly plan with ramp, attrition, growth, max-hires-per-quarter constraint, and manager-trigger logic. All three accept `--input ` (JSON), `--output {markdown,json}`, `--sample` (built-in example), and `--help`. Stdlib only. ## References - `references/queueing_theory_canon.md` — Erlang, Little, Hopp & Spearman, Reinertsen, Kingman, Cleveland, ITIL, Armony et al. (8 sources). The math. - `references/ops_workforce_planning_canon.md` — Fournier, Larson, Google SRE Workbook, Frei, Lawler, Bersin, Gartner, Grove (8 sources). The people factors. - `references/capacity_anti_patterns.md` — 11 named anti-patterns with cited sources, tool guards, and the meta-discipline that Lencioni + Goldratt + Christensen impose. (8+ named sources.) ## Assets - `assets/capacity_brief_template.md` — 20-minute fill-out template with JSON skeletons for all three tools and an output checklist. ## Assumptions This skill assumes: - Work is **queued** (tickets, cases, work items) — not project-style. If your team's work isn't queued, this is the wrong skill. - Demand has a **stationary-enough distribution** within a quarter. Step-changes (new product launch, M&A, regulatory shift) require re-running mid-quarter. - You have **at least 90 days of historical demand data** to compute P50/P90/P99. If not, generate the distribution from your sales / user-base forecast first. - Service is **single-class** within a queue. If you have hard priority tiers (P1/P2/P3 with class-specific SLAs), model each as a separate queue and sum. - **Channels are modeled coherently.** Multi-channel teams use the appropriate `--profile` with built-in shrinkage premium. ## Anti-patterns See `references/capacity_anti_patterns.md` for the full taxonomy with sources. Top eight: 1. Plan-to-100%-utilization (Reinertsen Principle 12) 2. Treat-ramp-as-instant (Larson) 3. Ignore-attrition-in-12-month-plan (Bersin) 4. Hire-ICs-forever-with-no-manager-trigger (Fournier) 5. Size-to-P50-demand-only (Cleveland) 6. No-shrinkage-adjustment (Cleveland, SRE Workbook) 7. Single-channel-model-for-multi-channel-work (Gartner, Kingman) 8. No-surge-plan-for-P99-events (Hopp & Spearman, Reinertsen) ## Distinct from - **`c-level-advisor/vpe-advisor`** measures *engineering* throughput via DORA 4 metrics, story points, deployment frequency, and cycle time bottlenecks. It is for engineering teams shipping code. This skill is for ops teams handling tickets/cases. Different unit of work, different math (Erlang-C vs. DORA), different bottleneck (queueing-blind staffing vs. WIP + lead time). - **`c-level-advisor/chro-advisor`** does *strategic* workforce planning (1-5 year capability portfolios, talent supply, leadership succession). This skill does *operational* 0-12 month capacity sizing against demand. Per Lawler: conflating them gets you hired into the wrong jobs. - **`project-management/*`** tracks delivery throughput on projects (Jira velocity, sprint capacity). This skill sizes around steady- state queued work. - **Sibling `process-mapper`** *finds* the bottleneck. This skill *sizes the team around* a known bottleneck. Order of operations: process-mapper first → capacity-planner second. Hiring around the wrong constraint wastes the hires. - **`business-growth/cs-coverage`** (if it exists) sizes Customer Success coverage by ARR/CSM ratio and segment. This skill sizes by queued work volume (tickets, cases, escalations). For a CS team that handles both relationship work AND a ticket queue, run both. ## Forcing-question library (Matt Pocock grill discipline) **Discipline**: walk these one at a time. Do not skip ahead. Answers must be written down. If you can't answer one, that is your next investigation. ### Q1 — "What is your bottleneck, and have you confirmed it empirically?" **Recommended answer**: a named, measured stage in the workflow with queue-time data showing where work waits. Not a vibe. Not "escalations take too long". An actual measured queue. **Why it's the first question**: Goldratt (*The Goal*, 1984) — every system has exactly one binding constraint at a time. Sizing around the wrong constraint wastes hires entirely. If you do not know your bottleneck, run `process-mapper` BEFORE this skill. **Canon**: Eli Goldratt, *The Goal* (1984); Reinertsen, *Principles of Product Development Flow* (2009). ### Q2 — "What service trade-off are you accepting?" **Recommended answer**: a written, explicit choice — fast vs. empathetic, broad vs. deep, low-cost vs. high-quality. Frances Frei is unambiguous: you cannot win all four. The team that tries wins zero. **Why it matters**: AHT, SLA, and shrinkage inputs are the operational expression of this trade-off. If they don't agree (e.g., you set AHT for "empathy" but SLA for "speed"), the plan is internally inconsistent. **Canon**: Frances Frei & Anne Morriss, *Uncommon Service* (HBR Press, 2012). ### Q3 — "What's your demand P90, and what's the gap to your P99?" **Recommended answer**: two specific numbers from the last 90 days of data, with the calendar context of each (e.g., "P90 was 480 tickets/day on normal Tuesdays; P99 was 720 on the day after the November release"). A team sized to P50 misses SLA half the time. A team sized to P99 overstaffs by 30-50%. P90 is the right operating sizing point per Cleveland. **Canon**: Brad Cleveland, *Call Center Management on Fast Forward* (4th ed., 2019); A.K. Erlang, *The Theory of Probabilities and Telephone Conversations* (1909). ### Q4 — "At your planned utilization, what is P(SLA breach) at P90 and at P99?" **Recommended answer**: two probabilities, computed (not guessed) from Erlang-C with your specific N, AHT, and SLA target. If P(breach at P90) > 10% you are understaffed at the sizing point. If P(breach at P99) > 50% you have no surge plan and the next peak event will be visible to the CEO. **Canon**: Erlang (1909); Hopp & Spearman, *Factory Physics* (3rd ed., 2008), VUT equation. ### Q5 — "Have you budgeted replacement hires for the attrition you'll see this year?" **Recommended answer**: yes, with a specific number. At 30% annual attrition (Bersin BPO midpoint), a 20-FTE team loses ~6 people this year. If your "add 5 net" plan is actually a "hire 11" plan, the recruiting volume changes drastically. Anti-pattern #3. **Canon**: Bersin/Deloitte talent benchmarks (2015-2023); Edward Lawler, *Strategic Workforce Planning* (USC CEO, 2008). ### Q6 — "When does span of control trigger a manager hire, and who is the candidate?" **Recommended answer**: a specific quarter (from `hiring_sequencer.py`) and at least one identified candidate (internal lead or external hire). Past 7 ICs/manager, 1:1s degrade, feedback cycles slip, attrition climbs. Past 10 you have a coverage crisis. Hire the manager BEFORE crossing 10, not after. **Canon**: Camille Fournier, *The Manager's Path* (O'Reilly, 2017), ch. 5; Andy Grove, *High Output Management* (1983). ### Q7 — "What is your surge plan for the P99 day?" **Recommended answer**: an explicit, documented plan — overflow tier, BPO contracted capacity, on-call rotation, executive escalation tree, OR a written degradation contract that says "on P99 days we extend SLA to X minutes and notify customers proactively". If the answer is "we'll figure it out", the P99 day is a fire visible to the board. **Canon**: Hopp & Spearman, *Factory Physics* (2008); Reinertsen (2009) on capacity-margin discipline. --- **Walk these seven in order. One at a time. Write the answers down. The plan you submit is only as defensible as your answers to these seven questions.** --- ## internal-comms > Use when a Head of People Ops, BizOps lead, or Internal Communications owner needs to draft and sequence an internal-only change-management communication — a re-org announcement, a tool rollout, a policy change, a benefit change, a leadership transition, a layoff, an acquisition close, or an internal product launch — and the audience is employees (not customers). Triggers on "all-hands announcement", "town-hall script", "change comms", "internal newsletter", "rollout comms", "policy change announcement", "re-org announcement", "internal FAQ", "manager talking points", "Prosci ADKAR", "Kotter 8-step", "layoff comms", "RIF comms", "internal memo". Pairs Prosci ADKAR (Awareness / Desire / Knowledge / Ability / Reinforcement) and Kotter's 8-step change model with deterministic stdlib-only Python tools to produce a sequenced touchpoint calendar, a Kotter-compliant primary announcement, an audience-segmented FAQ, and manager cascade talking points. Industry-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Distinct from marketing-skill/* (external/customer-facing), c-level-advisor/internal-narrative (strategic framing, not tactical drafts), and c-level-advisor/change-management (executive change strategy, not the comms package itself). # internal-comms — Tactical Internal Change-Management Authoring You are a BizOps / People Ops / Internal Communications operator. Your job is to produce the **comms package** for a specific internal change event: the primary announcement, the FAQ, the manager talking points, and the touchpoint calendar. Your audience is **employees, not customers**. Your decisions are about **timing, sequencing, channel mix, and what to NOT say**. ## Purpose Internal change announcements fail in four predictable ways: 1. **No framework** — the comms lead writes from instinct, the magnitude is mis-set, and tone collides with content (celebratory framing for a job cut, "minor update" for a 30% RIF). 2. **No touchpoint sequencing** — one Slack post is treated as "the comms plan." Prosci research shows 5–7 touchpoints are the floor for behavioral change. 3. **No FAQ scaffolding** — the questions employees actually ask ("Will my comp change?", "Will I report to someone new?", "Is this a precursor to layoffs?") are not pre-answered, so the announcement leaks ambiguity into Slack and Glassdoor. 4. **No manager cascade** — front-line managers find out at the same time as their reports, so when an IC asks them a question they cannot answer it. Prosci consistently rates **direct manager** as the #1 most-trusted change-communication channel; if managers are unprepared, the announcement is already broken. This skill produces the four artifacts above with deterministic logic anchored on **ADKAR** (Prosci) and **Kotter's 8-step** model — not LLM intuition. ## When to use - A re-org / leadership change / new tool rollout / policy change / benefit change / layoff / acquisition close needs internal announcement within 48 hours. - A draft announcement exists but no touchpoint calendar — you need to assess whether 5–7 touchpoints are scheduled and whether the channel mix matches magnitude. - An internal FAQ is required but the obvious-to-employees questions have not been seeded. - Manager talking points are needed so the front-line cascade is coherent. - A previous announcement landed badly and you need an anti-pattern audit before the next one. ## When NOT to use - Customer-facing launch comms / press release / blog post → `marketing-skill/*` - Strategic narrative framing for a transformation arc → `c-level-advisor/internal-narrative` - Executive change-strategy design (sponsor coalition, change-saturation analysis) → `c-level-advisor/change-management` - All-hands deck visual design / slide template → (future skill, not this one) - HR policy authoring itself (the legal/compliance text of the new policy) → outside scope; this skill assumes the policy decision is made ## Workflow Five-step deterministic flow. Follow in order. 1. **Intake the change.** Capture the event in JSON: type (`reorg | tool_rollout | policy_change | leadership_change | layoff | acquisition | product_launch_internal | benefit_change`), audience segments, magnitude (`low | medium | high | disruptive`), effective date, channels available. Use `assets/comms_brief_template.md` and its JSON skeleton. 2. **Assess magnitude vs. tone fit.** Run `change_announcement_builder.py` with `--profile `. The builder enforces magnitude/tone validations (no "exciting news" framing on disruptive, no "minor update" on high) and emits a Kotter 8-step structured announcement with each step explicitly labeled. 3. **Plan touchpoints.** Run `comms_calendar_builder.py`. It generates a 7-touchpoint sequence keyed to T-N / T+N relative to effective date, with channel, owner, ADKAR stage, and key message per touchpoint. Surfaces gaps (e.g., only 2 touchpoints planned for a disruptive change) and channel mismatches (e.g., Slack-only for a layoff). 4. **Draft full package.** Run `comms_template_filler.py`. It produces the four-artifact package — pre-comm, announcement, FAQ, follow-up — with each touchpoint explicitly tagged to its ADKAR stage and tailored per audience segment. 5. **Anti-pattern sweep.** Cross-check the output against `references/announcement_anti_patterns.md` before publishing. The 8 anti-patterns listed there are non-negotiable; any one of them is a "do not send" signal. ## Scripts **`scripts/comms_template_filler.py`** — Fills the 4-artifact comms package (pre-comm, announcement, FAQ, follow-up) using ADKAR anchors per audience segment. Each touchpoint output is tagged with the ADKAR stage it serves (Awareness, Desire, Knowledge, Ability, Reinforcement). Stdlib only. `--sample` prints a tool-rollout example for an engineering audience. **`scripts/change_announcement_builder.py`** — Produces a Kotter 8-step compliant primary announcement (Establish Urgency → Build Coalition → Form Vision → Communicate Vision → Empower Action → Generate Wins → Sustain Momentum → Anchor in Culture). Each step is labeled inline. Validates magnitude vs. tone (no "exciting news" if magnitude is `disruptive`; no "minor update" if magnitude is `high`). Industry-tuned via `--profile {tech-startup, scaleup, enterprise, public-company, non-profit}` — public-company tone is more conservative (material-event awareness), startup tone is more direct. **`scripts/comms_calendar_builder.py`** — Builds a 7-touchpoint sequencing calendar (Prosci's documented floor for behavioral change is 5–7). Each touchpoint has timing (T-N / T+N days), channel, owner, ADKAR stage, key message. Surfaces gaps and channel mismatches: e.g., "only 2 touchpoints planned for `disruptive` change — anti-pattern", "Slack-only for `layoff` is an anti-pattern; requires synchronous channel". All three: stdlib only, `--help` and `--sample` exit 0, accept `--input ` and `--output {markdown,json}`. ## References - `references/change_management_canon.md` — Jeff Hiatt *ADKAR* (Prosci), John Kotter *Leading Change* (8-step), William Bridges *Managing Transitions* (Endings / Neutral Zone / Beginnings), Edgar Schein *Organizational Culture and Leadership*, McKinsey 7-S framework, Heath brothers *Switch*, Patrick Lencioni *The Advantage*. - `references/internal_comms_canon.md` — Edelman Trust Barometer (internal-comms data), Gallup *State of the American Workplace*, Liz Wiseman *Multipliers*, Stew Friedman *Total Leadership*, Bersin (employee-comms research), Welch & Jackson 2007 (internal-communication taxonomy academic paper), IABC (International Association of Business Communicators) guidelines. - `references/announcement_anti_patterns.md` — 8 specific anti-patterns drawn from Prosci, MIT Sloan layoffs research (Sucher & Gupta), HBR transparent-leadership work, Lencioni, Adam Grant, Better.com/Vishal-Garg case study, and the Bishop Fox / Yahoo / Twitter layoff post-mortems. ## Assumptions 1. The user has authority (or a clear delegation from a sponsor) to publish the comms package. Without sponsor sign-off, this skill produces a draft, not a publication. 2. The decision being announced is already made. This skill does not help you decide *whether* to re-org; it helps you announce a re-org you've decided to do. 3. The user can name the audience segments honestly. "All-hands" is rarely the right segment — managers, ICs, affected team, unaffected team usually need different framings. 4. The magnitude field is honest. A 30% RIF is `disruptive`, not `high`. Mis-labelling magnitude is the most common upstream error and breaks every downstream validation. 5. The effective date is fixed. Sliding the date after publication is a separate trust event and requires its own comms cycle. ## Anti-patterns - **Slack-only announcement of a high or disruptive change.** Synchronous channels (town hall, manager 1:1) are required for trust-laden events. See `references/announcement_anti_patterns.md`. - **Passive voice for accountability.** "Decisions have been made" hides the decision-maker. Name them. - **Magnitude downplay.** "Minor restructuring" for a 30% RIF is the Better.com / Vishal-Garg failure mode. The tools reject this. - **No manager talking points.** Front-line managers must know first, with a script, or the cascade fails on contact. - **Celebratory framing for a job cut.** "We're streamlining to focus on our mission" applied to a layoff is the post-mortem-of-record anti-pattern. - **Bundled questions in the orchestrator.** Matt Pocock rule: one question at a time, with a recommended answer + canon citation. Never bundled. - **No follow-up touchpoints.** A single announcement is not a comms plan. Prosci floor is 5–7. - **Skipping the FAQ.** Employees will ask the questions anyway. Pre-answer them or watch Slack write the FAQ for you, badly. ## Distinct from - **`marketing-skill/*`** — external / customer-facing comms. Internal-comms is for employees, not press or customers. Different audience, different trust model, different success metric. - **`c-level-advisor/internal-narrative`** — strategic narrative framing across quarters / years (the *story arc* of a transformation). Internal-comms is the *tactical authoring* of one announcement within that arc. - **`c-level-advisor/change-management`** — executive change strategy: sponsor coalition design, change-saturation analysis, ADKAR diagnostics across portfolio. Internal-comms is the deliverable for one event, not the strategy. - **`business-growth/*`** — outbound sales / customer-success motion. Different audience, different goal. - **`engineering/handoff`** — conversation-continuity for AI sessions. Same word "handoff", different domain. ## Forcing-question library (Matt Pocock grill discipline) Before invoking the tools, the orchestrator (or `/cs:grill-bizops`) walks the user through these questions **one at a time, with a recommended answer + canon citation**. Never bundled. 1. **"What is the magnitude of this change — low, medium, high, or disruptive — and what specific impact on employees defines that level?"** Recommended: assume one level higher than instinct. Layoffs are always `disruptive`, never `high`. Canon: Hiatt 2006 (*ADKAR*) — under-rating magnitude is the single largest cause of resistance. 2. **"Who finds out first, and in what order — managers before ICs, affected team before unaffected, leadership before everyone?"** Recommended: managers always 24–48h ahead with talking points; affected team before unaffected; never in-the-same-meeting-as-the-public-announcement. Canon: Prosci Best Practices in Change Management (2023) — direct manager is the #1 most-trusted change channel; failure to brief them first guarantees the cascade breaks. 3. **"How many touchpoints have you planned across what channels, and which ADKAR stage does each serve?"** Recommended: minimum 5, target 7, across at least 3 channels; each touchpoint tagged to one ADKAR stage. Canon: Prosci 11th edition research — 5–7 touchpoints is the documented floor for behavioral change adoption. 4. **"What questions will employees ask the moment they see this — and have you written the answers down already?"** Recommended: seed the FAQ with at least 7 questions: comp, reporting line, location, role change, timing, why now, why us. Bias toward including the questions you wish people would not ask. Canon: Edelman Trust Barometer (annual) — internal trust collapses fastest when the obvious question is unanswered. 5. **"Who is the named accountable executive that will appear on the announcement and be present at the town hall, and have they confirmed both?"** Recommended: a single, named human at VP level or above; physically (or video-) present; not delegating to comms team. Canon: Kotter 1996 (*Leading Change*) — invisible sponsors trigger Step 1 (Establish Urgency) failure and the rest of the model collapses. 6. **"What are you NOT saying, and why?"** Recommended: surface the omissions explicitly to legal / sponsor. The unsaid will be inferred; better to know what's being inferred. Canon: Sucher & Gupta MIT Sloan layoffs research (2018) — what is omitted from a layoff announcement becomes the lead Glassdoor narrative. 7. **"What does success look like 30 / 60 / 90 days after the announcement — and how are you measuring it?"** Recommended: name 3 measurable signals (e.g., regrettable-attrition delta, pulse-survey trust score, manager-cascade audit results). Canon: Hiatt 2006 (*ADKAR*) — Reinforcement is the most-skipped ADKAR stage; without measurement there is no Reinforcement. --- ## knowledge-ops > Use when a Head of Ops, Knowledge Manager, or TPM-Internal needs to author, validate, or clean up company SOPs and internal runbooks (procurement intake, vendor offboarding, incident-comms cascade, employee onboarding, expense reimbursement, system-access provisioning, customer-escalation playbook) — including 5W2H completeness checks (Who-What-When-Where-Why-How-HowMuch), cross-link and orphan-page validation across a sprawling Notion/Confluence/Obsidian wiki, KB ingestion + hygiene reporting, ops onboarding doc generation, and runbook step verification (named owner, expected duration, observable success signal, rollback path, escalation contact). Pairs Kaoru Ishikawa's 5W2H method, Atul Gawande's *The Checklist Manifesto*, ISO 9001, ITIL v4 Service Operation, FDA 21 CFR Part 211, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists. Distinct from `engineering/llm-wiki` (Karpathy-style personal PKM second brain), `engineering-team/runbook-generator` (system-ops production debugging runbook), `project-management/*` (Jira/Confluence delivery + ticket tracking), and sibling `business-operations/process-mapper` (BPMN process *design*, while knowledge-ops is process *documentation*). # knowledge-ops Company SOP + internal runbook authoring, 5W2H completeness validation, and KB hygiene reporting for Head-of-Ops / Knowledge-Manager / TPM-Internal personas. ## Purpose An ops organization three years in accumulates a sprawl: 600 Notion pages, 200 Confluence runbooks, three Obsidian vaults, a `Drive/SOPs/` folder, and a `Slack #ops-questions` channel that exists because nobody can find the canonical doc. Predictable failure modes: 1. **No owner** — 40% of SOPs name "the team" instead of a person. When the doc rots, nobody is accountable. 2. **No last-reviewed date** — a 2023 vendor-offboarding SOP still references a procurement tool sunset in 2024. 3. **Vague success signals** — runbook step 4 says "verify the service is up". A new operator can't tell what that means. 4. **No rollback path** — incident-comms cascade runbook tells you how to send the alert. It doesn't tell you how to retract it when the alert was wrong. 5. **Orphan pages** — half the KB has no inbound links. Nobody finds them via navigation; they only exist because somebody knew the URL. 6. **Glossary drift** — "CSM" means Customer Success Manager in three docs and Customer Solutions Manager in five. New hires guess wrong for six months. 7. **Happy-path-only SOPs** — the doc covers what happens when everything works. It doesn't cover the 30% case where it doesn't. This skill answers the operator's actual question: **"Which 20 docs do I fix first, and what specifically is wrong with each?"** — with deterministic logic, not intuition. ## When to use - Authoring a new SOP for a cross-functional company process (procurement intake, vendor offboarding, incident-comms cascade, employee onboarding, expense reimbursement, customer-escalation playbook, security-incident comms, system-access provisioning). - Validating an existing internal runbook before it goes into rotation (every step must have a named owner, expected duration, observable success signal, observable failure signal, rollback path, escalation contact). - Ingesting a multi-document KB export (Notion zip, Confluence space export, Obsidian vault, `Drive/SOPs/` directory) and surfacing what's broken: orphan pages, stale pages (no edit > 12 months), glossary drift, missing-owner pages, cross-link map. - Onboarding a new ops hire by generating the SOPs and ops-handbook pages they need to read in week 1. - Wiki cleanup sprints — quarterly hygiene work where the org decides which 30 docs to archive, rewrite, or merge. ## Workflow Four-step deterministic flow (matches the ops org's actual workflow, not an abstract process): 1. **Ingest KB.** Run `kb_ingester.py --input ` on the existing wiki export. Output is a markdown health report: orphan pages, stale pages, glossary drift, missing-owner pages, cross-link map, prioritized cleanup list. The report ranks the top-20 docs to fix first — usually a mix of high-traffic stale docs and compliance-relevant missing-owner docs. Take this list to the cleanup sprint. 2. **Validate existing runbooks.** For each runbook in the cleanup list (or any new runbook before it goes into rotation), run `runbook_validator.py --input `. The validator scores each step against six checks (named owner, expected duration, observable success signal, observable failure signal, rollback path, escalation contact) and produces a per-step traffic-light + overall validity score 0-100 + MUST-FIX issue list. A runbook scoring < 60 is not safe to use in an incident. 3. **Generate missing SOPs.** For SOPs that need to be written from scratch (or rewritten because the existing one is unsalvageable), run `sop_generator.py --input --profile `. Output is a 5W2H-structured SOP scaffold: Who (RACI), What (process steps), When (triggers + frequency), Where (system + tool), Why (purpose + regulatory basis), How (step-by-step), How-much (cost + time per execution). The `regulated` profile adds version control, signoff, and audit-trail sections (ISO 9001 / FDA 21 CFR Part 211 / SOC 2 / HIPAA). 4. **Cross-link + close the loop.** Re-run `kb_ingester.py` after the cleanup sprint to verify orphan-page count is down and glossary drift is resolved. The metric that matters is **"unfindable docs"** (orphans) and **"unsafe runbooks"** (validity score < 60) — not page count. ## Scripts **`scripts/sop_generator.py`** — Reads a JSON metadata file describing an SOP (process owner, triggering event, audience role, frequency, regulatory overlay, inputs, outputs, steps outline) and emits a full 5W2H-structured SOP in markdown (or normalized JSON). The `--profile` flag tunes the output: `ops` (general internal ops), `support` (customer-support runbook style), `finance` (controls + reconciliation focus), `hr` (sensitive-data flagging), `it` (system + access focus), `regulated` (adds version control, signoff matrix, audit-trail). Regulatory overlays (`SOC2`, `HIPAA`, `ISO13485`, `GDPR`, `SOX`) attach the appropriate compliance preamble. `--sample` prints a complete vendor-offboarding SOP example. Stdlib only. **`scripts/runbook_validator.py`** — Reads a runbook (markdown file or JSON) and validates each step against six required attributes: (1) named owner (not "the team", not "ops"), (2) expected duration (concrete number + unit), (3) observable success signal (e.g., "HTTP 200 from `/healthz`" — not "service is up"), (4) observable failure signal, (5) rollback path (or explicit "this step cannot be rolled back, escalate to X"), (6) escalation contact (named person or named on-call rotation). Output is a per-step traffic-light (GREEN/AMBER/RED), an overall validity score 0-100, and a MUST-FIX issue list. Verdict: ≥ 80 = SAFE-TO-USE, 60-79 = USE-WITH-CAUTION, < 60 = NOT-SAFE. `--sample` prints a deliberately-broken incident-comms runbook to demonstrate failure detection. Stdlib only. **`scripts/kb_ingester.py`** — Walks a directory of markdown files (Notion export, Confluence space export, Obsidian vault, `Drive/SOPs/` directory). Extracts: (a) cross-link map (which page references which, via markdown `[link](path)` syntax), (b) glossary candidates (frequently used proper nouns and acronyms that recur in 3+ docs without a single canonical definition page), (c) orphan pages (no inbound links from anywhere in the vault), (d) glossary drift (the same term defined or used inconsistently across docs — e.g., "CSM" expanded differently in two places), (e) stale pages (no edit in > 12 months, detected via filesystem mtime or YAML `last_reviewed` frontmatter), (f) missing-owner pages (no `owner:` field in frontmatter). Emits a KB health report markdown with a prioritized top-20 cleanup list ranked by `staleness × inbound-link-count` (high-traffic stale docs first). `--sample` builds a tiny synthetic 8-page vault in a tmpdir and runs the full pipeline against it. Stdlib only. ## References - `references/5w2h_sop_canon.md` — Kaoru Ishikawa's 5W2H method, Toyota standard-work discipline, Atul Gawande's checklist manifesto, Atlassian Confluence SOP guidance, ISO 9001 SOP requirements, ITIL v4 Service Operation, FDA 21 CFR Part 211. Eight cited sources covering SOP authoring canon. - `references/runbook_canon.md` — Google SRE Workbook (runbook chapter), Atlassian incident-management runbooks, PagerDuty Incident Response taxonomy, AWS Well-Architected operational excellence pillar, Charity Majors on observability-runbook integration, Susan Fowler on production-ready microservices, ITIL v4 Operations. Seven cited sources covering runbook design canon. - `references/kb_hygiene_anti_patterns.md` — Eight anti-patterns drawn from Notion/Confluence wiki industry research, Mozilla SUMO knowledge-base lessons, Stack Overflow community-management research, the Atlassian Team Playbook, MIT TIK org-wiki studies, Cynthia Lee on glossary drift, and Adam Wiggins on "documentation rot". ## Assumptions 1. The KB is in markdown (or can be exported to markdown — Notion, Confluence, Obsidian, and Google Docs all support this). HTML-only or PDF-only KBs require a conversion pass first; out of scope. 2. The user has authority to commission rewrites or archives. Producing a cleanup list nobody acts on is wasted work — route findings to a named owner before running the ingester. 3. Owner metadata lives in YAML frontmatter (`owner: alex@company.com`) or in a top-of-page "Owner:" line. Tribal-knowledge ownership (the person who last edited the page) is treated as missing. 4. "Stale" defaults to 12 months. Override with `--stale-days` on `kb_ingester.py`. Some compliance regimes (FDA, ISO 13485) require shorter review cycles; use `--profile regulated` and `--stale-days 365`. 5. The user is not asking for a personal PKM. Personal Karpathy-style second-brain work belongs in `engineering/llm-wiki`. ## Anti-patterns - **Generating SOPs in bulk without owners.** A doc with no owner has a half-life of 6 months. Refuse to generate a batch of 30 SOPs unless each one is assigned to a named human. - **Using `runbook_validator.py` as a checkbox.** The validator catches missing structure. It does not catch wrong content. A runbook can score 100 and still tell the operator the wrong thing. - **Treating orphan pages as garbage by default.** Some orphans are reference pages found only via search — not all orphans should be archived. The cleanup list is a *priority queue*, not a delete list. - **Confusing knowledge-ops with `process-mapper`.** Process-mapper documents the *flow* of work between stages (BPMN, cycle time, bottleneck). Knowledge-ops documents the *artifacts* operators consume to execute the work (SOP, runbook, glossary). Both can apply to the same process. - **Letting glossary drift accumulate.** Two definitions of "CSM" in three years becomes seven definitions in five. Fix glossary drift the moment it surfaces in `kb_ingester.py` output. - **Skipping the regulated profile under regulated workload.** If the process touches PHI, SOX-relevant financial controls, or ISO 13485 device QMS, use `--profile regulated`. Missing version control on a regulated SOP is an audit finding. - **Hand-writing 5W2H sections from memory.** The 5W2H scaffold exists because operators forget "How-much". Use the generator; edit the output. ## Distinct from - **`engineering/llm-wiki`** — Karpathy-style personal PKM second brain where one human ingests sources into their own interlinked vault. Knowledge-ops is *organizational*: many authors, many readers, named owners per doc, formal review cycles, compliance overlays. - **`engineering-team/runbook-generator`** — system-ops runbook for debugging a production system (logs, alerts, k8s, on-call). Knowledge-ops runbooks are *operator* runbooks for business processes (incident-comms cascade, vendor offboarding, employee onboarding). The audience is fellow operators, not engineers tailing logs. - **`project-management/*`** — Jira / Confluence delivery tracking, sprint ticket workflow, project-status reporting. Knowledge-ops is the *content* in those Confluence pages, not the *tracking* of who edits them. - **`business-operations/process-mapper`** (sibling) — BPMN process *design*: where the stages are, where work waits, which stage is the bottleneck. Knowledge-ops is process *documentation*: the SOP and runbook artifacts that tell an operator how to execute the process the mapper described. - **`business-operations/internal-comms`** (sibling) — broadcast announcements, all-hands messaging, change-management comms. Knowledge-ops is the durable reference artifact; internal-comms is the broadcast. - **`ra-qm-team/*`** — formal regulatory compliance authoring (ISO 13485 QMS, MDR technical files, 21 CFR Part 820). Knowledge-ops borrows the regulatory checklist but is not a substitute for a notified-body audit. ## Forcing-question library (Matt Pocock grill discipline) Before invoking the tools, the orchestrator (or `/cs:grill-bizops`) walks the user through these questions **one at a time, with a recommended answer + canon citation**. Never bundled. Walk depth-first — do not open question 4 until 1-3 are locked. 1. **"Who is the named owner of this SOP / runbook, and do they know they own it?"** Recommended: a single human (not "the team"), and yes — they have agreed in writing. Canon: Gawande 2009 (*The Checklist Manifesto*) — checklists without an owner rot within 12 months. Ownership is the discipline. 2. **"When was this doc last reviewed, and what is the review cadence?"** Recommended: reviewed within the last 12 months (90 days if `--profile regulated`); cadence written in the frontmatter. Canon: ISO 9001:2015 §7.5.3 — controlled documents require review-cycle metadata. ITIL v4 echoes this for Service Operation runbooks. 3. **"For each runbook step: what is the observable success signal — by which I mean, what specific output tells you the step worked?"** Recommended: a concrete observable ("HTTP 200 from `/healthz`", "Slack thread closed with `done` reaction", "Salesforce opportunity moved to `Closed-Won` stage") — not "the service is up" or "it works". Canon: Beyer et al. 2018 (*Site Reliability Workbook*, Ch. 8) — observable signals are the entire point of a runbook. Vague success criteria are the leading cause of runbook misuse during incidents. 4. **"What is the rollback path for each runbook step that can fail?"** Recommended: every step that mutates state has either a rollback path or an explicit "cannot roll back — escalate to X" line. Canon: AWS Well-Architected Framework, Operational Excellence pillar — "you cannot run a process you cannot reverse without first agreeing what 'reverse' means". 5. **"Where does this doc live, and what other docs link to it?"** Recommended: in the canonical wiki, and at least 2 inbound links from related docs. An orphan SOP is an unfindable SOP. Canon: Atlassian Team Playbook on documentation health — orphan rate > 20% is the leading indicator of a wiki sprawl problem. 6. **"What is the regulatory overlay on this process — SOC 2, HIPAA, ISO 13485, GDPR, SOX, none?"** Recommended: explicit answer. If "none", confirm by checking the data classes the process touches. Canon: FDA 21 CFR Part 211.100 (Written procedures; deviations) — regulated SOPs require version control, change history, and signoff. Skip this step and the doc is an audit finding. 7. **"Is the happy path the *only* path documented, or are the 2-3 most common failure modes also documented?"** Recommended: the top-2 failure modes per process are documented with their own recovery sub-procedure. Canon: Fowler 2016 (*Production-Ready Microservices*) — operations docs that cover only the happy path are responsible for 60%+ of incident-time waste. After all 7 are locked, invoke `kb_ingester.py` → `runbook_validator.py` → `sop_generator.py` in sequence. --- ## process-mapper > Use when a BizOps lead, COO, or process-improvement owner needs to document an end-to-end business process (procurement, employee onboarding, incident handoff, customer-onboarding, claims adjudication) in BPMN-style notation, measure cycle times by stage, surface where work spends most of its time waiting vs. being worked, and quantify the gap between processing time and total elapsed time. Pairs Lean / Six Sigma / Theory-of-Constraints canon with deterministic stdlib-only Python tools to produce a process map, a ranked bottleneck list (with severity + root-cause hypothesis), and a cycle-time analysis (P50, P90, value-add ratio, Little's-Law throughput). Distinct from sales-pipeline, system-reliability (SLO), and strategic-OKR work — this is tactical process documentation for internal operations. # process-mapper BPMN-style business process documentation, bottleneck detection, and cycle-time analysis for internal-operations leaders. ## Purpose Internal-operations work suffers from three recurring failure modes: 1. **Implicit process** — the steps exist only in tribal knowledge, so handoffs drop and onboarding takes weeks. 2. **Invisible waiting** — most of the elapsed time on any business process is queue / wait / approval time, not actual work; teams optimize the wrong stage. 3. **Local optimization** — Goldratt's Theory of Constraints is ignored; resources are added to non-constraint stages, gaining nothing. This skill produces a documented process map, identifies where work waits, and points the constraint out by name with deterministic logic — not LLM intuition. ## When to use - Documenting a new business process (procurement intake, vendor onboarding, employee onboarding, incident handoff, expense reimbursement, customer onboarding, claims adjudication). - An existing process is "too slow" but nobody can name the bottleneck. - Cycle time is being measured but value-add ratio is not — so the team can't tell whether the process is healthy or waste-heavy. - Cross-functional handoffs are dropping work and root cause is unclear. ## Workflow Five-step deterministic flow: 1. **Intake.** Capture the process as a JSON file with one entry per stage: `name`, `owner`, `type` (`value-add` | `wait` | `rework`), `duration_minutes_p50`, `duration_minutes_p90`. Use `assets/process_template.md` and its JSON skeleton. 2. **Map stages.** Run `process_documenter.py` to produce an ASCII swim-lane diagram + a normalized JSON artifact. The swim-lane separates lanes by owner so cross-functional handoffs become visible. 3. **Measure cycle time.** Run `cycle_time_analyzer.py` to compute total P50, total P90, value-add ratio (VA%), and a Little's-Law throughput estimate. Verdict: VA% > 25% = HEALTHY, 10–25% = TYPICAL, < 10% = WASTE-HEAVY. 4. **Detect bottlenecks.** Run `bottleneck_detector.py` with the appropriate `--profile` (saas / services / manufacturing / healthcare). Output is a ranked list with severity (CRITICAL / HIGH / MEDIUM), root-cause hypothesis, and one recommended action per finding. 5. **Recommend.** Pair the bottleneck list with the cycle-time verdict; recommend a single constraint-focused intervention per Goldratt's "subordinate everything to the constraint" rule. Don't recommend optimization of a non-constraint stage. ## Scripts **`scripts/process_documenter.py`** — Reads a process JSON, validates it, and emits a text-based BPMN-style swim-lane diagram in Markdown (lanes by owner, stages annotated with type + duration). Also outputs a normalized JSON artifact for downstream tools. Stdlib only. `--sample` prints a 6-stage procurement-intake example. **`scripts/bottleneck_detector.py`** — Applies three deterministic detection rules: (a) stage P50 > 2× mean of value-add stages, (b) wait-state % > 40% of total cycle, (c) rework % > 15%. Thresholds adjust by `--profile` because SaaS, services, manufacturing, and healthcare have different "normal" wait ratios. Output is a ranked list with severity, hypothesis, action. **`scripts/cycle_time_analyzer.py`** — Computes total P50 and P90 cycle time, value-add ratio (VA%), wait %, rework %, and a Little's-Law throughput estimate (WIP / cycle time). Per Lean canon: VA% > 25% = HEALTHY, 10–25% = TYPICAL (most non-manufacturing processes land here), < 10% = WASTE-HEAVY. ## References - `references/lean_six_sigma_canon.md` — TIMWOOD wastes, value-stream mapping, Theory of Constraints, Kanban WIP, Little's Law. Cites Womack & Jones, Rother & Shook, Goldratt, Ohno, Liker, Pyzdek, Anderson. - `references/bpmn_essentials.md` — Pools, lanes, gateways, events, message flows, common notation mistakes. Cites the OMG BPMN 2.0 spec, Silver, Allweyer, Freund/Rücker, OASIS, ISO/IEC 19510:2013. - `references/bottleneck_anti_patterns.md` — Seven specific anti-patterns drawn from Goldratt, Kim et al., Spear, DORA, Deming, and process-mining research. ## Assumptions 1. The user can provide stage-level cycle-time data (even rough P50 / P90 estimates). If they cannot, the first step is to instrument the process — not to map it. 2. "Process" here means a repeatable business workflow with discrete stages, not a one-off project. 3. The user has authority to act on bottlenecks (or can route findings to someone who does). Without that, the output is academic. 4. Stage `type` is honest: a "value-add" stage labeled as such by the user really does change the work product from the customer's perspective. Mis-labelling waiting as value-add is the most common data-quality failure. ## Anti-patterns - **Mapping every process at once.** Pick one. Goldratt: the constraint is a single point. - **Optimizing the non-constraint.** If stage 4 is the bottleneck, speeding up stage 2 just builds inventory in front of stage 4. Subordinate everything to the constraint. - **Mistaking total cycle time for processing time.** They are almost never the same; VA% reveals the gap. - **Adding people to a wait-bound process.** Wait time is not solved by more headcount; it's solved by removing the handoff or batch. - **Treating rework as a separate problem.** Rework loops belong in the process map. Hiding them understates true cycle time. ## Distinct from - **business-growth skills** — external sales motion, lead-funnel conversion, customer-success retention. Process-mapper is *internal* operations. - **engineering/slo-architect** — system-reliability SLOs / error budgets / burn-rate alerts. Process-mapper is *business-process* cycle time, not system uptime. - **c-level-advisor (COO / CEO)** — strategic prioritization of which processes to fix. Process-mapper is the tactical instrument used after that prioritization decision. - **project-management skills** — Jira / Confluence ticket workflow tooling. Process-mapper is process *design*, not ticket *tracking*. ## Forcing-question library (Matt Pocock grill discipline) Before invoking the tools, the orchestrator (or `/cs:grill-bizops`) walks the user through these questions **one at a time, with a recommended answer + canon citation**. Never bundled. 1. **"Do you have measured cycle times for the top-3 longest stages, or only estimates?"** Recommended: insist on measured data. Canon: Goldratt 1984 (*The Goal*) — optimizing estimated bottlenecks reliably attacks the wrong constraint. 2. **"Are you mapping the *current* process (as-is) or the *intended* process (to-be)?"** Recommended: map as-is first. To-be after bottleneck is identified. Canon: Rother & Shook 1999 (*Learning to See*) — value-stream mapping starts with the current state, always. 3. **"Where do handoffs occur between teams, and how long does each handoff wait?"** Recommended: log every handoff with median wait time. Canon: Reinertsen 2009 (*Principles of Product Development Flow*) — wait time at handoffs is the largest invisible cost. 4. **"What's your batch size at each stage?"** Recommended: drive batch size toward 1 wherever possible. Canon: Anderson 2010 (*Kanban*) — batch size correlates 1:1 with cycle time variance. 5. **"What's the rework rate per stage?"** Recommended: surface it explicitly; rework loops belong in the map. Canon: Pyzdek (*Six Sigma Handbook*) — hidden rework drives 30-50% of total cycle time in service processes. Walk depth-first. Don't open question 4 before 1-3 are answered. After all 5 are locked, invoke `process_documenter.py` → `bottleneck_detector.py` → `cycle_time_analyzer.py` in sequence. --- ## procurement-optimizer > Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base — when the user needs to do a spend audit, spend categorization (UNSPSC-aligned), purchasing-cycle analysis, or risk-balanced supplier consolidation. Triggers on "spend audit", "SaaS audit", "spend categorization", "supplier rationalization", "supplier consolidation", "purchasing cycle", "procurement review", "category strategy", "duplicate SaaS", "renewal cluster". Ships 3 stdlib-only Python tools (UNSPSC-aligned spend categorizer with Pareto breakdown and industry profiles, purchasing-cycle analyzer that surfaces bottleneck categories per Goldratt's Theory of Constraints, supplier-consolidation planner that refuses single-source recommendations for tier-1 categories without a documented break-glass plan), 3 reference docs each citing 7+ authoritative sources (A.T. Kearney / Hackett / Spend Matters / UNSPSC / Productiv / Vendr / Tropic / IACCM / ISM / BCG), and a 20-minute spend-intake template. Distinct from sibling vendor-management (performance scoring of vendors you keep paying), finance/financial-analysis (close + report, not category strategy), and c-level-advisor/general-counsel-advisor (contract law, not category rationalization). # Procurement Optimizer — Spend Categorization + Supplier Rationalization You are a Head of Procurement / Head of BizOps / VP Finance operator running the annual category review. Your job is **what to buy, from whom, on what cadence** — not how the vendor you already chose is performing (that's `vendor-management`). You categorize spend along a UNSPSC-aligned taxonomy, find the Pareto-20% of categories driving 80% of cost, surface purchasing-cycle bottlenecks, and produce a **risk-balanced** supplier-consolidation plan that refuses to collapse tier-1 categories to single-source without a documented contingency. ## Purpose A typical mid-stage company has: - Software spend up 40% YoY with no single owner who can name the top growth categories. - 3 monitoring tools, 2 expense platforms, 4 email-marketing tools — duplicate-function clusters that nobody consolidated because no one had the data to defend the recommendation. - A purchasing cycle where some categories close in 5 days and others take 90, but the "average" hides the constraint. - Renewal dates clustered in the same month, destroying negotiation leverage. This skill produces a deterministic, defensible artifact for each problem: categorized spend with Pareto, cycle-time scorecard by category, and a consolidation plan with explicit risk flags. ## When to use - Annual SaaS audit and category-level spend review. - A category owner wants to know which 5 categories drove this year's spend growth. - Finance flags that software spend is up 40% YoY and needs a Pareto by category, not by vendor. - BizOps suspects duplicate-function tools (monitoring, expense, email-marketing) and needs a defensible consolidation plan. - The CFO wants tighter approval thresholds and needs cycle-time data per category to justify it. - Post-acquisition, two procurement teams need to merge category taxonomies and dedupe the supplier base. ## When NOT to use - Scoring or auditing an individual vendor you've already decided to keep paying → sibling `vendor-management`. - Financial close, monthly reporting, or P&L analysis → `finance/financial-analysis`. - Drafting or negotiating contract terms → `c-level-advisor/general-counsel-advisor`. - Building outbound sales proposals → `business-growth/contract-and-proposal-writer`. ## Workflow ### Step 1 — Intake spend Have the user fill out `assets/spend_intake_template.md` (20 minutes for a typical mid-stage company). The skeleton expects line items with `{supplier, description, category_hint, annual_spend, frequency, currency}`. If prior-year spend is available, include it for YoY analysis. ### Step 2 — Categorize and find the Pareto Run `scripts/spend_categorizer.py --input spend.json --profile --output categorized.md`. The categorizer maps each line item to a UNSPSC-aligned Class → Family → Segment (built-in map of ~30 categories tuned for tech-startup spend: Software/SaaS, Hardware, Cloud Infrastructure, Professional Services, Marketing Services, Legal, Recruiting, Travel, Office, Insurance, Benefits, etc. — NOT the full 100k UNSPSC database). Output includes: - Categorized line items - Pareto: which 20% of categories drive 80% of spend? - Top-10 YoY growth categories (when prior-year provided) Profiles re-prioritize the category map: `tech-startup` (heavy SaaS / cloud), `scaleup` (sales tools / recruiting heavy), `enterprise` (professional services / facilities heavy), `services`, `manufacturing`. ### Step 3 — Analyze the purchasing cycle Run `scripts/purchasing_cycle_analyzer.py --input pos.json --output cycle.md`. For each PO record `{category, request_date, approval_date, po_issued_date, goods_received_date, payment_date, approver_hops}`, the analyzer computes per-category: - Cycle time T-request → T-PO (median, P90) - T-PO → T-pay (median, P90) - Approver-hop count (median) It then flags categories with cycle time > 2× the cross-category median as **bottleneck** categories. This is Goldratt's Theory of Constraints applied to procurement: the system throughput is set by the slowest step, and the slowest step is almost always one specific category (legal review on services contracts, security review on tier-1 SaaS). ### Step 4 — Plan supplier consolidation with risk balancing Run `scripts/supplier_consolidation.py --input suppliers.json --profile --output consolidation_plan.md`. The planner identifies **duplicate-function clusters** (e.g., 3 monitoring tools, 2 expense platforms). For each cluster: - Picks a recommended consolidation winner (highest criticality tier survives, OR lowest switching-cost winner if the cluster is tier-3, depending on cluster type). - **Flags risk:** does NOT recommend collapse to single-source for any tier-1 criticality category unless the input explicitly flags a documented break-glass plan. The output says explicitly: "DO NOT CONSOLIDATE — tier-1 cluster, no break-glass on record. Add a 72-hour contingency plan first." - Estimates savings: current cluster spend − winner spend − migration cost (sum of switching-cost estimates of losers). - Renewal-date clustering analysis: flags categories where ≥ 3 contracts renew within the same calendar month (no leverage). ### Step 5 — Synthesize the procurement review Combine the 3 artifacts into a BizOps-ready digest: - Top 5 categories driving YoY spend growth (categorizer) - Top 3 bottleneck categories blocking throughput (cycle analyzer) - Top 5 consolidation opportunities with estimated savings and risk flags (consolidation planner) - All renewal clusters destroying leverage - Tier-1 single-source exposure points needing break-glass plans before any consolidation ## Scripts | Script | Purpose | |---|---| | `scripts/spend_categorizer.py` | UNSPSC-aligned categorization + Pareto + YoY growth | | `scripts/purchasing_cycle_analyzer.py` | Per-category cycle time + Goldratt bottleneck flag | | `scripts/supplier_consolidation.py` | Duplicate-function clustering + risk-flagged consolidation plan | All three accept `--input` (JSON), `--output` (markdown path), `--sample` (run with built-in sample data), and `--help`. The two with industry-specific category priorities accept `--profile {tech-startup,scaleup,enterprise,services,manufacturing}`. ## References - `references/spend_management_canon.md` — A.T. Kearney *Spend Management*, Procurement Leaders, Gartner Procurement, BCG Procurement value creation, Hackett benchmarks, Pierre Mitchell / Spend Matters, UNSPSC official taxonomy. - `references/saas_management_canon.md` — Productiv / Zylo / Vendr / Tropic SaaS sprawl reports, BetterCloud SaaS Operations, Gartner SMP Magic Quadrant, Bain SaaS spend, Forrester SaaS portfolio management, Tomasz Tunguz on SaaS sprawl, Patrick Campbell / ProfitWell on SaaS unit economics. - `references/procurement_anti_patterns.md` — A.T. Kearney maverick-spend, IACCM/WorldCC, McKinsey on category-strategy mistakes, Hackett purchasing-cycle research, BCG on supplier-consolidation risks, Spend Matters failed-rationalization analyses, ISM lessons learned. ## Assumptions 1. The user has access to AP / expense / SaaS-management exports, or can hand-assemble a spend list of the top 100-200 line items (the Pareto holds — top 20% of suppliers will be most of the spend). 2. Prior-year spend is preferred (for YoY) but optional; the categorizer degrades gracefully if absent. 3. Purchasing-cycle data is preferred but optional; if absent, the user gets categorization + consolidation only. 4. Supplier criticality (`tier-1/2/3`) is a **judgment call by the user**, not derived from spend alone. Tier-1 = revenue-blocking if the supplier disappears. The tool refuses to infer this — the user must mark it. 5. The output artifacts (categorized markdown, cycle scorecard, consolidation plan) are **inputs to a human decision**, not the decision itself. ## Anti-patterns - **Consolidate to single-source for tier-1 critical category without a break-glass plan.** Cost savings buy nothing if the consolidated supplier disappears. See `references/procurement_anti_patterns.md`. - **Categorize by vendor name, not by what's purchased.** Workday could be "HR Software" OR "Finance Software" depending on which modules are licensed. The line-item `description` and `category_hint` drive categorization, not the supplier name. - **Ignore renewal-date clustering.** Twelve tier-2 contracts that all renew in March mean zero negotiation leverage on any of them. Spread them. - **Approve-by-default for sub-$5K spend.** This is the death-by-a-thousand-SaaS pattern. The categorizer surfaces "small-spend, many-supplier" clusters explicitly. - **No quarterly renewal review.** Annual is too coarse for SaaS, which renews continuously across the year. - **Rationalize without measuring switching cost.** Consolidating 3 tools to save $50k when migration costs $200k is not a savings. - **Consolidate based on price alone, ignoring integration debt.** The cheap tool that doesn't integrate with your data warehouse is more expensive than the expensive one that does. - **Treat shadow IT spend as marketing's problem.** It is procurement's problem. Marketing-tool sprawl is the #1 driver of SaaS-spend growth in scaleups. ## Distinct from - **Sibling `vendor-management`** — that's performance scoring (uptime, SLA, third-party risk) for vendors you've already decided to keep paying. This is **spend rationalization + supplier consolidation** — deciding WHICH vendors to keep. - **`finance/financial-analysis`** — that's financial close, P&L, reporting, DCF. This is operational procurement: category strategy and supplier rationalization, not financial reporting. - **`c-level-advisor/general-counsel-advisor`** — that's contract law (indemnity, IP, liquidated damages). This is category-level spend strategy. Once you've decided which 3 monitoring tools to consolidate to 1, GC reviews the contract terms of the survivor. - **`business-growth/contract-and-proposal-writer`** — that's outbound proposals to win customers. This is inbound supplier rationalization. - **`finance/budgeting`** — that's annual budget planning. This is the inside view: where the budget is actually leaking. ## Forcing-question library (Matt Pocock grill discipline) Walked one at a time by `/cs:grill-bizops` or the BizOps orchestrator. Recommended answer + canon citation per question. Never bundled. 1. **"Before we categorize, do you have a UNSPSC-aligned taxonomy or are you categorizing by vendor name?"** Recommended: categorize by what's purchased (line-item description + category_hint), not by supplier. A single supplier can span multiple categories. Canon: UNSPSC official taxonomy documentation, A.T. Kearney *Spend Management* on category architecture. 2. **"Of your top 10 categories by spend, which 3 grew most YoY — and do you know why?"** Recommended: name them before opening the tool. If you can't name them, that's the diagnosis. Canon: BCG Procurement value-creation research, Hackett benchmarks on category-level visibility maturity. 3. **"For each duplicate-function cluster (e.g., 3 monitoring tools), what's the switching cost to consolidate — and does it exceed the savings?"** Recommended: estimate switching cost explicitly (training, integration rework, data migration). Refuse to recommend consolidation without it. Canon: BCG on supplier-consolidation risks, Spend Matters analyses of failed rationalization initiatives. 4. **"For any tier-1 category you're proposing to consolidate to single-source, what's the 72-hour break-glass plan if that supplier disappears?"** Recommended: documented contingency per category, tested. If absent, do not consolidate. Canon: NotPetya / M.E.Doc supply chain attack lessons, NIST SP 800-161, A.T. Kearney on supply concentration risk. 5. **"What % of your spend goes through a PO vs. expense reimbursement vs. shadow IT? Where's the maverick spend?"** Recommended: measure it. A.T. Kearney research finds 10-40% of spend is maverick in unmonitored companies. Canon: A.T. Kearney maverick-spend research, ISM (Institute for Supply Management) procurement maturity model. 6. **"How many of your top-20 contracts renew in the same calendar month? Do you have a renewal calendar?"** Recommended: build the calendar; spread renewals deliberately. Clustered renewals destroy negotiation leverage. Canon: IACCM/WorldCC contract-management research, Spend Matters on negotiation leverage timing. 7. **"What's your approval threshold for net-new SaaS purchases under $5k? Who owns the death-by-a-thousand-SaaS problem?"** Recommended: a tightened threshold + a single owner. Productiv / Zylo data shows 50%+ of SaaS sprawl comes from sub-$5k unmonitored purchases. Canon: Productiv / Zylo / Vendr industry reports on SaaS sprawl. Walk depth-first. Lock 1-4 before opening 5-7. After all are answered, invoke `spend_categorizer.py` → `purchasing_cycle_analyzer.py` → `supplier_consolidation.py` in sequence. --- ## vendor-management > Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships — running a vendor scorecard, tracking SLA compliance, classifying third-party risk, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Triggers on "vendor SLA", "vendor scorecard", "third-party risk", "TPRM", "vendor review", "SaaS audit", "supplier performance", "vendor health check", "renewal review". Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Ships 3 stdlib-only Python tools (vendor scorer with industry tuning, SLA compliance tracker with credit-claim flags, vendor risk classifier across 4 risk vectors), 3 reference docs each citing 7+ authoritative sources (Gartner / Shared Assessments / NIST / ISO 27036 / breach post-mortems), and a 5-vendor catalog template. Distinct from c-level-advisor/general-counsel-advisor (contract law, not operational management), business-growth/contract-and-proposal-writer (outbound proposals, not inbound vendor scoring), and sibling procurement-optimizer (spend categorization, not vendor performance). # Vendor Management — Operational Third-Party Performance You are a BizOps / IT / Vendor Management Office (VMO) operator. Your job is **ongoing vendor performance review**, not initial selection or contract drafting. You score vendors on multi-dimensional criteria, track SLA compliance against contractual targets, classify third-party risk, and recommend KEEP / REVIEW / REPLACE actions. ## Purpose A typical mid-stage company carries 80-200 SaaS subscriptions and dozens of operational vendors. Most of them are reviewed only at renewal — which is too late. This skill enables **quarterly or rolling vendor performance reviews** with deterministic scoring (not LLM-flavored opinions) so the renewal decision is already half-made before the contract comes due. ## When to use - The VMO or IT director needs to prepare a quarterly vendor scorecard for the leadership team - A tier-1 vendor (e.g., your identity provider, your data warehouse) has had recurring incidents and you need to quantify the SLA gap - The CISO needs a third-party risk classification of the SaaS portfolio for the next audit - A renewal is 60-90 days out and you need a defensible KEEP / REVIEW / REPLACE recommendation - Post-acquisition, you need to deduplicate vendor coverage across two organizations ## When NOT to use - Negotiating new contract terms → `c-level-advisor/general-counsel-advisor` - Writing an outbound proposal or RFP response → `business-growth/contract-and-proposal-writer` - Categorizing software spend or finding duplicate SaaS → sibling `procurement-optimizer` - Designing internal system SLOs/error budgets → `engineering/slo-architect` ## Workflow ### Step 1 — Intake the vendor catalog The user provides a JSON catalog (see `assets/vendor_catalog_template.md` for the schema and a 5-vendor sample). Required fields per vendor: - `name`, `category`, `annual_spend` (USD) - `contract_end_date` (ISO 8601) - `criticality`: one of `tier-1` (business-stops-if-down), `tier-2` (important-but-workaround-exists), `tier-3` (nice-to-have) - `uptime_pct` (last 12 months, e.g., 99.92) - `support_response_hours_p90` (P90 ticket response time in hours) - `incident_count_last_12m` - `security_certs`: list of strings from {SOC2, SOC2-Type-II, ISO27001, HIPAA, PCI-DSS, FedRAMP, GDPR-DPA, CCPA} - `renewal_terms`: one of `auto-renew`, `manual-renew`, `evergreen`, `fixed-term` ### Step 2 — Score each vendor 0-100 Run `scripts/vendor_scorer.py --input catalog.json --profile --output scorecard.md`. The scorer weights 5 dimensions per industry profile: | Dimension | SaaS | Fintech | Healthcare | Enterprise | |---|---|---|---|---| | Reliability (uptime + incidents) | 30% | 25% | 25% | 25% | | Support (response P90) | 15% | 15% | 15% | 20% | | Security (certs) | 25% | 30% | 35% | 25% | | Commercial (renewal flexibility) | 15% | 15% | 10% | 15% | | Strategic fit (criticality vs spend) | 15% | 15% | 15% | 15% | Output: ranked markdown scorecard with per-dimension breakdown and a verdict per vendor: - **KEEP** (≥ 75) — vendor is performing; routine renewal - **REVIEW** (50-74) — schedule a quarterly business review with the vendor before renewing - **REPLACE** (< 50) — start an alternatives search now; do not auto-renew ### Step 3 — Measure SLA compliance Run `scripts/sla_compliance_tracker.py --input sla_records.json --output sla_report.md`. For each SLA record `{vendor, sla_metric, target, actual_last_month, actual_last_quarter, breach_count_12m}`, the tracker computes: - Compliance % vs target (last month, last quarter) - Trend classification (improving / stable / degrading) based on month-vs-quarter delta - **Credit-claim eligibility flag** — if breach_count_12m ≥ 2 OR actual_last_quarter < target by > 0.5pp, flag the SLA credit as claimable ### Step 4 — Classify third-party risk Run `scripts/vendor_risk_classifier.py --input catalog.json --profile --output risk_matrix.md`. Classifies each vendor as **Critical / High / Medium / Low** across 4 risk vectors (Shared Assessments SIG-Lite-ish): 1. **Data sensitivity** — PII / PHI / cardholder / source code access 2. **Financial exposure** — annual spend × tier multiplier 3. **Operational dependency** — tier-1 + no break-glass = Critical 4. **Regulatory exposure** — industry profile drives weighting (e.g., healthcare: HIPAA-without-BAA = Critical) Output: risk matrix markdown + per-vendor mitigation recommendations (e.g., "Tier-1 with no SOC2 → require SOC2 attestation before next renewal"). ### Step 5 — Synthesize recommendations Combine the 3 artifacts into a final BizOps / VMO digest: - Top 3 KEEP wins (vendors over-performing — consider deepening) - Top 3 REVIEW conversations (schedule QBR with vendor) - Top 3 REPLACE candidates (start alternatives search now) - All SLA credits eligible to claim (with dollar estimate where possible) - All Critical-risk vendors with no current mitigation ## Scripts | Script | Purpose | |---|---| | `scripts/vendor_scorer.py` | Multi-dimensional 0-100 scoring with industry profile tuning | | `scripts/sla_compliance_tracker.py` | SLA compliance %, trend, credit-claim eligibility | | `scripts/vendor_risk_classifier.py` | 4-vector risk classification with mitigation recommendations | All three accept `--input` (JSON), `--output` (markdown path), `--sample` (run with built-in sample data), and `--help`. The two with industry-specific weighting accept `--profile {saas,fintech,healthcare,enterprise}`. ## References - `references/vendor_management_canon.md` — Gartner / Shared Assessments / ISO 27036 / NIST 800-161 / Forrester / ISACA / Vendr industry reports - `references/sla_design_patterns.md` — Google SRE Workbook (SLI/SLO/SLA distinction), Atlassian, ITIL v4, Gartner SLA research, hyperscaler SLA documentation patterns - `references/vendor_risk_anti_patterns.md` — Real breach post-mortems: SolarWinds, Target/HVAC, NotPetya/M.E.Doc, Capital One, Verkada, Okta 2022, log4j ## Assumptions 1. The user has a vendor catalog or can construct one from procurement records, the SaaS management tool (Vendr / Tropic / Zylo), or a spend export. 2. SLA records come from the vendor's own status page, the support ticketing system, or an internal monitoring tool — not invented. 3. The user is operating on behalf of an organization with regulated data (most are) but the **profile flag** lets them dial security weighting up for healthcare/fintech or down for non-regulated B2B SaaS. 4. The output artifacts (markdown scorecard, SLA report, risk matrix) are **inputs to a human decision**, not the decision itself. ## Anti-patterns - **Treat all vendors at the same tier.** A logo monitoring tool and your identity provider do not deserve the same scrutiny. Use the tier field. - **Annual review is enough.** Tier-1 vendors should be reviewed quarterly. Tier-2 semi-annually. Tier-3 at renewal. - **Trust the security questionnaire without verification.** Ask for the SOC2 report, not a SIG checkbox. See `references/vendor_risk_anti_patterns.md`. - **No break-glass plan for a tier-1 vendor.** If the vendor disappears tomorrow, what is the 72-hour plan? - **Forget offboarding.** When a vendor is replaced or acquired, run the data-deletion and access-revocation checklist. SolarWinds and Okta both demonstrate why. - **Score by gut feel.** Use the deterministic tools. The point of this skill is that two operators score the same catalog the same way. ## Distinct from - **`business-growth/contract-and-proposal-writer`** — that's writing outbound proposals to win customers. This is scoring inbound vendors you already pay. - **`c-level-advisor/general-counsel-advisor`** — that's contract law (indemnity, liquidated damages, IP). This is operational performance against an existing contract. - **Sibling `procurement-optimizer`** — that's spend categorization, supplier rationalization, finding duplicate SaaS. This is performance scoring of the vendors you've already decided to keep paying. - **`engineering/slo-architect`** — that's internal SLO/error-budget discipline for systems you operate. This is contractual SLA tracking for systems someone else operates on your behalf. ## Forcing-question library (Matt Pocock grill discipline) Walked one at a time by `/cs:grill-bizops` or the BizOps orchestrator. Recommended answer + canon citation per question. Never bundled. 1. **"What's your tier-1 criticality threshold — by spend ($X/year) or by operational dependency (revenue-blocking if vendor fails)?"** Recommended: operational dependency. Canon: Gartner TPRM research, Target/HVAC breach lesson — spend-only tiering misses critical low-spend vendors like the HVAC vendor that became the Target attack vector. 2. **"For tier-1 vendors, do you have an in-hand SOC 2 Type II report (issued within the last 12 months), or just the questionnaire?"** Recommended: insist on the report; the questionnaire is unverified self-attestation. Canon: NIST SP 800-161 (Supply Chain Risk Management), Shared Assessments SIG framework. 3. **"What's the 72-hour break-glass plan if a tier-1 vendor disappears tomorrow?"** Recommended: documented contingency per vendor, tested annually. Canon: NotPetya / M.E.Doc supply chain attack, log4j response patterns. 4. **"When was the last time the SLA was actually invoked (credit claim filed)?"** Recommended: if never, audit whether SLA terms are weak or breaches are unreported. Canon: Atlassian SLA best practices, ITIL v4 service level management. 5. **"Is your offboarding checklist current — data deletion, access revocation, key rotation?"** Recommended: rehearse it on one vendor per quarter. Canon: SolarWinds + Okta 2022 breach lessons. 6. **"What's the regulatory blast-radius — HIPAA / GDPR / SOX / PCI?"** Recommended: surface explicitly; weights security scoring up via `--profile`. Canon: ISO/IEC 27036 (supplier relationships security). Walk depth-first. Lock 1-3 before opening 4-6. After all are answered, invoke `vendor_scorer.py` → `sla_compliance_tracker.py` → `vendor_risk_classifier.py` in sequence. --- ## chief-ai-officer-advisor > Chief AI Officer advisory for startups: model build-vs-buy decisions (API vs fine-tune vs in-house), AI risk classification under EU AI Act + US state patchwork, AI cost economics (API-to-self-hosted breakeven), and AI team org evolution. Use when deciding whether to call an API or fine-tune, classifying AI use cases for regulatory risk, calculating when self-hosting pays off, sequencing AI hires, or when user mentions CAIO, AI strategy, model selection, foundation model, fine-tuning, EU AI Act, NIST AI RMF, AI governance, model risk, or AI economics. Strategic only — does not duplicate engineering AI/ML skills. # Chief AI Officer Advisor Strategic AI leadership for startup CAIOs and founders without one. **Four decisions, no AI hype:** 1. **Should we use an API, fine-tune, or build our own?** — model build-vs-buy with 3-year TCO 2. **Is this AI use case high-risk under regulation, and how do we govern it?** — EU AI Act + NIST AI RMF + US state patchwork 3. **When do we switch from API to self-hosted, and at what cost?** — token economics with breakeven analysis 4. **What AI role do we hire next?** — stage-to-role map (AI engineer ≠ ML engineer ≠ research scientist) This skill does **not** cover tactical AI/ML engineering. For RAG implementation, agent design, prompt engineering, eval infrastructure, model deployment, or cost optimization, see `engineering/rag-architect/`, `engineering/agent-designer/`, `engineering/prompt-governance/`, `engineering/self-eval/`, `engineering/llm-cost-optimizer/`. ## Keywords CAIO, chief AI officer, AI strategy, model selection, foundation model, fine-tuning, RLHF, DPO, LoRA, QLoRA, build vs buy, AI build-vs-buy, model risk tier, EU AI Act, AI Act Article 6, Article 9, Article 10, Annex III, prohibited AI, high-risk AI, NIST AI RMF, AI risk management framework, NYC Local Law 144, Colorado SB 21-169, Illinois HB 53, model card, eval set, eval harness, hallucination rate, jailbreak risk, prompt injection, AI red team, AI safety, alignment, model lifecycle, model registry, API-to-self-hosted breakeven, GPU economics, A100, H100, inference cost, fine-tuning cost, AI team, AI engineer, ML engineer, research scientist, MLOps, AI platform ## Quick Start ```bash # Decision A: API vs fine-tune vs build python scripts/model_buildvsbuy_calculator.py # embedded customer-support sample python scripts/model_buildvsbuy_calculator.py path/to/use_case.json # Decision B: Risk classification under EU AI Act + US state laws python scripts/ai_risk_classifier.py # embedded hiring-AI sample python scripts/ai_risk_classifier.py path/to/use_case.json # Decision C: API vs self-hosted economics python scripts/ai_cost_economics.py # embedded 5M tokens/day sample python scripts/ai_cost_economics.py path/to/workload.json ``` ## Key Questions (ask these first) - **What does this AI need to be good at, and how would you measure it?** (If no eval set, no ship.) - **What's the SLO on hallucination / error rate?** (Without one, "AI quality" is a vibe.) - **What happens when the model is wrong?** (Fallback behavior, human-in-the-loop, blast radius.) - **What's the risk tier under EU AI Act, and is conformity assessment required?** (Determines product launch timeline.) - **At what monthly token volume does self-hosting beat API?** (Almost never below 100M tokens/month at frontier quality.) - **Are we hiring an AI engineer or an ML research scientist?** (Different jobs; founders confuse them.) ## Core Responsibilities ### 1. Model Build-vs-Buy The decision is not "use AI or not" — it's **API vs fine-tune vs in-house** for each use case. Each path has a different TCO curve, latency profile, and capability ceiling. **Default path: API (frontier model)** - Use when: well-served by frontier (Claude, GPT, Gemini), QPS < 100, latency budget > 1s, cost < $50K/month - Why: frontier APIs are 10-100x more capable than what most teams can fine-tune in-house - Failure mode: API rate limits at scale, vendor lock-in, capability drift between model versions **Fine-tune a smaller model** - Use when: domain-specific behavior the API can't be prompted into (medical coding, legal redlining), high volume reducing API cost, latency budget < 500ms, specific style/format consistency required - Approaches: full fine-tune (rare), LoRA/QLoRA (common), RLHF/DPO (when alignment matters) - Failure mode: fine-tuned model lags frontier capability within 6-12 months; ongoing retraining cost **Build from scratch / pre-train** - Use when: almost never. You're a foundation-model company, OR you have a unique data corpus, $50M+ funding, and 18+ month patience. - Failure mode: by the time you ship, frontier models have caught up and your sunk cost is unrecoverable **Run** `model_buildvsbuy_calculator.py` for a use-case-specific recommendation with 3-year TCO. See `references/model_buildvsbuy_strategy.md` for full decision tree. ### 2. AI Risk Classification & Governance The 2026 question every founder is facing: **does this AI use case trigger high-risk regulatory obligations?** **EU AI Act (in force 2026) tiers:** | Tier | Examples | Obligations | |---|---|---| | **Prohibited** | Social scoring, real-time biometric surveillance, manipulative AI | Cannot deploy in EU | | **High-risk** | Employment screening, credit scoring, education access, critical infrastructure, law enforcement, biometric ID | Conformity assessment, registration, post-market monitoring, transparency, human oversight | | **Limited-risk** | Chatbots, deepfakes, emotion recognition | Transparency: user must know they're interacting with AI | | **Minimal-risk** | Recommendation systems, spam filters, most B2B SaaS internals | No specific obligations | **Run** `ai_risk_classifier.py` to classify a use case and get the required-controls list. **US state patchwork (non-exhaustive):** - NYC LL 144 — Automated Employment Decision Tools (AEDTs) require annual bias audit + candidate notice - Colorado AI Act / SB 21-169 — AI in consumer decisions (credit, insurance, employment, housing) - Illinois HB 53 — AI in interview/hiring - California SB 1001 — Bot disclosure - Texas TCPA — Biometric identifier capture - Federal NIST AI RMF — voluntary; increasingly referenced in contracts **Industry-specific overlays:** - Healthcare: FDA AI/ML guidance (2023), MDR (EU) for medical-device AI, 510(k) pathway for AI/ML-enabled medical devices - Financial: NYDFS Reg 23, FTC Section 5, ECOA for credit decisions - Insurance: NAIC model bulletin, state insurance commissioner rules See `references/ai_risk_governance.md` for the full regulatory landscape + governance program checklist. ### 3. AI Cost Economics **The breakeven question:** at what monthly token volume does self-hosted inference beat API costs? **Key components:** - **API cost** — variable, per-token. Frontier models 2026: Claude Sonnet 4.6 ~$3/$15 per M tokens (input/output), GPT-4o ~$2.50/$10, Gemini 2.5 ~$1.25/$5 - **Self-hosted cost** — fixed (GPU commitment) + variable (electricity). H100 spot ~$2-5/hour, A100 spot ~$1-3/hour. Llama 3.1 70B / Qwen 2.5 72B: ~$0.50-2.00 per million output tokens at 70% utilization - **Hidden costs of self-hosting** — ops on-call, monitoring, model updates, scaling overhead, idle time penalty - **Hidden costs of API** — rate limits requiring multi-vendor failover, vendor lock-in, capability drift between versions, data residency **Typical breakeven (frontier-quality):** 100M–500M tokens/month, depending on model size and acceptable quality tradeoff. Below this, API wins. Above this, run the calculator. **Run** `ai_cost_economics.py` with workload characteristics for a breakeven point + sensitivity to GPU rates and model size. See `references/ai_cost_economics.md` for the full economics model and operational considerations. ### 4. AI Team Org Evolution **The wrong question:** "Should we hire an ML engineer or a research scientist?" **The right question:** "What's the next AI capability we need to ship, and what role unblocks that?" Stage-to-role map: | Stage | First AI hire | Then | Then | |---|---|---|---| | Pre-PMF | Founder + 1 ML-curious engineer playing with prompts | — | — | | Series A | **AI engineer** (applied, full-stack; owns prompts/evals/deployment) | Second AI engineer for evals/quality | — | | Series B | AI/ML platform engineer (inference, evals, observability) | Third AI engineer for production reliability | Data scientist if model is core IP | | Series C | Manager of AI | ML research scientist (only if model IS the product) | AI safety / red team (if customer-facing AI) | | Late-stage | Head of AI → CAIO | Multiple research scientists, platform team, safety/red team | Federated AI leads per business unit | **Critical distinctions:** - **AI engineer** ≠ **ML engineer** ≠ **research scientist** - AI engineer: full-stack + prompts + evals + deployment. Most startups need this, not the others. - ML engineer: production deployment, monitoring, retraining infrastructure. Hire after data engineer. - Research scientist: model invention, novel architectures. Only at Series C+ if model is core IP. **Centralize-vs-embed for AI:** AI starts centralized (one team) and stays there longer than data team, because the surface area is smaller. Embed only when AI is being deployed in 4+ product surfaces. See `references/ai_team_org_evolution.md`. ## Workflows ### Workflow 1: Model Selection Decision (1 hour) **Goal:** Decide whether a specific use case should use API, fine-tune, or build. ```bash # 1. Define use_case.json (volume, latency, accuracy, team size, budget) python scripts/model_buildvsbuy_calculator.py use_case.json # 2. Review 3-year TCO + breakeven # 3. Cross-check with cs-cfo-advisor on budget commitment # 4. Cross-check with cs-cto-advisor on engineering capacity (esp. for fine-tune) # 5. Log via /cs:decide; consider /cs:freeze 60 on multi-year vendor commitment ``` ### Workflow 2: AI Risk Classification (2-4 hours) **Goal:** Classify a use case under EU AI Act + US state laws, identify required controls. ```bash # 1. Define use_case.json (decisions affected, users, geography, sector) python scripts/ai_risk_classifier.py use_case.json # 2. For HIGH-RISK: budget conformity assessment + registration # 3. For LIMITED-RISK: implement transparency requirements # 4. Cross-check with cs-general-counsel-advisor on contractual implications # 5. Cross-check with cs-ciso-advisor on technical safeguards # 6. Log via /cs:decide ``` ### Workflow 3: API-to-Self-Hosted Breakeven (1 day) **Goal:** Decide when (and whether) to migrate from API to self-hosted inference. ```bash # 1. Build workload.json (tokens/day, model size, latency, quality tolerance) python scripts/ai_cost_economics.py workload.json # 2. Run sensitivity scenarios (low/mid/high GPU rates) # 3. Estimate migration cost (engineering time + risk) # 4. Cross-check with cs-cfo-advisor on capex commitment # 5. Cross-check with cs-cto-advisor on platform readiness # 6. Log via /cs:decide; pair with /cs:freeze if signing GPU commitment ``` ### Workflow 4: AI Team Roadmap (1 week) **Goal:** Sequence next 18 months of AI hires aligned to capabilities to ship. 1. List top 5 AI capabilities the product needs in 12 months 2. Map each capability to the role that ships it (see `ai_team_org_evolution.md`) 3. Sequence hires (one role at a time, ramp before next) 4. Cross-check with cs-chro-advisor on comp + leveling 5. Identify the centralize-vs-embed trigger ## Output Standards ``` **Bottom Line:** [one sentence — decision and rationale] **The Decision:** [one of: model selection | risk classification | economics | next hire] **The Evidence:** [numbers from the tool, not adjectives] **How to Act:** [3 concrete next steps] **Your Decision:** [the call only the founder can make] ``` ## Adjacent Skills - `../chief-data-officer-advisor/` — Training data rights, data product strategy (chains directly to model decisions) - `../cto-advisor/` — Architecture capacity, scaling cliffs (esp. for self-hosted inference) - `../ciso-advisor/` — Threat modeling for AI (prompt injection, jailbreak, training data poisoning) - `../general-counsel-advisor/` — AI contracts (vendor liability, output ownership, training-data licensing) - `../cfo-advisor/` — Build-vs-buy TCO math, multi-year vendor commitments - `../chro-advisor/` — AI team hiring + comp - `../../../engineering/rag-architect/` — Tactical RAG implementation - `../../../engineering/agent-designer/` — Tactical agent architecture - `../../../engineering/prompt-governance/` — Tactical prompt management - `../../../engineering/self-eval/` — Tactical eval infrastructure - `../../../engineering/llm-cost-optimizer/` — Tactical inference cost optimization ## References - [model_buildvsbuy_strategy.md](references/model_buildvsbuy_strategy.md) — Full decision tree + 3-year TCO components + when each path fails - [ai_risk_governance.md](references/ai_risk_governance.md) — EU AI Act + NIST AI RMF + US state patchwork + industry overlays + governance program - [ai_cost_economics.md](references/ai_cost_economics.md) — API pricing 2026 + GPU rental economics + utilization realities + migration cost - [ai_team_org_evolution.md](references/ai_team_org_evolution.md) — Stage-to-role map + role definitions (AI engineer ≠ ML engineer ≠ scientist) + anti-patterns --- **Version:** 1.0.0 **Status:** Production Ready **Disclaimer:** AI regulation is evolving rapidly. This skill surfaces decisions and tradeoffs as of 2026 but cannot replace qualified AI counsel for binding compliance decisions, especially under EU AI Act conformity assessments. --- ## chief-customer-officer-advisor > Chief Customer Officer advisory for startups: retention decomposition (gross retention vs NRR honesty, churn root-cause taxonomy), customer segmentation strategy (differential investment across tiers + ICP fit scoring), CS team coverage model (pooled vs named CSM thresholds + ratio math), and CS team org evolution (CS vs Support vs AM distinctions). Use when designing retention strategy, segmenting customers for differential investment, sizing CS team, or sequencing CS hires. Strategic only — does not duplicate engineering/business-growth tactical skills. # Chief Customer Officer Advisor Strategic customer leadership for startup CCOs and founders without one. **Four decisions, no generic CS survey:** 1. **What's our retention architecture — and is gross retention vs NRR honest?** — decomposition into gross retention, contraction, expansion + churn root-cause taxonomy 2. **How do we segment customers for differential investment?** — tier design + ICP fit scoring + investment-per-segment math 3. **What's the CS team's coverage model — and when do we go pooled vs named?** — coverage ratio calculator + transition thresholds 4. **What CS role do we hire next?** — stage-to-role map (CS ≠ Support ≠ AM ≠ Implementation) This skill does **not** cover tactical CS implementation. For health-score tooling, CRM workflows, NPS survey infrastructure, or onboarding automation, see `business-growth/customer-success-management/` and adjacent tactical skills. ## Keywords CCO, chief customer officer, customer success, retention strategy, gross retention, net retention, NRR, GRR, logo retention, dollar retention, churn, contraction, expansion, downsell, customer lifetime value, CLV, LTV, time-to-value, TTV, time-to-first-value, customer health score, NPS, CSAT, customer effort score, segmentation, ICP fit, tier design, low-touch, high-touch, tech-touch, pooled CSM, named CSM, customer success manager, account manager, AM, implementation manager, IM, customer success operations, CS ops, book of business, ratio, ARR-per-CSM, customer marketing, advocacy, expansion playbook, voice of customer, VoC ## Quick Start ```bash # Decision A: Decompose retention honestly python scripts/retention_decomposition_analyzer.py # embedded B2B SaaS sample python scripts/retention_decomposition_analyzer.py path/to/cohorts.json # Decision B: Design customer segmentation + differential investment python scripts/customer_segmentation_designer.py # embedded 4-tier sample python scripts/customer_segmentation_designer.py path/to/customers.json # Decision C: Calculate CS team coverage model python scripts/cs_coverage_calculator.py # embedded 350-customer sample python scripts/cs_coverage_calculator.py path/to/book.json ``` ## Key Questions (ask these first) - **What's your GROSS retention rate?** (Not NRR — NRR hides churn behind expansion. Ask gross first.) - **What's the #1 reason customers leave?** (If you can't name it, you don't understand churn.) - **What's the median time-to-value (TTV) by segment?** (Long TTV in low tier = misfit; long TTV in high tier = onboarding broken.) - **Which customer would you fire today?** (If "none" — your segmentation is broken; some accounts cost more than they earn.) - **What's your ARR-per-CSM ratio, and what's the model — pooled or named?** (Stage and ACV determine the right answer.) - **Is CS in your comp plan, and how is it different from Sales comp?** (CS comp on retention; misalignment is a leading indicator of failure.) ## Core Responsibilities ### 1. Retention Decomposition **The trap:** "Our NRR is 115%, retention is great." The truth: NRR = Gross Retention − Contraction + Expansion. A 115% NRR with 85% gross retention is a leaky bucket masked by upsells. A 115% NRR with 98% gross retention is a healthy product. **Mandatory decomposition every quarter:** | Metric | What it measures | Health threshold (B2B SaaS) | |---|---|---| | **Gross Retention (GRR)** | $ from existing customers minus churn + contraction | ≥ 90% at growth stage; ≥ 95% at scale | | **Logo Retention** | % of customers who renewed | ≥ 85% at growth; ≥ 90% at scale | | **Net Revenue Retention (NRR)** | GRR + expansion | ≥ 110% at growth; ≥ 120% at scale | | **Contraction** | $ from existing customers reducing seats/usage | < 5% annually | | **Expansion** | $ from existing customers growing | 15-25% annually at healthy | **Run** `retention_decomposition_analyzer.py` with cohort data for honest decomposition + churn root-cause categorization. See `references/retention_decomposition.md` for the 7-category churn taxonomy + leading indicator playbook. ### 2. Customer Segmentation **The trap:** "Every customer is important." The reality: customers exist on a spectrum of ICP fit × strategic value. Treating them identically wastes CS capacity and ignores expansion opportunity. **4-tier framework (B2B SaaS baseline):** | Tier | ARR range | Coverage | Investment per account/yr | |---|---|---|---| | **Strategic** | Top 5%, often $100K+ | Named CSM + executive sponsor | $20K-50K | | **Enterprise** | Next 15-20%, $20K-100K | Named CSM | $5K-15K | | **Mid-market** | Next 30-40%, $5K-20K | Pooled CSM + automation | $1K-3K | | **SMB / Long-tail** | Bottom 40-50%, <$5K | Tech-touch + self-serve | $50-500 | **Run** `customer_segmentation_designer.py` to design segmentation tiers + differential investment + ICP fit scoring. See `references/customer_segmentation_strategy.md` for ICP fit framework, tier transition triggers, and the kill list (customers below the investment floor). ### 3. CS Team Coverage Model **The trap:** "Hire one CSM per X customers" with a single ratio across all segments. The reality: coverage model depends on segment, ACV, and complexity. Pooled CSM works for low-touch; named CSM is required for strategic accounts. **Coverage models:** | Model | Best for | Ratio (ARR-per-CSM) | Trade-offs | |---|---|---|---| | **Tech-touch (no human)** | SMB, low ACV | $5M-15M+ | Automation cost; cannot save high-stakes deals | | **Pooled CSM** | Mid-market | $2M-5M | Lower cost; less account intimacy | | **Named CSM** | Enterprise | $500K-2M | Higher cost; deeper relationships | | **Named CSM + exec sponsor** | Strategic | $300K-1M | Highest cost; reserved for top accounts | **Run** `cs_coverage_calculator.py` with book characteristics to calculate required CSM headcount and identify transition thresholds. See `references/cs_coverage_model.md` for ratios, ramp curves, and the "when to add a manager" trigger. ### 4. CS Team Org Evolution **The wrong question:** "Should we hire a CSM or a Support engineer?" **The right question:** "What's the next customer outcome we're failing to deliver, and what role unblocks that?" **Critical distinctions (founders confuse these):** | Role | Owns | Does NOT own | |---|---|---| | Customer Support | Reactive issue resolution (ticket queue) | Renewal, expansion, success outcomes | | Customer Success Manager | Proactive value realization + renewal + expansion lead | Day-to-day tickets, implementation | | Account Manager | Commercial relationship + expansion close | Day-to-day success, technical depth | | Implementation Manager | Onboarding + go-live | Ongoing success after launch | | CS Operations | Tooling, data, analytics, playbooks | Direct customer relationships | | Customer Marketing | Advocacy, case studies, references | 1:1 customer relationships | See `references/cs_team_org_evolution.md` for stage-to-role map (seed → late-stage) + the AM-vs-CSM split decision. ## Workflows ### Workflow 1: Quarterly Retention Review (4 hours) **Goal:** Decompose retention honestly + identify top-3 churn drivers. ```bash # 1. Pull cohort data: closed/won by quarter for last 8 quarters python scripts/retention_decomposition_analyzer.py cohorts.json # 2. Review GRR / NRR / contraction / expansion separately # 3. For each cohort showing GRR < 90%: identify churn root cause (7-category taxonomy) # 4. Cross-check with cs-cro-advisor: does the expansion math add up? # 5. Cross-check with cs-cpo-advisor: are product gaps driving churn? # 6. Output: top-3 leakage points + 90-day mitigation plan ``` ### Workflow 2: Customer Segmentation Audit (1 day) **Goal:** Re-segment customer base + reset differential investment. ```bash # 1. Build customers.json with ARR, tenure, ICP fit signals python scripts/customer_segmentation_designer.py customers.json # 2. Identify segment migration (mid-market → enterprise upgrades, downsells) # 3. Identify kill list (customers below investment floor) # 4. Output: new tier assignment + investment-per-tier + kill list for sales review ``` ### Workflow 3: CS Team Sizing (1 week) **Goal:** Size the CS team aligned to book composition + coverage model. ```bash # 1. Build book.json with current customer base + planned acquisition python scripts/cs_coverage_calculator.py book.json # 2. Calculate required CSM headcount by segment # 3. Compare to current team; identify gaps # 4. Cross-check with cs-chro-advisor on comp + leveling # 5. Cross-check with cs-cfo-advisor on the cost # 6. Output: 12-month hiring plan + role sequence ``` ### Workflow 4: CS Team Roadmap (1 week) **Goal:** Sequence next 18 months of CS hires aligned to customer outcomes. 1. List top 5 customer outcomes the company is failing to deliver 2. Map each outcome to the role that unblocks it (CSM / AM / IM / Support / CS Ops) 3. Sequence hires; respect prerequisite order 4. Cross-check with cs-chro-advisor ## Output Standards ``` **Bottom Line:** [one sentence — decision and rationale] **The Decision:** [one of: retention | segmentation | coverage | next hire] **The Evidence:** [numbers from the tool, not adjectives] **How to Act:** [3 concrete next steps] **Your Decision:** [the call only the founder can make] ``` ## Adjacent Skills - `../cro-advisor/` — Revenue math, NRR, expansion comp (CCO owns customer experience; CRO owns revenue math; clean split) - `../cpo-advisor/` — Product strategy, JTBD (CCO surfaces product gaps; CPO decides roadmap) - `../cmo-advisor/` — Customer marketing, advocacy, references - `../cfo-advisor/` — CS team cost, retention-impact-on-revenue math - `../chro-advisor/` — CS team hiring + leveling - `../../../business-growth/` — Tactical CS execution: health scores, CRM workflows, onboarding tooling ## References - [retention_decomposition.md](references/retention_decomposition.md) — GRR vs NRR honest math + 7-category churn taxonomy + leading indicator playbook - [customer_segmentation_strategy.md](references/customer_segmentation_strategy.md) — 4-tier framework + ICP fit scoring + tier transition triggers + kill list criteria - [cs_coverage_model.md](references/cs_coverage_model.md) — Coverage model decision (tech-touch / pooled / named / named+exec) + ratio benchmarks + manager-trigger - [cs_team_org_evolution.md](references/cs_team_org_evolution.md) — Stage-to-role map + 6-role definition table (CSM ≠ Support ≠ AM ≠ IM ≠ CS Ops ≠ Customer Marketing) + AM-vs-CSM split decision + anti-patterns --- **Version:** 1.0.0 **Status:** Production Ready **Disclaimer:** Retention benchmarks vary significantly by ACV, segment, and industry. This skill provides B2B SaaS-baseline guidance; consumer SaaS, marketplaces, and hardware all have materially different retention math. --- ## chief-data-officer-advisor > Chief Data Officer advisory for startups: AI training data rights and consent provenance, data product strategy (warehouse vs lakehouse vs mesh, build-vs-buy), B2B customer-data-as-asset valuation and M&A readiness, data team org evolution. Use when deciding whether to train models on customer data, choosing data architecture, valuing data for fundraising or M&A, sequencing data hires, or when user mentions CDO, chief data officer, data strategy, data mesh, lakehouse, training data, data product, data monetization, or customer data asset. NOT a tactical data engineering skill — strategic decisions only. # Chief Data Officer Advisor Strategic data leadership for startup CDOs and founders without one. **Four decisions, no surveys:** 1. **Can we train our model on this data?** — origin × consent × use-case matrix 2. **Warehouse, lakehouse, or mesh — and what do we build vs buy?** — stage-driven architecture 3. **What is our customer data worth?** — strategic value + M&A multiplier + productization paths 4. **What data role do we hire next?** — stage-to-role map, centralize-vs-embed trigger This skill does **not** cover tactical data engineering. For schema design, observability, query optimization, RAG, or ML platform implementation, see `engineering/database-designer/`, `engineering/observability-designer/`, `engineering/data-quality-auditor/`, `engineering/sql-database-assistant/`, `engineering/rag-architect/`, `engineering/llm-cost-optimizer/`. ## Keywords CDO, chief data officer, AI training data, consent provenance, training rights, GDPR Article 6 lawful basis, GDPR Article 22, EU AI Act high-risk, ePrivacy, copyright fair use, hiQ v. LinkedIn, scraped data, synthetic data, data product, data mesh, lakehouse, medallion architecture, dbt, Snowflake, BigQuery, Databricks, Fivetran, Airbyte, reverse ETL, feature store, customer data as asset, data monetization, data productization, anonymization, k-anonymity, differential privacy, M&A data diligence, data org, analytics engineer, data engineer, data scientist, data product manager, centralize vs embed, hub and spoke ## Quick Start ```bash # Audit data sources for AI training eligibility python scripts/ai_training_data_audit.py # uses embedded sample python scripts/ai_training_data_audit.py path/to/sources.json # Pick data architecture + build-vs-buy + sequencing python scripts/data_product_strategy_picker.py # uses embedded Series A SaaS python scripts/data_product_strategy_picker.py path/to/profile.json # Value the customer data corpus + productization viability python scripts/data_asset_valuator.py # uses embedded B2B sample python scripts/data_asset_valuator.py path/to/corpus.json ``` ## Key Questions (ask these first) - **What decision does this data drive?** (If none, why are we collecting it?) - **What's the consent provenance of every source we want to train on?** (TOS-only is not the same as explicit opt-in.) - **Who are the internal data consumers, and how many distinct domains do they span?** (Drives centralize-vs-embed and warehouse-vs-mesh.) - **In an M&A scenario, is our data a moat or a liability?** (Customer carve-outs in MSAs can flip the answer.) - **Are we hiring an analytics engineer or a data scientist next?** (They solve different problems; founders confuse them.) - **Have we run an anonymization audit before any external sharing?** (k-anonymity ≥ 5 is the floor, not the ceiling.) ## Core Responsibilities ### 1. AI Training Data Rights The 2026 question every startup is facing: **can we use customer data to train our model?** The answer is rarely binary. It depends on three independent dimensions: | Dimension | Values | |---|---| | **Origin** | 1st-party-explicit-opt-in / 1st-party-TOS-only / partner-licensed / scraped / synthetic | | **Data class** | Anonymous aggregate / behavioral / PII / 3rd-party content / regulated (PHI, PCI, kids) | | **Use case** | In-product personalization / fine-tune our model / train foundation model / external sharing | Each combination produces GO / MITIGATE / NO-GO. **Run** `ai_training_data_audit.py` on a JSON inventory of sources. See `references/ai_training_data_rights.md` for the full matrix + GDPR Art. 6 lawful basis decision tree + EU AI Act high-risk triggers. ### 2. Data Product Strategy **Architecture choice (warehouse vs lakehouse vs mesh) is stage-driven, not preference-driven:** - **Warehouse only** (Snowflake / BigQuery / Postgres): ≤5 data consumers, <2TB, no ML use cases - **Lakehouse** (warehouse + object storage, often Databricks or Snowflake-with-Iceberg): 5–25 data consumers, 2TB–1PB, 1–3 ML use cases - **Data mesh**: 25+ data consumers across 4+ domains, federated ownership culture in place **Build vs buy is decided per layer:** | Layer | Buy unless | Build only if | |---|---|---| | Storage / warehouse | Never build | (You’re a data infra company) | | ELT / ingest | Never build | Source isn’t supported by Fivetran/Airbyte | | Modeling (dbt) | Always build | This is your IP | | BI / dashboards | Buy at <100 consumers | Embedded analytics for customers | | Feature store | Defer until 3+ prod models | Then build OR buy Tecton/Hopsworks | | ML platform | Defer until 5+ prod models | Then buy SageMaker/Vertex/Databricks | **Run** `data_product_strategy_picker.py` for a stage-specific recommendation. See `references/data_product_strategy.md` for kill criteria per architecture and the build-vs-buy decision tree. ### 3. B2B Customer-Data-as-Asset **The shift:** at Series B+, customer data is no longer just operational — it’s an asset that can be: - A defensibility moat (replicating requires years of customer cohort) - An M&A multiplier (1.2x–2x ARR uplift for strategic buyers) - A direct revenue stream (anonymized industry benchmarks, embedding endpoints, licensing) But it can also be a **liability**: - 47/380 customers with MSA carve-outs makes productization legally infeasible - Anonymization audits often reveal re-identification risk above tolerable thresholds - Regulatory exposure increases linearly with productization (GDPR Art. 28 processors vs Art. 26 joint controllers) **Run** `data_asset_valuator.py` with corpus characteristics to get strategic value score + productization paths + risk-adjusted value. See `references/customer_data_as_asset.md` for the valuation framework, M&A diligence prep checklist, and contractual constraint audit pattern. ### 4. Data Team Org Evolution **The wrong question:** "Should we hire a data scientist?" **The right question:** "What’s the next decision we can’t make because we lack data, and what role unblocks that?" Stage-to-role map (B2B SaaS baseline): | Stage | First hire | Then | Then | |---|---|---|---| | Pre-seed / seed | Founder-as-analyst (SQL + spreadsheets) | — | — | | Series A (Series A) | Analyst | Analytics engineer (dbt) | — | | Series B | Data engineer | Senior analyst (embedded in GTM) | Data PM (if 3+ teams need data) | | Growth | Manager of analytics | ML engineer (if model is core) | Head of Data | | Late-stage | Head of Data → CDO | Specialized: BI, MLE, DPO | Federated owners per domain (mesh) | **Centralize-vs-embed trigger:** when 3+ functional areas (sales, marketing, product, ops, CS) need bespoke data weekly, the central team becomes the bottleneck. Move to hub-and-spoke (central platform + embedded analysts) before that becomes a hiring crisis. See `references/data_team_org_evolution.md`. ## Workflows ### Workflow 1: AI Training Decision (1 hour) **Goal:** Decide whether a specific data source can train a specific use case. ```bash # 1. Build sources.json with one entry per data source # 2. Run the audit python scripts/ai_training_data_audit.py sources.json # 3. For each MITIGATE: assign owner + remediation # 4. For each NO-GO: document the kill reason for the legal log # 5. Cross-check with cs-general-counsel-advisor on top-3 mitigation items # 6. Log via /cs:decide ``` ### Workflow 2: Architecture Decision (1 day) **Goal:** Pick warehouse / lakehouse / mesh and the build-vs-buy split for the next 12 months. ```bash python scripts/data_product_strategy_picker.py profile.json # Cross-check with cs-cto-advisor on engineering capacity # Cross-check with cs-cfo-advisor on 3-year TCO # Log via /cs:decide; consider /cs:freeze 90 if signing a multi-year SaaS contract ``` ### Workflow 3: Data Asset Valuation for M&A Prep (3 days) **Goal:** Value the data corpus and prepare for due diligence. 1. Inventory the corpus: size, freshness, exclusivity, customer overlap, contractual restrictions 2. Run `data_asset_valuator.py` 3. Run the M&A diligence prep checklist in `customer_data_as_asset.md` 4. Surface contractual carve-outs to cs-general-counsel-advisor for re-papering plan 5. Decide productization path (benchmark report / embedding endpoint / direct license) 6. Log via /cs:decide ### Workflow 4: Data Team Roadmap (1 week) **Goal:** Build the next 18 months of data hires aligned to business decisions. 1. List the top 5 decisions the business can’t make today due to missing data or analysis 2. Map each decision to the role that unblocks it 3. Sequence hires (one role at a time, ramp before next) 4. Cross-check with cs-chro-advisor on comp bands and leveling 5. Identify the centralize-vs-embed trigger date ## Output Standards (when invoked via cs-cdo-advisor) ``` **Bottom Line:** [one sentence — decision and rationale] **The Decision:** [one of the 4 framings] **The Evidence:** [numbers, not adjectives] **How to Act:** [3 concrete next steps] **Your Decision:** [the call only the founder can make] ``` ## Adjacent Skills - `../cto-advisor/` — architecture capacity, scaling cliffs - `../ciso-advisor/` — data security, threat modeling for productized data - `../general-counsel-advisor/` — contractual constraints, DPA, training-data rights - `../cfo-advisor/` — build-vs-buy TCO, M&A valuation math - `../chro-advisor/` — data team hiring, leveling, comp - `../../../engineering/database-designer/` — tactical schema design - `../../../engineering/rag-architect/` — tactical AI/RAG implementation - `../../../engineering/llm-cost-optimizer/` — model cost management ## References - [ai_training_data_rights.md](references/ai_training_data_rights.md) — The training-rights matrix + GDPR Art. 6 / EU AI Act decision tree - [data_product_strategy.md](references/data_product_strategy.md) — Warehouse / lakehouse / mesh kill criteria + build-vs-buy decision tree - [customer_data_as_asset.md](references/customer_data_as_asset.md) — Valuation framework + M&A diligence prep + productization paths - [data_team_org_evolution.md](references/data_team_org_evolution.md) — Stage-to-role map + centralize-vs-embed trigger --- **Version:** 1.0.0 **Status:** Production Ready **Disclaimer:** Decisions touching training data rights, data productization, or M&A data diligence should involve qualified counsel. This skill surfaces decisions and tradeoffs — it does not replace legal review. --- ## boardroom > /cs:boardroom — 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo. # /cs:boardroom — Multi-Role Boardroom Deliberation **Command:** `/cs:boardroom ` Runs the `board-meeting` skill protocol across the C-suite for a single strategy brief. This is the **heart of the plugin** — the multi-role deliberation that gstack's review chain only approximates. ## Pipeline Position ``` /cs:office-hours → /cs:brief → /cs:boardroom → /cs:decide → /cs:execute → /cs:post-mortem ↑ you are here ``` ## The 6 Phases (from board-meeting skill) ### Phase 1 — Briefing - Chief of Staff distributes the brief to all advisors marked in **Affected Roles**. - Each advisor reads company-context.md + the brief. - No discussion yet. ### Phase 2 — Independent Thinking (ISOLATION) - **Critical:** each advisor produces their position **independently**, without seeing others' positions. - This prevents groupthink and surfaces dissent. - Each writes: their voice's opening, recommendation, top 3 concerns, top 3 supports. ### Phase 3 — Cross-Examination - Positions revealed simultaneously. - Each advisor critiques the others' positions on the dimensions they own: - cs-cfo-advisor critiques the math - cs-ciso-advisor critiques the risk - cs-cpo-advisor critiques the JTBD - cs-cmo-advisor critiques the positioning - cs-cro-advisor critiques the revenue math - etc. ### Phase 4 — Devil's Advocate Pass - `executive-mentor/devils-advocate` agent runs `/em:challenge` on the leading option. - Surfaces three concerns with severity ratings. ### Phase 5 — Synthesis - Chief of Staff synthesizes: which option commands majority, what are unresolved dissents. - Produces the **board memo** with recommendation + dissent. ### Phase 6 — Decision Hand-off - Memo is presented to the founder. - Founder accepts, modifies, or rejects. - Approved memo routes to `/cs:decide` for logging. ## Output: Board Memo Saved to `~/.claude/boardroom/YYYY-MM-DD-.md`: ```markdown # Board Memo: **Date:** YYYY-MM-DD **Brief:** **Status:** AWAITING FOUNDER DECISION | APPROVED | REJECTED ## Question [One sentence from the brief] ## Recommended Option **