')
+ body += _section("Action Items from Last Retro", _table(
+ ["Action", "Owner", "Status"],
+ [["", "", macro_status("DONE", "Green")], ["", "", macro_status("IN PROGRESS", "Yellow")]],
+ ))
+ body += _section("New Action Items", _table(
+ ["Action", "Owner", "Due Date", "Priority"],
+ [["", "", "", "High/Medium/Low"]],
+ ))
+ body += _section("Team Health Check", macro_info_panel("Rate each area 1-5 (1=needs work, 5=great)") + _table(
+ ["Area", "Rating", "Trend", "Notes"],
+ [["Teamwork", "", "", ""], ["Delivery", "", "", ""],
+ ["Fun", "", "", ""], ["Learning", "", "", ""]],
+ ))
+
+ return {"name": "Sprint Retrospective", "body": body, "labels": ["sprint-retro", "agile", "template"]}
+
+
+def template_how_to_guide() -> Dict[str, Any]:
+ """Generate how-to guide template."""
+ body = macro_toc() + '\n'
+ body += macro_info_panel("This guide explains how to accomplish a specific task.") + '\n'
+ body += _section("Overview", '
Brief description of what this guide covers and who it is for.
')
+ body += _section("Prerequisites", '
Prerequisite 1
Prerequisite 2
')
+ body += _section("Step-by-Step Instructions",
+ '
Step 1: Title
Description of what to do.
'
+ '
Step 2: Title
Description of what to do.
'
+ '
Step 3: Title
Description of what to do.
')
+ body += _section("Troubleshooting", macro_expand("Common Issues",
+ '
Issue 1
Solution...
'
+ '
Issue 2
Solution...
'))
+ body += _section("Related Resources", '
Link 1
Link 2
')
+
+ return {"name": "How-To Guide", "body": body, "labels": ["how-to", "guide", "template"]}
+
+
+TEMPLATE_REGISTRY = {
+ "meeting-notes": template_meeting_notes,
+ "decision-log": template_decision_log,
+ "runbook": template_runbook,
+ "project-kickoff": template_project_kickoff,
+ "sprint-retro": template_sprint_retro,
+ "how-to-guide": template_how_to_guide,
+}
+
+
+# ---------------------------------------------------------------------------
+# Custom Template Builder
+# ---------------------------------------------------------------------------
+
+def build_custom_template(
+ sections: List[str],
+ macros: List[str],
+) -> Dict[str, Any]:
+ """Build a custom template from sections and macros."""
+ body = ""
+
+ # Add requested macros at the top
+ if "toc" in macros:
+ body += macro_toc() + '\n'
+ if "status" in macros:
+ body += '
Status: ' + macro_status() + '
\n'
+
+ for section in sections:
+ section = section.strip()
+ if not section:
+ continue
+ body += _section(section, '')
+
+ # Add panels if requested
+ if "info" in macros:
+ body = macro_info_panel("Add instructions or context here.") + '\n' + body
+ if "warning" in macros:
+ body += macro_warning_panel("Add warnings here.") + '\n'
+ if "note" in macros:
+ body += macro_note_panel("Add notes here.") + '\n'
+
+ return {"name": "Custom Template", "body": body, "labels": ["custom", "template"]}
+
+
+# ---------------------------------------------------------------------------
+# Output Formatting
+# ---------------------------------------------------------------------------
+
+def format_text_output(result: Dict[str, Any]) -> str:
+ """Format results as readable text report."""
+ lines = []
+ lines.append("=" * 60)
+ lines.append(f"TEMPLATE: {result['name']}")
+ lines.append("=" * 60)
+ lines.append("")
+ lines.append(f"Labels: {', '.join(result.get('labels', []))}")
+ lines.append("")
+ lines.append("CONFLUENCE STORAGE FORMAT MARKUP")
+ lines.append("-" * 30)
+ lines.append(result["body"])
+
+ return "\n".join(lines)
+
+
+def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
+ """Format results as JSON."""
+ return result
+
+
+def format_list_output(output_format: str) -> str:
+ """Format available templates list."""
+ if output_format == "json":
+ templates = {}
+ for name, func in TEMPLATE_REGISTRY.items():
+ result = func()
+ templates[name] = {
+ "name": result["name"],
+ "labels": result["labels"],
+ }
+ return json.dumps(templates, indent=2)
+
+ lines = []
+ lines.append("=" * 60)
+ lines.append("AVAILABLE TEMPLATES")
+ lines.append("=" * 60)
+ lines.append("")
+ for name, func in TEMPLATE_REGISTRY.items():
+ result = func()
+ lines.append(f" {name}")
+ lines.append(f" Name: {result['name']}")
+ lines.append(f" Labels: {', '.join(result['labels'])}")
+ lines.append("")
+ lines.append(f"Total templates: {len(TEMPLATE_REGISTRY)}")
+ lines.append("")
+ lines.append("Usage:")
+ lines.append(" python template_scaffolder.py ")
+ lines.append(' python template_scaffolder.py custom --sections "Section1,Section2" --macros toc,status')
+ return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CLI Interface
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+ """Main CLI entry point."""
+ parser = argparse.ArgumentParser(
+ description="Generate Confluence page template markup"
+ )
+ parser.add_argument(
+ "template",
+ nargs="?",
+ help="Template name or 'custom' for custom template",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["text", "json"],
+ default="text",
+ help="Output format (default: text)",
+ )
+ parser.add_argument(
+ "--list",
+ action="store_true",
+ help="List all available template types",
+ )
+ parser.add_argument(
+ "--sections",
+ help='Comma-separated section names for custom template (e.g., "Overview,Goals,Action Items")',
+ )
+ parser.add_argument(
+ "--macros",
+ help='Comma-separated macro names to include (e.g., "toc,status,info")',
+ )
+
+ args = parser.parse_args()
+
+ try:
+ if args.list:
+ print(format_list_output(args.format))
+ return 0
+
+ if not args.template:
+ parser.error("template name is required unless --list is used")
+
+ template_name = args.template.lower()
+
+ if template_name == "custom":
+ if not args.sections:
+ parser.error("--sections is required for custom templates")
+ sections = [s.strip() for s in args.sections.split(",")]
+ macros = [m.strip() for m in args.macros.split(",")] if args.macros else []
+ result = build_custom_template(sections, macros)
+ elif template_name in TEMPLATE_REGISTRY:
+ result = TEMPLATE_REGISTRY[template_name]()
+ else:
+ available = ", ".join(sorted(TEMPLATE_REGISTRY.keys()))
+ print(f"Error: Unknown template '{template_name}'. Available: {available}", file=sys.stderr)
+ return 1
+
+ if args.format == "json":
+ print(json.dumps(format_json_output(result), indent=2))
+ else:
+ print(format_text_output(result))
+
+ return 0
+
+ except Exception as e:
+ print(f"Error: {e}", file=sys.stderr)
+ return 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/skills/auto-memory-pro/CLAUDE.md b/skills/auto-memory-pro/CLAUDE.md
new file mode 100644
index 00000000..cbd99937
--- /dev/null
+++ b/skills/auto-memory-pro/CLAUDE.md
@@ -0,0 +1,79 @@
+# Self-Improving Agent — Claude Code Instructions
+
+This plugin helps you curate Claude Code's auto-memory into durable project knowledge.
+
+## Commands
+
+Use the `/si:` namespace for all commands:
+
+- `/si:review` — Analyze auto-memory health and find promotion candidates
+- `/si:promote ` — Graduate a learning to CLAUDE.md or `.claude/rules/`
+- `/si:extract ` — Create a reusable skill from a proven pattern
+- `/si:status` — Quick memory health dashboard
+- `/si:remember ` — Explicitly save something to auto-memory
+
+## How auto-memory works
+
+Claude Code maintains `~/.claude/projects//memory/MEMORY.md` automatically. The first 200 lines load into every session. When it grows too large, Claude moves details into topic files like `debugging.md` or `patterns.md`.
+
+This plugin reads that directory — it never creates its own storage.
+
+## When to use each command
+
+### After completing a feature or debugging session
+```
+/si:review
+```
+Check if anything Claude learned should become a permanent rule.
+
+### When a pattern keeps coming up
+```
+/si:promote "Always run migrations before tests in this project"
+```
+Moves it from MEMORY.md (background note) to CLAUDE.md (enforced rule).
+
+### When you solved something non-obvious that could help other projects
+```
+/si:extract "Docker build fix for ARM64 platform mismatch"
+```
+Creates a standalone skill with SKILL.md, ready to install elsewhere.
+
+### To check memory capacity
+```
+/si:status
+```
+Shows line counts, topic files, stale entries, and recommendations.
+
+## Key principle
+
+**Don't fight auto-memory — orchestrate it.**
+
+- Auto-memory is great at capturing patterns. Let it do its job.
+- This plugin adds judgment: what's worth keeping, what should be promoted, what's stale.
+- Promoted rules in CLAUDE.md have higher priority than MEMORY.md entries.
+- Removing promoted entries from MEMORY.md frees space for new learnings.
+
+## Agents
+
+- **memory-analyst**: Spawned by `/si:review` to analyze patterns across memory files
+- **skill-extractor**: Spawned by `/si:extract` to generate complete skill packages
+
+## Hooks
+
+The `error-capture.sh` hook fires on `PostToolUse` (Bash only). It detects command failures and appends structured entries to auto-memory. Zero overhead on successful commands.
+
+To enable:
+```json
+// .claude/settings.json
+{
+ "hooks": {
+ "PostToolUse": [{
+ "matcher": "Bash",
+ "hooks": [{
+ "type": "command",
+ "command": "./skills/self-improving-agent/hooks/error-capture.sh"
+ }]
+ }]
+ }
+}
+```
diff --git a/skills/auto-memory-pro/README.md b/skills/auto-memory-pro/README.md
new file mode 100644
index 00000000..414ed305
--- /dev/null
+++ b/skills/auto-memory-pro/README.md
@@ -0,0 +1,92 @@
+# Self-Improving Agent
+
+> Auto-memory captures. This plugin curates.
+
+A Claude Code plugin that turns auto-memory into a structured self-improvement loop. Analyze what Claude has learned, promote proven patterns to enforced rules, and extract recurring solutions into reusable skills.
+
+## Why
+
+Claude Code's auto-memory (v2.1.32+) automatically records project patterns in `MEMORY.md`. But it has no judgment about what to keep, what to promote, or when entries go stale. This plugin adds the intelligence layer.
+
+**The difference:**
+- **MEMORY.md**: "I noticed this project uses pnpm" (background note, truncated at 200 lines)
+- **CLAUDE.md**: "Use pnpm, not npm" (enforced instruction, loaded in full)
+
+Promoting a pattern from memory to rules fundamentally changes how Claude treats it.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/si:review` | Analyze auto-memory — find promotion candidates, stale entries, health metrics |
+| `/si:promote` | Graduate a pattern from MEMORY.md → CLAUDE.md or `.claude/rules/` |
+| `/si:extract` | Turn a recurring pattern into a standalone reusable skill |
+| `/si:status` | Memory health dashboard — line counts, capacity, recommendations |
+| `/si:remember` | Explicitly save important knowledge to auto-memory |
+
+## Install
+
+### Claude Code
+```
+/plugin marketplace add alirezarezvani/claude-skills
+/plugin install self-improving-agent@claude-code-skills
+```
+
+### OpenClaw
+```bash
+clawhub install self-improving-agent
+```
+
+### Codex CLI
+```bash
+./scripts/codex-install.sh --skill self-improving-agent
+```
+
+## How It Works
+
+```
+Claude discovers pattern → auto-memory (MEMORY.md)
+ ↓
+Pattern recurs 2-3x → /si:review flags it
+ ↓
+You approve → /si:promote graduates it to CLAUDE.md
+ ↓
+Pattern becomes enforced rule, memory entry removed
+ ↓
+Space freed for new learnings
+```
+
+## What's Included
+
+| Component | Count | Description |
+|-----------|-------|-------------|
+| Skills | 5 | review, promote, extract, status, remember |
+| Agents | 2 | memory-analyst, skill-extractor |
+| Hooks | 1 | PostToolUse error capture (zero overhead on success) |
+| Reference docs | 3 | memory architecture, promotion rules, rules directory patterns |
+| Templates | 2 | rule template, skill template |
+
+## Design Principles
+
+1. **Don't fight auto-memory — orchestrate it.** Auto-memory captures. This plugin curates.
+2. **No duplicate storage.** Reads from `~/.claude/projects/` directly. No `.learnings/` directory.
+3. **Zero capture overhead.** Auto-memory handles capture. Hook only fires on errors.
+4. **Promotion = graduation.** Moving a pattern from MEMORY.md to CLAUDE.md changes its priority.
+5. **Respect the 200-line limit.** Actively manages MEMORY.md capacity.
+
+## Platform Support
+
+| Platform | Memory System | Support |
+|----------|--------------|---------|
+| Claude Code | Auto-memory (MEMORY.md) | ✅ Full |
+| OpenClaw | workspace/MEMORY.md | ✅ Adapted |
+| Codex CLI | AGENTS.md | ✅ Adapted |
+| GitHub Copilot | copilot-instructions.md | ⚠️ Manual |
+
+## Credits
+
+Inspired by [pskoett/self-improving-agent](https://clawhub.ai/pskoett/self-improving-agent) — a structured learning loop for AI coding agents. This plugin builds on that concept by integrating natively with Claude Code's auto-memory system.
+
+## License
+
+MIT — see [LICENSE](LICENSE)
diff --git a/skills/auto-memory-pro/SKILL.md b/skills/auto-memory-pro/SKILL.md
new file mode 100644
index 00000000..0e2c8822
--- /dev/null
+++ b/skills/auto-memory-pro/SKILL.md
@@ -0,0 +1,162 @@
+---
+name: auto-memory-pro
+description: "Curate Claude Code's auto-memory into durable project knowledge. Analyze MEMORY.md for patterns, promote proven learnings to CLAUDE.md and .claude/rules/, extract recurring solutions into reusable skills. Use when: (1) reviewing what Claude has learned about your project, (2) graduating a pattern from notes to enforced rules, (3) turning a debugging solution into a skill, (4) checking memory health and capacity."
+---
+
+# Self-Improving Agent
+
+> Auto-memory captures. This plugin curates.
+
+Claude Code's auto-memory (v2.1.32+) automatically records project patterns, debugging insights, and your preferences in `MEMORY.md`. This plugin adds the intelligence layer: it analyzes what Claude has learned, promotes proven patterns into project rules, and extracts recurring solutions into reusable skills.
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `/si:review` | Analyze MEMORY.md — find promotion candidates, stale entries, consolidation opportunities |
+| `/si:promote` | Graduate a pattern from MEMORY.md → CLAUDE.md or `.claude/rules/` |
+| `/si:extract` | Turn a proven pattern into a standalone skill |
+| `/si:status` | Memory health dashboard — line counts, topic files, recommendations |
+| `/si:remember` | Explicitly save important knowledge to auto-memory |
+
+## How It Fits Together
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Claude Code Memory Stack │
+├─────────────┬──────────────────┬────────────────────────┤
+│ CLAUDE.md │ Auto Memory │ Session Memory │
+│ (you write)│ (Claude writes)│ (Claude writes) │
+│ Rules & │ MEMORY.md │ Conversation logs │
+│ standards │ + topic files │ + continuity │
+│ Full load │ First 200 lines│ Contextual load │
+├─────────────┴──────────────────┴────────────────────────┤
+│ ↑ /si:promote ↑ /si:review │
+│ Self-Improving Agent (this plugin) │
+│ ↓ /si:extract ↓ /si:remember │
+├─────────────────────────────────────────────────────────┤
+│ .claude/rules/ │ New Skills │ Error Logs │
+│ (scoped rules) │ (extracted) │ (auto-captured)│
+└─────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+### Claude Code (Plugin)
+```
+/plugin marketplace add alirezarezvani/claude-skills
+/plugin install self-improving-agent@claude-code-skills
+```
+
+### OpenClaw
+```bash
+clawhub install self-improving-agent
+```
+
+### Codex CLI
+```bash
+./scripts/codex-install.sh --skill self-improving-agent
+```
+
+## Memory Architecture
+
+### Where things live
+
+| File | Who writes | Scope | Loaded |
+|------|-----------|-------|--------|
+| `./CLAUDE.md` | You (+ `/si:promote`) | Project rules | Full file, every session |
+| `~/.claude/CLAUDE.md` | You | Global preferences | Full file, every session |
+| `~/.claude/projects//memory/MEMORY.md` | Claude (auto) | Project learnings | First 200 lines |
+| `~/.claude/projects//memory/*.md` | Claude (overflow) | Topic-specific notes | On demand |
+| `.claude/rules/*.md` | You (+ `/si:promote`) | Scoped rules | When matching files open |
+
+### The promotion lifecycle
+
+```
+1. Claude discovers pattern → auto-memory (MEMORY.md)
+2. Pattern recurs 2-3x → /si:review flags it as promotion candidate
+3. You approve → /si:promote graduates it to CLAUDE.md or rules/
+4. Pattern becomes an enforced rule, not just a note
+5. MEMORY.md entry removed → frees space for new learnings
+```
+
+## Core Concepts
+
+### Auto-memory is capture, not curation
+
+Auto-memory is excellent at recording what Claude learns. But it has no judgment about:
+- Which learnings are temporary vs. permanent
+- Which patterns should become enforced rules
+- When the 200-line limit is wasting space on stale entries
+- Which solutions are good enough to become reusable skills
+
+That's what this plugin does.
+
+### Promotion = graduation
+
+When you promote a learning, it moves from Claude's scratchpad (MEMORY.md) to your project's rule system (CLAUDE.md or `.claude/rules/`). The difference matters:
+
+- **MEMORY.md**: "I noticed this project uses pnpm" (background context)
+- **CLAUDE.md**: "Use pnpm, not npm" (enforced instruction)
+
+Promoted rules have higher priority and load in full (not truncated at 200 lines).
+
+### Rules directory for scoped knowledge
+
+Not everything belongs in CLAUDE.md. Use `.claude/rules/` for patterns that only apply to specific file types:
+
+```yaml
+# .claude/rules/api-testing.md
+---
+paths:
+ - "src/api/**/*.test.ts"
+ - "tests/api/**/*"
+---
+- Use supertest for API endpoint testing
+- Mock external services with msw
+- Always test error responses, not just happy paths
+```
+
+This loads only when Claude works with API test files — zero overhead otherwise.
+
+## Agents
+
+### memory-analyst
+Analyzes MEMORY.md and topic files to identify:
+- Entries that recur across sessions (promotion candidates)
+- Stale entries referencing deleted files or old patterns
+- Related entries that should be consolidated
+- Gaps between what MEMORY.md knows and what CLAUDE.md enforces
+
+### skill-extractor
+Takes a proven pattern and generates a complete skill:
+- SKILL.md with proper frontmatter
+- Reference documentation
+- Examples and edge cases
+- Ready for `/plugin install` or `clawhub publish`
+
+## Hooks
+
+### error-capture (PostToolUse → Bash)
+Monitors command output for errors. When detected, appends a structured entry to auto-memory with:
+- The command that failed
+- Error output (truncated)
+- Timestamp and context
+- Suggested category
+
+**Token overhead:** Zero on success. ~30 tokens only when an error is detected.
+
+## Platform Support
+
+| Platform | Memory System | Plugin Works? |
+|----------|--------------|---------------|
+| Claude Code | Auto-memory (MEMORY.md) | ✅ Full support |
+| OpenClaw | workspace/MEMORY.md | ✅ Adapted (reads workspace memory) |
+| Codex CLI | AGENTS.md | ✅ Adapted (reads AGENTS.md patterns) |
+| GitHub Copilot | `.github/copilot-instructions.md` | ⚠️ Manual promotion only |
+
+## Related
+
+- [Claude Code Memory Docs](https://code.claude.com/docs/en/memory)
+- [pskoett/self-improving-agent](https://clawhub.ai/pskoett/self-improving-agent) — inspiration
+- [playwright-pro](../playwright-pro/) — sister plugin in this repo
diff --git a/skills/auto-memory-pro/_meta.json b/skills/auto-memory-pro/_meta.json
new file mode 100644
index 00000000..c9dd819c
--- /dev/null
+++ b/skills/auto-memory-pro/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "auto-memory-pro",
+ "displayName": "Auto Memory Pro",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1772731553713,
+ "commit": "https://github.com/openclaw/skills/commit/b01d767ccdfac11acd4fd804f13c732aaf9c6da8"
+ },
+ "history": []
+}
diff --git a/skills/auto-memory-pro/agents/memory-analyst.md b/skills/auto-memory-pro/agents/memory-analyst.md
new file mode 100644
index 00000000..e3e04511
--- /dev/null
+++ b/skills/auto-memory-pro/agents/memory-analyst.md
@@ -0,0 +1,74 @@
+# Memory Analyst Agent
+
+You are a memory analyst for Claude Code projects. Your job is to analyze the auto-memory directory and produce actionable insights.
+
+## Your Role
+
+You analyze `~/.claude/projects//memory/` to find:
+1. **Promotion candidates** — entries proven enough to become CLAUDE.md rules
+2. **Stale entries** — references to files, tools, or patterns that no longer apply
+3. **Consolidation opportunities** — multiple entries about the same topic
+4. **Conflicts** — memory entries that contradict CLAUDE.md rules
+5. **Health metrics** — capacity, freshness, organization
+
+## Analysis Process
+
+### 1. Read all memory files
+- `MEMORY.md` (main file, first 200 lines loaded at startup)
+- Any topic files (`debugging.md`, `patterns.md`, etc.)
+- Note total line counts and file sizes
+
+### 2. Cross-reference with CLAUDE.md
+- Read `./CLAUDE.md` and `~/.claude/CLAUDE.md`
+- Read all files in `.claude/rules/`
+- Identify duplicates, contradictions, and gaps
+
+### 3. Detect patterns
+For each MEMORY.md entry, evaluate:
+
+**Recurrence signals:**
+- Same concept in multiple entries (paraphrased)
+- Words like "again", "still", "always", "every time"
+- Similar entries in topic files
+
+**Staleness signals:**
+- File paths that don't exist on disk (verify with `find` or `ls`)
+- Version numbers that are outdated
+- References to removed dependencies
+- Patterns that contradict current CLAUDE.md
+
+**Promotion signals:**
+- Actionable (can be written as "Do X" / "Never Y")
+- Broadly applicable (not a one-time debugging note)
+- Not already in CLAUDE.md or rules/
+- High impact (prevents common mistakes)
+
+### 4. Score each entry
+
+Rate each entry on three dimensions:
+- **Durability** (0-3): Will this still be true in a month?
+- **Impact** (0-3): How much does this affect daily work?
+- **Scope** (0-3): Project-wide (3) vs. one-file (1) vs. one-time (0)
+
+Promotion candidates: total score ≥ 6
+
+### 5. Generate report
+
+Organize findings into:
+1. Promotion candidates (sorted by score, highest first)
+2. Stale entries (with reason for staleness)
+3. Consolidation groups (which entries to merge)
+4. Conflicts (with both sides shown)
+5. Health metrics (capacity, freshness)
+6. Recommendations (top 3 actions)
+
+## Output Format
+
+Use the format defined in the `/si:review` skill. Be specific — include line numbers, exact text, and concrete suggestions.
+
+## Constraints
+
+- Never modify files directly — only analyze and report
+- Don't invent entries — only report what's actually in the memory files
+- Be concise — the report should be shorter than the memory files it analyzes
+- Prioritize actionable findings over completeness
diff --git a/skills/auto-memory-pro/agents/skill-extractor.md b/skills/auto-memory-pro/agents/skill-extractor.md
new file mode 100644
index 00000000..99e8578c
--- /dev/null
+++ b/skills/auto-memory-pro/agents/skill-extractor.md
@@ -0,0 +1,110 @@
+# Skill Extractor Agent
+
+You are a skill extraction specialist. Your job is to transform proven patterns and debugging solutions into standalone, portable skills.
+
+## Your Role
+
+Given a pattern description (and optionally auto-memory entries), generate a complete skill package that:
+- Solves a specific, recurring problem
+- Works in any project (no hardcoded paths, credentials, or project-specific values)
+- Is self-contained (readable without the original context)
+- Follows the claude-skills format specification
+
+## Extraction Process
+
+### 1. Understand the pattern
+
+From the input, identify:
+- **The problem**: What goes wrong? What's the symptom?
+- **The root cause**: Why does it happen?
+- **The solution**: What's the fix? Are there multiple approaches?
+- **The edge cases**: When does the solution NOT work?
+- **The trigger conditions**: When should an agent use this skill?
+
+### 2. Generate skill name
+
+Rules:
+- Lowercase, hyphens between words
+- 2-4 words, descriptive
+- Match the problem, not the project
+- Examples: `docker-arm64-fixes`, `api-timeout-patterns`, `pnpm-monorepo-setup`
+
+### 3. Create SKILL.md
+
+Required structure:
+
+```markdown
+---
+name: {{skill-name}}
+description: "{{One sentence}}. Use when: {{trigger conditions}}."
+---
+
+# {{Skill Title}}
+
+> {{One-line value proposition}}
+
+## Quick Reference
+
+| Problem | Solution |
+|---------|----------|
+| {{error/symptom}} | {{fix}} |
+
+## The Problem
+
+{{2-3 sentences. Include the error message or symptom people would search for.}}
+
+## Solutions
+
+### Option 1: {{Name}} (Recommended)
+
+{{Step-by-step instructions with code blocks.}}
+
+### Option 2: {{Alternative}} {{if applicable}}
+
+{{When Option 1 doesn't apply.}}
+
+## Trade-offs
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| {{option}} | {{pros}} | {{cons}} |
+
+## Edge Cases
+
+- {{When this approach breaks and what to do instead}}
+
+## Related
+
+- {{Links to official docs or related skills}}
+```
+
+### 4. Create README.md
+
+Brief human-readable overview:
+- What the skill does (1 paragraph)
+- Installation instructions
+- When to use it
+- Credits/source
+
+### 5. Quality checks
+
+Before delivering, verify:
+
+- [ ] YAML frontmatter is valid (`name` and `description` present)
+- [ ] `name` in frontmatter matches folder name
+- [ ] Description includes "Use when:" trigger
+- [ ] No project-specific paths, URLs, or credentials
+- [ ] Code examples are complete and runnable
+- [ ] Error messages are exact (copy-pasteable for searching)
+- [ ] Solutions work without additional context
+- [ ] Trade-offs table helps users choose between options
+- [ ] Skill is useful in a project you've never seen before
+
+## Constraints
+
+- **One problem per skill** — don't create omnibus guides
+- **Show, don't tell** — code examples over prose
+- **Include the error** — people search by error message
+- **Be portable** — no `npm` vs `pnpm` assumptions
+- **Keep it short** — under 200 lines for SKILL.md
+- **No unnecessary files** — only SKILL.md is required. Add reference/ only if the topic is complex enough to warrant it
diff --git a/skills/auto-memory-pro/hooks/error-capture.sh b/skills/auto-memory-pro/hooks/error-capture.sh
new file mode 100644
index 00000000..393cfe8b
--- /dev/null
+++ b/skills/auto-memory-pro/hooks/error-capture.sh
@@ -0,0 +1,110 @@
+#!/bin/bash
+# Self-Improving Agent — Error Capture Hook
+# Fires on PostToolUse (Bash) to detect command failures.
+# Zero output on success — only captures when errors are detected.
+#
+# Install: Add to .claude/settings.json:
+# {
+# "hooks": {
+# "PostToolUse": [{
+# "matcher": "Bash",
+# "hooks": [{
+# "type": "command",
+# "command": "./skills/self-improving-agent/hooks/error-capture.sh"
+# }]
+# }]
+# }
+# }
+
+set -e
+
+OUTPUT="${CLAUDE_TOOL_OUTPUT:-}"
+
+# Exit silently if no output or empty
+[ -z "$OUTPUT" ] && exit 0
+
+# Error patterns — ordered by specificity
+ERROR_PATTERNS=(
+ "error:"
+ "Error:"
+ "ERROR:"
+ "FATAL:"
+ "fatal:"
+ "FAILED"
+ "failed"
+ "command not found"
+ "No such file or directory"
+ "Permission denied"
+ "Module not found"
+ "ModuleNotFoundError"
+ "ImportError"
+ "SyntaxError"
+ "TypeError"
+ "ReferenceError"
+ "Cannot find module"
+ "ENOENT"
+ "EACCES"
+ "ECONNREFUSED"
+ "ETIMEDOUT"
+ "npm ERR!"
+ "pnpm ERR!"
+ "Traceback (most recent call last)"
+ "panic:"
+ "segmentation fault"
+ "core dumped"
+ "exit code"
+ "non-zero exit"
+ "Build failed"
+ "Compilation failed"
+ "Test failed"
+)
+
+# False positive exclusions — don't trigger on these
+EXCLUSIONS=(
+ "error-capture" # Don't trigger on ourselves
+ "error_handler" # Code that handles errors
+ "errorHandler"
+ "error.log" # Log file references
+ "console.error" # Code that logs errors
+ "catch (error" # Error handling code
+ "catch (err"
+ ".error(" # Logger calls
+ "no error" # Absence of error
+ "without error"
+ "error-free"
+)
+
+# Check exclusions first
+for excl in "${EXCLUSIONS[@]}"; do
+ if [[ "$OUTPUT" == *"$excl"* ]]; then
+ exit 0
+ fi
+done
+
+# Check for error patterns
+contains_error=false
+matched_pattern=""
+for pattern in "${ERROR_PATTERNS[@]}"; do
+ if [[ "$OUTPUT" == *"$pattern"* ]]; then
+ contains_error=true
+ matched_pattern="$pattern"
+ break
+ fi
+done
+
+# Exit silently if no error
+[ "$contains_error" = false ] && exit 0
+
+# Extract relevant error context (first 5 lines containing the pattern)
+error_context=$(echo "$OUTPUT" | grep -i -m 5 "$matched_pattern" | head -5)
+
+# Output a concise reminder — ~40 tokens
+cat << EOF
+
+Command error detected (pattern: "$matched_pattern").
+If this was unexpected or required investigation to fix, save the solution:
+ /si:remember "explanation of what went wrong and the fix"
+Or if this is a known pattern, check: /si:review
+Context: $(echo "$error_context" | head -2 | tr '\n' ' ' | cut -c1-200)
+
+EOF
diff --git a/skills/auto-memory-pro/hooks/hooks.json b/skills/auto-memory-pro/hooks/hooks.json
new file mode 100644
index 00000000..a164465d
--- /dev/null
+++ b/skills/auto-memory-pro/hooks/hooks.json
@@ -0,0 +1,11 @@
+{
+ "hooks": [
+ {
+ "name": "error-capture",
+ "event": "PostToolUse",
+ "matcher": "Bash",
+ "command": "./hooks/error-capture.sh",
+ "description": "Detects command failures and appends structured entries to auto-memory. Zero overhead on successful commands."
+ }
+ ]
+}
diff --git a/skills/auto-memory-pro/reference/memory-architecture.md b/skills/auto-memory-pro/reference/memory-architecture.md
new file mode 100644
index 00000000..dc15acda
--- /dev/null
+++ b/skills/auto-memory-pro/reference/memory-architecture.md
@@ -0,0 +1,131 @@
+# Claude Code Memory Architecture
+
+A complete reference for how Claude Code's memory systems work together.
+
+## Three Memory Systems
+
+### 1. CLAUDE.md Files (You → Claude)
+
+**Purpose:** Persistent instructions you write to guide Claude's behavior.
+
+**Locations (in priority order):**
+| Scope | Path | Shared |
+|-------|------|--------|
+| Managed policy | `/etc/claude-code/CLAUDE.md` (Linux) | All users |
+| Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team (git) |
+| User | `~/.claude/CLAUDE.md` | Just you |
+| Local | `./CLAUDE.local.md` | Just you |
+
+**Loading:** Full file, every session. Files higher in the directory tree load first.
+
+**Key facts:**
+- Target under 200 lines per file
+- Use `@path/to/file` syntax to import additional files (max 5 hops deep)
+- More specific locations take precedence over broader ones
+- Can import with `@README` or `@docs/guide.md`
+- CLAUDE.local.md is auto-added to .gitignore
+
+### 2. Auto Memory (Claude → Claude)
+
+**Purpose:** Notes Claude writes to itself about project patterns and learnings.
+
+**Location:** `~/.claude/projects//memory/`
+
+**Structure:**
+```
+~/.claude/projects//memory/
+├── MEMORY.md # Main file (first 200 lines loaded)
+├── debugging.md # Topic file (loaded on demand)
+├── patterns.md # Topic file (loaded on demand)
+└── ... # More topic files as needed
+```
+
+**Key facts:**
+- Enabled by default (since v2.1.32)
+- Only the first 200 lines of MEMORY.md load at startup
+- Claude creates topic files automatically when MEMORY.md gets long
+- Git repo root determines the project path
+- Git worktrees get separate memory directories
+- Local only — not shared via git
+- Toggle with `/memory`, settings, or `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
+- Subagents can have their own auto memory
+
+**What it captures:**
+- Build commands and test conventions
+- Debugging solutions and error patterns
+- Code style preferences and architecture notes
+- Your communication preferences and workflow habits
+
+### 3. Session Memory (Claude → Claude)
+
+**Purpose:** Conversation summaries for cross-session continuity.
+
+**Location:** `~/.claude/projects///session-memory/`
+
+**Key facts:**
+- Saves what was discussed and decided in specific sessions
+- "What did we do yesterday?" context
+- Loaded contextually (relevant past sessions, not all)
+- Use `/remember` to turn session memory into permanent project knowledge
+
+### 4. Rules Directory (You → Claude, scoped)
+
+**Purpose:** Modular instructions scoped to specific file types.
+
+**Location:** `.claude/rules/*.md`
+
+**Key facts:**
+- Uses YAML frontmatter with `paths` field for scoping
+- Only loads when Claude works with matching files
+- Recursive — can organize into subdirectories
+- Same priority as `.claude/CLAUDE.md`
+- Great for keeping CLAUDE.md under 200 lines
+
+```yaml
+---
+paths:
+ - "src/api/**/*.ts"
+---
+# API rules only load when working with API files
+```
+
+## Memory Priority
+
+When entries conflict:
+
+1. CLAUDE.md (highest — explicit instructions)
+2. `.claude/rules/` (high — scoped instructions)
+3. Auto-memory MEMORY.md (medium — learned patterns)
+4. Session memory (low — historical context)
+
+## The Self-Improving Agent's Role
+
+```
+Auto-memory captures → This plugin curates → CLAUDE.md enforces
+
+MEMORY.md (raw notes) → /si:review (analyze) → /si:promote (graduate)
+ ↓
+ CLAUDE.md or
+ .claude/rules/
+ (enforced rules)
+```
+
+**Why this matters:** MEMORY.md entries are background context truncated at 200 lines. CLAUDE.md entries are high-priority instructions loaded in full. Promoting a pattern from memory to rules fundamentally changes how Claude treats it.
+
+## Capacity Planning
+
+| File | Soft limit | Hard limit | What happens at limit |
+|------|-----------|------------|----------------------|
+| MEMORY.md | 150 lines | 200 lines | Lines after 200 not loaded at startup |
+| CLAUDE.md | 150 lines | No hard limit | Adherence decreases with length |
+| Topic files | No limit | No limit | Loaded on demand, not at startup |
+| Rules files | No limit per file | No limit | Only loaded when paths match |
+
+## Best Practices
+
+1. **Keep MEMORY.md lean** — promote proven patterns, delete stale ones
+2. **Keep CLAUDE.md under 200 lines** — split into rules/ if growing
+3. **Don't duplicate** — if it's in CLAUDE.md, remove it from MEMORY.md
+4. **Scope rules** — use `.claude/rules/` with paths for file-type-specific patterns
+5. **Review quarterly** — memory files go stale after refactors
+6. **Use /si:status** — monitor capacity before it becomes a problem
diff --git a/skills/auto-memory-pro/reference/promotion-rules.md b/skills/auto-memory-pro/reference/promotion-rules.md
new file mode 100644
index 00000000..67bc4179
--- /dev/null
+++ b/skills/auto-memory-pro/reference/promotion-rules.md
@@ -0,0 +1,83 @@
+# Promotion Rules
+
+When to promote a learning from auto-memory (MEMORY.md) to the project's rule system (CLAUDE.md or `.claude/rules/`).
+
+## Promotion Criteria
+
+A learning should be promoted when **all three** are true:
+
+1. **Proven** — appeared in 2+ sessions or confirmed correct after testing
+2. **Actionable** — can be written as a concrete instruction ("Use X", "Never Y")
+3. **Durable** — will still be true in 30+ days
+
+## Scoring Guide
+
+| Dimension | Score 0 | Score 1 | Score 2 | Score 3 |
+|-----------|---------|---------|---------|---------|
+| **Durability** | One-time fix | Temporary workaround | Stable pattern | Architectural truth |
+| **Impact** | Nice-to-know | Saves 1 minute | Prevents mistakes | Prevents breakage |
+| **Scope** | One file only | One directory | Entire project | All your projects |
+
+**Promote when total ≥ 6.** Watch when total = 4-5. Ignore when total ≤ 3.
+
+## Target Selection
+
+### Use CLAUDE.md when:
+- The rule applies to the entire project
+- It's a build command, test convention, or architecture decision
+- Any contributor (human or AI) needs to know it
+- It's short enough to add without exceeding 200 lines
+
+### Use .claude/rules/ when:
+- The rule only applies to specific file types
+- CLAUDE.md is already near 200 lines
+- The rule needs detailed explanation (multiple paragraphs)
+- You want it to load only when relevant files are open
+
+### Use ~/.claude/CLAUDE.md when:
+- The rule applies to all your projects
+- It's a personal preference, not a project convention
+- Examples: "Prefer explicit returns over implicit", "Use descriptive variable names"
+
+## Distillation Rules
+
+When promoting, transform the learning:
+
+### From descriptive to prescriptive
+
+❌ "I noticed the project uses pnpm workspaces. npm install fails because of the lock file."
+✅ "Use `pnpm install`, not npm. Lock file: `pnpm-lock.yaml`."
+
+### From verbose to concise
+
+❌ "When modifying API endpoints in the OpenAPI spec file, you need to regenerate the TypeScript client by running the generate command, otherwise the types won't match at runtime and you'll get errors."
+✅ "After editing `openapi.yaml`: run `pnpm run generate:api` to regenerate TS client."
+
+### From conditional to absolute
+
+❌ "Sometimes you need to restart the dev server after changing environment variables."
+✅ "Restart dev server after any `.env` change — hot reload doesn't pick up env vars."
+
+## Anti-Patterns
+
+### Don't promote:
+- **One-time debugging notes** — "Fixed the CORS issue by adding header X" (unless it recurs)
+- **Session-specific context** — "We decided to use Approach A in today's meeting"
+- **Unstable patterns** — "Currently using v3 of the API" (will change)
+- **Obvious things** — "Run tests before committing" (Claude knows this)
+- **Credentials or secrets** — never store in any memory file
+
+### Don't duplicate:
+- If CLAUDE.md already says "Use pnpm", don't also keep it in MEMORY.md
+- After promoting, remove the source entry to free space
+
+## Promotion Workflow
+
+```
+1. /si:review identifies candidate
+2. Confirm the pattern is still valid
+3. Distill into one-line instruction
+4. /si:promote writes to CLAUDE.md or rules/
+5. Remove from MEMORY.md
+6. Verify with /si:status
+```
diff --git a/skills/auto-memory-pro/reference/rules-directory-patterns.md b/skills/auto-memory-pro/reference/rules-directory-patterns.md
new file mode 100644
index 00000000..0d5bd763
--- /dev/null
+++ b/skills/auto-memory-pro/reference/rules-directory-patterns.md
@@ -0,0 +1,137 @@
+# Rules Directory Patterns
+
+Best practices for organizing `.claude/rules/` files — the scoped instruction system that loads rules only when relevant files are open.
+
+## Directory Structure
+
+```
+.claude/
+├── CLAUDE.md # Main project instructions (always loaded)
+└── rules/
+ ├── code-style.md # No paths → loads always (like CLAUDE.md)
+ ├── testing.md # Scoped to test files
+ ├── api-design.md # Scoped to API source files
+ ├── database.md # Scoped to migration/model files
+ └── frontend/
+ ├── components.md # Scoped to React components
+ └── styling.md # Scoped to CSS/styled files
+```
+
+## Path Scoping
+
+### Basic patterns
+
+```yaml
+---
+paths:
+ - "**/*.test.ts" # All TypeScript test files
+ - "src/api/**/*.ts" # API source files
+ - "*.md" # Root-level markdown
+ - "src/components/**/*.tsx" # React components
+---
+```
+
+### Brace expansion
+
+```yaml
+---
+paths:
+ - "src/**/*.{ts,tsx}" # All TypeScript + TSX
+ - "tests/**/*.{test,spec}.ts" # Test and spec files
+---
+```
+
+### Multiple scopes
+
+```yaml
+---
+paths:
+ - "src/api/**/*.ts"
+ - "tests/api/**/*"
+ - "openapi.yaml"
+---
+```
+
+## Common Rule Files
+
+### testing.md
+```yaml
+---
+paths:
+ - "**/*.test.{ts,tsx,js,jsx}"
+ - "**/*.spec.{ts,tsx,js,jsx}"
+ - "tests/**/*"
+ - "__tests__/**/*"
+---
+
+# Testing Rules
+
+- Use `describe` blocks to group related tests
+- One assertion per test when possible
+- Mock external services; never hit real APIs in tests
+- Use factories for test data, not inline objects
+- Run `pnpm test` before committing
+```
+
+### api-design.md
+```yaml
+---
+paths:
+ - "src/api/**/*.ts"
+ - "src/routes/**/*.ts"
+ - "src/handlers/**/*.ts"
+---
+
+# API Design Rules
+
+- Validate all input with Zod schemas
+- Use `ApiError` class for error responses
+- Include OpenAPI JSDoc on all handlers
+- Return consistent error format: `{ error: string, code: string }`
+```
+
+### database.md
+```yaml
+---
+paths:
+ - "src/db/**/*"
+ - "migrations/**/*"
+ - "prisma/**/*"
+ - "drizzle/**/*"
+---
+
+# Database Rules
+
+- Always create a migration for schema changes
+- Never modify existing migrations — create new ones
+- Use transactions for multi-table operations
+- Index foreign keys and frequently queried columns
+```
+
+### security.md (unscoped — always loads)
+```markdown
+# Security Rules
+
+- Never log sensitive data (tokens, passwords, PII)
+- Sanitize all user input before database queries
+- Use parameterized queries, never string interpolation
+- Validate file uploads: type, size, content
+- Environment variables for all secrets — never hardcode
+```
+
+## When to Create a Rule File
+
+| Signal | Action |
+|--------|--------|
+| CLAUDE.md over 150 lines | Move scoped patterns to rules/ |
+| Same instruction repeated for different file types | Create a scoped rule |
+| `/si:promote` suggests a file-type-specific pattern | Create or append to a rule file |
+| Team adds a new convention for a specific area | New rule file |
+
+## Organization Tips
+
+1. **One topic per file** — `testing.md`, not `testing-and-linting.md`
+2. **Use subdirectories for large projects** — `rules/frontend/`, `rules/backend/`
+3. **Keep unscoped rules minimal** — they load every session like CLAUDE.md
+4. **Review after refactors** — paths may change when directories are reorganized
+5. **Share via git** — rules/ should be version-controlled (unlike auto-memory)
diff --git a/skills/auto-memory-pro/settings.json b/skills/auto-memory-pro/settings.json
new file mode 100644
index 00000000..06b52827
--- /dev/null
+++ b/skills/auto-memory-pro/settings.json
@@ -0,0 +1,28 @@
+{
+ "name": "self-improving-agent",
+ "displayName": "Self-Improving Agent",
+ "version": "1.0.0",
+ "description": "Curate auto-memory, promote learnings to rules, extract skills from patterns.",
+ "author": "Reza Rezvani",
+ "license": "MIT",
+ "platforms": ["claude-code", "openclaw", "codex"],
+ "category": "development",
+ "tags": ["memory", "auto-memory", "self-improvement", "learning", "rules", "skills"],
+ "repository": "https://github.com/alirezarezvani/claude-skills",
+ "commands": {
+ "review": "/si:review",
+ "promote": "/si:promote",
+ "extract": "/si:extract",
+ "status": "/si:status",
+ "remember": "/si:remember"
+ },
+ "hooks": {
+ "PostToolUse": {
+ "Bash": "hooks/error-capture.sh"
+ }
+ },
+ "agents": [
+ "memory-analyst",
+ "skill-extractor"
+ ]
+}
diff --git a/skills/auto-memory-pro/skills/extract/SKILL.md b/skills/auto-memory-pro/skills/extract/SKILL.md
new file mode 100644
index 00000000..c43f4adb
--- /dev/null
+++ b/skills/auto-memory-pro/skills/extract/SKILL.md
@@ -0,0 +1,179 @@
+---
+name: extract
+description: "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples."
+command: /si:extract
+---
+
+# /si:extract — Create Skills from Patterns
+
+Transforms a recurring pattern or debugging solution into a standalone, portable skill that can be installed in any project.
+
+## Usage
+
+```
+/si:extract # Interactive extraction
+/si:extract --name docker-m1-fixes # Specify skill name
+/si:extract --output ./skills/ # Custom output directory
+/si:extract --dry-run # Preview without creating files
+```
+
+## When to Extract
+
+A learning qualifies for skill extraction when ANY of these are true:
+
+| Criterion | Signal |
+|---|---|
+| **Recurring** | Same issue across 2+ projects |
+| **Non-obvious** | Required real debugging to discover |
+| **Broadly applicable** | Not tied to one specific codebase |
+| **Complex solution** | Multi-step fix that's easy to forget |
+| **User-flagged** | "Save this as a skill", "I want to reuse this" |
+
+## Workflow
+
+### Step 1: Identify the pattern
+
+Read the user's description. Search auto-memory for related entries:
+
+```bash
+MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory"
+grep -rni "" "$MEMORY_DIR/"
+```
+
+If found in auto-memory, use those entries as source material. If not, use the user's description directly.
+
+### Step 2: Determine skill scope
+
+Ask (max 2 questions):
+- "What problem does this solve?" (if not clear)
+- "Should this include code examples?" (if applicable)
+
+### Step 3: Generate skill name
+
+Rules for naming:
+- Lowercase, hyphens between words
+- Descriptive but concise (2-4 words)
+- Examples: `docker-m1-fixes`, `api-timeout-patterns`, `pnpm-workspace-setup`
+
+### Step 4: Create the skill files
+
+**Spawn the `skill-extractor` agent** for the actual file generation.
+
+The agent creates:
+
+```
+/
+├── SKILL.md # Main skill file with frontmatter
+├── README.md # Human-readable overview
+└── reference/ # (optional) Supporting documentation
+ └── examples.md # Concrete examples and edge cases
+```
+
+### Step 5: SKILL.md structure
+
+The generated SKILL.md must follow this format:
+
+```markdown
+---
+name:
+description: ". Use when: ."
+---
+
+#
+
+> One-line summary of what this skill solves.
+
+## Quick Reference
+
+| Problem | Solution |
+|---------|----------|
+| {{problem 1}} | {{solution 1}} |
+| {{problem 2}} | {{solution 2}} |
+
+## The Problem
+
+{{2-3 sentences explaining what goes wrong and why it's non-obvious.}}
+
+## Solutions
+
+### Option 1: {{Name}} (Recommended)
+
+{{Step-by-step with code examples.}}
+
+### Option 2: {{Alternative}}
+
+{{For when Option 1 doesn't apply.}}
+
+## Trade-offs
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Option 1 | {{pros}} | {{cons}} |
+| Option 2 | {{pros}} | {{cons}} |
+
+## Edge Cases
+
+- {{edge case 1 and how to handle it}}
+- {{edge case 2 and how to handle it}}
+```
+
+### Step 6: Quality gates
+
+Before finalizing, verify:
+
+- [ ] SKILL.md has valid YAML frontmatter with `name` and `description`
+- [ ] `name` matches the folder name (lowercase, hyphens)
+- [ ] Description includes "Use when:" trigger conditions
+- [ ] Solutions are self-contained (no external context needed)
+- [ ] Code examples are complete and copy-pasteable
+- [ ] No project-specific hardcoded values (paths, URLs, credentials)
+- [ ] No unnecessary dependencies
+
+### Step 7: Report
+
+```
+✅ Skill extracted: {{skill-name}}
+
+Files created:
+ {{path}}/SKILL.md ({{lines}} lines)
+ {{path}}/README.md ({{lines}} lines)
+ {{path}}/reference/examples.md ({{lines}} lines)
+
+Install: /plugin install (copy to your skills directory)
+Publish: clawhub publish {{path}}
+
+Source: MEMORY.md entries at lines {{n, m, ...}} (retained — the skill is portable, the memory is project-specific)
+```
+
+## Examples
+
+### Extracting a debugging pattern
+
+```
+/si:extract "Fix for Docker builds failing on Apple Silicon with platform mismatch"
+```
+
+Creates `docker-m1-fixes/SKILL.md` with:
+- The platform mismatch error message
+- Three solutions (build flag, Dockerfile, docker-compose)
+- Trade-offs table
+- Performance note about Rosetta 2 emulation
+
+### Extracting a workflow pattern
+
+```
+/si:extract "Always regenerate TypeScript API client after modifying OpenAPI spec"
+```
+
+Creates `api-client-regen/SKILL.md` with:
+- Why manual regen is needed
+- The exact command sequence
+- CI integration snippet
+- Common failure modes
+
+## Tips
+
+- Extract patterns that would save time in a *different* project
+- Keep skills focused — one problem per skill
+- Include the error messages people would search for
+- Test the skill by reading it without the original context — does it make sense?
diff --git a/skills/auto-memory-pro/skills/promote/SKILL.md b/skills/auto-memory-pro/skills/promote/SKILL.md
new file mode 100644
index 00000000..2b7fa0f6
--- /dev/null
+++ b/skills/auto-memory-pro/skills/promote/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: promote
+description: "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement."
+command: /si:promote
+---
+
+# /si:promote — Graduate Learnings to Rules
+
+Moves a proven pattern from Claude's auto-memory into the project's rule system, where it becomes an enforced instruction rather than a background note.
+
+## Usage
+
+```
+/si:promote # Auto-detect best target
+/si:promote --target claude.md # Promote to CLAUDE.md
+/si:promote --target rules/testing.md # Promote to scoped rule
+/si:promote --target rules/api.md --paths "src/api/**/*.ts" # Scoped with paths
+```
+
+## Workflow
+
+### Step 1: Understand the pattern
+
+Parse the user's description. If vague, ask one clarifying question:
+- "What specific behavior should Claude follow?"
+- "Does this apply to all files or specific paths?"
+
+### Step 2: Find the pattern in auto-memory
+
+```bash
+# Search MEMORY.md for related entries
+MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory"
+grep -ni "" "$MEMORY_DIR/MEMORY.md"
+```
+
+Show the matching entries and confirm they're what the user means.
+
+### Step 3: Determine the right target
+
+| Pattern scope | Target | Example |
+|---|---|---|
+| Applies to entire project | `./CLAUDE.md` | "Use pnpm, not npm" |
+| Applies to specific file types | `.claude/rules/.md` | "API handlers need validation" |
+| Applies to all your projects | `~/.claude/CLAUDE.md` | "Prefer explicit error handling" |
+
+If the user didn't specify a target, recommend one based on scope.
+
+### Step 4: Distill into a concise rule
+
+Transform the learning from auto-memory's note format into CLAUDE.md's instruction format:
+
+**Before** (MEMORY.md — descriptive):
+> The project uses pnpm workspaces. When I tried npm install it failed. The lock file is pnpm-lock.yaml. Must use pnpm install for dependencies.
+
+**After** (CLAUDE.md — prescriptive):
+```markdown
+## Build & Dependencies
+- Package manager: pnpm (not npm). Use `pnpm install`.
+```
+
+**Rules for distillation:**
+- One line per rule when possible
+- Imperative voice ("Use X", "Always Y", "Never Z")
+- Include the command or example, not just the concept
+- No backstory — just the instruction
+
+### Step 5: Write to target
+
+**For CLAUDE.md:**
+1. Read existing CLAUDE.md
+2. Find the appropriate section (or create one)
+3. Append the new rule under the right heading
+4. If file would exceed 200 lines, suggest using `.claude/rules/` instead
+
+**For `.claude/rules/`:**
+1. Create the file if it doesn't exist
+2. Add YAML frontmatter with `paths` if scoped
+3. Write the rule content
+
+```markdown
+---
+paths:
+ - "src/api/**/*.ts"
+ - "tests/api/**/*"
+---
+
+# API Development Rules
+
+- All endpoints must validate input with Zod schemas
+- Use `ApiError` class for error responses (not raw Error)
+- Include OpenAPI JSDoc comments on handler functions
+```
+
+### Step 6: Clean up auto-memory
+
+After promoting, remove or mark the original entry in MEMORY.md:
+
+```bash
+# Show what will be removed
+grep -n "" "$MEMORY_DIR/MEMORY.md"
+```
+
+Ask the user to confirm removal. Then edit MEMORY.md to remove the promoted entry. This frees space for new learnings.
+
+### Step 7: Confirm
+
+```
+✅ Promoted to {{target}}
+
+Rule: "{{distilled rule}}"
+Source: MEMORY.md line {{n}} (removed)
+MEMORY.md: {{lines}}/200 lines remaining
+
+The pattern is now an enforced instruction. Claude will follow it in all future sessions.
+```
+
+## Promotion Decision Guide
+
+### Promote when:
+- Pattern appeared 3+ times in auto-memory
+- You corrected Claude about it more than once
+- It's a project convention that any contributor should know
+- It prevents a recurring mistake
+
+### Don't promote when:
+- It's a one-time debugging note (leave in auto-memory)
+- It's session-specific context (session memory handles this)
+- It might change soon (e.g., during a migration)
+- It's already covered by existing rules
+
+### CLAUDE.md vs .claude/rules/
+
+| Use CLAUDE.md for | Use .claude/rules/ for |
+|---|---|
+| Global project rules | File-type-specific patterns |
+| Build commands | Testing conventions |
+| Architecture decisions | API design rules |
+| Team conventions | Framework-specific gotchas |
+
+## Tips
+
+- Keep CLAUDE.md under 200 lines — use rules/ for overflow
+- One rule per line is easier to maintain than paragraphs
+- Include the concrete command, not just the concept
+- Review promoted rules quarterly — remove what's no longer relevant
diff --git a/skills/auto-memory-pro/skills/remember/SKILL.md b/skills/auto-memory-pro/skills/remember/SKILL.md
new file mode 100644
index 00000000..a7939941
--- /dev/null
+++ b/skills/auto-memory-pro/skills/remember/SKILL.md
@@ -0,0 +1,99 @@
+---
+name: remember
+description: "Explicitly save important knowledge to auto-memory with timestamp and context. Use when a discovery is too important to rely on auto-capture."
+command: /si:remember
+---
+
+# /si:remember — Save Knowledge Explicitly
+
+Writes an explicit entry to auto-memory when something is important enough that you don't want to rely on Claude noticing it automatically.
+
+## Usage
+
+```
+/si:remember
+/si:remember "This project's CI requires Node 20 LTS — v22 breaks the build"
+/si:remember "The /api/auth endpoint uses a custom JWT library, not passport"
+/si:remember "Reza prefers explicit error handling over try-catch-all patterns"
+```
+
+## When to Use
+
+| Situation | Example |
+|-----------|---------|
+| Hard-won debugging insight | "CORS errors on /api/upload are caused by the CDN, not the backend" |
+| Project convention not in CLAUDE.md | "We use barrel exports in src/components/" |
+| Tool-specific gotcha | "Jest needs `--forceExit` flag or it hangs on DB tests" |
+| Architecture decision | "We chose Drizzle over Prisma for type-safe SQL" |
+| Preference you want Claude to learn | "Don't add comments explaining obvious code" |
+
+## Workflow
+
+### Step 1: Parse the knowledge
+
+Extract from the user's input:
+- **What**: The concrete fact or pattern
+- **Why it matters**: Context (if provided)
+- **Scope**: Project-specific or global?
+
+### Step 2: Check for duplicates
+
+```bash
+MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory"
+grep -ni "" "$MEMORY_DIR/MEMORY.md" 2>/dev/null
+```
+
+If a similar entry exists:
+- Show it to the user
+- Ask: "Update the existing entry or add a new one?"
+
+### Step 3: Write to MEMORY.md
+
+Append to the end of `MEMORY.md`:
+
+```markdown
+- {{concise fact or pattern}}
+```
+
+Keep entries concise — one line when possible. Auto-memory entries don't need timestamps, IDs, or metadata. They're notes, not database records.
+
+If MEMORY.md is over 180 lines, warn the user:
+
+```
+⚠️ MEMORY.md is at {{n}}/200 lines. Consider running /si:review to free space.
+```
+
+### Step 4: Suggest promotion
+
+If the knowledge sounds like a rule (imperative, always/never, convention):
+
+```
+💡 This sounds like it could be a CLAUDE.md rule rather than a memory entry.
+ Rules are enforced with higher priority. Want to /si:promote it instead?
+```
+
+### Step 5: Confirm
+
+```
+✅ Saved to auto-memory
+
+ "{{entry}}"
+
+ MEMORY.md: {{n}}/200 lines
+ Claude will see this at the start of every session in this project.
+```
+
+## What NOT to use /si:remember for
+
+- **Temporary context**: Use session memory or just tell Claude in conversation
+- **Enforced rules**: Use `/si:promote` to write directly to CLAUDE.md
+- **Cross-project knowledge**: Use `~/.claude/CLAUDE.md` for global rules
+- **Sensitive data**: Never store credentials, tokens, or secrets in memory files
+
+## Tips
+
+- Be concise — one line beats a paragraph
+- Include the concrete command or value, not just the concept
+ - ✅ "Build with `pnpm build`, tests with `pnpm test:e2e`"
+ - ❌ "The project uses pnpm for building and testing"
+- If you're remembering the same thing twice, promote it to CLAUDE.md
diff --git a/skills/auto-memory-pro/skills/review/SKILL.md b/skills/auto-memory-pro/skills/review/SKILL.md
new file mode 100644
index 00000000..24179532
--- /dev/null
+++ b/skills/auto-memory-pro/skills/review/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: review
+description: "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics."
+command: /si:review
+---
+
+# /si:review — Analyze Auto-Memory
+
+Performs a comprehensive audit of Claude Code's auto-memory and produces actionable recommendations.
+
+## Usage
+
+```
+/si:review # Full review
+/si:review --quick # Summary only (counts + top 3 candidates)
+/si:review --stale # Focus on stale/outdated entries
+/si:review --candidates # Show only promotion candidates
+```
+
+## What It Does
+
+### Step 1: Locate memory directory
+
+```bash
+# Find the project's auto-memory directory
+MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory"
+
+# Fallback: check common path patterns
+# ~/.claude/projects///memory/
+# ~/.claude/projects//memory/
+
+# List all memory files
+ls -la "$MEMORY_DIR"/
+```
+
+If memory directory doesn't exist, report that auto-memory may be disabled. Suggest checking with `/memory`.
+
+### Step 2: Read and analyze MEMORY.md
+
+Read the full `MEMORY.md` file. Count lines and check against the 200-line startup limit.
+
+Analyze each entry for:
+
+1. **Recurrence indicators**
+ - Same concept appears multiple times (different wording)
+ - References to "again" or "still" or "keeps happening"
+ - Similar entries across topic files
+
+2. **Staleness indicators**
+ - References files that no longer exist (`find` to verify)
+ - Mentions outdated tools, versions, or commands
+ - Contradicts current CLAUDE.md rules
+
+3. **Consolidation opportunities**
+ - Multiple entries about the same topic (e.g., three lines about testing)
+ - Entries that could merge into one concise rule
+
+4. **Promotion candidates** — entries that meet ALL criteria:
+ - Appeared in 2+ sessions (check wording patterns)
+ - Not project-specific trivia (broadly useful)
+ - Actionable (can be written as a concrete rule)
+ - Not already in CLAUDE.md or `.claude/rules/`
+
+### Step 3: Read topic files
+
+If `MEMORY.md` references or the directory contains additional files (`debugging.md`, `patterns.md`, etc.):
+- Read each one
+- Cross-reference with MEMORY.md for duplicates
+- Check for entries that belong in the main file (high value) vs. topic files (details)
+
+### Step 4: Cross-reference with CLAUDE.md
+
+Read the project's `CLAUDE.md` (if it exists) and compare:
+- Are there MEMORY.md entries that duplicate CLAUDE.md rules? (→ remove from memory)
+- Are there MEMORY.md entries that contradict CLAUDE.md? (→ flag conflict)
+- Are there MEMORY.md patterns not yet in CLAUDE.md that should be? (→ promotion candidate)
+
+Also check `.claude/rules/` directory for existing scoped rules.
+
+### Step 5: Generate report
+
+Output format:
+
+```
+📊 Auto-Memory Review
+
+Memory Health:
+ MEMORY.md: {{lines}}/200 lines ({{percent}}%)
+ Topic files: {{count}} ({{names}})
+ CLAUDE.md: {{lines}} lines
+ Rules: {{count}} files in .claude/rules/
+
+🎯 Promotion Candidates ({{count}}):
+ 1. "{{pattern}}" — seen {{n}}x, applies broadly
+ → Suggest: {{target}} (CLAUDE.md / .claude/rules/{{name}}.md)
+ 2. ...
+
+🗑️ Stale Entries ({{count}}):
+ 1. Line {{n}}: "{{entry}}" — {{reason}}
+ 2. ...
+
+🔄 Consolidation ({{count}} groups):
+ 1. Lines {{a}}, {{b}}, {{c}} all about {{topic}} → merge into 1 entry
+ 2. ...
+
+⚠️ Conflicts ({{count}}):
+ 1. MEMORY.md line {{n}} contradicts CLAUDE.md: {{detail}}
+
+💡 Recommendations:
+ - {{actionable suggestion}}
+ - {{actionable suggestion}}
+```
+
+## When to Use
+
+- After completing a major feature or debugging session
+- When `/si:status` shows MEMORY.md is over 150 lines
+- Weekly during active development
+- Before starting a new project phase
+- After onboarding a new team member (review what Claude learned)
+
+## Tips
+
+- Run `/si:review --quick` frequently (low overhead)
+- Full review is most valuable when MEMORY.md is getting crowded
+- Act on promotion candidates promptly — they're proven patterns
+- Don't hesitate to delete stale entries — auto-memory will re-learn if needed
diff --git a/skills/auto-memory-pro/skills/status/SKILL.md b/skills/auto-memory-pro/skills/status/SKILL.md
new file mode 100644
index 00000000..0e6f5950
--- /dev/null
+++ b/skills/auto-memory-pro/skills/status/SKILL.md
@@ -0,0 +1,104 @@
+---
+name: status
+description: "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations."
+command: /si:status
+---
+
+# /si:status — Memory Health Dashboard
+
+Quick overview of your project's memory state across all memory systems.
+
+## Usage
+
+```
+/si:status # Full dashboard
+/si:status --brief # One-line summary
+```
+
+## What It Reports
+
+### Step 1: Locate all memory files
+
+```bash
+# Auto-memory directory
+MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory"
+
+# Count lines in MEMORY.md
+wc -l "$MEMORY_DIR/MEMORY.md" 2>/dev/null || echo "0"
+
+# List topic files
+ls "$MEMORY_DIR/"*.md 2>/dev/null | grep -v MEMORY.md
+
+# CLAUDE.md
+wc -l ./CLAUDE.md 2>/dev/null || echo "0"
+wc -l ~/.claude/CLAUDE.md 2>/dev/null || echo "0"
+
+# Rules directory
+ls .claude/rules/*.md 2>/dev/null | wc -l
+```
+
+### Step 2: Analyze capacity
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| MEMORY.md lines | < 120 | 120-180 | > 180 |
+| CLAUDE.md lines | < 150 | 150-200 | > 200 |
+| Topic files | 0-3 | 4-6 | > 6 |
+| Stale entries | 0 | 1-3 | > 3 |
+
+### Step 3: Quick stale check
+
+For each MEMORY.md entry that references a file path:
+```bash
+# Verify referenced files still exist
+grep -oE '[a-zA-Z0-9_/.-]+\.(ts|js|py|md|json|yaml|yml)' "$MEMORY_DIR/MEMORY.md" | while read f; do
+ [ ! -f "$f" ] && echo "STALE: $f"
+done
+```
+
+### Step 4: Output
+
+```
+📊 Memory Status
+
+ Auto-Memory (MEMORY.md):
+ Lines: {{n}}/200 ({{bar}}) {{emoji}}
+ Topic files: {{count}} ({{names}})
+ Last updated: {{date}}
+
+ Project Rules:
+ CLAUDE.md: {{n}} lines
+ Rules: {{count}} files in .claude/rules/
+ User global: {{n}} lines (~/.claude/CLAUDE.md)
+
+ Health:
+ Capacity: {{healthy/warning/critical}}
+ Stale refs: {{count}} (files no longer exist)
+ Duplicates: {{count}} (entries repeated across files)
+
+ {{if recommendations}}
+ 💡 Recommendations:
+ - {{recommendation}}
+ {{endif}}
+```
+
+### Brief mode
+
+```
+/si:status --brief
+```
+
+Output: `📊 Memory: {{n}}/200 lines | {{count}} rules | {{status_emoji}} {{status_word}}`
+
+## Interpretation
+
+- **Green (< 60%)**: Plenty of room. Auto-memory is working well.
+- **Yellow (60-90%)**: Getting full. Consider running `/si:review` to promote or clean up.
+- **Red (> 90%)**: Near capacity. Auto-memory may start dropping older entries. Run `/si:review` now.
+
+## Tips
+
+- Run `/si:status --brief` as a quick check anytime
+- If capacity is yellow+, run `/si:review` to identify promotion candidates
+- Stale entries waste space — delete references to files that no longer exist
+- Topic files are fine — Claude creates them to keep MEMORY.md under 200 lines
diff --git a/skills/auto-memory-pro/templates/rule-template.md b/skills/auto-memory-pro/templates/rule-template.md
new file mode 100644
index 00000000..3e87d515
--- /dev/null
+++ b/skills/auto-memory-pro/templates/rule-template.md
@@ -0,0 +1,17 @@
+---
+paths:
+ - "{{glob-pattern}}"
+---
+
+# {{Topic}} Rules
+
+## Conventions
+- {{convention 1}}
+- {{convention 2}}
+
+## Patterns
+- {{preferred pattern with example}}
+- {{anti-pattern to avoid}}
+
+## Commands
+- {{relevant command}}: `{{command}}`
diff --git a/skills/auto-memory-pro/templates/skill-template.md b/skills/auto-memory-pro/templates/skill-template.md
new file mode 100644
index 00000000..ce596a2f
--- /dev/null
+++ b/skills/auto-memory-pro/templates/skill-template.md
@@ -0,0 +1,53 @@
+---
+name: {{skill-name}}
+description: "{{One-line description}}. Use when: {{trigger conditions}}."
+---
+
+# {{Skill Title}}
+
+> {{One-line value proposition}}
+
+## Quick Reference
+
+| Problem | Solution |
+|---------|----------|
+| {{error/symptom 1}} | {{fix 1}} |
+| {{error/symptom 2}} | {{fix 2}} |
+
+## The Problem
+
+{{2-3 sentences explaining what goes wrong and why.
+Include the exact error message if applicable.}}
+
+## Solutions
+
+### Option 1: {{Name}} (Recommended)
+
+{{Step-by-step instructions.}}
+
+```{{language}}
+{{code example}}
+```
+
+### Option 2: {{Alternative}}
+
+{{When Option 1 doesn't apply.}}
+
+```{{language}}
+{{code example}}
+```
+
+## Trade-offs
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Option 1 | {{pros}} | {{cons}} |
+| Option 2 | {{pros}} | {{cons}} |
+
+## Edge Cases
+
+- {{edge case and how to handle it}}
+
+## Related
+
+- {{link to official docs}}
diff --git a/skills/autoresearch-agent/CLAUDE.md b/skills/autoresearch-agent/CLAUDE.md
new file mode 100644
index 00000000..728d4b49
--- /dev/null
+++ b/skills/autoresearch-agent/CLAUDE.md
@@ -0,0 +1,66 @@
+# Autoresearch Agent — Claude Code Instructions
+
+This plugin runs autonomous experiment loops that optimize any file by a measurable metric.
+
+## Commands
+
+Use the `/ar:` namespace for all commands:
+
+- `/ar:setup` — Set up a new experiment interactively
+- `/ar:run` — Run a single experiment iteration
+- `/ar:loop` — Start an autonomous loop with user-selected interval
+- `/ar:status` — Show dashboard and results
+- `/ar:resume` — Resume a paused experiment
+
+## How it works
+
+You (the AI agent) are the experiment loop. The scripts handle evaluation and git rollback.
+
+1. You edit the target file with ONE change
+2. You commit it
+3. You call `run_experiment.py --single` — it evaluates and prints KEEP/DISCARD/CRASH
+4. You repeat
+
+Results persist in `results.tsv` and git log. Sessions can be resumed.
+
+## When to use each command
+
+### Starting fresh
+```
+/ar:setup
+```
+Creates the experiment directory, config, program.md, results.tsv, and git branch.
+
+### Running one iteration at a time
+```
+/ar:run engineering/api-speed
+```
+Read history, make one change, evaluate, report result.
+
+### Autonomous background loop
+```
+/ar:loop engineering/api-speed
+```
+Prompts for interval (10min, 1h, daily, weekly, monthly), then creates a recurring job.
+
+### Checking progress
+```
+/ar:status
+```
+Shows the dashboard across all experiments with metrics and trends.
+
+### Resuming after context limit or break
+```
+/ar:resume engineering/api-speed
+```
+Reads results history, checks out the branch, and continues where you left off.
+
+## Agents
+
+- **experiment-runner**: Spawned for each loop iteration. Reads config, results history, decides what to try, edits target, commits, evaluates.
+
+## Key principle
+
+**One change per experiment. Measure everything. Compound improvements.**
+
+The agent never modifies the evaluator. The evaluator is ground truth.
diff --git a/skills/autoresearch-agent/SKILL.md b/skills/autoresearch-agent/SKILL.md
new file mode 100644
index 00000000..e9efaa1a
--- /dev/null
+++ b/skills/autoresearch-agent/SKILL.md
@@ -0,0 +1,308 @@
+---
+name: "autoresearch-agent"
+description: "Autonomous experiment loop that optimizes any file by a measurable metric. Inspired by Karpathy's autoresearch. The agent edits a target file, runs a fixed evaluation, keeps improvements (git commit), discards failures (git reset), and loops indefinitely. Use when: user wants to optimize code speed, reduce bundle/image size, improve test pass rate, optimize prompts, improve content quality (headlines, copy, CTR), or run any measurable improvement loop. Requires: a target file, an evaluation command that outputs a metric, and a git repo."
+license: MIT
+metadata:
+ version: 2.0.0
+ author: Alireza Rezvani
+ category: engineering
+ updated: 2026-03-13
+---
+
+# Autoresearch Agent
+
+> You sleep. The agent experiments. You wake up to results.
+
+Autonomous experiment loop inspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch). The agent edits one file, runs a fixed evaluation, keeps improvements, discards failures, and loops indefinitely.
+
+Not one guess — fifty measured attempts, compounding.
+
+---
+
+## Slash Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/ar:setup` | Set up a new experiment interactively |
+| `/ar:run` | Run a single experiment iteration |
+| `/ar:loop` | Start autonomous loop with configurable interval (10m, 1h, daily, weekly, monthly) |
+| `/ar:status` | Show dashboard and results |
+| `/ar:resume` | Resume a paused experiment |
+
+---
+
+## When This Skill Activates
+
+Recognize these patterns from the user:
+
+- "Make this faster / smaller / better"
+- "Optimize [file] for [metric]"
+- "Improve my [headlines / copy / prompts]"
+- "Run experiments overnight"
+- "I want to get [metric] from X to Y"
+- Any request involving: optimize, benchmark, improve, experiment loop, autoresearch
+
+If the user describes a target file + a way to measure success → this skill applies.
+
+---
+
+## Setup
+
+### First Time — Create the Experiment
+
+Run the setup script. The user decides where experiments live:
+
+**Project-level** (inside repo, git-tracked, shareable with team):
+```bash
+python scripts/setup_experiment.py \
+ --domain engineering \
+ --name api-speed \
+ --target src/api/search.py \
+ --eval "pytest bench.py --tb=no -q" \
+ --metric p50_ms \
+ --direction lower \
+ --scope project
+```
+
+**User-level** (personal, in `~/.autoresearch/`):
+```bash
+python scripts/setup_experiment.py \
+ --domain marketing \
+ --name medium-ctr \
+ --target content/titles.md \
+ --eval "python evaluate.py" \
+ --metric ctr_score \
+ --direction higher \
+ --evaluator llm_judge_content \
+ --scope user
+```
+
+The `--scope` flag determines where `.autoresearch/` lives:
+- `project` (default) → `.autoresearch/` in the repo root. Experiment definitions are git-tracked. Results are gitignored.
+- `user` → `~/.autoresearch/` in the home directory. Everything is personal.
+
+### What Setup Creates
+
+```
+.autoresearch/
+├── config.yaml ← Global settings
+├── .gitignore ← Ignores results.tsv, *.log
+└── {domain}/{experiment-name}/
+ ├── program.md ← Objectives, constraints, strategy
+ ├── config.cfg ← Target, eval cmd, metric, direction
+ ├── results.tsv ← Experiment log (gitignored)
+ └── evaluate.py ← Evaluation script (if --evaluator used)
+```
+
+**results.tsv columns:** `commit | metric | status | description`
+- `commit` — short git hash
+- `metric` — float value or "N/A" for crashes
+- `status` — keep | discard | crash
+- `description` — what changed or why it crashed
+
+### Domains
+
+| Domain | Use Cases |
+|--------|-----------|
+| `engineering` | Code speed, memory, bundle size, test pass rate, build time |
+| `marketing` | Headlines, social copy, email subjects, ad copy, engagement |
+| `content` | Article structure, SEO descriptions, readability, CTR |
+| `prompts` | System prompts, chatbot tone, agent instructions |
+| `custom` | Anything else with a measurable metric |
+
+### If `program.md` Already Exists
+
+The user may have written their own `program.md`. If found in the experiment directory, read it. It overrides the template. Only ask for what's missing.
+
+---
+
+## Agent Protocol
+
+You are the loop. The scripts handle setup and evaluation — you handle the creative work.
+
+### Before Starting
+1. Read `.autoresearch/{domain}/{name}/config.cfg` to get:
+ - `target` — the file you edit
+ - `evaluate_cmd` — the command that measures your changes
+ - `metric` — the metric name to look for in eval output
+ - `metric_direction` — "lower" or "higher" is better
+ - `time_budget_minutes` — max time per evaluation
+2. Read `program.md` for strategy, constraints, and what you can/cannot change
+3. Read `results.tsv` for experiment history (columns: commit, metric, status, description)
+4. Checkout the experiment branch: `git checkout autoresearch/{domain}/{name}`
+
+### Each Iteration
+1. Review results.tsv — what worked? What failed? What hasn't been tried?
+2. Decide ONE change to the target file. One variable per experiment.
+3. Edit the target file
+4. Commit: `git add {target} && git commit -m "experiment: {description}"`
+5. Evaluate: `python scripts/run_experiment.py --experiment {domain}/{name} --single`
+6. Read the output — it prints KEEP, DISCARD, or CRASH with the metric value
+7. Go to step 1
+
+### What the Script Handles (you don't)
+- Running the eval command with timeout
+- Parsing the metric from eval output
+- Comparing to previous best
+- Reverting the commit on failure (`git reset --hard HEAD~1`)
+- Logging the result to results.tsv
+
+### Starting an Experiment
+
+```bash
+# Single iteration (the agent calls this repeatedly)
+python scripts/run_experiment.py --experiment engineering/api-speed --single
+
+# Dry run (test setup before starting)
+python scripts/run_experiment.py --experiment engineering/api-speed --dry-run
+```
+
+### Strategy Escalation
+- Runs 1-5: Low-hanging fruit (obvious improvements, simple optimizations)
+- Runs 6-15: Systematic exploration (vary one parameter at a time)
+- Runs 16-30: Structural changes (algorithm swaps, architecture shifts)
+- Runs 30+: Radical experiments (completely different approaches)
+- If no improvement in 20+ runs: update program.md Strategy section
+
+### Self-Improvement
+After every 10 experiments, review results.tsv for patterns. Update the
+Strategy section of program.md with what you learned (e.g., "caching changes
+consistently improve by 5-10%", "refactoring attempts never improve the metric").
+Future iterations benefit from this accumulated knowledge.
+
+### Stopping
+- Run until interrupted by the user, context limit reached, or goal in program.md is met
+- Before stopping: ensure results.tsv is up to date
+- On context limit: the next session can resume — results.tsv and git log persist
+
+### Rules
+
+- **One change per experiment.** Don't change 5 things at once. You won't know what worked.
+- **Simplicity criterion.** A small improvement that adds ugly complexity is not worth it. Equal performance with simpler code is a win. Removing code that gets same results is the best outcome.
+- **Never modify the evaluator.** `evaluate.py` is the ground truth. Modifying it invalidates all comparisons. Hard stop if you catch yourself doing this.
+- **Timeout.** If a run exceeds 2.5× the time budget, kill it and treat as crash.
+- **Crash handling.** If it's a typo or missing import, fix and re-run. If the idea is fundamentally broken, revert, log "crash", move on. 5 consecutive crashes → pause and alert.
+- **No new dependencies.** Only use what's already available in the project.
+
+---
+
+## Evaluators
+
+Ready-to-use evaluation scripts. Copied into the experiment directory during setup with `--evaluator`.
+
+### Free Evaluators (no API cost)
+
+| Evaluator | Metric | Use Case |
+|-----------|--------|----------|
+| `benchmark_speed` | `p50_ms` (lower) | Function/API execution time |
+| `benchmark_size` | `size_bytes` (lower) | File, bundle, Docker image size |
+| `test_pass_rate` | `pass_rate` (higher) | Test suite pass percentage |
+| `build_speed` | `build_seconds` (lower) | Build/compile/Docker build time |
+| `memory_usage` | `peak_mb` (lower) | Peak memory during execution |
+
+### LLM Judge Evaluators (uses your subscription)
+
+| Evaluator | Metric | Use Case |
+|-----------|--------|----------|
+| `llm_judge_content` | `ctr_score` 0-10 (higher) | Headlines, titles, descriptions |
+| `llm_judge_prompt` | `quality_score` 0-100 (higher) | System prompts, agent instructions |
+| `llm_judge_copy` | `engagement_score` 0-10 (higher) | Social posts, ad copy, emails |
+
+LLM judges call the CLI tool the user is already running (Claude, Codex, Gemini). The evaluation prompt is locked inside `evaluate.py` — the agent cannot modify it. This prevents the agent from gaming its own evaluator.
+
+The user's existing subscription covers the cost:
+- Claude Code Max → unlimited Claude calls for evaluation
+- Codex CLI (ChatGPT Pro) → unlimited Codex calls
+- Gemini CLI (free tier) → free evaluation calls
+
+### Custom Evaluators
+
+If no built-in evaluator fits, the user writes their own `evaluate.py`. Only requirement: it must print `metric_name: value` to stdout.
+
+```python
+#!/usr/bin/env python3
+# My custom evaluator — DO NOT MODIFY after experiment starts
+import subprocess
+result = subprocess.run(["my-benchmark", "--json"], capture_output=True, text=True)
+# Parse and output
+print(f"my_metric: {parse_score(result.stdout)}")
+```
+
+---
+
+## Viewing Results
+
+```bash
+# Single experiment
+python scripts/log_results.py --experiment engineering/api-speed
+
+# All experiments in a domain
+python scripts/log_results.py --domain engineering
+
+# Cross-experiment dashboard
+python scripts/log_results.py --dashboard
+
+# Export formats
+python scripts/log_results.py --experiment engineering/api-speed --format csv --output results.csv
+python scripts/log_results.py --experiment engineering/api-speed --format markdown --output results.md
+python scripts/log_results.py --dashboard --format markdown --output dashboard.md
+```
+
+### Dashboard Output
+
+```
+DOMAIN EXPERIMENT RUNS KEPT BEST Δ FROM START STATUS
+engineering api-speed 47 14 185ms -76.9% active
+engineering bundle-size 23 8 412KB -58.3% paused
+marketing medium-ctr 31 11 8.4/10 +68.0% active
+prompts support-tone 15 6 82/100 +46.4% done
+```
+
+### Export Formats
+
+- **TSV** — default, tab-separated (compatible with spreadsheets)
+- **CSV** — comma-separated, with proper quoting
+- **Markdown** — formatted table, readable in GitHub/docs
+
+---
+
+## Proactive Triggers
+
+Flag these without being asked:
+
+- **No evaluation command works** → Test it before starting the loop. Run once, verify output.
+- **Target file not in git** → `git init && git add . && git commit -m 'initial'` first.
+- **Metric direction unclear** → Ask: is lower or higher better? Must know before starting.
+- **Time budget too short** → If eval takes longer than budget, every run crashes.
+- **Agent modifying evaluate.py** → Hard stop. This invalidates all comparisons.
+- **5 consecutive crashes** → Pause the loop. Alert the user. Don't keep burning cycles.
+- **No improvement in 20+ runs** → Suggest changing strategy in program.md or trying a different approach.
+
+---
+
+## Installation
+
+### One-liner (any tool)
+```bash
+git clone https://github.com/alirezarezvani/claude-skills.git
+cp -r claude-skills/engineering/autoresearch-agent ~/.claude/skills/
+```
+
+### Multi-tool install
+```bash
+./scripts/convert.sh --skill autoresearch-agent --tool codex|gemini|cursor|windsurf|openclaw
+```
+
+### OpenClaw
+```bash
+clawhub install cs-autoresearch-agent
+```
+
+---
+
+## Related Skills
+
+- **self-improving-agent** — improves an agent's own memory/rules over time. NOT for structured experiment loops.
+- **senior-ml-engineer** — ML architecture decisions. Complementary — use for initial design, then autoresearch for optimization.
+- **tdd-guide** — test-driven development. Complementary — tests can be the evaluation function.
+- **skill-security-auditor** — audit skills before publishing. NOT for optimization loops.
diff --git a/skills/autoresearch-agent/_meta.json b/skills/autoresearch-agent/_meta.json
new file mode 100644
index 00000000..f1553429
--- /dev/null
+++ b/skills/autoresearch-agent/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "autoresearch-agent",
+ "displayName": "Autoresearch Agent",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773996975073,
+ "commit": "https://github.com/openclaw/skills/commit/8e579a9e1cbf9d56a8ce850bde7a40675a11a73e"
+ },
+ "history": []
+}
diff --git a/skills/autoresearch-agent/agents/experiment-runner.md b/skills/autoresearch-agent/agents/experiment-runner.md
new file mode 100644
index 00000000..120d81eb
--- /dev/null
+++ b/skills/autoresearch-agent/agents/experiment-runner.md
@@ -0,0 +1,87 @@
+# Experiment Runner Agent
+
+You are an autonomous experimenter. Your job is to optimize a target file by a measurable metric, one change at a time.
+
+## Your Role
+
+You are spawned for each iteration of an autoresearch experiment loop. You:
+1. Read the experiment state (config, strategy, results history)
+2. Decide what to try based on accumulated evidence
+3. Make ONE change to the target file
+4. Commit and evaluate
+5. Report the result
+
+## Process
+
+### 1. Read experiment state
+
+```bash
+# Config: what to optimize and how to measure
+cat .autoresearch/{domain}/{name}/config.cfg
+
+# Strategy: what you can/cannot change, current approach
+cat .autoresearch/{domain}/{name}/program.md
+
+# History: every experiment ever run, with outcomes
+cat .autoresearch/{domain}/{name}/results.tsv
+
+# Recent changes: what the code looks like now
+git log --oneline -10
+git diff HEAD~1 --stat # last change if any
+```
+
+### 2. Analyze results history
+
+From results.tsv, identify:
+- **What worked** (status=keep): What do these changes have in common?
+- **What failed** (status=discard): What approaches should you avoid?
+- **What crashed** (status=crash): Are there fragile areas to be careful with?
+- **Trends**: Is the metric plateauing? Accelerating? Oscillating?
+
+### 3. Select strategy based on experiment count
+
+| Run Count | Strategy | Risk Level |
+|-----------|----------|------------|
+| 1-5 | Low-hanging fruit: obvious improvements, simple optimizations | Low |
+| 6-15 | Systematic exploration: vary one parameter at a time | Medium |
+| 16-30 | Structural changes: algorithm swaps, architecture shifts | High |
+| 30+ | Radical experiments: completely different approaches | Very High |
+
+If no improvement in the last 20 runs, it's time to update the Strategy section of program.md and try something fundamentally different.
+
+### 4. Make ONE change
+
+- Edit only the target file (from config.cfg)
+- Change one variable, one approach, one parameter
+- Keep it simple — equal results with simpler code is a win
+- No new dependencies
+
+### 5. Commit and evaluate
+
+```bash
+git add {target}
+git commit -m "experiment: {description}"
+python {skill_path}/scripts/run_experiment.py --experiment {domain}/{name} --single
+```
+
+### 6. Self-improvement
+
+After every 10th experiment, update program.md's Strategy section:
+- Which approaches consistently work? Double down.
+- Which approaches consistently fail? Stop trying.
+- Any new hypotheses based on the data?
+
+## Hard Rules
+
+- **ONE change per experiment.** Multiple changes = you won't know what worked.
+- **NEVER modify the evaluator.** evaluate.py is the ground truth. Modifying it invalidates all comparisons. If you catch yourself doing this, stop immediately.
+- **5 consecutive crashes → stop.** Alert the user. Don't burn cycles on a broken setup.
+- **Simplicity criterion.** A small improvement that adds ugly complexity is NOT worth it. Removing code that gets same results is the best outcome.
+- **No new dependencies.** Only use what's already available.
+
+## Constraints
+
+- Never read or modify files outside the target file and program.md
+- Never push to remote — all work stays local
+- Never skip the evaluation step — every change must be measured
+- Be concise in commit messages — they become the experiment log
diff --git a/skills/autoresearch-agent/evaluators/benchmark_size.py b/skills/autoresearch-agent/evaluators/benchmark_size.py
new file mode 100644
index 00000000..648ac9ca
--- /dev/null
+++ b/skills/autoresearch-agent/evaluators/benchmark_size.py
@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Measure file, bundle, or Docker image size.
+DO NOT MODIFY after experiment starts — this is the fixed evaluator."""
+
+import os
+import subprocess
+import sys
+
+# --- CONFIGURE ONE OF THESE ---
+# Option 1: File size
+TARGET_FILE = "dist/main.js"
+
+# Option 2: Directory size (uncomment to use)
+# TARGET_DIR = "dist/"
+
+# Option 3: Docker image (uncomment to use)
+# DOCKER_IMAGE = "myapp:latest"
+# DOCKER_BUILD_CMD = "docker build -t myapp:latest ."
+
+# Option 4: Build first, then measure (uncomment to use)
+# BUILD_CMD = "npm run build"
+# --- END CONFIG ---
+
+# Build if needed
+if "BUILD_CMD" in dir() or "BUILD_CMD" in globals():
+ result = subprocess.run(BUILD_CMD, shell=True, capture_output=True)
+ if result.returncode != 0:
+ print(f"Build failed: {result.stderr.decode()[:200]}", file=sys.stderr)
+ sys.exit(1)
+
+# Measure
+if "DOCKER_IMAGE" in dir() or "DOCKER_IMAGE" in globals():
+ if "DOCKER_BUILD_CMD" in dir():
+ subprocess.run(DOCKER_BUILD_CMD, shell=True, capture_output=True)
+ result = subprocess.run(
+ f"docker image inspect {DOCKER_IMAGE} --format '{{{{.Size}}}}'",
+ shell=True, capture_output=True, text=True
+ )
+ try:
+ size_bytes = int(result.stdout.strip())
+ except ValueError:
+ print(f"Could not parse size from: {result.stdout[:100]}", file=sys.stderr)
+ sys.exit(1)
+elif "TARGET_DIR" in dir() or "TARGET_DIR" in globals():
+ size_bytes = sum(
+ os.path.getsize(os.path.join(dp, f))
+ for dp, _, fns in os.walk(TARGET_DIR) for f in fns
+ )
+elif os.path.exists(TARGET_FILE):
+ size_bytes = os.path.getsize(TARGET_FILE)
+else:
+ print(f"Target not found: {TARGET_FILE}", file=sys.stderr)
+ sys.exit(1)
+
+size_kb = size_bytes / 1024
+size_mb = size_bytes / (1024 * 1024)
+
+print(f"size_bytes: {size_bytes}")
+print(f"size_kb: {size_kb:.1f}")
+print(f"size_mb: {size_mb:.2f}")
diff --git a/skills/autoresearch-agent/evaluators/benchmark_speed.py b/skills/autoresearch-agent/evaluators/benchmark_speed.py
new file mode 100644
index 00000000..9da6966a
--- /dev/null
+++ b/skills/autoresearch-agent/evaluators/benchmark_speed.py
@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Measure execution speed of a target function or command.
+DO NOT MODIFY after experiment starts — this is the fixed evaluator."""
+
+import statistics
+import subprocess
+import sys
+import time
+
+# --- CONFIGURE THESE ---
+COMMAND = "python src/module.py" # Command to benchmark
+RUNS = 5 # Number of runs
+WARMUP = 1 # Warmup runs (not counted)
+# --- END CONFIG ---
+
+times = []
+
+# Warmup
+for _ in range(WARMUP):
+ subprocess.run(COMMAND, shell=True, capture_output=True, timeout=120)
+
+# Benchmark
+for i in range(RUNS):
+ t0 = time.perf_counter()
+ result = subprocess.run(COMMAND, shell=True, capture_output=True, timeout=120)
+ elapsed = (time.perf_counter() - t0) * 1000 # ms
+
+ if result.returncode != 0:
+ print(f"Run {i+1} failed (exit {result.returncode})", file=sys.stderr)
+ print(f"stderr: {result.stderr.decode()[:200]}", file=sys.stderr)
+ sys.exit(1)
+
+ times.append(elapsed)
+
+p50 = statistics.median(times)
+p95 = sorted(times)[int(len(times) * 0.95)] if len(times) >= 5 else max(times)
+
+print(f"p50_ms: {p50:.2f}")
+print(f"p95_ms: {p95:.2f}")
+print(f"runs: {RUNS}")
diff --git a/skills/autoresearch-agent/evaluators/build_speed.py b/skills/autoresearch-agent/evaluators/build_speed.py
new file mode 100644
index 00000000..71dbaa00
--- /dev/null
+++ b/skills/autoresearch-agent/evaluators/build_speed.py
@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Measure build/compile time.
+DO NOT MODIFY after experiment starts — this is the fixed evaluator."""
+
+import subprocess
+import sys
+import time
+
+# --- CONFIGURE THESE ---
+BUILD_CMD = "npm run build" # or: docker build -t test .
+CLEAN_CMD = "" # optional: npm run clean (run before each build)
+RUNS = 3 # Number of builds to average
+# --- END CONFIG ---
+
+times = []
+
+for i in range(RUNS):
+ # Clean if configured
+ if CLEAN_CMD:
+ subprocess.run(CLEAN_CMD, shell=True, capture_output=True, timeout=60)
+
+ t0 = time.perf_counter()
+ result = subprocess.run(BUILD_CMD, shell=True, capture_output=True, timeout=600)
+ elapsed = time.perf_counter() - t0
+
+ if result.returncode != 0:
+ print(f"Build {i+1} failed (exit {result.returncode})", file=sys.stderr)
+ print(f"stderr: {result.stderr.decode()[:200]}", file=sys.stderr)
+ sys.exit(1)
+
+ times.append(elapsed)
+
+import statistics
+avg = statistics.mean(times)
+median = statistics.median(times)
+
+print(f"build_seconds: {median:.2f}")
+print(f"build_avg: {avg:.2f}")
+print(f"runs: {RUNS}")
diff --git a/skills/autoresearch-agent/evaluators/llm_judge_content.py b/skills/autoresearch-agent/evaluators/llm_judge_content.py
new file mode 100644
index 00000000..79bcd4cb
--- /dev/null
+++ b/skills/autoresearch-agent/evaluators/llm_judge_content.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""LLM judge for content quality (headlines, titles, descriptions).
+Uses the user's existing CLI tool (claude, codex, gemini) for evaluation.
+DO NOT MODIFY after experiment starts — this is the fixed evaluator."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+# --- CONFIGURE THESE ---
+TARGET_FILE = "content/titles.md" # File being optimized
+CLI_TOOL = "claude" # or: codex, gemini
+# --- END CONFIG ---
+
+# The judge prompt is FIXED — the agent cannot change how it's evaluated
+JUDGE_PROMPT = """You are a content quality evaluator. Score the following content strictly.
+
+Criteria (each scored 1-10):
+
+1. CURIOSITY GAP — Does this make you want to click? Is there an information gap
+ that can only be resolved by reading? Generic titles score 1-3. Specific,
+ intriguing titles score 7-10.
+
+2. SPECIFICITY — Are there concrete numbers, tools, or details? "How I improved
+ performance" = 2. "How I reduced API latency from 800ms to 185ms" = 9.
+
+3. EMOTIONAL PULL — Does it trigger curiosity, surprise, fear of missing out,
+ or recognition? Flat titles score 1-3. Emotionally charged score 7-10.
+
+4. SCROLL-STOP POWER — Would this stop someone scrolling through a feed or
+ search results? Would they pause on this headline? Rate honestly.
+
+5. SEO KEYWORD PRESENCE — Are searchable, high-intent terms present naturally?
+ Keyword-stuffed = 3. Natural integration of search terms = 8-10.
+
+Output EXACTLY this format (nothing else):
+curiosity:
+specificity:
+emotional:
+scroll_stop:
+seo:
+ctr_score:
+
+Be harsh. Most content is mediocre (4-6 range). Only exceptional content scores 8+."""
+
+try:
+ content = Path(TARGET_FILE).read_text()
+except FileNotFoundError:
+ print(f"Target file not found: {TARGET_FILE}", file=sys.stderr)
+ sys.exit(1)
+
+full_prompt = f"{JUDGE_PROMPT}\n\n---\n\nContent to evaluate:\n\n{content}"
+
+# Call the user's CLI tool
+result = subprocess.run(
+ [CLI_TOOL, "-p", full_prompt],
+ capture_output=True, text=True, timeout=120
+)
+
+if result.returncode != 0:
+ print(f"LLM judge failed: {result.stderr[:200]}", file=sys.stderr)
+ sys.exit(1)
+
+# Parse output — look for ctr_score line
+output = result.stdout
+for line in output.splitlines():
+ line = line.strip()
+ if line.startswith("ctr_score:"):
+ print(line)
+ elif line.startswith(("curiosity:", "specificity:", "emotional:", "scroll_stop:", "seo:")):
+ print(line)
+
+# Verify ctr_score was found
+if "ctr_score:" not in output:
+ print("Could not parse ctr_score from LLM output", file=sys.stderr)
+ print(f"Raw output: {output[:500]}", file=sys.stderr)
+ sys.exit(1)
diff --git a/skills/autoresearch-agent/evaluators/llm_judge_copy.py b/skills/autoresearch-agent/evaluators/llm_judge_copy.py
new file mode 100644
index 00000000..c4a9565f
--- /dev/null
+++ b/skills/autoresearch-agent/evaluators/llm_judge_copy.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""LLM judge for marketing copy (social posts, ads, emails).
+Uses the user's existing CLI tool for evaluation.
+DO NOT MODIFY after experiment starts — this is the fixed evaluator."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+# --- CONFIGURE THESE ---
+TARGET_FILE = "posts.md" # Copy being optimized
+CLI_TOOL = "claude" # or: codex, gemini
+PLATFORM = "twitter" # twitter, linkedin, instagram, email, ad
+# --- END CONFIG ---
+
+JUDGE_PROMPTS = {
+ "twitter": """Score this Twitter/X post strictly:
+1. HOOK (1-10) — Does the first line stop the scroll?
+2. VALUE (1-10) — Does it provide insight, entertainment, or utility?
+3. ENGAGEMENT (1-10) — Would people reply, retweet, or like?
+4. BREVITY (1-10) — Is every word earning its place? No filler?
+5. CTA (1-10) — Is there a clear next action (even implicit)?""",
+
+ "linkedin": """Score this LinkedIn post strictly:
+1. HOOK (1-10) — Does the first line make you click "see more"?
+2. STORYTELLING (1-10) — Is there a narrative arc or just statements?
+3. CREDIBILITY (1-10) — Does it demonstrate expertise without bragging?
+4. ENGAGEMENT (1-10) — Would professionals comment or share?
+5. CTA (1-10) — Does it invite discussion or action?""",
+
+ "instagram": """Score this Instagram caption strictly:
+1. HOOK (1-10) — Does the first line grab attention?
+2. RELATABILITY (1-10) — Does the audience see themselves in this?
+3. VISUAL MATCH (1-10) — Does the copy complement visual content?
+4. HASHTAG STRATEGY (1-10) — Are hashtags relevant and not spammy?
+5. CTA (1-10) — Does it encourage saves, shares, or comments?""",
+
+ "email": """Score this email subject + preview strictly:
+1. OPEN INCENTIVE (1-10) — Would you open this in a crowded inbox?
+2. SPECIFICITY (1-10) — Is it concrete or vague?
+3. URGENCY (1-10) — Is there a reason to open now vs later?
+4. PERSONALIZATION (1-10) — Does it feel written for someone, not everyone?
+5. PREVIEW SYNC (1-10) — Does the preview text complement the subject?""",
+
+ "ad": """Score this ad copy strictly:
+1. ATTENTION (1-10) — Does it stop someone scrolling past ads?
+2. DESIRE (1-10) — Does it create want for the product/service?
+3. PROOF (1-10) — Is there credibility (numbers, social proof)?
+4. ACTION (1-10) — Is the CTA clear and compelling?
+5. OBJECTION HANDLING (1-10) — Does it preempt "why not"?""",
+}
+
+platform_prompt = JUDGE_PROMPTS.get(PLATFORM, JUDGE_PROMPTS["twitter"])
+
+JUDGE_PROMPT = f"""{platform_prompt}
+
+IMPORTANT: You MUST use criterion_1 through criterion_5 as labels, NOT the criterion names.
+Do NOT output "hook: 7" — output "criterion_1: 7".
+
+Output EXACTLY this format:
+criterion_1:
+criterion_2:
+criterion_3:
+criterion_4:
+criterion_5:
+engagement_score:
+
+Be harsh. Most copy is mediocre (4-6). Only exceptional copy scores 8+."""
+
+try:
+ content = Path(TARGET_FILE).read_text()
+except FileNotFoundError:
+ print(f"Target file not found: {TARGET_FILE}", file=sys.stderr)
+ sys.exit(1)
+
+full_prompt = f"{JUDGE_PROMPT}\n\n---\n\nCopy to evaluate:\n\n{content}"
+
+result = subprocess.run(
+ [CLI_TOOL, "-p", full_prompt],
+ capture_output=True, text=True, timeout=120
+)
+
+if result.returncode != 0:
+ print(f"LLM judge failed: {result.stderr[:200]}", file=sys.stderr)
+ sys.exit(1)
+
+output = result.stdout
+found_scores = False
+for line in output.splitlines():
+ line = line.strip()
+ if line.startswith("engagement_score:") or line.startswith("criterion_"):
+ print(line)
+ found_scores = True
+
+# Fallback: if no criterion_ lines found, try parsing any "word: digit" lines
+if not found_scores:
+ import re
+ fallback_scores = []
+ for line in output.splitlines():
+ line = line.strip()
+ match = re.match(r'^(\w[\w\s]*?):\s*(\d+(?:\.\d+)?)\s*$', line)
+ if match and match.group(1).lower() not in ("engagement_score",):
+ fallback_scores.append(float(match.group(2)))
+ print(f"criterion_{len(fallback_scores)}: {match.group(2)}")
+ if fallback_scores:
+ avg = sum(fallback_scores) / len(fallback_scores)
+ print(f"engagement_score: {avg:.1f}")
+ found_scores = True
+
+if "engagement_score:" not in output and not found_scores:
+ print("Could not parse engagement_score from LLM output", file=sys.stderr)
+ print(f"Raw: {output[:500]}", file=sys.stderr)
+ sys.exit(1)
diff --git a/skills/autoresearch-agent/evaluators/llm_judge_prompt.py b/skills/autoresearch-agent/evaluators/llm_judge_prompt.py
new file mode 100644
index 00000000..8bb7fdac
--- /dev/null
+++ b/skills/autoresearch-agent/evaluators/llm_judge_prompt.py
@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""LLM judge for prompt/instruction quality.
+Uses the user's existing CLI tool for evaluation.
+DO NOT MODIFY after experiment starts — this is the fixed evaluator."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+# --- CONFIGURE THESE ---
+TARGET_FILE = "prompt.md" # Prompt being optimized
+TEST_CASES_FILE = "tests/cases.json" # Test cases: [{"input": "...", "expected": "..."}]
+CLI_TOOL = "claude" # or: codex, gemini
+# --- END CONFIG ---
+
+JUDGE_PROMPT_TEMPLATE = """You are evaluating a system prompt's effectiveness.
+
+SYSTEM PROMPT BEING TESTED:
+{prompt}
+
+TEST INPUT:
+{input}
+
+EXPECTED OUTPUT (reference):
+{expected}
+
+ACTUAL OUTPUT:
+{actual}
+
+Score the actual output on these criteria (each 1-10):
+1. ACCURACY — Does it match the expected output's intent and facts?
+2. COMPLETENESS — Does it cover all required elements?
+3. CLARITY — Is it well-structured and easy to understand?
+4. INSTRUCTION_FOLLOWING — Does it follow the system prompt's guidelines?
+
+Output EXACTLY: quality_score:
+Nothing else."""
+
+try:
+ prompt = Path(TARGET_FILE).read_text()
+except FileNotFoundError:
+ print(f"Target file not found: {TARGET_FILE}", file=sys.stderr)
+ sys.exit(1)
+
+try:
+ test_cases = json.loads(Path(TEST_CASES_FILE).read_text())
+except FileNotFoundError:
+ print(f"Test cases file not found: {TEST_CASES_FILE}", file=sys.stderr)
+ sys.exit(1)
+
+scores = []
+
+for i, case in enumerate(test_cases):
+ # Generate output using the prompt
+ gen_prompt = f"{prompt}\n\n{case['input']}"
+ gen_result = subprocess.run(
+ [CLI_TOOL, "-p", gen_prompt],
+ capture_output=True, text=True, timeout=60
+ )
+ if gen_result.returncode != 0:
+ print(f"Generation failed for case {i+1}", file=sys.stderr)
+ scores.append(0)
+ continue
+
+ actual = gen_result.stdout.strip()
+
+ # Judge the output
+ judge_prompt = JUDGE_PROMPT_TEMPLATE.format(
+ prompt=prompt[:500],
+ input=case["input"],
+ expected=case.get("expected", "N/A"),
+ actual=actual[:500]
+ )
+
+ judge_result = subprocess.run(
+ [CLI_TOOL, "-p", judge_prompt],
+ capture_output=True, text=True, timeout=60
+ )
+
+ if judge_result.returncode != 0:
+ scores.append(0)
+ continue
+
+ # Parse score
+ for line in judge_result.stdout.splitlines():
+ if "quality_score:" in line:
+ try:
+ score = float(line.split(":")[-1].strip())
+ scores.append(score)
+ except ValueError:
+ scores.append(0)
+ break
+ else:
+ scores.append(0)
+
+ print(f" Case {i+1}/{len(test_cases)}: {scores[-1]:.1f}", file=sys.stderr)
+
+if not scores:
+ print("No test cases evaluated", file=sys.stderr)
+ sys.exit(1)
+
+avg = sum(scores) / len(scores)
+quality = avg * 10 # 1-10 scores → 10-100 range
+
+print(f"quality_score: {quality:.2f}")
+print(f"cases_tested: {len(scores)}")
+print(f"avg_per_case: {avg:.2f}")
diff --git a/skills/autoresearch-agent/evaluators/memory_usage.py b/skills/autoresearch-agent/evaluators/memory_usage.py
new file mode 100644
index 00000000..faffb1cf
--- /dev/null
+++ b/skills/autoresearch-agent/evaluators/memory_usage.py
@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Measure peak memory usage of a command.
+DO NOT MODIFY after experiment starts — this is the fixed evaluator."""
+
+import platform
+import subprocess
+import sys
+
+# --- CONFIGURE THESE ---
+COMMAND = "python src/module.py" # Command to measure
+# --- END CONFIG ---
+
+system = platform.system()
+
+if system == "Linux":
+ # Use /usr/bin/time for peak RSS
+ result = subprocess.run(
+ f"/usr/bin/time -v {COMMAND}",
+ shell=True, capture_output=True, text=True, timeout=300
+ )
+ output = result.stderr
+ for line in output.splitlines():
+ if "Maximum resident set size" in line:
+ kb = int(line.split(":")[-1].strip())
+ mb = kb / 1024
+ print(f"peak_mb: {mb:.1f}")
+ print(f"peak_kb: {kb}")
+ sys.exit(0)
+ print("Could not parse memory from /usr/bin/time output", file=sys.stderr)
+ sys.exit(1)
+
+elif system == "Darwin":
+ # macOS: use /usr/bin/time -l
+ result = subprocess.run(
+ f"/usr/bin/time -l {COMMAND}",
+ shell=True, capture_output=True, text=True, timeout=300
+ )
+ output = result.stderr
+ for line in output.splitlines():
+ if "maximum resident set size" in line.lower():
+ # macOS reports in bytes
+ val = int(line.strip().split()[0])
+ kb = val / 1024
+ mb = val / (1024 * 1024)
+ print(f"peak_mb: {mb:.1f}")
+ print(f"peak_kb: {int(kb)}")
+ sys.exit(0)
+ print("Could not parse memory from time output", file=sys.stderr)
+ sys.exit(1)
+
+else:
+ print(f"Unsupported platform: {system}. Use Linux or macOS.", file=sys.stderr)
+ sys.exit(1)
diff --git a/skills/autoresearch-agent/evaluators/test_pass_rate.py b/skills/autoresearch-agent/evaluators/test_pass_rate.py
new file mode 100644
index 00000000..de421bc0
--- /dev/null
+++ b/skills/autoresearch-agent/evaluators/test_pass_rate.py
@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Measure test suite pass rate.
+DO NOT MODIFY after experiment starts — this is the fixed evaluator."""
+
+import re
+import subprocess
+import sys
+
+# --- CONFIGURE THESE ---
+TEST_CMD = "pytest tests/ --tb=no -q" # Test command
+# --- END CONFIG ---
+
+result = subprocess.run(TEST_CMD, shell=True, capture_output=True, text=True, timeout=300)
+output = result.stdout + "\n" + result.stderr
+
+# Try to parse pytest output: "X passed, Y failed, Z errors"
+passed = failed = errors = 0
+
+# pytest short format: "5 passed, 2 failed in 1.23s"
+match = re.search(r"(\d+) passed", output)
+if match:
+ passed = int(match.group(1))
+match = re.search(r"(\d+) failed", output)
+if match:
+ failed = int(match.group(1))
+match = re.search(r"(\d+) error", output)
+if match:
+ errors = int(match.group(1))
+
+total = passed + failed + errors
+if total == 0:
+ # Try unittest format: "Ran X tests"
+ match = re.search(r"Ran (\d+) test", output)
+ if match:
+ total = int(match.group(1))
+ if result.returncode == 0:
+ passed = total
+ else:
+ # Count failures from output
+ fail_match = re.search(r"FAILED \(failures=(\d+)", output)
+ if fail_match:
+ failed = int(fail_match.group(1))
+ passed = total - failed
+
+if total == 0:
+ print("Could not parse test results", file=sys.stderr)
+ print(f"Output: {output[:500]}", file=sys.stderr)
+ sys.exit(1)
+
+rate = passed / total
+
+print(f"pass_rate: {rate:.4f}")
+print(f"passed: {passed}")
+print(f"failed: {failed}")
+print(f"total: {total}")
diff --git a/skills/autoresearch-agent/references/experiment-domains.md b/skills/autoresearch-agent/references/experiment-domains.md
new file mode 100644
index 00000000..1ac50aa5
--- /dev/null
+++ b/skills/autoresearch-agent/references/experiment-domains.md
@@ -0,0 +1,255 @@
+# Experiment Domains Guide
+
+## Domain: Engineering
+
+### Code Speed Optimization
+
+```bash
+python scripts/setup_experiment.py \
+ --domain engineering \
+ --name api-speed \
+ --target src/api/search.py \
+ --eval "python -m pytest tests/bench_search.py --tb=no -q" \
+ --metric p50_ms \
+ --direction lower \
+ --evaluator benchmark_speed
+```
+
+**What the agent optimizes:** Algorithm, data structures, caching, query patterns, I/O.
+**Cost:** Free — just runs benchmarks.
+**Speed:** ~5 min/experiment, ~12/hour, ~100 overnight.
+
+### Bundle Size Reduction
+
+```bash
+python scripts/setup_experiment.py \
+ --domain engineering \
+ --name bundle-size \
+ --target webpack.config.js \
+ --eval "npm run build && python .autoresearch/engineering/bundle-size/evaluate.py" \
+ --metric size_bytes \
+ --direction lower \
+ --evaluator benchmark_size
+```
+
+Edit `evaluate.py` to set `TARGET_FILE = "dist/main.js"` and add `BUILD_CMD = "npm run build"`.
+
+### Test Pass Rate
+
+```bash
+python scripts/setup_experiment.py \
+ --domain engineering \
+ --name fix-flaky-tests \
+ --target src/utils/parser.py \
+ --eval "python .autoresearch/engineering/fix-flaky-tests/evaluate.py" \
+ --metric pass_rate \
+ --direction higher \
+ --evaluator test_pass_rate
+```
+
+### Docker Build Speed
+
+```bash
+python scripts/setup_experiment.py \
+ --domain engineering \
+ --name docker-build \
+ --target Dockerfile \
+ --eval "python .autoresearch/engineering/docker-build/evaluate.py" \
+ --metric build_seconds \
+ --direction lower \
+ --evaluator build_speed
+```
+
+### Memory Optimization
+
+```bash
+python scripts/setup_experiment.py \
+ --domain engineering \
+ --name memory-usage \
+ --target src/processor.py \
+ --eval "python .autoresearch/engineering/memory-usage/evaluate.py" \
+ --metric peak_mb \
+ --direction lower \
+ --evaluator memory_usage
+```
+
+### ML Training (Karpathy-style)
+
+Requires NVIDIA GPU. See [autoresearch](https://github.com/karpathy/autoresearch).
+
+```bash
+python scripts/setup_experiment.py \
+ --domain engineering \
+ --name ml-training \
+ --target train.py \
+ --eval "uv run train.py" \
+ --metric val_bpb \
+ --direction lower \
+ --time-budget 5
+```
+
+---
+
+## Domain: Marketing
+
+### Medium Article Headlines
+
+```bash
+python scripts/setup_experiment.py \
+ --domain marketing \
+ --name medium-ctr \
+ --target content/titles.md \
+ --eval "python .autoresearch/marketing/medium-ctr/evaluate.py" \
+ --metric ctr_score \
+ --direction higher \
+ --evaluator llm_judge_content
+```
+
+Edit `evaluate.py`: set `TARGET_FILE = "content/titles.md"` and `CLI_TOOL = "claude"`.
+
+**What the agent optimizes:** Title phrasing, curiosity gaps, specificity, emotional triggers.
+**Cost:** Uses your CLI subscription (Claude Max = unlimited).
+**Speed:** ~2 min/experiment, ~30/hour.
+
+### Social Media Copy
+
+```bash
+python scripts/setup_experiment.py \
+ --domain marketing \
+ --name twitter-engagement \
+ --target social/tweets.md \
+ --eval "python .autoresearch/marketing/twitter-engagement/evaluate.py" \
+ --metric engagement_score \
+ --direction higher \
+ --evaluator llm_judge_copy
+```
+
+Edit `evaluate.py`: set `PLATFORM = "twitter"` (or linkedin, instagram).
+
+### Email Subject Lines
+
+```bash
+python scripts/setup_experiment.py \
+ --domain marketing \
+ --name email-open-rate \
+ --target emails/subjects.md \
+ --eval "python .autoresearch/marketing/email-open-rate/evaluate.py" \
+ --metric engagement_score \
+ --direction higher \
+ --evaluator llm_judge_copy
+```
+
+Edit `evaluate.py`: set `PLATFORM = "email"`.
+
+### Ad Copy
+
+```bash
+python scripts/setup_experiment.py \
+ --domain marketing \
+ --name ad-copy-q2 \
+ --target ads/google-search.md \
+ --eval "python .autoresearch/marketing/ad-copy-q2/evaluate.py" \
+ --metric engagement_score \
+ --direction higher \
+ --evaluator llm_judge_copy
+```
+
+Edit `evaluate.py`: set `PLATFORM = "ad"`.
+
+---
+
+## Domain: Content
+
+### Article Structure & Readability
+
+```bash
+python scripts/setup_experiment.py \
+ --domain content \
+ --name article-structure \
+ --target drafts/my-article.md \
+ --eval "python .autoresearch/content/article-structure/evaluate.py" \
+ --metric ctr_score \
+ --direction higher \
+ --evaluator llm_judge_content
+```
+
+### SEO Descriptions
+
+```bash
+python scripts/setup_experiment.py \
+ --domain content \
+ --name seo-meta \
+ --target seo/descriptions.md \
+ --eval "python .autoresearch/content/seo-meta/evaluate.py" \
+ --metric ctr_score \
+ --direction higher \
+ --evaluator llm_judge_content
+```
+
+---
+
+## Domain: Prompts
+
+### System Prompt Optimization
+
+```bash
+python scripts/setup_experiment.py \
+ --domain prompts \
+ --name support-bot \
+ --target prompts/support-system.md \
+ --eval "python .autoresearch/prompts/support-bot/evaluate.py" \
+ --metric quality_score \
+ --direction higher \
+ --evaluator llm_judge_prompt
+```
+
+Requires `tests/cases.json` with test inputs and expected outputs:
+
+```json
+[
+ {
+ "input": "I can't log in to my account",
+ "expected": "Ask for email, check account status, offer password reset"
+ },
+ {
+ "input": "How do I cancel my subscription?",
+ "expected": "Empathetic response, explain cancellation steps, offer retention"
+ }
+]
+```
+
+### Agent Skill Optimization
+
+```bash
+python scripts/setup_experiment.py \
+ --domain prompts \
+ --name skill-improvement \
+ --target SKILL.md \
+ --eval "python .autoresearch/prompts/skill-improvement/evaluate.py" \
+ --metric quality_score \
+ --direction higher \
+ --evaluator llm_judge_prompt
+```
+
+---
+
+## Choosing Your Domain
+
+| I want to... | Domain | Evaluator | Cost |
+|-------------|--------|-----------|------|
+| Speed up my code | engineering | benchmark_speed | Free |
+| Shrink my bundle | engineering | benchmark_size | Free |
+| Fix flaky tests | engineering | test_pass_rate | Free |
+| Speed up Docker builds | engineering | build_speed | Free |
+| Reduce memory usage | engineering | memory_usage | Free |
+| Train ML models | engineering | (custom) | Free + GPU |
+| Write better headlines | marketing | llm_judge_content | Subscription |
+| Improve social posts | marketing | llm_judge_copy | Subscription |
+| Optimize email subjects | marketing | llm_judge_copy | Subscription |
+| Improve ad copy | marketing | llm_judge_copy | Subscription |
+| Optimize article structure | content | llm_judge_content | Subscription |
+| Improve SEO descriptions | content | llm_judge_content | Subscription |
+| Optimize system prompts | prompts | llm_judge_prompt | Subscription |
+| Improve agent skills | prompts | llm_judge_prompt | Subscription |
+
+**First time?** Start with an engineering experiment (free, fast, measurable). Once comfortable, try content/marketing with LLM judges.
diff --git a/skills/autoresearch-agent/references/program-template.md b/skills/autoresearch-agent/references/program-template.md
new file mode 100644
index 00000000..90cfe716
--- /dev/null
+++ b/skills/autoresearch-agent/references/program-template.md
@@ -0,0 +1,170 @@
+# program.md Templates
+
+Copy the template for your domain and paste into your project root as `program.md`.
+
+---
+
+## ML Training (Karpathy-style)
+
+```markdown
+# autoresearch — ML Training
+
+## Goal
+Minimize val_bpb on the validation set. Lower is better.
+
+## What You Can Change (train.py only)
+- Model architecture (depth, width, attention heads, FFN ratio)
+- Optimizer (learning rate, warmup, scheduler, weight decay)
+- Training loop (batch size, gradient accumulation, clipping)
+- Regularization (dropout, weight tying, etc.)
+- Any self-contained improvement that doesn't require new packages
+
+## What You Cannot Change
+- prepare.py (fixed — contains evaluation harness)
+- Dependencies (pyproject.toml is locked)
+- Time budget (always 5 minutes, wall clock)
+- Evaluation metric (val_bpb is the ground truth)
+
+## Strategy
+1. First run: establish baseline. Do not change anything.
+2. Explore learning rate range (try 2x and 0.5x current)
+3. Try depth changes (±2 layers)
+4. Try optimizer changes (Muon vs. AdamW variants)
+5. If things improve, double down. If stuck, try something radical.
+
+## Simplicity Rule
+A small improvement with ugly code is NOT worth it.
+Equal performance with simpler code IS worth it.
+Removing code that gets same results is the best outcome.
+
+## Stop When
+val_bpb < 0.95 OR after 100 experiments, whichever comes first.
+```
+
+---
+
+## Prompt Engineering
+
+```markdown
+# autoresearch — Prompt Optimization
+
+## Goal
+Maximize eval_score on the test suite. Higher is better (0-100).
+
+## What You Can Change (prompt.md only)
+- System prompt instructions
+- Examples and few-shot demonstrations
+- Output format specifications
+- Chain-of-thought instructions
+- Persona and tone
+- Task decomposition strategies
+
+## What You Cannot Change
+- evaluate.py (fixed evaluation harness)
+- Test cases in tests/ (ground truth)
+- Model being evaluated (specified in evaluate.py)
+- Scoring criteria (defined in evaluate.py)
+
+## Strategy
+1. First run: baseline with current prompt (or empty)
+2. Add clear role/persona definition
+3. Add output format specification
+4. Add chain-of-thought instruction
+5. Add 2-3 diverse examples
+6. Refine based on failure modes from run.log
+
+## Evaluation
+- evaluate.py runs the prompt against 20 test cases
+- Each test case is scored 1-10 by your CLI tool (Claude, Codex, or Gemini)
+- quality_score = average * 10 (maps to 10-100)
+- Run log shows which test cases failed
+
+## Stop When
+eval_score >= 85 OR after 50 experiments.
+```
+
+---
+
+## Code Performance
+
+```markdown
+# autoresearch — Performance Optimization
+
+## Goal
+Minimize p50_ms (median latency). Lower is better.
+
+## What You Can Change (src/module.py only)
+- Algorithm implementation
+- Data structures (use faster alternatives)
+- Caching and memoization
+- Vectorization (NumPy, etc.)
+- Loop optimization
+- I/O patterns
+- Memory allocation patterns
+
+## What You Cannot Change
+- benchmark.py (fixed benchmark harness)
+- Public API (function signatures must stay the same)
+- External dependencies (add nothing new)
+- Correctness tests (tests/ must still pass)
+
+## Constraints
+- Correctness is non-negotiable. benchmark.py runs tests first.
+- If tests fail → immediate crash status, no metric recorded.
+- Memory usage: p99 < 2x baseline acceptable, hard limit at 4x.
+
+## Strategy
+1. Baseline: profile first, don't guess
+2. Check if there's any O(n²) → O(n log n) opportunity
+3. Try caching repeated computations
+4. Try NumPy vectorization for loops
+5. Try algorithm-level changes last (higher risk)
+
+## Stop When
+p50_ms < 50ms OR improvement plateaus for 10 consecutive experiments.
+```
+
+---
+
+## Agent Skill Optimization
+
+```markdown
+# autoresearch — Skill Optimization
+
+## Goal
+Maximize pass_rate on the task evaluation suite. Higher is better (0-1).
+
+## What You Can Change (SKILL.md only)
+- Skill description and trigger phrases
+- Core workflow steps and ordering
+- Decision frameworks and rules
+- Output format specifications
+- Example inputs/outputs
+- Related skills disambiguation
+- Proactive trigger conditions
+
+## What You Cannot Change
+- your custom evaluate.py (see Custom Evaluators in SKILL.md)
+- Test tasks in tests/ (ground truth benchmark)
+- Skill name (used for routing)
+- License or metadata
+
+## Evaluation
+- evaluate.py runs SKILL.md against 15 standardized tasks
+- Your CLI tool scores each task: 0 (fail), 0.5 (partial), 1 (pass)
+- pass_rate = sum(scores) / 15
+
+## Strategy
+1. Baseline: run as-is
+2. Improve trigger description (better routing = more passes)
+3. Sharpen the core workflow (clearer = better execution)
+4. Add missing edge cases to the rules section
+5. Improve disambiguation (reduce false-positive routing)
+
+## Simplicity Rule
+A shorter SKILL.md that achieves the same score is better.
+Aim for 200-400 lines total.
+
+## Stop When
+pass_rate >= 0.90 OR after 30 experiments.
+```
diff --git a/skills/autoresearch-agent/scripts/log_results.py b/skills/autoresearch-agent/scripts/log_results.py
new file mode 100644
index 00000000..18202723
--- /dev/null
+++ b/skills/autoresearch-agent/scripts/log_results.py
@@ -0,0 +1,393 @@
+#!/usr/bin/env python3
+"""
+autoresearch-agent: Results Viewer
+
+View experiment results in multiple formats: terminal, CSV, Markdown.
+Supports single experiment, domain, or cross-experiment dashboard.
+
+Usage:
+ python scripts/log_results.py --experiment engineering/api-speed
+ python scripts/log_results.py --domain engineering
+ python scripts/log_results.py --dashboard
+ python scripts/log_results.py --experiment engineering/api-speed --format csv --output results.csv
+ python scripts/log_results.py --experiment engineering/api-speed --format markdown --output results.md
+ python scripts/log_results.py --dashboard --format markdown --output dashboard.md
+"""
+
+import argparse
+import csv
+import io
+import sys
+import time
+from pathlib import Path
+
+
+def find_autoresearch_root():
+ """Find .autoresearch/ in project or user home."""
+ project_root = Path(".").resolve() / ".autoresearch"
+ if project_root.exists():
+ return project_root
+ user_root = Path.home() / ".autoresearch"
+ if user_root.exists():
+ return user_root
+ return None
+
+
+def load_config(experiment_dir):
+ """Load config.cfg."""
+ cfg_file = experiment_dir / "config.cfg"
+ config = {}
+ if cfg_file.exists():
+ for line in cfg_file.read_text().splitlines():
+ if ":" in line:
+ k, v = line.split(":", 1)
+ config[k.strip()] = v.strip()
+ return config
+
+
+def load_results(experiment_dir):
+ """Load results.tsv into list of dicts."""
+ tsv = experiment_dir / "results.tsv"
+ if not tsv.exists():
+ return []
+ results = []
+ for line in tsv.read_text().splitlines()[1:]:
+ parts = line.split("\t")
+ if len(parts) >= 4:
+ try:
+ metric = float(parts[1]) if parts[1] != "N/A" else None
+ except ValueError:
+ metric = None
+ results.append({
+ "commit": parts[0],
+ "metric": metric,
+ "status": parts[2],
+ "description": parts[3],
+ })
+ return results
+
+
+def compute_stats(results, direction):
+ """Compute statistics from results."""
+ keeps = [r for r in results if r["status"] == "keep"]
+ discards = [r for r in results if r["status"] == "discard"]
+ crashes = [r for r in results if r["status"] == "crash"]
+
+ valid_keeps = [r for r in keeps if r["metric"] is not None]
+ baseline = valid_keeps[0]["metric"] if valid_keeps else None
+ if valid_keeps:
+ best = min(r["metric"] for r in valid_keeps) if direction == "lower" else max(r["metric"] for r in valid_keeps)
+ else:
+ best = None
+
+ pct_change = None
+ if baseline is not None and best is not None and baseline != 0:
+ if direction == "lower":
+ pct_change = (baseline - best) / baseline * 100
+ else:
+ pct_change = (best - baseline) / baseline * 100
+
+ return {
+ "total": len(results),
+ "keeps": len(keeps),
+ "discards": len(discards),
+ "crashes": len(crashes),
+ "baseline": baseline,
+ "best": best,
+ "pct_change": pct_change,
+ }
+
+
+# --- Terminal Output ---
+
+def print_experiment(experiment_dir, experiment_path):
+ """Print single experiment results to terminal."""
+ config = load_config(experiment_dir)
+ results = load_results(experiment_dir)
+ direction = config.get("metric_direction", "lower")
+ metric_name = config.get("metric", "metric")
+
+ if not results:
+ print(f"No results for {experiment_path}")
+ return
+
+ stats = compute_stats(results, direction)
+
+ print(f"\n{'─' * 65}")
+ print(f" {experiment_path}")
+ print(f" Target: {config.get('target', '?')} | Metric: {metric_name} ({direction})")
+ print(f"{'─' * 65}")
+ print(f" Total: {stats['total']} | Keep: {stats['keeps']} | Discard: {stats['discards']} | Crash: {stats['crashes']}")
+
+ if stats["baseline"] is not None and stats["best"] is not None:
+ pct = f" ({stats['pct_change']:+.1f}%)" if stats["pct_change"] is not None else ""
+ print(f" Baseline: {stats['baseline']:.6f} -> Best: {stats['best']:.6f}{pct}")
+
+ print(f"\n {'COMMIT':<10} {'METRIC':>12} {'STATUS':<10} DESCRIPTION")
+ print(f" {'─' * 60}")
+ for r in results:
+ m = f"{r['metric']:.6f}" if r["metric"] is not None else "N/A "
+ icon = {"keep": "+", "discard": "-", "crash": "!"}.get(r["status"], "?")
+ print(f" {r['commit']:<10} {m:>12} {icon} {r['status']:<7} {r['description'][:35]}")
+ print()
+
+
+def print_dashboard(root):
+ """Print cross-experiment dashboard."""
+ experiments = []
+ for domain_dir in sorted(root.iterdir()):
+ if not domain_dir.is_dir() or domain_dir.name.startswith("."):
+ continue
+ for exp_dir in sorted(domain_dir.iterdir()):
+ if not exp_dir.is_dir() or not (exp_dir / "config.cfg").exists():
+ continue
+ config = load_config(exp_dir)
+ results = load_results(exp_dir)
+ direction = config.get("metric_direction", "lower")
+ stats = compute_stats(results, direction)
+
+ best_str = f"{stats['best']:.4f}" if stats["best"] is not None else "—"
+ pct_str = f"{stats['pct_change']:+.1f}%" if stats["pct_change"] is not None else "—"
+
+ # Determine status
+ status = "idle"
+ if stats["total"] > 0:
+ tsv = exp_dir / "results.tsv"
+ if tsv.exists():
+ age_hours = (time.time() - tsv.stat().st_mtime) / 3600
+ status = "active" if age_hours < 1 else "paused" if age_hours < 24 else "done"
+
+ experiments.append({
+ "domain": domain_dir.name,
+ "name": exp_dir.name,
+ "runs": stats["total"],
+ "kept": stats["keeps"],
+ "best": best_str,
+ "change": pct_str,
+ "status": status,
+ "metric": config.get("metric", "?"),
+ })
+
+ if not experiments:
+ print("No experiments found.")
+ return experiments
+
+ print(f"\n{'─' * 90}")
+ print(f" autoresearch — Dashboard")
+ print(f"{'─' * 90}")
+ print(f" {'DOMAIN':<15} {'EXPERIMENT':<20} {'RUNS':>5} {'KEPT':>5} {'BEST':>12} {'CHANGE':>10} {'STATUS':<8}")
+ print(f" {'─' * 85}")
+ for e in experiments:
+ print(f" {e['domain']:<15} {e['name']:<20} {e['runs']:>5} {e['kept']:>5} {e['best']:>12} {e['change']:>10} {e['status']:<8}")
+ print()
+ return experiments
+
+
+# --- CSV Export ---
+
+def export_experiment_csv(experiment_dir, experiment_path):
+ """Export single experiment as CSV string."""
+ config = load_config(experiment_dir)
+ results = load_results(experiment_dir)
+ direction = config.get("metric_direction", "lower")
+ stats = compute_stats(results, direction)
+
+ buf = io.StringIO()
+ writer = csv.writer(buf)
+
+ # Header with metadata
+ writer.writerow(["# Experiment", experiment_path])
+ writer.writerow(["# Target", config.get("target", "")])
+ writer.writerow(["# Metric", f"{config.get('metric', '')} ({direction} is better)"])
+ if stats["baseline"] is not None:
+ writer.writerow(["# Baseline", f"{stats['baseline']:.6f}"])
+ if stats["best"] is not None:
+ pct = f" ({stats['pct_change']:+.1f}%)" if stats["pct_change"] is not None else ""
+ writer.writerow(["# Best", f"{stats['best']:.6f}{pct}"])
+ writer.writerow(["# Total", stats["total"]])
+ writer.writerow(["# Keep/Discard/Crash", f"{stats['keeps']}/{stats['discards']}/{stats['crashes']}"])
+ writer.writerow([])
+
+ writer.writerow(["Commit", "Metric", "Status", "Description"])
+ for r in results:
+ m = f"{r['metric']:.6f}" if r["metric"] is not None else "N/A"
+ writer.writerow([r["commit"], m, r["status"], r["description"]])
+
+ return buf.getvalue()
+
+
+def export_dashboard_csv(root, domain_filter=None):
+ """Export dashboard as CSV string."""
+ experiments = []
+ for domain_dir in sorted(root.iterdir()):
+ if not domain_dir.is_dir() or domain_dir.name.startswith("."):
+ continue
+ if domain_filter and domain_dir.name != domain_filter:
+ continue
+ for exp_dir in sorted(domain_dir.iterdir()):
+ if not exp_dir.is_dir() or not (exp_dir / "config.cfg").exists():
+ continue
+ config = load_config(exp_dir)
+ results = load_results(exp_dir)
+ direction = config.get("metric_direction", "lower")
+ stats = compute_stats(results, direction)
+ best_str = f"{stats['best']:.6f}" if stats["best"] is not None else ""
+ pct_str = f"{stats['pct_change']:+.1f}%" if stats["pct_change"] is not None else ""
+ experiments.append([
+ domain_dir.name, exp_dir.name, config.get("metric", ""),
+ stats["total"], stats["keeps"], stats["discards"], stats["crashes"],
+ best_str, pct_str
+ ])
+
+ buf = io.StringIO()
+ writer = csv.writer(buf)
+ writer.writerow(["Domain", "Experiment", "Metric", "Runs", "Kept", "Discarded", "Crashed", "Best", "Change"])
+ for e in experiments:
+ writer.writerow(e)
+ return buf.getvalue()
+
+
+# --- Markdown Export ---
+
+def export_experiment_markdown(experiment_dir, experiment_path):
+ """Export single experiment as Markdown string."""
+ config = load_config(experiment_dir)
+ results = load_results(experiment_dir)
+ direction = config.get("metric_direction", "lower")
+ metric_name = config.get("metric", "metric")
+ stats = compute_stats(results, direction)
+
+ lines = []
+ lines.append(f"# Autoresearch: {experiment_path}\n")
+ lines.append(f"**Target:** `{config.get('target', '?')}` ")
+ lines.append(f"**Metric:** `{metric_name}` ({direction} is better) ")
+ lines.append(f"**Experiments:** {stats['total']} total — {stats['keeps']} kept, {stats['discards']} discarded, {stats['crashes']} crashed\n")
+
+ if stats["baseline"] is not None and stats["best"] is not None:
+ pct = f" ({stats['pct_change']:+.1f}%)" if stats["pct_change"] is not None else ""
+ lines.append(f"**Progress:** `{stats['baseline']:.6f}` → `{stats['best']:.6f}`{pct}\n")
+
+ lines.append(f"| Commit | Metric | Status | Description |")
+ lines.append(f"|--------|--------|--------|-------------|")
+ for r in results:
+ m = f"`{r['metric']:.6f}`" if r["metric"] is not None else "N/A"
+ lines.append(f"| `{r['commit']}` | {m} | {r['status']} | {r['description']} |")
+ lines.append("")
+
+ return "\n".join(lines)
+
+
+def export_dashboard_markdown(root, domain_filter=None):
+ """Export dashboard as Markdown string."""
+ lines = []
+ lines.append("# Autoresearch Dashboard\n")
+ lines.append("| Domain | Experiment | Metric | Runs | Kept | Best | Change | Status |")
+ lines.append("|--------|-----------|--------|------|------|------|--------|--------|")
+
+ for domain_dir in sorted(root.iterdir()):
+ if not domain_dir.is_dir() or domain_dir.name.startswith("."):
+ continue
+ if domain_filter and domain_dir.name != domain_filter:
+ continue
+ for exp_dir in sorted(domain_dir.iterdir()):
+ if not exp_dir.is_dir() or not (exp_dir / "config.cfg").exists():
+ continue
+ config = load_config(exp_dir)
+ results = load_results(exp_dir)
+ direction = config.get("metric_direction", "lower")
+ stats = compute_stats(results, direction)
+ best = f"`{stats['best']:.4f}`" if stats["best"] is not None else "—"
+ pct = f"{stats['pct_change']:+.1f}%" if stats["pct_change"] is not None else "—"
+
+ tsv = exp_dir / "results.tsv"
+ status = "idle"
+ if tsv.exists() and stats["total"] > 0:
+ age_h = (time.time() - tsv.stat().st_mtime) / 3600
+ status = "active" if age_h < 1 else "paused" if age_h < 24 else "done"
+
+ lines.append(f"| {domain_dir.name} | {exp_dir.name} | {config.get('metric', '?')} | {stats['total']} | {stats['keeps']} | {best} | {pct} | {status} |")
+
+ lines.append("")
+ return "\n".join(lines)
+
+
+# --- Main ---
+
+def main():
+ parser = argparse.ArgumentParser(description="autoresearch-agent results viewer")
+ parser.add_argument("--experiment", help="Show one experiment: domain/name")
+ parser.add_argument("--domain", help="Show all experiments in a domain")
+ parser.add_argument("--dashboard", action="store_true", help="Cross-experiment dashboard")
+ parser.add_argument("--format", choices=["terminal", "csv", "markdown"], default="terminal",
+ help="Output format (default: terminal)")
+ parser.add_argument("--output", "-o", help="Write to file instead of stdout")
+ parser.add_argument("--all", action="store_true", help="Show all experiments (alias for --dashboard)")
+ args = parser.parse_args()
+
+ root = find_autoresearch_root()
+ if root is None:
+ print("No .autoresearch/ found. Run setup_experiment.py first.")
+ sys.exit(1)
+
+ output_text = None
+
+ # Single experiment
+ if args.experiment:
+ experiment_dir = root / args.experiment
+ if not experiment_dir.exists():
+ print(f"Experiment not found: {args.experiment}")
+ sys.exit(1)
+
+ if args.format == "csv":
+ output_text = export_experiment_csv(experiment_dir, args.experiment)
+ elif args.format == "markdown":
+ output_text = export_experiment_markdown(experiment_dir, args.experiment)
+ else:
+ print_experiment(experiment_dir, args.experiment)
+ return
+
+ # Domain
+ elif args.domain:
+ domain_dir = root / args.domain
+ if not domain_dir.exists():
+ print(f"Domain not found: {args.domain}")
+ sys.exit(1)
+ for exp_dir in sorted(domain_dir.iterdir()):
+ if exp_dir.is_dir() and (exp_dir / "config.cfg").exists():
+ if args.format == "terminal":
+ print_experiment(exp_dir, f"{args.domain}/{exp_dir.name}")
+ # For CSV/MD, fall through to dashboard with domain filter
+ if args.format != "terminal":
+ # Use dashboard export filtered to domain
+ output_text = export_dashboard_csv(root, domain_filter=args.domain) if args.format == "csv" else export_dashboard_markdown(root, domain_filter=args.domain)
+ else:
+ return
+
+ # Dashboard
+ elif args.dashboard or args.all:
+ if args.format == "csv":
+ output_text = export_dashboard_csv(root)
+ elif args.format == "markdown":
+ output_text = export_dashboard_markdown(root)
+ else:
+ print_dashboard(root)
+ return
+
+ else:
+ # Default: dashboard
+ if args.format == "terminal":
+ print_dashboard(root)
+ return
+ output_text = export_dashboard_csv(root) if args.format == "csv" else export_dashboard_markdown(root)
+
+ # Write output
+ if output_text:
+ if args.output:
+ Path(args.output).write_text(output_text)
+ print(f"Written to {args.output}")
+ else:
+ print(output_text)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/autoresearch-agent/scripts/run_experiment.py b/skills/autoresearch-agent/scripts/run_experiment.py
new file mode 100644
index 00000000..dad29be4
--- /dev/null
+++ b/skills/autoresearch-agent/scripts/run_experiment.py
@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""
+autoresearch-agent: Experiment Runner
+
+Executes a single experiment iteration. The AI agent is the loop —
+it calls this script repeatedly. The script handles evaluation,
+metric parsing, keep/discard decisions, and git rollback on failure.
+
+Usage:
+ python scripts/run_experiment.py --experiment engineering/api-speed --single
+ python scripts/run_experiment.py --experiment engineering/api-speed --dry-run
+ python scripts/run_experiment.py --experiment engineering/api-speed --single --description "added caching"
+"""
+
+import argparse
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+
+def find_autoresearch_root():
+ """Find .autoresearch/ in project or user home."""
+ project_root = Path(".").resolve() / ".autoresearch"
+ if project_root.exists():
+ return project_root
+ user_root = Path.home() / ".autoresearch"
+ if user_root.exists():
+ return user_root
+ return None
+
+
+def load_config(experiment_dir):
+ """Load config.cfg from experiment directory."""
+ cfg_file = experiment_dir / "config.cfg"
+ if not cfg_file.exists():
+ print(f" Error: no config.cfg in {experiment_dir}")
+ sys.exit(1)
+ config = {}
+ for line in cfg_file.read_text().splitlines():
+ if ":" in line:
+ k, v = line.split(":", 1)
+ config[k.strip()] = v.strip()
+ return config
+
+
+def run_git(args, cwd=None, timeout=30):
+ """Run a git command safely (no shell injection). Returns (returncode, stdout, stderr)."""
+ result = subprocess.run(
+ ["git"] + args,
+ capture_output=True, text=True,
+ cwd=cwd, timeout=timeout
+ )
+ return result.returncode, result.stdout.strip(), result.stderr.strip()
+
+
+def get_current_commit(path):
+ """Get short hash of current HEAD."""
+ _, commit, _ = run_git(["rev-parse", "--short", "HEAD"], cwd=path)
+ return commit
+
+
+def get_best_metric(experiment_dir, direction):
+ """Read the best metric from results.tsv."""
+ tsv = experiment_dir / "results.tsv"
+ if not tsv.exists():
+ return None
+ lines = [l for l in tsv.read_text().splitlines()[1:] if "\tkeep\t" in l]
+ if not lines:
+ return None
+ metrics = []
+ for line in lines:
+ parts = line.split("\t")
+ try:
+ if parts[1] != "N/A":
+ metrics.append(float(parts[1]))
+ except (ValueError, IndexError):
+ continue
+ if not metrics:
+ return None
+ return min(metrics) if direction == "lower" else max(metrics)
+
+
+def run_evaluation(project_root, eval_cmd, time_budget_minutes, log_file):
+ """Run evaluation with time limit. Output goes to log_file.
+
+ Note: shell=True is intentional here — eval_cmd is user-provided and
+ may contain pipes, redirects, or chained commands.
+ """
+ hard_limit = time_budget_minutes * 60 * 2.5
+ t0 = time.time()
+ try:
+ with open(log_file, "w") as lf:
+ result = subprocess.run(
+ eval_cmd, shell=True,
+ stdout=lf, stderr=subprocess.STDOUT,
+ cwd=str(project_root),
+ timeout=hard_limit
+ )
+ elapsed = time.time() - t0
+ return result.returncode, elapsed
+ except subprocess.TimeoutExpired:
+ elapsed = time.time() - t0
+ return -1, elapsed
+
+
+def extract_metric(log_file, metric_grep):
+ """Extract metric value from log file."""
+ log_path = Path(log_file)
+ if not log_path.exists():
+ return None
+ for line in reversed(log_path.read_text().splitlines()):
+ stripped = line.strip()
+ if stripped.startswith(metric_grep.lstrip("^")):
+ try:
+ return float(stripped.split(":")[-1].strip())
+ except ValueError:
+ continue
+ return None
+
+
+def is_improvement(new_val, old_val, direction):
+ """Check if new result is better than old."""
+ if old_val is None:
+ return True
+ if direction == "lower":
+ return new_val < old_val
+ return new_val > old_val
+
+
+def log_result(experiment_dir, commit, metric_val, status, description):
+ """Append result to results.tsv."""
+ tsv = experiment_dir / "results.tsv"
+ metric_str = f"{metric_val:.6f}" if metric_val is not None else "N/A"
+ with open(tsv, "a") as f:
+ f.write(f"{commit}\t{metric_str}\t{status}\t{description}\n")
+
+
+def get_experiment_count(experiment_dir):
+ """Count experiments run so far."""
+ tsv = experiment_dir / "results.tsv"
+ if not tsv.exists():
+ return 0
+ return max(0, len(tsv.read_text().splitlines()) - 1)
+
+
+def get_description_from_diff(project_root):
+ """Auto-generate a description from git diff --stat HEAD~1."""
+ code, diff_stat, _ = run_git(["diff", "--stat", "HEAD~1"], cwd=str(project_root))
+ if code == 0 and diff_stat:
+ return diff_stat.split("\n")[0][:50]
+ return "experiment"
+
+
+def read_last_lines(filepath, n=5):
+ """Read last n lines of a file (replaces tail shell command)."""
+ path = Path(filepath)
+ if not path.exists():
+ return ""
+ lines = path.read_text().splitlines()
+ return "\n".join(lines[-n:])
+
+
+def run_single(project_root, experiment_dir, config, exp_num, dry_run=False, description=None):
+ """Run one experiment iteration."""
+ direction = config.get("metric_direction", "lower")
+ metric_grep = config.get("metric_grep", "^metric:")
+ eval_cmd = config.get("evaluate_cmd", "python evaluate.py")
+ time_budget = int(config.get("time_budget_minutes", 5))
+ metric_name = config.get("metric", "metric")
+ log_file = str(experiment_dir / "run.log")
+
+ best = get_best_metric(experiment_dir, direction)
+ ts = datetime.now().strftime("%H:%M:%S")
+
+ print(f"\n[{ts}] Experiment #{exp_num}")
+ print(f" Best {metric_name}: {best}")
+
+ if dry_run:
+ print(" [DRY RUN] Would run evaluation and check metric")
+ return "dry_run"
+
+ # Auto-generate description if not provided
+ if not description:
+ description = get_description_from_diff(str(project_root))
+
+ # Run evaluation
+ print(f" Running: {eval_cmd} (budget: {time_budget}m)")
+ ret_code, elapsed = run_evaluation(project_root, eval_cmd, time_budget, log_file)
+
+ commit = get_current_commit(str(project_root))
+
+ # Timeout
+ if ret_code == -1:
+ print(f" TIMEOUT after {elapsed:.0f}s — discarding")
+ run_git(["checkout", "--", "."], cwd=str(project_root))
+ run_git(["reset", "--hard", "HEAD~1"], cwd=str(project_root))
+ log_result(experiment_dir, commit, None, "crash", f"timeout_{elapsed:.0f}s")
+ return "crash"
+
+ # Crash
+ if ret_code != 0:
+ tail = read_last_lines(log_file, 5)
+ print(f" CRASH (exit {ret_code}) after {elapsed:.0f}s")
+ print(f" Last output: {tail[:200]}")
+ run_git(["reset", "--hard", "HEAD~1"], cwd=str(project_root))
+ log_result(experiment_dir, commit, None, "crash", f"exit_{ret_code}")
+ return "crash"
+
+ # Extract metric
+ metric_val = extract_metric(log_file, metric_grep)
+ if metric_val is None:
+ print(f" Could not parse {metric_name} from run.log")
+ run_git(["reset", "--hard", "HEAD~1"], cwd=str(project_root))
+ log_result(experiment_dir, commit, None, "crash", "metric_parse_failed")
+ return "crash"
+
+ delta = ""
+ if best is not None:
+ diff = metric_val - best
+ delta = f" (delta {diff:+.4f})"
+
+ print(f" {metric_name}: {metric_val:.6f}{delta} in {elapsed:.0f}s")
+
+ # Keep or discard
+ if is_improvement(metric_val, best, direction):
+ print(f" KEEP — improvement")
+ log_result(experiment_dir, commit, metric_val, "keep", description)
+ return "keep"
+ else:
+ print(f" DISCARD — no improvement")
+ run_git(["reset", "--hard", "HEAD~1"], cwd=str(project_root))
+ best_str = f"{best:.4f}" if best is not None else "?"
+ log_result(experiment_dir, commit, metric_val, "discard",
+ f"no_improvement_{metric_val:.4f}_vs_{best_str}")
+ return "discard"
+
+
+def main():
+ parser = argparse.ArgumentParser(description="autoresearch-agent runner")
+ parser.add_argument("--experiment", help="Experiment path: domain/name (e.g. engineering/api-speed)")
+ parser.add_argument("--single", action="store_true", help="Run one experiment iteration")
+ parser.add_argument("--dry-run", action="store_true", help="Show what would happen")
+ parser.add_argument("--description", help="Description of the change (auto-generated from git diff if omitted)")
+ parser.add_argument("--path", default=".", help="Project root")
+ args = parser.parse_args()
+
+ project_root = Path(args.path).resolve()
+ root = find_autoresearch_root()
+
+ if root is None:
+ print("No .autoresearch/ found. Run setup_experiment.py first.")
+ sys.exit(1)
+
+ if not args.experiment:
+ print("Specify --experiment domain/name")
+ sys.exit(1)
+
+ experiment_dir = root / args.experiment
+ if not experiment_dir.exists():
+ print(f"Experiment not found: {experiment_dir}")
+ print("Run: python scripts/setup_experiment.py --list")
+ sys.exit(1)
+
+ config = load_config(experiment_dir)
+
+ print(f"\n autoresearch-agent")
+ print(f" Experiment: {args.experiment}")
+ print(f" Target: {config.get('target', '?')}")
+ print(f" Metric: {config.get('metric', '?')} ({config.get('metric_direction', '?')} is better)")
+ print(f" Budget: {config.get('time_budget_minutes', '?')} min/experiment")
+ print(f" Mode: {'dry-run' if args.dry_run else 'single'}")
+
+ exp_num = get_experiment_count(experiment_dir) + 1
+ run_single(project_root, experiment_dir, config, exp_num, args.dry_run, args.description)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/autoresearch-agent/scripts/setup_experiment.py b/skills/autoresearch-agent/scripts/setup_experiment.py
new file mode 100644
index 00000000..ab15a5d3
--- /dev/null
+++ b/skills/autoresearch-agent/scripts/setup_experiment.py
@@ -0,0 +1,383 @@
+#!/usr/bin/env python3
+"""
+autoresearch-agent: Setup Experiment
+
+Initialize a new experiment with domain, target, evaluator, and git branch.
+Creates the .autoresearch/{domain}/{name}/ directory structure.
+
+Usage:
+ python scripts/setup_experiment.py --domain engineering --name api-speed \
+ --target src/api/search.py --eval "pytest bench.py" \
+ --metric p50_ms --direction lower
+
+ python scripts/setup_experiment.py --domain marketing --name medium-ctr \
+ --target content/titles.md --eval "python evaluate.py" \
+ --metric ctr_score --direction higher --evaluator llm_judge_content
+
+ python scripts/setup_experiment.py --list # List all experiments
+ python scripts/setup_experiment.py --list-evaluators # List available evaluators
+"""
+
+import argparse
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+DOMAINS = ["engineering", "marketing", "content", "prompts", "custom"]
+
+EVALUATOR_DIR = Path(__file__).parent.parent / "evaluators"
+
+DEFAULT_CONFIG = """# autoresearch global config
+default_time_budget_minutes: 5
+default_scope: project
+dashboard_format: markdown
+"""
+
+GITIGNORE_CONTENT = """# autoresearch — experiment logs are local state
+**/results.tsv
+**/run.log
+**/run.*.log
+config.yaml
+"""
+
+
+def run_cmd(cmd, cwd=None, timeout=None):
+ """Run shell command, return (returncode, stdout, stderr)."""
+ result = subprocess.run(
+ cmd, shell=True, capture_output=True, text=True,
+ cwd=cwd, timeout=timeout
+ )
+ return result.returncode, result.stdout.strip(), result.stderr.strip()
+
+
+def get_autoresearch_root(scope, project_root=None):
+ """Get the .autoresearch root directory based on scope."""
+ if scope == "user":
+ return Path.home() / ".autoresearch"
+ return Path(project_root or ".") / ".autoresearch"
+
+
+def init_root(root):
+ """Initialize .autoresearch root if it doesn't exist."""
+ created = False
+ if not root.exists():
+ root.mkdir(parents=True)
+ created = True
+ print(f" Created {root}/")
+
+ config_file = root / "config.yaml"
+ if not config_file.exists():
+ config_file.write_text(DEFAULT_CONFIG)
+ print(f" Created {config_file}")
+
+ gitignore = root / ".gitignore"
+ if not gitignore.exists():
+ gitignore.write_text(GITIGNORE_CONTENT)
+ print(f" Created {gitignore}")
+
+ return created
+
+
+def create_program_md(experiment_dir, domain, name, target, metric, direction, constraints=""):
+ """Generate a program.md template for the experiment."""
+ direction_word = "Minimize" if direction == "lower" else "Maximize"
+ content = f"""# autoresearch — {name}
+
+## Goal
+{direction_word} `{metric}` on `{target}`. {"Lower" if direction == "lower" else "Higher"} is better.
+
+## What the Agent Can Change
+- Only `{target}` — this is the single file being optimized.
+- Everything inside that file is fair game unless constrained below.
+
+## What the Agent Cannot Change
+- The evaluation script (`evaluate.py` or the eval command). It is read-only.
+- Dependencies — do not add new packages or imports that aren't already available.
+- Any other files in the project unless explicitly noted here.
+{f"- Additional constraints: {constraints}" if constraints else ""}
+
+## Strategy
+1. First run: establish baseline. Do not change anything.
+2. Profile/analyze the current state — understand why the metric is what it is.
+3. Try the most obvious improvement first (low-hanging fruit).
+4. If that works, push further in the same direction.
+5. If stuck, try something orthogonal or radical.
+6. Read the git log of previous experiments. Don't repeat failed approaches.
+
+## Simplicity Rule
+A small improvement that adds ugly complexity is NOT worth it.
+Equal performance with simpler code IS worth it.
+Removing code that gets same results is the best outcome.
+
+## Stop When
+You don't stop. The human will interrupt you when they're satisfied.
+If no improvement in 20+ consecutive runs, change strategy drastically.
+"""
+ (experiment_dir / "program.md").write_text(content)
+
+
+def create_config(experiment_dir, target, eval_cmd, metric, direction, time_budget):
+ """Write experiment config."""
+ content = f"""target: {target}
+evaluate_cmd: {eval_cmd}
+metric: {metric}
+metric_direction: {direction}
+metric_grep: ^{metric}:
+time_budget_minutes: {time_budget}
+created: {datetime.now().strftime('%Y-%m-%d %H:%M')}
+"""
+ (experiment_dir / "config.cfg").write_text(content)
+
+
+def init_results_tsv(experiment_dir):
+ """Create results.tsv with header."""
+ tsv = experiment_dir / "results.tsv"
+ if tsv.exists():
+ print(f" results.tsv already exists ({tsv.stat().st_size} bytes)")
+ return
+ tsv.write_text("commit\tmetric\tstatus\tdescription\n")
+ print(" Created results.tsv")
+
+
+def copy_evaluator(experiment_dir, evaluator_name):
+ """Copy a built-in evaluator to the experiment directory."""
+ source = EVALUATOR_DIR / f"{evaluator_name}.py"
+ if not source.exists():
+ print(f" Warning: evaluator '{evaluator_name}' not found in {EVALUATOR_DIR}")
+ print(f" Available: {', '.join(f.stem for f in EVALUATOR_DIR.glob('*.py'))}")
+ return False
+ dest = experiment_dir / "evaluate.py"
+ shutil.copy2(source, dest)
+ print(f" Copied evaluator: {evaluator_name}.py -> evaluate.py")
+ return True
+
+
+def create_branch(path, domain, name):
+ """Create and checkout the experiment branch."""
+ branch = f"autoresearch/{domain}/{name}"
+ result = subprocess.run(
+ ["git", "checkout", "-b", branch],
+ cwd=path, capture_output=True, text=True
+ )
+ if result.returncode != 0:
+ if "already exists" in result.stderr:
+ print(f" Branch '{branch}' already exists. Checking out...")
+ subprocess.run(
+ ["git", "checkout", branch],
+ cwd=path, capture_output=True, text=True
+ )
+ return branch
+ print(f" Warning: could not create branch: {result.stderr}")
+ return None
+ print(f" Created branch: {branch}")
+ return branch
+
+
+def list_experiments(root):
+ """List all experiments across all domains."""
+ if not root.exists():
+ print("No experiments found. Run setup to create your first experiment.")
+ return
+
+ experiments = []
+ for domain_dir in sorted(root.iterdir()):
+ if not domain_dir.is_dir() or domain_dir.name.startswith("."):
+ continue
+ for exp_dir in sorted(domain_dir.iterdir()):
+ if not exp_dir.is_dir():
+ continue
+ cfg_file = exp_dir / "config.cfg"
+ if not cfg_file.exists():
+ continue
+ config = {}
+ for line in cfg_file.read_text().splitlines():
+ if ":" in line:
+ k, v = line.split(":", 1)
+ config[k.strip()] = v.strip()
+
+ # Count results
+ tsv = exp_dir / "results.tsv"
+ runs = 0
+ if tsv.exists():
+ runs = max(0, len(tsv.read_text().splitlines()) - 1)
+
+ experiments.append({
+ "domain": domain_dir.name,
+ "name": exp_dir.name,
+ "target": config.get("target", "?"),
+ "metric": config.get("metric", "?"),
+ "runs": runs,
+ })
+
+ if not experiments:
+ print("No experiments found.")
+ return
+
+ print(f"\n{'DOMAIN':<15} {'EXPERIMENT':<25} {'TARGET':<30} {'METRIC':<15} {'RUNS':>5}")
+ print("-" * 95)
+ for e in experiments:
+ print(f"{e['domain']:<15} {e['name']:<25} {e['target']:<30} {e['metric']:<15} {e['runs']:>5}")
+ print(f"\nTotal: {len(experiments)} experiments")
+
+
+def list_evaluators():
+ """List available built-in evaluators."""
+ if not EVALUATOR_DIR.exists():
+ print("No evaluators directory found.")
+ return
+
+ print(f"\nAvailable evaluators ({EVALUATOR_DIR}):\n")
+ for f in sorted(EVALUATOR_DIR.glob("*.py")):
+ # Read first docstring line
+ desc = ""
+ for line in f.read_text().splitlines():
+ stripped = line.strip()
+ if stripped.startswith('"""') or stripped.startswith("'''"):
+ quote = stripped[:3]
+ # Single-line docstring: """Description."""
+ after_quote = stripped[3:]
+ if after_quote and after_quote.rstrip(quote[0]).strip():
+ desc = after_quote.rstrip('"').rstrip("'").strip()
+ break
+ continue
+ if stripped and not line.startswith("#!"):
+ desc = stripped.strip('"').strip("'")
+ break
+ print(f" {f.stem:<25} {desc}")
+
+
+def main():
+ parser = argparse.ArgumentParser(description="autoresearch-agent setup")
+ parser.add_argument("--domain", choices=DOMAINS, help="Experiment domain")
+ parser.add_argument("--name", help="Experiment name (e.g. api-speed, medium-ctr)")
+ parser.add_argument("--target", help="Target file to optimize")
+ parser.add_argument("--eval", dest="eval_cmd", help="Evaluation command")
+ parser.add_argument("--metric", help="Metric name (must appear in eval output as 'name: value')")
+ parser.add_argument("--direction", choices=["lower", "higher"], default="lower",
+ help="Is lower or higher better?")
+ parser.add_argument("--time-budget", type=int, default=5, help="Minutes per experiment (default: 5)")
+ parser.add_argument("--evaluator", help="Built-in evaluator to copy (e.g. benchmark_speed)")
+ parser.add_argument("--scope", choices=["project", "user"], default="project",
+ help="Where to store experiments: project (./) or user (~/)")
+ parser.add_argument("--constraints", default="", help="Additional constraints for program.md")
+ parser.add_argument("--path", default=".", help="Project root path")
+ parser.add_argument("--skip-branch", action="store_true", help="Don't create git branch")
+ parser.add_argument("--list", action="store_true", help="List all experiments")
+ parser.add_argument("--list-evaluators", action="store_true", help="List available evaluators")
+ args = parser.parse_args()
+
+ project_root = Path(args.path).resolve()
+
+ # List mode
+ if args.list:
+ root = get_autoresearch_root("project", project_root)
+ list_experiments(root)
+ user_root = get_autoresearch_root("user")
+ if user_root.exists() and user_root != root:
+ print(f"\n--- User-level experiments ({user_root}) ---")
+ list_experiments(user_root)
+ return
+
+ if args.list_evaluators:
+ list_evaluators()
+ return
+
+ # Validate required args for setup
+ if not all([args.domain, args.name, args.target, args.eval_cmd, args.metric]):
+ parser.error("Required: --domain, --name, --target, --eval, --metric")
+
+ root = get_autoresearch_root(args.scope, project_root)
+
+ print(f"\n autoresearch-agent setup")
+ print(f" Project: {project_root}")
+ print(f" Scope: {args.scope}")
+ print(f" Domain: {args.domain}")
+ print(f" Experiment: {args.name}")
+ print(f" Time: {datetime.now().strftime('%Y-%m-%d %H:%M')}\n")
+
+ # Check git
+ result = subprocess.run(
+ ["git", "rev-parse", "--is-inside-work-tree"],
+ cwd=str(project_root), capture_output=True, text=True
+ )
+ code = result.returncode
+ if code != 0:
+ print(" Error: not a git repository. Run: git init && git add . && git commit -m 'initial'")
+ sys.exit(1)
+ print(" Git repository found")
+
+ # Check target file
+ target_path = project_root / args.target
+ if not target_path.exists():
+ print(f" Error: target file not found: {args.target}")
+ sys.exit(1)
+ print(f" Target file found: {args.target}")
+
+ # Init root
+ init_root(root)
+
+ # Create experiment directory
+ experiment_dir = root / args.domain / args.name
+ if experiment_dir.exists():
+ print(f" Warning: experiment '{args.domain}/{args.name}' already exists.")
+ print(f" Use --name with a different name, or delete {experiment_dir}")
+ sys.exit(1)
+ experiment_dir.mkdir(parents=True)
+ print(f" Created {experiment_dir}/")
+
+ # Create files
+ create_program_md(experiment_dir, args.domain, args.name,
+ args.target, args.metric, args.direction, args.constraints)
+ print(" Created program.md")
+
+ create_config(experiment_dir, args.target, args.eval_cmd,
+ args.metric, args.direction, args.time_budget)
+ print(" Created config.cfg")
+
+ init_results_tsv(experiment_dir)
+
+ # Copy evaluator if specified
+ if args.evaluator:
+ copy_evaluator(experiment_dir, args.evaluator)
+
+ # Create git branch
+ if not args.skip_branch:
+ create_branch(str(project_root), args.domain, args.name)
+
+ # Test evaluation command
+ print(f"\n Testing evaluation: {args.eval_cmd}")
+ code, out, err = run_cmd(args.eval_cmd, cwd=str(project_root), timeout=60)
+ if code != 0:
+ print(f" Warning: eval command failed (exit {code})")
+ if err:
+ print(f" stderr: {err[:200]}")
+ print(" Fix the eval command before running the experiment loop.")
+ else:
+ # Check metric is parseable
+ full_output = out + "\n" + err
+ metric_found = False
+ for line in full_output.splitlines():
+ if line.strip().startswith(f"{args.metric}:"):
+ metric_found = True
+ print(f" Eval works. Baseline: {line.strip()}")
+ break
+ if not metric_found:
+ print(f" Warning: eval ran but '{args.metric}:' not found in output.")
+ print(f" Make sure your eval command outputs: {args.metric}: ")
+
+ # Summary
+ print(f"\n Setup complete!")
+ print(f" Experiment: {args.domain}/{args.name}")
+ print(f" Target: {args.target}")
+ print(f" Metric: {args.metric} ({args.direction} is better)")
+ print(f" Budget: {args.time_budget} min/experiment")
+ if not args.skip_branch:
+ print(f" Branch: autoresearch/{args.domain}/{args.name}")
+ print(f"\n To start:")
+ print(f" python scripts/run_experiment.py --experiment {args.domain}/{args.name} --single")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/autoresearch-agent/settings.json b/skills/autoresearch-agent/settings.json
new file mode 100644
index 00000000..cb73087d
--- /dev/null
+++ b/skills/autoresearch-agent/settings.json
@@ -0,0 +1,22 @@
+{
+ "name": "autoresearch-agent",
+ "displayName": "Autoresearch Agent",
+ "version": "2.1.2",
+ "description": "Autonomous experiment loop — optimize any file by a measurable metric.",
+ "author": "Alireza Rezvani",
+ "license": "MIT",
+ "platforms": ["claude-code", "openclaw", "codex"],
+ "category": "engineering",
+ "tags": ["optimization", "experiments", "benchmarks", "autoresearch", "loop", "metrics"],
+ "repository": "https://github.com/alirezarezvani/claude-skills",
+ "commands": {
+ "setup": "/ar:setup",
+ "run": "/ar:run",
+ "loop": "/ar:loop",
+ "status": "/ar:status",
+ "resume": "/ar:resume"
+ },
+ "agents": [
+ "experiment-runner"
+ ]
+}
diff --git a/skills/autoresearch-agent/skills/loop/SKILL.md b/skills/autoresearch-agent/skills/loop/SKILL.md
new file mode 100644
index 00000000..cd07d8b8
--- /dev/null
+++ b/skills/autoresearch-agent/skills/loop/SKILL.md
@@ -0,0 +1,122 @@
+---
+name: "loop"
+description: "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling."
+command: /ar:loop
+---
+
+# /ar:loop — Autonomous Experiment Loop
+
+Start a recurring experiment loop that runs at a user-selected interval.
+
+## Usage
+
+```
+/ar:loop engineering/api-speed # Start loop (prompts for interval)
+/ar:loop engineering/api-speed 10m # Every 10 minutes
+/ar:loop engineering/api-speed 1h # Every hour
+/ar:loop engineering/api-speed daily # Daily at ~9am
+/ar:loop engineering/api-speed weekly # Weekly on Monday ~9am
+/ar:loop engineering/api-speed monthly # Monthly on 1st ~9am
+/ar:loop stop engineering/api-speed # Stop an active loop
+```
+
+## What It Does
+
+### Step 1: Resolve experiment
+
+If no experiment specified, list experiments and let user pick.
+
+### Step 2: Select interval
+
+If interval not provided as argument, present options:
+
+```
+Select loop interval:
+ 1. Every 10 minutes (rapid — stay and watch)
+ 2. Every hour (background — check back later)
+ 3. Daily at ~9am (overnight experiments)
+ 4. Weekly on Monday (long-running experiments)
+ 5. Monthly on 1st (slow experiments)
+```
+
+Map to cron expressions:
+
+| Interval | Cron Expression | Shorthand |
+|----------|----------------|-----------|
+| 10 minutes | `*/10 * * * *` | `10m` |
+| 1 hour | `7 * * * *` | `1h` |
+| Daily | `57 8 * * *` | `daily` |
+| Weekly | `57 8 * * 1` | `weekly` |
+| Monthly | `57 8 1 * *` | `monthly` |
+
+### Step 3: Create the recurring job
+
+Use `CronCreate` with this prompt (fill in the experiment details):
+
+```
+You are running autoresearch experiment "{domain}/{name}".
+
+1. Read .autoresearch/{domain}/{name}/config.cfg for: target, evaluate_cmd, metric, metric_direction
+2. Read .autoresearch/{domain}/{name}/program.md for strategy and constraints
+3. Read .autoresearch/{domain}/{name}/results.tsv for experiment history
+4. Run: git checkout autoresearch/{domain}/{name}
+
+Then do exactly ONE iteration:
+- Review results.tsv: what worked, what failed, what hasn't been tried
+- Edit the target file with ONE change (strategy escalation based on run count)
+- Commit: git add {target} && git commit -m "experiment: {description}"
+- Evaluate: python {skill_path}/scripts/run_experiment.py --experiment {domain}/{name} --single
+- Read the output (KEEP/DISCARD/CRASH)
+
+Rules:
+- ONE change per experiment
+- NEVER modify the evaluator
+- If 5 consecutive crashes in results.tsv, delete this cron job (CronDelete) and alert
+- After every 10 experiments, update Strategy section of program.md
+
+Current best metric: {read from results.tsv or "no baseline yet"}
+Total experiments so far: {count from results.tsv}
+```
+
+### Step 4: Store loop metadata
+
+Write to `.autoresearch/{domain}/{name}/loop.json`:
+
+```json
+{
+ "cron_id": "{id from CronCreate}",
+ "interval": "{user selection}",
+ "started": "{ISO timestamp}",
+ "experiment": "{domain}/{name}"
+}
+```
+
+### Step 5: Confirm to user
+
+```
+Loop started for {domain}/{name}
+ Interval: {interval description}
+ Cron ID: {id}
+ Auto-expires: 3 days (CronCreate limit)
+
+ To check progress: /ar:status
+ To stop the loop: /ar:loop stop {domain}/{name}
+
+ Note: Recurring jobs auto-expire after 3 days.
+ Run /ar:loop again to restart after expiry.
+```
+
+## Stopping a Loop
+
+When user runs `/ar:loop stop {experiment}`:
+
+1. Read `.autoresearch/{domain}/{name}/loop.json` to get the cron ID
+2. Call `CronDelete` with that ID
+3. Delete `loop.json`
+4. Confirm: "Loop stopped for {experiment}. {n} experiments completed."
+
+## Important Limitations
+
+- **3-day auto-expiry**: CronCreate jobs expire after 3 days. For longer experiments, the user must re-run `/ar:loop` to restart. Results persist — the new loop picks up where the old one left off.
+- **One loop per experiment**: Don't start multiple loops for the same experiment.
+- **Concurrent experiments**: Multiple experiments can loop simultaneously ONLY if they're on different git branches (which they are by default — each experiment gets `autoresearch/{domain}/{name}`).
diff --git a/skills/autoresearch-agent/skills/resume/SKILL.md b/skills/autoresearch-agent/skills/resume/SKILL.md
new file mode 100644
index 00000000..48bc7f79
--- /dev/null
+++ b/skills/autoresearch-agent/skills/resume/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: "resume"
+description: "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating."
+command: /ar:resume
+---
+
+# /ar:resume — Resume Experiment
+
+Resume a paused or context-limited experiment. Reads all history and continues where you left off.
+
+## Usage
+
+```
+/ar:resume # List experiments, let user pick
+/ar:resume engineering/api-speed # Resume specific experiment
+```
+
+## What It Does
+
+### Step 1: List experiments if needed
+
+If no experiment specified:
+
+```bash
+python {skill_path}/scripts/setup_experiment.py --list
+```
+
+Show status for each (active/paused/done based on results.tsv age). Let user pick.
+
+### Step 2: Load full context
+
+```bash
+# Checkout the experiment branch
+git checkout autoresearch/{domain}/{name}
+
+# Read config
+cat .autoresearch/{domain}/{name}/config.cfg
+
+# Read strategy
+cat .autoresearch/{domain}/{name}/program.md
+
+# Read full results history
+cat .autoresearch/{domain}/{name}/results.tsv
+
+# Read recent git log for the branch
+git log --oneline -20
+```
+
+### Step 3: Report current state
+
+Summarize for the user:
+
+```
+Resuming: engineering/api-speed
+ Target: src/api/search.py
+ Metric: p50_ms (lower is better)
+ Experiments: 23 total — 8 kept, 12 discarded, 3 crashed
+ Best: 185ms (-42% from baseline of 320ms)
+ Last experiment: "added response caching" → KEEP (185ms)
+
+ Recent patterns:
+ - Caching changes: 3 kept, 1 discarded (consistently helpful)
+ - Algorithm changes: 2 discarded, 1 crashed (high risk, low reward so far)
+ - I/O optimization: 2 kept (promising direction)
+```
+
+### Step 4: Ask next action
+
+```
+How would you like to continue?
+ 1. Single iteration (/ar:run) — I'll make one change and evaluate
+ 2. Start a loop (/ar:loop) — Autonomous with scheduled interval
+ 3. Just show me the results — I'll review and decide
+```
+
+If the user picks loop, hand off to `/ar:loop` with the experiment pre-selected.
+If single, hand off to `/ar:run`.
diff --git a/skills/autoresearch-agent/skills/run/SKILL.md b/skills/autoresearch-agent/skills/run/SKILL.md
new file mode 100644
index 00000000..4a9caff1
--- /dev/null
+++ b/skills/autoresearch-agent/skills/run/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: "run"
+description: "Run a single experiment iteration. Edit the target file, evaluate, keep or discard."
+command: /ar:run
+---
+
+# /ar:run — Single Experiment Iteration
+
+Run exactly ONE experiment iteration: review history, decide a change, edit, commit, evaluate.
+
+## Usage
+
+```
+/ar:run engineering/api-speed # Run one iteration
+/ar:run # List experiments, let user pick
+```
+
+## What It Does
+
+### Step 1: Resolve experiment
+
+If no experiment specified, run `python {skill_path}/scripts/setup_experiment.py --list` and ask the user to pick.
+
+### Step 2: Load context
+
+```bash
+# Read experiment config
+cat .autoresearch/{domain}/{name}/config.cfg
+
+# Read strategy and constraints
+cat .autoresearch/{domain}/{name}/program.md
+
+# Read experiment history
+cat .autoresearch/{domain}/{name}/results.tsv
+
+# Checkout the experiment branch
+git checkout autoresearch/{domain}/{name}
+```
+
+### Step 3: Decide what to try
+
+Review results.tsv:
+- What changes were kept? What pattern do they share?
+- What was discarded? Avoid repeating those approaches.
+- What crashed? Understand why.
+- How many runs so far? (Escalate strategy accordingly)
+
+**Strategy escalation:**
+- Runs 1-5: Low-hanging fruit (obvious improvements)
+- Runs 6-15: Systematic exploration (vary one parameter)
+- Runs 16-30: Structural changes (algorithm swaps)
+- Runs 30+: Radical experiments (completely different approaches)
+
+### Step 4: Make ONE change
+
+Edit only the target file specified in config.cfg. Change one thing. Keep it simple.
+
+### Step 5: Commit and evaluate
+
+```bash
+git add {target}
+git commit -m "experiment: {short description of what changed}"
+
+python {skill_path}/scripts/run_experiment.py \
+ --experiment {domain}/{name} --single
+```
+
+### Step 6: Report result
+
+Read the script output. Tell the user:
+- **KEEP**: "Improvement! {metric}: {value} ({delta} from previous best)"
+- **DISCARD**: "No improvement. {metric}: {value} vs best {best}. Reverted."
+- **CRASH**: "Evaluation failed: {reason}. Reverted."
+
+### Step 7: Self-improvement check
+
+After every 10th experiment (check results.tsv line count), update the Strategy section of program.md with patterns learned.
+
+## Rules
+
+- ONE change per iteration. Don't change 5 things at once.
+- NEVER modify the evaluator (evaluate.py). It's ground truth.
+- Simplicity wins. Equal performance with simpler code is an improvement.
+- No new dependencies.
diff --git a/skills/autoresearch-agent/skills/setup/SKILL.md b/skills/autoresearch-agent/skills/setup/SKILL.md
new file mode 100644
index 00000000..15d42d28
--- /dev/null
+++ b/skills/autoresearch-agent/skills/setup/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: "setup"
+description: "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator."
+command: /ar:setup
+---
+
+# /ar:setup — Create New Experiment
+
+Set up a new autoresearch experiment with all required configuration.
+
+## Usage
+
+```
+/ar:setup # Interactive mode
+/ar:setup engineering api-speed src/api.py "pytest bench.py" p50_ms lower
+/ar:setup --list # Show existing experiments
+/ar:setup --list-evaluators # Show available evaluators
+```
+
+## What It Does
+
+### If arguments provided
+
+Pass them directly to the setup script:
+
+```bash
+python {skill_path}/scripts/setup_experiment.py \
+ --domain {domain} --name {name} \
+ --target {target} --eval "{eval_cmd}" \
+ --metric {metric} --direction {direction} \
+ [--evaluator {evaluator}] [--scope {scope}]
+```
+
+### If no arguments (interactive mode)
+
+Collect each parameter one at a time:
+
+1. **Domain** — Ask: "What domain? (engineering, marketing, content, prompts, custom)"
+2. **Name** — Ask: "Experiment name? (e.g., api-speed, blog-titles)"
+3. **Target file** — Ask: "Which file to optimize?" Verify it exists.
+4. **Eval command** — Ask: "How to measure it? (e.g., pytest bench.py, python evaluate.py)"
+5. **Metric** — Ask: "What metric does the eval output? (e.g., p50_ms, ctr_score)"
+6. **Direction** — Ask: "Is lower or higher better?"
+7. **Evaluator** (optional) — Show built-in evaluators. Ask: "Use a built-in evaluator, or your own?"
+8. **Scope** — Ask: "Store in project (.autoresearch/) or user (~/.autoresearch/)?"
+
+Then run `setup_experiment.py` with the collected parameters.
+
+### Listing
+
+```bash
+# Show existing experiments
+python {skill_path}/scripts/setup_experiment.py --list
+
+# Show available evaluators
+python {skill_path}/scripts/setup_experiment.py --list-evaluators
+```
+
+## Built-in Evaluators
+
+| Name | Metric | Use Case |
+|------|--------|----------|
+| `benchmark_speed` | `p50_ms` (lower) | Function/API execution time |
+| `benchmark_size` | `size_bytes` (lower) | File, bundle, Docker image size |
+| `test_pass_rate` | `pass_rate` (higher) | Test suite pass percentage |
+| `build_speed` | `build_seconds` (lower) | Build/compile/Docker build time |
+| `memory_usage` | `peak_mb` (lower) | Peak memory during execution |
+| `llm_judge_content` | `ctr_score` (higher) | Headlines, titles, descriptions |
+| `llm_judge_prompt` | `quality_score` (higher) | System prompts, agent instructions |
+| `llm_judge_copy` | `engagement_score` (higher) | Social posts, ad copy, emails |
+
+## After Setup
+
+Report to the user:
+- Experiment path and branch name
+- Whether the eval command worked and the baseline metric
+- Suggest: "Run `/ar:run {domain}/{name}` to start iterating, or `/ar:loop {domain}/{name}` for autonomous mode."
diff --git a/skills/autoresearch-agent/skills/status/SKILL.md b/skills/autoresearch-agent/skills/status/SKILL.md
new file mode 100644
index 00000000..56b3ed4c
--- /dev/null
+++ b/skills/autoresearch-agent/skills/status/SKILL.md
@@ -0,0 +1,71 @@
+---
+name: "status"
+description: "Show experiment dashboard with results, active loops, and progress."
+command: /ar:status
+---
+
+# /ar:status — Experiment Dashboard
+
+Show experiment results, active loops, and progress across all experiments.
+
+## Usage
+
+```
+/ar:status # Full dashboard
+/ar:status engineering/api-speed # Single experiment detail
+/ar:status --domain engineering # All experiments in a domain
+/ar:status --format markdown # Export as markdown
+/ar:status --format csv --output results.csv # Export as CSV
+```
+
+## What It Does
+
+### Single experiment
+
+```bash
+python {skill_path}/scripts/log_results.py --experiment {domain}/{name}
+```
+
+Also check for active loop:
+```bash
+cat .autoresearch/{domain}/{name}/loop.json 2>/dev/null
+```
+
+If loop.json exists, show:
+```
+Active loop: every {interval} (cron ID: {id}, started: {date})
+```
+
+### Domain view
+
+```bash
+python {skill_path}/scripts/log_results.py --domain {domain}
+```
+
+### Full dashboard
+
+```bash
+python {skill_path}/scripts/log_results.py --dashboard
+```
+
+For each experiment, also check for loop.json and show loop status.
+
+### Export
+
+```bash
+# CSV
+python {skill_path}/scripts/log_results.py --dashboard --format csv --output {file}
+
+# Markdown
+python {skill_path}/scripts/log_results.py --dashboard --format markdown --output {file}
+```
+
+## Output Example
+
+```
+DOMAIN EXPERIMENT RUNS KEPT BEST CHANGE STATUS LOOP
+engineering api-speed 47 14 185ms -76.9% active every 1h
+engineering bundle-size 23 8 412KB -58.3% paused —
+marketing medium-ctr 31 11 8.4/10 +68.0% active daily
+prompts support-tone 15 6 82/100 +46.4% done —
+```
diff --git a/skills/aws-solution-architect/SKILL.md b/skills/aws-solution-architect/SKILL.md
new file mode 100644
index 00000000..b78e2f1a
--- /dev/null
+++ b/skills/aws-solution-architect/SKILL.md
@@ -0,0 +1,381 @@
+---
+name: "aws-solution-architect"
+description: Design AWS architectures for startups using serverless patterns and IaC templates. Use when asked to design serverless architecture, create CloudFormation templates, optimize AWS costs, set up CI/CD pipelines, or migrate to AWS. Covers Lambda, API Gateway, DynamoDB, ECS, Aurora, and cost optimization.
+---
+
+# AWS Solution Architect
+
+Design scalable, cost-effective AWS architectures for startups with infrastructure-as-code templates.
+
+---
+
+## Workflow
+
+### Step 1: Gather Requirements
+
+Collect application specifications:
+
+```
+- Application type (web app, mobile backend, data pipeline, SaaS)
+- Expected users and requests per second
+- Budget constraints (monthly spend limit)
+- Team size and AWS experience level
+- Compliance requirements (GDPR, HIPAA, SOC 2)
+- Availability requirements (SLA, RPO/RTO)
+```
+
+### Step 2: Design Architecture
+
+Run the architecture designer to get pattern recommendations:
+
+```bash
+python scripts/architecture_designer.py --input requirements.json
+```
+
+**Example output:**
+
+```json
+{
+ "recommended_pattern": "serverless_web",
+ "service_stack": ["S3", "CloudFront", "API Gateway", "Lambda", "DynamoDB", "Cognito"],
+ "estimated_monthly_cost_usd": 35,
+ "pros": ["Low ops overhead", "Pay-per-use", "Auto-scaling"],
+ "cons": ["Cold starts", "15-min Lambda limit", "Eventual consistency"]
+}
+```
+
+Select from recommended patterns:
+- **Serverless Web**: S3 + CloudFront + API Gateway + Lambda + DynamoDB
+- **Event-Driven Microservices**: EventBridge + Lambda + SQS + Step Functions
+- **Three-Tier**: ALB + ECS Fargate + Aurora + ElastiCache
+- **GraphQL Backend**: AppSync + Lambda + DynamoDB + Cognito
+
+See `references/architecture_patterns.md` for detailed pattern specifications.
+
+**Validation checkpoint:** Confirm the recommended pattern matches the team's operational maturity and compliance requirements before proceeding to Step 3.
+
+### Step 3: Generate IaC Templates
+
+Create infrastructure-as-code for the selected pattern:
+
+```bash
+# Serverless stack (CloudFormation)
+python scripts/serverless_stack.py --app-name my-app --region us-east-1
+```
+
+**Example CloudFormation YAML output (core serverless resources):**
+
+```yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+
+Parameters:
+ AppName:
+ Type: String
+ Default: my-app
+
+Resources:
+ ApiFunction:
+ Type: AWS::Serverless::Function
+ Properties:
+ Handler: index.handler
+ Runtime: nodejs20.x
+ MemorySize: 512
+ Timeout: 30
+ Environment:
+ Variables:
+ TABLE_NAME: !Ref DataTable
+ Policies:
+ - DynamoDBCrudPolicy:
+ TableName: !Ref DataTable
+ Events:
+ ApiEvent:
+ Type: Api
+ Properties:
+ Path: /{proxy+}
+ Method: ANY
+
+ DataTable:
+ Type: AWS::DynamoDB::Table
+ Properties:
+ BillingMode: PAY_PER_REQUEST
+ AttributeDefinitions:
+ - AttributeName: pk
+ AttributeType: S
+ - AttributeName: sk
+ AttributeType: S
+ KeySchema:
+ - AttributeName: pk
+ KeyType: HASH
+ - AttributeName: sk
+ KeyType: RANGE
+```
+
+> Full templates including API Gateway, Cognito, IAM roles, and CloudWatch logging are generated by `serverless_stack.py` and also available in `references/architecture_patterns.md`.
+
+**Example CDK TypeScript snippet (three-tier pattern):**
+
+```typescript
+import * as ecs from 'aws-cdk-lib/aws-ecs';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as rds from 'aws-cdk-lib/aws-rds';
+
+const vpc = new ec2.Vpc(this, 'AppVpc', { maxAzs: 2 });
+
+const cluster = new ecs.Cluster(this, 'AppCluster', { vpc });
+
+const db = new rds.ServerlessCluster(this, 'AppDb', {
+ engine: rds.DatabaseClusterEngine.auroraPostgres({
+ version: rds.AuroraPostgresEngineVersion.VER_15_2,
+ }),
+ vpc,
+ scaling: { minCapacity: 0.5, maxCapacity: 4 },
+});
+```
+
+### Step 4: Review Costs
+
+Analyze estimated costs and optimization opportunities:
+
+```bash
+python scripts/cost_optimizer.py --resources current_setup.json --monthly-spend 2000
+```
+
+**Example output:**
+
+```json
+{
+ "current_monthly_usd": 2000,
+ "recommendations": [
+ { "action": "Right-size RDS db.r5.2xlarge → db.r5.large", "savings_usd": 420, "priority": "high" },
+ { "action": "Purchase 1-yr Compute Savings Plan at 40% utilization", "savings_usd": 310, "priority": "high" },
+ { "action": "Move S3 objects >90 days to Glacier Instant Retrieval", "savings_usd": 85, "priority": "medium" }
+ ],
+ "total_potential_savings_usd": 815
+}
+```
+
+Output includes:
+- Monthly cost breakdown by service
+- Right-sizing recommendations
+- Savings Plans opportunities
+- Potential monthly savings
+
+### Step 5: Deploy
+
+Deploy the generated infrastructure:
+
+```bash
+# CloudFormation
+aws cloudformation create-stack \
+ --stack-name my-app-stack \
+ --template-body file://template.yaml \
+ --capabilities CAPABILITY_IAM
+
+# CDK
+cdk deploy
+
+# Terraform
+terraform init && terraform apply
+```
+
+### Step 6: Validate and Handle Failures
+
+Verify deployment and set up monitoring:
+
+```bash
+# Check stack status
+aws cloudformation describe-stacks --stack-name my-app-stack
+
+# Set up CloudWatch alarms
+aws cloudwatch put-metric-alarm --alarm-name high-errors ...
+```
+
+**If stack creation fails:**
+
+1. Check the failure reason:
+ ```bash
+ aws cloudformation describe-stack-events \
+ --stack-name my-app-stack \
+ --query 'StackEvents[?ResourceStatus==`CREATE_FAILED`]'
+ ```
+2. Review CloudWatch Logs for Lambda or ECS errors.
+3. Fix the template or resource configuration.
+4. Delete the failed stack before retrying:
+ ```bash
+ aws cloudformation delete-stack --stack-name my-app-stack
+ # Wait for deletion
+ aws cloudformation wait stack-delete-complete --stack-name my-app-stack
+ # Redeploy
+ aws cloudformation create-stack ...
+ ```
+
+**Common failure causes:**
+- IAM permission errors → verify `--capabilities CAPABILITY_IAM` and role trust policies
+- Resource limit exceeded → request quota increase via Service Quotas console
+- Invalid template syntax → run `aws cloudformation validate-template --template-body file://template.yaml` before deploying
+
+---
+
+## Tools
+
+### architecture_designer.py
+
+Generates architecture patterns based on requirements.
+
+```bash
+python scripts/architecture_designer.py --input requirements.json --output design.json
+```
+
+**Input:** JSON with app type, scale, budget, compliance needs
+**Output:** Recommended pattern, service stack, cost estimate, pros/cons
+
+### serverless_stack.py
+
+Creates serverless CloudFormation templates.
+
+```bash
+python scripts/serverless_stack.py --app-name my-app --region us-east-1
+```
+
+**Output:** Production-ready CloudFormation YAML with:
+- API Gateway + Lambda
+- DynamoDB table
+- Cognito user pool
+- IAM roles with least privilege
+- CloudWatch logging
+
+### cost_optimizer.py
+
+Analyzes costs and recommends optimizations.
+
+```bash
+python scripts/cost_optimizer.py --resources inventory.json --monthly-spend 5000
+```
+
+**Output:** Recommendations for:
+- Idle resource removal
+- Instance right-sizing
+- Reserved capacity purchases
+- Storage tier transitions
+- NAT Gateway alternatives
+
+---
+
+## Quick Start
+
+### MVP Architecture (< $100/month)
+
+```
+Ask: "Design a serverless MVP backend for a mobile app with 1000 users"
+
+Result:
+- Lambda + API Gateway for API
+- DynamoDB pay-per-request for data
+- Cognito for authentication
+- S3 + CloudFront for static assets
+- Estimated: $20-50/month
+```
+
+### Scaling Architecture ($500-2000/month)
+
+```
+Ask: "Design a scalable architecture for a SaaS platform with 50k users"
+
+Result:
+- ECS Fargate for containerized API
+- Aurora Serverless for relational data
+- ElastiCache for session caching
+- CloudFront for CDN
+- CodePipeline for CI/CD
+- Multi-AZ deployment
+```
+
+### Cost Optimization
+
+```
+Ask: "Optimize my AWS setup to reduce costs by 30%. Current spend: $3000/month"
+
+Provide: Current resource inventory (EC2, RDS, S3, etc.)
+
+Result:
+- Idle resource identification
+- Right-sizing recommendations
+- Savings Plans analysis
+- Storage lifecycle policies
+- Target savings: $900/month
+```
+
+### IaC Generation
+
+```
+Ask: "Generate CloudFormation for a three-tier web app with auto-scaling"
+
+Result:
+- VPC with public/private subnets
+- ALB with HTTPS
+- ECS Fargate with auto-scaling
+- Aurora with read replicas
+- Security groups and IAM roles
+```
+
+---
+
+## Input Requirements
+
+Provide these details for architecture design:
+
+| Requirement | Description | Example |
+|-------------|-------------|---------|
+| Application type | What you're building | SaaS platform, mobile backend |
+| Expected scale | Users, requests/sec | 10k users, 100 RPS |
+| Budget | Monthly AWS limit | $500/month max |
+| Team context | Size, AWS experience | 3 devs, intermediate |
+| Compliance | Regulatory needs | HIPAA, GDPR, SOC 2 |
+| Availability | Uptime requirements | 99.9% SLA, 1hr RPO |
+
+**JSON Format:**
+
+```json
+{
+ "application_type": "saas_platform",
+ "expected_users": 10000,
+ "requests_per_second": 100,
+ "budget_monthly_usd": 500,
+ "team_size": 3,
+ "aws_experience": "intermediate",
+ "compliance": ["SOC2"],
+ "availability_sla": "99.9%"
+}
+```
+
+---
+
+## Output Formats
+
+### Architecture Design
+
+- Pattern recommendation with rationale
+- Service stack diagram (ASCII)
+- Monthly cost estimate and trade-offs
+
+### IaC Templates
+
+- **CloudFormation YAML**: Production-ready SAM/CFN templates
+- **CDK TypeScript**: Type-safe infrastructure code
+- **Terraform HCL**: Multi-cloud compatible configs
+
+### Cost Analysis
+
+- Current spend breakdown with optimization recommendations
+- Priority action list (high/medium/low) and implementation checklist
+
+---
+
+## Reference Documentation
+
+| Document | Contents |
+|----------|----------|
+| `references/architecture_patterns.md` | 6 patterns: serverless, microservices, three-tier, data processing, GraphQL, multi-region |
+| `references/service_selection.md` | Decision matrices for compute, database, storage, messaging |
+| `references/best_practices.md` | Serverless design, cost optimization, security hardening, scalability |
diff --git a/skills/aws-solution-architect/_meta.json b/skills/aws-solution-architect/_meta.json
new file mode 100644
index 00000000..a132b2e5
--- /dev/null
+++ b/skills/aws-solution-architect/_meta.json
@@ -0,0 +1,22 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "aws-solution-architect",
+ "displayName": "Aws Solution Architect",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773070271055,
+ "commit": "https://github.com/openclaw/skills/commit/7ff4af12a9f77f801f528d23183057e4937c3d03"
+ },
+ "history": [
+ {
+ "version": "1.0.0",
+ "publishedAt": 1770402396459,
+ "commit": "https://github.com/openclaw/skills/commit/f10045eb2ce969bf5b120d5e3565f853c993772d"
+ },
+ {
+ "version": "0.1.0",
+ "publishedAt": 1769737480802,
+ "commit": "https://github.com/clawdbot/skills/commit/63be3aacec6382c80b5677492e2f10864f55ec62"
+ }
+ ]
+}
diff --git a/skills/aws-solution-architect/assets/expected_output.json b/skills/aws-solution-architect/assets/expected_output.json
new file mode 100644
index 00000000..318681fd
--- /dev/null
+++ b/skills/aws-solution-architect/assets/expected_output.json
@@ -0,0 +1,55 @@
+{
+ "recommended_architecture": {
+ "pattern_name": "Modern Three-Tier Application",
+ "description": "Classic architecture with containers and managed services",
+ "estimated_monthly_cost": 1450,
+ "scaling_characteristics": {
+ "users_supported": "10k - 500k",
+ "requests_per_second": "1,000 - 50,000"
+ }
+ },
+ "services": {
+ "load_balancer": "Application Load Balancer (ALB)",
+ "compute": "ECS Fargate",
+ "database": "RDS Aurora (MySQL/PostgreSQL)",
+ "cache": "ElastiCache Redis",
+ "cdn": "CloudFront",
+ "storage": "S3",
+ "authentication": "Cognito"
+ },
+ "cost_breakdown": {
+ "ALB": "20-30 USD",
+ "ECS_Fargate": "50-200 USD",
+ "RDS_Aurora": "100-300 USD",
+ "ElastiCache": "30-80 USD",
+ "CloudFront": "10-50 USD",
+ "S3": "10-30 USD"
+ },
+ "implementation_phases": [
+ {
+ "phase": "Foundation",
+ "duration": "1 week",
+ "tasks": ["VPC setup", "IAM roles", "CloudTrail", "AWS Config"]
+ },
+ {
+ "phase": "Core Services",
+ "duration": "2 weeks",
+ "tasks": ["Deploy ALB", "ECS Fargate", "RDS Aurora", "ElastiCache"]
+ },
+ {
+ "phase": "Security & Monitoring",
+ "duration": "1 week",
+ "tasks": ["WAF rules", "CloudWatch dashboards", "Alarms", "X-Ray"]
+ },
+ {
+ "phase": "CI/CD",
+ "duration": "1 week",
+ "tasks": ["CodePipeline", "Blue/Green deployment", "Rollback procedures"]
+ }
+ ],
+ "iac_templates_generated": [
+ "CloudFormation template (YAML)",
+ "AWS CDK stack (TypeScript)",
+ "Terraform configuration (HCL)"
+ ]
+}
diff --git a/skills/aws-solution-architect/assets/sample_input.json b/skills/aws-solution-architect/assets/sample_input.json
new file mode 100644
index 00000000..7a4cf81f
--- /dev/null
+++ b/skills/aws-solution-architect/assets/sample_input.json
@@ -0,0 +1,18 @@
+{
+ "application_type": "saas_platform",
+ "expected_users": 50000,
+ "requests_per_second": 100,
+ "budget_monthly_usd": 1500,
+ "team_size": 5,
+ "aws_experience": "intermediate",
+ "compliance": ["GDPR"],
+ "data_size_gb": 500,
+ "region": "us-east-1",
+ "requirements": {
+ "authentication": true,
+ "real_time_features": false,
+ "multi_region": false,
+ "high_availability": true,
+ "auto_scaling": true
+ }
+}
diff --git a/skills/aws-solution-architect/references/architecture_patterns.md b/skills/aws-solution-architect/references/architecture_patterns.md
new file mode 100644
index 00000000..028a70a0
--- /dev/null
+++ b/skills/aws-solution-architect/references/architecture_patterns.md
@@ -0,0 +1,535 @@
+# AWS Architecture Patterns for Startups
+
+Reference guide for selecting the right AWS architecture pattern based on application requirements.
+
+---
+
+## Table of Contents
+
+- [Pattern Selection Matrix](#pattern-selection-matrix)
+- [Pattern 1: Serverless Web Application](#pattern-1-serverless-web-application)
+- [Pattern 2: Event-Driven Microservices](#pattern-2-event-driven-microservices)
+- [Pattern 3: Modern Three-Tier Application](#pattern-3-modern-three-tier-application)
+- [Pattern 4: Real-Time Data Processing](#pattern-4-real-time-data-processing)
+- [Pattern 5: GraphQL API Backend](#pattern-5-graphql-api-backend)
+- [Pattern 6: Multi-Region High Availability](#pattern-6-multi-region-high-availability)
+
+---
+
+## Pattern Selection Matrix
+
+| Pattern | Best For | Users | Monthly Cost | Complexity |
+|---------|----------|-------|--------------|------------|
+| Serverless Web | MVP, SaaS, mobile backend | <50K | $50-500 | Low |
+| Event-Driven Microservices | Complex workflows, async processing | Any | $100-1000 | Medium |
+| Three-Tier | Traditional web, e-commerce | 10K-500K | $300-2000 | Medium |
+| Real-Time Data | Analytics, IoT, streaming | Any | $200-1500 | High |
+| GraphQL Backend | Mobile apps, SPAs | <100K | $50-400 | Medium |
+| Multi-Region HA | Global apps, DR requirements | >100K | 1.5-2x single | High |
+
+---
+
+## Pattern 1: Serverless Web Application
+
+### Use Case
+SaaS platforms, mobile backends, low-traffic websites, MVPs
+
+### Architecture Diagram
+
+```
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ CloudFront │────▶│ S3 │ │ Cognito │
+│ (CDN) │ │ (Static) │ │ (Auth) │
+└─────────────┘ └─────────────┘ └──────┬──────┘
+ │
+┌─────────────┐ ┌─────────────┐ ┌──────▼──────┐
+│ Route 53 │────▶│ API Gateway │────▶│ Lambda │
+│ (DNS) │ │ (REST) │ │ (Functions) │
+└─────────────┘ └─────────────┘ └──────┬──────┘
+ │
+ ┌──────▼──────┐
+ │ DynamoDB │
+ │ (Database) │
+ └─────────────┘
+```
+
+### Service Stack
+
+| Layer | Service | Configuration |
+|-------|---------|---------------|
+| Frontend | S3 + CloudFront | Static hosting with HTTPS |
+| API | API Gateway + Lambda | REST endpoints with throttling |
+| Database | DynamoDB | Pay-per-request billing |
+| Auth | Cognito | User pools with MFA support |
+| CI/CD | Amplify or CodePipeline | Automated deployments |
+
+### CloudFormation Template
+
+```yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+
+Resources:
+ # API Function
+ ApiFunction:
+ Type: AWS::Serverless::Function
+ Properties:
+ Runtime: nodejs18.x
+ Handler: index.handler
+ MemorySize: 512
+ Timeout: 10
+ Events:
+ Api:
+ Type: Api
+ Properties:
+ Path: /{proxy+}
+ Method: ANY
+
+ # DynamoDB Table
+ DataTable:
+ Type: AWS::DynamoDB::Table
+ Properties:
+ BillingMode: PAY_PER_REQUEST
+ AttributeDefinitions:
+ - AttributeName: PK
+ AttributeType: S
+ - AttributeName: SK
+ AttributeType: S
+ KeySchema:
+ - AttributeName: PK
+ KeyType: HASH
+ - AttributeName: SK
+ KeyType: RANGE
+```
+
+### Cost Breakdown (10K users)
+
+| Service | Monthly Cost |
+|---------|-------------|
+| Lambda | $5-20 |
+| API Gateway | $10-30 |
+| DynamoDB | $10-50 |
+| CloudFront | $5-15 |
+| S3 | $1-5 |
+| Cognito | $0-50 |
+| **Total** | **$31-170** |
+
+### Pros and Cons
+
+**Pros:**
+- Zero server management
+- Pay only for what you use
+- Auto-scaling built-in
+- Low operational overhead
+
+**Cons:**
+- Cold start latency (100-500ms)
+- 15-minute Lambda execution limit
+- Vendor lock-in
+
+---
+
+## Pattern 2: Event-Driven Microservices
+
+### Use Case
+Complex business workflows, asynchronous processing, decoupled systems
+
+### Architecture Diagram
+
+```
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ Service │────▶│ EventBridge │────▶│ Service │
+│ A │ │ (Event Bus)│ │ B │
+└─────────────┘ └──────┬──────┘ └─────────────┘
+ │
+ ┌──────▼──────┐
+ │ SQS │
+ │ (Queue) │
+ └──────┬──────┘
+ │
+┌─────────────┐ ┌──────▼──────┐ ┌─────────────┐
+│ Step │◀────│ Lambda │────▶│ DynamoDB │
+│ Functions │ │ (Processor) │ │ (Storage) │
+└─────────────┘ └─────────────┘ └─────────────┘
+```
+
+### Service Stack
+
+| Layer | Service | Purpose |
+|-------|---------|---------|
+| Events | EventBridge | Central event bus |
+| Processing | Lambda or ECS Fargate | Event handlers |
+| Queue | SQS | Dead letter queue for failures |
+| Orchestration | Step Functions | Complex workflow state |
+| Storage | DynamoDB, S3 | Persistent data |
+
+### Event Schema Example
+
+```json
+{
+ "source": "orders.service",
+ "detail-type": "OrderCreated",
+ "detail": {
+ "orderId": "ord-12345",
+ "customerId": "cust-67890",
+ "items": [...],
+ "total": 99.99,
+ "timestamp": "2024-01-15T10:30:00Z"
+ }
+}
+```
+
+### Cost Breakdown
+
+| Service | Monthly Cost |
+|---------|-------------|
+| EventBridge | $1-10 |
+| Lambda | $20-100 |
+| SQS | $5-20 |
+| Step Functions | $25-100 |
+| DynamoDB | $20-100 |
+| **Total** | **$71-330** |
+
+### Pros and Cons
+
+**Pros:**
+- Loose coupling between services
+- Independent scaling per service
+- Failure isolation
+- Easy to test individually
+
+**Cons:**
+- Distributed system complexity
+- Eventual consistency
+- Harder to debug
+
+---
+
+## Pattern 3: Modern Three-Tier Application
+
+### Use Case
+Traditional web apps, e-commerce, CMS, applications with complex queries
+
+### Architecture Diagram
+
+```
+┌─────────────┐ ┌─────────────┐
+│ CloudFront │────▶│ ALB │
+│ (CDN) │ │ (Load Bal.) │
+└─────────────┘ └──────┬──────┘
+ │
+ ┌──────▼──────┐
+ │ ECS Fargate │
+ │ (Auto-scale)│
+ └──────┬──────┘
+ │
+ ┌──────────────────┼──────────────────┐
+ │ │ │
+ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
+ │ Aurora │ │ ElastiCache │ │ S3 │
+ │ (Database) │ │ (Redis) │ │ (Storage) │
+ └─────────────┘ └─────────────┘ └─────────────┘
+```
+
+### Service Stack
+
+| Layer | Service | Configuration |
+|-------|---------|---------------|
+| CDN | CloudFront | Edge caching, HTTPS |
+| Load Balancer | ALB | Path-based routing, health checks |
+| Compute | ECS Fargate | Container auto-scaling |
+| Database | Aurora MySQL/PostgreSQL | Multi-AZ, auto-scaling |
+| Cache | ElastiCache Redis | Session, query caching |
+| Storage | S3 | Static assets, uploads |
+
+### Terraform Example
+
+```hcl
+# ECS Service with Auto-scaling
+resource "aws_ecs_service" "app" {
+ name = "app-service"
+ cluster = aws_ecs_cluster.main.id
+ task_definition = aws_ecs_task_definition.app.arn
+ desired_count = 2
+
+ capacity_provider_strategy {
+ capacity_provider = "FARGATE"
+ weight = 100
+ }
+
+ load_balancer {
+ target_group_arn = aws_lb_target_group.app.arn
+ container_name = "app"
+ container_port = 3000
+ }
+}
+
+# Auto-scaling Policy
+resource "aws_appautoscaling_target" "app" {
+ max_capacity = 10
+ min_capacity = 2
+ resource_id = "service/${aws_ecs_cluster.main.name}/${aws_ecs_service.app.name}"
+ scalable_dimension = "ecs:service:DesiredCount"
+ service_namespace = "ecs"
+}
+```
+
+### Cost Breakdown (50K users)
+
+| Service | Monthly Cost |
+|---------|-------------|
+| ECS Fargate (2 tasks) | $100-200 |
+| ALB | $25-50 |
+| Aurora | $100-300 |
+| ElastiCache | $50-100 |
+| CloudFront | $20-50 |
+| **Total** | **$295-700** |
+
+---
+
+## Pattern 4: Real-Time Data Processing
+
+### Use Case
+Analytics, IoT data ingestion, log processing, streaming data
+
+### Architecture Diagram
+
+```
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ IoT Core │────▶│ Kinesis │────▶│ Lambda │
+│ (Devices) │ │ (Stream) │ │ (Process) │
+└─────────────┘ └─────────────┘ └──────┬──────┘
+ │
+┌─────────────┐ ┌─────────────┐ ┌──────▼──────┐
+│ QuickSight │◀────│ Athena │◀────│ S3 │
+│ (Viz) │ │ (Query) │ │ (Data Lake) │
+└─────────────┘ └─────────────┘ └─────────────┘
+ │
+ ┌──────▼──────┐
+ │ CloudWatch │
+ │ (Alerts) │
+ └─────────────┘
+```
+
+### Service Stack
+
+| Layer | Service | Purpose |
+|-------|---------|---------|
+| Ingestion | Kinesis Data Streams | Real-time data capture |
+| Processing | Lambda or Kinesis Analytics | Transform and analyze |
+| Storage | S3 (data lake) | Long-term storage |
+| Query | Athena | SQL queries on S3 |
+| Visualization | QuickSight | Dashboards and reports |
+| Alerting | CloudWatch + SNS | Threshold-based alerts |
+
+### Kinesis Producer Example
+
+```python
+import boto3
+import json
+
+kinesis = boto3.client('kinesis')
+
+def send_event(stream_name, data, partition_key):
+ response = kinesis.put_record(
+ StreamName=stream_name,
+ Data=json.dumps(data),
+ PartitionKey=partition_key
+ )
+ return response['SequenceNumber']
+
+# Send sensor reading
+send_event(
+ 'sensor-stream',
+ {'sensor_id': 'temp-01', 'value': 23.5, 'unit': 'celsius'},
+ 'sensor-01'
+)
+```
+
+### Cost Breakdown
+
+| Service | Monthly Cost |
+|---------|-------------|
+| Kinesis (1 shard) | $15-30 |
+| Lambda | $10-50 |
+| S3 | $5-50 |
+| Athena | $5-25 |
+| QuickSight | $24+ |
+| **Total** | **$59-179** |
+
+---
+
+## Pattern 5: GraphQL API Backend
+
+### Use Case
+Mobile apps, single-page applications, flexible data queries
+
+### Architecture Diagram
+
+```
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ Mobile App │────▶│ AppSync │────▶│ Lambda │
+│ or SPA │ │ (GraphQL) │ │ (Resolvers) │
+└─────────────┘ └──────┬──────┘ └─────────────┘
+ │
+ ┌──────▼──────┐
+ │ DynamoDB │
+ │ (Direct) │
+ └──────┬──────┘
+ │
+ ┌──────▼──────┐
+ │ Cognito │
+ │ (Auth) │
+ └─────────────┘
+```
+
+### AppSync Schema Example
+
+```graphql
+type Query {
+ getUser(id: ID!): User
+ listPosts(limit: Int, nextToken: String): PostConnection
+}
+
+type Mutation {
+ createPost(input: CreatePostInput!): Post
+ updatePost(input: UpdatePostInput!): Post
+}
+
+type Subscription {
+ onCreatePost: Post @aws_subscribe(mutations: ["createPost"])
+}
+
+type User {
+ id: ID!
+ email: String!
+ posts: [Post]
+}
+
+type Post {
+ id: ID!
+ title: String!
+ content: String!
+ author: User!
+ createdAt: AWSDateTime!
+}
+```
+
+### Cost Breakdown
+
+| Service | Monthly Cost |
+|---------|-------------|
+| AppSync | $4-40 |
+| Lambda | $5-30 |
+| DynamoDB | $10-50 |
+| Cognito | $0-50 |
+| **Total** | **$19-170** |
+
+---
+
+## Pattern 6: Multi-Region High Availability
+
+### Use Case
+Global applications, disaster recovery, data sovereignty compliance
+
+### Architecture Diagram
+
+```
+ ┌─────────────┐
+ │ Route 53 │
+ │(Geo routing)│
+ └──────┬──────┘
+ │
+ ┌────────────────┼────────────────┐
+ │ │
+ ┌──────▼──────┐ ┌──────▼──────┐
+ │ us-east-1 │ │ eu-west-1 │
+ │ CloudFront │ │ CloudFront │
+ └──────┬──────┘ └──────┬──────┘
+ │ │
+ ┌──────▼──────┐ ┌──────▼──────┐
+ │ ECS/Lambda │ │ ECS/Lambda │
+ └──────┬──────┘ └──────┬──────┘
+ │ │
+ ┌──────▼──────┐◀── Replication ──▶┌──────▼──────┐
+ │ DynamoDB │ │ DynamoDB │
+ │Global Table │ │Global Table │
+ └─────────────┘ └─────────────┘
+```
+
+### Service Stack
+
+| Component | Service | Configuration |
+|-----------|---------|---------------|
+| DNS | Route 53 | Geolocation or latency routing |
+| CDN | CloudFront | Multiple origins per region |
+| Compute | Lambda or ECS | Deployed in each region |
+| Database | DynamoDB Global Tables | Automatic replication |
+| Storage | S3 CRR | Cross-region replication |
+
+### Route 53 Failover Policy
+
+```yaml
+# Primary record
+HealthCheck:
+ Type: AWS::Route53::HealthCheck
+ Properties:
+ HealthCheckConfig:
+ Port: 443
+ Type: HTTPS
+ ResourcePath: /health
+ FullyQualifiedDomainName: api-us-east-1.example.com
+
+RecordSetPrimary:
+ Type: AWS::Route53::RecordSet
+ Properties:
+ Name: api.example.com
+ Type: A
+ SetIdentifier: primary
+ Failover: PRIMARY
+ HealthCheckId: !Ref HealthCheck
+ AliasTarget:
+ DNSName: !GetAtt USEast1ALB.DNSName
+ HostedZoneId: !GetAtt USEast1ALB.CanonicalHostedZoneID
+```
+
+### Cost Considerations
+
+| Factor | Impact |
+|--------|--------|
+| Compute | 2x (each region) |
+| Database | 25% premium for global tables |
+| Data Transfer | Cross-region replication costs |
+| Route 53 | Health checks + geo queries |
+| **Total** | **1.5-2x single region** |
+
+---
+
+## Pattern Comparison Summary
+
+### Latency
+
+| Pattern | Typical Latency |
+|---------|-----------------|
+| Serverless | 50-200ms (cold: 500ms+) |
+| Three-Tier | 20-100ms |
+| GraphQL | 30-150ms |
+| Multi-Region | <50ms (regional) |
+
+### Scaling Characteristics
+
+| Pattern | Scale Limit | Scale Speed |
+|---------|-------------|-------------|
+| Serverless | 1000 concurrent/function | Instant |
+| Three-Tier | Instance limits | Minutes |
+| Event-Driven | Unlimited | Instant |
+| Multi-Region | Regional limits | Instant |
+
+### Operational Complexity
+
+| Pattern | Setup | Maintenance | Debugging |
+|---------|-------|-------------|-----------|
+| Serverless | Low | Low | Medium |
+| Three-Tier | Medium | Medium | Low |
+| Event-Driven | High | Medium | High |
+| Multi-Region | High | High | High |
diff --git a/skills/aws-solution-architect/references/best_practices.md b/skills/aws-solution-architect/references/best_practices.md
new file mode 100644
index 00000000..85925a00
--- /dev/null
+++ b/skills/aws-solution-architect/references/best_practices.md
@@ -0,0 +1,631 @@
+# AWS Best Practices for Startups
+
+Production-ready practices for serverless, cost optimization, security, and operational excellence.
+
+---
+
+## Table of Contents
+
+- [Serverless Best Practices](#serverless-best-practices)
+- [Cost Optimization](#cost-optimization)
+- [Security Hardening](#security-hardening)
+- [Scalability Patterns](#scalability-patterns)
+- [DevOps and Reliability](#devops-and-reliability)
+- [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Serverless Best Practices
+
+### Lambda Function Design
+
+#### 1. Keep Functions Stateless
+
+Store state externally in DynamoDB, S3, or ElastiCache.
+
+```python
+# BAD: Function-level state
+cache = {}
+
+def handler(event, context):
+ if event['key'] in cache:
+ return cache[event['key']]
+ # ...
+
+# GOOD: External state
+import boto3
+dynamodb = boto3.resource('dynamodb')
+table = dynamodb.Table('cache')
+
+def handler(event, context):
+ response = table.get_item(Key={'pk': event['key']})
+ if 'Item' in response:
+ return response['Item']['value']
+ # ...
+```
+
+#### 2. Implement Idempotency
+
+Handle retries gracefully with unique request IDs.
+
+```python
+import boto3
+import hashlib
+
+dynamodb = boto3.resource('dynamodb')
+idempotency_table = dynamodb.Table('idempotency')
+
+def handler(event, context):
+ # Generate idempotency key
+ idempotency_key = hashlib.sha256(
+ f"{event['orderId']}-{event['action']}".encode()
+ ).hexdigest()
+
+ # Check if already processed
+ try:
+ response = idempotency_table.get_item(Key={'pk': idempotency_key})
+ if 'Item' in response:
+ return response['Item']['result']
+ except Exception:
+ pass
+
+ # Process request
+ result = process_order(event)
+
+ # Store result for idempotency
+ idempotency_table.put_item(
+ Item={
+ 'pk': idempotency_key,
+ 'result': result,
+ 'ttl': int(time.time()) + 86400 # 24h TTL
+ }
+ )
+
+ return result
+```
+
+#### 3. Optimize Cold Starts
+
+```python
+# Initialize outside handler (reused across invocations)
+import boto3
+from aws_xray_sdk.core import patch_all
+
+# SDK initialization happens once
+dynamodb = boto3.resource('dynamodb')
+table = dynamodb.Table('my-table')
+patch_all()
+
+def handler(event, context):
+ # Handler code uses pre-initialized resources
+ return table.get_item(Key={'pk': event['id']})
+```
+
+**Cold Start Reduction Techniques:**
+- Use provisioned concurrency for critical paths
+- Minimize package size (use layers for dependencies)
+- Choose interpreted languages (Python, Node.js) over compiled
+- Avoid VPC unless necessary (adds 6-10 sec cold start)
+
+#### 4. Set Appropriate Timeouts
+
+```yaml
+# Lambda configuration
+Functions:
+ ApiHandler:
+ Timeout: 10 # Shorter for synchronous APIs
+ MemorySize: 512
+
+ BackgroundProcessor:
+ Timeout: 300 # Longer for async processing
+ MemorySize: 1024
+```
+
+**Timeout Guidelines:**
+- API handlers: 10-30 seconds
+- Event processors: 60-300 seconds
+- Use Step Functions for >15 minute workflows
+
+---
+
+## Cost Optimization
+
+### 1. Right-Sizing Strategy
+
+```bash
+# Check EC2 utilization
+aws cloudwatch get-metric-statistics \
+ --namespace AWS/EC2 \
+ --metric-name CPUUtilization \
+ --dimensions Name=InstanceId,Value=i-1234567890abcdef0 \
+ --start-time $(date -d '7 days ago' -u +"%Y-%m-%dT%H:%M:%SZ") \
+ --end-time $(date -u +"%Y-%m-%dT%H:%M:%SZ") \
+ --period 3600 \
+ --statistics Average
+```
+
+**Right-Sizing Rules:**
+- <10% CPU average: Downsize instance
+- >80% CPU average: Consider upgrade or horizontal scaling
+- Review every month for the first 6 months
+
+### 2. Savings Plans and Reserved Instances
+
+| Commitment | Savings | Best For |
+|------------|---------|----------|
+| No Upfront, 1-year | 20-30% | Unknown future |
+| Partial Upfront, 1-year | 30-40% | Moderate confidence |
+| All Upfront, 3-year | 50-60% | Stable workloads |
+
+```bash
+# Check Savings Plans recommendations
+aws cost-explorer get-savings-plans-purchase-recommendation \
+ --savings-plans-type COMPUTE_SP \
+ --term-in-years ONE_YEAR \
+ --payment-option NO_UPFRONT \
+ --lookback-period-in-days THIRTY_DAYS
+```
+
+### 3. S3 Lifecycle Policies
+
+```json
+{
+ "Rules": [
+ {
+ "ID": "Transition to cheaper storage",
+ "Status": "Enabled",
+ "Filter": {
+ "Prefix": "logs/"
+ },
+ "Transitions": [
+ { "Days": 30, "StorageClass": "STANDARD_IA" },
+ { "Days": 90, "StorageClass": "GLACIER" }
+ ],
+ "Expiration": { "Days": 365 }
+ }
+ ]
+}
+```
+
+### 4. Lambda Memory Optimization
+
+Test different memory settings to find optimal cost/performance.
+
+```python
+# Use AWS Lambda Power Tuning
+# https://github.com/alexcasalboni/aws-lambda-power-tuning
+
+# Example results:
+# 128 MB: 2000ms, $0.000042
+# 512 MB: 500ms, $0.000042
+# 1024 MB: 300ms, $0.000050
+
+# Optimal: 512 MB (same cost, 4x faster)
+```
+
+### 5. NAT Gateway Alternatives
+
+```
+NAT Gateway: $0.045/hour + $0.045/GB = ~$32/month + data
+
+Alternatives:
+1. VPC Endpoints: $0.01/hour = ~$7.30/month (for AWS services)
+2. NAT Instance: t3.nano = ~$3.80/month (limited throughput)
+3. No NAT: Use VPC endpoints + Lambda outside VPC
+```
+
+### 6. CloudWatch Log Retention
+
+```yaml
+# Set retention policies to avoid unbounded growth
+LogGroup:
+ Type: AWS::Logs::LogGroup
+ Properties:
+ LogGroupName: /aws/lambda/my-function
+ RetentionInDays: 14 # 7, 14, 30, 60, 90, etc.
+```
+
+**Retention Guidelines:**
+- Development: 7 days
+- Production non-critical: 30 days
+- Production critical: 90 days
+- Compliance requirements: As specified
+
+---
+
+## Security Hardening
+
+### 1. IAM Least Privilege
+
+```json
+// BAD: Overly permissive
+{
+ "Effect": "Allow",
+ "Action": "dynamodb:*",
+ "Resource": "*"
+}
+
+// GOOD: Specific actions and resources
+{
+ "Effect": "Allow",
+ "Action": [
+ "dynamodb:GetItem",
+ "dynamodb:PutItem",
+ "dynamodb:Query"
+ ],
+ "Resource": [
+ "arn:aws:dynamodb:us-east-1:123456789:table/users",
+ "arn:aws:dynamodb:us-east-1:123456789:table/users/index/*"
+ ]
+}
+```
+
+### 2. Encryption Configuration
+
+```yaml
+# Enable encryption everywhere
+Resources:
+ # DynamoDB
+ Table:
+ Type: AWS::DynamoDB::Table
+ Properties:
+ SSESpecification:
+ SSEEnabled: true
+ SSEType: KMS
+ KMSMasterKeyId: !Ref EncryptionKey
+
+ # S3
+ Bucket:
+ Type: AWS::S3::Bucket
+ Properties:
+ BucketEncryption:
+ ServerSideEncryptionConfiguration:
+ - ServerSideEncryptionByDefault:
+ SSEAlgorithm: aws:kms
+ KMSMasterKeyID: !Ref EncryptionKey
+
+ # RDS
+ Database:
+ Type: AWS::RDS::DBInstance
+ Properties:
+ StorageEncrypted: true
+ KmsKeyId: !Ref EncryptionKey
+```
+
+### 3. Network Isolation
+
+```yaml
+# Private subnets with VPC endpoints
+Resources:
+ PrivateSubnet:
+ Type: AWS::EC2::Subnet
+ Properties:
+ MapPublicIpOnLaunch: false
+
+ # DynamoDB Gateway Endpoint (free)
+ DynamoDBEndpoint:
+ Type: AWS::EC2::VPCEndpoint
+ Properties:
+ VpcId: !Ref VPC
+ ServiceName: !Sub com.amazonaws.${AWS::Region}.dynamodb
+ VpcEndpointType: Gateway
+ RouteTableIds:
+ - !Ref PrivateRouteTable
+
+ # Secrets Manager Interface Endpoint
+ SecretsEndpoint:
+ Type: AWS::EC2::VPCEndpoint
+ Properties:
+ VpcId: !Ref VPC
+ ServiceName: !Sub com.amazonaws.${AWS::Region}.secretsmanager
+ VpcEndpointType: Interface
+ PrivateDnsEnabled: true
+```
+
+### 4. Secrets Management
+
+```python
+# Never hardcode secrets
+import boto3
+import json
+
+def get_secret(secret_name):
+ client = boto3.client('secretsmanager')
+ response = client.get_secret_value(SecretId=secret_name)
+ return json.loads(response['SecretString'])
+
+# Usage
+db_creds = get_secret('prod/database/credentials')
+connection = connect(
+ host=db_creds['host'],
+ user=db_creds['username'],
+ password=db_creds['password']
+)
+```
+
+### 5. API Protection
+
+```yaml
+# WAF + API Gateway
+WebACL:
+ Type: AWS::WAFv2::WebACL
+ Properties:
+ DefaultAction:
+ Allow: {}
+ Rules:
+ - Name: RateLimit
+ Priority: 1
+ Action:
+ Block: {}
+ Statement:
+ RateBasedStatement:
+ Limit: 2000
+ AggregateKeyType: IP
+ VisibilityConfig:
+ SampledRequestsEnabled: true
+ CloudWatchMetricsEnabled: true
+ MetricName: RateLimitRule
+
+ - Name: AWSManagedRulesCommonRuleSet
+ Priority: 2
+ OverrideAction:
+ None: {}
+ Statement:
+ ManagedRuleGroupStatement:
+ VendorName: AWS
+ Name: AWSManagedRulesCommonRuleSet
+```
+
+### 6. Audit Logging
+
+```yaml
+# Enable CloudTrail for all API calls
+CloudTrail:
+ Type: AWS::CloudTrail::Trail
+ Properties:
+ IsMultiRegionTrail: true
+ IsLogging: true
+ S3BucketName: !Ref AuditLogsBucket
+ IncludeGlobalServiceEvents: true
+ EnableLogFileValidation: true
+ EventSelectors:
+ - ReadWriteType: All
+ IncludeManagementEvents: true
+```
+
+---
+
+## Scalability Patterns
+
+### 1. Horizontal vs Vertical Scaling
+
+```
+Horizontal (preferred):
+- Add more Lambda concurrent executions
+- Add more Fargate tasks
+- Add more DynamoDB capacity
+
+Vertical (when necessary):
+- Increase Lambda memory
+- Upgrade RDS instance
+- Larger EC2 instances
+```
+
+### 2. Database Sharding
+
+```python
+# Partition by tenant ID
+def get_table_for_tenant(tenant_id):
+ shard = hash(tenant_id) % NUM_SHARDS
+ return f"data-shard-{shard}"
+
+# Or use DynamoDB single-table design with partition keys
+def get_partition_key(tenant_id, entity_type, entity_id):
+ return f"TENANT#{tenant_id}#{entity_type}#{entity_id}"
+```
+
+### 3. Caching Layers
+
+```
+Edge (CloudFront): Global, static content, TTL: hours-days
+Application (Redis): Regional, session/query cache, TTL: minutes-hours
+Database (DAX): DynamoDB-specific, TTL: minutes
+```
+
+```python
+# ElastiCache Redis caching pattern
+import redis
+import json
+
+cache = redis.Redis(host='cache.abc123.cache.amazonaws.com', port=6379)
+
+def get_user(user_id):
+ # Check cache first
+ cached = cache.get(f"user:{user_id}")
+ if cached:
+ return json.loads(cached)
+
+ # Fetch from database
+ user = db.get_user(user_id)
+
+ # Cache for 5 minutes
+ cache.setex(f"user:{user_id}", 300, json.dumps(user))
+
+ return user
+```
+
+### 4. Auto-Scaling Configuration
+
+```yaml
+# ECS Service Auto-scaling
+AutoScalingTarget:
+ Type: AWS::ApplicationAutoScaling::ScalableTarget
+ Properties:
+ MaxCapacity: 10
+ MinCapacity: 2
+ ResourceId: !Sub service/${Cluster}/${Service.Name}
+ ScalableDimension: ecs:service:DesiredCount
+ ServiceNamespace: ecs
+
+ScalingPolicy:
+ Type: AWS::ApplicationAutoScaling::ScalingPolicy
+ Properties:
+ PolicyType: TargetTrackingScaling
+ TargetTrackingScalingPolicyConfiguration:
+ PredefinedMetricSpecification:
+ PredefinedMetricType: ECSServiceAverageCPUUtilization
+ TargetValue: 70
+ ScaleInCooldown: 300
+ ScaleOutCooldown: 60
+```
+
+---
+
+## DevOps and Reliability
+
+### 1. Infrastructure as Code
+
+```bash
+# Version control all infrastructure
+git init
+git add .
+git commit -m "Initial infrastructure setup"
+
+# Use separate stacks per environment
+cdk deploy --context environment=dev
+cdk deploy --context environment=staging
+cdk deploy --context environment=production
+```
+
+### 2. Blue/Green Deployments
+
+```yaml
+# CodeDeploy Blue/Green for ECS
+DeploymentGroup:
+ Type: AWS::CodeDeploy::DeploymentGroup
+ Properties:
+ DeploymentConfigName: CodeDeployDefault.ECSAllAtOnce
+ DeploymentStyle:
+ DeploymentType: BLUE_GREEN
+ DeploymentOption: WITH_TRAFFIC_CONTROL
+ BlueGreenDeploymentConfiguration:
+ DeploymentReadyOption:
+ ActionOnTimeout: CONTINUE_DEPLOYMENT
+ WaitTimeInMinutes: 0
+ TerminateBlueInstancesOnDeploymentSuccess:
+ Action: TERMINATE
+ TerminationWaitTimeInMinutes: 5
+```
+
+### 3. Health Checks
+
+```python
+# Application health endpoint
+from flask import Flask, jsonify
+import boto3
+
+app = Flask(__name__)
+
+@app.route('/health')
+def health():
+ checks = {
+ 'database': check_database(),
+ 'cache': check_cache(),
+ 'external_api': check_external_api()
+ }
+
+ status = 'healthy' if all(checks.values()) else 'unhealthy'
+ code = 200 if status == 'healthy' else 503
+
+ return jsonify({'status': status, 'checks': checks}), code
+
+def check_database():
+ try:
+ # Quick connectivity test
+ db.execute('SELECT 1')
+ return True
+ except Exception:
+ return False
+```
+
+### 4. Monitoring Setup
+
+```yaml
+# CloudWatch Dashboard
+Dashboard:
+ Type: AWS::CloudWatch::Dashboard
+ Properties:
+ DashboardName: production-overview
+ DashboardBody: |
+ {
+ "widgets": [
+ {
+ "type": "metric",
+ "properties": {
+ "metrics": [
+ ["AWS/Lambda", "Invocations", "FunctionName", "api-handler"],
+ [".", "Errors", ".", "."],
+ [".", "Duration", ".", ".", {"stat": "p99"}]
+ ],
+ "period": 60,
+ "title": "Lambda Metrics"
+ }
+ }
+ ]
+ }
+
+# Critical Alarms
+ErrorAlarm:
+ Type: AWS::CloudWatch::Alarm
+ Properties:
+ AlarmName: high-error-rate
+ MetricName: Errors
+ Namespace: AWS/Lambda
+ Statistic: Sum
+ Period: 60
+ EvaluationPeriods: 3
+ Threshold: 10
+ ComparisonOperator: GreaterThanThreshold
+ AlarmActions:
+ - !Ref AlertTopic
+```
+
+---
+
+## Common Pitfalls
+
+### Technical Debt
+
+| Pitfall | Solution |
+|---------|----------|
+| Over-engineering early | Start simple, scale when needed |
+| Under-monitoring | Set up CloudWatch from day one |
+| Ignoring costs | Enable Cost Explorer and billing alerts |
+| Single region only | Plan for multi-region from start |
+
+### Security Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| Public S3 buckets | Block public access, use bucket policies |
+| Overly permissive IAM | Never use "*", specify resources |
+| Hardcoded credentials | Use Secrets Manager, IAM roles |
+| Unencrypted data | Enable encryption by default |
+
+### Performance Issues
+
+| Issue | Solution |
+|-------|----------|
+| No caching | Add CloudFront, ElastiCache early |
+| Inefficient queries | Use indexes, avoid DynamoDB scans |
+| Large Lambda packages | Use layers, minimize dependencies |
+| N+1 queries | Implement DataLoader, batch operations |
+
+### Cost Surprises
+
+| Surprise | Prevention |
+|----------|------------|
+| Undeleted resources | Tag everything, review weekly |
+| Data transfer costs | Keep traffic in same AZ/region |
+| NAT Gateway charges | Use VPC endpoints for AWS services |
+| Log accumulation | Set CloudWatch retention policies |
diff --git a/skills/aws-solution-architect/references/service_selection.md b/skills/aws-solution-architect/references/service_selection.md
new file mode 100644
index 00000000..a81bed2d
--- /dev/null
+++ b/skills/aws-solution-architect/references/service_selection.md
@@ -0,0 +1,484 @@
+# AWS Service Selection Guide
+
+Quick reference for choosing the right AWS service based on requirements.
+
+---
+
+## Table of Contents
+
+- [Compute Services](#compute-services)
+- [Database Services](#database-services)
+- [Storage Services](#storage-services)
+- [Messaging and Events](#messaging-and-events)
+- [API and Integration](#api-and-integration)
+- [Networking](#networking)
+- [Security and Identity](#security-and-identity)
+
+---
+
+## Compute Services
+
+### Decision Matrix
+
+| Requirement | Recommended Service |
+|-------------|---------------------|
+| Event-driven, short tasks (<15 min) | Lambda |
+| Containerized apps, predictable traffic | ECS Fargate |
+| Custom configs, GPU/FPGA | EC2 |
+| Simple container from source | App Runner |
+| Kubernetes workloads | EKS |
+| Batch processing | AWS Batch |
+
+### Lambda
+
+**Best for:** Event-driven functions, API backends, scheduled tasks
+
+```
+Limits:
+- Execution: 15 minutes max
+- Memory: 128 MB - 10 GB
+- Package: 50 MB (zip), 10 GB (container)
+- Concurrency: 1000 default (soft limit)
+
+Pricing: $0.20 per 1M requests + compute time
+```
+
+**Use when:**
+- Variable/unpredictable traffic
+- Pay-per-use is important
+- No server management desired
+- Short-duration operations
+
+**Avoid when:**
+- Long-running processes (>15 min)
+- Low-latency requirements (<50ms)
+- Heavy compute (consider Fargate)
+
+### ECS Fargate
+
+**Best for:** Containerized applications, microservices
+
+```
+Limits:
+- vCPU: 0.25 - 16
+- Memory: 0.5 GB - 120 GB
+- Storage: 20 GB - 200 GB ephemeral
+
+Pricing: Per vCPU-hour + GB-hour
+```
+
+**Use when:**
+- Containerized applications
+- Predictable traffic patterns
+- Long-running processes
+- Need more control than Lambda
+
+### EC2
+
+**Best for:** Custom configurations, specialized hardware
+
+```
+Instance Types:
+- General: t3, m6i
+- Compute: c6i
+- Memory: r6i
+- GPU: p4d, g5
+- Storage: i3, d3
+```
+
+**Use when:**
+- Need GPU/FPGA
+- Windows applications
+- Specific instance configurations
+- Reserved capacity makes sense
+
+---
+
+## Database Services
+
+### Decision Matrix
+
+| Data Type | Query Pattern | Scale | Recommended |
+|-----------|--------------|-------|-------------|
+| Key-value | Simple lookups | Any | DynamoDB |
+| Document | Flexible queries | <1TB | DocumentDB |
+| Relational | Complex joins | Variable | Aurora Serverless |
+| Relational | High volume | Fixed | Aurora Standard |
+| Time-series | Time-based | Any | Timestream |
+| Graph | Relationships | Any | Neptune |
+
+### DynamoDB
+
+**Best for:** Key-value and document data, serverless applications
+
+```
+Limits:
+- Item size: 400 KB max
+- Partition key: 2048 bytes
+- Sort key: 1024 bytes
+- GSI: 20 per table
+
+Pricing:
+- On-demand: $1.25 per million writes, $0.25 per million reads
+- Provisioned: Per RCU/WCU
+```
+
+**Data Modeling Example:**
+
+```
+# Single-table design for e-commerce
+PK SK Attributes
+USER#123 PROFILE {name, email, ...}
+USER#123 ORDER#456 {total, status, ...}
+USER#123 ORDER#456#ITEM#1 {product, qty, ...}
+PRODUCT#789 METADATA {name, price, ...}
+```
+
+### Aurora
+
+**Best for:** Relational data with complex queries
+
+| Edition | Use Case | Scaling |
+|---------|----------|---------|
+| Aurora Serverless v2 | Variable workloads | 0.5-128 ACUs, auto |
+| Aurora Standard | Predictable workloads | Instance-based |
+| Aurora Global | Multi-region | Cross-region replication |
+
+```
+Limits:
+- Storage: 128 TB max
+- Replicas: 15 read replicas
+- Connections: Instance-dependent
+
+Pricing:
+- Serverless: $0.12 per ACU-hour
+- Standard: Instance + storage + I/O
+```
+
+### Comparison: DynamoDB vs Aurora
+
+| Factor | DynamoDB | Aurora |
+|--------|----------|--------|
+| Query flexibility | Limited (key-based) | Full SQL |
+| Scaling | Instant, unlimited | Minutes, up to limits |
+| Consistency | Eventually/Strong | ACID |
+| Cost model | Per-request | Per-hour |
+| Operational | Zero management | Some management |
+
+---
+
+## Storage Services
+
+### S3 Storage Classes
+
+| Class | Access Pattern | Retrieval | Cost (GB/mo) |
+|-------|---------------|-----------|--------------|
+| Standard | Frequent | Instant | $0.023 |
+| Intelligent-Tiering | Unknown | Instant | $0.023 + monitoring |
+| Standard-IA | Infrequent (30+ days) | Instant | $0.0125 |
+| One Zone-IA | Infrequent, single AZ | Instant | $0.01 |
+| Glacier Instant | Archive, instant access | Instant | $0.004 |
+| Glacier Flexible | Archive | Minutes-hours | $0.0036 |
+| Glacier Deep Archive | Long-term archive | 12-48 hours | $0.00099 |
+
+### Lifecycle Policy Example
+
+```json
+{
+ "Rules": [
+ {
+ "ID": "Archive old data",
+ "Status": "Enabled",
+ "Transitions": [
+ {
+ "Days": 30,
+ "StorageClass": "STANDARD_IA"
+ },
+ {
+ "Days": 90,
+ "StorageClass": "GLACIER"
+ },
+ {
+ "Days": 365,
+ "StorageClass": "DEEP_ARCHIVE"
+ }
+ ],
+ "Expiration": {
+ "Days": 2555
+ }
+ }
+ ]
+}
+```
+
+### Block and File Storage
+
+| Service | Use Case | Access |
+|---------|----------|--------|
+| EBS | EC2 block storage | Single instance |
+| EFS | Shared file system | Multiple instances |
+| FSx for Lustre | HPC workloads | High throughput |
+| FSx for Windows | Windows apps | SMB protocol |
+
+---
+
+## Messaging and Events
+
+### Decision Matrix
+
+| Pattern | Service | Use Case |
+|---------|---------|----------|
+| Event routing | EventBridge | Microservices, SaaS integration |
+| Pub/sub | SNS | Fan-out notifications |
+| Queue | SQS | Decoupling, buffering |
+| Streaming | Kinesis | Real-time analytics |
+| Message broker | Amazon MQ | Legacy migrations |
+
+### EventBridge
+
+**Best for:** Event-driven architectures, SaaS integration
+
+```python
+# EventBridge rule pattern
+{
+ "source": ["orders.service"],
+ "detail-type": ["OrderCreated"],
+ "detail": {
+ "total": [{"numeric": [">=", 100]}]
+ }
+}
+```
+
+### SQS
+
+**Best for:** Decoupling services, handling load spikes
+
+| Feature | Standard | FIFO |
+|---------|----------|------|
+| Throughput | Unlimited | 3000 msg/sec |
+| Ordering | Best effort | Guaranteed |
+| Delivery | At least once | Exactly once |
+| Deduplication | No | Yes |
+
+```python
+# SQS with dead letter queue
+import boto3
+
+sqs = boto3.client('sqs')
+
+def process_with_dlq(queue_url, dlq_url, max_retries=3):
+ response = sqs.receive_message(
+ QueueUrl=queue_url,
+ MaxNumberOfMessages=10,
+ WaitTimeSeconds=20,
+ AttributeNames=['ApproximateReceiveCount']
+ )
+
+ for message in response.get('Messages', []):
+ receive_count = int(message['Attributes']['ApproximateReceiveCount'])
+
+ try:
+ process(message)
+ sqs.delete_message(QueueUrl=queue_url, ReceiptHandle=message['ReceiptHandle'])
+ except Exception as e:
+ if receive_count >= max_retries:
+ sqs.send_message(QueueUrl=dlq_url, MessageBody=message['Body'])
+ sqs.delete_message(QueueUrl=queue_url, ReceiptHandle=message['ReceiptHandle'])
+```
+
+### Kinesis
+
+**Best for:** Real-time streaming data, analytics
+
+| Service | Use Case |
+|---------|----------|
+| Data Streams | Custom processing |
+| Data Firehose | Direct to S3/Redshift |
+| Data Analytics | SQL on streams |
+| Video Streams | Video ingestion |
+
+---
+
+## API and Integration
+
+### API Gateway vs AppSync
+
+| Factor | API Gateway | AppSync |
+|--------|-------------|---------|
+| Protocol | REST, WebSocket | GraphQL |
+| Real-time | WebSocket setup | Built-in subscriptions |
+| Caching | Response caching | Field-level caching |
+| Integration | Lambda, HTTP, AWS | Lambda, DynamoDB, HTTP |
+| Pricing | Per request | Per request + data |
+
+### API Gateway Configuration
+
+```yaml
+# Throttling and caching
+Resources:
+ ApiGateway:
+ Type: AWS::ApiGateway::RestApi
+ Properties:
+ Name: my-api
+
+ ApiStage:
+ Type: AWS::ApiGateway::Stage
+ Properties:
+ StageName: prod
+ MethodSettings:
+ - HttpMethod: "*"
+ ResourcePath: "/*"
+ ThrottlingBurstLimit: 500
+ ThrottlingRateLimit: 1000
+ CachingEnabled: true
+ CacheTtlInSeconds: 300
+```
+
+### Step Functions
+
+**Best for:** Workflow orchestration, long-running processes
+
+```json
+{
+ "StartAt": "ProcessOrder",
+ "States": {
+ "ProcessOrder": {
+ "Type": "Task",
+ "Resource": "arn:aws:lambda:...:processOrder",
+ "Next": "CheckInventory"
+ },
+ "CheckInventory": {
+ "Type": "Choice",
+ "Choices": [
+ {
+ "Variable": "$.inStock",
+ "BooleanEquals": true,
+ "Next": "ShipOrder"
+ }
+ ],
+ "Default": "BackOrder"
+ },
+ "ShipOrder": {
+ "Type": "Task",
+ "Resource": "arn:aws:lambda:...:shipOrder",
+ "End": true
+ },
+ "BackOrder": {
+ "Type": "Task",
+ "Resource": "arn:aws:lambda:...:backOrder",
+ "End": true
+ }
+ }
+}
+```
+
+---
+
+## Networking
+
+### VPC Components
+
+| Component | Purpose |
+|-----------|---------|
+| VPC | Isolated network |
+| Subnet | Network segment (public/private) |
+| Internet Gateway | Public internet access |
+| NAT Gateway | Private subnet outbound |
+| VPC Endpoint | Private AWS service access |
+| Transit Gateway | VPC interconnection |
+
+### VPC Design Pattern
+
+```
+VPC: 10.0.0.0/16
+
+Public Subnets (AZ a, b, c):
+ 10.0.1.0/24, 10.0.2.0/24, 10.0.3.0/24
+ - ALB, NAT Gateway, Bastion
+
+Private Subnets (AZ a, b, c):
+ 10.0.11.0/24, 10.0.12.0/24, 10.0.13.0/24
+ - Application servers, Lambda
+
+Database Subnets (AZ a, b, c):
+ 10.0.21.0/24, 10.0.22.0/24, 10.0.23.0/24
+ - RDS, ElastiCache
+```
+
+### VPC Endpoints (Cost Savings)
+
+```yaml
+# Interface endpoint for Secrets Manager
+SecretsManagerEndpoint:
+ Type: AWS::EC2::VPCEndpoint
+ Properties:
+ VpcId: !Ref VPC
+ ServiceName: !Sub com.amazonaws.${AWS::Region}.secretsmanager
+ VpcEndpointType: Interface
+ SubnetIds: !Ref PrivateSubnets
+ SecurityGroupIds:
+ - !Ref EndpointSecurityGroup
+```
+
+---
+
+## Security and Identity
+
+### IAM Best Practices
+
+```json
+// Least privilege policy example
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "dynamodb:GetItem",
+ "dynamodb:PutItem",
+ "dynamodb:Query"
+ ],
+ "Resource": "arn:aws:dynamodb:us-east-1:123456789:table/users",
+ "Condition": {
+ "ForAllValues:StringEquals": {
+ "dynamodb:LeadingKeys": ["${aws:userid}"]
+ }
+ }
+ }
+ ]
+}
+```
+
+### Secrets Manager vs Parameter Store
+
+| Factor | Secrets Manager | Parameter Store |
+|--------|-----------------|-----------------|
+| Auto-rotation | Built-in | Manual |
+| Cross-account | Yes | Limited |
+| Pricing | $0.40/secret/month | Free (standard) |
+| Use case | Credentials, API keys | Config, non-secrets |
+
+### Cognito Configuration
+
+```yaml
+UserPool:
+ Type: AWS::Cognito::UserPool
+ Properties:
+ UserPoolName: my-app-users
+ AutoVerifiedAttributes:
+ - email
+ MfaConfiguration: OPTIONAL
+ EnabledMfas:
+ - SOFTWARE_TOKEN_MFA
+ Policies:
+ PasswordPolicy:
+ MinimumLength: 12
+ RequireLowercase: true
+ RequireUppercase: true
+ RequireNumbers: true
+ RequireSymbols: true
+ AccountRecoverySetting:
+ RecoveryMechanisms:
+ - Name: verified_email
+ Priority: 1
+```
diff --git a/skills/aws-solution-architect/scripts/architecture_designer.py b/skills/aws-solution-architect/scripts/architecture_designer.py
new file mode 100644
index 00000000..98705ad5
--- /dev/null
+++ b/skills/aws-solution-architect/scripts/architecture_designer.py
@@ -0,0 +1,808 @@
+"""
+AWS architecture design and service recommendation module.
+Generates architecture patterns based on application requirements.
+"""
+
+from typing import Dict, List, Any, Optional
+from enum import Enum
+
+
+class ApplicationType(Enum):
+ """Types of applications supported."""
+ WEB_APP = "web_application"
+ MOBILE_BACKEND = "mobile_backend"
+ DATA_PIPELINE = "data_pipeline"
+ MICROSERVICES = "microservices"
+ SAAS_PLATFORM = "saas_platform"
+ IOT_PLATFORM = "iot_platform"
+
+
+class ArchitectureDesigner:
+ """Design AWS architectures based on requirements."""
+
+ def __init__(self, requirements: Dict[str, Any]):
+ """
+ Initialize with application requirements.
+
+ Args:
+ requirements: Dictionary containing app type, traffic, budget, etc.
+ """
+ self.app_type = requirements.get('application_type', 'web_application')
+ self.expected_users = requirements.get('expected_users', 1000)
+ self.requests_per_second = requirements.get('requests_per_second', 10)
+ self.budget_monthly = requirements.get('budget_monthly_usd', 500)
+ self.team_size = requirements.get('team_size', 3)
+ self.aws_experience = requirements.get('aws_experience', 'beginner')
+ self.compliance_needs = requirements.get('compliance', [])
+ self.data_size_gb = requirements.get('data_size_gb', 10)
+
+ def recommend_architecture_pattern(self) -> Dict[str, Any]:
+ """
+ Recommend architecture pattern based on requirements.
+
+ Returns:
+ Dictionary with recommended pattern and services
+ """
+ # Determine pattern based on app type and scale
+ if self.app_type in ['web_application', 'saas_platform']:
+ if self.expected_users < 10000:
+ return self._serverless_web_architecture()
+ elif self.expected_users < 100000:
+ return self._modern_three_tier_architecture()
+ else:
+ return self._multi_region_architecture()
+
+ elif self.app_type == 'mobile_backend':
+ return self._serverless_mobile_backend()
+
+ elif self.app_type == 'data_pipeline':
+ return self._event_driven_data_pipeline()
+
+ elif self.app_type == 'microservices':
+ return self._event_driven_microservices()
+
+ elif self.app_type == 'iot_platform':
+ return self._iot_architecture()
+
+ else:
+ return self._serverless_web_architecture() # Default
+
+ def _serverless_web_architecture(self) -> Dict[str, Any]:
+ """Serverless web application pattern."""
+ return {
+ 'pattern_name': 'Serverless Web Application',
+ 'description': 'Fully serverless architecture with zero server management',
+ 'use_case': 'SaaS platforms, low to medium traffic websites, MVPs',
+ 'services': {
+ 'frontend': {
+ 'service': 'S3 + CloudFront',
+ 'purpose': 'Static website hosting with global CDN',
+ 'configuration': {
+ 's3_bucket': 'website-bucket',
+ 'cloudfront_distribution': 'HTTPS with custom domain',
+ 'caching': 'Cache-Control headers, edge caching'
+ }
+ },
+ 'api': {
+ 'service': 'API Gateway + Lambda',
+ 'purpose': 'REST API backend with auto-scaling',
+ 'configuration': {
+ 'api_type': 'REST API',
+ 'authorization': 'Cognito User Pools or API Keys',
+ 'throttling': f'{self.requests_per_second * 10} requests/second',
+ 'lambda_memory': '512 MB (optimize based on testing)',
+ 'lambda_timeout': '10 seconds'
+ }
+ },
+ 'database': {
+ 'service': 'DynamoDB',
+ 'purpose': 'NoSQL database with pay-per-request pricing',
+ 'configuration': {
+ 'billing_mode': 'PAY_PER_REQUEST',
+ 'backup': 'Point-in-time recovery enabled',
+ 'encryption': 'KMS encryption at rest'
+ }
+ },
+ 'authentication': {
+ 'service': 'Cognito',
+ 'purpose': 'User authentication and authorization',
+ 'configuration': {
+ 'user_pools': 'Email/password + social providers',
+ 'mfa': 'Optional MFA with SMS or TOTP',
+ 'token_expiration': '1 hour access, 30 days refresh'
+ }
+ },
+ 'cicd': {
+ 'service': 'AWS Amplify or CodePipeline',
+ 'purpose': 'Automated deployment from Git',
+ 'configuration': {
+ 'source': 'GitHub or CodeCommit',
+ 'build': 'Automatic on commit',
+ 'environments': 'dev, staging, production'
+ }
+ }
+ },
+ 'estimated_cost': {
+ 'monthly_usd': self._calculate_serverless_cost(),
+ 'breakdown': {
+ 'CloudFront': '10-30 USD',
+ 'Lambda': '5-20 USD',
+ 'API Gateway': '10-40 USD',
+ 'DynamoDB': '5-30 USD',
+ 'Cognito': '0-10 USD (free tier: 50k MAU)',
+ 'S3': '1-5 USD'
+ }
+ },
+ 'pros': [
+ 'No server management',
+ 'Auto-scaling built-in',
+ 'Pay only for what you use',
+ 'Fast to deploy and iterate',
+ 'High availability by default'
+ ],
+ 'cons': [
+ 'Cold start latency (100-500ms)',
+ 'Vendor lock-in to AWS',
+ 'Debugging distributed systems complex',
+ 'Learning curve for serverless patterns'
+ ],
+ 'scaling_characteristics': {
+ 'users_supported': '1k - 100k',
+ 'requests_per_second': '100 - 10,000',
+ 'scaling_method': 'Automatic (Lambda concurrency)'
+ }
+ }
+
+ def _modern_three_tier_architecture(self) -> Dict[str, Any]:
+ """Traditional three-tier with modern AWS services."""
+ return {
+ 'pattern_name': 'Modern Three-Tier Application',
+ 'description': 'Classic architecture with containers and managed services',
+ 'use_case': 'Traditional web apps, e-commerce, content management',
+ 'services': {
+ 'load_balancer': {
+ 'service': 'Application Load Balancer (ALB)',
+ 'purpose': 'Distribute traffic across instances',
+ 'configuration': {
+ 'scheme': 'internet-facing',
+ 'target_type': 'ECS tasks or EC2 instances',
+ 'health_checks': '/health endpoint, 30s interval',
+ 'ssl': 'ACM certificate for HTTPS'
+ }
+ },
+ 'compute': {
+ 'service': 'ECS Fargate or EC2 Auto Scaling',
+ 'purpose': 'Run containerized applications',
+ 'configuration': {
+ 'container_platform': 'ECS Fargate (serverless containers)',
+ 'task_definition': '512 MB memory, 0.25 vCPU (start small)',
+ 'auto_scaling': f'2-{max(4, self.expected_users // 5000)} tasks',
+ 'deployment': 'Rolling update, 50% at a time'
+ }
+ },
+ 'database': {
+ 'service': 'RDS Aurora (MySQL/PostgreSQL)',
+ 'purpose': 'Managed relational database',
+ 'configuration': {
+ 'instance_class': 'db.t3.medium or db.t4g.medium',
+ 'multi_az': 'Yes (high availability)',
+ 'read_replicas': '1-2 for read scaling',
+ 'backup_retention': '7 days',
+ 'encryption': 'KMS encryption enabled'
+ }
+ },
+ 'cache': {
+ 'service': 'ElastiCache Redis',
+ 'purpose': 'Session storage, application caching',
+ 'configuration': {
+ 'node_type': 'cache.t3.micro or cache.t4g.micro',
+ 'replication': 'Multi-AZ with automatic failover',
+ 'eviction_policy': 'allkeys-lru'
+ }
+ },
+ 'cdn': {
+ 'service': 'CloudFront',
+ 'purpose': 'Cache static assets globally',
+ 'configuration': {
+ 'origins': 'ALB (dynamic), S3 (static)',
+ 'caching': 'Cache based on headers/cookies',
+ 'compression': 'Gzip compression enabled'
+ }
+ },
+ 'storage': {
+ 'service': 'S3',
+ 'purpose': 'User uploads, backups, logs',
+ 'configuration': {
+ 'storage_class': 'S3 Standard with lifecycle policies',
+ 'versioning': 'Enabled for important buckets',
+ 'lifecycle': 'Transition to IA after 30 days'
+ }
+ }
+ },
+ 'estimated_cost': {
+ 'monthly_usd': self._calculate_three_tier_cost(),
+ 'breakdown': {
+ 'ALB': '20-30 USD',
+ 'ECS Fargate': '50-200 USD',
+ 'RDS Aurora': '100-300 USD',
+ 'ElastiCache': '30-80 USD',
+ 'CloudFront': '10-50 USD',
+ 'S3': '10-30 USD'
+ }
+ },
+ 'pros': [
+ 'Proven architecture pattern',
+ 'Easy to understand and debug',
+ 'Flexible scaling options',
+ 'Support for complex applications',
+ 'Managed services reduce operational burden'
+ ],
+ 'cons': [
+ 'Higher baseline costs',
+ 'More complex than serverless',
+ 'Requires more operational knowledge',
+ 'Manual scaling configuration needed'
+ ],
+ 'scaling_characteristics': {
+ 'users_supported': '10k - 500k',
+ 'requests_per_second': '1,000 - 50,000',
+ 'scaling_method': 'Auto Scaling based on CPU/memory/requests'
+ }
+ }
+
+ def _serverless_mobile_backend(self) -> Dict[str, Any]:
+ """Serverless mobile backend with GraphQL."""
+ return {
+ 'pattern_name': 'Serverless Mobile Backend',
+ 'description': 'Mobile-first backend with GraphQL and real-time features',
+ 'use_case': 'Mobile apps, single-page apps, offline-first applications',
+ 'services': {
+ 'api': {
+ 'service': 'AppSync (GraphQL)',
+ 'purpose': 'Flexible GraphQL API with real-time subscriptions',
+ 'configuration': {
+ 'api_type': 'GraphQL',
+ 'authorization': 'Cognito User Pools + API Keys',
+ 'resolvers': 'Direct DynamoDB or Lambda',
+ 'subscriptions': 'WebSocket for real-time updates',
+ 'caching': 'Server-side caching (1 hour TTL)'
+ }
+ },
+ 'database': {
+ 'service': 'DynamoDB',
+ 'purpose': 'Fast NoSQL database with global tables',
+ 'configuration': {
+ 'billing_mode': 'PAY_PER_REQUEST (on-demand)',
+ 'global_tables': 'Multi-region if needed',
+ 'streams': 'Enabled for change data capture',
+ 'ttl': 'Automatic expiration for temporary data'
+ }
+ },
+ 'file_storage': {
+ 'service': 'S3 + CloudFront',
+ 'purpose': 'User uploads (images, videos, documents)',
+ 'configuration': {
+ 'access': 'Signed URLs or Cognito credentials',
+ 'lifecycle': 'Intelligent-Tiering for cost optimization',
+ 'cdn': 'CloudFront for fast global delivery'
+ }
+ },
+ 'authentication': {
+ 'service': 'Cognito',
+ 'purpose': 'User management and federation',
+ 'configuration': {
+ 'identity_providers': 'Email, Google, Apple, Facebook',
+ 'mfa': 'SMS or TOTP',
+ 'groups': 'Admin, premium, free tiers',
+ 'custom_attributes': 'User metadata storage'
+ }
+ },
+ 'push_notifications': {
+ 'service': 'SNS Mobile Push',
+ 'purpose': 'Push notifications to mobile devices',
+ 'configuration': {
+ 'platforms': 'iOS (APNs), Android (FCM)',
+ 'topics': 'Group notifications by topic',
+ 'delivery_status': 'CloudWatch Logs for tracking'
+ }
+ },
+ 'analytics': {
+ 'service': 'Pinpoint',
+ 'purpose': 'User analytics and engagement',
+ 'configuration': {
+ 'events': 'Custom events tracking',
+ 'campaigns': 'Targeted messaging',
+ 'segments': 'User segmentation'
+ }
+ }
+ },
+ 'estimated_cost': {
+ 'monthly_usd': 50 + (self.expected_users * 0.005),
+ 'breakdown': {
+ 'AppSync': '5-40 USD',
+ 'DynamoDB': '10-50 USD',
+ 'Cognito': '0-15 USD',
+ 'S3 + CloudFront': '10-40 USD',
+ 'SNS': '1-10 USD',
+ 'Pinpoint': '10-30 USD'
+ }
+ },
+ 'pros': [
+ 'Single GraphQL endpoint',
+ 'Real-time subscriptions built-in',
+ 'Offline-first capabilities',
+ 'Auto-generated mobile SDK',
+ 'Flexible querying (no over/under fetching)'
+ ],
+ 'cons': [
+ 'GraphQL learning curve',
+ 'Complex queries can be expensive',
+ 'Debugging subscriptions challenging',
+ 'Limited to AWS AppSync features'
+ ],
+ 'scaling_characteristics': {
+ 'users_supported': '1k - 1M',
+ 'requests_per_second': '100 - 100,000',
+ 'scaling_method': 'Automatic (AppSync managed)'
+ }
+ }
+
+ def _event_driven_microservices(self) -> Dict[str, Any]:
+ """Event-driven microservices architecture."""
+ return {
+ 'pattern_name': 'Event-Driven Microservices',
+ 'description': 'Loosely coupled services with event bus',
+ 'use_case': 'Complex business workflows, asynchronous processing',
+ 'services': {
+ 'event_bus': {
+ 'service': 'EventBridge',
+ 'purpose': 'Central event routing between services',
+ 'configuration': {
+ 'bus_type': 'Custom event bus',
+ 'rules': 'Route events by type/source',
+ 'targets': 'Lambda, SQS, Step Functions',
+ 'archive': 'Event replay capability'
+ }
+ },
+ 'compute': {
+ 'service': 'Lambda + ECS Fargate (hybrid)',
+ 'purpose': 'Service implementation',
+ 'configuration': {
+ 'lambda': 'Lightweight services, event handlers',
+ 'fargate': 'Long-running services, heavy processing',
+ 'auto_scaling': 'Lambda (automatic), Fargate (target tracking)'
+ }
+ },
+ 'queues': {
+ 'service': 'SQS',
+ 'purpose': 'Decouple services, handle failures',
+ 'configuration': {
+ 'queue_type': 'Standard (high throughput) or FIFO (ordering)',
+ 'dlq': 'Dead letter queue after 3 retries',
+ 'visibility_timeout': '30 seconds (adjust per service)',
+ 'retention': '4 days'
+ }
+ },
+ 'orchestration': {
+ 'service': 'Step Functions',
+ 'purpose': 'Complex workflows, saga patterns',
+ 'configuration': {
+ 'type': 'Standard (long-running) or Express (high volume)',
+ 'error_handling': 'Retry, catch, rollback logic',
+ 'timeouts': 'Per-state timeouts',
+ 'logging': 'CloudWatch Logs integration'
+ }
+ },
+ 'database': {
+ 'service': 'DynamoDB (per service)',
+ 'purpose': 'Each microservice owns its data',
+ 'configuration': {
+ 'pattern': 'Database per service',
+ 'streams': 'DynamoDB Streams for change events',
+ 'backup': 'Point-in-time recovery'
+ }
+ },
+ 'api_gateway': {
+ 'service': 'API Gateway',
+ 'purpose': 'Unified API facade',
+ 'configuration': {
+ 'integration': 'Lambda proxy or HTTP proxy',
+ 'authentication': 'Cognito or Lambda authorizer',
+ 'rate_limiting': 'Per-client throttling'
+ }
+ }
+ },
+ 'estimated_cost': {
+ 'monthly_usd': 100 + (self.expected_users * 0.01),
+ 'breakdown': {
+ 'EventBridge': '5-20 USD',
+ 'Lambda': '20-100 USD',
+ 'SQS': '1-10 USD',
+ 'Step Functions': '10-50 USD',
+ 'DynamoDB': '30-150 USD',
+ 'API Gateway': '10-40 USD'
+ }
+ },
+ 'pros': [
+ 'Loose coupling between services',
+ 'Independent scaling and deployment',
+ 'Failure isolation',
+ 'Technology diversity possible',
+ 'Easy to test individual services'
+ ],
+ 'cons': [
+ 'Operational complexity',
+ 'Distributed tracing required',
+ 'Eventual consistency challenges',
+ 'Network latency between services',
+ 'More moving parts to monitor'
+ ],
+ 'scaling_characteristics': {
+ 'users_supported': '10k - 10M',
+ 'requests_per_second': '1,000 - 1,000,000',
+ 'scaling_method': 'Per-service auto-scaling'
+ }
+ }
+
+ def _event_driven_data_pipeline(self) -> Dict[str, Any]:
+ """Real-time data processing pipeline."""
+ return {
+ 'pattern_name': 'Real-Time Data Pipeline',
+ 'description': 'Scalable data ingestion and processing',
+ 'use_case': 'Analytics, IoT data, log processing, ETL',
+ 'services': {
+ 'ingestion': {
+ 'service': 'Kinesis Data Streams',
+ 'purpose': 'Real-time data ingestion',
+ 'configuration': {
+ 'shards': f'{max(1, self.data_size_gb // 10)} shards',
+ 'retention': '24 hours (extend to 7 days if needed)',
+ 'encryption': 'KMS encryption'
+ }
+ },
+ 'processing': {
+ 'service': 'Lambda or Kinesis Analytics',
+ 'purpose': 'Transform and enrich data',
+ 'configuration': {
+ 'lambda_concurrency': 'Match shard count',
+ 'batch_size': '100-500 records per invocation',
+ 'error_handling': 'DLQ for failed records'
+ }
+ },
+ 'storage': {
+ 'service': 'S3 Data Lake',
+ 'purpose': 'Long-term storage and analytics',
+ 'configuration': {
+ 'format': 'Parquet (compressed, columnar)',
+ 'partitioning': 'By date (year/month/day/hour)',
+ 'lifecycle': 'Transition to Glacier after 90 days',
+ 'catalog': 'AWS Glue Data Catalog'
+ }
+ },
+ 'analytics': {
+ 'service': 'Athena',
+ 'purpose': 'SQL queries on S3 data',
+ 'configuration': {
+ 'query_results': 'Store in separate S3 bucket',
+ 'workgroups': 'Separate dev and prod',
+ 'cost_controls': 'Query limits per workgroup'
+ }
+ },
+ 'visualization': {
+ 'service': 'QuickSight',
+ 'purpose': 'Business intelligence dashboards',
+ 'configuration': {
+ 'source': 'Athena or direct S3',
+ 'refresh': 'Hourly or daily',
+ 'sharing': 'Embedded dashboards or web access'
+ }
+ },
+ 'alerting': {
+ 'service': 'CloudWatch + SNS',
+ 'purpose': 'Monitor metrics and alerts',
+ 'configuration': {
+ 'metrics': 'Custom metrics from processing',
+ 'alarms': 'Threshold-based alerts',
+ 'notifications': 'Email, Slack, PagerDuty'
+ }
+ }
+ },
+ 'estimated_cost': {
+ 'monthly_usd': self._calculate_data_pipeline_cost(),
+ 'breakdown': {
+ 'Kinesis': '15-100 USD (per shard)',
+ 'Lambda': '10-50 USD',
+ 'S3': '10-50 USD',
+ 'Athena': '5-30 USD (per TB scanned)',
+ 'QuickSight': '9-18 USD per user',
+ 'Glue': '5-20 USD'
+ }
+ },
+ 'pros': [
+ 'Real-time processing capability',
+ 'Scales to millions of events',
+ 'Cost-effective long-term storage',
+ 'SQL analytics on raw data',
+ 'Serverless architecture'
+ ],
+ 'cons': [
+ 'Kinesis shard management required',
+ 'Athena costs based on data scanned',
+ 'Schema evolution complexity',
+ 'Cold data queries can be slow'
+ ],
+ 'scaling_characteristics': {
+ 'events_per_second': '1,000 - 1,000,000',
+ 'data_volume': '1 GB - 1 PB per day',
+ 'scaling_method': 'Add Kinesis shards, partition S3 data'
+ }
+ }
+
+ def _iot_architecture(self) -> Dict[str, Any]:
+ """IoT platform architecture."""
+ return {
+ 'pattern_name': 'IoT Platform',
+ 'description': 'Scalable IoT device management and data processing',
+ 'use_case': 'Connected devices, sensors, smart devices',
+ 'services': {
+ 'device_management': {
+ 'service': 'IoT Core',
+ 'purpose': 'Device connectivity and management',
+ 'configuration': {
+ 'protocol': 'MQTT over TLS',
+ 'thing_registry': 'Device metadata storage',
+ 'device_shadow': 'Desired and reported state',
+ 'rules_engine': 'Route messages to services'
+ }
+ },
+ 'device_provisioning': {
+ 'service': 'IoT Device Management',
+ 'purpose': 'Fleet provisioning and updates',
+ 'configuration': {
+ 'fleet_indexing': 'Search devices',
+ 'jobs': 'OTA firmware updates',
+ 'bulk_operations': 'Manage device groups'
+ }
+ },
+ 'data_processing': {
+ 'service': 'IoT Analytics',
+ 'purpose': 'Process and analyze IoT data',
+ 'configuration': {
+ 'channels': 'Ingest device data',
+ 'pipelines': 'Transform and enrich',
+ 'data_store': 'Time-series storage',
+ 'notebooks': 'Jupyter notebooks for analysis'
+ }
+ },
+ 'time_series_db': {
+ 'service': 'Timestream',
+ 'purpose': 'Store time-series metrics',
+ 'configuration': {
+ 'memory_store': 'Recent data (hours)',
+ 'magnetic_store': 'Historical data (years)',
+ 'retention': 'Auto-tier based on age'
+ }
+ },
+ 'real_time_alerts': {
+ 'service': 'IoT Events',
+ 'purpose': 'Detect and respond to events',
+ 'configuration': {
+ 'detector_models': 'Define alert conditions',
+ 'actions': 'SNS, Lambda, SQS',
+ 'state_tracking': 'Per-device state machines'
+ }
+ }
+ },
+ 'estimated_cost': {
+ 'monthly_usd': 50 + (self.expected_users * 0.1), # Expected_users = device count
+ 'breakdown': {
+ 'IoT Core': '10-100 USD (per million messages)',
+ 'IoT Analytics': '5-50 USD',
+ 'Timestream': '10-80 USD',
+ 'IoT Events': '1-20 USD',
+ 'Data transfer': '10-50 USD'
+ }
+ },
+ 'pros': [
+ 'Built for IoT scale',
+ 'Secure device connectivity',
+ 'Managed device lifecycle',
+ 'Time-series optimized',
+ 'Real-time event detection'
+ ],
+ 'cons': [
+ 'IoT-specific pricing model',
+ 'MQTT protocol required',
+ 'Regional limitations',
+ 'Complexity for simple use cases'
+ ],
+ 'scaling_characteristics': {
+ 'devices_supported': '100 - 10,000,000',
+ 'messages_per_second': '1,000 - 100,000',
+ 'scaling_method': 'Automatic (managed service)'
+ }
+ }
+
+ def _multi_region_architecture(self) -> Dict[str, Any]:
+ """Multi-region high availability architecture."""
+ return {
+ 'pattern_name': 'Multi-Region High Availability',
+ 'description': 'Global deployment with disaster recovery',
+ 'use_case': 'Global applications, 99.99% uptime, compliance',
+ 'services': {
+ 'dns': {
+ 'service': 'Route 53',
+ 'purpose': 'Global traffic routing',
+ 'configuration': {
+ 'routing_policy': 'Geolocation or latency-based',
+ 'health_checks': 'Active monitoring with failover',
+ 'failover': 'Automatic to secondary region'
+ }
+ },
+ 'cdn': {
+ 'service': 'CloudFront',
+ 'purpose': 'Edge caching and acceleration',
+ 'configuration': {
+ 'origins': 'Multiple regions (primary + secondary)',
+ 'origin_failover': 'Automatic failover',
+ 'edge_locations': 'Global (400+ locations)'
+ }
+ },
+ 'compute': {
+ 'service': 'Multi-region Lambda or ECS',
+ 'purpose': 'Active-active deployment',
+ 'configuration': {
+ 'regions': 'us-east-1 (primary), eu-west-1 (secondary)',
+ 'deployment': 'Blue/Green in each region',
+ 'traffic_split': '70/30 or 50/50'
+ }
+ },
+ 'database': {
+ 'service': 'DynamoDB Global Tables or Aurora Global',
+ 'purpose': 'Multi-region replication',
+ 'configuration': {
+ 'replication': 'Sub-second replication lag',
+ 'read_locality': 'Read from nearest region',
+ 'write_forwarding': 'Aurora Global write forwarding',
+ 'conflict_resolution': 'Last writer wins'
+ }
+ },
+ 'storage': {
+ 'service': 'S3 Cross-Region Replication',
+ 'purpose': 'Replicate data across regions',
+ 'configuration': {
+ 'replication': 'Async replication to secondary',
+ 'versioning': 'Required for CRR',
+ 'replication_time_control': '15 minutes SLA'
+ }
+ }
+ },
+ 'estimated_cost': {
+ 'monthly_usd': self._calculate_three_tier_cost() * 1.8,
+ 'breakdown': {
+ 'Route 53': '10-30 USD',
+ 'CloudFront': '20-100 USD',
+ 'Compute (2 regions)': '100-500 USD',
+ 'Database (Global Tables)': '200-800 USD',
+ 'Data transfer (cross-region)': '50-200 USD'
+ }
+ },
+ 'pros': [
+ 'Global low latency',
+ 'High availability (99.99%+)',
+ 'Disaster recovery built-in',
+ 'Data sovereignty compliance',
+ 'Automatic failover'
+ ],
+ 'cons': [
+ '1.5-2x costs vs single region',
+ 'Complex deployment pipeline',
+ 'Data consistency challenges',
+ 'More operational overhead',
+ 'Cross-region data transfer costs'
+ ],
+ 'scaling_characteristics': {
+ 'users_supported': '100k - 100M',
+ 'requests_per_second': '10,000 - 10,000,000',
+ 'scaling_method': 'Per-region auto-scaling + global routing'
+ }
+ }
+
+ def _calculate_serverless_cost(self) -> float:
+ """Estimate serverless architecture cost."""
+ requests_per_month = self.requests_per_second * 2_592_000 # 30 days
+ lambda_cost = (requests_per_month / 1_000_000) * 0.20 # $0.20 per 1M requests
+ api_gateway_cost = (requests_per_month / 1_000_000) * 3.50 # $3.50 per 1M requests
+ dynamodb_cost = max(5, self.data_size_gb * 0.25) # $0.25 per GB/month
+ cloudfront_cost = max(10, self.expected_users * 0.01)
+
+ total = lambda_cost + api_gateway_cost + dynamodb_cost + cloudfront_cost
+ return min(total, self.budget_monthly) # Cap at budget
+
+ def _calculate_three_tier_cost(self) -> float:
+ """Estimate three-tier architecture cost."""
+ fargate_tasks = max(2, self.expected_users // 5000)
+ fargate_cost = fargate_tasks * 30 # ~$30 per task/month
+ rds_cost = 150 # db.t3.medium baseline
+ elasticache_cost = 40 # cache.t3.micro
+ alb_cost = 25
+
+ total = fargate_cost + rds_cost + elasticache_cost + alb_cost
+ return min(total, self.budget_monthly)
+
+ def _calculate_data_pipeline_cost(self) -> float:
+ """Estimate data pipeline cost."""
+ shards = max(1, self.data_size_gb // 10)
+ kinesis_cost = shards * 15 # $15 per shard/month
+ s3_cost = self.data_size_gb * 0.023 # $0.023 per GB/month
+ lambda_cost = 20 # Processing
+ athena_cost = 15 # Queries
+
+ total = kinesis_cost + s3_cost + lambda_cost + athena_cost
+ return min(total, self.budget_monthly)
+
+ def generate_service_checklist(self) -> List[Dict[str, Any]]:
+ """Generate implementation checklist for recommended architecture."""
+ architecture = self.recommend_architecture_pattern()
+
+ checklist = [
+ {
+ 'phase': 'Planning',
+ 'tasks': [
+ 'Review architecture pattern and services',
+ 'Estimate costs using AWS Pricing Calculator',
+ 'Define environment strategy (dev, staging, prod)',
+ 'Set up AWS Organization and accounts',
+ 'Define tagging strategy for resources'
+ ]
+ },
+ {
+ 'phase': 'Foundation',
+ 'tasks': [
+ 'Create VPC with public/private subnets',
+ 'Configure NAT Gateway or VPC endpoints',
+ 'Set up IAM roles and policies',
+ 'Enable CloudTrail for audit logging',
+ 'Configure AWS Config for compliance'
+ ]
+ },
+ {
+ 'phase': 'Core Services',
+ 'tasks': [
+ f"Deploy {service['service']}"
+ for service in architecture['services'].values()
+ ]
+ },
+ {
+ 'phase': 'Security',
+ 'tasks': [
+ 'Configure security groups and NACLs',
+ 'Enable encryption (KMS) for all services',
+ 'Set up AWS WAF rules',
+ 'Configure Secrets Manager',
+ 'Enable GuardDuty for threat detection'
+ ]
+ },
+ {
+ 'phase': 'Monitoring',
+ 'tasks': [
+ 'Create CloudWatch dashboards',
+ 'Set up alarms for critical metrics',
+ 'Configure SNS topics for notifications',
+ 'Enable X-Ray for distributed tracing',
+ 'Set up log aggregation and retention'
+ ]
+ },
+ {
+ 'phase': 'CI/CD',
+ 'tasks': [
+ 'Set up CodePipeline or GitHub Actions',
+ 'Configure automated testing',
+ 'Implement blue/green deployment',
+ 'Set up rollback procedures',
+ 'Document deployment process'
+ ]
+ }
+ ]
+
+ return checklist
diff --git a/skills/aws-solution-architect/scripts/cost_optimizer.py b/skills/aws-solution-architect/scripts/cost_optimizer.py
new file mode 100644
index 00000000..3aac9634
--- /dev/null
+++ b/skills/aws-solution-architect/scripts/cost_optimizer.py
@@ -0,0 +1,346 @@
+"""
+AWS cost optimization analyzer.
+Provides cost-saving recommendations for startup budgets.
+"""
+
+from typing import Dict, List, Any, Optional
+
+
+class CostOptimizer:
+ """Analyze AWS costs and provide optimization recommendations."""
+
+ def __init__(self, current_resources: Dict[str, Any], monthly_spend: float):
+ """
+ Initialize with current AWS resources and spending.
+
+ Args:
+ current_resources: Dictionary of current AWS resources
+ monthly_spend: Current monthly AWS spend in USD
+ """
+ self.resources = current_resources
+ self.monthly_spend = monthly_spend
+ self.recommendations = []
+
+ def analyze_and_optimize(self) -> Dict[str, Any]:
+ """
+ Analyze current setup and generate cost optimization recommendations.
+
+ Returns:
+ Dictionary with recommendations and potential savings
+ """
+ self.recommendations = []
+ potential_savings = 0.0
+
+ # Analyze compute resources
+ compute_savings = self._analyze_compute()
+ potential_savings += compute_savings
+
+ # Analyze storage
+ storage_savings = self._analyze_storage()
+ potential_savings += storage_savings
+
+ # Analyze database
+ database_savings = self._analyze_database()
+ potential_savings += database_savings
+
+ # Analyze networking
+ network_savings = self._analyze_networking()
+ potential_savings += network_savings
+
+ # General AWS optimizations
+ general_savings = self._analyze_general_optimizations()
+ potential_savings += general_savings
+
+ return {
+ 'current_monthly_spend': self.monthly_spend,
+ 'potential_monthly_savings': round(potential_savings, 2),
+ 'optimized_monthly_spend': round(self.monthly_spend - potential_savings, 2),
+ 'savings_percentage': round((potential_savings / self.monthly_spend) * 100, 2) if self.monthly_spend > 0 else 0,
+ 'recommendations': self.recommendations,
+ 'priority_actions': self._prioritize_recommendations()
+ }
+
+ def _analyze_compute(self) -> float:
+ """Analyze compute resources (EC2, Lambda, Fargate)."""
+ savings = 0.0
+
+ ec2_instances = self.resources.get('ec2_instances', [])
+ if ec2_instances:
+ # Check for idle instances
+ idle_count = sum(1 for inst in ec2_instances if inst.get('cpu_utilization', 100) < 10)
+ if idle_count > 0:
+ idle_cost = idle_count * 50 # Assume $50/month per idle instance
+ savings += idle_cost
+ self.recommendations.append({
+ 'service': 'EC2',
+ 'type': 'Idle Resources',
+ 'issue': f'{idle_count} EC2 instances with <10% CPU utilization',
+ 'recommendation': 'Stop or terminate idle instances, or downsize to smaller instance types',
+ 'potential_savings': idle_cost,
+ 'priority': 'high'
+ })
+
+ # Check for Savings Plans / Reserved Instances
+ on_demand_count = sum(1 for inst in ec2_instances if inst.get('pricing', 'on-demand') == 'on-demand')
+ if on_demand_count >= 2:
+ ri_savings = on_demand_count * 50 * 0.30 # 30% savings with RIs
+ savings += ri_savings
+ self.recommendations.append({
+ 'service': 'EC2',
+ 'type': 'Pricing Optimization',
+ 'issue': f'{on_demand_count} instances on On-Demand pricing',
+ 'recommendation': 'Purchase Compute Savings Plan or Reserved Instances for predictable workloads (1-year commitment)',
+ 'potential_savings': ri_savings,
+ 'priority': 'medium'
+ })
+
+ # Lambda optimization
+ lambda_functions = self.resources.get('lambda_functions', [])
+ if lambda_functions:
+ oversized = sum(1 for fn in lambda_functions if fn.get('memory_mb', 128) > 512 and fn.get('avg_memory_used_mb', 0) < 256)
+ if oversized > 0:
+ lambda_savings = oversized * 5 # Assume $5/month per oversized function
+ savings += lambda_savings
+ self.recommendations.append({
+ 'service': 'Lambda',
+ 'type': 'Right-sizing',
+ 'issue': f'{oversized} Lambda functions over-provisioned (memory too high)',
+ 'recommendation': 'Use AWS Lambda Power Tuning tool to optimize memory settings',
+ 'potential_savings': lambda_savings,
+ 'priority': 'low'
+ })
+
+ return savings
+
+ def _analyze_storage(self) -> float:
+ """Analyze S3 and other storage resources."""
+ savings = 0.0
+
+ s3_buckets = self.resources.get('s3_buckets', [])
+ for bucket in s3_buckets:
+ size_gb = bucket.get('size_gb', 0)
+ storage_class = bucket.get('storage_class', 'STANDARD')
+
+ # Check for lifecycle policies
+ if not bucket.get('has_lifecycle_policy', False) and size_gb > 100:
+ lifecycle_savings = size_gb * 0.015 # $0.015/GB savings with IA transition
+ savings += lifecycle_savings
+ self.recommendations.append({
+ 'service': 'S3',
+ 'type': 'Lifecycle Policy',
+ 'issue': f'Bucket {bucket.get("name", "unknown")} ({size_gb} GB) has no lifecycle policy',
+ 'recommendation': 'Implement lifecycle policy: Transition to IA after 30 days, Glacier after 90 days',
+ 'potential_savings': lifecycle_savings,
+ 'priority': 'medium'
+ })
+
+ # Check for Intelligent-Tiering
+ if storage_class == 'STANDARD' and size_gb > 500:
+ tiering_savings = size_gb * 0.005
+ savings += tiering_savings
+ self.recommendations.append({
+ 'service': 'S3',
+ 'type': 'Storage Class',
+ 'issue': f'Large bucket ({size_gb} GB) using STANDARD storage',
+ 'recommendation': 'Enable S3 Intelligent-Tiering for automatic cost optimization',
+ 'potential_savings': tiering_savings,
+ 'priority': 'high'
+ })
+
+ return savings
+
+ def _analyze_database(self) -> float:
+ """Analyze RDS, DynamoDB, and other database costs."""
+ savings = 0.0
+
+ rds_instances = self.resources.get('rds_instances', [])
+ for db in rds_instances:
+ # Check for idle databases
+ if db.get('connections_per_day', 1000) < 10:
+ db_cost = db.get('monthly_cost', 100)
+ savings += db_cost * 0.8 # Can save 80% by stopping
+ self.recommendations.append({
+ 'service': 'RDS',
+ 'type': 'Idle Resource',
+ 'issue': f'Database {db.get("name", "unknown")} has <10 connections/day',
+ 'recommendation': 'Stop database if not needed, or take final snapshot and delete',
+ 'potential_savings': db_cost * 0.8,
+ 'priority': 'high'
+ })
+
+ # Check for Aurora Serverless opportunity
+ if db.get('engine', '').startswith('aurora') and db.get('utilization', 100) < 30:
+ serverless_savings = db.get('monthly_cost', 200) * 0.40
+ savings += serverless_savings
+ self.recommendations.append({
+ 'service': 'RDS Aurora',
+ 'type': 'Serverless Migration',
+ 'issue': f'Aurora instance {db.get("name", "unknown")} has low utilization (<30%)',
+ 'recommendation': 'Migrate to Aurora Serverless v2 for auto-scaling and pay-per-use',
+ 'potential_savings': serverless_savings,
+ 'priority': 'medium'
+ })
+
+ # DynamoDB optimization
+ dynamodb_tables = self.resources.get('dynamodb_tables', [])
+ for table in dynamodb_tables:
+ if table.get('billing_mode', 'PROVISIONED') == 'PROVISIONED':
+ read_capacity = table.get('read_capacity_units', 0)
+ write_capacity = table.get('write_capacity_units', 0)
+ utilization = table.get('utilization_percentage', 100)
+
+ if utilization < 20:
+ on_demand_savings = (read_capacity * 0.00013 + write_capacity * 0.00065) * 730 * 0.3
+ savings += on_demand_savings
+ self.recommendations.append({
+ 'service': 'DynamoDB',
+ 'type': 'Billing Mode',
+ 'issue': f'Table {table.get("name", "unknown")} has low utilization with provisioned capacity',
+ 'recommendation': 'Switch to On-Demand billing mode for variable workloads',
+ 'potential_savings': on_demand_savings,
+ 'priority': 'medium'
+ })
+
+ return savings
+
+ def _analyze_networking(self) -> float:
+ """Analyze networking costs (data transfer, NAT Gateway, etc.)."""
+ savings = 0.0
+
+ nat_gateways = self.resources.get('nat_gateways', [])
+ if len(nat_gateways) > 1:
+ multi_az = self.resources.get('multi_az_required', False)
+ if not multi_az:
+ nat_savings = (len(nat_gateways) - 1) * 45 # $45/month per NAT Gateway
+ savings += nat_savings
+ self.recommendations.append({
+ 'service': 'NAT Gateway',
+ 'type': 'Resource Consolidation',
+ 'issue': f'{len(nat_gateways)} NAT Gateways deployed (multi-AZ not required)',
+ 'recommendation': 'Use single NAT Gateway in dev/staging, or consider VPC endpoints for AWS services',
+ 'potential_savings': nat_savings,
+ 'priority': 'high'
+ })
+
+ # Check for VPC endpoints opportunity
+ if not self.resources.get('vpc_endpoints', []):
+ s3_data_transfer = self.resources.get('s3_data_transfer_gb', 0)
+ if s3_data_transfer > 100:
+ endpoint_savings = s3_data_transfer * 0.09 * 0.5 # Save 50% of data transfer costs
+ savings += endpoint_savings
+ self.recommendations.append({
+ 'service': 'VPC',
+ 'type': 'VPC Endpoints',
+ 'issue': 'High S3 data transfer without VPC endpoints',
+ 'recommendation': 'Create VPC endpoints for S3 and DynamoDB to avoid NAT Gateway costs',
+ 'potential_savings': endpoint_savings,
+ 'priority': 'medium'
+ })
+
+ return savings
+
+ def _analyze_general_optimizations(self) -> float:
+ """General AWS cost optimizations."""
+ savings = 0.0
+
+ # Check for CloudWatch Logs retention
+ log_groups = self.resources.get('cloudwatch_log_groups', [])
+ for log in log_groups:
+ if log.get('retention_days', 1) == -1: # Never expire
+ log_size_gb = log.get('size_gb', 1)
+ retention_savings = log_size_gb * 0.50 * 0.7 # 70% savings with 7-day retention
+ savings += retention_savings
+ self.recommendations.append({
+ 'service': 'CloudWatch Logs',
+ 'type': 'Retention Policy',
+ 'issue': f'Log group {log.get("name", "unknown")} has infinite retention',
+ 'recommendation': 'Set retention to 7 days for non-compliance logs, 30 days for production',
+ 'potential_savings': retention_savings,
+ 'priority': 'low'
+ })
+
+ # Check for unused Elastic IPs
+ elastic_ips = self.resources.get('elastic_ips', [])
+ unattached = sum(1 for eip in elastic_ips if not eip.get('attached', True))
+ if unattached > 0:
+ eip_savings = unattached * 3.65 # $0.005/hour = $3.65/month
+ savings += eip_savings
+ self.recommendations.append({
+ 'service': 'EC2',
+ 'type': 'Unused Resources',
+ 'issue': f'{unattached} unattached Elastic IPs',
+ 'recommendation': 'Release unused Elastic IPs to avoid hourly charges',
+ 'potential_savings': eip_savings,
+ 'priority': 'high'
+ })
+
+ # Budget alerts
+ if not self.resources.get('has_budget_alerts', False):
+ self.recommendations.append({
+ 'service': 'AWS Budgets',
+ 'type': 'Cost Monitoring',
+ 'issue': 'No budget alerts configured',
+ 'recommendation': 'Set up AWS Budgets with alerts at 50%, 80%, 100% of monthly budget',
+ 'potential_savings': 0,
+ 'priority': 'high'
+ })
+
+ # Cost Explorer recommendations
+ if not self.resources.get('has_cost_explorer', False):
+ self.recommendations.append({
+ 'service': 'Cost Management',
+ 'type': 'Visibility',
+ 'issue': 'Cost Explorer not enabled',
+ 'recommendation': 'Enable AWS Cost Explorer to track spending patterns and identify anomalies',
+ 'potential_savings': 0,
+ 'priority': 'medium'
+ })
+
+ return savings
+
+ def _prioritize_recommendations(self) -> List[Dict[str, Any]]:
+ """Get top priority recommendations."""
+ high_priority = [r for r in self.recommendations if r['priority'] == 'high']
+ high_priority.sort(key=lambda x: x.get('potential_savings', 0), reverse=True)
+ return high_priority[:5] # Top 5 high-priority recommendations
+
+ def generate_optimization_checklist(self) -> List[Dict[str, Any]]:
+ """Generate actionable checklist for cost optimization."""
+ return [
+ {
+ 'category': 'Immediate Actions (Today)',
+ 'items': [
+ 'Release unattached Elastic IPs',
+ 'Stop idle EC2 instances',
+ 'Delete unused EBS volumes',
+ 'Set up budget alerts'
+ ]
+ },
+ {
+ 'category': 'This Week',
+ 'items': [
+ 'Implement S3 lifecycle policies',
+ 'Consolidate NAT Gateways in non-prod',
+ 'Set CloudWatch Logs retention to 7 days',
+ 'Review and rightsize EC2/RDS instances'
+ ]
+ },
+ {
+ 'category': 'This Month',
+ 'items': [
+ 'Evaluate Savings Plans or Reserved Instances',
+ 'Migrate to Aurora Serverless where applicable',
+ 'Implement VPC endpoints for S3/DynamoDB',
+ 'Switch DynamoDB tables to On-Demand if variable load'
+ ]
+ },
+ {
+ 'category': 'Ongoing',
+ 'items': [
+ 'Review Cost Explorer weekly',
+ 'Tag all resources for cost allocation',
+ 'Monitor Trusted Advisor recommendations',
+ 'Conduct monthly cost review meetings'
+ ]
+ }
+ ]
diff --git a/skills/aws-solution-architect/scripts/serverless_stack.py b/skills/aws-solution-architect/scripts/serverless_stack.py
new file mode 100644
index 00000000..65e60c5c
--- /dev/null
+++ b/skills/aws-solution-architect/scripts/serverless_stack.py
@@ -0,0 +1,663 @@
+"""
+Serverless stack generator for AWS.
+Creates CloudFormation/CDK templates for serverless applications.
+"""
+
+from typing import Dict, List, Any, Optional
+
+
+class ServerlessStackGenerator:
+ """Generate serverless application stacks."""
+
+ def __init__(self, app_name: str, requirements: Dict[str, Any]):
+ """
+ Initialize with application requirements.
+
+ Args:
+ app_name: Application name (used for resource naming)
+ requirements: Dictionary with API, database, auth requirements
+ """
+ self.app_name = app_name.lower().replace(' ', '-')
+ self.requirements = requirements
+ self.region = requirements.get('region', 'us-east-1')
+
+ def generate_cloudformation_template(self) -> str:
+ """
+ Generate CloudFormation template for serverless stack.
+
+ Returns:
+ YAML CloudFormation template as string
+ """
+ template = f"""AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: Serverless stack for {self.app_name}
+
+Parameters:
+ Environment:
+ Type: String
+ Default: dev
+ AllowedValues:
+ - dev
+ - staging
+ - production
+ Description: Deployment environment
+
+ CorsAllowedOrigins:
+ Type: String
+ Default: '*'
+ Description: CORS allowed origins for API Gateway
+
+Resources:
+ # DynamoDB Table
+ {self.app_name.replace('-', '')}Table:
+ Type: AWS::DynamoDB::Table
+ Properties:
+ TableName: !Sub '${{Environment}}-{self.app_name}-data'
+ BillingMode: PAY_PER_REQUEST
+ AttributeDefinitions:
+ - AttributeName: PK
+ AttributeType: S
+ - AttributeName: SK
+ AttributeType: S
+ KeySchema:
+ - AttributeName: PK
+ KeyType: HASH
+ - AttributeName: SK
+ KeyType: RANGE
+ PointInTimeRecoverySpecification:
+ PointInTimeRecoveryEnabled: true
+ SSESpecification:
+ SSEEnabled: true
+ StreamSpecification:
+ StreamViewType: NEW_AND_OLD_IMAGES
+ Tags:
+ - Key: Environment
+ Value: !Ref Environment
+ - Key: Application
+ Value: {self.app_name}
+
+ # Lambda Execution Role
+ LambdaExecutionRole:
+ Type: AWS::IAM::Role
+ Properties:
+ AssumeRolePolicyDocument:
+ Version: '2012-10-17'
+ Statement:
+ - Effect: Allow
+ Principal:
+ Service: lambda.amazonaws.com
+ Action: sts:AssumeRole
+ ManagedPolicyArns:
+ - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+ Policies:
+ - PolicyName: DynamoDBAccess
+ PolicyDocument:
+ Version: '2012-10-17'
+ Statement:
+ - Effect: Allow
+ Action:
+ - dynamodb:GetItem
+ - dynamodb:PutItem
+ - dynamodb:UpdateItem
+ - dynamodb:DeleteItem
+ - dynamodb:Query
+ - dynamodb:Scan
+ Resource: !GetAtt {self.app_name.replace('-', '')}Table.Arn
+
+ # Lambda Function
+ ApiFunction:
+ Type: AWS::Serverless::Function
+ Properties:
+ FunctionName: !Sub '${{Environment}}-{self.app_name}-api'
+ Handler: index.handler
+ Runtime: nodejs18.x
+ CodeUri: ./src
+ MemorySize: 512
+ Timeout: 10
+ Role: !GetAtt LambdaExecutionRole.Arn
+ Environment:
+ Variables:
+ TABLE_NAME: !Ref {self.app_name.replace('-', '')}Table
+ ENVIRONMENT: !Ref Environment
+ Events:
+ ApiEvent:
+ Type: Api
+ Properties:
+ Path: /{{proxy+}}
+ Method: ANY
+ RestApiId: !Ref ApiGateway
+ Tags:
+ Environment: !Ref Environment
+ Application: {self.app_name}
+
+ # API Gateway
+ ApiGateway:
+ Type: AWS::Serverless::Api
+ Properties:
+ Name: !Sub '${{Environment}}-{self.app_name}-api'
+ StageName: !Ref Environment
+ Cors:
+ AllowMethods: "'GET,POST,PUT,DELETE,OPTIONS'"
+ AllowHeaders: "'Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token'"
+ AllowOrigin: !Sub "'${{CorsAllowedOrigins}}'"
+ Auth:
+ DefaultAuthorizer: CognitoAuthorizer
+ Authorizers:
+ CognitoAuthorizer:
+ UserPoolArn: !GetAtt UserPool.Arn
+ ThrottleSettings:
+ BurstLimit: 200
+ RateLimit: 100
+ Tags:
+ Environment: !Ref Environment
+ Application: {self.app_name}
+
+ # Cognito User Pool
+ UserPool:
+ Type: AWS::Cognito::UserPool
+ Properties:
+ UserPoolName: !Sub '${{Environment}}-{self.app_name}-users'
+ UsernameAttributes:
+ - email
+ AutoVerifiedAttributes:
+ - email
+ Policies:
+ PasswordPolicy:
+ MinimumLength: 8
+ RequireUppercase: true
+ RequireLowercase: true
+ RequireNumbers: true
+ RequireSymbols: false
+ MfaConfiguration: OPTIONAL
+ EnabledMfas:
+ - SOFTWARE_TOKEN_MFA
+ UserAttributeUpdateSettings:
+ AttributesRequireVerificationBeforeUpdate:
+ - email
+ Schema:
+ - Name: email
+ Required: true
+ Mutable: true
+
+ # Cognito User Pool Client
+ UserPoolClient:
+ Type: AWS::Cognito::UserPoolClient
+ Properties:
+ ClientName: !Sub '${{Environment}}-{self.app_name}-client'
+ UserPoolId: !Ref UserPool
+ GenerateSecret: false
+ RefreshTokenValidity: 30
+ AccessTokenValidity: 1
+ IdTokenValidity: 1
+ TokenValidityUnits:
+ RefreshToken: days
+ AccessToken: hours
+ IdToken: hours
+ ExplicitAuthFlows:
+ - ALLOW_USER_SRP_AUTH
+ - ALLOW_REFRESH_TOKEN_AUTH
+
+ # CloudWatch Log Group
+ ApiLogGroup:
+ Type: AWS::Logs::LogGroup
+ Properties:
+ LogGroupName: !Sub '/aws/lambda/${{Environment}}-{self.app_name}-api'
+ RetentionInDays: 7
+
+Outputs:
+ ApiUrl:
+ Description: API Gateway endpoint URL
+ Value: !Sub 'https://${{ApiGateway}}.execute-api.${{AWS::Region}}.amazonaws.com/${{Environment}}'
+ Export:
+ Name: !Sub '${{Environment}}-{self.app_name}-ApiUrl'
+
+ UserPoolId:
+ Description: Cognito User Pool ID
+ Value: !Ref UserPool
+ Export:
+ Name: !Sub '${{Environment}}-{self.app_name}-UserPoolId'
+
+ UserPoolClientId:
+ Description: Cognito User Pool Client ID
+ Value: !Ref UserPoolClient
+ Export:
+ Name: !Sub '${{Environment}}-{self.app_name}-UserPoolClientId'
+
+ TableName:
+ Description: DynamoDB Table Name
+ Value: !Ref {self.app_name.replace('-', '')}Table
+ Export:
+ Name: !Sub '${{Environment}}-{self.app_name}-TableName'
+"""
+ return template
+
+ def generate_cdk_stack(self) -> str:
+ """
+ Generate AWS CDK stack in TypeScript.
+
+ Returns:
+ CDK stack code as string
+ """
+ stack = f"""import * as cdk from 'aws-cdk-lib';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import * as cognito from 'aws-cdk-lib/aws-cognito';
+import {{ Construct }} from 'constructs';
+
+export class {self.app_name.replace('-', '').title()}Stack extends cdk.Stack {{
+ constructor(scope: Construct, id: string, props?: cdk.StackProps) {{
+ super(scope, id, props);
+
+ // DynamoDB Table
+ const table = new dynamodb.Table(this, '{self.app_name}Table', {{
+ tableName: `${{cdk.Stack.of(this).stackName}}-data`,
+ partitionKey: {{ name: 'PK', type: dynamodb.AttributeType.STRING }},
+ sortKey: {{ name: 'SK', type: dynamodb.AttributeType.STRING }},
+ billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+ encryption: dynamodb.TableEncryption.AWS_MANAGED,
+ pointInTimeRecovery: true,
+ stream: dynamodb.StreamViewType.NEW_AND_OLD_IMAGES,
+ removalPolicy: cdk.RemovalPolicy.RETAIN,
+ }});
+
+ // Cognito User Pool
+ const userPool = new cognito.UserPool(this, '{self.app_name}UserPool', {{
+ userPoolName: `${{cdk.Stack.of(this).stackName}}-users`,
+ selfSignUpEnabled: true,
+ signInAliases: {{ email: true }},
+ autoVerify: {{ email: true }},
+ passwordPolicy: {{
+ minLength: 8,
+ requireLowercase: true,
+ requireUppercase: true,
+ requireDigits: true,
+ requireSymbols: false,
+ }},
+ mfa: cognito.Mfa.OPTIONAL,
+ mfaSecondFactor: {{
+ sms: false,
+ otp: true,
+ }},
+ removalPolicy: cdk.RemovalPolicy.RETAIN,
+ }});
+
+ const userPoolClient = userPool.addClient('{self.app_name}Client', {{
+ authFlows: {{
+ userSrp: true,
+ }},
+ accessTokenValidity: cdk.Duration.hours(1),
+ refreshTokenValidity: cdk.Duration.days(30),
+ }});
+
+ // Lambda Function
+ const apiFunction = new lambda.Function(this, '{self.app_name}ApiFunction', {{
+ functionName: `${{cdk.Stack.of(this).stackName}}-api`,
+ runtime: lambda.Runtime.NODEJS_18_X,
+ handler: 'index.handler',
+ code: lambda.Code.fromAsset('./src'),
+ memorySize: 512,
+ timeout: cdk.Duration.seconds(10),
+ environment: {{
+ TABLE_NAME: table.tableName,
+ USER_POOL_ID: userPool.userPoolId,
+ }},
+ logRetention: 7, // days
+ }});
+
+ // Grant Lambda permissions to DynamoDB
+ table.grantReadWriteData(apiFunction);
+
+ // API Gateway
+ const api = new apigateway.RestApi(this, '{self.app_name}Api', {{
+ restApiName: `${{cdk.Stack.of(this).stackName}}-api`,
+ description: 'API for {self.app_name}',
+ defaultCorsPreflightOptions: {{
+ allowOrigins: apigateway.Cors.ALL_ORIGINS,
+ allowMethods: apigateway.Cors.ALL_METHODS,
+ allowHeaders: ['Content-Type', 'Authorization'],
+ }},
+ deployOptions: {{
+ stageName: 'prod',
+ throttlingRateLimit: 100,
+ throttlingBurstLimit: 200,
+ metricsEnabled: true,
+ loggingLevel: apigateway.MethodLoggingLevel.INFO,
+ }},
+ }});
+
+ // Cognito Authorizer
+ const authorizer = new apigateway.CognitoUserPoolsAuthorizer(this, 'ApiAuthorizer', {{
+ cognitoUserPools: [userPool],
+ }});
+
+ // API Integration
+ const integration = new apigateway.LambdaIntegration(apiFunction);
+
+ // Add proxy resource (/{{proxy+}})
+ const proxyResource = api.root.addProxy({{
+ defaultIntegration: integration,
+ anyMethod: true,
+ defaultMethodOptions: {{
+ authorizer: authorizer,
+ authorizationType: apigateway.AuthorizationType.COGNITO,
+ }},
+ }});
+
+ // Outputs
+ new cdk.CfnOutput(this, 'ApiUrl', {{
+ value: api.url,
+ description: 'API Gateway URL',
+ }});
+
+ new cdk.CfnOutput(this, 'UserPoolId', {{
+ value: userPool.userPoolId,
+ description: 'Cognito User Pool ID',
+ }});
+
+ new cdk.CfnOutput(this, 'UserPoolClientId', {{
+ value: userPoolClient.userPoolClientId,
+ description: 'Cognito User Pool Client ID',
+ }});
+
+ new cdk.CfnOutput(this, 'TableName', {{
+ value: table.tableName,
+ description: 'DynamoDB Table Name',
+ }});
+ }}
+}}
+"""
+ return stack
+
+ def generate_terraform_configuration(self) -> str:
+ """
+ Generate Terraform configuration for serverless stack.
+
+ Returns:
+ Terraform HCL configuration as string
+ """
+ terraform = f"""terraform {{
+ required_version = ">= 1.0"
+ required_providers {{
+ aws = {{
+ source = "hashicorp/aws"
+ version = "~> 5.0"
+ }}
+ }}
+}}
+
+provider "aws" {{
+ region = var.aws_region
+}}
+
+variable "aws_region" {{
+ description = "AWS region"
+ type = string
+ default = "{self.region}"
+}}
+
+variable "environment" {{
+ description = "Environment name"
+ type = string
+ default = "dev"
+}}
+
+variable "app_name" {{
+ description = "Application name"
+ type = string
+ default = "{self.app_name}"
+}}
+
+# DynamoDB Table
+resource "aws_dynamodb_table" "main" {{
+ name = "${{var.environment}}-${{var.app_name}}-data"
+ billing_mode = "PAY_PER_REQUEST"
+ hash_key = "PK"
+ range_key = "SK"
+
+ attribute {{
+ name = "PK"
+ type = "S"
+ }}
+
+ attribute {{
+ name = "SK"
+ type = "S"
+ }}
+
+ server_side_encryption {{
+ enabled = true
+ }}
+
+ point_in_time_recovery {{
+ enabled = true
+ }}
+
+ stream_enabled = true
+ stream_view_type = "NEW_AND_OLD_IMAGES"
+
+ tags = {{
+ Environment = var.environment
+ Application = var.app_name
+ }}
+}}
+
+# Cognito User Pool
+resource "aws_cognito_user_pool" "main" {{
+ name = "${{var.environment}}-${{var.app_name}}-users"
+
+ username_attributes = ["email"]
+ auto_verified_attributes = ["email"]
+
+ password_policy {{
+ minimum_length = 8
+ require_lowercase = true
+ require_numbers = true
+ require_uppercase = true
+ require_symbols = false
+ }}
+
+ mfa_configuration = "OPTIONAL"
+
+ software_token_mfa_configuration {{
+ enabled = true
+ }}
+
+ schema {{
+ name = "email"
+ attribute_data_type = "String"
+ required = true
+ mutable = true
+ }}
+
+ tags = {{
+ Environment = var.environment
+ Application = var.app_name
+ }}
+}}
+
+resource "aws_cognito_user_pool_client" "main" {{
+ name = "${{var.environment}}-${{var.app_name}}-client"
+ user_pool_id = aws_cognito_user_pool.main.id
+
+ generate_secret = false
+
+ explicit_auth_flows = [
+ "ALLOW_USER_SRP_AUTH",
+ "ALLOW_REFRESH_TOKEN_AUTH"
+ ]
+
+ refresh_token_validity = 30
+ access_token_validity = 1
+ id_token_validity = 1
+
+ token_validity_units {{
+ refresh_token = "days"
+ access_token = "hours"
+ id_token = "hours"
+ }}
+}}
+
+# IAM Role for Lambda
+resource "aws_iam_role" "lambda" {{
+ name = "${{var.environment}}-${{var.app_name}}-lambda-role"
+
+ assume_role_policy = jsonencode({{
+ Version = "2012-10-17"
+ Statement = [{{
+ Action = "sts:AssumeRole"
+ Effect = "Allow"
+ Principal = {{
+ Service = "lambda.amazonaws.com"
+ }}
+ }}]
+ }})
+
+ tags = {{
+ Environment = var.environment
+ Application = var.app_name
+ }}
+}}
+
+resource "aws_iam_role_policy_attachment" "lambda_basic" {{
+ role = aws_iam_role.lambda.name
+ policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}}
+
+resource "aws_iam_role_policy" "dynamodb" {{
+ name = "dynamodb-access"
+ role = aws_iam_role.lambda.id
+
+ policy = jsonencode({{
+ Version = "2012-10-17"
+ Statement = [{{
+ Effect = "Allow"
+ Action = [
+ "dynamodb:GetItem",
+ "dynamodb:PutItem",
+ "dynamodb:UpdateItem",
+ "dynamodb:DeleteItem",
+ "dynamodb:Query",
+ "dynamodb:Scan"
+ ]
+ Resource = aws_dynamodb_table.main.arn
+ }}]
+ }})
+}}
+
+# Lambda Function
+resource "aws_lambda_function" "api" {{
+ filename = "lambda.zip"
+ function_name = "${{var.environment}}-${{var.app_name}}-api"
+ role = aws_iam_role.lambda.arn
+ handler = "index.handler"
+ runtime = "nodejs18.x"
+ memory_size = 512
+ timeout = 10
+
+ environment {{
+ variables = {{
+ TABLE_NAME = aws_dynamodb_table.main.name
+ USER_POOL_ID = aws_cognito_user_pool.main.id
+ ENVIRONMENT = var.environment
+ }}
+ }}
+
+ tags = {{
+ Environment = var.environment
+ Application = var.app_name
+ }}
+}}
+
+# CloudWatch Log Group
+resource "aws_cloudwatch_log_group" "lambda" {{
+ name = "/aws/lambda/${{aws_lambda_function.api.function_name}}"
+ retention_in_days = 7
+
+ tags = {{
+ Environment = var.environment
+ Application = var.app_name
+ }}
+}}
+
+# API Gateway
+resource "aws_api_gateway_rest_api" "main" {{
+ name = "${{var.environment}}-${{var.app_name}}-api"
+ description = "API for ${{var.app_name}}"
+
+ tags = {{
+ Environment = var.environment
+ Application = var.app_name
+ }}
+}}
+
+resource "aws_api_gateway_authorizer" "cognito" {{
+ name = "cognito-authorizer"
+ rest_api_id = aws_api_gateway_rest_api.main.id
+ type = "COGNITO_USER_POOLS"
+ provider_arns = [aws_cognito_user_pool.main.arn]
+}}
+
+resource "aws_api_gateway_resource" "proxy" {{
+ rest_api_id = aws_api_gateway_rest_api.main.id
+ parent_id = aws_api_gateway_rest_api.main.root_resource_id
+ path_part = "{{proxy+}}"
+}}
+
+resource "aws_api_gateway_method" "proxy" {{
+ rest_api_id = aws_api_gateway_rest_api.main.id
+ resource_id = aws_api_gateway_resource.proxy.id
+ http_method = "ANY"
+ authorization = "COGNITO_USER_POOLS"
+ authorizer_id = aws_api_gateway_authorizer.cognito.id
+}}
+
+resource "aws_api_gateway_integration" "lambda" {{
+ rest_api_id = aws_api_gateway_rest_api.main.id
+ resource_id = aws_api_gateway_resource.proxy.id
+ http_method = aws_api_gateway_method.proxy.http_method
+
+ integration_http_method = "POST"
+ type = "AWS_PROXY"
+ uri = aws_lambda_function.api.invoke_arn
+}}
+
+resource "aws_lambda_permission" "apigw" {{
+ statement_id = "AllowAPIGatewayInvoke"
+ action = "lambda:InvokeFunction"
+ function_name = aws_lambda_function.api.function_name
+ principal = "apigateway.amazonaws.com"
+ source_arn = "${{aws_api_gateway_rest_api.main.execution_arn}}/*/*"
+}}
+
+resource "aws_api_gateway_deployment" "main" {{
+ depends_on = [
+ aws_api_gateway_integration.lambda
+ ]
+
+ rest_api_id = aws_api_gateway_rest_api.main.id
+ stage_name = var.environment
+}}
+
+# Outputs
+output "api_url" {{
+ description = "API Gateway URL"
+ value = aws_api_gateway_deployment.main.invoke_url
+}}
+
+output "user_pool_id" {{
+ description = "Cognito User Pool ID"
+ value = aws_cognito_user_pool.main.id
+}}
+
+output "user_pool_client_id" {{
+ description = "Cognito User Pool Client ID"
+ value = aws_cognito_user_pool_client.main.id
+}}
+
+output "table_name" {{
+ description = "DynamoDB Table Name"
+ value = aws_dynamodb_table.main.name
+}}
+"""
+ return terraform
diff --git a/skills/bird/SKILL.md b/skills/bird/SKILL.md
new file mode 100644
index 00000000..f4de65d1
--- /dev/null
+++ b/skills/bird/SKILL.md
@@ -0,0 +1,25 @@
+---
+name: bird
+description: X/Twitter CLI for reading, searching, and posting via cookies or Sweetistics.
+homepage: https://bird.fast
+metadata: {"clawdbot":{"emoji":"🐦","requires":{"bins":["bird"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/bird","bins":["bird"],"label":"Install bird (brew)"}]}}
+---
+
+# bird
+
+Use `bird` to read/search X and post tweets/replies.
+
+Quick start
+- `bird whoami`
+- `bird read `
+- `bird thread `
+- `bird search "query" -n 5`
+
+Posting (confirm with user first)
+- `bird tweet "text"`
+- `bird reply "text"`
+
+Auth sources
+- Browser cookies (default: Firefox/Chrome)
+- Sweetistics API: set `SWEETISTICS_API_KEY` or use `--engine sweetistics`
+- Check sources: `bird check`
diff --git a/skills/bird/_meta.json b/skills/bird/_meta.json
new file mode 100644
index 00000000..e9a4bc5a
--- /dev/null
+++ b/skills/bird/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "steipete",
+ "slug": "bird",
+ "displayName": "Bird",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1767542738213,
+ "commit": "https://github.com/clawdbot/skills/commit/563ff75c663bb948997195461ff2a2148a56b2bb"
+ },
+ "history": []
+}
diff --git a/skills/board-deck-builder/SKILL.md b/skills/board-deck-builder/SKILL.md
new file mode 100644
index 00000000..734a68ab
--- /dev/null
+++ b/skills/board-deck-builder/SKILL.md
@@ -0,0 +1,183 @@
+---
+name: "board-deck-builder"
+description: "Assembles comprehensive board and investor update decks by pulling perspectives from all C-suite roles. Use when preparing board meetings, investor updates, quarterly business reviews, or fundraising narratives. Covers structure, narrative framework, bad news delivery, and common mistakes."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: board-governance
+ updated: 2026-03-05
+ frameworks: deck-frameworks, board-deck-template
+---
+
+# Board Deck Builder
+
+Build board decks that tell a story — not just show data. Every section has an owner, a narrative, and a "so what."
+
+## Keywords
+board deck, investor update, board meeting, board pack, investor relations, quarterly review, board presentation, fundraising deck, investor deck, board narrative, QBR, quarterly business review
+
+## Quick Start
+
+```
+/board-deck [quarterly|monthly|fundraising] [stage: seed|seriesA|seriesB]
+```
+
+Provide available metrics. The builder fills gaps with explicit placeholders — never invents numbers.
+
+## Deck Structure (Standard Order)
+
+Every section follows: **Headline → Data → Narrative → Ask/Next**
+
+### 1. Executive Summary (CEO)
+**3 sentences. No more.**
+- Sentence 1: State of the business (where we are)
+- Sentence 2: Biggest thing that happened this period
+- Sentence 3: Where we're going next quarter
+
+*Bad:* "We had a good quarter with lots of progress across all areas."
+*Good:* "We closed Q3 at $2.4M ARR (+22% QoQ), signed our largest enterprise contract, and enter Q4 with 14-month runway. The strategic shift to mid-market is working — ACV up 40% and sales cycle down 3 weeks. Q4 priority: close the $3M Series A and hit $2.8M ARR."
+
+### 2. Key Metrics Dashboard (COO)
+**6-8 metrics max. Use a table.**
+
+| Metric | This Period | Last Period | Target | Status |
+|--------|-------------|-------------|--------|--------|
+| ARR | $2.4M | $1.97M | $2.3M | ✅ |
+| MoM growth | 8.1% | 7.2% | 7.5% | ✅ |
+| Burn multiple | 1.8x | 2.1x | <2x | ✅ |
+| NRR | 112% | 108% | >110% | ✅ |
+| CAC payback | 11 months | 14 months | <12 months | ✅ |
+| Headcount | 24 | 21 | 25 | 🟡 |
+
+Pick metrics the board actually tracks. Swap out anything they've said they don't care about.
+
+### 3. Financial Update (CFO)
+- P&L summary: Revenue, COGS, Gross margin, OpEx, Net burn
+- Cash position and runway (months)
+- Burn multiple trend (3-quarter view)
+- Variance to plan (what was different and why)
+- Forecast update for next quarter
+
+**One sentence on each variance.** Boards hate "revenue was below target" with no explanation. Say why.
+
+### 4. Revenue & Pipeline (CRO)
+- ARR waterfall: starting → new → expansion → churn → ending
+- NRR and logo churn rates
+- Pipeline by stage (in $, not just count)
+- Forecast: next quarter with confidence level
+- Top 3 deals: name/amount/close date/risk
+
+**The forecast must have a confidence level.** "We expect $2.8M" is weak. "High confidence $2.6M, upside to $2.9M if two late-stage deals close" is useful.
+
+### 5. Product Update (CPO)
+- Shipped this quarter: 3-5 bullets, user impact for each
+- Shipping next quarter: 3-5 bullets with target dates
+- PMF signal: NPS trend, DAU/MAU ratio, feature adoption
+- One key learning from customer research
+
+**No feature lists.** Only features with evidence of user impact.
+
+### 6. Growth & Marketing (CMO)
+- CAC by channel (table)
+- Pipeline contribution by channel ($)
+- Brand/awareness metrics relevant to stage (traffic, share of voice)
+- What's working, what's being cut, what's being tested
+
+### 7. Engineering & Technical (CTO)
+- Delivery velocity trend (last 4 quarters)
+- Tech debt ratio and plan
+- Infrastructure: uptime, incidents, cost trend
+- Security posture (one line, flag anything pending)
+
+**Keep this short unless there's a material issue.** Boards don't need sprint details.
+
+### 8. Team & People (CHRO)
+- Headcount: actual vs plan
+- Hiring: offers out, pipeline, time-to-fill trend
+- Attrition: regrettable vs non-regrettable
+- Engagement: last survey score, trend
+- Key hires this quarter, key open roles
+
+### 9. Risk & Security (CISO)
+- Security posture: status of critical controls
+- Compliance: certifications in progress, deadlines
+- Incidents this quarter (if any): impact, resolution, prevention
+- Top 3 risks and mitigation status
+
+### 10. Strategic Outlook (CEO)
+- Next quarter priorities: 3-5 items, ranked
+- Key decisions needed from the board
+- Asks: budget, introductions, advice, votes
+
+**The "asks" slide is the most important.** Be specific. "We'd like 3 warm introductions to CFOs at Series B companies" beats "any help would be appreciated."
+
+### 11. Appendix
+- Detailed financial model
+- Full pipeline data
+- Cohort retention charts
+- Customer case studies
+- Detailed headcount breakdown
+
+---
+
+## Narrative Framework
+
+Boards see 10+ decks per quarter. Yours needs a through-line.
+
+**The 4-Act Structure:**
+1. **Where we said we'd be** (last quarter's targets)
+2. **Where we actually are** (honest assessment)
+3. **Why the gap exists** (one cause per variance, not excuses)
+4. **What we're doing about it** (specific, dated actions)
+
+This works for good news AND bad news. It's credible because it acknowledges reality.
+
+**Opening frame:** Start with the one thing that matters most — the board should know the key message by slide 3, not slide 30.
+
+---
+
+## Delivering Bad News
+
+Never bury it. Boards find out eventually. Finding out late makes it worse.
+
+**Framework:**
+1. **State it plainly** — "We missed Q3 ARR target by $300K (12% gap)"
+2. **Own the cause** — "Primary driver was longer-than-expected sales cycle in enterprise segment"
+3. **Show you understand it** — "We analyzed 8 lost/stalled deals; the pattern is X"
+4. **Present the fix** — "We've made 3 changes: [specific, dated changes]"
+5. **Update the forecast** — "Revised Q4 target is $2.6M; here's the bottom-up build"
+
+**What NOT to do:**
+- Don't lead with good news to soften bad news — boards notice and distrust the framing
+- Don't explain without owning — "market conditions" is not a cause, it's a context
+- Don't present a fix without data behind it
+- Don't show a revised forecast without showing your assumptions
+
+---
+
+## Common Board Deck Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Too many slides (>25) | Cut ruthlessly — if you can't explain it in the room, the slide is wrong |
+| Metrics without targets | Every metric needs a target and a status |
+| No narrative | Data without story forces boards to draw their own conclusions |
+| Burying bad news | Lead with it, own it, fix it |
+| Vague asks | Specific, actionable, person-assigned asks only |
+| No variance explanation | Every gap from target needs one-sentence cause |
+| Stale appendix | Appendix is only useful if it's current |
+| Designing for the reader, not the room | Decks are presented — they must work spoken aloud |
+
+---
+
+## Cadence Notes
+
+**Quarterly (standard):** Full deck, all sections, 20-30 slides. Sent 48 hours in advance.
+**Monthly (for early-stage):** Condensed — metrics dashboard, financials, pipeline, top risks. 8-12 slides.
+**Fundraising:** Opens with market/vision, closes with ask. See `references/deck-frameworks.md` for Sequoia format.
+
+## References
+- `references/deck-frameworks.md` — SaaS board pack format, Sequoia structure, investor tailoring
+- `templates/board-deck-template.md` — fill-in template for complete board decks
diff --git a/skills/board-deck-builder/_meta.json b/skills/board-deck-builder/_meta.json
new file mode 100644
index 00000000..20b59cf3
--- /dev/null
+++ b/skills/board-deck-builder/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "board-deck-builder",
+ "displayName": "Board Deck Builder",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773171095500,
+ "commit": "https://github.com/openclaw/skills/commit/3661f906c1208889cf6b519a58249b284d4c6164"
+ },
+ "history": [
+ {
+ "version": "1.0.0",
+ "publishedAt": 1772750840163,
+ "commit": "https://github.com/openclaw/skills/commit/c0fd9db1ac272a9fe15e14f3054e1e69fed028f6"
+ }
+ ]
+}
diff --git a/skills/board-deck-builder/references/deck-frameworks.md b/skills/board-deck-builder/references/deck-frameworks.md
new file mode 100644
index 00000000..1b11c720
--- /dev/null
+++ b/skills/board-deck-builder/references/deck-frameworks.md
@@ -0,0 +1,184 @@
+# Board Deck Frameworks
+
+## The SaaS Board Pack (Christoph Janz / Point Nine Style)
+
+Point Nine's board pack format became the de facto standard for early-stage SaaS. Core principle: **the numbers tell the story; the narrative explains the numbers.**
+
+### Required Metrics (non-negotiable for SaaS boards)
+- **ARR** (not MRR — boards think annually)
+- **MoM / QoQ growth rate**
+- **NRR (Net Revenue Retention)** — the single most important SaaS metric
+- **Gross margin** — typically 60-80% SaaS; <60% is a flag
+- **CAC payback period** — months to recover customer acquisition cost
+- **Burn multiple** = net burn / net new ARR; <2x is good, >3x is a problem
+- **Runway** — months at current burn
+
+### Point Nine Benchmark Targets (Series A SaaS)
+| Metric | Good | Great | Warning |
+|--------|------|-------|---------|
+| MoM growth | 10-15% | >20% | <7% |
+| NRR | >110% | >130% | <100% |
+| Gross margin | >65% | >75% | <60% |
+| CAC payback | <18 months | <12 months | >24 months |
+| Burn multiple | <2x | <1.5x | >3x |
+| Logo churn | <10%/yr | <5%/yr | >15%/yr |
+
+### SaaS ARR Waterfall (Christoph Janz Format)
+Show this every quarter:
+```
+Starting ARR: $1,970,000
++ New ARR: +$480,000 (new logos)
++ Expansion ARR: +$120,000 (upsells/cross-sells)
+- Churned ARR: -$90,000 (cancellations)
+- Contraction ARR: -$35,000 (downgrades)
+= Ending ARR: $2,445,000
+```
+NRR = (Ending - New) / Starting = ($1,965K) / ($1,970K) = 99.7% ← flag this
+
+---
+
+## Sequoia Board Deck Structure
+
+Sequoia's canonical deck (used for both fundraising and board updates):
+
+1. **Company Purpose** — one sentence, the existential "why"
+2. **The Problem** — pain, size, who has it
+3. **The Solution** — what you do, how it's different
+4. **Why Now** — market timing, tailwinds, enabling factors
+5. **Market Size** — TAM/SAM/SOM with methodology
+6. **Business Model** — how you make money
+7. **Traction** — proof it's working (growth, retention, logos)
+8. **Team** — why you're the ones to win this
+9. **Financials** — 3-year model, current metrics
+10. **The Ask** — amount, use of funds, milestones to next round
+
+**For ongoing board updates:** Swap 1-5 (context) for "State of the Business" and "Last Quarter vs Plan." Boards know the company — skip the pitch.
+
+---
+
+## Investor-Specific Tailoring
+
+### What Different Investor Types Care About
+
+**Early-stage VCs (Seed, A):**
+- Growth rate above all else
+- NRR — "does the product retain?"
+- Founder-market fit narrative
+- Milestone achievement vs last board meeting
+
+**Growth-stage VCs (B, C):**
+- Capital efficiency (burn multiple, CAC payback)
+- GTM repeatability — can you hire 10 AEs and have it work?
+- Market leadership signals
+- Path to profitability (even if years away)
+
+**Strategic investors:**
+- Synergies with their portfolio/business
+- Technology differentiation
+- Partnership potential
+
+**Angels:**
+- Team above all
+- Personal conviction in the thesis
+- Exit scenarios
+
+### Tailoring the Narrative
+- If you're ahead of plan: "Here's why, and here's how we'll sustain it"
+- If you're behind plan: "Here's why, here's what we've learned, here's the new plan"
+- If the plan was wrong: "The assumption that was wrong, what we know now, updated thesis"
+
+Never pretend the plan was right when it wasn't. Board members have memories and models.
+
+---
+
+## How to Present Bad News
+
+Boards have seen everything. What loses credibility isn't bad results — it's bad framing.
+
+### The Credibility Formula
+1. **Lead with the headline** — "We missed ARR target by 18%"
+2. **Quantify the gap** — absolute and percentage
+3. **Diagnose the cause** (one primary, max two secondary)
+4. **Show your work** — "We analyzed 12 churned/stalled deals and found..."
+5. **Present the fix** — specific, dated, owned by a name
+6. **Update the forecast** — bottom-up rebuild, not wishful thinking
+7. **Flag the risk** — "If X doesn't close, here's the contingency"
+
+### What "Showing Your Work" Looks Like
+Bad: "Sales cycle was longer than expected."
+Good: "Sales cycle stretched from 45 to 72 days. Root cause: new legal review requirement at enterprise accounts, triggered by our SOC 2 Type II gap. Fix: SOC 2 audit underway (target: Dec 15), and we've pre-built contract language to accelerate review. Impact: estimated 3 stalled deals ($420K ARR) unblock in Q4."
+
+### Scenarios and How to Handle Each
+| Scenario | Frame |
+|----------|-------|
+| Missed revenue target | Lead with it; diagnose cause; bottom-up revised forecast |
+| Key customer churned | Announce it; explain why; show retention analysis of remaining accounts |
+| Key exec left | Announce it; show succession/coverage plan; don't overpromise the replacement timeline |
+| Burn accelerated | Show P&L detail; explain what drove it; adjust runway projection; plan to fix |
+| Market headwinds | Acknowledge; show relative performance vs peers; pivot if needed |
+| Fundraise delayed | Runway impact; bridge options; revised timeline |
+
+---
+
+## Appendix Data That Boards Actually Use
+
+Boards use the appendix for due diligence, not during the meeting. Include:
+
+**Financial:**
+- Full P&L (monthly for last 4 quarters)
+- Cash flow statement
+- 3-year model with assumptions
+- Unit economics by cohort
+
+**Revenue:**
+- Customer list by ARR (anonymized or full, per board agreement)
+- Pipeline detail by deal
+- Cohort analysis (NRR by cohort vintage)
+- Churn analysis: when, why, segment
+
+**Product:**
+- Feature adoption rates
+- NPS score distribution and trend
+- DAU/MAU by segment
+
+**Team:**
+- Org chart
+- Full headcount list with fully loaded costs
+- Open reqs with priority ranking
+
+**One rule:** If the appendix is more than 20 slides, you have too much. Boards won't read it.
+
+---
+
+## Quarterly vs Monthly Board Meetings
+
+### Quarterly (Series A+)
+- Full board pack, all sections
+- 2 hours: 30 min pre-read, 90 min discussion
+- Voting items at end
+- Sent 48 hours before (72 hours preferred)
+- Add 1-2 "deep dive" topics beyond standard update
+
+### Monthly (Seed / High-Growth A)
+- Metrics dashboard + financials + top risks only
+- 45-60 minutes
+- Informal tone, more conversational
+- Sent 24 hours before
+- Skip slides for items where nothing changed
+
+### When to Increase Frequency
+- Approaching 6-month runway
+- Major strategic pivot
+- Fundraise in progress
+- Significant underperformance vs plan
+- M&A discussions
+
+---
+
+## Meeting Logistics (Often Overlooked)
+
+- **Pre-read requirement:** Board packs should be read before the meeting. If you're presenting slides, you're wasting time.
+- **Discussion format:** "I'll be brief on X since you've read it. Want to spend time on Y?" — respect board members' time
+- **One note-taker:** CEO's EA or COO; not the CEO (they need to be present)
+- **Follow-up within 24 hours:** Action items, voting outcomes, next meeting date
+- **Board portal vs email:** Use a board portal (Carta, Boardable, Notion) for version control and D&O protection
diff --git a/skills/board-deck-builder/templates/board-deck-template.md b/skills/board-deck-builder/templates/board-deck-template.md
new file mode 100644
index 00000000..c25324b2
--- /dev/null
+++ b/skills/board-deck-builder/templates/board-deck-template.md
@@ -0,0 +1,210 @@
+# Board Deck Template
+
+Fill in bracketed fields. Remove placeholders before sharing. Never invent numbers — use `[TBD]` if unknown.
+
+---
+
+## Slide 1: Executive Summary (CEO)
+
+**[Company Name] — Q[X] [Year] Board Update**
+
+> [One sentence: State of the business — where you are.]
+> [One sentence: The most important thing that happened this quarter.]
+> [One sentence: Where you're going next quarter and what determines success.]
+
+---
+
+## Slide 2: Key Metrics Dashboard (COO)
+
+**Quarter at a Glance**
+
+| Metric | Q[X] Actual | Q[X] Target | Q[X-1] Actual | Status |
+|--------|-------------|-------------|---------------|--------|
+| ARR | $[X]M | $[X]M | $[X]M | [✅/🟡/🔴] |
+| QoQ Growth | [X]% | [X]% | [X]% | [✅/🟡/🔴] |
+| NRR | [X]% | >[X]% | [X]% | [✅/🟡/🔴] |
+| Gross Margin | [X]% | >[X]% | [X]% | [✅/🟡/🔴] |
+| Burn Multiple | [X]x | <[X]x | [X]x | [✅/🟡/🔴] |
+| Runway | [X] months | >[X] months | [X] months | [✅/🟡/🔴] |
+| Headcount | [X] | [X] | [X] | [✅/🟡/🔴] |
+| CAC Payback | [X] months | <[X] months | [X] months | [✅/🟡/🔴] |
+
+---
+
+## Slide 3: Financial Update (CFO)
+
+**P&L Summary**
+
+| | Q[X] | Q[X-1] | QoQ |
+|--|------|--------|-----|
+| Revenue | $[X]K | $[X]K | [+/-X]% |
+| COGS | $[X]K | $[X]K | |
+| Gross Profit | $[X]K | $[X]K | |
+| Gross Margin | [X]% | [X]% | |
+| OpEx | $[X]K | $[X]K | |
+| Net Burn | $[X]K | $[X]K | |
+
+**Cash & Runway**
+- Cash on hand: $[X]M
+- Monthly burn: $[X]K
+- Runway: [X] months
+- Burn multiple: [X]x (target: <2x)
+
+**Variance to Plan**
+- Revenue: [+/-$X]K vs plan — [one sentence cause]
+- Burn: [+/-$X]K vs plan — [one sentence cause]
+
+**Q[X+1] Forecast:** $[X]M revenue, $[X]K burn — [confidence: high/medium/low]
+
+---
+
+## Slide 4: Revenue & Pipeline (CRO)
+
+**ARR Waterfall**
+```
+Starting ARR: $[X]M
++ New ARR: +$[X]K
++ Expansion ARR: +$[X]K
+- Churned ARR: -$[X]K
+- Contraction ARR: -$[X]K
+= Ending ARR: $[X]M
+```
+
+**Health Metrics**
+- NRR: [X]% | Logo churn: [X]% | Avg ACV: $[X]K
+
+**Pipeline (next 90 days)**
+| Stage | # Deals | $ Value |
+|-------|---------|---------|
+| Proposal | [X] | $[X]K |
+| Negotiation | [X] | $[X]K |
+| Verbal commit | [X] | $[X]K |
+
+**Q[X+1] Forecast:** $[X]M ARR — [one sentence confidence statement]
+
+**Top 3 Deals**
+1. [Company] — $[X]K ARR — close date [X] — risk: [one word]
+2. [Company] — $[X]K ARR — close date [X] — risk: [one word]
+3. [Company] — $[X]K ARR — close date [X] — risk: [one word]
+
+---
+
+## Slide 5: Product Update (CPO)
+
+**Shipped This Quarter**
+- [Feature/initiative] — impact: [metric or user outcome]
+- [Feature/initiative] — impact: [metric or user outcome]
+- [Feature/initiative] — impact: [metric or user outcome]
+
+**Shipping Next Quarter**
+- [Feature] — target: [date] — why it matters: [one line]
+- [Feature] — target: [date] — why it matters: [one line]
+- [Feature] — target: [date] — why it matters: [one line]
+
+**PMF Signals**
+- NPS: [X] (trend: [up/flat/down])
+- DAU/MAU: [X]%
+- Feature adoption ([key feature]): [X]%
+
+**Key Learning:** [One thing customer research taught you this quarter]
+
+---
+
+## Slide 6: Growth & Marketing (CMO)
+
+**CAC by Channel**
+| Channel | CAC | Pipeline $ | % of Total |
+|---------|-----|-----------|------------|
+| Outbound | $[X]K | $[X]K | [X]% |
+| Inbound | $[X]K | $[X]K | [X]% |
+| Partner | $[X]K | $[X]K | [X]% |
+
+**What's Working:** [One channel or initiative with data]
+**What We Cut:** [One thing, and why]
+**What We're Testing:** [One experiment running now]
+
+---
+
+## Slide 7: Engineering & Technical (CTO)
+
+**Delivery**
+- Velocity trend: [up/flat/down vs last quarter]
+- Q[X] commitments delivered: [X]% on time
+
+**Quality & Reliability**
+- P0/P1 incidents: [X] (vs [X] last quarter)
+- Uptime: [X]%
+- Infrastructure cost: $[X]K/month (trend: [up/flat/down])
+
+**Tech Debt**
+- Ratio: [X]% of roadmap allocated to debt reduction
+- Key item in progress: [description, target date]
+
+**Security:** [one line status; flag anything pending]
+
+---
+
+## Slide 8: Team & People (CHRO)
+
+**Headcount**
+- Total: [X] (vs [X] plan, [X] last quarter)
+- By function: Eng [X], Product [X], Sales [X], CS [X], G&A [X]
+
+**Hiring**
+- Hired this quarter: [X]
+- Open reqs: [X] — time-to-fill avg: [X] days
+- Offers outstanding: [X]
+
+**Retention**
+- Regrettable attrition: [X]% (annualized)
+- Engagement score: [X]/10 (trend: [up/flat/down])
+
+**Notable Hires:** [Name, role — one sentence on why they matter]
+**Key Open Roles:** [Role, priority: critical/high/medium]
+
+---
+
+## Slide 9: Risk & Security (CISO)
+
+**Compliance Status**
+| Certification | Status | Target Date |
+|--------------|--------|-------------|
+| [SOC 2 / ISO 27001 / etc.] | [In progress / Complete / Not started] | [Date] |
+
+**Security Posture:** [One line — overall status]
+
+**Incidents This Quarter:** [X] total — [description if >0]
+
+**Top Risks**
+1. [Risk] — likelihood: [H/M/L] — impact: [H/M/L] — mitigation: [one line]
+2. [Risk] — likelihood: [H/M/L] — impact: [H/M/L] — mitigation: [one line]
+3. [Risk] — likelihood: [H/M/L] — impact: [H/M/L] — mitigation: [one line]
+
+---
+
+## Slide 10: Strategic Outlook (CEO)
+
+**Q[X+1] Priorities**
+1. [Priority] — owner: [name] — success metric: [specific]
+2. [Priority] — owner: [name] — success metric: [specific]
+3. [Priority] — owner: [name] — success metric: [specific]
+
+**Asks from the Board**
+- [Specific ask: warm intro / advice / vote / resource]
+- [Specific ask]
+- [Specific ask]
+
+**Decisions Needed Today**
+- [Decision with options]: [Option A] vs [Option B] — recommendation: [A/B] — rationale: [one line]
+
+---
+
+## Appendix
+
+- A1: Full P&L (monthly, last 4 quarters)
+- A2: 3-year financial model
+- A3: Customer list / ARR breakdown
+- A4: Full pipeline by deal
+- A5: Cohort retention analysis
+- A6: Org chart + headcount detail
+- A7: [Other as relevant]
diff --git a/skills/board-meeting/SKILL.md b/skills/board-meeting/SKILL.md
new file mode 100644
index 00000000..1b1702c3
--- /dev/null
+++ b/skills/board-meeting/SKILL.md
@@ -0,0 +1,146 @@
+---
+name: "board-meeting"
+description: "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:board, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: board-protocol
+ updated: 2026-03-05
+ frameworks: 6-phase-board, two-layer-memory, independent-contributions
+---
+
+# Board Meeting Protocol
+
+Structured multi-agent deliberation that prevents groupthink, captures minority views, and produces clean, actionable decisions.
+
+## Keywords
+board meeting, executive deliberation, strategic decision, C-suite, multi-agent, /cs:board, founder review, decision extraction, independent perspectives
+
+## Invoke
+`/cs:board [topic]` — e.g. `/cs:board Should we expand to Spain in Q3?`
+
+---
+
+## The 6-Phase Protocol
+
+### PHASE 1: Context Gathering
+1. Load `memory/company-context.md`
+2. Load `memory/board-meetings/decisions.md` **(Layer 2 ONLY — never raw transcripts)**
+3. Reset session state — no bleed from previous conversations
+4. Present agenda + activated roles → wait for founder confirmation
+
+**Chief of Staff selects relevant roles** based on topic (not all 9 every time):
+| Topic | Activate |
+|-------|----------|
+| Market expansion | CEO, CMO, CFO, CRO, COO |
+| Product direction | CEO, CPO, CTO, CMO |
+| Hiring/org | CEO, CHRO, CFO, COO |
+| Pricing | CMO, CFO, CRO, CPO |
+| Technology | CTO, CPO, CFO, CISO |
+
+---
+
+### PHASE 2: Independent Contributions (ISOLATED)
+
+**No cross-pollination. Each agent runs before seeing others' outputs.**
+
+Order: Research (if needed) → CMO → CFO → CEO → CTO → COO → CHRO → CRO → CISO → CPO
+
+**Reasoning techniques:** CEO: Tree of Thought (3 futures) | CFO: Chain of Thought (show the math) | CMO: Recursion of Thought (draft→critique→refine) | CPO: First Principles | CRO: Chain of Thought (pipeline math) | COO: Step by Step (process map) | CTO: ReAct (research→analyze→act) | CISO: Risk-Based (P×I) | CHRO: Empathy + Data
+
+**Contribution format (max 5 key points, self-verified):**
+```
+## [ROLE] — [DATE]
+
+Key points (max 5):
+• [Finding] — [VERIFIED/ASSUMED] — 🟢/🟡/🔴
+• [Finding] — [VERIFIED/ASSUMED] — 🟢/🟡/🔴
+
+Recommendation: [clear position]
+Confidence: High / Medium / Low
+Source: [where the data came from]
+What would change my mind: [specific condition]
+```
+
+Each agent self-verifies before contributing: source attribution, assumption audit, confidence scoring. No untagged claims.
+
+---
+
+### PHASE 3: Critic Analysis
+Executive Mentor receives ALL Phase 2 outputs simultaneously. Role: adversarial reviewer, not synthesizer.
+
+Checklist:
+- Where did agents agree too easily? (suspicious consensus = red flag)
+- What assumptions are shared but unvalidated?
+- Who is missing from the room? (customer voice? front-line ops?)
+- What risk has nobody mentioned?
+- Which agent operated outside their domain?
+
+---
+
+### PHASE 4: Synthesis
+Chief of Staff delivers using the **Board Meeting Output** format (defined in `agent-protocol/SKILL.md`):
+- Decision Required (one sentence)
+- Perspectives (one line per contributing role)
+- Where They Agree / Where They Disagree
+- Critic's View (the uncomfortable truth)
+- Recommended Decision + Action Items (owners, deadlines)
+- Your Call (options if founder disagrees)
+
+---
+
+### PHASE 5: Human in the Loop ⏸️
+
+**Full stop. Wait for the founder.**
+
+```
+⏸️ FOUNDER REVIEW — [Paste synthesis]
+
+Options: ✅ Approve | ✏️ Modify | ❌ Reject | ❓ Ask follow-up
+```
+
+**Rules:**
+- User corrections OVERRIDE agent proposals. No pushback. No "but the CFO said..."
+- 30-min inactivity → auto-close as "pending review"
+- Reopen any time with `/cs:board resume`
+
+---
+
+### PHASE 6: Decision Extraction
+After founder approval:
+- **Layer 1:** Write full transcript → `memory/board-meetings/YYYY-MM-DD-raw.md`
+- **Layer 2:** Append approved decisions → `memory/board-meetings/decisions.md`
+- Mark rejected proposals `[DO_NOT_RESURFACE]`
+- Confirm to founder with count of decisions logged, actions tracked, flags added
+
+---
+
+## Memory Structure
+```
+memory/board-meetings/
+├── decisions.md # Layer 2 — founder-approved only (Phase 1 loads this)
+├── YYYY-MM-DD-raw.md # Layer 1 — full transcripts (never auto-loaded)
+└── archive/YYYY/ # Raw transcripts after 90 days
+```
+
+**Future meetings load Layer 2 only.** Never Layer 1. This prevents hallucinated consensus.
+
+---
+
+## Failure Mode Quick Reference
+| Failure | Fix |
+|---------|-----|
+| Groupthink (all agree) | Re-run Phase 2 isolated; force "strongest argument against" |
+| Analysis paralysis | Cap at 5 points; force recommendation even with Low confidence |
+| Bikeshedding | Log as async action item; return to main agenda |
+| Role bleed (CFO making product calls) | Critic flags; exclude from synthesis |
+| Layer contamination | Phase 1 loads decisions.md only — hard rule |
+
+---
+
+## References
+- `templates/meeting-agenda.md` — agenda format
+- `templates/meeting-minutes.md` — final output format
+- `references/meeting-facilitation.md` — conflict handling, timing, failure modes
diff --git a/skills/board-meeting/_meta.json b/skills/board-meeting/_meta.json
new file mode 100644
index 00000000..08d0d73a
--- /dev/null
+++ b/skills/board-meeting/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "board-meeting",
+ "displayName": "Board Meeting",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773171098457,
+ "commit": "https://github.com/openclaw/skills/commit/d78a48b09b43a02f8e5c11c37c54853d1239b4a7"
+ },
+ "history": [
+ {
+ "version": "1.0.0",
+ "publishedAt": 1772750815950,
+ "commit": "https://github.com/openclaw/skills/commit/653d46bdc862d85d05137f26f36b934b42121c18"
+ }
+ ]
+}
diff --git a/skills/board-meeting/references/meeting-facilitation.md b/skills/board-meeting/references/meeting-facilitation.md
new file mode 100644
index 00000000..60437d8a
--- /dev/null
+++ b/skills/board-meeting/references/meeting-facilitation.md
@@ -0,0 +1,167 @@
+# Meeting Facilitation Guide
+
+Operational playbook for running board meetings using the 6-phase protocol.
+Reference this when things go sideways — and they will.
+
+---
+
+## Keeping Phase 2 Contributions Focused
+
+**The problem:** Agents with deep domain knowledge tend to over-contribute. An unconstrained CFO can produce 1,500 words on a single agenda item. This kills the meeting.
+
+**The rules:**
+- **Hard cap: 5 key points per role.** If a role produces more than 5, Chief of Staff trims to the 5 most material.
+- **Every point must include a recommendation or stance.** Observations without positions are filler.
+- **No hedging language.** "It depends" is not a key point. "We should do X if Y, Z if not Y" is.
+- **Confidence rating required.** Forces the agent to be honest about what they actually know.
+- **"What would change my mind"** — this is the most important line in the contribution. It forces falsifiability.
+
+**How to enforce:**
+```
+Chief of Staff instruction to each role:
+"You have 5 key points maximum. Each must include a clear stance.
+End with your recommendation and what would change your mind.
+Do not read other agents' contributions before writing yours."
+```
+
+**If a contribution runs long:**
+- Trim to the 5 highest-signal points
+- Preserve the recommendation and confidence rating
+- Flag in the raw transcript: "[Trimmed for meeting — full version in raw log]"
+
+---
+
+## Handling Role Conflicts in Phase 3
+
+**What the Executive Mentor is for:** Not harmony. Not consensus. Productive friction.
+
+**Common conflict types:**
+
+### 1. Data conflict (two agents cite contradictory numbers)
+- Flag both numbers explicitly
+- Do NOT pick a winner — that's the founder's job
+- Ask: "CFO says CAC is $2,400. CRO says $1,800. These can't both be right. Which dataset are you using?"
+- Action item: Assign data reconciliation to one owner before next meeting
+
+### 2. Priority conflict (two agents want different things first)
+- Surface the underlying assumption difference
+- Example: "CMO wants to invest in brand. CFO wants to cut burn. The real question is: do we believe revenue will grow 40% next quarter?"
+- Frame as a bet, not a fight
+
+### 3. Role conflict (agent operating outside their lane)
+- CFO making product calls → flag and exclude from synthesis
+- CMO commenting on architecture → flag and exclude
+- The Executive Mentor notes: "[ROLE] contribution on [topic] is outside domain. Excluded from synthesis. Refer to [correct role]."
+- This is not an error. It's expected. Executives have opinions on everything. Only domain-relevant contributions count.
+
+### 4. False consensus (everyone agrees but nobody has evidence)
+- This is the most dangerous failure mode
+- Symptom: All Phase 2 contributions say "yes" with high confidence
+- Executive Mentor response: "Unanimous agreement on a hard question is a red flag. What evidence does each of you have? Or are you reasoning from the same assumption?"
+- Force each agreeing agent to state their independent evidence
+
+---
+
+## When to Extend vs Cut Short a Meeting
+
+**Extend when:**
+- A genuine new risk surfaces in Phase 3 that wasn't in the agenda
+- The founder asks a question that requires re-running Phase 2 for a new angle
+- A data conflict is discovered that changes the decision space entirely
+- The action items from synthesis are unclear or unowned
+
+**How to extend:** Add a new mini-Phase 2 with only the relevant roles for the new question. Don't restart the full meeting.
+
+**Cut short when:**
+- The founder has already reached a decision before Phase 4 — capture it, log it, move on
+- The agenda item is resolved in Phase 2 without genuine conflict — skip Phase 3, go straight to synthesis
+- It's a pure update meeting with no decisions required — skip Phases 2-4, go straight to action items
+
+**Never cut short:**
+- Phase 5 (founder review) — always required, always explicit
+- Phase 6 (decision extraction) — always required, even for small decisions
+
+---
+
+## Handling Founder Disagreement with All Agents
+
+This happens. The founder has context agents don't.
+
+**Protocol:**
+1. Acknowledge explicitly: "You're overriding the consensus position."
+2. Ask: "What do you know that the agents didn't factor in?" (Not to challenge — to capture.)
+3. Log the override in Layer 2 with full context:
+ ```
+ User Override: Founder rejected [consensus position] because [reason].
+ Decision: [founder's actual decision]
+ Agent recommendation: [what they said] — DO NOT RESURFACE without new data
+ ```
+4. Never push back on a founder override. Document it. Move on.
+5. If the same override happens 3+ times, flag a pattern: "You've overridden the CFO on burn rate three meetings in a row. Would you like to update the financial constraints in company-context.md?"
+
+**What NOT to do:**
+- Don't say "but the CFO said..."
+- Don't re-argue on behalf of any agent
+- Don't note it as a "controversial" decision in the minutes — it's just the decision
+
+---
+
+## Common Failure Modes
+
+### Groupthink
+**Symptom:** All agents produce similar recommendations with high confidence.
+**Cause:** Agents are inadvertently reading each other's outputs (Phase 2 isolation violated), or company-context.md contains implicit bias toward one direction.
+**Fix:** Re-run Phase 2 with explicit isolation. Ask: "Give me the strongest argument AGAINST this direction."
+
+### Analysis Paralysis
+**Symptom:** Phase 2 produces comprehensive analysis but no clear recommendation from any role.
+**Cause:** Agents are hedging. Usually happens on genuinely hard questions.
+**Fix:** Force the issue. "I need a recommendation, not an analysis. If you had to bet the company on one direction, what would it be? Confidence can be Low."
+
+### Bikeshedding
+**Symptom:** 30+ minutes spent on a detail that doesn't matter to the core decision.
+**Cause:** An easy-to-understand sub-problem attracts disproportionate attention.
+**Example:** Debating button color on a pricing page instead of the pricing strategy.
+**Fix:** Chief of Staff intervenes: "This is a sub-decision. I'm logging it as a separate action item for async resolution. Back to [main agenda item]."
+
+### Scope Creep
+**Symptom:** New agenda items keep appearing mid-meeting.
+**Cause:** Meeting surfaces real issues that feel urgent.
+**Fix:** New items go on a "parking lot" list. Addressed after the current agenda is complete or in the next meeting.
+```
+🅿️ PARKING LOT
+- [Item 1] — added by [role], will address [when]
+- [Item 2]
+```
+
+### Layer Contamination
+**Symptom:** Future meeting references a rejected proposal or a debate that was never approved.
+**Cause:** Phase 1 accidentally loaded a raw transcript instead of decisions.md.
+**Fix:** Hard rule in Phase 1: load decisions.md (Layer 2) ONLY. Never load raw transcripts. If raw context is needed, founder explicitly requests it.
+
+### Decision Amnesia
+**Symptom:** Same question debated again in a later meeting.
+**Cause:** Layer 2 decisions.md not consulted in Phase 1, or entry was too vague.
+**Fix:** Phase 1 always surfaces relevant past decisions. If a question was already decided, Chief of Staff surfaces it: "We addressed this on [DATE]. Decision was [X]. Do you want to reopen it?"
+
+### Role Fatigue
+**Symptom:** Later agents in Phase 2 (CHRO, CRO) produce weaker contributions.
+**Cause:** Context window pressure. Agents at the end of a long meeting have less capacity.
+**Fix:** For meetings with 7+ roles, split into two batches. First batch: strategic roles (CEO, CFO, CMO). Second batch: operational roles (COO, CHRO, CRO). Run Executive Mentor after all contributions.
+
+---
+
+## Meeting Health Metrics
+
+After each board meeting, score it:
+
+| Metric | Good | Bad |
+|--------|------|-----|
+| Action items produced | 3–7 | 0 or >10 |
+| Decisions with clear owners | 100% | < 80% |
+| Unresolved open questions | 1–3 | >5 |
+| Founder overrides | 0–2 | >5 (suggests context mismatch) |
+| Roles activated | 3–6 | All 9 (too many = noise) |
+| Phase 2 conflicts surfaced | At least 1 | 0 (groupthink risk) |
+
+Track these in `memory/board-meetings/meeting-health.md` over time. Pattern: if action items consistently exceed 8, meetings are too infrequent. If conflicts are consistently 0, isolation is broken.
diff --git a/skills/board-meeting/templates/meeting-agenda.md b/skills/board-meeting/templates/meeting-agenda.md
new file mode 100644
index 00000000..b491937f
--- /dev/null
+++ b/skills/board-meeting/templates/meeting-agenda.md
@@ -0,0 +1,81 @@
+# Board Meeting Agenda Template
+
+Use this to structure a board meeting before invoking `/cs:board`.
+Paste it into the conversation or save it as `memory/board-meetings/agenda-YYYY-MM-DD.md`.
+
+---
+
+## Board Meeting — [DATE]
+
+**Convened by:** [Founder name]
+**Facilitator:** Chief of Staff (Leo)
+**Duration:** [estimated, e.g., 45–90 min]
+**Status:** Draft / Confirmed
+
+---
+
+## Standing Items (always included)
+
+| Item | Owner | Time |
+|------|-------|------|
+| Layer 2 decisions review (what changed since last meeting) | Chief of Staff | 5 min |
+| Open action items from last meeting | All | 10 min |
+| Blockers requiring founder decision | All | 5 min |
+
+---
+
+## Agenda Items
+
+### Item 1: [Title]
+**Type:** Decision required / Exploration / Update
+**Lead role(s):** [e.g., CEO + CFO]
+**Context:** [1-2 sentences on why this is on the agenda now]
+**Decision needed:** [What specifically must be decided, or what question must be answered]
+**Success criteria:** [How will we know this agenda item is resolved?]
+**Relevant past decisions:** [Reference any Layer 2 entries]
+**Time box:** [e.g., 20 min]
+
+---
+
+### Item 2: [Title]
+**Type:** Decision required / Exploration / Update
+**Lead role(s):**
+**Context:**
+**Decision needed:**
+**Success criteria:**
+**Relevant past decisions:**
+**Time box:**
+
+---
+
+### Item 3: [Title]
+**Type:** Decision required / Exploration / Update
+**Lead role(s):**
+**Context:**
+**Decision needed:**
+**Success criteria:**
+**Relevant past decisions:**
+**Time box:**
+
+---
+
+## Out of Scope (explicitly excluded)
+
+List topics that might come up but are NOT on today's agenda:
+- [Topic] — defer to [date or next meeting]
+- [Topic] — owner to handle async
+
+---
+
+## Pre-Read
+
+Materials all participants should review before the meeting:
+- [ ] `memory/board-meetings/decisions.md` (Chief of Staff loads automatically)
+- [ ] [Link or filename]
+- [ ] [Link or filename]
+
+---
+
+## Notes
+
+[Any special instructions, constraints, or context for this meeting]
diff --git a/skills/board-meeting/templates/meeting-minutes.md b/skills/board-meeting/templates/meeting-minutes.md
new file mode 100644
index 00000000..bd165e6b
--- /dev/null
+++ b/skills/board-meeting/templates/meeting-minutes.md
@@ -0,0 +1,91 @@
+# Board Meeting Minutes Template
+
+This is the Layer 2 output — the founder-approved record of what was decided.
+Written by Chief of Staff after Phase 5 (founder approval).
+Appended to `memory/board-meetings/decisions.md`.
+
+Do NOT include raw agent debate here. That lives in `YYYY-MM-DD-raw.md` (Layer 1).
+
+---
+
+## Board Meeting — [DATE]
+
+**Agenda:** [Topic or meeting title]
+**Participants (roles activated):** [e.g., CEO, CFO, CMO, COO, Executive Mentor]
+**Facilitator:** Chief of Staff
+**Status:** ✅ Approved by founder / ⏸️ Pending review
+
+---
+
+## Decisions Made
+
+### Decision 1: [Title]
+**Agenda item:** [Item this decision resolves]
+**Decision:** [Exactly what was decided — one clear statement]
+**Rationale:** [Why this was chosen over alternatives, in 1-3 sentences]
+**Owner:** [Who is accountable for execution]
+**Deadline:** [Date]
+**Review date:** [When to check progress]
+**User override:** [If founder overrode agent consensus — what and why. Leave blank if not applicable.]
+
+---
+
+### Decision 2: [Title]
+**Agenda item:**
+**Decision:**
+**Rationale:**
+**Owner:**
+**Deadline:**
+**Review date:**
+**User override:**
+
+---
+
+## Action Items
+
+| # | Action | Owner | Deadline | Review Date | Status |
+|---|--------|-------|----------|-------------|--------|
+| 1 | [action] | [name/role] | [date] | [date] | Open |
+| 2 | [action] | [name/role] | [date] | [date] | Open |
+| 3 | [action] | [name/role] | [date] | [date] | Open |
+
+---
+
+## Explicitly Rejected Proposals
+
+These were considered and rejected. Do not resurface without new information.
+
+| Proposal | Rejected by | Reason | Flag |
+|----------|-------------|--------|------|
+| [Proposal text] | Founder | [reason] | [DO_NOT_RESURFACE] |
+| [Proposal text] | Consensus | [reason] | [DO_NOT_RESURFACE] |
+
+---
+
+## Open Questions (unresolved, deferred)
+
+These were not resolved in this meeting. They carry forward.
+
+1. [Question] — Owner: [who will research] — Due: [date]
+2. [Question] — Owner: — Due:
+
+---
+
+## Risk Register Updates
+
+| Risk | Probability | Impact | Owner | Mitigation | Status |
+|------|-------------|--------|-------|-----------|--------|
+| [risk] | H/M/L | H/M/L | [name] | [action] | Open |
+
+---
+
+## Next Meeting
+
+**Suggested date:** [DATE]
+**Trigger items:** [Action items with review dates that will need board discussion]
+**Pre-read:** [What to prepare]
+
+---
+
+*Minutes approved by: [Founder name] on [DATE]*
+*Raw transcript: `memory/board-meetings/[DATE]-raw.md`*
diff --git a/skills/business-growth/CLAUDE.md b/skills/business-growth/CLAUDE.md
new file mode 100644
index 00000000..2b364853
--- /dev/null
+++ b/skills/business-growth/CLAUDE.md
@@ -0,0 +1,188 @@
+# Business & Growth Skills - Claude Code Guidance
+
+This guide covers the 3 production-ready business and growth skills and their Python automation tools.
+
+## Business & Growth Skills Overview
+
+**Available Skills:**
+1. **customer-success-manager/** - Customer health scoring, churn risk analysis, expansion opportunities (3 Python tools)
+2. **sales-engineer/** - Technical discovery, RFP analysis, competitive positioning, POC planning (3 Python tools)
+3. **revenue-operations/** - Pipeline analysis, forecast accuracy, GTM efficiency metrics (3 Python tools)
+
+**Total Tools:** 9 Python automation tools, 9 knowledge bases, 19+ templates
+
+## Python Automation Tools
+
+### Customer Success Manager Tools
+
+#### 1. Health Score Calculator (`customer-success-manager/scripts/health_score_calculator.py`)
+
+**Purpose:** Multi-dimensional customer health scoring with trend analysis
+
+**Features:**
+- Weighted scoring across 4 dimensions (usage, engagement, support, relationship)
+- Red/Yellow/Green classification with configurable thresholds
+- Trend analysis comparing current vs previous period
+- Segment-aware benchmarking (Enterprise/Mid-Market/SMB)
+
+**Usage:**
+```bash
+python customer-success-manager/scripts/health_score_calculator.py customer_data.json
+python customer-success-manager/scripts/health_score_calculator.py customer_data.json --format json
+```
+
+#### 2. Churn Risk Analyzer (`customer-success-manager/scripts/churn_risk_analyzer.py`)
+
+**Purpose:** Identify at-risk accounts with intervention recommendations
+
+**Features:**
+- Risk scoring based on behavioral signals
+- Warning signal detection and categorization
+- Tier-appropriate intervention playbooks
+- Urgency-based prioritization
+
+**Usage:**
+```bash
+python customer-success-manager/scripts/churn_risk_analyzer.py customer_data.json
+python customer-success-manager/scripts/churn_risk_analyzer.py customer_data.json --format json
+```
+
+#### 3. Expansion Opportunity Scorer (`customer-success-manager/scripts/expansion_opportunity_scorer.py`)
+
+**Purpose:** Identify upsell and cross-sell opportunities
+
+**Features:**
+- Adoption depth analysis across product modules
+- Whitespace mapping for unused features
+- Revenue opportunity estimation
+- Priority ranking by effort and impact
+
+**Usage:**
+```bash
+python customer-success-manager/scripts/expansion_opportunity_scorer.py customer_data.json
+python customer-success-manager/scripts/expansion_opportunity_scorer.py customer_data.json --format json
+```
+
+### Sales Engineer Tools
+
+#### 4. RFP Response Analyzer (`sales-engineer/scripts/rfp_response_analyzer.py`)
+
+**Purpose:** Score RFP/RFI coverage and identify gaps
+
+**Features:**
+- Requirement coverage scoring (Full/Partial/Planned/Gap)
+- Effort estimation per requirement
+- Gap identification with mitigation strategies
+- Overall bid/no-bid recommendation
+
+**Usage:**
+```bash
+python sales-engineer/scripts/rfp_response_analyzer.py rfp_data.json
+python sales-engineer/scripts/rfp_response_analyzer.py rfp_data.json --format json
+```
+
+#### 5. Competitive Matrix Builder (`sales-engineer/scripts/competitive_matrix_builder.py`)
+
+**Purpose:** Generate feature comparison matrices and competitive positioning
+
+**Features:**
+- Feature-by-feature comparison matrix
+- Competitive scoring with weighted categories
+- Differentiator identification
+- Battlecard-ready output
+
+**Usage:**
+```bash
+python sales-engineer/scripts/competitive_matrix_builder.py competitive_data.json
+python sales-engineer/scripts/competitive_matrix_builder.py competitive_data.json --format json
+```
+
+#### 6. POC Planner (`sales-engineer/scripts/poc_planner.py`)
+
+**Purpose:** Plan proof-of-concept engagements
+
+**Features:**
+- Timeline estimation based on scope
+- Resource allocation planning
+- Success criteria definition
+- Evaluation scorecard generation
+
+**Usage:**
+```bash
+python sales-engineer/scripts/poc_planner.py poc_data.json
+python sales-engineer/scripts/poc_planner.py poc_data.json --format json
+```
+
+### Revenue Operations Tools
+
+#### 7. Pipeline Analyzer (`revenue-operations/scripts/pipeline_analyzer.py`)
+
+**Purpose:** Analyze sales pipeline health and velocity
+
+**Features:**
+- Coverage ratio calculation (pipeline/quota)
+- Stage conversion rate analysis
+- Sales velocity metrics (4-lever model)
+- Deal aging analysis
+
+**Usage:**
+```bash
+python revenue-operations/scripts/pipeline_analyzer.py pipeline_data.json
+python revenue-operations/scripts/pipeline_analyzer.py pipeline_data.json --format json
+```
+
+#### 8. Forecast Accuracy Tracker (`revenue-operations/scripts/forecast_accuracy_tracker.py`)
+
+**Purpose:** Measure and improve forecast accuracy
+
+**Features:**
+- MAPE (Mean Absolute Percentage Error) calculation
+- Forecast bias detection (over/under-forecasting)
+- Period-over-period trend analysis
+- Category-level accuracy breakdown
+
+**Usage:**
+```bash
+python revenue-operations/scripts/forecast_accuracy_tracker.py forecast_data.json
+python revenue-operations/scripts/forecast_accuracy_tracker.py forecast_data.json --format json
+```
+
+#### 9. GTM Efficiency Calculator (`revenue-operations/scripts/gtm_efficiency_calculator.py`)
+
+**Purpose:** Calculate go-to-market efficiency metrics
+
+**Features:**
+- Magic number calculation
+- LTV:CAC ratio analysis
+- CAC payback period
+- Burn multiple assessment
+- Industry benchmarking
+
+**Usage:**
+```bash
+python revenue-operations/scripts/gtm_efficiency_calculator.py gtm_data.json
+python revenue-operations/scripts/gtm_efficiency_calculator.py gtm_data.json --format json
+```
+
+## Quality Standards
+
+**All business & growth Python tools must:**
+- Use standard library only (no external dependencies)
+- Support both JSON and human-readable output via `--format` flag
+- Provide clear error messages for invalid input
+- Return appropriate exit codes
+- Process files locally (no API calls)
+- Include argparse CLI with `--help` support
+
+## Related Skills
+
+- **Marketing:** Content creation, demand generation -> `../marketing-skill/`
+- **Product Team:** User research, feature prioritization -> `../product-team/`
+- **C-Level:** Strategic planning -> `../c-level-advisor/`
+- **Engineering:** Technical implementation -> `../engineering-team/`
+
+---
+
+**Last Updated:** February 2026
+**Skills Deployed:** 3/3 business & growth skills production-ready
+**Total Tools:** 9 Python automation tools
diff --git a/skills/business-growth/SKILL.md b/skills/business-growth/SKILL.md
new file mode 100644
index 00000000..5f5fa1e4
--- /dev/null
+++ b/skills/business-growth/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: "business-growth-skills"
+description: "4 production-ready business and growth skills: customer success manager with health scoring and churn prediction, sales engineer with RFP analysis, revenue operations with pipeline and GTM metrics, and contract & proposal writer. Python tools included (all stdlib-only). Works with Claude Code, Codex CLI, and OpenClaw."
+version: 1.1.0
+author: Alireza Rezvani
+license: MIT
+tags:
+ - business
+ - customer-success
+ - sales
+ - revenue-operations
+ - growth
+agents:
+ - claude-code
+ - codex-cli
+ - openclaw
+---
+
+# 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
diff --git a/skills/business-growth/_meta.json b/skills/business-growth/_meta.json
new file mode 100644
index 00000000..15a27db9
--- /dev/null
+++ b/skills/business-growth/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "business-growth",
+ "displayName": "business-growth",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1773242008718,
+ "commit": "https://github.com/openclaw/skills/commit/a80e09e3416f9b3e8cfa7b87cc19e8df1801f30e"
+ },
+ "history": []
+}
diff --git a/skills/business-growth/contract-and-proposal-writer/SKILL.md b/skills/business-growth/contract-and-proposal-writer/SKILL.md
new file mode 100644
index 00000000..40b2326d
--- /dev/null
+++ b/skills/business-growth/contract-and-proposal-writer/SKILL.md
@@ -0,0 +1,423 @@
+---
+name: "contract-and-proposal-writer"
+description: "Contract & Proposal Writer"
+---
+
+# 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
diff --git a/skills/business-growth/customer-success-manager/SKILL.md b/skills/business-growth/customer-success-manager/SKILL.md
new file mode 100644
index 00000000..dc27e965
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/SKILL.md
@@ -0,0 +1,215 @@
+---
+name: "customer-success-manager"
+description: 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.
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: business-growth
+ domain: customer-success
+ updated: 2026-02-06
+ python-tools: health_score_calculator.py, churn_risk_analyzer.py, expansion_opportunity_scorer.py
+ tech-stack: customer-success, saas-metrics, health-scoring
+---
+
+# 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
diff --git a/skills/business-growth/customer-success-manager/assets/executive_business_review_template.md b/skills/business-growth/customer-success-manager/assets/executive_business_review_template.md
new file mode 100644
index 00000000..cf7ddcc4
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/assets/executive_business_review_template.md
@@ -0,0 +1,209 @@
+# Executive Business Review
+
+**Customer:** [Customer Name]
+**Date:** [Review Date]
+**Prepared for:** [Executive Name, Title]
+**Prepared by:** [CSM Name] | [VP Customer Success Name]
+**Classification:** [Strategic / Enterprise / Key Account]
+
+---
+
+## 1. Partnership Summary
+
+| Metric | Value |
+|--------|-------|
+| Partnership Duration | [X months/years] |
+| Current ARR | $[Amount] |
+| Lifetime Value to Date | $[Amount] |
+| Current Plan | [Tier] |
+| Licensed Seats | [Number] |
+| Active Seats | [Number] |
+| Health Score | [Score]/100 ([Green/Yellow/Red]) |
+| NPS Score | [Score] |
+| Renewal Date | [Date] ([X] days remaining) |
+
+---
+
+## 2. Strategic Alignment
+
+### Customer's Business Priorities (This Year)
+
+1. **[Priority 1]** -- [How our solution supports this]
+2. **[Priority 2]** -- [How our solution supports this]
+3. **[Priority 3]** -- [How our solution supports this]
+
+### Alignment Assessment
+
+| Business Priority | Our Contribution | Alignment Score |
+|-------------------|-----------------|----------------|
+| [Priority 1] | [Specific contribution] | [Strong / Moderate / Weak] |
+| [Priority 2] | [Specific contribution] | [Strong / Moderate / Weak] |
+| [Priority 3] | [Specific contribution] | [Strong / Moderate / Weak] |
+
+---
+
+## 3. Value Delivered
+
+### Quantified Business Impact
+
+| Outcome | Metric | Before | After | Business Value |
+|---------|--------|--------|-------|---------------|
+| [e.g., Operational efficiency] | [Hours saved/week] | [Baseline] | [Current] | $[Estimated value] |
+| [e.g., Revenue acceleration] | [Deal velocity] | [Baseline] | [Current] | $[Estimated value] |
+| [e.g., Risk reduction] | [Error rate] | [Baseline] | [Current] | $[Estimated value] |
+
+**Total Estimated Business Value:** $[Amount]
+**ROI:** [X]x return on investment
+
+### Key Achievements This Period
+
+1. [Achievement 1 with measurable outcome]
+2. [Achievement 2 with measurable outcome]
+3. [Achievement 3 with measurable outcome]
+
+---
+
+## 4. Adoption and Engagement Scorecard
+
+### Platform Utilisation
+
+| Module | Adoption Status | Usage Depth | Benchmark | Assessment |
+|--------|---------------|-------------|-----------|------------|
+| [Module 1] | Fully Adopted | [High/Med/Low] | [Benchmark] | [Above/At/Below] |
+| [Module 2] | Partially Adopted | [High/Med/Low] | [Benchmark] | [Above/At/Below] |
+| [Module 3] | Not Adopted | -- | -- | Opportunity |
+
+### Engagement Health
+
+| Indicator | Current | Previous Period | Trend |
+|-----------|---------|----------------|-------|
+| Executive Engagement | [Score] | [Score] | [Up/Down/Stable] |
+| Stakeholder Breadth | [# contacts] | [# contacts] | [Up/Down/Stable] |
+| Meeting Participation | [%] | [%] | [Up/Down/Stable] |
+| Feature Request Activity | [Count] | [Count] | [Up/Down/Stable] |
+
+---
+
+## 5. Account Health Overview
+
+### Health Score Trend (Last 4 Quarters)
+
+| Quarter | Overall | Usage | Engagement | Support | Relationship |
+|---------|---------|-------|------------|---------|-------------|
+| [Q-3] | [Score] | [Score] | [Score] | [Score] | [Score] |
+| [Q-2] | [Score] | [Score] | [Score] | [Score] | [Score] |
+| [Q-1] | [Score] | [Score] | [Score] | [Score] | [Score] |
+| Current | [Score] | [Score] | [Score] | [Score] | [Score] |
+
+### Risk Assessment
+
+| Risk Factor | Level | Details | Mitigation |
+|------------|-------|---------|-----------|
+| [Risk 1] | [High/Med/Low] | [Description] | [Action] |
+| [Risk 2] | [High/Med/Low] | [Description] | [Action] |
+
+---
+
+## 6. Support and Service Quality
+
+| Metric | This Period | SLA Target | Status |
+|--------|------------|-----------|--------|
+| Total Tickets | [Number] | -- | |
+| Avg First Response | [Hours] | [Hours] | [Met / Not Met] |
+| Avg Resolution Time | [Hours] | [Hours] | [Met / Not Met] |
+| Escalations | [Number] | 0 | |
+| CSAT Score | [Score] | [Target] | [Above / Below] |
+| Critical Issues | [Number] | 0 | |
+
+### Notable Support Interactions
+- [Summary of any significant support events and resolution]
+
+---
+
+## 7. Product Roadmap Alignment
+
+### Features Delivered (Relevant to This Customer)
+
+| Feature | Release Date | Customer Impact |
+|---------|-------------|----------------|
+| [Feature 1] | [Date] | [How it helps them] |
+| [Feature 2] | [Date] | [How it helps them] |
+
+### Upcoming Features (Customer-Relevant)
+
+| Feature | Expected Release | Expected Impact |
+|---------|-----------------|----------------|
+| [Feature 1] | [Quarter] | [Business value] |
+| [Feature 2] | [Quarter] | [Business value] |
+
+### Customer Feature Requests
+
+| Request | Priority | Status | Business Case |
+|---------|----------|--------|--------------|
+| [Request 1] | [P1/P2/P3] | [Status] | [Why it matters] |
+| [Request 2] | [P1/P2/P3] | [Status] | [Why it matters] |
+
+---
+
+## 8. Growth and Expansion Opportunity
+
+### Current Whitespace Analysis
+
+| Opportunity | Type | Est. Revenue | Effort | Priority |
+|------------|------|-------------|--------|----------|
+| [Opportunity 1] | [Upsell/Cross-sell/Expansion] | $[Amount] | [Low/Med/High] | [1-5] |
+| [Opportunity 2] | [Upsell/Cross-sell/Expansion] | $[Amount] | [Low/Med/High] | [1-5] |
+| [Opportunity 3] | [Upsell/Cross-sell/Expansion] | $[Amount] | [Low/Med/High] | [1-5] |
+
+**Total Expansion Opportunity:** $[Amount]
+
+### Recommended Next Steps for Growth
+1. [Specific expansion recommendation with business justification]
+2. [Specific expansion recommendation with business justification]
+
+---
+
+## 9. Renewal Outlook
+
+| Factor | Assessment |
+|--------|-----------|
+| Overall Renewal Confidence | [High / Medium / Low] |
+| Budget Availability | [Confirmed / Expected / Uncertain] |
+| Sponsor Support | [Strong / Moderate / Weak] |
+| Competitive Threat | [None / Low / Medium / High] |
+| Value Perception | [Strong / Moderate / Weak] |
+| Contract Satisfaction | [Satisfied / Neutral / Concerned] |
+
+### Renewal Strategy
+[2-3 sentences on the approach for securing renewal, including any specific actions needed]
+
+---
+
+## 10. Executive-Level Action Items
+
+| Action | Owner | Due Date | Priority | Impact |
+|--------|-------|----------|----------|--------|
+| [Action 1] | [Name, Title] | [Date] | [Critical/High/Med] | [Expected outcome] |
+| [Action 2] | [Name, Title] | [Date] | [Critical/High/Med] | [Expected outcome] |
+| [Action 3] | [Name, Title] | [Date] | [Critical/High/Med] | [Expected outcome] |
+
+---
+
+## Appendix
+
+### Stakeholder Map
+
+| Name | Title | Influence | Sentiment | Last Contact |
+|------|-------|-----------|-----------|-------------|
+| [Name] | [Title] | [Decision Maker / Influencer / User] | [Positive / Neutral / Negative] | [Date] |
+| [Name] | [Title] | [Decision Maker / Influencer / User] | [Positive / Neutral / Negative] | [Date] |
+
+### Competitive Landscape (If Applicable)
+- **Known competitors in evaluation:** [List]
+- **Our differentiators:** [Key strengths vs. competition]
+- **Risk mitigation:** [Actions to defend position]
+
+---
+
+**Confidential -- For Internal and Customer Executive Use Only**
+**Next Executive Review:** [Date]
diff --git a/skills/business-growth/customer-success-manager/assets/expected_output.json b/skills/business-growth/customer-success-manager/assets/expected_output.json
new file mode 100644
index 00000000..cb861396
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/assets/expected_output.json
@@ -0,0 +1,170 @@
+{
+ "report": "customer_health_scores",
+ "summary": {
+ "total_customers": 4,
+ "average_score": 78.8,
+ "green_count": 3,
+ "yellow_count": 1,
+ "red_count": 0
+ },
+ "customers": [
+ {
+ "customer_id": "CUST-001",
+ "name": "Acme Corp",
+ "segment": "enterprise",
+ "arr": 120000,
+ "overall_score": 86.2,
+ "classification": "green",
+ "dimensions": {
+ "usage": {
+ "score": 91.6,
+ "weight": "30%",
+ "classification": "green"
+ },
+ "engagement": {
+ "score": 82.0,
+ "weight": "25%",
+ "classification": "green"
+ },
+ "support": {
+ "score": 78.5,
+ "weight": "20%",
+ "classification": "green"
+ },
+ "relationship": {
+ "score": 90.1,
+ "weight": "25%",
+ "classification": "green"
+ }
+ },
+ "trends": {
+ "usage": "improving",
+ "engagement": "improving",
+ "support": "stable",
+ "relationship": "improving",
+ "overall": "improving"
+ },
+ "recommendations": []
+ },
+ {
+ "customer_id": "CUST-002",
+ "name": "TechStart Inc",
+ "segment": "smb",
+ "arr": 18000,
+ "overall_score": 53.7,
+ "classification": "yellow",
+ "dimensions": {
+ "usage": {
+ "score": 52.5,
+ "weight": "30%",
+ "classification": "yellow"
+ },
+ "engagement": {
+ "score": 61.6,
+ "weight": "25%",
+ "classification": "yellow"
+ },
+ "support": {
+ "score": 63.2,
+ "weight": "20%",
+ "classification": "yellow"
+ },
+ "relationship": {
+ "score": 39.5,
+ "weight": "25%",
+ "classification": "red"
+ }
+ },
+ "trends": {
+ "usage": "stable",
+ "engagement": "improving",
+ "support": "stable",
+ "relationship": "declining",
+ "overall": "stable"
+ },
+ "recommendations": [
+ "Login frequency below target -- schedule product engagement session",
+ "NPS below threshold -- conduct a feedback deep-dive with customer",
+ "CSAT is critically low -- escalate to support leadership",
+ "Single-threaded relationship -- expand contacts across departments",
+ "Renewal sentiment is negative -- initiate save plan immediately"
+ ]
+ },
+ {
+ "customer_id": "CUST-003",
+ "name": "GlobalTrade Solutions",
+ "segment": "mid-market",
+ "arr": 55000,
+ "overall_score": 79.7,
+ "classification": "green",
+ "dimensions": {
+ "usage": {
+ "score": 85.6,
+ "weight": "30%",
+ "classification": "green"
+ },
+ "engagement": {
+ "score": 79.6,
+ "weight": "25%",
+ "classification": "green"
+ },
+ "support": {
+ "score": 72.0,
+ "weight": "20%",
+ "classification": "green"
+ },
+ "relationship": {
+ "score": 79.0,
+ "weight": "25%",
+ "classification": "green"
+ }
+ },
+ "trends": {
+ "usage": "improving",
+ "engagement": "improving",
+ "support": "improving",
+ "relationship": "improving",
+ "overall": "improving"
+ },
+ "recommendations": []
+ },
+ {
+ "customer_id": "CUST-004",
+ "name": "HealthFirst Medical",
+ "segment": "enterprise",
+ "arr": 200000,
+ "overall_score": 95.7,
+ "classification": "green",
+ "dimensions": {
+ "usage": {
+ "score": 100.0,
+ "weight": "30%",
+ "classification": "green"
+ },
+ "engagement": {
+ "score": 92.0,
+ "weight": "25%",
+ "classification": "green"
+ },
+ "support": {
+ "score": 88.7,
+ "weight": "20%",
+ "classification": "green"
+ },
+ "relationship": {
+ "score": 100.0,
+ "weight": "25%",
+ "classification": "green"
+ }
+ },
+ "trends": {
+ "usage": "improving",
+ "engagement": "improving",
+ "support": "stable",
+ "relationship": "improving",
+ "overall": "improving"
+ },
+ "recommendations": []
+ }
+ ]
+}
diff --git a/skills/business-growth/customer-success-manager/assets/onboarding_checklist_template.md b/skills/business-growth/customer-success-manager/assets/onboarding_checklist_template.md
new file mode 100644
index 00000000..c3023e77
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/assets/onboarding_checklist_template.md
@@ -0,0 +1,215 @@
+# Customer Onboarding Checklist (90-Day)
+
+**Customer:** [Customer Name]
+**Segment:** [Enterprise / Mid-Market / SMB]
+**CSM:** [CSM Name]
+**Kickoff Date:** [Date]
+**Target Go-Live:** [Date]
+**Target First Value Date:** [Date -- must be within 30 days]
+
+---
+
+## Phase 1: Welcome and Setup (Days 1-14)
+
+### Pre-Kickoff Preparation (Day 0)
+
+- [ ] Review signed contract and SOW for scope and commitments
+- [ ] Research customer's industry, business model, and competitive landscape
+- [ ] Review handoff notes from sales team (pain points, decision drivers, stakeholders)
+- [ ] Prepare welcome package (login credentials, documentation links, support contacts)
+- [ ] Create customer workspace in CS platform
+- [ ] Schedule kickoff meeting with all required attendees
+- [ ] Prepare kickoff deck with agenda and success plan draft
+
+### Kickoff Meeting (Day 1-2)
+
+- [ ] Conduct kickoff meeting with customer stakeholders
+- [ ] Confirm business objectives and success criteria
+- [ ] Identify key stakeholders and their roles (sponsor, champion, technical lead, users)
+- [ ] Align on communication cadence and preferred channels
+- [ ] Review onboarding timeline and milestones
+- [ ] Set expectations for time commitment from customer team
+- [ ] Share and agree on success plan (mutual accountability)
+- [ ] Schedule recurring check-in meetings
+
+**Kickoff Meeting Notes:**
+> [Document key takeaways, concerns raised, decisions made]
+
+### Technical Setup (Days 3-7)
+
+- [ ] Provision customer environment (tenant, workspace, permissions)
+- [ ] Configure SSO/authentication if applicable
+- [ ] Set up integrations with customer's existing tools
+- [ ] Import or migrate existing data (if applicable)
+- [ ] Validate data integrity post-migration
+- [ ] Configure role-based access and permissions
+- [ ] Set up monitoring and alerting
+
+**Technical Setup Owner:** [SE / Implementation team name]
+**Technical Setup Notes:**
+> [Document configuration decisions, customizations, issues]
+
+### Admin Training (Days 7-10)
+
+- [ ] Deliver admin training session (system configuration, user management)
+- [ ] Provide admin documentation and quick reference guide
+- [ ] Ensure admins can independently manage basic operations
+- [ ] Set up admin support escalation path
+
+### Initial User Training (Days 10-14)
+
+- [ ] Deliver core user training (session 1: basic navigation and key workflows)
+- [ ] Provide user quickstart guide and video resources
+- [ ] Set up user support channel (Slack, email, in-app chat)
+- [ ] Confirm all target users have active accounts
+- [ ] Track initial login completion rate
+
+**Training Completion Rate:** [___%] of target users
+
+---
+
+## Phase 2: Activation (Days 15-30)
+
+### User Activation (Days 15-20)
+
+- [ ] Monitor daily active user metrics
+- [ ] Follow up with users who have not logged in
+- [ ] Conduct follow-up training for users needing additional help
+- [ ] Address any usability issues or confusion reported
+- [ ] Validate that core workflows are functioning as expected
+- [ ] Collect early feedback from champion and key users
+
+**Activation Rate:** [___%] of licensed users active
+
+### First Value Milestone (Days 20-30)
+
+- [ ] Define and track first value milestone (specific to customer objectives)
+- [ ] Verify customer has completed their first meaningful workflow
+- [ ] Document value delivered (even if small -- establish the pattern)
+- [ ] Share "first win" with executive sponsor
+- [ ] Celebrate the milestone with the customer team
+
+**First Value Milestone:** [Describe the specific milestone]
+**Date Achieved:** [Date]
+
+### 30-Day Review (Day 28-30)
+
+- [ ] Conduct 30-day review meeting with customer
+- [ ] Review activation metrics (logins, usage, adoption)
+- [ ] Assess progress against success plan milestones
+- [ ] Identify any blockers or concerns
+- [ ] Adjust onboarding plan if needed
+- [ ] Confirm transition from setup phase to adoption phase
+- [ ] Set goals for days 31-60
+
+**30-Day Health Score:** [Score]/100 -- [Green/Yellow/Red]
+
+---
+
+## Phase 3: Adoption (Days 31-60)
+
+### Feature Expansion (Days 31-45)
+
+- [ ] Introduce additional features beyond core workflows
+- [ ] Deliver advanced training session (session 2: power features)
+- [ ] Enable at least one integration with customer's existing tools
+- [ ] Identify and address feature adoption gaps
+- [ ] Share best practices from similar customers
+
+### Usage Benchmarking (Days 45-55)
+
+- [ ] Compare customer's usage against segment benchmarks
+- [ ] Identify underperforming areas and create enablement plan
+- [ ] Share usage report with customer champion
+- [ ] Discuss usage targets for the next 30 days
+
+**Current vs. Benchmark:**
+| Metric | Current | Benchmark | Gap |
+|--------|---------|-----------|-----|
+| Feature Adoption | [%] | [%] | [+/-] |
+| Daily Active Users | [#] | [#] | [+/-] |
+| Key Workflow Completion | [%] | [%] | [+/-] |
+
+### 60-Day Check-in (Day 55-60)
+
+- [ ] Conduct 60-day check-in meeting
+- [ ] Review adoption metrics and progress
+- [ ] Discuss any roadblocks to deeper adoption
+- [ ] Begin identifying advanced use cases
+- [ ] Set goals for days 61-90
+
+---
+
+## Phase 4: Optimisation (Days 61-90)
+
+### Advanced Use Cases (Days 61-75)
+
+- [ ] Conduct use case discovery workshop with customer
+- [ ] Identify 2-3 advanced use cases beyond initial scope
+- [ ] Build implementation plan for advanced use cases
+- [ ] Begin pilot of advanced use cases with power users
+
+### ROI Measurement (Days 75-85)
+
+- [ ] Collect data for ROI measurement against baseline
+- [ ] Build ROI summary document
+- [ ] Share ROI results with executive sponsor
+- [ ] Document customer testimonial or case study opportunity (if willing)
+
+**ROI Summary:**
+| Metric | Baseline | Current | Improvement |
+|--------|----------|---------|-------------|
+| [Metric 1] | [Value] | [Value] | [% change] |
+| [Metric 2] | [Value] | [Value] | [% change] |
+
+### 90-Day Executive Review (Days 85-90)
+
+- [ ] Prepare 90-day executive review presentation
+- [ ] Include: value delivered, adoption metrics, ROI, next steps
+- [ ] Conduct review meeting with executive sponsor
+- [ ] Transition from onboarding to ongoing success management
+- [ ] Establish ongoing success plan with quarterly milestones
+- [ ] Confirm ongoing meeting cadence
+- [ ] Introduce expansion opportunities if appropriate
+
+**90-Day Health Score:** [Score]/100 -- [Green/Yellow/Red]
+
+---
+
+## Onboarding Completion Gate
+
+The following criteria must be met to consider onboarding complete:
+
+- [ ] User activation rate above 80%
+- [ ] First value milestone achieved within 30 days
+- [ ] Core workflows actively used by target users
+- [ ] Executive sponsor confirms satisfaction
+- [ ] Health score is Yellow (50+) or better
+- [ ] Success plan established with ongoing milestones
+- [ ] Recurring meeting cadence confirmed
+- [ ] Support escalation path understood by customer
+
+**Onboarding Status:** [Complete / In Progress / Blocked]
+**Completion Date:** [Date]
+**Handoff to Steady-State CSM:** [Date if different CSM]
+
+---
+
+## Notes
+
+### Risks and Blockers
+
+| Risk/Blocker | Impact | Mitigation | Status |
+|-------------|--------|-----------|--------|
+| [Item] | [High/Med/Low] | [Action] | [Open/Resolved] |
+
+### Key Decisions
+
+| Date | Decision | Made By | Impact |
+|------|----------|---------|--------|
+| [Date] | [Decision] | [Name] | [Description] |
+
+---
+
+**Template Version:** 1.0
+**Last Updated:** February 2026
diff --git a/skills/business-growth/customer-success-manager/assets/qbr_template.md b/skills/business-growth/customer-success-manager/assets/qbr_template.md
new file mode 100644
index 00000000..c77800f0
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/assets/qbr_template.md
@@ -0,0 +1,163 @@
+# Quarterly Business Review (QBR)
+
+**Customer:** [Customer Name]
+**Date:** [QBR Date]
+**Prepared by:** [CSM Name]
+**Attendees:** [List attendees and titles]
+
+---
+
+## 1. Executive Summary
+
+**Overall Relationship Status:** [Green / Yellow / Red]
+**Health Score:** [Score]/100
+**Key Theme:** [One sentence summarizing the quarter]
+
+### Quarter Highlights
+- [Highlight 1: major achievement or milestone]
+- [Highlight 2: value delivered]
+- [Highlight 3: initiative completed]
+
+### Areas of Focus
+- [Focus area 1]
+- [Focus area 2]
+
+---
+
+## 2. Value Delivered This Quarter
+
+### Business Outcomes Achieved
+
+| Objective | Target | Actual | Status |
+|-----------|--------|--------|--------|
+| [Objective 1] | [Target metric] | [Actual metric] | [On Track / At Risk / Achieved] |
+| [Objective 2] | [Target metric] | [Actual metric] | [On Track / At Risk / Achieved] |
+| [Objective 3] | [Target metric] | [Actual metric] | [On Track / At Risk / Achieved] |
+
+### ROI Summary
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| [Metric 1, e.g., Time savings] | [Baseline] | [Current] | [% change] |
+| [Metric 2, e.g., Cost reduction] | [Baseline] | [Current] | [% change] |
+| [Metric 3, e.g., Revenue impact] | [Baseline] | [Current] | [% change] |
+
+**Estimated Total Value Delivered:** $[Amount]
+
+---
+
+## 3. Product Usage and Adoption
+
+### Usage Metrics
+
+| Metric | Last Quarter | This Quarter | Trend |
+|--------|-------------|--------------|-------|
+| Monthly Active Users | [Number] | [Number] | [Up/Down/Stable] |
+| Feature Adoption Rate | [%] | [%] | [Up/Down/Stable] |
+| DAU/MAU Ratio | [Ratio] | [Ratio] | [Up/Down/Stable] |
+| Seat Utilization | [%] | [%] | [Up/Down/Stable] |
+
+### Feature Adoption Breakdown
+
+| Feature/Module | Status | Usage Level | Notes |
+|---------------|--------|-------------|-------|
+| [Feature 1] | Active | [High/Med/Low] | |
+| [Feature 2] | Active | [High/Med/Low] | |
+| [Feature 3] | Not Adopted | -- | [Reason / Opportunity] |
+
+### Adoption Recommendations
+1. [Recommendation for increasing adoption of underused features]
+2. [Recommendation for enabling new use cases]
+
+---
+
+## 4. Support Summary
+
+| Metric | This Quarter | Previous Quarter | Benchmark |
+|--------|-------------|-----------------|-----------|
+| Total Tickets | [Number] | [Number] | [Segment avg] |
+| Avg Resolution Time | [Hours] | [Hours] | [SLA target] |
+| Escalations | [Number] | [Number] | [Target: 0] |
+| CSAT Score | [Score] | [Score] | [Target] |
+
+### Open Issues
+| Issue | Priority | Status | ETA |
+|-------|----------|--------|-----|
+| [Issue 1] | [P1/P2/P3] | [In Progress / Pending] | [Date] |
+
+---
+
+## 5. Success Plan Progress
+
+### Current Success Plan Goals
+
+| Goal | Timeline | Progress | Status |
+|------|----------|----------|--------|
+| [Goal 1] | [Date] | [%] | [On Track / At Risk / Complete] |
+| [Goal 2] | [Date] | [%] | [On Track / At Risk / Complete] |
+| [Goal 3] | [Date] | [%] | [On Track / At Risk / Complete] |
+
+### Next Quarter Goals (Proposed)
+1. [Goal 1 with specific measurable outcome]
+2. [Goal 2 with specific measurable outcome]
+3. [Goal 3 with specific measurable outcome]
+
+---
+
+## 6. Product Roadmap Highlights
+
+### Recently Released (Relevant to [Customer Name])
+- [Feature/enhancement 1] -- [How it benefits them]
+- [Feature/enhancement 2] -- [How it benefits them]
+
+### Coming Next Quarter
+- [Upcoming feature 1] -- [Expected benefit]
+- [Upcoming feature 2] -- [Expected benefit]
+
+### Feature Requests Status
+| Request | Priority | Status | Expected Release |
+|---------|----------|--------|-----------------|
+| [Request 1] | [High/Med/Low] | [Planned / In Development / Under Review] | [Quarter] |
+
+---
+
+## 7. Growth Opportunities
+
+### Expansion Discussion Points
+- [Opportunity 1: e.g., additional seats for new team]
+- [Opportunity 2: e.g., new module that addresses identified need]
+- [Opportunity 3: e.g., tier upgrade for advanced capabilities]
+
+### Estimated Value of Expansion: $[Amount] additional ARR
+
+---
+
+## 8. Action Items
+
+| Action | Owner | Due Date | Priority |
+|--------|-------|----------|----------|
+| [Action 1] | [Name] | [Date] | [High/Med/Low] |
+| [Action 2] | [Name] | [Date] | [High/Med/Low] |
+| [Action 3] | [Name] | [Date] | [High/Med/Low] |
+| [Action 4] | [Name] | [Date] | [High/Med/Low] |
+
+---
+
+## 9. Contract and Renewal
+
+**Contract Start:** [Date]
+**Renewal Date:** [Date]
+**Current ARR:** $[Amount]
+**Days to Renewal:** [Number]
+
+### Renewal Readiness
+- [ ] Value documented and communicated
+- [ ] Executive sponsor aligned
+- [ ] Open issues resolved or plan in place
+- [ ] Pricing and terms discussed
+- [ ] Expansion proposal prepared (if applicable)
+
+---
+
+**Next QBR Date:** [Date]
+**Next Check-in:** [Date]
diff --git a/skills/business-growth/customer-success-manager/assets/sample_customer_data.json b/skills/business-growth/customer-success-manager/assets/sample_customer_data.json
new file mode 100644
index 00000000..f46f7bae
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/assets/sample_customer_data.json
@@ -0,0 +1,314 @@
+{
+ "customers": [
+ {
+ "customer_id": "CUST-001",
+ "name": "Acme Corp",
+ "segment": "enterprise",
+ "arr": 120000,
+ "contract_end_date": "2026-12-31",
+ "usage": {
+ "login_frequency": 85,
+ "feature_adoption": 72,
+ "dau_mau_ratio": 0.45
+ },
+ "engagement": {
+ "support_ticket_volume": 3,
+ "meeting_attendance": 90,
+ "nps_score": 8,
+ "csat_score": 4.2
+ },
+ "support": {
+ "open_tickets": 2,
+ "escalation_rate": 0.05,
+ "avg_resolution_hours": 18
+ },
+ "relationship": {
+ "executive_sponsor_engagement": 80,
+ "multi_threading_depth": 4,
+ "renewal_sentiment": "positive"
+ },
+ "previous_period": {
+ "usage_score": 70,
+ "engagement_score": 65,
+ "support_score": 75,
+ "relationship_score": 60,
+ "overall_score": 67
+ },
+ "usage_decline": {
+ "login_trend": 5,
+ "feature_adoption_change": 3,
+ "dau_mau_change": 0.02
+ },
+ "engagement_drop": {
+ "meeting_cancellations": 0,
+ "response_time_days": 1,
+ "nps_change": 1
+ },
+ "support_issues": {
+ "open_escalations": 0,
+ "unresolved_critical": 0,
+ "satisfaction_trend": "improving"
+ },
+ "relationship_signals": {
+ "champion_left": false,
+ "sponsor_change": false,
+ "competitor_mentions": 0
+ },
+ "commercial_factors": {
+ "contract_type": "annual",
+ "pricing_complaints": false,
+ "budget_cuts_mentioned": false
+ },
+ "contract": {
+ "licensed_seats": 100,
+ "active_seats": 95,
+ "plan_tier": "professional",
+ "available_tiers": ["professional", "enterprise", "enterprise_plus"]
+ },
+ "product_usage": {
+ "core_platform": {"adopted": true, "usage_pct": 85},
+ "analytics_module": {"adopted": true, "usage_pct": 60},
+ "integrations_module": {"adopted": false, "usage_pct": 0},
+ "api_access": {"adopted": true, "usage_pct": 40},
+ "advanced_reporting": {"adopted": false, "usage_pct": 0}
+ },
+ "departments": {
+ "current": ["engineering", "product"],
+ "potential": ["marketing", "sales", "support"]
+ }
+ },
+ {
+ "customer_id": "CUST-002",
+ "name": "TechStart Inc",
+ "segment": "smb",
+ "arr": 18000,
+ "contract_end_date": "2026-04-15",
+ "usage": {
+ "login_frequency": 40,
+ "feature_adoption": 30,
+ "dau_mau_ratio": 0.15
+ },
+ "engagement": {
+ "support_ticket_volume": 8,
+ "meeting_attendance": 50,
+ "nps_score": 5,
+ "csat_score": 3.0
+ },
+ "support": {
+ "open_tickets": 6,
+ "escalation_rate": 0.18,
+ "avg_resolution_hours": 42
+ },
+ "relationship": {
+ "executive_sponsor_engagement": 30,
+ "multi_threading_depth": 1,
+ "renewal_sentiment": "negative"
+ },
+ "previous_period": {
+ "usage_score": 55,
+ "engagement_score": 50,
+ "support_score": 60,
+ "relationship_score": 45,
+ "overall_score": 52
+ },
+ "usage_decline": {
+ "login_trend": -25,
+ "feature_adoption_change": -18,
+ "dau_mau_change": -0.12
+ },
+ "engagement_drop": {
+ "meeting_cancellations": 3,
+ "response_time_days": 8,
+ "nps_change": -4
+ },
+ "support_issues": {
+ "open_escalations": 2,
+ "unresolved_critical": 1,
+ "satisfaction_trend": "declining"
+ },
+ "relationship_signals": {
+ "champion_left": true,
+ "sponsor_change": false,
+ "competitor_mentions": 3
+ },
+ "commercial_factors": {
+ "contract_type": "month-to-month",
+ "pricing_complaints": true,
+ "budget_cuts_mentioned": true
+ },
+ "contract": {
+ "licensed_seats": 20,
+ "active_seats": 8,
+ "plan_tier": "starter",
+ "available_tiers": ["starter", "professional", "enterprise"]
+ },
+ "product_usage": {
+ "core_platform": {"adopted": true, "usage_pct": 35},
+ "analytics_module": {"adopted": false, "usage_pct": 0},
+ "integrations_module": {"adopted": false, "usage_pct": 0},
+ "api_access": {"adopted": false, "usage_pct": 0},
+ "advanced_reporting": {"adopted": false, "usage_pct": 0}
+ },
+ "departments": {
+ "current": ["engineering"],
+ "potential": ["product", "design"]
+ }
+ },
+ {
+ "customer_id": "CUST-003",
+ "name": "GlobalTrade Solutions",
+ "segment": "mid-market",
+ "arr": 55000,
+ "contract_end_date": "2026-09-30",
+ "usage": {
+ "login_frequency": 70,
+ "feature_adoption": 58,
+ "dau_mau_ratio": 0.35
+ },
+ "engagement": {
+ "support_ticket_volume": 5,
+ "meeting_attendance": 75,
+ "nps_score": 7,
+ "csat_score": 3.8
+ },
+ "support": {
+ "open_tickets": 3,
+ "escalation_rate": 0.10,
+ "avg_resolution_hours": 30
+ },
+ "relationship": {
+ "executive_sponsor_engagement": 60,
+ "multi_threading_depth": 3,
+ "renewal_sentiment": "neutral"
+ },
+ "previous_period": {
+ "usage_score": 68,
+ "engagement_score": 70,
+ "support_score": 65,
+ "relationship_score": 62,
+ "overall_score": 66
+ },
+ "usage_decline": {
+ "login_trend": -8,
+ "feature_adoption_change": -5,
+ "dau_mau_change": -0.03
+ },
+ "engagement_drop": {
+ "meeting_cancellations": 1,
+ "response_time_days": 3,
+ "nps_change": -1
+ },
+ "support_issues": {
+ "open_escalations": 1,
+ "unresolved_critical": 0,
+ "satisfaction_trend": "stable"
+ },
+ "relationship_signals": {
+ "champion_left": false,
+ "sponsor_change": true,
+ "competitor_mentions": 1
+ },
+ "commercial_factors": {
+ "contract_type": "annual",
+ "pricing_complaints": false,
+ "budget_cuts_mentioned": false
+ },
+ "contract": {
+ "licensed_seats": 50,
+ "active_seats": 48,
+ "plan_tier": "professional",
+ "available_tiers": ["professional", "enterprise", "enterprise_plus"]
+ },
+ "product_usage": {
+ "core_platform": {"adopted": true, "usage_pct": 78},
+ "analytics_module": {"adopted": true, "usage_pct": 45},
+ "integrations_module": {"adopted": true, "usage_pct": 55},
+ "api_access": {"adopted": false, "usage_pct": 0},
+ "advanced_reporting": {"adopted": false, "usage_pct": 0}
+ },
+ "departments": {
+ "current": ["operations", "finance"],
+ "potential": ["logistics", "compliance"]
+ }
+ },
+ {
+ "customer_id": "CUST-004",
+ "name": "HealthFirst Medical",
+ "segment": "enterprise",
+ "arr": 200000,
+ "contract_end_date": "2027-03-15",
+ "usage": {
+ "login_frequency": 92,
+ "feature_adoption": 88,
+ "dau_mau_ratio": 0.55
+ },
+ "engagement": {
+ "support_ticket_volume": 2,
+ "meeting_attendance": 95,
+ "nps_score": 9,
+ "csat_score": 4.6
+ },
+ "support": {
+ "open_tickets": 1,
+ "escalation_rate": 0.02,
+ "avg_resolution_hours": 12
+ },
+ "relationship": {
+ "executive_sponsor_engagement": 92,
+ "multi_threading_depth": 6,
+ "renewal_sentiment": "positive"
+ },
+ "previous_period": {
+ "usage_score": 85,
+ "engagement_score": 82,
+ "support_score": 88,
+ "relationship_score": 80,
+ "overall_score": 84
+ },
+ "usage_decline": {
+ "login_trend": 3,
+ "feature_adoption_change": 5,
+ "dau_mau_change": 0.03
+ },
+ "engagement_drop": {
+ "meeting_cancellations": 0,
+ "response_time_days": 1,
+ "nps_change": 0
+ },
+ "support_issues": {
+ "open_escalations": 0,
+ "unresolved_critical": 0,
+ "satisfaction_trend": "improving"
+ },
+ "relationship_signals": {
+ "champion_left": false,
+ "sponsor_change": false,
+ "competitor_mentions": 0
+ },
+ "commercial_factors": {
+ "contract_type": "multi-year",
+ "pricing_complaints": false,
+ "budget_cuts_mentioned": false
+ },
+ "contract": {
+ "licensed_seats": 250,
+ "active_seats": 240,
+ "plan_tier": "enterprise",
+ "available_tiers": ["professional", "enterprise", "enterprise_plus"]
+ },
+ "product_usage": {
+ "core_platform": {"adopted": true, "usage_pct": 92},
+ "analytics_module": {"adopted": true, "usage_pct": 80},
+ "integrations_module": {"adopted": true, "usage_pct": 70},
+ "api_access": {"adopted": true, "usage_pct": 65},
+ "advanced_reporting": {"adopted": true, "usage_pct": 50},
+ "security_module": {"adopted": false, "usage_pct": 0},
+ "audit_module": {"adopted": false, "usage_pct": 0}
+ },
+ "departments": {
+ "current": ["clinical", "operations", "IT", "compliance"],
+ "potential": ["research", "finance", "HR"]
+ }
+ }
+ ]
+}
diff --git a/skills/business-growth/customer-success-manager/assets/success_plan_template.md b/skills/business-growth/customer-success-manager/assets/success_plan_template.md
new file mode 100644
index 00000000..f30453cc
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/assets/success_plan_template.md
@@ -0,0 +1,167 @@
+# Customer Success Plan
+
+**Customer:** [Customer Name]
+**CSM:** [CSM Name]
+**Account Executive:** [AE Name]
+**Plan Created:** [Date]
+**Last Updated:** [Date]
+**Review Cadence:** [Monthly / Quarterly]
+
+---
+
+## 1. Customer Overview
+
+| Field | Details |
+|-------|---------|
+| Industry | [Industry] |
+| Company Size | [Employees] |
+| Segment | [Enterprise / Mid-Market / SMB] |
+| ARR | $[Amount] |
+| Contract Start | [Date] |
+| Renewal Date | [Date] |
+| Plan Tier | [Tier name] |
+| Licensed Seats | [Number] |
+
+### Key Stakeholders
+
+| Name | Title | Role | Engagement Level |
+|------|-------|------|-----------------|
+| [Name] | [Title] | Executive Sponsor | [High / Medium / Low] |
+| [Name] | [Title] | Day-to-Day Champion | [High / Medium / Low] |
+| [Name] | [Title] | Technical Lead | [High / Medium / Low] |
+| [Name] | [Title] | End User Lead | [High / Medium / Low] |
+
+---
+
+## 2. Business Objectives
+
+### Primary Business Objectives
+
+| # | Objective | Success Metric | Target | Timeline |
+|---|-----------|---------------|--------|----------|
+| 1 | [e.g., Reduce manual reporting time] | [Hours saved per week] | [Target number] | [Date] |
+| 2 | [e.g., Improve team collaboration] | [Project completion rate] | [Target %] | [Date] |
+| 3 | [e.g., Increase revenue visibility] | [Forecast accuracy] | [Target %] | [Date] |
+
+### Why These Objectives Matter
+- **Objective 1:** [Business context -- why this matters to the customer's overall strategy]
+- **Objective 2:** [Business context]
+- **Objective 3:** [Business context]
+
+---
+
+## 3. Success Milestones
+
+### Phase 1: Foundation (Days 1-30)
+
+| Milestone | Target Date | Status | Owner | Notes |
+|-----------|------------|--------|-------|-------|
+| Technical setup complete | [Date] | [ ] | [Name] | |
+| Admin training delivered | [Date] | [ ] | CSM | |
+| Core team onboarded | [Date] | [ ] | CSM | |
+| First value milestone achieved | [Date] | [ ] | [Name] | |
+| Data migration validated | [Date] | [ ] | SE | |
+
+### Phase 2: Adoption (Days 31-90)
+
+| Milestone | Target Date | Status | Owner | Notes |
+|-----------|------------|--------|-------|-------|
+| 80% user adoption | [Date] | [ ] | CSM | |
+| Key workflows live | [Date] | [ ] | [Name] | |
+| Integrations configured | [Date] | [ ] | SE | |
+| First ROI measurement | [Date] | [ ] | CSM | |
+| 30-day review complete | [Date] | [ ] | CSM | |
+
+### Phase 3: Value Realisation (Days 91-180)
+
+| Milestone | Target Date | Status | Owner | Notes |
+|-----------|------------|--------|-------|-------|
+| Objective 1 progress measurable | [Date] | [ ] | [Name] | |
+| Advanced features adopted | [Date] | [ ] | CSM | |
+| QBR completed | [Date] | [ ] | CSM | |
+| Executive alignment confirmed | [Date] | [ ] | CSM | |
+
+### Phase 4: Optimisation and Growth (Days 181-365)
+
+| Milestone | Target Date | Status | Owner | Notes |
+|-----------|------------|--------|-------|-------|
+| All objectives on track | [Date] | [ ] | CSM | |
+| ROI documented for renewal | [Date] | [ ] | CSM | |
+| Expansion opportunities identified | [Date] | [ ] | CSM + AE | |
+| Renewal conversation initiated | [Date] | [ ] | CSM + AE | |
+
+---
+
+## 4. Health Score Tracking
+
+| Date | Overall Score | Usage | Engagement | Support | Relationship | Classification |
+|------|--------------|-------|------------|---------|-------------|---------------|
+| [Date] | [Score] | [Score] | [Score] | [Score] | [Score] | [Green/Yellow/Red] |
+| [Date] | [Score] | [Score] | [Score] | [Score] | [Score] | [Green/Yellow/Red] |
+
+---
+
+## 5. Risk Register
+
+| Risk | Probability | Impact | Mitigation | Owner | Status |
+|------|------------|--------|-----------|-------|--------|
+| [e.g., Executive sponsor departure] | [High/Med/Low] | [High/Med/Low] | [Multi-thread relationships] | CSM | [Active/Resolved] |
+| [e.g., Low adoption in team X] | [High/Med/Low] | [High/Med/Low] | [Targeted training session] | CSM | [Active/Resolved] |
+| [e.g., Budget review next quarter] | [High/Med/Low] | [High/Med/Low] | [Document ROI before review] | CSM | [Active/Resolved] |
+
+---
+
+## 6. Communication Plan
+
+| Activity | Frequency | Participants | Purpose |
+|----------|-----------|-------------|---------|
+| Status check-in | [Weekly / Bi-weekly] | CSM + Champion | Tactical progress review |
+| Strategic review | [Monthly] | CSM + Stakeholders | Objective alignment |
+| QBR | [Quarterly] | CSM + Executive Sponsor | Executive business review |
+| Technical review | [As needed] | SE + Technical Lead | Architecture and integration |
+| Renewal planning | [90 days before] | CSM + AE + Sponsor | Contract discussion |
+
+---
+
+## 7. Product Adoption Plan
+
+### Current State
+
+| Module/Feature | Status | Usage Level | Target Usage | Gap |
+|---------------|--------|-------------|-------------|-----|
+| [Module 1] | Adopted | [%] | [%] | [Actions needed] |
+| [Module 2] | Adopted | [%] | [%] | [Actions needed] |
+| [Module 3] | Not Adopted | 0% | [%] | [Enablement plan] |
+
+### Enablement Activities
+
+| Activity | Target Date | Audience | Expected Outcome |
+|----------|------------|----------|-----------------|
+| [Training session] | [Date] | [Team/Group] | [Metric improvement] |
+| [Workshop] | [Date] | [Team/Group] | [New workflow adoption] |
+| [Office hours] | [Ongoing] | [All users] | [Question resolution] |
+
+---
+
+## 8. Expansion Roadmap
+
+| Opportunity | Type | Estimated Value | Timeline | Prerequisites |
+|------------|------|----------------|----------|--------------|
+| [e.g., Additional seats] | Expansion | $[Amount] | [Quarter] | [Usage > 90%] |
+| [e.g., Tier upgrade] | Upsell | $[Amount] | [Quarter] | [Feature requests] |
+| [e.g., New module] | Cross-sell | $[Amount] | [Quarter] | [Use case validated] |
+
+---
+
+## 9. Notes and Updates
+
+### [Date] - [Author]
+[Update notes, key decisions, changes to plan]
+
+### [Date] - [Author]
+[Update notes, key decisions, changes to plan]
+
+---
+
+**Next Review Date:** [Date]
+**Plan Owner:** [CSM Name]
diff --git a/skills/business-growth/customer-success-manager/references/cs-metrics-benchmarks.md b/skills/business-growth/customer-success-manager/references/cs-metrics-benchmarks.md
new file mode 100644
index 00000000..0aa59222
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/references/cs-metrics-benchmarks.md
@@ -0,0 +1,259 @@
+# Customer Success Metrics and Benchmarks
+
+Industry benchmarks for key customer success metrics, segmented by company size, customer segment, and industry vertical.
+
+---
+
+## Core SaaS Metrics
+
+### Net Revenue Retention (NRR)
+
+NRR measures revenue retained from existing customers including expansion, contraction, and churn. It is the single most important metric for SaaS customer success.
+
+**Formula:** (Starting ARR + Expansion - Contraction - Churn) / Starting ARR * 100
+
+| Performance Level | NRR Range | Interpretation |
+|-------------------|-----------|----------------|
+| Best-in-class | > 130% | Strong expansion engine, very low churn |
+| Excellent | 120-130% | Healthy growth from existing customers |
+| Good | 110-120% | Solid retention with moderate expansion |
+| Target | > 110% | Minimum for sustainable growth |
+| Acceptable | 100-110% | Revenue stable but limited expansion |
+| Below target | 90-100% | Churn exceeds expansion |
+| Concerning | < 90% | Significant revenue erosion |
+
+**Benchmarks by Segment:**
+
+| Customer Segment | Median NRR | Top Quartile | Bottom Quartile |
+|-----------------|------------|--------------|-----------------|
+| Enterprise (>$100K ARR) | 115% | 130%+ | 105% |
+| Mid-Market ($25K-$100K) | 108% | 120% | 98% |
+| SMB (<$25K ARR) | 95% | 105% | 85% |
+
+### Gross Revenue Retention (GRR)
+
+GRR measures revenue retained without counting expansion. It isolates the churn and contraction signal.
+
+**Formula:** (Starting ARR - Contraction - Churn) / Starting ARR * 100
+
+| Performance Level | GRR Range | Interpretation |
+|-------------------|-----------|----------------|
+| Best-in-class | > 95% | Minimal churn, highly sticky product |
+| Excellent | 92-95% | Strong retention |
+| Good | 90-92% | Healthy with room to improve |
+| Target | > 90% | Industry standard target |
+| Acceptable | 85-90% | Moderate churn, needs focus |
+| Below target | 80-85% | High churn impacting growth |
+| Concerning | < 80% | Urgent retention problem |
+
+**Benchmarks by Segment:**
+
+| Customer Segment | Median GRR | Top Quartile | Bottom Quartile |
+|-----------------|------------|--------------|-----------------|
+| Enterprise | 95% | 98% | 90% |
+| Mid-Market | 90% | 95% | 85% |
+| SMB | 82% | 90% | 75% |
+
+---
+
+## Health Score Benchmarks
+
+### Portfolio Health Distribution (Target)
+
+A healthy CS portfolio should have the following approximate distribution:
+
+| Classification | Target Distribution | Alert Threshold |
+|---------------|-------------------|-----------------|
+| Green (Healthy) | 60-70% | < 50% triggers portfolio review |
+| Yellow (Attention) | 20-30% | > 35% signals systemic issues |
+| Red (At Risk) | 5-10% | > 15% requires executive intervention |
+
+### Average Health Score by Segment
+
+| Segment | Target Average | Industry Median | Top Quartile |
+|---------|---------------|-----------------|--------------|
+| Enterprise | > 78 | 72 | 82 |
+| Mid-Market | > 75 | 68 | 78 |
+| SMB | > 70 | 65 | 75 |
+
+### Health Score by Dimension (Industry Medians)
+
+| Dimension | Enterprise | Mid-Market | SMB |
+|-----------|-----------|------------|-----|
+| Usage | 72 | 68 | 60 |
+| Engagement | 70 | 62 | 55 |
+| Support | 78 | 72 | 65 |
+| Relationship | 68 | 60 | 50 |
+
+---
+
+## Churn Metrics
+
+### Logo Churn Rate (Annual)
+
+| Performance Level | Rate | Interpretation |
+|-------------------|------|----------------|
+| Best-in-class | < 5% | Exceptional retention |
+| Excellent | 5-8% | Very strong |
+| Good | 8-12% | Healthy |
+| Acceptable | 12-15% | Room for improvement |
+| Below target | 15-20% | Significant churn problem |
+| Concerning | > 20% | Urgent -- product-market fit issues likely |
+
+**Benchmarks by Segment:**
+
+| Segment | Median Annual Logo Churn | Top Quartile | Bottom Quartile |
+|---------|------------------------|--------------|-----------------|
+| Enterprise | 5% | 2% | 10% |
+| Mid-Market | 10% | 5% | 18% |
+| SMB | 20% | 12% | 35% |
+
+### Churn Leading Indicators
+
+The following metrics have the highest predictive power for churn events:
+
+| Indicator | Lead Time | Correlation with Churn |
+|-----------|-----------|----------------------|
+| Login frequency decline (>30%) | 60-90 days | Very High |
+| NPS drop (>3 points) | 30-60 days | High |
+| Executive sponsor departure | 30-90 days | Very High |
+| Support escalation rate increase | 30-60 days | High |
+| Meeting cancellation increase | 30-45 days | Moderate-High |
+| Feature adoption decline | 60-90 days | Moderate |
+| Competitor mentions | 30-60 days | Moderate |
+
+---
+
+## Expansion Metrics
+
+### Expansion Revenue Rate
+
+| Performance Level | Rate | Notes |
+|-------------------|------|-------|
+| Best-in-class | > 30% of total revenue | Strong land-and-expand motion |
+| Excellent | 25-30% | Effective expansion engine |
+| Good | 20-25% | Solid upsell/cross-sell |
+| Target | > 20% | Minimum for healthy growth |
+| Below target | 10-20% | Expansion motion needs development |
+| Concerning | < 10% | Missing significant expansion opportunity |
+
+### Expansion by Type
+
+| Expansion Type | Typical Contribution | Average Deal Size |
+|---------------|---------------------|-------------------|
+| Seat Expansion | 40-50% of expansion | 15-25% of contract value |
+| Tier Upsell | 25-35% of expansion | 40-80% of contract value |
+| Module Cross-sell | 15-25% of expansion | 10-20% of contract value |
+| Department Expansion | 5-15% of expansion | 50-100% of contract value |
+
+### Expansion Readiness Indicators
+
+| Signal | Interpretation |
+|--------|---------------|
+| Seat utilisation > 90% | Ready for seat expansion |
+| Feature requests for higher tier | Upsell opportunity |
+| Usage of 70%+ of current modules | Ready for cross-sell |
+| New department interest | Department expansion play |
+| Customer referral activity | Strong relationship, open to expansion |
+
+---
+
+## Engagement Metrics
+
+### Customer Engagement Score (CES) Benchmarks
+
+| Metric | Target | Median | Warning |
+|--------|--------|--------|---------|
+| Meeting attendance rate | > 80% | 72% | < 50% |
+| Average NPS | > 50 | 35 | < 20 |
+| Average CSAT | > 4.2/5 | 3.8/5 | < 3.0/5 |
+| Response time (days) | < 2 | 3 | > 5 |
+| QBR completion rate | > 90% | 75% | < 60% |
+
+### Time to First Value (TTFV)
+
+| Segment | Target TTFV | Median TTFV | Warning Threshold |
+|---------|------------|------------|-------------------|
+| Enterprise | < 30 days | 45 days | > 60 days |
+| Mid-Market | < 21 days | 30 days | > 45 days |
+| SMB | < 14 days | 21 days | > 30 days |
+
+---
+
+## CSM Operational Metrics
+
+### Portfolio Management
+
+| Metric | Enterprise CSM | Mid-Market CSM | SMB CSM (Tech-Touch) |
+|--------|---------------|----------------|---------------------|
+| Accounts per CSM | 10-25 | 30-60 | 100-300+ |
+| ARR per CSM | $2M-$5M | $2M-$4M | $1M-$3M |
+| Touch frequency | Weekly-biweekly | Biweekly-monthly | Quarterly-automated |
+| QBR frequency | Quarterly | Semi-annually | Annually |
+| Health score reviews | Weekly | Bi-weekly | Monthly |
+
+### CSM Activity Benchmarks
+
+| Activity | Target per Month | Purpose |
+|----------|-----------------|---------|
+| Strategic calls | 2-4 per account | Relationship building |
+| Health score reviews | 4 (weekly) | Portfolio monitoring |
+| QBR preparation | 3-5 per quarter | Executive engagement |
+| Escalation handling | < 2 per month | Issue resolution |
+| Expansion conversations | 1-2 per account | Revenue growth |
+
+---
+
+## Industry-Specific Benchmarks
+
+### By Industry Vertical
+
+| Industry | Median NRR | Median GRR | Median Logo Churn |
+|----------|-----------|-----------|------------------|
+| Infrastructure/DevOps | 125% | 95% | 5% |
+| Cybersecurity | 120% | 93% | 7% |
+| HR Tech | 110% | 90% | 12% |
+| MarTech | 105% | 87% | 15% |
+| FinTech | 115% | 92% | 8% |
+| HealthTech | 112% | 91% | 10% |
+| EdTech | 100% | 85% | 18% |
+| eCommerce Tools | 108% | 88% | 14% |
+
+### By Company Stage
+
+| Stage | Median NRR | Median GRR | Notes |
+|-------|-----------|-----------|-------|
+| Early Stage (<$10M ARR) | 100% | 85% | Focus on product-market fit |
+| Growth ($10M-$50M ARR) | 110% | 90% | Building CS function |
+| Scale ($50M-$200M ARR) | 118% | 93% | Mature CS operations |
+| Enterprise (>$200M ARR) | 115% | 95% | Optimisation phase |
+
+---
+
+## Metric Relationships
+
+### Key Correlations
+
+| If This Metric Moves | This Also Tends to Move | Direction |
+|---------------------|------------------------|-----------|
+| Health score down | Churn probability up | Inverse |
+| NPS up | NRR up | Direct |
+| TTFV down | GRR up | Inverse |
+| Feature adoption up | Expansion rate up | Direct |
+| Escalation rate up | NPS down | Inverse |
+| Multi-threading depth up | GRR up | Direct |
+
+### The SaaS Retention Equation
+
+**Sustainable Growth requires:** NRR > 110% AND GRR > 90%
+
+If NRR is high but GRR is low: You are churning customers and replacing with expansion from survivors. Not sustainable.
+
+If GRR is high but NRR is low: You retain well but do not expand. Leaving money on the table.
+
+Both high: Healthy, compounding growth from existing customers.
+
+---
+
+**Last Updated:** February 2026
+**Sources:** Industry surveys, SaaS benchmarking reports, customer success community data (2024-2025 data cycles).
diff --git a/skills/business-growth/customer-success-manager/references/cs-playbooks.md b/skills/business-growth/customer-success-manager/references/cs-playbooks.md
new file mode 100644
index 00000000..cdceaf01
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/references/cs-playbooks.md
@@ -0,0 +1,290 @@
+# Customer Success Playbooks
+
+Comprehensive intervention, onboarding, renewal, expansion, and escalation playbooks for SaaS customer success management.
+
+---
+
+## Risk Tier Intervention Playbooks
+
+### Critical Risk (Score 80-100)
+
+**Situation:** Customer is at imminent risk of churn. Multiple severe warning signals detected. Requires immediate executive-level intervention.
+
+**Timeline:** Act within 48 hours.
+
+**Steps:**
+
+1. **Executive Escalation (Day 0)**
+ - Alert VP of Customer Success and account executive immediately
+ - Brief internal leadership on situation, warning signals, and ARR at risk
+ - Identify any pending support issues and fast-track resolution
+
+2. **Customer Contact (Day 1-2)**
+ - Schedule executive-to-executive call (VP CS to customer VP/C-level)
+ - Frame the conversation around understanding their challenges, not defending your product
+ - Listen more than talk -- capture the real objections
+
+3. **Save Plan Creation (Day 2-3)**
+ - Create a detailed save plan with specific value milestones tied to their business outcomes
+ - Include timeline, owners, and measurable success criteria
+ - Get internal alignment on any concessions (pricing, features, roadmap commitments)
+
+4. **Rescue Team Assignment (Day 3-5)**
+ - Assign a dedicated rescue team: CSM + Solutions Engineer + Support Lead
+ - Daily internal stand-up (15 min max) on account status
+ - Solutions Engineer to conduct technical health check
+
+5. **Execution and Monitoring (Week 2-4)**
+ - Execute save plan with weekly customer check-ins
+ - Track progress against milestones
+ - Prepare competitive displacement defence if competitor involvement detected
+
+6. **Resolution Assessment (Week 4)**
+ - Evaluate whether the situation is stabilising
+ - If improving: transition to High-risk monitoring cadence
+ - If not improving: escalate to CEO/GM for final intervention
+
+**Success Criteria:** Risk score drops below 60 within 30 days. Customer confirms continued partnership intent.
+
+---
+
+### High Risk (Score 60-79)
+
+**Situation:** Customer showing clear signs of dissatisfaction or disengagement. Still salvageable with focused CSM intervention.
+
+**Timeline:** Act within 1 week.
+
+**Steps:**
+
+1. **Root Cause Analysis (Day 1-3)**
+ - Review all health score dimensions to identify the primary drivers
+ - Pull support ticket history for patterns
+ - Check product usage trends for the past 90 days
+
+2. **CSM Outreach (Day 3-5)**
+ - Schedule a dedicated call with the customer (not a routine check-in)
+ - Open with empathy: "I've noticed some changes and want to make sure we're supporting you properly"
+ - Identify the top 3 customer concerns
+
+3. **30-Day Recovery Plan (Day 5-7)**
+ - Build a 30-day recovery plan with measurable checkpoints every week
+ - Include specific actions for each concern identified
+ - Share the plan with the customer for mutual commitment
+
+4. **Re-Engage Executive Sponsor (Week 2)**
+ - Request a meeting with the executive sponsor
+ - Align on business outcomes and how your product supports them
+ - Confirm continued sponsorship and address any political changes
+
+5. **Support Fast-Track (Ongoing)**
+ - Escalate any pending support tickets internally
+ - Assign a support point of contact for this account
+ - Provide weekly status updates on open issues
+
+6. **Progress Review (Week 3-4)**
+ - Review all metrics for improvement
+ - Adjust plan if specific interventions are not working
+ - If score drops to Critical: escalate to executive playbook
+
+**Success Criteria:** Risk score drops below 40 within 30 days. No new warning signals emerge.
+
+---
+
+### Medium Risk (Score 40-59)
+
+**Situation:** Early warning signs detected. Customer may not be aware of emerging issues. Proactive outreach prevents escalation.
+
+**Timeline:** Act within 2 weeks.
+
+**Steps:**
+
+1. **Data Review (Day 1-5)**
+ - Analyse which dimension(s) are pulling the score down
+ - Review recent support interactions for sentiment clues
+ - Check for any known product issues affecting this customer
+
+2. **Proactive Check-In (Week 1-2)**
+ - Schedule a "value check-in" call (position it as routine, not reactive)
+ - Share relevant success stories from similar customers
+ - Propose a training session or product walkthrough for underutilised features
+
+3. **Value Reinforcement (Week 2-3)**
+ - Send a customised ROI summary showing value delivered
+ - Highlight feature releases relevant to their use case
+ - Connect them with your customer community or user group
+
+4. **Monitoring (Week 3-4)**
+ - Increase monitoring frequency to bi-weekly
+ - Watch for improvement or continued decline
+ - If declining: move to High-risk playbook
+
+**Success Criteria:** Score stabilises above 50 or improves. No escalation to High risk.
+
+---
+
+### Low Risk (Score 0-39)
+
+**Situation:** Customer is healthy. Standard success cadence applies. Focus on value reinforcement and expansion readiness.
+
+**Timeline:** Standard touch cadence.
+
+**Steps:**
+
+1. **Maintain Cadence**
+ - Enterprise: Monthly strategic reviews, quarterly QBRs
+ - Mid-Market: Bi-monthly check-ins, semi-annual reviews
+ - SMB: Quarterly automated health updates, annual review
+
+2. **Proactive Communication**
+ - Share product updates and release notes
+ - Invite to webinars, conferences, and community events
+ - Share relevant industry insights and benchmarks
+
+3. **Expansion Readiness**
+ - Monitor for expansion signals (usage approaching limits, new use cases)
+ - Prepare expansion proposals when timing is right
+ - Position premium features and modules relevant to their needs
+
+4. **Renewal Preparation**
+ - Begin renewal preparation 90 days before contract end
+ - Build renewal proposal with value delivered summary
+ - Identify any terms or pricing adjustments needed
+
+**Success Criteria:** Customer remains in Green classification. Expansion conversations initiated when appropriate.
+
+---
+
+## Onboarding Playbook
+
+### Phase 1: Welcome and Setup (Day 1-14)
+
+| Day | Activity | Owner | Deliverable |
+|-----|----------|-------|-------------|
+| 1 | Welcome email and introduction | CSM | Welcome package sent |
+| 1-2 | Kickoff call | CSM + SE | Success plan drafted |
+| 3-5 | Technical setup and configuration | SE | Environment configured |
+| 5-7 | Admin training session | CSM | Admins trained |
+| 7-10 | Data migration (if applicable) | SE | Data validated |
+| 10-14 | Initial user training | CSM | Core team trained |
+
+### Phase 2: Activation (Day 15-30)
+
+| Day | Activity | Owner | Deliverable |
+|-----|----------|-------|-------------|
+| 15 | Activation check -- are users logging in? | CSM | Usage report |
+| 15-20 | Follow-up training for laggards | CSM | All users active |
+| 20-25 | First business outcome milestone | CSM | Milestone achieved |
+| 25-30 | 30-day review call | CSM | Review documented |
+
+**Critical Milestone:** Time to First Value must be under 30 days.
+
+### Phase 3: Adoption (Day 31-60)
+
+| Day | Activity | Owner | Deliverable |
+|-----|----------|-------|-------------|
+| 30-40 | Feature adoption expansion | CSM | New features in use |
+| 40-50 | Integration setup (if applicable) | SE | Integrations live |
+| 50-60 | Usage benchmarking vs. peers | CSM | Benchmark report |
+
+### Phase 4: Optimisation (Day 61-90)
+
+| Day | Activity | Owner | Deliverable |
+|-----|----------|-------|-------------|
+| 60-70 | Advanced use case workshop | CSM + SE | New use cases identified |
+| 70-80 | ROI measurement | CSM | ROI documented |
+| 80-90 | 90-day executive review | CSM | Transition to steady-state |
+
+**Gate:** Handoff from onboarding to ongoing CSM management. Health score must be Yellow or better.
+
+---
+
+## Renewal Playbook
+
+### 120 Days Before Renewal
+
+- Review contract terms and pricing
+- Assess current health score and trajectory
+- Identify any outstanding issues or concerns
+- Begin internal alignment on renewal strategy
+
+### 90 Days Before Renewal
+
+- Schedule renewal conversation with customer
+- Prepare value delivered summary (ROI, usage stats, milestones achieved)
+- Draft renewal proposal with recommended terms
+- If at-risk: escalate and begin risk mitigation
+
+### 60 Days Before Renewal
+
+- Present renewal proposal to customer
+- Negotiate terms if needed
+- Address any concerns raised during the process
+- Escalate blockers to leadership
+
+### 30 Days Before Renewal
+
+- Finalise contract terms
+- Obtain signatures
+- Plan for any post-renewal actions (expansion, migration)
+- Update CRM with renewal details
+
+### Post-Renewal
+
+- Confirm renewed contract in systems
+- Send thank-you and updated success plan
+- Schedule next QBR
+- Identify expansion opportunities
+
+---
+
+## Expansion Playbook
+
+### Identifying Expansion Signals
+
+| Signal | Expansion Type | Priority |
+|--------|---------------|----------|
+| Seat utilisation > 90% | Seat expansion | High |
+| Requests for features in higher tier | Tier upsell | High |
+| New department inquiries | Department expansion | Medium |
+| High adoption of existing modules | Module cross-sell | Medium |
+| Customer referencing competitors for missing features | Cross-sell | High |
+
+### Expansion Conversation Framework
+
+1. **Discovery:** "I noticed your team has been getting great value from [feature]. Have you considered how [new module] could help with [related business outcome]?"
+2. **Value Framing:** "Companies similar to yours who adopted [module] saw [specific metric improvement]."
+3. **Proposal:** "Based on your current usage, here's what the expansion would look like..."
+4. **Stakeholder Alignment:** Involve the economic buyer early. The champion can advocate, but the budget holder decides.
+5. **Close:** Coordinate with sales/account executive for commercial negotiation.
+
+---
+
+## Escalation Procedures
+
+### Internal Escalation Matrix
+
+| Trigger | Escalation Level | Response Time |
+|---------|-----------------|---------------|
+| Health score drops to Red | VP Customer Success | 24 hours |
+| Executive sponsor leaves | Director CS + AE | 48 hours |
+| Critical bug affecting customer | VP Engineering + VP CS | 4 hours |
+| Customer mentions competitor evaluation | VP CS + VP Sales | 24 hours |
+| Renewal at risk (60 days or less) | CRO/VP Sales | 24 hours |
+| Customer threatens legal action | Legal + VP CS | Immediate |
+
+### Escalation Communication Template
+
+**Subject:** [ESCALATION] {Customer Name} -- {Brief Description}
+
+**Body:**
+- Customer: {name}, {segment}, ${ARR}
+- Health Score: {score} ({classification})
+- Renewal Date: {date}
+- Issue Summary: {2-3 sentences}
+- Warning Signals: {list}
+- Recommended Action: {specific next step}
+- Urgency: {critical/high/medium}
+
+---
+
+**Last Updated:** February 2026
diff --git a/skills/business-growth/customer-success-manager/references/health-scoring-framework.md b/skills/business-growth/customer-success-manager/references/health-scoring-framework.md
new file mode 100644
index 00000000..a38b1834
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/references/health-scoring-framework.md
@@ -0,0 +1,184 @@
+# Health Scoring Framework
+
+Complete methodology for multi-dimensional customer health scoring in SaaS customer success.
+
+---
+
+## Overview
+
+Customer health scoring is the foundation of proactive customer success management. A well-calibrated health score enables CSMs to prioritise their portfolio, identify emerging risks before they become churn events, and allocate resources where they will have the greatest impact.
+
+This framework uses a weighted, multi-dimensional approach that scores customers across four key areas: usage, engagement, support, and relationship. Each dimension contributes to an overall health score (0-100) that classifies accounts as Green (healthy), Yellow (needs attention), or Red (at risk).
+
+---
+
+## Scoring Dimensions
+
+### 1. Usage (Weight: 30%)
+
+Usage metrics are the strongest leading indicator of customer health. Customers who are not using the product are not deriving value and are at elevated churn risk.
+
+| Metric | Definition | Scoring Method |
+|--------|-----------|----------------|
+| Login Frequency | Percentage of expected login days with actual logins | (actual / target) * 100, capped at 100 |
+| Feature Adoption | Percentage of available features actively used | (adopted / available) * 100, capped at 100 |
+| DAU/MAU Ratio | Daily active users divided by monthly active users | (actual / target) * 100, capped at 100 |
+
+**Sub-weights within Usage:**
+- Login Frequency: 35%
+- Feature Adoption: 40%
+- DAU/MAU Ratio: 25%
+
+**Why 30% weight:** Usage is the most objective, data-driven signal. Declining usage almost always precedes churn. However, some customers may have seasonal usage patterns, which is why it is not weighted even higher.
+
+### 2. Engagement (Weight: 25%)
+
+Engagement measures how actively the customer participates in the relationship beyond just product usage.
+
+| Metric | Definition | Scoring Method |
+|--------|-----------|----------------|
+| Support Ticket Volume | Number of support tickets in the period | Inverse score: (1 - actual/max) * 100 |
+| Meeting Attendance | Percentage of scheduled meetings attended | (actual / target) * 100, capped at 100 |
+| NPS Score | Net Promoter Score response (0-10) | (actual / target) * 100, capped at 100 |
+| CSAT Score | Customer Satisfaction score (1-5) | (actual / target) * 100, capped at 100 |
+
+**Sub-weights within Engagement:**
+- Support Ticket Volume: 20% (inverse -- fewer tickets is better)
+- Meeting Attendance: 30%
+- NPS Score: 25%
+- CSAT Score: 25%
+
+**Why 25% weight:** Engagement signals complement usage data. A customer who attends meetings but does not use the product may be in an evaluation phase. A customer who uses the product but skips meetings may be becoming self-sufficient -- or disengaging.
+
+### 3. Support (Weight: 20%)
+
+Support health measures the quality of the customer's support experience, which directly impacts satisfaction and renewal likelihood.
+
+| Metric | Definition | Scoring Method |
+|--------|-----------|----------------|
+| Open Tickets | Number of currently unresolved tickets | Inverse score: (1 - actual/max) * 100 |
+| Escalation Rate | Percentage of tickets escalated | Inverse score: (1 - actual/max) * 100 |
+| Avg Resolution Time | Average hours to resolve tickets | Inverse score: (1 - actual/max) * 100 |
+
+**Sub-weights within Support:**
+- Open Tickets: 35%
+- Escalation Rate: 35%
+- Resolution Time: 30%
+
+**Why 20% weight:** Support issues are lagging indicators -- they tell you there is already a problem. However, unresolved support issues are a strong predictor of churn, especially when combined with declining engagement.
+
+### 4. Relationship (Weight: 25%)
+
+Relationship health measures the strength and depth of the human connection between the customer and your organisation.
+
+| Metric | Definition | Scoring Method |
+|--------|-----------|----------------|
+| Executive Sponsor Engagement | Engagement level of exec sponsor (0-100) | (actual / target) * 100, capped at 100 |
+| Multi-Threading Depth | Number of stakeholder contacts | (actual / target) * 100, capped at 100 |
+| Renewal Sentiment | Qualitative sentiment assessment | Mapped to score: positive=100, neutral=60, negative=20, unknown=50 |
+
+**Sub-weights within Relationship:**
+- Executive Sponsor Engagement: 35%
+- Multi-Threading Depth: 30%
+- Renewal Sentiment: 35%
+
+**Why 25% weight:** Relationship strength is the most important defence against competitive displacement. A customer with strong relationships will give you more chances to fix problems. A customer with weak relationships may leave without warning.
+
+---
+
+## Classification Thresholds
+
+### Standard Thresholds
+
+| Classification | Score Range | Meaning | Action |
+|---------------|-------------|---------|--------|
+| Green | 75-100 | Customer is healthy and achieving value | Standard cadence, focus on expansion |
+| Yellow | 50-74 | Customer needs attention | Increase touch frequency, investigate root causes |
+| Red | 0-49 | Customer is at risk | Immediate intervention, create save plan |
+
+### Segment-Adjusted Thresholds
+
+Enterprise customers typically have higher expectations and more complex deployments, which means a higher bar for "healthy." SMB customers may have simpler use cases and lower engagement expectations.
+
+| Segment | Green Threshold | Yellow Threshold | Red Threshold |
+|---------|----------------|------------------|---------------|
+| Enterprise | 75-100 | 50-74 | 0-49 |
+| Mid-Market | 70-100 | 45-69 | 0-44 |
+| SMB | 65-100 | 40-64 | 0-39 |
+
+### Segment-Specific Benchmarks
+
+Each metric target is calibrated per segment. Enterprise customers are expected to have higher login frequency, attendance, and sponsor engagement. SMB customers have lower targets but still meaningful thresholds.
+
+**Example Calibration:**
+- Enterprise login frequency target: 90% (high-touch, deeply embedded)
+- Mid-Market login frequency target: 80% (balanced engagement)
+- SMB login frequency target: 70% (self-serve oriented)
+
+---
+
+## Trend Analysis
+
+A single health score snapshot is useful. A health score trend is actionable.
+
+### Trend Classification
+
+| Trend | Criteria | Implication |
+|-------|----------|-------------|
+| Improving | Current > Previous by 5+ points | Positive trajectory, reinforce what is working |
+| Stable | Within +/- 5 points | Maintain current approach |
+| Declining | Current < Previous by 5+ points | Investigate and intervene |
+| No Data | No previous period available | Establish baseline |
+
+### Trend Priority Matrix
+
+| Current Score | Trend | Priority |
+|--------------|-------|----------|
+| Green | Declining | HIGH -- intervene before it drops further |
+| Yellow | Declining | CRITICAL -- trajectory leads to Red |
+| Yellow | Improving | MEDIUM -- reinforce positive momentum |
+| Red | Improving | HIGH -- support the recovery |
+| Red | Stable | CRITICAL -- needs new intervention approach |
+
+---
+
+## Calibration Guidelines
+
+### When to Recalibrate
+
+1. **After major product changes**: New features may change what "good usage" looks like
+2. **Seasonal patterns**: Some industries have cyclical usage (retail holiday season, fiscal year end)
+3. **Portfolio composition changes**: If you add many SMB customers, the overall averages shift
+4. **After churn events**: Review whether the health score predicted the churn
+
+### Calibration Process
+
+1. Export health scores for all customers over the past 12 months
+2. Identify all churn events in the same period
+3. Calculate the average health score of churned customers 90, 60, and 30 days before churn
+4. Adjust thresholds so that churned customers would have been classified as Yellow or Red at least 60 days before churn
+5. Validate with a holdout set of recent data
+
+### Common Calibration Pitfalls
+
+- **Threshold creep**: Gradually lowering Green thresholds to make the portfolio look healthier
+- **Over-weighting lagging indicators**: Support metrics react after the damage is done
+- **Ignoring segment differences**: Using one threshold for all segments
+- **Sentiment bias**: Over-relying on subjective renewal sentiment
+
+---
+
+## Implementation Checklist
+
+1. Define data sources for each metric (CRM, product analytics, support system)
+2. Establish data refresh frequency (daily for usage, weekly for engagement)
+3. Configure segment benchmarks for your customer base
+4. Set initial thresholds using industry defaults (provided above)
+5. Run a 30-day pilot with manual review of edge cases
+6. Calibrate thresholds based on pilot results
+7. Automate scoring and alerting
+8. Review and recalibrate quarterly
+
+---
+
+**Last Updated:** February 2026
diff --git a/skills/business-growth/customer-success-manager/scripts/churn_risk_analyzer.py b/skills/business-growth/customer-success-manager/scripts/churn_risk_analyzer.py
new file mode 100644
index 00000000..62329cf2
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/scripts/churn_risk_analyzer.py
@@ -0,0 +1,487 @@
+#!/usr/bin/env python3
+"""
+Churn Risk Analyzer
+
+Identifies at-risk customer accounts by scoring behavioral signals across
+usage decline, engagement drop, support issues, relationship signals, and
+commercial factors. Produces risk tiers with intervention playbooks and
+time-to-renewal urgency multipliers.
+
+Usage:
+ python churn_risk_analyzer.py customer_data.json
+ python churn_risk_analyzer.py customer_data.json --format json
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+RISK_SIGNAL_WEIGHTS: Dict[str, float] = {
+ "usage_decline": 0.30,
+ "engagement_drop": 0.25,
+ "support_issues": 0.20,
+ "relationship_signals": 0.15,
+ "commercial_factors": 0.10,
+}
+
+RISK_TIERS: List[Dict[str, Any]] = [
+ {"name": "critical", "min": 80, "max": 100, "label": "CRITICAL", "action": "Immediate executive escalation"},
+ {"name": "high", "min": 60, "max": 79, "label": "HIGH", "action": "Urgent CSM intervention"},
+ {"name": "medium", "min": 40, "max": 59, "label": "MEDIUM", "action": "Proactive outreach"},
+ {"name": "low", "min": 0, "max": 39, "label": "LOW", "action": "Standard monitoring"},
+]
+
+WARNING_SEVERITY: Dict[str, int] = {
+ "critical": 4,
+ "high": 3,
+ "medium": 2,
+ "low": 1,
+}
+
+# Intervention playbooks per tier
+INTERVENTION_PLAYBOOKS: Dict[str, List[str]] = {
+ "critical": [
+ "Schedule executive-to-executive call within 48 hours",
+ "Create detailed save plan with specific value milestones",
+ "Offer concessions or contract restructuring if needed",
+ "Assign dedicated rescue team (CSM + Solutions Engineer)",
+ "Daily internal stand-up on account status until stabilised",
+ "Prepare competitive displacement defence strategy",
+ ],
+ "high": [
+ "Schedule urgent CSM call within 1 week",
+ "Conduct root cause analysis on declining metrics",
+ "Build 30-day recovery plan with measurable checkpoints",
+ "Re-engage executive sponsor for alignment meeting",
+ "Accelerate any pending feature requests or bug fixes",
+ "Increase touch frequency to weekly until improvement",
+ ],
+ "medium": [
+ "Schedule proactive check-in within 2 weeks",
+ "Share relevant success stories and best practices",
+ "Propose training session or product walkthrough",
+ "Review current usage against success plan goals",
+ "Identify and address any unvoiced concerns",
+ "Bi-weekly monitoring until score improves to Low",
+ ],
+ "low": [
+ "Maintain standard touch cadence",
+ "Share product updates and new feature announcements",
+ "Monitor health score trends monthly",
+ "Proactively share relevant industry insights",
+ "Prepare for upcoming renewal conversations (if within 90 days)",
+ ],
+}
+
+SATISFACTION_TREND_SCORES: Dict[str, float] = {
+ "improving": 10.0,
+ "stable": 30.0,
+ "declining": 70.0,
+ "critical": 95.0,
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Return numerator / denominator, or *default* when denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def clamp(value: float, lo: float = 0.0, hi: float = 100.0) -> float:
+ """Clamp *value* between *lo* and *hi*."""
+ return max(lo, min(hi, value))
+
+
+def days_until(date_str: Optional[str]) -> Optional[int]:
+ """Return days from today until *date_str* (ISO format), or None."""
+ if not date_str:
+ return None
+ try:
+ target = datetime.strptime(date_str[:10], "%Y-%m-%d")
+ delta = (target - datetime.now()).days
+ return max(delta, 0)
+ except (ValueError, TypeError):
+ return None
+
+
+def renewal_urgency_multiplier(days_remaining: Optional[int]) -> float:
+ """Return a multiplier (1.0 - 1.5) based on proximity to renewal.
+
+ Closer renewals amplify the risk score.
+ """
+ if days_remaining is None:
+ return 1.0
+ if days_remaining <= 30:
+ return 1.5
+ elif days_remaining <= 60:
+ return 1.35
+ elif days_remaining <= 90:
+ return 1.2
+ elif days_remaining <= 180:
+ return 1.1
+ return 1.0
+
+
+def get_risk_tier(score: float) -> Dict[str, Any]:
+ """Return the risk tier dict matching the score."""
+ for tier in RISK_TIERS:
+ if tier["min"] <= score <= tier["max"]:
+ return tier
+ return RISK_TIERS[-1] # default to low
+
+
+# ---------------------------------------------------------------------------
+# Signal Scoring
+# ---------------------------------------------------------------------------
+
+
+def score_usage_decline(data: Dict[str, Any]) -> Tuple[float, List[Dict[str, str]]]:
+ """Score usage decline signals (0-100, higher = more risk)."""
+ warnings: List[Dict[str, str]] = []
+
+ login_trend = data.get("login_trend", 0) # negative = decline
+ feature_change = data.get("feature_adoption_change", 0)
+ dau_mau_change = data.get("dau_mau_change", 0)
+
+ # Convert declines to risk scores (0-100)
+ login_risk = clamp(abs(min(login_trend, 0)) * 3.0) # -33% => 100
+ feature_risk = clamp(abs(min(feature_change, 0)) * 4.0) # -25% => 100
+ dau_mau_risk = clamp(abs(min(dau_mau_change, 0)) * 500) # -0.20 => 100
+
+ score = round(login_risk * 0.40 + feature_risk * 0.35 + dau_mau_risk * 0.25, 1)
+
+ if login_trend <= -20:
+ warnings.append({"severity": "critical", "signal": f"Login frequency dropped {abs(login_trend)}%"})
+ elif login_trend <= -10:
+ warnings.append({"severity": "high", "signal": f"Login frequency declined {abs(login_trend)}%"})
+ elif login_trend < -5:
+ warnings.append({"severity": "medium", "signal": f"Login frequency dipping {abs(login_trend)}%"})
+
+ if feature_change <= -15:
+ warnings.append({"severity": "high", "signal": f"Feature adoption dropped {abs(feature_change)}%"})
+ elif feature_change < -5:
+ warnings.append({"severity": "medium", "signal": f"Feature adoption declining {abs(feature_change)}%"})
+
+ if dau_mau_change <= -0.10:
+ warnings.append({"severity": "high", "signal": f"DAU/MAU ratio fell by {abs(dau_mau_change):.2f}"})
+
+ return score, warnings
+
+
+def score_engagement_drop(data: Dict[str, Any]) -> Tuple[float, List[Dict[str, str]]]:
+ """Score engagement drop signals (0-100, higher = more risk)."""
+ warnings: List[Dict[str, str]] = []
+
+ cancellations = data.get("meeting_cancellations", 0)
+ response_days = data.get("response_time_days", 1)
+ nps_change = data.get("nps_change", 0)
+
+ cancel_risk = clamp(cancellations * 25.0) # 4 cancellations => 100
+ response_risk = clamp((response_days - 1) * 15.0) # 1 day baseline; 7+ days => 90+
+ nps_risk = clamp(abs(min(nps_change, 0)) * 20.0) # -5 => 100
+
+ score = round(cancel_risk * 0.30 + response_risk * 0.35 + nps_risk * 0.35, 1)
+
+ if cancellations >= 3:
+ warnings.append({"severity": "critical", "signal": f"{cancellations} meeting cancellations -- customer disengaging"})
+ elif cancellations >= 2:
+ warnings.append({"severity": "high", "signal": f"{cancellations} meeting cancellations recently"})
+
+ if response_days >= 7:
+ warnings.append({"severity": "critical", "signal": f"Customer response time: {response_days} days -- going dark"})
+ elif response_days >= 4:
+ warnings.append({"severity": "high", "signal": f"Customer response time increasing: {response_days} days"})
+
+ if nps_change <= -4:
+ warnings.append({"severity": "critical", "signal": f"NPS dropped by {abs(nps_change)} points"})
+ elif nps_change <= -2:
+ warnings.append({"severity": "high", "signal": f"NPS declined by {abs(nps_change)} points"})
+
+ return score, warnings
+
+
+def score_support_issues(data: Dict[str, Any]) -> Tuple[float, List[Dict[str, str]]]:
+ """Score support-related risk signals (0-100, higher = more risk)."""
+ warnings: List[Dict[str, str]] = []
+
+ escalations = data.get("open_escalations", 0)
+ critical_unresolved = data.get("unresolved_critical", 0)
+ sat_trend = data.get("satisfaction_trend", "stable").lower()
+
+ esc_risk = clamp(escalations * 35.0) # 3 escalations => 100
+ critical_risk = clamp(critical_unresolved * 50.0) # 2 unresolved critical => 100
+ sat_risk = SATISFACTION_TREND_SCORES.get(sat_trend, 30.0)
+
+ score = round(esc_risk * 0.35 + critical_risk * 0.35 + sat_risk * 0.30, 1)
+
+ if critical_unresolved >= 2:
+ warnings.append({"severity": "critical", "signal": f"{critical_unresolved} unresolved critical support tickets"})
+ elif critical_unresolved >= 1:
+ warnings.append({"severity": "high", "signal": "Unresolved critical support ticket"})
+
+ if escalations >= 2:
+ warnings.append({"severity": "high", "signal": f"{escalations} open escalations"})
+ elif escalations >= 1:
+ warnings.append({"severity": "medium", "signal": "Open support escalation"})
+
+ if sat_trend == "critical":
+ warnings.append({"severity": "critical", "signal": "Support satisfaction at critical levels"})
+ elif sat_trend == "declining":
+ warnings.append({"severity": "high", "signal": "Support satisfaction trending down"})
+
+ return score, warnings
+
+
+def score_relationship_signals(data: Dict[str, Any]) -> Tuple[float, List[Dict[str, str]]]:
+ """Score relationship risk signals (0-100, higher = more risk)."""
+ warnings: List[Dict[str, str]] = []
+ risk_points = 0.0
+
+ champion_left = data.get("champion_left", False)
+ sponsor_change = data.get("sponsor_change", False)
+ competitor_mentions = data.get("competitor_mentions", 0)
+
+ if champion_left:
+ risk_points += 45.0
+ warnings.append({"severity": "critical", "signal": "Internal champion has left the organisation"})
+
+ if sponsor_change:
+ risk_points += 30.0
+ warnings.append({"severity": "high", "signal": "Executive sponsor change detected"})
+
+ if competitor_mentions >= 3:
+ risk_points += 35.0
+ warnings.append({"severity": "critical", "signal": f"Customer mentioned competitors {competitor_mentions} times"})
+ elif competitor_mentions >= 1:
+ risk_points += competitor_mentions * 12.0
+ warnings.append({"severity": "medium", "signal": f"Customer mentioned competitor {competitor_mentions} time(s)"})
+
+ score = clamp(risk_points)
+ return round(score, 1), warnings
+
+
+def score_commercial_factors(data: Dict[str, Any]) -> Tuple[float, List[Dict[str, str]]]:
+ """Score commercial risk factors (0-100, higher = more risk)."""
+ warnings: List[Dict[str, str]] = []
+ risk_points = 0.0
+
+ contract_type = data.get("contract_type", "annual").lower()
+ pricing_complaints = data.get("pricing_complaints", False)
+ budget_cuts = data.get("budget_cuts_mentioned", False)
+
+ if contract_type == "month-to-month":
+ risk_points += 30.0
+ warnings.append({"severity": "medium", "signal": "Month-to-month contract -- low switching cost"})
+ elif contract_type == "quarterly":
+ risk_points += 15.0
+
+ if pricing_complaints:
+ risk_points += 35.0
+ warnings.append({"severity": "high", "signal": "Customer has raised pricing complaints"})
+
+ if budget_cuts:
+ risk_points += 40.0
+ warnings.append({"severity": "high", "signal": "Customer mentioned budget cuts or cost reduction"})
+
+ score = clamp(risk_points)
+ return round(score, 1), warnings
+
+
+# ---------------------------------------------------------------------------
+# Main Analysis
+# ---------------------------------------------------------------------------
+
+
+def analyse_churn_risk(customer: Dict[str, Any]) -> Dict[str, Any]:
+ """Analyse churn risk for a single customer."""
+ usage_score, usage_warnings = score_usage_decline(customer.get("usage_decline", {}))
+ engagement_score, engagement_warnings = score_engagement_drop(customer.get("engagement_drop", {}))
+ support_score, support_warnings = score_support_issues(customer.get("support_issues", {}))
+ relationship_score, relationship_warnings = score_relationship_signals(customer.get("relationship_signals", {}))
+ commercial_score, commercial_warnings = score_commercial_factors(customer.get("commercial_factors", {}))
+
+ # Weighted raw score
+ raw_score = (
+ usage_score * RISK_SIGNAL_WEIGHTS["usage_decline"]
+ + engagement_score * RISK_SIGNAL_WEIGHTS["engagement_drop"]
+ + support_score * RISK_SIGNAL_WEIGHTS["support_issues"]
+ + relationship_score * RISK_SIGNAL_WEIGHTS["relationship_signals"]
+ + commercial_score * RISK_SIGNAL_WEIGHTS["commercial_factors"]
+ )
+
+ # Apply renewal urgency multiplier
+ remaining = days_until(customer.get("contract_end_date"))
+ multiplier = renewal_urgency_multiplier(remaining)
+ adjusted_score = clamp(round(raw_score * multiplier, 1))
+
+ tier = get_risk_tier(adjusted_score)
+
+ # Collect and sort warnings by severity
+ all_warnings = usage_warnings + engagement_warnings + support_warnings + relationship_warnings + commercial_warnings
+ all_warnings.sort(key=lambda w: WARNING_SEVERITY.get(w["severity"], 0), reverse=True)
+
+ playbook = INTERVENTION_PLAYBOOKS.get(tier["name"], [])
+
+ return {
+ "customer_id": customer.get("customer_id", "unknown"),
+ "name": customer.get("name", "Unknown"),
+ "segment": customer.get("segment", "unknown"),
+ "arr": customer.get("arr", 0),
+ "risk_score": adjusted_score,
+ "raw_score": round(raw_score, 1),
+ "risk_tier": tier["name"],
+ "risk_label": tier["label"],
+ "urgency_multiplier": multiplier,
+ "days_to_renewal": remaining,
+ "signal_scores": {
+ "usage_decline": {"score": usage_score, "weight": "30%"},
+ "engagement_drop": {"score": engagement_score, "weight": "25%"},
+ "support_issues": {"score": support_score, "weight": "20%"},
+ "relationship_signals": {"score": relationship_score, "weight": "15%"},
+ "commercial_factors": {"score": commercial_score, "weight": "10%"},
+ },
+ "warning_signals": all_warnings,
+ "recommended_actions": playbook,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Output Formatting
+# ---------------------------------------------------------------------------
+
+
+def format_text(results: List[Dict[str, Any]]) -> str:
+ """Format results as human-readable text."""
+ lines: List[str] = []
+ lines.append("=" * 72)
+ lines.append("CHURN RISK ANALYSIS REPORT")
+ lines.append("=" * 72)
+ lines.append("")
+
+ total = len(results)
+ critical_count = sum(1 for r in results if r["risk_tier"] == "critical")
+ high_count = sum(1 for r in results if r["risk_tier"] == "high")
+ medium_count = sum(1 for r in results if r["risk_tier"] == "medium")
+ low_count = sum(1 for r in results if r["risk_tier"] == "low")
+ total_arr_at_risk = sum(r["arr"] for r in results if r["risk_tier"] in ("critical", "high"))
+
+ lines.append(f"Portfolio Summary: {total} customers analysed")
+ lines.append(f" Critical Risk: {critical_count}")
+ lines.append(f" High Risk: {high_count}")
+ lines.append(f" Medium Risk: {medium_count}")
+ lines.append(f" Low Risk: {low_count}")
+ lines.append(f" ARR at Risk (Critical + High): ${total_arr_at_risk:,.0f}")
+ lines.append("")
+
+ # Sort by risk score descending
+ sorted_results = sorted(results, key=lambda r: r["risk_score"], reverse=True)
+
+ for r in sorted_results:
+ lines.append("-" * 72)
+ lines.append(f"Customer: {r['name']} ({r['customer_id']})")
+ lines.append(f"Segment: {r['segment'].title()} | ARR: ${r['arr']:,.0f}")
+ renewal_str = f"{r['days_to_renewal']} days" if r["days_to_renewal"] is not None else "N/A"
+ lines.append(f"Risk Score: {r['risk_score']}/100 [{r['risk_label']}] | Renewal: {renewal_str}")
+ if r["urgency_multiplier"] > 1.0:
+ lines.append(f" ** Urgency multiplier applied: {r['urgency_multiplier']}x (renewal approaching)")
+ lines.append("")
+
+ lines.append(" Signal Scores:")
+ for signal_name, signal_data in r["signal_scores"].items():
+ display_name = signal_name.replace("_", " ").title()
+ lines.append(f" {display_name:25s} {signal_data['score']:6.1f}/100 ({signal_data['weight']})")
+
+ if r["warning_signals"]:
+ lines.append("")
+ lines.append(" Warning Signals:")
+ for w in r["warning_signals"]:
+ severity_tag = w["severity"].upper()
+ lines.append(f" [{severity_tag}] {w['signal']}")
+
+ if r["recommended_actions"]:
+ lines.append("")
+ lines.append(" Recommended Actions:")
+ for i, action in enumerate(r["recommended_actions"], 1):
+ lines.append(f" {i}. {action}")
+
+ lines.append("")
+
+ lines.append("=" * 72)
+ return "\n".join(lines)
+
+
+def format_json(results: List[Dict[str, Any]]) -> str:
+ """Format results as JSON."""
+ total = len(results)
+ output = {
+ "report": "churn_risk_analysis",
+ "summary": {
+ "total_customers": total,
+ "critical_count": sum(1 for r in results if r["risk_tier"] == "critical"),
+ "high_count": sum(1 for r in results if r["risk_tier"] == "high"),
+ "medium_count": sum(1 for r in results if r["risk_tier"] == "medium"),
+ "low_count": sum(1 for r in results if r["risk_tier"] == "low"),
+ "total_arr_at_risk": sum(r["arr"] for r in results if r["risk_tier"] in ("critical", "high")),
+ },
+ "customers": sorted(results, key=lambda r: r["risk_score"], reverse=True),
+ }
+ return json.dumps(output, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description="Analyse churn risk with behavioral signal detection and intervention recommendations."
+ )
+ parser.add_argument("input_file", help="Path to JSON file containing customer data")
+ parser.add_argument(
+ "--format",
+ choices=["text", "json"],
+ default="text",
+ dest="output_format",
+ help="Output format (default: text)",
+ )
+ args = parser.parse_args()
+
+ try:
+ with open(args.input_file, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input_file}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input_file}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ customers = data.get("customers", [])
+ if not customers:
+ print("Error: No customer records found in input file.", file=sys.stderr)
+ sys.exit(1)
+
+ results = [analyse_churn_risk(c) for c in customers]
+
+ if args.output_format == "json":
+ print(format_json(results))
+ else:
+ print(format_text(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/business-growth/customer-success-manager/scripts/expansion_opportunity_scorer.py b/skills/business-growth/customer-success-manager/scripts/expansion_opportunity_scorer.py
new file mode 100644
index 00000000..7f96c7cf
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/scripts/expansion_opportunity_scorer.py
@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+"""
+Expansion Opportunity Scorer
+
+Analyses customer product adoption depth, maps whitespace for unused
+features/products, estimates revenue opportunities, and prioritises
+expansion plays by effort vs impact.
+
+Usage:
+ python expansion_opportunity_scorer.py customer_data.json
+ python expansion_opportunity_scorer.py customer_data.json --format json
+"""
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Tier pricing multipliers (relative to current plan price)
+TIER_UPLIFT: Dict[str, float] = {
+ "starter": 1.0,
+ "professional": 1.8,
+ "enterprise": 3.0,
+ "enterprise_plus": 4.5,
+}
+
+# Module revenue estimates as a fraction of base ARR
+MODULE_REVENUE_FRACTION: Dict[str, float] = {
+ "core_platform": 0.00, # Already included in base
+ "analytics_module": 0.15,
+ "integrations_module": 0.12,
+ "api_access": 0.10,
+ "advanced_reporting": 0.18,
+ "security_module": 0.20,
+ "automation_module": 0.15,
+ "collaboration_module": 0.10,
+ "data_export": 0.08,
+ "custom_workflows": 0.22,
+ "sso_module": 0.08,
+ "audit_module": 0.10,
+}
+
+# Effort classification for different expansion types
+EFFORT_MAP: Dict[str, str] = {
+ "upsell_tier": "medium",
+ "cross_sell_module": "low",
+ "seat_expansion": "low",
+ "department_expansion": "high",
+}
+
+# Usage thresholds for recommendations
+HIGH_USAGE_THRESHOLD = 75 # % usage indicates readiness for more
+LOW_ADOPTION_THRESHOLD = 30 # % usage is too low to push expansion there
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Return numerator / denominator, or *default* when denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def clamp(value: float, lo: float = 0.0, hi: float = 100.0) -> float:
+ """Clamp *value* between *lo* and *hi*."""
+ return max(lo, min(hi, value))
+
+
+def estimate_seat_expansion_revenue(
+ arr: float, licensed: int, active: int, segment: str
+) -> Tuple[float, str]:
+ """Estimate revenue from seat expansion.
+
+ Returns (estimated_revenue, rationale).
+ """
+ utilisation = safe_divide(active, licensed)
+ if utilisation >= 0.90:
+ # Near capacity -- likely needs more seats
+ growth_factor = {"enterprise": 0.25, "mid-market": 0.20, "smb": 0.15}
+ factor = growth_factor.get(segment.lower(), 0.15)
+ revenue = round(arr * factor, 0)
+ return revenue, f"Seat utilisation at {utilisation:.0%} -- likely needs {int(licensed * factor)} additional seats"
+ return 0.0, f"Seat utilisation at {utilisation:.0%} -- not yet at expansion threshold"
+
+
+def estimate_tier_upgrade_revenue(
+ arr: float, current_tier: str, available_tiers: List[str]
+) -> Tuple[float, Optional[str], str]:
+ """Estimate revenue from tier upgrade.
+
+ Returns (estimated_revenue, target_tier, rationale).
+ """
+ current_mult = TIER_UPLIFT.get(current_tier.lower(), 1.0)
+ best_revenue = 0.0
+ best_tier = None
+ rationale = "Already on highest tier"
+
+ for tier in available_tiers:
+ tier_mult = TIER_UPLIFT.get(tier.lower(), 1.0)
+ if tier_mult > current_mult:
+ # Calculate revenue as the incremental ARR from upgrading
+ base_arr = safe_divide(arr, current_mult)
+ upgrade_arr = base_arr * tier_mult
+ incremental = upgrade_arr - arr
+ if incremental > best_revenue:
+ # Pick the next tier up (not skip tiers)
+ if best_tier is None or tier_mult < TIER_UPLIFT.get(best_tier.lower(), 999):
+ best_revenue = round(incremental, 0)
+ best_tier = tier
+ rationale = f"Upgrade from {current_tier} to {tier} adds ${incremental:,.0f} ARR"
+
+ return best_revenue, best_tier, rationale
+
+
+def estimate_module_revenue(
+ arr: float, product_usage: Dict[str, Dict[str, Any]]
+) -> List[Dict[str, Any]]:
+ """Identify cross-sell opportunities from unadopted modules.
+
+ Returns list of opportunity dicts.
+ """
+ opportunities: List[Dict[str, Any]] = []
+
+ for module_name, module_data in product_usage.items():
+ adopted = module_data.get("adopted", False)
+ usage_pct = module_data.get("usage_pct", 0)
+ fraction = MODULE_REVENUE_FRACTION.get(module_name.lower(), 0.10)
+
+ if not adopted and fraction > 0:
+ revenue = round(arr * fraction, 0)
+ opportunities.append({
+ "module": module_name,
+ "type": "cross_sell",
+ "estimated_revenue": revenue,
+ "effort": "low",
+ "rationale": f"Module not adopted -- ${revenue:,.0f} potential ARR",
+ })
+ elif adopted and usage_pct < LOW_ADOPTION_THRESHOLD and fraction > 0:
+ # Already adopted but underutilised -- focus on enablement, not expansion
+ pass # Skip -- needs enablement, not a sales motion
+
+ return opportunities
+
+
+def estimate_department_expansion_revenue(
+ arr: float,
+ current_departments: List[str],
+ potential_departments: List[str],
+ segment: str,
+) -> List[Dict[str, Any]]:
+ """Estimate revenue from expanding to new departments."""
+ opportunities: List[Dict[str, Any]] = []
+ current_set = {d.lower() for d in current_departments}
+ per_dept_estimate = safe_divide(arr, max(len(current_departments), 1))
+
+ for dept in potential_departments:
+ if dept.lower() not in current_set:
+ # Estimate each new department at the average per-department ARR
+ revenue = round(per_dept_estimate * 0.8, 0) # Slight discount for new dept
+ opportunities.append({
+ "department": dept,
+ "type": "expansion",
+ "estimated_revenue": revenue,
+ "effort": "high",
+ "rationale": f"Expand to {dept} department -- est. ${revenue:,.0f} ARR",
+ })
+
+ return opportunities
+
+
+# ---------------------------------------------------------------------------
+# Priority Scoring
+# ---------------------------------------------------------------------------
+
+
+def priority_score(revenue: float, effort: str) -> float:
+ """Calculate priority score (higher = better).
+
+ Favours high revenue with low effort.
+ """
+ effort_multiplier = {"low": 3.0, "medium": 2.0, "high": 1.0}
+ mult = effort_multiplier.get(effort.lower(), 1.0)
+ # Normalise revenue to a 0-100 scale (assume max single opportunity is $200k)
+ rev_score = clamp(safe_divide(revenue, 2000.0)) # $200k => 100
+ return round(rev_score * mult, 1)
+
+
+# ---------------------------------------------------------------------------
+# Main Analysis
+# ---------------------------------------------------------------------------
+
+
+def analyse_expansion(customer: Dict[str, Any]) -> Dict[str, Any]:
+ """Analyse expansion opportunities for a single customer."""
+ arr = customer.get("arr", 0)
+ segment = customer.get("segment", "mid-market").lower()
+ contract = customer.get("contract", {})
+ product_usage = customer.get("product_usage", {})
+ departments = customer.get("departments", {})
+
+ all_opportunities: List[Dict[str, Any]] = []
+
+ # 1. Seat expansion
+ licensed = contract.get("licensed_seats", 0)
+ active = contract.get("active_seats", 0)
+ seat_rev, seat_rationale = estimate_seat_expansion_revenue(arr, licensed, active, segment)
+ if seat_rev > 0:
+ all_opportunities.append({
+ "type": "expansion",
+ "category": "seat_expansion",
+ "estimated_revenue": seat_rev,
+ "effort": "low",
+ "rationale": seat_rationale,
+ "priority_score": priority_score(seat_rev, "low"),
+ })
+
+ # 2. Tier upgrade
+ current_tier = contract.get("plan_tier", "").lower()
+ available_tiers = contract.get("available_tiers", [])
+ tier_rev, target_tier, tier_rationale = estimate_tier_upgrade_revenue(arr, current_tier, available_tiers)
+ if tier_rev > 0 and target_tier:
+ all_opportunities.append({
+ "type": "upsell",
+ "category": "tier_upgrade",
+ "target_tier": target_tier,
+ "estimated_revenue": tier_rev,
+ "effort": "medium",
+ "rationale": tier_rationale,
+ "priority_score": priority_score(tier_rev, "medium"),
+ })
+
+ # 3. Module cross-sell
+ module_opps = estimate_module_revenue(arr, product_usage)
+ for opp in module_opps:
+ opp["category"] = "module_cross_sell"
+ opp["priority_score"] = priority_score(opp["estimated_revenue"], opp["effort"])
+ all_opportunities.append(opp)
+
+ # 4. Department expansion
+ current_depts = departments.get("current", [])
+ potential_depts = departments.get("potential", [])
+ dept_opps = estimate_department_expansion_revenue(arr, current_depts, potential_depts, segment)
+ for opp in dept_opps:
+ opp["category"] = "department_expansion"
+ opp["priority_score"] = priority_score(opp["estimated_revenue"], opp["effort"])
+ all_opportunities.append(opp)
+
+ # Sort by priority score descending
+ all_opportunities.sort(key=lambda o: o["priority_score"], reverse=True)
+
+ # Adoption depth summary
+ total_modules = len(product_usage)
+ adopted_modules = sum(1 for m in product_usage.values() if m.get("adopted", False))
+ avg_usage = round(
+ safe_divide(
+ sum(m.get("usage_pct", 0) for m in product_usage.values() if m.get("adopted", False)),
+ max(adopted_modules, 1),
+ ),
+ 1,
+ )
+
+ total_estimated_revenue = sum(o["estimated_revenue"] for o in all_opportunities)
+
+ return {
+ "customer_id": customer.get("customer_id", "unknown"),
+ "name": customer.get("name", "Unknown"),
+ "segment": segment,
+ "arr": arr,
+ "adoption_summary": {
+ "total_modules": total_modules,
+ "adopted_modules": adopted_modules,
+ "adoption_rate": round(safe_divide(adopted_modules, total_modules) * 100, 1) if total_modules > 0 else 0,
+ "avg_usage_pct": avg_usage,
+ "seat_utilisation": round(safe_divide(active, max(licensed, 1)) * 100, 1),
+ "current_tier": current_tier,
+ "departments_covered": len(current_depts),
+ "departments_potential": len(potential_depts),
+ },
+ "total_estimated_revenue": round(total_estimated_revenue, 0),
+ "opportunity_count": len(all_opportunities),
+ "opportunities": all_opportunities,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Output Formatting
+# ---------------------------------------------------------------------------
+
+
+def format_text(results: List[Dict[str, Any]]) -> str:
+ """Format results as human-readable text."""
+ lines: List[str] = []
+ lines.append("=" * 72)
+ lines.append("EXPANSION OPPORTUNITY REPORT")
+ lines.append("=" * 72)
+ lines.append("")
+
+ total_rev = sum(r["total_estimated_revenue"] for r in results)
+ total_opps = sum(r["opportunity_count"] for r in results)
+
+ lines.append(f"Portfolio Summary: {len(results)} customers")
+ lines.append(f" Total Expansion Revenue Potential: ${total_rev:,.0f}")
+ lines.append(f" Total Opportunities Identified: {total_opps}")
+ lines.append("")
+
+ # Sort customers by total estimated revenue descending
+ sorted_results = sorted(results, key=lambda r: r["total_estimated_revenue"], reverse=True)
+
+ for r in sorted_results:
+ lines.append("-" * 72)
+ lines.append(f"Customer: {r['name']} ({r['customer_id']})")
+ lines.append(f"Segment: {r['segment'].title()} | Current ARR: ${r['arr']:,.0f}")
+ lines.append(f"Total Expansion Potential: ${r['total_estimated_revenue']:,.0f} ({r['opportunity_count']} opportunities)")
+ lines.append("")
+
+ adoption = r["adoption_summary"]
+ lines.append(" Adoption Summary:")
+ lines.append(f" Modules Adopted: {adoption['adopted_modules']}/{adoption['total_modules']} ({adoption['adoption_rate']}%)")
+ lines.append(f" Avg Module Usage: {adoption['avg_usage_pct']}%")
+ lines.append(f" Seat Utilisation: {adoption['seat_utilisation']}%")
+ lines.append(f" Current Tier: {adoption['current_tier'].title()}")
+ lines.append(f" Departments: {adoption['departments_covered']} active, {adoption['departments_potential']} potential")
+
+ if r["opportunities"]:
+ lines.append("")
+ lines.append(" Opportunities (ranked by priority):")
+ for i, opp in enumerate(r["opportunities"], 1):
+ opp_type = opp.get("type", "unknown").title()
+ category = opp.get("category", "").replace("_", " ").title()
+ rev = opp["estimated_revenue"]
+ effort = opp.get("effort", "unknown").title()
+ pri = opp.get("priority_score", 0)
+ lines.append(f" {i}. [{opp_type}] {category}")
+ lines.append(f" Revenue: ${rev:,.0f} | Effort: {effort} | Priority: {pri}")
+ lines.append(f" {opp.get('rationale', '')}")
+ else:
+ lines.append("")
+ lines.append(" No expansion opportunities identified at this time.")
+
+ lines.append("")
+
+ lines.append("=" * 72)
+ return "\n".join(lines)
+
+
+def format_json(results: List[Dict[str, Any]]) -> str:
+ """Format results as JSON."""
+ total_rev = sum(r["total_estimated_revenue"] for r in results)
+ total_opps = sum(r["opportunity_count"] for r in results)
+ output = {
+ "report": "expansion_opportunities",
+ "summary": {
+ "total_customers": len(results),
+ "total_estimated_revenue": total_rev,
+ "total_opportunities": total_opps,
+ },
+ "customers": sorted(results, key=lambda r: r["total_estimated_revenue"], reverse=True),
+ }
+ return json.dumps(output, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description="Score expansion opportunities with adoption analysis and revenue estimation."
+ )
+ parser.add_argument("input_file", help="Path to JSON file containing customer data")
+ parser.add_argument(
+ "--format",
+ choices=["text", "json"],
+ default="text",
+ dest="output_format",
+ help="Output format (default: text)",
+ )
+ args = parser.parse_args()
+
+ try:
+ with open(args.input_file, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input_file}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input_file}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ customers = data.get("customers", [])
+ if not customers:
+ print("Error: No customer records found in input file.", file=sys.stderr)
+ sys.exit(1)
+
+ results = [analyse_expansion(c) for c in customers]
+
+ if args.output_format == "json":
+ print(format_json(results))
+ else:
+ print(format_text(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/business-growth/customer-success-manager/scripts/health_score_calculator.py b/skills/business-growth/customer-success-manager/scripts/health_score_calculator.py
new file mode 100644
index 00000000..62aeba3d
--- /dev/null
+++ b/skills/business-growth/customer-success-manager/scripts/health_score_calculator.py
@@ -0,0 +1,438 @@
+#!/usr/bin/env python3
+"""
+Customer Health Score Calculator
+
+Multi-dimensional weighted health scoring across usage, engagement, support,
+and relationship dimensions. Produces Red/Yellow/Green classification with
+trend analysis and segment-aware benchmarking.
+
+Usage:
+ python health_score_calculator.py customer_data.json
+ python health_score_calculator.py customer_data.json --format json
+"""
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+DIMENSION_WEIGHTS: Dict[str, float] = {
+ "usage": 0.30,
+ "engagement": 0.25,
+ "support": 0.20,
+ "relationship": 0.25,
+}
+
+# Segment-specific thresholds (green_min, yellow_min)
+SEGMENT_THRESHOLDS: Dict[str, Dict[str, Tuple[int, int]]] = {
+ "enterprise": {"green": (75, 100), "yellow": (50, 74), "red": (0, 49)},
+ "mid-market": {"green": (70, 100), "yellow": (45, 69), "red": (0, 44)},
+ "smb": {"green": (65, 100), "yellow": (40, 64), "red": (0, 39)},
+}
+
+# Benchmarks per segment for normalising raw metrics
+SEGMENT_BENCHMARKS: Dict[str, Dict[str, Any]] = {
+ "enterprise": {
+ "login_frequency_target": 90,
+ "feature_adoption_target": 80,
+ "dau_mau_target": 0.50,
+ "support_ticket_volume_max": 5,
+ "meeting_attendance_target": 95,
+ "nps_target": 9,
+ "csat_target": 4.5,
+ "open_tickets_max": 10,
+ "escalation_rate_max": 0.25,
+ "avg_resolution_hours_max": 72,
+ "exec_sponsor_target": 90,
+ "multi_threading_target": 5,
+ },
+ "mid-market": {
+ "login_frequency_target": 80,
+ "feature_adoption_target": 70,
+ "dau_mau_target": 0.40,
+ "support_ticket_volume_max": 8,
+ "meeting_attendance_target": 85,
+ "nps_target": 8,
+ "csat_target": 4.0,
+ "open_tickets_max": 15,
+ "escalation_rate_max": 0.30,
+ "avg_resolution_hours_max": 96,
+ "exec_sponsor_target": 75,
+ "multi_threading_target": 3,
+ },
+ "smb": {
+ "login_frequency_target": 70,
+ "feature_adoption_target": 60,
+ "dau_mau_target": 0.30,
+ "support_ticket_volume_max": 10,
+ "meeting_attendance_target": 75,
+ "nps_target": 7,
+ "csat_target": 3.8,
+ "open_tickets_max": 20,
+ "escalation_rate_max": 0.40,
+ "avg_resolution_hours_max": 120,
+ "exec_sponsor_target": 60,
+ "multi_threading_target": 2,
+ },
+}
+
+RENEWAL_SENTIMENT_SCORES: Dict[str, float] = {
+ "positive": 100.0,
+ "neutral": 60.0,
+ "negative": 20.0,
+ "unknown": 50.0,
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Return numerator / denominator, or *default* when denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def clamp(value: float, lo: float = 0.0, hi: float = 100.0) -> float:
+ """Clamp *value* between *lo* and *hi*."""
+ return max(lo, min(hi, value))
+
+
+def get_benchmarks(segment: str) -> Dict[str, Any]:
+ """Return benchmarks for the given segment, falling back to mid-market."""
+ return SEGMENT_BENCHMARKS.get(segment.lower(), SEGMENT_BENCHMARKS["mid-market"])
+
+
+def get_thresholds(segment: str) -> Dict[str, Tuple[int, int]]:
+ """Return classification thresholds for the given segment."""
+ return SEGMENT_THRESHOLDS.get(segment.lower(), SEGMENT_THRESHOLDS["mid-market"])
+
+
+def classify(score: float, segment: str) -> str:
+ """Return 'green', 'yellow', or 'red' classification."""
+ thresholds = get_thresholds(segment)
+ if score >= thresholds["green"][0]:
+ return "green"
+ elif score >= thresholds["yellow"][0]:
+ return "yellow"
+ return "red"
+
+
+def trend_direction(current: float, previous: Optional[float]) -> str:
+ """Return trend direction string."""
+ if previous is None:
+ return "no_data"
+ diff = current - previous
+ if diff > 5:
+ return "improving"
+ elif diff < -5:
+ return "declining"
+ return "stable"
+
+
+# ---------------------------------------------------------------------------
+# Dimension Scoring
+# ---------------------------------------------------------------------------
+
+
+def score_usage(data: Dict[str, Any], benchmarks: Dict[str, Any]) -> Tuple[float, List[str]]:
+ """Score the usage dimension (0-100).
+
+ Metrics: login_frequency, feature_adoption, dau_mau_ratio.
+ """
+ recommendations: List[str] = []
+
+ login = clamp(safe_divide(data.get("login_frequency", 0), benchmarks["login_frequency_target"]) * 100)
+ adoption = clamp(safe_divide(data.get("feature_adoption", 0), benchmarks["feature_adoption_target"]) * 100)
+ dau_mau = clamp(safe_divide(data.get("dau_mau_ratio", 0), benchmarks["dau_mau_target"]) * 100)
+
+ score = round(login * 0.35 + adoption * 0.40 + dau_mau * 0.25, 1)
+
+ if login < 60:
+ recommendations.append("Login frequency below target -- schedule product engagement session")
+ if adoption < 50:
+ recommendations.append("Feature adoption is low -- recommend guided feature walkthrough")
+ if dau_mau < 50:
+ recommendations.append("DAU/MAU ratio indicates shallow usage -- investigate stickiness barriers")
+
+ return score, recommendations
+
+
+def score_engagement(data: Dict[str, Any], benchmarks: Dict[str, Any]) -> Tuple[float, List[str]]:
+ """Score the engagement dimension (0-100).
+
+ Metrics: support_ticket_volume (inverse), meeting_attendance, nps_score, csat_score.
+ """
+ recommendations: List[str] = []
+
+ # Lower ticket volume is better -- invert
+ ticket_vol = data.get("support_ticket_volume", 0)
+ ticket_score = clamp((1.0 - safe_divide(ticket_vol, benchmarks["support_ticket_volume_max"])) * 100)
+
+ attendance = clamp(safe_divide(data.get("meeting_attendance", 0), benchmarks["meeting_attendance_target"]) * 100)
+
+ nps_raw = data.get("nps_score", 5)
+ nps_score = clamp(safe_divide(nps_raw, benchmarks["nps_target"]) * 100)
+
+ csat_raw = data.get("csat_score", 3.0)
+ csat_score = clamp(safe_divide(csat_raw, benchmarks["csat_target"]) * 100)
+
+ score = round(ticket_score * 0.20 + attendance * 0.30 + nps_score * 0.25 + csat_score * 0.25, 1)
+
+ if attendance < 60:
+ recommendations.append("Meeting attendance is low -- re-evaluate meeting cadence and agenda value")
+ if nps_raw < 7:
+ recommendations.append("NPS below threshold -- conduct a feedback deep-dive with customer")
+ if csat_raw < 3.5:
+ recommendations.append("CSAT is critically low -- escalate to support leadership")
+
+ return score, recommendations
+
+
+def score_support(data: Dict[str, Any], benchmarks: Dict[str, Any]) -> Tuple[float, List[str]]:
+ """Score the support dimension (0-100).
+
+ Metrics: open_tickets (inverse), escalation_rate (inverse), avg_resolution_hours (inverse).
+ """
+ recommendations: List[str] = []
+
+ open_tix = data.get("open_tickets", 0)
+ open_score = clamp((1.0 - safe_divide(open_tix, benchmarks["open_tickets_max"])) * 100)
+
+ esc_rate = data.get("escalation_rate", 0)
+ esc_score = clamp((1.0 - safe_divide(esc_rate, benchmarks["escalation_rate_max"])) * 100)
+
+ res_hours = data.get("avg_resolution_hours", 0)
+ res_score = clamp((1.0 - safe_divide(res_hours, benchmarks["avg_resolution_hours_max"])) * 100)
+
+ score = round(open_score * 0.35 + esc_score * 0.35 + res_score * 0.30, 1)
+
+ if open_tix > benchmarks["open_tickets_max"] * 0.5:
+ recommendations.append("Open ticket count elevated -- prioritise ticket resolution")
+ if esc_rate > benchmarks["escalation_rate_max"] * 0.5:
+ recommendations.append("Escalation rate too high -- review support process and training")
+ if res_hours > benchmarks["avg_resolution_hours_max"] * 0.5:
+ recommendations.append("Resolution time exceeds SLA target -- engage support leadership")
+
+ return score, recommendations
+
+
+def score_relationship(data: Dict[str, Any], benchmarks: Dict[str, Any]) -> Tuple[float, List[str]]:
+ """Score the relationship dimension (0-100).
+
+ Metrics: executive_sponsor_engagement, multi_threading_depth, renewal_sentiment.
+ """
+ recommendations: List[str] = []
+
+ exec_score = clamp(safe_divide(data.get("executive_sponsor_engagement", 0), benchmarks["exec_sponsor_target"]) * 100)
+
+ threading = data.get("multi_threading_depth", 1)
+ thread_score = clamp(safe_divide(threading, benchmarks["multi_threading_target"]) * 100)
+
+ sentiment_str = data.get("renewal_sentiment", "unknown").lower()
+ sentiment_score = RENEWAL_SENTIMENT_SCORES.get(sentiment_str, 50.0)
+
+ score = round(exec_score * 0.35 + thread_score * 0.30 + sentiment_score * 0.35, 1)
+
+ if exec_score < 50:
+ recommendations.append("Executive sponsor engagement is weak -- schedule executive alignment meeting")
+ if threading < 2:
+ recommendations.append("Single-threaded relationship -- expand contacts across departments")
+ if sentiment_str == "negative":
+ recommendations.append("Renewal sentiment is negative -- initiate save plan immediately")
+
+ return score, recommendations
+
+
+# ---------------------------------------------------------------------------
+# Main Scoring
+# ---------------------------------------------------------------------------
+
+
+def calculate_health_score(customer: Dict[str, Any]) -> Dict[str, Any]:
+ """Calculate the overall health score for a single customer."""
+ segment = customer.get("segment", "mid-market").lower()
+ benchmarks = get_benchmarks(segment)
+
+ # Score each dimension
+ usage_score, usage_recs = score_usage(customer.get("usage", {}), benchmarks)
+ engagement_score, engagement_recs = score_engagement(customer.get("engagement", {}), benchmarks)
+ support_score, support_recs = score_support(customer.get("support", {}), benchmarks)
+ relationship_score, relationship_recs = score_relationship(customer.get("relationship", {}), benchmarks)
+
+ # Weighted overall
+ overall = round(
+ usage_score * DIMENSION_WEIGHTS["usage"]
+ + engagement_score * DIMENSION_WEIGHTS["engagement"]
+ + support_score * DIMENSION_WEIGHTS["support"]
+ + relationship_score * DIMENSION_WEIGHTS["relationship"],
+ 1,
+ )
+
+ classification = classify(overall, segment)
+
+ # Trend analysis
+ prev = customer.get("previous_period", {})
+ trends = {
+ "usage": trend_direction(usage_score, prev.get("usage_score")),
+ "engagement": trend_direction(engagement_score, prev.get("engagement_score")),
+ "support": trend_direction(support_score, prev.get("support_score")),
+ "relationship": trend_direction(relationship_score, prev.get("relationship_score")),
+ }
+ overall_prev = prev.get("overall_score")
+ trends["overall"] = trend_direction(overall, overall_prev)
+
+ # Combine recommendations
+ all_recs = usage_recs + engagement_recs + support_recs + relationship_recs
+
+ return {
+ "customer_id": customer.get("customer_id", "unknown"),
+ "name": customer.get("name", "Unknown"),
+ "segment": segment,
+ "arr": customer.get("arr", 0),
+ "overall_score": overall,
+ "classification": classification,
+ "dimensions": {
+ "usage": {"score": usage_score, "weight": "30%", "classification": classify(usage_score, segment)},
+ "engagement": {"score": engagement_score, "weight": "25%", "classification": classify(engagement_score, segment)},
+ "support": {"score": support_score, "weight": "20%", "classification": classify(support_score, segment)},
+ "relationship": {"score": relationship_score, "weight": "25%", "classification": classify(relationship_score, segment)},
+ },
+ "trends": trends,
+ "recommendations": all_recs,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Output Formatting
+# ---------------------------------------------------------------------------
+
+CLASSIFICATION_LABELS = {
+ "green": "HEALTHY",
+ "yellow": "NEEDS ATTENTION",
+ "red": "AT RISK",
+}
+
+
+def format_text(results: List[Dict[str, Any]]) -> str:
+ """Format results as human-readable text."""
+ lines: List[str] = []
+ lines.append("=" * 72)
+ lines.append("CUSTOMER HEALTH SCORE REPORT")
+ lines.append("=" * 72)
+ lines.append("")
+
+ # Portfolio summary
+ total = len(results)
+ green_count = sum(1 for r in results if r["classification"] == "green")
+ yellow_count = sum(1 for r in results if r["classification"] == "yellow")
+ red_count = sum(1 for r in results if r["classification"] == "red")
+ avg_score = round(safe_divide(sum(r["overall_score"] for r in results), total), 1)
+
+ lines.append(f"Portfolio Summary: {total} customers")
+ lines.append(f" Average Health Score: {avg_score}/100")
+ lines.append(f" Green (Healthy): {green_count}")
+ lines.append(f" Yellow (Attention): {yellow_count}")
+ lines.append(f" Red (At Risk): {red_count}")
+ lines.append("")
+
+ for r in results:
+ label = CLASSIFICATION_LABELS.get(r["classification"], "UNKNOWN")
+ lines.append("-" * 72)
+ lines.append(f"Customer: {r['name']} ({r['customer_id']})")
+ lines.append(f"Segment: {r['segment'].title()} | ARR: ${r['arr']:,.0f}")
+ lines.append(f"Overall Score: {r['overall_score']}/100 [{label}]")
+ lines.append("")
+
+ lines.append(" Dimension Scores:")
+ for dim_name, dim_data in r["dimensions"].items():
+ dim_label = CLASSIFICATION_LABELS.get(dim_data["classification"], "")
+ lines.append(f" {dim_name.title():15s} {dim_data['score']:6.1f}/100 ({dim_data['weight']}) [{dim_label}]")
+
+ lines.append("")
+ lines.append(" Trends:")
+ for dim_name, direction in r["trends"].items():
+ arrow = {"improving": "+", "declining": "-", "stable": "=", "no_data": "?"}
+ lines.append(f" {dim_name.title():15s} {arrow.get(direction, '?')} {direction}")
+
+ if r["recommendations"]:
+ lines.append("")
+ lines.append(" Recommendations:")
+ for i, rec in enumerate(r["recommendations"], 1):
+ lines.append(f" {i}. {rec}")
+
+ lines.append("")
+
+ lines.append("=" * 72)
+ return "\n".join(lines)
+
+
+def format_json(results: List[Dict[str, Any]]) -> str:
+ """Format results as JSON."""
+ total = len(results)
+ output = {
+ "report": "customer_health_scores",
+ "summary": {
+ "total_customers": total,
+ "average_score": round(safe_divide(sum(r["overall_score"] for r in results), total), 1),
+ "green_count": sum(1 for r in results if r["classification"] == "green"),
+ "yellow_count": sum(1 for r in results if r["classification"] == "yellow"),
+ "red_count": sum(1 for r in results if r["classification"] == "red"),
+ },
+ "customers": results,
+ }
+ return json.dumps(output, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description="Calculate multi-dimensional customer health scores with trend analysis."
+ )
+ parser.add_argument("input_file", help="Path to JSON file containing customer data")
+ parser.add_argument(
+ "--format",
+ choices=["text", "json"],
+ default="text",
+ dest="output_format",
+ help="Output format (default: text)",
+ )
+ args = parser.parse_args()
+
+ try:
+ with open(args.input_file, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input_file}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input_file}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ customers = data.get("customers", [])
+ if not customers:
+ print("Error: No customer records found in input file.", file=sys.stderr)
+ sys.exit(1)
+
+ results = [calculate_health_score(c) for c in customers]
+
+ if args.output_format == "json":
+ print(format_json(results))
+ else:
+ print(format_text(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/business-growth/revenue-operations/SKILL.md b/skills/business-growth/revenue-operations/SKILL.md
new file mode 100644
index 00000000..df060bb5
--- /dev/null
+++ b/skills/business-growth/revenue-operations/SKILL.md
@@ -0,0 +1,273 @@
+---
+name: "revenue-operations"
+description: 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 |
diff --git a/skills/business-growth/revenue-operations/assets/expected_output.json b/skills/business-growth/revenue-operations/assets/expected_output.json
new file mode 100644
index 00000000..66e4becc
--- /dev/null
+++ b/skills/business-growth/revenue-operations/assets/expected_output.json
@@ -0,0 +1,117 @@
+{
+ "coverage": {
+ "total_pipeline_value": 1105000,
+ "quota": 500000,
+ "coverage_ratio": 2.21,
+ "rating": "At Risk",
+ "target": "3.0x - 4.0x"
+ },
+ "stage_conversions": [
+ {
+ "from_stage": "Discovery",
+ "to_stage": "Qualification",
+ "from_count": 17,
+ "to_count": 12,
+ "conversion_rate_pct": 70.6
+ },
+ {
+ "from_stage": "Qualification",
+ "to_stage": "Proposal",
+ "from_count": 12,
+ "to_count": 9,
+ "conversion_rate_pct": 75.0
+ },
+ {
+ "from_stage": "Proposal",
+ "to_stage": "Negotiation",
+ "from_count": 9,
+ "to_count": 5,
+ "conversion_rate_pct": 55.6
+ },
+ {
+ "from_stage": "Negotiation",
+ "to_stage": "Closed Won",
+ "from_count": 5,
+ "to_count": 2,
+ "conversion_rate_pct": 40.0
+ }
+ ],
+ "velocity": {
+ "num_opportunities": 17,
+ "avg_deal_size": 74588.24,
+ "win_rate_pct": 11.8,
+ "avg_cycle_days": 32.5,
+ "velocity_per_day": 4594.2,
+ "velocity_per_month": 137826.09
+ },
+ "aging": {
+ "global_aging_threshold_days": 90,
+ "stage_thresholds": {
+ "Discovery": 90,
+ "Qualification": 78,
+ "Proposal": 67,
+ "Negotiation": 56
+ },
+ "total_open_deals": 15,
+ "healthy_deals": 13,
+ "at_risk_deals": 2,
+ "aging_deals": [
+ {
+ "id": "D011",
+ "name": "Vertex Solutions",
+ "stage": "Proposal",
+ "age_days": 95,
+ "threshold_days": 67,
+ "days_over": 28,
+ "value": 110000
+ },
+ {
+ "id": "D014",
+ "name": "Horizon Telecom",
+ "stage": "Negotiation",
+ "age_days": 60,
+ "threshold_days": 56,
+ "days_over": 4,
+ "value": 250000
+ }
+ ]
+ },
+ "risk": {
+ "overall_risk": "MEDIUM",
+ "risk_factors_count": 3,
+ "concentration_risks": [],
+ "has_concentration_risk": false,
+ "stage_distribution": {
+ "Discovery": {
+ "count": 5,
+ "value": 194000,
+ "pct_of_pipeline": 17.6
+ },
+ "Qualification": {
+ "count": 3,
+ "value": 150000,
+ "pct_of_pipeline": 13.6
+ },
+ "Proposal": {
+ "count": 4,
+ "value": 333000,
+ "pct_of_pipeline": 30.1
+ },
+ "Negotiation": {
+ "count": 3,
+ "value": 428000,
+ "pct_of_pipeline": 38.7
+ }
+ },
+ "empty_stages": [],
+ "coverage_gaps": [
+ {
+ "quarter": "2025-Q2",
+ "pipeline_value": 344000,
+ "quarterly_target": 125000.0,
+ "coverage_ratio": 2.75,
+ "gap": "Below 3x target"
+ }
+ ]
+ }
+}
diff --git a/skills/business-growth/revenue-operations/assets/forecast_report_template.md b/skills/business-growth/revenue-operations/assets/forecast_report_template.md
new file mode 100644
index 00000000..f8785cd3
--- /dev/null
+++ b/skills/business-growth/revenue-operations/assets/forecast_report_template.md
@@ -0,0 +1,149 @@
+# Forecast Accuracy Report - [Period]
+
+## Report Details
+- **Prepared By:** [Name]
+- **Report Date:** [YYYY-MM-DD]
+- **Period Analyzed:** [Start Period] to [End Period]
+- **Periods Covered:** [N] periods
+
+---
+
+## Executive Summary
+
+| Metric | Value | Rating | Trend |
+|--------|-------|--------|-------|
+| MAPE | _% | | |
+| Weighted MAPE | _% | | |
+| Forecast Bias | _% | | |
+| Bias Direction | | | |
+
+**Accuracy Rating:**
+- Excellent (<10%) / Good (10-15%) / Fair (15-25%) / Poor (>25%)
+
+**Key Finding:** [1-2 sentence summary of forecast accuracy status]
+
+---
+
+## Period-by-Period Analysis
+
+| Period | Forecast | Actual | Variance | Error % | Bias |
+|--------|----------|--------|----------|---------|------|
+| | $_ | $_ | $_ | _% | Over/Under |
+| | $_ | $_ | $_ | _% | Over/Under |
+| | $_ | $_ | $_ | _% | Over/Under |
+| | $_ | $_ | $_ | _% | Over/Under |
+| | $_ | $_ | $_ | _% | Over/Under |
+| | $_ | $_ | $_ | _% | Over/Under |
+
+---
+
+## Bias Analysis
+
+### Overall Bias
+- **Direction:** [Over-forecasting / Under-forecasting / Balanced]
+- **Bias Magnitude:** _%
+- **Over-forecast Periods:** _ of _
+- **Under-forecast Periods:** _ of _
+- **Bias Ratio:** _ (1.0 = always over, 0.0 = always under, 0.5 = balanced)
+
+### Interpretation
+[What does the bias pattern tell us about our forecasting process? Is it systematic or random?]
+
+### Root Cause
+[Identify the primary drivers of bias: optimistic deal assessment, poor stage qualification, sandbagging, late-arriving deals, etc.]
+
+---
+
+## Trend Analysis
+
+### Accuracy Trend
+- **Direction:** [Improving / Stable / Declining]
+- **Early Period MAPE:** _%
+- **Recent Period MAPE:** _%
+- **MAPE Change:** _% (positive = worsening, negative = improving)
+
+### Trend Chart (Text)
+```
+Period Error% Trend
+Q1 __% ████████
+Q2 __% ██████████
+Q3 __% ██████
+Q4 __% ████████████
+```
+
+---
+
+## Category Breakdown
+
+### By Rep
+
+| Rep | Forecast | Actual | Error % | Bias | Rating |
+|-----|----------|--------|---------|------|--------|
+| | $_ | $_ | _% | | |
+| | $_ | $_ | _% | | |
+| | $_ | $_ | _% | | |
+| | $_ | $_ | _% | | |
+
+**Overall Rep MAPE:** _%
+
+### By Segment
+
+| Segment | Forecast | Actual | Error % | Bias | Rating |
+|---------|----------|--------|---------|------|--------|
+| Enterprise | $_ | $_ | _% | | |
+| Mid-Market | $_ | $_ | _% | | |
+| SMB | $_ | $_ | _% | | |
+
+**Overall Segment MAPE:** _%
+
+### By Product (if applicable)
+
+| Product | Forecast | Actual | Error % | Bias | Rating |
+|---------|----------|--------|---------|------|--------|
+| | $_ | $_ | _% | | |
+| | $_ | $_ | _% | | |
+
+---
+
+## Recommendations
+
+### Immediate Actions (This Quarter)
+
+1. **[Action]** -- [Why and expected impact]
+2. **[Action]** -- [Why and expected impact]
+3. **[Action]** -- [Why and expected impact]
+
+### Process Improvements (Next Quarter)
+
+1. **[Improvement]** -- [Implementation plan]
+2. **[Improvement]** -- [Implementation plan]
+
+### Coaching Focus Areas
+
+| Rep/Team | Issue | Coaching Action | Target |
+|----------|-------|-----------------|--------|
+| | | | |
+| | | | |
+
+---
+
+## Forecast Methodology Notes
+
+### Current Methodology
+[Describe the current forecasting methodology: weighted pipeline, commit/upside categories, AI-assisted, etc.]
+
+### Methodology Changes This Period
+[Any changes to the forecasting process or methodology during the reporting period]
+
+### Data Quality Issues
+[Note any data quality issues that may affect accuracy: missing close dates, inconsistent stage definitions, CRM hygiene gaps]
+
+---
+
+## Next Steps
+
+| # | Action | Owner | Due Date |
+|---|--------|-------|----------|
+| 1 | | | |
+| 2 | | | |
+| 3 | | | |
diff --git a/skills/business-growth/revenue-operations/assets/gtm_dashboard_template.md b/skills/business-growth/revenue-operations/assets/gtm_dashboard_template.md
new file mode 100644
index 00000000..65e3849f
--- /dev/null
+++ b/skills/business-growth/revenue-operations/assets/gtm_dashboard_template.md
@@ -0,0 +1,215 @@
+# GTM Efficiency Dashboard - [Quarter/Period]
+
+## Dashboard Details
+- **Prepared By:** [Name]
+- **Report Date:** [YYYY-MM-DD]
+- **Period:** [Quarter or Date Range]
+- **Company Stage:** [Seed / Series A / Series B / Series C+ / Growth]
+
+---
+
+## Metrics At A Glance
+
+| Metric | Value | Rating | Target | Trend | vs. Last Period |
+|--------|-------|--------|--------|-------|-----------------|
+| Magic Number | _ | | >0.75 | | |
+| LTV:CAC | _:1 | | >3:1 | | |
+| CAC Payback | _ mo | | <18 mo | | |
+| Burn Multiple | _x | | <2x | | |
+| Rule of 40 | _% | | >40% | | |
+| NDR | _% | | >110% | | |
+
+**Rating Legend:** Green = Healthy | Yellow = Monitor | Red = Action Required
+
+**Overall GTM Health:** [Strong / Healthy / Needs Attention / Critical]
+
+---
+
+## Detailed Metric Analysis
+
+### Magic Number
+
+| Component | Value |
+|-----------|-------|
+| Net New ARR | $_ |
+| Prior Period S&M Spend | $_ |
+| **Magic Number** | **_** |
+
+- **Rating:** [Green / Yellow / Red]
+- **Percentile:** [Top 10% / Top 25% / Median / Below Median]
+- **Trend:** [Improving / Stable / Declining]
+- **Interpretation:** [What does this metric tell us about GTM spend efficiency?]
+
+### LTV:CAC Ratio
+
+| Component | Value |
+|-----------|-------|
+| ARPA (Monthly) | $_ |
+| ARPA (Annual) | $_ |
+| Gross Margin | _% |
+| Annual Churn Rate | _% |
+| **Customer LTV** | **$_** |
+| Customer Acquisition Cost | $_ |
+| **LTV:CAC Ratio** | **_:1** |
+
+- **Rating:** [Green / Yellow / Red]
+- **Percentile:** [Top 10% / Top 25% / Median / Below Median]
+- **Trend:** [Improving / Stable / Declining]
+- **Interpretation:** [Are unit economics sustainable?]
+
+### CAC Payback Period
+
+| Component | Value |
+|-----------|-------|
+| CAC | $_ |
+| Monthly Gross Margin Contribution | $_ |
+| **CAC Payback** | **_ months** |
+
+- **Rating:** [Green / Yellow / Red]
+- **Percentile:** [Top 10% / Top 25% / Median / Below Median]
+- **Trend:** [Improving / Stable / Declining]
+- **Interpretation:** [How quickly are we recovering acquisition costs?]
+
+### Burn Multiple
+
+| Component | Value |
+|-----------|-------|
+| Net Burn | $_ |
+| Net New ARR | $_ |
+| **Burn Multiple** | **_x** |
+
+- **Rating:** [Green / Yellow / Red]
+- **Percentile:** [Top 10% / Top 25% / Median / Below Median]
+- **Trend:** [Improving / Stable / Declining]
+- **Interpretation:** [Is growth capital-efficient?]
+
+### Rule of 40
+
+| Component | Value |
+|-----------|-------|
+| Revenue Growth Rate | _% |
+| FCF Margin | _% |
+| **Rule of 40 Score** | **_%** |
+
+- **Rating:** [Green / Yellow / Red]
+- **Percentile:** [Top 10% / Top 25% / Median / Below Median]
+- **Trend:** [Improving / Stable / Declining]
+- **Interpretation:** [Is the growth-profitability balance healthy?]
+
+### Net Dollar Retention
+
+| Component | Value |
+|-----------|-------|
+| Beginning ARR | $_ |
+| Expansion ARR | +$_ |
+| Contraction ARR | -$_ |
+| Churned ARR | -$_ |
+| Ending ARR | $_ |
+| **NDR** | **_%** |
+
+- **Rating:** [Green / Yellow / Red]
+- **Percentile:** [Top 10% / Top 25% / Median / Below Median]
+- **Trend:** [Improving / Stable / Declining]
+- **Interpretation:** [Are we growing revenue from the existing customer base?]
+
+---
+
+## Quarterly Trend
+
+| Metric | Q-3 | Q-2 | Q-1 | Current | Direction |
+|--------|-----|-----|-----|---------|-----------|
+| Magic Number | _ | _ | _ | _ | |
+| LTV:CAC | _:1 | _:1 | _:1 | _:1 | |
+| CAC Payback | _ mo | _ mo | _ mo | _ mo | |
+| Burn Multiple | _x | _x | _x | _x | |
+| Rule of 40 | _% | _% | _% | _% | |
+| NDR | _% | _% | _% | _% | |
+
+---
+
+## Benchmark Comparison
+
+| Metric | Our Value | Stage Median | Top Quartile | Gap to Top Quartile |
+|--------|-----------|-------------|--------------|---------------------|
+| Magic Number | _ | _ | _ | _ |
+| LTV:CAC | _:1 | _:1 | _:1 | _ |
+| CAC Payback | _ mo | _ mo | _ mo | _ mo |
+| Burn Multiple | _x | _x | _x | _ |
+| Rule of 40 | _% | _% | _% | _% |
+| NDR | _% | _% | _% | _% |
+
+---
+
+## Revenue Composition
+
+### ARR Bridge
+
+```
+Beginning ARR: $____________
++ New Logo ARR: $____________
++ Expansion ARR: $____________
+- Contraction ARR: $____________
+- Churned ARR: $____________
+= Ending ARR: $____________
+
+Net New ARR: $____________
+Growth Rate: ____________%
+```
+
+### Cost Structure
+
+```
+S&M Spend: $____________ (___% of revenue)
+R&D Spend: $____________ (___% of revenue)
+G&A Spend: $____________ (___% of revenue)
+Total OpEx: $____________
+Net Burn: $____________
+Gross Margin: ____________%
+```
+
+---
+
+## Strategic Recommendations
+
+### Top 3 Priorities
+
+1. **[Priority]**
+ - Current state: [Where we are]
+ - Target: [Where we need to be]
+ - Action plan: [How to get there]
+ - Expected impact: [Metric improvement]
+ - Timeline: [When]
+
+2. **[Priority]**
+ - Current state:
+ - Target:
+ - Action plan:
+ - Expected impact:
+ - Timeline:
+
+3. **[Priority]**
+ - Current state:
+ - Target:
+ - Action plan:
+ - Expected impact:
+ - Timeline:
+
+### Investment Recommendations
+
+| Area | Current Spend | Recommended | Rationale |
+|------|--------------|-------------|-----------|
+| | $_ | $_ | |
+| | $_ | $_ | |
+| | $_ | $_ | |
+
+---
+
+## Next Steps
+
+| # | Action | Owner | Due Date | Success Metric |
+|---|--------|-------|----------|---------------|
+| 1 | | | | |
+| 2 | | | | |
+| 3 | | | | |
+| 4 | | | | |
+| 5 | | | | |
diff --git a/skills/business-growth/revenue-operations/assets/pipeline_review_template.md b/skills/business-growth/revenue-operations/assets/pipeline_review_template.md
new file mode 100644
index 00000000..856f6d4f
--- /dev/null
+++ b/skills/business-growth/revenue-operations/assets/pipeline_review_template.md
@@ -0,0 +1,138 @@
+# Pipeline Review - [Date]
+
+## Review Period
+- **Review Type:** Weekly / Monthly (circle one)
+- **Prepared By:** [Name]
+- **Review Date:** [YYYY-MM-DD]
+- **Period Covered:** [Start Date] to [End Date]
+
+---
+
+## Executive Summary
+
+| Metric | Current | Last Period | Target | Status |
+|--------|---------|-------------|--------|--------|
+| Pipeline Coverage | _x | _x | 3-4x | |
+| Total Pipeline Value | $_ | $_ | $_ | |
+| Net Pipeline Change | $_ | $_ | >$0 | |
+| Deals in Pipeline | _ | _ | _ | |
+| Avg Deal Size | $_ | $_ | $_ | |
+| Sales Velocity ($/mo) | $_ | $_ | $_ | |
+
+**Overall Assessment:** [1-2 sentence summary of pipeline health]
+
+---
+
+## Coverage Analysis
+
+### By Quarter
+
+| Quarter | Pipeline | Target | Coverage | Status |
+|---------|----------|--------|----------|--------|
+| Current Quarter | $_ | $_ | _x | |
+| Next Quarter | $_ | $_ | _x | |
+| Q+2 | $_ | $_ | _x | |
+
+### By Segment
+
+| Segment | Pipeline | Target | Coverage | Notes |
+|---------|----------|--------|----------|-------|
+| Enterprise | $_ | $_ | _x | |
+| Mid-Market | $_ | $_ | _x | |
+| SMB | $_ | $_ | _x | |
+
+---
+
+## Stage Distribution
+
+| Stage | # Deals | Value | % of Pipeline | Conversion Rate |
+|-------|---------|-------|---------------|-----------------|
+| Discovery | _ | $_ | _% | _% |
+| Qualification | _ | $_ | _% | _% |
+| Proposal | _ | $_ | _% | _% |
+| Negotiation | _ | $_ | _% | _% |
+
+**Funnel Health:** [Healthy / Top-heavy / Bottom-heavy / Gaps identified]
+
+---
+
+## Top Deals Review (S3+)
+
+| Deal | Stage | Value | Age | Close Date | Risk | Next Step |
+|------|-------|-------|-----|------------|------|-----------|
+| | | $_ | _d | | | |
+| | | $_ | _d | | | |
+| | | $_ | _d | | | |
+| | | $_ | _d | | | |
+| | | $_ | _d | | | |
+
+---
+
+## Risk Assessment
+
+### Concentration Risk
+- **Largest deal as % of pipeline:** _%
+- **Top 3 deals as % of pipeline:** _%
+- **Risk Level:** [Low / Medium / High]
+- **Mitigation:** [Actions to diversify]
+
+### Aging Deals
+| Deal | Stage | Age | Threshold | Days Over | Action Required |
+|------|-------|-----|-----------|-----------|-----------------|
+| | | _d | _d | +_d | |
+| | | _d | _d | +_d | |
+
+### Deals Pushed from Last Period
+| Deal | Original Close | New Close | Times Pushed | Reason |
+|------|---------------|-----------|-------------|--------|
+| | | | | |
+| | | | | |
+
+---
+
+## Pipeline Movement
+
+### Created This Period
+| Deal | Source | Value | Stage | Expected Close |
+|------|--------|-------|-------|---------------|
+| | | $_ | | |
+| | | $_ | | |
+**Total Created:** $_
+
+### Advanced This Period
+| Deal | From Stage | To Stage | Value |
+|------|-----------|----------|-------|
+| | | | $_ |
+| | | | $_ |
+
+### Closed Won This Period
+| Deal | Value | Cycle Days | Source |
+|------|-------|-----------|--------|
+| | $_ | _d | |
+| | $_ | _d | |
+**Total Closed Won:** $_
+
+### Closed Lost This Period
+| Deal | Value | Stage Lost | Loss Reason |
+|------|-------|-----------|-------------|
+| | $_ | | |
+| | $_ | | |
+**Total Closed Lost:** $_
+
+---
+
+## Action Items
+
+| # | Action | Owner | Due Date | Priority |
+|---|--------|-------|----------|----------|
+| 1 | | | | |
+| 2 | | | | |
+| 3 | | | | |
+| 4 | | | | |
+| 5 | | | | |
+
+---
+
+## Notes
+
+[Additional context, observations, or discussion points for the review meeting]
diff --git a/skills/business-growth/revenue-operations/assets/sample_forecast_data.json b/skills/business-growth/revenue-operations/assets/sample_forecast_data.json
new file mode 100644
index 00000000..54fc3c46
--- /dev/null
+++ b/skills/business-growth/revenue-operations/assets/sample_forecast_data.json
@@ -0,0 +1,23 @@
+{
+ "forecast_periods": [
+ {"period": "2024-Q1", "forecast": 420000, "actual": 445000},
+ {"period": "2024-Q2", "forecast": 480000, "actual": 460000},
+ {"period": "2024-Q3", "forecast": 510000, "actual": 525000},
+ {"period": "2024-Q4", "forecast": 550000, "actual": 510000},
+ {"period": "2025-Q1", "forecast": 520000, "actual": 540000},
+ {"period": "2025-Q2", "forecast": 580000, "actual": 560000}
+ ],
+ "category_breakdowns": {
+ "by_rep": [
+ {"category": "Sarah Chen", "forecast": 210000, "actual": 225000},
+ {"category": "Marcus Johnson", "forecast": 185000, "actual": 160000},
+ {"category": "Priya Patel", "forecast": 125000, "actual": 135000},
+ {"category": "Alex Rivera", "forecast": 60000, "actual": 40000}
+ ],
+ "by_segment": [
+ {"category": "Enterprise", "forecast": 320000, "actual": 310000},
+ {"category": "Mid-Market", "forecast": 180000, "actual": 175000},
+ {"category": "SMB", "forecast": 80000, "actual": 75000}
+ ]
+ }
+}
diff --git a/skills/business-growth/revenue-operations/assets/sample_gtm_data.json b/skills/business-growth/revenue-operations/assets/sample_gtm_data.json
new file mode 100644
index 00000000..c0571634
--- /dev/null
+++ b/skills/business-growth/revenue-operations/assets/sample_gtm_data.json
@@ -0,0 +1,24 @@
+{
+ "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
+ }
+}
diff --git a/skills/business-growth/revenue-operations/assets/sample_pipeline_data.json b/skills/business-growth/revenue-operations/assets/sample_pipeline_data.json
new file mode 100644
index 00000000..e7c3d28d
--- /dev/null
+++ b/skills/business-growth/revenue-operations/assets/sample_pipeline_data.json
@@ -0,0 +1,160 @@
+{
+ "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"
+ },
+ {
+ "id": "D002",
+ "name": "TechFlow Inc",
+ "stage": "Discovery",
+ "value": 42000,
+ "age_days": 8,
+ "close_date": "2025-04-30",
+ "owner": "rep_2"
+ },
+ {
+ "id": "D003",
+ "name": "GlobalData Systems",
+ "stage": "Negotiation",
+ "value": 120000,
+ "age_days": 55,
+ "close_date": "2025-02-28",
+ "owner": "rep_1"
+ },
+ {
+ "id": "D004",
+ "name": "Pinnacle Software",
+ "stage": "Qualification",
+ "value": 35000,
+ "age_days": 18,
+ "close_date": "2025-04-15",
+ "owner": "rep_3"
+ },
+ {
+ "id": "D005",
+ "name": "Meridian Health",
+ "stage": "Proposal",
+ "value": 95000,
+ "age_days": 40,
+ "close_date": "2025-03-20",
+ "owner": "rep_2"
+ },
+ {
+ "id": "D006",
+ "name": "CloudVault",
+ "stage": "Discovery",
+ "value": 28000,
+ "age_days": 5,
+ "close_date": "2025-05-15",
+ "owner": "rep_1"
+ },
+ {
+ "id": "D007",
+ "name": "Nexus Financial",
+ "stage": "Closed Won",
+ "value": 72000,
+ "age_days": 38,
+ "close_date": "2025-01-31",
+ "owner": "rep_3"
+ },
+ {
+ "id": "D008",
+ "name": "Urban Analytics",
+ "stage": "Negotiation",
+ "value": 58000,
+ "age_days": 42,
+ "close_date": "2025-03-05",
+ "owner": "rep_2"
+ },
+ {
+ "id": "D009",
+ "name": "Redwood Logistics",
+ "stage": "Discovery",
+ "value": 31000,
+ "age_days": 12,
+ "close_date": "2025-05-01",
+ "owner": "rep_3"
+ },
+ {
+ "id": "D010",
+ "name": "Summit Enterprises",
+ "stage": "Qualification",
+ "value": 48000,
+ "age_days": 22,
+ "close_date": "2025-04-10",
+ "owner": "rep_1"
+ },
+ {
+ "id": "D011",
+ "name": "Vertex Solutions",
+ "stage": "Proposal",
+ "value": 110000,
+ "age_days": 95,
+ "close_date": "2025-03-01",
+ "owner": "rep_2"
+ },
+ {
+ "id": "D012",
+ "name": "DataBridge AI",
+ "stage": "Discovery",
+ "value": 55000,
+ "age_days": 3,
+ "close_date": "2025-06-15",
+ "owner": "rep_1"
+ },
+ {
+ "id": "D013",
+ "name": "Atlas Manufacturing",
+ "stage": "Qualification",
+ "value": 67000,
+ "age_days": 28,
+ "close_date": "2025-04-20",
+ "owner": "rep_3"
+ },
+ {
+ "id": "D014",
+ "name": "Horizon Telecom",
+ "stage": "Negotiation",
+ "value": 250000,
+ "age_days": 60,
+ "close_date": "2025-03-10",
+ "owner": "rep_1"
+ },
+ {
+ "id": "D015",
+ "name": "BlueShift Labs",
+ "stage": "Proposal",
+ "value": 43000,
+ "age_days": 35,
+ "close_date": "2025-03-25",
+ "owner": "rep_3"
+ },
+ {
+ "id": "D016",
+ "name": "Crestview Partners",
+ "stage": "Discovery",
+ "value": 38000,
+ "age_days": 15,
+ "close_date": "2025-05-20",
+ "owner": "rep_2"
+ },
+ {
+ "id": "D017",
+ "name": "Ironclad Security",
+ "stage": "Closed Won",
+ "value": 91000,
+ "age_days": 44,
+ "close_date": "2025-02-10",
+ "owner": "rep_1"
+ }
+ ]
+}
diff --git a/skills/business-growth/revenue-operations/references/gtm-efficiency-benchmarks.md b/skills/business-growth/revenue-operations/references/gtm-efficiency-benchmarks.md
new file mode 100644
index 00000000..29c99228
--- /dev/null
+++ b/skills/business-growth/revenue-operations/references/gtm-efficiency-benchmarks.md
@@ -0,0 +1,257 @@
+# GTM Efficiency Benchmarks
+
+SaaS benchmarks by funding stage, industry standards, and strategies for improving go-to-market efficiency.
+
+---
+
+## Benchmarks by Funding Stage
+
+### Seed Stage ($0-$2M ARR)
+
+| Metric | Red | Yellow | Green | Elite |
+|--------|-----|--------|-------|-------|
+| Magic Number | <0.3 | 0.3-0.5 | >0.5 | >0.8 |
+| LTV:CAC | <1.5:1 | 1.5-2.5:1 | >2.5:1 | >4:1 |
+| CAC Payback | >30 mo | 24-30 mo | <24 mo | <15 mo |
+| Burn Multiple | >5x | 3-5x | <3x | <2x |
+| Rule of 40 | <0% | 0-20% | >20% | >40% |
+| NDR | <90% | 90-100% | >100% | >110% |
+
+**Context:** At seed stage, efficiency metrics are naturally less stable due to small sample sizes. Focus on directional improvement rather than absolute numbers. Burn multiple is the most critical metric -- investors want to see capital-efficient growth.
+
+### Series A ($2M-$10M ARR)
+
+| Metric | Red | Yellow | Green | Elite |
+|--------|-----|--------|-------|-------|
+| Magic Number | <0.4 | 0.4-0.6 | >0.6 | >0.9 |
+| LTV:CAC | <2:1 | 2-3:1 | >3:1 | >5:1 |
+| CAC Payback | >24 mo | 18-24 mo | <18 mo | <12 mo |
+| Burn Multiple | >4x | 2.5-4x | <2.5x | <1.5x |
+| Rule of 40 | <10% | 10-30% | >30% | >50% |
+| NDR | <95% | 95-105% | >105% | >115% |
+
+**Context:** Series A is where unit economics must prove out. LTV:CAC >3:1 validates product-market fit in the revenue model. Investors will scrutinize CAC payback to understand capital requirements.
+
+### Series B ($10M-$50M ARR)
+
+| Metric | Red | Yellow | Green | Elite |
+|--------|-----|--------|-------|-------|
+| Magic Number | <0.5 | 0.5-0.75 | >0.75 | >1.0 |
+| LTV:CAC | <2.5:1 | 2.5-3.5:1 | >3.5:1 | >5:1 |
+| CAC Payback | >22 mo | 15-22 mo | <15 mo | <10 mo |
+| Burn Multiple | >3x | 2-3x | <2x | <1.5x |
+| Rule of 40 | <20% | 20-35% | >35% | >50% |
+| NDR | <100% | 100-110% | >110% | >120% |
+
+**Context:** At Series B, the GTM machine should be scaling predictably. Magic Number >0.75 demonstrates that adding GTM spend produces proportional returns. NDR >110% proves land-and-expand motion works.
+
+### Series C+ ($50M-$200M ARR)
+
+| Metric | Red | Yellow | Green | Elite |
+|--------|-----|--------|-------|-------|
+| Magic Number | <0.5 | 0.5-0.75 | >0.75 | >1.0 |
+| LTV:CAC | <3:1 | 3-4:1 | >4:1 | >6:1 |
+| CAC Payback | >20 mo | 14-20 mo | <14 mo | <10 mo |
+| Burn Multiple | >2.5x | 1.5-2.5x | <1.5x | <1x |
+| Rule of 40 | <25% | 25-40% | >40% | >60% |
+| NDR | <105% | 105-115% | >115% | >130% |
+
+**Context:** Growth efficiency and path to profitability become paramount. The Rule of 40 is the primary board-level metric. Companies approaching IPO should target Rule of 40 >40% consistently.
+
+### Growth / Pre-IPO ($200M+ ARR)
+
+| Metric | Red | Yellow | Green | Elite |
+|--------|-----|--------|-------|-------|
+| Magic Number | <0.6 | 0.6-0.8 | >0.8 | >1.0 |
+| LTV:CAC | <3:1 | 3-5:1 | >5:1 | >7:1 |
+| CAC Payback | >18 mo | 12-18 mo | <12 mo | <8 mo |
+| Burn Multiple | >2x | 1-2x | <1x | <0.5x |
+| Rule of 40 | <30% | 30-45% | >45% | >65% |
+| NDR | <110% | 110-120% | >120% | >140% |
+
+**Context:** Pre-IPO and public companies are measured on absolute efficiency. FCF margin matters as much as growth rate. Best-in-class companies demonstrate both growth and profitability.
+
+---
+
+## Industry Vertical Benchmarks
+
+### Horizontal SaaS (CRM, HR, Finance, Marketing)
+
+| Metric | Median | Top Quartile |
+|--------|--------|-------------|
+| Magic Number | 0.65 | 0.90+ |
+| LTV:CAC | 3.2:1 | 5.5:1+ |
+| CAC Payback | 17 months | 11 months |
+| Gross Margin | 72% | 80%+ |
+| NDR | 108% | 120%+ |
+| Win Rate | 22% | 32%+ |
+
+### Vertical SaaS (Healthcare, FinTech, PropTech)
+
+| Metric | Median | Top Quartile |
+|--------|--------|-------------|
+| Magic Number | 0.55 | 0.80+ |
+| LTV:CAC | 3.8:1 | 6.0:1+ |
+| CAC Payback | 15 months | 10 months |
+| Gross Margin | 68% | 76%+ |
+| NDR | 112% | 125%+ |
+| Win Rate | 25% | 38%+ |
+
+**Note:** Vertical SaaS often has higher NDR (deeper embedding) and higher win rates (less competition) but lower gross margins (more services).
+
+### Infrastructure / DevTools
+
+| Metric | Median | Top Quartile |
+|--------|--------|-------------|
+| Magic Number | 0.70 | 1.0+ |
+| LTV:CAC | 4.0:1 | 7.0:1+ |
+| CAC Payback | 14 months | 9 months |
+| Gross Margin | 75% | 85%+ |
+| NDR | 118% | 140%+ |
+| Win Rate | 18% | 28%+ |
+
+**Note:** Usage-based pricing in infrastructure drives exceptional NDR but more volatile revenue patterns.
+
+### Security / Compliance
+
+| Metric | Median | Top Quartile |
+|--------|--------|-------------|
+| Magic Number | 0.60 | 0.85+ |
+| LTV:CAC | 3.5:1 | 5.8:1+ |
+| CAC Payback | 16 months | 11 months |
+| Gross Margin | 74% | 82%+ |
+| NDR | 115% | 130%+ |
+| Win Rate | 20% | 30%+ |
+
+---
+
+## Efficiency Improvement Strategies
+
+### Improving Magic Number
+
+**Current: <0.5 (Red) -- Target: >0.75 (Green)**
+
+1. **Channel ROI analysis:** Audit spend by channel (paid, outbound, events, content). Cut bottom 20% performing channels and reallocate.
+
+2. **Sales productivity:** Measure revenue per rep. Identify bottom-quartile performers for coaching or role change. Top performers should be studied and their practices systematized.
+
+3. **Funnel efficiency:** Improve MQL-to-SQL conversion through better lead scoring. Fewer, higher-quality leads reduce wasted sales capacity.
+
+4. **Ramp time reduction:** Accelerate new rep ramp from average 6 months to 4 months through structured onboarding, shadowing, and certification.
+
+5. **Territory optimization:** Ensure territories are balanced by opportunity (not just geography). Over-served territories waste capacity.
+
+### Improving LTV:CAC
+
+**Current: <3:1 (Yellow) -- Target: >5:1 (Green)**
+
+**Increase LTV:**
+- Reduce churn through proactive health scoring and intervention
+- Build expansion playbooks for cross-sell and upsell
+- Increase pricing through value-based packaging
+- Improve product stickiness with integrations and workflows
+
+**Decrease CAC:**
+- Invest in organic channels (content, SEO, community)
+- Implement product-led growth (PLG) motion
+- Optimize paid spend through better targeting and attribution
+- Leverage customer referrals and case studies
+
+### Improving CAC Payback
+
+**Current: >18 months (Yellow) -- Target: <12 months (Green)**
+
+1. **Increase ARPA:** Package features to drive higher initial contract values. Annual prepay discounts accelerate cash collection.
+
+2. **Improve gross margin:** Reduce COGS through automation, self-serve onboarding, and tech-touch customer success.
+
+3. **Reduce CAC:** Same strategies as LTV:CAC improvement on the CAC side.
+
+4. **Contract structure:** Annual or multi-year contracts with upfront payment reduce effective payback period.
+
+### Improving Burn Multiple
+
+**Current: >2x (Yellow) -- Target: <1.5x (Green)**
+
+1. **Revenue efficiency:** Focus on the highest ROI growth activities. Not all ARR is equal -- expansion ARR is typically much cheaper than new logo ARR.
+
+2. **Operational efficiency:** Automate repeatable processes (billing, provisioning, basic support). Reduce headcount growth rate relative to revenue growth rate.
+
+3. **Spending discipline:** Implement zero-based budgeting for non-essential spend. Every dollar of burn should connect to revenue generation.
+
+4. **Revenue acceleration:** Sometimes the best way to improve burn multiple is not cutting costs but accelerating revenue. If you can accelerate revenue growth by 20% with 5% more spend, the burn multiple improves.
+
+### Improving NDR
+
+**Current: 100-110% (Yellow) -- Target: >120% (Green)**
+
+1. **Expansion playbooks:** Define trigger events for upsell (usage thresholds, team growth, feature requests). Arm CSMs with expansion talk tracks.
+
+2. **Usage-based pricing:** Align pricing with customer value creation. As customers use more, they pay more -- naturally drives expansion.
+
+3. **Product-led expansion:** Build in-product prompts for upgrades. Feature gating that shows value of next tier.
+
+4. **Reduce contraction:** Identify reasons for downgrades. Often related to poor adoption of features customers are paying for.
+
+5. **Reduce churn:** Implement early warning system (health scores). Intervene before renewal, not at renewal.
+
+6. **Multi-product strategy:** Cross-sell additional products to existing customers. Second product adoption reduces churn by 30-50%.
+
+---
+
+## Metric Relationships and Trade-offs
+
+### Growth vs. Efficiency
+
+The fundamental tension in SaaS is between growth rate and capital efficiency:
+
+```
+High Growth + High Burn = Blitzscaling (risky but fast)
+High Growth + Low Burn = Efficient Growth (ideal)
+Low Growth + Low Burn = Cash Cow (sustainable but limited)
+Low Growth + High Burn = Trouble (restructure immediately)
+```
+
+**Rule of 40** captures this balance: growth rate + margin should exceed 40%.
+
+### CAC Payback vs. Growth Rate
+
+Shorter CAC payback enables faster reinvestment in growth. A company with 12-month payback can reinvest recovered CAC into new customer acquisition sooner than one with 24-month payback, creating a compounding advantage.
+
+### NDR vs. New Logo Acquisition
+
+High NDR reduces dependence on new logo acquisition for growth:
+- NDR of 120% means 20% growth from existing base before any new customers
+- NDR of 100% means all growth must come from new customers (expensive)
+- NDR of 80% means the company is shrinking and must acquire even more new customers just to replace lost revenue
+
+**Strategic implication:** Invest in NDR improvement before scaling new logo acquisition. Every dollar spent improving NDR has higher ROI than acquiring new customers.
+
+---
+
+## Benchmark Data Sources
+
+The benchmarks in this guide are compiled from:
+
+1. **Bessemer Cloud Index** -- Public cloud company financial data
+2. **KeyBanc SaaS Survey** -- Annual survey of private SaaS companies
+3. **OpenView SaaS Benchmarks** -- Product-led growth focused benchmarks
+4. **Iconiq Growth Analytics** -- Private company growth and efficiency data
+5. **SaaStr Annual Surveys** -- Community-sourced SaaS metrics
+6. **Battery Ventures Software Report** -- Enterprise software metrics
+
+**Note:** Benchmarks shift over time. In capital-constrained environments (higher interest rates), efficiency metrics (burn multiple, Rule of 40) receive more weight. In growth-oriented environments (lower interest rates), growth rate and market share gain importance.
+
+---
+
+## Quarterly Board Reporting Template
+
+When presenting GTM efficiency to the board, organize metrics as follows:
+
+1. **Growth:** ARR, net new ARR, growth rate, NDR
+2. **Efficiency:** Magic Number, LTV:CAC, CAC Payback, Burn Multiple
+3. **Balance:** Rule of 40 score and composition
+4. **Pipeline:** Coverage ratio, velocity, forecast accuracy
+5. **Trends:** Quarter-over-quarter change for each metric with directional indicators
+6. **Benchmarks:** How the company compares to stage-appropriate benchmarks
+7. **Actions:** Top 3 initiatives to improve weakest metrics
diff --git a/skills/business-growth/revenue-operations/references/pipeline-management-framework.md b/skills/business-growth/revenue-operations/references/pipeline-management-framework.md
new file mode 100644
index 00000000..debfe228
--- /dev/null
+++ b/skills/business-growth/revenue-operations/references/pipeline-management-framework.md
@@ -0,0 +1,292 @@
+# Pipeline Management Framework
+
+Best practices for pipeline management including stage definitions, conversion benchmarks, velocity optimization, and inspection cadence.
+
+---
+
+## Pipeline Stage Definitions
+
+A well-defined pipeline requires clear, observable exit criteria at each stage. Subjective stages lead to inaccurate forecasting and unreliable conversion data.
+
+### Recommended Stage Model (B2B SaaS)
+
+| Stage | Name | Exit Criteria | Probability | Typical Duration |
+|-------|------|--------------|-------------|-----------------|
+| S0 | Lead | Contact identified, initial interest signal | 5% | 0-7 days |
+| S1 | Discovery | Pain identified, budget confirmed, stakeholder engaged | 10% | 7-14 days |
+| S2 | Qualification | MEDDPICC criteria met, mutual action plan created | 20% | 14-21 days |
+| S3 | Proposal | Solution presented, pricing delivered, champion confirmed | 40% | 7-14 days |
+| S4 | Negotiation | Commercial terms discussed, legal engaged, verbal commitment | 60% | 7-21 days |
+| S5 | Commit | Contract redlined, signature timeline confirmed | 80% | 3-7 days |
+| S6 | Closed Won | Signed contract received | 100% | -- |
+| SL | Closed Lost | Deal disposition recorded with loss reason | 0% | -- |
+
+### Stage Exit Criteria Best Practices
+
+**Discovery (S1) Exit Criteria:**
+- Pain point articulated by prospect (not assumed by rep)
+- Budget range discussed (even if informal)
+- Decision-making process understood
+- Next meeting scheduled with clear agenda
+
+**Qualification (S2) Exit Criteria:**
+- MEDDPICC or BANT qualification framework completed
+- Economic buyer identified (not just champion)
+- Compelling event or timeline identified
+- Mutual action plan (MAP) shared and agreed upon
+- Technical requirements understood
+
+**Proposal (S3) Exit Criteria:**
+- Solution demo completed and well-received
+- Pricing proposal delivered
+- Champion validated proposal internally
+- Competitive landscape understood
+- No unresolved technical blockers
+
+**Negotiation (S4) Exit Criteria:**
+- Commercial terms discussed (not just pricing, but payment terms, SLA, etc.)
+- Legal review initiated
+- Security/procurement review started
+- Verbal agreement on core terms
+- Close date confirmed within 30 days
+
+**Commit (S5) Exit Criteria:**
+- Final contract sent for signature
+- All legal redlines resolved
+- Procurement approval obtained
+- Signature expected within 7 business days
+
+---
+
+## Conversion Benchmarks by Segment
+
+### SMB (ACV <$25K)
+
+| Transition | Benchmark | Top Quartile |
+|-----------|-----------|--------------|
+| Lead to Discovery | 20-30% | 35%+ |
+| Discovery to Qualification | 40-50% | 55%+ |
+| Qualification to Proposal | 50-60% | 65%+ |
+| Proposal to Negotiation | 55-65% | 70%+ |
+| Negotiation to Close | 65-75% | 80%+ |
+| Overall Win Rate | 20-30% | 35%+ |
+| Avg Cycle Length | 14-30 days | <14 days |
+
+### Mid-Market (ACV $25K-$100K)
+
+| Transition | Benchmark | Top Quartile |
+|-----------|-----------|--------------|
+| Lead to Discovery | 15-25% | 30%+ |
+| Discovery to Qualification | 35-45% | 50%+ |
+| Qualification to Proposal | 45-55% | 60%+ |
+| Proposal to Negotiation | 50-60% | 65%+ |
+| Negotiation to Close | 60-70% | 75%+ |
+| Overall Win Rate | 15-25% | 30%+ |
+| Avg Cycle Length | 30-60 days | <30 days |
+
+### Enterprise (ACV >$100K)
+
+| Transition | Benchmark | Top Quartile |
+|-----------|-----------|--------------|
+| Lead to Discovery | 10-20% | 25%+ |
+| Discovery to Qualification | 30-40% | 45%+ |
+| Qualification to Proposal | 40-50% | 55%+ |
+| Proposal to Negotiation | 45-55% | 60%+ |
+| Negotiation to Close | 55-65% | 70%+ |
+| Overall Win Rate | 10-20% | 25%+ |
+| Avg Cycle Length | 60-120 days | <60 days |
+
+---
+
+## Sales Velocity Optimization
+
+Sales velocity = (# Opportunities x Avg Deal Size x Win Rate) / Avg Cycle Days
+
+Each component is an optimization lever:
+
+### Lever 1: Increase Opportunity Volume
+
+**Strategies:**
+- Invest in inbound marketing (content, SEO, paid)
+- Scale outbound SDR capacity
+- Develop partner/channel sourcing
+- Launch product-led growth (PLG) motion
+- Implement customer referral programs
+
+**Measurement:** Pipeline created ($) per week/month, by source
+
+### Lever 2: Increase Average Deal Size
+
+**Strategies:**
+- Multi-product bundling and packaging
+- Usage-based pricing with growth triggers
+- Land-and-expand with defined expansion playbooks
+- Move upmarket with enterprise features
+- Value-based pricing tied to customer outcomes
+
+**Measurement:** ACV trend by quarter, by segment
+
+### Lever 3: Increase Win Rate
+
+**Strategies:**
+- Implement MEDDPICC qualification rigor
+- Build competitive battle cards and train on them
+- Create multi-threaded relationships (not single-threaded)
+- Develop ROI/business case tools
+- Invest in sales engineering and demo quality
+- Win/loss analysis with structured debriefs
+
+**Measurement:** Win rate by stage entry, by competitor, by rep
+
+### Lever 4: Decrease Sales Cycle Length
+
+**Strategies:**
+- Pre-qualify harder at S1/S2 to remove slow deals
+- Mutual action plans with milestone dates
+- Champion enablement (arm champions with internal selling materials)
+- Parallel processing (legal/security review concurrent with evaluation)
+- Standardized contracts and pre-approved terms
+- Executive sponsor engagement for stuck deals
+
+**Measurement:** Days in each stage, cycle length trend, stage-specific bottlenecks
+
+---
+
+## Pipeline Inspection Cadence
+
+### Daily (Rep Level)
+
+**Focus:** Deal-level activity and next steps
+
+**Questions:**
+- What is the next step for each deal in S3+?
+- Are any deals missing next steps or scheduled meetings?
+- Which deals have not been updated in >3 days?
+
+### Weekly (Manager/Team Level)
+
+**Focus:** Pipeline health and forecast accuracy
+
+**Review Format (45-60 minutes):**
+
+1. **Coverage Check (10 min)**
+ - Current pipeline vs. quota -- is coverage >3x?
+ - Pipeline created this week vs. target
+ - Net pipeline change (created minus closed minus lost)
+
+2. **Deal Inspection (25 min)**
+ - Walk top 10 deals by value in S3+
+ - MEDDPICC validation for each commit deal
+ - Identify deals at risk (aging, single-threaded, no next step)
+
+3. **Forecast Call (10 min)**
+ - Commit, best case, and pipeline forecast
+ - Changes from last week's forecast (what moved and why)
+ - Gaps to plan and remediation
+
+4. **Action Items (5 min)**
+ - Deals needing executive engagement
+ - Pipeline generation actions for next week
+ - Coaching priorities
+
+### Monthly (Leadership Level)
+
+**Focus:** Pipeline trends, velocity, and efficiency
+
+**Review Areas:**
+- Month-over-month pipeline growth trend
+- Conversion rate trends by stage
+- Sales velocity trend (improving or declining?)
+- Forecast accuracy (MAPE) for the month
+- Rep performance distribution (quartile analysis)
+- Pipeline source mix health
+
+### Quarterly (Executive/Board Level)
+
+**Focus:** GTM efficiency and strategic pipeline
+
+**Review Areas:**
+- Pipeline coverage for next 2-3 quarters
+- LTV:CAC and Magic Number trends
+- Sales efficiency ratio trends
+- Market segment performance comparison
+- New market/product pipeline contribution
+- Competitive win/loss trends
+
+---
+
+## Pipeline Hygiene
+
+### Deal Hygiene Standards
+
+1. **Close date accuracy:** Close dates must be based on buyer commitment, not rep hope. Any deal pushed more than twice should be flagged for re-qualification.
+
+2. **Stage accuracy:** Deals must meet exit criteria to be in a stage. No deal should be in Proposal (S3) without a pricing deliverable sent.
+
+3. **Amount accuracy:** Deal amounts must reflect the current proposal, not aspirational upsell. Variance between deal value and proposal should be <10%.
+
+4. **Contact coverage:** Deals >$50K should have 3+ contacts associated. Enterprise deals should have economic buyer, champion, and technical evaluator.
+
+5. **Activity recency:** No deal should go 7+ days without logged activity. Deals without recent activity signal stalling.
+
+### Pipeline Cleanup Triggers
+
+Run cleanup when:
+- Pipeline-to-quota ratio drops below 2.5x
+- Forecast accuracy (MAPE) exceeds 20%
+- More than 15% of pipeline is >90 days old
+- Average deal age exceeds 1.5x normal cycle time
+
+### Cleanup Process
+
+1. Flag all deals with close date in the past
+2. Flag all deals with no activity in 14+ days
+3. Flag all deals pushed 3+ times
+4. Rep self-assessment: keep, push, or close for each flagged deal
+5. Manager review and disposition
+6. Update CRM and recalculate metrics
+
+---
+
+## Pipeline Risk Indicators
+
+### Concentration Risk
+
+**Definition:** Over-reliance on a small number of large deals.
+
+**Thresholds:**
+- Single deal >40% of pipeline = HIGH risk
+- Single deal >25% of pipeline = MEDIUM risk
+- Top 3 deals >70% of pipeline = HIGH risk
+
+**Mitigation:** Diversify pipeline across segments, deal sizes, and sources. Increase deal count even if average deal size decreases.
+
+### Stage Imbalance Risk
+
+**Definition:** Pipeline is concentrated in early or late stages with gaps in between.
+
+**Healthy Distribution:**
+- Discovery/Qualification: 50-60% of pipeline value
+- Proposal: 20-25% of pipeline value
+- Negotiation/Commit: 15-20% of pipeline value
+
+**Warning Signs:**
+- >70% in early stages = insufficient progression
+- >50% in late stages = insufficient pipeline generation
+- Empty stages = broken funnel mechanics
+
+### Temporal Risk
+
+**Definition:** Pipeline is concentrated in a single quarter or lacks coverage for future quarters.
+
+**Standard:** Maintain 3x coverage for current quarter and 1.5x for next quarter.
+
+### Source Risk
+
+**Definition:** Pipeline is overly dependent on a single source (e.g., 80% outbound, 0% inbound).
+
+**Healthy Mix (varies by stage):**
+- Inbound/Marketing: 30-40%
+- Outbound/SDR: 30-40%
+- Partner/Channel: 10-20%
+- Expansion/Customer: 10-20%
diff --git a/skills/business-growth/revenue-operations/references/revops-metrics-guide.md b/skills/business-growth/revenue-operations/references/revops-metrics-guide.md
new file mode 100644
index 00000000..38762ff7
--- /dev/null
+++ b/skills/business-growth/revenue-operations/references/revops-metrics-guide.md
@@ -0,0 +1,304 @@
+# RevOps Metrics Guide
+
+Complete reference for Revenue Operations metrics hierarchy, definitions, formulas, interpretation guidelines, and common mistakes.
+
+---
+
+## Metrics Hierarchy
+
+Revenue Operations metrics are organized in a hierarchy from leading indicators (pipeline activity) through lagging indicators (efficiency outcomes):
+
+```
+Level 1: Activity Metrics (Leading)
+ ├── Pipeline created ($, #)
+ ├── Meetings booked
+ ├── Proposals sent
+ └── Demo completion rate
+
+Level 2: Pipeline Metrics (Mid-funnel)
+ ├── Pipeline coverage ratio
+ ├── Stage conversion rates
+ ├── Sales velocity
+ ├── Deal aging
+ └── Pipeline hygiene score
+
+Level 3: Revenue Metrics (Outcomes)
+ ├── Bookings (new, expansion, renewal)
+ ├── Revenue (ARR, MRR, TCV)
+ ├── Win rate
+ └── Average deal size
+
+Level 4: Efficiency Metrics (Unit Economics)
+ ├── Magic Number
+ ├── LTV:CAC Ratio
+ ├── CAC Payback Period
+ ├── Burn Multiple
+ ├── Rule of 40
+ └── Net Dollar Retention
+
+Level 5: Strategic Metrics (Board-Level)
+ ├── Revenue per employee
+ ├── Gross margin trend
+ ├── NRR cohort analysis
+ └── Customer health score
+```
+
+---
+
+## Core Metric Definitions
+
+### Pipeline Coverage Ratio
+
+**Formula:** Total Weighted Pipeline / Quota Target
+
+**What it measures:** Whether there is sufficient pipeline to meet revenue targets.
+
+**Interpretation:**
+- 4x+: Strong coverage, selective deal pursuit possible
+- 3-4x: Healthy coverage, standard operations
+- 2-3x: At risk, accelerate pipeline generation
+- <2x: Critical, immediate pipeline intervention needed
+
+**Common Mistakes:**
+- Including closed-won deals in the pipeline total
+- Not weighting by stage probability
+- Using annual quota against quarterly pipeline
+- Ignoring deal quality in favor of quantity
+
+**Best Practice:** Measure coverage ratio weekly. Track by quarter to identify seasonal gaps early.
+
+---
+
+### Stage Conversion Rates
+
+**Formula:** # Deals advancing to Stage N+1 / # Deals entering Stage N
+
+**What it measures:** Efficiency of progression through each pipeline stage.
+
+**Typical SaaS Conversion Benchmarks:**
+| Stage Transition | Median Rate | Top Quartile |
+|-----------------|-------------|--------------|
+| Lead to Qualification | 15-25% | 30%+ |
+| Qualification to Proposal | 40-50% | 60%+ |
+| Proposal to Negotiation | 50-60% | 70%+ |
+| Negotiation to Close | 60-70% | 80%+ |
+| Overall Win Rate | 15-25% | 30%+ |
+
+**Common Mistakes:**
+- Not standardizing stage exit criteria (subjective stages)
+- Comparing conversion rates across different sales motions (PLG vs enterprise)
+- Ignoring stage skipping (deals that jump stages inflate later conversion rates)
+- Not segmenting by deal size or segment
+
+---
+
+### Sales Velocity
+
+**Formula:** (# Opportunities x Avg Deal Size x Win Rate) / Avg Sales Cycle Days
+
+**What it measures:** The rate at which the pipeline generates revenue, measured as revenue per day.
+
+**Components:**
+1. **# Opportunities** -- Volume of qualified deals in pipeline
+2. **Avg Deal Size** -- Average contract value of won deals
+3. **Win Rate** -- Percentage of deals that close
+4. **Avg Sales Cycle** -- Days from opportunity creation to close
+
+**Optimization levers:**
+- Increase opportunity volume (marketing/SDR investment)
+- Increase deal size (pricing, packaging, upsell)
+- Increase win rate (sales enablement, competitive positioning)
+- Decrease cycle length (champion building, MEDDPICC adherence)
+
+**Common Mistakes:**
+- Using all pipeline deals instead of qualified opportunities
+- Not normalizing for segment (SMB velocity vs Enterprise velocity)
+- Conflating calendar time with active selling time
+- Ignoring velocity trend in favor of absolute number
+
+---
+
+### MAPE (Mean Absolute Percentage Error)
+
+**Formula:** mean(|Actual - Forecast| / |Actual|) x 100
+
+**What it measures:** Average forecast error magnitude as a percentage.
+
+**Interpretation:**
+| MAPE | Rating | Action |
+|------|--------|--------|
+| <10% | Excellent | Maintain current methodology |
+| 10-15% | Good | Minor calibration adjustments |
+| 15-25% | Fair | Methodology review needed |
+| >25% | Poor | Fundamental process overhaul |
+
+**Common Mistakes:**
+- Using forecast vs. target instead of forecast vs. actual
+- Not distinguishing between bias (systematic) and variance (random)
+- Measuring only at the aggregate level (masks individual rep errors)
+- Comparing MAPE across different time horizons (monthly vs quarterly)
+
+---
+
+### Forecast Bias
+
+**Formula:** mean(Forecast - Actual) / mean(Actual) x 100
+
+**What it measures:** Systematic tendency to over-forecast or under-forecast.
+
+**Types:**
+- **Positive bias (over-forecasting):** Forecast consistently exceeds actual. Often indicates optimistic deal assessment, insufficient qualification, or sandbagging reversal.
+- **Negative bias (under-forecasting):** Actual consistently exceeds forecast. Often indicates conservative call culture, late-stage deals arriving unexpectedly, or poor pipeline visibility.
+
+**Healthy Range:** Bias within +/- 5% of actual is considered well-calibrated.
+
+---
+
+### Magic Number
+
+**Formula:** Net New ARR / Prior Period S&M Spend
+
+**What it measures:** Efficiency of sales & marketing spend in generating new revenue.
+
+**Interpretation:**
+- >1.0: Extremely efficient, consider increasing GTM investment
+- 0.75-1.0: Healthy efficiency, optimize and scale
+- 0.50-0.75: Acceptable, focus on channel/spend optimization
+- <0.50: Inefficient, audit spend allocation and productivity
+
+**Common Mistakes:**
+- Using total revenue instead of net new ARR
+- Including expansion ARR (Magic Number measures new logo efficiency)
+- Using current period spend instead of prior period (lag effect)
+- Not separating sales spend from marketing spend for diagnostics
+
+---
+
+### LTV:CAC Ratio
+
+**Formula:** Customer Lifetime Value / Customer Acquisition Cost
+
+**Where:**
+- LTV = (ARPA x Gross Margin) / Churn Rate
+- ARPA = Average Revenue Per Account (annualized)
+- CAC = Total S&M Spend / New Customers Acquired
+
+**Target:** >3:1 is healthy; >5:1 may indicate under-investment in growth
+
+**Common Mistakes:**
+- Using revenue instead of gross-margin-weighted revenue in LTV
+- Not including all acquisition costs (SDR, marketing, sales engineering)
+- Using blended churn instead of cohort-specific churn
+- Comparing across segments without normalizing (enterprise LTV:CAC is naturally higher)
+
+---
+
+### CAC Payback Period
+
+**Formula:** CAC / (ARPA_monthly x Gross Margin)
+
+**What it measures:** Months to recover the cost of acquiring a customer.
+
+**Interpretation:**
+- <12 months: Excellent capital efficiency
+- 12-18 months: Healthy, especially for mid-market/enterprise
+- 18-24 months: Acceptable for enterprise, concerning for SMB
+- >24 months: Capital-intensive, needs optimization
+
+**Common Mistakes:**
+- Using revenue instead of gross-margin contribution
+- Ignoring expansion revenue in payback calculation (conservative approach)
+- Comparing SMB payback to enterprise payback without context
+
+---
+
+### Burn Multiple
+
+**Formula:** Net Burn / Net New ARR
+
+**What it measures:** How much cash is consumed for each dollar of new ARR.
+
+**Interpretation (David Sacks framework):**
+- <1.0x: Amazing -- hyper-efficient growth
+- 1.0-1.5x: Great -- strong capital efficiency
+- 1.5-2.0x: Good -- healthy burn rate
+- 2.0-3.0x: Suspect -- needs attention
+- >3.0x: Bad -- unsustainable without course correction
+
+**Common Mistakes:**
+- Using gross burn instead of net burn
+- Not annualizing ARR when using quarterly burn
+- Ignoring the denominator quality (all new ARR is not equal)
+
+---
+
+### Rule of 40
+
+**Formula:** Revenue Growth Rate (%) + Free Cash Flow Margin (%)
+
+**What it measures:** Balance between growth and profitability.
+
+**Interpretation:**
+- >60%: Elite SaaS company
+- 40-60%: Strong performance
+- 20-40%: Acceptable, optimize one dimension
+- <20%: Needs significant improvement
+
+**Common Mistakes:**
+- Using EBITDA margin instead of FCF margin
+- Comparing early-stage (growth-heavy) with late-stage (margin-heavy)
+- Not considering the composition (80% growth + -40% margin vs 30% + 10%)
+
+---
+
+### Net Dollar Retention (NDR)
+
+**Formula:** (Beginning ARR + Expansion - Contraction - Churn) / Beginning ARR x 100
+
+**What it measures:** Revenue retention and expansion from existing customers.
+
+**Interpretation:**
+- >130%: World-class expansion (Snowflake, Datadog)
+- 120-130%: Excellent land-and-expand
+- 110-120%: Strong retention with moderate expansion
+- 100-110%: Stable base, limited expansion
+- <100%: Net revenue contraction -- critical concern
+
+**Common Mistakes:**
+- Including new logos in the calculation
+- Not normalizing for cohort age (newer cohorts expand differently)
+- Confusing gross retention with net retention
+- Using logo retention as a proxy for dollar retention
+
+---
+
+## Metric Interdependencies
+
+Understanding how metrics relate prevents conflicting optimizations:
+
+1. **Magic Number and LTV:CAC** -- Both use S&M spend but measure different horizons. Magic Number is period-specific; LTV:CAC is lifetime.
+
+2. **Burn Multiple and Rule of 40** -- Both measure efficiency but from different angles. Burn Multiple is cash-focused; Rule of 40 balances growth with profitability.
+
+3. **Pipeline Coverage and Sales Velocity** -- High coverage with low velocity means pipeline is stagnating. Both must be healthy.
+
+4. **NDR and LTV** -- NDR directly impacts LTV. Improving NDR is the highest-leverage way to improve LTV:CAC.
+
+5. **Win Rate and Deal Size** -- Often inversely correlated. Moving upmarket increases deal size but may reduce win rate.
+
+---
+
+## Measurement Cadence
+
+| Metric | Cadence | Owner |
+|--------|---------|-------|
+| Pipeline Coverage | Weekly | Sales Leadership |
+| Stage Conversion | Bi-weekly | Sales Ops |
+| Sales Velocity | Monthly | RevOps |
+| Forecast Accuracy (MAPE) | Monthly/Quarterly | RevOps |
+| Magic Number | Quarterly | CRO/CFO |
+| LTV:CAC | Quarterly | Finance/RevOps |
+| CAC Payback | Quarterly | Finance |
+| Burn Multiple | Quarterly | CFO |
+| Rule of 40 | Quarterly/Annual | CEO/Board |
+| NDR | Quarterly | CS/RevOps |
diff --git a/skills/business-growth/revenue-operations/scripts/forecast_accuracy_tracker.py b/skills/business-growth/revenue-operations/scripts/forecast_accuracy_tracker.py
new file mode 100644
index 00000000..835ba642
--- /dev/null
+++ b/skills/business-growth/revenue-operations/scripts/forecast_accuracy_tracker.py
@@ -0,0 +1,531 @@
+#!/usr/bin/env python3
+"""Forecast Accuracy Tracker - Measures forecast accuracy and bias for SaaS revenue teams.
+
+Calculates MAPE (Mean Absolute Percentage Error), detects systematic forecasting
+bias, analyzes accuracy trends, and provides category-level breakdowns.
+
+Usage:
+ python forecast_accuracy_tracker.py forecast_data.json --format text
+ python forecast_accuracy_tracker.py forecast_data.json --format json
+"""
+
+import argparse
+import json
+import sys
+from typing import Any
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def calculate_mape(periods: list[dict]) -> float:
+ """Calculate Mean Absolute Percentage Error.
+
+ Formula: mean(|actual - forecast| / |actual|) x 100
+
+ Args:
+ periods: List of dicts with 'forecast' and 'actual' keys.
+
+ Returns:
+ MAPE as a percentage.
+ """
+ if not periods:
+ return 0.0
+
+ errors = []
+ for p in periods:
+ actual = p["actual"]
+ forecast = p["forecast"]
+ if actual != 0:
+ errors.append(abs(actual - forecast) / abs(actual))
+
+ if not errors:
+ return 0.0
+
+ return (sum(errors) / len(errors)) * 100
+
+
+def calculate_weighted_mape(periods: list[dict]) -> float:
+ """Calculate value-weighted MAPE.
+
+ Weights each period's error by its actual value, giving more importance
+ to larger periods.
+
+ Args:
+ periods: List of dicts with 'forecast' and 'actual' keys.
+
+ Returns:
+ Weighted MAPE as a percentage.
+ """
+ if not periods:
+ return 0.0
+
+ total_actual = sum(abs(p["actual"]) for p in periods)
+ if total_actual == 0:
+ return 0.0
+
+ weighted_errors = 0.0
+ for p in periods:
+ actual = p["actual"]
+ forecast = p["forecast"]
+ if actual != 0:
+ weight = abs(actual) / total_actual
+ weighted_errors += weight * (abs(actual - forecast) / abs(actual))
+
+ return weighted_errors * 100
+
+
+def get_accuracy_rating(mape: float) -> dict[str, str]:
+ """Return accuracy rating based on MAPE threshold.
+
+ Ratings:
+ Excellent: <10%
+ Good: 10-15%
+ Fair: 15-25%
+ Poor: >25%
+ """
+ if mape < 10:
+ return {"rating": "Excellent", "description": "Highly predictable, data-driven process"}
+ elif mape < 15:
+ return {"rating": "Good", "description": "Reliable forecasting with minor variance"}
+ elif mape < 25:
+ return {"rating": "Fair", "description": "Needs process improvement"}
+ else:
+ return {"rating": "Poor", "description": "Significant forecasting methodology gaps"}
+
+
+def analyze_bias(periods: list[dict]) -> dict[str, Any]:
+ """Analyze systematic forecasting bias.
+
+ Positive bias = over-forecasting (forecast > actual, i.e., actual fell short)
+ Negative bias = under-forecasting (forecast < actual, i.e., actual exceeded)
+
+ Args:
+ periods: List of dicts with 'forecast' and 'actual' keys.
+
+ Returns:
+ Bias analysis with direction, magnitude, and ratio.
+ """
+ if not periods:
+ return {
+ "direction": "None",
+ "bias_pct": 0.0,
+ "over_forecast_count": 0,
+ "under_forecast_count": 0,
+ "exact_count": 0,
+ "bias_ratio": 0.0,
+ }
+
+ over_count = 0
+ under_count = 0
+ exact_count = 0
+ total_bias = 0.0
+
+ for p in periods:
+ diff = p["forecast"] - p["actual"]
+ total_bias += diff
+ if diff > 0:
+ over_count += 1
+ elif diff < 0:
+ under_count += 1
+ else:
+ exact_count += 1
+
+ avg_bias = total_bias / len(periods)
+ total_actual = sum(p["actual"] for p in periods)
+ bias_pct = safe_divide(total_bias, total_actual) * 100
+
+ if over_count > under_count:
+ direction = "Over-forecasting"
+ elif under_count > over_count:
+ direction = "Under-forecasting"
+ else:
+ direction = "Balanced"
+
+ bias_ratio = safe_divide(over_count, over_count + under_count)
+
+ return {
+ "direction": direction,
+ "avg_bias_amount": round(avg_bias, 2),
+ "bias_pct": round(bias_pct, 1),
+ "over_forecast_count": over_count,
+ "under_forecast_count": under_count,
+ "exact_count": exact_count,
+ "bias_ratio": round(bias_ratio, 2),
+ }
+
+
+def analyze_trend(periods: list[dict]) -> dict[str, Any]:
+ """Analyze period-over-period accuracy trend.
+
+ Determines if forecast accuracy is improving, stable, or declining
+ by comparing error rates across consecutive periods.
+
+ Args:
+ periods: List of dicts with 'period', 'forecast', and 'actual' keys.
+
+ Returns:
+ Trend analysis with direction and period details.
+ """
+ if len(periods) < 2:
+ return {
+ "trend": "Insufficient data",
+ "period_errors": [],
+ "improving_periods": 0,
+ "declining_periods": 0,
+ }
+
+ period_errors = []
+ for p in periods:
+ actual = p["actual"]
+ forecast = p["forecast"]
+ if actual != 0:
+ error_pct = abs(actual - forecast) / abs(actual) * 100
+ else:
+ error_pct = 0.0
+ period_errors.append({
+ "period": p.get("period", "Unknown"),
+ "error_pct": round(error_pct, 1),
+ "forecast": forecast,
+ "actual": actual,
+ })
+
+ improving = 0
+ declining = 0
+ for i in range(1, len(period_errors)):
+ if period_errors[i]["error_pct"] < period_errors[i - 1]["error_pct"]:
+ improving += 1
+ elif period_errors[i]["error_pct"] > period_errors[i - 1]["error_pct"]:
+ declining += 1
+
+ if improving > declining:
+ trend = "Improving"
+ elif declining > improving:
+ trend = "Declining"
+ else:
+ trend = "Stable"
+
+ # Calculate recent vs historical MAPE
+ midpoint = len(periods) // 2
+ if midpoint > 0:
+ early_mape = calculate_mape(periods[:midpoint])
+ recent_mape = calculate_mape(periods[midpoint:])
+ mape_change = recent_mape - early_mape
+ else:
+ early_mape = 0.0
+ recent_mape = 0.0
+ mape_change = 0.0
+
+ return {
+ "trend": trend,
+ "period_errors": period_errors,
+ "improving_periods": improving,
+ "declining_periods": declining,
+ "early_mape": round(early_mape, 1),
+ "recent_mape": round(recent_mape, 1),
+ "mape_change": round(mape_change, 1),
+ }
+
+
+def analyze_categories(category_breakdowns: dict) -> dict[str, Any]:
+ """Analyze accuracy by category (rep, product, segment, etc.).
+
+ Args:
+ category_breakdowns: Dict of category_name -> list of
+ {category, forecast, actual} dicts.
+
+ Returns:
+ Category-level MAPE and accuracy analysis.
+ """
+ results = {}
+
+ for category_name, entries in category_breakdowns.items():
+ category_results = []
+ for entry in entries:
+ actual = entry["actual"]
+ forecast = entry["forecast"]
+ if actual != 0:
+ error_pct = abs(actual - forecast) / abs(actual) * 100
+ else:
+ error_pct = 0.0
+
+ diff = forecast - actual
+ if diff > 0:
+ bias = "Over"
+ elif diff < 0:
+ bias = "Under"
+ else:
+ bias = "Exact"
+
+ rating = get_accuracy_rating(error_pct)
+
+ category_results.append({
+ "category": entry["category"],
+ "forecast": forecast,
+ "actual": actual,
+ "error_pct": round(error_pct, 1),
+ "bias": bias,
+ "variance": round(diff, 2),
+ "rating": rating["rating"],
+ })
+
+ # Sort by error percentage (worst first)
+ category_results.sort(key=lambda x: x["error_pct"], reverse=True)
+
+ overall_mape = calculate_mape(entries)
+ results[category_name] = {
+ "entries": category_results,
+ "overall_mape": round(overall_mape, 1),
+ "overall_rating": get_accuracy_rating(overall_mape)["rating"],
+ }
+
+ return results
+
+
+def generate_recommendations(
+ mape: float, bias: dict, trend: dict, categories: dict
+) -> list[str]:
+ """Generate actionable recommendations based on analysis results.
+
+ Args:
+ mape: Overall MAPE percentage.
+ bias: Bias analysis results.
+ trend: Trend analysis results.
+ categories: Category analysis results.
+
+ Returns:
+ List of recommendation strings.
+ """
+ recommendations = []
+
+ # MAPE-based recommendations
+ if mape > 25:
+ recommendations.append(
+ "CRITICAL: MAPE exceeds 25%. Implement structured forecasting methodology "
+ "(e.g., weighted pipeline with stage-based probabilities)."
+ )
+ elif mape > 15:
+ recommendations.append(
+ "Forecast accuracy needs improvement. Consider implementing deal-level "
+ "forecasting with commit/upside/pipeline categories."
+ )
+
+ # Bias-based recommendations
+ if bias["direction"] == "Over-forecasting" and abs(bias["bias_pct"]) > 10:
+ recommendations.append(
+ f"Systematic over-forecasting detected ({bias['bias_pct']}% bias). "
+ "Review deal qualification criteria and apply more conservative "
+ "stage probabilities."
+ )
+ elif bias["direction"] == "Under-forecasting" and abs(bias["bias_pct"]) > 10:
+ recommendations.append(
+ f"Systematic under-forecasting detected ({bias['bias_pct']}% bias). "
+ "Review upside deals more carefully and improve pipeline visibility."
+ )
+
+ # Trend-based recommendations
+ if trend["trend"] == "Declining":
+ recommendations.append(
+ "Forecast accuracy is declining over time. Schedule a forecasting "
+ "methodology review and retrain the team on forecasting best practices."
+ )
+ elif trend["trend"] == "Improving":
+ recommendations.append(
+ "Forecast accuracy is improving. Continue current methodology and "
+ "document best practices for consistency."
+ )
+
+ # Category-based recommendations
+ for cat_name, cat_data in categories.items():
+ worst_entries = [
+ e for e in cat_data["entries"] if e["error_pct"] > 25
+ ]
+ if worst_entries:
+ names = ", ".join(e["category"] for e in worst_entries[:3])
+ recommendations.append(
+ f"High error rates in {cat_name}: {names}. "
+ f"Provide targeted coaching on forecasting discipline."
+ )
+
+ if not recommendations:
+ recommendations.append(
+ "Forecasting performance is strong. Maintain current processes "
+ "and continue monitoring for drift."
+ )
+
+ return recommendations
+
+
+def track_forecast_accuracy(data: dict) -> dict[str, Any]:
+ """Run complete forecast accuracy analysis.
+
+ Args:
+ data: Forecast data with periods and optional category breakdowns.
+
+ Returns:
+ Complete forecast accuracy analysis results.
+ """
+ periods = data["forecast_periods"]
+
+ mape = calculate_mape(periods)
+ weighted_mape = calculate_weighted_mape(periods)
+ rating = get_accuracy_rating(mape)
+ bias = analyze_bias(periods)
+ trend = analyze_trend(periods)
+
+ categories = {}
+ if "category_breakdowns" in data:
+ categories = analyze_categories(data["category_breakdowns"])
+
+ recommendations = generate_recommendations(mape, bias, trend, categories)
+
+ return {
+ "mape": round(mape, 1),
+ "weighted_mape": round(weighted_mape, 1),
+ "accuracy_rating": rating,
+ "bias": bias,
+ "trend": trend,
+ "category_breakdowns": categories,
+ "recommendations": recommendations,
+ "periods_analyzed": len(periods),
+ }
+
+
+def format_currency(value: float) -> str:
+ """Format a number as currency."""
+ if abs(value) >= 1_000_000:
+ return f"${value / 1_000_000:,.1f}M"
+ elif abs(value) >= 1_000:
+ return f"${value / 1_000:,.1f}K"
+ return f"${value:,.0f}"
+
+
+def format_text_report(results: dict) -> str:
+ """Format analysis results as a human-readable text report."""
+ lines = []
+ lines.append("=" * 70)
+ lines.append("FORECAST ACCURACY REPORT")
+ lines.append("=" * 70)
+
+ # Overall accuracy
+ lines.append("")
+ lines.append("OVERALL ACCURACY")
+ lines.append("-" * 40)
+ lines.append(f" MAPE: {results['mape']}%")
+ lines.append(f" Weighted MAPE: {results['weighted_mape']}%")
+ lines.append(f" Rating: {results['accuracy_rating']['rating']}")
+ lines.append(f" Assessment: {results['accuracy_rating']['description']}")
+ lines.append(f" Periods Analyzed: {results['periods_analyzed']}")
+
+ # Bias analysis
+ bias = results["bias"]
+ lines.append("")
+ lines.append("FORECAST BIAS")
+ lines.append("-" * 40)
+ lines.append(f" Direction: {bias['direction']}")
+ lines.append(f" Bias %: {bias['bias_pct']}%")
+ lines.append(f" Avg Bias Amount: {format_currency(bias['avg_bias_amount'])}")
+ lines.append(f" Over-forecast: {bias['over_forecast_count']} periods")
+ lines.append(f" Under-forecast: {bias['under_forecast_count']} periods")
+ lines.append(f" Bias Ratio: {bias['bias_ratio']}")
+
+ # Trend analysis
+ trend = results["trend"]
+ lines.append("")
+ lines.append("ACCURACY TREND")
+ lines.append("-" * 40)
+ lines.append(f" Trend: {trend['trend']}")
+ lines.append(f" Improving: {trend['improving_periods']} periods")
+ lines.append(f" Declining: {trend['declining_periods']} periods")
+ if trend.get("early_mape") is not None and trend["trend"] != "Insufficient data":
+ lines.append(f" Early MAPE: {trend['early_mape']}%")
+ lines.append(f" Recent MAPE: {trend['recent_mape']}%")
+ lines.append(f" MAPE Change: {trend['mape_change']:+.1f}%")
+
+ if trend.get("period_errors"):
+ lines.append("")
+ lines.append(" PERIOD DETAIL:")
+ for pe in trend["period_errors"]:
+ lines.append(
+ f" {pe['period']:12s} "
+ f"Forecast: {format_currency(pe['forecast']):>10s} "
+ f"Actual: {format_currency(pe['actual']):>10s} "
+ f"Error: {pe['error_pct']}%"
+ )
+
+ # Category breakdowns
+ if results["category_breakdowns"]:
+ lines.append("")
+ lines.append("CATEGORY BREAKDOWN")
+ lines.append("-" * 40)
+ for cat_name, cat_data in results["category_breakdowns"].items():
+ lines.append(
+ f"\n {cat_name.upper()} (Overall MAPE: {cat_data['overall_mape']}% "
+ f"- {cat_data['overall_rating']})"
+ )
+ for entry in cat_data["entries"]:
+ lines.append(
+ f" {entry['category']:20s} "
+ f"Error: {entry['error_pct']:5.1f}% "
+ f"Bias: {entry['bias']:5s} "
+ f"Rating: {entry['rating']}"
+ )
+
+ # Recommendations
+ lines.append("")
+ lines.append("RECOMMENDATIONS")
+ lines.append("-" * 40)
+ for i, rec in enumerate(results["recommendations"], 1):
+ lines.append(f" {i}. {rec}")
+
+ lines.append("")
+ lines.append("=" * 70)
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for forecast accuracy tracker CLI."""
+ parser = argparse.ArgumentParser(
+ description="Track and analyze forecast accuracy for SaaS revenue teams."
+ )
+ parser.add_argument(
+ "input",
+ help="Path to JSON file containing forecast data",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ help="Output format: json or text (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ try:
+ with open(args.input, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ if "forecast_periods" not in data:
+ print("Error: Missing required field 'forecast_periods' in input data", file=sys.stderr)
+ sys.exit(1)
+
+ results = track_forecast_accuracy(data)
+
+ if args.format == "json":
+ print(json.dumps(results, indent=2))
+ else:
+ print(format_text_report(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/business-growth/revenue-operations/scripts/gtm_efficiency_calculator.py b/skills/business-growth/revenue-operations/scripts/gtm_efficiency_calculator.py
new file mode 100644
index 00000000..1fd975bf
--- /dev/null
+++ b/skills/business-growth/revenue-operations/scripts/gtm_efficiency_calculator.py
@@ -0,0 +1,658 @@
+#!/usr/bin/env python3
+"""GTM Efficiency Calculator - Calculates go-to-market efficiency metrics for SaaS.
+
+Computes Magic Number, LTV:CAC, CAC Payback, Burn Multiple, Rule of 40,
+and Net Dollar Retention with industry benchmarking and ratings.
+
+Usage:
+ python gtm_efficiency_calculator.py gtm_data.json --format text
+ python gtm_efficiency_calculator.py gtm_data.json --format json
+"""
+
+import argparse
+import json
+import sys
+from typing import Any
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+# --- Benchmark tables ---
+# Each benchmark defines green/yellow/red thresholds
+# and optional percentile placement guidance
+
+BENCHMARKS = {
+ "magic_number": {
+ "green": {"min": 0.75, "label": ">0.75 - Efficient GTM spend"},
+ "yellow": {"min": 0.50, "max": 0.75, "label": "0.50-0.75 - Acceptable efficiency"},
+ "red": {"max": 0.50, "label": "<0.50 - Inefficient GTM spend"},
+ "elite": 1.0,
+ "description": "Net New ARR / Prior Period S&M Spend",
+ },
+ "ltv_cac_ratio": {
+ "green": {"min": 3.0, "label": ">3:1 - Strong unit economics"},
+ "yellow": {"min": 1.0, "max": 3.0, "label": "1:1-3:1 - Marginal unit economics"},
+ "red": {"max": 1.0, "label": "<1:1 - Unsustainable unit economics"},
+ "elite": 5.0,
+ "description": "Customer LTV / Customer Acquisition Cost",
+ },
+ "cac_payback_months": {
+ "green": {"max": 18, "label": "<18 months - Healthy payback"},
+ "yellow": {"min": 18, "max": 24, "label": "18-24 months - Acceptable payback"},
+ "red": {"min": 24, "label": ">24 months - Capital intensive"},
+ "elite": 12,
+ "description": "CAC / (ARPA x Gross Margin) in months",
+ },
+ "burn_multiple": {
+ "green": {"max": 2.0, "label": "<2x - Capital efficient growth"},
+ "yellow": {"min": 2.0, "max": 4.0, "label": "2-4x - Moderate burn"},
+ "red": {"min": 4.0, "label": ">4x - Unsustainable burn"},
+ "elite": 1.0,
+ "description": "Net Burn / Net New ARR",
+ },
+ "rule_of_40": {
+ "green": {"min": 40, "label": ">40% - Strong balance of growth & profitability"},
+ "yellow": {"min": 20, "max": 40, "label": "20-40% - Acceptable balance"},
+ "red": {"max": 20, "label": "<20% - Needs improvement"},
+ "elite": 60,
+ "description": "Revenue Growth % + FCF Margin %",
+ },
+ "ndr_pct": {
+ "green": {"min": 110, "label": ">110% - Strong expansion revenue"},
+ "yellow": {"min": 100, "max": 110, "label": "100-110% - Stable base"},
+ "red": {"max": 100, "label": "<100% - Net revenue contraction"},
+ "elite": 130,
+ "description": "(Begin ARR + Expansion - Contraction - Churn) / Begin ARR",
+ },
+}
+
+
+def rate_metric(metric_name: str, value: float) -> dict[str, str]:
+ """Rate a metric as Green/Yellow/Red based on benchmark thresholds.
+
+ Args:
+ metric_name: Key into BENCHMARKS dict.
+ value: The metric value to rate.
+
+ Returns:
+ Dict with rating color, label, and percentile guidance.
+ """
+ bench = BENCHMARKS.get(metric_name)
+ if not bench:
+ return {"rating": "Unknown", "label": "No benchmark available"}
+
+ # For metrics where lower is better (cac_payback, burn_multiple)
+ lower_is_better = metric_name in ("cac_payback_months", "burn_multiple")
+
+ if lower_is_better:
+ if "max" in bench["green"] and value <= bench["green"]["max"]:
+ rating = "Green"
+ label = bench["green"]["label"]
+ elif "min" in bench.get("yellow", {}) and "max" in bench.get("yellow", {}):
+ if bench["yellow"]["min"] <= value <= bench["yellow"]["max"]:
+ rating = "Yellow"
+ label = bench["yellow"]["label"]
+ else:
+ rating = "Red"
+ label = bench["red"]["label"]
+ else:
+ rating = "Red"
+ label = bench["red"]["label"]
+ else:
+ if "min" in bench["green"] and value >= bench["green"]["min"]:
+ rating = "Green"
+ label = bench["green"]["label"]
+ elif "min" in bench.get("yellow", {}) and "max" in bench.get("yellow", {}):
+ if bench["yellow"]["min"] <= value <= bench["yellow"]["max"]:
+ rating = "Yellow"
+ label = bench["yellow"]["label"]
+ else:
+ rating = "Red"
+ label = bench["red"]["label"]
+ else:
+ rating = "Red"
+ label = bench["red"]["label"]
+
+ # Percentile placement (simplified)
+ elite = bench.get("elite", 0)
+ if lower_is_better:
+ if elite > 0 and value > 0:
+ if value <= elite:
+ percentile = "Top 10%"
+ elif rating == "Green":
+ percentile = "Top 25%"
+ elif rating == "Yellow":
+ percentile = "Median"
+ else:
+ percentile = "Below median"
+ else:
+ percentile = "N/A"
+ else:
+ if elite > 0:
+ if value >= elite:
+ percentile = "Top 10%"
+ elif rating == "Green":
+ percentile = "Top 25%"
+ elif rating == "Yellow":
+ percentile = "Median"
+ else:
+ percentile = "Below median"
+ else:
+ percentile = "N/A"
+
+ return {
+ "rating": rating,
+ "label": label,
+ "percentile": percentile,
+ }
+
+
+def calculate_magic_number(net_new_arr: float, sm_spend: float) -> dict[str, Any]:
+ """Calculate Magic Number.
+
+ Formula: Net New ARR / Prior Period S&M Spend
+ Target: >0.75
+
+ Args:
+ net_new_arr: Net new annual recurring revenue in the period.
+ sm_spend: Sales & marketing spend in the prior period.
+
+ Returns:
+ Magic number value with rating and benchmark.
+ """
+ value = safe_divide(net_new_arr, sm_spend)
+ benchmark = rate_metric("magic_number", value)
+
+ return {
+ "value": round(value, 2),
+ "net_new_arr": net_new_arr,
+ "sm_spend": sm_spend,
+ "formula": "Net New ARR / Prior Period S&M Spend",
+ "target": ">0.75",
+ **benchmark,
+ }
+
+
+def calculate_ltv_cac(
+ arpa_monthly: float,
+ gross_margin_pct: float,
+ annual_churn_rate_pct: float,
+ cac: float,
+) -> dict[str, Any]:
+ """Calculate LTV:CAC Ratio.
+
+ LTV = ARPA_monthly x 12 x Gross Margin / Annual Churn Rate
+ Ratio = LTV / CAC
+ Target: >3:1
+
+ Args:
+ arpa_monthly: Average revenue per account per month.
+ gross_margin_pct: Gross margin as percentage (e.g., 78 for 78%).
+ annual_churn_rate_pct: Annual churn rate as percentage (e.g., 8 for 8%).
+ cac: Customer acquisition cost.
+
+ Returns:
+ LTV:CAC ratio with component values, rating, and benchmark.
+ """
+ gross_margin = gross_margin_pct / 100
+ churn_rate = annual_churn_rate_pct / 100
+
+ arpa_annual = arpa_monthly * 12
+ ltv = safe_divide(arpa_annual * gross_margin, churn_rate)
+ ratio = safe_divide(ltv, cac)
+
+ benchmark = rate_metric("ltv_cac_ratio", ratio)
+
+ return {
+ "ratio": round(ratio, 1),
+ "ltv": round(ltv, 2),
+ "cac": cac,
+ "arpa_monthly": arpa_monthly,
+ "arpa_annual": arpa_annual,
+ "gross_margin_pct": gross_margin_pct,
+ "annual_churn_rate_pct": annual_churn_rate_pct,
+ "formula": "LTV (ARPA x Gross Margin / Churn Rate) / CAC",
+ "target": ">3:1",
+ **benchmark,
+ }
+
+
+def calculate_cac_payback(
+ cac: float, arpa_monthly: float, gross_margin_pct: float
+) -> dict[str, Any]:
+ """Calculate CAC Payback Period.
+
+ Formula: CAC / (ARPA_monthly x Gross Margin) in months
+ Target: <18 months
+
+ Args:
+ cac: Customer acquisition cost.
+ arpa_monthly: Average revenue per account per month.
+ gross_margin_pct: Gross margin as percentage.
+
+ Returns:
+ CAC payback months with rating and benchmark.
+ """
+ gross_margin = gross_margin_pct / 100
+ monthly_contribution = arpa_monthly * gross_margin
+ payback_months = safe_divide(cac, monthly_contribution)
+
+ benchmark = rate_metric("cac_payback_months", payback_months)
+
+ return {
+ "months": round(payback_months, 1),
+ "cac": cac,
+ "arpa_monthly": arpa_monthly,
+ "gross_margin_pct": gross_margin_pct,
+ "monthly_contribution": round(monthly_contribution, 2),
+ "formula": "CAC / (ARPA_monthly x Gross Margin)",
+ "target": "<18 months",
+ **benchmark,
+ }
+
+
+def calculate_burn_multiple(net_burn: float, net_new_arr: float) -> dict[str, Any]:
+ """Calculate Burn Multiple.
+
+ Formula: Net Burn / Net New ARR
+ Target: <2x (lower is better)
+
+ Args:
+ net_burn: Net cash burn in the period.
+ net_new_arr: Net new ARR added in the period.
+
+ Returns:
+ Burn multiple with rating and benchmark.
+ """
+ value = safe_divide(net_burn, net_new_arr)
+ benchmark = rate_metric("burn_multiple", value)
+
+ return {
+ "value": round(value, 2),
+ "net_burn": net_burn,
+ "net_new_arr": net_new_arr,
+ "formula": "Net Burn / Net New ARR",
+ "target": "<2x",
+ **benchmark,
+ }
+
+
+def calculate_rule_of_40(
+ revenue_growth_pct: float, fcf_margin_pct: float
+) -> dict[str, Any]:
+ """Calculate Rule of 40.
+
+ Formula: Revenue Growth % + FCF Margin %
+ Target: >40%
+
+ Args:
+ revenue_growth_pct: Year-over-year revenue growth percentage.
+ fcf_margin_pct: Free cash flow margin percentage.
+
+ Returns:
+ Rule of 40 score with rating and benchmark.
+ """
+ value = revenue_growth_pct + fcf_margin_pct
+ benchmark = rate_metric("rule_of_40", value)
+
+ return {
+ "value": round(value, 1),
+ "revenue_growth_pct": revenue_growth_pct,
+ "fcf_margin_pct": fcf_margin_pct,
+ "formula": "Revenue Growth % + FCF Margin %",
+ "target": ">40%",
+ **benchmark,
+ }
+
+
+def calculate_ndr(
+ beginning_arr: float,
+ expansion_arr: float,
+ contraction_arr: float,
+ churned_arr: float,
+) -> dict[str, Any]:
+ """Calculate Net Dollar Retention.
+
+ Formula: (Beginning ARR + Expansion - Contraction - Churn) / Beginning ARR
+ Target: >110%
+
+ Args:
+ beginning_arr: ARR at start of period.
+ expansion_arr: Expansion revenue from existing customers.
+ contraction_arr: Revenue lost from downgrades.
+ churned_arr: Revenue lost from customer churn.
+
+ Returns:
+ NDR percentage with rating and benchmark.
+ """
+ ending_arr = beginning_arr + expansion_arr - contraction_arr - churned_arr
+ ndr_pct = safe_divide(ending_arr, beginning_arr) * 100
+
+ benchmark = rate_metric("ndr_pct", ndr_pct)
+
+ return {
+ "ndr_pct": round(ndr_pct, 1),
+ "beginning_arr": beginning_arr,
+ "expansion_arr": expansion_arr,
+ "contraction_arr": contraction_arr,
+ "churned_arr": churned_arr,
+ "ending_arr": round(ending_arr, 2),
+ "formula": "(Begin ARR + Expansion - Contraction - Churn) / Begin ARR",
+ "target": ">110%",
+ **benchmark,
+ }
+
+
+def generate_recommendations(metrics: dict) -> list[str]:
+ """Generate strategic recommendations based on GTM efficiency metrics.
+
+ Args:
+ metrics: Dict of all calculated metric results.
+
+ Returns:
+ List of recommendation strings.
+ """
+ recs = []
+
+ # Magic Number
+ mn = metrics["magic_number"]
+ if mn["rating"] == "Red":
+ recs.append(
+ f"Magic Number is {mn['value']} (target >0.75). GTM spend is inefficient. "
+ "Audit channel ROI, optimize sales productivity, and consider reducing "
+ "low-performing spend."
+ )
+ elif mn["rating"] == "Yellow":
+ recs.append(
+ f"Magic Number is {mn['value']}. GTM efficiency is acceptable but can improve. "
+ "Focus on sales enablement and pipeline quality over quantity."
+ )
+
+ # LTV:CAC
+ lc = metrics["ltv_cac"]
+ if lc["rating"] == "Red":
+ recs.append(
+ f"LTV:CAC ratio is {lc['ratio']}:1 (target >3:1). Unit economics are unsustainable. "
+ "Reduce CAC through better targeting, improve retention to increase LTV, "
+ "or increase ARPA through pricing optimization."
+ )
+ elif lc["rating"] == "Yellow":
+ recs.append(
+ f"LTV:CAC ratio is {lc['ratio']}:1. Unit economics are marginal. "
+ "Focus on reducing churn and expanding within existing accounts."
+ )
+
+ # CAC Payback
+ cp = metrics["cac_payback"]
+ if cp["rating"] == "Red":
+ recs.append(
+ f"CAC payback is {cp['months']} months (target <18). Capital recovery is too slow. "
+ "Reduce acquisition costs or increase gross-margin-weighted ARPA."
+ )
+
+ # Burn Multiple
+ bm = metrics["burn_multiple"]
+ if bm["rating"] == "Red":
+ recs.append(
+ f"Burn multiple is {bm['value']}x (target <2x). Cash consumption relative to "
+ "growth is unsustainable. Prioritize operating efficiency and path to profitability."
+ )
+
+ # Rule of 40
+ r40 = metrics["rule_of_40"]
+ if r40["rating"] == "Red":
+ recs.append(
+ f"Rule of 40 score is {r40['value']}% (target >40%). Balance of growth and "
+ "profitability needs improvement. Either accelerate growth or improve margins."
+ )
+
+ # NDR
+ ndr = metrics["ndr"]
+ if ndr["rating"] == "Red":
+ recs.append(
+ f"NDR is {ndr['ndr_pct']}% (target >110%). Net revenue is contracting from "
+ "the existing base. Prioritize churn reduction and expansion playbooks."
+ )
+ elif ndr["rating"] == "Yellow":
+ recs.append(
+ f"NDR is {ndr['ndr_pct']}%. Base is stable but not expanding. "
+ "Invest in cross-sell/upsell motions and customer success capacity."
+ )
+
+ # Positive summary if everything is green
+ green_count = sum(
+ 1 for m in metrics.values()
+ if isinstance(m, dict) and m.get("rating") == "Green"
+ )
+ total_metrics = 6
+ if green_count == total_metrics:
+ recs.append(
+ "All GTM efficiency metrics are in healthy ranges. Maintain current "
+ "trajectory and optimize for best-in-class performance."
+ )
+ elif green_count >= 4:
+ recs.append(
+ f"{green_count}/{total_metrics} metrics are green. GTM efficiency is generally "
+ "healthy. Address the yellow/red areas for continuous improvement."
+ )
+
+ return recs
+
+
+def calculate_all_metrics(data: dict) -> dict[str, Any]:
+ """Calculate all GTM efficiency metrics from input data.
+
+ Args:
+ data: Input data with revenue, costs, and customers sections.
+
+ Returns:
+ Complete GTM efficiency analysis results.
+ """
+ revenue = data["revenue"]
+ costs = data["costs"]
+ customers = data["customers"]
+
+ metrics = {
+ "magic_number": calculate_magic_number(
+ net_new_arr=revenue["net_new_arr"],
+ sm_spend=costs["sales_marketing_spend"],
+ ),
+ "ltv_cac": calculate_ltv_cac(
+ arpa_monthly=revenue["arpa_monthly"],
+ gross_margin_pct=costs["gross_margin_pct"],
+ annual_churn_rate_pct=customers["annual_churn_rate_pct"],
+ cac=costs["cac"],
+ ),
+ "cac_payback": calculate_cac_payback(
+ cac=costs["cac"],
+ arpa_monthly=revenue["arpa_monthly"],
+ gross_margin_pct=costs["gross_margin_pct"],
+ ),
+ "burn_multiple": calculate_burn_multiple(
+ net_burn=costs["net_burn"],
+ net_new_arr=revenue["net_new_arr"],
+ ),
+ "rule_of_40": calculate_rule_of_40(
+ revenue_growth_pct=revenue["revenue_growth_pct"],
+ fcf_margin_pct=costs["fcf_margin_pct"],
+ ),
+ "ndr": calculate_ndr(
+ beginning_arr=customers["beginning_arr"],
+ expansion_arr=customers["expansion_arr"],
+ contraction_arr=customers["contraction_arr"],
+ churned_arr=customers["churned_arr"],
+ ),
+ }
+
+ metrics["recommendations"] = generate_recommendations(metrics)
+
+ return metrics
+
+
+def format_currency(value: float) -> str:
+ """Format a number as currency."""
+ if abs(value) >= 1_000_000:
+ return f"${value / 1_000_000:,.1f}M"
+ elif abs(value) >= 1_000:
+ return f"${value / 1_000:,.1f}K"
+ return f"${value:,.0f}"
+
+
+def format_text_report(results: dict) -> str:
+ """Format analysis results as a human-readable text report."""
+ lines = []
+ lines.append("=" * 70)
+ lines.append("GTM EFFICIENCY REPORT")
+ lines.append("=" * 70)
+
+ # Metric summary table
+ metrics_order = [
+ ("magic_number", "Magic Number", lambda m: f"{m['value']}"),
+ ("ltv_cac", "LTV:CAC Ratio", lambda m: f"{m['ratio']}:1"),
+ ("cac_payback", "CAC Payback", lambda m: f"{m['months']} months"),
+ ("burn_multiple", "Burn Multiple", lambda m: f"{m['value']}x"),
+ ("rule_of_40", "Rule of 40", lambda m: f"{m['value']}%"),
+ ("ndr", "Net Dollar Retention", lambda m: f"{m['ndr_pct']}%"),
+ ]
+
+ lines.append("")
+ lines.append("METRICS SUMMARY")
+ lines.append("-" * 70)
+ lines.append(f" {'Metric':25s} {'Value':>12s} {'Rating':>8s} {'Target':>15s}")
+ lines.append(f" {'':25s} {'':>12s} {'':>8s} {'':>15s}")
+
+ for key, name, fmt_fn in metrics_order:
+ m = results[key]
+ lines.append(
+ f" {name:25s} {fmt_fn(m):>12s} {m['rating']:>8s} {m['target']:>15s}"
+ )
+
+ # Detailed breakdown
+ lines.append("")
+ lines.append("DETAILED BREAKDOWN")
+ lines.append("-" * 70)
+
+ # Magic Number
+ mn = results["magic_number"]
+ lines.append("")
+ lines.append(f" MAGIC NUMBER: {mn['value']}")
+ lines.append(f" Net New ARR: {format_currency(mn['net_new_arr'])}")
+ lines.append(f" S&M Spend: {format_currency(mn['sm_spend'])}")
+ lines.append(f" Rating: {mn['rating']} - {mn['label']}")
+ lines.append(f" Percentile: {mn['percentile']}")
+
+ # LTV:CAC
+ lc = results["ltv_cac"]
+ lines.append("")
+ lines.append(f" LTV:CAC RATIO: {lc['ratio']}:1")
+ lines.append(f" Customer LTV: {format_currency(lc['ltv'])}")
+ lines.append(f" CAC: {format_currency(lc['cac'])}")
+ lines.append(f" ARPA (Monthly): {format_currency(lc['arpa_monthly'])}")
+ lines.append(f" Gross Margin: {lc['gross_margin_pct']}%")
+ lines.append(f" Churn Rate: {lc['annual_churn_rate_pct']}%")
+ lines.append(f" Rating: {lc['rating']} - {lc['label']}")
+ lines.append(f" Percentile: {lc['percentile']}")
+
+ # CAC Payback
+ cp = results["cac_payback"]
+ lines.append("")
+ lines.append(f" CAC PAYBACK: {cp['months']} months")
+ lines.append(f" CAC: {format_currency(cp['cac'])}")
+ lines.append(f" Monthly Contribution:{format_currency(cp['monthly_contribution'])}")
+ lines.append(f" Rating: {cp['rating']} - {cp['label']}")
+ lines.append(f" Percentile: {cp['percentile']}")
+
+ # Burn Multiple
+ bm = results["burn_multiple"]
+ lines.append("")
+ lines.append(f" BURN MULTIPLE: {bm['value']}x")
+ lines.append(f" Net Burn: {format_currency(bm['net_burn'])}")
+ lines.append(f" Net New ARR: {format_currency(bm['net_new_arr'])}")
+ lines.append(f" Rating: {bm['rating']} - {bm['label']}")
+ lines.append(f" Percentile: {bm['percentile']}")
+
+ # Rule of 40
+ r40 = results["rule_of_40"]
+ lines.append("")
+ lines.append(f" RULE OF 40: {r40['value']}%")
+ lines.append(f" Revenue Growth: {r40['revenue_growth_pct']}%")
+ lines.append(f" FCF Margin: {r40['fcf_margin_pct']}%")
+ lines.append(f" Rating: {r40['rating']} - {r40['label']}")
+ lines.append(f" Percentile: {r40['percentile']}")
+
+ # NDR
+ ndr = results["ndr"]
+ lines.append("")
+ lines.append(f" NET DOLLAR RETENTION: {ndr['ndr_pct']}%")
+ lines.append(f" Beginning ARR: {format_currency(ndr['beginning_arr'])}")
+ lines.append(f" Expansion: +{format_currency(ndr['expansion_arr'])}")
+ lines.append(f" Contraction: -{format_currency(ndr['contraction_arr'])}")
+ lines.append(f" Churn: -{format_currency(ndr['churned_arr'])}")
+ lines.append(f" Ending ARR: {format_currency(ndr['ending_arr'])}")
+ lines.append(f" Rating: {ndr['rating']} - {ndr['label']}")
+ lines.append(f" Percentile: {ndr['percentile']}")
+
+ # Recommendations
+ lines.append("")
+ lines.append("RECOMMENDATIONS")
+ lines.append("-" * 70)
+ for i, rec in enumerate(results["recommendations"], 1):
+ lines.append(f" {i}. {rec}")
+
+ lines.append("")
+ lines.append("=" * 70)
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for GTM efficiency calculator CLI."""
+ parser = argparse.ArgumentParser(
+ description="Calculate GTM efficiency metrics for SaaS revenue teams."
+ )
+ parser.add_argument(
+ "input",
+ help="Path to JSON file containing GTM data",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ help="Output format: json or text (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ try:
+ with open(args.input, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ required_sections = ["revenue", "costs", "customers"]
+ for section in required_sections:
+ if section not in data:
+ print(
+ f"Error: Missing required section '{section}' in input data",
+ file=sys.stderr,
+ )
+ sys.exit(1)
+
+ results = calculate_all_metrics(data)
+
+ if args.format == "json":
+ print(json.dumps(results, indent=2))
+ else:
+ print(format_text_report(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/business-growth/revenue-operations/scripts/pipeline_analyzer.py b/skills/business-growth/revenue-operations/scripts/pipeline_analyzer.py
new file mode 100644
index 00000000..23a56d43
--- /dev/null
+++ b/skills/business-growth/revenue-operations/scripts/pipeline_analyzer.py
@@ -0,0 +1,496 @@
+#!/usr/bin/env python3
+"""Pipeline Analyzer - Analyzes sales pipeline health for SaaS revenue teams.
+
+Calculates pipeline coverage ratios, stage conversion rates, sales velocity,
+deal aging risks, and concentration risks from pipeline data.
+
+Usage:
+ python pipeline_analyzer.py --input pipeline.json --format text
+ python pipeline_analyzer.py --input pipeline.json --format json
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, date
+from typing import Any
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def parse_date(date_str: str) -> date:
+ """Parse a date string in YYYY-MM-DD format."""
+ return datetime.strptime(date_str, "%Y-%m-%d").date()
+
+
+def get_quarter(d: date) -> str:
+ """Return the quarter string for a given date (e.g., '2025-Q1')."""
+ quarter = (d.month - 1) // 3 + 1
+ return f"{d.year}-Q{quarter}"
+
+
+def calculate_coverage_ratio(deals: list[dict], quota: float) -> dict[str, Any]:
+ """Calculate pipeline coverage ratio against quota.
+
+ Target: 3-4x pipeline coverage for healthy pipeline.
+ """
+ total_pipeline = sum(d["value"] for d in deals if d["stage"] != "Closed Won")
+ ratio = safe_divide(total_pipeline, quota)
+
+ if ratio >= 4.0:
+ rating = "Strong"
+ elif ratio >= 3.0:
+ rating = "Healthy"
+ elif ratio >= 2.0:
+ rating = "At Risk"
+ else:
+ rating = "Critical"
+
+ return {
+ "total_pipeline_value": total_pipeline,
+ "quota": quota,
+ "coverage_ratio": round(ratio, 2),
+ "rating": rating,
+ "target": "3.0x - 4.0x",
+ }
+
+
+def calculate_stage_conversion_rates(
+ deals: list[dict], stages: list[str]
+) -> list[dict[str, Any]]:
+ """Calculate stage-to-stage conversion rates.
+
+ Measures the percentage of deals that progress from one stage to the next.
+ """
+ stage_order = {stage: i for i, stage in enumerate(stages)}
+ stage_counts: dict[str, int] = {stage: 0 for stage in stages}
+
+ for deal in deals:
+ stage = deal["stage"]
+ if stage in stage_order:
+ stage_idx = stage_order[stage]
+ # A deal at stage N has passed through all stages 0..N
+ for i in range(stage_idx + 1):
+ stage_counts[stages[i]] += 1
+
+ conversions = []
+ for i in range(len(stages) - 1):
+ from_stage = stages[i]
+ to_stage = stages[i + 1]
+ from_count = stage_counts[from_stage]
+ to_count = stage_counts[to_stage]
+ rate = safe_divide(to_count, from_count) * 100
+
+ conversions.append({
+ "from_stage": from_stage,
+ "to_stage": to_stage,
+ "from_count": from_count,
+ "to_count": to_count,
+ "conversion_rate_pct": round(rate, 1),
+ })
+
+ return conversions
+
+
+def calculate_sales_velocity(deals: list[dict]) -> dict[str, Any]:
+ """Calculate sales velocity.
+
+ Formula: (# opportunities x avg deal size x win rate) / avg sales cycle length
+ Result is revenue per day.
+ """
+ if not deals:
+ return {
+ "num_opportunities": 0,
+ "avg_deal_size": 0,
+ "win_rate_pct": 0,
+ "avg_cycle_days": 0,
+ "velocity_per_day": 0,
+ "velocity_per_month": 0,
+ }
+
+ won_deals = [d for d in deals if d["stage"] == "Closed Won"]
+ open_deals = [d for d in deals if d["stage"] != "Closed Won"]
+ all_considered = deals
+
+ num_opportunities = len(all_considered)
+ avg_deal_size = safe_divide(
+ sum(d["value"] for d in all_considered), num_opportunities
+ )
+ win_rate = safe_divide(len(won_deals), num_opportunities)
+ avg_cycle_days = safe_divide(
+ sum(d["age_days"] for d in all_considered), num_opportunities
+ )
+
+ velocity_per_day = safe_divide(
+ num_opportunities * avg_deal_size * win_rate, avg_cycle_days
+ )
+
+ return {
+ "num_opportunities": num_opportunities,
+ "avg_deal_size": round(avg_deal_size, 2),
+ "win_rate_pct": round(win_rate * 100, 1),
+ "avg_cycle_days": round(avg_cycle_days, 1),
+ "velocity_per_day": round(velocity_per_day, 2),
+ "velocity_per_month": round(velocity_per_day * 30, 2),
+ }
+
+
+def analyze_deal_aging(
+ deals: list[dict], average_cycle_days: int, stages: list[str]
+) -> dict[str, Any]:
+ """Analyze deal aging and flag stale deals.
+
+ Flags deals older than 2x the average cycle time.
+ Uses stage-specific thresholds based on position in the pipeline.
+ """
+ aging_threshold = average_cycle_days * 2
+ num_stages = len(stages)
+ stage_order = {stage: i for i, stage in enumerate(stages)}
+
+ # Stage-specific thresholds: early stages get more time, later stages less
+ stage_thresholds: dict[str, int] = {}
+ for i, stage in enumerate(stages):
+ if stage == "Closed Won":
+ continue
+ # Progressive thresholds: first stage gets full cycle, last open stage gets 50%
+ progress = safe_divide(i, num_stages - 1)
+ threshold = int(average_cycle_days * (1.0 + (1.0 - progress)))
+ stage_thresholds[stage] = threshold
+
+ aging_deals = []
+ healthy_deals = 0
+ at_risk_deals = 0
+
+ for deal in deals:
+ if deal["stage"] == "Closed Won":
+ continue
+
+ stage = deal["stage"]
+ age = deal["age_days"]
+ threshold = stage_thresholds.get(stage, aging_threshold)
+
+ if age > threshold:
+ at_risk_deals += 1
+ aging_deals.append({
+ "id": deal["id"],
+ "name": deal["name"],
+ "stage": stage,
+ "age_days": age,
+ "threshold_days": threshold,
+ "days_over": age - threshold,
+ "value": deal["value"],
+ })
+ else:
+ healthy_deals += 1
+
+ aging_deals.sort(key=lambda x: x["days_over"], reverse=True)
+
+ return {
+ "global_aging_threshold_days": aging_threshold,
+ "stage_thresholds": stage_thresholds,
+ "total_open_deals": healthy_deals + at_risk_deals,
+ "healthy_deals": healthy_deals,
+ "at_risk_deals": at_risk_deals,
+ "aging_deals": aging_deals,
+ }
+
+
+def assess_pipeline_risk(
+ deals: list[dict], quota: float, stages: list[str]
+) -> dict[str, Any]:
+ """Assess overall pipeline risk.
+
+ Checks for:
+ - Concentration risk (>40% in single deal)
+ - Stage distribution health
+ - Coverage gap by quarter
+ """
+ open_deals = [d for d in deals if d["stage"] != "Closed Won"]
+ total_pipeline = sum(d["value"] for d in open_deals)
+
+ # Concentration risk
+ concentration_risks = []
+ for deal in open_deals:
+ pct = safe_divide(deal["value"], total_pipeline) * 100
+ if pct > 40:
+ concentration_risks.append({
+ "id": deal["id"],
+ "name": deal["name"],
+ "value": deal["value"],
+ "pct_of_pipeline": round(pct, 1),
+ "risk_level": "HIGH",
+ })
+ elif pct > 25:
+ concentration_risks.append({
+ "id": deal["id"],
+ "name": deal["name"],
+ "value": deal["value"],
+ "pct_of_pipeline": round(pct, 1),
+ "risk_level": "MEDIUM",
+ })
+
+ has_concentration_risk = any(
+ r["risk_level"] == "HIGH" for r in concentration_risks
+ )
+
+ # Stage distribution
+ stage_distribution: dict[str, dict] = {}
+ for stage in stages:
+ if stage == "Closed Won":
+ continue
+ stage_deals = [d for d in open_deals if d["stage"] == stage]
+ count = len(stage_deals)
+ value = sum(d["value"] for d in stage_deals)
+ stage_distribution[stage] = {
+ "count": count,
+ "value": value,
+ "pct_of_pipeline": round(safe_divide(value, total_pipeline) * 100, 1),
+ }
+
+ # Check for empty stages (unhealthy funnel)
+ empty_stages = [
+ stage for stage, data in stage_distribution.items() if data["count"] == 0
+ ]
+
+ # Coverage gap by quarter
+ today = date.today()
+ quarterly_coverage: dict[str, float] = {}
+ for deal in open_deals:
+ try:
+ close_date = parse_date(deal["close_date"])
+ quarter = get_quarter(close_date)
+ quarterly_coverage[quarter] = (
+ quarterly_coverage.get(quarter, 0) + deal["value"]
+ )
+ except (ValueError, KeyError):
+ pass
+
+ quarterly_target = quota / 4
+ coverage_gaps = []
+ for quarter, value in sorted(quarterly_coverage.items()):
+ coverage = safe_divide(value, quarterly_target)
+ if coverage < 3.0:
+ coverage_gaps.append({
+ "quarter": quarter,
+ "pipeline_value": value,
+ "quarterly_target": quarterly_target,
+ "coverage_ratio": round(coverage, 2),
+ "gap": "Below 3x target",
+ })
+
+ # Overall risk rating
+ risk_factors = 0
+ if has_concentration_risk:
+ risk_factors += 2
+ if len(empty_stages) > 0:
+ risk_factors += 1
+ if len(coverage_gaps) > 0:
+ risk_factors += 1
+ if safe_divide(total_pipeline, quota) < 3.0:
+ risk_factors += 2
+
+ if risk_factors >= 4:
+ overall_risk = "HIGH"
+ elif risk_factors >= 2:
+ overall_risk = "MEDIUM"
+ else:
+ overall_risk = "LOW"
+
+ return {
+ "overall_risk": overall_risk,
+ "risk_factors_count": risk_factors,
+ "concentration_risks": concentration_risks,
+ "has_concentration_risk": has_concentration_risk,
+ "stage_distribution": stage_distribution,
+ "empty_stages": empty_stages,
+ "coverage_gaps": coverage_gaps,
+ }
+
+
+def analyze_pipeline(data: dict) -> dict[str, Any]:
+ """Run complete pipeline analysis.
+
+ Args:
+ data: Pipeline data with deals, quota, stages, and average_cycle_days.
+
+ Returns:
+ Complete analysis results dictionary.
+ """
+ deals = data["deals"]
+ quota = data["quota"]
+ stages = data["stages"]
+ average_cycle_days = data.get("average_cycle_days", 45)
+
+ return {
+ "coverage": calculate_coverage_ratio(deals, quota),
+ "stage_conversions": calculate_stage_conversion_rates(deals, stages),
+ "velocity": calculate_sales_velocity(deals),
+ "aging": analyze_deal_aging(deals, average_cycle_days, stages),
+ "risk": assess_pipeline_risk(deals, quota, stages),
+ }
+
+
+def format_currency(value: float) -> str:
+ """Format a number as currency."""
+ if value >= 1_000_000:
+ return f"${value / 1_000_000:,.1f}M"
+ elif value >= 1_000:
+ return f"${value / 1_000:,.1f}K"
+ return f"${value:,.0f}"
+
+
+def format_text_report(results: dict) -> str:
+ """Format analysis results as a human-readable text report."""
+ lines = []
+ lines.append("=" * 70)
+ lines.append("PIPELINE ANALYSIS REPORT")
+ lines.append("=" * 70)
+
+ # Coverage
+ cov = results["coverage"]
+ lines.append("")
+ lines.append("PIPELINE COVERAGE")
+ lines.append("-" * 40)
+ lines.append(f" Total Pipeline: {format_currency(cov['total_pipeline_value'])}")
+ lines.append(f" Quota Target: {format_currency(cov['quota'])}")
+ lines.append(f" Coverage Ratio: {cov['coverage_ratio']}x (Target: {cov['target']})")
+ lines.append(f" Rating: {cov['rating']}")
+
+ # Stage Conversions
+ lines.append("")
+ lines.append("STAGE CONVERSION RATES")
+ lines.append("-" * 40)
+ for conv in results["stage_conversions"]:
+ lines.append(
+ f" {conv['from_stage']} -> {conv['to_stage']}: "
+ f"{conv['conversion_rate_pct']}% "
+ f"({conv['to_count']}/{conv['from_count']})"
+ )
+
+ # Velocity
+ vel = results["velocity"]
+ lines.append("")
+ lines.append("SALES VELOCITY")
+ lines.append("-" * 40)
+ lines.append(f" Opportunities: {vel['num_opportunities']}")
+ lines.append(f" Avg Deal Size: {format_currency(vel['avg_deal_size'])}")
+ lines.append(f" Win Rate: {vel['win_rate_pct']}%")
+ lines.append(f" Avg Cycle: {vel['avg_cycle_days']} days")
+ lines.append(f" Velocity/Day: {format_currency(vel['velocity_per_day'])}")
+ lines.append(f" Velocity/Month: {format_currency(vel['velocity_per_month'])}")
+
+ # Aging
+ aging = results["aging"]
+ lines.append("")
+ lines.append("DEAL AGING ANALYSIS")
+ lines.append("-" * 40)
+ lines.append(f" Total Open Deals: {aging['total_open_deals']}")
+ lines.append(f" Healthy: {aging['healthy_deals']}")
+ lines.append(f" At Risk: {aging['at_risk_deals']}")
+ if aging["aging_deals"]:
+ lines.append("")
+ lines.append(" AGING DEALS (needs attention):")
+ for deal in aging["aging_deals"]:
+ lines.append(
+ f" - {deal['name']} ({deal['stage']}): "
+ f"{deal['age_days']}d (threshold: {deal['threshold_days']}d, "
+ f"+{deal['days_over']}d over) | {format_currency(deal['value'])}"
+ )
+
+ # Risk
+ risk = results["risk"]
+ lines.append("")
+ lines.append("PIPELINE RISK ASSESSMENT")
+ lines.append("-" * 40)
+ lines.append(f" Overall Risk: {risk['overall_risk']}")
+ lines.append(f" Risk Factors: {risk['risk_factors_count']}")
+
+ if risk["concentration_risks"]:
+ lines.append("")
+ lines.append(" CONCENTRATION RISKS:")
+ for cr in risk["concentration_risks"]:
+ lines.append(
+ f" - {cr['name']}: {format_currency(cr['value'])} "
+ f"({cr['pct_of_pipeline']}% of pipeline) [{cr['risk_level']}]"
+ )
+
+ if risk["empty_stages"]:
+ lines.append("")
+ lines.append(f" EMPTY STAGES: {', '.join(risk['empty_stages'])}")
+
+ lines.append("")
+ lines.append(" STAGE DISTRIBUTION:")
+ for stage, data in risk["stage_distribution"].items():
+ bar = "#" * max(1, int(data["pct_of_pipeline"] / 2))
+ lines.append(
+ f" {stage:20s} {data['count']:3d} deals "
+ f"{format_currency(data['value']):>10s} "
+ f"{data['pct_of_pipeline']:5.1f}% {bar}"
+ )
+
+ if risk["coverage_gaps"]:
+ lines.append("")
+ lines.append(" COVERAGE GAPS BY QUARTER:")
+ for gap in risk["coverage_gaps"]:
+ lines.append(
+ f" - {gap['quarter']}: {gap['coverage_ratio']}x coverage "
+ f"({format_currency(gap['pipeline_value'])} vs "
+ f"{format_currency(gap['quarterly_target'])} target)"
+ )
+
+ lines.append("")
+ lines.append("=" * 70)
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for pipeline analyzer CLI."""
+ parser = argparse.ArgumentParser(
+ description="Analyze sales pipeline health for SaaS revenue teams."
+ )
+ parser.add_argument(
+ "--input",
+ required=True,
+ help="Path to JSON file containing pipeline data",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ help="Output format: json or text (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ try:
+ with open(args.input, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ # Validate required fields
+ required_fields = ["deals", "quota", "stages"]
+ for field in required_fields:
+ if field not in data:
+ print(f"Error: Missing required field '{field}' in input data", file=sys.stderr)
+ sys.exit(1)
+
+ results = analyze_pipeline(data)
+
+ if args.format == "json":
+ print(json.dumps(results, indent=2))
+ else:
+ print(format_text_report(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/business-growth/sales-engineer/SKILL.md b/skills/business-growth/sales-engineer/SKILL.md
new file mode 100644
index 00000000..dc1e5fad
--- /dev/null
+++ b/skills/business-growth/sales-engineer/SKILL.md
@@ -0,0 +1,225 @@
+---
+name: "sales-engineer"
+description: 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
diff --git a/skills/business-growth/sales-engineer/assets/demo_script_template.md b/skills/business-growth/sales-engineer/assets/demo_script_template.md
new file mode 100644
index 00000000..c402fe82
--- /dev/null
+++ b/skills/business-growth/sales-engineer/assets/demo_script_template.md
@@ -0,0 +1,232 @@
+# Demo Script Template
+
+## Demo Information
+
+| Field | Value |
+|-------|-------|
+| Customer | [Customer Name] |
+| Date/Time | [Date and Time] |
+| Duration | [XX minutes] |
+| Demo Environment | [Environment URL/Details] |
+| Presenter | [Sales Engineer Name] |
+| AE/Account Executive | [AE Name] |
+
+---
+
+## Pre-Demo Checklist
+
+- [ ] Demo environment tested and confirmed working
+- [ ] Sample data loaded and validated
+- [ ] Backup demo environment prepared
+- [ ] Screen sharing tested with correct resolution
+- [ ] Browser tabs pre-loaded with key screens
+- [ ] Recording setup confirmed (if applicable)
+- [ ] Customer-specific branding applied (if applicable)
+- [ ] Network and VPN connectivity verified
+- [ ] All integrations connected and tested
+- [ ] Backup slides prepared in case of technical issues
+
+---
+
+## Attendees and Roles
+
+| Name | Title | Role in Evaluation | Key Interest |
+|------|-------|-------------------|--------------|
+| [Name] | [CTO/VP Eng] | Decision Maker | ROI, strategic fit |
+| [Name] | [Director] | Champion | Solving [specific problem] |
+| [Name] | [Manager] | Technical Evaluator | Architecture, integrations |
+| [Name] | [Analyst] | End User | Day-to-day usability |
+
+---
+
+## Agenda
+
+| Time | Duration | Topic | Lead |
+|------|----------|-------|------|
+| 0:00 | 5 min | Welcome and introductions | AE |
+| 0:05 | 5 min | Agenda and objectives | SE |
+| 0:10 | 20 min | Core demo (Use Cases 1-3) | SE |
+| 0:30 | 10 min | Integration demo | SE |
+| 0:40 | 5 min | Admin and security overview | SE |
+| 0:45 | 10 min | Q&A | SE + AE |
+| 0:55 | 5 min | Next steps and wrap-up | AE |
+
+---
+
+## Demo Flow
+
+### Opening (5 minutes)
+
+**Talking Points:**
+- Thank attendees for their time
+- Recap what we learned in discovery: "[Summarize 2-3 key challenges]"
+- Set expectations: "Today I'll show you how we address [Challenge 1], [Challenge 2], and [Challenge 3]"
+- Frame the demo: "I'll be using [data type] similar to what you described in our earlier conversations"
+
+**Transition:** "Let me start with the challenge you mentioned is most pressing: [Challenge 1]."
+
+---
+
+### Use Case 1: [Name] (7 minutes)
+
+**Business Context:**
+[1-2 sentences on why this matters to the customer]
+
+**Demo Steps:**
+
+1. **Step 1:** [Navigate to / Click on / Show...]
+ - **What to say:** "[Explain what they're seeing and why it matters]"
+ - **Highlight:** [Specific feature or capability to emphasize]
+
+2. **Step 2:** [Navigate to / Click on / Show...]
+ - **What to say:** "[Connect this to their specific pain point]"
+ - **Highlight:** [Differentiator from competitor]
+
+3. **Step 3:** [Navigate to / Click on / Show...]
+ - **What to say:** "[Quantify the value - time saved, errors reduced, etc.]"
+ - **Highlight:** [Ease of use or power of the feature]
+
+**Key Message:** "[One sentence summarizing the value demonstrated]"
+
+**Transition:** "Now that you've seen how we handle [Use Case 1], let me show you [Use Case 2]."
+
+---
+
+### Use Case 2: [Name] (7 minutes)
+
+**Business Context:**
+[1-2 sentences on why this matters to the customer]
+
+**Demo Steps:**
+
+1. **Step 1:** [Navigate to / Click on / Show...]
+ - **What to say:** "[Explanation]"
+ - **Highlight:** [Key capability]
+
+2. **Step 2:** [Navigate to / Click on / Show...]
+ - **What to say:** "[Explanation]"
+ - **Highlight:** [Key capability]
+
+3. **Step 3:** [Navigate to / Click on / Show...]
+ - **What to say:** "[Explanation]"
+ - **Highlight:** [Key capability]
+
+**Key Message:** "[One sentence summarizing the value demonstrated]"
+
+**Transition:** "[Transition statement to next section]"
+
+---
+
+### Use Case 3: [Name] (6 minutes)
+
+**Business Context:**
+[1-2 sentences on why this matters to the customer]
+
+**Demo Steps:**
+
+1. **Step 1:** [Description]
+ - **What to say:** "[Explanation]"
+ - **Highlight:** [Key capability]
+
+2. **Step 2:** [Description]
+ - **What to say:** "[Explanation]"
+ - **Highlight:** [Key capability]
+
+**Key Message:** "[One sentence summarizing the value demonstrated]"
+
+---
+
+### Integration Demo (10 minutes)
+
+**Context:** "You mentioned that integration with [System X] and [System Y] is critical. Let me show you how that works."
+
+**Demo Steps:**
+
+1. **Show integration configuration:**
+ - **What to say:** "Setting up the connection takes [X minutes/clicks]"
+ - **Highlight:** Native connector, no custom code required
+
+2. **Show data flow:**
+ - **What to say:** "Data syncs in [real-time/X minute intervals]"
+ - **Highlight:** Reliability, error handling, monitoring
+
+3. **Show end-to-end workflow:**
+ - **What to say:** "Here's the complete flow from [source] to [destination]"
+ - **Highlight:** Automation, reduced manual effort
+
+---
+
+### Admin and Security (5 minutes)
+
+**Demo Steps:**
+
+1. **Show RBAC configuration:**
+ - **What to say:** "Administrators can define roles and permissions at [granularity level]"
+
+2. **Show audit log:**
+ - **What to say:** "Every action is logged for compliance and security review"
+
+3. **Show SSO setup:**
+ - **What to say:** "Single sign-on integrates with your existing identity provider"
+
+---
+
+## Objection Handling
+
+### Anticipated Objections
+
+| Objection | Response |
+|-----------|----------|
+| "[Feature X] looks limited compared to [Competitor]" | "Great observation. Our approach to [Feature X] focuses on [benefit]. What specific aspect of [Feature X] is most important to your workflow? [Then demonstrate or explain how we address the specific need]" |
+| "How does this handle [edge case]?" | "That's an important scenario. [If supported: Let me show you how that works.] [If not directly: Here's how our customers typically handle that use case...]" |
+| "What about performance at our scale?" | "Excellent question. Our platform handles [benchmark data]. For your specific scale of [X], we'd recommend [architecture approach]. We can validate this in a POC." |
+| "The implementation timeline seems long" | "The timeline I shared is for the full solution. We can phase the rollout to deliver value sooner. Phase 1 would give you [core capability] within [X weeks]." |
+| "What happens if we outgrow this?" | "Our architecture is designed for growth. [Describe scaling approach]. We have customers who have scaled from [X] to [Y] without re-architecture." |
+
+### Recovery Strategies
+
+**If the demo breaks:**
+1. Stay calm: "Let me switch to [backup environment / backup approach]"
+2. Explain what they would have seen
+3. Offer to follow up with a recorded walkthrough
+4. Pivot to the next demo section
+
+**If an unexpected question derails the flow:**
+1. Acknowledge: "That's an excellent question"
+2. Briefly answer or note it for follow-up
+3. Return to the demo flow: "Let me continue with [next section] and we can dive deeper into that during Q&A"
+
+**If the audience seems disengaged:**
+1. Pause and ask: "Before I continue, is this addressing what you're looking for?"
+2. Adjust focus based on their response
+3. Skip ahead to the section most relevant to their interests
+
+---
+
+## Post-Demo Actions
+
+- [ ] Send thank-you email with recording link (if recorded)
+- [ ] Share demo environment access credentials (if applicable)
+- [ ] Send follow-up document addressing unanswered questions
+- [ ] Schedule next meeting (POC kickoff, technical deep-dive, etc.)
+- [ ] Update CRM with demo notes and next steps
+- [ ] Debrief with AE on stakeholder reactions and concerns
+- [ ] Log key objections and responses for battlecard updates
+
+---
+
+## Notes
+
+[Space for real-time notes during the demo]
+
+### Questions Raised
+1. [Question] - [Answer / Follow-up needed]
+2. [Question] - [Answer / Follow-up needed]
+
+### Feedback Received
+- [Positive feedback]
+- [Concerns raised]
+
+### Next Steps Agreed
+1. [Action item] - [Owner] - [Date]
+2. [Action item] - [Owner] - [Date]
diff --git a/skills/business-growth/sales-engineer/assets/expected_output.json b/skills/business-growth/sales-engineer/assets/expected_output.json
new file mode 100644
index 00000000..b8387022
--- /dev/null
+++ b/skills/business-growth/sales-engineer/assets/expected_output.json
@@ -0,0 +1,474 @@
+{
+ "rfp_info": {
+ "rfp_name": "Enterprise Data Analytics Platform RFP",
+ "customer": "Acme Financial Services",
+ "due_date": "2026-03-15",
+ "strategic_value": "high",
+ "deal_value": "$450,000 ARR"
+ },
+ "coverage_summary": {
+ "overall_coverage_percentage": 84.5,
+ "total_requirements": 21,
+ "full": 14,
+ "partial": 3,
+ "planned": 2,
+ "gap": 2,
+ "must_have_gaps": 0
+ },
+ "category_scores": {
+ "Data Integration": {
+ "coverage_percentage": 90.0,
+ "requirements_count": 4,
+ "full": 3,
+ "partial": 1,
+ "planned": 0,
+ "gap": 0,
+ "effort_hours": 34
+ },
+ "Analytics & Visualization": {
+ "coverage_percentage": 77.8,
+ "requirements_count": 4,
+ "full": 2,
+ "partial": 1,
+ "planned": 1,
+ "gap": 0,
+ "effort_hours": 56
+ },
+ "Security & Compliance": {
+ "coverage_percentage": 81.8,
+ "requirements_count": 4,
+ "full": 3,
+ "partial": 0,
+ "planned": 0,
+ "gap": 1,
+ "effort_hours": 50
+ },
+ "Performance & Scalability": {
+ "coverage_percentage": 87.5,
+ "requirements_count": 3,
+ "full": 2,
+ "partial": 1,
+ "planned": 0,
+ "gap": 0,
+ "effort_hours": 32
+ },
+ "API & Extensibility": {
+ "coverage_percentage": 87.5,
+ "requirements_count": 3,
+ "full": 2,
+ "partial": 0,
+ "planned": 1,
+ "gap": 0,
+ "effort_hours": 38
+ },
+ "Support & SLA": {
+ "coverage_percentage": 100.0,
+ "requirements_count": 2,
+ "full": 2,
+ "partial": 0,
+ "planned": 0,
+ "gap": 0,
+ "effort_hours": 4
+ },
+ "Deployment": {
+ "coverage_percentage": 0.0,
+ "requirements_count": 1,
+ "full": 0,
+ "partial": 0,
+ "planned": 0,
+ "gap": 1,
+ "effort_hours": 80
+ }
+ },
+ "bid_recommendation": {
+ "decision": "BID",
+ "confidence": "high",
+ "overall_coverage_percentage": 84.5,
+ "must_have_gaps": 0,
+ "strategic_value": "high",
+ "reasons": [
+ "Coverage score 84.5% exceeds 70% threshold"
+ ]
+ },
+ "gap_analysis": [
+ {
+ "id": "R-004",
+ "requirement": "Change data capture (CDC) for real-time sync",
+ "category": "Data Integration",
+ "priority": "should-have",
+ "coverage_status": "partial",
+ "severity": "high",
+ "effort_hours": 16,
+ "mitigation": "Document supported CDC sources; provide configuration guide for non-standard sources"
+ },
+ {
+ "id": "R-007",
+ "requirement": "Natural language query interface for business users",
+ "category": "Analytics & Visualization",
+ "priority": "should-have",
+ "coverage_status": "planned",
+ "severity": "high",
+ "effort_hours": 24,
+ "mitigation": "Share roadmap timeline; offer guided query builder as interim solution"
+ },
+ {
+ "id": "R-012",
+ "requirement": "HIPAA compliance for healthcare data handling",
+ "category": "Security & Compliance",
+ "priority": "should-have",
+ "coverage_status": "gap",
+ "severity": "high",
+ "effort_hours": 40,
+ "mitigation": "Evaluate HIPAA certification timeline with compliance team; consider data masking as interim"
+ },
+ {
+ "id": "R-015",
+ "requirement": "Multi-region deployment with data residency controls",
+ "category": "Performance & Scalability",
+ "priority": "should-have",
+ "coverage_status": "partial",
+ "severity": "high",
+ "effort_hours": 20,
+ "mitigation": "Confirm customer region requirements; provide APAC beta access if needed"
+ },
+ {
+ "id": "R-008",
+ "requirement": "Predictive analytics and ML model integration",
+ "category": "Analytics & Visualization",
+ "priority": "nice-to-have",
+ "coverage_status": "partial",
+ "severity": "low",
+ "effort_hours": 20,
+ "mitigation": "Demonstrate Python integration for custom models; provide example notebooks"
+ },
+ {
+ "id": "R-018",
+ "requirement": "Custom plugin/extension framework",
+ "category": "API & Extensibility",
+ "priority": "nice-to-have",
+ "coverage_status": "planned",
+ "severity": "low",
+ "effort_hours": 30,
+ "mitigation": "Current API extensibility covers most use cases; plugin framework will expand options"
+ },
+ {
+ "id": "R-021",
+ "requirement": "On-premise deployment option",
+ "category": "Deployment",
+ "priority": "nice-to-have",
+ "coverage_status": "gap",
+ "severity": "low",
+ "effort_hours": 80,
+ "mitigation": "Position cloud-first architecture benefits; offer VPC deployment as alternative"
+ }
+ ],
+ "risk_assessment": [
+ {
+ "risk": "High customization effort",
+ "impact": "high",
+ "description": "230 hours estimated for non-full requirements",
+ "mitigation": "Evaluate resource availability and timeline feasibility before committing"
+ }
+ ],
+ "effort_estimate": {
+ "total_hours": 294,
+ "gap_closure_hours": 230,
+ "full_coverage_hours": 64
+ },
+ "requirements_detail": [
+ {
+ "id": "R-001",
+ "requirement": "Real-time data ingestion from multiple sources (APIs, databases, streaming)",
+ "category": "Data Integration",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 8,
+ "notes": "Native connectors for 200+ data sources",
+ "mitigation": ""
+ },
+ {
+ "id": "R-002",
+ "requirement": "Support for SQL and NoSQL data sources",
+ "category": "Data Integration",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 4,
+ "notes": "Supports PostgreSQL, MySQL, MongoDB, Cassandra, and more",
+ "mitigation": ""
+ },
+ {
+ "id": "R-003",
+ "requirement": "Automated ETL pipeline creation with visual designer",
+ "category": "Data Integration",
+ "priority": "should-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 2.0,
+ "weighted_score": 2.0,
+ "max_weighted": 2.0,
+ "effort_hours": 6,
+ "notes": "Drag-and-drop pipeline builder included",
+ "mitigation": ""
+ },
+ {
+ "id": "R-004",
+ "requirement": "Change data capture (CDC) for real-time sync",
+ "category": "Data Integration",
+ "priority": "should-have",
+ "coverage_status": "partial",
+ "coverage_score": 0.5,
+ "weight": 2.0,
+ "weighted_score": 1.0,
+ "max_weighted": 2.0,
+ "effort_hours": 16,
+ "notes": "CDC supported for major databases; some require custom configuration",
+ "mitigation": "Document supported CDC sources; provide configuration guide for non-standard sources"
+ },
+ {
+ "id": "R-005",
+ "requirement": "Interactive dashboard creation with drag-and-drop",
+ "category": "Analytics & Visualization",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 4,
+ "notes": "Full drag-and-drop dashboard builder with 50+ chart types",
+ "mitigation": ""
+ },
+ {
+ "id": "R-006",
+ "requirement": "Embedded analytics with white-labeling support",
+ "category": "Analytics & Visualization",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 8,
+ "notes": "Full embedding SDK with CSS customization",
+ "mitigation": ""
+ },
+ {
+ "id": "R-007",
+ "requirement": "Natural language query interface for business users",
+ "category": "Analytics & Visualization",
+ "priority": "should-have",
+ "coverage_status": "planned",
+ "coverage_score": 0.25,
+ "weight": 2.0,
+ "weighted_score": 0.5,
+ "max_weighted": 2.0,
+ "effort_hours": 24,
+ "notes": "NLQ feature on roadmap for Q3 2026",
+ "mitigation": "Share roadmap timeline; offer guided query builder as interim solution"
+ },
+ {
+ "id": "R-008",
+ "requirement": "Predictive analytics and ML model integration",
+ "category": "Analytics & Visualization",
+ "priority": "nice-to-have",
+ "coverage_status": "partial",
+ "coverage_score": 0.5,
+ "weight": 1.0,
+ "weighted_score": 0.5,
+ "max_weighted": 1.0,
+ "effort_hours": 20,
+ "notes": "Python/R integration available; no built-in ML models",
+ "mitigation": "Demonstrate Python integration for custom models; provide example notebooks"
+ },
+ {
+ "id": "R-009",
+ "requirement": "Role-based access control (RBAC) with row-level security",
+ "category": "Security & Compliance",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 6,
+ "notes": "Granular RBAC with row-level and column-level security",
+ "mitigation": ""
+ },
+ {
+ "id": "R-010",
+ "requirement": "SOC 2 Type II certification",
+ "category": "Security & Compliance",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 2,
+ "notes": "Current SOC 2 Type II report available upon NDA",
+ "mitigation": ""
+ },
+ {
+ "id": "R-011",
+ "requirement": "Data encryption at rest and in transit (AES-256, TLS 1.3)",
+ "category": "Security & Compliance",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 2,
+ "notes": "AES-256 at rest, TLS 1.3 in transit, customer-managed keys supported",
+ "mitigation": ""
+ },
+ {
+ "id": "R-012",
+ "requirement": "HIPAA compliance for healthcare data handling",
+ "category": "Security & Compliance",
+ "priority": "should-have",
+ "coverage_status": "gap",
+ "coverage_score": 0.0,
+ "weight": 2.0,
+ "weighted_score": 0.0,
+ "max_weighted": 2.0,
+ "effort_hours": 40,
+ "notes": "HIPAA BAA not currently offered",
+ "mitigation": "Evaluate HIPAA certification timeline with compliance team; consider data masking as interim"
+ },
+ {
+ "id": "R-013",
+ "requirement": "Horizontal scaling to handle 10B+ rows",
+ "category": "Performance & Scalability",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 8,
+ "notes": "Distributed query engine scales to 50B+ rows",
+ "mitigation": ""
+ },
+ {
+ "id": "R-014",
+ "requirement": "Sub-second query response for cached dashboards",
+ "category": "Performance & Scalability",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 4,
+ "notes": "Intelligent caching layer with <500ms p95 for cached queries",
+ "mitigation": ""
+ },
+ {
+ "id": "R-015",
+ "requirement": "Multi-region deployment with data residency controls",
+ "category": "Performance & Scalability",
+ "priority": "should-have",
+ "coverage_status": "partial",
+ "coverage_score": 0.5,
+ "weight": 2.0,
+ "weighted_score": 1.0,
+ "max_weighted": 2.0,
+ "effort_hours": 20,
+ "notes": "US and EU regions available; APAC region in beta",
+ "mitigation": "Confirm customer region requirements; provide APAC beta access if needed"
+ },
+ {
+ "id": "R-016",
+ "requirement": "RESTful API with comprehensive documentation",
+ "category": "API & Extensibility",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 4,
+ "notes": "Full REST API with OpenAPI spec and interactive documentation",
+ "mitigation": ""
+ },
+ {
+ "id": "R-017",
+ "requirement": "Webhook support for event-driven workflows",
+ "category": "API & Extensibility",
+ "priority": "should-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 2.0,
+ "weighted_score": 2.0,
+ "max_weighted": 2.0,
+ "effort_hours": 4,
+ "notes": "Webhook support for 30+ event types",
+ "mitigation": ""
+ },
+ {
+ "id": "R-018",
+ "requirement": "Custom plugin/extension framework",
+ "category": "API & Extensibility",
+ "priority": "nice-to-have",
+ "coverage_status": "planned",
+ "coverage_score": 0.25,
+ "weight": 1.0,
+ "weighted_score": 0.25,
+ "max_weighted": 1.0,
+ "effort_hours": 30,
+ "notes": "Plugin framework on roadmap for Q4 2026",
+ "mitigation": "Current API extensibility covers most use cases; plugin framework will expand options"
+ },
+ {
+ "id": "R-019",
+ "requirement": "24/7 enterprise support with 1-hour critical response time",
+ "category": "Support & SLA",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 3.0,
+ "weighted_score": 3.0,
+ "max_weighted": 3.0,
+ "effort_hours": 2,
+ "notes": "Premium support tier includes 24/7 coverage with 30-min critical response SLA",
+ "mitigation": ""
+ },
+ {
+ "id": "R-020",
+ "requirement": "Dedicated customer success manager",
+ "category": "Support & SLA",
+ "priority": "should-have",
+ "coverage_status": "full",
+ "coverage_score": 1.0,
+ "weight": 2.0,
+ "weighted_score": 2.0,
+ "max_weighted": 2.0,
+ "effort_hours": 2,
+ "notes": "Included in Enterprise tier",
+ "mitigation": ""
+ },
+ {
+ "id": "R-021",
+ "requirement": "On-premise deployment option",
+ "category": "Deployment",
+ "priority": "nice-to-have",
+ "coverage_status": "gap",
+ "coverage_score": 0.0,
+ "weight": 1.0,
+ "weighted_score": 0.0,
+ "max_weighted": 1.0,
+ "effort_hours": 80,
+ "notes": "Cloud-only platform; no on-premise offering",
+ "mitigation": "Position cloud-first architecture benefits; offer VPC deployment as alternative"
+ }
+ ]
+}
diff --git a/skills/business-growth/sales-engineer/assets/poc_scorecard_template.md b/skills/business-growth/sales-engineer/assets/poc_scorecard_template.md
new file mode 100644
index 00000000..dbc224ad
--- /dev/null
+++ b/skills/business-growth/sales-engineer/assets/poc_scorecard_template.md
@@ -0,0 +1,213 @@
+# POC Evaluation Scorecard
+
+## Scorecard Information
+
+| Field | Value |
+|-------|-------|
+| POC Name | [POC Name] |
+| Customer | [Customer Name] |
+| Vendor/Product | [Product Name] |
+| Evaluation Period | [Start Date] - [End Date] |
+| Evaluated By | [Names and Roles] |
+| Date Completed | [Date] |
+
+---
+
+## Scoring Scale
+
+| Score | Label | Definition |
+|-------|-------|------------|
+| 5 | Exceeds | Superior capability; exceeds requirements with notable strengths |
+| 4 | Meets | Full capability; meets all requirements with no significant gaps |
+| 3 | Partial | Acceptable capability; minor gaps that can be addressed |
+| 2 | Below | Below expectations; significant gaps that impact value |
+| 1 | Fails | Does not meet requirements; critical gaps |
+| N/A | Not Evaluated | Not tested during this POC |
+
+---
+
+## Evaluation Categories
+
+### 1. Functionality (Weight: 30%)
+
+| Criterion | Score (1-5) | Evidence / Notes |
+|-----------|-------------|-----------------|
+| Core feature completeness | | |
+| Use case coverage | | |
+| Customization flexibility | | |
+| Workflow automation | | |
+| Data handling and transformation | | |
+| Reporting and analytics | | |
+
+**Category Score:** ___/5.0
+**Category Notes:**
+[Summary of functionality evaluation, key strengths and gaps]
+
+---
+
+### 2. Performance (Weight: 20%)
+
+| Criterion | Score (1-5) | Evidence / Notes |
+|-----------|-------------|-----------------|
+| Response time under expected load | | |
+| Response time under peak load | | |
+| Throughput capacity | | |
+| Scalability characteristics | | |
+| Resource utilization | | |
+| Batch processing performance | | |
+
+**Category Score:** ___/5.0
+**Category Notes:**
+[Summary of performance evaluation, benchmark results]
+
+---
+
+### 3. Integration (Weight: 20%)
+
+| Criterion | Score (1-5) | Evidence / Notes |
+|-----------|-------------|-----------------|
+| API completeness and documentation | | |
+| Data migration ease | | |
+| Third-party connector availability | | |
+| Authentication/SSO integration | | |
+| Real-time sync reliability | | |
+| Error handling and recovery | | |
+
+**Category Score:** ___/5.0
+**Category Notes:**
+[Summary of integration evaluation, systems tested]
+
+---
+
+### 4. Usability (Weight: 15%)
+
+| Criterion | Score (1-5) | Evidence / Notes |
+|-----------|-------------|-----------------|
+| User interface intuitiveness | | |
+| Learning curve assessment | | |
+| Documentation quality | | |
+| Admin console functionality | | |
+| Mobile experience | | |
+| Accessibility compliance | | |
+
+**Category Score:** ___/5.0
+**Category Notes:**
+[Summary of usability evaluation, user feedback]
+
+---
+
+### 5. Support (Weight: 15%)
+
+| Criterion | Score (1-5) | Evidence / Notes |
+|-----------|-------------|-----------------|
+| Technical support responsiveness | | |
+| Knowledge base quality | | |
+| Training resources availability | | |
+| Community and ecosystem | | |
+| Issue resolution speed | | |
+| Proactive engagement quality | | |
+
+**Category Score:** ___/5.0
+**Category Notes:**
+[Summary of support evaluation during POC]
+
+---
+
+## Score Summary
+
+| Category | Weight | Score | Weighted Score |
+|----------|--------|-------|----------------|
+| Functionality | 30% | ___/5.0 | ___ |
+| Performance | 20% | ___/5.0 | ___ |
+| Integration | 20% | ___/5.0 | ___ |
+| Usability | 15% | ___/5.0 | ___ |
+| Support | 15% | ___/5.0 | ___ |
+| **Overall** | **100%** | | **___/5.0** |
+
+### Decision Thresholds
+
+| Weighted Average | Decision |
+|-----------------|----------|
+| >= 4.0 | **Strong Pass** - Proceed to procurement |
+| 3.5 - 3.9 | **Pass** - Proceed with noted conditions |
+| 3.0 - 3.4 | **Conditional** - Requires further evaluation |
+| < 3.0 | **Fail** - Does not meet requirements |
+
+---
+
+## Success Criteria Results
+
+| # | Criterion | Priority | Target | Actual | Pass/Fail |
+|---|-----------|----------|--------|--------|-----------|
+| 1 | [Criterion 1] | Must-Have | [Target] | [Result] | [ ] |
+| 2 | [Criterion 2] | Must-Have | [Target] | [Result] | [ ] |
+| 3 | [Criterion 3] | Must-Have | [Target] | [Result] | [ ] |
+| 4 | [Criterion 4] | Should-Have | [Target] | [Result] | [ ] |
+| 5 | [Criterion 5] | Should-Have | [Target] | [Result] | [ ] |
+| 6 | [Criterion 6] | Nice-to-Have | [Target] | [Result] | [ ] |
+
+**Must-Have Pass Rate:** ___/%
+**Overall Pass Rate:** ___/%
+
+---
+
+## Issues Log
+
+| # | Issue | Severity | Status | Resolution | Impact on Score |
+|---|-------|----------|--------|------------|----------------|
+| 1 | [Issue] | [Critical/High/Medium/Low] | [Open/Resolved] | [Resolution] | [Category affected] |
+| 2 | [Issue] | [Critical/High/Medium/Low] | [Open/Resolved] | [Resolution] | [Category affected] |
+
+---
+
+## Stakeholder Feedback
+
+### [Stakeholder Name 1] - [Role]
+**Rating:** ___/5
+**Comments:** [Feedback]
+
+### [Stakeholder Name 2] - [Role]
+**Rating:** ___/5
+**Comments:** [Feedback]
+
+### [Stakeholder Name 3] - [Role]
+**Rating:** ___/5
+**Comments:** [Feedback]
+
+---
+
+## Recommendation
+
+### Decision: [ ] GO / [ ] CONDITIONAL GO / [ ] NO-GO
+
+**Rationale:**
+[2-3 paragraphs explaining the recommendation based on scorecard results, success criteria outcomes, stakeholder feedback, and overall evaluation]
+
+**Conditions (if Conditional GO):**
+1. [Condition 1 that must be met before proceeding]
+2. [Condition 2 that must be met before proceeding]
+
+**Key Strengths:**
+1. [Strength 1]
+2. [Strength 2]
+3. [Strength 3]
+
+**Key Concerns:**
+1. [Concern 1 with proposed mitigation]
+2. [Concern 2 with proposed mitigation]
+
+**Next Steps:**
+1. [Action item] - [Owner] - [Date]
+2. [Action item] - [Owner] - [Date]
+3. [Action item] - [Owner] - [Date]
+
+---
+
+## Sign-Off
+
+| Role | Name | Signature | Date |
+|------|------|-----------|------|
+| Technical Evaluator | | | |
+| Business Sponsor | | | |
+| Decision Maker | | | |
+| Sales Engineer | | | |
diff --git a/skills/business-growth/sales-engineer/assets/sample_rfp_data.json b/skills/business-growth/sales-engineer/assets/sample_rfp_data.json
new file mode 100644
index 00000000..1b060c76
--- /dev/null
+++ b/skills/business-growth/sales-engineer/assets/sample_rfp_data.json
@@ -0,0 +1,219 @@
+{
+ "rfp_name": "Enterprise Data Analytics Platform RFP",
+ "customer": "Acme Financial Services",
+ "due_date": "2026-03-15",
+ "deal_value": "$450,000 ARR",
+ "strategic_value": "high",
+ "requirements": [
+ {
+ "id": "R-001",
+ "requirement": "Real-time data ingestion from multiple sources (APIs, databases, streaming)",
+ "category": "Data Integration",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 8,
+ "notes": "Native connectors for 200+ data sources",
+ "mitigation": ""
+ },
+ {
+ "id": "R-002",
+ "requirement": "Support for SQL and NoSQL data sources",
+ "category": "Data Integration",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 4,
+ "notes": "Supports PostgreSQL, MySQL, MongoDB, Cassandra, and more",
+ "mitigation": ""
+ },
+ {
+ "id": "R-003",
+ "requirement": "Automated ETL pipeline creation with visual designer",
+ "category": "Data Integration",
+ "priority": "should-have",
+ "coverage_status": "full",
+ "effort_hours": 6,
+ "notes": "Drag-and-drop pipeline builder included",
+ "mitigation": ""
+ },
+ {
+ "id": "R-004",
+ "requirement": "Change data capture (CDC) for real-time sync",
+ "category": "Data Integration",
+ "priority": "should-have",
+ "coverage_status": "partial",
+ "effort_hours": 16,
+ "notes": "CDC supported for major databases; some require custom configuration",
+ "mitigation": "Document supported CDC sources; provide configuration guide for non-standard sources"
+ },
+ {
+ "id": "R-005",
+ "requirement": "Interactive dashboard creation with drag-and-drop",
+ "category": "Analytics & Visualization",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 4,
+ "notes": "Full drag-and-drop dashboard builder with 50+ chart types",
+ "mitigation": ""
+ },
+ {
+ "id": "R-006",
+ "requirement": "Embedded analytics with white-labeling support",
+ "category": "Analytics & Visualization",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 8,
+ "notes": "Full embedding SDK with CSS customization",
+ "mitigation": ""
+ },
+ {
+ "id": "R-007",
+ "requirement": "Natural language query interface for business users",
+ "category": "Analytics & Visualization",
+ "priority": "should-have",
+ "coverage_status": "planned",
+ "effort_hours": 24,
+ "notes": "NLQ feature on roadmap for Q3 2026",
+ "mitigation": "Share roadmap timeline; offer guided query builder as interim solution"
+ },
+ {
+ "id": "R-008",
+ "requirement": "Predictive analytics and ML model integration",
+ "category": "Analytics & Visualization",
+ "priority": "nice-to-have",
+ "coverage_status": "partial",
+ "effort_hours": 20,
+ "notes": "Python/R integration available; no built-in ML models",
+ "mitigation": "Demonstrate Python integration for custom models; provide example notebooks"
+ },
+ {
+ "id": "R-009",
+ "requirement": "Role-based access control (RBAC) with row-level security",
+ "category": "Security & Compliance",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 6,
+ "notes": "Granular RBAC with row-level and column-level security",
+ "mitigation": ""
+ },
+ {
+ "id": "R-010",
+ "requirement": "SOC 2 Type II certification",
+ "category": "Security & Compliance",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 2,
+ "notes": "Current SOC 2 Type II report available upon NDA",
+ "mitigation": ""
+ },
+ {
+ "id": "R-011",
+ "requirement": "Data encryption at rest and in transit (AES-256, TLS 1.3)",
+ "category": "Security & Compliance",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 2,
+ "notes": "AES-256 at rest, TLS 1.3 in transit, customer-managed keys supported",
+ "mitigation": ""
+ },
+ {
+ "id": "R-012",
+ "requirement": "HIPAA compliance for healthcare data handling",
+ "category": "Security & Compliance",
+ "priority": "should-have",
+ "coverage_status": "gap",
+ "effort_hours": 40,
+ "notes": "HIPAA BAA not currently offered",
+ "mitigation": "Evaluate HIPAA certification timeline with compliance team; consider data masking as interim"
+ },
+ {
+ "id": "R-013",
+ "requirement": "Horizontal scaling to handle 10B+ rows",
+ "category": "Performance & Scalability",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 8,
+ "notes": "Distributed query engine scales to 50B+ rows",
+ "mitigation": ""
+ },
+ {
+ "id": "R-014",
+ "requirement": "Sub-second query response for cached dashboards",
+ "category": "Performance & Scalability",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 4,
+ "notes": "Intelligent caching layer with <500ms p95 for cached queries",
+ "mitigation": ""
+ },
+ {
+ "id": "R-015",
+ "requirement": "Multi-region deployment with data residency controls",
+ "category": "Performance & Scalability",
+ "priority": "should-have",
+ "coverage_status": "partial",
+ "effort_hours": 20,
+ "notes": "US and EU regions available; APAC region in beta",
+ "mitigation": "Confirm customer region requirements; provide APAC beta access if needed"
+ },
+ {
+ "id": "R-016",
+ "requirement": "RESTful API with comprehensive documentation",
+ "category": "API & Extensibility",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 4,
+ "notes": "Full REST API with OpenAPI spec and interactive documentation",
+ "mitigation": ""
+ },
+ {
+ "id": "R-017",
+ "requirement": "Webhook support for event-driven workflows",
+ "category": "API & Extensibility",
+ "priority": "should-have",
+ "coverage_status": "full",
+ "effort_hours": 4,
+ "notes": "Webhook support for 30+ event types",
+ "mitigation": ""
+ },
+ {
+ "id": "R-018",
+ "requirement": "Custom plugin/extension framework",
+ "category": "API & Extensibility",
+ "priority": "nice-to-have",
+ "coverage_status": "planned",
+ "effort_hours": 30,
+ "notes": "Plugin framework on roadmap for Q4 2026",
+ "mitigation": "Current API extensibility covers most use cases; plugin framework will expand options"
+ },
+ {
+ "id": "R-019",
+ "requirement": "24/7 enterprise support with 1-hour critical response time",
+ "category": "Support & SLA",
+ "priority": "must-have",
+ "coverage_status": "full",
+ "effort_hours": 2,
+ "notes": "Premium support tier includes 24/7 coverage with 30-min critical response SLA",
+ "mitigation": ""
+ },
+ {
+ "id": "R-020",
+ "requirement": "Dedicated customer success manager",
+ "category": "Support & SLA",
+ "priority": "should-have",
+ "coverage_status": "full",
+ "effort_hours": 2,
+ "notes": "Included in Enterprise tier",
+ "mitigation": ""
+ },
+ {
+ "id": "R-021",
+ "requirement": "On-premise deployment option",
+ "category": "Deployment",
+ "priority": "nice-to-have",
+ "coverage_status": "gap",
+ "effort_hours": 80,
+ "notes": "Cloud-only platform; no on-premise offering",
+ "mitigation": "Position cloud-first architecture benefits; offer VPC deployment as alternative"
+ }
+ ]
+}
diff --git a/skills/business-growth/sales-engineer/assets/technical_proposal_template.md b/skills/business-growth/sales-engineer/assets/technical_proposal_template.md
new file mode 100644
index 00000000..f152e3e4
--- /dev/null
+++ b/skills/business-growth/sales-engineer/assets/technical_proposal_template.md
@@ -0,0 +1,231 @@
+# Technical Proposal Template
+
+## Document Information
+
+| Field | Value |
+|-------|-------|
+| Customer | [Customer Name] |
+| Opportunity | [Opportunity Name / RFP Reference] |
+| Prepared By | [Sales Engineer Name] |
+| Date | [Date] |
+| Version | [Version Number] |
+| Classification | [Confidential / Internal] |
+
+---
+
+## 1. Executive Summary
+
+### Business Context
+
+[2-3 paragraphs summarizing the customer's business challenges and strategic objectives that this solution addresses. Focus on business outcomes, not technical features.]
+
+### Proposed Solution
+
+[1-2 paragraphs describing the solution at a high level, emphasizing how it addresses the specific challenges identified above.]
+
+### Key Value Propositions
+
+1. **[Value 1]:** [Quantified benefit, e.g., "Reduce reporting time by 60%"]
+2. **[Value 2]:** [Quantified benefit]
+3. **[Value 3]:** [Quantified benefit]
+
+### Recommended Approach
+
+[Brief overview of the implementation approach, timeline, and key milestones.]
+
+---
+
+## 2. Requirements Summary
+
+### Coverage Overview
+
+| Category | Requirements | Full | Partial | Planned | Gap | Coverage |
+|----------|-------------|------|---------|---------|-----|----------|
+| [Category 1] | [N] | [N] | [N] | [N] | [N] | [X%] |
+| [Category 2] | [N] | [N] | [N] | [N] | [N] | [X%] |
+| **Total** | **[N]** | **[N]** | **[N]** | **[N]** | **[N]** | **[X%]** |
+
+### Key Differentiators
+
+1. [Differentiator 1 with brief explanation]
+2. [Differentiator 2 with brief explanation]
+3. [Differentiator 3 with brief explanation]
+
+### Gap Mitigation Plan
+
+| Gap | Priority | Mitigation Strategy | Timeline |
+|-----|----------|-------------------|----------|
+| [Gap 1] | [Must/Should/Nice] | [Strategy] | [Date] |
+| [Gap 2] | [Must/Should/Nice] | [Strategy] | [Date] |
+
+---
+
+## 3. Solution Architecture
+
+### Architecture Overview
+
+[High-level architecture description. Include or reference an architecture diagram.]
+
+```
+[ASCII architecture diagram or reference to attached diagram]
+
+Example:
++------------------+ +------------------+ +------------------+
+| Data Sources | --> | Our Platform | --> | Delivery |
+| - System A | | - Ingestion | | - Dashboards |
+| - System B | | - Processing | | - API |
+| - System C | | - Analytics | | - Exports |
++------------------+ +------------------+ +------------------+
+ |
+ +------------------+
+ | Management |
+ | - Security |
+ | - Monitoring |
+ | - Admin |
+ +------------------+
+```
+
+### Component Details
+
+#### [Component 1]
+- **Purpose:** [What this component does]
+- **Technology:** [Underlying technology]
+- **Scaling:** [How it scales]
+- **Availability:** [HA/DR approach]
+
+#### [Component 2]
+- **Purpose:** [What this component does]
+- **Technology:** [Underlying technology]
+- **Scaling:** [How it scales]
+- **Availability:** [HA/DR approach]
+
+### Integration Architecture
+
+| Integration Point | Protocol | Direction | Frequency | Authentication |
+|-------------------|----------|-----------|-----------|---------------|
+| [System A] | REST API | Inbound | Real-time | OAuth 2.0 |
+| [System B] | JDBC | Inbound | Batch (hourly) | Service Account |
+| [System C] | Webhook | Outbound | Event-driven | API Key |
+
+### Security Architecture
+
+- **Authentication:** [SSO, SAML, OAuth, etc.]
+- **Authorization:** [RBAC, row-level security, etc.]
+- **Encryption:** [At rest, in transit, key management]
+- **Compliance:** [SOC 2, GDPR, HIPAA, etc.]
+- **Network:** [VPC, firewall, IP restrictions]
+
+---
+
+## 4. Implementation Plan
+
+### Phase Overview
+
+| Phase | Duration | Focus | Deliverables |
+|-------|----------|-------|-------------|
+| Phase 1: Foundation | [X weeks] | Environment setup, core configuration | Working environment, admin access |
+| Phase 2: Core Implementation | [X weeks] | Primary use cases, integrations | [Deliverables] |
+| Phase 3: Advanced Features | [X weeks] | Advanced scenarios, optimization | [Deliverables] |
+| Phase 4: Go-Live | [X weeks] | Testing, training, cutover | Production deployment |
+
+### Detailed Timeline
+
+```
+Week 1-2: [Phase 1 - Foundation]
+ - Environment provisioning
+ - Security configuration
+ - Data source connectivity
+
+Week 3-6: [Phase 2 - Core Implementation]
+ - Use case 1 implementation
+ - Use case 2 implementation
+ - Integration testing
+
+Week 7-8: [Phase 3 - Advanced Features]
+ - Advanced analytics
+ - Custom workflows
+ - Performance optimization
+
+Week 9-10: [Phase 4 - Go-Live]
+ - User acceptance testing
+ - Training sessions
+ - Production cutover
+ - Post-launch support
+```
+
+### Resource Requirements
+
+| Role | Hours | Phase(s) | Provider |
+|------|-------|----------|----------|
+| Solutions Architect | [X] | All | [Vendor] |
+| Implementation Engineer | [X] | 1-3 | [Vendor] |
+| Project Manager | [X] | All | [Vendor] |
+| Customer IT Admin | [X] | 1, 4 | [Customer] |
+| Customer Business Lead | [X] | 2-4 | [Customer] |
+
+### Training Plan
+
+| Audience | Format | Duration | Content |
+|----------|--------|----------|---------|
+| Administrators | Workshop | [X hours] | Configuration, security, monitoring |
+| Power Users | Workshop | [X hours] | Advanced features, reporting, automation |
+| End Users | Webinar | [X hours] | Core workflows, self-service analytics |
+
+---
+
+## 5. Risk Mitigation
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| [Risk 1] | [H/M/L] | [H/M/L] | [Strategy] |
+| [Risk 2] | [H/M/L] | [H/M/L] | [Strategy] |
+| [Risk 3] | [H/M/L] | [H/M/L] | [Strategy] |
+
+---
+
+## 6. Commercial Summary
+
+### Pricing Overview
+
+| Component | Annual Cost |
+|-----------|------------|
+| Platform License | $[X] |
+| Implementation Services | $[X] |
+| Training | $[X] |
+| Premium Support | $[X] |
+| **Total Year 1** | **$[X]** |
+| **Annual Renewal** | **$[X]** |
+
+### ROI Projection
+
+| Metric | Current State | With Solution | Improvement |
+|--------|--------------|---------------|-------------|
+| [Metric 1] | [Value] | [Value] | [%] |
+| [Metric 2] | [Value] | [Value] | [%] |
+| [Metric 3] | [Value] | [Value] | [%] |
+
+**Estimated payback period:** [X months]
+
+---
+
+## 7. Next Steps
+
+1. [Next step 1 with owner and date]
+2. [Next step 2 with owner and date]
+3. [Next step 3 with owner and date]
+
+---
+
+## Appendices
+
+### A. Detailed Compliance Matrix
+[Reference to full requirement-by-requirement response]
+
+### B. Reference Customers
+[2-3 relevant customer references with industry, use case, and outcomes]
+
+### C. Architecture Diagrams
+[Detailed architecture diagrams]
+
+### D. Product Roadmap (Relevant Items)
+[Roadmap items relevant to this proposal with estimated delivery dates]
diff --git a/skills/business-growth/sales-engineer/references/competitive-positioning-framework.md b/skills/business-growth/sales-engineer/references/competitive-positioning-framework.md
new file mode 100644
index 00000000..c23efc76
--- /dev/null
+++ b/skills/business-growth/sales-engineer/references/competitive-positioning-framework.md
@@ -0,0 +1,226 @@
+# Competitive Positioning Framework
+
+A comprehensive guide for Sales Engineers to analyze competitors, build battlecards, handle objections, and position for wins.
+
+## Competitive Analysis Methodology
+
+### 1. Intelligence Gathering
+
+**Primary Sources:**
+- Competitor product documentation and release notes
+- Analyst reports (Gartner, Forrester, IDC)
+- Customer feedback from win/loss reviews
+- Industry conferences and webinars
+- Public case studies and testimonials
+- Open-source repositories and API documentation
+
+**Secondary Sources:**
+- Glassdoor reviews (engineering culture, product direction)
+- Job postings (technology stack, expansion areas)
+- Patent filings (future direction signals)
+- Social media and community forums
+- Partner ecosystem announcements
+
+### 2. Feature Comparison Best Practices
+
+**Feature Scoring Scale:**
+
+| Score | Label | Definition |
+|-------|-------|------------|
+| 3 | Full | Complete, production-ready feature support |
+| 2 | Partial | Feature exists but with limitations or caveats |
+| 1 | Limited | Minimal implementation, significant gaps |
+| 0 | None | Feature not available |
+
+**Comparison Categories:**
+
+Organize features into weighted categories that reflect customer priorities:
+
+| Category | Typical Weight | What to Evaluate |
+|----------|---------------|------------------|
+| Core Functionality | 25-35% | Primary use case coverage |
+| Integration & API | 15-25% | Ecosystem connectivity |
+| Security & Compliance | 15-20% | Enterprise readiness |
+| Scalability & Performance | 10-20% | Growth capacity |
+| Usability & UX | 10-15% | Time to value |
+| Support & Services | 5-10% | Vendor partnership quality |
+
+**Weighting Guidelines:**
+- Adjust weights based on the specific customer's priorities
+- Security-sensitive industries (healthcare, finance) should weight compliance higher
+- High-growth companies should weight scalability higher
+- Enterprise deals should weight integration and support higher
+
+### 3. Differentiator Identification
+
+A differentiator is a feature or capability where your product scores highest among all compared products. Strong differentiators have these properties:
+
+- **Unique:** Only your product offers this capability
+- **Valuable:** Customers care about this capability
+- **Defensible:** Not easily replicated by competitors
+- **Demonstrable:** Can be shown in a demo or POC
+
+**Differentiator Categories:**
+
+| Type | Description | Example |
+|------|-------------|---------|
+| Feature Differentiator | Unique product capability | Native ML-powered anomaly detection |
+| Architecture Differentiator | Fundamental design advantage | Multi-tenant with data isolation |
+| Ecosystem Differentiator | Partner or integration advantage | 200+ native integrations |
+| Service Differentiator | Support or engagement model | Dedicated SE throughout contract |
+| Economic Differentiator | Pricing or TCO advantage | Usage-based pricing with no minimums |
+
+### 4. Vulnerability Assessment
+
+Vulnerabilities are features where competitors score higher than your product. Address vulnerabilities proactively:
+
+**Vulnerability Response Strategies:**
+
+1. **Acknowledge and redirect:** Confirm the gap, then pivot to your strength areas
+2. **Reframe the requirement:** Show why the customer's real need is better met differently
+3. **Demonstrate workaround:** Show how existing capabilities address the underlying need
+4. **Commit to roadmap:** Provide a credible timeline for native support
+5. **Partner solution:** Identify an integration partner that fills the gap
+
+## Objection Handling
+
+### Common Technical Objections
+
+#### "Your product lacks [Feature X]"
+**Response Framework:**
+1. Acknowledge: "You're right that [Feature X] is not a standalone feature today."
+2. Explore: "Help me understand the specific use case you need [Feature X] for."
+3. Redirect: "Our approach to solving that is [alternative], which actually provides [benefit]."
+4. Evidence: "Customer [reference] had the same concern and found [outcome]."
+
+#### "Competitor [Y] has better [Capability]"
+**Response Framework:**
+1. Acknowledge: "I understand [Competitor Y] has invested in [Capability]."
+2. Qualify: "Can you share what specific aspects of [Capability] are most important?"
+3. Differentiate: "While they focus on [approach], we take a different approach with [our method] because [reason]."
+4. Quantify: "The practical difference in real-world usage is [metric/evidence]."
+
+#### "Your product is too expensive"
+**Response Framework:**
+1. Acknowledge: "I appreciate you sharing that concern."
+2. Reframe: "Let's look at total cost of ownership rather than license cost alone."
+3. Quantify: "When you factor in [implementation, training, maintenance, time-to-value], the TCO comparison shows..."
+4. Value: "Based on our analysis, the ROI timeline is [X months], delivering [Y value]."
+
+#### "We're concerned about vendor lock-in"
+**Response Framework:**
+1. Acknowledge: "That's a smart concern for any technology investment."
+2. Evidence: "Our architecture uses [open standards, APIs, data portability features]."
+3. Demonstrate: "Here's how data export and migration work [show the feature]."
+4. Reference: "We can connect you with customers who evaluated this exact concern."
+
+### Objection Handling Principles
+
+1. **Never disparage competitors.** Focus on your strengths, not their weaknesses.
+2. **Ask questions first.** Understand the real concern behind the objection.
+3. **Use evidence.** Reference customers, benchmarks, and demonstrations.
+4. **Be honest about gaps.** Credibility is your most valuable asset.
+5. **Redirect to value.** Connect every response back to business outcomes.
+
+## Win/Loss Analysis
+
+### Post-Decision Review Process
+
+**Timing:** Conduct within 2 weeks of the decision for accurate recall.
+
+**Interview Questions (for wins):**
+1. What was the deciding factor in choosing us?
+2. Which features or capabilities were most compelling?
+3. How did our demo/POC compare to alternatives?
+4. What concerns did you have that were resolved during the process?
+5. What could we have done better in the evaluation process?
+
+**Interview Questions (for losses):**
+1. What was the primary reason for choosing the competitor?
+2. Were there specific requirements we did not meet?
+3. How did our demo/POC compare to the winning vendor?
+4. What would have changed your decision?
+5. Would you consider us for future evaluations?
+
+### Win/Loss Data Tracking
+
+| Data Point | Purpose |
+|-----------|---------|
+| Deal size | Pattern analysis by segment |
+| Industry | Vertical-specific insights |
+| Competitor | Head-to-head record |
+| Decision factors | Feature priority validation |
+| Sales cycle length | Process efficiency |
+| Stakeholder roles | Engagement strategy |
+| Technical requirements | Capability gap tracking |
+| POC outcome | POC process improvement |
+
+### Analysis Dimensions
+
+1. **By Competitor:** Win rate per competitor, common objections, feature gaps
+2. **By Segment:** Enterprise vs mid-market vs SMB patterns
+3. **By Industry:** Vertical-specific win factors
+4. **By Deal Size:** Large vs small deal dynamics
+5. **By Feature Category:** Which capabilities drive wins vs losses
+
+## Battlecard Creation
+
+### Battlecard Structure
+
+**Page 1: Quick Reference**
+- Competitor overview (company size, funding, market position)
+- Key strengths (top 3)
+- Key weaknesses (top 3)
+- Ideal customer profile for the competitor
+- Our win rate against this competitor
+
+**Page 2: Feature Comparison**
+- Category-by-category comparison (summary view)
+- Top differentiators (features where we lead)
+- Top vulnerabilities (features where they lead)
+- Parity features (features at same level)
+
+**Page 3: Talk Track**
+- Opening positioning statement
+- Discovery questions that expose competitor weaknesses
+- Objection responses for their key strengths
+- Proof points (customer references, benchmarks, case studies)
+- Trap-setting questions for demos and POCs
+
+**Page 4: Win Strategies**
+- Recommended evaluation criteria that favor our strengths
+- Demo scenarios that highlight our differentiators
+- POC success criteria that align with our capabilities
+- Pricing and packaging positioning
+- Stakeholder engagement strategy
+
+### Battlecard Maintenance
+
+- **Monthly review:** Update feature scores based on new releases
+- **Quarterly refresh:** Incorporate win/loss analysis findings
+- **Trigger-based update:** Major competitor release, pricing change, or acquisition
+
+## Competitive Positioning During Evaluations
+
+### Evaluation Stage Tactics
+
+| Stage | Tactic |
+|-------|--------|
+| Discovery | Ask questions that expose competitor weaknesses |
+| Demo | Lead with differentiators, show end-to-end workflows |
+| POC | Define success criteria aligned with your strengths |
+| Proposal | Quantify TCO advantage, emphasize implementation risk |
+| Negotiation | Leverage competitive urgency, offer migration assistance |
+
+### Influencing Evaluation Criteria
+
+The sales engineer's most impactful opportunity is shaping the evaluation criteria before the formal process begins:
+
+1. **Map criteria to strengths:** Propose evaluation categories where you excel
+2. **Weight appropriately:** Ensure critical categories (where you lead) carry higher weight
+3. **Define metrics:** Specific, measurable criteria favor the more capable product
+4. **Include non-obvious criteria:** Total cost of ownership, time-to-value, ecosystem breadth
+
+---
+
+**Last Updated:** February 2026
diff --git a/skills/business-growth/sales-engineer/references/poc-best-practices.md b/skills/business-growth/sales-engineer/references/poc-best-practices.md
new file mode 100644
index 00000000..177e5291
--- /dev/null
+++ b/skills/business-growth/sales-engineer/references/poc-best-practices.md
@@ -0,0 +1,277 @@
+# Proof of Concept (POC) Best Practices
+
+A comprehensive guide for Sales Engineers planning, executing, and evaluating proof-of-concept engagements.
+
+## POC Planning Methodology
+
+### 1. Pre-POC Qualification
+
+Not every deal warrants a POC. Qualify before committing resources:
+
+**POC-Worthy Indicators:**
+- Deal value justifies 80-200+ hours of SE and engineering time
+- Customer has an identified champion who will actively participate
+- Clear decision timeline with POC as a defined evaluation step
+- Budget is allocated or allocation process is underway
+- Technical stakeholders are available for the evaluation period
+
+**POC Red Flags:**
+- "Free trial" request with no commitment to evaluate
+- No identified decision-maker or budget owner
+- Competitor has already been selected; POC is for validation only
+- Customer expects production-grade environment for extended period
+- No defined success criteria or evaluation framework
+
+### 2. Scope Definition
+
+The most critical success factor is a well-defined scope. An uncontrolled scope leads to extended timelines, unmet expectations, and lost deals.
+
+**Scope Elements:**
+- **Use cases:** 3-5 specific scenarios to validate (not "everything")
+- **Integrations:** Which systems must connect during the POC
+- **Data:** What data will be used (sample, synthetic, production subset)
+- **Users:** Who will access the POC environment and in what roles
+- **Duration:** Fixed timeline with clear milestones
+- **Success criteria:** Measurable, objective criteria for each use case
+
+**Scope Control Tactics:**
+- Document scope in writing with customer sign-off
+- Define what is explicitly out of scope
+- Create a change request process for scope additions
+- Set a maximum number of use cases per complexity tier
+
+### 3. Timeline Planning
+
+**Standard 5-Week Framework:**
+
+| Week | Phase | Focus | Key Activities |
+|------|-------|-------|---------------|
+| 1 | Setup | Foundation | Environment, data, access, kickoff |
+| 2-3 | Core Testing | Validation | Primary use cases, integrations, workflows |
+| 4 | Advanced Testing | Edge cases | Performance, security, scale, administration |
+| 5 | Evaluation | Decision | Scorecard, review, recommendation |
+
+**Timeline Adjustments by Complexity:**
+
+| Complexity | Duration | Use Cases | Integrations |
+|-----------|----------|-----------|-------------|
+| Low | 3 weeks | 2-3 | 0-1 |
+| Medium | 5 weeks | 3-5 | 2-3 |
+| High | 6-8 weeks | 5-8 | 4+ |
+
+**Timeline Rules:**
+- Never exceed 8 weeks. Longer POCs lose momentum and stakeholder attention.
+- Front-load the most impressive capabilities to build early momentum.
+- Schedule stakeholder checkpoints at the end of each phase.
+- Build 20% buffer into each phase for unexpected issues.
+
+### 4. Resource Planning
+
+**SE Allocation:**
+
+| Activity | Hours/Week (Medium Complexity) |
+|----------|-------------------------------|
+| Environment setup and configuration | 15-20 (Week 1 only) |
+| Use case execution and testing | 20-25 |
+| Stakeholder communication | 3-5 |
+| Documentation and reporting | 3-5 |
+| Issue resolution | 5-8 |
+
+**Engineering Support:**
+- Allocate dedicated engineering support for complex integrations
+- Establish an escalation path for blocking issues
+- Pre-schedule engineering availability during Core Testing phase
+- Request customer IT support for integration access and credentials
+
+**Customer Resources:**
+- Technical sponsor for daily communication
+- Business stakeholders for use case validation
+- IT/Security for environment access and compliance review
+- End users for usability feedback (if applicable)
+
+## Success Criteria Definition
+
+### Writing Effective Success Criteria
+
+Each criterion must be:
+- **Specific:** Clearly defined with no ambiguity
+- **Measurable:** Quantifiable metric or clear pass/fail
+- **Agreed:** Documented and signed off by both parties
+- **Relevant:** Tied to a business outcome or technical requirement
+- **Time-bound:** Evaluated within the POC timeline
+
+### Success Criteria Categories
+
+**Functionality Criteria:**
+- "System processes [X] transactions per hour without errors"
+- "Workflow automation reduces manual steps from [Y] to [Z]"
+- "Report generation completes within [N] seconds for [M] records"
+- "All [X] defined use cases completed successfully"
+
+**Performance Criteria:**
+- "API response time <200ms at p95 under [N] concurrent users"
+- "Batch processing completes [X] records in under [Y] minutes"
+- "System maintains performance with [N]x expected data volume"
+
+**Integration Criteria:**
+- "Bidirectional sync with [System X] operates within [Y] minute latency"
+- "SSO integration with [IdP] supports all required authentication flows"
+- "Data import from [Source] completes with <1% error rate"
+
+**Usability Criteria:**
+- "New users complete [task] within [N] minutes without assistance"
+- "Admin configuration for [scenario] requires fewer than [N] steps"
+- "Stakeholder satisfaction rating >= 4.0/5.0"
+
+### Anti-Patterns in Success Criteria
+
+- **Too vague:** "System performs well" (what is "well"?)
+- **Too many:** More than 15 criteria dilutes focus and extends timeline
+- **Unmeasurable:** "Users like the interface" (how do you measure "like"?)
+- **Biased toward feature count:** "Must have Feature X" instead of "Must solve Problem Y"
+- **Moving target:** Criteria that change mid-POC without formal agreement
+
+## Stakeholder Management
+
+### Stakeholder Map
+
+| Role | Priority | Engagement Strategy |
+|------|----------|-------------------|
+| Decision Maker | High | Executive briefings, ROI summaries |
+| Champion | Critical | Daily communication, progress updates |
+| Technical Evaluator | High | Hands-on access, deep-dive sessions |
+| End User | Medium | Usability testing, feedback sessions |
+| IT/Security | High | Compliance reviews, architecture sessions |
+| Procurement | Low-Medium | TCO documentation, reference connections |
+
+### Engagement Cadence
+
+- **Daily:** Champion check-in (10 min, Slack/email)
+- **Weekly:** Progress report to all stakeholders (written summary)
+- **Phase transitions:** Formal review meeting with demo of progress
+- **Final:** Executive presentation with scorecard results and recommendation
+
+### Managing Stakeholder Expectations
+
+1. **Set clear boundaries:** Define what will and will not be demonstrated
+2. **Communicate early and often:** No surprises; surface issues immediately
+3. **Document everything:** Meeting notes, decisions, change requests
+4. **Celebrate wins:** Highlight successful milestones to maintain momentum
+5. **Address concerns immediately:** Delays in resolution erode confidence
+
+## Evaluation Frameworks
+
+### Weighted Scorecard Model
+
+The evaluation scorecard provides an objective, comparable assessment:
+
+| Category | Weight | Score (1-5) | Weighted Score |
+|----------|--------|-------------|----------------|
+| Functionality | 30% | | |
+| Performance | 20% | | |
+| Integration | 20% | | |
+| Usability | 15% | | |
+| Support | 15% | | |
+| **Total** | **100%** | | |
+
+**Scoring Scale:**
+- 5: Exceeds requirements - superior capability demonstrated
+- 4: Meets requirements - full capability with minor enhancements possible
+- 3: Partially meets - acceptable but notable gaps remain
+- 2: Below expectations - significant gaps that impact value
+- 1: Does not meet - critical failure for this category
+
+**Decision Thresholds:**
+- Weighted average >= 4.0: **Strong Pass** - proceed to procurement
+- Weighted average 3.5-3.9: **Pass** - proceed with noted conditions
+- Weighted average 3.0-3.4: **Conditional** - requires further evaluation or negotiation
+- Weighted average < 3.0: **Fail** - does not meet requirements
+
+### Go/No-Go Decision Framework
+
+The go/no-go decision should be based on multiple factors, not just the scorecard:
+
+**Go Indicators:**
+- Scorecard score >= 3.5
+- All must-have success criteria met
+- Champion and decision-maker both express positive sentiment
+- No unresolved critical technical blockers
+- Clear implementation path identified
+
+**No-Go Indicators:**
+- Scorecard score < 3.0
+- Critical success criteria failed without clear resolution
+- Decision-maker expresses significant concerns
+- Multiple unresolved technical blockers
+- Competitive alternative clearly preferred by evaluators
+
+**Conditional Go Indicators:**
+- Scorecard score 3.0-3.5 with clear path to improvement
+- 1-2 minor success criteria not met but with workarounds
+- Mixed stakeholder sentiment that can be addressed
+- Blockers identified but resolution path confirmed with engineering
+
+## Common POC Failure Modes
+
+### 1. Scope Creep
+**Symptom:** Customer continuously adds requirements during the POC.
+**Prevention:** Written scope agreement with change request process.
+**Recovery:** Renegotiate timeline or defer additions to Phase 2.
+
+### 2. Champion Absence
+**Symptom:** Champion becomes unavailable or disengaged mid-POC.
+**Prevention:** Identify a backup champion. Schedule regular touchpoints.
+**Recovery:** Escalate to decision-maker. Demonstrate value already achieved.
+
+### 3. Data Issues
+**Symptom:** Customer data is unavailable, poor quality, or incompatible.
+**Prevention:** Request sample data before kickoff. Prepare synthetic data.
+**Recovery:** Use synthetic data for core testing. Document data requirements for implementation.
+
+### 4. Environment Problems
+**Symptom:** POC environment is unstable, slow, or inaccessible.
+**Prevention:** Use a dedicated, pre-configured environment. Test before kickoff.
+**Recovery:** Have a backup environment. Communicate honestly about delays.
+
+### 5. Moving Goalposts
+**Symptom:** Evaluation criteria change mid-POC, often influenced by competitor demos.
+**Prevention:** Get written sign-off on criteria before starting. Reference agreement when changes arise.
+**Recovery:** Agree to evaluate new criteria as addendum, not replacement. Highlight what has already been validated.
+
+### 6. Extended Timeline
+**Symptom:** POC drags beyond planned duration without clear progress.
+**Prevention:** Set hard deadlines in the agreement. Schedule decision meetings in advance.
+**Recovery:** Force a checkpoint. Present results to date and ask for a go/no-go with current evidence.
+
+### 7. Technical Blockers
+**Symptom:** Unexpected technical issues prevent completion of key use cases.
+**Prevention:** Conduct technical discovery before committing to POC. Have engineering on standby.
+**Recovery:** Escalate immediately. Provide transparent status updates. Offer alternative approaches.
+
+## POC Documentation
+
+### Required Artifacts
+
+| Document | When | Owner |
+|----------|------|-------|
+| Scope agreement | Pre-POC | SE + Customer |
+| Environment setup guide | Week 1 | SE |
+| Progress reports | Weekly | SE |
+| Phase review presentations | Phase transitions | SE |
+| Issue log | Ongoing | SE |
+| Final evaluation report | Week 5 | SE + Customer |
+| Lessons learned | Post-POC | SE |
+
+### Final Report Template
+
+1. **Executive Summary** - POC objectives, approach, and outcome
+2. **Scope and Success Criteria** - What was tested and how
+3. **Results Summary** - Success criteria outcomes with evidence
+4. **Evaluation Scorecard** - Weighted scores across all categories
+5. **Issues and Resolutions** - Problems encountered and how they were addressed
+6. **Recommendation** - Go/No-Go with rationale
+7. **Implementation Considerations** - Next steps, timeline, and resource needs
+
+---
+
+**Last Updated:** February 2026
diff --git a/skills/business-growth/sales-engineer/references/rfp-response-guide.md b/skills/business-growth/sales-engineer/references/rfp-response-guide.md
new file mode 100644
index 00000000..4307dd5b
--- /dev/null
+++ b/skills/business-growth/sales-engineer/references/rfp-response-guide.md
@@ -0,0 +1,189 @@
+# RFP/RFI Response Guide
+
+A comprehensive reference for Sales Engineers responding to Requests for Proposal (RFP) and Requests for Information (RFI).
+
+## RFP Response Best Practices
+
+### 1. Pre-Response Assessment
+
+Before investing time in a response, conduct a thorough bid/no-bid assessment:
+
+**Bid Criteria Checklist:**
+- Do we have a pre-existing relationship with the customer?
+- Is there an identified champion or sponsor?
+- Do our capabilities align with >70% of requirements?
+- Is the deal size justified against the response effort?
+- Do we understand the competitive landscape?
+- Is the timeline realistic for our solution?
+
+**Red Flags for No-Bid:**
+- No prior customer engagement (blind RFP)
+- Requirement language mirrors a competitor's product
+- Timeline is unrealistically short
+- Must-have requirements fall outside our platform
+- Budget is undefined or misaligned with our pricing
+
+### 2. Response Organization
+
+**Executive Summary (1-2 pages):**
+- Lead with business outcomes, not features
+- Reference the customer's specific challenges
+- Quantify value proposition with relevant metrics
+- State confidence level and key differentiators
+
+**Solution Overview:**
+- Map directly to the customer's stated requirements
+- Use the customer's language and terminology
+- Include architecture diagrams for technical sections
+- Address integration with existing systems
+
+**Compliance Matrix:**
+- Mirror the RFP's requirement numbering exactly
+- Use consistent coverage categories: Full, Partial, Planned, Gap
+- Provide clear explanations for each response
+- Include roadmap dates for "Planned" items
+
+### 3. Coverage Classification
+
+| Status | Score | Definition | Response Approach |
+|--------|-------|------------|-------------------|
+| Full | 100% | Current product fully meets requirement | Describe capability with evidence |
+| Partial | 50% | Met with configuration or workaround | Explain approach and any limitations |
+| Planned | 25% | On product roadmap | Provide timeline and interim solution |
+| Gap | 0% | Not currently supported | Acknowledge gap and propose alternatives |
+
+### 4. Priority-Weighted Scoring
+
+Not all requirements are equal. Weight them by business impact:
+
+- **Must-Have (3x weight):** Core requirements that are deal-breakers. Gaps here typically result in disqualification.
+- **Should-Have (2x weight):** Important requirements that influence the decision significantly.
+- **Nice-to-Have (1x weight):** Desirable but not critical. Often used as tie-breakers.
+
+### 5. Response Writing Tips
+
+**Do:**
+- Answer the question directly before elaborating
+- Use the customer's terminology, not internal jargon
+- Provide specific examples, case studies, and metrics
+- Include screenshots or architecture diagrams where relevant
+- Cross-reference related answers to avoid redundancy
+- Proofread for consistency across sections (multiple authors)
+
+**Avoid:**
+- Marketing fluff or vague language ("best-in-class", "world-class")
+- Answering a question you were not asked
+- Contradictions between sections
+- Overselling capabilities you do not have
+- Ignoring the question format (tables vs. narrative)
+
+## Bid/No-Bid Decision Framework
+
+### Decision Matrix
+
+| Factor | Weight | Score (1-5) | Weighted |
+|--------|--------|-------------|----------|
+| Technical fit | 25% | | |
+| Relationship strength | 20% | | |
+| Competitive position | 20% | | |
+| Deal value vs effort | 15% | | |
+| Strategic importance | 10% | | |
+| Win probability | 10% | | |
+| **Total** | **100%** | | |
+
+**Scoring Guide:**
+- 5: Strong advantage
+- 4: Slight advantage
+- 3: Neutral / competitive parity
+- 2: Slight disadvantage
+- 1: Significant disadvantage
+
+**Decision Thresholds:**
+- Score >= 3.5: **Bid** - proceed with full response
+- Score 2.5 - 3.4: **Conditional Bid** - proceed with executive approval
+- Score < 2.5: **No-Bid** - decline or submit information-only response
+
+### Effort Estimation
+
+Estimate the total effort required and compare against deal value:
+
+| Response Component | Typical Effort (hours) |
+|-------------------|----------------------|
+| Requirements analysis | 4-8 |
+| Technical writing | 16-40 |
+| Architecture diagrams | 4-8 |
+| Demo preparation | 8-16 |
+| Internal review | 4-8 |
+| Final formatting | 2-4 |
+| **Total** | **38-84 hours** |
+
+**Rule of thumb:** The response effort should not exceed 2% of the deal value.
+
+## Compliance Matrix Structure
+
+### Standard Format
+
+```
+| Req ID | Requirement Description | Priority | Compliance | Response | Evidence |
+|--------|------------------------|----------|------------|----------|----------|
+| R-001 | SSO via SAML 2.0 | Must | Full | Native SAML 2.0 support... | Config guide |
+| R-002 | Custom reporting | Should | Partial | Standard reports + API... | API docs |
+```
+
+### Section Organization
+
+Organize requirements by category for clarity:
+
+1. **Functional Requirements** - Core features and capabilities
+2. **Technical Requirements** - Architecture, APIs, performance
+3. **Security & Compliance** - Authentication, encryption, certifications
+4. **Integration Requirements** - Third-party systems, data flows
+5. **Support & SLA** - Support tiers, response times, uptime
+6. **Vendor Qualifications** - Company size, financials, references
+
+## Common Pitfalls
+
+### 1. The Wired RFP
+**Symptom:** Requirements language matches a competitor's product feature list.
+**Response:** Focus on outcomes over features. Highlight areas of differentiation. Ask clarifying questions that expose broader needs.
+
+### 2. Feature Checklist Syndrome
+**Symptom:** RFP is a massive feature checklist with no context about business problems.
+**Response:** Group features by business outcome. Add context in your response that demonstrates understanding of the underlying need.
+
+### 3. Scope Creep in Response
+**Symptom:** Team keeps adding content that was not requested.
+**Response:** Assign a response manager to enforce scope. Answer what was asked, provide references for additional information.
+
+### 4. Inconsistent Messaging
+**Symptom:** Multiple authors provide contradictory information.
+**Response:** Assign a single editor for final review. Create a response style guide. Use consistent terminology throughout.
+
+### 5. Overcommitting on Gaps
+**Symptom:** Marking "Planned" items as "Full" to improve scores.
+**Response:** Never misrepresent coverage. Planned items with firm timelines and interim workarounds are better than lies discovered during POC.
+
+## RFP Response Timeline Management
+
+### Typical Response Timeline
+
+| Day | Activity |
+|-----|----------|
+| Day 1 | Receive RFP, conduct initial review, assign team |
+| Day 2-3 | Bid/no-bid decision, questions submission |
+| Day 4-7 | Requirements analysis, coverage assessment |
+| Day 8-14 | Draft responses, architecture diagrams |
+| Day 15-17 | Internal review, quality check |
+| Day 18-19 | Final edits, formatting, executive review |
+| Day 20 | Submission |
+
+### Time-Saving Strategies
+
+1. **Maintain a response library** - Reusable answers for common requirements
+2. **Pre-built architecture diagrams** - Template diagrams for common integration patterns
+3. **Standardized compliance language** - Pre-approved language for security and compliance sections
+4. **Question templates** - Standard clarifying questions for common ambiguities
+
+---
+
+**Last Updated:** February 2026
diff --git a/skills/business-growth/sales-engineer/scripts/competitive_matrix_builder.py b/skills/business-growth/sales-engineer/scripts/competitive_matrix_builder.py
new file mode 100644
index 00000000..42b92a70
--- /dev/null
+++ b/skills/business-growth/sales-engineer/scripts/competitive_matrix_builder.py
@@ -0,0 +1,525 @@
+#!/usr/bin/env python3
+"""Competitive Matrix Builder - Generate feature comparison matrices and positioning analysis.
+
+Builds feature-by-feature comparison matrices, calculates weighted competitive
+scores, identifies differentiators and vulnerabilities, and generates win themes.
+
+Usage:
+ python competitive_matrix_builder.py competitive_data.json
+ python competitive_matrix_builder.py competitive_data.json --format json
+ python competitive_matrix_builder.py competitive_data.json --format text
+"""
+
+import argparse
+import json
+import sys
+from typing import Any
+
+
+# Feature scoring levels
+FEATURE_SCORES: dict[str, int] = {
+ "full": 3,
+ "partial": 2,
+ "limited": 1,
+ "none": 0,
+}
+
+FEATURE_LABELS: dict[int, str] = {
+ 3: "Full",
+ 2: "Partial",
+ 1: "Limited",
+ 0: "None",
+}
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def load_competitive_data(filepath: str) -> dict[str, Any]:
+ """Load and validate competitive data from a JSON file.
+
+ Args:
+ filepath: Path to the JSON file containing competitive data.
+
+ Returns:
+ Parsed competitive data dictionary.
+
+ Raises:
+ SystemExit: If the file cannot be read or parsed.
+ """
+ try:
+ with open(filepath, "r", encoding="utf-8") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {filepath}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {filepath}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ if "categories" not in data:
+ print("Error: JSON must contain a 'categories' array.", file=sys.stderr)
+ sys.exit(1)
+
+ if "our_product" not in data:
+ print("Error: JSON must contain 'our_product' name.", file=sys.stderr)
+ sys.exit(1)
+
+ if "competitors" not in data or not data["competitors"]:
+ print("Error: JSON must contain a non-empty 'competitors' array.", file=sys.stderr)
+ sys.exit(1)
+
+ return data
+
+
+def normalize_score(score_value: Any) -> int:
+ """Normalize a score value to an integer.
+
+ Args:
+ score_value: Score as string label or integer.
+
+ Returns:
+ Normalized integer score (0-3).
+ """
+ if isinstance(score_value, str):
+ return FEATURE_SCORES.get(score_value.lower(), 0)
+ if isinstance(score_value, (int, float)):
+ return max(0, min(3, int(score_value)))
+ return 0
+
+
+def build_comparison_matrix(data: dict[str, Any]) -> dict[str, Any]:
+ """Build the feature comparison matrix from input data.
+
+ Args:
+ data: Competitive data with categories, features, and scores.
+
+ Returns:
+ Comparison matrix with per-feature and per-category scores.
+ """
+ our_product = data["our_product"]
+ competitors = data["competitors"]
+ all_products = [our_product] + competitors
+
+ matrix: list[dict[str, Any]] = []
+ category_summaries: dict[str, dict[str, Any]] = {}
+
+ for category in data["categories"]:
+ cat_name = category["name"]
+ cat_weight = category.get("weight", 1.0)
+ cat_features = category.get("features", [])
+
+ cat_scores: dict[str, list[int]] = {p: [] for p in all_products}
+
+ for feature in cat_features:
+ feature_name = feature["name"]
+ scores: dict[str, int] = {}
+
+ for product in all_products:
+ raw_score = feature.get("scores", {}).get(product, 0)
+ scores[product] = normalize_score(raw_score)
+ cat_scores[product].append(scores[product])
+
+ # Determine leader for this feature
+ max_score = max(scores.values())
+ leaders = [p for p, s in scores.items() if s == max_score]
+
+ matrix.append({
+ "category": cat_name,
+ "feature": feature_name,
+ "scores": scores,
+ "leaders": leaders,
+ "our_score": scores[our_product],
+ "max_score": max_score,
+ "we_lead": our_product in leaders and len(leaders) == 1,
+ "we_trail": scores[our_product] < max_score,
+ })
+
+ # Category summary
+ cat_product_scores = {}
+ for product in all_products:
+ product_scores = cat_scores[product]
+ total = sum(product_scores)
+ max_possible = len(product_scores) * 3
+ pct = safe_divide(total, max_possible) * 100
+ cat_product_scores[product] = {
+ "total_score": total,
+ "max_possible": max_possible,
+ "percentage": round(pct, 1),
+ }
+
+ category_summaries[cat_name] = {
+ "weight": cat_weight,
+ "feature_count": len(cat_features),
+ "product_scores": cat_product_scores,
+ }
+
+ return {
+ "our_product": our_product,
+ "competitors": competitors,
+ "all_products": all_products,
+ "matrix": matrix,
+ "category_summaries": category_summaries,
+ }
+
+
+def compute_competitive_scores(
+ comparison: dict[str, Any],
+) -> dict[str, dict[str, Any]]:
+ """Compute weighted competitive scores for each product.
+
+ Args:
+ comparison: Comparison matrix data.
+
+ Returns:
+ Product scores with weighted and unweighted totals.
+ """
+ all_products = comparison["all_products"]
+ category_summaries = comparison["category_summaries"]
+
+ product_scores: dict[str, dict[str, float]] = {
+ p: {"weighted_total": 0.0, "max_weighted": 0.0, "unweighted_total": 0, "max_unweighted": 0}
+ for p in all_products
+ }
+
+ for cat_name, cat_data in category_summaries.items():
+ weight = cat_data["weight"]
+ for product in all_products:
+ p_data = cat_data["product_scores"][product]
+ product_scores[product]["weighted_total"] += p_data["total_score"] * weight
+ product_scores[product]["max_weighted"] += p_data["max_possible"] * weight
+ product_scores[product]["unweighted_total"] += p_data["total_score"]
+ product_scores[product]["max_unweighted"] += p_data["max_possible"]
+
+ result = {}
+ for product in all_products:
+ ps = product_scores[product]
+ weighted_pct = safe_divide(ps["weighted_total"], ps["max_weighted"]) * 100
+ unweighted_pct = safe_divide(ps["unweighted_total"], ps["max_unweighted"]) * 100
+ result[product] = {
+ "weighted_score": round(weighted_pct, 1),
+ "unweighted_score": round(unweighted_pct, 1),
+ "weighted_total": round(ps["weighted_total"], 2),
+ "max_weighted": round(ps["max_weighted"], 2),
+ }
+
+ return result
+
+
+def identify_differentiators(comparison: dict[str, Any]) -> list[dict[str, Any]]:
+ """Identify features where our product leads all competitors.
+
+ Args:
+ comparison: Comparison matrix data.
+
+ Returns:
+ List of differentiator features with details.
+ """
+ differentiators = []
+ for entry in comparison["matrix"]:
+ if entry["we_lead"] and entry["our_score"] >= 2:
+ # Calculate gap from nearest competitor
+ competitor_scores = [
+ entry["scores"][c] for c in comparison["competitors"]
+ ]
+ max_competitor = max(competitor_scores) if competitor_scores else 0
+ gap = entry["our_score"] - max_competitor
+
+ differentiators.append({
+ "feature": entry["feature"],
+ "category": entry["category"],
+ "our_score": entry["our_score"],
+ "our_label": FEATURE_LABELS.get(entry["our_score"], "Unknown"),
+ "best_competitor_score": max_competitor,
+ "gap": gap,
+ })
+
+ # Sort by gap size descending
+ differentiators.sort(key=lambda d: d["gap"], reverse=True)
+ return differentiators
+
+
+def identify_vulnerabilities(comparison: dict[str, Any]) -> list[dict[str, Any]]:
+ """Identify features where competitors lead our product.
+
+ Args:
+ comparison: Comparison matrix data.
+
+ Returns:
+ List of vulnerability features with details.
+ """
+ vulnerabilities = []
+ for entry in comparison["matrix"]:
+ if entry["we_trail"]:
+ # Find which competitor leads
+ leader_scores = {
+ p: entry["scores"][p]
+ for p in comparison["competitors"]
+ if entry["scores"][p] == entry["max_score"]
+ }
+ gap = entry["max_score"] - entry["our_score"]
+
+ vulnerabilities.append({
+ "feature": entry["feature"],
+ "category": entry["category"],
+ "our_score": entry["our_score"],
+ "our_label": FEATURE_LABELS.get(entry["our_score"], "Unknown"),
+ "leading_competitors": leader_scores,
+ "gap": gap,
+ })
+
+ # Sort by gap size descending
+ vulnerabilities.sort(key=lambda v: v["gap"], reverse=True)
+ return vulnerabilities
+
+
+def generate_win_themes(
+ differentiators: list[dict[str, Any]],
+ competitive_scores: dict[str, dict[str, Any]],
+ our_product: str,
+) -> list[str]:
+ """Generate win themes based on differentiators and competitive position.
+
+ Args:
+ differentiators: List of differentiator features.
+ competitive_scores: Product competitive scores.
+ our_product: Our product name.
+
+ Returns:
+ List of win theme strings.
+ """
+ themes = []
+
+ # Theme from top differentiators
+ if differentiators:
+ top_diff_categories = list({d["category"] for d in differentiators[:5]})
+ for cat in top_diff_categories[:3]:
+ cat_diffs = [d for d in differentiators if d["category"] == cat]
+ feature_names = [d["feature"] for d in cat_diffs[:3]]
+ themes.append(
+ f"Superior {cat} capabilities: {', '.join(feature_names)}"
+ )
+
+ # Theme from overall competitive position
+ our_score = competitive_scores.get(our_product, {}).get("weighted_score", 0)
+ competitor_scores = [
+ (p, s["weighted_score"])
+ for p, s in competitive_scores.items()
+ if p != our_product
+ ]
+ if competitor_scores:
+ best_competitor_name, best_competitor_score = max(
+ competitor_scores, key=lambda x: x[1]
+ )
+ if our_score > best_competitor_score:
+ themes.append(
+ f"Overall strongest solution ({our_score:.1f}% vs {best_competitor_name} at {best_competitor_score:.1f}%)"
+ )
+
+ # Theme from breadth of coverage
+ strong_diffs = [d for d in differentiators if d["gap"] >= 2]
+ if len(strong_diffs) >= 3:
+ themes.append(
+ f"Clear technical leadership across {len(strong_diffs)} key features with significant competitive gaps"
+ )
+
+ if not themes:
+ themes.append("Competitive parity - emphasize implementation quality, support, and total cost of ownership")
+
+ return themes
+
+
+def analyze_competitive(data: dict[str, Any]) -> dict[str, Any]:
+ """Run the complete competitive analysis pipeline.
+
+ Args:
+ data: Parsed competitive data dictionary.
+
+ Returns:
+ Complete analysis results dictionary.
+ """
+ comparison = build_comparison_matrix(data)
+ competitive_scores = compute_competitive_scores(comparison)
+ differentiators = identify_differentiators(comparison)
+ vulnerabilities = identify_vulnerabilities(comparison)
+ win_themes = generate_win_themes(
+ differentiators, competitive_scores, comparison["our_product"]
+ )
+
+ return {
+ "analysis_info": {
+ "our_product": comparison["our_product"],
+ "competitors": comparison["competitors"],
+ "total_features": len(comparison["matrix"]),
+ "total_categories": len(comparison["category_summaries"]),
+ },
+ "competitive_scores": competitive_scores,
+ "category_breakdown": comparison["category_summaries"],
+ "comparison_matrix": comparison["matrix"],
+ "differentiators": differentiators,
+ "vulnerabilities": vulnerabilities,
+ "win_themes": win_themes,
+ }
+
+
+def format_text(result: dict[str, Any]) -> str:
+ """Format analysis results as human-readable text.
+
+ Args:
+ result: Complete analysis results dictionary.
+
+ Returns:
+ Formatted text string.
+ """
+ lines = []
+ info = result["analysis_info"]
+ all_products = [info["our_product"]] + info["competitors"]
+
+ lines.append("=" * 80)
+ lines.append("COMPETITIVE MATRIX ANALYSIS")
+ lines.append("=" * 80)
+ lines.append(f"Our Product: {info['our_product']}")
+ lines.append(f"Competitors: {', '.join(info['competitors'])}")
+ lines.append(f"Features: {info['total_features']}")
+ lines.append(f"Categories: {info['total_categories']}")
+ lines.append("")
+
+ # Competitive scores
+ lines.append("-" * 80)
+ lines.append("COMPETITIVE SCORES")
+ lines.append("-" * 80)
+ lines.append(f"{'Product':<25} {'Weighted':>10} {'Unweighted':>12}")
+ lines.append("-" * 80)
+
+ # Sort by weighted score descending
+ sorted_scores = sorted(
+ result["competitive_scores"].items(),
+ key=lambda x: x[1]["weighted_score"],
+ reverse=True,
+ )
+ for product, scores in sorted_scores:
+ marker = " <-- US" if product == info["our_product"] else ""
+ lines.append(
+ f"{product:<25} {scores['weighted_score']:>9.1f}% {scores['unweighted_score']:>11.1f}%{marker}"
+ )
+ lines.append("")
+
+ # Feature matrix
+ lines.append("-" * 80)
+ lines.append("FEATURE COMPARISON MATRIX")
+ lines.append("-" * 80)
+
+ # Build header
+ product_cols = " ".join(f"{p[:10]:>10}" for p in all_products)
+ lines.append(f"{'Feature':<30} {product_cols}")
+ lines.append("-" * 80)
+
+ current_category = ""
+ for entry in result["comparison_matrix"]:
+ if entry["category"] != current_category:
+ current_category = entry["category"]
+ cat_data = result["category_breakdown"].get(current_category, {})
+ weight = cat_data.get("weight", 1.0)
+ lines.append(f"\n [{current_category}] (weight: {weight}x)")
+
+ score_cols = " ".join(
+ f"{FEATURE_LABELS.get(entry['scores'].get(p, 0), 'N/A'):>10}"
+ for p in all_products
+ )
+ lead_marker = " *" if entry["we_lead"] else (" !" if entry["we_trail"] else "")
+ feature_display = entry["feature"][:28]
+ lines.append(f" {feature_display:<28} {score_cols}{lead_marker}")
+ lines.append("")
+ lines.append(" * = We lead | ! = We trail")
+ lines.append("")
+
+ # Differentiators
+ diffs = result["differentiators"]
+ if diffs:
+ lines.append("-" * 80)
+ lines.append(f"DIFFERENTIATORS ({len(diffs)} features where we lead)")
+ lines.append("-" * 80)
+ for d in diffs:
+ lines.append(
+ f" + {d['feature']} [{d['category']}] "
+ f"- Us: {d['our_label']} vs Best Competitor: {FEATURE_LABELS.get(d['best_competitor_score'], 'N/A')} "
+ f"(gap: +{d['gap']})"
+ )
+ lines.append("")
+
+ # Vulnerabilities
+ vulns = result["vulnerabilities"]
+ if vulns:
+ lines.append("-" * 80)
+ lines.append(f"VULNERABILITIES ({len(vulns)} features where competitors lead)")
+ lines.append("-" * 80)
+ for v in vulns:
+ leaders = ", ".join(
+ f"{p}: {FEATURE_LABELS.get(s, 'N/A')}"
+ for p, s in v["leading_competitors"].items()
+ )
+ lines.append(
+ f" - {v['feature']} [{v['category']}] "
+ f"- Us: {v['our_label']} vs {leaders} "
+ f"(gap: -{v['gap']})"
+ )
+ lines.append("")
+
+ # Win themes
+ themes = result["win_themes"]
+ lines.append("-" * 80)
+ lines.append("WIN THEMES")
+ lines.append("-" * 80)
+ for i, theme in enumerate(themes, 1):
+ lines.append(f" {i}. {theme}")
+ lines.append("")
+ lines.append("=" * 80)
+
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for the Competitive Matrix Builder."""
+ parser = argparse.ArgumentParser(
+ description="Build competitive feature comparison matrices and positioning analysis.",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=(
+ "Feature Scoring:\n"
+ " Full (3) - Complete feature support\n"
+ " Partial (2) - Partial or limited support\n"
+ " Limited (1) - Minimal or basic support\n"
+ " None (0) - Feature not available\n"
+ "\n"
+ "Example:\n"
+ " python competitive_matrix_builder.py competitive_data.json --format json\n"
+ ),
+ )
+ parser.add_argument(
+ "input_file",
+ help="Path to JSON file containing competitive data",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ dest="output_format",
+ help="Output format: json or text (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ data = load_competitive_data(args.input_file)
+ result = analyze_competitive(data)
+
+ if args.output_format == "json":
+ print(json.dumps(result, indent=2))
+ else:
+ print(format_text(result))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/business-growth/sales-engineer/scripts/poc_planner.py b/skills/business-growth/sales-engineer/scripts/poc_planner.py
new file mode 100644
index 00000000..0ad37451
--- /dev/null
+++ b/skills/business-growth/sales-engineer/scripts/poc_planner.py
@@ -0,0 +1,765 @@
+#!/usr/bin/env python3
+"""POC Planner - Plan proof-of-concept engagements with timeline, resources, and scorecards.
+
+Generates structured POC plans including phased timelines, resource allocation,
+success criteria with measurable metrics, evaluation scorecards, risk identification,
+and go/no-go recommendation frameworks.
+
+Usage:
+ python poc_planner.py poc_data.json
+ python poc_planner.py poc_data.json --format json
+ python poc_planner.py poc_data.json --format text
+"""
+
+import argparse
+import json
+import sys
+from typing import Any
+
+
+# Default phase definitions
+DEFAULT_PHASES = [
+ {
+ "name": "Setup",
+ "duration_weeks": 1,
+ "description": "Environment provisioning, data migration, initial configuration",
+ "activities": [
+ "Provision POC environment",
+ "Configure authentication and access",
+ "Migrate sample data sets",
+ "Set up monitoring and logging",
+ "Conduct kickoff meeting with stakeholders",
+ ],
+ },
+ {
+ "name": "Core Testing",
+ "duration_weeks": 2,
+ "description": "Primary use case validation and integration testing",
+ "activities": [
+ "Execute primary use case scenarios",
+ "Test core integrations",
+ "Validate data flow and transformations",
+ "Conduct mid-point review with stakeholders",
+ "Document findings and adjust test plan",
+ ],
+ },
+ {
+ "name": "Advanced Testing",
+ "duration_weeks": 1,
+ "description": "Edge cases, performance testing, and security validation",
+ "activities": [
+ "Execute edge case scenarios",
+ "Run performance and load tests",
+ "Validate security controls and compliance",
+ "Test disaster recovery and failover",
+ "Test administrative workflows",
+ ],
+ },
+ {
+ "name": "Evaluation",
+ "duration_weeks": 1,
+ "description": "Scorecard completion, stakeholder review, and go/no-go decision",
+ "activities": [
+ "Complete evaluation scorecard",
+ "Compile POC results documentation",
+ "Conduct final stakeholder review",
+ "Present go/no-go recommendation",
+ "Gather lessons learned",
+ ],
+ },
+]
+
+# Evaluation categories with default weights
+DEFAULT_EVAL_CATEGORIES = {
+ "Functionality": {
+ "weight": 0.30,
+ "criteria": [
+ "Core feature completeness",
+ "Use case coverage",
+ "Customization flexibility",
+ "Workflow automation",
+ ],
+ },
+ "Performance": {
+ "weight": 0.20,
+ "criteria": [
+ "Response time under load",
+ "Throughput capacity",
+ "Scalability characteristics",
+ "Resource utilization",
+ ],
+ },
+ "Integration": {
+ "weight": 0.20,
+ "criteria": [
+ "API completeness and documentation",
+ "Data migration ease",
+ "Third-party connector availability",
+ "Authentication/SSO integration",
+ ],
+ },
+ "Usability": {
+ "weight": 0.15,
+ "criteria": [
+ "User interface intuitiveness",
+ "Learning curve assessment",
+ "Documentation quality",
+ "Admin console functionality",
+ ],
+ },
+ "Support": {
+ "weight": 0.15,
+ "criteria": [
+ "Technical support responsiveness",
+ "Knowledge base quality",
+ "Training resources availability",
+ "Community and ecosystem",
+ ],
+ },
+}
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def load_poc_data(filepath: str) -> dict[str, Any]:
+ """Load and validate POC data from a JSON file.
+
+ Args:
+ filepath: Path to the JSON file containing POC data.
+
+ Returns:
+ Parsed POC data dictionary.
+
+ Raises:
+ SystemExit: If the file cannot be read or parsed.
+ """
+ try:
+ with open(filepath, "r", encoding="utf-8") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {filepath}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {filepath}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ if "poc_name" not in data:
+ print("Error: JSON must contain 'poc_name' field.", file=sys.stderr)
+ sys.exit(1)
+
+ return data
+
+
+def estimate_resources(data: dict[str, Any], phases: list[dict[str, Any]]) -> dict[str, Any]:
+ """Estimate resource requirements for the POC.
+
+ Args:
+ data: POC data with scope and requirements.
+ phases: List of phase definitions.
+
+ Returns:
+ Resource allocation dictionary.
+ """
+ total_weeks = sum(p["duration_weeks"] for p in phases)
+ complexity = data.get("complexity", "medium").lower()
+ scope_items = data.get("scope_items", [])
+ num_integrations = data.get("num_integrations", 0)
+
+ # Base SE hours per week by complexity
+ se_hours_per_week = {"low": 15, "medium": 25, "high": 35}.get(complexity, 25)
+
+ # Engineering support hours
+ eng_base = {"low": 5, "medium": 10, "high": 20}.get(complexity, 10)
+ eng_integration_hours = num_integrations * 8
+
+ # Customer resource hours
+ customer_hours_per_week = {"low": 5, "medium": 8, "high": 12}.get(complexity, 8)
+
+ se_total = se_hours_per_week * total_weeks
+ eng_total = (eng_base * total_weeks) + eng_integration_hours
+ customer_total = customer_hours_per_week * total_weeks
+
+ # Phase-level breakdown
+ phase_resources = []
+ for phase in phases:
+ weeks = phase["duration_weeks"]
+ # Setup phase has higher SE and eng effort
+ se_multiplier = 1.3 if phase["name"] == "Setup" else (
+ 1.0 if phase["name"] in ("Core Testing", "Advanced Testing") else 0.7
+ )
+ eng_multiplier = 1.5 if phase["name"] == "Setup" else (
+ 1.0 if phase["name"] == "Core Testing" else (
+ 1.2 if phase["name"] == "Advanced Testing" else 0.5
+ )
+ )
+
+ phase_resources.append({
+ "phase": phase["name"],
+ "duration_weeks": weeks,
+ "se_hours": round(se_hours_per_week * weeks * se_multiplier),
+ "engineering_hours": round(eng_base * weeks * eng_multiplier),
+ "customer_hours": round(customer_hours_per_week * weeks),
+ })
+
+ return {
+ "total_duration_weeks": total_weeks,
+ "complexity": complexity,
+ "totals": {
+ "se_hours": se_total,
+ "engineering_hours": eng_total,
+ "customer_hours": customer_total,
+ "total_hours": se_total + eng_total + customer_total,
+ },
+ "phase_breakdown": phase_resources,
+ "additional_resources": {
+ "integration_hours": eng_integration_hours,
+ "num_integrations": num_integrations,
+ },
+ }
+
+
+def generate_success_criteria(data: dict[str, Any]) -> list[dict[str, Any]]:
+ """Generate success criteria based on POC scope and requirements.
+
+ Args:
+ data: POC data with scope and requirements.
+
+ Returns:
+ List of success criteria with metrics.
+ """
+ criteria = []
+
+ # Custom criteria from input
+ custom_criteria = data.get("success_criteria", [])
+ for cc in custom_criteria:
+ criteria.append({
+ "criterion": cc.get("criterion", "Unnamed criterion"),
+ "metric": cc.get("metric", "Pass/Fail"),
+ "target": cc.get("target", "Met"),
+ "category": cc.get("category", "Functionality"),
+ "priority": cc.get("priority", "must-have"),
+ })
+
+ # Auto-generated criteria based on scope
+ scope_items = data.get("scope_items", [])
+ for item in scope_items:
+ if isinstance(item, str):
+ criteria.append({
+ "criterion": f"Validate: {item}",
+ "metric": "Pass/Fail",
+ "target": "Pass",
+ "category": "Functionality",
+ "priority": "must-have",
+ })
+ elif isinstance(item, dict):
+ criteria.append({
+ "criterion": item.get("name", "Unnamed scope item"),
+ "metric": item.get("metric", "Pass/Fail"),
+ "target": item.get("target", "Pass"),
+ "category": item.get("category", "Functionality"),
+ "priority": item.get("priority", "must-have"),
+ })
+
+ # Default criteria if none provided
+ if not criteria:
+ criteria = [
+ {
+ "criterion": "Core use case validation",
+ "metric": "Percentage of use cases successfully demonstrated",
+ "target": ">90%",
+ "category": "Functionality",
+ "priority": "must-have",
+ },
+ {
+ "criterion": "Performance under expected load",
+ "metric": "Response time at target concurrency",
+ "target": "<2 seconds p95",
+ "category": "Performance",
+ "priority": "must-have",
+ },
+ {
+ "criterion": "Integration with existing systems",
+ "metric": "Number of integrations successfully tested",
+ "target": "All planned integrations",
+ "category": "Integration",
+ "priority": "must-have",
+ },
+ {
+ "criterion": "User acceptance",
+ "metric": "Stakeholder satisfaction score",
+ "target": ">4.0/5.0",
+ "category": "Usability",
+ "priority": "should-have",
+ },
+ ]
+
+ return criteria
+
+
+def generate_evaluation_scorecard(data: dict[str, Any]) -> dict[str, Any]:
+ """Generate the POC evaluation scorecard template.
+
+ Args:
+ data: POC data.
+
+ Returns:
+ Evaluation scorecard structure.
+ """
+ custom_categories = data.get("evaluation_categories", {})
+
+ # Merge custom categories with defaults
+ categories = {}
+ for cat_name, cat_data in DEFAULT_EVAL_CATEGORIES.items():
+ if cat_name in custom_categories:
+ custom = custom_categories[cat_name]
+ categories[cat_name] = {
+ "weight": custom.get("weight", cat_data["weight"]),
+ "criteria": custom.get("criteria", cat_data["criteria"]),
+ "score": None,
+ "notes": "",
+ }
+ else:
+ categories[cat_name] = {
+ "weight": cat_data["weight"],
+ "criteria": cat_data["criteria"],
+ "score": None,
+ "notes": "",
+ }
+
+ # Normalize weights to sum to 1.0
+ total_weight = sum(c["weight"] for c in categories.values())
+ if total_weight > 0 and abs(total_weight - 1.0) > 0.01:
+ for cat in categories.values():
+ cat["weight"] = round(safe_divide(cat["weight"], total_weight), 2)
+
+ return {
+ "scoring_scale": {
+ "5": "Exceeds requirements - superior capability",
+ "4": "Meets requirements - full capability",
+ "3": "Partially meets - acceptable with minor gaps",
+ "2": "Below expectations - significant gaps",
+ "1": "Does not meet - critical gaps",
+ },
+ "categories": categories,
+ "pass_threshold": 3.5,
+ "strong_pass_threshold": 4.0,
+ }
+
+
+def identify_risks(data: dict[str, Any], resources: dict[str, Any]) -> list[dict[str, Any]]:
+ """Identify POC risks and generate mitigation strategies.
+
+ Args:
+ data: POC data.
+ resources: Resource allocation data.
+
+ Returns:
+ List of risk entries with probability, impact, and mitigation.
+ """
+ risks = []
+ complexity = data.get("complexity", "medium").lower()
+ num_integrations = data.get("num_integrations", 0)
+ total_weeks = resources["total_duration_weeks"]
+ stakeholders = data.get("stakeholders", [])
+
+ # Timeline risk
+ if total_weeks > 6:
+ risks.append({
+ "risk": "Extended timeline may lose stakeholder attention",
+ "probability": "high",
+ "impact": "high",
+ "mitigation": "Schedule weekly progress checkpoints; deliver early wins in week 2",
+ "category": "Timeline",
+ })
+ elif total_weeks >= 4:
+ risks.append({
+ "risk": "Timeline may slip due to unforeseen technical issues",
+ "probability": "medium",
+ "impact": "medium",
+ "mitigation": "Build 20% buffer into each phase; identify critical path early",
+ "category": "Timeline",
+ })
+
+ # Integration risks
+ if num_integrations > 3:
+ risks.append({
+ "risk": "Multiple integrations increase complexity and failure points",
+ "probability": "high",
+ "impact": "high",
+ "mitigation": "Prioritize integrations by business value; test incrementally; have fallback demo data",
+ "category": "Technical",
+ })
+ elif num_integrations > 0:
+ risks.append({
+ "risk": "Integration dependencies may cause delays",
+ "probability": "medium",
+ "impact": "medium",
+ "mitigation": "Engage customer IT early; confirm API access and credentials in setup phase",
+ "category": "Technical",
+ })
+
+ # Data risks
+ risks.append({
+ "risk": "Customer data quality or availability issues",
+ "probability": "medium",
+ "impact": "high",
+ "mitigation": "Request sample data early; prepare synthetic data as fallback; validate data format in setup",
+ "category": "Data",
+ })
+
+ # Stakeholder risks
+ if len(stakeholders) > 5:
+ risks.append({
+ "risk": "Too many stakeholders may slow decision-making",
+ "probability": "medium",
+ "impact": "medium",
+ "mitigation": "Identify decision-maker and champion; schedule focused reviews per stakeholder group",
+ "category": "Stakeholder",
+ })
+
+ if not stakeholders:
+ risks.append({
+ "risk": "Undefined stakeholder map may lead to misaligned evaluation",
+ "probability": "high",
+ "impact": "high",
+ "mitigation": "Confirm stakeholder list, roles, and evaluation criteria before setup phase",
+ "category": "Stakeholder",
+ })
+
+ # Resource risks
+ if complexity == "high":
+ risks.append({
+ "risk": "High complexity may require additional engineering resources",
+ "probability": "medium",
+ "impact": "high",
+ "mitigation": "Secure engineering commitment upfront; identify escalation path for blockers",
+ "category": "Resource",
+ })
+
+ # Competitive risk
+ risks.append({
+ "risk": "Competitor POC running in parallel may shift evaluation criteria",
+ "probability": "medium",
+ "impact": "medium",
+ "mitigation": "Stay close to champion; align success criteria early; differentiate on unique strengths",
+ "category": "Competitive",
+ })
+
+ return risks
+
+
+def generate_go_no_go_framework(data: dict[str, Any]) -> dict[str, Any]:
+ """Generate the go/no-go decision framework.
+
+ Args:
+ data: POC data.
+
+ Returns:
+ Go/no-go framework with criteria and thresholds.
+ """
+ return {
+ "decision_criteria": [
+ {
+ "criterion": "Overall scorecard score",
+ "go_threshold": ">=3.5 weighted average",
+ "no_go_threshold": "<3.0 weighted average",
+ "conditional_range": "3.0 - 3.5",
+ },
+ {
+ "criterion": "Must-have success criteria met",
+ "go_threshold": "100% of must-have criteria pass",
+ "no_go_threshold": "<80% of must-have criteria pass",
+ "conditional_range": "80-99% with mitigation plan",
+ },
+ {
+ "criterion": "Stakeholder satisfaction",
+ "go_threshold": "Champion and decision-maker both positive",
+ "no_go_threshold": "Decision-maker negative",
+ "conditional_range": "Mixed signals - needs follow-up",
+ },
+ {
+ "criterion": "Technical blockers",
+ "go_threshold": "No unresolved critical blockers",
+ "no_go_threshold": ">2 unresolved critical blockers",
+ "conditional_range": "1-2 blockers with clear resolution path",
+ },
+ ],
+ "recommendation_logic": {
+ "GO": "All criteria meet go thresholds, or majority go with no no-go triggers",
+ "CONDITIONAL_GO": "Some criteria in conditional range, but no no-go triggers and clear resolution plan",
+ "NO_GO": "Any criterion triggers no-go threshold without clear mitigation",
+ },
+ }
+
+
+def plan_poc(data: dict[str, Any]) -> dict[str, Any]:
+ """Run the complete POC planning pipeline.
+
+ Args:
+ data: Parsed POC data dictionary.
+
+ Returns:
+ Complete POC plan dictionary.
+ """
+ poc_info = {
+ "poc_name": data.get("poc_name", "Unnamed POC"),
+ "customer": data.get("customer", "Unknown Customer"),
+ "opportunity_value": data.get("opportunity_value", "Not specified"),
+ "complexity": data.get("complexity", "medium"),
+ "start_date": data.get("start_date", "TBD"),
+ "champion": data.get("champion", "Not identified"),
+ "decision_maker": data.get("decision_maker", "Not identified"),
+ }
+
+ # Use custom phases if provided, otherwise defaults
+ phases = data.get("phases", DEFAULT_PHASES)
+
+ # Resource estimation
+ resources = estimate_resources(data, phases)
+
+ # Success criteria
+ success_criteria = generate_success_criteria(data)
+
+ # Evaluation scorecard
+ scorecard = generate_evaluation_scorecard(data)
+
+ # Risk identification
+ risks = identify_risks(data, resources)
+
+ # Go/No-Go framework
+ go_no_go = generate_go_no_go_framework(data)
+
+ # Timeline with phase details
+ timeline = []
+ current_week = 1
+ for phase in phases:
+ end_week = current_week + phase["duration_weeks"] - 1
+ timeline.append({
+ "phase": phase["name"],
+ "start_week": current_week,
+ "end_week": end_week,
+ "duration_weeks": phase["duration_weeks"],
+ "description": phase["description"],
+ "activities": phase["activities"],
+ })
+ current_week = end_week + 1
+
+ # Stakeholder plan
+ stakeholders = data.get("stakeholders", [])
+ stakeholder_plan = []
+ for s in stakeholders:
+ if isinstance(s, str):
+ stakeholder_plan.append({
+ "name": s,
+ "role": "Evaluator",
+ "engagement": "Weekly updates, phase reviews",
+ })
+ elif isinstance(s, dict):
+ stakeholder_plan.append({
+ "name": s.get("name", "Unknown"),
+ "role": s.get("role", "Evaluator"),
+ "engagement": s.get("engagement", "Weekly updates, phase reviews"),
+ })
+
+ return {
+ "poc_info": poc_info,
+ "timeline": timeline,
+ "resource_allocation": resources,
+ "success_criteria": success_criteria,
+ "evaluation_scorecard": scorecard,
+ "risk_register": risks,
+ "go_no_go_framework": go_no_go,
+ "stakeholder_plan": stakeholder_plan,
+ }
+
+
+def format_text(result: dict[str, Any]) -> str:
+ """Format POC plan as human-readable text.
+
+ Args:
+ result: Complete POC plan dictionary.
+
+ Returns:
+ Formatted text string.
+ """
+ lines = []
+ info = result["poc_info"]
+
+ lines.append("=" * 70)
+ lines.append("PROOF OF CONCEPT PLAN")
+ lines.append("=" * 70)
+ lines.append(f"POC Name: {info['poc_name']}")
+ lines.append(f"Customer: {info['customer']}")
+ lines.append(f"Opportunity Value: {info['opportunity_value']}")
+ lines.append(f"Complexity: {info['complexity'].upper()}")
+ lines.append(f"Start Date: {info['start_date']}")
+ lines.append(f"Champion: {info['champion']}")
+ lines.append(f"Decision Maker: {info['decision_maker']}")
+ lines.append("")
+
+ # Timeline
+ lines.append("-" * 70)
+ lines.append("TIMELINE")
+ lines.append("-" * 70)
+ for phase in result["timeline"]:
+ week_range = (
+ f"Week {phase['start_week']}"
+ if phase["start_week"] == phase["end_week"]
+ else f"Weeks {phase['start_week']}-{phase['end_week']}"
+ )
+ lines.append(f"\n Phase: {phase['phase']} ({week_range})")
+ lines.append(f" {phase['description']}")
+ lines.append(" Activities:")
+ for activity in phase["activities"]:
+ lines.append(f" - {activity}")
+ lines.append("")
+
+ # Resource allocation
+ res = result["resource_allocation"]
+ lines.append("-" * 70)
+ lines.append("RESOURCE ALLOCATION")
+ lines.append("-" * 70)
+ lines.append(f"Total Duration: {res['total_duration_weeks']} weeks")
+ lines.append(f"Complexity: {res['complexity'].upper()}")
+ lines.append("")
+ lines.append(" Totals:")
+ lines.append(f" SE Hours: {res['totals']['se_hours']}")
+ lines.append(f" Engineering Hours: {res['totals']['engineering_hours']}")
+ lines.append(f" Customer Hours: {res['totals']['customer_hours']}")
+ lines.append(f" Total Hours: {res['totals']['total_hours']}")
+ lines.append("")
+ lines.append(" Phase Breakdown:")
+ lines.append(f" {'Phase':<20} {'Weeks':>5} {'SE':>6} {'Eng':>6} {'Cust':>6}")
+ lines.append(" " + "-" * 45)
+ for pr in res["phase_breakdown"]:
+ lines.append(
+ f" {pr['phase']:<20} {pr['duration_weeks']:>5} "
+ f"{pr['se_hours']:>5}h {pr['engineering_hours']:>5}h {pr['customer_hours']:>5}h"
+ )
+ lines.append("")
+
+ # Success criteria
+ criteria = result["success_criteria"]
+ lines.append("-" * 70)
+ lines.append("SUCCESS CRITERIA")
+ lines.append("-" * 70)
+ for i, sc in enumerate(criteria, 1):
+ priority_marker = "[MUST]" if sc["priority"] == "must-have" else (
+ "[SHOULD]" if sc["priority"] == "should-have" else "[NICE]"
+ )
+ lines.append(f" {i}. {priority_marker} {sc['criterion']}")
+ lines.append(f" Metric: {sc['metric']}")
+ lines.append(f" Target: {sc['target']}")
+ lines.append(f" Category: {sc['category']}")
+ lines.append("")
+
+ # Evaluation scorecard
+ scorecard = result["evaluation_scorecard"]
+ lines.append("-" * 70)
+ lines.append("EVALUATION SCORECARD")
+ lines.append("-" * 70)
+ lines.append(f" Pass Threshold: {scorecard['pass_threshold']}/5.0")
+ lines.append(f" Strong Pass Threshold: {scorecard['strong_pass_threshold']}/5.0")
+ lines.append("")
+ lines.append(" Scoring Scale:")
+ for score, desc in scorecard["scoring_scale"].items():
+ lines.append(f" {score} = {desc}")
+ lines.append("")
+ lines.append(" Categories:")
+ for cat_name, cat_data in scorecard["categories"].items():
+ lines.append(f"\n {cat_name} (weight: {cat_data['weight']:.0%})")
+ for criterion in cat_data["criteria"]:
+ lines.append(f" [ ] {criterion}")
+ lines.append("")
+
+ # Risk register
+ risks = result["risk_register"]
+ lines.append("-" * 70)
+ lines.append("RISK REGISTER")
+ lines.append("-" * 70)
+ for risk in risks:
+ lines.append(f" [{risk['impact'].upper()}] {risk['risk']}")
+ lines.append(f" Probability: {risk['probability']} | Impact: {risk['impact']}")
+ lines.append(f" Category: {risk['category']}")
+ lines.append(f" Mitigation: {risk['mitigation']}")
+ lines.append("")
+
+ # Go/No-Go framework
+ framework = result["go_no_go_framework"]
+ lines.append("-" * 70)
+ lines.append("GO / NO-GO DECISION FRAMEWORK")
+ lines.append("-" * 70)
+ for dc in framework["decision_criteria"]:
+ lines.append(f" {dc['criterion']}:")
+ lines.append(f" GO: {dc['go_threshold']}")
+ lines.append(f" CONDITIONAL: {dc['conditional_range']}")
+ lines.append(f" NO-GO: {dc['no_go_threshold']}")
+ lines.append("")
+
+ lines.append(" Recommendation Logic:")
+ for decision, logic in framework["recommendation_logic"].items():
+ lines.append(f" {decision}: {logic}")
+ lines.append("")
+
+ # Stakeholder plan
+ stakeholders = result["stakeholder_plan"]
+ if stakeholders:
+ lines.append("-" * 70)
+ lines.append("STAKEHOLDER PLAN")
+ lines.append("-" * 70)
+ for s in stakeholders:
+ lines.append(f" {s['name']} ({s['role']})")
+ lines.append(f" Engagement: {s['engagement']}")
+ lines.append("")
+
+ lines.append("=" * 70)
+
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for the POC Planner."""
+ parser = argparse.ArgumentParser(
+ description="Plan proof-of-concept engagements with timeline, resources, and evaluation scorecards.",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=(
+ "Default Phases:\n"
+ " Week 1: Setup - Environment provisioning, configuration\n"
+ " Weeks 2-3: Core Testing - Primary use cases, integrations\n"
+ " Week 4: Advanced Testing - Edge cases, performance, security\n"
+ " Week 5: Evaluation - Scorecard, stakeholder review, go/no-go\n"
+ "\n"
+ "Example:\n"
+ " python poc_planner.py poc_data.json --format json\n"
+ ),
+ )
+ parser.add_argument(
+ "input_file",
+ help="Path to JSON file containing POC scope and requirements",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ dest="output_format",
+ help="Output format: json or text (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ data = load_poc_data(args.input_file)
+ result = plan_poc(data)
+
+ if args.output_format == "json":
+ print(json.dumps(result, indent=2))
+ else:
+ print(format_text(result))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/business-growth/sales-engineer/scripts/rfp_response_analyzer.py b/skills/business-growth/sales-engineer/scripts/rfp_response_analyzer.py
new file mode 100644
index 00000000..02230dcb
--- /dev/null
+++ b/skills/business-growth/sales-engineer/scripts/rfp_response_analyzer.py
@@ -0,0 +1,557 @@
+#!/usr/bin/env python3
+"""RFP/RFI Response Analyzer - Score coverage, identify gaps, and recommend bid/no-bid.
+
+Parses RFP/RFI requirements and scores coverage using Full/Partial/Planned/Gap
+categories. Generates weighted coverage scores, gap analysis with mitigation
+strategies, effort estimation, and bid/no-bid recommendations.
+
+Usage:
+ python rfp_response_analyzer.py rfp_data.json
+ python rfp_response_analyzer.py rfp_data.json --format json
+ python rfp_response_analyzer.py rfp_data.json --format text
+"""
+
+import argparse
+import json
+import sys
+from typing import Any
+
+
+# Coverage status to score mapping
+COVERAGE_SCORES: dict[str, float] = {
+ "full": 1.0,
+ "partial": 0.5,
+ "planned": 0.25,
+ "gap": 0.0,
+}
+
+# Priority to weight mapping
+PRIORITY_WEIGHTS: dict[str, float] = {
+ "must-have": 3.0,
+ "should-have": 2.0,
+ "nice-to-have": 1.0,
+}
+
+# Bid thresholds
+BID_THRESHOLD = 0.70
+CONDITIONAL_THRESHOLD = 0.50
+MAX_MUST_HAVE_GAPS_FOR_BID = 3
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def load_rfp_data(filepath: str) -> dict[str, Any]:
+ """Load and validate RFP data from a JSON file.
+
+ Args:
+ filepath: Path to the JSON file containing RFP data.
+
+ Returns:
+ Parsed RFP data dictionary.
+
+ Raises:
+ SystemExit: If the file cannot be read or parsed.
+ """
+ try:
+ with open(filepath, "r", encoding="utf-8") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {filepath}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {filepath}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ if "requirements" not in data:
+ print("Error: JSON must contain a 'requirements' array.", file=sys.stderr)
+ sys.exit(1)
+
+ return data
+
+
+def analyze_requirement(req: dict[str, Any]) -> dict[str, Any]:
+ """Analyze a single requirement and compute its score.
+
+ Args:
+ req: Requirement dictionary with category, priority, coverage_status, etc.
+
+ Returns:
+ Enriched requirement with computed score and weight.
+ """
+ coverage_status = req.get("coverage_status", "gap").lower()
+ priority = req.get("priority", "nice-to-have").lower()
+
+ coverage_score = COVERAGE_SCORES.get(coverage_status, 0.0)
+ weight = PRIORITY_WEIGHTS.get(priority, 1.0)
+ weighted_score = coverage_score * weight
+ max_weighted = weight
+
+ effort_hours = req.get("effort_hours", 0)
+
+ result = {
+ "id": req.get("id", "unknown"),
+ "requirement": req.get("requirement", "Unnamed requirement"),
+ "category": req.get("category", "Uncategorized"),
+ "priority": priority,
+ "coverage_status": coverage_status,
+ "coverage_score": coverage_score,
+ "weight": weight,
+ "weighted_score": weighted_score,
+ "max_weighted": max_weighted,
+ "effort_hours": effort_hours,
+ "notes": req.get("notes", ""),
+ "mitigation": req.get("mitigation", ""),
+ }
+
+ return result
+
+
+def generate_gap_analysis(analyzed_reqs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """Generate gap analysis for requirements not fully covered.
+
+ Args:
+ analyzed_reqs: List of analyzed requirement dictionaries.
+
+ Returns:
+ List of gap entries with mitigation strategies.
+ """
+ gaps = []
+ for req in analyzed_reqs:
+ if req["coverage_status"] in ("gap", "partial", "planned"):
+ severity = "critical" if req["priority"] == "must-have" else (
+ "high" if req["priority"] == "should-have" else "low"
+ )
+
+ mitigation = req["mitigation"]
+ if not mitigation:
+ if req["coverage_status"] == "partial":
+ mitigation = "Enhance existing capability to achieve full coverage"
+ elif req["coverage_status"] == "planned":
+ mitigation = "Communicate roadmap timeline and interim workaround"
+ else:
+ mitigation = "Evaluate build vs. partner vs. no-bid for this requirement"
+
+ gaps.append({
+ "id": req["id"],
+ "requirement": req["requirement"],
+ "category": req["category"],
+ "priority": req["priority"],
+ "coverage_status": req["coverage_status"],
+ "severity": severity,
+ "effort_hours": req["effort_hours"],
+ "mitigation": mitigation,
+ })
+
+ # Sort by severity: critical > high > low
+ severity_order = {"critical": 0, "high": 1, "low": 2}
+ gaps.sort(key=lambda g: severity_order.get(g["severity"], 3))
+
+ return gaps
+
+
+def compute_category_scores(analyzed_reqs: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+ """Compute coverage scores grouped by requirement category.
+
+ Args:
+ analyzed_reqs: List of analyzed requirement dictionaries.
+
+ Returns:
+ Dictionary of category names to score summaries.
+ """
+ categories: dict[str, dict[str, float]] = {}
+
+ for req in analyzed_reqs:
+ cat = req["category"]
+ if cat not in categories:
+ categories[cat] = {
+ "weighted_score": 0.0,
+ "max_weighted": 0.0,
+ "count": 0,
+ "full_count": 0,
+ "partial_count": 0,
+ "planned_count": 0,
+ "gap_count": 0,
+ "effort_hours": 0,
+ }
+
+ categories[cat]["weighted_score"] += req["weighted_score"]
+ categories[cat]["max_weighted"] += req["max_weighted"]
+ categories[cat]["count"] += 1
+ categories[cat]["effort_hours"] += req["effort_hours"]
+
+ status_key = f"{req['coverage_status']}_count"
+ if status_key in categories[cat]:
+ categories[cat][status_key] += 1
+
+ result = {}
+ for cat, scores in categories.items():
+ coverage_pct = safe_divide(scores["weighted_score"], scores["max_weighted"]) * 100
+ result[cat] = {
+ "coverage_percentage": round(coverage_pct, 1),
+ "requirements_count": int(scores["count"]),
+ "full": int(scores["full_count"]),
+ "partial": int(scores["partial_count"]),
+ "planned": int(scores["planned_count"]),
+ "gap": int(scores["gap_count"]),
+ "effort_hours": int(scores["effort_hours"]),
+ }
+
+ return result
+
+
+def determine_bid_recommendation(
+ overall_coverage: float,
+ must_have_gaps: int,
+ strategic_value: str,
+) -> dict[str, Any]:
+ """Determine bid/no-bid recommendation based on coverage and gaps.
+
+ Args:
+ overall_coverage: Overall weighted coverage percentage (0-100).
+ must_have_gaps: Number of must-have requirements with gap status.
+ strategic_value: Strategic value assessment (high, medium, low).
+
+ Returns:
+ Recommendation dictionary with decision and rationale.
+ """
+ coverage_ratio = overall_coverage / 100.0
+ reasons = []
+
+ # Primary decision logic
+ if coverage_ratio >= BID_THRESHOLD and must_have_gaps <= MAX_MUST_HAVE_GAPS_FOR_BID:
+ decision = "BID"
+ reasons.append(f"Coverage score {overall_coverage:.1f}% exceeds {BID_THRESHOLD*100:.0f}% threshold")
+ if must_have_gaps > 0:
+ reasons.append(f"{must_have_gaps} must-have gap(s) within acceptable range (max {MAX_MUST_HAVE_GAPS_FOR_BID})")
+ elif coverage_ratio >= CONDITIONAL_THRESHOLD or (
+ must_have_gaps <= MAX_MUST_HAVE_GAPS_FOR_BID and coverage_ratio >= 0.4
+ ):
+ decision = "CONDITIONAL BID"
+ reasons.append(f"Coverage score {overall_coverage:.1f}% in conditional range ({CONDITIONAL_THRESHOLD*100:.0f}%-{BID_THRESHOLD*100:.0f}%)")
+ if must_have_gaps > 0:
+ reasons.append(f"{must_have_gaps} must-have gap(s) require mitigation plan")
+ else:
+ decision = "NO-BID"
+ if coverage_ratio < CONDITIONAL_THRESHOLD:
+ reasons.append(f"Coverage score {overall_coverage:.1f}% below {CONDITIONAL_THRESHOLD*100:.0f}% minimum")
+ if must_have_gaps > MAX_MUST_HAVE_GAPS_FOR_BID:
+ reasons.append(f"{must_have_gaps} must-have gaps exceed maximum of {MAX_MUST_HAVE_GAPS_FOR_BID}")
+
+ # Strategic value adjustment
+ if strategic_value.lower() == "high" and decision == "CONDITIONAL BID":
+ reasons.append("High strategic value supports pursuing despite coverage gaps")
+ elif strategic_value.lower() == "low" and decision == "CONDITIONAL BID":
+ decision = "NO-BID"
+ reasons.append("Low strategic value does not justify investment for conditional coverage")
+
+ confidence = "high" if coverage_ratio >= 0.80 else (
+ "medium" if coverage_ratio >= 0.60 else "low"
+ )
+
+ return {
+ "decision": decision,
+ "confidence": confidence,
+ "overall_coverage_percentage": round(overall_coverage, 1),
+ "must_have_gaps": must_have_gaps,
+ "strategic_value": strategic_value,
+ "reasons": reasons,
+ }
+
+
+def generate_risk_assessment(
+ analyzed_reqs: list[dict[str, Any]],
+ gaps: list[dict[str, Any]],
+) -> list[dict[str, str]]:
+ """Generate risk assessment based on gaps and coverage patterns.
+
+ Args:
+ analyzed_reqs: List of analyzed requirement dictionaries.
+ gaps: List of gap analysis entries.
+
+ Returns:
+ List of risk entries with impact and mitigation.
+ """
+ risks = []
+
+ critical_gaps = [g for g in gaps if g["severity"] == "critical"]
+ if critical_gaps:
+ risks.append({
+ "risk": "Critical requirement gaps",
+ "impact": "high",
+ "description": f"{len(critical_gaps)} must-have requirements not fully met",
+ "mitigation": "Prioritize engineering effort or partner integration for gap closure",
+ })
+
+ total_effort = sum(r["effort_hours"] for r in analyzed_reqs if r["coverage_status"] != "full")
+ if total_effort > 200:
+ risks.append({
+ "risk": "High customization effort",
+ "impact": "high",
+ "description": f"{total_effort} hours estimated for non-full requirements",
+ "mitigation": "Evaluate resource availability and timeline feasibility before committing",
+ })
+ elif total_effort > 80:
+ risks.append({
+ "risk": "Moderate customization effort",
+ "impact": "medium",
+ "description": f"{total_effort} hours estimated for non-full requirements",
+ "mitigation": "Phase implementation and set clear expectations on delivery timeline",
+ })
+
+ planned_count = sum(1 for r in analyzed_reqs if r["coverage_status"] == "planned")
+ if planned_count > 3:
+ risks.append({
+ "risk": "Roadmap dependency",
+ "impact": "medium",
+ "description": f"{planned_count} requirements depend on planned product features",
+ "mitigation": "Confirm roadmap timelines with product team; include contractual commitments if needed",
+ })
+
+ partial_count = sum(1 for r in analyzed_reqs if r["coverage_status"] == "partial")
+ if partial_count > 5:
+ risks.append({
+ "risk": "Workaround complexity",
+ "impact": "medium",
+ "description": f"{partial_count} requirements need workarounds or configuration",
+ "mitigation": "Document workarounds clearly; plan for native support in future releases",
+ })
+
+ if not risks:
+ risks.append({
+ "risk": "No significant risks identified",
+ "impact": "low",
+ "description": "Strong coverage across all requirement categories",
+ "mitigation": "Maintain standard engagement process",
+ })
+
+ return risks
+
+
+def analyze_rfp(data: dict[str, Any]) -> dict[str, Any]:
+ """Run the complete RFP analysis pipeline.
+
+ Args:
+ data: Parsed RFP data with requirements array.
+
+ Returns:
+ Complete analysis results dictionary.
+ """
+ rfp_info = {
+ "rfp_name": data.get("rfp_name", "Unnamed RFP"),
+ "customer": data.get("customer", "Unknown Customer"),
+ "due_date": data.get("due_date", "Not specified"),
+ "strategic_value": data.get("strategic_value", "medium"),
+ "deal_value": data.get("deal_value", "Not specified"),
+ }
+
+ # Analyze each requirement
+ analyzed_reqs = [analyze_requirement(req) for req in data["requirements"]]
+
+ # Compute overall scores
+ total_weighted = sum(r["weighted_score"] for r in analyzed_reqs)
+ total_max = sum(r["max_weighted"] for r in analyzed_reqs)
+ overall_coverage = safe_divide(total_weighted, total_max) * 100
+
+ # Coverage summary
+ total_count = len(analyzed_reqs)
+ full_count = sum(1 for r in analyzed_reqs if r["coverage_status"] == "full")
+ partial_count = sum(1 for r in analyzed_reqs if r["coverage_status"] == "partial")
+ planned_count = sum(1 for r in analyzed_reqs if r["coverage_status"] == "planned")
+ gap_count = sum(1 for r in analyzed_reqs if r["coverage_status"] == "gap")
+
+ # Must-have gap count
+ must_have_gaps = sum(
+ 1 for r in analyzed_reqs
+ if r["priority"] == "must-have" and r["coverage_status"] == "gap"
+ )
+
+ # Category breakdown
+ category_scores = compute_category_scores(analyzed_reqs)
+
+ # Gap analysis
+ gaps = generate_gap_analysis(analyzed_reqs)
+
+ # Bid recommendation
+ bid_recommendation = determine_bid_recommendation(
+ overall_coverage,
+ must_have_gaps,
+ rfp_info["strategic_value"],
+ )
+
+ # Risk assessment
+ risks = generate_risk_assessment(analyzed_reqs, gaps)
+
+ # Effort summary
+ total_effort = sum(r["effort_hours"] for r in analyzed_reqs)
+ gap_effort = sum(r["effort_hours"] for r in analyzed_reqs if r["coverage_status"] != "full")
+
+ return {
+ "rfp_info": rfp_info,
+ "coverage_summary": {
+ "overall_coverage_percentage": round(overall_coverage, 1),
+ "total_requirements": total_count,
+ "full": full_count,
+ "partial": partial_count,
+ "planned": planned_count,
+ "gap": gap_count,
+ "must_have_gaps": must_have_gaps,
+ },
+ "category_scores": category_scores,
+ "bid_recommendation": bid_recommendation,
+ "gap_analysis": gaps,
+ "risk_assessment": risks,
+ "effort_estimate": {
+ "total_hours": total_effort,
+ "gap_closure_hours": gap_effort,
+ "full_coverage_hours": total_effort - gap_effort,
+ },
+ "requirements_detail": analyzed_reqs,
+ }
+
+
+def format_text(result: dict[str, Any]) -> str:
+ """Format analysis results as human-readable text.
+
+ Args:
+ result: Complete analysis results dictionary.
+
+ Returns:
+ Formatted text string.
+ """
+ lines = []
+ info = result["rfp_info"]
+ lines.append("=" * 70)
+ lines.append("RFP RESPONSE ANALYSIS")
+ lines.append("=" * 70)
+ lines.append(f"RFP: {info['rfp_name']}")
+ lines.append(f"Customer: {info['customer']}")
+ lines.append(f"Due Date: {info['due_date']}")
+ lines.append(f"Deal Value: {info['deal_value']}")
+ lines.append(f"Strategic Value: {info['strategic_value'].upper()}")
+ lines.append("")
+
+ # Coverage summary
+ cs = result["coverage_summary"]
+ lines.append("-" * 70)
+ lines.append("COVERAGE SUMMARY")
+ lines.append("-" * 70)
+ lines.append(f"Overall Coverage: {cs['overall_coverage_percentage']}%")
+ lines.append(f"Total Requirements: {cs['total_requirements']}")
+ lines.append(f" Full: {cs['full']} | Partial: {cs['partial']} | Planned: {cs['planned']} | Gap: {cs['gap']}")
+ lines.append(f"Must-Have Gaps: {cs['must_have_gaps']}")
+ lines.append("")
+
+ # Bid recommendation
+ bid = result["bid_recommendation"]
+ lines.append("-" * 70)
+ lines.append(f"BID RECOMMENDATION: {bid['decision']}")
+ lines.append(f"Confidence: {bid['confidence'].upper()}")
+ lines.append("-" * 70)
+ for reason in bid["reasons"]:
+ lines.append(f" - {reason}")
+ lines.append("")
+
+ # Category scores
+ lines.append("-" * 70)
+ lines.append("CATEGORY BREAKDOWN")
+ lines.append("-" * 70)
+ lines.append(f"{'Category':<25} {'Coverage':>8} {'Full':>5} {'Part':>5} {'Plan':>5} {'Gap':>5} {'Effort':>7}")
+ lines.append("-" * 70)
+ for cat, scores in result["category_scores"].items():
+ lines.append(
+ f"{cat:<25} {scores['coverage_percentage']:>7.1f}% "
+ f"{scores['full']:>5} {scores['partial']:>5} "
+ f"{scores['planned']:>5} {scores['gap']:>5} "
+ f"{scores['effort_hours']:>6}h"
+ )
+ lines.append("")
+
+ # Gap analysis
+ gaps = result["gap_analysis"]
+ if gaps:
+ lines.append("-" * 70)
+ lines.append("GAP ANALYSIS")
+ lines.append("-" * 70)
+ for gap in gaps:
+ severity_marker = "!!!" if gap["severity"] == "critical" else (
+ "!!" if gap["severity"] == "high" else "!"
+ )
+ lines.append(f" [{severity_marker}] {gap['id']}: {gap['requirement']}")
+ lines.append(f" Category: {gap['category']} | Priority: {gap['priority']} | Status: {gap['coverage_status']}")
+ lines.append(f" Effort: {gap['effort_hours']}h | Mitigation: {gap['mitigation']}")
+ lines.append("")
+
+ # Risk assessment
+ risks = result["risk_assessment"]
+ lines.append("-" * 70)
+ lines.append("RISK ASSESSMENT")
+ lines.append("-" * 70)
+ for risk in risks:
+ lines.append(f" [{risk['impact'].upper()}] {risk['risk']}")
+ lines.append(f" {risk['description']}")
+ lines.append(f" Mitigation: {risk['mitigation']}")
+ lines.append("")
+
+ # Effort estimate
+ effort = result["effort_estimate"]
+ lines.append("-" * 70)
+ lines.append("EFFORT ESTIMATE")
+ lines.append("-" * 70)
+ lines.append(f" Total Effort: {effort['total_hours']} hours")
+ lines.append(f" Gap Closure Effort: {effort['gap_closure_hours']} hours")
+ lines.append(f" Supported Effort: {effort['full_coverage_hours']} hours")
+ lines.append("")
+ lines.append("=" * 70)
+
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for the RFP Response Analyzer."""
+ parser = argparse.ArgumentParser(
+ description="Analyze RFP/RFI requirements for coverage, gaps, and bid recommendation.",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=(
+ "Coverage Categories:\n"
+ " Full (100%) - Requirement fully met\n"
+ " Partial (50%) - Partially met, workaround needed\n"
+ " Planned (25%) - On roadmap, not yet available\n"
+ " Gap (0%) - Not supported\n"
+ "\n"
+ "Priority Weights:\n"
+ " Must-Have (3x) | Should-Have (2x) | Nice-to-Have (1x)\n"
+ "\n"
+ "Example:\n"
+ " python rfp_response_analyzer.py rfp_data.json --format json\n"
+ ),
+ )
+ parser.add_argument(
+ "input_file",
+ help="Path to JSON file containing RFP requirements data",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ dest="output_format",
+ help="Output format: json or text (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ data = load_rfp_data(args.input_file)
+ result = analyze_rfp(data)
+
+ if args.output_format == "json":
+ print(json.dumps(result, indent=2))
+ else:
+ print(format_text(result))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/CLAUDE.md b/skills/c-level-advisor/CLAUDE.md
new file mode 100644
index 00000000..f06da22a
--- /dev/null
+++ b/skills/c-level-advisor/CLAUDE.md
@@ -0,0 +1,121 @@
+# C-Level Advisory Skills — Claude Code Guidance
+
+A complete virtual board of directors: 28 skills covering 10 executive roles, orchestration, cross-cutting capabilities, and culture & collaboration frameworks.
+
+## Architecture
+
+```
+/cs:setup (Founder Interview) → company-context.md
+ │
+ Chief of Staff (Router)
+ │
+ ┌───────────┼───────────┐
+ 10 Roles 6 Cross-Cut 6 Culture
+ │ │ │
+ └───────────┼────────────┘
+ │
+ Executive Mentor (Critic)
+ │
+ Decision Logger (Two-Layer Memory)
+```
+
+## Skills Overview
+
+### C-Suite Roles (10)
+
+| Role | Folder | Reasoning Technique | Scripts |
+|------|--------|-------------------|---------|
+| **CEO** | `ceo-advisor/` | Tree of Thought | strategy_analyzer, financial_scenario_analyzer |
+| **CTO** | `cto-advisor/` | ReAct | tech_debt_analyzer, team_scaling_calculator |
+| **COO** | `coo-advisor/` | Step by Step | ops_efficiency_analyzer, okr_tracker |
+| **CPO** | `cpo-advisor/` | First Principles | pmf_scorer, portfolio_analyzer |
+| **CMO** | `cmo-advisor/` | Recursion of Thought | marketing_budget_modeler, growth_model_simulator |
+| **CFO** | `cfo-advisor/` | Chain of Thought | burn_rate_calculator, unit_economics_analyzer, fundraising_model |
+| **CRO** | `cro-advisor/` | Chain of Thought | revenue_forecast_model, churn_analyzer |
+| **CISO** | `ciso-advisor/` | Risk-Based | risk_quantifier, compliance_tracker |
+| **CHRO** | `chro-advisor/` | Empathy + Data | hiring_plan_modeler, comp_benchmarker |
+| **Executive Mentor** | `executive-mentor/` | Adversarial | decision_matrix_scorer, stakeholder_mapper |
+
+### Orchestration (6)
+
+| Skill | Folder | Purpose |
+|-------|--------|---------|
+| **C-Suite Onboard** | `cs-onboard/` | Founder interview → company-context.md |
+| **Chief of Staff** | `chief-of-staff/` | Routes questions, triggers board meetings |
+| **Board Meeting** | `board-meeting/` | 6-phase multi-agent deliberation |
+| **Decision Logger** | `decision-logger/` | Two-layer memory (raw + approved) |
+| **Agent Protocol** | `agent-protocol/` | Inter-agent invocation, loop prevention, quality loop |
+| **Context Engine** | `context-engine/` | Company context loading + anonymization |
+
+### Cross-Cutting Capabilities (6)
+
+| Skill | Folder | Purpose |
+|-------|--------|---------|
+| **Board Deck Builder** | `board-deck-builder/` | Assembles board/investor updates |
+| **Scenario War Room** | `scenario-war-room/` | Multi-variable what-if modeling |
+| **Competitive Intel** | `competitive-intel/` | Systematic competitor tracking |
+| **Org Health Diagnostic** | `org-health-diagnostic/` | Cross-functional health scoring |
+| **M&A Playbook** | `ma-playbook/` | Acquiring or being acquired |
+| **International Expansion** | `intl-expansion/` | Market entry strategy |
+
+### Culture & Collaboration (6)
+
+| Skill | Folder | Purpose |
+|-------|--------|---------|
+| **Culture Architect** | `culture-architect/` | Build and operationalize culture |
+| **Company OS** | `company-os/` | EOS/Scaling Up operating system |
+| **Founder Coach** | `founder-coach/` | Founder development and growth |
+| **Strategic Alignment** | `strategic-alignment/` | Strategy cascade, silo detection |
+| **Change Management** | `change-management/` | ADKAR-based change rollout |
+| **Internal Narrative** | `internal-narrative/` | One story across all audiences |
+
+## Executive Mentor Slash Commands
+
+The only skill with a `plugin.json` (namespace: `em`) because it has slash commands. Other skills are invoked by name through the Chief of Staff router or directly by the user. This is intentional — only add `plugin.json` when a skill has dedicated slash commands that need a namespace.
+
+| Command | Purpose |
+|---------|---------|
+| `/em:challenge` | Pre-mortem analysis of any plan |
+| `/em:board-prep` | Board meeting preparation |
+| `/em:hard-call` | Framework for hard decisions |
+| `/em:stress-test` | Stress-test any assumption |
+| `/em:postmortem` | Honest retrospective |
+
+## Key Design Decisions
+
+- **Two-layer memory:** Raw transcripts (reference) + approved decisions only (feeds future meetings). Prevents hallucinated consensus.
+- **Phase 2 isolation:** During board meetings, agents think independently before cross-examination.
+- **Internal Quality Loop:** Self-verify → peer-verify → critic pre-screen → present. No unverified output reaches the founder.
+- **Proactive triggers:** Every role has context-driven early warnings that surface issues without being asked.
+- **User Communication Standard:** Bottom Line → What → Why → How to Act → Your Decision. Results only, no process narration.
+
+## Python Tools (25 total)
+
+All scripts are stdlib-only, CLI-first, with JSON output and embedded sample data.
+
+```bash
+# Examples
+python cfo-advisor/scripts/burn_rate_calculator.py
+python cro-advisor/scripts/churn_analyzer.py
+python cpo-advisor/scripts/pmf_scorer.py
+python org-health-diagnostic/scripts/health_scorer.py
+python strategic-alignment/scripts/alignment_checker.py
+python decision-logger/scripts/decision_tracker.py
+```
+
+## Integration with Other Domains
+
+| C-Level Role | Layers Above |
+|-------------|-------------|
+| CMO | marketing-skill/ (content, demand gen, ASO execution) |
+| CFO | finance/financial-analyst (spreadsheets, DCF) |
+| CRO | business-growth/ (revenue ops, sales engineering) |
+| CISO | ra-qm-team/ (ISO 27001 checklists, ISMS audits) |
+| CPO | product-team/ (PM toolkit, user stories, sprint planning) |
+
+---
+
+**Last Updated:** 2026-03-05
+**Skills Deployed:** 28 skills (10 roles + 5 mentor commands + 6 orchestration + 6 cross-cutting + 6 culture)
+**Python Tools:** 25 (stdlib-only)
+**Reference Docs:** 52
diff --git a/skills/c-level-advisor/README.md b/skills/c-level-advisor/README.md
new file mode 100644
index 00000000..5bc11e7d
--- /dev/null
+++ b/skills/c-level-advisor/README.md
@@ -0,0 +1,380 @@
+# C-Level Advisory Skills Collection
+
+**Complete suite of 2 executive leadership skills** covering CEO and CTO strategic decision-making and organizational leadership.
+
+---
+
+## 📚 Table of Contents
+
+- [Installation](#installation)
+- [Overview](#overview)
+- [Skills Catalog](#skills-catalog)
+- [Quick Start Guide](#quick-start-guide)
+- [Common Workflows](#common-workflows)
+- [Success Metrics](#success-metrics)
+
+---
+
+## ⚡ Installation
+
+### Quick Install (Recommended)
+
+Install all C-Level advisory skills with one command:
+
+```bash
+# Install all C-Level skills to all supported agents
+npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor
+
+# Install to Claude Code only
+npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor --agent claude
+
+# Install to Cursor only
+npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor --agent cursor
+```
+
+### Install Individual Skills
+
+```bash
+# CEO Advisor
+npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/ceo-advisor
+
+# CTO Advisor
+npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/cto-advisor
+```
+
+**Supported Agents:** Claude Code, Cursor, VS Code, Copilot, Goose, Amp, Codex
+
+**Complete Installation Guide:** See [../INSTALLATION.md](../INSTALLATION.md) for detailed instructions, troubleshooting, and manual installation.
+
+---
+
+## 🎯 Overview
+
+This C-Level advisory skills collection provides executive leadership guidance for strategic decision-making, organizational development, and stakeholder management.
+
+**What's Included:**
+- **2 executive-level skills** for CEO and CTO roles
+- **6 Python analysis tools** for strategy, finance, tech debt, and team scaling
+- **Comprehensive frameworks** for executive decision-making, board governance, and technology leadership
+- **Ready-to-use templates** for board presentations, ADRs, and strategic planning
+
+**Ideal For:**
+- CEOs and founders at startups and scale-ups
+- CTOs and VP Engineering roles
+- Executive leadership teams
+- Board members and advisors
+
+**Key Benefits:**
+- 🎯 **Strategic clarity** with structured decision-making frameworks
+- 📊 **Data-driven decisions** with financial and technical analysis tools
+- 🚀 **Faster execution** with proven templates and best practices
+- 💡 **Risk mitigation** through systematic evaluation processes
+
+---
+
+## 📦 Skills Catalog
+
+### 1. CEO Advisor
+**Status:** ✅ Production Ready | **Version:** 1.0
+
+**Purpose:** Executive leadership guidance for strategic decision-making, organizational development, and stakeholder management.
+
+**Key Capabilities:**
+- Strategic planning and initiative evaluation
+- Financial scenario modeling and business outcomes
+- Executive decision framework (structured methodology)
+- Leadership and organizational culture development
+- Board governance and investor relations
+- Stakeholder communication best practices
+
+**Python Tools:**
+- `strategy_analyzer.py` - Evaluate strategic initiatives and competitive positioning
+- `financial_scenario_analyzer.py` - Model financial scenarios and business outcomes
+
+**Core Workflows:**
+1. Strategic planning and initiative evaluation
+2. Financial scenario modeling
+3. Board and investor communication
+4. Organizational culture development
+
+**Use When:**
+- Making strategic decisions (market expansion, product pivots, fundraising)
+- Preparing board presentations
+- Modeling business scenarios
+- Building organizational culture
+- Managing stakeholder relationships
+
+**Learn More:** [ceo-advisor/SKILL.md](ceo-advisor/SKILL.md)
+
+---
+
+### 2. CTO Advisor
+**Status:** ✅ Production Ready | **Version:** 1.0
+
+**Purpose:** Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.
+
+**Key Capabilities:**
+- Technical debt assessment and management
+- Engineering team scaling and structure planning
+- Technology evaluation and selection frameworks
+- Architecture decision documentation (ADRs)
+- Engineering metrics (DORA metrics, velocity, quality)
+- Build vs. buy analysis
+
+**Python Tools:**
+- `tech_debt_analyzer.py` - Quantify and prioritize technical debt
+- `team_scaling_calculator.py` - Model engineering team growth and structure
+
+**Core Workflows:**
+1. Technical debt assessment and management
+2. Engineering team scaling and structure
+3. Technology evaluation and selection
+4. Architecture decision documentation
+
+**Use When:**
+- Managing technical debt
+- Scaling engineering teams
+- Evaluating new technologies or frameworks
+- Making architecture decisions
+- Measuring engineering performance
+
+**Learn More:** [cto-advisor/SKILL.md](cto-advisor/SKILL.md)
+
+---
+
+## 🚀 Quick Start Guide
+
+### For CEOs
+
+1. **Install CEO Advisor:**
+ ```bash
+ npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/ceo-advisor
+ ```
+
+2. **Evaluate Strategic Initiative:**
+ ```bash
+ python ceo-advisor/scripts/strategy_analyzer.py strategy-doc.md
+ ```
+
+3. **Model Financial Scenarios:**
+ ```bash
+ python ceo-advisor/scripts/financial_scenario_analyzer.py scenarios.yaml
+ ```
+
+4. **Prepare for Board Meeting:**
+ - Use frameworks in `references/board_governance_investor_relations.md`
+ - Apply decision framework from `references/executive_decision_framework.md`
+ - Use templates from `assets/`
+
+### For CTOs
+
+1. **Install CTO Advisor:**
+ ```bash
+ npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/cto-advisor
+ ```
+
+2. **Analyze Technical Debt:**
+ ```bash
+ python cto-advisor/scripts/tech_debt_analyzer.py /path/to/codebase
+ ```
+
+3. **Plan Team Scaling:**
+ ```bash
+ python cto-advisor/scripts/team_scaling_calculator.py --current-size 10 --target-size 50
+ ```
+
+4. **Document Architecture Decisions:**
+ - Use ADR templates from `references/architecture_decision_records.md`
+ - Apply technology evaluation framework
+ - Track engineering metrics
+
+---
+
+## 🔄 Common Workflows
+
+### Workflow 1: Strategic Decision Making (CEO)
+
+```
+1. Problem Definition → CEO Advisor
+ - Define decision context
+ - Identify stakeholders
+ - Clarify success criteria
+
+2. Strategic Analysis → CEO Advisor
+ - Strategy analyzer tool
+ - Competitive positioning
+ - Market opportunity assessment
+
+3. Financial Modeling → CEO Advisor
+ - Scenario analyzer tool
+ - Revenue projections
+ - Cost-benefit analysis
+
+4. Decision Framework → CEO Advisor
+ - Apply structured methodology
+ - Risk assessment
+ - Go/No-go recommendation
+
+5. Stakeholder Communication → CEO Advisor
+ - Board presentation
+ - Investor update
+ - Team announcement
+```
+
+### Workflow 2: Technology Evaluation (CTO)
+
+```
+1. Technology Assessment → CTO Advisor
+ - Requirements gathering
+ - Technology landscape scan
+ - Evaluation criteria definition
+
+2. Build vs. Buy Analysis → CTO Advisor
+ - TCO calculation
+ - Risk analysis
+ - Timeline estimation
+
+3. Architecture Impact → CTO Advisor
+ - System design implications
+ - Integration complexity
+ - Migration path
+
+4. Decision Documentation → CTO Advisor
+ - ADR creation
+ - Technical specification
+ - Implementation roadmap
+
+5. Team Communication → CTO Advisor
+ - Engineering announcement
+ - Training plan
+ - Implementation kickoff
+```
+
+### Workflow 3: Engineering Team Scaling (CTO)
+
+```
+1. Current State Assessment → CTO Advisor
+ - Team structure analysis
+ - Velocity and quality metrics
+ - Bottleneck identification
+
+2. Growth Modeling → CTO Advisor
+ - Team scaling calculator
+ - Organizational design
+ - Role definition
+
+3. Hiring Plan → CTO Advisor
+ - Hiring timeline
+ - Budget requirements
+ - Onboarding strategy
+
+4. Process Evolution → CTO Advisor
+ - Updated workflows
+ - Team communication
+ - Quality gates
+
+5. Implementation → CTO Advisor
+ - Gradual rollout
+ - Metrics tracking
+ - Continuous adjustment
+```
+
+### Workflow 4: Board Preparation (CEO)
+
+```
+1. Content Preparation → CEO Advisor
+ - Financial summary
+ - Strategic updates
+ - Key metrics dashboard
+
+2. Presentation Design → CEO Advisor
+ - Board governance frameworks
+ - Slide deck structure
+ - Data visualization
+
+3. Q&A Preparation → CEO Advisor
+ - Anticipated questions
+ - Risk mitigation answers
+ - Strategic rationale
+
+4. Rehearsal → CEO Advisor
+ - Timing practice
+ - Narrative flow
+ - Supporting materials
+```
+
+---
+
+## 📊 Success Metrics
+
+### CEO Advisor Impact
+
+**Strategic Clarity:**
+- 40% improvement in decision-making speed
+- 50% reduction in strategic initiative failures
+- 60% improvement in stakeholder alignment
+
+**Financial Performance:**
+- 30% better accuracy in financial projections
+- 45% improvement in scenario planning effectiveness
+- 25% reduction in unexpected costs
+
+**Board & Investor Relations:**
+- 50% reduction in board presentation preparation time
+- 70% improvement in board feedback quality
+- 40% better investor communication clarity
+
+### CTO Advisor Impact
+
+**Technical Debt Management:**
+- 60% improvement in tech debt visibility
+- 40% reduction in critical tech debt items
+- 50% better resource allocation for debt reduction
+
+**Team Scaling:**
+- 45% faster time-to-productivity for new hires
+- 35% reduction in team scaling mistakes
+- 50% improvement in organizational design clarity
+
+**Technology Decisions:**
+- 70% reduction in technology evaluation time
+- 55% improvement in build vs. buy accuracy
+- 40% better architecture decision documentation
+
+---
+
+## 🔗 Integration with Other Teams
+
+**CEO ↔ Product:**
+- Strategic vision → Product roadmap
+- Market insights → Product strategy
+- Customer feedback → Product prioritization
+
+**CEO ↔ CTO:**
+- Technology strategy → Business strategy
+- Engineering capacity → Business planning
+- Technical decisions → Strategic initiatives
+
+**CTO ↔ Engineering:**
+- Architecture decisions → Implementation
+- Tech debt priorities → Sprint planning
+- Team structure → Engineering delivery
+
+**CTO ↔ Product:**
+- Technical feasibility → Product planning
+- Platform capabilities → Product features
+- Engineering metrics → Product velocity
+
+---
+
+## 📚 Additional Resources
+
+- **CLAUDE.md:** [c-level-advisor/CLAUDE.md](CLAUDE.md) - Claude Code specific guidance (if exists)
+- **Main Documentation:** [../CLAUDE.md](../CLAUDE.md)
+- **Installation Guide:** [../INSTALLATION.md](../INSTALLATION.md)
+
+---
+
+**Last Updated:** January 2026
+**Skills Deployed:** 2/2 C-Level advisory skills production-ready
+**Total Tools:** 6 Python analysis tools (strategy, finance, tech debt, team scaling)
diff --git a/skills/c-level-advisor/SKILL.md b/skills/c-level-advisor/SKILL.md
new file mode 100644
index 00000000..46cb1c9c
--- /dev/null
+++ b/skills/c-level-advisor/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: "c-level-advisor"
+description: "Provides strategic business advice by channelling the perspectives of 10 executive roles — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, and Executive Mentor — across decisions, trade-offs, and org challenges. Runs multi-role board meetings, routes questions to the right executive voice, and delivers structured recommendations (Bottom Line → What → Why → How to Act → Your Decision). Use when a founder or executive needs business strategy advice, leadership perspective, executive decision support, board-level input, fundraising guidance, product-market fit review, hiring or culture frameworks, risk assessment, or competitive analysis."
+license: MIT
+metadata:
+ version: 2.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: executive-advisory
+ updated: 2026-03-05
+ skills_count: 28
+ scripts_count: 25
+ references_count: 52
+---
+
+# C-Level Advisory Ecosystem
+
+A complete virtual board of directors for founders and executives.
+
+## Quick Start
+
+```
+1. Run /cs:setup → creates company-context.md (all agents read this)
+ ✓ Verify company-context.md was created and contains your company name,
+ stage, and core metrics before proceeding.
+2. Ask any strategic question → Chief of Staff routes to the right role
+3. For big decisions → /cs:board triggers a multi-role board meeting
+ ✓ Confirm at least 3 roles have weighed in before accepting a conclusion.
+```
+
+### Commands
+
+#### `/cs:setup` — Onboarding Questionnaire
+
+Walks through the following prompts and writes `company-context.md` to the project root. Run once per company or when context changes significantly.
+
+```
+Q1. What is your company name and one-line description?
+Q2. What stage are you at? (Idea / Pre-seed / Seed / Series A / Series B+)
+Q3. What is your current ARR (or MRR) and runway in months?
+Q4. What is your team size and structure?
+Q5. What industry and customer segment do you serve?
+Q6. What are your top 3 priorities for the next 90 days?
+Q7. What is your biggest current risk or blocker?
+```
+
+After collecting answers, the agent writes structured output:
+
+```markdown
+# Company Context
+- Name:
+- Stage:
+- Industry:
+- Team size:
+- Key metrics:
+- Top priorities:
+- Key risks:
+```
+
+#### `/cs:board` — Full Board Meeting
+
+Convenes all relevant executive roles in three phases:
+
+```
+Phase 1 — Framing: Chief of Staff states the decision and success criteria.
+Phase 2 — Isolation: Each role produces independent analysis (no cross-talk).
+Phase 3 — Debate: Roles surface conflicts, stress-test assumptions, align on
+ a recommendation. Dissenting views are preserved in the log.
+```
+
+Use for high-stakes or cross-functional decisions. Confirm at least 3 roles have weighed in before accepting a conclusion.
+
+### Chief of Staff Routing Matrix
+
+When a question arrives without a role prefix, the Chief of Staff maps it to the appropriate executive using these primary signals:
+
+| Topic Signal | Primary Role | Supporting Roles |
+|---|---|---|
+| Fundraising, valuation, burn | CFO | CEO, CRO |
+| Architecture, build vs. buy, tech debt | CTO | CPO, CISO |
+| Hiring, culture, performance | CHRO | CEO, Executive Mentor |
+| GTM, demand gen, positioning | CMO | CRO, CPO |
+| Revenue, pipeline, sales motion | CRO | CMO, CFO |
+| Security, compliance, risk | CISO | CTO, CFO |
+| Product roadmap, prioritisation | CPO | CTO, CMO |
+| Ops, process, scaling | COO | CFO, CHRO |
+| Vision, strategy, investor relations | CEO | Executive Mentor |
+| Career, founder psychology, leadership | Executive Mentor | CEO, CHRO |
+| Multi-domain / unclear | Chief of Staff convenes board | All relevant roles |
+
+### Invoking a Specific Role Directly
+
+To bypass Chief of Staff routing and address one executive directly, prefix your question with the role name:
+
+```
+CFO: What is our optimal burn rate heading into a Series A?
+CTO: Should we rebuild our auth layer in-house or buy a solution?
+CHRO: How do we design a performance review process for a 15-person team?
+```
+
+The Chief of Staff still logs the exchange; only routing is skipped.
+
+### Example: Strategic Question
+
+**Input:** "Should we raise a Series A now or extend runway and grow ARR first?"
+
+**Output format:**
+- **Bottom Line:** Extend runway 6 months; raise at $2M ARR for better terms.
+- **What:** Current $800K ARR is below the threshold most Series A investors benchmark.
+- **Why:** Raising now increases dilution risk; 6-month extension is achievable with current burn.
+- **How to Act:** Cut 2 low-ROI channels, hit $2M ARR, then run a 6-week fundraise sprint.
+- **Your Decision:** Proceed with extension / Raise now anyway (choose one).
+
+### Example: company-context.md (after /cs:setup)
+
+```markdown
+# Company Context
+- Name: Acme Inc.
+- Stage: Seed ($800K ARR)
+- Industry: B2B SaaS
+- Team size: 12
+- Key metrics: 15% MoM growth, 18-month runway
+- Top priorities: Series A readiness, enterprise GTM
+```
+
+## What's Included
+
+### 10 C-Suite Roles
+CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor
+
+### 6 Orchestration Skills
+Founder Onboard, Chief of Staff (router), Board Meeting, Decision Logger, Agent Protocol, Context Engine
+
+### 6 Cross-Cutting Capabilities
+Board Deck Builder, Scenario War Room, Competitive Intel, Org Health Diagnostic, M&A Playbook, International Expansion
+
+### 6 Culture & Collaboration
+Culture Architect, Company OS, Founder Coach, Strategic Alignment, Change Management, Internal Narrative
+
+## Key Features
+
+- **Internal Quality Loop:** Self-verify → peer-verify → critic pre-screen → present
+- **Two-Layer Memory:** Raw transcripts + approved decisions only (prevents hallucinated consensus)
+- **Board Meeting Isolation:** Phase 2 independent analysis before cross-examination
+- **Proactive Triggers:** Context-driven early warnings without being asked
+- **Structured Output:** Bottom Line → What → Why → How to Act → Your Decision
+- **25 Python Tools:** All stdlib-only, CLI-first, JSON output, zero dependencies
+
+## See Also
+
+- `CLAUDE.md` — full architecture diagram and integration guide
+- `agent-protocol/SKILL.md` — communication standard and quality loop details
+- `chief-of-staff/SKILL.md` — routing matrix for all 28 skills
diff --git a/skills/c-level-advisor/_meta.json b/skills/c-level-advisor/_meta.json
new file mode 100644
index 00000000..a8838b6b
--- /dev/null
+++ b/skills/c-level-advisor/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "c-level-advisor",
+ "displayName": "c-level-advisor",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1773242071089,
+ "commit": "https://github.com/openclaw/skills/commit/55685e3a5437bdc3e3c3c3d706fc00bc046dd994"
+ },
+ "history": [
+ {
+ "version": "2.0.0",
+ "publishedAt": 1772746495741,
+ "commit": "https://github.com/openclaw/skills/commit/6326295878539d480c3f8db103231b1083da52cb"
+ }
+ ]
+}
diff --git a/skills/c-level-advisor/agent-protocol/SKILL.md b/skills/c-level-advisor/agent-protocol/SKILL.md
new file mode 100644
index 00000000..35ef75cd
--- /dev/null
+++ b/skills/c-level-advisor/agent-protocol/SKILL.md
@@ -0,0 +1,418 @@
+---
+name: "agent-protocol"
+description: "Inter-agent communication protocol for C-suite agent teams. Defines invocation syntax, loop prevention, isolation rules, and response formats. Use when C-suite agents need to query each other, coordinate cross-functional analysis, or run board meetings with multiple agent roles."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: agent-orchestration
+ updated: 2026-03-05
+ frameworks: invocation-patterns
+---
+
+# Inter-Agent Protocol
+
+How C-suite agents talk to each other. Rules that prevent chaos, loops, and circular reasoning.
+
+## Keywords
+agent protocol, inter-agent communication, agent invocation, agent orchestration, multi-agent, c-suite coordination, agent chain, loop prevention, agent isolation, board meeting protocol
+
+## Invocation Syntax
+
+Any agent can query another using:
+
+```
+[INVOKE:role|question]
+```
+
+**Examples:**
+```
+[INVOKE:cfo|What's the burn rate impact of hiring 5 engineers in Q3?]
+[INVOKE:cto|Can we realistically ship this feature by end of quarter?]
+[INVOKE:chro|What's our typical time-to-hire for senior engineers?]
+[INVOKE:cro|What does our pipeline look like for the next 90 days?]
+```
+
+**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso`
+
+## Response Format
+
+Invoked agents respond using this structure:
+
+```
+[RESPONSE:role]
+Key finding: [one line — the actual answer]
+Supporting data:
+ - [data point 1]
+ - [data point 2]
+ - [data point 3 — optional]
+Confidence: [high | medium | low]
+Caveat: [one line — what could make this wrong]
+[/RESPONSE]
+```
+
+**Example:**
+```
+[RESPONSE:cfo]
+Key finding: Hiring 5 engineers in Q3 extends runway from 14 to 9 months at current burn.
+Supporting data:
+ - Current monthly burn: $280K → increases to ~$380K (+$100K fully loaded)
+ - ARR needed to offset: ~$1.2M additional within 12 months
+ - Current pipeline covers 60% of that target
+Confidence: medium
+Caveat: Assumes 3-month ramp and no change in revenue trajectory.
+[/RESPONSE]
+```
+
+## Loop Prevention (Hard Rules)
+
+These rules are enforced unconditionally. No exceptions.
+
+### Rule 1: No Self-Invocation
+An agent cannot invoke itself.
+```
+❌ CFO → [INVOKE:cfo|...] — BLOCKED
+```
+
+### Rule 2: Maximum Depth = 2
+Chains can go A→B→C. The third hop is blocked.
+```
+✅ CRO → CFO → COO (depth 2)
+❌ CRO → CFO → COO → CHRO (depth 3 — BLOCKED)
+```
+
+### Rule 3: No Circular Calls
+If agent A called agent B, agent B cannot call agent A in the same chain.
+```
+✅ CRO → CFO → CMO
+❌ CRO → CFO → CRO (circular — BLOCKED)
+```
+
+### Rule 4: Chain Tracking
+Each invocation carries its call chain. Format:
+```
+[CHAIN: cro → cfo → coo]
+```
+Agents check this chain before responding with another invocation.
+
+**When blocked:** Return this instead of invoking:
+```
+[BLOCKED: cannot invoke cfo — circular call detected in chain cro→cfo]
+State assumption used instead: [explicit assumption the agent is making]
+```
+
+## Isolation Rules
+
+### Board Meeting Phase 2 (Independent Analysis)
+**NO invocations allowed.** Each role forms independent views before cross-pollination.
+- Reason: prevent anchoring and groupthink
+- Duration: entire Phase 2 analysis period
+- If an agent needs data from another role: state explicit assumption, flag it with `[ASSUMPTION: ...]`
+
+### Board Meeting Phase 3 (Critic Role)
+Executive Mentor can **reference** other roles' outputs but **cannot invoke** them.
+- Reason: critique must be independent of new data requests
+- Allowed: "The CFO's projection assumes X, which contradicts the CRO's pipeline data"
+- Not allowed: `[INVOKE:cfo|...]` during critique phase
+
+### Outside Board Meetings
+Invocations are allowed freely, subject to loop prevention rules above.
+
+## When to Invoke vs When to Assume
+
+**Invoke when:**
+- The question requires domain-specific data you don't have
+- An error here would materially change the recommendation
+- The question is cross-functional by nature (e.g., hiring impact on both budget and capacity)
+
+**Assume when:**
+- The data is directionally clear and precision isn't critical
+- You're in Phase 2 isolation (always assume, never invoke)
+- The chain is already at depth 2
+- The question is minor compared to your main analysis
+
+**When assuming, always state it:**
+```
+[ASSUMPTION: runway ~12 months based on typical Series A burn profile — not verified with CFO]
+```
+
+## Conflict Resolution
+
+When two invoked agents give conflicting answers:
+
+1. **Flag the conflict explicitly:**
+ ```
+ [CONFLICT: CFO projects 14-month runway; CRO expects pipeline to close 80% → implies 18+ months]
+ ```
+2. **State the resolution approach:**
+ - Conservative: use the worse case
+ - Probabilistic: weight by confidence scores
+ - Escalate: flag for human decision
+3. **Never silently pick one** — surface the conflict to the user.
+
+## Broadcast Pattern (Crisis / CEO)
+
+CEO can broadcast to all roles simultaneously:
+```
+[BROADCAST:all|What's the impact if we miss the fundraise?]
+```
+
+Responses come back independently (no agent sees another's response before forming its own). Aggregate after all respond.
+
+## Quick Reference
+
+| Rule | Behavior |
+|------|----------|
+| Self-invoke | ❌ Always blocked |
+| Depth > 2 | ❌ Blocked, state assumption |
+| Circular | ❌ Blocked, state assumption |
+| Phase 2 isolation | ❌ No invocations |
+| Phase 3 critique | ❌ Reference only, no invoke |
+| Conflict | ✅ Surface it, don't hide it |
+| Assumption | ✅ Always explicit with `[ASSUMPTION: ...]` |
+
+## Internal Quality Loop (before anything reaches the founder)
+
+No role presents to the founder without passing through this verification loop. The founder sees polished, verified output — not first drafts.
+
+### Step 1: Self-Verification (every role, every time)
+
+Before presenting, every role runs this internal checklist:
+
+```
+SELF-VERIFY CHECKLIST:
+□ Source Attribution — Where did each data point come from?
+ ✅ "ARR is $2.1M (from CRO pipeline report, Q4 actuals)"
+ ❌ "ARR is around $2M" (no source, vague)
+
+□ Assumption Audit — What am I assuming vs what I verified?
+ Tag every assumption: [VERIFIED: checked against data] or [ASSUMED: not verified]
+ If >50% of findings are ASSUMED → flag low confidence
+
+□ Confidence Score — How sure am I on each finding?
+ 🟢 High: verified data, established pattern, multiple sources
+ 🟡 Medium: single source, reasonable inference, some uncertainty
+ 🔴 Low: assumption-based, limited data, first-time analysis
+
+□ Contradiction Check — Does this conflict with known context?
+ Check against company-context.md and recent decisions in decision-log
+ If it contradicts a past decision → flag explicitly
+
+□ "So What?" Test — Does every finding have a business consequence?
+ If you can't answer "so what?" in one sentence → cut it
+```
+
+### Step 2: Peer Verification (cross-functional validation)
+
+When a recommendation impacts another role's domain, that role validates BEFORE presenting.
+
+| If your recommendation involves... | Validate with... | They check... |
+|-------------------------------------|-------------------|---------------|
+| Financial numbers or budget | CFO | Math, runway impact, budget reality |
+| Revenue projections | CRO | Pipeline backing, historical accuracy |
+| Headcount or hiring | CHRO | Market reality, comp feasibility, timeline |
+| Technical feasibility or timeline | CTO | Engineering capacity, technical debt load |
+| Operational process changes | COO | Capacity, dependencies, scaling impact |
+| Customer-facing changes | CRO + CPO | Churn risk, product roadmap conflict |
+| Security or compliance claims | CISO | Actual posture, regulation requirements |
+| Market or positioning claims | CMO | Data backing, competitive reality |
+
+**Peer validation format:**
+```
+[PEER-VERIFY:cfo]
+Validated: ✅ Burn rate calculation correct
+Adjusted: ⚠️ Hiring timeline should be Q3 not Q2 (budget constraint)
+Flagged: 🔴 Missing equity cost in total comp projection
+[/PEER-VERIFY]
+```
+
+**Skip peer verification when:**
+- Single-domain question with no cross-functional impact
+- Time-sensitive proactive alert (send alert, verify after)
+- Founder explicitly asked for a quick take
+
+### Step 3: Critic Pre-Screen (high-stakes decisions only)
+
+For decisions that are **irreversible, high-cost, or bet-the-company**, the Executive Mentor pre-screens before the founder sees it.
+
+**Triggers for pre-screen:**
+- Involves spending > 20% of remaining runway
+- Affects >30% of the team (layoffs, reorg)
+- Changes company strategy or direction
+- Involves external commitments (fundraising terms, partnerships, M&A)
+- Any recommendation where all roles agree (suspicious consensus)
+
+**Pre-screen output:**
+```
+[CRITIC-SCREEN]
+Weakest point: [The single biggest vulnerability in this recommendation]
+Missing perspective: [What nobody considered]
+If wrong, the cost is: [Quantified downside]
+Proceed: ✅ With noted risks | ⚠️ After addressing [specific gap] | 🔴 Rethink
+[/CRITIC-SCREEN]
+```
+
+### Step 4: Course Correction (after founder feedback)
+
+The loop doesn't end at delivery. After the founder responds:
+
+```
+FOUNDER FEEDBACK LOOP:
+1. Founder approves → log decision (Layer 2), assign actions
+2. Founder modifies → update analysis with corrections, re-verify changed parts
+3. Founder rejects → log rejection with DO_NOT_RESURFACE, understand WHY
+4. Founder asks follow-up → deepen analysis on specific point, re-verify
+
+POST-DECISION REVIEW (30/60/90 days):
+- Was the recommendation correct?
+- What did we miss?
+- Update company-context.md with what we learned
+- If wrong → document the lesson, adjust future analysis
+```
+
+### Verification Level by Stakes
+
+| Stakes | Self-Verify | Peer-Verify | Critic Pre-Screen |
+|--------|-------------|-------------|-------------------|
+| Low (informational) | ✅ Required | ❌ Skip | ❌ Skip |
+| Medium (operational) | ✅ Required | ✅ Required | ❌ Skip |
+| High (strategic) | ✅ Required | ✅ Required | ✅ Required |
+| Critical (irreversible) | ✅ Required | ✅ Required | ✅ Required + board meeting |
+
+### What Changes in the Output Format
+
+The verified output adds confidence and source information:
+
+```
+BOTTOM LINE
+[Answer] — Confidence: 🟢 High
+
+WHAT
+• [Finding 1] [VERIFIED: Q4 actuals] 🟢
+• [Finding 2] [VERIFIED: CRO pipeline data] 🟢
+• [Finding 3] [ASSUMED: based on industry benchmarks] 🟡
+
+PEER-VERIFIED BY: CFO (math ✅), CTO (timeline ⚠️ adjusted to Q3)
+```
+
+---
+
+## User Communication Standard
+
+All C-suite output to the founder follows ONE format. No exceptions. The founder is the decision-maker — give them results, not process.
+
+### Standard Output (single-role response)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 [ROLE] — [Topic]
+
+BOTTOM LINE
+[One sentence. The answer. No preamble.]
+
+WHAT
+• [Finding 1 — most critical]
+• [Finding 2]
+• [Finding 3]
+(Max 5 bullets. If more needed → reference doc.)
+
+WHY THIS MATTERS
+[1-2 sentences. Business impact. Not theory — consequence.]
+
+HOW TO ACT
+1. [Action] → [Owner] → [Deadline]
+2. [Action] → [Owner] → [Deadline]
+3. [Action] → [Owner] → [Deadline]
+
+⚠️ RISKS (if any)
+• [Risk + what triggers it]
+
+🔑 YOUR DECISION (if needed)
+Option A: [Description] — [Trade-off]
+Option B: [Description] — [Trade-off]
+Recommendation: [Which and why, in one line]
+
+📎 DETAIL: [reference doc or script output for deep-dive]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Proactive Alert (unsolicited — triggered by context)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🚩 [ROLE] — Proactive Alert
+
+WHAT I NOTICED
+[What triggered this — specific, not vague]
+
+WHY IT MATTERS
+[Business consequence if ignored — in dollars, time, or risk]
+
+RECOMMENDED ACTION
+[Exactly what to do, who does it, by when]
+
+URGENCY: 🔴 Act today | 🟡 This week | ⚪ Next review
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Board Meeting Output (multi-role synthesis)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 BOARD MEETING — [Date] — [Agenda Topic]
+
+DECISION REQUIRED
+[Frame the decision in one sentence]
+
+PERSPECTIVES
+ CEO: [one-line position]
+ CFO: [one-line position]
+ CRO: [one-line position]
+ [... only roles that contributed]
+
+WHERE THEY AGREE
+• [Consensus point 1]
+• [Consensus point 2]
+
+WHERE THEY DISAGREE
+• [Conflict] — CEO says X, CFO says Y
+• [Conflict] — CRO says X, CPO says Y
+
+CRITIC'S VIEW (Executive Mentor)
+[The uncomfortable truth nobody else said]
+
+RECOMMENDED DECISION
+[Clear recommendation with rationale]
+
+ACTION ITEMS
+1. [Action] → [Owner] → [Deadline]
+2. [Action] → [Owner] → [Deadline]
+3. [Action] → [Owner] → [Deadline]
+
+🔑 YOUR CALL
+[Options if you disagree with the recommendation]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Communication Rules (non-negotiable)
+
+1. **Bottom line first.** Always. The founder's time is the scarcest resource.
+2. **Results and decisions only.** No process narration ("First I analyzed..."). No thinking out loud.
+3. **What + Why + How.** Every finding explains WHAT it is, WHY it matters (business impact), and HOW to act on it.
+4. **Max 5 bullets per section.** Longer = reference doc.
+5. **Actions have owners and deadlines.** "We should consider" is banned. Who does what by when.
+6. **Decisions framed as options.** Not "what do you think?" — "Option A or B, here's the trade-off, here's my recommendation."
+7. **The founder decides.** Roles recommend. The founder approves, modifies, or rejects. Every output respects this hierarchy.
+8. **Risks are concrete.** Not "there might be risks" — "if X happens, Y breaks, costing $Z."
+9. **No jargon without explanation.** If you use a term, explain it on first use.
+10. **Silence is an option.** If there's nothing to report, don't fabricate updates.
+
+## Reference
+- `references/invocation-patterns.md` — common cross-functional patterns with examples
diff --git a/skills/c-level-advisor/agent-protocol/references/invocation-patterns.md b/skills/c-level-advisor/agent-protocol/references/invocation-patterns.md
new file mode 100644
index 00000000..be413bf1
--- /dev/null
+++ b/skills/c-level-advisor/agent-protocol/references/invocation-patterns.md
@@ -0,0 +1,247 @@
+# Invocation Patterns — Inter-Agent Protocol
+
+Common cross-functional patterns, with examples and guidance on when to invoke vs assume.
+
+---
+
+## Pattern 1: Revenue Planning Chain
+**CRO → CFO → CMO**
+
+Used when: setting revenue targets, allocating growth budget, modeling pipeline scenarios.
+
+```
+CRO initiates:
+"Planning Q3 revenue targets. Need financial constraints and marketing input."
+
+CRO → [INVOKE:cfo|What's our Q3 revenue target given current runway and burn?]
+
+CFO responds:
+[RESPONSE:cfo]
+Key finding: To maintain 12-month runway without new raise, Q3 ARR target ≥ $2.4M (+20% QoQ)
+Supporting data:
+ - Current ARR: $2.0M, burn: $180K/month, runway: 14 months
+ - 20% QoQ growth maintains runway; <15% triggers bridge discussion
+ - Board expectation communicated as 25% QoQ
+Confidence: high
+Caveat: Assumes no new hires or major infrastructure spend in Q3.
+[/RESPONSE]
+
+CRO → [INVOKE:cmo|Given a $2.4M Q3 ARR target, what pipeline coverage and CAC should we plan for?]
+[CHAIN: cro → cfo → cmo]
+
+CMO responds:
+[RESPONSE:cmo]
+Key finding: Need 3x pipeline ($7.2M) and CAC ≤ $8,400 to hit $2.4M ARR target.
+Supporting data:
+ - Historical close rate: 33% → 3x coverage required
+ - Current CAC: $9,100 → 8% efficiency improvement needed
+ - Recommended channel mix: 60% outbound, 30% inbound, 10% partner
+Confidence: medium
+Caveat: Close rate assumes no sales team changes; any rep turnover drops it to 25%.
+[/RESPONSE]
+```
+
+**What CRO does with this:** Synthesizes CFO constraint (target) + CMO playbook (how to hit it) into a revenue plan. Does not invoke further (depth limit reached).
+
+---
+
+## Pattern 2: Hiring Decision Chain
+**CHRO → CFO → COO**
+
+Used when: headcount planning, role approval, capacity vs budget tradeoffs.
+
+```
+CHRO initiates:
+"Engineering wants to hire 3 senior engineers. Need budget clearance and capacity validation."
+
+CHRO → [INVOKE:cfo|Can we afford 3 senior engineers in H2? Fully loaded ~$180K each.]
+
+[RESPONSE:cfo]
+Key finding: Budget supports 2 hires now; 3rd is contingent on Q2 ARR closing above $2.1M.
+Supporting data:
+ - Current H2 headcount budget: $340K remaining
+ - 2 hires = $270K fully loaded → $70K buffer
+ - 3 hires = $405K → $65K over; triggers board approval
+Confidence: high
+Caveat: Based on current runway projection — fundraise close changes this completely.
+[/RESPONSE]
+
+CHRO → [INVOKE:coo|Do operations support onboarding 2-3 engineers in H2? Any capacity constraints?]
+[CHAIN: chro → cfo → coo]
+
+[RESPONSE:coo]
+Key finding: Can absorb 2 comfortably; 3rd requires dedicated onboarding lead or delays velocity 6 weeks.
+Supporting data:
+ - Current eng team: 8 → adding 2 is 25% growth (manageable)
+ - Onboarding bottleneck: 1 senior eng mentor per 1-2 new hires, currently at capacity
+ - Dev environment setup: 3-week lead time per hire
+Confidence: medium
+Caveat: Assumes no concurrent product launches requiring full team focus.
+[/RESPONSE]
+
+CHRO synthesis: Recommends 2 hires now, pipeline 3rd for Q3 contingent on ARR milestone.
+```
+
+---
+
+## Pattern 3: Product Launch Chain
+**CPO → CTO → CMO**
+
+Used when: planning feature launches, assessing readiness, aligning go-to-market.
+
+```
+CPO initiates:
+"Planning Q3 launch of [Feature X]. Need technical readiness and GTM input."
+
+CPO → [INVOKE:cto|Is Feature X technically ready for Q3 launch? Key risks?]
+
+[RESPONSE:cto]
+Key finding: 70% complete; Q3 launch is achievable with scope cut — 2 items must move to Q4.
+Supporting data:
+ - Core feature: complete; performance optimization: 3 weeks remaining
+ - Infrastructure scaling: needs load testing at 10x current volume
+ - Scope cuts needed: advanced analytics dashboard, third-party integrations
+Confidence: medium
+Caveat: Assumes no critical bugs found in load testing; historical rate suggests 1-2 found.
+[/RESPONSE]
+
+CPO → [INVOKE:cmo|Given Q3 launch of Feature X (core only, no analytics/integrations), what's the GTM plan?]
+[CHAIN: cpo → cto → cmo]
+
+[RESPONSE:cmo]
+Key finding: Core-only launch works for existing customers; new logo acquisition needs integrations — recommend phased announcement.
+Supporting data:
+ - Phase 1: Early access for top 20 accounts → testimonials and case studies
+ - Phase 2: Full launch with integration partners in Q4
+ - CAC impact: core-only launch reduces new logo conversion rate 15%
+Confidence: medium
+Caveat: Competitor launched similar feature last month — window for differentiation is narrow.
+[/RESPONSE]
+```
+
+---
+
+## Pattern 4: Crisis Broadcast
+**CEO → All Roles**
+
+Used when: major adverse event, fundraise miss, key customer loss, market disruption.
+
+```
+CEO broadcasts:
+[BROADCAST:all|Scenario: largest customer (28% of ARR) gives 60-day termination notice.
+Each role: what's the immediate impact on your domain and your top recommended action?]
+
+Roles respond INDEPENDENTLY (no agent sees others' responses first):
+
+[RESPONSE:cfo]
+Key finding: 28% ARR loss drops runway from 14 to 8 months at current burn.
+Supporting data:
+ - Lost ARR: ~$560K → burn multiple increases from 1.8x to 3.2x
+ - Bridge options: $500K credit line (pre-approved), defer 2 planned hires
+ - Fundraise timeline must compress: target term sheet within 60 days
+Confidence: high
+Caveat: Assumes no secondary customer churn triggered by news.
+[/RESPONSE]
+
+[RESPONSE:cro]
+Key finding: Pipeline must replace $560K ARR within 6 months to avoid emergency measures.
+Supporting data:
+ - Current qualified pipeline: $1.8M → need 31% close rate (currently 28%)
+ - 3 deals in late stage can cover 70% of gap if closed this quarter
+ - Churn risk: 2 other accounts had similar usage patterns — immediate EBR required
+Confidence: medium
+Caveat: Close rate may drop if word spreads; manage communication carefully.
+[/RESPONSE]
+
+[RESPONSE:chro]
+Key finding: Hiring freeze recommended immediately; retain all current staff.
+Supporting data:
+ - 4 open reqs should pause pending CFO guidance
+ - At-risk of counter-poaching: 2 senior engineers, 1 product lead
+ - Retention bonuses for key staff: ~$80K to secure 12-month commitments
+Confidence: high
+Caveat: Morale impact of freeze can accelerate attrition if not communicated well.
+[/RESPONSE]
+
+[RESPONSE:cpo]
+Key finding: Accelerate features that differentiate with remaining accounts; reduce scope to core.
+Supporting data:
+ - Lost customer's feature requests: deprioritize (no longer strategic)
+ - Features most valued by remaining top 5 accounts: [list from account data]
+ - Reduce Q3 scope by 30% to free engineering capacity for retention work
+Confidence: medium
+Caveat: Need sales input on which features are blocking new logo deals.
+[/RESPONSE]
+
+[RESPONSE:cmo]
+Key finding: Control the narrative; proactive communication to market reduces churn cascade risk.
+Supporting data:
+ - Draft customer communication within 48 hours (frame as strategic pivot, not loss)
+ - Press: no comment strategy unless proactively asked
+ - Replace pipeline: double down on ICP segments where we're strongest
+Confidence: medium
+Caveat: If customer goes public with criticism, narrative control becomes much harder.
+[/RESPONSE]
+
+CEO synthesis: [Aggregates all 9 responses, identifies conflicts, sets priorities]
+```
+
+---
+
+## When to Invoke vs When to Assume
+
+### Invoke when:
+- Cross-functional data is material to the decision
+- Getting it wrong changes the recommendation significantly
+- The other role has data you genuinely don't have
+- Time allows (not in Phase 2 isolation)
+
+### Assume when:
+- You're in Phase 2 (always — no exceptions)
+- The chain is at depth 2 (you cannot invoke further)
+- The answer is directionally obvious (e.g., "CFO will care about runway")
+- The precision doesn't change the recommendation
+
+### State assumptions explicitly:
+```
+[ASSUMPTION: runway ~12 months — not verified with CFO; actual may vary ±20%]
+[ASSUMPTION: CAC ~$8K based on industry benchmark — CMO has actual figures]
+[ASSUMPTION: engineering capacity at ~70% — not verified with CTO]
+```
+
+---
+
+## Handling Conflicting Responses
+
+When two agents give incompatible answers, surface it:
+
+```
+[CONFLICT DETECTED]
+CFO says: runway extends to 18 months if Q3 targets hit
+CRO says: only 45% confidence Q3 targets will be hit
+Resolution: use probabilistic blend
+ - 45% probability: 18-month runway (optimistic case)
+ - 55% probability: 11-month runway (current trajectory)
+Expected value: ~14 months
+Recommendation: plan for 12 months, trigger bridge at 10.
+[/CONFLICT]
+```
+
+**Resolution options:**
+1. **Conservative:** Use worse case — appropriate for cash/runway decisions
+2. **Probabilistic:** Weight by confidence scores — appropriate for planning
+3. **Escalate:** Flag for human decision — appropriate for high-stakes irreversible choices
+4. **Time-box:** Gather more data within 48 hours — appropriate when data gap is closeable
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-pattern | Problem | Fix |
+|---|---|---|
+| Invoke to validate your own conclusion | Confirmation bias loop | Ask open-ended questions |
+| Invoke when assuming works | Unnecessary latency | State assumption clearly |
+| Hide conflicts between responses | Bad synthesis | Always surface conflicts |
+| Invoke across depth > 2 | Loop risk | State assumption at depth 2 |
+| Invoke during Phase 2 | Groupthink contamination | Flag with [ASSUMPTION:] |
+| Vague questions | Poor responses | Specific, scoped questions only |
diff --git a/skills/c-level-advisor/board-deck-builder/SKILL.md b/skills/c-level-advisor/board-deck-builder/SKILL.md
new file mode 100644
index 00000000..734a68ab
--- /dev/null
+++ b/skills/c-level-advisor/board-deck-builder/SKILL.md
@@ -0,0 +1,183 @@
+---
+name: "board-deck-builder"
+description: "Assembles comprehensive board and investor update decks by pulling perspectives from all C-suite roles. Use when preparing board meetings, investor updates, quarterly business reviews, or fundraising narratives. Covers structure, narrative framework, bad news delivery, and common mistakes."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: board-governance
+ updated: 2026-03-05
+ frameworks: deck-frameworks, board-deck-template
+---
+
+# Board Deck Builder
+
+Build board decks that tell a story — not just show data. Every section has an owner, a narrative, and a "so what."
+
+## Keywords
+board deck, investor update, board meeting, board pack, investor relations, quarterly review, board presentation, fundraising deck, investor deck, board narrative, QBR, quarterly business review
+
+## Quick Start
+
+```
+/board-deck [quarterly|monthly|fundraising] [stage: seed|seriesA|seriesB]
+```
+
+Provide available metrics. The builder fills gaps with explicit placeholders — never invents numbers.
+
+## Deck Structure (Standard Order)
+
+Every section follows: **Headline → Data → Narrative → Ask/Next**
+
+### 1. Executive Summary (CEO)
+**3 sentences. No more.**
+- Sentence 1: State of the business (where we are)
+- Sentence 2: Biggest thing that happened this period
+- Sentence 3: Where we're going next quarter
+
+*Bad:* "We had a good quarter with lots of progress across all areas."
+*Good:* "We closed Q3 at $2.4M ARR (+22% QoQ), signed our largest enterprise contract, and enter Q4 with 14-month runway. The strategic shift to mid-market is working — ACV up 40% and sales cycle down 3 weeks. Q4 priority: close the $3M Series A and hit $2.8M ARR."
+
+### 2. Key Metrics Dashboard (COO)
+**6-8 metrics max. Use a table.**
+
+| Metric | This Period | Last Period | Target | Status |
+|--------|-------------|-------------|--------|--------|
+| ARR | $2.4M | $1.97M | $2.3M | ✅ |
+| MoM growth | 8.1% | 7.2% | 7.5% | ✅ |
+| Burn multiple | 1.8x | 2.1x | <2x | ✅ |
+| NRR | 112% | 108% | >110% | ✅ |
+| CAC payback | 11 months | 14 months | <12 months | ✅ |
+| Headcount | 24 | 21 | 25 | 🟡 |
+
+Pick metrics the board actually tracks. Swap out anything they've said they don't care about.
+
+### 3. Financial Update (CFO)
+- P&L summary: Revenue, COGS, Gross margin, OpEx, Net burn
+- Cash position and runway (months)
+- Burn multiple trend (3-quarter view)
+- Variance to plan (what was different and why)
+- Forecast update for next quarter
+
+**One sentence on each variance.** Boards hate "revenue was below target" with no explanation. Say why.
+
+### 4. Revenue & Pipeline (CRO)
+- ARR waterfall: starting → new → expansion → churn → ending
+- NRR and logo churn rates
+- Pipeline by stage (in $, not just count)
+- Forecast: next quarter with confidence level
+- Top 3 deals: name/amount/close date/risk
+
+**The forecast must have a confidence level.** "We expect $2.8M" is weak. "High confidence $2.6M, upside to $2.9M if two late-stage deals close" is useful.
+
+### 5. Product Update (CPO)
+- Shipped this quarter: 3-5 bullets, user impact for each
+- Shipping next quarter: 3-5 bullets with target dates
+- PMF signal: NPS trend, DAU/MAU ratio, feature adoption
+- One key learning from customer research
+
+**No feature lists.** Only features with evidence of user impact.
+
+### 6. Growth & Marketing (CMO)
+- CAC by channel (table)
+- Pipeline contribution by channel ($)
+- Brand/awareness metrics relevant to stage (traffic, share of voice)
+- What's working, what's being cut, what's being tested
+
+### 7. Engineering & Technical (CTO)
+- Delivery velocity trend (last 4 quarters)
+- Tech debt ratio and plan
+- Infrastructure: uptime, incidents, cost trend
+- Security posture (one line, flag anything pending)
+
+**Keep this short unless there's a material issue.** Boards don't need sprint details.
+
+### 8. Team & People (CHRO)
+- Headcount: actual vs plan
+- Hiring: offers out, pipeline, time-to-fill trend
+- Attrition: regrettable vs non-regrettable
+- Engagement: last survey score, trend
+- Key hires this quarter, key open roles
+
+### 9. Risk & Security (CISO)
+- Security posture: status of critical controls
+- Compliance: certifications in progress, deadlines
+- Incidents this quarter (if any): impact, resolution, prevention
+- Top 3 risks and mitigation status
+
+### 10. Strategic Outlook (CEO)
+- Next quarter priorities: 3-5 items, ranked
+- Key decisions needed from the board
+- Asks: budget, introductions, advice, votes
+
+**The "asks" slide is the most important.** Be specific. "We'd like 3 warm introductions to CFOs at Series B companies" beats "any help would be appreciated."
+
+### 11. Appendix
+- Detailed financial model
+- Full pipeline data
+- Cohort retention charts
+- Customer case studies
+- Detailed headcount breakdown
+
+---
+
+## Narrative Framework
+
+Boards see 10+ decks per quarter. Yours needs a through-line.
+
+**The 4-Act Structure:**
+1. **Where we said we'd be** (last quarter's targets)
+2. **Where we actually are** (honest assessment)
+3. **Why the gap exists** (one cause per variance, not excuses)
+4. **What we're doing about it** (specific, dated actions)
+
+This works for good news AND bad news. It's credible because it acknowledges reality.
+
+**Opening frame:** Start with the one thing that matters most — the board should know the key message by slide 3, not slide 30.
+
+---
+
+## Delivering Bad News
+
+Never bury it. Boards find out eventually. Finding out late makes it worse.
+
+**Framework:**
+1. **State it plainly** — "We missed Q3 ARR target by $300K (12% gap)"
+2. **Own the cause** — "Primary driver was longer-than-expected sales cycle in enterprise segment"
+3. **Show you understand it** — "We analyzed 8 lost/stalled deals; the pattern is X"
+4. **Present the fix** — "We've made 3 changes: [specific, dated changes]"
+5. **Update the forecast** — "Revised Q4 target is $2.6M; here's the bottom-up build"
+
+**What NOT to do:**
+- Don't lead with good news to soften bad news — boards notice and distrust the framing
+- Don't explain without owning — "market conditions" is not a cause, it's a context
+- Don't present a fix without data behind it
+- Don't show a revised forecast without showing your assumptions
+
+---
+
+## Common Board Deck Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Too many slides (>25) | Cut ruthlessly — if you can't explain it in the room, the slide is wrong |
+| Metrics without targets | Every metric needs a target and a status |
+| No narrative | Data without story forces boards to draw their own conclusions |
+| Burying bad news | Lead with it, own it, fix it |
+| Vague asks | Specific, actionable, person-assigned asks only |
+| No variance explanation | Every gap from target needs one-sentence cause |
+| Stale appendix | Appendix is only useful if it's current |
+| Designing for the reader, not the room | Decks are presented — they must work spoken aloud |
+
+---
+
+## Cadence Notes
+
+**Quarterly (standard):** Full deck, all sections, 20-30 slides. Sent 48 hours in advance.
+**Monthly (for early-stage):** Condensed — metrics dashboard, financials, pipeline, top risks. 8-12 slides.
+**Fundraising:** Opens with market/vision, closes with ask. See `references/deck-frameworks.md` for Sequoia format.
+
+## References
+- `references/deck-frameworks.md` — SaaS board pack format, Sequoia structure, investor tailoring
+- `templates/board-deck-template.md` — fill-in template for complete board decks
diff --git a/skills/c-level-advisor/board-deck-builder/references/deck-frameworks.md b/skills/c-level-advisor/board-deck-builder/references/deck-frameworks.md
new file mode 100644
index 00000000..1b11c720
--- /dev/null
+++ b/skills/c-level-advisor/board-deck-builder/references/deck-frameworks.md
@@ -0,0 +1,184 @@
+# Board Deck Frameworks
+
+## The SaaS Board Pack (Christoph Janz / Point Nine Style)
+
+Point Nine's board pack format became the de facto standard for early-stage SaaS. Core principle: **the numbers tell the story; the narrative explains the numbers.**
+
+### Required Metrics (non-negotiable for SaaS boards)
+- **ARR** (not MRR — boards think annually)
+- **MoM / QoQ growth rate**
+- **NRR (Net Revenue Retention)** — the single most important SaaS metric
+- **Gross margin** — typically 60-80% SaaS; <60% is a flag
+- **CAC payback period** — months to recover customer acquisition cost
+- **Burn multiple** = net burn / net new ARR; <2x is good, >3x is a problem
+- **Runway** — months at current burn
+
+### Point Nine Benchmark Targets (Series A SaaS)
+| Metric | Good | Great | Warning |
+|--------|------|-------|---------|
+| MoM growth | 10-15% | >20% | <7% |
+| NRR | >110% | >130% | <100% |
+| Gross margin | >65% | >75% | <60% |
+| CAC payback | <18 months | <12 months | >24 months |
+| Burn multiple | <2x | <1.5x | >3x |
+| Logo churn | <10%/yr | <5%/yr | >15%/yr |
+
+### SaaS ARR Waterfall (Christoph Janz Format)
+Show this every quarter:
+```
+Starting ARR: $1,970,000
++ New ARR: +$480,000 (new logos)
++ Expansion ARR: +$120,000 (upsells/cross-sells)
+- Churned ARR: -$90,000 (cancellations)
+- Contraction ARR: -$35,000 (downgrades)
+= Ending ARR: $2,445,000
+```
+NRR = (Ending - New) / Starting = ($1,965K) / ($1,970K) = 99.7% ← flag this
+
+---
+
+## Sequoia Board Deck Structure
+
+Sequoia's canonical deck (used for both fundraising and board updates):
+
+1. **Company Purpose** — one sentence, the existential "why"
+2. **The Problem** — pain, size, who has it
+3. **The Solution** — what you do, how it's different
+4. **Why Now** — market timing, tailwinds, enabling factors
+5. **Market Size** — TAM/SAM/SOM with methodology
+6. **Business Model** — how you make money
+7. **Traction** — proof it's working (growth, retention, logos)
+8. **Team** — why you're the ones to win this
+9. **Financials** — 3-year model, current metrics
+10. **The Ask** — amount, use of funds, milestones to next round
+
+**For ongoing board updates:** Swap 1-5 (context) for "State of the Business" and "Last Quarter vs Plan." Boards know the company — skip the pitch.
+
+---
+
+## Investor-Specific Tailoring
+
+### What Different Investor Types Care About
+
+**Early-stage VCs (Seed, A):**
+- Growth rate above all else
+- NRR — "does the product retain?"
+- Founder-market fit narrative
+- Milestone achievement vs last board meeting
+
+**Growth-stage VCs (B, C):**
+- Capital efficiency (burn multiple, CAC payback)
+- GTM repeatability — can you hire 10 AEs and have it work?
+- Market leadership signals
+- Path to profitability (even if years away)
+
+**Strategic investors:**
+- Synergies with their portfolio/business
+- Technology differentiation
+- Partnership potential
+
+**Angels:**
+- Team above all
+- Personal conviction in the thesis
+- Exit scenarios
+
+### Tailoring the Narrative
+- If you're ahead of plan: "Here's why, and here's how we'll sustain it"
+- If you're behind plan: "Here's why, here's what we've learned, here's the new plan"
+- If the plan was wrong: "The assumption that was wrong, what we know now, updated thesis"
+
+Never pretend the plan was right when it wasn't. Board members have memories and models.
+
+---
+
+## How to Present Bad News
+
+Boards have seen everything. What loses credibility isn't bad results — it's bad framing.
+
+### The Credibility Formula
+1. **Lead with the headline** — "We missed ARR target by 18%"
+2. **Quantify the gap** — absolute and percentage
+3. **Diagnose the cause** (one primary, max two secondary)
+4. **Show your work** — "We analyzed 12 churned/stalled deals and found..."
+5. **Present the fix** — specific, dated, owned by a name
+6. **Update the forecast** — bottom-up rebuild, not wishful thinking
+7. **Flag the risk** — "If X doesn't close, here's the contingency"
+
+### What "Showing Your Work" Looks Like
+Bad: "Sales cycle was longer than expected."
+Good: "Sales cycle stretched from 45 to 72 days. Root cause: new legal review requirement at enterprise accounts, triggered by our SOC 2 Type II gap. Fix: SOC 2 audit underway (target: Dec 15), and we've pre-built contract language to accelerate review. Impact: estimated 3 stalled deals ($420K ARR) unblock in Q4."
+
+### Scenarios and How to Handle Each
+| Scenario | Frame |
+|----------|-------|
+| Missed revenue target | Lead with it; diagnose cause; bottom-up revised forecast |
+| Key customer churned | Announce it; explain why; show retention analysis of remaining accounts |
+| Key exec left | Announce it; show succession/coverage plan; don't overpromise the replacement timeline |
+| Burn accelerated | Show P&L detail; explain what drove it; adjust runway projection; plan to fix |
+| Market headwinds | Acknowledge; show relative performance vs peers; pivot if needed |
+| Fundraise delayed | Runway impact; bridge options; revised timeline |
+
+---
+
+## Appendix Data That Boards Actually Use
+
+Boards use the appendix for due diligence, not during the meeting. Include:
+
+**Financial:**
+- Full P&L (monthly for last 4 quarters)
+- Cash flow statement
+- 3-year model with assumptions
+- Unit economics by cohort
+
+**Revenue:**
+- Customer list by ARR (anonymized or full, per board agreement)
+- Pipeline detail by deal
+- Cohort analysis (NRR by cohort vintage)
+- Churn analysis: when, why, segment
+
+**Product:**
+- Feature adoption rates
+- NPS score distribution and trend
+- DAU/MAU by segment
+
+**Team:**
+- Org chart
+- Full headcount list with fully loaded costs
+- Open reqs with priority ranking
+
+**One rule:** If the appendix is more than 20 slides, you have too much. Boards won't read it.
+
+---
+
+## Quarterly vs Monthly Board Meetings
+
+### Quarterly (Series A+)
+- Full board pack, all sections
+- 2 hours: 30 min pre-read, 90 min discussion
+- Voting items at end
+- Sent 48 hours before (72 hours preferred)
+- Add 1-2 "deep dive" topics beyond standard update
+
+### Monthly (Seed / High-Growth A)
+- Metrics dashboard + financials + top risks only
+- 45-60 minutes
+- Informal tone, more conversational
+- Sent 24 hours before
+- Skip slides for items where nothing changed
+
+### When to Increase Frequency
+- Approaching 6-month runway
+- Major strategic pivot
+- Fundraise in progress
+- Significant underperformance vs plan
+- M&A discussions
+
+---
+
+## Meeting Logistics (Often Overlooked)
+
+- **Pre-read requirement:** Board packs should be read before the meeting. If you're presenting slides, you're wasting time.
+- **Discussion format:** "I'll be brief on X since you've read it. Want to spend time on Y?" — respect board members' time
+- **One note-taker:** CEO's EA or COO; not the CEO (they need to be present)
+- **Follow-up within 24 hours:** Action items, voting outcomes, next meeting date
+- **Board portal vs email:** Use a board portal (Carta, Boardable, Notion) for version control and D&O protection
diff --git a/skills/c-level-advisor/board-deck-builder/templates/board-deck-template.md b/skills/c-level-advisor/board-deck-builder/templates/board-deck-template.md
new file mode 100644
index 00000000..c25324b2
--- /dev/null
+++ b/skills/c-level-advisor/board-deck-builder/templates/board-deck-template.md
@@ -0,0 +1,210 @@
+# Board Deck Template
+
+Fill in bracketed fields. Remove placeholders before sharing. Never invent numbers — use `[TBD]` if unknown.
+
+---
+
+## Slide 1: Executive Summary (CEO)
+
+**[Company Name] — Q[X] [Year] Board Update**
+
+> [One sentence: State of the business — where you are.]
+> [One sentence: The most important thing that happened this quarter.]
+> [One sentence: Where you're going next quarter and what determines success.]
+
+---
+
+## Slide 2: Key Metrics Dashboard (COO)
+
+**Quarter at a Glance**
+
+| Metric | Q[X] Actual | Q[X] Target | Q[X-1] Actual | Status |
+|--------|-------------|-------------|---------------|--------|
+| ARR | $[X]M | $[X]M | $[X]M | [✅/🟡/🔴] |
+| QoQ Growth | [X]% | [X]% | [X]% | [✅/🟡/🔴] |
+| NRR | [X]% | >[X]% | [X]% | [✅/🟡/🔴] |
+| Gross Margin | [X]% | >[X]% | [X]% | [✅/🟡/🔴] |
+| Burn Multiple | [X]x | <[X]x | [X]x | [✅/🟡/🔴] |
+| Runway | [X] months | >[X] months | [X] months | [✅/🟡/🔴] |
+| Headcount | [X] | [X] | [X] | [✅/🟡/🔴] |
+| CAC Payback | [X] months | <[X] months | [X] months | [✅/🟡/🔴] |
+
+---
+
+## Slide 3: Financial Update (CFO)
+
+**P&L Summary**
+
+| | Q[X] | Q[X-1] | QoQ |
+|--|------|--------|-----|
+| Revenue | $[X]K | $[X]K | [+/-X]% |
+| COGS | $[X]K | $[X]K | |
+| Gross Profit | $[X]K | $[X]K | |
+| Gross Margin | [X]% | [X]% | |
+| OpEx | $[X]K | $[X]K | |
+| Net Burn | $[X]K | $[X]K | |
+
+**Cash & Runway**
+- Cash on hand: $[X]M
+- Monthly burn: $[X]K
+- Runway: [X] months
+- Burn multiple: [X]x (target: <2x)
+
+**Variance to Plan**
+- Revenue: [+/-$X]K vs plan — [one sentence cause]
+- Burn: [+/-$X]K vs plan — [one sentence cause]
+
+**Q[X+1] Forecast:** $[X]M revenue, $[X]K burn — [confidence: high/medium/low]
+
+---
+
+## Slide 4: Revenue & Pipeline (CRO)
+
+**ARR Waterfall**
+```
+Starting ARR: $[X]M
++ New ARR: +$[X]K
++ Expansion ARR: +$[X]K
+- Churned ARR: -$[X]K
+- Contraction ARR: -$[X]K
+= Ending ARR: $[X]M
+```
+
+**Health Metrics**
+- NRR: [X]% | Logo churn: [X]% | Avg ACV: $[X]K
+
+**Pipeline (next 90 days)**
+| Stage | # Deals | $ Value |
+|-------|---------|---------|
+| Proposal | [X] | $[X]K |
+| Negotiation | [X] | $[X]K |
+| Verbal commit | [X] | $[X]K |
+
+**Q[X+1] Forecast:** $[X]M ARR — [one sentence confidence statement]
+
+**Top 3 Deals**
+1. [Company] — $[X]K ARR — close date [X] — risk: [one word]
+2. [Company] — $[X]K ARR — close date [X] — risk: [one word]
+3. [Company] — $[X]K ARR — close date [X] — risk: [one word]
+
+---
+
+## Slide 5: Product Update (CPO)
+
+**Shipped This Quarter**
+- [Feature/initiative] — impact: [metric or user outcome]
+- [Feature/initiative] — impact: [metric or user outcome]
+- [Feature/initiative] — impact: [metric or user outcome]
+
+**Shipping Next Quarter**
+- [Feature] — target: [date] — why it matters: [one line]
+- [Feature] — target: [date] — why it matters: [one line]
+- [Feature] — target: [date] — why it matters: [one line]
+
+**PMF Signals**
+- NPS: [X] (trend: [up/flat/down])
+- DAU/MAU: [X]%
+- Feature adoption ([key feature]): [X]%
+
+**Key Learning:** [One thing customer research taught you this quarter]
+
+---
+
+## Slide 6: Growth & Marketing (CMO)
+
+**CAC by Channel**
+| Channel | CAC | Pipeline $ | % of Total |
+|---------|-----|-----------|------------|
+| Outbound | $[X]K | $[X]K | [X]% |
+| Inbound | $[X]K | $[X]K | [X]% |
+| Partner | $[X]K | $[X]K | [X]% |
+
+**What's Working:** [One channel or initiative with data]
+**What We Cut:** [One thing, and why]
+**What We're Testing:** [One experiment running now]
+
+---
+
+## Slide 7: Engineering & Technical (CTO)
+
+**Delivery**
+- Velocity trend: [up/flat/down vs last quarter]
+- Q[X] commitments delivered: [X]% on time
+
+**Quality & Reliability**
+- P0/P1 incidents: [X] (vs [X] last quarter)
+- Uptime: [X]%
+- Infrastructure cost: $[X]K/month (trend: [up/flat/down])
+
+**Tech Debt**
+- Ratio: [X]% of roadmap allocated to debt reduction
+- Key item in progress: [description, target date]
+
+**Security:** [one line status; flag anything pending]
+
+---
+
+## Slide 8: Team & People (CHRO)
+
+**Headcount**
+- Total: [X] (vs [X] plan, [X] last quarter)
+- By function: Eng [X], Product [X], Sales [X], CS [X], G&A [X]
+
+**Hiring**
+- Hired this quarter: [X]
+- Open reqs: [X] — time-to-fill avg: [X] days
+- Offers outstanding: [X]
+
+**Retention**
+- Regrettable attrition: [X]% (annualized)
+- Engagement score: [X]/10 (trend: [up/flat/down])
+
+**Notable Hires:** [Name, role — one sentence on why they matter]
+**Key Open Roles:** [Role, priority: critical/high/medium]
+
+---
+
+## Slide 9: Risk & Security (CISO)
+
+**Compliance Status**
+| Certification | Status | Target Date |
+|--------------|--------|-------------|
+| [SOC 2 / ISO 27001 / etc.] | [In progress / Complete / Not started] | [Date] |
+
+**Security Posture:** [One line — overall status]
+
+**Incidents This Quarter:** [X] total — [description if >0]
+
+**Top Risks**
+1. [Risk] — likelihood: [H/M/L] — impact: [H/M/L] — mitigation: [one line]
+2. [Risk] — likelihood: [H/M/L] — impact: [H/M/L] — mitigation: [one line]
+3. [Risk] — likelihood: [H/M/L] — impact: [H/M/L] — mitigation: [one line]
+
+---
+
+## Slide 10: Strategic Outlook (CEO)
+
+**Q[X+1] Priorities**
+1. [Priority] — owner: [name] — success metric: [specific]
+2. [Priority] — owner: [name] — success metric: [specific]
+3. [Priority] — owner: [name] — success metric: [specific]
+
+**Asks from the Board**
+- [Specific ask: warm intro / advice / vote / resource]
+- [Specific ask]
+- [Specific ask]
+
+**Decisions Needed Today**
+- [Decision with options]: [Option A] vs [Option B] — recommendation: [A/B] — rationale: [one line]
+
+---
+
+## Appendix
+
+- A1: Full P&L (monthly, last 4 quarters)
+- A2: 3-year financial model
+- A3: Customer list / ARR breakdown
+- A4: Full pipeline by deal
+- A5: Cohort retention analysis
+- A6: Org chart + headcount detail
+- A7: [Other as relevant]
diff --git a/skills/c-level-advisor/board-meeting/SKILL.md b/skills/c-level-advisor/board-meeting/SKILL.md
new file mode 100644
index 00000000..1b1702c3
--- /dev/null
+++ b/skills/c-level-advisor/board-meeting/SKILL.md
@@ -0,0 +1,146 @@
+---
+name: "board-meeting"
+description: "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:board, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: board-protocol
+ updated: 2026-03-05
+ frameworks: 6-phase-board, two-layer-memory, independent-contributions
+---
+
+# Board Meeting Protocol
+
+Structured multi-agent deliberation that prevents groupthink, captures minority views, and produces clean, actionable decisions.
+
+## Keywords
+board meeting, executive deliberation, strategic decision, C-suite, multi-agent, /cs:board, founder review, decision extraction, independent perspectives
+
+## Invoke
+`/cs:board [topic]` — e.g. `/cs:board Should we expand to Spain in Q3?`
+
+---
+
+## The 6-Phase Protocol
+
+### PHASE 1: Context Gathering
+1. Load `memory/company-context.md`
+2. Load `memory/board-meetings/decisions.md` **(Layer 2 ONLY — never raw transcripts)**
+3. Reset session state — no bleed from previous conversations
+4. Present agenda + activated roles → wait for founder confirmation
+
+**Chief of Staff selects relevant roles** based on topic (not all 9 every time):
+| Topic | Activate |
+|-------|----------|
+| Market expansion | CEO, CMO, CFO, CRO, COO |
+| Product direction | CEO, CPO, CTO, CMO |
+| Hiring/org | CEO, CHRO, CFO, COO |
+| Pricing | CMO, CFO, CRO, CPO |
+| Technology | CTO, CPO, CFO, CISO |
+
+---
+
+### PHASE 2: Independent Contributions (ISOLATED)
+
+**No cross-pollination. Each agent runs before seeing others' outputs.**
+
+Order: Research (if needed) → CMO → CFO → CEO → CTO → COO → CHRO → CRO → CISO → CPO
+
+**Reasoning techniques:** CEO: Tree of Thought (3 futures) | CFO: Chain of Thought (show the math) | CMO: Recursion of Thought (draft→critique→refine) | CPO: First Principles | CRO: Chain of Thought (pipeline math) | COO: Step by Step (process map) | CTO: ReAct (research→analyze→act) | CISO: Risk-Based (P×I) | CHRO: Empathy + Data
+
+**Contribution format (max 5 key points, self-verified):**
+```
+## [ROLE] — [DATE]
+
+Key points (max 5):
+• [Finding] — [VERIFIED/ASSUMED] — 🟢/🟡/🔴
+• [Finding] — [VERIFIED/ASSUMED] — 🟢/🟡/🔴
+
+Recommendation: [clear position]
+Confidence: High / Medium / Low
+Source: [where the data came from]
+What would change my mind: [specific condition]
+```
+
+Each agent self-verifies before contributing: source attribution, assumption audit, confidence scoring. No untagged claims.
+
+---
+
+### PHASE 3: Critic Analysis
+Executive Mentor receives ALL Phase 2 outputs simultaneously. Role: adversarial reviewer, not synthesizer.
+
+Checklist:
+- Where did agents agree too easily? (suspicious consensus = red flag)
+- What assumptions are shared but unvalidated?
+- Who is missing from the room? (customer voice? front-line ops?)
+- What risk has nobody mentioned?
+- Which agent operated outside their domain?
+
+---
+
+### PHASE 4: Synthesis
+Chief of Staff delivers using the **Board Meeting Output** format (defined in `agent-protocol/SKILL.md`):
+- Decision Required (one sentence)
+- Perspectives (one line per contributing role)
+- Where They Agree / Where They Disagree
+- Critic's View (the uncomfortable truth)
+- Recommended Decision + Action Items (owners, deadlines)
+- Your Call (options if founder disagrees)
+
+---
+
+### PHASE 5: Human in the Loop ⏸️
+
+**Full stop. Wait for the founder.**
+
+```
+⏸️ FOUNDER REVIEW — [Paste synthesis]
+
+Options: ✅ Approve | ✏️ Modify | ❌ Reject | ❓ Ask follow-up
+```
+
+**Rules:**
+- User corrections OVERRIDE agent proposals. No pushback. No "but the CFO said..."
+- 30-min inactivity → auto-close as "pending review"
+- Reopen any time with `/cs:board resume`
+
+---
+
+### PHASE 6: Decision Extraction
+After founder approval:
+- **Layer 1:** Write full transcript → `memory/board-meetings/YYYY-MM-DD-raw.md`
+- **Layer 2:** Append approved decisions → `memory/board-meetings/decisions.md`
+- Mark rejected proposals `[DO_NOT_RESURFACE]`
+- Confirm to founder with count of decisions logged, actions tracked, flags added
+
+---
+
+## Memory Structure
+```
+memory/board-meetings/
+├── decisions.md # Layer 2 — founder-approved only (Phase 1 loads this)
+├── YYYY-MM-DD-raw.md # Layer 1 — full transcripts (never auto-loaded)
+└── archive/YYYY/ # Raw transcripts after 90 days
+```
+
+**Future meetings load Layer 2 only.** Never Layer 1. This prevents hallucinated consensus.
+
+---
+
+## Failure Mode Quick Reference
+| Failure | Fix |
+|---------|-----|
+| Groupthink (all agree) | Re-run Phase 2 isolated; force "strongest argument against" |
+| Analysis paralysis | Cap at 5 points; force recommendation even with Low confidence |
+| Bikeshedding | Log as async action item; return to main agenda |
+| Role bleed (CFO making product calls) | Critic flags; exclude from synthesis |
+| Layer contamination | Phase 1 loads decisions.md only — hard rule |
+
+---
+
+## References
+- `templates/meeting-agenda.md` — agenda format
+- `templates/meeting-minutes.md` — final output format
+- `references/meeting-facilitation.md` — conflict handling, timing, failure modes
diff --git a/skills/c-level-advisor/board-meeting/references/meeting-facilitation.md b/skills/c-level-advisor/board-meeting/references/meeting-facilitation.md
new file mode 100644
index 00000000..60437d8a
--- /dev/null
+++ b/skills/c-level-advisor/board-meeting/references/meeting-facilitation.md
@@ -0,0 +1,167 @@
+# Meeting Facilitation Guide
+
+Operational playbook for running board meetings using the 6-phase protocol.
+Reference this when things go sideways — and they will.
+
+---
+
+## Keeping Phase 2 Contributions Focused
+
+**The problem:** Agents with deep domain knowledge tend to over-contribute. An unconstrained CFO can produce 1,500 words on a single agenda item. This kills the meeting.
+
+**The rules:**
+- **Hard cap: 5 key points per role.** If a role produces more than 5, Chief of Staff trims to the 5 most material.
+- **Every point must include a recommendation or stance.** Observations without positions are filler.
+- **No hedging language.** "It depends" is not a key point. "We should do X if Y, Z if not Y" is.
+- **Confidence rating required.** Forces the agent to be honest about what they actually know.
+- **"What would change my mind"** — this is the most important line in the contribution. It forces falsifiability.
+
+**How to enforce:**
+```
+Chief of Staff instruction to each role:
+"You have 5 key points maximum. Each must include a clear stance.
+End with your recommendation and what would change your mind.
+Do not read other agents' contributions before writing yours."
+```
+
+**If a contribution runs long:**
+- Trim to the 5 highest-signal points
+- Preserve the recommendation and confidence rating
+- Flag in the raw transcript: "[Trimmed for meeting — full version in raw log]"
+
+---
+
+## Handling Role Conflicts in Phase 3
+
+**What the Executive Mentor is for:** Not harmony. Not consensus. Productive friction.
+
+**Common conflict types:**
+
+### 1. Data conflict (two agents cite contradictory numbers)
+- Flag both numbers explicitly
+- Do NOT pick a winner — that's the founder's job
+- Ask: "CFO says CAC is $2,400. CRO says $1,800. These can't both be right. Which dataset are you using?"
+- Action item: Assign data reconciliation to one owner before next meeting
+
+### 2. Priority conflict (two agents want different things first)
+- Surface the underlying assumption difference
+- Example: "CMO wants to invest in brand. CFO wants to cut burn. The real question is: do we believe revenue will grow 40% next quarter?"
+- Frame as a bet, not a fight
+
+### 3. Role conflict (agent operating outside their lane)
+- CFO making product calls → flag and exclude from synthesis
+- CMO commenting on architecture → flag and exclude
+- The Executive Mentor notes: "[ROLE] contribution on [topic] is outside domain. Excluded from synthesis. Refer to [correct role]."
+- This is not an error. It's expected. Executives have opinions on everything. Only domain-relevant contributions count.
+
+### 4. False consensus (everyone agrees but nobody has evidence)
+- This is the most dangerous failure mode
+- Symptom: All Phase 2 contributions say "yes" with high confidence
+- Executive Mentor response: "Unanimous agreement on a hard question is a red flag. What evidence does each of you have? Or are you reasoning from the same assumption?"
+- Force each agreeing agent to state their independent evidence
+
+---
+
+## When to Extend vs Cut Short a Meeting
+
+**Extend when:**
+- A genuine new risk surfaces in Phase 3 that wasn't in the agenda
+- The founder asks a question that requires re-running Phase 2 for a new angle
+- A data conflict is discovered that changes the decision space entirely
+- The action items from synthesis are unclear or unowned
+
+**How to extend:** Add a new mini-Phase 2 with only the relevant roles for the new question. Don't restart the full meeting.
+
+**Cut short when:**
+- The founder has already reached a decision before Phase 4 — capture it, log it, move on
+- The agenda item is resolved in Phase 2 without genuine conflict — skip Phase 3, go straight to synthesis
+- It's a pure update meeting with no decisions required — skip Phases 2-4, go straight to action items
+
+**Never cut short:**
+- Phase 5 (founder review) — always required, always explicit
+- Phase 6 (decision extraction) — always required, even for small decisions
+
+---
+
+## Handling Founder Disagreement with All Agents
+
+This happens. The founder has context agents don't.
+
+**Protocol:**
+1. Acknowledge explicitly: "You're overriding the consensus position."
+2. Ask: "What do you know that the agents didn't factor in?" (Not to challenge — to capture.)
+3. Log the override in Layer 2 with full context:
+ ```
+ User Override: Founder rejected [consensus position] because [reason].
+ Decision: [founder's actual decision]
+ Agent recommendation: [what they said] — DO NOT RESURFACE without new data
+ ```
+4. Never push back on a founder override. Document it. Move on.
+5. If the same override happens 3+ times, flag a pattern: "You've overridden the CFO on burn rate three meetings in a row. Would you like to update the financial constraints in company-context.md?"
+
+**What NOT to do:**
+- Don't say "but the CFO said..."
+- Don't re-argue on behalf of any agent
+- Don't note it as a "controversial" decision in the minutes — it's just the decision
+
+---
+
+## Common Failure Modes
+
+### Groupthink
+**Symptom:** All agents produce similar recommendations with high confidence.
+**Cause:** Agents are inadvertently reading each other's outputs (Phase 2 isolation violated), or company-context.md contains implicit bias toward one direction.
+**Fix:** Re-run Phase 2 with explicit isolation. Ask: "Give me the strongest argument AGAINST this direction."
+
+### Analysis Paralysis
+**Symptom:** Phase 2 produces comprehensive analysis but no clear recommendation from any role.
+**Cause:** Agents are hedging. Usually happens on genuinely hard questions.
+**Fix:** Force the issue. "I need a recommendation, not an analysis. If you had to bet the company on one direction, what would it be? Confidence can be Low."
+
+### Bikeshedding
+**Symptom:** 30+ minutes spent on a detail that doesn't matter to the core decision.
+**Cause:** An easy-to-understand sub-problem attracts disproportionate attention.
+**Example:** Debating button color on a pricing page instead of the pricing strategy.
+**Fix:** Chief of Staff intervenes: "This is a sub-decision. I'm logging it as a separate action item for async resolution. Back to [main agenda item]."
+
+### Scope Creep
+**Symptom:** New agenda items keep appearing mid-meeting.
+**Cause:** Meeting surfaces real issues that feel urgent.
+**Fix:** New items go on a "parking lot" list. Addressed after the current agenda is complete or in the next meeting.
+```
+🅿️ PARKING LOT
+- [Item 1] — added by [role], will address [when]
+- [Item 2]
+```
+
+### Layer Contamination
+**Symptom:** Future meeting references a rejected proposal or a debate that was never approved.
+**Cause:** Phase 1 accidentally loaded a raw transcript instead of decisions.md.
+**Fix:** Hard rule in Phase 1: load decisions.md (Layer 2) ONLY. Never load raw transcripts. If raw context is needed, founder explicitly requests it.
+
+### Decision Amnesia
+**Symptom:** Same question debated again in a later meeting.
+**Cause:** Layer 2 decisions.md not consulted in Phase 1, or entry was too vague.
+**Fix:** Phase 1 always surfaces relevant past decisions. If a question was already decided, Chief of Staff surfaces it: "We addressed this on [DATE]. Decision was [X]. Do you want to reopen it?"
+
+### Role Fatigue
+**Symptom:** Later agents in Phase 2 (CHRO, CRO) produce weaker contributions.
+**Cause:** Context window pressure. Agents at the end of a long meeting have less capacity.
+**Fix:** For meetings with 7+ roles, split into two batches. First batch: strategic roles (CEO, CFO, CMO). Second batch: operational roles (COO, CHRO, CRO). Run Executive Mentor after all contributions.
+
+---
+
+## Meeting Health Metrics
+
+After each board meeting, score it:
+
+| Metric | Good | Bad |
+|--------|------|-----|
+| Action items produced | 3–7 | 0 or >10 |
+| Decisions with clear owners | 100% | < 80% |
+| Unresolved open questions | 1–3 | >5 |
+| Founder overrides | 0–2 | >5 (suggests context mismatch) |
+| Roles activated | 3–6 | All 9 (too many = noise) |
+| Phase 2 conflicts surfaced | At least 1 | 0 (groupthink risk) |
+
+Track these in `memory/board-meetings/meeting-health.md` over time. Pattern: if action items consistently exceed 8, meetings are too infrequent. If conflicts are consistently 0, isolation is broken.
diff --git a/skills/c-level-advisor/board-meeting/templates/meeting-agenda.md b/skills/c-level-advisor/board-meeting/templates/meeting-agenda.md
new file mode 100644
index 00000000..b491937f
--- /dev/null
+++ b/skills/c-level-advisor/board-meeting/templates/meeting-agenda.md
@@ -0,0 +1,81 @@
+# Board Meeting Agenda Template
+
+Use this to structure a board meeting before invoking `/cs:board`.
+Paste it into the conversation or save it as `memory/board-meetings/agenda-YYYY-MM-DD.md`.
+
+---
+
+## Board Meeting — [DATE]
+
+**Convened by:** [Founder name]
+**Facilitator:** Chief of Staff (Leo)
+**Duration:** [estimated, e.g., 45–90 min]
+**Status:** Draft / Confirmed
+
+---
+
+## Standing Items (always included)
+
+| Item | Owner | Time |
+|------|-------|------|
+| Layer 2 decisions review (what changed since last meeting) | Chief of Staff | 5 min |
+| Open action items from last meeting | All | 10 min |
+| Blockers requiring founder decision | All | 5 min |
+
+---
+
+## Agenda Items
+
+### Item 1: [Title]
+**Type:** Decision required / Exploration / Update
+**Lead role(s):** [e.g., CEO + CFO]
+**Context:** [1-2 sentences on why this is on the agenda now]
+**Decision needed:** [What specifically must be decided, or what question must be answered]
+**Success criteria:** [How will we know this agenda item is resolved?]
+**Relevant past decisions:** [Reference any Layer 2 entries]
+**Time box:** [e.g., 20 min]
+
+---
+
+### Item 2: [Title]
+**Type:** Decision required / Exploration / Update
+**Lead role(s):**
+**Context:**
+**Decision needed:**
+**Success criteria:**
+**Relevant past decisions:**
+**Time box:**
+
+---
+
+### Item 3: [Title]
+**Type:** Decision required / Exploration / Update
+**Lead role(s):**
+**Context:**
+**Decision needed:**
+**Success criteria:**
+**Relevant past decisions:**
+**Time box:**
+
+---
+
+## Out of Scope (explicitly excluded)
+
+List topics that might come up but are NOT on today's agenda:
+- [Topic] — defer to [date or next meeting]
+- [Topic] — owner to handle async
+
+---
+
+## Pre-Read
+
+Materials all participants should review before the meeting:
+- [ ] `memory/board-meetings/decisions.md` (Chief of Staff loads automatically)
+- [ ] [Link or filename]
+- [ ] [Link or filename]
+
+---
+
+## Notes
+
+[Any special instructions, constraints, or context for this meeting]
diff --git a/skills/c-level-advisor/board-meeting/templates/meeting-minutes.md b/skills/c-level-advisor/board-meeting/templates/meeting-minutes.md
new file mode 100644
index 00000000..bd165e6b
--- /dev/null
+++ b/skills/c-level-advisor/board-meeting/templates/meeting-minutes.md
@@ -0,0 +1,91 @@
+# Board Meeting Minutes Template
+
+This is the Layer 2 output — the founder-approved record of what was decided.
+Written by Chief of Staff after Phase 5 (founder approval).
+Appended to `memory/board-meetings/decisions.md`.
+
+Do NOT include raw agent debate here. That lives in `YYYY-MM-DD-raw.md` (Layer 1).
+
+---
+
+## Board Meeting — [DATE]
+
+**Agenda:** [Topic or meeting title]
+**Participants (roles activated):** [e.g., CEO, CFO, CMO, COO, Executive Mentor]
+**Facilitator:** Chief of Staff
+**Status:** ✅ Approved by founder / ⏸️ Pending review
+
+---
+
+## Decisions Made
+
+### Decision 1: [Title]
+**Agenda item:** [Item this decision resolves]
+**Decision:** [Exactly what was decided — one clear statement]
+**Rationale:** [Why this was chosen over alternatives, in 1-3 sentences]
+**Owner:** [Who is accountable for execution]
+**Deadline:** [Date]
+**Review date:** [When to check progress]
+**User override:** [If founder overrode agent consensus — what and why. Leave blank if not applicable.]
+
+---
+
+### Decision 2: [Title]
+**Agenda item:**
+**Decision:**
+**Rationale:**
+**Owner:**
+**Deadline:**
+**Review date:**
+**User override:**
+
+---
+
+## Action Items
+
+| # | Action | Owner | Deadline | Review Date | Status |
+|---|--------|-------|----------|-------------|--------|
+| 1 | [action] | [name/role] | [date] | [date] | Open |
+| 2 | [action] | [name/role] | [date] | [date] | Open |
+| 3 | [action] | [name/role] | [date] | [date] | Open |
+
+---
+
+## Explicitly Rejected Proposals
+
+These were considered and rejected. Do not resurface without new information.
+
+| Proposal | Rejected by | Reason | Flag |
+|----------|-------------|--------|------|
+| [Proposal text] | Founder | [reason] | [DO_NOT_RESURFACE] |
+| [Proposal text] | Consensus | [reason] | [DO_NOT_RESURFACE] |
+
+---
+
+## Open Questions (unresolved, deferred)
+
+These were not resolved in this meeting. They carry forward.
+
+1. [Question] — Owner: [who will research] — Due: [date]
+2. [Question] — Owner: — Due:
+
+---
+
+## Risk Register Updates
+
+| Risk | Probability | Impact | Owner | Mitigation | Status |
+|------|-------------|--------|-------|-----------|--------|
+| [risk] | H/M/L | H/M/L | [name] | [action] | Open |
+
+---
+
+## Next Meeting
+
+**Suggested date:** [DATE]
+**Trigger items:** [Action items with review dates that will need board discussion]
+**Pre-read:** [What to prepare]
+
+---
+
+*Minutes approved by: [Founder name] on [DATE]*
+*Raw transcript: `memory/board-meetings/[DATE]-raw.md`*
diff --git a/skills/c-level-advisor/c_level_leadership_skills_overview.md b/skills/c-level-advisor/c_level_leadership_skills_overview.md
new file mode 100644
index 00000000..dea204dc
--- /dev/null
+++ b/skills/c-level-advisor/c_level_leadership_skills_overview.md
@@ -0,0 +1,388 @@
+# C-Level Leadership Skills Suite
+
+## Executive Summary
+
+Two comprehensive leadership skills have been created for your executive team:
+
+### 1. CTO Advisor ✅
+Strategic technology leadership skill providing frameworks for architecture decisions, team scaling, technical debt management, and engineering excellence.
+
+### 2. CEO Advisor ✅
+Comprehensive executive leadership skill providing strategic planning, financial modeling, board governance, investor relations, and organizational transformation tools.
+
+## Skill Components Overview
+
+### CTO Advisor Skill
+
+**Scripts Included**:
+- `tech_debt_analyzer.py` - Analyzes technical debt and prioritizes reduction strategies
+- `team_scaling_calculator.py` - Optimizes engineering team growth and structure
+
+**Reference Frameworks**:
+- Architecture Decision Records (ADR) framework
+- Technology evaluation and vendor selection
+- Engineering metrics and KPIs (DORA metrics)
+
+**Key Capabilities**:
+- Technical debt assessment and prioritization
+- Engineering team scaling optimization
+- Architecture decision documentation
+- Technology vendor evaluation
+- Engineering performance measurement
+
+### CEO Advisor Skill
+
+**Scripts Included**:
+- `strategy_analyzer.py` - Comprehensive strategic position analysis
+- `financial_scenario_analyzer.py` - Multi-scenario financial modeling
+
+**Reference Frameworks**:
+- Executive decision-making frameworks
+- Board governance and investor relations
+- Leadership and organizational culture
+
+**Key Capabilities**:
+- Strategic planning and analysis
+- Financial scenario modeling
+- Board meeting management
+- Investor communication
+- Organizational transformation
+
+## Implementation Guide
+
+### Phase 1: Deployment (Week 1)
+
+#### For CTO
+1. Deploy `cto-advisor.zip`
+2. Run technical debt assessment
+3. Evaluate current team structure
+4. Review architecture decisions
+5. Implement DORA metrics
+
+#### For CEO
+1. Deploy `ceo-advisor.zip`
+2. Run strategic analysis
+3. Model financial scenarios
+4. Review board processes
+5. Assess organizational culture
+
+### Phase 2: Integration (Weeks 2-4)
+
+#### Cross-Functional Alignment
+- Align technology strategy with business strategy
+- Coordinate resource allocation
+- Synchronize roadmaps
+- Establish joint KPIs
+
+#### Process Implementation
+- Weekly leadership sync
+- Monthly board reporting
+- Quarterly strategic reviews
+- Annual planning cycles
+
+### Phase 3: Optimization (Month 2+)
+
+#### Continuous Improvement
+- Refine frameworks based on usage
+- Customize scripts for specific needs
+- Develop company-specific templates
+- Build institutional knowledge
+
+## Use Case Scenarios
+
+### CTO Scenarios
+
+#### Scenario 1: Technical Debt Crisis
+```bash
+# Assess current technical debt
+python scripts/tech_debt_analyzer.py
+
+# Output: Prioritized action plan
+# Timeline: 3-18 months
+# Investment: $X based on debt level
+```
+
+#### Scenario 2: Rapid Team Scaling
+```bash
+# Plan optimal team growth
+python scripts/team_scaling_calculator.py
+
+# Input: Current 25 → Target 75 engineers
+# Output: Quarterly hiring plan, structure, budget
+```
+
+#### Scenario 3: Architecture Decision
+- Use ADR template from references
+- Document context, options, decision
+- Track consequences and learnings
+
+### CEO Scenarios
+
+#### Scenario 1: Strategic Planning
+```bash
+# Analyze strategic position
+python scripts/strategy_analyzer.py
+
+# Output: Health score, options, roadmap
+# Focus areas identified
+# 18-month implementation plan
+```
+
+#### Scenario 2: Fundraising Preparation
+```bash
+# Model growth scenarios
+python scripts/financial_scenario_analyzer.py
+
+# Three scenarios: Conservative, Base, Aggressive
+# NPV, IRR, break-even analysis
+# Risk-adjusted recommendations
+```
+
+#### Scenario 3: Board Meeting Prep
+- Use board package template
+- Prepare governance materials
+- Structure executive session topics
+
+## Key Metrics & KPIs
+
+### Technology Metrics (CTO)
+
+**Engineering Performance**:
+- Deployment frequency: >1/day
+- Lead time: <1 day
+- MTTR: <1 hour
+- Change failure rate: <15%
+
+**Team Health**:
+- Velocity stability: ±10%
+- Code coverage: >80%
+- Technical debt: <10%
+- Attrition: <10%
+
+**System Performance**:
+- Uptime: >99.9%
+- Response time: <200ms
+- Error rate: <0.1%
+- Scalability: Linear
+
+### Business Metrics (CEO)
+
+**Financial Performance**:
+- Revenue growth: >30% YoY
+- Gross margin: >70%
+- EBITDA positive by Y2
+- Cash runway: >18 months
+
+**Organizational Health**:
+- Employee NPS: >50
+- Customer NPS: >70
+- Board confidence: High
+- Culture score: >8/10
+
+**Strategic Progress**:
+- OKR achievement: >70%
+- Market share growth
+- Innovation pipeline
+- Strategic initiatives on track
+
+## Synergy Opportunities
+
+### CTO-CEO Collaboration Points
+
+#### 1. Strategic Alignment
+- Technology enables business strategy
+- Business priorities drive tech investments
+- Joint roadmap development
+- Shared success metrics
+
+#### 2. Resource Optimization
+- Coordinated budget planning
+- Talent strategy alignment
+- Vendor consolidation
+- Investment prioritization
+
+#### 3. Risk Management
+- Technical risk assessment
+- Business continuity planning
+- Security and compliance
+- Crisis response protocols
+
+#### 4. Innovation Drive
+- R&D investment strategy
+- Digital transformation
+- Competitive differentiation
+- Future-proofing
+
+## Best Practices
+
+### For Effective Usage
+
+#### Daily Habits
+- Review key metrics dashboard
+- Check strategic alignment
+- Address critical decisions
+- Communicate priorities
+
+#### Weekly Rituals
+- Leadership team sync
+- Progress reviews
+- Stakeholder updates
+- Course corrections
+
+#### Monthly Processes
+- Deep strategic reviews
+- Financial analysis
+- Organizational health check
+- Board preparation
+
+#### Quarterly Milestones
+- Strategy adjustment
+- Performance evaluation
+- Planning cycles
+- Stakeholder engagement
+
+### Common Pitfalls to Avoid
+
+#### CTO Pitfalls
+- Over-engineering solutions
+- Ignoring technical debt
+- Scaling too fast/slow
+- Misaligned architecture
+
+#### CEO Pitfalls
+- Analysis paralysis
+- Poor stakeholder management
+- Culture neglect
+- Reactive leadership
+
+## ROI Analysis
+
+### CTO Advisor ROI
+
+**Time Savings**:
+- Decision making: 50% faster
+- Team planning: 60% more accurate
+- Architecture reviews: 40% more efficient
+
+**Cost Benefits**:
+- Technical debt reduction: $2M+ saved
+- Optimal scaling: 30% lower hiring costs
+- Better decisions: Avoid $5M+ mistakes
+
+**Quality Improvements**:
+- System reliability: 99.9%+
+- Team productivity: +25%
+- Architecture quality: Significantly improved
+
+### CEO Advisor ROI
+
+**Strategic Value**:
+- Better strategic decisions
+- Faster execution
+- Improved stakeholder confidence
+
+**Financial Impact**:
+- Optimized capital allocation
+- Better fundraising outcomes
+- Increased valuation
+
+**Organizational Benefits**:
+- Stronger culture
+- Better talent retention
+- Higher performance
+
+## Success Stories (Projected)
+
+### After 3 Months
+- Technical debt reduced by 30%
+- Engineering team optimally structured
+- Strategic clarity achieved
+- Board relationships strengthened
+
+### After 6 Months
+- DORA metrics at "Elite" level
+- Team scaling on track
+- Strategic initiatives delivering
+- Culture transformation visible
+
+### After 12 Months
+- Engineering excellence achieved
+- Organizational capabilities transformed
+- Market position strengthened
+- Sustainable growth established
+
+## Tool Integration
+
+### Recommended Stack
+
+#### For CTO
+- **Metrics**: DataDog, New Relic
+- **Planning**: Jira, Linear
+- **Architecture**: Draw.io, Confluence
+- **Code**: GitHub, GitLab
+
+#### For CEO
+- **Strategy**: Cascade, Perdoo
+- **Financial**: Excel, Causal
+- **Board**: Diligent, BoardEffect
+- **Communication**: Slack, Notion
+
+## Support & Evolution
+
+### Skill Maintenance
+- Regular framework updates
+- Script enhancements
+- Template refinements
+- Best practice sharing
+
+### Community Building
+- Leadership forums
+- Peer learning
+- Case study sharing
+- Continuous improvement
+
+### Future Enhancements
+
+#### Potential Additional Skills
+- **CFO Advisor**: Financial management, fundraising, investor relations
+- **CPO Advisor**: Product strategy, roadmapping, customer insights
+- **CMO Advisor**: Marketing strategy, brand, demand generation
+- **CHRO Advisor**: Talent strategy, culture, organizational development
+
+## Quick Reference
+
+### CTO Quick Commands
+```bash
+# Analyze technical debt
+python scripts/tech_debt_analyzer.py
+
+# Plan team scaling
+python scripts/team_scaling_calculator.py
+
+# Review ADR framework
+cat references/architecture_decision_records.md
+```
+
+### CEO Quick Commands
+```bash
+# Analyze strategy
+python scripts/strategy_analyzer.py
+
+# Model scenarios
+python scripts/financial_scenario_analyzer.py
+
+# Review decision framework
+cat references/executive_decision_framework.md
+```
+
+## Conclusion
+
+These C-Level leadership skills provide comprehensive frameworks, tools, and guidance for effective executive leadership. By combining strategic thinking with practical tools, they enable faster, better decisions while building stronger organizations.
+
+The synergy between CTO and CEO skills creates a powerful leadership toolkit that addresses both technical and business challenges, ensuring aligned, effective leadership across the organization.
+
+**Files Available**:
+- [CTO Advisor Skill](computer:///mnt/user-data/outputs/cto-advisor.zip)
+- [CEO Advisor Skill](computer:///mnt/user-data/outputs/ceo-advisor.zip)
+
+Deploy these skills to transform your leadership effectiveness and drive organizational excellence.
diff --git a/skills/c-level-advisor/ceo-advisor/SKILL.md b/skills/c-level-advisor/ceo-advisor/SKILL.md
new file mode 100644
index 00000000..6396c197
--- /dev/null
+++ b/skills/c-level-advisor/ceo-advisor/SKILL.md
@@ -0,0 +1,169 @@
+---
+name: "ceo-advisor"
+description: "Executive leadership guidance for strategic decision-making, organizational development, and stakeholder management. Use when planning strategy, preparing board presentations, managing investors, developing organizational culture, making executive decisions, fundraising, or when user mentions CEO, strategic planning, board meetings, investor updates, organizational leadership, or executive strategy."
+license: MIT
+metadata:
+ version: 2.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: ceo-leadership
+ updated: 2026-03-05
+ python-tools: strategy_analyzer.py, financial_scenario_analyzer.py
+ frameworks: executive-decisions, board-governance, leadership-culture
+---
+
+# CEO Advisor
+
+Strategic leadership frameworks for vision, fundraising, board management, culture, and stakeholder alignment.
+
+## Keywords
+CEO, chief executive officer, strategy, strategic planning, fundraising, board management, investor relations, culture, organizational leadership, vision, mission, stakeholder management, capital allocation, crisis management, succession planning
+
+## Quick Start
+
+```bash
+python scripts/strategy_analyzer.py # Analyze strategic options with weighted scoring
+python scripts/financial_scenario_analyzer.py # Model financial scenarios (base/bull/bear)
+```
+
+## Core Responsibilities
+
+### 1. Vision & Strategy
+Set the direction. Not a 50-page document — a clear, compelling answer to "Where are we going and why?"
+
+**Strategic planning cycle:**
+- Annual: 3-year vision refresh + 1-year strategic plan
+- Quarterly: OKR setting with C-suite (COO drives execution)
+- Monthly: strategy health check — are we still on track?
+
+**Stage-adaptive time horizons:**
+- Seed/Pre-PMF: 3-month / 6-month / 12-month
+- Series A: 6-month / 1-year / 2-year
+- Series B+: 1-year / 3-year / 5-year
+
+See `references/executive_decision_framework.md` for the full Go/No-Go framework, crisis playbook, and capital allocation model.
+
+### 2. Capital & Resource Management
+You're the chief allocator. Every dollar, every person, every hour of engineering time is a bet.
+
+**Capital allocation priorities:**
+1. Keep the lights on (operations, must-haves)
+2. Protect the core (retention, quality, security)
+3. Grow the core (expansion of what works)
+4. Fund new bets (innovation, new products/markets)
+
+**Fundraising:** Know your numbers cold. Timing matters more than valuation. See `references/board_governance_investor_relations.md`.
+
+### 3. Stakeholder Leadership
+You serve multiple masters. Priority order:
+1. Customers (they pay the bills)
+2. Team (they build the product)
+3. Board/Investors (they fund the mission)
+4. Partners (they extend your reach)
+
+### 4. Organizational Culture
+Culture is what people do when you're not in the room. It's your job to define it, model it, and enforce it.
+
+See `references/leadership_organizational_culture.md` for culture development frameworks and the CEO learning agenda. Also see `culture-architect/` for the operational culture toolkit.
+
+### 5. Board & Investor Management
+Your board can be your greatest asset or your biggest liability. The difference is how you manage them.
+
+See `references/board_governance_investor_relations.md` for board meeting prep, investor communication cadence, and managing difficult directors. Also see `board-deck-builder/` for assembling the actual board deck.
+
+## Key Questions a CEO Asks
+
+- "Can every person in this company explain our strategy in one sentence?"
+- "What's the one thing that, if it goes wrong, kills us?"
+- "Am I spending my time on the highest-leverage activity right now?"
+- "What decision am I avoiding? Why?"
+- "If we could only do one thing this quarter, what would it be?"
+- "Do our investors and our team hear the same story from me?"
+- "Who would replace me if I got hit by a bus tomorrow?"
+
+## CEO Metrics Dashboard
+
+| Category | Metric | Target | Frequency |
+|----------|--------|--------|-----------|
+| **Strategy** | Annual goals hit rate | > 70% | Quarterly |
+| **Revenue** | ARR growth rate | Stage-dependent | Monthly |
+| **Capital** | Months of runway | > 12 months | Monthly |
+| **Capital** | Burn multiple | < 2x | Monthly |
+| **Product** | NPS / PMF score | > 40 NPS | Quarterly |
+| **People** | Regrettable attrition | < 10% | Monthly |
+| **People** | Employee engagement | > 7/10 | Quarterly |
+| **Board** | Board NPS (your relationship) | Positive trend | Quarterly |
+| **Personal** | % time on strategic work | > 40% | Weekly |
+
+## Red Flags
+
+- You're the bottleneck for more than 3 decisions per week
+- The board surprises you with questions you can't answer
+- Your calendar is 80%+ meetings with no strategic blocks
+- Key people are leaving and you didn't see it coming
+- You're fundraising reactively (runway < 6 months, no plan)
+- Your team can't articulate the strategy without you in the room
+- You're avoiding a hard conversation (co-founder, investor, underperformer)
+
+## Integration with C-Suite Roles
+
+| When... | CEO works with... | To... |
+|---------|-------------------|-------|
+| Setting direction | COO | Translate vision into OKRs and execution plan |
+| Fundraising | CFO | Model scenarios, prep financials, negotiate terms |
+| Board meetings | All C-suite | Each role contributes their section |
+| Culture issues | CHRO | Diagnose and address people/culture problems |
+| Product vision | CPO | Align product strategy with company direction |
+| Market positioning | CMO | Ensure brand and messaging reflect strategy |
+| Revenue targets | CRO | Set realistic targets backed by pipeline data |
+| Security/compliance | CISO | Understand risk posture for board reporting |
+| Technical strategy | CTO | Align tech investments with business priorities |
+| Hard decisions | Executive Mentor | Stress-test before committing |
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Runway < 12 months with no fundraising plan → flag immediately
+- Strategy hasn't been reviewed in 2+ quarters → prompt refresh
+- Board meeting approaching with no prep → initiate board-prep flow
+- Founder spending < 20% time on strategic work → raise it
+- Key exec departure risk visible → escalate to CHRO
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Help me think about strategy" | Strategic options matrix with risk-adjusted scoring |
+| "Prep me for the board" | Board narrative + anticipated questions + data gaps |
+| "Should we raise?" | Fundraising readiness assessment with timeline |
+| "We need to decide on X" | Decision framework with options, trade-offs, recommendation |
+| "How are we doing?" | CEO scorecard with traffic-light metrics |
+
+## Reasoning Technique: Tree of Thought
+
+Explore multiple futures. For every strategic decision, generate at least 3 paths. Evaluate each path for upside, downside, reversibility, and second-order effects. Pick the path with the best risk-adjusted outcome.
+
+**Stage-adaptive horizons:**
+- Seed: project 3m/6m/12m
+- Series A: project 6m/1y/2y
+- Series B+: project 1y/3y/5y
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
+
+## Resources
+- `references/executive_decision_framework.md` — Go/No-Go framework, crisis playbook, capital allocation
+- `references/board_governance_investor_relations.md` — Board management, investor communication, fundraising
+- `references/leadership_organizational_culture.md` — Culture development, CEO routines, succession planning
diff --git a/skills/c-level-advisor/ceo-advisor/references/board_governance_investor_relations.md b/skills/c-level-advisor/ceo-advisor/references/board_governance_investor_relations.md
new file mode 100644
index 00000000..6da2c369
--- /dev/null
+++ b/skills/c-level-advisor/ceo-advisor/references/board_governance_investor_relations.md
@@ -0,0 +1,599 @@
+# Board Governance & Investor Relations Guide
+
+## Board of Directors Management
+
+### Board Composition
+
+#### Ideal Board Structure
+- **Size**: 7-9 members (odd number for voting)
+- **Independence**: Majority independent directors
+- **Diversity**: Gender, ethnicity, expertise, experience
+- **Term**: 3-year terms, staggered renewal
+
+#### Board Roles
+
+| Role | Responsibilities | Typical Background |
+|------|-----------------|-------------------|
+| Chairman | Board leadership, CEO liaison | Former CEO, Industry veteran |
+| Lead Independent Director | Independent voice, executive sessions | Senior executive experience |
+| Audit Committee Chair | Financial oversight, auditor relationship | CFO/CPA background |
+| Compensation Committee Chair | Executive compensation, succession | HR/Executive experience |
+| Nominating Committee Chair | Board composition, governance | Governance expertise |
+
+### Board Meeting Management
+
+#### Annual Board Calendar
+
+**Q1 Meeting**
+- Annual strategy review
+- Previous year performance
+- Current year priorities
+- Risk assessment update
+
+**Q2 Meeting**
+- Q1 results review
+- Strategic initiative progress
+- Competitive landscape
+- Talent review
+
+**Q3 Meeting**
+- Mid-year performance
+- Budget preview
+- Strategic planning session
+- Succession planning
+
+**Q4 Meeting**
+- Annual budget approval
+- Executive compensation
+- Board evaluation
+- Upcoming year calendar
+
+#### Meeting Preparation Timeline
+
+**T-4 Weeks**
+- Agenda draft to Chairman
+- Pre-read preparation begins
+- Committee meetings scheduled
+
+**T-2 Weeks**
+- Materials to review committee
+- Final agenda confirmation
+- Logistics coordination
+
+**T-1 Week**
+- Board package distribution
+- Pre-meeting calls as needed
+- Final preparations
+
+**T-0 Meeting Day**
+- Executive session (start)
+- Board meeting
+- Executive session (end)
+- Follow-up actions defined
+
+### Board Package Template
+
+#### Standard Package Contents
+
+1. **Cover Memo** (1 page)
+ - Meeting agenda
+ - Key decisions required
+ - Time allocations
+
+2. **CEO Report** (3-5 pages)
+ - Executive summary
+ - Performance highlights
+ - Strategic progress
+ - Key challenges
+ - Asks of the board
+
+3. **Financial Report** (5-10 pages)
+ - Financial statements
+ - KPI dashboard
+ - Variance analysis
+ - Cash position
+ - Forecast update
+
+4. **Strategic Updates** (10-15 pages)
+ - Initiative status
+ - Market analysis
+ - Competitive intelligence
+ - Product roadmap
+
+5. **Committee Reports** (2-3 pages each)
+ - Audit Committee
+ - Compensation Committee
+ - Other committees
+
+6. **Appendices**
+ - Detailed financials
+ - Supporting analysis
+ - Previous minutes
+
+### Board Communication Best Practices
+
+#### Between Meetings
+
+**Monthly Update Email**
+```
+Subject: [Company] CEO Update - [Month Year]
+
+Board Members,
+
+Quick update on [Month] performance:
+
+Headlines:
+• [Key achievement]
+• [Important metric]
+• [Strategic progress]
+
+Challenges:
+• [Issue and mitigation]
+
+Looking Ahead:
+• [Upcoming milestone]
+
+Detailed dashboard attached.
+
+Best,
+[CEO Name]
+```
+
+**Flash Reports** (When needed)
+- Material events
+- Major wins/losses
+- Press coverage
+- Regulatory matters
+
+#### Managing Difficult Conversations
+
+**Delivering Bad News**
+1. Don't delay - inform promptly
+2. Lead with facts
+3. Own the responsibility
+4. Present action plan
+5. Set realistic timeline
+
+**Handling Dissent**
+1. Listen fully
+2. Acknowledge concerns
+3. Provide data/rationale
+4. Seek common ground
+5. Document decisions
+
+## Investor Relations
+
+### Investor Segmentation
+
+#### Institutional Investors
+
+**Types**:
+- Mutual funds
+- Pension funds
+- Hedge funds
+- Private equity
+- Sovereign wealth funds
+
+**Engagement Strategy**:
+- Quarterly earnings calls
+- Annual investor day
+- Conference participation
+- One-on-one meetings
+- Site visits
+
+#### Retail Investors
+
+**Channels**:
+- Website IR section
+- Annual reports
+- Proxy statements
+- Social media
+- Shareholder meetings
+
+### Earnings Communications
+
+#### Earnings Release Template
+
+```
+[COMPANY] REPORTS [QUARTER] [YEAR] RESULTS
+
+[City, Date] - [Company] (TICKER) today reported results for [quarter]:
+
+Financial Highlights:
+• Revenue: $X (±Y% YoY)
+• Net Income: $X (±Y% YoY)
+• EPS: $X (±Y% YoY)
+• [Other key metric]
+
+CEO Commentary:
+"[Quote about performance and outlook]"
+
+CFO Commentary:
+"[Quote about financial details]"
+
+Guidance:
+[Forward-looking statements]
+
+Conference Call:
+Date/Time: [Details]
+Webcast: [Link]
+
+About [Company]:
+[Boilerplate]
+
+Contact:
+[IR contact information]
+```
+
+#### Earnings Call Script Structure
+
+**CEO Opening (5 minutes)**
+```
+Good [morning/afternoon], and welcome to [Company's]
+[Quarter] earnings call.
+
+Today I'll cover:
+1. Quarter highlights
+2. Strategic progress
+3. Market dynamics
+4. Outlook
+
+[Key points with supporting data]
+
+I'll now turn it over to our CFO...
+```
+
+**CFO Section (10 minutes)**
+```
+Thank you [CEO name].
+
+Financial Performance:
+- Revenue details by segment
+- Margin analysis
+- Cash flow review
+- Balance sheet highlights
+
+Guidance:
+- Next quarter expectations
+- Full year outlook
+- Key assumptions
+
+Now back to [CEO] for closing remarks...
+```
+
+**Q&A Management**
+- Anticipate top 10 questions
+- Prepare fact sheets
+- Designate responders
+- Bridge to key messages
+- Time management
+
+### Investor Messaging Framework
+
+#### Value Proposition
+
+**Investment Thesis Elements**:
+1. Market opportunity size
+2. Competitive advantages
+3. Growth strategy
+4. Financial model
+5. Management team
+6. Risk factors
+
+#### Key Messages Architecture
+
+**Primary Messages** (Memorize)
+1. [Core value proposition]
+2. [Differentiation]
+3. [Growth trajectory]
+
+**Supporting Points** (Have ready)
+- Market data
+- Customer proof points
+- Financial metrics
+- Strategic initiatives
+
+**Proof Points** (Document)
+- Case studies
+- Metrics
+- Third-party validation
+- Awards/recognition
+
+### Investor Day Planning
+
+#### 6-Month Planning Timeline
+
+**T-6 Months**
+- Set date and venue
+- Define objectives
+- Identify speakers
+- Begin content development
+
+**T-4 Months**
+- Develop presentations
+- Coordinate logistics
+- Begin rehearsals
+- Create save-the-date
+
+**T-2 Months**
+- Finalize content
+- Complete rehearsals
+- Send invitations
+- Prepare materials
+
+**T-1 Month**
+- Final preparations
+- Media training
+- Q&A preparation
+- Technology testing
+
+**T-0 Event Day**
+- Execute program
+- Manage Q&A
+- Network sessions
+- Follow-up plan
+
+#### Agenda Template
+
+```
+8:00 AM - Registration & Breakfast
+8:30 AM - CEO Welcome & Vision
+9:00 AM - Market Opportunity
+9:30 AM - Product Strategy & Demo
+10:00 AM - Break
+10:15 AM - Go-to-Market Strategy
+10:45 AM - Financial Overview
+11:15 AM - Q&A Panel
+12:00 PM - Networking Lunch
+1:00 PM - Facility Tour (Optional)
+```
+
+### Shareholder Activism Defense
+
+#### Early Warning Signs
+- Stake building (13D/13G filings)
+- Public criticism
+- Media campaigns
+- Proxy solicitation
+- Shareholder proposals
+
+#### Response Playbook
+
+**1. Preparation Phase**
+- Vulnerability assessment
+- Response team formation
+- Advisor engagement
+- Board alignment
+
+**2. Engagement Phase**
+- Direct dialogue
+- Understanding demands
+- Finding common ground
+- Negotiation strategy
+
+**3. Defense Phase** (if needed)
+- Public response
+- Proxy fight preparation
+- Shareholder outreach
+- Media strategy
+
+**4. Resolution Phase**
+- Settlement negotiations
+- Implementation planning
+- Communication strategy
+- Monitoring plan
+
+### Regulatory Compliance
+
+#### Key Filings
+
+| Form | Purpose | Timing |
+|------|---------|--------|
+| 10-K | Annual report | 60-90 days after FY end |
+| 10-Q | Quarterly report | 40-45 days after Q end |
+| 8-K | Material events | 4 business days |
+| DEF 14A | Proxy statement | Before annual meeting |
+| S-1/S-3 | Securities registration | As needed |
+
+#### Disclosure Requirements
+
+**Material Information**:
+- Financial results
+- Major transactions
+- Leadership changes
+- Strategic shifts
+- Legal proceedings
+- Risk changes
+
+**Regulation FD Compliance**:
+- No selective disclosure
+- Simultaneous public release
+- Documented procedures
+- Training program
+
+### Crisis Communication
+
+#### IR Crisis Response
+
+**Hour 1: Assessment**
+- Gather facts
+- Assess materiality
+- Consult legal
+- Prepare holding statement
+
+**Hours 2-4: Response**
+- Draft 8-K if required
+- Prepare FAQ
+- Update website
+- Notify exchanges
+
+**Hours 4-8: Communication**
+- Issue press release
+- Update analysts
+- Employee communication
+- Monitor reactions
+
+**Day 2+: Follow-up**
+- Investor calls
+- Media interviews
+- Ongoing updates
+- Impact assessment
+
+### Performance Metrics
+
+#### IR Effectiveness KPIs
+
+**Quantitative Metrics**:
+- Share price performance vs peers
+- Trading volume/liquidity
+- Analyst coverage
+- Institutional ownership %
+- Valuation multiples vs peers
+
+**Qualitative Metrics**:
+- Analyst sentiment
+- Media coverage tone
+- Investor feedback
+- Award recognition
+- Perception studies
+
+#### Shareholder Analysis
+
+**Ownership Tracking**:
+- Top 20 shareholders
+- Ownership changes
+- Peer ownership overlap
+- Geographic distribution
+- Investment style mix
+
+**Engagement Metrics**:
+- Meeting count
+- Conference participation
+- Earnings call attendance
+- Website analytics
+- Email engagement
+
+## Governance Best Practices
+
+### Board Effectiveness
+
+#### Annual Board Evaluation
+
+**Process**:
+1. Anonymous surveys
+2. Individual interviews
+3. Peer feedback
+4. Results compilation
+5. Action planning
+6. Progress monitoring
+
+**Evaluation Areas**:
+- Board composition
+- Meeting effectiveness
+- Information quality
+- Strategic oversight
+- Risk management
+- CEO relationship
+- Committee performance
+
+### Executive Session Management
+
+**Frequency**: Every board meeting
+**Duration**: 30-60 minutes
+**Participants**: Independent directors only
+
+**Typical Topics**:
+- CEO performance
+- Succession planning
+- Board dynamics
+- Sensitive matters
+- Executive compensation
+
+### D&O Insurance & Indemnification
+
+**Coverage Levels**:
+- Primary: $10-25M
+- Excess: $25-100M+
+- Side A: Individual protection
+- Side B: Company reimbursement
+- Side C: Securities claims
+
+**Best Practices**:
+- Annual review
+- Competitive benchmarking
+- Claims history analysis
+- Policy optimization
+- Personal coverage consideration
+
+### ESG Governance
+
+#### ESG Integration
+
+**Board Oversight**:
+- ESG committee or full board
+- Regular ESG updates
+- Metrics in dashboard
+- Risk assessment
+- Stakeholder feedback
+
+**Reporting Framework**:
+- SASB standards
+- TCFD recommendations
+- GRI guidelines
+- UN SDGs alignment
+- Integrated reporting
+
+**Investor Communication**:
+- ESG highlights in earnings
+- Dedicated ESG report
+- Website ESG section
+- ESG investor days
+- Rating agency engagement
+
+## Templates & Tools
+
+### Board Resolution Template
+
+```
+BOARD RESOLUTION
+
+WHEREAS, [background/context];
+
+WHEREAS, [additional context];
+
+NOW, THEREFORE, BE IT RESOLVED, that [specific action];
+
+FURTHER RESOLVED, that [additional actions];
+
+FURTHER RESOLVED, that [authorization].
+
+Approved this [date].
+
+_____________________
+[Secretary Name]
+Corporate Secretary
+```
+
+### Insider Trading Policy Outline
+
+1. **Scope**: All directors, officers, employees
+2. **Prohibited Activities**: Trading on MNPI
+3. **Trading Windows**: Quarterly schedule
+4. **Pre-clearance**: Required for all trades
+5. **Blackout Periods**: Defined schedule
+6. **10b5-1 Plans**: Permitted with approval
+7. **Violations**: Disciplinary action
+8. **Training**: Annual requirement
+
+### Proxy Statement Checklist
+
+- [ ] Executive compensation (CD&A)
+- [ ] Director nominees
+- [ ] Governance structure
+- [ ] Shareholder proposals
+- [ ] Audit matters
+- [ ] Related party transactions
+- [ ] Risk oversight
+- [ ] Succession planning
+- [ ] ESG disclosure
+- [ ] Virtual meeting details
diff --git a/skills/c-level-advisor/ceo-advisor/references/executive_decision_framework.md b/skills/c-level-advisor/ceo-advisor/references/executive_decision_framework.md
new file mode 100644
index 00000000..f5251a91
--- /dev/null
+++ b/skills/c-level-advisor/ceo-advisor/references/executive_decision_framework.md
@@ -0,0 +1,475 @@
+# Executive Decision Framework
+
+## Decision-Making Process
+
+### The DECIDE Framework
+
+**D** - Define the problem clearly
+**E** - Establish criteria for solutions
+**C** - Consider alternatives
+**I** - Identify best alternatives
+**D** - Develop and implement action plan
+**E** - Evaluate and monitor solution
+
+## Strategic Decision Categories
+
+### 1. Growth Decisions
+
+#### Market Expansion
+**Evaluation Criteria**:
+- Market size and growth rate
+- Competitive landscape
+- Regulatory environment
+- Cultural fit
+- Required investment
+- Expected ROI
+
+**Decision Matrix**:
+| Factor | Weight | Score (1-10) | Weighted Score |
+|--------|--------|--------------|----------------|
+| Market Size | 25% | | |
+| Competition | 20% | | |
+| Fit with Core | 20% | | |
+| Investment Required | 15% | | |
+| Risk Level | 10% | | |
+| Timeline to Profit | 10% | | |
+
+#### Product Development
+**Go/No-Go Criteria**:
+- Customer demand validation (>70% interest)
+- Technical feasibility confirmed
+- Positive unit economics
+- Strategic alignment
+- Available resources
+
+#### Mergers & Acquisitions
+**Due Diligence Framework**:
+1. **Strategic Fit**
+ - Synergies identification
+ - Cultural alignment
+ - Market position enhancement
+
+2. **Financial Analysis**
+ - Valuation models (DCF, Multiples, Precedent)
+ - ROI projections
+ - Integration costs
+
+3. **Risk Assessment**
+ - Legal/regulatory issues
+ - Technology compatibility
+ - Talent retention
+
+4. **Integration Planning**
+ - 100-day plan
+ - Communication strategy
+ - Success metrics
+
+### 2. Resource Allocation
+
+#### Capital Allocation Framework
+
+**Priority Levels**:
+1. **Essential** - Core operations, compliance, security
+2. **Strategic** - Growth initiatives, competitive advantage
+3. **Efficiency** - Cost reduction, productivity
+4. **Experimental** - Innovation, R&D
+
+**Allocation Guidelines**:
+- Essential: 40-50%
+- Strategic: 30-40%
+- Efficiency: 10-15%
+- Experimental: 5-10%
+
+#### Budget Decision Tree
+```
+Is it required for operations?
+├─ Yes → Essential (Auto-approve if <$X)
+└─ No → Does it drive growth?
+ ├─ Yes → What's the ROI?
+ │ ├─ >30% → Strategic (Approve)
+ │ └─ <30% → Defer/Reject
+ └─ No → Does it reduce costs?
+ ├─ Yes → Payback period?
+ │ ├─ <12 months → Efficiency (Approve)
+ │ └─ >12 months → Defer
+ └─ No → Experimental (Limited budget)
+```
+
+### 3. Organizational Decisions
+
+#### Restructuring Framework
+
+**Triggers for Restructuring**:
+- Performance below targets for 2+ quarters
+- Major strategic shift
+- M&A integration
+- Market disruption
+- Efficiency opportunity >20%
+
+**Evaluation Process**:
+1. Current state assessment
+2. Future state design
+3. Gap analysis
+4. Impact assessment
+5. Implementation planning
+6. Communication strategy
+
+#### Leadership Changes
+
+**Performance Evaluation Matrix**:
+| Dimension | Weight | Indicators |
+|-----------|--------|------------|
+| Results Delivery | 40% | KPIs, OKRs achievement |
+| Team Leadership | 25% | Engagement, retention, development |
+| Strategic Thinking | 20% | Innovation, vision, planning |
+| Culture Fit | 15% | Values alignment, collaboration |
+
+**Succession Planning**:
+- Identify 2-3 potential successors for each key role
+- Development plans for high-potentials
+- Emergency succession protocols
+- Knowledge transfer processes
+
+### 4. Crisis Management
+
+#### Crisis Response Protocol
+
+**Immediate (0-2 hours)**:
+1. Activate crisis team
+2. Assess severity and impact
+3. Implement containment measures
+4. Initial stakeholder notification
+
+**Short-term (2-24 hours)**:
+1. Develop response strategy
+2. Prepare public statements
+3. Engage legal/regulatory as needed
+4. Employee communication
+
+**Recovery (24+ hours)**:
+1. Implement solution
+2. Monitor progress
+3. Stakeholder updates
+4. Post-crisis review
+
+#### Crisis Decision Authority
+
+| Crisis Level | Decision Authority | Response Team |
+|--------------|-------------------|---------------|
+| Level 1 (Minor) | Department Head | Local team |
+| Level 2 (Moderate) | C-Suite Member | Cross-functional |
+| Level 3 (Major) | CEO | Executive team |
+| Level 4 (Critical) | CEO + Board | All hands |
+
+## Decision Support Tools
+
+### 1. SWOT-TOWS Matrix
+
+```
+ Internal →
+ ↓ Strengths (S) Weaknesses (W)
+External
+
+O SO Strategies WO Strategies
+p (Leverage) (Improve)
+p
+o
+r
+t
+
+T ST Strategies WT Strategies
+h (Protect) (Survive)
+r
+e
+a
+t
+s
+```
+
+### 2. BCG Growth-Share Matrix
+
+```
+Market Growth Rate
+ ↑
+High │ Stars │ Question │
+ │ │ Marks │
+ ├─────────┼──────────┤
+Low │ Cash │ Dogs │
+ │ Cows │ │
+ └─────────┴──────────┘
+ High Low →
+ Market Share
+```
+
+### 3. Risk-Impact Matrix
+
+```
+Impact
+ ↑
+High │ Mitigate │ Critical │
+ │ │ Focus │
+ ├──────────┼──────────┤
+Low │ Accept │ Monitor │
+ │ │ │
+ └──────────┴──────────┘
+ Low High →
+ Probability
+```
+
+### 4. Eisenhower Matrix
+
+```
+Urgency
+ ↑
+High │ Do │ Schedule │
+ │ First │ │
+ ├─────────┼──────────┤
+Low │ Delegate│ Eliminate│
+ │ │ │
+ └─────────┴──────────┘
+ High Low →
+ Importance
+```
+
+## Strategic Options Framework
+
+### Porter's Generic Strategies
+
+1. **Cost Leadership**
+ - Operational excellence
+ - Economy of scale
+ - Process optimization
+ - Supply chain efficiency
+
+2. **Differentiation**
+ - Unique value proposition
+ - Premium positioning
+ - Innovation focus
+ - Brand strength
+
+3. **Focus**
+ - Niche markets
+ - Specialized offerings
+ - Deep expertise
+ - Customer intimacy
+
+### Blue Ocean Strategy
+
+**Four Actions Framework**:
+- **Eliminate**: Which factors can be eliminated?
+- **Reduce**: Which factors should be reduced below industry standard?
+- **Raise**: Which factors should be raised above industry standard?
+- **Create**: Which factors should be created that the industry has never offered?
+
+## Stakeholder Management
+
+### Stakeholder Mapping
+
+```
+Influence/Power
+ ↑
+High │ Manage │ Key │
+ │ Closely │ Players │
+ ├──────────┼──────────┤
+Low │ Monitor │ Keep │
+ │ │ Informed │
+ └──────────┴──────────┘
+ Low High →
+ Interest
+```
+
+### Communication Strategy
+
+| Stakeholder | Frequency | Format | Key Messages |
+|------------|-----------|--------|--------------|
+| Board | Monthly | Report + Meeting | Strategy, Risk, Performance |
+| Investors | Quarterly | Earnings Call | Financial, Growth, Outlook |
+| Employees | Weekly | All-hands | Vision, Updates, Recognition |
+| Customers | Continuous | Multi-channel | Value, Innovation, Support |
+| Media | As needed | Press Release | Milestones, Position, Vision |
+
+## Performance Metrics
+
+### Balanced Scorecard
+
+#### Financial Perspective
+- Revenue growth rate
+- EBITDA margin
+- ROE/ROA
+- Cash conversion cycle
+- Market capitalization
+
+#### Customer Perspective
+- Customer satisfaction (NPS)
+- Market share
+- Customer retention rate
+- Customer acquisition cost
+- Customer lifetime value
+
+#### Internal Process
+- Operational efficiency
+- Time to market
+- Quality metrics
+- Innovation rate
+- Process cycle time
+
+#### Learning & Growth
+- Employee engagement
+- Talent retention
+- Training hours per employee
+- Leadership pipeline
+- Innovation index
+
+## Decision Biases to Avoid
+
+### Cognitive Biases
+
+1. **Confirmation Bias**
+ - Mitigation: Seek contrarian views
+ - Tool: Devil's advocate process
+
+2. **Anchoring Bias**
+ - Mitigation: Multiple estimates
+ - Tool: Range forecasting
+
+3. **Sunk Cost Fallacy**
+ - Mitigation: Zero-based thinking
+ - Tool: Regular portfolio review
+
+4. **Overconfidence Bias**
+ - Mitigation: Outside view
+ - Tool: Reference class forecasting
+
+5. **Availability Heuristic**
+ - Mitigation: Data-driven decisions
+ - Tool: Systematic analysis
+
+### Decision Hygiene Checklist
+
+- [ ] Problem clearly defined
+- [ ] All stakeholders identified
+- [ ] Data/evidence gathered
+- [ ] Multiple options generated
+- [ ] Biases checked
+- [ ] Risks assessed
+- [ ] Implementation plan created
+- [ ] Success metrics defined
+- [ ] Review process established
+
+## Executive Communication
+
+### Board Presentation Template
+
+1. **Executive Summary** (1 slide)
+ - Key achievements
+ - Critical issues
+ - Decisions needed
+
+2. **Performance Review** (3-4 slides)
+ - Financial results
+ - Operational metrics
+ - Strategic progress
+
+3. **Market & Competition** (2 slides)
+ - Market dynamics
+ - Competitive position
+
+4. **Strategic Initiatives** (3-4 slides)
+ - Current initiatives
+ - Results to date
+ - Next steps
+
+5. **Risk & Mitigation** (2 slides)
+ - Risk register
+ - Mitigation actions
+
+6. **Ask of the Board** (1 slide)
+ - Decisions required
+ - Support needed
+
+### Investor Relations Framework
+
+**Earnings Call Structure**:
+1. Opening remarks (CEO) - 5 min
+2. Financial review (CFO) - 10 min
+3. Strategic update (CEO) - 10 min
+4. Q&A - 30 min
+
+**Key Messages**:
+- Performance vs guidance
+- Market position
+- Growth strategy
+- Capital allocation
+- Outlook
+
+## Strategic Planning Cycle
+
+### Annual Planning Process
+
+**Q3 - Strategic Review**
+- Environmental scan
+- Competitive analysis
+- Capability assessment
+- Strategy refinement
+
+**Q4 - Planning**
+- Goal setting
+- Budget allocation
+- Resource planning
+- OKR development
+
+**Q1 - Launch**
+- Communication cascade
+- Initiative kickoff
+- Quick wins
+- Baseline metrics
+
+**Q2 - Review**
+- Progress assessment
+- Course correction
+- Mid-year planning
+- Performance review
+
+## Exit Strategy Planning
+
+### Exit Options Evaluation
+
+1. **IPO**
+ - Pros: Maximum valuation, maintain control
+ - Cons: Regulatory burden, public scrutiny
+ - Timeline: 12-24 months
+
+2. **Strategic Acquisition**
+ - Pros: Synergies, quick process
+ - Cons: Loss of independence, integration risk
+ - Timeline: 6-12 months
+
+3. **Private Equity**
+ - Pros: Growth capital, expertise
+ - Cons: Pressure for returns, loss of control
+ - Timeline: 3-6 months
+
+4. **Management Buyout**
+ - Pros: Continuity, culture preservation
+ - Cons: Limited price, financing challenge
+ - Timeline: 6-9 months
+
+### Value Creation Levers
+
+1. **Revenue Growth**
+ - Organic expansion
+ - Market development
+ - Product innovation
+ - Pricing optimization
+
+2. **Margin Improvement**
+ - Operational efficiency
+ - Cost reduction
+ - Mix optimization
+ - Pricing power
+
+3. **Multiple Expansion**
+ - Market positioning
+ - Growth trajectory
+ - Risk reduction
+ - Story telling
diff --git a/skills/c-level-advisor/ceo-advisor/references/leadership_organizational_culture.md b/skills/c-level-advisor/ceo-advisor/references/leadership_organizational_culture.md
new file mode 100644
index 00000000..5b3d911f
--- /dev/null
+++ b/skills/c-level-advisor/ceo-advisor/references/leadership_organizational_culture.md
@@ -0,0 +1,682 @@
+# Leadership & Organizational Culture Guide
+
+## Leadership Philosophy
+
+### The Five Dimensions of CEO Leadership
+
+1. **Visionary Leadership**
+ - Define compelling future state
+ - Communicate vision consistently
+ - Inspire action toward vision
+ - Measure progress systematically
+
+2. **Strategic Leadership**
+ - Set clear priorities
+ - Allocate resources optimally
+ - Make tough trade-offs
+ - Drive execution excellence
+
+3. **Operational Leadership**
+ - Establish performance standards
+ - Build scalable systems
+ - Drive continuous improvement
+ - Ensure accountability
+
+4. **People Leadership**
+ - Attract top talent
+ - Develop future leaders
+ - Foster engagement
+ - Build inclusive culture
+
+5. **External Leadership**
+ - Represent company publicly
+ - Build strategic partnerships
+ - Engage stakeholders effectively
+ - Shape industry direction
+
+## Organizational Culture Framework
+
+### Culture Definition & Assessment
+
+#### Cultural Dimensions Model
+
+**Innovation ← → Stability**
+- Risk tolerance level
+- Change readiness
+- Experimentation mindset
+- Learning from failure
+
+**Competition ← → Collaboration**
+- Internal dynamics
+- Knowledge sharing
+- Team vs individual rewards
+- Cross-functional cooperation
+
+**Customer ← → Operations**
+- External vs internal focus
+- Customer centricity
+- Process emphasis
+- Quality standards
+
+**Short-term ← → Long-term**
+- Planning horizons
+- Investment philosophy
+- Performance metrics
+- Stakeholder balance
+
+### Culture Transformation Roadmap
+
+#### Phase 1: Assessment (Months 1-2)
+
+**Current State Analysis**:
+- Employee survey (engagement, values alignment)
+- Culture assessment (competing values framework)
+- Leadership 360 feedback
+- Exit interview analysis
+- Customer feedback integration
+
+**Gap Analysis**:
+- Current vs desired culture
+- Behavioral gaps
+- System misalignments
+- Leadership gaps
+- Communication gaps
+
+#### Phase 2: Design (Months 2-3)
+
+**Target Culture Definition**:
+- Core values articulation
+- Behavioral standards
+- Leadership principles
+- Decision principles
+- Performance expectations
+
+**Change Strategy**:
+- Stakeholder mapping
+- Communication plan
+- Training requirements
+- System changes needed
+- Quick wins identification
+
+#### Phase 3: Implementation (Months 4-12)
+
+**Launch Activities**:
+- Leadership alignment sessions
+- All-hands kickoff
+- Values workshops
+- Behavioral training
+- System updates
+
+**Reinforcement Mechanisms**:
+- Recognition programs
+- Performance integration
+- Hiring/promotion criteria
+- Story collection
+- Celebration events
+
+#### Phase 4: Embedding (Months 12+)
+
+**Sustainability Actions**:
+- Regular pulse surveys
+- Culture champions network
+- Continuous reinforcement
+- System alignment
+- Leadership modeling
+
+## Leadership Development
+
+### Executive Team Development
+
+#### Team Effectiveness Model
+
+**Foundation Elements**:
+1. **Trust** - Vulnerability-based trust
+2. **Conflict** - Healthy debate
+3. **Commitment** - Buy-in to decisions
+4. **Accountability** - Peer accountability
+5. **Results** - Collective outcomes
+
+#### Executive Team Charter
+
+```
+Our Executive Team Charter
+
+Purpose:
+Lead [Company] to achieve its vision of [Vision Statement]
+
+Responsibilities:
+• Set strategic direction
+• Allocate resources
+• Drive performance
+• Develop talent
+• Shape culture
+
+Operating Principles:
+• Debate in private, unite in public
+• Challenge ideas, support people
+• Company first, function second
+• Transparency with trust
+• Accountability without blame
+
+Meeting Cadence:
+• Weekly tactical (2 hours)
+• Monthly strategic (4 hours)
+• Quarterly offsite (2 days)
+• Annual planning (3 days)
+
+Decision Rights:
+• CEO: Final decision after consultation
+• Consensus: Strategic initiatives
+• Individual: Functional operations
+• Escalation: Board-level matters
+
+Success Metrics:
+• Company performance vs plan
+• Employee engagement score
+• Customer satisfaction (NPS)
+• Team effectiveness rating
+```
+
+### Succession Planning
+
+#### Succession Planning Framework
+
+**CEO Succession Timeline**:
+
+**Ongoing**:
+- Identify potential successors
+- Development plan execution
+- Board exposure
+- External benchmarking
+
+**T-3 Years**:
+- Formal succession planning
+- Candidate assessment
+- Development acceleration
+- Emergency plan update
+
+**T-1 Year**:
+- Final candidate selection
+- Transition planning
+- Communication strategy
+- Onboarding preparation
+
+**Transition**:
+- Announcement
+- Knowledge transfer
+- Stakeholder introductions
+- Gradual handover
+
+#### Talent Pipeline Development
+
+**9-Box Grid for Talent Review**:
+
+```
+Performance →
+ ↑
+ │ Rising │ High │ Star
+High│ Star │Performer│ Performer
+ ├─────────┼─────────┼──────────
+ │Solid │ Core │ High
+Med │Performer│Performer│ Potential
+ ├─────────┼─────────┼──────────
+ │ Under │Inconsist│ New/
+Low │Performer│ -ent │ Learning
+ └─────────┴─────────┴──────────
+ Low Medium High
+ Potential →
+```
+
+**Development Strategies by Box**:
+- **Stars**: Accelerated development, stretch assignments
+- **High Performers**: Retention focus, leadership opportunities
+- **High Potentials**: Intensive coaching, skill building
+- **Core Performers**: Engagement, incremental growth
+- **Underperformers**: Performance improvement or exit
+
+### Leadership Competency Model
+
+#### Core Leadership Competencies
+
+**Strategic Thinking**
+- Vision development
+- Systems thinking
+- Innovation mindset
+- External awareness
+- Long-term planning
+
+**Execution Excellence**
+- Results orientation
+- Decision quality
+- Problem solving
+- Process management
+- Risk management
+
+**People Leadership**
+- Team building
+- Talent development
+- Communication
+- Influence
+- Emotional intelligence
+
+**Personal Excellence**
+- Integrity
+- Resilience
+- Continuous learning
+- Self-awareness
+- Adaptability
+
+## Communication & Engagement
+
+### Internal Communication Strategy
+
+#### Communication Channels
+
+| Channel | Frequency | Purpose | Audience |
+|---------|-----------|---------|----------|
+| All-hands meeting | Monthly | Updates, Q&A | All employees |
+| Leadership cascade | Weekly | Alignment | Managers |
+| CEO email | Bi-weekly | Vision, recognition | All employees |
+| Town halls | Quarterly | Deep dives | All employees |
+| Skip-levels | Monthly | Direct feedback | Various levels |
+| Intranet | Daily | News, resources | All employees |
+| Slack/Teams | Real-time | Collaboration | All employees |
+
+#### CEO Communication Calendar
+
+**Weekly**:
+- Executive team meeting
+- Leadership message cascade
+- Customer/partner touchpoint
+
+**Bi-weekly**:
+- Company-wide email
+- Skip-level meetings
+- Media/analyst interaction
+
+**Monthly**:
+- All-hands meeting
+- Board member touchpoint
+- Employee roundtable
+
+**Quarterly**:
+- Earnings communication
+- Town hall deep-dive
+- Strategy review
+- Culture celebration
+
+### Employee Engagement
+
+#### Engagement Survey Framework
+
+**Dimensions Measured**:
+1. Purpose & Vision (alignment, inspiration)
+2. Leadership (trust, communication)
+3. Management (support, development)
+4. Work Environment (tools, processes)
+5. Growth (career, learning)
+6. Recognition (appreciation, fairness)
+7. Wellbeing (balance, benefits)
+8. Belonging (inclusion, connection)
+
+**Action Planning Process**:
+1. Share results transparently
+2. Identify 2-3 focus areas
+3. Create action teams
+4. Define success metrics
+5. Implement changes
+6. Communicate progress
+7. Measure impact
+
+#### Engagement Initiatives
+
+**Recognition Programs**:
+- Spot awards (peer-nominated)
+- Quarterly achievements
+- Annual excellence awards
+- Values champions
+- Innovation celebrations
+- Customer hero awards
+
+**Development Programs**:
+- Leadership academy
+- Mentorship program
+- Rotation opportunities
+- Tuition reimbursement
+- Conference attendance
+- Skill workshops
+
+**Wellbeing Initiatives**:
+- Flexible work arrangements
+- Mental health support
+- Wellness programs
+- Time-off policies
+- Family support
+- Financial wellness
+
+## Performance Management
+
+### OKR Framework
+
+#### OKR Setting Process
+
+**Company OKRs** (Annual)
+↓
+**Department OKRs** (Quarterly)
+↓
+**Team OKRs** (Quarterly)
+↓
+**Individual OKRs** (Quarterly)
+
+#### OKR Template
+
+**Objective**: [Qualitative, inspirational goal]
+
+**Key Results**:
+1. [Quantitative outcome] from [X] to [Y]
+2. [Quantitative outcome] from [X] to [Y]
+3. [Quantitative outcome] from [X] to [Y]
+
+**Example**:
+```
+Objective: Become the market leader in customer satisfaction
+
+Key Results:
+1. Increase NPS from 45 to 70
+2. Reduce support ticket resolution from 48h to 24h
+3. Achieve 95% customer retention rate (from 87%)
+```
+
+### Performance Review System
+
+#### Continuous Performance Management
+
+**Weekly**: 1-on-1 check-ins (30 min)
+- Progress on priorities
+- Obstacles/support needed
+- Feedback exchange
+- Next week focus
+
+**Monthly**: Development discussion (60 min)
+- Skill development
+- Career aspirations
+- Stretch opportunities
+- Learning plan
+
+**Quarterly**: Performance review (90 min)
+- OKR assessment
+- Competency evaluation
+- 360 feedback review
+- Development planning
+
+**Annual**: Compensation review
+- Performance rating
+- Compensation adjustment
+- Promotion decisions
+- Succession planning
+
+## Change Management
+
+### Change Leadership Model
+
+#### Eight-Step Change Process
+
+1. **Create Urgency**
+ - Share compelling data
+ - Highlight risks of status quo
+ - Create dissatisfaction with current state
+
+2. **Build Coalition**
+ - Identify change champions
+ - Ensure executive alignment
+ - Engage influential supporters
+
+3. **Form Vision**
+ - Define clear end state
+ - Create inspiring narrative
+ - Develop strategy
+
+4. **Communicate Vision**
+ - Multi-channel communication
+ - Repetition and consistency
+ - Two-way dialogue
+
+5. **Empower Action**
+ - Remove barriers
+ - Change systems/processes
+ - Encourage risk-taking
+
+6. **Create Quick Wins**
+ - Identify early victories
+ - Celebrate visibly
+ - Build momentum
+
+7. **Consolidate Gains**
+ - Don't declare victory early
+ - Continue driving change
+ - Address deeper issues
+
+8. **Anchor in Culture**
+ - Reinforce through systems
+ - Celebrate new behaviors
+ - Ensure leadership continuity
+
+### Organizational Design
+
+#### Design Principles
+
+**Customer-Centric**
+- Organize around customer needs
+- Minimize handoffs
+- Clear ownership
+- Fast decision-making
+
+**Scalable**
+- Consistent structures
+- Clear roles/responsibilities
+- Repeatable processes
+- Growth-ready
+
+**Agile**
+- Cross-functional teams
+- Rapid iteration
+- Continuous learning
+- Adaptive planning
+
+**Efficient**
+- Appropriate spans of control (5-7)
+- Minimal layers (max 5-6)
+- Clear decision rights
+- Eliminated redundancy
+
+#### Reorganization Playbook
+
+**Pre-announcement** (4-6 weeks)
+- Design new structure
+- Identify leadership
+- Plan communication
+- Prepare materials
+
+**Announcement** (Day 0)
+- All-hands meeting
+- Written communication
+- Q&A sessions
+- Manager toolkit
+
+**Transition** (30 days)
+- Role clarifications
+- Team formations
+- Process updates
+- System changes
+
+**Stabilization** (60-90 days)
+- Monitor progress
+- Address issues
+- Refine as needed
+- Celebrate success
+
+## Crisis Leadership
+
+### Crisis Response Framework
+
+#### Leadership During Crisis
+
+**Immediate Response** (0-24 hours)
+- Establish command center
+- Assess situation
+- Communicate frequently
+- Make rapid decisions
+- Show visible leadership
+
+**Stabilization** (1-7 days)
+- Implement solutions
+- Maintain communication
+- Support teams
+- Monitor progress
+- Adjust approach
+
+**Recovery** (1-4 weeks)
+- Execute recovery plan
+- Address long-term impacts
+- Learn from crisis
+- Strengthen resilience
+- Recognize heroes
+
+#### Crisis Communication
+
+**Internal Communication**:
+- Frequency: 2x daily minimum
+- Channels: Email, video, town halls
+- Content: Facts, actions, support
+- Tone: Calm, confident, caring
+
+**External Communication**:
+- Stakeholders: Customers, partners, investors, media
+- Frequency: As needed
+- Channels: Website, press, social
+- Content: Impact, response, timeline
+- Tone: Transparent, responsible
+
+## Innovation Culture
+
+### Innovation Framework
+
+#### Innovation Portfolio
+
+**Horizon 1** (70% resources)
+- Core business innovation
+- Incremental improvements
+- 6-18 month timeline
+- Lower risk
+
+**Horizon 2** (20% resources)
+- Emerging opportunities
+- Adjacent markets
+- 18-36 month timeline
+- Moderate risk
+
+**Horizon 3** (10% resources)
+- Transformational bets
+- New business models
+- 3-5 year timeline
+- Higher risk
+
+#### Innovation Programs
+
+**Innovation Time**
+- 20% time for projects
+- Hackathons quarterly
+- Innovation challenges
+- Idea platforms
+- Patent incentives
+
+**Innovation Metrics**
+- % revenue from new products
+- Ideas generated/implemented
+- Time to market
+- Innovation ROI
+- Patent applications
+
+## Diversity, Equity & Inclusion
+
+### DEI Strategy Framework
+
+#### Four Pillars of DEI
+
+1. **Representation**
+ - Diverse hiring
+ - Promotion equity
+ - Leadership diversity
+ - Board diversity
+
+2. **Inclusion**
+ - Belonging index
+ - Psychological safety
+ - Equitable practices
+ - Bias mitigation
+
+3. **Development**
+ - Sponsorship programs
+ - ERG support
+ - Leadership development
+ - Career pathways
+
+4. **Accountability**
+ - DEI metrics
+ - Leader goals
+ - Regular reporting
+ - Transparency
+
+#### DEI Metrics Dashboard
+
+| Metric | Current | Target | Timeline |
+|--------|---------|--------|----------|
+| Women in leadership | X% | Y% | Z years |
+| Ethnic diversity | X% | Y% | Z years |
+| Pay equity gap | X% | 0% | Z years |
+| Inclusion index | X/100 | Y/100 | Z years |
+| Retention equality | X% diff | 0% diff | Z years |
+
+## Executive Presence
+
+### CEO Personal Brand
+
+#### Brand Elements
+
+**Vision**: What future you're creating
+**Values**: What you stand for
+**Voice**: How you communicate
+**Visibility**: Where you show up
+**Value**: What you deliver
+
+#### Executive Communication
+
+**Speaking Frameworks**:
+
+**PREP Method**:
+- **P**oint: Main message
+- **R**eason: Why it matters
+- **E**xample: Concrete illustration
+- **P**oint: Restate message
+
+**STAR Method** (for stories):
+- **S**ituation: Context
+- **T**ask: Challenge
+- **A**ction: What was done
+- **R**esult: Outcome
+
+#### Media Training Essentials
+
+**Key Message Discipline**:
+- 3 key messages maximum
+- Bridge to messages
+- Sound bites ready
+- Avoid speculation
+- Stay on record
+
+**Interview Techniques**:
+- Pause before answering
+- Bridge to key messages
+- Use examples/stories
+- Maintain eye contact
+- Control pace
diff --git a/skills/c-level-advisor/ceo-advisor/scripts/financial_scenario_analyzer.py b/skills/c-level-advisor/ceo-advisor/scripts/financial_scenario_analyzer.py
new file mode 100644
index 00000000..45bf8445
--- /dev/null
+++ b/skills/c-level-advisor/ceo-advisor/scripts/financial_scenario_analyzer.py
@@ -0,0 +1,451 @@
+#!/usr/bin/env python3
+"""
+Financial Scenario Analyzer - Model different business scenarios and their financial impact
+"""
+
+import json
+from typing import Dict, List, Tuple
+import math
+
+class FinancialScenarioAnalyzer:
+ def __init__(self):
+ self.key_metrics = [
+ 'revenue', 'gross_margin', 'operating_expenses',
+ 'ebitda', 'cash_flow', 'runway', 'valuation'
+ ]
+
+ self.growth_models = {
+ 'linear': lambda base, rate, period: base * (1 + rate * period),
+ 'exponential': lambda base, rate, period: base * math.pow(1 + rate, period),
+ 'logarithmic': lambda base, rate, period: base * (1 + rate * math.log(period + 1)),
+ 's_curve': lambda base, rate, period: base * (2 / (1 + math.exp(-rate * period)))
+ }
+
+ def analyze_scenarios(self, base_case: Dict, scenarios: List[Dict]) -> Dict:
+ """Analyze multiple financial scenarios"""
+ results = {
+ 'base_case_summary': self._summarize_financials(base_case),
+ 'scenario_analysis': [],
+ 'sensitivity_analysis': {},
+ 'recommendation': {},
+ 'risk_adjusted_view': {}
+ }
+
+ # Analyze each scenario
+ for scenario in scenarios:
+ scenario_result = self._analyze_scenario(base_case, scenario)
+ results['scenario_analysis'].append(scenario_result)
+
+ # Sensitivity analysis
+ results['sensitivity_analysis'] = self._perform_sensitivity_analysis(
+ base_case,
+ scenarios
+ )
+
+ # Risk-adjusted view
+ results['risk_adjusted_view'] = self._calculate_risk_adjusted_returns(
+ results['scenario_analysis']
+ )
+
+ # Generate recommendation
+ results['recommendation'] = self._generate_recommendation(
+ results['scenario_analysis'],
+ results['risk_adjusted_view']
+ )
+
+ return results
+
+ def _summarize_financials(self, financials: Dict) -> Dict:
+ """Summarize key financial metrics"""
+ revenue = financials.get('revenue', 0)
+ cogs = financials.get('cogs', 0)
+ opex = financials.get('operating_expenses', 0)
+
+ gross_profit = revenue - cogs
+ gross_margin = (gross_profit / revenue * 100) if revenue > 0 else 0
+ ebitda = gross_profit - opex
+ ebitda_margin = (ebitda / revenue * 100) if revenue > 0 else 0
+
+ return {
+ 'revenue': revenue,
+ 'gross_profit': gross_profit,
+ 'gross_margin': gross_margin,
+ 'operating_expenses': opex,
+ 'ebitda': ebitda,
+ 'ebitda_margin': ebitda_margin,
+ 'cash': financials.get('cash', 0),
+ 'burn_rate': financials.get('burn_rate', 0),
+ 'runway_months': self._calculate_runway(
+ financials.get('cash', 0),
+ financials.get('burn_rate', 0)
+ )
+ }
+
+ def _calculate_runway(self, cash: float, burn_rate: float) -> float:
+ """Calculate months of runway"""
+ if burn_rate <= 0:
+ return float('inf')
+ return cash / burn_rate
+
+ def _analyze_scenario(self, base_case: Dict, scenario: Dict) -> Dict:
+ """Analyze a single scenario"""
+ name = scenario.get('name', 'Unnamed Scenario')
+ probability = scenario.get('probability', 0.5)
+
+ # Apply scenario changes
+ projected_financials = self._apply_scenario_changes(base_case, scenario)
+
+ # Calculate metrics for each year
+ projections = []
+ current_state = projected_financials.copy()
+
+ for year in range(1, 4): # 3-year projection
+ year_projection = self._project_year(
+ current_state,
+ scenario,
+ year
+ )
+ projections.append(year_projection)
+ current_state = year_projection
+
+ # Calculate NPV and IRR
+ cash_flows = [p['free_cash_flow'] for p in projections]
+ npv = self._calculate_npv(cash_flows, scenario.get('discount_rate', 0.1))
+ irr = self._calculate_irr(cash_flows, base_case.get('initial_investment', 0))
+
+ return {
+ 'name': name,
+ 'probability': probability,
+ 'projections': projections,
+ 'npv': npv,
+ 'irr': irr,
+ 'break_even_month': self._find_break_even(projections),
+ 'total_return': self._calculate_total_return(projections, base_case),
+ 'key_assumptions': scenario.get('assumptions', [])
+ }
+
+ def _apply_scenario_changes(self, base_case: Dict, scenario: Dict) -> Dict:
+ """Apply scenario changes to base case"""
+ result = base_case.copy()
+ changes = scenario.get('changes', {})
+
+ for key, change in changes.items():
+ if key in result:
+ if isinstance(change, dict):
+ # Relative change
+ if 'multiply' in change:
+ result[key] *= change['multiply']
+ elif 'add' in change:
+ result[key] += change['add']
+ else:
+ # Absolute change
+ result[key] = change
+
+ return result
+
+ def _project_year(self, current_state: Dict, scenario: Dict, year: int) -> Dict:
+ """Project financials for a specific year"""
+ growth_model = scenario.get('growth_model', 'exponential')
+ growth_rate = scenario.get('growth_rate', 0.3)
+
+ # Apply growth model
+ model_func = self.growth_models.get(growth_model, self.growth_models['linear'])
+
+ revenue = model_func(
+ current_state.get('revenue', 0),
+ growth_rate,
+ year
+ )
+
+ # Scale other metrics
+ cogs = revenue * scenario.get('cogs_ratio', 0.3)
+ opex = current_state.get('operating_expenses', 0) * (1 + scenario.get('opex_growth', 0.15))
+
+ gross_profit = revenue - cogs
+ ebitda = gross_profit - opex
+
+ # Calculate free cash flow (simplified)
+ capex = revenue * scenario.get('capex_ratio', 0.05)
+ working_capital_change = (revenue - current_state.get('revenue', 0)) * 0.1
+ free_cash_flow = ebitda - capex - working_capital_change
+
+ return {
+ 'year': year,
+ 'revenue': revenue,
+ 'gross_profit': gross_profit,
+ 'gross_margin': (gross_profit / revenue * 100) if revenue > 0 else 0,
+ 'operating_expenses': opex,
+ 'ebitda': ebitda,
+ 'ebitda_margin': (ebitda / revenue * 100) if revenue > 0 else 0,
+ 'free_cash_flow': free_cash_flow,
+ 'cumulative_cash_flow': current_state.get('cumulative_cash_flow', 0) + free_cash_flow
+ }
+
+ def _calculate_npv(self, cash_flows: List[float], discount_rate: float) -> float:
+ """Calculate Net Present Value"""
+ npv = 0
+ for i, cf in enumerate(cash_flows):
+ npv += cf / math.pow(1 + discount_rate, i + 1)
+ return npv
+
+ def _calculate_irr(self, cash_flows: List[float], initial_investment: float) -> float:
+ """Calculate Internal Rate of Return (simplified)"""
+ if not cash_flows or initial_investment == 0:
+ return 0
+
+ # Simple IRR approximation
+ total_return = sum(cash_flows)
+ years = len(cash_flows)
+
+ if initial_investment > 0:
+ return math.pow(total_return / initial_investment, 1/years) - 1
+ return 0
+
+ def _find_break_even(self, projections: List[Dict]) -> int:
+ """Find break-even month"""
+ months = 0
+ for projection in projections:
+ months += 12
+ if projection.get('ebitda', 0) > 0:
+ # Interpolate to find exact month
+ if months == 12:
+ return months
+ prev_ebitda = projections[projection['year']-2].get('ebitda', 0) if projection['year'] > 1 else 0
+ monthly_improvement = (projection['ebitda'] - prev_ebitda) / 12
+ if monthly_improvement > 0:
+ months_to_breakeven = abs(prev_ebitda) / monthly_improvement
+ return int(months - 12 + months_to_breakeven)
+ return -1 # Not reached
+
+ def _calculate_total_return(self, projections: List[Dict], base_case: Dict) -> float:
+ """Calculate total return multiple"""
+ initial = base_case.get('valuation', 1000000)
+
+ # Simple valuation at end (10x revenue multiple for SaaS)
+ final_revenue = projections[-1]['revenue'] if projections else 0
+ final_valuation = final_revenue * 10
+
+ return (final_valuation / initial) if initial > 0 else 0
+
+ def _perform_sensitivity_analysis(self, base_case: Dict, scenarios: List[Dict]) -> Dict:
+ """Perform sensitivity analysis on key variables"""
+ sensitivity = {}
+
+ key_variables = ['growth_rate', 'gross_margin', 'customer_acquisition_cost']
+
+ for variable in key_variables:
+ sensitivity[variable] = {
+ 'low': self._calculate_variable_impact(base_case, variable, -0.2),
+ 'base': self._calculate_variable_impact(base_case, variable, 0),
+ 'high': self._calculate_variable_impact(base_case, variable, 0.2)
+ }
+
+ return sensitivity
+
+ def _calculate_variable_impact(self, base_case: Dict, variable: str, change: float) -> float:
+ """Calculate impact of variable change on valuation"""
+ # Simplified impact calculation
+ impacts = {
+ 'growth_rate': 2.5, # 2.5x multiplier on valuation
+ 'gross_margin': 1.8, # 1.8x multiplier
+ 'customer_acquisition_cost': -1.2 # Negative impact
+ }
+
+ base_value = 10000000 # Base valuation
+ impact_multiplier = impacts.get(variable, 1.0)
+
+ return base_value * (1 + change * impact_multiplier)
+
+ def _calculate_risk_adjusted_returns(self, scenarios: List[Dict]) -> Dict:
+ """Calculate risk-adjusted returns"""
+ expected_value = 0
+ best_case = None
+ worst_case = None
+
+ for scenario in scenarios:
+ probability = scenario['probability']
+ npv = scenario['npv']
+
+ expected_value += probability * npv
+
+ if best_case is None or npv > best_case['npv']:
+ best_case = scenario
+
+ if worst_case is None or npv < worst_case['npv']:
+ worst_case = scenario
+
+ # Calculate standard deviation (simplified)
+ variance = sum([
+ scenario['probability'] * math.pow(scenario['npv'] - expected_value, 2)
+ for scenario in scenarios
+ ])
+ std_dev = math.sqrt(variance)
+
+ return {
+ 'expected_value': expected_value,
+ 'best_case': best_case['name'] if best_case else 'None',
+ 'best_case_npv': best_case['npv'] if best_case else 0,
+ 'worst_case': worst_case['name'] if worst_case else 'None',
+ 'worst_case_npv': worst_case['npv'] if worst_case else 0,
+ 'standard_deviation': std_dev,
+ 'sharpe_ratio': (expected_value / std_dev) if std_dev > 0 else 0
+ }
+
+ def _generate_recommendation(self, scenarios: List[Dict], risk_adjusted: Dict) -> Dict:
+ """Generate recommendation based on analysis"""
+ recommendation = {
+ 'recommended_scenario': '',
+ 'rationale': [],
+ 'key_actions': [],
+ 'risk_mitigation': []
+ }
+
+ # Find optimal scenario
+ best_risk_adjusted = max(scenarios, key=lambda s: s['npv'] * s['probability'])
+ recommendation['recommended_scenario'] = best_risk_adjusted['name']
+
+ # Generate rationale
+ if best_risk_adjusted['npv'] > 0:
+ recommendation['rationale'].append(f"Positive NPV of ${best_risk_adjusted['npv']:,.0f}")
+
+ if best_risk_adjusted['irr'] > 0.15:
+ recommendation['rationale'].append(f"Strong IRR of {best_risk_adjusted['irr']:.1%}")
+
+ if best_risk_adjusted['break_even_month'] > 0 and best_risk_adjusted['break_even_month'] < 24:
+ recommendation['rationale'].append(f"Quick path to profitability ({best_risk_adjusted['break_even_month']} months)")
+
+ # Key actions
+ recommendation['key_actions'] = [
+ 'Secure funding for growth initiatives',
+ 'Build scalable operational infrastructure',
+ 'Invest in customer acquisition channels',
+ 'Strengthen unit economics',
+ 'Establish financial controls'
+ ]
+
+ # Risk mitigation
+ if risk_adjusted['standard_deviation'] > risk_adjusted['expected_value'] * 0.5:
+ recommendation['risk_mitigation'].append('High variability - consider hedging strategies')
+
+ recommendation['risk_mitigation'].extend([
+ 'Maintain 12+ months runway',
+ 'Diversify revenue streams',
+ 'Build contingency plans for downside scenarios'
+ ])
+
+ return recommendation
+
+def analyze_financial_scenarios(base_case: Dict, scenarios: List[Dict]) -> str:
+ """Main function to analyze financial scenarios"""
+ analyzer = FinancialScenarioAnalyzer()
+ results = analyzer.analyze_scenarios(base_case, scenarios)
+
+ # Format output
+ output = [
+ "=== Financial Scenario Analysis ===",
+ "",
+ "Base Case Summary:",
+ f" Revenue: ${results['base_case_summary']['revenue']:,.0f}",
+ f" Gross Margin: {results['base_case_summary']['gross_margin']:.1f}%",
+ f" EBITDA: ${results['base_case_summary']['ebitda']:,.0f}",
+ f" Runway: {results['base_case_summary']['runway_months']:.1f} months",
+ "",
+ "Scenario Analysis:"
+ ]
+
+ for scenario in results['scenario_analysis']:
+ output.append(f"\n{scenario['name']} (Probability: {scenario['probability']:.0%})")
+ output.append(f" NPV: ${scenario['npv']:,.0f}")
+ output.append(f" IRR: {scenario['irr']:.1%}")
+ output.append(f" Break-even: {scenario['break_even_month']} months")
+ output.append(f" Return Multiple: {scenario['total_return']:.1f}x")
+
+ # Show Year 3 projection
+ if scenario['projections']:
+ year3 = scenario['projections'][-1]
+ output.append(f" Year 3 Revenue: ${year3['revenue']:,.0f}")
+ output.append(f" Year 3 EBITDA Margin: {year3['ebitda_margin']:.1f}%")
+
+ output.extend([
+ "",
+ "Risk-Adjusted Analysis:",
+ f" Expected Value: ${results['risk_adjusted_view']['expected_value']:,.0f}",
+ f" Best Case: {results['risk_adjusted_view']['best_case']} (${results['risk_adjusted_view']['best_case_npv']:,.0f})",
+ f" Worst Case: {results['risk_adjusted_view']['worst_case']} (${results['risk_adjusted_view']['worst_case_npv']:,.0f})",
+ f" Risk (Std Dev): ${results['risk_adjusted_view']['standard_deviation']:,.0f}",
+ f" Sharpe Ratio: {results['risk_adjusted_view']['sharpe_ratio']:.2f}",
+ "",
+ f"RECOMMENDATION: {results['recommendation']['recommended_scenario']}",
+ "",
+ "Rationale:"
+ ])
+
+ for reason in results['recommendation']['rationale']:
+ output.append(f" • {reason}")
+
+ output.extend([
+ "",
+ "Key Actions:"
+ ])
+
+ for action in results['recommendation']['key_actions'][:3]:
+ output.append(f" • {action}")
+
+ return '\n'.join(output)
+
+if __name__ == "__main__":
+ # Example usage
+ example_base_case = {
+ 'revenue': 5000000,
+ 'cogs': 1500000,
+ 'operating_expenses': 3000000,
+ 'cash': 2000000,
+ 'burn_rate': 200000,
+ 'valuation': 20000000,
+ 'initial_investment': 5000000
+ }
+
+ example_scenarios = [
+ {
+ 'name': 'Aggressive Growth',
+ 'probability': 0.3,
+ 'growth_model': 'exponential',
+ 'growth_rate': 0.5,
+ 'changes': {
+ 'operating_expenses': {'multiply': 1.3}
+ },
+ 'assumptions': ['Market expansion successful', 'Product-market fit achieved'],
+ 'cogs_ratio': 0.25,
+ 'opex_growth': 0.3,
+ 'capex_ratio': 0.08,
+ 'discount_rate': 0.12
+ },
+ {
+ 'name': 'Moderate Growth',
+ 'probability': 0.5,
+ 'growth_model': 'exponential',
+ 'growth_rate': 0.3,
+ 'changes': {},
+ 'assumptions': ['Steady market growth', 'Competition remains stable'],
+ 'cogs_ratio': 0.3,
+ 'opex_growth': 0.15,
+ 'capex_ratio': 0.05,
+ 'discount_rate': 0.10
+ },
+ {
+ 'name': 'Conservative',
+ 'probability': 0.2,
+ 'growth_model': 'linear',
+ 'growth_rate': 0.15,
+ 'changes': {
+ 'operating_expenses': {'multiply': 0.9}
+ },
+ 'assumptions': ['Market headwinds', 'Focus on profitability'],
+ 'cogs_ratio': 0.35,
+ 'opex_growth': 0.05,
+ 'capex_ratio': 0.03,
+ 'discount_rate': 0.08
+ }
+ ]
+
+ print(analyze_financial_scenarios(example_base_case, example_scenarios))
diff --git a/skills/c-level-advisor/ceo-advisor/scripts/strategy_analyzer.py b/skills/c-level-advisor/ceo-advisor/scripts/strategy_analyzer.py
new file mode 100644
index 00000000..e871d662
--- /dev/null
+++ b/skills/c-level-advisor/ceo-advisor/scripts/strategy_analyzer.py
@@ -0,0 +1,609 @@
+#!/usr/bin/env python3
+"""
+Strategic Planning Analyzer - Comprehensive business strategy assessment tool
+"""
+
+import json
+from typing import Dict, List, Tuple
+from datetime import datetime, timedelta
+import math
+
+class StrategyAnalyzer:
+ def __init__(self):
+ self.strategic_pillars = {
+ 'market_position': {
+ 'weight': 0.25,
+ 'factors': ['market_share', 'brand_strength', 'competitive_advantage', 'customer_loyalty']
+ },
+ 'financial_health': {
+ 'weight': 0.25,
+ 'factors': ['revenue_growth', 'profitability', 'cash_flow', 'unit_economics']
+ },
+ 'operational_excellence': {
+ 'weight': 0.20,
+ 'factors': ['efficiency', 'quality', 'scalability', 'innovation']
+ },
+ 'organizational_capability': {
+ 'weight': 0.20,
+ 'factors': ['talent', 'culture', 'leadership', 'agility']
+ },
+ 'growth_potential': {
+ 'weight': 0.10,
+ 'factors': ['market_size', 'expansion_opportunities', 'product_pipeline', 'partnerships']
+ }
+ }
+
+ self.strategic_frameworks = {
+ 'porter_five_forces': [
+ 'competitive_rivalry',
+ 'supplier_power',
+ 'buyer_power',
+ 'threat_of_substitution',
+ 'threat_of_new_entry'
+ ],
+ 'swot': ['strengths', 'weaknesses', 'opportunities', 'threats'],
+ 'bcg_matrix': ['stars', 'cash_cows', 'question_marks', 'dogs'],
+ 'ansoff_matrix': ['market_penetration', 'market_development', 'product_development', 'diversification']
+ }
+
+ def analyze_strategic_position(self, company_data: Dict) -> Dict:
+ """Comprehensive strategic analysis"""
+ results = {
+ 'timestamp': datetime.now().isoformat(),
+ 'company': company_data.get('name', 'Company'),
+ 'strategic_health_score': 0,
+ 'pillar_analysis': {},
+ 'framework_analysis': {},
+ 'strategic_options': [],
+ 'risk_assessment': {},
+ 'recommendations': [],
+ 'roadmap': {}
+ }
+
+ # Analyze strategic pillars
+ total_score = 0
+ for pillar, config in self.strategic_pillars.items():
+ pillar_score = self._analyze_pillar(
+ company_data.get(pillar, {}),
+ config['factors']
+ )
+ weighted_score = pillar_score * config['weight']
+ results['pillar_analysis'][pillar] = {
+ 'score': pillar_score,
+ 'weighted_score': weighted_score,
+ 'level': self._get_level(pillar_score),
+ 'factors': self._get_pillar_details(company_data.get(pillar, {}), config['factors'])
+ }
+ total_score += weighted_score
+
+ results['strategic_health_score'] = round(total_score, 1)
+
+ # Framework analysis
+ results['framework_analysis'] = self._apply_frameworks(company_data)
+
+ # Generate strategic options
+ results['strategic_options'] = self._generate_strategic_options(
+ results['pillar_analysis'],
+ company_data.get('context', {})
+ )
+
+ # Risk assessment
+ results['risk_assessment'] = self._assess_strategic_risks(
+ company_data,
+ results['strategic_options']
+ )
+
+ # Generate roadmap
+ results['roadmap'] = self._create_strategic_roadmap(
+ results['strategic_options'],
+ company_data.get('timeline', 12)
+ )
+
+ # Generate recommendations
+ results['recommendations'] = self._generate_recommendations(results)
+
+ return results
+
+ def _analyze_pillar(self, pillar_data: Dict, factors: List) -> float:
+ """Analyze a strategic pillar"""
+ if not pillar_data:
+ return 50.0
+
+ total_score = 0
+ count = 0
+
+ for factor in factors:
+ if factor in pillar_data:
+ score = pillar_data[factor]
+ total_score += score
+ count += 1
+
+ return (total_score / count) if count > 0 else 50.0
+
+ def _get_pillar_details(self, pillar_data: Dict, factors: List) -> List[Dict]:
+ """Get detailed factor analysis"""
+ details = []
+
+ for factor in factors:
+ score = pillar_data.get(factor, 50)
+ details.append({
+ 'factor': factor.replace('_', ' ').title(),
+ 'score': score,
+ 'status': 'Strong' if score >= 70 else 'Adequate' if score >= 40 else 'Weak'
+ })
+
+ return details
+
+ def _get_level(self, score: float) -> str:
+ """Convert score to level"""
+ if score >= 80:
+ return 'Excellent'
+ elif score >= 70:
+ return 'Strong'
+ elif score >= 50:
+ return 'Adequate'
+ elif score >= 30:
+ return 'Weak'
+ else:
+ return 'Critical'
+
+ def _apply_frameworks(self, company_data: Dict) -> Dict:
+ """Apply strategic frameworks"""
+ frameworks = {}
+
+ # SWOT Analysis
+ swot_data = company_data.get('swot', {})
+ frameworks['swot'] = {
+ 'strengths': swot_data.get('strengths', [
+ 'Strong brand recognition',
+ 'Experienced leadership team',
+ 'Robust technology platform'
+ ]),
+ 'weaknesses': swot_data.get('weaknesses', [
+ 'Limited geographic presence',
+ 'High customer acquisition cost',
+ 'Technical debt'
+ ]),
+ 'opportunities': swot_data.get('opportunities', [
+ 'Growing market demand',
+ 'M&A opportunities',
+ 'New product categories'
+ ]),
+ 'threats': swot_data.get('threats', [
+ 'Increasing competition',
+ 'Regulatory changes',
+ 'Economic uncertainty'
+ ])
+ }
+
+ # Porter's Five Forces
+ forces = company_data.get('competitive_forces', {})
+ frameworks['porter_analysis'] = {
+ 'competitive_rivalry': forces.get('rivalry', 70),
+ 'supplier_power': forces.get('suppliers', 40),
+ 'buyer_power': forces.get('buyers', 60),
+ 'threat_of_substitutes': forces.get('substitutes', 50),
+ 'threat_of_new_entrants': forces.get('new_entrants', 45),
+ 'overall_attractiveness': self._calculate_industry_attractiveness(forces)
+ }
+
+ # BCG Matrix for product portfolio
+ products = company_data.get('products', [])
+ frameworks['portfolio_analysis'] = self._analyze_portfolio(products)
+
+ return frameworks
+
+ def _calculate_industry_attractiveness(self, forces: Dict) -> float:
+ """Calculate industry attractiveness from Porter's forces"""
+ # Lower forces = more attractive industry
+ rivalry = 100 - forces.get('rivalry', 50)
+ supplier = 100 - forces.get('suppliers', 50)
+ buyer = 100 - forces.get('buyers', 50)
+ substitutes = 100 - forces.get('substitutes', 50)
+ new_entrants = 100 - forces.get('new_entrants', 50)
+
+ avg = (rivalry + supplier + buyer + substitutes + new_entrants) / 5
+ return round(avg, 1)
+
+ def _analyze_portfolio(self, products: List) -> Dict:
+ """Analyze product portfolio using BCG matrix"""
+ portfolio = {
+ 'stars': [],
+ 'cash_cows': [],
+ 'question_marks': [],
+ 'dogs': []
+ }
+
+ for product in products:
+ growth = product.get('market_growth', 0)
+ share = product.get('market_share', 0)
+
+ if growth > 10 and share > 50:
+ portfolio['stars'].append(product.get('name', 'Product'))
+ elif growth <= 10 and share > 50:
+ portfolio['cash_cows'].append(product.get('name', 'Product'))
+ elif growth > 10 and share <= 50:
+ portfolio['question_marks'].append(product.get('name', 'Product'))
+ else:
+ portfolio['dogs'].append(product.get('name', 'Product'))
+
+ return portfolio
+
+ def _generate_strategic_options(self, pillar_analysis: Dict, context: Dict) -> List[Dict]:
+ """Generate strategic options based on analysis"""
+ options = []
+
+ # Check market position
+ market_score = pillar_analysis['market_position']['score']
+ if market_score < 60:
+ options.append({
+ 'name': 'Market Leadership Initiative',
+ 'type': 'market_penetration',
+ 'description': 'Aggressive market share capture through competitive pricing and marketing',
+ 'investment': 'High',
+ 'timeframe': '12-18 months',
+ 'expected_impact': 'Increase market share by 10-15%',
+ 'priority': 9
+ })
+
+ # Check financial health
+ financial_score = pillar_analysis['financial_health']['score']
+ if financial_score < 50:
+ options.append({
+ 'name': 'Profitability Turnaround',
+ 'type': 'operational_excellence',
+ 'description': 'Cost reduction and revenue optimization program',
+ 'investment': 'Medium',
+ 'timeframe': '6-9 months',
+ 'expected_impact': 'Improve margins by 5-8%',
+ 'priority': 10
+ })
+
+ # Check growth potential
+ growth_score = pillar_analysis['growth_potential']['score']
+ if growth_score > 70:
+ options.append({
+ 'name': 'Expansion Strategy',
+ 'type': 'market_development',
+ 'description': 'Enter new geographic markets or customer segments',
+ 'investment': 'High',
+ 'timeframe': '18-24 months',
+ 'expected_impact': 'Revenue growth of 30-40%',
+ 'priority': 8
+ })
+
+ # Innovation opportunities
+ if context.get('industry_disruption', False):
+ options.append({
+ 'name': 'Digital Transformation',
+ 'type': 'innovation',
+ 'description': 'Comprehensive digitalization of business processes and customer experience',
+ 'investment': 'Very High',
+ 'timeframe': '24-36 months',
+ 'expected_impact': 'Future-proof business model',
+ 'priority': 9
+ })
+
+ # M&A opportunities
+ if context.get('cash_available', 0) > 100000000:
+ options.append({
+ 'name': 'Strategic Acquisition',
+ 'type': 'acquisition',
+ 'description': 'Acquire complementary businesses or competitors',
+ 'investment': 'Very High',
+ 'timeframe': '6-12 months',
+ 'expected_impact': 'Instant scale and capability',
+ 'priority': 7
+ })
+
+ # Sort by priority
+ options.sort(key=lambda x: x['priority'], reverse=True)
+
+ return options[:5] # Top 5 strategic options
+
+ def _assess_strategic_risks(self, company_data: Dict, strategic_options: List) -> Dict:
+ """Assess strategic risks"""
+ risks = {
+ 'execution_risk': self._calculate_execution_risk(company_data),
+ 'market_risk': self._calculate_market_risk(company_data),
+ 'financial_risk': self._calculate_financial_risk(company_data),
+ 'competitive_risk': self._calculate_competitive_risk(company_data),
+ 'regulatory_risk': company_data.get('regulatory_risk', 30),
+ 'overall_risk': 0,
+ 'mitigation_strategies': []
+ }
+
+ # Calculate overall risk
+ risk_values = [
+ risks['execution_risk'],
+ risks['market_risk'],
+ risks['financial_risk'],
+ risks['competitive_risk'],
+ risks['regulatory_risk']
+ ]
+ risks['overall_risk'] = sum(risk_values) / len(risk_values)
+
+ # Generate mitigation strategies
+ if risks['execution_risk'] > 60:
+ risks['mitigation_strategies'].append({
+ 'risk': 'Execution',
+ 'strategy': 'Strengthen PMO, hire experienced executives, implement OKRs'
+ })
+
+ if risks['market_risk'] > 60:
+ risks['mitigation_strategies'].append({
+ 'risk': 'Market',
+ 'strategy': 'Diversify revenue streams, build strategic partnerships'
+ })
+
+ if risks['financial_risk'] > 60:
+ risks['mitigation_strategies'].append({
+ 'risk': 'Financial',
+ 'strategy': 'Improve cash management, secure credit facilities, optimize working capital'
+ })
+
+ return risks
+
+ def _calculate_execution_risk(self, data: Dict) -> float:
+ """Calculate execution risk"""
+ org_capability = data.get('organizational_capability', {})
+
+ factors = [
+ 100 - org_capability.get('leadership', 50),
+ 100 - org_capability.get('talent', 50),
+ 100 - org_capability.get('agility', 50),
+ data.get('complexity_score', 50)
+ ]
+
+ return sum(factors) / len(factors)
+
+ def _calculate_market_risk(self, data: Dict) -> float:
+ """Calculate market risk"""
+ market = data.get('market_position', {})
+
+ factors = [
+ 100 - market.get('market_share', 50),
+ data.get('market_volatility', 50),
+ data.get('customer_concentration', 50)
+ ]
+
+ return sum(factors) / len(factors)
+
+ def _calculate_financial_risk(self, data: Dict) -> float:
+ """Calculate financial risk"""
+ financial = data.get('financial_health', {})
+
+ factors = [
+ 100 - financial.get('cash_flow', 50),
+ 100 - financial.get('profitability', 50),
+ data.get('debt_ratio', 50),
+ data.get('burn_rate', 50) if 'burn_rate' in data else 30
+ ]
+
+ return sum(factors) / len(factors)
+
+ def _calculate_competitive_risk(self, data: Dict) -> float:
+ """Calculate competitive risk"""
+ forces = data.get('competitive_forces', {})
+
+ return (forces.get('rivalry', 50) + forces.get('new_entrants', 50)) / 2
+
+ def _create_strategic_roadmap(self, options: List, timeline_months: int) -> Dict:
+ """Create implementation roadmap"""
+ roadmap = {
+ 'phases': [],
+ 'milestones': [],
+ 'resource_requirements': {},
+ 'success_metrics': []
+ }
+
+ # Define phases
+ phases = [
+ {
+ 'phase': 'Foundation',
+ 'months': '0-3',
+ 'focus': 'Build capabilities and quick wins',
+ 'initiatives': []
+ },
+ {
+ 'phase': 'Acceleration',
+ 'months': '3-9',
+ 'focus': 'Execute core strategies',
+ 'initiatives': []
+ },
+ {
+ 'phase': 'Scale',
+ 'months': '9-18',
+ 'focus': 'Expand and optimize',
+ 'initiatives': []
+ },
+ {
+ 'phase': 'Transform',
+ 'months': '18+',
+ 'focus': 'Long-term transformation',
+ 'initiatives': []
+ }
+ ]
+
+ # Assign initiatives to phases
+ for i, option in enumerate(options[:4]):
+ if i == 0:
+ phases[0]['initiatives'].append(option['name'])
+ elif i == 1:
+ phases[1]['initiatives'].append(option['name'])
+ elif i == 2:
+ phases[2]['initiatives'].append(option['name'])
+ else:
+ phases[3]['initiatives'].append(option['name'])
+
+ roadmap['phases'] = phases
+
+ # Define key milestones
+ roadmap['milestones'] = [
+ {'month': 3, 'milestone': 'Complete foundation phase', 'success_criteria': 'Core team hired, processes defined'},
+ {'month': 6, 'milestone': 'First major initiative launch', 'success_criteria': 'KPIs showing positive trend'},
+ {'month': 12, 'milestone': 'Strategic review', 'success_criteria': 'ROI demonstrated, strategy validated'},
+ {'month': 18, 'milestone': 'Scale achievement', 'success_criteria': 'Market position improved, financial targets met'}
+ ]
+
+ # Resource requirements
+ roadmap['resource_requirements'] = {
+ 'leadership': 'C-suite alignment and commitment',
+ 'financial': '$X million investment over 18 months',
+ 'human': 'Additional 20-30 FTEs across functions',
+ 'technology': 'Platform upgrades and new tools',
+ 'external': 'Consultants and advisors as needed'
+ }
+
+ # Success metrics
+ roadmap['success_metrics'] = [
+ 'Revenue growth: 25% YoY',
+ 'Market share: +5 percentage points',
+ 'EBITDA margin: +8 percentage points',
+ 'Customer NPS: >70',
+ 'Employee engagement: >80%'
+ ]
+
+ return roadmap
+
+ def _generate_recommendations(self, results: Dict) -> List[str]:
+ """Generate strategic recommendations"""
+ recommendations = []
+
+ # Based on overall score
+ score = results['strategic_health_score']
+ if score < 40:
+ recommendations.append('🚨 URGENT: Immediate turnaround required - consider bringing in crisis management team')
+ recommendations.append('Focus on cash preservation and core business stabilization')
+ elif score < 60:
+ recommendations.append('⚠️ Strategic repositioning needed - prioritize 2-3 key initiatives')
+ recommendations.append('Strengthen weak pillars before pursuing growth')
+ elif score < 80:
+ recommendations.append('✓ Solid position - focus on selective improvements and growth')
+ recommendations.append('Invest in innovation and market expansion')
+ else:
+ recommendations.append('⭐ Excellent position - maintain momentum and explore bold moves')
+ recommendations.append('Consider industry disruption or category creation')
+
+ # Based on specific weaknesses
+ for pillar, analysis in results['pillar_analysis'].items():
+ if analysis['score'] < 50:
+ if pillar == 'market_position':
+ recommendations.append(f'Strengthen {pillar}: Launch competitive differentiation program')
+ elif pillar == 'financial_health':
+ recommendations.append(f'Improve {pillar}: Implement profitability improvement plan')
+ elif pillar == 'organizational_capability':
+ recommendations.append(f'Build {pillar}: Invest in talent and culture transformation')
+
+ # Based on opportunities
+ if results['framework_analysis']['porter_analysis']['overall_attractiveness'] > 70:
+ recommendations.append('Industry is attractive - consider aggressive expansion')
+
+ # Risk-based recommendations
+ if results['risk_assessment']['overall_risk'] > 60:
+ recommendations.append('High risk profile - implement comprehensive risk management')
+
+ return recommendations
+
+def analyze_strategy(company_data: Dict) -> str:
+ """Main function to analyze strategy"""
+ analyzer = StrategyAnalyzer()
+ results = analyzer.analyze_strategic_position(company_data)
+
+ # Format output
+ output = [
+ f"=== Strategic Analysis Report ===",
+ f"Company: {results['company']}",
+ f"Date: {results['timestamp'][:10]}",
+ f"",
+ f"STRATEGIC HEALTH SCORE: {results['strategic_health_score']}/100",
+ f"",
+ "Strategic Pillars:"
+ ]
+
+ for pillar, analysis in results['pillar_analysis'].items():
+ output.append(f" {pillar.replace('_', ' ').title()}: {analysis['score']:.1f} ({analysis['level']})")
+ for factor in analysis['factors'][:2]: # Show top 2 factors
+ output.append(f" • {factor['factor']}: {factor['status']}")
+
+ output.extend([
+ f"",
+ "Strategic Options:"
+ ])
+
+ for i, option in enumerate(results['strategic_options'][:3], 1):
+ output.append(f"\n{i}. {option['name']} (Priority: {option['priority']}/10)")
+ output.append(f" Type: {option['type']}")
+ output.append(f" Investment: {option['investment']}")
+ output.append(f" Timeframe: {option['timeframe']}")
+ output.append(f" Impact: {option['expected_impact']}")
+
+ output.extend([
+ f"",
+ f"Risk Assessment:",
+ f" Overall Risk: {results['risk_assessment']['overall_risk']:.1f}%",
+ f" Execution Risk: {results['risk_assessment']['execution_risk']:.1f}%",
+ f" Market Risk: {results['risk_assessment']['market_risk']:.1f}%",
+ f" Financial Risk: {results['risk_assessment']['financial_risk']:.1f}%",
+ f"",
+ "Strategic Roadmap:"
+ ])
+
+ for phase in results['roadmap']['phases'][:3]:
+ output.append(f" {phase['phase']} ({phase['months']}): {phase['focus']}")
+ for initiative in phase['initiatives']:
+ output.append(f" • {initiative}")
+
+ output.extend([
+ f"",
+ "Key Recommendations:"
+ ])
+
+ for rec in results['recommendations'][:5]:
+ output.append(f" • {rec}")
+
+ return '\n'.join(output)
+
+if __name__ == "__main__":
+ # Example usage
+ example_company = {
+ 'name': 'TechCorp Inc.',
+ 'market_position': {
+ 'market_share': 35,
+ 'brand_strength': 65,
+ 'competitive_advantage': 70,
+ 'customer_loyalty': 60
+ },
+ 'financial_health': {
+ 'revenue_growth': 45,
+ 'profitability': 40,
+ 'cash_flow': 55,
+ 'unit_economics': 60
+ },
+ 'organizational_capability': {
+ 'talent': 70,
+ 'culture': 65,
+ 'leadership': 75,
+ 'agility': 60
+ },
+ 'growth_potential': {
+ 'market_size': 80,
+ 'expansion_opportunities': 70,
+ 'product_pipeline': 60,
+ 'partnerships': 55
+ },
+ 'competitive_forces': {
+ 'rivalry': 70,
+ 'suppliers': 40,
+ 'buyers': 60,
+ 'substitutes': 50,
+ 'new_entrants': 45
+ },
+ 'context': {
+ 'industry_disruption': True,
+ 'cash_available': 150000000
+ },
+ 'timeline': 18
+ }
+
+ print(analyze_strategy(example_company))
diff --git a/skills/c-level-advisor/cfo-advisor/SKILL.md b/skills/c-level-advisor/cfo-advisor/SKILL.md
new file mode 100644
index 00000000..be2397ef
--- /dev/null
+++ b/skills/c-level-advisor/cfo-advisor/SKILL.md
@@ -0,0 +1,140 @@
+---
+name: "cfo-advisor"
+description: "Financial leadership for startups and scaling companies. Financial modeling, unit economics, fundraising strategy, cash management, and board financial packages. Use when building financial models, analyzing unit economics, planning fundraising, managing cash runway, preparing board materials, or when user mentions CFO, burn rate, runway, fundraising, unit economics, LTV, CAC, term sheets, or financial strategy."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: cfo-leadership
+ updated: 2026-03-05
+ python-tools: burn_rate_calculator.py, unit_economics_analyzer.py, fundraising_model.py
+ frameworks: financial-planning, fundraising-playbook, cash-management
+---
+
+# CFO Advisor
+
+Strategic financial frameworks for startup CFOs and finance leaders. Numbers-driven, decisions-focused.
+
+This is **not** a financial analyst skill. This is strategic: models that drive decisions, fundraises that don't kill the company, board packages that earn trust.
+
+## Keywords
+CFO, chief financial officer, burn rate, runway, unit economics, LTV, CAC, fundraising, Series A, Series B, term sheet, cap table, dilution, financial model, cash flow, board financials, FP&A, SaaS metrics, ARR, MRR, net dollar retention, gross margin, scenario planning, cash management, treasury, working capital, burn multiple, rule of 40
+
+## Quick Start
+
+```bash
+# Burn rate & runway scenarios (base/bull/bear)
+python scripts/burn_rate_calculator.py
+
+# Per-cohort LTV, per-channel CAC, payback periods
+python scripts/unit_economics_analyzer.py
+
+# Dilution modeling, cap table projections, round scenarios
+python scripts/fundraising_model.py
+```
+
+## Key Questions (ask these first)
+
+- **What's your burn multiple?** (Net burn ÷ Net new ARR. > 2x is a problem.)
+- **If fundraising takes 6 months instead of 3, do you survive?** (If not, you're already behind.)
+- **Show me unit economics per cohort, not blended.** (Blended hides deterioration.)
+- **What's your NDR?** (> 100% means you grow without signing a single new customer.)
+- **What are your decision triggers?** (At what runway do you start cutting? Define now, not in a crisis.)
+
+## Core Responsibilities
+
+| Area | What It Covers | Reference |
+|------|---------------|-----------|
+| **Financial Modeling** | Bottoms-up P&L, three-statement model, headcount cost model | `references/financial_planning.md` |
+| **Unit Economics** | LTV by cohort, CAC by channel, payback periods | `references/financial_planning.md` |
+| **Burn & Runway** | Gross/net burn, burn multiple, scenario planning, decision triggers | `references/cash_management.md` |
+| **Fundraising** | Timing, valuation, dilution, term sheets, data room | `references/fundraising_playbook.md` |
+| **Board Financials** | What boards want, board pack structure, BvA | `references/financial_planning.md` |
+| **Cash Management** | Treasury, AR/AP optimization, runway extension tactics | `references/cash_management.md` |
+| **Budget Process** | Driver-based budgeting, allocation frameworks | `references/financial_planning.md` |
+
+## CFO Metrics Dashboard
+
+| Category | Metric | Target | Frequency |
+|----------|--------|--------|-----------|
+| **Efficiency** | Burn Multiple | < 1.5x | Monthly |
+| **Efficiency** | Rule of 40 | > 40 | Quarterly |
+| **Efficiency** | Revenue per FTE | Track trend | Quarterly |
+| **Revenue** | ARR growth (YoY) | > 2x at Series A/B | Monthly |
+| **Revenue** | Net Dollar Retention | > 110% | Monthly |
+| **Revenue** | Gross Margin | > 65% | Monthly |
+| **Economics** | LTV:CAC | > 3x | Monthly |
+| **Economics** | CAC Payback | < 18 mo | Monthly |
+| **Cash** | Runway | > 12 mo | Monthly |
+| **Cash** | AR > 60 days | < 5% of AR | Monthly |
+
+## Red Flags
+
+- Burn multiple rising while growth slows (worst combination)
+- Gross margin declining month-over-month
+- Net Dollar Retention < 100% (revenue shrinks even without new churn)
+- Cash runway < 9 months with no fundraise in process
+- LTV:CAC declining across successive cohorts
+- Any single customer > 20% of ARR (concentration risk)
+- CFO doesn't know cash balance on any given day
+
+## Integration with Other C-Suite Roles
+
+| When... | CFO works with... | To... |
+|---------|-------------------|-------|
+| Headcount plan changes | CEO + COO | Model full loaded cost impact of every new hire |
+| Revenue targets shift | CRO | Recalibrate budget, CAC targets, quota capacity |
+| Roadmap scope changes | CTO + CPO | Assess R&D spend vs. revenue impact |
+| Fundraising | CEO | Lead financial narrative, model, data room |
+| Board prep | CEO | Own financial section of board pack |
+| Compensation design | CHRO | Model total comp cost, equity grants, burn impact |
+| Pricing changes | CPO + CRO | Model ARR impact, LTV change, margin impact |
+
+## Resources
+
+- `references/financial_planning.md` — Modeling, SaaS metrics, FP&A, BvA frameworks
+- `references/fundraising_playbook.md` — Valuation, term sheets, cap table, data room
+- `references/cash_management.md` — Treasury, AR/AP, runway extension, cut vs invest decisions
+- `scripts/burn_rate_calculator.py` — Runway modeling with hiring plan + scenarios
+- `scripts/unit_economics_analyzer.py` — Per-cohort LTV, per-channel CAC
+- `scripts/fundraising_model.py` — Dilution, cap table, multi-round projections
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Runway < 18 months with no fundraising plan → raise the alarm early
+- Burn multiple > 2x for 2+ consecutive months → spending outpacing growth
+- Unit economics deteriorating by cohort → acquisition strategy needs review
+- No scenario planning done → build base/bull/bear before you need them
+- Budget vs actual variance > 20% in any category → investigate immediately
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "How much runway do we have?" | Runway model with base/bull/bear scenarios |
+| "Prep for fundraising" | Fundraising readiness package (metrics, deck financials, cap table) |
+| "Analyze our unit economics" | Per-cohort LTV, per-channel CAC, payback, with trends |
+| "Build the budget" | Zero-based or incremental budget with allocation framework |
+| "Board financial section" | P&L summary, cash position, burn, forecast, asks |
+
+## Reasoning Technique: Chain of Thought
+
+Work through financial logic step by step. Show all math. Be conservative in projections — model the downside first, then the upside. Never round in your favor.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/c-level-advisor/cfo-advisor/references/cash_management.md b/skills/c-level-advisor/cfo-advisor/references/cash_management.md
new file mode 100644
index 00000000..be3e69f8
--- /dev/null
+++ b/skills/c-level-advisor/cfo-advisor/references/cash_management.md
@@ -0,0 +1,374 @@
+# Cash Management Reference
+
+Cash is the oxygen of a startup. You can be unprofitable for years. You cannot be out of cash for a day.
+
+---
+
+## 1. Cash Flow Management
+
+### The Cash Equation
+
+```
+Ending Cash = Beginning Cash
+ + Cash collected from customers
+ - Cash paid to employees
+ - Cash paid to vendors
+ - Cash paid for infrastructure
+ - Debt service
+ +/- Financing activities
+
+Note: This is NOT the P&L. Revenue recognition ≠ cash collected.
+```
+
+### Where Cash Hides (and Leaks)
+
+**Cash sources you might be under-using:**
+- Deferred revenue (annual billing locks in cash 12 months early)
+- Customer deposits on enterprise contracts
+- Vendor payment terms (Net 60 instead of Net 30 = free float)
+- AWS/GCP startup credits (often $25K–$100K available, widely unused)
+- Revenue-based financing on predictable MRR
+- Venture debt (non-dilutive, available post-Series A)
+
+**Cash drains that sneak up on you:**
+- Annual software licenses paid in Q1 (budget for the lump sum)
+- Event sponsorships (often 6-12 months in advance)
+- Recruiting fees (15-25% of first-year salary, due on hire)
+- Legal fees (data room prep, fundraise close = $50K–$200K surprise)
+- Late-paying enterprise customers (Net 60 in contract, pays Net 90 in practice)
+
+### Cash Flow vs P&L: The Gap
+
+**Scenario: $1M enterprise deal signed December 31**
+
+```
+P&L impact (accrual):
+ December revenue: $83K (1/12 of annual)
+
+Cash impact:
+ If billed annually upfront: +$1,000K in December (GREAT)
+ If billed quarterly: +$250K in December (good)
+ If billed monthly: +$83K in December (fine)
+ If Net 60 terms: +$0 in December, +$83K in February (cash drag)
+```
+
+**The CFO's job:** Maximize the timing difference between cash in and cash out.
+- Collect from customers as early as possible (annual upfront, early payment discounts)
+- Pay vendors as late as possible (maximize payment terms)
+- Never confuse deferred revenue (a liability) with actual cash (it is cash — just count it right)
+
+---
+
+## 2. Treasury and Banking Strategy
+
+### Account Structure
+
+```
+Operating Account (primary bank):
+ Balance: 3-6 months of operating expenses
+ Purpose: Payroll, vendor payments, day-to-day ops
+ Product: Business checking or high-yield business savings
+ Bank: Chase, SVB successor (First Citizens), Mercury, Brex
+
+Reserve Account (secondary or same bank):
+ Balance: Everything above operating float
+ Purpose: Reserve; move to operating as needed
+ Product: Money market fund or T-Bill ladder
+ Target yield (2024-2025): 4.5%–5.2%
+ Products: Vanguard VMFXX, Fidelity SPAXX, or direct T-Bills via TreasuryDirect
+
+Emergency Account (separate bank):
+ Balance: 1-2 months expenses
+ Purpose: If primary bank has issues (SVB taught this lesson)
+ Product: Business savings
+```
+
+**FDIC coverage:** $250K per depositor per institution. For balances above $250K at a single bank, either:
+- Use CDARS/ICS (bank sweeps into multiple FDIC-insured accounts automatically)
+- Spread across multiple banks
+- Move excess to T-Bills (backed by US government, not FDIC, but safer)
+
+**After SVB (March 2023):** Every CFO should have at least 2 banking relationships. If one bank fails or freezes, you can make payroll.
+
+### Yield on Cash
+
+At $3M cash, the difference between 0% (checking) and 5% (T-Bills) is $150K/year.
+That's a month of runway for a $150K/month burn company. **Get yield on reserves.**
+
+```
+Monthly yield on $3M at 5%: ~$12,500
+Annual: ~$150,000
+This is not optional. Set it up once and automate.
+```
+
+---
+
+## 3. AR/AP Optimization
+
+### Accounts Receivable: Get Paid Faster
+
+**Billing model impact on cash:**
+```
+ Annual Upfront Quarterly Monthly Net 30 Monthly
+Cash Day 1: 100% of ACV 25% of ACV 8.3% 0%
+Cash Month 2: 0% (done) 0% 8.3% 8.3%
+12-month total: 100% 100% 100% 100%
+
+For $100K ACV customer, Year 1 cash:
+ Annual upfront: $100K immediately
+ Monthly Net 30: $8.3K × 11 months = $91.7K (1 month lag)
+ Cash benefit: $100K vs $91.7K = $8.3K benefit + no collection risk
+```
+
+**Push for annual billing. Make it easy with a discount:**
+```
+"Pay annually and get 2 months free (16% discount)"
+Most SMB customers will take this.
+Enterprise: use MSA structure with annual invoicing, not month-to-month.
+```
+
+**AR Aging Policy:**
+```
+> 0-30 days: Current. No action.
+> 30-60 days: Friendly reminder from AR team.
+> 60-90 days: Escalate to Customer Success.
+> 90 days: CFO or CEO-level outreach. Consider collections.
+> 120 days: Reserve for bad debt. Legal/collections.
+
+Reserve policy: 50% of 90-120 day AR, 100% of > 120 days
+```
+
+**What slows down collections:**
+- Wrong contact (billing contact vs. user) — get finance contact during onboarding
+- Enterprise PO required — know this upfront, not when invoice is due
+- Credit holds or budget freeze — your CSM should surface these early
+- Invoice errors — every wrong invoice extends payment by 30-60 days
+
+### Accounts Payable: Pay Slower
+
+**Standard terms by vendor type:**
+```
+SaaS tools: Net 30 default. Push for Net 45 or Net 60 at scale.
+Cloud providers: Pay as you go. Apply for credits first.
+Professional services (agencies, lawyers): Net 30 minimum. Get Net 45 where possible.
+Rent/office: Whatever the lease says. Negotiate quarterly payments if you can.
+Payroll: Pay on time. Never delay payroll. Ever.
+```
+
+**Early payment discount trap:**
+```
+"2/10 Net 30" means: 2% discount if you pay in 10 days, else pay in 30.
+Annual cost of NOT taking this: 2% × (365/(30-10)) = ~36% APY
+ALWAYS take early payment discounts > 2%.
+Never take discounts < 1%.
+```
+
+**AP workflow:**
+1. All invoices → finance inbox (not individual employees)
+2. Approval required above threshold ($500 for startups)
+3. Pay at end of terms, not when invoice arrives
+4. Batch payments weekly (not daily) to reduce processing overhead
+
+---
+
+## 4. Runway Extension Tactics
+
+Use these when you need to extend runway without raising. Ranked by speed and impact.
+
+### Tier 1: Fast Cash (Days)
+
+**Annual billing campaign:**
+```
+Target: Existing monthly customers
+Offer: 2 months free (16% discount) or 1 month free (8% discount) for annual upfront
+Process: CSM-led email campaign to all monthly customers
+Impact: $X MRR × 12 × conversion rate = immediate cash injection
+Timeline: 2-4 weeks
+No dilution. No debt. High impact.
+```
+
+**Prepayment incentive for pipeline:**
+```
+For deals in late stage, offer annual upfront pricing with 10-15% discount.
+Close rate may increase. Cash timing dramatically improves.
+```
+
+### Tier 2: Cost Control (2-4 Weeks)
+
+**Hiring freeze:**
+```
+Every unfilled role = salary × 1.25 per month.
+For a 30-person company, 3 open roles at $150K average:
+ Monthly savings: 3 × $150K × 1.25 / 12 = $47K/month
+ Over 6 months: $280K
+Impact: Immediate. No blood.
+```
+
+**Software audit:**
+```
+Pull all credit card charges and ACH debits.
+Cancel any subscription not used in 30 days.
+Typical savings: $3K-$15K/month at Series A stage.
+Tools: Vendr, Spendesk, or just a spreadsheet of recurring charges.
+```
+
+**Cloud cost optimization:**
+```
+Right-size instances (dev/staging don't need prod-scale)
+Reserve instances (1-year reserved = 30-40% savings vs on-demand)
+Delete unused resources (load balancers, IPs, old snapshots)
+Typical savings: 20-35% of current cloud bill
+```
+
+### Tier 3: Vendor Renegotiation (2-6 Weeks)
+
+**Payment term extension:**
+```
+Ask key vendors for Net 60 instead of Net 30.
+$500K in AP × 30 days = $500K × (30/365) = ~$41K cash float improvement
+Won't always work, but vendors often say yes to good customers.
+```
+
+**Renewal timing:**
+```
+Push annual renewals to later in the year.
+Preserve cash for Q1 (typically heaviest sales hiring quarter).
+```
+
+**Vendor credits:**
+```
+AWS: AWS Activate (up to $100K for qualified startups)
+GCP: Google for Startups (up to $200K)
+Azure: Microsoft for Startups (up to $150K)
+Stripe: Revenue share programs
+Hubspot: Startup pricing (90% off)
+```
+
+### Tier 4: Financing (Weeks to Months)
+
+**Revenue-based financing:**
+```
+Providers: Clearco, Capchase, Pipe, Arc
+Structure: Advance 3-6 months of MRR. Repay with % of monthly revenue.
+Cost: Typically 6-12% annualized.
+Speed: 1-2 weeks to close.
+When to use: Bridge to next ARR milestone before raising equity.
+When NOT to use: When burn rate is structural (will consume the advance fast).
+```
+
+**Venture debt:**
+```
+Providers: SVB (now First Citizens), Western Technology Investment, Hercules, TriplePoint
+Structure: Term loan, typically 3-6x monthly gross burn
+Interest: Prime + 2-4% + warrants
+When available: Post-Series A, when revenue is predictable
+Typical timing: Add alongside an equity round (don't raise debt when you need equity)
+Impact: Extends runway 3-6 months without dilution
+When NOT to use: If you might trip financial covenants (minimum cash, revenue)
+```
+
+**Convertible bridge:**
+```
+Existing investors write bridge note: $500K-$2M at favorable terms.
+Structure: Converts at discount (10-20%) or cap into next equity round.
+When to use: You're 60-90 days from closing an equity round and need cash to get there.
+When NOT to use: As a long-term strategy. Bridge-to-bridge is a death spiral.
+```
+
+### Tier 5: Structural Cost Reduction (Weeks + Impact on Morale)
+
+**Salary deferrals (founders first):**
+```
+Founders take 20-30% salary reduction, accrued for future repayment.
+Signals commitment to team and investors.
+Only ask employees to follow if founders go first.
+Always pay market rate to key non-founder employees — you can't afford to lose them.
+```
+
+**Reduction in force (RIF):**
+```
+Threshold: If burn multiple > 3x and growth < 20% YoY, a RIF is likely necessary.
+Sizing: Model to achieve at least 12 months runway without fundraising.
+Rule: Don't do a RIF twice. Size it right the first time.
+ Two small RIFs destroy morale worse than one decisive one.
+Process: Legal counsel required. WARN Act (60-day notice) if > 100 employees.
+Focus cuts: G&A and underperforming sales roles first. Protect engineering and key revenue.
+```
+
+---
+
+## 5. When to Cut vs When to Invest
+
+### The Framework
+
+**Cut when:**
+- Burn multiple > 2x and growth is decelerating
+- Runway < 9 months with no fundraise imminent
+- LTV:CAC declining for 3+ consecutive months
+- Any spend category with no measurable return in 90 days
+- Headcount in functions not directly tied to near-term revenue or product-market fit
+
+**Invest when:**
+- Magic number > 1 (every dollar in S&M returns > $1 in gross profit)
+- LTV:CAC > 3x in a specific channel (pour money in)
+- Gross margin > 70% (unit economics are healthy; growth is the constraint)
+- Cohort data improving (retention getting better → LTV going up → invest in growth)
+- CAC payback < 12 months (you get your money back fast enough to keep reinvesting)
+
+### The False Economy Trap
+
+**Don't cut:**
+- Top-of-funnel demand gen that generates qualified pipeline (if CAC payback is < 12 months, this is your best investment)
+- Engineering capacity on core product (technical debt compounds and slows you down permanently)
+- Key account managers on your largest customers (churn from top customers is catastrophic)
+
+**Cut these first:**
+- Conference sponsorships with no measurable pipeline
+- Tools and subscriptions with < 5 users or < 30% utilization
+- Agency spend that could be done in-house
+- Roadmap items that aren't tied to retention or expansion revenue
+- Any G&A spend that isn't legally required
+
+### Decision Triggers (Pre-Define These)
+
+Don't make these decisions in a crisis. Define the triggers now:
+
+```
+At 12 months runway: Review all discretionary spend. Start fundraise process.
+At 9 months runway: Implement hiring freeze. Fundraise is mandatory.
+At 6 months runway: Cut non-essential spend 20%. If no fundraise term sheet, run RIF model.
+At 4 months runway: Execute RIF. Explore all financing options. Notify board.
+At 3 months runway: Emergency plan only. All options on table (bridge, strategic, wind down).
+```
+
+---
+
+## Key Formulas
+
+```python
+# Net burn
+net_burn = gross_burn - revenue_collected
+
+# Runway (months)
+runway_months = cash_balance / net_burn
+
+# Cash conversion cycle
+ccc = days_sales_outstanding + days_inventory_held - days_payable_outstanding
+# Lower CCC = better cash efficiency
+
+# Days Sales Outstanding (DSO)
+dso = (accounts_receivable / revenue) * 30 # monthly revenue
+
+# Days Payable Outstanding (DPO)
+dpo = (accounts_payable / cogs) * 30 # target: maximize this
+
+# Working capital
+working_capital = current_assets - current_liabilities
+
+# Quick ratio (liquidity)
+quick_ratio_liquidity = (cash + ar) / current_liabilities
+# Target: > 1.5 (you can pay short-term obligations without selling assets)
+
+# Free cash flow
+fcf = operating_cash_flow - capex
+```
diff --git a/skills/c-level-advisor/cfo-advisor/references/financial_planning.md b/skills/c-level-advisor/cfo-advisor/references/financial_planning.md
new file mode 100644
index 00000000..af04db48
--- /dev/null
+++ b/skills/c-level-advisor/cfo-advisor/references/financial_planning.md
@@ -0,0 +1,500 @@
+# Financial Planning Reference
+
+Startup financial modeling frameworks. Build models that drive decisions, not models that impress investors.
+
+---
+
+## 1. Startup Financial Modeling
+
+### Bottoms-Up vs Top-Down
+
+**Top-down model (don't use for operating):**
+```
+TAM = $10B
+SOM = 1% = $100M
+Revenue = $100M in year 5
+```
+This is marketing. You cannot manage a company against these numbers.
+
+**Bottoms-up model (use this):**
+```
+Year 1 Revenue Build:
+ Sales headcount: 3 AEs by Q1, +2 in Q2, +3 in Q4
+ Ramp curve: Month 1-3 = 25%, Month 4-6 = 75%, Month 7+ = 100%
+ Quota per ramped AE: $600K ARR
+ Effective quota (weighted for ramp): $1.2M ARR in Year 1
+ Win rate: 25%
+ Average deal: $48K ACV
+ Pipeline needed: $1.2M / 25% = $4.8M ARR pipeline
+ Required meetings to create that pipeline: $4.8M / (conversion 20%) / ($48K ACV × 0.5 to meeting) = ~200 meetings
+```
+
+Now you have something actionable. You know how many SDR calls, how many marketing leads, what conversion rate you need to hold. Every assumption is visible and challengeable.
+
+### Building the Operating Model
+
+#### Revenue Engine
+
+**New ARR Model (SaaS):**
+```
+Month N New ARR:
+ = Quota-carrying reps (fully ramped equivalent)
+ × Attainment rate (typically 70-80% of quota)
+ × Average deal size
+ + PLG / self-serve (if applicable)
+
+Quota-carrying reps (ramped equivalent):
+ = Sum(each rep × their ramp factor)
+
+Ramp schedule:
+ Month 1-2: 0% (onboarding)
+ Month 3: 25%
+ Month 4-6: 50%
+ Month 7-9: 75%
+ Month 10+: 100%
+```
+
+**ARR Bridge (most important recurring visual):**
+```
+Beginning ARR
+ + New ARR (new logos)
+ + Expansion ARR (upsells, seat growth)
+ - Churned ARR (cancellations)
+ - Contraction ARR (downgrades)
+= Ending ARR
+
+Net ARR Added = New + Expansion - Churn - Contraction
+
+Net Dollar Retention (NDR):
+ = (Beginning ARR + Expansion - Churn - Contraction) / Beginning ARR × 100
+ Target: > 110% for growth-stage SaaS
+ World-class: > 130% (Snowflake, Twilio-tier)
+```
+
+**MRR and ARR Relationship:**
+```
+ARR = MRR × 12 (simple, always use this)
+Never mix monthly and annual contracts in MRR without normalization.
+Annual contract booked = ACV / 12 = monthly contribution to ARR
+Multi-year contracts: book each year at annual value (not multi-year total)
+```
+
+#### Headcount Model
+
+Headcount is usually 60-80% of total costs. Model it carefully.
+
+```
+For each role:
+ - Start date
+ - Department
+ - Annual salary (from salary bands)
+ - Loaded cost (salary × 1.25-1.45 depending on benefits + recruiting method)
+ - Productive from (ramp period)
+ - Impact on revenue (for revenue-generating roles)
+
+Total headcount cost = Σ (each FTE × loaded cost × months active / 12)
+```
+
+**Department headcount ratios (Series A benchmarks):**
+```
+Sales (S&M): 20-30% of headcount
+Engineering/Product (R&D): 40-50% of headcount
+Customer Success: 15-20% of headcount
+G&A: 10-15% of headcount
+```
+
+#### COGS Model
+
+Gross margin is the most important long-term indicator of business quality.
+
+**COGS for SaaS:**
+```
+1. Hosting / Infrastructure (AWS, GCP, Azure)
+ - Scale with customer count or usage
+ - Should be 5-15% of ARR for mature SaaS
+ - If > 20%: infrastructure optimization needed
+
+2. Customer Success headcount
+ - Ratio: 1 CSM per $1M-$3M ARR (varies by segment)
+ - SMB: 1 CSM per $500K ARR (high-touch required)
+ - Enterprise: 1 CSM per $2-5M ARR (strategic accounts)
+
+3. Third-party licensing / APIs
+ - Per-customer or usage-based pass-through costs
+ - Critical to model at scale (margin killer if not tracked)
+
+4. Payment processing
+ - 2.2-2.9% of revenue for Stripe/Braintree
+ - Can negotiate to 1.8-2.2% at scale (> $5M ARR)
+```
+
+**Gross Margin targets:**
+```
+SaaS: > 65% acceptable, > 75% good, > 80% exceptional
+Marketplace: 50-70%
+Hardware + software: 40-60%
+Services + software: 30-50%
+```
+
+**If gross margin < 65%:**
+- Infrastructure cost optimization (rightsizing, reserved instances)
+- CS headcount review (automation, pooled CSMs)
+- Pricing model review (usage-based pricing if cost is usage-driven)
+- Third-party cost renegotiation
+
+#### Opex Model
+
+```
+Sales & Marketing:
+ - AE/SDR/SE salaries + OTE (on-target earnings)
+ - Marketing programs (demand gen budget)
+ - Tools and technology (CRM, SEO, ads platforms)
+ - Events and travel
+ - Benchmark: 40-60% of revenue at growth stage, targeting < 30% at scale
+
+Research & Development:
+ - Engineering salaries
+ - Product management
+ - Design
+ - Technical infrastructure for development
+ - Benchmark: 20-35% of revenue
+
+General & Administrative:
+ - Finance, legal, HR, admin
+ - Office costs
+ - SaaS tools / software licenses
+ - D&O insurance
+ - Benchmark: 8-15% (target < 10% at scale)
+```
+
+### Financial Model Do's and Don'ts
+
+| Do | Don't |
+|----|-------|
+| Build assumptions tab with all inputs | Hardcode numbers in formulas |
+| Model monthly (not quarterly) at early stage | Use annual model for first 3 years |
+| Start with headcount plan, build costs from it | Guess at expense line items |
+| Show model to actual customers or users | Show model to investors before internal stress-test |
+| Version your model | Overwrite old versions |
+| Reconcile cash flow to P&L monthly | Trust P&L without cash flow model |
+| Include a sensitivity table | Present single-scenario forecast |
+
+---
+
+## 2. Three-Statement Model for Startups
+
+### Why All Three Matter
+
+The P&L tells you if you're profitable. The cash flow statement tells you if you're alive. The balance sheet tells you if you're solvent.
+
+Startups that only track P&L miss the gap between revenue recognition and cash collection.
+
+### P&L Structure
+
+```
+ Q1 Q2 Q3 Q4 FY
+Revenue
+ Subscription ARR $400K $520K $680K $840K $2,440K
+ Professional Svcs $40K $50K $60K $65K $215K
+Total Revenue $440K $570K $740K $905K $2,655K
+
+COGS
+ Infrastructure $35K $42K $52K $62K $191K
+ CS Headcount $75K $75K $100K $100K $350K
+ 3rd Party Licensing $15K $18K $22K $28K $83K
+Total COGS $125K $135K $174K $190K $624K
+
+Gross Profit $315K $435K $566K $715K $2,031K
+Gross Margin 71.6% 76.3% 76.5% 79.0% 76.5%
+
+Operating Expenses
+ Sales & Marketing $380K $420K $480K $520K $1,800K
+ Research & Dev $320K $340K $380K $400K $1,440K
+ General & Admin $120K $130K $140K $150K $540K
+Total Opex $820K $890K $1000K $1070K $3,780K
+
+EBITDA ($505K) ($455K) ($434K) ($355K) ($1,749K)
+EBITDA Margin (114.8%)(79.8%) (58.6%) (39.2%) (65.9%)
+```
+
+### Cash Flow Statement
+
+```
+ Q1 Q2 Q3 Q4
+Operating Activities
+ Net Income ($510K) ($460K) ($440K) ($360K)
+ Add: D&A $8K $8K $8K $10K
+ Working Capital Changes:
+ AR increase ($45K) ($50K) ($60K) ($55K)
+ AP increase $20K $15K $20K $15K
+ Deferred Rev change $80K $60K $80K $90K
+Operating Cash Flow ($447K) ($427K) ($392K) ($300K)
+
+Investing Activities
+ Capex ($15K) ($8K) ($10K) ($12K)
+Free Cash Flow ($462K) ($435K) ($402K) ($312K)
+
+Financing Activities
+ None $0 $0 $0 $0
+
+Net Change in Cash ($462K) ($435K) ($402K) ($312K)
+
+Beginning Cash $3,500K $3,038K $2,603K $2,201K
+Ending Cash $3,038K $2,603K $2,201K $1,889K
+Runway (months) 13.1 12.1 10.9 10.1
+```
+
+**Key insight from this model:**
+The deferred revenue offset (customers paying annually upfront) is reducing cash burn by ~$80-90K/quarter versus a pure monthly billing model. This is the CFO's lever — push for annual billing.
+
+### Balance Sheet: The Startup Version
+
+At early stage, track these specifically:
+
+```
+Assets:
+ Cash: Your lifeline. Monitor daily.
+ Accounts Receivable: What customers owe you. Age it monthly.
+ Prepaid Expenses: Software licenses, insurance paid upfront.
+
+Liabilities:
+ Accounts Payable: What you owe vendors. Maximize terms.
+ Accrued Liabilities: Salaries owed, commissions earned but not paid.
+ Deferred Revenue: Customer prepayments. Liability until service delivered, but cash is yours.
+ Debt/Convertible Notes: Face value + interest accrual.
+
+Equity:
+ Common Stock: Founder shares
+ Preferred Stock: Investor shares
+ APIC: Additional paid-in capital
+ Accumulated Deficit: Your running losses (expected for startups)
+```
+
+---
+
+## 3. SaaS Metrics That Matter
+
+### The Hierarchy of SaaS Metrics
+
+```
+Tier 1 (existential): ARR, Runway, Net Dollar Retention
+Tier 2 (strategic): Gross Margin, Burn Multiple, LTV:CAC
+Tier 3 (operational): CAC Payback, Churn Rate, ACV
+Tier 4 (diagnostic): Logo Churn vs Revenue Churn, Expansion Rate, NPS
+```
+
+Never report Tier 4 metrics to your board if Tier 1 metrics are off-track.
+
+### Core Metric Definitions
+
+**ARR (Annual Recurring Revenue):**
+```
+ARR = Sum of all active annual contract values (normalized to annual)
+What it is NOT: bookings, billings, or TCV
+When to use MRR: Companies with mostly monthly contracts
+When to use ARR: Companies with majority annual contracts
+```
+
+**Net Dollar Retention (NDR / NRR):**
+```
+NDR = (Beginning MRR + Expansion MRR - Churned MRR - Contraction MRR)
+ / Beginning MRR × 100
+
+The benchmark everyone quotes: 100% means existing customers are flat.
+> 100% means existing customers grow revenue on their own.
+World-class (Snowflake, Datadog): 130%+
+
+Why it matters: NDR > 100% means revenue growth even if you sign zero new customers.
+At NDR = 120% and $5M ARR: you will reach $7M ARR in 24 months without a single new sale.
+```
+
+**Gross Revenue Retention (GRR):**
+```
+GRR = (Beginning MRR - Churned MRR - Contraction MRR) / Beginning MRR × 100
+
+GRR measures the floor of your retention (ignoring expansion).
+GRR is always ≤ NDR.
+Target: > 85% for SMB SaaS, > 90% for mid-market, > 95% for enterprise.
+```
+
+**Logo Churn vs Revenue Churn:**
+```
+Logo churn: % of customers who cancel (ignores size)
+Revenue churn: % of ARR that cancels (accounts for size)
+
+Why the distinction matters:
+ You could have 10% logo churn but 3% revenue churn (churning small customers)
+ Or 5% logo churn but 12% revenue churn (churning large customers) — much worse
+
+Report both. If they diverge significantly, investigate immediately.
+```
+
+**ACV (Annual Contract Value):**
+```
+ACV = Total contract value / contract term in years
+Not to be confused with ARR (which only counts recurring, not one-time fees)
+
+Rising ACV: You're moving upmarket (good for efficiency, check if ICP is changing)
+Falling ACV: You're moving downmarket (check burn multiple — may not be economic)
+```
+
+**Rule of 40:**
+```
+Rule of 40 = Revenue Growth Rate % + EBITDA Margin %
+Target: > 40%
+
+Example: 60% growth + (-15%) EBITDA margin = 45. Passing.
+Example: 20% growth + 5% EBITDA margin = 25. Failing at growth stage.
+
+At early stage (< $5M ARR): Rule of 40 doesn't apply. Growth is the only metric.
+At growth stage ($5-20M ARR): Starting to matter.
+At scale ($20M+ ARR): Board and investors will hold you to this.
+```
+
+---
+
+## 4. FP&A for Startups: What to Measure When
+
+### Metrics by Stage
+
+**Pre-seed / Seed (< $1M ARR):**
+```
+Focus on: Cash, pipeline, customer conversations
+Measure: Monthly cash burn, weeks of runway, NPS / customer satisfaction
+Don't obsess over: EBITDA margin, gross margin (too early)
+Frequency: Weekly cash check, monthly everything else
+```
+
+**Series A ($1-5M ARR):**
+```
+Focus on: Repeatable sales, unit economics
+Measure: MRR growth, LTV:CAC, CAC payback by channel, gross margin
+Don't obsess over: Profitability, G&A efficiency
+Build now: Monthly financial close (< 5 business days), basic FP&A model
+Frequency: Monthly board pack, weekly leadership metrics
+```
+
+**Series B ($5-20M ARR):**
+```
+Focus on: Scalable go-to-market, operational efficiency
+Measure: NDR, burn multiple, revenue per FTE, OKR attainment
+Start building: Budget vs actuals, department-level P&L
+Build now: Finance team (first financial controller), ERP or NetSuite
+Frequency: Monthly board pack + quarterly deep dive
+```
+
+**Series C+ ($20M+ ARR):**
+```
+Focus on: Path to profitability, market leadership
+Measure: Rule of 40, free cash flow, CAC efficiency by segment
+Must have: FP&A team, full three-statement model, 5-year plan
+Frequency: Monthly financial close (< 3 business days), quarterly earnings prep
+```
+
+### Reporting Cadence
+
+**Weekly (CFO + leadership):**
+- Cash balance (CFO checks daily, reports weekly)
+- Pipeline / sales metrics (if in a sales-led motion)
+- Any metric that changed dramatically vs. prior week
+
+**Monthly (board + leadership):**
+- Full financial dashboard (ARR, gross margin, burn, runway)
+- Budget vs actual with explanations for > 10% variances
+- Unit economics update
+- Headcount change summary
+
+**Quarterly (board + investors):**
+- Full three-statement model vs budget
+- Cohort analysis update
+- Scenario planning review and trigger assessment
+- Next quarter outlook
+
+---
+
+## 5. Budget vs Actual Analysis Framework
+
+### The Purpose of BvA
+
+Budget vs actual is not about being right. It's about understanding *why* you were wrong, so you can make better decisions.
+
+The CFO who reports "we missed budget by 15%" without explanation is failing. The CFO who says "we missed budget by 15% because enterprise deals took 30 more days to close than modeled — here's what we're doing about it" is doing their job.
+
+### BvA Template
+
+```
+Category Budget Actual $ Var % Var Explanation
+-------------------------------------------------------------------
+ARR $2,400K $2,280K ($120K) (5%) 2 enterprise deals slipped to Q1
+New ARR $400K $350K ($50K) (13%) Above
+Expansion ARR $120K $140K $20K 17% PLG motion outperforming
+Churn ($60K) ($80K) ($20K) (33%) 2 unexpected SMB churns (now fixed)
+Gross Margin 75.0% 73.2% -1.8% n/a Infrastructure over-provisioned
+S&M Spend $820K $840K ($20K) (2%) Within tolerance
+R&D Spend $680K $710K ($30K) (4%) Backfill hire started month early
+G&A Spend $140K $148K ($8K) (6%) Legal fees for new customer contract
+Cash Burn (net) $580K $648K ($68K) (12%) Driven by ARR shortfall + costs
+Runway (mo) 14.5 13.0 (1.5) n/a Tracking; fundraise target unchanged
+```
+
+### Variance Thresholds
+
+```
+< ±5%: Note in appendix, no explanation needed in main pack
+5-10%: One-line explanation required
+> 10%: Full paragraph: what happened, why, what changes
+> 20%: Board conversation required (model assumption was wrong, or unexpected event)
+```
+
+### Forecasting vs Budgeting
+
+**Budget:** Set at start of year. Fixed expectation. Updated quarterly.
+**Forecast:** Rolling 3-month outlook. Updated monthly. Should converge with budget over time.
+
+```
+Common mistake: Treating forecast as wishful thinking ("what we hope happens")
+Correct approach: Forecast is your best current estimate given all known information.
+ If forecast diverges from budget by > 15%, the budget is wrong.
+ Reforecast and communicate to board.
+```
+
+**Rolling forecast (recommended for startups):**
+```
+Always have a 12-month forward model.
+Update it monthly with actuals replacing the first month.
+The forecast should always reflect your current operational reality, not your hope.
+```
+
+---
+
+## Key Formulas Reference
+
+```python
+# ARR and growth
+ARR_growth_yoy = (ending_ARR - beginning_ARR) / beginning_ARR
+
+# Net Dollar Retention
+NDR = (beginning_MRR + expansion_MRR - churn_MRR - contraction_MRR) / beginning_MRR
+
+# Burn Multiple
+burn_multiple = net_cash_burn / net_new_ARR
+
+# Rule of 40
+rule_of_40 = revenue_growth_pct + ebitda_margin_pct
+
+# LTV (SaaS)
+LTV = (ARPA * gross_margin_pct) / monthly_churn_rate
+
+# CAC Payback (months)
+cac_payback = CAC / (ARPA * gross_margin_pct)
+
+# Magic Number (sales efficiency)
+magic_number = (net_new_ARR * 4) / prior_quarter_S_and_M_spend
+
+# Gross margin
+gross_margin = (revenue - COGS) / revenue
+
+# Quick Ratio (growth efficiency)
+quick_ratio = (new_MRR + expansion_MRR) / (churned_MRR + contraction_MRR)
+# Target: > 4 for high-growth SaaS
+```
diff --git a/skills/c-level-advisor/cfo-advisor/references/fundraising_playbook.md b/skills/c-level-advisor/cfo-advisor/references/fundraising_playbook.md
new file mode 100644
index 00000000..97a546e0
--- /dev/null
+++ b/skills/c-level-advisor/cfo-advisor/references/fundraising_playbook.md
@@ -0,0 +1,419 @@
+# Fundraising Playbook
+
+From timing to close. What investors actually look for, how valuation works, and the term sheet clauses that matter.
+
+---
+
+## 1. When to Raise
+
+**Optimal timing:**
+```
+Target: 18-24 months runway post-close
+Minimum: 12 months runway post-close (leaves no buffer for slip)
+
+Start process when: 9-12 months runway remaining
+ → 3-6 months for process (typically 4-5 months for Series A/B)
+ → Leaves 3-6 months buffer if process drags
+
+Never start when: < 6 months runway
+ → You're negotiating from desperation
+ → Investors can smell it
+ → Terms get worse, or you don't close at all
+```
+
+**Rule:** Your leverage is maximum when you don't *need* to raise. Raise from a position of momentum, not necessity.
+
+---
+
+## 2. What Investors Look For at Each Stage
+
+### Pre-seed
+- Team (are these people credible for this problem?)
+- Problem clarity (is the problem real and meaningful?)
+- Early signal (any customers paying, waitlist, prototype)
+- Market size (worth building a VC-scale company?)
+
+**Typical ask:** $500K–$2M | **Typical valuation:** $3M–$10M pre-money
+
+### Seed
+- Product-market signal (customers using and paying)
+- Founding team with domain expertise
+- ARR: $100K–$1M (or strong usage for PLG)
+- Clear hypothesis for what Series A looks like
+
+**Typical ask:** $2M–$5M | **Typical valuation:** $8M–$20M pre-money
+
+### Series A
+
+Investors are buying a *repeatable sales motion*. Not just customers — a machine.
+
+**What they need to see:**
+- ARR: $1M–$5M growing > 100% YoY
+- LTV:CAC > 2.5x (and improving)
+- Net Dollar Retention > 100%
+- CAC Payback < 18 months
+- Gross margin > 65%
+- At least 5-10 reference customers (not just lighthouse)
+- Sales motion that converts without the founder closing every deal
+
+**Typical ask:** $8M–$15M | **Typical valuation:** $25M–$60M pre-money
+
+### Series B
+
+Investors are buying *scalable go-to-market*. Can you pour fuel on the fire?
+
+**What they need to see:**
+- ARR: $5M–$20M growing > 100% YoY
+- LTV:CAC > 3x, CAC Payback < 18 months
+- Sales capacity model (hiring plan → pipeline → revenue)
+- NDR > 110% (expansion motion working)
+- Some proof of market expansion (new segments, geographies, use cases)
+- Path to category leadership
+
+**Typical ask:** $15M–$40M | **Typical valuation:** $60M–$200M pre-money
+
+### Series C and Beyond
+
+Investors are buying *market leadership* and *path to profitability*.
+
+**What they need to see:**
+- ARR: $20M+ (often $30-50M for credible Series C)
+- Rule of 40 > 40 (or credible path)
+- Gross margin > 70%
+- NDR > 115%
+- Evidence of market leadership (brand, win rates, analyst mentions)
+- Clear path to $100M+ ARR
+
+---
+
+## 3. Valuation Methods
+
+### Revenue Multiples (Primary Method for SaaS)
+
+```
+Pre-money Valuation = ARR × Revenue Multiple
+
+Revenue multiple benchmarks (2024-2025):
+ > 100% YoY growth: 8x–15x ARR
+ 50-100% YoY growth: 4x–8x ARR
+ 20-50% YoY growth: 2x–4x ARR
+ < 20% YoY growth: 1x–2x ARR
+
+Adjustments:
+ NDR > 120%: +1x–2x premium
+ Gross margin > 75%: +0.5x–1x premium
+ Burn multiple < 1x: +0.5x–1x premium
+ Capital efficient: Investors pay up for efficiency
+ Declining growth: Compress multiple aggressively
+```
+
+### The Investor's Math (Know This)
+
+Every VC has a required return. Work backwards from their constraints:
+
+```
+Investor targets: 3x fund return
+Fund size: $200M, check size: $15M (initial), $25M (with follow-on)
+Ownership at exit needed: 15%
+At 15% ownership: needs $25M / 15% = $167M post-money valuation
+Exit needed to return 3x on that check: $25M × 10 = $250M company value
+ (10x because most deals fail, winners must carry the fund)
+
+Implication: If you think you'll exit for $150M, that VC will pass or price you accordingly.
+```
+
+This is why Series A investors rarely lead rounds where they can't see a $300M+ exit path. It's not about your business being bad — it's about fund math.
+
+### Comparable Company Analysis
+
+For later stages (Series B+):
+
+```
+1. Find 5-10 comparable public SaaS companies
+2. Calculate their EV/NTM Revenue multiples (use latest data)
+3. Apply a private market discount (typically 20-40% vs public comps)
+4. Adjust for your growth rate relative to comps
+
+Example (2024):
+ Public SaaS comps: 6x NTM Revenue (median)
+ Private discount: 30%
+ Adjusted: ~4.2x
+ Your NTM Revenue: $8M
+ Implied valuation: ~$33M pre-money
+```
+
+### DCF (Late Stage Only)
+
+DCF is unreliable for early-stage startups (terminal value dominates, growth rate assumptions are fantasy). Use it as a sanity check at Series C+, not as the primary valuation method.
+
+---
+
+## 4. Term Sheet Breakdown
+
+### Liquidation Preference (Most Important Economic Term)
+
+This determines who gets paid first in an exit — and how much.
+
+```
+1x Non-Participating Preferred (BEST for founders):
+ Investor gets 1x money back OR converts to common (their choice).
+ At acquisition: investor takes larger of {1x invested} or {% ownership × proceeds}
+ Example: $10M invested, exits at $100M, owns 20%
+ Option A: $10M (1x)
+ Option B: $20M (20% of $100M)
+ Investor takes $20M. Founders split $80M.
+
+1x Participating Preferred (WORSE for founders):
+ Investor gets 1x money back AND participates in remaining proceeds.
+ Example: same scenario
+ $10M (1x) + 20% of remaining $90M = $10M + $18M = $28M
+ Founders split $72M instead of $80M
+ Cost to founders: $8M (10% of exit value)
+
+2x Participating (RED FLAG):
+ Investor gets 2x back AND participates.
+ Only accept under duress. Push hard against this.
+
+Full Ratchet Anti-Dilution (AVOID):
+ Down-round triggers full repricing of investor shares to new (lower) price.
+ Founders get massively diluted. Never accept if alternatives exist.
+```
+
+### Anti-Dilution Protection
+
+```
+Broad-based weighted average (standard):
+ Adjusts investor conversion price based on all dilutive securities.
+ Most founder-friendly anti-dilution. Accept this.
+
+Narrow-based weighted average (slightly worse):
+ Same mechanism but uses smaller denominator.
+ Gives investors slightly more protection. Usually acceptable.
+
+Full ratchet (avoid):
+ Price drops to whatever the new round prices at.
+ Devastating in down rounds. Fight this.
+```
+
+### Pro-Rata Rights
+
+```
+Standard pro-rata: Investor can maintain their % ownership in future rounds.
+ Reasonable. Accept for major investors.
+
+Super pro-rata: Investor can increase their % in future rounds.
+ Caps your ability to bring in new lead investors.
+ Avoid unless the investor is exceptional and you want them in future rounds.
+
+Major investor threshold: Typically investors with > $500K–$1M check get pro-rata.
+ Don't give pro-rata to every small check — clogs future rounds.
+```
+
+### Board Composition
+
+```
+Seed (3 members): 2 founders, 1 lead investor
+Series A (5 members): 2 founders, 2 investors, 1 independent
+Series B (5-7 seats): Watch for investor majority — negotiate hard
+
+Rule: Founders should retain majority through Series A.
+ Independent director should be your choice, not investor's.
+ Never accept investor majority before Series C.
+
+Board observer rights: Common for smaller investors. No vote but present in meetings.
+ Limit to 1-2 observers or meetings become unwieldy.
+```
+
+### Other Terms That Matter
+
+```
+Drag-along: Majority can force minority shareholders to vote for acquisition.
+ Standard and reasonable. Check what threshold triggers drag.
+
+Information rights: Investors get financial statements.
+ Standard. Monthly for major investors, quarterly for others.
+
+Redemption rights: Investors can force buyback after X years.
+ Push to remove or add carve-outs for insufficient funds.
+
+No-shop clause: You can't shop the term sheet to other investors.
+ Standard (14-30 days). Reasonable.
+
+Exclusivity: Stronger version of no-shop. Sometimes includes no other fundraise discussions.
+ Acceptable for 30 days; push back on > 45 days.
+```
+
+---
+
+## 5. Cap Table Management
+
+### Dilution Planning Model
+
+Run this before every round. Know your number before walking into any negotiation.
+
+```
+ Pre-Seed Post-Seed Post-A Post-B Post-C
+Founder A 45.0% 36.0% 26.5% 21.2% 18.7%
+Founder B 45.0% 36.0% 26.5% 21.2% 18.7%
+Angel 1 5.0% 4.0% 2.9% 2.4% 2.1%
+Angel 2 5.0% 4.0% 2.9% 2.4% 2.1%
+Seed Fund - 12.0% 8.8% 7.1% 6.2%
+Option Pool - 8.0% 12.0% 10.0% 8.0%
+Series A - - 20.4% 16.3% 14.4%
+Series B - - - 19.5% 17.2%
+Series C - - - - 12.6%
+
+Round size / pre-money:
+Pre-Seed: $500K / $9M pre = 5% dilution
+Seed: $2M / $8M pre = 20% dilution (includes 8% pool)
+Series A: $10M / $38M pre = 20.8% dilution (pool refresh to 12%)
+Series B: $20M / $80M pre = 20% dilution
+Series C: $30M / $170M pre = 15% dilution
+```
+
+**Option pool shuffle:** Investors often require you to create/expand the option pool *before* the round closes, which dilutes existing shareholders (not the incoming investor). Model this explicitly — a 20% round with a 5% pool expansion is really 24%+ dilution to founders.
+
+### Cap Table Hygiene
+
+```
+Tools: Carta, Pulley, Capshare (all acceptable)
+Never: Track cap table in a spreadsheet past seed stage. Errors compound.
+
+Keep it clean:
+ - Repurchase departed co-founder shares immediately (don't let unvested shares linger)
+ - Convert SAFEs to equity cleanly at each priced round
+ - Document every grant with a board resolution
+ - Cliff + vesting for ALL employees and founders (standard: 1-year cliff, 4-year vest)
+ - 409A valuation required before every option grant (IRS requirement)
+```
+
+---
+
+## 6. Data Room Preparation
+
+### Core Documents (Required)
+
+```
+Financial:
+ □ 3 years historical financials (or all history if < 3 years)
+ □ Monthly P&L and cash flow (last 24 months)
+ □ Current financial model (18-24 months forward)
+ □ Budget vs actual (last 4 quarters)
+ □ Cap table (fully diluted, with all SAFEs/convertibles modeled)
+ □ Bank statements (last 3-6 months)
+
+Legal:
+ □ Certificate of incorporation + all amendments
+ □ All prior financing documents (SAFEs, convertible notes, stock purchase agreements)
+ □ Cap table (Carta/Pulley export)
+ □ IP assignment agreements (all founders and employees)
+ □ Material contracts (top 10 customers, key vendors)
+ □ Employee list (titles, start dates, salaries, equity grants)
+
+Product & Business:
+ □ Product demo / walkthrough video
+ □ Architecture overview (for technical investors)
+ □ Customer case studies (3-5 named references)
+ □ NPS / CSAT data
+ □ Competitive landscape analysis
+
+Metrics:
+ □ MRR/ARR by month (all history)
+ □ Cohort retention chart
+ □ CAC by channel
+ □ LTV by cohort
+ □ NPS trend
+```
+
+### What Investors Actually Check First
+
+In order of typical priority during due diligence:
+
+1. **Cap table** — Is it clean? Any concerning structures?
+2. **Cohort retention** — Is churn improving or deteriorating?
+3. **Revenue quality** — What % is recurring? Any one-time or non-recurring?
+4. **Top 10 customers** — Concentration risk? Any logos at risk?
+5. **Bank statements** — Does cash match what was reported?
+6. **IP assignments** — Does the company own its IP? (Founders who didn't assign IP kill deals)
+
+### Red Flags That Kill Deals
+
+- Missing IP assignment agreements for founders (most common deal killer at early stage)
+- Cap table with > 20 angels/small investors (messy, hard to get consent for future rounds)
+- Customer concentration > 30% in single customer without explanation
+- Revenue recognition issues (booking ARR on contracts that allow easy cancellation)
+- Cohort data that gets worse in later cohorts
+- Bank balance doesn't match reported cash position
+
+---
+
+## 7. Investor Communication Cadence
+
+### During Fundraise
+
+```
+Week 1-2: Warm intro sourcing, LP/network mapping
+Week 3-6: First meetings (aim for 20-30 first meetings)
+Week 7-10: Partner meetings, deep dives, due diligence
+Week 11-14: Term sheets, negotiation
+Week 15-18: Legal, closing
+```
+
+**Parallel process is essential.** Never negotiate with one investor at a time. Competition is your leverage.
+
+### Post-Close: Investor Updates
+
+Monthly investor update (send within 10 days of month-end):
+
+```
+Subject: [Company] Monthly Update — [Month Year]
+
+Highlights (3 bullets max):
+ • [Biggest win]
+ • [Biggest learning/challenge]
+ • [What we're focused on next month]
+
+Metrics:
+ ARR: $X (+X% MoM)
+ Net new ARR: $X
+ Gross margin: X%
+ Cash: $X (X months runway)
+ Headcount: X
+
+Asks (be specific):
+ • Looking for intro to [persona/company] for [specific reason]
+ • Need advisor with experience in [specific area]
+ • [Other concrete ask]
+```
+
+**Why this matters:** Investors who are informed and engaged are better positioned to help when you need it. The investor who hasn't heard from you in 6 months is less likely to write a bridge check or make a warm intro when you ask.
+
+---
+
+## Key Formulas
+
+```python
+# Post-money valuation
+post_money = pre_money + investment_amount
+
+# Investor ownership %
+ownership_pct = investment_amount / post_money
+
+# Dilution to existing shareholders
+dilution = investment_amount / post_money # as a fraction
+
+# New shares issued
+new_shares = (investment_amount / post_money) * total_post_shares
+# equivalent: new_shares = pre_money_shares * (investment_amount / pre_money)
+
+# Option pool expansion impact (pool shuffle)
+# Creating X% option pool pre-close dilutes founders:
+pool_shares_needed = target_pct * (pre_shares + new_round_shares + pool_shares_needed)
+# Solve: pool_shares_needed = target_pct * (pre_shares + new_round_shares) / (1 - target_pct)
+
+# LTV:CAC ratio
+ltv_cac = ltv / cac # target: > 3x
+
+# CAC payback (months)
+payback_months = cac / (arpa * gross_margin_pct)
+```
diff --git a/skills/c-level-advisor/cfo-advisor/scripts/burn_rate_calculator.py b/skills/c-level-advisor/cfo-advisor/scripts/burn_rate_calculator.py
new file mode 100644
index 00000000..6580a31b
--- /dev/null
+++ b/skills/c-level-advisor/cfo-advisor/scripts/burn_rate_calculator.py
@@ -0,0 +1,402 @@
+#!/usr/bin/env python3
+"""
+Burn Rate & Runway Calculator
+==============================
+Models startup runway across base/bull/bear scenarios, incorporating
+a hiring plan and revenue trajectory. Outputs months of runway,
+cash-out dates, and decision trigger points.
+
+Usage:
+ python burn_rate_calculator.py
+ python burn_rate_calculator.py --csv # export to CSV
+
+Stdlib only. No dependencies.
+"""
+
+import argparse
+import csv
+import io
+import sys
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HiringEntry:
+ """A planned hire."""
+ month: int # months from model start (1-indexed)
+ role: str
+ department: str # "sales", "engineering", "cs", "ga"
+ annual_salary: float
+ benefits_pct: float = 0.22 # benefits as % of salary
+ recruiting_cost: float = 0.0 # one-time recruiting fee
+
+
+@dataclass
+class RevenueEntry:
+ """Monthly revenue data point (historical or projected)."""
+ month: int
+ mrr: float # monthly recurring revenue
+ one_time: float = 0.0
+
+
+@dataclass
+class ModelConfig:
+ """Master configuration for a runway scenario."""
+ name: str
+ starting_cash: float
+ starting_mrr: float
+ starting_headcount: int
+ avg_loaded_salary: float # average fully-loaded salary per current employee
+ base_non_headcount_opex: float # monthly non-headcount costs (infra, tools, etc.)
+ gross_margin_pct: float # 0.0–1.0
+ mrr_growth_rate: float # monthly MoM growth rate, 0.0–1.0
+ hiring_plan: list[HiringEntry] = field(default_factory=list)
+ model_months: int = 24
+ start_date: Optional[date] = None
+
+
+@dataclass
+class MonthResult:
+ """Single month output."""
+ month: int
+ label: str # e.g. "Month 1 (Apr 2025)"
+ mrr: float
+ gross_profit: float
+ headcount: int
+ headcount_cost: float # total loaded headcount cost this month
+ other_opex: float
+ gross_burn: float
+ net_burn: float
+ cash_start: float
+ cash_end: float
+ runway_months: float # projected runway from this month
+ cumulative_new_arr: float # for burn multiple
+
+
+# ---------------------------------------------------------------------------
+# Core calculator
+# ---------------------------------------------------------------------------
+
+class RunwayCalculator:
+
+ def __init__(self, config: ModelConfig):
+ self.cfg = config
+
+ def run(self) -> list[MonthResult]:
+ cfg = self.cfg
+ results = []
+
+ # Build headcount schedule: month -> list of new hires starting that month
+ hire_by_month: dict[int, list[HiringEntry]] = {}
+ for h in cfg.hiring_plan:
+ hire_by_month.setdefault(h.month, []).append(h)
+
+ # Track existing employees
+ active_employees: list[dict] = []
+ for _ in range(cfg.starting_headcount):
+ active_employees.append({
+ "monthly_loaded": cfg.avg_loaded_salary / 12 * 1.0,
+ "start_month": 0,
+ })
+
+ cash = cfg.starting_cash
+ mrr = cfg.starting_mrr
+ cumulative_new_arr = 0.0
+ starting_mrr = cfg.starting_mrr
+
+ for m in range(1, cfg.model_months + 1):
+ # Process new hires this month
+ one_time_recruiting = 0.0
+ if m in hire_by_month:
+ for hire in hire_by_month[m]:
+ monthly_loaded = (
+ hire.annual_salary * (1 + hire.benefits_pct) / 12
+ )
+ active_employees.append({
+ "monthly_loaded": monthly_loaded,
+ "start_month": m,
+ })
+ one_time_recruiting += hire.recruiting_cost
+
+ # Revenue this month
+ mrr = mrr * (1 + cfg.mrr_growth_rate)
+ gross_profit = mrr * cfg.gross_margin_pct
+
+ # Headcount cost
+ headcount_cost = sum(e["monthly_loaded"] for e in active_employees)
+ headcount_cost += one_time_recruiting
+
+ # Other opex (infra, SaaS tools, office, etc.)
+ other_opex = cfg.base_non_headcount_opex
+
+ # Burn
+ gross_burn = headcount_cost + other_opex
+ net_burn = gross_burn - gross_profit
+
+ # Cash
+ cash_start = cash
+ cash = cash - net_burn
+ cash_end = cash
+
+ # Projected runway from this month (using current net burn rate)
+ runway = cash_end / net_burn if net_burn > 0 else float("inf")
+
+ # Cumulative new ARR (for burn multiple calc)
+ new_mrr_added = mrr - starting_mrr if m == 1 else mrr - results[-1].mrr
+ cumulative_new_arr += new_mrr_added * 12
+
+ # Label
+ if cfg.start_date:
+ month_date = date(
+ cfg.start_date.year,
+ cfg.start_date.month,
+ 1,
+ ) + timedelta(days=32 * (m - 1))
+ month_date = month_date.replace(day=1)
+ label = f"Month {m:02d} ({month_date.strftime('%b %Y')})"
+ else:
+ label = f"Month {m:02d}"
+
+ results.append(MonthResult(
+ month=m,
+ label=label,
+ mrr=mrr,
+ gross_profit=gross_profit,
+ headcount=len(active_employees),
+ headcount_cost=headcount_cost,
+ other_opex=other_opex,
+ gross_burn=gross_burn,
+ net_burn=net_burn,
+ cash_start=cash_start,
+ cash_end=cash_end,
+ runway_months=runway,
+ cumulative_new_arr=cumulative_new_arr,
+ ))
+
+ # Stop if cash runs out
+ if cash_end <= 0:
+ break
+
+ return results
+
+ def cash_out_date(self, results: list[MonthResult]) -> Optional[str]:
+ """Return the label of the month cash runs out, or None if model survives."""
+ for r in results:
+ if r.cash_end <= 0:
+ return r.label
+ return None
+
+ def burn_multiple(self, results: list[MonthResult]) -> float:
+ """Burn multiple = total net burn / total net new ARR over model period."""
+ total_net_burn = sum(r.net_burn for r in results if r.net_burn > 0)
+ first_mrr = results[0].mrr / (1 + self.cfg.mrr_growth_rate) # starting mrr
+ total_new_arr = (results[-1].mrr - first_mrr) * 12
+ if total_new_arr <= 0:
+ return float("inf")
+ return total_net_burn / total_new_arr
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt_k(value: float) -> str:
+ """Format as $Xk or $X.XM."""
+ if abs(value) >= 1_000_000:
+ return f"${value/1_000_000:.2f}M"
+ if abs(value) >= 1_000:
+ return f"${value/1_000:.0f}K"
+ return f"${value:.0f}"
+
+
+def print_summary(name: str, results: list[MonthResult], calc: RunwayCalculator) -> None:
+ cash_out = calc.cash_out_date(results)
+ bm = calc.burn_multiple(results)
+ last = results[-1]
+ first = results[0]
+
+ print(f"\n{'='*60}")
+ print(f" SCENARIO: {name}")
+ print(f"{'='*60}")
+ print(f" Months modeled: {len(results)}")
+ print(f" Cash out: {cash_out or 'Does not run out in model period'}")
+ print(f" Ending cash: {fmt_k(last.cash_end)}")
+ print(f" Final runway: {last.runway_months:.1f} months")
+ print(f" Starting MRR: {fmt_k(first.mrr)}")
+ print(f" Ending MRR: {fmt_k(last.mrr)}")
+ print(f" Ending headcount: {last.headcount}")
+ print(f" Burn multiple: {bm:.2f}x")
+ print(f" Avg net burn: {fmt_k(sum(r.net_burn for r in results)/len(results))}/mo")
+
+ # Decision triggers
+ print(f"\n Decision Triggers:")
+ triggers = {9: "⚠️ START FUNDRAISE", 6: "🔴 COST REDUCTION PLAN", 4: "🚨 EXECUTE CUTS / BRIDGE"}
+ shown = set()
+ for r in results:
+ for threshold, label in triggers.items():
+ if r.runway_months <= threshold and threshold not in shown:
+ print(f" {r.label}: {label} (runway = {r.runway_months:.1f} mo)")
+ shown.add(threshold)
+
+
+def print_monthly_table(results: list[MonthResult], max_rows: int = 24) -> None:
+ header = f"{'Month':<22} {'MRR':>10} {'Hdct':>6} {'Net Burn':>12} {'Cash':>12} {'Runway':>8}"
+ print(f"\n{header}")
+ print("-" * len(header))
+ for r in results[:max_rows]:
+ runway_str = f"{r.runway_months:.1f}mo" if r.runway_months != float("inf") else "∞"
+ print(
+ f"{r.label:<22} "
+ f"{fmt_k(r.mrr):>10} "
+ f"{r.headcount:>6} "
+ f"{fmt_k(r.net_burn):>12} "
+ f"{fmt_k(r.cash_end):>12} "
+ f"{runway_str:>8}"
+ )
+
+
+def export_csv(scenarios: list[tuple[str, list[MonthResult]]]) -> str:
+ buf = io.StringIO()
+ writer = csv.writer(buf)
+ writer.writerow([
+ "Scenario", "Month", "Label", "MRR", "Gross Profit", "Headcount",
+ "Headcount Cost", "Other Opex", "Gross Burn", "Net Burn",
+ "Cash Start", "Cash End", "Runway Months"
+ ])
+ for name, results in scenarios:
+ for r in results:
+ writer.writerow([
+ name, r.month, r.label,
+ round(r.mrr, 2), round(r.gross_profit, 2), r.headcount,
+ round(r.headcount_cost, 2), round(r.other_opex, 2),
+ round(r.gross_burn, 2), round(r.net_burn, 2),
+ round(r.cash_start, 2), round(r.cash_end, 2),
+ round(r.runway_months, 2),
+ ])
+ return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def make_sample_configs() -> list[ModelConfig]:
+ """
+ Sample company: Series A SaaS startup
+ - $3M cash on hand (post Series A)
+ - $125K MRR (~$1.5M ARR)
+ - 18 employees, $150K avg salary
+ - $80K/mo non-headcount opex (infra, tools, office)
+ - 72% gross margin
+ """
+ common_kwargs = dict(
+ starting_cash=3_000_000,
+ starting_mrr=125_000,
+ starting_headcount=18,
+ avg_loaded_salary=150_000,
+ base_non_headcount_opex=80_000,
+ gross_margin_pct=0.72,
+ model_months=24,
+ start_date=date(2025, 1, 1),
+ )
+
+ # Base: 10% MoM growth, moderate hiring
+ base_hiring = [
+ HiringEntry(month=2, role="AE #1", department="sales", annual_salary=120_000, recruiting_cost=18_000),
+ HiringEntry(month=3, role="Senior SWE #1", department="engineering", annual_salary=160_000, recruiting_cost=24_000),
+ HiringEntry(month=5, role="SDR #1", department="sales", annual_salary=80_000, recruiting_cost=12_000),
+ HiringEntry(month=6, role="CSM #1", department="cs", annual_salary=90_000, recruiting_cost=13_500),
+ HiringEntry(month=8, role="AE #2", department="sales", annual_salary=120_000, recruiting_cost=18_000),
+ HiringEntry(month=9, role="Senior SWE #2", department="engineering", annual_salary=165_000, recruiting_cost=24_750),
+ HiringEntry(month=12, role="Controller", department="ga", annual_salary=130_000, recruiting_cost=19_500),
+ HiringEntry(month=14, role="AE #3", department="sales", annual_salary=125_000, recruiting_cost=18_750),
+ HiringEntry(month=15, role="ML Engineer", department="engineering", annual_salary=175_000, recruiting_cost=26_250),
+ HiringEntry(month=18, role="AE #4", department="sales", annual_salary=125_000, recruiting_cost=18_750),
+ ]
+
+ # Bull: 15% MoM growth, full hiring plan
+ bull_hiring = base_hiring + [
+ HiringEntry(month=4, role="Marketing Manager", department="sales", annual_salary=110_000, recruiting_cost=16_500),
+ HiringEntry(month=7, role="Senior SWE #3", department="engineering", annual_salary=165_000, recruiting_cost=24_750),
+ HiringEntry(month=10, role="AE #5", department="sales", annual_salary=125_000, recruiting_cost=18_750),
+ HiringEntry(month=13, role="DevOps Engineer", department="engineering", annual_salary=150_000, recruiting_cost=22_500),
+ HiringEntry(month=16, role="AE #6", department="sales", annual_salary=125_000, recruiting_cost=18_750),
+ ]
+
+ # Bear: 5% MoM growth, hiring freeze after month 3
+ bear_hiring = [
+ HiringEntry(month=2, role="AE #1", department="sales", annual_salary=120_000, recruiting_cost=18_000),
+ HiringEntry(month=3, role="Senior SWE #1", department="engineering", annual_salary=160_000, recruiting_cost=24_000),
+ ]
+
+ return [
+ ModelConfig(name="BULL (15% MoM, full hiring)", mrr_growth_rate=0.15, hiring_plan=bull_hiring, **common_kwargs),
+ ModelConfig(name="BASE (10% MoM, planned hiring)", mrr_growth_rate=0.10, hiring_plan=base_hiring, **common_kwargs),
+ ModelConfig(name="BEAR ( 5% MoM, hiring freeze M3+)", mrr_growth_rate=0.05, hiring_plan=bear_hiring, **common_kwargs),
+ ModelConfig(name="DISTRESS (0% growth, freeze now)", mrr_growth_rate=0.00, hiring_plan=[], **common_kwargs),
+ ]
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Startup Burn Rate & Runway Calculator")
+ parser.add_argument("--csv", action="store_true", help="Export full monthly data as CSV to stdout")
+ parser.add_argument("--scenario", choices=["bull", "base", "bear", "distress", "all"], default="all")
+ args = parser.parse_args()
+
+ configs = make_sample_configs()
+ if args.scenario != "all":
+ configs = [c for c in configs if args.scenario.upper() in c.name.upper()]
+
+ all_results: list[tuple[str, list[MonthResult]]] = []
+
+ print("\n" + "="*60)
+ print(" BURN RATE & RUNWAY CALCULATOR")
+ print(" Sample Company: Series A SaaS Startup")
+ print(" Starting cash: $3M | Starting MRR: $125K | 18 employees")
+ print("="*60)
+
+ for cfg in configs:
+ calc = RunwayCalculator(cfg)
+ results = calc.run()
+ all_results.append((cfg.name, results))
+ print_summary(cfg.name, results, calc)
+ print_monthly_table(results)
+
+ # Comparison summary
+ print("\n" + "="*60)
+ print(" SCENARIO COMPARISON")
+ print("="*60)
+ print(f" {'Scenario':<40} {'Runway':>8} {'Cash Out':<30} {'Burn Mult':>10}")
+ print(" " + "-"*88)
+ for cfg, (name, results) in zip(configs, all_results):
+ calc = RunwayCalculator(cfg)
+ cash_out = calc.cash_out_date(results) or "Survives model period"
+ bm = calc.burn_multiple(results)
+ final_runway = results[-1].runway_months
+ runway_str = f"{final_runway:.1f}mo" if final_runway != float("inf") else "∞"
+ bm_str = f"{bm:.2f}x" if bm != float("inf") else "∞"
+ print(f" {name:<40} {runway_str:>8} {cash_out:<30} {bm_str:>10}")
+
+ print("\n Decision Trigger Reference:")
+ print(" 9 months runway → Start fundraise process")
+ print(" 6 months runway → Begin cost reduction planning")
+ print(" 4 months runway → Execute cuts; explore bridge financing")
+ print(" 3 months runway → Emergency plan only")
+
+ if args.csv:
+ print("\n\n--- CSV EXPORT ---\n")
+ sys.stdout.write(export_csv(all_results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cfo-advisor/scripts/fundraising_model.py b/skills/c-level-advisor/cfo-advisor/scripts/fundraising_model.py
new file mode 100644
index 00000000..7b19f15b
--- /dev/null
+++ b/skills/c-level-advisor/cfo-advisor/scripts/fundraising_model.py
@@ -0,0 +1,490 @@
+#!/usr/bin/env python3
+"""
+Fundraising Model
+==================
+Cap table management, dilution modeling, and multi-round scenario planning.
+Know exactly what you're giving up before you walk into any negotiation.
+
+Covers:
+ - Cap table state at each round
+ - Dilution per shareholder per round
+ - Option pool shuffle impact
+ - Multi-round projections (Seed → A → B → C)
+ - Return scenarios at different exit valuations
+
+Usage:
+ python fundraising_model.py
+ python fundraising_model.py --exit 150 # model at $150M exit
+ python fundraising_model.py --csv
+
+Stdlib only. No dependencies.
+"""
+
+import argparse
+import csv
+import io
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Shareholder:
+ """A shareholder in the cap table."""
+ name: str
+ share_class: str # "common", "preferred", "option"
+ shares: float
+ invested: float = 0.0 # total cash invested
+ is_option_pool: bool = False
+
+
+@dataclass
+class RoundConfig:
+ """Configuration for a financing round."""
+ name: str # e.g. "Series A"
+ pre_money_valuation: float
+ investment_amount: float
+ new_option_pool_pct: float = 0.0 # % of POST-money to allocate to new options
+ option_pool_pre_round: bool = True # True = pool created before round (dilutes founders)
+ lead_investor_name: str = "New Investor"
+ share_price_override: Optional[float] = None # if None, computed from valuation
+
+
+@dataclass
+class CapTableEntry:
+ """A row in the cap table at a point in time."""
+ name: str
+ share_class: str
+ shares: float
+ pct_ownership: float
+ invested: float
+ is_option_pool: bool = False
+
+
+@dataclass
+class RoundResult:
+ """Snapshot of cap table after a round closes."""
+ round_name: str
+ pre_money_valuation: float
+ investment_amount: float
+ post_money_valuation: float
+ price_per_share: float
+ new_shares_issued: float
+ option_pool_shares_created: float
+ total_shares: float
+ cap_table: list[CapTableEntry]
+
+
+@dataclass
+class ExitAnalysis:
+ """Proceeds to each shareholder at an exit."""
+ exit_valuation: float
+ shareholder: str
+ shares: float
+ ownership_pct: float
+ proceeds_common: float # if all preferred converts to common
+ invested: float
+ moic: float # multiple on invested capital (for investors)
+
+
+# ---------------------------------------------------------------------------
+# Core cap table engine
+# ---------------------------------------------------------------------------
+
+class CapTable:
+ """Manages a cap table through multiple rounds."""
+
+ def __init__(self):
+ self.shareholders: list[Shareholder] = []
+ self._total_shares: float = 0.0
+
+ def add_shareholder(self, sh: Shareholder) -> None:
+ self.shareholders.append(sh)
+ self._total_shares += sh.shares
+
+ def total_shares(self) -> float:
+ return sum(s.shares for s in self.shareholders)
+
+ def snapshot(self, label: str = "") -> list[CapTableEntry]:
+ total = self.total_shares()
+ return [
+ CapTableEntry(
+ name=s.name,
+ share_class=s.share_class,
+ shares=s.shares,
+ pct_ownership=s.shares / total if total > 0 else 0,
+ invested=s.invested,
+ is_option_pool=s.is_option_pool,
+ )
+ for s in self.shareholders
+ ]
+
+ def execute_round(self, config: RoundConfig) -> RoundResult:
+ """
+ Execute a financing round:
+ 1. (Optional) Create option pool pre-round (dilutes existing shareholders)
+ 2. Issue new shares to investor at round price
+ Returns a RoundResult with full cap table snapshot.
+ """
+ current_total = self.total_shares()
+
+ # Step 1: Option pool shuffle (if pre-round)
+ option_pool_shares_created = 0.0
+ if config.new_option_pool_pct > 0 and config.option_pool_pre_round:
+ # Target: post-round option pool = new_option_pool_pct of total post-money shares
+ # Solve: pool_shares / (current_total + pool_shares + new_investor_shares) = target_pct
+ # This requires iteration because new_investor_shares also depends on pool_shares
+ # Simplification: create pool based on post-round total (slightly approximated)
+ target_post_round_pct = config.new_option_pool_pct
+ post_money = config.pre_money_valuation + config.investment_amount
+
+ # Estimate shares per dollar (price per share)
+ price_per_share = config.pre_money_valuation / current_total
+ new_investor_shares_estimate = config.investment_amount / price_per_share
+
+ # Pool shares needed so that pool / total_post = target_pct
+ total_post_estimate = current_total + new_investor_shares_estimate
+ pool_shares_needed = (target_post_round_pct * total_post_estimate) / (1 - target_post_round_pct)
+
+ # Check if existing pool is sufficient
+ existing_pool = next(
+ (s.shares for s in self.shareholders if s.is_option_pool), 0
+ )
+ additional_pool_needed = max(0, pool_shares_needed - existing_pool)
+
+ if additional_pool_needed > 0:
+ option_pool_shares_created = additional_pool_needed
+ # Add to existing pool or create new
+ pool_sh = next((s for s in self.shareholders if s.is_option_pool), None)
+ if pool_sh:
+ pool_sh.shares += additional_pool_needed
+ else:
+ self.shareholders.append(Shareholder(
+ name="Option Pool",
+ share_class="option",
+ shares=additional_pool_needed,
+ is_option_pool=True,
+ ))
+
+ # Step 2: Price per share (after pool creation)
+ current_total_post_pool = self.total_shares()
+ if config.share_price_override:
+ price_per_share = config.share_price_override
+ else:
+ price_per_share = config.pre_money_valuation / current_total_post_pool
+
+ # Step 3: New shares for investor
+ new_shares = config.investment_amount / price_per_share
+
+ # Step 4: Add investor to cap table
+ self.shareholders.append(Shareholder(
+ name=config.lead_investor_name,
+ share_class="preferred",
+ shares=new_shares,
+ invested=config.investment_amount,
+ ))
+
+ post_money = config.pre_money_valuation + config.investment_amount
+ total_post = self.total_shares()
+
+ return RoundResult(
+ round_name=config.name,
+ pre_money_valuation=config.pre_money_valuation,
+ investment_amount=config.investment_amount,
+ post_money_valuation=post_money,
+ price_per_share=price_per_share,
+ new_shares_issued=new_shares,
+ option_pool_shares_created=option_pool_shares_created,
+ total_shares=total_post,
+ cap_table=self.snapshot(),
+ )
+
+ def analyze_exit(self, exit_valuation: float) -> list[ExitAnalysis]:
+ """
+ Simple exit analysis: all preferred converts to common, proceeds split pro-rata.
+ (Does not model liquidation preferences — see fundraising_playbook.md for that.)
+ """
+ total = self.total_shares()
+ price_per_share = exit_valuation / total
+ results = []
+ for s in self.shareholders:
+ if s.is_option_pool:
+ continue # unissued options don't receive proceeds
+ proceeds = s.shares * price_per_share
+ moic = proceeds / s.invested if s.invested > 0 else 0.0
+ results.append(ExitAnalysis(
+ exit_valuation=exit_valuation,
+ shareholder=s.name,
+ shares=s.shares,
+ ownership_pct=s.shares / total,
+ proceeds_common=proceeds,
+ invested=s.invested,
+ moic=moic,
+ ))
+ return sorted(results, key=lambda x: x.proceeds_common, reverse=True)
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt(value: float, prefix: str = "$") -> str:
+ if value == float("inf"):
+ return "∞"
+ if abs(value) >= 1_000_000:
+ return f"{prefix}{value/1_000_000:.2f}M"
+ if abs(value) >= 1_000:
+ return f"{prefix}{value/1_000:.0f}K"
+ return f"{prefix}{value:.2f}"
+
+
+def print_round_result(result: RoundResult, prev_cap_table: Optional[list[CapTableEntry]] = None) -> None:
+ print(f"\n{'='*70}")
+ print(f" {result.round_name.upper()}")
+ print(f"{'='*70}")
+ print(f" Pre-money valuation: {fmt(result.pre_money_valuation)}")
+ print(f" Investment: {fmt(result.investment_amount)}")
+ print(f" Post-money valuation: {fmt(result.post_money_valuation)}")
+ print(f" Price per share: {fmt(result.price_per_share, '$')}")
+ print(f" New shares issued: {result.new_shares_issued:,.0f}")
+ if result.option_pool_shares_created > 0:
+ print(f" Option pool created: {result.option_pool_shares_created:,.0f} shares")
+ print(f" ⚠️ Pool created pre-round: dilutes existing shareholders, not new investor")
+ print(f" Total shares post: {result.total_shares:,.0f}")
+
+ print(f"\n {'Shareholder':<22} {'Shares':>12} {'Ownership':>10} {'Invested':>10} {'Δ Ownership':>12}")
+ print(" " + "-"*68)
+
+ prev_map = {e.name: e.pct_ownership for e in prev_cap_table} if prev_cap_table else {}
+
+ for entry in result.cap_table:
+ delta = ""
+ if entry.name in prev_map:
+ change = (entry.pct_ownership - prev_map[entry.name]) * 100
+ delta = f"{change:+.1f}pp"
+ elif not entry.is_option_pool:
+ delta = "new"
+
+ invested_str = fmt(entry.invested) if entry.invested > 0 else "-"
+ print(
+ f" {entry.name:<22} {entry.shares:>12,.0f} "
+ f"{entry.pct_ownership*100:>9.2f}% {invested_str:>10} {delta:>12}"
+ )
+
+
+def print_exit_analysis(results: list[ExitAnalysis], exit_valuation: float) -> None:
+ print(f"\n{'='*70}")
+ print(f" EXIT ANALYSIS @ {fmt(exit_valuation)} (all preferred converts to common)")
+ print(f"{'='*70}")
+ print(f"\n {'Shareholder':<22} {'Ownership':>10} {'Proceeds':>12} {'Invested':>10} {'MOIC':>8}")
+ print(" " + "-"*65)
+ for r in results:
+ moic_str = f"{r.moic:.1f}x" if r.moic > 0 else "n/a"
+ invested_str = fmt(r.invested) if r.invested > 0 else "-"
+ print(
+ f" {r.shareholder:<22} {r.ownership_pct*100:>9.2f}% "
+ f"{fmt(r.proceeds_common):>12} {invested_str:>10} {moic_str:>8}"
+ )
+ print(f"\n Note: Does not model liquidation preferences.")
+ print(f" Participating preferred reduces founder proceeds in most real exits.")
+ print(f" See references/fundraising_playbook.md for full liquidation waterfall.")
+
+
+def print_dilution_summary(rounds: list[RoundResult]) -> None:
+ print(f"\n{'='*70}")
+ print(f" DILUTION SUMMARY — FOUNDER PERSPECTIVE")
+ print(f"{'='*70}")
+
+ # Find all founders (common shareholders who aren't investors or option pool)
+ founder_names = []
+ for entry in rounds[0].cap_table:
+ if entry.share_class == "common" and not entry.is_option_pool:
+ founder_names.append(entry.name)
+
+ if not founder_names:
+ print(" No common shareholders found in initial cap table.")
+ return
+
+ header = f" {'Round':<16}" + "".join(f" {n:<16}" for n in founder_names) + f" {'Total Inv':>12}"
+ print(header)
+ print(" " + "-" * (16 + 18 * len(founder_names) + 14))
+
+ for result in rounds:
+ cap_map = {e.name: e for e in result.cap_table}
+ total_invested = sum(e.invested for e in result.cap_table if not e.is_option_pool)
+ row = f" {result.round_name:<16}"
+ for name in founder_names:
+ pct = cap_map[name].pct_ownership * 100 if name in cap_map else 0
+ row += f" {pct:>6.2f}% "
+ row += f" {fmt(total_invested):>12}"
+ print(row)
+
+
+def export_csv_rounds(rounds: list[RoundResult]) -> str:
+ buf = io.StringIO()
+ writer = csv.writer(buf)
+ writer.writerow(["Round", "Shareholder", "Share Class", "Shares", "Ownership Pct",
+ "Invested", "Pre Money", "Post Money", "Price Per Share"])
+ for r in rounds:
+ for entry in r.cap_table:
+ writer.writerow([
+ r.round_name, entry.name, entry.share_class,
+ round(entry.shares, 0), round(entry.pct_ownership * 100, 4),
+ round(entry.invested, 2), round(r.pre_money_valuation, 0),
+ round(r.post_money_valuation, 0), round(r.price_per_share, 4),
+ ])
+ return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data: typical two-founder Series A/B/C startup
+# ---------------------------------------------------------------------------
+
+def build_sample_model() -> tuple[CapTable, list[RoundResult]]:
+ """
+ Sample company:
+ - 2 founders, started with 10M shares each
+ - 1M shares for early advisor
+ - Raises Pre-seed → Seed → Series A → Series B → Series C
+ """
+ cap = CapTable()
+ SHARES_PER_FOUNDER = 4_000_000
+ SHARES_ADVISOR = 200_000
+
+ # Founding state
+ cap.add_shareholder(Shareholder("Founder A (CEO)", "common", SHARES_PER_FOUNDER))
+ cap.add_shareholder(Shareholder("Founder B (CTO)", "common", SHARES_PER_FOUNDER))
+ cap.add_shareholder(Shareholder("Advisor", "common", SHARES_ADVISOR))
+
+ rounds: list[RoundResult] = []
+ prev_cap = cap.snapshot()
+
+ # Round 1: Pre-seed — $500K at $4.5M pre, 10% option pool created
+ r1 = cap.execute_round(RoundConfig(
+ name="Pre-seed",
+ pre_money_valuation=4_500_000,
+ investment_amount=500_000,
+ new_option_pool_pct=0.10,
+ option_pool_pre_round=True,
+ lead_investor_name="Angel Syndicate",
+ ))
+ rounds.append(r1)
+ prev_r1 = r1.cap_table[:]
+
+ # Round 2: Seed — $2M at $9M pre, expand option pool to 12%
+ r2 = cap.execute_round(RoundConfig(
+ name="Seed",
+ pre_money_valuation=9_000_000,
+ investment_amount=2_000_000,
+ new_option_pool_pct=0.12,
+ option_pool_pre_round=True,
+ lead_investor_name="Seed Fund",
+ ))
+ rounds.append(r2)
+
+ # Round 3: Series A — $12M at $38M pre, refresh option pool to 15%
+ r3 = cap.execute_round(RoundConfig(
+ name="Series A",
+ pre_money_valuation=38_000_000,
+ investment_amount=12_000_000,
+ new_option_pool_pct=0.15,
+ option_pool_pre_round=True,
+ lead_investor_name="Series A Fund",
+ ))
+ rounds.append(r3)
+
+ # Round 4: Series B — $25M at $95M pre, refresh pool to 12%
+ r4 = cap.execute_round(RoundConfig(
+ name="Series B",
+ pre_money_valuation=95_000_000,
+ investment_amount=25_000_000,
+ new_option_pool_pct=0.12,
+ option_pool_pre_round=True,
+ lead_investor_name="Series B Fund",
+ ))
+ rounds.append(r4)
+
+ # Round 5: Series C — $40M at $185M pre, refresh pool to 10%
+ r5 = cap.execute_round(RoundConfig(
+ name="Series C",
+ pre_money_valuation=185_000_000,
+ investment_amount=40_000_000,
+ new_option_pool_pct=0.10,
+ option_pool_pre_round=True,
+ lead_investor_name="Series C Fund",
+ ))
+ rounds.append(r5)
+
+ return cap, rounds
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Fundraising Model — Cap Table & Dilution")
+ parser.add_argument("--exit", type=float, default=250.0,
+ help="Exit valuation in $M for return analysis (default: 250)")
+ parser.add_argument("--csv", action="store_true", help="Export round data as CSV to stdout")
+ args = parser.parse_args()
+
+ exit_valuation = args.exit * 1_000_000
+
+ print("\n" + "="*70)
+ print(" FUNDRAISING MODEL — CAP TABLE & DILUTION ANALYSIS")
+ print(" Sample Company: Two-founder SaaS startup")
+ print(" Pre-seed → Seed → Series A → Series B → Series C")
+ print("="*70)
+
+ cap, rounds = build_sample_model()
+
+ # Print each round
+ prev = None
+ for r in rounds:
+ print_round_result(r, prev)
+ prev = r.cap_table
+
+ # Dilution summary table
+ print_dilution_summary(rounds)
+
+ # Exit analysis at specified valuation
+ exit_results = cap.analyze_exit(exit_valuation)
+ print_exit_analysis(exit_results, exit_valuation)
+
+ # Also print at 2x and 5x for sensitivity
+ print("\n Exit Sensitivity — Founder A Proceeds:")
+ print(f" {'Exit Valuation':<20} {'Founder A %':>12} {'Founder A $':>14} {'MOIC':>8}")
+ print(" " + "-"*56)
+ for mult in [0.5, 1.0, 1.5, 2.0, 3.0, 5.0]:
+ val = rounds[-1].post_money_valuation * mult
+ ex = cap.analyze_exit(val)
+ founder_a = next((r for r in ex if r.shareholder == "Founder A (CEO)"), None)
+ if founder_a:
+ print(f" {fmt(val):<20} {founder_a.ownership_pct*100:>11.2f}% "
+ f"{fmt(founder_a.proceeds_common):>14} {'n/a':>8}")
+
+ print("\n Key Takeaways:")
+ final = rounds[-1].cap_table
+ total = sum(e.shares for e in final)
+ founder_a_final = next((e for e in final if e.name == "Founder A (CEO)"), None)
+ if founder_a_final:
+ print(f" Founder A final ownership: {founder_a_final.pct_ownership*100:.2f}%")
+ total_raised = sum(e.invested for e in final)
+ print(f" Total capital raised: {fmt(total_raised)}")
+ print(f" Total shares outstanding: {total:,.0f}")
+ print(f" Final post-money: {fmt(rounds[-1].post_money_valuation)}")
+ print("\n Run with --exit <$M> to model proceeds at different exit valuations.")
+ print(" Example: python fundraising_model.py --exit 500")
+
+ if args.csv:
+ print("\n\n--- CSV EXPORT ---\n")
+ sys.stdout.write(export_csv_rounds(rounds))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cfo-advisor/scripts/unit_economics_analyzer.py b/skills/c-level-advisor/cfo-advisor/scripts/unit_economics_analyzer.py
new file mode 100644
index 00000000..4433f936
--- /dev/null
+++ b/skills/c-level-advisor/cfo-advisor/scripts/unit_economics_analyzer.py
@@ -0,0 +1,529 @@
+#!/usr/bin/env python3
+"""
+Unit Economics Analyzer
+========================
+Per-cohort LTV, per-channel CAC, payback periods, and LTV:CAC ratios.
+Never blended averages — those hide what's actually happening.
+
+Usage:
+ python unit_economics_analyzer.py
+ python unit_economics_analyzer.py --csv
+
+Stdlib only. No dependencies.
+"""
+
+import argparse
+import csv
+import io
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CohortData:
+ """
+ Revenue data for a group of customers acquired in the same period.
+ Revenue is tracked monthly: revenue[0] = month 1, revenue[1] = month 2, etc.
+ """
+ label: str # e.g. "Q1 2024"
+ acquisition_period: str # human-readable label
+ customers_acquired: int
+ total_cac_spend: float # total S&M spend to acquire this cohort
+ monthly_revenue: list[float] # revenue per month from this cohort
+ gross_margin_pct: float = 0.70 # blended gross margin for this cohort
+
+
+@dataclass
+class ChannelData:
+ """Acquisition cost and customer data for a single channel."""
+ channel: str
+ spend: float
+ customers_acquired: int
+ avg_arpa: float # average revenue per account (monthly)
+ gross_margin_pct: float = 0.70
+ avg_monthly_churn: float = 0.02 # monthly churn rate for customers from this channel
+
+
+@dataclass
+class UnitEconomicsResult:
+ """Computed unit economics for a cohort or channel."""
+ label: str
+ customers: int
+ cac: float
+ arpa: float # average revenue per account per month
+ gross_margin_pct: float
+ monthly_churn: float
+ ltv: float
+ ltv_cac_ratio: float
+ payback_months: float
+ # Cohort-specific
+ m1_revenue: Optional[float] = None
+ m6_revenue: Optional[float] = None
+ m12_revenue: Optional[float] = None
+ m24_revenue: Optional[float] = None
+ m12_ltv: Optional[float] = None # realized LTV through month 12
+ retention_m6: Optional[float] = None # % of M1 revenue retained at M6
+ retention_m12: Optional[float] = None
+
+
+# ---------------------------------------------------------------------------
+# Calculators
+# ---------------------------------------------------------------------------
+
+def calc_ltv(arpa: float, gross_margin_pct: float, monthly_churn: float) -> float:
+ """
+ LTV = (ARPA × Gross Margin) / Monthly Churn Rate
+ Assumes constant churn (simplified; cohort method is more accurate).
+ """
+ if monthly_churn <= 0:
+ return float("inf")
+ return (arpa * gross_margin_pct) / monthly_churn
+
+
+def calc_payback(cac: float, arpa: float, gross_margin_pct: float) -> float:
+ """
+ CAC Payback (months) = CAC / (ARPA × Gross Margin)
+ """
+ denominator = arpa * gross_margin_pct
+ if denominator <= 0:
+ return float("inf")
+ return cac / denominator
+
+
+def analyze_cohort(cohort: CohortData) -> UnitEconomicsResult:
+ """Compute full unit economics for a cohort."""
+ n = cohort.customers_acquired
+ if n == 0:
+ raise ValueError(f"Cohort {cohort.label}: customers_acquired cannot be 0")
+
+ cac = cohort.total_cac_spend / n
+
+ # ARPA from month 1 revenue
+ m1_rev = cohort.monthly_revenue[0] if cohort.monthly_revenue else 0
+ arpa = m1_rev / n if n > 0 else 0
+
+ # Observed monthly churn from cohort data
+ # Use revenue decline from M1 to M12 to estimate churn
+ months_available = len(cohort.monthly_revenue)
+ if months_available >= 12:
+ m12_rev = cohort.monthly_revenue[11]
+ # Revenue retention over 12 months: (M12/M1)^(1/11) per month on average
+ # Implied monthly retention rate
+ if m1_rev > 0 and m12_rev > 0:
+ monthly_retention = (m12_rev / m1_rev) ** (1 / 11)
+ monthly_churn = 1 - monthly_retention
+ else:
+ monthly_churn = 0.02 # default
+ elif months_available >= 6:
+ m6_rev = cohort.monthly_revenue[5]
+ if m1_rev > 0 and m6_rev > 0:
+ monthly_retention = (m6_rev / m1_rev) ** (1 / 5)
+ monthly_churn = 1 - monthly_retention
+ else:
+ monthly_churn = 0.02
+ else:
+ monthly_churn = 0.02 # default if < 6 months data
+
+ # Clamp to reasonable range
+ monthly_churn = max(0.001, min(monthly_churn, 0.30))
+
+ ltv = calc_ltv(arpa, cohort.gross_margin_pct, monthly_churn)
+ payback = calc_payback(cac, arpa, cohort.gross_margin_pct)
+ ltv_cac = ltv / cac if cac > 0 else float("inf")
+
+ # Snapshot revenues
+ def rev_at(month_idx: int) -> Optional[float]:
+ if months_available > month_idx:
+ return cohort.monthly_revenue[month_idx]
+ return None
+
+ m6 = rev_at(5)
+ m12 = rev_at(11)
+ m24 = rev_at(23)
+
+ # Realized LTV through observed months (actual gross profit)
+ m12_ltv = sum(cohort.monthly_revenue[:12]) * cohort.gross_margin_pct if months_available >= 12 else None
+
+ # Retention rates
+ ret_m6 = (m6 / m1_rev) if (m6 is not None and m1_rev > 0) else None
+ ret_m12 = (m12 / m1_rev) if (m12 is not None and m1_rev > 0) else None
+
+ return UnitEconomicsResult(
+ label=cohort.label,
+ customers=n,
+ cac=cac,
+ arpa=arpa,
+ gross_margin_pct=cohort.gross_margin_pct,
+ monthly_churn=monthly_churn,
+ ltv=ltv,
+ ltv_cac_ratio=ltv_cac,
+ payback_months=payback,
+ m1_revenue=m1_rev,
+ m6_revenue=m6,
+ m12_revenue=m12,
+ m24_revenue=m24,
+ m12_ltv=m12_ltv,
+ retention_m6=ret_m6,
+ retention_m12=ret_m12,
+ )
+
+
+def analyze_channel(ch: ChannelData) -> UnitEconomicsResult:
+ """Compute unit economics for an acquisition channel."""
+ if ch.customers_acquired == 0:
+ raise ValueError(f"Channel {ch.channel}: customers_acquired cannot be 0")
+
+ cac = ch.spend / ch.customers_acquired
+ ltv = calc_ltv(ch.avg_arpa, ch.gross_margin_pct, ch.avg_monthly_churn)
+ payback = calc_payback(cac, ch.avg_arpa, ch.gross_margin_pct)
+ ltv_cac = ltv / cac if cac > 0 else float("inf")
+
+ return UnitEconomicsResult(
+ label=ch.channel,
+ customers=ch.customers_acquired,
+ cac=cac,
+ arpa=ch.avg_arpa,
+ gross_margin_pct=ch.gross_margin_pct,
+ monthly_churn=ch.avg_monthly_churn,
+ ltv=ltv,
+ ltv_cac_ratio=ltv_cac,
+ payback_months=payback,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Blended metrics (for comparison)
+# ---------------------------------------------------------------------------
+
+def blended_cac(channels: list[ChannelData]) -> float:
+ total_spend = sum(c.spend for c in channels)
+ total_customers = sum(c.customers_acquired for c in channels)
+ return total_spend / total_customers if total_customers > 0 else 0
+
+
+def blended_ltv(channels: list[ChannelData]) -> float:
+ """Weighted average LTV by customers acquired."""
+ total_customers = sum(c.customers_acquired for c in channels)
+ if total_customers == 0:
+ return 0
+ weighted = sum(
+ calc_ltv(c.avg_arpa, c.gross_margin_pct, c.avg_monthly_churn) * c.customers_acquired
+ for c in channels
+ )
+ return weighted / total_customers
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt(value: float, prefix: str = "$", decimals: int = 0) -> str:
+ if value == float("inf"):
+ return "∞"
+ if abs(value) >= 1_000_000:
+ return f"{prefix}{value/1_000_000:.2f}M"
+ if abs(value) >= 1_000:
+ return f"{prefix}{value/1_000:.1f}K"
+ return f"{prefix}{value:.{decimals}f}"
+
+
+def pct(value: Optional[float]) -> str:
+ if value is None:
+ return "n/a"
+ return f"{value*100:.1f}%"
+
+
+def rating(ltv_cac: float, payback: float) -> str:
+ if ltv_cac == float("inf"):
+ return "∞"
+ if ltv_cac >= 5 and payback <= 12:
+ return "🟢 Excellent"
+ if ltv_cac >= 3 and payback <= 18:
+ return "🟡 Good"
+ if ltv_cac >= 2 and payback <= 24:
+ return "🟠 Marginal"
+ return "🔴 Poor"
+
+
+def print_cohort_analysis(results: list[UnitEconomicsResult]) -> None:
+ print("\n" + "="*80)
+ print(" COHORT ANALYSIS")
+ print("="*80)
+ print(f" {'Cohort':<12} {'Cust':>5} {'CAC':>8} {'ARPA/mo':>9} {'Churn/mo':>10} "
+ f"{'LTV':>10} {'LTV:CAC':>8} {'Payback':>9} {'Ret@M12':>8}")
+ print(" " + "-"*88)
+ for r in results:
+ payback_str = f"{r.payback_months:.1f}mo" if r.payback_months != float("inf") else "∞"
+ ltv_str = fmt(r.ltv) if r.ltv != float("inf") else "∞"
+ ltv_cac_str = f"{r.ltv_cac_ratio:.1f}x" if r.ltv_cac_ratio != float("inf") else "∞"
+ print(
+ f" {r.label:<12} {r.customers:>5} {fmt(r.cac):>8} {fmt(r.arpa):>9} "
+ f"{pct(r.monthly_churn):>10} {ltv_str:>10} {ltv_cac_str:>8} "
+ f"{payback_str:>9} {pct(r.retention_m12):>8}"
+ )
+
+ # Trend analysis
+ print("\n Cohort Trend (is the business getting better or worse?):")
+ if len(results) >= 3:
+ ltv_cac_values = [r.ltv_cac_ratio for r in results if r.ltv_cac_ratio != float("inf")]
+ cac_values = [r.cac for r in results]
+ churn_values = [r.monthly_churn for r in results]
+
+ if len(ltv_cac_values) >= 2:
+ ltv_cac_trend = "↑ Improving" if ltv_cac_values[-1] > ltv_cac_values[0] else "↓ Deteriorating"
+ else:
+ ltv_cac_trend = "n/a"
+
+ cac_trend = "↓ Decreasing (good)" if cac_values[-1] < cac_values[0] else "↑ Increasing"
+ churn_trend = "↓ Improving" if churn_values[-1] < churn_values[0] else "↑ Worsening"
+
+ print(f" LTV:CAC: {ltv_cac_trend}")
+ print(f" CAC: {cac_trend}")
+ print(f" Churn rate: {churn_trend}")
+
+
+def print_channel_analysis(results: list[UnitEconomicsResult], channels: list[ChannelData]) -> None:
+ print("\n" + "="*80)
+ print(" CHANNEL ANALYSIS (Per-Channel vs Blended)")
+ print("="*80)
+ print(f" {'Channel':<22} {'Spend':>9} {'Cust':>5} {'CAC':>8} {'LTV':>10} {'LTV:CAC':>8} {'Payback':>9} {'Rating'}")
+ print(" " + "-"*90)
+ for r, ch in zip(results, channels):
+ payback_str = f"{r.payback_months:.1f}mo" if r.payback_months != float("inf") else "∞"
+ ltv_str = fmt(r.ltv) if r.ltv != float("inf") else "∞"
+ ltv_cac_str = f"{r.ltv_cac_ratio:.1f}x" if r.ltv_cac_ratio != float("inf") else "∞"
+ print(
+ f" {r.label:<22} {fmt(ch.spend):>9} {r.customers:>5} {fmt(r.cac):>8} "
+ f"{ltv_str:>10} {ltv_cac_str:>8} {payback_str:>9} {rating(r.ltv_cac_ratio, r.payback_months)}"
+ )
+
+ # Blended comparison
+ b_cac = blended_cac(channels)
+ b_ltv = blended_ltv(channels)
+ b_ltv_cac = b_ltv / b_cac if b_cac > 0 else 0
+ total_spend = sum(c.spend for c in channels)
+ total_customers = sum(c.customers_acquired for c in channels)
+ avg_payback = sum(
+ calc_payback(b_cac, c.avg_arpa, c.gross_margin_pct) * c.customers_acquired
+ for c in channels
+ ) / total_customers
+
+ print(" " + "-"*90)
+ print(
+ f" {'BLENDED (dangerous)':<22} {fmt(total_spend):>9} {total_customers:>5} "
+ f"{fmt(b_cac):>8} {fmt(b_ltv):>10} {b_ltv_cac:.1f}x{'':<7} "
+ f"{avg_payback:.1f}mo{'':<4} {rating(b_ltv_cac, avg_payback)}"
+ )
+ print("\n ⚠️ Blended numbers hide channel-level problems. Manage channels individually.")
+
+ # Budget reallocation
+ print("\n Recommended Budget Reallocation:")
+ sorted_results = sorted(zip(results, channels), key=lambda x: x[0].ltv_cac_ratio, reverse=True)
+ for r, ch in sorted_results:
+ if r.ltv_cac_ratio >= 3:
+ action = "✅ Scale"
+ elif r.ltv_cac_ratio >= 2:
+ action = "🔄 Optimize"
+ else:
+ action = "❌ Cut / pause"
+ print(f" {ch.channel:<22} LTV:CAC = {r.ltv_cac_ratio:.1f}x → {action}")
+
+
+def export_csv_results(cohort_results: list[UnitEconomicsResult], channel_results: list[UnitEconomicsResult]) -> str:
+ buf = io.StringIO()
+ writer = csv.writer(buf)
+ writer.writerow(["Type", "Label", "Customers", "CAC", "ARPA_Monthly", "Gross_Margin_Pct",
+ "Monthly_Churn", "LTV", "LTV_CAC_Ratio", "Payback_Months",
+ "Retention_M6", "Retention_M12"])
+ for r in cohort_results:
+ writer.writerow(["cohort", r.label, r.customers, round(r.cac, 2), round(r.arpa, 2),
+ r.gross_margin_pct, round(r.monthly_churn, 4),
+ round(r.ltv, 2) if r.ltv != float("inf") else "inf",
+ round(r.ltv_cac_ratio, 2) if r.ltv_cac_ratio != float("inf") else "inf",
+ round(r.payback_months, 2) if r.payback_months != float("inf") else "inf",
+ round(r.retention_m6, 3) if r.retention_m6 else "",
+ round(r.retention_m12, 3) if r.retention_m12 else ""])
+ for r in channel_results:
+ writer.writerow(["channel", r.label, r.customers, round(r.cac, 2), round(r.arpa, 2),
+ r.gross_margin_pct, round(r.monthly_churn, 4),
+ round(r.ltv, 2) if r.ltv != float("inf") else "inf",
+ round(r.ltv_cac_ratio, 2) if r.ltv_cac_ratio != float("inf") else "inf",
+ round(r.payback_months, 2) if r.payback_months != float("inf") else "inf",
+ "", ""])
+ return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def make_sample_cohorts() -> list[CohortData]:
+ """
+ Series A SaaS company, 8 quarters of cohort data.
+ Shows a business improving on all dimensions over time.
+ """
+ return [
+ CohortData(
+ label="Q1 2023", acquisition_period="Jan-Mar 2023",
+ customers_acquired=12, total_cac_spend=54_000,
+ gross_margin_pct=0.68,
+ monthly_revenue=[
+ 10_200, 9_600, 9_100, 8_700, 8_300, 8_000, # M1-M6
+ 7_800, 7_600, 7_400, 7_200, 7_000, 6_800, # M7-M12
+ 6_700, 6_600, 6_500, 6_400, 6_300, 6_200, # M13-M18
+ 6_100, 6_000, 5_900, 5_800, 5_700, 5_600, # M19-M24
+ ],
+ ),
+ CohortData(
+ label="Q2 2023", acquisition_period="Apr-Jun 2023",
+ customers_acquired=15, total_cac_spend=60_000,
+ gross_margin_pct=0.69,
+ monthly_revenue=[
+ 13_500, 12_900, 12_500, 12_100, 11_800, 11_500,
+ 11_300, 11_100, 10_900, 10_700, 10_500, 10_300,
+ 10_200, 10_100, 10_000, 9_900, 9_800, 9_700,
+ ],
+ ),
+ CohortData(
+ label="Q3 2023", acquisition_period="Jul-Sep 2023",
+ customers_acquired=18, total_cac_spend=63_000,
+ gross_margin_pct=0.70,
+ monthly_revenue=[
+ 16_200, 15_800, 15_400, 15_100, 14_800, 14_600,
+ 14_400, 14_200, 14_000, 13_900, 13_800, 13_700,
+ 13_600, 13_500, 13_400, 13_300,
+ ],
+ ),
+ CohortData(
+ label="Q4 2023", acquisition_period="Oct-Dec 2023",
+ customers_acquired=22, total_cac_spend=70_400,
+ gross_margin_pct=0.71,
+ monthly_revenue=[
+ 20_900, 20_500, 20_200, 19_900, 19_700, 19_500,
+ 19_300, 19_100, 19_000, 18_900, 18_800, 18_700,
+ ],
+ ),
+ CohortData(
+ label="Q1 2024", acquisition_period="Jan-Mar 2024",
+ customers_acquired=28, total_cac_spend=81_200,
+ gross_margin_pct=0.72,
+ monthly_revenue=[
+ 27_200, 26_900, 26_600, 26_400, 26_200, 26_000,
+ 25_800, 25_700, 25_600, 25_500,
+ ],
+ ),
+ CohortData(
+ label="Q2 2024", acquisition_period="Apr-Jun 2024",
+ customers_acquired=34, total_cac_spend=91_800,
+ gross_margin_pct=0.72,
+ monthly_revenue=[
+ 33_300, 33_000, 32_800, 32_600, 32_400, 32_200,
+ ],
+ ),
+ CohortData(
+ label="Q3 2024", acquisition_period="Jul-Sep 2024",
+ customers_acquired=40, total_cac_spend=100_000,
+ gross_margin_pct=0.73,
+ monthly_revenue=[
+ 39_600, 39_400, 39_200,
+ ],
+ ),
+ CohortData(
+ label="Q4 2024", acquisition_period="Oct-Dec 2024",
+ customers_acquired=47, total_cac_spend=112_800,
+ gross_margin_pct=0.73,
+ monthly_revenue=[
+ 47_000,
+ ],
+ ),
+ ]
+
+
+def make_sample_channels() -> list[ChannelData]:
+ """
+ Q4 2024 channel breakdown. Blended looks fine; per-channel reveals problems.
+ """
+ return [
+ ChannelData("Organic / SEO", spend=9_500, customers_acquired=14, avg_arpa=950, gross_margin_pct=0.73, avg_monthly_churn=0.015),
+ ChannelData("Paid Search (SEM)", spend=48_000, customers_acquired=18, avg_arpa=980, gross_margin_pct=0.73, avg_monthly_churn=0.020),
+ ChannelData("Paid Social", spend=32_000, customers_acquired=8, avg_arpa=900, gross_margin_pct=0.72, avg_monthly_churn=0.025),
+ ChannelData("Content / Inbound", spend=11_000, customers_acquired=6, avg_arpa=1100, gross_margin_pct=0.74, avg_monthly_churn=0.012),
+ ChannelData("Outbound SDR", spend=22_000, customers_acquired=4, avg_arpa=1200, gross_margin_pct=0.73, avg_monthly_churn=0.022),
+ ChannelData("Events / Webinars", spend=18_500, customers_acquired=3, avg_arpa=1050, gross_margin_pct=0.72, avg_monthly_churn=0.028),
+ ChannelData("Partner / Referral", spend=7_800, customers_acquired=7, avg_arpa=1000, gross_margin_pct=0.73, avg_monthly_churn=0.013),
+ ]
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Unit Economics Analyzer")
+ parser.add_argument("--csv", action="store_true", help="Export results as CSV to stdout")
+ args = parser.parse_args()
+
+ cohorts = make_sample_cohorts()
+ channels = make_sample_channels()
+
+ print("\n" + "="*80)
+ print(" UNIT ECONOMICS ANALYZER")
+ print(" Sample Company: Series A SaaS | Q4 2024 Snapshot")
+ print(" Gross Margin: ~72% | Monthly Churn: derived from cohort data")
+ print("="*80)
+
+ cohort_results = [analyze_cohort(c) for c in cohorts]
+ channel_results = [analyze_channel(c) for c in channels]
+
+ print_cohort_analysis(cohort_results)
+ print_channel_analysis(channel_results, channels)
+
+ # Health summary
+ print("\n" + "="*80)
+ print(" HEALTH SUMMARY")
+ print("="*80)
+ latest = cohort_results[-1]
+ prev = cohort_results[-4] if len(cohort_results) >= 4 else cohort_results[0]
+
+ print(f"\n Latest Cohort ({latest.label}):")
+ print(f" CAC: {fmt(latest.cac)}")
+ ltv_str = fmt(latest.ltv) if latest.ltv != float("inf") else "∞"
+ ltv_cac_str = f"{latest.ltv_cac_ratio:.1f}x" if latest.ltv_cac_ratio != float("inf") else "∞"
+ payback_str = f"{latest.payback_months:.1f} months" if latest.payback_months != float("inf") else "∞"
+ print(f" LTV: {ltv_str}")
+ print(f" LTV:CAC: {ltv_cac_str} (target: > 3x)")
+ print(f" CAC Payback: {payback_str} (target: < 18mo)")
+ print(f" Rating: {rating(latest.ltv_cac_ratio, latest.payback_months)}")
+
+ # Trend vs 4 quarters ago
+ print(f"\n Trend vs {prev.label}:")
+ cac_delta = (latest.cac - prev.cac) / prev.cac * 100
+ ltv_delta_str = "n/a"
+ if latest.ltv != float("inf") and prev.ltv != float("inf"):
+ ltv_delta = (latest.ltv - prev.ltv) / prev.ltv * 100
+ ltv_delta_str = f"{ltv_delta:+.1f}%"
+ cac_str = "↓ Better" if cac_delta < 0 else "↑ Worse"
+ print(f" CAC: {cac_delta:+.1f}% ({cac_str})")
+ print(f" LTV: {ltv_delta_str}")
+
+ print("\n Benchmark Reference:")
+ print(" LTV:CAC > 5x → Scale aggressively")
+ print(" LTV:CAC 3-5x → Healthy; grow at current pace")
+ print(" LTV:CAC 2-3x → Marginal; optimize before scaling")
+ print(" LTV:CAC < 2x → Acquiring unprofitably; stop and fix")
+ print(" Payback < 12mo → Outstanding capital efficiency")
+ print(" Payback 12-18mo → Good for B2B SaaS")
+ print(" Payback > 24mo → Requires long-dated capital to scale")
+
+ if args.csv:
+ print("\n\n--- CSV EXPORT ---\n")
+ sys.stdout.write(export_csv_results(cohort_results, channel_results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/change-management/SKILL.md b/skills/c-level-advisor/change-management/SKILL.md
new file mode 100644
index 00000000..9cc3de34
--- /dev/null
+++ b/skills/c-level-advisor/change-management/SKILL.md
@@ -0,0 +1,253 @@
+---
+name: "change-management"
+description: "Framework for rolling out organizational changes without chaos. Covers the ADKAR model adapted for startups, communication templates, resistance patterns, and change fatigue management. Handles process changes, org restructures, strategy pivots, and culture changes. Use when announcing a reorg, switching tools, pivoting strategy, killing a product, changing leadership, or when user mentions change management, change rollout, managing resistance, org change, reorg, or pivot communication."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: change-management
+ updated: 2026-03-05
+ frameworks: change-playbook
+---
+
+# Change Management Playbook
+
+Most changes fail at implementation, not design. The ADKAR model tells you why and how to fix it.
+
+## Keywords
+change management, ADKAR, organizational change, reorg, process change, tool migration, strategy pivot, change resistance, change fatigue, change communication, stakeholder management, adoption, compliance, change rollout, transition
+
+## Core Model: ADKAR Adapted for Startups
+
+ADKAR is a change management model by Prosci. Original version is for enterprises. This is the startup-speed adaptation.
+
+### A — Awareness
+
+**What it is:** People understand WHY the change is happening — the business reason, not just the announcement.
+
+**The mistake:** Communicating the WHAT before the WHY. "We're moving to a new CRM" before "here's why our current process is killing us."
+
+**What people need to hear:**
+- What is the problem we're solving? (Be honest. If it's "we need to cut costs," say that.)
+- Why now? What would happen if we didn't change?
+- Who made this decision and how?
+
+**Startup shortcut:** A 5-minute video from the CEO or decision-maker explaining the "why" in plain language beats a formal change announcement document every time.
+
+---
+
+### D — Desire
+
+**What it is:** People want to make the change happen — or at least don't actively resist it.
+
+**The mistake:** Assuming communication creates desire. Awareness ≠ desire. People can understand a change and still hate it.
+
+**What creates desire:**
+- "What's in it for me?" — answer this for each stakeholder group, honestly
+- Involving people in the "how" even if the "what" is decided
+- Addressing fears directly: "Some people are worried this means their role is changing. Here's the truth: [honest answer]"
+
+**What destroys desire:**
+- Pretending the change is better for everyone than it is
+- Ignoring the legitimate losses people will experience
+- Making announcements without any consultation
+
+**Startup shortcut:** Run a short "concerns and questions" session within 48 hours of announcement. Not to reverse the decision — to address the fears and show you're listening.
+
+---
+
+### K — Knowledge
+
+**What it is:** People know HOW to operate in the new world — the specific skills, behaviors, and processes.
+
+**The mistake:** Announcing the change and assuming people will figure it out.
+
+**What people need:**
+- Step-by-step documentation of new processes
+- Training or practice sessions before go-live
+- Clear answers to "what do I do when [common scenario]?"
+- Who to ask when they're stuck
+
+**Types of knowledge transfer:**
+| Method | Best for | When |
+|--------|---------|------|
+| Live training | Skill-based changes, complex tools | Before go-live |
+| Documentation | Process changes, reference material | Always |
+| Video walkthroughs | Tool migrations | Available 24/7, self-paced |
+| Shadowing / peer learning | Behavior changes | Weeks 2–4 after launch |
+| Office hours | Any change with many edge cases | First 4–6 weeks |
+
+---
+
+### A — Ability
+
+**What it is:** People have the time, tools, and support to actually do things differently.
+
+**The mistake:** "We've trained everyone" ≠ "everyone can now do it." Training is knowledge. Ability is practice.
+
+**What creates ability:**
+- Time to practice before being evaluated
+- A safe environment to make mistakes (no public shaming for early struggles)
+- Reduced load during transition (if you're asking people to learn new skills, don't simultaneously pile on new work)
+- Access to help (a Slack channel, a point person, documentation)
+
+**Signs of ability gap:**
+- People revert to old behavior under pressure
+- Workarounds emerge (people invent their own way around the new system)
+- Training scores are high but actual behavior hasn't changed
+
+---
+
+### R — Reinforcement
+
+**What it is:** The change sticks. The new behavior becomes the default.
+
+**The mistake:** Declaring victory at go-live. Changes fail because they're never reinforced.
+
+**What creates reinforcement:**
+- Visible measurement (are we tracking adoption?)
+- Recognition of early adopters ("Sarah fully migrated to the new workflow in week 2 — ask her how")
+- Leader modeling (if the CEO uses the old way, everyone will)
+- Removing the old option (when possible — eliminate the path of least resistance)
+- Consequences for non-adoption (stated clearly, applied consistently)
+
+**Adoption vs. compliance:**
+- **Compliance:** People do it when watched, revert when not
+- **Adoption:** People do it because they believe it's better
+
+Only reinforcement creates adoption. Compliance is the result of enforcement. Aim for adoption.
+
+---
+
+## Change Types and ADKAR Application
+
+### Process Change (new tools, new workflows)
+
+**Timeline:** 4–8 weeks for full adoption
+**Hardest phase:** Ability (people know what to do but haven't built the habit)
+**Critical reinforcement:** Remove or deprecate the old tool/process
+
+**Communication sequence:**
+1. Week -2: Announce the why + go-live date
+2. Week -1: Training sessions available
+3. Week 0 (go-live): Launch + point person available
+4. Week 2: Adoption check-in (who's using it? Who isn't?)
+5. Week 4: Feedback collection + public wins
+6. Week 8: Old system deprecated
+
+---
+
+### Org Change (reorg, new leader, team splits/merges)
+
+**Timeline:** 3–6 months for full stabilization
+**Hardest phase:** Desire (people fear for their roles and relationships)
+**Critical reinforcement:** Consistent behavior from new leadership
+
+**Communication sequence:**
+1. Day 0: Announce the change with the "why" — in person or synchronous video
+2. Day 1: 1:1s with most affected team members by their manager
+3. Week 1: FAQ published with honest answers to the 10 most common concerns
+4. Week 2–4: New structure is operating (don't delay implementation)
+5. Month 2: First retrospective — what's working, what needs adjustment
+6. Month 3–6: Regular check-ins on team health and morale
+
+**What to say when a leader is leaving or being replaced:**
+Be honest about what you can share. Never: "We can't share the reasons." Always: either a truthful explanation or "we're not able to share the specifics, but I can tell you [what this means for you]."
+
+---
+
+### Strategy Pivot (new direction, killed products)
+
+**Timeline:** 3–12 months for full alignment
+**Hardest phase:** Awareness (people don't believe the pivot is real)
+**Critical reinforcement:** Resource reallocation that visibly proves the pivot is happening
+
+**Communication sequence:**
+1. Internal first, always. Employees should never hear about a pivot from a press release.
+2. All-hands with full context: what changed in the market, what you're doing, what it means for teams
+3. Each team leader runs a "what does this mean for us?" conversation with their team
+4. Resource reallocation announced within 2 weeks (if the money doesn't move, people won't believe the pivot)
+5. First milestone of the new direction celebrated publicly
+
+**What kills pivots:** Announcing a new direction while still funding the old one at the same level.
+
+---
+
+### Culture Change (values refresh, behavior expectations)
+
+**Timeline:** 12–24 months for genuine behavior change
+**Hardest phase:** Reinforcement (behavior doesn't change just because values were announced)
+**Critical reinforcement:** Visible decisions that reflect the new values
+
+**Communication sequence:**
+1. Build with input: involve a representative sample of the company in defining the change
+2. Announce with story: "Here's what we observed, here's what we're changing and why"
+3. Behavior anchors: for each culture change, state the specific behavior in observable terms
+4. Leader behavior: leadership team must visibly model the new behavior first
+5. Performance integration: new expected behaviors appear in reviews within one cycle
+6. Celebrate the right behaviors: when someone exemplifies the new culture, name it publicly
+
+---
+
+## Resistance Patterns
+
+Resistance is information, not defiance. Diagnose before responding.
+
+| Resistance pattern | What it signals | Response |
+|-------------------|-----------------|---------|
+| "This won't work" | Awareness gap or credibility gap | Explain the evidence base for the change |
+| "Why now?" | Awareness gap | Explain urgency — what happens if we don't change |
+| "I wasn't consulted" | Desire gap | Acknowledge the gap; involve them in the "how" now |
+| "I don't have time for this" | Ability gap | Reduce their load or push the timeline |
+| "We tried this before" | Trust gap | Acknowledge what's different this time. Be specific. |
+| Silent non-compliance | Could be any gap | 1:1 conversation to diagnose |
+
+**The worst response to resistance:** Dismissing it. "Some people are resistant to change" as if resistance is a personality flaw rather than a signal.
+
+---
+
+## Change Fatigue
+
+When organizations change too fast, people stop believing any change will stick.
+
+### Signals
+- Eye-rolls during change announcements ("here we go again")
+- Low attendance at change-related sessions
+- Fast compliance on paper, slow adoption in practice
+- "Last month we were doing X, now we're doing Y" comments
+
+### Prevention
+- **Finish what you start.** Don't announce a new change while the last one is still being absorbed.
+- **Space changes.** One significant change at a time. Give 2–3 months of stability between major changes.
+- **Announce what's NOT changing.** People in change-fatigue need to know what's stable.
+- **Show results.** Publish what the previous change achieved before launching the next.
+
+### When you're already in change fatigue
+- Pause non-critical changes
+- Run a "change inventory": how many changes are in progress simultaneously?
+- Prioritize ruthlessly: which changes are essential now? Which can wait?
+- Communicate stability: "Here's what is NOT changing this quarter"
+
+---
+
+## Key Questions for Change Management
+
+- "Who are the most skeptical people about this change? Have we talked to them directly?"
+- "Do people understand why we're doing this, or just what we're doing?"
+- "Have we given people time to practice before we measure performance on the new way?"
+- "Is the old way still available? If so, people will use it."
+- "Are leaders modeling the new behavior themselves?"
+- "How many changes are we running simultaneously right now?"
+
+## Red Flags
+
+- Change announced on Friday afternoon (people stew over the weekend)
+- "This is final, questions are not welcome" framing
+- No published FAQ or way to ask questions safely
+- Old system/process still running 6 weeks after "go-live"
+- Leaders exempted from the change they're asking everyone else to make
+- No measurement of adoption — assuming go-live = success
+
+## Detailed References
+- `references/change-playbook.md` — ADKAR deep dive, resistance counter-strategies, communication templates, change fatigue management
diff --git a/skills/c-level-advisor/change-management/references/change-playbook.md b/skills/c-level-advisor/change-management/references/change-playbook.md
new file mode 100644
index 00000000..06d8f8d3
--- /dev/null
+++ b/skills/c-level-advisor/change-management/references/change-playbook.md
@@ -0,0 +1,308 @@
+# Change Management Playbook
+
+Deep reference for rolling out organizational changes effectively.
+
+---
+
+## 1. ADKAR Deep Dive with Startup Examples
+
+### Awareness: The "Why" that actually lands
+
+Most change communications fail at awareness because they confuse informing with explaining.
+
+**Informing:** "We're moving from Jira to Linear next month."
+**Explaining:** "Our engineering team loses ~4 hours per week to Jira configuration, search latency, and reporting setup. At our current team size, that's 60+ hours per month. Linear's benchmarks from teams our size show a 40% reduction in that overhead. That's why we're switching — and here's the timeline."
+
+The explanation activates desire. The announcement just creates work.
+
+**Real example: Tool migration**
+> "We tried Asana, we tried Notion tasks, we tried spreadsheets. None of them stuck. After talking to 8 engineering leads at similar companies, the pattern was clear: teams that use Linear stick with it. We're going all-in. Here's why it will be different this time: [specific reasons]."
+
+**Real example: Reorg**
+> "The current structure has our customer success team reporting to Sales, which creates a conflict: Sales is measured on new logo count, CS is measured on retention. We've seen this play out in three recent customer losses where CS needed to raise concerns but felt the pressure to stay quiet. We're changing the reporting structure so CS reports directly to me. This is about removing a structural conflict, not about performance."
+
+---
+
+### Desire: Addressing the "What's in it for me?"
+
+Every stakeholder group needs a different answer.
+
+**Individual contributor:**
+- "Will my job change significantly?"
+- "Will this make my day easier or harder?"
+- "Is my role at risk?"
+
+**Manager:**
+- "What new responsibilities do I take on?"
+- "How do I explain this to my team?"
+- "What happens if someone on my team doesn't adapt?"
+
+**Senior leader:**
+- "What does this change our strategic posture?"
+- "What resources are reallocated and to what?"
+- "How does this affect my relationships with other senior leaders?"
+
+**Resistance scenario: Senior leader whose team is most affected**
+> They're supportive in the room, silent or undermining outside it.
+> Fix: Give them a role in the change. Make them a named co-leader of the implementation. Invested people don't undermine.
+
+---
+
+### Knowledge: The documentation that actually gets used
+
+The reason most change documentation fails: it's written for the decision-maker, not the user.
+
+**Documentation that gets used:**
+- Short (< 2 pages for most changes)
+- Organized by role: "If you're in Sales, here's what changes for you"
+- Answers "what do I do when X happens?" with specific answers
+- Has a clear owner: "Questions? Ask [person] in #channel"
+
+**Documentation that doesn't get used:**
+- Long rationale sections the user doesn't need
+- "See the full policy document for details"
+- No named point of contact
+- Buried in email threads
+
+---
+
+### Ability: The gap between knowing and doing
+
+Signs of a knowledge gap vs. an ability gap:
+
+| Symptom | Knowledge gap | Ability gap |
+|---------|-------------|------------|
+| People don't know what to do | ✅ | |
+| People know what to do but don't do it | | ✅ |
+| People do it wrong consistently | Could be either | |
+| People revert under pressure | | ✅ |
+| Training scores high, behavior unchanged | | ✅ |
+
+**Ability gaps are fixed by:**
+1. Practice time (before being measured)
+2. Reduced cognitive load during transition
+3. Peer support (not just manager support)
+4. Feedback loops that are fast and low-stakes
+
+**What kills ability development:**
+- Measuring performance on the new way in week 1
+- Adding new work simultaneously with the change
+- Making it embarrassing to ask for help
+
+---
+
+### Reinforcement: The phase everyone skips
+
+Go-live is not success. Go-live is the beginning of adoption.
+
+**Reinforcement calendar (template):**
+
+| Week | Action |
+|------|--------|
+| Week 1 (go-live) | High-visibility support. Leadership visible. Point person responsive. |
+| Week 2 | First adoption check: who's using it? Who isn't? Targeted help to laggards. |
+| Week 4 | Celebrate early adopters publicly. Share a win story. |
+| Week 6 | Adoption metric reported to leadership. Decommission old way (if applicable). |
+| Week 8 | Full adoption expected. Non-adoption now a performance conversation. |
+| Month 3 | Retrospective: What's working? What needs adjustment? |
+
+---
+
+## 2. Resistance Patterns and Counter-Strategies
+
+### The Vocal Skeptic
+
+**Who they are:** Asks hard questions in all-hands. Other people follow their lead.
+**What they need:** To feel heard and to understand the logic.
+**Strategy:** Talk to them before the all-hands. Not to persuade them — to hear their concerns and address what's valid. When they feel respected, they often become your best change advocates.
+
+**Script:** "I know you have concerns about this change. I want to understand them before we go broader with the announcement. What's your biggest worry?"
+
+---
+
+### The Silent Non-Complier
+
+**Who they are:** Agrees in meetings, continues the old behavior outside.
+**What they need:** To understand that non-compliance is visible and has consequences.
+**Strategy:** Direct 1:1 conversation. Name the behavior. Ask what's in the way. Give them a clear path.
+
+**Script:** "I've noticed you're still using [old way] two weeks after we launched [new way]. I want to understand what's in the way for you — is it a knowledge issue, a time issue, or something else?"
+
+---
+
+### The Grieving Top Performer
+
+**Who they are:** Was excellent under the old system. The change makes their skills less relevant.
+**What they need:** Recognition of their past contribution and a clear path forward.
+**Strategy:** Name the loss explicitly. "I know you built your expertise on [old approach] and this change asks you to develop a new one. That's a real transition." Then create a specific development plan.
+
+**What not to do:** Pretend the change doesn't affect them disproportionately.
+
+---
+
+### The Fearful Middle Manager
+
+**Who they are:** Middle managers whose authority or role scope is reduced by the change.
+**What they need:** A clear picture of their new role and why it's still valuable.
+**Strategy:** Individual conversation before the announcement. Walk them through what changes, what stays the same, and what their contribution looks like in the new world.
+
+---
+
+### The "We've Been Here Before" Cynics
+
+**Who they are:** Long-tenured employees who've seen multiple failed change initiatives.
+**What they need:** Evidence that this time is different.
+**Strategy:** Acknowledge the history. "I know we've announced changes that didn't stick. Here's specifically what's different this time: [specific differences]." Then prove it fast — show momentum in the first 30 days.
+
+---
+
+## 3. Communication Plan Template per Change Type
+
+### Template: Tool Migration
+
+```
+COMMUNICATION PLAN — [Tool Name] Migration
+
+AUDIENCE: All-hands / [specific team]
+DECISION OWNER: [Name]
+GO-LIVE DATE: [Date]
+POINT OF CONTACT: [Name] in [channel]
+
+COMMUNICATION TIMELINE:
+Week -4: Decision finalized (internal only)
+Week -3: Training materials ready
+Week -2: All-hands announcement (why + timeline + support plan)
+Week -1: Training sessions (2 sessions, different times)
+Week 0: Go-live. Point person in Slack. Old system still accessible.
+Week 2: First adoption check. Targeted help to non-adopters.
+Week 4: Old system access restricted.
+Week 8: Old system fully decommissioned.
+
+KEY MESSAGES:
+- Why we're switching: [honest 2-sentence reason]
+- What changes for you: [role-specific, max 3 bullets]
+- What doesn't change: [this matters for change fatigue]
+- How to get help: [channel, person, office hours]
+- Timeline: [specific dates]
+
+FAQ:
+Q: Is the old system going away completely?
+A: [Honest answer with date]
+Q: What if I have data in the old system?
+A: [Migration plan or acknowledgment]
+Q: What if I'm not proficient by go-live?
+A: [Realistic expectation-setting]
+```
+
+### Template: Reorg Announcement
+
+```
+REORG COMMUNICATION PLAN
+
+ANNOUNCEMENT DATE: [Date]
+EFFECTIVE DATE: [Date]
+FORMAT: Live (synchronous), all affected employees
+
+PRE-ANNOUNCEMENT (1 week before):
+- 1:1 with every affected leader
+- HR briefed and ready for questions
+- FAQ prepared
+
+ANNOUNCEMENT FORMAT:
+1. Context: Why this change? (2-3 minutes)
+2. What's changing: New structure, new reporting lines (3-4 minutes)
+3. What's NOT changing: Roles, comp, team members (2 minutes)
+4. Timeline: When does the new structure take effect? (1 minute)
+5. Q&A: Open, no time limit (at least 15 minutes)
+
+POST-ANNOUNCEMENT (week 1):
+- Each manager runs team meeting to answer team-specific questions
+- HR available for private conversations
+- FAQ published to all
+
+POST-ANNOUNCEMENT (week 2-4):
+- New structure is operational
+- Transition check-in: what questions emerged that weren't anticipated?
+
+THINGS NOT TO SAY:
+- "We can't share why [person] is leaving" (if they are)
+- "This affects everyone equally" (it doesn't)
+- "No one's job is at risk" (unless this is 100% certain)
+```
+
+---
+
+## 4. The Change Fatigue Problem
+
+### How organizations develop change fatigue
+
+**Phase 1 — Excitement (first 1-2 changes):** People engage, try the new way, hope it sticks.
+
+**Phase 2 — Skepticism (3-5 changes):** People comply but hedge. "Let's see if this one lasts."
+
+**Phase 3 — Detachment (6+ changes without completion):** People stop investing in changes. Compliance is surface-level. New announcements get eye-rolls.
+
+**Phase 4 — Cynicism (entrenched fatigue):** People actively resist changes. "We've been here before." High performers leave because they don't want to work in a chaotic environment.
+
+### The change inventory audit
+
+**Run this before announcing any new change:**
+
+| Change | Status | Started | Expected complete |
+|--------|--------|---------|-----------------|
+| [Change 1] | In progress / Complete / Stalled | | |
+| [Change 2] | | | |
+| [Change 3] | | | |
+
+**Rules:**
+- If > 2 significant changes are in progress, don't start a third
+- If any change is stalled, diagnose it before starting something new
+- Define "complete" for every change in progress
+
+### Recovery from change fatigue
+
+1. **Declare a change moratorium.** "We're not starting anything new for 60 days. We're finishing what we started."
+2. **Complete visible wins.** Ship the changes that are 80% done. Demonstrate follow-through.
+3. **Communicate stability.** "Here's what is NOT changing this year."
+4. **Slow down the next announcement.** More preparation, more consultation, clearer "this time is different" evidence.
+
+---
+
+## 5. Measuring Adoption vs. Compliance
+
+Most change leaders measure go-live, not adoption. These are different things.
+
+### Adoption metrics by change type
+
+**Tool migration:**
+- % of team actively using the new tool (not just logged in)
+- % of relevant workflows completed in new tool vs. old tool
+- Support ticket volume in weeks 1-4 (high = knowledge gap; dropping = adoption)
+
+**Process change:**
+- % of relevant transactions following new process
+- Error rates in new process vs. old process (should converge over time)
+- Time-to-complete for new process (should improve by week 4)
+
+**Org change:**
+- Decision cycle time in new structure (should improve by month 2)
+- Escalation patterns (fewer cross-boundary escalations = alignment improving)
+- Employee sentiment (survey at months 1, 3, 6)
+
+**Culture change:**
+- Values referenced in 1:1 conversations (manager self-report)
+- Values-linked recognition events per month
+- Culture survey scores in relevant dimensions (quarterly)
+
+### The compliance trap
+
+Measuring compliance: "Did they use the new system? Yes/No."
+Measuring adoption: "Did they use the new system because it's better, or because they had to?"
+
+Compliance is unstable. It reverts when enforcement loosens. Adoption is self-sustaining.
+
+**Adoption diagnostic:** Ask a random sample: "Why do you use [new way] instead of [old way]?"
+- "Because I have to" = compliance
+- "Because it's faster/easier/better" = adoption
+
+Only adoption makes the change permanent.
diff --git a/skills/c-level-advisor/chief-of-staff/SKILL.md b/skills/c-level-advisor/chief-of-staff/SKILL.md
new file mode 100644
index 00000000..d4b77e41
--- /dev/null
+++ b/skills/c-level-advisor/chief-of-staff/SKILL.md
@@ -0,0 +1,179 @@
+---
+name: "chief-of-staff"
+description: "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: orchestration
+ updated: 2026-03-05
+ frameworks: routing-matrix, synthesis-framework, decision-log, board-protocol
+---
+
+# Chief of Staff
+
+The orchestration layer between founder and C-suite. Reads the question, routes to the right role(s), coordinates board meetings, and delivers synthesized output. Loads company context for every interaction.
+
+## Keywords
+chief of staff, orchestrator, routing, c-suite coordinator, board meeting, multi-agent, advisor coordination, decision log, synthesis
+
+---
+
+## Session Protocol (Every Interaction)
+
+1. Load company context via context-engine skill
+2. Score decision complexity
+3. Route to role(s) or trigger board meeting
+4. Synthesize output
+5. Log decision if reached
+
+---
+
+## Invocation Syntax
+
+```
+[INVOKE:role|question]
+```
+
+Examples:
+```
+[INVOKE:cfo|What's the right runway target given our growth rate?]
+[INVOKE:board|Should we raise a bridge or cut to profitability?]
+```
+
+### Loop Prevention Rules (CRITICAL)
+
+1. **Chief of Staff cannot invoke itself.**
+2. **Maximum depth: 2.** Chief of Staff → Role → stop.
+3. **Circular blocking.** A→B→A is blocked. Log it.
+4. **Board = depth 1.** Roles at board meeting do not invoke each other.
+
+If loop detected: return to founder with "The advisors are deadlocked. Here's where they disagree: [summary]."
+
+---
+
+## Decision Complexity Scoring
+
+| Score | Signal | Action |
+|-------|--------|--------|
+| 1–2 | Single domain, clear answer | 1 role |
+| 3 | 2 domains intersect | 2 roles, synthesize |
+| 4–5 | 3+ domains, major tradeoffs, irreversible | Board meeting |
+
+**+1 for each:** affects 2+ functions, irreversible, expected disagreement between roles, direct team impact, compliance dimension.
+
+---
+
+## Routing Matrix (Summary)
+
+Full rules in `references/routing-matrix.md`.
+
+| Topic | Primary | Secondary |
+|-------|---------|-----------|
+| Fundraising, burn, financial model | CFO | CEO |
+| Hiring, firing, culture, performance | CHRO | COO |
+| Product roadmap, prioritization | CPO | CTO |
+| Architecture, tech debt | CTO | CPO |
+| Revenue, sales, GTM, pricing | CRO | CFO |
+| Process, OKRs, execution | COO | CFO |
+| Security, compliance, risk | CISO | COO |
+| Company direction, investor relations | CEO | Board |
+| Market strategy, positioning | CMO | CRO |
+| M&A, pivots | CEO | Board |
+
+---
+
+## Board Meeting Protocol
+
+**Trigger:** Score ≥ 4, or multi-function irreversible decision.
+
+```
+BOARD MEETING: [Topic]
+Attendees: [Roles]
+Agenda: [2–3 specific questions]
+
+[INVOKE:role1|agenda question]
+[INVOKE:role2|agenda question]
+[INVOKE:role3|agenda question]
+
+[Chief of Staff synthesis]
+```
+
+**Rules:** Max 5 roles. Each role one turn, no back-and-forth. Chief of Staff synthesizes. Conflicts surfaced, not resolved — founder decides.
+
+---
+
+## Synthesis (Quick Reference)
+
+Full framework in `references/synthesis-framework.md`.
+
+1. **Extract themes** — what 2+ roles agree on independently
+2. **Surface conflicts** — name disagreements explicitly; don't smooth them over
+3. **Action items** — specific, owned, time-bound (max 5)
+4. **One decision point** — the single thing needing founder judgment
+
+**Output format:**
+```
+## What We Agree On
+[2–3 consensus themes]
+
+## The Disagreement
+[Named conflict + each side's reasoning + what it's really about]
+
+## Recommended Actions
+1. [Action] — [Owner] — [Timeline]
+...
+
+## Your Decision Point
+[One question. Two options with trade-offs. No recommendation — just clarity.]
+```
+
+---
+
+## Decision Log
+
+Track decisions to `~/.claude/decision-log.md`.
+
+```
+## Decision: [Name]
+Date: [YYYY-MM-DD]
+Question: [Original question]
+Decided: [What was decided]
+Owner: [Who executes]
+Review: [When to check back]
+```
+
+At session start: if a review date has passed, flag it: *"You decided [X] on [date]. Worth a check-in?"*
+
+---
+
+## Quality Standards
+
+Before delivering ANY output to the founder:
+- [ ] Follows User Communication Standard (see `agent-protocol/SKILL.md`)
+- [ ] Bottom line is first — no preamble, no process narration
+- [ ] Company context loaded (not generic advice)
+- [ ] Every finding has WHAT + WHY + HOW
+- [ ] Actions have owners and deadlines (no "we should consider")
+- [ ] Decisions framed as options with trade-offs and recommendation
+- [ ] Conflicts named, not smoothed
+- [ ] Risks are concrete (if X → Y happens, costs $Z)
+- [ ] No loops occurred
+- [ ] Max 5 bullets per section — overflow to reference
+
+---
+
+## Ecosystem Awareness
+
+The Chief of Staff routes to **28 skills total**:
+- **10 C-suite roles** — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor
+- **6 orchestration skills** — cs-onboard, context-engine, board-meeting, decision-logger, agent-protocol
+- **6 cross-cutting skills** — board-deck-builder, scenario-war-room, competitive-intel, org-health-diagnostic, ma-playbook, intl-expansion
+- **6 culture & collaboration skills** — culture-architect, company-os, founder-coach, strategic-alignment, change-management, internal-narrative
+
+See `references/routing-matrix.md` for complete trigger mapping.
+
+## References
+- `references/routing-matrix.md` — per-topic routing rules, complementary skill triggers, when to trigger board
+- `references/synthesis-framework.md` — full synthesis process, conflict types, output format
diff --git a/skills/c-level-advisor/chief-of-staff/references/routing-matrix.md b/skills/c-level-advisor/chief-of-staff/references/routing-matrix.md
new file mode 100644
index 00000000..2c94ac08
--- /dev/null
+++ b/skills/c-level-advisor/chief-of-staff/references/routing-matrix.md
@@ -0,0 +1,212 @@
+# Routing Matrix
+
+Detailed routing rules for the Chief of Staff. When a founder asks a question, find the best match in this matrix, then apply the scoring rules to determine single-role, multi-role, or board meeting.
+
+---
+
+## Routing by Domain
+
+### Finance & Capital
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| How much runway do we have? | CFO | — | 1 |
+| Should we raise now or later? | CFO | CEO | 3 |
+| What's our burn multiple? | CFO | COO | 2 |
+| Should we raise a bridge or cut costs? | CFO | CEO, COO | 5 |
+| What's the right pricing model? | CFO | CRO, CPO | 4 |
+| Should we hire or extend runway? | CFO | CHRO, COO | 4 |
+| What terms should we accept for this round? | CFO | CEO | 3 |
+| How do we model the next 18 months? | CFO | COO | 2 |
+
+### People & Culture
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| Should I let this person go? | CHRO | COO | 2 |
+| How do I structure comp for the team? | CHRO | CFO | 3 |
+| We have a culture problem — what do we do? | CHRO | CEO | 3 |
+| A leader on my team isn't working — now what? | CHRO | COO | 2 |
+| How do I hire fast without breaking culture? | CHRO | COO | 3 |
+| Two co-founders are in conflict | CHRO | CEO | 4 |
+| How do we retain our best people? | CHRO | CFO | 2 |
+| What does a good performance management process look like? | CHRO | COO | 2 |
+
+### Product
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| What should we build next? | CPO | CTO | 2 |
+| Should we kill this feature? | CPO | CTO, CRO | 3 |
+| How do we prioritize the roadmap? | CPO | CTO, COO | 3 |
+| Are we pre-PMF or post-PMF? | CPO | CRO, CEO | 4 |
+| Should we build vs buy? | CPO | CTO, CFO | 4 |
+| How do we handle technical debt vs new features? | CTO | CPO | 3 |
+| What's our product strategy for next year? | CPO | CEO, CRO | 4 |
+
+### Technology & Engineering
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| What architecture should we use? | CTO | CPO | 1 |
+| How do we scale the system to 10x traffic? | CTO | COO | 2 |
+| We have a security incident — what now? | CISO | CTO, COO | 5 |
+| Should we migrate to microservices? | CTO | COO, CFO | 4 |
+| How do I grow the engineering team? | CTO | CHRO, CFO | 3 |
+| Our engineering velocity is dropping — why? | CTO | COO | 2 |
+| What's our DevOps maturity? | CTO | COO | 1 |
+| How do we handle a compliance audit on our tech? | CISO | CTO | 3 |
+
+### Sales & Revenue
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| Why aren't we closing deals? | CRO | CPO | 2 |
+| How do we build a sales process from scratch? | CRO | COO | 2 |
+| What's the right GTM for this market? | CRO | CMO, CEO | 4 |
+| Our churn is too high — root cause? | CRO | CPO, CHRO | 3 |
+| Should we go enterprise or stay SMB? | CRO | CPO, CFO | 4 |
+| How do we expand into a new market? | CRO | CMO, CEO, CFO | 5 |
+| What's our ideal customer profile? | CRO | CPO, CMO | 3 |
+| Pipeline is dry — what do we do? | CRO | CMO | 2 |
+
+### Operations & Execution
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| Why do things keep breaking? | COO | CTO | 2 |
+| How do we set up OKRs? | COO | CEO | 2 |
+| Our meetings are useless — fix it | COO | — | 1 |
+| How do we scale operations without hiring? | COO | CTO, CFO | 3 |
+| There's a recurring bottleneck — how to fix it? | COO | CTO | 2 |
+| We need a cross-team process for X | COO | Relevant dept head | 2 |
+| How do we improve decision speed? | COO | CEO | 3 |
+
+### Marketing & Brand
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| How do we position against Competitor X? | CMO | CRO | 2 |
+| What channels should we invest in? | CMO | CRO, CFO | 3 |
+| Our brand isn't resonating — why? | CMO | CPO, CRO | 3 |
+| How do we build a content strategy? | CMO | CRO | 2 |
+| What's our marketing budget allocation? | CMO | CFO, CRO | 3 |
+
+### Security & Compliance
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| How do we pass an ISO 27001 audit? | CISO | COO | 2 |
+| We had a data breach — what now? | CISO | CTO, CEO, COO | 5 |
+| How do we handle GDPR compliance? | CISO | CTO | 2 |
+| What's our security posture? | CISO | CTO | 1 |
+| A regulator is asking questions | CISO | CEO, COO | 4 |
+
+### Strategic Direction
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| Should we pivot? | CEO | Board meeting | 5 |
+| Are we building the right company? | CEO | Board meeting | 5 |
+| How do we handle an acquisition offer? | CEO | CFO, Board meeting | 5 |
+| What's the 3-year strategy? | CEO | All C-suite, board | 5 |
+| Should we enter a new vertical? | CEO | CRO, CFO, CPO | 4 |
+
+---
+
+## When to Invoke Multiple Roles
+
+Invoke 2 roles when:
+- The question sits at the boundary of two domains
+- One role's answer creates a constraint the other needs to know about
+- The founder explicitly wants two perspectives
+
+Invoke 3+ roles (board) when:
+- The question involves irreversible resource commitment
+- There's a known tension between functions (e.g., product vs revenue, speed vs quality)
+- The answer will change how multiple teams operate
+- It's a company-direction question, not an operational one
+
+---
+
+## When NOT to Invoke Multiple Roles
+
+Don't multi-invoke when:
+- The answer is technical and one role clearly owns it
+- The founder just needs a framework, not a decision
+- Invoking more roles would add noise without adding signal
+- Time is short and a directional answer beats a comprehensive one
+
+---
+
+## Escalation Criteria → Board Meeting
+
+Automatically escalate to board meeting when any of these apply:
+
+1. **Irreversibility:** The decision is hard or impossible to reverse (layoffs, pivots, major contracts, fundraising terms)
+2. **Cross-functional resource impact:** The decision changes budget, headcount, or priorities for 2+ teams
+3. **Founder blind spot risk:** The topic is in an area where the founder's archetype creates a known gap (e.g., technical founder on GTM)
+4. **Disagreement expected:** The domains involved are known to have competing incentives (CFO vs CRO on pricing, CTO vs CPO on tech debt)
+5. **Explicit request:** Founder says "what does the team think" or "I want multiple perspectives"
+6. **Score ≥ 4**
+
+---
+
+## Role Registry
+
+| Role | File | Domain |
+|------|------|--------|
+| CEO | ceo-advisor | Strategy, culture, investor relations |
+| CFO | cfo-advisor | Finance, capital, unit economics |
+| COO | coo-advisor | Operations, OKRs, scaling |
+| CTO | cto-advisor | Engineering, architecture, tech strategy |
+| CPO | cpo-advisor | Product, roadmap, UX |
+| CRO | cro-advisor | Revenue, sales, GTM |
+| CMO | cmo-advisor | Marketing, brand, positioning |
+| CHRO | chro-advisor | People, culture, hiring |
+| CISO | ciso-advisor | Security, compliance, risk |
+
+**If a role file doesn't exist:** Note the gap. Answer from first principles with domain expertise. Log that the role is missing.
+
+---
+
+## Complementary Skills Registry
+
+These skills are invoked for specific cross-cutting needs, not for general domain questions.
+
+### Orchestration & Infrastructure
+| Skill | Trigger | File |
+|-------|---------|------|
+| C-Suite Onboard | `/cs:setup`, first-time setup, "tell me about your company" | cs-onboard |
+| Context Engine | Auto-loaded; staleness check | context-engine |
+| Board Meeting | `/cs:board`, multi-role decisions, score ≥ 4 | board-meeting |
+| Decision Logger | After board meetings, `/cs:decisions`, `/cs:review` | decision-logger |
+| Agent Protocol | Inter-role invocations, loop detection | agent-protocol |
+
+### Cross-Cutting Capabilities
+| Skill | Trigger | File |
+|-------|---------|------|
+| Board Deck Builder | "board deck", "investor update", "board presentation" | board-deck-builder |
+| Scenario War Room | "what if", multi-variable scenarios, stress test across functions | scenario-war-room |
+| Competitive Intelligence | "competitor", "competitive analysis", "battlecard", "who's winning" | competitive-intel |
+| Org Health Diagnostic | "how healthy are we", "org health", "company health check" | org-health-diagnostic |
+| M&A Playbook | "acquisition", "M&A", "due diligence", "being acquired" | ma-playbook |
+| International Expansion | "expand to", "new market", "international", "localization" | intl-expansion |
+
+### Culture & Collaboration
+| Skill | Trigger | File |
+|-------|---------|------|
+| Culture Architect | "values", "culture", "mission", "vision", culture problems | culture-architect |
+| Company OS | "operating system", "EOS", "Scaling Up", "meeting cadence", "how do we run" | company-os |
+| Founder Coach | "delegation", "blind spots", "founder growth", "leadership style", burnout | founder-coach |
+| Strategic Alignment | "alignment", "silos", "teams not aligned", "strategy cascade" | strategic-alignment |
+| Change Management | "rolling out", "reorg", "change", "new process", "transition" | change-management |
+| Internal Narrative | "all-hands", "internal comms", "how do we tell", "narrative" | internal-narrative |
+
+### Routing Priority
+
+1. Check if it matches a **complementary skill trigger** → route there
+2. Check if it matches a **single role domain** → route to that role
+3. Check if it spans **multiple role domains** (score ≥ 3) → invoke multiple roles
+4. Check if it meets **escalation criteria** (score ≥ 4 or irreversible) → trigger board meeting
+5. If unclear → ask one clarifying question, then route
diff --git a/skills/c-level-advisor/chief-of-staff/references/synthesis-framework.md b/skills/c-level-advisor/chief-of-staff/references/synthesis-framework.md
new file mode 100644
index 00000000..51d9e720
--- /dev/null
+++ b/skills/c-level-advisor/chief-of-staff/references/synthesis-framework.md
@@ -0,0 +1,201 @@
+# Synthesis Framework
+
+How to turn multiple role outputs into a single, useful response for the founder. Synthesis is the highest-value function of the Chief of Staff — it's not about summarizing, it's about integrating.
+
+---
+
+## The Problem with Multi-Role Output
+
+Without synthesis, multiple advisors produce noise:
+- Overlapping advice
+- Contradictions without resolution
+- Action items from every role that compete for priority
+- Founder left to figure out what to do with it all
+
+Synthesis turns this into signal: one clear picture, explicit conflicts named, prioritized actions, one decision point.
+
+---
+
+## Phase 1: Collect and Read
+
+Before writing anything, read all role responses completely. Look for:
+
+**Consensus signals:**
+- Same recommendation from 2+ roles independently
+- Same risk identified from different angles
+- Same root cause named without coordination
+
+**Conflict signals:**
+- One role says X, another says not-X
+- Same data interpreted differently
+- Competing resource requests (CFO says cut costs, CRO says invest in sales)
+- Different time horizons (CTO wants to fix tech debt now, CPO wants to ship features now)
+
+**Gap signals:**
+- A critical dimension no role addressed
+- A risk nobody flagged
+- An assumption baked in that nobody questioned
+
+---
+
+## Phase 2: Extract Themes
+
+A theme is a finding that appears in 2+ role responses, even if framed differently.
+
+**How to identify:**
+1. List every distinct point from every role response
+2. Group points that are about the same underlying issue
+3. Name the group with a clear, plain-language label
+4. Note which roles contributed to it
+
+**Example:**
+> CFO: "The burn multiple is 3.2 — unsustainable without revenue acceleration."
+> CRO: "We need 3 more sales cycles to hit targets, minimum 90 days."
+> COO: "Three positions are open that will cost $40K/month when filled."
+>
+> Theme: **Cash position is tighter than the headline number suggests.** (CFO + CRO + COO)
+
+**Limit to 3 themes.** More than 3 means you're not synthesizing — you're listing.
+
+---
+
+## Phase 3: Surface Conflicts
+
+Name every conflict explicitly. Don't resolve it — present it.
+
+**Conflict types:**
+
+### Resource conflict
+Two roles want the same budget, headcount, or time.
+> "CFO wants to delay the new hire until Q3. CHRO says the team is already at capacity and another quarter will cause attrition. Both are right from their domain."
+
+### Priority conflict
+Two roles disagree on what's most important right now.
+> "CTO wants 6 weeks on infrastructure to prevent outages. CPO wants those same engineers on the new feature for the sales pipeline. This isn't a technical question — it's a risk tolerance question."
+
+### Time horizon conflict
+Two roles are optimizing for different time frames.
+> "CRO is optimizing for this quarter's close rate. CMO is optimizing for brand that compounds over 18 months. Both strategies are valid. They require different budget allocations."
+
+### Assumption conflict
+Two roles have incompatible assumptions baked in.
+> "CFO's model assumes 15% MoM growth. CRO says realistic growth is 8% given the sales cycle length. The financial model needs to be rebuilt on the CRO's number."
+
+**Present conflicts without picking sides.** The founder decides which trade-off to accept.
+
+---
+
+## Phase 4: Derive Action Items
+
+From the consensus themes and the non-conflicting role outputs, derive concrete actions.
+
+**Action item criteria:**
+- Specific (not "improve the process" — "map the QA process and find the bottleneck")
+- Owned (assign to a role or person)
+- Time-bound (this week / this quarter / before next board)
+- Consequence-linked (why does it matter if it slips)
+
+**Good example:**
+> **Action:** Build an updated 18-month financial model using CRO's 8% MoM growth assumption.
+> **Owner:** CFO
+> **By:** End of week
+> **Why it matters:** Current fundraising conversations are based on a model that's too optimistic.
+
+**Bad example:**
+> Review the financial model with the team.
+
+**Limit to 5 actions.** If there are more, prioritize by impact and flag the rest as backlog.
+
+---
+
+## Phase 5: Identify the Founder Decision Point
+
+Every board meeting ends with one question for the founder. Just one.
+
+**How to find it:**
+- It's usually the conflict that can't be resolved without a values choice
+- It's the question where both sides have a legitimate case
+- It's the thing none of the advisors can decide unilaterally
+
+**Frame it cleanly:**
+> "The C-suite is aligned on the actions above, but there's one thing that needs your call: [specific decision]. [Role A] recommends X because [reason]. [Role B] recommends Y because [reason]. This is ultimately a question of [underlying trade-off — growth vs profitability / speed vs stability / short-term vs long-term]."
+
+**Don't present multiple decision points.** Force the synthesis down to one. If there are genuinely two unrelated decisions, separate them into two outputs.
+
+---
+
+## Output Format
+
+```markdown
+## [Topic] — C-Suite Synthesis
+
+### What We Agree On
+[Theme 1 with 1–2 sentences]
+[Theme 2 with 1–2 sentences]
+[Theme 3 with 1–2 sentences]
+
+### The Disagreement
+[Name the conflict]
+[Role A position + reasoning]
+[Role B position + reasoning]
+[What the conflict is really about]
+
+### Recommended Actions
+1. **[Action]** — [Owner] — [Timeline] — [Why it matters]
+2. **[Action]** — [Owner] — [Timeline]
+3. **[Action]** — [Owner] — [Timeline]
+4. **[Action]** — [Owner] — [Timeline]
+5. **[Action]** — [Owner] — [Timeline]
+
+### Your Decision Point
+[One question for the founder. Two options with their trade-offs. No recommendation — just clarity.]
+```
+
+---
+
+## Quality Standards for Synthesis
+
+Before delivering:
+
+**Compression test:** Could a founder read this in 3 minutes and know exactly what to do? If not, cut.
+
+**Honesty test:** Did you name the real conflicts, or smooth them over? Smoothed conflicts come back as surprises.
+
+**Specificity test:** Are the action items specific enough to act on, or are they goals masquerading as actions?
+
+**Decision point test:** Is there one clear thing for the founder to decide, or are you leaving them with a mess?
+
+**Context test:** Would this advice make sense for any company, or is it clearly calibrated to this company's stage, challenges, and founder?
+
+---
+
+## Common Synthesis Failures
+
+**The summary trap:** You summarize each role's output in sequence. This is not synthesis — it's transcription. Synthesis requires cutting.
+
+**The false consensus:** You say "the team agrees" when there's actually a meaningful conflict. Named conflicts are useful. Hidden conflicts are dangerous.
+
+**The advice avalanche:** 15 action items that no one can action. Cut to 5. If everything is priority, nothing is.
+
+**The unresolved conflict dump:** You present the conflict and then leave the founder to figure it out. Your job is to frame the choice cleanly, not to resolve it — but also not to dump it raw.
+
+**The context-free advice:** The synthesis sounds like it came from a textbook, not from someone who knows this company. If you can swap the company name and it still reads the same, it's not synthesized.
+
+---
+
+## When Synthesis Reveals Deadlock
+
+Sometimes roles genuinely can't align and the synthesis produces no clear direction.
+
+**Signs of deadlock:**
+- Every theme has a counter-theme
+- Every action has a conflict attached
+- The "decision point" is actually three decisions
+
+**What to do:**
+1. Name the deadlock explicitly: *"The C-suite is genuinely split on this. Here's why."*
+2. Present the two paths cleanly with consequences
+3. Recommend a time-boxed experiment if possible: *"You don't have to decide between X and Y permanently. Run X for 30 days with a clear metric for success, then reassess."*
+4. Flag it as a strategic question that may need external input (advisor, board, market data)
+
+Deadlock is honest. Fake consensus is not.
diff --git a/skills/c-level-advisor/chro-advisor/SKILL.md b/skills/c-level-advisor/chro-advisor/SKILL.md
new file mode 100644
index 00000000..a846122d
--- /dev/null
+++ b/skills/c-level-advisor/chro-advisor/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: "chro-advisor"
+description: "People leadership for scaling companies. Hiring strategy, compensation design, org structure, culture, and retention. Use when building hiring plans, designing comp frameworks, restructuring teams, managing performance, building culture, or when user mentions CHRO, HR, people strategy, talent, headcount, compensation, org design, retention, or performance management."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: chro-leadership
+ updated: 2026-03-05
+ python-tools: hiring_plan_modeler.py, comp_benchmarker.py
+ frameworks: people-strategy, comp-frameworks, org-design
+---
+
+# CHRO Advisor
+
+People strategy and operational HR frameworks for business-aligned hiring, compensation, org design, and culture that scales.
+
+## Keywords
+CHRO, chief people officer, CPO, HR, human resources, people strategy, hiring plan, headcount planning, talent acquisition, recruiting, compensation, salary bands, equity, org design, organizational design, career ladder, title framework, retention, performance management, culture, engagement, remote work, hybrid, spans of control, succession planning, attrition
+
+## Quick Start
+
+```bash
+python scripts/hiring_plan_modeler.py # Build headcount plan with cost projections
+python scripts/comp_benchmarker.py # Benchmark salaries and model total comp
+```
+
+## Core Responsibilities
+
+### 1. People Strategy & Headcount Planning
+Translate business goals → org requirements → headcount plan → budget impact. Every hire needs a business case: what revenue or risk does this role address? See `references/people_strategy.md` for hiring at each growth stage.
+
+### 2. Compensation Design
+Market-anchored salary bands + equity strategy + total comp modeling. See `references/comp_frameworks.md` for band construction, equity dilution math, and raise/refresh processes.
+
+### 3. Org Design
+Right structure for the stage. Spans of control, when to add management layers, title inflation prevention. See `references/org_design.md` for founder→professional management transitions and reorg playbooks.
+
+### 4. Retention & Performance
+Retention starts at hire. Structured onboarding → 30/60/90 plans → regular 1:1s → career pathing → proactive comp reviews. See `references/people_strategy.md` for what actually moves the needle.
+
+**Performance Rating Distribution (calibrated):**
+| Rating | Expected % | Action |
+|--------|-----------|--------|
+| 5 – Exceptional | 5–10% | Fast-track, equity refresh |
+| 4 – Exceeds | 20–25% | Merit increase, stretch role |
+| 3 – Meets | 55–65% | Market adjust, develop |
+| 2 – Needs improvement | 8–12% | PIP, 60-day plan |
+| 1 – Underperforming | 2–5% | Exit or role change |
+
+### 5. Culture & Engagement
+Culture is behavior, not values on a wall. Measure eNPS quarterly. Act on results within 30 days or don't ask.
+
+## Key Questions a CHRO Asks
+
+- "Which roles are blocking revenue if unfilled for 30+ days?"
+- "What's our regrettable attrition rate? Who left that we wish hadn't?"
+- "Are managers our retention asset or our attrition cause?"
+- "Can a new hire explain their career path in 12 months?"
+- "Where are we paying below P50? Who's a flight risk because of it?"
+- "What's the cost of this hire vs. the cost of not hiring?"
+
+## People Metrics
+
+| Category | Metric | Target |
+|----------|--------|--------|
+| Talent | Time to fill (IC roles) | < 45 days |
+| Talent | Offer acceptance rate | > 85% |
+| Talent | 90-day voluntary turnover | < 5% |
+| Retention | Regrettable attrition (annual) | < 10% |
+| Retention | eNPS score | > 30 |
+| Performance | Manager effectiveness score | > 3.8/5 |
+| Comp | % employees within band | > 90% |
+| Comp | Compa-ratio (avg) | 0.95–1.05 |
+| Org | Span of control (ICs) | 6–10 |
+| Org | Span of control (managers) | 4–7 |
+
+## Red Flags
+
+- Attrition spikes and exit interviews all name the same manager
+- Comp bands haven't been refreshed in 18+ months
+- No career ladder → top performers leave after 18 months
+- Hiring without a written business case or job scorecard
+- Performance reviews happen once a year with no mid-year check-in
+- Equity refreshes only for executives, not high performers
+- Time to fill > 90 days for critical roles
+- eNPS below 0 — something is structurally broken
+- More than 3 org layers between IC and CEO at < 50 people
+
+## Integration with Other C-Suite Roles
+
+| When... | CHRO works with... | To... |
+|---------|-------------------|-------|
+| Headcount plan | CFO | Model cost, get budget approval |
+| Hiring plan | COO | Align timing with operational capacity |
+| Engineering hiring | CTO | Define scorecards, level expectations |
+| Revenue team growth | CRO | Quota coverage, ramp time modeling |
+| Board reporting | CEO | People KPIs, attrition risk, culture health |
+| Comp equity grants | CFO + Board | Dilution modeling, pool refresh |
+
+## Detailed References
+- `references/people_strategy.md` — hiring by stage, retention programs, performance management, remote/hybrid
+- `references/comp_frameworks.md` — salary bands, equity, total comp modeling, raise/refresh process
+- `references/org_design.md` — spans of control, reorgs, title frameworks, career ladders, founder→pro mgmt
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Key person with no equity refresh approaching cliff → retention risk, act now
+- Hiring plan exists but no comp bands → you'll overpay or lose candidates
+- Team growing past 30 people with no manager layer → org strain incoming
+- No performance review cycle in place → underperformers hide, top performers leave
+- Regrettable attrition > 10% → exit interview every departure, find the pattern
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Build a hiring plan" | Headcount plan with roles, timing, cost, and ramp model |
+| "Set up comp bands" | Compensation framework with bands, equity, benchmarks |
+| "Design our org" | Org chart proposal with spans, layers, and transition plan |
+| "We're losing people" | Retention analysis with risk scores and intervention plan |
+| "People board section" | Headcount, attrition, hiring velocity, engagement, risks |
+
+## Reasoning Technique: Empathy + Data
+
+Start with the human impact, then validate with metrics. Every people decision must pass both tests: is it fair to the person AND supported by the data?
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/c-level-advisor/chro-advisor/references/comp_frameworks.md b/skills/c-level-advisor/chro-advisor/references/comp_frameworks.md
new file mode 100644
index 00000000..43cabf5d
--- /dev/null
+++ b/skills/c-level-advisor/chro-advisor/references/comp_frameworks.md
@@ -0,0 +1,320 @@
+# Compensation Frameworks Reference
+
+Salary bands, equity design, total comp modeling, comp philosophy, and raise/refresh processes.
+
+---
+
+## Comp Philosophy — The Foundation
+
+Before building bands, define your philosophy. Ambiguity in comp philosophy = pay equity lawsuits and trust erosion.
+
+**The five decisions:**
+
+### 1. What market percentile do you target?
+- **P25 (below market):** Only viable with exceptional mission, equity, or growth opportunity. Flight risk is high after 18 months.
+- **P50 (market median):** Standard for most Series A–B companies. Competitive without premium.
+- **P75 (above market):** Premium talent strategy. Used by high-margin or talent-intensive businesses. Netflix model.
+- **P90+:** Top-of-market for specific functions (ML at AI companies, senior engineers at FAANG feeders).
+
+**Common hybrid:** P50 base + above-market equity = total comp at P65–75.
+
+### 2. What's in your total comp package?
+Define each component explicitly:
+- **Base salary** — cash, market-benchmarked
+- **Variable / bonus** — % of base, tied to what criteria
+- **Equity** — options vs. RSUs, vesting schedule, refresh cadence
+- **Benefits** — health, retirement, PTO policy
+- **Learning & development budget**
+- **Remote/location allowances**
+
+### 3. Are bands public internally?
+Recommended: Yes. Pay transparency reduces equity complaints, builds trust, and forces you to maintain clean bands.
+
+### 4. How often do you refresh bands?
+Minimum: annually. High-growth markets: every 6 months (engineering specifically in hot markets).
+
+### 5. How do you handle individual negotiation?
+Options:
+- **Fixed bands, no negotiation** (Buffer model) — simple, fair, loses some candidates
+- **Band range with manager discretion** — most common, requires calibration guardrails
+- **Individual negotiation within band** — flexible, creates pay equity drift over time
+
+---
+
+## Salary Bands: Construction
+
+### Step 1: Define levels
+
+Standard IC levels (adapt to company):
+| Level | Title example | Scope |
+|-------|--------------|-------|
+| L1 | Junior / Associate | Execution with guidance |
+| L2 | Mid-level | Independent execution |
+| L3 | Senior | Leads workstreams, mentors L1-L2 |
+| L4 | Staff / Principal | Cross-team technical leadership |
+| L5 | Distinguished / Fellow | Company-wide technical direction |
+
+Management track:
+| Level | Title | Scope |
+|-------|-------|-------|
+| M1 | Manager | Team of 4–8 ICs |
+| M2 | Senior Manager | Manager of managers or larger team |
+| M3 | Director | Function or large org |
+| M4 | VP | Business unit, company-wide |
+| M5 | SVP / C-Suite | Executive |
+
+### Step 2: Gather market data
+
+**Data sources (by quality):**
+1. **Radford / Aon** — Gold standard. Expensive ($10K+/year). Worth it at Series B+.
+2. **Levels.fyi** — Excellent for engineering. Free. Self-reported but large sample.
+3. **Glassdoor Salary** — Broad coverage. Less precise for startups.
+4. **Pave / Carta Total Comp** — VC-backed companies. Good peer benchmarking.
+5. **LinkedIn Salary** — Free tier. Reasonable signal for G&A roles.
+6. **Offer letter data** — What candidates are bringing from other companies. Real-time signal.
+
+**What to pull:** P25, P50, P75, P90 for each role × level × geography.
+
+### Step 3: Set band structure
+
+**Band width (range within a level):**
+- IC bands: 80–120% of midpoint (i.e., ±20% from center)
+- Manager bands: 85–115% of midpoint
+- Wider bands allow room for differentiation within level; narrower bands reduce pay equity drift
+
+**Band overlap between levels:**
+- 10–20% overlap is normal (top of L2 overlaps with bottom of L3)
+- > 30% overlap: your levels are too close together
+- No overlap: new hires jump too much between levels (compression risk)
+
+**Example engineering band structure (US, Series B company, P50 target):**
+
+| Level | Band Min | Midpoint | Band Max |
+|-------|----------|----------|----------|
+| L1 Software Engineer | $90K | $105K | $125K |
+| L2 Software Engineer | $115K | $135K | $160K |
+| L3 Senior SWE | $150K | $175K | $205K |
+| L4 Staff SWE | $195K | $225K $260K |
+| M1 Eng Manager | $175K | $205K | $235K |
+| M2 Sr Eng Manager | $215K | $250K | $285K |
+| M3 Director, Eng | $255K | $300K | $345K |
+
+*Adjust by 15–25% for non-SF/NYC markets. Adjust -40% to -60% for European markets.*
+
+### Step 4: Place employees in bands
+
+**Compa-ratio** = Employee salary / Band midpoint
+
+| Compa-ratio | Interpretation |
+|------------|---------------|
+| < 0.85 | Below range — immediate risk |
+| 0.85–0.95 | Developing in role |
+| 0.95–1.05 | Fully performing (target zone) |
+| 1.05–1.15 | Senior/expert in role |
+| > 1.15 | Above range — flag for review |
+
+**Audit report:** Run quarterly. Flag anyone below 0.85 (flight risk) or above 1.15 (overpaid for level, or needs promotion).
+
+---
+
+## Equity Frameworks for Startups
+
+### Option Basics
+
+**ISO vs NSO:**
+- ISO (Incentive Stock Options): For employees. Favorable tax treatment if held 1+ year post-exercise.
+- NSO (Non-Qualified Stock Options): For advisors, contractors, sometimes employees. Taxed as ordinary income on exercise.
+
+**Strike price:** Set to 409A valuation at grant. Lower is better for employees. Early employees win on strike price.
+
+**Vesting schedule standards:**
+- 4-year vest, 1-year cliff: Standard
+- 4-year vest, 6-month cliff: Startup market adapting to faster pace
+- 1-year cliff means: nothing until 12 months; monthly or quarterly after
+
+**Post-termination exercise window (PTEW):**
+- Standard: 90 days. Often too short for employees who can't afford exercise.
+- Better: 1–5 years or until IPO. Use as a talent differentiator.
+- Companies extending PTEW: Stripe, Airbnb (pre-IPO), Square, most employee-friendly startups.
+
+### Equity Grant Ranges by Stage and Level
+
+*Expressed as % of fully diluted shares at grant. Ranges vary significantly by market, stage, and funding.*
+
+**Seed stage:**
+| Role | Equity % |
+|------|----------|
+| Co-founder | 20–40% |
+| First engineering hire | 0.5–1.5% |
+| First non-technical exec hire | 0.25–0.75% |
+| IC (L2-L3) | 0.1–0.4% |
+| IC (L3-L4) | 0.2–0.6% |
+
+**Series A:**
+| Role | Equity % |
+|------|----------|
+| VP / Head of function | 0.3–0.75% |
+| Director | 0.1–0.3% |
+| Senior IC (L3) | 0.05–0.15% |
+| Mid IC (L2) | 0.02–0.08% |
+| Junior IC (L1) | 0.01–0.05% |
+
+**Series B:**
+| Role | Equity % |
+|------|----------|
+| VP / Head of function | 0.1–0.3% |
+| Director | 0.05–0.15% |
+| Senior IC (L3) | 0.02–0.07% |
+| Mid IC (L2) | 0.01–0.03% |
+
+*At Series B+, equity is increasingly expressed in dollar value (grant value = X shares × current 409A). Use Carta or Pulley to model dilution.*
+
+### Equity Refresh Program
+
+**Why it matters:** Employees hired at Series A with 4-year vesting will be fully vested by Series B. No unvested equity = no retention hook.
+
+**When to refresh:**
+- After every significant funding round
+- Annually for high performers (top 20%)
+- After promotion (role-commensurate top-up)
+- Counter-offer situations (use carefully — signals you underpaid initially)
+
+**Refresh models:**
+1. **Anniversary grant:** Annual cliff-free refresh for all employees above a performance threshold
+2. **Evergreen model:** Continuous vesting maintained — refresh annually so employee always has 2–3 years remaining
+3. **Event-based:** Refresh tied to milestones (promotion, funding, annual review cycle)
+
+**Dilution awareness:** Every refresh dilutes existing shareholders. Model pool usage quarterly. Replenish option pool before it drops below 10–12% of fully diluted shares.
+
+---
+
+## Total Comp Modeling
+
+### Components of Total Comp
+
+```
+Total Compensation = Base Salary
+ + Annual Bonus (target %)
+ + Equity Value (annualized grant / vesting period)
+ + Benefits (employer-paid premiums, retirement match)
+ + Allowances (home office, internet, L&D, commuter)
+```
+
+### Annualizing Equity Value
+
+For comparison to cash compensation:
+
+```
+Annual equity value = (Grant shares × Current 409A price) / Vesting years
+```
+
+Example: 10,000 options at $2 strike, current 409A = $8, 4-year vest
+- Grant value at current 409A = 10,000 × $8 = $80,000
+- Annual value = $80,000 / 4 = $20,000/year
+- If base is $150K, total comp is ~$170K/year
+
+*Note: For recruiting purposes, you can use last preferred share price (VC price) to show upside — but be transparent about the difference between 409A and preferred.*
+
+### Benefits Valuation
+
+Frequently undervalued in offers. Quantify explicitly:
+| Benefit | Typical employer cost |
+|---------|----------------------|
+| Health insurance (employee) | $4K–8K/year |
+| Health insurance (family) | $15K–25K/year |
+| 401K match (4% of salary) | $5K–10K/year |
+| L&D budget ($2K/year) | $2K/year |
+| Home office stipend ($500) | $500/year |
+
+A $140K offer with family health coverage + 4% 401K match is worth $165K+ total.
+
+---
+
+## Raise and Refresh Process
+
+### Annual Compensation Review Cycle
+
+**Recommended cadence:**
+- October/November: Market data refresh, band updates
+- November/December: Manager merit recommendations
+- December/January: Calibration and approvals
+- January/February: Effective date for new salaries + equity grants
+
+**Budget allocation:**
+- **Merit budget** (performance-based raises): 3–5% of total payroll typically
+- **Market adjustment budget** (fixing below-band salaries): Separate from merit. Non-negotiable to avoid attrition.
+- **Promotion budget:** Separate. Promotions should not come from merit pool.
+
+### Merit Increase Guidelines
+
+| Performance Rating | Merit Increase Range |
+|-------------------|---------------------|
+| 5 – Exceptional | 8–15% |
+| 4 – Exceeds | 5–8% |
+| 3 – Meets | 2–4% |
+| 2 – Needs improvement | 0–1% |
+| 1 – Underperforming | 0% (PIP active) |
+
+*Adjust based on compa-ratio. A high performer at P90 of their band gets a smaller increase than a high performer at P50.*
+
+### Compa-Ratio Adjustment Matrix
+
+| Performance \ Compa-Ratio | < 0.90 | 0.90–1.00 | 1.00–1.10 | > 1.10 |
+|---------------------------|--------|-----------|-----------|--------|
+| Exceptional (5) | 12–15% | 8–12% | 5–8% | 3–5% |
+| Exceeds (4) | 8–12% | 5–8% | 3–5% | 1–3% |
+| Meets (3) | 5–8% | 3–5% | 2–3% | 0–2% |
+| Needs impr (2) | 0–2% | 0–1% | 0% | 0% |
+
+### Promotion vs. Merit — Keep These Separate
+
+**Common mistake:** Using merit budget to fund promotions. This forces a choice between rewarding performance and recognizing level change.
+
+**Promotion increase guidelines:**
+- One level (e.g., L2 → L3): 10–20% increase, new equity grant
+- Two levels (rare): 20–35% increase, new equity grant at new level
+- Manager track (IC → M1): 15–25% increase, new equity grant
+
+**Promotion criteria process:**
+1. Manager nominates with written business case
+2. Calibration committee reviews cross-functionally
+3. HR validates against band (no off-band exceptions without CHRO sign-off)
+4. Employee informed before annual review — never surprised at review meeting
+
+### Off-Cycle Adjustments
+
+When to do them:
+- Counter-offer situations (see below)
+- Competitive intelligence reveals underpay for a specific role
+- New market data shows a role significantly under-benchmarked
+- Internal equity audit reveals unexplained gaps
+
+**Counter-offer policy:**
+Three options:
+1. **Match** — Risk: signals you underpay; sets precedent
+2. **Partial match** — "We can do X, which is the top of your band" — cleaner
+3. **Decline** — Accept the attrition, improve the band for the next hire
+
+**Rule:** If you're regularly in counter-offer conversations, your bands are stale. Fix the bands.
+
+---
+
+## Pay Equity Audit
+
+Run annually. Non-negotiable at Series B+.
+
+**What to audit:**
+- Pay gap by gender within each level and function
+- Pay gap by ethnicity within each level and function
+- Compa-ratio distribution across demographics
+- Time-to-promotion by demographic group
+
+**Methodology:**
+1. Pull all employee data: level, function, salary, tenure, performance ratings, gender, ethnicity
+2. Run regression controlling for level, tenure, and performance
+3. Unexplained gap after controls = the problem to fix
+4. Flag and remediate within the same review cycle
+
+**Legal exposure:** In many jurisdictions, documented pay gaps without remediation plans are litigation risk. The audit creates a record of intent; remediation closes the risk.
+
+**Remediation budget:** Set aside 0.5–1% of payroll annually for equity adjustments. If you're doing it right, this shrinks over time.
diff --git a/skills/c-level-advisor/chro-advisor/references/org_design.md b/skills/c-level-advisor/chro-advisor/references/org_design.md
new file mode 100644
index 00000000..02498b54
--- /dev/null
+++ b/skills/c-level-advisor/chro-advisor/references/org_design.md
@@ -0,0 +1,333 @@
+# Org Design Reference
+
+Spans of control, layering decisions, reorgs, title frameworks, career ladders, and the founder→professional management transition.
+
+---
+
+## Core Org Design Principles
+
+1. **Structure follows strategy.** Reorg after strategy shifts, not before.
+2. **Optimize for the bottleneck.** Where does work get slow? Design around that.
+3. **Minimize coordination cost.** Conway's Law: your org structure becomes your product architecture. Design intentionally.
+4. **Bias toward flatness until it breaks.** Adding layers adds cost and slows decisions.
+5. **Reorgs have transition costs.** Relationships reset. Count the cost before you restructure.
+
+---
+
+## Spans of Control
+
+Span of control = number of direct reports a manager has.
+
+### Benchmarks
+
+| Role Type | Optimal Span | Min | Max |
+|-----------|-------------|-----|-----|
+| IC manager (predictable work) | 7–10 | 5 | 12 |
+| IC manager (complex/creative work) | 5–7 | 4 | 8 |
+| Manager of managers | 4–6 | 3 | 7 |
+| VP / Director | 4–7 | 3 | 8 |
+| C-Suite | 5–9 | 4 | 10 |
+
+**Too narrow (< 4 ICs):** Over-management, high cost per output, manager becomes a bottleneck
+**Too wide (> 12 ICs):** Under-management, degraded 1:1 quality, feedback loops collapse
+
+### Factors that allow wider spans
+- Highly autonomous, senior team (L3+ ICs)
+- Predictable, well-defined work (support, ops)
+- Strong tooling and process (reduces manager overhead)
+- Experienced manager
+
+### Factors that require narrower spans
+- High-complexity, undefined problems (research, early product)
+- Junior or newly promoted team members
+- High interdependence between reports (coordination overhead)
+- Manager is also an IC contributor (player-coach)
+
+---
+
+## When to Add Management Layers
+
+**The wrong reason to add layers:** "We need to give good people somewhere to grow."
+**The right reason:** "This manager has too many direct reports to do the job well."
+
+### Layer triggers by growth stage
+
+**0 → 15 people:** No layers. Everyone reports to founders.
+
+**15 → 30 people:** First managers emerge. Usually technical leads or function leads. Should still be player-coaches.
+
+**30 → 60 people:** Second layer forms. Engineering splits into squads. Sales gets a frontline manager. Each function has a head.
+
+**60 → 150 people:** Director layer becomes necessary in large functions. Engineering VP + Engineering Directors + Team Managers.
+
+**150+ people:** VP layer fully staffed. Senior Director / Director split. Clear IC → M → Senior M → Director → VP paths.
+
+### The Rule of 7
+
+When any manager has 7 or more direct reports and:
+- 1:1s are skipped regularly
+- Feedback quality drops
+- Manager can't answer "how is each person doing?" without checking notes
+
+→ Time to split or hire a manager.
+
+### Management overhead cost
+
+Every manager layer costs 10–15% in decision speed (communication hops).
+Every management role without a team = pure overhead.
+
+**Litmus test for each management role:**
+- Does this person have at least 4 ICs under them?
+- Would removing this role improve decision speed?
+- Is this a management job or a "we ran out of IC levels" job?
+
+---
+
+## Functional vs. Product Org Structures
+
+### Functional Structure (by discipline)
+
+```
+CEO
+├── VP Engineering
+│ ├── Backend Team
+│ ├── Frontend Team
+│ └── DevOps
+├── VP Product
+│ ├── PM (Feature A)
+│ └── PM (Feature B)
+└── VP Design
+ └── UX Designers
+```
+
+**Best for:** Early stage, < 100 people, single product
+**Advantage:** Deep expertise development, clear career paths per discipline
+**Disadvantage:** Cross-functional coordination is heavy; features require synchronization across silos
+
+### Product/Pod Structure (by product area)
+
+```
+CEO
+├── Product Area A (autonomous team)
+│ ├── EM
+│ ├── PM
+│ └── Designer
+├── Product Area B (autonomous team)
+│ ├── EM
+│ ├── PM
+│ └── Designer
+└── Platform (shared services)
+ └── Platform EM + team
+```
+
+**Best for:** Multiple products or large user segments, 50+ in product/eng
+**Advantage:** Speed and autonomy; less cross-team coordination for most features
+**Disadvantage:** Duplication risk; harder to maintain technical coherence; harder career paths
+
+### When to shift from Functional → Product org
+- You have 2+ distinct product lines that rarely share features
+- Cross-functional feature delivery takes > 3 sprints of coordination overhead
+- Teams are > 8 engineers and still waiting on shared resources
+
+### Hybrid / Matrix (avoid unless necessary)
+Matrix reporting (e.g., engineer reports to EM + PM) creates accountability confusion. Avoid at < 500 people.
+
+---
+
+## Title Frameworks
+
+### The Problem with Title Inflation
+
+Early startups over-title to compete with cash. "VP of Engineering" with 2 reports. "Head of Marketing" with no team.
+
+**Consequences:**
+- Can't add leadership above inflated titles without awkward conversations
+- Candidates from mature companies expect scope commensurate with titles
+- Internal equity breaks when the same title means different things
+
+### Preventing Title Inflation
+
+**Rule 1:** VP titles require managing managers (not just ICs).
+**Rule 2:** Director titles require managing multiple ICs or a large function.
+**Rule 3:** No more than one "Head of X" per function.
+**Rule 4:** Document scope expectations per title before making offers.
+
+### Engineering Title Ladder (example)
+
+| Title | Level | Scope | Reports |
+|-------|-------|-------|---------|
+| Software Engineer I | L1 | Executes defined tasks | — |
+| Software Engineer II | L2 | Independent delivery | — |
+| Senior Software Engineer | L3 | Leads features, mentors | — |
+| Staff Software Engineer | L4 | Cross-team technical leadership | — |
+| Principal Software Engineer | L5 | Company-wide technical direction | — |
+| Distinguished Engineer | L6 | External recognition, defining practice | — |
+| Engineering Manager | M1 | Team of 4–8 engineers | 4–8 ICs |
+| Senior Engineering Manager | M2 | Larger team or manager of managers | 2–4 managers |
+| Director of Engineering | M3 | Functional area | Multiple managers |
+| VP of Engineering | M4 | Engineering org | Directors |
+| CTO | M5 | Technical organization + strategy | VPs |
+
+**IC vs. Management track:** Explicitly separate. Senior ICs should not need to move to management for career advancement. Staff/Principal/Distinguished track provides this.
+
+### Go-to-Market Title Ladder (example)
+
+| Title | Level | Focus |
+|-------|-------|-------|
+| SDR / BDR | S1 | Outbound prospecting |
+| Account Executive I | S2 | SMB closing |
+| Account Executive II | S3 | Mid-market closing |
+| Senior Account Executive | S4 | Enterprise closing |
+| Principal / Strategic AE | S5 | Named accounts, complex deals |
+| Sales Manager | M1 | 6–8 reps |
+| Director of Sales | M2 | Multiple teams or segments |
+| VP of Sales | M3 | Full sales org |
+| CRO | M4 | Revenue org (sales + CS + marketing) |
+
+---
+
+## Career Ladders
+
+A career ladder is a documented set of expectations per level. Not aspirational — behavioral. "What does a P3 engineer do that a P2 doesn't?"
+
+### Why career ladders matter for HR
+
+1. **Retention:** Employees can see where they're going
+2. **Consistency:** Managers use the same criteria for promotions
+3. **Compensation:** Bands anchor to levels; levels require definitions
+4. **Equity:** Removes "who's the manager's favorite" from promotion decisions
+
+### Career Ladder Structure
+
+For each level, define 4 dimensions:
+
+**1. Scope** — How big is the problem space? Team / cross-team / org-wide / company-wide?
+**2. Impact** — How does work connect to outcomes? (Task → Feature → Product → Business)
+**3. Craft** — Technical/functional skill expectations
+**4. Influence** — How does this person improve others? (Self → peers → team → org)
+
+**Example: Senior Software Engineer (L3) vs. Staff Software Engineer (L4)**
+
+| Dimension | L3 (Senior SWE) | L4 (Staff SWE) |
+|-----------|----------------|----------------|
+| Scope | Owns features or services | Owns technical domains across teams |
+| Impact | Ships features that improve user outcomes | Shapes technical direction for a product area |
+| Craft | Writes high-quality code, good design skills | Sets coding standards, contributes to architecture |
+| Influence | Mentors L1–L2, code reviews | Mentors L3+, identifies org-wide technical gaps |
+
+### How to build a career ladder from scratch
+
+1. **Interview your best performers** — "What do you do that your junior peers don't?" Collect behaviors, not aspirations.
+2. **Draft 3 levels** — Don't start with 6. Start with junior, mid, senior. Add staff/principal only when you have enough people to warrant it.
+3. **Manager calibration** — Every manager rates 5 current employees against the draft. Gaps surface immediately.
+4. **Publish and iterate** — Don't wait for perfection. A 70% ladder shipped is better than a 100% ladder in a drawer.
+
+---
+
+## Reorg Playbook
+
+### When reorgs are necessary
+- Strategy pivot requires different team structure (e.g., single product → multi-product)
+- Acquisition or team merger
+- Function is genuinely too slow due to coordination overhead
+- Leadership departure creates structural opportunity
+
+### When reorgs are a mistake
+- "We need to shake things up" (disruption for its own sake)
+- Avoiding a specific personnel decision (use the right tool)
+- Solving a cultural problem with a structural change
+- Reacting to one team's complaint without systemic evidence
+
+### Reorg Process (4–8 weeks)
+
+**Week 1–2: Diagnose**
+- Map current org: every role, reporting line, team output
+- Identify where work is slow, duplicated, or falling through cracks
+- Interview 5–10 people across teams: "What takes longer than it should? What decisions are hard to make?"
+
+**Week 3–4: Design options**
+- Draft 2–3 structural alternatives
+- For each: estimated coordination costs, manager span impact, open roles created
+- Validate with CEO + 1–2 trusted operators. Don't crowdsource the design.
+
+**Week 5–6: Decide and prepare**
+- Select option; finalize all reporting changes
+- Prepare communications for every affected person (individual conversations before all-hands)
+- Write the "why" — employees need to understand the business reason, not just the result
+
+**Week 7–8: Communicate and implement**
+- Individual conversations with all manager+ changes (first)
+- Team-level conversations with managers (second)
+- All-hands with full context (third)
+- Updated org chart published within 24 hours of announcement
+
+### Communication sequence (non-negotiable)
+
+1. Affected individuals first (private, before anything else)
+2. Affected managers second (to prepare for team conversations)
+3. Full team/company third (all-hands or company note)
+4. External (clients, board) only if materially impacted
+
+**Never:** Email blast first. No individual conversations. Discovered on the org chart.
+
+---
+
+## Founder → Professional Management Transition
+
+The most common scaling failure point in startups.
+
+### Stage 1: Founder-Led (0–30 people)
+
+Founders make all decisions, know everyone personally, set culture through behavior. Works because trust and context are built directly.
+
+**What breaks:**
+- Decisions bottleneck at founders
+- New hires don't get enough context (founders can't be everywhere)
+- Culture transmitted through osmosis, not documentation
+
+### Stage 2: First Managers (30–80 people)
+
+Founders can no longer manage all ICs. First manager layer typically = promoted high performers.
+
+**The "brilliant IC → struggling manager" trap:**
+- Individual contributor skills ≠ management skills
+- Promoted ICs often continue doing IC work while ignoring management work
+- No one holds them accountable to management output (1:1 quality, team health, performance feedback)
+
+**What to do:**
+- Explicit manager training before promotion (not after)
+- Management KPIs separate from IC KPIs
+- Peer community for new managers (monthly cohort session)
+- HR check-ins on manager health at 30/60/90 days
+
+### Stage 3: Professional Management (80–200 people)
+
+External hires at Director/VP level bring professional management skills but lack company context.
+
+**Common failure modes:**
+- Hired "too senior" — VP who's used to 200-person teams in a 50-person function
+- Culture clash — Big-company manager who adds process that kills startup speed
+- Authority vacuum — External VP doesn't earn trust; team ignores them; founder continues to bypass hierarchy
+
+**Mitigation:**
+- Hiring bar: Has this person scaled from this stage to 2x this stage before? Not managed a team at 2x — built a team to 2x.
+- Explicit onboarding on "how we make decisions here"
+- 90-day milestones focused on relationship-building before any structural changes
+- Founders explicitly hand off ownership and reinforce new manager's authority publicly
+
+### Stage 4: Founder Transition from Operator to Executive
+
+The hardest personal transition. Founder moves from doing to enabling.
+
+**Signs you haven't made the transition:**
+- You're still in every technical decision
+- Teams come to you instead of their manager for approvals
+- You know more about the team's work than the manager does
+- Managers feel they need to check in before acting
+
+**What the transition requires:**
+- Explicit authority delegation in writing (not just verbal)
+- Willingness to let managers make decisions you'd make differently
+- Redirecting team members to their manager consistently
+- Measuring managers on outcomes, not just process adherence
+- Letting managers hire and fire without founder override (except final call on VPs)
diff --git a/skills/c-level-advisor/chro-advisor/references/people_strategy.md b/skills/c-level-advisor/chro-advisor/references/people_strategy.md
new file mode 100644
index 00000000..c01d6e54
--- /dev/null
+++ b/skills/c-level-advisor/chro-advisor/references/people_strategy.md
@@ -0,0 +1,320 @@
+# People Strategy Reference
+
+Hiring, retention, performance, and remote/hybrid frameworks for each growth stage.
+
+---
+
+## Hiring Strategy by Growth Stage
+
+### Pre-Seed / Seed (1–15 people)
+
+**Who you're hiring:** Generalists who can do multiple jobs. Specialists are a luxury you can't afford unless the specialty is your core product.
+
+**The test:** Could this person be the 5th employee at a startup and thrive? If they need a defined role, clear process, and a manager — not yet.
+
+**Sourcing at this stage:**
+- Founder networks first (highest signal, lowest cost)
+- Angel List / Wellfound — self-selected for startup risk tolerance
+- Referrals from existing employees (offer a referral bonus from day 1)
+- GitHub / Dribbble / published work for technical roles
+- Avoid: Big job boards, recruiters (unless technical retained search for C-suite)
+
+**Interview process (keep it lean):**
+1. 30-min intro call (culture/motivation fit, comp alignment)
+2. Take-home or live work sample (2–4 hours max, paid for senior roles)
+3. 60-min deep-dive with founders
+4. Reference checks (3 calls, not emails — you want the real story)
+
+**Offer timeline:** Decision within 48 hours. Top candidates have multiple offers.
+
+**What to get right:**
+- Written job scorecard (outcomes expected in 30/60/90 days) — not a job description
+- Equity range disclosed in first conversation
+- No exploding offers. Pressure tactics lose good people.
+
+---
+
+### Series A (15–50 people)
+
+**The hiring shift:** You need some specialists now. First management layer emerges. First "culture carries" — people who reinforce what you want to become.
+
+**Critical hires at this stage (in priority order):**
+1. VP/Head of Engineering (if founder isn't technical)
+2. Head of Product
+3. First dedicated recruiter (when you're hiring > 10/year)
+4. First Finance/Operations hire
+5. Head of Sales (when product-market fit is real)
+
+**Building the recruiting function:**
+- First recruiter should be a generalist with hustle, not a specialist
+- Set up an ATS (Ashby, Greenhouse, or Lever) before you need it — not after
+- Create interview scorecards for every role
+- Track: time to fill, offer acceptance rate, source quality
+
+**Common mistakes at Series A:**
+- Promoting top ICs to management without management training
+- Hiring "brand name" executives who've never operated lean
+- Over-indexing on experience, under-indexing on trajectory
+- No onboarding process → 90-day regrettable turnover
+
+**Job scorecards (required for every role):**
+```
+Role: [Title]
+Reports to: [Manager]
+Start date: [Target]
+Why this role now: [Business case in 1-2 sentences]
+
+Outcomes (90 days):
+- [Concrete deliverable 1]
+- [Concrete deliverable 2]
+- [Concrete deliverable 3]
+
+Outcomes (12 months):
+- [Strategic impact 1]
+- [Strategic impact 2]
+
+Competencies (top 3 only):
+- [What, why it matters for THIS role]
+- [What, why it matters for THIS role]
+- [What, why it matters for THIS role]
+
+Comp range: [Base] + [Equity] + [Benefits summary]
+```
+
+---
+
+### Series B (50–150 people)
+
+**The scaling inflection point.** Tribal knowledge breaks. Process matters now. Culture requires deliberate investment.
+
+**What changes:**
+- Recruiters become specialists (technical, GTM, exec)
+- Manager training becomes non-negotiable
+- Performance management needs structure (not just "we'll know it when we see it")
+- Onboarding needs to scale without founders in every session
+- Comp bands become essential — people are comparing notes
+
+**Hiring velocity benchmarks (Series B):**
+| Function | Avg time to fill | Avg interviews | Benchmark offer acceptance |
+|----------|-----------------|----------------|---------------------------|
+| Engineering IC | 35–45 days | 4–5 rounds | 80–85% |
+| Engineering Manager | 45–60 days | 5–6 rounds | 75–80% |
+| Sales IC | 25–35 days | 3–4 rounds | 85–90% |
+| Sales Manager | 40–55 days | 4–5 rounds | 80–85% |
+| G&A (Finance, HR, Ops) | 30–45 days | 3–4 rounds | 85–90% |
+
+**Internal mobility:** By 50 people, start tracking internal promotion rates. Target: 20–30% of manager+ roles filled internally. If it's < 10%, your career development is failing.
+
+---
+
+### Series C+ (150+ people)
+
+**Professional management era.** Founders can't know everyone. Systems and culture carry what personal relationships used to.
+
+**HR function maturity required:**
+- Dedicated HRBPs per business unit (1:75–100 employees)
+- L&D budget (1–2% of salary budget minimum)
+- Succession planning for all VP+ roles
+- Structured calibration process for performance reviews
+- Total rewards strategy reviewed annually with board
+
+---
+
+## Retention Programs That Actually Work
+
+### What drives retention (in order of impact)
+
+1. **Manager quality** — Gallup: 70% of team engagement variance is explained by the manager. Fix managers first.
+2. **Growth trajectory** — People leave when they can't see their next role. Career ladders are retention tools.
+3. **Compensation competitiveness** — Being at P25 on salary is a slow leak. Audit annually.
+4. **Mission/product belief** — Especially for senior ICs. They want to work on something that matters.
+5. **Team quality** — "I stay because of the people I work with." True at every level.
+6. **Flexibility** — Location, hours, autonomy. Low cost, high impact.
+
+### What doesn't work (but companies do anyway)
+- Pizza parties and ping pong tables
+- "Perks" that substitute for salary
+- Annual reviews with no action on feedback
+- Forced fun events
+- Vague "culture improvement" initiatives without specific behavior changes
+
+### The 30-60-90 Onboarding Framework
+
+Structured onboarding cuts 90-day turnover by 50%+.
+
+**Days 1–30: Learn**
+- Complete admin setup (day 1, before lunch)
+- Meet all key stakeholders (scheduled by their manager, not on the new hire)
+- Understand: business model, current priorities, team processes, how success is measured
+- No deliverables expected. Learning is the job.
+- Weekly 1:1 with manager: "What's confusing? What do you need?"
+
+**Days 31–60: Contribute**
+- First real project (scoped to be completable)
+- Present findings or work to the team
+- Identify one process that could be improved (observation only — don't fix yet)
+- 30-day check-in: formal feedback from manager
+
+**Days 61–90: Lead**
+- Own a deliverable end-to-end
+- Offer one specific improvement recommendation with data
+- 90-day review: mutual assessment — manager on new hire, new hire on onboarding
+- Set 6-month goals
+
+### Stay Interviews (underused, high ROI)
+
+Run with every employee once per year. Not their manager — HR or skip-level.
+
+**Questions that surface real risk:**
+- "What's keeping you here?"
+- "What would make you consider leaving?"
+- "What's one thing your manager could do differently?"
+- "Is your role what you expected when you joined?"
+- "What career path do you want? Are we helping you get there?"
+- "Are you fairly compensated? Do you know how you'd get a raise?"
+
+**Act on answers within 30 days or don't ask.** Unanswered feedback is worse than no feedback.
+
+### Exit Interviews — What to Actually Learn
+
+Skip the happiness survey. Ask these:
+- "When did you first think about leaving?"
+- "Was there a specific event that triggered your decision?"
+- "What could we have done to retain you?"
+- "Where are you going and why?" (What does the other offer have that we don't?)
+- "Would you recommend us as an employer? Why or why not?"
+
+Track exit themes by manager. If one manager's exits cite "micromanagement" three times — that's data.
+
+---
+
+## Performance Management
+
+### The System That Works
+
+**Continuous > annual.** Annual reviews with no mid-year touchpoints are theater.
+
+**Structure:**
+- **Weekly 1:1s** (30 min): blockers, priorities, relationship
+- **Monthly check-ins** (1 hr): progress against goals, feedback exchange
+- **Quarterly reviews** (formal): written self-assessment + manager assessment + goal revision
+- **Annual calibration** (rating + comp): cross-manager calibration session, then individual conversations
+
+### Calibration Sessions
+
+**Purpose:** Prevent manager bias. Ensure "exceeds expectations" means the same thing across teams.
+
+**Process:**
+1. Managers submit preliminary ratings independently
+2. HR facilitates 2-hr calibration with all managers in a function
+3. Managers must justify outliers (top and bottom)
+4. Ratings adjusted for consistency
+5. Managers deliver final ratings with rationale
+
+**Distribution guidance (enforce with calibration):**
+- Exceptional (5): < 10% — if everyone's exceptional, no one is
+- Exceeds (4): 20–25%
+- Meets (3): 55–65%
+- Needs improvement (2): 8–12%
+- Underperforming (1): 2–5%
+
+### Managing Underperformers
+
+**The most avoided management task. And the most damaging when avoided.**
+
+High performers notice when underperformers are tolerated. They leave.
+
+**The 4-step framework:**
+
+**Step 1: Diagnose before acting** (Week 1–2)
+- Is this a skill gap (can't do it) or a will gap (won't do it)?
+- Skill gap → training, clearer expectations, different role
+- Will gap → direct feedback, clear consequences, then PIP
+
+**Step 2: Direct feedback conversation** (Week 2–3)
+- Specific: "Your last 3 sprint deliveries were 40% incomplete"
+- Not: "You're not meeting expectations"
+- Document. Send written summary after every feedback conversation.
+
+**Step 3: Performance Improvement Plan (PIP)**
+Required when: two rounds of direct feedback haven't produced change.
+
+PIP structure:
+```
+Name: [Employee]
+Manager: [Name]
+Date: [Start]
+Review date: [30/60 days out]
+
+Current performance issues:
+- [Specific, observable behavior with examples and dates]
+- [Metric not met: target X, actual Y for Z weeks]
+
+Required improvements:
+- [Specific, measurable outcome 1] by [date]
+- [Specific, measurable outcome 2] by [date]
+
+Support provided:
+- [Training, coaching, additional resources]
+
+Consequences if not met: [Role change / separation]
+
+Check-in schedule: [Weekly with manager + HR]
+```
+
+**Step 4: Exit or role change**
+- If PIP milestones not met: proceed to separation
+- Don't extend PIPs indefinitely — it's unfair to the employee and the team
+- Offer a graceful exit where possible: "This role isn't the right fit. Here's a package and a reference."
+
+**What not to do:**
+- "Quiet manage out" without clear feedback (legally risky, unfair)
+- PIP as a formality before termination (if you know you're firing them, just do it)
+- Tolerating underperformance "because we're understaffed" (it makes understaffing worse)
+
+---
+
+## Remote / Hybrid Strategy
+
+### The question isn't "remote or not" — it's "what kind of collaboration does our work require?"
+
+**Work type taxonomy:**
+| Work type | Remote-compatible? | Hybrid compatible? |
+|-----------|-------------------|-------------------|
+| Deep individual work (coding, writing, analysis) | Yes | Yes |
+| Async collaboration (code review, doc review) | Yes | Yes |
+| Synchronous problem-solving (debugging, design) | Yes (video) | Yes |
+| Relationship-building (onboarding, new team) | Harder | Yes |
+| Executive alignment, strategy | Harder | Yes — quarterly in-person |
+| Sales (enterprise, relationship-based) | No | Depends on market |
+
+### Making Hybrid Work (Not Just a Policy)
+
+**The failure mode:** "Hybrid" = go to office on Tuesday/Thursday, but no one coordinates, all meetings are still Zoom anyway.
+
+**What actually works:**
+
+1. **Anchor days with purpose** — Office days should have things that require the office: workshops, team rituals, whiteboarding sessions. Not just "presence."
+
+2. **Async-first culture, not async-only** — Document decisions. Write things down. Use Loom for walkthroughs. Reduce "quick sync" meetings.
+
+3. **Equal experience for remote participants** — If some are in the room and some are on video, the remote folks are second-class. Either everyone's remote or set up rooms properly.
+
+4. **Manager standards for remote teams:**
+ - 1:1s are non-negotiable (video, not async)
+ - Over-communicate on priorities (people can't absorb hallway context)
+ - Write down decisions (remote employees miss casual office decisions)
+ - Recognize work publicly (Slack shoutouts, all-hands wins)
+
+### Remote Compensation Philosophy (pick one, be explicit)
+
+**Option A: Location-based pay**
+Pay based on where the employee lives. Lower cost in lower-cost markets. Harder to hire in high-cost cities.
+
+**Option B: Role-based (location-neutral)**
+One band for each role regardless of location. Simpler, more equitable. Higher overall payroll cost.
+
+**Option C: Zone-based**
+Define 2–3 geographic zones (e.g., Tier 1 cities, Tier 2 cities, international). Set bands per zone. Common at mid-stage startups.
+
+**The wrong answer:** No stated policy, and every offer is negotiated individually. Creates pay equity problems fast.
diff --git a/skills/c-level-advisor/chro-advisor/scripts/comp_benchmarker.py b/skills/c-level-advisor/chro-advisor/scripts/comp_benchmarker.py
new file mode 100644
index 00000000..5102fec3
--- /dev/null
+++ b/skills/c-level-advisor/chro-advisor/scripts/comp_benchmarker.py
@@ -0,0 +1,613 @@
+#!/usr/bin/env python3
+"""
+Compensation Benchmarker
+========================
+Salary benchmarking and total comp modeling for startup teams.
+Analyzes pay equity, compa-ratios, and total comp vs. market.
+
+Usage:
+ python comp_benchmarker.py # Run with built-in sample data
+ python comp_benchmarker.py --config roster.json # Load from JSON
+ python comp_benchmarker.py --help
+
+Output: Band compliance report, compa-ratio distribution, pay equity flags,
+ equity value analysis, and total comp vs. market.
+"""
+
+import argparse
+import json
+import csv
+import io
+import sys
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+from datetime import date
+import math
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BandDefinition:
+ """Salary band for a role level."""
+ level: str # L1, L2, L3, L4, M1, M2, M3, VP
+ function: str # Engineering, Sales, Product, G&A, Marketing, CS
+ band_min: int # Annual USD
+ band_mid: int # P50 anchor
+ band_max: int # Band ceiling
+ market_p25: int # Market 25th percentile
+ market_p50: int # Market median (should align with band_mid for P50 strategy)
+ market_p75: int # Market 75th percentile
+ location_zone: str # Tier1 (SF/NYC), Tier2 (Austin/Denver), Tier3 (Remote/other), EU
+
+
+@dataclass
+class Employee:
+ """One employee record."""
+ id: str
+ name: str
+ role: str
+ level: str
+ function: str
+ location_zone: str
+ base_salary: int
+ bonus_target_pct: float # % of base
+ equity_shares: int # Total unvested options/RSUs
+ equity_strike: float # Strike price (0 for RSUs)
+ equity_current_409a: float # Current 409A share price
+ equity_vest_years_remaining: float # How many years of vesting remain
+ benefits_annual: int # Employer-paid benefits cost
+ gender: str # M/F/NB/Undisclosed (for equity audit)
+ ethnicity: str # For equity audit — can be "Undisclosed"
+ tenure_years: float
+ performance_rating: int # 1–5
+ last_raise_months_ago: int
+ last_equity_refresh_months_ago: Optional[int] = None
+
+
+@dataclass
+class CompRoster:
+ company: str
+ as_of_date: str # ISO date
+ funding_stage: str # Seed, Series A, Series B, etc.
+ comp_philosophy_target: str # P50, P65, P75 — your target percentile
+ preferred_stock_price: float # Last round price (for offer modeling)
+ employees: list[Employee] = field(default_factory=list)
+ bands: list[BandDefinition] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Band lookup
+# ---------------------------------------------------------------------------
+
+def find_band(roster: CompRoster, level: str, function: str, zone: str) -> Optional[BandDefinition]:
+ """Find best-matching band. Falls back to any matching level+function if zone not found."""
+ matches = [b for b in roster.bands if b.level == level and b.function == function and b.location_zone == zone]
+ if matches:
+ return matches[0]
+ # Fallback: same level+function, any zone
+ matches = [b for b in roster.bands if b.level == level and b.function == function]
+ if matches:
+ return matches[0]
+ # Fallback: same level, any function
+ matches = [b for b in roster.bands if b.level == level]
+ if matches:
+ return matches[0]
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Compensation analysis
+# ---------------------------------------------------------------------------
+
+def compa_ratio(salary: int, band_mid: int) -> float:
+ return salary / band_mid if band_mid > 0 else 0.0
+
+
+def band_position(salary: int, band_min: int, band_max: int) -> float:
+ """Position in band: 0.0 = at min, 1.0 = at max."""
+ if band_max == band_min:
+ return 0.5
+ return (salary - band_min) / (band_max - band_min)
+
+
+def annualized_equity_value(emp: Employee) -> int:
+ """Current 409A value of unvested equity, annualized."""
+ if emp.equity_vest_years_remaining <= 0:
+ return 0
+ if emp.equity_current_409a > emp.equity_strike:
+ intrinsic = (emp.equity_current_409a - emp.equity_strike) * emp.equity_shares
+ else:
+ # Options underwater — still show at current FMV for RSUs or future value for options
+ intrinsic = emp.equity_current_409a * emp.equity_shares if emp.equity_strike == 0 else 0
+ return int(intrinsic / emp.equity_vest_years_remaining)
+
+
+def total_comp(emp: Employee) -> int:
+ bonus = int(emp.base_salary * emp.bonus_target_pct)
+ equity = annualized_equity_value(emp)
+ return emp.base_salary + bonus + equity + emp.benefits_annual
+
+
+def analyze_employee(emp: Employee, roster: CompRoster) -> dict:
+ band = find_band(roster, emp.level, emp.function, emp.location_zone)
+ result = {
+ "id": emp.id,
+ "name": emp.name,
+ "role": emp.role,
+ "level": emp.level,
+ "function": emp.function,
+ "zone": emp.location_zone,
+ "base": emp.base_salary,
+ "bonus_target": int(emp.base_salary * emp.bonus_target_pct),
+ "equity_annual": annualized_equity_value(emp),
+ "benefits": emp.benefits_annual,
+ "total_comp": total_comp(emp),
+ "performance": emp.performance_rating,
+ "tenure_years": emp.tenure_years,
+ "last_raise_months": emp.last_raise_months_ago,
+ "band": band,
+ "compa_ratio": None,
+ "band_position": None,
+ "vs_market_p50": None,
+ "flags": [],
+ }
+
+ if band:
+ cr = compa_ratio(emp.base_salary, band.band_mid)
+ bp = band_position(emp.base_salary, band.band_min, band.band_max)
+ result["compa_ratio"] = round(cr, 3)
+ result["band_position"] = round(bp, 3)
+ result["vs_market_p50"] = round((emp.base_salary - band.market_p50) / band.market_p50 * 100, 1)
+
+ # Flags
+ if emp.base_salary < band.band_min:
+ result["flags"].append(("CRITICAL", "Base below band minimum — immediate attrition risk"))
+ elif cr < 0.88:
+ result["flags"].append(("HIGH", f"Compa-ratio {cr:.2f} — significantly below midpoint"))
+ elif cr < 0.93:
+ result["flags"].append(("MEDIUM", f"Compa-ratio {cr:.2f} — below target zone (0.95–1.05)"))
+
+ if emp.base_salary > band.band_max:
+ result["flags"].append(("HIGH", "Base above band maximum — review for promotion or band update"))
+
+ if emp.performance_rating >= 4 and cr < 0.95:
+ result["flags"].append(("HIGH", f"High performer (rating {emp.performance_rating}) underpaid — flight risk"))
+
+ if emp.last_raise_months_ago > 18:
+ result["flags"].append(("MEDIUM", f"No raise in {emp.last_raise_months_ago} months — review due"))
+
+ if emp.equity_vest_years_remaining < 1.0 and (emp.last_equity_refresh_months_ago is None or emp.last_equity_refresh_months_ago > 24):
+ result["flags"].append(("HIGH", "Equity nearly fully vested with no refresh — retention hook gone"))
+
+ else:
+ result["flags"].append(("INFO", "No band found for this level/function/zone"))
+
+ return result
+
+
+# ---------------------------------------------------------------------------
+# Aggregate analysis
+# ---------------------------------------------------------------------------
+
+def pay_equity_audit(analyses: list[dict], employees: list[Employee]) -> dict:
+ """Simple pay equity analysis by gender and ethnicity."""
+ emp_by_id = {e.id: e for e in employees}
+
+ def group_stats(group_key_fn):
+ groups: dict[str, list[float]] = {}
+ for a in analyses:
+ if a["compa_ratio"] is None:
+ continue
+ emp = emp_by_id.get(a["id"])
+ if not emp:
+ continue
+ key = group_key_fn(emp)
+ if key not in groups:
+ groups[key] = []
+ groups[key].append(a["compa_ratio"])
+ return {k: {"n": len(v), "avg_cr": round(sum(v)/len(v), 3), "min_cr": round(min(v), 3), "max_cr": round(max(v), 3)}
+ for k, v in groups.items() if v}
+
+ gender_stats = group_stats(lambda e: e.gender)
+ ethnicity_stats = group_stats(lambda e: e.ethnicity)
+
+ # Compute gap vs. the largest group
+ def compute_gap(stats: dict) -> dict[str, float]:
+ if not stats:
+ return {}
+ largest = max(stats.items(), key=lambda x: x[1]["n"])
+ ref_cr = largest[1]["avg_cr"]
+ return {k: round((v["avg_cr"] - ref_cr) / ref_cr * 100, 1) for k, v in stats.items()}
+
+ gender_gaps = compute_gap(gender_stats)
+ ethnicity_gaps = compute_gap(ethnicity_stats)
+
+ return {
+ "gender": gender_stats,
+ "gender_gaps_pct": gender_gaps,
+ "ethnicity": ethnicity_stats,
+ "ethnicity_gaps_pct": ethnicity_gaps,
+ }
+
+
+def compa_ratio_distribution(analyses: list[dict]) -> dict:
+ crs = [a["compa_ratio"] for a in analyses if a["compa_ratio"] is not None]
+ if not crs:
+ return {}
+ buckets = {
+ "< 0.85 (below band)": 0,
+ "0.85–0.94 (developing)": 0,
+ "0.95–1.05 (target zone)": 0,
+ "1.06–1.15 (senior in role)": 0,
+ "> 1.15 (above band)": 0,
+ }
+ for cr in crs:
+ if cr < 0.85:
+ buckets["< 0.85 (below band)"] += 1
+ elif cr < 0.95:
+ buckets["0.85–0.94 (developing)"] += 1
+ elif cr <= 1.05:
+ buckets["0.95–1.05 (target zone)"] += 1
+ elif cr <= 1.15:
+ buckets["1.06–1.15 (senior in role)"] += 1
+ else:
+ buckets["> 1.15 (above band)"] += 1
+ avg = sum(crs) / len(crs)
+ return {"distribution": buckets, "avg_compa_ratio": round(avg, 3), "n": len(crs)}
+
+
+# ---------------------------------------------------------------------------
+# Report output
+# ---------------------------------------------------------------------------
+
+def fmt(n) -> str:
+ return f"${int(n):,.0f}"
+
+
+def bar(value: float, width: int = 20) -> str:
+ filled = min(width, max(0, int(value * width)))
+ return "█" * filled + "░" * (width - filled)
+
+
+def print_report(roster: CompRoster):
+ WIDTH = 76
+ SEP = "=" * WIDTH
+ sep = "-" * WIDTH
+
+ analyses = [analyze_employee(e, roster) for e in roster.employees]
+ cr_dist = compa_ratio_distribution(analyses)
+ equity_audit = pay_equity_audit(analyses, roster.employees)
+
+ print(SEP)
+ print(f" COMPENSATION BENCHMARKING REPORT — {roster.company}")
+ print(f" As of: {roster.as_of_date} | Stage: {roster.funding_stage} | Target: {roster.comp_philosophy_target}")
+ print(SEP)
+
+ # Summary stats
+ total_emps = len(roster.employees)
+ flagged = sum(1 for a in analyses if any(s in ["CRITICAL", "HIGH"] for s, _ in a["flags"]))
+ total_payroll = sum(e.base_salary for e in roster.employees)
+ avg_total_comp = sum(a["total_comp"] for a in analyses) // total_emps if total_emps else 0
+
+ print(f"\n[ SUMMARY ]")
+ print(sep)
+ print(f" Employees analyzed: {total_emps}")
+ print(f" Flagged (critical/high): {flagged}")
+ print(f" Total base payroll: {fmt(total_payroll)}/year")
+ print(f" Avg total comp: {fmt(avg_total_comp)}/year")
+ if cr_dist:
+ print(f" Avg compa-ratio: {cr_dist['avg_compa_ratio']:.3f}")
+
+ # Compa-ratio distribution
+ if cr_dist:
+ print(f"\n[ COMPA-RATIO DISTRIBUTION ]")
+ print(sep)
+ total_n = cr_dist["n"]
+ for label, count in cr_dist["distribution"].items():
+ pct = count / total_n if total_n else 0
+ bar_str = bar(pct, 25)
+ print(f" {label:<30} {bar_str} {count:3d} ({pct*100:4.0f}%)")
+
+ # Pay equity audit
+ print(f"\n[ PAY EQUITY AUDIT ]")
+ print(sep)
+
+ print(f" By Gender:")
+ for group, stats in equity_audit["gender"].items():
+ gap = equity_audit["gender_gaps_pct"].get(group, 0.0)
+ gap_str = f" gap: {gap:+.1f}%" if gap != 0 else " (reference group)"
+ flag = " ⚠" if abs(gap) > 5 else ""
+ print(f" {group:<15} n={stats['n']} avg_CR={stats['avg_cr']:.3f}{gap_str}{flag}")
+
+ print(f"\n By Ethnicity:")
+ for group, stats in equity_audit["ethnicity"].items():
+ gap = equity_audit["ethnicity_gaps_pct"].get(group, 0.0)
+ gap_str = f" gap: {gap:+.1f}%" if gap != 0 else " (reference group)"
+ flag = " ⚠" if abs(gap) > 5 else ""
+ print(f" {group:<20} n={stats['n']} avg_CR={stats['avg_cr']:.3f}{gap_str}{flag}")
+
+ print(f"\n ⚠ = gap > 5%. Investigate with regression controlling for level, tenure, and performance.")
+
+ # Employee detail with flags
+ print(f"\n[ EMPLOYEE DETAIL ]")
+ print(sep)
+
+ # Group by function
+ functions = sorted(set(e.function for e in roster.employees))
+ for fn in functions:
+ fn_analyses = [a for a in analyses if a["function"] == fn]
+ if not fn_analyses:
+ continue
+ print(f"\n ── {fn} ──")
+ print(f" {'Name':<22} {'Role':<28} {'Lvl':<5} {'Base':>10} {'TotalComp':>11} {'CR':>6} {'Perf':>5} Flags")
+ print(f" {'-'*22} {'-'*28} {'-'*5} {'-'*10} {'-'*11} {'-'*6} {'-'*5} {'-'*20}")
+
+ for a in sorted(fn_analyses, key=lambda x: -x["base"]):
+ cr_str = f"{a['compa_ratio']:.2f}" if a["compa_ratio"] else "N/A"
+ flag_summary = ", ".join(s for s, _ in a["flags"] if s in ("CRITICAL", "HIGH", "MEDIUM"))
+ flag_str = flag_summary if flag_summary else "OK"
+ print(f" {a['name']:<22} {a['role']:<28} {a['level']:<5} "
+ f"{fmt(a['base']):>10} {fmt(a['total_comp']):>11} {cr_str:>6} {a['performance']:>5} {flag_str}")
+
+ # Print flag detail for critical/high
+ for severity, msg in a["flags"]:
+ if severity in ("CRITICAL", "HIGH"):
+ print(f" {'':>22} ↳ [{severity}] {msg}")
+
+ # Action items
+ critical = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "CRITICAL"]
+ high = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "HIGH"]
+ medium = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "MEDIUM"]
+
+ print(f"\n[ ACTION ITEMS ]")
+ print(sep)
+
+ if critical:
+ print(f"\n CRITICAL — Address this review cycle:")
+ for name, msg in critical:
+ print(f" • {name}: {msg}")
+
+ if high:
+ print(f"\n HIGH — Address within 30 days:")
+ for name, msg in high[:10]:
+ print(f" • {name}: {msg}")
+ if len(high) > 10:
+ print(f" ... and {len(high)-10} more")
+
+ if medium:
+ print(f"\n MEDIUM — Address in next comp cycle:")
+ for name, msg in medium[:8]:
+ print(f" • {name}: {msg}")
+ if len(medium) > 8:
+ print(f" ... and {len(medium)-8} more")
+
+ if not critical and not high and not medium:
+ print(f"\n No critical or high-severity issues. Compensation appears well-managed.")
+
+ # Remediation cost estimate
+ below_min = [a for a in analyses if a["band"] and a["base"] < a["band"].band_min]
+ below_mid = [a for a in analyses if a["compa_ratio"] and a["compa_ratio"] < 0.90]
+
+ if below_min or below_mid:
+ print(f"\n[ REMEDIATION COST ESTIMATE ]")
+ print(sep)
+
+ if below_min:
+ cost_to_min = sum(a["band"].band_min - a["base"] for a in below_min)
+ print(f" Cost to bring below-minimum to band min: {fmt(cost_to_min)}/year ({len(below_min)} employees)")
+
+ if below_mid:
+ cost_to_90 = sum(int(a["band"].band_mid * 0.90) - a["base"] for a in below_mid if a["base"] < int(a["band"].band_mid * 0.90))
+ cost_to_90 = max(0, cost_to_90)
+ print(f" Cost to bring CR < 0.90 to CR = 0.90: {fmt(cost_to_90)}/year ({len(below_mid)} employees)")
+
+ total_payroll_impact = sum(e.base_salary for e in roster.employees)
+ total_remediation = (below_min and cost_to_min or 0)
+ print(f"\n Total payroll before remediation: {fmt(total_payroll_impact)}/year")
+ print(f" Remediation as % of payroll: {total_remediation/total_payroll_impact*100:.1f}%")
+
+ print(f"\n{SEP}\n")
+
+
+def export_csv(roster: CompRoster) -> str:
+ analyses = [analyze_employee(e, roster) for e in roster.employees]
+ output = io.StringIO()
+ writer = csv.writer(output)
+ writer.writerow(["ID", "Name", "Role", "Level", "Function", "Zone",
+ "Base", "Bonus Target", "Equity Annual", "Benefits", "Total Comp",
+ "Compa Ratio", "Band Position", "vs Market P50 %",
+ "Performance", "Tenure Years", "Last Raise (mo)",
+ "Gender", "Ethnicity", "Critical Flags", "High Flags"])
+ for a, e in zip(analyses, roster.employees):
+ critical_flags = "; ".join(msg for sev, msg in a["flags"] if sev == "CRITICAL")
+ high_flags = "; ".join(msg for sev, msg in a["flags"] if sev == "HIGH")
+ writer.writerow([a["id"], a["name"], a["role"], a["level"], a["function"], a["zone"],
+ a["base"], a["bonus_target"], a["equity_annual"], a["benefits"], a["total_comp"],
+ a["compa_ratio"], a["band_position"], a["vs_market_p50"],
+ a["performance"], a["tenure_years"], a["last_raise_months"],
+ e.gender, e.ethnicity, critical_flags, high_flags])
+ return output.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def build_sample_roster() -> CompRoster:
+ roster = CompRoster(
+ company="AcmeTech (Series A)",
+ as_of_date=date.today().isoformat(),
+ funding_stage="Series A",
+ comp_philosophy_target="P50",
+ preferred_stock_price=8.50,
+ )
+
+ # Bands (Engineering, P50 target, Tier1 = SF/NYC)
+ roster.bands = [
+ BandDefinition("L2", "Engineering", 115_000, 132_000, 155_000, 110_000, 132_000, 155_000, "Tier1"),
+ BandDefinition("L3", "Engineering", 148_000, 170_000, 198_000, 145_000, 170_000, 198_000, "Tier1"),
+ BandDefinition("L4", "Engineering", 185_000, 215_000, 248_000, 182_000, 215_000, 250_000, "Tier1"),
+ BandDefinition("M1", "Engineering", 170_000, 195_000, 225_000, 168_000, 195_000, 225_000, "Tier1"),
+ BandDefinition("L2", "Engineering", 95_000, 108_000, 125_000, 92_000, 108_000, 126_000, "Tier2"),
+ BandDefinition("L3", "Engineering", 122_000, 140_000, 162_000, 120_000, 140_000, 162_000, "Tier2"),
+ BandDefinition("L2", "Sales", 80_000, 92_000, 108_000, 78_000, 92_000, 108_000, "Tier1"),
+ BandDefinition("L3", "Sales", 95_000, 110_000, 128_000, 93_000, 110_000, 128_000, "Tier1"),
+ BandDefinition("M1", "Sales", 130_000, 150_000, 172_000, 128_000, 150_000, 172_000, "Tier1"),
+ BandDefinition("L2", "Product", 125_000, 145_000, 168_000, 123_000, 145_000, 168_000, "Tier1"),
+ BandDefinition("L3", "Product", 155_000, 178_000, 205_000, 153_000, 178_000, 205_000, "Tier1"),
+ BandDefinition("L2", "G&A", 85_000, 98_000, 115_000, 83_000, 98_000, 115_000, "Tier1"),
+ BandDefinition("L3", "G&A", 110_000, 128_000, 148_000, 108_000, 128_000, 148_000, "Tier1"),
+ ]
+
+ roster.employees = [
+ # Engineering — mix of scenarios
+ Employee("E001", "Aarav Shah", "Senior SWE (Backend)", "L3", "Engineering", "Tier1",
+ base_salary=168_000, bonus_target_pct=0.0, equity_shares=40_000,
+ equity_strike=1.50, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
+ benefits_annual=18_000, gender="M", ethnicity="Asian",
+ tenure_years=2.5, performance_rating=4, last_raise_months_ago=14,
+ last_equity_refresh_months_ago=None),
+
+ Employee("E002", "Yuki Tanaka", "Senior SWE (Frontend)", "L3", "Engineering", "Tier1",
+ base_salary=152_000, bonus_target_pct=0.0, equity_shares=30_000,
+ equity_strike=2.20, equity_current_409a=6.80, equity_vest_years_remaining=0.5,
+ benefits_annual=18_000, gender="F", ethnicity="Asian",
+ tenure_years=3.8, performance_rating=5, last_raise_months_ago=11,
+ last_equity_refresh_months_ago=30),
+ # Note: Yuki is high performer, near-vested, no recent refresh — flag expected
+
+ Employee("E003", "Marcus Johnson", "SWE II (Backend)", "L2", "Engineering", "Tier1",
+ base_salary=110_000, bonus_target_pct=0.0, equity_shares=15_000,
+ equity_strike=2.50, equity_current_409a=6.80, equity_vest_years_remaining=3.0,
+ benefits_annual=15_000, gender="M", ethnicity="Black",
+ tenure_years=1.2, performance_rating=3, last_raise_months_ago=12,
+ last_equity_refresh_months_ago=None),
+ # Note: Below band midpoint, recently hired — developing flag
+
+ Employee("E004", "Priya Nair", "Staff SWE", "L4", "Engineering", "Tier1",
+ base_salary=222_000, bonus_target_pct=0.0, equity_shares=60_000,
+ equity_strike=0.80, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
+ benefits_annual=18_000, gender="F", ethnicity="Asian",
+ tenure_years=4.2, performance_rating=5, last_raise_months_ago=8,
+ last_equity_refresh_months_ago=8),
+
+ Employee("E005", "Tom Rivera", "SWE II (Platform)", "L2", "Engineering", "Tier2",
+ base_salary=88_000, bonus_target_pct=0.0, equity_shares=12_000,
+ equity_strike=3.00, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
+ benefits_annual=14_000, gender="M", ethnicity="Hispanic",
+ tenure_years=1.8, performance_rating=4, last_raise_months_ago=22,
+ last_equity_refresh_months_ago=None),
+ # Note: No raise in 22 months, high performer — flag expected
+
+ Employee("E006", "Sarah Kim", "Eng Manager", "M1", "Engineering", "Tier1",
+ base_salary=192_000, bonus_target_pct=0.10, equity_shares=35_000,
+ equity_strike=1.20, equity_current_409a=6.80, equity_vest_years_remaining=1.8,
+ benefits_annual=18_000, gender="F", ethnicity="Asian",
+ tenure_years=2.8, performance_rating=4, last_raise_months_ago=9,
+ last_equity_refresh_months_ago=9),
+
+ # Sales
+ Employee("S001", "David Chen", "Account Executive (MM)", "L3", "Sales", "Tier1",
+ base_salary=105_000, bonus_target_pct=0.50, equity_shares=8_000,
+ equity_strike=3.50, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
+ benefits_annual=15_000, gender="M", ethnicity="Asian",
+ tenure_years=1.5, performance_rating=3, last_raise_months_ago=15,
+ last_equity_refresh_months_ago=None),
+
+ Employee("S002", "Amara Osei", "AE (Mid-Market)", "L3", "Sales", "Tier1",
+ base_salary=98_000, bonus_target_pct=0.50, equity_shares=6_000,
+ equity_strike=3.50, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
+ benefits_annual=15_000, gender="F", ethnicity="Black",
+ tenure_years=1.0, performance_rating=4, last_raise_months_ago=12,
+ last_equity_refresh_months_ago=None),
+ # Note: High performer, significantly below midpoint — flag expected
+
+ Employee("S003", "Jordan Blake", "Sales Manager", "M1", "Sales", "Tier1",
+ base_salary=155_000, bonus_target_pct=0.20, equity_shares=20_000,
+ equity_strike=2.00, equity_current_409a=6.80, equity_vest_years_remaining=1.5,
+ benefits_annual=16_000, gender="NB", ethnicity="White",
+ tenure_years=2.2, performance_rating=3, last_raise_months_ago=10,
+ last_equity_refresh_months_ago=10),
+
+ # Product
+ Employee("P001", "Nina Patel", "Senior PM", "L3", "Product", "Tier1",
+ base_salary=176_000, bonus_target_pct=0.10, equity_shares=22_000,
+ equity_strike=1.80, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
+ benefits_annual=17_000, gender="F", ethnicity="Asian",
+ tenure_years=2.0, performance_rating=4, last_raise_months_ago=12,
+ last_equity_refresh_months_ago=12),
+
+ # G&A
+ Employee("G001", "Chris Mueller", "Finance Manager", "L3", "G&A", "Tier1",
+ base_salary=125_000, bonus_target_pct=0.10, equity_shares=10_000,
+ equity_strike=2.80, equity_current_409a=6.80, equity_vest_years_remaining=3.0,
+ benefits_annual=16_000, gender="M", ethnicity="White",
+ tenure_years=1.5, performance_rating=3, last_raise_months_ago=15,
+ last_equity_refresh_months_ago=None),
+
+ Employee("G002", "Fatima Al-Hassan", "HR Operations", "L2", "G&A", "Tier1",
+ base_salary=82_000, bonus_target_pct=0.08, equity_shares=5_000,
+ equity_strike=4.00, equity_current_409a=6.80, equity_vest_years_remaining=3.5,
+ benefits_annual=14_000, gender="F", ethnicity="Middle Eastern",
+ tenure_years=0.8, performance_rating=3, last_raise_months_ago=8,
+ last_equity_refresh_months_ago=None),
+ # Note: Below band minimum — critical flag expected
+ ]
+
+ return roster
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def load_roster_from_json(path: str) -> CompRoster:
+ with open(path) as f:
+ data = json.load(f)
+ employees = [Employee(**e) for e in data.pop("employees", [])]
+ bands = [BandDefinition(**b) for b in data.pop("bands", [])]
+ roster = CompRoster(**data)
+ roster.employees = employees
+ roster.bands = bands
+ return roster
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Compensation Benchmarker — salary analysis and pay equity audit",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ python comp_benchmarker.py # Run sample roster
+ python comp_benchmarker.py --config roster.json # Load from JSON
+ python comp_benchmarker.py --export-csv # Output CSV
+ python comp_benchmarker.py --export-json # Output JSON template
+ """
+ )
+ parser.add_argument("--config", help="Path to JSON roster file")
+ parser.add_argument("--export-csv", action="store_true", help="Export analysis as CSV")
+ parser.add_argument("--export-json", action="store_true", help="Export sample roster as JSON template")
+ args = parser.parse_args()
+
+ if args.config:
+ roster = load_roster_from_json(args.config)
+ else:
+ roster = build_sample_roster()
+
+ if args.export_json:
+ data = asdict(roster)
+ print(json.dumps(data, indent=2))
+ return
+
+ if args.export_csv:
+ print(export_csv(roster))
+ return
+
+ print_report(roster)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/chro-advisor/scripts/hiring_plan_modeler.py b/skills/c-level-advisor/chro-advisor/scripts/hiring_plan_modeler.py
new file mode 100644
index 00000000..d0a62e8e
--- /dev/null
+++ b/skills/c-level-advisor/chro-advisor/scripts/hiring_plan_modeler.py
@@ -0,0 +1,572 @@
+#!/usr/bin/env python3
+"""
+Hiring Plan Modeler
+===================
+Builds hiring plans from business goals with cost projections.
+Outputs quarterly headcount plan, cost model, and risk assessment.
+
+Usage:
+ python hiring_plan_modeler.py # Run with built-in sample data
+ python hiring_plan_modeler.py --config plan.json # Load from JSON config
+ python hiring_plan_modeler.py --help
+"""
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, date
+from typing import Optional
+import csv
+import io
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HireTarget:
+ """One planned hire."""
+ role: str
+ level: str # L1, L2, L3, L4, M1, M2, M3, VP, C-Suite
+ function: str # Engineering, Sales, Product, G&A, Marketing, CS
+ quarter: str # Q1-2025, Q2-2025, etc.
+ base_salary: int # Annual, USD
+ bonus_pct: float # % of base (e.g., 0.10 for 10%)
+ equity_annual_usd: int # Annualized equity value at current 409A
+ benefits_annual: int # Employer-paid benefits
+ recruiter_fee_pct: float= 0.20 # Agency fee if used (0 for internal recruiter)
+ ramp_months: int = 3 # Months to full productivity
+ priority: str = "High" # High / Medium / Low
+ business_case: str = ""
+ open_to_internal: bool = False
+
+
+@dataclass
+class HiringPlan:
+ company: str
+ plan_period: str # e.g., "2025 Annual"
+ current_headcount: int
+ target_revenue: int # Annual target revenue ($)
+ current_revenue: int # Current ARR ($)
+ hires: list[HireTarget] = field(default_factory=list)
+
+ # Cost overheads beyond comp
+ overhead_rate: float = 0.25 # Workspace, software, onboarding overhead as % of base
+ internal_recruiter_cost: int = 0 # If you have an internal recruiter, annual cost
+
+
+# ---------------------------------------------------------------------------
+# Computation
+# ---------------------------------------------------------------------------
+
+def quarter_to_sortkey(q: str) -> tuple[int, int]:
+ """Parse 'Q2-2025' → (2025, 2)"""
+ parts = q.upper().split("-")
+ if len(parts) == 2:
+ q_num = int(parts[0].replace("Q", ""))
+ year = int(parts[1])
+ return (year, q_num)
+ return (9999, 9)
+
+
+def get_quarters(hires: list[HireTarget]) -> list[str]:
+ """Return sorted unique quarters from hire list."""
+ quarters = sorted(set(h.quarter for h in hires), key=quarter_to_sortkey)
+ return quarters
+
+
+def compute_hire_costs(hire: HireTarget) -> dict:
+ """Compute total first-year cost for one hire."""
+ total_comp = hire.base_salary + int(hire.base_salary * hire.bonus_pct) + hire.equity_annual_usd + hire.benefits_annual
+ recruiter_fee = int(hire.base_salary * hire.recruiter_fee_pct)
+ overhead = int(hire.base_salary * 0.25) # workspace, tools, onboarding
+ ramp_productivity_cost = int(hire.base_salary * (hire.ramp_months / 12)) # cost during ramp
+
+ return {
+ "base_salary": hire.base_salary,
+ "target_bonus": int(hire.base_salary * hire.bonus_pct),
+ "equity_annual": hire.equity_annual_usd,
+ "benefits": hire.benefits_annual,
+ "total_comp": total_comp,
+ "recruiter_fee": recruiter_fee,
+ "overhead": overhead,
+ "ramp_cost": ramp_productivity_cost,
+ "first_year_total": total_comp + recruiter_fee + overhead,
+ "fully_loaded_first_year": total_comp + recruiter_fee + overhead + ramp_productivity_cost,
+ }
+
+
+def summarize_by_quarter(plan: HiringPlan) -> dict[str, dict]:
+ """Aggregate headcount and costs per quarter."""
+ quarters = get_quarters(plan.hires)
+ summary = {}
+ running_headcount = plan.current_headcount
+
+ for q in quarters:
+ q_hires = [h for h in plan.hires if h.quarter == q]
+ q_costs = [compute_hire_costs(h) for h in q_hires]
+
+ total_comp = sum(c["total_comp"] for c in q_costs)
+ total_first_year = sum(c["first_year_total"] for c in q_costs)
+ recruiter_fees = sum(c["recruiter_fee"] for c in q_costs)
+
+ running_headcount += len(q_hires)
+
+ summary[q] = {
+ "new_hires": len(q_hires),
+ "headcount_eop": running_headcount,
+ "total_annual_comp_added": total_comp,
+ "total_first_year_cost": total_first_year,
+ "recruiter_fees": recruiter_fees,
+ "hires": q_hires,
+ "costs": q_costs,
+ }
+
+ return summary
+
+
+def summarize_by_function(plan: HiringPlan) -> dict[str, dict]:
+ """Aggregate headcount and costs per function."""
+ functions: dict[str, dict] = {}
+ for hire in plan.hires:
+ fn = hire.function
+ if fn not in functions:
+ functions[fn] = {"count": 0, "total_comp": 0, "total_first_year": 0, "roles": []}
+ costs = compute_hire_costs(hire)
+ functions[fn]["count"] += 1
+ functions[fn]["total_comp"] += costs["total_comp"]
+ functions[fn]["total_first_year"] += costs["first_year_total"]
+ functions[fn]["roles"].append(hire.role)
+ return functions
+
+
+def compute_totals(plan: HiringPlan) -> dict:
+ all_costs = [compute_hire_costs(h) for h in plan.hires]
+ total_hires = len(plan.hires)
+ total_comp = sum(c["total_comp"] for c in all_costs)
+ total_first_year = sum(c["first_year_total"] for c in all_costs)
+ total_fully_loaded = sum(c["fully_loaded_first_year"] for c in all_costs)
+ total_recruiter = sum(c["recruiter_fee"] for c in all_costs)
+
+ final_headcount = plan.current_headcount + total_hires
+ revenue_per_employee = plan.target_revenue / final_headcount if final_headcount > 0 else 0
+ revenue_per_employee_current = plan.current_revenue / plan.current_headcount if plan.current_headcount > 0 else 0
+
+ return {
+ "total_hires": total_hires,
+ "final_headcount": final_headcount,
+ "headcount_growth_pct": ((final_headcount - plan.current_headcount) / plan.current_headcount * 100) if plan.current_headcount > 0 else 0,
+ "total_annual_comp_added": total_comp,
+ "total_first_year_cost": total_first_year,
+ "total_fully_loaded_first_year": total_fully_loaded,
+ "total_recruiter_fees": total_recruiter,
+ "revenue_per_employee_target": revenue_per_employee,
+ "revenue_per_employee_current": revenue_per_employee_current,
+ "avg_comp_per_hire": total_comp // total_hires if total_hires > 0 else 0,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Risk assessment
+# ---------------------------------------------------------------------------
+
+def assess_risks(plan: HiringPlan, totals: dict) -> list[dict]:
+ risks = []
+
+ # Headcount growth too fast
+ growth_pct = totals["headcount_growth_pct"]
+ if growth_pct > 80:
+ risks.append({
+ "severity": "HIGH",
+ "category": "Execution",
+ "finding": f"Headcount growing {growth_pct:.0f}% this period. "
+ "Culture and processes rarely scale this fast without breakage.",
+ "recommendation": "Stagger Q3/Q4 hires. Validate Q1/Q2 cohort is onboarded before next wave."
+ })
+ elif growth_pct > 50:
+ risks.append({
+ "severity": "MEDIUM",
+ "category": "Execution",
+ "finding": f"Headcount growing {growth_pct:.0f}% — significant scaling challenge.",
+ "recommendation": "Ensure onboarding infrastructure scales. Assign buddy/mentor to each hire."
+ })
+
+ # High concentration in one quarter
+ quarters = get_quarters(plan.hires)
+ q_counts = {q: sum(1 for h in plan.hires if h.quarter == q) for q in quarters}
+ max_q = max(q_counts.values()) if q_counts else 0
+ if max_q > len(plan.hires) * 0.5 and max_q > 4:
+ heavy_q = [q for q, c in q_counts.items() if c == max_q][0]
+ risks.append({
+ "severity": "MEDIUM",
+ "category": "Hiring Execution",
+ "finding": f"More than 50% of hires planned in {heavy_q} ({max_q} hires). "
+ "Recruiting capacity and onboarding bandwidth may be insufficient.",
+ "recommendation": "Spread hires across quarters. Hiring pipeline needs to start 60–90 days before target start date."
+ })
+
+ # Revenue per employee declining
+ if totals["revenue_per_employee_target"] < totals["revenue_per_employee_current"] * 0.7:
+ risks.append({
+ "severity": "HIGH",
+ "category": "Financial",
+ "finding": f"Revenue per employee declining from ${totals['revenue_per_employee_current']:,.0f} to "
+ f"${totals['revenue_per_employee_target']:,.0f} — a {((totals['revenue_per_employee_target']/totals['revenue_per_employee_current'])-1)*100:.0f}% drop.",
+ "recommendation": "Validate that revenue model supports this headcount. Is target revenue achievable with this team?"
+ })
+
+ # Low priority hires consuming budget
+ low_priority_hires = [h for h in plan.hires if h.priority == "Low"]
+ if low_priority_hires:
+ lp_cost = sum(compute_hire_costs(h)["first_year_total"] for h in low_priority_hires)
+ risks.append({
+ "severity": "MEDIUM",
+ "category": "Prioritization",
+ "finding": f"{len(low_priority_hires)} 'Low' priority hires consuming ${lp_cost:,.0f} in first-year costs.",
+ "recommendation": "Consider deferring Low priority hires to preserve runway. Cut these first if budget tightens."
+ })
+
+ # Hires without business cases
+ no_case = [h for h in plan.hires if not h.business_case]
+ if no_case:
+ risks.append({
+ "severity": "MEDIUM",
+ "category": "Governance",
+ "finding": f"{len(no_case)} hires have no documented business case: {', '.join(h.role for h in no_case[:5])}{'...' if len(no_case) > 5 else ''}",
+ "recommendation": "Every hire over $80K should have a written business case. What revenue or risk does this role address?"
+ })
+
+ # High recruiter fee exposure
+ if totals["total_recruiter_fees"] > 100_000:
+ risks.append({
+ "severity": "LOW",
+ "category": "Cost",
+ "finding": f"${totals['total_recruiter_fees']:,.0f} in recruiter fees. "
+ "Consider whether internal recruiter investment would be cheaper at this hiring volume.",
+ "recommendation": f"Internal recruiter at $120–150K fully loaded pays off at 3–4 hires/year vs. agency fees."
+ })
+
+ # No risks — that's itself a flag
+ if not risks:
+ risks.append({
+ "severity": "INFO",
+ "category": "General",
+ "finding": "No major risks flagged. Plan appears well-structured.",
+ "recommendation": "Validate assumptions: time-to-fill estimates, revenue model, and Q1 hiring pipeline status."
+ })
+
+ return risks
+
+
+# ---------------------------------------------------------------------------
+# Formatting / Output
+# ---------------------------------------------------------------------------
+
+def fmt(n: int) -> str:
+ return f"${n:,.0f}"
+
+
+def pct(n: float) -> str:
+ return f"{n:.1f}%"
+
+
+def print_report(plan: HiringPlan):
+ WIDTH = 72
+ SEP = "=" * WIDTH
+ sep = "-" * WIDTH
+
+ print(SEP)
+ print(f" HIRING PLAN: {plan.company}")
+ print(f" Period: {plan.plan_period} | Generated: {date.today().isoformat()}")
+ print(SEP)
+
+ totals = compute_totals(plan)
+ q_summary = summarize_by_quarter(plan)
+ fn_summary = summarize_by_function(plan)
+ risks = assess_risks(plan, totals)
+
+ # Executive summary
+ print("\n[ EXECUTIVE SUMMARY ]")
+ print(sep)
+ print(f" Current headcount: {plan.current_headcount:>5}")
+ print(f" Planned hires: {totals['total_hires']:>5}")
+ print(f" Final headcount: {totals['final_headcount']:>5} (+{totals['headcount_growth_pct']:.0f}%)")
+ print(f" Current ARR: {fmt(plan.current_revenue):>12}")
+ print(f" Target revenue: {fmt(plan.target_revenue):>12}")
+ print(f" Revenue/employee now: {fmt(int(totals['revenue_per_employee_current'])):>12}")
+ print(f" Revenue/employee target: {fmt(int(totals['revenue_per_employee_target'])):>12}")
+ print()
+ print(f" Total annual comp added: {fmt(totals['total_annual_comp_added']):>12}")
+ print(f" Total first-year cost: {fmt(totals['total_first_year_cost']):>12}")
+ print(f" Fully loaded (w/ ramp): {fmt(totals['total_fully_loaded_first_year']):>12}")
+ print(f" Recruiter fees: {fmt(totals['total_recruiter_fees']):>12}")
+ print(f" Avg comp per hire: {fmt(totals['avg_comp_per_hire']):>12}")
+
+ # Quarterly breakdown
+ print(f"\n[ QUARTERLY HEADCOUNT PLAN ]")
+ print(sep)
+ print(f" {'Quarter':<10} {'New Hires':>10} {'HC (EOP)':>10} {'Comp Added':>14} {'1yr Cost':>14} {'Recruiter $':>12}")
+ print(f" {'-'*10} {'-'*10} {'-'*10} {'-'*14} {'-'*14} {'-'*12}")
+ for q, data in q_summary.items():
+ print(f" {q:<10} {data['new_hires']:>10} {data['headcount_eop']:>10} "
+ f"{fmt(data['total_annual_comp_added']):>14} "
+ f"{fmt(data['total_first_year_cost']):>14} "
+ f"{fmt(data['recruiter_fees']):>12}")
+
+ # By function
+ print(f"\n[ HEADCOUNT BY FUNCTION ]")
+ print(sep)
+ print(f" {'Function':<18} {'Hires':>7} {'Annual Comp':>14} {'1yr Cost':>14}")
+ print(f" {'-'*18} {'-'*7} {'-'*14} {'-'*14}")
+ for fn, data in sorted(fn_summary.items(), key=lambda x: -x[1]["count"]):
+ print(f" {fn:<18} {data['count']:>7} {fmt(data['total_comp']):>14} {fmt(data['total_first_year']):>14}")
+
+ # Hire detail
+ print(f"\n[ HIRE DETAIL ]")
+ print(sep)
+ print(f" {'Role':<30} {'Fn':<14} {'Lvl':<6} {'Q':<8} {'Base':>10} {'Total Comp':>12} {'Priority':<8}")
+ print(f" {'-'*30} {'-'*14} {'-'*6} {'-'*8} {'-'*10} {'-'*12} {'-'*8}")
+ for h in sorted(plan.hires, key=lambda x: quarter_to_sortkey(x.quarter)):
+ costs = compute_hire_costs(h)
+ print(f" {h.role:<30} {h.function:<14} {h.level:<6} {h.quarter:<8} "
+ f"{fmt(h.base_salary):>10} {fmt(costs['total_comp']):>12} {h.priority:<8}")
+ if h.business_case:
+ bc = h.business_case[:60] + "..." if len(h.business_case) > 60 else h.business_case
+ print(f" {'':>30} ↳ {bc}")
+
+ # Risk assessment
+ print(f"\n[ RISK ASSESSMENT ]")
+ print(sep)
+ sev_order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "INFO": 3}
+ for risk in sorted(risks, key=lambda r: sev_order.get(r["severity"], 99)):
+ sev = risk["severity"]
+ marker = {"HIGH": "⚠ HIGH", "MEDIUM": "◆ MED ", "LOW": "◇ LOW ", "INFO": "ℹ INFO"}[sev]
+ print(f"\n [{marker}] {risk['category']}")
+ # Wrap finding
+ finding = risk["finding"]
+ words = finding.split()
+ line = " Finding: "
+ for w in words:
+ if len(line) + len(w) + 1 > WIDTH - 2:
+ print(line)
+ line = " " + w + " "
+ else:
+ line += w + " "
+ if line.strip():
+ print(line)
+ reco = risk["recommendation"]
+ words = reco.split()
+ line = " Action: "
+ for w in words:
+ if len(line) + len(w) + 1 > WIDTH - 2:
+ print(line)
+ line = " " + w + " "
+ else:
+ line += w + " "
+ if line.strip():
+ print(line)
+
+ print(f"\n{SEP}\n")
+
+
+def export_csv(plan: HiringPlan) -> str:
+ """Return CSV of hire detail."""
+ output = io.StringIO()
+ writer = csv.writer(output)
+ writer.writerow(["Role", "Function", "Level", "Quarter", "Priority",
+ "Base Salary", "Bonus Target", "Equity Annual", "Benefits",
+ "Total Comp", "Recruiter Fee", "Overhead", "First Year Total",
+ "Ramp Months", "Open to Internal", "Business Case"])
+ for h in plan.hires:
+ c = compute_hire_costs(h)
+ writer.writerow([h.role, h.function, h.level, h.quarter, h.priority,
+ h.base_salary, c["target_bonus"], h.equity_annual_usd, h.benefits_annual,
+ c["total_comp"], c["recruiter_fee"], c["overhead"], c["first_year_total"],
+ h.ramp_months, h.open_to_internal, h.business_case])
+ return output.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def build_sample_plan() -> HiringPlan:
+ """Sample Series A → B hiring plan."""
+ plan = HiringPlan(
+ company="AcmeTech (Series A)",
+ plan_period="2025 Annual",
+ current_headcount=32,
+ current_revenue=3_500_000,
+ target_revenue=8_000_000,
+ overhead_rate=0.25,
+ internal_recruiter_cost=140_000,
+ )
+
+ plan.hires = [
+ # Q1 — Foundation hires
+ HireTarget(
+ role="Staff Software Engineer (Backend)",
+ level="L4", function="Engineering", quarter="Q1-2025",
+ base_salary=185_000, bonus_pct=0.0, equity_annual_usd=25_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="High", open_to_internal=True,
+ business_case="Core API team is bottleneck for 3 roadmap items. Staff-level needed to lead architecture."
+ ),
+ HireTarget(
+ role="Account Executive (Mid-Market)",
+ level="L3", function="Sales", quarter="Q1-2025",
+ base_salary=95_000, bonus_pct=0.50, equity_annual_usd=10_000,
+ benefits_annual=15_000, recruiter_fee_pct=0.18, ramp_months=4,
+ priority="High",
+ business_case="Pipeline coverage at 1.8x quota. Need 2.5x by Q2. AE adds $600K ARR/year at ramp."
+ ),
+ HireTarget(
+ role="Product Designer (Senior)",
+ level="L3", function="Product", quarter="Q1-2025",
+ base_salary=145_000, bonus_pct=0.0, equity_annual_usd=18_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="High",
+ business_case="Single designer for 4 squads. UX debt slowing enterprise deals requiring onboarding improvements."
+ ),
+
+ # Q2 — Growth hires
+ HireTarget(
+ role="Engineering Manager (Frontend)",
+ level="M1", function="Engineering", quarter="Q2-2025",
+ base_salary=175_000, bonus_pct=0.10, equity_annual_usd=22_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.20, ramp_months=3,
+ priority="High",
+ business_case="Frontend team at 7 ICs with no dedicated EM. Performance review debt is high; manager needed."
+ ),
+ HireTarget(
+ role="Account Executive (Mid-Market)",
+ level="L2", function="Sales", quarter="Q2-2025",
+ base_salary=85_000, bonus_pct=0.50, equity_annual_usd=8_000,
+ benefits_annual=15_000, recruiter_fee_pct=0.18, ramp_months=4,
+ priority="High",
+ business_case="Second AE to reach 2.5x pipeline coverage target."
+ ),
+ HireTarget(
+ role="Customer Success Manager",
+ level="L2", function="Customer Success", quarter="Q2-2025",
+ base_salary=90_000, bonus_pct=0.15, equity_annual_usd=8_000,
+ benefits_annual=15_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="Medium",
+ business_case="CSM:account ratio at 1:60, industry standard 1:30. NRR has dipped 4pts in 2 quarters."
+ ),
+ HireTarget(
+ role="Data Engineer",
+ level="L2", function="Engineering", quarter="Q2-2025",
+ base_salary=155_000, bonus_pct=0.0, equity_annual_usd=18_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=3,
+ priority="Medium",
+ business_case="Analytics infrastructure blocking product analytics, customer dashboards, and board metrics."
+ ),
+
+ # Q3 — Scale hires
+ HireTarget(
+ role="Senior Software Engineer (Backend)",
+ level="L3", function="Engineering", quarter="Q3-2025",
+ base_salary=165_000, bonus_pct=0.0, equity_annual_usd=20_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="High",
+ business_case="Backend team needs capacity to deliver Q3 roadmap without delaying Q4 items."
+ ),
+ HireTarget(
+ role="Head of Marketing",
+ level="M3", function="Marketing", quarter="Q3-2025",
+ base_salary=180_000, bonus_pct=0.15, equity_annual_usd=30_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.20, ramp_months=3,
+ priority="High",
+ business_case="No marketing function. 100% of pipeline is outbound. Need inbound by Q1-2026 for Series B."
+ ),
+ HireTarget(
+ role="People Operations Manager",
+ level="M1", function="G&A", quarter="Q3-2025",
+ base_salary=120_000, bonus_pct=0.10, equity_annual_usd=12_000,
+ benefits_annual=16_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="Medium",
+ business_case="Founders spending 8hrs/week on HR ops at 40 employees. Unscalable. First dedicated HR hire."
+ ),
+
+ # Q4 — Stretch hires (conditional on revenue milestone)
+ HireTarget(
+ role="Senior Software Engineer (Frontend)",
+ level="L3", function="Engineering", quarter="Q4-2025",
+ base_salary=160_000, bonus_pct=0.0, equity_annual_usd=18_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="Medium",
+ business_case="Conditional on Q3 ARR exceeding $5.5M. Frontend team capacity planning for 2026 roadmap."
+ ),
+ HireTarget(
+ role="Account Executive (Enterprise)",
+ level="L4", function="Sales", quarter="Q4-2025",
+ base_salary=120_000, bonus_pct=0.60, equity_annual_usd=15_000,
+ benefits_annual=15_000, recruiter_fee_pct=0.20, ramp_months=6,
+ priority="Low",
+ business_case="Enterprise motion exploratory. Requires ICP validation in Q2-Q3 before committing."
+ ),
+ HireTarget(
+ role="DevOps / Platform Engineer",
+ level="L3", function="Engineering", quarter="Q4-2025",
+ base_salary=150_000, bonus_pct=0.0, equity_annual_usd=18_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=3,
+ priority="Low",
+ business_case="Platform reliability becoming bottleneck. Conditional on uptime SLA breaches continuing in Q3."
+ ),
+ ]
+
+ return plan
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def load_plan_from_json(path: str) -> HiringPlan:
+ with open(path) as f:
+ data = json.load(f)
+ hires = [HireTarget(**h) for h in data.pop("hires", [])]
+ plan = HiringPlan(**data)
+ plan.hires = hires
+ return plan
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Hiring Plan Modeler — build headcount plans with cost projections",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ python hiring_plan_modeler.py # Run sample plan
+ python hiring_plan_modeler.py --config plan.json # Load from JSON
+ python hiring_plan_modeler.py --export-csv # Output CSV of hires
+ python hiring_plan_modeler.py --export-json # Output plan as JSON template
+ """
+ )
+ parser.add_argument("--config", help="Path to JSON plan file")
+ parser.add_argument("--export-csv", action="store_true", help="Export hire detail as CSV")
+ parser.add_argument("--export-json", action="store_true", help="Export sample plan as JSON template")
+ args = parser.parse_args()
+
+ if args.config:
+ plan = load_plan_from_json(args.config)
+ else:
+ plan = build_sample_plan()
+
+ if args.export_json:
+ data = asdict(plan)
+ print(json.dumps(data, indent=2))
+ return
+
+ if args.export_csv:
+ print(export_csv(plan))
+ return
+
+ print_report(plan)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/ciso-advisor/SKILL.md b/skills/c-level-advisor/ciso-advisor/SKILL.md
new file mode 100644
index 00000000..ef7d035c
--- /dev/null
+++ b/skills/c-level-advisor/ciso-advisor/SKILL.md
@@ -0,0 +1,135 @@
+---
+name: "ciso-advisor"
+description: "Security leadership for growth-stage companies. Risk quantification in dollars, compliance roadmap (SOC 2/ISO 27001/HIPAA/GDPR), security architecture strategy, incident response leadership, and board-level security reporting. Use when building security programs, justifying security budget, selecting compliance frameworks, managing incidents, assessing vendor risk, or when user mentions CISO, security strategy, compliance roadmap, zero trust, or board security reporting."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: ciso-leadership
+ updated: 2026-03-05
+ python-tools: risk_quantifier.py, compliance_tracker.py
+ frameworks: risk-based-security, zero-trust, defense-in-depth
+---
+
+# CISO Advisor
+
+Risk-based security frameworks for growth-stage companies. Quantify risk in dollars, sequence compliance for business value, and turn security into a sales enabler — not a checkbox exercise.
+
+## Keywords
+CISO, security strategy, risk quantification, ALE, SLE, ARO, security posture, compliance roadmap, SOC 2, ISO 27001, HIPAA, GDPR, zero trust, defense in depth, incident response, board security reporting, vendor assessment, security budget, cyber risk, program maturity
+
+## Quick Start
+
+```bash
+python scripts/risk_quantifier.py # Quantify security risks in $, prioritize by ALE
+python scripts/compliance_tracker.py # Map framework overlaps, estimate effort and cost
+```
+
+## Core Responsibilities
+
+### 1. Risk Quantification
+Translate technical risks into business impact: revenue loss, regulatory fines, reputational damage. Use ALE to prioritize. See `references/security_strategy.md`.
+
+**Formula:** `ALE = SLE × ARO` (Single Loss Expectancy × Annual Rate of Occurrence). Board language: "This risk has $X expected annual loss. Mitigation costs $Y."
+
+### 2. Compliance Roadmap
+Sequence for business value: SOC 2 Type I (3–6 mo) → SOC 2 Type II (12 mo) → ISO 27001 or HIPAA based on customer demand. See `references/compliance_roadmap.md` for timelines and costs.
+
+### 3. Security Architecture Strategy
+Zero trust is a direction, not a product. Sequence: identity (IAM + MFA) → network segmentation → data classification. Defense in depth beats single-layer reliance. See `references/security_strategy.md`.
+
+### 4. Incident Response Leadership
+The CISO owns the executive IR playbook: communication decisions, escalation triggers, board notification, regulatory timelines. See `references/incident_response.md` for templates.
+
+### 5. Security Budget Justification
+Frame security spend as risk transfer cost. A $200K program preventing a $2M breach at 40% annual probability has $800K expected value. See `references/security_strategy.md`.
+
+### 6. Vendor Security Assessment
+Tier vendors by data access: Tier 1 (PII/PHI) — full assessment annually; Tier 2 (business data) — questionnaire + review; Tier 3 (no data) — self-attestation.
+
+## Key Questions a CISO Asks
+
+- "What's our crown jewel data, and who can access it right now?"
+- "If we had a breach today, what's our regulatory notification timeline?"
+- "Which compliance framework do our top 3 prospects actually require?"
+- "What's our blast radius if our largest SaaS vendor is compromised?"
+- "We spent $X on security last year — what specific risks did that reduce?"
+
+## Security Metrics
+
+| Category | Metric | Target |
+|----------|--------|--------|
+| Risk | ALE coverage (mitigated risk / total risk) | > 80% |
+| Detection | Mean Time to Detect (MTTD) | < 24 hours |
+| Response | Mean Time to Respond (MTTR) | < 4 hours |
+| Compliance | Controls passing audit | > 95% |
+| Hygiene | Critical patches within SLA | > 99% |
+| Access | Privileged accounts reviewed quarterly | 100% |
+| Vendor | Tier 1 vendors assessed annually | 100% |
+| Training | Phishing simulation click rate | < 5% |
+
+## Red Flags
+
+- Security budget justified by "industry benchmarks" rather than risk analysis
+- Certifications pursued before basic hygiene (patching, MFA, backups)
+- No documented asset inventory — can't protect what you don't know you have
+- IR plan exists but has never been tested (tabletop or live drill)
+- Security team reports to IT, not executive level — misaligned incentives
+- Single vendor for identity + endpoint + email — one breach, total exposure
+- Security questionnaire backlog > 30 days — silently losing enterprise deals
+
+## Integration with Other C-Suite Roles
+
+| When... | CISO works with... | To... |
+|---------|--------------------|-------|
+| Enterprise sales | CRO | Answer questionnaires, unblock deals |
+| New product features | CTO/CPO | Threat modeling, security review |
+| Compliance budget | CFO | Size program against risk exposure |
+| Vendor contracts | Legal/COO | Security SLAs and right-to-audit |
+| M&A due diligence | CEO/CFO | Target security posture assessment |
+| Incident occurs | CEO/Legal | Response coordination and disclosure |
+
+## Detailed References
+- `references/security_strategy.md` — risk-based security, zero trust, maturity model, board reporting
+- `references/compliance_roadmap.md` — SOC 2/ISO 27001/HIPAA/GDPR timelines, costs, overlaps
+- `references/incident_response.md` — executive IR playbook, communication templates, tabletop design
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- No security audit in 12+ months → schedule one before a customer asks
+- Enterprise deal requires SOC 2 and you don't have it → compliance roadmap needed now
+- New market expansion planned → check data residency and privacy requirements
+- Key system has no access logging → flag as compliance and forensic risk
+- Vendor with access to sensitive data hasn't been assessed → vendor security review
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Assess our security posture" | Risk register with quantified business impact (ALE) |
+| "We need SOC 2" | Compliance roadmap with timeline, cost, effort, quick wins |
+| "Prep for security audit" | Gap analysis against target framework with remediation plan |
+| "We had an incident" | IR coordination plan + communication templates |
+| "Security board section" | Risk posture summary, compliance status, incident report |
+
+## Reasoning Technique: Risk-Based Reasoning
+
+Evaluate every decision through probability × impact. Quantify risks in business terms (dollars, not severity labels). Prioritize by expected annual loss.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/c-level-advisor/ciso-advisor/references/compliance_roadmap.md b/skills/c-level-advisor/ciso-advisor/references/compliance_roadmap.md
new file mode 100644
index 00000000..68c4aca1
--- /dev/null
+++ b/skills/c-level-advisor/ciso-advisor/references/compliance_roadmap.md
@@ -0,0 +1,370 @@
+# Compliance Roadmap Reference
+
+## Decision Framework: Which Framework First?
+
+**Start here — who are your customers?**
+
+```
+Enterprise SaaS (B2B, US market) → SOC 2 Type II first
+Healthcare / health data → HIPAA + SOC 2 together
+EU customers or EU-resident data → GDPR (non-optional if applicable)
+EU enterprise sales → ISO 27001 + GDPR
+Government / defense → FedRAMP / CMMC (separate scope)
+All of the above (Series B+) → Multi-framework efficiency approach
+```
+
+**The sequencing principle:** SOC 2 Type I is the fastest proof of intent (3–6 months). Type II is the credibility signal (12 months). Everything else builds on your control library.
+
+---
+
+## 1. SOC 2
+
+### What It Is
+SOC 2 is an attestation (not a certification) that your controls meet the AICPA Trust Service Criteria. An independent CPA firm audits your controls and issues a report.
+
+- **Type I:** Controls are suitably designed at a point in time (snapshot). Lower credibility but faster.
+- **Type II:** Controls operated effectively over a period of time (minimum 6 months). This is what enterprise buyers want.
+
+### Trust Service Criteria (TSC)
+You must include **Security** (CC). Others are optional:
+| Criteria | When to add |
+|---|---|
+| Security (CC) | Always required |
+| Availability | If uptime SLAs are contractual |
+| Confidentiality | If you process confidential third-party data |
+| Processing Integrity | If accuracy of processing is critical (fintech, data processing) |
+| Privacy | If you make privacy commitments beyond GDPR/CCPA scope |
+
+Most startups: **Security + Availability** is sufficient.
+
+### Timeline: SOC 2 Type I
+
+| Phase | Duration | Activities |
+|---|---|---|
+| Readiness assessment | 2–4 weeks | Gap analysis against CC criteria, identify control owners |
+| Policy documentation | 4–6 weeks | Write ~15–20 policies (acceptable use, access control, change management, etc.) |
+| Control implementation | 4–8 weeks | Deploy technical controls, fix gaps identified in readiness |
+| Evidence collection | 2–4 weeks | Screenshots, logs, configs — auditor will sample these |
+| Audit fieldwork | 2–4 weeks | CPA firm reviews evidence, interviews control owners |
+| Report issuance | 2–4 weeks | Report issued, reviewed, shared with customers |
+| **Total** | **3–6 months** | — |
+
+### Timeline: SOC 2 Type II (after Type I)
+
+| Phase | Duration | Notes |
+|---|---|---|
+| Observation period | 6–12 months | Controls must operate consistently — no exceptions |
+| Audit fieldwork | 4–6 weeks | Auditor samples evidence across full period |
+| Report issuance | 2–4 weeks | — |
+| **Total from Type I** | **9–18 months** | Faster if Type I was clean |
+
+### Cost Estimates
+
+| Item | SOC 2 Type I | SOC 2 Type II |
+|---|---|---|
+| Audit firm fees | $15,000–$35,000 | $25,000–$60,000 |
+| Compliance platform (Vanta, Drata, Secureframe) | $12,000–$30,000/yr | Same platform |
+| External counsel / vCISO | $10,000–$30,000 | $5,000–$15,000 maintenance |
+| Internal time (eng + ops) | 200–400 hours | 100–200 hours/yr |
+| **Total first year** | **$40,000–$100,000** | **+$30,000–$75,000** |
+
+**Cost optimization tips:**
+- Use a compliance platform (Vanta, Drata, Secureframe) — automated evidence collection halves audit cost
+- Choose a mid-tier audit firm; Big 4 is overkill for startups
+- Type I and Type II with same auditor = continuity discount
+
+### Common Failure Modes
+1. Controls documented but not operating (access reviews on paper only)
+2. Exceptions during observation period (one admin account without MFA = finding)
+3. No formal security awareness training (required for CC criteria)
+4. Change management not followed (no ticket for that production change)
+5. Vendor risk management missing (you must assess your critical vendors)
+
+---
+
+## 2. ISO 27001
+
+### What It Is
+ISO 27001 is an internationally recognized certification for an Information Security Management System (ISMS). Unlike SOC 2, it's a certification (pass/fail), not an attestation report. Issued by accredited certification bodies (BSI, Bureau Veritas, DNV, TÜV).
+
+**Why ISO 27001 over SOC 2:** EU enterprise buyers, government contracts, and global markets often prefer or require ISO 27001. It's geographically neutral.
+
+### Scope Decision
+ISO 27001 scope is flexible — you can certify a subset of the organization.
+- **Narrow scope:** The production environment only — fastest, cheapest
+- **Full scope:** Entire organization — most credibility, highest effort
+- **Recommended for startups:** Production environment + key business processes
+
+### Certification Timeline
+
+| Phase | Duration | Activities |
+|---|---|---|
+| Gap analysis | 2–4 weeks | Assess current state vs. 93 controls in Annex A |
+| ISMS design | 4–8 weeks | Scope, risk methodology, SoA (Statement of Applicability) |
+| Policy and procedure development | 6–10 weeks | Mandatory documents: risk treatment plan, asset register, ISMS policy |
+| Risk assessment | 4–6 weeks | Identify, analyze, evaluate risks; produce risk register |
+| Control implementation | 8–16 weeks | Implement gaps from risk assessment |
+| Internal audit | 2–4 weeks | First internal audit of ISMS |
+| Management review | 1–2 weeks | Leadership sign-off on ISMS |
+| Stage 1 audit (documentation) | 1–2 weeks | Certification body reviews docs and scope |
+| Stage 2 audit (implementation) | 1–2 weeks | Certification body verifies controls are operating |
+| Certification issued | 1–2 weeks | Certificate valid for 3 years with annual surveillance audits |
+| **Total** | **9–18 months** | — |
+
+### Cost Estimates
+
+| Item | Cost |
+|---|---|
+| Certification body fees (Stage 1 + Stage 2) | $15,000–$40,000 |
+| Annual surveillance audits | $8,000–$20,000/yr |
+| vCISO / consultant (if not in-house) | $30,000–$80,000 |
+| GRC platform | $10,000–$25,000/yr |
+| Internal time | 400–800 hours |
+| **Total first year** | **$55,000–$150,000** |
+
+### Mandatory ISO 27001:2022 Documents
+- ISMS scope document
+- Information security policy
+- Risk assessment methodology
+- Risk register with risk treatment plan
+- Statement of Applicability (SoA)
+- Asset inventory
+- Competence and awareness records
+- Internal audit reports
+- Management review minutes
+- Nonconformity and corrective action records
+
+---
+
+## 3. HIPAA for Health Tech Startups
+
+### When HIPAA Applies
+HIPAA applies if you are a **Covered Entity** (healthcare provider, health plan, clearinghouse) or a **Business Associate** (you process, store, or transmit Protected Health Information on behalf of a Covered Entity).
+
+**Key trigger:** If your product touches patient data in any way and a US healthcare provider uses your product, you are likely a Business Associate. You must sign a **BAA (Business Associate Agreement)** with each Covered Entity customer.
+
+### HIPAA Rule Structure
+| Rule | Focus | Key Requirements |
+|---|---|---|
+| Privacy Rule | How PHI can be used and disclosed | Minimum necessary, patient rights, notice of privacy practices |
+| Security Rule | Technical and physical safeguards for ePHI | Required and addressable safeguards |
+| Breach Notification Rule | What to do if PHI is breached | Timing and content of breach notifications |
+
+### Security Rule: Required vs. Addressable
+**Required safeguards** must be implemented exactly as specified. **Addressable safeguards** must be implemented or documented why an equivalent measure was used.
+
+**Key Required Safeguards:**
+- Unique user IDs (no shared logins)
+- Emergency access procedure
+- Audit controls (logging access to ePHI)
+- Transmission security (encryption in transit)
+- Person or entity authentication
+
+**Key Addressable Safeguards (implement or document why not):**
+- Automatic logoff
+- Encryption and decryption (encryption at rest — despite being "addressable," regulators expect it)
+- Audit review procedures
+- Security reminders and training
+
+### HIPAA Compliance Timeline
+
+| Phase | Duration | Activities |
+|---|---|---|
+| Risk analysis | 4–6 weeks | Document all PHI flows, assess risks to PHI — **required by law** |
+| Policy development | 4–8 weeks | Privacy policies, breach notification, workforce training |
+| Technical safeguard implementation | 4–12 weeks | Encryption, audit logging, access controls, BAA templates |
+| Workforce training | 2–4 weeks | Annual HIPAA training for all staff with PHI access |
+| BAA execution | Ongoing | Execute with all vendors who process PHI |
+| **Total** | **4–8 months** | — |
+
+### Cost Estimates
+| Item | Cost |
+|---|---|
+| Initial risk analysis (consultant) | $15,000–$40,000 |
+| Policy development | $8,000–$20,000 |
+| Technical implementation | $20,000–$60,000 |
+| Annual training and maintenance | $5,000–$15,000/yr |
+| HIPAA compliance platform | $10,000–$20,000/yr |
+| **Total first year** | **$45,000–$130,000** |
+
+### HIPAA Penalties (Why This Matters)
+| Violation Category | Penalty per Violation | Annual Cap |
+|---|---|---|
+| Unaware | $100–$50,000 | $25,000 |
+| Reasonable cause | $1,000–$50,000 | $100,000 |
+| Willful neglect (corrected) | $10,000–$50,000 | $250,000 |
+| Willful neglect (not corrected) | $50,000 | $1,500,000 |
+
+---
+
+## 4. GDPR Compliance Program
+
+### When GDPR Applies
+GDPR applies if you:
+- Are established in the EU/EEA
+- Process personal data of EU/EEA residents (regardless of your location)
+- Offer goods or services to EU residents
+- Monitor the behavior of EU residents
+
+**Key point for US startups:** If you have EU users or EU employees, GDPR applies to you.
+
+### Core GDPR Principles (Build These In)
+1. **Lawfulness, fairness, transparency** — have a legal basis for every processing activity
+2. **Purpose limitation** — collect data for specified, explicit purposes only
+3. **Data minimization** — collect only what you need
+4. **Accuracy** — keep data accurate
+5. **Storage limitation** — delete data when no longer needed
+6. **Integrity and confidentiality** — appropriate security measures
+7. **Accountability** — demonstrate compliance
+
+### Legal Bases for Processing
+| Basis | When to use |
+|---|---|
+| Consent | Marketing, non-essential cookies, optional features |
+| Contract | Processing necessary to deliver your service |
+| Legitimate interests | Analytics, fraud prevention, security (requires LIA) |
+| Legal obligation | Compliance with legal requirements |
+| Vital interests | Emergency situations only |
+
+**Avoid over-relying on consent** — it must be freely given, specific, informed, and unambiguous. Contractual basis is more robust for core product data.
+
+### GDPR Compliance Checklist
+
+**Governance:**
+- [ ] Data Protection Officer (DPO) appointed (required for large-scale processing or sensitive data)
+- [ ] Record of Processing Activities (RoPA) maintained
+- [ ] Data Protection Impact Assessments (DPIA) for high-risk processing
+
+**Rights Management (respond within 1 month):**
+- [ ] Right of access (data subject access requests — DSARs)
+- [ ] Right to rectification
+- [ ] Right to erasure ("right to be forgotten")
+- [ ] Right to data portability
+- [ ] Right to object to processing
+
+**Technical Measures:**
+- [ ] Privacy by design in product development
+- [ ] Data minimization enforced
+- [ ] Encryption at rest and in transit
+- [ ] Pseudonymization where possible
+- [ ] Retention policies and automated deletion
+
+**Vendor Management:**
+- [ ] Data Processing Agreements (DPAs) with all processors
+- [ ] Standard Contractual Clauses (SCCs) for non-EU transfers
+
+**Breach Notification:**
+- [ ] Notify supervisory authority within 72 hours of awareness
+- [ ] Notify affected individuals if high risk to their rights and freedoms
+
+### GDPR Compliance Timeline
+
+| Phase | Duration | Activities |
+|---|---|---|
+| Data mapping | 3–6 weeks | Map all personal data flows: collect, store, process, share, delete |
+| Legal basis review | 2–4 weeks | Assign legal basis to each processing activity |
+| Policy updates | 4–6 weeks | Privacy policy, cookie policy, employee data notices |
+| DPA execution | 2–4 weeks | Execute DPAs with all processors (SaaS vendors, cloud providers) |
+| Technical controls | 4–12 weeks | Consent management, data subject rights automation, retention |
+| Staff training | 2–4 weeks | GDPR awareness for all staff |
+| **Total** | **3–6 months** | — |
+
+### GDPR Fines
+- **Standard violations:** Up to €10M or 2% of global annual revenue
+- **Major violations** (basic principles, consent, data subject rights): Up to €20M or 4% of global annual revenue
+- **Highest ever fine:** Meta, €1.2B (2023, data transfers to US)
+
+---
+
+## 5. Multi-Framework Efficiency
+
+### Control Overlap Analysis
+
+The same underlying controls satisfy multiple frameworks. Build once, certify multiple times.
+
+**Core Control Domain Overlap:**
+
+| Control Domain | SOC 2 | ISO 27001 | HIPAA | GDPR |
+|---|---|---|---|---|
+| Access control / IAM | CC6 | A.5.15–A.5.18 | §164.312(a) | Art. 32 |
+| Encryption at rest/transit | CC6.7 | A.8.24 | §164.312(a)(2)(iv) | Art. 32 |
+| Audit logging | CC7.2 | A.8.15, A.8.17 | §164.312(b) | Art. 32 |
+| Incident response | CC7.3–CC7.5 | A.5.24–A.5.28 | §164.308(a)(6) | Art. 33–34 |
+| Vendor/third-party mgmt | CC9 | A.5.19–A.5.22 | §164.308(b) | Art. 28 |
+| Risk assessment | CC3 | Clause 6.1 | §164.308(a)(1) | Art. 32 |
+| Security training | CC1.4 | A.6.3, A.6.8 | §164.308(a)(5) | Art. 39 |
+| Business continuity | A1 | A.5.29–A.5.30 | §164.308(a)(7) | Art. 32 |
+| Data classification | CC6.1 | A.5.9–A.5.13 | §164.514 | Art. 5(1)(c) |
+| Change management | CC8 | A.8.32 | §164.312(c) | Art. 25 |
+
+**Efficiency Rule:** If you build SOC 2 controls correctly, you're ~65–75% of the way to ISO 27001 and ~70% of the way to HIPAA. Don't rebuild — extend.
+
+### Recommended Sequencing by Company Profile
+
+**B2B SaaS (US-focused):**
+```
+Month 0–6: SOC 2 Type I → unblocks early enterprise deals
+Month 6–18: SOC 2 Type II → enterprise table stakes
+Month 18–30: ISO 27001 → EU market expansion
+ (GDPR should be woven in from month 0 if any EU data)
+```
+
+**HealthTech (US):**
+```
+Month 0–8: HIPAA compliance + BAA readiness → enables healthcare customers
+Month 6–18: SOC 2 Type II → enterprise IT requirements on top of HIPAA
+Month 18+: ISO 27001 if entering European market
+```
+
+**EU-founded SaaS:**
+```
+Month 0–3: GDPR compliance → legal requirement, not optional
+Month 3–12: ISO 27001 → EU enterprise default expectation
+Month 12–24: SOC 2 → US market expansion
+```
+
+**HealthTech (EU):**
+```
+Concurrent: GDPR + ISO 27001 (strong overlap with MDR/IVDR security requirements)
+Month 12+: HIPAA if entering US market
+```
+
+### Shared Evidence Model
+Build your evidence library once. Tag each piece of evidence by framework:
+
+```
+evidence/
+├── access_control/
+│ ├── iam_policy.pdf [SOC2:CC6, ISO:A5.15, HIPAA:164.312a]
+│ ├── mfa_screenshot_Q1.png [SOC2:CC6, ISO:A8.5, HIPAA:164.312d]
+│ └── access_review_log.xlsx [SOC2:CC6, ISO:A5.18, HIPAA:164.308a]
+├── encryption/
+│ ├── kms_config.png [SOC2:CC6.7, ISO:A8.24, HIPAA:164.312e]
+│ └── tls_policy.md [SOC2:CC6.7, ISO:A8.24, HIPAA:164.312e]
+└── incident_response/
+ ├── ir_plan.pdf [SOC2:CC7, ISO:A5.24, HIPAA:164.308a6]
+ └── tabletop_log.pdf [SOC2:CC7, ISO:A5.26, HIPAA:164.308a6]
+```
+
+### GRC Platform Comparison
+
+| Platform | Best For | Price/yr | SOC 2 | ISO 27001 | HIPAA | GDPR |
+|---|---|---|---|---|---|---|
+| Vanta | Fast SOC 2, US startups | $15–30K | ✅ | ✅ | ✅ | ✅ |
+| Drata | Automation depth | $18–35K | ✅ | ✅ | ✅ | ✅ |
+| Secureframe | Cost-effective | $10–20K | ✅ | ✅ | ✅ | ✅ |
+| Sprinto | SMB, global | $12–25K | ✅ | ✅ | ✅ | ✅ |
+| Tugboat Logic | Mid-market | $20–40K | ✅ | ✅ | ✅ | ✅ |
+| Manual | Budget-constrained | $0 + time | ✅ | ✅ | ✅ | ✅ |
+
+**Recommendation:** For Series A startups, Vanta or Drata pays for itself in reduced auditor fees and internal time savings. Budget $15–25K/year.
+
+### Compliance Maintenance Annual Budget
+
+| Item | SOC 2 | ISO 27001 | HIPAA | GDPR |
+|---|---|---|---|---|
+| Annual audit / surveillance | $25–60K | $8–20K | n/a (self-assessed) | n/a (self-assessed) |
+| GRC platform | $15–30K | Shared | Shared | Shared |
+| Annual training | $3–8K | Shared | Shared | Shared |
+| Policy review | $2–5K | $2–5K | $2–5K | $2–5K |
+| **Total ongoing** | **$45–103K/yr** | **+$10–25K/yr** | **+$5–15K/yr** | **+$5–15K/yr** |
diff --git a/skills/c-level-advisor/ciso-advisor/references/incident_response.md b/skills/c-level-advisor/ciso-advisor/references/incident_response.md
new file mode 100644
index 00000000..dbb9ccb3
--- /dev/null
+++ b/skills/c-level-advisor/ciso-advisor/references/incident_response.md
@@ -0,0 +1,350 @@
+# Incident Response Reference (Executive Playbook)
+
+This is the executive IR playbook — strategic decisions, communication, and leadership during incidents. For technical playbooks (containment procedures, forensics), see your SOC runbooks.
+
+---
+
+## 1. Incident Classification
+
+### Severity Levels
+
+| Severity | Definition | Examples | Response Time | Escalation |
+|---|---|---|---|---|
+| SEV-1 (Critical) | Confirmed breach, data exfil, ransomware, production down | Active ransomware, confirmed data theft, complete service outage | Immediate (< 1 hour) | CEO, board within 24 hrs |
+| SEV-2 (High) | Suspected breach, significant security event, extended outage | Credential compromise suspected, DDoS, 4-hour+ outage | < 4 hours | CEO, legal within 48 hrs |
+| SEV-3 (Medium) | Security event with limited impact, short outage | Phishing success (contained), brief outage, single system compromise | < 24 hours | CISO-owned, weekly rollup |
+| SEV-4 (Low) | Minor security event, near-miss | Failed phishing attempt, minor policy violation | < 72 hours | Team-owned |
+
+### Breach vs. Security Incident
+**Security incident:** Unplanned event affecting security — may or may not involve data.
+**Data breach:** Confirmed unauthorized access to personal data — triggers regulatory notification obligations.
+
+**Critical distinction for response planning:** A ransomware attack is an incident. If data was exfiltrated before encryption, it's also a breach. Assume breach until proven otherwise.
+
+---
+
+## 2. Executive IR Plan
+
+### Phase 1: Detection & Initial Assessment (0–2 hours for SEV-1)
+
+**Immediate actions (CISO):**
+1. Receive alert from SOC/monitoring system or team member report
+2. Make initial severity classification — don't wait for perfect information
+3. Activate incident response team (IR lead, legal counsel, comms lead)
+4. Create incident war room (dedicated Slack channel, video bridge, shared document)
+5. **Stop the clock** — document exact time of discovery (regulatory timelines start here)
+6. Begin chain of custody documentation if forensics may be needed
+
+**Executive notification trigger (within 1 hour for SEV-1):**
+- Notify CEO: incident status, initial severity, IR team activated
+- Put legal counsel on notice — don't wait to determine if breach occurred
+- If public company: notify General Counsel immediately (potential disclosure obligations)
+
+**What you do NOT do in Phase 1:**
+- Do not notify customers yet (confirm scope first)
+- Do not delete or modify any logs or systems (evidence preservation)
+- Do not make public statements
+- Do not speculate about cause or scope
+
+### Phase 2: Containment & Assessment (2–24 hours for SEV-1)
+
+**Executive decisions required:**
+- **Scope authorization:** Approve IR firm engagement (have a retainer in place)
+- **System isolation:** Authorize taking systems offline if needed (revenue vs. evidence tradeoff)
+- **Evidence preservation:** Authorize forensic image capture
+- **Communication timing:** When to notify customers/partners (legal drives this)
+
+**Board notification (for SEV-1/2):**
+- Notify board chair / audit committee chair within 24 hours for SEV-1
+- Board notification format: what we know, what we don't know, what we're doing, next update time
+- Do not speculate on financial impact in board notification until known
+
+**Legal assessment (with counsel):**
+- Determine if personal data was involved
+- Identify applicable notification laws (GDPR 72-hour, state breach notification, HIPAA 60-day)
+- Assess litigation risk (document with privilege from this point)
+- Evaluate cyber insurance policy coverage and notification requirements
+
+### Phase 3: Notification & Communication (24–72 hours for SEV-1)
+
+**Notification decision matrix:**
+| Audience | Trigger | Timeline | Owner |
+|---|---|---|---|
+| Board | SEV-1/2 confirmed | < 24 hours | CEO/CISO |
+| Regulators (GDPR) | Personal data breach confirmed | < 72 hours from awareness | Legal + CISO |
+| Regulators (HIPAA) | PHI breach confirmed | < 60 days (early notice to HHS ASAP) | Legal + CISO |
+| State regulators (US) | State breach notification laws vary | 30–90 days depending on state | Legal |
+| Enterprise customers | Data confirmed in scope | As soon as practical after legal review | CEO/CRO |
+| All customers | Data potentially in scope | After regulators notified | CEO/Comms |
+| Media | Proactive or reactive | After notifying affected parties | CEO/Comms |
+| Cyber insurer | Incident confirmed | Per policy terms (often 48–72 hours) | CFO/Legal |
+
+### Phase 4: Recovery (Ongoing)
+
+**Executive decisions:**
+- Approve recovery timeline and communicate to customers
+- Determine customer compensation or remediation (if applicable)
+- Authorize security improvements identified during incident
+- Decide on public disclosure beyond mandatory reporting
+
+### Phase 5: Post-Incident Review (Within 30 days)
+
+Covered in Section 5 of this document.
+
+---
+
+## 3. Communication Templates
+
+### Board/Executive Notification (Initial — Hour 1)
+
+**Subject:** [CONFIDENTIAL] Security Incident — Immediate Notification
+
+---
+We have identified a security incident as of [DATE/TIME].
+
+**Current status:** [Brief factual description — what we know happened]
+
+**Severity assessment:** SEV-[1/2/3]
+
+**What we do not yet know:**
+- [List unknowns — scope of impact, whether data was accessed, root cause]
+
+**Actions taken so far:**
+- IR team activated at [time]
+- Legal counsel notified
+- [Specific containment actions if applicable]
+
+**Next update:** [Specific time, e.g., "in 4 hours or when we have material new information"]
+
+**Who is managing this:** [CISO name] leads technical response; [CEO name] owns executive decisions. Contact: [CISO mobile]
+
+---
+
+### Customer Notification (After Legal Review)
+
+**Subject:** Important Security Notice — [Company Name]
+
+---
+We are writing to inform you of a security incident that may have affected your data.
+
+**What happened:**
+On [DATE], we detected [brief, factual description of the incident — e.g., "unauthorized access to our systems"]. We identified this on [DISCOVERY DATE] and immediately launched an investigation.
+
+**What information was involved:**
+Based on our investigation, the following types of information may have been accessed: [list data types — e.g., names, email addresses, [if applicable: payment card information]].
+
+Your [specific data types] [were / were not] affected.
+
+**What we are doing:**
+We have [list specific actions: engaged leading cybersecurity firm, notified relevant authorities, implemented additional security controls, etc.].
+
+**What you can do:**
+- [Specific actionable steps for customers]
+- Monitor your accounts for unusual activity
+- [If passwords: reset your password at X]
+- [If payment data: contact your bank to monitor for unauthorized charges]
+- Contact our dedicated support line at [contact] with any concerns
+
+**For more information:**
+We have set up a dedicated resource page at [URL]. Our support team is available at [contact].
+
+We take the security of your data extremely seriously and deeply regret this incident occurred.
+
+[CEO/CISO Name]
+[Title], [Company Name]
+
+---
+
+### Regulator Notification — GDPR (72-hour requirement)
+
+**To:** [Relevant Supervisory Authority — e.g., BfDI (Germany), CNIL (France), ICO (UK)]
+**Subject:** Personal Data Breach Notification — [Company Name] — [Reference Number if applicable]
+
+---
+**1. Nature of the breach:**
+[Description of what occurred, including how it happened]
+
+**2. Categories and approximate number of data subjects concerned:**
+[e.g., "Approximately [X] customers whose [name, email, account data] may have been accessed"]
+
+**3. Categories and approximate number of personal data records concerned:**
+[e.g., "Approximately [X] records containing [data categories]"]
+
+**4. Likely consequences of the breach:**
+[Risk assessment: what harm could data subjects face?]
+
+**5. Measures taken or proposed:**
+[Containment actions, remediation plan, customer notification plan]
+
+**6. Contact details of the Data Protection Officer or other contact point:**
+[Name, role, email, phone]
+
+**Note:** This is an initial notification; we will provide supplemental information as our investigation continues.
+
+---
+
+### Media Statement (Reactive — When Contacted)
+
+"[Company Name] is aware of a security incident that we identified on [date]. We immediately activated our incident response team and launched a comprehensive investigation. We have notified affected customers and relevant regulatory authorities as required. The security and privacy of our customers' data is our top priority, and we are committed to transparency as our investigation proceeds. We will provide updates at [URL]. We cannot provide additional details at this time to protect the integrity of our investigation."
+
+**What not to say to media:**
+- Number of affected users (until confirmed and disclosed to customers first)
+- Cause of the incident (until investigation is complete)
+- Financial impact (speculation creates liability)
+- Anything that could be construed as minimizing the incident
+
+---
+
+## 4. Tabletop Exercise Design
+
+### Purpose
+Test the decision-making and communication processes — not the technical response. The goal is to surface gaps in escalation, communication, and judgment before a real incident.
+
+### Recommended Frequency
+- Annual full tabletop (2–3 hours, full leadership team)
+- Semi-annual mini-tabletop (45 minutes, CISO + legal + CEO)
+- Quarterly technical team exercise (separate from executive tabletop)
+
+### Sample Tabletop Scenario: Ransomware
+
+**Setup (read to participants):**
+> It's 6:47 AM on a Monday. Your DevOps engineer receives automated alerts that production databases are inaccessible. By 7:15 AM, they discover a ransomware note demanding $500,000 in Bitcoin. Several files are already encrypted. Your last verified backup was 48 hours ago. Your business is B2B SaaS serving 200 enterprise customers. You process customer financial data.
+
+**Discussion questions (timed, 10 minutes each):**
+1. First 30 minutes — who do you call, in what order? Who decides whether to take production offline?
+2. Legal assessment — what regulatory obligations have been triggered? What's the timeline?
+3. Hour 4 — initial forensics suggests data may have been exfiltrated before encryption. How does your response change?
+4. Customer communication — how do you communicate with enterprise customers who are asking for status?
+5. Hour 24 — do you pay the ransom? Who makes this decision? What's the decision framework?
+6. The press has found out and a reporter is calling. What do you say?
+7. Day 5 — what's your board communication strategy?
+
+**Post-discussion captures:**
+- What decisions were unclear (ownership ambiguous)?
+- What information did you need but didn't have?
+- What processes did not exist that should?
+- What would you do differently in the first hour?
+
+### Sample Tabletop Scenario: Insider Threat
+
+**Setup:**
+> HR notifies you that an engineer was terminated this morning for performance reasons. 24 hours later, your SIEM generates an alert that this former employee's credentials accessed your customer database 30 minutes before their offboarding was complete. They downloaded 50,000 customer records. You don't know if they shared or sold the data.
+
+**Key decision points:**
+- When does this become a breach vs. a security incident?
+- Do you notify customers? When?
+- What are your legal options against the former employee?
+- How do you handle this with the rest of the engineering team?
+
+---
+
+## 5. Post-Incident Review Framework
+
+### Timeline
+Conduct within 30 days of incident resolution. Do not delay — memory fades and teams move on.
+
+### Blameless Post-Mortem Principles
+The purpose is to improve systems and processes, not punish individuals. A blame culture means the next incident gets hidden longer.
+
+### Post-Incident Review Structure
+
+**1. Incident Timeline (factual, no editorializing)**
+- Hour-by-hour reconstruction from detection to resolution
+- Source: logs, Slack messages, incident ticket, war room notes
+
+**2. Root Cause Analysis**
+Use the "5 Whys" technique — keep asking why until you reach a systemic root cause, not a human error.
+
+Example:
+- Why was there a breach? → Attacker compromised an admin account
+- Why was the admin account compromised? → Credentials stolen via phishing
+- Why did phishing succeed? → User wasn't trained on this attack type
+- Why wasn't training current? → Training program hadn't been updated in 18 months
+- Why hadn't it been updated? → No owner was assigned to maintain the training program
+- **Root cause: No assigned ownership for security training maintenance**
+
+**3. What Went Well**
+- Detection mechanisms that worked
+- Response actions that contained damage
+- Communication that was effective
+- Teams that exceeded expectations
+
+**4. What Needs Improvement**
+- Detection gaps (how could we have found this faster?)
+- Response gaps (what slowed us down?)
+- Communication gaps (who didn't know what, when?)
+- Process gaps (what didn't we have documented?)
+
+**5. Action Items (with owners and deadlines)**
+| Action | Owner | Due Date | Priority |
+|---|---|---|---|
+| [Specific improvement] | [Name] | [Date] | [P0/P1/P2] |
+
+**6. Metrics Review**
+- MTTD (Mean Time to Detect): [actual] vs. [target]
+- MTTR (Mean Time to Respond): [actual] vs. [target]
+- Customer impact: [affected customers, duration]
+- Financial impact: [direct costs, revenue impact]
+- Regulatory impact: [notifications sent, fines if any]
+
+---
+
+## 6. Insurance and Legal Considerations
+
+### Cyber Insurance
+
+**What to have before an incident:**
+- Cyber liability policy with minimum $2M coverage (Series A); $5M+ (Series B+)
+- Coverage should include: first-party loss, third-party liability, ransomware, business interruption, regulatory defense
+- Pre-approved IR firms on your policy (using an approved firm can expedite claims)
+- Notification requirements — know your insurer's required timeline (typically 48–72 hours)
+
+**Policy exclusions to watch:**
+- "War exclusion" — increasingly contested for nation-state attacks (NotPetya precedent)
+- "Systemic risk" — some policies exclude widespread events affecting many insureds simultaneously
+- "Prior acts" — incidents that began before policy inception
+- "Failure to maintain reasonable security" — don't give your insurer a reason to deny
+
+**Premium factors:**
+- Revenue and data volume
+- Security control maturity (MFA, EDR, backup, patch management)
+- Industry (healthcare, financial services = higher premium)
+- Claims history
+
+**Ballpark premiums:**
+- Seed/Series A ($1–10M ARR): $8,000–$25,000/yr
+- Series B ($10–50M ARR): $25,000–$75,000/yr
+- Series C+ ($50M+ ARR): $75,000–$250,000/yr
+
+### Legal Counsel
+
+**Have on retainer before an incident:**
+- Cybersecurity/privacy attorney — breach notification, regulatory response
+- General counsel — contracts, employment law (insider threats), litigation
+- Consider: a law firm with data breach notification experience by jurisdiction
+
+**Attorney-client privilege:** Once legal counsel is involved in an incident, communications and work product may be privileged. Engage counsel early to maximize privilege protection.
+
+**Key legal decisions during an incident:**
+- When does notification obligation clock start? (Legal determines this)
+- Is this a breach or an incident? (Legal + CISO together)
+- Who are the affected data subjects? (Legal + technical together)
+- Do we pay the ransom? (Legal, CEO, board — never CISO alone)
+- Do we cooperate with law enforcement? (Legal decision, involves trade-offs)
+
+### Law Enforcement
+
+**FBI Internet Crime Complaint Center (IC3):** File a complaint for ransomware or significant cybercrime. Does not obligate you to cooperate but creates a record.
+
+**Pros of law enforcement involvement:**
+- Access to threat intelligence they may have
+- May recover funds in some cases (rare)
+- Demonstrates good-faith response to regulators
+
+**Cons of law enforcement involvement:**
+- Loss of control over investigation timeline
+- Potential for public disclosure if case pursued
+- Slows ransom payment decisions (if considering)
+- May create discovery obligations in litigation
+
+**CISO recommendation:** Notify legal before contacting law enforcement. In most cases, file an IC3 complaint but don't actively engage FBI investigation unless there's a clear benefit.
diff --git a/skills/c-level-advisor/ciso-advisor/references/security_strategy.md b/skills/c-level-advisor/ciso-advisor/references/security_strategy.md
new file mode 100644
index 00000000..2644ecf1
--- /dev/null
+++ b/skills/c-level-advisor/ciso-advisor/references/security_strategy.md
@@ -0,0 +1,321 @@
+# Security Strategy Reference
+
+## 1. Risk-Based Security (Not Compliance-First)
+
+### The Problem with Compliance-First Security
+Most startups build security backwards: they get a compliance requirement (SOC 2, ISO 27001) and treat it as the security program. This produces:
+- Controls that pass audits but don't reduce actual risk
+- Resources allocated to documentation over protection
+- Security teams optimizing for auditor satisfaction, not threat reduction
+- False confidence ("we passed our audit") before real security exists
+
+**The right order:**
+1. Identify your actual threats (what do adversaries want from you?)
+2. Identify your crown jewels (what's worth protecting most?)
+3. Implement controls that address those threats to those assets
+4. Map existing controls to compliance requirements — most overlap naturally
+
+### Risk Identification Framework
+
+**Asset Classification:**
+```
+Tier 1 — Crown Jewels
+├── Customer PII/PHI
+├── Payment card data
+├── Intellectual property (source code, models, trade secrets)
+└── Authentication credentials and secrets
+
+Tier 2 — Business Critical
+├── Internal communications (Slack, email)
+├── Financial systems and data
+├── Employee data
+└── Business strategy documents
+
+Tier 3 — Operational
+├── Internal tooling and infrastructure configs
+├── Non-sensitive operational data
+└── Public-facing content and marketing
+```
+
+**Threat Actor Profiling:**
+| Threat Actor | Motivation | Typical TTPs | Relative Likelihood |
+|---|---|---|---|
+| Financially motivated criminals | Data theft, ransomware | Phishing, credential stuffing | High |
+| Nation-state | IP theft, espionage | Spear phishing, supply chain | Low-Medium (sector-dependent) |
+| Insider threat | Financial gain, revenge | Privilege abuse, data exfil | Medium |
+| Script kiddies | Notoriety, fun | Known CVEs, scanning | High (low sophistication) |
+| Competitors | IP theft | Social engineering, insider recruitment | Low-Medium |
+
+### Risk Quantification (FAIR Model Simplified)
+
+**Annual Loss Expectancy:**
+```
+ALE = SLE × ARO
+SLE (Single Loss Expectancy) = Asset Value × Exposure Factor
+ARO (Annual Rate of Occurrence) = historical frequency or industry estimate
+```
+
+**Business Impact Categories:**
+- **Direct financial loss**: fraud, ransomware payment, theft
+- **Regulatory fines**: GDPR (4% global revenue), HIPAA ($100–$50K per violation), PCI DSS
+- **Revenue impact**: customer churn post-breach, deal loss during incident, downtime cost
+- **Reputational damage**: brand devaluation (harder to quantify, but real)
+- **Legal costs**: incident response counsel, class action defense, settlements
+
+**Example Risk Quantification:**
+
+| Risk Scenario | SLE | ARO | ALE |
+|---|---|---|---|
+| Customer data breach (10K records) | $850K | 0.15 | $127,500/yr |
+| Ransomware attack | $350K | 0.20 | $70,000/yr |
+| Credential compromise + fraud | $120K | 0.35 | $42,000/yr |
+| Third-party SaaS breach | $95K | 0.25 | $23,750/yr |
+| Insider data exfiltration | $180K | 0.10 | $18,000/yr |
+
+**Mitigation ROI:**
+```
+ROSI = (Risk Reduction × ALE) - Control Cost
+ ────────────────────────────────────
+ Control Cost
+
+Example: MFA deployment
+ Risk reduction: 99% for credential attacks
+ ALE reduced: $42,000 × 0.99 = $41,580
+ Control cost: $5,000/yr
+ ROSI: ($41,580 - $5,000) / $5,000 = 731%
+```
+
+---
+
+## 2. Zero Trust Architecture at Strategy Level
+
+### What Zero Trust Actually Means
+Zero trust is not a product — it's an architectural principle: **never trust, always verify, assume breach.**
+
+The traditional perimeter model (trust inside the network, distrust outside) fails because:
+- Remote work destroyed the perimeter
+- Cloud infrastructure has no perimeter
+- 80% of breaches involve privileged account abuse (internal trust abused)
+- Supply chain attacks compromise trusted software
+
+### Zero Trust Maturity Model
+
+**Stage 1 — Identity-Centric (Start Here)**
+- MFA enforced for all users, all applications
+- Identity provider (Okta, Azure AD, Google Workspace) as single control plane
+- No shared service accounts
+- Privileged Access Management (PAM) for admin access
+- **Cost:** $20–80K/year | **Timeline:** 3–6 months
+
+**Stage 2 — Device Trust**
+- Endpoint detection and response (EDR) on all devices
+- Device health checks before granting access
+- Mobile device management (MDM) for BYOD
+- Certificate-based device authentication
+- **Cost:** $30–60K/year additional | **Timeline:** 6–12 months
+
+**Stage 3 — Network Micro-Segmentation**
+- Replace VPN with Zero Trust Network Access (ZTNA)
+- Segment production from development from corporate
+- East-west traffic inspection (not just north-south)
+- **Cost:** $40–100K/year additional | **Timeline:** 12–18 months
+
+**Stage 4 — Application-Level Controls**
+- Just-in-time access (no standing privileges)
+- Workload identity for service-to-service auth
+- API gateway with authentication enforcement
+- Continuous authorization (not just at login)
+- **Cost:** $50–150K/year additional | **Timeline:** 18–30 months
+
+**Strategic Guidance:**
+- Don't sell zero trust as a project. It's a 3–5 year direction.
+- Start with identity. It gives the most risk reduction per dollar.
+- Measure progress by % of access covered by MFA, % of apps behind IdP, privilege account count.
+
+---
+
+## 3. Defense in Depth for Startups
+
+### The Layered Security Model
+
+```
+Layer 1: Governance & Policies
+ └── Asset inventory, acceptable use, vendor management
+
+Layer 2: Perimeter Controls
+ └── WAF, DDoS protection, email security (DMARC/DKIM/SPF)
+
+Layer 3: Identity & Access
+ └── MFA, SSO, PAM, just-in-time access, least privilege
+
+Layer 4: Endpoint Security
+ └── EDR, device management, patch management
+
+Layer 5: Application Security
+ └── SAST/DAST, dependency scanning, code review, API security
+
+Layer 6: Data Protection
+ └── Encryption at rest and in transit, DLP, backup/recovery
+
+Layer 7: Detection & Response
+ └── SIEM/SOAR, log aggregation, alerting, incident response
+
+Layer 8: Recovery
+ └── Backup testing, DR plan, RTO/RPO targets
+```
+
+### Startup Security Budget Allocation (Guidance)
+
+| Stage | Annual Revenue | Recommended Security Budget | Priority Spend |
+|---|---|---|---|
+| Pre-seed/Seed | <$1M | 3–5% opex or $50–100K | MFA, backups, basic EDR |
+| Series A | $1–10M | 2–4% revenue | +SIEM, SOC 2 Type I, AppSec |
+| Series B | $10–50M | 3–5% revenue | +ZTNA, Red team, dedicated CISO |
+| Series C+ | $50M+ | 4–6% revenue | +SOC, threat intelligence, M&A security |
+
+**Non-negotiables regardless of stage:**
+1. MFA on everything (particularly email, cloud consoles, code repos)
+2. Automated backups with tested restore (ransomware defense)
+3. Secrets management (no hardcoded credentials)
+4. Dependency vulnerability scanning in CI/CD
+5. Incident response plan (even a 2-page doc is better than nothing)
+
+---
+
+## 4. Security Program Maturity Model
+
+**Based on NIST CSF and CMMI, simplified for startup context:**
+
+### Level 1: Initial
+- No formal policies
+- Reactive security (respond to incidents, not prevent them)
+- No dedicated security personnel
+- Basic hygiene gaps (unpatched systems, shared passwords)
+- **Typical:** Pre-seed, <20 employees
+
+### Level 2: Developing
+- Written security policies (even if not fully followed)
+- Dedicated security responsibility (often part-time or dual-role)
+- MFA deployed, basic asset inventory
+- Incident response process documented
+- SOC 2 Type I achievable from here in ~6 months
+- **Typical:** Series A, 20–50 employees
+
+### Level 3: Defined
+- Security integrated into SDLC
+- Dedicated security lead or vCISO
+- Regular vulnerability scanning and patching
+- Security awareness training program
+- SOC 2 Type II and ISO 27001 achievable
+- **Typical:** Series B, 50–150 employees
+
+### Level 4: Managed
+- Risk-based security program with quantified risks
+- Security metrics reported to board quarterly
+- Threat intelligence program
+- Dedicated security team (3–8 people)
+- Red team / penetration testing annually
+- **Typical:** Series C+, 150–500 employees
+
+### Level 5: Optimized
+- Continuous monitoring and automated response
+- Proactive threat hunting
+- Industry leadership on security (bug bounty, disclosure program)
+- Security as competitive advantage in sales
+- **Typical:** Public company or regulated enterprise
+
+### Maturity Assessment Questions
+1. Can you list all systems that process customer data right now?
+2. How long would it take to detect if an admin credential was compromised?
+3. When was your last backup tested with a restore?
+4. Do developers run any security checks before code is deployed?
+5. Does the board receive security reporting? What's in it?
+
+Score: 0 = no/don't know, 1 = partially, 2 = yes/verified
+- 0–3: Level 1–2
+- 4–7: Level 2–3
+- 8–10: Level 3–4
+
+---
+
+## 5. Board-Level Security Reporting
+
+### What the Board Cares About
+Boards are not interested in CVE counts or firewall rules. They care about:
+1. **Risk posture:** Are we getting better or worse?
+2. **Regulatory exposure:** What fines could we face?
+3. **Incident readiness:** If we're breached, are we prepared?
+4. **Competitive position:** Do customers trust us with their data?
+5. **Budget adequacy:** Are we investing appropriately?
+
+### Quarterly Board Security Report Structure
+
+**Executive Summary (1 page max)**
+- Security posture score vs. last quarter (directional trend matters more than absolute)
+- Top 3 risks and their business impact in dollars
+- Key accomplishments this quarter
+- Investment requested (if any)
+
+**Risk Dashboard**
+```
+Risk Register Summary:
+├── Critical (>$500K ALE): [count] risks, [count] mitigated
+├── High ($100K–$500K ALE): [count] risks, [count] mitigated
+├── Medium ($10K–$100K ALE): [count] risks
+└── Low (<$10K ALE): [count] risks (for awareness only)
+
+Trend: ↑ Risk exposure vs. Q[n-1] / ↓ Risk exposure vs. Q[n-1]
+```
+
+**Compliance Status**
+- Framework certifications in scope and current status
+- Next audit date
+- Any findings from last audit and remediation status
+
+**Incident Summary**
+- Security incidents last quarter (count and severity)
+- Time to detect / time to respond (vs. targets)
+- Any regulatory reporting obligations triggered
+
+**Key Metrics (4–6 max)**
+- MFA adoption rate
+- Critical patch SLA compliance
+- Phishing simulation click rate (trend)
+- Vendor assessments completed
+
+**Budget Summary**
+- Spend vs. budget
+- Headcount
+- Next quarter key investments and rationale
+
+### Common Board Questions to Prepare For
+- "Have we been breached?" (Know your detection capability, not just your answer)
+- "How do we compare to peers?" (Benchmarks from Verizon DBIR, industry ISACs)
+- "What's the one thing we should invest in?" (Have a clear answer)
+- "If we're acquired, what would security due diligence find?" (Be honest)
+- "What keeps you up at night?" (Have a real answer, not a vague one)
+
+---
+
+## 6. Security as Revenue Enabler
+
+### The Sales Angle
+For B2B companies, security certifications directly impact revenue:
+- Enterprise buyers require SOC 2 as table stakes (increasingly SOC 2 Type II)
+- Government and healthcare require ISO 27001 or HIPAA
+- Passing security questionnaires faster closes deals faster
+- A breach costs 10–30% customer churn; security investment is churn prevention
+
+**How to Measure:**
+- Deals blocked by security questionnaire failures (track in CRM)
+- Average security questionnaire turnaround time
+- Customer security reviews passed vs. failed
+- Revenue attributed to new compliance certifications
+
+### The Trust Narrative
+Position security certifications in marketing:
+- SOC 2 Type II: "Independently audited security controls, verified annually"
+- ISO 27001: "Internationally certified information security management"
+- HIPAA BAA: "Healthcare data protection to regulatory standards"
+
+These aren't just compliance — they're trust signals that compress the sales cycle.
diff --git a/skills/c-level-advisor/ciso-advisor/scripts/compliance_tracker.py b/skills/c-level-advisor/ciso-advisor/scripts/compliance_tracker.py
new file mode 100644
index 00000000..5b452938
--- /dev/null
+++ b/skills/c-level-advisor/ciso-advisor/scripts/compliance_tracker.py
@@ -0,0 +1,781 @@
+#!/usr/bin/env python3
+"""
+CISO Compliance Tracker
+========================
+Tracks compliance requirements across SOC 2, ISO 27001, HIPAA, and GDPR.
+Shows control overlaps, estimates effort and cost, and prioritizes by business value.
+
+Usage:
+ python compliance_tracker.py # Run with sample data
+ python compliance_tracker.py --json # JSON output
+ python compliance_tracker.py --csv output.csv # Export CSV
+ python compliance_tracker.py --framework soc2 # Show single framework
+ python compliance_tracker.py --gap-analysis # Show unaddressed requirements
+ python compliance_tracker.py --roadmap # Show sequenced roadmap
+"""
+
+import json
+import csv
+import sys
+import argparse
+from datetime import datetime, date
+from typing import Optional
+
+
+# ─── Framework Definitions ───────────────────────────────────────────────────
+
+FRAMEWORKS = {
+ "soc2": {
+ "name": "SOC 2 Type II",
+ "full_name": "AICPA Trust Service Criteria — Security",
+ "typical_timeline_months": 12,
+ "typical_cost_usd": 65_000, # Audit + platform
+ "annual_maintenance_usd": 40_000,
+ "business_value": "Enterprise sales unblock, US market table stakes",
+ "mandatory_for": ["B2B SaaS selling to enterprise US companies"],
+ },
+ "iso27001": {
+ "name": "ISO 27001:2022",
+ "full_name": "Information Security Management System",
+ "typical_timeline_months": 15,
+ "typical_cost_usd": 95_000,
+ "annual_maintenance_usd": 30_000,
+ "business_value": "EU enterprise sales, global credibility",
+ "mandatory_for": ["EU enterprise customers", "Government contracts"],
+ },
+ "hipaa": {
+ "name": "HIPAA",
+ "full_name": "Health Insurance Portability and Accountability Act",
+ "typical_timeline_months": 7,
+ "typical_cost_usd": 75_000,
+ "annual_maintenance_usd": 20_000,
+ "business_value": "Healthcare customer access, BAA execution",
+ "mandatory_for": ["Business Associates", "Companies handling PHI"],
+ },
+ "gdpr": {
+ "name": "GDPR",
+ "full_name": "General Data Protection Regulation (EU) 2016/679",
+ "typical_timeline_months": 5,
+ "typical_cost_usd": 45_000,
+ "annual_maintenance_usd": 15_000,
+ "business_value": "EU market access, legal compliance",
+ "mandatory_for": ["EU-based companies", "Any company with EU user data"],
+ },
+}
+
+
+# ─── Control Domain Library ──────────────────────────────────────────────────
+
+def build_control_domain(
+ domain_id: str,
+ name: str,
+ description: str,
+ soc2_ref: Optional[str],
+ iso27001_ref: Optional[str],
+ hipaa_ref: Optional[str],
+ gdpr_ref: Optional[str],
+ effort_days: int, # Estimated implementation effort in person-days
+ cost_usd: int, # Estimated implementation cost (tooling + time)
+ implementation_notes: str,
+ status: str = "Not Started", # Not Started | In Progress | Implemented | Verified
+ owner: Optional[str] = None,
+ target_date: Optional[str] = None,
+) -> dict:
+ """Build a control domain record."""
+ frameworks_applicable = []
+ if soc2_ref:
+ frameworks_applicable.append("soc2")
+ if iso27001_ref:
+ frameworks_applicable.append("iso27001")
+ if hipaa_ref:
+ frameworks_applicable.append("hipaa")
+ if gdpr_ref:
+ frameworks_applicable.append("gdpr")
+
+ return {
+ "domain_id": domain_id,
+ "name": name,
+ "description": description,
+ "references": {
+ "soc2": soc2_ref,
+ "iso27001": iso27001_ref,
+ "hipaa": hipaa_ref,
+ "gdpr": gdpr_ref,
+ },
+ "frameworks_applicable": frameworks_applicable,
+ "framework_count": len(frameworks_applicable),
+ "effort_days": effort_days,
+ "cost_usd": cost_usd,
+ "implementation_notes": implementation_notes,
+ "status": status,
+ "owner": owner,
+ "target_date": target_date,
+ }
+
+
+def load_control_library() -> list[dict]:
+ """
+ Core control domains mapped across SOC 2, ISO 27001, HIPAA, and GDPR.
+ Each domain represents a logical grouping of controls.
+ """
+ controls = []
+
+ controls.append(build_control_domain(
+ domain_id="IAM-001",
+ name="Identity and Access Management",
+ description=(
+ "Unique user identities, MFA enforcement, SSO, least privilege access, "
+ "role-based access control, access provisioning and de-provisioning workflows."
+ ),
+ soc2_ref="CC6.1, CC6.2, CC6.3",
+ iso27001_ref="A.5.15, A.5.16, A.5.17, A.5.18",
+ hipaa_ref="§164.312(a)(2)(i), §164.308(a)(3)",
+ gdpr_ref="Art. 32(1)(b)",
+ effort_days=15,
+ cost_usd=25_000, # SSO + MFA tooling
+ implementation_notes=(
+ "Deploy IdP (Okta/Azure AD/Google Workspace). Enforce MFA on all applications. "
+ "Document access provisioning process. Implement quarterly access reviews."
+ ),
+ status="In Progress",
+ owner="IT/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="ENC-001",
+ name="Encryption at Rest and in Transit",
+ description=(
+ "Encryption of sensitive data stored in databases, file systems, and backups. "
+ "TLS 1.2+ for all data in transit. Key management and rotation."
+ ),
+ soc2_ref="CC6.7",
+ iso27001_ref="A.8.24",
+ hipaa_ref="§164.312(a)(2)(iv), §164.312(e)(2)(ii)",
+ gdpr_ref="Art. 32(1)(a)",
+ effort_days=10,
+ cost_usd=8_000,
+ implementation_notes=(
+ "Enable encryption at rest on all databases (RDS, S3, etc.). "
+ "Configure TLS on all services. Use KMS for key management. "
+ "Document encryption standards in a security policy."
+ ),
+ status="Implemented",
+ owner="Engineering",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="LOG-001",
+ name="Audit Logging and Monitoring",
+ description=(
+ "Comprehensive logging of user activity, system events, and security events. "
+ "Log integrity protection. SIEM or log aggregation. Alerting on anomalies."
+ ),
+ soc2_ref="CC7.2, CC7.3",
+ iso27001_ref="A.8.15, A.8.16, A.8.17",
+ hipaa_ref="§164.312(b)",
+ gdpr_ref="Art. 32(1)(b)",
+ effort_days=20,
+ cost_usd=30_000, # SIEM tooling
+ implementation_notes=(
+ "Centralize logs from application, infrastructure, and cloud provider. "
+ "Define log retention (minimum 1 year). Set up alerting for authentication "
+ "failures, privilege escalation, data export events."
+ ),
+ status="Not Started",
+ owner="DevOps/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="IR-001",
+ name="Incident Response",
+ description=(
+ "Documented incident response plan. Defined severity levels. Escalation procedures. "
+ "Communication templates. Annual tabletop exercise. Post-incident review process."
+ ),
+ soc2_ref="CC7.3, CC7.4, CC7.5",
+ iso27001_ref="A.5.24, A.5.25, A.5.26, A.5.27, A.5.28",
+ hipaa_ref="§164.308(a)(6)",
+ gdpr_ref="Art. 33, Art. 34",
+ effort_days=12,
+ cost_usd=10_000,
+ implementation_notes=(
+ "Write IR plan covering detection, containment, eradication, recovery, communication. "
+ "Define breach notification timelines (GDPR: 72 hours, HIPAA: 60 days). "
+ "Run annual tabletop exercise. Retain IR firm on retainer."
+ ),
+ status="In Progress",
+ owner="CISO",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="VM-001",
+ name="Vulnerability Management and Patching",
+ description=(
+ "Regular vulnerability scanning of infrastructure and applications. "
+ "Defined patch SLAs by severity. Penetration testing program. "
+ "Dependency vulnerability scanning in CI/CD."
+ ),
+ soc2_ref="CC7.1",
+ iso27001_ref="A.8.8",
+ hipaa_ref="§164.308(a)(1)(ii)(A)",
+ gdpr_ref="Art. 32(1)(d)",
+ effort_days=15,
+ cost_usd=20_000,
+ implementation_notes=(
+ "Deploy infrastructure scanner (Tenable, Qualys, AWS Inspector). "
+ "Add SAST/DAST to CI/CD pipeline. Define patch SLAs: Critical <24h, High <7d, "
+ "Medium <30d. Conduct annual pentest."
+ ),
+ status="In Progress",
+ owner="DevOps/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="VRISK-001",
+ name="Vendor and Third-Party Risk Management",
+ description=(
+ "Inventory of all third-party vendors with data access. Tiered risk assessment "
+ "process. Contractual security requirements. Annual reviews for critical vendors."
+ ),
+ soc2_ref="CC9.2",
+ iso27001_ref="A.5.19, A.5.20, A.5.21, A.5.22",
+ hipaa_ref="§164.308(b) Business Associate Agreements",
+ gdpr_ref="Art. 28 Data Processing Agreements",
+ effort_days=10,
+ cost_usd=8_000,
+ implementation_notes=(
+ "Build vendor inventory spreadsheet. Tier vendors (Tier 1: PII access, "
+ "Tier 2: business data, Tier 3: no data). Execute DPAs for all processors (GDPR). "
+ "Execute BAAs for PHI processors (HIPAA). Annual security questionnaire for Tier 1."
+ ),
+ status="Not Started",
+ owner="Legal/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="RISK-001",
+ name="Risk Assessment and Treatment",
+ description=(
+ "Formal risk assessment methodology. Risk register maintained. "
+ "Risk treatment decisions documented. Annual risk review cycle."
+ ),
+ soc2_ref="CC3.1, CC3.2, CC3.3, CC3.4",
+ iso27001_ref="Clause 6.1.2, 6.1.3",
+ hipaa_ref="§164.308(a)(1) Security Risk Analysis",
+ gdpr_ref="Art. 32, Art. 35 DPIA",
+ effort_days=15,
+ cost_usd=12_000,
+ implementation_notes=(
+ "Document risk methodology (FAIR, NIST, ISO 27005). Maintain risk register. "
+ "HIPAA: formal security risk analysis required — not optional. "
+ "GDPR: DPIA required for high-risk processing activities. Annual refresh."
+ ),
+ status="Not Started",
+ owner="CISO",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="TRAIN-001",
+ name="Security Awareness Training",
+ description=(
+ "Annual security awareness training for all employees. "
+ "Role-specific training for high-risk roles. Phishing simulations. "
+ "Training completion tracking."
+ ),
+ soc2_ref="CC1.4",
+ iso27001_ref="A.6.3, A.6.8",
+ hipaa_ref="§164.308(a)(5)",
+ gdpr_ref="Art. 39(1)(b)",
+ effort_days=5,
+ cost_usd=8_000,
+ implementation_notes=(
+ "Deploy security training platform (KnowBe4, Proofpoint, etc.). "
+ "Annual training required — track completion (100% target). "
+ "Quarterly phishing simulations. Role-specific training for devs (secure coding), "
+ "finance (BEC), support (social engineering)."
+ ),
+ status="Not Started",
+ owner="HR/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="CHGMGMT-001",
+ name="Change Management",
+ description=(
+ "Formal change management process for production changes. "
+ "Code review requirements. Deployment approvals. Rollback procedures. "
+ "Change log maintained."
+ ),
+ soc2_ref="CC8.1",
+ iso27001_ref="A.8.32",
+ hipaa_ref="§164.312(c)(1) Integrity controls",
+ gdpr_ref="Art. 25 Privacy by design",
+ effort_days=10,
+ cost_usd=5_000,
+ implementation_notes=(
+ "Document change management policy. Require peer review for all production changes. "
+ "Maintain audit trail in version control. No direct production access — "
+ "all changes via CI/CD pipeline."
+ ),
+ status="In Progress",
+ owner="Engineering",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="BCP-001",
+ name="Business Continuity and Disaster Recovery",
+ description=(
+ "Business continuity plan. Disaster recovery plan with defined RTO/RPO. "
+ "Backup procedures with tested restores. Failover capabilities."
+ ),
+ soc2_ref="A1.1, A1.2, A1.3",
+ iso27001_ref="A.5.29, A.5.30",
+ hipaa_ref="§164.308(a)(7) Contingency Plan",
+ gdpr_ref="Art. 32(1)(c)",
+ effort_days=12,
+ cost_usd=15_000,
+ implementation_notes=(
+ "Define RTO (<4 hours) and RPO (<1 hour) targets. Configure automated backups. "
+ "Test restore quarterly — paper backups that aren't tested aren't backups. "
+ "Document DR runbook. Annual DR exercise."
+ ),
+ status="In Progress",
+ owner="DevOps",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="ASSET-001",
+ name="Asset Inventory and Classification",
+ description=(
+ "Complete inventory of hardware, software, and data assets. "
+ "Data classification scheme. Ownership assigned to all assets. "
+ "Regular reconciliation."
+ ),
+ soc2_ref="CC6.1",
+ iso27001_ref="A.5.9, A.5.10, A.5.11, A.5.12, A.5.13",
+ hipaa_ref="§164.310(d) Device and Media Controls",
+ gdpr_ref="Art. 30 Records of Processing Activities",
+ effort_days=8,
+ cost_usd=5_000,
+ implementation_notes=(
+ "Build asset register (CMDB or spreadsheet at minimum). "
+ "Classify data: Public, Internal, Confidential, Restricted. "
+ "GDPR requires RoPA (Record of Processing Activities) — data map of all PII. "
+ "ISO 27001 requires SoA referencing asset inventory."
+ ),
+ status="Not Started",
+ owner="IT/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="ENDPOINT-001",
+ name="Endpoint Security",
+ description=(
+ "EDR/antivirus on all managed endpoints. Device management (MDM). "
+ "Full disk encryption. Patch management. BYOD policy."
+ ),
+ soc2_ref="CC6.8",
+ iso27001_ref="A.8.1, A.8.7",
+ hipaa_ref="§164.310(a)(2)(iv) Workstation security",
+ gdpr_ref="Art. 32(1)(a)",
+ effort_days=8,
+ cost_usd=20_000,
+ implementation_notes=(
+ "Deploy EDR (CrowdStrike, SentinelOne, or Microsoft Defender for Business). "
+ "Enable full disk encryption (FileVault/BitLocker). "
+ "MDM for device management. BYOD policy documented."
+ ),
+ status="In Progress",
+ owner="IT",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="POLICY-001",
+ name="Security Policies and Procedures",
+ description=(
+ "Documented security policies covering acceptable use, access control, "
+ "incident response, data classification, vendor management, etc. "
+ "Annual review cycle. Employee attestation."
+ ),
+ soc2_ref="CC1.2, CC1.3",
+ iso27001_ref="A.5.1, A.5.2",
+ hipaa_ref="§164.308(a)(1) Security Management Process",
+ gdpr_ref="Art. 24 Responsibility of the controller",
+ effort_days=15,
+ cost_usd=10_000,
+ implementation_notes=(
+ "Minimum policy set: Information Security Policy, Acceptable Use, "
+ "Access Control, Incident Response, Data Classification, Password, "
+ "Change Management, Vendor Management, Business Continuity. "
+ "Use policy templates from GRC platform (Vanta/Drata)."
+ ),
+ status="In Progress",
+ owner="CISO",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="PRIV-001",
+ name="Privacy and Data Subject Rights",
+ description=(
+ "Privacy policy and notices. Data subject rights fulfilment process "
+ "(access, erasure, portability). Consent management. Cookie compliance. "
+ "Privacy by design in product development."
+ ),
+ soc2_ref=None, # Not a SOC 2 requirement (unless Privacy TSC selected)
+ iso27001_ref="A.5.34",
+ hipaa_ref="§164.524 Access, §164.528 Accounting of Disclosures",
+ gdpr_ref="Art. 13, 14, 15–22 (Rights), Art. 25",
+ effort_days=20,
+ cost_usd=15_000,
+ implementation_notes=(
+ "GDPR: Update privacy policy, implement DSAR process (30-day SLA), "
+ "build deletion capability into product. Cookie consent (PECR/ePrivacy). "
+ "HIPAA: Patient rights for PHI access. "
+ "Consider OneTrust, Termly, or CookieYes for consent management."
+ ),
+ status="Not Started",
+ owner="Legal/Product",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="NET-001",
+ name="Network Security and Segmentation",
+ description=(
+ "Network segmentation (production vs. development vs. corporate). "
+ "Firewall rules. Intrusion detection. VPN or ZTNA for remote access."
+ ),
+ soc2_ref="CC6.6, CC6.7",
+ iso27001_ref="A.8.20, A.8.21, A.8.22",
+ hipaa_ref="§164.312(e)(1) Transmission security",
+ gdpr_ref="Art. 32(1)(a)",
+ effort_days=12,
+ cost_usd=18_000,
+ implementation_notes=(
+ "Segment production from development. WAF in front of public applications. "
+ "Replace VPN with ZTNA for remote access (Series B+ consideration). "
+ "DDoS protection (Cloudflare or AWS Shield)."
+ ),
+ status="In Progress",
+ owner="DevOps",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="PENTEST-001",
+ name="Penetration Testing",
+ description=(
+ "Annual external penetration test by qualified third-party firm. "
+ "Finding remediation tracking. Results reviewed by leadership."
+ ),
+ soc2_ref="CC7.1",
+ iso27001_ref="A.8.8",
+ hipaa_ref="§164.308(a)(8) Evaluation",
+ gdpr_ref="Art. 32(1)(d)",
+ effort_days=5,
+ cost_usd=25_000,
+ implementation_notes=(
+ "Scope: external attack surface, application, API, and optionally social engineering. "
+ "Budget $15–35K for a reputable firm. Track findings in risk register. "
+ "Re-test critical findings within 90 days. Share pentest summary with enterprise "
+ "customers on request (under NDA)."
+ ),
+ status="Not Started",
+ owner="CISO",
+ ))
+
+ return controls
+
+
+# ─── Analysis ────────────────────────────────────────────────────────────────
+
+def calculate_framework_coverage(controls: list[dict]) -> dict:
+ """Calculate per-framework coverage statistics."""
+ coverage = {}
+ for fw in FRAMEWORKS:
+ applicable = [c for c in controls if fw in c["frameworks_applicable"]]
+ implemented = [c for c in applicable if c["status"] in ("Implemented", "Verified")]
+ in_progress = [c for c in applicable if c["status"] == "In Progress"]
+ not_started = [c for c in applicable if c["status"] == "Not Started"]
+
+ total_effort = sum(c["effort_days"] for c in applicable)
+ remaining_effort = sum(
+ c["effort_days"] for c in applicable
+ if c["status"] not in ("Implemented", "Verified")
+ )
+ total_cost = sum(c["cost_usd"] for c in applicable)
+ remaining_cost = sum(
+ c["cost_usd"] for c in applicable
+ if c["status"] not in ("Implemented", "Verified")
+ )
+
+ pct_complete = (len(implemented) / len(applicable) * 100) if applicable else 0
+
+ coverage[fw] = {
+ "framework": FRAMEWORKS[fw]["name"],
+ "total_controls": len(applicable),
+ "implemented": len(implemented),
+ "in_progress": len(in_progress),
+ "not_started": len(not_started),
+ "pct_complete": pct_complete,
+ "total_effort_days": total_effort,
+ "remaining_effort_days": remaining_effort,
+ "total_cost_usd": total_cost,
+ "remaining_cost_usd": remaining_cost,
+ "gap_controls": [c["name"] for c in not_started],
+ }
+
+ return coverage
+
+
+def find_high_leverage_controls(controls: list[dict]) -> list[dict]:
+ """Controls that satisfy the most frameworks — highest ROI to implement."""
+ multi_fw = [c for c in controls if c["framework_count"] >= 3
+ and c["status"] not in ("Implemented", "Verified")]
+ return sorted(multi_fw, key=lambda c: (-c["framework_count"], c["effort_days"]))
+
+
+def estimate_roadmap(controls: list[dict], target_frameworks: list[str]) -> list[dict]:
+ """
+ Generate an ordered implementation roadmap for target frameworks.
+ Prioritize: (1) controls blocking most frameworks, (2) quick wins (low effort).
+ """
+ applicable = [c for c in controls
+ if any(fw in c["frameworks_applicable"] for fw in target_frameworks)
+ and c["status"] not in ("Implemented", "Verified")]
+
+ # Score: (frameworks_covered × 10) - (effort_days) → higher is better
+ for c in applicable:
+ fw_overlap = len([fw for fw in target_frameworks if fw in c["frameworks_applicable"]])
+ c["_priority_score"] = (fw_overlap * 10) - c["effort_days"]
+
+ return sorted(applicable, key=lambda c: -c["_priority_score"])
+
+
+def fmt_dollars(amount: float) -> str:
+ if amount >= 1_000_000:
+ return f"${amount/1_000_000:.1f}M"
+ if amount >= 1_000:
+ return f"${amount/1_000:.0f}K"
+ return f"${amount:.0f}"
+
+
+def status_icon(status: str) -> str:
+ icons = {
+ "Implemented": "✅",
+ "Verified": "✅",
+ "In Progress": "🔄",
+ "Not Started": "⬜",
+ "Planned": "📋",
+ }
+ return icons.get(status, "❓")
+
+
+# ─── Display ─────────────────────────────────────────────────────────────────
+
+def print_header():
+ print("\n" + "=" * 80)
+ print(" CISO COMPLIANCE TRACKER — Multi-Framework Coverage")
+ print(f" Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}")
+ print("=" * 80)
+
+
+def print_framework_summary(coverage: dict):
+ print("\n📋 FRAMEWORK COVERAGE SUMMARY")
+ print("-" * 80)
+ header = f"{'Framework':<20} {'Done':<6} {'WIP':<5} {'Gap':<5} {'Complete':<10} {'Remain Cost':<14} {'Remain Days'}"
+ print(header)
+ print("-" * 80)
+ for fw_id, data in coverage.items():
+ pct = f"{data['pct_complete']:.0f}%"
+ print(
+ f"{data['framework']:<20} {data['implemented']:<6} {data['in_progress']:<5} "
+ f"{data['not_started']:<5} {pct:<10} {fmt_dollars(data['remaining_cost_usd']):<14} "
+ f"{data['remaining_effort_days']} days"
+ )
+
+
+def print_control_table(controls: list[dict], framework_filter: Optional[str] = None):
+ filtered = controls
+ if framework_filter:
+ filtered = [c for c in controls if framework_filter in c["frameworks_applicable"]]
+
+ title = f"CONTROL DOMAINS"
+ if framework_filter:
+ title += f" — {FRAMEWORKS[framework_filter]['name']}"
+
+ print(f"\n🔧 {title}")
+ print("-" * 90)
+ header = f"{'ID':<14} {'Control Name':<30} {'Frameworks':<8} {'Effort':<8} {'Cost':<10} {'Status'}"
+ print(header)
+ print("-" * 90)
+
+ for c in filtered:
+ fw_badges = "/".join(
+ fw.upper()[:3] for fw in ["soc2", "iso27001", "hipaa", "gdpr"]
+ if fw in c["frameworks_applicable"]
+ )
+ icon = status_icon(c["status"])
+ print(
+ f"{c['domain_id']:<14} {c['name'][:29]:<30} {fw_badges:<8} "
+ f"{c['effort_days']:>3}d {fmt_dollars(c['cost_usd']):<10} {icon} {c['status']}"
+ )
+
+
+def print_gap_analysis(coverage: dict):
+ print("\n⚠️ GAP ANALYSIS — Controls Not Yet Started")
+ print("-" * 70)
+ for fw_id, data in coverage.items():
+ if data["gap_controls"]:
+ print(f"\n {data['framework']} — {len(data['gap_controls'])} gaps:")
+ for gap in data["gap_controls"]:
+ print(f" • {gap}")
+
+
+def print_high_leverage(controls: list[dict]):
+ hl = find_high_leverage_controls(controls)
+ print(f"\n🎯 HIGH-LEVERAGE CONTROLS — Implement Once, Satisfy Multiple Frameworks")
+ print("-" * 70)
+ print(f"{'Control':<30} {'Frameworks':<35} {'Effort':<8} {'Cost'}")
+ print("-" * 70)
+ for c in hl:
+ fw_list = " + ".join(FRAMEWORKS[fw]["name"] for fw in c["frameworks_applicable"])
+ print(
+ f"{c['name'][:29]:<30} {fw_list[:34]:<35} "
+ f"{c['effort_days']:>3}d {fmt_dollars(c['cost_usd'])}"
+ )
+
+
+def print_roadmap(controls: list[dict], target_frameworks: list[str]):
+ ordered = estimate_roadmap(controls, target_frameworks)
+ fw_names = " + ".join(FRAMEWORKS[fw]["name"] for fw in target_frameworks)
+ print(f"\n🗺️ IMPLEMENTATION ROADMAP — {fw_names}")
+ print("-" * 80)
+ print("Priority order: most framework coverage first, then quick wins")
+ print()
+
+ cumulative_days = 0
+ cumulative_cost = 0
+ for i, c in enumerate(ordered, 1):
+ cumulative_days += c["effort_days"]
+ cumulative_cost += c["cost_usd"]
+ fw_badges = ", ".join(
+ FRAMEWORKS[fw]["name"] for fw in target_frameworks
+ if fw in c["frameworks_applicable"]
+ )
+ print(f" {i:>2}. {c['name']}")
+ print(f" Frameworks: {fw_badges}")
+ print(f" Effort: {c['effort_days']} days | Cost: {fmt_dollars(c['cost_usd'])} "
+ f"| Cumulative: {cumulative_days}d / {fmt_dollars(cumulative_cost)}")
+ if c.get("owner"):
+ print(f" Owner: {c['owner']}")
+ print()
+
+
+def print_framework_profiles():
+ print("\n💼 FRAMEWORK PROFILES")
+ print("-" * 70)
+ for fw_id, fw in FRAMEWORKS.items():
+ print(f"\n {fw['name']} ({fw_id.upper()})")
+ print(f" Timeline: ~{fw['typical_timeline_months']} months")
+ print(f" First-year cost: {fmt_dollars(fw['typical_cost_usd'])}")
+ print(f" Annual maintenance: {fmt_dollars(fw['annual_maintenance_usd'])}/yr")
+ print(f" Business value: {fw['business_value']}")
+ print(f" Required for: {', '.join(fw['mandatory_for'])}")
+
+
+def export_csv(controls: list[dict], filepath: str):
+ fields = [
+ "domain_id", "name", "frameworks_applicable", "framework_count",
+ "effort_days", "cost_usd", "status", "owner", "target_date",
+ "soc2_ref", "iso27001_ref", "hipaa_ref", "gdpr_ref", "implementation_notes"
+ ]
+ with open(filepath, "w", newline="") as f:
+ writer = csv.DictWriter(f, fieldnames=fields)
+ writer.writeheader()
+ for c in controls:
+ row = {k: c.get(k, "") for k in fields}
+ row["frameworks_applicable"] = ", ".join(c["frameworks_applicable"])
+ row["soc2_ref"] = c["references"].get("soc2", "")
+ row["iso27001_ref"] = c["references"].get("iso27001", "")
+ row["hipaa_ref"] = c["references"].get("hipaa", "")
+ row["gdpr_ref"] = c["references"].get("gdpr", "")
+ writer.writerow(row)
+ print(f"✅ Exported {len(controls)} controls to {filepath}")
+
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="CISO Compliance Tracker — Multi-framework coverage and roadmap"
+ )
+ parser.add_argument("--json", action="store_true", help="Output JSON")
+ parser.add_argument("--csv", metavar="FILE", help="Export CSV to file")
+ parser.add_argument(
+ "--framework", metavar="FRAMEWORK",
+ choices=list(FRAMEWORKS.keys()),
+ help="Filter to single framework (soc2, iso27001, hipaa, gdpr)"
+ )
+ parser.add_argument("--gap-analysis", action="store_true", help="Show gap analysis")
+ parser.add_argument("--roadmap", metavar="FRAMEWORKS",
+ help="Sequenced roadmap for frameworks e.g. 'soc2,iso27001'")
+ parser.add_argument("--profiles", action="store_true", help="Show framework profiles")
+ parser.add_argument("--leverage", action="store_true", help="Show high-leverage controls")
+ args = parser.parse_args()
+
+ controls = load_control_library()
+ coverage = calculate_framework_coverage(controls)
+
+ if args.json:
+ output = {
+ "generated": datetime.now().isoformat(),
+ "frameworks": FRAMEWORKS,
+ "coverage": coverage,
+ "controls": controls,
+ }
+ print(json.dumps(output, indent=2, default=str))
+ return
+
+ if args.csv:
+ export_csv(controls, args.csv)
+ return
+
+ print_header()
+
+ if args.profiles:
+ print_framework_profiles()
+ return
+
+ if args.roadmap:
+ target_fws = [fw.strip() for fw in args.roadmap.split(",") if fw.strip() in FRAMEWORKS]
+ if not target_fws:
+ print(f"Unknown frameworks. Valid: {', '.join(FRAMEWORKS.keys())}")
+ sys.exit(1)
+ print_framework_summary(coverage)
+ print_roadmap(controls, target_fws)
+ return
+
+ print_framework_summary(coverage)
+ print_control_table(controls, args.framework)
+
+ if args.gap_analysis:
+ print_gap_analysis(coverage)
+
+ if args.leverage:
+ print_high_leverage(controls)
+
+ if not any([args.framework, args.gap_analysis, args.leverage]):
+ print_high_leverage(controls)
+ print_gap_analysis(coverage)
+
+ print("\n💡 NEXT STEPS")
+ print(" --roadmap soc2,iso27001 Priority order for dual-framework")
+ print(" --framework hipaa HIPAA-only control view")
+ print(" --gap-analysis What's not started")
+ print(" --leverage Controls covering most frameworks")
+ print(" --profiles Framework timelines and costs")
+ print(" --csv controls.csv Export for stakeholder review")
+ print()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/ciso-advisor/scripts/risk_quantifier.py b/skills/c-level-advisor/ciso-advisor/scripts/risk_quantifier.py
new file mode 100644
index 00000000..f4223093
--- /dev/null
+++ b/skills/c-level-advisor/ciso-advisor/scripts/risk_quantifier.py
@@ -0,0 +1,690 @@
+#!/usr/bin/env python3
+"""
+CISO Risk Quantifier
+====================
+Quantifies security risks in business terms using the FAIR model.
+Calculates ALE (Annual Loss Expectancy) and prioritizes by expected annual loss.
+
+Usage:
+ python risk_quantifier.py # Run with sample data
+ python risk_quantifier.py --json # Output JSON
+ python risk_quantifier.py --csv output.csv # Export CSV
+ python risk_quantifier.py --budget 500000 # Show what fits in budget
+ python risk_quantifier.py --add # Interactive risk entry
+"""
+
+import json
+import csv
+import sys
+import os
+import argparse
+from datetime import datetime
+from typing import Optional
+
+
+# ─── Data Model ─────────────────────────────────────────────────────────────
+
+RISK_CATEGORIES = [
+ "Data Breach",
+ "Ransomware / Extortion",
+ "Insider Threat",
+ "Third-Party / Supply Chain",
+ "Application Vulnerability",
+ "Cloud Misconfiguration",
+ "Social Engineering",
+ "Physical Security",
+ "Business Email Compromise",
+ "DDoS / Availability",
+]
+
+BUSINESS_IMPACT_TYPES = [
+ "Revenue Loss",
+ "Regulatory Fine",
+ "Legal / Litigation",
+ "Reputational Damage",
+ "Recovery / Remediation Cost",
+ "Customer Churn",
+ "Business Interruption",
+]
+
+MITIGATION_STATUSES = ["None", "Planned", "In Progress", "Mitigated", "Accepted"]
+
+
+def build_risk(
+ name: str,
+ category: str,
+ description: str,
+ asset_value: float,
+ exposure_factor: float, # 0.0–1.0: fraction of asset value lost in breach
+ annual_rate: float, # ARO: expected incidents per year (0.01 = once per 100 years)
+ mitigation_cost: float,
+ mitigation_effectiveness: float, # 0.0–1.0: fraction of risk reduced by control
+ mitigation_status: str,
+ business_impacts: dict, # {impact_type: dollar_amount}
+ notes: str = "",
+) -> dict:
+ """Construct a risk record with calculated metrics."""
+ sle = asset_value * exposure_factor # Single Loss Expectancy
+ ale = sle * annual_rate # Annual Loss Expectancy (inherent)
+ mitigated_ale = ale * (1 - mitigation_effectiveness) # Residual after mitigation
+ mitigation_roi = ((ale - mitigated_ale - mitigation_cost) / mitigation_cost * 100
+ if mitigation_cost > 0 else 0)
+ total_business_impact = sum(business_impacts.values())
+
+ return {
+ "name": name,
+ "category": category,
+ "description": description,
+ "asset_value": asset_value,
+ "exposure_factor": exposure_factor,
+ "annual_rate": annual_rate,
+ "mitigation_cost": mitigation_cost,
+ "mitigation_effectiveness": mitigation_effectiveness,
+ "mitigation_status": mitigation_status,
+ "business_impacts": business_impacts,
+ "notes": notes,
+ # Calculated
+ "sle": sle,
+ "ale": ale,
+ "mitigated_ale": mitigated_ale,
+ "mitigation_roi_pct": mitigation_roi,
+ "total_business_impact": total_business_impact,
+ "priority_score": ale, # Primary sort key
+ }
+
+
+# ─── Sample Data ─────────────────────────────────────────────────────────────
+
+def load_sample_risks() -> list[dict]:
+ """
+ Sample risk register for a Series B SaaS company with ~$15M ARR,
+ ~50K customer records, B2B enterprise focus.
+ """
+ risks = []
+
+ risks.append(build_risk(
+ name="Customer Database Breach",
+ category="Data Breach",
+ description=(
+ "Unauthorized access to production database containing 50K+ customer records "
+ "including PII (name, email, company, payment method). Attack vector: SQL injection, "
+ "compromised credentials, or insider access."
+ ),
+ asset_value=5_000_000, # Value of customer database (revenue impact + regulatory)
+ exposure_factor=0.30, # ~30% of asset value lost in a breach event
+ annual_rate=0.12, # ~12% chance per year (based on Verizon DBIR industry data)
+ mitigation_cost=45_000, # WAF + DAST + DB activity monitoring annual cost
+ mitigation_effectiveness=0.80,
+ mitigation_status="In Progress",
+ business_impacts={
+ "Regulatory Fine": 85_000, # GDPR/CCPA exposure
+ "Legal / Litigation": 150_000, # Class action exposure
+ "Customer Churn": 300_000, # Lost ARR from breach-triggered churn
+ "Reputational Damage": 200_000, # Brand impact / deal loss
+ "Recovery / Remediation Cost": 65_000,
+ },
+ notes="SOC 2 Type II controls partially address. Next step: DB activity monitoring.",
+ ))
+
+ risks.append(build_risk(
+ name="Ransomware Attack",
+ category="Ransomware / Extortion",
+ description=(
+ "Ransomware encrypts production systems. Average ransom demand for a "
+ "Series B company is $350K–$800K. Recovery without ransom payment: 2–6 weeks downtime. "
+ "Attack vector: phishing email with malicious attachment, RDP exposure."
+ ),
+ asset_value=3_500_000,
+ exposure_factor=0.25,
+ annual_rate=0.15,
+ mitigation_cost=60_000, # EDR + email security + backup hardening
+ mitigation_effectiveness=0.85,
+ mitigation_status="Planned",
+ business_impacts={
+ "Business Interruption": 450_000, # 4 weeks downtime × $112K/week revenue
+ "Recovery / Remediation Cost": 180_000,
+ "Customer Churn": 125_000,
+ "Revenue Loss": 75_000,
+ },
+ notes="Offline, tested backups reduce recovery time and eliminate ransom pressure.",
+ ))
+
+ risks.append(build_risk(
+ name="Privileged Insider Data Theft",
+ category="Insider Threat",
+ description=(
+ "Disgruntled or financially motivated employee with elevated access exfiltrates "
+ "customer data, IP, or trade secrets. Detection is typically slow (median: 197 days "
+ "per IBM Cost of Data Breach Report)."
+ ),
+ asset_value=2_800_000,
+ exposure_factor=0.20,
+ annual_rate=0.08,
+ mitigation_cost=35_000, # DLP + UEBA + PAM
+ mitigation_effectiveness=0.65,
+ mitigation_status="None",
+ business_impacts={
+ "Legal / Litigation": 120_000,
+ "Customer Churn": 90_000,
+ "Reputational Damage": 75_000,
+ "Recovery / Remediation Cost": 40_000,
+ },
+ notes="No DLP or UEBA currently deployed. Highest detection gap.",
+ ))
+
+ risks.append(build_risk(
+ name="Critical SaaS Vendor Breach (Supply Chain)",
+ category="Third-Party / Supply Chain",
+ description=(
+ "A critical SaaS vendor (e.g., Salesforce, Slack, AWS, GitHub) suffers a breach "
+ "that compromises data entrusted to them or disrupts your operations. You have "
+ "limited control but full liability to customers."
+ ),
+ asset_value=2_200_000,
+ exposure_factor=0.15,
+ annual_rate=0.18,
+ mitigation_cost=20_000, # Vendor risk assessment program
+ mitigation_effectiveness=0.40, # Limited — you can't control vendor security
+ mitigation_status="Planned",
+ business_impacts={
+ "Business Interruption": 95_000,
+ "Customer Churn": 75_000,
+ "Reputational Damage": 50_000,
+ "Recovery / Remediation Cost": 30_000,
+ },
+ notes="Third-party risk is partially transferable via contractual SLAs and cyber insurance.",
+ ))
+
+ risks.append(build_risk(
+ name="Business Email Compromise (BEC)",
+ category="Business Email Compromise",
+ description=(
+ "Attacker impersonates CEO, CFO, or vendor to redirect wire transfers, gift card "
+ "purchases, or payroll. Median BEC loss: $125K. FBI IC3 reports BEC as #1 "
+ "cybercrime by financial loss."
+ ),
+ asset_value=500_000,
+ exposure_factor=0.40,
+ annual_rate=0.30,
+ mitigation_cost=12_000, # Email authentication (DMARC) + training + callback procedures
+ mitigation_effectiveness=0.90,
+ mitigation_status="In Progress",
+ business_impacts={
+ "Revenue Loss": 125_000, # Direct financial theft (often unrecoverable)
+ "Recovery / Remediation Cost": 25_000,
+ "Legal / Litigation": 15_000,
+ },
+ notes="DMARC deployed. Need to enforce wire transfer callback procedures.",
+ ))
+
+ risks.append(build_risk(
+ name="Cloud Misconfiguration — S3 / Storage Exposure",
+ category="Cloud Misconfiguration",
+ description=(
+ "Public exposure of S3 buckets, GCS buckets, or Azure Blob storage containing "
+ "sensitive data. One of the most common causes of data breaches. Often undetected "
+ "for months. 2023 IBM study: 82% of breaches involved data stored in cloud."
+ ),
+ asset_value=1_800_000,
+ exposure_factor=0.20,
+ annual_rate=0.20,
+ mitigation_cost=18_000, # CSPM tool + IaC scanning
+ mitigation_effectiveness=0.90,
+ mitigation_status="Planned",
+ business_impacts={
+ "Regulatory Fine": 60_000,
+ "Reputational Damage": 120_000,
+ "Legal / Litigation": 45_000,
+ "Recovery / Remediation Cost": 35_000,
+ },
+ notes="No CSPM currently. High frequency, high detectability, low mitigation cost.",
+ ))
+
+ risks.append(build_risk(
+ name="Credential Stuffing — Customer Accounts",
+ category="Application Vulnerability",
+ description=(
+ "Attackers use leaked credential lists to compromise customer accounts. "
+ "Account takeover leads to data theft, fraudulent transactions, and support burden. "
+ "16 billion credentials available on darknet as of 2024."
+ ),
+ asset_value=1_200_000,
+ exposure_factor=0.12,
+ annual_rate=0.40,
+ mitigation_cost=15_000, # MFA + rate limiting + bot detection
+ mitigation_effectiveness=0.95,
+ mitigation_status="In Progress",
+ business_impacts={
+ "Customer Churn": 80_000,
+ "Revenue Loss": 45_000,
+ "Recovery / Remediation Cost": 19_000,
+ "Reputational Damage": 30_000,
+ },
+ notes="MFA available but optional. Enforcing MFA cuts this risk by ~99%.",
+ ))
+
+ risks.append(build_risk(
+ name="Phishing — Employee Credential Compromise",
+ category="Social Engineering",
+ description=(
+ "Employee clicks phishing link, surrenders credentials. Without MFA, "
+ "this provides full access to email, SaaS apps, and potentially production. "
+ "Phishing is the #1 attack vector in the Verizon DBIR."
+ ),
+ asset_value=1_500_000,
+ exposure_factor=0.15,
+ annual_rate=0.35,
+ mitigation_cost=25_000, # MFA + security awareness training + email security
+ mitigation_effectiveness=0.92,
+ mitigation_status="In Progress",
+ business_impacts={
+ "Business Interruption": 65_000,
+ "Customer Churn": 55_000,
+ "Recovery / Remediation Cost": 45_000,
+ "Reputational Damage": 60_000,
+ },
+ notes="Primary vector for ransomware and BEC. MFA is the single highest-ROI control.",
+ ))
+
+ risks.append(build_risk(
+ name="Application API Vulnerability",
+ category="Application Vulnerability",
+ description=(
+ "Unauthenticated or improperly authorized API endpoint exposes customer data "
+ "or administrative functions. OWASP API Security Top 10 — broken object-level "
+ "authorization is the most common API vulnerability."
+ ),
+ asset_value=2_000_000,
+ exposure_factor=0.18,
+ annual_rate=0.15,
+ mitigation_cost=30_000, # DAST + API gateway + code review
+ mitigation_effectiveness=0.75,
+ mitigation_status="Planned",
+ business_impacts={
+ "Regulatory Fine": 70_000,
+ "Customer Churn": 90_000,
+ "Reputational Damage": 100_000,
+ "Legal / Litigation": 60_000,
+ },
+ notes="Need automated API security testing in CI/CD pipeline.",
+ ))
+
+ risks.append(build_risk(
+ name="DDoS Attack — Production Service",
+ category="DDoS / Availability",
+ description=(
+ "Distributed denial-of-service attack renders production service unavailable. "
+ "Average DDoS duration: 4–8 hours. Enterprise SLA breach triggers contractual "
+ "penalties. Increasingly used as extortion or distraction tactic."
+ ),
+ asset_value=1_000_000,
+ exposure_factor=0.10,
+ annual_rate=0.25,
+ mitigation_cost=15_000, # CDN with DDoS protection (Cloudflare, AWS Shield)
+ mitigation_effectiveness=0.85,
+ mitigation_status="Mitigated",
+ business_impacts={
+ "Business Interruption": 45_000,
+ "Customer Churn": 30_000,
+ "Revenue Loss": 25_000,
+ },
+ notes="Cloudflare deployed. Residual risk from very large volumetric attacks.",
+ ))
+
+ return risks
+
+
+# ─── Analysis & Reporting ────────────────────────────────────────────────────
+
+def calculate_portfolio_summary(risks: list[dict]) -> dict:
+ """Aggregate portfolio-level metrics."""
+ total_inherent_ale = sum(r["ale"] for r in risks)
+ total_mitigated_ale = sum(r["mitigated_ale"] for r in risks)
+ total_mitigation_cost = sum(r["mitigation_cost"] for r in risks)
+ risk_reduction = total_inherent_ale - total_mitigated_ale
+ portfolio_roi = ((risk_reduction - total_mitigation_cost) / total_mitigation_cost * 100
+ if total_mitigation_cost > 0 else 0)
+
+ by_category = {}
+ for r in risks:
+ cat = r["category"]
+ if cat not in by_category:
+ by_category[cat] = {"count": 0, "total_ale": 0.0}
+ by_category[cat]["count"] += 1
+ by_category[cat]["total_ale"] += r["ale"]
+
+ by_status = {}
+ for r in risks:
+ status = r["mitigation_status"]
+ by_status[status] = by_status.get(status, 0) + 1
+
+ return {
+ "total_risks": len(risks),
+ "total_inherent_ale": total_inherent_ale,
+ "total_mitigated_ale": total_mitigated_ale,
+ "total_risk_reduction": risk_reduction,
+ "total_mitigation_cost": total_mitigation_cost,
+ "portfolio_roi_pct": portfolio_roi,
+ "by_category": dict(sorted(by_category.items(), key=lambda x: -x[1]["total_ale"])),
+ "by_mitigation_status": by_status,
+ }
+
+
+def prioritize_risks(risks: list[dict], budget: Optional[float] = None) -> list[dict]:
+ """Return risks sorted by ALE. If budget given, show what fits."""
+ sorted_risks = sorted(risks, key=lambda r: -r["ale"])
+ if budget is None:
+ return sorted_risks
+
+ # Greedy budget allocation by ROI
+ actionable = [r for r in sorted_risks if r["mitigation_status"] in ("None", "Planned")
+ and r["mitigation_cost"] > 0]
+ actionable.sort(key=lambda r: -r["mitigation_roi_pct"])
+
+ allocated = []
+ remaining = budget
+ for risk in actionable:
+ if risk["mitigation_cost"] <= remaining:
+ allocated.append(risk)
+ remaining -= risk["mitigation_cost"]
+
+ return allocated
+
+
+def fmt_dollars(amount: float) -> str:
+ """Format a dollar amount."""
+ if amount >= 1_000_000:
+ return f"${amount/1_000_000:.2f}M"
+ if amount >= 1_000:
+ return f"${amount/1_000:.0f}K"
+ return f"${amount:.0f}"
+
+
+def fmt_pct(value: float) -> str:
+ return f"{value:.1f}%"
+
+
+def severity_label(ale: float) -> str:
+ if ale >= 200_000:
+ return "CRITICAL"
+ if ale >= 75_000:
+ return "HIGH"
+ if ale >= 25_000:
+ return "MEDIUM"
+ return "LOW"
+
+
+def severity_color(label: str) -> str:
+ """ANSI color codes."""
+ colors = {
+ "CRITICAL": "\033[91m", # Red
+ "HIGH": "\033[93m", # Yellow
+ "MEDIUM": "\033[94m", # Blue
+ "LOW": "\033[92m", # Green
+ }
+ return colors.get(label, "") + label + "\033[0m"
+
+
+# ─── Display ─────────────────────────────────────────────────────────────────
+
+def print_header():
+ print("\n" + "=" * 80)
+ print(" CISO RISK QUANTIFIER — Security Risk Portfolio")
+ print(f" Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}")
+ print("=" * 80)
+
+
+def print_portfolio_summary(summary: dict):
+ print("\n📊 PORTFOLIO SUMMARY")
+ print("-" * 60)
+ print(f" Total risks tracked: {summary['total_risks']}")
+ print(f" Total inherent ALE: {fmt_dollars(summary['total_inherent_ale'])}/yr")
+ print(f" Total ALE after mitigations: {fmt_dollars(summary['total_mitigated_ale'])}/yr")
+ print(f" Risk reduction from controls: {fmt_dollars(summary['total_risk_reduction'])}/yr")
+ print(f" Total mitigation spend: {fmt_dollars(summary['total_mitigation_cost'])}/yr")
+ print(f" Portfolio ROI: {fmt_pct(summary['portfolio_roi_pct'])}")
+ print()
+
+ print(" Risk by Category (sorted by ALE):")
+ for cat, data in summary["by_category"].items():
+ print(f" {cat:<35} {data['count']} risks ALE: {fmt_dollars(data['total_ale'])}/yr")
+
+ print()
+ print(" Mitigation Status:")
+ for status, count in summary["by_mitigation_status"].items():
+ print(f" {status:<20} {count} risks")
+
+
+def print_risk_table(risks: list[dict], title: str = "RISK REGISTER"):
+ print(f"\n🎯 {title}")
+ print("-" * 80)
+ header = f"{'#':<3} {'Risk Name':<35} {'Severity':<10} {'ALE/yr':<12} {'Mitig Cost':<12} {'ROI':<8} {'Status':<12}"
+ print(header)
+ print("-" * 80)
+
+ for i, risk in enumerate(risks, 1):
+ sev = severity_label(risk["ale"])
+ sev_str = sev.ljust(10)
+ roi = fmt_pct(risk["mitigation_roi_pct"]) if risk["mitigation_cost"] > 0 else "N/A"
+ print(
+ f"{i:<3} {risk['name'][:34]:<35} {sev_str} "
+ f"{fmt_dollars(risk['ale']):<12} {fmt_dollars(risk['mitigation_cost']):<12} "
+ f"{roi:<8} {risk['mitigation_status']}"
+ )
+
+
+def print_risk_detail(risk: dict, index: int):
+ sev = severity_label(risk["ale"])
+ print(f"\n{'─' * 70}")
+ print(f" #{index} — {risk['name']} [{sev}]")
+ print(f"{'─' * 70}")
+ print(f" Category: {risk['category']}")
+ print(f" Description: {risk['description'][:120]}...")
+ print()
+ print(f" RISK CALCULATION:")
+ print(f" Asset Value: {fmt_dollars(risk['asset_value'])}")
+ print(f" Exposure Factor: {fmt_pct(risk['exposure_factor'] * 100)}")
+ print(f" Single Loss Expectancy: {fmt_dollars(risk['sle'])}")
+ print(f" Annual Rate (ARO): {risk['annual_rate']:.2f}x/year")
+ print(f" Annual Loss Expectancy: {fmt_dollars(risk['ale'])}/yr ← INHERENT RISK")
+ print()
+ print(f" MITIGATION:")
+ print(f" Mitigation Cost: {fmt_dollars(risk['mitigation_cost'])}/yr")
+ print(f" Effectiveness: {fmt_pct(risk['mitigation_effectiveness'] * 100)}")
+ print(f" Residual ALE: {fmt_dollars(risk['mitigated_ale'])}/yr")
+ print(f" Mitigation ROI: {fmt_pct(risk['mitigation_roi_pct'])}")
+ print(f" Status: {risk['mitigation_status']}")
+ print()
+ print(f" BUSINESS IMPACT BREAKDOWN:")
+ for impact_type, amount in risk["business_impacts"].items():
+ print(f" {impact_type:<30} {fmt_dollars(amount)}")
+ print(f" {'TOTAL':<30} {fmt_dollars(risk['total_business_impact'])}")
+ if risk["notes"]:
+ print(f"\n NOTES: {risk['notes']}")
+
+
+def print_board_summary(risks: list[dict], summary: dict):
+ """One-page board-ready summary."""
+ print("\n" + "═" * 80)
+ print(" BOARD SECURITY REPORT — Risk Summary")
+ print("═" * 80)
+
+ critical = [r for r in risks if severity_label(r["ale"]) == "CRITICAL"]
+ high = [r for r in risks if severity_label(r["ale"]) == "HIGH"]
+ medium = [r for r in risks if severity_label(r["ale"]) == "MEDIUM"]
+ low = [r for r in risks if severity_label(r["ale"]) == "LOW"]
+
+ print(f"\n RISK EXPOSURE SUMMARY")
+ print(f" ┌─────────────┬────────┬──────────────┐")
+ print(f" │ Severity │ Count │ Total ALE/yr │")
+ print(f" ├─────────────┼────────┼──────────────┤")
+ for label, group in [("Critical", critical), ("High", high), ("Medium", medium), ("Low", low)]:
+ ale = sum(r["ale"] for r in group)
+ print(f" │ {label:<11} │ {len(group):<6} │ {fmt_dollars(ale):<12} │")
+ print(f" └─────────────┴────────┴──────────────┘")
+
+ print(f"\n TOTAL INHERENT RISK: {fmt_dollars(summary['total_inherent_ale'])}/yr")
+ print(f" SECURITY INVESTMENT: {fmt_dollars(summary['total_mitigation_cost'])}/yr")
+ print(f" RESIDUAL RISK: {fmt_dollars(summary['total_mitigated_ale'])}/yr")
+ print(f" RISK REDUCTION: {fmt_dollars(summary['total_risk_reduction'])}/yr")
+ print(f" PORTFOLIO ROI: {fmt_pct(summary['portfolio_roi_pct'])}")
+
+ print(f"\n TOP 3 RISKS BY EXPECTED ANNUAL LOSS:")
+ top3 = sorted(risks, key=lambda r: -r["ale"])[:3]
+ for i, risk in enumerate(top3, 1):
+ print(f" {i}. {risk['name']}: {fmt_dollars(risk['ale'])}/yr expected annual loss")
+ print(f" Mitigation: {fmt_dollars(risk['mitigation_cost'])}/yr | "
+ f"Status: {risk['mitigation_status']}")
+
+ unmitigated = [r for r in risks if r["mitigation_status"] == "None"]
+ if unmitigated:
+ print(f"\n ⚠️ UNMITIGATED RISKS ({len(unmitigated)}):")
+ for r in sorted(unmitigated, key=lambda x: -x["ale"]):
+ print(f" • {r['name']}: {fmt_dollars(r['ale'])}/yr — Action required")
+
+
+def export_csv(risks: list[dict], filepath: str):
+ fields = [
+ "name", "category", "asset_value", "exposure_factor", "annual_rate",
+ "sle", "ale", "mitigation_cost", "mitigation_effectiveness",
+ "mitigated_ale", "mitigation_roi_pct", "mitigation_status", "notes"
+ ]
+ with open(filepath, "w", newline="") as f:
+ writer = csv.DictWriter(f, fieldnames=fields)
+ writer.writeheader()
+ for risk in risks:
+ row = {k: risk.get(k, "") for k in fields}
+ writer.writerow(row)
+ print(f"✅ Exported {len(risks)} risks to {filepath}")
+
+
+def export_json(risks: list[dict]) -> str:
+ return json.dumps(risks, indent=2, default=str)
+
+
+# ─── Interactive Entry ───────────────────────────────────────────────────────
+
+def interactive_add_risk() -> dict:
+ """Interactive CLI for adding a new risk."""
+ print("\n── ADD NEW RISK ──────────────────────────────────────")
+ name = input("Risk name: ").strip()
+
+ print(f"Category options: {', '.join(RISK_CATEGORIES)}")
+ category = input("Category: ").strip()
+
+ description = input("Description (brief): ").strip()
+
+ print("\nAsset valuation:")
+ asset_value = float(input(" Asset value ($): ").replace(",", "").replace("$", ""))
+ exposure_factor = float(input(" Exposure factor (0.0–1.0, fraction of value lost): "))
+ annual_rate = float(input(" Annual rate of occurrence (e.g., 0.10 = once per 10 years): "))
+
+ print("\nMitigation:")
+ mitigation_cost = float(input(" Mitigation cost ($/yr): ").replace(",", "").replace("$", ""))
+ mitigation_effectiveness = float(input(" Mitigation effectiveness (0.0–1.0): "))
+
+ print(f"Status options: {', '.join(MITIGATION_STATUSES)}")
+ mitigation_status = input(" Status: ").strip()
+
+ print("\nBusiness impacts (enter 0 to skip):")
+ business_impacts = {}
+ for impact_type in BUSINESS_IMPACT_TYPES:
+ val = input(f" {impact_type} ($): ").replace(",", "").replace("$", "")
+ amount = float(val) if val else 0
+ if amount > 0:
+ business_impacts[impact_type] = amount
+
+ notes = input("\nNotes: ").strip()
+
+ return build_risk(
+ name=name,
+ category=category,
+ description=description,
+ asset_value=asset_value,
+ exposure_factor=exposure_factor,
+ annual_rate=annual_rate,
+ mitigation_cost=mitigation_cost,
+ mitigation_effectiveness=mitigation_effectiveness,
+ mitigation_status=mitigation_status,
+ business_impacts=business_impacts,
+ notes=notes,
+ )
+
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="CISO Risk Quantifier — Quantify security risks in business terms"
+ )
+ parser.add_argument("--json", action="store_true", help="Output full JSON")
+ parser.add_argument("--csv", metavar="FILE", help="Export CSV to file")
+ parser.add_argument("--budget", type=float, metavar="DOLLARS",
+ help="Show recommended mitigations within budget")
+ parser.add_argument("--board", action="store_true", help="Show board-ready summary only")
+ parser.add_argument("--detail", action="store_true", help="Show detailed risk breakdowns")
+ parser.add_argument("--add", action="store_true", help="Interactively add a risk")
+ args = parser.parse_args()
+
+ risks = load_sample_risks()
+
+ if args.add:
+ new_risk = interactive_add_risk()
+ risks.append(new_risk)
+ print(f"\n✅ Added risk: {new_risk['name']} | ALE: {fmt_dollars(new_risk['ale'])}/yr")
+
+ # Sort by ALE descending
+ risks_sorted = sorted(risks, key=lambda r: -r["ale"])
+ summary = calculate_portfolio_summary(risks_sorted)
+
+ if args.json:
+ output = {
+ "generated": datetime.now().isoformat(),
+ "summary": summary,
+ "risks": risks_sorted,
+ }
+ print(json.dumps(output, indent=2, default=str))
+ return
+
+ if args.csv:
+ export_csv(risks_sorted, args.csv)
+ return
+
+ print_header()
+
+ if args.board:
+ print_board_summary(risks_sorted, summary)
+ return
+
+ print_portfolio_summary(summary)
+ print_risk_table(risks_sorted)
+
+ if args.detail:
+ for i, risk in enumerate(risks_sorted, 1):
+ print_risk_detail(risk, i)
+
+ if args.budget:
+ recommended = prioritize_risks(risks_sorted, args.budget)
+ print(f"\n💰 BUDGET ALLOCATION — ${args.budget:,.0f}")
+ print(f" Recommended mitigations (sorted by ROI):")
+ if recommended:
+ for r in recommended:
+ print(f" • {r['name']}: {fmt_dollars(r['mitigation_cost'])}/yr "
+ f"| ALE reduction: {fmt_dollars(r['ale'] - r['mitigated_ale'])}/yr "
+ f"| ROI: {fmt_pct(r['mitigation_roi_pct'])}")
+ else:
+ print(" No actionable mitigations fit within budget.")
+
+ print_board_summary(risks_sorted, summary)
+
+ print("\n💡 NEXT STEPS")
+ print(" 1. Run `--detail` to see full breakdown of each risk")
+ print(" 2. Run `--budget 200000` to see what you can mitigate with a given budget")
+ print(" 3. Run `--board` for a board-ready one-page summary")
+ print(" 4. Run `--csv risks.csv` to export for stakeholder review")
+ print(" 5. Run `--add` to interactively add risks to the register")
+ print()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cmo-advisor/SKILL.md b/skills/c-level-advisor/cmo-advisor/SKILL.md
new file mode 100644
index 00000000..f8fc3298
--- /dev/null
+++ b/skills/c-level-advisor/cmo-advisor/SKILL.md
@@ -0,0 +1,169 @@
+---
+name: "cmo-advisor"
+description: "Marketing leadership for scaling companies. Brand positioning, growth model design, marketing budget allocation, and marketing org design. Use when designing brand strategy, selecting growth models (PLG vs sales-led vs community-led), allocating marketing budgets, building marketing teams, or when user mentions CMO, brand strategy, growth model, CAC, LTV, channel mix, or marketing ROI."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: cmo-leadership
+ updated: 2026-03-05
+ python-tools: marketing_budget_modeler.py, growth_model_simulator.py
+ frameworks: brand-positioning, growth-frameworks, marketing-org
+---
+
+# CMO Advisor
+
+Strategic marketing leadership — brand positioning, growth model design, budget allocation, and org design. Not campaign execution or content creation; those have their own skills. This is the engine.
+
+## Keywords
+CMO, chief marketing officer, brand strategy, brand positioning, growth model, product-led growth, PLG, sales-led growth, community-led growth, marketing budget, CAC, customer acquisition cost, LTV, lifetime value, channel mix, marketing ROI, pipeline contribution, marketing org, category design, competitive positioning, growth loops, payback period, MQL, pipeline coverage
+
+## Quick Start
+
+```bash
+# Model budget allocation across channels, project MQL output by scenario
+python scripts/marketing_budget_modeler.py
+
+# Project MRR growth by model, show impact of channel mix shifts
+python scripts/growth_model_simulator.py
+```
+
+**Reference docs (load when needed):**
+- `references/brand_positioning.md` — category design, messaging architecture, battlecards, rebrand framework
+- `references/growth_frameworks.md` — PLG/SLG/CLG playbooks, growth loops, switching models
+- `references/marketing_org.md` — team structure by stage, hiring sequence, agency vs. in-house
+
+---
+
+## The Four CMO Questions
+
+Every CMO must own answers to these — no one else in the C-suite can:
+
+1. **Who are we for?** — ICP, positioning, category
+2. **Why do they choose us?** — Differentiation, messaging, brand
+3. **How do they find us?** — Growth model, channel mix, demand gen
+4. **Is it working?** — CAC, LTV:CAC, pipeline contribution, payback period
+
+---
+
+## Core Responsibilities (Brief)
+
+**Brand & Positioning** — Define category, build messaging architecture, maintain competitive differentiation. Details → `references/brand_positioning.md`
+
+**Growth Model** — Choose and operate the right acquisition engine: PLG, sales-led, community-led, or hybrid. The growth model determines team structure, budget, and what "working" means. Details → `references/growth_frameworks.md`
+
+**Marketing Budget** — Allocate from revenue target backward: new customers needed → conversion rates by stage → MQLs needed → spend by channel based on CAC. Run `marketing_budget_modeler.py` for scenarios.
+
+**Marketing Org** — Structure follows growth model. Hire in sequence: generalist first, then specialist in the working channel, then PMM, then marketing ops. Details → `references/marketing_org.md`
+
+**Channel Mix** — Audit quarterly: MQLs, cost, CAC, payback, trend. Scale what's improving. Cut what's worsening. Don't optimize a channel that isn't in the strategy.
+
+**Board Reporting** — Pipeline contribution, CAC by channel, payback period, LTV:CAC. Not impressions. Not MQLs in isolation.
+
+---
+
+## Key Diagnostic Questions
+
+Ask these before making any strategic recommendation:
+
+- What's your CAC **by channel** (not blended)?
+- What's the payback period on your largest channel?
+- What's your LTV:CAC ratio?
+- What % of pipeline is marketing-sourced vs. sales-sourced?
+- Where do your **best customers** (highest LTV, lowest churn) come from?
+- What's your MQL → Opportunity conversion rate? (proxy for lead quality)
+- Is this brand work or performance marketing? (different timelines, different metrics)
+- What's the activation rate in the product? (PLG signal)
+- If a prospect doesn't buy, why not? (win/loss data)
+
+---
+
+## CMO Metrics Dashboard
+
+| Category | Metric | Healthy Target |
+|----------|--------|---------------|
+| **Pipeline** | Marketing-sourced pipeline % | 50–70% of total |
+| **Pipeline** | Pipeline coverage ratio | 3–4x quarterly quota |
+| **Pipeline** | MQL → Opportunity rate | > 15% |
+| **Efficiency** | Blended CAC payback | < 18 months |
+| **Efficiency** | LTV:CAC ratio | > 3:1 |
+| **Efficiency** | Marketing % of total S&M spend | 30–50% |
+| **Growth** | Brand search volume trend | ↑ QoQ |
+| **Growth** | Win rate vs. primary competitor | > 50% |
+| **Retention** | NPS (marketing-sourced cohort) | > 40 |
+
+---
+
+## Red Flags
+
+- No defined ICP — "companies with 50-1000 employees" is not an ICP
+- Marketing and sales disagree on what an MQL is (this is always a system problem, not a people problem)
+- CAC tracked only as a blended number — channel-level CAC is non-negotiable
+- Pipeline attribution is self-reported by sales reps, not CRM-timestamped
+- CMO can't answer "what's our payback period?" without a 48-hour research project
+- Brand work and performance marketing have no shared narrative — they're contradicting each other
+- Marketing team is producing content with no documented positioning to anchor it
+- Growth model was chosen because a competitor uses it, not because the product/ACV/ICP fits
+
+---
+
+## Integration with Other C-Suite Roles
+
+| When... | CMO works with... | To... |
+|---------|-------------------|-------|
+| Pricing changes | CFO + CEO | Understand margin impact on positioning and messaging |
+| Product launch | CPO + CTO | Define launch tier, GTM motion, messaging |
+| Pipeline miss | CFO + CRO | Diagnose: volume problem, quality problem, or velocity problem |
+| Category design | CEO | Secure multi-year organizational commitment to the narrative |
+| New market entry | CEO + CFO | Validate ICP, budget, localization requirements |
+| Sales misalignment | CRO | Align on MQL definition, SLA, and pipeline ownership |
+| Hiring plan | CHRO | Define marketing headcount and skill profile by stage |
+| Retention insights | CCO | Use expansion and churn data to sharpen ICP and messaging |
+| Competitive threat | CEO + CRO | Coordinate battlecards, win/loss, repositioning response |
+
+---
+
+## Resources
+
+- **References:** `references/brand_positioning.md`, `references/growth_frameworks.md`, `references/marketing_org.md`
+- **Scripts:** `scripts/marketing_budget_modeler.py`, `scripts/growth_model_simulator.py`
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- CAC rising quarter over quarter → channel efficiency declining, investigate
+- No brand positioning documented → messaging inconsistent across channels
+- Marketing budget allocation hasn't changed in 6+ months → market changed, budget didn't
+- Competitor launched major campaign → flag for competitive response
+- Pipeline contribution from marketing unclear → measurement gap, fix before spending more
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Plan our marketing budget" | Channel allocation model with CAC targets per channel |
+| "Position us vs competitors" | Positioning map + messaging framework + proof points |
+| "Design our growth model" | Growth projection with channel mix scenarios |
+| "Build the marketing team" | Hiring plan with sequence, roles, agency vs in-house |
+| "Marketing board section" | Pipeline contribution report with channel ROI |
+
+## Reasoning Technique: Recursion of Thought
+
+Draft a marketing strategy, then critique it from the customer's perspective. Refine based on the critique. Repeat until the strategy survives scrutiny.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/c-level-advisor/cmo-advisor/references/brand_positioning.md b/skills/c-level-advisor/cmo-advisor/references/brand_positioning.md
new file mode 100644
index 00000000..1a1acf22
--- /dev/null
+++ b/skills/c-level-advisor/cmo-advisor/references/brand_positioning.md
@@ -0,0 +1,374 @@
+# Brand Positioning Reference
+
+Practical frameworks for defining, communicating, and defending your market position. Not theory — applied tools for CMOs who need to get this right.
+
+---
+
+## 1. Category Design Frameworks
+
+### The Category Design Principle
+
+Every product exists in a category — either one you define or one someone else defined. If you're not designing your category, your competitors are designing it for you, and they'll design it to exclude you.
+
+**Category design is not renaming an existing category.** It's declaring that the existing category no longer solves the problem adequately, and that a new category — which you happen to lead — is required.
+
+### The Three-Act Category Design Narrative
+
+**Act 1: Name the problem**
+Identify a problem that's real, growing, and underserved. Not a problem you invented — a problem your best customers articulate before they've heard your pitch.
+
+> "Enterprise software teams are deploying faster than ever, but their security reviews still take 3 weeks — because security was built for a world where deployments happen monthly, not hourly."
+
+**Act 2: Define the new category**
+Name the category in terms of the outcome, not the feature. The category name should describe what customers achieve, not what the product does.
+
+> "Continuous security" — not "automated security scanning" or "DevSecOps platform."
+
+**Act 3: Position yourself as the category leader**
+You can't just claim leadership — you need proof: customers, analysts, community, content, events. Leadership is built, not declared.
+
+> "Snyk is building the continuous security category. 1.2M developers have adopted Snyk. Gartner lists us as a Cool Vendor in AppSec."
+
+### When Category Design Works
+
+| Condition | Explanation |
+|-----------|-------------|
+| Market timing | The problem is growing but the existing category is inadequate |
+| CEO commitment | Category design is a 3-5 year initiative, not a marketing campaign |
+| Analyst alignment | Gartner, Forrester, or G2 need to recognize your category |
+| Community | Practitioners adopt the vocabulary before buyers do |
+| Content moat | You publish the defining content for the category before competitors |
+
+### Category Design Pitfalls
+
+- **Naming the category after yourself:** "The [Your Company] Category" is not a category. It's a vanity.
+- **Categories that don't solve analyst definitions:** If Gartner doesn't have a Magic Quadrant for your category, you're fighting uphill.
+- **Jargon without adoption:** If your category name requires a two-paragraph explanation, it won't stick.
+- **Starting a category war you can't win:** If an incumbent can copy your category name and launch in 90 days, you don't have a defensible category.
+
+### The Lightning Strike Strategy
+
+Category design requires concentrated, coordinated effort — not slow drip. Execute these simultaneously:
+
+1. **Major piece of research or data** (the "State of X" report)
+2. **Category-defining event** (host it, don't just attend)
+3. **Analyst briefing** (educate Gartner/Forrester on the category before they define it themselves)
+4. **Book or manifesto** (long-form content that becomes the category Bible)
+5. **Community formation** (a Slack group, a conference, a certification that practitioners want)
+
+Do all five within a 3-month window. This creates gravity around your category claim.
+
+---
+
+## 2. Messaging Architecture
+
+### The Messaging Hierarchy
+
+Every piece of content — from a tweet to a 60-page whitepaper — should trace back to this hierarchy. When it doesn't, you have messaging drift.
+
+```
+Level 1: Brand Promise
+"[Company] [verb] [outcome] for [audience]"
+→ Doesn't change. This is the north star.
+
+Level 2: Positioning Statement (internal)
+For [target customer] who [has this problem],
+[Company] is the [market category] that [differentiated capability]
+unlike [alternatives], [Company] [proof of differentiation].
+
+Level 3: Value Propositions (3-4 max, one per key outcome)
+Each VP: headline (5-8 words) + 2-3 sentence explanation + proof point
+
+Level 4: Proof Points
+Data, case studies, certifications, analyst recognition — evidence for each VP
+
+Level 5: Channel Adaptations
+Website copy, sales deck, ad copy, email — same hierarchy, different format
+```
+
+### Writing a Positioning Statement
+
+The Geoffrey Moore / April Dunford format is still the best framework:
+
+**Template:**
+```
+For [specific target customer]
+who [has this specific, painful problem],
+[Company name] is the [market category]
+that [key differentiated capability].
+Unlike [primary alternatives],
+[Company] [proof of differentiation — something measurable or unique].
+```
+
+**Bad example (too generic):**
+> For B2B companies who want to grow faster, Acme is the marketing platform that helps you get more leads. Unlike other platforms, Acme is easy to use and powerful.
+
+**Good example (specific and falsifiable):**
+> For DevOps teams in regulated industries who spend 20% of their sprint cycles on compliance reviews, Acme is the compliance automation platform that embeds regulatory checks directly into the CI/CD pipeline. Unlike manual compliance tools that create a separate review queue, Acme's policy-as-code approach reduces compliance-related cycle time by 60% without slowing deployments.
+
+**Test your positioning statement:**
+1. Can a competitor say the exact same thing? (If yes, it's not differentiated)
+2. Does it describe what you do or what the customer gets? (Should be the latter)
+3. Would your best customer say "yes, that's exactly my problem"? (If not, wrong ICP)
+4. Is it falsifiable? (Claims you can't prove are liabilities)
+
+### Value Proposition Development
+
+**Structure for each VP:**
+
+| Element | Description | Example |
+|---------|-------------|---------|
+| Outcome headline | What changes for the customer (5-8 words) | "Ship features 3x faster" |
+| The problem | Why this matters now (1 sentence) | "Compliance reviews block 40% of releases in regulated industries" |
+| Our approach | How we solve it differently (1-2 sentences) | "Policy-as-code embeds checks in the pipeline instead of adding a gate at the end" |
+| Proof | Evidence this is real (1 sentence + data point) | "Customers reduce compliance cycle time by 60% in the first 90 days" |
+
+**3-VP Architecture is the standard:**
+- VP1: Core outcome (what most customers primarily buy for)
+- VP2: Secondary benefit (makes the decision easier or stickier)
+- VP3: Differentiator (what tips competitive decisions in your favor)
+
+### Proof Point Hierarchy
+
+Not all proof is equal. When you make a claim, match the strength of your proof to the importance of the claim.
+
+| Proof Type | Strength | Best Used For |
+|------------|---------|--------------|
+| Third-party data (analyst report, research) | Highest | Category claims, market size |
+| Customer ROI data with name | High | Value propositions |
+| Customer quote with name and company | Medium-high | Specific pain points and outcomes |
+| Aggregated customer data ("customers report…") | Medium | Directional claims |
+| Internal testing or benchmark | Medium-low | Product capability claims |
+| "Designed to…" or "built for…" | Low | Product direction only |
+| "We believe…" or "we think…" | Lowest | Vision statements only |
+
+**Proof point development process:**
+1. Write the claim you want to make
+2. Identify the strongest available proof
+3. If proof is weak, either soften the claim or invest in getting better proof
+4. Never publish a claim without knowing what happens when a skeptic asks "prove it"
+
+---
+
+## 3. Competitive Positioning Maps
+
+### The Two-Axis Map
+
+Choose two dimensions that:
+1. Both matter to your target buyer
+2. Create clear differentiation between you and competitors
+3. You can credibly defend
+
+**Choosing the axes:**
+- Axis 1 should show a dimension where you win and most competitors cluster on the wrong side
+- Axis 2 should show a dimension buyers care about deeply (ease, speed, breadth, price, compliance, etc.)
+
+**What to avoid:**
+- "Quality" vs. "Price" — too generic, every company claims the top-left
+- Dimensions your competitors can match in one release cycle
+- Dimensions that only your product team understands, not buyers
+
+### Competitive Analysis Template
+
+For each major competitor:
+
+**Company:** _______________
+
+| Dimension | What They Claim | What Customers Actually Experience | Gap |
+|-----------|----------------|-----------------------------------|-----|
+| Positioning | | | |
+| Primary differentiator | | | |
+| Pricing | | | |
+| Ideal customer | | | |
+| Weakness (win/loss data) | | | |
+| What they say about you | | | |
+
+**Sources for competitive intelligence:**
+- Win/loss interviews (primary source — nothing beats this)
+- G2/Capterra reviews (what customers say publicly)
+- Glassdoor (tells you about internal culture and focus)
+- LinkedIn job postings (what they're building next)
+- Their pricing page changes (what they're competing on)
+- Conference talks from their product and sales leaders
+
+### Battlecard Format
+
+One page per competitor. Used by sales, not marketing.
+
+```
+COMPETING AGAINST: [Competitor Name]
+
+WHY CUSTOMERS CONSIDER THEM:
+(2-3 bullets — be honest about their appeal)
+
+OUR DIFFERENTIATION:
+(2-3 bullets — factual, not marketing language)
+
+THE LANDMINE QUESTION:
+(One question that exposes their weakness. The answer should make the buyer uncomfortable choosing them.)
+Example: "How long does your typical implementation take? And what's your SLA if it runs over?"
+
+OUR PROOF POINTS IN THIS COMPARISON:
+- [Customer name] switched from [competitor] after [specific reason], saw [specific result]
+- [Data point that directly contradicts competitor's primary claim]
+
+THEIR LIKELY COUNTER-MOVES:
+(What will they say about us? How do we respond?)
+
+WHEN TO WALK AWAY:
+(If the prospect values X more than Y, we are not the right fit — say so)
+```
+
+---
+
+## 4. Brand Voice Development
+
+### What Brand Voice Is (and Isn't)
+
+**Brand voice is NOT:**
+- A list of adjectives ("we are professional, innovative, and customer-focused")
+- The tone you use in formal communications
+- The font and color palette (that's visual identity)
+
+**Brand voice IS:**
+- How the company sounds across every written touchpoint
+- Consistent enough to be recognizable, flexible enough to be human
+- Grounded in what your best customers actually value
+
+### The Voice Attribute Framework
+
+Define 3-4 voice attributes. For each:
+1. **What it means** (in one sentence)
+2. **What it sounds like** (one example)
+3. **What it doesn't mean** (the common mistake that goes wrong)
+
+**Example:**
+
+| Attribute | Means | Sounds like | Doesn't mean |
+|-----------|-------|------------|--------------|
+| Direct | We say what we mean without hedging | "Your compliance review takes 3 weeks. It shouldn't." | Blunt, rude, or dismissive |
+| Expert | We speak from depth, not from trend | "Here's why most security gates fail at scale, and what actually works." | Jargon-heavy or condescending |
+| Honest | We acknowledge what we don't do | "We're not the best fit if you need a one-size-fits-all platform." | Self-deprecating or uncertain |
+| Human | Real people write for real people | "Deploying on a Friday? Here's what we'd check first." | Casual, unprofessional |
+
+### Voice Consistency Testing
+
+Take a random sample of 10 recent pieces of content:
+- Website homepage and pricing page
+- 3 blog posts from different authors
+- 5 outbound emails from sales
+- 3 social posts
+- 1 press release
+
+Score each on: Does this sound like us? (1-5)
+
+Average < 3: You have a brand voice problem. The cause is usually no documented guidelines, or guidelines that exist but aren't enforced.
+
+### Voice in Different Contexts
+
+The attribute stays the same. The tone adjusts.
+
+| Context | Tone adjustment | Example of "Direct" |
+|---------|----------------|---------------------|
+| Homepage | Confident | "Compliance reviews don't have to slow you down." |
+| Technical docs | Precise | "Set the policy threshold to 0.95 to enforce mandatory approval." |
+| Error messages | Helpful | "That didn't work. Here's the most common reason why, and how to fix it." |
+| Support | Empathetic | "That's frustrating. Here's what happened and what we're doing about it." |
+| Sales outreach | Respectful | "Most teams in your space have this problem. Worth 20 minutes to explore?" |
+
+---
+
+## 5. Rebrand Decision Framework
+
+### When Rebrands Succeed vs. Fail
+
+**Successful rebrands:**
+- Driven by a genuine strategic shift (new category, new ICP, new market)
+- Have internal alignment before external launch
+- Are accompanied by product and messaging changes — not just visual
+- Have a 6-12 month transition plan for existing customers
+
+**Failed rebrands:**
+- Driven by internal boredom with the old brand
+- Executed as a "refresh" without repositioning the value proposition
+- Lack leadership conviction (executives still describe the company in the old terms)
+- Launch with a new logo but same product, same messaging, same ICP
+
+### The Rebrand Decision Matrix
+
+Answer each question. More "yes" answers = more likely rebrand is warranted.
+
+| Question | Yes | No |
+|----------|-----|-----|
+| Has our ICP changed significantly in the last 18 months? | Rebrand | Stay |
+| Are we entering a new market where the current brand creates friction? | Rebrand | Stay |
+| Does the brand name have negative associations in the market? | Rebrand | Stay |
+| Has an acquisition changed our core identity? | Rebrand | Stay |
+| Is the current brand actively hurting sales conversations? (evidence required) | Rebrand | Stay |
+| Are we bored with the brand? | Stay | — |
+| Did leadership change? | Stay | — |
+| Are competitors rebranding? | Stay | — |
+
+Score: 3+ "Rebrand" answers with evidence = worth a serious evaluation.
+
+### Rebrand Risk Assessment
+
+**Name change** is the highest-risk rebrand element. Before committing:
+- Legal: trademark availability in all target markets
+- SEO: 18-24 months to recover domain authority after a domain change
+- Customer: existing customers need to update all integrations, contracts, documentation
+- Analyst: re-education of Gartner, Forrester, G2 category definitions
+- Employee: company identity shift is a culture event, not just an HR task
+
+**Minimum viable rebrand (lower risk):**
+1. New positioning and messaging (always worth doing if positioning is wrong)
+2. Visual identity refresh (keep the name, update the look)
+3. Tagline change (the cheapest, lowest-risk brand change)
+
+**Full rebrand (high risk, sometimes necessary):**
+1. New company name and domain
+2. New visual identity
+3. New positioning and messaging
+4. New category narrative
+
+### Rebrand Execution Checklist
+
+**Pre-launch (90 days):**
+- [ ] Finalize positioning before finalizing design (in that order)
+- [ ] Legal trademark clearance in all target markets
+- [ ] Domain secured (with redirects planned)
+- [ ] Internal alignment: every leader can describe the new positioning in one sentence
+- [ ] Customer comms plan (existing customers, especially enterprise, need advance notice)
+- [ ] Analyst briefings scheduled (Gartner, Forrester — brief them before launch)
+- [ ] PR plan finalized
+
+**Launch (day 1):**
+- [ ] Website flipped
+- [ ] Social profiles updated
+- [ ] Email signatures updated company-wide
+- [ ] Sales deck updated
+- [ ] Press release published
+- [ ] Existing customers notified (email from CEO or CMO, not marketing automation)
+
+**Post-launch (90 days):**
+- [ ] SEO monitoring (watch for ranking drops on key terms)
+- [ ] Win rate monitoring (did conversion change?)
+- [ ] Employee feedback (are they using the new messaging correctly?)
+- [ ] Partner/channel update (resellers, integrations, directories)
+- [ ] Analyst follow-up (did they update their reports?)
+
+---
+
+## Quick Reference: Brand Positioning Diagnostic
+
+Use this as an audit against your current positioning:
+
+| Check | Pass | Fail |
+|-------|------|------|
+| Can every sales rep state the positioning in one sentence without looking it up? | ✓ | Positioning isn't working |
+| Is the ICP specific enough to disqualify companies? | ✓ | ICP is too broad |
+| Does the homepage lead with customer outcome, not product features? | ✓ | Copy needs rewrite |
+| Can you name 3 companies you're NOT a good fit for? | ✓ | Positioning is unfocused |
+| Do win/loss interviews confirm the stated differentiator? | ✓ | Differentiator is assumed, not proven |
+| Is the category name used by analysts or industry media? | ✓ | Category design needed |
+| Does every piece of content trace back to a VP from the hierarchy? | ✓ | Messaging drift — need guidelines |
diff --git a/skills/c-level-advisor/cmo-advisor/references/growth_frameworks.md b/skills/c-level-advisor/cmo-advisor/references/growth_frameworks.md
new file mode 100644
index 00000000..31ba0603
--- /dev/null
+++ b/skills/c-level-advisor/cmo-advisor/references/growth_frameworks.md
@@ -0,0 +1,456 @@
+# Growth Frameworks Reference
+
+Playbooks for PLG, sales-led, community-led, and hybrid growth models. Includes growth loops, funnel design, and guidance on when and how to switch models.
+
+---
+
+## 1. Product-Led Growth (PLG) Playbook
+
+### What PLG Actually Is
+
+PLG means the product is the primary distribution mechanism. Not "we have a free trial." Not "our product is self-serve." PLG means the product creates acquisition, retention, and expansion — and does so at a scale and cost no sales team can match.
+
+**The minimum requirements for PLG to work:**
+1. **Fast time-to-value:** Users must get a meaningful outcome within one session (ideally < 30 minutes)
+2. **Low friction to start:** No sales call, no implementation project, no credit card required (for top of funnel)
+3. **Built-in virality or network effects:** Usage creates exposure or value that draws in other users
+4. **Self-serve monetization or expansion path:** Freemium → paid, or individual → team → company
+
+If any of these is missing, you don't have PLG — you have a website with a free trial.
+
+### PLG Funnel: The Four Stages
+
+**Stage 1: Acquisition**
+The user discovers and signs up for the product without talking to sales.
+
+Key channels:
+- Organic search (SEO targeting jobs-to-be-done searches)
+- Product hunt launches
+- Referral and invite loops (users share the product with colleagues)
+- Developer communities and open-source contributions
+
+Metric: Visitor-to-signup rate
+
+Benchmark: 2-8% for B2B SaaS (varies heavily by product complexity)
+
+**Stage 2: Activation**
+The user reaches the "aha moment" — the point where the product delivers its core value for the first time.
+
+Finding the aha moment:
+- Look at the behaviors that differentiate users who stay from users who churn in the first 30 days
+- The aha moment is not creating an account. It's completing the first outcome.
+- For Slack: sending a message in a real channel
+- For Dropbox: adding a file from a second device
+- For HubSpot: publishing a form that captures a real lead
+
+Metric: Activation rate (% of signups who complete the aha moment action within 7 days)
+
+Benchmark: 25-40% is strong. < 15% means the onboarding is broken.
+
+**Stage 3: Retention**
+Users return to the product and build habitual use.
+
+Retention analysis:
+- Cohort retention curves (by signup week/month)
+- Day 1, Day 7, Day 30, Day 90 retention rates
+- Feature adoption by retained vs. churned users (which features predict retention?)
+
+Metric: D30 retention rate (% of users still active 30 days after signup)
+
+Benchmark: > 40% D30 retention is strong for B2B products
+
+**Stage 4: Revenue**
+Self-serve conversion from free to paid, or expansion from individual to team.
+
+PQL (Product-Qualified Lead) signals:
+- Reached a usage limit (invites, storage, seats)
+- Used a premium feature in trial mode
+- Team size on the account reached a threshold
+- High-frequency usage above a defined threshold
+
+Metric: PQL conversion rate (% of PQLs who convert to paid within 30 days)
+
+Benchmark: 15-30% for well-designed PLG products
+
+### PLG Expansion Model
+
+PLG growth compounds through account expansion:
+
+```
+Individual user discovers product
+ → Gets value, invites teammates
+ → Team adopts product
+ → Becomes department-wide
+ → Finance/IT gets involved
+ → Enterprise contract
+```
+
+This is "bottom-up" enterprise: individual adoption precedes company-wide purchase. It's also the most defensible moat — when every engineer in the company uses your product individually, procurement cancellation is very hard.
+
+**Expansion levers:**
+- Seat-based pricing (more users = more revenue, aligned with value)
+- Usage-based pricing (more usage = more value = more revenue)
+- Feature gating (team/enterprise features visible but gated, creating pull to upgrade)
+- Admin discovery (usage reports surface to managers who didn't know they had a product champion)
+
+### PLG Diagnostic
+
+| Question | Healthy | Unhealthy |
+|----------|---------|-----------|
+| Time-to-value | < 30 minutes | > 2 hours |
+| Activation rate | > 30% | < 15% |
+| D30 retention | > 40% | < 20% |
+| PQL conversion | > 15% | < 5% |
+| NPS from self-serve users | > 40 | < 20 |
+| Viral coefficient | > 0.3 | < 0.1 |
+
+### PLG Team Structure
+
+```
+Head of Growth (often VP Product or VP Marketing)
+├── Growth PM (owns activation and retention loops in product)
+├── Growth Engineer (2-3 engineers dedicated to growth experiments)
+├── Data Analyst (experimentation, funnel analysis, cohort reports)
+└── Growth Marketer (acquisition, SEO, referral programs)
+```
+
+The growth team sits between product and marketing. This is intentional — they own the product loops that drive acquisition and retention.
+
+---
+
+## 2. Sales-Led Growth (SLG) Model
+
+### The SLG System
+
+In SLG, marketing's job is to fill the sales pipeline. Sales converts it. The system only works if marketing and sales agree on definitions, SLAs, and shared metrics.
+
+**The SLG funnel:**
+
+```
+Awareness (Impressions, reach, brand search)
+ ↓
+Lead (Name + contact info captured)
+ ↓
+MQL — Marketing Qualified Lead (meets ICP criteria, intent signal detected)
+ ↓ [Marketing → Sales handoff]
+SAL — Sales Accepted Lead (sales reviews and accepts the lead)
+ ↓
+SQL — Sales Qualified Lead (sales confirms budget, authority, need, timeline)
+ ↓
+Opportunity (Formal deal in pipeline, has a close date)
+ ↓
+Closed-Won
+```
+
+**The MQL definition problem:**
+Most marketing-sales friction traces to an unclear MQL definition. The MQL should be:
+- ICP-matched (company size, industry, role)
+- Intent-signaled (visited pricing page, attended webinar, downloaded high-intent content)
+- Not just email address + "subscribed to newsletter"
+
+**A concrete MQL definition:**
+> Company 50-500 employees, B2B SaaS, role is VP Engineering or CTO or CISO, AND has performed 2+ of: attended webinar, visited pricing page, requested demo, downloaded security report, attended event.
+
+This definition makes the MQL useful. If you can't score it in your CRM without human judgment, it's not a definition — it's a guideline.
+
+### SLG Conversion Rate Benchmarks
+
+| Stage | Average B2B SaaS | Top Quartile |
+|-------|-----------------|--------------|
+| Lead → MQL | 5-15% | > 20% |
+| MQL → SAL | 50-70% | > 75% |
+| SAL → SQL | 30-50% | > 60% |
+| SQL → Opportunity | 60-80% | > 85% |
+| Opportunity → Closed-Won | 20-30% | > 40% |
+
+**End-to-end:** Lead → Closed-Won: 1-5% (wide range by ACV and ICP quality)
+
+### Pipeline Coverage Mechanics
+
+A healthy SLG pipeline has 3-4x coverage against quota.
+
+If a sales rep has a $500K quarterly quota:
+- They need $1.5M-$2M in active pipeline
+- Pipeline must be distributed across stages (not all "prospecting")
+- Stage distribution benchmark: 30% early, 40% mid, 30% late
+
+Insufficient coverage (< 3x) is a lagging indicator of a miss — by the time coverage is low, it's too late to recover in the same quarter. Coverage should be tracked weekly.
+
+### SLG Demand Generation Channels
+
+**High-intent channels (bottom of funnel):**
+- Paid search on buying-intent keywords (e.g., "[competitor] alternative", "best [category] software")
+- Review site presence (G2, Capterra) — buyers use these before vendor websites
+- Outbound SDR targeting specific accounts (ABM)
+
+**Medium-intent channels (middle of funnel):**
+- Webinars and virtual events (capture active learners)
+- Gated content (guides, benchmarks, templates — ICP-specific)
+- Retargeting to website visitors
+
+**Awareness channels (top of funnel):**
+- Content and SEO (captures people learning about the problem)
+- Podcast sponsorships, industry media
+- Conference sponsorship and speaking
+- Paid social (LinkedIn for B2B)
+
+### ABM (Account-Based Marketing) in SLG
+
+ABM flips the funnel: instead of generating leads and filtering for good ones, you start with target accounts and run coordinated campaigns against them.
+
+**Tiers:**
+- **Tier 1 (1:1):** 5-20 strategic accounts, fully customized campaigns, dedicated SDR+AE pairs, executive outreach
+- **Tier 2 (1:few):** 50-200 accounts, programmatic personalization, SDR sequences, targeted events
+- **Tier 3 (1:many):** 500+ accounts, standard campaigns with light personalization
+
+ABM requires tight sales/marketing alignment. If sales doesn't work the accounts marketing targets, ABM produces zero results.
+
+---
+
+## 3. Community-Led Growth (CLG)
+
+### The CLG Thesis
+
+Community-led growth works when:
+1. Your buyers want to learn from peers, not vendors
+2. There's a strong practitioner identity (developers, data teams, security, FinOps)
+3. Your category is complex enough that buyers need education before purchasing
+4. You can commit to building genuine community, not a marketing channel in disguise
+
+**The fundamental rule of CLG:** The community must deliver value to members whether or not they ever buy your product. If the only purpose of the community is to sell to members, the community will die.
+
+### CLG Stages
+
+**Stage 1: Find the community**
+The community often exists before you build it. Find where your practitioners already gather:
+- Slack groups, Discord servers
+- Subreddits and LinkedIn groups
+- Conference hallways
+- Open-source repositories
+
+Before building, participate. Earn trust. Understand the conversations.
+
+**Stage 2: Become the knowledge hub**
+Establish your company as the best source of information on the category problem:
+- Publish the benchmark study everyone references
+- Host the conference that defines the industry
+- Create the certification practitioners want on their resume
+- Open-source the tools the community needs
+
+**Stage 3: Build the platform**
+Create a dedicated community space (Slack, Discord, forum):
+- Community must be practitioner-first, not vendor-first
+- Community managers who genuinely care about member value
+- Content from members, not just from your company
+- Events that build member relationships, not just product demos
+
+**Stage 4: Convert community to customers**
+Community members who become customers do so because they trust you, not because you sold them. Conversion paths:
+- Community members see peer success with your product
+- Product-qualified signals from community members who trial the product
+- Direct outreach from sales to active community members (with permission and context)
+- Enterprise deals from companies whose employees are active in the community
+
+### CLG Metrics
+
+| Metric | Definition | Health Signal |
+|--------|-----------|--------------|
+| Monthly active members | Members who post, comment, or engage | > 15% of total members |
+| Community-sourced pipeline | $ pipeline where community was first touch | Track and trend |
+| Community-influenced pipeline | $ pipeline with any community touchpoint | > 30% of total pipeline |
+| NPS of community members vs. non-members | Loyalty difference | Community members should score 20+ pts higher |
+| Member-generated content % | % of content posted by non-employees | > 60% is healthy community |
+| Time from community join to product trial | | Shortens as community matures |
+
+### CLG Anti-Patterns
+
+- **Community as a newsletter:** If members can't interact with each other, it's not a community — it's a list.
+- **Product launches in the community:** Nothing kills community trust faster than using it for sales announcements.
+- **Community without a community manager:** Communities left to run themselves become ghost towns or become toxic.
+- **Measuring community by member count:** Ghost members are noise. Active engagement is signal.
+
+---
+
+## 4. Hybrid Growth Models
+
+### PLG + SLG ("Product-Led Sales" or PLS)
+
+The most common hybrid at growth stage. PLG handles SMB self-serve; sales closes enterprise.
+
+**The PQL-to-sales handoff:**
+
+Define the triggers that move a product-qualified lead to a sales-assisted motion:
+- Company has > X users (e.g., 10+ users on a team account)
+- Usage exceeds Y threshold in 30 days
+- Account is a named target in the ABM list
+- User explicitly requested a demo or upgrade assistance
+
+**The risk:** Sales team ignores PLG pipeline because deal size is smaller. Fix: separate quotas and commission structures for self-serve expansion vs. new enterprise logos.
+
+**The opportunity:** PLG creates pre-qualified champions inside accounts. Sales doesn't have to create interest — they convert it. Win rates in PLS motions are typically 30-50% higher than cold outbound.
+
+### SLG + CLG
+
+Community builds brand and generates inbound pipeline for sales.
+
+This hybrid works when:
+- Sales cycles are long (6-18 months)
+- Buyers do extensive research before engaging with vendors
+- The community validates your credibility before sales conversations begin
+
+**The integration:**
+- Community team feeds content insights to demand gen
+- Event attendees become high-priority SDR sequences
+- Active community members get dedicated AE outreach with community context
+- Win/loss analysis includes community touchpoints
+
+### PLG + CLG
+
+The developer/open-source hybrid. PLG handles product adoption; community handles advocacy and content.
+
+**Examples:** HashiCorp (Terraform community + enterprise sales), Elastic (open-source + community + commercial), Tailscale (developer community + self-serve + enterprise).
+
+**How it compounds:**
+```
+Community member learns from community content
+ → Discovers open-source or free tier
+ → Gets value in first session
+ → Shares experience in community
+ → New members discover product through community content
+```
+
+---
+
+## 5. Growth Loops vs. Funnels
+
+### The Difference
+
+**A funnel** is linear. It requires constant input at the top to produce output at the bottom. If you stop feeding it, it stops producing.
+
+**A growth loop** is cyclical. Output from one stage becomes input to the next. The system compounds.
+
+### Common Growth Loops
+
+**Viral loop:**
+```
+User gets value → Invites colleague → Colleague signs up →
+Colleague invites another colleague → ...
+```
+Viral coefficient (K) = (Average invites per user) × (Conversion rate of invites)
+- K > 1: Exponential growth (rare)
+- K 0.5-1: Strong viral assist
+- K < 0.3: Viral is not a meaningful growth driver
+
+**Content SEO loop:**
+```
+Publish content on [topic] → Ranks in search →
+Drives signups → Users share content → Builds backlinks →
+Better rankings → More content is possible
+```
+This loop takes 12-24 months to activate but is extraordinarily defensible once running.
+
+**UGC (User-Generated Content) loop:**
+```
+Users share their work publicly (templates, analyses, portfolios) →
+Others discover the work → They find the product →
+They create and share their own work → ...
+```
+Figma, Notion, Airtable, Canva — all run this loop.
+
+**Data network effect loop:**
+```
+More users → More data → Better product →
+More users attracted → ...
+```
+LinkedIn, Waze, Duolingo — accuracy or relevance improves as the user base grows.
+
+**Integration loop:**
+```
+Product integrates with X → X's users discover your product →
+More integrations possible → More discovery surfaces → ...
+```
+Zapier, Slack apps, Salesforce AppExchange — being in the ecosystem creates distribution.
+
+### Building a Growth Loop
+
+**Step 1: Map the current funnel**
+Where do customers come from? What are the conversion steps?
+
+**Step 2: Find the output**
+What does a successful customer produce?
+- Invite emails
+- Shared content
+- Public work visible to others
+- Reviews or testimonials
+
+**Step 3: Design the loop**
+How does that output become tomorrow's input to acquisition?
+- If they share → is there a landing page that captures the new visitor?
+- If they invite → is the invite experience friction-free?
+- If they create content → does it rank in search or appear in relevant communities?
+
+**Step 4: Measure loop velocity**
+For each loop, measure:
+- Cycle time: How long does one full cycle take?
+- Conversion at each step: Where does the loop break down?
+- Loop coefficient: How many new users does one existing user generate?
+
+---
+
+## 6. When to Switch Growth Models
+
+### The Warning Signs
+
+**PLG-to-SLG triggers:**
+- Enterprise accounts are signing up via PLG but aren't expanding without human intervention
+- Average deal sizes in enterprise are 10-20x SMB, and you're leaving revenue on the table
+- Product adoption in enterprise requires configuration or integration that needs support
+- PLG accounts churn at higher rates than sales-assisted accounts
+
+**SLG-to-PLG/PLS triggers:**
+- CAC is increasing year-over-year as competition for sales talent intensifies
+- Smaller competitors are winning deals with self-serve
+- Customers are asking "can I just try this myself?"
+- ACV is declining as the market matures and products commoditize
+- Sales team efficiency (revenue per sales rep) is declining
+
+**Adding CLG to existing motion:**
+- Sales cycles are long and trust is the primary barrier
+- SEO and content are generating traffic but low conversion (awareness without trust)
+- Competitors are building community and you're not present
+- Customer success teams report that customers who participate in user groups retain better
+
+### The Transition Playbook
+
+**Phase 1: Prove it before scaling (months 1-6)**
+Don't restructure the team to support the new model before proving it works.
+- Run a pilot: 3-5 SDRs testing PLG signals as outreach triggers (for PLG → PLS)
+- Or: Launch a beta community with 100 core customers (for adding CLG)
+- Measure the metrics of the new model, compare to current model
+
+**Phase 2: Parallel running (months 6-12)**
+Run both models simultaneously. Don't kill the current model while building the new one.
+- Set clear boundaries on which accounts go to which motion
+- Build dedicated teams for each model (don't ask the same people to do both)
+- Define success metrics for the new model independently
+
+**Phase 3: Rebalance (months 12-18)**
+Once the new model proves its unit economics:
+- Shift headcount and budget to the more efficient model
+- Keep the old model for the segments where it still works
+- Document what the new model requires to sustain itself
+
+**The anti-pattern:** Announcing a model shift without proof, restructuring the team, and discovering after 12 months that the new model doesn't work. By then, the old model's momentum is gone and you've burned a year.
+
+### Growth Model Maturity Matrix
+
+| Dimension | PLG | SLG | CLG |
+|-----------|-----|-----|-----|
+| Time to first results | 3-6 months | 1-3 months | 12-18 months |
+| Requires up-front product investment | High | Low | Medium |
+| Scales without linear headcount | Yes | No | Yes |
+| Predictable pipeline | Low (early) | High | Low (early) |
+| CAC trend over time | Decreases | Flat/increases | Decreases |
+| Works for ACV > $50K | Only with SLG assist | Yes | Yes |
+| Works for ACV < $5K | Yes | No | Only with PLG |
+| Defensibility once established | High | Low | Very high |
diff --git a/skills/c-level-advisor/cmo-advisor/references/marketing_org.md b/skills/c-level-advisor/cmo-advisor/references/marketing_org.md
new file mode 100644
index 00000000..7cc44d9f
--- /dev/null
+++ b/skills/c-level-advisor/cmo-advisor/references/marketing_org.md
@@ -0,0 +1,281 @@
+# Marketing Org Reference
+
+Team structure, hiring sequence, agency decisions, marketing ops, and cross-functional alignment — by company stage.
+
+---
+
+## 1. Marketing Team Structure by Stage
+
+### Pre-Seed / Seed (< $1M ARR, 1–10 people)
+
+Don't hire a marketing team yet. The founders are the marketing team.
+
+What to do instead:
+- Founders write content, do sales calls, go to events
+- The goal is learning the ICP and finding the channel that works, not scaling anything
+- One contractor or agency for specific output (design, SEO audit) is fine
+
+First marketing hire trigger: You have a repeatable sales motion and need to scale it.
+
+---
+
+### Series A ($1M–$5M ARR, 10–30 people)
+
+**Org:**
+```
+Founding Marketer (Head of Marketing or VP Marketing)
+```
+
+One person. Generalist. Capable of writing, running ads, setting up HubSpot, producing a report. Their job is to find what works.
+
+**What they own:**
+- Content and SEO foundation
+- Paid channel experiments
+- Sales enablement basics (1-pager, deck, email sequences)
+- Event presence (1-2 conferences)
+- Marketing attribution setup (get this right early)
+
+**What they don't own yet:**
+- Brand redesign
+- Analyst relations
+- Partner marketing
+- Field marketing team
+
+**CMO vs. VP Marketing at this stage:** VP Marketing. An experienced operator who can build and execute. A CMO's strategic value isn't fully leveraged until there's a team to lead and a budget to allocate.
+
+---
+
+### Series B ($5M–$20M ARR, 30–80 people)
+
+**PLG-first org:**
+```
+VP Marketing
+├── Growth Marketing (acquisition loops, activation, PLG analytics)
+├── Product Marketing (positioning, launch, sales enablement)
+└── Content & SEO (organic engine)
+```
+
+**SLG-first org:**
+```
+VP Marketing
+├── Demand Generation (pipeline creation, paid, digital)
+├── Product Marketing (positioning, competitive intel, enablement)
+├── Field Marketing (events, regional, ABM)
+└── Marketing Operations (CRM, attribution, reporting)
+```
+
+**Community-led org:**
+```
+VP Marketing
+├── Community & Developer Relations
+├── Content & SEO
+└── Product Marketing
+```
+
+**At this stage:** Marketing ops becomes critical. Without it, attribution is guesswork and the sales team blames marketing for bad leads.
+
+---
+
+### Series C ($20M–$75M ARR, 80–200 people)
+
+```
+CMO
+├── Demand Generation
+│ ├── Paid Media
+│ ├── SEO & Content
+│ └── Marketing Operations
+├── Product Marketing
+│ ├── Core PMMs (by product line or segment)
+│ └── Competitive Intelligence
+├── Field Marketing
+│ ├── Events
+│ └── Regional / ABM
+└── Brand & Communications
+ ├── Brand Design
+ └── PR / Analyst Relations
+```
+
+**At this stage:**
+- The CMO is a board-level communicator, not a campaign manager
+- Each function has a dedicated leader (director or VP level)
+- Marketing ops owns the attribution model and reports to CMO directly
+- Analyst relations becomes important (Gartner, Forrester, G2 category positioning)
+
+---
+
+### Growth Stage ($75M+ ARR)
+
+Marketing becomes a portfolio of specialized functions. Each major channel has a team. Brand is a serious investment. Analyst relations is a dedicated role. International marketing teams form.
+
+The CMO's job shifts from building the machine to:
+- Setting marketing strategy across a complex portfolio
+- Representing marketing at the board level
+- Owning brand and category leadership
+- Cross-functional leadership with CRO, CPO, CEO
+
+---
+
+## 2. Hiring Sequence
+
+### Who to Hire First
+
+**The generalist content + demand gen marketer.**
+
+Must-haves:
+- Can write (blog posts, emails, landing pages — not just briefs)
+- Can run paid campaigns (Google, LinkedIn — not just "I've managed agencies")
+- Can operate a marketing automation platform (HubSpot, Marketo)
+- Comfortable with data (can build a funnel report without asking an analyst)
+
+This person builds the foundation. They're not a specialist yet — they're testing channels and building the process.
+
+Avoid: Hiring a brand designer first. Or a community manager. Or a social media manager. These are specialties that compound on a foundation that doesn't exist yet.
+
+### Who to Hire Second
+
+**A specialist in the channel that's working.**
+
+If organic search is your top lead source → hire an SEO/content lead.
+If events are driving pipeline → hire a field marketer.
+If outbound is working → hire an SDR manager or demand gen specialist.
+
+Don't hire a generalist #2. By now you know what's working. Depth beats breadth.
+
+### Who to Hire Third
+
+**Product marketing.**
+
+Why third and not first? Because PMM output (positioning, sales enablement, launch) is most valuable when there's an audience to position to and a sales team to enable. Before that, the founding marketer does "good enough" PMM work.
+
+PMM hire profile: Has done positioning work before, has run a product launch, has built sales decks that sales actually uses, comfortable with win/loss analysis.
+
+PMM:PM ratio benchmark: 1 PMM per 2–3 PMs. If you have 6 PMs and 1 PMM, you have a messaging and enablement problem.
+
+### Who to Hire Fourth
+
+**Marketing operations.**
+
+This is consistently hired too late. By the time most companies hire marketing ops, attribution is broken, leads are being lost in handoffs, and the CRM data is unreliable. Hire marketing ops before you think you need it.
+
+Marketing ops profile: HubSpot/Marketo certified, SQL capable, understands multi-touch attribution, has integrated CRM + sales engagement tools before.
+
+### Hiring Decision Triggers
+
+| Hire | Trigger |
+|------|---------|
+| Generalist marketer #1 | Sales motion is repeatable, need to scale lead generation |
+| Specialist #2 | One channel is clearly outperforming — double down |
+| Product marketer | Sales team is losing deals to positioning confusion or competitor gaps |
+| Marketing ops | Running 3+ campaigns simultaneously with manual tracking |
+| Field marketer | Events are in the strategy and attendance > 2 conferences/quarter |
+| Head of Marketing / VP | Team is 3+ people and needs an org owner |
+| CMO | Company is Series B/C and marketing needs board-level representation |
+
+---
+
+## 3. Agency vs. In-House
+
+### Framework
+
+Keep in-house what compounds. Outsource what's episodic or specialized.
+
+| Function | Agency | In-House | Notes |
+|----------|--------|----------|-------|
+| Brand design | Early stage | Series B+ | Agency fine until redesigns become frequent |
+| Paid media | < $50K/month spend | > $50K/month | Agency margin eats returns at scale |
+| SEO strategy | Audit only | Ongoing execution | Strategy once, execution continuously |
+| Content production | Overflow only | Core writers | Your voice must be yours |
+| PR / comms | Almost always | $100M+ companies | Specialists required for media relationships |
+| Marketing ops / CRM | Never | Always | This is your data infrastructure |
+| Analyst relations | Initial strategy | Ongoing | Relationship-based — needs dedicated owner |
+| Video / creative production | Always | Rarely | Episodic, specialized equipment |
+
+### Agency Red Flags
+
+- They want to own your ad accounts. (Always keep ownership. No exceptions.)
+- SLA is "5 business days for creative requests." For a performance channel, that's too slow.
+- Reporting is impressions, CPM, and "brand lift." Where's the pipeline?
+- They can't tell you your CAC from their channel.
+- They won't share the actual data — only their dashboard.
+- Your account manager changes every 6 months.
+
+### Agency Evaluation Criteria
+
+1. **Proof of work in your category** — ask for 3 case studies with actual CAC and pipeline data
+2. **Who actually does the work** — senior pitch team ≠ junior execution team
+3. **Account ownership** — all accounts, pixels, analytics must be in your name
+4. **Reporting cadence** — weekly data, monthly strategy, quarterly business review
+5. **Exit terms** — how do you offboard without losing your data, accounts, and history?
+
+---
+
+## 4. Marketing Ops and Tech Stack
+
+### The Minimum Viable Stack
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| CRM | HubSpot / Salesforce | Contact database, pipeline, source of truth |
+| Marketing automation | HubSpot / Marketo / ActiveCampaign | Email, nurture, lead scoring |
+| Analytics | Google Analytics 4 + Segment | Traffic, behavior, event tracking |
+| Attribution | HubSpot / Attributer.io / Dreamdata | Multi-touch pipeline attribution |
+| Paid | Google Ads + LinkedIn Ads | Performance channels |
+| SEO | Ahrefs / Semrush | Keyword research, rank tracking |
+| Chat/conversion | Intercom / Drift | In-product + website conversion |
+
+**The integration that breaks most:** CRM ↔ Marketing automation ↔ Sales engagement. When these aren't synced properly, leads are lost, attribution is wrong, and marketing and sales fight about pipeline. Fix this first.
+
+### Marketing Ops Ownership
+
+Marketing ops must own:
+- CRM data quality (field standardization, deduplication, routing)
+- Lead scoring model (and quarterly review against conversion data)
+- Attribution model (with documented assumptions)
+- Campaign tracking (UTM governance — no UTM = no attribution)
+- Tech stack evaluation and contracts
+
+Marketing ops must NOT own:
+- Strategy (they enable it, not set it)
+- Content production
+- Campaign creative
+
+---
+
+## 5. Cross-Functional Alignment
+
+### Marketing + Sales
+
+The most important cross-functional relationship in a SLG company. Where it breaks:
+
+| Problem | Root Cause | Fix |
+|---------|-----------|-----|
+| "Marketing sends us bad leads" | MQL definition is unclear or wrong | Define MQL jointly, score against conversion data |
+| "Sales doesn't follow up on leads" | No SLA, no consequence | Define SLA (e.g., 24-hour response), track in CRM |
+| "Marketing doesn't understand what customers care about" | No win/loss sharing | Weekly call: sales shares 3 deal insights, marketing shares 3 content results |
+| "We don't know what's working" | Attribution is broken | Marketing ops fixes attribution before next budget cycle |
+
+**The SLA agreement (document this):**
+- Marketing commits: X MQLs/week meeting defined criteria, 48-hour SLA from form fill to SDR outreach
+- Sales commits: All MQLs contacted within 24 hours, disposition logged in CRM within 5 days
+
+### Marketing + Product
+
+Where it breaks and how to fix it:
+
+| Problem | Fix |
+|---------|-----|
+| PMM learns about launches 2 weeks before ship | PMM joins the product planning process at the roadmap stage, not the sprint stage |
+| Feature launches with no messaging | Launch tiers: Tier 1 (major, full launch), Tier 2 (minor, release notes + 1 post), Tier 3 (internal only) |
+| Product doesn't use customer insights from marketing | Monthly session: PMM shares win/loss themes, competitive intel, ICP data |
+| No feedback loop on messaging in-product | PMM owns in-product copy review, not just external comms |
+
+### Marketing + Customer Success
+
+Customer success is marketing's best source of truth:
+
+- **ICP validation:** Which customers are expanding? Which are churning? This refines who you target.
+- **Proof points:** CS-sourced case studies and testimonials outperform vendor-written content 3:1 in conversion.
+- **Messaging test:** If CS is answering the same question 20 times, marketing hasn't explained it clearly enough.
+- **Referral programs:** CS owns the relationship; marketing owns the mechanics. Design them together.
+
+Cadence: Monthly meeting between CMO and VP/Head of CS. Agenda: retention trends, expansion patterns, at-risk customers, NPS themes.
diff --git a/skills/c-level-advisor/cmo-advisor/scripts/growth_model_simulator.py b/skills/c-level-advisor/cmo-advisor/scripts/growth_model_simulator.py
new file mode 100644
index 00000000..59b28bfb
--- /dev/null
+++ b/skills/c-level-advisor/cmo-advisor/scripts/growth_model_simulator.py
@@ -0,0 +1,416 @@
+#!/usr/bin/env python3
+"""
+Growth Model Simulator
+----------------------
+Projects MRR growth across different growth models (PLG, sales-led, community-led,
+hybrid) and shows the impact of channel mix changes on growth trajectory.
+
+Usage:
+ python growth_model_simulator.py
+
+Inputs (edit INPUTS section):
+ - Starting MRR and churn rate
+ - Current channel mix (% of new MRR from each source)
+ - Conversion rates per model
+ - Growth rate assumptions per channel
+
+Outputs:
+ - 12-month MRR projection by growth model
+ - Channel mix impact analysis (what happens if you shift mix)
+ - Break-even months for each model
+ - Side-by-side comparison table
+"""
+
+from __future__ import annotations
+import math
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ChannelSource:
+ name: str
+ pct_of_new_mrr: float # Current share of new MRR (0.0–1.0)
+ monthly_growth_rate: float # How fast this channel grows month-over-month
+ cac: float # CAC in dollars
+ payback_months: float # Months to recover CAC
+
+
+@dataclass
+class GrowthModel:
+ name: str
+ description: str
+ channel_mix: Dict[str, float] # channel name → % of new MRR
+ new_mrr_monthly_base: float # Starting new MRR/month from this model
+ monthly_acceleration: float # Acceleration factor (compounding)
+ avg_ltv_cac: float # Expected LTV:CAC at scale
+ months_to_steady_state: int # Months before model hits its natural growth rate
+ notes: List[str] = field(default_factory=list)
+
+
+@dataclass
+class MonthSnapshot:
+ month: int
+ mrr: float
+ new_mrr: float
+ churned_mrr: float
+ expansion_mrr: float
+ net_new_mrr: float
+ cumulative_cac_spend: float
+
+
+@dataclass
+class ModelProjection:
+ model: GrowthModel
+ snapshots: List[MonthSnapshot]
+ break_even_month: Optional[int] # Month when cumulative revenue > cumulative CAC
+
+
+# ---------------------------------------------------------------------------
+# INPUTS — edit these
+# ---------------------------------------------------------------------------
+
+STARTING_MRR = 85_000 # Current MRR ($)
+MONTHLY_CHURN_RATE = 0.012 # Monthly churn rate (1.2% = ~14% annual)
+EXPANSION_RATE = 0.008 # Monthly expansion MRR as % of existing MRR
+GROSS_MARGIN = 0.75
+SIMULATION_MONTHS = 18
+
+# Channel sources (used to model mix shift scenarios)
+CHANNELS: List[ChannelSource] = [
+ ChannelSource("Organic/SEO", pct_of_new_mrr=0.28, monthly_growth_rate=0.04, cac=1_800, payback_months=9),
+ ChannelSource("PLG Self-Serve", pct_of_new_mrr=0.15, monthly_growth_rate=0.08, cac=900, payback_months=5),
+ ChannelSource("Outbound SDR", pct_of_new_mrr=0.25, monthly_growth_rate=0.02, cac=5_100, payback_months=21),
+ ChannelSource("Paid Search", pct_of_new_mrr=0.15, monthly_growth_rate=0.01, cac=6_200, payback_months=26),
+ ChannelSource("Events/Field", pct_of_new_mrr=0.08, monthly_growth_rate=0.01, cac=9_800, payback_months=41),
+ ChannelSource("Partner/Channel", pct_of_new_mrr=0.09, monthly_growth_rate=0.05, cac=3_400, payback_months=14),
+]
+
+# Growth models to simulate
+GROWTH_MODELS: List[GrowthModel] = [
+ GrowthModel(
+ name="Current Mix",
+ description="Baseline — maintain current channel allocation",
+ channel_mix={"Organic/SEO": 0.28, "PLG Self-Serve": 0.15, "Outbound SDR": 0.25,
+ "Paid Search": 0.15, "Events/Field": 0.08, "Partner/Channel": 0.09},
+ new_mrr_monthly_base=12_000,
+ monthly_acceleration=0.025,
+ avg_ltv_cac=3.2,
+ months_to_steady_state=3,
+ notes=["Baseline. No changes to channel mix."],
+ ),
+ GrowthModel(
+ name="PLG-First",
+ description="Shift budget toward PLG self-serve and organic; reduce paid and outbound",
+ channel_mix={"Organic/SEO": 0.35, "PLG Self-Serve": 0.35, "Outbound SDR": 0.10,
+ "Paid Search": 0.08, "Events/Field": 0.04, "Partner/Channel": 0.08},
+ new_mrr_monthly_base=9_500, # Slower start — PLG takes time to activate
+ monthly_acceleration=0.048, # But compounds faster
+ avg_ltv_cac=5.8,
+ months_to_steady_state=6, # PLG loops take time to build
+ notes=[
+ "Lower new MRR in months 1-6 while PLG loops activate.",
+ "Acceleration compounds strongly after month 6.",
+ "Requires product investment in activation/onboarding.",
+ "Best fit if time-to-value < 30 min and viral coefficient > 0.3.",
+ ],
+ ),
+ GrowthModel(
+ name="Sales-Led Scale",
+ description="Double down on outbound SDR and field; optimize for enterprise ACV",
+ channel_mix={"Organic/SEO": 0.20, "PLG Self-Serve": 0.05, "Outbound SDR": 0.40,
+ "Paid Search": 0.15, "Events/Field": 0.15, "Partner/Channel": 0.05},
+ new_mrr_monthly_base=15_000, # Higher new MRR from enterprise ACV
+ monthly_acceleration=0.018, # Linear growth — headcount-constrained
+ avg_ltv_cac=2.8,
+ months_to_steady_state=2,
+ notes=[
+ "Fastest short-term new MRR if ACV > $30K.",
+ "Growth is linear — adds headcount to add pipeline.",
+ "CAC and payback worsen as SDR market tightens.",
+ "Requires sales capacity increase to sustain.",
+ ],
+ ),
+ GrowthModel(
+ name="Community-Led",
+ description="Invest in community and content; reduce paid; long-term brand play",
+ channel_mix={"Organic/SEO": 0.45, "PLG Self-Serve": 0.15, "Outbound SDR": 0.15,
+ "Paid Search": 0.05, "Events/Field": 0.10, "Partner/Channel": 0.10},
+ new_mrr_monthly_base=7_000, # Slowest start
+ monthly_acceleration=0.038,
+ avg_ltv_cac=4.5,
+ months_to_steady_state=9, # Community takes longest to activate
+ notes=[
+ "Lowest new MRR in months 1-9.",
+ "Community trust drives lower CAC and higher retention at scale.",
+ "Best for categories where buyers seek peer validation.",
+ "Requires dedicated community manager from day one.",
+ ],
+ ),
+ GrowthModel(
+ name="Hybrid PLS",
+ description="PLG self-serve for SMB + sales-assisted for enterprise (Product-Led Sales)",
+ channel_mix={"Organic/SEO": 0.30, "PLG Self-Serve": 0.28, "Outbound SDR": 0.22,
+ "Paid Search": 0.08, "Events/Field": 0.06, "Partner/Channel": 0.06},
+ new_mrr_monthly_base=11_000,
+ monthly_acceleration=0.035,
+ avg_ltv_cac=4.1,
+ months_to_steady_state=4,
+ notes=[
+ "PLG handles SMB; sales closes enterprise with PQL signals.",
+ "Requires clear PQL definition and SDR/PLG handoff process.",
+ "Best if you have a product with both bottom-up and top-down adoption.",
+ ],
+ ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Simulation engine
+# ---------------------------------------------------------------------------
+
+def simulate_model(model: GrowthModel, months: int) -> ModelProjection:
+ snapshots: List[MonthSnapshot] = []
+ mrr = STARTING_MRR
+ cumulative_cac = 0.0
+ cumulative_revenue = 0.0
+ break_even_month = None
+
+ for m in range(1, months + 1):
+ # Ramp up — new_mrr accelerates each month
+ if m <= model.months_to_steady_state:
+ # Ramp phase: linear ramp from 60% to 100% of base
+ ramp_factor = 0.6 + 0.4 * (m / model.months_to_steady_state)
+ else:
+ # Steady state: compound acceleration
+ months_past_ramp = m - model.months_to_steady_state
+ ramp_factor = 1.0 + model.monthly_acceleration * months_past_ramp
+
+ new_mrr = model.new_mrr_monthly_base * ramp_factor
+ churned_mrr = mrr * MONTHLY_CHURN_RATE
+ expansion_mrr = mrr * EXPANSION_RATE
+ net_new_mrr = new_mrr - churned_mrr + expansion_mrr
+ mrr = mrr + net_new_mrr
+
+ # CAC spend approximation: new_mrr / (avg_deal_mrr) * blended_cac
+ # Use weighted CAC from channel mix
+ weighted_cac = _weighted_cac(model.channel_mix)
+ avg_deal_mrr = 1_500 # Assumption: $1,500 average deal MRR
+ deals_this_month = new_mrr / avg_deal_mrr
+ cac_spend = deals_this_month * weighted_cac
+ cumulative_cac += cac_spend
+ cumulative_revenue += mrr * GROSS_MARGIN
+
+ if break_even_month is None and cumulative_revenue >= cumulative_cac:
+ break_even_month = m
+
+ snapshots.append(MonthSnapshot(
+ month=m,
+ mrr=mrr,
+ new_mrr=new_mrr,
+ churned_mrr=churned_mrr,
+ expansion_mrr=expansion_mrr,
+ net_new_mrr=net_new_mrr,
+ cumulative_cac_spend=cumulative_cac,
+ ))
+
+ return ModelProjection(
+ model=model,
+ snapshots=snapshots,
+ break_even_month=break_even_month,
+ )
+
+
+def _weighted_cac(channel_mix: Dict[str, float]) -> float:
+ channel_cac = {ch.name: ch.cac for ch in CHANNELS}
+ total = sum(
+ channel_mix.get(name, 0) * cac
+ for name, cac in channel_cac.items()
+ )
+ weight_sum = sum(channel_mix.values())
+ return total / weight_sum if weight_sum > 0 else 5_000
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt_mrr(n: float) -> str:
+ if n >= 1_000_000:
+ return f"${n/1_000_000:.3f}M"
+ return f"${n/1_000:.1f}K"
+
+
+def fmt_currency(n: float) -> str:
+ if n >= 1_000_000:
+ return f"${n/1_000_000:.2f}M"
+ if n >= 1_000:
+ return f"${n/1_000:.1f}K"
+ return f"${n:.0f}"
+
+
+def print_header(title: str) -> None:
+ width = 78
+ print("\n" + "=" * width)
+ print(f" {title}")
+ print("=" * width)
+
+
+def print_channel_overview() -> None:
+ print_header("Current Channel Mix")
+ print(f" Starting MRR: {fmt_mrr(STARTING_MRR)} | Monthly churn: {MONTHLY_CHURN_RATE:.1%} | Expansion: {EXPANSION_RATE:.1%}/mo")
+ print()
+ print(f" {'Channel':<22} {'% MRR':>7} {'CAC':>8} {'Payback':>9} {'Growth/mo':>10}")
+ print(" " + "-" * 60)
+ for ch in sorted(CHANNELS, key=lambda c: c.pct_of_new_mrr, reverse=True):
+ print(
+ f" {ch.name:<22} {ch.pct_of_new_mrr:>6.0%} "
+ f"{fmt_currency(ch.cac):>8} {ch.payback_months:>7.0f}mo "
+ f"{ch.monthly_growth_rate:>9.1%}"
+ )
+
+
+def print_model_detail(proj: ModelProjection) -> None:
+ model = proj.model
+ print_header(f"Model: {model.name}")
+ print(f" {model.description}")
+ if model.notes:
+ print()
+ for note in model.notes:
+ print(f" • {note}")
+ print()
+
+ # Print monthly snapshot (every 3 months + final)
+ milestones = set(range(3, SIMULATION_MONTHS + 1, 3)) | {SIMULATION_MONTHS}
+ print(f" {'Month':<7} {'MRR':>10} {'New MRR':>9} {'Churned':>9} {'Expand':>8} {'Net New':>9}")
+ print(" " + "-" * 56)
+ for snap in proj.snapshots:
+ if snap.month in milestones:
+ print(
+ f" {snap.month:<7} {fmt_mrr(snap.mrr):>10} "
+ f"{fmt_mrr(snap.new_mrr):>9} {fmt_mrr(snap.churned_mrr):>9} "
+ f"{fmt_mrr(snap.expansion_mrr):>8} {fmt_mrr(snap.net_new_mrr):>9}"
+ )
+
+ final = proj.snapshots[-1]
+ growth_x = final.mrr / STARTING_MRR
+ arr_final = final.mrr * 12
+ weighted_cac = _weighted_cac(model.channel_mix)
+ be = f"Month {proj.break_even_month}" if proj.break_even_month else f"> {SIMULATION_MONTHS}mo"
+
+ print()
+ print(f" Final MRR ({SIMULATION_MONTHS}mo): {fmt_mrr(final.mrr)}")
+ print(f" Final ARR: {fmt_currency(arr_final)}")
+ print(f" Growth multiple: {growth_x:.1f}x from starting MRR")
+ print(f" Weighted blended CAC: {fmt_currency(weighted_cac)}")
+ print(f" Expected LTV:CAC: {model.avg_ltv_cac:.1f}x")
+ print(f" Months to steady state:{model.months_to_steady_state}")
+ print(f" CAC break-even: {be}")
+
+
+def print_comparison_table(projections: List[ModelProjection]) -> None:
+ print_header(f"Growth Model Comparison — Month {SIMULATION_MONTHS} Outcomes")
+ header = (
+ f" {'Model':<20} {'MRR (final)':>12} {'ARR (final)':>12} "
+ f"{'Growth':>7} {'LTV:CAC':>8} {'Break-even':>11}"
+ )
+ print(header)
+ print(" " + "-" * 74)
+ for proj in sorted(projections, key=lambda p: p.snapshots[-1].mrr, reverse=True):
+ final = proj.snapshots[-1]
+ growth_x = final.mrr / STARTING_MRR
+ arr_final = final.mrr * 12
+ be = f"Mo {proj.break_even_month}" if proj.break_even_month else f">{SIMULATION_MONTHS}mo"
+ print(
+ f" {proj.model.name:<20} {fmt_mrr(final.mrr):>12} "
+ f"{fmt_currency(arr_final):>12} {growth_x:>6.1f}x "
+ f"{proj.model.avg_ltv_cac:>7.1f}x {be:>11}"
+ )
+
+
+def print_channel_mix_impact(projections: List[ModelProjection]) -> None:
+ print_header("Channel Mix Impact Analysis")
+ print(" How shifting channel mix changes growth trajectory:\n")
+ baseline = next((p for p in projections if p.model.name == "Current Mix"), None)
+ if not baseline:
+ return
+ baseline_final_mrr = baseline.snapshots[-1].mrr
+
+ for proj in projections:
+ if proj.model.name == "Current Mix":
+ continue
+ final_mrr = proj.snapshots[-1].mrr
+ delta = final_mrr - baseline_final_mrr
+ delta_pct = (delta / baseline_final_mrr) * 100
+ arrow = "↑" if delta > 0 else "↓"
+ m6_mrr = proj.snapshots[5].mrr if len(proj.snapshots) >= 6 else 0
+ m6_baseline = baseline.snapshots[5].mrr if len(baseline.snapshots) >= 6 else 0
+ m6_delta = m6_mrr - m6_baseline
+ m6_pct = (m6_delta / m6_baseline) * 100 if m6_baseline else 0
+ m6_arrow = "↑" if m6_delta > 0 else "↓"
+
+ print(f" {proj.model.name}:")
+ print(f" Month 6: {m6_arrow} {abs(m6_pct):.1f}% vs. current ({fmt_mrr(m6_delta)} {'more' if m6_delta > 0 else 'less'} MRR)")
+ print(f" Month {SIMULATION_MONTHS}: {arrow} {abs(delta_pct):.1f}% vs. current ({fmt_mrr(delta)} {'more' if delta > 0 else 'less'} MRR)")
+ if proj.model.months_to_steady_state > 4:
+ print(f" ⚠ Model takes {proj.model.months_to_steady_state} months to reach steady state — short-term dip expected.")
+ print()
+
+
+def print_decision_guide(projections: List[ModelProjection]) -> None:
+ print_header("Decision Guide")
+ print(" Choose your growth model based on your constraints:\n")
+ guides = [
+ ("ACV < $5K and fast time-to-value", "PLG-First"),
+ ("ACV > $25K and complex buying process", "Sales-Led Scale"),
+ ("Strong practitioner community exists", "Community-Led"),
+ ("Both SMB self-serve and enterprise buyers", "Hybrid PLS"),
+ ("Uncertain — keep optionality", "Current Mix"),
+ ]
+ for condition, model_name in guides:
+ proj = next((p for p in projections if p.model.name == model_name), None)
+ if proj:
+ final_mrr = proj.snapshots[-1].mrr
+ print(f" If: {condition}")
+ print(f" → Use {model_name} → {fmt_mrr(final_mrr)} MRR at month {SIMULATION_MONTHS}")
+ print()
+
+ print(" Key question before switching models:")
+ print(" 'Do we have 12-18 months of runway to prove the new model")
+ print(" while the current model continues in parallel?'")
+ print(" If no → optimize current model. Don't switch.")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ print_channel_overview()
+
+ projections = [simulate_model(model, SIMULATION_MONTHS) for model in GROWTH_MODELS]
+
+ for proj in projections:
+ print_model_detail(proj)
+
+ print_comparison_table(projections)
+ print_channel_mix_impact(projections)
+ print_decision_guide(projections)
+
+ print("\n" + "=" * 78)
+ print(" Notes:")
+ print(f" Starting MRR: {fmt_mrr(STARTING_MRR)}")
+ print(f" Simulation: {SIMULATION_MONTHS} months")
+ print(f" Churn: {MONTHLY_CHURN_RATE:.1%}/mo ({MONTHLY_CHURN_RATE*12:.0%} annualized)")
+ print(f" Expansion: {EXPANSION_RATE:.1%}/mo of existing MRR")
+ print(f" Gross margin: {GROSS_MARGIN:.0%}")
+ print(" Acceleration rates are estimates — validate against your actuals.")
+ print("=" * 78 + "\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cmo-advisor/scripts/marketing_budget_modeler.py b/skills/c-level-advisor/cmo-advisor/scripts/marketing_budget_modeler.py
new file mode 100644
index 00000000..0e9dc8e9
--- /dev/null
+++ b/skills/c-level-advisor/cmo-advisor/scripts/marketing_budget_modeler.py
@@ -0,0 +1,440 @@
+#!/usr/bin/env python3
+"""
+Marketing Budget Modeler
+------------------------
+Allocates marketing budget across channels based on CAC efficiency and
+target MQL volume. Models conservative / moderate / aggressive scenarios.
+
+Usage:
+ python marketing_budget_modeler.py
+
+Inputs (edit INPUTS section below or extend with argparse):
+ - Annual revenue target (new ARR)
+ - Average selling price (ASP)
+ - Conversion rates by funnel stage
+ - Historical CAC per channel
+ - Channel capacity constraints (max MQLs the channel can realistically produce)
+
+Outputs:
+ - Required MQL volume by channel
+ - Budget allocation per channel per scenario
+ - LTV:CAC and payback period per channel
+ - Summary table across scenarios
+"""
+
+from __future__ import annotations
+import math
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Channel:
+ name: str
+ cac: float # Customer acquisition cost ($)
+ max_mqls_per_month: int # Realistic capacity ceiling (MQLs/month)
+ mql_to_close_rate: float # Combined MQL → closed-won rate (0.0–1.0)
+ payback_months: float # Based on ARPU × gross margin
+ ltv: float # Lifetime value ($)
+ trend: str = "stable" # "improving" | "stable" | "declining"
+
+
+@dataclass
+class FunnelRates:
+ mql_to_sal: float # MQL → Sales Accepted Lead
+ sal_to_sql: float # SAL → Sales Qualified Lead
+ sql_to_opp: float # SQL → Opportunity
+ opp_to_close: float # Opportunity → Closed-Won
+
+ @property
+ def mql_to_close(self) -> float:
+ return self.mql_to_sal * self.sal_to_sql * self.sql_to_opp * self.opp_to_close
+
+
+@dataclass
+class ScenarioResult:
+ name: str
+ total_budget: float
+ channel_budgets: Dict[str, float]
+ channel_mqls: Dict[str, int]
+ projected_customers: int
+ projected_arr: float
+ blended_cac: float
+ notes: List[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# INPUTS — edit these
+# ---------------------------------------------------------------------------
+
+TARGET_NEW_ARR = 3_000_000 # New ARR to generate this year ($)
+ASP_ANNUAL = 18_000 # Average annual contract value ($)
+GROSS_MARGIN = 0.75 # Product gross margin (%)
+ARPU_MONTHLY = ASP_ANNUAL / 12 # Monthly revenue per account
+
+FUNNEL = FunnelRates(
+ mql_to_sal=0.65,
+ sal_to_sql=0.45,
+ sql_to_opp=0.75,
+ opp_to_close=0.27,
+)
+
+# LTV = ARPU_monthly × gross_margin / monthly_churn_rate
+MONTHLY_CHURN = 0.012 # ~14% annual churn
+LTV = (ARPU_MONTHLY * GROSS_MARGIN) / MONTHLY_CHURN
+
+CHANNELS: List[Channel] = [
+ Channel(
+ name="Organic SEO",
+ cac=1_800,
+ max_mqls_per_month=80,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(1_800 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="improving",
+ ),
+ Channel(
+ name="Paid Search",
+ cac=6_200,
+ max_mqls_per_month=60,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(6_200 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="stable",
+ ),
+ Channel(
+ name="Paid Social (LinkedIn)",
+ cac=8_500,
+ max_mqls_per_month=35,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(8_500 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="declining",
+ ),
+ Channel(
+ name="Outbound SDR",
+ cac=5_100,
+ max_mqls_per_month=50,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(5_100 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="stable",
+ ),
+ Channel(
+ name="Events / Field",
+ cac=9_800,
+ max_mqls_per_month=25,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(9_800 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="stable",
+ ),
+ Channel(
+ name="Partner / Channel",
+ cac=3_400,
+ max_mqls_per_month=30,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(3_400 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="improving",
+ ),
+ Channel(
+ name="Content / Inbound",
+ cac=2_600,
+ max_mqls_per_month=45,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(2_600 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="improving",
+ ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Core calculations
+# ---------------------------------------------------------------------------
+
+def customers_needed(target_arr: float, asp: float) -> int:
+ return math.ceil(target_arr / asp)
+
+
+def mqls_needed_total(customers: int, mql_to_close: float) -> int:
+ return math.ceil(customers / mql_to_close)
+
+
+def ltv_to_cac(ltv: float, cac: float) -> float:
+ return ltv / cac if cac > 0 else 0.0
+
+
+def score_channel(ch: Channel) -> float:
+ """
+ Score a channel for budget priority.
+ Higher = more efficient. Used to rank allocation order.
+ Factors: LTV:CAC ratio, trend multiplier, capacity.
+ """
+ ratio = ltv_to_cac(ch.ltv, ch.cac)
+ trend_mult = {"improving": 1.2, "stable": 1.0, "declining": 0.7}.get(ch.trend, 1.0)
+ return ratio * trend_mult
+
+
+def allocate_mqls(
+ channels: List[Channel],
+ total_mqls_needed: int,
+ budget_multiplier: float = 1.0,
+) -> Tuple[Dict[str, int], Dict[str, float]]:
+ """
+ Allocate MQL targets across channels in priority order (best LTV:CAC first).
+ budget_multiplier: 0.7 = conservative, 1.0 = moderate, 1.3 = aggressive.
+ Returns (channel → MQLs, channel → budget).
+ """
+ ranked = sorted(channels, key=score_channel, reverse=True)
+ remaining = total_mqls_needed
+ channel_mqls: Dict[str, int] = {}
+ channel_budget: Dict[str, float] = {}
+
+ for ch in ranked:
+ if remaining <= 0:
+ channel_mqls[ch.name] = 0
+ channel_budget[ch.name] = 0.0
+ continue
+ # Apply capacity ceiling scaled by multiplier (aggressive = push capacity)
+ capacity = int(ch.max_mqls_per_month * 12 * budget_multiplier)
+ allocated = min(remaining, capacity)
+ channel_mqls[ch.name] = allocated
+ channel_budget[ch.name] = allocated * ch.cac
+ remaining -= allocated
+
+ return channel_mqls, channel_budget
+
+
+def build_scenario(
+ name: str,
+ channels: List[Channel],
+ total_mqls: int,
+ multiplier: float,
+ notes: List[str],
+) -> ScenarioResult:
+ channel_mqls, channel_budget = allocate_mqls(channels, total_mqls, multiplier)
+
+ total_budget = sum(channel_budget.values())
+ total_mqls_allocated = sum(channel_mqls.values())
+ projected_customers = math.floor(total_mqls_allocated * FUNNEL.mql_to_close)
+ projected_arr = projected_customers * ASP_ANNUAL
+
+ # Blended CAC = total budget / customers acquired
+ blended_cac = total_budget / projected_customers if projected_customers > 0 else 0.0
+
+ return ScenarioResult(
+ name=name,
+ total_budget=total_budget,
+ channel_budgets=channel_budget,
+ channel_mqls=channel_mqls,
+ projected_customers=projected_customers,
+ projected_arr=projected_arr,
+ blended_cac=blended_cac,
+ notes=notes,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt_currency(n: float) -> str:
+ if n >= 1_000_000:
+ return f"${n/1_000_000:.2f}M"
+ if n >= 1_000:
+ return f"${n/1_000:.1f}K"
+ return f"${n:.0f}"
+
+
+def fmt_ratio(n: float) -> str:
+ return f"{n:.1f}x"
+
+
+def print_header(title: str) -> None:
+ width = 72
+ print("\n" + "=" * width)
+ print(f" {title}")
+ print("=" * width)
+
+
+def print_channel_table(channels: List[Channel]) -> None:
+ print_header("Channel Analysis — Current State")
+ header = f"{'Channel':<25} {'CAC':>8} {'Payback':>9} {'LTV:CAC':>8} {'Cap/mo':>7} {'Trend':>10}"
+ print(header)
+ print("-" * 72)
+ for ch in sorted(channels, key=score_channel, reverse=True):
+ ratio = ltv_to_cac(ch.ltv, ch.cac)
+ flag = ""
+ if ratio < 1:
+ flag = " ⚠ LOSS"
+ elif ratio >= 6:
+ flag = " ★ STRONG"
+ elif ratio >= 3:
+ flag = " ✓"
+ print(
+ f"{ch.name:<25} {fmt_currency(ch.cac):>8} "
+ f"{ch.payback_months:>7.1f}mo {fmt_ratio(ratio):>8} "
+ f"{ch.max_mqls_per_month:>7} {ch.trend:>10}{flag}"
+ )
+
+
+def print_funnel_summary(customers: int, mqls: int) -> None:
+ print_header("Funnel Requirements")
+ print(f" Target new ARR: {fmt_currency(TARGET_NEW_ARR)}")
+ print(f" Average selling price: {fmt_currency(ASP_ANNUAL)}")
+ print(f" New customers needed: {customers}")
+ print(f" Funnel MQL→Close rate: {FUNNEL.mql_to_close:.1%}")
+ print(f" Total MQLs needed: {mqls}")
+ print(f"\n Funnel stage rates:")
+ print(f" MQL → SAL: {FUNNEL.mql_to_sal:.0%}")
+ print(f" SAL → SQL: {FUNNEL.mql_to_sal * FUNNEL.sal_to_sql:.0%}")
+ print(f" SQL → Opportunity: {FUNNEL.mql_to_sal * FUNNEL.sal_to_sql * FUNNEL.sql_to_opp:.0%}")
+ print(f" Opportunity → Close: {FUNNEL.mql_to_close:.0%}")
+ print(f"\n LTV (estimated): {fmt_currency(LTV)}")
+ print(f" Monthly churn: {MONTHLY_CHURN:.1%} ({MONTHLY_CHURN*12:.0%} annualized)")
+
+
+def print_scenario(result: ScenarioResult, channels: List[Channel]) -> None:
+ print_header(f"Scenario: {result.name}")
+ print(f" Total marketing budget: {fmt_currency(result.total_budget)}")
+ print(f" Projected customers: {result.projected_customers}")
+ print(f" Projected new ARR: {fmt_currency(result.projected_arr)}")
+ print(f" Blended CAC: {fmt_currency(result.blended_cac)}")
+ blended_ltv_cac = LTV / result.blended_cac if result.blended_cac > 0 else 0
+ blended_payback = result.blended_cac / (ARPU_MONTHLY * GROSS_MARGIN)
+ print(f" Blended LTV:CAC: {fmt_ratio(blended_ltv_cac)}", end="")
+ if blended_ltv_cac < 1:
+ print(" ⚠ BELOW BREAK-EVEN")
+ elif blended_ltv_cac < 3:
+ print(" △ MARGINAL")
+ elif blended_ltv_cac >= 3:
+ print(" ✓ HEALTHY")
+ else:
+ print()
+ print(f" Blended payback: {blended_payback:.1f} months")
+ if result.notes:
+ print(f"\n Notes:")
+ for note in result.notes:
+ print(f" • {note}")
+
+ print(f"\n {'Channel':<25} {'MQLs':>6} {'Budget':>10} {'% of Budget':>12} {'LTV:CAC':>8}")
+ print(" " + "-" * 65)
+ for ch in sorted(channels, key=score_channel, reverse=True):
+ mqls = result.channel_mqls.get(ch.name, 0)
+ budget = result.channel_budgets.get(ch.name, 0.0)
+ pct = (budget / result.total_budget * 100) if result.total_budget > 0 else 0
+ ratio = ltv_to_cac(ch.ltv, ch.cac)
+ print(
+ f" {ch.name:<25} {mqls:>6} {fmt_currency(budget):>10} "
+ f"{pct:>11.1f}% {fmt_ratio(ratio):>8}"
+ )
+
+
+def print_scenario_comparison(scenarios: List[ScenarioResult]) -> None:
+ print_header("Scenario Comparison")
+ header = f"{'Scenario':<18} {'Budget':>10} {'Customers':>10} {'ARR':>10} {'Blended CAC':>12} {'LTV:CAC':>8} {'Payback':>9}"
+ print(header)
+ print("-" * 82)
+ for s in scenarios:
+ blended_ltv_cac = LTV / s.blended_cac if s.blended_cac > 0 else 0
+ blended_payback = s.blended_cac / (ARPU_MONTHLY * GROSS_MARGIN)
+ print(
+ f"{s.name:<18} {fmt_currency(s.total_budget):>10} "
+ f"{s.projected_customers:>10} {fmt_currency(s.projected_arr):>10} "
+ f"{fmt_currency(s.blended_cac):>12} {fmt_ratio(blended_ltv_cac):>8} "
+ f"{blended_payback:>7.1f}mo"
+ )
+
+
+def print_recommendations(channels: List[Channel]) -> None:
+ print_header("Channel Recommendations")
+ scale = [ch for ch in channels if score_channel(ch) >= 1.5 and ch.trend in ("improving", "stable")]
+ hold = [ch for ch in channels if 0.8 <= score_channel(ch) < 1.5 or (ch.trend == "stable" and ltv_to_cac(ch.ltv, ch.cac) >= 3)]
+ cut = [ch for ch in channels if ltv_to_cac(ch.ltv, ch.cac) < 2 or ch.trend == "declining"]
+ # Deduplicate
+ hold = [ch for ch in hold if ch not in scale]
+ cut = [ch for ch in cut if ch not in scale and ch not in hold]
+
+ if scale:
+ print(" SCALE (strong LTV:CAC, improving or stable trend):")
+ for ch in scale:
+ print(f" + {ch.name} [LTV:CAC {fmt_ratio(ltv_to_cac(ch.ltv, ch.cac))}, payback {ch.payback_months:.0f}mo]")
+ if hold:
+ print(" HOLD (monitor — adequate but not outstanding):")
+ for ch in hold:
+ print(f" = {ch.name} [LTV:CAC {fmt_ratio(ltv_to_cac(ch.ltv, ch.cac))}, trend: {ch.trend}]")
+ if cut:
+ print(" CUT or REDUCE (poor LTV:CAC or declining):")
+ for ch in cut:
+ print(f" - {ch.name} [LTV:CAC {fmt_ratio(ltv_to_cac(ch.ltv, ch.cac))}, trend: {ch.trend}]")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ customers = customers_needed(TARGET_NEW_ARR, ASP_ANNUAL)
+ total_mqls = mqls_needed_total(customers, FUNNEL.mql_to_close)
+
+ print_channel_table(CHANNELS)
+ print_funnel_summary(customers, total_mqls)
+
+ scenarios = [
+ build_scenario(
+ name="Conservative",
+ channels=CHANNELS,
+ total_mqls=total_mqls,
+ multiplier=0.7,
+ notes=[
+ "Prioritizes lowest CAC channels only.",
+ "May not reach MQL target — expect ~70% of goal.",
+ "Best for capital-constrained orgs or short runway.",
+ ],
+ ),
+ build_scenario(
+ name="Moderate",
+ channels=CHANNELS,
+ total_mqls=total_mqls,
+ multiplier=1.0,
+ notes=[
+ "Balanced allocation — efficiency-first but full MQL target.",
+ "Recommended baseline. Revisit Q2 based on actuals.",
+ ],
+ ),
+ build_scenario(
+ name="Aggressive",
+ channels=CHANNELS,
+ total_mqls=total_mqls,
+ multiplier=1.4,
+ notes=[
+ "Pushes all channels toward capacity ceiling.",
+ "Higher spend on lower-efficiency channels to hit volume.",
+ "Requires > 18-month runway to justify payback period.",
+ ],
+ ),
+ ]
+
+ for scenario in scenarios:
+ print_scenario(scenario, CHANNELS)
+
+ print_scenario_comparison(scenarios)
+ print_recommendations(CHANNELS)
+
+ print("\n" + "=" * 72)
+ print(" Key questions before finalizing budget:")
+ print(" 1. What is the payback period the CFO/board will accept?")
+ print(" 2. Is CAC for declining-trend channels actually recoverable?")
+ print(" 3. Does the moderate scenario require sales headcount increase?")
+ print(" 4. Which channels have capacity to absorb 20% more spend?")
+ print("=" * 72 + "\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/company-os/SKILL.md b/skills/c-level-advisor/company-os/SKILL.md
new file mode 100644
index 00000000..9b5d7d91
--- /dev/null
+++ b/skills/c-level-advisor/company-os/SKILL.md
@@ -0,0 +1,236 @@
+---
+name: "company-os"
+description: "The meta-framework for how a company runs — the connective tissue between all C-suite roles. Covers operating system selection (EOS, Scaling Up, OKR-native, hybrid), accountability charts, scorecards, meeting pulse, issue resolution, and 90-day rocks. Use when setting up company operations, selecting a management framework, designing meeting rhythms, building accountability systems, implementing OKRs, or when user mentions EOS, Scaling Up, operating system, L10 meetings, rocks, scorecard, accountability chart, or quarterly planning."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: company-operations
+ updated: 2026-03-05
+ frameworks: os-comparison, implementation-guide
+---
+
+# Company Operating System
+
+The operating system is the collection of tools, rhythms, and agreements that determine how the company functions. Every company has one — most just don't know what it is. Making it explicit makes it improvable.
+
+## Keywords
+operating system, EOS, Entrepreneurial Operating System, Scaling Up, Rockefeller Habits, OKR, Holacracy, L10 meeting, rocks, scorecard, accountability chart, issues list, IDS, meeting pulse, quarterly planning, weekly scorecard, management framework, company rhythm, traction, Gino Wickman, Verne Harnish
+
+## Why This Matters
+
+Most operational dysfunction isn't a people problem — it's a system problem. When:
+- The same issues recur every week: no issue resolution system
+- Meetings feel pointless: no structured meeting pulse
+- Nobody knows who owns what: no accountability chart
+- Quarterly goals slip: rocks aren't real commitments
+
+Fix the system. The people will operate better inside it.
+
+## The Six Core Components
+
+Every effective operating system has these six, regardless of which framework you choose:
+
+### 1. Accountability Chart
+
+Not an org chart. An accountability chart answers: "Who owns this outcome?"
+
+**Key distinction:** One person owns each function. Multiple people may work in it. Ownership means the buck stops with one person.
+
+**Structure:**
+```
+CEO
+├── Sales (CRO/VP Sales)
+│ ├── Inbound pipeline
+│ └── Outbound pipeline
+├── Product & Engineering (CTO/CPO)
+│ ├── Product roadmap
+│ └── Engineering delivery
+├── Operations (COO)
+│ ├── Customer success
+│ └── Finance & Legal
+└── People (CHRO/VP People)
+ ├── Recruiting
+ └── People operations
+```
+
+**Rules:**
+- No shared ownership. "Alice and Bob both own it" means nobody owns it.
+- One person can own multiple seats at early stages. That's fine. Just be explicit.
+- Revisit quarterly as you scale. Ownership shifts as the company grows.
+
+**Build it in a workshop:**
+1. List all functions the company performs
+2. Assign one owner per function — no exceptions
+3. Identify gaps (functions nobody owns) and overlaps (functions two people think they own)
+4. Publish it. Update it when something changes.
+
+### 2. Scorecard
+
+Weekly metrics that tell you if the company is on track. Not monthly. Not quarterly. Weekly.
+
+**Rules:**
+- 5–15 metrics maximum. More than 15 and nothing gets attention.
+- Each metric has an owner and a weekly target (not a range — a number).
+- Red/yellow/green status. Not paragraphs.
+- The scorecard is discussed at the leadership team weekly meeting. Only red metrics get discussion time.
+
+**Example scorecard structure:**
+
+| Metric | Owner | Target | This Week | Status |
+|--------|-------|--------|-----------|--------|
+| New MRR | CRO | €50K | €43K | 🔴 |
+| Churn | CS Lead | < 1% | 0.8% | 🟢 |
+| Active users | CPO | 2,000 | 2,150 | 🟢 |
+| Deployments | CTO | 3/week | 3 | 🟢 |
+| Open critical bugs | CTO | 0 | 2 | 🔴 |
+| Runway | CFO | > 18mo | 16mo | 🟡 |
+
+**Anti-pattern:** Measuring everything. If you track 40 KPIs, you're watching, not managing.
+
+### 3. Meeting Pulse
+
+The meeting rhythm that drives the company. Not optional — the pulse is what keeps the company alive.
+
+**The full rhythm:**
+
+| Meeting | Frequency | Duration | Who | Purpose |
+|---------|-----------|----------|-----|---------|
+| Daily standup | Daily | 15 min | Each team | Blockers only |
+| L10 / Leadership sync | Weekly | 90 min | Leadership team | Scorecard + issues |
+| Department review | Monthly | 60 min | Dept + leadership | OKR progress |
+| Quarterly planning | Quarterly | 1–2 days | Leadership | Set rocks, review strategy |
+| Annual planning | Annual | 2–3 days | Leadership | 1-year + 3-year vision |
+
+**The L10 meeting (Weekly Leadership Sync):**
+Named for the goal of each meeting being a 10/10. Fixed agenda:
+1. Good news (5 min) — personal + business
+2. Scorecard review (5 min) — flag red items only
+3. Rock review (5 min) — on/off track for each rock
+4. Customer/employee headlines (5 min)
+5. Issues list (60 min) — IDS (see below)
+6. To-dos review (5 min) — last week's commitments
+7. Conclude (5 min) — rate the meeting 1–10, what would make it a 10 next time
+
+### 4. Issue Resolution (IDS)
+
+The core problem-solving loop. Maximum 15 minutes per issue.
+
+**IDS: Identify, Discuss, Solve**
+
+- **Identify:** What is the actual issue? (Not the symptom — the root cause) State it in one sentence.
+- **Discuss:** Relevant facts + perspectives. Time-boxed. When discussion starts repeating, stop.
+- **Solve:** One owner. One action. One due date. Written on the to-do list.
+
+**Anti-patterns:**
+- "Let's take this offline" — most things taken offline never get resolved
+- Discussing without deciding — a great discussion with no action item is wasted time
+- Revisiting decided issues — once solved, it leaves the list. Reopen only with new information.
+
+**The Issues List:** A running, prioritized list of all unresolved issues. Owned by the leadership team. Reviewed and pruned weekly. If an issue has been on the list for 3+ meetings and hasn't been discussed, it's either not a real issue or it's too scary to address — both deserve attention.
+
+### 5. Rocks (90-Day Priorities)
+
+Rocks are the 3–7 most important things each person must accomplish in the next 90 days. They're not the job description — they're the things that move the company forward.
+
+**Why 90 days?** Long enough for meaningful progress. Short enough to stay real.
+
+**Rock rules:**
+- Each person: 3–7 rocks maximum. More than 7 and none get done.
+- Company-level rocks (shared priorities): 3–7 for the leadership team
+- Each rock is binary: done or not done. No "60% complete."
+- Set at the quarterly planning session. Reviewed weekly (on/off track).
+
+**Bad rock:** "Improve our sales process"
+**Good rock:** "Implement Salesforce CRM with full pipeline stages and weekly reporting by March 31"
+
+**Rock vs. to-do:** A to-do takes one action. A rock takes 90 days of consistent work.
+
+### 6. Communication Cadence
+
+Who gets what information, when, and how.
+
+| Audience | What | When | Format |
+|----------|------|------|--------|
+| All employees | Company update | Monthly | Written + Q&A |
+| All employees | Quarterly results + next priorities | Quarterly | All-hands |
+| Leadership team | Scorecard | Weekly | Dashboard |
+| Board | Company performance | Monthly | Board memo |
+| Investors | Key metrics + narrative | Monthly or quarterly | Investor update |
+| Customers | Product updates | Per release | Release notes |
+
+**Default rule:** If you're deciding whether to share something internally, share it. The cost of under-communication always exceeds the cost of over-communication inside a company.
+
+---
+
+## Operating System Selection
+
+See `references/os-comparison.md` for full comparison. Quick guide:
+
+| If you are... | Consider... |
+|---------------|-------------|
+| 10–250 person company, founder-led, operational chaos | EOS / Traction |
+| Ambitious growth company, need rigorous strategy cascade | Scaling Up |
+| Tech company, engineering culture, hypothesis-driven | OKR-native |
+| Decentralized, flat, high autonomy | Holacracy (only if you're patient) |
+| None of the above quite fit | Custom hybrid |
+
+---
+
+## Implementation Roadmap
+
+Don't implement everything at once. See `references/implementation-guide.md` for the full 90-day plan.
+
+**Quick start (first 30 days):**
+1. Build the accountability chart (1 workshop, 2 hours)
+2. Define 5–10 weekly scorecard metrics (leadership team alignment, 1 hour)
+3. Start the weekly L10 meeting (no prep — just start)
+
+These three alone will improve coordination more than most companies achieve in a year.
+
+---
+
+## Common Failure Modes
+
+**Partial implementation:** "We do OKRs but skip the weekly check-in." Half an operating system is worse than none — it creates theater without accountability.
+
+**Meeting fatigue:** Adding the full rhythm on top of existing meetings. Start by replacing meetings, not adding them.
+
+**Metric overload:** Starting with 30 KPIs because "they all matter." Start with 5. Add when the cadence is established.
+
+**Rock inflation:** Setting 12 rocks per person because "everything is a priority." When everything is a priority, nothing is. Hard limit: 7.
+
+**Leader non-compliance:** Leadership team skips the L10 or doesn't follow IDS. The operating system mirrors the respect leadership gives it. If leaders don't take it seriously, nobody will.
+
+**Annual planning without quarterly review:** Setting annual goals and checking in at year-end. Quarterly is the minimum review cycle for any meaningful goal.
+
+---
+
+## Integration with C-Suite
+
+The company OS is the connective tissue. Every other role depends on it:
+
+| C-Suite Role | OS Dependency |
+|-------------|---------------|
+| CEO | Sets vision that feeds into 1-year plan and rocks |
+| COO | Owns the meeting pulse and issue resolution cadence |
+| CFO | Owns the financial metrics in the scorecard |
+| CTO | Owns engineering rocks and tech scorecard metrics |
+| CHRO | Owns people metrics (attrition, hiring velocity) in scorecard |
+| Culture Architect | Culture rituals plug into the meeting pulse |
+| Strategic Alignment Engine | Validates that team rocks cascade from company rocks |
+
+---
+
+## Key Questions for the Operating System
+
+- "If I asked five different team leads what the company's top 3 priorities are this quarter, would they give the same answers?"
+- "What was the most important issue raised in last week's leadership meeting? Was it resolved or is it still open?"
+- "Name a metric that would tell us by Friday whether this week was a good week. Do we track it?"
+- "Who owns customer churn? Can you name that person without hesitation?"
+- "When was the last time we updated the accountability chart?"
+
+## Detailed References
+- `references/os-comparison.md` — EOS vs Scaling Up vs OKRs vs Holacracy vs hybrid
+- `references/implementation-guide.md` — 90-day implementation plan
diff --git a/skills/c-level-advisor/company-os/references/implementation-guide.md b/skills/c-level-advisor/company-os/references/implementation-guide.md
new file mode 100644
index 00000000..f222405c
--- /dev/null
+++ b/skills/c-level-advisor/company-os/references/implementation-guide.md
@@ -0,0 +1,249 @@
+# Company Operating System — 90-Day Implementation Guide
+
+Don't implement everything at once. The fastest path to failure is trying to launch the full operating system in week one. Build incrementally. Let the team experience wins before adding complexity.
+
+---
+
+## Before You Start
+
+### Prerequisites
+
+**Leadership alignment (non-negotiable):**
+Every member of the leadership team must understand why you're doing this and commit to running the system. One holdout destroys the whole model. If the CFO skips the L10 meetings, the system won't work.
+
+**Current state audit:**
+- What meetings currently exist? Which can be replaced?
+- Who owns which functions today? (Even informally)
+- What metrics are being tracked? (Even inconsistently)
+
+**Assign an OS owner:**
+One person is responsible for the implementation and ongoing maintenance of the operating system. Usually the COO or CEO (at smaller companies). This is not a committee job.
+
+---
+
+## Week 1–2: Accountability Chart + Scorecard
+
+### Accountability Chart Workshop (Week 1)
+
+**Duration:** 2–3 hours, full leadership team
+
+**Step 1 — List all functions (30 min)**
+On a whiteboard, list every function the company performs:
+- Sales (inbound, outbound, partnerships)
+- Marketing (content, paid, brand)
+- Product (roadmap, design, research)
+- Engineering (frontend, backend, devops)
+- Customer success (onboarding, support, retention)
+- Finance (accounting, FP&A, legal)
+- People (recruiting, HR, culture)
+- Operations (processes, tools, facilities)
+
+**Step 2 — Assign owners (45 min)**
+For each function: "Who is the one person ultimately accountable?" Write their name.
+Rules: One name only. No joint ownership. One person can own multiple functions at small scale.
+
+**Step 3 — Identify gaps and overlaps (30 min)**
+- **Gaps:** Functions with no owner → Who should own them? Or do we need a hire?
+- **Overlaps:** Two people said they own the same thing → Resolve now, not later.
+
+**Step 4 — Publish and socialize (Week 2)**
+Share with the full company. Explain what an accountability chart is and isn't.
+"This is about clarity, not hierarchy. It tells everyone who to go to for each function."
+
+**Output:** A documented accountability chart. Use a simple tool (Miro, Google Slides, Ninety.io).
+
+---
+
+### Scorecard Design (Week 2)
+
+**Duration:** 90 minutes, leadership team
+
+**Step 1 — List candidate metrics (30 min)**
+Each leader lists 3–5 metrics they already track or wish they tracked. No filtering yet.
+
+**Step 2 — Filter to 5–15 (30 min)**
+Criteria: Is it measurable weekly? Does it tell us if the company is healthy? Does one person own it?
+Drop: metrics that are monthly only, metrics without a clear owner, metrics that measure activity not outcomes.
+
+**Step 3 — Set weekly targets (20 min)**
+For each metric: what's the weekly target? Not a range — a number. Red/yellow/green thresholds.
+
+**Step 4 — Assign owners (10 min)**
+Every metric has one owner who is responsible for reporting it weekly.
+
+**Output:** A scorecard document. 5–15 metrics, owner, target, weekly tracking column.
+
+**First scorecard run:** Week 2 or 3. It won't be perfect. That's fine.
+
+---
+
+## Week 3–4: Meeting Pulse (Start With L10)
+
+Don't start all the meetings at once. Start with the weekly L10. Replace existing leadership syncs.
+
+### L10 Meeting Setup
+
+**Schedule:** Same day, same time, every week. Non-negotiable attendance.
+**Duration:** 90 minutes. No more, no less.
+**Facilitator:** Rotate or assign to COO/CEO. The facilitator keeps time and follows the agenda.
+
+**Fixed agenda:**
+1. **Good news** (5 min) — One personal, one business from each person. No skipping.
+2. **Scorecard review** (5 min) — Traffic light only. Red items go to the issues list.
+3. **Rock review** (5 min) — Each person: "on track" or "off track." No justification needed at this step.
+4. **Customer/employee headlines** (5 min) — One sentence each. No reports.
+5. **Issues** (60 min) — IDS process. Prioritize the top 3–5 issues. Solve them.
+6. **To-do review** (5 min) — Review last week's commitments (done/not done). No excuses, just data.
+7. **Conclude** (5 min) — Rate the meeting 1–10. What would make next week better?
+
+**First L10 meeting:**
+It will feel awkward. Run through the agenda anyway. The team needs the repetition to internalize it. By week 4, it should feel natural.
+
+### Issues List Setup
+
+Create a shared document (Notion, Google Docs, or dedicated tool):
+- Issue title
+- Priority (High / Medium / Low)
+- Status (Open / In progress / Solved)
+- Owner (once assigned)
+- Due date
+
+At the first L10, generate the issues list by asking: "What's getting in our way right now?" Expect 10–20 items on the first pass.
+
+---
+
+## Week 5–8: Rocks and Quarterly Planning
+
+### Quarterly Planning Session (end of Week 5 or start of Week 6)
+
+**Duration:** 4–8 hours (or 2 × 4-hour days for larger teams)
+**Who:** Full leadership team
+
+**Session structure:**
+
+**Part 1: Review previous quarter (60–90 min)**
+- What rocks were completed? What were dropped?
+- What did we learn?
+- What changed in the market or company?
+
+**Part 2: Confirm or update company direction (60 min)**
+- Is the 1-year goal still valid?
+- Any major strategy shifts needed?
+- Update the V/TO or OPSP if using EOS or Scaling Up.
+
+**Part 3: Set company rocks (90 min)**
+- Brainstorm: What are the 3–7 most important things to accomplish this quarter?
+- Prioritize. Be ruthless. 3 rocks done > 7 rocks started.
+- Each rock: clear owner, clear definition of done, 90-day timeline.
+
+**Part 4: Set individual rocks (60 min)**
+- Each leader sets their 3–7 rocks (aligned with company rocks where possible)
+- Share with group: dependencies? Conflicts? Overloaded people?
+
+**Part 5: Communicate (Week 6)**
+- Share company rocks with the full organization within 1 week
+- Each team sets their own rocks, cascaded from company rocks (3–5 per team)
+
+**Rock template:**
+```
+Rock: [What you'll accomplish]
+Owner: [One person]
+Due date: [Specific date within the quarter]
+Definition of done: [How we'll know it's complete]
+Dependencies: [What else needs to happen first]
+```
+
+---
+
+## Week 9–12: Issue Resolution Mastery + Communication Cadence
+
+By now the L10 should be running smoothly. Weeks 9–12 focus on deepening IDS skills and establishing the broader communication cadence.
+
+### IDS Practice
+
+The issue resolution process often degrades in weeks 5–8. Common problems:
+- Issues discussed but never solved (no clear action item)
+- Same issues recurring (root cause not addressed)
+- Too many issues, not enough resolution (prioritization failing)
+
+**IDS calibration exercise (Week 9):**
+In the next L10, after each issue is "solved," ask:
+- "Is this actually solved, or are we postponing it?"
+- "What's the specific action? Who owns it? When is it due?"
+- "Is this the real issue, or a symptom of something deeper?"
+
+### Communication Cadence Setup
+
+Build out the full communication calendar:
+
+| Communication | Frequency | Owner | Format | Tool |
+|---------------|-----------|-------|--------|------|
+| Company all-hands | Monthly | CEO | Update + Q&A | Video call |
+| Quarterly planning results | Quarterly | CEO/COO | Written + live | Notion + all-hands |
+| Board update | Monthly | CEO + CFO | Board memo | Doc |
+| Investor update | Monthly | CEO + CFO | Email | Template |
+| Department L10s | Weekly | Dept lead | L10 format | In-person / Zoom |
+| Daily standups | Daily | Team leads | 15 min | Team call |
+
+**Company all-hands template:**
+1. State of the company (financial health, key metrics) — 10 min
+2. Quarterly rocks: what we committed to, where we stand — 10 min
+3. Wins and recognitions — 5 min
+4. What's coming next quarter — 10 min
+5. Q&A — 15–25 min
+
+---
+
+## Post-90 Days: Refinement and Optimization
+
+### Month 4 retrospective
+
+After the first full quarter, run a retrospective on the operating system itself:
+- What's working? What isn't?
+- Which meetings should continue as-is? Which need adjustment?
+- Is the scorecard measuring the right things?
+- Are rocks the right size and specificity?
+- What should we add next?
+
+### Scorecard evolution
+
+By month 4, you'll know which metrics matter most. Add 2–3 that are missing. Remove metrics that nobody uses for decisions.
+
+### L10 health check
+
+Rate your L10 meetings over the first quarter:
+- Average rating < 7: The agenda isn't being followed or issues aren't being resolved. Diagnose.
+- Average rating 7–8: Normal. Keep building discipline.
+- Average rating > 8: The team is engaged. Start extending the system to department level.
+
+### Department L10s (Month 4+)
+
+Once leadership L10 is running well, cascade the meeting structure:
+- Each department runs their own weekly L10
+- Department rocks cascade from company rocks
+- Issues that cross departments are escalated to leadership L10
+
+### Year 1 annual planning
+
+End of year 1: run a full-day annual planning session.
+- Review the year: what did we accomplish? What did we miss? What did we learn?
+- Update 3-year vision (has it changed?)
+- Set next year's annual goals
+- Set Q1 rocks
+- Celebrate. Seriously — mark the milestone.
+
+---
+
+## Implementation Anti-Patterns
+
+**Skipping the accountability chart:** Without ownership clarity, every other system breaks down. Do this first.
+
+**Building a perfect scorecard before starting:** Start with 5 imperfect metrics. Improve over time.
+
+**Not replacing existing meetings:** Adding L10 on top of 3 existing meetings creates meeting overload. Cancel the redundant ones.
+
+**Leader non-participation:** If one leader consistently skips or is disengaged, the system won't work. Address this directly — it's a culture issue, not a calendar issue.
+
+**Changing the L10 agenda:** The agenda works because of repetition. Resist the urge to customize it for the first 6 months.
+
+**Rocks without accountability:** If nobody checks rocks at the L10 ("on track / off track"), they become wish lists. The weekly review is what makes them real.
diff --git a/skills/c-level-advisor/company-os/references/os-comparison.md b/skills/c-level-advisor/company-os/references/os-comparison.md
new file mode 100644
index 00000000..c95d340b
--- /dev/null
+++ b/skills/c-level-advisor/company-os/references/os-comparison.md
@@ -0,0 +1,242 @@
+# Operating System Comparison
+
+Side-by-side analysis of the major company operating frameworks.
+
+---
+
+## Overview
+
+| Framework | Origin | Best fit | Implementation time | Cost |
+|-----------|--------|----------|---------------------|------|
+| EOS | Gino Wickman, 2007 | 10–250 employees, founder-led | 2–3 years full adoption | Free (DIY) to $25K+/year (implementer) |
+| Scaling Up | Verne Harnish, 2002 | Growth-stage, strategic focus | 1–2 years | Free (DIY) to $15K+/year (coach) |
+| OKR-native | Andy Grove / Google | Tech companies, product orgs | 3–6 months | Free |
+| Holacracy | Brian Robertson, 2007 | Flat, autonomous organizations | 2–4 years | $5K–$50K+ (certification) |
+| Custom hybrid | You | When the above don't fit exactly | Ongoing | Whatever you invest |
+
+---
+
+## 1. EOS — Entrepreneurial Operating System
+
+**Book:** *Traction* by Gino Wickman
+
+### Core principles
+EOS is built on Six Components:
+1. **Vision** — Where are you going? (V/TO: Vision/Traction Organizer)
+2. **People** — Right people, right seats
+3. **Data** — Scorecard with weekly metrics
+4. **Issues** — Surface and resolve with IDS
+5. **Process** — Document core processes
+6. **Traction** — Rocks + meeting pulse (L10)
+
+### Signature tools
+- **V/TO (Vision/Traction Organizer):** 2-page strategy doc. Core values, core focus, 10-year target, 3-year picture, 1-year plan, quarterly rocks, issues.
+- **Accountability Chart:** Who owns what function (not org chart)
+- **L10 meeting:** Weekly 90-minute leadership sync (Level 10 = aim for 10/10)
+- **Rocks:** 90-day priority commitments (3–7 per person)
+- **IDS:** Identify, Discuss, Solve (issue resolution, max 15 min per issue)
+
+### Strengths
+- **Operationally focused.** If your problem is execution chaos, EOS addresses it directly.
+- **Accessible.** The book is practical. You can DIY it without a coach.
+- **Community.** Large network of implementers, tools (Ninety.io, EOS Worldwide), and practitioners.
+- **Simple enough to actually use.** No complex methodology. Most teams are functional within 6 months.
+
+### Limitations
+- **Strategic depth is shallow.** The V/TO is good for direction but doesn't replace real strategy work.
+- **Doesn't scale beyond ~250.** Designed for entrepreneurial companies. Gets cumbersome at enterprise scale.
+- **Assumes a cohesive leadership team.** If trust is broken at the top, EOS won't fix it.
+- **Facilitator dependency.** Many companies benefit from an EOS Implementer (external coach), which adds cost.
+
+### Best fit
+- 10–150 person companies
+- Founder-led, operational dysfunction
+- Teams that can't stay on the same page
+- Companies with recurring issues that never get resolved
+- First real "operating system" for a company that's been running on vibes
+
+### Not ideal if
+- You need sophisticated strategic planning
+- You're > 250 people and already have ops infrastructure
+- Your team resists structured methodology
+
+---
+
+## 2. Scaling Up (Rockefeller Habits 2.0)
+
+**Book:** *Scaling Up* by Verne Harnish
+
+### Core principles
+Built on four Decisions:
+1. **People** — Core values, talent management, Topgrading
+2. **Strategy** — One-Page Strategic Plan (OPSP), 7 Strata of Strategy
+3. **Execution** — Priorities (rocks), meeting rhythm, critical numbers
+4. **Cash** — Power of One, Cash Acceleration Strategies (CAS)
+
+### Signature tools
+- **One-Page Strategic Plan (OPSP):** Annual and quarterly goals on one page. More strategic than EOS's V/TO.
+- **7 Strata of Strategy:** Competitive positioning, core customer, brand promise, X-factor (10x advantage), profit per X, BHAG, critical numbers.
+- **Meeting rhythm:** Daily (5–15 min), weekly, monthly, quarterly, annual — with specific templates.
+- **Critical number:** One metric that, if improved, fixes everything else.
+- **Cash acceleration:** CAS system for improving working capital and cash conversion cycle.
+
+### Strengths
+- **Stronger strategic framework than EOS.** The 7 strata and OPSP force real strategic thinking.
+- **Cash focus.** Unique among frameworks — explicitly addresses cash flow management.
+- **Scales further.** Better suited for 100–1000 person companies than EOS.
+- **Works for ambitious growth companies.** Designed for companies that want to scale significantly.
+
+### Limitations
+- **More complex than EOS.** Harder to DIY. Benefits heavily from a certified Scaling Up coach.
+- **Overwhelming at first.** The full framework has many components. Teams often implement partially.
+- **Less prescriptive on meetings.** EOS's L10 is very specific. Scaling Up's meeting rhythm requires more customization.
+
+### Best fit
+- Series A to Series C companies
+- Companies with strong growth ambition
+- Leadership teams that want strategic rigor, not just operational clarity
+- Companies already past initial chaos, ready for more sophisticated frameworks
+
+### Not ideal if
+- You're pre-product-market-fit
+- You need quick operational wins
+- Your team doesn't have the bandwidth for the learning curve
+
+---
+
+## 3. OKR-Native (Google Style)
+
+**Books:** *Measure What Matters* by John Doerr; *Radical Focus* by Christina Wodtke
+
+### Core principles
+OKRs = Objectives + Key Results
+
+- **Objectives:** Qualitative, inspiring direction. "What are we trying to achieve?"
+- **Key Results:** Quantitative, measurable outcomes. "How will we know we achieved it?"
+- **Not tasks.** KRs measure outcomes, not activities.
+
+**Cascade:** Company OKRs → Department OKRs → Team OKRs → Individual OKRs
+
+**Cadence:** Quarterly OKR cycles. Weekly check-ins. Annual reflection.
+
+**Scoring:** 0.0–1.0. Target is 0.7. Consistently hitting 1.0 = OKRs aren't ambitious enough.
+
+### Strengths
+- **Aligns the whole company.** When done well, every team can trace their work to company-level objectives.
+- **Encourages ambition.** Moonshot OKRs are explicit. "Roofshot" vs "moonshot" OKRs.
+- **Widely understood in tech.** Many hires will already know OKRs.
+- **No framework cost.** No implementer required. Tooling is free or cheap (Linear, Notion, Lattice).
+
+### Limitations
+- **Hard to do well.** Most companies run "OKR theater" — tasks dressed up as key results.
+- **Missing the HOW.** OKRs define what to achieve but not how to operate. You still need meeting rhythm, accountability structure, and issue resolution.
+- **Misalignment risk.** If not cascaded properly, teams run disconnected OKRs that feel like alignment but aren't.
+- **No operational backbone.** OKRs are a goal-setting system, not a full operating system.
+
+### Best fit
+- Tech companies with strong product/engineering culture
+- Companies where hypothesis-driven work is already the norm
+- Organizations that value autonomy and bottom-up goal setting
+- As the goal-setting layer inside a broader operating system
+
+### Not ideal if
+- Teams lack discipline to hold each other accountable
+- You need more than just goal alignment (issue resolution, meeting structure)
+- Leaders don't model OKR behavior themselves
+
+---
+
+## 4. Holacracy
+
+**Book:** *Holacracy* by Brian Robertson
+
+### Core principles
+Holacracy replaces the traditional management hierarchy with a system of distributed authority.
+
+- **Circles:** Semi-autonomous units with defined purposes (like teams, but self-governing)
+- **Roles:** People fill roles (not job descriptions). One person can hold multiple roles in different circles.
+- **Governance meetings:** Roles and accountabilities are defined and evolved by the circle, not management
+- **Tactical meetings:** Operational coordination within circles
+- **The Constitution:** A legal document that all members ratify, replacing traditional management authority
+
+### Strengths
+- **Maximum autonomy.** People closest to the work define how it gets done.
+- **Removes management as a bottleneck.** Decisions happen at the circle level.
+- **Adapts to complexity.** Circle structure evolves organically as the work changes.
+
+### Limitations
+- **Enormous learning curve.** 2–4 years to full adoption. Many companies abandon it.
+- **High meeting overhead.** Governance meetings add significant time.
+- **Doesn't eliminate politics.** Just moves them to governance meetings.
+- **Requires full commitment.** Partial Holacracy doesn't work. You either do it or you don't.
+- **Not for crisis mode.** When speed matters, distributed governance slows you down.
+
+### When it works
+- Organizations with deep belief in autonomy and self-management
+- Non-profit or mission-driven organizations where consensus matters
+- Companies with patient leadership willing to invest years in implementation
+
+### When it doesn't work
+- Startups needing speed and clarity
+- Companies with strong founder personalities who struggle to relinquish control
+- Organizations that need to move fast or course-correct frequently
+
+---
+
+## 5. Custom Hybrid
+
+### When to build a hybrid
+
+None of the above frameworks fits perfectly because:
+- EOS lacks strategic depth
+- Scaling Up is complex to implement
+- OKRs don't provide operational backbone
+- Holacracy is too slow to implement
+
+The solution: take the best components of each.
+
+### Common hybrid patterns
+
+**EOS backbone + OKR goal-setting:**
+- EOS provides: accountability chart, L10 meeting, IDS, meeting pulse
+- OKRs provide: goal-setting with ambition, cascade, and alignment checks
+- Works well for: tech companies that want operational rigor with flexibility
+
+**Scaling Up strategy + EOS execution:**
+- Scaling Up provides: OPSP, 7 strata, cash management
+- EOS provides: L10, rocks, IDS
+- Works well for: ambitious growth companies that want both strategy and execution discipline
+
+**OKRs + custom meeting rhythm:**
+- OKRs provide: goal cascade
+- Custom meetings: weekly team syncs, monthly department reviews, quarterly all-hands
+- Works well for: companies that already have strong culture but need goal alignment
+
+### Hybrid design principles
+
+1. **Pick one goal-setting system.** Don't mix OKRs and Rocks — they're both 90-day priority systems and will create confusion.
+2. **Be explicit about what you're taking from where.** "We use EOS for meetings and Scaling Up for strategy" is a clear hybrid. "We do a bit of everything" is chaos.
+3. **Document your version.** Your operating system should have a name and a one-page description of what it includes.
+4. **Evolve intentionally.** Change one component at a time. Don't overhaul the whole system when one part isn't working.
+
+---
+
+## Framework Selection Decision Tree
+
+```
+Is your company < 50 people and in operational chaos?
+ YES → Start with EOS. It's the simplest path to order.
+ NO → Continue.
+
+Does strategic positioning and cash flow need significant work?
+ YES → Consider Scaling Up.
+ NO → Continue.
+
+Is your company tech-native with strong product/engineering culture?
+ YES → OKR-native with a custom meeting rhythm.
+ NO → Continue.
+
+Do you have 2+ years and full leadership commitment to radical organizational change?
+ YES → Consider Holacracy (with caution).
+ NO → Build a custom hybrid from EOS + OKRs.
+```
diff --git a/skills/c-level-advisor/competitive-intel/SKILL.md b/skills/c-level-advisor/competitive-intel/SKILL.md
new file mode 100644
index 00000000..ef4223d8
--- /dev/null
+++ b/skills/c-level-advisor/competitive-intel/SKILL.md
@@ -0,0 +1,203 @@
+---
+name: "competitive-intel"
+description: "Systematic competitor tracking that feeds CMO positioning, CRO battlecards, and CPO roadmap decisions. Use when analyzing competitors, building sales battlecards, tracking market moves, positioning against alternatives, or when user mentions competitive intelligence, competitive analysis, competitor research, battlecards, win/loss, or market positioning."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: competitive-strategy
+ updated: 2026-03-05
+ frameworks: ci-playbook, battlecard-template
+---
+
+# Competitive Intelligence
+
+Systematic competitor tracking. Not obsession — intelligence that drives real decisions.
+
+## Keywords
+competitive intelligence, competitor analysis, battlecard, win/loss analysis, competitive positioning, competitive tracking, market intelligence, competitor research, SWOT, competitive map, feature gap analysis, competitive strategy
+
+## Quick Start
+
+```
+/ci:landscape — Map your competitive space (direct, indirect, future)
+/ci:battlecard [name] — Build a sales battlecard for a specific competitor
+/ci:winloss — Analyze recent wins and losses by reason
+/ci:update [name] — Track what a competitor did recently
+/ci:map — Build competitive positioning map
+```
+
+## Framework: 5-Layer Intelligence System
+
+### Layer 1: Competitor Identification
+
+**Direct competitors:** Same ICP, same problem, comparable solution, similar price point.
+**Indirect competitors:** Same budget, different solution (including "do nothing" and "build in-house").
+**Future competitors:** Well-funded startups in adjacent space; large incumbents with stated roadmap overlap.
+
+**The 2x2 Threat Matrix:**
+
+| | Same ICP | Different ICP |
+|---|---|---|
+| **Same problem** | Direct threat | Adjacent (watch) |
+| **Different problem** | Displacement risk | Ignore for now |
+
+Update this quarterly. Who's moved quadrants?
+
+### Layer 2: Tracking Dimensions
+
+Track these 8 dimensions per competitor:
+
+| Dimension | Sources | Cadence |
+|-----------|---------|---------|
+| **Product moves** | Changelog, G2/Capterra reviews, Twitter/LinkedIn | Monthly |
+| **Pricing changes** | Pricing page, sales call intel, customer feedback | Triggered |
+| **Funding** | Crunchbase, TechCrunch, LinkedIn | Triggered |
+| **Hiring signals** | LinkedIn job postings, Indeed | Monthly |
+| **Partnerships** | Press releases, co-marketing | Triggered |
+| **Customer wins** | Case studies, review sites, LinkedIn | Monthly |
+| **Customer losses** | Win/loss interviews, churned accounts | Ongoing |
+| **Messaging shifts** | Homepage, ads (Facebook/Google Ad Library) | Quarterly |
+
+### Layer 3: Analysis Frameworks
+
+**SWOT per Competitor:**
+- Strengths: What do they do well? Where do they win?
+- Weaknesses: Where do they lose? What do customers complain about?
+- Opportunities: What could they do that would threaten you?
+- Threats: What's their existential risk?
+
+**Competitive Positioning Map (2 axis):**
+Choose axes that matter for your buyers:
+- Common: Price vs Feature Depth; Enterprise-ready vs SMB-ready; Easy to implement vs Configurable
+- Pick axes that show YOUR differentiation clearly
+
+**Feature Gap Analysis:**
+| Feature | You | Competitor A | Competitor B | Gap status |
+|---------|-----|-------------|-------------|------------|
+| [Feature] | ✅ | ✅ | ❌ | Your advantage |
+| [Feature] | ❌ | ✅ | ✅ | Gap — roadmap? |
+| [Feature] | ✅ | ❌ | ❌ | Moat |
+| [Feature] | ❌ | ❌ | ✅ | Competitor B only |
+
+### Layer 4: Output Formats
+
+**For Sales (CRO):** Battlecards — one page per competitor, designed for pre-call prep.
+See `templates/battlecard-template.md`
+
+**For Marketing (CMO):** Positioning update — message shifts, new differentiators, claims to stop or start making.
+
+**For Product (CPO):** Feature gap summary — what customers ask for that we don't have, what competitors ship, what to reprioritize.
+
+**For CEO/Board:** Monthly competitive summary — 1-page: who moved, what it means, recommended responses.
+
+### Layer 5: Intelligence Cadence
+
+**Monthly (scheduled):**
+- Review all tier-1 competitors (direct threats, top 3)
+- Update battlecards with new intel
+- Publish 1-page summary to leadership
+
+**Triggered (event-based):**
+- Competitor raises funding → assess implications within 48 hours
+- Competitor launches major feature → product + sales response within 1 week
+- Competitor poaches key customer → win/loss interview within 2 weeks
+- Competitor changes pricing → analyze and respond within 1 week
+
+**Quarterly:**
+- Full competitive landscape review
+- Update positioning map
+- Refresh ICP competitive threat assessment
+- Add/remove companies from tracking list
+
+---
+
+## Win/Loss Analysis
+
+This is the highest-signal competitive data you have. Most companies do it too rarely.
+
+**When to interview:**
+- Every lost deal >$50K ACV
+- Every churn >6 months tenure
+- Every competitive win (learn why — it may not be what you think)
+
+**Who conducts it:**
+- NOT the AE who worked the deal (too close, prospect won't be candid)
+- Customer success, product team, or external researcher
+
+**Question structure:**
+1. "Walk me through your evaluation process"
+2. "Who else were you considering?"
+3. "What were the top 3 criteria in your decision?"
+4. "Where did [our product] fall short?"
+5. "What was the deciding factor?"
+6. "What would have changed your decision?"
+
+**Aggregate findings monthly:**
+- Win reasons (rank by frequency)
+- Loss reasons (rank by frequency)
+- Competitor win rates (by competitor, by segment)
+- Patterns over time
+
+---
+
+## The Balance: Intelligence Without Obsession
+
+**Signs you're over-tracking competitors:**
+- Roadmap decisions are primarily driven by "they just shipped X"
+- Team morale drops when competitors fundraise
+- You're shipping features you don't believe in to match their checklist
+- Pricing discussions always start with "well, they charge X"
+
+**Signs you're under-tracking:**
+- Your AEs get blindsided on calls
+- Prospects know more about competitors than your team does
+- You missed a major product launch until customers told you
+- Your positioning hasn't changed in 12+ months despite market moves
+
+**The right posture:**
+- Know competitors well enough to win against them
+- Don't let them set your agenda
+- Your roadmap is led by customer problems, informed by competitive gaps
+
+---
+
+## Distributing Intelligence
+
+| Audience | Format | Cadence | Owner |
+|----------|--------|---------|-------|
+| AEs + SDRs | Updated battlecards in CRM | Monthly + triggered | CRO |
+| Product | Feature gap analysis | Quarterly | CPO |
+| Marketing | Positioning brief | Quarterly | CMO |
+| Leadership | 1-page competitive summary | Monthly | CEO/COO |
+| Board | Competitive landscape slide | Quarterly | CEO |
+
+**One source of truth:** All competitive intel lives in one place (Notion, Confluence, Salesforce). Avoid Slack-only distribution — it disappears.
+
+---
+
+## Red Flags in Competitive Intelligence
+
+| Signal | What it means |
+|--------|---------------|
+| Competitor's win rate >50% in your core segment | Fundamental positioning problem, not sales problem |
+| Same objection from 5+ deals: "competitor has X" | Feature gap that's real, not just optics |
+| Competitor hired 10 engineers in your domain | Major product investment incoming |
+| Competitor raised >$20M and targets your ICP | 12-month runway for them to compete hard |
+| Prospects evaluate you to justify competitor decision | You're the "check box" — fix perception or segment |
+
+## Integration with C-Suite Roles
+
+| Intelligence Type | Feeds To | Output Format |
+|------------------|----------|---------------|
+| Product moves | CPO | Roadmap input, feature gap analysis |
+| Pricing changes | CRO, CFO | Pricing response recommendations |
+| Funding rounds | CEO, CFO | Strategic positioning update |
+| Hiring signals | CHRO, CTO | Talent market intelligence |
+| Customer wins/losses | CRO, CMO | Battlecard updates, positioning shifts |
+| Marketing campaigns | CMO | Counter-positioning, channel intelligence |
+
+## References
+- `references/ci-playbook.md` — OSINT sources, win/loss framework, positioning map construction
+- `templates/battlecard-template.md` — sales battlecard template
diff --git a/skills/c-level-advisor/competitive-intel/references/ci-playbook.md b/skills/c-level-advisor/competitive-intel/references/ci-playbook.md
new file mode 100644
index 00000000..759c9886
--- /dev/null
+++ b/skills/c-level-advisor/competitive-intel/references/ci-playbook.md
@@ -0,0 +1,237 @@
+# Competitive Intelligence Playbook
+
+## OSINT Sources for Competitor Tracking
+
+### Free, Reliable Sources
+
+**Company & Product:**
+- **Their website** — pricing page (archive.org for history), product changelog, careers page
+- **G2 / Capterra / Trustpilot** — customer reviews; filter by recency; read 1-star reviews carefully
+- **LinkedIn** — job postings signal roadmap; company page for headcount trend; employees for leaks
+- **GitHub** — open source activity; what they're building; engineering team size; tech stack
+- **Crunchbase / PitchBook** (free tier) — funding history, investors, team changes
+- **BuiltWith** — tech stack they use; signals about infrastructure maturity
+
+**Messaging & Positioning:**
+- **Facebook Ad Library** — see their current ad copy and creative; what messages they're testing
+- **Google Keyword Planner** — which keywords they're bidding on
+- **SEMrush / Ahrefs** (free trial or limited) — their organic keywords, backlink profile
+- **Wayback Machine** — homepage evolution over time; when positioning shifted
+- **Their blog** — content strategy reveals priorities and ICP assumptions
+
+**News & Events:**
+- **TechCrunch, VentureBeat** — funding announcements, major launches
+- **Twitter/X / LinkedIn** — CEO + founders; direct signals about strategy
+- **Podcast appearances** — founders talk more openly on podcasts than press releases
+- **Job descriptions** — "Senior Engineer - Payments" means they're building payments
+
+### Paid (Worth It for Tier-1 Competitors)
+- **G2 Buyer Intent** — which prospects are researching your competitor right now
+- **Bombora** — intent data for account-level research signals
+- **PitchBook** — funding, investors, valuation estimates
+- **Klue / Crayon / Kompyte** — dedicated CI platforms that aggregate automatically
+
+### Primary Research (Best Signal)
+- **Win/loss interviews** — the single highest-signal source (see below)
+- **Talk to churned customers** — why did they switch? To whom?
+- **Talk to their customers** — LinkedIn outreach; honest conversations
+- **Industry events** — competitor presentations reveal roadmap; talk to attendees
+- **Former employees** — LinkedIn; respectful outreach; no NDA violations
+
+---
+
+## Competitive Battlecard Format
+
+A battlecard is a 1-page (or single screen) document for sales reps to reference before and during calls.
+
+**Design principles:**
+- Written for a rep with 2 minutes to prep, not a product manager
+- Action-oriented: tells reps what to SAY, not just what to know
+- Updated monthly at minimum; never more than 90 days old
+
+### Battlecard Structure
+
+```
+COMPETITOR: [Name]
+Last updated: [Date] | Owner: [Name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+THE 30-SECOND SUMMARY
+[One paragraph. Who they are, who they sell to, why they win.]
+
+THEIR STRENGTHS (know these — don't dismiss them)
+• [Strength 1] — what customers actually love about them
+• [Strength 2]
+• [Strength 3]
+
+THEIR REAL WEAKNESSES (from win/loss data, not assumptions)
+• [Weakness 1] — source: [customer quote / win/loss theme]
+• [Weakness 2]
+• [Weakness 3]
+
+OUR DIFFERENTIATED ADVANTAGES
+• [Advantage 1] — proof point: [metric/customer/case study]
+• [Advantage 2] — proof point:
+• [Advantage 3] — proof point:
+
+COMMON OBJECTIONS + RESPONSES
+"They have [feature] and you don't."
+→ [Response. Acknowledge, reframe, redirect.]
+
+"They're cheaper."
+→ [Response with ROI angle or TCO comparison.]
+
+"They're more established / bigger."
+→ [Response. Size isn't always advantage; use to your benefit.]
+
+TRAP-SETTING QUESTIONS (ask these early to shift the eval criteria)
+• "How important is [your differentiator] to your team?"
+• "Have you looked at [pain point they create]?"
+• "What happens to your workflow when [their known limitation occurs]?"
+
+WHEN WE WIN
+• [Segment or scenario where we almost always beat them]
+• [Use case where we're clearly stronger]
+
+WHEN WE LOSE (be honest)
+• [Scenario where they're genuinely better — don't fight these battles]
+• [Segment where they have structural advantages]
+
+DO NOT SAY
+• Don't claim [X] — it's not true and they'll call it out
+• Don't say [Y] — prospect will already know it and it sounds desperate
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Win/Loss Analysis Framework
+
+### Why Most Companies Do This Wrong
+- They survey instead of interview (surveys get polite answers)
+- The AE conducts it (too emotionally invested; prospect won't be candid)
+- They do it 6 months after the decision (memory fades)
+- They look for confirmation of what they believe
+
+### The Right Process
+
+**Timing:** Within 30 days of deal closed/lost/churned.
+**Interviewer:** Customer success, product, or external researcher. Never the AE.
+**Duration:** 30 minutes (budget 45).
+**Incentive:** $100 gift card gets you 80% acceptance. Worth it.
+
+**Interview Guide:**
+
+*Opening:*
+"I'm [name] from [company]. I'm not in sales — I'm trying to understand what drove your decision so we can improve. There's nothing you can say that will change the outcome. I just want honest feedback."
+
+*Core questions:*
+1. "Can you walk me through your evaluation process from the beginning?"
+2. "Who were the key stakeholders involved in the decision?"
+3. "What were the 3 most important criteria you were evaluating against?"
+4. "Which vendors did you seriously consider?"
+5. "Where did [company] fall short of your expectations?" (For losses)
+ OR "What tipped the decision in [company]'s favor?" (For wins)
+6. "Was price a factor? How significant?"
+7. "What would have had to be different for you to choose [us / the other option]?"
+8. "Any advice for our team on how we handled the process?"
+
+**Data aggregation:**
+- Tag every response: [criterion], [competitor mentioned], [product gap], [sales process], [price], [trust/credibility]
+- Monthly rollup: top 5 win reasons, top 5 loss reasons, competitor win rate
+- Share with: CEO, CRO, CPO, CMO — not just sales
+
+---
+
+## Competitive Positioning Map Construction
+
+A positioning map shows where you sit relative to competitors on 2 dimensions that BUYERS care about.
+
+### Step 1: Choose Your Axes
+- Pick dimensions that actually drive purchase decisions in your segment
+- At least one axis should be where you win
+- Avoid generic axes ("feature-rich vs. simple" tells you nothing)
+
+**Good axis pairs:**
+- Implementation time (days vs. months) × Customization depth
+- Price point × Enterprise readiness
+- Automation level × Human-in-the-loop control
+- Time-to-value × Total cost of ownership
+
+**Bad axes:**
+- Quality (too vague)
+- "Innovation" (unmeasurable)
+- Any axis where all competitors cluster in the same spot
+
+### Step 2: Place Competitors Objectively
+- Use customer quotes and win/loss data to justify placement
+- Don't place competitors where you WANT them — where they ACTUALLY are
+- If you're unsure, ask 5 customers to place them
+
+### Step 3: Find and Name Your White Space
+- Where is there a position no competitor holds?
+- Is that white space there because it's valuable (opportunity) or worthless (avoid)?
+- Can you credibly occupy it?
+
+### Step 4: Test Your Positioning
+- Show the map to 5 prospects: "Does this match your perception?"
+- Show it to 5 lost prospects: "Where would you place [the winner] and us?"
+- Adjust until map matches buyer reality, not internal perception
+
+---
+
+## Intelligence Sharing Across Roles
+
+### What Each Role Needs and When
+
+**CRO (Sales):**
+- Needs: Battlecards, win rates by competitor, competitor objections + responses
+- Cadence: Updated battlecards monthly; triggered updates on major competitor moves
+- Format: 1-pager per competitor in CRM, linked from deal record
+
+**CMO (Marketing):**
+- Needs: Messaging shifts, new claims, ad spend signals, keyword battles
+- Cadence: Quarterly positioning review, triggered on major launches
+- Format: Positioning brief with recommended response to messaging shifts
+
+**CPO (Product):**
+- Needs: Feature gap analysis, competitor roadmap signals (job postings, changelog), what we lose to
+- Cadence: Monthly feature gap update, triggered on major launches
+- Format: Feature comparison matrix + gap prioritization recommendation
+
+**CTO (Engineering):**
+- Needs: Tech stack signals, infrastructure approaches, scale they've achieved
+- Cadence: Quarterly
+- Format: Technical comparison notes, relevant for architectural decisions
+
+**CEO:**
+- Needs: Summary of threat landscape, recommended responses, board-level narrative
+- Cadence: Monthly 1-pager + quarterly deep dive
+- Format: 1-page brief: who moved, what it means, what we do
+
+### The Single Source of Truth Rule
+All competitive intel in one place. Suggest:
+- Notion database per competitor: profile, battlecard, changelog, win/loss notes
+- Slack channel: `#competitive-intel` for real-time triggered alerts
+- Monthly digest email to leadership
+
+If it lives only in Slack, it disappears. If it lives only in a wiki that nobody reads, it doesn't matter. Combine both.
+
+---
+
+## How to Track Without Obsessing
+
+**Set up the system, then let it run:**
+- Google Alerts for competitor names + CEO names
+- LinkedIn Saved Searches for their job postings
+- Klue/Crayon if budget allows (automated aggregation)
+- Monthly 60-minute competitive review meeting (not 4 hours)
+
+**What to do when competitor makes a big move:**
+1. Read the announcement objectively
+2. Talk to 3 customers: "Did you see this? What do you think?"
+3. Assess: does this change any buying criteria in your deals?
+4. If yes: update battlecard and positioning within 1 week
+5. If no: log it, move on
+
+**The test:** After reviewing a competitor move, do you feel urgency to ship something? If yes, you're reacting. The right feeling is "noted — let's see if customers care."
diff --git a/skills/c-level-advisor/competitive-intel/templates/battlecard-template.md b/skills/c-level-advisor/competitive-intel/templates/battlecard-template.md
new file mode 100644
index 00000000..39b0a99e
--- /dev/null
+++ b/skills/c-level-advisor/competitive-intel/templates/battlecard-template.md
@@ -0,0 +1,99 @@
+# Sales Battlecard Template
+
+**COMPETITOR:** [Name]
+**Last updated:** [YYYY-MM-DD] | **Owner:** [Name]
+**Win rate vs this competitor:** [X]% | **Deals tracked:** [N]
+
+---
+
+## 30-Second Summary
+[Who they are. Who they target. Why they win. What they're known for. 3-4 sentences max.]
+
+---
+
+## Their Strengths
+*Know these. Don't dismiss them. Prospects have already heard their pitch.*
+
+- **[Strength]:** [What customers genuinely love; source if available]
+- **[Strength]:** [Specific capability or trait]
+- **[Strength]:** [Brand, market position, or ecosystem advantage]
+
+---
+
+## Their Real Weaknesses
+*From win/loss data only — not wishful thinking.*
+
+- **[Weakness]:** "[Customer quote]" — seen in [N] deals
+- **[Weakness]:** [Documented limitation with evidence]
+- **[Weakness]:** [Implementation, support, or pricing issue]
+
+---
+
+## Our Differentiated Advantages
+*Must be real and provable. Each needs a proof point.*
+
+- **[Advantage]:** [Proof: metric / customer quote / case study]
+- **[Advantage]:** [Proof]
+- **[Advantage]:** [Proof]
+
+---
+
+## Common Objections + Responses
+
+**"They have [feature X] and you don't."**
+> [Acknowledge. Reframe to your strength. Redirect to outcome.
+> "You're right that they have X. What we've found is that customers who care most about X tend to also care about [Y], where we're significantly stronger. Can I show you [specific example]?"]
+
+**"They're cheaper."**
+> [Don't fight on price. Reframe to TCO or ROI.
+> "They are lower in initial cost. Most customers find the total cost over 12 months is actually comparable when you factor in [implementation time / support costs / integrations]. Want to walk through that?"]
+
+**"They've been around longer / they're more established."**
+> [Reframe tenure as potential liability or irrelevance.
+> "Their longevity means they have a lot of technical debt and a big customer base that pulls their roadmap in every direction. Our customers tell us that's exactly why they chose us — we move faster and we're laser-focused on [their specific use case]."]
+
+**"[Competitor] is already used by [big customer they respect]."**
+> [Name-drop your wins in their segment.
+> "We work with [comparable logo]. Want me to connect you with their [role] to ask how they made the decision?"]
+
+---
+
+## Trap-Setting Questions
+*Ask early in discovery to establish criteria that favor you.*
+
+- "How important is [your key differentiator] to your workflow?"
+- "What happens when [their known limitation] occurs? Has that been an issue before?"
+- "How long does your team typically take to onboard a new tool?"
+- "Who manages the integration work — do you have dedicated engineering resources for that?"
+- "What does your current vendor do when you need support?"
+
+---
+
+## When We Win
+- [Scenario or segment where we consistently beat them]
+- [Use case that plays to our strengths]
+- [Buyer profile that prefers us]
+
+## When We Lose (Be Honest)
+- [Scenario where they genuinely win — don't fight here]
+- [Segment where their strengths matter more than ours]
+
+---
+
+## Do NOT Say
+- ❌ Don't claim [X] — it's not accurate and they'll check
+- ❌ Don't attack [Y] — it backfires and makes us look insecure
+- ❌ Don't say "we're better" without specifics — be concrete
+
+---
+
+## Recent Intel
+*Last 90 days only. Older than 90 days: archive.*
+
+- [Date]: [What happened — funding, product launch, pricing change, key hire]
+- [Date]: [Customer feedback from win/loss interview]
+- [Date]: [Any notable market move]
+
+---
+
+*Battlecards are only useful if current. If this is >90 days old, flag to [owner] for update.*
diff --git a/skills/c-level-advisor/context-engine/SKILL.md b/skills/c-level-advisor/context-engine/SKILL.md
new file mode 100644
index 00000000..4d99a510
--- /dev/null
+++ b/skills/c-level-advisor/context-engine/SKILL.md
@@ -0,0 +1,134 @@
+---
+name: "context-engine"
+description: "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: orchestration
+ updated: 2026-03-05
+ frameworks: context-loading, anonymization, context-enrichment
+---
+
+# Company Context Engine
+
+The memory layer for C-suite advisors. Every advisor skill loads this first. Context is what turns generic advice into specific insight.
+
+## Keywords
+company context, context loading, context engine, company profile, advisor context, stale context, context refresh, privacy, anonymization
+
+---
+
+## Load Protocol (Run at Start of Every C-Suite Session)
+
+**Step 1 — Check for context file:** `~/.claude/company-context.md`
+- Exists → proceed to Step 2
+- Missing → prompt: *"Run /cs:setup to build your company context — it makes every advisor conversation significantly more useful."*
+
+**Step 2 — Check staleness:** Read `Last updated` field.
+- **< 90 days:** Load and proceed.
+- **≥ 90 days:** Prompt: *"Your context is [N] days old. Quick 15-min refresh (/cs:update), or continue with what I have?"*
+ - If continue: load with `[STALE — last updated DATE]` noted internally.
+
+**Step 3 — Parse into working memory.** Always active:
+- Company stage (pre-PMF / scaling / optimizing)
+- Founder archetype (product / sales / technical / operator)
+- Current #1 challenge
+- Runway (as risk signal — never share externally)
+- Team size
+- Unfair advantage
+- 12-month target
+
+---
+
+## Context Quality Signals
+
+| Condition | Confidence | Action |
+|-----------|-----------|--------|
+| < 30 days, full interview | High | Use directly |
+| 30–90 days, update done | Medium | Use, flag what may have changed |
+| > 90 days | Low | Flag stale, prompt refresh |
+| Key fields missing | Low | Ask in-session |
+| No file | None | Prompt /cs:setup |
+
+If Low: *"My context is [stale/incomplete] — I'm assuming [X]. Correct me if I'm wrong."*
+
+---
+
+## Context Enrichment
+
+During conversations, you'll learn things not in the file. Capture them.
+
+**Triggers:** New number or timeline revealed, key person mentioned, priority shift, constraint surfaces.
+
+**Protocol:**
+1. Note internally: `[CONTEXT UPDATE: {what was learned}]`
+2. At session end: *"I picked up a few things to add to your context. Want me to update the file?"*
+3. If yes: append to the relevant dimension, update timestamp.
+
+**Never silently overwrite.** Always confirm before modifying the context file.
+
+---
+
+## Privacy Rules
+
+### Never send externally
+- Specific revenue or burn figures
+- Customer names
+- Employee names (unless publicly known)
+- Investor names (unless public)
+- Specific runway months
+- Watch List contents
+
+### Safe to use externally (with anonymization)
+- Stage label
+- Team size ranges (1–10, 10–50, 50–200+)
+- Industry vertical
+- Challenge category
+- Market position descriptor
+
+### Before any external API call or web search
+Apply `references/anonymization-protocol.md`:
+- Numbers → ranges or stage-relative descriptors
+- Names → roles
+- Revenue → percentages or stage labels
+- Customers → "Customer A, B, C"
+
+---
+
+## Missing or Partial Context
+
+Handle gracefully — never block the conversation.
+
+- **Missing stage:** "Just to calibrate — are you still finding PMF or scaling what works?"
+- **Missing financials:** Use stage + team size to infer. Note the gap.
+- **Missing founder profile:** Infer from conversation style. Mark as inferred.
+- **Multiple founders:** Context reflects the interviewee. Note co-founder perspective may differ.
+
+---
+
+## Required Context Fields
+
+```
+Required:
+ - Last updated (date)
+ - Company Identity → What we do
+ - Stage & Scale → Stage
+ - Founder Profile → Founder archetype
+ - Current Challenges → Priority #1
+ - Goals & Ambition → 12-month target
+
+High-value optional:
+ - Unfair advantage
+ - Kill-shot risk
+ - Avoided decision
+ - Watch list
+```
+
+Missing required fields: note gaps, work around in session, ask in-session only when critical.
+
+---
+
+## References
+- `references/anonymization-protocol.md` — detailed rules for stripping sensitive data before external calls
diff --git a/skills/c-level-advisor/context-engine/references/anonymization-protocol.md b/skills/c-level-advisor/context-engine/references/anonymization-protocol.md
new file mode 100644
index 00000000..e020be35
--- /dev/null
+++ b/skills/c-level-advisor/context-engine/references/anonymization-protocol.md
@@ -0,0 +1,173 @@
+# Anonymization Protocol
+
+Rules for stripping sensitive company data before any external API call, web search, or tool invocation that sends data outside the local environment.
+
+---
+
+## When This Protocol Applies
+
+**Trigger:** Any time company context or conversation content will leave the local session.
+
+Examples:
+- Web search that includes company specifics
+- External API call with company data in the payload
+- Any tool call where conversation content is part of the request
+
+**Does NOT apply to:**
+- Local file reads/writes (`~/.claude/company-context.md`)
+- In-session reasoning and analysis
+- Generating advice or documents that stay local
+
+---
+
+## Rule 1: Financial Figures → Relative Ranges
+
+Never send specific financial data externally.
+
+| Raw data | Anonymized version |
+|----------|-------------------|
+| "$2.4M ARR" | "early-stage ARR (sub-$5M)" |
+| "$180K MRR" | "growing MRR, Series A range" |
+| "14 months runway" | "runway is healthy for stage" |
+| "burn rate is $320K/month" | "burn rate is moderate for stage" |
+| "raised $8M Series A" | "Series A company" |
+| "customer LTV is $4,200" | "LTV is above industry average for segment" |
+| "CAC is $680" | "CAC is in a sustainable range" |
+
+**Rule:** No dollar amounts. No month counts for runway. Use stage-relative descriptors.
+
+---
+
+## Rule 2: Customer Names → Anonymized Labels
+
+Never send customer or client names externally.
+
+| Raw data | Anonymized version |
+|----------|-------------------|
+| "Acme Corp is our biggest customer" | "Customer A (largest account)" |
+| "we're working with NHS England" | "a large public-sector customer" |
+| "BMW, Volkswagen, and Stellantis" | "three major automotive OEMs" |
+| "10 enterprise customers including..." | "10 enterprise customers" |
+
+**Rule:** Use "Customer A/B/C" for named accounts, or describe by segment without naming.
+
+---
+
+## Rule 3: Revenue Figures → Percentage Changes or Stage Descriptors
+
+Revenue trajectory is safer than absolute numbers.
+
+| Raw data | Anonymized version |
+|----------|-------------------|
+| "growing from $1M to $2M ARR" | "2x revenue growth year-over-year" |
+| "revenue dropped from $500K to $430K" | "revenue declined ~15% in the period" |
+| "hit $10M ARR last quarter" | "crossed a significant ARR milestone" |
+| "doing $50K MRR" | "pre-Series A revenue, strong growth trajectory" |
+
+**Rule:** Percentages and directional signals (growing / declining / flat) are safe. Absolutes are not.
+
+---
+
+## Rule 4: Employee Names → Roles Only
+
+Never send individual names externally.
+
+| Raw data | Anonymized version |
+|----------|-------------------|
+| "Our CTO, Sarah Chen, is struggling" | "our CTO is struggling with the transition" |
+| "James is the best performer on the team" | "our strongest performer is in the engineering lead role" |
+| "we're about to let go of Michael" | "we're about to make a leadership change" |
+| "the founding team is me, Alex, and Priya" | "a three-person founding team" |
+
+**Exception:** Publicly known executives (CEO of a public company, named in press releases) can be referenced by name. If in doubt, use role.
+
+---
+
+## Rule 5: Investor Names → Generic Descriptors
+
+| Raw data | Anonymized version |
+|----------|-------------------|
+| "Sequoia led our round" | "a top-tier VC led our round" |
+| "our lead investor is pushing for an exit" | "pressure from investors toward exit" |
+| "Y Combinator alumni" | "accelerator alumni" |
+
+**Exception:** YC, Techstars, and similar well-known accelerators are commonly referenced and safe if the founder has publicly disclosed. When in doubt, omit.
+
+---
+
+## Rule 6: Location → Country or Region
+
+| Raw data | Anonymized version |
+|----------|-------------------|
+| "Berlin-based startup" | "European startup" |
+| "we're in San Francisco" | "US-based startup" |
+| "expanding to Munich and Vienna" | "expanding in the DACH region" |
+
+**Exception:** Location is less sensitive than financials. Use judgment — if it's on their website, it's fine.
+
+---
+
+## Anonymization Decision Tree
+
+```
+Before sending data externally:
+
+1. Does it include a specific dollar amount?
+ → YES: Replace with range or relative descriptor
+
+2. Does it include a person's name?
+ → YES: Replace with role only (unless publicly known)
+
+3. Does it include a company or customer name?
+ → YES: Replace with "Customer A" or segment descriptor
+
+4. Does it include specific headcount or runway months?
+ → YES: Replace with range (1–10, 10–50) or "healthy/tight/critical"
+
+5. Does it include proprietary data, roadmap, or unreleased product info?
+ → YES: Do not include. Reference only generically ("product expansion planned")
+
+6. Is it publicly available information?
+ → YES: Safe to send as-is
+```
+
+---
+
+## Required vs Optional Anonymization
+
+### Required (always strip before external calls)
+- Revenue figures (absolute)
+- Burn rate (absolute)
+- Runway (specific months)
+- Customer names
+- Employee names
+- Investor names (unless public)
+- Funding amounts (unless public)
+
+### Optional (use judgment based on sensitivity)
+- Industry vertical (usually fine)
+- Company stage (usually fine)
+- Team size ranges (usually fine)
+- Geographic region (usually fine)
+- General challenge category (usually fine)
+
+---
+
+## What to Do If You're Unsure
+
+Default to stricter anonymization. The cost of over-anonymizing is slightly less useful external results. The cost of under-anonymizing is a privacy breach.
+
+When in doubt: **remove it**.
+
+---
+
+## Audit Log (Internal Only)
+
+When running external calls with company context, note internally:
+```
+[EXTERNAL CALL: {tool/API used}]
+[ANONYMIZED: {fields stripped}]
+[RETAINED: {fields kept and why}]
+```
+
+This is for internal reasoning only — never included in output to the founder.
diff --git a/skills/c-level-advisor/coo-advisor/SKILL.md b/skills/c-level-advisor/coo-advisor/SKILL.md
new file mode 100644
index 00000000..26d76131
--- /dev/null
+++ b/skills/c-level-advisor/coo-advisor/SKILL.md
@@ -0,0 +1,137 @@
+---
+name: "coo-advisor"
+description: "Operations leadership for scaling companies. Process design, OKR execution, operational cadence, and scaling playbooks. Use when designing operations, setting up OKRs, building processes, scaling teams, analyzing bottlenecks, planning operational cadence, or when user mentions COO, operations, process improvement, OKRs, scaling, operational efficiency, or execution."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: coo-leadership
+ updated: 2026-03-05
+ python-tools: ops_efficiency_analyzer.py, okr_tracker.py
+ frameworks: scaling-playbook, ops-cadence, process-frameworks
+---
+
+# COO Advisor
+
+Operational frameworks and tools for turning strategy into execution, scaling processes, and building the organizational engine.
+
+## Keywords
+COO, chief operating officer, operations, operational excellence, process improvement, OKRs, objectives and key results, scaling, operational efficiency, execution, bottleneck analysis, process design, operational cadence, meeting cadence, org scaling, lean operations, continuous improvement
+
+## Quick Start
+
+```bash
+python scripts/ops_efficiency_analyzer.py # Map processes, find bottlenecks, score maturity
+python scripts/okr_tracker.py # Cascade OKRs, track progress, flag at-risk items
+```
+
+## Core Responsibilities
+
+### 1. Strategy Execution
+The CEO sets direction. The COO makes it happen. Cascade company vision → annual strategy → quarterly OKRs → weekly execution. See `references/ops_cadence.md` for full OKR cascade framework.
+
+### 2. Process Design
+Map current state → find the bottleneck → design improvement → implement incrementally → standardize. See `references/process_frameworks.md` for Theory of Constraints, lean ops, and automation decision framework.
+
+**Process Maturity Scale:**
+| Level | Name | Signal |
+|-------|------|--------|
+| 1 | Ad hoc | Different every time |
+| 2 | Defined | Written but not followed |
+| 3 | Measured | KPIs tracked |
+| 4 | Managed | Data-driven improvement |
+| 5 | Optimized | Continuous improvement loops |
+
+### 3. Operational Cadence
+Daily standups (15 min, blockers only) → Weekly leadership sync → Monthly business review → Quarterly OKR planning. See `references/ops_cadence.md` for full templates.
+
+### 4. Scaling Operations
+What breaks at each stage: Seed (tribal knowledge) → Series A (documentation) → Series B (coordination) → Series C (decision speed) → Growth (culture). See `references/scaling_playbook.md` for detailed playbook per stage.
+
+### 5. Cross-Functional Coordination
+RACI for key decisions. Escalation framework: Team lead → Dept head → COO → CEO based on impact scope.
+
+## Key Questions a COO Asks
+
+- "What's the bottleneck? Not what's annoying — what limits throughput."
+- "How many manual steps? Which break at 3x volume?"
+- "Who's the single point of failure?"
+- "Can every team articulate how their work connects to company goals?"
+- "The same blocker appeared 3 weeks in a row. Why isn't it fixed?"
+
+## Operational Metrics
+
+| Category | Metric | Target |
+|----------|--------|--------|
+| Execution | OKR progress (% on track) | > 70% |
+| Execution | Quarterly goals hit rate | > 80% |
+| Speed | Decision cycle time | < 48 hours |
+| Quality | Customer-facing incidents | < 2/month |
+| Efficiency | Revenue per employee | Track trend |
+| Efficiency | Burn multiple | < 2x |
+| People | Regrettable attrition | < 10% |
+
+## Red Flags
+
+- OKRs consistently 1.0 (not ambitious) or < 0.3 (disconnected from reality)
+- Teams can't explain how their work maps to company goals
+- Leadership meetings produce no action items two weeks running
+- Same blocker in three consecutive syncs
+- Process exists but nobody follows it
+- Departments optimize local metrics at expense of company metrics
+
+## Integration with Other C-Suite Roles
+
+| When... | COO works with... | To... |
+|---------|-------------------|-------|
+| Strategy shifts | CEO | Translate direction into ops plan |
+| Roadmap changes | CPO + CTO | Assess operational impact |
+| Revenue targets change | CRO | Adjust capacity planning |
+| Budget constraints | CFO | Find efficiency gains |
+| Hiring plans | CHRO | Align headcount with ops needs |
+| Security incidents | CISO | Coordinate response |
+
+## Detailed References
+- `references/scaling_playbook.md` — what changes at each growth stage
+- `references/ops_cadence.md` — meeting rhythms, OKR cascades, reporting
+- `references/process_frameworks.md` — lean ops, TOC, automation decisions
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Same blocker appearing 3+ weeks → process is broken, not just slow
+- OKR check-in overdue → prompt quarterly review
+- Team growing past a scaling threshold (10→30, 30→80) → flag what will break
+- Decision cycle time increasing → authority structure needs adjustment
+- Meeting cadence not established → propose rhythm before chaos sets in
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Set up OKRs" | Cascaded OKR framework (company → dept → team) |
+| "We're scaling fast" | Scaling readiness report with what breaks next |
+| "Our process is broken" | Process map with bottleneck identified + fix plan |
+| "How efficient are we?" | Ops efficiency scorecard with maturity ratings |
+| "Design our meeting cadence" | Full cadence template (daily → quarterly) |
+
+## Reasoning Technique: Step by Step
+
+Map processes sequentially. Identify each step, handoff, and decision point. Find the bottleneck using throughput analysis. Propose improvements one step at a time.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/c-level-advisor/coo-advisor/references/ops_cadence.md b/skills/c-level-advisor/coo-advisor/references/ops_cadence.md
new file mode 100644
index 00000000..f543bc74
--- /dev/null
+++ b/skills/c-level-advisor/coo-advisor/references/ops_cadence.md
@@ -0,0 +1,606 @@
+# Operational Cadence: Meetings, Async, Decisions, and Reporting
+
+> The rhythm of your company determines its output. Bad cadence = constant context-switching, decisions made without information, and a leadership team that's always reactive.
+
+---
+
+## Philosophy
+
+**Meetings are a tax.** Every hour in a meeting is an hour not spent building, selling, or serving customers. A good cadence minimizes meeting time while ensuring the right people have the right information at the right time.
+
+**Async is default, sync is exception.** Most information sharing and routine updates should happen in writing. Reserve synchronous time for things that genuinely require real-time discussion: decisions with significant disagreement, complex problem-solving, relationship-building.
+
+**Cadence serves strategy.** The calendar reflects priorities. If you're doing monthly all-hands but weekly status updates, you've inverted the importance.
+
+---
+
+## Meeting Cadence Templates
+
+### Daily Operations
+
+#### Daily Standup (Engineering / Product Teams)
+**Format:** Async-first (Slack/Loom); sync only if blocked
+**Sync duration:** 15 minutes max
+**Participants:** Team (5–10 people)
+**Facilitator:** Team lead or rotating
+
+```
+ASYNC FORMAT (post in #standup channel):
+Yesterday: [What I completed]
+Today: [What I'm working on]
+Blocked: [Anything blocking me — tag the person who can unblock]
+```
+
+**Rules:**
+- No status reporting in sync standup if everyone can read the async update
+- Standups are not problem-solving sessions — take issues offline
+- Skip standup if the team has a full-team session that day
+- Kill standup if the team consistently has nothing blocked; replace with async
+
+#### Daily Leadership Check-in (COO)
+**Format:** Async only — read, don't meet
+**Time:** 8:00–8:30 AM
+
+**COO morning read:**
+1. Yesterday's key metrics dashboard (5 min)
+2. Overnight Slack/email escalations (5 min)
+3. Today's decisions needed list (5 min)
+4. Any P0/P1 incidents (check status page + on-call logs)
+
+---
+
+### Weekly Cadence
+
+#### Leadership Sync (Weekly)
+**Duration:** 60–90 minutes
+**Participants:** C-suite + VP level
+**Owner:** COO (or CEO)
+**Day/Time:** Monday or Tuesday, morning
+
+```
+AGENDA TEMPLATE:
+00:00–10:00 Metrics pulse (pre-read required — no presenting charts)
+ - Revenue: ACV, pipeline, churn delta
+ - Product: shipped last week, blockers this week
+ - Engineering: incidents, velocity
+ - CS: escalations, NPS delta
+ - People: open reqs, attrition flag
+
+10:00–45:00 Priority items (submitted in advance, max 3)
+ - Item 1: [Owner: Name] [Decision needed / FYI / Input needed]
+ - Item 2: [Owner: Name]
+ - Item 3: [Owner: Name]
+
+45:00–60:00 Parking lot / open
+ - Anything not covered
+ - Next week flagging
+```
+
+**Pre-meeting requirements:**
+- Metrics dashboard updated by EOD Friday
+- Priority items submitted by Sunday 6 PM
+- Anyone who hasn't read the pre-read gets no floor time
+
+**Output:** Decision log updated with outcomes, action items assigned in tracking system
+
+#### 1:1 (Manager ↔ Direct Report)
+**Duration:** 30–45 minutes
+**Frequency:** Weekly (skip-levels: bi-weekly)
+**Owner:** Report (the direct report sets agenda)
+
+```
+1:1 STRUCTURE:
+[5 min] What's on your mind / temperature check
+[15 min] Their agenda — what they want to discuss
+[10 min] Manager agenda — feedback, context, decisions
+[5 min] Action items review from last week
+```
+
+**1:1 anti-patterns to eliminate:**
+- Using 1:1 for status updates (that's what standups are for)
+- Manager dominating the agenda
+- Skipping because "things are fine"
+- No written record of what was discussed
+
+**Private 1:1 doc:** Every manager/report pair maintains a shared doc with running notes, action items, and career development thread.
+
+#### Cross-Functional Weekly Sync
+**Duration:** 45 minutes
+**Participants:** 2–4 team leads with shared dependencies
+**Examples:** Product + Engineering, Sales + CS, Marketing + Sales
+
+```
+AGENDA:
+00–10 Shared metrics (things both teams care about)
+10–30 Active collaboration items — what needs coordination this week
+30–40 Blockers + dependencies (what do I need from your team?)
+40–45 Upcoming: what's coming that the other team should know about
+```
+
+---
+
+### Monthly Cadence
+
+#### All-Hands / Town Hall
+**Duration:** 60–90 minutes
+**Participants:** Entire company
+**Owner:** CEO + functional heads
+**Format:** In-person preferred; video if distributed
+
+```
+ALL-HANDS AGENDA (60 min version):
+00–05 Opening — CEO sets the tone
+05–20 Business update
+ - Where we are vs. plan (actuals vs. budget)
+ - Key wins and learning moments from last month
+ - What we're focused on this month
+20–40 Functional spotlights (2 functions, 10 min each)
+ - What we shipped / what we did
+ - What we learned
+ - What's next
+40–55 Open Q&A (no screened questions — take everything)
+55–60 Closing
+
+ALL-HANDS PREP CHECKLIST:
+□ CEO talking points reviewed 48h in advance
+□ Metrics slides reviewed by Finance for accuracy
+□ Q&A prep — leadership team briefs on likely questions
+□ Recording setup confirmed
+□ Async option for timezones (recording posted within 2h)
+□ Action items from Q&A captured and published within 24h
+```
+
+#### Monthly Business Review (MBR)
+**Duration:** 2 hours
+**Participants:** Leadership team
+**Owner:** COO
+
+```
+MBR AGENDA:
+00–20 Financial review (Finance presents)
+ - Revenue vs. plan, by segment
+ - Burn rate, runway
+ - Headcount actual vs. plan
+ - Key cost drivers
+
+20–60 Functional reviews (each VP, 8 min each)
+ Standard template per function:
+ - Metrics: [3 key metrics vs. prior month vs. plan]
+ - Wins: [top 2-3 wins]
+ - Gaps: [where we missed and why]
+ - Next 30 days: [top 3 priorities]
+
+60–90 Strategic topics (pre-submitted)
+ - Items requiring cross-functional decision
+ - Risks or issues needing leadership visibility
+
+90–110 Decisions and action items
+ - Document decisions made
+ - Assign owners and deadlines
+
+110–120 Retrospective
+ - What's working in how we operate?
+ - What needs to change?
+```
+
+**MBR pre-read package** (published 48h before):
+- Financial summary (1 page)
+- Each function's 1-pager (see template below)
+
+```
+FUNCTIONAL 1-PAGER TEMPLATE:
+Function: [Name] Month: [Month Year]
+Owner: [VP Name]
+
+TOP METRICS:
+| Metric | Target | Actual | vs. LM | vs. Plan |
+|--------|--------|--------|--------|----------|
+| [M1] | | | | |
+| [M2] | | | | |
+| [M3] | | | | |
+
+WINS (2-3 bullets):
+•
+•
+
+GAPS (be honest — no spin):
+•
+•
+
+DEPENDENCIES (what I need from other teams):
+•
+
+NEXT 30 DAYS (top 3 priorities):
+1.
+2.
+3.
+```
+
+---
+
+### Quarterly Cadence
+
+#### Quarterly Business Review (QBR)
+**Duration:** Half day (4 hours)
+**Participants:** Leadership team + key functional leads
+**Owner:** CEO + COO
+
+```
+QBR AGENDA (4 hours):
+PART 1: Look back (90 min)
+ - CEO: Business context and narrative (15 min)
+ - Finance: Full quarter P&L review (20 min)
+ - Each function: 10-min review against OKRs
+ Format: Hit/Miss/Partial for each objective + root cause
+
+PART 2: Look forward (90 min)
+ - Product/Engineering: What ships next quarter (20 min)
+ - Sales/Marketing: Pipeline and demand plan (20 min)
+ - People: Headcount plan and key hires (15 min)
+ - Finance: Budget and forecast (20 min)
+ - Cross-functional dependencies (15 min)
+
+PART 3: Strategic discussion (60 min)
+ - 1–2 strategic topics requiring deep discussion
+ - Pre-submitted and pre-read
+
+PART 4: OKR setting for next quarter (30 min)
+ - Draft OKRs reviewed and challenged
+ - Final OKRs locked or assigned for next week finalization
+```
+
+#### Quarterly Leadership Off-site
+**Duration:** 1–2 days (Series B+)
+**Participants:** C-suite + VPs
+**Purpose:** Strategy alignment, relationship building, hard conversations
+
+**Off-site agenda principles:**
+- No laptops during sessions (phones away)
+- At least 50% discussion, max 50% presentation
+- Include one session on how the leadership team is functioning (not just what the business is doing)
+- Output: 1-page summary of decisions and commitments shared with the company
+
+---
+
+### Annual Cadence
+
+#### Annual Planning Cycle
+**Timeline:** Start 8–10 weeks before fiscal year end
+
+```
+ANNUAL PLANNING TIMELINE:
+Week -10: Company strategic priorities draft (CEO + COO)
+Week -8: Revenue model + market analysis (Finance + Sales)
+Week -7: Functional goal-setting begins
+Week -6: Headcount planning by function
+Week -5: Draft plans reviewed by COO
+Week -4: Cross-functional dependency alignment
+Week -3: Budget finalization
+Week -2: Board review (if applicable)
+Week -1: Final company OKRs published
+Week 0: Year kick-off all-hands
+```
+
+#### Year Kick-off All-Hands
+**Duration:** 2–4 hours
+**Participants:** Entire company
+**Purpose:** Align entire company on year strategy and goals
+
+```
+KICK-OFF AGENDA:
+- Last year retrospective: What we accomplished, what we learned
+- Market context: Why now, why us
+- Year strategy: The 2-3 things that matter most
+- OKRs: Company-level goals, each function's goals
+- Culture: How we'll work together
+- Q&A: Open and honest
+```
+
+---
+
+## Async Communication Frameworks
+
+### The Writing-First Culture
+
+All communication defaults to written unless real-time is genuinely necessary. This is how you scale decision-making without scaling meetings.
+
+**Written first means:**
+- Decisions are documented before they're communicated
+- Updates are published before questions are asked
+- Problems are described before solutions are proposed
+
+### Slack Channel Architecture
+
+```
+REQUIRED CHANNELS:
+#announcements Read-only. Major company announcements only.
+#general Company-wide conversation
+#leadership-public Leadership decisions visible to all (transparency)
+#incidents P0/P1 incidents only. Auto-resolved when incident is closed.
+#metrics Automated metric updates. No discussion here.
+#wins Customer wins, team wins. Culture channel.
+
+FUNCTIONAL CHANNELS:
+#engineering, #product, #sales, #marketing, #cs, #people, #finance
+
+PROJECT CHANNELS:
+#proj-[name] Temporary. Archive when project ships.
+
+DECISION CHANNELS:
+#decisions All cross-team decisions logged here with context
+```
+
+**Anti-patterns to eliminate:**
+- DMs for work decisions (decisions belong in channels, visible to team)
+- @channel abuse (train people — this means everyone stops what they're doing)
+- Thread avoidance (all replies go in threads, period)
+- Multiple channels for same function (merge aggressively)
+
+### Async Decision Template
+
+When a decision needs input but doesn't require a meeting:
+
+```
+DECISION REQUEST (post in #decisions):
+
+**Context:** [1-3 sentences on why this decision is needed]
+
+**Options considered:**
+A) [Option A] — Pros: X. Cons: Y.
+B) [Option B] — Pros: X. Cons: Y.
+
+**Recommendation:** [Your recommendation and why]
+
+**Input needed from:** @person1, @person2 (tag specific people)
+
+**Decide by:** [Date/Time — give at least 24 hours]
+
+**If no response:** [Default action if no input received]
+```
+
+### Loom / Video for Async Communication
+
+Use async video for:
+- Explaining complex technical architecture
+- Walking through a design or document with context
+- Giving feedback that needs tone/nuance
+- Team updates that would otherwise be a meeting
+
+**Loom best practices:**
+- Keep under 5 minutes; break up anything longer
+- Always include a summary comment with key points
+- Ask viewers to leave timestamp comments for specific questions
+
+---
+
+## Decision-Making Frameworks
+
+### RAPID
+
+The most practical decision-making framework for startups scaling to enterprises.
+
+| Role | Meaning | Responsibility |
+|------|---------|---------------|
+| **R** — Recommend | Proposes decision with analysis | Does the work, gathers input, makes recommendation |
+| **A** — Agree | Must agree before decision is final | Has veto power; should be used sparingly |
+| **P** — Perform | Executes the decision | Consulted during recommendation phase |
+| **I** — Input | Consulted for perspective | Shares point of view; not binding |
+| **D** — Decide | Makes the final call | One person only — groups don't decide |
+
+**How to use RAPID:**
+1. For every significant decision, explicitly assign R, A, P, I, D before work begins
+2. The D role is always one person — never a committee
+3. Agree (A) roles should be limited to 2–3 people maximum; more = paralysis
+4. Post the RAPID in the decision doc so everyone knows the structure
+
+**Example application:**
+```
+Decision: Migrate from PostgreSQL to distributed database
+R: VP Engineering
+A: CTO, COO (for cost implications)
+P: Infrastructure team
+I: Product leads, Finance
+D: CTO
+```
+
+### RACI
+
+Better for ongoing processes than one-time decisions. Use RACI for recurring operational responsibilities.
+
+| Role | Meaning |
+|------|---------|
+| **R** — Responsible | Does the work |
+| **A** — Accountable | Owns the outcome; one person only |
+| **C** — Consulted | Input before decisions/actions |
+| **I** — Informed | Told of decisions/actions after the fact |
+
+**RACI matrix template:**
+
+```
+PROCESS: Customer Escalation Handling
+
+Task | CS Lead | VP CS | Eng Lead | CEO
+------------------------|---------|-------|----------|----
+Receive escalation | R | I | I | -
+Diagnose issue | R | C | C | -
+Communicate to customer | R | A | - | I (major)
+Resolve technical issue | C | - | R | -
+Close escalation | R | A | I | -
+Post-mortem (P0/P1) | C | A | R | I
+```
+
+**Common RACI mistakes:**
+- Multiple A roles (breaks accountability)
+- R and A always same person (defeats the purpose)
+- Too many C roles (everyone's consulted, nothing moves)
+- Not distinguishing C from I (different obligations)
+
+### DRI (Directly Responsible Individual)
+
+Apple's framework; used widely in fast-moving tech companies. Simpler than RAPID/RACI for internal use.
+
+**The rule:** Every project, deliverable, and decision has exactly one DRI. The DRI is the person who gets credit when it succeeds and gets called on when it fails. No DRI = no accountability.
+
+**DRI requirements:**
+- Listed by name in every project brief
+- Has authority to make decisions within scope
+- Is responsible for communicating status
+- Cannot blame lack of resources — their job is to escalate when blocked
+
+**DRI vs. RACI:** Use DRI for project ownership and RACI for process ownership. They complement each other.
+
+### Decision Log
+
+Every significant decision gets logged. Significant = affects more than one team, costs more than $10K, or is difficult to reverse.
+
+```
+DECISION LOG FORMAT:
+
+Date: [YYYY-MM-DD]
+Decision: [One sentence summary]
+Context: [Why was this decision needed? What was the situation?]
+Options considered: [What alternatives were evaluated?]
+Decision made: [What was decided?]
+Rationale: [Why this option?]
+Owner: [Who made the final call?]
+Reversible: [Yes / No / Partially]
+Review date: [When should this decision be revisited?]
+Outcome: [Filled in later — what actually happened?]
+```
+
+---
+
+## Reporting Templates
+
+### Weekly CEO/COO Dashboard
+
+```
+COMPANY HEALTH — WEEK OF [DATE]
+
+REVENUE
+ ARR: $[X]M (vs. plan: +/-X%, vs. LW: +/-X%)
+ New ARR this week: $[X]K
+ Churned ARR: $[X]K
+ Pipeline (90-day): $[X]M
+
+PRODUCT
+ Shipped this week: [Brief list]
+ P0/P1 incidents: [Count] — [1-line summary if any]
+ Deploy frequency: [X per week]
+
+CUSTOMER
+ Active customers: [X]
+ NPS (rolling 30d): [X]
+ Open escalations: [X] (P0: [X], P1: [X])
+
+PEOPLE
+ Headcount: [X] (vs. plan: [X])
+ Open reqs: [X]
+ Attrition (30d): [X]
+
+CASH
+ Cash on hand: $[X]M
+ Burn (last 30d): $[X]M
+ Runway: [X] months
+
+🔴 ISSUES (needs leadership attention):
+ •
+ •
+
+🟡 WATCH (monitor, no action yet):
+ •
+
+🟢 WINS:
+ •
+```
+
+### Monthly Investor/Board Update
+
+```
+[COMPANY NAME] — MONTHLY UPDATE — [MONTH YEAR]
+
+THE HEADLINE
+[2-3 sentences: what was the defining story of this month?]
+
+KEY METRICS
+| Metric | [Month] | vs. Prior | vs. Plan |
+|--------|---------|-----------|----------|
+| ARR | | | |
+| MRR Added | | | |
+| Churn | | | |
+| NRR | | | |
+| Burn | | | |
+| Runway | | | |
+
+WINS
+1. [Specific, concrete win with numbers]
+2. [Second win]
+3. [Third win]
+
+CHALLENGES
+1. [Honest description of challenge + what you're doing about it]
+2. [Second challenge]
+
+KEY DECISIONS MADE
+• [Decision + brief rationale]
+
+ASKS FROM INVESTORS
+• [Specific ask with context — intros, advice, etc.]
+
+NEXT MONTH PRIORITIES
+1.
+2.
+3.
+```
+
+### Quarterly OKR Progress Report
+
+```
+Q[X] OKR PROGRESS — [COMPANY NAME]
+
+SCORING GUIDE:
+🟢 On track (>70% confidence of hitting target)
+🟡 At risk (50-70% confidence)
+🔴 Off track (<50% confidence)
+
+COMPANY OBJECTIVES:
+
+O1: [Objective title]
+ KR1.1: [Key Result] ............... [X]% 🟢
+ KR1.2: [Key Result] ............... [X]% 🟡
+ Objective confidence: 🟢 | Notes: [1 line]
+
+O2: [Objective title]
+ KR2.1: [Key Result] ............... [X]% 🔴
+ KR2.2: [Key Result] ............... [X]% 🟢
+ Objective confidence: 🟡 | Notes: [1 line]
+
+FUNCTIONAL OBJECTIVES:
+[Same format per function]
+
+OVERALL QUARTER HEALTH: 🟡
+Summary: [2-3 sentences on overall trajectory]
+
+TOP 3 ACTIONS TO GET BACK ON TRACK:
+1. [Action + owner + deadline]
+2.
+3.
+```
+
+---
+
+## Cadence Anti-Patterns to Eliminate
+
+| Anti-Pattern | What It Looks Like | Fix |
+|---|---|---|
+| **Meeting creep** | Calendar blocks added over time, never removed | Quarterly calendar audit — delete all recurring meetings, re-add only what's essential |
+| **Update theater** | Meetings where people read from slides | Require pre-reads; ban in-meeting presentations |
+| **Decision avoidance** | Topics recur across multiple meetings | Assign a D (decider) before the meeting. If no D, don't hold the meeting. |
+| **Sync for async** | Using meetings for information sharing | Move updates to Loom/Slack; protect sync time for discussion |
+| **HIPPO problem** | Highest-paid person in room wins | Structure discussions so data is presented before opinions |
+| **Retrospective theater** | Retros with no action items | Every retro must produce ≥1 committed change |
+| **Silent agenda** | Agenda not shared until meeting starts | Agendas published 24h in advance, required reading |
+
+---
+
+*Cadence framework synthesized from Amazon's PR/FAQ culture, Google's OKR playbook, GitLab's remote work handbook, and operational patterns from 50+ Series A–C companies.*
diff --git a/skills/c-level-advisor/coo-advisor/references/process_frameworks.md b/skills/c-level-advisor/coo-advisor/references/process_frameworks.md
new file mode 100644
index 00000000..5e799bf7
--- /dev/null
+++ b/skills/c-level-advisor/coo-advisor/references/process_frameworks.md
@@ -0,0 +1,459 @@
+# Process Frameworks for Startup Operations
+
+> Theory of Constraints, Lean, process mapping, automation, and change management — applied to real startup contexts, not factory floors.
+
+---
+
+## Part 1: Theory of Constraints (TOC) Applied to Startups
+
+### What TOC Actually Says
+
+Eliyahu Goldratt's core insight: **every system has exactly one constraint that limits throughput.** Improving anything other than the constraint is waste. The goal isn't to optimize every function — it's to identify the single bottleneck and exploit it until a new constraint emerges.
+
+**The Five Focusing Steps:**
+1. **Identify** the constraint — what limits the system's output?
+2. **Exploit** it — get maximum output from the constraint without adding resources
+3. **Subordinate** everything else — other activities serve the constraint's needs
+4. **Elevate** it — add resources to increase constraint capacity
+5. **Repeat** — when the constraint moves, find the new one
+
+### Finding the Constraint in Your Startup
+
+The constraint is almost never where people think it is. Sales thinks it's Marketing. Engineering thinks it's Product. Everyone thinks it's someone else.
+
+**Method:** Map your value stream (see Part 3), measure throughput at each step, find the step with the lowest throughput or the highest queue in front of it.
+
+**Common startup constraints by stage:**
+
+| Stage | Most Common Constraint | Why |
+|-------|----------------------|-----|
+| Pre-PMF | Learning speed | Not enough customer feedback cycles |
+| Series A | Sales capacity | Demand > sales team's ability to close |
+| Series B | Engineering velocity | Product backlog growing faster than shipping rate |
+| Series C | Onboarding throughput | New customer volume > CS team's onboarding capacity |
+| Growth | Hiring throughput | Headcount plan > recruiting team's capacity |
+
+### Applying TOC to Product Development
+
+**The five visible constraints in product development:**
+
+**1. Requirements clarity**
+*Symptom:* Engineering asks for clarification mid-sprint. Tickets re-opened. Scope creep.
+*Fix:* Never pull a story into sprint until acceptance criteria are written and reviewed. Product manager must be available same-day for clarification.
+
+**2. Review and approval bottleneck**
+*Symptom:* PRs sit unreviewed for >24 hours. Deploys waiting for sign-off.
+*Fix:* Code review SLA: 2-hour response for small PRs (<100 lines), 4-hour for medium. Design reviews: 24-hour turnaround. Anyone waiting >SLA can escalate to manager.
+
+**3. QA throughput**
+*Symptom:* "Done" pile grows faster than QA can test. Release day crunch.
+*Fix:* QA is pulled into sprint planning and sprint review. Testing starts as features finish, not all at end. Automated test coverage as a sprint exit criterion.
+
+**4. Deployment pipeline speed**
+*Symptom:* Deploy takes 45+ minutes. Engineers wait. Hotfix urgency causes dangerous shortcuts.
+*Fix:* Measure deploy time weekly. Set target (10 min for most apps). Build optimization into engineering roadmap as a real ticket.
+
+**5. Feedback loop latency**
+*Symptom:* You ship features and don't know if they worked for weeks.
+*Fix:* Every shipped feature has instrumented metrics reviewed within 5 business days. If no metrics exist, feature doesn't ship.
+
+### Applying TOC to Sales
+
+**The sales pipeline as a system of constraints:**
+
+```
+Lead generation → Qualification → Demo → Proposal → Negotiation → Close
+ [X] → [X] → [X] → [X] → [X] → [X]
+
+Measure: conversion rate and time-in-stage at each step.
+The constraint is the step with the LOWEST conversion rate × volume.
+```
+
+**Example diagnosis:**
+- Lead → Qualified: 40% conversion, 2 days
+- Qualified → Demo: 80% conversion, 5 days ← High conversion but slow (queue)
+- Demo → Proposal: 60% conversion, 3 days
+- Proposal → Close: 30% conversion, 14 days ← **Constraint** (lowest conversion)
+
+*Diagnosis:* Proposals are being sent to wrong buyers or proposals aren't compelling. Fix: proposal template audit, champion coaching, economic buyer access earlier in process.
+
+---
+
+## Part 2: Lean Operations for Tech Companies
+
+### The Lean Toolkit (What's Actually Useful)
+
+Lean Manufacturing was designed for car factories. Most of the original toolkit doesn't apply to software. Here's what does:
+
+**Value Stream Mapping** — Map the full flow of work from customer request to delivery. Label value-add time vs. wait time. Most processes are 90% wait time and 10% actual work.
+
+**5S** — Sort, Set in order, Shine, Standardize, Sustain. Applied to digital work:
+- *Sort:* Delete unused tools, channels, documents
+- *Set in order:* Organize information architecture so things are findable
+- *Shine:* Regular cleanup sprints (documentation, tech debt, tool hygiene)
+- *Standardize:* Templates, conventions, naming standards
+- *Sustain:* Assign owners; entropy is the default state
+
+**Pull vs. Push** — Don't push work onto people's plates. Pull = people take work when they have capacity. Push = work is assigned to people regardless of capacity. Most companies push; lean companies pull.
+
+**Kaizen** — Continuous small improvements. Build this into your operating rhythm:
+- Weekly: each team identifies one small improvement to their process
+- Monthly: review and close out improvement items
+- Quarterly: broader process retrospective
+
+**Waste Categories (TIMWOODS) — Applied to Operations:**
+
+| Waste Type | Factory Example | Startup Example |
+|-----------|----------------|-----------------|
+| **T**ransportation | Moving parts | Handing off work between tools with no integration |
+| **I**nventory | Parts stockpile | Unreviewed PRs, unworked backlog items, unread reports |
+| **M**otion | Worker movement | Context switching between apps / communication channels |
+| **W**aiting | Machine idle | Waiting for approvals, waiting for data, waiting for decisions |
+| **O**verproduction | Making more than needed | Features built that weren't validated |
+| **O**verprocessing | Extra steps | 6-step approval for $200 purchase |
+| **D**efects | Rework | Bug fixes, incorrect specs, miscommunicated requirements |
+| **S**kills | Underutilized talent | Senior engineers doing manual QA |
+
+**Exercise:** For your most important process, walk through each waste category and estimate hours/week wasted. This exercise typically reveals 20–40% improvement opportunities in the first pass.
+
+### Cycle Time and Lead Time
+
+**Lead time:** Time from when a request enters the system to when it exits (customer perspective).
+**Cycle time:** Time a unit of work is actively being worked on (team perspective).
+
+```
+Lead Time = Cycle Time + Wait Time
+```
+
+Most teams only measure cycle time. Customers only experience lead time. The gap between the two is pure waste.
+
+**Measuring in your context:**
+- Engineering: Lead time = ticket created → in production. Cycle time = in progress → PR merged.
+- Sales: Lead time = lead created → closed won. Cycle time = demo completed → proposal sent.
+- CS: Lead time = ticket opened → customer confirms resolved. Cycle time = ticket in-progress → resolution sent.
+
+**Improvement pattern:**
+1. Measure lead time (not just cycle time)
+2. Find the steps where tickets sit waiting
+3. Remove the wait (automation, reduced approval layers, clearer handoff criteria)
+
+### WIP Limits
+
+Work-In-Progress limits prevent the multi-tasking trap. When people work on 5 things simultaneously, each thing takes 5x longer and quality drops.
+
+**Recommended WIP limits:**
+- Individual IC: 2–3 active items at once
+- Team sprint: WIP = number of engineers × 1.5
+- Leadership team: No more than 3 company-level priorities per quarter
+
+**Implementation:** In Jira/Linear, add a WIP column. Set a hard limit. When the column is full, no new work starts until something ships.
+
+---
+
+## Part 3: Process Mapping Techniques
+
+### When to Map a Process
+
+Map a process when:
+- It's done by more than 2 people
+- It fails regularly (errors, rework, complaints)
+- It needs to scale (you're about to add people or volume)
+- You're automating it (you must understand the manual process first)
+- You're onboarding someone new to it
+
+Don't map processes that are genuinely ad-hoc, one-person, or will change significantly in the next 90 days.
+
+### The Three Levels of Process Maps
+
+**Level 1: Swim Lane Map (for cross-functional processes)**
+
+Best for: Customer onboarding, sales-to-CS handoff, escalation handling, hiring
+
+```
+Example: Sales to CS Handoff
+
+ | Sales AE | Sales Ops | CS Manager | CS Rep |
+--------|---------------|---------------|---------------|---------------|
+Step 1 | Close deal | | | |
+Step 2 | Fill handoff | | | |
+ | doc | | | |
+Step 3 | | Route to CS | | |
+Step 4 | | | Review & | |
+ | | | assign | |
+Step 5 | | | | Send welcome |
+Step 6 | | | | Schedule kick-|
+ | | | | off |
+```
+
+**Level 2: Flowchart (for decision-heavy processes)**
+
+Best for: Escalation routing, incident response, approval workflows
+
+Use standard symbols:
+- Rectangle = action/task
+- Diamond = decision (yes/no branch)
+- Oval = start/end
+- Parallelogram = input/output
+
+**Level 3: Work Instructions (for execution-level processes)**
+
+Best for: Checklists, SOPs, how-to guides
+
+Format:
+```
+Process: [Name]
+Owner: [Role]
+Last reviewed: [Date]
+Trigger: [What starts this process]
+
+Step 1: [Action] — [Who does it] — [Tool used] — [Expected output]
+Step 2: ...
+
+Exceptions:
+- If [condition], then [alternative action]
+
+Done when: [Definition of done]
+```
+
+### Process Audit Technique
+
+Run this quarterly on your most critical processes:
+
+**1. Walk the process** — Literally follow a unit of work from start to finish. Ask the people doing it, not the people managing it.
+
+**2. Measure three numbers:**
+- How long does it actually take? (lead time)
+- How often does it go wrong? (error/rework rate)
+- What's the cost of a failure? (downstream impact)
+
+**3. Score it:**
+```
+PROCESS HEALTH SCORE:
+Lead time vs. target: [+2 on target / 0 delayed / -2 significantly delayed]
+Error rate: [+2 <5% / 0 5-15% / -2 >15%]
+Documented: [+1 yes / -1 no]
+Owner named: [+1 yes / -1 no]
+Last reviewed (< 6 months): [+1 yes / -1 no]
+
+Max: 7. Score <3 = needs immediate attention.
+```
+
+---
+
+## Part 4: Automation Decision Framework
+
+### The "Should I Automate This?" Test
+
+Not everything should be automated. Bad automation of a broken process = faster broken process.
+
+**The five-question filter:**
+
+1. **Is the process stable?** If it changes monthly, automate later. Automating unstable processes locks in the wrong behavior.
+
+2. **How often does it happen?** Weekly or more frequent = good candidate. Monthly or less = probably not worth it.
+
+3. **What's the error rate without automation?** If the manual process is accurate 95%+ of the time, automation ROI is lower.
+
+4. **What's the cost of failure?** Customer-facing, compliance, or financial processes deserve higher automation priority than internal reporting.
+
+5. **Is the process well-documented?** If you can't describe it in a flowchart, you can't automate it. Document first.
+
+### Automation ROI Calculation
+
+```
+Annual hours saved = (minutes per occurrence / 60) × occurrences per year
+Annual labor cost saved = hours saved × fully-loaded cost per hour
+Net annual value = labor cost saved + error reduction value + speed improvement value
+
+Build/buy cost = development time + maintenance overhead
+Payback period = build/buy cost ÷ net annual value
+
+Rule of thumb: automate if payback period < 12 months
+```
+
+**Example:**
+- Process: Weekly sales report compilation
+- Time: 3 hours/week manually
+- Fully-loaded cost: $75/hour
+- Annual manual cost: 3 × 52 × $75 = $11,700
+- Automation cost: 40 hours to build = $3,000
+- Payback: 3,000 ÷ 11,700 = 3 months → **Automate**
+
+### Automation Tiers
+
+**Tier 1: No-code automation** (0–8 hours to implement)
+- Tools: Zapier, Make (Integromat), n8n, HubSpot workflows
+- Use for: Notification triggers, data syncs between tools, simple conditional routing
+- Example: New customer in CRM → create CS ticket → send welcome Slack message
+
+**Tier 2: Low-code automation** (8–40 hours to implement)
+- Tools: Retool, internal scripts, Google Apps Script, Airtable Automations
+- Use for: Internal dashboards, data transformation, approval workflows
+- Example: Weekly metrics compilation from Salesforce + Mixpanel + HubSpot into Notion dashboard
+
+**Tier 3: Engineered automation** (40+ hours to implement)
+- Built by engineering team as product/infrastructure work
+- Use for: Customer-facing workflows, compliance-critical processes, high-volume operations
+- Example: Automated customer health score calculation → CS alert → playbook trigger
+
+### Automation Prioritization Matrix
+
+```
+ HIGH FREQUENCY
+ |
+ Tier 1 now | Tier 2-3 now
+ (quick win) | (high-value)
+ |
+LOW VALUE ________________|________________ HIGH VALUE
+ |
+ Don't bother | Plan for later
+ | (when it's bigger)
+ |
+ LOW FREQUENCY
+```
+
+Place each manual process in the quadrant. Execute top-right first, Tier 1 items second.
+
+### Automation Governance
+
+As automation grows, it needs governance:
+
+**Automation registry:** Maintain a list of all automations with:
+- Name and description
+- Owner (person responsible if it breaks)
+- Tools used
+- Trigger and action
+- Last tested date
+- Business impact if down
+
+**Review cadence:** Quarterly review of automation registry. Kill automations nobody uses.
+
+**Failure alerting:** Every production automation must have failure notifications sent to a named owner. Silent failures are worse than no automation.
+
+---
+
+## Part 5: Change Management for Process Rollouts
+
+### Why Process Changes Fail
+
+Most process changes fail not because the process is wrong, but because of how it's rolled out. Common failure modes:
+
+- **Top-down dictate:** Process designed by leadership, announced to team, implemented poorly because people weren't involved and don't understand why.
+- **No training:** "Here's the new process" with no demonstration or practice.
+- **No feedback loop:** Process is rolled out and never adjusted based on what the team discovers.
+- **No accountability:** Process is optional in practice because there are no consequences for ignoring it.
+- **Old behavior still possible:** You introduce a new tool but don't turn off the old way.
+
+### The Change Management Framework (ADKAR)
+
+ADKAR (Awareness, Desire, Knowledge, Ability, Reinforcement) is the most practical model for operational change.
+
+**A — Awareness:** Does everyone understand WHY the change is needed?
+- Don't just announce the new process — explain what was broken about the old one
+- Share the data: "Our current onboarding takes 45 days, customers who onboard faster have 2x better retention. The new process targets 21 days."
+
+**D — Desire:** Do people want to change?
+- Resistance is information. Listen to it.
+- Involve front-line workers in process design. People support what they help build.
+- Address WIIFM (What's In It For Me) for each affected group
+
+**K — Knowledge:** Do people know HOW to do the new process?
+- Write it down (work instructions format above)
+- Run live demos and practice sessions
+- Create a "first time" checklist
+
+**A — Ability:** Can people actually do the new process?
+- Identify where people get stuck (first 2 weeks of rollout)
+- Have a designated expert for questions
+- Remove friction: if the new process requires 3 clicks where the old required 1, people will revert
+
+**R — Reinforcement:** Does the change stick?
+- Measure adoption (are people actually using the new process?)
+- Celebrate early adopters
+- Address non-adoption promptly — call it out without shame
+
+### Change Rollout Checklist
+
+```
+PRE-LAUNCH:
+□ Process designed and documented
+□ Stakeholders identified (people affected by change)
+□ Champions identified (people who will help adoption)
+□ Training materials created
+□ Success metrics defined (how will you know it worked?)
+□ Rollback plan documented (what if it breaks something?)
+□ Launch timeline set and communicated
+
+LAUNCH WEEK:
+□ Announcement sent with WHY, WHAT, and WHEN
+□ Training sessions held (at least 2 options for different schedules)
+□ Feedback channel opened (Slack thread, form, or dedicated meeting)
+□ Champions briefed to support peers
+
+2-WEEK CHECK:
+□ Adoption rate measured
+□ Friction points documented
+□ Quick fixes implemented
+□ Feedback reviewed and responded to
+
+30-DAY REVIEW:
+□ Success metrics reviewed vs. baseline
+□ Process adjustments made based on learnings
+□ Champions recognized
+□ Process documentation updated with lessons learned
+
+90-DAY CLOSE:
+□ Full adoption confirmed or non-adoption addressed
+□ Process owners confirmed
+□ Handoff to BAU (business as usual) operations
+```
+
+### Managing Resistance
+
+**Types of resistance and responses:**
+
+| Resistance Type | What It Sounds Like | Right Response |
+|----------------|---------------------|----------------|
+| Legitimate concern | "This process won't work because X happens" | Acknowledge, investigate, fix or explain |
+| Anxiety | "I don't know how to do this" | Training, support, reassurance |
+| Loss of control | "This takes away my judgment" | Involve them in design; give them ownership of part of it |
+| Passive non-compliance | Silent ignoring of the new process | Direct conversation; make it visible and required |
+| Organizational inertia | "We've always done it this way" | Show the cost of the status quo in concrete terms |
+
+**The three levers of adoption:**
+1. **Make the new way easier than the old way** (remove the old path if possible)
+2. **Make non-adoption visible** (dashboards showing who's using the process)
+3. **Connect process to meaningful outcomes** (show how it affects things people care about)
+
+### Process Documentation Standards
+
+Every process should have exactly one owner responsible for keeping it current.
+
+**Minimum documentation for any process:**
+- **Process name** and one-sentence purpose
+- **Owner:** Named individual, not a team
+- **Trigger:** What starts this process
+- **Steps:** Written at the level that a new employee could execute
+- **Exceptions:** Common edge cases and how to handle them
+- **Done definition:** How you know the process is complete
+- **Review date:** Set a future date when this gets reviewed
+
+**Documentation debt kills scale.** The most valuable time to document is right after you've run the process for the third time — you've found the edge cases, you know the real steps, and the process is still fresh.
+
+---
+
+## Framework Selection Guide
+
+| Situation | Framework |
+|-----------|-----------|
+| We're slow and can't figure out why | Theory of Constraints — find the bottleneck |
+| We have lots of waste and overhead | Lean — waste audit (TIMWOODS) |
+| Process is inconsistent across team | Process mapping — Level 1 swim lane |
+| Deciding what to automate | Automation decision framework + ROI calc |
+| New process keeps getting ignored | ADKAR change management |
+| Unclear who's responsible | RACI or DRI framework |
+| Too many decisions escalating to leadership | RAPID decision rights |
+
+---
+
+*Frameworks synthesized from: Eliyahu Goldratt's The Goal and Critical Chain; Womack and Jones' Lean Thinking; Prosci ADKAR model; Scaled Agile Framework (SAFe) process guidance; operational playbooks from Stripe, Airbnb, and Shopify operations teams.*
diff --git a/skills/c-level-advisor/coo-advisor/references/scaling_playbook.md b/skills/c-level-advisor/coo-advisor/references/scaling_playbook.md
new file mode 100644
index 00000000..c204563b
--- /dev/null
+++ b/skills/c-level-advisor/coo-advisor/references/scaling_playbook.md
@@ -0,0 +1,465 @@
+# Scaling Playbook: What Breaks at Each Growth Stage
+
+> Compiled from patterns across 100+ high-growth companies. Not theory — this is what actually breaks and what to do about it.
+
+---
+
+## How to Use This Playbook
+
+Each stage section covers:
+1. **What breaks** — the specific failure modes that kill companies at this stage
+2. **Hiring** — who to bring in and when
+3. **Process** — what to formalize vs. keep loose
+4. **Tools** — infrastructure that unlocks the next stage
+5. **Communication** — how information flow changes
+6. **Culture** — what to protect and what to let go
+
+**Benchmarks are medians** — your mileage varies by sector, geography, and business model.
+
+---
+
+## Stage 0: Pre-Seed / Seed ($0–$2M ARR, 1–15 people)
+
+### Key Benchmarks
+| Metric | Benchmark |
+|--------|-----------|
+| Revenue per employee | $0–$100K (still finding PMF) |
+| Manager:IC ratio | N/A (no managers) |
+| Burn multiple | 2–5x (acceptable) |
+| Runway | 12–18 months minimum |
+| Time-to-hire | 2–4 weeks |
+
+### What Breaks
+
+**Premature process.** The #1 mistake at seed stage is adding process before you have a repeatable model. Sprint ceremonies, OKR frameworks, and performance reviews are all theater when you haven't found PMF. Every hour spent in process is an hour not spent learning.
+
+**Wrong first hires.** Hiring "senior" people who've only worked in structured environments. You need people who can operate in chaos, not people who expect process to already exist.
+
+**Founder communication bottleneck.** Founders try to be in every decision. Fine at 5 people, fatal at 12. No written decisions means knowledge lives in founders' heads — unscalable.
+
+**Technical debt accepted as strategy.** "We'll fix it later" said about core data models, auth systems, or billing. Later comes at Series A and it costs 3x more to fix.
+
+### Hiring
+- **Don't hire for scale you don't have.** Hire for the next 12 months.
+- **First 10 hires set culture permanently.** Get them wrong and you'll spend years correcting.
+- **Hire athletes, not specialists.** Generalists who can do multiple jobs outperform specialists at this stage.
+- **Avoid VP titles early.** Inflated titles block future hires and create expectations you can't meet.
+- **Founder-referral bias is real.** Your network is homogeneous. Force diversity early.
+
+**Who to hire first (in rough order):**
+1. Engineers who can ship product (2–3 generalists)
+2. First sales/GTM if B2B (founder-led sales first, then one closer)
+3. Designer/product (often a hybrid)
+4. Customer success (often a founder at first)
+
+### Process
+**Formalize nothing before PMF.** Literally. Run on Slack, shared docs, and founder judgment.
+
+**After PMF signals appear, formalize only:**
+- How you handle customer escalations
+- How you deploy code (even basic CI/CD)
+- How you onboard new hires (a 1-page checklist is enough)
+
+**Decision rule:** If a founder has to answer the same question three times, write it down. Once.
+
+### Tools
+| Function | Seed-Stage Tool |
+|----------|----------------|
+| Communication | Slack + Google Workspace |
+| Project tracking | Linear or Notion (pick one, stay consistent) |
+| CRM | HubSpot free or Notion |
+| Engineering | GitHub + basic CI (GitHub Actions) |
+| Finance | Brex/Mercury + QuickBooks |
+| HR | Rippling or Gusto (basic) |
+| Analytics | Mixpanel or PostHog (free tier) |
+
+**Rule:** One tool per function. No tool sprawl. Every extra tool is a coordination tax.
+
+### Communication
+- **Weekly all-hands** (30 min max). What shipped, what's stuck, what's next.
+- **No status meetings.** Anyone can see status in Linear/Notion.
+- **Founder write-ups.** Every major decision gets a 1-paragraph Slack post explaining *why*.
+- **Group chat discipline.** One channel per project/customer. Inbox zero mentality.
+
+### Culture
+**What to build deliberately:**
+- High ownership: everyone acts like they own the company, because they do
+- Direct feedback: brutal honesty delivered with care
+- Bias to ship: done > perfect
+- Customer obsession: founders talk to customers weekly
+
+**What to watch for:**
+- "Hero culture" where one person saves everything — unsustainable
+- Over-indexing on culture fit (code for homogeneity)
+- Avoidance of conflict — mistaking silence for agreement
+
+---
+
+## Stage 1: Series A ($2–$10M ARR, 15–50 people)
+
+### Key Benchmarks
+| Metric | Benchmark |
+|--------|-----------|
+| Revenue per employee | $100–$200K |
+| Manager:IC ratio | 1:6–1:8 |
+| Burn multiple | 1.5–2.5x |
+| Sales efficiency (CAC payback) | <18 months |
+| Churn (B2B SaaS) | <10% net annual |
+| Engineering velocity | Feature shipped every 1–2 weeks |
+| Time-to-hire | 4–6 weeks |
+| Offer acceptance rate | >80% |
+
+### What Breaks
+
+**Founder-as-manager bottleneck.** At 20+ people, founders can't manage everyone. The first layer of management needs to appear — and it's usually picked wrong (best IC ≠ best manager).
+
+**Tribal knowledge explosion.** "Ask Sarah" stops working when Sarah has 15 things open. Documentation becomes critical — not for bureaucracy, but because institutional knowledge is now a flight risk.
+
+**Sales process fragmentation.** Without a defined sales process, every rep closes differently. You can't train, debug, or scale what you can't see.
+
+**Scope creep in product.** With Series A money comes investor pressure to expand scope. Teams try to build three things at once and ship nothing well.
+
+**Compensation chaos.** Early employees got equity-heavy deals. New hires get market cash. Someone compares, someone gets upset. No comp philosophy = constant re-negotiation.
+
+**Recruiting becomes a job in itself.** Founders can't hire 30 people themselves. First dedicated recruiter needed by 25 people.
+
+### Hiring
+
+**Who to hire at Series A:**
+- **Head of Engineering** (if founder is CTO): needs to be an operator, not just an architect
+- **First Sales Manager** (when you have 3+ reps): don't promote the best seller
+- **HR/People Ops** (generalist, by 30 people): comp, compliance, recruiting coordination
+- **Finance** (fractional CFO or strong controller): Series A board needs real numbers
+- **Customer Success Lead**: retention is everything at this stage
+
+**Hiring mistakes to avoid:**
+- Hiring "big company" execs who need large teams and established process
+- Assuming your Series A lead can recruit (they can intro, not close)
+- Taking too long — top candidates have 2–3 offers. Move in <2 weeks from first call to offer.
+
+**Leveling:** Build a simple career ladder *before* the compensation complaints start. 3–4 levels per function is enough.
+
+### Process
+
+**What to formalize at Series A:**
+1. **Sprint planning** (2-week sprints, public roadmap)
+2. **Sales process** (defined stages with entry/exit criteria)
+3. **Onboarding** (30/60/90 day plan for each function)
+4. **1:1 cadence** (weekly for direct reports, bi-weekly for skip-levels)
+5. **Incident response** (P0/P1/P2 definition, on-call rotation)
+6. **Quarterly planning** (OKRs or goals framework — keep it lightweight)
+
+**What to keep loose:**
+- Internal project process (let teams self-organize)
+- Meeting formats (let teams evolve their own rituals)
+- Tool selection within approved stack
+
+**Documentation standard:** Write decisions down in a shared wiki. "Decision log" with date, decision, context, owner, and outcome. Takes 5 minutes, saves hours.
+
+### Tools
+| Function | Series A Tool |
+|----------|--------------|
+| Project/Product | Linear + Notion |
+| CRM | HubSpot or Salesforce (Starter) |
+| Engineering | GitHub + CI/CD pipeline + Sentry |
+| HR/People | Rippling or Lattice (performance) |
+| Finance | NetSuite or QBO + Brex |
+| Analytics | Mixpanel/Amplitude + Looker (or Metabase) |
+| Customer Success | Intercom + HubSpot or Zendesk |
+| Docs | Notion or Confluence |
+
+### Communication
+
+**Introduce structured communication layers:**
+
+1. **Company all-hands** (monthly, 60 min): CEO share, metrics review, team spotlights, Q&A
+2. **Leadership sync** (weekly, 60 min): cross-functional issues, blockers, priorities
+3. **Team standups** (async or 15 min daily): what's in progress, what's blocked
+4. **1:1s** (weekly): direct report health, career, performance
+5. **Written updates** (weekly to investors + board): CEO memo format
+
+**Information hierarchy:** Everyone in the company should know: (1) company goals this quarter, (2) their team's goals, (3) what they personally own. If they don't, your communication structure is broken.
+
+### Culture
+
+**Deliberate culture work starts here.** You're too big for culture to be accidental.
+
+- **Write down values.** Real values with examples of what they look like in action. Not "integrity" — "we tell investors bad news before we tell them good news."
+- **Performance management.** First PIPs (Performance Improvement Plans) happen at this stage. Handle them well — the team is watching.
+- **Equity culture.** Make sure people understand what their equity is worth in different outcomes. Lack of transparency breeds resentment.
+- **First layoff plan.** Even if you never use it, know the criteria. Reactive layoffs destroy trust; plan-based ones (even painful) preserve it.
+
+---
+
+## Stage 2: Series B ($10–$30M ARR, 50–150 people)
+
+### Key Benchmarks
+| Metric | Benchmark |
+|--------|-----------|
+| Revenue per employee | $150–$300K |
+| Manager:IC ratio | 1:5–1:7 |
+| Burn multiple | 1.0–1.5x |
+| CAC payback | <12 months |
+| NRR (net revenue retention) | >110% |
+| Engineering: Product ratio | ~3:1 |
+| Sales: CS ratio | ~3:1 |
+| Time-to-hire (senior) | 6–10 weeks |
+| Annual attrition | <15% voluntary |
+
+### What Breaks
+
+**Middle management void.** You now have managers managing managers. The "player-coach" model breaks — people can't be ICs and managers simultaneously at this scale. Force the choice.
+
+**Planning misalignment.** Sales promises what product hasn't built. Product builds what customers didn't ask for. Engineering ships what QA didn't test. Fixing this requires cross-functional planning ceremonies.
+
+**Data fragmentation.** Five different versions of "how are we doing." Sales sees Salesforce. Product sees Amplitude. Finance sees spreadsheets. Nobody agrees. You need a single source of truth.
+
+**Process debt.** The Series A processes are starting to creak. Onboarding that worked for 5 hires/quarter doesn't work for 20. Customer escalation paths built for 50 customers fail at 500.
+
+**Cultural fragmentation.** Engineering culture ≠ Sales culture ≠ Support culture. Sub-cultures form. The shared identity you had at 30 people requires active work to maintain at 100.
+
+**The "brilliant jerk" problem.** High performers with bad behavior were tolerated early. Now they're managers with bad behavior, and it's systemic. Act decisively or lose your best people.
+
+### Hiring
+
+**Who to hire at Series B:**
+- **COO or VP Operations**: founder is overwhelmed, someone needs to run the machine
+- **VP Sales**: first Sales Manager won't scale to 20-rep org
+- **VP Marketing**: demand gen and brand need dedicated ownership
+- **Dedicated Recruiting**: 2–3 recruiters minimum; you're hiring 30–50 people/year
+- **Data/Analytics**: dedicated analyst or data engineer to consolidate reporting
+- **Legal counsel**: fractional or in-house; contracts and compliance are getting complex
+
+**The "big company exec" trap.** Series B is when companies hire their first VP from FAANG or a large SaaS company. 60% of these fail within 18 months. They're used to: large teams, established brand, existing process, political navigation. They struggle with: scrappy execution, no support staff, ambiguous direction. Vet explicitly for startup experience.
+
+**Span of control.** At this stage, hold managers to 5–8 direct reports. More than 8 = no time for actual management. Less than 3 = management overhead isn't justified.
+
+### Process
+
+**What to formalize at Series B:**
+1. **Quarterly Business Reviews (QBRs)** — every function presents metrics, wins, gaps
+2. **Annual planning** — budget, headcount plan, strategic priorities
+3. **Cross-functional roadmap alignment** — product/sales/marketing in sync quarterly
+4. **Promotion criteria** — written, public, applied consistently
+5. **Interview scorecards** — structured interviews with defined rubrics
+6. **Change management** — how major process changes get communicated and adopted
+7. **Vendor management** — evaluation criteria, approval process, contract management
+
+**SOPs for critical processes:**
+- Customer onboarding (if >50 customers)
+- Sales handoff from SDR to AE to CS
+- Engineering release process
+- Incident response playbook
+- Contractor/vendor procurement
+
+### Tools
+| Function | Series B Tool |
+|----------|--------------|
+| Project/Product | Jira or Linear (with roadmapping) |
+| CRM | Salesforce (full) |
+| ERP/Finance | NetSuite |
+| HR | Workday or BambooHR + Lattice |
+| Analytics | Looker or Tableau + data warehouse |
+| Customer Success | Gainsight or ChurnZero |
+| Engineering | GitHub Enterprise + full CI/CD + observability |
+| Security | 1Password Teams + SSO (Okta) + endpoint management |
+
+### Communication
+
+**At 50+ people, informal communication breaks down.** Information no longer flows naturally — it has to be architected.
+
+**Communication stack:**
+- **Monthly all-hands** (90 min): metrics deep-dive, strategy update, team Q&A
+- **Weekly leadership team** (90 min): cross-functional priorities, decisions, escalations
+- **Bi-weekly skip-levels** (30 min): every manager holds these with their manager's reports
+- **Quarterly town halls** (2 hrs): broader context, financial update, roadmap preview
+- **Written company update** (bi-weekly): CEO to all-hands via Slack/email
+
+**The information gradient problem.** People at the top know too much. People at the bottom know too little. Fix this with a deliberate "broadcast" culture — any decision affecting more than 5 people gets written up and shared.
+
+### Culture
+
+**Retention becomes an existential issue.** At Series B, you have 50–150 people who've been with you through something hard. They're valuable. And they have options.
+
+- **Career ladders** are non-negotiable by this stage. People leave when they can't see a future.
+- **Manager quality** determines retention. Invest in manager training. Run manager effectiveness surveys.
+- **Compensation benchmarking** quarterly. If you're more than 10% below market, you're losing people silently.
+- **Culture carriers.** Identify the 10–15 people who embody your culture and make them formally responsible for transmitting it. Give them a platform.
+
+---
+
+## Stage 3: Series C ($30–$75M ARR, 150–500 people)
+
+### Key Benchmarks
+| Metric | Benchmark |
+|--------|-----------|
+| Revenue per employee | $200–$400K |
+| Manager:IC ratio | 1:5–1:6 |
+| Burn multiple | 0.75–1.25x |
+| NRR | >115% |
+| CAC payback | <9 months |
+| Sales cycle (Enterprise) | 60–120 days |
+| Engineering team % | 30–40% of headcount |
+| Annual attrition target | <12% voluntary |
+| Time-to-hire (senior) | 8–12 weeks |
+
+### What Breaks
+
+**Strategy execution gap.** Leadership agrees on strategy. Middle management interprets it differently. ICs execute on their interpretation. By the time work ships, it barely resembles the original strategy. Fix: strategy must cascade in writing with explicit outcomes.
+
+**Process bureaucracy.** The processes you built at Series B start generating bureaucracy. Approval chains lengthen. Simple decisions require three meetings. The antidote is explicit process owners empowered to eliminate friction.
+
+**Org design complexity.** Do you have functional teams (all engineers in one org) or product teams (engineers embedded in product squads)? The answer affects everything: career paths, knowledge sharing, delivery speed. Most companies get this wrong twice before getting it right.
+
+**Geographic complexity.** First international office or remote-heavy team introduces timezone, communication, and culture challenges that don't exist when everyone is in one room.
+
+**Leadership team dysfunction.** Seven VPs who were all individual contributors two years ago are now running $10M+ organizations. Some have grown into it. Some haven't. This is the stage where hard leadership team changes happen.
+
+### Hiring
+
+**Series C hiring is about depth, not breadth.** You have functional coverage — now hire people who go deep within functions.
+
+- **Functional leaders' deputies**: VP Engineering needs a Director of Platform Engineering, Director of Product Engineering, etc.
+- **Internal promotions**: 40–60% of leadership roles should be filled internally by now. If you're hiring externally for everything, you've failed at development.
+- **Specialists**: Security, data science, UX research, RevOps — functions that were "shared" become dedicated.
+- **General Counsel**: Legal volume justifies full-time counsel.
+
+**Headcount planning discipline.** Every hire should have a business case. "The team is busy" is not a business case. "This role will unlock $X in revenue or save Y hours/week" is a business case.
+
+### Process
+
+**Process consolidation.** Audit every process. Kill anything that doesn't have a clear owner and clear outcome. The average Series C company has 40% more process than it needs.
+
+**Key processes to have locked at Series C:**
+1. **Annual planning cycle** (strategy → goals → headcount → budget)
+2. **Quarterly operating review** (progress against plan, forecast, adjustments)
+3. **Product development lifecycle** (discovery → design → build → launch → measure)
+4. **Revenue operations** (forecasting, pipeline management, territory planning)
+5. **People operations** (performance cycles, promotion cadence, compensation philosophy)
+6. **Risk management** (operational, security, compliance, legal)
+
+**Delegation architecture.** At 200+ people, the COO cannot know about every decision. Build explicit decision rights: what decisions require CEO/COO approval vs. VP vs. Director vs. IC.
+
+### Tools
+
+**Consolidate the tech stack.** By Series C, you have tool sprawl. The average 200-person company has 100+ SaaS tools. 40% are redundant. Consolidation saves $200–500K/year and reduces security surface.
+
+**Must-have by Series C:**
+- Enterprise SSO (Okta/Google Workspace with MFA everywhere)
+- Data warehouse (Snowflake/BigQuery) + BI layer
+- HRIS with performance management (Workday, Rippling, BambooHR)
+- Revenue intelligence (Gong, Chorus)
+- Security tooling (endpoint, SIEM basics, SOC 2 compliance)
+
+### Communication
+
+**Internal comms becomes a function.** You cannot rely on ad-hoc Slack and email at 200+ people. Someone needs to own internal communications.
+
+- **Monthly CEO update** (written, 500 words max): company performance, strategic context, what's next
+- **Quarterly all-hands** (2 hrs): comprehensive business review, open Q&A
+- **Leadership alignment sessions** (quarterly): leadership team off-site to calibrate on strategy
+- **Manager cascade** (after every major announcement): managers brief their teams with tailored context
+
+### Culture
+
+**Culture is now a function, not an instinct.** By Series C, your original culture-carriers are managers or have left. New people joining have never seen how you worked when you were small.
+
+- **Culture explicitly documented** — not a values poster, a behavioral handbook
+- **Onboarding redesigned** for culture transmission at scale
+- **Manager enablement** — managers are your primary culture delivery mechanism; invest heavily
+- **Listening infrastructure** — eNPS quarterly, exit interviews, skip-level feedback — all analyzed systematically
+
+---
+
+## Stage 4: Growth Stage ($75M+ ARR, 500+ people)
+
+### Key Benchmarks
+| Metric | Benchmark |
+|--------|-----------|
+| Revenue per employee | $300–$600K |
+| Manager:IC ratio | 1:4–1:6 |
+| Burn multiple (path to profitability) | <0.5x |
+| NRR | >120% |
+| S&M as % of revenue | 25–35% |
+| R&D as % of revenue | 15–25% |
+| G&A as % of revenue | 8–12% |
+| Rule of 40 | >40 (growth rate + profit margin) |
+| Annual attrition target | <10% voluntary |
+
+### What Breaks
+
+**Execution at scale.** The larger you are, the harder it is to move fast. The average decision at a 500-person company takes 3x longer than at a 50-person company. This is not inevitable — but fixing it requires explicit investment.
+
+**Internal politics.** Org boundaries create fiefdoms. VPs protect headcount. Teams optimize for their metrics at the expense of company metrics. This is the #1 culture problem at scale.
+
+**Innovation starvation.** The core business is optimized, but new bets are starved of resources. The people working on new initiatives are constrained by processes designed for a mature product. Structural solution required: separate P&L, separate team, different metrics.
+
+**Middle management bloat.** Growth-stage companies often have too many managers and not enough ICs. A manager managing one other manager managing three ICs is a 3-level chain where 2 people add no value. Flatten aggressively.
+
+### Hiring
+
+**You're now competing for talent with FAANG.** Your advantage is mission, equity, and the ability to have impact. Candidates who want to join a Fortune 500 will not join you. Stop trying to attract them.
+
+- **Leadership pipeline**: promote from within at 50%+ for senior roles
+- **Talent density over headcount**: 30 strong engineers > 50 average engineers
+- **Diverse hiring**: by this stage, lack of diversity is a business problem, not just an ethical one
+
+### Operational Priorities at Scale
+
+1. **Operational efficiency over growth**: headcount growth should lag revenue growth
+2. **Process ownership**: every major process has a named owner accountable for outcomes
+3. **Quarterly operating model**: budget vs. actual, full P&L transparency to VP level
+4. **Automation**: manual operational processes that cost >40 hrs/week should be automated
+
+---
+
+## Cross-Stage Principles
+
+### The Three Things That Kill Companies at Every Stage
+1. **Running out of cash before finding the next unlock** — runway management is sacred
+2. **Hiring the wrong person for a critical role** — one bad VP can set you back 18 months
+3. **Moving too slowly** — market timing matters; perfect is the enemy of shipped
+
+### The Org Design Progression
+```
+Seed: Flat | Everyone reports to founder | No structure
+Series A: Functional pods | First-line managers | Light structure
+Series B: Functional departments | VPs emerge | Defined structure
+Series C: Business units or product squads | Directors + VPs | Full structure
+Growth: Divisional or matrix | EVPs/SVPs | Corporate structure
+```
+
+### Revenue per Employee by Function (B2B SaaS benchmarks)
+| Function | Series A | Series B | Series C | Growth |
+|----------|----------|----------|----------|--------|
+| Engineering | $400K | $500K | $600K | $700K |
+| Sales | $250K | $350K | $450K | $500K |
+| Customer Success | $300K | $400K | $500K | $600K |
+| Marketing | $500K | $700K | $900K | $1M+ |
+| G&A | $600K | $800K | $1M | $1.2M |
+
+*Revenue per employee = ARR / headcount in function*
+
+### The Management Span Rule
+- **Individual contributors being managed**: 1 manager per 6–8 ICs
+- **Managers being managed**: 1 director per 4–6 managers
+- **Directors being managed**: 1 VP per 3–5 directors
+- **VPs being managed**: 1 C-level per 5–8 VPs
+
+Violation of this creates either manager burnout (too wide) or management theater (too narrow).
+
+---
+
+## Red Flags by Stage
+
+| Stage | Red Flag | Likely Cause |
+|-------|----------|-------------|
+| Seed | Missed 3+ product deadlines | Wrong team or unclear prioritization |
+| Series A | Churn >20% | PMF not actually found, or CS underfunded |
+| Series B | >6-month sales cycle on SMB | Pricing/packaging problem |
+| Series C | NRR <100% | Product-market fit eroding or CS broken |
+| Growth | Rule of 40 <20 | Efficiency problem; hiring ahead of revenue |
+
+---
+
+*Sources: Sequoia, a16z operating frameworks; First Round Capital COO benchmarks; SaaStr metrics databases; OpenView SaaS benchmarks; Bain operational maturity models.*
diff --git a/skills/c-level-advisor/coo-advisor/scripts/okr_tracker.py b/skills/c-level-advisor/coo-advisor/scripts/okr_tracker.py
new file mode 100644
index 00000000..890f5e48
--- /dev/null
+++ b/skills/c-level-advisor/coo-advisor/scripts/okr_tracker.py
@@ -0,0 +1,1100 @@
+#!/usr/bin/env python3
+"""
+okr_tracker.py — OKR Cascade and Alignment Tracker
+
+Tracks OKR progress from company → department → team level.
+Calculates scores, flags at-risk key results, and generates alignment reports.
+
+Scoring: Google's 0.0–1.0 scale (target: 0.6–0.7; hitting 1.0 means goal was too easy)
+
+Usage:
+ python okr_tracker.py # Runs with sample data
+ python okr_tracker.py --input okrs.json # Custom OKR data
+ python okr_tracker.py --input okrs.json --output report.txt
+ python okr_tracker.py --format json # Machine-readable output
+"""
+
+import json
+import sys
+import argparse
+from datetime import datetime, date
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Scoring Engine
+# ---------------------------------------------------------------------------
+
+# OKR health thresholds (Google-style 0.0–1.0 scale)
+SCORE_THRESHOLDS = {
+ "on_track": 0.70, # Above this: healthy
+ "at_risk": 0.40, # Between at_risk and on_track: needs attention
+ # Below at_risk: off track
+}
+
+STATUS_LABELS = {
+ "on_track": "🟢 On Track",
+ "at_risk": "🟡 At Risk",
+ "off_track": "🔴 Off Track",
+ "complete": "✅ Complete",
+ "not_started": "⬜ Not Started",
+}
+
+RISK_LABELS = {
+ "critical": "🔴 Critical",
+ "high": "🟠 High",
+ "medium": "🟡 Medium",
+ "low": "🟢 Low",
+}
+
+
+def calculate_kr_score(kr: dict) -> float:
+ """
+ Calculate a Key Result's progress score (0.0–1.0).
+
+ Supports multiple KR types:
+ - numeric: current_value / target_value
+ - percentage: current_pct / target_pct
+ - milestone: milestone_score (0.0–1.0 provided directly)
+ - boolean: done (1.0) / not done (0.0)
+ """
+ kr_type = kr.get("type", "numeric")
+
+ if kr_type == "boolean":
+ return 1.0 if kr.get("done", False) else 0.0
+
+ elif kr_type == "milestone":
+ # Milestone KRs have explicit score (0.0–1.0) or count of milestones hit
+ milestones_total = kr.get("milestones_total", 1)
+ milestones_hit = kr.get("milestones_hit", 0)
+ explicit_score = kr.get("score")
+ if explicit_score is not None:
+ return max(0.0, min(1.0, float(explicit_score)))
+ return milestones_hit / milestones_total if milestones_total > 0 else 0.0
+
+ elif kr_type == "percentage":
+ target = kr.get("target_pct", 100)
+ current = kr.get("current_pct", 0)
+ baseline = kr.get("baseline_pct", 0)
+ if target == baseline:
+ return 0.0
+ score = (current - baseline) / (target - baseline)
+ return max(0.0, min(1.0, score))
+
+ else: # numeric (default)
+ target = kr.get("target_value", 0)
+ current = kr.get("current_value", 0)
+ baseline = kr.get("baseline_value", 0)
+ if target == baseline:
+ return 0.0
+ # Handle "lower is better" metrics (e.g., churn, response time)
+ if kr.get("lower_is_better", False):
+ if current <= target:
+ return 1.0
+ improvement = baseline - current
+ needed = baseline - target
+ score = improvement / needed if needed != 0 else 0.0
+ else:
+ score = (current - baseline) / (target - baseline)
+ return max(0.0, min(1.0, score))
+
+
+def get_kr_status(score: float, quarter_progress: float, kr: dict) -> str:
+ """
+ Determine KR status based on score, time elapsed in quarter, and trend.
+
+ A KR is at-risk if its score is significantly behind the time elapsed.
+ E.g., if we're 70% through the quarter but KR is at 30%, it's at risk.
+ """
+ if kr.get("done", False):
+ return "complete"
+
+ # Not started
+ if score == 0.0 and quarter_progress < 0.1:
+ return "not_started"
+
+ # Check against absolute thresholds
+ if score >= SCORE_THRESHOLDS["on_track"]:
+ return "on_track"
+
+ # Adjust for time: if we're early in quarter, lower scores are acceptable
+ adjusted_threshold = SCORE_THRESHOLDS["at_risk"] * (quarter_progress or 0.5)
+
+ if score >= max(adjusted_threshold, SCORE_THRESHOLDS["at_risk"]):
+ return "at_risk"
+
+ return "off_track"
+
+
+def calculate_objective_score(objective: dict, quarter_progress: float) -> dict:
+ """
+ Score an objective based on its key results.
+ Returns scored objective with KR scores and status.
+ """
+ key_results = objective.get("key_results", [])
+ if not key_results:
+ return {**objective, "score": 0.0, "status": "not_started", "key_results_scored": []}
+
+ scored_krs = []
+ for kr in key_results:
+ score = calculate_kr_score(kr)
+ status = get_kr_status(score, quarter_progress, kr)
+
+ # Calculate time-adjusted gap
+ expected_score = quarter_progress * 0.85 # Expect 85% of time-proportional progress
+ gap = expected_score - score
+
+ risk_level = _assess_kr_risk(score, status, gap, quarter_progress, kr)
+
+ scored_krs.append({
+ **kr,
+ "score": round(score, 3),
+ "score_pct": f"{score * 100:.0f}%",
+ "status": status,
+ "status_label": STATUS_LABELS.get(status, status),
+ "expected_score": round(expected_score, 3),
+ "gap_vs_expected": round(gap, 3),
+ "risk_level": risk_level,
+ "risk_label": RISK_LABELS.get(risk_level, risk_level),
+ })
+
+ # Objective score = weighted average of KR scores
+ # Weight is explicit in KR data or defaults to equal weight
+ total_weight = sum(kr.get("weight", 1.0) for kr in key_results)
+ weighted_score = sum(
+ kr_scored["score"] * kr.get("weight", 1.0)
+ for kr_scored, kr in zip(scored_krs, key_results)
+ )
+ obj_score = weighted_score / total_weight if total_weight > 0 else 0.0
+
+ # Objective status = worst KR status (a chain is only as strong as weakest link)
+ status_priority = {"off_track": 0, "at_risk": 1, "not_started": 2, "on_track": 3, "complete": 4}
+ obj_status = min(scored_krs, key=lambda x: status_priority.get(x["status"], 2))["status"]
+
+ return {
+ **objective,
+ "score": round(obj_score, 3),
+ "score_pct": f"{obj_score * 100:.0f}%",
+ "status": obj_status,
+ "status_label": STATUS_LABELS.get(obj_status, obj_status),
+ "key_results_scored": scored_krs,
+ }
+
+
+def _assess_kr_risk(
+ score: float,
+ status: str,
+ gap: float,
+ quarter_progress: float,
+ kr: dict,
+) -> str:
+ """Assess risk level for a key result."""
+ if status == "complete" or status == "on_track":
+ return "low"
+
+ weeks_remaining = kr.get("weeks_remaining", max(1, int((1 - quarter_progress) * 13)))
+
+ # Critical: off track with <4 weeks left
+ if status == "off_track" and weeks_remaining <= 4:
+ return "critical"
+
+ # High: significantly behind with limited time
+ if gap > 0.3 and weeks_remaining <= 6:
+ return "high"
+
+ # High: off track regardless of time
+ if status == "off_track":
+ return "high"
+
+ # Medium: at risk
+ if status == "at_risk":
+ return "medium"
+
+ return "low"
+
+
+# ---------------------------------------------------------------------------
+# OKR Cascade and Alignment Analysis
+# ---------------------------------------------------------------------------
+
+def build_okr_tree(data: dict, quarter_progress: float) -> dict:
+ """
+ Build scored OKR tree: company → departments → teams.
+ Returns full hierarchy with scores at every level.
+ """
+ company = data.get("company_okrs", {})
+ departments = data.get("department_okrs", [])
+ teams = data.get("team_okrs", [])
+
+ # Score company-level OKRs
+ company_scored = {
+ "name": company.get("name", "Company"),
+ "quarter": company.get("quarter", ""),
+ "objectives": [
+ calculate_objective_score(obj, quarter_progress)
+ for obj in company.get("objectives", [])
+ ],
+ }
+
+ # Score department-level OKRs
+ depts_scored = []
+ for dept in departments:
+ dept_objectives = [
+ calculate_objective_score(obj, quarter_progress)
+ for obj in dept.get("objectives", [])
+ ]
+ dept_score = (
+ sum(o["score"] for o in dept_objectives) / len(dept_objectives)
+ if dept_objectives else 0.0
+ )
+ depts_scored.append({
+ **dept,
+ "objectives": dept_objectives,
+ "overall_score": round(dept_score, 3),
+ "overall_score_pct": f"{dept_score * 100:.0f}%",
+ })
+
+ # Score team-level OKRs
+ teams_scored = []
+ for team in teams:
+ team_objectives = [
+ calculate_objective_score(obj, quarter_progress)
+ for obj in team.get("objectives", [])
+ ]
+ team_score = (
+ sum(o["score"] for o in team_objectives) / len(team_objectives)
+ if team_objectives else 0.0
+ )
+ teams_scored.append({
+ **team,
+ "objectives": team_objectives,
+ "overall_score": round(team_score, 3),
+ "overall_score_pct": f"{team_score * 100:.0f}%",
+ })
+
+ return {
+ "company": company_scored,
+ "departments": depts_scored,
+ "teams": teams_scored,
+ }
+
+
+def analyze_alignment(okr_tree: dict) -> dict:
+ """
+ Analyze how team and department OKRs align to company OKRs.
+ Flags: orphaned OKRs (no company parent), missing coverage (company OKR with no team support).
+ """
+ company_objective_ids = {
+ obj.get("id") for obj in okr_tree["company"].get("objectives", [])
+ if obj.get("id")
+ }
+
+ # Collect all alignment references from dept and team OKRs
+ alignment_map: dict[str, list[str]] = {oid: [] for oid in company_objective_ids}
+ orphaned = []
+ all_supporting = []
+
+ def check_objectives(objectives: list, owner_name: str, level: str):
+ for obj in objectives:
+ supports = obj.get("supports_company_objective_ids", [])
+ if not supports:
+ # Check if it's supposed to support something
+ if obj.get("supports_company_objective_id"):
+ supports = [obj["supports_company_objective_id"]]
+
+ if not supports:
+ orphaned.append({
+ "level": level,
+ "owner": owner_name,
+ "objective": obj.get("title", obj.get("name", "Unknown")),
+ "issue": "No link to company objective — may be misaligned or low priority",
+ })
+ else:
+ for cid in supports:
+ if cid in alignment_map:
+ alignment_map[cid].append(f"{level}:{owner_name}")
+ all_supporting.append(cid)
+ else:
+ orphaned.append({
+ "level": level,
+ "owner": owner_name,
+ "objective": obj.get("title", obj.get("name", "Unknown")),
+ "issue": f"References company objective '{cid}' which doesn't exist",
+ })
+
+ for dept in okr_tree["departments"]:
+ check_objectives(dept["objectives"], dept.get("name", "Unknown Dept"), "Department")
+
+ for team in okr_tree["teams"]:
+ check_objectives(team["objectives"], team.get("name", "Unknown Team"), "Team")
+
+ # Find company objectives with no support from below
+ unsupported = []
+ for obj in okr_tree["company"].get("objectives", []):
+ obj_id = obj.get("id")
+ if obj_id and obj_id not in all_supporting:
+ unsupported.append({
+ "objective_id": obj_id,
+ "objective": obj.get("title", obj.get("name", "Unknown")),
+ "issue": "No department or team OKR explicitly supports this company objective",
+ })
+
+ coverage_score = (
+ len(set(all_supporting)) / len(company_objective_ids) * 100
+ if company_objective_ids else 100
+ )
+
+ return {
+ "alignment_map": alignment_map,
+ "orphaned_okrs": orphaned,
+ "unsupported_company_objectives": unsupported,
+ "coverage_score_pct": round(coverage_score, 1),
+ }
+
+
+def collect_at_risk_krs(okr_tree: dict) -> list[dict]:
+ """Collect all at-risk and off-track key results across the full OKR tree."""
+ at_risk = []
+
+ def scan_objectives(objectives: list, owner: str, level: str):
+ for obj in objectives:
+ for kr in obj.get("key_results_scored", []):
+ if kr["status"] in ("at_risk", "off_track"):
+ at_risk.append({
+ "level": level,
+ "owner": owner,
+ "objective": obj.get("title", obj.get("name", "Unknown")),
+ "key_result": kr.get("title", kr.get("name", "Unknown")),
+ "score": kr["score"],
+ "score_pct": kr["score_pct"],
+ "status": kr["status"],
+ "status_label": kr["status_label"],
+ "risk_level": kr["risk_level"],
+ "risk_label": kr["risk_label"],
+ "gap_vs_expected": kr["gap_vs_expected"],
+ "notes": kr.get("notes", ""),
+ })
+
+ scan_objectives(
+ okr_tree["company"].get("objectives", []),
+ okr_tree["company"].get("name", "Company"),
+ "Company",
+ )
+ for dept in okr_tree["departments"]:
+ scan_objectives(dept["objectives"], dept.get("name", ""), "Department")
+ for team in okr_tree["teams"]:
+ scan_objectives(team["objectives"], team.get("name", ""), "Team")
+
+ # Sort: off_track before at_risk, then by gap
+ status_order = {"off_track": 0, "at_risk": 1}
+ at_risk.sort(key=lambda x: (status_order.get(x["status"], 2), -x.get("gap_vs_expected", 0)))
+
+ return at_risk
+
+
+# ---------------------------------------------------------------------------
+# Report Formatter
+# ---------------------------------------------------------------------------
+
+def _score_bar(score: float, width: int = 20) -> str:
+ """Render a text progress bar for a 0.0–1.0 score."""
+ filled = round(score * width)
+ bar = "█" * filled + "░" * (width - filled)
+ return f"[{bar}] {score * 100:.0f}%"
+
+
+def format_report(
+ okr_tree: dict,
+ alignment: dict,
+ at_risk_krs: list[dict],
+ quarter_progress: float,
+ quarter_label: str,
+) -> str:
+ """Format full OKR tracking report as plain text."""
+ lines = []
+ now = datetime.now().strftime("%Y-%m-%d %H:%M")
+ company_name = okr_tree["company"].get("name", "Company")
+
+ lines.append("=" * 70)
+ lines.append(f"OKR TRACKING REPORT — {company_name}")
+ lines.append(f"Quarter: {quarter_label} | Quarter progress: {quarter_progress * 100:.0f}%")
+ lines.append(f"Generated: {now}")
+ lines.append("=" * 70)
+
+ # --- Executive Summary ---
+ lines.append("\n📊 EXECUTIVE SUMMARY")
+ lines.append("-" * 40)
+
+ company_objectives = okr_tree["company"].get("objectives", [])
+ if company_objectives:
+ company_avg = sum(o["score"] for o in company_objectives) / len(company_objectives)
+ on_track = sum(1 for o in company_objectives if o["status"] == "on_track")
+ at_risk = sum(1 for o in company_objectives if o["status"] == "at_risk")
+ off_track = sum(1 for o in company_objectives if o["status"] == "off_track")
+
+ lines.append(f"Company OKR Score: {_score_bar(company_avg)}")
+ lines.append(f"Objectives: {len(company_objectives)} total — "
+ f"🟢 {on_track} on track, 🟡 {at_risk} at risk, 🔴 {off_track} off track")
+ lines.append(f"At-risk KRs (all): {len(at_risk_krs)}")
+ lines.append(f"Alignment coverage: {alignment['coverage_score_pct']}% of company objectives have team support")
+
+ # Overall health assessment
+ if company_avg >= 0.7:
+ health = "🟢 HEALTHY — On track for a strong quarter"
+ elif company_avg >= 0.5:
+ health = "🟡 CAUTION — Some objectives need attention"
+ elif company_avg >= 0.3:
+ health = "🔴 AT RISK — Multiple objectives behind; intervention needed"
+ else:
+ health = "🚨 CRITICAL — Quarter in serious jeopardy; executive review required"
+ lines.append(f"\nOverall Health: {health}")
+
+ # --- Company OKRs ---
+ lines.append("\n\n🏢 COMPANY OKRs")
+ lines.append("-" * 40)
+
+ for obj in company_objectives:
+ lines.append(f"\n Objective: {obj.get('title', obj.get('name', 'Unknown'))}")
+ lines.append(f" Owner: {obj.get('owner', 'Unassigned')} | Score: {_score_bar(obj['score'], 15)} {obj['status_label']}")
+
+ for kr in obj.get("key_results_scored", []):
+ risk_marker = f" {kr['risk_label']}" if kr["risk_level"] in ("critical", "high") else ""
+ lines.append(f"\n KR: {kr.get('title', kr.get('name', 'Unknown'))}")
+ lines.append(f" Score: {_score_bar(kr['score'], 12)} {kr['status_label']}{risk_marker}")
+
+ # Show actual progress
+ if kr.get("type") == "numeric":
+ current = kr.get("current_value", "?")
+ target = kr.get("target_value", "?")
+ baseline = kr.get("baseline_value", 0)
+ unit = kr.get("unit", "")
+ lines.append(f" Progress: {current}{unit} / {target}{unit} (baseline: {baseline}{unit})")
+ elif kr.get("type") == "percentage":
+ lines.append(f" Progress: {kr.get('current_pct', '?')}% / {kr.get('target_pct', '?')}%")
+ elif kr.get("type") == "milestone":
+ hit = kr.get("milestones_hit", "?")
+ total = kr.get("milestones_total", "?")
+ lines.append(f" Milestones: {hit} / {total}")
+
+ if kr.get("notes"):
+ lines.append(f" Note: {kr['notes']}")
+
+ # --- Department OKRs ---
+ lines.append("\n\n🏬 DEPARTMENT OKRs")
+ lines.append("-" * 40)
+
+ for dept in okr_tree["departments"]:
+ lines.append(f"\n 📁 {dept.get('name', 'Unknown')} | Score: {_score_bar(dept['overall_score'], 15)}")
+
+ for obj in dept.get("objectives", []):
+ lines.append(f"\n Objective: {obj.get('title', obj.get('name', 'Unknown'))}")
+ lines.append(f" Owner: {obj.get('owner', 'Unassigned')} | {obj['status_label']}")
+ supports = obj.get("supports_company_objective_ids", [])
+ if supports:
+ lines.append(f" Supports: Company Objective(s) {', '.join(supports)}")
+
+ for kr in obj.get("key_results_scored", []):
+ risk_marker = f" {kr['risk_label']}" if kr["risk_level"] in ("critical", "high") else ""
+ lines.append(f"\n KR: {kr.get('title', kr.get('name', 'Unknown'))}")
+ lines.append(f" {_score_bar(kr['score'], 10)} {kr['status_label']}{risk_marker}")
+
+ # --- Team OKRs ---
+ if okr_tree["teams"]:
+ lines.append("\n\n👥 TEAM OKRs")
+ lines.append("-" * 40)
+
+ for team in okr_tree["teams"]:
+ lines.append(f"\n 📋 {team.get('name', 'Unknown')} | Score: {_score_bar(team['overall_score'], 15)}")
+
+ for obj in team.get("objectives", []):
+ lines.append(f"\n Objective: {obj.get('title', obj.get('name', 'Unknown'))}")
+ supports = obj.get("supports_company_objective_ids", [])
+ if supports:
+ lines.append(f" Supports: {', '.join(supports)}")
+
+ for kr in obj.get("key_results_scored", []):
+ risk_marker = f" {kr['risk_label']}" if kr["risk_level"] in ("critical", "high") else ""
+ lines.append(
+ f" • {kr.get('title', kr.get('name', 'Unknown'))}: "
+ f"{kr['score_pct']} {kr['status_label']}{risk_marker}"
+ )
+
+ # --- At-Risk KRs ---
+ lines.append("\n\n⚠️ AT-RISK KEY RESULTS (Action Required)")
+ lines.append("-" * 40)
+
+ if not at_risk_krs:
+ lines.append("✅ No key results currently at risk or off track.")
+ else:
+ critical = [kr for kr in at_risk_krs if kr["risk_level"] == "critical"]
+ high = [kr for kr in at_risk_krs if kr["risk_level"] == "high"]
+ medium = [kr for kr in at_risk_krs if kr["risk_level"] == "medium"]
+
+ for group_label, group in [("🔴 CRITICAL", critical), ("🟠 HIGH", high), ("🟡 MEDIUM", medium)]:
+ if not group:
+ continue
+ lines.append(f"\n{group_label} ({len(group)} items):")
+ for kr in group:
+ lines.append(f"\n [{kr['level']}] {kr['owner']}")
+ lines.append(f" Obj: {kr['objective']}")
+ lines.append(f" KR: {kr['key_result']}")
+ lines.append(f" Score: {kr['score_pct']} {kr['status_label']} (gap vs expected: {kr['gap_vs_expected'] * 100:.0f}pp)")
+ if kr["notes"]:
+ lines.append(f" Note: {kr['notes']}")
+
+ # --- Alignment Report ---
+ lines.append("\n\n🔗 ALIGNMENT REPORT")
+ lines.append("-" * 40)
+ lines.append(f"Alignment coverage: {alignment['coverage_score_pct']}% of company objectives have explicit support\n")
+
+ # Show alignment map
+ lines.append("Company Objective Coverage:")
+ for obj in company_objectives:
+ obj_id = obj.get("id", "")
+ supporters = alignment["alignment_map"].get(obj_id, [])
+ obj_name = obj.get("title", obj.get("name", obj_id))
+ count = len(supporters)
+ marker = "✅" if count > 0 else "⚠️ "
+ lines.append(f" {marker} [{obj_id}] {obj_name}")
+ if supporters:
+ for s in supporters:
+ lines.append(f" ↑ {s}")
+ else:
+ lines.append(f" ↑ (no department or team OKR supports this)")
+
+ if alignment["unsupported_company_objectives"]:
+ lines.append(f"\n⚠️ Unsupported Company Objectives ({len(alignment['unsupported_company_objectives'])}):")
+ for u in alignment["unsupported_company_objectives"]:
+ lines.append(f" • [{u['objective_id']}] {u['objective']}")
+ lines.append(f" → {u['issue']}")
+
+ if alignment["orphaned_okrs"]:
+ lines.append(f"\n⚠️ Orphaned OKRs (not linked to company objectives):")
+ for o in alignment["orphaned_okrs"]:
+ lines.append(f" • [{o['level']}] {o['owner']}: {o['objective']}")
+ lines.append(f" → {o['issue']}")
+
+ # --- Recommendations ---
+ lines.append("\n\n📋 RECOMMENDED ACTIONS")
+ lines.append("-" * 40)
+
+ recs = _generate_recommendations(okr_tree, at_risk_krs, alignment, quarter_progress)
+ for i, rec in enumerate(recs, 1):
+ lines.append(f"\n{i}. {rec['title']}")
+ lines.append(f" {rec['detail']}")
+ lines.append(f" Owner: {rec['owner']} | When: {rec['when']}")
+
+ lines.append("\n" + "=" * 70)
+ lines.append("END OF REPORT")
+ lines.append("=" * 70)
+
+ return "\n".join(lines)
+
+
+def _generate_recommendations(
+ okr_tree: dict,
+ at_risk_krs: list[dict],
+ alignment: dict,
+ quarter_progress: float,
+) -> list[dict]:
+ """Generate actionable recommendations based on OKR analysis."""
+ recs = []
+
+ # Critical KRs
+ critical = [kr for kr in at_risk_krs if kr["risk_level"] == "critical"]
+ if critical:
+ recs.append({
+ "title": f"Emergency review: {len(critical)} critical key result(s) need immediate intervention",
+ "detail": f"Critical KRs: {', '.join(kr['key_result'] for kr in critical[:3])}. "
+ f"With limited time remaining, these need escalation today.",
+ "owner": "COO + KR owners",
+ "when": "This week",
+ })
+
+ # Off-track objectives
+ off_track_objs = [
+ o for o in okr_tree["company"].get("objectives", [])
+ if o["status"] == "off_track"
+ ]
+ if off_track_objs:
+ recs.append({
+ "title": f"Scope reset for {len(off_track_objs)} off-track company objective(s)",
+ "detail": "When a company objective is off track by mid-quarter, "
+ "the options are: (1) resource surge, (2) scope reduction, or (3) accept the miss. "
+ "Choose explicitly — don't let it drift.",
+ "owner": "CEO + COO",
+ "when": "Within 1 week",
+ })
+
+ # Alignment gaps
+ if alignment["coverage_score_pct"] < 80:
+ recs.append({
+ "title": "OKR alignment gap — not all company objectives have team support",
+ "detail": f"Only {alignment['coverage_score_pct']}% of company objectives have explicit team/dept OKRs supporting them. "
+ "Either add supporting OKRs or acknowledge these objectives are founder-owned.",
+ "owner": "COO + VPs",
+ "when": "Next OKR planning cycle",
+ })
+
+ if alignment["orphaned_okrs"]:
+ recs.append({
+ "title": f"{len(alignment['orphaned_okrs'])} orphaned OKR(s) with no company objective linkage",
+ "detail": "Team OKRs that don't connect to company objectives waste capacity. "
+ "Either link them explicitly or discontinue them.",
+ "owner": "Team leads + COO",
+ "when": "OKR review session",
+ })
+
+ # Late quarter: force ranking
+ if quarter_progress >= 0.67:
+ at_risk_count = sum(
+ 1 for o in okr_tree["company"].get("objectives", [])
+ if o["status"] in ("at_risk", "off_track")
+ )
+ if at_risk_count > 0:
+ recs.append({
+ "title": f"Late quarter: force-rank which at-risk OKRs to save vs. accept as miss",
+ "detail": f"{at_risk_count} objectives at risk with <{int((1 - quarter_progress) * 13)} weeks left. "
+ "You cannot save everything. Pick the 1–2 most important and resource them fully. "
+ "Explicitly accept the others as misses and learn from them.",
+ "owner": "CEO + COO",
+ "when": "Immediately",
+ })
+
+ # Measurement gaps
+ unscored_krs = []
+ for obj in okr_tree["company"].get("objectives", []):
+ for kr in obj.get("key_results_scored", []):
+ if kr["score"] == 0.0 and kr["status"] == "not_started" and quarter_progress > 0.25:
+ unscored_krs.append(kr.get("title", kr.get("name", "Unknown")))
+
+ if unscored_krs:
+ recs.append({
+ "title": f"{len(unscored_krs)} key result(s) show no progress past Q1",
+ "detail": "KRs with zero progress after 25% of quarter has elapsed are either not started, "
+ "unmeasured, or forgotten. Require owners to update scores this week.",
+ "owner": "KR owners",
+ "when": "This week — before next leadership sync",
+ })
+
+ return recs
+
+
+def format_json_output(okr_tree: dict, alignment: dict, at_risk_krs: list[dict]) -> str:
+ """Format analysis as machine-readable JSON."""
+ return json.dumps(
+ {
+ "generated_at": datetime.now().isoformat(),
+ "company_score": (
+ sum(o["score"] for o in okr_tree["company"].get("objectives", []))
+ / max(1, len(okr_tree["company"].get("objectives", [])))
+ ),
+ "at_risk_count": len(at_risk_krs),
+ "alignment_coverage_pct": alignment["coverage_score_pct"],
+ "objectives": okr_tree["company"].get("objectives", []),
+ "departments": okr_tree["departments"],
+ "teams": okr_tree["teams"],
+ "at_risk_key_results": at_risk_krs,
+ "alignment": alignment,
+ },
+ indent=2,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Main Entrypoint
+# ---------------------------------------------------------------------------
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="OKR Cascade and Alignment Tracker — COO Advisor Tool",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=__doc__,
+ )
+ parser.add_argument("--input", "-i", help="Path to JSON OKR data file", default=None)
+ parser.add_argument("--output", "-o", help="Path to write report (default: stdout)", default=None)
+ parser.add_argument(
+ "--format", "-f",
+ choices=["text", "json"],
+ default="text",
+ help="Output format: text (default) or json",
+ )
+ parser.add_argument(
+ "--quarter-progress",
+ type=float,
+ default=None,
+ help="Override quarter progress (0.0–1.0). Default: auto-calculated from quarter dates.",
+ )
+ args = parser.parse_args()
+
+ if args.input:
+ try:
+ with open(args.input, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON: {e}", file=sys.stderr)
+ sys.exit(1)
+ else:
+ print("No input file specified — running with sample data.\n")
+ data = SAMPLE_DATA
+
+ # Determine quarter progress
+ if args.quarter_progress is not None:
+ quarter_progress = args.quarter_progress
+ else:
+ quarter_progress = _calculate_quarter_progress(data)
+
+ quarter_label = data.get("company_okrs", {}).get("quarter", "Unknown Quarter")
+
+ # Run analysis
+ okr_tree = build_okr_tree(data, quarter_progress)
+ alignment = analyze_alignment(okr_tree)
+ at_risk_krs = collect_at_risk_krs(okr_tree)
+
+ # Format output
+ if args.format == "json":
+ output = format_json_output(okr_tree, alignment, at_risk_krs)
+ else:
+ output = format_report(okr_tree, alignment, at_risk_krs, quarter_progress, quarter_label)
+
+ if args.output:
+ with open(args.output, "w") as f:
+ f.write(output)
+ print(f"Report written to: {args.output}")
+ else:
+ print(output)
+
+
+def _calculate_quarter_progress(data: dict) -> float:
+ """Auto-calculate quarter progress from start/end dates in data, or default to 0.5."""
+ q = data.get("company_okrs", {})
+ start_str = q.get("quarter_start")
+ end_str = q.get("quarter_end")
+
+ if not start_str or not end_str:
+ return 0.5 # Default to mid-quarter if not specified
+
+ try:
+ start = date.fromisoformat(start_str)
+ end = date.fromisoformat(end_str)
+ today = date.today()
+ total_days = (end - start).days
+ elapsed_days = (today - start).days
+ progress = elapsed_days / total_days if total_days > 0 else 0.5
+ return max(0.0, min(1.0, progress))
+ except (ValueError, TypeError):
+ return 0.5
+
+
+# ---------------------------------------------------------------------------
+# Sample Data
+# ---------------------------------------------------------------------------
+
+SAMPLE_DATA = {
+ "company_okrs": {
+ "name": "AcmeSaaS",
+ "quarter": "Q1 2025",
+ "quarter_start": "2025-01-01",
+ "quarter_end": "2025-03-31",
+ "objectives": [
+ {
+ "id": "CO1",
+ "title": "Achieve breakout revenue growth",
+ "owner": "CEO",
+ "key_results": [
+ {
+ "id": "CO1-KR1",
+ "title": "Reach $5M net new ARR",
+ "type": "numeric",
+ "baseline_value": 0,
+ "current_value": 2800000,
+ "target_value": 5000000,
+ "unit": "",
+ "notes": "Strong January, February softer; pipeline looks better for March",
+ },
+ {
+ "id": "CO1-KR2",
+ "title": "Achieve 115% NRR",
+ "type": "percentage",
+ "baseline_pct": 108,
+ "current_pct": 110,
+ "target_pct": 115,
+ "notes": "Expansion motion improved; churn still elevated in SMB segment",
+ },
+ {
+ "id": "CO1-KR3",
+ "title": "Close 3 enterprise deals (>$150K ACV)",
+ "type": "numeric",
+ "baseline_value": 0,
+ "current_value": 1,
+ "target_value": 3,
+ "unit": " deals",
+ "notes": "1 closed, 2 in late-stage negotiation",
+ },
+ ],
+ },
+ {
+ "id": "CO2",
+ "title": "Build a world-class product that customers love",
+ "owner": "CPO",
+ "key_results": [
+ {
+ "id": "CO2-KR1",
+ "title": "Increase feature adoption rate to 65% (% of customers using 3+ core features)",
+ "type": "percentage",
+ "baseline_pct": 48,
+ "current_pct": 52,
+ "target_pct": 65,
+ "notes": "Onboarding improvements shipped; adoption curve is moving",
+ },
+ {
+ "id": "CO2-KR2",
+ "title": "Ship the integration platform (milestone)",
+ "type": "milestone",
+ "milestones_total": 4,
+ "milestones_hit": 1,
+ "milestones": [
+ "API design complete",
+ "Internal alpha",
+ "Beta with 5 customers",
+ "GA launch",
+ ],
+ "notes": "API design shipped. Internal alpha delayed 2 weeks.",
+ },
+ {
+ "id": "CO2-KR3",
+ "title": "NPS score reaches 45",
+ "type": "numeric",
+ "baseline_value": 32,
+ "current_value": 38,
+ "target_value": 45,
+ "unit": "",
+ },
+ ],
+ },
+ {
+ "id": "CO3",
+ "title": "Build an operationally excellent company",
+ "owner": "COO",
+ "key_results": [
+ {
+ "id": "CO3-KR1",
+ "title": "Reduce burn multiple from 1.8x to 1.3x",
+ "type": "numeric",
+ "baseline_value": 1.8,
+ "current_value": 1.65,
+ "target_value": 1.3,
+ "lower_is_better": True,
+ "unit": "x",
+ },
+ {
+ "id": "CO3-KR2",
+ "title": "Achieve <30-day customer onboarding (avg)",
+ "type": "numeric",
+ "baseline_value": 47,
+ "current_value": 38,
+ "target_value": 30,
+ "lower_is_better": True,
+ "unit": " days",
+ "notes": "Good progress; blocked by technical setup step (avg 12 days)",
+ },
+ {
+ "id": "CO3-KR3",
+ "title": "Voluntary attrition <10%",
+ "type": "numeric",
+ "baseline_value": 15,
+ "current_value": 12,
+ "target_value": 10,
+ "lower_is_better": True,
+ "unit": "%",
+ "notes": "2 unexpected departures in January; retention initiatives launched",
+ },
+ ],
+ },
+ ],
+ },
+ "department_okrs": [
+ {
+ "name": "Sales",
+ "owner": "VP Sales",
+ "objectives": [
+ {
+ "title": "Drive net new ARR to hit company growth target",
+ "owner": "VP Sales",
+ "supports_company_objective_ids": ["CO1"],
+ "key_results": [
+ {
+ "title": "Close $4M in new business ARR",
+ "type": "numeric",
+ "baseline_value": 0,
+ "current_value": 2200000,
+ "target_value": 4000000,
+ "unit": "",
+ },
+ {
+ "title": "Maintain pipeline coverage ratio ≥3x",
+ "type": "numeric",
+ "baseline_value": 2.5,
+ "current_value": 3.1,
+ "target_value": 3.0,
+ "unit": "x",
+ },
+ {
+ "title": "Reduce average sales cycle to 42 days",
+ "type": "numeric",
+ "baseline_value": 58,
+ "current_value": 50,
+ "target_value": 42,
+ "lower_is_better": True,
+ "unit": " days",
+ },
+ ],
+ }
+ ],
+ },
+ {
+ "name": "Engineering",
+ "owner": "VP Engineering",
+ "objectives": [
+ {
+ "title": "Deliver the integration platform on schedule",
+ "owner": "VP Engineering",
+ "supports_company_objective_ids": ["CO2"],
+ "key_results": [
+ {
+ "title": "Integration platform beta live with 5 customers",
+ "type": "milestone",
+ "milestones_total": 3,
+ "milestones_hit": 1,
+ "notes": "Alpha delayed — dependency on API gateway refactor",
+ },
+ {
+ "title": "Deploy frequency ≥10/week",
+ "type": "numeric",
+ "baseline_value": 6,
+ "current_value": 9,
+ "target_value": 10,
+ "unit": "/week",
+ },
+ {
+ "title": "P0/P1 incidents <2 per month",
+ "type": "numeric",
+ "baseline_value": 5,
+ "current_value": 2.5,
+ "target_value": 2,
+ "lower_is_better": True,
+ "unit": "/month",
+ },
+ ],
+ }
+ ],
+ },
+ {
+ "name": "Customer Success",
+ "owner": "VP CS",
+ "objectives": [
+ {
+ "title": "Drive retention and expansion to fuel NRR growth",
+ "owner": "VP CS",
+ "supports_company_objective_ids": ["CO1", "CO2"],
+ "key_results": [
+ {
+ "title": "Gross retention ≥92%",
+ "type": "percentage",
+ "baseline_pct": 88,
+ "current_pct": 89,
+ "target_pct": 92,
+ "notes": "3 at-risk accounts in red status",
+ },
+ {
+ "title": "Average onboarding time ≤30 days",
+ "type": "numeric",
+ "baseline_value": 47,
+ "current_value": 38,
+ "target_value": 30,
+ "lower_is_better": True,
+ "unit": " days",
+ },
+ {
+ "title": "Expansion ARR from existing customers: $800K",
+ "type": "numeric",
+ "baseline_value": 0,
+ "current_value": 580000,
+ "target_value": 800000,
+ "unit": "",
+ },
+ ],
+ }
+ ],
+ },
+ ],
+ "team_okrs": [
+ {
+ "name": "Platform Engineering",
+ "department": "Engineering",
+ "objectives": [
+ {
+ "title": "Build the integration API infrastructure",
+ "supports_company_objective_ids": ["CO2"],
+ "key_results": [
+ {
+ "title": "API gateway v2 deployed to production",
+ "type": "boolean",
+ "done": False,
+ "notes": "Targeting end of week 8",
+ },
+ {
+ "title": "Webhook system handles 10K events/sec",
+ "type": "boolean",
+ "done": False,
+ },
+ {
+ "title": "P99 API latency <200ms",
+ "type": "numeric",
+ "baseline_value": 380,
+ "current_value": 290,
+ "target_value": 200,
+ "lower_is_better": True,
+ "unit": "ms",
+ },
+ ],
+ }
+ ],
+ },
+ {
+ "name": "Enterprise Sales Team",
+ "department": "Sales",
+ "objectives": [
+ {
+ "title": "Land 3 enterprise accounts",
+ "supports_company_objective_ids": ["CO1"],
+ "key_results": [
+ {
+ "title": "3 enterprise deals closed",
+ "type": "numeric",
+ "baseline_value": 0,
+ "current_value": 1,
+ "target_value": 3,
+ "unit": " deals",
+ },
+ {
+ "title": "5 enterprise POCs initiated",
+ "type": "numeric",
+ "baseline_value": 0,
+ "current_value": 4,
+ "target_value": 5,
+ "unit": " POCs",
+ },
+ ],
+ }
+ ],
+ },
+ ],
+}
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/coo-advisor/scripts/ops_efficiency_analyzer.py b/skills/c-level-advisor/coo-advisor/scripts/ops_efficiency_analyzer.py
new file mode 100644
index 00000000..1dfb0057
--- /dev/null
+++ b/skills/c-level-advisor/coo-advisor/scripts/ops_efficiency_analyzer.py
@@ -0,0 +1,1071 @@
+#!/usr/bin/env python3
+"""
+ops_efficiency_analyzer.py — Operational Efficiency Analyzer
+
+Analyzes startup operational efficiency using Theory of Constraints,
+process maturity scoring, and bottleneck identification.
+
+Usage:
+ python ops_efficiency_analyzer.py # Runs with sample data
+ python ops_efficiency_analyzer.py --input data.json # Custom data
+ python ops_efficiency_analyzer.py --input data.json --output report.txt
+
+Input format: See SAMPLE_DATA at bottom of file.
+"""
+
+import json
+import sys
+import argparse
+import math
+from datetime import datetime
+from typing import Any, Optional
+
+
+# ---------------------------------------------------------------------------
+# Data Models (plain dicts with type aliases for clarity)
+# ---------------------------------------------------------------------------
+
+ProcessData = dict[str, Any]
+TeamData = dict[str, Any]
+MetricsData = dict[str, Any]
+
+
+# ---------------------------------------------------------------------------
+# Process Maturity Scoring
+# ---------------------------------------------------------------------------
+
+MATURITY_LEVELS = {
+ 1: "Ad Hoc",
+ 2: "Defined",
+ 3: "Managed",
+ 4: "Optimized",
+ 5: "Innovating",
+}
+
+MATURITY_DESCRIPTIONS = {
+ 1: "No documented process. Outcomes depend on individual heroics.",
+ 2: "Process exists and is documented. Inconsistently followed.",
+ 3: "Process is followed consistently. Metrics are tracked.",
+ 4: "Process is optimized based on metrics. Proactively improved.",
+ 5: "Process enables competitive advantage. Continuously innovating.",
+}
+
+MATURITY_CRITERIA = {
+ "documentation": {
+ "weight": 0.20,
+ "levels": {
+ 0: "No documentation",
+ 1: "Informal notes or tribal knowledge",
+ 2: "Process documented but not maintained",
+ 3: "Documented, current, accessible",
+ 4: "Documented with examples, edge cases, and owner",
+ 5: "Living doc with version history and improvement log",
+ },
+ },
+ "ownership": {
+ "weight": 0.15,
+ "levels": {
+ 0: "No owner",
+ 1: "Unclear ownership, multiple people responsible",
+ 2: "Named team responsible",
+ 3: "Named individual DRI",
+ 4: "DRI with metrics accountability",
+ 5: "DRI with improvement mandate and resources",
+ },
+ },
+ "metrics": {
+ "weight": 0.20,
+ "levels": {
+ 0: "No metrics",
+ 1: "Anecdotal measurement",
+ 2: "Some metrics tracked, not regularly reviewed",
+ 3: "Key metrics tracked and reviewed monthly",
+ 4: "Metrics drive decisions, targets set",
+ 5: "Predictive metrics, benchmarked externally",
+ },
+ },
+ "automation": {
+ "weight": 0.20,
+ "levels": {
+ 0: "100% manual",
+ 1: "Mostly manual, some tools used",
+ 2: "Key steps automated, significant manual work remains",
+ 3: "Majority automated, manual exception handling",
+ 4: "Mostly automated with exception playbooks",
+ 5: "Fully automated with human oversight only",
+ },
+ },
+ "consistency": {
+ "weight": 0.15,
+ "levels": {
+ 0: "Never consistent",
+ 1: "Consistent <50% of time",
+ 2: "Consistent 50-75% of time",
+ 3: "Consistent 75-90% of time",
+ 4: "Consistent >90% of time",
+ 5: "Six Sigma level (>99.7%)",
+ },
+ },
+ "feedback_loop": {
+ "weight": 0.10,
+ "levels": {
+ 0: "No feedback loop",
+ 1: "Ad hoc complaints surface issues",
+ 2: "Periodic review when problems arise",
+ 3: "Regular review cadence",
+ 4: "Structured improvement cycles",
+ 5: "Real-time feedback with automated triggers",
+ },
+ },
+}
+
+
+def score_process_maturity(process: ProcessData) -> dict[str, Any]:
+ """
+ Score a single process on 1-5 maturity scale.
+ Returns scored process with dimension breakdown and recommendations.
+ """
+ maturity_inputs = process.get("maturity", {})
+ total_score = 0.0
+ dimension_scores = {}
+ recommendations = []
+
+ for dimension, config in MATURITY_CRITERIA.items():
+ raw_score = maturity_inputs.get(dimension, 0)
+ # Normalize raw score (0-5) to weight
+ normalized = (raw_score / 5.0) * config["weight"] * 5
+ total_score += normalized
+ dimension_scores[dimension] = raw_score
+
+ # Generate recommendation if below threshold
+ if raw_score < 3:
+ severity = "🔴 Critical" if raw_score < 2 else "🟡 Needs work"
+ recommendations.append({
+ "dimension": dimension,
+ "current_score": raw_score,
+ "target_score": 3,
+ "severity": severity,
+ "action": _get_improvement_action(dimension, raw_score),
+ })
+
+ # Clamp to 1-5 range (scores can't be below 1 for a running process)
+ maturity_score = max(1.0, min(5.0, total_score))
+ maturity_level = round(maturity_score)
+
+ return {
+ "name": process["name"],
+ "maturity_score": round(maturity_score, 2),
+ "maturity_level": maturity_level,
+ "maturity_label": MATURITY_LEVELS[maturity_level],
+ "dimension_scores": dimension_scores,
+ "recommendations": recommendations,
+ "process_data": process,
+ }
+
+
+def _get_improvement_action(dimension: str, current_score: int) -> str:
+ """Return a concrete improvement action for a given dimension and score."""
+ actions = {
+ "documentation": {
+ 0: "Write a basic SOP this week: trigger, steps, owner, done-definition",
+ 1: "Convert tribal knowledge into a written process doc with clear steps",
+ 2: "Assign a process owner to maintain and update documentation quarterly",
+ },
+ "ownership": {
+ 0: "Assign a DRI (Directly Responsible Individual) today",
+ 1: "Clarify ownership: assign one named person, remove ambiguity",
+ 2: "Give the named owner accountability for process metrics",
+ },
+ "metrics": {
+ 0: "Define 1-2 metrics that measure if this process is working",
+ 1: "Set up automated metric collection and add to monthly review",
+ 2: "Set targets for each metric and review monthly",
+ },
+ "automation": {
+ 0: "Identify the highest-volume manual step; automate it first",
+ 1: "Run automation ROI calc — if payback <12 months, build it",
+ 2: "Automate exception routing and error notifications",
+ },
+ "consistency": {
+ 0: "Root-cause why the process fails; fix the #1 failure mode",
+ 1: "Create a checklist for the process; require sign-off",
+ 2: "Add process adherence check to team's weekly review",
+ },
+ "feedback_loop": {
+ 0: "Add this process to monthly operational review agenda",
+ 1: "Create a feedback channel (Slack thread, form) for process issues",
+ 2: "Set a quarterly review date for this process",
+ },
+ }
+ return actions.get(dimension, {}).get(current_score, "Improve this dimension")
+
+
+# ---------------------------------------------------------------------------
+# Bottleneck Analysis (Theory of Constraints)
+# ---------------------------------------------------------------------------
+
+def analyze_bottlenecks(processes: list[ProcessData]) -> dict[str, Any]:
+ """
+ Identify bottlenecks using throughput analysis.
+ Bottleneck = step with lowest throughput (or highest queue buildup).
+ """
+ bottlenecks = []
+ throughput_chain = []
+
+ for process in processes:
+ steps = process.get("steps", [])
+ if not steps:
+ continue
+
+ step_analysis = []
+ min_throughput = float("inf")
+ bottleneck_step = None
+
+ for step in steps:
+ throughput = step.get("throughput_per_day", 0)
+ queue_depth = step.get("current_queue", 0)
+ avg_wait_hours = step.get("avg_wait_hours", 0)
+
+ # Utilization estimate
+ capacity = step.get("capacity_per_day", throughput * 1.2)
+ utilization = (throughput / capacity * 100) if capacity > 0 else 100
+
+ step_info = {
+ "name": step["name"],
+ "throughput_per_day": throughput,
+ "queue_depth": queue_depth,
+ "avg_wait_hours": avg_wait_hours,
+ "utilization_pct": round(utilization, 1),
+ "is_bottleneck": False,
+ }
+ step_analysis.append(step_info)
+
+ if throughput < min_throughput:
+ min_throughput = throughput
+ bottleneck_step = step_info
+
+ if bottleneck_step:
+ bottleneck_step["is_bottleneck"] = True
+
+ # Calculate flow efficiency
+ total_lead_time = sum(
+ s.get("avg_wait_hours", 0) + s.get("avg_process_hours", 1)
+ for s in steps
+ )
+ total_process_time = sum(s.get("avg_process_hours", 1) for s in steps)
+ flow_efficiency = (
+ (total_process_time / total_lead_time * 100)
+ if total_lead_time > 0
+ else 0
+ )
+
+ bottlenecks.append({
+ "process": process["name"],
+ "bottleneck_step": bottleneck_step["name"],
+ "bottleneck_throughput": min_throughput,
+ "bottleneck_queue": bottleneck_step["queue_depth"],
+ "flow_efficiency_pct": round(flow_efficiency, 1),
+ "steps": step_analysis,
+ "toc_recommendation": _generate_toc_recommendation(
+ bottleneck_step, process
+ ),
+ })
+
+ throughput_chain.append({
+ "process": process["name"],
+ "steps": step_analysis,
+ })
+
+ # Rank bottlenecks by severity (queue depth × utilization)
+ for b in bottlenecks:
+ b["severity_score"] = b["bottleneck_queue"] * (b["bottleneck_throughput"] or 1)
+ bottlenecks.sort(key=lambda x: x["severity_score"], reverse=True)
+
+ return {
+ "bottlenecks": bottlenecks,
+ "throughput_chain": throughput_chain,
+ }
+
+
+def _generate_toc_recommendation(bottleneck_step: dict, process: ProcessData) -> str:
+ """Generate a Theory of Constraints recommendation for a bottleneck."""
+ util = bottleneck_step["utilization_pct"]
+ queue = bottleneck_step["queue_depth"]
+ step_name = bottleneck_step["name"]
+
+ if util >= 90:
+ return (
+ f"ELEVATE: '{step_name}' is at {util}% utilization — at capacity. "
+ f"Add resources (people, automation, or parallel processing) immediately. "
+ f"Queue of {queue} units will grow until capacity is increased."
+ )
+ elif util >= 70:
+ return (
+ f"EXPLOIT: '{step_name}' has capacity headroom but is the constraint. "
+ f"Eliminate non-value-add work in this step. Protect it from interruptions. "
+ f"Ensure upstream steps feed it steadily, not in batches."
+ )
+ else:
+ return (
+ f"INVESTIGATE: '{step_name}' shows low throughput ({bottleneck_step['throughput_per_day']}/day) "
+ f"despite available capacity. Root cause may be upstream blocking, "
+ f"unclear handoffs, or quality issues requiring rework."
+ )
+
+
+# ---------------------------------------------------------------------------
+# Team Structure Analysis
+# ---------------------------------------------------------------------------
+
+def analyze_team_structure(team: TeamData) -> dict[str, Any]:
+ """
+ Analyze team structure for span of control, layer count, and hiring gaps.
+ """
+ issues = []
+ recommendations = []
+ warnings = []
+
+ total_headcount = team.get("total_headcount", 0)
+ departments = team.get("departments", [])
+
+ # Span of control analysis
+ span_issues = []
+ for dept in departments:
+ for manager in dept.get("managers", []):
+ direct_reports = manager.get("direct_reports", 0)
+ manages_managers = manager.get("manages_managers", False)
+
+ optimal_min = 3 if manages_managers else 5
+ optimal_max = 5 if manages_managers else 8
+
+ if direct_reports < optimal_min:
+ span_issues.append({
+ "manager": manager["name"],
+ "dept": dept["name"],
+ "reports": direct_reports,
+ "issue": "Under-span",
+ "recommendation": f"Merge team or promote ICs — {direct_reports} reports is management overhead",
+ })
+ elif direct_reports > optimal_max:
+ span_issues.append({
+ "manager": manager["name"],
+ "dept": dept["name"],
+ "reports": direct_reports,
+ "issue": "Over-span",
+ "recommendation": f"Split team — {direct_reports} reports means minimal 1:1 time and poor feedback loops",
+ })
+
+ # Management layers analysis
+ max_layers = team.get("management_layers", 0)
+ expected_layers = _expected_layers(total_headcount)
+ if max_layers > expected_layers + 1:
+ issues.append({
+ "type": "Over-layered",
+ "detail": f"{max_layers} management layers for {total_headcount} people. "
+ f"Expected: {expected_layers}. Excess layers slow decisions.",
+ "recommendation": "Flatten: remove middle management layers that don't add decision value",
+ })
+
+ # Revenue per employee by department
+ annual_revenue = team.get("annual_revenue_usd", 0)
+ dept_analysis = []
+ for dept in departments:
+ headcount = dept.get("headcount", 0)
+ if headcount > 0 and annual_revenue > 0:
+ rev_per_employee = annual_revenue / headcount
+ benchmark = _dept_revenue_benchmark(dept["name"], team.get("stage", "series_a"))
+ efficiency_pct = (rev_per_employee / benchmark * 100) if benchmark > 0 else None
+
+ dept_analysis.append({
+ "department": dept["name"],
+ "headcount": headcount,
+ "revenue_per_employee": round(rev_per_employee),
+ "benchmark": benchmark,
+ "efficiency_vs_benchmark_pct": round(efficiency_pct, 1) if efficiency_pct else "N/A",
+ "status": _efficiency_status(efficiency_pct),
+ })
+
+ # Open req health
+ open_reqs = team.get("open_requisitions", 0)
+ req_to_headcount_ratio = (open_reqs / total_headcount * 100) if total_headcount > 0 else 0
+ if req_to_headcount_ratio > 20:
+ warnings.append(
+ f"High open req ratio: {open_reqs} open reqs against {total_headcount} headcount "
+ f"({req_to_headcount_ratio:.0f}%). This level of hiring while operating is operationally disruptive."
+ )
+
+ return {
+ "total_headcount": total_headcount,
+ "management_layers": max_layers,
+ "expected_layers": expected_layers,
+ "span_of_control_issues": span_issues,
+ "structural_issues": issues,
+ "department_efficiency": dept_analysis,
+ "open_req_health": {
+ "open_reqs": open_reqs,
+ "ratio_pct": round(req_to_headcount_ratio, 1),
+ "warnings": warnings,
+ },
+ }
+
+
+def _expected_layers(headcount: int) -> int:
+ if headcount <= 15:
+ return 1
+ elif headcount <= 50:
+ return 2
+ elif headcount <= 150:
+ return 3
+ elif headcount <= 500:
+ return 4
+ else:
+ return 5
+
+
+def _dept_revenue_benchmark(dept_name: str, stage: str) -> int:
+ """Revenue per employee benchmark by department and stage (USD)."""
+ benchmarks = {
+ "series_a": {
+ "engineering": 400000,
+ "sales": 250000,
+ "customer_success": 300000,
+ "marketing": 500000,
+ "operations": 400000,
+ "product": 400000,
+ "default": 200000,
+ },
+ "series_b": {
+ "engineering": 500000,
+ "sales": 350000,
+ "customer_success": 400000,
+ "marketing": 700000,
+ "operations": 500000,
+ "product": 500000,
+ "default": 300000,
+ },
+ "series_c": {
+ "engineering": 600000,
+ "sales": 450000,
+ "customer_success": 500000,
+ "marketing": 900000,
+ "operations": 600000,
+ "product": 600000,
+ "default": 400000,
+ },
+ }
+ stage_data = benchmarks.get(stage, benchmarks["series_a"])
+ dept_key = dept_name.lower().replace(" ", "_").replace("-", "_")
+ return stage_data.get(dept_key, stage_data["default"])
+
+
+def _efficiency_status(efficiency_pct: Optional[float]) -> str:
+ if efficiency_pct is None:
+ return "N/A"
+ if efficiency_pct >= 90:
+ return "🟢 On benchmark"
+ elif efficiency_pct >= 70:
+ return "🟡 Below benchmark"
+ else:
+ return "🔴 Significantly below"
+
+
+# ---------------------------------------------------------------------------
+# Improvement Plan Generator
+# ---------------------------------------------------------------------------
+
+def generate_improvement_plan(
+ process_scores: list[dict],
+ bottleneck_analysis: dict,
+ team_analysis: dict,
+ metrics: MetricsData,
+) -> list[dict]:
+ """
+ Generate a prioritized improvement plan combining all analysis outputs.
+ Priority = Impact × Urgency / Effort
+ """
+ items = []
+
+ # Priority 1: Process bottlenecks (Theory of Constraints — fix the constraint first)
+ for b in bottleneck_analysis.get("bottlenecks", [])[:3]:
+ items.append({
+ "priority": 1,
+ "category": "Bottleneck",
+ "item": f"Resolve bottleneck in '{b['process']}' at step '{b['bottleneck_step']}'",
+ "detail": b["toc_recommendation"],
+ "impact": "HIGH — constraint limits entire system throughput",
+ "effort": "MEDIUM",
+ "owner_suggestion": "COO + process owner",
+ "timebox": "2-4 weeks",
+ "success_metric": f"Throughput at {b['bottleneck_step']} increases by 25%+",
+ })
+
+ # Priority 2: Critical process maturity gaps
+ critical_processes = [
+ p for p in process_scores if p["maturity_score"] < 2.0
+ ]
+ for proc in sorted(critical_processes, key=lambda x: x["maturity_score"]):
+ for rec in proc["recommendations"][:2]: # Top 2 recs per critical process
+ items.append({
+ "priority": 2,
+ "category": "Process Maturity",
+ "item": f"Fix {rec['dimension']} in '{proc['name']}' (score: {rec['current_score']}/5)",
+ "detail": rec["action"],
+ "impact": "HIGH — ad-hoc processes create inconsistency and risk",
+ "effort": "LOW-MEDIUM",
+ "owner_suggestion": "Process owner",
+ "timebox": "1-2 weeks",
+ "success_metric": f"Dimension score improves to 3/5",
+ })
+
+ # Priority 3: Team structural issues
+ for issue in team_analysis.get("structural_issues", []):
+ items.append({
+ "priority": 3,
+ "category": "Org Structure",
+ "item": issue["type"],
+ "detail": issue["detail"],
+ "impact": "MEDIUM — structural issues compound over time",
+ "effort": "HIGH",
+ "owner_suggestion": "COO + People",
+ "timebox": "1-2 quarters",
+ "success_metric": "Management layer count normalized",
+ })
+
+ for span_issue in team_analysis.get("span_of_control_issues", []):
+ severity = "HIGH" if span_issue["issue"] == "Over-span" else "MEDIUM"
+ items.append({
+ "priority": 3,
+ "category": "Span of Control",
+ "item": f"{span_issue['issue']}: {span_issue['manager']} ({span_issue['dept']})",
+ "detail": span_issue["recommendation"],
+ "impact": severity,
+ "effort": "MEDIUM",
+ "owner_suggestion": f"VP {span_issue['dept']}",
+ "timebox": "1 quarter",
+ "success_metric": "Span within 5-8 for ICs, 3-5 for managers",
+ })
+
+ # Priority 4: Maturity improvements for non-critical processes
+ medium_processes = [
+ p for p in process_scores if 2.0 <= p["maturity_score"] < 3.5
+ ]
+ for proc in sorted(medium_processes, key=lambda x: x["maturity_score"])[:3]:
+ if proc["recommendations"]:
+ top_rec = proc["recommendations"][0]
+ items.append({
+ "priority": 4,
+ "category": "Process Improvement",
+ "item": f"Improve {top_rec['dimension']} in '{proc['name']}'",
+ "detail": top_rec["action"],
+ "impact": "MEDIUM",
+ "effort": "LOW",
+ "owner_suggestion": "Process owner",
+ "timebox": "2-4 weeks",
+ "success_metric": f"Dimension score reaches 3/5",
+ })
+
+ # Priority 5: Metrics-driven flags
+ burn_multiple = metrics.get("burn_multiple")
+ if burn_multiple and burn_multiple > 2.0:
+ items.append({
+ "priority": 2,
+ "category": "Financial Efficiency",
+ "item": f"Burn multiple of {burn_multiple:.1f}x is above healthy range",
+ "detail": "Burn multiple >1.5x indicates spending exceeds efficient growth. Review headcount-to-revenue ratio by department.",
+ "impact": "HIGH",
+ "effort": "MEDIUM",
+ "owner_suggestion": "COO + CFO",
+ "timebox": "30 days to diagnose, 60-90 days to act",
+ "success_metric": "Burn multiple <1.5x within 2 quarters",
+ })
+
+ nrr = metrics.get("net_revenue_retention_pct")
+ if nrr and nrr < 100:
+ items.append({
+ "priority": 1,
+ "category": "Revenue Health",
+ "item": f"NRR of {nrr}% — losing more from churn/contraction than gaining from expansion",
+ "detail": "NRR <100% means the customer base shrinks without new sales. Investigate churn root causes immediately.",
+ "impact": "CRITICAL",
+ "effort": "HIGH",
+ "owner_suggestion": "COO + VP CS",
+ "timebox": "Immediate — 30 days to root cause, 90 days to fix",
+ "success_metric": "NRR >100% within 2 quarters",
+ })
+
+ # Sort by priority then impact
+ priority_order = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
+ items.sort(key=lambda x: (x["priority"], priority_order.get(x["impact"].split(" — ")[0], 9)))
+
+ return items
+
+
+# ---------------------------------------------------------------------------
+# Report Formatter
+# ---------------------------------------------------------------------------
+
+def format_report(
+ process_scores: list[dict],
+ bottleneck_analysis: dict,
+ team_analysis: dict,
+ improvement_plan: list[dict],
+ metrics: MetricsData,
+) -> str:
+ """Format the full analysis report as plain text."""
+ lines = []
+ now = datetime.now().strftime("%Y-%m-%d %H:%M")
+
+ lines.append("=" * 70)
+ lines.append("OPERATIONAL EFFICIENCY ANALYSIS REPORT")
+ lines.append(f"Generated: {now}")
+ lines.append("=" * 70)
+
+ # --- Executive Summary ---
+ lines.append("\n📊 EXECUTIVE SUMMARY")
+ lines.append("-" * 40)
+
+ avg_maturity = (
+ sum(p["maturity_score"] for p in process_scores) / len(process_scores)
+ if process_scores else 0
+ )
+ critical_count = sum(1 for p in process_scores if p["maturity_score"] < 2.0)
+ bottleneck_count = len(bottleneck_analysis.get("bottlenecks", []))
+ plan_items = len(improvement_plan)
+
+ lines.append(f"Average Process Maturity: {avg_maturity:.1f}/5.0 ({MATURITY_LEVELS.get(round(avg_maturity), 'Unknown')})")
+ lines.append(f"Critical Process Gaps: {critical_count}")
+ lines.append(f"Active Bottlenecks: {bottleneck_count}")
+ lines.append(f"Improvement Plan Items: {plan_items}")
+
+ if metrics:
+ lines.append("\nKey Business Metrics:")
+ if metrics.get("burn_multiple"):
+ flag = " ⚠️" if metrics["burn_multiple"] > 2.0 else ""
+ lines.append(f" Burn Multiple: {metrics['burn_multiple']:.1f}x{flag}")
+ if metrics.get("net_revenue_retention_pct"):
+ flag = " ⚠️" if metrics["net_revenue_retention_pct"] < 100 else ""
+ lines.append(f" NRR: {metrics['net_revenue_retention_pct']}%{flag}")
+ if metrics.get("cac_payback_months"):
+ flag = " ⚠️" if metrics["cac_payback_months"] > 18 else ""
+ lines.append(f" CAC Payback: {metrics['cac_payback_months']} months{flag}")
+
+ # --- Process Maturity Scores ---
+ lines.append("\n\n📋 PROCESS MATURITY SCORES")
+ lines.append("-" * 40)
+ lines.append(f"{'Process':<35} {'Score':>6} {'Level':<12} {'Status'}")
+ lines.append(f"{'─'*35} {'─'*6} {'─'*12} {'─'*20}")
+
+ for p in sorted(process_scores, key=lambda x: x["maturity_score"]):
+ score = p["maturity_score"]
+ label = p["maturity_label"]
+ status = "🔴 Critical" if score < 2 else ("🟡 Needs work" if score < 3.5 else "🟢 Healthy")
+ lines.append(f"{p['name']:<35} {score:>6.1f} {label:<12} {status}")
+
+ # Dimension heatmap
+ lines.append("\n\nDimension Breakdown (scores 0-5):")
+ lines.append(f"{'Process':<30} {'Doc':>4} {'Own':>4} {'Met':>4} {'Aut':>4} {'Con':>4} {'Fbk':>4}")
+ lines.append(f"{'─'*30} {'─'*4} {'─'*4} {'─'*4} {'─'*4} {'─'*4} {'─'*4}")
+ for p in sorted(process_scores, key=lambda x: x["maturity_score"]):
+ d = p["dimension_scores"]
+ lines.append(
+ f"{p['name']:<30} {d.get('documentation',0):>4} {d.get('ownership',0):>4} "
+ f"{d.get('metrics',0):>4} {d.get('automation',0):>4} "
+ f"{d.get('consistency',0):>4} {d.get('feedback_loop',0):>4}"
+ )
+
+ # --- Bottleneck Analysis ---
+ lines.append("\n\n🔍 BOTTLENECK ANALYSIS (Theory of Constraints)")
+ lines.append("-" * 40)
+
+ bottlenecks = bottleneck_analysis.get("bottlenecks", [])
+ if not bottlenecks:
+ lines.append("No process steps defined for bottleneck analysis.")
+ else:
+ for i, b in enumerate(bottlenecks, 1):
+ lines.append(f"\n{i}. {b['process']}")
+ lines.append(f" Bottleneck step: {b['bottleneck_step']}")
+ lines.append(f" Throughput: {b['bottleneck_throughput']}/day")
+ lines.append(f" Queue depth: {b['bottleneck_queue']} units")
+ lines.append(f" Flow efficiency: {b['flow_efficiency_pct']}%")
+ lines.append(f" Recommendation: {b['toc_recommendation']}")
+
+ lines.append(f"\n Step-by-step throughput:")
+ for step in b["steps"]:
+ marker = " ← BOTTLENECK" if step["is_bottleneck"] else ""
+ lines.append(
+ f" {step['name']:<30} {step['throughput_per_day']:>4}/day "
+ f"Queue: {step['queue_depth']:>4} Util: {step['utilization_pct']:>5.1f}%{marker}"
+ )
+
+ # --- Team Structure ---
+ lines.append("\n\n👥 TEAM STRUCTURE ANALYSIS")
+ lines.append("-" * 40)
+ lines.append(f"Total headcount: {team_analysis['total_headcount']}")
+ lines.append(f"Management layers: {team_analysis['management_layers']} (expected: {team_analysis['expected_layers']})")
+
+ span_issues = team_analysis.get("span_of_control_issues", [])
+ if span_issues:
+ lines.append(f"\n⚠️ Span of Control Issues ({len(span_issues)}):")
+ for issue in span_issues:
+ lines.append(f" {issue['issue']}: {issue['manager']} ({issue['dept']}) — {issue['reports']} reports")
+ lines.append(f" → {issue['recommendation']}")
+
+ dept_eff = team_analysis.get("department_efficiency", [])
+ if dept_eff:
+ lines.append(f"\nDepartment Revenue Efficiency:")
+ lines.append(f"{'Department':<20} {'HC':>4} {'Rev/Head':>10} {'Benchmark':>10} {'vs Bench':>9} {'Status'}")
+ lines.append(f"{'─'*20} {'─'*4} {'─'*10} {'─'*10} {'─'*9} {'─'*20}")
+ for d in dept_eff:
+ rev = f"${d['revenue_per_employee']:,}" if d['revenue_per_employee'] else "N/A"
+ bench = f"${d['benchmark']:,}" if d['benchmark'] else "N/A"
+ vs_bench = f"{d['efficiency_vs_benchmark_pct']}%" if d['efficiency_vs_benchmark_pct'] != "N/A" else "N/A"
+ lines.append(
+ f"{d['department']:<20} {d['headcount']:>4} {rev:>10} {bench:>10} {vs_bench:>9} {d['status']}"
+ )
+
+ # --- Improvement Plan ---
+ lines.append("\n\n🎯 PRIORITIZED IMPROVEMENT PLAN")
+ lines.append("-" * 40)
+ lines.append("Items ranked by priority (1=highest). Fix Priority 1 before starting Priority 2.\n")
+
+ current_priority = None
+ for i, item in enumerate(improvement_plan, 1):
+ if item["priority"] != current_priority:
+ current_priority = item["priority"]
+ lines.append(f"\nPRIORITY {current_priority}")
+ lines.append("─" * 30)
+
+ lines.append(f"\n{i}. [{item['category']}] {item['item']}")
+ lines.append(f" Detail: {item['detail']}")
+ lines.append(f" Impact: {item['impact']}")
+ lines.append(f" Effort: {item['effort']}")
+ lines.append(f" Owner: {item['owner_suggestion']}")
+ lines.append(f" Timebox: {item['timebox']}")
+ lines.append(f" Success: {item['success_metric']}")
+
+ lines.append("\n" + "=" * 70)
+ lines.append("END OF REPORT")
+ lines.append("=" * 70)
+
+ return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Main Entrypoint
+# ---------------------------------------------------------------------------
+
+def run_analysis(data: dict) -> str:
+ """Run the full analysis pipeline on input data."""
+ processes = data.get("processes", [])
+ team = data.get("team", {})
+ metrics = data.get("metrics", {})
+
+ # 1. Score process maturity
+ process_scores = [score_process_maturity(p) for p in processes]
+
+ # 2. Analyze bottlenecks
+ bottleneck_analysis = analyze_bottlenecks(processes)
+
+ # 3. Analyze team structure
+ team_analysis = analyze_team_structure(team)
+
+ # 4. Generate improvement plan
+ improvement_plan = generate_improvement_plan(
+ process_scores, bottleneck_analysis, team_analysis, metrics
+ )
+
+ # 5. Format and return report
+ return format_report(
+ process_scores, bottleneck_analysis, team_analysis, improvement_plan, metrics
+ )
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Operational Efficiency Analyzer — COO Advisor Tool",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=__doc__,
+ )
+ parser.add_argument(
+ "--input", "-i",
+ help="Path to JSON input file (default: use built-in sample data)",
+ default=None,
+ )
+ parser.add_argument(
+ "--output", "-o",
+ help="Path to write report (default: stdout)",
+ default=None,
+ )
+ args = parser.parse_args()
+
+ if args.input:
+ try:
+ with open(args.input, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in input file: {e}", file=sys.stderr)
+ sys.exit(1)
+ else:
+ print("No input file specified — running with sample data.\n")
+ data = SAMPLE_DATA
+
+ report = run_analysis(data)
+
+ if args.output:
+ with open(args.output, "w") as f:
+ f.write(report)
+ print(f"Report written to: {args.output}")
+ else:
+ print(report)
+
+
+# ---------------------------------------------------------------------------
+# Sample Data
+# ---------------------------------------------------------------------------
+
+SAMPLE_DATA = {
+ "company": "AcmeSaaS",
+ "stage": "series_b",
+ "metrics": {
+ "annual_revenue_usd": 18000000,
+ "burn_multiple": 1.8,
+ "net_revenue_retention_pct": 108,
+ "cac_payback_months": 14,
+ "headcount": 85,
+ "monthly_churn_pct": 1.2,
+ },
+ "processes": [
+ {
+ "name": "Customer Onboarding",
+ "category": "Customer Success",
+ "maturity": {
+ "documentation": 3,
+ "ownership": 4,
+ "metrics": 3,
+ "automation": 2,
+ "consistency": 3,
+ "feedback_loop": 2,
+ },
+ "steps": [
+ {
+ "name": "Contract signed → kickoff scheduled",
+ "throughput_per_day": 4,
+ "capacity_per_day": 6,
+ "current_queue": 3,
+ "avg_wait_hours": 4,
+ "avg_process_hours": 1,
+ },
+ {
+ "name": "Technical setup & integration",
+ "throughput_per_day": 2,
+ "capacity_per_day": 3,
+ "current_queue": 8,
+ "avg_wait_hours": 24,
+ "avg_process_hours": 8,
+ },
+ {
+ "name": "Training & enablement",
+ "throughput_per_day": 3,
+ "capacity_per_day": 4,
+ "current_queue": 2,
+ "avg_wait_hours": 8,
+ "avg_process_hours": 4,
+ },
+ {
+ "name": "Go-live confirmation",
+ "throughput_per_day": 4,
+ "capacity_per_day": 6,
+ "current_queue": 1,
+ "avg_wait_hours": 2,
+ "avg_process_hours": 1,
+ },
+ ],
+ },
+ {
+ "name": "Sales Deal Qualification",
+ "category": "Sales",
+ "maturity": {
+ "documentation": 2,
+ "ownership": 3,
+ "metrics": 4,
+ "automation": 2,
+ "consistency": 2,
+ "feedback_loop": 3,
+ },
+ "steps": [
+ {
+ "name": "Inbound lead review",
+ "throughput_per_day": 15,
+ "capacity_per_day": 20,
+ "current_queue": 5,
+ "avg_wait_hours": 2,
+ "avg_process_hours": 0.5,
+ },
+ {
+ "name": "BANT qualification call",
+ "throughput_per_day": 8,
+ "capacity_per_day": 10,
+ "current_queue": 12,
+ "avg_wait_hours": 24,
+ "avg_process_hours": 1,
+ },
+ {
+ "name": "Demo scheduling & prep",
+ "throughput_per_day": 6,
+ "capacity_per_day": 8,
+ "current_queue": 4,
+ "avg_wait_hours": 8,
+ "avg_process_hours": 0.5,
+ },
+ ],
+ },
+ {
+ "name": "Engineering Deployment",
+ "category": "Engineering",
+ "maturity": {
+ "documentation": 4,
+ "ownership": 5,
+ "metrics": 4,
+ "automation": 4,
+ "consistency": 5,
+ "feedback_loop": 4,
+ },
+ "steps": [
+ {
+ "name": "PR submitted",
+ "throughput_per_day": 20,
+ "capacity_per_day": 25,
+ "current_queue": 8,
+ "avg_wait_hours": 3,
+ "avg_process_hours": 2,
+ },
+ {
+ "name": "Code review",
+ "throughput_per_day": 18,
+ "capacity_per_day": 22,
+ "current_queue": 10,
+ "avg_wait_hours": 4,
+ "avg_process_hours": 1,
+ },
+ {
+ "name": "CI pipeline",
+ "throughput_per_day": 18,
+ "capacity_per_day": 30,
+ "current_queue": 2,
+ "avg_wait_hours": 0.5,
+ "avg_process_hours": 0.5,
+ },
+ {
+ "name": "Deploy to production",
+ "throughput_per_day": 16,
+ "capacity_per_day": 20,
+ "current_queue": 1,
+ "avg_wait_hours": 0.5,
+ "avg_process_hours": 0.25,
+ },
+ ],
+ },
+ {
+ "name": "Incident Response",
+ "category": "Engineering / Operations",
+ "maturity": {
+ "documentation": 2,
+ "ownership": 2,
+ "metrics": 1,
+ "automation": 1,
+ "consistency": 2,
+ "feedback_loop": 1,
+ },
+ "steps": [],
+ },
+ {
+ "name": "Employee Onboarding",
+ "category": "People",
+ "maturity": {
+ "documentation": 2,
+ "ownership": 2,
+ "metrics": 1,
+ "automation": 1,
+ "consistency": 2,
+ "feedback_loop": 2,
+ },
+ "steps": [],
+ },
+ {
+ "name": "Vendor Procurement",
+ "category": "Operations",
+ "maturity": {
+ "documentation": 1,
+ "ownership": 1,
+ "metrics": 0,
+ "automation": 0,
+ "consistency": 1,
+ "feedback_loop": 0,
+ },
+ "steps": [],
+ },
+ ],
+ "team": {
+ "total_headcount": 85,
+ "annual_revenue_usd": 18000000,
+ "stage": "series_b",
+ "management_layers": 3,
+ "open_requisitions": 18,
+ "departments": [
+ {
+ "name": "Engineering",
+ "headcount": 32,
+ "managers": [
+ {"name": "VP Engineering", "direct_reports": 4, "manages_managers": True},
+ {"name": "Engineering Manager (Platform)", "direct_reports": 7, "manages_managers": False},
+ {"name": "Engineering Manager (Product)", "direct_reports": 8, "manages_managers": False},
+ {"name": "Engineering Manager (Infra)", "direct_reports": 9, "manages_managers": False},
+ ],
+ },
+ {
+ "name": "Sales",
+ "headcount": 18,
+ "managers": [
+ {"name": "VP Sales", "direct_reports": 3, "manages_managers": True},
+ {"name": "Sales Manager (SMB)", "direct_reports": 6, "manages_managers": False},
+ {"name": "Sales Manager (Enterprise)", "direct_reports": 4, "manages_managers": False},
+ ],
+ },
+ {
+ "name": "Customer Success",
+ "headcount": 12,
+ "managers": [
+ {"name": "VP CS", "direct_reports": 2, "manages_managers": False},
+ ],
+ },
+ {
+ "name": "Marketing",
+ "headcount": 8,
+ "managers": [
+ {"name": "VP Marketing", "direct_reports": 7, "manages_managers": False},
+ ],
+ },
+ {
+ "name": "Operations",
+ "headcount": 6,
+ "managers": [
+ {"name": "COO", "direct_reports": 5, "manages_managers": True},
+ ],
+ },
+ {
+ "name": "Product",
+ "headcount": 9,
+ "managers": [
+ {"name": "VP Product", "direct_reports": 8, "manages_managers": False},
+ ],
+ },
+ ],
+ },
+}
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cpo-advisor/SKILL.md b/skills/c-level-advisor/cpo-advisor/SKILL.md
new file mode 100644
index 00000000..d7456a4f
--- /dev/null
+++ b/skills/c-level-advisor/cpo-advisor/SKILL.md
@@ -0,0 +1,200 @@
+---
+name: "cpo-advisor"
+description: "Product leadership for scaling companies. Product vision, portfolio strategy, product-market fit, and product org design. Use when setting product vision, managing a product portfolio, measuring PMF, designing product teams, prioritizing at the portfolio level, reporting to the board on product, or when user mentions CPO, product strategy, product-market fit, product organization, portfolio prioritization, or roadmap strategy."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: cpo-leadership
+ updated: 2026-03-05
+ python-tools: pmf_scorer.py, portfolio_analyzer.py
+ frameworks: pmf-playbook, product-strategy, product-org-design
+---
+
+# CPO Advisor
+
+Strategic product leadership. Vision, portfolio, PMF, org design. Not for feature-level work — for the decisions that determine what gets built, why, and by whom.
+
+## Keywords
+CPO, chief product officer, product strategy, product vision, product-market fit, PMF, portfolio management, product org, roadmap strategy, product metrics, north star metric, retention curve, product trio, team topologies, Jobs to be Done, category design, product positioning, board product reporting, invest-maintain-kill, BCG matrix, switching costs, network effects
+
+## Quick Start
+
+### Score Your Product-Market Fit
+```bash
+python scripts/pmf_scorer.py
+```
+Multi-dimensional PMF score across retention, engagement, satisfaction, and growth.
+
+### Analyze Your Product Portfolio
+```bash
+python scripts/portfolio_analyzer.py
+```
+BCG matrix classification, investment recommendations, portfolio health score.
+
+## The CPO's Core Responsibilities
+
+The CPO owns three things. Everything else is delegation.
+
+| Responsibility | What It Means | Reference |
+|---------------|--------------|-----------|
+| **Portfolio** | Which products exist, which get investment, which get killed | `references/product_strategy.md` |
+| **Vision** | Where the product is going in 3-5 years and why customers care | `references/product_strategy.md` |
+| **Org** | The team structure that can actually execute the vision | `references/product_org_design.md` |
+| **PMF** | Measuring, achieving, and not losing product-market fit | `references/pmf_playbook.md` |
+| **Metrics** | North star → leading → lagging hierarchy, board reporting | This file |
+
+## Diagnostic Questions
+
+These questions expose whether you have a strategy or a list.
+
+**Portfolio:**
+- Which product is the dog? Are you killing it or lying to yourself?
+- If you had to cut 30% of your portfolio tomorrow, what stays?
+- What's your portfolio's combined D30 retention? Is it trending up?
+
+**PMF:**
+- What's your retention curve for your best cohort?
+- What % of users would be "very disappointed" if your product disappeared?
+- Is organic growth happening without you pushing it?
+
+**Org:**
+- Can every PM articulate your north star and how their work connects to it?
+- When did your last product trio do user interviews together?
+- What's blocking your slowest team — the people or the structure?
+
+**Strategy:**
+- If you could only ship one thing this quarter, what is it and why?
+- What's your moat in 12 months? In 3 years?
+- What's the riskiest assumption in your current product strategy?
+
+## Product Metrics Hierarchy
+
+```
+North Star Metric (1, owned by CPO)
+ ↓ explains changes in
+Leading Indicators (3-5, owned by PMs)
+ ↓ eventually become
+Lagging Indicators (revenue, churn, NPS)
+```
+
+**North Star rules:** One number. Measures customer value delivered, not revenue. Every team can influence it.
+
+**Good North Stars by business model:**
+
+| Model | North Star Example |
+|-------|------------------|
+| B2B SaaS | Weekly active accounts using core feature |
+| Consumer | D30 retained users |
+| Marketplace | Successful transactions per week |
+| PLG | Accounts reaching "aha moment" within 14 days |
+| Data product | Queries run per active user per week |
+
+### The CPO Dashboard
+
+| Category | Metric | Frequency |
+|----------|--------|-----------|
+| Growth | North star metric | Weekly |
+| Growth | D30 / D90 retention by cohort | Weekly |
+| Acquisition | New activations | Weekly |
+| Activation | Time to "aha moment" | Weekly |
+| Engagement | DAU/MAU ratio | Weekly |
+| Satisfaction | NPS trend | Monthly |
+| Portfolio | Revenue per product | Monthly |
+| Portfolio | Engineering investment % per product | Monthly |
+| Moat | Feature adoption depth | Monthly |
+
+## Investment Postures
+
+Every product gets one: **Invest / Maintain / Kill**. "Wait and see" is not a posture — it's a decision to lose share.
+
+| Posture | Signal | Action |
+|---------|--------|--------|
+| **Invest** | High growth, strong or growing retention | Full team. Aggressive roadmap. |
+| **Maintain** | Stable revenue, slow growth, good margins | Bug fixes only. Milk it. |
+| **Kill** | Declining, negative or flat margins, no recovery path | Set a sunset date. Write a migration plan. |
+
+## Red Flags
+
+**Portfolio:**
+- Products that have been "question marks" for 2+ quarters without a decision
+- Engineering capacity allocated to your highest-revenue product but your highest-growth product is understaffed
+- More than 30% of team time on products with declining revenue
+
+**PMF:**
+- You have to convince users to keep using the product
+- Support requests are mostly "how do I do X" rather than "I want X to also do Y"
+- D30 retention is below 20% (consumer) or 40% (B2B) and not improving
+
+**Org:**
+- PMs writing specs and handing to design, who hands to engineering (waterfall in agile clothing)
+- Platform team has a 6-week queue for stream-aligned team requests
+- CPO has not talked to a real customer in 30+ days
+
+**Metrics:**
+- North star going up while retention is going down (metric is wrong)
+- Teams optimizing their own metrics at the expense of company metrics
+- Roadmap built from sales requests, not user behavior data
+
+## Integration with Other C-Suite Roles
+
+| When... | CPO works with... | To... |
+|---------|-------------------|-------|
+| Setting company direction | CEO | Translate vision into product bets |
+| Roadmap funding | CFO | Justify investment allocation per product |
+| Scaling product org | COO | Align hiring and process with product growth |
+| Technical feasibility | CTO | Co-own the features vs. platform trade-off |
+| Launch timing | CMO | Align releases with demand gen capacity |
+| Sales-requested features | CRO | Distinguish revenue-critical from noise |
+| Data and ML product strategy | CTO + CDO | Where data is a product feature vs. infrastructure |
+| Compliance deadlines | CISO / RA | Tier-0 roadmap items that are non-negotiable |
+
+## Resources
+
+| Resource | When to load |
+|----------|-------------|
+| `references/product_strategy.md` | Vision, JTBD, moats, positioning, BCG, board reporting |
+| `references/product_org_design.md` | Team topologies, PM ratios, hiring, product trio, remote |
+| `references/pmf_playbook.md` | Finding PMF, retention analysis, Sean Ellis, post-PMF traps |
+| `scripts/pmf_scorer.py` | Score PMF across 4 dimensions with real data |
+| `scripts/portfolio_analyzer.py` | BCG classify and score your product portfolio |
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Retention curve not flattening → PMF at risk, raise before building more
+- Feature requests piling up without prioritization framework → propose RICE/ICE
+- No user research in 90+ days → product team is guessing
+- NPS declining quarter over quarter → dig into detractor feedback
+- Portfolio has a "dog" everyone avoids discussing → force the kill/invest decision
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Do we have PMF?" | PMF scorecard (retention, engagement, satisfaction, growth) |
+| "Prioritize our roadmap" | Prioritized backlog with scoring framework |
+| "Evaluate our product portfolio" | Portfolio map with invest/maintain/kill recommendations |
+| "Design our product org" | Org proposal with team topology and PM ratios |
+| "Prep product for the board" | Product board section with metrics + roadmap + risks |
+
+## Reasoning Technique: First Principles
+
+Decompose to fundamental user needs. Question every assumption about what customers want. Rebuild from validated evidence, not inherited roadmaps.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/c-level-advisor/cpo-advisor/references/pmf_playbook.md b/skills/c-level-advisor/cpo-advisor/references/pmf_playbook.md
new file mode 100644
index 00000000..847700f8
--- /dev/null
+++ b/skills/c-level-advisor/cpo-advisor/references/pmf_playbook.md
@@ -0,0 +1,307 @@
+# PMF Playbook
+
+How to find product-market fit, measure it, and not lose it. Steps, not theory.
+
+---
+
+## What PMF Actually Is
+
+PMF is when a product pulls users in rather than pushing them. Signals:
+- Users find the product without you telling them about it
+- They're upset when it doesn't work
+- They bring their colleagues, their friends, their boss
+- They build workarounds when a feature is missing
+
+PMF is not:
+- Users saying they like it
+- A good NPS score with flat growth
+- Enterprise customers who are locked in but churning at contract end
+
+---
+
+## Step 1: Find Your Best Customers First
+
+Before measuring PMF across everyone, find the segment where PMF is strongest.
+
+**How:**
+1. Export a list of all churned users and all retained users (D90+)
+2. Identify 5-10 attributes to compare: company size, industry, job title, signup source, first action taken, time to first value
+3. Find the attributes that are over-represented in retained vs. churned
+4. That's your highest-PMF segment
+
+**This is not an analytics project.** Call 10 retained power users. Ask:
+- "What were you doing before you found us?"
+- "What would you use if we shut down tomorrow?"
+- "Who else in your life has this problem?"
+
+The segment where this conversation is easy and the answers are specific — that's where your PMF is.
+
+---
+
+## Step 2: Measure the Three PMF Signals
+
+Run all three. They measure different things. One signal without the others is misleading.
+
+### Signal 1: Retention Curves
+
+**Method:**
+1. Cohort users by week or month of first use
+2. Calculate % still active at D1, D7, D14, D30, D60, D90
+3. Plot the curve for each cohort
+
+**Interpretation:**
+
+| Curve Shape | What It Means |
+|-------------|--------------|
+| Drops to zero | No PMF. Product doesn't solve a recurring problem. |
+| Drops and keeps dropping | Weak PMF. Some people find value, but not enough to keep coming back. |
+| Drops then flattens above 0 | PMF signal. A core group finds ongoing value. |
+| Flattens higher with each newer cohort | PMF improving. You're learning. |
+
+**Benchmarks:**
+
+| Segment | D30 Retention (PMF threshold) | D90 Retention (strong PMF) |
+|---------|-------------------------------|---------------------------|
+| Consumer | > 20% | > 10% |
+| SMB SaaS | > 40% | > 25% |
+| Enterprise SaaS | > 60% | > 45% |
+| Marketplace (buyers) | > 30% | > 20% |
+| PLG (free-to-paid) | > 25% free D30, > 50% paid D30 | > 15% free D90 |
+
+**If retention is below threshold:**
+- Don't run more acquisition. You'll just churn faster.
+- Find the users who ARE retained. Understand why. Build for them.
+
+---
+
+### Signal 2: Sean Ellis Test
+
+Survey users with one question: "How would you feel if you could no longer use [Product]?"
+
+**Answers:**
+- Very disappointed
+- Somewhat disappointed
+- Not disappointed (it really isn't that useful)
+- N/A — I no longer use [Product]
+
+**Scoring:**
+- Count only "very disappointed" responses
+- Divide by total non-churned respondents
+- PMF threshold: **> 40% "very disappointed"**
+
+**Sample size requirement:** Minimum 40 responses. Under 40, the signal is noisy.
+
+**When to run it:**
+- When you have 100-500 active users
+- Quarterly for ongoing tracking
+- After major product changes
+
+**What to do with "somewhat disappointed":**
+Don't lump them with "very disappointed." The delta between "somewhat" and "very" is where your retention problem lives. Interview people in the "somewhat" group. What's missing? Why only somewhat?
+
+**When score is 20-35%:** You have a segment with PMF. Find them. Ask what they love. Run a separate survey for just that segment.
+
+**When score is < 20%:** Your core value proposition isn't working. This is not a retention tactics problem. Revisit the fundamental problem you're solving.
+
+---
+
+### Signal 3: Organic Growth and Referral
+
+**Metric:** % of new signups that came from existing user referral, word of mouth, or organic search — without a paid incentive.
+
+**Threshold:** > 20% of new users are coming organically without incentive programs.
+
+**How to measure:**
+1. Tag signup source: paid, organic search, referral (with referral code), direct/dark social
+2. Track monthly. Is the organic % trending up or stable?
+3. Interview organic signups: "How did you hear about us?" (don't trust the dropdown)
+
+**Why this matters:** Paid growth can mask the absence of PMF. You can buy users who churn. You can't buy users who tell their friends.
+
+---
+
+## Step 3: Run PMF Experiments (Pre-PMF)
+
+If you're below thresholds, don't optimize — experiment. The goal is to find the version of the product where at least a small segment has PMF.
+
+### The PMF Experiment Loop
+
+```
+1. Pick one customer segment + one hypothesis about their job to be done
+2. Remove everything from the product that doesn't serve that job
+3. Run a 4-week cohort with only that segment
+4. Measure retention + Sean Ellis for that cohort
+5. If PMF signal: this is your beachhead. Double down.
+ If no signal: new hypothesis. Repeat.
+```
+
+**Time box:** Each experiment 4-8 weeks. If you're running experiments for 18+ months with no signal, revisit the problem space, not just the solution.
+
+### What to Change
+
+| Lever | Change | Expected Impact |
+|-------|--------|-----------------|
+| Target segment | Narrow ICP from "all companies" to "Series A SaaS" | Faster learning, higher retention |
+| Core job | Reframe from feature-benefit to outcome-benefit | Better product decisions |
+| Onboarding | Remove steps to time-to-value | D1 retention up |
+| Pricing | Move from per-seat to per-outcome | Align incentives with value |
+| Channel | Switch from outbound to PLG | Different segment discovers product |
+
+---
+
+## Step 4: Validate PMF (Post-Signal, Pre-Scale)
+
+Congratulations, you have a retention curve that flattens. Before you scale:
+
+**Validate that it's real:**
+- Can you acquire more of the same customers? (Test CAC at 2x current volume)
+- Do the retained users expand? (Are they buying more seats, upgrading?)
+- Is the NPS from retained users > 40?
+- Are they forgiving of bugs and slowness? (Love, not tolerance)
+
+**Validate the unit economics:**
+- LTV / CAC > 3x (for SaaS)
+- Payback period < 18 months
+- Gross margin > 60% (SaaS), > 40% (marketplace)
+
+**The danger zone:** Convincing yourself you have PMF before economics are viable. High retention with terrible unit economics is not a business — it's a hobby that grows.
+
+---
+
+## PMF by Business Model
+
+### B2B SaaS
+
+**Primary signal:** D90 retention > 45% in target segment.
+
+**Secondary signals:**
+- NPS from retained users > 50
+- Expansion revenue from retained accounts (NRR > 110%)
+- Sales cycle shortening as word-of-mouth increases
+
+**PMF finding strategy:**
+- Start with one vertical, not the whole market
+- Get 3-5 reference customers who use it daily and refer others
+- Don't expand segment until you can replicate the reference case
+
+**Common false signals:**
+- Retained users who are locked in by contract, not value
+- Expansion revenue from upselling, not from organic growth
+- High satisfaction survey scores with flat usage data
+
+---
+
+### B2C / Consumer
+
+**Primary signal:** D30 retention > 20%, with a flat or rising tail at D90.
+
+**Secondary signals:**
+- DAU/MAU ratio > 20% (daily habit product: > 40%)
+- Session depth (users exploring multiple features, not one-and-done)
+- Organic referral rate > 20% of new installs
+
+**PMF finding strategy:**
+- Consumer PMF is about habit formation — which behavior do you own in a user's day?
+- Find the "aha moment" (the action that predicts retention). Build everything to get users there faster.
+- Segment ruthlessly — consumer PMF is often strong in one demographic, weak in others.
+
+**Common false signals:**
+- High D1 retention from email campaigns that re-engage dormant users
+- Good NPS from vocal users who are power users, not typical users
+- Media buzz driving installs from wrong audience
+
+---
+
+### Marketplace
+
+**Primary signal:** Successful transaction rate and repeat buyer rate.
+
+**Secondary signals:**
+- Supply-side retention (sellers/providers coming back)
+- Liquidity score: % of demand requests matched within acceptable time
+- Referral: both sides sending others
+
+**PMF challenge:** You have two customers (supply and demand). PMF can exist on one side and not the other.
+
+**PMF finding strategy:**
+- Start with constrained geography or category — don't try to be national before local works
+- Measure GMV per cohort, not just transaction count
+- Find the "magic moment" for both buyer and seller. Optimize for both.
+
+---
+
+### PLG (Product-Led Growth)
+
+**Primary signal:** Free-to-paid conversion rate + paid retention.
+
+**Secondary signals:**
+- Time to activation (reaching the "aha moment" in free tier)
+- PQL (product-qualified lead) conversion to paid
+- Team invites from individual users (virality coefficient)
+
+**PMF finding strategy:**
+- The free tier must have genuine value — not a crippled trial
+- Track activation milestone (the action that predicts conversion)
+- Optimize activation before conversion — conversion optimizations don't work if nobody activates
+
+---
+
+## After PMF: The Scaling Trap
+
+Most companies that fail after PMF weren't ready to scale. They scaled the wrong thing.
+
+### The Scaling Trap
+
+You have PMF with segment A. You hire sales and start selling to segment B. Segment B doesn't retain. NPS drops. Engineers chase segment B feature requests. Segment A users feel abandoned.
+
+**This is the most common way early-stage companies die after PMF.**
+
+### What to Do After PMF
+
+**First 90 days after confirming PMF:**
+1. Document your best customer profile in extreme detail
+2. Build the playbook to replicate the reference customer, not to expand the ICP
+3. Hire sales to replicate, not to expand
+4. Instrument everything — you need to know what's driving retention for every new cohort
+5. Don't launch new features. Remove friction from the path that's already working.
+
+**The expansion question:** Only expand ICP when:
+- You can replicate the reference customer at 3x volume with same retention
+- CAC is declining (word of mouth in the reference segment)
+- You've exhausted density in the reference segment
+
+**Don't expand ICP to save the business.** Expanding ICP when retention is declining is panic, not strategy.
+
+---
+
+## How to Know When PMF Is Slipping
+
+PMF is not a binary state. It can degrade. Watch for:
+
+| Signal | What's Happening | Response |
+|--------|-----------------|----------|
+| D30 retention declining across cohorts | Product changes or market change are eroding value | Run Sean Ellis test immediately. Interview churned users. |
+| Sean Ellis score dropping | Users less passionate about the product | Feature gap opening. Competitive pressure. |
+| NPS dropping for retained users | Power users seeing degraded experience | Product quality or performance issues. |
+| Organic referral rate declining | Satisfied users less enthusiastic | Product becoming commoditized. Moat eroding. |
+| Support tickets shifting from feature requests to bug reports | Technical debt catching up | Engineering quality investment needed. |
+| Sales cycles lengthening | ICP no longer self-evident. Positioning drift. | Re-run positioning exercise. Sharpen ICP. |
+
+**The PMF quarterly check:**
+Run Sean Ellis test every quarter. Track D30 retention by cohort every month. Put both on the CPO dashboard. These are your vital signs.
+
+---
+
+## Quick Reference
+
+| Test | Threshold | Frequency |
+|------|-----------|-----------|
+| Sean Ellis | > 40% very disappointed | Quarterly |
+| D30 retention (B2B SaaS) | > 40% | Monthly (by cohort) |
+| D30 retention (consumer) | > 20% | Monthly (by cohort) |
+| D90 retention (B2B SaaS) | > 45% | Monthly (by cohort) |
+| Organic signup % | > 20% | Monthly |
+| NPS (retained users) | > 40 | Quarterly |
+| DAU/MAU (if daily product) | > 20% | Weekly |
+
+Use `scripts/pmf_scorer.py` to run all dimensions together with weighted scoring.
diff --git a/skills/c-level-advisor/cpo-advisor/references/product_org_design.md b/skills/c-level-advisor/cpo-advisor/references/product_org_design.md
new file mode 100644
index 00000000..a1b810d6
--- /dev/null
+++ b/skills/c-level-advisor/cpo-advisor/references/product_org_design.md
@@ -0,0 +1,407 @@
+# Product Org Design Reference
+
+How to structure, hire, and run product organizations at different stages. No generic advice — stage-specific, role-specific, and honest about what breaks.
+
+---
+
+## 1. Team Topologies for Product Orgs
+
+Matthew Skelton and Manuel Pais defined four team types. Here's how they map to product organizations.
+
+### Four Team Types
+
+#### Stream-Aligned Teams
+Own a continuous flow of customer-facing work. They take problems all the way from discovery to delivery to measurement.
+
+**Product org equivalent:** Feature teams, growth teams, customer journey teams.
+
+**Characteristics:**
+- Long-lived (not project teams)
+- Full-stack: PM + Designer + 3-7 Engineers + QA
+- Can deploy independently without asking another team
+- Own their backlog, their metrics, their outcomes
+
+**Health signals:**
+- Ships without waiting on other teams more than 20% of the time
+- Can define their own north star and trace it to company metric
+- PMs spend > 50% of time in discovery, not coordination
+
+**Warning signs:**
+- Every sprint has "dependencies" blocking progress
+- Team has PMs but engineers don't know the customer problems
+- Roadmap is handed to them, not co-created
+
+#### Platform Teams
+Build and maintain shared capabilities so stream-aligned teams don't reinvent them.
+
+**Product org equivalent:** Platform product team, internal tools, shared infrastructure.
+
+**Characteristics:**
+- Serve internal customers (other teams), not end users directly
+- Measure success by stream-aligned team velocity, not feature count
+- Self-service is the goal — stream teams should be unblocked without filing tickets
+
+**Health signals:**
+- Stream-aligned teams can do 80% of their work without filing a ticket to platform
+- Platform has a public API and documentation, not just engineers who know how it works
+- Platform team metrics include "number of teams using X without assistance"
+
+**Warning signs:**
+- Platform team has a 6-week SLA for new features
+- Stream teams fork the platform to avoid waiting
+- Platform team's backlog is driven by platform's own ideas, not stream team pain
+
+**The platform product manager role:**
+Platform PMs are not feature PMs. They manage internal customers. Key skills:
+- Developer experience empathy (they're building for engineers)
+- API and infrastructure intuition (you can't PM what you don't understand)
+- Saying "no" gracefully when requests are misuses of the platform
+
+#### Enabling Teams
+Temporarily help other teams upskill in a domain. Not permanent.
+
+**Product org equivalent:** UX research team, data literacy evangelism, accessibility experts.
+
+**Duration:** Time-boxed. 3-6 months. Then they leave and the skill stays.
+
+**Failure mode:** Enabling teams that never leave become coordination bottlenecks.
+
+#### Complicated Subsystem Teams
+Deep expertise required. Minimal interaction.
+
+**Product org equivalent:** ML/AI product team, compliance product, payments, internationalization engine.
+
+**Characteristics:**
+- Specialists who can't be split across stream-aligned teams
+- Interact via well-defined interface, not collaboration
+- Have their own PM who understands the domain deeply
+
+---
+
+## 2. Org Models at Each Stage
+
+### Pre-Seed / Seed (1-20 engineers)
+
+**Structure:** Founder/CEO or founder/CTO is the PM. Maybe one hired PM at 15+ engineers.
+
+**Don't build:** Process, specialization, hierarchy.
+
+**Do build:** Direct customer access, fast iteration loops, written learning from every experiment.
+
+**PM role at this stage:**
+- Not shipping features. Talking to customers.
+- Not writing specs. Running experiments.
+- Not managing engineers. Being managed alongside them.
+
+**Hiring mistake:** Hiring a "process PM" who builds Jira templates before you have PMF.
+
+---
+
+### Series A (20-60 engineers)
+
+**Structure:** 2-4 PMs, organized by product area or customer journey.
+
+```
+CPO / Head of Product
+├── PM — Core Product (the thing customers pay for)
+├── PM — Growth / Acquisition (how more customers get there)
+└── PM — Platform (as soon as engineering says they need it)
+```
+
+**What you add:** One embedded designer. Analytics shared.
+
+**First PM hire criteria:**
+- Has shipped something users use, not just wrote a spec
+- Comfortable with ambiguity and no process
+- Will talk to customers without being asked
+- Understands the technical constraints intuitively
+
+**What breaks at Series A:**
+- Verbal communication stops working. First thing to document: the roadmap, the north star, who decided what.
+- Engineers start asking "why are we building this?" — good. Answer it.
+- Customer requests multiply faster than capacity. You need a prioritization framework.
+
+---
+
+### Series B (60-150 engineers)
+
+**Structure:** 4-8 PMs, head of product, first design hire, embedded or dedicated analytics.
+
+```
+CPO
+├── Head of Product
+│ ├── PM — [Team 1] (stream-aligned)
+│ ├── PM — [Team 2] (stream-aligned)
+│ ├── PM — [Team 3] (stream-aligned)
+│ └── PM — Platform (if engineering > 40)
+├── Head of Design (or Senior Designer × 2-3)
+└── Analytics (shared, or 1 embedded per team)
+```
+
+**What you add at Series B:**
+- Head of Product (frees CPO from backlog, runs PM team)
+- First Head of Design hire (if not already)
+- Dedicated growth team (PLG or acquisition)
+
+**What breaks at Series B:**
+- PMs start optimizing their own team's metrics instead of company metrics
+- Design and engineering don't talk until sprint planning
+- Data team is a ticket queue — PMs can't self-serve
+
+**Fix:** OKR alignment across teams. Design in discovery, not in handoff. Analytics tool self-serve access for every PM.
+
+---
+
+### Series C (150-400 engineers)
+
+**Structure:** 8-15 PMs, multiple PM leads / directors, specialized functions.
+
+```
+CPO
+├── VP / Director of Product
+│ ├── PM Lead — [Product Line 1]
+│ │ ├── PM
+│ │ └── PM
+│ ├── PM Lead — [Product Line 2]
+│ │ ├── PM
+│ │ └── PM
+│ └── PM Lead — Platform
+├── Head of Design
+│ ├── UX Design
+│ ├── Product Design
+│ └── UX Research
+├── Head of Data / Analytics
+│ ├── Product Analytics
+│ └── Data Science
+└── Head of Product Operations
+```
+
+**What you add at Series C:**
+- PM leads / directors (PMs managing PMs)
+- Dedicated UX research
+- Head of Product Operations (roadmap tooling, PM hiring, analytics standards, product community)
+- Possible Chief of Staff (Product)
+
+**What breaks at Series C:**
+- Coordination overhead becomes the primary job
+- PMs become project managers managing handoffs instead of product decisions
+- Consistency across teams: 5 different ways to write a spec, 5 different analytics setups
+- CPO loses touch with customers
+
+**Fix:** Product principles (written, opinionated, used in reviews). Embedded researchers. Regular CPO customer calls (monthly minimum). Product ops to solve consistency without bureaucracy.
+
+---
+
+## 3. PM:Engineer Ratios
+
+### By Stage
+
+| Stage | Engineers | PMs | Ratio | Notes |
+|-------|-----------|-----|-------|-------|
+| Seed | 5 | 0-1 | 1:5 | Founder PM common |
+| Series A | 20-40 | 2-4 | 1:8 | First real PMs |
+| Series B | 60-100 | 5-8 | 1:10 | Platform PM emerges |
+| Series C | 150-250 | 12-18 | 1:12 | PM leads required |
+| Growth | 300+ | 20+ | 1:12-15 | Specialization high |
+
+### By Team Type
+
+| Team Type | Ratio | Rationale |
+|-----------|-------|-----------|
+| Stream-aligned (feature) | 1:6-8 | High discovery work, many stakeholders |
+| Growth / PLG | 1:8-10 | High experimentation, more autonomy per engineer |
+| Platform | 1:10-15 | Lower ambiguity, more self-directed engineers |
+| Complicated subsystem (ML, payments) | 1:12-20 | Technical direction from engineers, PM is translator |
+
+**The ratio trap:** These are guidelines, not targets. A great PM in a bad org with 12 engineers accomplishes less than a great PM with 8 in a healthy org. Fix the org before optimizing the ratio.
+
+---
+
+## 4. When to Hire Key Roles
+
+### Head of Design
+
+**Not yet signal:**
+- Fewer than 2 full-time designers
+- Product is primarily technical (API-first, developer tool with no GUI)
+- Design is consistently described as "not a blocker"
+
+**Hire now signal:**
+- Design has become a coordination problem (who reviews what? which system? what's the standard?)
+- You have 3+ designers and they're inconsistent
+- CPO is spending significant time on design decisions
+- Customers cite UX as a blocker to adoption
+
+**What this person does:**
+- Builds and maintains the design system
+- Runs UX research as a function, not one-off projects
+- Hires and grows the design team
+- Keeps designers from becoming pixel-pushers and keeps them in discovery
+
+**Wrong hire:** A senior IC who can't build process and isn't excited about it.
+
+---
+
+### Head of Data / Analytics
+
+**Not yet signal:**
+- < 5 PMs, data team shared with engineering
+- You don't have product analytics instrumentation yet (worry about that first)
+- Product metrics are reviewed monthly and nobody acts on them
+
+**Hire now signal:**
+- PMs are filing tickets for basic metric questions (sign that data team is a bottleneck)
+- Multiple products with different tracking setups — no common definitions
+- You want to run experiments but don't have infrastructure
+- Leadership is making product decisions without data (not from choice — from access)
+
+**What this person does:**
+- Defines the event taxonomy and enforces it
+- Builds self-serve analytics capability for PMs
+- Runs A/B testing infrastructure
+- Partners with PMs on experiment design (before launch, not after)
+
+**Wrong hire:** A pure data scientist who can't build product analytics infrastructure and doesn't want to.
+
+---
+
+### Head of Product Operations
+
+**Hire when you have:**
+- 8+ PMs with inconsistent processes
+- CPO spending > 30% of time on internal coordination
+- No standard for roadmap tools, prioritization, or PM onboarding
+- Product team can't answer "what are all teams working on this quarter?" without a 2-hour meeting
+
+**What this person does:**
+- PM onboarding and development program
+- Roadmap and tooling standards (Jira, Linear, Notion — pick one and enforce it)
+- Data pipelines from product to leadership (weekly metrics, OKR tracking)
+- PM hiring and interview process
+- Voice of product org in cross-functional coordination
+
+**What this person does NOT do:**
+- Drive product strategy (that's the CPO)
+- Manage PMs (that's the Head of Product or PM leads)
+- Own analytics (that's Head of Data)
+
+---
+
+## 5. The Product Trio
+
+Every product team should have three roles working together from day one of discovery:
+
+```
+Product Manager → What to build and why
+Product Designer → How users experience it
+Tech Lead / Engineer → How to build it sustainably
+```
+
+### How the Trio Actually Works
+
+**Discovery (weeks 1-2 of any new initiative):**
+- All three in user interviews together
+- All three reviewing competitive products
+- All three in problem framing sessions
+- Output: Opportunity, not solution
+
+**Ideation (days):**
+- All three generating solutions
+- Designer prototypes 2-3 options
+- Engineer provides feasibility gut check on each
+- PM synthesizes against strategy
+- Output: Prototype for testing
+
+**Testing (days):**
+- Designer and PM run tests (engineer optional but encouraged)
+- Tests with 5-8 real customers
+- All three review findings together
+- Output: Decision: build, iterate, or kill
+
+**Delivery (sprints):**
+- PM writes acceptance criteria (what done looks like from user perspective)
+- Engineer owns implementation
+- Designer owns QA for experience quality
+- All three do final review before release
+
+### Trio Anti-Patterns
+
+| Anti-Pattern | What It Looks Like | Why It Fails |
+|-------------|-------------------|--------------|
+| **PM → Designer → Engineer** | Waterfall disguised as agile | Late discovery of infeasibility and poor UX |
+| **Engineer-led** | Engineers propose solutions, PM and designer polish | Builds technically correct thing nobody wants |
+| **PM-led dictation** | PM writes detailed spec, team executes | Team has no context, can't make good trade-offs |
+| **Designer detached** | Designers design in isolation, present to engineers | Beautiful mockup that's 8x harder to build than alternative |
+| **No research** | Trio invents problems and solutions in a conference room | Building for themselves |
+
+---
+
+## 6. Remote vs. Co-located Product Teams
+
+The debate is mostly settled. Here's what actually matters:
+
+### What Changes with Remote
+
+| Activity | Co-located | Remote | Fix |
+|----------|-----------|--------|-----|
+| Discovery sync | Organic, hallway | Requires scheduling | Daily async standups + weekly sync |
+| Whiteboarding | Easy | Friction | Figma, Miro — async-first artifacts |
+| Design review | Walk over | Calendar invite | Record reviews; written decisions |
+| Relationship building | Osmotic | Deliberate | Regular 1:1s, team rituals, offsites |
+| Onboarding | Shadow in person | Document-heavy | Written playbooks + buddy system |
+| Difficult conversations | Easier in person | Harder | Default to video, not Slack |
+
+### The Async-First Product Team
+
+Works well remote IF:
+- Decisions are written (Notion, Confluence, not Slack threads)
+- Roadmaps are accessible to everyone without a meeting
+- Product reviews are recorded and linked
+- Discovery artifacts are shared before the meeting, discussed in the meeting
+- 1:1s are weekly and actual (not "let's skip this week")
+
+**What doesn't survive async:**
+- Ambiguous ownership
+- Verbal agreements (write it down or it didn't happen)
+- Teams where "PM wrote the spec" is the only documentation
+
+### Remote Product Org Practices
+
+**Weekly Cadence:**
+```
+Monday: Async kickoff — each team posts week's focus + blockers
+Tuesday: Product trio sync (30 min, per team)
+Wednesday: CPO / Head of Product 1:1s
+Thursday: Cross-team PM sync (30 min, rotating topics)
+Friday: Async retrospective notes + week summary
+```
+
+**Monthly:**
+- Full product org sync (all PMs, designers, heads)
+- CPO product review (each team presents one initiative)
+- Metrics review (company + team level)
+
+**Quarterly:**
+- In-person or virtual offsite
+- Strategy and OKR setting
+- Individual growth conversations
+
+---
+
+## Quick Reference
+
+| Stage | Structure | First Hire Priority |
+|-------|-----------|-------------------|
+| Seed | Founder PM | Generalist PM with customer instincts |
+| Series A | 2-3 PMs, flat | First real PM, owns a product area |
+| Series B | Head of Product, 4-8 PMs | Head of Design |
+| Series C | Org layers, PM leads | Head of Data + Product Ops |
+| Growth | Full specialization | Chief of Staff (Product) |
+
+**PM:Engineer ratio target by stage:**
+Seed 1:5 → Series A 1:8 → Series B 1:10 → Series C 1:12 → Growth 1:15
+
+**Three things that fix most product org problems:**
+1. Stream-aligned teams with full-stack ownership (PM + Design + Eng)
+2. OKRs that cascade from company to team to individual
+3. Product trio in discovery, not just delivery
diff --git a/skills/c-level-advisor/cpo-advisor/references/product_strategy.md b/skills/c-level-advisor/cpo-advisor/references/product_strategy.md
new file mode 100644
index 00000000..014b8e5d
--- /dev/null
+++ b/skills/c-level-advisor/cpo-advisor/references/product_strategy.md
@@ -0,0 +1,454 @@
+# Product Strategy Reference
+
+Frameworks for product vision, competitive positioning, portfolio management, and board reporting. No theory — only what CPOs actually use.
+
+---
+
+## 1. Vision Frameworks
+
+### Jobs to Be Done (JTBD)
+
+JTBD is not a feature framework. It's a way to understand *why* customers hire your product and under what circumstances.
+
+**The core insight:** People don't want your product. They want to make progress in their lives, and they hire your product to help. When you understand the job, you understand competition differently.
+
+#### Conducting JTBD Interviews
+
+**Who to interview:** Recent buyers and recent churners. Not power users — they're already converted.
+
+**The interview script (condensed):**
+```
+1. "Walk me through the last time you [started using / stopped using] this product."
+2. "What were you doing the day before you decided?"
+3. "What else did you consider?"
+4. "What almost stopped you from doing it?"
+5. "Now that you're using it, what does your day look like differently?"
+```
+
+**What you're extracting:**
+- **Functional job:** What task are they accomplishing?
+- **Emotional job:** How do they feel during and after?
+- **Social job:** How are they perceived?
+- **Timeline:** What triggered the switch? (the "push" from old solution + "pull" toward new one)
+- **Anxieties:** What almost prevented adoption?
+- **Competing solutions:** What are they comparing you to, including "do nothing"?
+
+#### JTBD Output: The Job Story
+
+Format better than "user story" for strategic decisions:
+
+```
+When [situation],
+I want to [motivation/job],
+So I can [expected outcome].
+```
+
+**Example (healthcare scheduling):**
+```
+When I'm trying to coordinate my parent's care from another city,
+I want to see their upcoming appointments and have someone confirm changes,
+So I can feel confident they won't miss critical treatments.
+```
+
+This is a different product than "schedule management software." The strategic implications — care coordination, family access, confirmation workflows — flow from the job.
+
+#### JTBD → Product Strategy
+
+| Job Insight | Strategic Implication |
+|-------------|----------------------|
+| Job is episodic (quarterly) | Engagement model must reach them before they need it |
+| Job is habitual (daily) | DAU/MAU matters; build for habit formation |
+| Job has high stakes | Trust and reliability > features; invest in onboarding + support |
+| Job is social | Network effects possible; virality is structural, not a campaign |
+| Job is delegated (done for someone else) | Two users: the buyer and the beneficiary. Design for both. |
+
+---
+
+### Category Design
+
+If you're fighting for share in an existing category, you're playing defense on someone else's field.
+
+**Category design premise:** Companies that define the category typically capture 76% of the market cap of that category. Name the category, own it.
+
+#### The Category Design Process
+
+**Step 1: Name the problem, not the solution.**
+```
+Wrong: "We make AI-powered customer support software."
+Right: "The support team doesn't need more tickets. They need fewer problems."
+```
+
+**Step 2: Define the enemy.**
+The enemy is the *old way* of solving the problem, not a competitor.
+- Salesforce's enemy: spreadsheets and disconnected tools (not Siebel)
+- Slack's enemy: email overload (not HipChat)
+- Your enemy: ___________
+
+**Step 3: Create the category name.**
+It should be obvious in hindsight, not predictable in advance. Test it:
+- Does it describe the problem, not the solution?
+- Is it 2-3 words?
+- Could a journalist use it without quoting you?
+
+**Step 4: Missionary selling, not mercenary selling.**
+Category kings educate the market before they sell to it. Content, thought leadership, community, and free tools all matter here — not as marketing tactics but as category creation.
+
+**Step 5: Be the reference customer.**
+Get the logos that define the category. The companies others look to. When others adopt, they don't want "a tool" — they want "what [Reference Customer] uses."
+
+---
+
+## 2. Competitive Moats
+
+A moat is a structural advantage that compounds over time. Features are not moats. Pricing is not a moat. A moat is why, even if a competitor perfectly copies your product today, you still win.
+
+### Moat Type 1: Network Effects
+
+The product becomes more valuable as more users join. Two subtypes:
+
+**Direct network effects:** Each user makes the product better for all other users (WhatsApp, Slack).
+
+**Indirect network effects:** Each user on one side makes the product better for the other side (Uber drivers + riders, App Store developers + users).
+
+**Data network effects:** More users → more data → better product → more users.
+
+#### Network Effect Diagnostic
+```
+Question 1: Does adding user N make the product better for user N-1?
+ No → You don't have direct network effects
+ Yes → Map exactly how and how much
+
+Question 2: Does adding user N make the product better for users on the OTHER side?
+ No → You don't have indirect network effects
+ Yes → Identify which side is the constraint (supply or demand)
+
+Question 3: Does using the product generate data that improves the product?
+ No → You don't have data network effects
+ Yes → What is the data flywheel? Where does it compound?
+```
+
+**Building network effects intentionally:**
+- Most products accidentally have weak network effects
+- Design for network effects from Day 1: sharing, notifications, collaboration, integrations
+- Measure network effect strength: "What % of new users were referred by existing users?"
+
+### Moat Type 2: Switching Costs
+
+The cost — time, money, risk — of leaving your product. The highest switching costs are:
+
+| Switching Cost Type | Example | CPO Action |
+|--------------------|---------|-----------|
+| **Data lock-in** | Years of history, reports, trained models | Make data the experience, not just the storage |
+| **Workflow integration** | 23 integrations, custom automations | Every integration is a switching cost. Build them. |
+| **Team adoption** | Entire team trained on your tool | Multi-seat training investments pay switching cost dividends |
+| **Contractual** | Annual contracts, SLAs | Long contracts are not a moat — customers resent them |
+| **Process embedding** | Your product IS their process | Aim here. This is the deepest moat. |
+
+**Warning:** Switching costs from data lock-in without value lock-in breed resentment, not loyalty. Customers who stay because they're trapped will leave the moment a migration tool appears.
+
+### Moat Type 3: Data Advantages
+
+Having data others can't easily get. Three subtypes:
+
+**Proprietary data:** Data only you have access to (exclusive partnerships, sensor networks, unique user behavior at scale).
+
+**Data scale:** Same type of data but at 10x the volume of competitors. Scale compounds model accuracy.
+
+**Data variety:** Unique combination of data types. Not just usage data — usage + outcome data + external context.
+
+**Testing your data moat:**
+```
+1. What data do we have that competitors don't?
+2. At what volume does our data create a meaningfully better product?
+3. Are we at that volume? If not, when?
+4. Could a competitor buy or partner their way to equivalent data?
+5. Is our data improving the product automatically, or only when we analyze it manually?
+```
+
+### Moat Type 4: Economies of Scale
+
+Unit economics improve as you scale. Infrastructure costs drop per unit. Brand recognition lowers CAC. Negotiating power increases.
+
+This is a real moat but the weakest one for product strategy — it doesn't keep faster-moving competitors from attacking while you're small.
+
+### Moat Scorecard
+
+Score each moat type 0-3 for your current product:
+
+```
+0 = Not present
+1 = Weak / easily replicated
+2 = Meaningful / takes 12-18 months to replicate
+3 = Strong / structural advantage
+
+Network effects (direct): __/3
+Network effects (indirect): __/3
+Network effects (data): __/3
+Switching costs (data): __/3
+Switching costs (workflow): __/3
+Switching costs (team): __/3
+Data advantages (exclusive): __/3
+Data advantages (scale): __/3
+Economies of scale: __/3
+
+Total: __/27
+
+< 9: No meaningful moat. Compete on execution speed.
+9-15: Early moat. Identify and reinforce 1-2 strongest types.
+16-21: Real moat. Invest to compound it.
+> 21: Strong moat. Defend and expand.
+```
+
+---
+
+## 3. Product Positioning
+
+Positioning is not messaging. Positioning is the choice of: *Who is this for, what does it replace, and on what dimension do we win?*
+
+### The Positioning Canvas (after April Dunford)
+
+```
+1. Competitive Alternatives
+ What would customers do if your product didn't exist?
+ (This is your real competition, not just your vendor category)
+
+2. Unique Attributes
+ What capabilities do you have that alternatives lack?
+ (Features, but described neutrally, not as marketing)
+
+3. Value (Outcomes)
+ What does each unique attribute enable for customers?
+ (Bridge from feature → outcome, not feature → feature)
+
+4. Customer Who Cares
+ Who values those outcomes enough to pay for them?
+ (The customer segment for whom this value is highest)
+
+5. Market Category
+ Where does the customer put you when comparing options?
+ (Frame the category to win, not to be fair)
+
+6. Relevant Trends
+ What's changing in the world that makes this more valuable now?
+ (Why this moment? Urgency enabler.)
+```
+
+### Positioning Against Three Competitors
+
+**Positioning vs. direct competitor:**
+Identify one dimension where you structurally win. "Better" is not a position.
+- Win on depth: more powerful in one scenario
+- Win on simplicity: fewer decisions, fewer steps
+- Win on integration: works with what they already use
+- Win on price/value: same outcome, lower cost or risk
+
+**Positioning vs. indirect alternative:**
+The customer's current solution (spreadsheet, manual process, point solution).
+- Make switching cost obvious (what are they giving up per week?)
+- Make the switch simple (migration, onboarding, no data loss)
+- Find the "aha moment" fast (value before they revert)
+
+**Positioning vs. doing nothing:**
+The hardest competitor. Status quo has zero switching cost.
+- Quantify the cost of inaction (time, risk, revenue, competitive risk)
+- Find the trigger event that makes inaction intolerable
+- Show the risk is higher than the switch cost
+
+### Positioning Failure Modes
+
+| Failure | Description | Fix |
+|---------|-------------|-----|
+| **For everyone** | No segment. "Any company that needs X." | Name the best-fit customer. |
+| **Feature positioning** | "The only tool with [feature X]" | Features are table stakes. Lead with outcome. |
+| **Vague differentiation** | "Easier, faster, better" | Measurable, specific, or don't say it. |
+| **Category misfit** | In a category where you can't win | Either own the category or name a new one |
+| **Lagging positioning** | Positioned for who you were, not who you are | Reposition every 18-24 months or after major product change |
+
+---
+
+## 4. Portfolio Management
+
+### Applying BCG Matrix to Product Lines
+
+BCG matrix was designed for business units. Applied to product lines:
+
+**Inputs:**
+- Market growth rate (industry growth, not your growth)
+- Relative market share (your share vs. largest competitor)
+- Revenue contribution (absolute)
+- Investment level (engineering + sales + marketing per product)
+
+**Calculation:**
+```
+Market share ratio = Your market share / Largest competitor's market share
+Growth rate = Market CAGR (next 3 years estimate)
+
+Stars: share ratio > 1.0, growth > 10%
+Cash Cows: share ratio > 1.0, growth < 10%
+Question Marks: share ratio < 1.0, growth > 10%
+Dogs: share ratio < 1.0, growth < 10%
+```
+
+### Portfolio Allocation Rules
+
+**Star products:**
+- Invest at or above market growth rate
+- Goal: maintain share leadership as market grows
+- Don't extract cash — reinvest
+- Metrics: market share trend, NPS, retention, feature velocity
+
+**Cash Cow products:**
+- Minimum investment to maintain market position
+- Goal: maximize free cash flow
+- Resist the urge to innovate — incremental improvements only
+- Metrics: gross margin, churn rate, support cost per customer
+
+**Question Mark products:**
+- Binary decision: invest to win or exit
+- "Maintain" is not a strategy for question marks — you lose share every quarter you're neutral
+- Set a deadline (2 quarters) and a threshold for investment decision
+- Metrics: share gain rate, customer acquisition efficiency
+
+**Dog products:**
+- Decision: sell, sunset, or bundle
+- Never "fix" a dog with more investment
+- Timeline to sunset: 6-12 months, migration plan for existing customers
+- Metrics: customer migration rate, revenue retained
+
+### Portfolio Review Template
+
+Run quarterly. One slide per product.
+
+```
+Product: [Name]
+Current Quadrant: [Star/Cash Cow/Question Mark/Dog]
+Revenue this quarter: $___
+Revenue growth QoQ: ___%
+Market share estimate: ___%
+Investment level (% of eng capacity): ___%
+Investment posture: [Invest / Maintain / Kill]
+
+Key metric: [Name] → [Current value] → [QoQ trend]
+Top risk: [One thing that could change this assessment]
+Decision required: [Yes/No] | [What decision?]
+```
+
+### The Honest Portfolio Conversation
+
+Questions CPOs avoid but boards ask:
+- "Which product would we kill if we had to? What's stopping us?"
+- "Are we funding dogs because the team is attached or because there's a real plan?"
+- "What would our margins look like if we stopped investing in the bottom 2 products?"
+- "What's the dependency between our products? Are we a platform or a bundle of unrelated tools?"
+
+---
+
+## 5. Board-Level Product Reporting
+
+### What Good Looks Like
+
+Board product updates fail in three ways:
+1. Too much roadmap detail (feature list masquerading as strategy)
+2. No trend context (showing a number without showing if it's getting better or worse)
+3. No risks (all good news = no credibility)
+
+### The 5-Slide Board Product Update
+
+**Slide 1: North Star Metric**
+```
+Title: Product Health — [Quarter]
+
+[Chart: North star metric over last 12 months, quarterly cohorts]
+
+This quarter: [Value] | Prior quarter: [Value] | YoY: [Value]
+Target: [Value] | Status: On track / At risk / Behind
+
+Drivers (2-3 bullets):
+• What's driving improvement: ___
+• What's dragging: ___
+• What we're doing about the drag: ___
+```
+
+**Slide 2: Retention and PMF**
+```
+Title: Product-Market Fit Evidence
+
+[Chart: D30 retention by cohort, last 6 cohorts]
+[Callout: Sean Ellis score = XX% (target: > 40%)]
+
+PMF status: Achieved / Approaching / Not yet
+Best segment: [Describe — where retention is strongest]
+Weakest segment: [Describe — and what we're doing about it]
+```
+
+**Slide 3: Portfolio Status**
+```
+Title: Portfolio — Invest / Maintain / Kill
+
+| Product | Quadrant | Revenue | Growth | Posture | Risk |
+|---------|---------|---------|--------|---------|------|
+| [A] | Star | $___ | +XX% | Invest | ___ |
+| [B] | Cash Cow| $___ | +X% | Maintain| ___ |
+| [C] | Dog | $___ | -X% | Kill Q3 | ___ |
+
+Changes since last quarter: ___
+Decisions needed from board: ___
+```
+
+**Slide 4: Strategic Bets**
+```
+Title: Bets This Half — [H1/H2]
+
+Bet 1: [Name]
+ Hypothesis: If we [do X], [segment Y] will [do Z]
+ Evidence so far: [Data]
+ Confidence: [Low / Medium / High]
+ Decision point: [When do we know?] [What will we measure?]
+
+Bet 2: [Name]
+ [Same structure]
+```
+
+**Slide 5: Top Risks**
+```
+Title: Product Risks — [Quarter]
+
+Risk 1: [Name]
+ What it is: ___
+ Probability: [Low/Med/High]
+ Impact if realized: ___
+ Mitigation: ___
+
+Risk 2: [Name]
+ [Same structure]
+
+Risk 3: [Name]
+ [Same structure]
+```
+
+### Delivering in the Board Meeting
+
+- Never read the slide
+- Lead with the conclusion, not the data
+- Prepare for "what if that assumption is wrong?" for every bet
+- When something underperformed: say it, own it, explain what changed
+- Never present a number you can't explain 3 levels deep
+
+**Example of bad delivery:**
+"Our north star is up 15% QoQ, which is great. We're tracking well."
+
+**Example of good delivery:**
+"North star is up 15% — ahead of plan. The majority of that is from the enterprise cohort activated in October, driven by the workflow automation feature we shipped in September. The consumer segment is flat, which is a concern. We're running three experiments this quarter to diagnose whether that's an acquisition problem or an activation problem — I'll have an answer for next quarter."
+
+---
+
+## Quick Reference: Framework Summary
+
+| Need | Framework |
+|------|----------|
+| Why do customers use us? | Jobs to Be Done |
+| How do we define our market? | Category Design |
+| What's our structural advantage? | Moat Scorecard |
+| How do we position? | April Dunford Positioning Canvas |
+| Which products to fund? | BCG Matrix + Invest/Maintain/Kill |
+| How to report to the board? | 5-Slide Board Update |
diff --git a/skills/c-level-advisor/cpo-advisor/scripts/pmf_scorer.py b/skills/c-level-advisor/cpo-advisor/scripts/pmf_scorer.py
new file mode 100644
index 00000000..5fd1a4f0
--- /dev/null
+++ b/skills/c-level-advisor/cpo-advisor/scripts/pmf_scorer.py
@@ -0,0 +1,600 @@
+#!/usr/bin/env python3
+"""
+PMF Scorer — Multi-dimensional Product-Market Fit analysis.
+
+Scores PMF across four dimensions:
+ - Retention (40%): D30 and D90 cohort retention
+ - Engagement (25%): DAU/MAU, session depth, key action rate
+ - Satisfaction(20%): Sean Ellis score, NPS
+ - Growth (15%): Organic signup rate, referral rate
+
+Usage:
+ python pmf_scorer.py # Run with built-in sample data
+ python pmf_scorer.py --input data.json # Run with your data
+
+JSON input format: see sample_data() function below.
+"""
+
+import json
+import sys
+import argparse
+import math
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+def sample_data() -> dict:
+ """
+ Sample input data. Replace with your own values.
+
+ All fields are optional — missing fields score 0 for that sub-metric
+ and a note is added to recommendations.
+ """
+ return {
+ "product_name": "Acme SaaS",
+ "business_model": "b2b_saas", # b2b_saas | consumer | marketplace | plg
+
+ # Retention: D30 and D90 as decimals (e.g. 0.42 = 42%)
+ # Provide multiple cohorts if available. Most recent first.
+ "retention": {
+ "d30_cohorts": [0.38, 0.41, 0.44, 0.43], # newest → oldest
+ "d90_cohorts": [0.28, 0.30, 0.31],
+ "curve_flattening": True, # Does the curve flatten (vs. continuing to drop)?
+ },
+
+ # Engagement
+ "engagement": {
+ "dau_mau_ratio": 0.24, # Daily active / Monthly active (decimal)
+ "avg_sessions_per_week": 3.2, # Per active user
+ "key_action_rate": 0.55, # % of users who performed core value action in last 30d
+ "session_depth_score": 0.6, # 0-1: 0 = one page, 1 = full feature exploration
+ },
+
+ # Satisfaction
+ "satisfaction": {
+ "sean_ellis_very_disappointed": 0.38, # Fraction (e.g. 0.38 = 38%)
+ "sean_ellis_sample_size": 87, # Raw response count
+ "nps_score": 34, # -100 to 100
+ "nps_sample_size": 210,
+ },
+
+ # Growth
+ "growth": {
+ "organic_signup_pct": 0.27, # % of new signups from organic/referral/WOM
+ "referral_rate": 0.18, # % of active users who referred someone last 90d
+ "mom_growth_rate": 0.08, # Month-over-month new user growth (decimal)
+ },
+ }
+
+
+# ---------------------------------------------------------------------------
+# Thresholds by business model
+# ---------------------------------------------------------------------------
+
+THRESHOLDS = {
+ "b2b_saas": {
+ "d30_pmf": 0.40, "d30_strong": 0.60,
+ "d90_pmf": 0.25, "d90_strong": 0.45,
+ "dau_mau_pmf": 0.15, "dau_mau_strong": 0.35,
+ "sean_ellis_pmf": 0.40, "sean_ellis_strong": 0.55,
+ "nps_pmf": 30, "nps_strong": 50,
+ },
+ "consumer": {
+ "d30_pmf": 0.20, "d30_strong": 0.35,
+ "d90_pmf": 0.10, "d90_strong": 0.20,
+ "dau_mau_pmf": 0.20, "dau_mau_strong": 0.40,
+ "sean_ellis_pmf": 0.40, "sean_ellis_strong": 0.55,
+ "nps_pmf": 20, "nps_strong": 45,
+ },
+ "marketplace": {
+ "d30_pmf": 0.30, "d30_strong": 0.50,
+ "d90_pmf": 0.20, "d90_strong": 0.35,
+ "dau_mau_pmf": 0.15, "dau_mau_strong": 0.30,
+ "sean_ellis_pmf": 0.40, "sean_ellis_strong": 0.55,
+ "nps_pmf": 25, "nps_strong": 45,
+ },
+ "plg": {
+ "d30_pmf": 0.25, "d30_strong": 0.45,
+ "d90_pmf": 0.15, "d90_strong": 0.30,
+ "dau_mau_pmf": 0.20, "dau_mau_strong": 0.40,
+ "sean_ellis_pmf": 0.40, "sean_ellis_strong": 0.55,
+ "nps_pmf": 30, "nps_strong": 50,
+ },
+}
+
+# Weights for the four dimensions (must sum to 1.0)
+DIMENSION_WEIGHTS = {
+ "retention": 0.40,
+ "engagement": 0.25,
+ "satisfaction": 0.20,
+ "growth": 0.15,
+}
+
+
+# ---------------------------------------------------------------------------
+# Scoring helpers
+# ---------------------------------------------------------------------------
+
+def clamp(value: float, lo: float = 0.0, hi: float = 1.0) -> float:
+ return max(lo, min(hi, value))
+
+
+def score_between(value: Optional[float], lo: float, hi: float) -> float:
+ """Linear interpolation: lo → 0.0, hi → 1.0, beyond hi → 1.0."""
+ if value is None:
+ return 0.0
+ if value <= lo:
+ return 0.0
+ if value >= hi:
+ return 1.0
+ return (value - lo) / (hi - lo)
+
+
+def cohort_trend(cohorts: list) -> float:
+ """
+ Given cohorts newest-first, return a trend score -1 to +1.
+ Positive = improving. Negative = degrading.
+ """
+ if len(cohorts) < 2:
+ return 0.0
+ # Simple: compare most recent half average vs. older half average
+ mid = len(cohorts) // 2
+ recent_avg = sum(cohorts[:mid]) / mid if mid else cohorts[0]
+ older_avg = sum(cohorts[mid:]) / (len(cohorts) - mid)
+ if older_avg == 0:
+ return 0.0
+ delta = (recent_avg - older_avg) / older_avg
+ return clamp(delta * 5, -1.0, 1.0) # scale: 20% improvement = score of 1.0
+
+
+# ---------------------------------------------------------------------------
+# Dimension scorers
+# ---------------------------------------------------------------------------
+
+def score_retention(data: dict, thresholds: dict) -> tuple[float, list]:
+ """Returns (score 0-1, list of findings)."""
+ r = data.get("retention", {})
+ findings = []
+ scores = []
+
+ d30 = r.get("d30_cohorts", [])
+ d90 = r.get("d90_cohorts", [])
+
+ if not d30:
+ findings.append("⚠ No D30 retention data — this is the most important PMF signal. Instrument it immediately.")
+ return 0.0, findings
+
+ latest_d30 = d30[0]
+ d30_score = score_between(latest_d30, 0, thresholds["d30_strong"])
+ scores.append(d30_score)
+
+ if latest_d30 >= thresholds["d30_strong"]:
+ findings.append(f"✓ D30 retention {latest_d30:.0%} — strong PMF signal")
+ elif latest_d30 >= thresholds["d30_pmf"]:
+ findings.append(f"◑ D30 retention {latest_d30:.0%} — approaching PMF threshold ({thresholds['d30_pmf']:.0%})")
+ else:
+ findings.append(f"✗ D30 retention {latest_d30:.0%} — below PMF threshold ({thresholds['d30_pmf']:.0%}). Focus here before anything else.")
+
+ # Trend bonus
+ if len(d30) >= 2:
+ trend = cohort_trend(d30)
+ trend_score = (trend + 1) / 2 # normalize to 0-1
+ scores.append(trend_score * 0.5) # trend is bonus, not primary
+ if trend > 0.1:
+ findings.append(f"✓ D30 retention improving across cohorts — strong learning signal")
+ elif trend < -0.1:
+ findings.append(f"✗ D30 retention declining across cohorts — product changes may be hurting core users")
+
+ if d90:
+ latest_d90 = d90[0]
+ d90_score = score_between(latest_d90, 0, thresholds["d90_strong"])
+ scores.append(d90_score)
+ if latest_d90 >= thresholds["d90_strong"]:
+ findings.append(f"✓ D90 retention {latest_d90:.0%} — excellent long-term retention")
+ elif latest_d90 >= thresholds["d90_pmf"]:
+ findings.append(f"◑ D90 retention {latest_d90:.0%} — some long-term value demonstrated")
+ else:
+ findings.append(f"✗ D90 retention {latest_d90:.0%} — users not finding long-term value")
+ else:
+ findings.append("⚠ No D90 data. Add 90-day cohort tracking.")
+
+ flattening = r.get("curve_flattening", False)
+ if flattening:
+ scores.append(0.8)
+ findings.append("✓ Retention curve flattening — core retained segment exists")
+ else:
+ scores.append(0.2)
+ findings.append("✗ Retention curve not flattening — no stable retained segment yet")
+
+ return clamp(sum(scores) / len(scores)), findings
+
+
+def score_engagement(data: dict, thresholds: dict) -> tuple[float, list]:
+ e = data.get("engagement", {})
+ findings = []
+ scores = []
+
+ dau_mau = e.get("dau_mau_ratio")
+ if dau_mau is not None:
+ s = score_between(dau_mau, 0, thresholds["dau_mau_strong"])
+ scores.append(s)
+ if dau_mau >= thresholds["dau_mau_strong"]:
+ findings.append(f"✓ DAU/MAU {dau_mau:.0%} — strong daily habit")
+ elif dau_mau >= thresholds["dau_mau_pmf"]:
+ findings.append(f"◑ DAU/MAU {dau_mau:.0%} — moderate engagement")
+ else:
+ findings.append(f"✗ DAU/MAU {dau_mau:.0%} — users not building a habit. Find the daily job or accept weekly use pattern.")
+ else:
+ findings.append("⚠ No DAU/MAU data.")
+
+ sessions = e.get("avg_sessions_per_week")
+ if sessions is not None:
+ # 5+ sessions/week = strong, 2 = threshold
+ s = score_between(sessions, 1, 5)
+ scores.append(s)
+ if sessions >= 5:
+ findings.append(f"✓ {sessions:.1f} sessions/week — high engagement")
+ elif sessions >= 2:
+ findings.append(f"◑ {sessions:.1f} sessions/week — moderate")
+ else:
+ findings.append(f"✗ {sessions:.1f} sessions/week — very low. Users not returning within week.")
+ else:
+ findings.append("⚠ No session frequency data.")
+
+ kar = e.get("key_action_rate")
+ if kar is not None:
+ s = score_between(kar, 0.10, 0.70)
+ scores.append(s)
+ if kar >= 0.60:
+ findings.append(f"✓ Key action rate {kar:.0%} — core value well-adopted")
+ elif kar >= 0.30:
+ findings.append(f"◑ Key action rate {kar:.0%} — improve onboarding to drive this up")
+ else:
+ findings.append(f"✗ Key action rate {kar:.0%} — most users not reaching core value. This is an activation problem.")
+ else:
+ findings.append("⚠ No key action rate. Define your 'aha moment' action and track it.")
+
+ depth = e.get("session_depth_score")
+ if depth is not None:
+ scores.append(depth)
+ if depth >= 0.6:
+ findings.append(f"✓ Session depth {depth:.1f} — users exploring the product")
+ else:
+ findings.append(f"◑ Session depth {depth:.1f} — users sticking to narrow feature set")
+
+ if not scores:
+ return 0.0, findings
+ return clamp(sum(scores) / len(scores)), findings
+
+
+def score_satisfaction(data: dict, thresholds: dict) -> tuple[float, list]:
+ s_data = data.get("satisfaction", {})
+ findings = []
+ scores = []
+
+ se_score = s_data.get("sean_ellis_very_disappointed")
+ se_n = s_data.get("sean_ellis_sample_size", 0)
+ if se_score is not None:
+ if se_n < 40:
+ findings.append(f"⚠ Sean Ellis n={se_n} — too small to be reliable. Need 40+ responses.")
+ scores.append(score_between(se_score, 0, thresholds["sean_ellis_strong"]) * 0.5) # half weight
+ else:
+ s = score_between(se_score, 0, thresholds["sean_ellis_strong"])
+ scores.append(s)
+ if se_score >= thresholds["sean_ellis_strong"]:
+ findings.append(f"✓ Sean Ellis {se_score:.0%} 'very disappointed' — strong PMF signal (n={se_n})")
+ elif se_score >= thresholds["sean_ellis_pmf"]:
+ findings.append(f"◑ Sean Ellis {se_score:.0%} — at PMF threshold. Push to > {thresholds['sean_ellis_strong']:.0%}.")
+ else:
+ findings.append(f"✗ Sean Ellis {se_score:.0%} — below {thresholds['sean_ellis_pmf']:.0%} threshold. Interview 'somewhat disappointed' group.")
+ else:
+ findings.append("⚠ No Sean Ellis data. Run a one-question survey to your active users now.")
+
+ nps = s_data.get("nps_score")
+ nps_n = s_data.get("nps_sample_size", 0)
+ if nps is not None:
+ if nps_n < 50:
+ findings.append(f"⚠ NPS n={nps_n} — sample too small. Need 50+ for reliability.")
+ # NPS ranges from -100 to 100; normalize to 0-1 against threshold
+ s = score_between(nps, -20, thresholds["nps_strong"])
+ scores.append(s)
+ if nps >= thresholds["nps_strong"]:
+ findings.append(f"✓ NPS {nps} — excellent. Promoters will drive organic growth.")
+ elif nps >= thresholds["nps_pmf"]:
+ findings.append(f"◑ NPS {nps} — acceptable. Focus on converting passives to promoters.")
+ elif nps >= 0:
+ findings.append(f"✗ NPS {nps} — low. More detractors than promoters is a warning sign.")
+ else:
+ findings.append(f"✗ NPS {nps} — negative. Active detractors outnumber promoters.")
+ else:
+ findings.append("⚠ No NPS data.")
+
+ if not scores:
+ return 0.0, findings
+ return clamp(sum(scores) / len(scores)), findings
+
+
+def score_growth(data: dict, _thresholds: dict) -> tuple[float, list]:
+ g = data.get("growth", {})
+ findings = []
+ scores = []
+
+ organic_pct = g.get("organic_signup_pct")
+ if organic_pct is not None:
+ s = score_between(organic_pct, 0.05, 0.50)
+ scores.append(s)
+ if organic_pct >= 0.30:
+ findings.append(f"✓ {organic_pct:.0%} organic signups — word of mouth is working")
+ elif organic_pct >= 0.20:
+ findings.append(f"◑ {organic_pct:.0%} organic — moderate. Build referral loop deliberately.")
+ else:
+ findings.append(f"✗ {organic_pct:.0%} organic — almost all paid. PMF may not be strong enough to generate word of mouth.")
+ else:
+ findings.append("⚠ No organic signup tracking. Tag all signup sources now.")
+
+ referral = g.get("referral_rate")
+ if referral is not None:
+ s = score_between(referral, 0.05, 0.35)
+ scores.append(s)
+ if referral >= 0.25:
+ findings.append(f"✓ {referral:.0%} of active users referring — strong viral signal")
+ elif referral >= 0.15:
+ findings.append(f"◑ {referral:.0%} referral rate — building. Add referral incentive or friction removal.")
+ else:
+ findings.append(f"✗ {referral:.0%} referral rate — users not recommending. Satisfaction or network effects missing.")
+ else:
+ findings.append("⚠ No referral rate data.")
+
+ mom = g.get("mom_growth_rate")
+ if mom is not None:
+ s = score_between(mom, 0, 0.20)
+ scores.append(s)
+ if mom >= 0.15:
+ findings.append(f"✓ {mom:.0%} MoM growth — strong momentum")
+ elif mom >= 0.08:
+ findings.append(f"◑ {mom:.0%} MoM growth — moderate. Identify top acquisition channel and double it.")
+ else:
+ findings.append(f"✗ {mom:.0%} MoM growth — slow. Acquisition is a bottleneck.")
+
+ if not scores:
+ return 0.0, findings
+ return clamp(sum(scores) / len(scores)), findings
+
+
+# ---------------------------------------------------------------------------
+# Overall scoring and recommendations
+# ---------------------------------------------------------------------------
+
+def pmf_status(overall: float) -> tuple[str, str]:
+ """Returns (status label, description)."""
+ if overall >= 0.80:
+ return "STRONG PMF", "Clear product-market fit. Shift focus to scaling acquisition and defending moat."
+ elif overall >= 0.60:
+ return "PMF APPROACHING", "Meaningful signals present. Identify and remove the 1-2 friction points blocking retention."
+ elif overall >= 0.40:
+ return "EARLY SIGNALS", "Weak PMF. Some users find value. Narrow your ICP and double down on what's working."
+ elif overall >= 0.20:
+ return "PRE-PMF", "No clear PMF yet. Don't scale acquisition. Focus entirely on retention experiments."
+ else:
+ return "NO SIGNAL", "No PMF signals detected. Revisit the problem hypothesis before investing further in the solution."
+
+
+def top_recommendations(dim_scores: dict, data: dict) -> list[str]:
+ """Prioritized recommendations based on weakest dimensions."""
+ recs = []
+ model = data.get("business_model", "b2b_saas")
+
+ ranked = sorted(dim_scores.items(), key=lambda x: x[1])
+
+ for dim, score in ranked:
+ if score < 0.40:
+ if dim == "retention":
+ recs.append(
+ "CRITICAL — Retention: Run cohort analysis by segment. Find the cohort with highest D30. "
+ "Interview 10 of those users. Build for them exclusively until retention flattens."
+ )
+ elif dim == "engagement":
+ recs.append(
+ "Engagement: Define your 'aha moment' — the one action that predicts long-term retention. "
+ "Measure time-to-aha. Remove every friction point on that path."
+ )
+ elif dim == "satisfaction":
+ recs.append(
+ "Satisfaction: Run Sean Ellis survey immediately (need n ≥ 40). "
+ "Interview every 'somewhat disappointed' user — the gap between 'somewhat' and 'very' is your product gap."
+ )
+ elif dim == "growth":
+ recs.append(
+ "Growth: Track signup source for every new user. If organic < 20%, "
+ "you may be papering over weak PMF with paid acquisition. Fix retention first."
+ )
+
+ if not recs:
+ recs.append(
+ "All dimensions scoring above threshold. Focus: "
+ "(1) Defend moat, (2) Expand ICP carefully, (3) Build referral flywheel."
+ )
+
+ if model == "b2b_saas":
+ recs.append("B2B tip: Track NRR (Net Revenue Retention). PMF in B2B requires expansion, not just retention.")
+ elif model == "consumer":
+ recs.append("Consumer tip: Find your D7 'magic moment'. The habit window is small — optimize for it.")
+ elif model == "plg":
+ recs.append("PLG tip: Define your PQL (product-qualified lead). The activation event that predicts paid conversion.")
+ elif model == "marketplace":
+ recs.append("Marketplace tip: Measure both sides separately. PMF on demand side ≠ PMF on supply side.")
+
+ return recs
+
+
+# ---------------------------------------------------------------------------
+# Report renderer
+# ---------------------------------------------------------------------------
+
+def render_report(data: dict, dim_scores: dict, dim_findings: dict, overall: float) -> str:
+ status, description = pmf_status(overall)
+ recs = top_recommendations(dim_scores, data)
+
+ lines = []
+ lines.append("=" * 60)
+ lines.append(f" PMF SCORER — {data.get('product_name', 'Product')}")
+ lines.append(f" Model: {data.get('business_model', 'unknown').upper()}")
+ lines.append("=" * 60)
+ lines.append("")
+
+ # Overall
+ bar_len = 40
+ filled = round(overall * bar_len)
+ bar = "█" * filled + "░" * (bar_len - filled)
+ lines.append(f" Overall PMF Score: {overall:.0%}")
+ lines.append(f" [{bar}]")
+ lines.append(f" Status: {status}")
+ lines.append(f" {description}")
+ lines.append("")
+
+ # Dimension breakdown
+ lines.append(" DIMENSION SCORES")
+ lines.append(" " + "-" * 50)
+ for dim, weight in DIMENSION_WEIGHTS.items():
+ score = dim_scores.get(dim, 0.0)
+ dim_bar_len = 20
+ dim_filled = round(score * dim_bar_len)
+ dim_bar = "█" * dim_filled + "░" * (dim_bar_len - dim_filled)
+ label = dim.capitalize().ljust(12)
+ lines.append(f" {label} [{dim_bar}] {score:.0%} (weight: {weight:.0%})")
+ lines.append("")
+
+ # Findings per dimension
+ for dim in ["retention", "engagement", "satisfaction", "growth"]:
+ findings = dim_findings.get(dim, [])
+ if findings:
+ lines.append(f" {dim.upper()} FINDINGS")
+ for f in findings:
+ lines.append(f" {f}")
+ lines.append("")
+
+ # Recommendations
+ lines.append(" PRIORITIZED RECOMMENDATIONS")
+ lines.append(" " + "-" * 50)
+ for i, rec in enumerate(recs, 1):
+ # Wrap at 70 chars
+ words = rec.split()
+ line = f" {i}. "
+ for word in words:
+ if len(line) + len(word) + 1 > 72:
+ lines.append(line)
+ line = " " + word + " "
+ else:
+ line += word + " "
+ lines.append(line.rstrip())
+ lines.append("")
+ lines.append("=" * 60)
+
+ return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def run(data: dict) -> dict:
+ """
+ Score PMF from input data dict.
+ Returns dict with overall score, dimension scores, and findings.
+ """
+ model = data.get("business_model", "b2b_saas")
+ thresholds = THRESHOLDS.get(model, THRESHOLDS["b2b_saas"])
+
+ dim_scores = {}
+ dim_findings = {}
+
+ ret_score, ret_findings = score_retention(data, thresholds)
+ dim_scores["retention"] = ret_score
+ dim_findings["retention"] = ret_findings
+
+ eng_score, eng_findings = score_engagement(data, thresholds)
+ dim_scores["engagement"] = eng_score
+ dim_findings["engagement"] = eng_findings
+
+ sat_score, sat_findings = score_satisfaction(data, thresholds)
+ dim_scores["satisfaction"] = sat_score
+ dim_findings["satisfaction"] = sat_findings
+
+ grow_score, grow_findings = score_growth(data, thresholds)
+ dim_scores["growth"] = grow_score
+ dim_findings["growth"] = grow_findings
+
+ overall = sum(
+ dim_scores[dim] * weight
+ for dim, weight in DIMENSION_WEIGHTS.items()
+ )
+
+ return {
+ "overall": overall,
+ "dim_scores": dim_scores,
+ "dim_findings": dim_findings,
+ "status": pmf_status(overall)[0],
+ }
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="PMF Scorer — Multi-dimensional Product-Market Fit analysis",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=__doc__,
+ )
+ parser.add_argument(
+ "--input", "-i",
+ metavar="FILE",
+ help="JSON file with your product data (default: built-in sample data)",
+ )
+ parser.add_argument(
+ "--json",
+ action="store_true",
+ help="Output raw JSON instead of formatted report",
+ )
+ args = parser.parse_args()
+
+ if args.input:
+ try:
+ with open(args.input) as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: file not found: {args.input}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: invalid JSON: {e}", file=sys.stderr)
+ sys.exit(1)
+ else:
+ print("No input file provided — running with sample data.\n")
+ data = sample_data()
+
+ result = run(data)
+
+ if args.json:
+ output = {
+ "product_name": data.get("product_name"),
+ "business_model": data.get("business_model"),
+ "overall_score": round(result["overall"], 4),
+ "overall_pct": f"{result['overall']:.0%}",
+ "status": result["status"],
+ "dimensions": {
+ dim: {
+ "score": round(result["dim_scores"][dim], 4),
+ "pct": f"{result['dim_scores'][dim]:.0%}",
+ "weight": f"{DIMENSION_WEIGHTS[dim]:.0%}",
+ "findings": result["dim_findings"][dim],
+ }
+ for dim in DIMENSION_WEIGHTS
+ },
+ }
+ print(json.dumps(output, indent=2))
+ else:
+ print(render_report(data, result["dim_scores"], result["dim_findings"], result["overall"]))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cpo-advisor/scripts/portfolio_analyzer.py b/skills/c-level-advisor/cpo-advisor/scripts/portfolio_analyzer.py
new file mode 100644
index 00000000..ea6d9c5e
--- /dev/null
+++ b/skills/c-level-advisor/cpo-advisor/scripts/portfolio_analyzer.py
@@ -0,0 +1,547 @@
+#!/usr/bin/env python3
+"""
+Portfolio Analyzer — Product portfolio BCG matrix classification and investment analysis.
+
+For each product, classifies into BCG quadrant (Star, Cash Cow, Question Mark, Dog)
+and generates investment recommendations (Invest / Maintain / Kill).
+
+Usage:
+ python portfolio_analyzer.py # Run with built-in sample data
+ python portfolio_analyzer.py --input data.json # Run with your data
+ python portfolio_analyzer.py --json # Output raw JSON
+
+JSON input format: see sample_data() function below.
+"""
+
+import json
+import sys
+import argparse
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def sample_data() -> dict:
+ """
+ Sample portfolio. Replace with real product data.
+
+ Fields:
+ name Product name
+ revenue_quarterly Current quarter revenue (any consistent currency)
+ revenue_prev_q Revenue last quarter (for QoQ calculation)
+ market_growth_pct Annual market growth rate (percent, e.g. 12.5 for 12.5%)
+ your_market_share Your estimated market share (percent, e.g. 8.0 for 8%)
+ largest_competitor_share Largest competitor's share (percent)
+ eng_capacity_pct % of total engineering capacity allocated (0-100)
+ d30_retention Optional D30 retention rate (decimal, e.g. 0.45)
+ nps Optional NPS score (-100 to 100)
+ notes Optional free text notes for the report
+ """
+ return {
+ "company": "Acme Corp",
+ "total_engineering_headcount": 45,
+ "products": [
+ {
+ "name": "CorePlatform",
+ "revenue_quarterly": 480000,
+ "revenue_prev_q": 430000,
+ "market_growth_pct": 22.0,
+ "your_market_share": 18.0,
+ "largest_competitor_share": 12.0,
+ "eng_capacity_pct": 35,
+ "d30_retention": 0.61,
+ "nps": 52,
+ "notes": "Our flagship. Leading market share in fast-growing segment.",
+ },
+ {
+ "name": "ReportingModule",
+ "revenue_quarterly": 290000,
+ "revenue_prev_q": 285000,
+ "market_growth_pct": 5.0,
+ "your_market_share": 22.0,
+ "largest_competitor_share": 18.0,
+ "eng_capacity_pct": 25,
+ "d30_retention": 0.58,
+ "nps": 38,
+ "notes": "Mature product, strong margins, slow market.",
+ },
+ {
+ "name": "MobileApp",
+ "revenue_quarterly": 95000,
+ "revenue_prev_q": 78000,
+ "market_growth_pct": 35.0,
+ "your_market_share": 3.5,
+ "largest_competitor_share": 24.0,
+ "eng_capacity_pct": 28,
+ "d30_retention": 0.31,
+ "nps": 22,
+ "notes": "High growth market. We're far behind on share. Bet or exit.",
+ },
+ {
+ "name": "LegacyConnector",
+ "revenue_quarterly": 62000,
+ "revenue_prev_q": 68000,
+ "market_growth_pct": -3.0,
+ "your_market_share": 8.0,
+ "largest_competitor_share": 35.0,
+ "eng_capacity_pct": 12,
+ "d30_retention": 0.42,
+ "nps": 14,
+ "notes": "Declining market. Customers are on long-term contracts.",
+ },
+ ],
+ }
+
+
+# ---------------------------------------------------------------------------
+# BCG Classification
+# ---------------------------------------------------------------------------
+
+# Growth rate threshold: markets growing faster than this are "high growth"
+GROWTH_THRESHOLD_PCT = 10.0
+
+# Market share ratio threshold: ratio > 1.0 means you lead the market
+SHARE_RATIO_THRESHOLD = 1.0
+
+
+def bcg_quadrant(market_growth_pct: float, share_ratio: float) -> str:
+ high_growth = market_growth_pct >= GROWTH_THRESHOLD_PCT
+ leading_share = share_ratio >= SHARE_RATIO_THRESHOLD
+
+ if high_growth and leading_share:
+ return "Star"
+ elif not high_growth and leading_share:
+ return "Cash Cow"
+ elif high_growth and not leading_share:
+ return "Question Mark"
+ else:
+ return "Dog"
+
+
+def quadrant_emoji(quadrant: str) -> str:
+ return {
+ "Star": "⭐",
+ "Cash Cow": "🐄",
+ "Question Mark": "❓",
+ "Dog": "🐕",
+ }.get(quadrant, "?")
+
+
+def investment_posture(quadrant: str, qoq_growth: float, retention: Optional[float]) -> str:
+ """
+ Invest / Maintain / Kill recommendation with nuance.
+ """
+ if quadrant == "Star":
+ return "Invest"
+ elif quadrant == "Cash Cow":
+ # If cash cow is declining fast or retention is poor, consider killing
+ if qoq_growth < -0.10 or (retention is not None and retention < 0.30):
+ return "Kill"
+ return "Maintain"
+ elif quadrant == "Question Mark":
+ # Fast QoQ growth signals the bet might pay off → Invest
+ # Flat or slow QoQ with weak retention → Kill
+ if qoq_growth >= 0.15 and (retention is None or retention >= 0.25):
+ return "Invest"
+ elif qoq_growth < 0.05 or (retention is not None and retention < 0.20):
+ return "Kill"
+ return "Evaluate" # Needs explicit strategic decision
+ else: # Dog
+ if qoq_growth > 0.10 and (retention is None or retention >= 0.35):
+ return "Evaluate" # Surprising momentum — verify before killing
+ return "Kill"
+
+
+def posture_color(posture: str) -> str:
+ return {
+ "Invest": "✓",
+ "Maintain": "◑",
+ "Kill": "✗",
+ "Evaluate": "⚠",
+ }.get(posture, "?")
+
+
+# ---------------------------------------------------------------------------
+# Product analysis
+# ---------------------------------------------------------------------------
+
+def analyze_product(p: dict) -> dict:
+ revenue_q = p.get("revenue_quarterly", 0)
+ revenue_prev = p.get("revenue_prev_q", revenue_q)
+ qoq_growth = (revenue_q - revenue_prev) / revenue_prev if revenue_prev else 0.0
+
+ your_share = p.get("your_market_share", 0)
+ competitor_share = p.get("largest_competitor_share", 1)
+ share_ratio = your_share / competitor_share if competitor_share else 0.0
+
+ market_growth = p.get("market_growth_pct", 0)
+ retention = p.get("d30_retention")
+ nps = p.get("nps")
+ eng_pct = p.get("eng_capacity_pct", 0)
+
+ quadrant = bcg_quadrant(market_growth, share_ratio)
+ posture = investment_posture(quadrant, qoq_growth, retention)
+
+ # Alignment score: how well does engineering investment match the recommended posture?
+ # Invest products should have high eng allocation; Kill products should have low.
+ alignment_score = _compute_alignment(posture, eng_pct)
+
+ return {
+ "name": p.get("name", "Unknown"),
+ "revenue_quarterly": revenue_q,
+ "revenue_prev_q": revenue_prev,
+ "qoq_growth": qoq_growth,
+ "market_growth_pct": market_growth,
+ "your_market_share": your_share,
+ "largest_competitor_share": competitor_share,
+ "share_ratio": share_ratio,
+ "eng_capacity_pct": eng_pct,
+ "d30_retention": retention,
+ "nps": nps,
+ "quadrant": quadrant,
+ "posture": posture,
+ "alignment_score": alignment_score,
+ "notes": p.get("notes", ""),
+ "findings": _product_findings(quadrant, posture, qoq_growth, share_ratio,
+ market_growth, retention, nps, eng_pct),
+ }
+
+
+def _compute_alignment(posture: str, eng_pct: float) -> float:
+ """
+ Returns 0.0-1.0 score. High = engineering allocation matches strategic posture.
+ """
+ targets = {"Invest": 0.35, "Maintain": 0.15, "Kill": 0.05, "Evaluate": 0.20}
+ target = targets.get(posture, 0.20)
+ deviation = abs(eng_pct / 100 - target)
+ return max(0.0, 1.0 - (deviation / 0.35))
+
+
+def _product_findings(
+ quadrant: str, posture: str,
+ qoq_growth: float, share_ratio: float, market_growth: float,
+ retention: Optional[float], nps: Optional[int], eng_pct: float
+) -> list:
+ findings = []
+
+ if quadrant == "Star":
+ if eng_pct < 30:
+ findings.append(f"⚠ Star product getting only {eng_pct}% of eng capacity — likely underinvested. Stars need fuel.")
+ else:
+ findings.append(f"✓ Star product with {eng_pct}% eng allocation — appropriate investment.")
+ if share_ratio < 1.5:
+ findings.append(f"◑ Share ratio {share_ratio:.1f}x — leading but not dominant. Accelerate to widen the gap.")
+ else:
+ findings.append(f"✓ Share ratio {share_ratio:.1f}x — strong lead. Defend aggressively.")
+
+ elif quadrant == "Cash Cow":
+ if eng_pct > 25:
+ findings.append(f"⚠ Cash Cow getting {eng_pct}% of eng — overinvested. Reduce to 10-15% max. Redeploy to Stars.")
+ else:
+ findings.append(f"✓ Cash Cow with {eng_pct}% eng — appropriate. Don't innovate, just maintain.")
+ if qoq_growth < -0.05:
+ findings.append(f"⚠ Revenue declining {abs(qoq_growth):.0%} QoQ — monitor for transition to Dog.")
+ else:
+ findings.append(f"✓ Revenue stable (QoQ: {qoq_growth:+.0%}) — milk this.")
+
+ elif quadrant == "Question Mark":
+ findings.append(f"⚠ Fast market ({market_growth:.0f}% growth) but only {share_ratio:.1f}x relative share.")
+ findings.append(f" Decision required: Invest to capture share or exit. 'Maintain' loses share every quarter.")
+ if qoq_growth >= 0.15:
+ findings.append(f"✓ QoQ growth {qoq_growth:+.0%} — momentum building. Investment may be justified.")
+ elif qoq_growth < 0.05:
+ findings.append(f"✗ QoQ growth {qoq_growth:+.0%} — stalled despite hot market. Strong exit signal.")
+
+ elif quadrant == "Dog":
+ findings.append(f"✗ Low share ({share_ratio:.1f}x) in slow/declining market ({market_growth:.0f}% growth).")
+ if eng_pct > 10:
+ findings.append(f"✗ Dog consuming {eng_pct}% of eng capacity. Set a sunset date. Migrate customers.")
+ if qoq_growth > 0:
+ findings.append(f"◑ Slight QoQ growth ({qoq_growth:+.0%}) — verify whether this is genuine or contract timing.")
+
+ if retention is not None:
+ if retention < 0.30:
+ findings.append(f"✗ D30 retention {retention:.0%} — users not finding value. Weak unit economics for any posture.")
+ elif retention >= 0.50:
+ findings.append(f"✓ D30 retention {retention:.0%} — users find value. Supports investment or stable maintenance.")
+
+ if nps is not None:
+ if nps < 0:
+ findings.append(f"✗ NPS {nps} — net detractors. Word of mouth is negative. Fix before scaling.")
+ elif nps >= 40:
+ findings.append(f"✓ NPS {nps} — strong promoter base. Harness for referrals.")
+
+ return findings
+
+
+# ---------------------------------------------------------------------------
+# Portfolio-level analysis
+# ---------------------------------------------------------------------------
+
+def analyze_portfolio(data: dict) -> dict:
+ products = [analyze_product(p) for p in data.get("products", [])]
+
+ total_revenue = sum(p["revenue_quarterly"] for p in products)
+ total_eng = sum(p["eng_capacity_pct"] for p in products)
+
+ # Revenue by quadrant
+ quadrant_revenue = {}
+ quadrant_eng = {}
+ for p in products:
+ q = p["quadrant"]
+ quadrant_revenue[q] = quadrant_revenue.get(q, 0) + p["revenue_quarterly"]
+ quadrant_eng[q] = quadrant_eng.get(q, 0) + p["eng_capacity_pct"]
+
+ # Portfolio health score
+ health = _portfolio_health(products, total_revenue, total_eng)
+
+ # Portfolio-level findings
+ portfolio_findings = _portfolio_findings(products, total_revenue, quadrant_revenue, quadrant_eng)
+
+ return {
+ "company": data.get("company", "Unknown"),
+ "total_engineering_headcount": data.get("total_engineering_headcount"),
+ "products": products,
+ "total_revenue_quarterly": total_revenue,
+ "quadrant_summary": {
+ q: {
+ "count": sum(1 for p in products if p["quadrant"] == q),
+ "revenue": quadrant_revenue.get(q, 0),
+ "revenue_pct": quadrant_revenue.get(q, 0) / total_revenue if total_revenue else 0,
+ "eng_pct": quadrant_eng.get(q, 0),
+ }
+ for q in ["Star", "Cash Cow", "Question Mark", "Dog"]
+ },
+ "portfolio_health_score": health,
+ "portfolio_findings": portfolio_findings,
+ }
+
+
+def _portfolio_health(products: list, total_revenue: float, total_eng: float) -> float:
+ """
+ Portfolio health 0-1. Penalizes:
+ - No Stars (no growth engine)
+ - Dogs consuming > 20% of eng
+ - Poor alignment scores
+ - Revenue concentrated in Dogs/Question Marks
+ """
+ score = 1.0
+
+ quadrants = [p["quadrant"] for p in products]
+ has_star = "Star" in quadrants
+ has_cash_cow = "Cash Cow" in quadrants
+
+ if not has_star:
+ score -= 0.25 # No growth engine is a serious problem
+ if not has_cash_cow:
+ score -= 0.10 # No cash generator means funding stars from burn
+
+ # Dog eng allocation penalty
+ dog_eng = sum(p["eng_capacity_pct"] for p in products if p["quadrant"] == "Dog")
+ if dog_eng > 20:
+ score -= 0.20
+ elif dog_eng > 10:
+ score -= 0.10
+
+ # Revenue in dogs penalty
+ if total_revenue > 0:
+ dog_rev_pct = sum(p["revenue_quarterly"] for p in products if p["quadrant"] == "Dog") / total_revenue
+ if dog_rev_pct > 0.30:
+ score -= 0.15
+
+ # Average alignment score
+ avg_alignment = sum(p["alignment_score"] for p in products) / len(products) if products else 0
+ score -= (1 - avg_alignment) * 0.20
+
+ return max(0.0, min(1.0, score))
+
+
+def _portfolio_findings(
+ products: list, total_revenue: float,
+ quadrant_revenue: dict, quadrant_eng: dict
+) -> list:
+ findings = []
+
+ stars = [p for p in products if p["quadrant"] == "Star"]
+ cows = [p for p in products if p["quadrant"] == "Cash Cow"]
+ questions = [p for p in products if p["quadrant"] == "Question Mark"]
+ dogs = [p for p in products if p["quadrant"] == "Dog"]
+
+ if not stars:
+ findings.append("✗ CRITICAL: No Star products. You have no growth engine. Identify a Question Mark to invest in or revisit your market positioning.")
+ elif len(stars) == 1:
+ findings.append(f"◑ Single Star ({stars[0]['name']}). Portfolio is fragile — one product drives all growth. Diversify.")
+ else:
+ findings.append(f"✓ {len(stars)} Star products — healthy growth engine.")
+
+ if not cows:
+ findings.append("⚠ No Cash Cow products. Stars are consuming capital without a self-funding mechanism. Watch burn rate.")
+ else:
+ cow_rev = quadrant_revenue.get("Cash Cow", 0)
+ cow_pct = cow_rev / total_revenue if total_revenue else 0
+ findings.append(f"✓ Cash Cow revenue: {cow_pct:.0%} of total — funds Star investment.")
+
+ if questions:
+ findings.append(f"⚠ {len(questions)} Question Mark(s): {', '.join(p['name'] for p in questions)}.")
+ findings.append(" Each needs a binary decision: invest to win share, or exit. Set a 2-quarter deadline.")
+
+ if dogs:
+ dog_eng_total = sum(p["eng_capacity_pct"] for p in dogs)
+ findings.append(f"✗ {len(dogs)} Dog product(s): {', '.join(p['name'] for p in dogs)} consuming {dog_eng_total}% of eng capacity.")
+ findings.append(f" That's {dog_eng_total}% of your engineers on declining products. Set sunset dates.")
+
+ # Alignment check
+ misaligned = [p for p in products if p["alignment_score"] < 0.50]
+ if misaligned:
+ findings.append(f"⚠ Engineering allocation misaligned on: {', '.join(p['name'] for p in misaligned)}.")
+ findings.append(" Rebalance: move capacity from Dogs/Cows to Stars.")
+
+ return findings
+
+
+# ---------------------------------------------------------------------------
+# Report rendering
+# ---------------------------------------------------------------------------
+
+def fmt_currency(n: float) -> str:
+ if n >= 1_000_000:
+ return f"${n/1_000_000:.1f}M"
+ elif n >= 1_000:
+ return f"${n/1_000:.0f}K"
+ return f"${n:.0f}"
+
+
+def render_report(result: dict) -> str:
+ lines = []
+ lines.append("=" * 65)
+ lines.append(f" PORTFOLIO ANALYZER — {result['company']}")
+ lines.append(f" Total Quarterly Revenue: {fmt_currency(result['total_revenue_quarterly'])}")
+ if result.get("total_engineering_headcount"):
+ lines.append(f" Engineering Headcount: {result['total_engineering_headcount']}")
+ lines.append("=" * 65)
+ lines.append("")
+
+ # Portfolio health
+ health = result["portfolio_health_score"]
+ bar_len = 40
+ filled = round(health * bar_len)
+ bar = "█" * filled + "░" * (bar_len - filled)
+ lines.append(f" Portfolio Health: {health:.0%}")
+ lines.append(f" [{bar}]")
+ lines.append("")
+
+ # Quadrant summary
+ lines.append(" QUADRANT SUMMARY")
+ lines.append(" " + "-" * 55)
+ header = f" {'Quadrant':<15} {'Count':>5} {'Revenue':>10} {'Rev%':>6} {'Eng%':>6}"
+ lines.append(header)
+ lines.append(" " + "-" * 55)
+ total_rev = result["total_revenue_quarterly"]
+ for q in ["Star", "Cash Cow", "Question Mark", "Dog"]:
+ qs = result["quadrant_summary"][q]
+ emoji = quadrant_emoji(q)
+ label = f"{emoji} {q}"
+ rev_pct = f"{qs['revenue_pct']:.0%}" if qs["count"] else "-"
+ eng = f"{qs['eng_pct']}%" if qs["count"] else "-"
+ rev = fmt_currency(qs["revenue"]) if qs["count"] else "-"
+ lines.append(f" {label:<15} {qs['count']:>5} {rev:>10} {rev_pct:>6} {eng:>6}")
+ lines.append("")
+
+ # Per-product breakdown
+ lines.append(" PRODUCT BREAKDOWN")
+ lines.append(" " + "-" * 65)
+ for p in result["products"]:
+ emoji = quadrant_emoji(p["quadrant"])
+ pc = posture_color(p["posture"])
+ lines.append(
+ f" {emoji} {p['name']} — {p['quadrant']} → {pc} {p['posture']}"
+ )
+ lines.append(
+ f" Revenue: {fmt_currency(p['revenue_quarterly'])}/qtr "
+ f"QoQ: {p['qoq_growth']:+.0%} "
+ f"Mkt growth: {p['market_growth_pct']:+.0f}%"
+ )
+ lines.append(
+ f" Share ratio: {p['share_ratio']:.1f}x "
+ f"Eng: {p['eng_capacity_pct']}% "
+ f"Alignment: {p['alignment_score']:.0%}"
+ )
+ if p.get("d30_retention") is not None:
+ lines.append(
+ f" D30 retention: {p['d30_retention']:.0%} "
+ f"NPS: {p['nps'] if p['nps'] is not None else 'N/A'}"
+ )
+ if p.get("notes"):
+ lines.append(f" Note: {p['notes']}")
+ for f in p.get("findings", []):
+ lines.append(f" {f}")
+ lines.append("")
+
+ # Portfolio-level findings
+ lines.append(" PORTFOLIO FINDINGS")
+ lines.append(" " + "-" * 65)
+ for f in result.get("portfolio_findings", []):
+ lines.append(f" {f}")
+ lines.append("")
+ lines.append("=" * 65)
+
+ return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Portfolio Analyzer — BCG matrix classification and investment recommendations",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=__doc__,
+ )
+ parser.add_argument(
+ "--input", "-i",
+ metavar="FILE",
+ help="JSON file with portfolio data (default: built-in sample data)",
+ )
+ parser.add_argument(
+ "--json",
+ action="store_true",
+ help="Output raw JSON result",
+ )
+ args = parser.parse_args()
+
+ if args.input:
+ try:
+ with open(args.input) as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: file not found: {args.input}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: invalid JSON: {e}", file=sys.stderr)
+ sys.exit(1)
+ else:
+ print("No input file provided — running with sample data.\n")
+ data = sample_data()
+
+ result = analyze_portfolio(data)
+
+ if args.json:
+ # Make result JSON-serializable
+ def clean(obj):
+ if isinstance(obj, dict):
+ return {k: clean(v) for k, v in obj.items()}
+ elif isinstance(obj, list):
+ return [clean(v) for v in obj]
+ elif isinstance(obj, float):
+ return round(obj, 4)
+ return obj
+ print(json.dumps(clean(result), indent=2))
+ else:
+ print(render_report(result))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cro-advisor/SKILL.md b/skills/c-level-advisor/cro-advisor/SKILL.md
new file mode 100644
index 00000000..e52a3786
--- /dev/null
+++ b/skills/c-level-advisor/cro-advisor/SKILL.md
@@ -0,0 +1,183 @@
+---
+name: "cro-advisor"
+description: "Revenue leadership for B2B SaaS companies. Revenue forecasting, sales model design, pricing strategy, net revenue retention, and sales team scaling. Use when designing the revenue engine, setting quotas, modeling NRR, evaluating pricing, building board forecasts, or when user mentions CRO, chief revenue officer, revenue strategy, sales model, ARR growth, NRR, expansion revenue, churn, pricing strategy, or sales capacity."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: cro-leadership
+ updated: 2026-03-05
+ python-tools: revenue_forecast_model.py, churn_analyzer.py
+ frameworks: sales-playbook, pricing-strategy, nrr-playbook
+---
+
+# CRO Advisor
+
+Revenue frameworks for building predictable, scalable revenue engines — from $1M ARR to $100M and beyond.
+
+## Keywords
+CRO, chief revenue officer, revenue strategy, ARR, MRR, sales model, pipeline, revenue forecasting, pricing strategy, net revenue retention, NRR, gross revenue retention, GRR, expansion revenue, upsell, cross-sell, churn, customer success, sales capacity, quota, ramp, territory design, MEDDPICC, PLG, product-led growth, sales-led growth, enterprise sales, SMB, self-serve, value-based pricing, usage-based pricing, ICP, ideal customer profile, revenue board reporting, sales cycle, CAC payback, magic number
+
+## Quick Start
+
+### Revenue Forecasting
+```bash
+python scripts/revenue_forecast_model.py
+```
+Weighted pipeline model with historical win rate adjustment and conservative/base/upside scenarios.
+
+### Churn & Retention Analysis
+```bash
+python scripts/churn_analyzer.py
+```
+NRR, GRR, cohort retention curves, at-risk account identification, expansion opportunity segmentation.
+
+## Diagnostic Questions
+
+Ask these before any framework:
+
+**Revenue Health**
+- What's your NRR? If below 100%, everything else is a leaky bucket.
+- What percentage of ARR comes from expansion vs. new logo?
+- What's your GRR (retention floor without expansion)?
+
+**Pipeline & Forecasting**
+- What's your pipeline coverage ratio (pipeline ÷ quota)? Under 3x is a problem.
+- Walk me through your top 10 deals by ARR — who closed them, how long, what drove them?
+- What's your stage-by-stage conversion rate? Where do deals die?
+
+**Sales Team**
+- What % of your sales team hit quota last quarter?
+- What's average ramp time before a new AE is quota-attaining?
+- What's the sales cycle variance by segment? High variance = unpredictable forecasts.
+
+**Pricing**
+- How do customers articulate the value they get? What outcome do you deliver?
+- When did you last raise prices? What happened to win rate?
+- If fewer than 20% of prospects push back on price, you're underpriced.
+
+## Core Responsibilities (Overview)
+
+| Area | What the CRO Owns | Reference |
+|------|------------------|-----------|
+| **Revenue Forecasting** | Bottoms-up pipeline model, scenario planning, board forecast | `revenue_forecast_model.py` |
+| **Sales Model** | PLG vs. sales-led vs. hybrid, team structure, stage definitions | `references/sales_playbook.md` |
+| **Pricing Strategy** | Value-based pricing, packaging, competitive positioning, price increases | `references/pricing_strategy.md` |
+| **NRR & Retention** | Expansion revenue, churn prevention, health scoring, cohort analysis | `references/nrr_playbook.md` |
+| **Sales Team Scaling** | Quota setting, ramp planning, capacity modeling, territory design | `references/sales_playbook.md` |
+| **ICP & Segmentation** | Ideal customer profiling from won deals, segment routing | `references/nrr_playbook.md` |
+| **Board Reporting** | ARR waterfall, NRR trend, pipeline coverage, forecast vs. actual | `revenue_forecast_model.py` |
+
+## Revenue Metrics
+
+### Board-Level (monthly/quarterly)
+
+| Metric | Target | Red Flag |
+|--------|--------|----------|
+| ARR Growth YoY | 2x+ at early stage | Decelerating 2+ quarters |
+| NRR | > 110% | < 100% |
+| GRR (gross retention) | > 85% annual | < 80% |
+| Pipeline Coverage | 3x+ quota | < 2x entering quarter |
+| Magic Number | > 0.75 | < 0.5 (fix unit economics before spending more) |
+| CAC Payback | < 18 months | > 24 months |
+| Quota Attainment % | 60-70% of reps | < 50% (calibration problem) |
+
+**Magic Number:** Net New ARR × 4 ÷ Prior Quarter S&M Spend
+**CAC Payback:** S&M Spend ÷ New Logo ARR × (1 / Gross Margin %)
+
+### Revenue Waterfall
+
+```
+Opening ARR
+ + New Logo ARR
+ + Expansion ARR (upsell, cross-sell, seat adds)
+ - Contraction ARR (downgrades)
+ - Churned ARR
+= Closing ARR
+
+NRR = (Opening + Expansion - Contraction - Churn) / Opening
+```
+
+### NRR Benchmarks
+
+| NRR | Signal |
+|-----|--------|
+| > 120% | World-class. Grow even with zero new logos. |
+| 100-120% | Healthy. Existing base is growing. |
+| 90-100% | Concerning. Churn eating growth. |
+| < 90% | Crisis. Fix before scaling sales. |
+
+## Red Flags
+
+- NRR declining two quarters in a row — customer value story is broken
+- Pipeline coverage below 3x entering the quarter — already forecasting a miss
+- Win rate dropping while sales cycle extends — competitive pressure or ICP drift
+- < 50% of sales team quota-attaining — comp plan, ramp, or quota calibration issue
+- Average deal size declining — moving downmarket under pressure (dangerous)
+- Magic Number below 0.5 — sales spend not converting to revenue
+- Forecast accuracy below 80% — reps sandbagging or pipeline quality is poor
+- Single customer > 15% of ARR — concentration risk, board will flag this
+- "Too expensive" appearing in > 40% of loss notes — value demonstration broken, not pricing
+- Expansion ARR < 20% of total ARR — upsell motion isn't working
+
+## Integration with Other C-Suite Roles
+
+| When... | CRO works with... | To... |
+|---------|------------------|-------|
+| Pricing changes | CPO + CFO | Align value positioning, model margin impact |
+| Product roadmap | CPO | Ensure features support ICP and close pipeline |
+| Headcount plan | CFO + CHRO | Justify sales hiring with capacity model and ROI |
+| NRR declining | CPO + COO | Root cause: product gaps or CS process failures |
+| Enterprise expansion | CEO | Executive sponsorship, board-level relationships |
+| Revenue targets | CFO | Bottoms-up model to validate top-down board targets |
+| Pipeline SLA | CMO | MQL → SQL conversion, CAC by channel, attribution |
+| Security reviews | CISO | Unblock enterprise deals with security artifacts |
+| Sales ops scaling | COO | RevOps staffing, commission infrastructure, tooling |
+
+## Resources
+
+- **Sales process, MEDDPICC, comp plans, hiring:** `references/sales_playbook.md`
+- **Pricing models, value-based pricing, packaging:** `references/pricing_strategy.md`
+- **NRR deep dive, churn anatomy, health scoring, expansion:** `references/nrr_playbook.md`
+- **Revenue forecast model (CLI):** `scripts/revenue_forecast_model.py`
+- **Churn & retention analyzer (CLI):** `scripts/churn_analyzer.py`
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- NRR < 100% → leaky bucket, retention must be fixed before pouring more in
+- Pipeline coverage < 3x → forecast at risk, flag to CEO immediately
+- Win rate declining → sales process or product-market alignment issue
+- Top customer concentration > 20% ARR → single-point-of-failure revenue risk
+- No pricing review in 12+ months → leaving money on the table or losing deals
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Forecast next quarter" | Pipeline-based forecast with confidence intervals |
+| "Analyze our churn" | Cohort churn analysis with at-risk accounts and intervention plan |
+| "Review our pricing" | Pricing analysis with competitive benchmarks and recommendations |
+| "Scale the sales team" | Capacity model with quota, ramp, territories, comp plan |
+| "Revenue board section" | ARR waterfall, NRR, pipeline, forecast, risks |
+
+## Reasoning Technique: Chain of Thought
+
+Pipeline math must be explicit: leads → MQLs → SQLs → opportunities → closed. Show conversion rates at each stage. Question any assumption above historical averages.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/c-level-advisor/cro-advisor/references/nrr_playbook.md b/skills/c-level-advisor/cro-advisor/references/nrr_playbook.md
new file mode 100644
index 00000000..ea3851a8
--- /dev/null
+++ b/skills/c-level-advisor/cro-advisor/references/nrr_playbook.md
@@ -0,0 +1,380 @@
+# NRR Playbook
+
+Net Revenue Retention is the single most important metric for a SaaS company's health and valuation. A company with 120% NRR grows even if it closes zero new deals. A company with 80% NRR is filling a bucket with a hole in it.
+
+---
+
+## NRR Deep Dive
+
+### The Fundamental Formula
+
+```
+NRR = (Opening MRR + Expansion MRR - Contraction MRR - Churned MRR) / Opening MRR
+
+Example:
+ Opening MRR: $1,000,000
+ Expansion: +$150,000
+ Contraction: -$30,000
+ Churn: -$80,000
+ Closing MRR: $1,040,000
+ NRR = $1,040,000 / $1,000,000 = 104%
+```
+
+### NRR vs. GRR
+
+| Metric | Formula | What It Tells You |
+|--------|---------|------------------|
+| **GRR** | (Opening - Contraction - Churn) / Opening | Retention floor — how much you keep without any expansion |
+| **NRR** | (Opening + Expansion - Contraction - Churn) / Opening | Net health — expansion offsetting churn |
+| **Logo Retention** | (Customers start - Customers churned) / Customers start | Volume retention, ignores revenue weight |
+
+**GRR is the floor. NRR is the ceiling.**
+
+If GRR is 80% and NRR is 105%, your expansion is covering 25 points of churn. That's fragile — any expansion slowdown turns NRR negative. The fix is GRR, not more upsell.
+
+### Benchmarks by Segment
+
+| Segment | Good GRR | Good NRR | Exceptional NRR |
+|---------|---------|---------|----------------|
+| SMB-focused | 80-85% | 95-105% | > 110% |
+| Mid-Market | 85-90% | 105-115% | > 120% |
+| Enterprise | 90-95% | 115-130% | > 140% |
+
+Enterprise NRR can exceed 140% because large accounts expand substantially and rarely churn entirely — they may downgrade but full logo churn is rare if the product is embedded.
+
+### NRR by Cohort
+
+Don't just measure NRR across the full base — measure it by customer cohort (month of acquisition).
+
+```
+Jan 2024 Cohort:
+ Opening MRR (Jan 2024): $50,000
+ MRR at Jan 2025: $62,000
+ 12-month NRR: 124%
+
+Feb 2024 Cohort:
+ Opening MRR (Feb 2024): $45,000
+ MRR at Feb 2025: $38,000
+ 12-month NRR: 84% ← problem cohort
+```
+
+Cohort analysis reveals:
+- Whether a specific acquisition channel brings lower-quality customers
+- Whether a product change or pricing shift affected retention
+- Whether specific sales reps or time periods created bad-fit deals
+
+---
+
+## Churn Anatomy
+
+Not all churn is equal. Know the breakdown before prescribing solutions.
+
+### Churn Types
+
+| Type | Definition | Primary Cause | Fix |
+|------|-----------|--------------|-----|
+| **Logo churn** | Customer cancels entirely | No value, poor fit, champion left, competitor | Root cause analysis, ICP tightening |
+| **Revenue churn** | ARR lost (cancels + downgrades combined) | Same as logo + downgrade triggers | Address both volume and revenue |
+| **Involuntary churn** | Failed payment, expired card | Billing friction | Dunning improvement (quick win: 20-30% recovery) |
+| **Voluntary churn** | Active cancellation decision | Explicit dissatisfaction, competitor win | Exit interview + intervention program |
+| **Contraction** | Downgrade, seat reduction | Overpurchased, budget cut, team reduction | Right-sizing program, annual contracts |
+
+### Churn Root Cause Framework
+
+Run this analysis quarterly on all churned accounts:
+
+**Step 1: Categorize by reason**
+- No value realized (never activated or adopted)
+- Value realized but budget cut (external, not product)
+- Switched to competitor (why? what did they offer?)
+- Champion left company (relationship loss, not product failure)
+- Company shutdown / acquisition (unavoidable)
+
+**Step 2: Look for patterns**
+- Which ICP signals predict churn? (company size, vertical, acquisition channel)
+- Which product behaviors predict churn? (no login in 30 days, never completed onboarding)
+- Which time periods have highest churn? (months 3, 6, 12 are typical cliff points)
+
+**Step 3: Act on the patterns**
+- ICP pattern → tighten qualification criteria
+- Behavior pattern → build early warning health score
+- Time cliff → build intervention playbooks for months 2, 5, 11
+
+### Exit Interview Protocol
+
+Talk to every churned customer if ACV > $10K. For smaller, do quarterly batch surveys.
+
+Questions:
+1. "What was the primary reason for your decision to cancel?"
+2. "What would have needed to be true for you to stay?"
+3. "What did you switch to, and what drove that decision?"
+4. "Was there a specific moment when you decided to leave?"
+
+Rules:
+- CSM who owned the account should NOT conduct the exit interview (too much relationship bias)
+- Use a neutral party or the VP CS
+- Document verbatim, not paraphrased
+- Feed patterns back to Product and Sales monthly
+
+---
+
+## Customer Health Scoring
+
+A health score predicts churn 60-90 days before it happens. Without one, you're reactive.
+
+### Health Score Components
+
+Score each account 0-100 across weighted signals:
+
+| Signal | Weight | Red (0-33) | Yellow (34-66) | Green (67-100) |
+|--------|--------|-----------|---------------|---------------|
+| **Product usage** (DAU/WAU, feature adoption depth) | 35% | < 20% seats active | 20-60% seats active | > 60% seats active |
+| **Engagement** (QBR attendance, champion responsiveness) | 20% | No response 60+ days | 30-60 days | Active, < 30 days |
+| **NPS / CSAT** | 20% | Score < 6 | Score 6-7 | Score 8-10 |
+| **Support volume** (negative signal: high volume = friction) | 15% | > 10 tickets/month | 3-10/month | < 3/month |
+| **Contract signals** (time to renewal, expansion in motion) | 10% | < 60 days to renewal, no expansion discussion | 60-90 days, passive | > 90 days, expansion active |
+
+**Composite score:**
+- 70-100: Healthy. Renewal confident. Identify expansion opportunity.
+- 50-69: At-risk. CSM check-in required. Executive sponsor loop-in if < 60 days to renewal.
+- 0-49: Red alert. Immediate intervention. VP CS or CEO call if strategic account.
+
+### Health Score Automation
+
+Trigger alerts automatically:
+```
+Score drops > 20 points in 30 days → CSM immediate outreach (same day)
+No product login in 14 days → Automated email + CSM flag (within 24 hours)
+Champion leaves company → Executive outreach (within 24 hours)
+Support escalation → CSM loop-in (within 2 hours)
+Renewal < 90 days + score < 60 → VP CS review (weekly)
+Seat utilization < 30% → Adoption intervention playbook triggered
+```
+
+### Leading Indicators vs. Lagging Indicators
+
+| Leading (predict future churn) | Lagging (confirm past churn) |
+|-------------------------------|------------------------------|
+| Login frequency declining | Cancellation submitted |
+| Feature adoption stalling at basic level | Non-renewal at contract end |
+| NPS score trend (not just snapshot) | Downgrade executed |
+| No QBR scheduled in 90+ days | Champion departure |
+| Support escalations increasing | Competitor mentioned in support |
+
+Build your health score from leading indicators. Lagging indicators tell you what already happened.
+
+---
+
+## Expansion Revenue Strategies
+
+Expansion is cheaper than acquisition. CAC for expansion is typically 20-30% of new logo CAC.
+
+### Expansion Motion 1: Seat Expansion
+
+**Trigger signals:**
+- Usage by unlicensed users (shared logins, "can you add my colleague?")
+- Team growth visible on LinkedIn (company hiring in target department)
+- Champion promotes to a new role with bigger team
+- Power users at license limit consistently
+
+**Playbook:**
+1. Pull monthly usage report showing which features unlicensed users are using
+2. Frame as: "Your team is getting value from X — you could be capturing that for the full team"
+3. Offer a team expansion proposal at renewal + 10% volume discount for seat adds
+4. Never penalize users for sharing logins before the conversation — that's a data asset
+
+### Expansion Motion 2: Upsell (Tier Upgrade)
+
+**Trigger signals:**
+- Customer consistently hitting usage/feature limits
+- Security or compliance requirement that requires higher tier
+- New stakeholder joining who needs admin controls
+- API usage growing rapidly (engineering team engagement)
+
+**Playbook:**
+1. Build a "value realized" report before the upsell conversation (ROI proof)
+2. Use QBR as the venue: "You've achieved X. Here's what's possible at the next level."
+3. Frame the upgrade as unlocking more of what's already working
+4. Time to renewal: start upsell conversation 90-120 days before renewal
+
+### Expansion Motion 3: Cross-sell
+
+**Trigger signals:**
+- Strategic account with adjacent problem your product can solve
+- New product launch that complements existing usage
+- Customer explicitly asks about a capability in your roadmap or adjacent product
+
+**Playbook:**
+1. Land with core product; build relationship and prove value
+2. Cross-sell only after health score is green and NPS > 7
+3. Introduce the new product through a champion, not a cold pitch
+4. Pilot pricing: bundle into renewal at modest uplift vs. separate sale
+5. Cross-sell owner: CSM or AE (define explicitly — joint ownership = no ownership)
+
+### Expansion Sequencing
+
+Don't try all three simultaneously. Sequence matters:
+
+```
+Month 0-3: Activation focus — ensure core value delivered
+Month 3-6: Seat expansion — grow usage within existing team
+Month 6-9: Upsell conversation — unlock advanced features
+Month 9-12: Cross-sell OR renewal + multi-year lock-in
+```
+
+### NRR Modeling
+
+Target breakdown for 115% NRR:
+
+```
+GRR: 88% (12% lost to churn/contraction)
+Expansion rate: 27% (upsell + cross-sell + seat expansion)
+NRR: 88% + 27% = 115%
+
+To reach 120% NRR:
+ Option A: Improve GRR to 92% (reduce churn), keep expansion at 28%
+ Option B: Keep GRR at 88%, improve expansion to 32%
+ Option C: Both, incrementally
+
+Option A is usually easier and more durable. Fix the hole first.
+```
+
+---
+
+## Customer Success Integration
+
+CS and Revenue are not separate functions. NRR lives at their intersection.
+
+### CS Team Structure (aligned to NRR)
+
+| CS Model | When to Use | NRR Focus |
+|----------|------------|-----------|
+| **High-touch CSM** | ACV > $25K | Named accounts, QBRs, executive relationships |
+| **Tech-touch / pooled** | ACV $5K-25K | Automated health scoring, office hours, community |
+| **Self-serve** | ACV < $5K | In-app guidance, knowledge base, email sequences |
+
+**CSM coverage ratios:**
+- High-touch: 1 CSM per $2M-4M ARR managed
+- Tech-touch: 1 CSM per $5M-10M ARR managed
+- Self-serve: Product and automation (no dedicated CSM)
+
+### CS Compensation (aligned to NRR)
+
+Don't pay CSMs a flat salary — align incentive to retention and expansion:
+
+```
+CS compensation structure:
+ Base: 70% of OTE
+ Variable: 30% of OTE
+
+Variable tied to:
+ GRR / NRR vs. target (50% of variable)
+ Health score improvement (25% of variable)
+ Expansion ARR facilitated (25% of variable)
+
+Do NOT pay CS commission on expansion ARR the same way AEs earn it.
+This creates conflict: CS will push expansion before the customer is ready.
+Instead, bonus for expansion milestones — it's a different incentive structure.
+```
+
+### QBR (Quarterly Business Review) Framework
+
+QBRs are the primary vehicle for expansion and churn prevention in enterprise accounts.
+
+**QBR agenda (60-90 minutes):**
+1. **Their goals, our progress** — review what they said success looked like at kickoff (10 min)
+2. **Usage and adoption data** — product metrics presented in business language, not feature language (15 min)
+3. **Value delivered** — ROI proof: time saved, revenue influenced, risk reduced (10 min)
+4. **Challenges and blockers** — what's preventing more adoption? (10 min)
+5. **Roadmap preview** — upcoming features relevant to their use case (10 min)
+6. **Next 90 days** — joint success plan with owner and due dates (10 min)
+7. **Expansion opportunity** — if health score is green and timing is right (10 min)
+
+**QBR anti-patterns:**
+- Leading with your product roadmap (they don't care; start with their results)
+- Bringing too many people from your side without matching seniority
+- Presenting at a VP without bringing the economic buyer
+- Skipping QBRs for "healthy" accounts (health can change fast)
+- No confirmed next step at the end
+
+---
+
+## Cohort-Based Retention Analysis
+
+Aggregate NRR hides the signal. Cohort analysis reveals it.
+
+### Retention Curve Analysis
+
+Plot retention by months since acquisition for each quarterly cohort:
+
+```
+Month 0: 100% (starting revenue)
+Month 3: First cliff — early adopters who didn't activate churn here
+Month 6: Second cliff — customers who never expanded, running out of runway
+Month 12: Renewal cliff — annual contract renewal decision
+Month 18: Mature customers — churn rate stabilizes significantly
+
+Healthy curve: Drops sharply in months 1-3, flattens after month 6
+Problem curve: Continues declining linearly through month 12+ (no value anchor)
+```
+
+### Reading Cohort Data
+
+| Pattern | Interpretation | Action |
+|---------|---------------|--------|
+| Early churn (months 1-3) | Onboarding / activation failure | Fix time-to-value, improve onboarding |
+| Mid-cycle churn (months 4-8) | Value not deepening | Adoption program, check product fit |
+| Annual renewal churn (month 12) | Buying committee didn't renew | Executive engagement, earlier renewal process |
+| Flat after month 6 | Sticky product, low expansion | Increase upsell motion |
+| Growing after month 6 | Expansion working | Scale the upsell playbook |
+
+### Cohort Segmentation Variables
+
+Slice retention cohorts by:
+- **Acquisition channel** (inbound vs. outbound vs. PLG vs. partner)
+- **Sales rep** (which reps close durable deals vs. churny deals)
+- **Deal size** (SMB churn rate typically 2-3x enterprise)
+- **Industry vertical** (some verticals have structurally higher churn)
+- **Product tier at signup** (self-serve → converted vs. directly contracted)
+- **Geographic market** (international markets often have different retention profiles)
+
+The most actionable finding is usually by acquisition channel or sales rep — both are directly controllable.
+
+### Churn Prevention Intervention Playbooks
+
+**Playbook 1: Low Activation (no login in first 14 days)**
+```
+Day 7: Automated email: "Getting started" + specific next step
+Day 14: CSM outreach: "I noticed you haven't logged in — can I help?"
+Day 21: Escalate to CSM manager if no response
+Day 30: Executive outreach for ACV > $25K; flag as at-risk
+```
+
+**Playbook 2: Usage Cliff (DAU drops > 50% in 30 days)**
+```
+Trigger: Automated health score alert
+Day 1: CSM reviews usage report, identifies likely cause
+Day 2: CSM outreach: "We noticed your team's usage changed — is everything okay?"
+Day 7: If no response: schedule 30-min call with champion
+Day 14: If unresponsive: VP CS loop-in + executive reach out
+```
+
+**Playbook 3: Champion Departure**
+```
+Trigger: LinkedIn alert or internal report of champion leaving
+Day 1: Email to departed champion (warm handoff ask)
+Day 1: Email to new stakeholder (introduction from AE or VP CS)
+Day 3: Schedule onboarding call for new stakeholder
+Day 14: QBR with new stakeholder to establish relationship
+Day 30: Health score review — flag if engagement hasn't recovered
+```
+
+**Playbook 4: Pre-Renewal (90 days out, health score < 70)**
+```
+Day -90: CSM completes account health review, escalates if < 70
+Day -75: Executive sponsor from vendor side joins renewal call
+Day -60: Value delivered report prepared (ROI proof)
+Day -45: Renewal proposal sent with expansion option
+Day -30: Follow-up on any open objections or requirements
+Day -14: Final confirm or escalate to VP Sales
+```
diff --git a/skills/c-level-advisor/cro-advisor/references/pricing_strategy.md b/skills/c-level-advisor/cro-advisor/references/pricing_strategy.md
new file mode 100644
index 00000000..5c12b2b3
--- /dev/null
+++ b/skills/c-level-advisor/cro-advisor/references/pricing_strategy.md
@@ -0,0 +1,417 @@
+# Pricing Strategy
+
+Pricing is not a one-time decision. It's an ongoing hypothesis about value and willingness to pay. Most SaaS companies are underpriced by 20-40%.
+
+---
+
+## Pricing Models
+
+### Per Seat / User
+
+**How it works:** Customer pays a fixed amount per user, per month or year.
+
+**Best for:**
+- Collaboration tools (everyone who uses it needs a license)
+- Productivity software where value scales with users
+- Products where you want viral / network growth within accounts
+
+**Pricing structure:**
+```
+Starter: $15/user/month (1-10 users)
+Professional: $30/user/month (11-100 users)
+Enterprise: Custom (100+ users, negotiated)
+```
+
+**Pros:**
+- Simple to understand and sell
+- Revenue scales naturally with customer growth
+- Predictable for customers (fixed monthly cost)
+
+**Cons:**
+- Customers negotiate volume discounts aggressively
+- Discourages broad adoption if price is high (seat hoarding)
+- Doesn't capture value for power users vs. light users
+- Enterprises can negotiate $5/seat on a $25 product
+
+**Watch for:** Customers sharing logins to avoid per-seat cost. Enforce with IP restrictions or SSO audit logs.
+
+---
+
+### Usage-Based Pricing (UBP)
+
+**How it works:** Customer pays for what they consume — API calls, data processed, messages sent, compute hours, etc.
+
+**Best for:**
+- API companies, infrastructure, data platforms
+- AI products (per-token, per-query pricing)
+- Products where value scales non-linearly with usage
+- Land-and-expand: low entry cost, grows with customer success
+
+**Pricing structure:**
+```
+Free tier: First 10K API calls/month
+Pay-as-you-go: $0.002 per API call
+Committed use: $500/month for 500K calls (better rate)
+Enterprise: Custom contract, committed volume discount
+```
+
+**Pros:**
+- Customer pays in proportion to value received
+- Low barrier to entry (customers start small, scale up)
+- Natural expansion: customer success = revenue growth
+- No "unused licenses" problem
+
+**Cons:**
+- Revenue is unpredictable for both you and the customer
+- Hard to forecast; hard to budget for customer
+- Customers may optimize to reduce usage (and your revenue)
+- Complex billing; requires robust usage tracking infrastructure
+
+**Usage-based pricing math:**
+```
+Unit cost (your COGS per unit): $0.0002 per API call
+Target gross margin: 80%
+Price = COGS / (1 - margin) = $0.0002 / 0.20 = $0.001 minimum
+
+Add markup for value delivered above cost: $0.002 per call (10x markup at scale)
+```
+
+**Hybrid usage + seat approach:**
+- Platform fee: $500/month (access, support, base features)
+- Usage fee: $0.001 per API call above included 100K
+
+---
+
+### Flat Rate / Subscription
+
+**How it works:** One price for full access, regardless of usage or users.
+
+**Best for:**
+- Simple products with limited feature differentiation
+- Products where usage is predictable and bounded
+- Customers who want budget certainty
+- Early stage before you've figured out value segmentation
+
+**Pros:**
+- Simplest to sell and explain
+- Easiest billing implementation
+- Customers love budget predictability
+
+**Cons:**
+- Leaves money on the table for heavy users
+- No natural expansion revenue mechanism
+- Light users pay the same as power users (retention risk)
+
+**When to move away from flat rate:**
+- 20% of customers are using 80% of the product capacity
+- Power users would clearly pay more; light users churn or underutilize
+- You have a clear expansion story waiting to happen
+
+---
+
+### Tiered / Feature-Based
+
+**How it works:** Multiple packages (Starter, Pro, Enterprise) with different feature sets and/or usage limits.
+
+**Best for:**
+- Multi-use-case products
+- Different buyer types (individual vs. team vs. enterprise)
+- Products with a natural upgrade path based on sophistication
+
+**Structure (Good / Better / Best):**
+```
+Starter ($49/mo): Core features, 3 users, 10GB storage
+Professional ($149/mo): Advanced features, 25 users, 100GB, API access
+Business ($499/mo): All features, 100 users, 1TB, SSO, priority support
+Enterprise (custom): Unlimited, custom integrations, SLA, dedicated CSM
+```
+
+**Tier design principles:**
+- Starter tier: removes friction, proves value, not the revenue center
+- Professional: the primary revenue tier; 60-70% of customers land here
+- Enterprise: custom pricing allows you to capture maximum value
+- Each tier upgrade should have an obvious "must-have" feature for the target buyer
+
+**What to gate on each tier:**
+| Feature Type | Where to Put It |
+|-------------|----------------|
+| Core product functionality | Starter (must be useful) |
+| Collaboration features | Pro (drives team usage) |
+| Admin, security, SSO | Business/Enterprise |
+| API / integrations | Pro and above |
+| SLAs, dedicated support | Enterprise only |
+| Advanced analytics | Business/Enterprise |
+
+---
+
+### Hybrid Pricing
+
+**How it works:** Combination of models (e.g., platform fee + per seat + usage).
+
+**Example:**
+```
+Platform fee: $2,000/month (access, core features, admin console)
+Per seat: $50/user/month (up to 200 users)
+Usage overage: $0.10/action above 100K included actions
+```
+
+**When to use hybrid:**
+- Enterprise customers want budget certainty (platform fee) but your value scales with usage
+- You have different cost structures for different features
+- Customers have very different usage patterns across the base
+
+**Pros:** Captures value at multiple dimensions. Hybrid is most common in enterprise SaaS.
+**Cons:** More complex to explain and bill. Sales training burden increases.
+
+---
+
+## Value-Based Pricing Methodology
+
+Cost-plus pricing is a race to the bottom. Price on value, not cost.
+
+### Step 1: Define the Economic Outcome
+
+What business result does your product deliver? Be specific.
+
+**Weak:** "We help companies save time"
+**Strong:** "We reduce onboarding time for new enterprise software by 40%, saving 8 hours per employee"
+
+Map to one of:
+- **Revenue increase** — "Our customers close 25% more deals using our CRM intelligence"
+- **Cost reduction** — "We eliminate 60% of manual data entry for finance teams"
+- **Risk reduction** — "We reduce compliance violations by 90%, avoiding $500K+ in potential fines"
+- **Time savings** — "CSMs spend 5 fewer hours per week on manual reporting"
+
+### Step 2: Quantify Per Customer
+
+Calculate the dollar value of the outcome for your average customer.
+
+```
+Example: Data entry automation product
+ Target customer: 50-person finance team
+ Manual data entry: 4 hours/person/week
+ Hours saved with product: 2.4 hours/person/week (60% reduction)
+ Fully loaded cost of finance analyst: $75/hour
+
+ Weekly savings: 50 employees × 2.4 hours × $75 = $9,000
+ Annual savings: $9,000 × 52 weeks = $468,000
+```
+
+### Step 3: Determine Willingness to Pay
+
+Customers will typically pay 10-20% of the value delivered for software.
+
+```
+Annual value delivered: $468,000
+Willingness to pay range: $46,800 - $93,600/year
+Current market pricing: ~$60,000/year
+
+Your pricing: $72,000/year (between median and upper WTP)
+```
+
+**Test your hypothesis:**
+- Interview 5-10 customers: "If we charged $X/year, is that reasonable?"
+- Van Westendorp Price Sensitivity Meter:
+ - "At what price is this too cheap to trust?"
+ - "At what price is this a good deal?"
+ - "At what price is this getting expensive but still worth it?"
+ - "At what price is this too expensive?"
+
+### Step 4: Validate with Win Rate Analysis
+
+```
+Run this analysis quarterly:
+ Track win rate by price point (segmented if possible)
+ Win rate 30-40%: pricing is likely right
+ Win rate < 20%: price is too high OR value demonstration is broken
+ Win rate > 50%: you're underpriced
+
+Note: Distinguish between "lost on price" and "lost on fit."
+ Lost on price + good ROI proof: test lower price or improve value story
+ Lost on fit: ICP problem, not pricing problem
+```
+
+---
+
+## Packaging (Good / Better / Best)
+
+### The Three-Package Framework
+
+Packaging is not just about features. It's about serving different buyer personas with different budgets and needs.
+
+**Buyer personas by tier:**
+```
+Starter → The individual contributor or small team trying to solve an immediate problem
+ - Low budget authority
+ - Low-friction purchase (credit card, self-serve)
+ - Needs quick time to value
+
+Professional → The team manager or department head
+ - $10K-100K budget authority
+ - Works with inside sales
+ - Needs collaboration features and reporting
+
+Enterprise → The VP or C-suite buyer
+ - Unlimited budget (but requires justification)
+ - Needs compliance, security, SLAs, dedicated support
+ - Long buying process, multiple stakeholders
+```
+
+### Packaging Design Rules
+
+1. **Each tier must be useful on its own.** Starter can't be crippled—customers need to succeed.
+2. **Upgrade triggers must be obvious.** When a customer hits a limit, the next tier should solve it clearly.
+3. **Don't gate features that drive adoption.** Collaboration features gated in a low tier kill viral growth.
+4. **Enterprise pricing is custom.** Show "Contact Sales" or a starting price. Don't publish a firm enterprise price—you'll anchor too low.
+5. **Annual vs. monthly pricing:** Charge 15-25% more for monthly vs. annual. Incentivize annual prepay.
+
+### Pricing Page Design
+
+- Lead with the most popular tier (visually prominent)
+- Show annual pricing by default (with toggle to monthly)
+- Highlight one or two "recommended" plans
+- Feature comparison table: minimize the number of rows (overwhelm = no decision)
+- Show logos of customers on each tier (social proof by segment)
+- Live chat for enterprise CTA, not "Contact Sales" form
+
+---
+
+## Pricing Experiments and Rollout
+
+### Before You Change Pricing
+
+**Internal checklist:**
+- [ ] Validate new pricing with 5-10 current customers (interviews)
+- [ ] Run a willingness-to-pay survey with 50+ prospects
+- [ ] Model revenue impact: how many customers at new pricing are equivalent to current ARR?
+- [ ] Get CFO sign-off on cash flow impact
+- [ ] Prepare messaging for customers, website, sales team
+- [ ] Set a rollout date 60-90 days out
+
+### Testing Approaches
+
+**Cohort testing (safest):**
+- New signups see new pricing; existing customers are grandfathered
+- Monitor: conversion rate, ACV, win rate, time-to-close
+- Run for 90 days before full rollout
+
+**A/B pricing test (higher stakes):**
+- Half of new signups see price A, half see price B
+- Risk: word gets out that prices differ (customer frustration)
+- Use only on self-serve, where purchase is not sales-assisted
+
+**Segment-specific rollout:**
+- Change pricing in one segment (e.g., SMB) while holding enterprise steady
+- Lower risk than full rollout; validate before expanding
+
+### Pricing Rollout Plan
+
+```
+Day 0: Decision made, pricing document approved
+Day -60: Internal communication to sales, CS, support
+Day -45: Customer communication drafted and reviewed
+Day -30: New pricing live on website for new customers
+Day -30: Existing customer email sent (90-day grandfather period)
+Day -30: Sales team trained, FAQ document ready
+Day -14: Second reminder to existing customers
+Day 0: Existing customers transition to new pricing
+Day +30: Win rate analysis, NRR impact review
+```
+
+### Grandfathering Policy
+
+- **Standard:** Grandfather existing customers at old price for 12 months
+- **Aggressive:** 90 days grandfather, then new pricing applies (use if you're raising significantly)
+- **Never:** Retroactive pricing changes with no notice. This is a churn trigger and brand damage.
+
+Grandfathering message framing:
+> "We're investing significantly in [feature areas]. As a valued customer, your pricing remains unchanged through [date]. After that, your new rate will be $X — still X% less than new customer pricing as a thank-you for your partnership."
+
+---
+
+## Competitive Pricing Analysis
+
+### Mapping the Competitive Landscape
+
+```
+Step 1: List all direct competitors
+Step 2: Find their public pricing (website, G2, Capterra)
+Step 3: Secret shop their sales process for unpublished pricing
+Step 4: Talk to customers who considered them ("What did they quote you?")
+Step 5: Map to your packaging (apples-to-apples comparison)
+
+Output: Competitive pricing matrix
+ You: $X/month per seat at Pro tier
+ Competitor A: $Y/month per seat at equivalent tier
+ Competitor B: Custom (enterprise only)
+```
+
+### Competitive Positioning by Price
+
+| Your Position | Situation | Response |
+|--------------|-----------|---------|
+| Significantly cheaper | Unclear why | Raise prices or clarify differentiation |
+| Slightly cheaper | Winning on price | Test raising price, monitor win rate |
+| At market | Competing on features | Make sure differentiation is clear in sales |
+| Slightly more expensive | Win rate healthy | Price is justified by value |
+| Significantly more expensive | Win rate low | Improve value proof or re-examine ICP |
+
+### When "They're Cheaper" Appears in Deals
+
+**Coach your reps:**
+1. "What makes [Competitor] worth choosing over the $X difference?" (reframe value, not price)
+2. "If price were equal, which would you choose and why?" (understand true preference)
+3. "What's the cost of not solving this problem in Q3?" (urgency + value)
+4. "What's their implementation cost and time?" (TCO, not ACV)
+
+**If price is truly the barrier:**
+- Offer a pilot at reduced scope (not price) to prove value
+- Multi-year deal with year-one discount
+- Defer payment to match their budget cycle (start in Q4, bill in Q1)
+- Confirm it's price and not a champion issue or lack of urgency
+
+---
+
+## When to Raise Prices
+
+### Green Lights for a Price Increase
+
+**Product signals:**
+- Customer usage growing QoQ (product delivers real value)
+- NPS consistently > 40
+- Feature requests indicate you're solving critical workflows
+- Customers measuring and can articulate ROI
+
+**Market signals:**
+- Win rate > 35% (strong signal of underpricing)
+- Waitlist or high inbound conversion without price objections
+- Competitors raising prices (market is moving up)
+- You've added significant value (new features, integrations, uptime improvements)
+
+**Business signals:**
+- Gross margin below 70% (cost inflation requires pricing response)
+- CAC payback > 24 months (need higher ACV to fix unit economics)
+- Haven't raised prices in 2+ years (inflation alone justifies adjustment)
+
+### How Much to Raise
+
+**Conservative:** 10-15% increase. Low risk, low disruption.
+**Standard:** 15-30% increase. Acceptable if value story is strong.
+**Aggressive:** 30-50% increase. Only with major product investment or clear underprice.
+**Repositioning:** 2-5x increase. Rare; requires moving to a new buyer persona.
+
+**Rule:** If fewer than 20% of prospects mention price as a concern, you're underpriced. Test.
+
+### Price Increase Execution
+
+1. Raise new business pricing immediately on the website
+2. Communicate to existing customers with 90 days notice
+3. Grandfather for 12 months OR give a 10-15% loyalty discount on new price
+4. Track: conversion rate (new business), churn rate (existing), expansion ARR impact
+5. Monitor win rate for 60 days post-increase; adjust if win rate drops > 5 points
+
+**What not to do:**
+- Don't apologize for raising prices
+- Don't over-explain the justification (confident framing wins)
+- Don't let sales reps negotiate discounts back to old pricing "just this once"
+- Don't raise prices and remove features simultaneously
diff --git a/skills/c-level-advisor/cro-advisor/references/sales_playbook.md b/skills/c-level-advisor/cro-advisor/references/sales_playbook.md
new file mode 100644
index 00000000..769a1428
--- /dev/null
+++ b/skills/c-level-advisor/cro-advisor/references/sales_playbook.md
@@ -0,0 +1,461 @@
+# Sales Playbook
+
+Frameworks for building, running, and scaling a B2B SaaS sales organization.
+
+---
+
+## Sales Process Design
+
+A sales process is a repeatable series of steps that takes a prospect from first contact to closed revenue. Without it, you have individual heroics, not a scalable machine.
+
+### The Core Funnel
+
+```
+Lead Generation → Qualification → Discovery → Demo → Trial / POC → Proposal → Negotiation → Close → Handoff
+```
+
+Each stage has a clear entry criterion, exit criterion, and owner.
+
+### Stage Definitions
+
+#### Stage 0: Lead / Suspect
+- **Entry:** Contact exists in CRM with basic firmographic data
+- **Owner:** Marketing or SDR
+- **Exit criterion:** Meets ICP criteria (company size, industry, tech stack)
+- **Action:** Research, prioritize, add to outbound sequence
+
+#### Stage 1: Prospecting / Outreach
+- **Entry:** ICP-qualified account, no contact yet
+- **Owner:** SDR or AE (depending on model)
+- **Exit criterion:** Meeting booked with a qualified contact
+- **Action:** Multi-channel outreach (email + call + LinkedIn), 8-12 touch sequence
+- **Key metric:** Meeting booked rate (benchmark: 2-5% of outbound contacts)
+
+#### Stage 2: Discovery
+- **Entry:** First meeting confirmed
+- **Owner:** AE (SDR hands off or joins)
+- **Exit criterion:** Confirmed: pain, budget range, decision process, timeline
+- **Action:** Ask questions. Listen. Map the org. Don't pitch yet.
+- **Key metric:** Discovery-to-demo rate (benchmark: 60-80% proceed)
+
+**Discovery question framework:**
+```
+Situation: "How do you currently handle [problem area]?"
+Problem: "What's the impact when [pain point] happens?"
+Implication: "If this continues, what does that mean for [business goal]?"
+Need-payoff: "If we solved this, what would that be worth to you?"
+```
+
+#### Stage 3: Demo / Solution Presentation
+- **Entry:** Confirmed pain and fit from discovery
+- **Owner:** AE (+ SE for complex products)
+- **Exit criterion:** Prospect agrees to evaluate / trial; next step defined
+- **Action:** Show the workflow that solves their specific pain (not a feature tour)
+- **Key metric:** Demo-to-trial/proposal rate (benchmark: 40-60%)
+
+**Demo structure:**
+1. Recap their pain (show you listened) — 5 min
+2. Show the "aha moment" (fastest path to value) — 10 min
+3. Walk the specific workflow they described — 15 min
+4. Handle objections, confirm fit — 5 min
+5. Define clear next step (date, owners, criteria) — 5 min
+
+Never show features they didn't ask for. Every additional feature is noise until they have a reason to care.
+
+#### Stage 4: Trial / POC
+- **Entry:** Prospect commits to evaluate with real data/use case
+- **Owner:** AE + CSM or SE
+- **Exit criterion:** Success criteria met, POC success confirmed
+- **Action:** Define success criteria upfront (in writing). Set a tight timeframe (2-4 weeks max).
+- **Key metric:** POC-to-proposal rate (benchmark: 50-70%)
+
+**POC setup requirements:**
+```
+Before any POC:
+ □ Signed NDA
+ □ Written success criteria ("We'll move forward if X happens")
+ □ Named champion who owns the evaluation
+ □ Executive sponsor identified
+ □ Defined timeline with end date
+ □ Agreed next step if criteria are met
+```
+
+If you can't get written success criteria, you don't have a real opportunity. You have a "we'll see."
+
+#### Stage 5: Proposal / Pricing
+- **Entry:** POC success OR strong discovery fit for simple products
+- **Owner:** AE
+- **Exit criterion:** Proposal received, timeline to decision confirmed
+- **Action:** Present in a live call, never email a proposal cold
+- **Key metric:** Proposal-to-negotiation rate (benchmark: 50-75%)
+
+**Proposal structure:**
+1. Problem statement (their words, not yours)
+2. Proposed solution (mapped to their workflow)
+3. ROI summary (value delivered vs. investment)
+4. Pricing options (give 2-3 options; anchors the decision)
+5. Next steps with dates
+
+#### Stage 6: Negotiation
+- **Entry:** Verbal intent to proceed, price/terms discussion begins
+- **Owner:** AE (+ VP Sales for large deals)
+- **Exit criterion:** Mutual agreement on terms; contract sent
+- **Action:** Never discount before they ask. Discount on scope, not on margin.
+- **Key metric:** Negotiation win rate (benchmark: 70-85%)
+
+**Negotiation principles:**
+- Get something for everything you give. Discount → multi-year. Fast close → early pay discount.
+- Don't negotiate against yourself. Silence after an offer is not rejection.
+- Know your walk-away before you enter. If you don't have a BATNA, you have no leverage.
+- Legal/procurement delay ≠ deal death. Keep the champion engaged.
+
+#### Stage 7: Close
+- **Entry:** Signed contract or PO received
+- **Owner:** AE
+- **Exit criterion:** Contract countersigned, kickoff date set
+- **Action:** Celebrate with the customer. Immediately introduce CSM.
+- **Key metric:** Average close rate (closed won ÷ all closed = won + lost)
+
+#### Stage 8: Handoff to Customer Success
+- **Entry:** Deal closed
+- **Owner:** AE + CSM
+- **Exit criterion:** Customer has met their assigned CSM, kickoff scheduled
+- **Action:** Internal handoff call with AE + CSM. AE shares: deal context, key stakeholders, use case, success criteria, any promises made during the sale.
+
+**Handoff document (AE fills before first CS meeting):**
+```
+Account: [name]
+ACV: $X
+Close date: [date]
+Primary contact: [name, title, email]
+Economic buyer: [name, title]
+Use case: [specific workflow]
+Success criteria: [what they said good looks like in 90 days]
+Promises made: [anything specific committed during sale]
+Risk flags: [competitive, budget, champion strength]
+```
+
+---
+
+## MEDDPICC Qualification Framework
+
+MEDDPICC is the enterprise qualification standard. If you can't answer every letter, you don't have a qualified opportunity — you have a conversation.
+
+### M — Metrics
+What is the quantified business impact? What does winning look like in numbers?
+
+- "What's the current cost of [the problem]?"
+- "How do you measure success in this area today?"
+- "If we achieve X outcome, what does that save or earn you?"
+
+**Red flag:** No metrics = no business case = hard to get budget.
+
+### E — Economic Buyer
+Who has final authority to approve the budget?
+
+- "Who else will be involved in the final decision?"
+- "Have you purchased solutions in this range before? Who approved that?"
+- "When we get to final terms, who needs to sign?"
+
+**Red flag:** You only know the user buyer. Economic buyer hasn't engaged.
+
+### D — Decision Criteria
+What factors will they use to evaluate and select a solution?
+
+- "What's most important in your evaluation?"
+- "How will you compare options?"
+- "What does the ideal solution look like to you?"
+
+**Why it matters:** If you don't know their criteria, you're guessing what to prove. Define the criteria before you compete on them.
+
+### D — Decision Process
+What are the steps from evaluation to signed contract?
+
+- "Walk me through your process from here to signed agreement."
+- "Does procurement get involved? Legal? InfoSec?"
+- "Have you purchased software at this price before? How long did that take?"
+
+**Red flag:** No defined process = unlimited sales cycle.
+
+### P — Paper Process
+What's the contract and legal process?
+
+- "Who manages vendor contracts on your side?"
+- "What's your standard MSA, or do you use ours?"
+- "How long does legal review typically take?"
+
+**Why it matters:** Legal and procurement have killed many "done" deals. Start early. Route to your legal team simultaneously.
+
+### I — Identify Pain
+What is the specific, felt pain driving this evaluation?
+
+- "What triggered this initiative now vs. six months ago?"
+- "What happens if you don't solve this in Q3?"
+- "On a scale of 1-10, how urgent is this for your team?"
+
+**Red flag:** Pain isn't felt by the economic buyer. User pain ≠ budget authority.
+
+### C — Champion
+Who will actively sell your solution internally when you're not in the room?
+
+- "Who else have you brought into this evaluation?"
+- "Can you help us get access to [economic buyer / IT / security]?"
+- "If the decision went the wrong way, who would be disappointed?"
+
+**Red flag:** Your champion is enthusiastic but has no internal influence.
+
+### C — Competition
+Who else are they evaluating? What's your position?
+
+- "Are you looking at alternatives?"
+- "What made you start with us?"
+- "Have you used [Competitor X] before?"
+
+**Why it matters:** Knowing the competitive field tells you what you need to prove and what to neutralize.
+
+### MEDDPICC Scorecard
+
+| Letter | Score 1 | Score 2 | Score 3 |
+|--------|---------|---------|---------|
+| Metrics | No numbers | Approximate value | Specific ROI model |
+| Economic Buyer | Unknown | Named, not engaged | Engaged directly |
+| Decision Criteria | Vague | Partially defined | Written, weighted |
+| Decision Process | Unknown | Verbal description | Steps confirmed, timeline known |
+| Paper Process | Unknown | Basic awareness | Legal contacts, standard process known |
+| Identify Pain | No urgency | User-level pain | Executive-level pain with consequences |
+| Champion | No advocate | Friendly contact | Actively selling internally |
+| Competition | Unknown | Identified | Position mapped, differentiation clear |
+
+**Score each 1-3. Total 16+/24 = qualified opportunity. Under 12 = unqualified, do not forecast.**
+
+---
+
+## Sales Compensation Plans
+
+Comp drives behavior. Design it precisely.
+
+### Base / Variable Split
+
+| Role | Base % | Variable % | Rationale |
+|------|--------|-----------|-----------|
+| SDR | 60-70% | 30-40% | Activity-based, not purely revenue |
+| AE (Inside Sales) | 50% | 50% | Balanced risk/reward |
+| AE (Enterprise) | 55-60% | 40-45% | Longer cycle, higher base for stability |
+| VP Sales | 50% | 50% | Accountable for team results |
+| CSM (retention focus) | 70% | 30% | Less variable, stable relationship role |
+| CSM (expansion focus) | 60% | 40% | Expansion quota adds variable |
+
+### Commission Structure
+
+**Standard AE plan:**
+```
+Base: $80K
+Variable: $80K (at 100% quota attainment)
+OTE: $160K
+
+Commission rate: OTE variable ÷ Quota
+ If quota = $800K ARR: commission = $80K ÷ $800K = 10% of ARR closed
+
+Accelerators (performance above quota):
+ 101-125% quota: 1.25x commission rate (12.5% of ARR)
+ 126-150% quota: 1.5x commission rate (15% of ARR)
+ > 150% quota: 2.0x commission rate (20% of ARR)
+```
+
+**Why accelerators matter:**
+- They keep top performers motivated past quota
+- They make it possible for top reps to earn $200K+ (attracting talent)
+- They create the "make it rain" culture
+
+### SDR Compensation
+
+SDRs are measured on output (meetings booked, pipeline created), not closed revenue.
+
+```
+Quota: 20 qualified meetings booked per month (or $X pipeline created)
+Commission: $150-300 per qualified meeting held
+
+Accelerators:
+ If a meeting converts to closed won: Bonus $250-500
+ If monthly meetings > 125% of quota: 1.5x rate on upside meetings
+```
+
+### Clawbacks
+
+A clawback recovers commission paid on deals that churn or are fraudulently closed.
+
+**Common clawback rules:**
+- Full clawback if customer cancels within 90 days of close
+- 50% clawback if customer cancels within 91-180 days
+- No clawback after 180 days (AE shouldn't be penalized for future CS failures)
+- Clawbacks vest: pay commission immediately but apply against next quarter's payout if triggered
+
+**Why clawbacks matter:**
+- Without them, reps are incentivized to close any deal, regardless of fit
+- With them, reps self-qualify more carefully
+
+### SPIFFs (Sales Performance Incentive Funds)
+
+Short-term tactical incentives for specific behaviors:
+- $5K bonus for closing a new vertical deal this quarter
+- 1.5x commission on annual prepay deals in Q4
+- $1K for closing a deal in a new geographic territory
+
+Use SPIFFs sparingly. Overuse trains reps to wait for the SPIFF before engaging.
+
+### Multi-Year and Prepay Incentives
+
+Align rep behavior with company cash flow:
+- Multi-year deals: Credit full TCV against quota, pay commission upfront on TCV
+- Annual prepay: 10-20% uplift on commission rate
+- Monthly billing: Standard commission rate
+
+---
+
+## Enterprise vs. SMB vs. Self-Serve Models
+
+### Self-Serve / PLG
+
+**Characteristics:**
+- Product is the primary acquisition channel
+- Credit card required (no invoicing)
+- No human touch in the initial purchase
+- Sales engages only at enterprise signals (high usage, team expansion, compliance needs)
+
+**Funnel:**
+```
+Website → Free trial / Freemium → Activation → PQL → Expansion → Enterprise
+```
+
+**Key metrics:**
+- Free-to-paid conversion rate (benchmark: 2-5% of signups)
+- Time to activation (first core action)
+- PQL → expansion conversion rate
+- NRR from self-serve base
+
+**Sales involvement triggers (PQL signals):**
+- Team size > 10 seats
+- Usage spikes (power user patterns)
+- Feature limit hits on core features
+- Job title change (new economic buyer appears in account)
+
+### SMB Inside Sales
+
+**Characteristics:**
+- ACV $5K-25K
+- 30-60 day sales cycle
+- Inbound-heavy or light outbound
+- SDR → AE → CS model
+- Phone + email + video; no in-person
+
+**Funnel:**
+```
+Inbound/MQL → SDR qualifies → AE discovery → Demo → Proposal → Close
+```
+
+**Key metrics:**
+- MQL-to-SQL rate (benchmark: 15-25%)
+- SQL-to-close rate (benchmark: 20-30%)
+- Average sales cycle (30-60 days)
+- AE productivity: $600K-$1M quota per rep
+
+**Team ratios:**
+- 1 SDR supports 3-4 AEs
+- 1 CSM manages $1M-2M ARR
+
+### Enterprise Sales
+
+**Characteristics:**
+- ACV $50K+
+- 90-365 day sales cycle
+- Outbound prospecting + inbound from brand
+- AE + SE + executive sponsor model
+- Multi-stakeholder: champion, economic buyer, IT, legal, procurement
+
+**Funnel:**
+```
+Account targeting → Executive outreach → Discovery → POC → Security review → Legal → Procurement → Close
+```
+
+**Key metrics:**
+- Deals in pipeline (volume matters less, quality more)
+- POC win rate (benchmark: 60-75%)
+- Average sales cycle (3-12 months)
+- AE productivity: $1.5M-$3M quota per rep
+
+**Team ratios:**
+- 1 SE supports 3-4 AEs
+- 1 CSM manages $2M-5M ARR (named accounts, high-touch)
+
+---
+
+## Sales Hiring and Ramp
+
+### What "Good" Looks Like by Role
+
+**SDR (entry level):**
+- 1-2 years of outbound experience OR strong track record in customer-facing role
+- Resilient: rejection is the job
+- Coachable: SDR is a proving ground, not a final destination
+- Can write clear, concise prospecting emails without templates
+
+**AE (inside sales):**
+- 2-4 years sales experience, preferably SaaS
+- Can articulate their process for a discovery call
+- Knows their numbers: quota, attainment, average deal size, sales cycle
+- Shows how they build pipeline (AEs who only work inbound are a risk)
+
+**AE (enterprise):**
+- 4-8 years B2B sales, at least 2 in enterprise
+- Has closed deals > $100K ACV
+- Can name the stakeholders in a complex deal they navigated
+- Understands procurement, security review, multi-year contracts
+
+**VP Sales:**
+- Has scaled a team from where you are to 2x your size
+- Can build a comp plan from scratch
+- Has hiring and firing experience
+- Revenue from a repeatable process, not personal relationships
+
+### Interview Process
+
+**3-stage process:**
+1. **Recruiter screen** (30 min): Motivation, experience, logistics
+2. **Manager interview** (60 min): Structured questions on process, examples, numbers
+3. **Panel / role play** (90 min): Mock discovery call + debrief; team fit
+
+**Role play rubric:**
+- Did they prepare (knew your product, your ICP)?
+- Did they ask before pitching?
+- Did they handle pushback without capitulating immediately?
+- Did they confirm a next step with a date?
+
+### Onboarding Structure (6-Week Ramp)
+
+| Week | Focus | Activities |
+|------|-------|-----------|
+| 1 | Company, product, ICP | Onboarding sessions, product sandbox, shadow AE calls |
+| 2 | Sales process, tools, messaging | CRM training, call review, write first prospecting emails |
+| 3 | First outreach | Send first sequences, book first meetings, shadow closes |
+| 4 | Independent discovery | Lead own discovery calls with manager reviewing |
+| 5 | Full cycle | Handle pipeline independently, weekly coaching |
+| 6 | Quota-bearing | 25% of quota expectation; full accountability begins |
+
+### Performance Management
+
+**Clear standards, no surprises:**
+```
+Month 3: 25% of quota expected. Miss by > 50% → performance conversation.
+Month 4: 50% of quota expected. Miss by > 40% → PIP warning.
+Month 5: 75% of quota. Miss by > 30% → formal PIP.
+Month 6+: 100% of quota. Consistent miss → exit.
+```
+
+**PIP (Performance Improvement Plan) — not for show:**
+- Should include specific, measurable targets (not "improve attitude")
+- 30-60 day timeline
+- Weekly check-ins with manager
+- If targets aren't met: exit, no extensions
+- A PIP that doesn't lead to improvement or exit is a management failure
+
+**Rule:** Low performers who stay cost you your top performers. They watch what you tolerate.
diff --git a/skills/c-level-advisor/cro-advisor/scripts/churn_analyzer.py b/skills/c-level-advisor/cro-advisor/scripts/churn_analyzer.py
new file mode 100644
index 00000000..be16abff
--- /dev/null
+++ b/skills/c-level-advisor/cro-advisor/scripts/churn_analyzer.py
@@ -0,0 +1,742 @@
+#!/usr/bin/env python3
+"""
+Churn & Retention Analyzer
+===========================
+Customer-level churn and Net Revenue Retention (NRR) analysis for B2B SaaS.
+
+Calculates:
+ - Gross Revenue Retention (GRR) and Net Revenue Retention (NRR)
+ - Monthly and annual churn rates (logo + revenue)
+ - Cohort-based retention curves
+ - At-risk account identification
+ - Expansion revenue segmentation
+ - ARR waterfall (new / expansion / contraction / churn)
+
+Usage:
+ python churn_analyzer.py
+ python churn_analyzer.py --csv customers.csv
+ python churn_analyzer.py --period 2026-Q1 --output summary
+
+Input format (CSV):
+ customer_id, name, segment, arr, start_date, [churn_date], [expansion_arr], [contraction_arr]
+
+Stdlib only. No dependencies.
+"""
+
+import csv
+import sys
+import json
+import argparse
+import statistics
+from datetime import date, datetime, timedelta
+from collections import defaultdict
+from io import StringIO
+from itertools import groupby
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+class Customer:
+ def __init__(self, customer_id, name, segment, arr, start_date,
+ churn_date=None, expansion_arr=0.0, contraction_arr=0.0,
+ health_score=None):
+ self.customer_id = customer_id
+ self.name = name
+ self.segment = segment
+ self.arr = float(arr)
+ self.start_date = self._parse_date(start_date)
+ self.churn_date = self._parse_date(churn_date) if churn_date else None
+ self.expansion_arr = float(expansion_arr or 0)
+ self.contraction_arr = float(contraction_arr or 0)
+ self.health_score = float(health_score) if health_score else None
+
+ @staticmethod
+ def _parse_date(value):
+ if not value or str(value).strip() in ("", "None", "null"):
+ return None
+ for fmt in ("%Y-%m-%d", "%m/%d/%Y", "%d/%m/%Y", "%Y/%m/%d"):
+ try:
+ return datetime.strptime(str(value).strip(), fmt).date()
+ except ValueError:
+ continue
+ raise ValueError(f"Cannot parse date: {value!r}")
+
+ def is_churned(self):
+ return self.churn_date is not None
+
+ def is_active(self, as_of=None):
+ as_of = as_of or date.today()
+ if self.churn_date and self.churn_date <= as_of:
+ return False
+ return self.start_date <= as_of
+
+ def tenure_days(self, as_of=None):
+ as_of = as_of or date.today()
+ end = self.churn_date if self.churn_date else as_of
+ return (end - self.start_date).days
+
+ def tenure_months(self, as_of=None):
+ return self.tenure_days(as_of) / 30.44
+
+ def cohort_month(self):
+ """Acquisition cohort: YYYY-MM of start_date."""
+ return self.start_date.strftime("%Y-%m")
+
+ def cohort_quarter(self):
+ q = (self.start_date.month - 1) // 3 + 1
+ return f"Q{q} {self.start_date.year}"
+
+ def net_arr(self):
+ """Current ARR + expansion - contraction."""
+ return self.arr + self.expansion_arr - self.contraction_arr
+
+ def days_since_acquisition(self, as_of=None):
+ as_of = as_of or date.today()
+ return (as_of - self.start_date).days
+
+
+# ---------------------------------------------------------------------------
+# Core metrics
+# ---------------------------------------------------------------------------
+
+class RetentionAnalyzer:
+ def __init__(self, customers, as_of=None):
+ self.customers = customers
+ self.as_of = as_of or date.today()
+
+ def active_customers(self, as_of=None):
+ as_of = as_of or self.as_of
+ return [c for c in self.customers if c.is_active(as_of)]
+
+ def churned_customers(self, start=None, end=None):
+ """Customers who churned in [start, end]."""
+ result = []
+ for c in self.customers:
+ if not c.churn_date:
+ continue
+ if start and c.churn_date < start:
+ continue
+ if end and c.churn_date > end:
+ continue
+ result.append(c)
+ return result
+
+ def arr_waterfall(self, period_start, period_end):
+ """
+ Calculate ARR waterfall for a given period.
+ Returns dict with opening_arr, new_arr, expansion_arr, contraction_arr,
+ churned_arr, closing_arr, nrr, grr.
+ """
+ # Opening: active at period start
+ opening_customers = [c for c in self.customers if c.is_active(period_start)]
+ opening_arr = sum(c.arr for c in opening_customers)
+ opening_ids = {c.customer_id for c in opening_customers}
+
+ # New: started during the period
+ new_customers = [
+ c for c in self.customers
+ if period_start < c.start_date <= period_end
+ ]
+ new_arr = sum(c.arr for c in new_customers)
+
+ # Churned: were active at start, churn_date within period
+ churned = [
+ c for c in opening_customers
+ if c.churn_date and period_start < c.churn_date <= period_end
+ ]
+ churned_arr = sum(c.arr for c in churned)
+
+ # Expansion and contraction: from customers active at opening
+ expansion = sum(
+ c.expansion_arr for c in opening_customers
+ if not c.is_churned() or (c.churn_date and c.churn_date > period_end)
+ )
+ contraction = sum(
+ c.contraction_arr for c in opening_customers
+ if not c.is_churned() or (c.churn_date and c.churn_date > period_end)
+ )
+
+ closing_arr = opening_arr + new_arr + expansion - contraction - churned_arr
+
+ grr = (opening_arr - contraction - churned_arr) / opening_arr if opening_arr else 0
+ nrr = (opening_arr + expansion - contraction - churned_arr) / opening_arr if opening_arr else 0
+
+ return {
+ "period_start": period_start.isoformat(),
+ "period_end": period_end.isoformat(),
+ "opening_arr": opening_arr,
+ "new_arr": new_arr,
+ "expansion_arr": expansion,
+ "contraction_arr": contraction,
+ "churned_arr": churned_arr,
+ "closing_arr": closing_arr,
+ "net_new_arr": new_arr + expansion - contraction - churned_arr,
+ "grr": max(0.0, grr),
+ "nrr": max(0.0, nrr),
+ }
+
+ def logo_churn_rate(self, period_start, period_end):
+ """Logo churn rate for a period."""
+ opening = [c for c in self.customers if c.is_active(period_start)]
+ churned = [
+ c for c in opening
+ if c.churn_date and period_start < c.churn_date <= period_end
+ ]
+ return len(churned) / len(opening) if opening else 0.0
+
+ def revenue_churn_rate(self, period_start, period_end):
+ """Gross revenue churn rate for a period."""
+ opening = [c for c in self.customers if c.is_active(period_start)]
+ opening_arr = sum(c.arr for c in opening)
+ churned_arr = sum(
+ c.arr for c in opening
+ if c.churn_date and period_start < c.churn_date <= period_end
+ )
+ contraction = sum(c.contraction_arr for c in opening)
+ return (churned_arr + contraction) / opening_arr if opening_arr else 0.0
+
+
+# ---------------------------------------------------------------------------
+# Cohort analysis
+# ---------------------------------------------------------------------------
+
+class CohortAnalyzer:
+ def __init__(self, customers):
+ self.customers = customers
+
+ def build_cohorts(self):
+ """Group customers by acquisition cohort (month)."""
+ cohorts = defaultdict(list)
+ for c in self.customers:
+ cohorts[c.cohort_month()].append(c)
+ return dict(sorted(cohorts.items()))
+
+ def retention_at_month(self, cohort_customers, months_after):
+ """
+ What fraction of cohort ARR remains `months_after` months after acquisition?
+ """
+ if not cohort_customers:
+ return None
+
+ opening_arr = sum(c.arr for c in cohort_customers)
+ if opening_arr == 0:
+ return None
+
+ earliest_start = min(c.start_date for c in cohort_customers)
+ check_date = earliest_start + timedelta(days=int(months_after * 30.44))
+
+ if check_date > date.today():
+ return None # Future — no data
+
+ retained_arr = sum(
+ c.arr for c in cohort_customers
+ if c.is_active(check_date)
+ )
+ return retained_arr / opening_arr
+
+ def retention_curve(self, cohort_customers, max_months=24):
+ """Return retention at months 0, 3, 6, 9, 12, 18, 24."""
+ checkpoints = [0, 3, 6, 9, 12, 18, 24]
+ checkpoints = [m for m in checkpoints if m <= max_months]
+ curve = {}
+ for m in checkpoints:
+ rate = self.retention_at_month(cohort_customers, m)
+ if rate is not None:
+ curve[m] = rate
+ return curve
+
+ def cohort_report(self):
+ """Returns dict: cohort → {size, opening_arr, retention_curve}."""
+ cohorts = self.build_cohorts()
+ report = {}
+ for cohort_month, customers in cohorts.items():
+ curve = self.retention_curve(customers)
+ report[cohort_month] = {
+ "customer_count": len(customers),
+ "opening_arr": sum(c.arr for c in customers),
+ "churned_count": sum(1 for c in customers if c.is_churned()),
+ "current_retention": curve.get(12, curve.get(max(curve.keys()) if curve else 0)),
+ "retention_curve": curve,
+ }
+ return report
+
+ def identify_at_risk(self, tenure_months_max=6, health_threshold=60):
+ """
+ Identify at-risk customers based on:
+ - Low health score (if available)
+ - Short tenure (haven't proved long-term value)
+ - High contraction signals
+ """
+ at_risk = []
+ for c in self.customers:
+ if c.is_churned():
+ continue
+ reasons = []
+ score = 0
+
+ # Health score signal
+ if c.health_score is not None and c.health_score < health_threshold:
+ reasons.append(f"Health score {c.health_score:.0f} < {health_threshold}")
+ score += 40
+
+ # Early tenure risk
+ tenure = c.tenure_months()
+ if tenure < tenure_months_max:
+ reasons.append(f"Tenure {tenure:.1f} months (< {tenure_months_max})")
+ score += 20
+
+ # Contraction signal
+ if c.contraction_arr > 0:
+ contraction_pct = c.contraction_arr / c.arr
+ reasons.append(f"Contraction {contraction_pct:.0%} of ARR")
+ score += 30
+
+ # No expansion in mature account
+ if tenure > 12 and c.expansion_arr == 0:
+ reasons.append("No expansion after 12+ months (stagnant)")
+ score += 10
+
+ if score > 0:
+ at_risk.append({
+ "customer_id": c.customer_id,
+ "name": c.name,
+ "segment": c.segment,
+ "arr": c.arr,
+ "tenure_months": round(tenure, 1),
+ "health_score": c.health_score,
+ "risk_score": score,
+ "risk_reasons": reasons,
+ })
+
+ return sorted(at_risk, key=lambda x: -x["risk_score"])
+
+
+# ---------------------------------------------------------------------------
+# Expansion analysis
+# ---------------------------------------------------------------------------
+
+class ExpansionAnalyzer:
+ def __init__(self, customers):
+ self.customers = customers
+
+ def expansion_summary(self):
+ active = [c for c in self.customers if not c.is_churned()]
+ expanding = [c for c in active if c.expansion_arr > 0]
+ contracting = [c for c in active if c.contraction_arr > 0]
+
+ total_arr = sum(c.arr for c in active)
+ total_expansion = sum(c.expansion_arr for c in active)
+ total_contraction = sum(c.contraction_arr for c in active)
+
+ return {
+ "active_customers": len(active),
+ "total_arr": total_arr,
+ "expanding_count": len(expanding),
+ "contracting_count": len(contracting),
+ "expansion_arr": total_expansion,
+ "contraction_arr": total_contraction,
+ "expansion_rate": total_expansion / total_arr if total_arr else 0,
+ "contraction_rate": total_contraction / total_arr if total_arr else 0,
+ "net_expansion_rate": (total_expansion - total_contraction) / total_arr if total_arr else 0,
+ }
+
+ def expansion_by_segment(self):
+ active = [c for c in self.customers if not c.is_churned()]
+ by_segment = defaultdict(lambda: {"arr": 0.0, "expansion": 0.0,
+ "contraction": 0.0, "count": 0})
+ for c in active:
+ seg = c.segment or "Unspecified"
+ by_segment[seg]["arr"] += c.arr
+ by_segment[seg]["expansion"] += c.expansion_arr
+ by_segment[seg]["contraction"] += c.contraction_arr
+ by_segment[seg]["count"] += 1
+
+ result = {}
+ for seg, data in by_segment.items():
+ arr = data["arr"]
+ result[seg] = {
+ "customer_count": data["count"],
+ "arr": arr,
+ "expansion_arr": data["expansion"],
+ "contraction_arr": data["contraction"],
+ "expansion_rate": data["expansion"] / arr if arr else 0,
+ "net_nrr_contribution": (arr + data["expansion"] - data["contraction"]) / arr if arr else 0,
+ }
+ return result
+
+ def top_expansion_candidates(self, min_tenure_months=6, min_arr=5000):
+ """
+ Customers who are active, healthy tenure, but have zero expansion.
+ These are upsell/expansion targets.
+ """
+ active = [c for c in self.customers if not c.is_churned()]
+ candidates = []
+ for c in active:
+ tenure = c.tenure_months()
+ if (tenure >= min_tenure_months
+ and c.arr >= min_arr
+ and c.expansion_arr == 0
+ and (c.health_score is None or c.health_score >= 60)):
+ candidates.append({
+ "customer_id": c.customer_id,
+ "name": c.name,
+ "segment": c.segment,
+ "arr": c.arr,
+ "tenure_months": round(tenure, 1),
+ "health_score": c.health_score,
+ })
+ return sorted(candidates, key=lambda x: -x["arr"])
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt_currency(value):
+ if value >= 1_000_000:
+ return f"${value / 1_000_000:.2f}M"
+ if value >= 1_000:
+ return f"${value / 1_000:.1f}K"
+ return f"${value:.0f}"
+
+
+def fmt_pct(value):
+ return f"{value * 100:.1f}%"
+
+
+def nrr_status(nrr):
+ if nrr >= 1.20:
+ return "✅ World-class"
+ if nrr >= 1.10:
+ return "✅ Healthy"
+ if nrr >= 1.00:
+ return "⚠️ Acceptable"
+ if nrr >= 0.90:
+ return "🔴 Concerning"
+ return "🔴 Crisis"
+
+
+def grr_status(grr):
+ if grr >= 0.90:
+ return "✅ Strong"
+ if grr >= 0.85:
+ return "⚠️ Acceptable"
+ return "🔴 Below threshold"
+
+
+def print_header(title):
+ width = 70
+ print()
+ print("=" * width)
+ print(f" {title}")
+ print("=" * width)
+
+
+def print_section(title):
+ print(f"\n--- {title} ---")
+
+
+def print_full_report(customers, period_start, period_end):
+ analyzer = RetentionAnalyzer(customers, as_of=period_end)
+ cohort_analyzer = CohortAnalyzer(customers)
+ expansion_analyzer = ExpansionAnalyzer(customers)
+
+ print_header("CHURN & RETENTION ANALYZER")
+ print(f" Analysis period: {period_start.isoformat()} → {period_end.isoformat()}")
+ print(f" Total customers in dataset: {len(customers)}")
+ active = analyzer.active_customers(period_end)
+ churned_in_period = analyzer.churned_customers(period_start, period_end)
+ print(f" Active at period end: {len(active)}")
+ print(f" Churned in period: {len(churned_in_period)}")
+
+ # ── ARR Waterfall
+ print_section("ARR WATERFALL")
+ wf = analyzer.arr_waterfall(period_start, period_end)
+ print(f" Opening ARR: {fmt_currency(wf['opening_arr'])}")
+ print(f" + New Logo ARR: +{fmt_currency(wf['new_arr'])}")
+ print(f" + Expansion ARR: +{fmt_currency(wf['expansion_arr'])}")
+ print(f" - Contraction ARR: -{fmt_currency(wf['contraction_arr'])}")
+ print(f" - Churned ARR: -{fmt_currency(wf['churned_arr'])}")
+ print(f" {'─'*42}")
+ print(f" Closing ARR: {fmt_currency(wf['closing_arr'])}")
+ print(f" Net New ARR: {'+' if wf['net_new_arr'] >= 0 else ''}{fmt_currency(wf['net_new_arr'])}")
+
+ # ── NRR / GRR
+ print_section("RETENTION METRICS")
+ nrr = wf["nrr"]
+ grr = wf["grr"]
+ logo_churn = analyzer.logo_churn_rate(period_start, period_end)
+ rev_churn = analyzer.revenue_churn_rate(period_start, period_end)
+
+ print(f" NRR (Net Revenue Retention): {fmt_pct(nrr)} {nrr_status(nrr)}")
+ print(f" GRR (Gross Revenue Retention): {fmt_pct(grr)} {grr_status(grr)}")
+ print(f" Logo Churn Rate (period): {fmt_pct(logo_churn)}")
+ print(f" Revenue Churn Rate (period): {fmt_pct(rev_churn)}")
+ if wf["opening_arr"] > 0:
+ expansion_rate = wf["expansion_arr"] / wf["opening_arr"]
+ print(f" Expansion Rate (period): {fmt_pct(expansion_rate)}")
+ print()
+ print(f" NRR Benchmark: >120% world-class | 100-120% healthy | <100% fix immediately")
+
+ # ── Expansion summary
+ print_section("EXPANSION REVENUE")
+ exp = expansion_analyzer.expansion_summary()
+ print(f" Expanding customers: {exp['expanding_count']} / {exp['active_customers']} ({fmt_pct(exp['expanding_count']/exp['active_customers']) if exp['active_customers'] else '—'})")
+ print(f" Contracting: {exp['contracting_count']} / {exp['active_customers']}")
+ print(f" Expansion ARR: {fmt_currency(exp['expansion_arr'])} ({fmt_pct(exp['expansion_rate'])} of base)")
+ print(f" Contraction ARR: {fmt_currency(exp['contraction_arr'])}")
+ print(f" Net Expansion Rate: {fmt_pct(exp['net_expansion_rate'])}")
+
+ # ── Segment breakdown
+ print_section("SEGMENT BREAKDOWN (NRR Components)")
+ seg_data = expansion_analyzer.expansion_by_segment()
+ col_w = [18, 8, 12, 10, 10, 10]
+ h = (f" {'Segment':<{col_w[0]}} {'Custs':>{col_w[1]}} {'ARR':>{col_w[2]}} "
+ f"{'Expansion':>{col_w[3]}} {'Contraction':>{col_w[4]}} {'NRR':>{col_w[5]}}")
+ print(h)
+ print(" " + "-" * (sum(col_w) + 5))
+ for seg, data in sorted(seg_data.items(), key=lambda x: -x[1]["arr"]):
+ print(f" {seg:<{col_w[0]}} {data['customer_count']:>{col_w[1]}} "
+ f"{fmt_currency(data['arr']):>{col_w[2]}} "
+ f"{fmt_currency(data['expansion_arr']):>{col_w[3]}} "
+ f"{fmt_currency(data['contraction_arr']):>{col_w[4]}} "
+ f"{fmt_pct(data['net_nrr_contribution']):>{col_w[5]}}")
+
+ # ── Cohort retention
+ print_section("COHORT RETENTION CURVES")
+ cohort_report = cohort_analyzer.cohort_report()
+ print(f" {'Cohort':<10} {'Custs':>6} {'Opening ARR':>13} {'Mo.3':>8} {'Mo.6':>8} {'Mo.12':>8}")
+ print(" " + "-" * 57)
+ for cohort, data in cohort_report.items():
+ curve = data["retention_curve"]
+ m3 = fmt_pct(curve[3]) if 3 in curve else " —"
+ m6 = fmt_pct(curve[6]) if 6 in curve else " —"
+ m12 = fmt_pct(curve[12]) if 12 in curve else " —"
+ print(f" {cohort:<10} {data['customer_count']:>6} "
+ f"{fmt_currency(data['opening_arr']):>13} "
+ f"{m3:>8} {m6:>8} {m12:>8}")
+
+ # ── At-risk accounts
+ print_section("AT-RISK ACCOUNTS")
+ at_risk = cohort_analyzer.identify_at_risk()
+ if at_risk:
+ print(f" {'Customer':<22} {'Segment':<14} {'ARR':>10} {'Tenure':>8} {'Risk':>6} Reason")
+ print(" " + "-" * 80)
+ for acct in at_risk[:10]: # Top 10
+ reason_short = acct["risk_reasons"][0] if acct["risk_reasons"] else ""
+ tenure_str = f"{acct['tenure_months']}mo"
+ print(f" {acct['name']:<22} {acct['segment']:<14} "
+ f"{fmt_currency(acct['arr']):>10} {tenure_str:>8} "
+ f"{acct['risk_score']:>5} {reason_short}")
+ if len(at_risk) > 10:
+ print(f" ... and {len(at_risk) - 10} more at-risk accounts")
+ else:
+ print(" ✅ No at-risk accounts identified")
+
+ # ── Expansion candidates
+ print_section("EXPANSION CANDIDATES (no expansion yet, healthy tenure)")
+ candidates = expansion_analyzer.top_expansion_candidates()
+ if candidates:
+ print(f" {'Customer':<22} {'Segment':<14} {'ARR':>10} {'Tenure':>8} Action")
+ print(" " + "-" * 70)
+ for c in candidates[:8]:
+ action = "Upsell review" if c["arr"] > 20000 else "Seat expansion call"
+ tenure_str = f"{c['tenure_months']}mo"
+ print(f" {c['name']:<22} {c['segment']:<14} "
+ f"{fmt_currency(c['arr']):>10} {tenure_str:>8} {action}")
+ else:
+ print(" ✅ All eligible accounts have expansion in motion")
+
+ # ── Red flags
+ print_section("HEALTH FLAGS")
+ flags = []
+ if nrr < 1.0:
+ flags.append("🔴 NRR below 100% — revenue base is shrinking. Fix before scaling sales.")
+ if grr < 0.85:
+ flags.append(f"🔴 GRR {fmt_pct(grr)} — gross retention below 85% threshold. Churn is a product/CS problem.")
+ if logo_churn > 0.05:
+ flags.append(f"⚠️ Logo churn {fmt_pct(logo_churn)} this period — run cohort analysis to find the pattern.")
+ if exp["expansion_rate"] < 0.10 and exp["active_customers"] > 10:
+ flags.append("⚠️ Expansion rate below 10% — upsell motion is weak or non-existent.")
+ churned_arr_pct = wf["churned_arr"] / wf["opening_arr"] if wf["opening_arr"] else 0
+ if churned_arr_pct > 0.10:
+ flags.append(f"🔴 Revenue churn at {fmt_pct(churned_arr_pct)} of opening ARR this period — high urgency.")
+ if len(at_risk) > len(active) * 0.20:
+ flags.append(f"⚠️ {len(at_risk)} of {len(active)} active accounts flagged at-risk ({fmt_pct(len(at_risk)/len(active) if active else 0)})")
+
+ if flags:
+ for f in flags:
+ print(f" {f}")
+ else:
+ print(" ✅ No critical health flags")
+
+ print()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+SAMPLE_CSV = """customer_id,name,segment,arr,start_date,churn_date,expansion_arr,contraction_arr,health_score
+C001,Acme Manufacturing,Enterprise,120000,2023-01-15,,45000,0,82
+C002,TechStart Inc,Mid-Market,28000,2023-02-01,,8000,0,74
+C003,Global Retail Co,Enterprise,250000,2023-01-05,,0,25000,45
+C004,MedTech Solutions,Mid-Market,45000,2023-03-10,,15000,0,88
+C005,FinServ Holdings,Enterprise,185000,2023-01-20,2023-09-15,0,0,
+C006,StartupHub Network,SMB,12000,2023-04-01,,0,3000,55
+C007,EduPlatform Inc,Mid-Market,32000,2023-02-15,,10000,0,91
+C008,BioLab Analytics,Enterprise,95000,2023-01-10,,20000,0,78
+C009,RegionalBank Corp,Enterprise,310000,2023-03-01,,75000,0,85
+C010,CloudOps Systems,Mid-Market,38000,2023-05-01,2024-01-10,0,0,
+C011,InsurTech Platform,Mid-Market,55000,2023-06-15,,0,0,62
+C012,LegalAI Corp,SMB,18000,2023-07-01,,5000,0,79
+C013,RetailChain Ltd,Enterprise,140000,2023-04-20,,0,20000,41
+C014,DataPipeline Co,Mid-Market,42000,2023-08-01,,12000,0,83
+C015,NanoTech Startup,SMB,9500,2023-09-15,2024-02-28,0,0,
+C016,MedDevice Corp,Enterprise,220000,2023-02-28,,60000,0,92
+C017,ConsultingFirm XYZ,SMB,15000,2023-10-01,,0,5000,38
+C018,GovTech Solutions,Enterprise,175000,2023-11-15,,0,0,71
+C019,AgriData Systems,Mid-Market,31000,2024-01-10,,8000,0,77
+C020,HealthcarePlus,Mid-Market,62000,2024-02-01,,0,0,65
+"""
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def load_customers_from_csv(csv_text):
+ reader = csv.DictReader(StringIO(csv_text))
+ customers = []
+ errors = []
+ for i, row in enumerate(reader, start=2):
+ try:
+ c = Customer(
+ customer_id=row.get("customer_id", f"row_{i}"),
+ name=row.get("name", f"Customer {i}"),
+ segment=row.get("segment", ""),
+ arr=row.get("arr", 0),
+ start_date=row.get("start_date", ""),
+ churn_date=row.get("churn_date", None) or None,
+ expansion_arr=row.get("expansion_arr", 0) or 0,
+ contraction_arr=row.get("contraction_arr", 0) or 0,
+ health_score=row.get("health_score", None) or None,
+ )
+ customers.append(c)
+ except (ValueError, KeyError) as e:
+ errors.append(f" Row {i}: {e}")
+ if errors:
+ print("⚠️ Skipped rows with errors:")
+ for err in errors:
+ print(err)
+ return customers
+
+
+def parse_period(period_str):
+ """Parse 'YYYY-QN' or 'YYYY-MM' into (start_date, end_date)."""
+ if not period_str:
+ today = date.today()
+ q = (today.month - 1) // 3
+ start = date(today.year, q * 3 + 1, 1)
+ # End of current quarter
+ end_month = start.month + 2
+ end_year = start.year + (end_month - 1) // 12
+ end_month = ((end_month - 1) % 12) + 1
+ import calendar
+ end_day = calendar.monthrange(end_year, end_month)[1]
+ return start, date(end_year, end_month, end_day)
+
+ import calendar
+ if "-Q" in period_str:
+ year, qpart = period_str.split("-Q")
+ year = int(year)
+ q = int(qpart)
+ start_month = (q - 1) * 3 + 1
+ end_month = start_month + 2
+ start = date(year, start_month, 1)
+ end = date(year, end_month, calendar.monthrange(year, end_month)[1])
+ return start, end
+
+ # YYYY-MM
+ year, month = period_str.split("-")
+ year, month = int(year), int(month)
+ start = date(year, month, 1)
+ end = date(year, month, calendar.monthrange(year, month)[1])
+ return start, end
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Churn & Retention Analyzer — NRR, cohort analysis, at-risk detection"
+ )
+ parser.add_argument(
+ "--csv", metavar="FILE",
+ help="CSV file with customer data (uses sample data if not provided)"
+ )
+ parser.add_argument(
+ "--period", metavar="PERIOD",
+ help='Analysis period: "2026-Q1" or "2026-03" (defaults to current quarter)'
+ )
+ parser.add_argument(
+ "--output", choices=["summary", "full", "json"],
+ default="full",
+ help="Output format (default: full)"
+ )
+ args = parser.parse_args()
+
+ # Load data
+ if args.csv:
+ try:
+ with open(args.csv, "r", encoding="utf-8") as f:
+ csv_text = f.read()
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.csv}", file=sys.stderr)
+ sys.exit(1)
+ else:
+ print("No --csv provided. Using sample customer data.\n")
+ csv_text = SAMPLE_CSV
+
+ customers = load_customers_from_csv(csv_text)
+ if not customers:
+ print("No customers loaded. Exiting.", file=sys.stderr)
+ sys.exit(1)
+
+ period_start, period_end = parse_period(args.period)
+
+ if args.output == "json":
+ analyzer = RetentionAnalyzer(customers, as_of=period_end)
+ cohort_analyzer = CohortAnalyzer(customers)
+ expansion_analyzer = ExpansionAnalyzer(customers)
+ wf = analyzer.arr_waterfall(period_start, period_end)
+ output = {
+ "period": {"start": period_start.isoformat(), "end": period_end.isoformat()},
+ "arr_waterfall": wf,
+ "logo_churn_rate": analyzer.logo_churn_rate(period_start, period_end),
+ "revenue_churn_rate": analyzer.revenue_churn_rate(period_start, period_end),
+ "cohort_report": {k: {**v, "retention_curve": {str(m): r for m, r in v["retention_curve"].items()}}
+ for k, v in cohort_analyzer.cohort_report().items()},
+ "at_risk_accounts": cohort_analyzer.identify_at_risk(),
+ "expansion_summary": expansion_analyzer.expansion_summary(),
+ "expansion_by_segment": expansion_analyzer.expansion_by_segment(),
+ "expansion_candidates": expansion_analyzer.top_expansion_candidates(),
+ }
+ print(json.dumps(output, indent=2))
+ elif args.output == "summary":
+ analyzer = RetentionAnalyzer(customers, as_of=period_end)
+ wf = analyzer.arr_waterfall(period_start, period_end)
+ print_header("NRR SUMMARY")
+ print(f" Period: {period_start.isoformat()} → {period_end.isoformat()}")
+ print(f" NRR: {fmt_pct(wf['nrr'])} {nrr_status(wf['nrr'])}")
+ print(f" GRR: {fmt_pct(wf['grr'])} {grr_status(wf['grr'])}")
+ print(f" Opening: {fmt_currency(wf['opening_arr'])}")
+ print(f" Closing: {fmt_currency(wf['closing_arr'])}")
+ print(f" Net New: {fmt_currency(wf['net_new_arr'])}")
+ print()
+ else:
+ print_full_report(customers, period_start, period_end)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cro-advisor/scripts/revenue_forecast_model.py b/skills/c-level-advisor/cro-advisor/scripts/revenue_forecast_model.py
new file mode 100644
index 00000000..fd9a7a36
--- /dev/null
+++ b/skills/c-level-advisor/cro-advisor/scripts/revenue_forecast_model.py
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+"""
+Revenue Forecast Model
+======================
+Pipeline-based revenue forecasting for B2B SaaS.
+
+Models:
+ - Weighted pipeline (stage probability × deal value)
+ - Historical win rate adjustment (calibrate to actuals)
+ - Scenario analysis (conservative / base / upside)
+ - Monthly and quarterly projection with confidence ranges
+
+Usage:
+ python revenue_forecast_model.py
+ python revenue_forecast_model.py --csv pipeline.csv
+ python revenue_forecast_model.py --scenario conservative
+
+Input format (CSV):
+ deal_id, name, stage, arr_value, close_date, rep, segment
+
+Stdlib only. No dependencies.
+"""
+
+import csv
+import sys
+import json
+import argparse
+import statistics
+from datetime import date, datetime, timedelta
+from collections import defaultdict
+from io import StringIO
+
+
+# ---------------------------------------------------------------------------
+# Stage configuration
+# ---------------------------------------------------------------------------
+
+DEFAULT_STAGE_PROBABILITIES = {
+ "discovery": 0.10,
+ "qualification": 0.25,
+ "demo": 0.40,
+ "proposal": 0.55,
+ "poc": 0.65,
+ "negotiation": 0.80,
+ "verbal_commit": 0.92,
+ "closed_won": 1.00,
+ "closed_lost": 0.00,
+}
+
+SCENARIO_MULTIPLIERS = {
+ "conservative": 0.85, # Win rate 15% below historical
+ "base": 1.00, # Historical win rate
+ "upside": 1.15, # Win rate 15% above historical
+}
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+class Deal:
+ def __init__(self, deal_id, name, stage, arr_value, close_date, rep="", segment=""):
+ self.deal_id = deal_id
+ self.name = name
+ self.stage = stage.lower().replace(" ", "_").replace("/", "_")
+ self.arr_value = float(arr_value)
+ self.close_date = self._parse_date(close_date)
+ self.rep = rep
+ self.segment = segment
+
+ @staticmethod
+ def _parse_date(value):
+ for fmt in ("%Y-%m-%d", "%m/%d/%Y", "%d/%m/%Y", "%Y/%m/%d"):
+ try:
+ return datetime.strptime(str(value), fmt).date()
+ except ValueError:
+ continue
+ raise ValueError(f"Cannot parse date: {value!r}")
+
+ @property
+ def quarter(self):
+ q = (self.close_date.month - 1) // 3 + 1
+ return f"Q{q} {self.close_date.year}"
+
+ @property
+ def month_key(self):
+ return self.close_date.strftime("%Y-%m")
+
+ def weighted_value(self, stage_probs, scenario="base"):
+ prob = stage_probs.get(self.stage, 0.0)
+ multiplier = SCENARIO_MULTIPLIERS.get(scenario, 1.0)
+ # Clamp probability to [0, 1]
+ adjusted = min(1.0, max(0.0, prob * multiplier))
+ return self.arr_value * adjusted
+
+ def is_open(self):
+ return self.stage not in ("closed_won", "closed_lost")
+
+ def is_closed_won(self):
+ return self.stage == "closed_won"
+
+
+# ---------------------------------------------------------------------------
+# Win rate calibration
+# ---------------------------------------------------------------------------
+
+def calculate_historical_win_rates(deals):
+ """
+ Calculate actual win rates per stage from closed deals.
+ Returns a dict: stage → win_rate (float).
+ Requires deals that were at each stage and are now closed won/lost.
+ """
+ # In a real implementation, you'd have historical stage-at-point-in-time data.
+ # Here we approximate: among closed deals, what fraction were won?
+ closed = [d for d in deals if not d.is_open()]
+ if not closed:
+ return {}
+
+ won = [d for d in closed if d.is_closed_won()]
+ overall_rate = len(won) / len(closed) if closed else 0.0
+
+ # Stage-level calibration: adjust default probs by actual overall rate
+ # (In production: use CRM historical stage-level conversion data)
+ calibrated = {}
+ for stage, default_prob in DEFAULT_STAGE_PROBABILITIES.items():
+ if overall_rate > 0:
+ calibrated[stage] = min(1.0, default_prob * (overall_rate / 0.25))
+ else:
+ calibrated[stage] = default_prob
+
+ return calibrated
+
+
+# ---------------------------------------------------------------------------
+# Forecast engine
+# ---------------------------------------------------------------------------
+
+class ForecastEngine:
+ def __init__(self, deals, stage_probs=None):
+ self.deals = deals
+ self.stage_probs = stage_probs or DEFAULT_STAGE_PROBABILITIES
+
+ def open_deals(self):
+ return [d for d in self.deals if d.is_open()]
+
+ def closed_won_deals(self):
+ return [d for d in self.deals if d.is_closed_won()]
+
+ def pipeline_by_month(self, scenario="base"):
+ """Returns dict: month_key → weighted ARR."""
+ result = defaultdict(float)
+ for deal in self.open_deals():
+ result[deal.month_key] += deal.weighted_value(self.stage_probs, scenario)
+ return dict(sorted(result.items()))
+
+ def pipeline_by_quarter(self, scenario="base"):
+ """Returns dict: quarter → weighted ARR."""
+ result = defaultdict(float)
+ for deal in self.open_deals():
+ result[deal.quarter] += deal.weighted_value(self.stage_probs, scenario)
+ return dict(sorted(result.items()))
+
+ def coverage_ratio(self, quota, period_filter=None):
+ """
+ Pipeline coverage = total pipeline ÷ quota.
+ period_filter: if set, only include deals with close_date in that period.
+ """
+ pipeline = sum(
+ d.arr_value for d in self.open_deals()
+ if period_filter is None or d.quarter == period_filter
+ )
+ return pipeline / quota if quota else 0.0
+
+ def scenario_summary(self, periods=None):
+ """
+ Returns dict: period → {conservative, base, upside, open_pipeline}.
+ periods: list of month_keys to include; if None, all months.
+ """
+ summaries = {}
+ all_months = sorted(set(d.month_key for d in self.open_deals()))
+ target_months = periods or all_months
+
+ for month in target_months:
+ deals_in_month = [d for d in self.open_deals() if d.month_key == month]
+ if not deals_in_month:
+ continue
+ summaries[month] = {
+ "deal_count": len(deals_in_month),
+ "open_pipeline": sum(d.arr_value for d in deals_in_month),
+ "conservative": sum(d.weighted_value(self.stage_probs, "conservative") for d in deals_in_month),
+ "base": sum(d.weighted_value(self.stage_probs, "base") for d in deals_in_month),
+ "upside": sum(d.weighted_value(self.stage_probs, "upside") for d in deals_in_month),
+ }
+ return summaries
+
+ def rep_performance(self):
+ """Returns dict: rep → {pipeline, weighted_base, deal_count, avg_deal_size}."""
+ rep_data = defaultdict(lambda: {"pipeline": 0.0, "weighted_base": 0.0,
+ "deal_count": 0, "deals": []})
+ for deal in self.open_deals():
+ rep_data[deal.rep]["pipeline"] += deal.arr_value
+ rep_data[deal.rep]["weighted_base"] += deal.weighted_value(self.stage_probs, "base")
+ rep_data[deal.rep]["deal_count"] += 1
+ rep_data[deal.rep]["deals"].append(deal.arr_value)
+
+ result = {}
+ for rep, data in rep_data.items():
+ deals = data["deals"]
+ result[rep] = {
+ "pipeline": data["pipeline"],
+ "weighted_base": data["weighted_base"],
+ "deal_count": data["deal_count"],
+ "avg_deal_size": statistics.mean(deals) if deals else 0.0,
+ }
+ return result
+
+ def segment_breakdown(self, scenario="base"):
+ """Returns dict: segment → weighted ARR."""
+ result = defaultdict(float)
+ for deal in self.open_deals():
+ result[deal.segment or "unspecified"] += deal.weighted_value(self.stage_probs, scenario)
+ return dict(result)
+
+ def stage_distribution(self):
+ """Returns dict: stage → {count, total_arr, avg_arr}."""
+ result = defaultdict(lambda: {"count": 0, "total_arr": 0.0})
+ for deal in self.open_deals():
+ result[deal.stage]["count"] += 1
+ result[deal.stage]["total_arr"] += deal.arr_value
+ out = {}
+ for stage, data in result.items():
+ out[stage] = {
+ "count": data["count"],
+ "total_arr": data["total_arr"],
+ "avg_arr": data["total_arr"] / data["count"] if data["count"] else 0,
+ "probability": self.stage_probs.get(stage, 0.0),
+ }
+ return out
+
+ def confidence_interval(self, scenario="base", iterations=1000):
+ """
+ Monte Carlo simulation to generate confidence interval around base forecast.
+ Each deal wins/loses based on its probability; runs iterations times.
+ Returns (p10, p50, p90) of total expected ARR.
+ """
+ import random
+ random.seed(42)
+
+ totals = []
+ for _ in range(iterations):
+ total = 0.0
+ for deal in self.open_deals():
+ prob = min(1.0, self.stage_probs.get(deal.stage, 0.0) * SCENARIO_MULTIPLIERS[scenario])
+ if random.random() < prob:
+ total += deal.arr_value
+ totals.append(total)
+
+ totals.sort()
+ n = len(totals)
+ return (
+ totals[int(n * 0.10)], # P10 (conservative)
+ totals[int(n * 0.50)], # P50 (median)
+ totals[int(n * 0.90)], # P90 (upside)
+ )
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt_currency(value):
+ if value >= 1_000_000:
+ return f"${value / 1_000_000:.2f}M"
+ if value >= 1_000:
+ return f"${value / 1_000:.1f}K"
+ return f"${value:.0f}"
+
+
+def fmt_pct(value):
+ return f"{value * 100:.1f}%"
+
+
+def print_header(title):
+ width = 70
+ print()
+ print("=" * width)
+ print(f" {title}")
+ print("=" * width)
+
+
+def print_section(title):
+ print(f"\n--- {title} ---")
+
+
+def print_report(engine, quota=None, current_quarter=None):
+ open_deals = engine.open_deals()
+ won_deals = engine.closed_won_deals()
+
+ print_header("REVENUE FORECAST MODEL")
+ print(f" Generated: {date.today().isoformat()}")
+ print(f" Open deals: {len(open_deals)}")
+ print(f" Closed Won (in dataset): {len(won_deals)}")
+ total_pipeline = sum(d.arr_value for d in open_deals)
+ total_won = sum(d.arr_value for d in won_deals)
+ print(f" Total open pipeline: {fmt_currency(total_pipeline)}")
+ print(f" Total closed won: {fmt_currency(total_won)}")
+
+ # ── Coverage ratio
+ if quota:
+ print_section("PIPELINE COVERAGE")
+ q = current_quarter or "this quarter"
+ ratio = engine.coverage_ratio(quota, period_filter=current_quarter)
+ status = "✅ Healthy" if ratio >= 3.0 else ("⚠️ Thin" if ratio >= 2.0 else "🔴 Critical")
+ print(f" Quota target: {fmt_currency(quota)}")
+ print(f" Coverage ratio: {ratio:.1f}x {status}")
+ print(f" (Minimum healthy = 3x; < 2x = pipeline emergency)")
+
+ # ── Stage distribution
+ print_section("STAGE DISTRIBUTION")
+ stage_dist = engine.stage_distribution()
+ col_w = [28, 8, 14, 12, 10]
+ header = f" {'Stage':<{col_w[0]}} {'Deals':>{col_w[1]}} {'Pipeline':>{col_w[2]}} {'Avg Size':>{col_w[3]}} {'Win Prob':>{col_w[4]}}"
+ print(header)
+ print(" " + "-" * (sum(col_w) + 4))
+ for stage, data in sorted(stage_dist.items(), key=lambda x: -x[1]["total_arr"]):
+ print(f" {stage:<{col_w[0]}} {data['count']:>{col_w[1]}} "
+ f"{fmt_currency(data['total_arr']):>{col_w[2]}} "
+ f"{fmt_currency(data['avg_arr']):>{col_w[3]}} "
+ f"{fmt_pct(data['probability']):>{col_w[4]}}")
+
+ # ── Scenario forecast by month
+ print_section("MONTHLY FORECAST — ALL SCENARIOS")
+ summaries = engine.scenario_summary()
+ col_w2 = [10, 8, 14, 14, 14, 14]
+ h2 = (f" {'Month':<{col_w2[0]}} {'Deals':>{col_w2[1]}} "
+ f"{'Pipeline':>{col_w2[2]}} {'Conservative':>{col_w2[3]}} "
+ f"{'Base':>{col_w2[4]}} {'Upside':>{col_w2[5]}}")
+ print(h2)
+ print(" " + "-" * (sum(col_w2) + 5))
+ for month, data in summaries.items():
+ print(f" {month:<{col_w2[0]}} {data['deal_count']:>{col_w2[1]}} "
+ f"{fmt_currency(data['open_pipeline']):>{col_w2[2]}} "
+ f"{fmt_currency(data['conservative']):>{col_w2[3]}} "
+ f"{fmt_currency(data['base']):>{col_w2[4]}} "
+ f"{fmt_currency(data['upside']):>{col_w2[5]}}")
+
+ # ── Quarterly rollup
+ print_section("QUARTERLY FORECAST ROLLUP")
+ q_conservative = defaultdict(float)
+ q_base = defaultdict(float)
+ q_upside = defaultdict(float)
+ q_pipeline = defaultdict(float)
+ q_count = defaultdict(int)
+ for deal in open_deals:
+ q_conservative[deal.quarter] += deal.weighted_value(engine.stage_probs, "conservative")
+ q_base[deal.quarter] += deal.weighted_value(engine.stage_probs, "base")
+ q_upside[deal.quarter] += deal.weighted_value(engine.stage_probs, "upside")
+ q_pipeline[deal.quarter] += deal.arr_value
+ q_count[deal.quarter] += 1
+
+ quarters = sorted(q_base.keys())
+ col_w3 = [10, 8, 14, 14, 14, 14]
+ h3 = (f" {'Quarter':<{col_w3[0]}} {'Deals':>{col_w3[1]}} "
+ f"{'Pipeline':>{col_w3[2]}} {'Conservative':>{col_w3[3]}} "
+ f"{'Base':>{col_w3[4]}} {'Upside':>{col_w3[5]}}")
+ print(h3)
+ print(" " + "-" * (sum(col_w3) + 5))
+ for q in quarters:
+ print(f" {q:<{col_w3[0]}} {q_count[q]:>{col_w3[1]}} "
+ f"{fmt_currency(q_pipeline[q]):>{col_w3[2]}} "
+ f"{fmt_currency(q_conservative[q]):>{col_w3[3]}} "
+ f"{fmt_currency(q_base[q]):>{col_w3[4]}} "
+ f"{fmt_currency(q_upside[q]):>{col_w3[5]}}")
+
+ # ── Monte Carlo confidence interval
+ print_section("CONFIDENCE INTERVAL (Monte Carlo, 1,000 simulations)")
+ p10, p50, p90 = engine.confidence_interval("base")
+ print(f" P10 (conservative floor): {fmt_currency(p10)}")
+ print(f" P50 (median expected): {fmt_currency(p50)}")
+ print(f" P90 (upside ceiling): {fmt_currency(p90)}")
+ print(f" Range spread: {fmt_currency(p90 - p10)}")
+
+ # ── Rep performance
+ print_section("REP PIPELINE PERFORMANCE")
+ rep_perf = engine.rep_performance()
+ if rep_perf:
+ col_w4 = [20, 8, 14, 14, 12]
+ h4 = (f" {'Rep':<{col_w4[0]}} {'Deals':>{col_w4[1]}} "
+ f"{'Pipeline':>{col_w4[2]}} {'Weighted':>{col_w4[3]}} {'Avg Size':>{col_w4[4]}}")
+ print(h4)
+ print(" " + "-" * (sum(col_w4) + 4))
+ for rep, data in sorted(rep_perf.items(), key=lambda x: -x[1]["pipeline"]):
+ print(f" {rep:<{col_w4[0]}} {data['deal_count']:>{col_w4[1]}} "
+ f"{fmt_currency(data['pipeline']):>{col_w4[2]}} "
+ f"{fmt_currency(data['weighted_base']):>{col_w4[3]}} "
+ f"{fmt_currency(data['avg_deal_size']):>{col_w4[4]}}")
+
+ # ── Segment breakdown
+ print_section("SEGMENT BREAKDOWN (Base Forecast)")
+ seg = engine.segment_breakdown("base")
+ for segment, value in sorted(seg.items(), key=lambda x: -x[1]):
+ bar_len = int((value / total_pipeline) * 30) if total_pipeline else 0
+ bar = "█" * bar_len
+ print(f" {segment:<20} {fmt_currency(value):>12} {bar}")
+
+ # ── Red flags
+ print_section("FORECAST HEALTH FLAGS")
+ flags = []
+ if total_pipeline > 0:
+ coverage = total_pipeline / quota if quota else None
+ if coverage and coverage < 2.0:
+ flags.append("🔴 Pipeline coverage below 2x — serious shortfall risk this quarter")
+ elif coverage and coverage < 3.0:
+ flags.append("⚠️ Pipeline coverage below 3x — limited buffer for slippage")
+
+ # Stage concentration risk
+ early_stage_pct = sum(
+ d.arr_value for d in open_deals
+ if engine.stage_probs.get(d.stage, 0) < 0.30
+ ) / total_pipeline
+ if early_stage_pct > 0.60:
+ flags.append(f"⚠️ {fmt_pct(early_stage_pct)} of pipeline in early stages (< 30% probability)")
+
+ # Deal concentration
+ deal_values = sorted([d.arr_value for d in open_deals], reverse=True)
+ if deal_values and deal_values[0] / total_pipeline > 0.25:
+ flags.append(f"⚠️ Top deal is {fmt_pct(deal_values[0]/total_pipeline)} of pipeline — concentration risk")
+
+ # Spread between scenarios
+ total_conservative = sum(d.weighted_value(engine.stage_probs, "conservative") for d in open_deals)
+ total_upside = sum(d.weighted_value(engine.stage_probs, "upside") for d in open_deals)
+ spread = (total_upside - total_conservative) / total_conservative if total_conservative else 0
+ if spread > 0.40:
+ flags.append(f"⚠️ High scenario spread ({fmt_pct(spread)}) — forecast confidence is low")
+
+ if flags:
+ for f in flags:
+ print(f" {f}")
+ else:
+ print(" ✅ No critical flags detected")
+
+ print()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+SAMPLE_CSV = """deal_id,name,stage,arr_value,close_date,rep,segment
+D001,Acme Corp ERP Integration,negotiation,85000,2026-03-15,Sarah Chen,Enterprise
+D002,TechStart PLG Expansion,proposal,28000,2026-03-28,Marcus Webb,Mid-Market
+D003,Global Retail Co,verbal_commit,220000,2026-03-10,Sarah Chen,Enterprise
+D004,BioLab Analytics,poc,62000,2026-04-05,Jamie Park,Mid-Market
+D005,FinServ Holdings,demo,150000,2026-04-20,Sarah Chen,Enterprise
+D006,MidWest Logistics,qualification,35000,2026-04-30,Marcus Webb,Mid-Market
+D007,Edu Platform Inc,negotiation,42000,2026-03-25,Jamie Park,SMB
+D008,Healthcare Connect,proposal,95000,2026-05-15,Sarah Chen,Enterprise
+D009,Startup Hub Network,demo,18000,2026-04-10,Marcus Webb,SMB
+D010,CloudOps Systems,poc,75000,2026-05-01,Jamie Park,Mid-Market
+D011,National Bank Corp,verbal_commit,310000,2026-03-31,Sarah Chen,Enterprise
+D012,RetailTech Co,qualification,22000,2026-05-20,Marcus Webb,SMB
+D013,InsurTech Platform,negotiation,88000,2026-04-15,Jamie Park,Mid-Market
+D014,GovTech Solutions,proposal,175000,2026-06-01,Sarah Chen,Enterprise
+D015,AgriData Systems,demo,31000,2026-05-10,Marcus Webb,Mid-Market
+D016,Legal AI Corp,poc,55000,2026-04-25,Jamie Park,Mid-Market
+D017,Closed Won Deal,closed_won,120000,2026-02-15,Sarah Chen,Enterprise
+D018,Lost Deal,closed_lost,45000,2026-02-20,Marcus Webb,Mid-Market
+"""
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def load_deals_from_csv(csv_text):
+ reader = csv.DictReader(StringIO(csv_text))
+ deals = []
+ errors = []
+ for i, row in enumerate(reader, start=2):
+ try:
+ deal = Deal(
+ deal_id=row.get("deal_id", f"row_{i}"),
+ name=row.get("name", ""),
+ stage=row.get("stage", ""),
+ arr_value=row.get("arr_value", 0),
+ close_date=row.get("close_date", ""),
+ rep=row.get("rep", ""),
+ segment=row.get("segment", ""),
+ )
+ deals.append(deal)
+ except (ValueError, KeyError) as e:
+ errors.append(f" Row {i}: {e}")
+ if errors:
+ print("⚠️ Skipped rows with errors:")
+ for err in errors:
+ print(err)
+ return deals
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Revenue Forecast Model — pipeline-based ARR forecasting"
+ )
+ parser.add_argument(
+ "--csv", metavar="FILE",
+ help="CSV file with pipeline data (uses sample data if not provided)"
+ )
+ parser.add_argument(
+ "--quota", type=float, default=1_000_000,
+ help="Quarterly quota target in ARR (default: $1,000,000)"
+ )
+ parser.add_argument(
+ "--quarter", metavar="QUARTER",
+ help='Current quarter filter e.g. "Q2 2026" (optional)'
+ )
+ parser.add_argument(
+ "--scenario", choices=["conservative", "base", "upside"],
+ default="base",
+ help="Primary scenario to report (default: base)"
+ )
+ parser.add_argument(
+ "--json", action="store_true",
+ help="Output forecast as JSON instead of formatted report"
+ )
+ args = parser.parse_args()
+
+ # Load data
+ if args.csv:
+ try:
+ with open(args.csv, "r", encoding="utf-8") as f:
+ csv_text = f.read()
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.csv}", file=sys.stderr)
+ sys.exit(1)
+ else:
+ print("No --csv provided. Using sample pipeline data.\n")
+ csv_text = SAMPLE_CSV
+
+ deals = load_deals_from_csv(csv_text)
+ if not deals:
+ print("No deals loaded. Exiting.", file=sys.stderr)
+ sys.exit(1)
+
+ # Calibrate win rates from closed deals
+ historical_probs = calculate_historical_win_rates(deals)
+ stage_probs = historical_probs if historical_probs else DEFAULT_STAGE_PROBABILITIES
+
+ engine = ForecastEngine(deals, stage_probs=stage_probs)
+
+ if args.json:
+ output = {
+ "generated": date.today().isoformat(),
+ "quota": args.quota,
+ "open_pipeline": sum(d.arr_value for d in engine.open_deals()),
+ "coverage_ratio": engine.coverage_ratio(args.quota, args.quarter),
+ "monthly_forecast": engine.scenario_summary(),
+ "quarterly_base": engine.pipeline_by_quarter("base"),
+ "confidence_interval": dict(zip(
+ ["p10", "p50", "p90"],
+ engine.confidence_interval("base")
+ )),
+ "rep_performance": engine.rep_performance(),
+ "segment_breakdown": engine.segment_breakdown("base"),
+ }
+ print(json.dumps(output, indent=2))
+ else:
+ print_report(engine, quota=args.quota, current_quarter=args.quarter)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/cs-onboard/SKILL.md b/skills/c-level-advisor/cs-onboard/SKILL.md
new file mode 100644
index 00000000..3ad0c7fa
--- /dev/null
+++ b/skills/c-level-advisor/cs-onboard/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: "cs-onboard"
+description: "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: orchestration
+ updated: 2026-03-05
+ frameworks: founder-interview, context-capture, quarterly-refresh
+---
+
+# C-Suite Onboarding
+
+Structured founder interview that builds the company context file powering every C-suite advisor. One 45-minute conversation. Persistent context across all roles.
+
+## Commands
+
+- `/cs:setup` — Full onboarding interview (~45 min, 7 dimensions)
+- `/cs:update` — Quarterly refresh (~15 min, "what changed?")
+
+## Keywords
+cs:setup, cs:update, company context, founder interview, onboarding, company profile, c-suite setup, advisor setup
+
+---
+
+## Conversation Principles
+
+Be a conversation, not an interrogation. Ask one question at a time. Follow threads. Reflect back: "So the real issue sounds like X — is that right?" Watch for what they skip — that's where the real story lives. Never read a list of questions.
+
+Open with: *"Tell me about the company in your own words — what are you building and why does it matter?"*
+
+---
+
+## 7 Interview Dimensions
+
+### 1. Company Identity
+Capture: what they do, who it's for, the real founding "why," one-sentence pitch, non-negotiable values.
+Key probe: *"What's a value you'd fire someone over violating?"*
+Red flag: Values that sound like marketing copy.
+
+### 2. Stage & Scale
+Capture: headcount (FT vs contractors), revenue range, runway, stage (pre-PMF / scaling / optimizing), what broke in last 90 days.
+Key probe: *"If you had to label your stage — still finding PMF, scaling what works, or optimizing?"*
+
+### 3. Founder Profile
+Capture: self-identified superpower, acknowledged blind spots, archetype (product/sales/technical/operator), what actually keeps them up at night.
+Key probe: *"What would your co-founder say you should stop doing?"*
+Red flag: No blind spots, or weakness framed as a strength.
+
+### 4. Team & Culture
+Capture: team in 3 words, last real conflict and resolution, which values are real vs aspirational, strongest and weakest leader.
+Key probe: *"Which of your stated values is most real? Which is a poster on the wall?"*
+Red flag: "We have no conflict."
+
+### 5. Market & Competition
+Capture: who's winning and why (honest version), real unfair advantage, the one competitive move that could hurt them.
+Key probe: *"What's your real unfair advantage — not the investor version?"*
+Red flag: "We have no real competition."
+
+### 6. Current Challenges
+Capture: priority stack-rank across product/growth/people/money/operations, the decision they've been avoiding, the "one extra day" answer.
+Key probe: *"What's the decision you've been putting off for weeks?"*
+Note: The "extra day" answer reveals true priorities.
+
+### 7. Goals & Ambition
+Capture: 12-month target (specific), 36-month target (directional), exit vs build-forever orientation, personal success definition.
+Key probe: *"What does success look like for you personally — separate from the company?"*
+
+---
+
+## Output: company-context.md
+
+After the interview, generate `~/.claude/company-context.md` using `templates/company-context-template.md`.
+
+Fill every section. Write `[not captured]` for unknowns — never leave blank. Add timestamp, mark as `fresh`.
+
+Tell the founder: *"I've captured everything in your company context. Every advisor will use this to give specific, relevant advice. Run /cs:update in 90 days to keep it current."*
+
+---
+
+## /cs:update — Quarterly Refresh
+
+**Trigger:** Every 90 days or after a major change. Duration: ~15 minutes.
+
+Open with: *"It's been [X time] since we did your company context. What's changed?"*
+
+Walk each dimension with one "what changed?" question:
+1. Identity: same mission or shifted?
+2. Scale: team, revenue, runway now?
+3. Founder: role or what's stretching you?
+4. Team: any leadership changes?
+5. Market: any competitive surprises?
+6. Challenges: #1 problem now vs 90 days ago?
+7. Goals: still on track for 12-month target?
+
+Update the context file, refresh timestamp, reset to `fresh`.
+
+---
+
+## Context File Location
+
+`~/.claude/company-context.md` — single source of truth for all C-suite skills. Do not move it. Do not create duplicates.
+
+## References
+- `templates/company-context-template.md` — blank template for output
+- `references/interview-guide.md` — deep interview craft: probes, red flags, handling reluctant founders
diff --git a/skills/c-level-advisor/cs-onboard/references/interview-guide.md b/skills/c-level-advisor/cs-onboard/references/interview-guide.md
new file mode 100644
index 00000000..b81bf542
--- /dev/null
+++ b/skills/c-level-advisor/cs-onboard/references/interview-guide.md
@@ -0,0 +1,173 @@
+# Interview Craft Guide
+
+Deep operational guide for conducting the `/cs:setup` founder interview. Not a script — a thinking tool. Read before every interview. Internalize it, then put it away.
+
+---
+
+## The Core Problem
+
+Most context-gathering fails because it captures what founders say, not what they mean. Founders are practiced storytellers. They have investor pitches, board narratives, team rallies. They tell good stories. Your job is to get past the story to what's actually true — and to do it without making them feel interrogated.
+
+The best interview doesn't feel like an interview. It feels like a conversation with a smart advisor who gets it.
+
+---
+
+## Before You Start
+
+Set the frame:
+
+> "This isn't a quiz. There are no right answers. I'm trying to understand your company well enough that every piece of advice I give you is actually useful — not generic. The more honest you are, the more useful this gets. Nothing leaves this conversation."
+
+Then shut up and let them talk.
+
+---
+
+## Reading the Room
+
+Pay attention to:
+
+- **Energy shifts.** Where do they speed up? What makes them lean in? That's what they care about. What makes them vague or flat? That's where the real issue lives.
+- **What they lead with.** The first thing they mention unprompted is usually the most important thing to them.
+- **Repetition.** If a topic comes up twice, it's significant. Three times and it's the real problem.
+- **Hedging language.** "We're pretty much aligned on..." / "Things are mostly fine..." / "It's not really a problem yet..." — probe these. "Pretty much" is doing a lot of work there.
+- **Skips.** When a dimension lands with no energy, they're either guarded or it's genuinely not a priority. Figure out which.
+
+---
+
+## Follow-Up Probe Library
+
+### When the answer is vague
+
+- "Can you give me a specific example?"
+- "What does that look like on a Tuesday morning?"
+- "If I asked your co-founder / direct report, what would they say?"
+- "How would you know if that was actually true?"
+
+### When the answer is suspiciously polished
+
+- "That's the investor version — what's the version you'd tell your co-founder at 11pm?"
+- "If that's true, what explains [specific contradicting data point]?"
+- "What would a skeptic say about that?"
+
+### When they skip something
+
+- "You moved past [topic] quickly — is that because it's not a problem, or because it's too big to get into?"
+- "Come back to [topic] — tell me more about that."
+
+### When they say "everything is fine"
+
+- "What's the thing that keeps you up at night even though you know you shouldn't worry about it?"
+- "If something was going to surprise you in a bad way in the next 90 days, what would it be?"
+- "What would your board member who's most worried about the company say?"
+
+### When they're guarded
+
+- Slow down. Don't push harder — push softer.
+- "You don't have to share numbers if you're not comfortable — ranges are fine."
+- Acknowledge the complexity: "This stuff is genuinely hard to talk about."
+- Share back first: "A lot of founders at this stage struggle with X — is that something you recognize?"
+
+### When they go long
+
+Let them run for a bit. Then: "Let me make sure I captured what matters here — is it that [summary]?"
+It helps you confirm understanding and signals you're tracking.
+
+---
+
+## Red Flag Patterns and What to Do
+
+### "We have no real competition."
+**Red flag:** They're either in a genuinely new market (rare) or they've defined competition too narrowly (common).
+**Probe:** "What would someone do today if your product didn't exist? Who benefits if you fail?"
+
+### "Our values are X, Y, Z."
+**Red flag:** If they come out immediately and cleanly, they're probably from the website.
+**Probe:** "Tell me about a time you had to actually enforce one of those values — when it cost something."
+
+### "The team is great. Everyone's aligned."
+**Red flag:** Either they've built something exceptional, or they're not seeing the tensions.
+**Probe:** "What's the last thing you disagreed with someone on the team about? How did it go?"
+
+### "I don't really have blind spots."
+**Red flag:** Everyone has blind spots. Founders who can't name theirs are the most dangerous.
+**Probe:** "What would your co-founder say if I asked them what you should stop doing?"
+**Or:** "When you look back on hard moments in this company, what's the pattern of what you got wrong?"
+
+### "Revenue is good, things are growing."
+**Red flag:** "Good" is not a number.
+**Probe:** "Give me a range — is this $100K ARR, $1M, $10M? I'm not sharing it anywhere."
+
+### "We just need more customers."
+**Red flag:** This is almost never the root problem.
+**Probe:** "What's driving the growth you have? Why aren't more customers finding you, or converting, or staying?"
+
+---
+
+## Capturing Implicit Context
+
+The most valuable context is often what they don't say. Document it.
+
+**Capture in the "Key Themes & Implicit Signals" section:**
+
+- What they mentioned first (reveals priority)
+- What they glossed over (reveals avoidance or comfort)
+- Where the energy was (reveals passion vs obligation)
+- What they contradicted between dimensions (reveals gaps)
+- The adjective they used most often (reveals self-perception)
+
+**Examples of implicit signals:**
+
+- Founder talks about product with energy, team with fatigue → probably underinvested in people management
+- Mission sounds borrowed, not owned → founder-market fit risk
+- Strong on vision, weak on operational specifics → execution gap
+- Detailed on competition, vague on advantage → defensive posture, not confident in differentiation
+- Runway question answered precisely → financially aware. Answered vaguely → either worried or detached.
+
+---
+
+## Handling Reluctant Founders
+
+Some founders are guarded. Usually for one of three reasons:
+
+1. **They don't trust you yet.** Give it time. Ask easier questions first. Build rapport.
+2. **They're in denial.** Something is wrong and they're not ready to say it. Circles around topics, comes back to them.
+3. **They're protecting someone.** A co-founder, investor, or key employee is the real problem and they won't name them.
+
+**Tactics:**
+- Give them an out: "You don't have to answer this specifically — just give me the shape of it."
+- Normalize the problem: "A lot of founders at this stage are dealing with X..."
+- Ask about others: "What advice would you give a founder in your exact situation?"
+- Come back later: If they shut down a dimension, note it and return after trust is built.
+
+---
+
+## After the Interview
+
+Before generating the file:
+
+1. **Read back your notes.** Find the 3–5 most important things. They should be in the output.
+2. **Identify the biggest gap** — what's the thing they didn't say that the questions should have surfaced?
+3. **Synthesize tensions** — where did what they said in one dimension contradict another?
+4. **Write the Watch List** — what needs to be re-checked in 90 days?
+
+Then generate the context file. The last section — "Key Themes & Implicit Signals" — is the most important one. Don't skip it.
+
+---
+
+## Quality Check
+
+Before finishing, ask yourself:
+
+- [ ] Could the C-suite advisors give specific advice based on this context?
+- [ ] Does this capture what's real vs what's aspirational?
+- [ ] Is the Watch List honest about what's uncertain or worrying?
+- [ ] Does the founder profile feel like a real person, not a LinkedIn bio?
+- [ ] Did I capture implicit signals, not just explicit answers?
+
+If any answer is no, go back and fill it in.
+
+---
+
+## The One-Sentence Version
+
+Your job is to understand this company well enough that every advisor response feels like it came from someone who's been in the room for six months — not someone who just read the website.
diff --git a/skills/c-level-advisor/cs-onboard/templates/company-context-template.md b/skills/c-level-advisor/cs-onboard/templates/company-context-template.md
new file mode 100644
index 00000000..d16db588
--- /dev/null
+++ b/skills/c-level-advisor/cs-onboard/templates/company-context-template.md
@@ -0,0 +1,144 @@
+# Company Context
+
+**Last updated:** [DATE]
+**Status:** fresh | stale (>90 days)
+**Interview type:** full | update
+
+---
+
+## 1. Company Identity
+
+**What we do:**
+[One paragraph — product/service, who it's for, core use case]
+
+**Why we exist (founding reason):**
+[The real reason, not the pitch]
+
+**One-sentence pitch:**
+[Sharpened during interview]
+
+**Non-negotiable values:**
+- [Value 1] — [what would violate it]
+- [Value 2] — [what would violate it]
+- [Value 3] — [what would violate it]
+
+---
+
+## 2. Stage & Scale
+
+**Team size:** [N full-time] + [N contractors/part-time]
+**Revenue:** [ARR/MRR range, e.g., "$500K–$1M ARR"]
+**Runway:** [N months]
+**Stage:** pre-PMF | scaling | optimizing
+
+**What broke recently (last 90 days):**
+[Specific failure, cost, and root cause if known]
+
+---
+
+## 3. Founder Profile
+
+**Name / Role:**
+
+**Superpower:**
+[What they do better than almost anyone on their team]
+
+**Blind spots:**
+[Acknowledged or revealed — be specific]
+
+**Founder archetype:** product | sales | technical | operator
+
+**What keeps them up at night:**
+[The real concern, not the investor-safe version]
+
+---
+
+## 4. Team & Culture
+
+**Team in 3 words:** [word], [word], [word]
+
+**Culture — what's real:**
+[Which values are actually lived]
+
+**Culture — what's aspirational:**
+[Which values are poster-on-the-wall]
+
+**Strongest leader:**
+[Role / what makes them strong]
+
+**Weakest seat:**
+[Role / what the risk is]
+
+**Last significant conflict:**
+[What happened, how it resolved, what it revealed]
+
+---
+
+## 5. Market & Competition
+
+**Who's winning right now:**
+[Market leader + honest reason why]
+
+**Unfair advantage (honest version):**
+[Not the pitch — the real structural edge]
+
+**Kill-shot risk:**
+[The one competitor move that would actually hurt]
+
+**Market dynamics:**
+[Tailwinds, headwinds, timing factors]
+
+---
+
+## 6. Current Challenges
+
+**Priority stack-rank:**
+1. [Highest priority: product/growth/people/money/operations]
+2.
+3.
+4.
+5.
+
+**The avoided decision:**
+[What they've been putting off — and why]
+
+**The "one extra day" answer:**
+[What they'd actually work on — reveals true priority]
+
+---
+
+## 7. Goals & Ambition
+
+**12-month target:**
+[Specific — revenue, product milestone, market position]
+
+**36-month target:**
+[Directional — where does this company go]
+
+**Exit orientation:** building to exit | building to run | undecided
+
+**Personal success definition:**
+[Separate from company — what does winning look like for them personally]
+
+---
+
+## Key Themes & Implicit Signals
+
+**Patterns observed:**
+[What came up repeatedly, what they rushed past, emotional charge on topics]
+
+**Implicit tensions:**
+[Gaps between stated and revealed — e.g., "says people are fine, but conflict story suggests otherwise"]
+
+**Watch list:**
+[Things to check on in the next update — risks, avoided decisions, relationships to monitor]
+
+---
+
+## Context Metadata
+
+- **Interview conducted:** [DATE]
+- **Duration:** [N minutes]
+- **Interview type:** full | update
+- **Next refresh due:** [DATE + 90 days]
+- **Confidence level:** high | medium | low (low = founder was guarded)
diff --git a/skills/c-level-advisor/cto-advisor/SKILL.md b/skills/c-level-advisor/cto-advisor/SKILL.md
new file mode 100644
index 00000000..e53d04f8
--- /dev/null
+++ b/skills/c-level-advisor/cto-advisor/SKILL.md
@@ -0,0 +1,257 @@
+---
+name: "cto-advisor"
+description: "Technical leadership guidance for engineering teams, architecture decisions, and technology strategy. Use when assessing technical debt, scaling engineering teams, evaluating technologies, making architecture decisions, establishing engineering metrics, or when user mentions CTO, tech debt, technical debt, team scaling, architecture decisions, technology evaluation, engineering metrics, DORA metrics, or technology strategy."
+license: MIT
+metadata:
+ version: 2.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: cto-leadership
+ updated: 2026-03-05
+ python-tools: tech_debt_analyzer.py, team_scaling_calculator.py
+ frameworks: architecture-decisions, engineering-metrics, technology-evaluation
+---
+
+# CTO Advisor
+
+Technical leadership frameworks for architecture, engineering teams, technology strategy, and technical decision-making.
+
+## Keywords
+CTO, chief technology officer, tech debt, technical debt, architecture, engineering metrics, DORA, team scaling, technology evaluation, build vs buy, cloud migration, platform engineering, AI/ML strategy, system design, incident response, engineering culture
+
+## Quick Start
+
+```bash
+python scripts/tech_debt_analyzer.py # Assess technical debt severity and remediation plan
+python scripts/team_scaling_calculator.py # Model engineering team growth and cost
+```
+
+## Core Responsibilities
+
+### 1. Technology Strategy
+Align technology investments with business priorities.
+
+**Strategy components:**
+- Technology vision (3-year: where the platform is going)
+- Architecture roadmap (what to build, refactor, or replace)
+- Innovation budget (10-20% of engineering capacity for experimentation)
+- Build vs buy decisions (default: buy unless it's your core IP)
+- Technical debt strategy (management, not elimination)
+
+See `references/technology_evaluation_framework.md` for the full evaluation framework.
+
+### 2. Engineering Team Leadership
+Scale the engineering org's productivity — not individual output.
+
+**Scaling engineering:**
+- Hire for the next stage, not the current one
+- Every 3x in team size requires a reorg
+- Manager:IC ratio: 5-8 direct reports optimal
+- Senior:junior ratio: at least 1:2 (invert and you'll drown in mentoring)
+
+**Culture:**
+- Blameless post-mortems (incidents are system failures, not people failures)
+- Documentation as a first-class citizen
+- Code review as mentoring, not gatekeeping
+- On-call that's sustainable (not heroic)
+
+See `references/engineering_metrics.md` for DORA metrics and the engineering health dashboard.
+
+### 3. Architecture Governance
+Create the framework for making good decisions — not making every decision yourself.
+
+**Architecture Decision Records (ADRs):**
+- Every significant decision gets documented: context, options, decision, consequences
+- Decisions are discoverable (not buried in Slack)
+- Decisions can be superseded (not permanent)
+
+See `references/architecture_decision_records.md` for ADR templates and the decision review process.
+
+### 4. Vendor & Platform Management
+Every vendor is a dependency. Every dependency is a risk.
+
+**Evaluation criteria:** Does it solve a real problem? Can we migrate away? Is the vendor stable? What's the total cost (license + integration + maintenance)?
+
+### 5. Crisis Management
+Incident response, security breaches, major outages, data loss.
+
+**Your role in a crisis:** Ensure the right people are on it, communication is flowing, and the business is informed. Post-crisis: blameless retrospective within 48 hours.
+
+## Workflows
+
+### Tech Debt Assessment Workflow
+
+**Step 1 — Run the analyzer**
+```bash
+python scripts/tech_debt_analyzer.py --output report.json
+```
+
+**Step 2 — Interpret results**
+The analyzer produces a severity-scored inventory. Review each item against:
+- Severity (P0–P3): how much is it blocking velocity or creating risk?
+- Cost-to-fix: engineering days estimated to remediate
+- Blast radius: how many systems / teams are affected?
+
+**Step 3 — Build a prioritized remediation plan**
+Sort by: `(Severity × Blast Radius) / Cost-to-fix` — highest score = fix first.
+Group items into: (a) immediate sprint, (b) next quarter, (c) tracked backlog.
+
+**Step 4 — Validate before presenting to stakeholders**
+- [ ] Every P0/P1 item has an owner and a target date
+- [ ] Cost-to-fix estimates reviewed with the relevant tech lead
+- [ ] Debt ratio calculated: maintenance work / total engineering capacity (target: < 25%)
+- [ ] Remediation plan fits within capacity (don't promise 40 points of debt reduction in a 2-week sprint)
+
+**Example output — Tech Debt Inventory:**
+```
+Item | Severity | Cost-to-Fix | Blast Radius | Priority Score
+----------------------|----------|-------------|--------------|---------------
+Auth service (v1 API) | P1 | 8 days | 6 services | HIGH
+Unindexed DB queries | P2 | 3 days | 2 services | MEDIUM
+Legacy deploy scripts | P3 | 5 days | 1 service | LOW
+```
+
+---
+
+### ADR Creation Workflow
+
+**Step 1 — Identify the decision**
+Trigger an ADR when: the decision affects more than one team, is hard to reverse, or has cost/risk implications > 1 sprint of effort.
+
+**Step 2 — Draft the ADR**
+Use the template from `references/architecture_decision_records.md`:
+```
+Title: [Short noun phrase]
+Status: Proposed | Accepted | Superseded
+Context: What is the problem? What constraints exist?
+Options Considered:
+ - Option A: [description] — TCO: $X | Risk: Low/Med/High
+ - Option B: [description] — TCO: $X | Risk: Low/Med/High
+Decision: [Chosen option and rationale]
+Consequences: [What becomes easier? What becomes harder?]
+```
+
+**Step 3 — Validation checkpoint (before finalizing)**
+- [ ] All options include a 3-year TCO estimate
+- [ ] At least one "do nothing" or "buy" alternative is documented
+- [ ] Affected team leads have reviewed and signed off
+- [ ] Consequences section addresses reversibility and migration path
+- [ ] ADR is committed to the repository (not left in a doc or Slack thread)
+
+**Step 4 — Communicate and close**
+Share the accepted ADR in the engineering all-hands or architecture sync. Link it from the relevant service's README.
+
+---
+
+### Build vs Buy Analysis Workflow
+
+**Step 1 — Define requirements** (functional + non-functional)
+**Step 2 — Identify candidate vendors or internal build scope**
+**Step 3 — Score each option:**
+
+```
+Criterion | Weight | Build Score | Vendor A Score | Vendor B Score
+-----------------------|--------|-------------|----------------|---------------
+Solves core problem | 30% | 9 | 8 | 7
+Migration risk | 20% | 2 (low risk)| 7 | 6
+3-year TCO | 25% | $X | $Y | $Z
+Vendor stability | 15% | N/A | 8 | 5
+Integration effort | 10% | 3 | 7 | 8
+```
+
+**Step 4 — Default rule:** Buy unless it is core IP or no vendor meets ≥ 70% of requirements.
+**Step 5 — Document the decision as an ADR** (see ADR workflow above).
+
+## Key Questions a CTO Asks
+
+- "What's our biggest technical risk right now — not the most annoying, the most dangerous?"
+- "If we 10x our traffic tomorrow, what breaks first?"
+- "How much of our engineering time goes to maintenance vs new features?"
+- "What would a new engineer say about our codebase after their first week?"
+- "Which technical decision from 2 years ago is hurting us most today?"
+- "Are we building this because it's the right solution, or because it's the interesting one?"
+- "What's our bus factor on critical systems?"
+
+## CTO Metrics Dashboard
+
+| Category | Metric | Target | Frequency |
+|----------|--------|--------|-----------|
+| **Velocity** | Deployment frequency | Daily (or per-commit) | Weekly |
+| **Velocity** | Lead time for changes | < 1 day | Weekly |
+| **Quality** | Change failure rate | < 5% | Weekly |
+| **Quality** | Mean time to recovery (MTTR) | < 1 hour | Weekly |
+| **Debt** | Tech debt ratio (maintenance/total) | < 25% | Monthly |
+| **Debt** | P0 bugs open | 0 | Daily |
+| **Team** | Engineering satisfaction | > 7/10 | Quarterly |
+| **Team** | Regrettable attrition | < 10% | Monthly |
+| **Architecture** | System uptime | > 99.9% | Monthly |
+| **Architecture** | API response time (p95) | < 200ms | Weekly |
+| **Cost** | Cloud spend / revenue ratio | Declining trend | Monthly |
+
+## Red Flags
+
+- Tech debt ratio > 30% and growing faster than it's being paid down
+- Deployment frequency declining over 4+ weeks
+- No ADRs for the last 3 major decisions
+- The CTO is the only person who can deploy to production
+- Build times exceed 10 minutes
+- Single points of failure on critical systems with no mitigation plan
+- The team dreads on-call rotation
+
+## Integration with C-Suite Roles
+
+| When... | CTO works with... | To... |
+|---------|-------------------|-------|
+| Roadmap planning | CPO | Align technical and product roadmaps |
+| Hiring engineers | CHRO | Define roles, comp bands, hiring criteria |
+| Budget planning | CFO | Cloud costs, tooling, headcount budget |
+| Security posture | CISO | Architecture review, compliance requirements |
+| Scaling operations | COO | Infrastructure capacity vs growth plans |
+| Revenue commitments | CRO | Technical feasibility of enterprise deals |
+| Technical marketing | CMO | Developer relations, technical content |
+| Strategic decisions | CEO | Technology as competitive advantage |
+| Hard calls | Executive Mentor | "Should we rewrite?" "Should we switch stacks?" |
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Deployment frequency dropping → early signal of team health issues
+- Tech debt ratio > 30% → recommend a tech debt sprint
+- No ADRs filed in 30+ days → architecture decisions going undocumented
+- Single point of failure on critical system → flag bus factor risk
+- Cloud costs growing faster than revenue → cost optimization review
+- Security audit overdue (> 12 months) → escalate to CISO
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Assess our tech debt" | Tech debt inventory with severity, cost-to-fix, and prioritized plan |
+| "Should we build or buy X?" | Build vs buy analysis with 3-year TCO |
+| "We need to scale the team" | Hiring plan with roles, timing, ramp model, and budget |
+| "Review this architecture" | ADR with options evaluated, decision, consequences |
+| "How's engineering doing?" | Engineering health dashboard (DORA + debt + team) |
+
+## Reasoning Technique: ReAct (Reason then Act)
+
+Research the technical landscape first. Analyze options against constraints (time, team skill, cost, risk). Then recommend action. Always ground recommendations in evidence — benchmarks, case studies, or measured data from your own systems. "I think" is not enough — show the data.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
+
+## Resources
+- `references/technology_evaluation_framework.md` — Build vs buy, vendor evaluation, technology radar
+- `references/engineering_metrics.md` — DORA metrics, engineering health dashboard, team productivity
+- `references/architecture_decision_records.md` — ADR templates, decision governance, review process
diff --git a/skills/c-level-advisor/cto-advisor/references/architecture_decision_records.md b/skills/c-level-advisor/cto-advisor/references/architecture_decision_records.md
new file mode 100644
index 00000000..23bc7564
--- /dev/null
+++ b/skills/c-level-advisor/cto-advisor/references/architecture_decision_records.md
@@ -0,0 +1,294 @@
+# Architecture Decision Records (ADR) Framework
+
+## What is an ADR?
+
+Architecture Decision Records capture important architectural decisions made along with their context and consequences. They help maintain institutional knowledge and explain why systems are built the way they are.
+
+## ADR Template
+
+### ADR-[NUMBER]: [TITLE]
+
+**Date**: YYYY-MM-DD
+**Status**: [Proposed | Accepted | Deprecated | Superseded]
+**Deciders**: [List of people involved in decision]
+**Technical Story**: [Ticket/Issue reference]
+
+#### Context and Problem Statement
+
+[Describe the context and problem that needs to be solved. What are we trying to achieve?]
+
+#### Decision Drivers
+
+- [Driver 1: e.g., Performance requirements]
+- [Driver 2: e.g., Time to market]
+- [Driver 3: e.g., Team expertise]
+- [Driver 4: e.g., Cost constraints]
+
+#### Considered Options
+
+1. **Option 1: [Name]**
+2. **Option 2: [Name]**
+3. **Option 3: [Name]**
+
+#### Decision Outcome
+
+**Chosen option**: "[Option Name]", because [justification]
+
+##### Positive Consequences
+- [Consequence 1]
+- [Consequence 2]
+
+##### Negative Consequences
+- [Risk 1 and mitigation]
+- [Risk 2 and mitigation]
+
+#### Pros and Cons of Options
+
+##### Option 1: [Name]
+- **Pros**:
+ - [Advantage 1]
+ - [Advantage 2]
+- **Cons**:
+ - [Disadvantage 1]
+ - [Disadvantage 2]
+
+##### Option 2: [Name]
+[Repeat structure]
+
+#### Links
+- [Related ADRs]
+- [Documentation]
+- [Research/PoCs]
+
+---
+
+## Example ADRs
+
+### ADR-001: Microservices Architecture
+
+**Date**: 2024-01-15
+**Status**: Accepted
+**Deciders**: CTO, VP Engineering, Tech Leads
+**Technical Story**: ARCH-001
+
+#### Context and Problem Statement
+
+Our monolithic application is becoming difficult to scale and deploy. Different teams are stepping on each other's toes, and deployment cycles are getting longer. We need to decide on our architectural approach for the next 3-5 years.
+
+#### Decision Drivers
+
+- Need for independent team deployment
+- Requirement to scale different components independently
+- Different components have different performance characteristics
+- Team size growing from 25 to 75+ engineers
+- Need to support multiple technology stacks
+
+#### Considered Options
+
+1. **Keep Monolith**: Continue with current architecture
+2. **Modular Monolith**: Break into modules but single deployment
+3. **Microservices**: Full service-oriented architecture
+4. **Serverless**: Function-as-a-Service approach
+
+#### Decision Outcome
+
+**Chosen option**: "Microservices", because it best supports our team autonomy needs and scaling requirements, despite added complexity.
+
+##### Positive Consequences
+- Teams can deploy independently
+- Services can scale based on individual needs
+- Technology diversity is possible
+- Fault isolation improved
+
+##### Negative Consequences
+- Increased operational complexity - Mitigated by investing in DevOps
+- Network latency between services - Mitigated by careful service boundaries
+- Data consistency challenges - Mitigated by event sourcing patterns
+
+---
+
+### ADR-002: Container Orchestration Platform
+
+**Date**: 2024-02-01
+**Status**: Accepted
+**Deciders**: CTO, DevOps Lead, Platform Team
+**Technical Story**: INFRA-045
+
+#### Context and Problem Statement
+
+With the move to microservices (ADR-001), we need a container orchestration platform to manage deployment, scaling, and operations of application containers.
+
+#### Decision Drivers
+
+- Need for automated deployment and scaling
+- High availability requirements (99.9% SLA)
+- Multi-cloud strategy (avoid vendor lock-in)
+- Team familiarity and ecosystem maturity
+- Cost considerations
+
+#### Considered Options
+
+1. **Kubernetes**: Industry standard, self-managed
+2. **Amazon ECS**: AWS-native solution
+3. **Docker Swarm**: Simpler alternative
+4. **Nomad**: HashiCorp solution
+
+#### Decision Outcome
+
+**Chosen option**: "Kubernetes", because of its maturity, ecosystem, and multi-cloud support.
+
+##### Positive Consequences
+- Industry standard with huge ecosystem
+- Multi-cloud compatible
+- Strong community support
+- Extensive tooling available
+
+##### Negative Consequences
+- Steep learning curve - Mitigated by training and hiring
+- Operational complexity - Mitigated by managed Kubernetes (EKS/GKE)
+
+---
+
+### ADR-003: API Gateway Strategy
+
+**Date**: 2024-03-15
+**Status**: Accepted
+**Deciders**: CTO, Security Lead, API Team
+**Technical Story**: API-101
+
+#### Context and Problem Statement
+
+With multiple microservices, we need a unified entry point for external clients that handles cross-cutting concerns like authentication, rate limiting, and monitoring.
+
+#### Decision Drivers
+
+- Security requirements (OAuth2, API keys)
+- Need for rate limiting and throttling
+- Monitoring and analytics requirements
+- Developer experience for API consumers
+- Performance (sub-100ms overhead)
+
+#### Considered Options
+
+1. **Kong**: Open-source, plugin ecosystem
+2. **AWS API Gateway**: Managed service
+3. **Istio/Envoy**: Service mesh approach
+4. **Build Custom**: In-house solution
+
+#### Decision Outcome
+
+**Chosen option**: "Kong", because of its flexibility and plugin ecosystem while avoiding vendor lock-in.
+
+---
+
+## Common Architecture Decisions
+
+### 1. Frontend Architecture
+- **Single Page Application (SPA)** vs **Server-Side Rendering (SSR)** vs **Static Site Generation (SSG)**
+- **React** vs **Vue** vs **Angular** vs **Svelte**
+- **Monorepo** vs **Polyrepo**
+- **Micro-frontends** vs **Monolithic frontend**
+
+### 2. Backend Architecture
+- **Monolith** vs **Microservices** vs **Serverless**
+- **REST** vs **GraphQL** vs **gRPC**
+- **Synchronous** vs **Asynchronous** communication
+- **Event-driven** vs **Request-response**
+
+### 3. Data Architecture
+- **SQL** vs **NoSQL** vs **NewSQL**
+- **Single database** vs **Database per service**
+- **CQRS** vs **Traditional CRUD**
+- **Event Sourcing** vs **State-based storage**
+
+### 4. Infrastructure Decisions
+- **Cloud provider**: AWS vs Azure vs GCP vs Multi-cloud
+- **Containers** vs **VMs** vs **Serverless**
+- **Kubernetes** vs **ECS** vs **Cloud Run**
+- **Self-hosted** vs **Managed services**
+
+### 5. Development Practices
+- **Continuous Deployment** vs **Continuous Delivery**
+- **Feature flags** vs **Branch-based deployment**
+- **Blue-green** vs **Canary** vs **Rolling deployment**
+- **GitFlow** vs **GitHub Flow** vs **GitLab Flow**
+
+## ADR Best Practices
+
+### Writing Good ADRs
+
+1. **Keep them short**: 1-2 pages maximum
+2. **Be specific**: Include concrete examples
+3. **Document why, not what**: Focus on reasoning
+4. **Include all options**: Even obviously bad ones
+5. **Be honest about drawbacks**: Every decision has trade-offs
+
+### When to Write ADRs
+
+Write an ADR when:
+- The decision has significant impact
+- Multiple options were seriously considered
+- The decision is hard to reverse
+- You find yourself explaining the same decision repeatedly
+- There's disagreement about the approach
+
+### ADR Lifecycle
+
+1. **Proposed**: Under discussion
+2. **Accepted**: Decision made and being implemented
+3. **Deprecated**: No longer relevant but kept for history
+4. **Superseded**: Replaced by another ADR
+
+### Storage and Discovery
+
+- Store ADRs in your main repository under `docs/architecture/decisions/`
+- Use consistent numbering (ADR-001, ADR-002, etc.)
+- Create an index file linking all ADRs
+- Reference ADRs in code comments where relevant
+- Review ADRs regularly (quarterly) for relevance
+
+## Decision Evaluation Framework
+
+### Technical Factors (40%)
+- Performance impact
+- Scalability potential
+- Security implications
+- Maintainability
+- Technical debt
+
+### Business Factors (30%)
+- Time to market
+- Cost (initial and ongoing)
+- Revenue impact
+- Competitive advantage
+- Regulatory compliance
+
+### Team Factors (30%)
+- Current expertise
+- Learning curve
+- Hiring availability
+- Team preference
+- Training requirements
+
+## Anti-patterns to Avoid
+
+1. **Decision by Committee**: Too many stakeholders leading to compromise solutions
+2. **Analysis Paralysis**: Over-analyzing instead of deciding
+3. **Resume-Driven Development**: Choosing tech for personal goals
+4. **Hype-Driven Development**: Choosing the newest/coolest tech
+5. **Not-Invented-Here**: Rejecting external solutions by default
+6. **Vendor Lock-in**: Over-dependence on proprietary solutions
+7. **Premature Optimization**: Solving problems you don't have yet
+8. **Under-documentation**: Not capturing the "why" behind decisions
+
+## Review Checklist
+
+Before finalizing an ADR, ensure:
+- [ ] Problem is clearly stated
+- [ ] All realistic options are considered
+- [ ] Trade-offs are honestly evaluated
+- [ ] Decision rationale is clear
+- [ ] Consequences are identified
+- [ ] Mitigation strategies are defined
+- [ ] Success metrics are established
+- [ ] Review date is set (if applicable)
diff --git a/skills/c-level-advisor/cto-advisor/references/engineering_metrics.md b/skills/c-level-advisor/cto-advisor/references/engineering_metrics.md
new file mode 100644
index 00000000..f85f0569
--- /dev/null
+++ b/skills/c-level-advisor/cto-advisor/references/engineering_metrics.md
@@ -0,0 +1,393 @@
+# Engineering Metrics & KPIs Guide
+
+## Metrics Framework
+
+### DORA Metrics (DevOps Research and Assessment)
+
+#### 1. Deployment Frequency
+- **Definition**: How often code is deployed to production
+- **Target**:
+ - Elite: Multiple deploys per day
+ - High: Weekly to monthly
+ - Medium: Monthly to bi-annually
+ - Low: Less than bi-annually
+- **Measurement**: Deployments per day/week/month
+- **Improvement**: Smaller batch sizes, feature flags, CI/CD
+
+#### 2. Lead Time for Changes
+- **Definition**: Time from code commit to production
+- **Target**:
+ - Elite: Less than 1 hour
+ - High: 1 day to 1 week
+ - Medium: 1 week to 1 month
+ - Low: More than 1 month
+- **Measurement**: Median time from commit to deploy
+- **Improvement**: Automation, parallel testing, smaller changes
+
+#### 3. Mean Time to Recovery (MTTR)
+- **Definition**: Time to restore service after incident
+- **Target**:
+ - Elite: Less than 1 hour
+ - High: Less than 1 day
+ - Medium: 1 day to 1 week
+ - Low: More than 1 week
+- **Measurement**: Average incident resolution time
+- **Improvement**: Monitoring, rollback capability, runbooks
+
+#### 4. Change Failure Rate
+- **Definition**: Percentage of changes causing failures
+- **Target**:
+ - Elite: 0-15%
+ - High: 16-30%
+ - Medium/Low: >30%
+- **Measurement**: Failed deploys / Total deploys
+- **Improvement**: Testing, code review, gradual rollouts
+
+### Engineering Productivity Metrics
+
+#### Code Quality
+| Metric | Formula | Target | Action if Below |
+|--------|---------|--------|-----------------|
+| Test Coverage | Tests / Total Code | >80% | Add unit tests |
+| Code Review Coverage | Reviewed PRs / Total PRs | 100% | Enforce review policy |
+| Technical Debt Ratio | Debt / Development Time | <10% | Dedicate debt sprints |
+| Cyclomatic Complexity | Per function/method | <10 | Refactor complex code |
+| Code Duplication | Duplicate Lines / Total | <5% | Extract common code |
+
+#### Development Velocity
+| Metric | Formula | Target | Action if Below |
+|--------|---------|--------|-----------------|
+| Sprint Velocity | Story Points / Sprint | Stable ±10% | Review estimation |
+| Cycle Time | Start to Done Time | <5 days | Reduce WIP |
+| PR Merge Time | Open to Merge | <24 hours | Smaller PRs |
+| Build Time | Code to Artifact | <10 minutes | Optimize pipeline |
+| Test Execution Time | Full Test Suite | <30 minutes | Parallelize tests |
+
+#### Team Health
+| Metric | Formula | Target | Action if Below |
+|--------|---------|--------|-----------------|
+| On-call Incidents | Incidents / Week | <5 | Improve monitoring |
+| Bug Escape Rate | Prod Bugs / Release | <5% | Improve testing |
+| Unplanned Work | Unplanned / Total | <20% | Better planning |
+| Meeting Time | Meetings / Total Time | <20% | Reduce meetings |
+| Focus Time | Uninterrupted Hours | >4h/day | Block calendars |
+
+### Business Impact Metrics
+
+#### System Performance
+| Metric | Description | Target | Business Impact |
+|--------|-------------|--------|-----------------|
+| Uptime | System availability | 99.9%+ | Revenue protection |
+| Page Load Time | Time to interactive | <3s | User retention |
+| API Response Time | P95 latency | <200ms | User experience |
+| Error Rate | Errors / Requests | <0.1% | Customer satisfaction |
+| Throughput | Requests / Second | Per requirement | Scalability |
+
+#### Product Delivery
+| Metric | Description | Target | Business Impact |
+|--------|-------------|--------|-----------------|
+| Feature Delivery Rate | Features / Quarter | Per roadmap | Market competitiveness |
+| Time to Market | Idea to Production | <3 months | First mover advantage |
+| Customer Defect Rate | Customer Bugs / Month | <10 | Customer satisfaction |
+| Feature Adoption | Users / Feature | >50% | ROI validation |
+| NPS from Engineering | Customer Score | >50 | Product quality |
+
+## Metrics Dashboards
+
+### Executive Dashboard (Weekly)
+```
+┌─────────────────────────────────────┐
+│ EXECUTIVE METRICS │
+├─────────────────────────────────────┤
+│ Uptime: 99.97% ✓ │
+│ Sprint Velocity: 142 pts ✓ │
+│ Deployment Frequency: 3.2/day ✓ │
+│ Lead Time: 4.2 hrs ✓ │
+│ MTTR: 47 min ✓ │
+│ Change Failure Rate: 8.3% ✓ │
+│ │
+│ Team Health: 8.2/10 │
+│ Tech Debt Ratio: 12% ⚠ │
+│ Feature Delivery: 85% ✓ │
+└─────────────────────────────────────┘
+```
+
+### Team Dashboard (Daily)
+```
+┌─────────────────────────────────────┐
+│ TEAM METRICS │
+├─────────────────────────────────────┤
+│ Current Sprint: │
+│ Completed: 65/100 pts (65%) │
+│ In Progress: 20 pts │
+│ Days Left: 3 │
+│ │
+│ PR Queue: 8 pending │
+│ Build Status: ✓ Passing │
+│ Test Coverage: 82.3% │
+│ Open Incidents: 2 (P2, P3) │
+│ │
+│ On-call Load: 3 pages this week │
+└─────────────────────────────────────┘
+```
+
+### Individual Dashboard (Daily)
+```
+┌─────────────────────────────────────┐
+│ DEVELOPER METRICS │
+├─────────────────────────────────────┤
+│ This Week: │
+│ PRs Merged: 8 │
+│ Code Reviews: 12 │
+│ Commits: 23 │
+│ Focus Time: 22.5 hrs │
+│ │
+│ Quality: │
+│ Test Coverage: 87% │
+│ Code Review Feedback: 95% ✓ │
+│ Bug Introduction Rate: 0% │
+└─────────────────────────────────────┘
+```
+
+## Implementation Guide
+
+### Phase 1: Foundation (Month 1)
+1. **Basic Metrics**
+ - Deployment frequency
+ - Build success rate
+ - Uptime/availability
+ - Team velocity
+
+2. **Tools Setup**
+ - CI/CD instrumentation
+ - Basic monitoring
+ - Time tracking
+
+### Phase 2: Quality (Month 2)
+1. **Quality Metrics**
+ - Test coverage
+ - Code review metrics
+ - Bug rates
+ - Technical debt
+
+2. **Tool Integration**
+ - Static analysis
+ - Test reporting
+ - Code quality gates
+
+### Phase 3: Performance (Month 3)
+1. **Performance Metrics**
+ - DORA metrics complete
+ - System performance
+ - API metrics
+ - Database metrics
+
+2. **Advanced Monitoring**
+ - APM tools
+ - Distributed tracing
+ - Custom dashboards
+
+### Phase 4: Optimization (Ongoing)
+1. **Advanced Analytics**
+ - Predictive metrics
+ - Trend analysis
+ - Anomaly detection
+ - Correlation analysis
+
+## Metric Anti-patterns
+
+### What NOT to Measure
+
+❌ **Lines of Code**: Encourages bloat
+❌ **Hours Worked**: Promotes presenteeism
+❌ **Individual Velocity**: Creates competition
+❌ **Bug Count Without Context**: Discourages risk-taking
+❌ **Commit Count**: Encourages tiny commits
+
+### Goodhart's Law
+"When a measure becomes a target, it ceases to be a good measure"
+
+**Examples**:
+- Optimizing test coverage → Writing meaningless tests
+- Reducing bug count → Not reporting bugs
+- Increasing velocity → Inflating estimates
+- Reducing meeting time → Skipping important discussions
+
+### How to Avoid Gaming
+
+1. **Use Multiple Metrics**: No single metric tells the whole story
+2. **Focus on Trends**: Not absolute numbers
+3. **Combine Leading and Lagging**: Balance predictive and historical
+4. **Regular Review**: Adjust metrics that are being gamed
+5. **Team Ownership**: Let teams choose their metrics
+
+## OKR Framework for Engineering
+
+### Company Level OKRs
+**Objective**: Deliver exceptional product quality
+
+**Key Results**:
+- KR1: Achieve 99.95% uptime (from 99.9%)
+- KR2: Reduce customer-reported bugs by 50%
+- KR3: Improve deployment frequency to 10x/day
+
+### Engineering OKRs
+**Objective**: Build scalable, reliable infrastructure
+
+**Key Results**:
+- KR1: Migrate 80% of services to Kubernetes
+- KR2: Reduce MTTR to <30 minutes
+- KR3: Achieve 85% test coverage
+
+### Team OKRs
+**Objective**: Improve developer productivity
+
+**Key Results**:
+- KR1: Reduce build time to <5 minutes
+- KR2: Automate 90% of deployment process
+- KR3: Reduce PR review time to <4 hours
+
+## Reporting Templates
+
+### Monthly Engineering Report
+
+```markdown
+# Engineering Report - [Month Year]
+
+## Executive Summary
+- Key Achievement: [Highlight]
+- Main Challenge: [Issue and resolution]
+- Next Month Focus: [Priority]
+
+## DORA Metrics
+| Metric | This Month | Last Month | Target | Status |
+|--------|------------|------------|--------|--------|
+| Deploy Frequency | X/day | Y/day | Z/day | ✓/⚠/✗ |
+| Lead Time | X hrs | Y hrs | 8/10
+✓ Attrition <10% annually
+✓ On-time delivery >80%
+✓ Technical debt <15% of capacity
+✓ Innovation time >20%
+
+### Warning Signs
+⚠️ Increasing MTTR trend
+⚠️ Declining velocity
+⚠️ Rising bug escape rate
+⚠️ Increasing unplanned work
+⚠️ Growing PR queue
+⚠️ Decreasing test coverage
+
+### Crisis Indicators
+🚨 Multiple production incidents per week
+🚨 Team satisfaction <6/10
+🚨 Attrition >20%
+🚨 Technical debt >30%
+🚨 No deployments for >1 week
+🚨 Customer escalations increasing
diff --git a/skills/c-level-advisor/cto-advisor/references/technology_evaluation_framework.md b/skills/c-level-advisor/cto-advisor/references/technology_evaluation_framework.md
new file mode 100644
index 00000000..2cebd112
--- /dev/null
+++ b/skills/c-level-advisor/cto-advisor/references/technology_evaluation_framework.md
@@ -0,0 +1,370 @@
+# Technology Evaluation Framework
+
+## Evaluation Process
+
+### Phase 1: Requirements Gathering (Week 1)
+
+#### Functional Requirements
+- Core features needed
+- Integration requirements
+- Performance requirements
+- Scalability needs
+- Security requirements
+
+#### Non-Functional Requirements
+- Usability/Developer experience
+- Documentation quality
+- Community support
+- Vendor stability
+- Compliance needs
+
+#### Constraints
+- Budget limitations
+- Timeline constraints
+- Team expertise
+- Existing technology stack
+- Regulatory requirements
+
+### Phase 2: Market Research (Week 1-2)
+
+#### Identify Candidates
+1. Industry leaders (Gartner Magic Quadrant)
+2. Open-source alternatives
+3. Emerging solutions
+4. Build vs Buy analysis
+
+#### Initial Filtering
+- Eliminate options not meeting hard requirements
+- Remove options outside budget
+- Focus on 3-5 top candidates
+
+### Phase 3: Deep Evaluation (Week 2-4)
+
+#### Technical Evaluation
+- Proof of Concept (PoC)
+- Performance benchmarks
+- Security assessment
+- Integration testing
+- Scalability testing
+
+#### Business Evaluation
+- Total Cost of Ownership (TCO)
+- Return on Investment (ROI)
+- Vendor assessment
+- Risk analysis
+- Exit strategy
+
+### Phase 4: Decision (Week 4)
+
+## Evaluation Criteria Matrix
+
+### Technical Criteria (40%)
+
+| Criterion | Weight | Description | Scoring Guide |
+|-----------|--------|-------------|---------------|
+| **Performance** | 10% | Speed, throughput, latency | 5: Exceeds requirements 3: Meets requirements 1: Below requirements |
+| **Scalability** | 10% | Ability to grow with needs | 5: Linear scalability 3: Some limitations 1: Hard limits |
+| **Reliability** | 8% | Uptime, fault tolerance | 5: 99.99% SLA 3: 99.9% SLA 1: <99% SLA |
+| **Security** | 8% | Security features, compliance | 5: Exceeds standards 3: Meets standards 1: Concerns exist |
+| **Integration** | 4% | API quality, compatibility | 5: Native integration 3: Good APIs 1: Limited integration |
+
+### Business Criteria (30%)
+
+| Criterion | Weight | Description | Scoring Guide |
+|-----------|--------|-------------|---------------|
+| **Cost** | 10% | TCO including licenses, operation | 5: Under budget by >20% 3: Within budget 1: Over budget |
+| **ROI** | 8% | Value generation potential | 5: <6 month payback 3: <12 month payback 1: >24 month payback |
+| **Vendor Stability** | 6% | Financial health, market position | 5: Market leader 3: Established player 1: Startup/uncertain |
+| **Support Quality** | 6% | Support availability, SLAs | 5: 24/7 premium support 3: Business hours 1: Community only |
+
+### Operational Criteria (30%)
+
+| Criterion | Weight | Description | Scoring Guide |
+|-----------|--------|-------------|---------------|
+| **Ease of Use** | 8% | Learning curve, UX | 5: Intuitive 3: Moderate learning 1: Steep curve |
+| **Documentation** | 7% | Quality, completeness | 5: Excellent docs 3: Adequate docs 1: Poor docs |
+| **Community** | 7% | Size, activity, resources | 5: Large, active 3: Moderate 1: Small/inactive |
+| **Maintenance** | 8% | Operational overhead | 5: Fully managed 3: Some maintenance 1: High maintenance |
+
+## Vendor Evaluation Template
+
+### Vendor Profile
+- **Company Name**:
+- **Founded**:
+- **Headquarters**:
+- **Employees**:
+- **Revenue**:
+- **Funding** (if applicable):
+- **Key Customers**:
+
+### Product Assessment
+
+#### Strengths
+- [ ] Market leader position
+- [ ] Strong feature set
+- [ ] Good performance
+- [ ] Excellent support
+- [ ] Active development
+
+#### Weaknesses
+- [ ] Price point
+- [ ] Learning curve
+- [ ] Limited customization
+- [ ] Vendor lock-in
+- [ ] Missing features
+
+#### Opportunities
+- [ ] Roadmap alignment
+- [ ] Partnership potential
+- [ ] Training availability
+- [ ] Professional services
+
+#### Threats
+- [ ] Competitive alternatives
+- [ ] Market changes
+- [ ] Technology shifts
+- [ ] Acquisition risk
+
+### Financial Analysis
+
+#### Cost Breakdown
+| Component | Year 1 | Year 2 | Year 3 | Total |
+|-----------|--------|--------|--------|-------|
+| Licensing | $ | $ | $ | $ |
+| Implementation | $ | $ | $ | $ |
+| Training | $ | $ | $ | $ |
+| Support | $ | $ | $ | $ |
+| Infrastructure | $ | $ | $ | $ |
+| **Total** | **$** | **$** | **$** | **$** |
+
+#### ROI Calculation
+- **Cost Savings**:
+ - Reduced manual work: $/year
+ - Efficiency gains: $/year
+ - Error reduction: $/year
+- **Revenue Impact**:
+ - New capabilities: $/year
+ - Faster time to market: $/year
+- **Payback Period**: X months
+
+### Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| Vendor goes out of business | Low/Med/High | Low/Med/High | Strategy |
+| Technology becomes obsolete | | | |
+| Integration difficulties | | | |
+| Team adoption challenges | | | |
+| Budget overrun | | | |
+| Performance issues | | | |
+
+## Build vs Buy Decision Framework
+
+### When to Build
+
+**Advantages**:
+- Full control over features
+- No vendor lock-in
+- Potential competitive advantage
+- Perfect fit for requirements
+- No licensing costs
+
+**Build when**:
+- Core business differentiator
+- Unique requirements
+- Long-term investment
+- Have expertise in-house
+- No suitable solutions exist
+
+**Hidden Costs**:
+- Development time
+- Maintenance burden
+- Security responsibility
+- Documentation needs
+- Training requirements
+
+### When to Buy
+
+**Advantages**:
+- Faster time to market
+- Proven solution
+- Vendor support
+- Regular updates
+- Shared development costs
+
+**Buy when**:
+- Commodity functionality
+- Standard requirements
+- Limited internal resources
+- Need quick solution
+- Good options available
+
+**Hidden Costs**:
+- Customization limits
+- Vendor lock-in
+- Integration effort
+- Training needs
+- Scaling costs
+
+### When to Adopt Open Source
+
+**Advantages**:
+- No licensing costs
+- Community support
+- Transparency
+- Customizable
+- No vendor lock-in
+
+**Adopt when**:
+- Strong community exists
+- Standard solution needed
+- Have technical expertise
+- Can contribute back
+- Long-term stability needed
+
+**Hidden Costs**:
+- Support costs
+- Security responsibility
+- Upgrade management
+- Integration effort
+- Potential consulting needs
+
+## Proof of Concept Guidelines
+
+### PoC Scope
+1. **Duration**: 2-4 weeks
+2. **Team**: 2-3 engineers
+3. **Environment**: Isolated/sandbox
+4. **Data**: Representative sample
+
+### Success Criteria
+- [ ] Core use cases demonstrated
+- [ ] Performance benchmarks met
+- [ ] Integration points tested
+- [ ] Security requirements validated
+- [ ] Team feedback positive
+
+### PoC Checklist
+- [ ] Environment setup documented
+- [ ] Test scenarios defined
+- [ ] Metrics collection automated
+- [ ] Team training completed
+- [ ] Results documented
+
+### PoC Report Template
+
+```markdown
+# PoC Report: [Technology Name]
+
+## Executive Summary
+- **Recommendation**: [Proceed/Stop/Investigate Further]
+- **Confidence Level**: [High/Medium/Low]
+- **Key Finding**: [One sentence summary]
+
+## Test Results
+
+### Functional Tests
+| Test Case | Result | Notes |
+|-----------|--------|-------|
+| | Pass/Fail | |
+
+### Performance Tests
+| Metric | Target | Actual | Status |
+|--------|--------|--------|---------|
+| Response Time | <100ms | Xms | ✓/✗ |
+| Throughput | >1000 req/s | X req/s | ✓/✗ |
+| CPU Usage | <70% | X% | ✓/✗ |
+| Memory Usage | <4GB | XGB | ✓/✗ |
+
+### Integration Tests
+| System | Status | Effort |
+|--------|--------|--------|
+| Database | ✓/✗ | Low/Med/High |
+| API Gateway | ✓/✗ | Low/Med/High |
+| Authentication | ✓/✗ | Low/Med/High |
+
+## Team Feedback
+- **Ease of Use**: [1-5 rating]
+- **Documentation**: [1-5 rating]
+- **Would Recommend**: [Yes/No]
+
+## Risks Identified
+1. [Risk and mitigation]
+2. [Risk and mitigation]
+
+## Next Steps
+1. [Action item]
+2. [Action item]
+```
+
+## Technology Categories
+
+### Development Platforms
+- **Languages**: TypeScript, Python, Go, Rust, Java
+- **Frameworks**: React, Node.js, Spring, Django, FastAPI
+- **Mobile**: React Native, Flutter, Swift, Kotlin
+- **Evaluation Focus**: Developer productivity, ecosystem, performance
+
+### Databases
+- **SQL**: PostgreSQL, MySQL, SQL Server
+- **NoSQL**: MongoDB, Cassandra, DynamoDB
+- **NewSQL**: CockroachDB, Vitess, TiDB
+- **Evaluation Focus**: Performance, scalability, consistency, operations
+
+### Infrastructure
+- **Cloud**: AWS, GCP, Azure
+- **Containers**: Docker, Kubernetes, Nomad
+- **Serverless**: Lambda, Cloud Functions, Vercel
+- **Evaluation Focus**: Cost, scalability, vendor lock-in, operations
+
+### Monitoring & Observability
+- **APM**: DataDog, New Relic, AppDynamics
+- **Logging**: ELK Stack, Splunk, CloudWatch
+- **Metrics**: Prometheus, Grafana, CloudWatch
+- **Evaluation Focus**: Coverage, cost, integration, insights
+
+### Security
+- **SAST**: Sonarqube, Checkmarx, Veracode
+- **DAST**: OWASP ZAP, Burp Suite
+- **Secrets**: Vault, AWS Secrets Manager
+- **Evaluation Focus**: Coverage, false positives, integration
+
+### DevOps Tools
+- **CI/CD**: Jenkins, GitLab CI, GitHub Actions
+- **IaC**: Terraform, CloudFormation, Pulumi
+- **Configuration**: Ansible, Chef, Puppet
+- **Evaluation Focus**: Flexibility, integration, learning curve
+
+## Continuous Evaluation
+
+### Quarterly Reviews
+- Technology landscape changes
+- Performance against expectations
+- Cost optimization opportunities
+- Team satisfaction
+- Market alternatives
+
+### Annual Assessment
+- Full technology stack review
+- Vendor relationship evaluation
+- Strategic alignment check
+- Technical debt assessment
+- Roadmap planning
+
+### Deprecation Planning
+- Migration strategy
+- Timeline definition
+- Risk assessment
+- Communication plan
+- Success metrics
+
+## Decision Documentation
+
+Always document:
+1. **Why** the technology was chosen
+2. **Who** was involved in the decision
+3. **When** the decision was made
+4. **What** alternatives were considered
+5. **How** success will be measured
+
+Use Architecture Decision Records (ADRs) for significant technology choices.
diff --git a/skills/c-level-advisor/cto-advisor/scripts/team_scaling_calculator.py b/skills/c-level-advisor/cto-advisor/scripts/team_scaling_calculator.py
new file mode 100644
index 00000000..66842259
--- /dev/null
+++ b/skills/c-level-advisor/cto-advisor/scripts/team_scaling_calculator.py
@@ -0,0 +1,562 @@
+#!/usr/bin/env python3
+"""
+Engineering Team Scaling Calculator - Optimize team growth and structure
+"""
+
+import json
+import math
+from typing import Dict, List, Tuple
+
+class TeamScalingCalculator:
+ def __init__(self):
+ self.conway_factor = 1.5 # Conway's Law impact factor
+ self.brooks_factor = 0.75 # Brooks' Law diminishing returns
+
+ # Optimal team structures based on size
+ self.team_structures = {
+ 'startup': {'min': 1, 'max': 10, 'structure': 'flat'},
+ 'growth': {'min': 11, 'max': 50, 'structure': 'team_leads'},
+ 'scale': {'min': 51, 'max': 150, 'structure': 'departments'},
+ 'enterprise': {'min': 151, 'max': 9999, 'structure': 'divisions'}
+ }
+
+ # Role ratios for balanced teams
+ self.role_ratios = {
+ 'engineering_manager': 0.125, # 1:8 ratio
+ 'tech_lead': 0.167, # 1:6 ratio
+ 'senior_engineer': 0.3,
+ 'mid_engineer': 0.4,
+ 'junior_engineer': 0.2,
+ 'devops': 0.1,
+ 'qa': 0.15,
+ 'product_manager': 0.1,
+ 'designer': 0.08,
+ 'data_engineer': 0.05
+ }
+
+ def calculate_scaling_plan(self, current_state: Dict, growth_targets: Dict) -> Dict:
+ """Calculate optimal scaling plan"""
+ results = {
+ 'current_analysis': self._analyze_current_state(current_state),
+ 'growth_timeline': self._create_growth_timeline(current_state, growth_targets),
+ 'hiring_plan': {},
+ 'team_structure': {},
+ 'budget_projection': {},
+ 'risk_factors': [],
+ 'recommendations': []
+ }
+
+ # Generate hiring plan
+ results['hiring_plan'] = self._generate_hiring_plan(
+ current_state,
+ growth_targets
+ )
+
+ # Design team structure
+ results['team_structure'] = self._design_team_structure(
+ growth_targets['target_headcount']
+ )
+
+ # Calculate budget
+ results['budget_projection'] = self._calculate_budget(
+ results['hiring_plan'],
+ current_state.get('location', 'US')
+ )
+
+ # Assess risks
+ results['risk_factors'] = self._assess_scaling_risks(
+ current_state,
+ growth_targets
+ )
+
+ # Generate recommendations
+ results['recommendations'] = self._generate_recommendations(results)
+
+ return results
+
+ def _analyze_current_state(self, current_state: Dict) -> Dict:
+ """Analyze current team state"""
+ total_engineers = current_state.get('headcount', 0)
+
+ analysis = {
+ 'total_headcount': total_engineers,
+ 'team_stage': self._get_team_stage(total_engineers),
+ 'productivity_index': 0,
+ 'balance_score': 0,
+ 'issues': []
+ }
+
+ # Calculate productivity index
+ if total_engineers > 0:
+ velocity = current_state.get('velocity', 100)
+ expected_velocity = total_engineers * 20 # baseline 20 points per engineer
+ analysis['productivity_index'] = (velocity / expected_velocity) * 100
+
+ # Check team balance
+ roles = current_state.get('roles', {})
+ analysis['balance_score'] = self._calculate_balance_score(roles, total_engineers)
+
+ # Identify issues
+ if analysis['productivity_index'] < 70:
+ analysis['issues'].append('Low productivity - possible process or tooling issues')
+
+ if analysis['balance_score'] < 60:
+ analysis['issues'].append('Team imbalance - review role distribution')
+
+ manager_ratio = roles.get('managers', 0) / max(total_engineers, 1)
+ if manager_ratio > 0.2:
+ analysis['issues'].append('Over-managed - too many managers')
+ elif manager_ratio < 0.08 and total_engineers > 20:
+ analysis['issues'].append('Under-managed - need more engineering managers')
+
+ return analysis
+
+ def _get_team_stage(self, headcount: int) -> str:
+ """Determine team stage based on size"""
+ for stage, config in self.team_structures.items():
+ if config['min'] <= headcount <= config['max']:
+ return stage
+ return 'startup'
+
+ def _calculate_balance_score(self, roles: Dict, total: int) -> float:
+ """Calculate team balance score"""
+ if total == 0:
+ return 0
+
+ score = 100
+ ideal_ratios = self.role_ratios
+
+ for role, ideal_ratio in ideal_ratios.items():
+ actual_count = roles.get(role, 0)
+ actual_ratio = actual_count / total
+
+ # Penalize deviation from ideal ratio
+ deviation = abs(actual_ratio - ideal_ratio)
+ penalty = deviation * 100
+ score -= min(penalty, 20) # Max 20 point penalty per role
+
+ return max(0, score)
+
+ def _create_growth_timeline(self, current: Dict, targets: Dict) -> List[Dict]:
+ """Create quarterly growth timeline"""
+ current_headcount = current.get('headcount', 0)
+ target_headcount = targets.get('target_headcount', current_headcount)
+ timeline_quarters = targets.get('timeline_quarters', 4)
+
+ growth_needed = target_headcount - current_headcount
+ timeline = []
+
+ for quarter in range(1, timeline_quarters + 1):
+ # Apply Brooks' Law - diminishing returns with rapid growth
+ if quarter == 1:
+ quarterly_growth = math.ceil(growth_needed * 0.4) # Front-load hiring
+ else:
+ remaining_growth = target_headcount - current_headcount
+ quarters_left = timeline_quarters - quarter + 1
+ quarterly_growth = math.ceil(remaining_growth / quarters_left)
+
+ # Adjust for onboarding capacity
+ max_onboarding = math.ceil(current_headcount * 0.25) # 25% growth per quarter max
+ quarterly_growth = min(quarterly_growth, max_onboarding)
+
+ current_headcount += quarterly_growth
+
+ timeline.append({
+ 'quarter': f'Q{quarter}',
+ 'headcount': current_headcount,
+ 'new_hires': quarterly_growth,
+ 'onboarding_capacity': max_onboarding,
+ 'productivity_factor': 1.0 - (0.2 * (quarterly_growth / max(current_headcount, 1)))
+ })
+
+ return timeline
+
+ def _generate_hiring_plan(self, current: Dict, targets: Dict) -> Dict:
+ """Generate detailed hiring plan"""
+ current_roles = current.get('roles', {})
+ target_headcount = targets.get('target_headcount', 0)
+
+ hiring_plan = {
+ 'total_hires_needed': target_headcount - current.get('headcount', 0),
+ 'by_role': {},
+ 'by_quarter': {},
+ 'interview_capacity_needed': 0,
+ 'recruiting_resources': 0
+ }
+
+ # Calculate ideal role distribution
+ for role, ideal_ratio in self.role_ratios.items():
+ ideal_count = math.ceil(target_headcount * ideal_ratio)
+ current_count = current_roles.get(role, 0)
+ hires_needed = max(0, ideal_count - current_count)
+
+ if hires_needed > 0:
+ hiring_plan['by_role'][role] = {
+ 'current': current_count,
+ 'target': ideal_count,
+ 'hires_needed': hires_needed,
+ 'priority': self._get_role_priority(role, current_roles, target_headcount)
+ }
+
+ # Distribute hires across quarters
+ timeline = self._create_growth_timeline(current, targets)
+ for quarter_data in timeline:
+ quarter = quarter_data['quarter']
+ hires = quarter_data['new_hires']
+
+ hiring_plan['by_quarter'][quarter] = {
+ 'total_hires': hires,
+ 'breakdown': self._distribute_quarterly_hires(hires, hiring_plan['by_role'])
+ }
+
+ # Calculate interview capacity (5 interviews per hire average)
+ hiring_plan['interview_capacity_needed'] = hiring_plan['total_hires_needed'] * 5
+
+ # Calculate recruiting resources (1 recruiter per 50 hires/year)
+ annual_hires = hiring_plan['total_hires_needed'] * (4 / max(targets.get('timeline_quarters', 4), 1))
+ hiring_plan['recruiting_resources'] = math.ceil(annual_hires / 50)
+
+ return hiring_plan
+
+ def _get_role_priority(self, role: str, current_roles: Dict, target_size: int) -> int:
+ """Determine hiring priority for a role"""
+ # Priority based on criticality and current gaps
+ priorities = {
+ 'engineering_manager': 10 if target_size > 20 else 5,
+ 'tech_lead': 9,
+ 'senior_engineer': 8,
+ 'devops': 7 if current_roles.get('devops', 0) == 0 else 5,
+ 'qa': 6,
+ 'mid_engineer': 5,
+ 'product_manager': 6,
+ 'designer': 5,
+ 'data_engineer': 4,
+ 'junior_engineer': 3
+ }
+
+ return priorities.get(role, 5)
+
+ def _distribute_quarterly_hires(self, total_hires: int, role_needs: Dict) -> Dict:
+ """Distribute quarterly hires across roles"""
+ distribution = {}
+
+ # Sort roles by priority
+ sorted_roles = sorted(
+ role_needs.items(),
+ key=lambda x: x[1]['priority'],
+ reverse=True
+ )
+
+ remaining_hires = total_hires
+
+ for role, needs in sorted_roles:
+ if remaining_hires <= 0:
+ break
+
+ hires = min(needs['hires_needed'], max(1, remaining_hires // 3))
+ distribution[role] = hires
+ remaining_hires -= hires
+
+ return distribution
+
+ def _design_team_structure(self, target_headcount: int) -> Dict:
+ """Design optimal team structure"""
+ stage = self._get_team_stage(target_headcount)
+ structure = {
+ 'organizational_model': self.team_structures[stage]['structure'],
+ 'teams': [],
+ 'reporting_structure': {},
+ 'communication_paths': 0
+ }
+
+ if stage == 'startup':
+ structure['teams'] = [{
+ 'name': 'Core Team',
+ 'size': target_headcount,
+ 'focus': 'Full-stack'
+ }]
+
+ elif stage == 'growth':
+ # Create 2-4 teams
+ team_size = 6
+ num_teams = math.ceil(target_headcount / team_size)
+
+ structure['teams'] = [
+ {
+ 'name': f'Team {i+1}',
+ 'size': team_size,
+ 'focus': ['Platform', 'Product', 'Infrastructure', 'Growth'][i % 4]
+ }
+ for i in range(num_teams)
+ ]
+
+ elif stage == 'scale':
+ # Create departments with multiple teams
+ structure['departments'] = [
+ {'name': 'Platform', 'teams': 3, 'headcount': target_headcount * 0.3},
+ {'name': 'Product', 'teams': 4, 'headcount': target_headcount * 0.4},
+ {'name': 'Infrastructure', 'teams': 2, 'headcount': target_headcount * 0.2},
+ {'name': 'Data', 'teams': 1, 'headcount': target_headcount * 0.1}
+ ]
+
+ # Calculate communication paths (n*(n-1)/2)
+ structure['communication_paths'] = (target_headcount * (target_headcount - 1)) // 2
+
+ # Add management layers
+ structure['management_layers'] = math.ceil(math.log(target_headcount, 7))
+
+ return structure
+
+ def _calculate_budget(self, hiring_plan: Dict, location: str) -> Dict:
+ """Calculate budget projection"""
+ # Average salaries by role and location (in USD)
+ salary_bands = {
+ 'US': {
+ 'engineering_manager': 200000,
+ 'tech_lead': 180000,
+ 'senior_engineer': 160000,
+ 'mid_engineer': 120000,
+ 'junior_engineer': 85000,
+ 'devops': 150000,
+ 'qa': 100000,
+ 'product_manager': 150000,
+ 'designer': 120000,
+ 'data_engineer': 140000
+ },
+ 'EU': {
+ 'engineering_manager': 160000,
+ 'tech_lead': 144000,
+ 'senior_engineer': 128000,
+ 'mid_engineer': 96000,
+ 'junior_engineer': 68000,
+ 'devops': 120000,
+ 'qa': 80000,
+ 'product_manager': 120000,
+ 'designer': 96000,
+ 'data_engineer': 112000
+ },
+ 'APAC': {
+ 'engineering_manager': 120000,
+ 'tech_lead': 108000,
+ 'senior_engineer': 96000,
+ 'mid_engineer': 72000,
+ 'junior_engineer': 51000,
+ 'devops': 90000,
+ 'qa': 60000,
+ 'product_manager': 90000,
+ 'designer': 72000,
+ 'data_engineer': 84000
+ }
+ }
+
+ location_salaries = salary_bands.get(location, salary_bands['US'])
+
+ budget = {
+ 'annual_salary_cost': 0,
+ 'benefits_cost': 0, # 30% of salary
+ 'equipment_cost': 0, # $5k per hire
+ 'recruiting_cost': 0, # 20% of first-year salary
+ 'onboarding_cost': 0, # $10k per hire
+ 'total_cost': 0,
+ 'cost_per_hire': 0
+ }
+
+ for role, details in hiring_plan['by_role'].items():
+ hires = details['hires_needed']
+ salary = location_salaries.get(role, 100000)
+
+ budget['annual_salary_cost'] += hires * salary
+ budget['recruiting_cost'] += hires * salary * 0.2
+
+ budget['benefits_cost'] = budget['annual_salary_cost'] * 0.3
+ budget['equipment_cost'] = hiring_plan['total_hires_needed'] * 5000
+ budget['onboarding_cost'] = hiring_plan['total_hires_needed'] * 10000
+
+ budget['total_cost'] = sum([
+ budget['annual_salary_cost'],
+ budget['benefits_cost'],
+ budget['equipment_cost'],
+ budget['recruiting_cost'],
+ budget['onboarding_cost']
+ ])
+
+ if hiring_plan['total_hires_needed'] > 0:
+ budget['cost_per_hire'] = budget['total_cost'] / hiring_plan['total_hires_needed']
+
+ return budget
+
+ def _assess_scaling_risks(self, current: Dict, targets: Dict) -> List[Dict]:
+ """Assess risks in scaling plan"""
+ risks = []
+
+ growth_rate = (targets['target_headcount'] - current['headcount']) / max(current['headcount'], 1)
+
+ if growth_rate > 1.0: # More than 100% growth
+ risks.append({
+ 'risk': 'Rapid growth dilution',
+ 'impact': 'High',
+ 'mitigation': 'Implement strong onboarding and mentorship programs'
+ })
+
+ if current.get('attrition_rate', 0) > 15:
+ risks.append({
+ 'risk': 'High attrition during scaling',
+ 'impact': 'High',
+ 'mitigation': 'Address retention issues before aggressive hiring'
+ })
+
+ if targets.get('timeline_quarters', 4) < 4:
+ risks.append({
+ 'risk': 'Compressed timeline',
+ 'impact': 'Medium',
+ 'mitigation': 'Consider extending timeline or increasing recruiting resources'
+ })
+
+ return risks
+
+ def _generate_recommendations(self, results: Dict) -> List[str]:
+ """Generate scaling recommendations"""
+ recommendations = []
+
+ # Based on growth rate
+ total_hires = results['hiring_plan']['total_hires_needed']
+ current_size = results['current_analysis']['total_headcount']
+
+ if current_size > 0:
+ growth_rate = total_hires / current_size
+
+ if growth_rate > 0.5:
+ recommendations.append('Consider hiring a dedicated recruiting team')
+ recommendations.append('Implement scalable onboarding processes')
+ recommendations.append('Establish clear team charters and boundaries')
+
+ if growth_rate > 1.0:
+ recommendations.append('⚠️ High growth risk - consider slowing timeline')
+ recommendations.append('Focus on senior hires first to establish culture')
+ recommendations.append('Implement continuous integration practices early')
+
+ # Based on structure
+ if results['team_structure']['communication_paths'] > 1000:
+ recommendations.append('Implement clear communication channels and tools')
+ recommendations.append('Consider platform teams to reduce dependencies')
+
+ # Based on balance
+ if results['current_analysis']['balance_score'] < 70:
+ recommendations.append('Prioritize hiring for underrepresented roles')
+ recommendations.append('Consider role rotation for skill development')
+
+ return recommendations
+
+def calculate_team_scaling(current_state: Dict, growth_targets: Dict) -> str:
+ """Main function to calculate team scaling"""
+ calculator = TeamScalingCalculator()
+ results = calculator.calculate_scaling_plan(current_state, growth_targets)
+
+ # Format output
+ output = [
+ "=== Engineering Team Scaling Plan ===",
+ f"",
+ f"Current State Analysis:",
+ f" Current Headcount: {results['current_analysis']['total_headcount']}",
+ f" Team Stage: {results['current_analysis']['team_stage']}",
+ f" Productivity Index: {results['current_analysis']['productivity_index']:.1f}%",
+ f" Team Balance Score: {results['current_analysis']['balance_score']:.1f}/100",
+ f"",
+ f"Growth Plan:",
+ f" Target Headcount: {growth_targets['target_headcount']}",
+ f" Total Hires Needed: {results['hiring_plan']['total_hires_needed']}",
+ f" Timeline: {growth_targets['timeline_quarters']} quarters",
+ f"",
+ "Quarterly Timeline:"
+ ]
+
+ for quarter in results['growth_timeline']:
+ output.append(
+ f" {quarter['quarter']}: {quarter['headcount']} total "
+ f"(+{quarter['new_hires']} hires, "
+ f"{quarter['productivity_factor']:.0%} productivity)"
+ )
+
+ output.extend([
+ f"",
+ "Hiring Priorities:"
+ ])
+
+ sorted_roles = sorted(
+ results['hiring_plan']['by_role'].items(),
+ key=lambda x: x[1]['priority'],
+ reverse=True
+ )
+
+ for role, details in sorted_roles[:5]:
+ output.append(
+ f" {role}: {details['hires_needed']} hires "
+ f"(Priority: {details['priority']}/10)"
+ )
+
+ output.extend([
+ f"",
+ f"Budget Projection:",
+ f" Annual Salary Cost: ${results['budget_projection']['annual_salary_cost']:,.0f}",
+ f" Total Investment: ${results['budget_projection']['total_cost']:,.0f}",
+ f" Cost per Hire: ${results['budget_projection']['cost_per_hire']:,.0f}",
+ f"",
+ f"Team Structure:",
+ f" Model: {results['team_structure']['organizational_model']}",
+ f" Management Layers: {results['team_structure']['management_layers']}",
+ f" Communication Paths: {results['team_structure']['communication_paths']:,}",
+ f"",
+ "Key Recommendations:"
+ ])
+
+ for rec in results['recommendations']:
+ output.append(f" • {rec}")
+
+ return '\n'.join(output)
+
+if __name__ == "__main__":
+ import argparse
+
+ parser = argparse.ArgumentParser(
+ description="Engineering Team Scaling Calculator - Optimize team growth and structure"
+ )
+ parser.add_argument(
+ "input_file", nargs="?", default=None,
+ help="JSON file with current_state and growth_targets (default: run with sample data)"
+ )
+ parser.add_argument(
+ "--json", action="store_true",
+ help="Output raw JSON instead of formatted report"
+ )
+ args = parser.parse_args()
+
+ if args.input_file:
+ with open(args.input_file) as f:
+ data = json.load(f)
+ current_state = data["current_state"]
+ growth_targets = data["growth_targets"]
+ else:
+ current_state = {
+ 'headcount': 25,
+ 'velocity': 450,
+ 'roles': {
+ 'engineering_manager': 2,
+ 'tech_lead': 3,
+ 'senior_engineer': 8,
+ 'mid_engineer': 10,
+ 'junior_engineer': 2
+ },
+ 'attrition_rate': 12,
+ 'location': 'US'
+ }
+ growth_targets = {
+ 'target_headcount': 75,
+ 'timeline_quarters': 4
+ }
+
+ if args.json:
+ calculator = TeamScalingCalculator()
+ results = calculator.calculate_scaling_plan(current_state, growth_targets)
+ print(json.dumps(results, indent=2))
+ else:
+ print(calculate_team_scaling(current_state, growth_targets))
diff --git a/skills/c-level-advisor/cto-advisor/scripts/tech_debt_analyzer.py b/skills/c-level-advisor/cto-advisor/scripts/tech_debt_analyzer.py
new file mode 100644
index 00000000..1a3211e3
--- /dev/null
+++ b/skills/c-level-advisor/cto-advisor/scripts/tech_debt_analyzer.py
@@ -0,0 +1,450 @@
+#!/usr/bin/env python3
+"""
+Technical Debt Analyzer - Assess and prioritize technical debt across systems
+"""
+
+import json
+from typing import Dict, List, Tuple
+from datetime import datetime
+import math
+
+class TechDebtAnalyzer:
+ def __init__(self):
+ self.debt_categories = {
+ 'architecture': {
+ 'weight': 0.25,
+ 'indicators': [
+ 'monolithic_design', 'tight_coupling', 'no_microservices',
+ 'legacy_patterns', 'no_api_gateway', 'synchronous_only'
+ ]
+ },
+ 'code_quality': {
+ 'weight': 0.20,
+ 'indicators': [
+ 'low_test_coverage', 'high_complexity', 'code_duplication',
+ 'no_documentation', 'inconsistent_standards', 'legacy_language'
+ ]
+ },
+ 'infrastructure': {
+ 'weight': 0.20,
+ 'indicators': [
+ 'manual_deployments', 'no_ci_cd', 'single_points_failure',
+ 'no_monitoring', 'no_auto_scaling', 'outdated_servers'
+ ]
+ },
+ 'security': {
+ 'weight': 0.20,
+ 'indicators': [
+ 'outdated_dependencies', 'no_security_scans', 'plain_text_secrets',
+ 'no_encryption', 'missing_auth', 'no_audit_logs'
+ ]
+ },
+ 'performance': {
+ 'weight': 0.15,
+ 'indicators': [
+ 'slow_response_times', 'no_caching', 'inefficient_queries',
+ 'memory_leaks', 'no_optimization', 'blocking_operations'
+ ]
+ }
+ }
+
+ self.impact_matrix = {
+ 'user_impact': {'weight': 0.30, 'score': 0},
+ 'developer_velocity': {'weight': 0.25, 'score': 0},
+ 'system_reliability': {'weight': 0.20, 'score': 0},
+ 'scalability': {'weight': 0.15, 'score': 0},
+ 'maintenance_cost': {'weight': 0.10, 'score': 0}
+ }
+
+ def analyze_system(self, system_data: Dict) -> Dict:
+ """Analyze a system for technical debt"""
+ results = {
+ 'timestamp': datetime.now().isoformat(),
+ 'system_name': system_data.get('name', 'Unknown'),
+ 'debt_score': 0,
+ 'debt_level': '',
+ 'category_scores': {},
+ 'prioritized_actions': [],
+ 'estimated_effort': {},
+ 'risk_assessment': {},
+ 'recommendations': []
+ }
+
+ # Calculate debt scores by category
+ total_debt_score = 0
+ for category, config in self.debt_categories.items():
+ category_score = self._calculate_category_score(
+ system_data.get(category, {}),
+ config['indicators']
+ )
+ weighted_score = category_score * config['weight']
+ results['category_scores'][category] = {
+ 'raw_score': category_score,
+ 'weighted_score': weighted_score,
+ 'level': self._get_level(category_score)
+ }
+ total_debt_score += weighted_score
+
+ results['debt_score'] = round(total_debt_score, 2)
+ results['debt_level'] = self._get_level(total_debt_score)
+
+ # Calculate impact and prioritize
+ results['prioritized_actions'] = self._prioritize_actions(
+ results['category_scores'],
+ system_data.get('business_context', {})
+ )
+
+ # Estimate effort
+ results['estimated_effort'] = self._estimate_effort(
+ results['prioritized_actions'],
+ system_data.get('team_size', 5)
+ )
+
+ # Risk assessment
+ results['risk_assessment'] = self._assess_risks(
+ results['debt_score'],
+ system_data.get('system_criticality', 'medium')
+ )
+
+ # Generate recommendations
+ results['recommendations'] = self._generate_recommendations(results)
+
+ return results
+
+ def _calculate_category_score(self, category_data: Dict, indicators: List) -> float:
+ """Calculate score for a specific category"""
+ if not category_data:
+ return 50.0 # Default middle score if no data
+
+ total_score = 0
+ count = 0
+
+ for indicator in indicators:
+ if indicator in category_data:
+ # Score from 0 (no debt) to 100 (high debt)
+ total_score += category_data[indicator]
+ count += 1
+
+ return (total_score / count) if count > 0 else 50.0
+
+ def _get_level(self, score: float) -> str:
+ """Convert numerical score to level"""
+ if score < 20:
+ return 'Low'
+ elif score < 40:
+ return 'Medium-Low'
+ elif score < 60:
+ return 'Medium'
+ elif score < 80:
+ return 'Medium-High'
+ else:
+ return 'Critical'
+
+ def _prioritize_actions(self, category_scores: Dict, business_context: Dict) -> List:
+ """Prioritize technical debt reduction actions"""
+ actions = []
+
+ for category, scores in category_scores.items():
+ if scores['raw_score'] > 60: # Focus on high debt areas
+ priority = self._calculate_priority(
+ scores['raw_score'],
+ category,
+ business_context
+ )
+
+ action = {
+ 'category': category,
+ 'priority': priority,
+ 'score': scores['raw_score'],
+ 'action_items': self._get_action_items(category, scores['level'])
+ }
+ actions.append(action)
+
+ # Sort by priority
+ actions.sort(key=lambda x: x['priority'], reverse=True)
+ return actions[:5] # Top 5 priorities
+
+ def _calculate_priority(self, score: float, category: str, context: Dict) -> float:
+ """Calculate priority based on score and business context"""
+ base_priority = score
+
+ # Adjust based on business context
+ if context.get('growth_phase') == 'rapid' and category in ['scalability', 'performance']:
+ base_priority *= 1.5
+
+ if context.get('compliance_required') and category == 'security':
+ base_priority *= 2.0
+
+ if context.get('cost_pressure') and category == 'infrastructure':
+ base_priority *= 1.3
+
+ return min(100, base_priority)
+
+ def _get_action_items(self, category: str, level: str) -> List[str]:
+ """Get specific action items based on category and level"""
+ actions = {
+ 'architecture': {
+ 'Critical': [
+ 'Immediate: Create architecture migration roadmap',
+ 'Week 1: Identify service boundaries for decomposition',
+ 'Month 1: Begin extracting first microservice',
+ 'Month 2: Implement API gateway',
+ 'Quarter: Complete critical service separation'
+ ],
+ 'Medium-High': [
+ 'Month 1: Document current architecture',
+ 'Month 2: Design target architecture',
+ 'Quarter: Begin gradual migration',
+ 'Monitor: Track coupling metrics'
+ ]
+ },
+ 'code_quality': {
+ 'Critical': [
+ 'Immediate: Implement code quality gates',
+ 'Week 1: Set up automated testing pipeline',
+ 'Month 1: Achieve 40% test coverage',
+ 'Month 2: Refactor critical modules',
+ 'Quarter: Reach 70% test coverage'
+ ],
+ 'Medium-High': [
+ 'Month 1: Establish coding standards',
+ 'Month 2: Implement code review process',
+ 'Quarter: Gradual refactoring plan'
+ ]
+ },
+ 'infrastructure': {
+ 'Critical': [
+ 'Immediate: Implement basic CI/CD',
+ 'Week 1: Set up monitoring and alerts',
+ 'Month 1: Automate critical deployments',
+ 'Month 2: Implement disaster recovery',
+ 'Quarter: Full infrastructure as code'
+ ],
+ 'Medium-High': [
+ 'Month 1: Document infrastructure',
+ 'Month 2: Begin automation',
+ 'Quarter: Modernize critical components'
+ ]
+ },
+ 'security': {
+ 'Critical': [
+ 'Immediate: Security audit and patching',
+ 'Week 1: Implement secrets management',
+ 'Month 1: Set up vulnerability scanning',
+ 'Month 2: Implement security training',
+ 'Quarter: Achieve compliance standards'
+ ],
+ 'Medium-High': [
+ 'Month 1: Security assessment',
+ 'Month 2: Implement security tools',
+ 'Quarter: Regular security reviews'
+ ]
+ },
+ 'performance': {
+ 'Critical': [
+ 'Immediate: Performance profiling',
+ 'Week 1: Implement caching strategy',
+ 'Month 1: Optimize database queries',
+ 'Month 2: Implement CDN',
+ 'Quarter: Re-architect bottlenecks'
+ ],
+ 'Medium-High': [
+ 'Month 1: Performance baseline',
+ 'Month 2: Optimization plan',
+ 'Quarter: Incremental improvements'
+ ]
+ }
+ }
+
+ return actions.get(category, {}).get(level, ['Create action plan'])
+
+ def _estimate_effort(self, actions: List, team_size: int) -> Dict:
+ """Estimate effort required for debt reduction"""
+ total_story_points = 0
+ effort_breakdown = {}
+
+ for action in actions:
+ # Estimate based on category and score
+ base_points = action['score'] * 2 # Higher debt = more effort
+
+ if action['category'] == 'architecture':
+ points = base_points * 1.5 # Architecture changes are complex
+ elif action['category'] == 'security':
+ points = base_points * 1.2 # Security requires careful work
+ else:
+ points = base_points
+
+ effort_breakdown[action['category']] = {
+ 'story_points': round(points),
+ 'sprints': math.ceil(points / (team_size * 20)), # 20 points per dev per sprint
+ 'developers_needed': math.ceil(points / 100)
+ }
+ total_story_points += points
+
+ return {
+ 'total_story_points': round(total_story_points),
+ 'estimated_sprints': math.ceil(total_story_points / (team_size * 20)),
+ 'recommended_team_size': max(team_size, math.ceil(total_story_points / 200)),
+ 'breakdown': effort_breakdown
+ }
+
+ def _assess_risks(self, debt_score: float, criticality: str) -> Dict:
+ """Assess risks associated with technical debt"""
+ risk_level = 'Low'
+
+ if debt_score > 70 and criticality == 'high':
+ risk_level = 'Critical'
+ elif debt_score > 60 or criticality == 'high':
+ risk_level = 'High'
+ elif debt_score > 40:
+ risk_level = 'Medium'
+
+ risks = {
+ 'overall_risk': risk_level,
+ 'specific_risks': []
+ }
+
+ if debt_score > 60:
+ risks['specific_risks'].extend([
+ 'System failure risk increasing',
+ 'Developer productivity declining',
+ 'Innovation velocity blocked',
+ 'Maintenance costs escalating'
+ ])
+
+ if debt_score > 80:
+ risks['specific_risks'].extend([
+ 'Competitive disadvantage emerging',
+ 'Talent retention risk',
+ 'Customer satisfaction impact',
+ 'Potential data breach vulnerability'
+ ])
+
+ return risks
+
+ def _generate_recommendations(self, results: Dict) -> List[str]:
+ """Generate strategic recommendations"""
+ recommendations = []
+
+ # Overall strategy based on debt level
+ if results['debt_level'] == 'Critical':
+ recommendations.append('🚨 URGENT: Dedicate 40% of engineering capacity to debt reduction')
+ recommendations.append('Create dedicated debt reduction team')
+ recommendations.append('Implement weekly debt reduction reviews')
+ recommendations.append('Consider temporary feature freeze')
+ elif results['debt_level'] in ['Medium-High', 'High']:
+ recommendations.append('Allocate 25-30% of sprints to debt reduction')
+ recommendations.append('Establish technical debt budget')
+ recommendations.append('Implement debt prevention practices')
+ else:
+ recommendations.append('Maintain 15-20% ongoing debt reduction allocation')
+ recommendations.append('Focus on prevention over correction')
+
+ # Category-specific recommendations
+ for category, scores in results['category_scores'].items():
+ if scores['raw_score'] > 70:
+ if category == 'architecture':
+ recommendations.append(f'Consider hiring architecture specialist')
+ elif category == 'security':
+ recommendations.append(f'Engage security audit firm')
+ elif category == 'performance':
+ recommendations.append(f'Implement performance SLA monitoring')
+
+ # Team recommendations
+ effort = results.get('estimated_effort', {})
+ if effort.get('recommended_team_size', 0) > effort.get('total_story_points', 0) / 200:
+ recommendations.append(f"Scale team to {effort['recommended_team_size']} engineers")
+
+ return recommendations
+
+def analyze_technical_debt(system_config: Dict) -> str:
+ """Main function to analyze technical debt"""
+ analyzer = TechDebtAnalyzer()
+ results = analyzer.analyze_system(system_config)
+
+ # Format output
+ output = [
+ f"=== Technical Debt Analysis Report ===",
+ f"System: {results['system_name']}",
+ f"Analysis Date: {results['timestamp'][:10]}",
+ f"",
+ f"OVERALL DEBT SCORE: {results['debt_score']}/100 ({results['debt_level']})",
+ f"",
+ "Category Breakdown:"
+ ]
+
+ for category, scores in results['category_scores'].items():
+ output.append(f" {category.title()}: {scores['raw_score']:.1f} ({scores['level']})")
+
+ output.extend([
+ f"",
+ "Risk Assessment:",
+ f" Overall Risk: {results['risk_assessment']['overall_risk']}"
+ ])
+
+ for risk in results['risk_assessment']['specific_risks']:
+ output.append(f" • {risk}")
+
+ output.extend([
+ f"",
+ "Effort Estimation:",
+ f" Total Story Points: {results['estimated_effort']['total_story_points']}",
+ f" Estimated Sprints: {results['estimated_effort']['estimated_sprints']}",
+ f" Recommended Team Size: {results['estimated_effort']['recommended_team_size']}",
+ f"",
+ "Top Priority Actions:"
+ ])
+
+ for i, action in enumerate(results['prioritized_actions'][:3], 1):
+ output.append(f"\n{i}. {action['category'].title()} (Priority: {action['priority']:.0f})")
+ for item in action['action_items'][:3]:
+ output.append(f" - {item}")
+
+ output.extend([
+ f"",
+ "Strategic Recommendations:"
+ ])
+
+ for rec in results['recommendations']:
+ output.append(f" • {rec}")
+
+ return '\n'.join(output)
+
+if __name__ == "__main__":
+ # Example usage
+ example_system = {
+ 'name': 'Legacy E-commerce Platform',
+ 'architecture': {
+ 'monolithic_design': 80,
+ 'tight_coupling': 70,
+ 'no_microservices': 90,
+ 'legacy_patterns': 60
+ },
+ 'code_quality': {
+ 'low_test_coverage': 75,
+ 'high_complexity': 65,
+ 'code_duplication': 55
+ },
+ 'infrastructure': {
+ 'manual_deployments': 70,
+ 'no_ci_cd': 60,
+ 'no_monitoring': 40
+ },
+ 'security': {
+ 'outdated_dependencies': 85,
+ 'no_security_scans': 70
+ },
+ 'performance': {
+ 'slow_response_times': 60,
+ 'no_caching': 50
+ },
+ 'team_size': 8,
+ 'system_criticality': 'high',
+ 'business_context': {
+ 'growth_phase': 'rapid',
+ 'compliance_required': True,
+ 'cost_pressure': False
+ }
+ }
+
+ print(analyze_technical_debt(example_system))
diff --git a/skills/c-level-advisor/culture-architect/SKILL.md b/skills/c-level-advisor/culture-architect/SKILL.md
new file mode 100644
index 00000000..c1f80847
--- /dev/null
+++ b/skills/c-level-advisor/culture-architect/SKILL.md
@@ -0,0 +1,167 @@
+---
+name: "culture-architect"
+description: "Build, measure, and evolve company culture as operational behavior — not wall posters. Covers mission/vision/values workshops, values-to-behaviors translation, culture code creation, culture health assessment, and cultural rituals by stage. Use when building company values, assessing culture health, designing cultural rituals, creating culture codes, handling culture clashes, or when user mentions culture, values, culture debt, founder culture, or culture code."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: culture-leadership
+ updated: 2026-03-05
+ frameworks: culture-playbook, culture-code-template
+---
+
+# Culture Architect
+
+Culture is what you DO, not what you SAY. This skill builds culture as an operational system — observable behaviors, measurable health, and rituals that scale.
+
+## Keywords
+culture, company culture, values, mission, vision, culture code, cultural rituals, culture health, values-to-behaviors, founder culture, culture debt, value-washing, culture assessment, culture survey, Netflix culture deck, HubSpot culture code, psychological safety, culture scaling
+
+## Core Principle
+
+**Culture = (What you reward) + (What you tolerate) + (What you celebrate)**
+
+If your values say "transparency" but you punish bearers of bad news — your real value is "optics." Culture is not aspirational. It's descriptive. The work is closing the gap between stated and actual.
+
+## Frameworks
+
+### 1. Mission / Vision / Values Workshop
+
+Run this conversationally, not as a corporate offsite. Three questions:
+
+**Mission** — Why do we exist (beyond making money)?
+- "What would be lost if we disappeared tomorrow?"
+- Mission is present-tense. "We reduce preventable falls in elderly care." Not "to be the leading..."
+
+**Vision** — What does winning look like in 5–10 years?
+- Specific enough to be wrong. "Every care home in Europe uses our system" beats "be the market leader."
+
+**Values** — What behaviors do we actually model?
+- Start with what you observe, not what sounds good. "What did our last great hire do that nobody asked them to?"
+- Keep to 3–5. More than 5 and none of them mean anything.
+
+### 2. Values → Behaviors Translation
+
+This is the work. Every value needs behavioral anchors or it's decoration.
+
+| Value | Bad version | Behavioral anchor |
+|-------|------------|-------------------|
+| Transparency | "We're open and honest" | "We share bad news within 24 hours, including to our manager" |
+| Ownership | "We take responsibility" | "We don't hand off problems — we own them until resolved, even across team boundaries" |
+| Speed | "We move fast" | "Decisions under €5K happen at team level, same day, no approval needed" |
+| Quality | "We don't cut corners" | "We stop the line before shipping something we're not proud of" |
+| Customer-first | "Customers are our priority" | "Any team member can escalate a customer issue to leadership, bypassing normal channels" |
+
+**Workshop exercise:** Write your value. Then ask "How would a new hire know we actually live this on day 30?" If you can't answer concretely, it's not a value — it's an aspiration.
+
+### 3. Culture Code Creation
+
+A culture code is a public document that describes how you operate. It should scare off the wrong people and attract the right ones.
+
+**Structure:**
+1. Who we are (mission + context)
+2. Who thrives here (specific behaviors, not adjectives)
+3. Who doesn't thrive here (honest — this is the useful part)
+4. How we make decisions
+5. How we communicate
+6. How we grow people
+7. What we expect of leaders
+
+See `templates/culture-code-template.md` for a complete template.
+
+**Anti-patterns to avoid:**
+- "We're a family" — families don't fire each other for performance
+- Listing only positive traits — the "who doesn't thrive here" section is what makes it credible
+- Making it aspirational instead of descriptive
+
+### 4. Culture Health Assessment
+
+Run quarterly. 8–12 questions. Anonymous. See `references/culture-playbook.md` for survey design.
+
+**Core areas to measure:**
+1. Psychological safety — "Can I raise a concern without fear?"
+2. Clarity — "Do I know how my work connects to company goals?"
+3. Fairness — "Are decisions made consistently and transparently?"
+4. Growth — "Am I learning and being challenged here?"
+5. Trust in leadership — "Do I believe what leadership tells me?"
+
+**Score interpretation:**
+| Score | Signal | Action |
+|-------|--------|--------|
+| 80–100% | Healthy | Maintain, celebrate, document |
+| 65–79% | Warning | Identify specific friction — don't over-react |
+| 50–64% | Damaged | Urgent leadership attention + specific fixes |
+| < 50% | Crisis | Culture emergency — all-hands intervention |
+
+### 5. Cultural Rituals by Stage
+
+Rituals are the delivery mechanism for culture. What works at 10 people breaks at 100.
+
+**Seed stage (< 15 people)**
+- Weekly all-hands (30 min): company update + one win + one learning
+- Monthly retrospective: what's working, what's not — no hierarchy
+- "Default to transparency": share everything unless there's a specific reason not to
+
+**Early growth (15–50 people)**
+- Quarterly culture survey: first formal check-in
+- Recognition ritual: explicit, public, tied to values (not just results)
+- Onboarding buddy program: cultural transmission now requires intentional effort
+- Leadership office hours: founders stay accessible as layers appear
+
+**Scaling (50–200 people)**
+- Culture committee (peer-driven, not HR): 4–6 people rotating quarterly
+- Values-based performance review: culture fit is measured, not assumed
+- Manager training: culture now lives or dies in team leads
+- Department all-hands + company all-hands separate
+
+**Large (200+ people)**
+- Culture as strategy: explicit annual culture plan with owner and KPIs
+- Internal NPS for culture ("Would you recommend this company to a friend?")
+- Subculture management: engineering culture ≠ sales culture — both must align to company core
+
+### 6. Culture Anti-Patterns
+
+**Value-washing:** Listing values you don't practice. Symptom: employees roll their eyes during values discussions.
+- Fix: Run a values audit. Ask "What did the last person who got promoted demonstrate?" If it doesn't match your values, your real values are different.
+
+**Culture debt:** Accumulating cultural compromises over time. "We'll address the toxic star performer later." Later compounds.
+- Fix: Act on culture violations faster than you think necessary. One tolerated bad behavior destroys what ten good behaviors build.
+
+**Founder culture trap:** Culture stays frozen at founding team's personality. New hires assimilate or leave.
+- Fix: Explicitly evolve values as you scale. What worked at 10 people (move fast, ask forgiveness) may be destructive at 100 (we need process).
+
+**Culture by osmosis:** Assuming culture transmits naturally. It did at 10 people. It doesn't at 50.
+- Fix: Make culture intentional. Document it. Teach it. Measure it. Reward it explicitly.
+
+## Culture Integration with C-Suite
+
+| When... | Culture Architect works with... | To... |
+|---------|---------------------------------|-------|
+| Hiring surge | CHRO | Ensure culture fit is measured, not guessed |
+| Org reorg | COO + CEO | Manage culture disruption from structure change |
+| M&A or partnership | CEO + COO | Detect and resolve culture clashes early |
+| Performance issues | CHRO | Separate culture fit from skill deficit |
+| Strategy pivot | CEO | Update values/behaviors that the pivot makes obsolete |
+| Rapid growth | All | Scale rituals before culture dilutes |
+
+## Key Questions a Culture Architect Asks
+
+- "Can you name the last person we fired for culture reasons? What did they do?"
+- "What behavior got your last promoted employee promoted? Is that in your values?"
+- "What would a new hire observe on day 1 that tells them what's really valued here?"
+- "What do we tolerate that we shouldn't? Who knows and does nothing?"
+- "How does a team lead in Berlin know what the culture is in Madrid?"
+
+## Red Flags
+
+- Values posted on the wall, never referenced in reviews or decisions
+- Star performers protected from cultural standards
+- Leaders who "don't have time" for culture rituals
+- New hires feeling the culture is "different than advertised"
+- No mechanism to raise cultural concerns safely
+- Culture survey results never shared with the team
+
+## Detailed References
+- `references/culture-playbook.md` — Netflix analysis, survey design, ritual examples, M&A playbook
+- `templates/culture-code-template.md` — Culture code document template
diff --git a/skills/c-level-advisor/culture-architect/references/culture-playbook.md b/skills/c-level-advisor/culture-architect/references/culture-playbook.md
new file mode 100644
index 00000000..d8bfdfa5
--- /dev/null
+++ b/skills/c-level-advisor/culture-architect/references/culture-playbook.md
@@ -0,0 +1,243 @@
+# Culture Playbook
+
+Reference frameworks for building, measuring, and evolving company culture.
+
+---
+
+## 1. Netflix Culture Deck — What Works, What Doesn't
+
+Reed Hastings published this in 2009. 125 slides. 20M+ views. It changed how tech companies think about culture.
+
+### What works
+
+**"Adequate performance gets a generous severance"** — This is the sentence that made HR professionals uncomfortable. It's also why Netflix has high performers. If you keep B-players, A-players leave.
+
+**Context, not control** — Instead of rules and approvals, Netflix provides context (strategy, goals, constraints) and expects people to make good decisions. This only works if you actually hire people who can.
+
+**"Freedom and responsibility" as a pair** — You can't have one without the other. Freedom without responsibility is chaos. Responsibility without freedom is bureaucracy.
+
+**Publicly stated values actually describe behavior** — The deck is descriptive, not aspirational. It says "here's what we actually do." That's rare and valuable.
+
+### What doesn't work (or doesn't transfer)
+
+**"We are not a family"** — Works at Netflix, lands badly in many cultures (especially European). The principle underneath it is valid: performance matters. The framing is optional.
+
+**"Keeper test"** — "Would I fight to keep this person?" Powerful tool, but managers need coaching to use it well. Without context, it becomes paranoia-inducing.
+
+**No vacation policy** — Works when managers model healthy vacation use. Doesn't work when culture implicitly punishes taking time off. The policy is neutral; the culture around it determines the outcome.
+
+**Radical transparency on compensation** — Netflix publishes pay bands. This works in high-trust, high-fairness environments. In environments with existing pay inequities, it creates problems before it fixes them.
+
+### Key lesson
+The Netflix culture deck works because it's honest about tradeoffs. Your culture code should be equally honest. "We move fast, which sometimes means decisions get revisited" is more credible than "we move fast AND we get it right the first time."
+
+---
+
+## 2. Values-to-Behaviors Mapping Framework
+
+Values without behavioral anchors are intentions. Behavioral anchors make values operational.
+
+### The mapping process
+
+**Step 1: List your stated values**
+Don't curate. Write down everything on the values list, however it's currently stated.
+
+**Step 2: For each value, find three real examples**
+"Describe a time in the last 6 months when someone exemplified [value]."
+If you can't find three examples, the value isn't real.
+
+**Step 3: Extract the observable behavior**
+From the examples, identify the specific action. Not the feeling, not the intention — the action.
+
+**Step 4: Write the behavioral anchor**
+Format: "[Subject] does [specific action] in [specific context]."
+
+**Step 5: Find the counter-example**
+For each value, identify a behavior that violates it. This is what you don't tolerate.
+Format: "[Subject] does NOT [specific opposite action] even when [temptation/pressure]."
+
+### Example mapping: "Customer Obsession"
+
+| Component | Content |
+|-----------|---------|
+| Value | Customer Obsession |
+| Example 1 | PM delayed a sprint to fix a bug a customer reported on a call, even though it wasn't on the roadmap |
+| Example 2 | Support rep escalated a technical issue directly to engineering at 9pm, resolved within 2 hours |
+| Example 3 | Sales declined a deal that would have required features that would hurt existing customers |
+| Behavioral anchor | "We resolve customer-reported critical issues within 24 hours, regardless of roadmap priority" |
+| Counter-example | "We do not close a customer issue as 'resolved' until the customer confirms it's resolved" |
+
+### Common mapping mistakes
+
+**Too vague:** "We put customers first" — this doesn't change behavior.
+**Too broad:** "We care about quality in everything we do" — can't be measured or violated.
+**Too personal:** "We're passionate" — describes emotion, not action.
+**Too aspirational:** "We strive to deliver world-class..." — "strive" lets you off the hook.
+
+---
+
+## 3. Culture Survey Design — 8-12 Questions That Reveal Truth
+
+Most culture surveys are useless because they measure satisfaction, not health. Satisfaction can be high in a dysfunctional culture ("I like my team, my boss, my pay" ≠ healthy culture).
+
+### Survey design principles
+
+1. **Anonymous, always.** If it's not anonymous, people answer what they think you want to hear.
+2. **Short enough to complete honestly.** 8–12 questions max. 15 minutes max.
+3. **Likert + open text.** "On a scale of 1–5" captures signal. "Why did you give that score?" captures insight.
+4. **Action-linked.** Never run a survey unless you're prepared to share results and act on them.
+5. **Consistent questions over time.** You want trend data, not one-off snapshots.
+
+### The 10-question core survey
+
+| # | Question | Area measured |
+|---|----------|---------------|
+| 1 | I can raise concerns or disagreements with my manager without fear of negative consequences. | Psychological safety |
+| 2 | I know how my work connects to the company's most important goals. | Clarity/alignment |
+| 3 | When I make a mistake, I can be honest about it without hiding it. | Psychological safety |
+| 4 | Decisions here are made based on merit and data, not politics or relationships. | Fairness |
+| 5 | I trust that leadership tells us the truth, even when it's bad news. | Trust in leadership |
+| 6 | I am growing and being challenged in my current role. | Growth |
+| 7 | When someone underperforms and nothing happens, I feel that's handled appropriately. | Accountability |
+| 8 | I feel comfortable being myself at work. | Inclusion |
+| 9 | My manager recognizes my contributions in ways that feel meaningful. | Recognition |
+| 10 | I would recommend this company as a great place to work to someone I respect. | Overall health (eNPS) |
+
+### Follow-up open text questions (pick 2–3)
+
+- "What's the one thing leadership could do differently that would most improve the culture?"
+- "What do we tolerate that we shouldn't?"
+- "What should we protect as we grow that we're at risk of losing?"
+- "What's the gap between what we say we value and what we actually do?"
+
+### Analyzing results
+
+**eNPS (question 10):** Score = % Promoters (9–10) minus % Detractors (1–6). Healthy: > 20. Great: > 40.
+
+**Questions 1 and 3 (psychological safety):** If below 70%, you have a leadership problem, not a culture problem. Fix the manager first.
+
+**Question 7 (accountability):** This is the most honest question. Cultures that fail to hold underperformers accountable destroy high-performer retention.
+
+**Biggest drop between surveys:** This is your fire. Don't average it away.
+
+---
+
+## 4. Cultural Ritual Examples by Company Stage
+
+### Seed (< 15 people)
+
+**Weekly "Wins and Learnings" (15 min, Fridays)**
+- Each person shares one win (however small) and one learning (failure, insight, mistake)
+- No slides. No prep. Just talking.
+- Purpose: normalizes imperfection, builds psychological safety early
+
+**"Open book" financials**
+- Share revenue, burn, runway with the whole team monthly
+- Builds owners, not employees
+- Requires trust that people won't misuse the data
+
+**"Postmortem as celebration"**
+- When something goes wrong, celebrate the post-mortem publicly
+- "We learned X, here's how we'll do it differently"
+- Prevents a blame culture from forming early
+
+### Early growth (15–50 people)
+
+**Monthly "Founder's Letter"**
+- CEO writes an unfiltered update: what we're winning, what's hard, what's changed
+- Not polished. Not PR. Real.
+- Distributed internally before it goes external
+
+**Values spotlight in team meetings**
+- One agenda item: "Who exemplified [value] this week? What did they do?"
+- Takes 3 minutes. Trains the muscle for values-linked recognition.
+
+**New hire "30-day truth sessions"**
+- At day 30, every new hire meets with a senior leader (not their manager) and answers: "What surprised you? What's different from what you expected? What would you fix?"
+- Captures culture signal while the new hire's eyes are still fresh
+
+### Scaling (50–200 people)
+
+**Quarterly culture review**
+- Culture committee reviews survey results, names top issues, proposes 2–3 concrete actions
+- Results shared with all-hands within 2 weeks of survey close
+- 30-day action accountability check-in
+
+**Manager calibration on culture fit**
+- Quarterly: managers share one team member who exemplifies culture, one who struggles
+- Group discussion on patterns, not individuals
+- Identifies culture outliers early before they become retention or performance crises
+
+**"Culture at the edges" audit**
+- Review last 10 performance issues, 10 terminations, 10 promotions
+- Ask: "Is the pattern consistent with our stated values?"
+- This is the reality check. The data doesn't lie.
+
+### Large (200+ people)
+
+**Subculture alignment mapping**
+- Each department articulates its micro-culture
+- Cross-reference with company core values
+- Identify deviations: healthy variation vs. value violation
+
+**Culture ambassador program**
+- Peer-nominated, rotating, not HR
+- Run culture rituals, surface issues, connect remote/distributed teams
+- Budget: small (recognition, team events), influence: large
+
+---
+
+## 5. How to Evolve Culture Without Losing Identity
+
+Culture must evolve as you scale. The mistake is either: (a) refusing to evolve, preserving founder culture that doesn't scale, or (b) evolving so fast that original identity is lost.
+
+### The evolution framework
+
+**Preserve:** Core values that define who you are. These should be stable across stages. If "move fast" is core, it doesn't go away — but its expression changes.
+
+**Adapt:** Behaviors that worked at one stage but need updating. "Move fast" at 10 people = decide same day. At 200 people = decide within 1 week with the right people in the room.
+
+**Add:** New behaviors required at the new scale. "Documentation culture" wasn't needed at 10. It's essential at 100.
+
+**Retire:** Behaviors that actively hurt at scale. "Ask forgiveness, not permission" works at seed. Creates coordination chaos at Series B.
+
+### The evolution process
+
+1. Annual values review (not a rewrite — an audit)
+2. Ask: "Which of our current behaviors are we proud of? Which embarrass us?"
+3. Identify behaviors to add/adapt/retire
+4. Communicate the evolution explicitly: "Here's what's changing and why"
+5. Update the culture code, onboarding, and performance criteria
+
+### Communication of culture change
+
+Never let culture evolution look like hypocrisy. Proactively name it:
+"We used to make all decisions quickly at the team level. As we've grown, that's created coordination problems. Here's how we're updating that: [new behavior]. The underlying value — speed — hasn't changed. How we deliver it has."
+
+---
+
+## 6. Handling Culture Clashes in M&A or Rapid Hiring
+
+### M&A culture integration
+
+**Before signing:**
+- Culture due diligence is as important as financial DD
+- Questions to answer: How do they make decisions? What gets people fired? What gets them promoted? What do they celebrate?
+- Red flag: "We have a great culture" with no supporting evidence
+
+**First 90 days:**
+- Don't impose culture; conduct a bilateral audit
+- Identify: what do they do that we should adopt? What do we do that they should adopt? What conflicts must be resolved?
+- Assign an integration lead on each side. Give them actual authority.
+
+**Failure mode:** Assuming acquisition = cultural absorption. The target's culture doesn't disappear. It goes underground and resurfaces as dysfunction.
+
+### Rapid hiring culture dilution
+
+When a company doubles in headcount in 12 months, culture dilution is near-certain. Prevention:
+
+1. **Codify before you scale.** Document the culture before the surge, not after.
+2. **Onboarding is cultural transmission.** Not just process, not just paperwork — immersion in how decisions get made, what's celebrated, what's not tolerated.
+3. **Hire for culture adds, not fits.** "Fit" means homogeneity. "Add" means the person brings a perspective or behavior that strengthens the culture without violating core values.
+4. **Manager density matters.** If you're adding 10 ICs and 0 managers, the new people have nobody to transmit culture to them. Hire managers ahead of the curve.
+5. **Culture buddy system.** Pair new hires with culture exemplars for the first 60 days.
diff --git a/skills/c-level-advisor/culture-architect/templates/culture-code-template.md b/skills/c-level-advisor/culture-architect/templates/culture-code-template.md
new file mode 100644
index 00000000..20e18095
--- /dev/null
+++ b/skills/c-level-advisor/culture-architect/templates/culture-code-template.md
@@ -0,0 +1,137 @@
+# [Company Name] Culture Code
+
+> This document describes how we work, what we value, and what it's like to be here. It's meant to be honest — which means it will attract some people and repel others. Both outcomes are correct.
+
+---
+
+## Who We Are
+
+[2–3 sentences: what you do, who you serve, what would be lost if you disappeared.]
+
+**Our mission:** [One sentence. Present tense. Specific enough to be wrong.]
+
+**Our vision:** [Where we'll be in 5–10 years. Specific enough to debate.]
+
+---
+
+## What We Value
+
+*Values are behaviors, not adjectives. Each one has a "this is what it looks like" and a "this is what it doesn't look like."*
+
+### [Value 1]
+
+**What this means:** [Behavioral anchor — what someone does when they live this value]
+
+**What this doesn't mean:** [The misconception or violation to guard against]
+
+**Example:** [A real story of this value in action at your company]
+
+---
+
+### [Value 2]
+
+**What this means:** [Behavioral anchor]
+
+**What this doesn't mean:** [The misconception or violation]
+
+**Example:** [Real story]
+
+---
+
+### [Value 3]
+
+**What this means:** [Behavioral anchor]
+
+**What this doesn't mean:** [The misconception or violation]
+
+**Example:** [Real story]
+
+---
+
+*(Repeat for each value. 3–5 total. Never more than 5.)*
+
+---
+
+## Who Thrives Here
+
+*These are specific, observable behaviors — not personality traits or adjectives.*
+
+- You raise problems early, not after they've grown. You don't complain privately and stay silent publicly.
+- You own decisions even when the outcome isn't what you expected.
+- You say "I don't know" instead of bluffing. Then you find out.
+- You give direct feedback to the person who needs to hear it, not to everyone else.
+- You make things better, not just done. You notice what's broken and fix it even when it's not your job.
+- [Add 2–3 specific to your company]
+
+---
+
+## Who Doesn't Thrive Here
+
+*This is the most useful section. Read it carefully.*
+
+- People who need clear instructions before taking action. We provide context; you figure out the path.
+- People who optimize for credit over outcomes. We care what got done, not who gets the headline.
+- People who treat bad news as a liability. Here, hiding problems is the problem.
+- People who need consensus before every decision. We move faster than that.
+- [Add 2–3 specific to your company — be honest]
+
+---
+
+## How We Make Decisions
+
+**Decision types:**
+- **Reversible, small scope:** Make it yourself. Don't ask. Tell us what you decided.
+- **Reversible, larger scope:** Tell relevant people, move forward unless you hear an objection within 24 hours.
+- **Irreversible or high-stakes:** Bring the right people into the room. Write it down. Decide together.
+
+**Default:** Bias toward action. A good decision made fast beats a perfect decision made slow.
+
+**Who decides:** The person closest to the problem, with the most context. Not the most senior person in the room.
+
+---
+
+## How We Communicate
+
+**Default to async.** Most things don't need a meeting. If it can be written, write it.
+
+**Meetings that happen:** [List your recurring meetings and what they're for]
+
+**Meetings that don't happen:** Status updates (use tools), information sharing (write a doc), decisions that one person could make.
+
+**How we give feedback:** Direct, specific, timely. "That report was late and incomplete" not "you should think about your time management." We give feedback to help, not to vent.
+
+**How we share bad news:** Within 24 hours of knowing. To the person who needs to know. Not softened to the point of unclear.
+
+---
+
+## How We Grow People
+
+**We invest in people who invest in themselves.** We provide [budget, learning days, access — be specific]. We don't require you to use them.
+
+**Promotions:** Based on impact already demonstrated, not time served. You're promoted when you're already doing the job you want.
+
+**Performance feedback:** [How often, what format, who delivers it]
+
+**When things aren't working:** We have direct conversations early. We don't let problems simmer for quarterly reviews.
+
+---
+
+## What We Expect of Leaders
+
+Leaders here are multipliers, not heroes. Your job is to make your team better.
+
+- You share context, not just instructions. Your team should be able to make decisions you'd make when you're not there.
+- You give credit visibly and take accountability privately.
+- You have hard conversations before they become unavoidable.
+- You model the culture. If you don't live the values, neither will your team.
+- You develop people, including ones who will outgrow their role here.
+
+---
+
+## The Fine Print
+
+This document is descriptive, not aspirational. It describes how we operate today, with the intent to keep improving.
+
+We update this annually. When the update happens, we'll tell you what changed and why.
+
+*Last updated: [Date] | Version: [X.X]*
diff --git a/skills/c-level-advisor/decision-logger/SKILL.md b/skills/c-level-advisor/decision-logger/SKILL.md
new file mode 100644
index 00000000..b29c2694
--- /dev/null
+++ b/skills/c-level-advisor/decision-logger/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: "decision-logger"
+description: "Two-layer memory architecture for board meeting decisions. Manages raw transcripts (Layer 1) and approved decisions (Layer 2). Use when logging decisions after a board meeting, reviewing past decisions with /cs:decisions, or checking overdue action items with /cs:review. Invoked automatically by the board-meeting skill after Phase 5 founder approval."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: decision-memory
+ updated: 2026-03-05
+ python-tools: scripts/decision_tracker.py
+---
+
+# Decision Logger
+
+Two-layer memory system. Layer 1 stores everything. Layer 2 stores only what the founder approved. Future meetings read Layer 2 only — this prevents hallucinated consensus from past debates bleeding into new deliberations.
+
+## Keywords
+decision log, memory, approved decisions, action items, board minutes, /cs:decisions, /cs:review, conflict detection, DO_NOT_RESURFACE
+
+## Quick Start
+
+```bash
+python scripts/decision_tracker.py --demo # See sample output
+python scripts/decision_tracker.py --summary # Overview + overdue
+python scripts/decision_tracker.py --overdue # Past-deadline actions
+python scripts/decision_tracker.py --conflicts # Contradiction detection
+python scripts/decision_tracker.py --owner "CTO" # Filter by owner
+python scripts/decision_tracker.py --search "pricing" # Search decisions
+```
+
+---
+
+## Commands
+
+| Command | Effect |
+|---------|--------|
+| `/cs:decisions` | Last 10 approved decisions |
+| `/cs:decisions --all` | Full history |
+| `/cs:decisions --owner CMO` | Filter by owner |
+| `/cs:decisions --topic pricing` | Search by keyword |
+| `/cs:review` | Action items due within 7 days |
+| `/cs:review --overdue` | Items past deadline |
+
+---
+
+## Two-Layer Architecture
+
+### Layer 1 — Raw Transcripts
+**Location:** `memory/board-meetings/YYYY-MM-DD-raw.md`
+- Full Phase 2 agent contributions, Phase 3 critique, Phase 4 synthesis
+- All debates, including rejected arguments
+- **NEVER auto-loaded.** Only on explicit founder request.
+- Archive after 90 days → `memory/board-meetings/archive/YYYY/`
+
+### Layer 2 — Approved Decisions
+**Location:** `memory/board-meetings/decisions.md`
+- ONLY founder-approved decisions, action items, user corrections
+- **Loaded automatically in Phase 1 of every board meeting**
+- Append-only. Decisions are never deleted — only superseded.
+- Managed by Chief of Staff after Phase 5. Never written by agents directly.
+
+---
+
+## Decision Entry Format
+
+```markdown
+## [YYYY-MM-DD] — [AGENDA ITEM TITLE]
+
+**Decision:** [One clear statement of what was decided.]
+**Owner:** [One person or role — accountable for execution.]
+**Deadline:** [YYYY-MM-DD]
+**Review:** [YYYY-MM-DD]
+**Rationale:** [Why this over alternatives. 1-2 sentences.]
+
+**User Override:** [If founder changed agent recommendation — what and why. Blank if not applicable.]
+
+**Rejected:**
+- [Proposal] — [reason] [DO_NOT_RESURFACE]
+
+**Action Items:**
+- [ ] [Action] — Owner: [name] — Due: [YYYY-MM-DD] — Review: [YYYY-MM-DD]
+
+**Supersedes:** [DATE of previous decision on same topic, if any]
+**Superseded by:** [Filled in retroactively if overridden later]
+**Raw transcript:** memory/board-meetings/[DATE]-raw.md
+```
+
+---
+
+## Conflict Detection
+
+Before logging, Chief of Staff checks for:
+1. **DO_NOT_RESURFACE violations** — new decision matches a rejected proposal
+2. **Topic contradictions** — two active decisions on same topic with different conclusions
+3. **Owner conflicts** — same action assigned to different people in different decisions
+
+When a conflict is found:
+```
+⚠️ DECISION CONFLICT
+New: [text]
+Conflicts with: [DATE] — [existing text]
+
+Options: (1) Supersede old (2) Merge (3) Defer to founder
+```
+
+**DO_NOT_RESURFACE enforcement:**
+```
+🚫 BLOCKED: "[Proposal]" was rejected on [DATE]. Reason: [reason].
+To reopen: founder must explicitly say "reopen [topic] from [DATE]".
+```
+
+---
+
+## Logging Workflow (Post Phase 5)
+
+1. Founder approves synthesis
+2. Write Layer 1 raw transcript → `YYYY-MM-DD-raw.md`
+3. Check conflicts against `decisions.md`
+4. Surface conflicts → wait for founder resolution
+5. Append approved entries to `decisions.md`
+6. Confirm: decisions logged, actions tracked, DO_NOT_RESURFACE flags added
+
+---
+
+## Marking Actions Complete
+
+```markdown
+- [x] [Action] — Owner: [name] — Completed: [DATE] — Result: [one sentence]
+```
+
+Never delete completed items. The history is the record.
+
+---
+
+## File Structure
+
+```
+memory/board-meetings/
+├── decisions.md # Layer 2: append-only, founder-approved
+├── YYYY-MM-DD-raw.md # Layer 1: full transcript per meeting
+└── archive/YYYY/ # Raw files after 90 days
+```
+
+---
+
+## References
+- `templates/decision-entry.md` — single entry template with field rules
+- `scripts/decision_tracker.py` — CLI parser, overdue tracker, conflict detector
diff --git a/skills/c-level-advisor/decision-logger/scripts/decision_tracker.py b/skills/c-level-advisor/decision-logger/scripts/decision_tracker.py
new file mode 100644
index 00000000..7a9020df
--- /dev/null
+++ b/skills/c-level-advisor/decision-logger/scripts/decision_tracker.py
@@ -0,0 +1,620 @@
+#!/usr/bin/env python3
+"""
+decision_tracker.py — Board Meeting Decision Parser & Reporter
+Part of the C-Level Advisor / Decision Logger skill.
+
+Parses memory/board-meetings/decisions.md and produces actionable reports.
+Stdlib only. No dependencies.
+
+Usage:
+ python decision_tracker.py --summary
+ python decision_tracker.py --overdue
+ python decision_tracker.py --conflicts
+ python decision_tracker.py --owner "CMO"
+ python decision_tracker.py --search "pricing"
+ python decision_tracker.py --due-within 7
+ python decision_tracker.py --demo # Run with sample data
+"""
+
+import argparse
+import os
+import re
+import sys
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+
+# ─────────────────────────────────────────────
+# Data structures
+# ─────────────────────────────────────────────
+
+class ActionItem:
+ def __init__(self, text: str, owner: str, due: Optional[date],
+ review: Optional[date], completed: bool, completed_date: Optional[date],
+ result: str):
+ self.text = text
+ self.owner = owner
+ self.due = due
+ self.review = review
+ self.completed = completed
+ self.completed_date = completed_date
+ self.result = result
+
+ def is_overdue(self) -> bool:
+ if self.completed:
+ return False
+ if self.due and self.due < date.today():
+ return True
+ return False
+
+ def is_due_within(self, days: int) -> bool:
+ if self.completed:
+ return False
+ if self.due:
+ return date.today() <= self.due <= date.today() + timedelta(days=days)
+ return False
+
+
+class Decision:
+ def __init__(self):
+ self.date: Optional[date] = None
+ self.title: str = ""
+ self.decision: str = ""
+ self.owner: str = ""
+ self.deadline: Optional[date] = None
+ self.review: Optional[date] = None
+ self.rationale: str = ""
+ self.user_override: str = ""
+ self.rejected: list[str] = []
+ self.action_items: list[ActionItem] = []
+ self.supersedes: str = ""
+ self.superseded_by: str = ""
+ self.raw_transcript: str = ""
+
+ def is_active(self) -> bool:
+ return not bool(self.superseded_by.strip())
+
+ def has_override(self) -> bool:
+ return bool(self.user_override.strip())
+
+
+# ─────────────────────────────────────────────
+# Parser
+# ─────────────────────────────────────────────
+
+def parse_date(s: str) -> Optional[date]:
+ """Parse YYYY-MM-DD or return None."""
+ if not s:
+ return None
+ s = s.strip()
+ for fmt in ("%Y-%m-%d", "%Y/%m/%d", "%d.%m.%Y"):
+ try:
+ return datetime.strptime(s, fmt).date()
+ except ValueError:
+ continue
+ return None
+
+
+def parse_action_item(line: str) -> Optional[ActionItem]:
+ """
+ Parse a line like:
+ - [ ] Action text — Owner: CMO — Due: 2026-03-15 — Review: 2026-03-29
+ - [x] Action text — Owner: CEO — Completed: 2026-03-10 — Result: Done
+ """
+ line = line.strip()
+ if not line.startswith("- ["):
+ return None
+
+ completed = line.startswith("- [x]") or line.startswith("- [X]")
+ text_start = line.find("]") + 1
+ raw = line[text_start:].strip()
+
+ # Split on " — " (em dash with spaces) or " - " fallback
+ parts_raw = re.split(r"\s+[—\-]{1,2}\s+", raw)
+ text = parts_raw[0].strip() if parts_raw else raw
+
+ def extract(label: str, parts: list[str]) -> str:
+ for p in parts:
+ if p.lower().startswith(label.lower() + ":"):
+ return p[len(label) + 1:].strip()
+ return ""
+
+ owner = extract("Owner", parts_raw[1:])
+ due_str = extract("Due", parts_raw[1:])
+ review_str = extract("Review", parts_raw[1:])
+ completed_str = extract("Completed", parts_raw[1:])
+ result = extract("Result", parts_raw[1:])
+
+ return ActionItem(
+ text=text,
+ owner=owner,
+ due=parse_date(due_str),
+ review=parse_date(review_str),
+ completed=completed,
+ completed_date=parse_date(completed_str),
+ result=result,
+ )
+
+
+def parse_decisions(content: str) -> list[Decision]:
+ """Parse the full decisions.md content into Decision objects."""
+ decisions = []
+ current: Optional[Decision] = None
+ in_rejected = False
+ in_actions = False
+
+ for line in content.splitlines():
+ # New decision entry
+ header_match = re.match(r"^## (\d{4}-\d{2}-\d{2}) — (.+)$", line)
+ if header_match:
+ if current:
+ decisions.append(current)
+ current = Decision()
+ current.date = parse_date(header_match.group(1))
+ current.title = header_match.group(2).strip()
+ in_rejected = False
+ in_actions = False
+ continue
+
+ if current is None:
+ continue
+
+ # Field parsing
+ def extract_field(label: str) -> Optional[str]:
+ pattern = rf"^\*\*{re.escape(label)}:\*\*\s*(.*)$"
+ m = re.match(pattern, line)
+ return m.group(1).strip() if m else None
+
+ val = extract_field("Decision")
+ if val is not None:
+ current.decision = val
+ in_rejected = False
+ in_actions = False
+ continue
+
+ val = extract_field("Owner")
+ if val is not None:
+ current.owner = val
+ continue
+
+ val = extract_field("Deadline")
+ if val is not None:
+ current.deadline = parse_date(val)
+ continue
+
+ val = extract_field("Review")
+ if val is not None:
+ current.review = parse_date(val)
+ continue
+
+ val = extract_field("Rationale")
+ if val is not None:
+ current.rationale = val
+ continue
+
+ val = extract_field("User Override")
+ if val is not None:
+ current.user_override = val
+ in_rejected = False
+ in_actions = False
+ continue
+
+ val = extract_field("Supersedes")
+ if val is not None:
+ current.supersedes = val
+ continue
+
+ val = extract_field("Superseded by")
+ if val is not None:
+ current.superseded_by = val
+ continue
+
+ val = extract_field("Raw transcript")
+ if val is not None:
+ current.raw_transcript = val
+ continue
+
+ # Section headers
+ if re.match(r"^\*\*Rejected:\*\*", line):
+ in_rejected = True
+ in_actions = False
+ continue
+
+ if re.match(r"^\*\*Action Items:\*\*", line):
+ in_actions = True
+ in_rejected = False
+ continue
+
+ if line.startswith("**"):
+ in_rejected = False
+ in_actions = False
+
+ # List items
+ if in_rejected and line.strip().startswith("-"):
+ item = line.strip().lstrip("- ").strip()
+ if item and not item.startswith("
+
+**Rejected:**
+
+- [Proposal text] — [reason for rejection] [DO_NOT_RESURFACE]
+
+**Action Items:**
+- [ ] [Specific action] — Owner: [name] — Due: [YYYY-MM-DD] — Review: [YYYY-MM-DD]
+- [ ] [Specific action] — Owner: [name] — Due: [YYYY-MM-DD] — Review: [YYYY-MM-DD]
+
+**Supersedes:**
+**Superseded by:**
+
+**Raw transcript:** memory/board-meetings/[YYYY-MM-DD]-raw.md
+```
+
+---
+
+## Field Rules
+
+| Field | Rule |
+|-------|------|
+| Decision | Must be a single statement. If it takes two sentences, split into two decisions. |
+| Owner | One person or role. "Everyone" owns nothing. |
+| Deadline | Required. No "TBD". If unknown, set 14 days and review. |
+| Review | Always set. Minimum 1 day after deadline. |
+| Rationale | Required. "Because we decided so" is not rationale. |
+| User Override | Honest record. Do not soften or omit. |
+| Rejected | Every rejected proposal must be listed. |
+| DO_NOT_RESURFACE | Applied to every rejected item. No exceptions. |
+
+---
+
+## Marking Action Items Complete
+
+When an action item is done, update the entry in decisions.md:
+
+```markdown
+- [x] [Action text] — Owner: [name] — Completed: [YYYY-MM-DD] — Result: [one sentence outcome]
+```
+
+Do not delete completed items. The history is the record.
diff --git a/skills/c-level-advisor/executive-mentor/SKILL.md b/skills/c-level-advisor/executive-mentor/SKILL.md
new file mode 100644
index 00000000..8c54885b
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/SKILL.md
@@ -0,0 +1,142 @@
+---
+name: "executive-mentor"
+description: "Adversarial thinking partner for founders and executives. Stress-tests plans, prepares for brutal board meetings, dissects decisions with no good options, and forces honest post-mortems. Use when you need someone to find the holes before the board does, make a decision you've been avoiding, or understand what actually went wrong."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: executive-leadership
+ updated: 2026-03-05
+ python-tools: decision_matrix_scorer.py, stakeholder_mapper.py
+ frameworks: pre-mortem, board-prep, hard-call, stress-test, postmortem
+---
+
+# Executive Mentor
+
+Not another advisor. An adversarial thinking partner — finds the holes before your competitors, board, or customers do.
+
+## The Difference
+
+Other C-suite skills give you frameworks. Executive Mentor gives you the questions you don't want to answer.
+
+- **CEO/COO/CTO Advisor** → strategy, execution, tech — building the plan
+- **Executive Mentor** → "Your plan has three fatal assumptions. Let's find them now."
+
+## Keywords
+executive mentor, pre-mortem, board prep, hard decisions, stress test, postmortem, plan challenge, devil's advocate, founder coaching, adversarial thinking, crisis, pivot, layoffs, co-founder conflict
+
+## Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `/em:challenge ` | Find weaknesses before they find you. Pre-mortem + severity ratings. |
+| `/em:board-prep ` | Prepare for hard questions. Build the narrative. Know your numbers cold. |
+| `/em:hard-call ` | Framework for decisions with no good options. Layoffs, pivots, firings. |
+| `/em:stress-test ` | Challenge any assumption. Revenue projections, moats, market size. |
+| `/em:postmortem ` | Honest analysis. 5 Whys done properly. Who owns what change. |
+
+## Quick Start
+
+```bash
+python scripts/decision_matrix_scorer.py # Weighted decision analysis with sensitivity
+python scripts/stakeholder_mapper.py # Map influence vs alignment, find blockers
+```
+
+## Voice
+
+Direct. Uncomfortable when necessary. Not mean — honest.
+
+Questions nobody wants to answer:
+- "What happens if your biggest customer churns next month?"
+- "Your burn rate gives you 11 months. What's plan B?"
+- "You've been 'almost closing' this deal for 6 weeks. Is it real?"
+- "Your co-founder hasn't shipped anything meaningful in 90 days. What are you doing about it?"
+
+This isn't therapy. It's preparation.
+
+## When to Use This
+
+**Use when:**
+- You have a plan you're excited about (excitement = more scrutiny, not less)
+- Board meeting is coming and you can't fully defend the numbers
+- You're facing a decision you've avoided for weeks
+- Something went wrong and you're still explaining it away
+- You're about to take an irreversible action
+
+**Don't use when:**
+- You need validation for a decision already made
+- You want frameworks without hard questions
+
+## Commands in Detail
+
+### `/em:challenge `
+Takes any plan — roadmap, GTM, hiring, fundraising — and finds what breaks first. Identifies assumptions, rates confidence, maps dependencies. Output: numbered vulnerabilities with severity (Critical / High / Medium). See `skills/challenge/SKILL.md`
+
+### `/em:board-prep `
+48 hours before investors. What are the 10 hardest questions? What data do you need cold? How do you build a narrative that acknowledges weakness without losing the room? Prepares you for the adversarial board, not the friendly one. See `skills/board-prep/SKILL.md`
+
+### `/em:hard-call `
+Reversibility test. 10/10/10 framework. Stakeholder impact mapping. Communication planning. For decisions with no good answer — only less bad ones. See `skills/hard-call/SKILL.md`
+
+### `/em:stress-test `
+"$5B market." "$2M ARR by December." "3-year moat." Every plan is built on assumptions. Surfaces counter-evidence, models the downside, proposes the hedge. See `skills/stress-test/SKILL.md`
+
+### `/em:postmortem `
+Lost deal. Failed feature. Missed quarter. No blame sessions, no whitewash. 5 Whys without softening, contributing factors vs root cause, owners per change, verification dates. See `skills/postmortem/SKILL.md`
+
+## Agents & References
+
+- `agents/devils-advocate.md` — Always finds 3 concerns, rates severity, never gives clean approval
+- `references/hard_things.md` — Firing, layoffs, pivoting, co-founder conflicts, killing products
+- `references/board_dynamics.md` — Board types, difficult directors, when they lose confidence
+- `references/crisis_playbook.md` — Cash crisis, key departure, PR disaster, legal threat, failed fundraise
+
+## What This Isn't
+
+Executive Mentor won't tell you your plan is great. It won't soften bad news.
+
+What it will do: make sure bad news comes from you — first, with a plan — not from your board or customers.
+
+Andy Grove ran Intel through the memory chip crisis by being brutally honest. Ben Horowitz fired his best friend to save his company. The best executives see hard things coming and act first.
+
+That's what this is for.
+
+
+## Proactive Triggers
+
+Surface these without being asked:
+- Board meeting in < 2 weeks with no prep → initiate `/em:board-prep`
+- Major decision made without stress-testing → retroactively challenge it
+- Team in unanimous agreement on a big bet → that's suspicious, challenge it
+- Founder avoiding a hard conversation for 2+ weeks → surface it directly
+- Post-mortem not done after a significant failure → push for it
+
+## When the Mentor Engages Other Roles
+
+| Situation | Mentor Does | Invokes |
+|-----------|-------------|---------|
+| Revenue plan looks too optimistic | Challenges the assumptions | `[INVOKE:cfo|Model the bear case]` |
+| Hiring plan with no budget check | Questions feasibility | `[INVOKE:cfo|Can we afford this?]` |
+| Product bet without validation | Demands evidence | `[INVOKE:cpo|What's the retention data?]` |
+| Strategy shift without alignment check | Tests for cascading impact | `[INVOKE:coo|What breaks if we pivot?]` |
+| Security ignored in growth push | Raises the risk | `[INVOKE:ciso|What's the exposure?]` |
+
+## Reasoning Technique: Adversarial Reasoning
+
+Assume the plan will fail. Find the three most likely failure modes. For each, identify the earliest warning signal and the cheapest hedge. Never say 'this looks good' without finding at least one risk.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/c-level-advisor/executive-mentor/agents/devils-advocate.md b/skills/c-level-advisor/executive-mentor/agents/devils-advocate.md
new file mode 100644
index 00000000..8b7fe872
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/agents/devils-advocate.md
@@ -0,0 +1,139 @@
+# Devil's Advocate Agent
+
+**Role:** Adversarial thinker. Finds what's wrong before others do.
+
+---
+
+## System Prompt
+
+You are a devil's advocate agent for executive decision-making. Your role is not to be contrarian for the sake of it — it is to ensure that every plan, proposal, and decision has been examined from an adversarial perspective before commitment.
+
+You have one job: **find the risks that optimism is hiding.**
+
+You are not pessimistic. You are rigorous. There's a difference.
+
+---
+
+## Non-Negotiable Rules
+
+**Rule 1: Always give exactly 3 specific concerns.**
+Not "there are some risks here." Three concerns, each one concrete and specific. Not "execution risk" — "the VP Sales role has been open for 4 months, which means Q3 revenue is dependent on someone who isn't hired yet."
+
+**Rule 2: Always rate severity.**
+Each concern gets a severity rating:
+- **CRITICAL** — if this materializes, the plan likely fails or causes serious irreversible harm
+- **HIGH** — significant impact, requires contingency planning
+- **MEDIUM** — manageable but worth watching and mitigating
+
+If you can't find a Critical or High risk, look harder. Plans presented for review almost always have at least one.
+
+**Rule 3: Always suggest a mitigation.**
+Every concern should come with a specific mitigation — something the team can actually do. Not "be more careful" — "validate this assumption with 5 customer conversations before committing budget."
+
+**Rule 4: Never approve without finding a risk.**
+If something genuinely looks well-constructed, your job is still to find the most likely failure point. "This looks solid, but here's what I'd watch most closely" is acceptable. "This looks good" with no qualification is not.
+
+**Rule 5: Target the most important assumptions, not the easiest ones.**
+It's easy to find surface-level risks. The valuable work is finding the assumptions the team is most confident about — and stress-testing those. Confident assumptions are dangerous precisely because they don't get questioned.
+
+---
+
+## Concern Structure
+
+Each of your 3 concerns should follow this format:
+
+```
+[SEVERITY] Concern #N: [Short title]
+
+What the plan assumes: [State the assumption explicitly]
+Why this might be wrong: [Specific counter-evidence or reasoning]
+What happens if it is: [Concrete impact — quantify when possible]
+Mitigation: [Specific action that reduces this risk]
+```
+
+---
+
+## Behaviors
+
+**Do:**
+- Be direct. "This is a critical risk because..." not "one might consider..."
+- Be specific. Name the assumption, the counter-evidence, the impact.
+- Be useful. The goal is to improve the plan, not to torpedo it.
+- Engage with the strongest version of the plan, then find its weakness.
+- Surface dependencies — places where multiple things must all go right.
+
+**Don't:**
+- List generic risks that apply to any plan ("execution is always hard")
+- Repeat the same concern in different words
+- Soften concerns to spare feelings
+- Say "this looks great" without a genuine risk identified
+- Confuse style concerns with substance concerns
+
+---
+
+## Example Output
+
+**Input:** "We're planning to raise a $5M seed round in Q2, led by a Tier 1 VC we've been in conversations with for 6 weeks."
+
+**Devil's Advocate Response:**
+
+```
+[CRITICAL] Concern #1: Single-thread fundraise
+
+What the plan assumes: The Tier 1 VC will lead the round, and the process
+will close in Q2.
+
+Why this might be wrong: 6 weeks of conversations is early for a lead
+commitment. Tier 1 VCs frequently stay in "exploratory" mode for months
+before deciding. If they pass — or ask for a reference customer you don't
+have — you have no parallel process running and Q2 close becomes impossible.
+
+What happens if it is: At current burn, Q2 close was assumed for 18 months
+of runway. A 3-month slip changes this to 15 months — still manageable, but
+you lose the ability to be selective about the round.
+
+Mitigation: Run parallel conversations with 3–4 additional funds now, even
+if the Tier 1 is preferred. Parallel processes also create leverage.
+
+---
+
+[HIGH] Concern #2: Valuation expectation mismatch
+
+What the plan assumes: Valuation expectations are aligned between you and
+the lead investor.
+
+Why this might be wrong: There's no mention of a term sheet or valuation
+discussion. Many founders reach advanced-stage conversations before the
+valuation gap becomes apparent.
+
+What happens if it is: Late-stage valuation misalignment often kills rounds
+or forces founder-unfavorable terms under time pressure.
+
+Mitigation: Have the valuation conversation explicitly in the next meeting,
+before other investors are engaged.
+
+---
+
+[HIGH] Concern #3: Q2 close assumption is baked into headcount plan
+
+What the plan assumes: Q2 close means Q3 hires can proceed on schedule.
+
+Why this might be wrong: Even if the round closes end of Q2, hiring 4
+senior roles takes 8–12 weeks per role. The revenue impact of those hires
+was modeled assuming Q3 start.
+
+What happens if it is: Revenue in Q4 will be lower than modeled, which
+affects the Series A story — you'll be raising on lower numbers than your
+projections showed seed investors.
+
+Mitigation: Either model hiring 6 weeks later in the financial model,
+or begin recruiting now for roles you'll close post-funding.
+```
+
+---
+
+## Calibration
+
+The best devil's advocate responses are the ones the team didn't want to hear but couldn't argue with. If the team reads your concerns and says "yeah, we already thought about that" — good. Verification has value.
+
+If they say "we hadn't thought about that" — that's what you're here for.
diff --git a/skills/c-level-advisor/executive-mentor/references/board_dynamics.md b/skills/c-level-advisor/executive-mentor/references/board_dynamics.md
new file mode 100644
index 00000000..7bca221c
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/references/board_dynamics.md
@@ -0,0 +1,263 @@
+# Board Dynamics — Managing the People Who Can Fire You
+
+Your board has the power to fire you. Most boards don't want to. But the relationship deteriorates in predictable ways, and the founders who get replaced are rarely blindsided — in hindsight, they saw it coming.
+
+This is the playbook for building a board that works for you, not against you.
+
+---
+
+## Part 1: Understanding Board Member Types
+
+Not all directors are the same. Understanding who you're dealing with changes how you work with them.
+
+### The Operator Board Member
+
+Usually a former founder or executive. Has built companies, made payroll, managed crises. Values: pragmatism, execution, honesty about what's not working.
+
+**What they want from you:**
+- To see that you understand your own business cold
+- Honesty when things are hard
+- A clear sense that you know what you're doing operationally
+
+**How to work with them:**
+- Be direct and specific about problems
+- Ask for their experience on specific operational challenges
+- They can smell spin — don't try it
+
+**Warning sign:** They go quiet in board meetings. Operators who disengage are usually losing confidence.
+
+### The Financial Investor Director
+
+VC or PE-backed. Focused on return. Watches: growth rate, burn, path to next round, exit prospects.
+
+**What they want from you:**
+- The company to be on track to return their fund
+- To not be surprised by bad news
+- Confidence that you're the right person to lead through the next stage
+
+**How to work with them:**
+- Know their fund's investment thesis — understand what "success" looks like to them
+- Give them the data they need proactively, before they ask
+- Be clear on fundraising timeline so they can plan
+
+**Warning sign:** They start asking about the management team more than the business. This is a proxy for evaluating whether you need to be replaced.
+
+### The Independent Director
+
+Usually brought in for governance, domain expertise, or to balance the board. Can be former industry executives, board members at comparable companies, or subject matter experts.
+
+**What they want from you:**
+- To genuinely contribute, not just show up
+- To be informed and included, not just called when there's a crisis
+- Governance that protects them from legal exposure
+
+**How to work with them:**
+- Give them a specific domain to own (e.g., "I want your guidance on enterprise sales strategy")
+- Consult them before board meetings on their area of expertise
+- Treat them as partners, not decoration
+
+### The Strategic Partner Director
+
+Comes from a corporate strategic investment or partnership. Focused on how your success maps to their strategic interests.
+
+**What they want from you:**
+- Alignment on strategy (their strategy, not just yours)
+- A productive relationship with the parent company
+- Visibility into product direction
+
+**The complication:** Their interests and your investors' interests sometimes diverge. Manage this proactively. Don't let the board divide into factions.
+
+---
+
+## Part 2: Information Architecture
+
+What you tell the board, when you tell them, and how shapes the relationship more than almost anything else.
+
+### The Rule on Bad News
+
+**Tell them before the meeting, not during it.**
+
+When revenue misses, when the key executive leaves, when the product launch slips — board members should hear from you directly, before the formal meeting. A brief message: "I want to flag that Q3 came in below target. Here's what happened, here's what I'm doing, here's what I'll cover in the board meeting."
+
+Why this matters:
+- It demonstrates you're on top of it
+- It removes the emotional surprise during the meeting (which makes it harder to have a productive conversation)
+- It shows that you treat them as partners, not as a board to manage
+
+Board members who are surprised by bad news in a meeting start asking themselves: "What else don't I know?"
+
+### The Pre-Read
+
+Send materials 5–7 days before the meeting, not the night before.
+
+Standard pre-read package:
+- Board deck (current state, key metrics, major topics)
+- 1-page executive summary (what's the meeting for, what decisions are needed)
+- Supporting data appendices
+- Any significant updates since last meeting
+
+**The discipline test:** If you're sending materials the day before, you're not in control of your business. The data should be available earlier. If it isn't, that's a systems problem worth fixing.
+
+### What to Keep Confidential
+
+Not everything that happens in the company should go to the board. Use judgment:
+
+**Always share:** Significant strategic changes, financial surprises, executive departures, legal matters, fundraising updates, product pivots.
+
+**Use discretion:** Internal team conflicts, early-stage ideas, specific customer names (check NDAs), competitive intelligence.
+
+**Be careful about:** Creating information asymmetry between board members. If you tell one director something significant, think carefully about whether others need to know.
+
+---
+
+## Part 3: Running Effective Board Meetings
+
+### The Structure That Works
+
+**(15 min) CEO Update**
+Current state of business in 5 minutes. What changed since last meeting. The one or two things you're most focused on. What you need from the board today.
+
+**(30–45 min) Deep Dive Topics (1–2 max)**
+One or two topics that need board input, expertise, or decision. Not status updates — strategic questions. "Should we enter the enterprise market now or in 12 months?" "We have two acquisition opportunities — what's your view?"
+
+**(30 min) Financial Review**
+Actuals vs budget. Burn, runway, key metrics. Honest discussion of variance.
+
+**(15 min) Closed Session (CEO + Board only)**
+Every meeting. Used for: board governance, executive compensation, confidential matters. This signals maturity. Skip it and directors raise it anyway.
+
+**(15 min) Wrap + Action Items**
+What was decided, who owns what, by when. Sent within 24 hours.
+
+### How to Handle Disagreement in the Meeting
+
+Board members will sometimes challenge your recommendations publicly. How you handle it determines the room's perception of your leadership.
+
+**Good response to challenge:**
+1. Acknowledge the concern genuinely ("That's a fair point — let me address it")
+2. State your position with specific evidence
+3. Acknowledge uncertainty where it exists
+4. Be clear about who decides and that you've considered this
+
+**Bad responses:**
+- Getting defensive ("I think you're not seeing the full picture")
+- Caving immediately to avoid conflict ("You're right, we'll change it")
+- Being dismissive ("We already thought about that")
+
+You can disagree with a board member and still build their confidence in you. What matters is how you engage with the challenge.
+
+### The Closed Session
+
+Every board meeting should end with a closed session — board members only, no CEO.
+
+**Yes, this is uncomfortable.** It's supposed to be. This is the board's opportunity to discuss management team performance, compensation, and governance without the CEO present.
+
+Don't skip it because it makes you nervous. Skipping it means the same conversations happen in parking lots and side calls instead. Better in the room.
+
+**After the closed session:** The board chair should brief you on any significant outcomes. If they don't, ask.
+
+---
+
+## Part 4: When the Board Loses Confidence
+
+### Early Warning Signs
+
+- Questions about the management team become more frequent
+- Board members start contacting reports directly without telling you
+- You notice side conversations happening before or after board meetings
+- Meeting dynamics shift — less engagement, more skepticism
+- A director asks to be added to distribution lists you normally manage
+- Requests for more frequent reporting
+
+**The mistake:** Pretending not to notice.
+
+**The right move:** Name it. "I've noticed some different dynamics in recent board interactions. I want to understand if there are concerns about my leadership or execution that we should talk about directly."
+
+This is hard. It's also the only thing that gives you a chance to address it.
+
+### The CEO Review
+
+Most boards conduct annual or semi-annual CEO reviews. If yours doesn't, ask for one. This is a governance strength, not a vulnerability.
+
+Questions typically asked in a CEO review:
+- Is the company meeting its strategic goals?
+- Is the CEO executing on the plan?
+- Is the CEO building the right team?
+- What's the CEO's relationship with the board?
+- Is the CEO growing into the company's stage?
+
+**Preparing for your own review:** Self-assess honestly first. Know where you're strong and where you're not. The directors already have opinions — your job is to show self-awareness and a plan.
+
+### The Confidence Conversation
+
+If you believe the board is losing confidence, have the direct conversation — one-on-one with the board chair or lead director.
+
+"I want to be direct with you. I have a sense that there are questions about my performance or leadership that haven't been said explicitly. I'd rather hear them directly than through signals."
+
+**If the answer is yes, there are concerns:**
+- Listen without defending
+- Ask clarifying questions
+- Ask what a successful path forward looks like
+- Agree on specific commitments and a timeline
+
+**If the answer is "no, everything is fine":**
+- Note your concern ("I appreciate that, and I'd rather air this concern than not")
+- Keep watching the signals
+
+---
+
+## Part 5: Managing Investor Expectations
+
+### The Fundraising Narrative
+
+Your current investors are your reference letters for the next round. How you manage them through the current period shapes what they say about you to the next investor.
+
+**The mistake:** Only engaging investors deeply when you need something.
+
+**The right approach:** Proactive, regular, honest communication. Monthly investor updates. Reply to emails within 24 hours. Share wins and problems with equal transparency.
+
+### Monthly Investor Update Template
+
+```
+[Company] — [Month] Update
+
+**Headline:** [One sentence — the most important thing that happened]
+
+**Key Metrics:**
+- MRR: $X (vs $Y last month)
+- Burn: $X/month, Runway: X months
+- [3-5 metrics that matter for your stage]
+
+**What went well:**
+- [2-3 bullets]
+
+**What didn't:**
+- [1-2 bullets — being honest here builds more trust than hiding it]
+
+**What we need:**
+- [Specific asks — introductions, expertise, candidates]
+```
+
+Monthly. Brief. Honest. Consistent. This is table stakes.
+
+### When to Call an Emergency Meeting
+
+Don't wait for the quarterly board meeting if:
+- You've missed a significant milestone by more than 20%
+- A key executive is leaving
+- There's a legal or compliance issue
+- You're considering a strategic pivot
+- Runway is below 9 months and fundraising hasn't started
+
+The call should come from you, with your analysis and your plan, before they start asking questions.
+
+### Navigating Competing Investor Interests
+
+If you have multiple institutional investors, their interests sometimes conflict. Common tensions:
+- One wants to sell early; another wants to push for a larger outcome
+- One is focused on strategic acquirers; another on IPO
+- One wants to protect pro-rata in a new round; another wants a new lead
+
+**Your job:** Be transparent with all of them, don't manage information asymmetrically, and be clear about your own perspective and what's best for the company. You serve the company, not any individual investor.
+
+When conflicts are severe: get independent legal counsel. Do not navigate cap table and governance conflicts with only your investors' lawyers advising.
diff --git a/skills/c-level-advisor/executive-mentor/references/crisis_playbook.md b/skills/c-level-advisor/executive-mentor/references/crisis_playbook.md
new file mode 100644
index 00000000..ff39ca36
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/references/crisis_playbook.md
@@ -0,0 +1,173 @@
+# Crisis Playbook — When Things Go Really Wrong
+
+Crises aren't random. They fall into predictable categories. The companies that survive them have usually thought through the response before it happened.
+
+This playbook covers six crisis types: cash crisis, key person departure, PR disaster, legal threat, lost major customer, failed fundraise.
+
+For each: what to do in the first 24 hours, the first week, and the recovery path.
+
+---
+
+## Framework: The First Response
+
+Every crisis response starts with the same three questions:
+
+1. **What is the actual scope?** (Not the fear-amplified version — the real facts)
+2. **Who needs to know, and in what order?** (Don't broadcast before you understand the problem)
+3. **What's the first stabilizing action?** (One thing that stops the bleeding or prevents it from getting worse)
+
+The biggest mistake in crisis response: reactive communication before you understand the situation. The second biggest: waiting too long to communicate once you do.
+
+---
+
+## Crisis 1: Cash Crisis
+
+### Definition
+Less than 6 months of runway at current burn, without a funded plan to extend it.
+
+### First 24 Hours
+- **Get exact numbers.** Not approximate — exact. Current cash balance, exact monthly burn, exact accounts receivable timeline, exact date when you hit zero.
+- **Stop discretionary spending immediately.** Before you know the full plan, stop: all non-essential vendor renewals, all hiring (unless critical path), all travel, all subscriptions you don't use daily.
+- **Call your board chair.** Not the full board — the chair, one-on-one. This conversation: "Here's the situation. Here's what I know. Here's what I'm doing today. I want to schedule an emergency board call for [48 hours from now]."
+- **Do not tell the broader team yet.** Not because you're hiding it — because you'll be telling a different story in 48 hours when you have a plan. "We're out of money and I don't know what we're doing" is not a message that helps anyone.
+
+### First Week
+- **Model three scenarios.** (1) Raise now — how long and at what terms? (2) Reduce burn to extend runway — what cuts, and what does that company look like? (3) Bridge from existing investors — is that realistic?
+- **Emergency board meeting.** Present the three scenarios. Make a recommendation. Come with a plan, not just a problem.
+- **Start the raise immediately if that's the path.** Cash crises give you no luxury of preparation time. Reach out to existing investors and warm prospects the same week you make the decision.
+- **If cutting, do it once and do it right.** See hard_things.md — layoffs section. Dragging it out is worse.
+- **Communicate to team within one week.** After you have a plan. Honest, direct, with clarity on what it means for their jobs. "We have N months of runway. Here's what we're doing. Here's what this means for you."
+
+### Recovery Path
+- If raising: Closing the round is the only milestone that matters. Assign someone to own diligence data, legal docs, and investor follow-up. This is now the CEO's full-time job.
+- If cutting: You need to demonstrate that the cuts were sufficient and that the business is stable. Three straight months of burn at or below plan is the proof point.
+- The narrative question: "Why did this happen and why won't it happen again?" You will be asked this in the next fundraise. Have a direct, honest answer.
+
+### What kills companies in cash crises
+- Raising a bridge that isn't a bridge — it extends pain without solving the underlying problem
+- Cutting too slowly (two rounds of cuts) — kills morale and loses the people you want to keep
+- Hiding it from the team until it becomes a rumor — the rumor is always worse than the truth
+- Not raising the issue with the board until it's critical — board members are more useful with more lead time
+
+---
+
+## Crisis 2: Key Person Departure
+
+### Definition
+A person whose departure significantly impacts company execution, customer relationships, or team stability. Usually C-level or a critical technical/commercial lead.
+
+### First 24 Hours
+- **Clarify what "departure" means.** Resignation? Fired? Mutual agreement? The situation determines the response.
+- **Assess the actual impact.** What does this person own that isn't covered? Who on the team will be most affected? Do any customers have primary relationships with this person?
+- **Secure institutional knowledge.** If possible and appropriate, agree on a knowledge transfer plan before they leave.
+- **Notify the board chair.** Same day. Same rule: facts only, no spin.
+- **Don't announce internally yet** unless the person is already telling people (which they sometimes do). Get ahead of it by a few hours if possible.
+
+### First Week
+- **Control the narrative internally.** All-hands or department meeting within 2–3 days. Honest: "Name is leaving. Here's what I can share about why. Here's the plan." Gap in leadership acknowledged, interim plan named, hiring process started.
+- **Handle customer relationships.** Identify the top 5-10 customers with a relationship with this person. CEO or another senior person reaches out personally. "I want to make sure you hear from me directly..."
+- **Announce interim ownership.** Don't leave reporting lines and responsibilities ambiguous. Even a temporary assignment provides stability.
+- **Start the search.** Don't wait. The bench is always thinner than you think and searches take 3–4 months.
+
+### Recovery Path
+- The signal the team is watching: does the company continue executing or does it stall?
+- Keep shipping. Keep hitting targets. The successor to a strong leader builds credibility by maintaining forward momentum.
+- Be honest in fundraising about the departure — investors will do reference checks. "We had a key departure and here's how we managed the transition" is a much better story than one they have to discover.
+
+---
+
+## Crisis 3: PR Disaster
+
+### Definition
+A story, social media incident, or public situation that damages brand, reputation, or customer trust. Security breach, discriminatory behavior, regulatory violation, public founder misconduct.
+
+### First 24 Hours
+- **Establish facts before you communicate.** What actually happened? What data was affected? Who is affected? What is the extent?
+- **Activate legal counsel immediately.** Before any external communication. Not to suppress the story — to make sure what you say is accurate and doesn't create additional liability.
+- **Designate one spokesperson.** Only one person speaks to media, posts on social. Everyone else: "I can't comment on that, but [spokesperson] is handling media inquiries."
+- **Acknowledge, don't stonewall.** If the story is breaking publicly, a "we are aware and investigating" response within hours is better than silence, which looks like hiding.
+
+### First Week
+- **Communicate to affected parties first.** If it's a data breach: affected customers before media. If it's a discrimination situation: affected employees and team before investors.
+- **Draft a public statement.** Elements: what happened (factual), who is affected, what you're doing, what you're doing to prevent recurrence. No corporate-speak. No deflection. No passive voice ("mistakes were made").
+- **Proactively update investors.** They'll hear about it anyway. Hearing from you first, with context, is materially better.
+- **Execute the response plan.** Assign owners to every stream: affected customers, media, team, investors, legal.
+
+### Recovery Path
+- PR crises recover through consistent, demonstrated behavior over time — not through a single statement.
+- What you do in the weeks after the initial story is more important than the initial statement.
+- If someone in leadership caused the problem: the decision about whether they stay or go will be watched closely. Protecting the wrong person damages recovery.
+- Customer trust recovers faster when they see tangible changes, not just words.
+
+---
+
+## Crisis 4: Legal Threat
+
+### Definition
+Significant legal action: patent claim, employment lawsuit, customer breach of contract claim, regulatory investigation, IP dispute.
+
+### First 24 Hours
+- **Do not engage directly with the opposing party without counsel.** Nothing — no calls, no emails, no messages.
+- **Get legal counsel on the call today.** Not next week. If you have outside counsel, call them. If you don't have a relationship, get one immediately.
+- **Document what you know.** The sequence of events, relevant contracts, communications. Don't delete or alter anything — that can become a separate problem.
+- **Tell the board chair.** Same day. Board members sometimes have relevant experience or relationships that help.
+
+### First Week
+- **Assess exposure.** With counsel: what's the realistic worst case? What's the likely case? What's the cost range?
+- **Determine response strategy.** Fight, settle, or ignore (only for clearly frivolous claims with no risk). Most legal threats are best resolved through settlement discussion, not litigation.
+- **Evaluate business impact.** Does this affect fundraising? Customer relationships? Employment contracts? Scope the full impact.
+- **Communication plan.** Employees? Customers? Investors? In most cases, confidentiality is important — but key stakeholders need to know.
+
+### Recovery Path
+- Most legal threats resolve. They resolve faster and cheaper when addressed directly and early.
+- Avoid the temptation to ignore small claims — small claims become large ones when ignored.
+- If this exposed a real process gap (inadequate IP protection, unclear employment agreements, contract gaps), fix it. The litigation is the signal; the underlying gap is the problem.
+
+---
+
+## Crisis 5: Lost Major Customer
+
+### Definition
+Churn of a customer representing more than 10% of ARR, or whose departure creates a dangerous narrative ("even your biggest customer left").
+
+### First 24 Hours
+- **Get the real reason.** Not the polite exit reason — the real one. Ask directly: "I want to understand what we could have done differently. Not to change the decision — to learn." Sometimes they'll tell you.
+- **Assess financial impact.** Model the immediate effect on runway, burn coverage, and next fundraising story.
+- **Notify the board chair.** If this is >10% ARR, same day. No surprises at board meeting.
+- **Do not panic-announce internally.** You need a plan before you tell the team.
+
+### First Week
+- **Understand the signal.** Is this one customer's specific situation, or a symptom of a broader product/market fit problem? The answer changes the response completely.
+- **Address the team.** The team will notice a major logo disappear. Name it, explain what you know, explain what's changing.
+- **Accelerate pipeline.** If this creates a gap to target, which deals can be accelerated? What expansion opportunities are there with existing customers?
+- **Review other at-risk customers.** Implement a customer health review — who else might be showing similar signals?
+
+### Recovery Path
+- If this is an isolated case: close the gap with another customer, document the lesson, move on.
+- If this is a signal of broader PMF problems: this is the more serious situation. What are customers getting from you that they can't get elsewhere? Are your most engaged customers using the product the same way you thought?
+- The fundraising question: "We lost [major customer]. Why?" Have a direct, honest answer that includes what you changed as a result.
+
+---
+
+## Crisis 6: Failed Fundraise
+
+### Definition
+A fundraising process that ends without closing: term sheet pulled, lead investor passed, round didn't close, or bridge not available.
+
+### First 24 Hours
+- **Assess actual runway.** How much time do you have at current burn?
+- **Identify where the process broke.** Was it valuation? Team? Product? Market? The "why" determines the path.
+- **Immediately convene board.** You need their help and their network. A failed raise is not something to manage quietly.
+- **Do not tell the team yet.** You need a plan first. "We didn't raise and I don't know what we're doing" destroys morale in a way that's hard to recover from.
+
+### First Week
+- **Model survival scenarios.** At current burn: how long? At 50% reduced burn: how long? What does the reduced-burn company look like? Is it sustainable?
+- **Identify specific reasons the raise failed.** Investor feedback, even if uncomfortable. "The market doesn't understand our vision" is not useful. "Three investors said the unit economics weren't believable" is useful.
+- **Evaluate alternative paths.** Revenue-based financing, venture debt, strategic investment, customer advance payments, bridge from existing investors, acqui-hire.
+- **Communicate to team.** Within one week. With a plan. "Here's what we're doing. Here's what this means for the team."
+
+### Recovery Path
+- The raise failed for reasons. Fix the reasons. If it was valuation: you may need to lower expectations. If it was market: you may need to refocus. If it was metrics: you need to improve metrics before the next attempt.
+- Failed raises are more common than founders discuss publicly. Most companies that eventually succeed have had at least one.
+- The companies that recover from failed fundraises usually do so by extending runway aggressively (cutting), finding a lead from outside their normal network, or changing something material about the business.
+- **Do not do bridge rounds as avoidance.** A bridge that extends your runway 3 months to a problem you haven't fixed is not a solution. Only bridge if you have a specific, credible path to a successful close.
diff --git a/skills/c-level-advisor/executive-mentor/references/hard_things.md b/skills/c-level-advisor/executive-mentor/references/hard_things.md
new file mode 100644
index 00000000..72a4486d
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/references/hard_things.md
@@ -0,0 +1,256 @@
+# Hard Things — Decision Frameworks for the Calls Nobody Wants to Make
+
+Firing people. Laying off teams. Pivoting when you've raised money on the old direction. Telling a co-founder it's over. Shutting down a product.
+
+This isn't a framework for feeling better about hard calls. It's a framework for making them correctly.
+
+---
+
+## Part 1: Firing
+
+### When to Fire Someone
+
+Most leaders wait too long. By the time they act, everyone else on the team already knows the problem person isn't working out. The team watches the leader, waiting to see if they'll act.
+
+**Fire when:**
+- Performance isn't improving after clear, direct, documented feedback
+- The person is a culture or values problem, not just a skills problem
+- You find yourself routing around them (giving their work to others, excluding them from important discussions)
+- The team is being damaged by having them there
+- You wouldn't hire them today for this role
+
+**The question to ask:** "If I could wave a magic wand and this person just stopped coming to work, would I be relieved or would I miss them?" If relieved — you already know.
+
+**The hidden test:** "Would I enthusiastically recommend this person to a friend's company for this exact role?" If no, what does that tell you?
+
+### The Warning Signs You're Avoiding the Decision
+
+- You've been "working on it" for more than 3 months
+- You're hoping they'll leave on their own
+- You're giving them feedback that's softer than what you actually think
+- You're planning to "deal with it after the quarter"
+- Other team members have started asking you about it
+
+### Before Firing: The Due Diligence
+
+Have you been **direct** — not hinted, not soft-pedaled, but explicitly said "your performance is not meeting the standard required for this role and your job is at risk"?
+
+Have you given them **a fair chance to improve** with clear criteria for what success looks like?
+
+Have you checked whether this is a **fit problem** (wrong role for their skills) vs a **performance problem** (not executing in a role they're capable of)?
+
+Have you considered whether this is **your failure** — bad hire, bad onboarding, bad management — and whether another manager would get different results?
+
+This isn't to talk yourself out of it. It's to make sure you can stand behind the decision.
+
+### How to Fire Someone
+
+**The conversation:**
+
+Do it in person. Start of the week (not Friday — that's cruel). Private meeting. 30 minutes max.
+
+Three sentences:
+1. "I have difficult news — today is your last day."
+2. "The reason is [one clear sentence — not a list of grievances]."
+3. "Here's what the transition looks like [severance, references, timeline]."
+
+**Do not:**
+- Soften it so much that the person doesn't understand what's happening
+- Give a performance review at the end ("you're really good at X but...")
+- Apologize excessively (once is appropriate; more makes it about you)
+- Leave open questions about whether this is final (it is)
+
+**The question they'll ask:** "Why now?" Be ready for this. Have a direct answer.
+
+**What to say to the team:** Same day. "I want to let you know that [Name] is no longer with the company. I can't share details, but I want to be transparent that this was a decision we made, not something they chose. Their last day is today." That's it. Don't litigate. Don't share reasons.
+
+### Severance
+
+Be generous. Not because you have to — because it's the right thing to do and it protects the culture. The team watches how you treat people when they leave.
+
+For executives: 2–3 months standard, more if they've been there a long time.
+For individual contributors: 2–4 weeks per year of service is reasonable.
+
+**Reference:** Only confirm dates and title (standard practice). If you genuinely believe they'd be good somewhere else, offer a more substantive reference. Don't damage their career because the fit wasn't right.
+
+---
+
+## Part 2: Layoffs
+
+### The First Question: Is This the Right Move?
+
+Layoffs are sometimes the right call. But they're also sometimes an avoidance tactic — avoiding harder decisions about business model, spending discipline, or strategic direction.
+
+Before proceeding, be clear on what problem you're solving:
+
+- **Extending runway:** How many months does this buy? Is that enough?
+- **Restructuring:** Are you changing the direction of the company, not just the headcount?
+- **Cost cutting without strategic change:** This is usually a mistake — you lose talent, damage culture, and face the same problem 6 months later.
+
+**The math:** At your current burn, you need to cut \_\_% to extend runway from \_\_ months to \_\_ months. That math should drive the decision, not a "feels about right" number.
+
+### Cut Once, Cut Deep
+
+The worst outcome is two rounds of layoffs. After the first, the people who stay are already thinking about leaving. A second round converts "scared" to "gone."
+
+If you're going to do this, do it once and do it to a level that solves the problem for 18+ months. Psychological safety matters more than any individual cost saving.
+
+### Deciding Who to Let Go
+
+This is the hardest part. A framework:
+
+**By role:** Does the company need this function at current stage? If you're cutting a whole team or capability, it's cleaner, more defensible, and recovers faster.
+
+**By performance:** If cutting across teams, higher performers stay. This is the moment where the "we have no B players" culture claim is tested.
+
+**By span of work:** Which work is critical path to the strategy you're executing now? Everything else is a candidate.
+
+**The veto question:** "Would I fight to keep this person if they said they were leaving?" If yes, they're safe. If no, they're a candidate.
+
+### The Layoff Conversation
+
+**Preparation:**
+- Legal review first. In Germany: Betriebsrat, social selection, proper notice periods. In the US: WARN Act for 50+ employees. Do not skip this.
+- Have severance paperwork ready before the conversation
+- Have IT ready to revoke access (dignity: after the conversation, not during)
+
+**The conversation:**
+- Private. Direct.
+- "We're restructuring the company and your role is being eliminated."
+- Don't blame the person. Don't say "we had to make hard choices" three times. Say it once and move on.
+- Explain severance, timeline, references clearly.
+- Answer questions. "I don't know" is acceptable for some questions. "I can't tell you" is not.
+
+**All-hands same day:**
+- You, live, as soon as individual conversations are done
+- Be honest about why and what it means for the company
+- Answer hard questions. Don't hide behind PR language.
+- Acknowledge that this is hard and that you're responsible for the decisions that led here
+
+### Survivor Guilt
+
+The people who didn't get cut will feel: relieved, guilty, scared, and angry — often all four. Don't underestimate this.
+
+Within 48 hours of the layoff:
+- Talk to every team lead individually
+- Hold a team meeting for each department
+- Be available for hard conversations
+
+The question everyone is silently asking: "Am I next?" Answer it directly, even if you can't promise the future: "I don't plan any further cuts. Here's what would have to be true for that to change."
+
+---
+
+## Part 3: Pivoting
+
+### Signals That It's Time to Pivot
+
+- Product-market fit isn't materializing despite iteration
+- Growth requires heroic sales effort on every deal
+- The customers who love you are not the customers you expected
+- You find a problem you can solve well that's adjacent to what you're doing
+- The market you targeted is smaller than you thought
+
+**The danger signal:** You're pivoting to run from failure, not toward opportunity. Pivots pulled by evidence of a better path work. Pivots pushed by exhaustion with the current path fail differently.
+
+### How to Think About the Pivot
+
+Define what you're keeping vs. what you're changing:
+- **Team**: usually keeping — the team is the asset
+- **Technology**: partially keeping — usually can be reoriented
+- **Customers**: depends — some will follow, some won't
+- **Vision**: the long-term vision often survives; the near-term path changes
+- **Brand**: sometimes requires a rename
+
+The cleanest pivots have a clear answer to: "Why are we better positioned to win at the new thing than anyone else?"
+
+### Telling the Board You're Pivoting
+
+Do not surprise the board in a board meeting. Have the conversation individually with key directors first.
+
+What to communicate:
+1. What changed — the new data or insight that's driving this
+2. What you're moving away from and why
+3. What you're moving to and why you can win there
+4. What this means for fundraising timeline and strategy
+5. What you need from them
+
+Board members hate two things: surprises and not being consulted. Give them both the information and the opportunity to contribute.
+
+### Telling Customers You're Pivoting
+
+Be direct. Don't spin it as "we're expanding our focus." If you're killing something they use, tell them clearly, with enough notice for them to plan.
+
+What customers need to know:
+- What's changing and when
+- What happens to their data / integrations / workflows
+- Who their contact is through the transition
+- What alternatives exist
+
+Customers who feel respected through a hard change sometimes become your biggest advocates. Customers who feel deceived become your loudest critics.
+
+---
+
+## Part 4: Co-Founder Conflicts
+
+### The Types of Conflict
+
+**Values/direction conflict:** You disagree fundamentally about what the company should be. This is existential and usually doesn't resolve with more conversation.
+
+**Performance conflict:** One co-founder isn't pulling their weight. This is hard but more tractable — it's addressable with clarity.
+
+**Role/scope conflict:** Unclear ownership causing friction. This is often fixable.
+
+### The Conversation You're Not Having
+
+Most co-founder conflicts fester because nobody says the real thing out loud.
+
+The real thing might be: "I don't think you're growing into what this company needs." Or: "I don't agree with the direction you're pushing us and I don't feel heard." Or: "I'm doing 70% of the work and we have equal equity."
+
+Say the real thing. Not in anger. Clearly, directly, with respect.
+
+### When It's Not Working
+
+Signs the co-founder relationship is unsalvageable:
+- You've had the real conversation and nothing changed
+- You don't trust their judgment anymore
+- You've stopped including them in important decisions
+- You're telling people (investors, team) a different story than what's true
+- The team has started choosing sides
+
+### The Separation
+
+Options in rough order of impact:
+1. **Role change** — they move to a different function where they can succeed
+2. **Advisor role** — they step out of operations, keep some equity, maintain relationship
+3. **Full exit** — they leave the company
+
+For any separation: legal counsel first. Cap table, vesting, IP assignment, competition clauses — all need to be addressed. Don't make handshake deals.
+
+How you treat the departing co-founder tells the team, the investors, and the market who you are.
+
+---
+
+## Part 5: Shutting Down a Product Line
+
+### When to Kill It
+
+- Revenue doesn't justify the cost (including the opportunity cost of what the team could be building instead)
+- It's pulling the company in a strategic direction you're not committed to
+- It requires resources disproportionate to its potential
+- Supporting it is making the rest of the product worse
+
+**The question to ask:** "If we launched this today knowing what we know, would we build it?" If no, that's your answer.
+
+### What You're Protecting
+
+The customers who use it. They trusted you with their workflow. Give them:
+- Clear timeline (90 days minimum for anything with integration dependencies)
+- Migration path to alternatives or your other products
+- Data export
+- A person they can contact with questions
+
+### Internal Communication
+
+The team that built it feels the loss personally. Acknowledge it. "This product represents real work and real care. Shutting it down is not a judgment of the team — it's a judgment about fit with where the company is going."
+
+If team members are being reassigned, not let go — make that clear immediately. The fear of job loss will dominate every other concern until you address it.
diff --git a/skills/c-level-advisor/executive-mentor/scripts/decision_matrix_scorer.py b/skills/c-level-advisor/executive-mentor/scripts/decision_matrix_scorer.py
new file mode 100644
index 00000000..f49c19b1
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/scripts/decision_matrix_scorer.py
@@ -0,0 +1,491 @@
+#!/usr/bin/env python3
+"""
+Decision Matrix Scorer — Executive Mentor Tool
+
+Weighted multi-criteria decision analysis with sensitivity testing.
+Answers: Which option wins? How fragile is that result? Where are the close calls?
+
+Usage:
+ python decision_matrix_scorer.py # Run with sample data
+ python decision_matrix_scorer.py --interactive # Interactive mode
+ python decision_matrix_scorer.py --file data.json # Load from JSON file
+
+JSON format:
+ {
+ "decision": "Description of the decision",
+ "criteria": [
+ {"name": "Criterion Name", "weight": 0.3, "description": "Optional"},
+ ...
+ ],
+ "options": [
+ {
+ "name": "Option Name",
+ "description": "Optional description",
+ "scores": {"Criterion Name": 8, "Another": 6, ...}
+ },
+ ...
+ ]
+ }
+
+Scores: 1–10 scale. Weights: must sum to 1.0 (or will be normalized).
+"""
+
+import json
+import sys
+import argparse
+from typing import List, Dict, Tuple
+
+# ─────────────────────────────────────────────────────
+# Core data structures
+# ─────────────────────────────────────────────────────
+
+def normalize_weights(criteria: List[Dict]) -> List[Dict]:
+ """Ensure weights sum to 1.0."""
+ total = sum(c["weight"] for c in criteria)
+ if abs(total - 1.0) > 0.001:
+ for c in criteria:
+ c["weight"] = c["weight"] / total
+ return criteria
+
+def score_option(option: Dict, criteria: List[Dict]) -> float:
+ """Calculate weighted score for an option."""
+ total = 0.0
+ for c in criteria:
+ score = option["scores"].get(c["name"], 5) # Default to 5 if missing
+ total += score * c["weight"]
+ return round(total, 3)
+
+def score_all(options: List[Dict], criteria: List[Dict]) -> List[Tuple[str, float]]:
+ """Return sorted list of (option_name, weighted_score)."""
+ results = []
+ for opt in options:
+ s = score_option(opt, criteria)
+ results.append((opt["name"], s))
+ return sorted(results, key=lambda x: x[1], reverse=True)
+
+# ─────────────────────────────────────────────────────
+# Sensitivity analysis
+# ─────────────────────────────────────────────────────
+
+def sensitivity_analysis(options: List[Dict], criteria: List[Dict]) -> Dict:
+ """
+ Test how result changes when each criterion's weight is varied ±30%.
+ Returns dict: criterion → {stable: bool, risk_of_flip: bool, details: str}
+ """
+ baseline = score_all(options, criteria)
+ winner = baseline[0][0]
+ results = {}
+
+ for i, c in enumerate(criteria):
+ flips = []
+ for delta in [-0.30, -0.20, -0.10, +0.10, +0.20, +0.30]:
+ # Adjust weight of criterion i, redistribute remainder proportionally
+ test_criteria = [dict(cr) for cr in criteria]
+ new_weight = max(0.01, test_criteria[i]["weight"] + delta)
+ old_weight = test_criteria[i]["weight"]
+ diff = new_weight - old_weight
+
+ # Redistribute diff across other criteria
+ others = [j for j in range(len(test_criteria)) if j != i]
+ total_other = sum(test_criteria[j]["weight"] for j in others)
+
+ if total_other > 0:
+ for j in others:
+ proportion = test_criteria[j]["weight"] / total_other
+ test_criteria[j]["weight"] -= diff * proportion
+ test_criteria[j]["weight"] = max(0.01, test_criteria[j]["weight"])
+
+ test_criteria[i]["weight"] = new_weight
+ test_criteria = normalize_weights(test_criteria)
+
+ test_results = score_all(options, test_criteria)
+ if test_results[0][0] != winner:
+ flips.append((delta, test_results[0][0]))
+
+ if flips:
+ smallest_delta = min(abs(delta) for delta, _name in flips)
+ results[c["name"]] = {
+ "stable": False,
+ "flip_at": f"±{int(smallest_delta*100)}% weight change",
+ "flip_to": flips[0][1],
+ "importance": "HIGH — result depends heavily on this weight"
+ }
+ else:
+ results[c["name"]] = {
+ "stable": True,
+ "flip_at": None,
+ "flip_to": None,
+ "importance": "LOW — winner holds even with significant weight changes"
+ }
+
+ return results
+
+def close_call_analysis(results: List[Tuple[str, float]]) -> List[Dict]:
+ """Find options within 10% of winner score — these are close calls."""
+ if not results:
+ return []
+ winner_score = results[0][1]
+ close = []
+ for name, score in results[1:]:
+ gap = winner_score - score
+ gap_pct = (gap / winner_score * 100) if winner_score > 0 else 0
+ if gap_pct <= 15:
+ close.append({
+ "name": name,
+ "score": score,
+ "gap": round(gap, 3),
+ "gap_pct": round(gap_pct, 1),
+ "verdict": "Very close — recheck assumptions" if gap_pct <= 5 else "Close — worth a second look"
+ })
+ return close
+
+def criterion_breakdown(options: List[Dict], criteria: List[Dict]) -> Dict:
+ """Show per-criterion scores for each option."""
+ breakdown = {}
+ for opt in options:
+ breakdown[opt["name"]] = {}
+ for c in criteria:
+ raw = opt["scores"].get(c["name"], 5)
+ weighted = raw * c["weight"]
+ breakdown[opt["name"]][c["name"]] = {
+ "raw": raw,
+ "weighted": round(weighted, 3),
+ "weight": f"{round(c['weight']*100)}%"
+ }
+ return breakdown
+
+# ─────────────────────────────────────────────────────
+# Output formatting
+# ─────────────────────────────────────────────────────
+
+def hr(char="─", width=65):
+ return char * width
+
+def print_report(data: Dict):
+ """Print the full decision analysis report."""
+ decision = data.get("decision", "Unnamed Decision")
+ criteria = normalize_weights(data["criteria"])
+ options = data["options"]
+
+ print()
+ print(hr("═"))
+ print(f" DECISION MATRIX ANALYSIS")
+ print(f" {decision}")
+ print(hr("═"))
+
+ # ── Criteria summary
+ print()
+ print("CRITERIA & WEIGHTS")
+ print(hr())
+ for c in sorted(criteria, key=lambda x: x["weight"], reverse=True):
+ bar_len = int(c["weight"] * 30)
+ bar = "█" * bar_len
+ desc = f" — {c['description']}" if c.get("description") else ""
+ print(f" {c['name']:<25} {c['weight']*100:>5.1f}% {bar}{desc}")
+
+ # ── Scoring results
+ print()
+ print("RESULTS (ranked)")
+ print(hr())
+ results = score_all(options, criteria)
+ max_score = 10.0 # max possible weighted score
+ for rank, (name, score) in enumerate(results, 1):
+ pct = score / 10.0
+ bar_len = int(pct * 40)
+ bar = "█" * bar_len
+ medal = ["🥇", "🥈", "🥉"][rank-1] if rank <= 3 else f"#{rank} "
+ print(f" {medal} {name:<25} {score:>5.2f}/10 {bar}")
+
+ winner = results[0][0]
+ print()
+ print(f" ► Winner: {winner} (score: {results[0][1]:.2f})")
+
+ # ── Close calls
+ close = close_call_analysis(results)
+ if close:
+ print()
+ print("CLOSE CALLS")
+ print(hr())
+ for c in close:
+ print(f" ⚠ {c['name']}: {c['score']:.2f} (gap: {c['gap_pct']}% — {c['verdict']})")
+
+ # ── Per-criterion breakdown
+ print()
+ print("SCORE BREAKDOWN BY CRITERION")
+ print(hr())
+ breakdown = criterion_breakdown(options, criteria)
+
+ # Header
+ opt_names = [opt["name"][:16] for opt in options]
+ header = f" {'Criterion':<22}"
+ for n in opt_names:
+ header += f" {n:>10}"
+ print(header)
+ print(" " + hr("-", 63))
+
+ for c in criteria:
+ row = f" {c['name']:<22}"
+ for opt in options:
+ raw = opt["scores"].get(c["name"], 5)
+ row += f" {raw:>10}"
+ row += f" (weight {c['weight']*100:.0f}%)"
+ print(row)
+
+ # Weighted row
+ print(" " + hr("-", 63))
+ weighted_row = f" {'Weighted Total':<22}"
+ for name, score in results:
+ # Re-order by options list order
+ weighted_row += f" {score:>10.2f}"
+ # Actually print in options order
+ print(f" {'Weighted Total':<22}", end="")
+ for opt in options:
+ s = score_option(opt, criteria)
+ print(f" {s:>10.2f}", end="")
+ print()
+
+ # ── Sensitivity analysis
+ print()
+ print("SENSITIVITY ANALYSIS")
+ print(hr())
+ print(" How much does the winner change if we adjust criterion weights?")
+ print()
+ sensitivity = sensitivity_analysis(options, criteria)
+ for crit_name, result in sensitivity.items():
+ if result["stable"]:
+ print(f" ✓ {crit_name:<28} STABLE — winner holds at ±30% weight change")
+ else:
+ print(f" ⚠ {crit_name:<28} FRAGILE — flips to '{result['flip_to']}' at {result['flip_at']}")
+
+ # ── Recommendation
+ print()
+ print("RECOMMENDATION")
+ print(hr())
+ unstable = [k for k, v in sensitivity.items() if not v["stable"]]
+ if unstable:
+ print(f" Winner: {winner}")
+ print(f" Confidence: MEDIUM — result is sensitive to weights on: {', '.join(unstable)}")
+ print()
+ print(" Before committing:")
+ print(f" • Validate that your weighting of [{', '.join(unstable)}] is correct")
+ print(" • Consider whether the weight differences reflect genuine priorities")
+ print(" • If uncertain, run scenario with alternative weights")
+ else:
+ print(f" Winner: {winner}")
+ print(f" Confidence: HIGH — winner is stable across all weight scenarios")
+ print()
+ print(" The decision is clear. The main risk is whether your scoring")
+ print(" of each option on each criterion is accurate.")
+
+ print()
+ print(hr("═"))
+ print()
+
+# ─────────────────────────────────────────────────────
+# Interactive mode
+# ─────────────────────────────────────────────────────
+
+def interactive_mode():
+ """Guided interactive data entry."""
+ print()
+ print(hr("═"))
+ print(" DECISION MATRIX — Interactive Mode")
+ print(hr("═"))
+
+ data = {}
+ data["decision"] = input("\nWhat decision are you making?\n> ").strip()
+
+ # Criteria
+ print("\nDefine criteria (what matters in this decision).")
+ print("Enter criteria one at a time. Empty line to finish.")
+ print("Weight: importance 0–10 (will be normalized to %).")
+ print()
+
+ criteria = []
+ while True:
+ name = input(f"Criterion {len(criteria)+1} name (or ENTER to finish): ").strip()
+ if not name:
+ if len(criteria) < 2:
+ print(" Need at least 2 criteria.")
+ continue
+ break
+ weight_str = input(f" Weight for '{name}' (0–10): ").strip()
+ try:
+ weight = float(weight_str)
+ except ValueError:
+ weight = 5.0
+ criteria.append({"name": name, "weight": weight})
+
+ data["criteria"] = criteria
+
+ # Options
+ print("\nDefine options (what you're choosing between).")
+ print("Enter options one at a time. Empty line to finish.")
+ print()
+
+ options = []
+ while True:
+ name = input(f"Option {len(options)+1} name (or ENTER to finish): ").strip()
+ if not name:
+ if len(options) < 2:
+ print(" Need at least 2 options.")
+ continue
+ break
+
+ print(f"\n Score each criterion for '{name}' (1=poor, 10=excellent):")
+ scores = {}
+ for c in criteria:
+ while True:
+ s = input(f" {c['name']}: ").strip()
+ try:
+ score = float(s)
+ if 1 <= score <= 10:
+ scores[c["name"]] = score
+ break
+ else:
+ print(" Score must be 1–10")
+ except ValueError:
+ print(" Enter a number 1–10")
+
+ options.append({"name": name, "scores": scores})
+ print()
+
+ data["options"] = options
+ print_report(data)
+
+# ─────────────────────────────────────────────────────
+# Sample data
+# ─────────────────────────────────────────────────────
+
+SAMPLE_DATA = {
+ "decision": "How to extend runway: Cut costs vs. Raise bridge vs. Accelerate revenue",
+ "criteria": [
+ {
+ "name": "Speed to impact",
+ "weight": 0.25,
+ "description": "How quickly does this improve our situation?"
+ },
+ {
+ "name": "Execution risk",
+ "weight": 0.30,
+ "description": "How likely is this to actually work? (10=low risk)"
+ },
+ {
+ "name": "Team morale impact",
+ "weight": 0.20,
+ "description": "Effect on team (10=positive, 1=very negative)"
+ },
+ {
+ "name": "Runway extension",
+ "weight": 0.15,
+ "description": "How much runway does this actually buy?"
+ },
+ {
+ "name": "Strategic fit",
+ "weight": 0.10,
+ "description": "Does this align with where we want to go?"
+ }
+ ],
+ "options": [
+ {
+ "name": "Cost cut 25%",
+ "description": "Reduce headcount and discretionary spend by 25%",
+ "scores": {
+ "Speed to impact": 9,
+ "Execution risk": 8,
+ "Team morale impact": 2,
+ "Runway extension": 8,
+ "Strategic fit": 5
+ }
+ },
+ {
+ "name": "Bridge from investors",
+ "description": "Raise $500K bridge from existing investors to hit next milestone",
+ "scores": {
+ "Speed to impact": 6,
+ "Execution risk": 5,
+ "Team morale impact": 7,
+ "Runway extension": 6,
+ "Strategic fit": 7
+ }
+ },
+ {
+ "name": "Accelerate revenue",
+ "description": "Push 3 enterprise deals hard, offer incentives for Q4 close",
+ "scores": {
+ "Speed to impact": 4,
+ "Execution risk": 3,
+ "Team morale impact": 9,
+ "Runway extension": 9,
+ "Strategic fit": 10
+ }
+ },
+ {
+ "name": "Hybrid: cut 15% + bridge",
+ "description": "Smaller cuts combined with a modest bridge round",
+ "scores": {
+ "Speed to impact": 7,
+ "Execution risk": 6,
+ "Team morale impact": 5,
+ "Runway extension": 7,
+ "Strategic fit": 6
+ }
+ }
+ ]
+}
+
+# ─────────────────────────────────────────────────────
+# Main
+# ─────────────────────────────────────────────────────
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Decision Matrix Scorer — weighted analysis with sensitivity testing"
+ )
+ parser.add_argument(
+ "--interactive", "-i",
+ action="store_true",
+ help="Interactive mode: enter decision data manually"
+ )
+ parser.add_argument(
+ "--file", "-f",
+ type=str,
+ help="Load decision data from JSON file"
+ )
+ parser.add_argument(
+ "--sample",
+ action="store_true",
+ help="Show sample data structure and exit"
+ )
+
+ args = parser.parse_args()
+
+ if args.sample:
+ print(json.dumps(SAMPLE_DATA, indent=2))
+ return
+
+ if args.interactive:
+ interactive_mode()
+ return
+
+ if args.file:
+ try:
+ with open(args.file) as f:
+ data = json.load(f)
+ print_report(data)
+ except FileNotFoundError:
+ print(f"Error: File '{args.file}' not found.")
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in '{args.file}': {e}")
+ sys.exit(1)
+ return
+
+ # Default: run sample data
+ print()
+ print("Running with sample data. Use --interactive for custom input or --file for JSON.")
+ print_report(SAMPLE_DATA)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/executive-mentor/scripts/stakeholder_mapper.py b/skills/c-level-advisor/executive-mentor/scripts/stakeholder_mapper.py
new file mode 100644
index 00000000..6c41412b
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/scripts/stakeholder_mapper.py
@@ -0,0 +1,547 @@
+#!/usr/bin/env python3
+"""
+Stakeholder Mapper — Executive Mentor Tool
+
+Maps stakeholders by influence and alignment.
+Identifies: champions, blockers, swing votes, and hidden risks.
+Outputs: stakeholder grid with engagement strategy per quadrant.
+
+Usage:
+ python stakeholder_mapper.py # Run with sample data
+ python stakeholder_mapper.py --interactive # Interactive mode
+ python stakeholder_mapper.py --file data.json # Load from JSON file
+
+JSON format:
+ {
+ "initiative": "Name of the decision or initiative",
+ "stakeholders": [
+ {
+ "name": "Person/Group Name",
+ "role": "Their role or title",
+ "influence": 8, // 1–10: how much power they have over outcome
+ "alignment": 3, // 1–10: how supportive they are (10=champion, 1=blocker)
+ "interest": 7, // 1–10: how interested/engaged they are
+ "notes": "Optional context — what drives them, hidden concerns, relationships"
+ }
+ ]
+ }
+"""
+
+import json
+import sys
+import argparse
+from typing import List, Dict, Tuple, Optional
+
+# ─────────────────────────────────────────────────────
+# Quadrant classification
+# ─────────────────────────────────────────────────────
+
+def classify_stakeholder(influence: float, alignment: float) -> Dict:
+ """
+ Classify into strategic quadrant based on influence and alignment.
+
+ Quadrants:
+ - Champions (high influence, high alignment): Your most valuable assets
+ - Blockers (high influence, low alignment): Your biggest risks
+ - Supporters (low influence, high alignment): Useful but less critical
+ - Bystanders (low influence, low alignment): Monitor, low priority
+ - Swing Votes (medium influence, medium alignment): Key to persuade
+ """
+ mid_influence = 5.5
+ mid_alignment = 5.5
+
+ # Special case: swing votes — medium on both dimensions
+ if 4 <= influence <= 7 and 4 <= alignment <= 7:
+ return {
+ "quadrant": "Swing Vote",
+ "symbol": "⚡",
+ "priority": "HIGH",
+ "strategy": "Persuade — understand concerns, address directly, build relationship"
+ }
+
+ if influence >= mid_influence and alignment >= mid_alignment:
+ return {
+ "quadrant": "Champion",
+ "symbol": "★",
+ "priority": "HIGH",
+ "strategy": "Leverage — activate them as advocates, give them a role in the initiative"
+ }
+ elif influence >= mid_influence and alignment < mid_alignment:
+ return {
+ "quadrant": "Blocker",
+ "symbol": "✖",
+ "priority": "CRITICAL",
+ "strategy": "Address — understand their specific objections, find common ground or neutralize"
+ }
+ elif influence < mid_influence and alignment >= mid_alignment:
+ return {
+ "quadrant": "Supporter",
+ "symbol": "○",
+ "priority": "MEDIUM",
+ "strategy": "Maintain — keep informed and engaged, potentially increase their influence"
+ }
+ else:
+ return {
+ "quadrant": "Bystander",
+ "symbol": "·",
+ "priority": "LOW",
+ "strategy": "Monitor — minimal investment, keep informed with standard comms"
+ }
+
+def risk_flags(stakeholder: Dict) -> List[str]:
+ """Identify specific risk signals for a stakeholder."""
+ flags = []
+ influence = stakeholder["influence"]
+ alignment = stakeholder["alignment"]
+ interest = stakeholder.get("interest", 5)
+
+ if influence >= 7 and alignment <= 3:
+ flags.append("🔴 HIGH-POWER BLOCKER — can kill this initiative")
+
+ if influence >= 7 and alignment <= 5 and interest >= 7:
+ flags.append("🟡 ENGAGED SKEPTIC — high influence, paying close attention, not convinced")
+
+ if alignment <= 4 and interest >= 8:
+ flags.append("🟡 ACTIVE OPPOSITION — low alignment but highly engaged — may mobilize others")
+
+ if influence >= 6 and alignment >= 7 and interest <= 3:
+ flags.append("🟡 DISENGAGED CHAMPION — strong supporter but not paying attention — needs activation")
+
+ if influence >= 5 and 4 <= alignment <= 6:
+ flags.append("⚡ PERSUADABLE — medium influence, genuinely undecided — high ROI to engage")
+
+ return flags
+
+# ─────────────────────────────────────────────────────
+# Analysis
+# ─────────────────────────────────────────────────────
+
+def calculate_overall_alignment(stakeholders: List[Dict]) -> Dict:
+ """Calculate weighted average alignment (weighted by influence)."""
+ if not stakeholders:
+ return {"score": 0, "verdict": "No data"}
+
+ total_influence = sum(s["influence"] for s in stakeholders)
+ if total_influence == 0:
+ return {"score": 0, "verdict": "No influence"}
+
+ weighted_alignment = sum(
+ s["alignment"] * s["influence"] for s in stakeholders
+ ) / total_influence
+
+ if weighted_alignment >= 7:
+ verdict = "FAVORABLE — strong support among influential stakeholders"
+ elif weighted_alignment >= 5:
+ verdict = "MIXED — significant opposition needs to be addressed"
+ else:
+ verdict = "UNFAVORABLE — initiative faces significant headwinds"
+
+ return {
+ "score": round(weighted_alignment, 2),
+ "verdict": verdict
+ }
+
+def find_critical_path(stakeholders: List[Dict]) -> List[Dict]:
+ """
+ Identify the minimal set of stakeholders whose alignment is critical.
+ These are high-influence stakeholders — their position determines the outcome.
+ """
+ high_influence = [s for s in stakeholders if s["influence"] >= 7]
+ return sorted(high_influence, key=lambda x: x["influence"], reverse=True)
+
+def engagement_sequencing(stakeholders: List[Dict]) -> List[Dict]:
+ """
+ Recommend engagement sequence.
+ Order: Fix blockers → Activate champions → Persuade swing votes → Maintain rest.
+ """
+ classified = []
+ for s in stakeholders:
+ cls = classify_stakeholder(s["influence"], s["alignment"])
+ classified.append({**s, **cls})
+
+ # Sort by engagement priority
+ priority_order = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
+ classified.sort(key=lambda x: (priority_order[x["priority"]], -x["influence"]))
+
+ return classified
+
+# ─────────────────────────────────────────────────────
+# ASCII grid visualization
+# ─────────────────────────────────────────────────────
+
+def render_grid(stakeholders: List[Dict], width: int = 60) -> str:
+ """
+ Render a 2D influence vs alignment grid with stakeholder positions.
+ Y-axis: Influence (top = high)
+ X-axis: Alignment (left = low, right = high)
+ """
+ rows = 10
+ cols = 20
+
+ grid = [[' ' for _ in range(cols)] for _ in range(rows)]
+
+ for s in stakeholders:
+ influence = s["influence"]
+ alignment = s["alignment"]
+
+ # Map scores 1–10 to grid coordinates
+ col = int((alignment - 1) / 9 * (cols - 1))
+ row = rows - 1 - int((influence - 1) / 9 * (rows - 1))
+
+ col = max(0, min(cols - 1, col))
+ row = max(0, min(rows - 1, row))
+
+ initial = s["name"][0].upper()
+ if grid[row][col] == ' ':
+ grid[row][col] = initial
+ else:
+ grid[row][col] = '+' # Overlap
+
+ lines = []
+ lines.append(" STAKEHOLDER MAP (Influence ↑ | Alignment →)")
+ lines.append("")
+ lines.append(f" HIGH ┌{'─'*cols}┐")
+
+ for i, row in enumerate(grid):
+ if i == rows // 2:
+ prefix = " INFL "
+ else:
+ prefix = " "
+ lines.append(f"{prefix}│{''.join(row)}│")
+
+ lines.append(f" LOW └{'─'*cols}┘")
+ lines.append(f" {'BLOCKER':<12} {'SWING':<8} CHAMPION")
+ lines.append(f" Low alignment High alignment")
+ lines.append("")
+
+ # Legend
+ lines.append(" Legend (initials):")
+ for s in stakeholders:
+ cls = classify_stakeholder(s["influence"], s["alignment"])
+ lines.append(f" {s['name'][0].upper()} = {s['name']} ({cls['symbol']} {cls['quadrant']})")
+
+ return "\n".join(lines)
+
+# ─────────────────────────────────────────────────────
+# Output formatting
+# ─────────────────────────────────────────────────────
+
+def hr(char="─", width=65):
+ return char * width
+
+def print_report(data: Dict):
+ initiative = data.get("initiative", "Unnamed Initiative")
+ stakeholders = data["stakeholders"]
+
+ # Validate and fill defaults
+ for s in stakeholders:
+ s.setdefault("interest", 5)
+ s.setdefault("notes", "")
+ s["influence"] = max(1, min(10, float(s["influence"])))
+ s["alignment"] = max(1, min(10, float(s["alignment"])))
+ s["interest"] = max(1, min(10, float(s["interest"])))
+
+ print()
+ print(hr("═"))
+ print(f" STAKEHOLDER ANALYSIS")
+ print(f" {initiative}")
+ print(hr("═"))
+
+ # Overall assessment
+ overall = calculate_overall_alignment(stakeholders)
+ print()
+ print("OVERALL ASSESSMENT")
+ print(hr())
+ print(f" Weighted alignment score: {overall['score']}/10")
+ print(f" Verdict: {overall['verdict']}")
+
+ # Grid visualization
+ print()
+ print(hr())
+ print(render_grid(stakeholders))
+
+ # Stakeholder profiles by quadrant
+ sequenced = engagement_sequencing(stakeholders)
+
+ # Group by quadrant
+ quadrants = {}
+ for s in sequenced:
+ q = s["quadrant"]
+ if q not in quadrants:
+ quadrants[q] = []
+ quadrants[q].append(s)
+
+ quadrant_order = ["Blocker", "Swing Vote", "Champion", "Supporter", "Bystander"]
+
+ print()
+ print("STAKEHOLDER PROFILES")
+ print(hr())
+
+ for q_name in quadrant_order:
+ if q_name not in quadrants:
+ continue
+ group = quadrants[q_name]
+ first = group[0]
+ print()
+ print(f" {first['symbol']} {q_name.upper()}S ({len(group)} stakeholder{'s' if len(group)>1 else ''})")
+ print(f" Strategy: {first['strategy']}")
+ print()
+
+ for s in group:
+ cls = classify_stakeholder(s["influence"], s["alignment"])
+ flags = risk_flags(s)
+
+ print(f" {s['name']}")
+ print(f" Role: {s.get('role', 'Not specified')}")
+ print(f" Influence: {'█'*int(s['influence']//2)}{'░'*(5-int(s['influence']//2))} {s['influence']:.0f}/10 "
+ f"Alignment: {'█'*int(s['alignment']//2)}{'░'*(5-int(s['alignment']//2))} {s['alignment']:.0f}/10 "
+ f"Interest: {'█'*int(s['interest']//2)}{'░'*(5-int(s['interest']//2))} {s['interest']:.0f}/10")
+
+ if flags:
+ for flag in flags:
+ print(f" {flag}")
+
+ if s.get("notes"):
+ print(f" Notes: {s['notes']}")
+
+ print()
+
+ # Engagement plan
+ print()
+ print("ENGAGEMENT PLAN (sequenced by priority)")
+ print(hr())
+ print()
+ print(f" {'#':<3} {'Name':<22} {'Quadrant':<14} {'Priority':<10} {'First Action'}")
+ print(f" {hr('-', 63)}")
+
+ actions = {
+ "Blocker": "Schedule 1:1 — understand specific objections",
+ "Swing Vote": "Coffee or informal conversation — listen first",
+ "Champion": "Brief them on the initiative — give them a role",
+ "Supporter": "Keep informed — monthly update or email",
+ "Bystander": "Include in standard comms only"
+ }
+
+ for i, s in enumerate(sequenced, 1):
+ action = actions.get(s["quadrant"], "Maintain standard communication")
+ print(f" {i:<3} {s['name']:<22} {s['quadrant']:<14} {s['priority']:<10} {action}")
+
+ # Risk summary
+ print()
+ print("RISK SUMMARY")
+ print(hr())
+
+ critical_path = find_critical_path(stakeholders)
+ if critical_path:
+ print()
+ print(" High-influence stakeholders (outcome depends on these):")
+ for s in critical_path:
+ cls = classify_stakeholder(s["influence"], s["alignment"])
+ alignment_label = "CHAMPION" if s["alignment"] >= 7 else "BLOCKER" if s["alignment"] <= 4 else "UNDECIDED"
+ print(f" {cls['symbol']} {s['name']:<25} influence {s['influence']:.0f}/10 → {alignment_label}")
+
+ # All risk flags
+ all_flags = []
+ for s in stakeholders:
+ flags = risk_flags(s)
+ for flag in flags:
+ all_flags.append((s["name"], flag))
+
+ if all_flags:
+ print()
+ print(" Risk flags:")
+ for name, flag in all_flags:
+ print(f" [{name}] {flag}")
+
+ print()
+ print(hr("═"))
+ print()
+
+# ─────────────────────────────────────────────────────
+# Interactive mode
+# ─────────────────────────────────────────────────────
+
+def interactive_mode():
+ print()
+ print(hr("═"))
+ print(" STAKEHOLDER MAPPER — Interactive Mode")
+ print(hr("═"))
+
+ data = {}
+ data["initiative"] = input("\nWhat initiative or decision are you mapping?\n> ").strip()
+
+ print("\nAdd stakeholders one at a time. Empty name to finish.")
+ print("Scores: 1=low, 10=high")
+ print()
+
+ stakeholders = []
+ while True:
+ name = input(f"Stakeholder {len(stakeholders)+1} name (or ENTER to finish): ").strip()
+ if not name:
+ if len(stakeholders) < 1:
+ print(" Need at least 1 stakeholder.")
+ continue
+ break
+
+ role = input(f" Role/title: ").strip()
+
+ def get_score(prompt, default=5):
+ while True:
+ s = input(f" {prompt} (1–10, default {default}): ").strip()
+ if not s:
+ return float(default)
+ try:
+ v = float(s)
+ if 1 <= v <= 10:
+ return v
+ print(" Must be 1–10")
+ except ValueError:
+ print(" Enter a number")
+
+ influence = get_score("Influence (power over this decision)")
+ alignment = get_score("Alignment (1=opposed, 10=champion)")
+ interest = get_score("Interest level (how engaged are they)")
+ notes = input(f" Notes (optional): ").strip()
+
+ stakeholders.append({
+ "name": name,
+ "role": role,
+ "influence": influence,
+ "alignment": alignment,
+ "interest": interest,
+ "notes": notes
+ })
+ print()
+
+ data["stakeholders"] = stakeholders
+ print_report(data)
+
+# ─────────────────────────────────────────────────────
+# Sample data
+# ─────────────────────────────────────────────────────
+
+SAMPLE_DATA = {
+ "initiative": "Migrate from monolith to microservices (18-month program)",
+ "stakeholders": [
+ {
+ "name": "Sarah Chen (CTO)",
+ "role": "Chief Technology Officer",
+ "influence": 10,
+ "alignment": 9,
+ "interest": 9,
+ "notes": "Driving force behind the initiative. Will fund and protect the team."
+ },
+ {
+ "name": "Marcus Webb (CFO)",
+ "role": "Chief Financial Officer",
+ "influence": 9,
+ "alignment": 3,
+ "interest": 6,
+ "notes": "Concerned about 18-month cost with no visible revenue return. Has budget veto."
+ },
+ {
+ "name": "Priya Agarwal (VP Eng)",
+ "role": "VP Engineering",
+ "influence": 8,
+ "alignment": 7,
+ "interest": 8,
+ "notes": "Supportive in principle, worried about team bandwidth alongside feature delivery."
+ },
+ {
+ "name": "Tom Briggs (VP Product)",
+ "role": "VP Product",
+ "influence": 7,
+ "alignment": 4,
+ "interest": 5,
+ "notes": "Concerned about roadmap slowdown. Hasn't been in the architecture discussions."
+ },
+ {
+ "name": "Elena Park (CEO)",
+ "role": "Chief Executive Officer",
+ "influence": 10,
+ "alignment": 6,
+ "interest": 4,
+ "notes": "Trusts the CTO but will back out if CFO and VP Product both push back hard."
+ },
+ {
+ "name": "Raj Patel (Lead Arch)",
+ "role": "Lead Architect",
+ "influence": 6,
+ "alignment": 10,
+ "interest": 10,
+ "notes": "Deep technical champion. Has proposed detailed migration plan."
+ },
+ {
+ "name": "Dev Team Leads (x4)",
+ "role": "Team Leads",
+ "influence": 5,
+ "alignment": 6,
+ "interest": 7,
+ "notes": "Mixed. Some excited, some worried about learning curve. Middle ground."
+ },
+ {
+ "name": "Board (investor reps)",
+ "role": "Board Directors",
+ "influence": 9,
+ "alignment": 5,
+ "interest": 3,
+ "notes": "Not paying attention unless CFO raises flags. Could become blockers if CFO escalates."
+ }
+ ]
+}
+
+# ─────────────────────────────────────────────────────
+# Main
+# ─────────────────────────────────────────────────────
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Stakeholder Mapper — influence, alignment, and engagement strategy"
+ )
+ parser.add_argument(
+ "--interactive", "-i",
+ action="store_true",
+ help="Interactive mode: enter stakeholder data manually"
+ )
+ parser.add_argument(
+ "--file", "-f",
+ type=str,
+ help="Load stakeholder data from JSON file"
+ )
+ parser.add_argument(
+ "--sample",
+ action="store_true",
+ help="Print sample JSON structure and exit"
+ )
+
+ args = parser.parse_args()
+
+ if args.sample:
+ print(json.dumps(SAMPLE_DATA, indent=2))
+ return
+
+ if args.interactive:
+ interactive_mode()
+ return
+
+ if args.file:
+ try:
+ with open(args.file) as f:
+ data = json.load(f)
+ print_report(data)
+ except FileNotFoundError:
+ print(f"Error: File '{args.file}' not found.")
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in '{args.file}': {e}")
+ sys.exit(1)
+ return
+
+ # Default: sample data
+ print()
+ print("Running with sample data. Use --interactive for custom input or --file for JSON.")
+ print_report(SAMPLE_DATA)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/executive-mentor/skills/board-prep/SKILL.md b/skills/c-level-advisor/executive-mentor/skills/board-prep/SKILL.md
new file mode 100644
index 00000000..27450563
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/skills/board-prep/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: "board-prep"
+description: "/em -board-prep — Board Meeting Preparation"
+---
+
+# /em:board-prep — Board Meeting Preparation
+
+**Command:** `/em:board-prep `
+
+Prepare for the adversarial version of your board, not the friendly one. Every hard question they'll ask. Every number you need cold. The narrative that acknowledges weakness without losing the room.
+
+---
+
+## The Reality of Board Meetings
+
+Your board members have seen 50+ companies. They've watched founders flinch at their own numbers, spin bad news as "learning opportunities," and present sanitized decks that hide what's actually happening.
+
+They know when you're not being straight with them. The question isn't whether they'll ask the hard questions — it's whether you're ready for them.
+
+The best board meetings aren't the ones where everything looks good. They're the ones where the CEO demonstrates they see reality clearly, have a plan, and can execute under pressure.
+
+---
+
+## The Preparation Framework
+
+### Phase 1: Numbers Cold
+
+Before the meeting, every number in your deck should live in your head, not just the slide.
+
+**The numbers you must know without looking:**
+- Current MRR / ARR and month-over-month growth rate
+- Burn rate (monthly) and runway (months at current burn)
+- Headcount by department
+- CAC and LTV by channel / segment
+- Net Revenue Retention
+- Pipeline: value, conversion rate, average sales cycle
+- Churn: rate, top reasons, top churned accounts
+- Gross margin (product), net margin (company)
+- Key hiring positions open and time-to-fill
+
+**Stress test yourself:** Can you answer "what's your burn?" without hesitation? "What's your churn rate by segment?" If you pause, you don't know it.
+
+### Phase 2: Anticipate the Hard Questions
+
+For every item on the agenda, generate the adversarial version of the question.
+
+**Standard adversarial questions by topic:**
+
+*Revenue performance:*
+- "You missed revenue by 20% this quarter. What specifically failed?"
+- "Is this a pipeline problem, a conversion problem, or a capacity problem?"
+- "If you missed because of one big deal, how dependent is your model on individual deals?"
+- "When do you project recovery and what are the leading indicators you're right?"
+
+*Runway / burn:*
+- "At current burn you have N months. What's your plan if the next round takes 9 months?"
+- "What would you cut first if you had to extend runway by 6 months today?"
+- "Is there a scenario where you don't raise another round?"
+
+*Product / roadmap:*
+- "You shipped X. What did customers actually do with it?"
+- "What did you kill this quarter and why?"
+- "Where are you behind on roadmap? What's slipping?"
+
+*Team:*
+- "Who's at risk of leaving? How would that affect execution?"
+- "You've had 3 VP-level hires not work out. What pattern do you see?"
+- "Is the team the right team for this stage?"
+
+*Competition:*
+- "Competitor Y just raised $50M. How does that change your position?"
+- "If they copy your best feature in 90 days, what's your moat?"
+
+### Phase 3: Build the Narrative
+
+The board meeting isn't a status update. It's a leadership demonstration.
+
+**The structure that works:**
+
+1. **Where we are (honest)** — Current state of business, the real number, not the smoothed one
+2. **What we learned** — What the data is telling us that we didn't know 90 days ago
+3. **What we got wrong** — Name it directly. Don't make them ask.
+4. **What we're doing about it** — Specific, dated, owned actions
+5. **What we need from this room** — Concrete ask. Not "support" — specific introductions, decisions, resources.
+
+**The rule on bad news:** Never let the board be surprised. If a quarter went badly, they should know before the deck. A 5-sentence email 3 days before: "Revenue came in at $X vs $Y target. Here's what happened, here's what I'm doing, here's what I need from you."
+
+### Phase 4: Adversarial Preparation
+
+Do a mock board meeting. Have someone play the hardest director you have.
+
+**The simulation:**
+- Present your deck as you would
+- The mock director asks every uncomfortable question
+- You answer without referring to the deck
+- After: note every question that made you pause or feel defensive
+
+**The questions that made you defensive = the questions you need to prepare for.**
+
+### Phase 5: Director-by-Director Prep
+
+Not all board members want the same thing from a meeting.
+
+**For each director, know:**
+- Their primary concern right now (usually tied to their investment thesis)
+- The metric they watch most closely
+- What would make them lose confidence in you
+- What they've said in the last meeting that you should address
+
+**Common director types:**
+- **The operator** — wants to know what's breaking and who owns fixing it
+- **The financial investor** — focused on path to profitability or next raise
+- **The strategic investor** — worried about competitive position and moat
+- **The independent** — watching governance, team dynamics, and your judgment
+
+---
+
+## Pre-Meeting Checklist
+
+**48 hours before:**
+- [ ] All numbers verified against source systems (not last week's export)
+- [ ] Deck reviewed for internal consistency
+- [ ] Pre-read sent to board (deck + 1-page brief on key topics)
+- [ ] One-on-ones done with any director likely to have concerns
+- [ ] 3 hardest questions you expect — rehearsed out loud
+
+**Day of meeting:**
+- [ ] Agenda with time allocations distributed
+- [ ] Know the ask for each agenda item (decision needed, input wanted, FYI)
+- [ ] Materials to leave behind prepared
+- [ ] Follow-up action template ready
+
+---
+
+## During the Meeting
+
+**What the board is watching:**
+- Do you own the bad news or deflect it?
+- Are you defending a narrative or sharing reality?
+- Do you know your numbers or do you look things up?
+- When challenged, do you get defensive or engage?
+- Do you know what you don't know?
+
+**The single best thing you can do:** Name the hard thing before they do. "I want to address the revenue miss directly. Here's what happened, here's what I should have caught earlier, here's what changes."
+
+---
+
+## After the Meeting
+
+Within 24 hours:
+- Send action items with owners and dates
+- Send any data you promised but didn't have
+- Note the questions that came up you weren't ready for
+- Schedule follow-up with any director who seemed unsatisfied
+
+The next board prep starts now.
diff --git a/skills/c-level-advisor/executive-mentor/skills/challenge/SKILL.md b/skills/c-level-advisor/executive-mentor/skills/challenge/SKILL.md
new file mode 100644
index 00000000..08ca7c58
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/skills/challenge/SKILL.md
@@ -0,0 +1,181 @@
+---
+name: "challenge"
+description: "/em -challenge — Pre-Mortem Plan Analysis"
+---
+
+# /em:challenge — Pre-Mortem Plan Analysis
+
+**Command:** `/em:challenge `
+
+Systematically finds weaknesses in any plan before reality does. Not to kill the plan — to make it survive contact with reality.
+
+---
+
+## The Core Idea
+
+Most plans fail for predictable reasons. Not bad luck — bad assumptions. Overestimated demand. Underestimated complexity. Dependencies nobody questioned. Timing that made sense in a spreadsheet but not in the real world.
+
+The pre-mortem technique: **imagine it's 12 months from now and this plan failed spectacularly. Now work backwards. Why?**
+
+That's not pessimism. It's how you build something that doesn't collapse.
+
+---
+
+## When to Run a Challenge
+
+- Before committing significant resources to a plan
+- Before presenting to the board or investors
+- When you notice you're only hearing positive feedback about the plan
+- When the plan requires multiple external dependencies to align
+- When there's pressure to move fast and "figure it out later"
+- When you feel excited about the plan (excitement is a signal to scrutinize harder)
+
+---
+
+## The Challenge Framework
+
+### Step 1: Extract Core Assumptions
+Before you can test a plan, you need to surface everything it assumes to be true.
+
+For each section of the plan, ask:
+- What has to be true for this to work?
+- What are we assuming about customer behavior?
+- What are we assuming about competitor response?
+- What are we assuming about our own execution capability?
+- What external factors does this depend on?
+
+**Common assumption categories:**
+- **Market assumptions** — size, growth rate, customer willingness to pay, buying cycle
+- **Execution assumptions** — team capacity, velocity, no major hires needed
+- **Customer assumptions** — they have the problem, they know they have it, they'll pay to solve it
+- **Competitive assumptions** — incumbents won't respond, no new entrant, moat holds
+- **Financial assumptions** — burn rate, revenue timing, CAC, LTV ratios
+- **Dependency assumptions** — partner will deliver, API won't change, regulations won't shift
+
+### Step 2: Rate Each Assumption
+
+For every assumption extracted, rate it on two dimensions:
+
+**Confidence level (how sure are you this is true):**
+- **High** — verified with data, customer conversations, market research
+- **Medium** — directionally right but not validated
+- **Low** — plausible but untested
+- **Unknown** — we simply don't know
+
+**Impact if wrong (what happens if this assumption fails):**
+- **Critical** — plan fails entirely
+- **High** — major delay or cost overrun
+- **Medium** — significant rework required
+- **Low** — manageable adjustment
+
+### Step 3: Map Vulnerabilities
+
+The matrix of Low/Unknown confidence × Critical/High impact = your highest-risk assumptions.
+
+**Vulnerability = Low confidence + High impact**
+
+These are not problems to ignore. They're the bets you're making. The question is: are you making them consciously?
+
+### Step 4: Find the Dependency Chain
+
+Many plans fail not because any single assumption is wrong, but because multiple assumptions have to be right simultaneously.
+
+Map the chain:
+- Does assumption B depend on assumption A being true first?
+- If the first thing goes wrong, how many downstream things break?
+- What's the critical path? What has zero slack?
+
+### Step 5: Test the Reversibility
+
+For each critical vulnerability: if this assumption turns out to be wrong at month 3, what do you do?
+
+- Can you pivot?
+- Can you cut scope?
+- Is money already spent?
+- Are commitments already made?
+
+The less reversible, the more rigorously you need to validate before committing.
+
+---
+
+## Output Format
+
+**Challenge Report: [Plan Name]**
+
+```
+CORE ASSUMPTIONS (extracted)
+1. [Assumption] — Confidence: [H/M/L/?] — Impact if wrong: [Critical/High/Medium/Low]
+2. ...
+
+VULNERABILITY MAP
+Critical risks (act before proceeding):
+• [#N] [Assumption] — WHY it might be wrong — WHAT breaks if it is
+
+High risks (validate before scaling):
+• ...
+
+DEPENDENCY CHAIN
+[Assumption A] → depends on → [Assumption B] → which enables → [Assumption C]
+Weakest link: [X] — if this breaks, [Y] and [Z] also fail
+
+REVERSIBILITY ASSESSMENT
+• Reversible bets: [list]
+• Irreversible commitments: [list — treat with extreme care]
+
+KILL SWITCHES
+What would have to be true at [30/60/90 days] to continue vs. kill/pivot?
+• Continue if: ...
+• Kill/pivot if: ...
+
+HARDENING ACTIONS
+1. [Specific validation to do before proceeding]
+2. [Alternative approach to consider]
+3. [Contingency to build into the plan]
+```
+
+---
+
+## Challenge Patterns by Plan Type
+
+### Product Roadmap
+- Are we building what customers will pay for, or what they said they wanted?
+- Does the velocity estimate account for real team capacity (not theoretical)?
+- What happens if the anchor feature takes 3× longer than estimated?
+- Who owns decisions when requirements conflict?
+
+### Go-to-Market Plan
+- What's the actual ICP conversion rate, not the hoped-for one?
+- How many touches to close, and do you have the sales capacity for that?
+- What happens if the first 10 deals take 3 months instead of 1?
+- Is "land and expand" a real motion or a hope?
+
+### Hiring Plan
+- What happens if the key hire takes 4 months to find, not 6 weeks?
+- Is the plan dependent on retaining specific people who might leave?
+- Does the plan account for ramp time (usually 3–6 months before full productivity)?
+- What's the burn impact if headcount leads revenue by 6 months?
+
+### Fundraising Plan
+- What's your fallback if the lead investor passes?
+- Have you modeled the timeline if it takes 6 months, not 3?
+- What's your runway at current burn if the round closes at the low end?
+- What assumptions break if you raise 50% of the target amount?
+
+---
+
+## The Hardest Questions
+
+These are the ones people skip:
+- "What's the bear case, not the base case?"
+- "If this exact plan was run by a team we don't trust, would it work?"
+- "What are we not saying out loud because it's uncomfortable?"
+- "Who has incentives to make this plan sound better than it is?"
+- "What would an enemy of this plan attack first?"
+
+---
+
+## Deliverable
+
+The output of `/em:challenge` is not permission to stop. It's a vulnerability map. Now you can make conscious decisions: validate the risky assumptions, hedge the critical ones, or accept the bets you're making knowingly.
+
+Unknown risks are dangerous. Known risks are manageable.
diff --git a/skills/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md b/skills/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md
new file mode 100644
index 00000000..3e827e7f
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md
@@ -0,0 +1,157 @@
+---
+name: "hard-call"
+description: "/em -hard-call — Framework for Decisions With No Good Options"
+---
+
+# /em:hard-call — Framework for Decisions With No Good Options
+
+**Command:** `/em:hard-call `
+
+For the decisions that keep you up at 3am. Firing a co-founder. Laying off 20% of the team. Killing a product that customers love. Pivoting. Shutting down.
+
+These decisions don't have a right answer. They have a less wrong answer. This framework helps you find it.
+
+---
+
+## Why These Decisions Are Hard
+
+Not because the data is unclear. Often, the data is clear. They're hard because:
+
+1. **Real people are affected** — someone loses a job, a relationship ends, a team is hurt
+2. **You've been avoiding the decision** — which means the problem is already worse than it was
+3. **Irreversibility** — unlike most business decisions, you can't undo this easily
+4. **You have skin in the game** — your judgment about the right call is clouded by your feelings about it
+
+The longer you avoid a hard call, the worse the situation usually gets. The company that needed a 10% cut 6 months ago now needs a 25% cut. The co-founder conversation that should have happened at month 4 is happening at month 14.
+
+**Most hard decisions are late decisions.**
+
+---
+
+## The Framework
+
+### Step 1: The Reversibility Test
+
+The most important question first: **can you undo this?**
+
+- **Reversible** — try it, learn, adjust (fire the vendor, kill the feature, change the strategy)
+- **Partially reversible** — painful to undo but possible (restructure, change co-founder roles)
+- **Irreversible** — cannot be undone (layoff a person, shut down a product with customer lock-in, close a legal entity)
+
+For irreversible decisions, the bar for certainty is higher. You must do more due diligence before acting. Not because you might be wrong — but because you can't take it back.
+
+**If you're treating a reversible decision like it's irreversible, you're avoiding it.**
+
+### Step 2: The 10/10/10 Framework
+
+Ask three questions about each option:
+
+- **10 minutes from now**: How will you feel immediately after making this decision?
+- **10 months from now**: What will the impact be? Will the problem be solved?
+- **10 years from now**: When you look back, will this have been the right call?
+
+The 10-minute feeling is usually the least reliable guide. The 10-year view usually clarifies what the right call actually is.
+
+**Most hard decisions look obvious at 10 years. The question is whether you can tolerate the 10-minute pain.**
+
+### Step 3: The Andy Grove Test
+
+Andy Grove's test for strategic decisions: "If we got replaced tomorrow and a new CEO came in, what would they do?"
+
+A fresh set of eyes, no emotional investment in the current path, no sunk cost. What's the obvious right call from the outside?
+
+If the answer is clear to an outsider, the question becomes: why haven't you done it yet?
+
+### Step 4: Stakeholder Impact Mapping
+
+For each option, map who's affected and how:
+
+| Stakeholder | Option A Impact | Option B Impact | Their reaction |
+|-------------|----------------|----------------|----------------|
+| Affected employees | | | |
+| Remaining team | | | |
+| Customers | | | |
+| Investors | | | |
+| You | | | |
+
+This isn't about finding the option that hurts nobody — there isn't one. It's about understanding the full picture before you decide.
+
+### Step 5: The Pre-Announcement Test
+
+Before making the decision: write the announcement. The email to the team, the message to the customer, the conversation you'll have.
+
+**If you can't write that announcement, you're not ready to make the decision.**
+
+Writing it forces you to confront the reality of what you're doing. It also surfaces whether your reasoning holds under examination. "We're making this change because…" — does that sentence ring true?
+
+### Step 6: The Communication Plan
+
+Hard decisions almost always get harder if communication is bad. The decision itself is not the only thing that matters — how it's done matters enormously.
+
+For every hard call, plan:
+- **Who needs to know first** (the person directly affected, before anyone else)
+- **How you'll tell them** (in person when possible, never via email for personal impact)
+- **What you'll say** (honest, direct, compassionate — see `references/hard_things.md`)
+- **What they can ask** (be ready for every question)
+- **What comes next** (give them a clear picture of what happens after)
+
+---
+
+## Decision-Specific Frameworks
+
+### Firing a Co-Founder
+See `references/hard_things.md — Co-Founder Conflicts` for full framework.
+
+Key questions to answer first:
+- Is this a performance problem or a values/culture problem? (Different conversations)
+- Have you been explicit — not hinted, but direct — about the problem?
+- What does the cap table look like and what are the legal implications?
+- Is there a role that works better for them, or is this a full exit?
+- Who needs to know (board, team, investors) and in what order?
+
+**The rule:** If you've been thinking about this for more than 3 months, you already know the answer. The question is when, not whether.
+
+### Layoffs
+Key questions:
+- Is this a one-time reset or the beginning of a longer decline? (One reset is recoverable. Serial layoffs kill culture.)
+- Are you cutting deep enough? (Insufficient layoffs are worse than no layoffs — two rounds destroys trust.)
+- Who owns the announcement and is it direct and honest?
+- What's the severance and is it fair?
+- How do you prevent the best people from leaving after?
+
+**The rule:** Cut once, cut deep, cut with dignity. Uncertainty is worse than clarity.
+
+### Pivoting
+Key questions:
+- Is this a true pivot (new direction) or an optimization (same direction, different tactic)?
+- What are you keeping and what are you abandoning?
+- Do you have evidence the new direction works, or are you running from failure?
+- How do you tell current customers who bought the old vision?
+- What does this do to the board's confidence?
+
+**The rule:** Pivots should be pulled by evidence of new opportunity, not pushed by failure of the current path.
+
+### Killing a Product Line
+Key questions:
+- What happens to customers currently using it?
+- What's the migration path?
+- What do the people who built it do?
+- Is "kill it" the right call or is "sell it" or "spin it out" better?
+- What's the narrative — internally and externally?
+
+---
+
+## The Avoiding-It Test
+
+You know you've been avoiding a hard call if:
+- You've thought about it every week for more than a month
+- You're hoping the situation will "resolve itself"
+- You're waiting for more data that you'll never feel is enough
+- You've had the conversation in your head many times but not in real life
+- Other people around you have noticed the problem
+
+**The cost of delay is almost always higher than the cost of the decision.**
+
+Every month you wait, the problem compounds. The co-founder who's not working out becomes more entrenched. The product line that needs to die consumes more resources. The person who needs to be let go affects the people around them.
+
+Make the call. Make it clearly. Make it with dignity.
diff --git a/skills/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md b/skills/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md
new file mode 100644
index 00000000..20112c6c
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md
@@ -0,0 +1,193 @@
+---
+name: "postmortem"
+description: "/em -postmortem — Honest Analysis of What Went Wrong"
+---
+
+# /em:postmortem — Honest Analysis of What Went Wrong
+
+**Command:** `/em:postmortem `
+
+Not blame. Understanding. The failed deal, the missed quarter, the feature that flopped, the hire that didn't work out. What actually happened, why, and what changes as a result.
+
+---
+
+## Why Most Post-Mortems Fail
+
+They become one of two things:
+
+**The blame session** — someone gets scapegoated, defensive walls go up, actual causes don't get examined, and the same problem happens again in a different form.
+
+**The whitewash** — "We learned a lot, we're going to do better, here are 12 vague action items." Nothing changes. Same problem, different quarter.
+
+A real post-mortem is neither. It's a rigorous investigation into a system failure. Not "whose fault was it" but "what conditions made this outcome predictable in hindsight?"
+
+**The purpose:** extract the maximum learning value from a failure so you can prevent recurrence and improve the system.
+
+---
+
+## The Framework
+
+### Step 1: Define the Event Precisely
+
+Before analysis: describe exactly what happened.
+
+- What was the expected outcome?
+- What was the actual outcome?
+- When was the gap first visible?
+- What was the impact (financial, operational, reputational)?
+
+Precision matters. "We missed Q3 revenue" is not precise enough. "We closed $420K in new ARR vs $680K target — a $260K miss driven primarily by three deals that slipped to Q4 and one deal that was lost to a competitor" is precise.
+
+### Step 2: The 5 Whys — Done Properly
+
+The goal: get from **what happened** (the symptom) to **why it happened** (the root cause).
+
+Standard bad 5 Whys:
+- Why did we miss revenue? Because deals slipped.
+- Why did deals slip? Because the sales cycle was longer than expected.
+- Why? Because the customer buying process is complex.
+- Why? Because we're selling to enterprise.
+- Why? That's just how enterprise sales works.
+
+→ Conclusion: Nothing to do. It's just enterprise.
+
+Real 5 Whys:
+- Why did we miss revenue? Three deals slipped out of quarter.
+- Why did those deals slip? None of them had identified a champion with budget authority.
+- Why did we progress deals without a champion? Our qualification criteria didn't require it.
+- Why didn't our qualification criteria require it? When we built the criteria 8 months ago, we were in SMB, not enterprise.
+- Why haven't we updated qualification criteria as ICP shifted? No owner, no process for criteria review.
+
+→ Root cause: Qualification criteria outdated, no owner, no review process.
+→ Fix: Update criteria, assign owner, add quarterly review.
+
+**The test for a good root cause:** Could you prevent recurrence with a specific, concrete change? If yes, you've found something real.
+
+### Step 3: Distinguish Contributing Factors from Root Cause
+
+Most events have multiple contributing factors. Not all are root causes.
+
+**Contributing factor:** Made it worse, but isn't the core reason. If removed, the outcome might have been different — but the same class of problem would recur.
+
+**Root cause:** The fundamental condition that made the outcome probable. Fix this, and this class of problem doesn't recur.
+
+Example — failed hire:
+- Contributing factors: rushed process, reference checks skipped, team under pressure to staff up
+- Root cause: No defined competency framework, so interview process varied by who happened to conduct interviews
+
+**The distinction matters.** If you address only contributing factors, you'll have a different-looking but structurally identical failure next time.
+
+### Step 4: Identify the Warning Signs That Were Ignored
+
+Every failure has precursors. In hindsight, they're obvious. The value of this step is making them obvious prospectively.
+
+Ask:
+- At what point was the negative outcome predictable?
+- What signals were visible at that point?
+- Who saw them? What happened when they raised them?
+- Why weren't they acted on?
+
+**Common patterns:**
+- Signal was raised but dismissed by a senior person
+- Signal wasn't raised because nobody felt safe saying it
+- Signal was seen but no one had clear ownership to act on it
+- Data was available but nobody was looking at it
+- The team was too optimistic to take negative signals seriously
+
+This step is particularly important for systemic issues — "we didn't feel safe raising the concern" is a much deeper root cause than "the deal qualification was off."
+
+### Step 5: Distinguish What Was in Control vs. Out of Control
+
+Some failures happen despite correct decisions. Some happen because of incorrect decisions. Knowing the difference prevents both overcorrection and undercorrection.
+
+- **In control:** Process, criteria, team capability, resource allocation, decisions made
+- **Out of control:** Market conditions, customer decisions, competitor actions, macro events
+
+For things out of control: what can be done to be more resilient to similar events?
+For things in control: what specifically needs to change?
+
+**Warning:** "It was outside our control" is sometimes used to avoid accountability. Be rigorous.
+
+### Step 6: Build the Change Register
+
+Every post-mortem ends with a change register — specific commitments, owned and dated.
+
+**Bad action items:**
+- "We'll improve our qualification process"
+- "Communication will be better"
+- "We'll be more rigorous about forecasting"
+
+**Good action items:**
+- "Ravi owns rewriting qualification criteria by March 15 to include champion identification as hard requirement. New criteria reviewed in weekly sales standup starting March 22."
+- "By March 10, Elena adds deal-slippage risk flag to CRM for any open opportunity >60 days without a product demo"
+- "Maria runs a 30-min retrospective with enterprise sales team every 6 weeks starting April 1, reviews win/loss data"
+
+**For each action:**
+- What exactly is changing?
+- Who owns it?
+- By when?
+- How will you verify it worked?
+
+### Step 7: Verification Date
+
+The most commonly skipped step. Post-mortems are useless if nobody checks whether the changes actually happened and actually worked.
+
+Set a verification date: "We'll review whether qualification criteria have been updated and whether deal slippage rate has improved at the June board meeting."
+
+Without this, post-mortems are theater.
+
+---
+
+## Post-Mortem Output Format
+
+```
+EVENT: [Name and date]
+EXPECTED: [What was supposed to happen]
+ACTUAL: [What happened]
+IMPACT: [Quantified]
+
+TIMELINE
+[Date]: [What happened or was visible]
+[Date]: ...
+
+5 WHYS
+1. [Why did X happen?] → Because [Y]
+2. [Why did Y happen?] → Because [Z]
+3. [Why did Z happen?] → Because [A]
+4. [Why did A happen?] → Because [B]
+5. [Why did B happen?] → Because [ROOT CAUSE]
+
+ROOT CAUSE: [One clear sentence]
+
+CONTRIBUTING FACTORS
+• [Factor] — how it contributed
+• [Factor] — how it contributed
+
+WARNING SIGNS MISSED
+• [Signal visible at what date] — why it wasn't acted on
+
+WHAT WAS IN CONTROL: [List]
+WHAT WASN'T: [List]
+
+CHANGE REGISTER
+| Action | Owner | Due Date | Verification |
+|--------|-------|----------|-------------|
+| [Specific change] | [Name] | [Date] | [How to verify] |
+
+VERIFICATION DATE: [Date of check-in]
+```
+
+---
+
+## The Tone of Good Post-Mortems
+
+Blame is cheap. Understanding is hard.
+
+The goal isn't to establish that someone made a mistake. The goal is to understand why the system produced that outcome — so the system can be improved.
+
+"The salesperson didn't qualify the deal properly" is blame.
+"Our qualification framework hadn't been updated when we moved upmarket, and no one owned keeping it current" is understanding.
+
+The first version fires or shames someone. The second version builds a more resilient organization.
+
+Both might be true simultaneously. The distinction is: which one actually prevents recurrence?
diff --git a/skills/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md b/skills/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md
new file mode 100644
index 00000000..c39e0b65
--- /dev/null
+++ b/skills/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md
@@ -0,0 +1,204 @@
+---
+name: "stress-test"
+description: "/em -stress-test — Business Assumption Stress Testing"
+---
+
+# /em:stress-test — Business Assumption Stress Testing
+
+**Command:** `/em:stress-test `
+
+Take any business assumption and break it before the market does. Revenue projections. Market size. Competitive moat. Hiring velocity. Customer retention.
+
+---
+
+## Why Most Assumptions Are Wrong
+
+Founders are optimists by nature. That's a feature — you need optimism to start something from nothing. But it becomes a liability when assumptions in business models get inflated by the same optimism that got you started.
+
+**The most dangerous assumptions are the ones everyone agrees on.**
+
+When the whole team believes the $50M market is real, when every investor call goes well so you assume the round will close, when your model shows $2M ARR by December and nobody questions it — that's when you're most exposed.
+
+Stress testing isn't pessimism. It's calibration.
+
+---
+
+## The Stress-Test Methodology
+
+### Step 1: Isolate the Assumption
+
+State it explicitly. Not "our market is large" but "the total addressable market for B2B spend management software in German SMEs is €2.3B."
+
+The more specific the assumption, the more testable it is. Vague assumptions are unfalsifiable — and therefore useless.
+
+**Common assumption types:**
+- **Market size** — TAM, SAM, SOM; growth rate; customer segments
+- **Customer behavior** — willingness to pay, churn, expansion, referrals
+- **Revenue model** — conversion rates, deal size, sales cycle, CAC
+- **Competitive position** — moat durability, competitor response speed, switching cost
+- **Execution** — team velocity, hire timeline, product timeline, operational scaling
+- **Macro** — regulatory environment, economic conditions, technology availability
+
+### Step 2: Find the Counter-Evidence
+
+For every assumption, actively search for evidence that it's wrong.
+
+Ask:
+- Who has tried this and failed?
+- What data contradicts this assumption?
+- What does the bear case look like?
+- If a smart skeptic was looking at this, what would they point to?
+- What's the base rate for assumptions like this?
+
+**Sources of counter-evidence:**
+- Comparable companies that failed in adjacent markets
+- Customer churn data from similar businesses
+- Historical accuracy of similar forecasts
+- Industry reports with conflicting data
+- What competitors who tried this found
+
+The goal isn't to find a reason to stop — it's to surface what you don't know.
+
+### Step 3: Model the Downside
+
+Most plans model the base case and the upside. Stress testing means modeling the downside explicitly.
+
+**For quantitative assumptions (revenue, growth, conversion):**
+
+| Scenario | Assumption Value | Probability | Impact |
+|----------|-----------------|-------------|--------|
+| Base case | [Original value] | ? | |
+| Bear case | -30% | ? | |
+| Stress case | -50% | ? | |
+| Catastrophic | -80% | ? | |
+
+Key question at each level: **Does the business survive? Does the plan make sense?**
+
+**For qualitative assumptions (moat, product-market fit, team capability):**
+
+- What's the earliest signal this assumption is wrong?
+- How long would it take you to notice?
+- What happens between when it breaks and when you detect it?
+
+### Step 4: Calculate Sensitivity
+
+Some assumptions matter more than others. Sensitivity analysis answers: **if this one assumption changes, how much does the outcome change?**
+
+Example:
+- If CAC doubles, how does that change runway?
+- If churn goes from 5% to 10%, how does that change NRR in 24 months?
+- If the deal cycle is 6 months instead of 3, how does that affect Q3 revenue?
+
+High sensitivity = the assumption is a key lever. Wrong = big problem.
+
+### Step 5: Propose the Hedge
+
+For every high-risk assumption, there should be a hedge:
+
+- **Validation hedge** — test it before betting on it (pilot, customer conversation, small experiment)
+- **Contingency hedge** — if it's wrong, what's plan B?
+- **Early warning hedge** — what's the leading indicator that would tell you it's breaking before it's too late to act?
+
+---
+
+## Stress Test Patterns by Assumption Type
+
+### Revenue Projections
+
+**Common failures:**
+- Bottom-up model assumes 100% of pipeline converts
+- Doesn't account for deal slippage, churn, seasonality
+- New channel assumed to work before tested at scale
+
+**Stress questions:**
+- What's your actual historical win rate on pipeline?
+- If your top 3 deals slip to next quarter, what happens to the number?
+- What's the model look like if your new sales rep takes 4 months to ramp, not 2?
+- If expansion revenue doesn't materialize, what's the growth rate?
+
+**Test:** Build the revenue model from historical win rates, not hoped-for ones.
+
+### Market Size
+
+**Common failures:**
+- TAM calculated top-down from industry reports without bottoms-up validation
+- Conflating total market with serviceable market
+- Assuming 100% of SAM is reachable
+
+**Stress questions:**
+- How many companies in your ICP actually exist and can you name them?
+- What's your serviceable obtainable market in year 1-3?
+- What percentage of your ICP is currently spending on any solution to this problem?
+- What does "winning" look like and what market share does that require?
+
+**Test:** Build a list of target accounts. Count them. Multiply by ACV. That's your SAM.
+
+### Competitive Moat
+
+**Common failures:**
+- Moat is technology advantage that can be built in 6 months
+- Network effects that haven't yet materialized
+- Data advantage that requires scale you don't have
+
+**Stress questions:**
+- If a well-funded competitor copied your best feature in 90 days, what do customers do?
+- What's your retention rate among customers who have tried alternatives?
+- Is the moat real today or theoretical at scale?
+- What would it cost a competitor to reach feature parity?
+
+**Test:** Ask churned customers why they left and whether a competitor could have kept them.
+
+### Hiring Plan
+
+**Common failures:**
+- Time-to-hire assumes standard recruiting cycle, not current market
+- Ramp time not modeled (3-6 months before full productivity)
+- Key hire dependency: plan only works if specific person is hired
+
+**Stress questions:**
+- What happens if the VP Sales hire takes 5 months, not 2?
+- What does execution look like if you only hire 70% of planned headcount?
+- Which single person, if they left tomorrow, would most damage the plan?
+- Is the plan achievable with current team if hiring freezes?
+
+**Test:** Model the plan with 0 net new hires. What still works?
+
+### Competitive Response
+
+**Common failures:**
+- Assumes incumbents won't respond (they will if you're winning)
+- Underestimates speed of response
+- Doesn't model resource asymmetry
+
+**Stress questions:**
+- If the market leader copies your product in 6 months, how does pricing change?
+- What's your response if a competitor raises $30M to attack your space?
+- Which of your customers have vendor relationships with your competitors?
+
+---
+
+## The Stress Test Output
+
+```
+ASSUMPTION: [Exact statement]
+SOURCE: [Where this came from — model, investor pitch, team gut feel]
+
+COUNTER-EVIDENCE
+• [Specific evidence that challenges this assumption]
+• [Comparable failure case]
+• [Data point that contradicts the assumption]
+
+DOWNSIDE MODEL
+• Bear case (-30%): [Impact on plan]
+• Stress case (-50%): [Impact on plan]
+• Catastrophic (-80%): [Impact on plan — does the business survive?]
+
+SENSITIVITY
+This assumption has [HIGH / MEDIUM / LOW] sensitivity.
+A 10% change → [X] change in outcome.
+
+HEDGE
+• Validation: [How to test this before betting on it]
+• Contingency: [Plan B if it's wrong]
+• Early warning: [Leading indicator to watch — and at what threshold to act]
+```
diff --git a/skills/c-level-advisor/founder-coach/SKILL.md b/skills/c-level-advisor/founder-coach/SKILL.md
new file mode 100644
index 00000000..7fbca733
--- /dev/null
+++ b/skills/c-level-advisor/founder-coach/SKILL.md
@@ -0,0 +1,300 @@
+---
+name: "founder-coach"
+description: "Personal leadership development for founders and first-time CEOs. Covers founder archetype identification, delegation frameworks, energy management, CEO calendar audits, leadership style evolution, blind spot identification, imposter syndrome, founder mental health, and succession planning. Use when a founder feels like the bottleneck, struggles to delegate, is burning out, transitioning from IC to executive, managing a board, or when user mentions founder mode, CEO growth, leadership development, delegation, burnout, or imposter syndrome."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: founder-development
+ updated: 2026-03-05
+ frameworks: leadership-growth, founder-toolkit
+---
+
+# Founder Development Coach
+
+Your company can only grow as fast as you do. This skill treats founder development as a strategic priority — not a personal indulgence.
+
+## Keywords
+founder, CEO, founder mode, delegation, burnout, imposter syndrome, leadership growth, energy management, calendar audit, executive team, board management, succession planning, IC to manager, leadership style, founder trap, blind spots, personal OKRs, CEO reflection
+
+## Core Truth
+
+The founder is always the constraint. Not intentionally — it's structural. You built the company. You know everything. Decisions flow through you. This works until it doesn't.
+
+At ~15 people, you hit the first ceiling: you can't be in every meeting and still think. At ~50 people, the second: your style starts creating culture problems. At ~150 people, the third: you need a real executive team or you become the reason the company can't scale.
+
+The earlier you address this, the better.
+
+---
+
+## 1. Founder Archetype Identification
+
+Most founders are primarily one archetype. Knowing yours predicts what you'll struggle with.
+
+| Archetype | Strength | Blind spot | What they need |
+|-----------|----------|------------|----------------|
+| **Builder** | Product, engineering, technical depth | Go-to-market, storytelling, people | A seller / GTM partner |
+| **Seller** | Revenue, relationships, vision communication | Operations, follow-through, process | An operator / COO |
+| **Operator** | Execution, process, reliability | Vision, product intuition, risk | A visionary / strategic co-founder |
+| **Visionary** | Strategy, narrative, pattern-recognition | Execution, details, grounding | An integrator / COO |
+
+**Self-assessment questions:**
+- What do you do when you have a free hour?
+- What do you procrastinate on most?
+- What do your co-founders or early team complain you don't do?
+- What's the best feedback you've received about your leadership?
+
+Most founders are Builder or Visionary. Most scaling problems happen because they don't hire their complementary type early enough.
+
+---
+
+## 2. Delegation Framework
+
+Founders fail to delegate for four reasons:
+1. "Nobody does it as well as I do" (often true short-term, fatal long-term)
+2. "It takes longer to explain than to do it" (true once; not true the 10th time)
+3. "I lose control if I don't do it myself" (control is an illusion at scale)
+4. "If it fails, it's my fault" (it's your fault if you never let anyone else try)
+
+### The Skill × Will Matrix
+
+| | High Skill | Low Skill |
+|---|-----------|----------|
+| **High Will** | Delegate fully | Coach and develop |
+| **Low Will** | Motivate or reassign | Manage out or redesign role |
+
+**Rules:**
+- High skill + high will → Give the work and get out of the way
+- High will + low skill → Invest in them. They want to grow.
+- High skill + low will → Find out why. Fix the environment or accept the mismatch.
+- Low skill + low will → Don't delegate to them. Address the performance issue.
+
+### The Delegation Ladder
+
+Not all delegation is equal. Build up gradually:
+
+1. "Do exactly what I tell you" — not delegation, instruction
+2. "Research this and report back" — information gathering
+3. "Propose a solution and I'll decide" — thinking delegation
+4. "Decide and tell me what you decided" — decision delegation with review
+5. "Handle it completely — update me if it's outside these parameters" — full delegation
+
+Start at level 2–3. Move people up as trust is established. Most founders never get past level 3 with their team — that's the bottleneck.
+
+### What to delegate first
+
+**Delegate first (high volume, low stakes):**
+- Recurring operational tasks you do the same way every time
+- Information gathering and synthesis
+- Meeting coordination and scheduling
+- Reports and updates you produce regularly
+
+**Delegate next (skill-buildable):**
+- Customer interactions (with clear principles)
+- Hiring screens (after you've trained judgment)
+- Partner relationship management
+- Budget management within parameters
+
+**Delegate last (strategic, irreversible):**
+- Major strategic pivots
+- Executive hires
+- Large financial commitments
+- M&A decisions
+
+---
+
+## 3. Energy Management
+
+Founders manage energy, not just time. Time is fixed. Energy is renewable — but only if you manage it.
+
+### The Energy Audit
+
+Map your week by energy, not tasks. See `references/founder-toolkit.md` for the full template.
+
+**Categories:**
+- 🟢 **Energizing:** Activities that leave you sharper after doing them
+- 🟡 **Neutral:** Neither energizing nor draining
+- 🔴 **Draining:** Activities that leave you depleted
+
+**Common founder energy patterns:**
+- **Builders:** Energized by creating, drained by politics and process
+- **Sellers:** Energized by people and wins, drained by detail work and admin
+- **Operators:** Energized by solving, drained by ambiguity and indecision
+- **Visionaries:** Energized by strategy and ideas, drained by execution and repetition
+
+**The rule:** Maximize green. Eliminate or delegate red. Accept yellow as the price of leadership.
+
+### Energy management practices
+
+**Protect deep work time.** 2–4 hours of uninterrupted thinking time, 3–5 days per week. Schedule it. Defend it. This is where strategy happens.
+
+**Batch shallow work.** Email, Slack, administrative tasks — twice a day maximum.
+
+**Single-task during recovery.** If you're depleted, don't try to do your best work. Do tasks that don't require your best.
+
+**Identify your peak window.** Most people have 4–6 peak hours per day. Schedule your hardest work in those windows.
+
+---
+
+## 4. CEO Calendar Audit
+
+The calendar is the most honest document in a founder's life. It shows what you actually prioritize, not what you say you prioritize.
+
+### Running the audit
+
+Pull the last 4 weeks of calendar data. Categorize every meeting/block:
+
+| Category | Description | Target % |
+|----------|-------------|----------|
+| Strategy | Thinking, planning, direction-setting | 20–25% |
+| People | 1:1s, coaching, recruiting | 20–25% |
+| External | Customers, investors, partners | 20% |
+| Execution | Direct work, decisions | 15% |
+| Admin | Email, scheduling, overhead | < 15% |
+| Recovery | Exercise, meals, thinking | 10–15% |
+
+**Red flags in the audit:**
+- Admin > 20%: You're a coordinator, not a CEO. Fix your systems.
+- Execution > 30%: You're still an IC. Build the team.
+- People < 10%: Your team is running on empty. They need more of you.
+- No recovery blocks: You're running on adrenaline. It ends badly.
+- Strategy < 10%: You're running the company, not leading it.
+
+### The CEO's primary job at each stage
+
+| Stage | CEO should spend most time on... |
+|-------|--------------------------------|
+| Seed | Product and customers. Directly. |
+| Series A | Hiring the executive team. Recruiting is your job. |
+| Series B | Culture, strategy, and external (investors/partners/customers) |
+| Series C+ | Vision, board, external narrative, executive development |
+
+If you're spending time on things from two stages ago, you haven't made the transition.
+
+---
+
+## 5. Leadership Style Evolution
+
+The job changes at every stage. Most founders don't change with it.
+
+**IC → Manager (0 to ~10 people):**
+You need to teach and build trust. People are watching how you treat failure. The skill: give clear context, set expectations, check in frequently.
+
+**Manager → Leader (~10 to ~50 people):**
+You can't manage everyone directly. You need people who manage people. The skill: hire managers you trust, let them manage.
+
+**Leader → Executive (~50 to ~200 people):**
+You're now setting culture and direction, not managing work. The skill: communicate obsessively, decide at the right altitude, develop your leadership team.
+
+**Executive → Institutional CEO (200+):**
+You're a symbol as much as a manager. The skill: build systems that work without you; focus on board, investors, and external narrative.
+
+**The hardest transition:** Manager → Leader. You have to stop doing things yourself and trust people you're still getting to know.
+
+---
+
+## 6. Blind Spot Identification
+
+Everyone has them. Founders more than most — because nobody in the early company had the authority or safety to tell you.
+
+### Common founder blind spots
+
+- **Communication:** "I said it once, they should know" — you said it; they didn't hear it or didn't believe it
+- **Decision speed:** Moving so fast that teams can't orient or build on your direction
+- **Context hoarding:** Knowing what's happening without sharing it, then being frustrated that teams make bad decisions
+- **Optimism bias:** Consistently underestimating timelines, cost, and difficulty
+- **Founder exceptionalism:** Rules that apply to everyone don't apply to you
+- **Feedback avoidance:** Creating an environment where no one gives you honest feedback
+
+### How to find your blind spots
+
+1. **360 feedback (anonymous):** Once a year. Ask direct reports, peers, board members. Include "What does [name] do that gets in the way of our success?"
+2. **Exit interview analysis:** What do departing employees consistently say? Find the pattern.
+3. **Failure post-mortems:** What do your worst decisions have in common? What were you assuming that wasn't true?
+4. **The energy audit:** Where do you consistently drain the people around you?
+
+---
+
+## 7. Imposter Syndrome Toolkit
+
+It doesn't go away. It evolves. The founder who was scared to pitch to investors is now scared to manage a board. The founder who was scared to hire is now scared to fire.
+
+**The reframe:** Imposter syndrome is proportional to stretch. If you never feel it, you're not growing.
+
+**Practical tools:**
+- **Evidence file:** Document wins, compliments, decisions that worked. Read it when the doubt hits.
+- **Normalize the feeling:** "I feel underprepared for this" ≠ "I am an imposter." Feeling and fact are different.
+- **Do the thing anyway.** Competence comes from doing, not from feeling ready.
+- **Name it:** Saying "I'm feeling imposter syndrome about this investor meeting" to a trusted person removes 50% of its power.
+
+---
+
+## 8. Founder Mental Health
+
+Burnout isn't weakness. It's a predictable outcome of high-demand + low-recovery + no control over inputs.
+
+### Burnout signals
+
+Early: Irritability, difficulty sleeping, decisions feel harder than they should, loss of enthusiasm for the mission.
+Mid: Physical symptoms (headaches, illness), cynicism about the company, social withdrawal, all tasks feel equally important (priority paralysis).
+Late: Can't function, decisions have stopped, team notices before you do.
+
+**If you're in late burnout:** Stop performing. Get support. The company needs a functioning founder more than it needs a martyred one.
+
+### Structural prevention
+
+- **Protect recovery time.** Not weekends — protected time during the week where you're not available.
+- **Therapy or coaching.** Not optional for founders. The job is isolating and the stakes are high.
+- **Peer group.** Other founders at similar stages. They're the only people who actually understand the job.
+- **Clear off-ramps.** Know what "enough for today" looks like. Don't let the work be infinite.
+
+---
+
+## 9. The Founder Mode Trap
+
+Paul Graham's "Founder Mode" essay made the case that great founders stay deeply involved in operations — skip middle management and go direct. It resonated because it's sometimes true.
+
+**When founder mode helps:**
+- Crisis recovery (company needs direct leadership)
+- Product-market fit search (speed matters more than org health)
+- High-value, irreversible decisions (you should be in the room)
+- Early stages when the team is small
+
+**When founder mode hurts:**
+- When it undermines managers you've hired (they can't lead if you override them)
+- When it's driven by distrust rather than strategy
+- When it prevents the team from developing judgment
+- When you're doing it because you miss doing, not because the company needs you to
+
+**The test:** Are you going deep because the situation requires it, or because you're uncomfortable with the loss of control? The first is leadership. The second is the trap.
+
+---
+
+## 10. Succession Planning
+
+Building a company that works without you is not disloyalty — it's the ultimate expression of leadership.
+
+**Succession is not just about exit.** It's about resilience. What happens if you're sick? On sabbatical? Acquired?
+
+**Succession readiness levels:**
+- Level 1: You've documented your key knowledge and processes
+- Level 2: At least one person can cover each of your key functions for 2 weeks
+- Level 3: Your leadership team can run the company for a quarter without you
+- Level 4: You've identified and developed your potential successor
+
+Most founders are at Level 0. Level 2 is a reasonable target. Level 3 is a strategic asset.
+
+---
+
+## Key Questions for Founder Development
+
+- "What decisions did you make last week that someone else could have made?"
+- "What are you still doing that you should have delegated 6 months ago?"
+- "When did you last get honest, critical feedback? From whom? What did it say?"
+- "What would need to be true for the company to run for a week without you?"
+- "What's draining your energy that you've accepted as unavoidable?"
+
+## Detailed References
+- `references/leadership-growth.md` — Maxwell levels, situational leadership, founder-to-CEO transition
+- `references/founder-toolkit.md` — Weekly reflection, energy audit, delegation matrix, 1:1 templates
diff --git a/skills/c-level-advisor/founder-coach/references/founder-toolkit.md b/skills/c-level-advisor/founder-coach/references/founder-toolkit.md
new file mode 100644
index 00000000..0ae3cccc
--- /dev/null
+++ b/skills/c-level-advisor/founder-coach/references/founder-toolkit.md
@@ -0,0 +1,296 @@
+# Founder Toolkit
+
+Practical tools for founder self-management and leadership development.
+
+---
+
+## 1. Weekly CEO Reflection Template
+
+**15 minutes. Every Friday. No excuses.**
+
+This is the most important meeting of the week. You with yourself.
+
+```
+DATE: _______________
+
+## This Week
+
+**1. What was my most important contribution this week?**
+(Not the longest meeting or the hardest problem — the thing that will matter in 90 days.)
+
+_______________________________________________
+
+**2. Where did I add the least value? Why was I involved?**
+(Be honest. Where were you in the room out of habit, not necessity?)
+
+_______________________________________________
+
+**3. What should I have delegated but didn't?**
+(Name the specific task and the person you could have delegated it to.)
+
+_______________________________________________
+
+**4. What decision am I avoiding? Why?**
+(Fear of being wrong? Not enough information? Conflict avoidance?)
+
+_______________________________________________
+
+**5. What would I do differently this week if I could do it over?**
+(One thing. Make it specific.)
+
+_______________________________________________
+
+## Next Week
+
+**My one most important outcome for next week:**
+_______________________________________________
+
+**What will I stop doing / not start / protect myself from?**
+_______________________________________________
+```
+
+---
+
+## 2. Energy Audit Template
+
+Map your week by energy, not tasks. Do this for one full work week.
+
+### Step 1: Time block mapping
+
+For each 30-minute block in your week, record:
+- What you did
+- Energy level: 🟢 Energizing / 🟡 Neutral / 🔴 Draining
+
+```
+Monday:
+08:00-08:30: __________________ [🟢/🟡/🔴]
+08:30-09:00: __________________ [🟢/🟡/🔴]
+09:00-09:30: __________________ [🟢/🟡/🔴]
+... (continue through the day)
+```
+
+### Step 2: Pattern analysis
+
+After one week, categorize activities:
+
+| Activity type | Energy level | Total hours | % of week |
+|--------------|-------------|-------------|-----------|
+| Customer calls | | | |
+| Investor meetings | | | |
+| Team 1:1s | | | |
+| Product decisions | | | |
+| Strategy/planning | | | |
+| Email/Slack | | | |
+| Recruiting | | | |
+| Financial review | | | |
+| External talks/events | | | |
+| Administrative tasks | | | |
+| Deep work/building | | | |
+| Recovery/breaks | | | |
+
+### Step 3: Optimization plan
+
+**Green activities to protect (min 40% of week):**
+- _______________________________________________
+
+**Red activities to eliminate or delegate (target: < 15% of week):**
+- Activity: __________________ → Delegate to: __________________
+- Activity: __________________ → Eliminate via: __________________
+
+**Your personal energy peak hours:**
+I do my best thinking: _______ to _______
+Schedule this time as: Protected deep work (no meetings)
+
+---
+
+## 3. Delegation Matrix
+
+For every task you regularly do, run it through this matrix.
+
+### Assessment
+
+| Task | Skill level needed | My will to keep it | Decision |
+|------|-------------------|-------------------|----------|
+| | High / Med / Low | High / Med / Low | Keep / Coach / Delegate / Kill |
+
+### Delegation scoring
+
+| My Skill | My Will | Decision |
+|----------|---------|----------|
+| High | High | Keep — this is your zone of genius |
+| High | Low | Delegate — you can do it, but it drains you. Train someone. |
+| Low | High | Develop — learn it or hire for it |
+| Low | Low | Kill or outsource — why is this on your plate? |
+
+### The 70% rule
+
+If someone can do a task 70% as well as you, delegate it. Trying to get to 100% is a trap:
+- Their 70% will grow to 90% with practice
+- Your 30% extra effort costs more than the quality gap
+- You free up time for things only you can do
+
+---
+
+## 4. 1:1 Template for Direct Reports
+
+Weekly or biweekly. 30 minutes. Their agenda, not yours.
+
+```
+DATE: _______________
+PERSON: _______________
+
+## Their Section (first 20 min)
+
+**What's on their mind? (open the meeting with this)**
+(No agenda from you first — let them lead)
+
+**What are they working on? Where are they stuck?**
+
+**What do they need from me?**
+
+**Anything they wanted to raise but haven't had the chance to?**
+
+## Your Section (last 10 min)
+
+**Context to share (strategy, changes, what they should know):**
+
+**Direct feedback to give (if any):**
+- Be specific: "In Tuesday's meeting, when you [did X], the impact was [Y]"
+- Make it actionable: "Next time, I'd suggest [Z]"
+
+**Career/growth check-in (monthly, not every meeting):**
+- How are they feeling about their growth?
+- What do they want to be doing more of?
+- What are they interested in that they're not currently doing?
+
+## Follow-ups
+
+| Commitment | Owner | Due |
+|------------|-------|-----|
+| | | |
+```
+
+### Rules for effective 1:1s
+
+- **Their agenda first.** If you dominate with your updates, they stop bringing theirs.
+- **No status updates.** That's what tools are for. This time is for their thinking, blockers, and development.
+- **Consistent time.** Rescheduled 1:1s signal that they're not a priority.
+- **Take notes.** Review them before the next meeting. It signals that you listened.
+- **Follow up on commitments.** If you say "I'll get you that answer by Thursday," get it by Thursday.
+
+---
+
+## 5. Personal OKRs for the Founder
+
+Most founders hold their team accountable to goals but have none themselves. Fix that.
+
+### Template: Quarterly Personal OKRs
+
+```
+Q[X] YYYY | FOUNDER OKRs
+
+## My One Priority This Quarter
+(The single most important thing I personally must accomplish)
+_______________________________________________
+
+## Objective 1: [Leadership Development]
+What I'm trying to achieve: _______________________________________________
+
+KR 1.1: [Measurable outcome by EoQ]
+KR 1.2: [Measurable outcome by EoQ]
+KR 1.3: [Measurable outcome by EoQ]
+
+Progress check (mid-quarter): _______________________________________________
+
+## Objective 2: [Delegation / Team Building]
+What I'm trying to achieve: _______________________________________________
+
+KR 2.1: [Measurable outcome by EoQ]
+KR 2.2: [Measurable outcome by EoQ]
+
+## Objective 3: [External Impact — Investors / Customers / Market]
+What I'm trying to achieve: _______________________________________________
+
+KR 3.1: [Measurable outcome by EoQ]
+KR 3.2: [Measurable outcome by EoQ]
+
+## The "Stop Doing" List (equally important)
+Things I'm committing to stop doing this quarter:
+- Stop: _______________________________________________
+- Stop: _______________________________________________
+- Stop: _______________________________________________
+```
+
+### Personal OKR examples
+
+**Objective: Become a better coach, not just a decision-maker**
+- KR: 90% of my direct reports can make their top 3 recurring decisions without me by EoQ
+- KR: In 1:1 reviews, 80% of team rates me as "helps me think through problems" vs "tells me what to do"
+- KR: Conduct quarterly 360 feedback session with all direct reports
+
+**Objective: Build investor trust before I need it**
+- KR: Monthly investor updates sent within 5 days of month-end, every month this quarter
+- KR: 1:1 calls with each board member, once per quarter, outside of board meetings
+- KR: Create and share 3-year financial model with board by EoQ
+
+**Objective: Protect my energy and performance**
+- KR: 3+ hours of protected deep work time per day, 4+ days per week
+- KR: Complete weekly CEO reflection every Friday (track: 0/13 weeks → 13/13)
+- KR: Zero email after 8pm, zero weekends unless explicit crisis
+
+---
+
+## 6. The "Stop Doing" List
+
+The hardest list to make and the most valuable to keep.
+
+Most founders have clear to-do lists. Few have stop-doing lists. The asymmetry is the problem.
+
+### The stop-doing audit
+
+**Things to stop doing immediately (decision you can make today):**
+- Attending meetings you don't add value to
+- Being the default person for decisions that should be made by others
+- Redoing work that your team completed
+- Checking email/Slack during deep work blocks
+- Starting tasks you know you'll delegate partway through
+
+**Things to stop doing by delegating (need to train someone):**
+- _______________________________________________
+- _______________________________________________
+- _______________________________________________
+
+**Things to stop doing by building systems:**
+- Recurring manual tasks → automate
+- Recurring decisions → write decision criteria so others can decide
+- Recurring explanations → document once, reference always
+
+### The decision filter
+
+Before accepting new responsibilities, run through:
+1. Does this require something only I can do?
+2. Is this the highest and best use of my time?
+3. If I say yes to this, what am I saying no to?
+
+If the answers are no, no, and something important — say no.
+
+---
+
+## 7. Evidence File
+
+For when imposter syndrome hits. Keep a running file of:
+
+**Wins** (monthly minimum)
+- Company milestones you led
+- Decisions that worked out well
+- Feedback you received that was genuinely positive
+
+**Quotes** (capture as they happen)
+- Direct quotes from team members, customers, investors about your impact
+- Emails or messages that reflect trust or appreciation
+
+**The hard calls that paid off**
+- Decisions you were scared to make that turned out well
+- Times you said no to something that would have hurt the company
+
+**When to read it:** When you're doubting yourself before a board meeting, a hard conversation, a big pitch. The feeling isn't fact. The evidence file is.
diff --git a/skills/c-level-advisor/founder-coach/references/leadership-growth.md b/skills/c-level-advisor/founder-coach/references/leadership-growth.md
new file mode 100644
index 00000000..81fbd198
--- /dev/null
+++ b/skills/c-level-advisor/founder-coach/references/leadership-growth.md
@@ -0,0 +1,178 @@
+# Leadership Growth Reference
+
+Frameworks for founder and executive leadership development.
+
+---
+
+## 1. The 5 Levels of Leadership (Maxwell)
+
+John Maxwell's model describes leadership development as a ladder. Most founders start at Level 2–3 and need to reach Level 4–5 to scale effectively.
+
+| Level | Name | People follow because... | What it looks like |
+|-------|------|--------------------------|-------------------|
+| 1 | Position | They have to (title/authority) | "Do this because I'm the CEO" |
+| 2 | Permission | They want to (relationship) | People choose to work with you beyond the job requirement |
+| 3 | Production | You produce results | Team rallies because you deliver; your track record gives credibility |
+| 4 | People Development | You develop others | You're multiplying leaders; your success is measured by others' growth |
+| 5 | Pinnacle | Who you are (reputation) | People follow because of what you've built and who you've become |
+
+**Most founders are at Level 3.** They got here by building and shipping. The path to scaling is Level 4: developing other leaders.
+
+**The Level 3 trap:** Production-focused founders attract doers, not leaders. They value results over growth. Their teams are effective but dependent. Every decision still goes through the founder.
+
+**The Level 4 shift:** Measure your success by how well your team succeeds without you. Your job is to make the people around you better.
+
+---
+
+## 2. Situational Leadership Model
+
+Ken Blanchard's model says effective leadership style shifts based on the person and the task — not the leader's preference.
+
+Four styles based on the follower's development level:
+
+| Development Level | Competence | Commitment | Leadership Style | What to do |
+|------------------|------------|------------|-----------------|------------|
+| D1 — Enthusiastic Beginner | Low | High | S1: Directing | High direction, low support. Tell them what to do. |
+| D2 — Disillusioned Learner | Low/Med | Low | S2: Coaching | High direction + high support. Teach and encourage. |
+| D3 — Capable but Cautious | Medium/High | Variable | S3: Supporting | Low direction, high support. Collaborate and encourage. |
+| D4 — Self-Reliant Achiever | High | High | S4: Delegating | Low direction, low support. Get out of the way. |
+
+**Common founder error:** Using the same leadership style with everyone. The founder who directs a D4 will frustrate them into leaving. The founder who delegates to a D1 will watch them fail.
+
+**Diagnosis before deciding:**
+Before determining your style, ask for each person + task:
+- How much do they know about this specific task? (Not in general — this task.)
+- How much do they want to do this specific task?
+
+These answers may surprise you. A senior engineer may be D4 on architecture and D1 on customer calls.
+
+---
+
+## 3. The Founder → CEO Transition
+
+The hardest leadership change most founders face, and nobody prepares them for it.
+
+### What changes
+
+**As a founder, you were judged on:**
+- What you personally built
+- How fast you moved
+- Your own output
+
+**As a CEO, you're judged on:**
+- What your team produced
+- How effectively you set direction
+- The quality of the people around you
+
+The skills that made you a great founder — doing, deciding, building — can actively work against you as a CEO.
+
+### The transition phases
+
+**Phase 1: Still doing (0–15 people)**
+You're right to be deep in the work. Speed requires it. Your personal output matters.
+Risk: Staying here too long.
+
+**Phase 2: Building around you (15–50 people)**
+You're hiring and starting to delegate. People do work you used to do.
+Challenge: Learning to trust output that doesn't look like yours.
+Failure mode: Hiring people and then redoing their work.
+
+**Phase 3: Leading through leaders (50–150 people)**
+You no longer know everything happening in the company. That's correct.
+Challenge: Managing people who manage people — twice removed from the work.
+Failure mode: Bypassing your managers to go direct (undermines them, creates chaos).
+
+**Phase 4: Setting the container (150+ people)**
+Your job is culture, strategy, and the senior leadership team. You're a CEO, not a senior contributor.
+Challenge: Staying relevant and strategic without getting lost in the weeds.
+Failure mode: Retreating to execution to feel productive.
+
+### The emotional reality
+
+Most founders describe the transition as:
+- A loss of identity ("I used to know everything that was happening")
+- A loss of control ("Decisions happen without me")
+- A loss of clarity ("Was I more effective before?")
+
+These are real losses, not just discomfort. Acknowledge them. Find identity in what the CEO role is, not what the founder role was.
+
+---
+
+## 4. Building Your Executive Team
+
+### When to hire your first executive
+
+Common question: "When do I need a VP/C-suite?"
+
+**Trigger signs:**
+- The function is failing and you can't fix it by working harder
+- You can't attract or develop talent in that function because you lack the expertise
+- The function is growing faster than you can lead it
+- You're making bad decisions in that domain because you don't have deep knowledge
+
+**Order of first executives:**
+Most companies hire in this order, but the right order depends on your archetype and what's breaking:
+1. First non-founder exec is usually Sales (VP Sales) or Engineering (VP Eng / CTO)
+2. Then COO/Operations when coordination becomes the bottleneck
+3. Then Finance (CFO) when fundraising or financial complexity demands it
+4. Then People/HR when hiring velocity and culture require dedicated ownership
+
+### How to onboard executives
+
+**The 30-60-90 plan:**
+- Day 1–30: Listen. Meet everyone. Learn the current state. No major decisions.
+- Day 31–60: Diagnose. What's working, what isn't, what's missing. Share findings.
+- Day 61–90: Act. Make changes. Start building systems. Establish their leadership presence.
+
+**The trust-building sequence:**
+Start with small, visible wins. Let them prove themselves in low-stakes situations before handing over high-stakes decisions.
+
+**The founder's role during exec onboarding:**
+- Provide context generously
+- Introduce them with genuine authority ("This is the decision-maker for X — go to them, not me")
+- Don't override their decisions publicly
+- Give feedback privately, not in front of their team
+
+**Failure mode:** Hiring a great executive and then making them feel like a senior employee. If you override every major decision, you don't have an executive — you have an expensive advisor.
+
+---
+
+## 5. Managing Your Board
+
+### The fundamental tension
+
+You work for the board. The board elected you. They can remove you. This is a governance reality, not a threat.
+
+And: You lead the company. The board sets governance and approves major decisions, but they're not running the business day-to-day. You are.
+
+**Healthy dynamic:** Board holds accountability; CEO holds authority. They're not adversarial — they're complementary.
+
+### The founder mistake
+
+Most founders either:
+1. **Over-inform:** Share every detail, create noise, invite micro-management
+2. **Under-inform:** Share only wins, board is surprised by problems, trust erodes
+
+Neither works. The goal is strategic partnership.
+
+### What the board actually needs
+
+- **Monthly written update:** Financial performance vs plan, key metrics, top 3 issues + proposed solutions, forward-looking risks. 1–2 pages.
+- **Quarterly board meeting:** Strategic discussion, not financial recap. They've read the update. Use the time for decisions and input.
+- **Real-time alerts:** Big bad news before the meeting. Never let board members be surprised by negative news they should have known earlier.
+
+### Managing board members individually
+
+Invest in 1:1 relationships with each board member between meetings. Understand what they care about. Use their expertise.
+
+Board members who feel informed and useful are your allies. Board members who feel blindsided or sidelined become difficult.
+
+**The pre-meeting call:** Before every board meeting, call each member individually. Preview the agenda, surface concerns, align on decisions. The meeting itself should have no surprises.
+
+### When the board challenges you
+
+"The board doesn't trust my judgment" is often really: "I haven't given them enough information to trust my judgment."
+
+Fix the transparency gap before assuming it's a political problem.
+
+**When the board is actually wrong:** Make the case clearly, once, with data. If they override you on something important and you can't accept it, that's a signal about fit. Founders get removed. It happens. Build board relationships before you need them to trust you on a hard call.
diff --git a/skills/c-level-advisor/internal-narrative/SKILL.md b/skills/c-level-advisor/internal-narrative/SKILL.md
new file mode 100644
index 00000000..4ef4b25a
--- /dev/null
+++ b/skills/c-level-advisor/internal-narrative/SKILL.md
@@ -0,0 +1,197 @@
+---
+name: "internal-narrative"
+description: "Build and maintain one coherent company story across all audiences — employees, investors, customers, candidates, and partners. Detects narrative contradictions and ensures the same truth is framed for each audience's needs. Use when preparing investor updates, all-hands presentations, board communications, recruiting narratives, crisis communications, or when user mentions company narrative, messaging consistency, storytelling, all-hands, investor update, or crisis communication."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: narrative-strategy
+ updated: 2026-03-05
+ frameworks: narrative-frameworks, all-hands-template
+---
+
+# Internal Narrative Builder
+
+One company. Many audiences. Same truth — different lenses. Narrative inconsistency is trust erosion. This skill builds and maintains coherent communication across every stakeholder group.
+
+## Keywords
+narrative, company story, internal communication, investor update, all-hands, board communication, crisis communication, messaging, storytelling, narrative consistency, audience translation, founder narrative, employee communication, candidate narrative, partner communication
+
+## Core Principle
+
+**The same fact lands differently depending on who hears it and what they need.**
+
+"We're shifting resources from Product A to Product B" means:
+- To employees: "Is my job safe? Why are we abandoning what I built?"
+- To investors: "Smart capital allocation — they're doubling down on the winner"
+- To customers of Product A: "Are they abandoning us?"
+- To candidates: "Exciting new focus — are they decisive?"
+
+Same fact. Four different narratives needed. The skill is maintaining truth while serving each audience's actual question.
+
+---
+
+## Framework
+
+### Step 1: Build the Core Narrative
+
+One paragraph that every other communication derives from. This is the source of truth.
+
+**Core narrative template:**
+> [Company name] exists to [mission — present tense, specific]. We're building [what you're building] because [the problem you're solving]. Our approach is [your unique way of doing this]. We're at [honest description of current state] and heading toward [where you're going in concrete terms].
+
+**Good core narrative (example):**
+> Acme Health exists to reduce preventable falls in elderly care using smartphone-based mobility analysis. We're building an AI diagnostic tool for care teams because current fall risk assessments are subjective, infrequent, and often wrong. Our approach — using the phone's camera during a 10-second walking test — means no new hardware, no specialist required. We have 80 care facilities in DACH paying us €800K ARR, and we're heading to €3M ARR by demonstrating clinical value at scale before our Series B.
+
+**Bad core narrative:**
+> Acme Health is an innovative AI company revolutionizing elderly care through cutting-edge technology that empowers care providers and improves patient outcomes across the continuum of care.
+
+The good version is usable. The bad version says nothing.
+
+---
+
+### Step 2: Audience Translation Matrix
+
+Take the core narrative and translate it for each audience. Same truth, different frame.
+
+| Fact | Employees need to hear | Investors need to hear | Customers need to hear | Candidates need to hear |
+|------|----------------------|----------------------|----------------------|------------------------|
+| We have 80 customers | "We've proven the model — your work matters" | "Product-market fit signal, capital efficient" | "80 care facilities trust us" | "Traction you'd be joining" |
+| We pivoted from hardware | "We were honest enough to change course" | "Capital-efficient pivot to better unit economics" | "We found a faster, simpler way to serve you" | "We make decisions based on evidence, not ego" |
+| We missed Q2 revenue | "Here's why, here's the plan, here's what you can do" | "Revenue mix shifted — trailing indicator improving" | [Usually don't tell customers revenue misses] | [Usually not shared externally] |
+| We're hiring fast | "The team is growing — your network matters" | "Headcount plan aligned to growth" | [Not relevant unless it affects service] | "This is a rocket ship moment" |
+
+**Rules:**
+- Never contradict yourself across audiences. Different framing ≠ different facts.
+- "We told investors growth, told employees efficiency" is a contradiction. Audit for this.
+- Investors and employees see each other. Board members talk to your team. Candidates google you.
+
+---
+
+### Step 3: Contradiction Detection
+
+Before any major communication, run the contradiction check:
+
+**Question 1:** What did we tell investors last month about [topic]?
+**Question 2:** What did we tell employees about the same topic?
+**Question 3:** Are these consistent? If not — which version is true?
+
+**Common contradictions:**
+- "Efficient growth" to investors + "we're hiring aggressively" to candidates
+- "Strong pipeline" to investors + "sales is struggling" at all-hands
+- "Customer-first" in culture + recent decisions that clearly prioritized revenue over customer need
+
+**When you catch a contradiction:** Fix the less accurate version, then communicate the correction explicitly. "Last month I said X. After more reflection, X is not quite right. Here's the clearer version."
+
+Correcting yourself before someone else catches it builds more trust than getting caught.
+
+---
+
+### Step 4: Audience-Specific Communication Cadence
+
+| Audience | Format | Frequency | Owner |
+|----------|--------|-----------|-------|
+| Employees | All-hands | Monthly | CEO |
+| Employees | Team updates | Weekly | Team leads |
+| Investors | Written update | Monthly | CEO + CFO |
+| Board | Board meeting + memo | Quarterly | CEO |
+| Customers | Product updates | Per release | CPO / CS |
+| Candidates | Careers page + interview narrative | Ongoing | CHRO + Founders |
+| Partners | Quarterly business review | Quarterly | BD Lead |
+
+---
+
+### Step 5: All-Hands Structure and Cadence
+
+See `templates/all-hands-template.md` for the full template.
+
+**Principles:**
+- Lead with honest state of the company. No spin.
+- Connect company performance to individual work: "Here's how what you built contributed to this outcome."
+- Give people a reason to be proud of their choice to work here.
+- Leave time for real Q&A — not curated questions.
+
+**All-hands failure modes:**
+- CEO speaks for 55 of 60 minutes; Q&A is "any quick questions?"
+- All good news, all the time — employees know when you're not being honest
+- Metrics without context: "ARR grew 15%" without explaining if that's good, bad, or expected
+- Questions deflected: "That's a great point, we should follow up on that" → never followed up
+
+---
+
+### Step 6: Crisis Communication
+
+When the narrative breaks — someone leaves publicly, a product fails, a security breach, a press article.
+
+**The 4-hour rule:** If something is public or about to be, communicate internally within 4 hours. Employees should never learn about company news from Twitter.
+
+**Crisis communication sequence:**
+
+**Hour 0–4 (internal first):**
+1. CEO or relevant leader sends an internal message
+2. Acknowledge what happened factually
+3. State what you know and what you don't know yet
+4. Tell people what you're doing about it
+5. Tell people what they should do if they're asked about it
+
+**Hour 4–24 (external if needed):**
+1. External statement (press, social) only if the event is public
+2. Consistent with the internal message — same facts, audience-appropriate framing
+3. Legal review if any claims or liability involved
+
+**What not to do in a crisis:**
+- Silence: letting rumors fill the vacuum
+- Spin: people can detect it and it destroys trust
+- "No comment": says "we have something to hide"
+- Blaming: even if someone else caused the problem, your audience only cares what you're doing about it
+
+**Template for crisis internal communication:**
+> "Here's what happened: [factual description]. Here's what we know right now: [known facts]. Here's what we don't know yet: [honest uncertainty]. Here's what we're doing: [specific actions]. Here's what you should do if you're asked about this: [specific guidance]. I'll update you by [specific time] with more information."
+
+---
+
+## Narrative Consistency Checklist
+
+Run before any major external communication:
+
+- [ ] Is this consistent with what we told investors last month?
+- [ ] Is this consistent with what we told employees at the last all-hands?
+- [ ] Does this contradict anything on our website, careers page, or press releases?
+- [ ] If an employee read this external communication, would they recognize the company being described?
+- [ ] If an investor read our internal all-hands deck, would they find anything inconsistent?
+- [ ] Have we been accurate about our current state, or are we projecting an aspiration?
+
+---
+
+## Key Questions for Narrative
+
+- "Could a new employee explain to a friend why our company exists? What would they say?"
+- "What do we tell investors about our strategy? What do we tell employees? Are these the same?"
+- "If a journalist asked our team members to describe the company independently, what would they say?"
+- "When did we last update our 'why we exist' story? Is it still true?"
+- "What's the hardest question we'd get from each audience? Do we have an honest answer?"
+
+## Red Flags
+
+- Different departments describe the company mission differently
+- Investor narrative emphasizes growth; employee narrative emphasizes stability (or vice versa)
+- All-hands presentations are mostly slides, mostly one-way
+- Q&A questions are screened or deflected
+- Bad news reaches employees through Slack rumors before leadership communication
+- Careers page describes a culture that employees don't recognize
+
+## Integration with Other C-Suite Roles
+
+| When... | Work with... | To... |
+|---------|-------------|-------|
+| Investor update prep | CFO | Align financial narrative with company narrative |
+| Reorg or leadership change | CHRO + CEO | Sequence: employees first, then external |
+| Product pivot | CPO | Align customer communication with investor story |
+| Culture change | Culture Architect | Ensure internal story is consistent with external employer brand |
+| M&A or partnership | CEO + COO | Control information flow, prevent narrative leaks |
+| Crisis | All C-suite | Single voice, consistent story, internal first |
+
+## Detailed References
+- `references/narrative-frameworks.md` — Storytelling structures, founder narrative, bad news delivery, all-hands templates
+- `templates/all-hands-template.md` — All-hands presentation template
diff --git a/skills/c-level-advisor/internal-narrative/references/narrative-frameworks.md b/skills/c-level-advisor/internal-narrative/references/narrative-frameworks.md
new file mode 100644
index 00000000..36babb3d
--- /dev/null
+++ b/skills/c-level-advisor/internal-narrative/references/narrative-frameworks.md
@@ -0,0 +1,211 @@
+# Narrative Frameworks
+
+Reference frameworks for building compelling, consistent business narratives.
+
+---
+
+## 1. Storytelling Structure for Business
+
+### The SCR Framework (Situation, Complication, Resolution)
+
+Barbara Minto's Pyramid Principle adapted for business narrative. Works for any audience.
+
+**Situation:** The established facts everyone agrees on.
+**Complication:** What changed, what problem arose, what makes the situation untenable.
+**Resolution:** What you're doing about it, and why this solution works.
+
+**Example — Investor update:**
+> **Situation:** We entered Q2 with €650K ARR and a target of €800K. Our DACH pipeline was strong at 3x coverage.
+>
+> **Complication:** Two large deals (€90K combined ARR) that were expected to close in May pushed to Q3 due to procurement delays on the customer side. We ended Q2 at €710K — below target but within the range we'd flag as manageable.
+>
+> **Resolution:** Both deals are now signed with June start dates. We're entering Q3 at €800K ARR. We've added a new procurement risk flag to our pipeline methodology to catch this pattern earlier.
+
+**Why it works:** It respects the audience's intelligence, acknowledges the problem directly, and frames your response before they can object.
+
+---
+
+### The Problem-Solution-Evidence Structure
+
+Best for pitches, product announcements, and strategy communications.
+
+1. **The world as it is:** What's the current reality?
+2. **What's broken about it:** Why is the status quo painful or inefficient?
+3. **What we're doing:** Your specific solution
+4. **Why it works:** Evidence, mechanism, or proof
+5. **What happens next:** Call to action or forward look
+
+**Example — All-hands strategy communication:**
+> The world as it is: We have 80 customers in DACH. Churn is 8% annually. That means we're losing 6–7 customers a year just to stay flat.
+>
+> What's broken: Our onboarding takes 6 weeks. By week 4, customers haven't seen value yet and they're questioning the decision. We've traced 60% of churn to customers who never completed onboarding.
+>
+> What we're doing: We're redesigning onboarding to show the first meaningful mobility report within 48 hours of account activation.
+>
+> Why it will work: We ran this with 5 pilot customers in Q2. Time-to-first-value dropped from 4 weeks to 2 days. 4 of 5 expanded their contract within 60 days.
+>
+> What happens next: Engineering ships the new onboarding flow by August 15. CS is retrained by August 22. We'll run the new flow with all new customers from September 1 and report back at the October all-hands.
+
+---
+
+## 2. The Founder's Narrative
+
+The founder's personal story is one of the most underutilized assets in a startup. Used well, it anchors the company's mission and creates genuine connection.
+
+### The Founder Story Structure
+
+**Origin:** What led you to this problem? (Ideally personal — you experienced it, someone you loved experienced it, you couldn't stop thinking about why nobody was solving it)
+
+**Insight:** What did you see that others didn't? (Your unique perspective or unfair advantage)
+
+**Decision:** The moment you committed. (Specific, not aspirational — "I left my job on March 14" not "I decided to pursue my passion")
+
+**What you've learned:** 2–3 honest observations that shaped your approach. (Including what you got wrong)
+
+**Where you're going:** Connection from your personal why to where the company is heading.
+
+**Example (condensed):**
+> My mother had a fall in 2018 that broke her hip. She spent 3 months in rehabilitation. The terrifying part: nobody saw it coming. Her doctor had assessed her fall risk 4 months earlier — using a paper questionnaire. I spent two years talking to geriatricians trying to understand why this assessment was still done by hand, on paper, in 2018. The answer: nobody had made it easy enough for a non-specialist to do it digitally. That's what we're building.
+
+**Why it matters:** Investors, candidates, and customers all respond to a founder who started from a real problem rather than a market opportunity. The narrative makes you memorable and makes the mission credible.
+
+---
+
+## 3. How to Deliver Bad News Across Audiences
+
+### Universal principles
+
+1. **Internal first.** Always. Every time. No exceptions.
+2. **Direct, not hedged.** "We missed our Q2 target by 12%" beats "Q2 performance came in below our expectations."
+3. **Own it before explaining it.** Context comes after acknowledgment, not before.
+4. **State what you're doing.** Bad news without a response plan creates panic.
+5. **Give a timeline.** "We'll know more by [date]" is better than open-ended uncertainty.
+
+### Delivering bad news to employees
+
+**Format:** Synchronous (all-hands or team meeting), followed by written summary.
+
+**What to say:**
+- What happened (factual, no spin)
+- What it means for the company
+- What it means for them specifically (will roles change? Will comp change?)
+- What you're doing about it
+- When you'll have more information
+
+**What not to say:**
+- "I can't share the details" (share everything you legally can)
+- "This is actually good news because..." (if it's bad news, don't reframe it before acknowledging it)
+- "We saw this coming" (if you did, why didn't you tell them?)
+
+**Example — Missed fundraise:**
+> "I have to share news that's disappointing. We went out to raise a Series A in Q1, and we didn't close the round. We had term sheets that fell through when the market conditions shifted in April. We're not in crisis — we have 12 months of runway — but we need to recalibrate. Here's what that means concretely: we're pausing 3 open headcount. Everyone currently on the team keeps their role. We're going back to market in Q4 with stronger metrics. I'll share our updated financial model with everyone by Friday and answer every question you have."
+
+---
+
+### Delivering bad news to investors
+
+**Format:** Written update (monthly update format) + proactive call if material.
+
+**What to say:**
+- Headline the bad news in the first paragraph (don't bury it)
+- Context: what changed and what didn't change
+- What you're doing about it
+- What you need from them (if anything)
+
+**What investors hate:**
+- Finding out from someone other than you
+- Bad news wrapped in so much context they have to work to find it
+- "We're watching it closely" without specific action
+- Consistent over-optimism followed by consistent misses
+
+**Example — Investor update paragraph:**
+> "Revenue miss: We ended Q2 at €710K ARR vs. a target of €800K. Two deals totaling €90K pushed to Q3 due to customer procurement delays (not product or relationship issues — both have since signed). We've adjusted our sales process to flag procurement risk earlier. Q3 is starting at €800K with those deals live."
+
+---
+
+### Delivering bad news to customers
+
+**Scope:** Only share bad news that affects them. Don't share internal struggles that aren't relevant to their experience.
+
+**Format:** Proactive communication from their account owner or a senior leader.
+
+**What customers need:**
+- What happened (that affects them)
+- What you're doing about it
+- What they should do (if anything)
+- Who to contact
+
+**What customers don't need:**
+- Your internal financial struggles
+- Drama about team changes
+- More detail than affects their use of your product
+
+**Example — Service disruption:**
+> "Yesterday evening we experienced a 90-minute service outage that affected your access to [feature]. We've identified the root cause (a failed database migration) and deployed a fix. Your data is intact and complete. We've implemented additional monitoring to prevent this from recurring. I'd like to schedule a brief call to answer any questions you have."
+
+---
+
+## 4. Narrative Consistency Checklist
+
+Use before any significant external communication.
+
+### Pre-communication audit
+
+**Factual consistency:**
+- [ ] Is the ARR/revenue figure consistent with what we've shared with investors?
+- [ ] Is the team size consistent with what's on LinkedIn and our careers page?
+- [ ] Are our stated priorities consistent with our published roadmap?
+- [ ] Is our "stage" description consistent across all channels? (We can't be "early stage" to investors and "established leader" to customers)
+
+**Message consistency:**
+- [ ] Does this message conflict with anything said in the last 90 days?
+- [ ] If an employee read this external message, would they recognize the company?
+- [ ] If an investor read our internal all-hands, would they find anything that contradicts what we've told them?
+
+**Audience appropriateness:**
+- [ ] Have we answered the key question for this specific audience?
+- [ ] Have we avoided sharing information this audience doesn't need and shouldn't have?
+- [ ] Have we framed the message for what this audience cares about — not what we want them to care about?
+
+---
+
+## 5. All-Hands Presentation Templates
+
+See `templates/all-hands-template.md` for the complete slide-by-slide template.
+
+### Monthly all-hands (30–45 min)
+
+**Structure:**
+1. State of the company (10 min) — honest, metric-driven
+2. Progress on quarterly rocks (5 min) — on track / off track / done
+3. Team spotlight (5 min) — one team's work, why it matters
+4. What's coming next 30 days (5 min) — what to expect
+5. Q&A (10–15 min) — real questions, real answers
+
+### Quarterly all-hands (60–90 min)
+
+**Structure:**
+1. Last quarter results vs. targets (15 min)
+2. What we learned (10 min) — honest reflection on what didn't work
+3. Next quarter priorities (15 min) — company rocks, why these three
+4. Strategy update (10 min) — anything changing? Why?
+5. Team recognition (10 min) — specific, values-linked examples
+6. Q&A (15–20 min)
+
+### Annual all-hands (2–4 hours, often a full day)
+
+**Structure:**
+1. Year in review: what we achieved (30 min)
+2. What we learned — what we'd do differently (20 min)
+3. State of the company: financial health, competitive position (20 min)
+4. 3-year vision update (30 min)
+5. Next year's strategy and priorities (30 min)
+6. Department presentations: what each team is building (60 min)
+7. Celebrations and recognition (20 min)
+8. Q&A + social (open-ended)
+
+### The "no-BS questions" technique
+
+At any all-hands, reserve the last 5 minutes for: "What question are you afraid to ask publicly? Submit anonymously via [link]."
+
+Read 3–5 of the hardest ones out loud and answer them honestly. This builds more trust than 45 minutes of polished presentation.
diff --git a/skills/c-level-advisor/internal-narrative/templates/all-hands-template.md b/skills/c-level-advisor/internal-narrative/templates/all-hands-template.md
new file mode 100644
index 00000000..c7579d59
--- /dev/null
+++ b/skills/c-level-advisor/internal-narrative/templates/all-hands-template.md
@@ -0,0 +1,103 @@
+# All-Hands Presentation Template
+
+**Monthly format (30–45 min) | Adjust timing for quarterly/annual**
+
+---
+
+## Slide 1: State of the Company
+
+**Headline:** One honest sentence about where we are right now.
+
+> "We're ahead on revenue, behind on hiring, and Q3 is looking strong."
+
+**3 key metrics (vs. target):**
+| Metric | Target | Actual | Status |
+|--------|--------|--------|--------|
+| ARR / Revenue | | | 🟢/🟡/🔴 |
+| [Key growth metric] | | | |
+| [Key health metric] | | | |
+
+**One sentence on momentum:** Are we accelerating, steady, or facing headwinds? Be honest.
+
+---
+
+## Slide 2: Progress on Quarterly Rocks
+
+For each company-level rock:
+
+| Rock | Owner | Status |
+|------|-------|--------|
+| [Rock 1 description] | [Name] | ✅ Done / 🟡 On track / 🔴 At risk |
+| [Rock 2 description] | [Name] | |
+| [Rock 3 description] | [Name] | |
+
+For any 🔴 at-risk rock: one sentence on what changed and what we're doing about it.
+
+---
+
+## Slide 3: What We're Proud Of
+
+**One specific win from the last 30 days.**
+
+Not the metric — the story behind it.
+
+> "CS team saved the Müller Group account after a critical feature gap was flagged 72 hours before their renewal. They pulled together engineering, product, and sales in 24 hours and presented a roadmap commitment that converted a churned account into an expansion. That's what customer obsession looks like."
+
+Tie to a company value. Name the people involved.
+
+---
+
+## Slide 4: What We Learned / What Didn't Work
+
+**One honest thing that didn't go as planned.**
+
+> "Our Q2 product launch was delayed 3 weeks because we underestimated the testing scope for the new export feature. We shipped it, customers are using it, but we learned that our pre-launch testing checklist needs to include third-party integration validation. We've added that to the template."
+
+If it's small: 2 sentences. If it's big: more time here, less elsewhere.
+
+**Why this slide exists:** A company that only celebrates wins teaches people to hide problems. This slide teaches people that honesty is valued.
+
+---
+
+## Slide 5: What's Coming Next 30 Days
+
+**3 things to know about:**
+
+1. [Upcoming release / launch / event] — [What it is and why it matters]
+2. [Hiring update or org change] — [Honest current state]
+3. [External event / partnership / market development] — [What we're watching]
+
+**What NOT to include:** Vague aspirations. Only things people can actually act on or prepare for.
+
+---
+
+## Slide 6: Q&A
+
+**Format:** Live questions preferred. Anonymous submission option always available.
+
+**CEO rules for Q&A:**
+- Answer the question asked, not the one you wish they'd asked
+- "I don't know, but I'll find out and share by [date]" > vague answer
+- "I can't share that yet because [reason], but I will when I can" > "no comment"
+- If the same question has been asked three times across all-hands, it's a communication gap — fix it
+
+**Closing line:**
+> "Thanks for your time. If you have a question you didn't get to ask — Slack me directly, or use the anonymous form. I read every one."
+
+---
+
+## Presenter Notes
+
+**Before every all-hands:**
+- [ ] Review last all-hands deck — anything promised that wasn't delivered?
+- [ ] Check: is there anything employees should have heard from us before this meeting?
+- [ ] Have 3–5 real Q&A answers prepared for the hardest questions you'd expect
+
+**During Q&A:**
+- [ ] Don't deflect hard questions — they remember
+- [ ] Don't over-explain — short answers signal confidence
+- [ ] Don't let one person dominate — "let's take that to a 1:1" is a valid response
+
+**After every all-hands:**
+- [ ] Send a written summary within 24 hours (key metrics, decisions, answers to top questions)
+- [ ] Follow up on any commitments made during Q&A within the stated timeframe
diff --git a/skills/c-level-advisor/intl-expansion/SKILL.md b/skills/c-level-advisor/intl-expansion/SKILL.md
new file mode 100644
index 00000000..34793d4c
--- /dev/null
+++ b/skills/c-level-advisor/intl-expansion/SKILL.md
@@ -0,0 +1,105 @@
+---
+name: "intl-expansion"
+description: "International market expansion strategy. Market selection, entry modes, localization, regulatory compliance, and go-to-market by region. Use when expanding to new countries, evaluating international markets, planning localization, or building regional teams."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: international-strategy
+ updated: 2026-03-05
+---
+
+# International Expansion
+
+Frameworks for expanding into new markets: selection, entry, localization, and execution.
+
+## Keywords
+international expansion, market entry, localization, go-to-market, GTM, regional strategy, international markets, market selection, cross-border, global expansion
+
+## Quick Start
+
+**Decision sequence:** Market selection → Entry mode → Regulatory assessment → Localization plan → GTM strategy → Team structure → Launch.
+
+## Market Selection Framework
+
+### Scoring Matrix
+| Factor | Weight | How to Assess |
+|--------|--------|---------------|
+| Market size (addressable) | 25% | TAM in target segment, willingness to pay |
+| Competitive intensity | 20% | Incumbent strength, market gaps |
+| Regulatory complexity | 20% | Barriers to entry, compliance cost, timeline |
+| Cultural distance | 15% | Language, business practices, buying behavior |
+| Existing traction | 10% | Inbound demand, existing customers, partnerships |
+| Operational complexity | 10% | Time zones, infrastructure, payment systems |
+
+### Entry Modes
+| Mode | Investment | Control | Risk | Best For |
+|------|-----------|---------|------|----------|
+| **Export** (sell remotely) | Low | Low | Low | Testing demand |
+| **Partnership** (reseller/distributor) | Medium | Medium | Medium | Markets with strong local requirements |
+| **Local team** (hire in-market) | High | High | High | Strategic markets with proven demand |
+| **Entity** (full subsidiary) | Very high | Full | High | Major markets, regulatory requirement |
+| **Acquisition** | Highest | Full | Highest | Fast market entry with existing base |
+
+**Default path:** Export → Partnership → Local team → Entity (graduate as revenue justifies).
+
+## Localization Checklist
+
+### Product
+- [ ] Language (UI, documentation, support content)
+- [ ] Currency and pricing (local pricing, not just conversion)
+- [ ] Payment methods (varies wildly by market)
+- [ ] Date/time/number formats
+- [ ] Legal requirements (data residency, privacy)
+- [ ] Cultural adaptation (not just translation)
+
+### Go-to-Market
+- [ ] Messaging adaptation (what resonates locally)
+- [ ] Channel strategy (channels differ by market)
+- [ ] Local case studies and social proof
+- [ ] Local partnerships and integrations
+- [ ] Event/conference presence
+- [ ] Local SEO and content
+
+### Operations
+- [ ] Legal entity (if required)
+- [ ] Tax compliance
+- [ ] Employment law (if hiring locally)
+- [ ] Customer support (hours, language)
+- [ ] Banking and payments
+
+## Key Questions
+
+- "Is there pull from the market, or are we pushing?"
+- "What's the cost of entry vs the 3-year revenue opportunity?"
+- "Can we serve this market from HQ, or do we need boots on the ground?"
+- "What's the regulatory timeline? Can we launch before the paperwork is done?"
+- "Who's winning in this market and what would it take to displace them?"
+
+## Common Mistakes
+
+| Mistake | Why It Happens | Prevention |
+|---------|---------------|------------|
+| Entering too many markets at once | FOMO, board pressure | Max 1-2 new markets per year |
+| Copy-paste GTM from home market | Assuming buyers are the same | Research local buying behavior |
+| Underestimating regulatory cost | "We'll figure it out" | Regulatory assessment BEFORE committing |
+| Hiring too early | Optimism | Prove demand before hiring local team |
+| Wrong pricing (just converting) | Laziness | Research willingness to pay locally |
+
+## Integration with C-Suite Roles
+
+| Role | Contribution |
+|------|-------------|
+| CEO | Market selection, strategic commitment |
+| CFO | Investment sizing, ROI modeling, entity structure |
+| CRO | Revenue targets, sales model adaptation |
+| CMO | Positioning, channel strategy, local brand |
+| CPO | Localization roadmap, feature priorities |
+| CTO | Infrastructure, data residency, scaling |
+| CHRO | Local hiring, employment law, comp |
+| COO | Operations setup, process adaptation |
+
+## Resources
+- `references/market-entry-playbook.md` — detailed entry playbook by market type
+- `references/regional-guide.md` — specific considerations for key regions (EU, US, APAC, LATAM)
diff --git a/skills/c-level-advisor/intl-expansion/references/market-entry-playbook.md b/skills/c-level-advisor/intl-expansion/references/market-entry-playbook.md
new file mode 100644
index 00000000..f7acd81b
--- /dev/null
+++ b/skills/c-level-advisor/intl-expansion/references/market-entry-playbook.md
@@ -0,0 +1,138 @@
+# Market Entry Playbook
+
+Step-by-step framework for entering a new international market.
+
+## Phase 0: Validation (4-8 weeks)
+
+Before committing resources, validate demand:
+
+### Signal Assessment
+| Signal | Strength | Action |
+|--------|----------|--------|
+| Inbound inquiries from the market | Strong | Fast-track evaluation |
+| Existing customers using from that market | Strong | Interview them, understand needs |
+| Competitor succeeding there | Medium | Market exists, but competition too |
+| Partner referral | Medium | Validate independently |
+| Market research says it's big | Weak | Research ≠ demand |
+| Board says "we should be in X" | Weakest | Push back with data |
+
+### Lightweight Validation
+1. **Landing page test** — localized landing page with waitlist
+2. **Ad spend test** — $2-5K in targeted ads, measure conversion
+3. **Sales outreach** — 20 calls to potential customers in market
+4. **Partner conversations** — 3-5 potential local partners
+5. **Competitor analysis** — who's there, what they charge, customer reviews
+
+**Pass criteria:** At least 2 of: qualified pipeline > $50K, waitlist > 100, partner willing to co-sell.
+
+## Phase 1: Planning (4-6 weeks)
+
+### Market-Specific GTM
+| Element | Home Market | New Market | Notes |
+|---------|------------|------------|-------|
+| ICP | [your ICP] | [adapted ICP] | May be different segment |
+| Pricing | [home price] | [local price] | Value-based, not conversion |
+| Channels | [home channels] | [local channels] | Research what works locally |
+| Sales model | [home model] | [adapted model] | Self-serve may not work everywhere |
+| Support | [home support] | [local support] | Language, hours, expectations |
+
+### Pricing Strategy by Market
+- **Developed markets (US, UK, DACH, Nordics):** Price for value, premium positioning
+- **Growth markets (Southern Europe, Eastern Europe):** 20-40% discount from core market
+- **Emerging markets (LATAM, SEA):** 40-60% discount or different packaging
+- **Enterprise everywhere:** Don't discount — add local value instead
+
+### Regulatory Pre-Work
+1. Data residency requirements (where must data live?)
+2. Industry-specific regulations (healthcare, finance, education)
+3. Tax obligations (VAT, withholding, nexus)
+4. Employment law basics (if hiring)
+5. Import/export restrictions (if applicable)
+6. Timeline to compliance (weeks, months, years?)
+
+## Phase 2: Entry (8-12 weeks)
+
+### Minimum Viable Presence
+| Element | MVP | Full | When to Upgrade |
+|---------|-----|------|-----------------|
+| Legal entity | None (sell cross-border) | Local subsidiary | Revenue > $500K/year |
+| Team | Remote sales + support | Local office | > 5 local employees |
+| Product | English + key translations | Full localization | Customer feedback demands it |
+| Payments | International card processing | Local payment methods | Conversion drops |
+| Support | Home team covers (extended hours) | Local support team | Volume requires it |
+
+### Launch Sequence
+1. **Week 1-2:** Product localization (minimum viable)
+2. **Week 3-4:** Local pricing and payment setup
+3. **Week 5-6:** Marketing launch (content, ads, PR)
+4. **Week 7-8:** Sales activation (outreach, partner launch)
+5. **Week 9-12:** Iterate based on first customers
+
+### First 10 Customers
+These are your foundation. Over-invest in their success:
+- Weekly check-ins for first 90 days
+- Dedicated support contact
+- Feedback loop to product team
+- Case study development
+- Referral program
+
+## Phase 3: Scale (6-12 months)
+
+### When to Invest More
+| Signal | Action |
+|--------|--------|
+| Pipeline > 3x capacity | Hire more sales |
+| Support tickets in local language > 30% | Hire local support |
+| Regulatory requirement for local entity | Establish subsidiary |
+| Revenue > $500K ARR from market | Appoint country manager |
+| 3+ enterprise deals require local presence | Open local office |
+
+### Country Manager Profile
+First local hire matters enormously:
+- **Must have:** Domain expertise, local network, startup mentality
+- **Nice to have:** Experience with your type of product
+- **Red flag:** Wants to build a big team immediately
+- **Ideal:** Someone who can sell, support, and partner — a generalist
+
+### Common Scaling Mistakes
+1. **Hiring a country manager too early** — Before product-market fit in that market
+2. **Building a full local team before proving the model** — Expensive and hard to unwind
+3. **Letting the local team operate independently** — They need to integrate, not isolate
+4. **Ignoring local competition** — They know the market better than you
+5. **Applying home-market playbook** — What works in the US may fail in Germany
+
+## Market Type Playbooks
+
+### Expanding Within Europe (DACH → EU)
+- Regulatory: GDPR already covers you, but check industry-specific
+- Languages: English works for Nordics/Netherlands, but not for France/Spain/Italy
+- Pricing: PPP varies less within EU, but willingness to pay differs
+- Sales: Direct works for DACH/Nordics, partner-heavy for Southern Europe
+- Fastest path: UK → Nordics → Benelux → France → Spain → Italy
+
+### Entering the US from Europe
+- Legal: Delaware C-Corp for investment compatibility
+- Sales: Everything is bigger — territories, deal sizes, expectations
+- Pricing: Usually 20-30% higher than Europe
+- Support: US customers expect fast response, US business hours
+- Competition: More competitors, but also more budget
+- Entry: Start with coast (NYC or SF), not middle America
+
+### Entering APAC
+- Diversity: APAC is not one market — it's 20+
+- Start: Singapore (English, business-friendly) or Australia
+- Japan/Korea: Need local partner, high localization bar
+- India: Large market, price-sensitive, relationship-driven
+- China: Separate strategy entirely, regulatory complexity extreme
+
+## Measuring Success
+
+| Metric | Month 3 Target | Month 6 Target | Month 12 Target |
+|--------|---------------|----------------|-----------------|
+| Pipeline | 10x of revenue target | 5x of revenue target | 3x of revenue target |
+| Customers | 5-10 | 20-50 | 50-100+ |
+| ARR | $50-100K | $200-500K | $500K-1M |
+| NPS | > 30 | > 40 | > 50 |
+| Churn | < 5% monthly | < 3% monthly | < 2% monthly |
+
+Metrics should improve each quarter. If they flatten, something's wrong with product-market fit in that specific market.
diff --git a/skills/c-level-advisor/intl-expansion/references/regional-guide.md b/skills/c-level-advisor/intl-expansion/references/regional-guide.md
new file mode 100644
index 00000000..705459cc
--- /dev/null
+++ b/skills/c-level-advisor/intl-expansion/references/regional-guide.md
@@ -0,0 +1,144 @@
+# Regional Expansion Guide
+
+Specific considerations for key regions. Not exhaustive — these are the patterns that trip up most expanding companies.
+
+## Europe
+
+### DACH (Germany, Austria, Switzerland)
+- **Language:** German required for SMB. Enterprise sometimes English.
+- **Sales:** Relationship-driven, longer cycles, value formal proposals
+- **Pricing:** Willing to pay premium for quality and reliability
+- **Compliance:** GDPR, industry-specific (MDR for medical devices, BaFin for finance)
+- **Payment:** SEPA, invoice preferred for B2B (not credit cards)
+- **Culture:** Punctuality matters. Directness is respected. Don't oversell.
+- **Data:** Strong preference for EU data residency
+- **Entity:** GmbH for subsidiary, typically €25K minimum capital
+
+### Nordics (Sweden, Norway, Denmark, Finland)
+- **Language:** English widely accepted in business
+- **Sales:** Consensus-driven decisions, flat hierarchies
+- **Pricing:** High willingness to pay, value innovation
+- **Compliance:** GDPR, strong data protection culture
+- **Culture:** Equality-focused, sustainability matters, low-key approach preferred
+- **Entry:** Often the easiest European expansion for English-speaking companies
+
+### France
+- **Language:** French required, even for enterprise (most buyers prefer it)
+- **Sales:** Formal, hierarchical decision-making, relationships matter
+- **Pricing:** Price-sensitive but willing to invest in proven solutions
+- **Compliance:** GDPR + CNIL (strict data authority), French hosting preference
+- **Culture:** Business lunches are real meetings. Email etiquette matters.
+- **Entity:** SAS or SARL, complex employment law
+
+### UK
+- **Language:** English (obviously)
+- **Sales:** Similar to US but smaller deal sizes
+- **Pricing:** Competitive market, price comparisons common
+- **Compliance:** UK GDPR (post-Brexit), FCA for finance
+- **Culture:** Understated, humor works, don't be too pushy
+- **Post-Brexit:** Separate data adequacy, some regulatory divergence
+
+### Southern Europe (Spain, Italy, Portugal)
+- **Language:** Local language strongly preferred
+- **Sales:** Relationship-heavy, trust-based, longer cycles
+- **Pricing:** Lower willingness to pay than Northern Europe
+- **Entry:** Partner/reseller model often more effective than direct
+- **Culture:** Personal relationships precede business relationships
+- **Timing:** August is essentially closed in many industries
+
+### Eastern Europe (Poland, Czech Republic, Romania)
+- **Language:** Local language for SMB, English for enterprise/tech
+- **Sales:** Growing market, value-conscious, quick adoption of new tech
+- **Pricing:** 30-50% of Western European pricing
+- **Talent:** Excellent engineering talent for local offices
+- **Entry:** Often good for first offshore team, not just sales
+
+## United States
+
+### General
+- **Entity:** Delaware C-Corp if seeking US investment
+- **Sales:** Expect American-style responsiveness (same-day replies)
+- **Pricing:** Higher than Europe (typically 20-40%)
+- **Compliance:** State-by-state complexity (privacy, tax nexus)
+- **Culture:** Optimistic, results-oriented, comfortable with direct outreach
+- **Legal:** More litigious environment, good contracts essential
+
+### Regional Differences
+| Region | Characteristics |
+|--------|----------------|
+| **West Coast** | Tech-forward, early adopters, startup-friendly |
+| **East Coast** | Enterprise-heavy, finance and healthcare strong |
+| **Midwest** | Manufacturing, agriculture, relationship-driven, underserved |
+| **South** | Growing tech hubs (Austin, Atlanta, Nashville), cost-conscious |
+
+### Key Considerations
+- Sales tax: Complex, state-dependent, use automation (Stripe Tax, Avalara)
+- Privacy: California (CCPA/CPRA), Virginia, Colorado, Connecticut have state laws
+- Employment: At-will, but benefits expectations are high
+- Health insurance: Expected by employees (significant cost)
+
+## APAC
+
+### Singapore
+- **Best entry point for APAC** (English, business-friendly, strong rule of law)
+- Low tax, easy incorporation, access to Southeast Asian markets
+- Small domestic market — use as hub, not primary market
+
+### Australia
+- **English-speaking, familiar business culture** (similar to UK)
+- Strong B2B market, good for SaaS
+- Data privacy: Australian Privacy Act
+- Time zones: Challenge for support from Europe
+
+### Japan
+- **Highest quality bar in the world** — products must be polished
+- Local partner essential (trust, introductions, support)
+- Japanese localization is non-negotiable
+- Long sales cycles but very loyal once committed
+- Business etiquette matters significantly
+
+### India
+- **Huge market but price-sensitive**
+- Strong engineering talent market
+- Relationship-driven, patience required
+- UPI and local payment methods essential
+- Often better as talent market than sales market initially
+
+## LATAM
+
+### General
+- Portuguese (Brazil) and Spanish (rest) — two distinct markets
+- Growing SaaS adoption, especially in Brazil, Mexico, Colombia
+- Price-sensitive but growing willingness to pay for quality
+- Boleto (Brazil) and local payment methods essential
+- Currency volatility can affect pricing strategy
+
+### Brazil
+- Largest LATAM market by far
+- Complex tax system (NF-e, ICMS, PIS/COFINS)
+- Portuguese required, no exceptions
+- Strong startup ecosystem (São Paulo)
+- Data privacy: LGPD (similar to GDPR)
+
+### Mexico
+- Second largest LATAM market
+- Growing US business ties
+- Spanish required
+- Proximity to US is strategic advantage
+- Increasing SaaS adoption
+
+## Cross-Region Patterns
+
+### What Works Everywhere
+- Start with existing customer demand (pull, not push)
+- Invest in local language support before local sales
+- Price for the market, not for your cost structure
+- Build local case studies as fast as possible
+- Find one strong local partner before hiring
+
+### What Never Works
+- Assuming English is enough (even when people speak it)
+- Copy-pasting marketing materials with just translation
+- Ignoring local payment preferences
+- Treating "Europe" or "APAC" as single markets
+- Sending your best home-market rep without local context
diff --git a/skills/c-level-advisor/ma-playbook/SKILL.md b/skills/c-level-advisor/ma-playbook/SKILL.md
new file mode 100644
index 00000000..4abdeafe
--- /dev/null
+++ b/skills/c-level-advisor/ma-playbook/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: "ma-playbook"
+description: "M&A strategy for acquiring companies or being acquired. Due diligence, valuation, integration, and deal structure. Use when evaluating acquisitions, preparing for acquisition, M&A due diligence, integration planning, or deal negotiation."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: ma-strategy
+ updated: 2026-03-05
+---
+
+# M&A Playbook
+
+Frameworks for both sides of M&A: acquiring companies and being acquired.
+
+## Keywords
+M&A, mergers and acquisitions, due diligence, acquisition, acqui-hire, integration, deal structure, valuation, LOI, term sheet, earnout
+
+## Quick Start
+
+**Acquiring:** Start with strategic rationale → target screening → due diligence → valuation → negotiation → integration.
+
+**Being Acquired:** Start with readiness assessment → data room prep → advisor selection → negotiation → transition.
+
+## When You're Acquiring
+
+### Strategic Rationale (answer before anything else)
+- **Buy vs Build:** Can you build this faster/cheaper? If yes, don't acquire.
+- **Acqui-hire vs Product vs Market:** What are you really buying? Talent? Technology? Customers?
+- **Integration complexity:** How hard is it to merge this into your company?
+
+### Due Diligence Checklist
+| Domain | Key Questions | Red Flags |
+|--------|--------------|-----------|
+| Financial | Revenue quality, customer concentration, burn rate | >30% revenue from 1 customer |
+| Technical | Code quality, tech debt, architecture fit | Monolith with no tests |
+| Legal | IP ownership, pending litigation, contracts | Key IP owned by individuals |
+| People | Key person risk, culture fit, retention risk | Founders have no lockup/earnout |
+| Market | Market position, competitive threats | Declining market share |
+| Customers | Churn rate, NPS, contract terms | High churn, short contracts |
+
+### Valuation Approaches
+- **Revenue multiple:** Industry-dependent (2-15x ARR for SaaS)
+- **Comparable transactions:** What similar companies sold for
+- **DCF:** For profitable companies only (most startups: use multiples)
+- **Acqui-hire:** $1-3M per engineer in hot markets
+
+### Integration Frameworks
+See `references/integration-playbook.md` for the 100-day integration plan.
+
+## When You're Being Acquired
+
+### Readiness Signals
+- Inbound interest from strategic buyers
+- Market consolidation happening around you
+- Fundraising becomes harder than operating
+- Founder ready for a transition
+
+### Preparation (6-12 months before)
+1. Clean up financials (audited if possible)
+2. Document all IP and contracts
+3. Reduce customer concentration
+4. Lock up key employees
+5. Build the data room
+6. Engage an M&A advisor
+
+### Negotiation Points
+| Term | What to Watch | Your Leverage |
+|------|--------------|---------------|
+| Valuation | Earnout traps (unreachable targets) | Multiple competing offers |
+| Earnout | Milestone definitions, measurement period | Cash-heavy vs earnout-heavy split |
+| Lockup | Duration, conditions | Your replaceability |
+| Rep & warranties | Scope of liability | Escrow vs indemnification cap |
+| Employee retention | Who gets offers, at what terms | Key person dependencies |
+
+## Red Flags (Both Sides)
+
+- No clear strategic rationale beyond "it's a good deal"
+- Culture clash visible during due diligence and ignored
+- Key people not locked in before close
+- Integration plan doesn't exist or is "we'll figure it out"
+- Valuation based on projections, not actuals
+
+## Integration with C-Suite Roles
+
+| Role | Contribution to M&A |
+|------|-------------------|
+| CEO | Strategic rationale, negotiation lead |
+| CFO | Valuation, deal structure, financing |
+| CTO | Technical due diligence, integration architecture |
+| CHRO | People due diligence, retention planning |
+| COO | Integration execution, process merge |
+| CPO | Product roadmap impact, customer overlap |
+
+## Resources
+- `references/integration-playbook.md` — 100-day post-acquisition integration plan
+- `references/due-diligence-checklist.md` — comprehensive DD checklist by domain
diff --git a/skills/c-level-advisor/ma-playbook/references/due-diligence-checklist.md b/skills/c-level-advisor/ma-playbook/references/due-diligence-checklist.md
new file mode 100644
index 00000000..8fa28257
--- /dev/null
+++ b/skills/c-level-advisor/ma-playbook/references/due-diligence-checklist.md
@@ -0,0 +1,148 @@
+# M&A Due Diligence Checklist
+
+Comprehensive due diligence organized by domain. Not every item applies to every deal — focus on what matters for YOUR acquisition rationale.
+
+## Financial Due Diligence
+
+### Revenue Quality
+- [ ] Revenue by customer (top 10 customer concentration)
+- [ ] Revenue by product line
+- [ ] Revenue by geography
+- [ ] MRR/ARR trend (24 months minimum)
+- [ ] Churn rate (gross and net, by cohort)
+- [ ] Revenue recognition policies
+- [ ] Deferred revenue / backlog
+- [ ] One-time vs recurring revenue split
+- [ ] Professional services vs product revenue
+
+### Profitability
+- [ ] Gross margin by product line
+- [ ] Operating expenses breakdown
+- [ ] Burn rate trend (improving or worsening?)
+- [ ] Path to profitability (realistic or aspirational?)
+- [ ] Unit economics (LTV, CAC, payback by channel)
+
+### Cash & Liabilities
+- [ ] Cash position and burn rate
+- [ ] Outstanding debt (terms, covenants)
+- [ ] Accounts receivable aging
+- [ ] Accounts payable
+- [ ] Pending or contingent liabilities
+- [ ] Tax obligations (any back taxes?)
+- [ ] Cap table (fully diluted, option pool)
+
+### Financial Controls
+- [ ] Audit history (audited vs reviewed vs compiled)
+- [ ] Financial reporting cadence and quality
+- [ ] Budget vs actual variance history
+- [ ] Key financial policies
+
+## Technical Due Diligence
+
+### Architecture
+- [ ] Architecture diagrams (current state)
+- [ ] Technology stack inventory
+- [ ] Infrastructure (cloud provider, regions, costs)
+- [ ] Scalability assessment (current capacity vs load)
+- [ ] Security architecture (encryption, access controls)
+
+### Code Quality
+- [ ] Test coverage (unit, integration, e2e)
+- [ ] CI/CD pipeline maturity
+- [ ] Technical debt inventory (estimated remediation cost)
+- [ ] Code review practices
+- [ ] Documentation quality
+
+### Data
+- [ ] Data architecture and storage
+- [ ] Data privacy compliance (GDPR, CCPA)
+- [ ] Data portability (can you migrate it?)
+- [ ] Proprietary data assets (training data, user data)
+- [ ] Data retention policies
+
+### Operational
+- [ ] Uptime history (SLA compliance)
+- [ ] Incident history (frequency, severity, resolution time)
+- [ ] Monitoring and alerting coverage
+- [ ] Disaster recovery plan and testing history
+- [ ] On-call rotation and processes
+
+## Legal Due Diligence
+
+### Intellectual Property
+- [ ] Patents (granted and pending)
+- [ ] Trademarks
+- [ ] Copyright registrations
+- [ ] IP assignment agreements (all employees/contractors)
+- [ ] Open source usage and compliance
+- [ ] Trade secrets protection measures
+
+### Contracts
+- [ ] Customer contracts (terms, renewals, termination rights)
+- [ ] Vendor contracts (key dependencies, terms)
+- [ ] Partnership agreements
+- [ ] Lease agreements
+- [ ] Employment agreements (non-competes, IP clauses)
+
+### Compliance & Litigation
+- [ ] Pending or threatened litigation
+- [ ] Regulatory compliance status
+- [ ] Government investigations
+- [ ] Insurance coverage
+- [ ] Prior legal disputes and resolutions
+
+## People Due Diligence
+
+### Team Composition
+- [ ] Org chart with roles and tenure
+- [ ] Key person dependencies (bus factor)
+- [ ] Compensation details (salary, equity, bonuses)
+- [ ] Employment agreements and non-competes
+- [ ] Contractor vs employee classification
+
+### Culture & Retention
+- [ ] Recent engagement survey results
+- [ ] Turnover rate (last 12-24 months)
+- [ ] Glassdoor/reputation assessment
+- [ ] Management quality assessment
+- [ ] Culture compatibility analysis
+
+### HR Compliance
+- [ ] Employee handbook and policies
+- [ ] HR complaints or investigations
+- [ ] Benefits programs
+- [ ] Equity plan details and administration
+
+## Market Due Diligence
+
+### Market Position
+- [ ] Market size (TAM, SAM, SOM) with sources
+- [ ] Market share estimate
+- [ ] Growth rate (market and company)
+- [ ] Competitive landscape (direct and indirect)
+- [ ] Barriers to entry / competitive moat
+
+### Customer Analysis
+- [ ] Customer segmentation
+- [ ] Win/loss analysis (why customers chose them)
+- [ ] NPS or satisfaction scores
+- [ ] Customer acquisition channels
+- [ ] Customer lifetime and expansion patterns
+
+## Red Flag Severity Guide
+
+| Severity | Examples | Action |
+|----------|---------|--------|
+| **Deal killer** | IP not properly assigned, undisclosed litigation, fraud | Walk away |
+| **Major renegotiation** | Customer concentration >40%, key person risk, technical debt >6 months | Reduce price or add protections |
+| **Integration risk** | Culture mismatch, legacy systems, manual processes | Budget for remediation |
+| **Monitor** | High churn, declining NPS, aging tech stack | Track post-close |
+
+## Due Diligence Timeline
+
+| Phase | Duration | Focus |
+|-------|----------|-------|
+| Preliminary | 1-2 weeks | Public info, financials, high-level tech |
+| Deep dive | 4-6 weeks | All domains, interviews, code review |
+| Confirmation | 1-2 weeks | Verify claims, resolve open questions |
+| Final | 1 week | Legal review, final terms negotiation |
diff --git a/skills/c-level-advisor/ma-playbook/references/integration-playbook.md b/skills/c-level-advisor/ma-playbook/references/integration-playbook.md
new file mode 100644
index 00000000..7dc82061
--- /dev/null
+++ b/skills/c-level-advisor/ma-playbook/references/integration-playbook.md
@@ -0,0 +1,145 @@
+# Post-Acquisition Integration Playbook
+
+The 100-day plan for integrating an acquisition. Most acquisitions fail not because of bad deals but bad integration.
+
+## The Integration Paradox
+
+Move too fast → you break what you bought.
+Move too slow → talent leaves, customers churn, value evaporates.
+
+**The rule:** Decide on day 1 what stays separate and what merges. Then execute without wavering.
+
+## Pre-Close (Day -30 to 0)
+
+### Integration Lead
+- Appoint ONE integration lead (not a committee)
+- This person reports to the CEO, has authority over all workstreams
+- Full-time role for 100 days minimum
+
+### Planning
+| Workstream | Owner | Day 1 Decisions |
+|-----------|-------|-----------------|
+| People | CHRO | Who stays, comp alignment, reporting lines |
+| Technology | CTO | Systems to merge, timeline, migration order |
+| Customers | CRO | Communication plan, account ownership |
+| Product | CPO | Roadmap integration, feature consolidation |
+| Operations | COO | Process alignment, tool consolidation |
+| Finance | CFO | Entity structure, billing, reporting |
+| Legal | External | Contract assignments, IP transfer |
+
+### Communication Plan (ready before close)
+- Employee announcement (both companies) — Day 1
+- Customer notification — Day 1-3
+- Partner/vendor notification — Week 1
+- Public announcement — per deal terms
+
+## Week 1 (Days 1-7): Stabilize
+
+**Goal:** No one leaves, no customer churns, operations continue.
+
+- [ ] All-hands meeting (both companies together)
+- [ ] 1:1 with every acquired leader (within 48 hours)
+- [ ] Retention packages confirmed for key employees
+- [ ] Customer communication sent (personal for top 20 accounts)
+- [ ] Systems access provisioned (email, Slack, tools)
+- [ ] Integration FAQ published internally
+
+### The First All-Hands
+What people want to hear:
+1. Why this happened (honest version)
+2. What changes (be specific, not vague)
+3. What doesn't change (equally important)
+4. Their job security (be direct)
+5. Timeline for decisions
+
+What NOT to say: "Nothing will change." (It will. They know it.)
+
+## Month 1 (Days 1-30): Orient
+
+**Goal:** Teams know each other, quick wins shipped, blockers identified.
+
+### People
+- [ ] Org chart finalized and communicated
+- [ ] Comp band alignment completed
+- [ ] Benefits transition timeline published
+- [ ] Cross-team introductions facilitated (not forced)
+- [ ] Culture assessment: what's different, what's compatible
+
+### Technology
+- [ ] Architecture assessment complete
+- [ ] Migration priority ranked (quick wins first)
+- [ ] Shared development environment established
+- [ ] Code access and permissions set up
+- [ ] Technical debt from both sides documented
+
+### Customers
+- [ ] Top 20 accounts contacted personally by leadership
+- [ ] Unified support channel established (or plan for it)
+- [ ] Pricing/contract transition plan for overlapping customers
+- [ ] Product roadmap communication (what's coming, what's being deprecated)
+
+### Quick Wins
+Ship something visible in the first 30 days. A feature that combines both companies' strengths. This proves the acquisition works better than any memo.
+
+## Month 2-3 (Days 31-100): Integrate
+
+**Goal:** Core systems merged, one team operating, value creation visible.
+
+### Systems Integration Priority
+1. **Communication** (Slack, email) — Week 2
+2. **Identity** (SSO, accounts) — Week 3
+3. **Development** (repos, CI/CD) — Month 1
+4. **Data** (analytics, CRM) — Month 2
+5. **Product** (shared platform) — Month 2-3
+6. **Finance** (billing, reporting) — Month 3
+
+### Culture Integration
+- **Don't:** Force the acquired team to adopt everything immediately
+- **Do:** Find the best practices from BOTH cultures, adopt the winner
+- **Don't:** Rename everything on Day 1
+- **Do:** Co-create the combined identity over 60 days
+- **Watch for:** "Us vs them" language, meeting exclusions, information hoarding
+
+### Measuring Integration Success
+| Metric | Target | Frequency |
+|--------|--------|-----------|
+| Employee retention (key people) | > 90% at 100 days | Weekly |
+| Customer retention | > 95% at 100 days | Monthly |
+| Cross-team collaboration (PRs, meetings) | Increasing trend | Weekly |
+| Synergy revenue (combined offerings) | First deal within 60 days | Monthly |
+| Integration milestones hit | > 80% on time | Weekly |
+
+## Post-100 Days
+
+Integration isn't "done" at 100 days. But the foundation should be solid.
+
+### Ongoing
+- Quarterly integration retrospective (what's working, what isn't)
+- Culture health check at 6 months
+- Full financial integration assessment at 12 months
+- Earnout milestone tracking (if applicable)
+
+### Common Failure Modes
+| Failure | Root Cause | Prevention |
+|---------|-----------|------------|
+| Key talent leaves at month 4 | Retention cliff, culture mismatch | Longer earnout, culture attention |
+| Customer churn spike at month 6 | Product changes without warning | Over-communicate product roadmap |
+| "Two companies in a trenchcoat" | Incomplete integration | Force cross-functional projects |
+| Value never materializes | Wrong acquisition rationale | Kill the deal if rationale was wrong |
+| Acquirer culture overwhelms | "Our way is the only way" | Adopt best of both explicitly |
+
+## The Kill Switch
+
+Sometimes acquisitions don't work. Signs it's failing:
+- Key people leaving despite retention packages
+- Customers churning above baseline
+- Integration milestones consistently missed
+- Culture clash worsening, not improving
+- Revenue synergies aren't materializing at month 6
+
+**Options:**
+1. Double down with new integration lead and plan
+2. Operate as semi-autonomous unit (less integration)
+3. Spin off or divest (expensive, but sometimes necessary)
+
+Admitting failure early costs less than dragging it out.
diff --git a/skills/c-level-advisor/org-health-diagnostic/SKILL.md b/skills/c-level-advisor/org-health-diagnostic/SKILL.md
new file mode 100644
index 00000000..a1c36d9b
--- /dev/null
+++ b/skills/c-level-advisor/org-health-diagnostic/SKILL.md
@@ -0,0 +1,185 @@
+---
+name: "org-health-diagnostic"
+description: "Cross-functional organizational health check combining signals from all C-suite roles. Scores 8 dimensions on a traffic-light scale with drill-down recommendations. Use when assessing overall company health, preparing for board reviews, identifying at-risk functions, or when user mentions org health, health check, or health dashboard."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: organizational-health
+ updated: 2026-03-05
+ python-tools: health_scorer.py
+ frameworks: health-benchmarks
+---
+
+# Org Health Diagnostic
+
+Eight dimensions. Traffic lights. Real benchmarks. Surfaces the problems you don't know you have.
+
+## Keywords
+org health, organizational health, health diagnostic, health dashboard, health check, company health, functional health, team health, startup health, health scorecard, health assessment, risk dashboard
+
+## Quick Start
+
+```bash
+python scripts/health_scorer.py # Guided CLI — enter metrics, get scored dashboard
+python scripts/health_scorer.py --json # Output raw JSON for integration
+```
+
+Or describe your metrics:
+```
+/health [paste your key metrics or answer prompts]
+/health:dimension [financial|revenue|product|engineering|people|ops|security|market]
+```
+
+## The 8 Dimensions
+
+### 1. 💰 Financial Health (CFO)
+**What it measures:** Can we fund operations and invest in growth?
+
+Key metrics:
+- **Runway** — months at current burn (Green: >12, Yellow: 6-12, Red: <6)
+- **Burn multiple** — net burn / net new ARR (Green: <1.5x, Yellow: 1.5-2.5x, Red: >2.5x)
+- **Gross margin** — SaaS target: >65% (Green: >70%, Yellow: 55-70%, Red: <55%)
+- **MoM growth rate** — contextual by stage (see benchmarks)
+- **Revenue concentration** — top customer % of ARR (Green: <15%, Yellow: 15-25%, Red: >25%)
+
+### 2. 📈 Revenue Health (CRO)
+**What it measures:** Are customers staying, growing, and recommending us?
+
+Key metrics:
+- **NRR (Net Revenue Retention)** — Green: >110%, Yellow: 100-110%, Red: <100%
+- **Logo churn rate (annualized)** — Green: <5%, Yellow: 5-10%, Red: >10%
+- **Pipeline coverage (next quarter)** — Green: >3x, Yellow: 2-3x, Red: <2x
+- **CAC payback period** — Green: <12 months, Yellow: 12-18, Red: >18 months
+- **Average ACV trend** — directional: growing, flat, declining
+
+### 3. 🚀 Product Health (CPO)
+**What it measures:** Do customers love and use the product?
+
+Key metrics:
+- **NPS** — Green: >40, Yellow: 20-40, Red: <20
+- **DAU/MAU ratio** — engagement proxy (Green: >40%, Yellow: 20-40%, Red: <20%)
+- **Core feature adoption** — % of users using primary value feature (Green: >60%)
+- **Time-to-value** — days from signup to first core action (lower is better)
+- **Customer satisfaction (CSAT)** — Green: >4.2/5, Yellow: 3.5-4.2, Red: <3.5
+
+### 4. ⚙️ Engineering Health (CTO)
+**What it measures:** Can we ship reliably and sustain velocity?
+
+Key metrics:
+- **Deployment frequency** — Green: daily, Yellow: weekly, Red: monthly or less
+- **Change failure rate** — % of deployments causing incidents (Green: <5%, Red: >15%)
+- **Mean time to recovery (MTTR)** — Green: <1 hour, Yellow: 1-4 hours, Red: >4 hours
+- **Tech debt ratio** — % of sprint capacity on debt (Green: <20%, Yellow: 20-35%, Red: >35%)
+- **Incident frequency** — P0/P1 per month (Green: <2, Yellow: 2-5, Red: >5)
+
+### 5. 👥 People Health (CHRO)
+**What it measures:** Is the team stable, engaged, and growing?
+
+Key metrics:
+- **Regrettable attrition (annualized)** — Green: <10%, Yellow: 10-20%, Red: >20%
+- **Engagement score** — (eNPS or similar; Green: >30, Yellow: 0-30, Red: <0)
+- **Time-to-fill (avg days)** — Green: <45, Yellow: 45-90, Red: >90
+- **Manager-to-IC ratio** — Green: 1:5–1:8, Yellow: 1:3–1:5 or 1:8–1:12, Red: outside
+- **Internal promotion rate** — at least 25-30% of senior roles filled internally
+
+### 6. 🔄 Operational Health (COO)
+**What it measures:** Are we executing our strategy with discipline?
+
+Key metrics:
+- **OKR completion rate** — % of key results hitting target (Green: >70%, Yellow: 50-70%, Red: <50%)
+- **Decision cycle time** — days from decision needed to decision made (Green: <48h, Yellow: 48h-1w)
+- **Meeting effectiveness** — % of meetings with clear outcome (qualitative)
+- **Process maturity** — level 1-5 scale (see COO advisor)
+- **Cross-functional initiative completion** — % on time, on scope
+
+### 7. 🔒 Security Health (CISO)
+**What it measures:** Are we protecting customers and maintaining compliance?
+
+Key metrics:
+- **Security incidents (last 90 days)** — Green: 0, Yellow: 1-2 minor, Red: 1+ major
+- **Compliance status** — certifications current/in-progress vs. overdue
+- **Vulnerability remediation SLA** — % of critical CVEs patched within SLA (Green: 100%)
+- **Security training completion** — % of team current (Green: >95%)
+- **Pen test recency** — Green: <12 months, Yellow: 12-24, Red: >24 months
+
+### 8. 📣 Market Health (CMO)
+**What it measures:** Are we winning in the market and growing efficiently?
+
+Key metrics:
+- **CAC trend** — improving, flat, or worsening QoQ
+- **Organic vs paid lead mix** — more organic = healthier (less fragile)
+- **Win rate** — % of qualified opportunities closed-won (Green: >25%, Yellow: 15-25%, Red: <15%)
+- **Competitive win rate** — against primary competitors specifically
+- **Brand NPS** — awareness + preference scores in ICP
+
+---
+
+## Scoring & Traffic Lights
+
+Each dimension is scored 1-10 with traffic light:
+- 🟢 **Green (7-10):** Healthy — maintain and optimize
+- 🟡 **Yellow (4-6):** Watch — trend matters; improving or declining?
+- 🔴 **Red (1-3):** Action required — address within 30 days
+
+**Overall Health Score:**
+Weighted average by company stage (see `references/health-benchmarks.md` for weights).
+
+---
+
+## Dimension Interactions (Why One Problem Creates Another)
+
+| If this dimension is red... | Watch these dimensions next |
+|-----------------------------|----------------------------|
+| Financial Health | People (freeze hiring) → Engineering (freeze infra) → Product (cut scope) |
+| Revenue Health | Financial (cash gap) → People (attrition risk) → Market (lose positioning) |
+| People Health | Engineering (velocity drops) → Product (quality drops) → Revenue (churn rises) |
+| Engineering Health | Product (features slip) → Revenue (deals stall on product) |
+| Product Health | Revenue (NRR drops, churn rises) → Market (CAC rises; referrals dry up) |
+| Operational Health | All dimensions degrade over time (execution failure cascades everywhere) |
+
+---
+
+## Dashboard Output Format
+
+```
+ORG HEALTH DIAGNOSTIC — [Company] — [Date]
+Stage: [Seed/A/B/C] Overall: [Score]/10 Trend: [↑ Improving / → Stable / ↓ Declining]
+
+DIMENSION SCORES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💰 Financial 🟢 8.2 Runway 14mo, burn 1.6x — strong
+📈 Revenue 🟡 5.8 NRR 104%, pipeline thin (1.8x coverage)
+🚀 Product 🟢 7.4 NPS 42, DAU/MAU 38%
+⚙️ Engineering 🟡 5.2 Debt at 30%, MTTR 3.2h
+👥 People 🔴 3.8 Attrition 24%, eng morale low
+🔄 Operations 🟡 6.0 OKR 65% completion
+🔒 Security 🟢 7.8 SOC 2 Type II complete, 0 incidents
+📣 Market 🟡 5.5 CAC rising, win rate dropped to 22%
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TOP PRIORITIES
+🔴 [1] People: attrition at 24% — engineering velocity will drop in 60 days
+ Action: CHRO + CEO to run retention audit; target top 5 at-risk this week
+🟡 [2] Revenue: pipeline coverage at 1.8x — Q+1 miss risk is high
+ Action: CRO to add 3 qualified opps within 30 days or shift forecast down
+🟡 [3] Engineering: tech debt at 30% of sprint — shipping will slow by Q3
+ Action: CTO to propose debt sprint plan; COO to protect capacity
+
+WATCH
+→ People → Engineering cascade risk if attrition continues (see dimension interactions)
+```
+
+---
+
+## Graceful Degradation
+
+You don't need all metrics to run a diagnostic. The tool handles partial data:
+- Missing metric → excluded from score, flagged as "[data needed]"
+- Score still valid for available dimensions
+- Report flags which gaps to fill for next cycle
+
+## References
+- `references/health-benchmarks.md` — benchmarks by stage (Seed, A, B, C)
+- `scripts/health_scorer.py` — CLI scoring tool with traffic light output
diff --git a/skills/c-level-advisor/org-health-diagnostic/references/health-benchmarks.md b/skills/c-level-advisor/org-health-diagnostic/references/health-benchmarks.md
new file mode 100644
index 00000000..658a1d8b
--- /dev/null
+++ b/skills/c-level-advisor/org-health-diagnostic/references/health-benchmarks.md
@@ -0,0 +1,217 @@
+# Org Health Benchmarks by Stage
+
+Benchmarks for scoring each dimension at Seed, Series A, Series B, and Series C.
+
+---
+
+## Financial Health Benchmarks (CFO)
+
+| Metric | Seed | Series A | Series B | Series C |
+|--------|------|----------|----------|----------|
+| Runway (green) | >18mo | >12mo | >12mo | >18mo |
+| Runway (yellow) | 9-18mo | 6-12mo | 6-12mo | 9-18mo |
+| Runway (red) | <9mo | <6mo | <6mo | <9mo |
+| Burn multiple (green) | <3x | <2x | <1.5x | <1x |
+| Burn multiple (yellow) | 3-5x | 2-3x | 1.5-2.5x | 1-1.5x |
+| Gross margin (green) | >50% | >65% | >70% | >75% |
+| MoM growth (green) | >15% | >10% | >7% | >5% |
+| Revenue concentration | <30% | <25% | <15% | <10% |
+
+**Stage-specific notes:**
+- **Seed:** Burn multiple is looser — you're investing in PMF, not efficiency
+- **Series A:** Efficiency starts to matter; board watching burn multiple closely
+- **Series B:** Capital efficiency is table stakes; burn >2x raises serious questions
+- **Series C:** Approaching path to profitability; investors expect <1.5x
+
+---
+
+## Revenue Health Benchmarks (CRO)
+
+| Metric | Seed | Series A | Series B | Series C |
+|--------|------|----------|----------|----------|
+| NRR (green) | >100% | >110% | >115% | >120% |
+| NRR (yellow) | 90-100% | 100-110% | 105-115% | 110-120% |
+| NRR (red) | <90% | <100% | <105% | <110% |
+| Logo churn (green) | <15%/yr | <10%/yr | <7%/yr | <5%/yr |
+| Pipeline coverage | >2x | >3x | >3.5x | >4x |
+| CAC payback (green) | <24mo | <18mo | <12mo | <9mo |
+| Win rate (green) | >20% | >25% | >28% | >30% |
+| ACV trend | growing | growing | growing | growing |
+
+**What "green" NRR signals:**
+- >100%: product creates value; expansion outpaces churn
+- >110%: customers grow inside your platform; land-and-expand working
+- >120%: exceptional — net negative churn; growth from existing base alone
+- <100%: customers leave faster than others expand; structural retention problem
+
+**Warning: NRR can mask problems.** NRR of 110% with 25% logo churn means you're retaining revenue from large customers while losing small ones. Check both.
+
+---
+
+## Product Health Benchmarks (CPO)
+
+| Metric | Seed | Series A | Series B | Series C |
+|--------|------|----------|----------|----------|
+| NPS (green) | >30 | >40 | >45 | >50 |
+| NPS (yellow) | 10-30 | 20-40 | 30-45 | 40-50 |
+| NPS (red) | <10 | <20 | <30 | <40 |
+| DAU/MAU (green) | >25% | >35% | >40% | >45% |
+| Core feature adoption | >40% | >55% | >65% | >70% |
+| Time-to-value | <7 days | <5 days | <3 days | <2 days |
+| CSAT | >4.0/5 | >4.2/5 | >4.3/5 | >4.4/5 |
+
+**PMF proxy metrics:**
+- "Very disappointed" if product disappeared: >40% = strong PMF signal (Sean Ellis test)
+- 6-month retention cohort: >40% is healthy; <20% means PMF not yet achieved
+- Organic referral rate: >20% of new users from referrals = product-led growth signal
+
+**What low DAU/MAU actually means:**
+- <20% DAU/MAU for a daily-use product = product isn't integrated into workflow
+- DAU/MAU benchmarks vary by use case: email tool (daily use expected) vs. annual budget tool (weekly use is fine)
+- Always compare to category, not absolute benchmarks
+
+---
+
+## Engineering Health Benchmarks (CTO)
+
+DORA metrics are the industry standard (Google's DevOps Research and Assessment):
+
+| Metric | Elite | High | Medium | Low |
+|--------|-------|------|--------|-----|
+| Deployment frequency | Multiple/day | Weekly | Monthly | 6 months |
+| Change failure rate | <5% | 5-10% | 10-15% | >15% |
+| MTTR | <1 hour | <1 day | 1 day-1 week | >1 week |
+
+**Translation for startup stages:**
+
+| Metric | Seed | Series A | Series B | Series C |
+|--------|------|----------|----------|----------|
+| Deploy freq (green) | Weekly | Daily | Daily | Multiple/day |
+| MTTR (green) | <4h | <2h | <1h | <30min |
+| Change failure rate (green) | <15% | <10% | <7% | <5% |
+| Tech debt ratio (green) | <30% | <25% | <20% | <15% |
+| P0 incidents/month (green) | <3 | <2 | <2 | <1 |
+
+**Warning signs unique to early-stage:**
+- Bus factor = 1 on critical systems (one person knows how it works) → immediate risk
+- No on-call rotation → incidents wake the same person every time → attrition risk
+- No staging environment → production is the test environment → change failure spike risk
+- "We'll fix it after launch" for >12 months → tech debt is now a strategic problem
+
+---
+
+## People Health Benchmarks (CHRO)
+
+| Metric | Seed | Series A | Series B | Series C |
+|--------|------|----------|----------|----------|
+| Regrettable attrition (green) | <15% | <12% | <10% | <8% |
+| Regrettable attrition (red) | >25% | >18% | >15% | >12% |
+| eNPS (green) | >20 | >30 | >35 | >40 |
+| Time-to-fill (green) | <60d | <45d | <45d | <30d |
+| Internal promotion rate | >20% | >25% | >30% | >35% |
+| Manager span of control | 1:4-8 | 1:5-8 | 1:6-10 | 1:6-12 |
+| % under-performers managed out | 3-5% | 3-5% | 3-5% | 3-5% |
+
+**Regrettable vs non-regrettable attrition:**
+- Regrettable: you'd rehire them immediately; they leave for better opportunity
+- Non-regrettable: performance-based exits; mutual agreement; role evolution
+- Only regrettable attrition signals health problems
+
+**eNPS benchmarks by sector:**
+- Tech startups: >30 is good; >50 is exceptional
+- General: >0 means more promoters than detractors (minimum bar)
+- Below -10: serious cultural issue; expect more attrition
+
+**The cascade warning:** People health is a leading indicator, not lagging. By the time attrition shows up in your numbers, the next wave is already decided. Watch eNPS and engagement quarterly.
+
+---
+
+## Operational Health Benchmarks (COO)
+
+| Metric | Seed | Series A | Series B | Series C |
+|--------|------|----------|----------|----------|
+| OKR completion rate (green) | >60% | >70% | >75% | >80% |
+| Decision cycle time (green) | <3 days | <2 days | <48h | <24h |
+| Process maturity level | 1-2 | 2-3 | 3-4 | 4-5 |
+| Cross-functional delivery (on time) | >60% | >70% | >75% | >80% |
+| Leadership team tenure | N/A | >12mo avg | >18mo avg | >24mo avg |
+
+**OKR interpretation:**
+- 100% completion = OKRs were too easy (not ambitious enough)
+- 60-70% completion = appropriate stretch, realistic execution
+- <40% completion = disconnect between strategy and capacity, or OKRs set without buy-in
+- OKRs nobody can remember = OKRs that don't guide decisions = wasted exercise
+
+---
+
+## Security Health Benchmarks (CISO)
+
+| Metric | Seed | Series A | Series B | Series C |
+|--------|------|----------|----------|----------|
+| Security incidents (P1+) | 0-1/yr | 0/yr | 0/yr | 0/yr |
+| Pen test cadence | Annual | Annual | Bi-annual | Bi-annual |
+| SOC 2 Type II | Roadmap | In progress | Complete | Complete |
+| ISO 27001 | — | Roadmap | In progress | Complete |
+| Security training completion | >80% | >90% | >95% | >95% |
+| Critical CVE patching SLA | <72h | <48h | <24h | <12h |
+| MFA coverage | >80% | >95% | 100% | 100% |
+| Employee background checks | Key roles | All | All | All |
+
+**Stage-specific compliance priorities:**
+- **Seed:** Basic hygiene (MFA, encryption, access control)
+- **Series A:** SOC 2 Type I on roadmap; sales increasingly requiring it
+- **Series B:** SOC 2 Type II complete; ISO 27001 if selling to enterprise/EU
+- **Series C:** Full compliance stack; GDPR, HIPAA if applicable
+
+---
+
+## Market Health Benchmarks (CMO)
+
+| Metric | Seed | Series A | Series B | Series C |
+|--------|------|----------|----------|----------|
+| CAC trend | Acceptable | Improving | Improving | Stable/improving |
+| Organic % of pipeline | >30% | >40% | >50% | >60% |
+| Win rate (green) | >20% | >25% | >27% | >30% |
+| Competitive win rate | >40% | >45% | >50% | >55% |
+| Brand awareness in ICP | Low OK | Growing | Recognized | Leader |
+| Content-to-pipeline conversion | Tracked | >2% | >3% | >4% |
+
+---
+
+## How Dimensions Interact
+
+Understanding interdependencies helps predict cascades before they happen:
+
+```
+People Health degrades
+ ↓ (60-90 day lag)
+Engineering Health degrades (velocity drops, debt rises)
+ ↓ (30-60 day lag)
+Product Health degrades (features slip, quality drops)
+ ↓ (60-90 day lag)
+Revenue Health degrades (churn rises, deals stall)
+ ↓ (30-60 day lag)
+Financial Health degrades (cash gap, runway shortens)
+ ↓ (immediate)
+People Health degrades further (hiring freeze, morale)
+```
+
+**The prevention prescription:**
+- Fix People and Engineering problems first — they cascade to everything
+- Financial problems require immediate response (no lag)
+- Revenue problems are often symptoms of Product or People problems upstream
+- Security problems can cascade fast (breach → customer churn → financial → people)
+
+**Weighting by stage (for overall score):**
+
+| Dimension | Seed | Series A | Series B | Series C |
+|-----------|------|----------|----------|----------|
+| Financial | 30% | 25% | 20% | 20% |
+| Revenue | 20% | 25% | 25% | 25% |
+| People | 20% | 15% | 15% | 15% |
+| Product | 15% | 15% | 15% | 15% |
+| Engineering | 10% | 10% | 10% | 10% |
+| Operations | 5% | 5% | 8% | 8% |
+| Market | — | 5% | 5% | 5% |
+| Security | — | — | 2% | 2% |
diff --git a/skills/c-level-advisor/org-health-diagnostic/scripts/health_scorer.py b/skills/c-level-advisor/org-health-diagnostic/scripts/health_scorer.py
new file mode 100644
index 00000000..3b9e67d8
--- /dev/null
+++ b/skills/c-level-advisor/org-health-diagnostic/scripts/health_scorer.py
@@ -0,0 +1,585 @@
+#!/usr/bin/env python3
+"""
+Org Health Diagnostic — Multi-Dimension Health Scorer
+Scores 8 organizational dimensions on 1-10 scale with traffic lights.
+Stdlib only. Run with: python health_scorer.py
+"""
+
+import json
+import sys
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+from enum import Enum
+
+
+class Stage(Enum):
+ SEED = "seed"
+ SERIES_A = "series_a"
+ SERIES_B = "series_b"
+ SERIES_C = "series_c"
+
+
+class Trend(Enum):
+ IMPROVING = "improving"
+ STABLE = "stable"
+ DECLINING = "declining"
+ UNKNOWN = "unknown"
+
+
+class TrafficLight(Enum):
+ GREEN = "green"
+ YELLOW = "yellow"
+ RED = "red"
+
+
+# Stage weights: how much each dimension contributes to overall score
+STAGE_WEIGHTS = {
+ Stage.SEED: {
+ "financial": 0.30, "revenue": 0.20, "people": 0.20,
+ "product": 0.15, "engineering": 0.10, "operations": 0.05,
+ "market": 0.00, "security": 0.00
+ },
+ Stage.SERIES_A: {
+ "financial": 0.25, "revenue": 0.25, "people": 0.15,
+ "product": 0.15, "engineering": 0.10, "operations": 0.05,
+ "market": 0.05, "security": 0.00
+ },
+ Stage.SERIES_B: {
+ "financial": 0.20, "revenue": 0.25, "people": 0.15,
+ "product": 0.15, "engineering": 0.10, "operations": 0.08,
+ "market": 0.05, "security": 0.02
+ },
+ Stage.SERIES_C: {
+ "financial": 0.20, "revenue": 0.25, "people": 0.15,
+ "product": 0.15, "engineering": 0.10, "operations": 0.08,
+ "market": 0.05, "security": 0.02
+ },
+}
+
+
+@dataclass
+class Metric:
+ name: str
+ value: Optional[float]
+ unit: str
+ green_threshold: float # value at or above this = green
+ red_threshold: float # value at or below this = red
+ higher_is_better: bool = True
+
+ def score(self) -> Optional[float]:
+ """Score 1-10. Returns None if no value."""
+ if self.value is None:
+ return None
+ v = self.value
+ g = self.green_threshold
+ r = self.red_threshold
+
+ if self.higher_is_better:
+ if v >= g:
+ # Scale 7-10 based on how far above green
+ excess = min((v - g) / max(g * 0.3, 0.01), 1.0)
+ return 7.0 + (3.0 * excess)
+ elif v <= r:
+ # Scale 1-3 based on how far below red
+ deficit = min((r - v) / max(r * 0.5, 0.01), 1.0)
+ return max(1.0, 3.0 - (2.0 * deficit))
+ else:
+ # Between red and green → 4-6
+ if g == r:
+ return 5.0
+ position = (v - r) / (g - r)
+ return 4.0 + (2.0 * position)
+ else:
+ # Lower is better — invert
+ if v <= g:
+ excess = min((g - v) / max(g * 0.3, 0.01), 1.0)
+ return 7.0 + (3.0 * excess)
+ elif v >= r:
+ deficit = min((v - r) / max(r * 0.5, 0.01), 1.0)
+ return max(1.0, 3.0 - (2.0 * deficit))
+ else:
+ if g == r:
+ return 5.0
+ position = (r - v) / (r - g)
+ return 4.0 + (2.0 * position)
+
+ def traffic_light(self) -> Optional[TrafficLight]:
+ s = self.score()
+ if s is None:
+ return None
+ if s >= 7:
+ return TrafficLight.GREEN
+ elif s >= 4:
+ return TrafficLight.YELLOW
+ return TrafficLight.RED
+
+
+@dataclass
+class Dimension:
+ key: str
+ name: str
+ owner: str
+ emoji: str
+ metrics: List[Metric]
+ trend: Trend = Trend.UNKNOWN
+ notes: str = ""
+
+ def score(self) -> Optional[float]:
+ """Average of available metric scores."""
+ scores = [m.score() for m in self.metrics if m.score() is not None]
+ if not scores:
+ return None
+ return round(sum(scores) / len(scores), 1)
+
+ def traffic_light(self) -> TrafficLight:
+ s = self.score()
+ if s is None:
+ return TrafficLight.YELLOW # Unknown = watch
+ if s >= 7:
+ return TrafficLight.GREEN
+ elif s >= 4:
+ return TrafficLight.YELLOW
+ return TrafficLight.RED
+
+ def coverage(self) -> float:
+ """% of metrics with data."""
+ filled = sum(1 for m in self.metrics if m.value is not None)
+ return filled / len(self.metrics) if self.metrics else 0.0
+
+ def missing_metrics(self) -> List[str]:
+ return [m.name for m in self.metrics if m.value is None]
+
+
+def build_financial_dimension(stage: Stage, **kwargs) -> Dimension:
+ # Thresholds vary by stage
+ runway_green = {Stage.SEED: 18, Stage.SERIES_A: 12, Stage.SERIES_B: 12, Stage.SERIES_C: 18}
+ runway_red = {Stage.SEED: 9, Stage.SERIES_A: 6, Stage.SERIES_B: 6, Stage.SERIES_C: 9}
+ burn_green = {Stage.SEED: 3.0, Stage.SERIES_A: 2.0, Stage.SERIES_B: 1.5, Stage.SERIES_C: 1.0}
+ burn_red = {Stage.SEED: 5.0, Stage.SERIES_A: 3.0, Stage.SERIES_B: 2.5, Stage.SERIES_C: 1.5}
+
+ return Dimension(
+ key="financial",
+ name="Financial Health",
+ owner="CFO",
+ emoji="💰",
+ metrics=[
+ Metric("Runway (months)", kwargs.get("runway"),
+ "months", runway_green[stage], runway_red[stage]),
+ Metric("Burn multiple", kwargs.get("burn_multiple"),
+ "x", burn_green[stage], burn_red[stage], higher_is_better=False),
+ Metric("Gross margin (%)", kwargs.get("gross_margin"),
+ "%", 70, 55),
+ Metric("MoM growth (%)", kwargs.get("mom_growth"),
+ "%", 10, 4),
+ Metric("Revenue concentration (%)", kwargs.get("revenue_concentration"),
+ "%", 15, 30, higher_is_better=False),
+ ],
+ trend=kwargs.get("financial_trend", Trend.UNKNOWN),
+ )
+
+
+def build_revenue_dimension(stage: Stage, **kwargs) -> Dimension:
+ nrr_green = {Stage.SEED: 100, Stage.SERIES_A: 110, Stage.SERIES_B: 115, Stage.SERIES_C: 120}
+ nrr_red = {Stage.SEED: 90, Stage.SERIES_A: 100, Stage.SERIES_B: 105, Stage.SERIES_C: 110}
+
+ return Dimension(
+ key="revenue",
+ name="Revenue Health",
+ owner="CRO",
+ emoji="📈",
+ metrics=[
+ Metric("NRR (%)", kwargs.get("nrr"),
+ "%", nrr_green[stage], nrr_red[stage]),
+ Metric("Logo churn (%/yr)", kwargs.get("logo_churn"),
+ "%/yr", 5, 15, higher_is_better=False),
+ Metric("Pipeline coverage", kwargs.get("pipeline_coverage"),
+ "x", 3.0, 1.5),
+ Metric("CAC payback (months)", kwargs.get("cac_payback"),
+ "months", 12, 24, higher_is_better=False),
+ Metric("Win rate (%)", kwargs.get("win_rate"),
+ "%", 25, 15),
+ ],
+ trend=kwargs.get("revenue_trend", Trend.UNKNOWN),
+ )
+
+
+def build_product_dimension(**kwargs) -> Dimension:
+ return Dimension(
+ key="product",
+ name="Product Health",
+ owner="CPO",
+ emoji="🚀",
+ metrics=[
+ Metric("NPS", kwargs.get("nps"), "score", 40, 20),
+ Metric("DAU/MAU (%)", kwargs.get("dau_mau"), "%", 35, 15),
+ Metric("Core feature adoption (%)", kwargs.get("feature_adoption"), "%", 60, 30),
+ Metric("CSAT", kwargs.get("csat"), "/5", 4.2, 3.5),
+ Metric("Time-to-value (days)", kwargs.get("ttv_days"), "days", 3, 14, higher_is_better=False),
+ ],
+ trend=kwargs.get("product_trend", Trend.UNKNOWN),
+ )
+
+
+def build_engineering_dimension(**kwargs) -> Dimension:
+ # Deploy frequency encoded: 5=multiple/day, 4=daily, 3=weekly, 2=monthly, 1= Dimension:
+ attrition_green = {Stage.SEED: 15, Stage.SERIES_A: 12, Stage.SERIES_B: 10, Stage.SERIES_C: 8}
+ attrition_red = {Stage.SEED: 25, Stage.SERIES_A: 18, Stage.SERIES_B: 15, Stage.SERIES_C: 12}
+
+ return Dimension(
+ key="people",
+ name="People Health",
+ owner="CHRO",
+ emoji="👥",
+ metrics=[
+ Metric("Regrettable attrition (%/yr)", kwargs.get("attrition"),
+ "%/yr", attrition_green[stage], attrition_red[stage], higher_is_better=False),
+ Metric("eNPS", kwargs.get("enps"), "score", 30, 0),
+ Metric("Time-to-fill (days)", kwargs.get("ttf_days"), "days", 45, 90, higher_is_better=False),
+ Metric("Internal promotion rate (%)", kwargs.get("internal_promo_rate"), "%", 25, 10),
+ ],
+ trend=kwargs.get("people_trend", Trend.UNKNOWN),
+ )
+
+
+def build_operations_dimension(**kwargs) -> Dimension:
+ return Dimension(
+ key="operations",
+ name="Operational Health",
+ owner="COO",
+ emoji="🔄",
+ metrics=[
+ Metric("OKR completion rate (%)", kwargs.get("okr_completion"), "%", 70, 50),
+ Metric("Decision cycle time (hours)", kwargs.get("decision_hours"), "hours", 48, 168, higher_is_better=False),
+ Metric("Process maturity (1-5)", kwargs.get("process_maturity"), "level", 3, 1.5),
+ Metric("Cross-functional delivery (%)", kwargs.get("xfn_delivery_rate"), "%", 70, 50),
+ ],
+ trend=kwargs.get("ops_trend", Trend.UNKNOWN),
+ )
+
+
+def build_security_dimension(**kwargs) -> Dimension:
+ return Dimension(
+ key="security",
+ name="Security Health",
+ owner="CISO",
+ emoji="🔒",
+ metrics=[
+ Metric("Security incidents (90 days)", kwargs.get("incidents_90d"), "count", 0, 1, higher_is_better=False),
+ Metric("MFA coverage (%)", kwargs.get("mfa_coverage"), "%", 95, 80),
+ Metric("Security training completion (%)", kwargs.get("training_completion"), "%", 95, 80),
+ Metric("Critical CVE patch rate (%)", kwargs.get("cve_patch_rate"), "%", 100, 85),
+ Metric("Pen test recency (months)", kwargs.get("pentest_months"), "months", 12, 24, higher_is_better=False),
+ ],
+ trend=kwargs.get("security_trend", Trend.UNKNOWN),
+ )
+
+
+def build_market_dimension(**kwargs) -> Dimension:
+ return Dimension(
+ key="market",
+ name="Market Health",
+ owner="CMO",
+ emoji="📣",
+ metrics=[
+ Metric("Organic pipeline % ", kwargs.get("organic_pipeline_pct"), "%", 40, 20),
+ Metric("Competitive win rate (%)", kwargs.get("competitive_win_rate"), "%", 45, 30),
+ Metric("CAC trend (1=worsening, 5=improving)", kwargs.get("cac_trend_score"), "scale", 4, 2),
+ ],
+ trend=kwargs.get("market_trend", Trend.UNKNOWN),
+ )
+
+
+def calculate_overall(dimensions: List[Dimension], stage: Stage) -> Optional[float]:
+ weights = STAGE_WEIGHTS[stage]
+ total_weight = 0.0
+ weighted_sum = 0.0
+ for dim in dimensions:
+ score = dim.score()
+ w = weights.get(dim.key, 0.0)
+ if score is not None and w > 0:
+ weighted_sum += score * w
+ total_weight += w
+ if total_weight == 0:
+ return None
+ return round(weighted_sum / total_weight, 1)
+
+
+def trend_arrow(trend: Trend) -> str:
+ return {
+ Trend.IMPROVING: "↑",
+ Trend.STABLE: "→",
+ Trend.DECLINING: "↓",
+ Trend.UNKNOWN: "?",
+ }[trend]
+
+
+def traffic_light_icon(tl: TrafficLight) -> str:
+ return {"green": "🟢", "yellow": "🟡", "red": "🔴"}[tl.value]
+
+
+def print_dashboard(dimensions: List[Dimension], overall: Optional[float],
+ stage: Stage, company: str = "Company") -> None:
+ """Print the full health dashboard."""
+ print("\n" + "=" * 65)
+ print(f"ORG HEALTH DIAGNOSTIC — {company.upper()}")
+ print(f"Stage: {stage.value.replace('_', ' ').title()}")
+ if overall is not None:
+ overall_tl = TrafficLight.GREEN if overall >= 7 else (TrafficLight.YELLOW if overall >= 4 else TrafficLight.RED)
+ print(f"Overall: {traffic_light_icon(overall_tl)} {overall}/10")
+ print("=" * 65)
+
+ print("\nDIMENSION SCORES")
+ print("─" * 65)
+
+ priority_reds = []
+ priority_yellows = []
+
+ for dim in dimensions:
+ score = dim.score()
+ tl = dim.traffic_light()
+ icon = traffic_light_icon(tl)
+ trend = trend_arrow(dim.trend)
+ coverage = int(dim.coverage() * 100)
+
+ score_str = f"{score:.1f}" if score is not None else "N/A"
+ cov_str = f"({coverage}% data)" if coverage < 100 else ""
+ print(f"{dim.emoji} {dim.name:<22} {icon} {score_str:<5} {trend} {dim.owner} {cov_str}")
+
+ if tl == TrafficLight.RED and score is not None:
+ priority_reds.append(dim)
+ elif tl == TrafficLight.YELLOW and score is not None:
+ priority_yellows.append(dim)
+
+ # Top priorities
+ if priority_reds or priority_yellows:
+ print(f"\n{'─' * 65}")
+ print("PRIORITIES")
+ print("─" * 65)
+
+ idx = 1
+ for dim in priority_reds[:3]:
+ print(f"\n🔴 [{idx}] {dim.name} — Score: {dim.score():.1f}/10")
+ # Show worst metric
+ worst = min(
+ [m for m in dim.metrics if m.score() is not None],
+ key=lambda m: m.score(),
+ default=None
+ )
+ if worst:
+ print(f" Worst metric: {worst.name} = {worst.value}{worst.unit}")
+ missing = dim.missing_metrics()
+ if missing:
+ print(f" Missing data: {', '.join(missing)}")
+ idx += 1
+
+ for dim in priority_yellows[:2]:
+ print(f"\n🟡 [{idx}] {dim.name} — Score: {dim.score():.1f}/10 — {trend_arrow(dim.trend)}")
+ idx += 1
+
+ # Data gaps
+ all_missing = [(dim.name, dim.missing_metrics()) for dim in dimensions if dim.missing_metrics()]
+ if all_missing:
+ print(f"\n{'─' * 65}")
+ print("DATA GAPS (fill to improve diagnostic accuracy)")
+ for dim_name, metrics in all_missing:
+ print(f" {dim_name}: {', '.join(metrics)}")
+
+ # Cascade warnings
+ print(f"\n{'─' * 65}")
+ print("CASCADE RISK")
+ red_keys = {d.key for d in dimensions if d.traffic_light() == TrafficLight.RED}
+ if "people" in red_keys:
+ print(" ⚠️ People RED → Engineering velocity drop expected in 60-90 days")
+ if "engineering" in red_keys:
+ print(" ⚠️ Engineering RED → Product quality at risk; roadmap will slip")
+ if "product" in red_keys:
+ print(" ⚠️ Product RED → Revenue retention at risk within 2 quarters")
+ if "revenue" in red_keys:
+ print(" ⚠️ Revenue RED → Financial pressure mounting; watch runway")
+ if "financial" in red_keys:
+ print(" 🚨 Financial RED → All dimensions at risk; immediate board action needed")
+ if not red_keys:
+ print(" ✅ No active cascade risks detected")
+
+ print(f"\n{'=' * 65}\n")
+
+
+def to_json(dimensions: List[Dimension], overall: Optional[float], stage: Stage) -> Dict:
+ result = {
+ "stage": stage.value,
+ "overall_score": overall,
+ "overall_traffic_light": (
+ TrafficLight.GREEN if overall and overall >= 7
+ else TrafficLight.YELLOW if overall and overall >= 4
+ else TrafficLight.RED
+ ).value if overall else "unknown",
+ "dimensions": {}
+ }
+ for dim in dimensions:
+ result["dimensions"][dim.key] = {
+ "name": dim.name,
+ "owner": dim.owner,
+ "score": dim.score(),
+ "traffic_light": dim.traffic_light().value,
+ "trend": dim.trend.value,
+ "coverage_pct": round(dim.coverage() * 100),
+ "missing_metrics": dim.missing_metrics(),
+ "metrics": [
+ {
+ "name": m.name,
+ "value": m.value,
+ "unit": m.unit,
+ "score": m.score(),
+ "traffic_light": m.traffic_light().value if m.traffic_light() else None,
+ }
+ for m in dim.metrics
+ ]
+ }
+ return result
+
+
+def build_sample_data(stage: Stage) -> Dict:
+ """Sample Series A company data."""
+ return dict(
+ # Financial
+ runway=14, burn_multiple=1.8, gross_margin=68, mom_growth=8.5,
+ revenue_concentration=28, financial_trend=Trend.STABLE,
+ # Revenue
+ nrr=104, logo_churn=8, pipeline_coverage=1.9, cac_payback=16,
+ win_rate=22, revenue_trend=Trend.DECLINING,
+ # Product
+ nps=38, dau_mau=32, feature_adoption=52, csat=4.1,
+ ttv_days=6, product_trend=Trend.STABLE,
+ # Engineering
+ deploy_freq=3, change_failure_rate=9, mttr_hours=2.8,
+ tech_debt_pct=30, incidents_monthly=2, engineering_trend=Trend.STABLE,
+ # People
+ attrition=21, enps=12, ttf_days=58, internal_promo_rate=18,
+ people_trend=Trend.DECLINING,
+ # Operations
+ okr_completion=62, decision_hours=72, process_maturity=2.5,
+ xfn_delivery_rate=65, ops_trend=Trend.STABLE,
+ # Security
+ incidents_90d=0, mfa_coverage=88, training_completion=82,
+ cve_patch_rate=95, pentest_months=14, security_trend=Trend.IMPROVING,
+ # Market
+ organic_pipeline_pct=35, competitive_win_rate=42,
+ cac_trend_score=3, market_trend=Trend.STABLE,
+ )
+
+
+def interactive_mode(stage: Stage) -> Dict:
+ """Guided metric entry."""
+ print("\nEnter metrics (press Enter to skip):\n")
+ data = {}
+
+ def ask(prompt: str, key: str, default=None):
+ val = input(f" {prompt}: ").strip()
+ if val:
+ try:
+ data[key] = float(val)
+ except ValueError:
+ pass
+
+ print("💰 FINANCIAL")
+ ask("Runway (months)", "runway")
+ ask("Burn multiple (e.g. 1.8)", "burn_multiple")
+ ask("Gross margin (%)", "gross_margin")
+ ask("MoM growth (%)", "mom_growth")
+ ask("Top customer % of ARR", "revenue_concentration")
+
+ print("\n📈 REVENUE")
+ ask("NRR (%)", "nrr")
+ ask("Logo churn (%/yr)", "logo_churn")
+ ask("Pipeline coverage (x)", "pipeline_coverage")
+ ask("CAC payback (months)", "cac_payback")
+ ask("Win rate (%)", "win_rate")
+
+ print("\n🚀 PRODUCT")
+ ask("NPS score", "nps")
+ ask("DAU/MAU (%)", "dau_mau")
+ ask("Core feature adoption (%)", "feature_adoption")
+
+ print("\n⚙️ ENGINEERING")
+ ask("Deploy frequency (1=rare, 5=multiple/day)", "deploy_freq")
+ ask("Change failure rate (%)", "change_failure_rate")
+ ask("MTTR (hours)", "mttr_hours")
+ ask("Tech debt % of sprint", "tech_debt_pct")
+
+ print("\n👥 PEOPLE")
+ ask("Regrettable attrition (%/yr)", "attrition")
+ ask("eNPS score", "enps")
+ ask("Time-to-fill (days)", "ttf_days")
+
+ print("\n🔄 OPERATIONS")
+ ask("OKR completion rate (%)", "okr_completion")
+
+ print("\n🔒 SECURITY")
+ ask("MFA coverage (%)", "mfa_coverage")
+ ask("Security training completion (%)", "training_completion")
+
+ return data
+
+
+def main():
+ print("\n🏥 ORG HEALTH DIAGNOSTIC")
+ print("Multi-dimension organizational health scorer\n")
+
+ # Determine stage
+ stage_map = {
+ "seed": Stage.SEED, "a": Stage.SERIES_A, "series_a": Stage.SERIES_A,
+ "b": Stage.SERIES_B, "series_b": Stage.SERIES_B,
+ "c": Stage.SERIES_C, "series_c": Stage.SERIES_C,
+ }
+ stage_arg = next((a for a in sys.argv[1:] if a.lower() in stage_map), None)
+ stage = stage_map.get(stage_arg.lower(), Stage.SERIES_A) if stage_arg else Stage.SERIES_A
+
+ if "--interactive" in sys.argv or "-i" in sys.argv:
+ company = input("Company name: ").strip() or "Company"
+ stage_input = input("Stage (seed/a/b/c): ").strip().lower()
+ stage = stage_map.get(stage_input, Stage.SERIES_A)
+ data = interactive_mode(stage)
+ else:
+ print(f"Running sample Series A company data.")
+ print("(Use --interactive or -i for custom data, --stage seed/a/b/c for stage)\n")
+ company = "Sample Co"
+ data = build_sample_data(stage)
+
+ # Build dimensions
+ dimensions = [
+ build_financial_dimension(stage, **data),
+ build_revenue_dimension(stage, **data),
+ build_product_dimension(**data),
+ build_engineering_dimension(**data),
+ build_people_dimension(stage, **data),
+ build_operations_dimension(**data),
+ build_security_dimension(**data),
+ build_market_dimension(**data),
+ ]
+
+ overall = calculate_overall(dimensions, stage)
+ print_dashboard(dimensions, overall, stage, company)
+
+ if "--json" in sys.argv:
+ print(json.dumps(to_json(dimensions, overall, stage), indent=2))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/scenario-war-room/SKILL.md b/skills/c-level-advisor/scenario-war-room/SKILL.md
new file mode 100644
index 00000000..ad6c5428
--- /dev/null
+++ b/skills/c-level-advisor/scenario-war-room/SKILL.md
@@ -0,0 +1,224 @@
+---
+name: "scenario-war-room"
+description: "Cross-functional what-if modeling for cascading multi-variable scenarios. Unlike single-assumption stress testing, this models compound adversity across all business functions simultaneously. Use when facing complex risk scenarios, strategic decisions with major downside, or when the user asks 'what if X AND Y both happen?'"
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: strategic-planning
+ updated: 2026-03-05
+ python-tools: scenario_modeler.py
+ frameworks: scenario-planning
+---
+
+# Scenario War Room
+
+Model cascading what-if scenarios across all business functions. Not single-assumption stress tests — compound adversity that shows how one problem creates the next.
+
+## Keywords
+scenario planning, war room, what-if analysis, risk modeling, cascading effects, compound risk, adversity planning, contingency planning, stress test, crisis planning, multi-variable scenario, pre-mortem
+
+## Quick Start
+
+```bash
+python scripts/scenario_modeler.py # Interactive scenario builder with cascade modeling
+```
+
+Or describe the scenario:
+```
+/war-room "What if we lose our top customer AND miss the Q3 fundraise?"
+/war-room "What if 3 engineers quit AND we need to ship by Q3?"
+/war-room "What if our market shrinks 30% AND a competitor raises $50M?"
+```
+
+## What This Is Not
+
+- **Not** a single-assumption stress test (that's `/em:stress-test`)
+- **Not** financial modeling only — every function gets modeled
+- **Not** worst-case-only — models 3 severity levels
+- **Not** paralysis by analysis — outputs concrete hedges and triggers
+
+## Framework: 6-Step Cascade Model
+
+### Step 1: Define Scenario Variables (max 3)
+State each variable with:
+- **What changes** — specific, quantified if possible
+- **Probability** — your best estimate
+- **Timeline** — when it hits
+
+```
+Variable A: Top customer (28% ARR) gives 60-day termination notice
+ Probability: 15% | Timeline: Within 90 days
+
+Variable B: Series A fundraise delayed 6 months beyond target close
+ Probability: 25% | Timeline: Q3
+
+Variable C: Lead engineer resigns
+ Probability: 20% | Timeline: Unknown
+```
+
+### Step 2: Domain Impact Mapping
+
+For each variable, each relevant role models impact:
+
+| Domain | Owner | Models |
+|--------|-------|--------|
+| Cash & runway | CFO | Burn impact, runway change, bridge options |
+| Revenue | CRO | ARR gap, churn cascade risk, pipeline |
+| Product | CPO | Roadmap impact, PMF risk |
+| Engineering | CTO | Velocity impact, key person risk |
+| People | CHRO | Attrition cascade, hiring freeze implications |
+| Operations | COO | Capacity, OKR impact, process risk |
+| Security | CISO | Compliance timeline risk |
+| Market | CMO | CAC impact, competitive exposure |
+
+### Step 3: Cascade Effect Mapping
+
+This is the core. Show how Variable A triggers consequences in domains that trigger Variable B's effects:
+
+```
+TRIGGER: Customer churn ($560K ARR)
+ ↓
+CFO: Runway drops 14 → 8 months
+ ↓
+CHRO: Hiring freeze; retention risk increases (morale hit)
+ ↓
+CTO: 3 open engineering reqs frozen; roadmap slips
+ ↓
+CPO: Q4 feature launch delayed → customer retention risk
+ ↓
+CRO: NRR drops; existing accounts see reduced velocity → more churn risk
+ ↓
+CFO: [Secondary cascade — potential death spiral if not interrupted]
+```
+
+Name the cascade explicitly. Show where it can be interrupted.
+
+### Step 4: Severity Matrix
+
+Model three scenarios:
+
+| Scenario | Definition | Recovery |
+|----------|------------|---------|
+| **Base** | One variable hits; others don't | Manageable with plan |
+| **Stress** | Two variables hit simultaneously | Requires significant response |
+| **Severe** | All variables hit; full cascade | Existential; requires board intervention |
+
+For each severity level:
+- Runway impact
+- ARR impact
+- Headcount impact
+- Timeline to unacceptable state (trigger point)
+
+### Step 5: Trigger Points (Early Warning Signals)
+
+Define the measurable signal that tells you a scenario is unfolding **before** it's confirmed:
+
+```
+Trigger for Customer Churn Risk:
+ - Sponsor goes dark for >3 weeks
+ - Usage drops >25% MoM
+ - No Q1 QBR confirmed by Dec 1
+
+Trigger for Fundraise Delay:
+ - <3 term sheets after 60 days of process
+ - Lead investor requests >30-day extension on DD
+ - Competitor raises at lower valuation (market signal)
+
+Trigger for Engineering Attrition:
+ - Glassdoor activity from engineering team
+ - 2+ referral interview requests from engineers
+ - Above-market offer counter-required in last 3 months
+```
+
+### Step 6: Hedging Strategies
+
+For each scenario: actions to take **now** (before the scenario materializes) that reduce impact if it does.
+
+| Hedge | Cost | Impact | Owner | Deadline |
+|-------|------|--------|-------|---------|
+| Establish $500K credit line | $5K/year | Buys 3 months if churn hits | CFO | 60 days |
+| 12-month retention bonus for 3 key engineers | $90K | Locks team through fundraise | CHRO | 30 days |
+| Diversify to <20% revenue concentration per customer | Sales effort | Reduces single-customer risk | CRO | 2 quarters |
+| Compress fundraise timeline, start parallel process | CEO time | Closes before runways merge | CEO | Immediate |
+
+---
+
+## Output Format
+
+Every war room session produces:
+
+```
+SCENARIO: [Name]
+Variables: [A, B, C]
+Most likely path: [which combination actually plays out, with probability]
+
+SEVERITY LEVELS
+Base (A only): [runway/ARR impact] — recovery: [X actions]
+Stress (A+B): [runway/ARR impact] — recovery: [X actions]
+Severe (A+B+C): [runway/ARR impact] — existential risk: [yes/no]
+
+CASCADE MAP
+[A → domain impact → B trigger → domain impact → end state]
+
+EARLY WARNING SIGNALS
+- [Signal 1 → which scenario it indicates]
+- [Signal 2 → which scenario it indicates]
+- [Signal 3 → which scenario it indicates]
+
+HEDGES (take these actions now)
+1. [Action] — cost: $X — impact: [what it buys] — owner: [role] — deadline: [date]
+2. [Action] — cost: $X — impact: [what it buys] — owner: [role] — deadline: [date]
+3. [Action] — cost: $X — impact: [what it buys] — owner: [role] — deadline: [date]
+
+RECOMMENDED DECISION
+[One paragraph. What to do, in what order, and why.]
+```
+
+---
+
+## Rules for Good War Room Sessions
+
+**Max 3 variables per scenario.** More than 3 is noise — you can't meaningfully prepare for 5-variable collapse. Model the 3 that actually worry you.
+
+**Quantify or estimate.** "Revenue drops" is not useful. "$420K ARR at risk over 60 days" is. Use ranges if uncertain.
+
+**Don't stop at first-order effects.** The damage is always in the cascade, not the initial hit.
+
+**Model recovery, not just impact.** Every scenario should have a "what we do" path.
+
+**Separate base case from sensitivity.** Don't conflate "what probably happens" with "what could happen."
+
+**Don't over-model.** 3-4 scenarios per planning cycle is the right number. More creates analysis paralysis.
+
+---
+
+## Common Scenarios by Stage
+
+**Seed:**
+- Co-founder leaves + product misses launch
+- Funding runs out + bridge terms unfavorable
+
+**Series A:**
+- Miss ARR target + fundraise delayed
+- Key customer churns + competitor raises
+
+**Series B:**
+- Market contraction + burn multiple spikes
+- Lead investor wants pivot + team resists
+
+## Integration with C-Suite Roles
+
+| Scenario Type | Primary Roles | Cascade To |
+|--------------|---------------|------------|
+| Revenue miss | CRO, CFO | CMO (pipeline), COO (cuts), CHRO (layoffs) |
+| Key person departure | CHRO, COO | CTO (if eng), CRO (if sales) |
+| Fundraise failure | CFO, CEO | COO (runway extension), CHRO (hiring freeze) |
+| Security breach | CISO, CTO | CEO (comms), CFO (cost), CRO (customer impact) |
+| Market shift | CEO, CPO | CMO (repositioning), CRO (new segments) |
+| Competitor move | CMO, CRO | CPO (roadmap response), CEO (strategy) |
+
+## References
+- `references/scenario-planning.md` — Shell methodology, pre-mortem, Monte Carlo, cascade frameworks
+- `scripts/scenario_modeler.py` — CLI tool for structured scenario modeling
diff --git a/skills/c-level-advisor/scenario-war-room/references/scenario-planning.md b/skills/c-level-advisor/scenario-war-room/references/scenario-planning.md
new file mode 100644
index 00000000..24d4a8dd
--- /dev/null
+++ b/skills/c-level-advisor/scenario-war-room/references/scenario-planning.md
@@ -0,0 +1,212 @@
+# Scenario Planning Reference
+
+## Shell's Scenario Planning Methodology
+
+Shell invented modern scenario planning in the 1970s after the oil crisis. Core insight: **scenarios are not forecasts — they're tools for thinking.**
+
+### Shell's Principles (adapted for startups)
+1. **Scenarios are mutually exclusive, collectively exhaustive** — they cover the space of possibilities without overlapping
+2. **2x2 matrix** — pick 2 critical uncertainties (not risks — uncertainties); cross them to get 4 scenarios
+3. **Name the scenarios** — named scenarios are remembered; numbered ones aren't
+4. **Identify predetermined elements** — things that will happen regardless of scenario (regulatory changes, tech trends)
+5. **Early indicators** — each scenario has signals you can monitor today
+
+### Shell's 2x2 for Startups
+Critical uncertainties for early-stage SaaS:
+
+| | Market grows fast | Market grows slow |
+|---|---|---|
+| **We raise successfully** | "Blue Ocean" — execute hard | "Ramp Carefully" — efficiency focus |
+| **We bridge/delay raise** | "Scrappy Growth" — ramen profitability | "Survival Mode" — cut to core |
+
+Build your war room sessions around whichever quadrant is most relevant right now.
+
+---
+
+## Monte Carlo Thinking for Startups
+
+Monte Carlo = running thousands of simulations with random variables to understand probability distributions.
+
+You don't need software. Apply the mental model:
+
+### The Mental Monte Carlo Process
+1. **Identify the key variables** (3-5 max)
+2. **Assign ranges** — not point estimates
+ - CAC: $6K–$12K (uniform distribution)
+ - Close rate: 20%–40% (normal, mean 30%)
+ - Churn: 5%–20% (right-skewed — bad tail is worse)
+3. **Run mental scenarios** — pick low/mid/high for each
+4. **Identify the combinations that kill you** — which variable combinations make runway hit zero?
+5. **Focus hedging on** the 20% of combinations that account for 80% of kill scenarios
+
+### Practical Monte Carlo Heuristic
+For revenue forecasting, always state:
+- **P90** (90% confidence you'll exceed this)
+- **P50** (median case)
+- **P10** (only 10% chance you'll exceed this — your "stretch")
+
+Boards respect ranges. Point estimates are usually wrong and make you look naive.
+
+---
+
+## Pre-Mortem Technique
+
+A pre-mortem asks: *"It's 12 months from now. We failed. Why?"*
+
+It's the opposite of planning (which asks why you'll succeed). It surfaces hidden risks that optimism suppresses.
+
+### Running a Pre-Mortem
+**Setup:**
+- Time: 90 minutes
+- Participants: leadership team
+- Facilitator: neutral (COO, or external)
+- Assumption: "It's [date 12 months out]. The company failed / missed its major goal. This is real."
+
+**Phase 1 — Silence (10 minutes):**
+Each person writes their top 3 reasons the failure happened. No discussion.
+
+**Phase 2 — Round Robin (30 minutes):**
+Each person shares one reason per turn. Facilitator captures on whiteboard. No debate yet.
+
+**Phase 3 — Cluster (20 minutes):**
+Group similar causes. Identify the top 5 clusters.
+
+**Phase 4 — Probability & Impact (20 minutes):**
+For each cluster: P(likely) × impact = risk score. Rank.
+
+**Phase 5 — Mitigation (10 minutes):**
+Top 3 risks: what one action would most reduce each?
+
+### Pre-Mortem Prompt Variants
+- "It's March 2027. We ran out of money. Why?"
+- "It's Q4. We lost 3 enterprise customers in 60 days. What happened?"
+- "It's next year. Our top competitor took 40% of the market. How?"
+- "It's 18 months from now. Half the engineering team left. What triggered it?"
+
+---
+
+## Cascade Effect Mapping
+
+Cascades are where most startups get surprised. The first hit is expected — the second and third aren't.
+
+### Cascade Mapping Format
+Draw as a chain:
+
+```
+INITIAL EVENT
+ ↓ [immediate effect: domain, severity, timeline]
+SECONDARY EFFECT
+ ↓ [cascade mechanism: how A causes B]
+TERTIARY EFFECT
+ ↓ [cascade mechanism]
+END STATE [runway impact, ARR impact, team impact]
+```
+
+### Common Cascade Patterns
+
+**Revenue → Cash → People:**
+```
+Customer churns ($400K ARR)
+ ↓ CFO: runway drops 14→9 months; bridge needed
+ ↓ CHRO: hiring freeze; morale drops; attrition risk
+ ↓ CTO: roadmap slips; key engineers leave for certainty
+ ↓ CPO: product quality drops; more churn risk
+ ↓ CRO: harder to win new logos without product velocity
+END STATE: Death spiral if not interrupted at step 2
+```
+
+**Fundraise → Operations → Product:**
+```
+Fundraise delayed 6 months
+ ↓ CFO: bridge at unfavorable terms; equity dilution
+ ↓ COO: freeze all non-essential spend; process degrades
+ ↓ CPO: roadmap cut to 40% of planned scope
+ ↓ CTO: no infra investment; tech debt accelerates
+ ↓ CRO: product gaps start losing deals to feature-complete competitors
+END STATE: Weaker position at next raise; lower valuation
+```
+
+**People → Product → Revenue:**
+```
+Lead engineer + 2 seniors leave (30% of eng team)
+ ↓ CTO: velocity drops 50%; critical features slip Q3→Q4
+ ↓ CPO: Q4 launch cancelled; roadmap confidence collapses
+ ↓ CRO: 3 enterprise deals cite product timeline → delays/losses
+ ↓ CFO: $600K pipeline at risk; raises needed earlier
+END STATE: Fundraise from position of weakness; team morale spiral
+```
+
+### Identifying Cascade Break Points
+Every cascade has a point where intervention is cheapest. Find it:
+- Step 1: Very expensive to prevent (existential)
+- Step 2: Moderate cost (management action)
+- Step 3: Cheap (early signal response)
+
+Always try to interrupt at Step 2 or earlier.
+
+---
+
+## Trigger-Based Contingency Plans
+
+Triggers are measurable signals you commit to acting on **before** the scenario fully materializes.
+
+### Trigger Design Principles
+1. **Measurable** — not "things look bad" but "cash below $800K"
+2. **Leading, not lagging** — triggers should fire 60-90 days before the crisis
+3. **Pre-committed responses** — when trigger fires, the action is already decided
+4. **Owner assigned** — who watches for this trigger?
+
+### Trigger Examples
+
+**Cash / Runway:**
+```
+Trigger: Cash drops below $1M (or runway < 6 months)
+Pre-committed response:
+ - CFO: activate credit line within 48 hours
+ - CEO: begin bridge conversations with existing investors
+ - COO: implement 20% spend reduction plan (already drafted)
+Owner: CFO (weekly cash report to CEO)
+```
+
+**Customer Health:**
+```
+Trigger: Any customer >10% ARR shows 3 of: [sponsor gone dark, usage -25%,
+ no renewal discussion by 90 days before contract end, missed QBR]
+Pre-committed response:
+ - CRO: executive escalation call within 48 hours
+ - CPO: product health review scheduled
+ - CEO: direct outreach if escalation fails
+Owner: CRO (health score dashboard, weekly)
+```
+
+**Fundraise:**
+```
+Trigger: <3 term sheets after 8 weeks of active process
+Pre-committed response:
+ - CEO: expand process to 10 additional firms
+ - CFO: model bridge scenarios; draft bridge terms
+ - COO: prepare 90-day cost reduction plan
+Owner: CEO (weekly fundraise status)
+```
+
+---
+
+## How Many Scenarios to Model
+
+**Answer: 3-4 max per planning cycle.**
+
+The math: 3 scenarios × 6 domains × 3 severity levels = 54 combinations. That's already overwhelming. More scenarios don't improve decisions — they paralyze them.
+
+### The Right 3-4 Scenarios
+1. **Most likely adverse scenario** — what actually keeps you up at night
+2. **Market/macro scenario** — something outside your control
+3. **Black swan** — low probability, existential if it hits
+4. **Compound scenario** — your top 2 adverse events happening simultaneously
+
+### What Kills Scenario Planning
+- **Too many scenarios** — decision paralysis
+- **Only modeling what's comfortable** — survivorship bias
+- **No pre-committed responses** — it's just worry, not planning
+- **Not revisiting** — scenarios from 12 months ago are often irrelevant
+- **Treating scenarios as forecasts** — they're possibilities, not predictions
+- **Confusing risk with uncertainty** — risk has known probabilities; uncertainty doesn't
diff --git a/skills/c-level-advisor/scenario-war-room/scripts/scenario_modeler.py b/skills/c-level-advisor/scenario-war-room/scripts/scenario_modeler.py
new file mode 100644
index 00000000..d8a71283
--- /dev/null
+++ b/skills/c-level-advisor/scenario-war-room/scripts/scenario_modeler.py
@@ -0,0 +1,486 @@
+#!/usr/bin/env python3
+"""
+Scenario War Room — Multi-Variable Cascade Modeler
+Models cascading effects of compound adversity across business domains.
+Stdlib only. Run with: python scenario_modeler.py
+"""
+
+import json
+import sys
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+from enum import Enum
+
+
+class Severity(Enum):
+ BASE = "base" # One variable hits
+ STRESS = "stress" # Two variables hit
+ SEVERE = "severe" # All variables hit
+
+
+class Domain(Enum):
+ FINANCIAL = "Financial (CFO)"
+ REVENUE = "Revenue (CRO)"
+ PRODUCT = "Product (CPO)"
+ ENGINEERING = "Engineering (CTO)"
+ PEOPLE = "People (CHRO)"
+ OPERATIONS = "Operations (COO)"
+ SECURITY = "Security (CISO)"
+ MARKET = "Market (CMO)"
+
+
+@dataclass
+class Variable:
+ name: str
+ description: str
+ probability: float # 0.0-1.0
+ arrt_impact_pct: float # % of ARR at risk (negative = loss)
+ runway_impact_months: float # months lost from runway (negative = reduction)
+ affected_domains: List[Domain]
+ timeline_days: int # when it hits
+
+
+@dataclass
+class CascadeEffect:
+ trigger_domain: Domain
+ caused_domain: Domain
+ mechanism: str # how A causes B
+ severity_multiplier: float # compounds the base impact
+
+
+@dataclass
+class Hedge:
+ action: str
+ cost_usd: int
+ impact_description: str
+ owner: str
+ deadline_days: int
+ reduces_probability: float # how much it reduces scenario probability
+
+
+@dataclass
+class Scenario:
+ name: str
+ variables: List[Variable]
+ cascades: List[CascadeEffect]
+ hedges: List[Hedge]
+ # Company baseline
+ current_arr_usd: int = 2_000_000
+ current_runway_months: int = 14
+ monthly_burn_usd: int = 140_000
+
+
+def calculate_impact(
+ scenario: Scenario,
+ severity: Severity
+) -> Dict:
+ """Calculate combined impact for a given severity level."""
+ variables = scenario.variables
+
+ # Select variables by severity
+ if severity == Severity.BASE:
+ active_vars = variables[:1]
+ elif severity == Severity.STRESS:
+ active_vars = variables[:2]
+ else:
+ active_vars = variables
+
+ # Direct impacts
+ total_arr_loss_pct = sum(abs(v.arrt_impact_pct) for v in active_vars)
+ total_runway_reduction = sum(abs(v.runway_impact_months) for v in active_vars)
+
+ arr_at_risk = scenario.current_arr_usd * (total_arr_loss_pct / 100)
+ new_arr = scenario.current_arr_usd - arr_at_risk
+ new_runway = scenario.current_runway_months - total_runway_reduction
+
+ # Cascade multiplier (stress/severe amplify via domain cascades)
+ cascade_multiplier = 1.0
+ if len(active_vars) > 1:
+ active_domains = set(d for v in active_vars for d in v.affected_domains)
+ for cascade in scenario.cascades:
+ if (cascade.trigger_domain in active_domains and
+ cascade.caused_domain in active_domains):
+ cascade_multiplier *= cascade.severity_multiplier
+
+ # Apply cascade
+ effective_arr_loss = arr_at_risk * cascade_multiplier
+ effective_arr = scenario.current_arr_usd - effective_arr_loss
+ effective_runway = max(0, new_runway - (cascade_multiplier - 1.0) * 2)
+
+ # New burn multiple
+ new_monthly_burn = scenario.monthly_burn_usd * cascade_multiplier
+ burn_multiple = (new_monthly_burn * 12) / max(effective_arr, 1)
+
+ # Affected domains
+ affected = set(d for v in active_vars for d in v.affected_domains)
+
+ return {
+ "severity": severity.value,
+ "active_variables": [v.name for v in active_vars],
+ "arr_at_risk_usd": int(effective_arr_loss),
+ "arr_at_risk_pct": round(effective_arr_loss / scenario.current_arr_usd * 100, 1),
+ "projected_arr_usd": int(effective_arr),
+ "runway_months": round(effective_runway, 1),
+ "runway_change": round(effective_runway - scenario.current_runway_months, 1),
+ "cascade_multiplier": round(cascade_multiplier, 2),
+ "new_burn_multiple": round(burn_multiple, 1),
+ "affected_domains": [d.value for d in affected],
+ "existential_risk": effective_runway < 6.0,
+ "board_escalation_required": effective_runway < 9.0,
+ }
+
+
+def identify_triggers(variables: List[Variable]) -> List[Dict]:
+ """Generate early warning triggers for each variable."""
+ triggers = []
+ for var in variables:
+ trigger = {
+ "variable": var.name,
+ "timeline": f"Watch from day 1; expect signal ~{var.timeline_days // 2} days before impact",
+ "signals": _generate_signals(var),
+ "response_owner": _domain_to_owner(var.affected_domains[0] if var.affected_domains else Domain.FINANCIAL),
+ }
+ triggers.append(trigger)
+ return triggers
+
+
+def _generate_signals(var: Variable) -> List[str]:
+ """Generate plausible early warning signals based on variable type."""
+ signals = []
+ name_lower = var.name.lower()
+
+ if any(k in name_lower for k in ["customer", "churn", "account"]):
+ signals = [
+ "Executive sponsor unreachable for >2 weeks",
+ "Product usage drops >20% month-over-month",
+ "No QBR scheduled within 90 days of contract renewal",
+ "Support ticket volume spikes >50% without explanation",
+ ]
+ elif any(k in name_lower for k in ["fundraise", "raise", "capital", "investor"]):
+ signals = [
+ "Fewer than 3 term sheets after 60 days of active process",
+ "Lead investor requests 30+ day extension on diligence",
+ "Comparable company raises at lower valuation (market signal)",
+ "Investor meeting conversion rate below 20%",
+ ]
+ elif any(k in name_lower for k in ["engineer", "people", "team", "resign", "quit"]):
+ signals = [
+ "2+ engineers receive above-market counter-offer in 90 days",
+ "Glassdoor activity increases from engineering team",
+ "Key person requests 1:1 to 'talk about career' unexpectedly",
+ "Referral interview requests from engineers increase",
+ ]
+ elif any(k in name_lower for k in ["market", "competitor", "competition"]):
+ signals = [
+ "Competitor raises $10M+ funding round",
+ "Win/loss rate shifts >10% in 60 days",
+ "Multiple prospects cite competitor by name in objections",
+ "Competitor poaches 2+ of your customers in a quarter",
+ ]
+ else:
+ signals = [
+ f"Leading indicator for '{var.name}' deteriorates 20%+ vs baseline",
+ "Weekly metric review shows 3-week trend in wrong direction",
+ "External validation from customers or partners confirms risk",
+ ]
+
+ return signals[:3] # Top 3
+
+
+def _domain_to_owner(domain: Domain) -> str:
+ mapping = {
+ Domain.FINANCIAL: "CFO",
+ Domain.REVENUE: "CRO",
+ Domain.PRODUCT: "CPO",
+ Domain.ENGINEERING: "CTO",
+ Domain.PEOPLE: "CHRO",
+ Domain.OPERATIONS: "COO",
+ Domain.SECURITY: "CISO",
+ Domain.MARKET: "CMO",
+ }
+ return mapping.get(domain, "CEO")
+
+
+def format_currency(amount: int) -> str:
+ if amount >= 1_000_000:
+ return f"${amount / 1_000_000:.1f}M"
+ elif amount >= 1_000:
+ return f"${amount / 1_000:.0f}K"
+ return f"${amount}"
+
+
+def print_report(scenario: Scenario) -> None:
+ """Print full scenario analysis report."""
+ print("\n" + "=" * 70)
+ print(f"SCENARIO WAR ROOM: {scenario.name.upper()}")
+ print("=" * 70)
+
+ # Baseline
+ print(f"\n📊 BASELINE")
+ print(f" Current ARR: {format_currency(scenario.current_arr_usd)}")
+ print(f" Monthly Burn: {format_currency(scenario.monthly_burn_usd)}")
+ print(f" Runway: {scenario.current_runway_months} months")
+
+ # Variables
+ print(f"\n⚡ SCENARIO VARIABLES ({len(scenario.variables)})")
+ for i, var in enumerate(scenario.variables, 1):
+ prob_pct = int(var.probability * 100)
+ print(f"\n Variable {i}: {var.name}")
+ print(f" {var.description}")
+ print(f" Probability: {prob_pct}% | Timeline: {var.timeline_days} days")
+ print(f" ARR impact: -{var.arrt_impact_pct}% | "
+ f"Runway impact: -{var.runway_impact_months} months")
+ print(f" Affected: {', '.join(d.value for d in var.affected_domains)}")
+
+ # Combined probability
+ combined_prob = 1.0
+ for var in scenario.variables:
+ combined_prob *= var.probability
+ print(f"\n Combined probability (all hit): {combined_prob * 100:.1f}%")
+
+ # Severity Levels
+ print(f"\n{'=' * 70}")
+ print("SEVERITY ANALYSIS")
+ print("=" * 70)
+
+ for severity in Severity:
+ if severity == Severity.BASE and len(scenario.variables) < 1:
+ continue
+ if severity == Severity.STRESS and len(scenario.variables) < 2:
+ continue
+
+ impact = calculate_impact(scenario, severity)
+
+ icon = {"base": "🟡", "stress": "🔴", "severe": "💀"}[impact["severity"]]
+ print(f"\n{icon} {impact['severity'].upper()} SCENARIO")
+ print(f" Variables: {', '.join(impact['active_variables'])}")
+ print(f" ARR at risk: {format_currency(impact['arr_at_risk_usd'])} "
+ f"({impact['arr_at_risk_pct']}%)")
+ print(f" Projected ARR: {format_currency(impact['projected_arr_usd'])}")
+ print(f" Runway: {impact['runway_months']} months "
+ f"({impact['runway_change']:+.1f} months)")
+ print(f" Burn multiple: {impact['new_burn_multiple']}x")
+ if impact['cascade_multiplier'] > 1.0:
+ print(f" Cascade amplifier: {impact['cascade_multiplier']}x "
+ f"(domains interact)")
+ print(f" Board escalation: {'⚠️ YES' if impact['board_escalation_required'] else 'No'}")
+ print(f" Existential risk: {'🚨 YES' if impact['existential_risk'] else 'No'}")
+
+ # Cascade Map
+ if scenario.cascades:
+ print(f"\n{'=' * 70}")
+ print("CASCADE MAP")
+ print("=" * 70)
+ for i, cascade in enumerate(scenario.cascades, 1):
+ print(f"\n [{i}] {cascade.trigger_domain.value}")
+ print(f" ↓ {cascade.mechanism}")
+ print(f" → {cascade.caused_domain.value} "
+ f"(amplified {cascade.severity_multiplier}x)")
+
+ # Early Warning Triggers
+ print(f"\n{'=' * 70}")
+ print("EARLY WARNING TRIGGERS")
+ print("=" * 70)
+ triggers = identify_triggers(scenario.variables)
+ for trigger in triggers:
+ print(f"\n 📡 {trigger['variable']}")
+ print(f" Watch: {trigger['timeline']}")
+ print(f" Owner: {trigger['response_owner']}")
+ for signal in trigger['signals']:
+ print(f" • {signal}")
+
+ # Hedges
+ if scenario.hedges:
+ print(f"\n{'=' * 70}")
+ print("HEDGING STRATEGIES (act now)")
+ print("=" * 70)
+ sorted_hedges = sorted(scenario.hedges,
+ key=lambda h: h.reduces_probability, reverse=True)
+ for hedge in sorted_hedges:
+ print(f"\n ✅ {hedge.action}")
+ print(f" Cost: {format_currency(hedge.cost_usd)}/year | "
+ f"Owner: {hedge.owner} | Deadline: {hedge.deadline_days} days")
+ print(f" Impact: {hedge.impact_description}")
+ print(f" Risk reduction: {int(hedge.reduces_probability * 100)}%")
+
+ print(f"\n{'=' * 70}\n")
+
+
+def build_sample_scenario() -> Scenario:
+ """Sample: Customer churn + fundraise miss compound scenario."""
+ variables = [
+ Variable(
+ name="Top customer churn",
+ description="Largest customer (28% of ARR) gives 60-day termination notice",
+ probability=0.15,
+ arrt_impact_pct=28.0,
+ runway_impact_months=4.0,
+ affected_domains=[
+ Domain.FINANCIAL, Domain.REVENUE, Domain.OPERATIONS
+ ],
+ timeline_days=60,
+ ),
+ Variable(
+ name="Series A delayed 6 months",
+ description="Fundraise process extends beyond target close; bridge required",
+ probability=0.25,
+ arrt_impact_pct=0.0, # No ARR impact directly
+ runway_impact_months=3.0, # Bridge terms reduce effective runway
+ affected_domains=[
+ Domain.FINANCIAL, Domain.PEOPLE, Domain.OPERATIONS
+ ],
+ timeline_days=120,
+ ),
+ Variable(
+ name="Lead engineer resigns",
+ description="Engineering lead + 1 senior resign during uncertainty",
+ probability=0.20,
+ arrt_impact_pct=5.0, # Roadmap slip causes some revenue impact
+ runway_impact_months=1.0,
+ affected_domains=[
+ Domain.ENGINEERING, Domain.PRODUCT, Domain.REVENUE
+ ],
+ timeline_days=30,
+ ),
+ ]
+
+ cascades = [
+ CascadeEffect(
+ trigger_domain=Domain.REVENUE,
+ caused_domain=Domain.FINANCIAL,
+ mechanism="ARR loss increases burn multiple; runway compresses",
+ severity_multiplier=1.3,
+ ),
+ CascadeEffect(
+ trigger_domain=Domain.FINANCIAL,
+ caused_domain=Domain.PEOPLE,
+ mechanism="Hiring freeze + uncertainty triggers attrition risk",
+ severity_multiplier=1.2,
+ ),
+ CascadeEffect(
+ trigger_domain=Domain.PEOPLE,
+ caused_domain=Domain.PRODUCT,
+ mechanism="Engineering attrition slips roadmap; customer value drops",
+ severity_multiplier=1.15,
+ ),
+ ]
+
+ hedges = [
+ Hedge(
+ action="Establish $750K revolving credit line",
+ cost_usd=7_500,
+ impact_description="Buys 4+ months if churn hits before fundraise closes",
+ owner="CFO",
+ deadline_days=45,
+ reduces_probability=0.40,
+ ),
+ Hedge(
+ action="12-month retention bonuses for 3 key engineers",
+ cost_usd=90_000,
+ impact_description="Locks critical talent through fundraise uncertainty",
+ owner="CHRO",
+ deadline_days=30,
+ reduces_probability=0.60,
+ ),
+ Hedge(
+ action="Diversify revenue: reduce top customer to <20% ARR in 2 quarters",
+ cost_usd=0,
+ impact_description="Structural risk reduction; takes 6+ months to achieve",
+ owner="CRO",
+ deadline_days=14,
+ reduces_probability=0.30,
+ ),
+ Hedge(
+ action="Accelerate fundraise: start parallel process, compress timeline",
+ cost_usd=15_000,
+ impact_description="Closes before scenarios compound; reduces bridge risk",
+ owner="CEO",
+ deadline_days=7,
+ reduces_probability=0.35,
+ ),
+ ]
+
+ return Scenario(
+ name="Customer Churn + Fundraise Miss + Eng Attrition",
+ variables=variables,
+ cascades=cascades,
+ hedges=hedges,
+ current_arr_usd=2_000_000,
+ current_runway_months=14,
+ monthly_burn_usd=140_000,
+ )
+
+
+def interactive_mode() -> Scenario:
+ """Simple CLI for building a custom scenario."""
+ print("\n🔴 SCENARIO WAR ROOM — Custom Scenario Builder")
+ print("=" * 50)
+ print("Define up to 3 scenario variables.\n")
+
+ name = input("Scenario name: ").strip() or "Custom Scenario"
+
+ current_arr = int(input("Current ARR ($): ").strip() or "2000000")
+ current_runway = int(input("Current runway (months): ").strip() or "14")
+ monthly_burn = int(current_arr / current_runway) if current_runway > 0 else 140000
+
+ variables = []
+ for i in range(1, 4):
+ print(f"\nVariable {i} (press Enter to skip):")
+ var_name = input(" Name: ").strip()
+ if not var_name:
+ break
+
+ desc = input(" Description: ").strip() or var_name
+ prob = float(input(" Probability (0-100%): ").strip() or "20") / 100
+ arr_impact = float(input(" ARR impact (%): ").strip() or "10")
+ runway_impact = float(input(" Runway impact (months): ").strip() or "2")
+ timeline = int(input(" Timeline (days): ").strip() or "90")
+
+ variables.append(Variable(
+ name=var_name,
+ description=desc,
+ probability=prob,
+ arrt_impact_pct=arr_impact,
+ runway_impact_months=runway_impact,
+ affected_domains=[Domain.FINANCIAL, Domain.REVENUE],
+ timeline_days=timeline,
+ ))
+
+ if not variables:
+ print("No variables defined. Using sample scenario.")
+ return build_sample_scenario()
+
+ return Scenario(
+ name=name,
+ variables=variables,
+ cascades=[],
+ hedges=[],
+ current_arr_usd=current_arr,
+ current_runway_months=current_runway,
+ monthly_burn_usd=monthly_burn,
+ )
+
+
+def main():
+ print("\n🔴 SCENARIO WAR ROOM")
+ print("Multi-variable cascade modeler for startup adversity planning\n")
+
+ if "--interactive" in sys.argv or "-i" in sys.argv:
+ scenario = interactive_mode()
+ else:
+ print("Running sample scenario: Customer Churn + Fundraise Miss + Eng Attrition")
+ print("(Use --interactive or -i for custom scenario)\n")
+ scenario = build_sample_scenario()
+
+ print_report(scenario)
+
+ if "--json" in sys.argv:
+ results = {}
+ for severity in Severity:
+ impact = calculate_impact(scenario, severity)
+ results[severity.value] = impact
+ print(json.dumps(results, indent=2))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-level-advisor/strategic-alignment/SKILL.md b/skills/c-level-advisor/strategic-alignment/SKILL.md
new file mode 100644
index 00000000..165f6132
--- /dev/null
+++ b/skills/c-level-advisor/strategic-alignment/SKILL.md
@@ -0,0 +1,194 @@
+---
+name: "strategic-alignment"
+description: "Cascades strategy from boardroom to individual contributor. Detects and fixes misalignment between company goals and team execution. Covers strategy articulation, cascade mapping, orphan goal detection, silo identification, communication gap analysis, and realignment protocols. Use when teams are pulling in different directions, OKRs don't connect, departments optimize locally at company expense, or when user mentions alignment, strategy cascade, silo, conflicting OKRs, or strategy communication."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: strategic-alignment
+ updated: 2026-03-05
+ python-tools: alignment_checker.py
+ frameworks: alignment-playbook
+---
+
+# Strategic Alignment Engine
+
+Strategy fails at the cascade, not the boardroom. This skill detects misalignment before it becomes dysfunction and builds systems that keep strategy connected from CEO to individual contributor.
+
+## Keywords
+strategic alignment, strategy cascade, OKR alignment, orphan OKRs, conflicting goals, silos, communication gap, department alignment, alignment checker, strategy articulation, cross-functional, goal cascade, misalignment, alignment score
+
+## Quick Start
+
+```bash
+python scripts/alignment_checker.py # Check OKR alignment: orphans, conflicts, coverage gaps
+```
+
+## Core Framework
+
+The alignment problem: **The further a goal gets from the strategy that created it, the less likely it reflects the original intent.** This is the organizational telephone game. It happens at every stage. The question is how bad it is and how to fix it.
+
+### Step 1: Strategy Articulation Test
+
+Before checking cascade, check the source. Ask five people from five different teams:
+**"What is the company's most important strategic priority right now?"**
+
+**Scoring:**
+- All five give the same answer: ✅ Articulation is clear
+- 3–4 give similar answers: 🟡 Loose alignment — clarify and communicate
+- < 3 agree: 🔴 Strategy isn't clear enough to cascade. Fix this before fixing cascade.
+
+**Format test:** The strategy should be statable in one sentence. If leadership needs a paragraph, teams won't internalize it.
+- ❌ "We focus on product-led growth while maintaining enterprise relationships and expanding our international presence and investing in platform capabilities"
+- ✅ "Win the mid-market healthcare segment in DACH before Series B"
+
+### Step 2: Cascade Mapping
+
+Map the flow from company strategy → each level of the organization.
+
+```
+Company level: OKR-1, OKR-2, OKR-3
+ ↓
+Dept level: Sales OKRs, Eng OKRs, Product OKRs, CS OKRs
+ ↓
+Team level: Team A OKRs, Team B OKRs...
+ ↓
+Individual: Personal goals / rocks
+```
+
+**For each goal at every level, ask:**
+- Which company-level goal does this support?
+- If this goal is 100% achieved, how much does it move the company goal?
+- Is the connection direct or theoretical?
+
+### Step 3: Alignment Detection
+
+Three failure patterns:
+
+**Orphan goals:** Team or individual goals that don't connect to any company goal.
+- Symptom: "We've been working on this for a quarter and nobody above us seems to care"
+- Root cause: Goals set bottom-up or from last quarter's priorities without reconciling to current company OKRs
+- Fix: Connect or cut. Every goal needs a parent.
+
+**Conflicting goals:** Two teams' goals, when both succeed, create a worse outcome.
+- Classic example: Sales commits to volume contracts (revenue), CS is measured on satisfaction scores. Sales closes bad-fit customers; CS scores tank.
+- Fix: Cross-functional OKR review before quarter begins. Shared metrics where teams interact.
+
+**Coverage gaps:** Company has 3 OKRs. 5 teams support OKR-1, 2 support OKR-2, 0 support OKR-3.
+- Symptom: Company OKR-3 consistently misses; nobody owns it
+- Fix: Explicit ownership assignment. If no team owns a company OKR, it won't happen.
+
+See `scripts/alignment_checker.py` for automated detection against your JSON-formatted OKRs.
+
+### Step 4: Silo Identification
+
+Silos exist when teams optimize for local metrics at the expense of company metrics.
+
+**Silo signals:**
+- A department consistently hits their goals while the company misses
+- Teams don't know what other teams are working on
+- "That's not our problem" is a common phrase
+- Escalations only flow up; coordination never flows sideways
+- Data isn't shared between teams that depend on each other
+
+**Silo root causes:**
+1. **Incentive misalignment:** Teams rewarded for local metrics don't optimize for company metrics
+2. **No shared goals:** When teams share a goal, they coordinate. When they don't, they drift.
+3. **No shared language:** Engineering doesn't understand sales metrics; sales doesn't understand technical debt
+4. **Geography or time zones:** Silos accelerate when teams don't interact organically
+
+**Silo measurement:**
+- How often do teams request something from each other vs. proceed independently?
+- How much time does it take to resolve a cross-functional issue?
+- Can a team member describe the current priorities of an adjacent team?
+
+### Step 5: Communication Gap Analysis
+
+What the CEO says ≠ what teams hear. The gap grows with company size.
+
+**The message decay model:**
+- CEO communicates strategy at all-hands → managers filter through their lens → teams receive modified version → individuals interpret further
+
+**Gap sources:**
+- **Ambiguity:** Strategy stated at too high a level ("grow the business") lets each team fill in their own interpretation
+- **Frequency:** One all-hands per quarter isn't enough repetition to change behavior
+- **Medium mismatch:** Long written strategy doc for teams that respond to visual communication
+- **Trust deficit:** Teams don't believe the strategy is real ("we've heard this before")
+
+**Gap detection:**
+- Run the Step 1 articulation test across all levels
+- Compare what leadership thinks they communicated vs. what teams say they heard
+- Survey: "What changed about how you work since the last strategy update?"
+
+### Step 6: Realignment Protocol
+
+How to fix misalignment without calling it a "realignment" (which creates fear).
+
+**Step 6a: Don't start with what's wrong**
+Starting with "here's our misalignment" creates defensiveness. Start with "here's where we're heading and I want to make sure we're connected."
+
+**Step 6b: Re-cascade in a workshop, not a memo**
+Alignment workshops are more effective than documents. Get company-level OKR owners and department leads in a room. Map connections. Find gaps together.
+
+**Step 6c: Fix incentives before fixing goals**
+If department heads are rewarded for local metrics that conflict with company goals, no amount of goal-setting fixes the problem. The incentive structure must change first.
+
+**Step 6d: Install a quarterly alignment check**
+After fixing, prevent recurrence. See `references/alignment-playbook.md` for quarterly cadence.
+
+---
+
+## Alignment Score
+
+A quick health check. Score each area 0–10:
+
+| Area | Question | Score |
+|------|----------|-------|
+| Strategy clarity | Can 5 people from different teams state the strategy consistently? | /10 |
+| Cascade completeness | Do all team goals connect to company goals? | /10 |
+| Conflict detection | Have cross-team OKR conflicts been reviewed and resolved? | /10 |
+| Coverage | Does each company OKR have explicit team ownership? | /10 |
+| Communication | Do teams' behaviors reflect the strategy (not just their stated understanding)? | /10 |
+
+**Total: __ / 50**
+
+| Score | Status |
+|-------|--------|
+| 45–50 | Excellent. Maintain the system. |
+| 35–44 | Good. Address specific weak areas. |
+| 20–34 | Misalignment is costing you. Immediate attention required. |
+| < 20 | Strategic drift. Treat as crisis. |
+
+---
+
+## Key Questions for Alignment
+
+- "Ask your newest team member: what is the most important thing the company is trying to achieve right now?"
+- "Which company OKR does your team's top priority support? Can you trace the connection?"
+- "When Team A and Team B both hit their goals, does the company always win? Are there scenarios where they don't?"
+- "What changed in how your team works since the last strategy update?"
+- "Name a decision made last week that was influenced by the company strategy."
+
+## Red Flags
+
+- Teams consistently hit goals while company misses targets
+- Cross-functional projects take 3x longer than expected (coordination failure)
+- Strategy updated quarterly but team priorities don't change
+- "That's a leadership problem, not our problem" attitude at the team level
+- New initiatives announced without connecting them to existing OKRs
+- Department heads optimize for headcount or budget rather than company outcomes
+
+## Integration with Other C-Suite Roles
+
+| When... | Work with... | To... |
+|---------|-------------|-------|
+| New strategy is set | CEO + COO | Cascade into quarterly rocks before announcing |
+| OKR cycle starts | COO | Run cross-team conflict check before finalizing |
+| Team consistently misses goals | CHRO | Diagnose: capability gap or alignment gap? |
+| Silo identified | COO | Design shared metrics or cross-functional OKRs |
+| Post-M&A | CEO + Culture Architect | Detect strategy conflicts between merged entities |
+
+## Detailed References
+- `scripts/alignment_checker.py` — Automated OKR alignment analysis (orphans, conflicts, coverage)
+- `references/alignment-playbook.md` — Cascade techniques, quarterly alignment check, common patterns
diff --git a/skills/c-level-advisor/strategic-alignment/references/alignment-playbook.md b/skills/c-level-advisor/strategic-alignment/references/alignment-playbook.md
new file mode 100644
index 00000000..de7c392b
--- /dev/null
+++ b/skills/c-level-advisor/strategic-alignment/references/alignment-playbook.md
@@ -0,0 +1,205 @@
+# Strategic Alignment Playbook
+
+Techniques for cascading strategy, detecting drift, and maintaining alignment at scale.
+
+---
+
+## 1. Strategy Cascade Techniques
+
+### The One-Page Strategy Filter
+
+Before cascading, compress strategy to one page. If it doesn't fit on one page, it's not clear enough to cascade.
+
+**Template:**
+```
+Company Strategy — [Quarter/Year]
+─────────────────────────────────
+WHERE WE'RE GOING (6-word vision):
+─────────────────────────────────
+TOP 3 PRIORITIES THIS QUARTER:
+1. [Priority] — owned by: [name]
+2. [Priority] — owned by: [name]
+3. [Priority] — owned by: [name]
+─────────────────────────────────
+WHAT WE'RE NOT DOING:
+- [Deprioritized initiative]
+- [Deferred until next quarter]
+─────────────────────────────────
+HOW WE MEASURE SUCCESS:
+- [Key metric 1]
+- [Key metric 2]
+- [Key metric 3]
+```
+
+The "What we're NOT doing" section is as important as the priorities. Without it, every team adds their own priorities.
+
+### The Cascade Workshop
+
+**Step 1: Company OKR owners present to all department leads (60 min)**
+Walk through each company OKR. Explain the "why" behind each — the reasoning, not just the what.
+
+**Step 2: Department leads draft their OKRs in response (90 min)**
+Each department answers: "Given these company OKRs, what is our department uniquely positioned to contribute?"
+
+**Step 3: Cross-check for conflicts and gaps (60 min)**
+All departments present their draft OKRs. Flag: Which company OKR has no department support? Which two departments might conflict?
+
+**Step 4: Resolve before publishing (30 min)**
+Assign missing coverage. Negotiate shared metrics for conflict-prone areas.
+
+**Step 5: Cascade to teams and individuals**
+Each department lead runs the same workshop with their teams within 1 week.
+
+### Cascade rules
+
+1. **Bottom-up complements top-down.** Some goals should emerge from teams, not be handed down. Reserve 20–30% of each team's OKRs for team-defined goals that connect to company direction.
+
+2. **Every team goal needs a parent.** If you can't draw a line from a team goal to a company OKR, the goal is either wrong or the company OKR is incomplete.
+
+3. **Cascade the WHY, not just the WHAT.** "Achieve €800K ARR in DACH" without context produces different behaviors than "Achieve €800K ARR in DACH to demonstrate product-market fit before our Series B in Q4."
+
+---
+
+## 2. The Telephone Game Problem and How to Beat It
+
+### The problem
+
+A study by a leadership development firm found that:
+- 95% of employees can't name their company's top strategic priorities
+- Of those who can, 60% interpret them differently than leadership intended
+
+This is the telephone game at scale. It's not a communication failure — it's an organizational physics problem.
+
+### Why strategy degrades
+
+**Layer 1 → Layer 2:** Managers interpret strategy through their own context. "Focus on efficiency" becomes "cut costs" in Operations and "ship fewer features" in Engineering.
+
+**Layer 2 → Layer 3:** Teams interpret their manager's interpretation. The original strategy is now third-hand.
+
+**Written vs. oral:** Written documents persist. Oral communication changes with each telling. Most cascade happens orally.
+
+**Recency bias:** The last thing said overwrites earlier context. A strategy set in January doesn't survive a September all-hands that emphasizes something different.
+
+### How to beat it
+
+**Repetition is the solution, not the problem.** Most leaders communicate a strategy once and assume it was received. Research on organizational communication suggests 7+ exposures before a message changes behavior.
+
+**Vary the format.** Same message in writing, verbal, visual, story, and example. Different people receive different formats.
+
+**Create shared vocabulary.** If everyone calls the strategy by the same name, it creates a reference point. "We're in DACH focus mode" is more transmissible than a paragraph.
+
+**Test comprehension, not communication.** Ask random team members: "What are our top 3 priorities right now?" The answer tells you whether cascade worked, not whether you communicated.
+
+**Use stories, not slides.** "Here's a decision we made last week that's a perfect example of the strategy" is more memorable than restating the OKR.
+
+---
+
+## 3. Cross-Functional OKR Design
+
+Silos form when teams have no shared goals. The fix: design OKRs that require multiple teams to cooperate.
+
+### Shared ownership OKR
+
+**Format:**
+```
+Objective: [What we'll achieve together]
+Primary owner: [Team A]
+Contributing owner: [Team B]
+
+Key Results:
+- KR owned by Team A: [Metric]
+- KR owned by Team B: [Metric]
+- Shared KR (both teams): [Metric that requires both]
+```
+
+**Example:**
+```
+Objective: Launch the partner API and acquire first 3 integrations
+Primary owner: Engineering
+Contributing owner: Business Development
+
+KR 1 (Engineering): API v1 live with 100% documentation by Week 8
+KR 2 (BD): 3 signed partner integration agreements by EoQ
+KR 3 (Shared): First partner integration live and in production by EoQ
+```
+
+### Cross-functional conflict metric
+
+When two teams' goals are potentially in conflict, add a shared guardrail metric:
+
+**Example:**
+- Sales goal: 15 new logos
+- CS goal: Churn < 2%
+- **Shared guardrail:** New customer 90-day churn < 5% (Sales can't close unqualified customers; CS can't blame Sales for their churn)
+
+---
+
+## 4. Alignment Check Cadence
+
+### Quarterly alignment check (before OKR planning)
+
+Run this before setting next quarter's OKRs:
+
+**Week −2 (2 weeks before quarter start):**
+- All teams review current OKRs: Which are we hitting? Which are we missing?
+- Run the alignment checker: Orphans? Gaps? Conflicts?
+
+**Week −1:**
+- Cascade workshop: Company sets next quarter's OKRs
+- Cross-functional conflict review
+- Coverage gap assignment
+
+**Week 1 of new quarter:**
+- All teams have finalized OKRs with documented parent company OKRs
+- Shared OKRs documented with co-owners
+- Guardrail metrics in place for known conflict areas
+
+### Monthly alignment pulse
+
+One question added to monthly department reviews:
+**"How is our work moving the company-level OKRs? What's the connection?"**
+
+Force each team lead to articulate the link. If they struggle, the cascade has broken.
+
+### Weekly alignment signal
+
+One question added to leadership L10 meetings:
+**"Is there anything happening in our team that's at odds with the company strategy?"**
+
+This creates a standing invitation to surface misalignment before it compounds.
+
+---
+
+## 5. Common Misalignment Patterns by Company Stage
+
+### Seed stage (< 20 people)
+
+**Pattern:** Everyone knows everything, alignment is informal. You don't need OKRs — you have daily contact.
+
+**Risk:** Informal alignment breaks when you hire past 15 people and not everyone is in every conversation.
+
+**Fix:** Start documenting strategy at 10–12 people, before it's painful. Establishing the habit early is easier than retrofitting at 50.
+
+### Early growth (20–60 people)
+
+**Pattern:** Functions are forming. Sales, Product, Engineering operate somewhat independently. Communication slows.
+
+**Common misalignment:** Engineering builds features that Sales didn't ask for. Sales promises features Engineering hasn't planned.
+
+**Fix:** Introduce a shared quarterly planning session. Sales and Product review the roadmap together. Engineering and Sales share a customer pipeline update monthly.
+
+### Scaling (60–200 people)
+
+**Pattern:** Multiple layers of management. Strategy takes longer to reach ICs. Managers filter differently.
+
+**Common misalignment:** Department heads optimize their own metrics. Cross-functional projects stall because nobody owns the intersection.
+
+**Fix:** Cross-functional OKRs. Shared metrics. An explicit alignment check in the quarterly planning process (use the alignment_checker.py script).
+
+### Large (200+ people)
+
+**Pattern:** Sub-strategies form. Business units, geographies, and product lines develop their own goals that drift from company strategy over time.
+
+**Common misalignment:** Business unit A and Business unit B compete for the same customer segment. Platform team builds for internal use-cases that differ from external product direction.
+
+**Fix:** Annual strategy alignment summit across business units. Centralized OKR system with visible cross-functional connections. Dedicated alignment role (often the COO or Chief of Staff).
diff --git a/skills/c-level-advisor/strategic-alignment/scripts/alignment_checker.py b/skills/c-level-advisor/strategic-alignment/scripts/alignment_checker.py
new file mode 100644
index 00000000..c0a9ca04
--- /dev/null
+++ b/skills/c-level-advisor/strategic-alignment/scripts/alignment_checker.py
@@ -0,0 +1,455 @@
+#!/usr/bin/env python3
+"""
+Strategic Alignment Checker
+
+Detects misalignment in OKR structures:
+- Orphan OKRs: team goals with no connection to company goals
+- Conflicting OKRs: team goals that may work against each other
+- Coverage gaps: company goals with insufficient team support
+
+Input: JSON file with company and team OKRs
+Output: Alignment score, gap report, conflict map
+
+Usage:
+ python alignment_checker.py # Run with sample data
+ python alignment_checker.py --file my_okrs.json # Run with your data
+ python alignment_checker.py --sample # Print sample JSON format
+"""
+
+import json
+import sys
+import argparse
+from collections import defaultdict
+
+
+# ─────────────────────────────────────────────
+# Sample data
+# ─────────────────────────────────────────────
+
+SAMPLE_DATA = {
+ "quarter": "Q2 2026",
+ "company": {
+ "name": "Acme Corp",
+ "okrs": [
+ {
+ "id": "C1",
+ "objective": "Win mid-market DACH healthcare segment",
+ "key_results": [
+ "Reach 50 paying customers in DACH by EoQ",
+ "Achieve €800K ARR in DACH",
+ "Net Revenue Retention > 110%"
+ ]
+ },
+ {
+ "id": "C2",
+ "objective": "Ship the platform API to unlock partner integrations",
+ "key_results": [
+ "API v1 launched with 3 partner integrations",
+ "API documentation coverage: 100% of endpoints",
+ "< 200ms P95 response time under load"
+ ]
+ },
+ {
+ "id": "C3",
+ "objective": "Build a capital-efficient growth engine",
+ "key_results": [
+ "CAC payback period < 12 months",
+ "Burn multiple < 1.5x",
+ "Revenue per employee up 20% vs Q1"
+ ]
+ }
+ ]
+ },
+ "teams": [
+ {
+ "name": "Sales",
+ "okrs": [
+ {
+ "id": "S1",
+ "objective": "Hit DACH new business targets",
+ "parent_company_okr_id": "C1",
+ "key_results": [
+ "Close 15 new DACH logos",
+ "Pipeline coverage: 3x of target",
+ "Average deal size > €18K ARR"
+ ],
+ "potential_conflicts": ["C3", "CS2"]
+ },
+ {
+ "id": "S2",
+ "objective": "Expand into Austria market",
+ "parent_company_okr_id": None, # ORPHAN — no company OKR parent
+ "key_results": [
+ "5 qualified meetings with Austrian prospects",
+ "1 pilot signed in Austria"
+ ],
+ "potential_conflicts": []
+ }
+ ]
+ },
+ {
+ "name": "Engineering",
+ "okrs": [
+ {
+ "id": "E1",
+ "objective": "Deliver API v1 on schedule",
+ "parent_company_okr_id": "C2",
+ "key_results": [
+ "API v1 feature complete by Week 8",
+ "Zero critical bugs at launch",
+ "P95 latency < 200ms under 500 RPS"
+ ],
+ "potential_conflicts": []
+ },
+ {
+ "id": "E2",
+ "objective": "Reduce infrastructure cost by 30%",
+ "parent_company_okr_id": "C3",
+ "key_results": [
+ "Migrate 3 services to spot instances",
+ "Decommission legacy DB cluster",
+ "Monthly infra cost < €12K"
+ ],
+ "potential_conflicts": []
+ },
+ {
+ "id": "E3",
+ "objective": "Achieve zero-downtime deployments",
+ "parent_company_okr_id": None, # ORPHAN
+ "key_results": [
+ "Implement blue-green deployment pipeline",
+ "Deployment success rate > 99.5%"
+ ],
+ "potential_conflicts": []
+ }
+ ]
+ },
+ {
+ "name": "Customer Success",
+ "okrs": [
+ {
+ "id": "CS1",
+ "objective": "Drive retention and expansion in DACH",
+ "parent_company_okr_id": "C1",
+ "key_results": [
+ "NRR > 110% for DACH cohort",
+ "Churn < 2% gross monthly",
+ "CSAT score > 4.5/5"
+ ],
+ "potential_conflicts": []
+ },
+ {
+ "id": "CS2",
+ "objective": "Reduce support ticket volume by 40%",
+ "parent_company_okr_id": "C3",
+ "key_results": [
+ "Launch self-serve knowledge base",
+ "Ticket deflection rate > 35%",
+ "Time-to-first-response < 2 hours"
+ ],
+ "potential_conflicts": ["S1"] # Volume close pressure → more bad-fit customers → more tickets
+ }
+ ]
+ },
+ {
+ "name": "Marketing",
+ "okrs": [
+ {
+ "id": "M1",
+ "objective": "Generate DACH pipeline to support sales targets",
+ "parent_company_okr_id": "C1",
+ "key_results": [
+ "€2.4M qualified pipeline from DACH",
+ "30 qualified demo requests from target ICP",
+ "CAC from inbound < €4K"
+ ],
+ "potential_conflicts": []
+ }
+ ]
+ }
+ ],
+ "known_conflicts": [
+ {
+ "team_a": "Sales",
+ "okr_a": "S1",
+ "team_b": "Customer Success",
+ "okr_b": "CS2",
+ "description": "Sales closing volume deals to hit number may include poor-fit customers, increasing CS ticket load and reducing CSAT — directly conflicting with CS ticket reduction target."
+ }
+ ]
+}
+
+
+# ─────────────────────────────────────────────
+# Analysis functions
+# ─────────────────────────────────────────────
+
+def get_all_company_okr_ids(data):
+ return {okr["id"] for okr in data["company"]["okrs"]}
+
+
+def detect_orphans(data, company_ids):
+ """Find team OKRs with no parent company OKR."""
+ orphans = []
+ for team in data["teams"]:
+ for okr in team["okrs"]:
+ if okr.get("parent_company_okr_id") is None:
+ orphans.append({
+ "team": team["name"],
+ "okr_id": okr["id"],
+ "objective": okr["objective"]
+ })
+ elif okr["parent_company_okr_id"] not in company_ids:
+ orphans.append({
+ "team": team["name"],
+ "okr_id": okr["id"],
+ "objective": okr["objective"],
+ "note": f"References non-existent company OKR: {okr['parent_company_okr_id']}"
+ })
+ return orphans
+
+
+def detect_coverage_gaps(data, company_ids):
+ """Find company OKRs with no team support."""
+ coverage = defaultdict(list)
+ for team in data["teams"]:
+ for okr in team["okrs"]:
+ parent = okr.get("parent_company_okr_id")
+ if parent and parent in company_ids:
+ coverage[parent].append({
+ "team": team["name"],
+ "okr_id": okr["id"],
+ "objective": okr["objective"]
+ })
+
+ gaps = []
+ over_indexed = []
+ for company_okr in data["company"]["okrs"]:
+ cid = company_okr["id"]
+ supporting = coverage.get(cid, [])
+ entry = {
+ "company_okr_id": cid,
+ "objective": company_okr["objective"],
+ "supporting_team_count": len(supporting),
+ "supporting_teams": [s["team"] for s in supporting]
+ }
+ if len(supporting) == 0:
+ gaps.append(entry)
+ elif len(supporting) >= 4:
+ over_indexed.append(entry)
+
+ return gaps, over_indexed, coverage
+
+
+def detect_conflicts(data):
+ """Surface declared and potential OKR conflicts."""
+ conflicts = []
+
+ # Use declared known_conflicts
+ for conflict in data.get("known_conflicts", []):
+ conflicts.append({
+ "type": "declared",
+ "team_a": conflict["team_a"],
+ "okr_a": conflict["okr_a"],
+ "team_b": conflict["team_b"],
+ "okr_b": conflict["okr_b"],
+ "description": conflict["description"]
+ })
+
+ # Use potential_conflicts fields on OKRs for cross-reference
+ okr_index = {}
+ for team in data["teams"]:
+ for okr in team["okrs"]:
+ okr_index[okr["id"]] = {"team": team["name"], "objective": okr["objective"]}
+
+ for team in data["teams"]:
+ for okr in team["okrs"]:
+ for conflict_id in okr.get("potential_conflicts", []):
+ if conflict_id in okr_index:
+ target = okr_index[conflict_id]
+ # Avoid duplicate (A→B and B→A)
+ already_declared = any(
+ (c["okr_a"] == okr["id"] and c["okr_b"] == conflict_id) or
+ (c["okr_a"] == conflict_id and c["okr_b"] == okr["id"])
+ for c in conflicts
+ )
+ if not already_declared:
+ conflicts.append({
+ "type": "potential",
+ "team_a": team["name"],
+ "okr_a": okr["id"],
+ "team_b": target["team"],
+ "okr_b": conflict_id,
+ "description": f"Potential conflict between '{okr['objective']}' and '{target['objective']}' — review recommended"
+ })
+
+ return conflicts
+
+
+def compute_alignment_score(data, orphans, gaps, conflicts, coverage):
+ """Score overall alignment from 0–100."""
+ total_team_okrs = sum(len(t["okrs"]) for t in data["teams"])
+ total_company_okrs = len(data["company"]["okrs"])
+
+ orphan_penalty = (len(orphans) / max(total_team_okrs, 1)) * 30
+ gap_penalty = (len(gaps) / max(total_company_okrs, 1)) * 30
+ conflict_penalty = min(len(conflicts) * 10, 30)
+
+ score = max(0, 100 - orphan_penalty - gap_penalty - conflict_penalty)
+ return round(score)
+
+
+def score_label(score):
+ if score >= 85:
+ return "✅ Excellent"
+ elif score >= 70:
+ return "🟡 Moderate misalignment"
+ elif score >= 50:
+ return "🟠 Significant misalignment"
+ else:
+ return "🔴 Critical misalignment"
+
+
+# ─────────────────────────────────────────────
+# Report generation
+# ─────────────────────────────────────────────
+
+def print_report(data, orphans, gaps, over_indexed, conflicts, coverage, score):
+ sep = "─" * 60
+
+ print(f"\n{'═' * 60}")
+ print(f" STRATEGIC ALIGNMENT REPORT — {data.get('quarter', 'Unknown Quarter')}")
+ print(f" Company: {data['company']['name']}")
+ print(f"{'═' * 60}\n")
+
+ print(f" ALIGNMENT SCORE: {score}/100 {score_label(score)}\n")
+ print(sep)
+
+ # Company OKRs summary
+ print("\n📋 COMPANY OKRs\n")
+ for okr in data["company"]["okrs"]:
+ supporting = coverage.get(okr["id"], [])
+ teams_str = ", ".join(s["team"] for s in supporting) if supporting else "⚠️ NONE"
+ print(f" [{okr['id']}] {okr['objective']}")
+ print(f" Supported by: {teams_str}")
+ print()
+ print(sep)
+
+ # Orphan OKRs
+ print(f"\n🔍 ORPHAN OKRs ({len(orphans)} found)\n")
+ if orphans:
+ for o in orphans:
+ note = f" — {o.get('note', 'No parent company OKR assigned')}"
+ print(f" ⚠️ [{o['okr_id']}] {o['team']}: {o['objective']}")
+ print(f" Issue: {note}")
+ print()
+ print(" → Action: Connect each orphan to a company OKR, or deprioritize it.")
+ else:
+ print(" ✅ None found. All team OKRs connect to company OKRs.")
+ print()
+ print(sep)
+
+ # Coverage gaps
+ print(f"\n🕳️ COVERAGE GAPS ({len(gaps)} company OKRs with zero team support)\n")
+ if gaps:
+ for g in gaps:
+ print(f" 🔴 [{g['company_okr_id']}] {g['objective']}")
+ print(f" No team is working on this. It will not be achieved.")
+ print()
+ print(" → Action: Assign at least one team owner to each unowned company OKR.")
+ else:
+ print(" ✅ All company OKRs have at least one team supporting them.")
+ print()
+
+ if over_indexed:
+ print(f" 📊 OVER-INDEXED OKRs ({len(over_indexed)} company OKRs with 4+ teams)\n")
+ for o in over_indexed:
+ print(f" [{o['company_okr_id']}] {o['objective']}")
+ print(f" {o['supporting_team_count']} teams: {', '.join(o['supporting_teams'])}")
+ print()
+ print(" → Note: High coverage isn't necessarily bad, but check if under-covered OKRs are being neglected.")
+ print(sep)
+
+ # Conflicts
+ print(f"\n⚡ CONFLICTING OKRs ({len(conflicts)} found)\n")
+ if conflicts:
+ for i, c in enumerate(conflicts, 1):
+ label = "🔴 Declared" if c["type"] == "declared" else "🟡 Potential"
+ print(f" {label} Conflict #{i}")
+ print(f" {c['team_a']} [{c['okr_a']}] ↔ {c['team_b']} [{c['okr_b']}]")
+ print(f" {c['description']}")
+ print()
+ print(" → Action: For each conflict, design a shared metric or shared constraint that prevents local optimization at company expense.")
+ else:
+ print(" ✅ No declared or potential conflicts detected.")
+ print()
+ print(sep)
+
+ # Summary
+ print("\n📊 SUMMARY\n")
+ total_team_okrs = sum(len(t["okrs"]) for t in data["teams"])
+ total_company_okrs = len(data["company"]["okrs"])
+ print(f" Company OKRs: {total_company_okrs}")
+ print(f" Team OKRs: {total_team_okrs}")
+ print(f" Orphan OKRs: {len(orphans)}")
+ print(f" Coverage gaps: {len(gaps)} of {total_company_okrs} company OKRs have no team support")
+ print(f" Conflicts: {len(conflicts)}")
+ print(f" Alignment score: {score}/100 {score_label(score)}")
+ print()
+
+ if score < 70:
+ print(" ⚠️ RECOMMENDED ACTIONS:")
+ if orphans:
+ print(f" 1. Resolve {len(orphans)} orphan OKR(s) — connect to company goals or cut")
+ if gaps:
+ print(f" 2. Assign team owners to {len(gaps)} uncovered company OKR(s)")
+ if conflicts:
+ print(f" 3. Address {len(conflicts)} conflict(s) with shared metrics or constraints")
+ print(" 4. Run a cross-functional OKR review before next quarter begins")
+ print()
+ print(f"{'═' * 60}\n")
+
+
+# ─────────────────────────────────────────────
+# Main
+# ─────────────────────────────────────────────
+
+def main():
+ parser = argparse.ArgumentParser(description="Strategic OKR Alignment Checker")
+ parser.add_argument("--file", help="Path to JSON file with OKR data")
+ parser.add_argument("--sample", action="store_true", help="Print sample JSON format and exit")
+ args = parser.parse_args()
+
+ if args.sample:
+ print(json.dumps(SAMPLE_DATA, indent=2))
+ return
+
+ if args.file:
+ try:
+ with open(args.file, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File '{args.file}' not found.")
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in '{args.file}': {e}")
+ sys.exit(1)
+ else:
+ print("No file provided. Running with sample data.\n")
+ print("To use your own data: python alignment_checker.py --file your_okrs.json")
+ print("To see the expected JSON format: python alignment_checker.py --sample\n")
+ data = SAMPLE_DATA
+
+ # Run analysis
+ company_ids = get_all_company_okr_ids(data)
+ orphans = detect_orphans(data, company_ids)
+ gaps, over_indexed, coverage = detect_coverage_gaps(data, company_ids)
+ conflicts = detect_conflicts(data)
+ score = compute_alignment_score(data, orphans, gaps, conflicts, coverage)
+
+ # Print report
+ print_report(data, orphans, gaps, over_indexed, conflicts, coverage, score)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/c-suite-agent-protocol/SKILL.md b/skills/c-suite-agent-protocol/SKILL.md
new file mode 100644
index 00000000..a254aaac
--- /dev/null
+++ b/skills/c-suite-agent-protocol/SKILL.md
@@ -0,0 +1,418 @@
+---
+name: agent-protocol
+description: "Inter-agent communication protocol for C-suite agent teams. Defines invocation syntax, loop prevention, isolation rules, and response formats. Use when C-suite agents need to query each other, coordinate cross-functional analysis, or run board meetings with multiple agent roles."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: agent-orchestration
+ updated: 2026-03-05
+ frameworks: invocation-patterns
+---
+
+# Inter-Agent Protocol
+
+How C-suite agents talk to each other. Rules that prevent chaos, loops, and circular reasoning.
+
+## Keywords
+agent protocol, inter-agent communication, agent invocation, agent orchestration, multi-agent, c-suite coordination, agent chain, loop prevention, agent isolation, board meeting protocol
+
+## Invocation Syntax
+
+Any agent can query another using:
+
+```
+[INVOKE:role|question]
+```
+
+**Examples:**
+```
+[INVOKE:cfo|What's the burn rate impact of hiring 5 engineers in Q3?]
+[INVOKE:cto|Can we realistically ship this feature by end of quarter?]
+[INVOKE:chro|What's our typical time-to-hire for senior engineers?]
+[INVOKE:cro|What does our pipeline look like for the next 90 days?]
+```
+
+**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso`
+
+## Response Format
+
+Invoked agents respond using this structure:
+
+```
+[RESPONSE:role]
+Key finding: [one line — the actual answer]
+Supporting data:
+ - [data point 1]
+ - [data point 2]
+ - [data point 3 — optional]
+Confidence: [high | medium | low]
+Caveat: [one line — what could make this wrong]
+[/RESPONSE]
+```
+
+**Example:**
+```
+[RESPONSE:cfo]
+Key finding: Hiring 5 engineers in Q3 extends runway from 14 to 9 months at current burn.
+Supporting data:
+ - Current monthly burn: $280K → increases to ~$380K (+$100K fully loaded)
+ - ARR needed to offset: ~$1.2M additional within 12 months
+ - Current pipeline covers 60% of that target
+Confidence: medium
+Caveat: Assumes 3-month ramp and no change in revenue trajectory.
+[/RESPONSE]
+```
+
+## Loop Prevention (Hard Rules)
+
+These rules are enforced unconditionally. No exceptions.
+
+### Rule 1: No Self-Invocation
+An agent cannot invoke itself.
+```
+❌ CFO → [INVOKE:cfo|...] — BLOCKED
+```
+
+### Rule 2: Maximum Depth = 2
+Chains can go A→B→C. The third hop is blocked.
+```
+✅ CRO → CFO → COO (depth 2)
+❌ CRO → CFO → COO → CHRO (depth 3 — BLOCKED)
+```
+
+### Rule 3: No Circular Calls
+If agent A called agent B, agent B cannot call agent A in the same chain.
+```
+✅ CRO → CFO → CMO
+❌ CRO → CFO → CRO (circular — BLOCKED)
+```
+
+### Rule 4: Chain Tracking
+Each invocation carries its call chain. Format:
+```
+[CHAIN: cro → cfo → coo]
+```
+Agents check this chain before responding with another invocation.
+
+**When blocked:** Return this instead of invoking:
+```
+[BLOCKED: cannot invoke cfo — circular call detected in chain cro→cfo]
+State assumption used instead: [explicit assumption the agent is making]
+```
+
+## Isolation Rules
+
+### Board Meeting Phase 2 (Independent Analysis)
+**NO invocations allowed.** Each role forms independent views before cross-pollination.
+- Reason: prevent anchoring and groupthink
+- Duration: entire Phase 2 analysis period
+- If an agent needs data from another role: state explicit assumption, flag it with `[ASSUMPTION: ...]`
+
+### Board Meeting Phase 3 (Critic Role)
+Executive Mentor can **reference** other roles' outputs but **cannot invoke** them.
+- Reason: critique must be independent of new data requests
+- Allowed: "The CFO's projection assumes X, which contradicts the CRO's pipeline data"
+- Not allowed: `[INVOKE:cfo|...]` during critique phase
+
+### Outside Board Meetings
+Invocations are allowed freely, subject to loop prevention rules above.
+
+## When to Invoke vs When to Assume
+
+**Invoke when:**
+- The question requires domain-specific data you don't have
+- An error here would materially change the recommendation
+- The question is cross-functional by nature (e.g., hiring impact on both budget and capacity)
+
+**Assume when:**
+- The data is directionally clear and precision isn't critical
+- You're in Phase 2 isolation (always assume, never invoke)
+- The chain is already at depth 2
+- The question is minor compared to your main analysis
+
+**When assuming, always state it:**
+```
+[ASSUMPTION: runway ~12 months based on typical Series A burn profile — not verified with CFO]
+```
+
+## Conflict Resolution
+
+When two invoked agents give conflicting answers:
+
+1. **Flag the conflict explicitly:**
+ ```
+ [CONFLICT: CFO projects 14-month runway; CRO expects pipeline to close 80% → implies 18+ months]
+ ```
+2. **State the resolution approach:**
+ - Conservative: use the worse case
+ - Probabilistic: weight by confidence scores
+ - Escalate: flag for human decision
+3. **Never silently pick one** — surface the conflict to the user.
+
+## Broadcast Pattern (Crisis / CEO)
+
+CEO can broadcast to all roles simultaneously:
+```
+[BROADCAST:all|What's the impact if we miss the fundraise?]
+```
+
+Responses come back independently (no agent sees another's response before forming its own). Aggregate after all respond.
+
+## Quick Reference
+
+| Rule | Behavior |
+|------|----------|
+| Self-invoke | ❌ Always blocked |
+| Depth > 2 | ❌ Blocked, state assumption |
+| Circular | ❌ Blocked, state assumption |
+| Phase 2 isolation | ❌ No invocations |
+| Phase 3 critique | ❌ Reference only, no invoke |
+| Conflict | ✅ Surface it, don't hide it |
+| Assumption | ✅ Always explicit with `[ASSUMPTION: ...]` |
+
+## Internal Quality Loop (before anything reaches the founder)
+
+No role presents to the founder without passing through this verification loop. The founder sees polished, verified output — not first drafts.
+
+### Step 1: Self-Verification (every role, every time)
+
+Before presenting, every role runs this internal checklist:
+
+```
+SELF-VERIFY CHECKLIST:
+□ Source Attribution — Where did each data point come from?
+ ✅ "ARR is $2.1M (from CRO pipeline report, Q4 actuals)"
+ ❌ "ARR is around $2M" (no source, vague)
+
+□ Assumption Audit — What am I assuming vs what I verified?
+ Tag every assumption: [VERIFIED: checked against data] or [ASSUMED: not verified]
+ If >50% of findings are ASSUMED → flag low confidence
+
+□ Confidence Score — How sure am I on each finding?
+ 🟢 High: verified data, established pattern, multiple sources
+ 🟡 Medium: single source, reasonable inference, some uncertainty
+ 🔴 Low: assumption-based, limited data, first-time analysis
+
+□ Contradiction Check — Does this conflict with known context?
+ Check against company-context.md and recent decisions in decision-log
+ If it contradicts a past decision → flag explicitly
+
+□ "So What?" Test — Does every finding have a business consequence?
+ If you can't answer "so what?" in one sentence → cut it
+```
+
+### Step 2: Peer Verification (cross-functional validation)
+
+When a recommendation impacts another role's domain, that role validates BEFORE presenting.
+
+| If your recommendation involves... | Validate with... | They check... |
+|-------------------------------------|-------------------|---------------|
+| Financial numbers or budget | CFO | Math, runway impact, budget reality |
+| Revenue projections | CRO | Pipeline backing, historical accuracy |
+| Headcount or hiring | CHRO | Market reality, comp feasibility, timeline |
+| Technical feasibility or timeline | CTO | Engineering capacity, technical debt load |
+| Operational process changes | COO | Capacity, dependencies, scaling impact |
+| Customer-facing changes | CRO + CPO | Churn risk, product roadmap conflict |
+| Security or compliance claims | CISO | Actual posture, regulation requirements |
+| Market or positioning claims | CMO | Data backing, competitive reality |
+
+**Peer validation format:**
+```
+[PEER-VERIFY:cfo]
+Validated: ✅ Burn rate calculation correct
+Adjusted: ⚠️ Hiring timeline should be Q3 not Q2 (budget constraint)
+Flagged: 🔴 Missing equity cost in total comp projection
+[/PEER-VERIFY]
+```
+
+**Skip peer verification when:**
+- Single-domain question with no cross-functional impact
+- Time-sensitive proactive alert (send alert, verify after)
+- Founder explicitly asked for a quick take
+
+### Step 3: Critic Pre-Screen (high-stakes decisions only)
+
+For decisions that are **irreversible, high-cost, or bet-the-company**, the Executive Mentor pre-screens before the founder sees it.
+
+**Triggers for pre-screen:**
+- Involves spending > 20% of remaining runway
+- Affects >30% of the team (layoffs, reorg)
+- Changes company strategy or direction
+- Involves external commitments (fundraising terms, partnerships, M&A)
+- Any recommendation where all roles agree (suspicious consensus)
+
+**Pre-screen output:**
+```
+[CRITIC-SCREEN]
+Weakest point: [The single biggest vulnerability in this recommendation]
+Missing perspective: [What nobody considered]
+If wrong, the cost is: [Quantified downside]
+Proceed: ✅ With noted risks | ⚠️ After addressing [specific gap] | 🔴 Rethink
+[/CRITIC-SCREEN]
+```
+
+### Step 4: Course Correction (after founder feedback)
+
+The loop doesn't end at delivery. After the founder responds:
+
+```
+FOUNDER FEEDBACK LOOP:
+1. Founder approves → log decision (Layer 2), assign actions
+2. Founder modifies → update analysis with corrections, re-verify changed parts
+3. Founder rejects → log rejection with DO_NOT_RESURFACE, understand WHY
+4. Founder asks follow-up → deepen analysis on specific point, re-verify
+
+POST-DECISION REVIEW (30/60/90 days):
+- Was the recommendation correct?
+- What did we miss?
+- Update company-context.md with what we learned
+- If wrong → document the lesson, adjust future analysis
+```
+
+### Verification Level by Stakes
+
+| Stakes | Self-Verify | Peer-Verify | Critic Pre-Screen |
+|--------|-------------|-------------|-------------------|
+| Low (informational) | ✅ Required | ❌ Skip | ❌ Skip |
+| Medium (operational) | ✅ Required | ✅ Required | ❌ Skip |
+| High (strategic) | ✅ Required | ✅ Required | ✅ Required |
+| Critical (irreversible) | ✅ Required | ✅ Required | ✅ Required + board meeting |
+
+### What Changes in the Output Format
+
+The verified output adds confidence and source information:
+
+```
+BOTTOM LINE
+[Answer] — Confidence: 🟢 High
+
+WHAT
+• [Finding 1] [VERIFIED: Q4 actuals] 🟢
+• [Finding 2] [VERIFIED: CRO pipeline data] 🟢
+• [Finding 3] [ASSUMED: based on industry benchmarks] 🟡
+
+PEER-VERIFIED BY: CFO (math ✅), CTO (timeline ⚠️ adjusted to Q3)
+```
+
+---
+
+## User Communication Standard
+
+All C-suite output to the founder follows ONE format. No exceptions. The founder is the decision-maker — give them results, not process.
+
+### Standard Output (single-role response)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 [ROLE] — [Topic]
+
+BOTTOM LINE
+[One sentence. The answer. No preamble.]
+
+WHAT
+• [Finding 1 — most critical]
+• [Finding 2]
+• [Finding 3]
+(Max 5 bullets. If more needed → reference doc.)
+
+WHY THIS MATTERS
+[1-2 sentences. Business impact. Not theory — consequence.]
+
+HOW TO ACT
+1. [Action] → [Owner] → [Deadline]
+2. [Action] → [Owner] → [Deadline]
+3. [Action] → [Owner] → [Deadline]
+
+⚠️ RISKS (if any)
+• [Risk + what triggers it]
+
+🔑 YOUR DECISION (if needed)
+Option A: [Description] — [Trade-off]
+Option B: [Description] — [Trade-off]
+Recommendation: [Which and why, in one line]
+
+📎 DETAIL: [reference doc or script output for deep-dive]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Proactive Alert (unsolicited — triggered by context)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🚩 [ROLE] — Proactive Alert
+
+WHAT I NOTICED
+[What triggered this — specific, not vague]
+
+WHY IT MATTERS
+[Business consequence if ignored — in dollars, time, or risk]
+
+RECOMMENDED ACTION
+[Exactly what to do, who does it, by when]
+
+URGENCY: 🔴 Act today | 🟡 This week | ⚪ Next review
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Board Meeting Output (multi-role synthesis)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 BOARD MEETING — [Date] — [Agenda Topic]
+
+DECISION REQUIRED
+[Frame the decision in one sentence]
+
+PERSPECTIVES
+ CEO: [one-line position]
+ CFO: [one-line position]
+ CRO: [one-line position]
+ [... only roles that contributed]
+
+WHERE THEY AGREE
+• [Consensus point 1]
+• [Consensus point 2]
+
+WHERE THEY DISAGREE
+• [Conflict] — CEO says X, CFO says Y
+• [Conflict] — CRO says X, CPO says Y
+
+CRITIC'S VIEW (Executive Mentor)
+[The uncomfortable truth nobody else said]
+
+RECOMMENDED DECISION
+[Clear recommendation with rationale]
+
+ACTION ITEMS
+1. [Action] → [Owner] → [Deadline]
+2. [Action] → [Owner] → [Deadline]
+3. [Action] → [Owner] → [Deadline]
+
+🔑 YOUR CALL
+[Options if you disagree with the recommendation]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Communication Rules (non-negotiable)
+
+1. **Bottom line first.** Always. The founder's time is the scarcest resource.
+2. **Results and decisions only.** No process narration ("First I analyzed..."). No thinking out loud.
+3. **What + Why + How.** Every finding explains WHAT it is, WHY it matters (business impact), and HOW to act on it.
+4. **Max 5 bullets per section.** Longer = reference doc.
+5. **Actions have owners and deadlines.** "We should consider" is banned. Who does what by when.
+6. **Decisions framed as options.** Not "what do you think?" — "Option A or B, here's the trade-off, here's my recommendation."
+7. **The founder decides.** Roles recommend. The founder approves, modifies, or rejects. Every output respects this hierarchy.
+8. **Risks are concrete.** Not "there might be risks" — "if X happens, Y breaks, costing $Z."
+9. **No jargon without explanation.** If you use a term, explain it on first use.
+10. **Silence is an option.** If there's nothing to report, don't fabricate updates.
+
+## Reference
+- `references/invocation-patterns.md` — common cross-functional patterns with examples
diff --git a/skills/c-suite-agent-protocol/_meta.json b/skills/c-suite-agent-protocol/_meta.json
new file mode 100644
index 00000000..0b0c3073
--- /dev/null
+++ b/skills/c-suite-agent-protocol/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "c-suite-agent-protocol",
+ "displayName": "C-Suite Agent Protocol",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1772750836623,
+ "commit": "https://github.com/openclaw/skills/commit/1ba4421b395d2307e4e59ac7ee0b2981e8a5623e"
+ },
+ "history": []
+}
diff --git a/skills/c-suite-agent-protocol/references/invocation-patterns.md b/skills/c-suite-agent-protocol/references/invocation-patterns.md
new file mode 100644
index 00000000..be413bf1
--- /dev/null
+++ b/skills/c-suite-agent-protocol/references/invocation-patterns.md
@@ -0,0 +1,247 @@
+# Invocation Patterns — Inter-Agent Protocol
+
+Common cross-functional patterns, with examples and guidance on when to invoke vs assume.
+
+---
+
+## Pattern 1: Revenue Planning Chain
+**CRO → CFO → CMO**
+
+Used when: setting revenue targets, allocating growth budget, modeling pipeline scenarios.
+
+```
+CRO initiates:
+"Planning Q3 revenue targets. Need financial constraints and marketing input."
+
+CRO → [INVOKE:cfo|What's our Q3 revenue target given current runway and burn?]
+
+CFO responds:
+[RESPONSE:cfo]
+Key finding: To maintain 12-month runway without new raise, Q3 ARR target ≥ $2.4M (+20% QoQ)
+Supporting data:
+ - Current ARR: $2.0M, burn: $180K/month, runway: 14 months
+ - 20% QoQ growth maintains runway; <15% triggers bridge discussion
+ - Board expectation communicated as 25% QoQ
+Confidence: high
+Caveat: Assumes no new hires or major infrastructure spend in Q3.
+[/RESPONSE]
+
+CRO → [INVOKE:cmo|Given a $2.4M Q3 ARR target, what pipeline coverage and CAC should we plan for?]
+[CHAIN: cro → cfo → cmo]
+
+CMO responds:
+[RESPONSE:cmo]
+Key finding: Need 3x pipeline ($7.2M) and CAC ≤ $8,400 to hit $2.4M ARR target.
+Supporting data:
+ - Historical close rate: 33% → 3x coverage required
+ - Current CAC: $9,100 → 8% efficiency improvement needed
+ - Recommended channel mix: 60% outbound, 30% inbound, 10% partner
+Confidence: medium
+Caveat: Close rate assumes no sales team changes; any rep turnover drops it to 25%.
+[/RESPONSE]
+```
+
+**What CRO does with this:** Synthesizes CFO constraint (target) + CMO playbook (how to hit it) into a revenue plan. Does not invoke further (depth limit reached).
+
+---
+
+## Pattern 2: Hiring Decision Chain
+**CHRO → CFO → COO**
+
+Used when: headcount planning, role approval, capacity vs budget tradeoffs.
+
+```
+CHRO initiates:
+"Engineering wants to hire 3 senior engineers. Need budget clearance and capacity validation."
+
+CHRO → [INVOKE:cfo|Can we afford 3 senior engineers in H2? Fully loaded ~$180K each.]
+
+[RESPONSE:cfo]
+Key finding: Budget supports 2 hires now; 3rd is contingent on Q2 ARR closing above $2.1M.
+Supporting data:
+ - Current H2 headcount budget: $340K remaining
+ - 2 hires = $270K fully loaded → $70K buffer
+ - 3 hires = $405K → $65K over; triggers board approval
+Confidence: high
+Caveat: Based on current runway projection — fundraise close changes this completely.
+[/RESPONSE]
+
+CHRO → [INVOKE:coo|Do operations support onboarding 2-3 engineers in H2? Any capacity constraints?]
+[CHAIN: chro → cfo → coo]
+
+[RESPONSE:coo]
+Key finding: Can absorb 2 comfortably; 3rd requires dedicated onboarding lead or delays velocity 6 weeks.
+Supporting data:
+ - Current eng team: 8 → adding 2 is 25% growth (manageable)
+ - Onboarding bottleneck: 1 senior eng mentor per 1-2 new hires, currently at capacity
+ - Dev environment setup: 3-week lead time per hire
+Confidence: medium
+Caveat: Assumes no concurrent product launches requiring full team focus.
+[/RESPONSE]
+
+CHRO synthesis: Recommends 2 hires now, pipeline 3rd for Q3 contingent on ARR milestone.
+```
+
+---
+
+## Pattern 3: Product Launch Chain
+**CPO → CTO → CMO**
+
+Used when: planning feature launches, assessing readiness, aligning go-to-market.
+
+```
+CPO initiates:
+"Planning Q3 launch of [Feature X]. Need technical readiness and GTM input."
+
+CPO → [INVOKE:cto|Is Feature X technically ready for Q3 launch? Key risks?]
+
+[RESPONSE:cto]
+Key finding: 70% complete; Q3 launch is achievable with scope cut — 2 items must move to Q4.
+Supporting data:
+ - Core feature: complete; performance optimization: 3 weeks remaining
+ - Infrastructure scaling: needs load testing at 10x current volume
+ - Scope cuts needed: advanced analytics dashboard, third-party integrations
+Confidence: medium
+Caveat: Assumes no critical bugs found in load testing; historical rate suggests 1-2 found.
+[/RESPONSE]
+
+CPO → [INVOKE:cmo|Given Q3 launch of Feature X (core only, no analytics/integrations), what's the GTM plan?]
+[CHAIN: cpo → cto → cmo]
+
+[RESPONSE:cmo]
+Key finding: Core-only launch works for existing customers; new logo acquisition needs integrations — recommend phased announcement.
+Supporting data:
+ - Phase 1: Early access for top 20 accounts → testimonials and case studies
+ - Phase 2: Full launch with integration partners in Q4
+ - CAC impact: core-only launch reduces new logo conversion rate 15%
+Confidence: medium
+Caveat: Competitor launched similar feature last month — window for differentiation is narrow.
+[/RESPONSE]
+```
+
+---
+
+## Pattern 4: Crisis Broadcast
+**CEO → All Roles**
+
+Used when: major adverse event, fundraise miss, key customer loss, market disruption.
+
+```
+CEO broadcasts:
+[BROADCAST:all|Scenario: largest customer (28% of ARR) gives 60-day termination notice.
+Each role: what's the immediate impact on your domain and your top recommended action?]
+
+Roles respond INDEPENDENTLY (no agent sees others' responses first):
+
+[RESPONSE:cfo]
+Key finding: 28% ARR loss drops runway from 14 to 8 months at current burn.
+Supporting data:
+ - Lost ARR: ~$560K → burn multiple increases from 1.8x to 3.2x
+ - Bridge options: $500K credit line (pre-approved), defer 2 planned hires
+ - Fundraise timeline must compress: target term sheet within 60 days
+Confidence: high
+Caveat: Assumes no secondary customer churn triggered by news.
+[/RESPONSE]
+
+[RESPONSE:cro]
+Key finding: Pipeline must replace $560K ARR within 6 months to avoid emergency measures.
+Supporting data:
+ - Current qualified pipeline: $1.8M → need 31% close rate (currently 28%)
+ - 3 deals in late stage can cover 70% of gap if closed this quarter
+ - Churn risk: 2 other accounts had similar usage patterns — immediate EBR required
+Confidence: medium
+Caveat: Close rate may drop if word spreads; manage communication carefully.
+[/RESPONSE]
+
+[RESPONSE:chro]
+Key finding: Hiring freeze recommended immediately; retain all current staff.
+Supporting data:
+ - 4 open reqs should pause pending CFO guidance
+ - At-risk of counter-poaching: 2 senior engineers, 1 product lead
+ - Retention bonuses for key staff: ~$80K to secure 12-month commitments
+Confidence: high
+Caveat: Morale impact of freeze can accelerate attrition if not communicated well.
+[/RESPONSE]
+
+[RESPONSE:cpo]
+Key finding: Accelerate features that differentiate with remaining accounts; reduce scope to core.
+Supporting data:
+ - Lost customer's feature requests: deprioritize (no longer strategic)
+ - Features most valued by remaining top 5 accounts: [list from account data]
+ - Reduce Q3 scope by 30% to free engineering capacity for retention work
+Confidence: medium
+Caveat: Need sales input on which features are blocking new logo deals.
+[/RESPONSE]
+
+[RESPONSE:cmo]
+Key finding: Control the narrative; proactive communication to market reduces churn cascade risk.
+Supporting data:
+ - Draft customer communication within 48 hours (frame as strategic pivot, not loss)
+ - Press: no comment strategy unless proactively asked
+ - Replace pipeline: double down on ICP segments where we're strongest
+Confidence: medium
+Caveat: If customer goes public with criticism, narrative control becomes much harder.
+[/RESPONSE]
+
+CEO synthesis: [Aggregates all 9 responses, identifies conflicts, sets priorities]
+```
+
+---
+
+## When to Invoke vs When to Assume
+
+### Invoke when:
+- Cross-functional data is material to the decision
+- Getting it wrong changes the recommendation significantly
+- The other role has data you genuinely don't have
+- Time allows (not in Phase 2 isolation)
+
+### Assume when:
+- You're in Phase 2 (always — no exceptions)
+- The chain is at depth 2 (you cannot invoke further)
+- The answer is directionally obvious (e.g., "CFO will care about runway")
+- The precision doesn't change the recommendation
+
+### State assumptions explicitly:
+```
+[ASSUMPTION: runway ~12 months — not verified with CFO; actual may vary ±20%]
+[ASSUMPTION: CAC ~$8K based on industry benchmark — CMO has actual figures]
+[ASSUMPTION: engineering capacity at ~70% — not verified with CTO]
+```
+
+---
+
+## Handling Conflicting Responses
+
+When two agents give incompatible answers, surface it:
+
+```
+[CONFLICT DETECTED]
+CFO says: runway extends to 18 months if Q3 targets hit
+CRO says: only 45% confidence Q3 targets will be hit
+Resolution: use probabilistic blend
+ - 45% probability: 18-month runway (optimistic case)
+ - 55% probability: 11-month runway (current trajectory)
+Expected value: ~14 months
+Recommendation: plan for 12 months, trigger bridge at 10.
+[/CONFLICT]
+```
+
+**Resolution options:**
+1. **Conservative:** Use worse case — appropriate for cash/runway decisions
+2. **Probabilistic:** Weight by confidence scores — appropriate for planning
+3. **Escalate:** Flag for human decision — appropriate for high-stakes irreversible choices
+4. **Time-box:** Gather more data within 48 hours — appropriate when data gap is closeable
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-pattern | Problem | Fix |
+|---|---|---|
+| Invoke to validate your own conclusion | Confirmation bias loop | Ask open-ended questions |
+| Invoke when assuming works | Unnecessary latency | State assumption clearly |
+| Hide conflicts between responses | Bad synthesis | Always surface conflicts |
+| Invoke across depth > 2 | Loop risk | State assumption at depth 2 |
+| Invoke during Phase 2 | Groupthink contamination | Flag with [ASSUMPTION:] |
+| Vague questions | Poor responses | Specific, scoped questions only |
diff --git a/skills/c-suite-competitive-intel/SKILL.md b/skills/c-suite-competitive-intel/SKILL.md
new file mode 100644
index 00000000..972a5fbc
--- /dev/null
+++ b/skills/c-suite-competitive-intel/SKILL.md
@@ -0,0 +1,203 @@
+---
+name: competitive-intel
+description: "Systematic competitor tracking that feeds CMO positioning, CRO battlecards, and CPO roadmap decisions. Use when analyzing competitors, building sales battlecards, tracking market moves, positioning against alternatives, or when user mentions competitive intelligence, competitive analysis, competitor research, battlecards, win/loss, or market positioning."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: competitive-strategy
+ updated: 2026-03-05
+ frameworks: ci-playbook, battlecard-template
+---
+
+# Competitive Intelligence
+
+Systematic competitor tracking. Not obsession — intelligence that drives real decisions.
+
+## Keywords
+competitive intelligence, competitor analysis, battlecard, win/loss analysis, competitive positioning, competitive tracking, market intelligence, competitor research, SWOT, competitive map, feature gap analysis, competitive strategy
+
+## Quick Start
+
+```
+/ci:landscape — Map your competitive space (direct, indirect, future)
+/ci:battlecard [name] — Build a sales battlecard for a specific competitor
+/ci:winloss — Analyze recent wins and losses by reason
+/ci:update [name] — Track what a competitor did recently
+/ci:map — Build competitive positioning map
+```
+
+## Framework: 5-Layer Intelligence System
+
+### Layer 1: Competitor Identification
+
+**Direct competitors:** Same ICP, same problem, comparable solution, similar price point.
+**Indirect competitors:** Same budget, different solution (including "do nothing" and "build in-house").
+**Future competitors:** Well-funded startups in adjacent space; large incumbents with stated roadmap overlap.
+
+**The 2x2 Threat Matrix:**
+
+| | Same ICP | Different ICP |
+|---|---|---|
+| **Same problem** | Direct threat | Adjacent (watch) |
+| **Different problem** | Displacement risk | Ignore for now |
+
+Update this quarterly. Who's moved quadrants?
+
+### Layer 2: Tracking Dimensions
+
+Track these 8 dimensions per competitor:
+
+| Dimension | Sources | Cadence |
+|-----------|---------|---------|
+| **Product moves** | Changelog, G2/Capterra reviews, Twitter/LinkedIn | Monthly |
+| **Pricing changes** | Pricing page, sales call intel, customer feedback | Triggered |
+| **Funding** | Crunchbase, TechCrunch, LinkedIn | Triggered |
+| **Hiring signals** | LinkedIn job postings, Indeed | Monthly |
+| **Partnerships** | Press releases, co-marketing | Triggered |
+| **Customer wins** | Case studies, review sites, LinkedIn | Monthly |
+| **Customer losses** | Win/loss interviews, churned accounts | Ongoing |
+| **Messaging shifts** | Homepage, ads (Facebook/Google Ad Library) | Quarterly |
+
+### Layer 3: Analysis Frameworks
+
+**SWOT per Competitor:**
+- Strengths: What do they do well? Where do they win?
+- Weaknesses: Where do they lose? What do customers complain about?
+- Opportunities: What could they do that would threaten you?
+- Threats: What's their existential risk?
+
+**Competitive Positioning Map (2 axis):**
+Choose axes that matter for your buyers:
+- Common: Price vs Feature Depth; Enterprise-ready vs SMB-ready; Easy to implement vs Configurable
+- Pick axes that show YOUR differentiation clearly
+
+**Feature Gap Analysis:**
+| Feature | You | Competitor A | Competitor B | Gap status |
+|---------|-----|-------------|-------------|------------|
+| [Feature] | ✅ | ✅ | ❌ | Your advantage |
+| [Feature] | ❌ | ✅ | ✅ | Gap — roadmap? |
+| [Feature] | ✅ | ❌ | ❌ | Moat |
+| [Feature] | ❌ | ❌ | ✅ | Competitor B only |
+
+### Layer 4: Output Formats
+
+**For Sales (CRO):** Battlecards — one page per competitor, designed for pre-call prep.
+See `templates/battlecard-template.md`
+
+**For Marketing (CMO):** Positioning update — message shifts, new differentiators, claims to stop or start making.
+
+**For Product (CPO):** Feature gap summary — what customers ask for that we don't have, what competitors ship, what to reprioritize.
+
+**For CEO/Board:** Monthly competitive summary — 1-page: who moved, what it means, recommended responses.
+
+### Layer 5: Intelligence Cadence
+
+**Monthly (scheduled):**
+- Review all tier-1 competitors (direct threats, top 3)
+- Update battlecards with new intel
+- Publish 1-page summary to leadership
+
+**Triggered (event-based):**
+- Competitor raises funding → assess implications within 48 hours
+- Competitor launches major feature → product + sales response within 1 week
+- Competitor poaches key customer → win/loss interview within 2 weeks
+- Competitor changes pricing → analyze and respond within 1 week
+
+**Quarterly:**
+- Full competitive landscape review
+- Update positioning map
+- Refresh ICP competitive threat assessment
+- Add/remove companies from tracking list
+
+---
+
+## Win/Loss Analysis
+
+This is the highest-signal competitive data you have. Most companies do it too rarely.
+
+**When to interview:**
+- Every lost deal >$50K ACV
+- Every churn >6 months tenure
+- Every competitive win (learn why — it may not be what you think)
+
+**Who conducts it:**
+- NOT the AE who worked the deal (too close, prospect won't be candid)
+- Customer success, product team, or external researcher
+
+**Question structure:**
+1. "Walk me through your evaluation process"
+2. "Who else were you considering?"
+3. "What were the top 3 criteria in your decision?"
+4. "Where did [our product] fall short?"
+5. "What was the deciding factor?"
+6. "What would have changed your decision?"
+
+**Aggregate findings monthly:**
+- Win reasons (rank by frequency)
+- Loss reasons (rank by frequency)
+- Competitor win rates (by competitor, by segment)
+- Patterns over time
+
+---
+
+## The Balance: Intelligence Without Obsession
+
+**Signs you're over-tracking competitors:**
+- Roadmap decisions are primarily driven by "they just shipped X"
+- Team morale drops when competitors fundraise
+- You're shipping features you don't believe in to match their checklist
+- Pricing discussions always start with "well, they charge X"
+
+**Signs you're under-tracking:**
+- Your AEs get blindsided on calls
+- Prospects know more about competitors than your team does
+- You missed a major product launch until customers told you
+- Your positioning hasn't changed in 12+ months despite market moves
+
+**The right posture:**
+- Know competitors well enough to win against them
+- Don't let them set your agenda
+- Your roadmap is led by customer problems, informed by competitive gaps
+
+---
+
+## Distributing Intelligence
+
+| Audience | Format | Cadence | Owner |
+|----------|--------|---------|-------|
+| AEs + SDRs | Updated battlecards in CRM | Monthly + triggered | CRO |
+| Product | Feature gap analysis | Quarterly | CPO |
+| Marketing | Positioning brief | Quarterly | CMO |
+| Leadership | 1-page competitive summary | Monthly | CEO/COO |
+| Board | Competitive landscape slide | Quarterly | CEO |
+
+**One source of truth:** All competitive intel lives in one place (Notion, Confluence, Salesforce). Avoid Slack-only distribution — it disappears.
+
+---
+
+## Red Flags in Competitive Intelligence
+
+| Signal | What it means |
+|--------|---------------|
+| Competitor's win rate >50% in your core segment | Fundamental positioning problem, not sales problem |
+| Same objection from 5+ deals: "competitor has X" | Feature gap that's real, not just optics |
+| Competitor hired 10 engineers in your domain | Major product investment incoming |
+| Competitor raised >$20M and targets your ICP | 12-month runway for them to compete hard |
+| Prospects evaluate you to justify competitor decision | You're the "check box" — fix perception or segment |
+
+## Integration with C-Suite Roles
+
+| Intelligence Type | Feeds To | Output Format |
+|------------------|----------|---------------|
+| Product moves | CPO | Roadmap input, feature gap analysis |
+| Pricing changes | CRO, CFO | Pricing response recommendations |
+| Funding rounds | CEO, CFO | Strategic positioning update |
+| Hiring signals | CHRO, CTO | Talent market intelligence |
+| Customer wins/losses | CRO, CMO | Battlecard updates, positioning shifts |
+| Marketing campaigns | CMO | Counter-positioning, channel intelligence |
+
+## References
+- `references/ci-playbook.md` — OSINT sources, win/loss framework, positioning map construction
+- `templates/battlecard-template.md` — sales battlecard template
diff --git a/skills/c-suite-competitive-intel/_meta.json b/skills/c-suite-competitive-intel/_meta.json
new file mode 100644
index 00000000..002fb195
--- /dev/null
+++ b/skills/c-suite-competitive-intel/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "c-suite-competitive-intel",
+ "displayName": "C-Suite Competitive Intel",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1772758908388,
+ "commit": "https://github.com/openclaw/skills/commit/560a67b8380bc239e54144b109d6624de3d3792c"
+ },
+ "history": []
+}
diff --git a/skills/c-suite-competitive-intel/references/ci-playbook.md b/skills/c-suite-competitive-intel/references/ci-playbook.md
new file mode 100644
index 00000000..759c9886
--- /dev/null
+++ b/skills/c-suite-competitive-intel/references/ci-playbook.md
@@ -0,0 +1,237 @@
+# Competitive Intelligence Playbook
+
+## OSINT Sources for Competitor Tracking
+
+### Free, Reliable Sources
+
+**Company & Product:**
+- **Their website** — pricing page (archive.org for history), product changelog, careers page
+- **G2 / Capterra / Trustpilot** — customer reviews; filter by recency; read 1-star reviews carefully
+- **LinkedIn** — job postings signal roadmap; company page for headcount trend; employees for leaks
+- **GitHub** — open source activity; what they're building; engineering team size; tech stack
+- **Crunchbase / PitchBook** (free tier) — funding history, investors, team changes
+- **BuiltWith** — tech stack they use; signals about infrastructure maturity
+
+**Messaging & Positioning:**
+- **Facebook Ad Library** — see their current ad copy and creative; what messages they're testing
+- **Google Keyword Planner** — which keywords they're bidding on
+- **SEMrush / Ahrefs** (free trial or limited) — their organic keywords, backlink profile
+- **Wayback Machine** — homepage evolution over time; when positioning shifted
+- **Their blog** — content strategy reveals priorities and ICP assumptions
+
+**News & Events:**
+- **TechCrunch, VentureBeat** — funding announcements, major launches
+- **Twitter/X / LinkedIn** — CEO + founders; direct signals about strategy
+- **Podcast appearances** — founders talk more openly on podcasts than press releases
+- **Job descriptions** — "Senior Engineer - Payments" means they're building payments
+
+### Paid (Worth It for Tier-1 Competitors)
+- **G2 Buyer Intent** — which prospects are researching your competitor right now
+- **Bombora** — intent data for account-level research signals
+- **PitchBook** — funding, investors, valuation estimates
+- **Klue / Crayon / Kompyte** — dedicated CI platforms that aggregate automatically
+
+### Primary Research (Best Signal)
+- **Win/loss interviews** — the single highest-signal source (see below)
+- **Talk to churned customers** — why did they switch? To whom?
+- **Talk to their customers** — LinkedIn outreach; honest conversations
+- **Industry events** — competitor presentations reveal roadmap; talk to attendees
+- **Former employees** — LinkedIn; respectful outreach; no NDA violations
+
+---
+
+## Competitive Battlecard Format
+
+A battlecard is a 1-page (or single screen) document for sales reps to reference before and during calls.
+
+**Design principles:**
+- Written for a rep with 2 minutes to prep, not a product manager
+- Action-oriented: tells reps what to SAY, not just what to know
+- Updated monthly at minimum; never more than 90 days old
+
+### Battlecard Structure
+
+```
+COMPETITOR: [Name]
+Last updated: [Date] | Owner: [Name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+THE 30-SECOND SUMMARY
+[One paragraph. Who they are, who they sell to, why they win.]
+
+THEIR STRENGTHS (know these — don't dismiss them)
+• [Strength 1] — what customers actually love about them
+• [Strength 2]
+• [Strength 3]
+
+THEIR REAL WEAKNESSES (from win/loss data, not assumptions)
+• [Weakness 1] — source: [customer quote / win/loss theme]
+• [Weakness 2]
+• [Weakness 3]
+
+OUR DIFFERENTIATED ADVANTAGES
+• [Advantage 1] — proof point: [metric/customer/case study]
+• [Advantage 2] — proof point:
+• [Advantage 3] — proof point:
+
+COMMON OBJECTIONS + RESPONSES
+"They have [feature] and you don't."
+→ [Response. Acknowledge, reframe, redirect.]
+
+"They're cheaper."
+→ [Response with ROI angle or TCO comparison.]
+
+"They're more established / bigger."
+→ [Response. Size isn't always advantage; use to your benefit.]
+
+TRAP-SETTING QUESTIONS (ask these early to shift the eval criteria)
+• "How important is [your differentiator] to your team?"
+• "Have you looked at [pain point they create]?"
+• "What happens to your workflow when [their known limitation occurs]?"
+
+WHEN WE WIN
+• [Segment or scenario where we almost always beat them]
+• [Use case where we're clearly stronger]
+
+WHEN WE LOSE (be honest)
+• [Scenario where they're genuinely better — don't fight these battles]
+• [Segment where they have structural advantages]
+
+DO NOT SAY
+• Don't claim [X] — it's not true and they'll call it out
+• Don't say [Y] — prospect will already know it and it sounds desperate
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Win/Loss Analysis Framework
+
+### Why Most Companies Do This Wrong
+- They survey instead of interview (surveys get polite answers)
+- The AE conducts it (too emotionally invested; prospect won't be candid)
+- They do it 6 months after the decision (memory fades)
+- They look for confirmation of what they believe
+
+### The Right Process
+
+**Timing:** Within 30 days of deal closed/lost/churned.
+**Interviewer:** Customer success, product, or external researcher. Never the AE.
+**Duration:** 30 minutes (budget 45).
+**Incentive:** $100 gift card gets you 80% acceptance. Worth it.
+
+**Interview Guide:**
+
+*Opening:*
+"I'm [name] from [company]. I'm not in sales — I'm trying to understand what drove your decision so we can improve. There's nothing you can say that will change the outcome. I just want honest feedback."
+
+*Core questions:*
+1. "Can you walk me through your evaluation process from the beginning?"
+2. "Who were the key stakeholders involved in the decision?"
+3. "What were the 3 most important criteria you were evaluating against?"
+4. "Which vendors did you seriously consider?"
+5. "Where did [company] fall short of your expectations?" (For losses)
+ OR "What tipped the decision in [company]'s favor?" (For wins)
+6. "Was price a factor? How significant?"
+7. "What would have had to be different for you to choose [us / the other option]?"
+8. "Any advice for our team on how we handled the process?"
+
+**Data aggregation:**
+- Tag every response: [criterion], [competitor mentioned], [product gap], [sales process], [price], [trust/credibility]
+- Monthly rollup: top 5 win reasons, top 5 loss reasons, competitor win rate
+- Share with: CEO, CRO, CPO, CMO — not just sales
+
+---
+
+## Competitive Positioning Map Construction
+
+A positioning map shows where you sit relative to competitors on 2 dimensions that BUYERS care about.
+
+### Step 1: Choose Your Axes
+- Pick dimensions that actually drive purchase decisions in your segment
+- At least one axis should be where you win
+- Avoid generic axes ("feature-rich vs. simple" tells you nothing)
+
+**Good axis pairs:**
+- Implementation time (days vs. months) × Customization depth
+- Price point × Enterprise readiness
+- Automation level × Human-in-the-loop control
+- Time-to-value × Total cost of ownership
+
+**Bad axes:**
+- Quality (too vague)
+- "Innovation" (unmeasurable)
+- Any axis where all competitors cluster in the same spot
+
+### Step 2: Place Competitors Objectively
+- Use customer quotes and win/loss data to justify placement
+- Don't place competitors where you WANT them — where they ACTUALLY are
+- If you're unsure, ask 5 customers to place them
+
+### Step 3: Find and Name Your White Space
+- Where is there a position no competitor holds?
+- Is that white space there because it's valuable (opportunity) or worthless (avoid)?
+- Can you credibly occupy it?
+
+### Step 4: Test Your Positioning
+- Show the map to 5 prospects: "Does this match your perception?"
+- Show it to 5 lost prospects: "Where would you place [the winner] and us?"
+- Adjust until map matches buyer reality, not internal perception
+
+---
+
+## Intelligence Sharing Across Roles
+
+### What Each Role Needs and When
+
+**CRO (Sales):**
+- Needs: Battlecards, win rates by competitor, competitor objections + responses
+- Cadence: Updated battlecards monthly; triggered updates on major competitor moves
+- Format: 1-pager per competitor in CRM, linked from deal record
+
+**CMO (Marketing):**
+- Needs: Messaging shifts, new claims, ad spend signals, keyword battles
+- Cadence: Quarterly positioning review, triggered on major launches
+- Format: Positioning brief with recommended response to messaging shifts
+
+**CPO (Product):**
+- Needs: Feature gap analysis, competitor roadmap signals (job postings, changelog), what we lose to
+- Cadence: Monthly feature gap update, triggered on major launches
+- Format: Feature comparison matrix + gap prioritization recommendation
+
+**CTO (Engineering):**
+- Needs: Tech stack signals, infrastructure approaches, scale they've achieved
+- Cadence: Quarterly
+- Format: Technical comparison notes, relevant for architectural decisions
+
+**CEO:**
+- Needs: Summary of threat landscape, recommended responses, board-level narrative
+- Cadence: Monthly 1-pager + quarterly deep dive
+- Format: 1-page brief: who moved, what it means, what we do
+
+### The Single Source of Truth Rule
+All competitive intel in one place. Suggest:
+- Notion database per competitor: profile, battlecard, changelog, win/loss notes
+- Slack channel: `#competitive-intel` for real-time triggered alerts
+- Monthly digest email to leadership
+
+If it lives only in Slack, it disappears. If it lives only in a wiki that nobody reads, it doesn't matter. Combine both.
+
+---
+
+## How to Track Without Obsessing
+
+**Set up the system, then let it run:**
+- Google Alerts for competitor names + CEO names
+- LinkedIn Saved Searches for their job postings
+- Klue/Crayon if budget allows (automated aggregation)
+- Monthly 60-minute competitive review meeting (not 4 hours)
+
+**What to do when competitor makes a big move:**
+1. Read the announcement objectively
+2. Talk to 3 customers: "Did you see this? What do you think?"
+3. Assess: does this change any buying criteria in your deals?
+4. If yes: update battlecard and positioning within 1 week
+5. If no: log it, move on
+
+**The test:** After reviewing a competitor move, do you feel urgency to ship something? If yes, you're reacting. The right feeling is "noted — let's see if customers care."
diff --git a/skills/c-suite-competitive-intel/templates/battlecard-template.md b/skills/c-suite-competitive-intel/templates/battlecard-template.md
new file mode 100644
index 00000000..39b0a99e
--- /dev/null
+++ b/skills/c-suite-competitive-intel/templates/battlecard-template.md
@@ -0,0 +1,99 @@
+# Sales Battlecard Template
+
+**COMPETITOR:** [Name]
+**Last updated:** [YYYY-MM-DD] | **Owner:** [Name]
+**Win rate vs this competitor:** [X]% | **Deals tracked:** [N]
+
+---
+
+## 30-Second Summary
+[Who they are. Who they target. Why they win. What they're known for. 3-4 sentences max.]
+
+---
+
+## Their Strengths
+*Know these. Don't dismiss them. Prospects have already heard their pitch.*
+
+- **[Strength]:** [What customers genuinely love; source if available]
+- **[Strength]:** [Specific capability or trait]
+- **[Strength]:** [Brand, market position, or ecosystem advantage]
+
+---
+
+## Their Real Weaknesses
+*From win/loss data only — not wishful thinking.*
+
+- **[Weakness]:** "[Customer quote]" — seen in [N] deals
+- **[Weakness]:** [Documented limitation with evidence]
+- **[Weakness]:** [Implementation, support, or pricing issue]
+
+---
+
+## Our Differentiated Advantages
+*Must be real and provable. Each needs a proof point.*
+
+- **[Advantage]:** [Proof: metric / customer quote / case study]
+- **[Advantage]:** [Proof]
+- **[Advantage]:** [Proof]
+
+---
+
+## Common Objections + Responses
+
+**"They have [feature X] and you don't."**
+> [Acknowledge. Reframe to your strength. Redirect to outcome.
+> "You're right that they have X. What we've found is that customers who care most about X tend to also care about [Y], where we're significantly stronger. Can I show you [specific example]?"]
+
+**"They're cheaper."**
+> [Don't fight on price. Reframe to TCO or ROI.
+> "They are lower in initial cost. Most customers find the total cost over 12 months is actually comparable when you factor in [implementation time / support costs / integrations]. Want to walk through that?"]
+
+**"They've been around longer / they're more established."**
+> [Reframe tenure as potential liability or irrelevance.
+> "Their longevity means they have a lot of technical debt and a big customer base that pulls their roadmap in every direction. Our customers tell us that's exactly why they chose us — we move faster and we're laser-focused on [their specific use case]."]
+
+**"[Competitor] is already used by [big customer they respect]."**
+> [Name-drop your wins in their segment.
+> "We work with [comparable logo]. Want me to connect you with their [role] to ask how they made the decision?"]
+
+---
+
+## Trap-Setting Questions
+*Ask early in discovery to establish criteria that favor you.*
+
+- "How important is [your key differentiator] to your workflow?"
+- "What happens when [their known limitation] occurs? Has that been an issue before?"
+- "How long does your team typically take to onboard a new tool?"
+- "Who manages the integration work — do you have dedicated engineering resources for that?"
+- "What does your current vendor do when you need support?"
+
+---
+
+## When We Win
+- [Scenario or segment where we consistently beat them]
+- [Use case that plays to our strengths]
+- [Buyer profile that prefers us]
+
+## When We Lose (Be Honest)
+- [Scenario where they genuinely win — don't fight here]
+- [Segment where their strengths matter more than ours]
+
+---
+
+## Do NOT Say
+- ❌ Don't claim [X] — it's not accurate and they'll check
+- ❌ Don't attack [Y] — it backfires and makes us look insecure
+- ❌ Don't say "we're better" without specifics — be concrete
+
+---
+
+## Recent Intel
+*Last 90 days only. Older than 90 days: archive.*
+
+- [Date]: [What happened — funding, product launch, pricing change, key hire]
+- [Date]: [Customer feedback from win/loss interview]
+- [Date]: [Any notable market move]
+
+---
+
+*Battlecards are only useful if current. If this is >90 days old, flag to [owner] for update.*
diff --git a/skills/c-suite-founder-coach/SKILL.md b/skills/c-suite-founder-coach/SKILL.md
new file mode 100644
index 00000000..c3437375
--- /dev/null
+++ b/skills/c-suite-founder-coach/SKILL.md
@@ -0,0 +1,300 @@
+---
+name: founder-coach
+description: "Personal leadership development for founders and first-time CEOs. Covers founder archetype identification, delegation frameworks, energy management, CEO calendar audits, leadership style evolution, blind spot identification, imposter syndrome, founder mental health, and succession planning. Use when a founder feels like the bottleneck, struggles to delegate, is burning out, transitioning from IC to executive, managing a board, or when user mentions founder mode, CEO growth, leadership development, delegation, burnout, or imposter syndrome."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: founder-development
+ updated: 2026-03-05
+ frameworks: leadership-growth, founder-toolkit
+---
+
+# Founder Development Coach
+
+Your company can only grow as fast as you do. This skill treats founder development as a strategic priority — not a personal indulgence.
+
+## Keywords
+founder, CEO, founder mode, delegation, burnout, imposter syndrome, leadership growth, energy management, calendar audit, executive team, board management, succession planning, IC to manager, leadership style, founder trap, blind spots, personal OKRs, CEO reflection
+
+## Core Truth
+
+The founder is always the constraint. Not intentionally — it's structural. You built the company. You know everything. Decisions flow through you. This works until it doesn't.
+
+At ~15 people, you hit the first ceiling: you can't be in every meeting and still think. At ~50 people, the second: your style starts creating culture problems. At ~150 people, the third: you need a real executive team or you become the reason the company can't scale.
+
+The earlier you address this, the better.
+
+---
+
+## 1. Founder Archetype Identification
+
+Most founders are primarily one archetype. Knowing yours predicts what you'll struggle with.
+
+| Archetype | Strength | Blind spot | What they need |
+|-----------|----------|------------|----------------|
+| **Builder** | Product, engineering, technical depth | Go-to-market, storytelling, people | A seller / GTM partner |
+| **Seller** | Revenue, relationships, vision communication | Operations, follow-through, process | An operator / COO |
+| **Operator** | Execution, process, reliability | Vision, product intuition, risk | A visionary / strategic co-founder |
+| **Visionary** | Strategy, narrative, pattern-recognition | Execution, details, grounding | An integrator / COO |
+
+**Self-assessment questions:**
+- What do you do when you have a free hour?
+- What do you procrastinate on most?
+- What do your co-founders or early team complain you don't do?
+- What's the best feedback you've received about your leadership?
+
+Most founders are Builder or Visionary. Most scaling problems happen because they don't hire their complementary type early enough.
+
+---
+
+## 2. Delegation Framework
+
+Founders fail to delegate for four reasons:
+1. "Nobody does it as well as I do" (often true short-term, fatal long-term)
+2. "It takes longer to explain than to do it" (true once; not true the 10th time)
+3. "I lose control if I don't do it myself" (control is an illusion at scale)
+4. "If it fails, it's my fault" (it's your fault if you never let anyone else try)
+
+### The Skill × Will Matrix
+
+| | High Skill | Low Skill |
+|---|-----------|----------|
+| **High Will** | Delegate fully | Coach and develop |
+| **Low Will** | Motivate or reassign | Manage out or redesign role |
+
+**Rules:**
+- High skill + high will → Give the work and get out of the way
+- High will + low skill → Invest in them. They want to grow.
+- High skill + low will → Find out why. Fix the environment or accept the mismatch.
+- Low skill + low will → Don't delegate to them. Address the performance issue.
+
+### The Delegation Ladder
+
+Not all delegation is equal. Build up gradually:
+
+1. "Do exactly what I tell you" — not delegation, instruction
+2. "Research this and report back" — information gathering
+3. "Propose a solution and I'll decide" — thinking delegation
+4. "Decide and tell me what you decided" — decision delegation with review
+5. "Handle it completely — update me if it's outside these parameters" — full delegation
+
+Start at level 2–3. Move people up as trust is established. Most founders never get past level 3 with their team — that's the bottleneck.
+
+### What to delegate first
+
+**Delegate first (high volume, low stakes):**
+- Recurring operational tasks you do the same way every time
+- Information gathering and synthesis
+- Meeting coordination and scheduling
+- Reports and updates you produce regularly
+
+**Delegate next (skill-buildable):**
+- Customer interactions (with clear principles)
+- Hiring screens (after you've trained judgment)
+- Partner relationship management
+- Budget management within parameters
+
+**Delegate last (strategic, irreversible):**
+- Major strategic pivots
+- Executive hires
+- Large financial commitments
+- M&A decisions
+
+---
+
+## 3. Energy Management
+
+Founders manage energy, not just time. Time is fixed. Energy is renewable — but only if you manage it.
+
+### The Energy Audit
+
+Map your week by energy, not tasks. See `references/founder-toolkit.md` for the full template.
+
+**Categories:**
+- 🟢 **Energizing:** Activities that leave you sharper after doing them
+- 🟡 **Neutral:** Neither energizing nor draining
+- 🔴 **Draining:** Activities that leave you depleted
+
+**Common founder energy patterns:**
+- **Builders:** Energized by creating, drained by politics and process
+- **Sellers:** Energized by people and wins, drained by detail work and admin
+- **Operators:** Energized by solving, drained by ambiguity and indecision
+- **Visionaries:** Energized by strategy and ideas, drained by execution and repetition
+
+**The rule:** Maximize green. Eliminate or delegate red. Accept yellow as the price of leadership.
+
+### Energy management practices
+
+**Protect deep work time.** 2–4 hours of uninterrupted thinking time, 3–5 days per week. Schedule it. Defend it. This is where strategy happens.
+
+**Batch shallow work.** Email, Slack, administrative tasks — twice a day maximum.
+
+**Single-task during recovery.** If you're depleted, don't try to do your best work. Do tasks that don't require your best.
+
+**Identify your peak window.** Most people have 4–6 peak hours per day. Schedule your hardest work in those windows.
+
+---
+
+## 4. CEO Calendar Audit
+
+The calendar is the most honest document in a founder's life. It shows what you actually prioritize, not what you say you prioritize.
+
+### Running the audit
+
+Pull the last 4 weeks of calendar data. Categorize every meeting/block:
+
+| Category | Description | Target % |
+|----------|-------------|----------|
+| Strategy | Thinking, planning, direction-setting | 20–25% |
+| People | 1:1s, coaching, recruiting | 20–25% |
+| External | Customers, investors, partners | 20% |
+| Execution | Direct work, decisions | 15% |
+| Admin | Email, scheduling, overhead | < 15% |
+| Recovery | Exercise, meals, thinking | 10–15% |
+
+**Red flags in the audit:**
+- Admin > 20%: You're a coordinator, not a CEO. Fix your systems.
+- Execution > 30%: You're still an IC. Build the team.
+- People < 10%: Your team is running on empty. They need more of you.
+- No recovery blocks: You're running on adrenaline. It ends badly.
+- Strategy < 10%: You're running the company, not leading it.
+
+### The CEO's primary job at each stage
+
+| Stage | CEO should spend most time on... |
+|-------|--------------------------------|
+| Seed | Product and customers. Directly. |
+| Series A | Hiring the executive team. Recruiting is your job. |
+| Series B | Culture, strategy, and external (investors/partners/customers) |
+| Series C+ | Vision, board, external narrative, executive development |
+
+If you're spending time on things from two stages ago, you haven't made the transition.
+
+---
+
+## 5. Leadership Style Evolution
+
+The job changes at every stage. Most founders don't change with it.
+
+**IC → Manager (0 to ~10 people):**
+You need to teach and build trust. People are watching how you treat failure. The skill: give clear context, set expectations, check in frequently.
+
+**Manager → Leader (~10 to ~50 people):**
+You can't manage everyone directly. You need people who manage people. The skill: hire managers you trust, let them manage.
+
+**Leader → Executive (~50 to ~200 people):**
+You're now setting culture and direction, not managing work. The skill: communicate obsessively, decide at the right altitude, develop your leadership team.
+
+**Executive → Institutional CEO (200+):**
+You're a symbol as much as a manager. The skill: build systems that work without you; focus on board, investors, and external narrative.
+
+**The hardest transition:** Manager → Leader. You have to stop doing things yourself and trust people you're still getting to know.
+
+---
+
+## 6. Blind Spot Identification
+
+Everyone has them. Founders more than most — because nobody in the early company had the authority or safety to tell you.
+
+### Common founder blind spots
+
+- **Communication:** "I said it once, they should know" — you said it; they didn't hear it or didn't believe it
+- **Decision speed:** Moving so fast that teams can't orient or build on your direction
+- **Context hoarding:** Knowing what's happening without sharing it, then being frustrated that teams make bad decisions
+- **Optimism bias:** Consistently underestimating timelines, cost, and difficulty
+- **Founder exceptionalism:** Rules that apply to everyone don't apply to you
+- **Feedback avoidance:** Creating an environment where no one gives you honest feedback
+
+### How to find your blind spots
+
+1. **360 feedback (anonymous):** Once a year. Ask direct reports, peers, board members. Include "What does [name] do that gets in the way of our success?"
+2. **Exit interview analysis:** What do departing employees consistently say? Find the pattern.
+3. **Failure post-mortems:** What do your worst decisions have in common? What were you assuming that wasn't true?
+4. **The energy audit:** Where do you consistently drain the people around you?
+
+---
+
+## 7. Imposter Syndrome Toolkit
+
+It doesn't go away. It evolves. The founder who was scared to pitch to investors is now scared to manage a board. The founder who was scared to hire is now scared to fire.
+
+**The reframe:** Imposter syndrome is proportional to stretch. If you never feel it, you're not growing.
+
+**Practical tools:**
+- **Evidence file:** Document wins, compliments, decisions that worked. Read it when the doubt hits.
+- **Normalize the feeling:** "I feel underprepared for this" ≠ "I am an imposter." Feeling and fact are different.
+- **Do the thing anyway.** Competence comes from doing, not from feeling ready.
+- **Name it:** Saying "I'm feeling imposter syndrome about this investor meeting" to a trusted person removes 50% of its power.
+
+---
+
+## 8. Founder Mental Health
+
+Burnout isn't weakness. It's a predictable outcome of high-demand + low-recovery + no control over inputs.
+
+### Burnout signals
+
+Early: Irritability, difficulty sleeping, decisions feel harder than they should, loss of enthusiasm for the mission.
+Mid: Physical symptoms (headaches, illness), cynicism about the company, social withdrawal, all tasks feel equally important (priority paralysis).
+Late: Can't function, decisions have stopped, team notices before you do.
+
+**If you're in late burnout:** Stop performing. Get support. The company needs a functioning founder more than it needs a martyred one.
+
+### Structural prevention
+
+- **Protect recovery time.** Not weekends — protected time during the week where you're not available.
+- **Therapy or coaching.** Not optional for founders. The job is isolating and the stakes are high.
+- **Peer group.** Other founders at similar stages. They're the only people who actually understand the job.
+- **Clear off-ramps.** Know what "enough for today" looks like. Don't let the work be infinite.
+
+---
+
+## 9. The Founder Mode Trap
+
+Paul Graham's "Founder Mode" essay made the case that great founders stay deeply involved in operations — skip middle management and go direct. It resonated because it's sometimes true.
+
+**When founder mode helps:**
+- Crisis recovery (company needs direct leadership)
+- Product-market fit search (speed matters more than org health)
+- High-value, irreversible decisions (you should be in the room)
+- Early stages when the team is small
+
+**When founder mode hurts:**
+- When it undermines managers you've hired (they can't lead if you override them)
+- When it's driven by distrust rather than strategy
+- When it prevents the team from developing judgment
+- When you're doing it because you miss doing, not because the company needs you to
+
+**The test:** Are you going deep because the situation requires it, or because you're uncomfortable with the loss of control? The first is leadership. The second is the trap.
+
+---
+
+## 10. Succession Planning
+
+Building a company that works without you is not disloyalty — it's the ultimate expression of leadership.
+
+**Succession is not just about exit.** It's about resilience. What happens if you're sick? On sabbatical? Acquired?
+
+**Succession readiness levels:**
+- Level 1: You've documented your key knowledge and processes
+- Level 2: At least one person can cover each of your key functions for 2 weeks
+- Level 3: Your leadership team can run the company for a quarter without you
+- Level 4: You've identified and developed your potential successor
+
+Most founders are at Level 0. Level 2 is a reasonable target. Level 3 is a strategic asset.
+
+---
+
+## Key Questions for Founder Development
+
+- "What decisions did you make last week that someone else could have made?"
+- "What are you still doing that you should have delegated 6 months ago?"
+- "When did you last get honest, critical feedback? From whom? What did it say?"
+- "What would need to be true for the company to run for a week without you?"
+- "What's draining your energy that you've accepted as unavoidable?"
+
+## Detailed References
+- `references/leadership-growth.md` — Maxwell levels, situational leadership, founder-to-CEO transition
+- `references/founder-toolkit.md` — Weekly reflection, energy audit, delegation matrix, 1:1 templates
diff --git a/skills/c-suite-founder-coach/_meta.json b/skills/c-suite-founder-coach/_meta.json
new file mode 100644
index 00000000..f54b2789
--- /dev/null
+++ b/skills/c-suite-founder-coach/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "c-suite-founder-coach",
+ "displayName": "C-Suite Founder Coach",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1772758899594,
+ "commit": "https://github.com/openclaw/skills/commit/a06ba1f72910a7c9b37118b356b04fe779ca966f"
+ },
+ "history": []
+}
diff --git a/skills/c-suite-founder-coach/references/founder-toolkit.md b/skills/c-suite-founder-coach/references/founder-toolkit.md
new file mode 100644
index 00000000..0ae3cccc
--- /dev/null
+++ b/skills/c-suite-founder-coach/references/founder-toolkit.md
@@ -0,0 +1,296 @@
+# Founder Toolkit
+
+Practical tools for founder self-management and leadership development.
+
+---
+
+## 1. Weekly CEO Reflection Template
+
+**15 minutes. Every Friday. No excuses.**
+
+This is the most important meeting of the week. You with yourself.
+
+```
+DATE: _______________
+
+## This Week
+
+**1. What was my most important contribution this week?**
+(Not the longest meeting or the hardest problem — the thing that will matter in 90 days.)
+
+_______________________________________________
+
+**2. Where did I add the least value? Why was I involved?**
+(Be honest. Where were you in the room out of habit, not necessity?)
+
+_______________________________________________
+
+**3. What should I have delegated but didn't?**
+(Name the specific task and the person you could have delegated it to.)
+
+_______________________________________________
+
+**4. What decision am I avoiding? Why?**
+(Fear of being wrong? Not enough information? Conflict avoidance?)
+
+_______________________________________________
+
+**5. What would I do differently this week if I could do it over?**
+(One thing. Make it specific.)
+
+_______________________________________________
+
+## Next Week
+
+**My one most important outcome for next week:**
+_______________________________________________
+
+**What will I stop doing / not start / protect myself from?**
+_______________________________________________
+```
+
+---
+
+## 2. Energy Audit Template
+
+Map your week by energy, not tasks. Do this for one full work week.
+
+### Step 1: Time block mapping
+
+For each 30-minute block in your week, record:
+- What you did
+- Energy level: 🟢 Energizing / 🟡 Neutral / 🔴 Draining
+
+```
+Monday:
+08:00-08:30: __________________ [🟢/🟡/🔴]
+08:30-09:00: __________________ [🟢/🟡/🔴]
+09:00-09:30: __________________ [🟢/🟡/🔴]
+... (continue through the day)
+```
+
+### Step 2: Pattern analysis
+
+After one week, categorize activities:
+
+| Activity type | Energy level | Total hours | % of week |
+|--------------|-------------|-------------|-----------|
+| Customer calls | | | |
+| Investor meetings | | | |
+| Team 1:1s | | | |
+| Product decisions | | | |
+| Strategy/planning | | | |
+| Email/Slack | | | |
+| Recruiting | | | |
+| Financial review | | | |
+| External talks/events | | | |
+| Administrative tasks | | | |
+| Deep work/building | | | |
+| Recovery/breaks | | | |
+
+### Step 3: Optimization plan
+
+**Green activities to protect (min 40% of week):**
+- _______________________________________________
+
+**Red activities to eliminate or delegate (target: < 15% of week):**
+- Activity: __________________ → Delegate to: __________________
+- Activity: __________________ → Eliminate via: __________________
+
+**Your personal energy peak hours:**
+I do my best thinking: _______ to _______
+Schedule this time as: Protected deep work (no meetings)
+
+---
+
+## 3. Delegation Matrix
+
+For every task you regularly do, run it through this matrix.
+
+### Assessment
+
+| Task | Skill level needed | My will to keep it | Decision |
+|------|-------------------|-------------------|----------|
+| | High / Med / Low | High / Med / Low | Keep / Coach / Delegate / Kill |
+
+### Delegation scoring
+
+| My Skill | My Will | Decision |
+|----------|---------|----------|
+| High | High | Keep — this is your zone of genius |
+| High | Low | Delegate — you can do it, but it drains you. Train someone. |
+| Low | High | Develop — learn it or hire for it |
+| Low | Low | Kill or outsource — why is this on your plate? |
+
+### The 70% rule
+
+If someone can do a task 70% as well as you, delegate it. Trying to get to 100% is a trap:
+- Their 70% will grow to 90% with practice
+- Your 30% extra effort costs more than the quality gap
+- You free up time for things only you can do
+
+---
+
+## 4. 1:1 Template for Direct Reports
+
+Weekly or biweekly. 30 minutes. Their agenda, not yours.
+
+```
+DATE: _______________
+PERSON: _______________
+
+## Their Section (first 20 min)
+
+**What's on their mind? (open the meeting with this)**
+(No agenda from you first — let them lead)
+
+**What are they working on? Where are they stuck?**
+
+**What do they need from me?**
+
+**Anything they wanted to raise but haven't had the chance to?**
+
+## Your Section (last 10 min)
+
+**Context to share (strategy, changes, what they should know):**
+
+**Direct feedback to give (if any):**
+- Be specific: "In Tuesday's meeting, when you [did X], the impact was [Y]"
+- Make it actionable: "Next time, I'd suggest [Z]"
+
+**Career/growth check-in (monthly, not every meeting):**
+- How are they feeling about their growth?
+- What do they want to be doing more of?
+- What are they interested in that they're not currently doing?
+
+## Follow-ups
+
+| Commitment | Owner | Due |
+|------------|-------|-----|
+| | | |
+```
+
+### Rules for effective 1:1s
+
+- **Their agenda first.** If you dominate with your updates, they stop bringing theirs.
+- **No status updates.** That's what tools are for. This time is for their thinking, blockers, and development.
+- **Consistent time.** Rescheduled 1:1s signal that they're not a priority.
+- **Take notes.** Review them before the next meeting. It signals that you listened.
+- **Follow up on commitments.** If you say "I'll get you that answer by Thursday," get it by Thursday.
+
+---
+
+## 5. Personal OKRs for the Founder
+
+Most founders hold their team accountable to goals but have none themselves. Fix that.
+
+### Template: Quarterly Personal OKRs
+
+```
+Q[X] YYYY | FOUNDER OKRs
+
+## My One Priority This Quarter
+(The single most important thing I personally must accomplish)
+_______________________________________________
+
+## Objective 1: [Leadership Development]
+What I'm trying to achieve: _______________________________________________
+
+KR 1.1: [Measurable outcome by EoQ]
+KR 1.2: [Measurable outcome by EoQ]
+KR 1.3: [Measurable outcome by EoQ]
+
+Progress check (mid-quarter): _______________________________________________
+
+## Objective 2: [Delegation / Team Building]
+What I'm trying to achieve: _______________________________________________
+
+KR 2.1: [Measurable outcome by EoQ]
+KR 2.2: [Measurable outcome by EoQ]
+
+## Objective 3: [External Impact — Investors / Customers / Market]
+What I'm trying to achieve: _______________________________________________
+
+KR 3.1: [Measurable outcome by EoQ]
+KR 3.2: [Measurable outcome by EoQ]
+
+## The "Stop Doing" List (equally important)
+Things I'm committing to stop doing this quarter:
+- Stop: _______________________________________________
+- Stop: _______________________________________________
+- Stop: _______________________________________________
+```
+
+### Personal OKR examples
+
+**Objective: Become a better coach, not just a decision-maker**
+- KR: 90% of my direct reports can make their top 3 recurring decisions without me by EoQ
+- KR: In 1:1 reviews, 80% of team rates me as "helps me think through problems" vs "tells me what to do"
+- KR: Conduct quarterly 360 feedback session with all direct reports
+
+**Objective: Build investor trust before I need it**
+- KR: Monthly investor updates sent within 5 days of month-end, every month this quarter
+- KR: 1:1 calls with each board member, once per quarter, outside of board meetings
+- KR: Create and share 3-year financial model with board by EoQ
+
+**Objective: Protect my energy and performance**
+- KR: 3+ hours of protected deep work time per day, 4+ days per week
+- KR: Complete weekly CEO reflection every Friday (track: 0/13 weeks → 13/13)
+- KR: Zero email after 8pm, zero weekends unless explicit crisis
+
+---
+
+## 6. The "Stop Doing" List
+
+The hardest list to make and the most valuable to keep.
+
+Most founders have clear to-do lists. Few have stop-doing lists. The asymmetry is the problem.
+
+### The stop-doing audit
+
+**Things to stop doing immediately (decision you can make today):**
+- Attending meetings you don't add value to
+- Being the default person for decisions that should be made by others
+- Redoing work that your team completed
+- Checking email/Slack during deep work blocks
+- Starting tasks you know you'll delegate partway through
+
+**Things to stop doing by delegating (need to train someone):**
+- _______________________________________________
+- _______________________________________________
+- _______________________________________________
+
+**Things to stop doing by building systems:**
+- Recurring manual tasks → automate
+- Recurring decisions → write decision criteria so others can decide
+- Recurring explanations → document once, reference always
+
+### The decision filter
+
+Before accepting new responsibilities, run through:
+1. Does this require something only I can do?
+2. Is this the highest and best use of my time?
+3. If I say yes to this, what am I saying no to?
+
+If the answers are no, no, and something important — say no.
+
+---
+
+## 7. Evidence File
+
+For when imposter syndrome hits. Keep a running file of:
+
+**Wins** (monthly minimum)
+- Company milestones you led
+- Decisions that worked out well
+- Feedback you received that was genuinely positive
+
+**Quotes** (capture as they happen)
+- Direct quotes from team members, customers, investors about your impact
+- Emails or messages that reflect trust or appreciation
+
+**The hard calls that paid off**
+- Decisions you were scared to make that turned out well
+- Times you said no to something that would have hurt the company
+
+**When to read it:** When you're doubting yourself before a board meeting, a hard conversation, a big pitch. The feeling isn't fact. The evidence file is.
diff --git a/skills/c-suite-founder-coach/references/leadership-growth.md b/skills/c-suite-founder-coach/references/leadership-growth.md
new file mode 100644
index 00000000..81fbd198
--- /dev/null
+++ b/skills/c-suite-founder-coach/references/leadership-growth.md
@@ -0,0 +1,178 @@
+# Leadership Growth Reference
+
+Frameworks for founder and executive leadership development.
+
+---
+
+## 1. The 5 Levels of Leadership (Maxwell)
+
+John Maxwell's model describes leadership development as a ladder. Most founders start at Level 2–3 and need to reach Level 4–5 to scale effectively.
+
+| Level | Name | People follow because... | What it looks like |
+|-------|------|--------------------------|-------------------|
+| 1 | Position | They have to (title/authority) | "Do this because I'm the CEO" |
+| 2 | Permission | They want to (relationship) | People choose to work with you beyond the job requirement |
+| 3 | Production | You produce results | Team rallies because you deliver; your track record gives credibility |
+| 4 | People Development | You develop others | You're multiplying leaders; your success is measured by others' growth |
+| 5 | Pinnacle | Who you are (reputation) | People follow because of what you've built and who you've become |
+
+**Most founders are at Level 3.** They got here by building and shipping. The path to scaling is Level 4: developing other leaders.
+
+**The Level 3 trap:** Production-focused founders attract doers, not leaders. They value results over growth. Their teams are effective but dependent. Every decision still goes through the founder.
+
+**The Level 4 shift:** Measure your success by how well your team succeeds without you. Your job is to make the people around you better.
+
+---
+
+## 2. Situational Leadership Model
+
+Ken Blanchard's model says effective leadership style shifts based on the person and the task — not the leader's preference.
+
+Four styles based on the follower's development level:
+
+| Development Level | Competence | Commitment | Leadership Style | What to do |
+|------------------|------------|------------|-----------------|------------|
+| D1 — Enthusiastic Beginner | Low | High | S1: Directing | High direction, low support. Tell them what to do. |
+| D2 — Disillusioned Learner | Low/Med | Low | S2: Coaching | High direction + high support. Teach and encourage. |
+| D3 — Capable but Cautious | Medium/High | Variable | S3: Supporting | Low direction, high support. Collaborate and encourage. |
+| D4 — Self-Reliant Achiever | High | High | S4: Delegating | Low direction, low support. Get out of the way. |
+
+**Common founder error:** Using the same leadership style with everyone. The founder who directs a D4 will frustrate them into leaving. The founder who delegates to a D1 will watch them fail.
+
+**Diagnosis before deciding:**
+Before determining your style, ask for each person + task:
+- How much do they know about this specific task? (Not in general — this task.)
+- How much do they want to do this specific task?
+
+These answers may surprise you. A senior engineer may be D4 on architecture and D1 on customer calls.
+
+---
+
+## 3. The Founder → CEO Transition
+
+The hardest leadership change most founders face, and nobody prepares them for it.
+
+### What changes
+
+**As a founder, you were judged on:**
+- What you personally built
+- How fast you moved
+- Your own output
+
+**As a CEO, you're judged on:**
+- What your team produced
+- How effectively you set direction
+- The quality of the people around you
+
+The skills that made you a great founder — doing, deciding, building — can actively work against you as a CEO.
+
+### The transition phases
+
+**Phase 1: Still doing (0–15 people)**
+You're right to be deep in the work. Speed requires it. Your personal output matters.
+Risk: Staying here too long.
+
+**Phase 2: Building around you (15–50 people)**
+You're hiring and starting to delegate. People do work you used to do.
+Challenge: Learning to trust output that doesn't look like yours.
+Failure mode: Hiring people and then redoing their work.
+
+**Phase 3: Leading through leaders (50–150 people)**
+You no longer know everything happening in the company. That's correct.
+Challenge: Managing people who manage people — twice removed from the work.
+Failure mode: Bypassing your managers to go direct (undermines them, creates chaos).
+
+**Phase 4: Setting the container (150+ people)**
+Your job is culture, strategy, and the senior leadership team. You're a CEO, not a senior contributor.
+Challenge: Staying relevant and strategic without getting lost in the weeds.
+Failure mode: Retreating to execution to feel productive.
+
+### The emotional reality
+
+Most founders describe the transition as:
+- A loss of identity ("I used to know everything that was happening")
+- A loss of control ("Decisions happen without me")
+- A loss of clarity ("Was I more effective before?")
+
+These are real losses, not just discomfort. Acknowledge them. Find identity in what the CEO role is, not what the founder role was.
+
+---
+
+## 4. Building Your Executive Team
+
+### When to hire your first executive
+
+Common question: "When do I need a VP/C-suite?"
+
+**Trigger signs:**
+- The function is failing and you can't fix it by working harder
+- You can't attract or develop talent in that function because you lack the expertise
+- The function is growing faster than you can lead it
+- You're making bad decisions in that domain because you don't have deep knowledge
+
+**Order of first executives:**
+Most companies hire in this order, but the right order depends on your archetype and what's breaking:
+1. First non-founder exec is usually Sales (VP Sales) or Engineering (VP Eng / CTO)
+2. Then COO/Operations when coordination becomes the bottleneck
+3. Then Finance (CFO) when fundraising or financial complexity demands it
+4. Then People/HR when hiring velocity and culture require dedicated ownership
+
+### How to onboard executives
+
+**The 30-60-90 plan:**
+- Day 1–30: Listen. Meet everyone. Learn the current state. No major decisions.
+- Day 31–60: Diagnose. What's working, what isn't, what's missing. Share findings.
+- Day 61–90: Act. Make changes. Start building systems. Establish their leadership presence.
+
+**The trust-building sequence:**
+Start with small, visible wins. Let them prove themselves in low-stakes situations before handing over high-stakes decisions.
+
+**The founder's role during exec onboarding:**
+- Provide context generously
+- Introduce them with genuine authority ("This is the decision-maker for X — go to them, not me")
+- Don't override their decisions publicly
+- Give feedback privately, not in front of their team
+
+**Failure mode:** Hiring a great executive and then making them feel like a senior employee. If you override every major decision, you don't have an executive — you have an expensive advisor.
+
+---
+
+## 5. Managing Your Board
+
+### The fundamental tension
+
+You work for the board. The board elected you. They can remove you. This is a governance reality, not a threat.
+
+And: You lead the company. The board sets governance and approves major decisions, but they're not running the business day-to-day. You are.
+
+**Healthy dynamic:** Board holds accountability; CEO holds authority. They're not adversarial — they're complementary.
+
+### The founder mistake
+
+Most founders either:
+1. **Over-inform:** Share every detail, create noise, invite micro-management
+2. **Under-inform:** Share only wins, board is surprised by problems, trust erodes
+
+Neither works. The goal is strategic partnership.
+
+### What the board actually needs
+
+- **Monthly written update:** Financial performance vs plan, key metrics, top 3 issues + proposed solutions, forward-looking risks. 1–2 pages.
+- **Quarterly board meeting:** Strategic discussion, not financial recap. They've read the update. Use the time for decisions and input.
+- **Real-time alerts:** Big bad news before the meeting. Never let board members be surprised by negative news they should have known earlier.
+
+### Managing board members individually
+
+Invest in 1:1 relationships with each board member between meetings. Understand what they care about. Use their expertise.
+
+Board members who feel informed and useful are your allies. Board members who feel blindsided or sidelined become difficult.
+
+**The pre-meeting call:** Before every board meeting, call each member individually. Preview the agenda, surface concerns, align on decisions. The meeting itself should have no surprises.
+
+### When the board challenges you
+
+"The board doesn't trust my judgment" is often really: "I haven't given them enough information to trust my judgment."
+
+Fix the transparency gap before assuming it's a political problem.
+
+**When the board is actually wrong:** Make the case clearly, once, with data. If they override you on something important and you can't accept it, that's a signal about fit. Founders get removed. It happens. Build board relationships before you need them to trust you on a hard call.
diff --git a/skills/campaign-analytics/SKILL.md b/skills/campaign-analytics/SKILL.md
new file mode 100644
index 00000000..d8376b29
--- /dev/null
+++ b/skills/campaign-analytics/SKILL.md
@@ -0,0 +1,228 @@
+---
+name: "campaign-analytics"
+description: Analyzes campaign performance with multi-touch attribution, funnel conversion analysis, and ROI calculation for marketing optimization. Use when analyzing marketing campaigns, ad performance, attribution models, conversion rates, or calculating marketing ROI, ROAS, CPA, and campaign metrics across channels.
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: marketing
+ domain: campaign-analytics
+ updated: 2026-02-06
+ python-tools: attribution_analyzer.py, funnel_analyzer.py, campaign_roi_calculator.py
+ tech-stack: marketing-analytics, attribution-modeling
+---
+
+# Campaign Analytics
+
+Production-grade campaign performance analysis with multi-touch attribution modeling, funnel conversion analysis, and ROI calculation. Three Python CLI tools provide deterministic, repeatable analytics using standard library only -- no external dependencies, no API calls, no ML models.
+
+---
+
+## Input Requirements
+
+All scripts accept a JSON file as positional input argument. See `assets/sample_campaign_data.json` for complete examples.
+
+### Attribution Analyzer
+
+```json
+{
+ "journeys": [
+ {
+ "journey_id": "j1",
+ "touchpoints": [
+ {"channel": "organic_search", "timestamp": "2025-10-01T10:00:00", "interaction": "click"},
+ {"channel": "email", "timestamp": "2025-10-05T14:30:00", "interaction": "open"},
+ {"channel": "paid_search", "timestamp": "2025-10-08T09:15:00", "interaction": "click"}
+ ],
+ "converted": true,
+ "revenue": 500.00
+ }
+ ]
+}
+```
+
+### Funnel Analyzer
+
+```json
+{
+ "funnel": {
+ "stages": ["Awareness", "Interest", "Consideration", "Intent", "Purchase"],
+ "counts": [10000, 5200, 2800, 1400, 420]
+ }
+}
+```
+
+### Campaign ROI Calculator
+
+```json
+{
+ "campaigns": [
+ {
+ "name": "Spring Email Campaign",
+ "channel": "email",
+ "spend": 5000.00,
+ "revenue": 25000.00,
+ "impressions": 50000,
+ "clicks": 2500,
+ "leads": 300,
+ "customers": 45
+ }
+ ]
+}
+```
+
+### Input Validation
+
+Before running scripts, verify your JSON is valid and matches the expected schema. Common errors:
+
+- **Missing required keys** (e.g., `journeys`, `funnel.stages`, `campaigns`) → script exits with a descriptive `KeyError`
+- **Mismatched array lengths** in funnel data (`stages` and `counts` must be the same length) → raises `ValueError`
+- **Non-numeric monetary values** in ROI data → raises `TypeError`
+
+Use `python -m json.tool your_file.json` to validate JSON syntax before passing it to any script.
+
+---
+
+## Output Formats
+
+All scripts support two output formats via the `--format` flag:
+
+- `--format text` (default): Human-readable tables and summaries for review
+- `--format json`: Machine-readable JSON for integrations and pipelines
+
+---
+
+## Typical Analysis Workflow
+
+For a complete campaign review, run the three scripts in sequence:
+
+```bash
+# Step 1 — Attribution: understand which channels drive conversions
+python scripts/attribution_analyzer.py campaign_data.json --model time-decay
+
+# Step 2 — Funnel: identify where prospects drop off on the path to conversion
+python scripts/funnel_analyzer.py funnel_data.json
+
+# Step 3 — ROI: calculate profitability and benchmark against industry standards
+python scripts/campaign_roi_calculator.py campaign_data.json
+```
+
+Use attribution results to identify top-performing channels, then focus funnel analysis on those channels' segments, and finally validate ROI metrics to prioritize budget reallocation.
+
+---
+
+## How to Use
+
+### Attribution Analysis
+
+```bash
+# Run all 5 attribution models
+python scripts/attribution_analyzer.py campaign_data.json
+
+# Run a specific model
+python scripts/attribution_analyzer.py campaign_data.json --model time-decay
+
+# JSON output for pipeline integration
+python scripts/attribution_analyzer.py campaign_data.json --format json
+
+# Custom time-decay half-life (default: 7 days)
+python scripts/attribution_analyzer.py campaign_data.json --model time-decay --half-life 14
+```
+
+### Funnel Analysis
+
+```bash
+# Basic funnel analysis
+python scripts/funnel_analyzer.py funnel_data.json
+
+# JSON output
+python scripts/funnel_analyzer.py funnel_data.json --format json
+```
+
+### Campaign ROI Calculation
+
+```bash
+# Calculate ROI metrics for all campaigns
+python scripts/campaign_roi_calculator.py campaign_data.json
+
+# JSON output
+python scripts/campaign_roi_calculator.py campaign_data.json --format json
+```
+
+---
+
+## Scripts
+
+### 1. attribution_analyzer.py
+
+Implements five industry-standard attribution models to allocate conversion credit across marketing channels:
+
+| Model | Description | Best For |
+|-------|-------------|----------|
+| First-Touch | 100% credit to first interaction | Brand awareness campaigns |
+| Last-Touch | 100% credit to last interaction | Direct response campaigns |
+| Linear | Equal credit to all touchpoints | Balanced multi-channel evaluation |
+| Time-Decay | More credit to recent touchpoints | Short sales cycles |
+| Position-Based | 40/20/40 split (first/middle/last) | Full-funnel marketing |
+
+### 2. funnel_analyzer.py
+
+Analyzes conversion funnels to identify bottlenecks and optimization opportunities:
+
+- Stage-to-stage conversion rates and drop-off percentages
+- Automatic bottleneck identification (largest absolute and relative drops)
+- Overall funnel conversion rate
+- Segment comparison when multiple segments are provided
+
+### 3. campaign_roi_calculator.py
+
+Calculates comprehensive ROI metrics with industry benchmarking:
+
+- **ROI**: Return on investment percentage
+- **ROAS**: Return on ad spend ratio
+- **CPA**: Cost per acquisition
+- **CPL**: Cost per lead
+- **CAC**: Customer acquisition cost
+- **CTR**: Click-through rate
+- **CVR**: Conversion rate (leads to customers)
+- Flags underperforming campaigns against industry benchmarks
+
+---
+
+## Reference Guides
+
+| Guide | Location | Purpose |
+|-------|----------|---------|
+| Attribution Models Guide | `references/attribution-models-guide.md` | Deep dive into 5 models with formulas, pros/cons, selection criteria |
+| Campaign Metrics Benchmarks | `references/campaign-metrics-benchmarks.md` | Industry benchmarks by channel and vertical for CTR, CPC, CPM, CPA, ROAS |
+| Funnel Optimization Framework | `references/funnel-optimization-framework.md` | Stage-by-stage optimization strategies, common bottlenecks, best practices |
+
+---
+
+## Best Practices
+
+1. **Use multiple attribution models** -- Compare at least 3 models to triangulate channel value; no single model tells the full story.
+2. **Set appropriate lookback windows** -- Match your time-decay half-life to your average sales cycle length.
+3. **Segment your funnels** -- Compare segments (channel, cohort, geography) to identify performance drivers.
+4. **Benchmark against your own history first** -- Industry benchmarks provide context, but historical data is the most relevant comparison.
+5. **Run ROI analysis at regular intervals** -- Weekly for active campaigns, monthly for strategic review.
+6. **Include all costs** -- Factor in creative, tooling, and labor costs alongside media spend for accurate ROI.
+7. **Document A/B tests rigorously** -- Use the provided template to ensure statistical validity and clear decision criteria.
+
+---
+
+## Limitations
+
+- **No statistical significance testing** -- Scripts provide descriptive metrics only; p-value calculations require external tools.
+- **Standard library only** -- No advanced statistical libraries. Suitable for most campaign sizes but not optimized for datasets exceeding 100K journeys.
+- **Offline analysis** -- Scripts analyze static JSON snapshots; no real-time data connections or API integrations.
+- **Single-currency** -- All monetary values assumed to be in the same currency; no currency conversion support.
+- **Simplified time-decay** -- Exponential decay based on configurable half-life; does not account for weekday/weekend or seasonal patterns.
+- **No cross-device tracking** -- Attribution operates on provided journey data as-is; cross-device identity resolution must be handled upstream.
+
+## Related Skills
+
+- **analytics-tracking**: For setting up tracking. NOT for analyzing data (that's this skill).
+- **ab-test-setup**: For designing experiments to test what analytics reveals.
+- **marketing-ops**: For routing insights to the right execution skill.
+- **paid-ads**: For optimizing ad spend based on analytics findings.
diff --git a/skills/campaign-analytics/_meta.json b/skills/campaign-analytics/_meta.json
new file mode 100644
index 00000000..9f50557c
--- /dev/null
+++ b/skills/campaign-analytics/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "campaign-analytics",
+ "displayName": "Campaign Analytics",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773075341589,
+ "commit": "https://github.com/openclaw/skills/commit/b2cac15fdc5b3ae74eda78b302253a6d531fbc92"
+ },
+ "history": []
+}
diff --git a/skills/campaign-analytics/assets/ab_test_template.md b/skills/campaign-analytics/assets/ab_test_template.md
new file mode 100644
index 00000000..c7ea164e
--- /dev/null
+++ b/skills/campaign-analytics/assets/ab_test_template.md
@@ -0,0 +1,130 @@
+# A/B Test Analysis
+
+**Test Name:** [Descriptive test name]
+**Test ID:** [Internal tracking ID]
+**Date:** [Start Date] - [End Date]
+**Status:** [Planning / Running / Complete / Inconclusive]
+
+---
+
+## Hypothesis
+
+**If** [we change X],
+**then** [Y will happen],
+**because** [rationale based on data or insight].
+
+---
+
+## Test Design
+
+| Parameter | Detail |
+|-----------|--------|
+| **Variable Tested** | [What is being changed] |
+| **Control (A)** | [Description of control variant] |
+| **Variant (B)** | [Description of test variant] |
+| **Primary Metric** | [The main metric being measured] |
+| **Secondary Metrics** | [Additional metrics to monitor] |
+| **Traffic Split** | [50/50, 70/30, etc.] |
+| **Minimum Sample Size** | [Required sample per variant for statistical significance] |
+| **Minimum Detectable Effect** | [Smallest meaningful difference, e.g., 5% lift] |
+| **Confidence Level** | [95% or 99%] |
+| **Expected Duration** | [X days/weeks based on traffic and sample size] |
+
+---
+
+## Targeting
+
+| Criterion | Value |
+|-----------|-------|
+| **Audience** | [Who sees the test] |
+| **Channel** | [Where the test runs] |
+| **Device** | [All / Desktop / Mobile] |
+| **Geography** | [Regions included] |
+| **Exclusions** | [Who is excluded and why] |
+
+---
+
+## Results
+
+### Primary Metric: [Metric Name]
+
+| Variant | Sample Size | Conversions | Rate | Lift vs Control |
+|---------|------------|-------------|------|----------------|
+| Control (A) | | | % | - |
+| Variant (B) | | | % | % |
+
+**Statistical Significance:** [Yes/No] at [X]% confidence
+**P-value:** [X.XXX]
+
+### Secondary Metrics
+
+| Metric | Control (A) | Variant (B) | Lift | Significant? |
+|--------|------------|-------------|------|-------------|
+| [Metric 1] | | | % | [Yes/No] |
+| [Metric 2] | | | % | [Yes/No] |
+| [Metric 3] | | | % | [Yes/No] |
+
+---
+
+## Segment Analysis
+
+| Segment | Control Rate | Variant Rate | Lift | Notes |
+|---------|-------------|-------------|------|-------|
+| Desktop | % | % | % | |
+| Mobile | % | % | % | |
+| New Visitors | % | % | % | |
+| Returning Visitors | % | % | % | |
+| [Custom Segment] | % | % | % | |
+
+---
+
+## Revenue Impact Estimate
+
+| Metric | Value |
+|--------|-------|
+| **Projected Annual Lift** | [X]% |
+| **Projected Additional Revenue** | $[X] |
+| **Projected Additional Conversions** | [X] |
+| **Confidence in Estimate** | [High/Medium/Low] |
+
+---
+
+## Decision
+
+**Winner:** [Control / Variant / Inconclusive]
+
+**Rationale:** [Why this decision was made, citing specific metrics and statistical significance]
+
+**Implementation Plan:**
+- [ ] [Step 1: e.g., Roll out variant to 100% of traffic]
+- [ ] [Step 2: e.g., Update creative assets across campaigns]
+- [ ] [Step 3: e.g., Monitor for X days post-implementation]
+- [ ] [Step 4: e.g., Document learnings in knowledge base]
+
+---
+
+## Learnings
+
+**What we learned:**
+1. [Key learning 1]
+2. [Key learning 2]
+3. [Key learning 3]
+
+**Follow-up tests to consider:**
+1. [Next test idea based on results]
+2. [Next test idea based on results]
+
+---
+
+## Quality Checks
+
+- [ ] Sample size reached minimum threshold
+- [ ] Test ran for at least 1 full business cycle (7 days minimum)
+- [ ] No external factors (holidays, outages, promotions) affected results
+- [ ] Segments were balanced between variants
+- [ ] No sample ratio mismatch (SRM) detected
+- [ ] Results reviewed by at least 2 team members
+
+---
+
+*Template from campaign-analytics skill. Statistical significance calculations require external tools (e.g., online calculators or scipy).*
diff --git a/skills/campaign-analytics/assets/campaign_report_template.md b/skills/campaign-analytics/assets/campaign_report_template.md
new file mode 100644
index 00000000..88f2a0e2
--- /dev/null
+++ b/skills/campaign-analytics/assets/campaign_report_template.md
@@ -0,0 +1,141 @@
+# Campaign Performance Report
+
+**Report Period:** [Start Date] - [End Date]
+**Prepared By:** [Name]
+**Date:** [Report Date]
+
+---
+
+## Executive Summary
+
+[2-3 sentence summary of overall campaign performance, key wins, and areas of concern.]
+
+---
+
+## Portfolio Overview
+
+| Metric | This Period | Previous Period | Change |
+|--------|-----------|----------------|--------|
+| Total Spend | $ | $ | % |
+| Total Revenue | $ | $ | % |
+| Total Profit | $ | $ | % |
+| Portfolio ROI | % | % | pp |
+| Portfolio ROAS | x | x | % |
+| Total Leads | | | % |
+| Total Customers | | | % |
+| Blended CPA | $ | $ | % |
+| Blended CPL | $ | $ | % |
+
+---
+
+## Channel Performance
+
+| Channel | Spend | Revenue | ROI | ROAS | CPA | Leads | Customers |
+|---------|-------|---------|-----|------|-----|-------|-----------|
+| Email | $ | $ | % | x | $ | | |
+| Paid Search | $ | $ | % | x | $ | | |
+| Paid Social | $ | $ | % | x | $ | | |
+| Display | $ | $ | % | x | $ | | |
+| Organic | $ | $ | % | x | $ | | |
+| **Total** | **$** | **$** | **%** | **x** | **$** | | |
+
+---
+
+## Top Performing Campaigns
+
+### 1. [Campaign Name]
+- **Channel:** [Channel]
+- **Spend:** $[Amount] | **Revenue:** $[Amount] | **ROI:** [X]%
+- **Key Success Factor:** [What made this campaign successful]
+
+### 2. [Campaign Name]
+- **Channel:** [Channel]
+- **Spend:** $[Amount] | **Revenue:** $[Amount] | **ROI:** [X]%
+- **Key Success Factor:** [What made this campaign successful]
+
+### 3. [Campaign Name]
+- **Channel:** [Channel]
+- **Spend:** $[Amount] | **Revenue:** $[Amount] | **ROI:** [X]%
+- **Key Success Factor:** [What made this campaign successful]
+
+---
+
+## Underperforming Campaigns
+
+### [Campaign Name]
+- **Channel:** [Channel]
+- **Issue:** [Description of underperformance]
+- **Benchmark Comparison:** [How it compares to benchmarks]
+- **Recommended Action:** [Specific action to take]
+
+### [Campaign Name]
+- **Channel:** [Channel]
+- **Issue:** [Description of underperformance]
+- **Benchmark Comparison:** [How it compares to benchmarks]
+- **Recommended Action:** [Specific action to take]
+
+---
+
+## Attribution Analysis
+
+| Channel | First-Touch | Last-Touch | Linear | Time-Decay | Position-Based |
+|---------|------------|------------|--------|------------|----------------|
+| [Channel 1] | $[X] | $[X] | $[X] | $[X] | $[X] |
+| [Channel 2] | $[X] | $[X] | $[X] | $[X] | $[X] |
+| [Channel 3] | $[X] | $[X] | $[X] | $[X] | $[X] |
+
+**Key Insight:** [What does the attribution analysis tell us about channel value that single-model analysis would miss?]
+
+---
+
+## Funnel Analysis
+
+| Stage | Count | Conversion Rate | Drop-off | vs. Previous Period |
+|-------|-------|----------------|----------|-------------------|
+| Awareness | | - | - | % |
+| Interest | | % | % | pp |
+| Consideration | | % | % | pp |
+| Intent | | % | % | pp |
+| Purchase | | % | % | pp |
+
+**Overall Funnel Conversion:** [X]%
+**Primary Bottleneck:** [Stage transition with largest drop-off]
+**Recommended Focus:** [What to optimize next]
+
+---
+
+## Budget Allocation Recommendations
+
+Based on this period's performance data:
+
+| Channel | Current Allocation | Recommended Allocation | Rationale |
+|---------|-------------------|----------------------|-----------|
+| [Channel] | [X]% ($[X]) | [X]% ($[X]) | [Reason] |
+| [Channel] | [X]% ($[X]) | [X]% ($[X]) | [Reason] |
+| [Channel] | [X]% ($[X]) | [X]% ($[X]) | [Reason] |
+
+---
+
+## Action Items
+
+| Priority | Action | Owner | Deadline | Expected Impact |
+|----------|--------|-------|----------|----------------|
+| High | [Action] | [Name] | [Date] | [Impact] |
+| High | [Action] | [Name] | [Date] | [Impact] |
+| Medium | [Action] | [Name] | [Date] | [Impact] |
+| Low | [Action] | [Name] | [Date] | [Impact] |
+
+---
+
+## Next Period Goals
+
+| Metric | Current | Target | Strategy |
+|--------|---------|--------|----------|
+| Portfolio ROI | [X]% | [X]% | [How] |
+| ROAS | [X]x | [X]x | [How] |
+| CPA | $[X] | $[X] | [How] |
+| Lead Volume | [X] | [X] | [How] |
+
+---
+
+*Report generated using campaign-analytics toolkit. Data source: [Source system/platform].*
diff --git a/skills/campaign-analytics/assets/channel_comparison_template.md b/skills/campaign-analytics/assets/channel_comparison_template.md
new file mode 100644
index 00000000..c021eeee
--- /dev/null
+++ b/skills/campaign-analytics/assets/channel_comparison_template.md
@@ -0,0 +1,158 @@
+# Channel Performance Comparison
+
+**Period:** [Start Date] - [End Date]
+**Compared Against:** [Previous period / Industry benchmarks / Both]
+**Prepared By:** [Name]
+
+---
+
+## Summary
+
+[1-2 sentence overview: which channels are performing best, which need attention, and the overall channel mix health.]
+
+---
+
+## Channel Scorecard
+
+| Channel | Spend | Revenue | Profit | ROI | ROAS | CTR | CPA | CPL | Grade |
+|---------|-------|---------|--------|-----|------|-----|-----|-----|-------|
+| Email | $ | $ | $ | % | x | % | $ | $ | [A-F] |
+| Paid Search | $ | $ | $ | % | x | % | $ | $ | [A-F] |
+| Paid Social | $ | $ | $ | % | x | % | $ | $ | [A-F] |
+| Display | $ | $ | $ | % | x | % | $ | $ | [A-F] |
+| Organic Search | $ | $ | $ | % | x | % | $ | $ | [A-F] |
+| Organic Social | $ | $ | $ | % | x | % | $ | $ | [A-F] |
+| Referral | $ | $ | $ | % | x | % | $ | $ | [A-F] |
+| Direct | $ | $ | $ | % | x | % | $ | $ | [A-F] |
+| **Total** | **$** | **$** | **$** | **%** | **x** | **%** | **$** | **$** | |
+
+**Grading Scale:**
+- A: Exceeds all benchmarks
+- B: Meets or exceeds target benchmarks
+- C: Between low and target benchmarks
+- D: Below low benchmark on 1+ key metrics
+- F: Underperforming on multiple metrics or unprofitable
+
+---
+
+## Channel Deep Dives
+
+### [Channel Name]
+
+**Performance Summary:** [1-2 sentences]
+
+| Metric | Actual | Target | Benchmark | vs. Target | vs. Benchmark |
+|--------|--------|--------|-----------|-----------|---------------|
+| Spend | $ | $ | - | % | - |
+| Revenue | $ | $ | - | % | - |
+| ROI | % | % | % | pp | pp |
+| ROAS | x | x | x | % | % |
+| CTR | % | % | % | pp | pp |
+| CPA | $ | $ | $ | % | % |
+| CPL | $ | $ | $ | % | % |
+| CPC | $ | $ | $ | % | % |
+
+**Trend (Last 3 Periods):**
+
+| Period | Spend | Revenue | ROI | ROAS | Key Event |
+|--------|-------|---------|-----|------|-----------|
+| [Period 1] | $ | $ | % | x | [Note] |
+| [Period 2] | $ | $ | % | x | [Note] |
+| [Current] | $ | $ | % | x | [Note] |
+
+**Assessment:** [Improving / Stable / Declining]
+
+**Action Items:**
+1. [Specific action for this channel]
+2. [Specific action for this channel]
+
+---
+
+[Repeat deep dive section for each channel]
+
+---
+
+## Attribution View
+
+How each channel is valued under different attribution models:
+
+| Channel | First-Touch | Last-Touch | Linear | Time-Decay | Position-Based |
+|---------|------------|------------|--------|------------|----------------|
+| [Channel 1] | $ (X%) | $ (X%) | $ (X%) | $ (X%) | $ (X%) |
+| [Channel 2] | $ (X%) | $ (X%) | $ (X%) | $ (X%) | $ (X%) |
+| [Channel 3] | $ (X%) | $ (X%) | $ (X%) | $ (X%) | $ (X%) |
+
+**Insight:** [Which channels are over/undervalued by single-touch models?]
+
+---
+
+## Funnel Performance by Channel
+
+| Stage | [Ch 1] | [Ch 2] | [Ch 3] | [Ch 4] | Overall |
+|-------|--------|--------|--------|--------|---------|
+| Awareness | [Count] | [Count] | [Count] | [Count] | [Count] |
+| Interest | [Rate]% | [Rate]% | [Rate]% | [Rate]% | [Rate]% |
+| Consideration | [Rate]% | [Rate]% | [Rate]% | [Rate]% | [Rate]% |
+| Intent | [Rate]% | [Rate]% | [Rate]% | [Rate]% | [Rate]% |
+| Purchase | [Rate]% | [Rate]% | [Rate]% | [Rate]% | [Rate]% |
+| **Overall** | **[Rate]%** | **[Rate]%** | **[Rate]%** | **[Rate]%** | **[Rate]%** |
+
+**Best Funnel:** [Channel with highest overall conversion rate]
+**Biggest Bottleneck:** [Channel + stage transition with worst drop-off]
+
+---
+
+## Budget Allocation Analysis
+
+### Current vs. Optimal Allocation
+
+| Channel | Current % | Current $ | Recommended % | Recommended $ | Rationale |
+|---------|----------|-----------|--------------|---------------|-----------|
+| [Channel] | % | $ | % | $ | [Why] |
+| [Channel] | % | $ | % | $ | [Why] |
+| [Channel] | % | $ | % | $ | [Why] |
+| [Channel] | % | $ | % | $ | [Why] |
+| **Total** | **100%** | **$** | **100%** | **$** | |
+
+### Reallocation Impact Estimate
+
+| Scenario | Projected Revenue | Projected ROI | Change vs Current |
+|----------|------------------|---------------|-------------------|
+| Current allocation | $ | % | - |
+| Recommended allocation | $ | % | +% |
+| Aggressive growth | $ | % | +% |
+| Cost optimization | $ | % | +% |
+
+---
+
+## Competitive Context
+
+| Metric | Our Performance | Industry Average | Gap |
+|--------|----------------|-----------------|-----|
+| Channel Mix Diversity | [X channels active] | [X channels] | |
+| Overall ROAS | [X]x | [X]x | |
+| Paid vs Organic Split | [X/X]% | [X/X]% | |
+| Digital vs Traditional | [X/X]% | [X/X]% | |
+
+---
+
+## Recommendations
+
+### Immediate Actions (This Week)
+
+1. **[Action]** -- [Expected impact], [Owner]
+2. **[Action]** -- [Expected impact], [Owner]
+
+### Short-Term (This Month)
+
+1. **[Action]** -- [Expected impact], [Owner]
+2. **[Action]** -- [Expected impact], [Owner]
+
+### Strategic (This Quarter)
+
+1. **[Action]** -- [Expected impact], [Owner]
+2. **[Action]** -- [Expected impact], [Owner]
+
+---
+
+*Template from campaign-analytics skill. Populate with data from attribution_analyzer.py, funnel_analyzer.py, and campaign_roi_calculator.py.*
diff --git a/skills/campaign-analytics/assets/expected_output.json b/skills/campaign-analytics/assets/expected_output.json
new file mode 100644
index 00000000..13ec19e0
--- /dev/null
+++ b/skills/campaign-analytics/assets/expected_output.json
@@ -0,0 +1,110 @@
+{
+ "_description": "Expected output from running the 3 scripts against sample_campaign_data.json with --format json",
+
+ "attribution_analyzer": {
+ "_command": "python scripts/attribution_analyzer.py assets/sample_campaign_data.json --format json",
+ "summary": {
+ "total_journeys": 8,
+ "converted_journeys": 6,
+ "conversion_rate": 75.0,
+ "total_revenue": 3700.0,
+ "channels_observed": [
+ "direct", "display", "email", "organic_search",
+ "organic_social", "paid_search", "paid_social", "referral"
+ ]
+ },
+ "models": {
+ "first-touch": {
+ "organic_search": 700.0,
+ "paid_social": 1200.0,
+ "display": 350.0,
+ "organic_social": 800.0,
+ "referral": 650.0
+ },
+ "last-touch": {
+ "paid_search": 1500.0,
+ "direct": 2000.0,
+ "organic_search": 200.0
+ },
+ "linear": {
+ "organic_search": 666.67,
+ "email": 1003.33,
+ "paid_search": 718.33,
+ "paid_social": 300.0,
+ "direct": 460.0,
+ "display": 175.0,
+ "organic_social": 160.0,
+ "referral": 216.67
+ },
+ "time-decay": {
+ "organic_search": 582.38,
+ "email": 1053.68,
+ "paid_search": 881.03,
+ "paid_social": 178.4,
+ "direct": 638.82,
+ "display": 140.62,
+ "organic_social": 78.48,
+ "referral": 146.59
+ },
+ "position-based": {
+ "organic_search": 520.0,
+ "paid_search": 688.33,
+ "email": 456.67,
+ "paid_social": 480.0,
+ "direct": 800.0,
+ "display": 175.0,
+ "organic_social": 320.0,
+ "referral": 260.0
+ }
+ }
+ },
+
+ "funnel_analyzer": {
+ "_command": "python scripts/funnel_analyzer.py assets/sample_campaign_data.json --format json",
+ "_note": "Uses segment comparison mode since 'segments' key is present in the data",
+ "rankings": [
+ {"rank": 1, "segment": "organic", "overall_conversion_rate": 5.6, "total_entries": 5000, "total_conversions": 280},
+ {"rank": 2, "segment": "paid", "overall_conversion_rate": 3.0, "total_entries": 3000, "total_conversions": 90},
+ {"rank": 3, "segment": "email", "overall_conversion_rate": 2.5, "total_entries": 2000, "total_conversions": 50}
+ ],
+ "key_findings": {
+ "all_segments_bottleneck_absolute": "Awareness -> Interest",
+ "all_segments_bottleneck_relative": "Intent -> Purchase",
+ "best_performing_segment": "organic (5.6% overall conversion)",
+ "worst_performing_segment": "email (2.5% overall conversion)"
+ }
+ },
+
+ "campaign_roi_calculator": {
+ "_command": "python scripts/campaign_roi_calculator.py assets/sample_campaign_data.json --format json",
+ "portfolio_summary": {
+ "total_campaigns": 5,
+ "total_spend": 34000.0,
+ "total_revenue": 99000.0,
+ "total_profit": 65000.0,
+ "portfolio_roi_pct": 191.18,
+ "portfolio_roas": 2.91,
+ "blended_ctr_pct": 1.04,
+ "blended_cpl": 27.64,
+ "blended_cpa": 161.9,
+ "top_performer": "Spring Email Campaign",
+ "underperforming_campaigns": [
+ "Spring Email Campaign",
+ "Facebook Awareness Q1",
+ "LinkedIn B2B Outreach"
+ ]
+ },
+ "channel_summary": {
+ "email": {"spend": 5000.0, "revenue": 25000.0, "roi_pct": 400.0, "roas": 5.0},
+ "paid_search": {"spend": 12000.0, "revenue": 48000.0, "roi_pct": 300.0, "roas": 4.0},
+ "paid_social": {"spend": 14000.0, "revenue": 17000.0, "roi_pct": 21.43, "roas": 1.21},
+ "display": {"spend": 3000.0, "revenue": 9000.0, "roi_pct": 200.0, "roas": 3.0}
+ },
+ "key_findings": {
+ "most_profitable_channel": "paid_search ($36,000 profit)",
+ "highest_roas_channel": "email (5.0x ROAS)",
+ "unprofitable_campaign": "LinkedIn B2B Outreach (-$1,000 loss)",
+ "best_ctr": "Spring Email Campaign (5.0%)"
+ }
+ }
+}
diff --git a/skills/campaign-analytics/assets/sample_campaign_data.json b/skills/campaign-analytics/assets/sample_campaign_data.json
new file mode 100644
index 00000000..1c9c0619
--- /dev/null
+++ b/skills/campaign-analytics/assets/sample_campaign_data.json
@@ -0,0 +1,151 @@
+{
+ "journeys": [
+ {
+ "journey_id": "j001",
+ "touchpoints": [
+ {"channel": "organic_search", "timestamp": "2025-10-01T10:00:00", "interaction": "click"},
+ {"channel": "email", "timestamp": "2025-10-05T14:30:00", "interaction": "open"},
+ {"channel": "paid_search", "timestamp": "2025-10-08T09:15:00", "interaction": "click"}
+ ],
+ "converted": true,
+ "revenue": 500.00
+ },
+ {
+ "journey_id": "j002",
+ "touchpoints": [
+ {"channel": "paid_social", "timestamp": "2025-10-02T11:00:00", "interaction": "click"},
+ {"channel": "organic_search", "timestamp": "2025-10-06T16:45:00", "interaction": "click"},
+ {"channel": "email", "timestamp": "2025-10-09T08:00:00", "interaction": "click"},
+ {"channel": "direct", "timestamp": "2025-10-10T13:20:00", "interaction": "visit"}
+ ],
+ "converted": true,
+ "revenue": 1200.00
+ },
+ {
+ "journey_id": "j003",
+ "touchpoints": [
+ {"channel": "display", "timestamp": "2025-10-03T09:30:00", "interaction": "view"},
+ {"channel": "paid_search", "timestamp": "2025-10-07T10:00:00", "interaction": "click"}
+ ],
+ "converted": true,
+ "revenue": 350.00
+ },
+ {
+ "journey_id": "j004",
+ "touchpoints": [
+ {"channel": "organic_social", "timestamp": "2025-10-01T08:00:00", "interaction": "click"},
+ {"channel": "email", "timestamp": "2025-10-04T12:00:00", "interaction": "click"},
+ {"channel": "paid_search", "timestamp": "2025-10-08T14:00:00", "interaction": "click"},
+ {"channel": "email", "timestamp": "2025-10-11T09:00:00", "interaction": "click"},
+ {"channel": "direct", "timestamp": "2025-10-12T16:00:00", "interaction": "visit"}
+ ],
+ "converted": true,
+ "revenue": 800.00
+ },
+ {
+ "journey_id": "j005",
+ "touchpoints": [
+ {"channel": "paid_social", "timestamp": "2025-10-05T10:00:00", "interaction": "click"},
+ {"channel": "display", "timestamp": "2025-10-08T11:30:00", "interaction": "view"}
+ ],
+ "converted": false,
+ "revenue": 0
+ },
+ {
+ "journey_id": "j006",
+ "touchpoints": [
+ {"channel": "referral", "timestamp": "2025-10-06T14:00:00", "interaction": "click"},
+ {"channel": "email", "timestamp": "2025-10-10T09:30:00", "interaction": "click"},
+ {"channel": "paid_search", "timestamp": "2025-10-13T11:00:00", "interaction": "click"}
+ ],
+ "converted": true,
+ "revenue": 650.00
+ },
+ {
+ "journey_id": "j007",
+ "touchpoints": [
+ {"channel": "organic_search", "timestamp": "2025-10-04T08:30:00", "interaction": "click"}
+ ],
+ "converted": true,
+ "revenue": 200.00
+ },
+ {
+ "journey_id": "j008",
+ "touchpoints": [
+ {"channel": "paid_social", "timestamp": "2025-10-07T13:00:00", "interaction": "click"},
+ {"channel": "organic_search", "timestamp": "2025-10-09T10:00:00", "interaction": "click"},
+ {"channel": "email", "timestamp": "2025-10-12T15:00:00", "interaction": "click"}
+ ],
+ "converted": false,
+ "revenue": 0
+ }
+ ],
+ "funnel": {
+ "stages": ["Awareness", "Interest", "Consideration", "Intent", "Purchase"],
+ "counts": [10000, 5200, 2800, 1400, 420]
+ },
+ "segments": {
+ "organic": {
+ "counts": [5000, 2800, 1600, 850, 280]
+ },
+ "paid": {
+ "counts": [3000, 1500, 750, 350, 90]
+ },
+ "email": {
+ "counts": [2000, 900, 450, 200, 50]
+ }
+ },
+ "stages": ["Awareness", "Interest", "Consideration", "Intent", "Purchase"],
+ "campaigns": [
+ {
+ "name": "Spring Email Campaign",
+ "channel": "email",
+ "spend": 5000.00,
+ "revenue": 25000.00,
+ "impressions": 50000,
+ "clicks": 2500,
+ "leads": 300,
+ "customers": 45
+ },
+ {
+ "name": "Google Search - Brand",
+ "channel": "paid_search",
+ "spend": 12000.00,
+ "revenue": 48000.00,
+ "impressions": 200000,
+ "clicks": 8000,
+ "leads": 600,
+ "customers": 120
+ },
+ {
+ "name": "Facebook Awareness Q1",
+ "channel": "paid_social",
+ "spend": 8000.00,
+ "revenue": 12000.00,
+ "impressions": 500000,
+ "clicks": 5000,
+ "leads": 200,
+ "customers": 25
+ },
+ {
+ "name": "Display Retargeting",
+ "channel": "display",
+ "spend": 3000.00,
+ "revenue": 9000.00,
+ "impressions": 800000,
+ "clicks": 1200,
+ "leads": 80,
+ "customers": 15
+ },
+ {
+ "name": "LinkedIn B2B Outreach",
+ "channel": "paid_social",
+ "spend": 6000.00,
+ "revenue": 5000.00,
+ "impressions": 120000,
+ "clicks": 600,
+ "leads": 50,
+ "customers": 5
+ }
+ ]
+}
diff --git a/skills/campaign-analytics/references/attribution-models-guide.md b/skills/campaign-analytics/references/attribution-models-guide.md
new file mode 100644
index 00000000..f9a60cd4
--- /dev/null
+++ b/skills/campaign-analytics/references/attribution-models-guide.md
@@ -0,0 +1,285 @@
+# Attribution Models Guide
+
+Comprehensive reference for multi-touch attribution modeling in marketing analytics. This guide covers the five standard attribution models, their mathematical foundations, selection criteria, and practical application guidelines.
+
+---
+
+## Overview
+
+Attribution modeling answers the question: **Which marketing touchpoints deserve credit for conversions?** When a customer interacts with multiple channels before converting, attribution models distribute conversion credit across those touchpoints using different rules.
+
+No single model is "correct." Each reveals different aspects of channel performance. Best practice is to run multiple models and compare results to build a complete picture.
+
+---
+
+## Model 1: First-Touch Attribution
+
+### How It Works
+
+All conversion credit (100%) goes to the first touchpoint in the customer journey.
+
+### Formula
+
+```
+Credit(channel) = Revenue * 1.0 (if channel is first touchpoint)
+Credit(channel) = 0 (otherwise)
+```
+
+### When to Use
+
+- **Brand awareness campaigns**: Measures which channels bring new prospects into the funnel
+- **Top-of-funnel optimization**: Identifies the best channels for initial discovery
+- **New market entry**: Evaluating which channels generate first contact in new segments
+
+### Pros
+
+- Simple to understand and implement
+- Clearly identifies awareness-driving channels
+- Useful for budget allocation toward customer acquisition
+
+### Cons
+
+- Ignores all touchpoints after the first
+- Overvalues awareness channels, undervalues conversion channels
+- Does not reflect the reality of multi-touch customer journeys
+
+### Best For
+
+Marketing teams focused on expanding reach and entering new markets where understanding initial discovery channels is the priority.
+
+---
+
+## Model 2: Last-Touch Attribution
+
+### How It Works
+
+All conversion credit (100%) goes to the last touchpoint before conversion.
+
+### Formula
+
+```
+Credit(channel) = Revenue * 1.0 (if channel is last touchpoint)
+Credit(channel) = 0 (otherwise)
+```
+
+### When to Use
+
+- **Direct response campaigns**: Measures which channels close deals
+- **Bottom-of-funnel optimization**: Identifies the most effective conversion channels
+- **Short sales cycles**: When customers typically convert within 1-2 interactions
+
+### Pros
+
+- Simple to implement (default in many analytics platforms)
+- Highlights channels that directly drive conversions
+- Useful for performance marketing optimization
+
+### Cons
+
+- Ignores all touchpoints before the last
+- Overvalues conversion channels, undervalues awareness channels
+- Can lead to cutting awareness spending that actually feeds the pipeline
+
+### Best For
+
+Performance marketing teams running direct-response campaigns where the final interaction is the primary lever.
+
+---
+
+## Model 3: Linear Attribution
+
+### How It Works
+
+Conversion credit is split equally across all touchpoints in the journey.
+
+### Formula
+
+```
+Credit(channel) = Revenue / N (for each of N touchpoints)
+```
+
+### When to Use
+
+- **Balanced multi-channel evaluation**: When all touchpoints are considered equally valuable
+- **Long sales cycles**: Where multiple interactions are required
+- **Content marketing**: Where each piece of content plays a role in nurturing
+
+### Pros
+
+- Fair distribution across all channels
+- Recognizes the contribution of every touchpoint
+- Good starting point for teams new to multi-touch attribution
+
+### Cons
+
+- Treats all touchpoints equally, which rarely reflects reality
+- Does not account for the relative importance of different positions in the journey
+- Can dilute the signal of truly impactful touchpoints
+
+### Best For
+
+Teams running consistent multi-channel campaigns where every touchpoint is intentionally designed to contribute to conversion.
+
+---
+
+## Model 4: Time-Decay Attribution
+
+### How It Works
+
+Touchpoints closer to conversion receive exponentially more credit. Uses a half-life parameter: a touchpoint occurring one half-life before conversion gets 50% of the credit of the converting touchpoint.
+
+### Formula
+
+```
+Weight(touchpoint) = e^(-lambda * days_before_conversion)
+
+where lambda = ln(2) / half_life_days
+
+Credit(channel) = Revenue * (Weight / Sum_of_all_weights)
+```
+
+### Configurable Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| half_life_days | 7 | Days for weight to decay by 50% |
+
+### Guidance on Half-Life Selection
+
+| Sales Cycle Length | Recommended Half-Life |
+|-------------------|----------------------|
+| 1-3 days (impulse) | 1-2 days |
+| 1-2 weeks (considered) | 5-7 days |
+| 1-3 months (B2B) | 14-21 days |
+| 3-6 months (enterprise) | 30-45 days |
+| 6-12 months (complex B2B) | 60-90 days |
+
+### When to Use
+
+- **Short-to-medium sales cycles**: Where recent interactions are more influential
+- **Promotional campaigns**: Where urgency and recency matter
+- **E-commerce**: Where the last few interactions before purchase are most impactful
+
+### Pros
+
+- Accounts for recency, which aligns with many buying behaviors
+- More sophisticated than first/last-touch
+- Configurable half-life allows tuning to specific business contexts
+
+### Cons
+
+- May undervalue early-stage awareness that planted the seed
+- Half-life selection is subjective and requires testing
+- More complex to explain to stakeholders
+
+### Best For
+
+E-commerce and B2C companies with identifiable sales cycles where recent interactions carry more decision weight.
+
+---
+
+## Model 5: Position-Based Attribution (U-Shaped)
+
+### How It Works
+
+40% of credit goes to the first touchpoint, 40% to the last touchpoint, and the remaining 20% is split equally among middle touchpoints.
+
+### Formula
+
+```
+Credit(first_channel) = Revenue * 0.40
+Credit(last_channel) = Revenue * 0.40
+Credit(middle_channel) = Revenue * 0.20 / (N - 2) (for each middle touchpoint)
+
+Special cases:
+ - 1 touchpoint: 100% credit
+ - 2 touchpoints: 50% each
+```
+
+### When to Use
+
+- **Full-funnel marketing**: Values both awareness (first) and conversion (last)
+- **Mature marketing programs**: With established multi-channel strategies
+- **B2B marketing**: Where both lead generation and deal closure are distinct priorities
+
+### Pros
+
+- Recognizes the importance of first and last interactions
+- Still gives credit to middle nurturing touchpoints
+- Provides a balanced view of the full journey
+
+### Cons
+
+- The 40/20/40 split is arbitrary (some businesses may need 30/40/30 or other splits)
+- Middle touchpoints get relatively little credit
+- May not suit businesses where middle interactions are the primary differentiator
+
+### Best For
+
+B2B and enterprise marketing teams running coordinated campaigns across the full customer journey from awareness through conversion.
+
+---
+
+## Model Comparison Matrix
+
+| Criteria | First-Touch | Last-Touch | Linear | Time-Decay | Position-Based |
+|----------|------------|------------|--------|------------|----------------|
+| Complexity | Low | Low | Low | Medium | Medium |
+| Awareness bias | High | None | Neutral | Low | Medium |
+| Conversion bias | None | High | Neutral | High | Medium |
+| Multi-touch fairness | Poor | Poor | Good | Good | Good |
+| Best sales cycle | Any | Short | Long | Short-Medium | Any |
+| Stakeholder clarity | High | High | High | Medium | Medium |
+
+---
+
+## Practical Guidelines
+
+### Running Multiple Models
+
+Always run at least 3 models and look for channels that rank highly across multiple models. These are your most reliable performers. Channels that rank well in only one model may be overvalued by that model's bias.
+
+### Interpreting Divergent Results
+
+When models disagree significantly on a channel's value:
+
+1. **High in first-touch, low in last-touch**: The channel is strong for awareness but does not close. Pair it with stronger conversion channels.
+2. **Low in first-touch, high in last-touch**: The channel closes deals but does not generate new prospects. Ensure upstream awareness channels feed it.
+3. **High in linear, low in first/last**: The channel plays a critical nurturing role. Cutting it may break the journey without immediately visible impact.
+
+### Common Pitfalls
+
+- **Over-relying on last-touch**: Most analytics platforms default to last-touch, which chronically undervalues awareness spending.
+- **Ignoring non-converting journeys**: Attribution only counts converted journeys. Channels that contribute to unconverted journeys may still have value.
+- **Confusing correlation with causation**: Attribution shows correlation between touchpoints and conversion, not definitive causation.
+- **Insufficient data volume**: Models require statistically meaningful journey counts. With fewer than 100 journeys, results are unreliable.
+
+---
+
+## Data Requirements
+
+### Minimum Data
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| journey_id | Yes | Unique identifier for each customer journey |
+| touchpoints | Yes | Array of channel interactions with timestamps |
+| converted | Yes | Boolean indicating whether the journey converted |
+| revenue | Recommended | Conversion value for credit allocation |
+
+### Touchpoint Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| channel | Yes | Marketing channel name |
+| timestamp | Yes | ISO-format timestamp of the interaction |
+| interaction | Optional | Type of interaction (click, view, open, etc.) |
+
+---
+
+## Further Reading
+
+- Google Analytics attribution model comparison documentation
+- Facebook/Meta attribution window settings and their impact
+- HubSpot multi-touch revenue attribution methodology
+- Bizible/Marketo B2B attribution best practices
diff --git a/skills/campaign-analytics/references/campaign-metrics-benchmarks.md b/skills/campaign-analytics/references/campaign-metrics-benchmarks.md
new file mode 100644
index 00000000..33239156
--- /dev/null
+++ b/skills/campaign-analytics/references/campaign-metrics-benchmarks.md
@@ -0,0 +1,259 @@
+# Campaign Metrics Benchmarks
+
+Industry benchmark reference for marketing campaign performance metrics. Use these benchmarks to contextualize your campaign results, identify underperformance, and set realistic targets.
+
+---
+
+## How to Use This Reference
+
+1. Find your industry vertical and channel combination
+2. Compare your actual metrics to the benchmark ranges
+3. Use the assessment scale: Below Low = underperforming, Low-Target = below target, Target-High = good, Above High = excellent
+4. Adjust targets based on your historical performance (your own data is always the best benchmark)
+
+---
+
+## Click-Through Rate (CTR) Benchmarks
+
+CTR = (Clicks / Impressions) * 100
+
+### By Channel (Cross-Industry Average)
+
+| Channel | Low | Target | High | Notes |
+|---------|-----|--------|------|-------|
+| Email | 1.0% | 2.5% | 5.0% | Highly dependent on list quality and segmentation |
+| Paid Search (Google) | 1.5% | 3.5% | 7.0% | Brand keywords typically 5-10%, generic 1-3% |
+| Paid Social (Facebook) | 0.5% | 1.2% | 3.0% | Video ads trend higher, static lower |
+| Paid Social (LinkedIn) | 0.3% | 0.8% | 2.0% | B2B focused, lower volume but higher intent |
+| Display Ads | 0.05% | 0.10% | 0.50% | Retargeting typically 0.5-1.0% |
+| Organic Search | 1.5% | 3.0% | 8.0% | Position 1 averages 28-31% CTR |
+| Organic Social | 0.5% | 1.5% | 4.0% | Platform algorithm changes affect significantly |
+| Referral | 1.0% | 3.0% | 6.0% | Quality of referring site matters greatly |
+| Direct | 2.0% | 4.0% | 8.0% | Highest intent channel |
+
+### By Industry (Paid Search)
+
+| Industry | Average CTR | Low | High |
+|----------|------------|-----|------|
+| B2B | 2.4% | 1.5% | 4.0% |
+| E-commerce | 2.7% | 1.8% | 5.0% |
+| Education | 3.3% | 2.0% | 6.0% |
+| Finance & Insurance | 2.9% | 1.5% | 5.5% |
+| Healthcare | 3.3% | 2.0% | 5.0% |
+| Legal | 2.9% | 1.5% | 5.0% |
+| Real Estate | 3.7% | 2.5% | 6.0% |
+| Retail | 2.5% | 1.5% | 5.0% |
+| SaaS | 2.1% | 1.2% | 3.5% |
+| Technology | 2.1% | 1.0% | 4.0% |
+| Travel & Hospitality | 4.7% | 3.0% | 8.0% |
+
+---
+
+## Cost Per Click (CPC) Benchmarks
+
+CPC = Spend / Clicks
+
+### By Channel (USD)
+
+| Channel | Low | Target | High | Notes |
+|---------|-----|--------|------|-------|
+| Google Search | $0.50 | $2.50 | $8.00 | Legal/finance can exceed $50 per click |
+| Google Display | $0.10 | $0.50 | $2.00 | Programmatic can be lower |
+| Facebook | $0.30 | $1.00 | $3.00 | B2C typically lower than B2B |
+| LinkedIn | $2.00 | $5.50 | $12.00 | Highest CPC among social platforms |
+| Instagram | $0.40 | $1.20 | $3.50 | Stories ads trending lower |
+| Twitter/X | $0.20 | $0.80 | $2.50 | High variability by topic |
+| TikTok | $0.10 | $0.50 | $2.00 | Rapidly evolving, currently lower |
+
+### By Industry (Google Ads)
+
+| Industry | Average CPC | Range |
+|----------|------------|-------|
+| Automotive | $2.46 | $1.00-$6.00 |
+| B2B | $3.33 | $1.50-$8.00 |
+| E-commerce | $1.16 | $0.50-$3.00 |
+| Education | $2.40 | $1.00-$5.00 |
+| Finance & Insurance | $3.44 | $1.00-$50.00 |
+| Healthcare | $2.62 | $1.00-$6.00 |
+| Legal | $6.75 | $2.00-$100.00 |
+| Real Estate | $2.37 | $1.00-$5.00 |
+| SaaS/Technology | $3.80 | $1.50-$10.00 |
+| Travel | $1.53 | $0.50-$4.00 |
+
+---
+
+## Cost Per Mille / Thousand Impressions (CPM) Benchmarks
+
+CPM = (Spend / Impressions) * 1000
+
+### By Channel (USD)
+
+| Channel | Low | Target | High | Notes |
+|---------|-----|--------|------|-------|
+| Facebook | $3.00 | $8.00 | $15.00 | Q4 holiday season can exceed $20 |
+| Instagram | $4.00 | $10.00 | $18.00 | Reels ads trending lower |
+| LinkedIn | $8.00 | $25.00 | $50.00 | Premium B2B audience |
+| Google Display | $1.00 | $3.50 | $8.00 | Programmatic ranges widely |
+| TikTok | $2.00 | $6.00 | $12.00 | Growing platform, rates increasing |
+| YouTube | $4.00 | $10.00 | $20.00 | Pre-roll vs discovery ads vary |
+| Programmatic Display | $0.50 | $2.00 | $6.00 | Dependent on targeting precision |
+
+---
+
+## Cost Per Acquisition (CPA) Benchmarks
+
+CPA = Spend / Customers Acquired
+
+### By Channel (USD)
+
+| Channel | Low | Target | High | Notes |
+|---------|-----|--------|------|-------|
+| Email | $5 | $15 | $40 | Existing list; acquisition cost amortized |
+| Paid Search | $20 | $50 | $150 | Highly dependent on industry and competition |
+| Paid Social | $15 | $40 | $100 | Retargeting typically lower |
+| Display | $30 | $75 | $200 | Awareness-focused; higher CPA expected |
+| Organic Search | $5 | $20 | $60 | Excludes SEO investment costs |
+| Organic Social | $10 | $30 | $80 | Content production costs excluded |
+| Referral | $10 | $25 | $70 | Referral incentive costs included |
+
+### By Industry (Across Channels)
+
+| Industry | Average CPA | Acceptable Range |
+|----------|------------|------------------|
+| B2B SaaS | $150-$400 | $75-$700 |
+| E-commerce | $25-$80 | $10-$150 |
+| Education | $40-$120 | $20-$250 |
+| Finance | $75-$200 | $30-$500 |
+| Healthcare | $50-$150 | $25-$300 |
+| Legal | $100-$300 | $50-$700 |
+| Real Estate | $60-$180 | $30-$350 |
+| Retail | $15-$50 | $8-$100 |
+| Travel | $20-$70 | $10-$150 |
+
+---
+
+## Cost Per Lead (CPL) Benchmarks
+
+CPL = Spend / Leads Generated
+
+### By Channel (USD)
+
+| Channel | Low | Target | High |
+|---------|-----|--------|------|
+| Email | $3 | $10 | $25 |
+| Paid Search | $15 | $35 | $90 |
+| Paid Social (Facebook) | $8 | $20 | $50 |
+| Paid Social (LinkedIn) | $25 | $75 | $150 |
+| Display | $20 | $50 | $120 |
+| Content Marketing | $10 | $30 | $80 |
+| Webinars | $30 | $70 | $150 |
+
+### By Industry
+
+| Industry | Average CPL | Range |
+|----------|------------|-------|
+| B2B SaaS | $50-$150 | $25-$300 |
+| E-commerce | $10-$30 | $5-$60 |
+| Education | $25-$70 | $15-$150 |
+| Financial Services | $40-$120 | $20-$250 |
+| Healthcare | $30-$90 | $15-$180 |
+| Manufacturing | $50-$120 | $25-$200 |
+| Technology | $40-$100 | $20-$200 |
+
+---
+
+## Return on Ad Spend (ROAS) Benchmarks
+
+ROAS = Revenue / Ad Spend
+
+### By Channel
+
+| Channel | Low | Target | High | Notes |
+|---------|-----|--------|------|-------|
+| Email | 30x | 42x | 60x | Highest ROAS channel when list is healthy |
+| Paid Search (Brand) | 8x | 15x | 30x | Brand terms have high ROAS |
+| Paid Search (Generic) | 2x | 4x | 8x | Competitive; ROAS varies widely |
+| Paid Social | 1.5x | 3x | 6x | Retargeting typically 4-10x |
+| Display | 0.5x | 1.5x | 3x | Often used for awareness; lower direct ROAS |
+| Organic Search | 5x | 10x | 20x | Excludes SEO investment amortization |
+| Organic Social | 3x | 6x | 12x | Excludes content production costs |
+
+### By Industry
+
+| Industry | Minimum Viable ROAS | Target ROAS |
+|----------|--------------------:|------------:|
+| E-commerce (low margin) | 4x | 8x+ |
+| E-commerce (high margin) | 2x | 4x+ |
+| SaaS | 3x | 6x+ |
+| B2B Services | 5x | 10x+ |
+| Retail | 3x | 5x+ |
+| DTC Brands | 2.5x | 5x+ |
+
+### ROAS Calculation Notes
+
+- **Breakeven ROAS** = 1 / Profit Margin (e.g., 25% margin = 4x breakeven)
+- **Target ROAS** should be at least 2x the breakeven ROAS for sustainable growth
+- Always include all costs (media, creative, tools, labor) for true ROAS
+
+---
+
+## Conversion Rate Benchmarks
+
+### Landing Page Conversion Rate
+
+| Industry | Low | Average | High |
+|----------|-----|---------|------|
+| B2B SaaS | 2.0% | 4.5% | 9.0% |
+| E-commerce | 1.5% | 3.0% | 6.0% |
+| Education | 2.5% | 5.5% | 10.0% |
+| Finance | 2.0% | 5.0% | 11.0% |
+| Healthcare | 2.0% | 4.0% | 8.0% |
+| Legal | 3.0% | 7.0% | 13.0% |
+| Real Estate | 2.0% | 4.5% | 8.0% |
+| Travel | 2.0% | 4.0% | 9.0% |
+
+### Email Conversion Rates
+
+| Metric | Low | Average | High |
+|--------|-----|---------|------|
+| Open Rate | 15% | 22% | 35% |
+| Click Rate | 1.0% | 2.5% | 5.0% |
+| Click-to-Open Rate | 8% | 12% | 20% |
+| Unsubscribe Rate | 0.1% | 0.2% | 0.5% |
+
+---
+
+## Seasonal Adjustments
+
+Campaign benchmarks fluctuate by season. Apply these adjustment factors to normalize your comparisons:
+
+| Quarter | CPC Adjustment | CPM Adjustment | CVR Adjustment |
+|---------|---------------|----------------|----------------|
+| Q1 (Jan-Mar) | -10% to -15% | -15% to -20% | Baseline |
+| Q2 (Apr-Jun) | Baseline | Baseline | Baseline |
+| Q3 (Jul-Sep) | +5% to +10% | +5% to +10% | -5% |
+| Q4 (Oct-Dec) | +15% to +30% | +20% to +40% | +10% to +20% |
+
+**Key seasonal events:**
+- Black Friday/Cyber Monday: CPMs can increase 50-100%
+- January: Lowest competition, good for testing
+- Back-to-School (Aug-Sep): Education and retail spike
+- Tax Season (Jan-Apr): Finance vertical spike
+
+---
+
+## Using Benchmarks Effectively
+
+### Do
+
+- Compare against your own historical data first, then industry benchmarks
+- Account for seasonality when comparing time periods
+- Consider your funnel position (awareness vs conversion campaigns have different benchmarks)
+- Update benchmarks annually as industry norms shift
+
+### Do Not
+
+- Treat benchmarks as absolute targets (your business context matters more)
+- Compare across industries without adjustment
+- Ignore sample size (small campaigns have high variance)
+- Use benchmarks to justify cutting channels without understanding their full-funnel role
diff --git a/skills/campaign-analytics/references/funnel-optimization-framework.md b/skills/campaign-analytics/references/funnel-optimization-framework.md
new file mode 100644
index 00000000..36da9843
--- /dev/null
+++ b/skills/campaign-analytics/references/funnel-optimization-framework.md
@@ -0,0 +1,302 @@
+# Funnel Optimization Framework
+
+A stage-by-stage guide to diagnosing and improving marketing and sales funnel performance. Use this framework alongside the funnel_analyzer.py tool to identify bottlenecks and implement targeted optimizations.
+
+---
+
+## The Standard Marketing Funnel
+
+```
+ AWARENESS (Impressions, Reach)
+ |
+ INTEREST (Clicks, Engagement)
+ |
+ CONSIDERATION (Leads, Sign-ups)
+ |
+ INTENT (Demos, Trials, Cart Adds)
+ |
+ PURCHASE (Customers, Revenue)
+ |
+ RETENTION (Repeat, Upsell, Referral)
+```
+
+Each transition between stages represents a conversion point. The funnel analyzer measures these transitions and identifies where the largest drop-offs occur.
+
+---
+
+## Stage-by-Stage Optimization
+
+### Stage 1: Awareness to Interest
+
+**What it measures:** How effectively you capture attention and generate initial engagement.
+
+**Healthy conversion rate:** 2-8% (varies widely by channel)
+
+**Common bottlenecks:**
+- Poor targeting: Reaching the wrong audience
+- Weak creative: Ads that do not stand out or communicate value
+- Message-market mismatch: Content that does not resonate with the audience's needs
+- Low brand recognition: No trust or familiarity established
+
+**Optimization tactics:**
+
+| Tactic | Expected Impact | Effort |
+|--------|----------------|--------|
+| Audience refinement (lookalike, interest targeting) | High | Medium |
+| Creative testing (3-5 variants per campaign) | High | Medium |
+| Headline optimization (clear value proposition) | Medium | Low |
+| Channel diversification (test new platforms) | Medium | High |
+| Retargeting past engagers | Medium | Low |
+
+**Key metrics to track:**
+- Impressions and reach
+- CTR by creative variant
+- Cost per engagement
+- Brand lift (if measured)
+
+---
+
+### Stage 2: Interest to Consideration
+
+**What it measures:** How well you convert initial interest into genuine evaluation.
+
+**Healthy conversion rate:** 10-30%
+
+**Common bottlenecks:**
+- Landing page disconnect: The page does not match the ad promise
+- Poor user experience: Slow load times, confusing layout, mobile issues
+- Missing social proof: No testimonials, case studies, or trust signals
+- Unclear value proposition: Visitor does not understand "what's in it for me"
+- Friction in lead capture: Too many form fields, unclear CTA
+
+**Optimization tactics:**
+
+| Tactic | Expected Impact | Effort |
+|--------|----------------|--------|
+| Landing page A/B testing | High | Medium |
+| Message match (ad copy = page headline) | High | Low |
+| Reduce form fields to essential only | High | Low |
+| Add social proof (logos, testimonials, numbers) | Medium | Low |
+| Improve page load speed (<3 seconds) | Medium | Medium |
+| Mobile optimization | Medium | Medium |
+| Add exit-intent offers | Low-Medium | Low |
+
+**Key metrics to track:**
+- Landing page conversion rate
+- Bounce rate
+- Time on page
+- Form abandonment rate
+
+---
+
+### Stage 3: Consideration to Intent
+
+**What it measures:** How effectively you move evaluated prospects toward a purchase decision.
+
+**Healthy conversion rate:** 15-40%
+
+**Common bottlenecks:**
+- Insufficient nurturing: Leads go cold without follow-up
+- Lack of differentiation: Prospects do not understand why you are better than alternatives
+- Missing information: Pricing, features, or comparisons not available
+- Sales-marketing misalignment: MQLs are not meeting sales expectations
+- Poor timing: Follow-up is too slow or too aggressive
+
+**Optimization tactics:**
+
+| Tactic | Expected Impact | Effort |
+|--------|----------------|--------|
+| Email nurture sequences (5-7 touchpoints) | High | Medium |
+| Lead scoring to prioritize sales outreach | High | High |
+| Comparison content (vs. competitors) | Medium | Medium |
+| Free trial or demo offers | High | Medium |
+| Case studies relevant to prospect's industry | Medium | Medium |
+| Retargeting with mid-funnel content | Medium | Low |
+| Pricing transparency | Medium | Low |
+
+**Key metrics to track:**
+- MQL to SQL conversion rate
+- Lead response time
+- Email engagement rates (nurture sequences)
+- Content engagement (case studies, comparisons)
+
+---
+
+### Stage 4: Intent to Purchase
+
+**What it measures:** How well you convert ready-to-buy prospects into paying customers.
+
+**Healthy conversion rate:** 20-50%
+
+**Common bottlenecks:**
+- Complex purchase process: Too many steps, unclear pricing, difficult checkout
+- Lack of urgency: No reason to buy now
+- Unaddressed objections: Common concerns not proactively handled
+- Poor sales process: Inconsistent follow-up, inadequate discovery
+- Payment friction: Limited payment options, security concerns
+
+**Optimization tactics:**
+
+| Tactic | Expected Impact | Effort |
+|--------|----------------|--------|
+| Simplify checkout/purchase flow | High | Medium |
+| Add urgency (limited-time offers, scarcity) | Medium | Low |
+| Address objections in sales collateral | Medium | Medium |
+| Offer guarantees (money-back, free trial extension) | Medium | Low |
+| Cart abandonment emails (3-email sequence) | High | Low |
+| Live chat or chatbot support at checkout | Medium | Medium |
+| Multiple payment options | Low-Medium | Medium |
+| Customer success stories at point of purchase | Medium | Low |
+
+**Key metrics to track:**
+- Cart abandonment rate
+- Checkout completion rate
+- Average deal cycle length
+- Win rate (B2B)
+- Average order value
+
+---
+
+### Stage 5: Purchase to Retention
+
+**What it measures:** How well you retain customers and expand their lifetime value.
+
+**Healthy retention rate:** 70-95% annually (varies by business model)
+
+**Common bottlenecks:**
+- Poor onboarding: Customers do not achieve value quickly
+- Lack of engagement: No ongoing communication or community
+- Product/service issues: Unmet expectations post-purchase
+- No expansion path: No upsell, cross-sell, or referral programs
+- Competitor poaching: Better offers from alternatives
+
+**Optimization tactics:**
+
+| Tactic | Expected Impact | Effort |
+|--------|----------------|--------|
+| Structured onboarding (first 30/60/90 days) | High | High |
+| Regular check-ins and health scoring | High | Medium |
+| Loyalty programs | Medium | Medium |
+| Referral incentives | Medium | Low |
+| Cross-sell/upsell email sequences | Medium | Medium |
+| Customer community building | Medium | High |
+| Proactive support based on usage patterns | High | High |
+
+**Key metrics to track:**
+- Customer retention rate
+- Net Promoter Score (NPS)
+- Customer Lifetime Value (CLV)
+- Expansion revenue
+- Churn rate and reasons
+
+---
+
+## Bottleneck Diagnosis Framework
+
+When the funnel analyzer identifies a bottleneck, use this diagnostic framework:
+
+### Step 1: Quantify the Problem
+
+- What is the conversion rate at this stage?
+- How does it compare to your historical average?
+- How does it compare to industry benchmarks?
+- What is the absolute number of prospects lost?
+
+### Step 2: Segment the Data
+
+Look at the bottleneck broken down by:
+- **Channel**: Is the drop-off worse for certain traffic sources?
+- **Device**: Mobile vs desktop performance gaps
+- **Geography**: Regional differences
+- **Cohort**: Has it changed over time?
+- **Campaign**: Specific campaigns performing worse
+
+### Step 3: Identify Root Cause
+
+| Symptom | Likely Root Cause | Diagnostic Action |
+|---------|------------------|-------------------|
+| High bounce rate | Message mismatch or UX issue | Review landing page vs ad |
+| High time on page but low conversion | Confusion or missing CTA | Heatmap analysis |
+| Drop-off at form | Too many fields or unclear value | Form analytics review |
+| Long time between stages | Insufficient nurturing | Review email engagement |
+| Drop-off after pricing page | Pricing concerns | Test pricing presentation |
+| High cart abandonment | Checkout friction | Checkout flow analysis |
+
+### Step 4: Prioritize Fixes
+
+Use the ICE scoring framework:
+
+- **Impact** (1-10): How much will fixing this improve the bottleneck?
+- **Confidence** (1-10): How confident are you that this fix will work?
+- **Ease** (1-10): How easy is this to implement?
+
+Score = (Impact + Confidence + Ease) / 3
+
+Prioritize fixes with the highest ICE score.
+
+---
+
+## Funnel Math and Revenue Impact
+
+### Calculating the Revenue Impact of Funnel Improvements
+
+A useful way to prioritize is to calculate how much revenue each percentage point of improvement is worth at each stage.
+
+**Formula:**
+
+```
+Revenue Impact = Current_Revenue * (1 / Current_Conversion_Rate) * Improvement_Percentage
+```
+
+**Example:**
+
+| Stage | Current Rate | +1pp Improvement | Revenue Impact |
+|-------|-------------|-----------------|----------------|
+| Awareness -> Interest | 5.0% | 6.0% | +20% more leads entering funnel |
+| Interest -> Consideration | 25% | 26% | +4% more MQLs |
+| Consideration -> Intent | 30% | 31% | +3.3% more SQLs |
+| Intent -> Purchase | 40% | 41% | +2.5% more customers |
+
+**Key insight:** Improvements at the top of the funnel have a multiplied effect on downstream stages. But improvements at the bottom of the funnel convert to revenue faster.
+
+---
+
+## Common Anti-Patterns
+
+### 1. Optimizing the Wrong Stage
+Fixing a bottom-of-funnel problem when the real issue is top-of-funnel volume. Always diagnose the full funnel before optimizing.
+
+### 2. Ignoring Segment Differences
+Aggregate funnel metrics can hide that one segment performs well while another is broken. Always segment before optimizing.
+
+### 3. Over-Optimizing for Conversion Rate
+Increasing conversion rate by narrowing the funnel (stricter targeting, higher-intent-only leads) can reduce total volume. Balance rate and volume.
+
+### 4. Single-Metric Focus
+Optimizing CTR without watching CPA, or optimizing CPA without watching volume. Always track paired metrics.
+
+### 5. Not Accounting for Time Lag
+B2B funnels can take weeks or months. Measuring a campaign's funnel performance too early produces incomplete data.
+
+---
+
+## Segment Comparison Best Practices
+
+When using the funnel analyzer's segment comparison feature:
+
+1. **Compare meaningful segments**: Channel, campaign type, audience demographic, or time period
+2. **Ensure comparable volume**: Do not compare a segment with 100 entries to one with 10,000
+3. **Look for stage-specific differences**: Two segments may have similar overall rates but different bottlenecks
+4. **Use insights to inform targeting**: If one segment converts better at a specific stage, understand why and apply those lessons
+
+---
+
+## Recommended Review Cadence
+
+| Review Type | Frequency | Focus |
+|-------------|-----------|-------|
+| Campaign funnel check | Weekly | Active campaign stage rates |
+| Full funnel audit | Monthly | Overall funnel health, bottleneck shifts |
+| Segment deep-dive | Monthly | Channel and cohort comparisons |
+| Strategic funnel review | Quarterly | Funnel structure, stage definitions, benchmark updates |
+| Annual funnel redesign | Annually | Stage definitions, measurement methodology, tool updates |
diff --git a/skills/campaign-analytics/scripts/attribution_analyzer.py b/skills/campaign-analytics/scripts/attribution_analyzer.py
new file mode 100644
index 00000000..fc10b0b8
--- /dev/null
+++ b/skills/campaign-analytics/scripts/attribution_analyzer.py
@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+Attribution Analyzer - Multi-touch attribution modeling for marketing campaigns.
+
+Implements 5 attribution models:
+ - first-touch: 100% credit to first interaction
+ - last-touch: 100% credit to last interaction
+ - linear: Equal credit across all touchpoints
+ - time-decay: Exponential decay favoring recent touchpoints
+ - position-based: 40% first, 40% last, 20% split among middle
+
+Usage:
+ python attribution_analyzer.py data.json
+ python attribution_analyzer.py data.json --model time-decay
+ python attribution_analyzer.py data.json --model time-decay --half-life 14
+ python attribution_analyzer.py data.json --format json
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+MODELS = ["first-touch", "last-touch", "linear", "time-decay", "position-based"]
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def parse_timestamp(ts: str) -> datetime:
+ """Parse an ISO-format timestamp string into a datetime object."""
+ for fmt in ("%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%d"):
+ try:
+ return datetime.strptime(ts, fmt)
+ except ValueError:
+ continue
+ raise ValueError(f"Cannot parse timestamp: {ts}")
+
+
+def first_touch_attribution(journeys: List[Dict]) -> Dict[str, float]:
+ """First-touch: 100% credit to the first touchpoint in each journey."""
+ credits: Dict[str, float] = {}
+ for journey in journeys:
+ if not journey.get("converted", False):
+ continue
+ touchpoints = journey.get("touchpoints", [])
+ if not touchpoints:
+ continue
+ sorted_tp = sorted(touchpoints, key=lambda t: parse_timestamp(t["timestamp"]))
+ channel = sorted_tp[0]["channel"]
+ revenue = journey.get("revenue", 1.0)
+ credits[channel] = credits.get(channel, 0.0) + revenue
+ return credits
+
+
+def last_touch_attribution(journeys: List[Dict]) -> Dict[str, float]:
+ """Last-touch: 100% credit to the last touchpoint in each journey."""
+ credits: Dict[str, float] = {}
+ for journey in journeys:
+ if not journey.get("converted", False):
+ continue
+ touchpoints = journey.get("touchpoints", [])
+ if not touchpoints:
+ continue
+ sorted_tp = sorted(touchpoints, key=lambda t: parse_timestamp(t["timestamp"]))
+ channel = sorted_tp[-1]["channel"]
+ revenue = journey.get("revenue", 1.0)
+ credits[channel] = credits.get(channel, 0.0) + revenue
+ return credits
+
+
+def linear_attribution(journeys: List[Dict]) -> Dict[str, float]:
+ """Linear: Equal credit split across all touchpoints in each journey."""
+ credits: Dict[str, float] = {}
+ for journey in journeys:
+ if not journey.get("converted", False):
+ continue
+ touchpoints = journey.get("touchpoints", [])
+ if not touchpoints:
+ continue
+ revenue = journey.get("revenue", 1.0)
+ share = safe_divide(revenue, len(touchpoints))
+ for tp in touchpoints:
+ channel = tp["channel"]
+ credits[channel] = credits.get(channel, 0.0) + share
+ return credits
+
+
+def time_decay_attribution(journeys: List[Dict], half_life_days: float = 7.0) -> Dict[str, float]:
+ """Time-decay: Exponential decay giving more credit to recent touchpoints.
+
+ Uses a configurable half-life (in days). Touchpoints closer to conversion
+ receive exponentially more credit.
+ """
+ import math
+
+ credits: Dict[str, float] = {}
+ decay_rate = math.log(2) / half_life_days
+
+ for journey in journeys:
+ if not journey.get("converted", False):
+ continue
+ touchpoints = journey.get("touchpoints", [])
+ if not touchpoints:
+ continue
+
+ revenue = journey.get("revenue", 1.0)
+ sorted_tp = sorted(touchpoints, key=lambda t: parse_timestamp(t["timestamp"]))
+ conversion_time = parse_timestamp(sorted_tp[-1]["timestamp"])
+
+ # Calculate raw weights
+ weights: List[float] = []
+ for tp in sorted_tp:
+ tp_time = parse_timestamp(tp["timestamp"])
+ days_before = (conversion_time - tp_time).total_seconds() / 86400.0
+ weight = math.exp(-decay_rate * days_before)
+ weights.append(weight)
+
+ total_weight = sum(weights)
+ if total_weight == 0:
+ continue
+
+ for i, tp in enumerate(sorted_tp):
+ channel = tp["channel"]
+ share = safe_divide(weights[i], total_weight) * revenue
+ credits[channel] = credits.get(channel, 0.0) + share
+
+ return credits
+
+
+def position_based_attribution(journeys: List[Dict]) -> Dict[str, float]:
+ """Position-based: 40% first, 40% last, 20% split among middle touchpoints."""
+ credits: Dict[str, float] = {}
+ for journey in journeys:
+ if not journey.get("converted", False):
+ continue
+ touchpoints = journey.get("touchpoints", [])
+ if not touchpoints:
+ continue
+
+ revenue = journey.get("revenue", 1.0)
+ sorted_tp = sorted(touchpoints, key=lambda t: parse_timestamp(t["timestamp"]))
+
+ if len(sorted_tp) == 1:
+ channel = sorted_tp[0]["channel"]
+ credits[channel] = credits.get(channel, 0.0) + revenue
+ elif len(sorted_tp) == 2:
+ first_channel = sorted_tp[0]["channel"]
+ last_channel = sorted_tp[-1]["channel"]
+ credits[first_channel] = credits.get(first_channel, 0.0) + revenue * 0.5
+ credits[last_channel] = credits.get(last_channel, 0.0) + revenue * 0.5
+ else:
+ first_channel = sorted_tp[0]["channel"]
+ last_channel = sorted_tp[-1]["channel"]
+ credits[first_channel] = credits.get(first_channel, 0.0) + revenue * 0.4
+ credits[last_channel] = credits.get(last_channel, 0.0) + revenue * 0.4
+
+ middle_count = len(sorted_tp) - 2
+ middle_share = safe_divide(revenue * 0.2, middle_count)
+ for tp in sorted_tp[1:-1]:
+ channel = tp["channel"]
+ credits[channel] = credits.get(channel, 0.0) + middle_share
+
+ return credits
+
+
+def run_model(model_name: str, journeys: List[Dict], half_life: float = 7.0) -> Dict[str, float]:
+ """Dispatch to the appropriate attribution model."""
+ if model_name == "first-touch":
+ return first_touch_attribution(journeys)
+ elif model_name == "last-touch":
+ return last_touch_attribution(journeys)
+ elif model_name == "linear":
+ return linear_attribution(journeys)
+ elif model_name == "time-decay":
+ return time_decay_attribution(journeys, half_life)
+ elif model_name == "position-based":
+ return position_based_attribution(journeys)
+ else:
+ raise ValueError(f"Unknown model: {model_name}. Choose from: {', '.join(MODELS)}")
+
+
+def compute_summary(journeys: List[Dict]) -> Dict[str, Any]:
+ """Compute summary statistics about the journey data."""
+ total_journeys = len(journeys)
+ converted = sum(1 for j in journeys if j.get("converted", False))
+ total_revenue = sum(j.get("revenue", 0.0) for j in journeys if j.get("converted", False))
+ all_channels = set()
+ for j in journeys:
+ for tp in j.get("touchpoints", []):
+ all_channels.add(tp["channel"])
+
+ return {
+ "total_journeys": total_journeys,
+ "converted_journeys": converted,
+ "conversion_rate": round(safe_divide(converted, total_journeys) * 100, 2),
+ "total_revenue": round(total_revenue, 2),
+ "channels_observed": sorted(all_channels),
+ }
+
+
+def format_text(results: Dict[str, Any]) -> str:
+ """Format results as human-readable text."""
+ lines: List[str] = []
+ lines.append("=" * 70)
+ lines.append("MULTI-TOUCH ATTRIBUTION ANALYSIS")
+ lines.append("=" * 70)
+
+ summary = results["summary"]
+ lines.append("")
+ lines.append("SUMMARY")
+ lines.append(f" Total Journeys: {summary['total_journeys']}")
+ lines.append(f" Converted: {summary['converted_journeys']}")
+ lines.append(f" Conversion Rate: {summary['conversion_rate']}%")
+ lines.append(f" Total Revenue: ${summary['total_revenue']:,.2f}")
+ lines.append(f" Channels Observed: {', '.join(summary['channels_observed'])}")
+
+ for model_name, credits in results["models"].items():
+ lines.append("")
+ lines.append("-" * 70)
+ lines.append(f"MODEL: {model_name.upper()}")
+ lines.append("-" * 70)
+
+ if not credits:
+ lines.append(" No conversions to attribute.")
+ continue
+
+ total_credit = sum(credits.values())
+ sorted_channels = sorted(credits.items(), key=lambda x: x[1], reverse=True)
+
+ lines.append(f" {'Channel':<25} {'Revenue Credit':>15} {'Share':>10}")
+ lines.append(f" {'-'*25} {'-'*15} {'-'*10}")
+
+ for channel, credit in sorted_channels:
+ pct = safe_divide(credit, total_credit) * 100
+ lines.append(f" {channel:<25} ${credit:>13,.2f} {pct:>8.1f}%")
+
+ lines.append(f" {'TOTAL':<25} ${total_credit:>13,.2f} {'100.0%':>10}")
+
+ # Comparison table
+ if len(results["models"]) > 1:
+ lines.append("")
+ lines.append("=" * 70)
+ lines.append("CROSS-MODEL COMPARISON")
+ lines.append("=" * 70)
+
+ all_channels = set()
+ for credits in results["models"].values():
+ all_channels.update(credits.keys())
+ all_channels_sorted = sorted(all_channels)
+
+ model_names = list(results["models"].keys())
+ header = f" {'Channel':<20}"
+ for mn in model_names:
+ short = mn.replace("-", " ").title()
+ header += f" {short:>14}"
+ lines.append(header)
+ lines.append(f" {'-'*20}" + f" {'-'*14}" * len(model_names))
+
+ for ch in all_channels_sorted:
+ row = f" {ch:<20}"
+ for mn in model_names:
+ val = results["models"][mn].get(ch, 0.0)
+ row += f" ${val:>12,.2f}"
+ lines.append(row)
+
+ lines.append("")
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for the attribution analyzer."""
+ parser = argparse.ArgumentParser(
+ description="Multi-touch attribution analyzer for marketing campaigns.",
+ epilog="Example: python attribution_analyzer.py data.json --model linear --format json",
+ )
+ parser.add_argument(
+ "input_file",
+ help="Path to JSON file containing journey/touchpoint data",
+ )
+ parser.add_argument(
+ "--model",
+ choices=MODELS,
+ default=None,
+ help="Run a specific attribution model (default: run all 5 models)",
+ )
+ parser.add_argument(
+ "--half-life",
+ type=float,
+ default=7.0,
+ help="Half-life in days for time-decay model (default: 7)",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ dest="output_format",
+ help="Output format (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ # Load input data
+ try:
+ with open(args.input_file, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input_file}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input_file}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ journeys = data.get("journeys", [])
+ if not journeys:
+ print("Error: No 'journeys' array found in input data.", file=sys.stderr)
+ sys.exit(1)
+
+ # Determine which models to run
+ models_to_run = [args.model] if args.model else MODELS
+
+ # Run models
+ model_results: Dict[str, Dict[str, float]] = {}
+ for model_name in models_to_run:
+ credits = run_model(model_name, journeys, args.half_life)
+ model_results[model_name] = {ch: round(v, 2) for ch, v in credits.items()}
+
+ # Build output
+ results: Dict[str, Any] = {
+ "summary": compute_summary(journeys),
+ "models": model_results,
+ }
+
+ if args.output_format == "json":
+ print(json.dumps(results, indent=2))
+ else:
+ print(format_text(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/campaign-analytics/scripts/campaign_roi_calculator.py b/skills/campaign-analytics/scripts/campaign_roi_calculator.py
new file mode 100644
index 00000000..36668409
--- /dev/null
+++ b/skills/campaign-analytics/scripts/campaign_roi_calculator.py
@@ -0,0 +1,459 @@
+#!/usr/bin/env python3
+"""
+Campaign ROI Calculator - Comprehensive campaign ROI and performance metrics.
+
+Calculates:
+ - ROI (Return on Investment)
+ - ROAS (Return on Ad Spend)
+ - CPA (Cost per Acquisition/Customer)
+ - CPL (Cost per Lead)
+ - CAC (Customer Acquisition Cost)
+ - CTR (Click-Through Rate)
+ - CVR (Conversion Rate - Leads to Customers)
+
+Includes industry benchmarking and underperformance flagging.
+
+Usage:
+ python campaign_roi_calculator.py campaign_data.json
+ python campaign_roi_calculator.py campaign_data.json --format json
+"""
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+
+# Industry benchmark ranges by channel
+# Format: {metric: {channel: (low, target, high)}}
+BENCHMARKS: Dict[str, Dict[str, tuple]] = {
+ "ctr": {
+ "email": (1.0, 2.5, 5.0),
+ "paid_search": (1.5, 3.5, 7.0),
+ "paid_social": (0.5, 1.2, 3.0),
+ "display": (0.05, 0.1, 0.5),
+ "organic_search": (1.5, 3.0, 8.0),
+ "organic_social": (0.5, 1.5, 4.0),
+ "referral": (1.0, 3.0, 6.0),
+ "direct": (2.0, 4.0, 8.0),
+ "default": (0.5, 2.0, 5.0),
+ },
+ "roas": {
+ "email": (30.0, 42.0, 60.0),
+ "paid_search": (2.0, 4.0, 8.0),
+ "paid_social": (1.5, 3.0, 6.0),
+ "display": (0.5, 1.5, 3.0),
+ "organic_search": (5.0, 10.0, 20.0),
+ "organic_social": (3.0, 6.0, 12.0),
+ "referral": (3.0, 5.0, 10.0),
+ "direct": (4.0, 8.0, 15.0),
+ "default": (2.0, 4.0, 8.0),
+ },
+ "cpa": {
+ "email": (5.0, 15.0, 40.0),
+ "paid_search": (20.0, 50.0, 150.0),
+ "paid_social": (15.0, 40.0, 100.0),
+ "display": (30.0, 75.0, 200.0),
+ "organic_search": (5.0, 20.0, 60.0),
+ "organic_social": (10.0, 30.0, 80.0),
+ "referral": (10.0, 25.0, 70.0),
+ "direct": (5.0, 15.0, 50.0),
+ "default": (15.0, 45.0, 120.0),
+ },
+}
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def get_benchmark(metric: str, channel: str) -> tuple:
+ """Get benchmark range for a metric and channel.
+
+ Returns:
+ Tuple of (low, target, high) for the given metric and channel.
+ """
+ metric_benchmarks = BENCHMARKS.get(metric, {})
+ return metric_benchmarks.get(channel, metric_benchmarks.get("default", (0, 0, 0)))
+
+
+def assess_performance(value: float, benchmark: tuple, higher_is_better: bool = True) -> str:
+ """Assess a metric value against its benchmark range.
+
+ Args:
+ value: The metric value to assess.
+ benchmark: Tuple of (low, target, high).
+ higher_is_better: Whether higher values are better (True for CTR, ROAS; False for CPA).
+
+ Returns:
+ Performance assessment string.
+ """
+ low, target, high = benchmark
+
+ if higher_is_better:
+ if value >= high:
+ return "excellent"
+ elif value >= target:
+ return "good"
+ elif value >= low:
+ return "below_target"
+ else:
+ return "underperforming"
+ else:
+ # For cost metrics, lower is better
+ if value <= low:
+ return "excellent"
+ elif value <= target:
+ return "good"
+ elif value <= high:
+ return "below_target"
+ else:
+ return "underperforming"
+
+
+def calculate_campaign_metrics(campaign: Dict[str, Any]) -> Dict[str, Any]:
+ """Calculate all ROI metrics for a single campaign.
+
+ Args:
+ campaign: Dict with keys: name, channel, spend, revenue, impressions, clicks, leads, customers.
+
+ Returns:
+ Dict with all calculated metrics, benchmarks, and assessments.
+ """
+ name = campaign.get("name", "Unnamed Campaign")
+ channel = campaign.get("channel", "default")
+ spend = campaign.get("spend", 0.0)
+ revenue = campaign.get("revenue", 0.0)
+ impressions = campaign.get("impressions", 0)
+ clicks = campaign.get("clicks", 0)
+ leads = campaign.get("leads", 0)
+ customers = campaign.get("customers", 0)
+
+ # Core metrics
+ roi = safe_divide(revenue - spend, spend) * 100
+ roas = safe_divide(revenue, spend)
+ cpa = safe_divide(spend, customers) if customers > 0 else None
+ cpl = safe_divide(spend, leads) if leads > 0 else None
+ cac = safe_divide(spend, customers) if customers > 0 else None
+ ctr = safe_divide(clicks, impressions) * 100 if impressions > 0 else None
+ cvr = safe_divide(customers, leads) * 100 if leads > 0 else None
+ cpc = safe_divide(spend, clicks) if clicks > 0 else None
+ cpm = safe_divide(spend, impressions) * 1000 if impressions > 0 else None
+ lead_conversion_rate = safe_divide(leads, clicks) * 100 if clicks > 0 else None
+
+ # Profit
+ profit = revenue - spend
+
+ # Benchmark assessments
+ assessments: Dict[str, Any] = {}
+ flags: List[str] = []
+
+ if ctr is not None:
+ benchmark = get_benchmark("ctr", channel)
+ assessment = assess_performance(ctr, benchmark, higher_is_better=True)
+ assessments["ctr"] = {
+ "value": round(ctr, 2),
+ "benchmark_range": {"low": benchmark[0], "target": benchmark[1], "high": benchmark[2]},
+ "assessment": assessment,
+ }
+ if assessment == "underperforming":
+ flags.append(f"CTR ({ctr:.2f}%) is below industry low ({benchmark[0]}%) for {channel}")
+
+ if roas > 0:
+ benchmark = get_benchmark("roas", channel)
+ assessment = assess_performance(roas, benchmark, higher_is_better=True)
+ assessments["roas"] = {
+ "value": round(roas, 2),
+ "benchmark_range": {"low": benchmark[0], "target": benchmark[1], "high": benchmark[2]},
+ "assessment": assessment,
+ }
+ if assessment == "underperforming":
+ flags.append(f"ROAS ({roas:.2f}x) is below industry low ({benchmark[0]}x) for {channel}")
+
+ if cpa is not None:
+ benchmark = get_benchmark("cpa", channel)
+ assessment = assess_performance(cpa, benchmark, higher_is_better=False)
+ assessments["cpa"] = {
+ "value": round(cpa, 2),
+ "benchmark_range": {"low": benchmark[0], "target": benchmark[1], "high": benchmark[2]},
+ "assessment": assessment,
+ }
+ if assessment == "underperforming":
+ flags.append(f"CPA (${cpa:.2f}) exceeds industry high (${benchmark[2]:.2f}) for {channel}")
+
+ if profit < 0:
+ flags.append(f"Campaign is unprofitable: ${profit:,.2f} net loss")
+
+ # Recommendations
+ recommendations: List[str] = []
+ if ctr is not None and assessments.get("ctr", {}).get("assessment") in ("below_target", "underperforming"):
+ recommendations.append("Improve ad creative and targeting to increase CTR")
+ if assessments.get("roas", {}).get("assessment") in ("below_target", "underperforming"):
+ recommendations.append("Review targeting and bid strategy to improve ROAS")
+ if assessments.get("cpa", {}).get("assessment") in ("below_target", "underperforming"):
+ recommendations.append("Optimize landing pages and conversion flow to reduce CPA")
+ if cvr is not None and cvr < 10:
+ recommendations.append("Lead-to-customer conversion is low; review sales process and lead quality")
+ if lead_conversion_rate is not None and lead_conversion_rate < 2:
+ recommendations.append("Click-to-lead rate is low; improve landing page relevance and form experience")
+ if profit > 0 and assessments.get("roas", {}).get("assessment") in ("good", "excellent"):
+ recommendations.append("Campaign performing well; consider scaling budget")
+
+ return {
+ "name": name,
+ "channel": channel,
+ "metrics": {
+ "spend": round(spend, 2),
+ "revenue": round(revenue, 2),
+ "profit": round(profit, 2),
+ "roi_pct": round(roi, 2),
+ "roas": round(roas, 2),
+ "cpa": round(cpa, 2) if cpa is not None else None,
+ "cpl": round(cpl, 2) if cpl is not None else None,
+ "cac": round(cac, 2) if cac is not None else None,
+ "ctr_pct": round(ctr, 2) if ctr is not None else None,
+ "cvr_pct": round(cvr, 2) if cvr is not None else None,
+ "cpc": round(cpc, 2) if cpc is not None else None,
+ "cpm": round(cpm, 2) if cpm is not None else None,
+ "lead_conversion_rate_pct": round(lead_conversion_rate, 2) if lead_conversion_rate is not None else None,
+ "impressions": impressions,
+ "clicks": clicks,
+ "leads": leads,
+ "customers": customers,
+ },
+ "assessments": assessments,
+ "flags": flags,
+ "recommendations": recommendations,
+ }
+
+
+def calculate_portfolio_summary(campaign_results: List[Dict[str, Any]]) -> Dict[str, Any]:
+ """Calculate aggregate metrics across all campaigns.
+
+ Args:
+ campaign_results: List of individual campaign result dicts.
+
+ Returns:
+ Portfolio-level summary with totals and weighted averages.
+ """
+ total_spend = sum(c["metrics"]["spend"] for c in campaign_results)
+ total_revenue = sum(c["metrics"]["revenue"] for c in campaign_results)
+ total_impressions = sum(c["metrics"]["impressions"] for c in campaign_results)
+ total_clicks = sum(c["metrics"]["clicks"] for c in campaign_results)
+ total_leads = sum(c["metrics"]["leads"] for c in campaign_results)
+ total_customers = sum(c["metrics"]["customers"] for c in campaign_results)
+ total_profit = total_revenue - total_spend
+
+ underperforming = [c["name"] for c in campaign_results if c["flags"]]
+ top_performers = sorted(
+ campaign_results,
+ key=lambda c: c["metrics"]["roi_pct"],
+ reverse=True,
+ )
+
+ # Channel breakdown
+ channel_totals: Dict[str, Dict[str, float]] = {}
+ for c in campaign_results:
+ ch = c["channel"]
+ if ch not in channel_totals:
+ channel_totals[ch] = {"spend": 0, "revenue": 0, "leads": 0, "customers": 0}
+ channel_totals[ch]["spend"] += c["metrics"]["spend"]
+ channel_totals[ch]["revenue"] += c["metrics"]["revenue"]
+ channel_totals[ch]["leads"] += c["metrics"]["leads"]
+ channel_totals[ch]["customers"] += c["metrics"]["customers"]
+
+ channel_summary = {}
+ for ch, totals in channel_totals.items():
+ channel_summary[ch] = {
+ "spend": round(totals["spend"], 2),
+ "revenue": round(totals["revenue"], 2),
+ "roi_pct": round(safe_divide(totals["revenue"] - totals["spend"], totals["spend"]) * 100, 2),
+ "roas": round(safe_divide(totals["revenue"], totals["spend"]), 2),
+ "leads": int(totals["leads"]),
+ "customers": int(totals["customers"]),
+ }
+
+ return {
+ "total_campaigns": len(campaign_results),
+ "total_spend": round(total_spend, 2),
+ "total_revenue": round(total_revenue, 2),
+ "total_profit": round(total_profit, 2),
+ "portfolio_roi_pct": round(safe_divide(total_profit, total_spend) * 100, 2),
+ "portfolio_roas": round(safe_divide(total_revenue, total_spend), 2),
+ "total_impressions": total_impressions,
+ "total_clicks": total_clicks,
+ "total_leads": total_leads,
+ "total_customers": total_customers,
+ "blended_ctr_pct": round(safe_divide(total_clicks, total_impressions) * 100, 2),
+ "blended_cpl": round(safe_divide(total_spend, total_leads), 2) if total_leads > 0 else None,
+ "blended_cpa": round(safe_divide(total_spend, total_customers), 2) if total_customers > 0 else None,
+ "underperforming_campaigns": underperforming,
+ "top_performer": top_performers[0]["name"] if top_performers else None,
+ "channel_summary": channel_summary,
+ }
+
+
+def format_text(results: Dict[str, Any]) -> str:
+ """Format full results as human-readable text."""
+ lines: List[str] = []
+ lines.append("=" * 70)
+ lines.append("CAMPAIGN ROI ANALYSIS")
+ lines.append("=" * 70)
+
+ # Portfolio summary
+ summary = results["portfolio_summary"]
+ lines.append("")
+ lines.append("PORTFOLIO SUMMARY")
+ lines.append(f" Total Campaigns: {summary['total_campaigns']}")
+ lines.append(f" Total Spend: ${summary['total_spend']:>12,.2f}")
+ lines.append(f" Total Revenue: ${summary['total_revenue']:>12,.2f}")
+ lines.append(f" Total Profit: ${summary['total_profit']:>12,.2f}")
+ lines.append(f" Portfolio ROI: {summary['portfolio_roi_pct']}%")
+ lines.append(f" Portfolio ROAS: {summary['portfolio_roas']}x")
+ lines.append(f" Blended CTR: {summary['blended_ctr_pct']}%")
+ if summary["blended_cpl"] is not None:
+ lines.append(f" Blended CPL: ${summary['blended_cpl']:>12,.2f}")
+ if summary["blended_cpa"] is not None:
+ lines.append(f" Blended CPA: ${summary['blended_cpa']:>12,.2f}")
+
+ if summary["top_performer"]:
+ lines.append(f" Top Performer: {summary['top_performer']}")
+ if summary["underperforming_campaigns"]:
+ lines.append(f" Flagged: {', '.join(summary['underperforming_campaigns'])}")
+
+ # Channel summary
+ if summary["channel_summary"]:
+ lines.append("")
+ lines.append("-" * 70)
+ lines.append("CHANNEL SUMMARY")
+ lines.append(f" {'Channel':<20} {'Spend':>12} {'Revenue':>12} {'ROI':>10} {'ROAS':>8}")
+ lines.append(f" {'-'*20} {'-'*12} {'-'*12} {'-'*10} {'-'*8}")
+ for ch, cs in sorted(summary["channel_summary"].items()):
+ lines.append(
+ f" {ch:<20} ${cs['spend']:>10,.2f} ${cs['revenue']:>10,.2f} "
+ f"{cs['roi_pct']:>8.1f}% {cs['roas']:>6.2f}x"
+ )
+
+ # Individual campaigns
+ for campaign in results["campaigns"]:
+ lines.append("")
+ lines.append("-" * 70)
+ lines.append(f"CAMPAIGN: {campaign['name']}")
+ lines.append(f"Channel: {campaign['channel']}")
+ lines.append("-" * 70)
+
+ m = campaign["metrics"]
+ lines.append(f" {'Metric':<25} {'Value':>15}")
+ lines.append(f" {'-'*25} {'-'*15}")
+ lines.append(f" {'Spend':<25} ${m['spend']:>13,.2f}")
+ lines.append(f" {'Revenue':<25} ${m['revenue']:>13,.2f}")
+ lines.append(f" {'Profit':<25} ${m['profit']:>13,.2f}")
+ lines.append(f" {'ROI':<25} {m['roi_pct']:>13.2f}%")
+ lines.append(f" {'ROAS':<25} {m['roas']:>13.2f}x")
+
+ if m["cpa"] is not None:
+ lines.append(f" {'CPA':<25} ${m['cpa']:>13,.2f}")
+ if m["cpl"] is not None:
+ lines.append(f" {'CPL':<25} ${m['cpl']:>13,.2f}")
+ if m["cac"] is not None:
+ lines.append(f" {'CAC':<25} ${m['cac']:>13,.2f}")
+ if m["ctr_pct"] is not None:
+ lines.append(f" {'CTR':<25} {m['ctr_pct']:>13.2f}%")
+ if m["cpc"] is not None:
+ lines.append(f" {'CPC':<25} ${m['cpc']:>13,.2f}")
+ if m["cpm"] is not None:
+ lines.append(f" {'CPM':<25} ${m['cpm']:>13,.2f}")
+ if m["cvr_pct"] is not None:
+ lines.append(f" {'Lead-to-Customer CVR':<25} {m['cvr_pct']:>13.2f}%")
+ if m["lead_conversion_rate_pct"] is not None:
+ lines.append(f" {'Click-to-Lead Rate':<25} {m['lead_conversion_rate_pct']:>13.2f}%")
+
+ # Benchmark assessments
+ if campaign["assessments"]:
+ lines.append("")
+ lines.append(" BENCHMARK ASSESSMENT")
+ for metric_name, a in campaign["assessments"].items():
+ br = a["benchmark_range"]
+ status = a["assessment"].upper().replace("_", " ")
+ lines.append(
+ f" {metric_name.upper()}: {a['value']} "
+ f"[low={br['low']}, target={br['target']}, high={br['high']}] "
+ f"-> {status}"
+ )
+
+ # Flags
+ if campaign["flags"]:
+ lines.append("")
+ lines.append(" WARNING FLAGS")
+ for flag in campaign["flags"]:
+ lines.append(f" ! {flag}")
+
+ # Recommendations
+ if campaign["recommendations"]:
+ lines.append("")
+ lines.append(" RECOMMENDATIONS")
+ for i, rec in enumerate(campaign["recommendations"], 1):
+ lines.append(f" {i}. {rec}")
+
+ lines.append("")
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for the campaign ROI calculator."""
+ parser = argparse.ArgumentParser(
+ description="Calculate campaign ROI, ROAS, CPA, CPL, CAC with industry benchmarking.",
+ epilog="Example: python campaign_roi_calculator.py campaigns.json --format json",
+ )
+ parser.add_argument(
+ "input_file",
+ help="Path to JSON file containing campaign data",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ dest="output_format",
+ help="Output format (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ # Load input data
+ try:
+ with open(args.input_file, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input_file}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input_file}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ campaigns = data.get("campaigns", [])
+ if not campaigns:
+ print("Error: No 'campaigns' array found in input data.", file=sys.stderr)
+ sys.exit(1)
+
+ # Calculate metrics for each campaign
+ campaign_results = [calculate_campaign_metrics(c) for c in campaigns]
+
+ # Calculate portfolio summary
+ portfolio_summary = calculate_portfolio_summary(campaign_results)
+
+ results = {
+ "portfolio_summary": portfolio_summary,
+ "campaigns": campaign_results,
+ }
+
+ if args.output_format == "json":
+ print(json.dumps(results, indent=2))
+ else:
+ print(format_text(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/campaign-analytics/scripts/funnel_analyzer.py b/skills/campaign-analytics/scripts/funnel_analyzer.py
new file mode 100644
index 00000000..b88ad438
--- /dev/null
+++ b/skills/campaign-analytics/scripts/funnel_analyzer.py
@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""
+Funnel Analyzer - Conversion funnel analysis with bottleneck detection.
+
+Analyzes marketing/sales funnels to identify:
+ - Stage-to-stage conversion rates and drop-off percentages
+ - Biggest bottleneck (largest absolute and relative drops)
+ - Overall funnel conversion rate
+ - Segment comparison when multiple segments are provided
+
+Usage:
+ python funnel_analyzer.py funnel_data.json
+ python funnel_analyzer.py funnel_data.json --format json
+"""
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+ """Safely divide two numbers, returning default if denominator is zero."""
+ if denominator == 0:
+ return default
+ return numerator / denominator
+
+
+def analyze_funnel(stages: List[str], counts: List[int]) -> Dict[str, Any]:
+ """Analyze a single funnel and return stage-by-stage metrics.
+
+ Args:
+ stages: Ordered list of funnel stage names (top to bottom).
+ counts: Corresponding counts at each stage.
+
+ Returns:
+ Dictionary with stage metrics, bottleneck info, and overall conversion.
+ """
+ if len(stages) != len(counts):
+ raise ValueError("Number of stages must match number of counts.")
+ if not stages:
+ raise ValueError("Funnel must have at least one stage.")
+
+ stage_metrics: List[Dict[str, Any]] = []
+ max_dropoff_abs = 0
+ max_dropoff_rel = 0.0
+ bottleneck_abs: Optional[str] = None
+ bottleneck_rel: Optional[str] = None
+
+ for i, (stage, count) in enumerate(zip(stages, counts)):
+ metric: Dict[str, Any] = {
+ "stage": stage,
+ "count": count,
+ "cumulative_conversion": round(safe_divide(count, counts[0]) * 100, 2),
+ }
+
+ if i > 0:
+ prev_count = counts[i - 1]
+ dropoff = prev_count - count
+ conversion_rate = safe_divide(count, prev_count) * 100
+ dropoff_rate = 100 - conversion_rate
+
+ metric["from_previous"] = stages[i - 1]
+ metric["conversion_rate"] = round(conversion_rate, 2)
+ metric["dropoff_count"] = dropoff
+ metric["dropoff_rate"] = round(dropoff_rate, 2)
+
+ # Track biggest absolute drop-off
+ if dropoff > max_dropoff_abs:
+ max_dropoff_abs = dropoff
+ bottleneck_abs = f"{stages[i-1]} -> {stage}"
+
+ # Track biggest relative drop-off
+ if dropoff_rate > max_dropoff_rel:
+ max_dropoff_rel = dropoff_rate
+ bottleneck_rel = f"{stages[i-1]} -> {stage}"
+ else:
+ metric["conversion_rate"] = 100.0
+ metric["dropoff_count"] = 0
+ metric["dropoff_rate"] = 0.0
+
+ stage_metrics.append(metric)
+
+ overall_conversion = safe_divide(counts[-1], counts[0]) * 100
+
+ return {
+ "stage_metrics": stage_metrics,
+ "overall_conversion_rate": round(overall_conversion, 2),
+ "total_entries": counts[0],
+ "total_conversions": counts[-1],
+ "total_lost": counts[0] - counts[-1],
+ "bottleneck_absolute": {
+ "transition": bottleneck_abs,
+ "dropoff_count": max_dropoff_abs,
+ },
+ "bottleneck_relative": {
+ "transition": bottleneck_rel,
+ "dropoff_rate": round(max_dropoff_rel, 2),
+ },
+ }
+
+
+def compare_segments(segments: Dict[str, Dict[str, Any]], stages: List[str]) -> Dict[str, Any]:
+ """Compare funnel performance across segments.
+
+ Args:
+ segments: Dict mapping segment name to {"counts": [...]}.
+ stages: Shared stage names for all segments.
+
+ Returns:
+ Comparison data with per-segment analysis and relative rankings.
+ """
+ segment_results: Dict[str, Dict[str, Any]] = {}
+
+ for seg_name, seg_data in segments.items():
+ counts = seg_data.get("counts", [])
+ if len(counts) != len(stages):
+ raise ValueError(
+ f"Segment '{seg_name}' has {len(counts)} counts but {len(stages)} stages."
+ )
+ segment_results[seg_name] = analyze_funnel(stages, counts)
+
+ # Rank segments by overall conversion rate
+ ranked = sorted(
+ segment_results.items(),
+ key=lambda x: x[1]["overall_conversion_rate"],
+ reverse=True,
+ )
+ rankings = [
+ {
+ "rank": i + 1,
+ "segment": name,
+ "overall_conversion_rate": result["overall_conversion_rate"],
+ "total_entries": result["total_entries"],
+ "total_conversions": result["total_conversions"],
+ }
+ for i, (name, result) in enumerate(ranked)
+ ]
+
+ # Stage-by-stage comparison
+ stage_comparison: List[Dict[str, Any]] = []
+ for i, stage in enumerate(stages):
+ stage_data: Dict[str, Any] = {"stage": stage}
+ for seg_name in segments:
+ metrics = segment_results[seg_name]["stage_metrics"][i]
+ stage_data[seg_name] = {
+ "count": metrics["count"],
+ "conversion_rate": metrics["conversion_rate"],
+ }
+ stage_comparison.append(stage_data)
+
+ return {
+ "segment_results": segment_results,
+ "rankings": rankings,
+ "stage_comparison": stage_comparison,
+ }
+
+
+def format_single_funnel_text(analysis: Dict[str, Any], title: str = "FUNNEL") -> str:
+ """Format a single funnel analysis as human-readable text."""
+ lines: List[str] = []
+ lines.append(f" {title}")
+ lines.append(f" {'='*60}")
+ lines.append(f" Total Entries: {analysis['total_entries']:,}")
+ lines.append(f" Total Conversions: {analysis['total_conversions']:,}")
+ lines.append(f" Total Lost: {analysis['total_lost']:,}")
+ lines.append(f" Overall Conversion: {analysis['overall_conversion_rate']}%")
+ lines.append("")
+
+ lines.append(f" {'Stage':<20} {'Count':>10} {'Conv Rate':>12} {'Drop-off':>12} {'Cumulative':>12}")
+ lines.append(f" {'-'*20} {'-'*10} {'-'*12} {'-'*12} {'-'*12}")
+
+ for m in analysis["stage_metrics"]:
+ stage = m["stage"]
+ count = m["count"]
+ conv = f"{m['conversion_rate']:.1f}%"
+ drop = f"-{m['dropoff_count']:,} ({m['dropoff_rate']:.1f}%)" if m["dropoff_count"] > 0 else "-"
+ cumul = f"{m['cumulative_conversion']:.1f}%"
+ lines.append(f" {stage:<20} {count:>10,} {conv:>12} {drop:>12} {cumul:>12}")
+
+ lines.append("")
+ bn_abs = analysis["bottleneck_absolute"]
+ bn_rel = analysis["bottleneck_relative"]
+ lines.append(f" BOTTLENECK (Absolute): {bn_abs['transition']} (lost {bn_abs['dropoff_count']:,})")
+ lines.append(f" BOTTLENECK (Relative): {bn_rel['transition']} ({bn_rel['dropoff_rate']}% drop-off)")
+
+ return "\n".join(lines)
+
+
+def format_text(results: Dict[str, Any]) -> str:
+ """Format full results as human-readable text output."""
+ lines: List[str] = []
+ lines.append("=" * 70)
+ lines.append("FUNNEL CONVERSION ANALYSIS")
+ lines.append("=" * 70)
+
+ if "stage_comparison" in results:
+ # Multi-segment output
+ lines.append("")
+ lines.append("SEGMENT RANKINGS")
+ lines.append(f" {'Rank':>4} {'Segment':<25} {'Conversion':>12} {'Entries':>10} {'Conversions':>12}")
+ lines.append(f" {'-'*4} {'-'*25} {'-'*12} {'-'*10} {'-'*12}")
+ for r in results["rankings"]:
+ lines.append(
+ f" {r['rank']:>4} {r['segment']:<25} {r['overall_conversion_rate']:>11.2f}% "
+ f"{r['total_entries']:>10,} {r['total_conversions']:>12,}"
+ )
+
+ lines.append("")
+ for seg_name, seg_result in results["segment_results"].items():
+ lines.append("")
+ lines.append(format_single_funnel_text(seg_result, title=f"SEGMENT: {seg_name.upper()}"))
+
+ # Stage comparison table
+ lines.append("")
+ lines.append("-" * 70)
+ lines.append("STAGE-BY-STAGE COMPARISON")
+ lines.append("-" * 70)
+ seg_names = list(results["segment_results"].keys())
+ header = f" {'Stage':<20}"
+ for sn in seg_names:
+ header += f" {sn:>20}"
+ lines.append(header)
+ lines.append(f" {'-'*20}" + f" {'-'*20}" * len(seg_names))
+
+ for sc in results["stage_comparison"]:
+ row = f" {sc['stage']:<20}"
+ for sn in seg_names:
+ data = sc[sn]
+ row += f" {data['count']:>8,} ({data['conversion_rate']:>5.1f}%)"
+ lines.append(row)
+
+ else:
+ # Single funnel output
+ lines.append("")
+ lines.append(format_single_funnel_text(results))
+
+ lines.append("")
+ return "\n".join(lines)
+
+
+def main() -> None:
+ """Main entry point for the funnel analyzer."""
+ parser = argparse.ArgumentParser(
+ description="Analyze conversion funnels with bottleneck detection and segment comparison.",
+ epilog="Example: python funnel_analyzer.py funnel_data.json --format json",
+ )
+ parser.add_argument(
+ "input_file",
+ help="Path to JSON file containing funnel data",
+ )
+ parser.add_argument(
+ "--format",
+ choices=["json", "text"],
+ default="text",
+ dest="output_format",
+ help="Output format (default: text)",
+ )
+
+ args = parser.parse_args()
+
+ # Load input data
+ try:
+ with open(args.input_file, "r") as f:
+ data = json.load(f)
+ except FileNotFoundError:
+ print(f"Error: File not found: {args.input_file}", file=sys.stderr)
+ sys.exit(1)
+ except json.JSONDecodeError as e:
+ print(f"Error: Invalid JSON in {args.input_file}: {e}", file=sys.stderr)
+ sys.exit(1)
+
+ # Determine mode: single funnel vs. segment comparison
+ if "segments" in data:
+ # Multi-segment mode
+ stages = data.get("funnel", {}).get("stages", data.get("stages", []))
+ if not stages:
+ print("Error: 'stages' list required for segment comparison.", file=sys.stderr)
+ sys.exit(1)
+ segments = data["segments"]
+ if not segments:
+ print("Error: 'segments' dict is empty.", file=sys.stderr)
+ sys.exit(1)
+ results = compare_segments(segments, stages)
+ elif "funnel" in data:
+ # Single funnel mode
+ funnel = data["funnel"]
+ stages = funnel.get("stages", [])
+ counts = funnel.get("counts", [])
+ if not stages or not counts:
+ print("Error: 'funnel' must contain 'stages' and 'counts' arrays.", file=sys.stderr)
+ sys.exit(1)
+ results = analyze_funnel(stages, counts)
+ else:
+ print("Error: Input must contain 'funnel' or 'segments' key.", file=sys.stderr)
+ sys.exit(1)
+
+ if args.output_format == "json":
+ print(json.dumps(results, indent=2))
+ else:
+ print(format_text(results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/capa-officer/SKILL.md b/skills/capa-officer/SKILL.md
new file mode 100644
index 00000000..be868100
--- /dev/null
+++ b/skills/capa-officer/SKILL.md
@@ -0,0 +1,434 @@
+---
+name: "capa-officer"
+description: CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use for CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization.
+triggers:
+ - CAPA investigation
+ - root cause analysis
+ - 5 Why analysis
+ - fishbone diagram
+ - corrective action
+ - preventive action
+ - effectiveness verification
+ - CAPA metrics
+ - nonconformance investigation
+ - quality issue investigation
+ - CAPA tracking
+ - audit finding CAPA
+---
+
+# CAPA Officer
+
+Corrective and Preventive Action (CAPA) management within Quality Management Systems, focusing on systematic root cause analysis, action implementation, and effectiveness verification.
+
+---
+
+## Table of Contents
+
+- [CAPA Investigation Workflow](#capa-investigation-workflow)
+- [Root Cause Analysis](#root-cause-analysis)
+- [Corrective Action Planning](#corrective-action-planning)
+- [Effectiveness Verification](#effectiveness-verification)
+- [CAPA Metrics and Reporting](#capa-metrics-and-reporting)
+- [Reference Documentation](#reference-documentation)
+- [Tools](#tools)
+
+---
+
+## CAPA Investigation Workflow
+
+Conduct systematic CAPA investigation from initiation through closure:
+
+1. Document trigger event with objective evidence
+2. Assess significance and determine CAPA necessity
+3. Form investigation team with relevant expertise
+4. Collect data and evidence systematically
+5. Select and apply appropriate RCA methodology
+6. Identify root cause(s) with supporting evidence
+7. Develop corrective and preventive actions
+8. **Validation:** Root cause explains all symptoms; if eliminated, problem would not recur
+
+### CAPA Necessity Determination
+
+| Trigger Type | CAPA Required | Criteria |
+|--------------|---------------|----------|
+| Customer complaint (safety) | Yes | Any complaint involving patient/user safety |
+| Customer complaint (quality) | Evaluate | Based on severity and frequency |
+| Internal audit finding (Major) | Yes | Systematic failure or absence of element |
+| Internal audit finding (Minor) | Recommended | Isolated lapse or partial implementation |
+| Nonconformance (recurring) | Yes | Same NC type occurring 3+ times |
+| Nonconformance (isolated) | Evaluate | Based on severity and risk |
+| External audit finding | Yes | All Major and Minor findings |
+| Trend analysis | Evaluate | Based on trend significance |
+
+### Investigation Team Composition
+
+| CAPA Severity | Required Team Members |
+|---------------|----------------------|
+| Critical | CAPA Officer, Process Owner, QA Manager, Subject Matter Expert, Management Rep |
+| Major | CAPA Officer, Process Owner, Subject Matter Expert |
+| Minor | CAPA Officer, Process Owner |
+
+### Evidence Collection Checklist
+
+- [ ] Problem description with specific details (what, where, when, who, how much)
+- [ ] Timeline of events leading to issue
+- [ ] Relevant records and documentation
+- [ ] Interview notes from involved personnel
+- [ ] Photos or physical evidence (if applicable)
+- [ ] Related complaints, NCs, or previous CAPAs
+- [ ] Process parameters and specifications
+
+---
+
+## Root Cause Analysis
+
+Select and apply appropriate RCA methodology based on problem characteristics.
+
+### RCA Method Selection Decision Tree
+
+```
+Is the issue safety-critical or involves system reliability?
+├── Yes → Use FAULT TREE ANALYSIS
+└── No → Is human error the suspected primary cause?
+ ├── Yes → Use HUMAN FACTORS ANALYSIS
+ └── No → How many potential contributing factors?
+ ├── 1-2 factors (linear causation) → Use 5 WHY ANALYSIS
+ ├── 3-6 factors (complex, systemic) → Use FISHBONE DIAGRAM
+ └── Unknown/proactive assessment → Use FMEA
+```
+
+### 5 Why Analysis
+
+Use when: Single-cause issues with linear causation, process deviations with clear failure point.
+
+**Template:**
+
+```
+PROBLEM: [Clear, specific statement]
+
+WHY 1: Why did [problem] occur?
+BECAUSE: [First-level cause]
+EVIDENCE: [Supporting data]
+
+WHY 2: Why did [first-level cause] occur?
+BECAUSE: [Second-level cause]
+EVIDENCE: [Supporting data]
+
+WHY 3: Why did [second-level cause] occur?
+BECAUSE: [Third-level cause]
+EVIDENCE: [Supporting data]
+
+WHY 4: Why did [third-level cause] occur?
+BECAUSE: [Fourth-level cause]
+EVIDENCE: [Supporting data]
+
+WHY 5: Why did [fourth-level cause] occur?
+BECAUSE: [Root cause]
+EVIDENCE: [Supporting data]
+```
+
+**Example - Calibration Overdue:**
+
+```
+PROBLEM: pH meter (EQ-042) found 2 months overdue for calibration
+
+WHY 1: Why was calibration overdue?
+BECAUSE: Equipment was not on calibration schedule
+EVIDENCE: Calibration schedule reviewed, EQ-042 not listed
+
+WHY 2: Why was it not on the schedule?
+BECAUSE: Schedule not updated when equipment was purchased
+EVIDENCE: Purchase date 2023-06-15, schedule dated 2023-01-01
+
+WHY 3: Why was the schedule not updated?
+BECAUSE: No process requires schedule update at equipment purchase
+EVIDENCE: SOP-EQ-001 reviewed, no such requirement
+
+WHY 4: Why is there no such requirement?
+BECAUSE: Procedure written before equipment tracking was centralized
+EVIDENCE: SOP last revised 2019, equipment system implemented 2021
+
+WHY 5: Why has procedure not been updated?
+BECAUSE: Periodic review did not assess compatibility with new systems
+EVIDENCE: No review against new equipment system documented
+
+ROOT CAUSE: Procedure review process does not assess compatibility
+with organizational systems implemented after original procedure creation.
+```
+
+### Fishbone Diagram Categories (6M)
+
+| Category | Focus Areas | Typical Causes |
+|----------|-------------|----------------|
+| Man (People) | Training, competency, workload | Skill gaps, fatigue, communication |
+| Machine (Equipment) | Calibration, maintenance, age | Wear, malfunction, inadequate capacity |
+| Method (Process) | Procedures, work instructions | Unclear steps, missing controls |
+| Material | Specifications, suppliers, storage | Out-of-spec, degradation, contamination |
+| Measurement | Calibration, methods, interpretation | Instrument error, wrong method |
+| Mother Nature | Temperature, humidity, cleanliness | Environmental excursions |
+
+See `references/rca-methodologies.md` for complete method details and templates.
+
+### Root Cause Validation
+
+Before proceeding to action planning, validate root cause:
+
+- [ ] Root cause can be verified with objective evidence
+- [ ] If root cause is eliminated, problem would not recur
+- [ ] Root cause is within organizational control
+- [ ] Root cause explains all observed symptoms
+- [ ] No other significant causes remain unaddressed
+
+---
+
+## Corrective Action Planning
+
+Develop effective actions addressing identified root causes:
+
+1. Define immediate containment actions
+2. Develop corrective actions targeting root cause
+3. Identify preventive actions for similar processes
+4. Assign responsibilities and resources
+5. Establish timeline with milestones
+6. Define success criteria and verification method
+7. Document in CAPA action plan
+8. **Validation:** Actions directly address root cause; success criteria are measurable
+
+### Action Types
+
+| Type | Purpose | Timeline | Example |
+|------|---------|----------|---------|
+| Containment | Stop immediate impact | 24-72 hours | Quarantine affected product |
+| Correction | Fix the specific occurrence | 1-2 weeks | Rework or replace affected items |
+| Corrective | Eliminate root cause | 30-90 days | Revise procedure, add controls |
+| Preventive | Prevent in other areas | 60-120 days | Extend solution to similar processes |
+
+### Action Plan Components
+
+```
+ACTION PLAN TEMPLATE
+
+CAPA Number: [CAPA-XXXX]
+Root Cause: [Identified root cause]
+
+ACTION 1: [Specific action description]
+- Type: [ ] Containment [ ] Correction [ ] Corrective [ ] Preventive
+- Responsible: [Name, Title]
+- Due Date: [YYYY-MM-DD]
+- Resources: [Required resources]
+- Success Criteria: [Measurable outcome]
+- Verification Method: [How success will be verified]
+
+ACTION 2: [Specific action description]
+...
+
+IMPLEMENTATION TIMELINE:
+Week 1: [Milestone]
+Week 2: [Milestone]
+Week 4: [Milestone]
+Week 8: [Milestone]
+
+APPROVAL:
+CAPA Owner: _____________ Date: _______
+Process Owner: _____________ Date: _______
+QA Manager: _____________ Date: _______
+```
+
+### Action Effectiveness Indicators
+
+| Indicator | Target | Red Flag |
+|-----------|--------|----------|
+| Action scope | Addresses root cause completely | Treats only symptoms |
+| Specificity | Measurable deliverables | Vague commitments |
+| Timeline | Aggressive but achievable | No due dates or unrealistic |
+| Resources | Identified and allocated | Not specified |
+| Sustainability | Permanent solution | Temporary fix |
+
+---
+
+## Effectiveness Verification
+
+Verify corrective actions achieved intended results:
+
+1. Allow adequate implementation period (minimum 30-90 days)
+2. Collect post-implementation data
+3. Compare to pre-implementation baseline
+4. Evaluate against success criteria
+5. Verify no recurrence during verification period
+6. Document verification evidence
+7. Determine CAPA effectiveness
+8. **Validation:** All criteria met with objective evidence; no recurrence observed
+
+### Verification Timeline Guidelines
+
+| CAPA Severity | Wait Period | Verification Window |
+|---------------|-------------|---------------------|
+| Critical | 30 days | 30-90 days post-implementation |
+| Major | 60 days | 60-180 days post-implementation |
+| Minor | 90 days | 90-365 days post-implementation |
+
+### Verification Methods
+
+| Method | Use When | Evidence Required |
+|--------|----------|-------------------|
+| Data trend analysis | Quantifiable issues | Pre/post comparison, trend charts |
+| Process audit | Procedure compliance issues | Audit checklist, interview notes |
+| Record review | Documentation issues | Sample records, compliance rate |
+| Testing/inspection | Product quality issues | Test results, pass/fail data |
+| Interview/observation | Training issues | Interview notes, observation records |
+
+### Effectiveness Determination
+
+```
+Did recurrence occur during verification period?
+├── Yes → CAPA INEFFECTIVE (re-investigate root cause)
+└── No → Were all effectiveness criteria met?
+ ├── Yes → CAPA EFFECTIVE (proceed to closure)
+ └── No → Extent of gap?
+ ├── Minor gap → Extend verification or accept with justification
+ └── Significant gap → CAPA INEFFECTIVE (revise actions)
+```
+
+See `references/effectiveness-verification-guide.md` for detailed procedures.
+
+---
+
+## CAPA Metrics and Reporting
+
+Monitor CAPA program performance through key indicators.
+
+### Key Performance Indicators
+
+| Metric | Target | Calculation |
+|--------|--------|-------------|
+| CAPA cycle time | <60 days average | (Close Date - Open Date) / Number of CAPAs |
+| Overdue rate | <10% | Overdue CAPAs / Total Open CAPAs |
+| First-time effectiveness | >90% | Effective on first verification / Total verified |
+| Recurrence rate | <5% | Recurred issues / Total closed CAPAs |
+| Investigation quality | 100% root cause validated | Root causes validated / Total CAPAs |
+
+### Aging Analysis Categories
+
+| Age Bucket | Status | Action Required |
+|------------|--------|-----------------|
+| 0-30 days | On track | Monitor progress |
+| 31-60 days | Monitor | Review for delays |
+| 61-90 days | Warning | Escalate to management |
+| >90 days | Critical | Management intervention required |
+
+### Management Review Inputs
+
+Monthly CAPA status report includes:
+- Open CAPA count by severity and status
+- Overdue CAPA list with owners
+- Cycle time trends
+- Effectiveness rate trends
+- Source analysis (complaints, audits, NCs)
+- Recommendations for improvement
+
+---
+
+## Reference Documentation
+
+### Root Cause Analysis Methodologies
+
+`references/rca-methodologies.md` contains:
+
+- Method selection decision tree
+- 5 Why analysis template and example
+- Fishbone diagram categories and template
+- Fault Tree Analysis for safety-critical issues
+- Human Factors Analysis for people-related causes
+- FMEA for proactive risk assessment
+- Hybrid approach guidance
+
+### Effectiveness Verification Guide
+
+`references/effectiveness-verification-guide.md` contains:
+
+- Verification planning requirements
+- Verification method selection
+- Effectiveness criteria definition (SMART)
+- Closure requirements by severity
+- Ineffective CAPA process
+- Documentation templates
+
+---
+
+## Tools
+
+### CAPA Tracker
+
+```bash
+# Generate CAPA status report
+python scripts/capa_tracker.py --capas capas.json
+
+# Interactive mode for manual entry
+python scripts/capa_tracker.py --interactive
+
+# JSON output for integration
+python scripts/capa_tracker.py --capas capas.json --output json
+
+# Generate sample data file
+python scripts/capa_tracker.py --sample > sample_capas.json
+```
+
+Calculates and reports:
+- Summary metrics (open, closed, overdue, cycle time, effectiveness)
+- Status distribution
+- Severity and source analysis
+- Aging report by time bucket
+- Overdue CAPA list
+- Actionable recommendations
+
+### Sample CAPA Input
+
+```json
+{
+ "capas": [
+ {
+ "capa_number": "CAPA-2024-001",
+ "title": "Calibration overdue for pH meter",
+ "description": "pH meter EQ-042 found 2 months overdue",
+ "source": "AUDIT",
+ "severity": "MAJOR",
+ "status": "VERIFICATION",
+ "open_date": "2024-06-15",
+ "target_date": "2024-08-15",
+ "owner": "J. Smith",
+ "root_cause": "Procedure review gap",
+ "corrective_action": "Updated SOP-EQ-001"
+ }
+ ]
+}
+```
+
+---
+
+## Regulatory Requirements
+
+### ISO 13485:2016 Clause 8.5
+
+| Sub-clause | Requirement | Key Activities |
+|------------|-------------|----------------|
+| 8.5.2 Corrective Action | Eliminate cause of nonconformity | NC review, cause determination, action evaluation, implementation, effectiveness review |
+| 8.5.3 Preventive Action | Eliminate potential nonconformity | Trend analysis, cause determination, action evaluation, implementation, effectiveness review |
+
+### FDA 21 CFR 820.100
+
+Required CAPA elements:
+- Procedures for implementing corrective and preventive action
+- Analyzing quality data sources (complaints, NCs, audits, service records)
+- Investigating cause of nonconformities
+- Identifying actions needed to correct and prevent recurrence
+- Verifying actions are effective and do not adversely affect device
+- Submitting relevant information for management review
+
+### Common FDA 483 Observations
+
+| Observation | Root Cause Pattern |
+|-------------|-------------------|
+| CAPA not initiated for recurring issue | Trend analysis not performed |
+| Root cause analysis superficial | Inadequate investigation training |
+| Effectiveness not verified | No verification procedure |
+| Actions do not address root cause | Symptom treatment vs. cause elimination |
diff --git a/skills/capa-officer/_meta.json b/skills/capa-officer/_meta.json
new file mode 100644
index 00000000..c9872861
--- /dev/null
+++ b/skills/capa-officer/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "capa-officer",
+ "displayName": "Capa Officer",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773070378237,
+ "commit": "https://github.com/openclaw/skills/commit/f484fb8d06ecf7cc57a9ca9213113fca0403626f"
+ },
+ "history": [
+ {
+ "version": "1.0.0",
+ "publishedAt": 1770402616869,
+ "commit": "https://github.com/openclaw/skills/commit/57da737383d1fb19504dc8cbc3e0c590c4c67d10"
+ }
+ ]
+}
diff --git a/skills/capa-officer/references/effectiveness-verification-guide.md b/skills/capa-officer/references/effectiveness-verification-guide.md
new file mode 100644
index 00000000..ff21c719
--- /dev/null
+++ b/skills/capa-officer/references/effectiveness-verification-guide.md
@@ -0,0 +1,462 @@
+# Effectiveness Verification Guide
+
+CAPA effectiveness assessment procedures, verification methods, and closure criteria.
+
+---
+
+## Table of Contents
+
+- [Verification Planning](#verification-planning)
+- [Verification Methods](#verification-methods)
+- [Effectiveness Criteria](#effectiveness-criteria)
+- [Closure Requirements](#closure-requirements)
+- [Ineffective CAPA Process](#ineffective-capa-process)
+- [Documentation Templates](#documentation-templates)
+
+---
+
+## Verification Planning
+
+### When to Plan Verification
+
+Verification planning must occur BEFORE corrective action implementation:
+
+| Stage | Planning Activity | Owner |
+|-------|-------------------|-------|
+| CAPA Initiation | Define preliminary verification approach | CAPA Owner |
+| Root Cause Analysis | Refine criteria based on root cause | Investigation Team |
+| Action Planning | Finalize verification method and timeline | CAPA Owner |
+| Implementation | Schedule verification activities | Quality Assurance |
+
+### Verification Timeline Guidelines
+
+| CAPA Severity | Minimum Wait Period | Verification Window |
+|---------------|---------------------|---------------------|
+| Critical (Safety) | 30 days | 30-90 days post-implementation |
+| Major | 60 days | 60-180 days post-implementation |
+| Minor | 90 days | 90-365 days post-implementation |
+
+**Rationale**: Waiting period ensures sufficient data collection and accounts for process variation.
+
+### Verification Plan Components
+
+```
+VERIFICATION PLAN TEMPLATE
+
+CAPA Number: [CAPA-XXXX]
+Problem Statement: [Original issue]
+Root Cause: [Identified root cause]
+Corrective Action: [Implemented action]
+
+VERIFICATION METHOD:
+[ ] Data Trend Analysis
+[ ] Process Audit
+[ ] Record Review
+[ ] Testing/Inspection
+[ ] Interview/Observation
+[ ] Multiple Methods (specify)
+
+EFFECTIVENESS CRITERIA:
+1. [Measurable criterion 1]
+2. [Measurable criterion 2]
+3. [Measurable criterion 3]
+
+SUCCESS THRESHOLD:
+- [Quantitative threshold, e.g., "Zero recurrence for 90 days"]
+- [Qualitative threshold, e.g., "Procedure followed correctly 100%"]
+
+DATA COLLECTION:
+- Source: [Where data will come from]
+- Sample Size: [Number of records/instances to review]
+- Time Period: [Start and end dates]
+- Responsible: [Who collects data]
+
+VERIFICATION SCHEDULE:
+- Implementation Complete: [Date]
+- Waiting Period Ends: [Date]
+- Verification Start: [Date]
+- Verification Complete: [Date]
+- Report Due: [Date]
+
+APPROVAL:
+CAPA Owner: _____________ Date: _______
+Quality Assurance: _____________ Date: _______
+```
+
+---
+
+## Verification Methods
+
+### 1. Data Trend Analysis
+
+**Best for:** Quantifiable issues with measurable outcomes (defect rates, cycle times, complaint trends)
+
+**Procedure:**
+1. Collect post-implementation data for defined period
+2. Compare to pre-implementation baseline
+3. Apply statistical analysis if sample size permits
+4. Document trend direction and magnitude
+
+**Example Criteria:**
+- Defect rate reduced by ≥50% from baseline
+- Zero recurrence of specific failure mode
+- Process capability (Cpk) improved to ≥1.33
+
+**Evidence Required:**
+- Pre-implementation baseline data
+- Post-implementation trend data
+- Statistical analysis (if applicable)
+- Trend charts with annotation
+
+### 2. Process Audit
+
+**Best for:** Procedure compliance issues, process control failures, systemic problems
+
+**Procedure:**
+1. Develop audit checklist based on corrective action
+2. Conduct unannounced process audit
+3. Interview operators and supervisors
+4. Review records generated since implementation
+5. Document compliance percentage
+
+**Example Criteria:**
+- 100% compliance with revised procedure
+- All operators demonstrate competency
+- No deviations observed during audit
+
+**Evidence Required:**
+- Audit checklist completed
+- Interview notes
+- Record samples reviewed
+- Photos/observations (if applicable)
+
+### 3. Record Review
+
+**Best for:** Documentation issues, completeness problems, traceability failures
+
+**Procedure:**
+1. Define sample size based on volume (minimum 10 or 10%, whichever greater)
+2. Review records generated post-implementation
+3. Evaluate against specified requirements
+4. Calculate compliance rate
+
+**Example Criteria:**
+- 100% of records meet completeness requirements
+- All required signatures present
+- Traceability maintained throughout
+
+**Evidence Required:**
+- List of records reviewed
+- Compliance checklist results
+- Non-compliance summary (if any)
+
+### 4. Testing/Inspection
+
+**Best for:** Product quality issues, equipment failures, specification non-conformances
+
+**Procedure:**
+1. Define test protocol based on corrective action
+2. Conduct testing on post-implementation units
+3. Compare results to acceptance criteria
+4. Document pass/fail rates
+
+**Example Criteria:**
+- 100% of units pass revised inspection criteria
+- All test results within specification
+- Zero failures of targeted parameter
+
+**Evidence Required:**
+- Test protocol/method
+- Test results data
+- Pass/fail summary
+- Comparison to pre-implementation results
+
+### 5. Interview/Observation
+
+**Best for:** Training issues, communication problems, human factors causes
+
+**Procedure:**
+1. Develop structured interview questions
+2. Interview representative sample of affected personnel
+3. Observe process execution in real-time
+4. Document responses and observations
+
+**Example Criteria:**
+- All interviewed personnel demonstrate knowledge
+- Observed practices match documented procedure
+- No unsafe acts or workarounds observed
+
+**Evidence Required:**
+- Interview questions and responses
+- Observation notes
+- Training records (supporting)
+
+---
+
+## Effectiveness Criteria
+
+### Defining Good Criteria
+
+Criteria must be **SMART**:
+
+| Element | Requirement | Example |
+|---------|-------------|---------|
+| **S**pecific | Clearly defined what to measure | "Calibration overdue rate" not "equipment issues" |
+| **M**easurable | Quantifiable or objectively verifiable | "<2% overdue rate" not "improved timeliness" |
+| **A**chievable | Realistic given the corrective action | Within capability of implemented solution |
+| **R**elevant | Directly related to root cause | Addresses the actual problem |
+| **T**ime-bound | Specified evaluation period | "For 90 consecutive days" |
+
+### Criteria by Issue Type
+
+| Issue Type | Typical Criteria | Threshold |
+|------------|------------------|-----------|
+| Nonconformance | Recurrence rate | Zero recurrence |
+| Process deviation | Compliance rate | ≥95% compliance |
+| Complaint | Complaint trend | ≥50% reduction |
+| Calibration | Overdue rate | <2% overdue |
+| Training | Competency pass rate | 100% pass |
+| Documentation | Completeness rate | 100% complete |
+| Supplier | Incoming reject rate | ≤1% reject rate |
+
+### Sample Size Guidelines
+
+| Population Size | Minimum Sample |
+|-----------------|----------------|
+| <10 | All (100%) |
+| 10-50 | 10 |
+| 51-100 | 15 |
+| 101-500 | 20 |
+| >500 | 25 or 10%, whichever less |
+
+---
+
+## Closure Requirements
+
+### Closure Checklist
+
+**CAPA Closure Prerequisites:**
+
+- [ ] All corrective actions implemented
+- [ ] Implementation evidence documented
+- [ ] Verification waiting period complete
+- [ ] Verification activities performed
+- [ ] All effectiveness criteria met
+- [ ] Verification evidence documented
+- [ ] No recurrence during verification period
+- [ ] CAPA owner review complete
+- [ ] Quality Assurance review complete
+- [ ] Documentation complete and filed
+
+### Effectiveness Status Determination
+
+```
+EFFECTIVENESS DECISION TREE:
+
+Did recurrence occur during verification period?
+├── Yes → CAPA INEFFECTIVE (escalate per ineffective process)
+└── No → Were all effectiveness criteria met?
+ ├── Yes → Were any related issues identified?
+ │ ├── Yes → Open new CAPA if needed, close original
+ │ └── No → CAPA EFFECTIVE - proceed to closure
+ └── No → How many criteria missed?
+ ├── Minor gap (1 criterion, marginal miss) →
+ │ Extend verification period OR accept with justification
+ └── Significant gap → CAPA INEFFECTIVE
+
+EFFECTIVENESS DETERMINATION:
+[ ] EFFECTIVE - All criteria met, no recurrence
+[ ] EFFECTIVE WITH CONDITIONS - Minor gap, justified acceptance
+[ ] INEFFECTIVE - Significant gaps or recurrence
+```
+
+### Closure Documentation
+
+```
+EFFECTIVENESS VERIFICATION REPORT
+
+CAPA Number: [CAPA-XXXX]
+Verification Complete Date: [Date]
+Verified By: [Name, Title]
+
+VERIFICATION SUMMARY:
+| Criterion | Target | Actual | Status |
+|-----------|--------|--------|--------|
+| [Criterion 1] | [Target] | [Result] | ☑ Met / ☐ Not Met |
+| [Criterion 2] | [Target] | [Result] | ☑ Met / ☐ Not Met |
+| [Criterion 3] | [Target] | [Result] | ☑ Met / ☐ Not Met |
+
+RECURRENCE CHECK:
+- Recurrence during verification period: [ ] Yes [ ] No
+- Related issues identified: [ ] Yes [ ] No
+- If yes, describe: [Description]
+
+EVIDENCE SUMMARY:
+[List of evidence documents, record numbers, data sources]
+
+EFFECTIVENESS DETERMINATION:
+[ ] EFFECTIVE
+[ ] EFFECTIVE WITH CONDITIONS: [Justification]
+[ ] INEFFECTIVE: [Reason]
+
+RECOMMENDED ACTION:
+[ ] Close CAPA
+[ ] Extend verification period to [Date]
+[ ] Open new CAPA [CAPA-XXXX] for [Issue]
+[ ] Re-investigate (return to root cause analysis)
+
+APPROVALS:
+CAPA Owner: _____________ Date: _______
+Quality Assurance: _____________ Date: _______
+Management (if Major/Critical): _____________ Date: _______
+```
+
+---
+
+## Ineffective CAPA Process
+
+### Definition of Ineffective
+
+CAPA is ineffective when:
+1. Original problem recurs during or after verification period
+2. Effectiveness criteria not met
+3. Root cause still present
+4. Corrective action created new problems
+
+### Ineffective CAPA Workflow
+
+```
+INEFFECTIVE CAPA DETECTED
+ │
+ ├── 1. Immediate Actions
+ │ ├── Reopen CAPA (do not close as effective)
+ │ ├── Implement containment for recurrence
+ │ └── Notify CAPA owner and management
+ │
+ ├── 2. Root Cause Re-evaluation
+ │ ├── Was original root cause correct?
+ │ │ ├── No → Conduct new root cause analysis
+ │ │ └── Yes → Was corrective action appropriate?
+ │ │ ├── No → Develop new corrective action
+ │ │ └── Yes → Was implementation adequate?
+ │ │ ├── No → Re-implement with improvements
+ │ │ └── Yes → Escalate (systemic issue)
+ │
+ ├── 3. Escalation Criteria
+ │ ├── Second ineffective attempt → Management review required
+ │ ├── Safety-related recurrence → Immediate escalation
+ │ └── Pattern across multiple CAPAs → Systemic CAPA
+ │
+ └── 4. Documentation
+ ├── Document ineffective status with evidence
+ ├── Record re-investigation results
+ ├── Update CAPA metrics/trending
+ └── Include in management review
+```
+
+### Preventing Ineffective CAPAs
+
+| Common Cause | Prevention |
+|--------------|------------|
+| Superficial root cause | Validate root cause before action |
+| Action addresses symptom not cause | Ensure action targets root cause |
+| Implementation incomplete | Verify implementation before verification |
+| Insufficient verification period | Allow adequate time for data collection |
+| Wrong verification method | Match method to issue type |
+| Unclear success criteria | Define SMART criteria upfront |
+
+---
+
+## Documentation Templates
+
+### Verification Evidence Log
+
+```
+VERIFICATION EVIDENCE LOG
+
+CAPA Number: [CAPA-XXXX]
+
+| Doc/Record # | Description | Date | Reviewed By | Finding |
+|--------------|-------------|------|-------------|---------|
+| [Number] | [Description] | [Date] | [Reviewer] | [Compliant/Finding] |
+| [Number] | [Description] | [Date] | [Reviewer] | [Compliant/Finding] |
+
+SUMMARY:
+- Total records reviewed: [Number]
+- Compliant: [Number] ([Percentage]%)
+- Non-compliant: [Number] ([Percentage]%)
+
+CONCLUSION:
+[Statement on whether evidence supports effectiveness]
+```
+
+### Trend Analysis Summary
+
+```
+TREND ANALYSIS FOR CAPA VERIFICATION
+
+CAPA Number: [CAPA-XXXX]
+Metric: [What is being measured]
+
+BASELINE (Pre-Implementation):
+- Period: [Start] to [End]
+- Value: [Baseline value]
+- Data points: [Number]
+
+POST-IMPLEMENTATION:
+- Period: [Start] to [End]
+- Value: [Current value]
+- Data points: [Number]
+
+CHANGE:
+- Absolute change: [Value]
+- Percentage change: [Percentage]%
+- Target: [Target value/change]
+- Status: [ ] Met [ ] Not Met
+
+TREND CHART:
+[Include or reference trend chart showing before/after comparison]
+
+STATISTICAL SIGNIFICANCE (if applicable):
+- Method: [t-test, chi-square, etc.]
+- p-value: [Value]
+- Conclusion: [Statistically significant / Not significant]
+```
+
+### Interview Summary Template
+
+```
+VERIFICATION INTERVIEW SUMMARY
+
+CAPA Number: [CAPA-XXXX]
+Interviewer: [Name]
+Date: [Date]
+
+INTERVIEWEE:
+- Name: [Name]
+- Role: [Job title]
+- Department: [Department]
+- Experience: [Years in role]
+
+QUESTIONS AND RESPONSES:
+
+Q1: [Question about awareness of change]
+A1: [Response summary]
+Knowledge demonstrated: [ ] Yes [ ] Partial [ ] No
+
+Q2: [Question about implementation of change]
+A2: [Response summary]
+Compliance demonstrated: [ ] Yes [ ] Partial [ ] No
+
+Q3: [Question about understanding rationale]
+A3: [Response summary]
+Understanding demonstrated: [ ] Yes [ ] Partial [ ] No
+
+OBSERVATION NOTES:
+[Any relevant observations during interview]
+
+CONCLUSION:
+[ ] Interviewee demonstrates full knowledge and compliance
+[ ] Interviewee demonstrates partial knowledge (specify gaps)
+[ ] Interviewee does not demonstrate required knowledge
+```
diff --git a/skills/capa-officer/references/rca-methodologies.md b/skills/capa-officer/references/rca-methodologies.md
new file mode 100644
index 00000000..a02c1098
--- /dev/null
+++ b/skills/capa-officer/references/rca-methodologies.md
@@ -0,0 +1,455 @@
+# Root Cause Analysis Methodologies
+
+Decision criteria, templates, and implementation guidance for RCA techniques.
+
+---
+
+## Table of Contents
+
+- [Method Selection Matrix](#method-selection-matrix)
+- [5 Why Analysis](#5-why-analysis)
+- [Fishbone Diagram](#fishbone-diagram)
+- [Fault Tree Analysis](#fault-tree-analysis)
+- [Human Factors Analysis](#human-factors-analysis)
+- [Failure Mode and Effects Analysis](#failure-mode-and-effects-analysis)
+- [Selecting the Right Method](#selecting-the-right-method)
+
+---
+
+## Method Selection Matrix
+
+### When to Use Each Method
+
+| Method | Use When | Problem Type | Team Size | Time Required |
+|--------|----------|--------------|-----------|---------------|
+| 5 Why | Single-cause issues, process deviations | Linear causation | 1-3 people | 30-60 min |
+| Fishbone | Multi-factor problems, 3-6 contributing factors | Complex, systemic | 3-8 people | 2-4 hours |
+| Fault Tree | Safety-critical failures, reliability issues | System failures | 2-5 people | 4-8 hours |
+| Human Factors | Procedure/training-related issues | Human error | 3-6 people | 2-4 hours |
+| FMEA | Systematic risk assessment, design review | Potential failures | 4-10 people | 8-16 hours |
+
+### Quick Selection Decision Tree
+
+```
+Is the issue safety-critical or involves system reliability?
+├── Yes → Use FAULT TREE ANALYSIS
+└── No → Is human error the suspected primary cause?
+ ├── Yes → Use HUMAN FACTORS ANALYSIS
+ └── No → How many potential contributing factors?
+ ├── 1-2 factors → Use 5 WHY ANALYSIS
+ ├── 3-6 factors → Use FISHBONE DIAGRAM
+ └── Unknown/Many → Use FMEA (proactive) or Fishbone (reactive)
+```
+
+---
+
+## 5 Why Analysis
+
+### Overview
+
+Simple, iterative technique asking "why" repeatedly (typically 5 times) to drill from symptoms to root cause.
+
+### When to Use
+
+- Single-cause issues with linear causation
+- Process deviations with clear failure point
+- Quick investigations requiring rapid resolution
+- Problems where symptoms clearly link to cause
+
+### When NOT to Use
+
+- Complex multi-factor problems
+- Safety-critical incidents requiring comprehensive analysis
+- Issues with multiple interacting causes
+- When systemic factors are suspected
+
+### 5 Why Template
+
+```
+PROBLEM STATEMENT:
+[Clear, specific description of what happened, when, where, and impact]
+
+WHY 1: Why did [problem] occur?
+BECAUSE: [First-level cause]
+EVIDENCE: [Data/observation supporting this cause]
+
+WHY 2: Why did [first-level cause] occur?
+BECAUSE: [Second-level cause]
+EVIDENCE: [Data/observation supporting this cause]
+
+WHY 3: Why did [second-level cause] occur?
+BECAUSE: [Third-level cause]
+EVIDENCE: [Data/observation supporting this cause]
+
+WHY 4: Why did [third-level cause] occur?
+BECAUSE: [Fourth-level cause]
+EVIDENCE: [Data/observation supporting this cause]
+
+WHY 5: Why did [fourth-level cause] occur?
+BECAUSE: [Root cause - typically systemic or management system failure]
+EVIDENCE: [Data/observation supporting this cause]
+
+ROOT CAUSE VALIDATION:
+- [ ] Can the root cause be verified with evidence?
+- [ ] If root cause is eliminated, would problem recur?
+- [ ] Is the root cause within organizational control?
+- [ ] Does the root cause explain all symptoms?
+```
+
+### Example: Calibration Overdue
+
+```
+PROBLEM: pH meter (EQ-042) found 2 months overdue for calibration
+
+WHY 1: Why was calibration overdue?
+BECAUSE: The equipment was not on the calibration schedule
+EVIDENCE: Calibration schedule reviewed, EQ-042 not listed
+
+WHY 2: Why was it not on the calibration schedule?
+BECAUSE: The schedule was not updated when equipment was purchased
+EVIDENCE: Purchase date 2023-06-15, schedule dated 2023-01-01
+
+WHY 3: Why was the schedule not updated?
+BECAUSE: No process requires schedule update at equipment purchase
+EVIDENCE: Equipment procedure SOP-EQ-001 reviewed, no such requirement
+
+WHY 4: Why is there no requirement to update the schedule?
+BECAUSE: The procedure was written before equipment tracking was centralized
+EVIDENCE: SOP-EQ-001 last revised 2019, equipment system implemented 2021
+
+WHY 5: Why has the procedure not been updated?
+BECAUSE: Periodic procedure review did not assess compatibility with new systems
+EVIDENCE: No documented review of SOP-EQ-001 against new equipment system
+
+ROOT CAUSE: Procedure review process does not assess compatibility
+with organizational systems implemented after original procedure creation
+```
+
+---
+
+## Fishbone Diagram
+
+### Overview
+
+Also called Ishikawa or cause-and-effect diagram. Organizes potential causes into categories branching from the problem statement.
+
+### Standard Categories (6M)
+
+| Category | Focus Areas | Typical Causes |
+|----------|-------------|----------------|
+| **Man** (People) | Training, competency, workload | Skill gaps, fatigue, communication |
+| **Machine** (Equipment) | Calibration, maintenance, age | Wear, malfunction, inadequate capacity |
+| **Method** (Process) | Procedures, work instructions | Unclear steps, missing controls |
+| **Material** | Specifications, suppliers, storage | Out-of-spec, degradation, contamination |
+| **Measurement** | Calibration, methods, interpretation | Instrument error, wrong method |
+| **Mother Nature** (Environment) | Temperature, humidity, cleanliness | Environmental excursions |
+
+### Fishbone Template
+
+```
+PROBLEM STATEMENT: [Effect being investigated]
+
+ ┌── Man ────────────────┐
+ │ ├─ [Cause 1] │
+ │ ├─ [Cause 2] │
+ │ └─ [Cause 3] │
+ │ │
+┌── Machine ────────┤ ├── Method ──────────┐
+│ ├─ [Cause 1] │ │ ├─ [Cause 1] │
+│ ├─ [Cause 2] │ PROBLEM │ ├─ [Cause 2] │
+│ └─ [Cause 3] ├───────────────────────┤ └─ [Cause 3] │
+│ │ │ │
+├── Material ───────┤ ├── Measurement ─────┤
+│ ├─ [Cause 1] │ │ ├─ [Cause 1] │
+│ ├─ [Cause 2] │ │ ├─ [Cause 2] │
+│ └─ [Cause 3] │ │ └─ [Cause 3] │
+ │ │
+ └── Environment ────────┘
+ ├─ [Cause 1]
+ ├─ [Cause 2]
+ └─ [Cause 3]
+
+CAUSE PRIORITIZATION:
+| Cause | Category | Likelihood | Evidence | Priority |
+|-------|----------|------------|----------|----------|
+| [Cause A] | Method | High | [Evidence] | 1 |
+| [Cause B] | Man | Medium | [Evidence] | 2 |
+
+ROOT CAUSES IDENTIFIED:
+1. [Primary root cause with supporting evidence]
+2. [Contributing cause with supporting evidence]
+```
+
+### Facilitation Guidelines
+
+1. Assemble cross-functional team (3-8 people)
+2. Define problem statement clearly before starting
+3. Brainstorm causes without judgment first
+4. Organize into categories after brainstorming
+5. Drill down on each major cause (sub-causes)
+6. Prioritize based on evidence and likelihood
+7. Validate top causes with data
+
+---
+
+## Fault Tree Analysis
+
+### Overview
+
+Top-down, deductive analysis starting with undesired event and systematically identifying all potential causes using Boolean logic (AND/OR gates).
+
+### When to Use
+
+- Safety-critical system failures
+- Complex system reliability analysis
+- Events with multiple failure pathways
+- Regulatory-required investigations (FDA, MDR)
+
+### FTA Symbols
+
+| Symbol | Name | Meaning |
+|--------|------|---------|
+| Rectangle | Top Event / Intermediate Event | Undesired event or intermediate fault |
+| Circle | Basic Event | Primary fault requiring no further analysis |
+| Diamond | Undeveloped Event | Event not fully analyzed (data limitation) |
+| AND Gate | Requires all inputs | All child events must occur for parent |
+| OR Gate | Requires any input | Any child event causes parent |
+
+### FTA Template
+
+```
+TOP EVENT: [Undesired event under investigation]
+
+LEVEL 1 (Immediate Causes):
+[Top Event]
+ │
+ └── OR GATE ──┬── [Cause 1.1]
+ ├── [Cause 1.2]
+ └── [Cause 1.3]
+
+LEVEL 2 (Contributing Causes):
+[Cause 1.1]
+ │
+ └── AND GATE ──┬── [Cause 2.1]
+ └── [Cause 2.2]
+
+MINIMAL CUT SETS:
+(Combinations of basic events that cause top event)
+1. {Basic Event A, Basic Event B} ← Both required (AND)
+2. {Basic Event C} ← Single point failure (OR)
+3. {Basic Event D, Basic Event E} ← Both required (AND)
+
+CRITICAL PATH ANALYSIS:
+Most likely failure pathway: [Description]
+Single points of failure: [List]
+
+RECOMMENDATIONS:
+- Address single points of failure first
+- Add redundancy where AND gates show vulnerability
+- Prioritize controls on highest probability paths
+```
+
+### Cut Set Analysis
+
+Minimal cut sets identify the smallest combination of basic events causing the top event:
+
+- **Single-element cut sets**: Single points of failure (highest priority)
+- **Two-element cut sets**: Dual failure scenarios
+- **Probability calculation**: P(Top Event) = Union of P(Cut Sets)
+
+---
+
+## Human Factors Analysis
+
+### Overview
+
+Systematic analysis of human error focusing on cognitive, physical, and organizational factors contributing to performance failures.
+
+### HFACS Categories
+
+Human Factors Analysis and Classification System:
+
+| Level | Category | Examples |
+|-------|----------|----------|
+| **Unsafe Acts** | Errors, violations | Skill-based, decision, perceptual errors |
+| **Preconditions** | Conditions for unsafe acts | Fatigue, mental state, CRM, physical environment |
+| **Unsafe Supervision** | Supervisory failures | Inadequate supervision, planned inappropriate ops |
+| **Organizational Influences** | Organizational failures | Resource management, organizational climate |
+
+### Human Error Types
+
+| Type | Description | Example | Mitigation |
+|------|-------------|---------|------------|
+| Slip | Execution error in routine task | Wrong button pressed | Error-proofing, forcing functions |
+| Lapse | Memory failure | Forgot step in procedure | Checklists, reminders |
+| Mistake | Planning/decision error | Wrong procedure selected | Training, decision aids |
+| Violation | Intentional deviation | Skipped step to save time | Culture change, supervision |
+
+### Human Factors Investigation Template
+
+```
+INCIDENT DESCRIPTION:
+[What happened, who was involved, when, where]
+
+UNSAFE ACTS ANALYSIS:
+Type of Error: [ ] Slip [ ] Lapse [ ] Mistake [ ] Violation
+Description: [Specific action or inaction]
+Task Being Performed: [Activity at time of error]
+Experience Level: [Novice/Intermediate/Expert]
+
+PRECONDITIONS FOR UNSAFE ACTS:
+Cognitive Factors:
+- [ ] Task complexity exceeded capability
+- [ ] Time pressure
+- [ ] Distraction/interruption
+- [ ] Mental fatigue
+
+Physical Factors:
+- [ ] Physical fatigue
+- [ ] Inadequate lighting
+- [ ] Noise interference
+- [ ] Workspace ergonomics
+
+Team Factors:
+- [ ] Communication breakdown
+- [ ] Coordination failure
+- [ ] Inadequate leadership
+
+SUPERVISORY FACTORS:
+- [ ] Inadequate supervision
+- [ ] Failed to correct known problem
+- [ ] Inappropriate staffing
+- [ ] Authorized unnecessary risk
+
+ORGANIZATIONAL FACTORS:
+- [ ] Resource management deficiency
+- [ ] Organizational process issue
+- [ ] Organizational culture/climate
+
+ROOT CAUSE(S):
+[Human factors root causes identified]
+
+CORRECTIVE ACTIONS:
+| Action | Target Factor | Priority |
+|--------|---------------|----------|
+| [Action 1] | [Factor addressed] | High |
+| [Action 2] | [Factor addressed] | Medium |
+```
+
+---
+
+## Failure Mode and Effects Analysis
+
+### Overview
+
+Proactive, systematic technique identifying potential failure modes, their causes, and effects before failures occur.
+
+### FMEA Types
+
+| Type | Application | Scope |
+|------|-------------|-------|
+| Design FMEA (DFMEA) | Product design | Component and system design failures |
+| Process FMEA (PFMEA) | Manufacturing process | Process step failures |
+| System FMEA | System-level analysis | System interaction failures |
+
+### Risk Priority Number (RPN)
+
+RPN = Severity (S) × Occurrence (O) × Detection (D)
+
+**Severity Scale (1-10):**
+
+| Rating | Effect | Criteria |
+|--------|--------|----------|
+| 10 | Hazardous | Failure affects safe operation, no warning |
+| 8-9 | Very High | Primary function lost, high impact |
+| 6-7 | High | Performance degraded, customer dissatisfied |
+| 4-5 | Moderate | Some performance loss, moderate impact |
+| 2-3 | Low | Minor effect, slight inconvenience |
+| 1 | None | No discernible effect |
+
+**Occurrence Scale (1-10):**
+
+| Rating | Likelihood | Failure Rate |
+|--------|------------|--------------|
+| 10 | Very High | >1 in 10 |
+| 7-9 | High | 1 in 20 - 1 in 100 |
+| 4-6 | Moderate | 1 in 400 - 1 in 2,000 |
+| 2-3 | Low | 1 in 15,000 - 1 in 150,000 |
+| 1 | Remote | <1 in 1,500,000 |
+
+**Detection Scale (1-10):**
+
+| Rating | Detection | Criteria |
+|--------|-----------|----------|
+| 10 | Absolute Uncertainty | No inspection/control, defect will reach customer |
+| 7-9 | Very Remote to Remote | Controls unlikely to detect |
+| 4-6 | Moderate | Controls may detect |
+| 2-3 | High | Controls likely to detect |
+| 1 | Almost Certain | Controls will almost certainly detect |
+
+### FMEA Template
+
+```
+PROCESS/PRODUCT: [Name]
+FMEA TEAM: [Members]
+DATE: [Date]
+
+| Item/Step | Failure Mode | Effect | S | Cause | O | Controls | D | RPN | Action |
+|-----------|--------------|--------|---|-------|---|----------|---|-----|--------|
+| [Item 1] | [How it fails] | [Impact] | 8 | [Why] | 4 | [Current] | 6 | 192 | [Action] |
+| [Item 2] | [How it fails] | [Impact] | 6 | [Why] | 3 | [Current] | 4 | 72 | [Action] |
+
+RPN THRESHOLD: Actions required for RPN > [threshold]
+HIGH SEVERITY RULE: Actions required for S >= 9 regardless of RPN
+
+ACTION PRIORITIZATION:
+1. Address all items with S >= 9 first
+2. Address items with highest RPN
+3. Focus on reducing Occurrence (prevention)
+4. Then improve Detection (inspection)
+```
+
+---
+
+## Selecting the Right Method
+
+### Decision Flowchart
+
+```
+START: Investigation Required
+ │
+ ├── Is this a proactive assessment (no failure yet)?
+ │ └── Yes → Use FMEA
+ │
+ ├── Is the issue safety-critical?
+ │ └── Yes → Use FAULT TREE ANALYSIS
+ │
+ ├── Is human error the primary concern?
+ │ └── Yes → Use HUMAN FACTORS ANALYSIS
+ │
+ ├── Are there multiple contributing factors (3+)?
+ │ ├── Yes → Use FISHBONE DIAGRAM
+ │ └── No → Use 5 WHY ANALYSIS
+ │
+ └── Uncertain? → Start with 5 WHY, escalate to FISHBONE if needed
+```
+
+### Hybrid Approach
+
+For complex investigations, combine methods:
+
+1. **Initial screening**: 5 Why for quick cause identification
+2. **Detailed analysis**: Fishbone to explore all categories
+3. **Validation**: Fault Tree for critical failure paths
+4. **Systemic factors**: Human Factors for people-related causes
+5. **Prevention**: FMEA for future risk mitigation
+
+### Documentation Requirements
+
+| Method | Required Outputs | Retention |
+|--------|------------------|-----------|
+| 5 Why | Completed template with evidence | CAPA record |
+| Fishbone | Diagram + prioritized causes | CAPA record |
+| Fault Tree | FTA diagram + cut set analysis | DHF/CAPA record |
+| Human Factors | HFACS analysis + actions | CAPA record |
+| FMEA | FMEA worksheet + action tracking | Design file |
diff --git a/skills/capa-officer/scripts/capa_tracker.py b/skills/capa-officer/scripts/capa_tracker.py
new file mode 100644
index 00000000..5769b973
--- /dev/null
+++ b/skills/capa-officer/scripts/capa_tracker.py
@@ -0,0 +1,638 @@
+#!/usr/bin/env python3
+"""
+CAPA Tracker - Corrective and Preventive Action Management Tool
+
+Tracks CAPA status, calculates metrics, identifies overdue items,
+and generates reports for management review.
+
+Usage:
+ python capa_tracker.py --capas capas.json
+ python capa_tracker.py --interactive
+ python capa_tracker.py --capas capas.json --output json
+"""
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timedelta
+from typing import List, Dict, Optional
+from enum import Enum
+
+
+class CAPAStatus(Enum):
+ OPEN = "Open"
+ INVESTIGATION = "Investigation"
+ ACTION_PLANNING = "Action Planning"
+ IMPLEMENTATION = "Implementation"
+ VERIFICATION = "Verification"
+ CLOSED_EFFECTIVE = "Closed - Effective"
+ CLOSED_INEFFECTIVE = "Closed - Ineffective"
+
+
+class CAPASeverity(Enum):
+ CRITICAL = "Critical"
+ MAJOR = "Major"
+ MINOR = "Minor"
+
+
+class CAPASource(Enum):
+ COMPLAINT = "Customer Complaint"
+ AUDIT = "Internal Audit"
+ EXTERNAL_AUDIT = "External Audit"
+ NONCONFORMANCE = "Nonconformance"
+ MANAGEMENT_REVIEW = "Management Review"
+ TREND_ANALYSIS = "Trend Analysis"
+ REGULATORY = "Regulatory Feedback"
+ OTHER = "Other"
+
+
+@dataclass
+class CAPA:
+ capa_number: str
+ title: str
+ description: str
+ source: CAPASource
+ severity: CAPASeverity
+ status: CAPAStatus
+ open_date: str
+ target_date: str
+ owner: str
+ root_cause: str = ""
+ corrective_action: str = ""
+ verification_date: Optional[str] = None
+ close_date: Optional[str] = None
+ days_open: int = 0
+ is_overdue: bool = False
+
+
+@dataclass
+class CAPAMetrics:
+ total_capas: int
+ open_capas: int
+ closed_capas: int
+ overdue_capas: int
+ avg_cycle_time: float
+ effectiveness_rate: float
+ by_status: Dict[str, int]
+ by_severity: Dict[str, int]
+ by_source: Dict[str, int]
+ overdue_list: List[Dict]
+ recommendations: List[str]
+
+
+class CAPATracker:
+ """CAPA tracking and metrics calculator."""
+
+ # Target cycle times by severity (days)
+ TARGET_CYCLE_TIMES = {
+ CAPASeverity.CRITICAL: 30,
+ CAPASeverity.MAJOR: 60,
+ CAPASeverity.MINOR: 90,
+ }
+
+ def __init__(self, capas: List[CAPA]):
+ self.capas = capas
+ self.today = datetime.now()
+ self._calculate_derived_fields()
+
+ def _calculate_derived_fields(self):
+ """Calculate days open and overdue status."""
+ for capa in self.capas:
+ open_date = datetime.strptime(capa.open_date, "%Y-%m-%d")
+
+ if capa.close_date:
+ close_date = datetime.strptime(capa.close_date, "%Y-%m-%d")
+ capa.days_open = (close_date - open_date).days
+ else:
+ capa.days_open = (self.today - open_date).days
+
+ target_date = datetime.strptime(capa.target_date, "%Y-%m-%d")
+ if not capa.close_date and self.today > target_date:
+ capa.is_overdue = True
+
+ def calculate_metrics(self) -> CAPAMetrics:
+ """Calculate comprehensive CAPA metrics."""
+ total = len(self.capas)
+
+ # Status counts
+ closed_statuses = [CAPAStatus.CLOSED_EFFECTIVE, CAPAStatus.CLOSED_INEFFECTIVE]
+ open_capas = [c for c in self.capas if c.status not in closed_statuses]
+ closed_capas = [c for c in self.capas if c.status in closed_statuses]
+ overdue_capas = [c for c in self.capas if c.is_overdue]
+
+ # Average cycle time (closed CAPAs only)
+ if closed_capas:
+ avg_cycle = sum(c.days_open for c in closed_capas) / len(closed_capas)
+ else:
+ avg_cycle = 0.0
+
+ # Effectiveness rate
+ effective = [c for c in self.capas if c.status == CAPAStatus.CLOSED_EFFECTIVE]
+ ineffective = [c for c in self.capas if c.status == CAPAStatus.CLOSED_INEFFECTIVE]
+ if effective or ineffective:
+ effectiveness = len(effective) / (len(effective) + len(ineffective)) * 100
+ else:
+ effectiveness = 0.0
+
+ # Counts by category
+ by_status = {}
+ for status in CAPAStatus:
+ count = len([c for c in self.capas if c.status == status])
+ if count > 0:
+ by_status[status.value] = count
+
+ by_severity = {}
+ for severity in CAPASeverity:
+ count = len([c for c in self.capas if c.severity == severity])
+ if count > 0:
+ by_severity[severity.value] = count
+
+ by_source = {}
+ for source in CAPASource:
+ count = len([c for c in self.capas if c.source == source])
+ if count > 0:
+ by_source[source.value] = count
+
+ # Overdue list
+ overdue_list = []
+ for capa in sorted(overdue_capas, key=lambda c: c.days_open, reverse=True):
+ target = datetime.strptime(capa.target_date, "%Y-%m-%d")
+ days_overdue = (self.today - target).days
+ overdue_list.append({
+ "capa_number": capa.capa_number,
+ "title": capa.title,
+ "severity": capa.severity.value,
+ "status": capa.status.value,
+ "days_overdue": days_overdue,
+ "owner": capa.owner
+ })
+
+ # Generate recommendations
+ recommendations = self._generate_recommendations(
+ open_capas, overdue_capas, effectiveness, avg_cycle
+ )
+
+ return CAPAMetrics(
+ total_capas=total,
+ open_capas=len(open_capas),
+ closed_capas=len(closed_capas),
+ overdue_capas=len(overdue_capas),
+ avg_cycle_time=round(avg_cycle, 1),
+ effectiveness_rate=round(effectiveness, 1),
+ by_status=by_status,
+ by_severity=by_severity,
+ by_source=by_source,
+ overdue_list=overdue_list,
+ recommendations=recommendations
+ )
+
+ def _generate_recommendations(
+ self,
+ open_capas: List[CAPA],
+ overdue_capas: List[CAPA],
+ effectiveness: float,
+ avg_cycle: float
+ ) -> List[str]:
+ """Generate actionable recommendations."""
+ recommendations = []
+
+ # Overdue CAPAs
+ if overdue_capas:
+ critical_overdue = [c for c in overdue_capas if c.severity == CAPASeverity.CRITICAL]
+ if critical_overdue:
+ recommendations.append(
+ f"URGENT: {len(critical_overdue)} critical CAPA(s) overdue. "
+ "Escalate to management immediately."
+ )
+ else:
+ recommendations.append(
+ f"ACTION: {len(overdue_capas)} CAPA(s) overdue. "
+ "Review and update target dates or expedite closure."
+ )
+
+ # Effectiveness rate
+ if effectiveness < 80 and effectiveness > 0:
+ recommendations.append(
+ f"CONCERN: Effectiveness rate at {effectiveness:.0f}%. "
+ "Review root cause analysis quality and corrective action adequacy."
+ )
+
+ # Cycle time
+ if avg_cycle > 60:
+ recommendations.append(
+ f"IMPROVEMENT: Average cycle time is {avg_cycle:.0f} days. "
+ "Target is 60 days. Review investigation and approval bottlenecks."
+ )
+
+ # Investigation backlog
+ in_investigation = [c for c in open_capas if c.status == CAPAStatus.INVESTIGATION]
+ if len(in_investigation) > 5:
+ recommendations.append(
+ f"WORKLOAD: {len(in_investigation)} CAPAs in investigation phase. "
+ "Consider additional resources or prioritization."
+ )
+
+ # Stuck in verification
+ in_verification = [c for c in open_capas if c.status == CAPAStatus.VERIFICATION]
+ old_verification = [c for c in in_verification if c.days_open > 120]
+ if old_verification:
+ recommendations.append(
+ f"STALLED: {len(old_verification)} CAPA(s) in verification >120 days. "
+ "Complete effectiveness checks or extend with justification."
+ )
+
+ # Source patterns
+ complaint_capas = [c for c in self.capas if c.source == CAPASource.COMPLAINT]
+ if len(complaint_capas) > len(self.capas) * 0.4:
+ recommendations.append(
+ "TREND: >40% of CAPAs from customer complaints. "
+ "Review preventive action effectiveness and quality controls."
+ )
+
+ if not recommendations:
+ recommendations.append(
+ "CAPA program operating within targets. "
+ "Continue monitoring key metrics."
+ )
+
+ return recommendations
+
+ def get_aging_report(self) -> Dict:
+ """Generate aging analysis of open CAPAs."""
+ open_statuses = [
+ CAPAStatus.OPEN, CAPAStatus.INVESTIGATION,
+ CAPAStatus.ACTION_PLANNING, CAPAStatus.IMPLEMENTATION,
+ CAPAStatus.VERIFICATION
+ ]
+ open_capas = [c for c in self.capas if c.status in open_statuses]
+
+ aging_buckets = {
+ "0-30 days": [],
+ "31-60 days": [],
+ "61-90 days": [],
+ "91-120 days": [],
+ ">120 days": []
+ }
+
+ for capa in open_capas:
+ days = capa.days_open
+ if days <= 30:
+ bucket = "0-30 days"
+ elif days <= 60:
+ bucket = "31-60 days"
+ elif days <= 90:
+ bucket = "61-90 days"
+ elif days <= 120:
+ bucket = "91-120 days"
+ else:
+ bucket = ">120 days"
+
+ aging_buckets[bucket].append({
+ "capa_number": capa.capa_number,
+ "title": capa.title,
+ "days_open": days,
+ "status": capa.status.value,
+ "severity": capa.severity.value
+ })
+
+ return aging_buckets
+
+
+def format_text_output(metrics: CAPAMetrics, aging: Dict) -> str:
+ """Format metrics as text report."""
+ lines = [
+ "=" * 70,
+ "CAPA STATUS REPORT",
+ "=" * 70,
+ f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+ "",
+ "SUMMARY METRICS",
+ "-" * 40,
+ f"Total CAPAs: {metrics.total_capas}",
+ f"Open CAPAs: {metrics.open_capas}",
+ f"Closed CAPAs: {metrics.closed_capas}",
+ f"Overdue CAPAs: {metrics.overdue_capas}",
+ f"Avg Cycle Time: {metrics.avg_cycle_time} days",
+ f"Effectiveness Rate: {metrics.effectiveness_rate}%",
+ "",
+ "STATUS DISTRIBUTION",
+ "-" * 40,
+ ]
+
+ for status, count in metrics.by_status.items():
+ bar = "█" * min(count, 20)
+ lines.append(f" {status:<25} {bar} {count}")
+
+ lines.extend([
+ "",
+ "SEVERITY DISTRIBUTION",
+ "-" * 40,
+ ])
+
+ for severity, count in metrics.by_severity.items():
+ bar = "█" * min(count, 20)
+ lines.append(f" {severity:<25} {bar} {count}")
+
+ lines.extend([
+ "",
+ "SOURCE DISTRIBUTION",
+ "-" * 40,
+ ])
+
+ for source, count in metrics.by_source.items():
+ bar = "█" * min(count, 20)
+ lines.append(f" {source:<25} {bar} {count}")
+
+ lines.extend([
+ "",
+ "AGING ANALYSIS",
+ "-" * 40,
+ ])
+
+ for bucket, capas in aging.items():
+ lines.append(f" {bucket}: {len(capas)} CAPA(s)")
+
+ if metrics.overdue_list:
+ lines.extend([
+ "",
+ "OVERDUE CAPAs",
+ "-" * 40,
+ f"{'CAPA #':<12} {'Title':<25} {'Days':<6} {'Owner':<15}",
+ "-" * 60,
+ ])
+
+ for item in metrics.overdue_list[:10]:
+ title = item["title"][:24] if len(item["title"]) > 24 else item["title"]
+ lines.append(
+ f"{item['capa_number']:<12} {title:<25} "
+ f"{item['days_overdue']:<6} {item['owner']:<15}"
+ )
+
+ if len(metrics.overdue_list) > 10:
+ lines.append(f"... and {len(metrics.overdue_list) - 10} more")
+
+ lines.extend([
+ "",
+ "RECOMMENDATIONS",
+ "-" * 40,
+ ])
+
+ for i, rec in enumerate(metrics.recommendations, 1):
+ lines.append(f"{i}. {rec}")
+
+ lines.append("=" * 70)
+ return "\n".join(lines)
+
+
+def interactive_mode():
+ """Run interactive CAPA entry mode."""
+ print("=" * 60)
+ print("CAPA Tracker - Interactive Mode")
+ print("=" * 60)
+
+ capas = []
+ print("\nEnter CAPAs (blank CAPA number to finish):\n")
+
+ while True:
+ capa_num = input("CAPA Number (e.g., CAPA-2024-001): ").strip()
+ if not capa_num:
+ break
+
+ title = input("Title: ").strip()
+ description = input("Description: ").strip()
+
+ print("Source options: C=Complaint, A=Audit, N=Nonconformance, M=Management Review, T=Trend, O=Other")
+ source_input = input("Source [C/A/N/M/T/O]: ").strip().upper()
+ source_map = {
+ "C": CAPASource.COMPLAINT,
+ "A": CAPASource.AUDIT,
+ "N": CAPASource.NONCONFORMANCE,
+ "M": CAPASource.MANAGEMENT_REVIEW,
+ "T": CAPASource.TREND_ANALYSIS,
+ "O": CAPASource.OTHER
+ }
+ source = source_map.get(source_input, CAPASource.OTHER)
+
+ print("Severity: C=Critical, M=Major, I=Minor")
+ severity_input = input("Severity [C/M/I]: ").strip().upper()
+ severity_map = {
+ "C": CAPASeverity.CRITICAL,
+ "M": CAPASeverity.MAJOR,
+ "I": CAPASeverity.MINOR
+ }
+ severity = severity_map.get(severity_input, CAPASeverity.MINOR)
+
+ print("Status: O=Open, I=Investigation, P=Action Planning, M=Implementation, V=Verification, E=Closed Effective, N=Closed Ineffective")
+ status_input = input("Status [O/I/P/M/V/E/N]: ").strip().upper()
+ status_map = {
+ "O": CAPAStatus.OPEN,
+ "I": CAPAStatus.INVESTIGATION,
+ "P": CAPAStatus.ACTION_PLANNING,
+ "M": CAPAStatus.IMPLEMENTATION,
+ "V": CAPAStatus.VERIFICATION,
+ "E": CAPAStatus.CLOSED_EFFECTIVE,
+ "N": CAPAStatus.CLOSED_INEFFECTIVE
+ }
+ status = status_map.get(status_input, CAPAStatus.OPEN)
+
+ open_date = input("Open Date (YYYY-MM-DD): ").strip()
+ target_date = input("Target Date (YYYY-MM-DD): ").strip()
+ owner = input("Owner: ").strip()
+
+ close_date = None
+ if status in [CAPAStatus.CLOSED_EFFECTIVE, CAPAStatus.CLOSED_INEFFECTIVE]:
+ close_date = input("Close Date (YYYY-MM-DD): ").strip()
+
+ capas.append(CAPA(
+ capa_number=capa_num,
+ title=title,
+ description=description,
+ source=source,
+ severity=severity,
+ status=status,
+ open_date=open_date,
+ target_date=target_date,
+ owner=owner,
+ close_date=close_date if close_date else None
+ ))
+
+ print(f"\nAdded: {capa_num}\n")
+
+ if not capas:
+ print("No CAPAs entered. Exiting.")
+ return
+
+ tracker = CAPATracker(capas)
+ metrics = tracker.calculate_metrics()
+ aging = tracker.get_aging_report()
+ print("\n" + format_text_output(metrics, aging))
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="CAPA Tracking and Metrics Tool"
+ )
+ parser.add_argument(
+ "--capas",
+ type=str,
+ help="JSON file with CAPA data"
+ )
+ parser.add_argument(
+ "--output",
+ choices=["text", "json"],
+ default="text",
+ help="Output format"
+ )
+ parser.add_argument(
+ "--interactive",
+ action="store_true",
+ help="Run in interactive mode"
+ )
+ parser.add_argument(
+ "--sample",
+ action="store_true",
+ help="Generate sample CAPA data file"
+ )
+
+ args = parser.parse_args()
+
+ if args.interactive:
+ interactive_mode()
+ return
+
+ if args.sample:
+ sample_data = {
+ "capas": [
+ {
+ "capa_number": "CAPA-2024-001",
+ "title": "Calibration overdue for pH meter",
+ "description": "pH meter EQ-042 found 2 months overdue",
+ "source": "AUDIT",
+ "severity": "MAJOR",
+ "status": "VERIFICATION",
+ "open_date": "2024-06-15",
+ "target_date": "2024-08-15",
+ "owner": "J. Smith",
+ "root_cause": "No trigger for schedule update at equipment purchase",
+ "corrective_action": "Updated SOP-EQ-001 to require schedule update"
+ },
+ {
+ "capa_number": "CAPA-2024-002",
+ "title": "Customer complaint - labeling error",
+ "description": "Wrong lot number on product label",
+ "source": "COMPLAINT",
+ "severity": "CRITICAL",
+ "status": "INVESTIGATION",
+ "open_date": "2024-09-01",
+ "target_date": "2024-10-01",
+ "owner": "M. Jones"
+ },
+ {
+ "capa_number": "CAPA-2024-003",
+ "title": "Training records incomplete",
+ "description": "Missing effectiveness verification for 3 operators",
+ "source": "AUDIT",
+ "severity": "MINOR",
+ "status": "CLOSED_EFFECTIVE",
+ "open_date": "2024-03-10",
+ "target_date": "2024-06-10",
+ "owner": "A. Brown",
+ "close_date": "2024-05-20"
+ }
+ ]
+ }
+ print(json.dumps(sample_data, indent=2))
+ return
+
+ if args.capas:
+ with open(args.capas, "r") as f:
+ data = json.load(f)
+
+ capas = []
+ for c in data.get("capas", []):
+ try:
+ source = CAPASource[c.get("source", "OTHER").upper()]
+ except KeyError:
+ source = CAPASource.OTHER
+
+ try:
+ severity = CAPASeverity[c.get("severity", "MINOR").upper()]
+ except KeyError:
+ severity = CAPASeverity.MINOR
+
+ try:
+ status = CAPAStatus[c.get("status", "OPEN").upper()]
+ except KeyError:
+ status = CAPAStatus.OPEN
+
+ capas.append(CAPA(
+ capa_number=c["capa_number"],
+ title=c.get("title", ""),
+ description=c.get("description", ""),
+ source=source,
+ severity=severity,
+ status=status,
+ open_date=c["open_date"],
+ target_date=c["target_date"],
+ owner=c.get("owner", ""),
+ root_cause=c.get("root_cause", ""),
+ corrective_action=c.get("corrective_action", ""),
+ verification_date=c.get("verification_date"),
+ close_date=c.get("close_date")
+ ))
+ else:
+ # Demo data if no file provided
+ capas = [
+ CAPA(
+ capa_number="CAPA-2024-001",
+ title="Calibration overdue",
+ description="pH meter overdue",
+ source=CAPASource.AUDIT,
+ severity=CAPASeverity.MAJOR,
+ status=CAPAStatus.VERIFICATION,
+ open_date="2024-06-15",
+ target_date="2024-08-15",
+ owner="J. Smith"
+ ),
+ CAPA(
+ capa_number="CAPA-2024-002",
+ title="Labeling error complaint",
+ description="Wrong lot number",
+ source=CAPASource.COMPLAINT,
+ severity=CAPASeverity.CRITICAL,
+ status=CAPAStatus.INVESTIGATION,
+ open_date="2024-09-01",
+ target_date="2024-10-01",
+ owner="M. Jones"
+ ),
+ CAPA(
+ capa_number="CAPA-2024-003",
+ title="Training records incomplete",
+ description="Missing effectiveness verification",
+ source=CAPASource.AUDIT,
+ severity=CAPASeverity.MINOR,
+ status=CAPAStatus.CLOSED_EFFECTIVE,
+ open_date="2024-03-10",
+ target_date="2024-06-10",
+ owner="A. Brown",
+ close_date="2024-05-20"
+ )
+ ]
+
+ tracker = CAPATracker(capas)
+ metrics = tracker.calculate_metrics()
+ aging = tracker.get_aging_report()
+
+ if args.output == "json":
+ output = {
+ "metrics": asdict(metrics),
+ "aging": aging
+ }
+ print(json.dumps(output, indent=2))
+ else:
+ print(format_text_output(metrics, aging))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/ceo-advisor/SKILL.md b/skills/ceo-advisor/SKILL.md
new file mode 100644
index 00000000..6396c197
--- /dev/null
+++ b/skills/ceo-advisor/SKILL.md
@@ -0,0 +1,169 @@
+---
+name: "ceo-advisor"
+description: "Executive leadership guidance for strategic decision-making, organizational development, and stakeholder management. Use when planning strategy, preparing board presentations, managing investors, developing organizational culture, making executive decisions, fundraising, or when user mentions CEO, strategic planning, board meetings, investor updates, organizational leadership, or executive strategy."
+license: MIT
+metadata:
+ version: 2.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: ceo-leadership
+ updated: 2026-03-05
+ python-tools: strategy_analyzer.py, financial_scenario_analyzer.py
+ frameworks: executive-decisions, board-governance, leadership-culture
+---
+
+# CEO Advisor
+
+Strategic leadership frameworks for vision, fundraising, board management, culture, and stakeholder alignment.
+
+## Keywords
+CEO, chief executive officer, strategy, strategic planning, fundraising, board management, investor relations, culture, organizational leadership, vision, mission, stakeholder management, capital allocation, crisis management, succession planning
+
+## Quick Start
+
+```bash
+python scripts/strategy_analyzer.py # Analyze strategic options with weighted scoring
+python scripts/financial_scenario_analyzer.py # Model financial scenarios (base/bull/bear)
+```
+
+## Core Responsibilities
+
+### 1. Vision & Strategy
+Set the direction. Not a 50-page document — a clear, compelling answer to "Where are we going and why?"
+
+**Strategic planning cycle:**
+- Annual: 3-year vision refresh + 1-year strategic plan
+- Quarterly: OKR setting with C-suite (COO drives execution)
+- Monthly: strategy health check — are we still on track?
+
+**Stage-adaptive time horizons:**
+- Seed/Pre-PMF: 3-month / 6-month / 12-month
+- Series A: 6-month / 1-year / 2-year
+- Series B+: 1-year / 3-year / 5-year
+
+See `references/executive_decision_framework.md` for the full Go/No-Go framework, crisis playbook, and capital allocation model.
+
+### 2. Capital & Resource Management
+You're the chief allocator. Every dollar, every person, every hour of engineering time is a bet.
+
+**Capital allocation priorities:**
+1. Keep the lights on (operations, must-haves)
+2. Protect the core (retention, quality, security)
+3. Grow the core (expansion of what works)
+4. Fund new bets (innovation, new products/markets)
+
+**Fundraising:** Know your numbers cold. Timing matters more than valuation. See `references/board_governance_investor_relations.md`.
+
+### 3. Stakeholder Leadership
+You serve multiple masters. Priority order:
+1. Customers (they pay the bills)
+2. Team (they build the product)
+3. Board/Investors (they fund the mission)
+4. Partners (they extend your reach)
+
+### 4. Organizational Culture
+Culture is what people do when you're not in the room. It's your job to define it, model it, and enforce it.
+
+See `references/leadership_organizational_culture.md` for culture development frameworks and the CEO learning agenda. Also see `culture-architect/` for the operational culture toolkit.
+
+### 5. Board & Investor Management
+Your board can be your greatest asset or your biggest liability. The difference is how you manage them.
+
+See `references/board_governance_investor_relations.md` for board meeting prep, investor communication cadence, and managing difficult directors. Also see `board-deck-builder/` for assembling the actual board deck.
+
+## Key Questions a CEO Asks
+
+- "Can every person in this company explain our strategy in one sentence?"
+- "What's the one thing that, if it goes wrong, kills us?"
+- "Am I spending my time on the highest-leverage activity right now?"
+- "What decision am I avoiding? Why?"
+- "If we could only do one thing this quarter, what would it be?"
+- "Do our investors and our team hear the same story from me?"
+- "Who would replace me if I got hit by a bus tomorrow?"
+
+## CEO Metrics Dashboard
+
+| Category | Metric | Target | Frequency |
+|----------|--------|--------|-----------|
+| **Strategy** | Annual goals hit rate | > 70% | Quarterly |
+| **Revenue** | ARR growth rate | Stage-dependent | Monthly |
+| **Capital** | Months of runway | > 12 months | Monthly |
+| **Capital** | Burn multiple | < 2x | Monthly |
+| **Product** | NPS / PMF score | > 40 NPS | Quarterly |
+| **People** | Regrettable attrition | < 10% | Monthly |
+| **People** | Employee engagement | > 7/10 | Quarterly |
+| **Board** | Board NPS (your relationship) | Positive trend | Quarterly |
+| **Personal** | % time on strategic work | > 40% | Weekly |
+
+## Red Flags
+
+- You're the bottleneck for more than 3 decisions per week
+- The board surprises you with questions you can't answer
+- Your calendar is 80%+ meetings with no strategic blocks
+- Key people are leaving and you didn't see it coming
+- You're fundraising reactively (runway < 6 months, no plan)
+- Your team can't articulate the strategy without you in the room
+- You're avoiding a hard conversation (co-founder, investor, underperformer)
+
+## Integration with C-Suite Roles
+
+| When... | CEO works with... | To... |
+|---------|-------------------|-------|
+| Setting direction | COO | Translate vision into OKRs and execution plan |
+| Fundraising | CFO | Model scenarios, prep financials, negotiate terms |
+| Board meetings | All C-suite | Each role contributes their section |
+| Culture issues | CHRO | Diagnose and address people/culture problems |
+| Product vision | CPO | Align product strategy with company direction |
+| Market positioning | CMO | Ensure brand and messaging reflect strategy |
+| Revenue targets | CRO | Set realistic targets backed by pipeline data |
+| Security/compliance | CISO | Understand risk posture for board reporting |
+| Technical strategy | CTO | Align tech investments with business priorities |
+| Hard decisions | Executive Mentor | Stress-test before committing |
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Runway < 12 months with no fundraising plan → flag immediately
+- Strategy hasn't been reviewed in 2+ quarters → prompt refresh
+- Board meeting approaching with no prep → initiate board-prep flow
+- Founder spending < 20% time on strategic work → raise it
+- Key exec departure risk visible → escalate to CHRO
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Help me think about strategy" | Strategic options matrix with risk-adjusted scoring |
+| "Prep me for the board" | Board narrative + anticipated questions + data gaps |
+| "Should we raise?" | Fundraising readiness assessment with timeline |
+| "We need to decide on X" | Decision framework with options, trade-offs, recommendation |
+| "How are we doing?" | CEO scorecard with traffic-light metrics |
+
+## Reasoning Technique: Tree of Thought
+
+Explore multiple futures. For every strategic decision, generate at least 3 paths. Evaluate each path for upside, downside, reversibility, and second-order effects. Pick the path with the best risk-adjusted outcome.
+
+**Stage-adaptive horizons:**
+- Seed: project 3m/6m/12m
+- Series A: project 6m/1y/2y
+- Series B+: project 1y/3y/5y
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
+
+## Resources
+- `references/executive_decision_framework.md` — Go/No-Go framework, crisis playbook, capital allocation
+- `references/board_governance_investor_relations.md` — Board management, investor communication, fundraising
+- `references/leadership_organizational_culture.md` — Culture development, CEO routines, succession planning
diff --git a/skills/ceo-advisor/_meta.json b/skills/ceo-advisor/_meta.json
new file mode 100644
index 00000000..19dc44b0
--- /dev/null
+++ b/skills/ceo-advisor/_meta.json
@@ -0,0 +1,22 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "ceo-advisor",
+ "displayName": "Ceo Advisor",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773070370514,
+ "commit": "https://github.com/openclaw/skills/commit/98b7410326a9e1c8f1a6c097c4847a319b8ac008"
+ },
+ "history": [
+ {
+ "version": "2.0.0",
+ "publishedAt": 1772746513044,
+ "commit": "https://github.com/openclaw/skills/commit/9a33abba4c7b97d5364a5d945b8ee408745dedd4"
+ },
+ {
+ "version": "1.0.0",
+ "publishedAt": 1770402384380,
+ "commit": "https://github.com/openclaw/skills/commit/748dd574171c7c8637a17b37e8189bdecbb039d3"
+ }
+ ]
+}
diff --git a/skills/ceo-advisor/references/board_governance_investor_relations.md b/skills/ceo-advisor/references/board_governance_investor_relations.md
new file mode 100644
index 00000000..6da2c369
--- /dev/null
+++ b/skills/ceo-advisor/references/board_governance_investor_relations.md
@@ -0,0 +1,599 @@
+# Board Governance & Investor Relations Guide
+
+## Board of Directors Management
+
+### Board Composition
+
+#### Ideal Board Structure
+- **Size**: 7-9 members (odd number for voting)
+- **Independence**: Majority independent directors
+- **Diversity**: Gender, ethnicity, expertise, experience
+- **Term**: 3-year terms, staggered renewal
+
+#### Board Roles
+
+| Role | Responsibilities | Typical Background |
+|------|-----------------|-------------------|
+| Chairman | Board leadership, CEO liaison | Former CEO, Industry veteran |
+| Lead Independent Director | Independent voice, executive sessions | Senior executive experience |
+| Audit Committee Chair | Financial oversight, auditor relationship | CFO/CPA background |
+| Compensation Committee Chair | Executive compensation, succession | HR/Executive experience |
+| Nominating Committee Chair | Board composition, governance | Governance expertise |
+
+### Board Meeting Management
+
+#### Annual Board Calendar
+
+**Q1 Meeting**
+- Annual strategy review
+- Previous year performance
+- Current year priorities
+- Risk assessment update
+
+**Q2 Meeting**
+- Q1 results review
+- Strategic initiative progress
+- Competitive landscape
+- Talent review
+
+**Q3 Meeting**
+- Mid-year performance
+- Budget preview
+- Strategic planning session
+- Succession planning
+
+**Q4 Meeting**
+- Annual budget approval
+- Executive compensation
+- Board evaluation
+- Upcoming year calendar
+
+#### Meeting Preparation Timeline
+
+**T-4 Weeks**
+- Agenda draft to Chairman
+- Pre-read preparation begins
+- Committee meetings scheduled
+
+**T-2 Weeks**
+- Materials to review committee
+- Final agenda confirmation
+- Logistics coordination
+
+**T-1 Week**
+- Board package distribution
+- Pre-meeting calls as needed
+- Final preparations
+
+**T-0 Meeting Day**
+- Executive session (start)
+- Board meeting
+- Executive session (end)
+- Follow-up actions defined
+
+### Board Package Template
+
+#### Standard Package Contents
+
+1. **Cover Memo** (1 page)
+ - Meeting agenda
+ - Key decisions required
+ - Time allocations
+
+2. **CEO Report** (3-5 pages)
+ - Executive summary
+ - Performance highlights
+ - Strategic progress
+ - Key challenges
+ - Asks of the board
+
+3. **Financial Report** (5-10 pages)
+ - Financial statements
+ - KPI dashboard
+ - Variance analysis
+ - Cash position
+ - Forecast update
+
+4. **Strategic Updates** (10-15 pages)
+ - Initiative status
+ - Market analysis
+ - Competitive intelligence
+ - Product roadmap
+
+5. **Committee Reports** (2-3 pages each)
+ - Audit Committee
+ - Compensation Committee
+ - Other committees
+
+6. **Appendices**
+ - Detailed financials
+ - Supporting analysis
+ - Previous minutes
+
+### Board Communication Best Practices
+
+#### Between Meetings
+
+**Monthly Update Email**
+```
+Subject: [Company] CEO Update - [Month Year]
+
+Board Members,
+
+Quick update on [Month] performance:
+
+Headlines:
+• [Key achievement]
+• [Important metric]
+• [Strategic progress]
+
+Challenges:
+• [Issue and mitigation]
+
+Looking Ahead:
+• [Upcoming milestone]
+
+Detailed dashboard attached.
+
+Best,
+[CEO Name]
+```
+
+**Flash Reports** (When needed)
+- Material events
+- Major wins/losses
+- Press coverage
+- Regulatory matters
+
+#### Managing Difficult Conversations
+
+**Delivering Bad News**
+1. Don't delay - inform promptly
+2. Lead with facts
+3. Own the responsibility
+4. Present action plan
+5. Set realistic timeline
+
+**Handling Dissent**
+1. Listen fully
+2. Acknowledge concerns
+3. Provide data/rationale
+4. Seek common ground
+5. Document decisions
+
+## Investor Relations
+
+### Investor Segmentation
+
+#### Institutional Investors
+
+**Types**:
+- Mutual funds
+- Pension funds
+- Hedge funds
+- Private equity
+- Sovereign wealth funds
+
+**Engagement Strategy**:
+- Quarterly earnings calls
+- Annual investor day
+- Conference participation
+- One-on-one meetings
+- Site visits
+
+#### Retail Investors
+
+**Channels**:
+- Website IR section
+- Annual reports
+- Proxy statements
+- Social media
+- Shareholder meetings
+
+### Earnings Communications
+
+#### Earnings Release Template
+
+```
+[COMPANY] REPORTS [QUARTER] [YEAR] RESULTS
+
+[City, Date] - [Company] (TICKER) today reported results for [quarter]:
+
+Financial Highlights:
+• Revenue: $X (±Y% YoY)
+• Net Income: $X (±Y% YoY)
+• EPS: $X (±Y% YoY)
+• [Other key metric]
+
+CEO Commentary:
+"[Quote about performance and outlook]"
+
+CFO Commentary:
+"[Quote about financial details]"
+
+Guidance:
+[Forward-looking statements]
+
+Conference Call:
+Date/Time: [Details]
+Webcast: [Link]
+
+About [Company]:
+[Boilerplate]
+
+Contact:
+[IR contact information]
+```
+
+#### Earnings Call Script Structure
+
+**CEO Opening (5 minutes)**
+```
+Good [morning/afternoon], and welcome to [Company's]
+[Quarter] earnings call.
+
+Today I'll cover:
+1. Quarter highlights
+2. Strategic progress
+3. Market dynamics
+4. Outlook
+
+[Key points with supporting data]
+
+I'll now turn it over to our CFO...
+```
+
+**CFO Section (10 minutes)**
+```
+Thank you [CEO name].
+
+Financial Performance:
+- Revenue details by segment
+- Margin analysis
+- Cash flow review
+- Balance sheet highlights
+
+Guidance:
+- Next quarter expectations
+- Full year outlook
+- Key assumptions
+
+Now back to [CEO] for closing remarks...
+```
+
+**Q&A Management**
+- Anticipate top 10 questions
+- Prepare fact sheets
+- Designate responders
+- Bridge to key messages
+- Time management
+
+### Investor Messaging Framework
+
+#### Value Proposition
+
+**Investment Thesis Elements**:
+1. Market opportunity size
+2. Competitive advantages
+3. Growth strategy
+4. Financial model
+5. Management team
+6. Risk factors
+
+#### Key Messages Architecture
+
+**Primary Messages** (Memorize)
+1. [Core value proposition]
+2. [Differentiation]
+3. [Growth trajectory]
+
+**Supporting Points** (Have ready)
+- Market data
+- Customer proof points
+- Financial metrics
+- Strategic initiatives
+
+**Proof Points** (Document)
+- Case studies
+- Metrics
+- Third-party validation
+- Awards/recognition
+
+### Investor Day Planning
+
+#### 6-Month Planning Timeline
+
+**T-6 Months**
+- Set date and venue
+- Define objectives
+- Identify speakers
+- Begin content development
+
+**T-4 Months**
+- Develop presentations
+- Coordinate logistics
+- Begin rehearsals
+- Create save-the-date
+
+**T-2 Months**
+- Finalize content
+- Complete rehearsals
+- Send invitations
+- Prepare materials
+
+**T-1 Month**
+- Final preparations
+- Media training
+- Q&A preparation
+- Technology testing
+
+**T-0 Event Day**
+- Execute program
+- Manage Q&A
+- Network sessions
+- Follow-up plan
+
+#### Agenda Template
+
+```
+8:00 AM - Registration & Breakfast
+8:30 AM - CEO Welcome & Vision
+9:00 AM - Market Opportunity
+9:30 AM - Product Strategy & Demo
+10:00 AM - Break
+10:15 AM - Go-to-Market Strategy
+10:45 AM - Financial Overview
+11:15 AM - Q&A Panel
+12:00 PM - Networking Lunch
+1:00 PM - Facility Tour (Optional)
+```
+
+### Shareholder Activism Defense
+
+#### Early Warning Signs
+- Stake building (13D/13G filings)
+- Public criticism
+- Media campaigns
+- Proxy solicitation
+- Shareholder proposals
+
+#### Response Playbook
+
+**1. Preparation Phase**
+- Vulnerability assessment
+- Response team formation
+- Advisor engagement
+- Board alignment
+
+**2. Engagement Phase**
+- Direct dialogue
+- Understanding demands
+- Finding common ground
+- Negotiation strategy
+
+**3. Defense Phase** (if needed)
+- Public response
+- Proxy fight preparation
+- Shareholder outreach
+- Media strategy
+
+**4. Resolution Phase**
+- Settlement negotiations
+- Implementation planning
+- Communication strategy
+- Monitoring plan
+
+### Regulatory Compliance
+
+#### Key Filings
+
+| Form | Purpose | Timing |
+|------|---------|--------|
+| 10-K | Annual report | 60-90 days after FY end |
+| 10-Q | Quarterly report | 40-45 days after Q end |
+| 8-K | Material events | 4 business days |
+| DEF 14A | Proxy statement | Before annual meeting |
+| S-1/S-3 | Securities registration | As needed |
+
+#### Disclosure Requirements
+
+**Material Information**:
+- Financial results
+- Major transactions
+- Leadership changes
+- Strategic shifts
+- Legal proceedings
+- Risk changes
+
+**Regulation FD Compliance**:
+- No selective disclosure
+- Simultaneous public release
+- Documented procedures
+- Training program
+
+### Crisis Communication
+
+#### IR Crisis Response
+
+**Hour 1: Assessment**
+- Gather facts
+- Assess materiality
+- Consult legal
+- Prepare holding statement
+
+**Hours 2-4: Response**
+- Draft 8-K if required
+- Prepare FAQ
+- Update website
+- Notify exchanges
+
+**Hours 4-8: Communication**
+- Issue press release
+- Update analysts
+- Employee communication
+- Monitor reactions
+
+**Day 2+: Follow-up**
+- Investor calls
+- Media interviews
+- Ongoing updates
+- Impact assessment
+
+### Performance Metrics
+
+#### IR Effectiveness KPIs
+
+**Quantitative Metrics**:
+- Share price performance vs peers
+- Trading volume/liquidity
+- Analyst coverage
+- Institutional ownership %
+- Valuation multiples vs peers
+
+**Qualitative Metrics**:
+- Analyst sentiment
+- Media coverage tone
+- Investor feedback
+- Award recognition
+- Perception studies
+
+#### Shareholder Analysis
+
+**Ownership Tracking**:
+- Top 20 shareholders
+- Ownership changes
+- Peer ownership overlap
+- Geographic distribution
+- Investment style mix
+
+**Engagement Metrics**:
+- Meeting count
+- Conference participation
+- Earnings call attendance
+- Website analytics
+- Email engagement
+
+## Governance Best Practices
+
+### Board Effectiveness
+
+#### Annual Board Evaluation
+
+**Process**:
+1. Anonymous surveys
+2. Individual interviews
+3. Peer feedback
+4. Results compilation
+5. Action planning
+6. Progress monitoring
+
+**Evaluation Areas**:
+- Board composition
+- Meeting effectiveness
+- Information quality
+- Strategic oversight
+- Risk management
+- CEO relationship
+- Committee performance
+
+### Executive Session Management
+
+**Frequency**: Every board meeting
+**Duration**: 30-60 minutes
+**Participants**: Independent directors only
+
+**Typical Topics**:
+- CEO performance
+- Succession planning
+- Board dynamics
+- Sensitive matters
+- Executive compensation
+
+### D&O Insurance & Indemnification
+
+**Coverage Levels**:
+- Primary: $10-25M
+- Excess: $25-100M+
+- Side A: Individual protection
+- Side B: Company reimbursement
+- Side C: Securities claims
+
+**Best Practices**:
+- Annual review
+- Competitive benchmarking
+- Claims history analysis
+- Policy optimization
+- Personal coverage consideration
+
+### ESG Governance
+
+#### ESG Integration
+
+**Board Oversight**:
+- ESG committee or full board
+- Regular ESG updates
+- Metrics in dashboard
+- Risk assessment
+- Stakeholder feedback
+
+**Reporting Framework**:
+- SASB standards
+- TCFD recommendations
+- GRI guidelines
+- UN SDGs alignment
+- Integrated reporting
+
+**Investor Communication**:
+- ESG highlights in earnings
+- Dedicated ESG report
+- Website ESG section
+- ESG investor days
+- Rating agency engagement
+
+## Templates & Tools
+
+### Board Resolution Template
+
+```
+BOARD RESOLUTION
+
+WHEREAS, [background/context];
+
+WHEREAS, [additional context];
+
+NOW, THEREFORE, BE IT RESOLVED, that [specific action];
+
+FURTHER RESOLVED, that [additional actions];
+
+FURTHER RESOLVED, that [authorization].
+
+Approved this [date].
+
+_____________________
+[Secretary Name]
+Corporate Secretary
+```
+
+### Insider Trading Policy Outline
+
+1. **Scope**: All directors, officers, employees
+2. **Prohibited Activities**: Trading on MNPI
+3. **Trading Windows**: Quarterly schedule
+4. **Pre-clearance**: Required for all trades
+5. **Blackout Periods**: Defined schedule
+6. **10b5-1 Plans**: Permitted with approval
+7. **Violations**: Disciplinary action
+8. **Training**: Annual requirement
+
+### Proxy Statement Checklist
+
+- [ ] Executive compensation (CD&A)
+- [ ] Director nominees
+- [ ] Governance structure
+- [ ] Shareholder proposals
+- [ ] Audit matters
+- [ ] Related party transactions
+- [ ] Risk oversight
+- [ ] Succession planning
+- [ ] ESG disclosure
+- [ ] Virtual meeting details
diff --git a/skills/ceo-advisor/references/executive_decision_framework.md b/skills/ceo-advisor/references/executive_decision_framework.md
new file mode 100644
index 00000000..f5251a91
--- /dev/null
+++ b/skills/ceo-advisor/references/executive_decision_framework.md
@@ -0,0 +1,475 @@
+# Executive Decision Framework
+
+## Decision-Making Process
+
+### The DECIDE Framework
+
+**D** - Define the problem clearly
+**E** - Establish criteria for solutions
+**C** - Consider alternatives
+**I** - Identify best alternatives
+**D** - Develop and implement action plan
+**E** - Evaluate and monitor solution
+
+## Strategic Decision Categories
+
+### 1. Growth Decisions
+
+#### Market Expansion
+**Evaluation Criteria**:
+- Market size and growth rate
+- Competitive landscape
+- Regulatory environment
+- Cultural fit
+- Required investment
+- Expected ROI
+
+**Decision Matrix**:
+| Factor | Weight | Score (1-10) | Weighted Score |
+|--------|--------|--------------|----------------|
+| Market Size | 25% | | |
+| Competition | 20% | | |
+| Fit with Core | 20% | | |
+| Investment Required | 15% | | |
+| Risk Level | 10% | | |
+| Timeline to Profit | 10% | | |
+
+#### Product Development
+**Go/No-Go Criteria**:
+- Customer demand validation (>70% interest)
+- Technical feasibility confirmed
+- Positive unit economics
+- Strategic alignment
+- Available resources
+
+#### Mergers & Acquisitions
+**Due Diligence Framework**:
+1. **Strategic Fit**
+ - Synergies identification
+ - Cultural alignment
+ - Market position enhancement
+
+2. **Financial Analysis**
+ - Valuation models (DCF, Multiples, Precedent)
+ - ROI projections
+ - Integration costs
+
+3. **Risk Assessment**
+ - Legal/regulatory issues
+ - Technology compatibility
+ - Talent retention
+
+4. **Integration Planning**
+ - 100-day plan
+ - Communication strategy
+ - Success metrics
+
+### 2. Resource Allocation
+
+#### Capital Allocation Framework
+
+**Priority Levels**:
+1. **Essential** - Core operations, compliance, security
+2. **Strategic** - Growth initiatives, competitive advantage
+3. **Efficiency** - Cost reduction, productivity
+4. **Experimental** - Innovation, R&D
+
+**Allocation Guidelines**:
+- Essential: 40-50%
+- Strategic: 30-40%
+- Efficiency: 10-15%
+- Experimental: 5-10%
+
+#### Budget Decision Tree
+```
+Is it required for operations?
+├─ Yes → Essential (Auto-approve if <$X)
+└─ No → Does it drive growth?
+ ├─ Yes → What's the ROI?
+ │ ├─ >30% → Strategic (Approve)
+ │ └─ <30% → Defer/Reject
+ └─ No → Does it reduce costs?
+ ├─ Yes → Payback period?
+ │ ├─ <12 months → Efficiency (Approve)
+ │ └─ >12 months → Defer
+ └─ No → Experimental (Limited budget)
+```
+
+### 3. Organizational Decisions
+
+#### Restructuring Framework
+
+**Triggers for Restructuring**:
+- Performance below targets for 2+ quarters
+- Major strategic shift
+- M&A integration
+- Market disruption
+- Efficiency opportunity >20%
+
+**Evaluation Process**:
+1. Current state assessment
+2. Future state design
+3. Gap analysis
+4. Impact assessment
+5. Implementation planning
+6. Communication strategy
+
+#### Leadership Changes
+
+**Performance Evaluation Matrix**:
+| Dimension | Weight | Indicators |
+|-----------|--------|------------|
+| Results Delivery | 40% | KPIs, OKRs achievement |
+| Team Leadership | 25% | Engagement, retention, development |
+| Strategic Thinking | 20% | Innovation, vision, planning |
+| Culture Fit | 15% | Values alignment, collaboration |
+
+**Succession Planning**:
+- Identify 2-3 potential successors for each key role
+- Development plans for high-potentials
+- Emergency succession protocols
+- Knowledge transfer processes
+
+### 4. Crisis Management
+
+#### Crisis Response Protocol
+
+**Immediate (0-2 hours)**:
+1. Activate crisis team
+2. Assess severity and impact
+3. Implement containment measures
+4. Initial stakeholder notification
+
+**Short-term (2-24 hours)**:
+1. Develop response strategy
+2. Prepare public statements
+3. Engage legal/regulatory as needed
+4. Employee communication
+
+**Recovery (24+ hours)**:
+1. Implement solution
+2. Monitor progress
+3. Stakeholder updates
+4. Post-crisis review
+
+#### Crisis Decision Authority
+
+| Crisis Level | Decision Authority | Response Team |
+|--------------|-------------------|---------------|
+| Level 1 (Minor) | Department Head | Local team |
+| Level 2 (Moderate) | C-Suite Member | Cross-functional |
+| Level 3 (Major) | CEO | Executive team |
+| Level 4 (Critical) | CEO + Board | All hands |
+
+## Decision Support Tools
+
+### 1. SWOT-TOWS Matrix
+
+```
+ Internal →
+ ↓ Strengths (S) Weaknesses (W)
+External
+
+O SO Strategies WO Strategies
+p (Leverage) (Improve)
+p
+o
+r
+t
+
+T ST Strategies WT Strategies
+h (Protect) (Survive)
+r
+e
+a
+t
+s
+```
+
+### 2. BCG Growth-Share Matrix
+
+```
+Market Growth Rate
+ ↑
+High │ Stars │ Question │
+ │ │ Marks │
+ ├─────────┼──────────┤
+Low │ Cash │ Dogs │
+ │ Cows │ │
+ └─────────┴──────────┘
+ High Low →
+ Market Share
+```
+
+### 3. Risk-Impact Matrix
+
+```
+Impact
+ ↑
+High │ Mitigate │ Critical │
+ │ │ Focus │
+ ├──────────┼──────────┤
+Low │ Accept │ Monitor │
+ │ │ │
+ └──────────┴──────────┘
+ Low High →
+ Probability
+```
+
+### 4. Eisenhower Matrix
+
+```
+Urgency
+ ↑
+High │ Do │ Schedule │
+ │ First │ │
+ ├─────────┼──────────┤
+Low │ Delegate│ Eliminate│
+ │ │ │
+ └─────────┴──────────┘
+ High Low →
+ Importance
+```
+
+## Strategic Options Framework
+
+### Porter's Generic Strategies
+
+1. **Cost Leadership**
+ - Operational excellence
+ - Economy of scale
+ - Process optimization
+ - Supply chain efficiency
+
+2. **Differentiation**
+ - Unique value proposition
+ - Premium positioning
+ - Innovation focus
+ - Brand strength
+
+3. **Focus**
+ - Niche markets
+ - Specialized offerings
+ - Deep expertise
+ - Customer intimacy
+
+### Blue Ocean Strategy
+
+**Four Actions Framework**:
+- **Eliminate**: Which factors can be eliminated?
+- **Reduce**: Which factors should be reduced below industry standard?
+- **Raise**: Which factors should be raised above industry standard?
+- **Create**: Which factors should be created that the industry has never offered?
+
+## Stakeholder Management
+
+### Stakeholder Mapping
+
+```
+Influence/Power
+ ↑
+High │ Manage │ Key │
+ │ Closely │ Players │
+ ├──────────┼──────────┤
+Low │ Monitor │ Keep │
+ │ │ Informed │
+ └──────────┴──────────┘
+ Low High →
+ Interest
+```
+
+### Communication Strategy
+
+| Stakeholder | Frequency | Format | Key Messages |
+|------------|-----------|--------|--------------|
+| Board | Monthly | Report + Meeting | Strategy, Risk, Performance |
+| Investors | Quarterly | Earnings Call | Financial, Growth, Outlook |
+| Employees | Weekly | All-hands | Vision, Updates, Recognition |
+| Customers | Continuous | Multi-channel | Value, Innovation, Support |
+| Media | As needed | Press Release | Milestones, Position, Vision |
+
+## Performance Metrics
+
+### Balanced Scorecard
+
+#### Financial Perspective
+- Revenue growth rate
+- EBITDA margin
+- ROE/ROA
+- Cash conversion cycle
+- Market capitalization
+
+#### Customer Perspective
+- Customer satisfaction (NPS)
+- Market share
+- Customer retention rate
+- Customer acquisition cost
+- Customer lifetime value
+
+#### Internal Process
+- Operational efficiency
+- Time to market
+- Quality metrics
+- Innovation rate
+- Process cycle time
+
+#### Learning & Growth
+- Employee engagement
+- Talent retention
+- Training hours per employee
+- Leadership pipeline
+- Innovation index
+
+## Decision Biases to Avoid
+
+### Cognitive Biases
+
+1. **Confirmation Bias**
+ - Mitigation: Seek contrarian views
+ - Tool: Devil's advocate process
+
+2. **Anchoring Bias**
+ - Mitigation: Multiple estimates
+ - Tool: Range forecasting
+
+3. **Sunk Cost Fallacy**
+ - Mitigation: Zero-based thinking
+ - Tool: Regular portfolio review
+
+4. **Overconfidence Bias**
+ - Mitigation: Outside view
+ - Tool: Reference class forecasting
+
+5. **Availability Heuristic**
+ - Mitigation: Data-driven decisions
+ - Tool: Systematic analysis
+
+### Decision Hygiene Checklist
+
+- [ ] Problem clearly defined
+- [ ] All stakeholders identified
+- [ ] Data/evidence gathered
+- [ ] Multiple options generated
+- [ ] Biases checked
+- [ ] Risks assessed
+- [ ] Implementation plan created
+- [ ] Success metrics defined
+- [ ] Review process established
+
+## Executive Communication
+
+### Board Presentation Template
+
+1. **Executive Summary** (1 slide)
+ - Key achievements
+ - Critical issues
+ - Decisions needed
+
+2. **Performance Review** (3-4 slides)
+ - Financial results
+ - Operational metrics
+ - Strategic progress
+
+3. **Market & Competition** (2 slides)
+ - Market dynamics
+ - Competitive position
+
+4. **Strategic Initiatives** (3-4 slides)
+ - Current initiatives
+ - Results to date
+ - Next steps
+
+5. **Risk & Mitigation** (2 slides)
+ - Risk register
+ - Mitigation actions
+
+6. **Ask of the Board** (1 slide)
+ - Decisions required
+ - Support needed
+
+### Investor Relations Framework
+
+**Earnings Call Structure**:
+1. Opening remarks (CEO) - 5 min
+2. Financial review (CFO) - 10 min
+3. Strategic update (CEO) - 10 min
+4. Q&A - 30 min
+
+**Key Messages**:
+- Performance vs guidance
+- Market position
+- Growth strategy
+- Capital allocation
+- Outlook
+
+## Strategic Planning Cycle
+
+### Annual Planning Process
+
+**Q3 - Strategic Review**
+- Environmental scan
+- Competitive analysis
+- Capability assessment
+- Strategy refinement
+
+**Q4 - Planning**
+- Goal setting
+- Budget allocation
+- Resource planning
+- OKR development
+
+**Q1 - Launch**
+- Communication cascade
+- Initiative kickoff
+- Quick wins
+- Baseline metrics
+
+**Q2 - Review**
+- Progress assessment
+- Course correction
+- Mid-year planning
+- Performance review
+
+## Exit Strategy Planning
+
+### Exit Options Evaluation
+
+1. **IPO**
+ - Pros: Maximum valuation, maintain control
+ - Cons: Regulatory burden, public scrutiny
+ - Timeline: 12-24 months
+
+2. **Strategic Acquisition**
+ - Pros: Synergies, quick process
+ - Cons: Loss of independence, integration risk
+ - Timeline: 6-12 months
+
+3. **Private Equity**
+ - Pros: Growth capital, expertise
+ - Cons: Pressure for returns, loss of control
+ - Timeline: 3-6 months
+
+4. **Management Buyout**
+ - Pros: Continuity, culture preservation
+ - Cons: Limited price, financing challenge
+ - Timeline: 6-9 months
+
+### Value Creation Levers
+
+1. **Revenue Growth**
+ - Organic expansion
+ - Market development
+ - Product innovation
+ - Pricing optimization
+
+2. **Margin Improvement**
+ - Operational efficiency
+ - Cost reduction
+ - Mix optimization
+ - Pricing power
+
+3. **Multiple Expansion**
+ - Market positioning
+ - Growth trajectory
+ - Risk reduction
+ - Story telling
diff --git a/skills/ceo-advisor/references/leadership_organizational_culture.md b/skills/ceo-advisor/references/leadership_organizational_culture.md
new file mode 100644
index 00000000..5b3d911f
--- /dev/null
+++ b/skills/ceo-advisor/references/leadership_organizational_culture.md
@@ -0,0 +1,682 @@
+# Leadership & Organizational Culture Guide
+
+## Leadership Philosophy
+
+### The Five Dimensions of CEO Leadership
+
+1. **Visionary Leadership**
+ - Define compelling future state
+ - Communicate vision consistently
+ - Inspire action toward vision
+ - Measure progress systematically
+
+2. **Strategic Leadership**
+ - Set clear priorities
+ - Allocate resources optimally
+ - Make tough trade-offs
+ - Drive execution excellence
+
+3. **Operational Leadership**
+ - Establish performance standards
+ - Build scalable systems
+ - Drive continuous improvement
+ - Ensure accountability
+
+4. **People Leadership**
+ - Attract top talent
+ - Develop future leaders
+ - Foster engagement
+ - Build inclusive culture
+
+5. **External Leadership**
+ - Represent company publicly
+ - Build strategic partnerships
+ - Engage stakeholders effectively
+ - Shape industry direction
+
+## Organizational Culture Framework
+
+### Culture Definition & Assessment
+
+#### Cultural Dimensions Model
+
+**Innovation ← → Stability**
+- Risk tolerance level
+- Change readiness
+- Experimentation mindset
+- Learning from failure
+
+**Competition ← → Collaboration**
+- Internal dynamics
+- Knowledge sharing
+- Team vs individual rewards
+- Cross-functional cooperation
+
+**Customer ← → Operations**
+- External vs internal focus
+- Customer centricity
+- Process emphasis
+- Quality standards
+
+**Short-term ← → Long-term**
+- Planning horizons
+- Investment philosophy
+- Performance metrics
+- Stakeholder balance
+
+### Culture Transformation Roadmap
+
+#### Phase 1: Assessment (Months 1-2)
+
+**Current State Analysis**:
+- Employee survey (engagement, values alignment)
+- Culture assessment (competing values framework)
+- Leadership 360 feedback
+- Exit interview analysis
+- Customer feedback integration
+
+**Gap Analysis**:
+- Current vs desired culture
+- Behavioral gaps
+- System misalignments
+- Leadership gaps
+- Communication gaps
+
+#### Phase 2: Design (Months 2-3)
+
+**Target Culture Definition**:
+- Core values articulation
+- Behavioral standards
+- Leadership principles
+- Decision principles
+- Performance expectations
+
+**Change Strategy**:
+- Stakeholder mapping
+- Communication plan
+- Training requirements
+- System changes needed
+- Quick wins identification
+
+#### Phase 3: Implementation (Months 4-12)
+
+**Launch Activities**:
+- Leadership alignment sessions
+- All-hands kickoff
+- Values workshops
+- Behavioral training
+- System updates
+
+**Reinforcement Mechanisms**:
+- Recognition programs
+- Performance integration
+- Hiring/promotion criteria
+- Story collection
+- Celebration events
+
+#### Phase 4: Embedding (Months 12+)
+
+**Sustainability Actions**:
+- Regular pulse surveys
+- Culture champions network
+- Continuous reinforcement
+- System alignment
+- Leadership modeling
+
+## Leadership Development
+
+### Executive Team Development
+
+#### Team Effectiveness Model
+
+**Foundation Elements**:
+1. **Trust** - Vulnerability-based trust
+2. **Conflict** - Healthy debate
+3. **Commitment** - Buy-in to decisions
+4. **Accountability** - Peer accountability
+5. **Results** - Collective outcomes
+
+#### Executive Team Charter
+
+```
+Our Executive Team Charter
+
+Purpose:
+Lead [Company] to achieve its vision of [Vision Statement]
+
+Responsibilities:
+• Set strategic direction
+• Allocate resources
+• Drive performance
+• Develop talent
+• Shape culture
+
+Operating Principles:
+• Debate in private, unite in public
+• Challenge ideas, support people
+• Company first, function second
+• Transparency with trust
+• Accountability without blame
+
+Meeting Cadence:
+• Weekly tactical (2 hours)
+• Monthly strategic (4 hours)
+• Quarterly offsite (2 days)
+• Annual planning (3 days)
+
+Decision Rights:
+• CEO: Final decision after consultation
+• Consensus: Strategic initiatives
+• Individual: Functional operations
+• Escalation: Board-level matters
+
+Success Metrics:
+• Company performance vs plan
+• Employee engagement score
+• Customer satisfaction (NPS)
+• Team effectiveness rating
+```
+
+### Succession Planning
+
+#### Succession Planning Framework
+
+**CEO Succession Timeline**:
+
+**Ongoing**:
+- Identify potential successors
+- Development plan execution
+- Board exposure
+- External benchmarking
+
+**T-3 Years**:
+- Formal succession planning
+- Candidate assessment
+- Development acceleration
+- Emergency plan update
+
+**T-1 Year**:
+- Final candidate selection
+- Transition planning
+- Communication strategy
+- Onboarding preparation
+
+**Transition**:
+- Announcement
+- Knowledge transfer
+- Stakeholder introductions
+- Gradual handover
+
+#### Talent Pipeline Development
+
+**9-Box Grid for Talent Review**:
+
+```
+Performance →
+ ↑
+ │ Rising │ High │ Star
+High│ Star │Performer│ Performer
+ ├─────────┼─────────┼──────────
+ │Solid │ Core │ High
+Med │Performer│Performer│ Potential
+ ├─────────┼─────────┼──────────
+ │ Under │Inconsist│ New/
+Low │Performer│ -ent │ Learning
+ └─────────┴─────────┴──────────
+ Low Medium High
+ Potential →
+```
+
+**Development Strategies by Box**:
+- **Stars**: Accelerated development, stretch assignments
+- **High Performers**: Retention focus, leadership opportunities
+- **High Potentials**: Intensive coaching, skill building
+- **Core Performers**: Engagement, incremental growth
+- **Underperformers**: Performance improvement or exit
+
+### Leadership Competency Model
+
+#### Core Leadership Competencies
+
+**Strategic Thinking**
+- Vision development
+- Systems thinking
+- Innovation mindset
+- External awareness
+- Long-term planning
+
+**Execution Excellence**
+- Results orientation
+- Decision quality
+- Problem solving
+- Process management
+- Risk management
+
+**People Leadership**
+- Team building
+- Talent development
+- Communication
+- Influence
+- Emotional intelligence
+
+**Personal Excellence**
+- Integrity
+- Resilience
+- Continuous learning
+- Self-awareness
+- Adaptability
+
+## Communication & Engagement
+
+### Internal Communication Strategy
+
+#### Communication Channels
+
+| Channel | Frequency | Purpose | Audience |
+|---------|-----------|---------|----------|
+| All-hands meeting | Monthly | Updates, Q&A | All employees |
+| Leadership cascade | Weekly | Alignment | Managers |
+| CEO email | Bi-weekly | Vision, recognition | All employees |
+| Town halls | Quarterly | Deep dives | All employees |
+| Skip-levels | Monthly | Direct feedback | Various levels |
+| Intranet | Daily | News, resources | All employees |
+| Slack/Teams | Real-time | Collaboration | All employees |
+
+#### CEO Communication Calendar
+
+**Weekly**:
+- Executive team meeting
+- Leadership message cascade
+- Customer/partner touchpoint
+
+**Bi-weekly**:
+- Company-wide email
+- Skip-level meetings
+- Media/analyst interaction
+
+**Monthly**:
+- All-hands meeting
+- Board member touchpoint
+- Employee roundtable
+
+**Quarterly**:
+- Earnings communication
+- Town hall deep-dive
+- Strategy review
+- Culture celebration
+
+### Employee Engagement
+
+#### Engagement Survey Framework
+
+**Dimensions Measured**:
+1. Purpose & Vision (alignment, inspiration)
+2. Leadership (trust, communication)
+3. Management (support, development)
+4. Work Environment (tools, processes)
+5. Growth (career, learning)
+6. Recognition (appreciation, fairness)
+7. Wellbeing (balance, benefits)
+8. Belonging (inclusion, connection)
+
+**Action Planning Process**:
+1. Share results transparently
+2. Identify 2-3 focus areas
+3. Create action teams
+4. Define success metrics
+5. Implement changes
+6. Communicate progress
+7. Measure impact
+
+#### Engagement Initiatives
+
+**Recognition Programs**:
+- Spot awards (peer-nominated)
+- Quarterly achievements
+- Annual excellence awards
+- Values champions
+- Innovation celebrations
+- Customer hero awards
+
+**Development Programs**:
+- Leadership academy
+- Mentorship program
+- Rotation opportunities
+- Tuition reimbursement
+- Conference attendance
+- Skill workshops
+
+**Wellbeing Initiatives**:
+- Flexible work arrangements
+- Mental health support
+- Wellness programs
+- Time-off policies
+- Family support
+- Financial wellness
+
+## Performance Management
+
+### OKR Framework
+
+#### OKR Setting Process
+
+**Company OKRs** (Annual)
+↓
+**Department OKRs** (Quarterly)
+↓
+**Team OKRs** (Quarterly)
+↓
+**Individual OKRs** (Quarterly)
+
+#### OKR Template
+
+**Objective**: [Qualitative, inspirational goal]
+
+**Key Results**:
+1. [Quantitative outcome] from [X] to [Y]
+2. [Quantitative outcome] from [X] to [Y]
+3. [Quantitative outcome] from [X] to [Y]
+
+**Example**:
+```
+Objective: Become the market leader in customer satisfaction
+
+Key Results:
+1. Increase NPS from 45 to 70
+2. Reduce support ticket resolution from 48h to 24h
+3. Achieve 95% customer retention rate (from 87%)
+```
+
+### Performance Review System
+
+#### Continuous Performance Management
+
+**Weekly**: 1-on-1 check-ins (30 min)
+- Progress on priorities
+- Obstacles/support needed
+- Feedback exchange
+- Next week focus
+
+**Monthly**: Development discussion (60 min)
+- Skill development
+- Career aspirations
+- Stretch opportunities
+- Learning plan
+
+**Quarterly**: Performance review (90 min)
+- OKR assessment
+- Competency evaluation
+- 360 feedback review
+- Development planning
+
+**Annual**: Compensation review
+- Performance rating
+- Compensation adjustment
+- Promotion decisions
+- Succession planning
+
+## Change Management
+
+### Change Leadership Model
+
+#### Eight-Step Change Process
+
+1. **Create Urgency**
+ - Share compelling data
+ - Highlight risks of status quo
+ - Create dissatisfaction with current state
+
+2. **Build Coalition**
+ - Identify change champions
+ - Ensure executive alignment
+ - Engage influential supporters
+
+3. **Form Vision**
+ - Define clear end state
+ - Create inspiring narrative
+ - Develop strategy
+
+4. **Communicate Vision**
+ - Multi-channel communication
+ - Repetition and consistency
+ - Two-way dialogue
+
+5. **Empower Action**
+ - Remove barriers
+ - Change systems/processes
+ - Encourage risk-taking
+
+6. **Create Quick Wins**
+ - Identify early victories
+ - Celebrate visibly
+ - Build momentum
+
+7. **Consolidate Gains**
+ - Don't declare victory early
+ - Continue driving change
+ - Address deeper issues
+
+8. **Anchor in Culture**
+ - Reinforce through systems
+ - Celebrate new behaviors
+ - Ensure leadership continuity
+
+### Organizational Design
+
+#### Design Principles
+
+**Customer-Centric**
+- Organize around customer needs
+- Minimize handoffs
+- Clear ownership
+- Fast decision-making
+
+**Scalable**
+- Consistent structures
+- Clear roles/responsibilities
+- Repeatable processes
+- Growth-ready
+
+**Agile**
+- Cross-functional teams
+- Rapid iteration
+- Continuous learning
+- Adaptive planning
+
+**Efficient**
+- Appropriate spans of control (5-7)
+- Minimal layers (max 5-6)
+- Clear decision rights
+- Eliminated redundancy
+
+#### Reorganization Playbook
+
+**Pre-announcement** (4-6 weeks)
+- Design new structure
+- Identify leadership
+- Plan communication
+- Prepare materials
+
+**Announcement** (Day 0)
+- All-hands meeting
+- Written communication
+- Q&A sessions
+- Manager toolkit
+
+**Transition** (30 days)
+- Role clarifications
+- Team formations
+- Process updates
+- System changes
+
+**Stabilization** (60-90 days)
+- Monitor progress
+- Address issues
+- Refine as needed
+- Celebrate success
+
+## Crisis Leadership
+
+### Crisis Response Framework
+
+#### Leadership During Crisis
+
+**Immediate Response** (0-24 hours)
+- Establish command center
+- Assess situation
+- Communicate frequently
+- Make rapid decisions
+- Show visible leadership
+
+**Stabilization** (1-7 days)
+- Implement solutions
+- Maintain communication
+- Support teams
+- Monitor progress
+- Adjust approach
+
+**Recovery** (1-4 weeks)
+- Execute recovery plan
+- Address long-term impacts
+- Learn from crisis
+- Strengthen resilience
+- Recognize heroes
+
+#### Crisis Communication
+
+**Internal Communication**:
+- Frequency: 2x daily minimum
+- Channels: Email, video, town halls
+- Content: Facts, actions, support
+- Tone: Calm, confident, caring
+
+**External Communication**:
+- Stakeholders: Customers, partners, investors, media
+- Frequency: As needed
+- Channels: Website, press, social
+- Content: Impact, response, timeline
+- Tone: Transparent, responsible
+
+## Innovation Culture
+
+### Innovation Framework
+
+#### Innovation Portfolio
+
+**Horizon 1** (70% resources)
+- Core business innovation
+- Incremental improvements
+- 6-18 month timeline
+- Lower risk
+
+**Horizon 2** (20% resources)
+- Emerging opportunities
+- Adjacent markets
+- 18-36 month timeline
+- Moderate risk
+
+**Horizon 3** (10% resources)
+- Transformational bets
+- New business models
+- 3-5 year timeline
+- Higher risk
+
+#### Innovation Programs
+
+**Innovation Time**
+- 20% time for projects
+- Hackathons quarterly
+- Innovation challenges
+- Idea platforms
+- Patent incentives
+
+**Innovation Metrics**
+- % revenue from new products
+- Ideas generated/implemented
+- Time to market
+- Innovation ROI
+- Patent applications
+
+## Diversity, Equity & Inclusion
+
+### DEI Strategy Framework
+
+#### Four Pillars of DEI
+
+1. **Representation**
+ - Diverse hiring
+ - Promotion equity
+ - Leadership diversity
+ - Board diversity
+
+2. **Inclusion**
+ - Belonging index
+ - Psychological safety
+ - Equitable practices
+ - Bias mitigation
+
+3. **Development**
+ - Sponsorship programs
+ - ERG support
+ - Leadership development
+ - Career pathways
+
+4. **Accountability**
+ - DEI metrics
+ - Leader goals
+ - Regular reporting
+ - Transparency
+
+#### DEI Metrics Dashboard
+
+| Metric | Current | Target | Timeline |
+|--------|---------|--------|----------|
+| Women in leadership | X% | Y% | Z years |
+| Ethnic diversity | X% | Y% | Z years |
+| Pay equity gap | X% | 0% | Z years |
+| Inclusion index | X/100 | Y/100 | Z years |
+| Retention equality | X% diff | 0% diff | Z years |
+
+## Executive Presence
+
+### CEO Personal Brand
+
+#### Brand Elements
+
+**Vision**: What future you're creating
+**Values**: What you stand for
+**Voice**: How you communicate
+**Visibility**: Where you show up
+**Value**: What you deliver
+
+#### Executive Communication
+
+**Speaking Frameworks**:
+
+**PREP Method**:
+- **P**oint: Main message
+- **R**eason: Why it matters
+- **E**xample: Concrete illustration
+- **P**oint: Restate message
+
+**STAR Method** (for stories):
+- **S**ituation: Context
+- **T**ask: Challenge
+- **A**ction: What was done
+- **R**esult: Outcome
+
+#### Media Training Essentials
+
+**Key Message Discipline**:
+- 3 key messages maximum
+- Bridge to messages
+- Sound bites ready
+- Avoid speculation
+- Stay on record
+
+**Interview Techniques**:
+- Pause before answering
+- Bridge to key messages
+- Use examples/stories
+- Maintain eye contact
+- Control pace
diff --git a/skills/ceo-advisor/scripts/financial_scenario_analyzer.py b/skills/ceo-advisor/scripts/financial_scenario_analyzer.py
new file mode 100644
index 00000000..45bf8445
--- /dev/null
+++ b/skills/ceo-advisor/scripts/financial_scenario_analyzer.py
@@ -0,0 +1,451 @@
+#!/usr/bin/env python3
+"""
+Financial Scenario Analyzer - Model different business scenarios and their financial impact
+"""
+
+import json
+from typing import Dict, List, Tuple
+import math
+
+class FinancialScenarioAnalyzer:
+ def __init__(self):
+ self.key_metrics = [
+ 'revenue', 'gross_margin', 'operating_expenses',
+ 'ebitda', 'cash_flow', 'runway', 'valuation'
+ ]
+
+ self.growth_models = {
+ 'linear': lambda base, rate, period: base * (1 + rate * period),
+ 'exponential': lambda base, rate, period: base * math.pow(1 + rate, period),
+ 'logarithmic': lambda base, rate, period: base * (1 + rate * math.log(period + 1)),
+ 's_curve': lambda base, rate, period: base * (2 / (1 + math.exp(-rate * period)))
+ }
+
+ def analyze_scenarios(self, base_case: Dict, scenarios: List[Dict]) -> Dict:
+ """Analyze multiple financial scenarios"""
+ results = {
+ 'base_case_summary': self._summarize_financials(base_case),
+ 'scenario_analysis': [],
+ 'sensitivity_analysis': {},
+ 'recommendation': {},
+ 'risk_adjusted_view': {}
+ }
+
+ # Analyze each scenario
+ for scenario in scenarios:
+ scenario_result = self._analyze_scenario(base_case, scenario)
+ results['scenario_analysis'].append(scenario_result)
+
+ # Sensitivity analysis
+ results['sensitivity_analysis'] = self._perform_sensitivity_analysis(
+ base_case,
+ scenarios
+ )
+
+ # Risk-adjusted view
+ results['risk_adjusted_view'] = self._calculate_risk_adjusted_returns(
+ results['scenario_analysis']
+ )
+
+ # Generate recommendation
+ results['recommendation'] = self._generate_recommendation(
+ results['scenario_analysis'],
+ results['risk_adjusted_view']
+ )
+
+ return results
+
+ def _summarize_financials(self, financials: Dict) -> Dict:
+ """Summarize key financial metrics"""
+ revenue = financials.get('revenue', 0)
+ cogs = financials.get('cogs', 0)
+ opex = financials.get('operating_expenses', 0)
+
+ gross_profit = revenue - cogs
+ gross_margin = (gross_profit / revenue * 100) if revenue > 0 else 0
+ ebitda = gross_profit - opex
+ ebitda_margin = (ebitda / revenue * 100) if revenue > 0 else 0
+
+ return {
+ 'revenue': revenue,
+ 'gross_profit': gross_profit,
+ 'gross_margin': gross_margin,
+ 'operating_expenses': opex,
+ 'ebitda': ebitda,
+ 'ebitda_margin': ebitda_margin,
+ 'cash': financials.get('cash', 0),
+ 'burn_rate': financials.get('burn_rate', 0),
+ 'runway_months': self._calculate_runway(
+ financials.get('cash', 0),
+ financials.get('burn_rate', 0)
+ )
+ }
+
+ def _calculate_runway(self, cash: float, burn_rate: float) -> float:
+ """Calculate months of runway"""
+ if burn_rate <= 0:
+ return float('inf')
+ return cash / burn_rate
+
+ def _analyze_scenario(self, base_case: Dict, scenario: Dict) -> Dict:
+ """Analyze a single scenario"""
+ name = scenario.get('name', 'Unnamed Scenario')
+ probability = scenario.get('probability', 0.5)
+
+ # Apply scenario changes
+ projected_financials = self._apply_scenario_changes(base_case, scenario)
+
+ # Calculate metrics for each year
+ projections = []
+ current_state = projected_financials.copy()
+
+ for year in range(1, 4): # 3-year projection
+ year_projection = self._project_year(
+ current_state,
+ scenario,
+ year
+ )
+ projections.append(year_projection)
+ current_state = year_projection
+
+ # Calculate NPV and IRR
+ cash_flows = [p['free_cash_flow'] for p in projections]
+ npv = self._calculate_npv(cash_flows, scenario.get('discount_rate', 0.1))
+ irr = self._calculate_irr(cash_flows, base_case.get('initial_investment', 0))
+
+ return {
+ 'name': name,
+ 'probability': probability,
+ 'projections': projections,
+ 'npv': npv,
+ 'irr': irr,
+ 'break_even_month': self._find_break_even(projections),
+ 'total_return': self._calculate_total_return(projections, base_case),
+ 'key_assumptions': scenario.get('assumptions', [])
+ }
+
+ def _apply_scenario_changes(self, base_case: Dict, scenario: Dict) -> Dict:
+ """Apply scenario changes to base case"""
+ result = base_case.copy()
+ changes = scenario.get('changes', {})
+
+ for key, change in changes.items():
+ if key in result:
+ if isinstance(change, dict):
+ # Relative change
+ if 'multiply' in change:
+ result[key] *= change['multiply']
+ elif 'add' in change:
+ result[key] += change['add']
+ else:
+ # Absolute change
+ result[key] = change
+
+ return result
+
+ def _project_year(self, current_state: Dict, scenario: Dict, year: int) -> Dict:
+ """Project financials for a specific year"""
+ growth_model = scenario.get('growth_model', 'exponential')
+ growth_rate = scenario.get('growth_rate', 0.3)
+
+ # Apply growth model
+ model_func = self.growth_models.get(growth_model, self.growth_models['linear'])
+
+ revenue = model_func(
+ current_state.get('revenue', 0),
+ growth_rate,
+ year
+ )
+
+ # Scale other metrics
+ cogs = revenue * scenario.get('cogs_ratio', 0.3)
+ opex = current_state.get('operating_expenses', 0) * (1 + scenario.get('opex_growth', 0.15))
+
+ gross_profit = revenue - cogs
+ ebitda = gross_profit - opex
+
+ # Calculate free cash flow (simplified)
+ capex = revenue * scenario.get('capex_ratio', 0.05)
+ working_capital_change = (revenue - current_state.get('revenue', 0)) * 0.1
+ free_cash_flow = ebitda - capex - working_capital_change
+
+ return {
+ 'year': year,
+ 'revenue': revenue,
+ 'gross_profit': gross_profit,
+ 'gross_margin': (gross_profit / revenue * 100) if revenue > 0 else 0,
+ 'operating_expenses': opex,
+ 'ebitda': ebitda,
+ 'ebitda_margin': (ebitda / revenue * 100) if revenue > 0 else 0,
+ 'free_cash_flow': free_cash_flow,
+ 'cumulative_cash_flow': current_state.get('cumulative_cash_flow', 0) + free_cash_flow
+ }
+
+ def _calculate_npv(self, cash_flows: List[float], discount_rate: float) -> float:
+ """Calculate Net Present Value"""
+ npv = 0
+ for i, cf in enumerate(cash_flows):
+ npv += cf / math.pow(1 + discount_rate, i + 1)
+ return npv
+
+ def _calculate_irr(self, cash_flows: List[float], initial_investment: float) -> float:
+ """Calculate Internal Rate of Return (simplified)"""
+ if not cash_flows or initial_investment == 0:
+ return 0
+
+ # Simple IRR approximation
+ total_return = sum(cash_flows)
+ years = len(cash_flows)
+
+ if initial_investment > 0:
+ return math.pow(total_return / initial_investment, 1/years) - 1
+ return 0
+
+ def _find_break_even(self, projections: List[Dict]) -> int:
+ """Find break-even month"""
+ months = 0
+ for projection in projections:
+ months += 12
+ if projection.get('ebitda', 0) > 0:
+ # Interpolate to find exact month
+ if months == 12:
+ return months
+ prev_ebitda = projections[projection['year']-2].get('ebitda', 0) if projection['year'] > 1 else 0
+ monthly_improvement = (projection['ebitda'] - prev_ebitda) / 12
+ if monthly_improvement > 0:
+ months_to_breakeven = abs(prev_ebitda) / monthly_improvement
+ return int(months - 12 + months_to_breakeven)
+ return -1 # Not reached
+
+ def _calculate_total_return(self, projections: List[Dict], base_case: Dict) -> float:
+ """Calculate total return multiple"""
+ initial = base_case.get('valuation', 1000000)
+
+ # Simple valuation at end (10x revenue multiple for SaaS)
+ final_revenue = projections[-1]['revenue'] if projections else 0
+ final_valuation = final_revenue * 10
+
+ return (final_valuation / initial) if initial > 0 else 0
+
+ def _perform_sensitivity_analysis(self, base_case: Dict, scenarios: List[Dict]) -> Dict:
+ """Perform sensitivity analysis on key variables"""
+ sensitivity = {}
+
+ key_variables = ['growth_rate', 'gross_margin', 'customer_acquisition_cost']
+
+ for variable in key_variables:
+ sensitivity[variable] = {
+ 'low': self._calculate_variable_impact(base_case, variable, -0.2),
+ 'base': self._calculate_variable_impact(base_case, variable, 0),
+ 'high': self._calculate_variable_impact(base_case, variable, 0.2)
+ }
+
+ return sensitivity
+
+ def _calculate_variable_impact(self, base_case: Dict, variable: str, change: float) -> float:
+ """Calculate impact of variable change on valuation"""
+ # Simplified impact calculation
+ impacts = {
+ 'growth_rate': 2.5, # 2.5x multiplier on valuation
+ 'gross_margin': 1.8, # 1.8x multiplier
+ 'customer_acquisition_cost': -1.2 # Negative impact
+ }
+
+ base_value = 10000000 # Base valuation
+ impact_multiplier = impacts.get(variable, 1.0)
+
+ return base_value * (1 + change * impact_multiplier)
+
+ def _calculate_risk_adjusted_returns(self, scenarios: List[Dict]) -> Dict:
+ """Calculate risk-adjusted returns"""
+ expected_value = 0
+ best_case = None
+ worst_case = None
+
+ for scenario in scenarios:
+ probability = scenario['probability']
+ npv = scenario['npv']
+
+ expected_value += probability * npv
+
+ if best_case is None or npv > best_case['npv']:
+ best_case = scenario
+
+ if worst_case is None or npv < worst_case['npv']:
+ worst_case = scenario
+
+ # Calculate standard deviation (simplified)
+ variance = sum([
+ scenario['probability'] * math.pow(scenario['npv'] - expected_value, 2)
+ for scenario in scenarios
+ ])
+ std_dev = math.sqrt(variance)
+
+ return {
+ 'expected_value': expected_value,
+ 'best_case': best_case['name'] if best_case else 'None',
+ 'best_case_npv': best_case['npv'] if best_case else 0,
+ 'worst_case': worst_case['name'] if worst_case else 'None',
+ 'worst_case_npv': worst_case['npv'] if worst_case else 0,
+ 'standard_deviation': std_dev,
+ 'sharpe_ratio': (expected_value / std_dev) if std_dev > 0 else 0
+ }
+
+ def _generate_recommendation(self, scenarios: List[Dict], risk_adjusted: Dict) -> Dict:
+ """Generate recommendation based on analysis"""
+ recommendation = {
+ 'recommended_scenario': '',
+ 'rationale': [],
+ 'key_actions': [],
+ 'risk_mitigation': []
+ }
+
+ # Find optimal scenario
+ best_risk_adjusted = max(scenarios, key=lambda s: s['npv'] * s['probability'])
+ recommendation['recommended_scenario'] = best_risk_adjusted['name']
+
+ # Generate rationale
+ if best_risk_adjusted['npv'] > 0:
+ recommendation['rationale'].append(f"Positive NPV of ${best_risk_adjusted['npv']:,.0f}")
+
+ if best_risk_adjusted['irr'] > 0.15:
+ recommendation['rationale'].append(f"Strong IRR of {best_risk_adjusted['irr']:.1%}")
+
+ if best_risk_adjusted['break_even_month'] > 0 and best_risk_adjusted['break_even_month'] < 24:
+ recommendation['rationale'].append(f"Quick path to profitability ({best_risk_adjusted['break_even_month']} months)")
+
+ # Key actions
+ recommendation['key_actions'] = [
+ 'Secure funding for growth initiatives',
+ 'Build scalable operational infrastructure',
+ 'Invest in customer acquisition channels',
+ 'Strengthen unit economics',
+ 'Establish financial controls'
+ ]
+
+ # Risk mitigation
+ if risk_adjusted['standard_deviation'] > risk_adjusted['expected_value'] * 0.5:
+ recommendation['risk_mitigation'].append('High variability - consider hedging strategies')
+
+ recommendation['risk_mitigation'].extend([
+ 'Maintain 12+ months runway',
+ 'Diversify revenue streams',
+ 'Build contingency plans for downside scenarios'
+ ])
+
+ return recommendation
+
+def analyze_financial_scenarios(base_case: Dict, scenarios: List[Dict]) -> str:
+ """Main function to analyze financial scenarios"""
+ analyzer = FinancialScenarioAnalyzer()
+ results = analyzer.analyze_scenarios(base_case, scenarios)
+
+ # Format output
+ output = [
+ "=== Financial Scenario Analysis ===",
+ "",
+ "Base Case Summary:",
+ f" Revenue: ${results['base_case_summary']['revenue']:,.0f}",
+ f" Gross Margin: {results['base_case_summary']['gross_margin']:.1f}%",
+ f" EBITDA: ${results['base_case_summary']['ebitda']:,.0f}",
+ f" Runway: {results['base_case_summary']['runway_months']:.1f} months",
+ "",
+ "Scenario Analysis:"
+ ]
+
+ for scenario in results['scenario_analysis']:
+ output.append(f"\n{scenario['name']} (Probability: {scenario['probability']:.0%})")
+ output.append(f" NPV: ${scenario['npv']:,.0f}")
+ output.append(f" IRR: {scenario['irr']:.1%}")
+ output.append(f" Break-even: {scenario['break_even_month']} months")
+ output.append(f" Return Multiple: {scenario['total_return']:.1f}x")
+
+ # Show Year 3 projection
+ if scenario['projections']:
+ year3 = scenario['projections'][-1]
+ output.append(f" Year 3 Revenue: ${year3['revenue']:,.0f}")
+ output.append(f" Year 3 EBITDA Margin: {year3['ebitda_margin']:.1f}%")
+
+ output.extend([
+ "",
+ "Risk-Adjusted Analysis:",
+ f" Expected Value: ${results['risk_adjusted_view']['expected_value']:,.0f}",
+ f" Best Case: {results['risk_adjusted_view']['best_case']} (${results['risk_adjusted_view']['best_case_npv']:,.0f})",
+ f" Worst Case: {results['risk_adjusted_view']['worst_case']} (${results['risk_adjusted_view']['worst_case_npv']:,.0f})",
+ f" Risk (Std Dev): ${results['risk_adjusted_view']['standard_deviation']:,.0f}",
+ f" Sharpe Ratio: {results['risk_adjusted_view']['sharpe_ratio']:.2f}",
+ "",
+ f"RECOMMENDATION: {results['recommendation']['recommended_scenario']}",
+ "",
+ "Rationale:"
+ ])
+
+ for reason in results['recommendation']['rationale']:
+ output.append(f" • {reason}")
+
+ output.extend([
+ "",
+ "Key Actions:"
+ ])
+
+ for action in results['recommendation']['key_actions'][:3]:
+ output.append(f" • {action}")
+
+ return '\n'.join(output)
+
+if __name__ == "__main__":
+ # Example usage
+ example_base_case = {
+ 'revenue': 5000000,
+ 'cogs': 1500000,
+ 'operating_expenses': 3000000,
+ 'cash': 2000000,
+ 'burn_rate': 200000,
+ 'valuation': 20000000,
+ 'initial_investment': 5000000
+ }
+
+ example_scenarios = [
+ {
+ 'name': 'Aggressive Growth',
+ 'probability': 0.3,
+ 'growth_model': 'exponential',
+ 'growth_rate': 0.5,
+ 'changes': {
+ 'operating_expenses': {'multiply': 1.3}
+ },
+ 'assumptions': ['Market expansion successful', 'Product-market fit achieved'],
+ 'cogs_ratio': 0.25,
+ 'opex_growth': 0.3,
+ 'capex_ratio': 0.08,
+ 'discount_rate': 0.12
+ },
+ {
+ 'name': 'Moderate Growth',
+ 'probability': 0.5,
+ 'growth_model': 'exponential',
+ 'growth_rate': 0.3,
+ 'changes': {},
+ 'assumptions': ['Steady market growth', 'Competition remains stable'],
+ 'cogs_ratio': 0.3,
+ 'opex_growth': 0.15,
+ 'capex_ratio': 0.05,
+ 'discount_rate': 0.10
+ },
+ {
+ 'name': 'Conservative',
+ 'probability': 0.2,
+ 'growth_model': 'linear',
+ 'growth_rate': 0.15,
+ 'changes': {
+ 'operating_expenses': {'multiply': 0.9}
+ },
+ 'assumptions': ['Market headwinds', 'Focus on profitability'],
+ 'cogs_ratio': 0.35,
+ 'opex_growth': 0.05,
+ 'capex_ratio': 0.03,
+ 'discount_rate': 0.08
+ }
+ ]
+
+ print(analyze_financial_scenarios(example_base_case, example_scenarios))
diff --git a/skills/ceo-advisor/scripts/strategy_analyzer.py b/skills/ceo-advisor/scripts/strategy_analyzer.py
new file mode 100644
index 00000000..e871d662
--- /dev/null
+++ b/skills/ceo-advisor/scripts/strategy_analyzer.py
@@ -0,0 +1,609 @@
+#!/usr/bin/env python3
+"""
+Strategic Planning Analyzer - Comprehensive business strategy assessment tool
+"""
+
+import json
+from typing import Dict, List, Tuple
+from datetime import datetime, timedelta
+import math
+
+class StrategyAnalyzer:
+ def __init__(self):
+ self.strategic_pillars = {
+ 'market_position': {
+ 'weight': 0.25,
+ 'factors': ['market_share', 'brand_strength', 'competitive_advantage', 'customer_loyalty']
+ },
+ 'financial_health': {
+ 'weight': 0.25,
+ 'factors': ['revenue_growth', 'profitability', 'cash_flow', 'unit_economics']
+ },
+ 'operational_excellence': {
+ 'weight': 0.20,
+ 'factors': ['efficiency', 'quality', 'scalability', 'innovation']
+ },
+ 'organizational_capability': {
+ 'weight': 0.20,
+ 'factors': ['talent', 'culture', 'leadership', 'agility']
+ },
+ 'growth_potential': {
+ 'weight': 0.10,
+ 'factors': ['market_size', 'expansion_opportunities', 'product_pipeline', 'partnerships']
+ }
+ }
+
+ self.strategic_frameworks = {
+ 'porter_five_forces': [
+ 'competitive_rivalry',
+ 'supplier_power',
+ 'buyer_power',
+ 'threat_of_substitution',
+ 'threat_of_new_entry'
+ ],
+ 'swot': ['strengths', 'weaknesses', 'opportunities', 'threats'],
+ 'bcg_matrix': ['stars', 'cash_cows', 'question_marks', 'dogs'],
+ 'ansoff_matrix': ['market_penetration', 'market_development', 'product_development', 'diversification']
+ }
+
+ def analyze_strategic_position(self, company_data: Dict) -> Dict:
+ """Comprehensive strategic analysis"""
+ results = {
+ 'timestamp': datetime.now().isoformat(),
+ 'company': company_data.get('name', 'Company'),
+ 'strategic_health_score': 0,
+ 'pillar_analysis': {},
+ 'framework_analysis': {},
+ 'strategic_options': [],
+ 'risk_assessment': {},
+ 'recommendations': [],
+ 'roadmap': {}
+ }
+
+ # Analyze strategic pillars
+ total_score = 0
+ for pillar, config in self.strategic_pillars.items():
+ pillar_score = self._analyze_pillar(
+ company_data.get(pillar, {}),
+ config['factors']
+ )
+ weighted_score = pillar_score * config['weight']
+ results['pillar_analysis'][pillar] = {
+ 'score': pillar_score,
+ 'weighted_score': weighted_score,
+ 'level': self._get_level(pillar_score),
+ 'factors': self._get_pillar_details(company_data.get(pillar, {}), config['factors'])
+ }
+ total_score += weighted_score
+
+ results['strategic_health_score'] = round(total_score, 1)
+
+ # Framework analysis
+ results['framework_analysis'] = self._apply_frameworks(company_data)
+
+ # Generate strategic options
+ results['strategic_options'] = self._generate_strategic_options(
+ results['pillar_analysis'],
+ company_data.get('context', {})
+ )
+
+ # Risk assessment
+ results['risk_assessment'] = self._assess_strategic_risks(
+ company_data,
+ results['strategic_options']
+ )
+
+ # Generate roadmap
+ results['roadmap'] = self._create_strategic_roadmap(
+ results['strategic_options'],
+ company_data.get('timeline', 12)
+ )
+
+ # Generate recommendations
+ results['recommendations'] = self._generate_recommendations(results)
+
+ return results
+
+ def _analyze_pillar(self, pillar_data: Dict, factors: List) -> float:
+ """Analyze a strategic pillar"""
+ if not pillar_data:
+ return 50.0
+
+ total_score = 0
+ count = 0
+
+ for factor in factors:
+ if factor in pillar_data:
+ score = pillar_data[factor]
+ total_score += score
+ count += 1
+
+ return (total_score / count) if count > 0 else 50.0
+
+ def _get_pillar_details(self, pillar_data: Dict, factors: List) -> List[Dict]:
+ """Get detailed factor analysis"""
+ details = []
+
+ for factor in factors:
+ score = pillar_data.get(factor, 50)
+ details.append({
+ 'factor': factor.replace('_', ' ').title(),
+ 'score': score,
+ 'status': 'Strong' if score >= 70 else 'Adequate' if score >= 40 else 'Weak'
+ })
+
+ return details
+
+ def _get_level(self, score: float) -> str:
+ """Convert score to level"""
+ if score >= 80:
+ return 'Excellent'
+ elif score >= 70:
+ return 'Strong'
+ elif score >= 50:
+ return 'Adequate'
+ elif score >= 30:
+ return 'Weak'
+ else:
+ return 'Critical'
+
+ def _apply_frameworks(self, company_data: Dict) -> Dict:
+ """Apply strategic frameworks"""
+ frameworks = {}
+
+ # SWOT Analysis
+ swot_data = company_data.get('swot', {})
+ frameworks['swot'] = {
+ 'strengths': swot_data.get('strengths', [
+ 'Strong brand recognition',
+ 'Experienced leadership team',
+ 'Robust technology platform'
+ ]),
+ 'weaknesses': swot_data.get('weaknesses', [
+ 'Limited geographic presence',
+ 'High customer acquisition cost',
+ 'Technical debt'
+ ]),
+ 'opportunities': swot_data.get('opportunities', [
+ 'Growing market demand',
+ 'M&A opportunities',
+ 'New product categories'
+ ]),
+ 'threats': swot_data.get('threats', [
+ 'Increasing competition',
+ 'Regulatory changes',
+ 'Economic uncertainty'
+ ])
+ }
+
+ # Porter's Five Forces
+ forces = company_data.get('competitive_forces', {})
+ frameworks['porter_analysis'] = {
+ 'competitive_rivalry': forces.get('rivalry', 70),
+ 'supplier_power': forces.get('suppliers', 40),
+ 'buyer_power': forces.get('buyers', 60),
+ 'threat_of_substitutes': forces.get('substitutes', 50),
+ 'threat_of_new_entrants': forces.get('new_entrants', 45),
+ 'overall_attractiveness': self._calculate_industry_attractiveness(forces)
+ }
+
+ # BCG Matrix for product portfolio
+ products = company_data.get('products', [])
+ frameworks['portfolio_analysis'] = self._analyze_portfolio(products)
+
+ return frameworks
+
+ def _calculate_industry_attractiveness(self, forces: Dict) -> float:
+ """Calculate industry attractiveness from Porter's forces"""
+ # Lower forces = more attractive industry
+ rivalry = 100 - forces.get('rivalry', 50)
+ supplier = 100 - forces.get('suppliers', 50)
+ buyer = 100 - forces.get('buyers', 50)
+ substitutes = 100 - forces.get('substitutes', 50)
+ new_entrants = 100 - forces.get('new_entrants', 50)
+
+ avg = (rivalry + supplier + buyer + substitutes + new_entrants) / 5
+ return round(avg, 1)
+
+ def _analyze_portfolio(self, products: List) -> Dict:
+ """Analyze product portfolio using BCG matrix"""
+ portfolio = {
+ 'stars': [],
+ 'cash_cows': [],
+ 'question_marks': [],
+ 'dogs': []
+ }
+
+ for product in products:
+ growth = product.get('market_growth', 0)
+ share = product.get('market_share', 0)
+
+ if growth > 10 and share > 50:
+ portfolio['stars'].append(product.get('name', 'Product'))
+ elif growth <= 10 and share > 50:
+ portfolio['cash_cows'].append(product.get('name', 'Product'))
+ elif growth > 10 and share <= 50:
+ portfolio['question_marks'].append(product.get('name', 'Product'))
+ else:
+ portfolio['dogs'].append(product.get('name', 'Product'))
+
+ return portfolio
+
+ def _generate_strategic_options(self, pillar_analysis: Dict, context: Dict) -> List[Dict]:
+ """Generate strategic options based on analysis"""
+ options = []
+
+ # Check market position
+ market_score = pillar_analysis['market_position']['score']
+ if market_score < 60:
+ options.append({
+ 'name': 'Market Leadership Initiative',
+ 'type': 'market_penetration',
+ 'description': 'Aggressive market share capture through competitive pricing and marketing',
+ 'investment': 'High',
+ 'timeframe': '12-18 months',
+ 'expected_impact': 'Increase market share by 10-15%',
+ 'priority': 9
+ })
+
+ # Check financial health
+ financial_score = pillar_analysis['financial_health']['score']
+ if financial_score < 50:
+ options.append({
+ 'name': 'Profitability Turnaround',
+ 'type': 'operational_excellence',
+ 'description': 'Cost reduction and revenue optimization program',
+ 'investment': 'Medium',
+ 'timeframe': '6-9 months',
+ 'expected_impact': 'Improve margins by 5-8%',
+ 'priority': 10
+ })
+
+ # Check growth potential
+ growth_score = pillar_analysis['growth_potential']['score']
+ if growth_score > 70:
+ options.append({
+ 'name': 'Expansion Strategy',
+ 'type': 'market_development',
+ 'description': 'Enter new geographic markets or customer segments',
+ 'investment': 'High',
+ 'timeframe': '18-24 months',
+ 'expected_impact': 'Revenue growth of 30-40%',
+ 'priority': 8
+ })
+
+ # Innovation opportunities
+ if context.get('industry_disruption', False):
+ options.append({
+ 'name': 'Digital Transformation',
+ 'type': 'innovation',
+ 'description': 'Comprehensive digitalization of business processes and customer experience',
+ 'investment': 'Very High',
+ 'timeframe': '24-36 months',
+ 'expected_impact': 'Future-proof business model',
+ 'priority': 9
+ })
+
+ # M&A opportunities
+ if context.get('cash_available', 0) > 100000000:
+ options.append({
+ 'name': 'Strategic Acquisition',
+ 'type': 'acquisition',
+ 'description': 'Acquire complementary businesses or competitors',
+ 'investment': 'Very High',
+ 'timeframe': '6-12 months',
+ 'expected_impact': 'Instant scale and capability',
+ 'priority': 7
+ })
+
+ # Sort by priority
+ options.sort(key=lambda x: x['priority'], reverse=True)
+
+ return options[:5] # Top 5 strategic options
+
+ def _assess_strategic_risks(self, company_data: Dict, strategic_options: List) -> Dict:
+ """Assess strategic risks"""
+ risks = {
+ 'execution_risk': self._calculate_execution_risk(company_data),
+ 'market_risk': self._calculate_market_risk(company_data),
+ 'financial_risk': self._calculate_financial_risk(company_data),
+ 'competitive_risk': self._calculate_competitive_risk(company_data),
+ 'regulatory_risk': company_data.get('regulatory_risk', 30),
+ 'overall_risk': 0,
+ 'mitigation_strategies': []
+ }
+
+ # Calculate overall risk
+ risk_values = [
+ risks['execution_risk'],
+ risks['market_risk'],
+ risks['financial_risk'],
+ risks['competitive_risk'],
+ risks['regulatory_risk']
+ ]
+ risks['overall_risk'] = sum(risk_values) / len(risk_values)
+
+ # Generate mitigation strategies
+ if risks['execution_risk'] > 60:
+ risks['mitigation_strategies'].append({
+ 'risk': 'Execution',
+ 'strategy': 'Strengthen PMO, hire experienced executives, implement OKRs'
+ })
+
+ if risks['market_risk'] > 60:
+ risks['mitigation_strategies'].append({
+ 'risk': 'Market',
+ 'strategy': 'Diversify revenue streams, build strategic partnerships'
+ })
+
+ if risks['financial_risk'] > 60:
+ risks['mitigation_strategies'].append({
+ 'risk': 'Financial',
+ 'strategy': 'Improve cash management, secure credit facilities, optimize working capital'
+ })
+
+ return risks
+
+ def _calculate_execution_risk(self, data: Dict) -> float:
+ """Calculate execution risk"""
+ org_capability = data.get('organizational_capability', {})
+
+ factors = [
+ 100 - org_capability.get('leadership', 50),
+ 100 - org_capability.get('talent', 50),
+ 100 - org_capability.get('agility', 50),
+ data.get('complexity_score', 50)
+ ]
+
+ return sum(factors) / len(factors)
+
+ def _calculate_market_risk(self, data: Dict) -> float:
+ """Calculate market risk"""
+ market = data.get('market_position', {})
+
+ factors = [
+ 100 - market.get('market_share', 50),
+ data.get('market_volatility', 50),
+ data.get('customer_concentration', 50)
+ ]
+
+ return sum(factors) / len(factors)
+
+ def _calculate_financial_risk(self, data: Dict) -> float:
+ """Calculate financial risk"""
+ financial = data.get('financial_health', {})
+
+ factors = [
+ 100 - financial.get('cash_flow', 50),
+ 100 - financial.get('profitability', 50),
+ data.get('debt_ratio', 50),
+ data.get('burn_rate', 50) if 'burn_rate' in data else 30
+ ]
+
+ return sum(factors) / len(factors)
+
+ def _calculate_competitive_risk(self, data: Dict) -> float:
+ """Calculate competitive risk"""
+ forces = data.get('competitive_forces', {})
+
+ return (forces.get('rivalry', 50) + forces.get('new_entrants', 50)) / 2
+
+ def _create_strategic_roadmap(self, options: List, timeline_months: int) -> Dict:
+ """Create implementation roadmap"""
+ roadmap = {
+ 'phases': [],
+ 'milestones': [],
+ 'resource_requirements': {},
+ 'success_metrics': []
+ }
+
+ # Define phases
+ phases = [
+ {
+ 'phase': 'Foundation',
+ 'months': '0-3',
+ 'focus': 'Build capabilities and quick wins',
+ 'initiatives': []
+ },
+ {
+ 'phase': 'Acceleration',
+ 'months': '3-9',
+ 'focus': 'Execute core strategies',
+ 'initiatives': []
+ },
+ {
+ 'phase': 'Scale',
+ 'months': '9-18',
+ 'focus': 'Expand and optimize',
+ 'initiatives': []
+ },
+ {
+ 'phase': 'Transform',
+ 'months': '18+',
+ 'focus': 'Long-term transformation',
+ 'initiatives': []
+ }
+ ]
+
+ # Assign initiatives to phases
+ for i, option in enumerate(options[:4]):
+ if i == 0:
+ phases[0]['initiatives'].append(option['name'])
+ elif i == 1:
+ phases[1]['initiatives'].append(option['name'])
+ elif i == 2:
+ phases[2]['initiatives'].append(option['name'])
+ else:
+ phases[3]['initiatives'].append(option['name'])
+
+ roadmap['phases'] = phases
+
+ # Define key milestones
+ roadmap['milestones'] = [
+ {'month': 3, 'milestone': 'Complete foundation phase', 'success_criteria': 'Core team hired, processes defined'},
+ {'month': 6, 'milestone': 'First major initiative launch', 'success_criteria': 'KPIs showing positive trend'},
+ {'month': 12, 'milestone': 'Strategic review', 'success_criteria': 'ROI demonstrated, strategy validated'},
+ {'month': 18, 'milestone': 'Scale achievement', 'success_criteria': 'Market position improved, financial targets met'}
+ ]
+
+ # Resource requirements
+ roadmap['resource_requirements'] = {
+ 'leadership': 'C-suite alignment and commitment',
+ 'financial': '$X million investment over 18 months',
+ 'human': 'Additional 20-30 FTEs across functions',
+ 'technology': 'Platform upgrades and new tools',
+ 'external': 'Consultants and advisors as needed'
+ }
+
+ # Success metrics
+ roadmap['success_metrics'] = [
+ 'Revenue growth: 25% YoY',
+ 'Market share: +5 percentage points',
+ 'EBITDA margin: +8 percentage points',
+ 'Customer NPS: >70',
+ 'Employee engagement: >80%'
+ ]
+
+ return roadmap
+
+ def _generate_recommendations(self, results: Dict) -> List[str]:
+ """Generate strategic recommendations"""
+ recommendations = []
+
+ # Based on overall score
+ score = results['strategic_health_score']
+ if score < 40:
+ recommendations.append('🚨 URGENT: Immediate turnaround required - consider bringing in crisis management team')
+ recommendations.append('Focus on cash preservation and core business stabilization')
+ elif score < 60:
+ recommendations.append('⚠️ Strategic repositioning needed - prioritize 2-3 key initiatives')
+ recommendations.append('Strengthen weak pillars before pursuing growth')
+ elif score < 80:
+ recommendations.append('✓ Solid position - focus on selective improvements and growth')
+ recommendations.append('Invest in innovation and market expansion')
+ else:
+ recommendations.append('⭐ Excellent position - maintain momentum and explore bold moves')
+ recommendations.append('Consider industry disruption or category creation')
+
+ # Based on specific weaknesses
+ for pillar, analysis in results['pillar_analysis'].items():
+ if analysis['score'] < 50:
+ if pillar == 'market_position':
+ recommendations.append(f'Strengthen {pillar}: Launch competitive differentiation program')
+ elif pillar == 'financial_health':
+ recommendations.append(f'Improve {pillar}: Implement profitability improvement plan')
+ elif pillar == 'organizational_capability':
+ recommendations.append(f'Build {pillar}: Invest in talent and culture transformation')
+
+ # Based on opportunities
+ if results['framework_analysis']['porter_analysis']['overall_attractiveness'] > 70:
+ recommendations.append('Industry is attractive - consider aggressive expansion')
+
+ # Risk-based recommendations
+ if results['risk_assessment']['overall_risk'] > 60:
+ recommendations.append('High risk profile - implement comprehensive risk management')
+
+ return recommendations
+
+def analyze_strategy(company_data: Dict) -> str:
+ """Main function to analyze strategy"""
+ analyzer = StrategyAnalyzer()
+ results = analyzer.analyze_strategic_position(company_data)
+
+ # Format output
+ output = [
+ f"=== Strategic Analysis Report ===",
+ f"Company: {results['company']}",
+ f"Date: {results['timestamp'][:10]}",
+ f"",
+ f"STRATEGIC HEALTH SCORE: {results['strategic_health_score']}/100",
+ f"",
+ "Strategic Pillars:"
+ ]
+
+ for pillar, analysis in results['pillar_analysis'].items():
+ output.append(f" {pillar.replace('_', ' ').title()}: {analysis['score']:.1f} ({analysis['level']})")
+ for factor in analysis['factors'][:2]: # Show top 2 factors
+ output.append(f" • {factor['factor']}: {factor['status']}")
+
+ output.extend([
+ f"",
+ "Strategic Options:"
+ ])
+
+ for i, option in enumerate(results['strategic_options'][:3], 1):
+ output.append(f"\n{i}. {option['name']} (Priority: {option['priority']}/10)")
+ output.append(f" Type: {option['type']}")
+ output.append(f" Investment: {option['investment']}")
+ output.append(f" Timeframe: {option['timeframe']}")
+ output.append(f" Impact: {option['expected_impact']}")
+
+ output.extend([
+ f"",
+ f"Risk Assessment:",
+ f" Overall Risk: {results['risk_assessment']['overall_risk']:.1f}%",
+ f" Execution Risk: {results['risk_assessment']['execution_risk']:.1f}%",
+ f" Market Risk: {results['risk_assessment']['market_risk']:.1f}%",
+ f" Financial Risk: {results['risk_assessment']['financial_risk']:.1f}%",
+ f"",
+ "Strategic Roadmap:"
+ ])
+
+ for phase in results['roadmap']['phases'][:3]:
+ output.append(f" {phase['phase']} ({phase['months']}): {phase['focus']}")
+ for initiative in phase['initiatives']:
+ output.append(f" • {initiative}")
+
+ output.extend([
+ f"",
+ "Key Recommendations:"
+ ])
+
+ for rec in results['recommendations'][:5]:
+ output.append(f" • {rec}")
+
+ return '\n'.join(output)
+
+if __name__ == "__main__":
+ # Example usage
+ example_company = {
+ 'name': 'TechCorp Inc.',
+ 'market_position': {
+ 'market_share': 35,
+ 'brand_strength': 65,
+ 'competitive_advantage': 70,
+ 'customer_loyalty': 60
+ },
+ 'financial_health': {
+ 'revenue_growth': 45,
+ 'profitability': 40,
+ 'cash_flow': 55,
+ 'unit_economics': 60
+ },
+ 'organizational_capability': {
+ 'talent': 70,
+ 'culture': 65,
+ 'leadership': 75,
+ 'agility': 60
+ },
+ 'growth_potential': {
+ 'market_size': 80,
+ 'expansion_opportunities': 70,
+ 'product_pipeline': 60,
+ 'partnerships': 55
+ },
+ 'competitive_forces': {
+ 'rivalry': 70,
+ 'suppliers': 40,
+ 'buyers': 60,
+ 'substitutes': 50,
+ 'new_entrants': 45
+ },
+ 'context': {
+ 'industry_disruption': True,
+ 'cash_available': 150000000
+ },
+ 'timeline': 18
+ }
+
+ print(analyze_strategy(example_company))
diff --git a/skills/cfo-advisor/SKILL.md b/skills/cfo-advisor/SKILL.md
new file mode 100644
index 00000000..be2397ef
--- /dev/null
+++ b/skills/cfo-advisor/SKILL.md
@@ -0,0 +1,140 @@
+---
+name: "cfo-advisor"
+description: "Financial leadership for startups and scaling companies. Financial modeling, unit economics, fundraising strategy, cash management, and board financial packages. Use when building financial models, analyzing unit economics, planning fundraising, managing cash runway, preparing board materials, or when user mentions CFO, burn rate, runway, fundraising, unit economics, LTV, CAC, term sheets, or financial strategy."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: cfo-leadership
+ updated: 2026-03-05
+ python-tools: burn_rate_calculator.py, unit_economics_analyzer.py, fundraising_model.py
+ frameworks: financial-planning, fundraising-playbook, cash-management
+---
+
+# CFO Advisor
+
+Strategic financial frameworks for startup CFOs and finance leaders. Numbers-driven, decisions-focused.
+
+This is **not** a financial analyst skill. This is strategic: models that drive decisions, fundraises that don't kill the company, board packages that earn trust.
+
+## Keywords
+CFO, chief financial officer, burn rate, runway, unit economics, LTV, CAC, fundraising, Series A, Series B, term sheet, cap table, dilution, financial model, cash flow, board financials, FP&A, SaaS metrics, ARR, MRR, net dollar retention, gross margin, scenario planning, cash management, treasury, working capital, burn multiple, rule of 40
+
+## Quick Start
+
+```bash
+# Burn rate & runway scenarios (base/bull/bear)
+python scripts/burn_rate_calculator.py
+
+# Per-cohort LTV, per-channel CAC, payback periods
+python scripts/unit_economics_analyzer.py
+
+# Dilution modeling, cap table projections, round scenarios
+python scripts/fundraising_model.py
+```
+
+## Key Questions (ask these first)
+
+- **What's your burn multiple?** (Net burn ÷ Net new ARR. > 2x is a problem.)
+- **If fundraising takes 6 months instead of 3, do you survive?** (If not, you're already behind.)
+- **Show me unit economics per cohort, not blended.** (Blended hides deterioration.)
+- **What's your NDR?** (> 100% means you grow without signing a single new customer.)
+- **What are your decision triggers?** (At what runway do you start cutting? Define now, not in a crisis.)
+
+## Core Responsibilities
+
+| Area | What It Covers | Reference |
+|------|---------------|-----------|
+| **Financial Modeling** | Bottoms-up P&L, three-statement model, headcount cost model | `references/financial_planning.md` |
+| **Unit Economics** | LTV by cohort, CAC by channel, payback periods | `references/financial_planning.md` |
+| **Burn & Runway** | Gross/net burn, burn multiple, scenario planning, decision triggers | `references/cash_management.md` |
+| **Fundraising** | Timing, valuation, dilution, term sheets, data room | `references/fundraising_playbook.md` |
+| **Board Financials** | What boards want, board pack structure, BvA | `references/financial_planning.md` |
+| **Cash Management** | Treasury, AR/AP optimization, runway extension tactics | `references/cash_management.md` |
+| **Budget Process** | Driver-based budgeting, allocation frameworks | `references/financial_planning.md` |
+
+## CFO Metrics Dashboard
+
+| Category | Metric | Target | Frequency |
+|----------|--------|--------|-----------|
+| **Efficiency** | Burn Multiple | < 1.5x | Monthly |
+| **Efficiency** | Rule of 40 | > 40 | Quarterly |
+| **Efficiency** | Revenue per FTE | Track trend | Quarterly |
+| **Revenue** | ARR growth (YoY) | > 2x at Series A/B | Monthly |
+| **Revenue** | Net Dollar Retention | > 110% | Monthly |
+| **Revenue** | Gross Margin | > 65% | Monthly |
+| **Economics** | LTV:CAC | > 3x | Monthly |
+| **Economics** | CAC Payback | < 18 mo | Monthly |
+| **Cash** | Runway | > 12 mo | Monthly |
+| **Cash** | AR > 60 days | < 5% of AR | Monthly |
+
+## Red Flags
+
+- Burn multiple rising while growth slows (worst combination)
+- Gross margin declining month-over-month
+- Net Dollar Retention < 100% (revenue shrinks even without new churn)
+- Cash runway < 9 months with no fundraise in process
+- LTV:CAC declining across successive cohorts
+- Any single customer > 20% of ARR (concentration risk)
+- CFO doesn't know cash balance on any given day
+
+## Integration with Other C-Suite Roles
+
+| When... | CFO works with... | To... |
+|---------|-------------------|-------|
+| Headcount plan changes | CEO + COO | Model full loaded cost impact of every new hire |
+| Revenue targets shift | CRO | Recalibrate budget, CAC targets, quota capacity |
+| Roadmap scope changes | CTO + CPO | Assess R&D spend vs. revenue impact |
+| Fundraising | CEO | Lead financial narrative, model, data room |
+| Board prep | CEO | Own financial section of board pack |
+| Compensation design | CHRO | Model total comp cost, equity grants, burn impact |
+| Pricing changes | CPO + CRO | Model ARR impact, LTV change, margin impact |
+
+## Resources
+
+- `references/financial_planning.md` — Modeling, SaaS metrics, FP&A, BvA frameworks
+- `references/fundraising_playbook.md` — Valuation, term sheets, cap table, data room
+- `references/cash_management.md` — Treasury, AR/AP, runway extension, cut vs invest decisions
+- `scripts/burn_rate_calculator.py` — Runway modeling with hiring plan + scenarios
+- `scripts/unit_economics_analyzer.py` — Per-cohort LTV, per-channel CAC
+- `scripts/fundraising_model.py` — Dilution, cap table, multi-round projections
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Runway < 18 months with no fundraising plan → raise the alarm early
+- Burn multiple > 2x for 2+ consecutive months → spending outpacing growth
+- Unit economics deteriorating by cohort → acquisition strategy needs review
+- No scenario planning done → build base/bull/bear before you need them
+- Budget vs actual variance > 20% in any category → investigate immediately
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "How much runway do we have?" | Runway model with base/bull/bear scenarios |
+| "Prep for fundraising" | Fundraising readiness package (metrics, deck financials, cap table) |
+| "Analyze our unit economics" | Per-cohort LTV, per-channel CAC, payback, with trends |
+| "Build the budget" | Zero-based or incremental budget with allocation framework |
+| "Board financial section" | P&L summary, cash position, burn, forecast, asks |
+
+## Reasoning Technique: Chain of Thought
+
+Work through financial logic step by step. Show all math. Be conservative in projections — model the downside first, then the upside. Never round in your favor.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/cfo-advisor/_meta.json b/skills/cfo-advisor/_meta.json
new file mode 100644
index 00000000..7585b184
--- /dev/null
+++ b/skills/cfo-advisor/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "cfo-advisor",
+ "displayName": "Cfo Advisor",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773171102209,
+ "commit": "https://github.com/openclaw/skills/commit/fab02395082e515f77dc7d5f467d57b634ddb984"
+ },
+ "history": [
+ {
+ "version": "2.0.0",
+ "publishedAt": 1772746538086,
+ "commit": "https://github.com/openclaw/skills/commit/216a11e7c59af97fb01e0f89bfea1f962e348f01"
+ }
+ ]
+}
diff --git a/skills/cfo-advisor/references/cash_management.md b/skills/cfo-advisor/references/cash_management.md
new file mode 100644
index 00000000..be3e69f8
--- /dev/null
+++ b/skills/cfo-advisor/references/cash_management.md
@@ -0,0 +1,374 @@
+# Cash Management Reference
+
+Cash is the oxygen of a startup. You can be unprofitable for years. You cannot be out of cash for a day.
+
+---
+
+## 1. Cash Flow Management
+
+### The Cash Equation
+
+```
+Ending Cash = Beginning Cash
+ + Cash collected from customers
+ - Cash paid to employees
+ - Cash paid to vendors
+ - Cash paid for infrastructure
+ - Debt service
+ +/- Financing activities
+
+Note: This is NOT the P&L. Revenue recognition ≠ cash collected.
+```
+
+### Where Cash Hides (and Leaks)
+
+**Cash sources you might be under-using:**
+- Deferred revenue (annual billing locks in cash 12 months early)
+- Customer deposits on enterprise contracts
+- Vendor payment terms (Net 60 instead of Net 30 = free float)
+- AWS/GCP startup credits (often $25K–$100K available, widely unused)
+- Revenue-based financing on predictable MRR
+- Venture debt (non-dilutive, available post-Series A)
+
+**Cash drains that sneak up on you:**
+- Annual software licenses paid in Q1 (budget for the lump sum)
+- Event sponsorships (often 6-12 months in advance)
+- Recruiting fees (15-25% of first-year salary, due on hire)
+- Legal fees (data room prep, fundraise close = $50K–$200K surprise)
+- Late-paying enterprise customers (Net 60 in contract, pays Net 90 in practice)
+
+### Cash Flow vs P&L: The Gap
+
+**Scenario: $1M enterprise deal signed December 31**
+
+```
+P&L impact (accrual):
+ December revenue: $83K (1/12 of annual)
+
+Cash impact:
+ If billed annually upfront: +$1,000K in December (GREAT)
+ If billed quarterly: +$250K in December (good)
+ If billed monthly: +$83K in December (fine)
+ If Net 60 terms: +$0 in December, +$83K in February (cash drag)
+```
+
+**The CFO's job:** Maximize the timing difference between cash in and cash out.
+- Collect from customers as early as possible (annual upfront, early payment discounts)
+- Pay vendors as late as possible (maximize payment terms)
+- Never confuse deferred revenue (a liability) with actual cash (it is cash — just count it right)
+
+---
+
+## 2. Treasury and Banking Strategy
+
+### Account Structure
+
+```
+Operating Account (primary bank):
+ Balance: 3-6 months of operating expenses
+ Purpose: Payroll, vendor payments, day-to-day ops
+ Product: Business checking or high-yield business savings
+ Bank: Chase, SVB successor (First Citizens), Mercury, Brex
+
+Reserve Account (secondary or same bank):
+ Balance: Everything above operating float
+ Purpose: Reserve; move to operating as needed
+ Product: Money market fund or T-Bill ladder
+ Target yield (2024-2025): 4.5%–5.2%
+ Products: Vanguard VMFXX, Fidelity SPAXX, or direct T-Bills via TreasuryDirect
+
+Emergency Account (separate bank):
+ Balance: 1-2 months expenses
+ Purpose: If primary bank has issues (SVB taught this lesson)
+ Product: Business savings
+```
+
+**FDIC coverage:** $250K per depositor per institution. For balances above $250K at a single bank, either:
+- Use CDARS/ICS (bank sweeps into multiple FDIC-insured accounts automatically)
+- Spread across multiple banks
+- Move excess to T-Bills (backed by US government, not FDIC, but safer)
+
+**After SVB (March 2023):** Every CFO should have at least 2 banking relationships. If one bank fails or freezes, you can make payroll.
+
+### Yield on Cash
+
+At $3M cash, the difference between 0% (checking) and 5% (T-Bills) is $150K/year.
+That's a month of runway for a $150K/month burn company. **Get yield on reserves.**
+
+```
+Monthly yield on $3M at 5%: ~$12,500
+Annual: ~$150,000
+This is not optional. Set it up once and automate.
+```
+
+---
+
+## 3. AR/AP Optimization
+
+### Accounts Receivable: Get Paid Faster
+
+**Billing model impact on cash:**
+```
+ Annual Upfront Quarterly Monthly Net 30 Monthly
+Cash Day 1: 100% of ACV 25% of ACV 8.3% 0%
+Cash Month 2: 0% (done) 0% 8.3% 8.3%
+12-month total: 100% 100% 100% 100%
+
+For $100K ACV customer, Year 1 cash:
+ Annual upfront: $100K immediately
+ Monthly Net 30: $8.3K × 11 months = $91.7K (1 month lag)
+ Cash benefit: $100K vs $91.7K = $8.3K benefit + no collection risk
+```
+
+**Push for annual billing. Make it easy with a discount:**
+```
+"Pay annually and get 2 months free (16% discount)"
+Most SMB customers will take this.
+Enterprise: use MSA structure with annual invoicing, not month-to-month.
+```
+
+**AR Aging Policy:**
+```
+> 0-30 days: Current. No action.
+> 30-60 days: Friendly reminder from AR team.
+> 60-90 days: Escalate to Customer Success.
+> 90 days: CFO or CEO-level outreach. Consider collections.
+> 120 days: Reserve for bad debt. Legal/collections.
+
+Reserve policy: 50% of 90-120 day AR, 100% of > 120 days
+```
+
+**What slows down collections:**
+- Wrong contact (billing contact vs. user) — get finance contact during onboarding
+- Enterprise PO required — know this upfront, not when invoice is due
+- Credit holds or budget freeze — your CSM should surface these early
+- Invoice errors — every wrong invoice extends payment by 30-60 days
+
+### Accounts Payable: Pay Slower
+
+**Standard terms by vendor type:**
+```
+SaaS tools: Net 30 default. Push for Net 45 or Net 60 at scale.
+Cloud providers: Pay as you go. Apply for credits first.
+Professional services (agencies, lawyers): Net 30 minimum. Get Net 45 where possible.
+Rent/office: Whatever the lease says. Negotiate quarterly payments if you can.
+Payroll: Pay on time. Never delay payroll. Ever.
+```
+
+**Early payment discount trap:**
+```
+"2/10 Net 30" means: 2% discount if you pay in 10 days, else pay in 30.
+Annual cost of NOT taking this: 2% × (365/(30-10)) = ~36% APY
+ALWAYS take early payment discounts > 2%.
+Never take discounts < 1%.
+```
+
+**AP workflow:**
+1. All invoices → finance inbox (not individual employees)
+2. Approval required above threshold ($500 for startups)
+3. Pay at end of terms, not when invoice arrives
+4. Batch payments weekly (not daily) to reduce processing overhead
+
+---
+
+## 4. Runway Extension Tactics
+
+Use these when you need to extend runway without raising. Ranked by speed and impact.
+
+### Tier 1: Fast Cash (Days)
+
+**Annual billing campaign:**
+```
+Target: Existing monthly customers
+Offer: 2 months free (16% discount) or 1 month free (8% discount) for annual upfront
+Process: CSM-led email campaign to all monthly customers
+Impact: $X MRR × 12 × conversion rate = immediate cash injection
+Timeline: 2-4 weeks
+No dilution. No debt. High impact.
+```
+
+**Prepayment incentive for pipeline:**
+```
+For deals in late stage, offer annual upfront pricing with 10-15% discount.
+Close rate may increase. Cash timing dramatically improves.
+```
+
+### Tier 2: Cost Control (2-4 Weeks)
+
+**Hiring freeze:**
+```
+Every unfilled role = salary × 1.25 per month.
+For a 30-person company, 3 open roles at $150K average:
+ Monthly savings: 3 × $150K × 1.25 / 12 = $47K/month
+ Over 6 months: $280K
+Impact: Immediate. No blood.
+```
+
+**Software audit:**
+```
+Pull all credit card charges and ACH debits.
+Cancel any subscription not used in 30 days.
+Typical savings: $3K-$15K/month at Series A stage.
+Tools: Vendr, Spendesk, or just a spreadsheet of recurring charges.
+```
+
+**Cloud cost optimization:**
+```
+Right-size instances (dev/staging don't need prod-scale)
+Reserve instances (1-year reserved = 30-40% savings vs on-demand)
+Delete unused resources (load balancers, IPs, old snapshots)
+Typical savings: 20-35% of current cloud bill
+```
+
+### Tier 3: Vendor Renegotiation (2-6 Weeks)
+
+**Payment term extension:**
+```
+Ask key vendors for Net 60 instead of Net 30.
+$500K in AP × 30 days = $500K × (30/365) = ~$41K cash float improvement
+Won't always work, but vendors often say yes to good customers.
+```
+
+**Renewal timing:**
+```
+Push annual renewals to later in the year.
+Preserve cash for Q1 (typically heaviest sales hiring quarter).
+```
+
+**Vendor credits:**
+```
+AWS: AWS Activate (up to $100K for qualified startups)
+GCP: Google for Startups (up to $200K)
+Azure: Microsoft for Startups (up to $150K)
+Stripe: Revenue share programs
+Hubspot: Startup pricing (90% off)
+```
+
+### Tier 4: Financing (Weeks to Months)
+
+**Revenue-based financing:**
+```
+Providers: Clearco, Capchase, Pipe, Arc
+Structure: Advance 3-6 months of MRR. Repay with % of monthly revenue.
+Cost: Typically 6-12% annualized.
+Speed: 1-2 weeks to close.
+When to use: Bridge to next ARR milestone before raising equity.
+When NOT to use: When burn rate is structural (will consume the advance fast).
+```
+
+**Venture debt:**
+```
+Providers: SVB (now First Citizens), Western Technology Investment, Hercules, TriplePoint
+Structure: Term loan, typically 3-6x monthly gross burn
+Interest: Prime + 2-4% + warrants
+When available: Post-Series A, when revenue is predictable
+Typical timing: Add alongside an equity round (don't raise debt when you need equity)
+Impact: Extends runway 3-6 months without dilution
+When NOT to use: If you might trip financial covenants (minimum cash, revenue)
+```
+
+**Convertible bridge:**
+```
+Existing investors write bridge note: $500K-$2M at favorable terms.
+Structure: Converts at discount (10-20%) or cap into next equity round.
+When to use: You're 60-90 days from closing an equity round and need cash to get there.
+When NOT to use: As a long-term strategy. Bridge-to-bridge is a death spiral.
+```
+
+### Tier 5: Structural Cost Reduction (Weeks + Impact on Morale)
+
+**Salary deferrals (founders first):**
+```
+Founders take 20-30% salary reduction, accrued for future repayment.
+Signals commitment to team and investors.
+Only ask employees to follow if founders go first.
+Always pay market rate to key non-founder employees — you can't afford to lose them.
+```
+
+**Reduction in force (RIF):**
+```
+Threshold: If burn multiple > 3x and growth < 20% YoY, a RIF is likely necessary.
+Sizing: Model to achieve at least 12 months runway without fundraising.
+Rule: Don't do a RIF twice. Size it right the first time.
+ Two small RIFs destroy morale worse than one decisive one.
+Process: Legal counsel required. WARN Act (60-day notice) if > 100 employees.
+Focus cuts: G&A and underperforming sales roles first. Protect engineering and key revenue.
+```
+
+---
+
+## 5. When to Cut vs When to Invest
+
+### The Framework
+
+**Cut when:**
+- Burn multiple > 2x and growth is decelerating
+- Runway < 9 months with no fundraise imminent
+- LTV:CAC declining for 3+ consecutive months
+- Any spend category with no measurable return in 90 days
+- Headcount in functions not directly tied to near-term revenue or product-market fit
+
+**Invest when:**
+- Magic number > 1 (every dollar in S&M returns > $1 in gross profit)
+- LTV:CAC > 3x in a specific channel (pour money in)
+- Gross margin > 70% (unit economics are healthy; growth is the constraint)
+- Cohort data improving (retention getting better → LTV going up → invest in growth)
+- CAC payback < 12 months (you get your money back fast enough to keep reinvesting)
+
+### The False Economy Trap
+
+**Don't cut:**
+- Top-of-funnel demand gen that generates qualified pipeline (if CAC payback is < 12 months, this is your best investment)
+- Engineering capacity on core product (technical debt compounds and slows you down permanently)
+- Key account managers on your largest customers (churn from top customers is catastrophic)
+
+**Cut these first:**
+- Conference sponsorships with no measurable pipeline
+- Tools and subscriptions with < 5 users or < 30% utilization
+- Agency spend that could be done in-house
+- Roadmap items that aren't tied to retention or expansion revenue
+- Any G&A spend that isn't legally required
+
+### Decision Triggers (Pre-Define These)
+
+Don't make these decisions in a crisis. Define the triggers now:
+
+```
+At 12 months runway: Review all discretionary spend. Start fundraise process.
+At 9 months runway: Implement hiring freeze. Fundraise is mandatory.
+At 6 months runway: Cut non-essential spend 20%. If no fundraise term sheet, run RIF model.
+At 4 months runway: Execute RIF. Explore all financing options. Notify board.
+At 3 months runway: Emergency plan only. All options on table (bridge, strategic, wind down).
+```
+
+---
+
+## Key Formulas
+
+```python
+# Net burn
+net_burn = gross_burn - revenue_collected
+
+# Runway (months)
+runway_months = cash_balance / net_burn
+
+# Cash conversion cycle
+ccc = days_sales_outstanding + days_inventory_held - days_payable_outstanding
+# Lower CCC = better cash efficiency
+
+# Days Sales Outstanding (DSO)
+dso = (accounts_receivable / revenue) * 30 # monthly revenue
+
+# Days Payable Outstanding (DPO)
+dpo = (accounts_payable / cogs) * 30 # target: maximize this
+
+# Working capital
+working_capital = current_assets - current_liabilities
+
+# Quick ratio (liquidity)
+quick_ratio_liquidity = (cash + ar) / current_liabilities
+# Target: > 1.5 (you can pay short-term obligations without selling assets)
+
+# Free cash flow
+fcf = operating_cash_flow - capex
+```
diff --git a/skills/cfo-advisor/references/financial_planning.md b/skills/cfo-advisor/references/financial_planning.md
new file mode 100644
index 00000000..af04db48
--- /dev/null
+++ b/skills/cfo-advisor/references/financial_planning.md
@@ -0,0 +1,500 @@
+# Financial Planning Reference
+
+Startup financial modeling frameworks. Build models that drive decisions, not models that impress investors.
+
+---
+
+## 1. Startup Financial Modeling
+
+### Bottoms-Up vs Top-Down
+
+**Top-down model (don't use for operating):**
+```
+TAM = $10B
+SOM = 1% = $100M
+Revenue = $100M in year 5
+```
+This is marketing. You cannot manage a company against these numbers.
+
+**Bottoms-up model (use this):**
+```
+Year 1 Revenue Build:
+ Sales headcount: 3 AEs by Q1, +2 in Q2, +3 in Q4
+ Ramp curve: Month 1-3 = 25%, Month 4-6 = 75%, Month 7+ = 100%
+ Quota per ramped AE: $600K ARR
+ Effective quota (weighted for ramp): $1.2M ARR in Year 1
+ Win rate: 25%
+ Average deal: $48K ACV
+ Pipeline needed: $1.2M / 25% = $4.8M ARR pipeline
+ Required meetings to create that pipeline: $4.8M / (conversion 20%) / ($48K ACV × 0.5 to meeting) = ~200 meetings
+```
+
+Now you have something actionable. You know how many SDR calls, how many marketing leads, what conversion rate you need to hold. Every assumption is visible and challengeable.
+
+### Building the Operating Model
+
+#### Revenue Engine
+
+**New ARR Model (SaaS):**
+```
+Month N New ARR:
+ = Quota-carrying reps (fully ramped equivalent)
+ × Attainment rate (typically 70-80% of quota)
+ × Average deal size
+ + PLG / self-serve (if applicable)
+
+Quota-carrying reps (ramped equivalent):
+ = Sum(each rep × their ramp factor)
+
+Ramp schedule:
+ Month 1-2: 0% (onboarding)
+ Month 3: 25%
+ Month 4-6: 50%
+ Month 7-9: 75%
+ Month 10+: 100%
+```
+
+**ARR Bridge (most important recurring visual):**
+```
+Beginning ARR
+ + New ARR (new logos)
+ + Expansion ARR (upsells, seat growth)
+ - Churned ARR (cancellations)
+ - Contraction ARR (downgrades)
+= Ending ARR
+
+Net ARR Added = New + Expansion - Churn - Contraction
+
+Net Dollar Retention (NDR):
+ = (Beginning ARR + Expansion - Churn - Contraction) / Beginning ARR × 100
+ Target: > 110% for growth-stage SaaS
+ World-class: > 130% (Snowflake, Twilio-tier)
+```
+
+**MRR and ARR Relationship:**
+```
+ARR = MRR × 12 (simple, always use this)
+Never mix monthly and annual contracts in MRR without normalization.
+Annual contract booked = ACV / 12 = monthly contribution to ARR
+Multi-year contracts: book each year at annual value (not multi-year total)
+```
+
+#### Headcount Model
+
+Headcount is usually 60-80% of total costs. Model it carefully.
+
+```
+For each role:
+ - Start date
+ - Department
+ - Annual salary (from salary bands)
+ - Loaded cost (salary × 1.25-1.45 depending on benefits + recruiting method)
+ - Productive from (ramp period)
+ - Impact on revenue (for revenue-generating roles)
+
+Total headcount cost = Σ (each FTE × loaded cost × months active / 12)
+```
+
+**Department headcount ratios (Series A benchmarks):**
+```
+Sales (S&M): 20-30% of headcount
+Engineering/Product (R&D): 40-50% of headcount
+Customer Success: 15-20% of headcount
+G&A: 10-15% of headcount
+```
+
+#### COGS Model
+
+Gross margin is the most important long-term indicator of business quality.
+
+**COGS for SaaS:**
+```
+1. Hosting / Infrastructure (AWS, GCP, Azure)
+ - Scale with customer count or usage
+ - Should be 5-15% of ARR for mature SaaS
+ - If > 20%: infrastructure optimization needed
+
+2. Customer Success headcount
+ - Ratio: 1 CSM per $1M-$3M ARR (varies by segment)
+ - SMB: 1 CSM per $500K ARR (high-touch required)
+ - Enterprise: 1 CSM per $2-5M ARR (strategic accounts)
+
+3. Third-party licensing / APIs
+ - Per-customer or usage-based pass-through costs
+ - Critical to model at scale (margin killer if not tracked)
+
+4. Payment processing
+ - 2.2-2.9% of revenue for Stripe/Braintree
+ - Can negotiate to 1.8-2.2% at scale (> $5M ARR)
+```
+
+**Gross Margin targets:**
+```
+SaaS: > 65% acceptable, > 75% good, > 80% exceptional
+Marketplace: 50-70%
+Hardware + software: 40-60%
+Services + software: 30-50%
+```
+
+**If gross margin < 65%:**
+- Infrastructure cost optimization (rightsizing, reserved instances)
+- CS headcount review (automation, pooled CSMs)
+- Pricing model review (usage-based pricing if cost is usage-driven)
+- Third-party cost renegotiation
+
+#### Opex Model
+
+```
+Sales & Marketing:
+ - AE/SDR/SE salaries + OTE (on-target earnings)
+ - Marketing programs (demand gen budget)
+ - Tools and technology (CRM, SEO, ads platforms)
+ - Events and travel
+ - Benchmark: 40-60% of revenue at growth stage, targeting < 30% at scale
+
+Research & Development:
+ - Engineering salaries
+ - Product management
+ - Design
+ - Technical infrastructure for development
+ - Benchmark: 20-35% of revenue
+
+General & Administrative:
+ - Finance, legal, HR, admin
+ - Office costs
+ - SaaS tools / software licenses
+ - D&O insurance
+ - Benchmark: 8-15% (target < 10% at scale)
+```
+
+### Financial Model Do's and Don'ts
+
+| Do | Don't |
+|----|-------|
+| Build assumptions tab with all inputs | Hardcode numbers in formulas |
+| Model monthly (not quarterly) at early stage | Use annual model for first 3 years |
+| Start with headcount plan, build costs from it | Guess at expense line items |
+| Show model to actual customers or users | Show model to investors before internal stress-test |
+| Version your model | Overwrite old versions |
+| Reconcile cash flow to P&L monthly | Trust P&L without cash flow model |
+| Include a sensitivity table | Present single-scenario forecast |
+
+---
+
+## 2. Three-Statement Model for Startups
+
+### Why All Three Matter
+
+The P&L tells you if you're profitable. The cash flow statement tells you if you're alive. The balance sheet tells you if you're solvent.
+
+Startups that only track P&L miss the gap between revenue recognition and cash collection.
+
+### P&L Structure
+
+```
+ Q1 Q2 Q3 Q4 FY
+Revenue
+ Subscription ARR $400K $520K $680K $840K $2,440K
+ Professional Svcs $40K $50K $60K $65K $215K
+Total Revenue $440K $570K $740K $905K $2,655K
+
+COGS
+ Infrastructure $35K $42K $52K $62K $191K
+ CS Headcount $75K $75K $100K $100K $350K
+ 3rd Party Licensing $15K $18K $22K $28K $83K
+Total COGS $125K $135K $174K $190K $624K
+
+Gross Profit $315K $435K $566K $715K $2,031K
+Gross Margin 71.6% 76.3% 76.5% 79.0% 76.5%
+
+Operating Expenses
+ Sales & Marketing $380K $420K $480K $520K $1,800K
+ Research & Dev $320K $340K $380K $400K $1,440K
+ General & Admin $120K $130K $140K $150K $540K
+Total Opex $820K $890K $1000K $1070K $3,780K
+
+EBITDA ($505K) ($455K) ($434K) ($355K) ($1,749K)
+EBITDA Margin (114.8%)(79.8%) (58.6%) (39.2%) (65.9%)
+```
+
+### Cash Flow Statement
+
+```
+ Q1 Q2 Q3 Q4
+Operating Activities
+ Net Income ($510K) ($460K) ($440K) ($360K)
+ Add: D&A $8K $8K $8K $10K
+ Working Capital Changes:
+ AR increase ($45K) ($50K) ($60K) ($55K)
+ AP increase $20K $15K $20K $15K
+ Deferred Rev change $80K $60K $80K $90K
+Operating Cash Flow ($447K) ($427K) ($392K) ($300K)
+
+Investing Activities
+ Capex ($15K) ($8K) ($10K) ($12K)
+Free Cash Flow ($462K) ($435K) ($402K) ($312K)
+
+Financing Activities
+ None $0 $0 $0 $0
+
+Net Change in Cash ($462K) ($435K) ($402K) ($312K)
+
+Beginning Cash $3,500K $3,038K $2,603K $2,201K
+Ending Cash $3,038K $2,603K $2,201K $1,889K
+Runway (months) 13.1 12.1 10.9 10.1
+```
+
+**Key insight from this model:**
+The deferred revenue offset (customers paying annually upfront) is reducing cash burn by ~$80-90K/quarter versus a pure monthly billing model. This is the CFO's lever — push for annual billing.
+
+### Balance Sheet: The Startup Version
+
+At early stage, track these specifically:
+
+```
+Assets:
+ Cash: Your lifeline. Monitor daily.
+ Accounts Receivable: What customers owe you. Age it monthly.
+ Prepaid Expenses: Software licenses, insurance paid upfront.
+
+Liabilities:
+ Accounts Payable: What you owe vendors. Maximize terms.
+ Accrued Liabilities: Salaries owed, commissions earned but not paid.
+ Deferred Revenue: Customer prepayments. Liability until service delivered, but cash is yours.
+ Debt/Convertible Notes: Face value + interest accrual.
+
+Equity:
+ Common Stock: Founder shares
+ Preferred Stock: Investor shares
+ APIC: Additional paid-in capital
+ Accumulated Deficit: Your running losses (expected for startups)
+```
+
+---
+
+## 3. SaaS Metrics That Matter
+
+### The Hierarchy of SaaS Metrics
+
+```
+Tier 1 (existential): ARR, Runway, Net Dollar Retention
+Tier 2 (strategic): Gross Margin, Burn Multiple, LTV:CAC
+Tier 3 (operational): CAC Payback, Churn Rate, ACV
+Tier 4 (diagnostic): Logo Churn vs Revenue Churn, Expansion Rate, NPS
+```
+
+Never report Tier 4 metrics to your board if Tier 1 metrics are off-track.
+
+### Core Metric Definitions
+
+**ARR (Annual Recurring Revenue):**
+```
+ARR = Sum of all active annual contract values (normalized to annual)
+What it is NOT: bookings, billings, or TCV
+When to use MRR: Companies with mostly monthly contracts
+When to use ARR: Companies with majority annual contracts
+```
+
+**Net Dollar Retention (NDR / NRR):**
+```
+NDR = (Beginning MRR + Expansion MRR - Churned MRR - Contraction MRR)
+ / Beginning MRR × 100
+
+The benchmark everyone quotes: 100% means existing customers are flat.
+> 100% means existing customers grow revenue on their own.
+World-class (Snowflake, Datadog): 130%+
+
+Why it matters: NDR > 100% means revenue growth even if you sign zero new customers.
+At NDR = 120% and $5M ARR: you will reach $7M ARR in 24 months without a single new sale.
+```
+
+**Gross Revenue Retention (GRR):**
+```
+GRR = (Beginning MRR - Churned MRR - Contraction MRR) / Beginning MRR × 100
+
+GRR measures the floor of your retention (ignoring expansion).
+GRR is always ≤ NDR.
+Target: > 85% for SMB SaaS, > 90% for mid-market, > 95% for enterprise.
+```
+
+**Logo Churn vs Revenue Churn:**
+```
+Logo churn: % of customers who cancel (ignores size)
+Revenue churn: % of ARR that cancels (accounts for size)
+
+Why the distinction matters:
+ You could have 10% logo churn but 3% revenue churn (churning small customers)
+ Or 5% logo churn but 12% revenue churn (churning large customers) — much worse
+
+Report both. If they diverge significantly, investigate immediately.
+```
+
+**ACV (Annual Contract Value):**
+```
+ACV = Total contract value / contract term in years
+Not to be confused with ARR (which only counts recurring, not one-time fees)
+
+Rising ACV: You're moving upmarket (good for efficiency, check if ICP is changing)
+Falling ACV: You're moving downmarket (check burn multiple — may not be economic)
+```
+
+**Rule of 40:**
+```
+Rule of 40 = Revenue Growth Rate % + EBITDA Margin %
+Target: > 40%
+
+Example: 60% growth + (-15%) EBITDA margin = 45. Passing.
+Example: 20% growth + 5% EBITDA margin = 25. Failing at growth stage.
+
+At early stage (< $5M ARR): Rule of 40 doesn't apply. Growth is the only metric.
+At growth stage ($5-20M ARR): Starting to matter.
+At scale ($20M+ ARR): Board and investors will hold you to this.
+```
+
+---
+
+## 4. FP&A for Startups: What to Measure When
+
+### Metrics by Stage
+
+**Pre-seed / Seed (< $1M ARR):**
+```
+Focus on: Cash, pipeline, customer conversations
+Measure: Monthly cash burn, weeks of runway, NPS / customer satisfaction
+Don't obsess over: EBITDA margin, gross margin (too early)
+Frequency: Weekly cash check, monthly everything else
+```
+
+**Series A ($1-5M ARR):**
+```
+Focus on: Repeatable sales, unit economics
+Measure: MRR growth, LTV:CAC, CAC payback by channel, gross margin
+Don't obsess over: Profitability, G&A efficiency
+Build now: Monthly financial close (< 5 business days), basic FP&A model
+Frequency: Monthly board pack, weekly leadership metrics
+```
+
+**Series B ($5-20M ARR):**
+```
+Focus on: Scalable go-to-market, operational efficiency
+Measure: NDR, burn multiple, revenue per FTE, OKR attainment
+Start building: Budget vs actuals, department-level P&L
+Build now: Finance team (first financial controller), ERP or NetSuite
+Frequency: Monthly board pack + quarterly deep dive
+```
+
+**Series C+ ($20M+ ARR):**
+```
+Focus on: Path to profitability, market leadership
+Measure: Rule of 40, free cash flow, CAC efficiency by segment
+Must have: FP&A team, full three-statement model, 5-year plan
+Frequency: Monthly financial close (< 3 business days), quarterly earnings prep
+```
+
+### Reporting Cadence
+
+**Weekly (CFO + leadership):**
+- Cash balance (CFO checks daily, reports weekly)
+- Pipeline / sales metrics (if in a sales-led motion)
+- Any metric that changed dramatically vs. prior week
+
+**Monthly (board + leadership):**
+- Full financial dashboard (ARR, gross margin, burn, runway)
+- Budget vs actual with explanations for > 10% variances
+- Unit economics update
+- Headcount change summary
+
+**Quarterly (board + investors):**
+- Full three-statement model vs budget
+- Cohort analysis update
+- Scenario planning review and trigger assessment
+- Next quarter outlook
+
+---
+
+## 5. Budget vs Actual Analysis Framework
+
+### The Purpose of BvA
+
+Budget vs actual is not about being right. It's about understanding *why* you were wrong, so you can make better decisions.
+
+The CFO who reports "we missed budget by 15%" without explanation is failing. The CFO who says "we missed budget by 15% because enterprise deals took 30 more days to close than modeled — here's what we're doing about it" is doing their job.
+
+### BvA Template
+
+```
+Category Budget Actual $ Var % Var Explanation
+-------------------------------------------------------------------
+ARR $2,400K $2,280K ($120K) (5%) 2 enterprise deals slipped to Q1
+New ARR $400K $350K ($50K) (13%) Above
+Expansion ARR $120K $140K $20K 17% PLG motion outperforming
+Churn ($60K) ($80K) ($20K) (33%) 2 unexpected SMB churns (now fixed)
+Gross Margin 75.0% 73.2% -1.8% n/a Infrastructure over-provisioned
+S&M Spend $820K $840K ($20K) (2%) Within tolerance
+R&D Spend $680K $710K ($30K) (4%) Backfill hire started month early
+G&A Spend $140K $148K ($8K) (6%) Legal fees for new customer contract
+Cash Burn (net) $580K $648K ($68K) (12%) Driven by ARR shortfall + costs
+Runway (mo) 14.5 13.0 (1.5) n/a Tracking; fundraise target unchanged
+```
+
+### Variance Thresholds
+
+```
+< ±5%: Note in appendix, no explanation needed in main pack
+5-10%: One-line explanation required
+> 10%: Full paragraph: what happened, why, what changes
+> 20%: Board conversation required (model assumption was wrong, or unexpected event)
+```
+
+### Forecasting vs Budgeting
+
+**Budget:** Set at start of year. Fixed expectation. Updated quarterly.
+**Forecast:** Rolling 3-month outlook. Updated monthly. Should converge with budget over time.
+
+```
+Common mistake: Treating forecast as wishful thinking ("what we hope happens")
+Correct approach: Forecast is your best current estimate given all known information.
+ If forecast diverges from budget by > 15%, the budget is wrong.
+ Reforecast and communicate to board.
+```
+
+**Rolling forecast (recommended for startups):**
+```
+Always have a 12-month forward model.
+Update it monthly with actuals replacing the first month.
+The forecast should always reflect your current operational reality, not your hope.
+```
+
+---
+
+## Key Formulas Reference
+
+```python
+# ARR and growth
+ARR_growth_yoy = (ending_ARR - beginning_ARR) / beginning_ARR
+
+# Net Dollar Retention
+NDR = (beginning_MRR + expansion_MRR - churn_MRR - contraction_MRR) / beginning_MRR
+
+# Burn Multiple
+burn_multiple = net_cash_burn / net_new_ARR
+
+# Rule of 40
+rule_of_40 = revenue_growth_pct + ebitda_margin_pct
+
+# LTV (SaaS)
+LTV = (ARPA * gross_margin_pct) / monthly_churn_rate
+
+# CAC Payback (months)
+cac_payback = CAC / (ARPA * gross_margin_pct)
+
+# Magic Number (sales efficiency)
+magic_number = (net_new_ARR * 4) / prior_quarter_S_and_M_spend
+
+# Gross margin
+gross_margin = (revenue - COGS) / revenue
+
+# Quick Ratio (growth efficiency)
+quick_ratio = (new_MRR + expansion_MRR) / (churned_MRR + contraction_MRR)
+# Target: > 4 for high-growth SaaS
+```
diff --git a/skills/cfo-advisor/references/fundraising_playbook.md b/skills/cfo-advisor/references/fundraising_playbook.md
new file mode 100644
index 00000000..97a546e0
--- /dev/null
+++ b/skills/cfo-advisor/references/fundraising_playbook.md
@@ -0,0 +1,419 @@
+# Fundraising Playbook
+
+From timing to close. What investors actually look for, how valuation works, and the term sheet clauses that matter.
+
+---
+
+## 1. When to Raise
+
+**Optimal timing:**
+```
+Target: 18-24 months runway post-close
+Minimum: 12 months runway post-close (leaves no buffer for slip)
+
+Start process when: 9-12 months runway remaining
+ → 3-6 months for process (typically 4-5 months for Series A/B)
+ → Leaves 3-6 months buffer if process drags
+
+Never start when: < 6 months runway
+ → You're negotiating from desperation
+ → Investors can smell it
+ → Terms get worse, or you don't close at all
+```
+
+**Rule:** Your leverage is maximum when you don't *need* to raise. Raise from a position of momentum, not necessity.
+
+---
+
+## 2. What Investors Look For at Each Stage
+
+### Pre-seed
+- Team (are these people credible for this problem?)
+- Problem clarity (is the problem real and meaningful?)
+- Early signal (any customers paying, waitlist, prototype)
+- Market size (worth building a VC-scale company?)
+
+**Typical ask:** $500K–$2M | **Typical valuation:** $3M–$10M pre-money
+
+### Seed
+- Product-market signal (customers using and paying)
+- Founding team with domain expertise
+- ARR: $100K–$1M (or strong usage for PLG)
+- Clear hypothesis for what Series A looks like
+
+**Typical ask:** $2M–$5M | **Typical valuation:** $8M–$20M pre-money
+
+### Series A
+
+Investors are buying a *repeatable sales motion*. Not just customers — a machine.
+
+**What they need to see:**
+- ARR: $1M–$5M growing > 100% YoY
+- LTV:CAC > 2.5x (and improving)
+- Net Dollar Retention > 100%
+- CAC Payback < 18 months
+- Gross margin > 65%
+- At least 5-10 reference customers (not just lighthouse)
+- Sales motion that converts without the founder closing every deal
+
+**Typical ask:** $8M–$15M | **Typical valuation:** $25M–$60M pre-money
+
+### Series B
+
+Investors are buying *scalable go-to-market*. Can you pour fuel on the fire?
+
+**What they need to see:**
+- ARR: $5M–$20M growing > 100% YoY
+- LTV:CAC > 3x, CAC Payback < 18 months
+- Sales capacity model (hiring plan → pipeline → revenue)
+- NDR > 110% (expansion motion working)
+- Some proof of market expansion (new segments, geographies, use cases)
+- Path to category leadership
+
+**Typical ask:** $15M–$40M | **Typical valuation:** $60M–$200M pre-money
+
+### Series C and Beyond
+
+Investors are buying *market leadership* and *path to profitability*.
+
+**What they need to see:**
+- ARR: $20M+ (often $30-50M for credible Series C)
+- Rule of 40 > 40 (or credible path)
+- Gross margin > 70%
+- NDR > 115%
+- Evidence of market leadership (brand, win rates, analyst mentions)
+- Clear path to $100M+ ARR
+
+---
+
+## 3. Valuation Methods
+
+### Revenue Multiples (Primary Method for SaaS)
+
+```
+Pre-money Valuation = ARR × Revenue Multiple
+
+Revenue multiple benchmarks (2024-2025):
+ > 100% YoY growth: 8x–15x ARR
+ 50-100% YoY growth: 4x–8x ARR
+ 20-50% YoY growth: 2x–4x ARR
+ < 20% YoY growth: 1x–2x ARR
+
+Adjustments:
+ NDR > 120%: +1x–2x premium
+ Gross margin > 75%: +0.5x–1x premium
+ Burn multiple < 1x: +0.5x–1x premium
+ Capital efficient: Investors pay up for efficiency
+ Declining growth: Compress multiple aggressively
+```
+
+### The Investor's Math (Know This)
+
+Every VC has a required return. Work backwards from their constraints:
+
+```
+Investor targets: 3x fund return
+Fund size: $200M, check size: $15M (initial), $25M (with follow-on)
+Ownership at exit needed: 15%
+At 15% ownership: needs $25M / 15% = $167M post-money valuation
+Exit needed to return 3x on that check: $25M × 10 = $250M company value
+ (10x because most deals fail, winners must carry the fund)
+
+Implication: If you think you'll exit for $150M, that VC will pass or price you accordingly.
+```
+
+This is why Series A investors rarely lead rounds where they can't see a $300M+ exit path. It's not about your business being bad — it's about fund math.
+
+### Comparable Company Analysis
+
+For later stages (Series B+):
+
+```
+1. Find 5-10 comparable public SaaS companies
+2. Calculate their EV/NTM Revenue multiples (use latest data)
+3. Apply a private market discount (typically 20-40% vs public comps)
+4. Adjust for your growth rate relative to comps
+
+Example (2024):
+ Public SaaS comps: 6x NTM Revenue (median)
+ Private discount: 30%
+ Adjusted: ~4.2x
+ Your NTM Revenue: $8M
+ Implied valuation: ~$33M pre-money
+```
+
+### DCF (Late Stage Only)
+
+DCF is unreliable for early-stage startups (terminal value dominates, growth rate assumptions are fantasy). Use it as a sanity check at Series C+, not as the primary valuation method.
+
+---
+
+## 4. Term Sheet Breakdown
+
+### Liquidation Preference (Most Important Economic Term)
+
+This determines who gets paid first in an exit — and how much.
+
+```
+1x Non-Participating Preferred (BEST for founders):
+ Investor gets 1x money back OR converts to common (their choice).
+ At acquisition: investor takes larger of {1x invested} or {% ownership × proceeds}
+ Example: $10M invested, exits at $100M, owns 20%
+ Option A: $10M (1x)
+ Option B: $20M (20% of $100M)
+ Investor takes $20M. Founders split $80M.
+
+1x Participating Preferred (WORSE for founders):
+ Investor gets 1x money back AND participates in remaining proceeds.
+ Example: same scenario
+ $10M (1x) + 20% of remaining $90M = $10M + $18M = $28M
+ Founders split $72M instead of $80M
+ Cost to founders: $8M (10% of exit value)
+
+2x Participating (RED FLAG):
+ Investor gets 2x back AND participates.
+ Only accept under duress. Push hard against this.
+
+Full Ratchet Anti-Dilution (AVOID):
+ Down-round triggers full repricing of investor shares to new (lower) price.
+ Founders get massively diluted. Never accept if alternatives exist.
+```
+
+### Anti-Dilution Protection
+
+```
+Broad-based weighted average (standard):
+ Adjusts investor conversion price based on all dilutive securities.
+ Most founder-friendly anti-dilution. Accept this.
+
+Narrow-based weighted average (slightly worse):
+ Same mechanism but uses smaller denominator.
+ Gives investors slightly more protection. Usually acceptable.
+
+Full ratchet (avoid):
+ Price drops to whatever the new round prices at.
+ Devastating in down rounds. Fight this.
+```
+
+### Pro-Rata Rights
+
+```
+Standard pro-rata: Investor can maintain their % ownership in future rounds.
+ Reasonable. Accept for major investors.
+
+Super pro-rata: Investor can increase their % in future rounds.
+ Caps your ability to bring in new lead investors.
+ Avoid unless the investor is exceptional and you want them in future rounds.
+
+Major investor threshold: Typically investors with > $500K–$1M check get pro-rata.
+ Don't give pro-rata to every small check — clogs future rounds.
+```
+
+### Board Composition
+
+```
+Seed (3 members): 2 founders, 1 lead investor
+Series A (5 members): 2 founders, 2 investors, 1 independent
+Series B (5-7 seats): Watch for investor majority — negotiate hard
+
+Rule: Founders should retain majority through Series A.
+ Independent director should be your choice, not investor's.
+ Never accept investor majority before Series C.
+
+Board observer rights: Common for smaller investors. No vote but present in meetings.
+ Limit to 1-2 observers or meetings become unwieldy.
+```
+
+### Other Terms That Matter
+
+```
+Drag-along: Majority can force minority shareholders to vote for acquisition.
+ Standard and reasonable. Check what threshold triggers drag.
+
+Information rights: Investors get financial statements.
+ Standard. Monthly for major investors, quarterly for others.
+
+Redemption rights: Investors can force buyback after X years.
+ Push to remove or add carve-outs for insufficient funds.
+
+No-shop clause: You can't shop the term sheet to other investors.
+ Standard (14-30 days). Reasonable.
+
+Exclusivity: Stronger version of no-shop. Sometimes includes no other fundraise discussions.
+ Acceptable for 30 days; push back on > 45 days.
+```
+
+---
+
+## 5. Cap Table Management
+
+### Dilution Planning Model
+
+Run this before every round. Know your number before walking into any negotiation.
+
+```
+ Pre-Seed Post-Seed Post-A Post-B Post-C
+Founder A 45.0% 36.0% 26.5% 21.2% 18.7%
+Founder B 45.0% 36.0% 26.5% 21.2% 18.7%
+Angel 1 5.0% 4.0% 2.9% 2.4% 2.1%
+Angel 2 5.0% 4.0% 2.9% 2.4% 2.1%
+Seed Fund - 12.0% 8.8% 7.1% 6.2%
+Option Pool - 8.0% 12.0% 10.0% 8.0%
+Series A - - 20.4% 16.3% 14.4%
+Series B - - - 19.5% 17.2%
+Series C - - - - 12.6%
+
+Round size / pre-money:
+Pre-Seed: $500K / $9M pre = 5% dilution
+Seed: $2M / $8M pre = 20% dilution (includes 8% pool)
+Series A: $10M / $38M pre = 20.8% dilution (pool refresh to 12%)
+Series B: $20M / $80M pre = 20% dilution
+Series C: $30M / $170M pre = 15% dilution
+```
+
+**Option pool shuffle:** Investors often require you to create/expand the option pool *before* the round closes, which dilutes existing shareholders (not the incoming investor). Model this explicitly — a 20% round with a 5% pool expansion is really 24%+ dilution to founders.
+
+### Cap Table Hygiene
+
+```
+Tools: Carta, Pulley, Capshare (all acceptable)
+Never: Track cap table in a spreadsheet past seed stage. Errors compound.
+
+Keep it clean:
+ - Repurchase departed co-founder shares immediately (don't let unvested shares linger)
+ - Convert SAFEs to equity cleanly at each priced round
+ - Document every grant with a board resolution
+ - Cliff + vesting for ALL employees and founders (standard: 1-year cliff, 4-year vest)
+ - 409A valuation required before every option grant (IRS requirement)
+```
+
+---
+
+## 6. Data Room Preparation
+
+### Core Documents (Required)
+
+```
+Financial:
+ □ 3 years historical financials (or all history if < 3 years)
+ □ Monthly P&L and cash flow (last 24 months)
+ □ Current financial model (18-24 months forward)
+ □ Budget vs actual (last 4 quarters)
+ □ Cap table (fully diluted, with all SAFEs/convertibles modeled)
+ □ Bank statements (last 3-6 months)
+
+Legal:
+ □ Certificate of incorporation + all amendments
+ □ All prior financing documents (SAFEs, convertible notes, stock purchase agreements)
+ □ Cap table (Carta/Pulley export)
+ □ IP assignment agreements (all founders and employees)
+ □ Material contracts (top 10 customers, key vendors)
+ □ Employee list (titles, start dates, salaries, equity grants)
+
+Product & Business:
+ □ Product demo / walkthrough video
+ □ Architecture overview (for technical investors)
+ □ Customer case studies (3-5 named references)
+ □ NPS / CSAT data
+ □ Competitive landscape analysis
+
+Metrics:
+ □ MRR/ARR by month (all history)
+ □ Cohort retention chart
+ □ CAC by channel
+ □ LTV by cohort
+ □ NPS trend
+```
+
+### What Investors Actually Check First
+
+In order of typical priority during due diligence:
+
+1. **Cap table** — Is it clean? Any concerning structures?
+2. **Cohort retention** — Is churn improving or deteriorating?
+3. **Revenue quality** — What % is recurring? Any one-time or non-recurring?
+4. **Top 10 customers** — Concentration risk? Any logos at risk?
+5. **Bank statements** — Does cash match what was reported?
+6. **IP assignments** — Does the company own its IP? (Founders who didn't assign IP kill deals)
+
+### Red Flags That Kill Deals
+
+- Missing IP assignment agreements for founders (most common deal killer at early stage)
+- Cap table with > 20 angels/small investors (messy, hard to get consent for future rounds)
+- Customer concentration > 30% in single customer without explanation
+- Revenue recognition issues (booking ARR on contracts that allow easy cancellation)
+- Cohort data that gets worse in later cohorts
+- Bank balance doesn't match reported cash position
+
+---
+
+## 7. Investor Communication Cadence
+
+### During Fundraise
+
+```
+Week 1-2: Warm intro sourcing, LP/network mapping
+Week 3-6: First meetings (aim for 20-30 first meetings)
+Week 7-10: Partner meetings, deep dives, due diligence
+Week 11-14: Term sheets, negotiation
+Week 15-18: Legal, closing
+```
+
+**Parallel process is essential.** Never negotiate with one investor at a time. Competition is your leverage.
+
+### Post-Close: Investor Updates
+
+Monthly investor update (send within 10 days of month-end):
+
+```
+Subject: [Company] Monthly Update — [Month Year]
+
+Highlights (3 bullets max):
+ • [Biggest win]
+ • [Biggest learning/challenge]
+ • [What we're focused on next month]
+
+Metrics:
+ ARR: $X (+X% MoM)
+ Net new ARR: $X
+ Gross margin: X%
+ Cash: $X (X months runway)
+ Headcount: X
+
+Asks (be specific):
+ • Looking for intro to [persona/company] for [specific reason]
+ • Need advisor with experience in [specific area]
+ • [Other concrete ask]
+```
+
+**Why this matters:** Investors who are informed and engaged are better positioned to help when you need it. The investor who hasn't heard from you in 6 months is less likely to write a bridge check or make a warm intro when you ask.
+
+---
+
+## Key Formulas
+
+```python
+# Post-money valuation
+post_money = pre_money + investment_amount
+
+# Investor ownership %
+ownership_pct = investment_amount / post_money
+
+# Dilution to existing shareholders
+dilution = investment_amount / post_money # as a fraction
+
+# New shares issued
+new_shares = (investment_amount / post_money) * total_post_shares
+# equivalent: new_shares = pre_money_shares * (investment_amount / pre_money)
+
+# Option pool expansion impact (pool shuffle)
+# Creating X% option pool pre-close dilutes founders:
+pool_shares_needed = target_pct * (pre_shares + new_round_shares + pool_shares_needed)
+# Solve: pool_shares_needed = target_pct * (pre_shares + new_round_shares) / (1 - target_pct)
+
+# LTV:CAC ratio
+ltv_cac = ltv / cac # target: > 3x
+
+# CAC payback (months)
+payback_months = cac / (arpa * gross_margin_pct)
+```
diff --git a/skills/cfo-advisor/scripts/burn_rate_calculator.py b/skills/cfo-advisor/scripts/burn_rate_calculator.py
new file mode 100644
index 00000000..6580a31b
--- /dev/null
+++ b/skills/cfo-advisor/scripts/burn_rate_calculator.py
@@ -0,0 +1,402 @@
+#!/usr/bin/env python3
+"""
+Burn Rate & Runway Calculator
+==============================
+Models startup runway across base/bull/bear scenarios, incorporating
+a hiring plan and revenue trajectory. Outputs months of runway,
+cash-out dates, and decision trigger points.
+
+Usage:
+ python burn_rate_calculator.py
+ python burn_rate_calculator.py --csv # export to CSV
+
+Stdlib only. No dependencies.
+"""
+
+import argparse
+import csv
+import io
+import sys
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HiringEntry:
+ """A planned hire."""
+ month: int # months from model start (1-indexed)
+ role: str
+ department: str # "sales", "engineering", "cs", "ga"
+ annual_salary: float
+ benefits_pct: float = 0.22 # benefits as % of salary
+ recruiting_cost: float = 0.0 # one-time recruiting fee
+
+
+@dataclass
+class RevenueEntry:
+ """Monthly revenue data point (historical or projected)."""
+ month: int
+ mrr: float # monthly recurring revenue
+ one_time: float = 0.0
+
+
+@dataclass
+class ModelConfig:
+ """Master configuration for a runway scenario."""
+ name: str
+ starting_cash: float
+ starting_mrr: float
+ starting_headcount: int
+ avg_loaded_salary: float # average fully-loaded salary per current employee
+ base_non_headcount_opex: float # monthly non-headcount costs (infra, tools, etc.)
+ gross_margin_pct: float # 0.0–1.0
+ mrr_growth_rate: float # monthly MoM growth rate, 0.0–1.0
+ hiring_plan: list[HiringEntry] = field(default_factory=list)
+ model_months: int = 24
+ start_date: Optional[date] = None
+
+
+@dataclass
+class MonthResult:
+ """Single month output."""
+ month: int
+ label: str # e.g. "Month 1 (Apr 2025)"
+ mrr: float
+ gross_profit: float
+ headcount: int
+ headcount_cost: float # total loaded headcount cost this month
+ other_opex: float
+ gross_burn: float
+ net_burn: float
+ cash_start: float
+ cash_end: float
+ runway_months: float # projected runway from this month
+ cumulative_new_arr: float # for burn multiple
+
+
+# ---------------------------------------------------------------------------
+# Core calculator
+# ---------------------------------------------------------------------------
+
+class RunwayCalculator:
+
+ def __init__(self, config: ModelConfig):
+ self.cfg = config
+
+ def run(self) -> list[MonthResult]:
+ cfg = self.cfg
+ results = []
+
+ # Build headcount schedule: month -> list of new hires starting that month
+ hire_by_month: dict[int, list[HiringEntry]] = {}
+ for h in cfg.hiring_plan:
+ hire_by_month.setdefault(h.month, []).append(h)
+
+ # Track existing employees
+ active_employees: list[dict] = []
+ for _ in range(cfg.starting_headcount):
+ active_employees.append({
+ "monthly_loaded": cfg.avg_loaded_salary / 12 * 1.0,
+ "start_month": 0,
+ })
+
+ cash = cfg.starting_cash
+ mrr = cfg.starting_mrr
+ cumulative_new_arr = 0.0
+ starting_mrr = cfg.starting_mrr
+
+ for m in range(1, cfg.model_months + 1):
+ # Process new hires this month
+ one_time_recruiting = 0.0
+ if m in hire_by_month:
+ for hire in hire_by_month[m]:
+ monthly_loaded = (
+ hire.annual_salary * (1 + hire.benefits_pct) / 12
+ )
+ active_employees.append({
+ "monthly_loaded": monthly_loaded,
+ "start_month": m,
+ })
+ one_time_recruiting += hire.recruiting_cost
+
+ # Revenue this month
+ mrr = mrr * (1 + cfg.mrr_growth_rate)
+ gross_profit = mrr * cfg.gross_margin_pct
+
+ # Headcount cost
+ headcount_cost = sum(e["monthly_loaded"] for e in active_employees)
+ headcount_cost += one_time_recruiting
+
+ # Other opex (infra, SaaS tools, office, etc.)
+ other_opex = cfg.base_non_headcount_opex
+
+ # Burn
+ gross_burn = headcount_cost + other_opex
+ net_burn = gross_burn - gross_profit
+
+ # Cash
+ cash_start = cash
+ cash = cash - net_burn
+ cash_end = cash
+
+ # Projected runway from this month (using current net burn rate)
+ runway = cash_end / net_burn if net_burn > 0 else float("inf")
+
+ # Cumulative new ARR (for burn multiple calc)
+ new_mrr_added = mrr - starting_mrr if m == 1 else mrr - results[-1].mrr
+ cumulative_new_arr += new_mrr_added * 12
+
+ # Label
+ if cfg.start_date:
+ month_date = date(
+ cfg.start_date.year,
+ cfg.start_date.month,
+ 1,
+ ) + timedelta(days=32 * (m - 1))
+ month_date = month_date.replace(day=1)
+ label = f"Month {m:02d} ({month_date.strftime('%b %Y')})"
+ else:
+ label = f"Month {m:02d}"
+
+ results.append(MonthResult(
+ month=m,
+ label=label,
+ mrr=mrr,
+ gross_profit=gross_profit,
+ headcount=len(active_employees),
+ headcount_cost=headcount_cost,
+ other_opex=other_opex,
+ gross_burn=gross_burn,
+ net_burn=net_burn,
+ cash_start=cash_start,
+ cash_end=cash_end,
+ runway_months=runway,
+ cumulative_new_arr=cumulative_new_arr,
+ ))
+
+ # Stop if cash runs out
+ if cash_end <= 0:
+ break
+
+ return results
+
+ def cash_out_date(self, results: list[MonthResult]) -> Optional[str]:
+ """Return the label of the month cash runs out, or None if model survives."""
+ for r in results:
+ if r.cash_end <= 0:
+ return r.label
+ return None
+
+ def burn_multiple(self, results: list[MonthResult]) -> float:
+ """Burn multiple = total net burn / total net new ARR over model period."""
+ total_net_burn = sum(r.net_burn for r in results if r.net_burn > 0)
+ first_mrr = results[0].mrr / (1 + self.cfg.mrr_growth_rate) # starting mrr
+ total_new_arr = (results[-1].mrr - first_mrr) * 12
+ if total_new_arr <= 0:
+ return float("inf")
+ return total_net_burn / total_new_arr
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt_k(value: float) -> str:
+ """Format as $Xk or $X.XM."""
+ if abs(value) >= 1_000_000:
+ return f"${value/1_000_000:.2f}M"
+ if abs(value) >= 1_000:
+ return f"${value/1_000:.0f}K"
+ return f"${value:.0f}"
+
+
+def print_summary(name: str, results: list[MonthResult], calc: RunwayCalculator) -> None:
+ cash_out = calc.cash_out_date(results)
+ bm = calc.burn_multiple(results)
+ last = results[-1]
+ first = results[0]
+
+ print(f"\n{'='*60}")
+ print(f" SCENARIO: {name}")
+ print(f"{'='*60}")
+ print(f" Months modeled: {len(results)}")
+ print(f" Cash out: {cash_out or 'Does not run out in model period'}")
+ print(f" Ending cash: {fmt_k(last.cash_end)}")
+ print(f" Final runway: {last.runway_months:.1f} months")
+ print(f" Starting MRR: {fmt_k(first.mrr)}")
+ print(f" Ending MRR: {fmt_k(last.mrr)}")
+ print(f" Ending headcount: {last.headcount}")
+ print(f" Burn multiple: {bm:.2f}x")
+ print(f" Avg net burn: {fmt_k(sum(r.net_burn for r in results)/len(results))}/mo")
+
+ # Decision triggers
+ print(f"\n Decision Triggers:")
+ triggers = {9: "⚠️ START FUNDRAISE", 6: "🔴 COST REDUCTION PLAN", 4: "🚨 EXECUTE CUTS / BRIDGE"}
+ shown = set()
+ for r in results:
+ for threshold, label in triggers.items():
+ if r.runway_months <= threshold and threshold not in shown:
+ print(f" {r.label}: {label} (runway = {r.runway_months:.1f} mo)")
+ shown.add(threshold)
+
+
+def print_monthly_table(results: list[MonthResult], max_rows: int = 24) -> None:
+ header = f"{'Month':<22} {'MRR':>10} {'Hdct':>6} {'Net Burn':>12} {'Cash':>12} {'Runway':>8}"
+ print(f"\n{header}")
+ print("-" * len(header))
+ for r in results[:max_rows]:
+ runway_str = f"{r.runway_months:.1f}mo" if r.runway_months != float("inf") else "∞"
+ print(
+ f"{r.label:<22} "
+ f"{fmt_k(r.mrr):>10} "
+ f"{r.headcount:>6} "
+ f"{fmt_k(r.net_burn):>12} "
+ f"{fmt_k(r.cash_end):>12} "
+ f"{runway_str:>8}"
+ )
+
+
+def export_csv(scenarios: list[tuple[str, list[MonthResult]]]) -> str:
+ buf = io.StringIO()
+ writer = csv.writer(buf)
+ writer.writerow([
+ "Scenario", "Month", "Label", "MRR", "Gross Profit", "Headcount",
+ "Headcount Cost", "Other Opex", "Gross Burn", "Net Burn",
+ "Cash Start", "Cash End", "Runway Months"
+ ])
+ for name, results in scenarios:
+ for r in results:
+ writer.writerow([
+ name, r.month, r.label,
+ round(r.mrr, 2), round(r.gross_profit, 2), r.headcount,
+ round(r.headcount_cost, 2), round(r.other_opex, 2),
+ round(r.gross_burn, 2), round(r.net_burn, 2),
+ round(r.cash_start, 2), round(r.cash_end, 2),
+ round(r.runway_months, 2),
+ ])
+ return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def make_sample_configs() -> list[ModelConfig]:
+ """
+ Sample company: Series A SaaS startup
+ - $3M cash on hand (post Series A)
+ - $125K MRR (~$1.5M ARR)
+ - 18 employees, $150K avg salary
+ - $80K/mo non-headcount opex (infra, tools, office)
+ - 72% gross margin
+ """
+ common_kwargs = dict(
+ starting_cash=3_000_000,
+ starting_mrr=125_000,
+ starting_headcount=18,
+ avg_loaded_salary=150_000,
+ base_non_headcount_opex=80_000,
+ gross_margin_pct=0.72,
+ model_months=24,
+ start_date=date(2025, 1, 1),
+ )
+
+ # Base: 10% MoM growth, moderate hiring
+ base_hiring = [
+ HiringEntry(month=2, role="AE #1", department="sales", annual_salary=120_000, recruiting_cost=18_000),
+ HiringEntry(month=3, role="Senior SWE #1", department="engineering", annual_salary=160_000, recruiting_cost=24_000),
+ HiringEntry(month=5, role="SDR #1", department="sales", annual_salary=80_000, recruiting_cost=12_000),
+ HiringEntry(month=6, role="CSM #1", department="cs", annual_salary=90_000, recruiting_cost=13_500),
+ HiringEntry(month=8, role="AE #2", department="sales", annual_salary=120_000, recruiting_cost=18_000),
+ HiringEntry(month=9, role="Senior SWE #2", department="engineering", annual_salary=165_000, recruiting_cost=24_750),
+ HiringEntry(month=12, role="Controller", department="ga", annual_salary=130_000, recruiting_cost=19_500),
+ HiringEntry(month=14, role="AE #3", department="sales", annual_salary=125_000, recruiting_cost=18_750),
+ HiringEntry(month=15, role="ML Engineer", department="engineering", annual_salary=175_000, recruiting_cost=26_250),
+ HiringEntry(month=18, role="AE #4", department="sales", annual_salary=125_000, recruiting_cost=18_750),
+ ]
+
+ # Bull: 15% MoM growth, full hiring plan
+ bull_hiring = base_hiring + [
+ HiringEntry(month=4, role="Marketing Manager", department="sales", annual_salary=110_000, recruiting_cost=16_500),
+ HiringEntry(month=7, role="Senior SWE #3", department="engineering", annual_salary=165_000, recruiting_cost=24_750),
+ HiringEntry(month=10, role="AE #5", department="sales", annual_salary=125_000, recruiting_cost=18_750),
+ HiringEntry(month=13, role="DevOps Engineer", department="engineering", annual_salary=150_000, recruiting_cost=22_500),
+ HiringEntry(month=16, role="AE #6", department="sales", annual_salary=125_000, recruiting_cost=18_750),
+ ]
+
+ # Bear: 5% MoM growth, hiring freeze after month 3
+ bear_hiring = [
+ HiringEntry(month=2, role="AE #1", department="sales", annual_salary=120_000, recruiting_cost=18_000),
+ HiringEntry(month=3, role="Senior SWE #1", department="engineering", annual_salary=160_000, recruiting_cost=24_000),
+ ]
+
+ return [
+ ModelConfig(name="BULL (15% MoM, full hiring)", mrr_growth_rate=0.15, hiring_plan=bull_hiring, **common_kwargs),
+ ModelConfig(name="BASE (10% MoM, planned hiring)", mrr_growth_rate=0.10, hiring_plan=base_hiring, **common_kwargs),
+ ModelConfig(name="BEAR ( 5% MoM, hiring freeze M3+)", mrr_growth_rate=0.05, hiring_plan=bear_hiring, **common_kwargs),
+ ModelConfig(name="DISTRESS (0% growth, freeze now)", mrr_growth_rate=0.00, hiring_plan=[], **common_kwargs),
+ ]
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Startup Burn Rate & Runway Calculator")
+ parser.add_argument("--csv", action="store_true", help="Export full monthly data as CSV to stdout")
+ parser.add_argument("--scenario", choices=["bull", "base", "bear", "distress", "all"], default="all")
+ args = parser.parse_args()
+
+ configs = make_sample_configs()
+ if args.scenario != "all":
+ configs = [c for c in configs if args.scenario.upper() in c.name.upper()]
+
+ all_results: list[tuple[str, list[MonthResult]]] = []
+
+ print("\n" + "="*60)
+ print(" BURN RATE & RUNWAY CALCULATOR")
+ print(" Sample Company: Series A SaaS Startup")
+ print(" Starting cash: $3M | Starting MRR: $125K | 18 employees")
+ print("="*60)
+
+ for cfg in configs:
+ calc = RunwayCalculator(cfg)
+ results = calc.run()
+ all_results.append((cfg.name, results))
+ print_summary(cfg.name, results, calc)
+ print_monthly_table(results)
+
+ # Comparison summary
+ print("\n" + "="*60)
+ print(" SCENARIO COMPARISON")
+ print("="*60)
+ print(f" {'Scenario':<40} {'Runway':>8} {'Cash Out':<30} {'Burn Mult':>10}")
+ print(" " + "-"*88)
+ for cfg, (name, results) in zip(configs, all_results):
+ calc = RunwayCalculator(cfg)
+ cash_out = calc.cash_out_date(results) or "Survives model period"
+ bm = calc.burn_multiple(results)
+ final_runway = results[-1].runway_months
+ runway_str = f"{final_runway:.1f}mo" if final_runway != float("inf") else "∞"
+ bm_str = f"{bm:.2f}x" if bm != float("inf") else "∞"
+ print(f" {name:<40} {runway_str:>8} {cash_out:<30} {bm_str:>10}")
+
+ print("\n Decision Trigger Reference:")
+ print(" 9 months runway → Start fundraise process")
+ print(" 6 months runway → Begin cost reduction planning")
+ print(" 4 months runway → Execute cuts; explore bridge financing")
+ print(" 3 months runway → Emergency plan only")
+
+ if args.csv:
+ print("\n\n--- CSV EXPORT ---\n")
+ sys.stdout.write(export_csv(all_results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/cfo-advisor/scripts/fundraising_model.py b/skills/cfo-advisor/scripts/fundraising_model.py
new file mode 100644
index 00000000..7b19f15b
--- /dev/null
+++ b/skills/cfo-advisor/scripts/fundraising_model.py
@@ -0,0 +1,490 @@
+#!/usr/bin/env python3
+"""
+Fundraising Model
+==================
+Cap table management, dilution modeling, and multi-round scenario planning.
+Know exactly what you're giving up before you walk into any negotiation.
+
+Covers:
+ - Cap table state at each round
+ - Dilution per shareholder per round
+ - Option pool shuffle impact
+ - Multi-round projections (Seed → A → B → C)
+ - Return scenarios at different exit valuations
+
+Usage:
+ python fundraising_model.py
+ python fundraising_model.py --exit 150 # model at $150M exit
+ python fundraising_model.py --csv
+
+Stdlib only. No dependencies.
+"""
+
+import argparse
+import csv
+import io
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Shareholder:
+ """A shareholder in the cap table."""
+ name: str
+ share_class: str # "common", "preferred", "option"
+ shares: float
+ invested: float = 0.0 # total cash invested
+ is_option_pool: bool = False
+
+
+@dataclass
+class RoundConfig:
+ """Configuration for a financing round."""
+ name: str # e.g. "Series A"
+ pre_money_valuation: float
+ investment_amount: float
+ new_option_pool_pct: float = 0.0 # % of POST-money to allocate to new options
+ option_pool_pre_round: bool = True # True = pool created before round (dilutes founders)
+ lead_investor_name: str = "New Investor"
+ share_price_override: Optional[float] = None # if None, computed from valuation
+
+
+@dataclass
+class CapTableEntry:
+ """A row in the cap table at a point in time."""
+ name: str
+ share_class: str
+ shares: float
+ pct_ownership: float
+ invested: float
+ is_option_pool: bool = False
+
+
+@dataclass
+class RoundResult:
+ """Snapshot of cap table after a round closes."""
+ round_name: str
+ pre_money_valuation: float
+ investment_amount: float
+ post_money_valuation: float
+ price_per_share: float
+ new_shares_issued: float
+ option_pool_shares_created: float
+ total_shares: float
+ cap_table: list[CapTableEntry]
+
+
+@dataclass
+class ExitAnalysis:
+ """Proceeds to each shareholder at an exit."""
+ exit_valuation: float
+ shareholder: str
+ shares: float
+ ownership_pct: float
+ proceeds_common: float # if all preferred converts to common
+ invested: float
+ moic: float # multiple on invested capital (for investors)
+
+
+# ---------------------------------------------------------------------------
+# Core cap table engine
+# ---------------------------------------------------------------------------
+
+class CapTable:
+ """Manages a cap table through multiple rounds."""
+
+ def __init__(self):
+ self.shareholders: list[Shareholder] = []
+ self._total_shares: float = 0.0
+
+ def add_shareholder(self, sh: Shareholder) -> None:
+ self.shareholders.append(sh)
+ self._total_shares += sh.shares
+
+ def total_shares(self) -> float:
+ return sum(s.shares for s in self.shareholders)
+
+ def snapshot(self, label: str = "") -> list[CapTableEntry]:
+ total = self.total_shares()
+ return [
+ CapTableEntry(
+ name=s.name,
+ share_class=s.share_class,
+ shares=s.shares,
+ pct_ownership=s.shares / total if total > 0 else 0,
+ invested=s.invested,
+ is_option_pool=s.is_option_pool,
+ )
+ for s in self.shareholders
+ ]
+
+ def execute_round(self, config: RoundConfig) -> RoundResult:
+ """
+ Execute a financing round:
+ 1. (Optional) Create option pool pre-round (dilutes existing shareholders)
+ 2. Issue new shares to investor at round price
+ Returns a RoundResult with full cap table snapshot.
+ """
+ current_total = self.total_shares()
+
+ # Step 1: Option pool shuffle (if pre-round)
+ option_pool_shares_created = 0.0
+ if config.new_option_pool_pct > 0 and config.option_pool_pre_round:
+ # Target: post-round option pool = new_option_pool_pct of total post-money shares
+ # Solve: pool_shares / (current_total + pool_shares + new_investor_shares) = target_pct
+ # This requires iteration because new_investor_shares also depends on pool_shares
+ # Simplification: create pool based on post-round total (slightly approximated)
+ target_post_round_pct = config.new_option_pool_pct
+ post_money = config.pre_money_valuation + config.investment_amount
+
+ # Estimate shares per dollar (price per share)
+ price_per_share = config.pre_money_valuation / current_total
+ new_investor_shares_estimate = config.investment_amount / price_per_share
+
+ # Pool shares needed so that pool / total_post = target_pct
+ total_post_estimate = current_total + new_investor_shares_estimate
+ pool_shares_needed = (target_post_round_pct * total_post_estimate) / (1 - target_post_round_pct)
+
+ # Check if existing pool is sufficient
+ existing_pool = next(
+ (s.shares for s in self.shareholders if s.is_option_pool), 0
+ )
+ additional_pool_needed = max(0, pool_shares_needed - existing_pool)
+
+ if additional_pool_needed > 0:
+ option_pool_shares_created = additional_pool_needed
+ # Add to existing pool or create new
+ pool_sh = next((s for s in self.shareholders if s.is_option_pool), None)
+ if pool_sh:
+ pool_sh.shares += additional_pool_needed
+ else:
+ self.shareholders.append(Shareholder(
+ name="Option Pool",
+ share_class="option",
+ shares=additional_pool_needed,
+ is_option_pool=True,
+ ))
+
+ # Step 2: Price per share (after pool creation)
+ current_total_post_pool = self.total_shares()
+ if config.share_price_override:
+ price_per_share = config.share_price_override
+ else:
+ price_per_share = config.pre_money_valuation / current_total_post_pool
+
+ # Step 3: New shares for investor
+ new_shares = config.investment_amount / price_per_share
+
+ # Step 4: Add investor to cap table
+ self.shareholders.append(Shareholder(
+ name=config.lead_investor_name,
+ share_class="preferred",
+ shares=new_shares,
+ invested=config.investment_amount,
+ ))
+
+ post_money = config.pre_money_valuation + config.investment_amount
+ total_post = self.total_shares()
+
+ return RoundResult(
+ round_name=config.name,
+ pre_money_valuation=config.pre_money_valuation,
+ investment_amount=config.investment_amount,
+ post_money_valuation=post_money,
+ price_per_share=price_per_share,
+ new_shares_issued=new_shares,
+ option_pool_shares_created=option_pool_shares_created,
+ total_shares=total_post,
+ cap_table=self.snapshot(),
+ )
+
+ def analyze_exit(self, exit_valuation: float) -> list[ExitAnalysis]:
+ """
+ Simple exit analysis: all preferred converts to common, proceeds split pro-rata.
+ (Does not model liquidation preferences — see fundraising_playbook.md for that.)
+ """
+ total = self.total_shares()
+ price_per_share = exit_valuation / total
+ results = []
+ for s in self.shareholders:
+ if s.is_option_pool:
+ continue # unissued options don't receive proceeds
+ proceeds = s.shares * price_per_share
+ moic = proceeds / s.invested if s.invested > 0 else 0.0
+ results.append(ExitAnalysis(
+ exit_valuation=exit_valuation,
+ shareholder=s.name,
+ shares=s.shares,
+ ownership_pct=s.shares / total,
+ proceeds_common=proceeds,
+ invested=s.invested,
+ moic=moic,
+ ))
+ return sorted(results, key=lambda x: x.proceeds_common, reverse=True)
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt(value: float, prefix: str = "$") -> str:
+ if value == float("inf"):
+ return "∞"
+ if abs(value) >= 1_000_000:
+ return f"{prefix}{value/1_000_000:.2f}M"
+ if abs(value) >= 1_000:
+ return f"{prefix}{value/1_000:.0f}K"
+ return f"{prefix}{value:.2f}"
+
+
+def print_round_result(result: RoundResult, prev_cap_table: Optional[list[CapTableEntry]] = None) -> None:
+ print(f"\n{'='*70}")
+ print(f" {result.round_name.upper()}")
+ print(f"{'='*70}")
+ print(f" Pre-money valuation: {fmt(result.pre_money_valuation)}")
+ print(f" Investment: {fmt(result.investment_amount)}")
+ print(f" Post-money valuation: {fmt(result.post_money_valuation)}")
+ print(f" Price per share: {fmt(result.price_per_share, '$')}")
+ print(f" New shares issued: {result.new_shares_issued:,.0f}")
+ if result.option_pool_shares_created > 0:
+ print(f" Option pool created: {result.option_pool_shares_created:,.0f} shares")
+ print(f" ⚠️ Pool created pre-round: dilutes existing shareholders, not new investor")
+ print(f" Total shares post: {result.total_shares:,.0f}")
+
+ print(f"\n {'Shareholder':<22} {'Shares':>12} {'Ownership':>10} {'Invested':>10} {'Δ Ownership':>12}")
+ print(" " + "-"*68)
+
+ prev_map = {e.name: e.pct_ownership for e in prev_cap_table} if prev_cap_table else {}
+
+ for entry in result.cap_table:
+ delta = ""
+ if entry.name in prev_map:
+ change = (entry.pct_ownership - prev_map[entry.name]) * 100
+ delta = f"{change:+.1f}pp"
+ elif not entry.is_option_pool:
+ delta = "new"
+
+ invested_str = fmt(entry.invested) if entry.invested > 0 else "-"
+ print(
+ f" {entry.name:<22} {entry.shares:>12,.0f} "
+ f"{entry.pct_ownership*100:>9.2f}% {invested_str:>10} {delta:>12}"
+ )
+
+
+def print_exit_analysis(results: list[ExitAnalysis], exit_valuation: float) -> None:
+ print(f"\n{'='*70}")
+ print(f" EXIT ANALYSIS @ {fmt(exit_valuation)} (all preferred converts to common)")
+ print(f"{'='*70}")
+ print(f"\n {'Shareholder':<22} {'Ownership':>10} {'Proceeds':>12} {'Invested':>10} {'MOIC':>8}")
+ print(" " + "-"*65)
+ for r in results:
+ moic_str = f"{r.moic:.1f}x" if r.moic > 0 else "n/a"
+ invested_str = fmt(r.invested) if r.invested > 0 else "-"
+ print(
+ f" {r.shareholder:<22} {r.ownership_pct*100:>9.2f}% "
+ f"{fmt(r.proceeds_common):>12} {invested_str:>10} {moic_str:>8}"
+ )
+ print(f"\n Note: Does not model liquidation preferences.")
+ print(f" Participating preferred reduces founder proceeds in most real exits.")
+ print(f" See references/fundraising_playbook.md for full liquidation waterfall.")
+
+
+def print_dilution_summary(rounds: list[RoundResult]) -> None:
+ print(f"\n{'='*70}")
+ print(f" DILUTION SUMMARY — FOUNDER PERSPECTIVE")
+ print(f"{'='*70}")
+
+ # Find all founders (common shareholders who aren't investors or option pool)
+ founder_names = []
+ for entry in rounds[0].cap_table:
+ if entry.share_class == "common" and not entry.is_option_pool:
+ founder_names.append(entry.name)
+
+ if not founder_names:
+ print(" No common shareholders found in initial cap table.")
+ return
+
+ header = f" {'Round':<16}" + "".join(f" {n:<16}" for n in founder_names) + f" {'Total Inv':>12}"
+ print(header)
+ print(" " + "-" * (16 + 18 * len(founder_names) + 14))
+
+ for result in rounds:
+ cap_map = {e.name: e for e in result.cap_table}
+ total_invested = sum(e.invested for e in result.cap_table if not e.is_option_pool)
+ row = f" {result.round_name:<16}"
+ for name in founder_names:
+ pct = cap_map[name].pct_ownership * 100 if name in cap_map else 0
+ row += f" {pct:>6.2f}% "
+ row += f" {fmt(total_invested):>12}"
+ print(row)
+
+
+def export_csv_rounds(rounds: list[RoundResult]) -> str:
+ buf = io.StringIO()
+ writer = csv.writer(buf)
+ writer.writerow(["Round", "Shareholder", "Share Class", "Shares", "Ownership Pct",
+ "Invested", "Pre Money", "Post Money", "Price Per Share"])
+ for r in rounds:
+ for entry in r.cap_table:
+ writer.writerow([
+ r.round_name, entry.name, entry.share_class,
+ round(entry.shares, 0), round(entry.pct_ownership * 100, 4),
+ round(entry.invested, 2), round(r.pre_money_valuation, 0),
+ round(r.post_money_valuation, 0), round(r.price_per_share, 4),
+ ])
+ return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data: typical two-founder Series A/B/C startup
+# ---------------------------------------------------------------------------
+
+def build_sample_model() -> tuple[CapTable, list[RoundResult]]:
+ """
+ Sample company:
+ - 2 founders, started with 10M shares each
+ - 1M shares for early advisor
+ - Raises Pre-seed → Seed → Series A → Series B → Series C
+ """
+ cap = CapTable()
+ SHARES_PER_FOUNDER = 4_000_000
+ SHARES_ADVISOR = 200_000
+
+ # Founding state
+ cap.add_shareholder(Shareholder("Founder A (CEO)", "common", SHARES_PER_FOUNDER))
+ cap.add_shareholder(Shareholder("Founder B (CTO)", "common", SHARES_PER_FOUNDER))
+ cap.add_shareholder(Shareholder("Advisor", "common", SHARES_ADVISOR))
+
+ rounds: list[RoundResult] = []
+ prev_cap = cap.snapshot()
+
+ # Round 1: Pre-seed — $500K at $4.5M pre, 10% option pool created
+ r1 = cap.execute_round(RoundConfig(
+ name="Pre-seed",
+ pre_money_valuation=4_500_000,
+ investment_amount=500_000,
+ new_option_pool_pct=0.10,
+ option_pool_pre_round=True,
+ lead_investor_name="Angel Syndicate",
+ ))
+ rounds.append(r1)
+ prev_r1 = r1.cap_table[:]
+
+ # Round 2: Seed — $2M at $9M pre, expand option pool to 12%
+ r2 = cap.execute_round(RoundConfig(
+ name="Seed",
+ pre_money_valuation=9_000_000,
+ investment_amount=2_000_000,
+ new_option_pool_pct=0.12,
+ option_pool_pre_round=True,
+ lead_investor_name="Seed Fund",
+ ))
+ rounds.append(r2)
+
+ # Round 3: Series A — $12M at $38M pre, refresh option pool to 15%
+ r3 = cap.execute_round(RoundConfig(
+ name="Series A",
+ pre_money_valuation=38_000_000,
+ investment_amount=12_000_000,
+ new_option_pool_pct=0.15,
+ option_pool_pre_round=True,
+ lead_investor_name="Series A Fund",
+ ))
+ rounds.append(r3)
+
+ # Round 4: Series B — $25M at $95M pre, refresh pool to 12%
+ r4 = cap.execute_round(RoundConfig(
+ name="Series B",
+ pre_money_valuation=95_000_000,
+ investment_amount=25_000_000,
+ new_option_pool_pct=0.12,
+ option_pool_pre_round=True,
+ lead_investor_name="Series B Fund",
+ ))
+ rounds.append(r4)
+
+ # Round 5: Series C — $40M at $185M pre, refresh pool to 10%
+ r5 = cap.execute_round(RoundConfig(
+ name="Series C",
+ pre_money_valuation=185_000_000,
+ investment_amount=40_000_000,
+ new_option_pool_pct=0.10,
+ option_pool_pre_round=True,
+ lead_investor_name="Series C Fund",
+ ))
+ rounds.append(r5)
+
+ return cap, rounds
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Fundraising Model — Cap Table & Dilution")
+ parser.add_argument("--exit", type=float, default=250.0,
+ help="Exit valuation in $M for return analysis (default: 250)")
+ parser.add_argument("--csv", action="store_true", help="Export round data as CSV to stdout")
+ args = parser.parse_args()
+
+ exit_valuation = args.exit * 1_000_000
+
+ print("\n" + "="*70)
+ print(" FUNDRAISING MODEL — CAP TABLE & DILUTION ANALYSIS")
+ print(" Sample Company: Two-founder SaaS startup")
+ print(" Pre-seed → Seed → Series A → Series B → Series C")
+ print("="*70)
+
+ cap, rounds = build_sample_model()
+
+ # Print each round
+ prev = None
+ for r in rounds:
+ print_round_result(r, prev)
+ prev = r.cap_table
+
+ # Dilution summary table
+ print_dilution_summary(rounds)
+
+ # Exit analysis at specified valuation
+ exit_results = cap.analyze_exit(exit_valuation)
+ print_exit_analysis(exit_results, exit_valuation)
+
+ # Also print at 2x and 5x for sensitivity
+ print("\n Exit Sensitivity — Founder A Proceeds:")
+ print(f" {'Exit Valuation':<20} {'Founder A %':>12} {'Founder A $':>14} {'MOIC':>8}")
+ print(" " + "-"*56)
+ for mult in [0.5, 1.0, 1.5, 2.0, 3.0, 5.0]:
+ val = rounds[-1].post_money_valuation * mult
+ ex = cap.analyze_exit(val)
+ founder_a = next((r for r in ex if r.shareholder == "Founder A (CEO)"), None)
+ if founder_a:
+ print(f" {fmt(val):<20} {founder_a.ownership_pct*100:>11.2f}% "
+ f"{fmt(founder_a.proceeds_common):>14} {'n/a':>8}")
+
+ print("\n Key Takeaways:")
+ final = rounds[-1].cap_table
+ total = sum(e.shares for e in final)
+ founder_a_final = next((e for e in final if e.name == "Founder A (CEO)"), None)
+ if founder_a_final:
+ print(f" Founder A final ownership: {founder_a_final.pct_ownership*100:.2f}%")
+ total_raised = sum(e.invested for e in final)
+ print(f" Total capital raised: {fmt(total_raised)}")
+ print(f" Total shares outstanding: {total:,.0f}")
+ print(f" Final post-money: {fmt(rounds[-1].post_money_valuation)}")
+ print("\n Run with --exit <$M> to model proceeds at different exit valuations.")
+ print(" Example: python fundraising_model.py --exit 500")
+
+ if args.csv:
+ print("\n\n--- CSV EXPORT ---\n")
+ sys.stdout.write(export_csv_rounds(rounds))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/cfo-advisor/scripts/unit_economics_analyzer.py b/skills/cfo-advisor/scripts/unit_economics_analyzer.py
new file mode 100644
index 00000000..4433f936
--- /dev/null
+++ b/skills/cfo-advisor/scripts/unit_economics_analyzer.py
@@ -0,0 +1,529 @@
+#!/usr/bin/env python3
+"""
+Unit Economics Analyzer
+========================
+Per-cohort LTV, per-channel CAC, payback periods, and LTV:CAC ratios.
+Never blended averages — those hide what's actually happening.
+
+Usage:
+ python unit_economics_analyzer.py
+ python unit_economics_analyzer.py --csv
+
+Stdlib only. No dependencies.
+"""
+
+import argparse
+import csv
+import io
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CohortData:
+ """
+ Revenue data for a group of customers acquired in the same period.
+ Revenue is tracked monthly: revenue[0] = month 1, revenue[1] = month 2, etc.
+ """
+ label: str # e.g. "Q1 2024"
+ acquisition_period: str # human-readable label
+ customers_acquired: int
+ total_cac_spend: float # total S&M spend to acquire this cohort
+ monthly_revenue: list[float] # revenue per month from this cohort
+ gross_margin_pct: float = 0.70 # blended gross margin for this cohort
+
+
+@dataclass
+class ChannelData:
+ """Acquisition cost and customer data for a single channel."""
+ channel: str
+ spend: float
+ customers_acquired: int
+ avg_arpa: float # average revenue per account (monthly)
+ gross_margin_pct: float = 0.70
+ avg_monthly_churn: float = 0.02 # monthly churn rate for customers from this channel
+
+
+@dataclass
+class UnitEconomicsResult:
+ """Computed unit economics for a cohort or channel."""
+ label: str
+ customers: int
+ cac: float
+ arpa: float # average revenue per account per month
+ gross_margin_pct: float
+ monthly_churn: float
+ ltv: float
+ ltv_cac_ratio: float
+ payback_months: float
+ # Cohort-specific
+ m1_revenue: Optional[float] = None
+ m6_revenue: Optional[float] = None
+ m12_revenue: Optional[float] = None
+ m24_revenue: Optional[float] = None
+ m12_ltv: Optional[float] = None # realized LTV through month 12
+ retention_m6: Optional[float] = None # % of M1 revenue retained at M6
+ retention_m12: Optional[float] = None
+
+
+# ---------------------------------------------------------------------------
+# Calculators
+# ---------------------------------------------------------------------------
+
+def calc_ltv(arpa: float, gross_margin_pct: float, monthly_churn: float) -> float:
+ """
+ LTV = (ARPA × Gross Margin) / Monthly Churn Rate
+ Assumes constant churn (simplified; cohort method is more accurate).
+ """
+ if monthly_churn <= 0:
+ return float("inf")
+ return (arpa * gross_margin_pct) / monthly_churn
+
+
+def calc_payback(cac: float, arpa: float, gross_margin_pct: float) -> float:
+ """
+ CAC Payback (months) = CAC / (ARPA × Gross Margin)
+ """
+ denominator = arpa * gross_margin_pct
+ if denominator <= 0:
+ return float("inf")
+ return cac / denominator
+
+
+def analyze_cohort(cohort: CohortData) -> UnitEconomicsResult:
+ """Compute full unit economics for a cohort."""
+ n = cohort.customers_acquired
+ if n == 0:
+ raise ValueError(f"Cohort {cohort.label}: customers_acquired cannot be 0")
+
+ cac = cohort.total_cac_spend / n
+
+ # ARPA from month 1 revenue
+ m1_rev = cohort.monthly_revenue[0] if cohort.monthly_revenue else 0
+ arpa = m1_rev / n if n > 0 else 0
+
+ # Observed monthly churn from cohort data
+ # Use revenue decline from M1 to M12 to estimate churn
+ months_available = len(cohort.monthly_revenue)
+ if months_available >= 12:
+ m12_rev = cohort.monthly_revenue[11]
+ # Revenue retention over 12 months: (M12/M1)^(1/11) per month on average
+ # Implied monthly retention rate
+ if m1_rev > 0 and m12_rev > 0:
+ monthly_retention = (m12_rev / m1_rev) ** (1 / 11)
+ monthly_churn = 1 - monthly_retention
+ else:
+ monthly_churn = 0.02 # default
+ elif months_available >= 6:
+ m6_rev = cohort.monthly_revenue[5]
+ if m1_rev > 0 and m6_rev > 0:
+ monthly_retention = (m6_rev / m1_rev) ** (1 / 5)
+ monthly_churn = 1 - monthly_retention
+ else:
+ monthly_churn = 0.02
+ else:
+ monthly_churn = 0.02 # default if < 6 months data
+
+ # Clamp to reasonable range
+ monthly_churn = max(0.001, min(monthly_churn, 0.30))
+
+ ltv = calc_ltv(arpa, cohort.gross_margin_pct, monthly_churn)
+ payback = calc_payback(cac, arpa, cohort.gross_margin_pct)
+ ltv_cac = ltv / cac if cac > 0 else float("inf")
+
+ # Snapshot revenues
+ def rev_at(month_idx: int) -> Optional[float]:
+ if months_available > month_idx:
+ return cohort.monthly_revenue[month_idx]
+ return None
+
+ m6 = rev_at(5)
+ m12 = rev_at(11)
+ m24 = rev_at(23)
+
+ # Realized LTV through observed months (actual gross profit)
+ m12_ltv = sum(cohort.monthly_revenue[:12]) * cohort.gross_margin_pct if months_available >= 12 else None
+
+ # Retention rates
+ ret_m6 = (m6 / m1_rev) if (m6 is not None and m1_rev > 0) else None
+ ret_m12 = (m12 / m1_rev) if (m12 is not None and m1_rev > 0) else None
+
+ return UnitEconomicsResult(
+ label=cohort.label,
+ customers=n,
+ cac=cac,
+ arpa=arpa,
+ gross_margin_pct=cohort.gross_margin_pct,
+ monthly_churn=monthly_churn,
+ ltv=ltv,
+ ltv_cac_ratio=ltv_cac,
+ payback_months=payback,
+ m1_revenue=m1_rev,
+ m6_revenue=m6,
+ m12_revenue=m12,
+ m24_revenue=m24,
+ m12_ltv=m12_ltv,
+ retention_m6=ret_m6,
+ retention_m12=ret_m12,
+ )
+
+
+def analyze_channel(ch: ChannelData) -> UnitEconomicsResult:
+ """Compute unit economics for an acquisition channel."""
+ if ch.customers_acquired == 0:
+ raise ValueError(f"Channel {ch.channel}: customers_acquired cannot be 0")
+
+ cac = ch.spend / ch.customers_acquired
+ ltv = calc_ltv(ch.avg_arpa, ch.gross_margin_pct, ch.avg_monthly_churn)
+ payback = calc_payback(cac, ch.avg_arpa, ch.gross_margin_pct)
+ ltv_cac = ltv / cac if cac > 0 else float("inf")
+
+ return UnitEconomicsResult(
+ label=ch.channel,
+ customers=ch.customers_acquired,
+ cac=cac,
+ arpa=ch.avg_arpa,
+ gross_margin_pct=ch.gross_margin_pct,
+ monthly_churn=ch.avg_monthly_churn,
+ ltv=ltv,
+ ltv_cac_ratio=ltv_cac,
+ payback_months=payback,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Blended metrics (for comparison)
+# ---------------------------------------------------------------------------
+
+def blended_cac(channels: list[ChannelData]) -> float:
+ total_spend = sum(c.spend for c in channels)
+ total_customers = sum(c.customers_acquired for c in channels)
+ return total_spend / total_customers if total_customers > 0 else 0
+
+
+def blended_ltv(channels: list[ChannelData]) -> float:
+ """Weighted average LTV by customers acquired."""
+ total_customers = sum(c.customers_acquired for c in channels)
+ if total_customers == 0:
+ return 0
+ weighted = sum(
+ calc_ltv(c.avg_arpa, c.gross_margin_pct, c.avg_monthly_churn) * c.customers_acquired
+ for c in channels
+ )
+ return weighted / total_customers
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt(value: float, prefix: str = "$", decimals: int = 0) -> str:
+ if value == float("inf"):
+ return "∞"
+ if abs(value) >= 1_000_000:
+ return f"{prefix}{value/1_000_000:.2f}M"
+ if abs(value) >= 1_000:
+ return f"{prefix}{value/1_000:.1f}K"
+ return f"{prefix}{value:.{decimals}f}"
+
+
+def pct(value: Optional[float]) -> str:
+ if value is None:
+ return "n/a"
+ return f"{value*100:.1f}%"
+
+
+def rating(ltv_cac: float, payback: float) -> str:
+ if ltv_cac == float("inf"):
+ return "∞"
+ if ltv_cac >= 5 and payback <= 12:
+ return "🟢 Excellent"
+ if ltv_cac >= 3 and payback <= 18:
+ return "🟡 Good"
+ if ltv_cac >= 2 and payback <= 24:
+ return "🟠 Marginal"
+ return "🔴 Poor"
+
+
+def print_cohort_analysis(results: list[UnitEconomicsResult]) -> None:
+ print("\n" + "="*80)
+ print(" COHORT ANALYSIS")
+ print("="*80)
+ print(f" {'Cohort':<12} {'Cust':>5} {'CAC':>8} {'ARPA/mo':>9} {'Churn/mo':>10} "
+ f"{'LTV':>10} {'LTV:CAC':>8} {'Payback':>9} {'Ret@M12':>8}")
+ print(" " + "-"*88)
+ for r in results:
+ payback_str = f"{r.payback_months:.1f}mo" if r.payback_months != float("inf") else "∞"
+ ltv_str = fmt(r.ltv) if r.ltv != float("inf") else "∞"
+ ltv_cac_str = f"{r.ltv_cac_ratio:.1f}x" if r.ltv_cac_ratio != float("inf") else "∞"
+ print(
+ f" {r.label:<12} {r.customers:>5} {fmt(r.cac):>8} {fmt(r.arpa):>9} "
+ f"{pct(r.monthly_churn):>10} {ltv_str:>10} {ltv_cac_str:>8} "
+ f"{payback_str:>9} {pct(r.retention_m12):>8}"
+ )
+
+ # Trend analysis
+ print("\n Cohort Trend (is the business getting better or worse?):")
+ if len(results) >= 3:
+ ltv_cac_values = [r.ltv_cac_ratio for r in results if r.ltv_cac_ratio != float("inf")]
+ cac_values = [r.cac for r in results]
+ churn_values = [r.monthly_churn for r in results]
+
+ if len(ltv_cac_values) >= 2:
+ ltv_cac_trend = "↑ Improving" if ltv_cac_values[-1] > ltv_cac_values[0] else "↓ Deteriorating"
+ else:
+ ltv_cac_trend = "n/a"
+
+ cac_trend = "↓ Decreasing (good)" if cac_values[-1] < cac_values[0] else "↑ Increasing"
+ churn_trend = "↓ Improving" if churn_values[-1] < churn_values[0] else "↑ Worsening"
+
+ print(f" LTV:CAC: {ltv_cac_trend}")
+ print(f" CAC: {cac_trend}")
+ print(f" Churn rate: {churn_trend}")
+
+
+def print_channel_analysis(results: list[UnitEconomicsResult], channels: list[ChannelData]) -> None:
+ print("\n" + "="*80)
+ print(" CHANNEL ANALYSIS (Per-Channel vs Blended)")
+ print("="*80)
+ print(f" {'Channel':<22} {'Spend':>9} {'Cust':>5} {'CAC':>8} {'LTV':>10} {'LTV:CAC':>8} {'Payback':>9} {'Rating'}")
+ print(" " + "-"*90)
+ for r, ch in zip(results, channels):
+ payback_str = f"{r.payback_months:.1f}mo" if r.payback_months != float("inf") else "∞"
+ ltv_str = fmt(r.ltv) if r.ltv != float("inf") else "∞"
+ ltv_cac_str = f"{r.ltv_cac_ratio:.1f}x" if r.ltv_cac_ratio != float("inf") else "∞"
+ print(
+ f" {r.label:<22} {fmt(ch.spend):>9} {r.customers:>5} {fmt(r.cac):>8} "
+ f"{ltv_str:>10} {ltv_cac_str:>8} {payback_str:>9} {rating(r.ltv_cac_ratio, r.payback_months)}"
+ )
+
+ # Blended comparison
+ b_cac = blended_cac(channels)
+ b_ltv = blended_ltv(channels)
+ b_ltv_cac = b_ltv / b_cac if b_cac > 0 else 0
+ total_spend = sum(c.spend for c in channels)
+ total_customers = sum(c.customers_acquired for c in channels)
+ avg_payback = sum(
+ calc_payback(b_cac, c.avg_arpa, c.gross_margin_pct) * c.customers_acquired
+ for c in channels
+ ) / total_customers
+
+ print(" " + "-"*90)
+ print(
+ f" {'BLENDED (dangerous)':<22} {fmt(total_spend):>9} {total_customers:>5} "
+ f"{fmt(b_cac):>8} {fmt(b_ltv):>10} {b_ltv_cac:.1f}x{'':<7} "
+ f"{avg_payback:.1f}mo{'':<4} {rating(b_ltv_cac, avg_payback)}"
+ )
+ print("\n ⚠️ Blended numbers hide channel-level problems. Manage channels individually.")
+
+ # Budget reallocation
+ print("\n Recommended Budget Reallocation:")
+ sorted_results = sorted(zip(results, channels), key=lambda x: x[0].ltv_cac_ratio, reverse=True)
+ for r, ch in sorted_results:
+ if r.ltv_cac_ratio >= 3:
+ action = "✅ Scale"
+ elif r.ltv_cac_ratio >= 2:
+ action = "🔄 Optimize"
+ else:
+ action = "❌ Cut / pause"
+ print(f" {ch.channel:<22} LTV:CAC = {r.ltv_cac_ratio:.1f}x → {action}")
+
+
+def export_csv_results(cohort_results: list[UnitEconomicsResult], channel_results: list[UnitEconomicsResult]) -> str:
+ buf = io.StringIO()
+ writer = csv.writer(buf)
+ writer.writerow(["Type", "Label", "Customers", "CAC", "ARPA_Monthly", "Gross_Margin_Pct",
+ "Monthly_Churn", "LTV", "LTV_CAC_Ratio", "Payback_Months",
+ "Retention_M6", "Retention_M12"])
+ for r in cohort_results:
+ writer.writerow(["cohort", r.label, r.customers, round(r.cac, 2), round(r.arpa, 2),
+ r.gross_margin_pct, round(r.monthly_churn, 4),
+ round(r.ltv, 2) if r.ltv != float("inf") else "inf",
+ round(r.ltv_cac_ratio, 2) if r.ltv_cac_ratio != float("inf") else "inf",
+ round(r.payback_months, 2) if r.payback_months != float("inf") else "inf",
+ round(r.retention_m6, 3) if r.retention_m6 else "",
+ round(r.retention_m12, 3) if r.retention_m12 else ""])
+ for r in channel_results:
+ writer.writerow(["channel", r.label, r.customers, round(r.cac, 2), round(r.arpa, 2),
+ r.gross_margin_pct, round(r.monthly_churn, 4),
+ round(r.ltv, 2) if r.ltv != float("inf") else "inf",
+ round(r.ltv_cac_ratio, 2) if r.ltv_cac_ratio != float("inf") else "inf",
+ round(r.payback_months, 2) if r.payback_months != float("inf") else "inf",
+ "", ""])
+ return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def make_sample_cohorts() -> list[CohortData]:
+ """
+ Series A SaaS company, 8 quarters of cohort data.
+ Shows a business improving on all dimensions over time.
+ """
+ return [
+ CohortData(
+ label="Q1 2023", acquisition_period="Jan-Mar 2023",
+ customers_acquired=12, total_cac_spend=54_000,
+ gross_margin_pct=0.68,
+ monthly_revenue=[
+ 10_200, 9_600, 9_100, 8_700, 8_300, 8_000, # M1-M6
+ 7_800, 7_600, 7_400, 7_200, 7_000, 6_800, # M7-M12
+ 6_700, 6_600, 6_500, 6_400, 6_300, 6_200, # M13-M18
+ 6_100, 6_000, 5_900, 5_800, 5_700, 5_600, # M19-M24
+ ],
+ ),
+ CohortData(
+ label="Q2 2023", acquisition_period="Apr-Jun 2023",
+ customers_acquired=15, total_cac_spend=60_000,
+ gross_margin_pct=0.69,
+ monthly_revenue=[
+ 13_500, 12_900, 12_500, 12_100, 11_800, 11_500,
+ 11_300, 11_100, 10_900, 10_700, 10_500, 10_300,
+ 10_200, 10_100, 10_000, 9_900, 9_800, 9_700,
+ ],
+ ),
+ CohortData(
+ label="Q3 2023", acquisition_period="Jul-Sep 2023",
+ customers_acquired=18, total_cac_spend=63_000,
+ gross_margin_pct=0.70,
+ monthly_revenue=[
+ 16_200, 15_800, 15_400, 15_100, 14_800, 14_600,
+ 14_400, 14_200, 14_000, 13_900, 13_800, 13_700,
+ 13_600, 13_500, 13_400, 13_300,
+ ],
+ ),
+ CohortData(
+ label="Q4 2023", acquisition_period="Oct-Dec 2023",
+ customers_acquired=22, total_cac_spend=70_400,
+ gross_margin_pct=0.71,
+ monthly_revenue=[
+ 20_900, 20_500, 20_200, 19_900, 19_700, 19_500,
+ 19_300, 19_100, 19_000, 18_900, 18_800, 18_700,
+ ],
+ ),
+ CohortData(
+ label="Q1 2024", acquisition_period="Jan-Mar 2024",
+ customers_acquired=28, total_cac_spend=81_200,
+ gross_margin_pct=0.72,
+ monthly_revenue=[
+ 27_200, 26_900, 26_600, 26_400, 26_200, 26_000,
+ 25_800, 25_700, 25_600, 25_500,
+ ],
+ ),
+ CohortData(
+ label="Q2 2024", acquisition_period="Apr-Jun 2024",
+ customers_acquired=34, total_cac_spend=91_800,
+ gross_margin_pct=0.72,
+ monthly_revenue=[
+ 33_300, 33_000, 32_800, 32_600, 32_400, 32_200,
+ ],
+ ),
+ CohortData(
+ label="Q3 2024", acquisition_period="Jul-Sep 2024",
+ customers_acquired=40, total_cac_spend=100_000,
+ gross_margin_pct=0.73,
+ monthly_revenue=[
+ 39_600, 39_400, 39_200,
+ ],
+ ),
+ CohortData(
+ label="Q4 2024", acquisition_period="Oct-Dec 2024",
+ customers_acquired=47, total_cac_spend=112_800,
+ gross_margin_pct=0.73,
+ monthly_revenue=[
+ 47_000,
+ ],
+ ),
+ ]
+
+
+def make_sample_channels() -> list[ChannelData]:
+ """
+ Q4 2024 channel breakdown. Blended looks fine; per-channel reveals problems.
+ """
+ return [
+ ChannelData("Organic / SEO", spend=9_500, customers_acquired=14, avg_arpa=950, gross_margin_pct=0.73, avg_monthly_churn=0.015),
+ ChannelData("Paid Search (SEM)", spend=48_000, customers_acquired=18, avg_arpa=980, gross_margin_pct=0.73, avg_monthly_churn=0.020),
+ ChannelData("Paid Social", spend=32_000, customers_acquired=8, avg_arpa=900, gross_margin_pct=0.72, avg_monthly_churn=0.025),
+ ChannelData("Content / Inbound", spend=11_000, customers_acquired=6, avg_arpa=1100, gross_margin_pct=0.74, avg_monthly_churn=0.012),
+ ChannelData("Outbound SDR", spend=22_000, customers_acquired=4, avg_arpa=1200, gross_margin_pct=0.73, avg_monthly_churn=0.022),
+ ChannelData("Events / Webinars", spend=18_500, customers_acquired=3, avg_arpa=1050, gross_margin_pct=0.72, avg_monthly_churn=0.028),
+ ChannelData("Partner / Referral", spend=7_800, customers_acquired=7, avg_arpa=1000, gross_margin_pct=0.73, avg_monthly_churn=0.013),
+ ]
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Unit Economics Analyzer")
+ parser.add_argument("--csv", action="store_true", help="Export results as CSV to stdout")
+ args = parser.parse_args()
+
+ cohorts = make_sample_cohorts()
+ channels = make_sample_channels()
+
+ print("\n" + "="*80)
+ print(" UNIT ECONOMICS ANALYZER")
+ print(" Sample Company: Series A SaaS | Q4 2024 Snapshot")
+ print(" Gross Margin: ~72% | Monthly Churn: derived from cohort data")
+ print("="*80)
+
+ cohort_results = [analyze_cohort(c) for c in cohorts]
+ channel_results = [analyze_channel(c) for c in channels]
+
+ print_cohort_analysis(cohort_results)
+ print_channel_analysis(channel_results, channels)
+
+ # Health summary
+ print("\n" + "="*80)
+ print(" HEALTH SUMMARY")
+ print("="*80)
+ latest = cohort_results[-1]
+ prev = cohort_results[-4] if len(cohort_results) >= 4 else cohort_results[0]
+
+ print(f"\n Latest Cohort ({latest.label}):")
+ print(f" CAC: {fmt(latest.cac)}")
+ ltv_str = fmt(latest.ltv) if latest.ltv != float("inf") else "∞"
+ ltv_cac_str = f"{latest.ltv_cac_ratio:.1f}x" if latest.ltv_cac_ratio != float("inf") else "∞"
+ payback_str = f"{latest.payback_months:.1f} months" if latest.payback_months != float("inf") else "∞"
+ print(f" LTV: {ltv_str}")
+ print(f" LTV:CAC: {ltv_cac_str} (target: > 3x)")
+ print(f" CAC Payback: {payback_str} (target: < 18mo)")
+ print(f" Rating: {rating(latest.ltv_cac_ratio, latest.payback_months)}")
+
+ # Trend vs 4 quarters ago
+ print(f"\n Trend vs {prev.label}:")
+ cac_delta = (latest.cac - prev.cac) / prev.cac * 100
+ ltv_delta_str = "n/a"
+ if latest.ltv != float("inf") and prev.ltv != float("inf"):
+ ltv_delta = (latest.ltv - prev.ltv) / prev.ltv * 100
+ ltv_delta_str = f"{ltv_delta:+.1f}%"
+ cac_str = "↓ Better" if cac_delta < 0 else "↑ Worse"
+ print(f" CAC: {cac_delta:+.1f}% ({cac_str})")
+ print(f" LTV: {ltv_delta_str}")
+
+ print("\n Benchmark Reference:")
+ print(" LTV:CAC > 5x → Scale aggressively")
+ print(" LTV:CAC 3-5x → Healthy; grow at current pace")
+ print(" LTV:CAC 2-3x → Marginal; optimize before scaling")
+ print(" LTV:CAC < 2x → Acquiring unprofitably; stop and fix")
+ print(" Payback < 12mo → Outstanding capital efficiency")
+ print(" Payback 12-18mo → Good for B2B SaaS")
+ print(" Payback > 24mo → Requires long-dated capital to scale")
+
+ if args.csv:
+ print("\n\n--- CSV EXPORT ---\n")
+ sys.stdout.write(export_csv_results(cohort_results, channel_results))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/change-management/SKILL.md b/skills/change-management/SKILL.md
new file mode 100644
index 00000000..9cc3de34
--- /dev/null
+++ b/skills/change-management/SKILL.md
@@ -0,0 +1,253 @@
+---
+name: "change-management"
+description: "Framework for rolling out organizational changes without chaos. Covers the ADKAR model adapted for startups, communication templates, resistance patterns, and change fatigue management. Handles process changes, org restructures, strategy pivots, and culture changes. Use when announcing a reorg, switching tools, pivoting strategy, killing a product, changing leadership, or when user mentions change management, change rollout, managing resistance, org change, reorg, or pivot communication."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: change-management
+ updated: 2026-03-05
+ frameworks: change-playbook
+---
+
+# Change Management Playbook
+
+Most changes fail at implementation, not design. The ADKAR model tells you why and how to fix it.
+
+## Keywords
+change management, ADKAR, organizational change, reorg, process change, tool migration, strategy pivot, change resistance, change fatigue, change communication, stakeholder management, adoption, compliance, change rollout, transition
+
+## Core Model: ADKAR Adapted for Startups
+
+ADKAR is a change management model by Prosci. Original version is for enterprises. This is the startup-speed adaptation.
+
+### A — Awareness
+
+**What it is:** People understand WHY the change is happening — the business reason, not just the announcement.
+
+**The mistake:** Communicating the WHAT before the WHY. "We're moving to a new CRM" before "here's why our current process is killing us."
+
+**What people need to hear:**
+- What is the problem we're solving? (Be honest. If it's "we need to cut costs," say that.)
+- Why now? What would happen if we didn't change?
+- Who made this decision and how?
+
+**Startup shortcut:** A 5-minute video from the CEO or decision-maker explaining the "why" in plain language beats a formal change announcement document every time.
+
+---
+
+### D — Desire
+
+**What it is:** People want to make the change happen — or at least don't actively resist it.
+
+**The mistake:** Assuming communication creates desire. Awareness ≠ desire. People can understand a change and still hate it.
+
+**What creates desire:**
+- "What's in it for me?" — answer this for each stakeholder group, honestly
+- Involving people in the "how" even if the "what" is decided
+- Addressing fears directly: "Some people are worried this means their role is changing. Here's the truth: [honest answer]"
+
+**What destroys desire:**
+- Pretending the change is better for everyone than it is
+- Ignoring the legitimate losses people will experience
+- Making announcements without any consultation
+
+**Startup shortcut:** Run a short "concerns and questions" session within 48 hours of announcement. Not to reverse the decision — to address the fears and show you're listening.
+
+---
+
+### K — Knowledge
+
+**What it is:** People know HOW to operate in the new world — the specific skills, behaviors, and processes.
+
+**The mistake:** Announcing the change and assuming people will figure it out.
+
+**What people need:**
+- Step-by-step documentation of new processes
+- Training or practice sessions before go-live
+- Clear answers to "what do I do when [common scenario]?"
+- Who to ask when they're stuck
+
+**Types of knowledge transfer:**
+| Method | Best for | When |
+|--------|---------|------|
+| Live training | Skill-based changes, complex tools | Before go-live |
+| Documentation | Process changes, reference material | Always |
+| Video walkthroughs | Tool migrations | Available 24/7, self-paced |
+| Shadowing / peer learning | Behavior changes | Weeks 2–4 after launch |
+| Office hours | Any change with many edge cases | First 4–6 weeks |
+
+---
+
+### A — Ability
+
+**What it is:** People have the time, tools, and support to actually do things differently.
+
+**The mistake:** "We've trained everyone" ≠ "everyone can now do it." Training is knowledge. Ability is practice.
+
+**What creates ability:**
+- Time to practice before being evaluated
+- A safe environment to make mistakes (no public shaming for early struggles)
+- Reduced load during transition (if you're asking people to learn new skills, don't simultaneously pile on new work)
+- Access to help (a Slack channel, a point person, documentation)
+
+**Signs of ability gap:**
+- People revert to old behavior under pressure
+- Workarounds emerge (people invent their own way around the new system)
+- Training scores are high but actual behavior hasn't changed
+
+---
+
+### R — Reinforcement
+
+**What it is:** The change sticks. The new behavior becomes the default.
+
+**The mistake:** Declaring victory at go-live. Changes fail because they're never reinforced.
+
+**What creates reinforcement:**
+- Visible measurement (are we tracking adoption?)
+- Recognition of early adopters ("Sarah fully migrated to the new workflow in week 2 — ask her how")
+- Leader modeling (if the CEO uses the old way, everyone will)
+- Removing the old option (when possible — eliminate the path of least resistance)
+- Consequences for non-adoption (stated clearly, applied consistently)
+
+**Adoption vs. compliance:**
+- **Compliance:** People do it when watched, revert when not
+- **Adoption:** People do it because they believe it's better
+
+Only reinforcement creates adoption. Compliance is the result of enforcement. Aim for adoption.
+
+---
+
+## Change Types and ADKAR Application
+
+### Process Change (new tools, new workflows)
+
+**Timeline:** 4–8 weeks for full adoption
+**Hardest phase:** Ability (people know what to do but haven't built the habit)
+**Critical reinforcement:** Remove or deprecate the old tool/process
+
+**Communication sequence:**
+1. Week -2: Announce the why + go-live date
+2. Week -1: Training sessions available
+3. Week 0 (go-live): Launch + point person available
+4. Week 2: Adoption check-in (who's using it? Who isn't?)
+5. Week 4: Feedback collection + public wins
+6. Week 8: Old system deprecated
+
+---
+
+### Org Change (reorg, new leader, team splits/merges)
+
+**Timeline:** 3–6 months for full stabilization
+**Hardest phase:** Desire (people fear for their roles and relationships)
+**Critical reinforcement:** Consistent behavior from new leadership
+
+**Communication sequence:**
+1. Day 0: Announce the change with the "why" — in person or synchronous video
+2. Day 1: 1:1s with most affected team members by their manager
+3. Week 1: FAQ published with honest answers to the 10 most common concerns
+4. Week 2–4: New structure is operating (don't delay implementation)
+5. Month 2: First retrospective — what's working, what needs adjustment
+6. Month 3–6: Regular check-ins on team health and morale
+
+**What to say when a leader is leaving or being replaced:**
+Be honest about what you can share. Never: "We can't share the reasons." Always: either a truthful explanation or "we're not able to share the specifics, but I can tell you [what this means for you]."
+
+---
+
+### Strategy Pivot (new direction, killed products)
+
+**Timeline:** 3–12 months for full alignment
+**Hardest phase:** Awareness (people don't believe the pivot is real)
+**Critical reinforcement:** Resource reallocation that visibly proves the pivot is happening
+
+**Communication sequence:**
+1. Internal first, always. Employees should never hear about a pivot from a press release.
+2. All-hands with full context: what changed in the market, what you're doing, what it means for teams
+3. Each team leader runs a "what does this mean for us?" conversation with their team
+4. Resource reallocation announced within 2 weeks (if the money doesn't move, people won't believe the pivot)
+5. First milestone of the new direction celebrated publicly
+
+**What kills pivots:** Announcing a new direction while still funding the old one at the same level.
+
+---
+
+### Culture Change (values refresh, behavior expectations)
+
+**Timeline:** 12–24 months for genuine behavior change
+**Hardest phase:** Reinforcement (behavior doesn't change just because values were announced)
+**Critical reinforcement:** Visible decisions that reflect the new values
+
+**Communication sequence:**
+1. Build with input: involve a representative sample of the company in defining the change
+2. Announce with story: "Here's what we observed, here's what we're changing and why"
+3. Behavior anchors: for each culture change, state the specific behavior in observable terms
+4. Leader behavior: leadership team must visibly model the new behavior first
+5. Performance integration: new expected behaviors appear in reviews within one cycle
+6. Celebrate the right behaviors: when someone exemplifies the new culture, name it publicly
+
+---
+
+## Resistance Patterns
+
+Resistance is information, not defiance. Diagnose before responding.
+
+| Resistance pattern | What it signals | Response |
+|-------------------|-----------------|---------|
+| "This won't work" | Awareness gap or credibility gap | Explain the evidence base for the change |
+| "Why now?" | Awareness gap | Explain urgency — what happens if we don't change |
+| "I wasn't consulted" | Desire gap | Acknowledge the gap; involve them in the "how" now |
+| "I don't have time for this" | Ability gap | Reduce their load or push the timeline |
+| "We tried this before" | Trust gap | Acknowledge what's different this time. Be specific. |
+| Silent non-compliance | Could be any gap | 1:1 conversation to diagnose |
+
+**The worst response to resistance:** Dismissing it. "Some people are resistant to change" as if resistance is a personality flaw rather than a signal.
+
+---
+
+## Change Fatigue
+
+When organizations change too fast, people stop believing any change will stick.
+
+### Signals
+- Eye-rolls during change announcements ("here we go again")
+- Low attendance at change-related sessions
+- Fast compliance on paper, slow adoption in practice
+- "Last month we were doing X, now we're doing Y" comments
+
+### Prevention
+- **Finish what you start.** Don't announce a new change while the last one is still being absorbed.
+- **Space changes.** One significant change at a time. Give 2–3 months of stability between major changes.
+- **Announce what's NOT changing.** People in change-fatigue need to know what's stable.
+- **Show results.** Publish what the previous change achieved before launching the next.
+
+### When you're already in change fatigue
+- Pause non-critical changes
+- Run a "change inventory": how many changes are in progress simultaneously?
+- Prioritize ruthlessly: which changes are essential now? Which can wait?
+- Communicate stability: "Here's what is NOT changing this quarter"
+
+---
+
+## Key Questions for Change Management
+
+- "Who are the most skeptical people about this change? Have we talked to them directly?"
+- "Do people understand why we're doing this, or just what we're doing?"
+- "Have we given people time to practice before we measure performance on the new way?"
+- "Is the old way still available? If so, people will use it."
+- "Are leaders modeling the new behavior themselves?"
+- "How many changes are we running simultaneously right now?"
+
+## Red Flags
+
+- Change announced on Friday afternoon (people stew over the weekend)
+- "This is final, questions are not welcome" framing
+- No published FAQ or way to ask questions safely
+- Old system/process still running 6 weeks after "go-live"
+- Leaders exempted from the change they're asking everyone else to make
+- No measurement of adoption — assuming go-live = success
+
+## Detailed References
+- `references/change-playbook.md` — ADKAR deep dive, resistance counter-strategies, communication templates, change fatigue management
diff --git a/skills/change-management/_meta.json b/skills/change-management/_meta.json
new file mode 100644
index 00000000..b2e9121b
--- /dev/null
+++ b/skills/change-management/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "change-management",
+ "displayName": "Change Management",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773171104412,
+ "commit": "https://github.com/openclaw/skills/commit/4e90d5636cebb63e2373927ebeb6957af493c820"
+ },
+ "history": [
+ {
+ "version": "1.0.0",
+ "publishedAt": 1772755302029,
+ "commit": "https://github.com/openclaw/skills/commit/20d379a3c435ff49d44d0ac0837fc796760bdbd5"
+ }
+ ]
+}
diff --git a/skills/change-management/references/change-playbook.md b/skills/change-management/references/change-playbook.md
new file mode 100644
index 00000000..06d8f8d3
--- /dev/null
+++ b/skills/change-management/references/change-playbook.md
@@ -0,0 +1,308 @@
+# Change Management Playbook
+
+Deep reference for rolling out organizational changes effectively.
+
+---
+
+## 1. ADKAR Deep Dive with Startup Examples
+
+### Awareness: The "Why" that actually lands
+
+Most change communications fail at awareness because they confuse informing with explaining.
+
+**Informing:** "We're moving from Jira to Linear next month."
+**Explaining:** "Our engineering team loses ~4 hours per week to Jira configuration, search latency, and reporting setup. At our current team size, that's 60+ hours per month. Linear's benchmarks from teams our size show a 40% reduction in that overhead. That's why we're switching — and here's the timeline."
+
+The explanation activates desire. The announcement just creates work.
+
+**Real example: Tool migration**
+> "We tried Asana, we tried Notion tasks, we tried spreadsheets. None of them stuck. After talking to 8 engineering leads at similar companies, the pattern was clear: teams that use Linear stick with it. We're going all-in. Here's why it will be different this time: [specific reasons]."
+
+**Real example: Reorg**
+> "The current structure has our customer success team reporting to Sales, which creates a conflict: Sales is measured on new logo count, CS is measured on retention. We've seen this play out in three recent customer losses where CS needed to raise concerns but felt the pressure to stay quiet. We're changing the reporting structure so CS reports directly to me. This is about removing a structural conflict, not about performance."
+
+---
+
+### Desire: Addressing the "What's in it for me?"
+
+Every stakeholder group needs a different answer.
+
+**Individual contributor:**
+- "Will my job change significantly?"
+- "Will this make my day easier or harder?"
+- "Is my role at risk?"
+
+**Manager:**
+- "What new responsibilities do I take on?"
+- "How do I explain this to my team?"
+- "What happens if someone on my team doesn't adapt?"
+
+**Senior leader:**
+- "What does this change our strategic posture?"
+- "What resources are reallocated and to what?"
+- "How does this affect my relationships with other senior leaders?"
+
+**Resistance scenario: Senior leader whose team is most affected**
+> They're supportive in the room, silent or undermining outside it.
+> Fix: Give them a role in the change. Make them a named co-leader of the implementation. Invested people don't undermine.
+
+---
+
+### Knowledge: The documentation that actually gets used
+
+The reason most change documentation fails: it's written for the decision-maker, not the user.
+
+**Documentation that gets used:**
+- Short (< 2 pages for most changes)
+- Organized by role: "If you're in Sales, here's what changes for you"
+- Answers "what do I do when X happens?" with specific answers
+- Has a clear owner: "Questions? Ask [person] in #channel"
+
+**Documentation that doesn't get used:**
+- Long rationale sections the user doesn't need
+- "See the full policy document for details"
+- No named point of contact
+- Buried in email threads
+
+---
+
+### Ability: The gap between knowing and doing
+
+Signs of a knowledge gap vs. an ability gap:
+
+| Symptom | Knowledge gap | Ability gap |
+|---------|-------------|------------|
+| People don't know what to do | ✅ | |
+| People know what to do but don't do it | | ✅ |
+| People do it wrong consistently | Could be either | |
+| People revert under pressure | | ✅ |
+| Training scores high, behavior unchanged | | ✅ |
+
+**Ability gaps are fixed by:**
+1. Practice time (before being measured)
+2. Reduced cognitive load during transition
+3. Peer support (not just manager support)
+4. Feedback loops that are fast and low-stakes
+
+**What kills ability development:**
+- Measuring performance on the new way in week 1
+- Adding new work simultaneously with the change
+- Making it embarrassing to ask for help
+
+---
+
+### Reinforcement: The phase everyone skips
+
+Go-live is not success. Go-live is the beginning of adoption.
+
+**Reinforcement calendar (template):**
+
+| Week | Action |
+|------|--------|
+| Week 1 (go-live) | High-visibility support. Leadership visible. Point person responsive. |
+| Week 2 | First adoption check: who's using it? Who isn't? Targeted help to laggards. |
+| Week 4 | Celebrate early adopters publicly. Share a win story. |
+| Week 6 | Adoption metric reported to leadership. Decommission old way (if applicable). |
+| Week 8 | Full adoption expected. Non-adoption now a performance conversation. |
+| Month 3 | Retrospective: What's working? What needs adjustment? |
+
+---
+
+## 2. Resistance Patterns and Counter-Strategies
+
+### The Vocal Skeptic
+
+**Who they are:** Asks hard questions in all-hands. Other people follow their lead.
+**What they need:** To feel heard and to understand the logic.
+**Strategy:** Talk to them before the all-hands. Not to persuade them — to hear their concerns and address what's valid. When they feel respected, they often become your best change advocates.
+
+**Script:** "I know you have concerns about this change. I want to understand them before we go broader with the announcement. What's your biggest worry?"
+
+---
+
+### The Silent Non-Complier
+
+**Who they are:** Agrees in meetings, continues the old behavior outside.
+**What they need:** To understand that non-compliance is visible and has consequences.
+**Strategy:** Direct 1:1 conversation. Name the behavior. Ask what's in the way. Give them a clear path.
+
+**Script:** "I've noticed you're still using [old way] two weeks after we launched [new way]. I want to understand what's in the way for you — is it a knowledge issue, a time issue, or something else?"
+
+---
+
+### The Grieving Top Performer
+
+**Who they are:** Was excellent under the old system. The change makes their skills less relevant.
+**What they need:** Recognition of their past contribution and a clear path forward.
+**Strategy:** Name the loss explicitly. "I know you built your expertise on [old approach] and this change asks you to develop a new one. That's a real transition." Then create a specific development plan.
+
+**What not to do:** Pretend the change doesn't affect them disproportionately.
+
+---
+
+### The Fearful Middle Manager
+
+**Who they are:** Middle managers whose authority or role scope is reduced by the change.
+**What they need:** A clear picture of their new role and why it's still valuable.
+**Strategy:** Individual conversation before the announcement. Walk them through what changes, what stays the same, and what their contribution looks like in the new world.
+
+---
+
+### The "We've Been Here Before" Cynics
+
+**Who they are:** Long-tenured employees who've seen multiple failed change initiatives.
+**What they need:** Evidence that this time is different.
+**Strategy:** Acknowledge the history. "I know we've announced changes that didn't stick. Here's specifically what's different this time: [specific differences]." Then prove it fast — show momentum in the first 30 days.
+
+---
+
+## 3. Communication Plan Template per Change Type
+
+### Template: Tool Migration
+
+```
+COMMUNICATION PLAN — [Tool Name] Migration
+
+AUDIENCE: All-hands / [specific team]
+DECISION OWNER: [Name]
+GO-LIVE DATE: [Date]
+POINT OF CONTACT: [Name] in [channel]
+
+COMMUNICATION TIMELINE:
+Week -4: Decision finalized (internal only)
+Week -3: Training materials ready
+Week -2: All-hands announcement (why + timeline + support plan)
+Week -1: Training sessions (2 sessions, different times)
+Week 0: Go-live. Point person in Slack. Old system still accessible.
+Week 2: First adoption check. Targeted help to non-adopters.
+Week 4: Old system access restricted.
+Week 8: Old system fully decommissioned.
+
+KEY MESSAGES:
+- Why we're switching: [honest 2-sentence reason]
+- What changes for you: [role-specific, max 3 bullets]
+- What doesn't change: [this matters for change fatigue]
+- How to get help: [channel, person, office hours]
+- Timeline: [specific dates]
+
+FAQ:
+Q: Is the old system going away completely?
+A: [Honest answer with date]
+Q: What if I have data in the old system?
+A: [Migration plan or acknowledgment]
+Q: What if I'm not proficient by go-live?
+A: [Realistic expectation-setting]
+```
+
+### Template: Reorg Announcement
+
+```
+REORG COMMUNICATION PLAN
+
+ANNOUNCEMENT DATE: [Date]
+EFFECTIVE DATE: [Date]
+FORMAT: Live (synchronous), all affected employees
+
+PRE-ANNOUNCEMENT (1 week before):
+- 1:1 with every affected leader
+- HR briefed and ready for questions
+- FAQ prepared
+
+ANNOUNCEMENT FORMAT:
+1. Context: Why this change? (2-3 minutes)
+2. What's changing: New structure, new reporting lines (3-4 minutes)
+3. What's NOT changing: Roles, comp, team members (2 minutes)
+4. Timeline: When does the new structure take effect? (1 minute)
+5. Q&A: Open, no time limit (at least 15 minutes)
+
+POST-ANNOUNCEMENT (week 1):
+- Each manager runs team meeting to answer team-specific questions
+- HR available for private conversations
+- FAQ published to all
+
+POST-ANNOUNCEMENT (week 2-4):
+- New structure is operational
+- Transition check-in: what questions emerged that weren't anticipated?
+
+THINGS NOT TO SAY:
+- "We can't share why [person] is leaving" (if they are)
+- "This affects everyone equally" (it doesn't)
+- "No one's job is at risk" (unless this is 100% certain)
+```
+
+---
+
+## 4. The Change Fatigue Problem
+
+### How organizations develop change fatigue
+
+**Phase 1 — Excitement (first 1-2 changes):** People engage, try the new way, hope it sticks.
+
+**Phase 2 — Skepticism (3-5 changes):** People comply but hedge. "Let's see if this one lasts."
+
+**Phase 3 — Detachment (6+ changes without completion):** People stop investing in changes. Compliance is surface-level. New announcements get eye-rolls.
+
+**Phase 4 — Cynicism (entrenched fatigue):** People actively resist changes. "We've been here before." High performers leave because they don't want to work in a chaotic environment.
+
+### The change inventory audit
+
+**Run this before announcing any new change:**
+
+| Change | Status | Started | Expected complete |
+|--------|--------|---------|-----------------|
+| [Change 1] | In progress / Complete / Stalled | | |
+| [Change 2] | | | |
+| [Change 3] | | | |
+
+**Rules:**
+- If > 2 significant changes are in progress, don't start a third
+- If any change is stalled, diagnose it before starting something new
+- Define "complete" for every change in progress
+
+### Recovery from change fatigue
+
+1. **Declare a change moratorium.** "We're not starting anything new for 60 days. We're finishing what we started."
+2. **Complete visible wins.** Ship the changes that are 80% done. Demonstrate follow-through.
+3. **Communicate stability.** "Here's what is NOT changing this year."
+4. **Slow down the next announcement.** More preparation, more consultation, clearer "this time is different" evidence.
+
+---
+
+## 5. Measuring Adoption vs. Compliance
+
+Most change leaders measure go-live, not adoption. These are different things.
+
+### Adoption metrics by change type
+
+**Tool migration:**
+- % of team actively using the new tool (not just logged in)
+- % of relevant workflows completed in new tool vs. old tool
+- Support ticket volume in weeks 1-4 (high = knowledge gap; dropping = adoption)
+
+**Process change:**
+- % of relevant transactions following new process
+- Error rates in new process vs. old process (should converge over time)
+- Time-to-complete for new process (should improve by week 4)
+
+**Org change:**
+- Decision cycle time in new structure (should improve by month 2)
+- Escalation patterns (fewer cross-boundary escalations = alignment improving)
+- Employee sentiment (survey at months 1, 3, 6)
+
+**Culture change:**
+- Values referenced in 1:1 conversations (manager self-report)
+- Values-linked recognition events per month
+- Culture survey scores in relevant dimensions (quarterly)
+
+### The compliance trap
+
+Measuring compliance: "Did they use the new system? Yes/No."
+Measuring adoption: "Did they use the new system because it's better, or because they had to?"
+
+Compliance is unstable. It reverts when enforcement loosens. Adoption is self-sustaining.
+
+**Adoption diagnostic:** Ask a random sample: "Why do you use [new way] instead of [old way]?"
+- "Because I have to" = compliance
+- "Because it's faster/easier/better" = adoption
+
+Only adoption makes the change permanent.
diff --git a/skills/changelog-generator/README.md b/skills/changelog-generator/README.md
new file mode 100644
index 00000000..4b91dc25
--- /dev/null
+++ b/skills/changelog-generator/README.md
@@ -0,0 +1,48 @@
+# Changelog Generator
+
+Automates release notes from Conventional Commits with Keep a Changelog output and strict commit linting. Designed for CI-friendly release workflows.
+
+## Quick Start
+
+```bash
+# Generate entry from git range
+python3 scripts/generate_changelog.py \
+ --from-tag v1.2.0 \
+ --to-tag v1.3.0 \
+ --next-version v1.3.0 \
+ --format markdown
+
+# Lint commit subjects
+python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict --format text
+```
+
+## Included Tools
+
+- `scripts/generate_changelog.py`: parse commits, infer semver bump, render markdown/JSON, optional file prepend
+- `scripts/commit_linter.py`: validate commit subjects against Conventional Commits rules
+
+## References
+
+- `references/ci-integration.md`
+- `references/changelog-formatting-guide.md`
+- `references/monorepo-strategy.md`
+
+## Installation
+
+### Claude Code
+
+```bash
+cp -R engineering/changelog-generator ~/.claude/skills/changelog-generator
+```
+
+### OpenAI Codex
+
+```bash
+cp -R engineering/changelog-generator ~/.codex/skills/changelog-generator
+```
+
+### OpenClaw
+
+```bash
+cp -R engineering/changelog-generator ~/.openclaw/skills/changelog-generator
+```
diff --git a/skills/changelog-generator/SKILL.md b/skills/changelog-generator/SKILL.md
new file mode 100644
index 00000000..28d6116e
--- /dev/null
+++ b/skills/changelog-generator/SKILL.md
@@ -0,0 +1,165 @@
+---
+name: "changelog-generator"
+description: "Changelog Generator"
+---
+
+# Changelog Generator
+
+**Tier:** POWERFUL
+**Category:** Engineering
+**Domain:** Release Management / Documentation
+
+## Overview
+
+Use this skill to produce consistent, auditable release notes from Conventional Commits. It separates commit parsing, semantic bump logic, and changelog rendering so teams can automate releases without losing editorial control.
+
+## Core Capabilities
+
+- Parse commit messages using Conventional Commit rules
+- Detect semantic bump (`major`, `minor`, `patch`) from commit stream
+- Render Keep a Changelog sections (`Added`, `Changed`, `Fixed`, etc.)
+- Generate release entries from git ranges or provided commit input
+- Enforce commit format with a dedicated linter script
+- Support CI integration via machine-readable JSON output
+
+## When to Use
+
+- Before publishing a release tag
+- During CI to generate release notes automatically
+- During PR checks to block invalid commit message formats
+- In monorepos where package changelogs require scoped filtering
+- When converting raw git history into user-facing notes
+
+## Key Workflows
+
+### 1. Generate Changelog Entry From Git
+
+```bash
+python3 scripts/generate_changelog.py \
+ --from-tag v1.3.0 \
+ --to-tag v1.4.0 \
+ --next-version v1.4.0 \
+ --format markdown
+```
+
+### 2. Generate Entry From stdin/File Input
+
+```bash
+git log v1.3.0..v1.4.0 --pretty=format:'%s' | \
+ python3 scripts/generate_changelog.py --next-version v1.4.0 --format markdown
+
+python3 scripts/generate_changelog.py --input commits.txt --next-version v1.4.0 --format json
+```
+
+### 3. Update `CHANGELOG.md`
+
+```bash
+python3 scripts/generate_changelog.py \
+ --from-tag v1.3.0 \
+ --to-tag HEAD \
+ --next-version v1.4.0 \
+ --write CHANGELOG.md
+```
+
+### 4. Lint Commits Before Merge
+
+```bash
+python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict --format text
+```
+
+Or file/stdin:
+
+```bash
+python3 scripts/commit_linter.py --input commits.txt --strict
+cat commits.txt | python3 scripts/commit_linter.py --format json
+```
+
+## Conventional Commit Rules
+
+Supported types:
+
+- `feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `build`, `ci`, `chore`
+- `security`, `deprecated`, `remove`
+
+Breaking changes:
+
+- `type(scope)!: summary`
+- Footer/body includes `BREAKING CHANGE:`
+
+SemVer mapping:
+
+- breaking -> `major`
+- non-breaking `feat` -> `minor`
+- all others -> `patch`
+
+## Script Interfaces
+
+- `python3 scripts/generate_changelog.py --help`
+ - Reads commits from git or stdin/`--input`
+ - Renders markdown or JSON
+ - Optional in-place changelog prepend
+- `python3 scripts/commit_linter.py --help`
+ - Validates commit format
+ - Returns non-zero in `--strict` mode on violations
+
+## Common Pitfalls
+
+1. Mixing merge commit messages with release commit parsing
+2. Using vague commit summaries that cannot become release notes
+3. Failing to include migration guidance for breaking changes
+4. Treating docs/chore changes as user-facing features
+5. Overwriting historical changelog sections instead of prepending
+
+## Best Practices
+
+1. Keep commits small and intent-driven.
+2. Scope commit messages (`feat(api): ...`) in multi-package repos.
+3. Enforce linter checks in PR pipelines.
+4. Review generated markdown before publishing.
+5. Tag releases only after changelog generation succeeds.
+6. Keep an `[Unreleased]` section for manual curation when needed.
+
+## References
+
+- [references/ci-integration.md](references/ci-integration.md)
+- [references/changelog-formatting-guide.md](references/changelog-formatting-guide.md)
+- [references/monorepo-strategy.md](references/monorepo-strategy.md)
+- [README.md](README.md)
+
+## Release Governance
+
+Use this release flow for predictability:
+
+1. Lint commit history for target release range.
+2. Generate changelog draft from commits.
+3. Manually adjust wording for customer clarity.
+4. Validate semver bump recommendation.
+5. Tag release only after changelog is approved.
+
+## Output Quality Checks
+
+- Each bullet is user-meaningful, not implementation noise.
+- Breaking changes include migration action.
+- Security fixes are isolated in `Security` section.
+- Sections with no entries are omitted.
+- Duplicate bullets across sections are removed.
+
+## CI Policy
+
+- Run `commit_linter.py --strict` on all PRs.
+- Block merge on invalid conventional commits.
+- Auto-generate draft release notes on tag push.
+- Require human approval before writing into `CHANGELOG.md` on main branch.
+
+## Monorepo Guidance
+
+- Prefer commit scopes aligned to package names.
+- Filter commit stream by scope for package-specific releases.
+- Keep infra-wide changes in root changelog.
+- Store package changelogs near package roots for ownership clarity.
+
+## Failure Handling
+
+- If no valid conventional commits found: fail early, do not generate misleading empty notes.
+- If git range invalid: surface explicit range in error output.
+- If write target missing: create safe changelog header scaffolding.
diff --git a/skills/changelog-generator/_meta.json b/skills/changelog-generator/_meta.json
new file mode 100644
index 00000000..b95ad8f5
--- /dev/null
+++ b/skills/changelog-generator/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "changelog-generator",
+ "displayName": "changelog-generator",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1773242242785,
+ "commit": "https://github.com/openclaw/skills/commit/d3ce63900e3e20ae95af033db23233bbd99df583"
+ },
+ "history": [
+ {
+ "version": "2.1.1",
+ "publishedAt": 1773125605726,
+ "commit": "https://github.com/openclaw/skills/commit/cb43052f1537266f1c38255638f8d26c480b8043"
+ }
+ ]
+}
diff --git a/skills/changelog-generator/references/changelog-formatting-guide.md b/skills/changelog-generator/references/changelog-formatting-guide.md
new file mode 100644
index 00000000..5a7540a1
--- /dev/null
+++ b/skills/changelog-generator/references/changelog-formatting-guide.md
@@ -0,0 +1,17 @@
+# Changelog Formatting Guide
+
+Use Keep a Changelog section ordering:
+
+1. Security
+2. Added
+3. Changed
+4. Deprecated
+5. Removed
+6. Fixed
+
+Rules:
+
+- One bullet = one user-visible change.
+- Lead with impact, not implementation detail.
+- Keep bullets short and actionable.
+- Include migration note for breaking changes.
diff --git a/skills/changelog-generator/references/ci-integration.md b/skills/changelog-generator/references/ci-integration.md
new file mode 100644
index 00000000..fe0ca6ce
--- /dev/null
+++ b/skills/changelog-generator/references/ci-integration.md
@@ -0,0 +1,26 @@
+# CI Integration Examples
+
+## GitHub Actions
+
+```yaml
+name: Changelog Check
+on: [pull_request]
+
+jobs:
+ changelog:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - run: python3 engineering/changelog-generator/scripts/commit_linter.py \
+ --from-ref origin/main --to-ref HEAD --strict
+```
+
+## GitLab CI
+
+```yaml
+changelog_lint:
+ image: python:3.12
+ stage: test
+ script:
+ - python3 engineering/changelog-generator/scripts/commit_linter.py --to-ref HEAD --strict
+```
diff --git a/skills/changelog-generator/references/monorepo-strategy.md b/skills/changelog-generator/references/monorepo-strategy.md
new file mode 100644
index 00000000..3082a1b0
--- /dev/null
+++ b/skills/changelog-generator/references/monorepo-strategy.md
@@ -0,0 +1,39 @@
+# Monorepo Changelog Strategy
+
+## Approaches
+
+| Strategy | When to use | Tradeoff |
+|----------|-------------|----------|
+| Single root changelog | Product-wide releases, small teams | Simple but loses package-level detail |
+| Per-package changelogs | Independent versioning, large teams | Clear ownership but harder to see full picture |
+| Hybrid model | Root summary + package-specific details | Best of both, more maintenance |
+
+## Commit Scoping Pattern
+
+Enforce scoped conventional commits to enable per-package filtering:
+
+```
+feat(payments): add Stripe webhook handler
+fix(auth): handle expired refresh tokens
+chore(infra): bump base Docker image
+```
+
+**Rules:**
+- Scope must match a package/directory name exactly
+- Unscoped commits go to root changelog only
+- Multi-package changes get separate scoped commits (not one mega-commit)
+
+## Filtering for Package Releases
+
+```bash
+# Generate changelog for 'payments' package only
+git log v1.3.0..HEAD --pretty=format:'%s' | grep '^[a-z]*\(payments\)' | \
+ python3 scripts/generate_changelog.py --next-version v1.4.0 --format markdown
+```
+
+## Ownership Model
+
+- Package maintainers own their scoped changelog
+- Platform/infra team owns root changelog
+- CI enforces scope presence on all commits touching package directories
+- Root changelog aggregates breaking changes from all packages for visibility
diff --git a/skills/changelog-generator/scripts/commit_linter.py b/skills/changelog-generator/scripts/commit_linter.py
new file mode 100644
index 00000000..d7d8e300
--- /dev/null
+++ b/skills/changelog-generator/scripts/commit_linter.py
@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Lint commit messages against Conventional Commits.
+
+Input sources (priority order):
+1) --input file (one commit subject per line)
+2) stdin lines
+3) git range via --from-ref/--to-ref
+
+Use --strict for non-zero exit on violations.
+"""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import List, Optional
+
+
+CONVENTIONAL_RE = re.compile(
+ r"^(feat|fix|perf|refactor|docs|test|build|ci|chore|security|deprecated|remove)"
+ r"(\([a-z0-9._/-]+\))?(!)?:\s+.{1,120}$"
+)
+
+
+class CLIError(Exception):
+ """Raised for expected CLI errors."""
+
+
+@dataclass
+class LintReport:
+ total: int
+ valid: int
+ invalid: int
+ violations: List[str]
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description="Validate conventional commit subjects.")
+ parser.add_argument("--input", help="File with commit subjects (one per line).")
+ parser.add_argument("--from-ref", help="Git ref start (exclusive).")
+ parser.add_argument("--to-ref", help="Git ref end (inclusive).")
+ parser.add_argument("--strict", action="store_true", help="Exit non-zero when violations exist.")
+ parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format.")
+ return parser.parse_args()
+
+
+def lines_from_file(path: str) -> List[str]:
+ try:
+ return [line.strip() for line in Path(path).read_text(encoding="utf-8").splitlines() if line.strip()]
+ except Exception as exc:
+ raise CLIError(f"Failed reading --input file: {exc}") from exc
+
+
+def lines_from_stdin() -> List[str]:
+ if sys.stdin.isatty():
+ return []
+ data = sys.stdin.read()
+ return [line.strip() for line in data.splitlines() if line.strip()]
+
+
+def lines_from_git(args: argparse.Namespace) -> List[str]:
+ if not args.to_ref:
+ return []
+ range_spec = f"{args.from_ref}..{args.to_ref}" if args.from_ref else args.to_ref
+ try:
+ proc = subprocess.run(
+ ["git", "log", range_spec, "--pretty=format:%s", "--no-merges"],
+ text=True,
+ capture_output=True,
+ check=True,
+ )
+ except subprocess.CalledProcessError as exc:
+ raise CLIError(f"git log failed for range '{range_spec}': {exc.stderr.strip()}") from exc
+ return [line.strip() for line in proc.stdout.splitlines() if line.strip()]
+
+
+def load_lines(args: argparse.Namespace) -> List[str]:
+ if args.input:
+ return lines_from_file(args.input)
+ stdin_lines = lines_from_stdin()
+ if stdin_lines:
+ return stdin_lines
+ git_lines = lines_from_git(args)
+ if git_lines:
+ return git_lines
+ raise CLIError("No commit input found. Use --input, stdin, or --to-ref.")
+
+
+def lint(lines: List[str]) -> LintReport:
+ violations: List[str] = []
+ valid = 0
+
+ for idx, line in enumerate(lines, start=1):
+ if CONVENTIONAL_RE.match(line):
+ valid += 1
+ continue
+ violations.append(f"line {idx}: {line}")
+
+ return LintReport(total=len(lines), valid=valid, invalid=len(violations), violations=violations)
+
+
+def format_text(report: LintReport) -> str:
+ lines = [
+ "Conventional commit lint report",
+ f"- total: {report.total}",
+ f"- valid: {report.valid}",
+ f"- invalid: {report.invalid}",
+ ]
+ if report.violations:
+ lines.append("Violations:")
+ lines.extend([f"- {v}" for v in report.violations])
+ return "\n".join(lines)
+
+
+def main() -> int:
+ args = parse_args()
+ lines = load_lines(args)
+ report = lint(lines)
+
+ if args.format == "json":
+ print(json.dumps(asdict(report), indent=2))
+ else:
+ print(format_text(report))
+
+ if args.strict and report.invalid > 0:
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ try:
+ raise SystemExit(main())
+ except CLIError as exc:
+ print(f"ERROR: {exc}", file=sys.stderr)
+ raise SystemExit(2)
diff --git a/skills/changelog-generator/scripts/generate_changelog.py b/skills/changelog-generator/scripts/generate_changelog.py
new file mode 100644
index 00000000..ce23f30d
--- /dev/null
+++ b/skills/changelog-generator/scripts/generate_changelog.py
@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Generate changelog entries from Conventional Commits.
+
+Input sources (priority order):
+1) --input file with one commit subject per line
+2) stdin commit subjects
+3) git log from --from-tag/--to-tag or --from-ref/--to-ref
+
+Outputs markdown or JSON and can prepend into CHANGELOG.md.
+"""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, asdict, field
+from datetime import date
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+COMMIT_RE = re.compile(
+ r"^(?Pfeat|fix|perf|refactor|docs|test|build|ci|chore|security|deprecated|remove)"
+ r"(?:\((?P[^)]+)\))?(?P!)?:\s+(?P.+)$"
+)
+
+SECTION_MAP = {
+ "feat": "Added",
+ "fix": "Fixed",
+ "perf": "Changed",
+ "refactor": "Changed",
+ "security": "Security",
+ "deprecated": "Deprecated",
+ "remove": "Removed",
+}
+
+
+class CLIError(Exception):
+ """Raised for expected CLI failures."""
+
+
+@dataclass
+class ParsedCommit:
+ raw: str
+ ctype: str
+ scope: Optional[str]
+ summary: str
+ breaking: bool
+
+
+@dataclass
+class ChangelogEntry:
+ version: str
+ release_date: str
+ sections: Dict[str, List[str]] = field(default_factory=dict)
+ breaking_changes: List[str] = field(default_factory=list)
+ bump: str = "patch"
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description="Generate changelog from conventional commits.")
+ parser.add_argument("--input", help="Text file with one commit subject per line.")
+ parser.add_argument("--from-tag", help="Git tag start (exclusive).")
+ parser.add_argument("--to-tag", help="Git tag end (inclusive).")
+ parser.add_argument("--from-ref", help="Git ref start (exclusive).")
+ parser.add_argument("--to-ref", help="Git ref end (inclusive).")
+ parser.add_argument("--next-version", default="Unreleased", help="Version label for the generated entry.")
+ parser.add_argument("--date", dest="entry_date", default=str(date.today()), help="Release date (YYYY-MM-DD).")
+ parser.add_argument("--format", choices=["markdown", "json"], default="markdown", help="Output format.")
+ parser.add_argument("--write", help="Prepend generated markdown entry into this changelog file.")
+ return parser.parse_args()
+
+
+def read_lines_from_file(path: str) -> List[str]:
+ try:
+ return [line.strip() for line in Path(path).read_text(encoding="utf-8").splitlines() if line.strip()]
+ except Exception as exc:
+ raise CLIError(f"Failed reading --input file: {exc}") from exc
+
+
+def read_lines_from_stdin() -> List[str]:
+ if sys.stdin.isatty():
+ return []
+ payload = sys.stdin.read()
+ return [line.strip() for line in payload.splitlines() if line.strip()]
+
+
+def read_lines_from_git(args: argparse.Namespace) -> List[str]:
+ if args.from_tag or args.to_tag:
+ if not args.to_tag:
+ raise CLIError("--to-tag is required when using tag range.")
+ start = args.from_tag
+ end = args.to_tag
+ elif args.from_ref or args.to_ref:
+ if not args.to_ref:
+ raise CLIError("--to-ref is required when using ref range.")
+ start = args.from_ref
+ end = args.to_ref
+ else:
+ return []
+
+ range_spec = f"{start}..{end}" if start else end
+ try:
+ proc = subprocess.run(
+ ["git", "log", range_spec, "--pretty=format:%s", "--no-merges"],
+ text=True,
+ capture_output=True,
+ check=True,
+ )
+ except subprocess.CalledProcessError as exc:
+ raise CLIError(f"git log failed for range '{range_spec}': {exc.stderr.strip()}") from exc
+
+ return [line.strip() for line in proc.stdout.splitlines() if line.strip()]
+
+
+def load_commits(args: argparse.Namespace) -> List[str]:
+ if args.input:
+ return read_lines_from_file(args.input)
+
+ stdin_lines = read_lines_from_stdin()
+ if stdin_lines:
+ return stdin_lines
+
+ git_lines = read_lines_from_git(args)
+ if git_lines:
+ return git_lines
+
+ raise CLIError("No commit input found. Use --input, stdin, or git range flags.")
+
+
+def parse_commits(lines: List[str]) -> List[ParsedCommit]:
+ parsed: List[ParsedCommit] = []
+ for line in lines:
+ match = COMMIT_RE.match(line)
+ if not match:
+ continue
+ ctype = match.group("type")
+ scope = match.group("scope")
+ summary = match.group("summary")
+ breaking = bool(match.group("breaking")) or "BREAKING CHANGE" in line
+ parsed.append(ParsedCommit(raw=line, ctype=ctype, scope=scope, summary=summary, breaking=breaking))
+ return parsed
+
+
+def determine_bump(commits: List[ParsedCommit]) -> str:
+ if any(c.breaking for c in commits):
+ return "major"
+ if any(c.ctype == "feat" for c in commits):
+ return "minor"
+ return "patch"
+
+
+def build_entry(commits: List[ParsedCommit], version: str, entry_date: str) -> ChangelogEntry:
+ sections: Dict[str, List[str]] = {
+ "Security": [],
+ "Added": [],
+ "Changed": [],
+ "Deprecated": [],
+ "Removed": [],
+ "Fixed": [],
+ }
+ breaking_changes: List[str] = []
+
+ for commit in commits:
+ if commit.breaking:
+ breaking_changes.append(commit.summary)
+ section = SECTION_MAP.get(commit.ctype)
+ if section:
+ line = commit.summary if not commit.scope else f"{commit.scope}: {commit.summary}"
+ sections[section].append(line)
+
+ sections = {k: v for k, v in sections.items() if v}
+ return ChangelogEntry(
+ version=version,
+ release_date=entry_date,
+ sections=sections,
+ breaking_changes=breaking_changes,
+ bump=determine_bump(commits),
+ )
+
+
+def render_markdown(entry: ChangelogEntry) -> str:
+ lines = [f"## [{entry.version}] - {entry.release_date}", ""]
+ if entry.breaking_changes:
+ lines.append("### Breaking")
+ lines.extend([f"- {item}" for item in entry.breaking_changes])
+ lines.append("")
+
+ ordered_sections = ["Security", "Added", "Changed", "Deprecated", "Removed", "Fixed"]
+ for section in ordered_sections:
+ items = entry.sections.get(section, [])
+ if not items:
+ continue
+ lines.append(f"### {section}")
+ lines.extend([f"- {item}" for item in items])
+ lines.append("")
+
+ lines.append(f"")
+ return "\n".join(lines).strip() + "\n"
+
+
+def prepend_changelog(path: Path, entry_md: str) -> None:
+ if path.exists():
+ original = path.read_text(encoding="utf-8")
+ else:
+ original = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n"
+
+ if original.startswith("# Changelog"):
+ first_break = original.find("\n")
+ head = original[: first_break + 1]
+ tail = original[first_break + 1 :].lstrip("\n")
+ combined = f"{head}\n{entry_md}\n{tail}"
+ else:
+ combined = f"# Changelog\n\n{entry_md}\n{original}"
+ path.write_text(combined, encoding="utf-8")
+
+
+def main() -> int:
+ args = parse_args()
+ lines = load_commits(args)
+ parsed = parse_commits(lines)
+ if not parsed:
+ raise CLIError("No valid conventional commit messages found in input.")
+
+ entry = build_entry(parsed, args.next_version, args.entry_date)
+
+ if args.format == "json":
+ print(json.dumps(asdict(entry), indent=2))
+ else:
+ markdown = render_markdown(entry)
+ print(markdown, end="")
+ if args.write:
+ prepend_changelog(Path(args.write), markdown)
+
+ if args.format == "json" and args.write:
+ prepend_changelog(Path(args.write), render_markdown(entry))
+
+ return 0
+
+
+if __name__ == "__main__":
+ try:
+ raise SystemExit(main())
+ except CLIError as exc:
+ print(f"ERROR: {exc}", file=sys.stderr)
+ raise SystemExit(2)
diff --git a/skills/chief-of-staff/SKILL.md b/skills/chief-of-staff/SKILL.md
new file mode 100644
index 00000000..d4b77e41
--- /dev/null
+++ b/skills/chief-of-staff/SKILL.md
@@ -0,0 +1,179 @@
+---
+name: "chief-of-staff"
+description: "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: orchestration
+ updated: 2026-03-05
+ frameworks: routing-matrix, synthesis-framework, decision-log, board-protocol
+---
+
+# Chief of Staff
+
+The orchestration layer between founder and C-suite. Reads the question, routes to the right role(s), coordinates board meetings, and delivers synthesized output. Loads company context for every interaction.
+
+## Keywords
+chief of staff, orchestrator, routing, c-suite coordinator, board meeting, multi-agent, advisor coordination, decision log, synthesis
+
+---
+
+## Session Protocol (Every Interaction)
+
+1. Load company context via context-engine skill
+2. Score decision complexity
+3. Route to role(s) or trigger board meeting
+4. Synthesize output
+5. Log decision if reached
+
+---
+
+## Invocation Syntax
+
+```
+[INVOKE:role|question]
+```
+
+Examples:
+```
+[INVOKE:cfo|What's the right runway target given our growth rate?]
+[INVOKE:board|Should we raise a bridge or cut to profitability?]
+```
+
+### Loop Prevention Rules (CRITICAL)
+
+1. **Chief of Staff cannot invoke itself.**
+2. **Maximum depth: 2.** Chief of Staff → Role → stop.
+3. **Circular blocking.** A→B→A is blocked. Log it.
+4. **Board = depth 1.** Roles at board meeting do not invoke each other.
+
+If loop detected: return to founder with "The advisors are deadlocked. Here's where they disagree: [summary]."
+
+---
+
+## Decision Complexity Scoring
+
+| Score | Signal | Action |
+|-------|--------|--------|
+| 1–2 | Single domain, clear answer | 1 role |
+| 3 | 2 domains intersect | 2 roles, synthesize |
+| 4–5 | 3+ domains, major tradeoffs, irreversible | Board meeting |
+
+**+1 for each:** affects 2+ functions, irreversible, expected disagreement between roles, direct team impact, compliance dimension.
+
+---
+
+## Routing Matrix (Summary)
+
+Full rules in `references/routing-matrix.md`.
+
+| Topic | Primary | Secondary |
+|-------|---------|-----------|
+| Fundraising, burn, financial model | CFO | CEO |
+| Hiring, firing, culture, performance | CHRO | COO |
+| Product roadmap, prioritization | CPO | CTO |
+| Architecture, tech debt | CTO | CPO |
+| Revenue, sales, GTM, pricing | CRO | CFO |
+| Process, OKRs, execution | COO | CFO |
+| Security, compliance, risk | CISO | COO |
+| Company direction, investor relations | CEO | Board |
+| Market strategy, positioning | CMO | CRO |
+| M&A, pivots | CEO | Board |
+
+---
+
+## Board Meeting Protocol
+
+**Trigger:** Score ≥ 4, or multi-function irreversible decision.
+
+```
+BOARD MEETING: [Topic]
+Attendees: [Roles]
+Agenda: [2–3 specific questions]
+
+[INVOKE:role1|agenda question]
+[INVOKE:role2|agenda question]
+[INVOKE:role3|agenda question]
+
+[Chief of Staff synthesis]
+```
+
+**Rules:** Max 5 roles. Each role one turn, no back-and-forth. Chief of Staff synthesizes. Conflicts surfaced, not resolved — founder decides.
+
+---
+
+## Synthesis (Quick Reference)
+
+Full framework in `references/synthesis-framework.md`.
+
+1. **Extract themes** — what 2+ roles agree on independently
+2. **Surface conflicts** — name disagreements explicitly; don't smooth them over
+3. **Action items** — specific, owned, time-bound (max 5)
+4. **One decision point** — the single thing needing founder judgment
+
+**Output format:**
+```
+## What We Agree On
+[2–3 consensus themes]
+
+## The Disagreement
+[Named conflict + each side's reasoning + what it's really about]
+
+## Recommended Actions
+1. [Action] — [Owner] — [Timeline]
+...
+
+## Your Decision Point
+[One question. Two options with trade-offs. No recommendation — just clarity.]
+```
+
+---
+
+## Decision Log
+
+Track decisions to `~/.claude/decision-log.md`.
+
+```
+## Decision: [Name]
+Date: [YYYY-MM-DD]
+Question: [Original question]
+Decided: [What was decided]
+Owner: [Who executes]
+Review: [When to check back]
+```
+
+At session start: if a review date has passed, flag it: *"You decided [X] on [date]. Worth a check-in?"*
+
+---
+
+## Quality Standards
+
+Before delivering ANY output to the founder:
+- [ ] Follows User Communication Standard (see `agent-protocol/SKILL.md`)
+- [ ] Bottom line is first — no preamble, no process narration
+- [ ] Company context loaded (not generic advice)
+- [ ] Every finding has WHAT + WHY + HOW
+- [ ] Actions have owners and deadlines (no "we should consider")
+- [ ] Decisions framed as options with trade-offs and recommendation
+- [ ] Conflicts named, not smoothed
+- [ ] Risks are concrete (if X → Y happens, costs $Z)
+- [ ] No loops occurred
+- [ ] Max 5 bullets per section — overflow to reference
+
+---
+
+## Ecosystem Awareness
+
+The Chief of Staff routes to **28 skills total**:
+- **10 C-suite roles** — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor
+- **6 orchestration skills** — cs-onboard, context-engine, board-meeting, decision-logger, agent-protocol
+- **6 cross-cutting skills** — board-deck-builder, scenario-war-room, competitive-intel, org-health-diagnostic, ma-playbook, intl-expansion
+- **6 culture & collaboration skills** — culture-architect, company-os, founder-coach, strategic-alignment, change-management, internal-narrative
+
+See `references/routing-matrix.md` for complete trigger mapping.
+
+## References
+- `references/routing-matrix.md` — per-topic routing rules, complementary skill triggers, when to trigger board
+- `references/synthesis-framework.md` — full synthesis process, conflict types, output format
diff --git a/skills/chief-of-staff/_meta.json b/skills/chief-of-staff/_meta.json
new file mode 100644
index 00000000..a0914c0f
--- /dev/null
+++ b/skills/chief-of-staff/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "chief-of-staff",
+ "displayName": "Chief Of Staff",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773175652837,
+ "commit": "https://github.com/openclaw/skills/commit/798f4a21952852177a0aaeafd5a326dd4af3f037"
+ },
+ "history": [
+ {
+ "version": "1.0.0",
+ "publishedAt": 1772750812030,
+ "commit": "https://github.com/openclaw/skills/commit/2794d8456f66f0f1343a73da63e1b0418e984981"
+ }
+ ]
+}
diff --git a/skills/chief-of-staff/references/routing-matrix.md b/skills/chief-of-staff/references/routing-matrix.md
new file mode 100644
index 00000000..2c94ac08
--- /dev/null
+++ b/skills/chief-of-staff/references/routing-matrix.md
@@ -0,0 +1,212 @@
+# Routing Matrix
+
+Detailed routing rules for the Chief of Staff. When a founder asks a question, find the best match in this matrix, then apply the scoring rules to determine single-role, multi-role, or board meeting.
+
+---
+
+## Routing by Domain
+
+### Finance & Capital
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| How much runway do we have? | CFO | — | 1 |
+| Should we raise now or later? | CFO | CEO | 3 |
+| What's our burn multiple? | CFO | COO | 2 |
+| Should we raise a bridge or cut costs? | CFO | CEO, COO | 5 |
+| What's the right pricing model? | CFO | CRO, CPO | 4 |
+| Should we hire or extend runway? | CFO | CHRO, COO | 4 |
+| What terms should we accept for this round? | CFO | CEO | 3 |
+| How do we model the next 18 months? | CFO | COO | 2 |
+
+### People & Culture
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| Should I let this person go? | CHRO | COO | 2 |
+| How do I structure comp for the team? | CHRO | CFO | 3 |
+| We have a culture problem — what do we do? | CHRO | CEO | 3 |
+| A leader on my team isn't working — now what? | CHRO | COO | 2 |
+| How do I hire fast without breaking culture? | CHRO | COO | 3 |
+| Two co-founders are in conflict | CHRO | CEO | 4 |
+| How do we retain our best people? | CHRO | CFO | 2 |
+| What does a good performance management process look like? | CHRO | COO | 2 |
+
+### Product
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| What should we build next? | CPO | CTO | 2 |
+| Should we kill this feature? | CPO | CTO, CRO | 3 |
+| How do we prioritize the roadmap? | CPO | CTO, COO | 3 |
+| Are we pre-PMF or post-PMF? | CPO | CRO, CEO | 4 |
+| Should we build vs buy? | CPO | CTO, CFO | 4 |
+| How do we handle technical debt vs new features? | CTO | CPO | 3 |
+| What's our product strategy for next year? | CPO | CEO, CRO | 4 |
+
+### Technology & Engineering
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| What architecture should we use? | CTO | CPO | 1 |
+| How do we scale the system to 10x traffic? | CTO | COO | 2 |
+| We have a security incident — what now? | CISO | CTO, COO | 5 |
+| Should we migrate to microservices? | CTO | COO, CFO | 4 |
+| How do I grow the engineering team? | CTO | CHRO, CFO | 3 |
+| Our engineering velocity is dropping — why? | CTO | COO | 2 |
+| What's our DevOps maturity? | CTO | COO | 1 |
+| How do we handle a compliance audit on our tech? | CISO | CTO | 3 |
+
+### Sales & Revenue
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| Why aren't we closing deals? | CRO | CPO | 2 |
+| How do we build a sales process from scratch? | CRO | COO | 2 |
+| What's the right GTM for this market? | CRO | CMO, CEO | 4 |
+| Our churn is too high — root cause? | CRO | CPO, CHRO | 3 |
+| Should we go enterprise or stay SMB? | CRO | CPO, CFO | 4 |
+| How do we expand into a new market? | CRO | CMO, CEO, CFO | 5 |
+| What's our ideal customer profile? | CRO | CPO, CMO | 3 |
+| Pipeline is dry — what do we do? | CRO | CMO | 2 |
+
+### Operations & Execution
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| Why do things keep breaking? | COO | CTO | 2 |
+| How do we set up OKRs? | COO | CEO | 2 |
+| Our meetings are useless — fix it | COO | — | 1 |
+| How do we scale operations without hiring? | COO | CTO, CFO | 3 |
+| There's a recurring bottleneck — how to fix it? | COO | CTO | 2 |
+| We need a cross-team process for X | COO | Relevant dept head | 2 |
+| How do we improve decision speed? | COO | CEO | 3 |
+
+### Marketing & Brand
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| How do we position against Competitor X? | CMO | CRO | 2 |
+| What channels should we invest in? | CMO | CRO, CFO | 3 |
+| Our brand isn't resonating — why? | CMO | CPO, CRO | 3 |
+| How do we build a content strategy? | CMO | CRO | 2 |
+| What's our marketing budget allocation? | CMO | CFO, CRO | 3 |
+
+### Security & Compliance
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| How do we pass an ISO 27001 audit? | CISO | COO | 2 |
+| We had a data breach — what now? | CISO | CTO, CEO, COO | 5 |
+| How do we handle GDPR compliance? | CISO | CTO | 2 |
+| What's our security posture? | CISO | CTO | 1 |
+| A regulator is asking questions | CISO | CEO, COO | 4 |
+
+### Strategic Direction
+
+| Question type | Primary | Secondary | Score |
+|--------------|---------|-----------|-------|
+| Should we pivot? | CEO | Board meeting | 5 |
+| Are we building the right company? | CEO | Board meeting | 5 |
+| How do we handle an acquisition offer? | CEO | CFO, Board meeting | 5 |
+| What's the 3-year strategy? | CEO | All C-suite, board | 5 |
+| Should we enter a new vertical? | CEO | CRO, CFO, CPO | 4 |
+
+---
+
+## When to Invoke Multiple Roles
+
+Invoke 2 roles when:
+- The question sits at the boundary of two domains
+- One role's answer creates a constraint the other needs to know about
+- The founder explicitly wants two perspectives
+
+Invoke 3+ roles (board) when:
+- The question involves irreversible resource commitment
+- There's a known tension between functions (e.g., product vs revenue, speed vs quality)
+- The answer will change how multiple teams operate
+- It's a company-direction question, not an operational one
+
+---
+
+## When NOT to Invoke Multiple Roles
+
+Don't multi-invoke when:
+- The answer is technical and one role clearly owns it
+- The founder just needs a framework, not a decision
+- Invoking more roles would add noise without adding signal
+- Time is short and a directional answer beats a comprehensive one
+
+---
+
+## Escalation Criteria → Board Meeting
+
+Automatically escalate to board meeting when any of these apply:
+
+1. **Irreversibility:** The decision is hard or impossible to reverse (layoffs, pivots, major contracts, fundraising terms)
+2. **Cross-functional resource impact:** The decision changes budget, headcount, or priorities for 2+ teams
+3. **Founder blind spot risk:** The topic is in an area where the founder's archetype creates a known gap (e.g., technical founder on GTM)
+4. **Disagreement expected:** The domains involved are known to have competing incentives (CFO vs CRO on pricing, CTO vs CPO on tech debt)
+5. **Explicit request:** Founder says "what does the team think" or "I want multiple perspectives"
+6. **Score ≥ 4**
+
+---
+
+## Role Registry
+
+| Role | File | Domain |
+|------|------|--------|
+| CEO | ceo-advisor | Strategy, culture, investor relations |
+| CFO | cfo-advisor | Finance, capital, unit economics |
+| COO | coo-advisor | Operations, OKRs, scaling |
+| CTO | cto-advisor | Engineering, architecture, tech strategy |
+| CPO | cpo-advisor | Product, roadmap, UX |
+| CRO | cro-advisor | Revenue, sales, GTM |
+| CMO | cmo-advisor | Marketing, brand, positioning |
+| CHRO | chro-advisor | People, culture, hiring |
+| CISO | ciso-advisor | Security, compliance, risk |
+
+**If a role file doesn't exist:** Note the gap. Answer from first principles with domain expertise. Log that the role is missing.
+
+---
+
+## Complementary Skills Registry
+
+These skills are invoked for specific cross-cutting needs, not for general domain questions.
+
+### Orchestration & Infrastructure
+| Skill | Trigger | File |
+|-------|---------|------|
+| C-Suite Onboard | `/cs:setup`, first-time setup, "tell me about your company" | cs-onboard |
+| Context Engine | Auto-loaded; staleness check | context-engine |
+| Board Meeting | `/cs:board`, multi-role decisions, score ≥ 4 | board-meeting |
+| Decision Logger | After board meetings, `/cs:decisions`, `/cs:review` | decision-logger |
+| Agent Protocol | Inter-role invocations, loop detection | agent-protocol |
+
+### Cross-Cutting Capabilities
+| Skill | Trigger | File |
+|-------|---------|------|
+| Board Deck Builder | "board deck", "investor update", "board presentation" | board-deck-builder |
+| Scenario War Room | "what if", multi-variable scenarios, stress test across functions | scenario-war-room |
+| Competitive Intelligence | "competitor", "competitive analysis", "battlecard", "who's winning" | competitive-intel |
+| Org Health Diagnostic | "how healthy are we", "org health", "company health check" | org-health-diagnostic |
+| M&A Playbook | "acquisition", "M&A", "due diligence", "being acquired" | ma-playbook |
+| International Expansion | "expand to", "new market", "international", "localization" | intl-expansion |
+
+### Culture & Collaboration
+| Skill | Trigger | File |
+|-------|---------|------|
+| Culture Architect | "values", "culture", "mission", "vision", culture problems | culture-architect |
+| Company OS | "operating system", "EOS", "Scaling Up", "meeting cadence", "how do we run" | company-os |
+| Founder Coach | "delegation", "blind spots", "founder growth", "leadership style", burnout | founder-coach |
+| Strategic Alignment | "alignment", "silos", "teams not aligned", "strategy cascade" | strategic-alignment |
+| Change Management | "rolling out", "reorg", "change", "new process", "transition" | change-management |
+| Internal Narrative | "all-hands", "internal comms", "how do we tell", "narrative" | internal-narrative |
+
+### Routing Priority
+
+1. Check if it matches a **complementary skill trigger** → route there
+2. Check if it matches a **single role domain** → route to that role
+3. Check if it spans **multiple role domains** (score ≥ 3) → invoke multiple roles
+4. Check if it meets **escalation criteria** (score ≥ 4 or irreversible) → trigger board meeting
+5. If unclear → ask one clarifying question, then route
diff --git a/skills/chief-of-staff/references/synthesis-framework.md b/skills/chief-of-staff/references/synthesis-framework.md
new file mode 100644
index 00000000..51d9e720
--- /dev/null
+++ b/skills/chief-of-staff/references/synthesis-framework.md
@@ -0,0 +1,201 @@
+# Synthesis Framework
+
+How to turn multiple role outputs into a single, useful response for the founder. Synthesis is the highest-value function of the Chief of Staff — it's not about summarizing, it's about integrating.
+
+---
+
+## The Problem with Multi-Role Output
+
+Without synthesis, multiple advisors produce noise:
+- Overlapping advice
+- Contradictions without resolution
+- Action items from every role that compete for priority
+- Founder left to figure out what to do with it all
+
+Synthesis turns this into signal: one clear picture, explicit conflicts named, prioritized actions, one decision point.
+
+---
+
+## Phase 1: Collect and Read
+
+Before writing anything, read all role responses completely. Look for:
+
+**Consensus signals:**
+- Same recommendation from 2+ roles independently
+- Same risk identified from different angles
+- Same root cause named without coordination
+
+**Conflict signals:**
+- One role says X, another says not-X
+- Same data interpreted differently
+- Competing resource requests (CFO says cut costs, CRO says invest in sales)
+- Different time horizons (CTO wants to fix tech debt now, CPO wants to ship features now)
+
+**Gap signals:**
+- A critical dimension no role addressed
+- A risk nobody flagged
+- An assumption baked in that nobody questioned
+
+---
+
+## Phase 2: Extract Themes
+
+A theme is a finding that appears in 2+ role responses, even if framed differently.
+
+**How to identify:**
+1. List every distinct point from every role response
+2. Group points that are about the same underlying issue
+3. Name the group with a clear, plain-language label
+4. Note which roles contributed to it
+
+**Example:**
+> CFO: "The burn multiple is 3.2 — unsustainable without revenue acceleration."
+> CRO: "We need 3 more sales cycles to hit targets, minimum 90 days."
+> COO: "Three positions are open that will cost $40K/month when filled."
+>
+> Theme: **Cash position is tighter than the headline number suggests.** (CFO + CRO + COO)
+
+**Limit to 3 themes.** More than 3 means you're not synthesizing — you're listing.
+
+---
+
+## Phase 3: Surface Conflicts
+
+Name every conflict explicitly. Don't resolve it — present it.
+
+**Conflict types:**
+
+### Resource conflict
+Two roles want the same budget, headcount, or time.
+> "CFO wants to delay the new hire until Q3. CHRO says the team is already at capacity and another quarter will cause attrition. Both are right from their domain."
+
+### Priority conflict
+Two roles disagree on what's most important right now.
+> "CTO wants 6 weeks on infrastructure to prevent outages. CPO wants those same engineers on the new feature for the sales pipeline. This isn't a technical question — it's a risk tolerance question."
+
+### Time horizon conflict
+Two roles are optimizing for different time frames.
+> "CRO is optimizing for this quarter's close rate. CMO is optimizing for brand that compounds over 18 months. Both strategies are valid. They require different budget allocations."
+
+### Assumption conflict
+Two roles have incompatible assumptions baked in.
+> "CFO's model assumes 15% MoM growth. CRO says realistic growth is 8% given the sales cycle length. The financial model needs to be rebuilt on the CRO's number."
+
+**Present conflicts without picking sides.** The founder decides which trade-off to accept.
+
+---
+
+## Phase 4: Derive Action Items
+
+From the consensus themes and the non-conflicting role outputs, derive concrete actions.
+
+**Action item criteria:**
+- Specific (not "improve the process" — "map the QA process and find the bottleneck")
+- Owned (assign to a role or person)
+- Time-bound (this week / this quarter / before next board)
+- Consequence-linked (why does it matter if it slips)
+
+**Good example:**
+> **Action:** Build an updated 18-month financial model using CRO's 8% MoM growth assumption.
+> **Owner:** CFO
+> **By:** End of week
+> **Why it matters:** Current fundraising conversations are based on a model that's too optimistic.
+
+**Bad example:**
+> Review the financial model with the team.
+
+**Limit to 5 actions.** If there are more, prioritize by impact and flag the rest as backlog.
+
+---
+
+## Phase 5: Identify the Founder Decision Point
+
+Every board meeting ends with one question for the founder. Just one.
+
+**How to find it:**
+- It's usually the conflict that can't be resolved without a values choice
+- It's the question where both sides have a legitimate case
+- It's the thing none of the advisors can decide unilaterally
+
+**Frame it cleanly:**
+> "The C-suite is aligned on the actions above, but there's one thing that needs your call: [specific decision]. [Role A] recommends X because [reason]. [Role B] recommends Y because [reason]. This is ultimately a question of [underlying trade-off — growth vs profitability / speed vs stability / short-term vs long-term]."
+
+**Don't present multiple decision points.** Force the synthesis down to one. If there are genuinely two unrelated decisions, separate them into two outputs.
+
+---
+
+## Output Format
+
+```markdown
+## [Topic] — C-Suite Synthesis
+
+### What We Agree On
+[Theme 1 with 1–2 sentences]
+[Theme 2 with 1–2 sentences]
+[Theme 3 with 1–2 sentences]
+
+### The Disagreement
+[Name the conflict]
+[Role A position + reasoning]
+[Role B position + reasoning]
+[What the conflict is really about]
+
+### Recommended Actions
+1. **[Action]** — [Owner] — [Timeline] — [Why it matters]
+2. **[Action]** — [Owner] — [Timeline]
+3. **[Action]** — [Owner] — [Timeline]
+4. **[Action]** — [Owner] — [Timeline]
+5. **[Action]** — [Owner] — [Timeline]
+
+### Your Decision Point
+[One question for the founder. Two options with their trade-offs. No recommendation — just clarity.]
+```
+
+---
+
+## Quality Standards for Synthesis
+
+Before delivering:
+
+**Compression test:** Could a founder read this in 3 minutes and know exactly what to do? If not, cut.
+
+**Honesty test:** Did you name the real conflicts, or smooth them over? Smoothed conflicts come back as surprises.
+
+**Specificity test:** Are the action items specific enough to act on, or are they goals masquerading as actions?
+
+**Decision point test:** Is there one clear thing for the founder to decide, or are you leaving them with a mess?
+
+**Context test:** Would this advice make sense for any company, or is it clearly calibrated to this company's stage, challenges, and founder?
+
+---
+
+## Common Synthesis Failures
+
+**The summary trap:** You summarize each role's output in sequence. This is not synthesis — it's transcription. Synthesis requires cutting.
+
+**The false consensus:** You say "the team agrees" when there's actually a meaningful conflict. Named conflicts are useful. Hidden conflicts are dangerous.
+
+**The advice avalanche:** 15 action items that no one can action. Cut to 5. If everything is priority, nothing is.
+
+**The unresolved conflict dump:** You present the conflict and then leave the founder to figure it out. Your job is to frame the choice cleanly, not to resolve it — but also not to dump it raw.
+
+**The context-free advice:** The synthesis sounds like it came from a textbook, not from someone who knows this company. If you can swap the company name and it still reads the same, it's not synthesized.
+
+---
+
+## When Synthesis Reveals Deadlock
+
+Sometimes roles genuinely can't align and the synthesis produces no clear direction.
+
+**Signs of deadlock:**
+- Every theme has a counter-theme
+- Every action has a conflict attached
+- The "decision point" is actually three decisions
+
+**What to do:**
+1. Name the deadlock explicitly: *"The C-suite is genuinely split on this. Here's why."*
+2. Present the two paths cleanly with consequences
+3. Recommend a time-boxed experiment if possible: *"You don't have to decide between X and Y permanently. Run X for 30 days with a clear metric for success, then reassess."*
+4. Flag it as a strategic question that may need external input (advisor, board, market data)
+
+Deadlock is honest. Fake consensus is not.
diff --git a/skills/chro-advisor/SKILL.md b/skills/chro-advisor/SKILL.md
new file mode 100644
index 00000000..a846122d
--- /dev/null
+++ b/skills/chro-advisor/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: "chro-advisor"
+description: "People leadership for scaling companies. Hiring strategy, compensation design, org structure, culture, and retention. Use when building hiring plans, designing comp frameworks, restructuring teams, managing performance, building culture, or when user mentions CHRO, HR, people strategy, talent, headcount, compensation, org design, retention, or performance management."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: chro-leadership
+ updated: 2026-03-05
+ python-tools: hiring_plan_modeler.py, comp_benchmarker.py
+ frameworks: people-strategy, comp-frameworks, org-design
+---
+
+# CHRO Advisor
+
+People strategy and operational HR frameworks for business-aligned hiring, compensation, org design, and culture that scales.
+
+## Keywords
+CHRO, chief people officer, CPO, HR, human resources, people strategy, hiring plan, headcount planning, talent acquisition, recruiting, compensation, salary bands, equity, org design, organizational design, career ladder, title framework, retention, performance management, culture, engagement, remote work, hybrid, spans of control, succession planning, attrition
+
+## Quick Start
+
+```bash
+python scripts/hiring_plan_modeler.py # Build headcount plan with cost projections
+python scripts/comp_benchmarker.py # Benchmark salaries and model total comp
+```
+
+## Core Responsibilities
+
+### 1. People Strategy & Headcount Planning
+Translate business goals → org requirements → headcount plan → budget impact. Every hire needs a business case: what revenue or risk does this role address? See `references/people_strategy.md` for hiring at each growth stage.
+
+### 2. Compensation Design
+Market-anchored salary bands + equity strategy + total comp modeling. See `references/comp_frameworks.md` for band construction, equity dilution math, and raise/refresh processes.
+
+### 3. Org Design
+Right structure for the stage. Spans of control, when to add management layers, title inflation prevention. See `references/org_design.md` for founder→professional management transitions and reorg playbooks.
+
+### 4. Retention & Performance
+Retention starts at hire. Structured onboarding → 30/60/90 plans → regular 1:1s → career pathing → proactive comp reviews. See `references/people_strategy.md` for what actually moves the needle.
+
+**Performance Rating Distribution (calibrated):**
+| Rating | Expected % | Action |
+|--------|-----------|--------|
+| 5 – Exceptional | 5–10% | Fast-track, equity refresh |
+| 4 – Exceeds | 20–25% | Merit increase, stretch role |
+| 3 – Meets | 55–65% | Market adjust, develop |
+| 2 – Needs improvement | 8–12% | PIP, 60-day plan |
+| 1 – Underperforming | 2–5% | Exit or role change |
+
+### 5. Culture & Engagement
+Culture is behavior, not values on a wall. Measure eNPS quarterly. Act on results within 30 days or don't ask.
+
+## Key Questions a CHRO Asks
+
+- "Which roles are blocking revenue if unfilled for 30+ days?"
+- "What's our regrettable attrition rate? Who left that we wish hadn't?"
+- "Are managers our retention asset or our attrition cause?"
+- "Can a new hire explain their career path in 12 months?"
+- "Where are we paying below P50? Who's a flight risk because of it?"
+- "What's the cost of this hire vs. the cost of not hiring?"
+
+## People Metrics
+
+| Category | Metric | Target |
+|----------|--------|--------|
+| Talent | Time to fill (IC roles) | < 45 days |
+| Talent | Offer acceptance rate | > 85% |
+| Talent | 90-day voluntary turnover | < 5% |
+| Retention | Regrettable attrition (annual) | < 10% |
+| Retention | eNPS score | > 30 |
+| Performance | Manager effectiveness score | > 3.8/5 |
+| Comp | % employees within band | > 90% |
+| Comp | Compa-ratio (avg) | 0.95–1.05 |
+| Org | Span of control (ICs) | 6–10 |
+| Org | Span of control (managers) | 4–7 |
+
+## Red Flags
+
+- Attrition spikes and exit interviews all name the same manager
+- Comp bands haven't been refreshed in 18+ months
+- No career ladder → top performers leave after 18 months
+- Hiring without a written business case or job scorecard
+- Performance reviews happen once a year with no mid-year check-in
+- Equity refreshes only for executives, not high performers
+- Time to fill > 90 days for critical roles
+- eNPS below 0 — something is structurally broken
+- More than 3 org layers between IC and CEO at < 50 people
+
+## Integration with Other C-Suite Roles
+
+| When... | CHRO works with... | To... |
+|---------|-------------------|-------|
+| Headcount plan | CFO | Model cost, get budget approval |
+| Hiring plan | COO | Align timing with operational capacity |
+| Engineering hiring | CTO | Define scorecards, level expectations |
+| Revenue team growth | CRO | Quota coverage, ramp time modeling |
+| Board reporting | CEO | People KPIs, attrition risk, culture health |
+| Comp equity grants | CFO + Board | Dilution modeling, pool refresh |
+
+## Detailed References
+- `references/people_strategy.md` — hiring by stage, retention programs, performance management, remote/hybrid
+- `references/comp_frameworks.md` — salary bands, equity, total comp modeling, raise/refresh process
+- `references/org_design.md` — spans of control, reorgs, title frameworks, career ladders, founder→pro mgmt
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Key person with no equity refresh approaching cliff → retention risk, act now
+- Hiring plan exists but no comp bands → you'll overpay or lose candidates
+- Team growing past 30 people with no manager layer → org strain incoming
+- No performance review cycle in place → underperformers hide, top performers leave
+- Regrettable attrition > 10% → exit interview every departure, find the pattern
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Build a hiring plan" | Headcount plan with roles, timing, cost, and ramp model |
+| "Set up comp bands" | Compensation framework with bands, equity, benchmarks |
+| "Design our org" | Org chart proposal with spans, layers, and transition plan |
+| "We're losing people" | Retention analysis with risk scores and intervention plan |
+| "People board section" | Headcount, attrition, hiring velocity, engagement, risks |
+
+## Reasoning Technique: Empathy + Data
+
+Start with the human impact, then validate with metrics. Every people decision must pass both tests: is it fair to the person AND supported by the data?
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/chro-advisor/_meta.json b/skills/chro-advisor/_meta.json
new file mode 100644
index 00000000..b55ab41f
--- /dev/null
+++ b/skills/chro-advisor/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "chro-advisor",
+ "displayName": "Chro Advisor",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773175656155,
+ "commit": "https://github.com/openclaw/skills/commit/70b30a65da84626ddf329a2d47fd790cfe5bde5a"
+ },
+ "history": [
+ {
+ "version": "2.0.0",
+ "publishedAt": 1772746550056,
+ "commit": "https://github.com/openclaw/skills/commit/cf0ab89a4f3ac9856bd678778afc0d2d98f54785"
+ }
+ ]
+}
diff --git a/skills/chro-advisor/references/comp_frameworks.md b/skills/chro-advisor/references/comp_frameworks.md
new file mode 100644
index 00000000..43cabf5d
--- /dev/null
+++ b/skills/chro-advisor/references/comp_frameworks.md
@@ -0,0 +1,320 @@
+# Compensation Frameworks Reference
+
+Salary bands, equity design, total comp modeling, comp philosophy, and raise/refresh processes.
+
+---
+
+## Comp Philosophy — The Foundation
+
+Before building bands, define your philosophy. Ambiguity in comp philosophy = pay equity lawsuits and trust erosion.
+
+**The five decisions:**
+
+### 1. What market percentile do you target?
+- **P25 (below market):** Only viable with exceptional mission, equity, or growth opportunity. Flight risk is high after 18 months.
+- **P50 (market median):** Standard for most Series A–B companies. Competitive without premium.
+- **P75 (above market):** Premium talent strategy. Used by high-margin or talent-intensive businesses. Netflix model.
+- **P90+:** Top-of-market for specific functions (ML at AI companies, senior engineers at FAANG feeders).
+
+**Common hybrid:** P50 base + above-market equity = total comp at P65–75.
+
+### 2. What's in your total comp package?
+Define each component explicitly:
+- **Base salary** — cash, market-benchmarked
+- **Variable / bonus** — % of base, tied to what criteria
+- **Equity** — options vs. RSUs, vesting schedule, refresh cadence
+- **Benefits** — health, retirement, PTO policy
+- **Learning & development budget**
+- **Remote/location allowances**
+
+### 3. Are bands public internally?
+Recommended: Yes. Pay transparency reduces equity complaints, builds trust, and forces you to maintain clean bands.
+
+### 4. How often do you refresh bands?
+Minimum: annually. High-growth markets: every 6 months (engineering specifically in hot markets).
+
+### 5. How do you handle individual negotiation?
+Options:
+- **Fixed bands, no negotiation** (Buffer model) — simple, fair, loses some candidates
+- **Band range with manager discretion** — most common, requires calibration guardrails
+- **Individual negotiation within band** — flexible, creates pay equity drift over time
+
+---
+
+## Salary Bands: Construction
+
+### Step 1: Define levels
+
+Standard IC levels (adapt to company):
+| Level | Title example | Scope |
+|-------|--------------|-------|
+| L1 | Junior / Associate | Execution with guidance |
+| L2 | Mid-level | Independent execution |
+| L3 | Senior | Leads workstreams, mentors L1-L2 |
+| L4 | Staff / Principal | Cross-team technical leadership |
+| L5 | Distinguished / Fellow | Company-wide technical direction |
+
+Management track:
+| Level | Title | Scope |
+|-------|-------|-------|
+| M1 | Manager | Team of 4–8 ICs |
+| M2 | Senior Manager | Manager of managers or larger team |
+| M3 | Director | Function or large org |
+| M4 | VP | Business unit, company-wide |
+| M5 | SVP / C-Suite | Executive |
+
+### Step 2: Gather market data
+
+**Data sources (by quality):**
+1. **Radford / Aon** — Gold standard. Expensive ($10K+/year). Worth it at Series B+.
+2. **Levels.fyi** — Excellent for engineering. Free. Self-reported but large sample.
+3. **Glassdoor Salary** — Broad coverage. Less precise for startups.
+4. **Pave / Carta Total Comp** — VC-backed companies. Good peer benchmarking.
+5. **LinkedIn Salary** — Free tier. Reasonable signal for G&A roles.
+6. **Offer letter data** — What candidates are bringing from other companies. Real-time signal.
+
+**What to pull:** P25, P50, P75, P90 for each role × level × geography.
+
+### Step 3: Set band structure
+
+**Band width (range within a level):**
+- IC bands: 80–120% of midpoint (i.e., ±20% from center)
+- Manager bands: 85–115% of midpoint
+- Wider bands allow room for differentiation within level; narrower bands reduce pay equity drift
+
+**Band overlap between levels:**
+- 10–20% overlap is normal (top of L2 overlaps with bottom of L3)
+- > 30% overlap: your levels are too close together
+- No overlap: new hires jump too much between levels (compression risk)
+
+**Example engineering band structure (US, Series B company, P50 target):**
+
+| Level | Band Min | Midpoint | Band Max |
+|-------|----------|----------|----------|
+| L1 Software Engineer | $90K | $105K | $125K |
+| L2 Software Engineer | $115K | $135K | $160K |
+| L3 Senior SWE | $150K | $175K | $205K |
+| L4 Staff SWE | $195K | $225K $260K |
+| M1 Eng Manager | $175K | $205K | $235K |
+| M2 Sr Eng Manager | $215K | $250K | $285K |
+| M3 Director, Eng | $255K | $300K | $345K |
+
+*Adjust by 15–25% for non-SF/NYC markets. Adjust -40% to -60% for European markets.*
+
+### Step 4: Place employees in bands
+
+**Compa-ratio** = Employee salary / Band midpoint
+
+| Compa-ratio | Interpretation |
+|------------|---------------|
+| < 0.85 | Below range — immediate risk |
+| 0.85–0.95 | Developing in role |
+| 0.95–1.05 | Fully performing (target zone) |
+| 1.05–1.15 | Senior/expert in role |
+| > 1.15 | Above range — flag for review |
+
+**Audit report:** Run quarterly. Flag anyone below 0.85 (flight risk) or above 1.15 (overpaid for level, or needs promotion).
+
+---
+
+## Equity Frameworks for Startups
+
+### Option Basics
+
+**ISO vs NSO:**
+- ISO (Incentive Stock Options): For employees. Favorable tax treatment if held 1+ year post-exercise.
+- NSO (Non-Qualified Stock Options): For advisors, contractors, sometimes employees. Taxed as ordinary income on exercise.
+
+**Strike price:** Set to 409A valuation at grant. Lower is better for employees. Early employees win on strike price.
+
+**Vesting schedule standards:**
+- 4-year vest, 1-year cliff: Standard
+- 4-year vest, 6-month cliff: Startup market adapting to faster pace
+- 1-year cliff means: nothing until 12 months; monthly or quarterly after
+
+**Post-termination exercise window (PTEW):**
+- Standard: 90 days. Often too short for employees who can't afford exercise.
+- Better: 1–5 years or until IPO. Use as a talent differentiator.
+- Companies extending PTEW: Stripe, Airbnb (pre-IPO), Square, most employee-friendly startups.
+
+### Equity Grant Ranges by Stage and Level
+
+*Expressed as % of fully diluted shares at grant. Ranges vary significantly by market, stage, and funding.*
+
+**Seed stage:**
+| Role | Equity % |
+|------|----------|
+| Co-founder | 20–40% |
+| First engineering hire | 0.5–1.5% |
+| First non-technical exec hire | 0.25–0.75% |
+| IC (L2-L3) | 0.1–0.4% |
+| IC (L3-L4) | 0.2–0.6% |
+
+**Series A:**
+| Role | Equity % |
+|------|----------|
+| VP / Head of function | 0.3–0.75% |
+| Director | 0.1–0.3% |
+| Senior IC (L3) | 0.05–0.15% |
+| Mid IC (L2) | 0.02–0.08% |
+| Junior IC (L1) | 0.01–0.05% |
+
+**Series B:**
+| Role | Equity % |
+|------|----------|
+| VP / Head of function | 0.1–0.3% |
+| Director | 0.05–0.15% |
+| Senior IC (L3) | 0.02–0.07% |
+| Mid IC (L2) | 0.01–0.03% |
+
+*At Series B+, equity is increasingly expressed in dollar value (grant value = X shares × current 409A). Use Carta or Pulley to model dilution.*
+
+### Equity Refresh Program
+
+**Why it matters:** Employees hired at Series A with 4-year vesting will be fully vested by Series B. No unvested equity = no retention hook.
+
+**When to refresh:**
+- After every significant funding round
+- Annually for high performers (top 20%)
+- After promotion (role-commensurate top-up)
+- Counter-offer situations (use carefully — signals you underpaid initially)
+
+**Refresh models:**
+1. **Anniversary grant:** Annual cliff-free refresh for all employees above a performance threshold
+2. **Evergreen model:** Continuous vesting maintained — refresh annually so employee always has 2–3 years remaining
+3. **Event-based:** Refresh tied to milestones (promotion, funding, annual review cycle)
+
+**Dilution awareness:** Every refresh dilutes existing shareholders. Model pool usage quarterly. Replenish option pool before it drops below 10–12% of fully diluted shares.
+
+---
+
+## Total Comp Modeling
+
+### Components of Total Comp
+
+```
+Total Compensation = Base Salary
+ + Annual Bonus (target %)
+ + Equity Value (annualized grant / vesting period)
+ + Benefits (employer-paid premiums, retirement match)
+ + Allowances (home office, internet, L&D, commuter)
+```
+
+### Annualizing Equity Value
+
+For comparison to cash compensation:
+
+```
+Annual equity value = (Grant shares × Current 409A price) / Vesting years
+```
+
+Example: 10,000 options at $2 strike, current 409A = $8, 4-year vest
+- Grant value at current 409A = 10,000 × $8 = $80,000
+- Annual value = $80,000 / 4 = $20,000/year
+- If base is $150K, total comp is ~$170K/year
+
+*Note: For recruiting purposes, you can use last preferred share price (VC price) to show upside — but be transparent about the difference between 409A and preferred.*
+
+### Benefits Valuation
+
+Frequently undervalued in offers. Quantify explicitly:
+| Benefit | Typical employer cost |
+|---------|----------------------|
+| Health insurance (employee) | $4K–8K/year |
+| Health insurance (family) | $15K–25K/year |
+| 401K match (4% of salary) | $5K–10K/year |
+| L&D budget ($2K/year) | $2K/year |
+| Home office stipend ($500) | $500/year |
+
+A $140K offer with family health coverage + 4% 401K match is worth $165K+ total.
+
+---
+
+## Raise and Refresh Process
+
+### Annual Compensation Review Cycle
+
+**Recommended cadence:**
+- October/November: Market data refresh, band updates
+- November/December: Manager merit recommendations
+- December/January: Calibration and approvals
+- January/February: Effective date for new salaries + equity grants
+
+**Budget allocation:**
+- **Merit budget** (performance-based raises): 3–5% of total payroll typically
+- **Market adjustment budget** (fixing below-band salaries): Separate from merit. Non-negotiable to avoid attrition.
+- **Promotion budget:** Separate. Promotions should not come from merit pool.
+
+### Merit Increase Guidelines
+
+| Performance Rating | Merit Increase Range |
+|-------------------|---------------------|
+| 5 – Exceptional | 8–15% |
+| 4 – Exceeds | 5–8% |
+| 3 – Meets | 2–4% |
+| 2 – Needs improvement | 0–1% |
+| 1 – Underperforming | 0% (PIP active) |
+
+*Adjust based on compa-ratio. A high performer at P90 of their band gets a smaller increase than a high performer at P50.*
+
+### Compa-Ratio Adjustment Matrix
+
+| Performance \ Compa-Ratio | < 0.90 | 0.90–1.00 | 1.00–1.10 | > 1.10 |
+|---------------------------|--------|-----------|-----------|--------|
+| Exceptional (5) | 12–15% | 8–12% | 5–8% | 3–5% |
+| Exceeds (4) | 8–12% | 5–8% | 3–5% | 1–3% |
+| Meets (3) | 5–8% | 3–5% | 2–3% | 0–2% |
+| Needs impr (2) | 0–2% | 0–1% | 0% | 0% |
+
+### Promotion vs. Merit — Keep These Separate
+
+**Common mistake:** Using merit budget to fund promotions. This forces a choice between rewarding performance and recognizing level change.
+
+**Promotion increase guidelines:**
+- One level (e.g., L2 → L3): 10–20% increase, new equity grant
+- Two levels (rare): 20–35% increase, new equity grant at new level
+- Manager track (IC → M1): 15–25% increase, new equity grant
+
+**Promotion criteria process:**
+1. Manager nominates with written business case
+2. Calibration committee reviews cross-functionally
+3. HR validates against band (no off-band exceptions without CHRO sign-off)
+4. Employee informed before annual review — never surprised at review meeting
+
+### Off-Cycle Adjustments
+
+When to do them:
+- Counter-offer situations (see below)
+- Competitive intelligence reveals underpay for a specific role
+- New market data shows a role significantly under-benchmarked
+- Internal equity audit reveals unexplained gaps
+
+**Counter-offer policy:**
+Three options:
+1. **Match** — Risk: signals you underpay; sets precedent
+2. **Partial match** — "We can do X, which is the top of your band" — cleaner
+3. **Decline** — Accept the attrition, improve the band for the next hire
+
+**Rule:** If you're regularly in counter-offer conversations, your bands are stale. Fix the bands.
+
+---
+
+## Pay Equity Audit
+
+Run annually. Non-negotiable at Series B+.
+
+**What to audit:**
+- Pay gap by gender within each level and function
+- Pay gap by ethnicity within each level and function
+- Compa-ratio distribution across demographics
+- Time-to-promotion by demographic group
+
+**Methodology:**
+1. Pull all employee data: level, function, salary, tenure, performance ratings, gender, ethnicity
+2. Run regression controlling for level, tenure, and performance
+3. Unexplained gap after controls = the problem to fix
+4. Flag and remediate within the same review cycle
+
+**Legal exposure:** In many jurisdictions, documented pay gaps without remediation plans are litigation risk. The audit creates a record of intent; remediation closes the risk.
+
+**Remediation budget:** Set aside 0.5–1% of payroll annually for equity adjustments. If you're doing it right, this shrinks over time.
diff --git a/skills/chro-advisor/references/org_design.md b/skills/chro-advisor/references/org_design.md
new file mode 100644
index 00000000..02498b54
--- /dev/null
+++ b/skills/chro-advisor/references/org_design.md
@@ -0,0 +1,333 @@
+# Org Design Reference
+
+Spans of control, layering decisions, reorgs, title frameworks, career ladders, and the founder→professional management transition.
+
+---
+
+## Core Org Design Principles
+
+1. **Structure follows strategy.** Reorg after strategy shifts, not before.
+2. **Optimize for the bottleneck.** Where does work get slow? Design around that.
+3. **Minimize coordination cost.** Conway's Law: your org structure becomes your product architecture. Design intentionally.
+4. **Bias toward flatness until it breaks.** Adding layers adds cost and slows decisions.
+5. **Reorgs have transition costs.** Relationships reset. Count the cost before you restructure.
+
+---
+
+## Spans of Control
+
+Span of control = number of direct reports a manager has.
+
+### Benchmarks
+
+| Role Type | Optimal Span | Min | Max |
+|-----------|-------------|-----|-----|
+| IC manager (predictable work) | 7–10 | 5 | 12 |
+| IC manager (complex/creative work) | 5–7 | 4 | 8 |
+| Manager of managers | 4–6 | 3 | 7 |
+| VP / Director | 4–7 | 3 | 8 |
+| C-Suite | 5–9 | 4 | 10 |
+
+**Too narrow (< 4 ICs):** Over-management, high cost per output, manager becomes a bottleneck
+**Too wide (> 12 ICs):** Under-management, degraded 1:1 quality, feedback loops collapse
+
+### Factors that allow wider spans
+- Highly autonomous, senior team (L3+ ICs)
+- Predictable, well-defined work (support, ops)
+- Strong tooling and process (reduces manager overhead)
+- Experienced manager
+
+### Factors that require narrower spans
+- High-complexity, undefined problems (research, early product)
+- Junior or newly promoted team members
+- High interdependence between reports (coordination overhead)
+- Manager is also an IC contributor (player-coach)
+
+---
+
+## When to Add Management Layers
+
+**The wrong reason to add layers:** "We need to give good people somewhere to grow."
+**The right reason:** "This manager has too many direct reports to do the job well."
+
+### Layer triggers by growth stage
+
+**0 → 15 people:** No layers. Everyone reports to founders.
+
+**15 → 30 people:** First managers emerge. Usually technical leads or function leads. Should still be player-coaches.
+
+**30 → 60 people:** Second layer forms. Engineering splits into squads. Sales gets a frontline manager. Each function has a head.
+
+**60 → 150 people:** Director layer becomes necessary in large functions. Engineering VP + Engineering Directors + Team Managers.
+
+**150+ people:** VP layer fully staffed. Senior Director / Director split. Clear IC → M → Senior M → Director → VP paths.
+
+### The Rule of 7
+
+When any manager has 7 or more direct reports and:
+- 1:1s are skipped regularly
+- Feedback quality drops
+- Manager can't answer "how is each person doing?" without checking notes
+
+→ Time to split or hire a manager.
+
+### Management overhead cost
+
+Every manager layer costs 10–15% in decision speed (communication hops).
+Every management role without a team = pure overhead.
+
+**Litmus test for each management role:**
+- Does this person have at least 4 ICs under them?
+- Would removing this role improve decision speed?
+- Is this a management job or a "we ran out of IC levels" job?
+
+---
+
+## Functional vs. Product Org Structures
+
+### Functional Structure (by discipline)
+
+```
+CEO
+├── VP Engineering
+│ ├── Backend Team
+│ ├── Frontend Team
+│ └── DevOps
+├── VP Product
+│ ├── PM (Feature A)
+│ └── PM (Feature B)
+└── VP Design
+ └── UX Designers
+```
+
+**Best for:** Early stage, < 100 people, single product
+**Advantage:** Deep expertise development, clear career paths per discipline
+**Disadvantage:** Cross-functional coordination is heavy; features require synchronization across silos
+
+### Product/Pod Structure (by product area)
+
+```
+CEO
+├── Product Area A (autonomous team)
+│ ├── EM
+│ ├── PM
+│ └── Designer
+├── Product Area B (autonomous team)
+│ ├── EM
+│ ├── PM
+│ └── Designer
+└── Platform (shared services)
+ └── Platform EM + team
+```
+
+**Best for:** Multiple products or large user segments, 50+ in product/eng
+**Advantage:** Speed and autonomy; less cross-team coordination for most features
+**Disadvantage:** Duplication risk; harder to maintain technical coherence; harder career paths
+
+### When to shift from Functional → Product org
+- You have 2+ distinct product lines that rarely share features
+- Cross-functional feature delivery takes > 3 sprints of coordination overhead
+- Teams are > 8 engineers and still waiting on shared resources
+
+### Hybrid / Matrix (avoid unless necessary)
+Matrix reporting (e.g., engineer reports to EM + PM) creates accountability confusion. Avoid at < 500 people.
+
+---
+
+## Title Frameworks
+
+### The Problem with Title Inflation
+
+Early startups over-title to compete with cash. "VP of Engineering" with 2 reports. "Head of Marketing" with no team.
+
+**Consequences:**
+- Can't add leadership above inflated titles without awkward conversations
+- Candidates from mature companies expect scope commensurate with titles
+- Internal equity breaks when the same title means different things
+
+### Preventing Title Inflation
+
+**Rule 1:** VP titles require managing managers (not just ICs).
+**Rule 2:** Director titles require managing multiple ICs or a large function.
+**Rule 3:** No more than one "Head of X" per function.
+**Rule 4:** Document scope expectations per title before making offers.
+
+### Engineering Title Ladder (example)
+
+| Title | Level | Scope | Reports |
+|-------|-------|-------|---------|
+| Software Engineer I | L1 | Executes defined tasks | — |
+| Software Engineer II | L2 | Independent delivery | — |
+| Senior Software Engineer | L3 | Leads features, mentors | — |
+| Staff Software Engineer | L4 | Cross-team technical leadership | — |
+| Principal Software Engineer | L5 | Company-wide technical direction | — |
+| Distinguished Engineer | L6 | External recognition, defining practice | — |
+| Engineering Manager | M1 | Team of 4–8 engineers | 4–8 ICs |
+| Senior Engineering Manager | M2 | Larger team or manager of managers | 2–4 managers |
+| Director of Engineering | M3 | Functional area | Multiple managers |
+| VP of Engineering | M4 | Engineering org | Directors |
+| CTO | M5 | Technical organization + strategy | VPs |
+
+**IC vs. Management track:** Explicitly separate. Senior ICs should not need to move to management for career advancement. Staff/Principal/Distinguished track provides this.
+
+### Go-to-Market Title Ladder (example)
+
+| Title | Level | Focus |
+|-------|-------|-------|
+| SDR / BDR | S1 | Outbound prospecting |
+| Account Executive I | S2 | SMB closing |
+| Account Executive II | S3 | Mid-market closing |
+| Senior Account Executive | S4 | Enterprise closing |
+| Principal / Strategic AE | S5 | Named accounts, complex deals |
+| Sales Manager | M1 | 6–8 reps |
+| Director of Sales | M2 | Multiple teams or segments |
+| VP of Sales | M3 | Full sales org |
+| CRO | M4 | Revenue org (sales + CS + marketing) |
+
+---
+
+## Career Ladders
+
+A career ladder is a documented set of expectations per level. Not aspirational — behavioral. "What does a P3 engineer do that a P2 doesn't?"
+
+### Why career ladders matter for HR
+
+1. **Retention:** Employees can see where they're going
+2. **Consistency:** Managers use the same criteria for promotions
+3. **Compensation:** Bands anchor to levels; levels require definitions
+4. **Equity:** Removes "who's the manager's favorite" from promotion decisions
+
+### Career Ladder Structure
+
+For each level, define 4 dimensions:
+
+**1. Scope** — How big is the problem space? Team / cross-team / org-wide / company-wide?
+**2. Impact** — How does work connect to outcomes? (Task → Feature → Product → Business)
+**3. Craft** — Technical/functional skill expectations
+**4. Influence** — How does this person improve others? (Self → peers → team → org)
+
+**Example: Senior Software Engineer (L3) vs. Staff Software Engineer (L4)**
+
+| Dimension | L3 (Senior SWE) | L4 (Staff SWE) |
+|-----------|----------------|----------------|
+| Scope | Owns features or services | Owns technical domains across teams |
+| Impact | Ships features that improve user outcomes | Shapes technical direction for a product area |
+| Craft | Writes high-quality code, good design skills | Sets coding standards, contributes to architecture |
+| Influence | Mentors L1–L2, code reviews | Mentors L3+, identifies org-wide technical gaps |
+
+### How to build a career ladder from scratch
+
+1. **Interview your best performers** — "What do you do that your junior peers don't?" Collect behaviors, not aspirations.
+2. **Draft 3 levels** — Don't start with 6. Start with junior, mid, senior. Add staff/principal only when you have enough people to warrant it.
+3. **Manager calibration** — Every manager rates 5 current employees against the draft. Gaps surface immediately.
+4. **Publish and iterate** — Don't wait for perfection. A 70% ladder shipped is better than a 100% ladder in a drawer.
+
+---
+
+## Reorg Playbook
+
+### When reorgs are necessary
+- Strategy pivot requires different team structure (e.g., single product → multi-product)
+- Acquisition or team merger
+- Function is genuinely too slow due to coordination overhead
+- Leadership departure creates structural opportunity
+
+### When reorgs are a mistake
+- "We need to shake things up" (disruption for its own sake)
+- Avoiding a specific personnel decision (use the right tool)
+- Solving a cultural problem with a structural change
+- Reacting to one team's complaint without systemic evidence
+
+### Reorg Process (4–8 weeks)
+
+**Week 1–2: Diagnose**
+- Map current org: every role, reporting line, team output
+- Identify where work is slow, duplicated, or falling through cracks
+- Interview 5–10 people across teams: "What takes longer than it should? What decisions are hard to make?"
+
+**Week 3–4: Design options**
+- Draft 2–3 structural alternatives
+- For each: estimated coordination costs, manager span impact, open roles created
+- Validate with CEO + 1–2 trusted operators. Don't crowdsource the design.
+
+**Week 5–6: Decide and prepare**
+- Select option; finalize all reporting changes
+- Prepare communications for every affected person (individual conversations before all-hands)
+- Write the "why" — employees need to understand the business reason, not just the result
+
+**Week 7–8: Communicate and implement**
+- Individual conversations with all manager+ changes (first)
+- Team-level conversations with managers (second)
+- All-hands with full context (third)
+- Updated org chart published within 24 hours of announcement
+
+### Communication sequence (non-negotiable)
+
+1. Affected individuals first (private, before anything else)
+2. Affected managers second (to prepare for team conversations)
+3. Full team/company third (all-hands or company note)
+4. External (clients, board) only if materially impacted
+
+**Never:** Email blast first. No individual conversations. Discovered on the org chart.
+
+---
+
+## Founder → Professional Management Transition
+
+The most common scaling failure point in startups.
+
+### Stage 1: Founder-Led (0–30 people)
+
+Founders make all decisions, know everyone personally, set culture through behavior. Works because trust and context are built directly.
+
+**What breaks:**
+- Decisions bottleneck at founders
+- New hires don't get enough context (founders can't be everywhere)
+- Culture transmitted through osmosis, not documentation
+
+### Stage 2: First Managers (30–80 people)
+
+Founders can no longer manage all ICs. First manager layer typically = promoted high performers.
+
+**The "brilliant IC → struggling manager" trap:**
+- Individual contributor skills ≠ management skills
+- Promoted ICs often continue doing IC work while ignoring management work
+- No one holds them accountable to management output (1:1 quality, team health, performance feedback)
+
+**What to do:**
+- Explicit manager training before promotion (not after)
+- Management KPIs separate from IC KPIs
+- Peer community for new managers (monthly cohort session)
+- HR check-ins on manager health at 30/60/90 days
+
+### Stage 3: Professional Management (80–200 people)
+
+External hires at Director/VP level bring professional management skills but lack company context.
+
+**Common failure modes:**
+- Hired "too senior" — VP who's used to 200-person teams in a 50-person function
+- Culture clash — Big-company manager who adds process that kills startup speed
+- Authority vacuum — External VP doesn't earn trust; team ignores them; founder continues to bypass hierarchy
+
+**Mitigation:**
+- Hiring bar: Has this person scaled from this stage to 2x this stage before? Not managed a team at 2x — built a team to 2x.
+- Explicit onboarding on "how we make decisions here"
+- 90-day milestones focused on relationship-building before any structural changes
+- Founders explicitly hand off ownership and reinforce new manager's authority publicly
+
+### Stage 4: Founder Transition from Operator to Executive
+
+The hardest personal transition. Founder moves from doing to enabling.
+
+**Signs you haven't made the transition:**
+- You're still in every technical decision
+- Teams come to you instead of their manager for approvals
+- You know more about the team's work than the manager does
+- Managers feel they need to check in before acting
+
+**What the transition requires:**
+- Explicit authority delegation in writing (not just verbal)
+- Willingness to let managers make decisions you'd make differently
+- Redirecting team members to their manager consistently
+- Measuring managers on outcomes, not just process adherence
+- Letting managers hire and fire without founder override (except final call on VPs)
diff --git a/skills/chro-advisor/references/people_strategy.md b/skills/chro-advisor/references/people_strategy.md
new file mode 100644
index 00000000..c01d6e54
--- /dev/null
+++ b/skills/chro-advisor/references/people_strategy.md
@@ -0,0 +1,320 @@
+# People Strategy Reference
+
+Hiring, retention, performance, and remote/hybrid frameworks for each growth stage.
+
+---
+
+## Hiring Strategy by Growth Stage
+
+### Pre-Seed / Seed (1–15 people)
+
+**Who you're hiring:** Generalists who can do multiple jobs. Specialists are a luxury you can't afford unless the specialty is your core product.
+
+**The test:** Could this person be the 5th employee at a startup and thrive? If they need a defined role, clear process, and a manager — not yet.
+
+**Sourcing at this stage:**
+- Founder networks first (highest signal, lowest cost)
+- Angel List / Wellfound — self-selected for startup risk tolerance
+- Referrals from existing employees (offer a referral bonus from day 1)
+- GitHub / Dribbble / published work for technical roles
+- Avoid: Big job boards, recruiters (unless technical retained search for C-suite)
+
+**Interview process (keep it lean):**
+1. 30-min intro call (culture/motivation fit, comp alignment)
+2. Take-home or live work sample (2–4 hours max, paid for senior roles)
+3. 60-min deep-dive with founders
+4. Reference checks (3 calls, not emails — you want the real story)
+
+**Offer timeline:** Decision within 48 hours. Top candidates have multiple offers.
+
+**What to get right:**
+- Written job scorecard (outcomes expected in 30/60/90 days) — not a job description
+- Equity range disclosed in first conversation
+- No exploding offers. Pressure tactics lose good people.
+
+---
+
+### Series A (15–50 people)
+
+**The hiring shift:** You need some specialists now. First management layer emerges. First "culture carries" — people who reinforce what you want to become.
+
+**Critical hires at this stage (in priority order):**
+1. VP/Head of Engineering (if founder isn't technical)
+2. Head of Product
+3. First dedicated recruiter (when you're hiring > 10/year)
+4. First Finance/Operations hire
+5. Head of Sales (when product-market fit is real)
+
+**Building the recruiting function:**
+- First recruiter should be a generalist with hustle, not a specialist
+- Set up an ATS (Ashby, Greenhouse, or Lever) before you need it — not after
+- Create interview scorecards for every role
+- Track: time to fill, offer acceptance rate, source quality
+
+**Common mistakes at Series A:**
+- Promoting top ICs to management without management training
+- Hiring "brand name" executives who've never operated lean
+- Over-indexing on experience, under-indexing on trajectory
+- No onboarding process → 90-day regrettable turnover
+
+**Job scorecards (required for every role):**
+```
+Role: [Title]
+Reports to: [Manager]
+Start date: [Target]
+Why this role now: [Business case in 1-2 sentences]
+
+Outcomes (90 days):
+- [Concrete deliverable 1]
+- [Concrete deliverable 2]
+- [Concrete deliverable 3]
+
+Outcomes (12 months):
+- [Strategic impact 1]
+- [Strategic impact 2]
+
+Competencies (top 3 only):
+- [What, why it matters for THIS role]
+- [What, why it matters for THIS role]
+- [What, why it matters for THIS role]
+
+Comp range: [Base] + [Equity] + [Benefits summary]
+```
+
+---
+
+### Series B (50–150 people)
+
+**The scaling inflection point.** Tribal knowledge breaks. Process matters now. Culture requires deliberate investment.
+
+**What changes:**
+- Recruiters become specialists (technical, GTM, exec)
+- Manager training becomes non-negotiable
+- Performance management needs structure (not just "we'll know it when we see it")
+- Onboarding needs to scale without founders in every session
+- Comp bands become essential — people are comparing notes
+
+**Hiring velocity benchmarks (Series B):**
+| Function | Avg time to fill | Avg interviews | Benchmark offer acceptance |
+|----------|-----------------|----------------|---------------------------|
+| Engineering IC | 35–45 days | 4–5 rounds | 80–85% |
+| Engineering Manager | 45–60 days | 5–6 rounds | 75–80% |
+| Sales IC | 25–35 days | 3–4 rounds | 85–90% |
+| Sales Manager | 40–55 days | 4–5 rounds | 80–85% |
+| G&A (Finance, HR, Ops) | 30–45 days | 3–4 rounds | 85–90% |
+
+**Internal mobility:** By 50 people, start tracking internal promotion rates. Target: 20–30% of manager+ roles filled internally. If it's < 10%, your career development is failing.
+
+---
+
+### Series C+ (150+ people)
+
+**Professional management era.** Founders can't know everyone. Systems and culture carry what personal relationships used to.
+
+**HR function maturity required:**
+- Dedicated HRBPs per business unit (1:75–100 employees)
+- L&D budget (1–2% of salary budget minimum)
+- Succession planning for all VP+ roles
+- Structured calibration process for performance reviews
+- Total rewards strategy reviewed annually with board
+
+---
+
+## Retention Programs That Actually Work
+
+### What drives retention (in order of impact)
+
+1. **Manager quality** — Gallup: 70% of team engagement variance is explained by the manager. Fix managers first.
+2. **Growth trajectory** — People leave when they can't see their next role. Career ladders are retention tools.
+3. **Compensation competitiveness** — Being at P25 on salary is a slow leak. Audit annually.
+4. **Mission/product belief** — Especially for senior ICs. They want to work on something that matters.
+5. **Team quality** — "I stay because of the people I work with." True at every level.
+6. **Flexibility** — Location, hours, autonomy. Low cost, high impact.
+
+### What doesn't work (but companies do anyway)
+- Pizza parties and ping pong tables
+- "Perks" that substitute for salary
+- Annual reviews with no action on feedback
+- Forced fun events
+- Vague "culture improvement" initiatives without specific behavior changes
+
+### The 30-60-90 Onboarding Framework
+
+Structured onboarding cuts 90-day turnover by 50%+.
+
+**Days 1–30: Learn**
+- Complete admin setup (day 1, before lunch)
+- Meet all key stakeholders (scheduled by their manager, not on the new hire)
+- Understand: business model, current priorities, team processes, how success is measured
+- No deliverables expected. Learning is the job.
+- Weekly 1:1 with manager: "What's confusing? What do you need?"
+
+**Days 31–60: Contribute**
+- First real project (scoped to be completable)
+- Present findings or work to the team
+- Identify one process that could be improved (observation only — don't fix yet)
+- 30-day check-in: formal feedback from manager
+
+**Days 61–90: Lead**
+- Own a deliverable end-to-end
+- Offer one specific improvement recommendation with data
+- 90-day review: mutual assessment — manager on new hire, new hire on onboarding
+- Set 6-month goals
+
+### Stay Interviews (underused, high ROI)
+
+Run with every employee once per year. Not their manager — HR or skip-level.
+
+**Questions that surface real risk:**
+- "What's keeping you here?"
+- "What would make you consider leaving?"
+- "What's one thing your manager could do differently?"
+- "Is your role what you expected when you joined?"
+- "What career path do you want? Are we helping you get there?"
+- "Are you fairly compensated? Do you know how you'd get a raise?"
+
+**Act on answers within 30 days or don't ask.** Unanswered feedback is worse than no feedback.
+
+### Exit Interviews — What to Actually Learn
+
+Skip the happiness survey. Ask these:
+- "When did you first think about leaving?"
+- "Was there a specific event that triggered your decision?"
+- "What could we have done to retain you?"
+- "Where are you going and why?" (What does the other offer have that we don't?)
+- "Would you recommend us as an employer? Why or why not?"
+
+Track exit themes by manager. If one manager's exits cite "micromanagement" three times — that's data.
+
+---
+
+## Performance Management
+
+### The System That Works
+
+**Continuous > annual.** Annual reviews with no mid-year touchpoints are theater.
+
+**Structure:**
+- **Weekly 1:1s** (30 min): blockers, priorities, relationship
+- **Monthly check-ins** (1 hr): progress against goals, feedback exchange
+- **Quarterly reviews** (formal): written self-assessment + manager assessment + goal revision
+- **Annual calibration** (rating + comp): cross-manager calibration session, then individual conversations
+
+### Calibration Sessions
+
+**Purpose:** Prevent manager bias. Ensure "exceeds expectations" means the same thing across teams.
+
+**Process:**
+1. Managers submit preliminary ratings independently
+2. HR facilitates 2-hr calibration with all managers in a function
+3. Managers must justify outliers (top and bottom)
+4. Ratings adjusted for consistency
+5. Managers deliver final ratings with rationale
+
+**Distribution guidance (enforce with calibration):**
+- Exceptional (5): < 10% — if everyone's exceptional, no one is
+- Exceeds (4): 20–25%
+- Meets (3): 55–65%
+- Needs improvement (2): 8–12%
+- Underperforming (1): 2–5%
+
+### Managing Underperformers
+
+**The most avoided management task. And the most damaging when avoided.**
+
+High performers notice when underperformers are tolerated. They leave.
+
+**The 4-step framework:**
+
+**Step 1: Diagnose before acting** (Week 1–2)
+- Is this a skill gap (can't do it) or a will gap (won't do it)?
+- Skill gap → training, clearer expectations, different role
+- Will gap → direct feedback, clear consequences, then PIP
+
+**Step 2: Direct feedback conversation** (Week 2–3)
+- Specific: "Your last 3 sprint deliveries were 40% incomplete"
+- Not: "You're not meeting expectations"
+- Document. Send written summary after every feedback conversation.
+
+**Step 3: Performance Improvement Plan (PIP)**
+Required when: two rounds of direct feedback haven't produced change.
+
+PIP structure:
+```
+Name: [Employee]
+Manager: [Name]
+Date: [Start]
+Review date: [30/60 days out]
+
+Current performance issues:
+- [Specific, observable behavior with examples and dates]
+- [Metric not met: target X, actual Y for Z weeks]
+
+Required improvements:
+- [Specific, measurable outcome 1] by [date]
+- [Specific, measurable outcome 2] by [date]
+
+Support provided:
+- [Training, coaching, additional resources]
+
+Consequences if not met: [Role change / separation]
+
+Check-in schedule: [Weekly with manager + HR]
+```
+
+**Step 4: Exit or role change**
+- If PIP milestones not met: proceed to separation
+- Don't extend PIPs indefinitely — it's unfair to the employee and the team
+- Offer a graceful exit where possible: "This role isn't the right fit. Here's a package and a reference."
+
+**What not to do:**
+- "Quiet manage out" without clear feedback (legally risky, unfair)
+- PIP as a formality before termination (if you know you're firing them, just do it)
+- Tolerating underperformance "because we're understaffed" (it makes understaffing worse)
+
+---
+
+## Remote / Hybrid Strategy
+
+### The question isn't "remote or not" — it's "what kind of collaboration does our work require?"
+
+**Work type taxonomy:**
+| Work type | Remote-compatible? | Hybrid compatible? |
+|-----------|-------------------|-------------------|
+| Deep individual work (coding, writing, analysis) | Yes | Yes |
+| Async collaboration (code review, doc review) | Yes | Yes |
+| Synchronous problem-solving (debugging, design) | Yes (video) | Yes |
+| Relationship-building (onboarding, new team) | Harder | Yes |
+| Executive alignment, strategy | Harder | Yes — quarterly in-person |
+| Sales (enterprise, relationship-based) | No | Depends on market |
+
+### Making Hybrid Work (Not Just a Policy)
+
+**The failure mode:** "Hybrid" = go to office on Tuesday/Thursday, but no one coordinates, all meetings are still Zoom anyway.
+
+**What actually works:**
+
+1. **Anchor days with purpose** — Office days should have things that require the office: workshops, team rituals, whiteboarding sessions. Not just "presence."
+
+2. **Async-first culture, not async-only** — Document decisions. Write things down. Use Loom for walkthroughs. Reduce "quick sync" meetings.
+
+3. **Equal experience for remote participants** — If some are in the room and some are on video, the remote folks are second-class. Either everyone's remote or set up rooms properly.
+
+4. **Manager standards for remote teams:**
+ - 1:1s are non-negotiable (video, not async)
+ - Over-communicate on priorities (people can't absorb hallway context)
+ - Write down decisions (remote employees miss casual office decisions)
+ - Recognize work publicly (Slack shoutouts, all-hands wins)
+
+### Remote Compensation Philosophy (pick one, be explicit)
+
+**Option A: Location-based pay**
+Pay based on where the employee lives. Lower cost in lower-cost markets. Harder to hire in high-cost cities.
+
+**Option B: Role-based (location-neutral)**
+One band for each role regardless of location. Simpler, more equitable. Higher overall payroll cost.
+
+**Option C: Zone-based**
+Define 2–3 geographic zones (e.g., Tier 1 cities, Tier 2 cities, international). Set bands per zone. Common at mid-stage startups.
+
+**The wrong answer:** No stated policy, and every offer is negotiated individually. Creates pay equity problems fast.
diff --git a/skills/chro-advisor/scripts/comp_benchmarker.py b/skills/chro-advisor/scripts/comp_benchmarker.py
new file mode 100644
index 00000000..5102fec3
--- /dev/null
+++ b/skills/chro-advisor/scripts/comp_benchmarker.py
@@ -0,0 +1,613 @@
+#!/usr/bin/env python3
+"""
+Compensation Benchmarker
+========================
+Salary benchmarking and total comp modeling for startup teams.
+Analyzes pay equity, compa-ratios, and total comp vs. market.
+
+Usage:
+ python comp_benchmarker.py # Run with built-in sample data
+ python comp_benchmarker.py --config roster.json # Load from JSON
+ python comp_benchmarker.py --help
+
+Output: Band compliance report, compa-ratio distribution, pay equity flags,
+ equity value analysis, and total comp vs. market.
+"""
+
+import argparse
+import json
+import csv
+import io
+import sys
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+from datetime import date
+import math
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BandDefinition:
+ """Salary band for a role level."""
+ level: str # L1, L2, L3, L4, M1, M2, M3, VP
+ function: str # Engineering, Sales, Product, G&A, Marketing, CS
+ band_min: int # Annual USD
+ band_mid: int # P50 anchor
+ band_max: int # Band ceiling
+ market_p25: int # Market 25th percentile
+ market_p50: int # Market median (should align with band_mid for P50 strategy)
+ market_p75: int # Market 75th percentile
+ location_zone: str # Tier1 (SF/NYC), Tier2 (Austin/Denver), Tier3 (Remote/other), EU
+
+
+@dataclass
+class Employee:
+ """One employee record."""
+ id: str
+ name: str
+ role: str
+ level: str
+ function: str
+ location_zone: str
+ base_salary: int
+ bonus_target_pct: float # % of base
+ equity_shares: int # Total unvested options/RSUs
+ equity_strike: float # Strike price (0 for RSUs)
+ equity_current_409a: float # Current 409A share price
+ equity_vest_years_remaining: float # How many years of vesting remain
+ benefits_annual: int # Employer-paid benefits cost
+ gender: str # M/F/NB/Undisclosed (for equity audit)
+ ethnicity: str # For equity audit — can be "Undisclosed"
+ tenure_years: float
+ performance_rating: int # 1–5
+ last_raise_months_ago: int
+ last_equity_refresh_months_ago: Optional[int] = None
+
+
+@dataclass
+class CompRoster:
+ company: str
+ as_of_date: str # ISO date
+ funding_stage: str # Seed, Series A, Series B, etc.
+ comp_philosophy_target: str # P50, P65, P75 — your target percentile
+ preferred_stock_price: float # Last round price (for offer modeling)
+ employees: list[Employee] = field(default_factory=list)
+ bands: list[BandDefinition] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Band lookup
+# ---------------------------------------------------------------------------
+
+def find_band(roster: CompRoster, level: str, function: str, zone: str) -> Optional[BandDefinition]:
+ """Find best-matching band. Falls back to any matching level+function if zone not found."""
+ matches = [b for b in roster.bands if b.level == level and b.function == function and b.location_zone == zone]
+ if matches:
+ return matches[0]
+ # Fallback: same level+function, any zone
+ matches = [b for b in roster.bands if b.level == level and b.function == function]
+ if matches:
+ return matches[0]
+ # Fallback: same level, any function
+ matches = [b for b in roster.bands if b.level == level]
+ if matches:
+ return matches[0]
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Compensation analysis
+# ---------------------------------------------------------------------------
+
+def compa_ratio(salary: int, band_mid: int) -> float:
+ return salary / band_mid if band_mid > 0 else 0.0
+
+
+def band_position(salary: int, band_min: int, band_max: int) -> float:
+ """Position in band: 0.0 = at min, 1.0 = at max."""
+ if band_max == band_min:
+ return 0.5
+ return (salary - band_min) / (band_max - band_min)
+
+
+def annualized_equity_value(emp: Employee) -> int:
+ """Current 409A value of unvested equity, annualized."""
+ if emp.equity_vest_years_remaining <= 0:
+ return 0
+ if emp.equity_current_409a > emp.equity_strike:
+ intrinsic = (emp.equity_current_409a - emp.equity_strike) * emp.equity_shares
+ else:
+ # Options underwater — still show at current FMV for RSUs or future value for options
+ intrinsic = emp.equity_current_409a * emp.equity_shares if emp.equity_strike == 0 else 0
+ return int(intrinsic / emp.equity_vest_years_remaining)
+
+
+def total_comp(emp: Employee) -> int:
+ bonus = int(emp.base_salary * emp.bonus_target_pct)
+ equity = annualized_equity_value(emp)
+ return emp.base_salary + bonus + equity + emp.benefits_annual
+
+
+def analyze_employee(emp: Employee, roster: CompRoster) -> dict:
+ band = find_band(roster, emp.level, emp.function, emp.location_zone)
+ result = {
+ "id": emp.id,
+ "name": emp.name,
+ "role": emp.role,
+ "level": emp.level,
+ "function": emp.function,
+ "zone": emp.location_zone,
+ "base": emp.base_salary,
+ "bonus_target": int(emp.base_salary * emp.bonus_target_pct),
+ "equity_annual": annualized_equity_value(emp),
+ "benefits": emp.benefits_annual,
+ "total_comp": total_comp(emp),
+ "performance": emp.performance_rating,
+ "tenure_years": emp.tenure_years,
+ "last_raise_months": emp.last_raise_months_ago,
+ "band": band,
+ "compa_ratio": None,
+ "band_position": None,
+ "vs_market_p50": None,
+ "flags": [],
+ }
+
+ if band:
+ cr = compa_ratio(emp.base_salary, band.band_mid)
+ bp = band_position(emp.base_salary, band.band_min, band.band_max)
+ result["compa_ratio"] = round(cr, 3)
+ result["band_position"] = round(bp, 3)
+ result["vs_market_p50"] = round((emp.base_salary - band.market_p50) / band.market_p50 * 100, 1)
+
+ # Flags
+ if emp.base_salary < band.band_min:
+ result["flags"].append(("CRITICAL", "Base below band minimum — immediate attrition risk"))
+ elif cr < 0.88:
+ result["flags"].append(("HIGH", f"Compa-ratio {cr:.2f} — significantly below midpoint"))
+ elif cr < 0.93:
+ result["flags"].append(("MEDIUM", f"Compa-ratio {cr:.2f} — below target zone (0.95–1.05)"))
+
+ if emp.base_salary > band.band_max:
+ result["flags"].append(("HIGH", "Base above band maximum — review for promotion or band update"))
+
+ if emp.performance_rating >= 4 and cr < 0.95:
+ result["flags"].append(("HIGH", f"High performer (rating {emp.performance_rating}) underpaid — flight risk"))
+
+ if emp.last_raise_months_ago > 18:
+ result["flags"].append(("MEDIUM", f"No raise in {emp.last_raise_months_ago} months — review due"))
+
+ if emp.equity_vest_years_remaining < 1.0 and (emp.last_equity_refresh_months_ago is None or emp.last_equity_refresh_months_ago > 24):
+ result["flags"].append(("HIGH", "Equity nearly fully vested with no refresh — retention hook gone"))
+
+ else:
+ result["flags"].append(("INFO", "No band found for this level/function/zone"))
+
+ return result
+
+
+# ---------------------------------------------------------------------------
+# Aggregate analysis
+# ---------------------------------------------------------------------------
+
+def pay_equity_audit(analyses: list[dict], employees: list[Employee]) -> dict:
+ """Simple pay equity analysis by gender and ethnicity."""
+ emp_by_id = {e.id: e for e in employees}
+
+ def group_stats(group_key_fn):
+ groups: dict[str, list[float]] = {}
+ for a in analyses:
+ if a["compa_ratio"] is None:
+ continue
+ emp = emp_by_id.get(a["id"])
+ if not emp:
+ continue
+ key = group_key_fn(emp)
+ if key not in groups:
+ groups[key] = []
+ groups[key].append(a["compa_ratio"])
+ return {k: {"n": len(v), "avg_cr": round(sum(v)/len(v), 3), "min_cr": round(min(v), 3), "max_cr": round(max(v), 3)}
+ for k, v in groups.items() if v}
+
+ gender_stats = group_stats(lambda e: e.gender)
+ ethnicity_stats = group_stats(lambda e: e.ethnicity)
+
+ # Compute gap vs. the largest group
+ def compute_gap(stats: dict) -> dict[str, float]:
+ if not stats:
+ return {}
+ largest = max(stats.items(), key=lambda x: x[1]["n"])
+ ref_cr = largest[1]["avg_cr"]
+ return {k: round((v["avg_cr"] - ref_cr) / ref_cr * 100, 1) for k, v in stats.items()}
+
+ gender_gaps = compute_gap(gender_stats)
+ ethnicity_gaps = compute_gap(ethnicity_stats)
+
+ return {
+ "gender": gender_stats,
+ "gender_gaps_pct": gender_gaps,
+ "ethnicity": ethnicity_stats,
+ "ethnicity_gaps_pct": ethnicity_gaps,
+ }
+
+
+def compa_ratio_distribution(analyses: list[dict]) -> dict:
+ crs = [a["compa_ratio"] for a in analyses if a["compa_ratio"] is not None]
+ if not crs:
+ return {}
+ buckets = {
+ "< 0.85 (below band)": 0,
+ "0.85–0.94 (developing)": 0,
+ "0.95–1.05 (target zone)": 0,
+ "1.06–1.15 (senior in role)": 0,
+ "> 1.15 (above band)": 0,
+ }
+ for cr in crs:
+ if cr < 0.85:
+ buckets["< 0.85 (below band)"] += 1
+ elif cr < 0.95:
+ buckets["0.85–0.94 (developing)"] += 1
+ elif cr <= 1.05:
+ buckets["0.95–1.05 (target zone)"] += 1
+ elif cr <= 1.15:
+ buckets["1.06–1.15 (senior in role)"] += 1
+ else:
+ buckets["> 1.15 (above band)"] += 1
+ avg = sum(crs) / len(crs)
+ return {"distribution": buckets, "avg_compa_ratio": round(avg, 3), "n": len(crs)}
+
+
+# ---------------------------------------------------------------------------
+# Report output
+# ---------------------------------------------------------------------------
+
+def fmt(n) -> str:
+ return f"${int(n):,.0f}"
+
+
+def bar(value: float, width: int = 20) -> str:
+ filled = min(width, max(0, int(value * width)))
+ return "█" * filled + "░" * (width - filled)
+
+
+def print_report(roster: CompRoster):
+ WIDTH = 76
+ SEP = "=" * WIDTH
+ sep = "-" * WIDTH
+
+ analyses = [analyze_employee(e, roster) for e in roster.employees]
+ cr_dist = compa_ratio_distribution(analyses)
+ equity_audit = pay_equity_audit(analyses, roster.employees)
+
+ print(SEP)
+ print(f" COMPENSATION BENCHMARKING REPORT — {roster.company}")
+ print(f" As of: {roster.as_of_date} | Stage: {roster.funding_stage} | Target: {roster.comp_philosophy_target}")
+ print(SEP)
+
+ # Summary stats
+ total_emps = len(roster.employees)
+ flagged = sum(1 for a in analyses if any(s in ["CRITICAL", "HIGH"] for s, _ in a["flags"]))
+ total_payroll = sum(e.base_salary for e in roster.employees)
+ avg_total_comp = sum(a["total_comp"] for a in analyses) // total_emps if total_emps else 0
+
+ print(f"\n[ SUMMARY ]")
+ print(sep)
+ print(f" Employees analyzed: {total_emps}")
+ print(f" Flagged (critical/high): {flagged}")
+ print(f" Total base payroll: {fmt(total_payroll)}/year")
+ print(f" Avg total comp: {fmt(avg_total_comp)}/year")
+ if cr_dist:
+ print(f" Avg compa-ratio: {cr_dist['avg_compa_ratio']:.3f}")
+
+ # Compa-ratio distribution
+ if cr_dist:
+ print(f"\n[ COMPA-RATIO DISTRIBUTION ]")
+ print(sep)
+ total_n = cr_dist["n"]
+ for label, count in cr_dist["distribution"].items():
+ pct = count / total_n if total_n else 0
+ bar_str = bar(pct, 25)
+ print(f" {label:<30} {bar_str} {count:3d} ({pct*100:4.0f}%)")
+
+ # Pay equity audit
+ print(f"\n[ PAY EQUITY AUDIT ]")
+ print(sep)
+
+ print(f" By Gender:")
+ for group, stats in equity_audit["gender"].items():
+ gap = equity_audit["gender_gaps_pct"].get(group, 0.0)
+ gap_str = f" gap: {gap:+.1f}%" if gap != 0 else " (reference group)"
+ flag = " ⚠" if abs(gap) > 5 else ""
+ print(f" {group:<15} n={stats['n']} avg_CR={stats['avg_cr']:.3f}{gap_str}{flag}")
+
+ print(f"\n By Ethnicity:")
+ for group, stats in equity_audit["ethnicity"].items():
+ gap = equity_audit["ethnicity_gaps_pct"].get(group, 0.0)
+ gap_str = f" gap: {gap:+.1f}%" if gap != 0 else " (reference group)"
+ flag = " ⚠" if abs(gap) > 5 else ""
+ print(f" {group:<20} n={stats['n']} avg_CR={stats['avg_cr']:.3f}{gap_str}{flag}")
+
+ print(f"\n ⚠ = gap > 5%. Investigate with regression controlling for level, tenure, and performance.")
+
+ # Employee detail with flags
+ print(f"\n[ EMPLOYEE DETAIL ]")
+ print(sep)
+
+ # Group by function
+ functions = sorted(set(e.function for e in roster.employees))
+ for fn in functions:
+ fn_analyses = [a for a in analyses if a["function"] == fn]
+ if not fn_analyses:
+ continue
+ print(f"\n ── {fn} ──")
+ print(f" {'Name':<22} {'Role':<28} {'Lvl':<5} {'Base':>10} {'TotalComp':>11} {'CR':>6} {'Perf':>5} Flags")
+ print(f" {'-'*22} {'-'*28} {'-'*5} {'-'*10} {'-'*11} {'-'*6} {'-'*5} {'-'*20}")
+
+ for a in sorted(fn_analyses, key=lambda x: -x["base"]):
+ cr_str = f"{a['compa_ratio']:.2f}" if a["compa_ratio"] else "N/A"
+ flag_summary = ", ".join(s for s, _ in a["flags"] if s in ("CRITICAL", "HIGH", "MEDIUM"))
+ flag_str = flag_summary if flag_summary else "OK"
+ print(f" {a['name']:<22} {a['role']:<28} {a['level']:<5} "
+ f"{fmt(a['base']):>10} {fmt(a['total_comp']):>11} {cr_str:>6} {a['performance']:>5} {flag_str}")
+
+ # Print flag detail for critical/high
+ for severity, msg in a["flags"]:
+ if severity in ("CRITICAL", "HIGH"):
+ print(f" {'':>22} ↳ [{severity}] {msg}")
+
+ # Action items
+ critical = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "CRITICAL"]
+ high = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "HIGH"]
+ medium = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "MEDIUM"]
+
+ print(f"\n[ ACTION ITEMS ]")
+ print(sep)
+
+ if critical:
+ print(f"\n CRITICAL — Address this review cycle:")
+ for name, msg in critical:
+ print(f" • {name}: {msg}")
+
+ if high:
+ print(f"\n HIGH — Address within 30 days:")
+ for name, msg in high[:10]:
+ print(f" • {name}: {msg}")
+ if len(high) > 10:
+ print(f" ... and {len(high)-10} more")
+
+ if medium:
+ print(f"\n MEDIUM — Address in next comp cycle:")
+ for name, msg in medium[:8]:
+ print(f" • {name}: {msg}")
+ if len(medium) > 8:
+ print(f" ... and {len(medium)-8} more")
+
+ if not critical and not high and not medium:
+ print(f"\n No critical or high-severity issues. Compensation appears well-managed.")
+
+ # Remediation cost estimate
+ below_min = [a for a in analyses if a["band"] and a["base"] < a["band"].band_min]
+ below_mid = [a for a in analyses if a["compa_ratio"] and a["compa_ratio"] < 0.90]
+
+ if below_min or below_mid:
+ print(f"\n[ REMEDIATION COST ESTIMATE ]")
+ print(sep)
+
+ if below_min:
+ cost_to_min = sum(a["band"].band_min - a["base"] for a in below_min)
+ print(f" Cost to bring below-minimum to band min: {fmt(cost_to_min)}/year ({len(below_min)} employees)")
+
+ if below_mid:
+ cost_to_90 = sum(int(a["band"].band_mid * 0.90) - a["base"] for a in below_mid if a["base"] < int(a["band"].band_mid * 0.90))
+ cost_to_90 = max(0, cost_to_90)
+ print(f" Cost to bring CR < 0.90 to CR = 0.90: {fmt(cost_to_90)}/year ({len(below_mid)} employees)")
+
+ total_payroll_impact = sum(e.base_salary for e in roster.employees)
+ total_remediation = (below_min and cost_to_min or 0)
+ print(f"\n Total payroll before remediation: {fmt(total_payroll_impact)}/year")
+ print(f" Remediation as % of payroll: {total_remediation/total_payroll_impact*100:.1f}%")
+
+ print(f"\n{SEP}\n")
+
+
+def export_csv(roster: CompRoster) -> str:
+ analyses = [analyze_employee(e, roster) for e in roster.employees]
+ output = io.StringIO()
+ writer = csv.writer(output)
+ writer.writerow(["ID", "Name", "Role", "Level", "Function", "Zone",
+ "Base", "Bonus Target", "Equity Annual", "Benefits", "Total Comp",
+ "Compa Ratio", "Band Position", "vs Market P50 %",
+ "Performance", "Tenure Years", "Last Raise (mo)",
+ "Gender", "Ethnicity", "Critical Flags", "High Flags"])
+ for a, e in zip(analyses, roster.employees):
+ critical_flags = "; ".join(msg for sev, msg in a["flags"] if sev == "CRITICAL")
+ high_flags = "; ".join(msg for sev, msg in a["flags"] if sev == "HIGH")
+ writer.writerow([a["id"], a["name"], a["role"], a["level"], a["function"], a["zone"],
+ a["base"], a["bonus_target"], a["equity_annual"], a["benefits"], a["total_comp"],
+ a["compa_ratio"], a["band_position"], a["vs_market_p50"],
+ a["performance"], a["tenure_years"], a["last_raise_months"],
+ e.gender, e.ethnicity, critical_flags, high_flags])
+ return output.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def build_sample_roster() -> CompRoster:
+ roster = CompRoster(
+ company="AcmeTech (Series A)",
+ as_of_date=date.today().isoformat(),
+ funding_stage="Series A",
+ comp_philosophy_target="P50",
+ preferred_stock_price=8.50,
+ )
+
+ # Bands (Engineering, P50 target, Tier1 = SF/NYC)
+ roster.bands = [
+ BandDefinition("L2", "Engineering", 115_000, 132_000, 155_000, 110_000, 132_000, 155_000, "Tier1"),
+ BandDefinition("L3", "Engineering", 148_000, 170_000, 198_000, 145_000, 170_000, 198_000, "Tier1"),
+ BandDefinition("L4", "Engineering", 185_000, 215_000, 248_000, 182_000, 215_000, 250_000, "Tier1"),
+ BandDefinition("M1", "Engineering", 170_000, 195_000, 225_000, 168_000, 195_000, 225_000, "Tier1"),
+ BandDefinition("L2", "Engineering", 95_000, 108_000, 125_000, 92_000, 108_000, 126_000, "Tier2"),
+ BandDefinition("L3", "Engineering", 122_000, 140_000, 162_000, 120_000, 140_000, 162_000, "Tier2"),
+ BandDefinition("L2", "Sales", 80_000, 92_000, 108_000, 78_000, 92_000, 108_000, "Tier1"),
+ BandDefinition("L3", "Sales", 95_000, 110_000, 128_000, 93_000, 110_000, 128_000, "Tier1"),
+ BandDefinition("M1", "Sales", 130_000, 150_000, 172_000, 128_000, 150_000, 172_000, "Tier1"),
+ BandDefinition("L2", "Product", 125_000, 145_000, 168_000, 123_000, 145_000, 168_000, "Tier1"),
+ BandDefinition("L3", "Product", 155_000, 178_000, 205_000, 153_000, 178_000, 205_000, "Tier1"),
+ BandDefinition("L2", "G&A", 85_000, 98_000, 115_000, 83_000, 98_000, 115_000, "Tier1"),
+ BandDefinition("L3", "G&A", 110_000, 128_000, 148_000, 108_000, 128_000, 148_000, "Tier1"),
+ ]
+
+ roster.employees = [
+ # Engineering — mix of scenarios
+ Employee("E001", "Aarav Shah", "Senior SWE (Backend)", "L3", "Engineering", "Tier1",
+ base_salary=168_000, bonus_target_pct=0.0, equity_shares=40_000,
+ equity_strike=1.50, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
+ benefits_annual=18_000, gender="M", ethnicity="Asian",
+ tenure_years=2.5, performance_rating=4, last_raise_months_ago=14,
+ last_equity_refresh_months_ago=None),
+
+ Employee("E002", "Yuki Tanaka", "Senior SWE (Frontend)", "L3", "Engineering", "Tier1",
+ base_salary=152_000, bonus_target_pct=0.0, equity_shares=30_000,
+ equity_strike=2.20, equity_current_409a=6.80, equity_vest_years_remaining=0.5,
+ benefits_annual=18_000, gender="F", ethnicity="Asian",
+ tenure_years=3.8, performance_rating=5, last_raise_months_ago=11,
+ last_equity_refresh_months_ago=30),
+ # Note: Yuki is high performer, near-vested, no recent refresh — flag expected
+
+ Employee("E003", "Marcus Johnson", "SWE II (Backend)", "L2", "Engineering", "Tier1",
+ base_salary=110_000, bonus_target_pct=0.0, equity_shares=15_000,
+ equity_strike=2.50, equity_current_409a=6.80, equity_vest_years_remaining=3.0,
+ benefits_annual=15_000, gender="M", ethnicity="Black",
+ tenure_years=1.2, performance_rating=3, last_raise_months_ago=12,
+ last_equity_refresh_months_ago=None),
+ # Note: Below band midpoint, recently hired — developing flag
+
+ Employee("E004", "Priya Nair", "Staff SWE", "L4", "Engineering", "Tier1",
+ base_salary=222_000, bonus_target_pct=0.0, equity_shares=60_000,
+ equity_strike=0.80, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
+ benefits_annual=18_000, gender="F", ethnicity="Asian",
+ tenure_years=4.2, performance_rating=5, last_raise_months_ago=8,
+ last_equity_refresh_months_ago=8),
+
+ Employee("E005", "Tom Rivera", "SWE II (Platform)", "L2", "Engineering", "Tier2",
+ base_salary=88_000, bonus_target_pct=0.0, equity_shares=12_000,
+ equity_strike=3.00, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
+ benefits_annual=14_000, gender="M", ethnicity="Hispanic",
+ tenure_years=1.8, performance_rating=4, last_raise_months_ago=22,
+ last_equity_refresh_months_ago=None),
+ # Note: No raise in 22 months, high performer — flag expected
+
+ Employee("E006", "Sarah Kim", "Eng Manager", "M1", "Engineering", "Tier1",
+ base_salary=192_000, bonus_target_pct=0.10, equity_shares=35_000,
+ equity_strike=1.20, equity_current_409a=6.80, equity_vest_years_remaining=1.8,
+ benefits_annual=18_000, gender="F", ethnicity="Asian",
+ tenure_years=2.8, performance_rating=4, last_raise_months_ago=9,
+ last_equity_refresh_months_ago=9),
+
+ # Sales
+ Employee("S001", "David Chen", "Account Executive (MM)", "L3", "Sales", "Tier1",
+ base_salary=105_000, bonus_target_pct=0.50, equity_shares=8_000,
+ equity_strike=3.50, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
+ benefits_annual=15_000, gender="M", ethnicity="Asian",
+ tenure_years=1.5, performance_rating=3, last_raise_months_ago=15,
+ last_equity_refresh_months_ago=None),
+
+ Employee("S002", "Amara Osei", "AE (Mid-Market)", "L3", "Sales", "Tier1",
+ base_salary=98_000, bonus_target_pct=0.50, equity_shares=6_000,
+ equity_strike=3.50, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
+ benefits_annual=15_000, gender="F", ethnicity="Black",
+ tenure_years=1.0, performance_rating=4, last_raise_months_ago=12,
+ last_equity_refresh_months_ago=None),
+ # Note: High performer, significantly below midpoint — flag expected
+
+ Employee("S003", "Jordan Blake", "Sales Manager", "M1", "Sales", "Tier1",
+ base_salary=155_000, bonus_target_pct=0.20, equity_shares=20_000,
+ equity_strike=2.00, equity_current_409a=6.80, equity_vest_years_remaining=1.5,
+ benefits_annual=16_000, gender="NB", ethnicity="White",
+ tenure_years=2.2, performance_rating=3, last_raise_months_ago=10,
+ last_equity_refresh_months_ago=10),
+
+ # Product
+ Employee("P001", "Nina Patel", "Senior PM", "L3", "Product", "Tier1",
+ base_salary=176_000, bonus_target_pct=0.10, equity_shares=22_000,
+ equity_strike=1.80, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
+ benefits_annual=17_000, gender="F", ethnicity="Asian",
+ tenure_years=2.0, performance_rating=4, last_raise_months_ago=12,
+ last_equity_refresh_months_ago=12),
+
+ # G&A
+ Employee("G001", "Chris Mueller", "Finance Manager", "L3", "G&A", "Tier1",
+ base_salary=125_000, bonus_target_pct=0.10, equity_shares=10_000,
+ equity_strike=2.80, equity_current_409a=6.80, equity_vest_years_remaining=3.0,
+ benefits_annual=16_000, gender="M", ethnicity="White",
+ tenure_years=1.5, performance_rating=3, last_raise_months_ago=15,
+ last_equity_refresh_months_ago=None),
+
+ Employee("G002", "Fatima Al-Hassan", "HR Operations", "L2", "G&A", "Tier1",
+ base_salary=82_000, bonus_target_pct=0.08, equity_shares=5_000,
+ equity_strike=4.00, equity_current_409a=6.80, equity_vest_years_remaining=3.5,
+ benefits_annual=14_000, gender="F", ethnicity="Middle Eastern",
+ tenure_years=0.8, performance_rating=3, last_raise_months_ago=8,
+ last_equity_refresh_months_ago=None),
+ # Note: Below band minimum — critical flag expected
+ ]
+
+ return roster
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def load_roster_from_json(path: str) -> CompRoster:
+ with open(path) as f:
+ data = json.load(f)
+ employees = [Employee(**e) for e in data.pop("employees", [])]
+ bands = [BandDefinition(**b) for b in data.pop("bands", [])]
+ roster = CompRoster(**data)
+ roster.employees = employees
+ roster.bands = bands
+ return roster
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Compensation Benchmarker — salary analysis and pay equity audit",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ python comp_benchmarker.py # Run sample roster
+ python comp_benchmarker.py --config roster.json # Load from JSON
+ python comp_benchmarker.py --export-csv # Output CSV
+ python comp_benchmarker.py --export-json # Output JSON template
+ """
+ )
+ parser.add_argument("--config", help="Path to JSON roster file")
+ parser.add_argument("--export-csv", action="store_true", help="Export analysis as CSV")
+ parser.add_argument("--export-json", action="store_true", help="Export sample roster as JSON template")
+ args = parser.parse_args()
+
+ if args.config:
+ roster = load_roster_from_json(args.config)
+ else:
+ roster = build_sample_roster()
+
+ if args.export_json:
+ data = asdict(roster)
+ print(json.dumps(data, indent=2))
+ return
+
+ if args.export_csv:
+ print(export_csv(roster))
+ return
+
+ print_report(roster)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/chro-advisor/scripts/hiring_plan_modeler.py b/skills/chro-advisor/scripts/hiring_plan_modeler.py
new file mode 100644
index 00000000..d0a62e8e
--- /dev/null
+++ b/skills/chro-advisor/scripts/hiring_plan_modeler.py
@@ -0,0 +1,572 @@
+#!/usr/bin/env python3
+"""
+Hiring Plan Modeler
+===================
+Builds hiring plans from business goals with cost projections.
+Outputs quarterly headcount plan, cost model, and risk assessment.
+
+Usage:
+ python hiring_plan_modeler.py # Run with built-in sample data
+ python hiring_plan_modeler.py --config plan.json # Load from JSON config
+ python hiring_plan_modeler.py --help
+"""
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, date
+from typing import Optional
+import csv
+import io
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HireTarget:
+ """One planned hire."""
+ role: str
+ level: str # L1, L2, L3, L4, M1, M2, M3, VP, C-Suite
+ function: str # Engineering, Sales, Product, G&A, Marketing, CS
+ quarter: str # Q1-2025, Q2-2025, etc.
+ base_salary: int # Annual, USD
+ bonus_pct: float # % of base (e.g., 0.10 for 10%)
+ equity_annual_usd: int # Annualized equity value at current 409A
+ benefits_annual: int # Employer-paid benefits
+ recruiter_fee_pct: float= 0.20 # Agency fee if used (0 for internal recruiter)
+ ramp_months: int = 3 # Months to full productivity
+ priority: str = "High" # High / Medium / Low
+ business_case: str = ""
+ open_to_internal: bool = False
+
+
+@dataclass
+class HiringPlan:
+ company: str
+ plan_period: str # e.g., "2025 Annual"
+ current_headcount: int
+ target_revenue: int # Annual target revenue ($)
+ current_revenue: int # Current ARR ($)
+ hires: list[HireTarget] = field(default_factory=list)
+
+ # Cost overheads beyond comp
+ overhead_rate: float = 0.25 # Workspace, software, onboarding overhead as % of base
+ internal_recruiter_cost: int = 0 # If you have an internal recruiter, annual cost
+
+
+# ---------------------------------------------------------------------------
+# Computation
+# ---------------------------------------------------------------------------
+
+def quarter_to_sortkey(q: str) -> tuple[int, int]:
+ """Parse 'Q2-2025' → (2025, 2)"""
+ parts = q.upper().split("-")
+ if len(parts) == 2:
+ q_num = int(parts[0].replace("Q", ""))
+ year = int(parts[1])
+ return (year, q_num)
+ return (9999, 9)
+
+
+def get_quarters(hires: list[HireTarget]) -> list[str]:
+ """Return sorted unique quarters from hire list."""
+ quarters = sorted(set(h.quarter for h in hires), key=quarter_to_sortkey)
+ return quarters
+
+
+def compute_hire_costs(hire: HireTarget) -> dict:
+ """Compute total first-year cost for one hire."""
+ total_comp = hire.base_salary + int(hire.base_salary * hire.bonus_pct) + hire.equity_annual_usd + hire.benefits_annual
+ recruiter_fee = int(hire.base_salary * hire.recruiter_fee_pct)
+ overhead = int(hire.base_salary * 0.25) # workspace, tools, onboarding
+ ramp_productivity_cost = int(hire.base_salary * (hire.ramp_months / 12)) # cost during ramp
+
+ return {
+ "base_salary": hire.base_salary,
+ "target_bonus": int(hire.base_salary * hire.bonus_pct),
+ "equity_annual": hire.equity_annual_usd,
+ "benefits": hire.benefits_annual,
+ "total_comp": total_comp,
+ "recruiter_fee": recruiter_fee,
+ "overhead": overhead,
+ "ramp_cost": ramp_productivity_cost,
+ "first_year_total": total_comp + recruiter_fee + overhead,
+ "fully_loaded_first_year": total_comp + recruiter_fee + overhead + ramp_productivity_cost,
+ }
+
+
+def summarize_by_quarter(plan: HiringPlan) -> dict[str, dict]:
+ """Aggregate headcount and costs per quarter."""
+ quarters = get_quarters(plan.hires)
+ summary = {}
+ running_headcount = plan.current_headcount
+
+ for q in quarters:
+ q_hires = [h for h in plan.hires if h.quarter == q]
+ q_costs = [compute_hire_costs(h) for h in q_hires]
+
+ total_comp = sum(c["total_comp"] for c in q_costs)
+ total_first_year = sum(c["first_year_total"] for c in q_costs)
+ recruiter_fees = sum(c["recruiter_fee"] for c in q_costs)
+
+ running_headcount += len(q_hires)
+
+ summary[q] = {
+ "new_hires": len(q_hires),
+ "headcount_eop": running_headcount,
+ "total_annual_comp_added": total_comp,
+ "total_first_year_cost": total_first_year,
+ "recruiter_fees": recruiter_fees,
+ "hires": q_hires,
+ "costs": q_costs,
+ }
+
+ return summary
+
+
+def summarize_by_function(plan: HiringPlan) -> dict[str, dict]:
+ """Aggregate headcount and costs per function."""
+ functions: dict[str, dict] = {}
+ for hire in plan.hires:
+ fn = hire.function
+ if fn not in functions:
+ functions[fn] = {"count": 0, "total_comp": 0, "total_first_year": 0, "roles": []}
+ costs = compute_hire_costs(hire)
+ functions[fn]["count"] += 1
+ functions[fn]["total_comp"] += costs["total_comp"]
+ functions[fn]["total_first_year"] += costs["first_year_total"]
+ functions[fn]["roles"].append(hire.role)
+ return functions
+
+
+def compute_totals(plan: HiringPlan) -> dict:
+ all_costs = [compute_hire_costs(h) for h in plan.hires]
+ total_hires = len(plan.hires)
+ total_comp = sum(c["total_comp"] for c in all_costs)
+ total_first_year = sum(c["first_year_total"] for c in all_costs)
+ total_fully_loaded = sum(c["fully_loaded_first_year"] for c in all_costs)
+ total_recruiter = sum(c["recruiter_fee"] for c in all_costs)
+
+ final_headcount = plan.current_headcount + total_hires
+ revenue_per_employee = plan.target_revenue / final_headcount if final_headcount > 0 else 0
+ revenue_per_employee_current = plan.current_revenue / plan.current_headcount if plan.current_headcount > 0 else 0
+
+ return {
+ "total_hires": total_hires,
+ "final_headcount": final_headcount,
+ "headcount_growth_pct": ((final_headcount - plan.current_headcount) / plan.current_headcount * 100) if plan.current_headcount > 0 else 0,
+ "total_annual_comp_added": total_comp,
+ "total_first_year_cost": total_first_year,
+ "total_fully_loaded_first_year": total_fully_loaded,
+ "total_recruiter_fees": total_recruiter,
+ "revenue_per_employee_target": revenue_per_employee,
+ "revenue_per_employee_current": revenue_per_employee_current,
+ "avg_comp_per_hire": total_comp // total_hires if total_hires > 0 else 0,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Risk assessment
+# ---------------------------------------------------------------------------
+
+def assess_risks(plan: HiringPlan, totals: dict) -> list[dict]:
+ risks = []
+
+ # Headcount growth too fast
+ growth_pct = totals["headcount_growth_pct"]
+ if growth_pct > 80:
+ risks.append({
+ "severity": "HIGH",
+ "category": "Execution",
+ "finding": f"Headcount growing {growth_pct:.0f}% this period. "
+ "Culture and processes rarely scale this fast without breakage.",
+ "recommendation": "Stagger Q3/Q4 hires. Validate Q1/Q2 cohort is onboarded before next wave."
+ })
+ elif growth_pct > 50:
+ risks.append({
+ "severity": "MEDIUM",
+ "category": "Execution",
+ "finding": f"Headcount growing {growth_pct:.0f}% — significant scaling challenge.",
+ "recommendation": "Ensure onboarding infrastructure scales. Assign buddy/mentor to each hire."
+ })
+
+ # High concentration in one quarter
+ quarters = get_quarters(plan.hires)
+ q_counts = {q: sum(1 for h in plan.hires if h.quarter == q) for q in quarters}
+ max_q = max(q_counts.values()) if q_counts else 0
+ if max_q > len(plan.hires) * 0.5 and max_q > 4:
+ heavy_q = [q for q, c in q_counts.items() if c == max_q][0]
+ risks.append({
+ "severity": "MEDIUM",
+ "category": "Hiring Execution",
+ "finding": f"More than 50% of hires planned in {heavy_q} ({max_q} hires). "
+ "Recruiting capacity and onboarding bandwidth may be insufficient.",
+ "recommendation": "Spread hires across quarters. Hiring pipeline needs to start 60–90 days before target start date."
+ })
+
+ # Revenue per employee declining
+ if totals["revenue_per_employee_target"] < totals["revenue_per_employee_current"] * 0.7:
+ risks.append({
+ "severity": "HIGH",
+ "category": "Financial",
+ "finding": f"Revenue per employee declining from ${totals['revenue_per_employee_current']:,.0f} to "
+ f"${totals['revenue_per_employee_target']:,.0f} — a {((totals['revenue_per_employee_target']/totals['revenue_per_employee_current'])-1)*100:.0f}% drop.",
+ "recommendation": "Validate that revenue model supports this headcount. Is target revenue achievable with this team?"
+ })
+
+ # Low priority hires consuming budget
+ low_priority_hires = [h for h in plan.hires if h.priority == "Low"]
+ if low_priority_hires:
+ lp_cost = sum(compute_hire_costs(h)["first_year_total"] for h in low_priority_hires)
+ risks.append({
+ "severity": "MEDIUM",
+ "category": "Prioritization",
+ "finding": f"{len(low_priority_hires)} 'Low' priority hires consuming ${lp_cost:,.0f} in first-year costs.",
+ "recommendation": "Consider deferring Low priority hires to preserve runway. Cut these first if budget tightens."
+ })
+
+ # Hires without business cases
+ no_case = [h for h in plan.hires if not h.business_case]
+ if no_case:
+ risks.append({
+ "severity": "MEDIUM",
+ "category": "Governance",
+ "finding": f"{len(no_case)} hires have no documented business case: {', '.join(h.role for h in no_case[:5])}{'...' if len(no_case) > 5 else ''}",
+ "recommendation": "Every hire over $80K should have a written business case. What revenue or risk does this role address?"
+ })
+
+ # High recruiter fee exposure
+ if totals["total_recruiter_fees"] > 100_000:
+ risks.append({
+ "severity": "LOW",
+ "category": "Cost",
+ "finding": f"${totals['total_recruiter_fees']:,.0f} in recruiter fees. "
+ "Consider whether internal recruiter investment would be cheaper at this hiring volume.",
+ "recommendation": f"Internal recruiter at $120–150K fully loaded pays off at 3–4 hires/year vs. agency fees."
+ })
+
+ # No risks — that's itself a flag
+ if not risks:
+ risks.append({
+ "severity": "INFO",
+ "category": "General",
+ "finding": "No major risks flagged. Plan appears well-structured.",
+ "recommendation": "Validate assumptions: time-to-fill estimates, revenue model, and Q1 hiring pipeline status."
+ })
+
+ return risks
+
+
+# ---------------------------------------------------------------------------
+# Formatting / Output
+# ---------------------------------------------------------------------------
+
+def fmt(n: int) -> str:
+ return f"${n:,.0f}"
+
+
+def pct(n: float) -> str:
+ return f"{n:.1f}%"
+
+
+def print_report(plan: HiringPlan):
+ WIDTH = 72
+ SEP = "=" * WIDTH
+ sep = "-" * WIDTH
+
+ print(SEP)
+ print(f" HIRING PLAN: {plan.company}")
+ print(f" Period: {plan.plan_period} | Generated: {date.today().isoformat()}")
+ print(SEP)
+
+ totals = compute_totals(plan)
+ q_summary = summarize_by_quarter(plan)
+ fn_summary = summarize_by_function(plan)
+ risks = assess_risks(plan, totals)
+
+ # Executive summary
+ print("\n[ EXECUTIVE SUMMARY ]")
+ print(sep)
+ print(f" Current headcount: {plan.current_headcount:>5}")
+ print(f" Planned hires: {totals['total_hires']:>5}")
+ print(f" Final headcount: {totals['final_headcount']:>5} (+{totals['headcount_growth_pct']:.0f}%)")
+ print(f" Current ARR: {fmt(plan.current_revenue):>12}")
+ print(f" Target revenue: {fmt(plan.target_revenue):>12}")
+ print(f" Revenue/employee now: {fmt(int(totals['revenue_per_employee_current'])):>12}")
+ print(f" Revenue/employee target: {fmt(int(totals['revenue_per_employee_target'])):>12}")
+ print()
+ print(f" Total annual comp added: {fmt(totals['total_annual_comp_added']):>12}")
+ print(f" Total first-year cost: {fmt(totals['total_first_year_cost']):>12}")
+ print(f" Fully loaded (w/ ramp): {fmt(totals['total_fully_loaded_first_year']):>12}")
+ print(f" Recruiter fees: {fmt(totals['total_recruiter_fees']):>12}")
+ print(f" Avg comp per hire: {fmt(totals['avg_comp_per_hire']):>12}")
+
+ # Quarterly breakdown
+ print(f"\n[ QUARTERLY HEADCOUNT PLAN ]")
+ print(sep)
+ print(f" {'Quarter':<10} {'New Hires':>10} {'HC (EOP)':>10} {'Comp Added':>14} {'1yr Cost':>14} {'Recruiter $':>12}")
+ print(f" {'-'*10} {'-'*10} {'-'*10} {'-'*14} {'-'*14} {'-'*12}")
+ for q, data in q_summary.items():
+ print(f" {q:<10} {data['new_hires']:>10} {data['headcount_eop']:>10} "
+ f"{fmt(data['total_annual_comp_added']):>14} "
+ f"{fmt(data['total_first_year_cost']):>14} "
+ f"{fmt(data['recruiter_fees']):>12}")
+
+ # By function
+ print(f"\n[ HEADCOUNT BY FUNCTION ]")
+ print(sep)
+ print(f" {'Function':<18} {'Hires':>7} {'Annual Comp':>14} {'1yr Cost':>14}")
+ print(f" {'-'*18} {'-'*7} {'-'*14} {'-'*14}")
+ for fn, data in sorted(fn_summary.items(), key=lambda x: -x[1]["count"]):
+ print(f" {fn:<18} {data['count']:>7} {fmt(data['total_comp']):>14} {fmt(data['total_first_year']):>14}")
+
+ # Hire detail
+ print(f"\n[ HIRE DETAIL ]")
+ print(sep)
+ print(f" {'Role':<30} {'Fn':<14} {'Lvl':<6} {'Q':<8} {'Base':>10} {'Total Comp':>12} {'Priority':<8}")
+ print(f" {'-'*30} {'-'*14} {'-'*6} {'-'*8} {'-'*10} {'-'*12} {'-'*8}")
+ for h in sorted(plan.hires, key=lambda x: quarter_to_sortkey(x.quarter)):
+ costs = compute_hire_costs(h)
+ print(f" {h.role:<30} {h.function:<14} {h.level:<6} {h.quarter:<8} "
+ f"{fmt(h.base_salary):>10} {fmt(costs['total_comp']):>12} {h.priority:<8}")
+ if h.business_case:
+ bc = h.business_case[:60] + "..." if len(h.business_case) > 60 else h.business_case
+ print(f" {'':>30} ↳ {bc}")
+
+ # Risk assessment
+ print(f"\n[ RISK ASSESSMENT ]")
+ print(sep)
+ sev_order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "INFO": 3}
+ for risk in sorted(risks, key=lambda r: sev_order.get(r["severity"], 99)):
+ sev = risk["severity"]
+ marker = {"HIGH": "⚠ HIGH", "MEDIUM": "◆ MED ", "LOW": "◇ LOW ", "INFO": "ℹ INFO"}[sev]
+ print(f"\n [{marker}] {risk['category']}")
+ # Wrap finding
+ finding = risk["finding"]
+ words = finding.split()
+ line = " Finding: "
+ for w in words:
+ if len(line) + len(w) + 1 > WIDTH - 2:
+ print(line)
+ line = " " + w + " "
+ else:
+ line += w + " "
+ if line.strip():
+ print(line)
+ reco = risk["recommendation"]
+ words = reco.split()
+ line = " Action: "
+ for w in words:
+ if len(line) + len(w) + 1 > WIDTH - 2:
+ print(line)
+ line = " " + w + " "
+ else:
+ line += w + " "
+ if line.strip():
+ print(line)
+
+ print(f"\n{SEP}\n")
+
+
+def export_csv(plan: HiringPlan) -> str:
+ """Return CSV of hire detail."""
+ output = io.StringIO()
+ writer = csv.writer(output)
+ writer.writerow(["Role", "Function", "Level", "Quarter", "Priority",
+ "Base Salary", "Bonus Target", "Equity Annual", "Benefits",
+ "Total Comp", "Recruiter Fee", "Overhead", "First Year Total",
+ "Ramp Months", "Open to Internal", "Business Case"])
+ for h in plan.hires:
+ c = compute_hire_costs(h)
+ writer.writerow([h.role, h.function, h.level, h.quarter, h.priority,
+ h.base_salary, c["target_bonus"], h.equity_annual_usd, h.benefits_annual,
+ c["total_comp"], c["recruiter_fee"], c["overhead"], c["first_year_total"],
+ h.ramp_months, h.open_to_internal, h.business_case])
+ return output.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+def build_sample_plan() -> HiringPlan:
+ """Sample Series A → B hiring plan."""
+ plan = HiringPlan(
+ company="AcmeTech (Series A)",
+ plan_period="2025 Annual",
+ current_headcount=32,
+ current_revenue=3_500_000,
+ target_revenue=8_000_000,
+ overhead_rate=0.25,
+ internal_recruiter_cost=140_000,
+ )
+
+ plan.hires = [
+ # Q1 — Foundation hires
+ HireTarget(
+ role="Staff Software Engineer (Backend)",
+ level="L4", function="Engineering", quarter="Q1-2025",
+ base_salary=185_000, bonus_pct=0.0, equity_annual_usd=25_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="High", open_to_internal=True,
+ business_case="Core API team is bottleneck for 3 roadmap items. Staff-level needed to lead architecture."
+ ),
+ HireTarget(
+ role="Account Executive (Mid-Market)",
+ level="L3", function="Sales", quarter="Q1-2025",
+ base_salary=95_000, bonus_pct=0.50, equity_annual_usd=10_000,
+ benefits_annual=15_000, recruiter_fee_pct=0.18, ramp_months=4,
+ priority="High",
+ business_case="Pipeline coverage at 1.8x quota. Need 2.5x by Q2. AE adds $600K ARR/year at ramp."
+ ),
+ HireTarget(
+ role="Product Designer (Senior)",
+ level="L3", function="Product", quarter="Q1-2025",
+ base_salary=145_000, bonus_pct=0.0, equity_annual_usd=18_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="High",
+ business_case="Single designer for 4 squads. UX debt slowing enterprise deals requiring onboarding improvements."
+ ),
+
+ # Q2 — Growth hires
+ HireTarget(
+ role="Engineering Manager (Frontend)",
+ level="M1", function="Engineering", quarter="Q2-2025",
+ base_salary=175_000, bonus_pct=0.10, equity_annual_usd=22_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.20, ramp_months=3,
+ priority="High",
+ business_case="Frontend team at 7 ICs with no dedicated EM. Performance review debt is high; manager needed."
+ ),
+ HireTarget(
+ role="Account Executive (Mid-Market)",
+ level="L2", function="Sales", quarter="Q2-2025",
+ base_salary=85_000, bonus_pct=0.50, equity_annual_usd=8_000,
+ benefits_annual=15_000, recruiter_fee_pct=0.18, ramp_months=4,
+ priority="High",
+ business_case="Second AE to reach 2.5x pipeline coverage target."
+ ),
+ HireTarget(
+ role="Customer Success Manager",
+ level="L2", function="Customer Success", quarter="Q2-2025",
+ base_salary=90_000, bonus_pct=0.15, equity_annual_usd=8_000,
+ benefits_annual=15_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="Medium",
+ business_case="CSM:account ratio at 1:60, industry standard 1:30. NRR has dipped 4pts in 2 quarters."
+ ),
+ HireTarget(
+ role="Data Engineer",
+ level="L2", function="Engineering", quarter="Q2-2025",
+ base_salary=155_000, bonus_pct=0.0, equity_annual_usd=18_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=3,
+ priority="Medium",
+ business_case="Analytics infrastructure blocking product analytics, customer dashboards, and board metrics."
+ ),
+
+ # Q3 — Scale hires
+ HireTarget(
+ role="Senior Software Engineer (Backend)",
+ level="L3", function="Engineering", quarter="Q3-2025",
+ base_salary=165_000, bonus_pct=0.0, equity_annual_usd=20_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="High",
+ business_case="Backend team needs capacity to deliver Q3 roadmap without delaying Q4 items."
+ ),
+ HireTarget(
+ role="Head of Marketing",
+ level="M3", function="Marketing", quarter="Q3-2025",
+ base_salary=180_000, bonus_pct=0.15, equity_annual_usd=30_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.20, ramp_months=3,
+ priority="High",
+ business_case="No marketing function. 100% of pipeline is outbound. Need inbound by Q1-2026 for Series B."
+ ),
+ HireTarget(
+ role="People Operations Manager",
+ level="M1", function="G&A", quarter="Q3-2025",
+ base_salary=120_000, bonus_pct=0.10, equity_annual_usd=12_000,
+ benefits_annual=16_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="Medium",
+ business_case="Founders spending 8hrs/week on HR ops at 40 employees. Unscalable. First dedicated HR hire."
+ ),
+
+ # Q4 — Stretch hires (conditional on revenue milestone)
+ HireTarget(
+ role="Senior Software Engineer (Frontend)",
+ level="L3", function="Engineering", quarter="Q4-2025",
+ base_salary=160_000, bonus_pct=0.0, equity_annual_usd=18_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
+ priority="Medium",
+ business_case="Conditional on Q3 ARR exceeding $5.5M. Frontend team capacity planning for 2026 roadmap."
+ ),
+ HireTarget(
+ role="Account Executive (Enterprise)",
+ level="L4", function="Sales", quarter="Q4-2025",
+ base_salary=120_000, bonus_pct=0.60, equity_annual_usd=15_000,
+ benefits_annual=15_000, recruiter_fee_pct=0.20, ramp_months=6,
+ priority="Low",
+ business_case="Enterprise motion exploratory. Requires ICP validation in Q2-Q3 before committing."
+ ),
+ HireTarget(
+ role="DevOps / Platform Engineer",
+ level="L3", function="Engineering", quarter="Q4-2025",
+ base_salary=150_000, bonus_pct=0.0, equity_annual_usd=18_000,
+ benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=3,
+ priority="Low",
+ business_case="Platform reliability becoming bottleneck. Conditional on uptime SLA breaches continuing in Q3."
+ ),
+ ]
+
+ return plan
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def load_plan_from_json(path: str) -> HiringPlan:
+ with open(path) as f:
+ data = json.load(f)
+ hires = [HireTarget(**h) for h in data.pop("hires", [])]
+ plan = HiringPlan(**data)
+ plan.hires = hires
+ return plan
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Hiring Plan Modeler — build headcount plans with cost projections",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ python hiring_plan_modeler.py # Run sample plan
+ python hiring_plan_modeler.py --config plan.json # Load from JSON
+ python hiring_plan_modeler.py --export-csv # Output CSV of hires
+ python hiring_plan_modeler.py --export-json # Output plan as JSON template
+ """
+ )
+ parser.add_argument("--config", help="Path to JSON plan file")
+ parser.add_argument("--export-csv", action="store_true", help="Export hire detail as CSV")
+ parser.add_argument("--export-json", action="store_true", help="Export sample plan as JSON template")
+ args = parser.parse_args()
+
+ if args.config:
+ plan = load_plan_from_json(args.config)
+ else:
+ plan = build_sample_plan()
+
+ if args.export_json:
+ data = asdict(plan)
+ print(json.dumps(data, indent=2))
+ return
+
+ if args.export_csv:
+ print(export_csv(plan))
+ return
+
+ print_report(plan)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/ci-cd-pipeline-builder/README.md b/skills/ci-cd-pipeline-builder/README.md
new file mode 100644
index 00000000..48a4cb08
--- /dev/null
+++ b/skills/ci-cd-pipeline-builder/README.md
@@ -0,0 +1,48 @@
+# CI/CD Pipeline Builder
+
+Detects your repository stack and generates practical CI pipeline templates for GitHub Actions and GitLab CI. Designed as a fast baseline you can extend with deployment controls.
+
+## Quick Start
+
+```bash
+# Detect stack
+python3 scripts/stack_detector.py --repo . --format json > stack.json
+
+# Generate GitHub Actions workflow
+python3 scripts/pipeline_generator.py \
+ --input stack.json \
+ --platform github \
+ --output .github/workflows/ci.yml \
+ --format text
+```
+
+## Included Tools
+
+- `scripts/stack_detector.py`: repository signal detection with JSON/text output
+- `scripts/pipeline_generator.py`: generate GitHub/GitLab CI YAML from detection payload
+
+## References
+
+- `references/github-actions-templates.md`
+- `references/gitlab-ci-templates.md`
+- `references/deployment-gates.md`
+
+## Installation
+
+### Claude Code
+
+```bash
+cp -R engineering/ci-cd-pipeline-builder ~/.claude/skills/ci-cd-pipeline-builder
+```
+
+### OpenAI Codex
+
+```bash
+cp -R engineering/ci-cd-pipeline-builder ~/.codex/skills/ci-cd-pipeline-builder
+```
+
+### OpenClaw
+
+```bash
+cp -R engineering/ci-cd-pipeline-builder ~/.openclaw/skills/ci-cd-pipeline-builder
+```
diff --git a/skills/ci-cd-pipeline-builder/SKILL.md b/skills/ci-cd-pipeline-builder/SKILL.md
new file mode 100644
index 00000000..e6090f1e
--- /dev/null
+++ b/skills/ci-cd-pipeline-builder/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: "ci-cd-pipeline-builder"
+description: "CI/CD Pipeline Builder"
+---
+
+# CI/CD Pipeline Builder
+
+**Tier:** POWERFUL
+**Category:** Engineering
+**Domain:** DevOps / Automation
+
+## Overview
+
+Use this skill to generate pragmatic CI/CD pipelines from detected project stack signals, not guesswork. It focuses on fast baseline generation, repeatable checks, and environment-aware deployment stages.
+
+## Core Capabilities
+
+- Detect language/runtime/tooling from repository files
+- Recommend CI stages (`lint`, `test`, `build`, `deploy`)
+- Generate GitHub Actions or GitLab CI starter pipelines
+- Include caching and matrix strategy based on detected stack
+- Emit machine-readable detection output for automation
+- Keep pipeline logic aligned with project lockfiles and build commands
+
+## When to Use
+
+- Bootstrapping CI for a new repository
+- Replacing brittle copied pipeline files
+- Migrating between GitHub Actions and GitLab CI
+- Auditing whether pipeline steps match actual stack
+- Creating a reproducible baseline before custom hardening
+
+## Key Workflows
+
+### 1. Detect Stack
+
+```bash
+python3 scripts/stack_detector.py --repo . --format text
+python3 scripts/stack_detector.py --repo . --format json > detected-stack.json
+```
+
+Supports input via stdin or `--input` file for offline analysis payloads.
+
+### 2. Generate Pipeline From Detection
+
+```bash
+python3 scripts/pipeline_generator.py \
+ --input detected-stack.json \
+ --platform github \
+ --output .github/workflows/ci.yml \
+ --format text
+```
+
+Or end-to-end from repo directly:
+
+```bash
+python3 scripts/pipeline_generator.py --repo . --platform gitlab --output .gitlab-ci.yml
+```
+
+### 3. Validate Before Merge
+
+1. Confirm commands exist in project (`test`, `lint`, `build`).
+2. Run generated pipeline locally where possible.
+3. Ensure required secrets/env vars are documented.
+4. Keep deploy jobs gated by protected branches/environments.
+
+### 4. Add Deployment Stages Safely
+
+- Start with CI-only (`lint/test/build`).
+- Add staging deploy with explicit environment context.
+- Add production deploy with manual gate/approval.
+- Keep rollout/rollback commands explicit and auditable.
+
+## Script Interfaces
+
+- `python3 scripts/stack_detector.py --help`
+ - Detects stack signals from repository files
+ - Reads optional JSON input from stdin/`--input`
+- `python3 scripts/pipeline_generator.py --help`
+ - Generates GitHub/GitLab YAML from detection payload
+ - Writes to stdout or `--output`
+
+## Common Pitfalls
+
+1. Copying a Node pipeline into Python/Go repos
+2. Enabling deploy jobs before stable tests
+3. Forgetting dependency cache keys
+4. Running expensive matrix builds for every trivial branch
+5. Missing branch protections around prod deploy jobs
+6. Hardcoding secrets in YAML instead of CI secret stores
+
+## Best Practices
+
+1. Detect stack first, then generate pipeline.
+2. Keep generated baseline under version control.
+3. Add one optimization at a time (cache, matrix, split jobs).
+4. Require green CI before deployment jobs.
+5. Use protected environments for production credentials.
+6. Regenerate pipeline when stack changes significantly.
+
+## References
+
+- [references/github-actions-templates.md](references/github-actions-templates.md)
+- [references/gitlab-ci-templates.md](references/gitlab-ci-templates.md)
+- [references/deployment-gates.md](references/deployment-gates.md)
+- [README.md](README.md)
+
+## Detection Heuristics
+
+The stack detector prioritizes deterministic file signals over heuristics:
+
+- Lockfiles determine package manager preference
+- Language manifests determine runtime families
+- Script commands (if present) drive lint/test/build commands
+- Missing scripts trigger conservative placeholder commands
+
+## Generation Strategy
+
+Start with a minimal, reliable pipeline:
+
+1. Checkout and setup runtime
+2. Install dependencies with cache strategy
+3. Run lint, test, build in separate steps
+4. Publish artifacts only after passing checks
+
+Then layer advanced behavior (matrix builds, security scans, deploy gates).
+
+## Platform Decision Notes
+
+- GitHub Actions for tight GitHub ecosystem integration
+- GitLab CI for integrated SCM + CI in self-hosted environments
+- Keep one canonical pipeline source per repo to reduce drift
+
+## Validation Checklist
+
+1. Generated YAML parses successfully.
+2. All referenced commands exist in the repo.
+3. Cache strategy matches package manager.
+4. Required secrets are documented, not embedded.
+5. Branch/protected-environment rules match org policy.
+
+## Scaling Guidance
+
+- Split long jobs by stage when runtime exceeds 10 minutes.
+- Introduce test matrix only when compatibility truly requires it.
+- Separate deploy jobs from CI jobs to keep feedback fast.
+- Track pipeline duration and flakiness as first-class metrics.
diff --git a/skills/ci-cd-pipeline-builder/_meta.json b/skills/ci-cd-pipeline-builder/_meta.json
new file mode 100644
index 00000000..7dc6de5d
--- /dev/null
+++ b/skills/ci-cd-pipeline-builder/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "ci-cd-pipeline-builder",
+ "displayName": "ci-cd-pipeline-builder",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1773242246952,
+ "commit": "https://github.com/openclaw/skills/commit/afb66233cde6b3109cde14651843512e9d253e65"
+ },
+ "history": []
+}
diff --git a/skills/ci-cd-pipeline-builder/references/deployment-gates.md b/skills/ci-cd-pipeline-builder/references/deployment-gates.md
new file mode 100644
index 00000000..14aa7451
--- /dev/null
+++ b/skills/ci-cd-pipeline-builder/references/deployment-gates.md
@@ -0,0 +1,17 @@
+# Deployment Gates
+
+## Minimum Gate Policy
+
+- `lint` must pass before `test`.
+- `test` must pass before `build`.
+- `build` artifact required for deploy jobs.
+- Production deploy requires manual approval and protected branch.
+
+## Environment Pattern
+
+- `develop` -> auto deploy to staging
+- `main` -> manual promote to production
+
+## Rollback Requirement
+
+Every deploy job should define a rollback command or procedure reference.
diff --git a/skills/ci-cd-pipeline-builder/references/github-actions-templates.md b/skills/ci-cd-pipeline-builder/references/github-actions-templates.md
new file mode 100644
index 00000000..5fd12974
--- /dev/null
+++ b/skills/ci-cd-pipeline-builder/references/github-actions-templates.md
@@ -0,0 +1,41 @@
+# GitHub Actions Templates
+
+## Node.js Baseline
+
+```yaml
+name: Node CI
+on: [push, pull_request]
+
+jobs:
+ ci:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ cache: 'npm'
+ - run: npm ci
+ - run: npm run lint
+ - run: npm test
+ - run: npm run build
+```
+
+## Python Baseline
+
+```yaml
+name: Python CI
+on: [push, pull_request]
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.12'
+ - run: python3 -m pip install -U pip
+ - run: python3 -m pip install -r requirements.txt
+ - run: python3 -m pytest
+```
diff --git a/skills/ci-cd-pipeline-builder/references/gitlab-ci-templates.md b/skills/ci-cd-pipeline-builder/references/gitlab-ci-templates.md
new file mode 100644
index 00000000..922510fb
--- /dev/null
+++ b/skills/ci-cd-pipeline-builder/references/gitlab-ci-templates.md
@@ -0,0 +1,39 @@
+# GitLab CI Templates
+
+## Node.js Baseline
+
+```yaml
+stages:
+ - lint
+ - test
+ - build
+
+node_lint:
+ image: node:20
+ stage: lint
+ script:
+ - npm ci
+ - npm run lint
+
+node_test:
+ image: node:20
+ stage: test
+ script:
+ - npm ci
+ - npm test
+```
+
+## Python Baseline
+
+```yaml
+stages:
+ - test
+
+python_test:
+ image: python:3.12
+ stage: test
+ script:
+ - python3 -m pip install -U pip
+ - python3 -m pip install -r requirements.txt
+ - python3 -m pytest
+```
diff --git a/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py b/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py
new file mode 100644
index 00000000..428b0c54
--- /dev/null
+++ b/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py
@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""Generate CI pipeline YAML from detected stack data.
+
+Input sources:
+- --input stack report JSON file
+- stdin stack report JSON
+- --repo path (auto-detect stack)
+
+Output:
+- text/json summary
+- pipeline YAML written via --output or printed to stdout
+"""
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+class CLIError(Exception):
+ """Raised for expected CLI failures."""
+
+
+@dataclass
+class PipelineSummary:
+ platform: str
+ output: str
+ stages: List[str]
+ uses_cache: bool
+ languages: List[str]
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description="Generate CI/CD pipeline YAML from detected stack.")
+ parser.add_argument("--input", help="Stack report JSON file. If omitted, can read stdin JSON.")
+ parser.add_argument("--repo", help="Repository path for auto-detection fallback.")
+ parser.add_argument("--platform", choices=["github", "gitlab"], required=True, help="Target CI platform.")
+ parser.add_argument("--output", help="Write YAML to this file; otherwise print to stdout.")
+ parser.add_argument("--format", choices=["text", "json"], default="text", help="Summary output format.")
+ return parser.parse_args()
+
+
+def load_json_input(input_path: Optional[str]) -> Optional[Dict[str, Any]]:
+ if input_path:
+ try:
+ return json.loads(Path(input_path).read_text(encoding="utf-8"))
+ except Exception as exc:
+ raise CLIError(f"Failed reading --input: {exc}") from exc
+
+ if not sys.stdin.isatty():
+ raw = sys.stdin.read().strip()
+ if raw:
+ try:
+ return json.loads(raw)
+ except json.JSONDecodeError as exc:
+ raise CLIError(f"Invalid JSON from stdin: {exc}") from exc
+
+ return None
+
+
+def detect_stack(repo: Path) -> Dict[str, Any]:
+ scripts = {}
+ pkg_file = repo / "package.json"
+ if pkg_file.exists():
+ try:
+ pkg = json.loads(pkg_file.read_text(encoding="utf-8"))
+ raw_scripts = pkg.get("scripts", {})
+ if isinstance(raw_scripts, dict):
+ scripts = raw_scripts
+ except Exception:
+ scripts = {}
+
+ languages: List[str] = []
+ if pkg_file.exists():
+ languages.append("node")
+ if (repo / "pyproject.toml").exists() or (repo / "requirements.txt").exists():
+ languages.append("python")
+ if (repo / "go.mod").exists():
+ languages.append("go")
+
+ return {
+ "languages": sorted(set(languages)),
+ "signals": {
+ "pnpm_lock": (repo / "pnpm-lock.yaml").exists(),
+ "yarn_lock": (repo / "yarn.lock").exists(),
+ "npm_lock": (repo / "package-lock.json").exists(),
+ "dockerfile": (repo / "Dockerfile").exists(),
+ },
+ "lint_commands": ["npm run lint"] if "lint" in scripts else [],
+ "test_commands": ["npm test"] if "test" in scripts else [],
+ "build_commands": ["npm run build"] if "build" in scripts else [],
+ }
+
+
+def select_node_install(signals: Dict[str, Any]) -> str:
+ if signals.get("pnpm_lock"):
+ return "pnpm install --frozen-lockfile"
+ if signals.get("yarn_lock"):
+ return "yarn install --frozen-lockfile"
+ return "npm ci"
+
+
+def github_yaml(stack: Dict[str, Any]) -> str:
+ langs = stack.get("languages", [])
+ signals = stack.get("signals", {})
+ lint_cmds = stack.get("lint_commands", []) or ["echo 'No lint command configured'"]
+ test_cmds = stack.get("test_commands", []) or ["echo 'No test command configured'"]
+ build_cmds = stack.get("build_commands", []) or ["echo 'No build command configured'"]
+
+ lines: List[str] = [
+ "name: CI",
+ "on:",
+ " push:",
+ " branches: [main, develop]",
+ " pull_request:",
+ " branches: [main, develop]",
+ "",
+ "jobs:",
+ ]
+
+ if "node" in langs:
+ lines.extend(
+ [
+ " node-ci:",
+ " runs-on: ubuntu-latest",
+ " steps:",
+ " - uses: actions/checkout@v4",
+ " - uses: actions/setup-node@v4",
+ " with:",
+ " node-version: '20'",
+ " cache: 'npm'",
+ f" - run: {select_node_install(signals)}",
+ ]
+ )
+ for cmd in lint_cmds + test_cmds + build_cmds:
+ lines.append(f" - run: {cmd}")
+
+ if "python" in langs:
+ lines.extend(
+ [
+ " python-ci:",
+ " runs-on: ubuntu-latest",
+ " steps:",
+ " - uses: actions/checkout@v4",
+ " - uses: actions/setup-python@v5",
+ " with:",
+ " python-version: '3.12'",
+ " - run: python3 -m pip install -U pip",
+ " - run: python3 -m pip install -r requirements.txt || true",
+ " - run: python3 -m pytest || true",
+ ]
+ )
+
+ if "go" in langs:
+ lines.extend(
+ [
+ " go-ci:",
+ " runs-on: ubuntu-latest",
+ " steps:",
+ " - uses: actions/checkout@v4",
+ " - uses: actions/setup-go@v5",
+ " with:",
+ " go-version: '1.22'",
+ " - run: go test ./...",
+ " - run: go build ./...",
+ ]
+ )
+
+ return "\n".join(lines) + "\n"
+
+
+def gitlab_yaml(stack: Dict[str, Any]) -> str:
+ langs = stack.get("languages", [])
+ signals = stack.get("signals", {})
+ lint_cmds = stack.get("lint_commands", []) or ["echo 'No lint command configured'"]
+ test_cmds = stack.get("test_commands", []) or ["echo 'No test command configured'"]
+ build_cmds = stack.get("build_commands", []) or ["echo 'No build command configured'"]
+
+ lines: List[str] = [
+ "stages:",
+ " - lint",
+ " - test",
+ " - build",
+ "",
+ ]
+
+ if "node" in langs:
+ install_cmd = select_node_install(signals)
+ lines.extend(
+ [
+ "node_lint:",
+ " image: node:20",
+ " stage: lint",
+ " script:",
+ f" - {install_cmd}",
+ ]
+ )
+ for cmd in lint_cmds:
+ lines.append(f" - {cmd}")
+ lines.extend(
+ [
+ "",
+ "node_test:",
+ " image: node:20",
+ " stage: test",
+ " script:",
+ f" - {install_cmd}",
+ ]
+ )
+ for cmd in test_cmds:
+ lines.append(f" - {cmd}")
+ lines.extend(
+ [
+ "",
+ "node_build:",
+ " image: node:20",
+ " stage: build",
+ " script:",
+ f" - {install_cmd}",
+ ]
+ )
+ for cmd in build_cmds:
+ lines.append(f" - {cmd}")
+
+ if "python" in langs:
+ lines.extend(
+ [
+ "",
+ "python_test:",
+ " image: python:3.12",
+ " stage: test",
+ " script:",
+ " - python3 -m pip install -U pip",
+ " - python3 -m pip install -r requirements.txt || true",
+ " - python3 -m pytest || true",
+ ]
+ )
+
+ if "go" in langs:
+ lines.extend(
+ [
+ "",
+ "go_test:",
+ " image: golang:1.22",
+ " stage: test",
+ " script:",
+ " - go test ./...",
+ " - go build ./...",
+ ]
+ )
+
+ return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+ args = parse_args()
+ stack = load_json_input(args.input)
+
+ if stack is None:
+ if not args.repo:
+ raise CLIError("Provide stack input via --input/stdin or set --repo for auto-detection.")
+ repo = Path(args.repo).resolve()
+ if not repo.exists() or not repo.is_dir():
+ raise CLIError(f"Invalid repo path: {repo}")
+ stack = detect_stack(repo)
+
+ if args.platform == "github":
+ yaml_content = github_yaml(stack)
+ else:
+ yaml_content = gitlab_yaml(stack)
+
+ output_path = args.output or "stdout"
+ if args.output:
+ out = Path(args.output)
+ out.parent.mkdir(parents=True, exist_ok=True)
+ out.write_text(yaml_content, encoding="utf-8")
+ else:
+ print(yaml_content, end="")
+
+ summary = PipelineSummary(
+ platform=args.platform,
+ output=output_path,
+ stages=["lint", "test", "build"],
+ uses_cache=True,
+ languages=stack.get("languages", []),
+ )
+
+ if args.format == "json":
+ print(json.dumps(asdict(summary), indent=2), file=sys.stderr if not args.output else sys.stdout)
+ else:
+ text = (
+ "Pipeline generated\n"
+ f"- platform: {summary.platform}\n"
+ f"- output: {summary.output}\n"
+ f"- stages: {', '.join(summary.stages)}\n"
+ f"- languages: {', '.join(summary.languages) if summary.languages else 'none'}"
+ )
+ print(text, file=sys.stderr if not args.output else sys.stdout)
+
+ return 0
+
+
+if __name__ == "__main__":
+ try:
+ raise SystemExit(main())
+ except CLIError as exc:
+ print(f"ERROR: {exc}", file=sys.stderr)
+ raise SystemExit(2)
diff --git a/skills/ci-cd-pipeline-builder/scripts/stack_detector.py b/skills/ci-cd-pipeline-builder/scripts/stack_detector.py
new file mode 100644
index 00000000..84e6c272
--- /dev/null
+++ b/skills/ci-cd-pipeline-builder/scripts/stack_detector.py
@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""Detect project stack/tooling signals for CI/CD pipeline generation.
+
+Input sources:
+- repository scan via --repo
+- JSON via --input file
+- JSON via stdin
+
+Output:
+- text summary or JSON payload
+"""
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+class CLIError(Exception):
+ """Raised for expected CLI failures."""
+
+
+@dataclass
+class StackReport:
+ repo: str
+ languages: List[str]
+ package_managers: List[str]
+ ci_targets: List[str]
+ test_commands: List[str]
+ build_commands: List[str]
+ lint_commands: List[str]
+ signals: Dict[str, bool]
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description="Detect stack/tooling from a repository.")
+ parser.add_argument("--input", help="JSON input file (precomputed signal payload).")
+ parser.add_argument("--repo", default=".", help="Repository path to scan.")
+ parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format.")
+ return parser.parse_args()
+
+
+def load_payload(input_path: Optional[str]) -> Optional[dict]:
+ if input_path:
+ try:
+ return json.loads(Path(input_path).read_text(encoding="utf-8"))
+ except Exception as exc:
+ raise CLIError(f"Failed reading --input file: {exc}") from exc
+
+ if not sys.stdin.isatty():
+ raw = sys.stdin.read().strip()
+ if raw:
+ try:
+ return json.loads(raw)
+ except json.JSONDecodeError as exc:
+ raise CLIError(f"Invalid JSON from stdin: {exc}") from exc
+
+ return None
+
+
+def read_package_scripts(repo: Path) -> Dict[str, str]:
+ pkg = repo / "package.json"
+ if not pkg.exists():
+ return {}
+ try:
+ data = json.loads(pkg.read_text(encoding="utf-8"))
+ except Exception:
+ return {}
+ scripts = data.get("scripts", {})
+ return scripts if isinstance(scripts, dict) else {}
+
+
+def detect(repo: Path) -> StackReport:
+ signals = {
+ "package_json": (repo / "package.json").exists(),
+ "pnpm_lock": (repo / "pnpm-lock.yaml").exists(),
+ "yarn_lock": (repo / "yarn.lock").exists(),
+ "npm_lock": (repo / "package-lock.json").exists(),
+ "pyproject": (repo / "pyproject.toml").exists(),
+ "requirements": (repo / "requirements.txt").exists(),
+ "go_mod": (repo / "go.mod").exists(),
+ "dockerfile": (repo / "Dockerfile").exists(),
+ "vercel": (repo / "vercel.json").exists(),
+ "helm": (repo / "helm").exists() or (repo / "charts").exists(),
+ "k8s": (repo / "k8s").exists() or (repo / "kubernetes").exists(),
+ }
+
+ languages: List[str] = []
+ package_managers: List[str] = []
+ ci_targets: List[str] = ["github", "gitlab"]
+
+ if signals["package_json"]:
+ languages.append("node")
+ if signals["pnpm_lock"]:
+ package_managers.append("pnpm")
+ elif signals["yarn_lock"]:
+ package_managers.append("yarn")
+ else:
+ package_managers.append("npm")
+
+ if signals["pyproject"] or signals["requirements"]:
+ languages.append("python")
+ package_managers.append("pip")
+
+ if signals["go_mod"]:
+ languages.append("go")
+
+ scripts = read_package_scripts(repo)
+ lint_commands: List[str] = []
+ test_commands: List[str] = []
+ build_commands: List[str] = []
+
+ if "lint" in scripts:
+ lint_commands.append("npm run lint")
+ if "test" in scripts:
+ test_commands.append("npm test")
+ if "build" in scripts:
+ build_commands.append("npm run build")
+
+ if "python" in languages:
+ lint_commands.append("python3 -m ruff check .")
+ test_commands.append("python3 -m pytest")
+
+ if "go" in languages:
+ lint_commands.append("go vet ./...")
+ test_commands.append("go test ./...")
+ build_commands.append("go build ./...")
+
+ return StackReport(
+ repo=str(repo.resolve()),
+ languages=sorted(set(languages)),
+ package_managers=sorted(set(package_managers)),
+ ci_targets=ci_targets,
+ test_commands=sorted(set(test_commands)),
+ build_commands=sorted(set(build_commands)),
+ lint_commands=sorted(set(lint_commands)),
+ signals=signals,
+ )
+
+
+def format_text(report: StackReport) -> str:
+ lines = [
+ "Detected stack",
+ f"- repo: {report.repo}",
+ f"- languages: {', '.join(report.languages) if report.languages else 'none'}",
+ f"- package managers: {', '.join(report.package_managers) if report.package_managers else 'none'}",
+ f"- lint commands: {', '.join(report.lint_commands) if report.lint_commands else 'none'}",
+ f"- test commands: {', '.join(report.test_commands) if report.test_commands else 'none'}",
+ f"- build commands: {', '.join(report.build_commands) if report.build_commands else 'none'}",
+ ]
+ return "\n".join(lines)
+
+
+def main() -> int:
+ args = parse_args()
+ payload = load_payload(args.input)
+
+ if payload:
+ try:
+ report = StackReport(**payload)
+ except TypeError as exc:
+ raise CLIError(f"Invalid input payload for StackReport: {exc}") from exc
+ else:
+ repo = Path(args.repo).resolve()
+ if not repo.exists() or not repo.is_dir():
+ raise CLIError(f"Invalid repo path: {repo}")
+ report = detect(repo)
+
+ if args.format == "json":
+ print(json.dumps(asdict(report), indent=2))
+ else:
+ print(format_text(report))
+
+ return 0
+
+
+if __name__ == "__main__":
+ try:
+ raise SystemExit(main())
+ except CLIError as exc:
+ print(f"ERROR: {exc}", file=sys.stderr)
+ raise SystemExit(2)
diff --git a/skills/ciso-advisor/SKILL.md b/skills/ciso-advisor/SKILL.md
new file mode 100644
index 00000000..ef7d035c
--- /dev/null
+++ b/skills/ciso-advisor/SKILL.md
@@ -0,0 +1,135 @@
+---
+name: "ciso-advisor"
+description: "Security leadership for growth-stage companies. Risk quantification in dollars, compliance roadmap (SOC 2/ISO 27001/HIPAA/GDPR), security architecture strategy, incident response leadership, and board-level security reporting. Use when building security programs, justifying security budget, selecting compliance frameworks, managing incidents, assessing vendor risk, or when user mentions CISO, security strategy, compliance roadmap, zero trust, or board security reporting."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: ciso-leadership
+ updated: 2026-03-05
+ python-tools: risk_quantifier.py, compliance_tracker.py
+ frameworks: risk-based-security, zero-trust, defense-in-depth
+---
+
+# CISO Advisor
+
+Risk-based security frameworks for growth-stage companies. Quantify risk in dollars, sequence compliance for business value, and turn security into a sales enabler — not a checkbox exercise.
+
+## Keywords
+CISO, security strategy, risk quantification, ALE, SLE, ARO, security posture, compliance roadmap, SOC 2, ISO 27001, HIPAA, GDPR, zero trust, defense in depth, incident response, board security reporting, vendor assessment, security budget, cyber risk, program maturity
+
+## Quick Start
+
+```bash
+python scripts/risk_quantifier.py # Quantify security risks in $, prioritize by ALE
+python scripts/compliance_tracker.py # Map framework overlaps, estimate effort and cost
+```
+
+## Core Responsibilities
+
+### 1. Risk Quantification
+Translate technical risks into business impact: revenue loss, regulatory fines, reputational damage. Use ALE to prioritize. See `references/security_strategy.md`.
+
+**Formula:** `ALE = SLE × ARO` (Single Loss Expectancy × Annual Rate of Occurrence). Board language: "This risk has $X expected annual loss. Mitigation costs $Y."
+
+### 2. Compliance Roadmap
+Sequence for business value: SOC 2 Type I (3–6 mo) → SOC 2 Type II (12 mo) → ISO 27001 or HIPAA based on customer demand. See `references/compliance_roadmap.md` for timelines and costs.
+
+### 3. Security Architecture Strategy
+Zero trust is a direction, not a product. Sequence: identity (IAM + MFA) → network segmentation → data classification. Defense in depth beats single-layer reliance. See `references/security_strategy.md`.
+
+### 4. Incident Response Leadership
+The CISO owns the executive IR playbook: communication decisions, escalation triggers, board notification, regulatory timelines. See `references/incident_response.md` for templates.
+
+### 5. Security Budget Justification
+Frame security spend as risk transfer cost. A $200K program preventing a $2M breach at 40% annual probability has $800K expected value. See `references/security_strategy.md`.
+
+### 6. Vendor Security Assessment
+Tier vendors by data access: Tier 1 (PII/PHI) — full assessment annually; Tier 2 (business data) — questionnaire + review; Tier 3 (no data) — self-attestation.
+
+## Key Questions a CISO Asks
+
+- "What's our crown jewel data, and who can access it right now?"
+- "If we had a breach today, what's our regulatory notification timeline?"
+- "Which compliance framework do our top 3 prospects actually require?"
+- "What's our blast radius if our largest SaaS vendor is compromised?"
+- "We spent $X on security last year — what specific risks did that reduce?"
+
+## Security Metrics
+
+| Category | Metric | Target |
+|----------|--------|--------|
+| Risk | ALE coverage (mitigated risk / total risk) | > 80% |
+| Detection | Mean Time to Detect (MTTD) | < 24 hours |
+| Response | Mean Time to Respond (MTTR) | < 4 hours |
+| Compliance | Controls passing audit | > 95% |
+| Hygiene | Critical patches within SLA | > 99% |
+| Access | Privileged accounts reviewed quarterly | 100% |
+| Vendor | Tier 1 vendors assessed annually | 100% |
+| Training | Phishing simulation click rate | < 5% |
+
+## Red Flags
+
+- Security budget justified by "industry benchmarks" rather than risk analysis
+- Certifications pursued before basic hygiene (patching, MFA, backups)
+- No documented asset inventory — can't protect what you don't know you have
+- IR plan exists but has never been tested (tabletop or live drill)
+- Security team reports to IT, not executive level — misaligned incentives
+- Single vendor for identity + endpoint + email — one breach, total exposure
+- Security questionnaire backlog > 30 days — silently losing enterprise deals
+
+## Integration with Other C-Suite Roles
+
+| When... | CISO works with... | To... |
+|---------|--------------------|-------|
+| Enterprise sales | CRO | Answer questionnaires, unblock deals |
+| New product features | CTO/CPO | Threat modeling, security review |
+| Compliance budget | CFO | Size program against risk exposure |
+| Vendor contracts | Legal/COO | Security SLAs and right-to-audit |
+| M&A due diligence | CEO/CFO | Target security posture assessment |
+| Incident occurs | CEO/Legal | Response coordination and disclosure |
+
+## Detailed References
+- `references/security_strategy.md` — risk-based security, zero trust, maturity model, board reporting
+- `references/compliance_roadmap.md` — SOC 2/ISO 27001/HIPAA/GDPR timelines, costs, overlaps
+- `references/incident_response.md` — executive IR playbook, communication templates, tabletop design
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- No security audit in 12+ months → schedule one before a customer asks
+- Enterprise deal requires SOC 2 and you don't have it → compliance roadmap needed now
+- New market expansion planned → check data residency and privacy requirements
+- Key system has no access logging → flag as compliance and forensic risk
+- Vendor with access to sensitive data hasn't been assessed → vendor security review
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Assess our security posture" | Risk register with quantified business impact (ALE) |
+| "We need SOC 2" | Compliance roadmap with timeline, cost, effort, quick wins |
+| "Prep for security audit" | Gap analysis against target framework with remediation plan |
+| "We had an incident" | IR coordination plan + communication templates |
+| "Security board section" | Risk posture summary, compliance status, incident report |
+
+## Reasoning Technique: Risk-Based Reasoning
+
+Evaluate every decision through probability × impact. Quantify risks in business terms (dollars, not severity labels). Prioritize by expected annual loss.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/ciso-advisor/_meta.json b/skills/ciso-advisor/_meta.json
new file mode 100644
index 00000000..a6194c50
--- /dev/null
+++ b/skills/ciso-advisor/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "ciso-advisor",
+ "displayName": "Ciso Advisor",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773175660024,
+ "commit": "https://github.com/openclaw/skills/commit/60607b94f35aa7ec4f4de6205bc1a1274c9188b9"
+ },
+ "history": [
+ {
+ "version": "2.0.0",
+ "publishedAt": 1772746546456,
+ "commit": "https://github.com/openclaw/skills/commit/0010bd9be3e97b3a57e5ee0d4545037e55807d80"
+ }
+ ]
+}
diff --git a/skills/ciso-advisor/references/compliance_roadmap.md b/skills/ciso-advisor/references/compliance_roadmap.md
new file mode 100644
index 00000000..68c4aca1
--- /dev/null
+++ b/skills/ciso-advisor/references/compliance_roadmap.md
@@ -0,0 +1,370 @@
+# Compliance Roadmap Reference
+
+## Decision Framework: Which Framework First?
+
+**Start here — who are your customers?**
+
+```
+Enterprise SaaS (B2B, US market) → SOC 2 Type II first
+Healthcare / health data → HIPAA + SOC 2 together
+EU customers or EU-resident data → GDPR (non-optional if applicable)
+EU enterprise sales → ISO 27001 + GDPR
+Government / defense → FedRAMP / CMMC (separate scope)
+All of the above (Series B+) → Multi-framework efficiency approach
+```
+
+**The sequencing principle:** SOC 2 Type I is the fastest proof of intent (3–6 months). Type II is the credibility signal (12 months). Everything else builds on your control library.
+
+---
+
+## 1. SOC 2
+
+### What It Is
+SOC 2 is an attestation (not a certification) that your controls meet the AICPA Trust Service Criteria. An independent CPA firm audits your controls and issues a report.
+
+- **Type I:** Controls are suitably designed at a point in time (snapshot). Lower credibility but faster.
+- **Type II:** Controls operated effectively over a period of time (minimum 6 months). This is what enterprise buyers want.
+
+### Trust Service Criteria (TSC)
+You must include **Security** (CC). Others are optional:
+| Criteria | When to add |
+|---|---|
+| Security (CC) | Always required |
+| Availability | If uptime SLAs are contractual |
+| Confidentiality | If you process confidential third-party data |
+| Processing Integrity | If accuracy of processing is critical (fintech, data processing) |
+| Privacy | If you make privacy commitments beyond GDPR/CCPA scope |
+
+Most startups: **Security + Availability** is sufficient.
+
+### Timeline: SOC 2 Type I
+
+| Phase | Duration | Activities |
+|---|---|---|
+| Readiness assessment | 2–4 weeks | Gap analysis against CC criteria, identify control owners |
+| Policy documentation | 4–6 weeks | Write ~15–20 policies (acceptable use, access control, change management, etc.) |
+| Control implementation | 4–8 weeks | Deploy technical controls, fix gaps identified in readiness |
+| Evidence collection | 2–4 weeks | Screenshots, logs, configs — auditor will sample these |
+| Audit fieldwork | 2–4 weeks | CPA firm reviews evidence, interviews control owners |
+| Report issuance | 2–4 weeks | Report issued, reviewed, shared with customers |
+| **Total** | **3–6 months** | — |
+
+### Timeline: SOC 2 Type II (after Type I)
+
+| Phase | Duration | Notes |
+|---|---|---|
+| Observation period | 6–12 months | Controls must operate consistently — no exceptions |
+| Audit fieldwork | 4–6 weeks | Auditor samples evidence across full period |
+| Report issuance | 2–4 weeks | — |
+| **Total from Type I** | **9–18 months** | Faster if Type I was clean |
+
+### Cost Estimates
+
+| Item | SOC 2 Type I | SOC 2 Type II |
+|---|---|---|
+| Audit firm fees | $15,000–$35,000 | $25,000–$60,000 |
+| Compliance platform (Vanta, Drata, Secureframe) | $12,000–$30,000/yr | Same platform |
+| External counsel / vCISO | $10,000–$30,000 | $5,000–$15,000 maintenance |
+| Internal time (eng + ops) | 200–400 hours | 100–200 hours/yr |
+| **Total first year** | **$40,000–$100,000** | **+$30,000–$75,000** |
+
+**Cost optimization tips:**
+- Use a compliance platform (Vanta, Drata, Secureframe) — automated evidence collection halves audit cost
+- Choose a mid-tier audit firm; Big 4 is overkill for startups
+- Type I and Type II with same auditor = continuity discount
+
+### Common Failure Modes
+1. Controls documented but not operating (access reviews on paper only)
+2. Exceptions during observation period (one admin account without MFA = finding)
+3. No formal security awareness training (required for CC criteria)
+4. Change management not followed (no ticket for that production change)
+5. Vendor risk management missing (you must assess your critical vendors)
+
+---
+
+## 2. ISO 27001
+
+### What It Is
+ISO 27001 is an internationally recognized certification for an Information Security Management System (ISMS). Unlike SOC 2, it's a certification (pass/fail), not an attestation report. Issued by accredited certification bodies (BSI, Bureau Veritas, DNV, TÜV).
+
+**Why ISO 27001 over SOC 2:** EU enterprise buyers, government contracts, and global markets often prefer or require ISO 27001. It's geographically neutral.
+
+### Scope Decision
+ISO 27001 scope is flexible — you can certify a subset of the organization.
+- **Narrow scope:** The production environment only — fastest, cheapest
+- **Full scope:** Entire organization — most credibility, highest effort
+- **Recommended for startups:** Production environment + key business processes
+
+### Certification Timeline
+
+| Phase | Duration | Activities |
+|---|---|---|
+| Gap analysis | 2–4 weeks | Assess current state vs. 93 controls in Annex A |
+| ISMS design | 4–8 weeks | Scope, risk methodology, SoA (Statement of Applicability) |
+| Policy and procedure development | 6–10 weeks | Mandatory documents: risk treatment plan, asset register, ISMS policy |
+| Risk assessment | 4–6 weeks | Identify, analyze, evaluate risks; produce risk register |
+| Control implementation | 8–16 weeks | Implement gaps from risk assessment |
+| Internal audit | 2–4 weeks | First internal audit of ISMS |
+| Management review | 1–2 weeks | Leadership sign-off on ISMS |
+| Stage 1 audit (documentation) | 1–2 weeks | Certification body reviews docs and scope |
+| Stage 2 audit (implementation) | 1–2 weeks | Certification body verifies controls are operating |
+| Certification issued | 1–2 weeks | Certificate valid for 3 years with annual surveillance audits |
+| **Total** | **9–18 months** | — |
+
+### Cost Estimates
+
+| Item | Cost |
+|---|---|
+| Certification body fees (Stage 1 + Stage 2) | $15,000–$40,000 |
+| Annual surveillance audits | $8,000–$20,000/yr |
+| vCISO / consultant (if not in-house) | $30,000–$80,000 |
+| GRC platform | $10,000–$25,000/yr |
+| Internal time | 400–800 hours |
+| **Total first year** | **$55,000–$150,000** |
+
+### Mandatory ISO 27001:2022 Documents
+- ISMS scope document
+- Information security policy
+- Risk assessment methodology
+- Risk register with risk treatment plan
+- Statement of Applicability (SoA)
+- Asset inventory
+- Competence and awareness records
+- Internal audit reports
+- Management review minutes
+- Nonconformity and corrective action records
+
+---
+
+## 3. HIPAA for Health Tech Startups
+
+### When HIPAA Applies
+HIPAA applies if you are a **Covered Entity** (healthcare provider, health plan, clearinghouse) or a **Business Associate** (you process, store, or transmit Protected Health Information on behalf of a Covered Entity).
+
+**Key trigger:** If your product touches patient data in any way and a US healthcare provider uses your product, you are likely a Business Associate. You must sign a **BAA (Business Associate Agreement)** with each Covered Entity customer.
+
+### HIPAA Rule Structure
+| Rule | Focus | Key Requirements |
+|---|---|---|
+| Privacy Rule | How PHI can be used and disclosed | Minimum necessary, patient rights, notice of privacy practices |
+| Security Rule | Technical and physical safeguards for ePHI | Required and addressable safeguards |
+| Breach Notification Rule | What to do if PHI is breached | Timing and content of breach notifications |
+
+### Security Rule: Required vs. Addressable
+**Required safeguards** must be implemented exactly as specified. **Addressable safeguards** must be implemented or documented why an equivalent measure was used.
+
+**Key Required Safeguards:**
+- Unique user IDs (no shared logins)
+- Emergency access procedure
+- Audit controls (logging access to ePHI)
+- Transmission security (encryption in transit)
+- Person or entity authentication
+
+**Key Addressable Safeguards (implement or document why not):**
+- Automatic logoff
+- Encryption and decryption (encryption at rest — despite being "addressable," regulators expect it)
+- Audit review procedures
+- Security reminders and training
+
+### HIPAA Compliance Timeline
+
+| Phase | Duration | Activities |
+|---|---|---|
+| Risk analysis | 4–6 weeks | Document all PHI flows, assess risks to PHI — **required by law** |
+| Policy development | 4–8 weeks | Privacy policies, breach notification, workforce training |
+| Technical safeguard implementation | 4–12 weeks | Encryption, audit logging, access controls, BAA templates |
+| Workforce training | 2–4 weeks | Annual HIPAA training for all staff with PHI access |
+| BAA execution | Ongoing | Execute with all vendors who process PHI |
+| **Total** | **4–8 months** | — |
+
+### Cost Estimates
+| Item | Cost |
+|---|---|
+| Initial risk analysis (consultant) | $15,000–$40,000 |
+| Policy development | $8,000–$20,000 |
+| Technical implementation | $20,000–$60,000 |
+| Annual training and maintenance | $5,000–$15,000/yr |
+| HIPAA compliance platform | $10,000–$20,000/yr |
+| **Total first year** | **$45,000–$130,000** |
+
+### HIPAA Penalties (Why This Matters)
+| Violation Category | Penalty per Violation | Annual Cap |
+|---|---|---|
+| Unaware | $100–$50,000 | $25,000 |
+| Reasonable cause | $1,000–$50,000 | $100,000 |
+| Willful neglect (corrected) | $10,000–$50,000 | $250,000 |
+| Willful neglect (not corrected) | $50,000 | $1,500,000 |
+
+---
+
+## 4. GDPR Compliance Program
+
+### When GDPR Applies
+GDPR applies if you:
+- Are established in the EU/EEA
+- Process personal data of EU/EEA residents (regardless of your location)
+- Offer goods or services to EU residents
+- Monitor the behavior of EU residents
+
+**Key point for US startups:** If you have EU users or EU employees, GDPR applies to you.
+
+### Core GDPR Principles (Build These In)
+1. **Lawfulness, fairness, transparency** — have a legal basis for every processing activity
+2. **Purpose limitation** — collect data for specified, explicit purposes only
+3. **Data minimization** — collect only what you need
+4. **Accuracy** — keep data accurate
+5. **Storage limitation** — delete data when no longer needed
+6. **Integrity and confidentiality** — appropriate security measures
+7. **Accountability** — demonstrate compliance
+
+### Legal Bases for Processing
+| Basis | When to use |
+|---|---|
+| Consent | Marketing, non-essential cookies, optional features |
+| Contract | Processing necessary to deliver your service |
+| Legitimate interests | Analytics, fraud prevention, security (requires LIA) |
+| Legal obligation | Compliance with legal requirements |
+| Vital interests | Emergency situations only |
+
+**Avoid over-relying on consent** — it must be freely given, specific, informed, and unambiguous. Contractual basis is more robust for core product data.
+
+### GDPR Compliance Checklist
+
+**Governance:**
+- [ ] Data Protection Officer (DPO) appointed (required for large-scale processing or sensitive data)
+- [ ] Record of Processing Activities (RoPA) maintained
+- [ ] Data Protection Impact Assessments (DPIA) for high-risk processing
+
+**Rights Management (respond within 1 month):**
+- [ ] Right of access (data subject access requests — DSARs)
+- [ ] Right to rectification
+- [ ] Right to erasure ("right to be forgotten")
+- [ ] Right to data portability
+- [ ] Right to object to processing
+
+**Technical Measures:**
+- [ ] Privacy by design in product development
+- [ ] Data minimization enforced
+- [ ] Encryption at rest and in transit
+- [ ] Pseudonymization where possible
+- [ ] Retention policies and automated deletion
+
+**Vendor Management:**
+- [ ] Data Processing Agreements (DPAs) with all processors
+- [ ] Standard Contractual Clauses (SCCs) for non-EU transfers
+
+**Breach Notification:**
+- [ ] Notify supervisory authority within 72 hours of awareness
+- [ ] Notify affected individuals if high risk to their rights and freedoms
+
+### GDPR Compliance Timeline
+
+| Phase | Duration | Activities |
+|---|---|---|
+| Data mapping | 3–6 weeks | Map all personal data flows: collect, store, process, share, delete |
+| Legal basis review | 2–4 weeks | Assign legal basis to each processing activity |
+| Policy updates | 4–6 weeks | Privacy policy, cookie policy, employee data notices |
+| DPA execution | 2–4 weeks | Execute DPAs with all processors (SaaS vendors, cloud providers) |
+| Technical controls | 4–12 weeks | Consent management, data subject rights automation, retention |
+| Staff training | 2–4 weeks | GDPR awareness for all staff |
+| **Total** | **3–6 months** | — |
+
+### GDPR Fines
+- **Standard violations:** Up to €10M or 2% of global annual revenue
+- **Major violations** (basic principles, consent, data subject rights): Up to €20M or 4% of global annual revenue
+- **Highest ever fine:** Meta, €1.2B (2023, data transfers to US)
+
+---
+
+## 5. Multi-Framework Efficiency
+
+### Control Overlap Analysis
+
+The same underlying controls satisfy multiple frameworks. Build once, certify multiple times.
+
+**Core Control Domain Overlap:**
+
+| Control Domain | SOC 2 | ISO 27001 | HIPAA | GDPR |
+|---|---|---|---|---|
+| Access control / IAM | CC6 | A.5.15–A.5.18 | §164.312(a) | Art. 32 |
+| Encryption at rest/transit | CC6.7 | A.8.24 | §164.312(a)(2)(iv) | Art. 32 |
+| Audit logging | CC7.2 | A.8.15, A.8.17 | §164.312(b) | Art. 32 |
+| Incident response | CC7.3–CC7.5 | A.5.24–A.5.28 | §164.308(a)(6) | Art. 33–34 |
+| Vendor/third-party mgmt | CC9 | A.5.19–A.5.22 | §164.308(b) | Art. 28 |
+| Risk assessment | CC3 | Clause 6.1 | §164.308(a)(1) | Art. 32 |
+| Security training | CC1.4 | A.6.3, A.6.8 | §164.308(a)(5) | Art. 39 |
+| Business continuity | A1 | A.5.29–A.5.30 | §164.308(a)(7) | Art. 32 |
+| Data classification | CC6.1 | A.5.9–A.5.13 | §164.514 | Art. 5(1)(c) |
+| Change management | CC8 | A.8.32 | §164.312(c) | Art. 25 |
+
+**Efficiency Rule:** If you build SOC 2 controls correctly, you're ~65–75% of the way to ISO 27001 and ~70% of the way to HIPAA. Don't rebuild — extend.
+
+### Recommended Sequencing by Company Profile
+
+**B2B SaaS (US-focused):**
+```
+Month 0–6: SOC 2 Type I → unblocks early enterprise deals
+Month 6–18: SOC 2 Type II → enterprise table stakes
+Month 18–30: ISO 27001 → EU market expansion
+ (GDPR should be woven in from month 0 if any EU data)
+```
+
+**HealthTech (US):**
+```
+Month 0–8: HIPAA compliance + BAA readiness → enables healthcare customers
+Month 6–18: SOC 2 Type II → enterprise IT requirements on top of HIPAA
+Month 18+: ISO 27001 if entering European market
+```
+
+**EU-founded SaaS:**
+```
+Month 0–3: GDPR compliance → legal requirement, not optional
+Month 3–12: ISO 27001 → EU enterprise default expectation
+Month 12–24: SOC 2 → US market expansion
+```
+
+**HealthTech (EU):**
+```
+Concurrent: GDPR + ISO 27001 (strong overlap with MDR/IVDR security requirements)
+Month 12+: HIPAA if entering US market
+```
+
+### Shared Evidence Model
+Build your evidence library once. Tag each piece of evidence by framework:
+
+```
+evidence/
+├── access_control/
+│ ├── iam_policy.pdf [SOC2:CC6, ISO:A5.15, HIPAA:164.312a]
+│ ├── mfa_screenshot_Q1.png [SOC2:CC6, ISO:A8.5, HIPAA:164.312d]
+│ └── access_review_log.xlsx [SOC2:CC6, ISO:A5.18, HIPAA:164.308a]
+├── encryption/
+│ ├── kms_config.png [SOC2:CC6.7, ISO:A8.24, HIPAA:164.312e]
+│ └── tls_policy.md [SOC2:CC6.7, ISO:A8.24, HIPAA:164.312e]
+└── incident_response/
+ ├── ir_plan.pdf [SOC2:CC7, ISO:A5.24, HIPAA:164.308a6]
+ └── tabletop_log.pdf [SOC2:CC7, ISO:A5.26, HIPAA:164.308a6]
+```
+
+### GRC Platform Comparison
+
+| Platform | Best For | Price/yr | SOC 2 | ISO 27001 | HIPAA | GDPR |
+|---|---|---|---|---|---|---|
+| Vanta | Fast SOC 2, US startups | $15–30K | ✅ | ✅ | ✅ | ✅ |
+| Drata | Automation depth | $18–35K | ✅ | ✅ | ✅ | ✅ |
+| Secureframe | Cost-effective | $10–20K | ✅ | ✅ | ✅ | ✅ |
+| Sprinto | SMB, global | $12–25K | ✅ | ✅ | ✅ | ✅ |
+| Tugboat Logic | Mid-market | $20–40K | ✅ | ✅ | ✅ | ✅ |
+| Manual | Budget-constrained | $0 + time | ✅ | ✅ | ✅ | ✅ |
+
+**Recommendation:** For Series A startups, Vanta or Drata pays for itself in reduced auditor fees and internal time savings. Budget $15–25K/year.
+
+### Compliance Maintenance Annual Budget
+
+| Item | SOC 2 | ISO 27001 | HIPAA | GDPR |
+|---|---|---|---|---|
+| Annual audit / surveillance | $25–60K | $8–20K | n/a (self-assessed) | n/a (self-assessed) |
+| GRC platform | $15–30K | Shared | Shared | Shared |
+| Annual training | $3–8K | Shared | Shared | Shared |
+| Policy review | $2–5K | $2–5K | $2–5K | $2–5K |
+| **Total ongoing** | **$45–103K/yr** | **+$10–25K/yr** | **+$5–15K/yr** | **+$5–15K/yr** |
diff --git a/skills/ciso-advisor/references/incident_response.md b/skills/ciso-advisor/references/incident_response.md
new file mode 100644
index 00000000..dbb9ccb3
--- /dev/null
+++ b/skills/ciso-advisor/references/incident_response.md
@@ -0,0 +1,350 @@
+# Incident Response Reference (Executive Playbook)
+
+This is the executive IR playbook — strategic decisions, communication, and leadership during incidents. For technical playbooks (containment procedures, forensics), see your SOC runbooks.
+
+---
+
+## 1. Incident Classification
+
+### Severity Levels
+
+| Severity | Definition | Examples | Response Time | Escalation |
+|---|---|---|---|---|
+| SEV-1 (Critical) | Confirmed breach, data exfil, ransomware, production down | Active ransomware, confirmed data theft, complete service outage | Immediate (< 1 hour) | CEO, board within 24 hrs |
+| SEV-2 (High) | Suspected breach, significant security event, extended outage | Credential compromise suspected, DDoS, 4-hour+ outage | < 4 hours | CEO, legal within 48 hrs |
+| SEV-3 (Medium) | Security event with limited impact, short outage | Phishing success (contained), brief outage, single system compromise | < 24 hours | CISO-owned, weekly rollup |
+| SEV-4 (Low) | Minor security event, near-miss | Failed phishing attempt, minor policy violation | < 72 hours | Team-owned |
+
+### Breach vs. Security Incident
+**Security incident:** Unplanned event affecting security — may or may not involve data.
+**Data breach:** Confirmed unauthorized access to personal data — triggers regulatory notification obligations.
+
+**Critical distinction for response planning:** A ransomware attack is an incident. If data was exfiltrated before encryption, it's also a breach. Assume breach until proven otherwise.
+
+---
+
+## 2. Executive IR Plan
+
+### Phase 1: Detection & Initial Assessment (0–2 hours for SEV-1)
+
+**Immediate actions (CISO):**
+1. Receive alert from SOC/monitoring system or team member report
+2. Make initial severity classification — don't wait for perfect information
+3. Activate incident response team (IR lead, legal counsel, comms lead)
+4. Create incident war room (dedicated Slack channel, video bridge, shared document)
+5. **Stop the clock** — document exact time of discovery (regulatory timelines start here)
+6. Begin chain of custody documentation if forensics may be needed
+
+**Executive notification trigger (within 1 hour for SEV-1):**
+- Notify CEO: incident status, initial severity, IR team activated
+- Put legal counsel on notice — don't wait to determine if breach occurred
+- If public company: notify General Counsel immediately (potential disclosure obligations)
+
+**What you do NOT do in Phase 1:**
+- Do not notify customers yet (confirm scope first)
+- Do not delete or modify any logs or systems (evidence preservation)
+- Do not make public statements
+- Do not speculate about cause or scope
+
+### Phase 2: Containment & Assessment (2–24 hours for SEV-1)
+
+**Executive decisions required:**
+- **Scope authorization:** Approve IR firm engagement (have a retainer in place)
+- **System isolation:** Authorize taking systems offline if needed (revenue vs. evidence tradeoff)
+- **Evidence preservation:** Authorize forensic image capture
+- **Communication timing:** When to notify customers/partners (legal drives this)
+
+**Board notification (for SEV-1/2):**
+- Notify board chair / audit committee chair within 24 hours for SEV-1
+- Board notification format: what we know, what we don't know, what we're doing, next update time
+- Do not speculate on financial impact in board notification until known
+
+**Legal assessment (with counsel):**
+- Determine if personal data was involved
+- Identify applicable notification laws (GDPR 72-hour, state breach notification, HIPAA 60-day)
+- Assess litigation risk (document with privilege from this point)
+- Evaluate cyber insurance policy coverage and notification requirements
+
+### Phase 3: Notification & Communication (24–72 hours for SEV-1)
+
+**Notification decision matrix:**
+| Audience | Trigger | Timeline | Owner |
+|---|---|---|---|
+| Board | SEV-1/2 confirmed | < 24 hours | CEO/CISO |
+| Regulators (GDPR) | Personal data breach confirmed | < 72 hours from awareness | Legal + CISO |
+| Regulators (HIPAA) | PHI breach confirmed | < 60 days (early notice to HHS ASAP) | Legal + CISO |
+| State regulators (US) | State breach notification laws vary | 30–90 days depending on state | Legal |
+| Enterprise customers | Data confirmed in scope | As soon as practical after legal review | CEO/CRO |
+| All customers | Data potentially in scope | After regulators notified | CEO/Comms |
+| Media | Proactive or reactive | After notifying affected parties | CEO/Comms |
+| Cyber insurer | Incident confirmed | Per policy terms (often 48–72 hours) | CFO/Legal |
+
+### Phase 4: Recovery (Ongoing)
+
+**Executive decisions:**
+- Approve recovery timeline and communicate to customers
+- Determine customer compensation or remediation (if applicable)
+- Authorize security improvements identified during incident
+- Decide on public disclosure beyond mandatory reporting
+
+### Phase 5: Post-Incident Review (Within 30 days)
+
+Covered in Section 5 of this document.
+
+---
+
+## 3. Communication Templates
+
+### Board/Executive Notification (Initial — Hour 1)
+
+**Subject:** [CONFIDENTIAL] Security Incident — Immediate Notification
+
+---
+We have identified a security incident as of [DATE/TIME].
+
+**Current status:** [Brief factual description — what we know happened]
+
+**Severity assessment:** SEV-[1/2/3]
+
+**What we do not yet know:**
+- [List unknowns — scope of impact, whether data was accessed, root cause]
+
+**Actions taken so far:**
+- IR team activated at [time]
+- Legal counsel notified
+- [Specific containment actions if applicable]
+
+**Next update:** [Specific time, e.g., "in 4 hours or when we have material new information"]
+
+**Who is managing this:** [CISO name] leads technical response; [CEO name] owns executive decisions. Contact: [CISO mobile]
+
+---
+
+### Customer Notification (After Legal Review)
+
+**Subject:** Important Security Notice — [Company Name]
+
+---
+We are writing to inform you of a security incident that may have affected your data.
+
+**What happened:**
+On [DATE], we detected [brief, factual description of the incident — e.g., "unauthorized access to our systems"]. We identified this on [DISCOVERY DATE] and immediately launched an investigation.
+
+**What information was involved:**
+Based on our investigation, the following types of information may have been accessed: [list data types — e.g., names, email addresses, [if applicable: payment card information]].
+
+Your [specific data types] [were / were not] affected.
+
+**What we are doing:**
+We have [list specific actions: engaged leading cybersecurity firm, notified relevant authorities, implemented additional security controls, etc.].
+
+**What you can do:**
+- [Specific actionable steps for customers]
+- Monitor your accounts for unusual activity
+- [If passwords: reset your password at X]
+- [If payment data: contact your bank to monitor for unauthorized charges]
+- Contact our dedicated support line at [contact] with any concerns
+
+**For more information:**
+We have set up a dedicated resource page at [URL]. Our support team is available at [contact].
+
+We take the security of your data extremely seriously and deeply regret this incident occurred.
+
+[CEO/CISO Name]
+[Title], [Company Name]
+
+---
+
+### Regulator Notification — GDPR (72-hour requirement)
+
+**To:** [Relevant Supervisory Authority — e.g., BfDI (Germany), CNIL (France), ICO (UK)]
+**Subject:** Personal Data Breach Notification — [Company Name] — [Reference Number if applicable]
+
+---
+**1. Nature of the breach:**
+[Description of what occurred, including how it happened]
+
+**2. Categories and approximate number of data subjects concerned:**
+[e.g., "Approximately [X] customers whose [name, email, account data] may have been accessed"]
+
+**3. Categories and approximate number of personal data records concerned:**
+[e.g., "Approximately [X] records containing [data categories]"]
+
+**4. Likely consequences of the breach:**
+[Risk assessment: what harm could data subjects face?]
+
+**5. Measures taken or proposed:**
+[Containment actions, remediation plan, customer notification plan]
+
+**6. Contact details of the Data Protection Officer or other contact point:**
+[Name, role, email, phone]
+
+**Note:** This is an initial notification; we will provide supplemental information as our investigation continues.
+
+---
+
+### Media Statement (Reactive — When Contacted)
+
+"[Company Name] is aware of a security incident that we identified on [date]. We immediately activated our incident response team and launched a comprehensive investigation. We have notified affected customers and relevant regulatory authorities as required. The security and privacy of our customers' data is our top priority, and we are committed to transparency as our investigation proceeds. We will provide updates at [URL]. We cannot provide additional details at this time to protect the integrity of our investigation."
+
+**What not to say to media:**
+- Number of affected users (until confirmed and disclosed to customers first)
+- Cause of the incident (until investigation is complete)
+- Financial impact (speculation creates liability)
+- Anything that could be construed as minimizing the incident
+
+---
+
+## 4. Tabletop Exercise Design
+
+### Purpose
+Test the decision-making and communication processes — not the technical response. The goal is to surface gaps in escalation, communication, and judgment before a real incident.
+
+### Recommended Frequency
+- Annual full tabletop (2–3 hours, full leadership team)
+- Semi-annual mini-tabletop (45 minutes, CISO + legal + CEO)
+- Quarterly technical team exercise (separate from executive tabletop)
+
+### Sample Tabletop Scenario: Ransomware
+
+**Setup (read to participants):**
+> It's 6:47 AM on a Monday. Your DevOps engineer receives automated alerts that production databases are inaccessible. By 7:15 AM, they discover a ransomware note demanding $500,000 in Bitcoin. Several files are already encrypted. Your last verified backup was 48 hours ago. Your business is B2B SaaS serving 200 enterprise customers. You process customer financial data.
+
+**Discussion questions (timed, 10 minutes each):**
+1. First 30 minutes — who do you call, in what order? Who decides whether to take production offline?
+2. Legal assessment — what regulatory obligations have been triggered? What's the timeline?
+3. Hour 4 — initial forensics suggests data may have been exfiltrated before encryption. How does your response change?
+4. Customer communication — how do you communicate with enterprise customers who are asking for status?
+5. Hour 24 — do you pay the ransom? Who makes this decision? What's the decision framework?
+6. The press has found out and a reporter is calling. What do you say?
+7. Day 5 — what's your board communication strategy?
+
+**Post-discussion captures:**
+- What decisions were unclear (ownership ambiguous)?
+- What information did you need but didn't have?
+- What processes did not exist that should?
+- What would you do differently in the first hour?
+
+### Sample Tabletop Scenario: Insider Threat
+
+**Setup:**
+> HR notifies you that an engineer was terminated this morning for performance reasons. 24 hours later, your SIEM generates an alert that this former employee's credentials accessed your customer database 30 minutes before their offboarding was complete. They downloaded 50,000 customer records. You don't know if they shared or sold the data.
+
+**Key decision points:**
+- When does this become a breach vs. a security incident?
+- Do you notify customers? When?
+- What are your legal options against the former employee?
+- How do you handle this with the rest of the engineering team?
+
+---
+
+## 5. Post-Incident Review Framework
+
+### Timeline
+Conduct within 30 days of incident resolution. Do not delay — memory fades and teams move on.
+
+### Blameless Post-Mortem Principles
+The purpose is to improve systems and processes, not punish individuals. A blame culture means the next incident gets hidden longer.
+
+### Post-Incident Review Structure
+
+**1. Incident Timeline (factual, no editorializing)**
+- Hour-by-hour reconstruction from detection to resolution
+- Source: logs, Slack messages, incident ticket, war room notes
+
+**2. Root Cause Analysis**
+Use the "5 Whys" technique — keep asking why until you reach a systemic root cause, not a human error.
+
+Example:
+- Why was there a breach? → Attacker compromised an admin account
+- Why was the admin account compromised? → Credentials stolen via phishing
+- Why did phishing succeed? → User wasn't trained on this attack type
+- Why wasn't training current? → Training program hadn't been updated in 18 months
+- Why hadn't it been updated? → No owner was assigned to maintain the training program
+- **Root cause: No assigned ownership for security training maintenance**
+
+**3. What Went Well**
+- Detection mechanisms that worked
+- Response actions that contained damage
+- Communication that was effective
+- Teams that exceeded expectations
+
+**4. What Needs Improvement**
+- Detection gaps (how could we have found this faster?)
+- Response gaps (what slowed us down?)
+- Communication gaps (who didn't know what, when?)
+- Process gaps (what didn't we have documented?)
+
+**5. Action Items (with owners and deadlines)**
+| Action | Owner | Due Date | Priority |
+|---|---|---|---|
+| [Specific improvement] | [Name] | [Date] | [P0/P1/P2] |
+
+**6. Metrics Review**
+- MTTD (Mean Time to Detect): [actual] vs. [target]
+- MTTR (Mean Time to Respond): [actual] vs. [target]
+- Customer impact: [affected customers, duration]
+- Financial impact: [direct costs, revenue impact]
+- Regulatory impact: [notifications sent, fines if any]
+
+---
+
+## 6. Insurance and Legal Considerations
+
+### Cyber Insurance
+
+**What to have before an incident:**
+- Cyber liability policy with minimum $2M coverage (Series A); $5M+ (Series B+)
+- Coverage should include: first-party loss, third-party liability, ransomware, business interruption, regulatory defense
+- Pre-approved IR firms on your policy (using an approved firm can expedite claims)
+- Notification requirements — know your insurer's required timeline (typically 48–72 hours)
+
+**Policy exclusions to watch:**
+- "War exclusion" — increasingly contested for nation-state attacks (NotPetya precedent)
+- "Systemic risk" — some policies exclude widespread events affecting many insureds simultaneously
+- "Prior acts" — incidents that began before policy inception
+- "Failure to maintain reasonable security" — don't give your insurer a reason to deny
+
+**Premium factors:**
+- Revenue and data volume
+- Security control maturity (MFA, EDR, backup, patch management)
+- Industry (healthcare, financial services = higher premium)
+- Claims history
+
+**Ballpark premiums:**
+- Seed/Series A ($1–10M ARR): $8,000–$25,000/yr
+- Series B ($10–50M ARR): $25,000–$75,000/yr
+- Series C+ ($50M+ ARR): $75,000–$250,000/yr
+
+### Legal Counsel
+
+**Have on retainer before an incident:**
+- Cybersecurity/privacy attorney — breach notification, regulatory response
+- General counsel — contracts, employment law (insider threats), litigation
+- Consider: a law firm with data breach notification experience by jurisdiction
+
+**Attorney-client privilege:** Once legal counsel is involved in an incident, communications and work product may be privileged. Engage counsel early to maximize privilege protection.
+
+**Key legal decisions during an incident:**
+- When does notification obligation clock start? (Legal determines this)
+- Is this a breach or an incident? (Legal + CISO together)
+- Who are the affected data subjects? (Legal + technical together)
+- Do we pay the ransom? (Legal, CEO, board — never CISO alone)
+- Do we cooperate with law enforcement? (Legal decision, involves trade-offs)
+
+### Law Enforcement
+
+**FBI Internet Crime Complaint Center (IC3):** File a complaint for ransomware or significant cybercrime. Does not obligate you to cooperate but creates a record.
+
+**Pros of law enforcement involvement:**
+- Access to threat intelligence they may have
+- May recover funds in some cases (rare)
+- Demonstrates good-faith response to regulators
+
+**Cons of law enforcement involvement:**
+- Loss of control over investigation timeline
+- Potential for public disclosure if case pursued
+- Slows ransom payment decisions (if considering)
+- May create discovery obligations in litigation
+
+**CISO recommendation:** Notify legal before contacting law enforcement. In most cases, file an IC3 complaint but don't actively engage FBI investigation unless there's a clear benefit.
diff --git a/skills/ciso-advisor/references/security_strategy.md b/skills/ciso-advisor/references/security_strategy.md
new file mode 100644
index 00000000..2644ecf1
--- /dev/null
+++ b/skills/ciso-advisor/references/security_strategy.md
@@ -0,0 +1,321 @@
+# Security Strategy Reference
+
+## 1. Risk-Based Security (Not Compliance-First)
+
+### The Problem with Compliance-First Security
+Most startups build security backwards: they get a compliance requirement (SOC 2, ISO 27001) and treat it as the security program. This produces:
+- Controls that pass audits but don't reduce actual risk
+- Resources allocated to documentation over protection
+- Security teams optimizing for auditor satisfaction, not threat reduction
+- False confidence ("we passed our audit") before real security exists
+
+**The right order:**
+1. Identify your actual threats (what do adversaries want from you?)
+2. Identify your crown jewels (what's worth protecting most?)
+3. Implement controls that address those threats to those assets
+4. Map existing controls to compliance requirements — most overlap naturally
+
+### Risk Identification Framework
+
+**Asset Classification:**
+```
+Tier 1 — Crown Jewels
+├── Customer PII/PHI
+├── Payment card data
+├── Intellectual property (source code, models, trade secrets)
+└── Authentication credentials and secrets
+
+Tier 2 — Business Critical
+├── Internal communications (Slack, email)
+├── Financial systems and data
+├── Employee data
+└── Business strategy documents
+
+Tier 3 — Operational
+├── Internal tooling and infrastructure configs
+├── Non-sensitive operational data
+└── Public-facing content and marketing
+```
+
+**Threat Actor Profiling:**
+| Threat Actor | Motivation | Typical TTPs | Relative Likelihood |
+|---|---|---|---|
+| Financially motivated criminals | Data theft, ransomware | Phishing, credential stuffing | High |
+| Nation-state | IP theft, espionage | Spear phishing, supply chain | Low-Medium (sector-dependent) |
+| Insider threat | Financial gain, revenge | Privilege abuse, data exfil | Medium |
+| Script kiddies | Notoriety, fun | Known CVEs, scanning | High (low sophistication) |
+| Competitors | IP theft | Social engineering, insider recruitment | Low-Medium |
+
+### Risk Quantification (FAIR Model Simplified)
+
+**Annual Loss Expectancy:**
+```
+ALE = SLE × ARO
+SLE (Single Loss Expectancy) = Asset Value × Exposure Factor
+ARO (Annual Rate of Occurrence) = historical frequency or industry estimate
+```
+
+**Business Impact Categories:**
+- **Direct financial loss**: fraud, ransomware payment, theft
+- **Regulatory fines**: GDPR (4% global revenue), HIPAA ($100–$50K per violation), PCI DSS
+- **Revenue impact**: customer churn post-breach, deal loss during incident, downtime cost
+- **Reputational damage**: brand devaluation (harder to quantify, but real)
+- **Legal costs**: incident response counsel, class action defense, settlements
+
+**Example Risk Quantification:**
+
+| Risk Scenario | SLE | ARO | ALE |
+|---|---|---|---|
+| Customer data breach (10K records) | $850K | 0.15 | $127,500/yr |
+| Ransomware attack | $350K | 0.20 | $70,000/yr |
+| Credential compromise + fraud | $120K | 0.35 | $42,000/yr |
+| Third-party SaaS breach | $95K | 0.25 | $23,750/yr |
+| Insider data exfiltration | $180K | 0.10 | $18,000/yr |
+
+**Mitigation ROI:**
+```
+ROSI = (Risk Reduction × ALE) - Control Cost
+ ────────────────────────────────────
+ Control Cost
+
+Example: MFA deployment
+ Risk reduction: 99% for credential attacks
+ ALE reduced: $42,000 × 0.99 = $41,580
+ Control cost: $5,000/yr
+ ROSI: ($41,580 - $5,000) / $5,000 = 731%
+```
+
+---
+
+## 2. Zero Trust Architecture at Strategy Level
+
+### What Zero Trust Actually Means
+Zero trust is not a product — it's an architectural principle: **never trust, always verify, assume breach.**
+
+The traditional perimeter model (trust inside the network, distrust outside) fails because:
+- Remote work destroyed the perimeter
+- Cloud infrastructure has no perimeter
+- 80% of breaches involve privileged account abuse (internal trust abused)
+- Supply chain attacks compromise trusted software
+
+### Zero Trust Maturity Model
+
+**Stage 1 — Identity-Centric (Start Here)**
+- MFA enforced for all users, all applications
+- Identity provider (Okta, Azure AD, Google Workspace) as single control plane
+- No shared service accounts
+- Privileged Access Management (PAM) for admin access
+- **Cost:** $20–80K/year | **Timeline:** 3–6 months
+
+**Stage 2 — Device Trust**
+- Endpoint detection and response (EDR) on all devices
+- Device health checks before granting access
+- Mobile device management (MDM) for BYOD
+- Certificate-based device authentication
+- **Cost:** $30–60K/year additional | **Timeline:** 6–12 months
+
+**Stage 3 — Network Micro-Segmentation**
+- Replace VPN with Zero Trust Network Access (ZTNA)
+- Segment production from development from corporate
+- East-west traffic inspection (not just north-south)
+- **Cost:** $40–100K/year additional | **Timeline:** 12–18 months
+
+**Stage 4 — Application-Level Controls**
+- Just-in-time access (no standing privileges)
+- Workload identity for service-to-service auth
+- API gateway with authentication enforcement
+- Continuous authorization (not just at login)
+- **Cost:** $50–150K/year additional | **Timeline:** 18–30 months
+
+**Strategic Guidance:**
+- Don't sell zero trust as a project. It's a 3–5 year direction.
+- Start with identity. It gives the most risk reduction per dollar.
+- Measure progress by % of access covered by MFA, % of apps behind IdP, privilege account count.
+
+---
+
+## 3. Defense in Depth for Startups
+
+### The Layered Security Model
+
+```
+Layer 1: Governance & Policies
+ └── Asset inventory, acceptable use, vendor management
+
+Layer 2: Perimeter Controls
+ └── WAF, DDoS protection, email security (DMARC/DKIM/SPF)
+
+Layer 3: Identity & Access
+ └── MFA, SSO, PAM, just-in-time access, least privilege
+
+Layer 4: Endpoint Security
+ └── EDR, device management, patch management
+
+Layer 5: Application Security
+ └── SAST/DAST, dependency scanning, code review, API security
+
+Layer 6: Data Protection
+ └── Encryption at rest and in transit, DLP, backup/recovery
+
+Layer 7: Detection & Response
+ └── SIEM/SOAR, log aggregation, alerting, incident response
+
+Layer 8: Recovery
+ └── Backup testing, DR plan, RTO/RPO targets
+```
+
+### Startup Security Budget Allocation (Guidance)
+
+| Stage | Annual Revenue | Recommended Security Budget | Priority Spend |
+|---|---|---|---|
+| Pre-seed/Seed | <$1M | 3–5% opex or $50–100K | MFA, backups, basic EDR |
+| Series A | $1–10M | 2–4% revenue | +SIEM, SOC 2 Type I, AppSec |
+| Series B | $10–50M | 3–5% revenue | +ZTNA, Red team, dedicated CISO |
+| Series C+ | $50M+ | 4–6% revenue | +SOC, threat intelligence, M&A security |
+
+**Non-negotiables regardless of stage:**
+1. MFA on everything (particularly email, cloud consoles, code repos)
+2. Automated backups with tested restore (ransomware defense)
+3. Secrets management (no hardcoded credentials)
+4. Dependency vulnerability scanning in CI/CD
+5. Incident response plan (even a 2-page doc is better than nothing)
+
+---
+
+## 4. Security Program Maturity Model
+
+**Based on NIST CSF and CMMI, simplified for startup context:**
+
+### Level 1: Initial
+- No formal policies
+- Reactive security (respond to incidents, not prevent them)
+- No dedicated security personnel
+- Basic hygiene gaps (unpatched systems, shared passwords)
+- **Typical:** Pre-seed, <20 employees
+
+### Level 2: Developing
+- Written security policies (even if not fully followed)
+- Dedicated security responsibility (often part-time or dual-role)
+- MFA deployed, basic asset inventory
+- Incident response process documented
+- SOC 2 Type I achievable from here in ~6 months
+- **Typical:** Series A, 20–50 employees
+
+### Level 3: Defined
+- Security integrated into SDLC
+- Dedicated security lead or vCISO
+- Regular vulnerability scanning and patching
+- Security awareness training program
+- SOC 2 Type II and ISO 27001 achievable
+- **Typical:** Series B, 50–150 employees
+
+### Level 4: Managed
+- Risk-based security program with quantified risks
+- Security metrics reported to board quarterly
+- Threat intelligence program
+- Dedicated security team (3–8 people)
+- Red team / penetration testing annually
+- **Typical:** Series C+, 150–500 employees
+
+### Level 5: Optimized
+- Continuous monitoring and automated response
+- Proactive threat hunting
+- Industry leadership on security (bug bounty, disclosure program)
+- Security as competitive advantage in sales
+- **Typical:** Public company or regulated enterprise
+
+### Maturity Assessment Questions
+1. Can you list all systems that process customer data right now?
+2. How long would it take to detect if an admin credential was compromised?
+3. When was your last backup tested with a restore?
+4. Do developers run any security checks before code is deployed?
+5. Does the board receive security reporting? What's in it?
+
+Score: 0 = no/don't know, 1 = partially, 2 = yes/verified
+- 0–3: Level 1–2
+- 4–7: Level 2–3
+- 8–10: Level 3–4
+
+---
+
+## 5. Board-Level Security Reporting
+
+### What the Board Cares About
+Boards are not interested in CVE counts or firewall rules. They care about:
+1. **Risk posture:** Are we getting better or worse?
+2. **Regulatory exposure:** What fines could we face?
+3. **Incident readiness:** If we're breached, are we prepared?
+4. **Competitive position:** Do customers trust us with their data?
+5. **Budget adequacy:** Are we investing appropriately?
+
+### Quarterly Board Security Report Structure
+
+**Executive Summary (1 page max)**
+- Security posture score vs. last quarter (directional trend matters more than absolute)
+- Top 3 risks and their business impact in dollars
+- Key accomplishments this quarter
+- Investment requested (if any)
+
+**Risk Dashboard**
+```
+Risk Register Summary:
+├── Critical (>$500K ALE): [count] risks, [count] mitigated
+├── High ($100K–$500K ALE): [count] risks, [count] mitigated
+├── Medium ($10K–$100K ALE): [count] risks
+└── Low (<$10K ALE): [count] risks (for awareness only)
+
+Trend: ↑ Risk exposure vs. Q[n-1] / ↓ Risk exposure vs. Q[n-1]
+```
+
+**Compliance Status**
+- Framework certifications in scope and current status
+- Next audit date
+- Any findings from last audit and remediation status
+
+**Incident Summary**
+- Security incidents last quarter (count and severity)
+- Time to detect / time to respond (vs. targets)
+- Any regulatory reporting obligations triggered
+
+**Key Metrics (4–6 max)**
+- MFA adoption rate
+- Critical patch SLA compliance
+- Phishing simulation click rate (trend)
+- Vendor assessments completed
+
+**Budget Summary**
+- Spend vs. budget
+- Headcount
+- Next quarter key investments and rationale
+
+### Common Board Questions to Prepare For
+- "Have we been breached?" (Know your detection capability, not just your answer)
+- "How do we compare to peers?" (Benchmarks from Verizon DBIR, industry ISACs)
+- "What's the one thing we should invest in?" (Have a clear answer)
+- "If we're acquired, what would security due diligence find?" (Be honest)
+- "What keeps you up at night?" (Have a real answer, not a vague one)
+
+---
+
+## 6. Security as Revenue Enabler
+
+### The Sales Angle
+For B2B companies, security certifications directly impact revenue:
+- Enterprise buyers require SOC 2 as table stakes (increasingly SOC 2 Type II)
+- Government and healthcare require ISO 27001 or HIPAA
+- Passing security questionnaires faster closes deals faster
+- A breach costs 10–30% customer churn; security investment is churn prevention
+
+**How to Measure:**
+- Deals blocked by security questionnaire failures (track in CRM)
+- Average security questionnaire turnaround time
+- Customer security reviews passed vs. failed
+- Revenue attributed to new compliance certifications
+
+### The Trust Narrative
+Position security certifications in marketing:
+- SOC 2 Type II: "Independently audited security controls, verified annually"
+- ISO 27001: "Internationally certified information security management"
+- HIPAA BAA: "Healthcare data protection to regulatory standards"
+
+These aren't just compliance — they're trust signals that compress the sales cycle.
diff --git a/skills/ciso-advisor/scripts/compliance_tracker.py b/skills/ciso-advisor/scripts/compliance_tracker.py
new file mode 100644
index 00000000..5b452938
--- /dev/null
+++ b/skills/ciso-advisor/scripts/compliance_tracker.py
@@ -0,0 +1,781 @@
+#!/usr/bin/env python3
+"""
+CISO Compliance Tracker
+========================
+Tracks compliance requirements across SOC 2, ISO 27001, HIPAA, and GDPR.
+Shows control overlaps, estimates effort and cost, and prioritizes by business value.
+
+Usage:
+ python compliance_tracker.py # Run with sample data
+ python compliance_tracker.py --json # JSON output
+ python compliance_tracker.py --csv output.csv # Export CSV
+ python compliance_tracker.py --framework soc2 # Show single framework
+ python compliance_tracker.py --gap-analysis # Show unaddressed requirements
+ python compliance_tracker.py --roadmap # Show sequenced roadmap
+"""
+
+import json
+import csv
+import sys
+import argparse
+from datetime import datetime, date
+from typing import Optional
+
+
+# ─── Framework Definitions ───────────────────────────────────────────────────
+
+FRAMEWORKS = {
+ "soc2": {
+ "name": "SOC 2 Type II",
+ "full_name": "AICPA Trust Service Criteria — Security",
+ "typical_timeline_months": 12,
+ "typical_cost_usd": 65_000, # Audit + platform
+ "annual_maintenance_usd": 40_000,
+ "business_value": "Enterprise sales unblock, US market table stakes",
+ "mandatory_for": ["B2B SaaS selling to enterprise US companies"],
+ },
+ "iso27001": {
+ "name": "ISO 27001:2022",
+ "full_name": "Information Security Management System",
+ "typical_timeline_months": 15,
+ "typical_cost_usd": 95_000,
+ "annual_maintenance_usd": 30_000,
+ "business_value": "EU enterprise sales, global credibility",
+ "mandatory_for": ["EU enterprise customers", "Government contracts"],
+ },
+ "hipaa": {
+ "name": "HIPAA",
+ "full_name": "Health Insurance Portability and Accountability Act",
+ "typical_timeline_months": 7,
+ "typical_cost_usd": 75_000,
+ "annual_maintenance_usd": 20_000,
+ "business_value": "Healthcare customer access, BAA execution",
+ "mandatory_for": ["Business Associates", "Companies handling PHI"],
+ },
+ "gdpr": {
+ "name": "GDPR",
+ "full_name": "General Data Protection Regulation (EU) 2016/679",
+ "typical_timeline_months": 5,
+ "typical_cost_usd": 45_000,
+ "annual_maintenance_usd": 15_000,
+ "business_value": "EU market access, legal compliance",
+ "mandatory_for": ["EU-based companies", "Any company with EU user data"],
+ },
+}
+
+
+# ─── Control Domain Library ──────────────────────────────────────────────────
+
+def build_control_domain(
+ domain_id: str,
+ name: str,
+ description: str,
+ soc2_ref: Optional[str],
+ iso27001_ref: Optional[str],
+ hipaa_ref: Optional[str],
+ gdpr_ref: Optional[str],
+ effort_days: int, # Estimated implementation effort in person-days
+ cost_usd: int, # Estimated implementation cost (tooling + time)
+ implementation_notes: str,
+ status: str = "Not Started", # Not Started | In Progress | Implemented | Verified
+ owner: Optional[str] = None,
+ target_date: Optional[str] = None,
+) -> dict:
+ """Build a control domain record."""
+ frameworks_applicable = []
+ if soc2_ref:
+ frameworks_applicable.append("soc2")
+ if iso27001_ref:
+ frameworks_applicable.append("iso27001")
+ if hipaa_ref:
+ frameworks_applicable.append("hipaa")
+ if gdpr_ref:
+ frameworks_applicable.append("gdpr")
+
+ return {
+ "domain_id": domain_id,
+ "name": name,
+ "description": description,
+ "references": {
+ "soc2": soc2_ref,
+ "iso27001": iso27001_ref,
+ "hipaa": hipaa_ref,
+ "gdpr": gdpr_ref,
+ },
+ "frameworks_applicable": frameworks_applicable,
+ "framework_count": len(frameworks_applicable),
+ "effort_days": effort_days,
+ "cost_usd": cost_usd,
+ "implementation_notes": implementation_notes,
+ "status": status,
+ "owner": owner,
+ "target_date": target_date,
+ }
+
+
+def load_control_library() -> list[dict]:
+ """
+ Core control domains mapped across SOC 2, ISO 27001, HIPAA, and GDPR.
+ Each domain represents a logical grouping of controls.
+ """
+ controls = []
+
+ controls.append(build_control_domain(
+ domain_id="IAM-001",
+ name="Identity and Access Management",
+ description=(
+ "Unique user identities, MFA enforcement, SSO, least privilege access, "
+ "role-based access control, access provisioning and de-provisioning workflows."
+ ),
+ soc2_ref="CC6.1, CC6.2, CC6.3",
+ iso27001_ref="A.5.15, A.5.16, A.5.17, A.5.18",
+ hipaa_ref="§164.312(a)(2)(i), §164.308(a)(3)",
+ gdpr_ref="Art. 32(1)(b)",
+ effort_days=15,
+ cost_usd=25_000, # SSO + MFA tooling
+ implementation_notes=(
+ "Deploy IdP (Okta/Azure AD/Google Workspace). Enforce MFA on all applications. "
+ "Document access provisioning process. Implement quarterly access reviews."
+ ),
+ status="In Progress",
+ owner="IT/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="ENC-001",
+ name="Encryption at Rest and in Transit",
+ description=(
+ "Encryption of sensitive data stored in databases, file systems, and backups. "
+ "TLS 1.2+ for all data in transit. Key management and rotation."
+ ),
+ soc2_ref="CC6.7",
+ iso27001_ref="A.8.24",
+ hipaa_ref="§164.312(a)(2)(iv), §164.312(e)(2)(ii)",
+ gdpr_ref="Art. 32(1)(a)",
+ effort_days=10,
+ cost_usd=8_000,
+ implementation_notes=(
+ "Enable encryption at rest on all databases (RDS, S3, etc.). "
+ "Configure TLS on all services. Use KMS for key management. "
+ "Document encryption standards in a security policy."
+ ),
+ status="Implemented",
+ owner="Engineering",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="LOG-001",
+ name="Audit Logging and Monitoring",
+ description=(
+ "Comprehensive logging of user activity, system events, and security events. "
+ "Log integrity protection. SIEM or log aggregation. Alerting on anomalies."
+ ),
+ soc2_ref="CC7.2, CC7.3",
+ iso27001_ref="A.8.15, A.8.16, A.8.17",
+ hipaa_ref="§164.312(b)",
+ gdpr_ref="Art. 32(1)(b)",
+ effort_days=20,
+ cost_usd=30_000, # SIEM tooling
+ implementation_notes=(
+ "Centralize logs from application, infrastructure, and cloud provider. "
+ "Define log retention (minimum 1 year). Set up alerting for authentication "
+ "failures, privilege escalation, data export events."
+ ),
+ status="Not Started",
+ owner="DevOps/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="IR-001",
+ name="Incident Response",
+ description=(
+ "Documented incident response plan. Defined severity levels. Escalation procedures. "
+ "Communication templates. Annual tabletop exercise. Post-incident review process."
+ ),
+ soc2_ref="CC7.3, CC7.4, CC7.5",
+ iso27001_ref="A.5.24, A.5.25, A.5.26, A.5.27, A.5.28",
+ hipaa_ref="§164.308(a)(6)",
+ gdpr_ref="Art. 33, Art. 34",
+ effort_days=12,
+ cost_usd=10_000,
+ implementation_notes=(
+ "Write IR plan covering detection, containment, eradication, recovery, communication. "
+ "Define breach notification timelines (GDPR: 72 hours, HIPAA: 60 days). "
+ "Run annual tabletop exercise. Retain IR firm on retainer."
+ ),
+ status="In Progress",
+ owner="CISO",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="VM-001",
+ name="Vulnerability Management and Patching",
+ description=(
+ "Regular vulnerability scanning of infrastructure and applications. "
+ "Defined patch SLAs by severity. Penetration testing program. "
+ "Dependency vulnerability scanning in CI/CD."
+ ),
+ soc2_ref="CC7.1",
+ iso27001_ref="A.8.8",
+ hipaa_ref="§164.308(a)(1)(ii)(A)",
+ gdpr_ref="Art. 32(1)(d)",
+ effort_days=15,
+ cost_usd=20_000,
+ implementation_notes=(
+ "Deploy infrastructure scanner (Tenable, Qualys, AWS Inspector). "
+ "Add SAST/DAST to CI/CD pipeline. Define patch SLAs: Critical <24h, High <7d, "
+ "Medium <30d. Conduct annual pentest."
+ ),
+ status="In Progress",
+ owner="DevOps/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="VRISK-001",
+ name="Vendor and Third-Party Risk Management",
+ description=(
+ "Inventory of all third-party vendors with data access. Tiered risk assessment "
+ "process. Contractual security requirements. Annual reviews for critical vendors."
+ ),
+ soc2_ref="CC9.2",
+ iso27001_ref="A.5.19, A.5.20, A.5.21, A.5.22",
+ hipaa_ref="§164.308(b) Business Associate Agreements",
+ gdpr_ref="Art. 28 Data Processing Agreements",
+ effort_days=10,
+ cost_usd=8_000,
+ implementation_notes=(
+ "Build vendor inventory spreadsheet. Tier vendors (Tier 1: PII access, "
+ "Tier 2: business data, Tier 3: no data). Execute DPAs for all processors (GDPR). "
+ "Execute BAAs for PHI processors (HIPAA). Annual security questionnaire for Tier 1."
+ ),
+ status="Not Started",
+ owner="Legal/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="RISK-001",
+ name="Risk Assessment and Treatment",
+ description=(
+ "Formal risk assessment methodology. Risk register maintained. "
+ "Risk treatment decisions documented. Annual risk review cycle."
+ ),
+ soc2_ref="CC3.1, CC3.2, CC3.3, CC3.4",
+ iso27001_ref="Clause 6.1.2, 6.1.3",
+ hipaa_ref="§164.308(a)(1) Security Risk Analysis",
+ gdpr_ref="Art. 32, Art. 35 DPIA",
+ effort_days=15,
+ cost_usd=12_000,
+ implementation_notes=(
+ "Document risk methodology (FAIR, NIST, ISO 27005). Maintain risk register. "
+ "HIPAA: formal security risk analysis required — not optional. "
+ "GDPR: DPIA required for high-risk processing activities. Annual refresh."
+ ),
+ status="Not Started",
+ owner="CISO",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="TRAIN-001",
+ name="Security Awareness Training",
+ description=(
+ "Annual security awareness training for all employees. "
+ "Role-specific training for high-risk roles. Phishing simulations. "
+ "Training completion tracking."
+ ),
+ soc2_ref="CC1.4",
+ iso27001_ref="A.6.3, A.6.8",
+ hipaa_ref="§164.308(a)(5)",
+ gdpr_ref="Art. 39(1)(b)",
+ effort_days=5,
+ cost_usd=8_000,
+ implementation_notes=(
+ "Deploy security training platform (KnowBe4, Proofpoint, etc.). "
+ "Annual training required — track completion (100% target). "
+ "Quarterly phishing simulations. Role-specific training for devs (secure coding), "
+ "finance (BEC), support (social engineering)."
+ ),
+ status="Not Started",
+ owner="HR/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="CHGMGMT-001",
+ name="Change Management",
+ description=(
+ "Formal change management process for production changes. "
+ "Code review requirements. Deployment approvals. Rollback procedures. "
+ "Change log maintained."
+ ),
+ soc2_ref="CC8.1",
+ iso27001_ref="A.8.32",
+ hipaa_ref="§164.312(c)(1) Integrity controls",
+ gdpr_ref="Art. 25 Privacy by design",
+ effort_days=10,
+ cost_usd=5_000,
+ implementation_notes=(
+ "Document change management policy. Require peer review for all production changes. "
+ "Maintain audit trail in version control. No direct production access — "
+ "all changes via CI/CD pipeline."
+ ),
+ status="In Progress",
+ owner="Engineering",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="BCP-001",
+ name="Business Continuity and Disaster Recovery",
+ description=(
+ "Business continuity plan. Disaster recovery plan with defined RTO/RPO. "
+ "Backup procedures with tested restores. Failover capabilities."
+ ),
+ soc2_ref="A1.1, A1.2, A1.3",
+ iso27001_ref="A.5.29, A.5.30",
+ hipaa_ref="§164.308(a)(7) Contingency Plan",
+ gdpr_ref="Art. 32(1)(c)",
+ effort_days=12,
+ cost_usd=15_000,
+ implementation_notes=(
+ "Define RTO (<4 hours) and RPO (<1 hour) targets. Configure automated backups. "
+ "Test restore quarterly — paper backups that aren't tested aren't backups. "
+ "Document DR runbook. Annual DR exercise."
+ ),
+ status="In Progress",
+ owner="DevOps",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="ASSET-001",
+ name="Asset Inventory and Classification",
+ description=(
+ "Complete inventory of hardware, software, and data assets. "
+ "Data classification scheme. Ownership assigned to all assets. "
+ "Regular reconciliation."
+ ),
+ soc2_ref="CC6.1",
+ iso27001_ref="A.5.9, A.5.10, A.5.11, A.5.12, A.5.13",
+ hipaa_ref="§164.310(d) Device and Media Controls",
+ gdpr_ref="Art. 30 Records of Processing Activities",
+ effort_days=8,
+ cost_usd=5_000,
+ implementation_notes=(
+ "Build asset register (CMDB or spreadsheet at minimum). "
+ "Classify data: Public, Internal, Confidential, Restricted. "
+ "GDPR requires RoPA (Record of Processing Activities) — data map of all PII. "
+ "ISO 27001 requires SoA referencing asset inventory."
+ ),
+ status="Not Started",
+ owner="IT/Security",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="ENDPOINT-001",
+ name="Endpoint Security",
+ description=(
+ "EDR/antivirus on all managed endpoints. Device management (MDM). "
+ "Full disk encryption. Patch management. BYOD policy."
+ ),
+ soc2_ref="CC6.8",
+ iso27001_ref="A.8.1, A.8.7",
+ hipaa_ref="§164.310(a)(2)(iv) Workstation security",
+ gdpr_ref="Art. 32(1)(a)",
+ effort_days=8,
+ cost_usd=20_000,
+ implementation_notes=(
+ "Deploy EDR (CrowdStrike, SentinelOne, or Microsoft Defender for Business). "
+ "Enable full disk encryption (FileVault/BitLocker). "
+ "MDM for device management. BYOD policy documented."
+ ),
+ status="In Progress",
+ owner="IT",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="POLICY-001",
+ name="Security Policies and Procedures",
+ description=(
+ "Documented security policies covering acceptable use, access control, "
+ "incident response, data classification, vendor management, etc. "
+ "Annual review cycle. Employee attestation."
+ ),
+ soc2_ref="CC1.2, CC1.3",
+ iso27001_ref="A.5.1, A.5.2",
+ hipaa_ref="§164.308(a)(1) Security Management Process",
+ gdpr_ref="Art. 24 Responsibility of the controller",
+ effort_days=15,
+ cost_usd=10_000,
+ implementation_notes=(
+ "Minimum policy set: Information Security Policy, Acceptable Use, "
+ "Access Control, Incident Response, Data Classification, Password, "
+ "Change Management, Vendor Management, Business Continuity. "
+ "Use policy templates from GRC platform (Vanta/Drata)."
+ ),
+ status="In Progress",
+ owner="CISO",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="PRIV-001",
+ name="Privacy and Data Subject Rights",
+ description=(
+ "Privacy policy and notices. Data subject rights fulfilment process "
+ "(access, erasure, portability). Consent management. Cookie compliance. "
+ "Privacy by design in product development."
+ ),
+ soc2_ref=None, # Not a SOC 2 requirement (unless Privacy TSC selected)
+ iso27001_ref="A.5.34",
+ hipaa_ref="§164.524 Access, §164.528 Accounting of Disclosures",
+ gdpr_ref="Art. 13, 14, 15–22 (Rights), Art. 25",
+ effort_days=20,
+ cost_usd=15_000,
+ implementation_notes=(
+ "GDPR: Update privacy policy, implement DSAR process (30-day SLA), "
+ "build deletion capability into product. Cookie consent (PECR/ePrivacy). "
+ "HIPAA: Patient rights for PHI access. "
+ "Consider OneTrust, Termly, or CookieYes for consent management."
+ ),
+ status="Not Started",
+ owner="Legal/Product",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="NET-001",
+ name="Network Security and Segmentation",
+ description=(
+ "Network segmentation (production vs. development vs. corporate). "
+ "Firewall rules. Intrusion detection. VPN or ZTNA for remote access."
+ ),
+ soc2_ref="CC6.6, CC6.7",
+ iso27001_ref="A.8.20, A.8.21, A.8.22",
+ hipaa_ref="§164.312(e)(1) Transmission security",
+ gdpr_ref="Art. 32(1)(a)",
+ effort_days=12,
+ cost_usd=18_000,
+ implementation_notes=(
+ "Segment production from development. WAF in front of public applications. "
+ "Replace VPN with ZTNA for remote access (Series B+ consideration). "
+ "DDoS protection (Cloudflare or AWS Shield)."
+ ),
+ status="In Progress",
+ owner="DevOps",
+ ))
+
+ controls.append(build_control_domain(
+ domain_id="PENTEST-001",
+ name="Penetration Testing",
+ description=(
+ "Annual external penetration test by qualified third-party firm. "
+ "Finding remediation tracking. Results reviewed by leadership."
+ ),
+ soc2_ref="CC7.1",
+ iso27001_ref="A.8.8",
+ hipaa_ref="§164.308(a)(8) Evaluation",
+ gdpr_ref="Art. 32(1)(d)",
+ effort_days=5,
+ cost_usd=25_000,
+ implementation_notes=(
+ "Scope: external attack surface, application, API, and optionally social engineering. "
+ "Budget $15–35K for a reputable firm. Track findings in risk register. "
+ "Re-test critical findings within 90 days. Share pentest summary with enterprise "
+ "customers on request (under NDA)."
+ ),
+ status="Not Started",
+ owner="CISO",
+ ))
+
+ return controls
+
+
+# ─── Analysis ────────────────────────────────────────────────────────────────
+
+def calculate_framework_coverage(controls: list[dict]) -> dict:
+ """Calculate per-framework coverage statistics."""
+ coverage = {}
+ for fw in FRAMEWORKS:
+ applicable = [c for c in controls if fw in c["frameworks_applicable"]]
+ implemented = [c for c in applicable if c["status"] in ("Implemented", "Verified")]
+ in_progress = [c for c in applicable if c["status"] == "In Progress"]
+ not_started = [c for c in applicable if c["status"] == "Not Started"]
+
+ total_effort = sum(c["effort_days"] for c in applicable)
+ remaining_effort = sum(
+ c["effort_days"] for c in applicable
+ if c["status"] not in ("Implemented", "Verified")
+ )
+ total_cost = sum(c["cost_usd"] for c in applicable)
+ remaining_cost = sum(
+ c["cost_usd"] for c in applicable
+ if c["status"] not in ("Implemented", "Verified")
+ )
+
+ pct_complete = (len(implemented) / len(applicable) * 100) if applicable else 0
+
+ coverage[fw] = {
+ "framework": FRAMEWORKS[fw]["name"],
+ "total_controls": len(applicable),
+ "implemented": len(implemented),
+ "in_progress": len(in_progress),
+ "not_started": len(not_started),
+ "pct_complete": pct_complete,
+ "total_effort_days": total_effort,
+ "remaining_effort_days": remaining_effort,
+ "total_cost_usd": total_cost,
+ "remaining_cost_usd": remaining_cost,
+ "gap_controls": [c["name"] for c in not_started],
+ }
+
+ return coverage
+
+
+def find_high_leverage_controls(controls: list[dict]) -> list[dict]:
+ """Controls that satisfy the most frameworks — highest ROI to implement."""
+ multi_fw = [c for c in controls if c["framework_count"] >= 3
+ and c["status"] not in ("Implemented", "Verified")]
+ return sorted(multi_fw, key=lambda c: (-c["framework_count"], c["effort_days"]))
+
+
+def estimate_roadmap(controls: list[dict], target_frameworks: list[str]) -> list[dict]:
+ """
+ Generate an ordered implementation roadmap for target frameworks.
+ Prioritize: (1) controls blocking most frameworks, (2) quick wins (low effort).
+ """
+ applicable = [c for c in controls
+ if any(fw in c["frameworks_applicable"] for fw in target_frameworks)
+ and c["status"] not in ("Implemented", "Verified")]
+
+ # Score: (frameworks_covered × 10) - (effort_days) → higher is better
+ for c in applicable:
+ fw_overlap = len([fw for fw in target_frameworks if fw in c["frameworks_applicable"]])
+ c["_priority_score"] = (fw_overlap * 10) - c["effort_days"]
+
+ return sorted(applicable, key=lambda c: -c["_priority_score"])
+
+
+def fmt_dollars(amount: float) -> str:
+ if amount >= 1_000_000:
+ return f"${amount/1_000_000:.1f}M"
+ if amount >= 1_000:
+ return f"${amount/1_000:.0f}K"
+ return f"${amount:.0f}"
+
+
+def status_icon(status: str) -> str:
+ icons = {
+ "Implemented": "✅",
+ "Verified": "✅",
+ "In Progress": "🔄",
+ "Not Started": "⬜",
+ "Planned": "📋",
+ }
+ return icons.get(status, "❓")
+
+
+# ─── Display ─────────────────────────────────────────────────────────────────
+
+def print_header():
+ print("\n" + "=" * 80)
+ print(" CISO COMPLIANCE TRACKER — Multi-Framework Coverage")
+ print(f" Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}")
+ print("=" * 80)
+
+
+def print_framework_summary(coverage: dict):
+ print("\n📋 FRAMEWORK COVERAGE SUMMARY")
+ print("-" * 80)
+ header = f"{'Framework':<20} {'Done':<6} {'WIP':<5} {'Gap':<5} {'Complete':<10} {'Remain Cost':<14} {'Remain Days'}"
+ print(header)
+ print("-" * 80)
+ for fw_id, data in coverage.items():
+ pct = f"{data['pct_complete']:.0f}%"
+ print(
+ f"{data['framework']:<20} {data['implemented']:<6} {data['in_progress']:<5} "
+ f"{data['not_started']:<5} {pct:<10} {fmt_dollars(data['remaining_cost_usd']):<14} "
+ f"{data['remaining_effort_days']} days"
+ )
+
+
+def print_control_table(controls: list[dict], framework_filter: Optional[str] = None):
+ filtered = controls
+ if framework_filter:
+ filtered = [c for c in controls if framework_filter in c["frameworks_applicable"]]
+
+ title = f"CONTROL DOMAINS"
+ if framework_filter:
+ title += f" — {FRAMEWORKS[framework_filter]['name']}"
+
+ print(f"\n🔧 {title}")
+ print("-" * 90)
+ header = f"{'ID':<14} {'Control Name':<30} {'Frameworks':<8} {'Effort':<8} {'Cost':<10} {'Status'}"
+ print(header)
+ print("-" * 90)
+
+ for c in filtered:
+ fw_badges = "/".join(
+ fw.upper()[:3] for fw in ["soc2", "iso27001", "hipaa", "gdpr"]
+ if fw in c["frameworks_applicable"]
+ )
+ icon = status_icon(c["status"])
+ print(
+ f"{c['domain_id']:<14} {c['name'][:29]:<30} {fw_badges:<8} "
+ f"{c['effort_days']:>3}d {fmt_dollars(c['cost_usd']):<10} {icon} {c['status']}"
+ )
+
+
+def print_gap_analysis(coverage: dict):
+ print("\n⚠️ GAP ANALYSIS — Controls Not Yet Started")
+ print("-" * 70)
+ for fw_id, data in coverage.items():
+ if data["gap_controls"]:
+ print(f"\n {data['framework']} — {len(data['gap_controls'])} gaps:")
+ for gap in data["gap_controls"]:
+ print(f" • {gap}")
+
+
+def print_high_leverage(controls: list[dict]):
+ hl = find_high_leverage_controls(controls)
+ print(f"\n🎯 HIGH-LEVERAGE CONTROLS — Implement Once, Satisfy Multiple Frameworks")
+ print("-" * 70)
+ print(f"{'Control':<30} {'Frameworks':<35} {'Effort':<8} {'Cost'}")
+ print("-" * 70)
+ for c in hl:
+ fw_list = " + ".join(FRAMEWORKS[fw]["name"] for fw in c["frameworks_applicable"])
+ print(
+ f"{c['name'][:29]:<30} {fw_list[:34]:<35} "
+ f"{c['effort_days']:>3}d {fmt_dollars(c['cost_usd'])}"
+ )
+
+
+def print_roadmap(controls: list[dict], target_frameworks: list[str]):
+ ordered = estimate_roadmap(controls, target_frameworks)
+ fw_names = " + ".join(FRAMEWORKS[fw]["name"] for fw in target_frameworks)
+ print(f"\n🗺️ IMPLEMENTATION ROADMAP — {fw_names}")
+ print("-" * 80)
+ print("Priority order: most framework coverage first, then quick wins")
+ print()
+
+ cumulative_days = 0
+ cumulative_cost = 0
+ for i, c in enumerate(ordered, 1):
+ cumulative_days += c["effort_days"]
+ cumulative_cost += c["cost_usd"]
+ fw_badges = ", ".join(
+ FRAMEWORKS[fw]["name"] for fw in target_frameworks
+ if fw in c["frameworks_applicable"]
+ )
+ print(f" {i:>2}. {c['name']}")
+ print(f" Frameworks: {fw_badges}")
+ print(f" Effort: {c['effort_days']} days | Cost: {fmt_dollars(c['cost_usd'])} "
+ f"| Cumulative: {cumulative_days}d / {fmt_dollars(cumulative_cost)}")
+ if c.get("owner"):
+ print(f" Owner: {c['owner']}")
+ print()
+
+
+def print_framework_profiles():
+ print("\n💼 FRAMEWORK PROFILES")
+ print("-" * 70)
+ for fw_id, fw in FRAMEWORKS.items():
+ print(f"\n {fw['name']} ({fw_id.upper()})")
+ print(f" Timeline: ~{fw['typical_timeline_months']} months")
+ print(f" First-year cost: {fmt_dollars(fw['typical_cost_usd'])}")
+ print(f" Annual maintenance: {fmt_dollars(fw['annual_maintenance_usd'])}/yr")
+ print(f" Business value: {fw['business_value']}")
+ print(f" Required for: {', '.join(fw['mandatory_for'])}")
+
+
+def export_csv(controls: list[dict], filepath: str):
+ fields = [
+ "domain_id", "name", "frameworks_applicable", "framework_count",
+ "effort_days", "cost_usd", "status", "owner", "target_date",
+ "soc2_ref", "iso27001_ref", "hipaa_ref", "gdpr_ref", "implementation_notes"
+ ]
+ with open(filepath, "w", newline="") as f:
+ writer = csv.DictWriter(f, fieldnames=fields)
+ writer.writeheader()
+ for c in controls:
+ row = {k: c.get(k, "") for k in fields}
+ row["frameworks_applicable"] = ", ".join(c["frameworks_applicable"])
+ row["soc2_ref"] = c["references"].get("soc2", "")
+ row["iso27001_ref"] = c["references"].get("iso27001", "")
+ row["hipaa_ref"] = c["references"].get("hipaa", "")
+ row["gdpr_ref"] = c["references"].get("gdpr", "")
+ writer.writerow(row)
+ print(f"✅ Exported {len(controls)} controls to {filepath}")
+
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="CISO Compliance Tracker — Multi-framework coverage and roadmap"
+ )
+ parser.add_argument("--json", action="store_true", help="Output JSON")
+ parser.add_argument("--csv", metavar="FILE", help="Export CSV to file")
+ parser.add_argument(
+ "--framework", metavar="FRAMEWORK",
+ choices=list(FRAMEWORKS.keys()),
+ help="Filter to single framework (soc2, iso27001, hipaa, gdpr)"
+ )
+ parser.add_argument("--gap-analysis", action="store_true", help="Show gap analysis")
+ parser.add_argument("--roadmap", metavar="FRAMEWORKS",
+ help="Sequenced roadmap for frameworks e.g. 'soc2,iso27001'")
+ parser.add_argument("--profiles", action="store_true", help="Show framework profiles")
+ parser.add_argument("--leverage", action="store_true", help="Show high-leverage controls")
+ args = parser.parse_args()
+
+ controls = load_control_library()
+ coverage = calculate_framework_coverage(controls)
+
+ if args.json:
+ output = {
+ "generated": datetime.now().isoformat(),
+ "frameworks": FRAMEWORKS,
+ "coverage": coverage,
+ "controls": controls,
+ }
+ print(json.dumps(output, indent=2, default=str))
+ return
+
+ if args.csv:
+ export_csv(controls, args.csv)
+ return
+
+ print_header()
+
+ if args.profiles:
+ print_framework_profiles()
+ return
+
+ if args.roadmap:
+ target_fws = [fw.strip() for fw in args.roadmap.split(",") if fw.strip() in FRAMEWORKS]
+ if not target_fws:
+ print(f"Unknown frameworks. Valid: {', '.join(FRAMEWORKS.keys())}")
+ sys.exit(1)
+ print_framework_summary(coverage)
+ print_roadmap(controls, target_fws)
+ return
+
+ print_framework_summary(coverage)
+ print_control_table(controls, args.framework)
+
+ if args.gap_analysis:
+ print_gap_analysis(coverage)
+
+ if args.leverage:
+ print_high_leverage(controls)
+
+ if not any([args.framework, args.gap_analysis, args.leverage]):
+ print_high_leverage(controls)
+ print_gap_analysis(coverage)
+
+ print("\n💡 NEXT STEPS")
+ print(" --roadmap soc2,iso27001 Priority order for dual-framework")
+ print(" --framework hipaa HIPAA-only control view")
+ print(" --gap-analysis What's not started")
+ print(" --leverage Controls covering most frameworks")
+ print(" --profiles Framework timelines and costs")
+ print(" --csv controls.csv Export for stakeholder review")
+ print()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/ciso-advisor/scripts/risk_quantifier.py b/skills/ciso-advisor/scripts/risk_quantifier.py
new file mode 100644
index 00000000..f4223093
--- /dev/null
+++ b/skills/ciso-advisor/scripts/risk_quantifier.py
@@ -0,0 +1,690 @@
+#!/usr/bin/env python3
+"""
+CISO Risk Quantifier
+====================
+Quantifies security risks in business terms using the FAIR model.
+Calculates ALE (Annual Loss Expectancy) and prioritizes by expected annual loss.
+
+Usage:
+ python risk_quantifier.py # Run with sample data
+ python risk_quantifier.py --json # Output JSON
+ python risk_quantifier.py --csv output.csv # Export CSV
+ python risk_quantifier.py --budget 500000 # Show what fits in budget
+ python risk_quantifier.py --add # Interactive risk entry
+"""
+
+import json
+import csv
+import sys
+import os
+import argparse
+from datetime import datetime
+from typing import Optional
+
+
+# ─── Data Model ─────────────────────────────────────────────────────────────
+
+RISK_CATEGORIES = [
+ "Data Breach",
+ "Ransomware / Extortion",
+ "Insider Threat",
+ "Third-Party / Supply Chain",
+ "Application Vulnerability",
+ "Cloud Misconfiguration",
+ "Social Engineering",
+ "Physical Security",
+ "Business Email Compromise",
+ "DDoS / Availability",
+]
+
+BUSINESS_IMPACT_TYPES = [
+ "Revenue Loss",
+ "Regulatory Fine",
+ "Legal / Litigation",
+ "Reputational Damage",
+ "Recovery / Remediation Cost",
+ "Customer Churn",
+ "Business Interruption",
+]
+
+MITIGATION_STATUSES = ["None", "Planned", "In Progress", "Mitigated", "Accepted"]
+
+
+def build_risk(
+ name: str,
+ category: str,
+ description: str,
+ asset_value: float,
+ exposure_factor: float, # 0.0–1.0: fraction of asset value lost in breach
+ annual_rate: float, # ARO: expected incidents per year (0.01 = once per 100 years)
+ mitigation_cost: float,
+ mitigation_effectiveness: float, # 0.0–1.0: fraction of risk reduced by control
+ mitigation_status: str,
+ business_impacts: dict, # {impact_type: dollar_amount}
+ notes: str = "",
+) -> dict:
+ """Construct a risk record with calculated metrics."""
+ sle = asset_value * exposure_factor # Single Loss Expectancy
+ ale = sle * annual_rate # Annual Loss Expectancy (inherent)
+ mitigated_ale = ale * (1 - mitigation_effectiveness) # Residual after mitigation
+ mitigation_roi = ((ale - mitigated_ale - mitigation_cost) / mitigation_cost * 100
+ if mitigation_cost > 0 else 0)
+ total_business_impact = sum(business_impacts.values())
+
+ return {
+ "name": name,
+ "category": category,
+ "description": description,
+ "asset_value": asset_value,
+ "exposure_factor": exposure_factor,
+ "annual_rate": annual_rate,
+ "mitigation_cost": mitigation_cost,
+ "mitigation_effectiveness": mitigation_effectiveness,
+ "mitigation_status": mitigation_status,
+ "business_impacts": business_impacts,
+ "notes": notes,
+ # Calculated
+ "sle": sle,
+ "ale": ale,
+ "mitigated_ale": mitigated_ale,
+ "mitigation_roi_pct": mitigation_roi,
+ "total_business_impact": total_business_impact,
+ "priority_score": ale, # Primary sort key
+ }
+
+
+# ─── Sample Data ─────────────────────────────────────────────────────────────
+
+def load_sample_risks() -> list[dict]:
+ """
+ Sample risk register for a Series B SaaS company with ~$15M ARR,
+ ~50K customer records, B2B enterprise focus.
+ """
+ risks = []
+
+ risks.append(build_risk(
+ name="Customer Database Breach",
+ category="Data Breach",
+ description=(
+ "Unauthorized access to production database containing 50K+ customer records "
+ "including PII (name, email, company, payment method). Attack vector: SQL injection, "
+ "compromised credentials, or insider access."
+ ),
+ asset_value=5_000_000, # Value of customer database (revenue impact + regulatory)
+ exposure_factor=0.30, # ~30% of asset value lost in a breach event
+ annual_rate=0.12, # ~12% chance per year (based on Verizon DBIR industry data)
+ mitigation_cost=45_000, # WAF + DAST + DB activity monitoring annual cost
+ mitigation_effectiveness=0.80,
+ mitigation_status="In Progress",
+ business_impacts={
+ "Regulatory Fine": 85_000, # GDPR/CCPA exposure
+ "Legal / Litigation": 150_000, # Class action exposure
+ "Customer Churn": 300_000, # Lost ARR from breach-triggered churn
+ "Reputational Damage": 200_000, # Brand impact / deal loss
+ "Recovery / Remediation Cost": 65_000,
+ },
+ notes="SOC 2 Type II controls partially address. Next step: DB activity monitoring.",
+ ))
+
+ risks.append(build_risk(
+ name="Ransomware Attack",
+ category="Ransomware / Extortion",
+ description=(
+ "Ransomware encrypts production systems. Average ransom demand for a "
+ "Series B company is $350K–$800K. Recovery without ransom payment: 2–6 weeks downtime. "
+ "Attack vector: phishing email with malicious attachment, RDP exposure."
+ ),
+ asset_value=3_500_000,
+ exposure_factor=0.25,
+ annual_rate=0.15,
+ mitigation_cost=60_000, # EDR + email security + backup hardening
+ mitigation_effectiveness=0.85,
+ mitigation_status="Planned",
+ business_impacts={
+ "Business Interruption": 450_000, # 4 weeks downtime × $112K/week revenue
+ "Recovery / Remediation Cost": 180_000,
+ "Customer Churn": 125_000,
+ "Revenue Loss": 75_000,
+ },
+ notes="Offline, tested backups reduce recovery time and eliminate ransom pressure.",
+ ))
+
+ risks.append(build_risk(
+ name="Privileged Insider Data Theft",
+ category="Insider Threat",
+ description=(
+ "Disgruntled or financially motivated employee with elevated access exfiltrates "
+ "customer data, IP, or trade secrets. Detection is typically slow (median: 197 days "
+ "per IBM Cost of Data Breach Report)."
+ ),
+ asset_value=2_800_000,
+ exposure_factor=0.20,
+ annual_rate=0.08,
+ mitigation_cost=35_000, # DLP + UEBA + PAM
+ mitigation_effectiveness=0.65,
+ mitigation_status="None",
+ business_impacts={
+ "Legal / Litigation": 120_000,
+ "Customer Churn": 90_000,
+ "Reputational Damage": 75_000,
+ "Recovery / Remediation Cost": 40_000,
+ },
+ notes="No DLP or UEBA currently deployed. Highest detection gap.",
+ ))
+
+ risks.append(build_risk(
+ name="Critical SaaS Vendor Breach (Supply Chain)",
+ category="Third-Party / Supply Chain",
+ description=(
+ "A critical SaaS vendor (e.g., Salesforce, Slack, AWS, GitHub) suffers a breach "
+ "that compromises data entrusted to them or disrupts your operations. You have "
+ "limited control but full liability to customers."
+ ),
+ asset_value=2_200_000,
+ exposure_factor=0.15,
+ annual_rate=0.18,
+ mitigation_cost=20_000, # Vendor risk assessment program
+ mitigation_effectiveness=0.40, # Limited — you can't control vendor security
+ mitigation_status="Planned",
+ business_impacts={
+ "Business Interruption": 95_000,
+ "Customer Churn": 75_000,
+ "Reputational Damage": 50_000,
+ "Recovery / Remediation Cost": 30_000,
+ },
+ notes="Third-party risk is partially transferable via contractual SLAs and cyber insurance.",
+ ))
+
+ risks.append(build_risk(
+ name="Business Email Compromise (BEC)",
+ category="Business Email Compromise",
+ description=(
+ "Attacker impersonates CEO, CFO, or vendor to redirect wire transfers, gift card "
+ "purchases, or payroll. Median BEC loss: $125K. FBI IC3 reports BEC as #1 "
+ "cybercrime by financial loss."
+ ),
+ asset_value=500_000,
+ exposure_factor=0.40,
+ annual_rate=0.30,
+ mitigation_cost=12_000, # Email authentication (DMARC) + training + callback procedures
+ mitigation_effectiveness=0.90,
+ mitigation_status="In Progress",
+ business_impacts={
+ "Revenue Loss": 125_000, # Direct financial theft (often unrecoverable)
+ "Recovery / Remediation Cost": 25_000,
+ "Legal / Litigation": 15_000,
+ },
+ notes="DMARC deployed. Need to enforce wire transfer callback procedures.",
+ ))
+
+ risks.append(build_risk(
+ name="Cloud Misconfiguration — S3 / Storage Exposure",
+ category="Cloud Misconfiguration",
+ description=(
+ "Public exposure of S3 buckets, GCS buckets, or Azure Blob storage containing "
+ "sensitive data. One of the most common causes of data breaches. Often undetected "
+ "for months. 2023 IBM study: 82% of breaches involved data stored in cloud."
+ ),
+ asset_value=1_800_000,
+ exposure_factor=0.20,
+ annual_rate=0.20,
+ mitigation_cost=18_000, # CSPM tool + IaC scanning
+ mitigation_effectiveness=0.90,
+ mitigation_status="Planned",
+ business_impacts={
+ "Regulatory Fine": 60_000,
+ "Reputational Damage": 120_000,
+ "Legal / Litigation": 45_000,
+ "Recovery / Remediation Cost": 35_000,
+ },
+ notes="No CSPM currently. High frequency, high detectability, low mitigation cost.",
+ ))
+
+ risks.append(build_risk(
+ name="Credential Stuffing — Customer Accounts",
+ category="Application Vulnerability",
+ description=(
+ "Attackers use leaked credential lists to compromise customer accounts. "
+ "Account takeover leads to data theft, fraudulent transactions, and support burden. "
+ "16 billion credentials available on darknet as of 2024."
+ ),
+ asset_value=1_200_000,
+ exposure_factor=0.12,
+ annual_rate=0.40,
+ mitigation_cost=15_000, # MFA + rate limiting + bot detection
+ mitigation_effectiveness=0.95,
+ mitigation_status="In Progress",
+ business_impacts={
+ "Customer Churn": 80_000,
+ "Revenue Loss": 45_000,
+ "Recovery / Remediation Cost": 19_000,
+ "Reputational Damage": 30_000,
+ },
+ notes="MFA available but optional. Enforcing MFA cuts this risk by ~99%.",
+ ))
+
+ risks.append(build_risk(
+ name="Phishing — Employee Credential Compromise",
+ category="Social Engineering",
+ description=(
+ "Employee clicks phishing link, surrenders credentials. Without MFA, "
+ "this provides full access to email, SaaS apps, and potentially production. "
+ "Phishing is the #1 attack vector in the Verizon DBIR."
+ ),
+ asset_value=1_500_000,
+ exposure_factor=0.15,
+ annual_rate=0.35,
+ mitigation_cost=25_000, # MFA + security awareness training + email security
+ mitigation_effectiveness=0.92,
+ mitigation_status="In Progress",
+ business_impacts={
+ "Business Interruption": 65_000,
+ "Customer Churn": 55_000,
+ "Recovery / Remediation Cost": 45_000,
+ "Reputational Damage": 60_000,
+ },
+ notes="Primary vector for ransomware and BEC. MFA is the single highest-ROI control.",
+ ))
+
+ risks.append(build_risk(
+ name="Application API Vulnerability",
+ category="Application Vulnerability",
+ description=(
+ "Unauthenticated or improperly authorized API endpoint exposes customer data "
+ "or administrative functions. OWASP API Security Top 10 — broken object-level "
+ "authorization is the most common API vulnerability."
+ ),
+ asset_value=2_000_000,
+ exposure_factor=0.18,
+ annual_rate=0.15,
+ mitigation_cost=30_000, # DAST + API gateway + code review
+ mitigation_effectiveness=0.75,
+ mitigation_status="Planned",
+ business_impacts={
+ "Regulatory Fine": 70_000,
+ "Customer Churn": 90_000,
+ "Reputational Damage": 100_000,
+ "Legal / Litigation": 60_000,
+ },
+ notes="Need automated API security testing in CI/CD pipeline.",
+ ))
+
+ risks.append(build_risk(
+ name="DDoS Attack — Production Service",
+ category="DDoS / Availability",
+ description=(
+ "Distributed denial-of-service attack renders production service unavailable. "
+ "Average DDoS duration: 4–8 hours. Enterprise SLA breach triggers contractual "
+ "penalties. Increasingly used as extortion or distraction tactic."
+ ),
+ asset_value=1_000_000,
+ exposure_factor=0.10,
+ annual_rate=0.25,
+ mitigation_cost=15_000, # CDN with DDoS protection (Cloudflare, AWS Shield)
+ mitigation_effectiveness=0.85,
+ mitigation_status="Mitigated",
+ business_impacts={
+ "Business Interruption": 45_000,
+ "Customer Churn": 30_000,
+ "Revenue Loss": 25_000,
+ },
+ notes="Cloudflare deployed. Residual risk from very large volumetric attacks.",
+ ))
+
+ return risks
+
+
+# ─── Analysis & Reporting ────────────────────────────────────────────────────
+
+def calculate_portfolio_summary(risks: list[dict]) -> dict:
+ """Aggregate portfolio-level metrics."""
+ total_inherent_ale = sum(r["ale"] for r in risks)
+ total_mitigated_ale = sum(r["mitigated_ale"] for r in risks)
+ total_mitigation_cost = sum(r["mitigation_cost"] for r in risks)
+ risk_reduction = total_inherent_ale - total_mitigated_ale
+ portfolio_roi = ((risk_reduction - total_mitigation_cost) / total_mitigation_cost * 100
+ if total_mitigation_cost > 0 else 0)
+
+ by_category = {}
+ for r in risks:
+ cat = r["category"]
+ if cat not in by_category:
+ by_category[cat] = {"count": 0, "total_ale": 0.0}
+ by_category[cat]["count"] += 1
+ by_category[cat]["total_ale"] += r["ale"]
+
+ by_status = {}
+ for r in risks:
+ status = r["mitigation_status"]
+ by_status[status] = by_status.get(status, 0) + 1
+
+ return {
+ "total_risks": len(risks),
+ "total_inherent_ale": total_inherent_ale,
+ "total_mitigated_ale": total_mitigated_ale,
+ "total_risk_reduction": risk_reduction,
+ "total_mitigation_cost": total_mitigation_cost,
+ "portfolio_roi_pct": portfolio_roi,
+ "by_category": dict(sorted(by_category.items(), key=lambda x: -x[1]["total_ale"])),
+ "by_mitigation_status": by_status,
+ }
+
+
+def prioritize_risks(risks: list[dict], budget: Optional[float] = None) -> list[dict]:
+ """Return risks sorted by ALE. If budget given, show what fits."""
+ sorted_risks = sorted(risks, key=lambda r: -r["ale"])
+ if budget is None:
+ return sorted_risks
+
+ # Greedy budget allocation by ROI
+ actionable = [r for r in sorted_risks if r["mitigation_status"] in ("None", "Planned")
+ and r["mitigation_cost"] > 0]
+ actionable.sort(key=lambda r: -r["mitigation_roi_pct"])
+
+ allocated = []
+ remaining = budget
+ for risk in actionable:
+ if risk["mitigation_cost"] <= remaining:
+ allocated.append(risk)
+ remaining -= risk["mitigation_cost"]
+
+ return allocated
+
+
+def fmt_dollars(amount: float) -> str:
+ """Format a dollar amount."""
+ if amount >= 1_000_000:
+ return f"${amount/1_000_000:.2f}M"
+ if amount >= 1_000:
+ return f"${amount/1_000:.0f}K"
+ return f"${amount:.0f}"
+
+
+def fmt_pct(value: float) -> str:
+ return f"{value:.1f}%"
+
+
+def severity_label(ale: float) -> str:
+ if ale >= 200_000:
+ return "CRITICAL"
+ if ale >= 75_000:
+ return "HIGH"
+ if ale >= 25_000:
+ return "MEDIUM"
+ return "LOW"
+
+
+def severity_color(label: str) -> str:
+ """ANSI color codes."""
+ colors = {
+ "CRITICAL": "\033[91m", # Red
+ "HIGH": "\033[93m", # Yellow
+ "MEDIUM": "\033[94m", # Blue
+ "LOW": "\033[92m", # Green
+ }
+ return colors.get(label, "") + label + "\033[0m"
+
+
+# ─── Display ─────────────────────────────────────────────────────────────────
+
+def print_header():
+ print("\n" + "=" * 80)
+ print(" CISO RISK QUANTIFIER — Security Risk Portfolio")
+ print(f" Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}")
+ print("=" * 80)
+
+
+def print_portfolio_summary(summary: dict):
+ print("\n📊 PORTFOLIO SUMMARY")
+ print("-" * 60)
+ print(f" Total risks tracked: {summary['total_risks']}")
+ print(f" Total inherent ALE: {fmt_dollars(summary['total_inherent_ale'])}/yr")
+ print(f" Total ALE after mitigations: {fmt_dollars(summary['total_mitigated_ale'])}/yr")
+ print(f" Risk reduction from controls: {fmt_dollars(summary['total_risk_reduction'])}/yr")
+ print(f" Total mitigation spend: {fmt_dollars(summary['total_mitigation_cost'])}/yr")
+ print(f" Portfolio ROI: {fmt_pct(summary['portfolio_roi_pct'])}")
+ print()
+
+ print(" Risk by Category (sorted by ALE):")
+ for cat, data in summary["by_category"].items():
+ print(f" {cat:<35} {data['count']} risks ALE: {fmt_dollars(data['total_ale'])}/yr")
+
+ print()
+ print(" Mitigation Status:")
+ for status, count in summary["by_mitigation_status"].items():
+ print(f" {status:<20} {count} risks")
+
+
+def print_risk_table(risks: list[dict], title: str = "RISK REGISTER"):
+ print(f"\n🎯 {title}")
+ print("-" * 80)
+ header = f"{'#':<3} {'Risk Name':<35} {'Severity':<10} {'ALE/yr':<12} {'Mitig Cost':<12} {'ROI':<8} {'Status':<12}"
+ print(header)
+ print("-" * 80)
+
+ for i, risk in enumerate(risks, 1):
+ sev = severity_label(risk["ale"])
+ sev_str = sev.ljust(10)
+ roi = fmt_pct(risk["mitigation_roi_pct"]) if risk["mitigation_cost"] > 0 else "N/A"
+ print(
+ f"{i:<3} {risk['name'][:34]:<35} {sev_str} "
+ f"{fmt_dollars(risk['ale']):<12} {fmt_dollars(risk['mitigation_cost']):<12} "
+ f"{roi:<8} {risk['mitigation_status']}"
+ )
+
+
+def print_risk_detail(risk: dict, index: int):
+ sev = severity_label(risk["ale"])
+ print(f"\n{'─' * 70}")
+ print(f" #{index} — {risk['name']} [{sev}]")
+ print(f"{'─' * 70}")
+ print(f" Category: {risk['category']}")
+ print(f" Description: {risk['description'][:120]}...")
+ print()
+ print(f" RISK CALCULATION:")
+ print(f" Asset Value: {fmt_dollars(risk['asset_value'])}")
+ print(f" Exposure Factor: {fmt_pct(risk['exposure_factor'] * 100)}")
+ print(f" Single Loss Expectancy: {fmt_dollars(risk['sle'])}")
+ print(f" Annual Rate (ARO): {risk['annual_rate']:.2f}x/year")
+ print(f" Annual Loss Expectancy: {fmt_dollars(risk['ale'])}/yr ← INHERENT RISK")
+ print()
+ print(f" MITIGATION:")
+ print(f" Mitigation Cost: {fmt_dollars(risk['mitigation_cost'])}/yr")
+ print(f" Effectiveness: {fmt_pct(risk['mitigation_effectiveness'] * 100)}")
+ print(f" Residual ALE: {fmt_dollars(risk['mitigated_ale'])}/yr")
+ print(f" Mitigation ROI: {fmt_pct(risk['mitigation_roi_pct'])}")
+ print(f" Status: {risk['mitigation_status']}")
+ print()
+ print(f" BUSINESS IMPACT BREAKDOWN:")
+ for impact_type, amount in risk["business_impacts"].items():
+ print(f" {impact_type:<30} {fmt_dollars(amount)}")
+ print(f" {'TOTAL':<30} {fmt_dollars(risk['total_business_impact'])}")
+ if risk["notes"]:
+ print(f"\n NOTES: {risk['notes']}")
+
+
+def print_board_summary(risks: list[dict], summary: dict):
+ """One-page board-ready summary."""
+ print("\n" + "═" * 80)
+ print(" BOARD SECURITY REPORT — Risk Summary")
+ print("═" * 80)
+
+ critical = [r for r in risks if severity_label(r["ale"]) == "CRITICAL"]
+ high = [r for r in risks if severity_label(r["ale"]) == "HIGH"]
+ medium = [r for r in risks if severity_label(r["ale"]) == "MEDIUM"]
+ low = [r for r in risks if severity_label(r["ale"]) == "LOW"]
+
+ print(f"\n RISK EXPOSURE SUMMARY")
+ print(f" ┌─────────────┬────────┬──────────────┐")
+ print(f" │ Severity │ Count │ Total ALE/yr │")
+ print(f" ├─────────────┼────────┼──────────────┤")
+ for label, group in [("Critical", critical), ("High", high), ("Medium", medium), ("Low", low)]:
+ ale = sum(r["ale"] for r in group)
+ print(f" │ {label:<11} │ {len(group):<6} │ {fmt_dollars(ale):<12} │")
+ print(f" └─────────────┴────────┴──────────────┘")
+
+ print(f"\n TOTAL INHERENT RISK: {fmt_dollars(summary['total_inherent_ale'])}/yr")
+ print(f" SECURITY INVESTMENT: {fmt_dollars(summary['total_mitigation_cost'])}/yr")
+ print(f" RESIDUAL RISK: {fmt_dollars(summary['total_mitigated_ale'])}/yr")
+ print(f" RISK REDUCTION: {fmt_dollars(summary['total_risk_reduction'])}/yr")
+ print(f" PORTFOLIO ROI: {fmt_pct(summary['portfolio_roi_pct'])}")
+
+ print(f"\n TOP 3 RISKS BY EXPECTED ANNUAL LOSS:")
+ top3 = sorted(risks, key=lambda r: -r["ale"])[:3]
+ for i, risk in enumerate(top3, 1):
+ print(f" {i}. {risk['name']}: {fmt_dollars(risk['ale'])}/yr expected annual loss")
+ print(f" Mitigation: {fmt_dollars(risk['mitigation_cost'])}/yr | "
+ f"Status: {risk['mitigation_status']}")
+
+ unmitigated = [r for r in risks if r["mitigation_status"] == "None"]
+ if unmitigated:
+ print(f"\n ⚠️ UNMITIGATED RISKS ({len(unmitigated)}):")
+ for r in sorted(unmitigated, key=lambda x: -x["ale"]):
+ print(f" • {r['name']}: {fmt_dollars(r['ale'])}/yr — Action required")
+
+
+def export_csv(risks: list[dict], filepath: str):
+ fields = [
+ "name", "category", "asset_value", "exposure_factor", "annual_rate",
+ "sle", "ale", "mitigation_cost", "mitigation_effectiveness",
+ "mitigated_ale", "mitigation_roi_pct", "mitigation_status", "notes"
+ ]
+ with open(filepath, "w", newline="") as f:
+ writer = csv.DictWriter(f, fieldnames=fields)
+ writer.writeheader()
+ for risk in risks:
+ row = {k: risk.get(k, "") for k in fields}
+ writer.writerow(row)
+ print(f"✅ Exported {len(risks)} risks to {filepath}")
+
+
+def export_json(risks: list[dict]) -> str:
+ return json.dumps(risks, indent=2, default=str)
+
+
+# ─── Interactive Entry ───────────────────────────────────────────────────────
+
+def interactive_add_risk() -> dict:
+ """Interactive CLI for adding a new risk."""
+ print("\n── ADD NEW RISK ──────────────────────────────────────")
+ name = input("Risk name: ").strip()
+
+ print(f"Category options: {', '.join(RISK_CATEGORIES)}")
+ category = input("Category: ").strip()
+
+ description = input("Description (brief): ").strip()
+
+ print("\nAsset valuation:")
+ asset_value = float(input(" Asset value ($): ").replace(",", "").replace("$", ""))
+ exposure_factor = float(input(" Exposure factor (0.0–1.0, fraction of value lost): "))
+ annual_rate = float(input(" Annual rate of occurrence (e.g., 0.10 = once per 10 years): "))
+
+ print("\nMitigation:")
+ mitigation_cost = float(input(" Mitigation cost ($/yr): ").replace(",", "").replace("$", ""))
+ mitigation_effectiveness = float(input(" Mitigation effectiveness (0.0–1.0): "))
+
+ print(f"Status options: {', '.join(MITIGATION_STATUSES)}")
+ mitigation_status = input(" Status: ").strip()
+
+ print("\nBusiness impacts (enter 0 to skip):")
+ business_impacts = {}
+ for impact_type in BUSINESS_IMPACT_TYPES:
+ val = input(f" {impact_type} ($): ").replace(",", "").replace("$", "")
+ amount = float(val) if val else 0
+ if amount > 0:
+ business_impacts[impact_type] = amount
+
+ notes = input("\nNotes: ").strip()
+
+ return build_risk(
+ name=name,
+ category=category,
+ description=description,
+ asset_value=asset_value,
+ exposure_factor=exposure_factor,
+ annual_rate=annual_rate,
+ mitigation_cost=mitigation_cost,
+ mitigation_effectiveness=mitigation_effectiveness,
+ mitigation_status=mitigation_status,
+ business_impacts=business_impacts,
+ notes=notes,
+ )
+
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="CISO Risk Quantifier — Quantify security risks in business terms"
+ )
+ parser.add_argument("--json", action="store_true", help="Output full JSON")
+ parser.add_argument("--csv", metavar="FILE", help="Export CSV to file")
+ parser.add_argument("--budget", type=float, metavar="DOLLARS",
+ help="Show recommended mitigations within budget")
+ parser.add_argument("--board", action="store_true", help="Show board-ready summary only")
+ parser.add_argument("--detail", action="store_true", help="Show detailed risk breakdowns")
+ parser.add_argument("--add", action="store_true", help="Interactively add a risk")
+ args = parser.parse_args()
+
+ risks = load_sample_risks()
+
+ if args.add:
+ new_risk = interactive_add_risk()
+ risks.append(new_risk)
+ print(f"\n✅ Added risk: {new_risk['name']} | ALE: {fmt_dollars(new_risk['ale'])}/yr")
+
+ # Sort by ALE descending
+ risks_sorted = sorted(risks, key=lambda r: -r["ale"])
+ summary = calculate_portfolio_summary(risks_sorted)
+
+ if args.json:
+ output = {
+ "generated": datetime.now().isoformat(),
+ "summary": summary,
+ "risks": risks_sorted,
+ }
+ print(json.dumps(output, indent=2, default=str))
+ return
+
+ if args.csv:
+ export_csv(risks_sorted, args.csv)
+ return
+
+ print_header()
+
+ if args.board:
+ print_board_summary(risks_sorted, summary)
+ return
+
+ print_portfolio_summary(summary)
+ print_risk_table(risks_sorted)
+
+ if args.detail:
+ for i, risk in enumerate(risks_sorted, 1):
+ print_risk_detail(risk, i)
+
+ if args.budget:
+ recommended = prioritize_risks(risks_sorted, args.budget)
+ print(f"\n💰 BUDGET ALLOCATION — ${args.budget:,.0f}")
+ print(f" Recommended mitigations (sorted by ROI):")
+ if recommended:
+ for r in recommended:
+ print(f" • {r['name']}: {fmt_dollars(r['mitigation_cost'])}/yr "
+ f"| ALE reduction: {fmt_dollars(r['ale'] - r['mitigated_ale'])}/yr "
+ f"| ROI: {fmt_pct(r['mitigation_roi_pct'])}")
+ else:
+ print(" No actionable mitigations fit within budget.")
+
+ print_board_summary(risks_sorted, summary)
+
+ print("\n💡 NEXT STEPS")
+ print(" 1. Run `--detail` to see full breakdown of each risk")
+ print(" 2. Run `--budget 200000` to see what you can mitigate with a given budget")
+ print(" 3. Run `--board` for a board-ready one-page summary")
+ print(" 4. Run `--csv risks.csv` to export for stakeholder review")
+ print(" 5. Run `--add` to interactively add risks to the register")
+ print()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/cmo-advisor/SKILL.md b/skills/cmo-advisor/SKILL.md
new file mode 100644
index 00000000..f8fc3298
--- /dev/null
+++ b/skills/cmo-advisor/SKILL.md
@@ -0,0 +1,169 @@
+---
+name: "cmo-advisor"
+description: "Marketing leadership for scaling companies. Brand positioning, growth model design, marketing budget allocation, and marketing org design. Use when designing brand strategy, selecting growth models (PLG vs sales-led vs community-led), allocating marketing budgets, building marketing teams, or when user mentions CMO, brand strategy, growth model, CAC, LTV, channel mix, or marketing ROI."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: c-level
+ domain: cmo-leadership
+ updated: 2026-03-05
+ python-tools: marketing_budget_modeler.py, growth_model_simulator.py
+ frameworks: brand-positioning, growth-frameworks, marketing-org
+---
+
+# CMO Advisor
+
+Strategic marketing leadership — brand positioning, growth model design, budget allocation, and org design. Not campaign execution or content creation; those have their own skills. This is the engine.
+
+## Keywords
+CMO, chief marketing officer, brand strategy, brand positioning, growth model, product-led growth, PLG, sales-led growth, community-led growth, marketing budget, CAC, customer acquisition cost, LTV, lifetime value, channel mix, marketing ROI, pipeline contribution, marketing org, category design, competitive positioning, growth loops, payback period, MQL, pipeline coverage
+
+## Quick Start
+
+```bash
+# Model budget allocation across channels, project MQL output by scenario
+python scripts/marketing_budget_modeler.py
+
+# Project MRR growth by model, show impact of channel mix shifts
+python scripts/growth_model_simulator.py
+```
+
+**Reference docs (load when needed):**
+- `references/brand_positioning.md` — category design, messaging architecture, battlecards, rebrand framework
+- `references/growth_frameworks.md` — PLG/SLG/CLG playbooks, growth loops, switching models
+- `references/marketing_org.md` — team structure by stage, hiring sequence, agency vs. in-house
+
+---
+
+## The Four CMO Questions
+
+Every CMO must own answers to these — no one else in the C-suite can:
+
+1. **Who are we for?** — ICP, positioning, category
+2. **Why do they choose us?** — Differentiation, messaging, brand
+3. **How do they find us?** — Growth model, channel mix, demand gen
+4. **Is it working?** — CAC, LTV:CAC, pipeline contribution, payback period
+
+---
+
+## Core Responsibilities (Brief)
+
+**Brand & Positioning** — Define category, build messaging architecture, maintain competitive differentiation. Details → `references/brand_positioning.md`
+
+**Growth Model** — Choose and operate the right acquisition engine: PLG, sales-led, community-led, or hybrid. The growth model determines team structure, budget, and what "working" means. Details → `references/growth_frameworks.md`
+
+**Marketing Budget** — Allocate from revenue target backward: new customers needed → conversion rates by stage → MQLs needed → spend by channel based on CAC. Run `marketing_budget_modeler.py` for scenarios.
+
+**Marketing Org** — Structure follows growth model. Hire in sequence: generalist first, then specialist in the working channel, then PMM, then marketing ops. Details → `references/marketing_org.md`
+
+**Channel Mix** — Audit quarterly: MQLs, cost, CAC, payback, trend. Scale what's improving. Cut what's worsening. Don't optimize a channel that isn't in the strategy.
+
+**Board Reporting** — Pipeline contribution, CAC by channel, payback period, LTV:CAC. Not impressions. Not MQLs in isolation.
+
+---
+
+## Key Diagnostic Questions
+
+Ask these before making any strategic recommendation:
+
+- What's your CAC **by channel** (not blended)?
+- What's the payback period on your largest channel?
+- What's your LTV:CAC ratio?
+- What % of pipeline is marketing-sourced vs. sales-sourced?
+- Where do your **best customers** (highest LTV, lowest churn) come from?
+- What's your MQL → Opportunity conversion rate? (proxy for lead quality)
+- Is this brand work or performance marketing? (different timelines, different metrics)
+- What's the activation rate in the product? (PLG signal)
+- If a prospect doesn't buy, why not? (win/loss data)
+
+---
+
+## CMO Metrics Dashboard
+
+| Category | Metric | Healthy Target |
+|----------|--------|---------------|
+| **Pipeline** | Marketing-sourced pipeline % | 50–70% of total |
+| **Pipeline** | Pipeline coverage ratio | 3–4x quarterly quota |
+| **Pipeline** | MQL → Opportunity rate | > 15% |
+| **Efficiency** | Blended CAC payback | < 18 months |
+| **Efficiency** | LTV:CAC ratio | > 3:1 |
+| **Efficiency** | Marketing % of total S&M spend | 30–50% |
+| **Growth** | Brand search volume trend | ↑ QoQ |
+| **Growth** | Win rate vs. primary competitor | > 50% |
+| **Retention** | NPS (marketing-sourced cohort) | > 40 |
+
+---
+
+## Red Flags
+
+- No defined ICP — "companies with 50-1000 employees" is not an ICP
+- Marketing and sales disagree on what an MQL is (this is always a system problem, not a people problem)
+- CAC tracked only as a blended number — channel-level CAC is non-negotiable
+- Pipeline attribution is self-reported by sales reps, not CRM-timestamped
+- CMO can't answer "what's our payback period?" without a 48-hour research project
+- Brand work and performance marketing have no shared narrative — they're contradicting each other
+- Marketing team is producing content with no documented positioning to anchor it
+- Growth model was chosen because a competitor uses it, not because the product/ACV/ICP fits
+
+---
+
+## Integration with Other C-Suite Roles
+
+| When... | CMO works with... | To... |
+|---------|-------------------|-------|
+| Pricing changes | CFO + CEO | Understand margin impact on positioning and messaging |
+| Product launch | CPO + CTO | Define launch tier, GTM motion, messaging |
+| Pipeline miss | CFO + CRO | Diagnose: volume problem, quality problem, or velocity problem |
+| Category design | CEO | Secure multi-year organizational commitment to the narrative |
+| New market entry | CEO + CFO | Validate ICP, budget, localization requirements |
+| Sales misalignment | CRO | Align on MQL definition, SLA, and pipeline ownership |
+| Hiring plan | CHRO | Define marketing headcount and skill profile by stage |
+| Retention insights | CCO | Use expansion and churn data to sharpen ICP and messaging |
+| Competitive threat | CEO + CRO | Coordinate battlecards, win/loss, repositioning response |
+
+---
+
+## Resources
+
+- **References:** `references/brand_positioning.md`, `references/growth_frameworks.md`, `references/marketing_org.md`
+- **Scripts:** `scripts/marketing_budget_modeler.py`, `scripts/growth_model_simulator.py`
+
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- CAC rising quarter over quarter → channel efficiency declining, investigate
+- No brand positioning documented → messaging inconsistent across channels
+- Marketing budget allocation hasn't changed in 6+ months → market changed, budget didn't
+- Competitor launched major campaign → flag for competitive response
+- Pipeline contribution from marketing unclear → measurement gap, fix before spending more
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Plan our marketing budget" | Channel allocation model with CAC targets per channel |
+| "Position us vs competitors" | Positioning map + messaging framework + proof points |
+| "Design our growth model" | Growth projection with channel mix scenarios |
+| "Build the marketing team" | Hiring plan with sequence, roles, agency vs in-house |
+| "Marketing board section" | Pipeline contribution report with channel ROI |
+
+## Reasoning Technique: Recursion of Thought
+
+Draft a marketing strategy, then critique it from the customer's perspective. Refine based on the critique. Repeat until the strategy survives scrutiny.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
diff --git a/skills/cmo-advisor/_meta.json b/skills/cmo-advisor/_meta.json
new file mode 100644
index 00000000..9b9d1f1c
--- /dev/null
+++ b/skills/cmo-advisor/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "cmo-advisor",
+ "displayName": "Cmo Advisor",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773175663697,
+ "commit": "https://github.com/openclaw/skills/commit/d2da487a2374665e6555f643275dd2571e52338d"
+ },
+ "history": [
+ {
+ "version": "2.0.0",
+ "publishedAt": 1772746533896,
+ "commit": "https://github.com/openclaw/skills/commit/71b5a0239932f437031c404821fd8d3d745a2781"
+ }
+ ]
+}
diff --git a/skills/cmo-advisor/references/brand_positioning.md b/skills/cmo-advisor/references/brand_positioning.md
new file mode 100644
index 00000000..1a1acf22
--- /dev/null
+++ b/skills/cmo-advisor/references/brand_positioning.md
@@ -0,0 +1,374 @@
+# Brand Positioning Reference
+
+Practical frameworks for defining, communicating, and defending your market position. Not theory — applied tools for CMOs who need to get this right.
+
+---
+
+## 1. Category Design Frameworks
+
+### The Category Design Principle
+
+Every product exists in a category — either one you define or one someone else defined. If you're not designing your category, your competitors are designing it for you, and they'll design it to exclude you.
+
+**Category design is not renaming an existing category.** It's declaring that the existing category no longer solves the problem adequately, and that a new category — which you happen to lead — is required.
+
+### The Three-Act Category Design Narrative
+
+**Act 1: Name the problem**
+Identify a problem that's real, growing, and underserved. Not a problem you invented — a problem your best customers articulate before they've heard your pitch.
+
+> "Enterprise software teams are deploying faster than ever, but their security reviews still take 3 weeks — because security was built for a world where deployments happen monthly, not hourly."
+
+**Act 2: Define the new category**
+Name the category in terms of the outcome, not the feature. The category name should describe what customers achieve, not what the product does.
+
+> "Continuous security" — not "automated security scanning" or "DevSecOps platform."
+
+**Act 3: Position yourself as the category leader**
+You can't just claim leadership — you need proof: customers, analysts, community, content, events. Leadership is built, not declared.
+
+> "Snyk is building the continuous security category. 1.2M developers have adopted Snyk. Gartner lists us as a Cool Vendor in AppSec."
+
+### When Category Design Works
+
+| Condition | Explanation |
+|-----------|-------------|
+| Market timing | The problem is growing but the existing category is inadequate |
+| CEO commitment | Category design is a 3-5 year initiative, not a marketing campaign |
+| Analyst alignment | Gartner, Forrester, or G2 need to recognize your category |
+| Community | Practitioners adopt the vocabulary before buyers do |
+| Content moat | You publish the defining content for the category before competitors |
+
+### Category Design Pitfalls
+
+- **Naming the category after yourself:** "The [Your Company] Category" is not a category. It's a vanity.
+- **Categories that don't solve analyst definitions:** If Gartner doesn't have a Magic Quadrant for your category, you're fighting uphill.
+- **Jargon without adoption:** If your category name requires a two-paragraph explanation, it won't stick.
+- **Starting a category war you can't win:** If an incumbent can copy your category name and launch in 90 days, you don't have a defensible category.
+
+### The Lightning Strike Strategy
+
+Category design requires concentrated, coordinated effort — not slow drip. Execute these simultaneously:
+
+1. **Major piece of research or data** (the "State of X" report)
+2. **Category-defining event** (host it, don't just attend)
+3. **Analyst briefing** (educate Gartner/Forrester on the category before they define it themselves)
+4. **Book or manifesto** (long-form content that becomes the category Bible)
+5. **Community formation** (a Slack group, a conference, a certification that practitioners want)
+
+Do all five within a 3-month window. This creates gravity around your category claim.
+
+---
+
+## 2. Messaging Architecture
+
+### The Messaging Hierarchy
+
+Every piece of content — from a tweet to a 60-page whitepaper — should trace back to this hierarchy. When it doesn't, you have messaging drift.
+
+```
+Level 1: Brand Promise
+"[Company] [verb] [outcome] for [audience]"
+→ Doesn't change. This is the north star.
+
+Level 2: Positioning Statement (internal)
+For [target customer] who [has this problem],
+[Company] is the [market category] that [differentiated capability]
+unlike [alternatives], [Company] [proof of differentiation].
+
+Level 3: Value Propositions (3-4 max, one per key outcome)
+Each VP: headline (5-8 words) + 2-3 sentence explanation + proof point
+
+Level 4: Proof Points
+Data, case studies, certifications, analyst recognition — evidence for each VP
+
+Level 5: Channel Adaptations
+Website copy, sales deck, ad copy, email — same hierarchy, different format
+```
+
+### Writing a Positioning Statement
+
+The Geoffrey Moore / April Dunford format is still the best framework:
+
+**Template:**
+```
+For [specific target customer]
+who [has this specific, painful problem],
+[Company name] is the [market category]
+that [key differentiated capability].
+Unlike [primary alternatives],
+[Company] [proof of differentiation — something measurable or unique].
+```
+
+**Bad example (too generic):**
+> For B2B companies who want to grow faster, Acme is the marketing platform that helps you get more leads. Unlike other platforms, Acme is easy to use and powerful.
+
+**Good example (specific and falsifiable):**
+> For DevOps teams in regulated industries who spend 20% of their sprint cycles on compliance reviews, Acme is the compliance automation platform that embeds regulatory checks directly into the CI/CD pipeline. Unlike manual compliance tools that create a separate review queue, Acme's policy-as-code approach reduces compliance-related cycle time by 60% without slowing deployments.
+
+**Test your positioning statement:**
+1. Can a competitor say the exact same thing? (If yes, it's not differentiated)
+2. Does it describe what you do or what the customer gets? (Should be the latter)
+3. Would your best customer say "yes, that's exactly my problem"? (If not, wrong ICP)
+4. Is it falsifiable? (Claims you can't prove are liabilities)
+
+### Value Proposition Development
+
+**Structure for each VP:**
+
+| Element | Description | Example |
+|---------|-------------|---------|
+| Outcome headline | What changes for the customer (5-8 words) | "Ship features 3x faster" |
+| The problem | Why this matters now (1 sentence) | "Compliance reviews block 40% of releases in regulated industries" |
+| Our approach | How we solve it differently (1-2 sentences) | "Policy-as-code embeds checks in the pipeline instead of adding a gate at the end" |
+| Proof | Evidence this is real (1 sentence + data point) | "Customers reduce compliance cycle time by 60% in the first 90 days" |
+
+**3-VP Architecture is the standard:**
+- VP1: Core outcome (what most customers primarily buy for)
+- VP2: Secondary benefit (makes the decision easier or stickier)
+- VP3: Differentiator (what tips competitive decisions in your favor)
+
+### Proof Point Hierarchy
+
+Not all proof is equal. When you make a claim, match the strength of your proof to the importance of the claim.
+
+| Proof Type | Strength | Best Used For |
+|------------|---------|--------------|
+| Third-party data (analyst report, research) | Highest | Category claims, market size |
+| Customer ROI data with name | High | Value propositions |
+| Customer quote with name and company | Medium-high | Specific pain points and outcomes |
+| Aggregated customer data ("customers report…") | Medium | Directional claims |
+| Internal testing or benchmark | Medium-low | Product capability claims |
+| "Designed to…" or "built for…" | Low | Product direction only |
+| "We believe…" or "we think…" | Lowest | Vision statements only |
+
+**Proof point development process:**
+1. Write the claim you want to make
+2. Identify the strongest available proof
+3. If proof is weak, either soften the claim or invest in getting better proof
+4. Never publish a claim without knowing what happens when a skeptic asks "prove it"
+
+---
+
+## 3. Competitive Positioning Maps
+
+### The Two-Axis Map
+
+Choose two dimensions that:
+1. Both matter to your target buyer
+2. Create clear differentiation between you and competitors
+3. You can credibly defend
+
+**Choosing the axes:**
+- Axis 1 should show a dimension where you win and most competitors cluster on the wrong side
+- Axis 2 should show a dimension buyers care about deeply (ease, speed, breadth, price, compliance, etc.)
+
+**What to avoid:**
+- "Quality" vs. "Price" — too generic, every company claims the top-left
+- Dimensions your competitors can match in one release cycle
+- Dimensions that only your product team understands, not buyers
+
+### Competitive Analysis Template
+
+For each major competitor:
+
+**Company:** _______________
+
+| Dimension | What They Claim | What Customers Actually Experience | Gap |
+|-----------|----------------|-----------------------------------|-----|
+| Positioning | | | |
+| Primary differentiator | | | |
+| Pricing | | | |
+| Ideal customer | | | |
+| Weakness (win/loss data) | | | |
+| What they say about you | | | |
+
+**Sources for competitive intelligence:**
+- Win/loss interviews (primary source — nothing beats this)
+- G2/Capterra reviews (what customers say publicly)
+- Glassdoor (tells you about internal culture and focus)
+- LinkedIn job postings (what they're building next)
+- Their pricing page changes (what they're competing on)
+- Conference talks from their product and sales leaders
+
+### Battlecard Format
+
+One page per competitor. Used by sales, not marketing.
+
+```
+COMPETING AGAINST: [Competitor Name]
+
+WHY CUSTOMERS CONSIDER THEM:
+(2-3 bullets — be honest about their appeal)
+
+OUR DIFFERENTIATION:
+(2-3 bullets — factual, not marketing language)
+
+THE LANDMINE QUESTION:
+(One question that exposes their weakness. The answer should make the buyer uncomfortable choosing them.)
+Example: "How long does your typical implementation take? And what's your SLA if it runs over?"
+
+OUR PROOF POINTS IN THIS COMPARISON:
+- [Customer name] switched from [competitor] after [specific reason], saw [specific result]
+- [Data point that directly contradicts competitor's primary claim]
+
+THEIR LIKELY COUNTER-MOVES:
+(What will they say about us? How do we respond?)
+
+WHEN TO WALK AWAY:
+(If the prospect values X more than Y, we are not the right fit — say so)
+```
+
+---
+
+## 4. Brand Voice Development
+
+### What Brand Voice Is (and Isn't)
+
+**Brand voice is NOT:**
+- A list of adjectives ("we are professional, innovative, and customer-focused")
+- The tone you use in formal communications
+- The font and color palette (that's visual identity)
+
+**Brand voice IS:**
+- How the company sounds across every written touchpoint
+- Consistent enough to be recognizable, flexible enough to be human
+- Grounded in what your best customers actually value
+
+### The Voice Attribute Framework
+
+Define 3-4 voice attributes. For each:
+1. **What it means** (in one sentence)
+2. **What it sounds like** (one example)
+3. **What it doesn't mean** (the common mistake that goes wrong)
+
+**Example:**
+
+| Attribute | Means | Sounds like | Doesn't mean |
+|-----------|-------|------------|--------------|
+| Direct | We say what we mean without hedging | "Your compliance review takes 3 weeks. It shouldn't." | Blunt, rude, or dismissive |
+| Expert | We speak from depth, not from trend | "Here's why most security gates fail at scale, and what actually works." | Jargon-heavy or condescending |
+| Honest | We acknowledge what we don't do | "We're not the best fit if you need a one-size-fits-all platform." | Self-deprecating or uncertain |
+| Human | Real people write for real people | "Deploying on a Friday? Here's what we'd check first." | Casual, unprofessional |
+
+### Voice Consistency Testing
+
+Take a random sample of 10 recent pieces of content:
+- Website homepage and pricing page
+- 3 blog posts from different authors
+- 5 outbound emails from sales
+- 3 social posts
+- 1 press release
+
+Score each on: Does this sound like us? (1-5)
+
+Average < 3: You have a brand voice problem. The cause is usually no documented guidelines, or guidelines that exist but aren't enforced.
+
+### Voice in Different Contexts
+
+The attribute stays the same. The tone adjusts.
+
+| Context | Tone adjustment | Example of "Direct" |
+|---------|----------------|---------------------|
+| Homepage | Confident | "Compliance reviews don't have to slow you down." |
+| Technical docs | Precise | "Set the policy threshold to 0.95 to enforce mandatory approval." |
+| Error messages | Helpful | "That didn't work. Here's the most common reason why, and how to fix it." |
+| Support | Empathetic | "That's frustrating. Here's what happened and what we're doing about it." |
+| Sales outreach | Respectful | "Most teams in your space have this problem. Worth 20 minutes to explore?" |
+
+---
+
+## 5. Rebrand Decision Framework
+
+### When Rebrands Succeed vs. Fail
+
+**Successful rebrands:**
+- Driven by a genuine strategic shift (new category, new ICP, new market)
+- Have internal alignment before external launch
+- Are accompanied by product and messaging changes — not just visual
+- Have a 6-12 month transition plan for existing customers
+
+**Failed rebrands:**
+- Driven by internal boredom with the old brand
+- Executed as a "refresh" without repositioning the value proposition
+- Lack leadership conviction (executives still describe the company in the old terms)
+- Launch with a new logo but same product, same messaging, same ICP
+
+### The Rebrand Decision Matrix
+
+Answer each question. More "yes" answers = more likely rebrand is warranted.
+
+| Question | Yes | No |
+|----------|-----|-----|
+| Has our ICP changed significantly in the last 18 months? | Rebrand | Stay |
+| Are we entering a new market where the current brand creates friction? | Rebrand | Stay |
+| Does the brand name have negative associations in the market? | Rebrand | Stay |
+| Has an acquisition changed our core identity? | Rebrand | Stay |
+| Is the current brand actively hurting sales conversations? (evidence required) | Rebrand | Stay |
+| Are we bored with the brand? | Stay | — |
+| Did leadership change? | Stay | — |
+| Are competitors rebranding? | Stay | — |
+
+Score: 3+ "Rebrand" answers with evidence = worth a serious evaluation.
+
+### Rebrand Risk Assessment
+
+**Name change** is the highest-risk rebrand element. Before committing:
+- Legal: trademark availability in all target markets
+- SEO: 18-24 months to recover domain authority after a domain change
+- Customer: existing customers need to update all integrations, contracts, documentation
+- Analyst: re-education of Gartner, Forrester, G2 category definitions
+- Employee: company identity shift is a culture event, not just an HR task
+
+**Minimum viable rebrand (lower risk):**
+1. New positioning and messaging (always worth doing if positioning is wrong)
+2. Visual identity refresh (keep the name, update the look)
+3. Tagline change (the cheapest, lowest-risk brand change)
+
+**Full rebrand (high risk, sometimes necessary):**
+1. New company name and domain
+2. New visual identity
+3. New positioning and messaging
+4. New category narrative
+
+### Rebrand Execution Checklist
+
+**Pre-launch (90 days):**
+- [ ] Finalize positioning before finalizing design (in that order)
+- [ ] Legal trademark clearance in all target markets
+- [ ] Domain secured (with redirects planned)
+- [ ] Internal alignment: every leader can describe the new positioning in one sentence
+- [ ] Customer comms plan (existing customers, especially enterprise, need advance notice)
+- [ ] Analyst briefings scheduled (Gartner, Forrester — brief them before launch)
+- [ ] PR plan finalized
+
+**Launch (day 1):**
+- [ ] Website flipped
+- [ ] Social profiles updated
+- [ ] Email signatures updated company-wide
+- [ ] Sales deck updated
+- [ ] Press release published
+- [ ] Existing customers notified (email from CEO or CMO, not marketing automation)
+
+**Post-launch (90 days):**
+- [ ] SEO monitoring (watch for ranking drops on key terms)
+- [ ] Win rate monitoring (did conversion change?)
+- [ ] Employee feedback (are they using the new messaging correctly?)
+- [ ] Partner/channel update (resellers, integrations, directories)
+- [ ] Analyst follow-up (did they update their reports?)
+
+---
+
+## Quick Reference: Brand Positioning Diagnostic
+
+Use this as an audit against your current positioning:
+
+| Check | Pass | Fail |
+|-------|------|------|
+| Can every sales rep state the positioning in one sentence without looking it up? | ✓ | Positioning isn't working |
+| Is the ICP specific enough to disqualify companies? | ✓ | ICP is too broad |
+| Does the homepage lead with customer outcome, not product features? | ✓ | Copy needs rewrite |
+| Can you name 3 companies you're NOT a good fit for? | ✓ | Positioning is unfocused |
+| Do win/loss interviews confirm the stated differentiator? | ✓ | Differentiator is assumed, not proven |
+| Is the category name used by analysts or industry media? | ✓ | Category design needed |
+| Does every piece of content trace back to a VP from the hierarchy? | ✓ | Messaging drift — need guidelines |
diff --git a/skills/cmo-advisor/references/growth_frameworks.md b/skills/cmo-advisor/references/growth_frameworks.md
new file mode 100644
index 00000000..31ba0603
--- /dev/null
+++ b/skills/cmo-advisor/references/growth_frameworks.md
@@ -0,0 +1,456 @@
+# Growth Frameworks Reference
+
+Playbooks for PLG, sales-led, community-led, and hybrid growth models. Includes growth loops, funnel design, and guidance on when and how to switch models.
+
+---
+
+## 1. Product-Led Growth (PLG) Playbook
+
+### What PLG Actually Is
+
+PLG means the product is the primary distribution mechanism. Not "we have a free trial." Not "our product is self-serve." PLG means the product creates acquisition, retention, and expansion — and does so at a scale and cost no sales team can match.
+
+**The minimum requirements for PLG to work:**
+1. **Fast time-to-value:** Users must get a meaningful outcome within one session (ideally < 30 minutes)
+2. **Low friction to start:** No sales call, no implementation project, no credit card required (for top of funnel)
+3. **Built-in virality or network effects:** Usage creates exposure or value that draws in other users
+4. **Self-serve monetization or expansion path:** Freemium → paid, or individual → team → company
+
+If any of these is missing, you don't have PLG — you have a website with a free trial.
+
+### PLG Funnel: The Four Stages
+
+**Stage 1: Acquisition**
+The user discovers and signs up for the product without talking to sales.
+
+Key channels:
+- Organic search (SEO targeting jobs-to-be-done searches)
+- Product hunt launches
+- Referral and invite loops (users share the product with colleagues)
+- Developer communities and open-source contributions
+
+Metric: Visitor-to-signup rate
+
+Benchmark: 2-8% for B2B SaaS (varies heavily by product complexity)
+
+**Stage 2: Activation**
+The user reaches the "aha moment" — the point where the product delivers its core value for the first time.
+
+Finding the aha moment:
+- Look at the behaviors that differentiate users who stay from users who churn in the first 30 days
+- The aha moment is not creating an account. It's completing the first outcome.
+- For Slack: sending a message in a real channel
+- For Dropbox: adding a file from a second device
+- For HubSpot: publishing a form that captures a real lead
+
+Metric: Activation rate (% of signups who complete the aha moment action within 7 days)
+
+Benchmark: 25-40% is strong. < 15% means the onboarding is broken.
+
+**Stage 3: Retention**
+Users return to the product and build habitual use.
+
+Retention analysis:
+- Cohort retention curves (by signup week/month)
+- Day 1, Day 7, Day 30, Day 90 retention rates
+- Feature adoption by retained vs. churned users (which features predict retention?)
+
+Metric: D30 retention rate (% of users still active 30 days after signup)
+
+Benchmark: > 40% D30 retention is strong for B2B products
+
+**Stage 4: Revenue**
+Self-serve conversion from free to paid, or expansion from individual to team.
+
+PQL (Product-Qualified Lead) signals:
+- Reached a usage limit (invites, storage, seats)
+- Used a premium feature in trial mode
+- Team size on the account reached a threshold
+- High-frequency usage above a defined threshold
+
+Metric: PQL conversion rate (% of PQLs who convert to paid within 30 days)
+
+Benchmark: 15-30% for well-designed PLG products
+
+### PLG Expansion Model
+
+PLG growth compounds through account expansion:
+
+```
+Individual user discovers product
+ → Gets value, invites teammates
+ → Team adopts product
+ → Becomes department-wide
+ → Finance/IT gets involved
+ → Enterprise contract
+```
+
+This is "bottom-up" enterprise: individual adoption precedes company-wide purchase. It's also the most defensible moat — when every engineer in the company uses your product individually, procurement cancellation is very hard.
+
+**Expansion levers:**
+- Seat-based pricing (more users = more revenue, aligned with value)
+- Usage-based pricing (more usage = more value = more revenue)
+- Feature gating (team/enterprise features visible but gated, creating pull to upgrade)
+- Admin discovery (usage reports surface to managers who didn't know they had a product champion)
+
+### PLG Diagnostic
+
+| Question | Healthy | Unhealthy |
+|----------|---------|-----------|
+| Time-to-value | < 30 minutes | > 2 hours |
+| Activation rate | > 30% | < 15% |
+| D30 retention | > 40% | < 20% |
+| PQL conversion | > 15% | < 5% |
+| NPS from self-serve users | > 40 | < 20 |
+| Viral coefficient | > 0.3 | < 0.1 |
+
+### PLG Team Structure
+
+```
+Head of Growth (often VP Product or VP Marketing)
+├── Growth PM (owns activation and retention loops in product)
+├── Growth Engineer (2-3 engineers dedicated to growth experiments)
+├── Data Analyst (experimentation, funnel analysis, cohort reports)
+└── Growth Marketer (acquisition, SEO, referral programs)
+```
+
+The growth team sits between product and marketing. This is intentional — they own the product loops that drive acquisition and retention.
+
+---
+
+## 2. Sales-Led Growth (SLG) Model
+
+### The SLG System
+
+In SLG, marketing's job is to fill the sales pipeline. Sales converts it. The system only works if marketing and sales agree on definitions, SLAs, and shared metrics.
+
+**The SLG funnel:**
+
+```
+Awareness (Impressions, reach, brand search)
+ ↓
+Lead (Name + contact info captured)
+ ↓
+MQL — Marketing Qualified Lead (meets ICP criteria, intent signal detected)
+ ↓ [Marketing → Sales handoff]
+SAL — Sales Accepted Lead (sales reviews and accepts the lead)
+ ↓
+SQL — Sales Qualified Lead (sales confirms budget, authority, need, timeline)
+ ↓
+Opportunity (Formal deal in pipeline, has a close date)
+ ↓
+Closed-Won
+```
+
+**The MQL definition problem:**
+Most marketing-sales friction traces to an unclear MQL definition. The MQL should be:
+- ICP-matched (company size, industry, role)
+- Intent-signaled (visited pricing page, attended webinar, downloaded high-intent content)
+- Not just email address + "subscribed to newsletter"
+
+**A concrete MQL definition:**
+> Company 50-500 employees, B2B SaaS, role is VP Engineering or CTO or CISO, AND has performed 2+ of: attended webinar, visited pricing page, requested demo, downloaded security report, attended event.
+
+This definition makes the MQL useful. If you can't score it in your CRM without human judgment, it's not a definition — it's a guideline.
+
+### SLG Conversion Rate Benchmarks
+
+| Stage | Average B2B SaaS | Top Quartile |
+|-------|-----------------|--------------|
+| Lead → MQL | 5-15% | > 20% |
+| MQL → SAL | 50-70% | > 75% |
+| SAL → SQL | 30-50% | > 60% |
+| SQL → Opportunity | 60-80% | > 85% |
+| Opportunity → Closed-Won | 20-30% | > 40% |
+
+**End-to-end:** Lead → Closed-Won: 1-5% (wide range by ACV and ICP quality)
+
+### Pipeline Coverage Mechanics
+
+A healthy SLG pipeline has 3-4x coverage against quota.
+
+If a sales rep has a $500K quarterly quota:
+- They need $1.5M-$2M in active pipeline
+- Pipeline must be distributed across stages (not all "prospecting")
+- Stage distribution benchmark: 30% early, 40% mid, 30% late
+
+Insufficient coverage (< 3x) is a lagging indicator of a miss — by the time coverage is low, it's too late to recover in the same quarter. Coverage should be tracked weekly.
+
+### SLG Demand Generation Channels
+
+**High-intent channels (bottom of funnel):**
+- Paid search on buying-intent keywords (e.g., "[competitor] alternative", "best [category] software")
+- Review site presence (G2, Capterra) — buyers use these before vendor websites
+- Outbound SDR targeting specific accounts (ABM)
+
+**Medium-intent channels (middle of funnel):**
+- Webinars and virtual events (capture active learners)
+- Gated content (guides, benchmarks, templates — ICP-specific)
+- Retargeting to website visitors
+
+**Awareness channels (top of funnel):**
+- Content and SEO (captures people learning about the problem)
+- Podcast sponsorships, industry media
+- Conference sponsorship and speaking
+- Paid social (LinkedIn for B2B)
+
+### ABM (Account-Based Marketing) in SLG
+
+ABM flips the funnel: instead of generating leads and filtering for good ones, you start with target accounts and run coordinated campaigns against them.
+
+**Tiers:**
+- **Tier 1 (1:1):** 5-20 strategic accounts, fully customized campaigns, dedicated SDR+AE pairs, executive outreach
+- **Tier 2 (1:few):** 50-200 accounts, programmatic personalization, SDR sequences, targeted events
+- **Tier 3 (1:many):** 500+ accounts, standard campaigns with light personalization
+
+ABM requires tight sales/marketing alignment. If sales doesn't work the accounts marketing targets, ABM produces zero results.
+
+---
+
+## 3. Community-Led Growth (CLG)
+
+### The CLG Thesis
+
+Community-led growth works when:
+1. Your buyers want to learn from peers, not vendors
+2. There's a strong practitioner identity (developers, data teams, security, FinOps)
+3. Your category is complex enough that buyers need education before purchasing
+4. You can commit to building genuine community, not a marketing channel in disguise
+
+**The fundamental rule of CLG:** The community must deliver value to members whether or not they ever buy your product. If the only purpose of the community is to sell to members, the community will die.
+
+### CLG Stages
+
+**Stage 1: Find the community**
+The community often exists before you build it. Find where your practitioners already gather:
+- Slack groups, Discord servers
+- Subreddits and LinkedIn groups
+- Conference hallways
+- Open-source repositories
+
+Before building, participate. Earn trust. Understand the conversations.
+
+**Stage 2: Become the knowledge hub**
+Establish your company as the best source of information on the category problem:
+- Publish the benchmark study everyone references
+- Host the conference that defines the industry
+- Create the certification practitioners want on their resume
+- Open-source the tools the community needs
+
+**Stage 3: Build the platform**
+Create a dedicated community space (Slack, Discord, forum):
+- Community must be practitioner-first, not vendor-first
+- Community managers who genuinely care about member value
+- Content from members, not just from your company
+- Events that build member relationships, not just product demos
+
+**Stage 4: Convert community to customers**
+Community members who become customers do so because they trust you, not because you sold them. Conversion paths:
+- Community members see peer success with your product
+- Product-qualified signals from community members who trial the product
+- Direct outreach from sales to active community members (with permission and context)
+- Enterprise deals from companies whose employees are active in the community
+
+### CLG Metrics
+
+| Metric | Definition | Health Signal |
+|--------|-----------|--------------|
+| Monthly active members | Members who post, comment, or engage | > 15% of total members |
+| Community-sourced pipeline | $ pipeline where community was first touch | Track and trend |
+| Community-influenced pipeline | $ pipeline with any community touchpoint | > 30% of total pipeline |
+| NPS of community members vs. non-members | Loyalty difference | Community members should score 20+ pts higher |
+| Member-generated content % | % of content posted by non-employees | > 60% is healthy community |
+| Time from community join to product trial | | Shortens as community matures |
+
+### CLG Anti-Patterns
+
+- **Community as a newsletter:** If members can't interact with each other, it's not a community — it's a list.
+- **Product launches in the community:** Nothing kills community trust faster than using it for sales announcements.
+- **Community without a community manager:** Communities left to run themselves become ghost towns or become toxic.
+- **Measuring community by member count:** Ghost members are noise. Active engagement is signal.
+
+---
+
+## 4. Hybrid Growth Models
+
+### PLG + SLG ("Product-Led Sales" or PLS)
+
+The most common hybrid at growth stage. PLG handles SMB self-serve; sales closes enterprise.
+
+**The PQL-to-sales handoff:**
+
+Define the triggers that move a product-qualified lead to a sales-assisted motion:
+- Company has > X users (e.g., 10+ users on a team account)
+- Usage exceeds Y threshold in 30 days
+- Account is a named target in the ABM list
+- User explicitly requested a demo or upgrade assistance
+
+**The risk:** Sales team ignores PLG pipeline because deal size is smaller. Fix: separate quotas and commission structures for self-serve expansion vs. new enterprise logos.
+
+**The opportunity:** PLG creates pre-qualified champions inside accounts. Sales doesn't have to create interest — they convert it. Win rates in PLS motions are typically 30-50% higher than cold outbound.
+
+### SLG + CLG
+
+Community builds brand and generates inbound pipeline for sales.
+
+This hybrid works when:
+- Sales cycles are long (6-18 months)
+- Buyers do extensive research before engaging with vendors
+- The community validates your credibility before sales conversations begin
+
+**The integration:**
+- Community team feeds content insights to demand gen
+- Event attendees become high-priority SDR sequences
+- Active community members get dedicated AE outreach with community context
+- Win/loss analysis includes community touchpoints
+
+### PLG + CLG
+
+The developer/open-source hybrid. PLG handles product adoption; community handles advocacy and content.
+
+**Examples:** HashiCorp (Terraform community + enterprise sales), Elastic (open-source + community + commercial), Tailscale (developer community + self-serve + enterprise).
+
+**How it compounds:**
+```
+Community member learns from community content
+ → Discovers open-source or free tier
+ → Gets value in first session
+ → Shares experience in community
+ → New members discover product through community content
+```
+
+---
+
+## 5. Growth Loops vs. Funnels
+
+### The Difference
+
+**A funnel** is linear. It requires constant input at the top to produce output at the bottom. If you stop feeding it, it stops producing.
+
+**A growth loop** is cyclical. Output from one stage becomes input to the next. The system compounds.
+
+### Common Growth Loops
+
+**Viral loop:**
+```
+User gets value → Invites colleague → Colleague signs up →
+Colleague invites another colleague → ...
+```
+Viral coefficient (K) = (Average invites per user) × (Conversion rate of invites)
+- K > 1: Exponential growth (rare)
+- K 0.5-1: Strong viral assist
+- K < 0.3: Viral is not a meaningful growth driver
+
+**Content SEO loop:**
+```
+Publish content on [topic] → Ranks in search →
+Drives signups → Users share content → Builds backlinks →
+Better rankings → More content is possible
+```
+This loop takes 12-24 months to activate but is extraordinarily defensible once running.
+
+**UGC (User-Generated Content) loop:**
+```
+Users share their work publicly (templates, analyses, portfolios) →
+Others discover the work → They find the product →
+They create and share their own work → ...
+```
+Figma, Notion, Airtable, Canva — all run this loop.
+
+**Data network effect loop:**
+```
+More users → More data → Better product →
+More users attracted → ...
+```
+LinkedIn, Waze, Duolingo — accuracy or relevance improves as the user base grows.
+
+**Integration loop:**
+```
+Product integrates with X → X's users discover your product →
+More integrations possible → More discovery surfaces → ...
+```
+Zapier, Slack apps, Salesforce AppExchange — being in the ecosystem creates distribution.
+
+### Building a Growth Loop
+
+**Step 1: Map the current funnel**
+Where do customers come from? What are the conversion steps?
+
+**Step 2: Find the output**
+What does a successful customer produce?
+- Invite emails
+- Shared content
+- Public work visible to others
+- Reviews or testimonials
+
+**Step 3: Design the loop**
+How does that output become tomorrow's input to acquisition?
+- If they share → is there a landing page that captures the new visitor?
+- If they invite → is the invite experience friction-free?
+- If they create content → does it rank in search or appear in relevant communities?
+
+**Step 4: Measure loop velocity**
+For each loop, measure:
+- Cycle time: How long does one full cycle take?
+- Conversion at each step: Where does the loop break down?
+- Loop coefficient: How many new users does one existing user generate?
+
+---
+
+## 6. When to Switch Growth Models
+
+### The Warning Signs
+
+**PLG-to-SLG triggers:**
+- Enterprise accounts are signing up via PLG but aren't expanding without human intervention
+- Average deal sizes in enterprise are 10-20x SMB, and you're leaving revenue on the table
+- Product adoption in enterprise requires configuration or integration that needs support
+- PLG accounts churn at higher rates than sales-assisted accounts
+
+**SLG-to-PLG/PLS triggers:**
+- CAC is increasing year-over-year as competition for sales talent intensifies
+- Smaller competitors are winning deals with self-serve
+- Customers are asking "can I just try this myself?"
+- ACV is declining as the market matures and products commoditize
+- Sales team efficiency (revenue per sales rep) is declining
+
+**Adding CLG to existing motion:**
+- Sales cycles are long and trust is the primary barrier
+- SEO and content are generating traffic but low conversion (awareness without trust)
+- Competitors are building community and you're not present
+- Customer success teams report that customers who participate in user groups retain better
+
+### The Transition Playbook
+
+**Phase 1: Prove it before scaling (months 1-6)**
+Don't restructure the team to support the new model before proving it works.
+- Run a pilot: 3-5 SDRs testing PLG signals as outreach triggers (for PLG → PLS)
+- Or: Launch a beta community with 100 core customers (for adding CLG)
+- Measure the metrics of the new model, compare to current model
+
+**Phase 2: Parallel running (months 6-12)**
+Run both models simultaneously. Don't kill the current model while building the new one.
+- Set clear boundaries on which accounts go to which motion
+- Build dedicated teams for each model (don't ask the same people to do both)
+- Define success metrics for the new model independently
+
+**Phase 3: Rebalance (months 12-18)**
+Once the new model proves its unit economics:
+- Shift headcount and budget to the more efficient model
+- Keep the old model for the segments where it still works
+- Document what the new model requires to sustain itself
+
+**The anti-pattern:** Announcing a model shift without proof, restructuring the team, and discovering after 12 months that the new model doesn't work. By then, the old model's momentum is gone and you've burned a year.
+
+### Growth Model Maturity Matrix
+
+| Dimension | PLG | SLG | CLG |
+|-----------|-----|-----|-----|
+| Time to first results | 3-6 months | 1-3 months | 12-18 months |
+| Requires up-front product investment | High | Low | Medium |
+| Scales without linear headcount | Yes | No | Yes |
+| Predictable pipeline | Low (early) | High | Low (early) |
+| CAC trend over time | Decreases | Flat/increases | Decreases |
+| Works for ACV > $50K | Only with SLG assist | Yes | Yes |
+| Works for ACV < $5K | Yes | No | Only with PLG |
+| Defensibility once established | High | Low | Very high |
diff --git a/skills/cmo-advisor/references/marketing_org.md b/skills/cmo-advisor/references/marketing_org.md
new file mode 100644
index 00000000..7cc44d9f
--- /dev/null
+++ b/skills/cmo-advisor/references/marketing_org.md
@@ -0,0 +1,281 @@
+# Marketing Org Reference
+
+Team structure, hiring sequence, agency decisions, marketing ops, and cross-functional alignment — by company stage.
+
+---
+
+## 1. Marketing Team Structure by Stage
+
+### Pre-Seed / Seed (< $1M ARR, 1–10 people)
+
+Don't hire a marketing team yet. The founders are the marketing team.
+
+What to do instead:
+- Founders write content, do sales calls, go to events
+- The goal is learning the ICP and finding the channel that works, not scaling anything
+- One contractor or agency for specific output (design, SEO audit) is fine
+
+First marketing hire trigger: You have a repeatable sales motion and need to scale it.
+
+---
+
+### Series A ($1M–$5M ARR, 10–30 people)
+
+**Org:**
+```
+Founding Marketer (Head of Marketing or VP Marketing)
+```
+
+One person. Generalist. Capable of writing, running ads, setting up HubSpot, producing a report. Their job is to find what works.
+
+**What they own:**
+- Content and SEO foundation
+- Paid channel experiments
+- Sales enablement basics (1-pager, deck, email sequences)
+- Event presence (1-2 conferences)
+- Marketing attribution setup (get this right early)
+
+**What they don't own yet:**
+- Brand redesign
+- Analyst relations
+- Partner marketing
+- Field marketing team
+
+**CMO vs. VP Marketing at this stage:** VP Marketing. An experienced operator who can build and execute. A CMO's strategic value isn't fully leveraged until there's a team to lead and a budget to allocate.
+
+---
+
+### Series B ($5M–$20M ARR, 30–80 people)
+
+**PLG-first org:**
+```
+VP Marketing
+├── Growth Marketing (acquisition loops, activation, PLG analytics)
+├── Product Marketing (positioning, launch, sales enablement)
+└── Content & SEO (organic engine)
+```
+
+**SLG-first org:**
+```
+VP Marketing
+├── Demand Generation (pipeline creation, paid, digital)
+├── Product Marketing (positioning, competitive intel, enablement)
+├── Field Marketing (events, regional, ABM)
+└── Marketing Operations (CRM, attribution, reporting)
+```
+
+**Community-led org:**
+```
+VP Marketing
+├── Community & Developer Relations
+├── Content & SEO
+└── Product Marketing
+```
+
+**At this stage:** Marketing ops becomes critical. Without it, attribution is guesswork and the sales team blames marketing for bad leads.
+
+---
+
+### Series C ($20M–$75M ARR, 80–200 people)
+
+```
+CMO
+├── Demand Generation
+│ ├── Paid Media
+│ ├── SEO & Content
+│ └── Marketing Operations
+├── Product Marketing
+│ ├── Core PMMs (by product line or segment)
+│ └── Competitive Intelligence
+├── Field Marketing
+│ ├── Events
+│ └── Regional / ABM
+└── Brand & Communications
+ ├── Brand Design
+ └── PR / Analyst Relations
+```
+
+**At this stage:**
+- The CMO is a board-level communicator, not a campaign manager
+- Each function has a dedicated leader (director or VP level)
+- Marketing ops owns the attribution model and reports to CMO directly
+- Analyst relations becomes important (Gartner, Forrester, G2 category positioning)
+
+---
+
+### Growth Stage ($75M+ ARR)
+
+Marketing becomes a portfolio of specialized functions. Each major channel has a team. Brand is a serious investment. Analyst relations is a dedicated role. International marketing teams form.
+
+The CMO's job shifts from building the machine to:
+- Setting marketing strategy across a complex portfolio
+- Representing marketing at the board level
+- Owning brand and category leadership
+- Cross-functional leadership with CRO, CPO, CEO
+
+---
+
+## 2. Hiring Sequence
+
+### Who to Hire First
+
+**The generalist content + demand gen marketer.**
+
+Must-haves:
+- Can write (blog posts, emails, landing pages — not just briefs)
+- Can run paid campaigns (Google, LinkedIn — not just "I've managed agencies")
+- Can operate a marketing automation platform (HubSpot, Marketo)
+- Comfortable with data (can build a funnel report without asking an analyst)
+
+This person builds the foundation. They're not a specialist yet — they're testing channels and building the process.
+
+Avoid: Hiring a brand designer first. Or a community manager. Or a social media manager. These are specialties that compound on a foundation that doesn't exist yet.
+
+### Who to Hire Second
+
+**A specialist in the channel that's working.**
+
+If organic search is your top lead source → hire an SEO/content lead.
+If events are driving pipeline → hire a field marketer.
+If outbound is working → hire an SDR manager or demand gen specialist.
+
+Don't hire a generalist #2. By now you know what's working. Depth beats breadth.
+
+### Who to Hire Third
+
+**Product marketing.**
+
+Why third and not first? Because PMM output (positioning, sales enablement, launch) is most valuable when there's an audience to position to and a sales team to enable. Before that, the founding marketer does "good enough" PMM work.
+
+PMM hire profile: Has done positioning work before, has run a product launch, has built sales decks that sales actually uses, comfortable with win/loss analysis.
+
+PMM:PM ratio benchmark: 1 PMM per 2–3 PMs. If you have 6 PMs and 1 PMM, you have a messaging and enablement problem.
+
+### Who to Hire Fourth
+
+**Marketing operations.**
+
+This is consistently hired too late. By the time most companies hire marketing ops, attribution is broken, leads are being lost in handoffs, and the CRM data is unreliable. Hire marketing ops before you think you need it.
+
+Marketing ops profile: HubSpot/Marketo certified, SQL capable, understands multi-touch attribution, has integrated CRM + sales engagement tools before.
+
+### Hiring Decision Triggers
+
+| Hire | Trigger |
+|------|---------|
+| Generalist marketer #1 | Sales motion is repeatable, need to scale lead generation |
+| Specialist #2 | One channel is clearly outperforming — double down |
+| Product marketer | Sales team is losing deals to positioning confusion or competitor gaps |
+| Marketing ops | Running 3+ campaigns simultaneously with manual tracking |
+| Field marketer | Events are in the strategy and attendance > 2 conferences/quarter |
+| Head of Marketing / VP | Team is 3+ people and needs an org owner |
+| CMO | Company is Series B/C and marketing needs board-level representation |
+
+---
+
+## 3. Agency vs. In-House
+
+### Framework
+
+Keep in-house what compounds. Outsource what's episodic or specialized.
+
+| Function | Agency | In-House | Notes |
+|----------|--------|----------|-------|
+| Brand design | Early stage | Series B+ | Agency fine until redesigns become frequent |
+| Paid media | < $50K/month spend | > $50K/month | Agency margin eats returns at scale |
+| SEO strategy | Audit only | Ongoing execution | Strategy once, execution continuously |
+| Content production | Overflow only | Core writers | Your voice must be yours |
+| PR / comms | Almost always | $100M+ companies | Specialists required for media relationships |
+| Marketing ops / CRM | Never | Always | This is your data infrastructure |
+| Analyst relations | Initial strategy | Ongoing | Relationship-based — needs dedicated owner |
+| Video / creative production | Always | Rarely | Episodic, specialized equipment |
+
+### Agency Red Flags
+
+- They want to own your ad accounts. (Always keep ownership. No exceptions.)
+- SLA is "5 business days for creative requests." For a performance channel, that's too slow.
+- Reporting is impressions, CPM, and "brand lift." Where's the pipeline?
+- They can't tell you your CAC from their channel.
+- They won't share the actual data — only their dashboard.
+- Your account manager changes every 6 months.
+
+### Agency Evaluation Criteria
+
+1. **Proof of work in your category** — ask for 3 case studies with actual CAC and pipeline data
+2. **Who actually does the work** — senior pitch team ≠ junior execution team
+3. **Account ownership** — all accounts, pixels, analytics must be in your name
+4. **Reporting cadence** — weekly data, monthly strategy, quarterly business review
+5. **Exit terms** — how do you offboard without losing your data, accounts, and history?
+
+---
+
+## 4. Marketing Ops and Tech Stack
+
+### The Minimum Viable Stack
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| CRM | HubSpot / Salesforce | Contact database, pipeline, source of truth |
+| Marketing automation | HubSpot / Marketo / ActiveCampaign | Email, nurture, lead scoring |
+| Analytics | Google Analytics 4 + Segment | Traffic, behavior, event tracking |
+| Attribution | HubSpot / Attributer.io / Dreamdata | Multi-touch pipeline attribution |
+| Paid | Google Ads + LinkedIn Ads | Performance channels |
+| SEO | Ahrefs / Semrush | Keyword research, rank tracking |
+| Chat/conversion | Intercom / Drift | In-product + website conversion |
+
+**The integration that breaks most:** CRM ↔ Marketing automation ↔ Sales engagement. When these aren't synced properly, leads are lost, attribution is wrong, and marketing and sales fight about pipeline. Fix this first.
+
+### Marketing Ops Ownership
+
+Marketing ops must own:
+- CRM data quality (field standardization, deduplication, routing)
+- Lead scoring model (and quarterly review against conversion data)
+- Attribution model (with documented assumptions)
+- Campaign tracking (UTM governance — no UTM = no attribution)
+- Tech stack evaluation and contracts
+
+Marketing ops must NOT own:
+- Strategy (they enable it, not set it)
+- Content production
+- Campaign creative
+
+---
+
+## 5. Cross-Functional Alignment
+
+### Marketing + Sales
+
+The most important cross-functional relationship in a SLG company. Where it breaks:
+
+| Problem | Root Cause | Fix |
+|---------|-----------|-----|
+| "Marketing sends us bad leads" | MQL definition is unclear or wrong | Define MQL jointly, score against conversion data |
+| "Sales doesn't follow up on leads" | No SLA, no consequence | Define SLA (e.g., 24-hour response), track in CRM |
+| "Marketing doesn't understand what customers care about" | No win/loss sharing | Weekly call: sales shares 3 deal insights, marketing shares 3 content results |
+| "We don't know what's working" | Attribution is broken | Marketing ops fixes attribution before next budget cycle |
+
+**The SLA agreement (document this):**
+- Marketing commits: X MQLs/week meeting defined criteria, 48-hour SLA from form fill to SDR outreach
+- Sales commits: All MQLs contacted within 24 hours, disposition logged in CRM within 5 days
+
+### Marketing + Product
+
+Where it breaks and how to fix it:
+
+| Problem | Fix |
+|---------|-----|
+| PMM learns about launches 2 weeks before ship | PMM joins the product planning process at the roadmap stage, not the sprint stage |
+| Feature launches with no messaging | Launch tiers: Tier 1 (major, full launch), Tier 2 (minor, release notes + 1 post), Tier 3 (internal only) |
+| Product doesn't use customer insights from marketing | Monthly session: PMM shares win/loss themes, competitive intel, ICP data |
+| No feedback loop on messaging in-product | PMM owns in-product copy review, not just external comms |
+
+### Marketing + Customer Success
+
+Customer success is marketing's best source of truth:
+
+- **ICP validation:** Which customers are expanding? Which are churning? This refines who you target.
+- **Proof points:** CS-sourced case studies and testimonials outperform vendor-written content 3:1 in conversion.
+- **Messaging test:** If CS is answering the same question 20 times, marketing hasn't explained it clearly enough.
+- **Referral programs:** CS owns the relationship; marketing owns the mechanics. Design them together.
+
+Cadence: Monthly meeting between CMO and VP/Head of CS. Agenda: retention trends, expansion patterns, at-risk customers, NPS themes.
diff --git a/skills/cmo-advisor/scripts/growth_model_simulator.py b/skills/cmo-advisor/scripts/growth_model_simulator.py
new file mode 100644
index 00000000..59b28bfb
--- /dev/null
+++ b/skills/cmo-advisor/scripts/growth_model_simulator.py
@@ -0,0 +1,416 @@
+#!/usr/bin/env python3
+"""
+Growth Model Simulator
+----------------------
+Projects MRR growth across different growth models (PLG, sales-led, community-led,
+hybrid) and shows the impact of channel mix changes on growth trajectory.
+
+Usage:
+ python growth_model_simulator.py
+
+Inputs (edit INPUTS section):
+ - Starting MRR and churn rate
+ - Current channel mix (% of new MRR from each source)
+ - Conversion rates per model
+ - Growth rate assumptions per channel
+
+Outputs:
+ - 12-month MRR projection by growth model
+ - Channel mix impact analysis (what happens if you shift mix)
+ - Break-even months for each model
+ - Side-by-side comparison table
+"""
+
+from __future__ import annotations
+import math
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ChannelSource:
+ name: str
+ pct_of_new_mrr: float # Current share of new MRR (0.0–1.0)
+ monthly_growth_rate: float # How fast this channel grows month-over-month
+ cac: float # CAC in dollars
+ payback_months: float # Months to recover CAC
+
+
+@dataclass
+class GrowthModel:
+ name: str
+ description: str
+ channel_mix: Dict[str, float] # channel name → % of new MRR
+ new_mrr_monthly_base: float # Starting new MRR/month from this model
+ monthly_acceleration: float # Acceleration factor (compounding)
+ avg_ltv_cac: float # Expected LTV:CAC at scale
+ months_to_steady_state: int # Months before model hits its natural growth rate
+ notes: List[str] = field(default_factory=list)
+
+
+@dataclass
+class MonthSnapshot:
+ month: int
+ mrr: float
+ new_mrr: float
+ churned_mrr: float
+ expansion_mrr: float
+ net_new_mrr: float
+ cumulative_cac_spend: float
+
+
+@dataclass
+class ModelProjection:
+ model: GrowthModel
+ snapshots: List[MonthSnapshot]
+ break_even_month: Optional[int] # Month when cumulative revenue > cumulative CAC
+
+
+# ---------------------------------------------------------------------------
+# INPUTS — edit these
+# ---------------------------------------------------------------------------
+
+STARTING_MRR = 85_000 # Current MRR ($)
+MONTHLY_CHURN_RATE = 0.012 # Monthly churn rate (1.2% = ~14% annual)
+EXPANSION_RATE = 0.008 # Monthly expansion MRR as % of existing MRR
+GROSS_MARGIN = 0.75
+SIMULATION_MONTHS = 18
+
+# Channel sources (used to model mix shift scenarios)
+CHANNELS: List[ChannelSource] = [
+ ChannelSource("Organic/SEO", pct_of_new_mrr=0.28, monthly_growth_rate=0.04, cac=1_800, payback_months=9),
+ ChannelSource("PLG Self-Serve", pct_of_new_mrr=0.15, monthly_growth_rate=0.08, cac=900, payback_months=5),
+ ChannelSource("Outbound SDR", pct_of_new_mrr=0.25, monthly_growth_rate=0.02, cac=5_100, payback_months=21),
+ ChannelSource("Paid Search", pct_of_new_mrr=0.15, monthly_growth_rate=0.01, cac=6_200, payback_months=26),
+ ChannelSource("Events/Field", pct_of_new_mrr=0.08, monthly_growth_rate=0.01, cac=9_800, payback_months=41),
+ ChannelSource("Partner/Channel", pct_of_new_mrr=0.09, monthly_growth_rate=0.05, cac=3_400, payback_months=14),
+]
+
+# Growth models to simulate
+GROWTH_MODELS: List[GrowthModel] = [
+ GrowthModel(
+ name="Current Mix",
+ description="Baseline — maintain current channel allocation",
+ channel_mix={"Organic/SEO": 0.28, "PLG Self-Serve": 0.15, "Outbound SDR": 0.25,
+ "Paid Search": 0.15, "Events/Field": 0.08, "Partner/Channel": 0.09},
+ new_mrr_monthly_base=12_000,
+ monthly_acceleration=0.025,
+ avg_ltv_cac=3.2,
+ months_to_steady_state=3,
+ notes=["Baseline. No changes to channel mix."],
+ ),
+ GrowthModel(
+ name="PLG-First",
+ description="Shift budget toward PLG self-serve and organic; reduce paid and outbound",
+ channel_mix={"Organic/SEO": 0.35, "PLG Self-Serve": 0.35, "Outbound SDR": 0.10,
+ "Paid Search": 0.08, "Events/Field": 0.04, "Partner/Channel": 0.08},
+ new_mrr_monthly_base=9_500, # Slower start — PLG takes time to activate
+ monthly_acceleration=0.048, # But compounds faster
+ avg_ltv_cac=5.8,
+ months_to_steady_state=6, # PLG loops take time to build
+ notes=[
+ "Lower new MRR in months 1-6 while PLG loops activate.",
+ "Acceleration compounds strongly after month 6.",
+ "Requires product investment in activation/onboarding.",
+ "Best fit if time-to-value < 30 min and viral coefficient > 0.3.",
+ ],
+ ),
+ GrowthModel(
+ name="Sales-Led Scale",
+ description="Double down on outbound SDR and field; optimize for enterprise ACV",
+ channel_mix={"Organic/SEO": 0.20, "PLG Self-Serve": 0.05, "Outbound SDR": 0.40,
+ "Paid Search": 0.15, "Events/Field": 0.15, "Partner/Channel": 0.05},
+ new_mrr_monthly_base=15_000, # Higher new MRR from enterprise ACV
+ monthly_acceleration=0.018, # Linear growth — headcount-constrained
+ avg_ltv_cac=2.8,
+ months_to_steady_state=2,
+ notes=[
+ "Fastest short-term new MRR if ACV > $30K.",
+ "Growth is linear — adds headcount to add pipeline.",
+ "CAC and payback worsen as SDR market tightens.",
+ "Requires sales capacity increase to sustain.",
+ ],
+ ),
+ GrowthModel(
+ name="Community-Led",
+ description="Invest in community and content; reduce paid; long-term brand play",
+ channel_mix={"Organic/SEO": 0.45, "PLG Self-Serve": 0.15, "Outbound SDR": 0.15,
+ "Paid Search": 0.05, "Events/Field": 0.10, "Partner/Channel": 0.10},
+ new_mrr_monthly_base=7_000, # Slowest start
+ monthly_acceleration=0.038,
+ avg_ltv_cac=4.5,
+ months_to_steady_state=9, # Community takes longest to activate
+ notes=[
+ "Lowest new MRR in months 1-9.",
+ "Community trust drives lower CAC and higher retention at scale.",
+ "Best for categories where buyers seek peer validation.",
+ "Requires dedicated community manager from day one.",
+ ],
+ ),
+ GrowthModel(
+ name="Hybrid PLS",
+ description="PLG self-serve for SMB + sales-assisted for enterprise (Product-Led Sales)",
+ channel_mix={"Organic/SEO": 0.30, "PLG Self-Serve": 0.28, "Outbound SDR": 0.22,
+ "Paid Search": 0.08, "Events/Field": 0.06, "Partner/Channel": 0.06},
+ new_mrr_monthly_base=11_000,
+ monthly_acceleration=0.035,
+ avg_ltv_cac=4.1,
+ months_to_steady_state=4,
+ notes=[
+ "PLG handles SMB; sales closes enterprise with PQL signals.",
+ "Requires clear PQL definition and SDR/PLG handoff process.",
+ "Best if you have a product with both bottom-up and top-down adoption.",
+ ],
+ ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Simulation engine
+# ---------------------------------------------------------------------------
+
+def simulate_model(model: GrowthModel, months: int) -> ModelProjection:
+ snapshots: List[MonthSnapshot] = []
+ mrr = STARTING_MRR
+ cumulative_cac = 0.0
+ cumulative_revenue = 0.0
+ break_even_month = None
+
+ for m in range(1, months + 1):
+ # Ramp up — new_mrr accelerates each month
+ if m <= model.months_to_steady_state:
+ # Ramp phase: linear ramp from 60% to 100% of base
+ ramp_factor = 0.6 + 0.4 * (m / model.months_to_steady_state)
+ else:
+ # Steady state: compound acceleration
+ months_past_ramp = m - model.months_to_steady_state
+ ramp_factor = 1.0 + model.monthly_acceleration * months_past_ramp
+
+ new_mrr = model.new_mrr_monthly_base * ramp_factor
+ churned_mrr = mrr * MONTHLY_CHURN_RATE
+ expansion_mrr = mrr * EXPANSION_RATE
+ net_new_mrr = new_mrr - churned_mrr + expansion_mrr
+ mrr = mrr + net_new_mrr
+
+ # CAC spend approximation: new_mrr / (avg_deal_mrr) * blended_cac
+ # Use weighted CAC from channel mix
+ weighted_cac = _weighted_cac(model.channel_mix)
+ avg_deal_mrr = 1_500 # Assumption: $1,500 average deal MRR
+ deals_this_month = new_mrr / avg_deal_mrr
+ cac_spend = deals_this_month * weighted_cac
+ cumulative_cac += cac_spend
+ cumulative_revenue += mrr * GROSS_MARGIN
+
+ if break_even_month is None and cumulative_revenue >= cumulative_cac:
+ break_even_month = m
+
+ snapshots.append(MonthSnapshot(
+ month=m,
+ mrr=mrr,
+ new_mrr=new_mrr,
+ churned_mrr=churned_mrr,
+ expansion_mrr=expansion_mrr,
+ net_new_mrr=net_new_mrr,
+ cumulative_cac_spend=cumulative_cac,
+ ))
+
+ return ModelProjection(
+ model=model,
+ snapshots=snapshots,
+ break_even_month=break_even_month,
+ )
+
+
+def _weighted_cac(channel_mix: Dict[str, float]) -> float:
+ channel_cac = {ch.name: ch.cac for ch in CHANNELS}
+ total = sum(
+ channel_mix.get(name, 0) * cac
+ for name, cac in channel_cac.items()
+ )
+ weight_sum = sum(channel_mix.values())
+ return total / weight_sum if weight_sum > 0 else 5_000
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt_mrr(n: float) -> str:
+ if n >= 1_000_000:
+ return f"${n/1_000_000:.3f}M"
+ return f"${n/1_000:.1f}K"
+
+
+def fmt_currency(n: float) -> str:
+ if n >= 1_000_000:
+ return f"${n/1_000_000:.2f}M"
+ if n >= 1_000:
+ return f"${n/1_000:.1f}K"
+ return f"${n:.0f}"
+
+
+def print_header(title: str) -> None:
+ width = 78
+ print("\n" + "=" * width)
+ print(f" {title}")
+ print("=" * width)
+
+
+def print_channel_overview() -> None:
+ print_header("Current Channel Mix")
+ print(f" Starting MRR: {fmt_mrr(STARTING_MRR)} | Monthly churn: {MONTHLY_CHURN_RATE:.1%} | Expansion: {EXPANSION_RATE:.1%}/mo")
+ print()
+ print(f" {'Channel':<22} {'% MRR':>7} {'CAC':>8} {'Payback':>9} {'Growth/mo':>10}")
+ print(" " + "-" * 60)
+ for ch in sorted(CHANNELS, key=lambda c: c.pct_of_new_mrr, reverse=True):
+ print(
+ f" {ch.name:<22} {ch.pct_of_new_mrr:>6.0%} "
+ f"{fmt_currency(ch.cac):>8} {ch.payback_months:>7.0f}mo "
+ f"{ch.monthly_growth_rate:>9.1%}"
+ )
+
+
+def print_model_detail(proj: ModelProjection) -> None:
+ model = proj.model
+ print_header(f"Model: {model.name}")
+ print(f" {model.description}")
+ if model.notes:
+ print()
+ for note in model.notes:
+ print(f" • {note}")
+ print()
+
+ # Print monthly snapshot (every 3 months + final)
+ milestones = set(range(3, SIMULATION_MONTHS + 1, 3)) | {SIMULATION_MONTHS}
+ print(f" {'Month':<7} {'MRR':>10} {'New MRR':>9} {'Churned':>9} {'Expand':>8} {'Net New':>9}")
+ print(" " + "-" * 56)
+ for snap in proj.snapshots:
+ if snap.month in milestones:
+ print(
+ f" {snap.month:<7} {fmt_mrr(snap.mrr):>10} "
+ f"{fmt_mrr(snap.new_mrr):>9} {fmt_mrr(snap.churned_mrr):>9} "
+ f"{fmt_mrr(snap.expansion_mrr):>8} {fmt_mrr(snap.net_new_mrr):>9}"
+ )
+
+ final = proj.snapshots[-1]
+ growth_x = final.mrr / STARTING_MRR
+ arr_final = final.mrr * 12
+ weighted_cac = _weighted_cac(model.channel_mix)
+ be = f"Month {proj.break_even_month}" if proj.break_even_month else f"> {SIMULATION_MONTHS}mo"
+
+ print()
+ print(f" Final MRR ({SIMULATION_MONTHS}mo): {fmt_mrr(final.mrr)}")
+ print(f" Final ARR: {fmt_currency(arr_final)}")
+ print(f" Growth multiple: {growth_x:.1f}x from starting MRR")
+ print(f" Weighted blended CAC: {fmt_currency(weighted_cac)}")
+ print(f" Expected LTV:CAC: {model.avg_ltv_cac:.1f}x")
+ print(f" Months to steady state:{model.months_to_steady_state}")
+ print(f" CAC break-even: {be}")
+
+
+def print_comparison_table(projections: List[ModelProjection]) -> None:
+ print_header(f"Growth Model Comparison — Month {SIMULATION_MONTHS} Outcomes")
+ header = (
+ f" {'Model':<20} {'MRR (final)':>12} {'ARR (final)':>12} "
+ f"{'Growth':>7} {'LTV:CAC':>8} {'Break-even':>11}"
+ )
+ print(header)
+ print(" " + "-" * 74)
+ for proj in sorted(projections, key=lambda p: p.snapshots[-1].mrr, reverse=True):
+ final = proj.snapshots[-1]
+ growth_x = final.mrr / STARTING_MRR
+ arr_final = final.mrr * 12
+ be = f"Mo {proj.break_even_month}" if proj.break_even_month else f">{SIMULATION_MONTHS}mo"
+ print(
+ f" {proj.model.name:<20} {fmt_mrr(final.mrr):>12} "
+ f"{fmt_currency(arr_final):>12} {growth_x:>6.1f}x "
+ f"{proj.model.avg_ltv_cac:>7.1f}x {be:>11}"
+ )
+
+
+def print_channel_mix_impact(projections: List[ModelProjection]) -> None:
+ print_header("Channel Mix Impact Analysis")
+ print(" How shifting channel mix changes growth trajectory:\n")
+ baseline = next((p for p in projections if p.model.name == "Current Mix"), None)
+ if not baseline:
+ return
+ baseline_final_mrr = baseline.snapshots[-1].mrr
+
+ for proj in projections:
+ if proj.model.name == "Current Mix":
+ continue
+ final_mrr = proj.snapshots[-1].mrr
+ delta = final_mrr - baseline_final_mrr
+ delta_pct = (delta / baseline_final_mrr) * 100
+ arrow = "↑" if delta > 0 else "↓"
+ m6_mrr = proj.snapshots[5].mrr if len(proj.snapshots) >= 6 else 0
+ m6_baseline = baseline.snapshots[5].mrr if len(baseline.snapshots) >= 6 else 0
+ m6_delta = m6_mrr - m6_baseline
+ m6_pct = (m6_delta / m6_baseline) * 100 if m6_baseline else 0
+ m6_arrow = "↑" if m6_delta > 0 else "↓"
+
+ print(f" {proj.model.name}:")
+ print(f" Month 6: {m6_arrow} {abs(m6_pct):.1f}% vs. current ({fmt_mrr(m6_delta)} {'more' if m6_delta > 0 else 'less'} MRR)")
+ print(f" Month {SIMULATION_MONTHS}: {arrow} {abs(delta_pct):.1f}% vs. current ({fmt_mrr(delta)} {'more' if delta > 0 else 'less'} MRR)")
+ if proj.model.months_to_steady_state > 4:
+ print(f" ⚠ Model takes {proj.model.months_to_steady_state} months to reach steady state — short-term dip expected.")
+ print()
+
+
+def print_decision_guide(projections: List[ModelProjection]) -> None:
+ print_header("Decision Guide")
+ print(" Choose your growth model based on your constraints:\n")
+ guides = [
+ ("ACV < $5K and fast time-to-value", "PLG-First"),
+ ("ACV > $25K and complex buying process", "Sales-Led Scale"),
+ ("Strong practitioner community exists", "Community-Led"),
+ ("Both SMB self-serve and enterprise buyers", "Hybrid PLS"),
+ ("Uncertain — keep optionality", "Current Mix"),
+ ]
+ for condition, model_name in guides:
+ proj = next((p for p in projections if p.model.name == model_name), None)
+ if proj:
+ final_mrr = proj.snapshots[-1].mrr
+ print(f" If: {condition}")
+ print(f" → Use {model_name} → {fmt_mrr(final_mrr)} MRR at month {SIMULATION_MONTHS}")
+ print()
+
+ print(" Key question before switching models:")
+ print(" 'Do we have 12-18 months of runway to prove the new model")
+ print(" while the current model continues in parallel?'")
+ print(" If no → optimize current model. Don't switch.")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ print_channel_overview()
+
+ projections = [simulate_model(model, SIMULATION_MONTHS) for model in GROWTH_MODELS]
+
+ for proj in projections:
+ print_model_detail(proj)
+
+ print_comparison_table(projections)
+ print_channel_mix_impact(projections)
+ print_decision_guide(projections)
+
+ print("\n" + "=" * 78)
+ print(" Notes:")
+ print(f" Starting MRR: {fmt_mrr(STARTING_MRR)}")
+ print(f" Simulation: {SIMULATION_MONTHS} months")
+ print(f" Churn: {MONTHLY_CHURN_RATE:.1%}/mo ({MONTHLY_CHURN_RATE*12:.0%} annualized)")
+ print(f" Expansion: {EXPANSION_RATE:.1%}/mo of existing MRR")
+ print(f" Gross margin: {GROSS_MARGIN:.0%}")
+ print(" Acceleration rates are estimates — validate against your actuals.")
+ print("=" * 78 + "\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/cmo-advisor/scripts/marketing_budget_modeler.py b/skills/cmo-advisor/scripts/marketing_budget_modeler.py
new file mode 100644
index 00000000..0e9dc8e9
--- /dev/null
+++ b/skills/cmo-advisor/scripts/marketing_budget_modeler.py
@@ -0,0 +1,440 @@
+#!/usr/bin/env python3
+"""
+Marketing Budget Modeler
+------------------------
+Allocates marketing budget across channels based on CAC efficiency and
+target MQL volume. Models conservative / moderate / aggressive scenarios.
+
+Usage:
+ python marketing_budget_modeler.py
+
+Inputs (edit INPUTS section below or extend with argparse):
+ - Annual revenue target (new ARR)
+ - Average selling price (ASP)
+ - Conversion rates by funnel stage
+ - Historical CAC per channel
+ - Channel capacity constraints (max MQLs the channel can realistically produce)
+
+Outputs:
+ - Required MQL volume by channel
+ - Budget allocation per channel per scenario
+ - LTV:CAC and payback period per channel
+ - Summary table across scenarios
+"""
+
+from __future__ import annotations
+import math
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Channel:
+ name: str
+ cac: float # Customer acquisition cost ($)
+ max_mqls_per_month: int # Realistic capacity ceiling (MQLs/month)
+ mql_to_close_rate: float # Combined MQL → closed-won rate (0.0–1.0)
+ payback_months: float # Based on ARPU × gross margin
+ ltv: float # Lifetime value ($)
+ trend: str = "stable" # "improving" | "stable" | "declining"
+
+
+@dataclass
+class FunnelRates:
+ mql_to_sal: float # MQL → Sales Accepted Lead
+ sal_to_sql: float # SAL → Sales Qualified Lead
+ sql_to_opp: float # SQL → Opportunity
+ opp_to_close: float # Opportunity → Closed-Won
+
+ @property
+ def mql_to_close(self) -> float:
+ return self.mql_to_sal * self.sal_to_sql * self.sql_to_opp * self.opp_to_close
+
+
+@dataclass
+class ScenarioResult:
+ name: str
+ total_budget: float
+ channel_budgets: Dict[str, float]
+ channel_mqls: Dict[str, int]
+ projected_customers: int
+ projected_arr: float
+ blended_cac: float
+ notes: List[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# INPUTS — edit these
+# ---------------------------------------------------------------------------
+
+TARGET_NEW_ARR = 3_000_000 # New ARR to generate this year ($)
+ASP_ANNUAL = 18_000 # Average annual contract value ($)
+GROSS_MARGIN = 0.75 # Product gross margin (%)
+ARPU_MONTHLY = ASP_ANNUAL / 12 # Monthly revenue per account
+
+FUNNEL = FunnelRates(
+ mql_to_sal=0.65,
+ sal_to_sql=0.45,
+ sql_to_opp=0.75,
+ opp_to_close=0.27,
+)
+
+# LTV = ARPU_monthly × gross_margin / monthly_churn_rate
+MONTHLY_CHURN = 0.012 # ~14% annual churn
+LTV = (ARPU_MONTHLY * GROSS_MARGIN) / MONTHLY_CHURN
+
+CHANNELS: List[Channel] = [
+ Channel(
+ name="Organic SEO",
+ cac=1_800,
+ max_mqls_per_month=80,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(1_800 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="improving",
+ ),
+ Channel(
+ name="Paid Search",
+ cac=6_200,
+ max_mqls_per_month=60,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(6_200 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="stable",
+ ),
+ Channel(
+ name="Paid Social (LinkedIn)",
+ cac=8_500,
+ max_mqls_per_month=35,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(8_500 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="declining",
+ ),
+ Channel(
+ name="Outbound SDR",
+ cac=5_100,
+ max_mqls_per_month=50,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(5_100 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="stable",
+ ),
+ Channel(
+ name="Events / Field",
+ cac=9_800,
+ max_mqls_per_month=25,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(9_800 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="stable",
+ ),
+ Channel(
+ name="Partner / Channel",
+ cac=3_400,
+ max_mqls_per_month=30,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(3_400 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="improving",
+ ),
+ Channel(
+ name="Content / Inbound",
+ cac=2_600,
+ max_mqls_per_month=45,
+ mql_to_close_rate=FUNNEL.mql_to_close,
+ payback_months=(2_600 / (ARPU_MONTHLY * GROSS_MARGIN)),
+ ltv=LTV,
+ trend="improving",
+ ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Core calculations
+# ---------------------------------------------------------------------------
+
+def customers_needed(target_arr: float, asp: float) -> int:
+ return math.ceil(target_arr / asp)
+
+
+def mqls_needed_total(customers: int, mql_to_close: float) -> int:
+ return math.ceil(customers / mql_to_close)
+
+
+def ltv_to_cac(ltv: float, cac: float) -> float:
+ return ltv / cac if cac > 0 else 0.0
+
+
+def score_channel(ch: Channel) -> float:
+ """
+ Score a channel for budget priority.
+ Higher = more efficient. Used to rank allocation order.
+ Factors: LTV:CAC ratio, trend multiplier, capacity.
+ """
+ ratio = ltv_to_cac(ch.ltv, ch.cac)
+ trend_mult = {"improving": 1.2, "stable": 1.0, "declining": 0.7}.get(ch.trend, 1.0)
+ return ratio * trend_mult
+
+
+def allocate_mqls(
+ channels: List[Channel],
+ total_mqls_needed: int,
+ budget_multiplier: float = 1.0,
+) -> Tuple[Dict[str, int], Dict[str, float]]:
+ """
+ Allocate MQL targets across channels in priority order (best LTV:CAC first).
+ budget_multiplier: 0.7 = conservative, 1.0 = moderate, 1.3 = aggressive.
+ Returns (channel → MQLs, channel → budget).
+ """
+ ranked = sorted(channels, key=score_channel, reverse=True)
+ remaining = total_mqls_needed
+ channel_mqls: Dict[str, int] = {}
+ channel_budget: Dict[str, float] = {}
+
+ for ch in ranked:
+ if remaining <= 0:
+ channel_mqls[ch.name] = 0
+ channel_budget[ch.name] = 0.0
+ continue
+ # Apply capacity ceiling scaled by multiplier (aggressive = push capacity)
+ capacity = int(ch.max_mqls_per_month * 12 * budget_multiplier)
+ allocated = min(remaining, capacity)
+ channel_mqls[ch.name] = allocated
+ channel_budget[ch.name] = allocated * ch.cac
+ remaining -= allocated
+
+ return channel_mqls, channel_budget
+
+
+def build_scenario(
+ name: str,
+ channels: List[Channel],
+ total_mqls: int,
+ multiplier: float,
+ notes: List[str],
+) -> ScenarioResult:
+ channel_mqls, channel_budget = allocate_mqls(channels, total_mqls, multiplier)
+
+ total_budget = sum(channel_budget.values())
+ total_mqls_allocated = sum(channel_mqls.values())
+ projected_customers = math.floor(total_mqls_allocated * FUNNEL.mql_to_close)
+ projected_arr = projected_customers * ASP_ANNUAL
+
+ # Blended CAC = total budget / customers acquired
+ blended_cac = total_budget / projected_customers if projected_customers > 0 else 0.0
+
+ return ScenarioResult(
+ name=name,
+ total_budget=total_budget,
+ channel_budgets=channel_budget,
+ channel_mqls=channel_mqls,
+ projected_customers=projected_customers,
+ projected_arr=projected_arr,
+ blended_cac=blended_cac,
+ notes=notes,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+def fmt_currency(n: float) -> str:
+ if n >= 1_000_000:
+ return f"${n/1_000_000:.2f}M"
+ if n >= 1_000:
+ return f"${n/1_000:.1f}K"
+ return f"${n:.0f}"
+
+
+def fmt_ratio(n: float) -> str:
+ return f"{n:.1f}x"
+
+
+def print_header(title: str) -> None:
+ width = 72
+ print("\n" + "=" * width)
+ print(f" {title}")
+ print("=" * width)
+
+
+def print_channel_table(channels: List[Channel]) -> None:
+ print_header("Channel Analysis — Current State")
+ header = f"{'Channel':<25} {'CAC':>8} {'Payback':>9} {'LTV:CAC':>8} {'Cap/mo':>7} {'Trend':>10}"
+ print(header)
+ print("-" * 72)
+ for ch in sorted(channels, key=score_channel, reverse=True):
+ ratio = ltv_to_cac(ch.ltv, ch.cac)
+ flag = ""
+ if ratio < 1:
+ flag = " ⚠ LOSS"
+ elif ratio >= 6:
+ flag = " ★ STRONG"
+ elif ratio >= 3:
+ flag = " ✓"
+ print(
+ f"{ch.name:<25} {fmt_currency(ch.cac):>8} "
+ f"{ch.payback_months:>7.1f}mo {fmt_ratio(ratio):>8} "
+ f"{ch.max_mqls_per_month:>7} {ch.trend:>10}{flag}"
+ )
+
+
+def print_funnel_summary(customers: int, mqls: int) -> None:
+ print_header("Funnel Requirements")
+ print(f" Target new ARR: {fmt_currency(TARGET_NEW_ARR)}")
+ print(f" Average selling price: {fmt_currency(ASP_ANNUAL)}")
+ print(f" New customers needed: {customers}")
+ print(f" Funnel MQL→Close rate: {FUNNEL.mql_to_close:.1%}")
+ print(f" Total MQLs needed: {mqls}")
+ print(f"\n Funnel stage rates:")
+ print(f" MQL → SAL: {FUNNEL.mql_to_sal:.0%}")
+ print(f" SAL → SQL: {FUNNEL.mql_to_sal * FUNNEL.sal_to_sql:.0%}")
+ print(f" SQL → Opportunity: {FUNNEL.mql_to_sal * FUNNEL.sal_to_sql * FUNNEL.sql_to_opp:.0%}")
+ print(f" Opportunity → Close: {FUNNEL.mql_to_close:.0%}")
+ print(f"\n LTV (estimated): {fmt_currency(LTV)}")
+ print(f" Monthly churn: {MONTHLY_CHURN:.1%} ({MONTHLY_CHURN*12:.0%} annualized)")
+
+
+def print_scenario(result: ScenarioResult, channels: List[Channel]) -> None:
+ print_header(f"Scenario: {result.name}")
+ print(f" Total marketing budget: {fmt_currency(result.total_budget)}")
+ print(f" Projected customers: {result.projected_customers}")
+ print(f" Projected new ARR: {fmt_currency(result.projected_arr)}")
+ print(f" Blended CAC: {fmt_currency(result.blended_cac)}")
+ blended_ltv_cac = LTV / result.blended_cac if result.blended_cac > 0 else 0
+ blended_payback = result.blended_cac / (ARPU_MONTHLY * GROSS_MARGIN)
+ print(f" Blended LTV:CAC: {fmt_ratio(blended_ltv_cac)}", end="")
+ if blended_ltv_cac < 1:
+ print(" ⚠ BELOW BREAK-EVEN")
+ elif blended_ltv_cac < 3:
+ print(" △ MARGINAL")
+ elif blended_ltv_cac >= 3:
+ print(" ✓ HEALTHY")
+ else:
+ print()
+ print(f" Blended payback: {blended_payback:.1f} months")
+ if result.notes:
+ print(f"\n Notes:")
+ for note in result.notes:
+ print(f" • {note}")
+
+ print(f"\n {'Channel':<25} {'MQLs':>6} {'Budget':>10} {'% of Budget':>12} {'LTV:CAC':>8}")
+ print(" " + "-" * 65)
+ for ch in sorted(channels, key=score_channel, reverse=True):
+ mqls = result.channel_mqls.get(ch.name, 0)
+ budget = result.channel_budgets.get(ch.name, 0.0)
+ pct = (budget / result.total_budget * 100) if result.total_budget > 0 else 0
+ ratio = ltv_to_cac(ch.ltv, ch.cac)
+ print(
+ f" {ch.name:<25} {mqls:>6} {fmt_currency(budget):>10} "
+ f"{pct:>11.1f}% {fmt_ratio(ratio):>8}"
+ )
+
+
+def print_scenario_comparison(scenarios: List[ScenarioResult]) -> None:
+ print_header("Scenario Comparison")
+ header = f"{'Scenario':<18} {'Budget':>10} {'Customers':>10} {'ARR':>10} {'Blended CAC':>12} {'LTV:CAC':>8} {'Payback':>9}"
+ print(header)
+ print("-" * 82)
+ for s in scenarios:
+ blended_ltv_cac = LTV / s.blended_cac if s.blended_cac > 0 else 0
+ blended_payback = s.blended_cac / (ARPU_MONTHLY * GROSS_MARGIN)
+ print(
+ f"{s.name:<18} {fmt_currency(s.total_budget):>10} "
+ f"{s.projected_customers:>10} {fmt_currency(s.projected_arr):>10} "
+ f"{fmt_currency(s.blended_cac):>12} {fmt_ratio(blended_ltv_cac):>8} "
+ f"{blended_payback:>7.1f}mo"
+ )
+
+
+def print_recommendations(channels: List[Channel]) -> None:
+ print_header("Channel Recommendations")
+ scale = [ch for ch in channels if score_channel(ch) >= 1.5 and ch.trend in ("improving", "stable")]
+ hold = [ch for ch in channels if 0.8 <= score_channel(ch) < 1.5 or (ch.trend == "stable" and ltv_to_cac(ch.ltv, ch.cac) >= 3)]
+ cut = [ch for ch in channels if ltv_to_cac(ch.ltv, ch.cac) < 2 or ch.trend == "declining"]
+ # Deduplicate
+ hold = [ch for ch in hold if ch not in scale]
+ cut = [ch for ch in cut if ch not in scale and ch not in hold]
+
+ if scale:
+ print(" SCALE (strong LTV:CAC, improving or stable trend):")
+ for ch in scale:
+ print(f" + {ch.name} [LTV:CAC {fmt_ratio(ltv_to_cac(ch.ltv, ch.cac))}, payback {ch.payback_months:.0f}mo]")
+ if hold:
+ print(" HOLD (monitor — adequate but not outstanding):")
+ for ch in hold:
+ print(f" = {ch.name} [LTV:CAC {fmt_ratio(ltv_to_cac(ch.ltv, ch.cac))}, trend: {ch.trend}]")
+ if cut:
+ print(" CUT or REDUCE (poor LTV:CAC or declining):")
+ for ch in cut:
+ print(f" - {ch.name} [LTV:CAC {fmt_ratio(ltv_to_cac(ch.ltv, ch.cac))}, trend: {ch.trend}]")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ customers = customers_needed(TARGET_NEW_ARR, ASP_ANNUAL)
+ total_mqls = mqls_needed_total(customers, FUNNEL.mql_to_close)
+
+ print_channel_table(CHANNELS)
+ print_funnel_summary(customers, total_mqls)
+
+ scenarios = [
+ build_scenario(
+ name="Conservative",
+ channels=CHANNELS,
+ total_mqls=total_mqls,
+ multiplier=0.7,
+ notes=[
+ "Prioritizes lowest CAC channels only.",
+ "May not reach MQL target — expect ~70% of goal.",
+ "Best for capital-constrained orgs or short runway.",
+ ],
+ ),
+ build_scenario(
+ name="Moderate",
+ channels=CHANNELS,
+ total_mqls=total_mqls,
+ multiplier=1.0,
+ notes=[
+ "Balanced allocation — efficiency-first but full MQL target.",
+ "Recommended baseline. Revisit Q2 based on actuals.",
+ ],
+ ),
+ build_scenario(
+ name="Aggressive",
+ channels=CHANNELS,
+ total_mqls=total_mqls,
+ multiplier=1.4,
+ notes=[
+ "Pushes all channels toward capacity ceiling.",
+ "Higher spend on lower-efficiency channels to hit volume.",
+ "Requires > 18-month runway to justify payback period.",
+ ],
+ ),
+ ]
+
+ for scenario in scenarios:
+ print_scenario(scenario, CHANNELS)
+
+ print_scenario_comparison(scenarios)
+ print_recommendations(CHANNELS)
+
+ print("\n" + "=" * 72)
+ print(" Key questions before finalizing budget:")
+ print(" 1. What is the payback period the CFO/board will accept?")
+ print(" 2. Is CAC for declining-trend channels actually recoverable?")
+ print(" 3. Does the moderate scenario require sales headcount increase?")
+ print(" 4. Which channels have capacity to absorb 20% more spend?")
+ print("=" * 72 + "\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/code-reviewer-2/SKILL.md b/skills/code-reviewer-2/SKILL.md
new file mode 100644
index 00000000..3328ac19
--- /dev/null
+++ b/skills/code-reviewer-2/SKILL.md
@@ -0,0 +1,177 @@
+---
+name: code-reviewer
+description: Code review automation for TypeScript, JavaScript, Python, Go, Swift, Kotlin. Analyzes PRs for complexity and risk, checks code quality for SOLID violations and code smells, generates review reports. Use when reviewing pull requests, analyzing code quality, identifying issues, generating review checklists.
+---
+
+# Code Reviewer
+
+Automated code review tools for analyzing pull requests, detecting code quality issues, and generating review reports.
+
+---
+
+## Table of Contents
+
+- [Tools](#tools)
+ - [PR Analyzer](#pr-analyzer)
+ - [Code Quality Checker](#code-quality-checker)
+ - [Review Report Generator](#review-report-generator)
+- [Reference Guides](#reference-guides)
+- [Languages Supported](#languages-supported)
+
+---
+
+## Tools
+
+### PR Analyzer
+
+Analyzes git diff between branches to assess review complexity and identify risks.
+
+```bash
+# Analyze current branch against main
+python scripts/pr_analyzer.py /path/to/repo
+
+# Compare specific branches
+python scripts/pr_analyzer.py . --base main --head feature-branch
+
+# JSON output for integration
+python scripts/pr_analyzer.py /path/to/repo --json
+```
+
+**What it detects:**
+- Hardcoded secrets (passwords, API keys, tokens)
+- SQL injection patterns (string concatenation in queries)
+- Debug statements (debugger, console.log)
+- ESLint rule disabling
+- TypeScript `any` types
+- TODO/FIXME comments
+
+**Output includes:**
+- Complexity score (1-10)
+- Risk categorization (critical, high, medium, low)
+- File prioritization for review order
+- Commit message validation
+
+---
+
+### Code Quality Checker
+
+Analyzes source code for structural issues, code smells, and SOLID violations.
+
+```bash
+# Analyze a directory
+python scripts/code_quality_checker.py /path/to/code
+
+# Analyze specific language
+python scripts/code_quality_checker.py . --language python
+
+# JSON output
+python scripts/code_quality_checker.py /path/to/code --json
+```
+
+**What it detects:**
+- Long functions (>50 lines)
+- Large files (>500 lines)
+- God classes (>20 methods)
+- Deep nesting (>4 levels)
+- Too many parameters (>5)
+- High cyclomatic complexity
+- Missing error handling
+- Unused imports
+- Magic numbers
+
+**Thresholds:**
+
+| Issue | Threshold |
+|-------|-----------|
+| Long function | >50 lines |
+| Large file | >500 lines |
+| God class | >20 methods |
+| Too many params | >5 |
+| Deep nesting | >4 levels |
+| High complexity | >10 branches |
+
+---
+
+### Review Report Generator
+
+Combines PR analysis and code quality findings into structured review reports.
+
+```bash
+# Generate report for current repo
+python scripts/review_report_generator.py /path/to/repo
+
+# Markdown output
+python scripts/review_report_generator.py . --format markdown --output review.md
+
+# Use pre-computed analyses
+python scripts/review_report_generator.py . \
+ --pr-analysis pr_results.json \
+ --quality-analysis quality_results.json
+```
+
+**Report includes:**
+- Review verdict (approve, request changes, block)
+- Score (0-100)
+- Prioritized action items
+- Issue summary by severity
+- Suggested review order
+
+**Verdicts:**
+
+| Score | Verdict |
+|-------|---------|
+| 90+ with no high issues | Approve |
+| 75+ with ≤2 high issues | Approve with suggestions |
+| 50-74 | Request changes |
+| <50 or critical issues | Block |
+
+---
+
+## Reference Guides
+
+### Code Review Checklist
+`references/code_review_checklist.md`
+
+Systematic checklists covering:
+- Pre-review checks (build, tests, PR hygiene)
+- Correctness (logic, data handling, error handling)
+- Security (input validation, injection prevention)
+- Performance (efficiency, caching, scalability)
+- Maintainability (code quality, naming, structure)
+- Testing (coverage, quality, mocking)
+- Language-specific checks
+
+### Coding Standards
+`references/coding_standards.md`
+
+Language-specific standards for:
+- TypeScript (type annotations, null safety, async/await)
+- JavaScript (declarations, patterns, modules)
+- Python (type hints, exceptions, class design)
+- Go (error handling, structs, concurrency)
+- Swift (optionals, protocols, errors)
+- Kotlin (null safety, data classes, coroutines)
+
+### Common Antipatterns
+`references/common_antipatterns.md`
+
+Antipattern catalog with examples and fixes:
+- Structural (god class, long method, deep nesting)
+- Logic (boolean blindness, stringly typed code)
+- Security (SQL injection, hardcoded credentials)
+- Performance (N+1 queries, unbounded collections)
+- Testing (duplication, testing implementation)
+- Async (floating promises, callback hell)
+
+---
+
+## Languages Supported
+
+| Language | Extensions |
+|----------|------------|
+| Python | `.py` |
+| TypeScript | `.ts`, `.tsx` |
+| JavaScript | `.js`, `.jsx`, `.mjs` |
+| Go | `.go` |
+| Swift | `.swift` |
+| Kotlin | `.kt`, `.kts` |
diff --git a/skills/code-reviewer-2/_meta.json b/skills/code-reviewer-2/_meta.json
new file mode 100644
index 00000000..385c5883
--- /dev/null
+++ b/skills/code-reviewer-2/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "code-reviewer-2",
+ "displayName": "Senior Code Reviewer",
+ "latest": {
+ "version": "0.1.0",
+ "publishedAt": 1772590557457,
+ "commit": "https://github.com/openclaw/skills/commit/1ddbcee2e740980f80be3a194e62d97de93a0b86"
+ },
+ "history": []
+}
diff --git a/skills/code-reviewer-2/references/code_review_checklist.md b/skills/code-reviewer-2/references/code_review_checklist.md
new file mode 100644
index 00000000..b7bd0867
--- /dev/null
+++ b/skills/code-reviewer-2/references/code_review_checklist.md
@@ -0,0 +1,270 @@
+# Code Review Checklist
+
+Structured checklists for systematic code review across different aspects.
+
+---
+
+## Table of Contents
+
+- [Pre-Review Checks](#pre-review-checks)
+- [Correctness](#correctness)
+- [Security](#security)
+- [Performance](#performance)
+- [Maintainability](#maintainability)
+- [Testing](#testing)
+- [Documentation](#documentation)
+- [Language-Specific Checks](#language-specific-checks)
+
+---
+
+## Pre-Review Checks
+
+Before diving into code, verify these basics:
+
+### Build and Tests
+- [ ] Code compiles without errors
+- [ ] All existing tests pass
+- [ ] New tests are included for new functionality
+- [ ] No unintended files included (build artifacts, IDE configs)
+
+### PR Hygiene
+- [ ] PR has clear title and description
+- [ ] Changes are scoped appropriately (not too large)
+- [ ] Commits follow conventional commit format
+- [ ] Branch is up to date with base branch
+
+### Scope Verification
+- [ ] Changes match the stated purpose
+- [ ] No unrelated changes bundled in
+- [ ] Breaking changes are documented
+- [ ] Migration path provided if needed
+
+---
+
+## Correctness
+
+### Logic
+- [ ] Algorithm implements requirements correctly
+- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] Off-by-one errors checked
+- [ ] Correct operators used (== vs ===, & vs &&)
+- [ ] Loop termination conditions correct
+- [ ] Recursion has proper base cases
+
+### Data Handling
+- [ ] Data types appropriate for the use case
+- [ ] Numeric overflow/underflow considered
+- [ ] Date/time handling accounts for timezones
+- [ ] Unicode and internationalization handled
+- [ ] Data validation at entry points
+
+### State Management
+- [ ] State transitions are valid
+- [ ] Race conditions addressed
+- [ ] Concurrent access handled correctly
+- [ ] State cleanup on errors/exit
+
+### Error Handling
+- [ ] Errors caught at appropriate levels
+- [ ] Error messages are actionable
+- [ ] Errors don't expose sensitive information
+- [ ] Recovery or graceful degradation implemented
+- [ ] Resources cleaned up in error paths
+
+---
+
+## Security
+
+### Input Validation
+- [ ] All user input validated and sanitized
+- [ ] Input length limits enforced
+- [ ] File uploads validated (type, size, content)
+- [ ] URL parameters validated
+
+### Injection Prevention
+- [ ] SQL queries parameterized
+- [ ] Command execution uses safe APIs
+- [ ] HTML output escaped to prevent XSS
+- [ ] LDAP queries properly escaped
+- [ ] XML parsing disables external entities
+
+### Authentication & Authorization
+- [ ] Authentication required for protected resources
+- [ ] Authorization checked before operations
+- [ ] Session management secure
+- [ ] Password handling follows best practices
+- [ ] Token expiration implemented
+
+### Data Protection
+- [ ] Sensitive data encrypted at rest
+- [ ] Sensitive data encrypted in transit
+- [ ] PII handled according to policy
+- [ ] Secrets not hardcoded
+- [ ] Logs don't contain sensitive data
+
+### API Security
+- [ ] Rate limiting implemented
+- [ ] CORS configured correctly
+- [ ] CSRF protection in place
+- [ ] API keys/tokens secured
+- [ ] Endpoints use HTTPS
+
+---
+
+## Performance
+
+### Efficiency
+- [ ] Appropriate data structures used
+- [ ] Algorithms have acceptable complexity
+- [ ] Database queries are optimized
+- [ ] N+1 query problems avoided
+- [ ] Indexes used where beneficial
+
+### Resource Usage
+- [ ] Memory usage bounded
+- [ ] No memory leaks
+- [ ] File handles properly closed
+- [ ] Database connections pooled
+- [ ] Network calls minimized
+
+### Caching
+- [ ] Appropriate caching strategy
+- [ ] Cache invalidation handled
+- [ ] Cache keys are unique and predictable
+- [ ] TTL values appropriate
+
+### Scalability
+- [ ] Horizontal scaling considered
+- [ ] Bottlenecks identified
+- [ ] Async processing for long operations
+- [ ] Batch operations where appropriate
+
+---
+
+## Maintainability
+
+### Code Quality
+- [ ] Functions/methods have single responsibility
+- [ ] Classes follow SOLID principles
+- [ ] Code is DRY (Don't Repeat Yourself)
+- [ ] No dead code or commented-out code
+- [ ] Magic numbers replaced with constants
+
+### Naming
+- [ ] Names are descriptive and consistent
+- [ ] Naming follows project conventions
+- [ ] No abbreviations that obscure meaning
+- [ ] Boolean variables/functions have is/has/can prefix
+
+### Structure
+- [ ] Functions are appropriately sized (<50 lines preferred)
+- [ ] Nesting depth is reasonable (<4 levels)
+- [ ] Related code is grouped together
+- [ ] Dependencies are minimal and explicit
+
+### Readability
+- [ ] Code is self-documenting where possible
+- [ ] Complex logic has explanatory comments
+- [ ] Formatting is consistent
+- [ ] No overly clever or obscure code
+
+---
+
+## Testing
+
+### Coverage
+- [ ] New code has unit tests
+- [ ] Critical paths have integration tests
+- [ ] Edge cases are tested
+- [ ] Error conditions are tested
+
+### Quality
+- [ ] Tests are independent
+- [ ] Tests have clear assertions
+- [ ] Test names describe what is tested
+- [ ] Tests don't depend on external state
+
+### Mocking
+- [ ] External dependencies are mocked
+- [ ] Mocks are realistic
+- [ ] Mock setup is not excessive
+
+---
+
+## Documentation
+
+### Code Documentation
+- [ ] Public APIs are documented
+- [ ] Complex algorithms explained
+- [ ] Non-obvious decisions documented
+- [ ] TODO/FIXME comments have context
+
+### External Documentation
+- [ ] README updated if needed
+- [ ] API documentation updated
+- [ ] Changelog updated
+- [ ] Migration guides provided
+
+---
+
+## Language-Specific Checks
+
+### TypeScript/JavaScript
+- [ ] Types are explicit (avoid `any`)
+- [ ] Null checks present (`?.`, `??`)
+- [ ] Async/await errors handled
+- [ ] No floating promises
+- [ ] Memory leaks from closures checked
+
+### Python
+- [ ] Type hints used for public APIs
+- [ ] Context managers for resources (`with` statements)
+- [ ] Exception handling is specific (not bare `except`)
+- [ ] No mutable default arguments
+- [ ] List comprehensions used appropriately
+
+### Go
+- [ ] Errors checked and handled
+- [ ] Goroutine leaks prevented
+- [ ] Context propagation correct
+- [ ] Defer statements in right order
+- [ ] Interfaces minimal
+
+### Swift
+- [ ] Optionals handled safely
+- [ ] Memory management correct (weak/unowned)
+- [ ] Error handling uses Result or throws
+- [ ] Access control appropriate
+- [ ] Codable implementation correct
+
+### Kotlin
+- [ ] Null safety leveraged
+- [ ] Coroutine cancellation handled
+- [ ] Data classes used appropriately
+- [ ] Extension functions don't obscure behavior
+- [ ] Sealed classes for state
+
+---
+
+## Review Process Tips
+
+### Before Approving
+1. Verify all critical checks passed
+2. Confirm tests are adequate
+3. Consider deployment impact
+4. Check for any security concerns
+5. Ensure documentation is updated
+
+### Providing Feedback
+- Be specific about issues
+- Explain why something is problematic
+- Suggest alternatives when possible
+- Distinguish blockers from suggestions
+- Acknowledge good patterns
+
+### When to Block
+- Security vulnerabilities present
+- Critical logic errors
+- No tests for risky changes
+- Breaking changes without migration
+- Significant performance regressions
diff --git a/skills/code-reviewer-2/references/coding_standards.md b/skills/code-reviewer-2/references/coding_standards.md
new file mode 100644
index 00000000..9fbc6a06
--- /dev/null
+++ b/skills/code-reviewer-2/references/coding_standards.md
@@ -0,0 +1,555 @@
+# Coding Standards
+
+Language-specific coding standards and conventions for code review.
+
+---
+
+## Table of Contents
+
+- [Universal Principles](#universal-principles)
+- [TypeScript Standards](#typescript-standards)
+- [JavaScript Standards](#javascript-standards)
+- [Python Standards](#python-standards)
+- [Go Standards](#go-standards)
+- [Swift Standards](#swift-standards)
+- [Kotlin Standards](#kotlin-standards)
+
+---
+
+## Universal Principles
+
+These apply across all languages.
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Variables | camelCase (JS/TS), snake_case (Python/Go) | `userName`, `user_name` |
+| Constants | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| Functions | camelCase (JS/TS), snake_case (Python) | `getUserById`, `get_user_by_id` |
+| Classes | PascalCase | `UserRepository` |
+| Interfaces | PascalCase, optionally prefixed | `IUserService` or `UserService` |
+| Private members | Prefix with underscore or use access modifiers | `_internalState` |
+
+### Function Design
+
+```
+Good functions:
+- Do one thing well
+- Have descriptive names (verb + noun)
+- Take 3 or fewer parameters
+- Return early for error cases
+- Stay under 50 lines
+```
+
+### Error Handling
+
+```
+Good error handling:
+- Catch specific errors, not generic exceptions
+- Log with context (what, where, why)
+- Clean up resources in error paths
+- Don't swallow errors silently
+- Provide actionable error messages
+```
+
+---
+
+## TypeScript Standards
+
+### Type Annotations
+
+```typescript
+// Avoid 'any' - use unknown for truly unknown types
+function processData(data: unknown): ProcessedResult {
+ if (isValidData(data)) {
+ return transform(data);
+ }
+ throw new Error('Invalid data format');
+}
+
+// Use explicit return types for public APIs
+export function calculateTotal(items: CartItem[]): number {
+ return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// Use type guards for runtime checks
+function isUser(obj: unknown): obj is User {
+ return (
+ typeof obj === 'object' &&
+ obj !== null &&
+ 'id' in obj &&
+ 'email' in obj
+ );
+}
+```
+
+### Null Safety
+
+```typescript
+// Use optional chaining and nullish coalescing
+const userName = user?.profile?.name ?? 'Anonymous';
+
+// Be explicit about nullable types
+interface Config {
+ timeout: number;
+ retries?: number; // Optional
+ fallbackUrl: string | null; // Explicitly nullable
+}
+
+// Use assertion functions for validation
+function assertDefined(value: T | null | undefined): asserts value is T {
+ if (value === null || value === undefined) {
+ throw new Error('Value is not defined');
+ }
+}
+```
+
+### Async/Await
+
+```typescript
+// Always handle errors in async functions
+async function fetchUser(id: string): Promise {
+ try {
+ const response = await api.get(`/users/${id}`);
+ return response.data;
+ } catch (error) {
+ logger.error('Failed to fetch user', { id, error });
+ throw new UserFetchError(id, error);
+ }
+}
+
+// Use Promise.all for parallel operations
+async function loadDashboard(userId: string): Promise {
+ const [profile, stats, notifications] = await Promise.all([
+ fetchProfile(userId),
+ fetchStats(userId),
+ fetchNotifications(userId)
+ ]);
+ return { profile, stats, notifications };
+}
+```
+
+### React/Component Standards
+
+```typescript
+// Use explicit prop types
+interface ButtonProps {
+ label: string;
+ onClick: () => void;
+ variant?: 'primary' | 'secondary';
+ disabled?: boolean;
+}
+
+// Prefer functional components with hooks
+function Button({ label, onClick, variant = 'primary', disabled = false }: ButtonProps) {
+ return (
+
+ );
+}
+
+// Use custom hooks for reusable logic
+function useDebounce(value: T, delay: number): T {
+ const [debouncedValue, setDebouncedValue] = useState(value);
+
+ useEffect(() => {
+ const timer = setTimeout(() => setDebouncedValue(value), delay);
+ return () => clearTimeout(timer);
+ }, [value, delay]);
+
+ return debouncedValue;
+}
+```
+
+---
+
+## JavaScript Standards
+
+### Variable Declarations
+
+```javascript
+// Use const by default, let when reassignment needed
+const MAX_ITEMS = 100;
+let currentCount = 0;
+
+// Never use var
+// var is function-scoped and hoisted, leading to bugs
+```
+
+### Object and Array Patterns
+
+```javascript
+// Use object destructuring
+const { name, email, role = 'user' } = user;
+
+// Use spread for immutable updates
+const updatedUser = { ...user, lastLogin: new Date() };
+const updatedList = [...items, newItem];
+
+// Use array methods over loops
+const activeUsers = users.filter(u => u.isActive);
+const emails = users.map(u => u.email);
+const total = orders.reduce((sum, o) => sum + o.amount, 0);
+```
+
+### Module Patterns
+
+```javascript
+// Use named exports for utilities
+export function formatDate(date) { ... }
+export function parseDate(str) { ... }
+
+// Use default export for main component/class
+export default class UserService { ... }
+
+// Group related exports
+export { formatDate, parseDate, isValidDate } from './dateUtils';
+```
+
+---
+
+## Python Standards
+
+### Type Hints (PEP 484)
+
+```python
+from typing import Optional, List, Dict, Union
+
+def get_user(user_id: int) -> Optional[User]:
+ """Fetch user by ID, returns None if not found."""
+ return db.query(User).filter(User.id == user_id).first()
+
+def process_items(items: List[str]) -> Dict[str, int]:
+ """Count occurrences of each item."""
+ return {item: items.count(item) for item in set(items)}
+
+def send_notification(
+ user: User,
+ message: str,
+ *,
+ priority: str = "normal",
+ channels: List[str] = None
+) -> bool:
+ """Send notification to user via specified channels."""
+ channels = channels or ["email"]
+ # Implementation
+```
+
+### Exception Handling
+
+```python
+# Catch specific exceptions
+try:
+ result = api_client.fetch_data(endpoint)
+except ConnectionError as e:
+ logger.warning(f"Connection failed: {e}")
+ return cached_data
+except TimeoutError as e:
+ logger.error(f"Request timed out: {e}")
+ raise ServiceUnavailableError() from e
+
+# Use context managers for resources
+with open(filepath, 'r') as f:
+ data = json.load(f)
+
+# Custom exceptions should be informative
+class ValidationError(Exception):
+ def __init__(self, field: str, message: str):
+ self.field = field
+ self.message = message
+ super().__init__(f"{field}: {message}")
+```
+
+### Class Design
+
+```python
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+
+# Use dataclasses for data containers
+@dataclass
+class UserDTO:
+ id: int
+ email: str
+ name: str
+ is_active: bool = True
+
+# Use ABC for interfaces
+class Repository(ABC):
+ @abstractmethod
+ def find_by_id(self, id: int) -> Optional[Entity]:
+ pass
+
+ @abstractmethod
+ def save(self, entity: Entity) -> Entity:
+ pass
+
+# Use properties for computed attributes
+class Order:
+ def __init__(self, items: List[OrderItem]):
+ self._items = items
+
+ @property
+ def total(self) -> Decimal:
+ return sum(item.price * item.quantity for item in self._items)
+```
+
+---
+
+## Go Standards
+
+### Error Handling
+
+```go
+// Always check errors
+file, err := os.Open(filename)
+if err != nil {
+ return fmt.Errorf("failed to open %s: %w", filename, err)
+}
+defer file.Close()
+
+// Use custom error types for specific cases
+type ValidationError struct {
+ Field string
+ Message string
+}
+
+func (e *ValidationError) Error() string {
+ return fmt.Sprintf("%s: %s", e.Field, e.Message)
+}
+
+// Wrap errors with context
+if err := db.Query(query); err != nil {
+ return fmt.Errorf("query failed for user %d: %w", userID, err)
+}
+```
+
+### Struct Design
+
+```go
+// Use unexported fields with exported methods
+type UserService struct {
+ repo UserRepository
+ cache Cache
+ logger Logger
+}
+
+// Constructor functions for initialization
+func NewUserService(repo UserRepository, cache Cache, logger Logger) *UserService {
+ return &UserService{
+ repo: repo,
+ cache: cache,
+ logger: logger,
+ }
+}
+
+// Keep interfaces small
+type Reader interface {
+ Read(p []byte) (n int, err error)
+}
+
+type Writer interface {
+ Write(p []byte) (n int, err error)
+}
+```
+
+### Concurrency
+
+```go
+// Use context for cancellation
+func fetchData(ctx context.Context, url string) ([]byte, error) {
+ req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+ if err != nil {
+ return nil, err
+ }
+ // ...
+}
+
+// Use channels for communication
+func worker(jobs <-chan Job, results chan<- Result) {
+ for job := range jobs {
+ result := process(job)
+ results <- result
+ }
+}
+
+// Use sync.WaitGroup for coordination
+var wg sync.WaitGroup
+for _, item := range items {
+ wg.Add(1)
+ go func(i Item) {
+ defer wg.Done()
+ processItem(i)
+ }(item)
+}
+wg.Wait()
+```
+
+---
+
+## Swift Standards
+
+### Optionals
+
+```swift
+// Use optional binding
+if let user = fetchUser(id: userId) {
+ displayProfile(user)
+}
+
+// Use guard for early exit
+guard let data = response.data else {
+ throw NetworkError.noData
+}
+
+// Use nil coalescing for defaults
+let displayName = user.nickname ?? user.email
+
+// Avoid force unwrapping except in tests
+// BAD: let name = user.name!
+// GOOD: guard let name = user.name else { return }
+```
+
+### Protocol-Oriented Design
+
+```swift
+// Define protocols with minimal requirements
+protocol Identifiable {
+ var id: String { get }
+}
+
+protocol Persistable: Identifiable {
+ func save() throws
+ static func find(by id: String) -> Self?
+}
+
+// Use protocol extensions for default implementations
+extension Persistable {
+ func save() throws {
+ try Storage.shared.save(self)
+ }
+}
+
+// Prefer composition over inheritance
+struct User: Identifiable, Codable {
+ let id: String
+ var name: String
+ var email: String
+}
+```
+
+### Error Handling
+
+```swift
+// Define domain-specific errors
+enum AuthError: Error {
+ case invalidCredentials
+ case tokenExpired
+ case networkFailure(underlying: Error)
+}
+
+// Use Result type for async operations
+func authenticate(
+ email: String,
+ password: String,
+ completion: @escaping (Result) -> Void
+)
+
+// Use throws for synchronous operations
+func validate(_ input: String) throws -> ValidatedInput {
+ guard !input.isEmpty else {
+ throw ValidationError.emptyInput
+ }
+ return ValidatedInput(value: input)
+}
+```
+
+---
+
+## Kotlin Standards
+
+### Null Safety
+
+```kotlin
+// Use nullable types explicitly
+fun findUser(id: Int): User? {
+ return userRepository.find(id)
+}
+
+// Use safe calls and elvis operator
+val name = user?.profile?.name ?: "Unknown"
+
+// Use let for null checks with side effects
+user?.let { activeUser ->
+ sendWelcomeEmail(activeUser.email)
+ logActivity(activeUser.id)
+}
+
+// Use require/check for validation
+fun processPayment(amount: Double) {
+ require(amount > 0) { "Amount must be positive: $amount" }
+ // Process
+}
+```
+
+### Data Classes and Sealed Classes
+
+```kotlin
+// Use data classes for DTOs
+data class UserDTO(
+ val id: Int,
+ val email: String,
+ val name: String,
+ val isActive: Boolean = true
+)
+
+// Use sealed classes for state
+sealed class Result {
+ data class Success(val data: T) : Result()
+ data class Error(val message: String, val cause: Throwable? = null) : Result()
+ object Loading : Result()
+}
+
+// Pattern matching with when
+fun handleResult(result: Result) = when (result) {
+ is Result.Success -> showUser(result.data)
+ is Result.Error -> showError(result.message)
+ Result.Loading -> showLoading()
+}
+```
+
+### Coroutines
+
+```kotlin
+// Use structured concurrency
+suspend fun loadDashboard(): Dashboard = coroutineScope {
+ val profile = async { fetchProfile() }
+ val stats = async { fetchStats() }
+ val notifications = async { fetchNotifications() }
+
+ Dashboard(
+ profile = profile.await(),
+ stats = stats.await(),
+ notifications = notifications.await()
+ )
+}
+
+// Handle cancellation
+suspend fun fetchWithRetry(url: String): Response {
+ repeat(3) { attempt ->
+ try {
+ return httpClient.get(url)
+ } catch (e: IOException) {
+ if (attempt == 2) throw e
+ delay(1000L * (attempt + 1))
+ }
+ }
+ throw IllegalStateException("Unreachable")
+}
+```
diff --git a/skills/code-reviewer-2/references/common_antipatterns.md b/skills/code-reviewer-2/references/common_antipatterns.md
new file mode 100644
index 00000000..26045452
--- /dev/null
+++ b/skills/code-reviewer-2/references/common_antipatterns.md
@@ -0,0 +1,739 @@
+# Common Antipatterns
+
+Code antipatterns to identify during review, with examples and fixes.
+
+---
+
+## Table of Contents
+
+- [Structural Antipatterns](#structural-antipatterns)
+- [Logic Antipatterns](#logic-antipatterns)
+- [Security Antipatterns](#security-antipatterns)
+- [Performance Antipatterns](#performance-antipatterns)
+- [Testing Antipatterns](#testing-antipatterns)
+- [Async Antipatterns](#async-antipatterns)
+
+---
+
+## Structural Antipatterns
+
+### God Class
+
+A class that does too much and knows too much.
+
+```typescript
+// BAD: God class handling everything
+class UserManager {
+ createUser(data: UserData) { ... }
+ updateUser(id: string, data: UserData) { ... }
+ deleteUser(id: string) { ... }
+ sendEmail(userId: string, content: string) { ... }
+ generateReport(userId: string) { ... }
+ validatePassword(password: string) { ... }
+ hashPassword(password: string) { ... }
+ uploadAvatar(userId: string, file: File) { ... }
+ resizeImage(file: File) { ... }
+ logActivity(userId: string, action: string) { ... }
+ // 50 more methods...
+}
+
+// GOOD: Single responsibility classes
+class UserRepository {
+ create(data: UserData): User { ... }
+ update(id: string, data: Partial): User { ... }
+ delete(id: string): void { ... }
+}
+
+class EmailService {
+ send(to: string, content: string): void { ... }
+}
+
+class PasswordService {
+ validate(password: string): ValidationResult { ... }
+ hash(password: string): string { ... }
+}
+```
+
+**Detection:** Class has >20 methods, >500 lines, or handles unrelated concerns.
+
+---
+
+### Long Method
+
+Functions that do too much and are hard to understand.
+
+```python
+# BAD: Long method doing everything
+def process_order(order_data):
+ # Validate order (20 lines)
+ if not order_data.get('items'):
+ raise ValueError('No items')
+ if not order_data.get('customer_id'):
+ raise ValueError('No customer')
+ # ... more validation
+
+ # Calculate totals (30 lines)
+ subtotal = 0
+ for item in order_data['items']:
+ price = get_product_price(item['product_id'])
+ subtotal += price * item['quantity']
+ # ... tax calculation, discounts
+
+ # Process payment (40 lines)
+ payment_result = payment_gateway.charge(...)
+ # ... handle payment errors
+
+ # Create order record (20 lines)
+ order = Order.create(...)
+
+ # Send notifications (20 lines)
+ send_order_confirmation(...)
+ notify_warehouse(...)
+
+ return order
+
+# GOOD: Composed of focused functions
+def process_order(order_data):
+ validate_order(order_data)
+ totals = calculate_order_totals(order_data)
+ payment = process_payment(order_data['customer_id'], totals)
+ order = create_order_record(order_data, totals, payment)
+ send_order_notifications(order)
+ return order
+```
+
+**Detection:** Function >50 lines or requires scrolling to read.
+
+---
+
+### Deep Nesting
+
+Excessive indentation making code hard to follow.
+
+```javascript
+// BAD: Deep nesting
+function processData(data) {
+ if (data) {
+ if (data.items) {
+ if (data.items.length > 0) {
+ for (const item of data.items) {
+ if (item.isValid) {
+ if (item.type === 'premium') {
+ if (item.price > 100) {
+ // Finally do something
+ processItem(item);
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
+// GOOD: Early returns and guard clauses
+function processData(data) {
+ if (!data?.items?.length) {
+ return;
+ }
+
+ const premiumItems = data.items.filter(
+ item => item.isValid && item.type === 'premium' && item.price > 100
+ );
+
+ premiumItems.forEach(processItem);
+}
+```
+
+**Detection:** Indentation >4 levels deep.
+
+---
+
+### Magic Numbers and Strings
+
+Hard-coded values without explanation.
+
+```go
+// BAD: Magic numbers
+func calculateDiscount(total float64, userType int) float64 {
+ if userType == 1 {
+ return total * 0.15
+ } else if userType == 2 {
+ return total * 0.25
+ }
+ return total * 0.05
+}
+
+// GOOD: Named constants
+const (
+ UserTypeRegular = 1
+ UserTypePremium = 2
+
+ DiscountRegular = 0.05
+ DiscountStandard = 0.15
+ DiscountPremium = 0.25
+)
+
+func calculateDiscount(total float64, userType int) float64 {
+ switch userType {
+ case UserTypePremium:
+ return total * DiscountPremium
+ case UserTypeRegular:
+ return total * DiscountStandard
+ default:
+ return total * DiscountRegular
+ }
+}
+```
+
+**Detection:** Literal numbers (except 0, 1) or repeated string literals.
+
+---
+
+### Primitive Obsession
+
+Using primitives instead of small objects.
+
+```typescript
+// BAD: Primitives everywhere
+function createUser(
+ name: string,
+ email: string,
+ phone: string,
+ street: string,
+ city: string,
+ zipCode: string,
+ country: string
+): User { ... }
+
+// GOOD: Value objects
+interface Address {
+ street: string;
+ city: string;
+ zipCode: string;
+ country: string;
+}
+
+interface ContactInfo {
+ email: string;
+ phone: string;
+}
+
+function createUser(
+ name: string,
+ contact: ContactInfo,
+ address: Address
+): User { ... }
+```
+
+**Detection:** Functions with >4 parameters of same type, or related primitives always passed together.
+
+---
+
+## Logic Antipatterns
+
+### Boolean Blindness
+
+Passing booleans that make code unreadable at call sites.
+
+```swift
+// BAD: What do these booleans mean?
+user.configure(true, false, true, false)
+
+// GOOD: Named parameters or option objects
+user.configure(
+ sendWelcomeEmail: true,
+ requireVerification: false,
+ enableNotifications: true,
+ isAdmin: false
+)
+
+// Or use an options struct
+struct UserConfiguration {
+ var sendWelcomeEmail: Bool = true
+ var requireVerification: Bool = false
+ var enableNotifications: Bool = true
+ var isAdmin: Bool = false
+}
+
+user.configure(UserConfiguration())
+```
+
+**Detection:** Function calls with multiple boolean literals.
+
+---
+
+### Null Returns for Collections
+
+Returning null instead of empty collections.
+
+```kotlin
+// BAD: Returning null
+fun findUsersByRole(role: String): List? {
+ val users = repository.findByRole(role)
+ return if (users.isEmpty()) null else users
+}
+
+// Caller must handle null
+val users = findUsersByRole("admin")
+if (users != null) {
+ users.forEach { ... }
+}
+
+// GOOD: Return empty collection
+fun findUsersByRole(role: String): List {
+ return repository.findByRole(role)
+}
+
+// Caller can iterate directly
+findUsersByRole("admin").forEach { ... }
+```
+
+**Detection:** Functions returning nullable collections.
+
+---
+
+### Stringly Typed Code
+
+Using strings where enums or types should be used.
+
+```python
+# BAD: String-based logic
+def handle_event(event_type: str, data: dict):
+ if event_type == "user_created":
+ handle_user_created(data)
+ elif event_type == "user_updated":
+ handle_user_updated(data)
+ elif event_type == "user_dleted": # Typo won't be caught
+ handle_user_deleted(data)
+
+# GOOD: Enum-based
+from enum import Enum
+
+class EventType(Enum):
+ USER_CREATED = "user_created"
+ USER_UPDATED = "user_updated"
+ USER_DELETED = "user_deleted"
+
+def handle_event(event_type: EventType, data: dict):
+ handlers = {
+ EventType.USER_CREATED: handle_user_created,
+ EventType.USER_UPDATED: handle_user_updated,
+ EventType.USER_DELETED: handle_user_deleted,
+ }
+ handlers[event_type](data)
+```
+
+**Detection:** String comparisons for type/status/category values.
+
+---
+
+## Security Antipatterns
+
+### SQL Injection
+
+String concatenation in SQL queries.
+
+```javascript
+// BAD: String concatenation
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+db.query(query);
+
+// BAD: String templates still vulnerable
+const query = `SELECT * FROM users WHERE name = '${userName}'`;
+
+// GOOD: Parameterized queries
+const query = 'SELECT * FROM users WHERE id = $1';
+db.query(query, [userId]);
+
+// GOOD: Using ORM safely
+User.findOne({ where: { id: userId } });
+```
+
+**Detection:** String concatenation or template literals with SQL keywords.
+
+---
+
+### Hardcoded Credentials
+
+Secrets in source code.
+
+```python
+# BAD: Hardcoded secrets
+API_KEY = "sk-abc123xyz789"
+DATABASE_URL = "postgresql://admin:password123@prod-db.internal:5432/app"
+
+# GOOD: Environment variables
+import os
+
+API_KEY = os.environ["API_KEY"]
+DATABASE_URL = os.environ["DATABASE_URL"]
+
+# GOOD: Secrets manager
+from aws_secretsmanager import get_secret
+
+API_KEY = get_secret("api-key")
+```
+
+**Detection:** Variables named `password`, `secret`, `key`, `token` with string literals.
+
+---
+
+### Unsafe Deserialization
+
+Deserializing untrusted data without validation.
+
+```python
+# BAD: Binary serialization from untrusted source can execute arbitrary code
+# Examples: Python's binary serialization, yaml.load without SafeLoader
+
+# GOOD: Use safe alternatives
+import json
+
+def load_data(file_path):
+ with open(file_path, 'r') as f:
+ return json.load(f)
+
+# GOOD: Use SafeLoader for YAML
+import yaml
+
+with open('config.yaml') as f:
+ config = yaml.safe_load(f)
+```
+
+**Detection:** Binary deserialization functions, yaml.load without safe loader, dynamic code execution on external data.
+
+---
+
+### Missing Input Validation
+
+Trusting user input without validation.
+
+```typescript
+// BAD: No validation
+app.post('/user', (req, res) => {
+ const user = db.create({
+ name: req.body.name,
+ email: req.body.email,
+ role: req.body.role // User can set themselves as admin!
+ });
+ res.json(user);
+});
+
+// GOOD: Validate and sanitize
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+ name: z.string().min(1).max(100),
+ email: z.string().email(),
+ // role is NOT accepted from input
+});
+
+app.post('/user', (req, res) => {
+ const validated = CreateUserSchema.parse(req.body);
+ const user = db.create({
+ ...validated,
+ role: 'user' // Default role, not from input
+ });
+ res.json(user);
+});
+```
+
+**Detection:** Request body/params used directly without validation schema.
+
+---
+
+## Performance Antipatterns
+
+### N+1 Query Problem
+
+Loading related data one record at a time.
+
+```python
+# BAD: N+1 queries
+def get_orders_with_items():
+ orders = Order.query.all() # 1 query
+ for order in orders:
+ items = OrderItem.query.filter_by(order_id=order.id).all() # N queries
+ order.items = items
+ return orders
+
+# GOOD: Eager loading
+def get_orders_with_items():
+ return Order.query.options(
+ joinedload(Order.items)
+ ).all() # 1 query with JOIN
+
+# GOOD: Batch loading
+def get_orders_with_items():
+ orders = Order.query.all()
+ order_ids = [o.id for o in orders]
+ items = OrderItem.query.filter(
+ OrderItem.order_id.in_(order_ids)
+ ).all() # 2 queries total
+ # Group items by order_id...
+```
+
+**Detection:** Database queries inside loops.
+
+---
+
+### Unbounded Collections
+
+Loading unlimited data into memory.
+
+```go
+// BAD: Load all records
+func GetAllUsers() ([]User, error) {
+ return db.Find(&[]User{}) // Could be millions
+}
+
+// GOOD: Pagination
+func GetUsers(page, pageSize int) ([]User, error) {
+ offset := (page - 1) * pageSize
+ return db.Limit(pageSize).Offset(offset).Find(&[]User{})
+}
+
+// GOOD: Streaming for large datasets
+func ProcessAllUsers(handler func(User) error) error {
+ rows, err := db.Model(&User{}).Rows()
+ if err != nil {
+ return err
+ }
+ defer rows.Close()
+
+ for rows.Next() {
+ var user User
+ db.ScanRows(rows, &user)
+ if err := handler(user); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+```
+
+**Detection:** `findAll()`, `find({})`, or queries without `LIMIT`.
+
+---
+
+### Synchronous I/O in Hot Paths
+
+Blocking operations in request handlers.
+
+```javascript
+// BAD: Sync file read on every request
+app.get('/config', (req, res) => {
+ const config = fs.readFileSync('./config.json'); // Blocks event loop
+ res.json(JSON.parse(config));
+});
+
+// GOOD: Load once at startup
+const config = JSON.parse(fs.readFileSync('./config.json'));
+
+app.get('/config', (req, res) => {
+ res.json(config);
+});
+
+// GOOD: Async with caching
+let configCache = null;
+
+app.get('/config', async (req, res) => {
+ if (!configCache) {
+ configCache = JSON.parse(await fs.promises.readFile('./config.json'));
+ }
+ res.json(configCache);
+});
+```
+
+**Detection:** `readFileSync`, `execSync`, or blocking calls in request handlers.
+
+---
+
+## Testing Antipatterns
+
+### Test Code Duplication
+
+Repeating setup in every test.
+
+```typescript
+// BAD: Duplicate setup
+describe('UserService', () => {
+ it('should create user', async () => {
+ const db = await createTestDatabase();
+ const userRepo = new UserRepository(db);
+ const emailService = new MockEmailService();
+ const service = new UserService(userRepo, emailService);
+
+ const user = await service.create({ name: 'Test' });
+ expect(user.name).toBe('Test');
+ });
+
+ it('should update user', async () => {
+ const db = await createTestDatabase(); // Duplicated
+ const userRepo = new UserRepository(db); // Duplicated
+ const emailService = new MockEmailService(); // Duplicated
+ const service = new UserService(userRepo, emailService); // Duplicated
+
+ // ...
+ });
+});
+
+// GOOD: Shared setup
+describe('UserService', () => {
+ let service: UserService;
+ let db: TestDatabase;
+
+ beforeEach(async () => {
+ db = await createTestDatabase();
+ const userRepo = new UserRepository(db);
+ const emailService = new MockEmailService();
+ service = new UserService(userRepo, emailService);
+ });
+
+ afterEach(async () => {
+ await db.cleanup();
+ });
+
+ it('should create user', async () => {
+ const user = await service.create({ name: 'Test' });
+ expect(user.name).toBe('Test');
+ });
+});
+```
+
+---
+
+### Testing Implementation Instead of Behavior
+
+Tests coupled to internal implementation.
+
+```python
+# BAD: Testing implementation details
+def test_add_item_to_cart():
+ cart = ShoppingCart()
+ cart.add_item(Product("Apple", 1.00))
+
+ # Testing internal structure
+ assert cart._items[0].name == "Apple"
+ assert cart._total == 1.00
+
+# GOOD: Testing behavior
+def test_add_item_to_cart():
+ cart = ShoppingCart()
+ cart.add_item(Product("Apple", 1.00))
+
+ # Testing public behavior
+ assert cart.item_count == 1
+ assert cart.total == 1.00
+ assert cart.contains("Apple")
+```
+
+---
+
+## Async Antipatterns
+
+### Floating Promises
+
+Promises without await or catch.
+
+```typescript
+// BAD: Floating promise
+async function saveUser(user: User) {
+ db.save(user); // Not awaited, errors lost
+ logger.info('User saved'); // Logs before save completes
+}
+
+// BAD: Fire and forget in loop
+for (const item of items) {
+ processItem(item); // All run in parallel, no error handling
+}
+
+// GOOD: Await the promise
+async function saveUser(user: User) {
+ await db.save(user);
+ logger.info('User saved');
+}
+
+// GOOD: Process with proper handling
+await Promise.all(items.map(item => processItem(item)));
+
+// Or sequentially
+for (const item of items) {
+ await processItem(item);
+}
+```
+
+**Detection:** Async function calls without `await` or `.then()`.
+
+---
+
+### Callback Hell
+
+Deeply nested callbacks.
+
+```javascript
+// BAD: Callback hell
+getUser(userId, (err, user) => {
+ if (err) return handleError(err);
+ getOrders(user.id, (err, orders) => {
+ if (err) return handleError(err);
+ getProducts(orders[0].productIds, (err, products) => {
+ if (err) return handleError(err);
+ renderPage(user, orders, products, (err) => {
+ if (err) return handleError(err);
+ console.log('Done');
+ });
+ });
+ });
+});
+
+// GOOD: Async/await
+async function loadPage(userId) {
+ try {
+ const user = await getUser(userId);
+ const orders = await getOrders(user.id);
+ const products = await getProducts(orders[0].productIds);
+ await renderPage(user, orders, products);
+ console.log('Done');
+ } catch (err) {
+ handleError(err);
+ }
+}
+```
+
+**Detection:** >2 levels of callback nesting.
+
+---
+
+### Async in Constructor
+
+Async operations in constructors.
+
+```typescript
+// BAD: Async in constructor
+class DatabaseConnection {
+ constructor(url: string) {
+ this.connect(url); // Fire-and-forget async
+ }
+
+ private async connect(url: string) {
+ this.client = await createClient(url);
+ }
+}
+
+// GOOD: Factory method
+class DatabaseConnection {
+ private constructor(private client: Client) {}
+
+ static async create(url: string): Promise {
+ const client = await createClient(url);
+ return new DatabaseConnection(client);
+ }
+}
+
+// Usage
+const db = await DatabaseConnection.create(url);
+```
+
+**Detection:** `async` calls or `.then()` in constructor.
diff --git a/skills/code-reviewer-2/scripts/code_quality_checker.py b/skills/code-reviewer-2/scripts/code_quality_checker.py
new file mode 100644
index 00000000..128dc9d8
--- /dev/null
+++ b/skills/code-reviewer-2/scripts/code_quality_checker.py
@@ -0,0 +1,560 @@
+#!/usr/bin/env python3
+"""
+Code Quality Checker
+
+Analyzes source code for quality issues, code smells, complexity metrics,
+and SOLID principle violations.
+
+Usage:
+ python code_quality_checker.py /path/to/file.py
+ python code_quality_checker.py /path/to/directory --recursive
+ python code_quality_checker.py . --language typescript --json
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+# Language-specific file extensions
+LANGUAGE_EXTENSIONS = {
+ "python": [".py"],
+ "typescript": [".ts", ".tsx"],
+ "javascript": [".js", ".jsx", ".mjs"],
+ "go": [".go"],
+ "swift": [".swift"],
+ "kotlin": [".kt", ".kts"]
+}
+
+# Code smell thresholds
+THRESHOLDS = {
+ "long_function_lines": 50,
+ "too_many_parameters": 5,
+ "high_complexity": 10,
+ "god_class_methods": 20,
+ "max_imports": 15
+}
+
+
+def get_file_extension(filepath: Path) -> str:
+ """Get file extension."""
+ return filepath.suffix.lower()
+
+
+def detect_language(filepath: Path) -> Optional[str]:
+ """Detect programming language from file extension."""
+ ext = get_file_extension(filepath)
+ for lang, extensions in LANGUAGE_EXTENSIONS.items():
+ if ext in extensions:
+ return lang
+ return None
+
+
+def read_file_content(filepath: Path) -> str:
+ """Read file content safely."""
+ try:
+ with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+ return f.read()
+ except Exception:
+ return ""
+
+
+def calculate_cyclomatic_complexity(content: str) -> int:
+ """
+ Estimate cyclomatic complexity based on control flow keywords.
+ """
+ complexity = 1 # Base complexity
+
+ # Control flow patterns that increase complexity
+ patterns = [
+ r"\bif\b",
+ r"\belif\b",
+ r"\belse\b",
+ r"\bfor\b",
+ r"\bwhile\b",
+ r"\bcase\b",
+ r"\bcatch\b",
+ r"\bexcept\b",
+ r"\band\b",
+ r"\bor\b",
+ r"\|\|",
+ r"&&"
+ ]
+
+ for pattern in patterns:
+ matches = re.findall(pattern, content, re.IGNORECASE)
+ complexity += len(matches)
+
+ return complexity
+
+
+def count_lines(content: str) -> Dict[str, int]:
+ """Count different types of lines in code."""
+ lines = content.split("\n")
+ total = len(lines)
+ blank = sum(1 for line in lines if not line.strip())
+ comment = 0
+
+ for line in lines:
+ stripped = line.strip()
+ if stripped.startswith("#") or stripped.startswith("//"):
+ comment += 1
+ elif stripped.startswith("/*") or stripped.startswith("'''") or stripped.startswith('"""'):
+ comment += 1
+
+ code = total - blank - comment
+
+ return {
+ "total": total,
+ "code": code,
+ "blank": blank,
+ "comment": comment
+ }
+
+
+def find_functions(content: str, language: str) -> List[Dict]:
+ """Find function definitions and their metrics."""
+ functions = []
+
+ # Language-specific function patterns
+ patterns = {
+ "python": r"def\s+(\w+)\s*\(([^)]*)\)",
+ "typescript": r"(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^)]*\)\s*=>)",
+ "javascript": r"(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^)]*\)\s*=>)",
+ "go": r"func\s+(?:\([^)]+\)\s+)?(\w+)\s*\(([^)]*)\)",
+ "swift": r"func\s+(\w+)\s*\(([^)]*)\)",
+ "kotlin": r"fun\s+(\w+)\s*\(([^)]*)\)"
+ }
+
+ pattern = patterns.get(language, patterns["python"])
+ matches = re.finditer(pattern, content, re.MULTILINE)
+
+ for match in matches:
+ name = next((g for g in match.groups() if g), "anonymous")
+ params_str = match.group(2) if len(match.groups()) > 1 and match.group(2) else ""
+
+ # Count parameters
+ params = [p.strip() for p in params_str.split(",") if p.strip()]
+ param_count = len(params)
+
+ # Estimate function length
+ start_pos = match.end()
+ remaining = content[start_pos:]
+
+ next_func = re.search(pattern, remaining)
+ if next_func:
+ func_body = remaining[:next_func.start()]
+ else:
+ func_body = remaining[:min(2000, len(remaining))]
+
+ line_count = len(func_body.split("\n"))
+ complexity = calculate_cyclomatic_complexity(func_body)
+
+ functions.append({
+ "name": name,
+ "parameters": param_count,
+ "lines": line_count,
+ "complexity": complexity
+ })
+
+ return functions
+
+
+def find_classes(content: str, language: str) -> List[Dict]:
+ """Find class definitions and their metrics."""
+ classes = []
+
+ patterns = {
+ "python": r"class\s+(\w+)",
+ "typescript": r"class\s+(\w+)",
+ "javascript": r"class\s+(\w+)",
+ "go": r"type\s+(\w+)\s+struct",
+ "swift": r"class\s+(\w+)",
+ "kotlin": r"class\s+(\w+)"
+ }
+
+ pattern = patterns.get(language, patterns["python"])
+ matches = re.finditer(pattern, content)
+
+ for match in matches:
+ name = match.group(1)
+
+ start_pos = match.end()
+ remaining = content[start_pos:]
+
+ next_class = re.search(pattern, remaining)
+ if next_class:
+ class_body = remaining[:next_class.start()]
+ else:
+ class_body = remaining
+
+ # Count methods
+ method_patterns = {
+ "python": r"def\s+\w+\s*\(",
+ "typescript": r"(?:public|private|protected)?\s*\w+\s*\([^)]*\)\s*[:{]",
+ "javascript": r"\w+\s*\([^)]*\)\s*\{",
+ "go": r"func\s+\(",
+ "swift": r"func\s+\w+",
+ "kotlin": r"fun\s+\w+"
+ }
+ method_pattern = method_patterns.get(language, method_patterns["python"])
+ methods = len(re.findall(method_pattern, class_body))
+
+ classes.append({
+ "name": name,
+ "methods": methods,
+ "lines": len(class_body.split("\n"))
+ })
+
+ return classes
+
+
+def check_code_smells(content: str, functions: List[Dict], classes: List[Dict]) -> List[Dict]:
+ """Check for code smells in the content."""
+ smells = []
+
+ # Long functions
+ for func in functions:
+ if func["lines"] > THRESHOLDS["long_function_lines"]:
+ smells.append({
+ "type": "long_function",
+ "severity": "medium",
+ "message": f"Function '{func['name']}' has {func['lines']} lines (max: {THRESHOLDS['long_function_lines']})",
+ "location": func["name"]
+ })
+
+ # Too many parameters
+ for func in functions:
+ if func["parameters"] > THRESHOLDS["too_many_parameters"]:
+ smells.append({
+ "type": "too_many_parameters",
+ "severity": "low",
+ "message": f"Function '{func['name']}' has {func['parameters']} parameters (max: {THRESHOLDS['too_many_parameters']})",
+ "location": func["name"]
+ })
+
+ # High complexity
+ for func in functions:
+ if func["complexity"] > THRESHOLDS["high_complexity"]:
+ severity = "high" if func["complexity"] > 20 else "medium"
+ smells.append({
+ "type": "high_complexity",
+ "severity": severity,
+ "message": f"Function '{func['name']}' has complexity {func['complexity']} (max: {THRESHOLDS['high_complexity']})",
+ "location": func["name"]
+ })
+
+ # God classes
+ for cls in classes:
+ if cls["methods"] > THRESHOLDS["god_class_methods"]:
+ smells.append({
+ "type": "god_class",
+ "severity": "high",
+ "message": f"Class '{cls['name']}' has {cls['methods']} methods (max: {THRESHOLDS['god_class_methods']})",
+ "location": cls["name"]
+ })
+
+ # Magic numbers
+ magic_pattern = r"\b(? List[Dict]:
+ """Check for potential SOLID principle violations."""
+ violations = []
+
+ # OCP: Type checking instead of polymorphism
+ type_checks = len(re.findall(r"isinstance\(|type\(.*\)\s*==|typeof\s+\w+\s*===", content))
+ if type_checks > 2:
+ violations.append({
+ "principle": "OCP",
+ "name": "Open/Closed Principle",
+ "severity": "medium",
+ "message": f"Found {type_checks} type checks - consider using polymorphism"
+ })
+
+ # LSP/ISP: NotImplementedError
+ not_impl = len(re.findall(r"raise\s+NotImplementedError|not\s+implemented", content, re.IGNORECASE))
+ if not_impl:
+ violations.append({
+ "principle": "LSP/ISP",
+ "name": "Liskov/Interface Segregation",
+ "severity": "low",
+ "message": f"Found {not_impl} unimplemented methods - may indicate oversized interface"
+ })
+
+ # DIP: Too many direct imports
+ imports = len(re.findall(r"^(?:import|from)\s+", content, re.MULTILINE))
+ if imports > THRESHOLDS["max_imports"]:
+ violations.append({
+ "principle": "DIP",
+ "name": "Dependency Inversion Principle",
+ "severity": "low",
+ "message": f"File has {imports} imports - consider dependency injection"
+ })
+
+ return violations
+
+
+def calculate_quality_score(
+ line_metrics: Dict,
+ functions: List[Dict],
+ classes: List[Dict],
+ smells: List[Dict],
+ violations: List[Dict]
+) -> int:
+ """Calculate overall quality score (0-100)."""
+ score = 100
+
+ # Deduct for code smells
+ for smell in smells:
+ if smell["severity"] == "high":
+ score -= 10
+ elif smell["severity"] == "medium":
+ score -= 5
+ elif smell["severity"] == "low":
+ score -= 2
+
+ # Deduct for SOLID violations
+ for violation in violations:
+ if violation["severity"] == "high":
+ score -= 8
+ elif violation["severity"] == "medium":
+ score -= 4
+ elif violation["severity"] == "low":
+ score -= 2
+
+ # Bonus for good comment ratio (10-30%)
+ if line_metrics["total"] > 0:
+ comment_ratio = line_metrics["comment"] / line_metrics["total"]
+ if 0.1 <= comment_ratio <= 0.3:
+ score += 5
+
+ # Bonus for reasonable function sizes
+ if functions:
+ avg_lines = sum(f["lines"] for f in functions) / len(functions)
+ if avg_lines < 30:
+ score += 5
+
+ return max(0, min(100, score))
+
+
+def get_grade(score: int) -> str:
+ """Convert score to letter grade."""
+ if score >= 90:
+ return "A"
+ elif score >= 80:
+ return "B"
+ elif score >= 70:
+ return "C"
+ elif score >= 60:
+ return "D"
+ else:
+ return "F"
+
+
+def analyze_file(filepath: Path) -> Dict:
+ """Analyze a single file for code quality."""
+ language = detect_language(filepath)
+ if not language:
+ return {"error": f"Unsupported file type: {filepath.suffix}"}
+
+ content = read_file_content(filepath)
+ if not content:
+ return {"error": f"Could not read file: {filepath}"}
+
+ line_metrics = count_lines(content)
+ functions = find_functions(content, language)
+ classes = find_classes(content, language)
+ smells = check_code_smells(content, functions, classes)
+ violations = check_solid_violations(content)
+ score = calculate_quality_score(line_metrics, functions, classes, smells, violations)
+
+ return {
+ "file": str(filepath),
+ "language": language,
+ "metrics": {
+ "lines": line_metrics,
+ "functions": len(functions),
+ "classes": len(classes),
+ "avg_complexity": round(sum(f["complexity"] for f in functions) / max(1, len(functions)), 1)
+ },
+ "quality_score": score,
+ "grade": get_grade(score),
+ "smells": smells,
+ "solid_violations": violations,
+ "function_details": functions[:10],
+ "class_details": classes[:10]
+ }
+
+
+def analyze_directory(
+ dir_path: Path,
+ recursive: bool = True,
+ language: Optional[str] = None
+) -> Dict:
+ """Analyze all files in a directory."""
+ results = []
+ extensions = []
+
+ if language:
+ extensions = LANGUAGE_EXTENSIONS.get(language, [])
+ else:
+ for exts in LANGUAGE_EXTENSIONS.values():
+ extensions.extend(exts)
+
+ pattern = "**/*" if recursive else "*"
+
+ for ext in extensions:
+ for filepath in dir_path.glob(f"{pattern}{ext}"):
+ if "node_modules" in str(filepath) or ".git" in str(filepath):
+ continue
+ result = analyze_file(filepath)
+ if "error" not in result:
+ results.append(result)
+
+ if not results:
+ return {"error": "No supported files found"}
+
+ total_score = sum(r["quality_score"] for r in results)
+ avg_score = total_score / len(results)
+ total_smells = sum(len(r["smells"]) for r in results)
+ total_violations = sum(len(r["solid_violations"]) for r in results)
+
+ return {
+ "directory": str(dir_path),
+ "files_analyzed": len(results),
+ "average_score": round(avg_score, 1),
+ "overall_grade": get_grade(int(avg_score)),
+ "total_code_smells": total_smells,
+ "total_solid_violations": total_violations,
+ "files": sorted(results, key=lambda x: x["quality_score"])
+ }
+
+
+def print_report(analysis: Dict) -> None:
+ """Print human-readable analysis report."""
+ if "error" in analysis:
+ print(f"Error: {analysis['error']}")
+ return
+
+ print("=" * 60)
+ print("CODE QUALITY REPORT")
+ print("=" * 60)
+
+ if "file" in analysis:
+ print(f"\nFile: {analysis['file']}")
+ print(f"Language: {analysis['language']}")
+ print(f"Quality Score: {analysis['quality_score']}/100 ({analysis['grade']})")
+
+ metrics = analysis["metrics"]
+ print(f"\nLines: {metrics['lines']['total']} ({metrics['lines']['code']} code, {metrics['lines']['comment']} comments)")
+ print(f"Functions: {metrics['functions']}")
+ print(f"Classes: {metrics['classes']}")
+ print(f"Avg Complexity: {metrics['avg_complexity']}")
+
+ if analysis["smells"]:
+ print("\n--- CODE SMELLS ---")
+ for smell in analysis["smells"][:10]:
+ print(f" [{smell['severity'].upper()}] {smell['message']} ({smell['location']})")
+
+ if analysis["solid_violations"]:
+ print("\n--- SOLID VIOLATIONS ---")
+ for v in analysis["solid_violations"]:
+ print(f" [{v['principle']}] {v['message']}")
+ else:
+ print(f"\nDirectory: {analysis['directory']}")
+ print(f"Files Analyzed: {analysis['files_analyzed']}")
+ print(f"Average Score: {analysis['average_score']}/100 ({analysis['overall_grade']})")
+ print(f"Total Code Smells: {analysis['total_code_smells']}")
+ print(f"Total SOLID Violations: {analysis['total_solid_violations']}")
+
+ print("\n--- FILES BY QUALITY ---")
+ for f in analysis["files"][:10]:
+ print(f" {f['quality_score']:3d}/100 [{f['grade']}] {f['file']}")
+
+ print("\n" + "=" * 60)
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Analyze code quality, smells, and SOLID violations"
+ )
+ parser.add_argument(
+ "path",
+ help="File or directory to analyze"
+ )
+ parser.add_argument(
+ "--recursive", "-r",
+ action="store_true",
+ default=True,
+ help="Recursively analyze directories (default: true)"
+ )
+ parser.add_argument(
+ "--language", "-l",
+ choices=list(LANGUAGE_EXTENSIONS.keys()),
+ help="Filter by programming language"
+ )
+ parser.add_argument(
+ "--json",
+ action="store_true",
+ help="Output in JSON format"
+ )
+ parser.add_argument(
+ "--output", "-o",
+ help="Write output to file"
+ )
+
+ args = parser.parse_args()
+
+ target = Path(args.path).resolve()
+
+ if not target.exists():
+ print(f"Error: Path does not exist: {target}", file=sys.stderr)
+ sys.exit(1)
+
+ if target.is_file():
+ analysis = analyze_file(target)
+ else:
+ analysis = analyze_directory(target, args.recursive, args.language)
+
+ if args.json:
+ output = json.dumps(analysis, indent=2, default=str)
+ if args.output:
+ with open(args.output, "w") as f:
+ f.write(output)
+ print(f"Results written to {args.output}")
+ else:
+ print(output)
+ else:
+ print_report(analysis)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/code-reviewer-2/scripts/pr_analyzer.py b/skills/code-reviewer-2/scripts/pr_analyzer.py
new file mode 100644
index 00000000..4cfd1b53
--- /dev/null
+++ b/skills/code-reviewer-2/scripts/pr_analyzer.py
@@ -0,0 +1,495 @@
+#!/usr/bin/env python3
+"""
+PR Analyzer
+
+Analyzes pull request changes for review complexity, risk assessment,
+and generates review priorities.
+
+Usage:
+ python pr_analyzer.py /path/to/repo
+ python pr_analyzer.py . --base main --head feature-branch
+ python pr_analyzer.py /path/to/repo --json
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+# File categories for review prioritization
+FILE_CATEGORIES = {
+ "critical": {
+ "patterns": [
+ r"auth", r"security", r"password", r"token", r"secret",
+ r"payment", r"billing", r"crypto", r"encrypt"
+ ],
+ "weight": 5,
+ "description": "Security-sensitive files requiring careful review"
+ },
+ "high": {
+ "patterns": [
+ r"api", r"database", r"migration", r"schema", r"model",
+ r"config", r"env", r"middleware"
+ ],
+ "weight": 4,
+ "description": "Core infrastructure files"
+ },
+ "medium": {
+ "patterns": [
+ r"service", r"controller", r"handler", r"util", r"helper"
+ ],
+ "weight": 3,
+ "description": "Business logic files"
+ },
+ "low": {
+ "patterns": [
+ r"test", r"spec", r"mock", r"fixture", r"story",
+ r"readme", r"docs", r"\.md$"
+ ],
+ "weight": 1,
+ "description": "Tests and documentation"
+ }
+}
+
+# Risky patterns to flag
+RISK_PATTERNS = [
+ {
+ "name": "hardcoded_secrets",
+ "pattern": r"(password|secret|api_key|token)\s*[=:]\s*['\"][^'\"]+['\"]",
+ "severity": "critical",
+ "message": "Potential hardcoded secret detected"
+ },
+ {
+ "name": "todo_fixme",
+ "pattern": r"(TODO|FIXME|HACK|XXX):",
+ "severity": "low",
+ "message": "TODO/FIXME comment found"
+ },
+ {
+ "name": "console_log",
+ "pattern": r"console\.(log|debug|info|warn|error)\(",
+ "severity": "medium",
+ "message": "Console statement found (remove for production)"
+ },
+ {
+ "name": "debugger",
+ "pattern": r"\bdebugger\b",
+ "severity": "high",
+ "message": "Debugger statement found"
+ },
+ {
+ "name": "disable_eslint",
+ "pattern": r"eslint-disable",
+ "severity": "medium",
+ "message": "ESLint rule disabled"
+ },
+ {
+ "name": "any_type",
+ "pattern": r":\s*any\b",
+ "severity": "medium",
+ "message": "TypeScript 'any' type used"
+ },
+ {
+ "name": "sql_concatenation",
+ "pattern": r"(SELECT|INSERT|UPDATE|DELETE).*\+.*['\"]",
+ "severity": "critical",
+ "message": "Potential SQL injection (string concatenation in query)"
+ }
+]
+
+
+def run_git_command(cmd: List[str], cwd: Path) -> Tuple[bool, str]:
+ """Run a git command and return success status and output."""
+ try:
+ result = subprocess.run(
+ cmd,
+ cwd=cwd,
+ capture_output=True,
+ text=True,
+ timeout=30
+ )
+ return result.returncode == 0, result.stdout.strip()
+ except subprocess.TimeoutExpired:
+ return False, "Command timed out"
+ except Exception as e:
+ return False, str(e)
+
+
+def get_changed_files(repo_path: Path, base: str, head: str) -> List[Dict]:
+ """Get list of changed files between two refs."""
+ success, output = run_git_command(
+ ["git", "diff", "--name-status", f"{base}...{head}"],
+ repo_path
+ )
+
+ if not success:
+ # Try without the triple dot (for uncommitted changes)
+ success, output = run_git_command(
+ ["git", "diff", "--name-status", base, head],
+ repo_path
+ )
+
+ if not success or not output:
+ # Fall back to staged changes
+ success, output = run_git_command(
+ ["git", "diff", "--name-status", "--cached"],
+ repo_path
+ )
+
+ files = []
+ for line in output.split("\n"):
+ if not line.strip():
+ continue
+ parts = line.split("\t")
+ if len(parts) >= 2:
+ status = parts[0][0] # First character of status
+ filepath = parts[-1] # Handle renames (R100\told\tnew)
+ status_map = {
+ "A": "added",
+ "M": "modified",
+ "D": "deleted",
+ "R": "renamed",
+ "C": "copied"
+ }
+ files.append({
+ "path": filepath,
+ "status": status_map.get(status, "modified")
+ })
+
+ return files
+
+
+def get_file_diff(repo_path: Path, filepath: str, base: str, head: str) -> str:
+ """Get diff content for a specific file."""
+ success, output = run_git_command(
+ ["git", "diff", f"{base}...{head}", "--", filepath],
+ repo_path
+ )
+ if not success:
+ success, output = run_git_command(
+ ["git", "diff", "--cached", "--", filepath],
+ repo_path
+ )
+ return output if success else ""
+
+
+def categorize_file(filepath: str) -> Tuple[str, int]:
+ """Categorize a file based on its path and name."""
+ filepath_lower = filepath.lower()
+
+ for category, info in FILE_CATEGORIES.items():
+ for pattern in info["patterns"]:
+ if re.search(pattern, filepath_lower):
+ return category, info["weight"]
+
+ return "medium", 2 # Default category
+
+
+def analyze_diff_for_risks(diff_content: str, filepath: str) -> List[Dict]:
+ """Analyze diff content for risky patterns."""
+ risks = []
+
+ # Only analyze added lines (starting with +)
+ added_lines = [
+ line[1:] for line in diff_content.split("\n")
+ if line.startswith("+") and not line.startswith("+++")
+ ]
+
+ content = "\n".join(added_lines)
+
+ for risk in RISK_PATTERNS:
+ matches = re.findall(risk["pattern"], content, re.IGNORECASE)
+ if matches:
+ risks.append({
+ "name": risk["name"],
+ "severity": risk["severity"],
+ "message": risk["message"],
+ "file": filepath,
+ "count": len(matches)
+ })
+
+ return risks
+
+
+def count_changes(diff_content: str) -> Dict[str, int]:
+ """Count additions and deletions in diff."""
+ additions = 0
+ deletions = 0
+
+ for line in diff_content.split("\n"):
+ if line.startswith("+") and not line.startswith("+++"):
+ additions += 1
+ elif line.startswith("-") and not line.startswith("---"):
+ deletions += 1
+
+ return {"additions": additions, "deletions": deletions}
+
+
+def calculate_complexity_score(files: List[Dict], all_risks: List[Dict]) -> int:
+ """Calculate overall PR complexity score (1-10)."""
+ score = 0
+
+ # File count contribution (max 3 points)
+ file_count = len(files)
+ if file_count > 20:
+ score += 3
+ elif file_count > 10:
+ score += 2
+ elif file_count > 5:
+ score += 1
+
+ # Total changes contribution (max 3 points)
+ total_changes = sum(f.get("additions", 0) + f.get("deletions", 0) for f in files)
+ if total_changes > 500:
+ score += 3
+ elif total_changes > 200:
+ score += 2
+ elif total_changes > 50:
+ score += 1
+
+ # Risk severity contribution (max 4 points)
+ critical_risks = sum(1 for r in all_risks if r["severity"] == "critical")
+ high_risks = sum(1 for r in all_risks if r["severity"] == "high")
+
+ score += min(2, critical_risks)
+ score += min(2, high_risks)
+
+ return min(10, max(1, score))
+
+
+def analyze_commit_messages(repo_path: Path, base: str, head: str) -> Dict:
+ """Analyze commit messages in the PR."""
+ success, output = run_git_command(
+ ["git", "log", "--oneline", f"{base}...{head}"],
+ repo_path
+ )
+
+ if not success or not output:
+ return {"commits": 0, "issues": []}
+
+ commits = output.strip().split("\n")
+ issues = []
+
+ for commit in commits:
+ if len(commit) < 10:
+ continue
+
+ # Check for conventional commit format
+ message = commit[8:] if len(commit) > 8 else commit # Skip hash
+
+ if not re.match(r"^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\(.+\))?:", message):
+ issues.append({
+ "commit": commit[:7],
+ "issue": "Does not follow conventional commit format"
+ })
+
+ if len(message) > 72:
+ issues.append({
+ "commit": commit[:7],
+ "issue": "Commit message exceeds 72 characters"
+ })
+
+ return {
+ "commits": len(commits),
+ "issues": issues
+ }
+
+
+def analyze_pr(
+ repo_path: Path,
+ base: str = "main",
+ head: str = "HEAD"
+) -> Dict:
+ """Perform complete PR analysis."""
+ # Get changed files
+ changed_files = get_changed_files(repo_path, base, head)
+
+ if not changed_files:
+ return {
+ "status": "no_changes",
+ "message": "No changes detected between branches"
+ }
+
+ # Analyze each file
+ all_risks = []
+ file_analyses = []
+
+ for file_info in changed_files:
+ filepath = file_info["path"]
+ category, weight = categorize_file(filepath)
+
+ # Get diff for the file
+ diff = get_file_diff(repo_path, filepath, base, head)
+ changes = count_changes(diff)
+ risks = analyze_diff_for_risks(diff, filepath)
+
+ all_risks.extend(risks)
+
+ file_analyses.append({
+ "path": filepath,
+ "status": file_info["status"],
+ "category": category,
+ "priority_weight": weight,
+ "additions": changes["additions"],
+ "deletions": changes["deletions"],
+ "risks": risks
+ })
+
+ # Sort by priority (highest first)
+ file_analyses.sort(key=lambda x: (-x["priority_weight"], x["path"]))
+
+ # Analyze commits
+ commit_analysis = analyze_commit_messages(repo_path, base, head)
+
+ # Calculate metrics
+ complexity = calculate_complexity_score(file_analyses, all_risks)
+
+ total_additions = sum(f["additions"] for f in file_analyses)
+ total_deletions = sum(f["deletions"] for f in file_analyses)
+
+ return {
+ "status": "analyzed",
+ "summary": {
+ "files_changed": len(file_analyses),
+ "total_additions": total_additions,
+ "total_deletions": total_deletions,
+ "complexity_score": complexity,
+ "complexity_label": get_complexity_label(complexity),
+ "commits": commit_analysis["commits"]
+ },
+ "risks": {
+ "critical": [r for r in all_risks if r["severity"] == "critical"],
+ "high": [r for r in all_risks if r["severity"] == "high"],
+ "medium": [r for r in all_risks if r["severity"] == "medium"],
+ "low": [r for r in all_risks if r["severity"] == "low"]
+ },
+ "files": file_analyses,
+ "commit_issues": commit_analysis["issues"],
+ "review_order": [f["path"] for f in file_analyses[:10]] # Top 10 priority files
+ }
+
+
+def get_complexity_label(score: int) -> str:
+ """Get human-readable complexity label."""
+ if score <= 2:
+ return "Simple"
+ elif score <= 4:
+ return "Moderate"
+ elif score <= 6:
+ return "Complex"
+ elif score <= 8:
+ return "Very Complex"
+ else:
+ return "Critical"
+
+
+def print_report(analysis: Dict) -> None:
+ """Print human-readable analysis report."""
+ if analysis["status"] == "no_changes":
+ print("No changes detected.")
+ return
+
+ summary = analysis["summary"]
+ risks = analysis["risks"]
+
+ print("=" * 60)
+ print("PR ANALYSIS REPORT")
+ print("=" * 60)
+
+ print(f"\nComplexity: {summary['complexity_score']}/10 ({summary['complexity_label']})")
+ print(f"Files Changed: {summary['files_changed']}")
+ print(f"Lines: +{summary['total_additions']} / -{summary['total_deletions']}")
+ print(f"Commits: {summary['commits']}")
+
+ # Risk summary
+ print("\n--- RISK SUMMARY ---")
+ print(f"Critical: {len(risks['critical'])}")
+ print(f"High: {len(risks['high'])}")
+ print(f"Medium: {len(risks['medium'])}")
+ print(f"Low: {len(risks['low'])}")
+
+ # Critical and high risks details
+ if risks["critical"]:
+ print("\n--- CRITICAL RISKS ---")
+ for risk in risks["critical"]:
+ print(f" [{risk['file']}] {risk['message']} (x{risk['count']})")
+
+ if risks["high"]:
+ print("\n--- HIGH RISKS ---")
+ for risk in risks["high"]:
+ print(f" [{risk['file']}] {risk['message']} (x{risk['count']})")
+
+ # Commit message issues
+ if analysis["commit_issues"]:
+ print("\n--- COMMIT MESSAGE ISSUES ---")
+ for issue in analysis["commit_issues"][:5]:
+ print(f" {issue['commit']}: {issue['issue']}")
+
+ # Review order
+ print("\n--- SUGGESTED REVIEW ORDER ---")
+ for i, filepath in enumerate(analysis["review_order"], 1):
+ file_info = next(f for f in analysis["files"] if f["path"] == filepath)
+ print(f" {i}. [{file_info['category'].upper()}] {filepath}")
+
+ print("\n" + "=" * 60)
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Analyze pull request for review complexity and risks"
+ )
+ parser.add_argument(
+ "repo_path",
+ nargs="?",
+ default=".",
+ help="Path to git repository (default: current directory)"
+ )
+ parser.add_argument(
+ "--base", "-b",
+ default="main",
+ help="Base branch for comparison (default: main)"
+ )
+ parser.add_argument(
+ "--head", "-h",
+ default="HEAD",
+ help="Head branch/commit for comparison (default: HEAD)"
+ )
+ parser.add_argument(
+ "--json",
+ action="store_true",
+ help="Output in JSON format"
+ )
+ parser.add_argument(
+ "--output", "-o",
+ help="Write output to file"
+ )
+
+ args = parser.parse_args()
+
+ repo_path = Path(args.repo_path).resolve()
+
+ if not (repo_path / ".git").exists():
+ print(f"Error: {repo_path} is not a git repository", file=sys.stderr)
+ sys.exit(1)
+
+ analysis = analyze_pr(repo_path, args.base, args.head)
+
+ if args.json:
+ output = json.dumps(analysis, indent=2)
+ if args.output:
+ with open(args.output, "w") as f:
+ f.write(output)
+ print(f"Results written to {args.output}")
+ else:
+ print(output)
+ else:
+ print_report(analysis)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/code-reviewer-2/scripts/review_report_generator.py b/skills/code-reviewer-2/scripts/review_report_generator.py
new file mode 100644
index 00000000..7c2246a9
--- /dev/null
+++ b/skills/code-reviewer-2/scripts/review_report_generator.py
@@ -0,0 +1,505 @@
+#!/usr/bin/env python3
+"""
+Review Report Generator
+
+Generates comprehensive code review reports by combining PR analysis
+and code quality findings into structured, actionable reports.
+
+Usage:
+ python review_report_generator.py /path/to/repo
+ python review_report_generator.py . --pr-analysis pr_results.json --quality-analysis quality_results.json
+ python review_report_generator.py /path/to/repo --format markdown --output review.md
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+# Severity weights for prioritization
+SEVERITY_WEIGHTS = {
+ "critical": 100,
+ "high": 75,
+ "medium": 50,
+ "low": 25,
+ "info": 10
+}
+
+# Review verdict thresholds
+VERDICT_THRESHOLDS = {
+ "approve": {"max_critical": 0, "max_high": 0, "max_score": 100},
+ "approve_with_suggestions": {"max_critical": 0, "max_high": 2, "max_score": 85},
+ "request_changes": {"max_critical": 0, "max_high": 5, "max_score": 70},
+ "block": {"max_critical": float("inf"), "max_high": float("inf"), "max_score": 0}
+}
+
+
+def load_json_file(filepath: str) -> Optional[Dict]:
+ """Load JSON file if it exists."""
+ try:
+ with open(filepath, "r") as f:
+ return json.load(f)
+ except (FileNotFoundError, json.JSONDecodeError):
+ return None
+
+
+def run_pr_analyzer(repo_path: Path) -> Dict:
+ """Run pr_analyzer.py and return results."""
+ script_path = Path(__file__).parent / "pr_analyzer.py"
+ if not script_path.exists():
+ return {"status": "error", "message": "pr_analyzer.py not found"}
+
+ try:
+ result = subprocess.run(
+ [sys.executable, str(script_path), str(repo_path), "--json"],
+ capture_output=True,
+ text=True,
+ timeout=120
+ )
+ if result.returncode == 0:
+ return json.loads(result.stdout)
+ return {"status": "error", "message": result.stderr}
+ except Exception as e:
+ return {"status": "error", "message": str(e)}
+
+
+def run_quality_checker(repo_path: Path) -> Dict:
+ """Run code_quality_checker.py and return results."""
+ script_path = Path(__file__).parent / "code_quality_checker.py"
+ if not script_path.exists():
+ return {"status": "error", "message": "code_quality_checker.py not found"}
+
+ try:
+ result = subprocess.run(
+ [sys.executable, str(script_path), str(repo_path), "--json"],
+ capture_output=True,
+ text=True,
+ timeout=300
+ )
+ if result.returncode == 0:
+ return json.loads(result.stdout)
+ return {"status": "error", "message": result.stderr}
+ except Exception as e:
+ return {"status": "error", "message": str(e)}
+
+
+def calculate_review_score(pr_analysis: Dict, quality_analysis: Dict) -> int:
+ """Calculate overall review score (0-100)."""
+ score = 100
+
+ # Deduct for PR risks
+ if "risks" in pr_analysis:
+ risks = pr_analysis["risks"]
+ score -= len(risks.get("critical", [])) * 15
+ score -= len(risks.get("high", [])) * 10
+ score -= len(risks.get("medium", [])) * 5
+ score -= len(risks.get("low", [])) * 2
+
+ # Deduct for code quality issues
+ if "issues" in quality_analysis:
+ issues = quality_analysis["issues"]
+ score -= len([i for i in issues if i.get("severity") == "critical"]) * 12
+ score -= len([i for i in issues if i.get("severity") == "high"]) * 8
+ score -= len([i for i in issues if i.get("severity") == "medium"]) * 4
+ score -= len([i for i in issues if i.get("severity") == "low"]) * 1
+
+ # Deduct for complexity
+ if "summary" in pr_analysis:
+ complexity = pr_analysis["summary"].get("complexity_score", 0)
+ if complexity > 7:
+ score -= 10
+ elif complexity > 5:
+ score -= 5
+
+ return max(0, min(100, score))
+
+
+def determine_verdict(score: int, critical_count: int, high_count: int) -> Tuple[str, str]:
+ """Determine review verdict based on score and issue counts."""
+ if critical_count > 0:
+ return "block", "Critical issues must be resolved before merge"
+
+ if score >= 90 and high_count == 0:
+ return "approve", "Code meets quality standards"
+
+ if score >= 75 and high_count <= 2:
+ return "approve_with_suggestions", "Minor improvements recommended"
+
+ if score >= 50:
+ return "request_changes", "Several issues need to be addressed"
+
+ return "block", "Significant issues prevent approval"
+
+
+def generate_findings_list(pr_analysis: Dict, quality_analysis: Dict) -> List[Dict]:
+ """Combine and prioritize all findings."""
+ findings = []
+
+ # Add PR risk findings
+ if "risks" in pr_analysis:
+ for severity, items in pr_analysis["risks"].items():
+ for item in items:
+ findings.append({
+ "source": "pr_analysis",
+ "severity": severity,
+ "category": item.get("name", "unknown"),
+ "message": item.get("message", ""),
+ "file": item.get("file", ""),
+ "count": item.get("count", 1)
+ })
+
+ # Add code quality findings
+ if "issues" in quality_analysis:
+ for issue in quality_analysis["issues"]:
+ findings.append({
+ "source": "quality_analysis",
+ "severity": issue.get("severity", "medium"),
+ "category": issue.get("type", "unknown"),
+ "message": issue.get("message", ""),
+ "file": issue.get("file", ""),
+ "line": issue.get("line", 0)
+ })
+
+ # Sort by severity weight
+ findings.sort(
+ key=lambda x: -SEVERITY_WEIGHTS.get(x["severity"], 0)
+ )
+
+ return findings
+
+
+def generate_action_items(findings: List[Dict]) -> List[Dict]:
+ """Generate prioritized action items from findings."""
+ action_items = []
+ seen_categories = set()
+
+ for finding in findings:
+ category = finding["category"]
+ severity = finding["severity"]
+
+ # Group similar issues
+ if category in seen_categories and severity not in ["critical", "high"]:
+ continue
+
+ action = {
+ "priority": "P0" if severity == "critical" else "P1" if severity == "high" else "P2",
+ "action": get_action_for_category(category, finding),
+ "severity": severity,
+ "files_affected": [finding["file"]] if finding.get("file") else []
+ }
+ action_items.append(action)
+ seen_categories.add(category)
+
+ return action_items[:15] # Top 15 actions
+
+
+def get_action_for_category(category: str, finding: Dict) -> str:
+ """Get actionable recommendation for issue category."""
+ actions = {
+ "hardcoded_secrets": "Remove hardcoded credentials and use environment variables or a secrets manager",
+ "sql_concatenation": "Use parameterized queries to prevent SQL injection",
+ "debugger": "Remove debugger statements before merging",
+ "console_log": "Remove or replace console statements with proper logging",
+ "todo_fixme": "Address TODO/FIXME comments or create tracking issues",
+ "disable_eslint": "Address the underlying issue instead of disabling lint rules",
+ "any_type": "Replace 'any' types with proper type definitions",
+ "long_function": "Break down function into smaller, focused units",
+ "god_class": "Split class into smaller, single-responsibility classes",
+ "too_many_params": "Use parameter objects or builder pattern",
+ "deep_nesting": "Refactor using early returns, guard clauses, or extraction",
+ "high_complexity": "Reduce cyclomatic complexity through refactoring",
+ "missing_error_handling": "Add proper error handling and recovery logic",
+ "duplicate_code": "Extract duplicate code into shared functions",
+ "magic_numbers": "Replace magic numbers with named constants",
+ "large_file": "Consider splitting into multiple smaller modules"
+ }
+ return actions.get(category, f"Review and address: {finding.get('message', category)}")
+
+
+def format_markdown_report(report: Dict) -> str:
+ """Generate markdown-formatted report."""
+ lines = []
+
+ # Header
+ lines.append("# Code Review Report")
+ lines.append("")
+ lines.append(f"**Generated:** {report['metadata']['generated_at']}")
+ lines.append(f"**Repository:** {report['metadata']['repository']}")
+ lines.append("")
+
+ # Executive Summary
+ lines.append("## Executive Summary")
+ lines.append("")
+ summary = report["summary"]
+ verdict = summary["verdict"]
+ verdict_emoji = {
+ "approve": "✅",
+ "approve_with_suggestions": "✅",
+ "request_changes": "⚠️",
+ "block": "❌"
+ }.get(verdict, "❓")
+
+ lines.append(f"**Verdict:** {verdict_emoji} {verdict.upper().replace('_', ' ')}")
+ lines.append(f"**Score:** {summary['score']}/100")
+ lines.append(f"**Rationale:** {summary['rationale']}")
+ lines.append("")
+
+ # Issue Counts
+ lines.append("### Issue Summary")
+ lines.append("")
+ lines.append("| Severity | Count |")
+ lines.append("|----------|-------|")
+ for severity in ["critical", "high", "medium", "low"]:
+ count = summary["issue_counts"].get(severity, 0)
+ lines.append(f"| {severity.capitalize()} | {count} |")
+ lines.append("")
+
+ # PR Statistics (if available)
+ if "pr_summary" in report:
+ pr = report["pr_summary"]
+ lines.append("### Change Statistics")
+ lines.append("")
+ lines.append(f"- **Files Changed:** {pr.get('files_changed', 'N/A')}")
+ lines.append(f"- **Lines Added:** +{pr.get('total_additions', 0)}")
+ lines.append(f"- **Lines Removed:** -{pr.get('total_deletions', 0)}")
+ lines.append(f"- **Complexity:** {pr.get('complexity_label', 'N/A')}")
+ lines.append("")
+
+ # Action Items
+ if report.get("action_items"):
+ lines.append("## Action Items")
+ lines.append("")
+ for i, item in enumerate(report["action_items"], 1):
+ priority = item["priority"]
+ emoji = "🔴" if priority == "P0" else "🟠" if priority == "P1" else "🟡"
+ lines.append(f"{i}. {emoji} **[{priority}]** {item['action']}")
+ if item.get("files_affected"):
+ lines.append(f" - Files: {', '.join(item['files_affected'][:3])}")
+ lines.append("")
+
+ # Critical Findings
+ critical_findings = [f for f in report.get("findings", []) if f["severity"] == "critical"]
+ if critical_findings:
+ lines.append("## Critical Issues (Must Fix)")
+ lines.append("")
+ for finding in critical_findings:
+ lines.append(f"- **{finding['category']}** in `{finding.get('file', 'unknown')}`")
+ lines.append(f" - {finding['message']}")
+ lines.append("")
+
+ # High Priority Findings
+ high_findings = [f for f in report.get("findings", []) if f["severity"] == "high"]
+ if high_findings:
+ lines.append("## High Priority Issues")
+ lines.append("")
+ for finding in high_findings[:10]:
+ lines.append(f"- **{finding['category']}** in `{finding.get('file', 'unknown')}`")
+ lines.append(f" - {finding['message']}")
+ lines.append("")
+
+ # Review Order (if available)
+ if "review_order" in report:
+ lines.append("## Suggested Review Order")
+ lines.append("")
+ for i, filepath in enumerate(report["review_order"][:10], 1):
+ lines.append(f"{i}. `{filepath}`")
+ lines.append("")
+
+ # Footer
+ lines.append("---")
+ lines.append("*Generated by Code Reviewer*")
+
+ return "\n".join(lines)
+
+
+def format_text_report(report: Dict) -> str:
+ """Generate plain text report."""
+ lines = []
+
+ lines.append("=" * 60)
+ lines.append("CODE REVIEW REPORT")
+ lines.append("=" * 60)
+ lines.append("")
+ lines.append(f"Generated: {report['metadata']['generated_at']}")
+ lines.append(f"Repository: {report['metadata']['repository']}")
+ lines.append("")
+
+ summary = report["summary"]
+ verdict = summary["verdict"].upper().replace("_", " ")
+ lines.append(f"VERDICT: {verdict}")
+ lines.append(f"SCORE: {summary['score']}/100")
+ lines.append(f"RATIONALE: {summary['rationale']}")
+ lines.append("")
+
+ lines.append("--- ISSUE SUMMARY ---")
+ for severity in ["critical", "high", "medium", "low"]:
+ count = summary["issue_counts"].get(severity, 0)
+ lines.append(f" {severity.capitalize()}: {count}")
+ lines.append("")
+
+ if report.get("action_items"):
+ lines.append("--- ACTION ITEMS ---")
+ for i, item in enumerate(report["action_items"][:10], 1):
+ lines.append(f" {i}. [{item['priority']}] {item['action']}")
+ lines.append("")
+
+ critical = [f for f in report.get("findings", []) if f["severity"] == "critical"]
+ if critical:
+ lines.append("--- CRITICAL ISSUES ---")
+ for f in critical:
+ lines.append(f" [{f.get('file', 'unknown')}] {f['message']}")
+ lines.append("")
+
+ lines.append("=" * 60)
+
+ return "\n".join(lines)
+
+
+def generate_report(
+ repo_path: Path,
+ pr_analysis: Optional[Dict] = None,
+ quality_analysis: Optional[Dict] = None
+) -> Dict:
+ """Generate comprehensive review report."""
+ # Run analyses if not provided
+ if pr_analysis is None:
+ pr_analysis = run_pr_analyzer(repo_path)
+
+ if quality_analysis is None:
+ quality_analysis = run_quality_checker(repo_path)
+
+ # Generate findings
+ findings = generate_findings_list(pr_analysis, quality_analysis)
+
+ # Count issues by severity
+ issue_counts = {
+ "critical": len([f for f in findings if f["severity"] == "critical"]),
+ "high": len([f for f in findings if f["severity"] == "high"]),
+ "medium": len([f for f in findings if f["severity"] == "medium"]),
+ "low": len([f for f in findings if f["severity"] == "low"])
+ }
+
+ # Calculate score and verdict
+ score = calculate_review_score(pr_analysis, quality_analysis)
+ verdict, rationale = determine_verdict(
+ score,
+ issue_counts["critical"],
+ issue_counts["high"]
+ )
+
+ # Generate action items
+ action_items = generate_action_items(findings)
+
+ # Build report
+ report = {
+ "metadata": {
+ "generated_at": datetime.now().isoformat(),
+ "repository": str(repo_path),
+ "version": "1.0.0"
+ },
+ "summary": {
+ "score": score,
+ "verdict": verdict,
+ "rationale": rationale,
+ "issue_counts": issue_counts
+ },
+ "findings": findings,
+ "action_items": action_items
+ }
+
+ # Add PR summary if available
+ if pr_analysis.get("status") == "analyzed":
+ report["pr_summary"] = pr_analysis.get("summary", {})
+ report["review_order"] = pr_analysis.get("review_order", [])
+
+ # Add quality summary if available
+ if quality_analysis.get("status") == "analyzed":
+ report["quality_summary"] = quality_analysis.get("summary", {})
+
+ return report
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Generate comprehensive code review reports"
+ )
+ parser.add_argument(
+ "repo_path",
+ nargs="?",
+ default=".",
+ help="Path to repository (default: current directory)"
+ )
+ parser.add_argument(
+ "--pr-analysis",
+ help="Path to pre-computed PR analysis JSON"
+ )
+ parser.add_argument(
+ "--quality-analysis",
+ help="Path to pre-computed quality analysis JSON"
+ )
+ parser.add_argument(
+ "--format", "-f",
+ choices=["text", "markdown", "json"],
+ default="text",
+ help="Output format (default: text)"
+ )
+ parser.add_argument(
+ "--output", "-o",
+ help="Write output to file"
+ )
+ parser.add_argument(
+ "--json",
+ action="store_true",
+ help="Output as JSON (shortcut for --format json)"
+ )
+
+ args = parser.parse_args()
+
+ repo_path = Path(args.repo_path).resolve()
+ if not repo_path.exists():
+ print(f"Error: Path does not exist: {repo_path}", file=sys.stderr)
+ sys.exit(1)
+
+ # Load pre-computed analyses if provided
+ pr_analysis = None
+ quality_analysis = None
+
+ if args.pr_analysis:
+ pr_analysis = load_json_file(args.pr_analysis)
+ if not pr_analysis:
+ print(f"Warning: Could not load PR analysis from {args.pr_analysis}")
+
+ if args.quality_analysis:
+ quality_analysis = load_json_file(args.quality_analysis)
+ if not quality_analysis:
+ print(f"Warning: Could not load quality analysis from {args.quality_analysis}")
+
+ # Generate report
+ report = generate_report(repo_path, pr_analysis, quality_analysis)
+
+ # Format output
+ output_format = "json" if args.json else args.format
+
+ if output_format == "json":
+ output = json.dumps(report, indent=2)
+ elif output_format == "markdown":
+ output = format_markdown_report(report)
+ else:
+ output = format_text_report(report)
+
+ # Write or print output
+ if args.output:
+ with open(args.output, "w") as f:
+ f.write(output)
+ print(f"Report written to {args.output}")
+ else:
+ print(output)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/code-to-prd/README.md b/skills/code-to-prd/README.md
new file mode 100644
index 00000000..12485fd0
--- /dev/null
+++ b/skills/code-to-prd/README.md
@@ -0,0 +1,58 @@
+# Code → PRD
+
+Reverse-engineer any codebase into a complete Product Requirements Document (PRD).
+
+## Quick Start
+
+```bash
+# One command
+/code-to-prd /path/to/project
+
+# Or step by step
+python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json
+python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App"
+```
+
+## Supported Frameworks
+
+| Stack | Frameworks |
+|-------|-----------|
+| Frontend | React, Vue, Angular, Svelte, Next.js, Nuxt, SvelteKit, Remix |
+| Backend | NestJS, Express, Django, DRF, FastAPI, Flask |
+| Fullstack | Next.js (pages + API), Nuxt (pages + server), Django (views + templates) |
+
+## What It Generates
+
+```
+prd/
+├── README.md # System overview
+├── pages/
+│ ├── 01-user-mgmt-list.md # Per-page/endpoint docs
+│ └── ...
+└── appendix/
+ ├── enum-dictionary.md # All enums and status codes
+ ├── api-inventory.md # Complete API reference
+ └── page-relationships.md # Navigation and data coupling
+```
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `codebase_analyzer.py` | Scan codebase → extract routes, APIs, models, enums |
+| `prd_scaffolder.py` | Generate PRD directory skeleton from analysis JSON |
+
+Both are stdlib-only — no pip install needed. Run `--help` for full usage.
+
+## References
+
+- `references/framework-patterns.md` — Route, state, API, form, and model patterns per framework
+- `references/prd-quality-checklist.md` — Validation checklist for completeness and accuracy
+
+## Attribution
+
+Inspired by [code-to-prd](https://github.com/lihanglogan/code-to-prd) by [@lihanglogan](https://github.com/lihanglogan).
+
+## License
+
+MIT
diff --git a/skills/code-to-prd/SKILL.md b/skills/code-to-prd/SKILL.md
new file mode 100644
index 00000000..3014a0a4
--- /dev/null
+++ b/skills/code-to-prd/SKILL.md
@@ -0,0 +1,507 @@
+---
+Name: code-to-prd
+Tier: STANDARD
+Category: product
+Dependencies: none
+Author: Alireza Rezvani
+Version: 2.1.2
+name: code-to-prd
+description: |
+ Reverse-engineer any codebase into a complete Product Requirements Document (PRD).
+ Analyzes routes, components, state management, API integrations, and user interactions to produce
+ business-readable documentation detailed enough for engineers or AI agents to fully reconstruct
+ every page and endpoint. Works with frontend frameworks (React, Vue, Angular, Svelte, Next.js, Nuxt),
+ backend frameworks (NestJS, Django, Express, FastAPI), and fullstack applications.
+
+ Trigger when users mention: generate PRD, reverse-engineer requirements, code to documentation,
+ extract product specs from code, document page logic, analyze page fields and interactions,
+ create a functional inventory, write requirements from an existing codebase, document API endpoints,
+ or analyze backend routes.
+license: MIT
+metadata:
+ updated: 2026-03-17
+---
+
+## Name
+
+Code → PRD
+
+## Description
+
+Reverse-engineer any frontend, backend, or fullstack codebase into a complete Product Requirements Document (PRD). Analyzes routes, components, models, APIs, and user interactions to produce business-readable documentation detailed enough for engineers or AI agents to fully reconstruct every page and endpoint.
+
+# Code → PRD: Reverse-Engineer Any Codebase into Product Requirements
+
+## Features
+
+- **3-phase workflow**: global scan → page-by-page analysis → structured document generation
+- **Frontend support**: React, Vue, Angular, Svelte, Next.js (App + Pages Router), Nuxt, SvelteKit, Remix
+- **Backend support**: NestJS, Express, Django, Django REST Framework, FastAPI, Flask
+- **Fullstack support**: Combined frontend + backend analysis with unified PRD output
+- **Mock detection**: Automatically distinguishes real API integrations from mock/fixture data
+- **Enum extraction**: Exhaustively lists all status codes, type mappings, and constants
+- **Model extraction**: Parses Django models, NestJS entities, Pydantic schemas
+- **Automation scripts**: `codebase_analyzer.py` for scanning, `prd_scaffolder.py` for directory generation
+- **Quality checklist**: Validation checklist for completeness, accuracy, readability
+
+## Usage
+
+```bash
+# Analyze a project and generate PRD skeleton
+python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json
+python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App"
+
+# Or use the slash command
+/code-to-prd /path/to/project
+```
+
+## Examples
+
+### Frontend (React)
+```bash
+/code-to-prd ./src
+# → Scans components, routes, API calls, state management
+# → Generates prd/ with per-page docs, enum dictionary, API inventory
+```
+
+### Backend (Django)
+```bash
+/code-to-prd ./myproject
+# → Detects Django via manage.py, scans urls.py, views.py, models.py
+# → Documents endpoints, model schemas, admin config, permissions
+```
+
+### Fullstack (Next.js)
+```bash
+/code-to-prd .
+# → Analyzes both app/ pages and api/ routes
+# → Generates unified PRD covering UI pages and API endpoints
+```
+
+---
+
+## Role
+
+You are a senior product analyst and technical architect. Your job is to read a frontend codebase, understand every page's business purpose, and produce a complete PRD in **product-manager-friendly language**.
+
+### Dual Audience
+
+1. **Product managers / business stakeholders** — need to understand *what* the system does, not *how*
+2. **Engineers / AI agents** — need enough detail to **fully reconstruct** every page's fields, interactions, and relationships
+
+Your document must describe functionality in non-technical language while omitting zero business details.
+
+### Supported Stacks
+
+| Stack | Frameworks |
+|-------|-----------|
+| **Frontend** | React, Vue, Angular, Svelte, Next.js (App/Pages Router), Nuxt, SvelteKit, Remix, Astro |
+| **Backend** | NestJS, Express, Fastify, Django, Django REST Framework, FastAPI, Flask |
+| **Fullstack** | Next.js (API routes + pages), Nuxt (server/ + pages/), Django (views + templates) |
+
+For **backend-only** projects, the "page" concept maps to **API resource groups** or **admin views**. The same 3-phase workflow applies — routes become endpoints, components become controllers/views, and interactions become request/response flows.
+
+---
+
+## Workflow
+
+### Phase 1 — Project Global Scan
+
+Build global context before diving into pages.
+
+#### 1. Identify Project Structure
+
+Scan the root directory and understand organization:
+
+```
+Frontend directories:
+- Pages/routes (pages/, views/, routes/, app/, src/pages/)
+- Components (components/, modules/)
+- Route config (router.ts, routes.ts, App.tsx route definitions)
+- API/service layer (services/, api/, requests/)
+- State management (store/, models/, context/)
+- i18n files (locales/, i18n/) — field display names often live here
+
+Backend directories (NestJS):
+- Modules (src/modules/, src/*.module.ts)
+- Controllers (*.controller.ts) — route handlers
+- Services (*.service.ts) — business logic
+- DTOs (dto/, *.dto.ts) — request/response shapes
+- Entities (entities/, *.entity.ts) — database models
+- Guards/pipes/interceptors — auth, validation, transformation
+
+Backend directories (Django):
+- Apps (*/apps.py, */views.py, */models.py, */urls.py)
+- URL config (urls.py, */urls.py)
+- Views (views.py, viewsets.py) — route handlers
+- Models (models.py) — database schema
+- Serializers (serializers.py) — request/response shapes
+- Forms (forms.py) — validation and field definitions
+- Templates (templates/) — server-rendered pages
+- Admin (admin.py) — admin panel configuration
+```
+
+**Identify framework** from `package.json` (Node.js frameworks) or project files (`manage.py` for Django, `requirements.txt`/`pyproject.toml` for Python). Routing, component patterns, and state management differ significantly across frameworks — identification enables accurate parsing.
+
+#### 2. Build Route & Page Inventory
+
+Extract all pages from route config into a complete **page inventory**:
+
+| Field | Description |
+|-------|-------------|
+| Route path | e.g. `/user/list`, `/order/:id` |
+| Page title | From route config, breadcrumbs, or page component |
+| Module / menu level | Where it sits in navigation |
+| Component file path | Source file(s) implementing this page |
+
+For file-system routing (Next.js, Nuxt), infer from directory structure.
+
+**For backend projects**, the page inventory becomes an **endpoint/resource inventory**:
+
+| Field | Description |
+|-------|-------------|
+| Endpoint path | e.g. `/api/users`, `/api/orders/:id` |
+| HTTP method | GET, POST, PUT, DELETE, PATCH |
+| Controller/view | Source file handling this route |
+| Module/app | Which NestJS module or Django app owns it |
+| Auth required | Whether authentication/permissions are needed |
+
+For NestJS: extract from `@Controller` + `@Get/@Post/@Put/@Delete` decorators.
+For Django: extract from `urls.py` → `urlpatterns` and `viewsets.py` → router registrations.
+
+#### 3. Map Global Context
+
+Before analyzing individual pages, capture:
+
+- **Global state** — user info, permissions, feature flags, config
+- **Shared components** — layout, nav, auth guards, error boundaries
+- **Enums & constants** — status codes, type mappings, role definitions
+- **API base config** — base URL, interceptors, auth headers, error handling
+- **Database models** (backend) — entity relationships, field types, constraints
+- **Middleware** (backend) — auth middleware, rate limiting, logging, CORS
+- **DTOs/Serializers** (backend) — request validation shapes, response formats
+
+These will be referenced throughout page/endpoint analysis.
+
+---
+
+### Phase 2 — Page-by-Page Deep Analysis
+
+Analyze every page in the inventory. **Each page produces its own Markdown file.**
+
+#### Analysis Dimensions
+
+For each page, answer:
+
+##### A. Page Overview
+- What does this page do? (one sentence)
+- Where does it fit in the system?
+- What scenario brings a user here?
+
+##### B. Layout & Regions
+- Major regions: search area, table, detail panel, action bar, tabs, etc.
+- Spatial arrangement: top/bottom, left/right, nested
+
+##### C. Field Inventory (core — be exhaustive)
+
+**For form pages**, list every field:
+
+| Field Name | Type | Required | Default | Validation | Business Description |
+|-----------|------|----------|---------|------------|---------------------|
+| Username | Text input | Yes | — | Max 20 chars | System login account |
+
+**For table/list pages**, list:
+- Search/filter fields (type, required, enum options)
+- Table columns (name, format, sortable, filterable)
+- Row action buttons (what each one does)
+
+**Field name extraction priority:**
+1. Hardcoded display text in code
+2. i18n translation values
+3. Component `placeholder` / `label` / `title` props
+4. Variable names (last resort — provide reasonable display name)
+
+##### D. Interaction Logic
+
+Describe as **"user action → system response"**:
+
+```
+[Action] User clicks "Create"
+[Response] Modal opens with form fields: ...
+[Validation] Name required, phone format check
+[API] POST /api/user/create with form data
+[Success] Toast "Created successfully", close modal, refresh list
+[Failure] Show API error message
+```
+
+**Cover all interaction types:**
+- Page load / initialization (default queries, preloaded data)
+- Search / filter / reset
+- CRUD operations (create, read, update, delete)
+- Table: pagination, sorting, row selection, bulk actions
+- Form submission & validation
+- Status transitions (e.g. approval flows: pending → approved → rejected)
+- Import / export
+- Field interdependencies (selecting value A changes options in field B)
+- Permission controls (buttons/fields visible only to certain roles)
+- Polling / auto-refresh / real-time updates
+
+##### E. API Dependencies
+
+**Case 1: API is integrated** (real HTTP calls in code)
+
+| API Name | Method | Path | Trigger | Key Params | Notes |
+|----------|--------|------|---------|-----------|-------|
+| Get users | GET | /api/user/list | Load, search | page, size, keyword | Paginated |
+
+**Case 2: API not integrated** (mock/hardcoded data)
+
+When the page uses mock data, hardcoded fixtures, `setTimeout` simulations, or `Promise.resolve()` stubs — the API isn't real yet. **Reverse-engineer the required API spec** from page functionality and data shape.
+
+For each needed API, document:
+- Method, suggested path, trigger
+- Input params (name, type, required, description)
+- Output fields (name, type, description)
+- Core business logic description
+
+**Detection signals:**
+- `setTimeout` / `Promise.resolve()` returning data → mock
+- Data defined in component or `*.mock.*` files → mock
+- Real HTTP calls (`axios`, `fetch`, service layer) with real paths → integrated
+- `__mocks__` directory → mock
+
+##### F. Page Relationships
+
+- **Inbound**: Which pages link here? What parameters do they pass?
+- **Outbound**: Where can users navigate from here? What parameters?
+- **Data coupling**: Which pages share data or trigger refreshes in each other?
+
+---
+
+### Phase 3 — Generate Documentation
+
+#### Output Structure
+
+Create `prd/` in project root (or user-specified directory):
+
+```
+prd/
+├── README.md # System overview
+├── pages/
+│ ├── 01-user-mgmt-list.md # One file per page
+│ ├── 02-user-mgmt-detail.md
+│ ├── 03-order-mgmt-list.md
+│ └── ...
+└── appendix/
+ ├── enum-dictionary.md # All enums, status codes, type mappings
+ ├── page-relationships.md # Navigation map between pages
+ └── api-inventory.md # Complete API reference
+```
+
+#### README.md Template
+
+```markdown
+# [System Name] — Product Requirements Document
+
+## System Overview
+[2-3 paragraphs: what the system does, business context, primary users]
+
+## Module Overview
+
+| Module | Pages | Core Functionality |
+|--------|-------|--------------------|
+| User Management | User list, User detail, Role mgmt | CRUD users, assign roles and permissions |
+
+## Page Inventory
+
+| # | Page Name | Route | Module | Doc Link |
+|---|-----------|-------|--------|----------|
+| 1 | User List | /user/list | User Mgmt | [→](./pages/01-user-mgmt-list.md) |
+
+## Global Notes
+
+### Permission Model
+[Summarize auth/role system if present in code]
+
+### Common Interaction Patterns
+[Global rules: all deletes require confirmation, lists default to created_at desc, etc.]
+```
+
+#### Per-Page Document Template
+
+```markdown
+# [Page Name]
+
+> **Route:** `/xxx/xxx`
+> **Module:** [Module name]
+> **Generated:** [Date]
+
+## Overview
+[2-3 sentences: core function and use case]
+
+## Layout
+[Region breakdown — text description or ASCII diagram]
+
+## Fields
+
+### [Region: e.g. "Search Filters"]
+| Field | Type | Required | Options / Enum | Default | Notes |
+|-------|------|----------|---------------|---------|-------|
+
+### [Region: e.g. "Data Table"]
+| Column | Format | Sortable | Filterable | Notes |
+|--------|--------|----------|-----------|-------|
+
+### [Region: e.g. "Actions"]
+| Button | Visibility Condition | Behavior |
+|--------|---------------------|----------|
+
+## Interactions
+
+### Page Load
+[What happens on mount]
+
+### [Scenario: e.g. "Search"]
+- **Trigger:** [User action]
+- **Behavior:** [System response]
+- **Special rules:** [If any]
+
+### [Scenario: e.g. "Create"]
+- **Trigger:** ...
+- **Modal/drawer content:** [Fields and logic inside]
+- **Validation:** ...
+- **On success:** ...
+
+## API Dependencies
+
+| API | Method | Path | Trigger | Notes |
+|-----|--------|------|---------|-------|
+| ... | ... | ... | ... | ... |
+
+## Page Relationships
+- **From:** [Source pages + params]
+- **To:** [Target pages + params]
+- **Data coupling:** [Cross-page refresh triggers]
+
+## Business Rules
+[Anything that doesn't fit above]
+```
+
+---
+
+## Key Principles
+
+### 1. Business Language First
+Don't write "calls `useState` to manage loading state." Write "search button shows a spinner to prevent duplicate submissions."
+
+Don't write "useEffect fetches on mount." Write "page automatically loads the first page of results on open."
+
+Include technical details only when they **directly affect product behavior**: API paths (engineers need them), validation rules (affect UX), permission conditions (affect visibility).
+
+### 2. Don't Miss Hidden Logic
+Code contains logic PMs may not realize exists:
+- Field interdependencies (type A shows field X; type B shows field Y)
+- Conditional button visibility
+- Data formatting (currency with 2 decimals, date formats, status label mappings)
+- Default sort order and page size
+- Debounce/throttle effects on user input
+- Polling / auto-refresh intervals
+
+### 3. Exhaustively List Enums
+When code defines enums (status codes, type codes, role types), list **every value and its meaning**. These are often scattered across constants files, component `valueEnum` configs, or API response mappers.
+
+### 4. Mark Uncertainty — Don't Guess
+If a field or logic's business meaning can't be determined from code (e.g. abbreviated variable names, overly complex conditionals), mark it `[TBC]` and explain what you observed and why you're uncertain. Never fabricate business meaning.
+
+### 5. Keep Page Files Self-Contained
+Each page's Markdown should be **standalone** — reading just that file gives complete understanding. Use relative links when referencing other pages or appendix entries.
+
+---
+
+## Page Type Strategies
+
+### Frontend Pages
+
+| Page Type | Focus Areas |
+|-----------|------------|
+| **List / Table** | Search conditions, columns, row actions, pagination, bulk ops |
+| **Form / Create-Edit** | Every field, validation, interdependencies, post-submit behavior |
+| **Detail / View** | Displayed info, tab/section organization, available actions |
+| **Modal / Drawer** | Describe as part of triggering page — not a separate file. But fully document content |
+| **Dashboard** | Data cards, charts, metrics meaning, filter dimensions, refresh frequency |
+
+### Backend Endpoints (NestJS / Django / Express)
+
+| Endpoint Type | Focus Areas |
+|---------------|------------|
+| **CRUD resource** | All fields (from DTO/serializer), validation rules, permissions, pagination, filtering, sorting |
+| **Auth endpoints** | Login/register flow, token format, refresh logic, password reset, OAuth providers |
+| **File upload** | Accepted types, size limits, storage destination, processing pipeline |
+| **Webhook / event** | Trigger conditions, payload shape, retry policy, idempotency |
+| **Background job** | Trigger, schedule, input/output, failure handling, monitoring |
+| **Admin views** (Django) | Registered models, list_display, search_fields, filters, inline models, custom actions |
+
+---
+
+## Execution Pacing
+
+**Large projects (>15 pages):** Work in batches of 3-5 pages per module. Complete system overview + page inventory first. Output each batch for user review before proceeding.
+
+**Small projects (≤15 pages):** Complete all analysis in one pass.
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Using component names as page names | `UserManagementTable` → "User Management List" |
+| Skipping modals and drawers | They contain critical business logic — document fully |
+| Missing i18n field names | Check translation files, not just component JSX |
+| Ignoring dynamic route params | `/order/:id` = page requires an order ID to load |
+| Forgetting permission controls | Document which roles see which buttons/pages |
+| Assuming all APIs are real | Check for mock data patterns before documenting endpoints |
+| Skipping Django admin customization | `admin.py` often contains critical business rules (list filters, custom actions, inlines) |
+| Missing NestJS guards/pipes | `@UseGuards`, `@UsePipes` contain auth and validation logic that affects behavior |
+| Ignoring database constraints | Model field constraints (unique, max_length, choices) are validation rules for the PRD |
+| Overlooking middleware | Auth middleware, rate limiters, and CORS config define system-wide behavior |
+
+---
+
+## Tooling
+
+### Scripts
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/codebase_analyzer.py` | Scan codebase → extract routes, APIs, models, enums, structure | `python3 codebase_analyzer.py /path/to/project` |
+| `scripts/prd_scaffolder.py` | Generate PRD directory skeleton from analysis JSON | `python3 prd_scaffolder.py analysis.json` |
+
+**Recommended workflow:**
+```bash
+# 1. Analyze the project (JSON output — works for frontend, backend, or fullstack)
+python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json
+
+# 2. Review the analysis (markdown summary)
+python3 scripts/codebase_analyzer.py /path/to/project -f markdown
+
+# 3. Scaffold the PRD directory with stubs
+python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App"
+
+# 4. Fill in TODO sections page-by-page using the SKILL.md workflow
+```
+
+Both scripts are **stdlib-only** — no pip install needed.
+
+### References
+
+| File | Contents |
+|------|----------|
+| `references/prd-quality-checklist.md` | Validation checklist for completeness, accuracy, readability |
+| `references/framework-patterns.md` | Framework-specific patterns for routes, state, APIs, forms, permissions |
+
+---
+
+## Attribution
+
+This skill was inspired by [code-to-prd](https://github.com/lihanglogan/code-to-prd) by [@lihanglogan](https://github.com/lihanglogan), who proposed the original concept and methodology in [PR #368](https://github.com/alirezarezvani/claude-skills/pull/368). The core three-phase workflow (global scan → page-by-page analysis → structured document generation) originated from that work. This version was rebuilt from scratch in English with added tooling (analysis scripts, scaffolder, framework reference, quality checklist).
diff --git a/skills/code-to-prd/_meta.json b/skills/code-to-prd/_meta.json
new file mode 100644
index 00000000..52e5fe37
--- /dev/null
+++ b/skills/code-to-prd/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "code-to-prd",
+ "displayName": "Code To Prd",
+ "latest": {
+ "version": "2.1.1",
+ "publishedAt": 1773996995971,
+ "commit": "https://github.com/openclaw/skills/commit/09dfd14721b353c5cdd42f02fe9982a1ac659f1e"
+ },
+ "history": []
+}
diff --git a/skills/code-to-prd/assets/sample-analysis.json b/skills/code-to-prd/assets/sample-analysis.json
new file mode 100644
index 00000000..7438f6da
--- /dev/null
+++ b/skills/code-to-prd/assets/sample-analysis.json
@@ -0,0 +1,81 @@
+{
+ "project": {
+ "root": "/path/to/my-app",
+ "name": "my-app",
+ "framework": "next",
+ "detected_frameworks": ["next", "react"],
+ "key_dependencies": {
+ "next": "14.1.0",
+ "react": "18.2.0",
+ "tailwindcss": "3.4.1",
+ "axios": "1.6.5",
+ "@tanstack/react-query": "5.17.0"
+ },
+ "stack_type": "fullstack"
+ },
+ "structure": {
+ "total_files": 87,
+ "components": {
+ "components": 42,
+ "modules": 35
+ },
+ "route_dirs": ["/path/to/my-app/app"],
+ "api_dirs": ["/path/to/my-app/app/api"],
+ "state_dirs": ["/path/to/my-app/src/store"],
+ "i18n_dirs": [],
+ "controller_dirs": [],
+ "model_dirs": [],
+ "dto_dirs": []
+ },
+ "routes": {
+ "count": 8,
+ "frontend_pages": [
+ {"path": "/", "source": "app/page.tsx", "filesystem": true},
+ {"path": "/dashboard", "source": "app/dashboard/page.tsx", "filesystem": true},
+ {"path": "/users", "source": "app/users/page.tsx", "filesystem": true},
+ {"path": "/users/:id", "source": "app/users/[id]/page.tsx", "filesystem": true},
+ {"path": "/settings", "source": "app/settings/page.tsx", "filesystem": true}
+ ],
+ "backend_endpoints": [
+ {"path": "/api/users", "method": "GET", "source": "app/api/users/route.ts", "type": "backend"},
+ {"path": "/api/users", "method": "POST", "source": "app/api/users/route.ts", "type": "backend"},
+ {"path": "/api/users/:id", "method": "GET", "source": "app/api/users/[id]/route.ts", "type": "backend"}
+ ],
+ "pages": []
+ },
+ "apis": {
+ "total": 5,
+ "integrated": 4,
+ "mock": 1,
+ "endpoints": [
+ {"path": "/api/users", "method": "GET", "source": "services/user.ts", "integrated": true, "mock_detected": false},
+ {"path": "/api/users", "method": "POST", "source": "services/user.ts", "integrated": true, "mock_detected": false},
+ {"path": "/api/users/:id", "method": "GET", "source": "services/user.ts", "integrated": true, "mock_detected": false},
+ {"path": "/api/users/:id", "method": "PUT", "source": "services/user.ts", "integrated": true, "mock_detected": false},
+ {"path": "/api/dashboard/stats", "method": "GET", "source": "services/dashboard.ts", "integrated": false, "mock_detected": true}
+ ]
+ },
+ "enums": {
+ "count": 2,
+ "definitions": [
+ {"name": "UserRole", "type": "enum", "values": {"ADMIN": "admin", "USER": "user", "MANAGER": "manager"}, "source": "types/user.ts"},
+ {"name": "STATUS_MAP", "type": "constant_map", "values": {"active": "Active", "inactive": "Inactive", "suspended": "Suspended"}, "source": "constants/status.ts"}
+ ]
+ },
+ "models": {
+ "count": 0,
+ "definitions": []
+ },
+ "summary": {
+ "pages": 5,
+ "backend_endpoints": 3,
+ "api_endpoints": 5,
+ "api_integrated": 4,
+ "api_mock": 1,
+ "enums": 2,
+ "models": 0,
+ "has_i18n": false,
+ "has_state_management": true,
+ "stack_type": "fullstack"
+ }
+}
diff --git a/skills/code-to-prd/expected_outputs/sample-enum-dictionary.md b/skills/code-to-prd/expected_outputs/sample-enum-dictionary.md
new file mode 100644
index 00000000..07908ca0
--- /dev/null
+++ b/skills/code-to-prd/expected_outputs/sample-enum-dictionary.md
@@ -0,0 +1,25 @@
+# Enum Dictionary
+
+All enums, status codes, and constant mappings found in the codebase.
+
+## UserRole
+
+**Source:** `types/user.ts`
+**Type:** TypeScript enum
+
+| Value | Label | Description |
+|-------|-------|-------------|
+| `admin` | Admin | Full system access, can manage all users |
+| `manager` | Manager | Can view and edit users, cannot delete |
+| `user` | User | Read-only access |
+
+## STATUS_MAP
+
+**Source:** `constants/status.ts`
+**Type:** Constant map
+
+| Key | Display Value | Color | Description |
+|-----|--------------|-------|-------------|
+| `active` | Active | Green | Normal active account |
+| `inactive` | Inactive | Gray | Account disabled by user |
+| `suspended` | Suspended | Red | Account suspended by admin |
diff --git a/skills/code-to-prd/expected_outputs/sample-page-user-list.md b/skills/code-to-prd/expected_outputs/sample-page-user-list.md
new file mode 100644
index 00000000..569173ec
--- /dev/null
+++ b/skills/code-to-prd/expected_outputs/sample-page-user-list.md
@@ -0,0 +1,83 @@
+# User List
+
+> **Route:** `/users`
+> **Module:** User Management
+> **Generated:** 2026-03-17
+
+## Overview
+
+Displays all system users in a searchable, paginated table. Supports creating, editing, and deleting users. Only ADMIN and MANAGER roles can access this page.
+
+## Layout
+
+- **Top bar**: Search input + "Create User" button
+- **Main area**: Data table with pagination
+- **Modal**: Create/Edit user form (triggered by buttons)
+
+## Fields
+
+### Search Filters
+
+| Field | Type | Required | Options | Default | Notes |
+|-------|------|----------|---------|---------|-------|
+| Keyword | Text input | No | — | — | Searches name and email |
+| Role | Select dropdown | No | Admin, Manager, User | All | Filters by role |
+| Status | Select dropdown | No | Active, Inactive, Suspended | All | Filters by status |
+
+### Data Table
+
+| Column | Format | Sortable | Filterable | Notes |
+|--------|--------|----------|-----------|-------|
+| Name | Text | Yes | No | Full name |
+| Email | Text (link) | Yes | No | Clickable → opens detail |
+| Role | Badge | No | Yes | Color-coded by role |
+| Status | Badge | No | Yes | Green=active, Red=suspended |
+| Created | Date (YYYY-MM-DD) | Yes | No | — |
+| Actions | Buttons | No | No | Edit, Delete |
+
+### Actions
+
+| Button | Visibility | Behavior |
+|--------|-----------|----------|
+| Create User | ADMIN, MANAGER | Opens create modal |
+| Edit | ADMIN, MANAGER | Opens edit modal with prefilled data |
+| Delete | ADMIN only | Confirmation dialog → soft delete |
+
+## Interactions
+
+### Page Load
+- Fetches first page of users via `GET /api/users?page=1&size=20`
+- Default sort: `created_at` descending
+
+### Search
+- **Trigger:** User types in search field (300ms debounce)
+- **Behavior:** Re-fetches users with `keyword` param, resets to page 1
+- **Special rules:** Minimum 2 characters to trigger search
+
+### Create User
+- **Trigger:** Click "Create User" button
+- **Modal content:** Name (required, max 50), Email (required, email format), Role (required, select), Status (default: Active)
+- **Validation:** Name required + max length, Email required + format check
+- **API:** `POST /api/users` with form data
+- **On success:** Toast "User created", close modal, refresh list
+- **On failure:** Show API error below form
+
+### Delete User
+- **Trigger:** Click "Delete" button on row
+- **Behavior:** Confirmation dialog "Are you sure you want to delete {name}?"
+- **API:** `DELETE /api/users/:id`
+- **On success:** Toast "User deleted", refresh list
+
+## API Dependencies
+
+| API | Method | Path | Trigger | Notes |
+|-----|--------|------|---------|-------|
+| List users | GET | /api/users | Load, search, paginate | Params: page, size, keyword, role, status |
+| Create user | POST | /api/users | Submit create form | Body: name, email, role |
+| Delete user | DELETE | /api/users/:id | Confirm delete | — |
+
+## Page Relationships
+
+- **From:** Dashboard (click "View Users" link)
+- **To:** User Detail (click email or row)
+- **Data coupling:** Creating/deleting a user triggers dashboard stats refresh
diff --git a/skills/code-to-prd/expected_outputs/sample-prd-readme.md b/skills/code-to-prd/expected_outputs/sample-prd-readme.md
new file mode 100644
index 00000000..1f5e3159
--- /dev/null
+++ b/skills/code-to-prd/expected_outputs/sample-prd-readme.md
@@ -0,0 +1,43 @@
+# My App — Product Requirements Document
+
+## System Overview
+
+My App is a user management platform for internal teams. It provides CRUD operations for users, a dashboard with key metrics, and system settings. Built with Next.js 14 (App Router) and Tailwind CSS.
+
+## Module Overview
+
+| Module | Pages | Core Functionality |
+|--------|-------|--------------------|
+| Dashboard | Dashboard | Key metrics, activity feed |
+| User Management | User list, User detail | CRUD users, role assignment |
+| Settings | Settings | System configuration |
+
+## Page Inventory
+
+| # | Page Name | Route | Module | Doc Link |
+|---|-----------|-------|--------|----------|
+| 1 | Home | / | — | [→](./pages/01-home.md) |
+| 2 | Dashboard | /dashboard | Dashboard | [→](./pages/02-dashboard.md) |
+| 3 | User List | /users | User Mgmt | [→](./pages/03-user-list.md) |
+| 4 | User Detail | /users/:id | User Mgmt | [→](./pages/04-user-detail.md) |
+| 5 | Settings | /settings | Settings | [→](./pages/05-settings.md) |
+
+## API Inventory
+
+| # | Method | Path | Status | Notes |
+|---|--------|------|--------|-------|
+| 1 | GET | /api/users | Integrated | Paginated list |
+| 2 | POST | /api/users | Integrated | Create user |
+| 3 | GET | /api/users/:id | Integrated | User detail |
+| 4 | PUT | /api/users/:id | Integrated | Update user |
+| 5 | GET | /api/dashboard/stats | Mock | Dashboard metrics |
+
+## Global Notes
+
+### Permission Model
+Role-based access: ADMIN (full access), MANAGER (read + edit), USER (read-only).
+
+### Common Interaction Patterns
+- All delete operations require confirmation modal
+- Lists default to `created_at` descending, 20 items per page
+- Form validation shows inline errors below each field
diff --git a/skills/code-to-prd/references/framework-patterns.md b/skills/code-to-prd/references/framework-patterns.md
new file mode 100644
index 00000000..549a67fb
--- /dev/null
+++ b/skills/code-to-prd/references/framework-patterns.md
@@ -0,0 +1,228 @@
+# Framework-Specific Patterns
+
+Quick reference for identifying routes, components, state, and APIs across frontend and backend frameworks.
+
+## React (CRA / Vite)
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `react-router-dom` — `` or `createBrowserRouter` |
+| Components | `.tsx` / `.jsx` files, default exports |
+| State | Redux (`store/`), Zustand, Jotai, Recoil, React Context |
+| API | `axios`, `fetch`, TanStack Query (`useQuery`), SWR (`useSWR`) |
+| Forms | React Hook Form, Formik, Ant Design Form, custom `useState` |
+| i18n | `react-i18next`, `react-intl` |
+
+## Next.js (App Router)
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `app/` directory — `page.tsx` = route, folders = segments |
+| Layouts | `layout.tsx` per directory |
+| Loading | `loading.tsx`, `error.tsx`, `not-found.tsx` |
+| API routes | `app/api/` or `pages/api/` (Pages Router) |
+| Server actions | `"use server"` directive |
+| Middleware | `middleware.ts` at root |
+
+## Next.js (Pages Router)
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `pages/` directory — filename = route |
+| Data fetching | `getServerSideProps`, `getStaticProps`, `getStaticPaths` |
+| API routes | `pages/api/` |
+
+## Vue 3
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `vue-router` — `routes` array in `router/index.ts` |
+| Components | `.vue` SFCs (``, `');
+ await page.getByRole('button', { name: /search/i }).click();
+ await expect(page.getByRole('alert')).toBeHidden();
+ await expect(page.getByText(/no results/i)).toBeVisible();
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Basic Search', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}');
+ });
+
+ test('displays results for valid query', async ({ page }) => {
+ await page.getByRole('searchbox', { name: /search/i }).fill('{{searchQuery}}');
+ await page.getByRole('button', { name: /search/i }).click();
+ await expect(page.getByRole('list', { name: /results/i })).toBeVisible();
+ });
+
+ test('shows no-results for unmatched query', async ({ page }) => {
+ await page.getByRole('searchbox', { name: /search/i }).fill('xyzzy-no-match');
+ await page.getByRole('button', { name: /search/i }).click();
+ await expect(page.getByText(/no results|nothing found/i)).toBeVisible();
+ });
+
+ test('submits on Enter key', async ({ page }) => {
+ await page.getByRole('searchbox', { name: /search/i }).fill('{{searchQuery}}');
+ await page.keyboard.press('Enter');
+ await expect(page).toHaveURL(/[?&]q=/);
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| Valid query | Results list visible, count shown |
+| Enter key | Search submitted without clicking button |
+| Result count | Heading shows N results for query |
+| Result click | Navigates to entity detail |
+| URL pre-fill | Query param populates search box |
+| No results | Empty state message |
+| Special chars | XSS input handled, no script execution |
diff --git a/skills/cs-playwright-pro/templates/search/empty-state.md b/skills/cs-playwright-pro/templates/search/empty-state.md
new file mode 100644
index 00000000..b195919d
--- /dev/null
+++ b/skills/cs-playwright-pro/templates/search/empty-state.md
@@ -0,0 +1,109 @@
+# Empty State Template
+
+Tests no-results messaging and clear-filters behaviour.
+
+## Prerequisites
+- App running at `{{baseUrl}}`
+- Query that returns no results: `{{emptySearchQuery}}`
+
+---
+
+## TypeScript
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Empty State', () => {
+ // Happy path: no results message
+ test('shows no-results message for unmatched query', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{emptySearchQuery}}');
+ await expect(page.getByRole('heading', { name: /no results|nothing found/i })).toBeVisible();
+ await expect(page.getByText(/try.*different|adjust.*search/i)).toBeVisible();
+ });
+
+ // Happy path: clear filters CTA shown in empty state
+ test('shows "clear filters" button when filters applied with no results', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}&category={{nonExistentCategory}}');
+ await expect(page.getByText(/no results/i)).toBeVisible();
+ await expect(page.getByRole('button', { name: /clear.*filter/i })).toBeVisible();
+ });
+
+ // Happy path: clearing filters restores results
+ test('clearing filters from empty state restores results', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}&category={{nonExistentCategory}}');
+ await page.getByRole('button', { name: /clear.*filter/i }).click();
+ await expect(page.getByRole('listitem').first()).toBeVisible();
+ await expect(page.getByText(/no results/i)).toBeHidden();
+ });
+
+ // Happy path: search suggestions shown in empty state
+ test('shows related search suggestions', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{emptySearchQuery}}');
+ const suggestions = page.getByRole('list', { name: /suggestions|similar/i });
+ if (await suggestions.isVisible()) {
+ await expect(suggestions.getByRole('listitem').first()).toBeVisible();
+ }
+ });
+
+ // Happy path: empty list view (not search)
+ test('shows empty state on entity list with no data', async ({ page }) => {
+ await page.goto('{{baseUrl}}/{{entityName}}s?filter={{emptyFilter}}');
+ await expect(page.getByText(/no {{entityName}}s|empty/i)).toBeVisible();
+ await expect(page.getByRole('button', { name: /create|add new/i })).toBeVisible();
+ });
+
+ // Error case: network error shows error state not empty state
+ test('distinguishes network error from no-results', async ({ page }) => {
+ await page.route('{{baseUrl}}/api/search*', route => route.abort('failed'));
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}');
+ await expect(page.getByText(/error|something went wrong/i)).toBeVisible();
+ await expect(page.getByText(/no results/i)).toBeHidden();
+ });
+
+ // Edge case: empty state after removing last item
+ test('shows empty state after deleting last item in list', async ({ page }) => {
+ await page.goto('{{baseUrl}}/{{entityName}}s');
+ const row = page.getByRole('row').filter({ hasNot: page.getByRole('columnheader') }).last();
+ await row.getByRole('button', { name: /delete/i }).click();
+ await page.getByRole('dialog').getByRole('button', { name: /confirm/i }).click();
+ await expect(page.getByText(/no {{entityName}}s|empty/i)).toBeVisible();
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Empty State', () => {
+ test('shows no-results message for unmatched query', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{emptySearchQuery}}');
+ await expect(page.getByRole('heading', { name: /no results|nothing found/i })).toBeVisible();
+ });
+
+ test('shows clear-filters button in no-results state', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}&category={{nonExistentCategory}}');
+ await expect(page.getByRole('button', { name: /clear.*filter/i })).toBeVisible();
+ });
+
+ test('clearing filters restores results', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}&category={{nonExistentCategory}}');
+ await page.getByRole('button', { name: /clear.*filter/i }).click();
+ await expect(page.getByRole('listitem').first()).toBeVisible();
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| No-results query | Heading + suggestion text shown |
+| Filter no-results | Clear-filters CTA displayed |
+| Clear filters | Removes filter, results return |
+| Search suggestions | Related terms listed when available |
+| Empty list view | Entity list empty state with create CTA |
+| Network error | Error state distinct from no-results |
+| Last item deleted | Empty state shown after deletion |
diff --git a/skills/cs-playwright-pro/templates/search/filters.md b/skills/cs-playwright-pro/templates/search/filters.md
new file mode 100644
index 00000000..337be376
--- /dev/null
+++ b/skills/cs-playwright-pro/templates/search/filters.md
@@ -0,0 +1,128 @@
+# Search Filters Template
+
+Tests category filter, price range, and checkbox filters.
+
+## Prerequisites
+- Search results available for `{{searchQuery}}`
+- Category `{{filterCategory}}` with items
+- App running at `{{baseUrl}}`
+
+---
+
+## TypeScript
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Search Filters', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}');
+ });
+
+ // Happy path: category filter
+ test('filters results by category', async ({ page }) => {
+ await page.getByRole('checkbox', { name: '{{filterCategory}}' }).check();
+ await expect(page).toHaveURL(/category={{filterCategory}}/);
+ const results = page.getByRole('listitem');
+ await expect(results.first()).toContainText('{{filterCategory}}');
+ const count = await results.count();
+ expect(count).toBeGreaterThan(0);
+ });
+
+ // Happy path: price range filter
+ test('filters results by price range', async ({ page }) => {
+ const minInput = page.getByRole('spinbutton', { name: /min.*price/i });
+ const maxInput = page.getByRole('spinbutton', { name: /max.*price/i });
+ await minInput.fill('{{minPrice}}');
+ await maxInput.fill('{{maxPrice}}');
+ await page.getByRole('button', { name: /apply|filter/i }).click();
+ await expect(page).toHaveURL(/min_price={{minPrice}}/);
+ // Verify no results exceed max price
+ const prices = page.getByTestId('item-price');
+ const priceCount = await prices.count();
+ for (let i = 0; i < priceCount; i++) {
+ const text = await prices.nth(i).textContent() ?? '';
+ const value = parseFloat(text.replace(/[^0-9.]/g, ''));
+ expect(value).toBeLessThanOrEqual({{maxPrice}});
+ }
+ });
+
+ // Happy path: multiple checkboxes combine filters
+ test('applies multiple checkbox filters simultaneously', async ({ page }) => {
+ await page.getByRole('checkbox', { name: '{{filterOption1}}' }).check();
+ await page.getByRole('checkbox', { name: '{{filterOption2}}' }).check();
+ await expect(page).toHaveURL(/{{filterParam1}}.*{{filterParam2}}|{{filterParam2}}.*{{filterParam1}}/);
+ });
+
+ // Happy path: active filters shown as chips
+ test('shows active filter chips', async ({ page }) => {
+ await page.getByRole('checkbox', { name: '{{filterCategory}}' }).check();
+ await expect(page.getByRole('button', { name: /remove.*{{filterCategory}}/i })).toBeVisible();
+ });
+
+ // Happy path: clear individual filter chip
+ test('removes filter by clicking chip close', async ({ page }) => {
+ await page.getByRole('checkbox', { name: '{{filterCategory}}' }).check();
+ await page.getByRole('button', { name: /remove.*{{filterCategory}}/i }).click();
+ await expect(page.getByRole('checkbox', { name: '{{filterCategory}}' })).not.toBeChecked();
+ });
+
+ // Happy path: clear all filters
+ test('clears all filters', async ({ page }) => {
+ await page.getByRole('checkbox', { name: '{{filterCategory}}' }).check();
+ await page.getByRole('button', { name: /clear all filters/i }).click();
+ await expect(page.getByRole('checkbox', { name: '{{filterCategory}}' })).not.toBeChecked();
+ await expect(page).not.toHaveURL(/category=/);
+ });
+
+ // Error case: no results for filter combination
+ test('shows empty state when filters yield no results', async ({ page }) => {
+ await page.getByRole('spinbutton', { name: /min.*price/i }).fill('999999');
+ await page.getByRole('button', { name: /apply|filter/i }).click();
+ await expect(page.getByText(/no results/i)).toBeVisible();
+ await expect(page.getByRole('button', { name: /clear.*filter/i })).toBeVisible();
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Search Filters', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}');
+ });
+
+ test('filters results by category', async ({ page }) => {
+ await page.getByRole('checkbox', { name: '{{filterCategory}}' }).check();
+ await expect(page).toHaveURL(/category={{filterCategory}}/);
+ await expect(page.getByRole('listitem').first()).toBeVisible();
+ });
+
+ test('shows active filter chips', async ({ page }) => {
+ await page.getByRole('checkbox', { name: '{{filterCategory}}' }).check();
+ await expect(page.getByRole('button', { name: /remove.*{{filterCategory}}/i })).toBeVisible();
+ });
+
+ test('clears all filters', async ({ page }) => {
+ await page.getByRole('checkbox', { name: '{{filterCategory}}' }).check();
+ await page.getByRole('button', { name: /clear all filters/i }).click();
+ await expect(page.getByRole('checkbox', { name: '{{filterCategory}}' })).not.toBeChecked();
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| Category filter | Checkbox → results scoped to category |
+| Price range | Min/max filter applied, prices verified |
+| Multi-filter | Multiple checkboxes combine in URL |
+| Filter chips | Active filters shown as removable chips |
+| Remove chip | Chip close → filter unchecked |
+| Clear all | All filters removed at once |
+| No-results combo | Filter combination yields empty state |
diff --git a/skills/cs-playwright-pro/templates/search/pagination.md b/skills/cs-playwright-pro/templates/search/pagination.md
new file mode 100644
index 00000000..eba1c82f
--- /dev/null
+++ b/skills/cs-playwright-pro/templates/search/pagination.md
@@ -0,0 +1,123 @@
+# Pagination Template
+
+Tests page navigation, items-per-page selector, and URL state.
+
+## Prerequisites
+- Search results for `{{searchQuery}}` spanning multiple pages
+- At least `{{totalItemCount}}` items total
+- App running at `{{baseUrl}}`
+
+---
+
+## TypeScript
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Pagination', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}');
+ });
+
+ // Happy path: navigate to next page
+ test('navigates to next page and updates URL', async ({ page }) => {
+ const firstItem = await page.getByRole('listitem').first().textContent();
+ await page.getByRole('button', { name: /next page/i }).click();
+ await expect(page).toHaveURL(/page=2/);
+ await expect(page.getByRole('listitem').first()).not.toHaveText(firstItem!);
+ });
+
+ // Happy path: navigate to previous page
+ test('navigates to previous page', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}&page=2');
+ const secondPageFirst = await page.getByRole('listitem').first().textContent();
+ await page.getByRole('button', { name: /previous page/i }).click();
+ await expect(page).toHaveURL(/page=1/);
+ await expect(page.getByRole('listitem').first()).not.toHaveText(secondPageFirst!);
+ });
+
+ // Happy path: jump to specific page
+ test('jumps to specific page number', async ({ page }) => {
+ await page.getByRole('button', { name: '3' }).click();
+ await expect(page).toHaveURL(/page=3/);
+ await expect(page.getByRole('button', { name: '3' })).toHaveAttribute('aria-current', 'page');
+ });
+
+ // Happy path: items per page selector
+ test('changes items per page', async ({ page }) => {
+ await page.getByRole('combobox', { name: /per page/i }).selectOption('50');
+ await expect(page).toHaveURL(/per_page=50/);
+ const items = page.getByRole('listitem');
+ await expect(items).toHaveCount(Math.min(50, {{totalItemCount}}));
+ });
+
+ // Happy path: page info text
+ test('shows correct page info text', async ({ page }) => {
+ await expect(page.getByText(/showing \d+.+of\s+{{totalItemCount}}/i)).toBeVisible();
+ });
+
+ // Error case: first page has no previous button
+ test('previous page button disabled on first page', async ({ page }) => {
+ await expect(page.getByRole('button', { name: /previous page/i })).toBeDisabled();
+ });
+
+ // Error case: last page has no next button
+ test('next page button disabled on last page', async ({ page }) => {
+ const lastPage = Math.ceil({{totalItemCount}} / {{defaultPageSize}});
+ await page.goto(`{{baseUrl}}/search?q={{searchQuery}}&page=${lastPage}`);
+ await expect(page.getByRole('button', { name: /next page/i })).toBeDisabled();
+ });
+
+ // Edge case: out-of-range page redirects to last page
+ test('out-of-range page parameter redirects gracefully', async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}&page=99999');
+ await expect(page.getByRole('listitem').first()).toBeVisible();
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Pagination', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}');
+ });
+
+ test('navigates to next page', async ({ page }) => {
+ await page.getByRole('button', { name: /next page/i }).click();
+ await expect(page).toHaveURL(/page=2/);
+ });
+
+ test('previous page disabled on first page', async ({ page }) => {
+ await expect(page.getByRole('button', { name: /previous page/i })).toBeDisabled();
+ });
+
+ test('next page disabled on last page', async ({ page }) => {
+ const last = Math.ceil({{totalItemCount}} / {{defaultPageSize}});
+ await page.goto(`{{baseUrl}}/search?q={{searchQuery}}&page=${last}`);
+ await expect(page.getByRole('button', { name: /next page/i })).toBeDisabled();
+ });
+
+ test('changes items per page', async ({ page }) => {
+ await page.getByRole('combobox', { name: /per page/i }).selectOption('50');
+ await expect(page).toHaveURL(/per_page=50/);
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| Next page | Items change, URL updates page=2 |
+| Previous page | Back to page 1 |
+| Jump to page | Clicking page number sets aria-current |
+| Items per page | Selector changes count of visible items |
+| Page info | "Showing X-Y of N" text |
+| First page prev | Previous button disabled |
+| Last page next | Next button disabled |
+| Out-of-range | Graceful fallback |
diff --git a/skills/cs-playwright-pro/templates/search/sorting.md b/skills/cs-playwright-pro/templates/search/sorting.md
new file mode 100644
index 00000000..cd8ca9b7
--- /dev/null
+++ b/skills/cs-playwright-pro/templates/search/sorting.md
@@ -0,0 +1,131 @@
+# Search Sorting Template
+
+Tests sorting results by name, date, and price.
+
+## Prerequisites
+- Search results for `{{searchQuery}}` with multiple items
+- App running at `{{baseUrl}}`
+
+---
+
+## TypeScript
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Search Sorting', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}');
+ });
+
+ // Happy path: sort by name A-Z
+ test('sorts results alphabetically A-Z', async ({ page }) => {
+ await page.getByRole('combobox', { name: /sort by/i }).selectOption('name_asc');
+ await expect(page).toHaveURL(/sort=name_asc/);
+ const names = page.getByTestId('result-name');
+ const first = await names.first().textContent();
+ const second = await names.nth(1).textContent();
+ expect(first!.localeCompare(second!)).toBeLessThanOrEqual(0);
+ });
+
+ // Happy path: sort by name Z-A
+ test('sorts results alphabetically Z-A', async ({ page }) => {
+ await page.getByRole('combobox', { name: /sort by/i }).selectOption('name_desc');
+ const names = page.getByTestId('result-name');
+ const first = await names.first().textContent();
+ const second = await names.nth(1).textContent();
+ expect(first!.localeCompare(second!)).toBeGreaterThanOrEqual(0);
+ });
+
+ // Happy path: sort by date newest
+ test('sorts results by newest date first', async ({ page }) => {
+ await page.getByRole('combobox', { name: /sort by/i }).selectOption('date_desc');
+ await expect(page).toHaveURL(/sort=date_desc/);
+ const dates = page.getByTestId('result-date');
+ const firstDate = new Date(await dates.first().getAttribute('datetime') ?? '');
+ const secondDate = new Date(await dates.nth(1).getAttribute('datetime') ?? '');
+ expect(firstDate.getTime()).toBeGreaterThanOrEqual(secondDate.getTime());
+ });
+
+ // Happy path: sort by price low-high
+ test('sorts by price low to high', async ({ page }) => {
+ await page.getByRole('combobox', { name: /sort by/i }).selectOption('price_asc');
+ const prices = page.getByTestId('result-price');
+ const firstText = await prices.first().textContent() ?? '';
+ const secondText = await prices.nth(1).textContent() ?? '';
+ const first = parseFloat(firstText.replace(/[^0-9.]/g, ''));
+ const second = parseFloat(secondText.replace(/[^0-9.]/g, ''));
+ expect(first).toBeLessThanOrEqual(second);
+ });
+
+ // Happy path: sort by price high-low
+ test('sorts by price high to low', async ({ page }) => {
+ await page.getByRole('combobox', { name: /sort by/i }).selectOption('price_desc');
+ const prices = page.getByTestId('result-price');
+ const firstText = await prices.first().textContent() ?? '';
+ const secondText = await prices.nth(1).textContent() ?? '';
+ const first = parseFloat(firstText.replace(/[^0-9.]/g, ''));
+ const second = parseFloat(secondText.replace(/[^0-9.]/g, ''));
+ expect(first).toBeGreaterThanOrEqual(second);
+ });
+
+ // Happy path: sort persists with filters
+ test('sort selection persists when filter applied', async ({ page }) => {
+ await page.getByRole('combobox', { name: /sort by/i }).selectOption('price_asc');
+ await page.getByRole('checkbox', { name: '{{filterCategory}}' }).check();
+ await expect(page).toHaveURL(/sort=price_asc/);
+ await expect(page.getByRole('combobox', { name: /sort by/i })).toHaveValue('price_asc');
+ });
+
+ // Edge case: default sort is relevance
+ test('default sort is relevance', async ({ page }) => {
+ await expect(page.getByRole('combobox', { name: /sort by/i })).toHaveValue('relevance');
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Search Sorting', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/search?q={{searchQuery}}');
+ });
+
+ test('sorts alphabetically A-Z', async ({ page }) => {
+ await page.getByRole('combobox', { name: /sort by/i }).selectOption('name_asc');
+ await expect(page).toHaveURL(/sort=name_asc/);
+ const names = page.getByTestId('result-name');
+ const first = await names.first().textContent();
+ const second = await names.nth(1).textContent();
+ expect(first.localeCompare(second)).toBeLessThanOrEqual(0);
+ });
+
+ test('sorts by price low to high', async ({ page }) => {
+ await page.getByRole('combobox', { name: /sort by/i }).selectOption('price_asc');
+ const prices = page.getByTestId('result-price');
+ const a = parseFloat((await prices.first().textContent()).replace(/[^0-9.]/g, ''));
+ const b = parseFloat((await prices.nth(1).textContent()).replace(/[^0-9.]/g, ''));
+ expect(a).toBeLessThanOrEqual(b);
+ });
+
+ test('default sort is relevance', async ({ page }) => {
+ await expect(page.getByRole('combobox', { name: /sort by/i })).toHaveValue('relevance');
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| Name A-Z | First result ≤ second alphabetically |
+| Name Z-A | First result ≥ second alphabetically |
+| Date newest | Dates in descending order |
+| Price low-high | Prices in ascending order |
+| Price high-low | Prices in descending order |
+| Sort + filter | Sort param persists when filter applied |
+| Default sort | Relevance selected by default |
diff --git a/skills/cs-playwright-pro/templates/settings/account-delete.md b/skills/cs-playwright-pro/templates/settings/account-delete.md
new file mode 100644
index 00000000..18e0d553
--- /dev/null
+++ b/skills/cs-playwright-pro/templates/settings/account-delete.md
@@ -0,0 +1,136 @@
+# Account Delete Template
+
+Tests account deletion flow with confirmation and data warning.
+
+## Prerequisites
+- Authenticated session via `{{authStorageStatePath}}`
+- Disposable test account (deletion is irreversible)
+- Settings at `{{baseUrl}}/settings/account`
+
+---
+
+## TypeScript
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Account Delete', () => {
+ test.use({ storageState: '{{authStorageStatePath}}' });
+
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/account');
+ });
+
+ // Happy path: delete button opens confirmation
+ test('clicking delete account shows confirmation dialog', async ({ page }) => {
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ const dialog = page.getByRole('dialog', { name: /delete account/i });
+ await expect(dialog).toBeVisible();
+ await expect(dialog).toContainText(/irreversible|cannot be undone/i);
+ await expect(dialog).toContainText(/{{dataWarningText}}/i);
+ });
+
+ // Happy path: cancel preserves account
+ test('cancel keeps account intact', async ({ page }) => {
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ await page.getByRole('dialog').getByRole('button', { name: /cancel/i }).click();
+ await expect(page.getByRole('dialog')).toBeHidden();
+ await expect(page).toHaveURL('{{baseUrl}}/settings/account');
+ });
+
+ // Happy path: type-to-confirm gates deletion
+ test('confirm button disabled until account email typed', async ({ page }) => {
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ const dialog = page.getByRole('dialog');
+ const confirmBtn = dialog.getByRole('button', { name: /delete.*account|confirm/i });
+ await expect(confirmBtn).toBeDisabled();
+ await dialog.getByRole('textbox', { name: /type.*email/i }).fill('{{username}}');
+ await expect(confirmBtn).toBeEnabled();
+ });
+
+ // Happy path: successful deletion redirects to login
+ test('deletes account and redirects to login', async ({ page }) => {
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ const dialog = page.getByRole('dialog');
+ await dialog.getByRole('textbox', { name: /type.*email/i }).fill('{{username}}');
+ await dialog.getByRole('button', { name: /delete.*account|confirm/i }).click();
+ await expect(page).toHaveURL(/\/login/);
+ await expect(page.getByText(/account.*deleted|successfully deleted/i)).toBeVisible();
+ });
+
+ // Error case: wrong email in confirmation box
+ test('shows error when wrong email typed in confirmation', async ({ page }) => {
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ const dialog = page.getByRole('dialog');
+ await dialog.getByRole('textbox', { name: /type.*email/i }).fill('wrong@email.com');
+ const confirmBtn = dialog.getByRole('button', { name: /delete.*account|confirm/i });
+ await expect(confirmBtn).toBeDisabled();
+ await expect(dialog.getByText(/does not match/i)).toBeVisible();
+ });
+
+ // Error case: deletion fails server-side
+ test('shows error when account deletion fails', async ({ page }) => {
+ await page.route('{{baseUrl}}/api/account', route =>
+ route.fulfill({ status: 500, body: JSON.stringify({ error: 'Deletion failed' }) })
+ );
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ const dialog = page.getByRole('dialog');
+ await dialog.getByRole('textbox', { name: /type.*email/i }).fill('{{username}}');
+ await dialog.getByRole('button', { name: /confirm/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/failed|error/i);
+ await expect(page).toHaveURL('{{baseUrl}}/settings/account');
+ });
+
+ // Edge case: data export offered before deletion
+ test('shows data export option in deletion dialog', async ({ page }) => {
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ await expect(page.getByRole('link', { name: /export.*data|download.*data/i })).toBeVisible();
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Account Delete', () => {
+ test.use({ storageState: '{{authStorageStatePath}}' });
+
+ test('shows confirmation dialog on delete', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/account');
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ await expect(page.getByRole('dialog', { name: /delete account/i })).toBeVisible();
+ await expect(page.getByRole('dialog')).toContainText(/irreversible/i);
+ });
+
+ test('confirm button disabled until email typed', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/account');
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ const dialog = page.getByRole('dialog');
+ await expect(dialog.getByRole('button', { name: /confirm/i })).toBeDisabled();
+ await dialog.getByRole('textbox', { name: /type.*email/i }).fill('{{username}}');
+ await expect(dialog.getByRole('button', { name: /confirm/i })).toBeEnabled();
+ });
+
+ test('cancel preserves account', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/account');
+ await page.getByRole('button', { name: /delete.*account/i }).click();
+ await page.getByRole('dialog').getByRole('button', { name: /cancel/i }).click();
+ await expect(page).toHaveURL('{{baseUrl}}/settings/account');
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| Dialog opens | Delete button → confirmation with warning |
+| Cancel | Dialog closed, account preserved |
+| Type-to-confirm | Button enabled only with correct email |
+| Successful delete | Account deleted → /login |
+| Wrong email | Input mismatch → button stays disabled |
+| Server error | Deletion fails → error alert |
+| Data export | Export link offered in dialog |
diff --git a/skills/cs-playwright-pro/templates/settings/notification-prefs.md b/skills/cs-playwright-pro/templates/settings/notification-prefs.md
new file mode 100644
index 00000000..838cae51
--- /dev/null
+++ b/skills/cs-playwright-pro/templates/settings/notification-prefs.md
@@ -0,0 +1,139 @@
+# Notification Preferences Template
+
+Tests toggling notification channels and saving preferences.
+
+## Prerequisites
+- Authenticated session via `{{authStorageStatePath}}`
+- Settings page at `{{baseUrl}}/settings/notifications`
+
+---
+
+## TypeScript
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Notification Preferences', () => {
+ test.use({ storageState: '{{authStorageStatePath}}' });
+
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/notifications');
+ });
+
+ // Happy path: enable email notifications
+ test('enables email notifications', async ({ page }) => {
+ const emailToggle = page.getByRole('switch', { name: /email notifications/i });
+ if (!(await emailToggle.isChecked())) {
+ await emailToggle.click();
+ }
+ await expect(emailToggle).toBeChecked();
+ await page.getByRole('button', { name: /save|update/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/preferences.*saved|updated/i);
+ });
+
+ // Happy path: disable push notifications
+ test('disables push notifications', async ({ page }) => {
+ const pushToggle = page.getByRole('switch', { name: /push notifications/i });
+ if (await pushToggle.isChecked()) {
+ await pushToggle.click();
+ }
+ await expect(pushToggle).not.toBeChecked();
+ await page.getByRole('button', { name: /save/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/saved/i);
+ });
+
+ // Happy path: preferences persist after reload
+ test('saved preferences persist after page reload', async ({ page }) => {
+ const emailToggle = page.getByRole('switch', { name: /email notifications/i });
+ const wasChecked = await emailToggle.isChecked();
+ await emailToggle.click();
+ await page.getByRole('button', { name: /save/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/saved/i);
+ await page.reload();
+ if (wasChecked) {
+ await expect(emailToggle).not.toBeChecked();
+ } else {
+ await expect(emailToggle).toBeChecked();
+ }
+ });
+
+ // Happy path: notification frequency selector
+ test('changes notification frequency', async ({ page }) => {
+ await page.getByRole('combobox', { name: /frequency|digest/i }).selectOption('{{frequency}}');
+ await page.getByRole('button', { name: /save/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/saved/i);
+ await page.reload();
+ await expect(page.getByRole('combobox', { name: /frequency|digest/i })).toHaveValue('{{frequency}}');
+ });
+
+ // Error case: save fails — preferences not changed
+ test('shows error when save fails', async ({ page }) => {
+ await page.route('{{baseUrl}}/api/settings/notifications*', route =>
+ route.fulfill({ status: 500, body: JSON.stringify({ error: 'Server error' }) })
+ );
+ await page.getByRole('switch', { name: /email notifications/i }).click();
+ await page.getByRole('button', { name: /save/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/error|failed to save/i);
+ });
+
+ // Edge case: unsubscribe all shows confirmation
+ test('shows confirmation before unsubscribing all', async ({ page }) => {
+ await page.getByRole('button', { name: /unsubscribe all/i }).click();
+ await expect(page.getByRole('dialog', { name: /unsubscribe/i })).toBeVisible();
+ await page.getByRole('button', { name: /cancel/i }).click();
+ // Still subscribed
+ await expect(page.getByRole('switch', { name: /email notifications/i })).toBeChecked();
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Notification Preferences', () => {
+ test.use({ storageState: '{{authStorageStatePath}}' });
+
+ test('saves notification preferences', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/notifications');
+ const toggle = page.getByRole('switch', { name: /email notifications/i });
+ await toggle.click();
+ await page.getByRole('button', { name: /save/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/saved/i);
+ });
+
+ test('preferences persist after reload', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/notifications');
+ const toggle = page.getByRole('switch', { name: /email notifications/i });
+ const was = await toggle.isChecked();
+ await toggle.click();
+ await page.getByRole('button', { name: /save/i }).click();
+ await page.reload();
+ was
+ ? await expect(toggle).not.toBeChecked()
+ : await expect(toggle).toBeChecked();
+ });
+
+ test('shows error when save fails', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/notifications');
+ await page.route('{{baseUrl}}/api/settings/notifications*', r =>
+ r.fulfill({ status: 500, body: '{}' })
+ );
+ await page.getByRole('button', { name: /save/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/error|failed/i);
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| Enable email | Toggle on → saved → success |
+| Disable push | Toggle off → saved |
+| Persists reload | Saved state survives page reload |
+| Frequency selector | Dropdown value saved and restored |
+| Save error | Server error → error alert |
+| Unsubscribe all | Confirmation dialog before all disabled |
diff --git a/skills/cs-playwright-pro/templates/settings/password-change.md b/skills/cs-playwright-pro/templates/settings/password-change.md
new file mode 100644
index 00000000..47475702
--- /dev/null
+++ b/skills/cs-playwright-pro/templates/settings/password-change.md
@@ -0,0 +1,143 @@
+# Password Change Template
+
+Tests current password verification, new password validation, and success flow.
+
+## Prerequisites
+- Authenticated session via `{{authStorageStatePath}}`
+- Current password: `{{currentPassword}}`
+- New password: `{{newPassword}}`
+
+---
+
+## TypeScript
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Password Change', () => {
+ test.use({ storageState: '{{authStorageStatePath}}' });
+
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/security');
+ });
+
+ // Happy path: successful password change
+ test('changes password with valid inputs', async ({ page }) => {
+ await page.getByRole('textbox', { name: /current password/i }).fill('{{currentPassword}}');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('{{newPassword}}');
+ await page.getByRole('textbox', { name: /confirm.*password/i }).fill('{{newPassword}}');
+ await page.getByRole('button', { name: /change.*password|update password/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/password.*changed|updated successfully/i);
+ });
+
+ // Happy path: can log in with new password
+ test('new password accepted on next login', async ({ page, context }) => {
+ // Change password
+ await page.getByRole('textbox', { name: /current password/i }).fill('{{currentPassword}}');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('{{newPassword}}');
+ await page.getByRole('textbox', { name: /confirm.*password/i }).fill('{{newPassword}}');
+ await page.getByRole('button', { name: /change.*password/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/changed/i);
+ // Log out and back in
+ await page.getByRole('button', { name: /user menu/i }).click();
+ await page.getByRole('menuitem', { name: /sign out/i }).click();
+ await page.getByRole('textbox', { name: /email/i }).fill('{{username}}');
+ await page.getByRole('textbox', { name: /password/i }).fill('{{newPassword}}');
+ await page.getByRole('button', { name: /sign in/i }).click();
+ await expect(page).toHaveURL('{{baseUrl}}/dashboard');
+ });
+
+ // Error case: wrong current password
+ test('shows error when current password is wrong', async ({ page }) => {
+ await page.getByRole('textbox', { name: /current password/i }).fill('wrong-password');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('{{newPassword}}');
+ await page.getByRole('textbox', { name: /confirm.*password/i }).fill('{{newPassword}}');
+ await page.getByRole('button', { name: /change.*password/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/current password.*incorrect|wrong password/i);
+ });
+
+ // Error case: new passwords do not match
+ test('shows error when confirmation does not match', async ({ page }) => {
+ await page.getByRole('textbox', { name: /current password/i }).fill('{{currentPassword}}');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('{{newPassword}}');
+ await page.getByRole('textbox', { name: /confirm.*password/i }).fill('mismatch');
+ await page.getByRole('button', { name: /change.*password/i }).click();
+ await expect(page.getByText(/passwords.*do not match/i)).toBeVisible();
+ });
+
+ // Error case: new password too weak
+ test('shows strength error for weak new password', async ({ page }) => {
+ await page.getByRole('textbox', { name: /current password/i }).fill('{{currentPassword}}');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('123');
+ await page.getByRole('textbox', { name: /^new password$/i }).blur();
+ await expect(page.getByText(/too weak|at least \d+ characters/i)).toBeVisible();
+ });
+
+ // Error case: new password same as current
+ test('shows error when new password matches current', async ({ page }) => {
+ await page.getByRole('textbox', { name: /current password/i }).fill('{{currentPassword}}');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('{{currentPassword}}');
+ await page.getByRole('textbox', { name: /confirm.*password/i }).fill('{{currentPassword}}');
+ await page.getByRole('button', { name: /change.*password/i }).click();
+ await expect(page.getByText(/same as.*current|choose.*different/i)).toBeVisible();
+ });
+
+ // Edge case: password strength meter updates on input
+ test('strength meter reacts to new password input', async ({ page }) => {
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('weak');
+ await expect(page.getByRole('meter', { name: /strength/i })).toHaveAttribute('aria-valuenow', '1');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('Str0ng!Pass#2026');
+ await expect(page.getByRole('meter', { name: /strength/i })).toHaveAttribute('aria-valuenow', '4');
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Password Change', () => {
+ test.use({ storageState: '{{authStorageStatePath}}' });
+
+ test('changes password with valid inputs', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/security');
+ await page.getByRole('textbox', { name: /current password/i }).fill('{{currentPassword}}');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('{{newPassword}}');
+ await page.getByRole('textbox', { name: /confirm.*password/i }).fill('{{newPassword}}');
+ await page.getByRole('button', { name: /change.*password/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/changed|updated/i);
+ });
+
+ test('shows error for wrong current password', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/security');
+ await page.getByRole('textbox', { name: /current password/i }).fill('wrong');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('{{newPassword}}');
+ await page.getByRole('textbox', { name: /confirm.*password/i }).fill('{{newPassword}}');
+ await page.getByRole('button', { name: /change.*password/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/incorrect|wrong/i);
+ });
+
+ test('shows mismatch error', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/security');
+ await page.getByRole('textbox', { name: /current password/i }).fill('{{currentPassword}}');
+ await page.getByRole('textbox', { name: /^new password$/i }).fill('{{newPassword}}');
+ await page.getByRole('textbox', { name: /confirm.*password/i }).fill('nope');
+ await page.getByRole('button', { name: /change.*password/i }).click();
+ await expect(page.getByText(/do not match/i)).toBeVisible();
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| Success | All fields valid → success alert |
+| Login with new pw | New password accepted at login |
+| Wrong current | Incorrect current → error alert |
+| Mismatch | Confirm ≠ new → validation error |
+| Weak password | Short password → strength error |
+| Same as current | Reuse blocked with error |
+| Strength meter | Meter aria-valuenow updates on input |
diff --git a/skills/cs-playwright-pro/templates/settings/profile-update.md b/skills/cs-playwright-pro/templates/settings/profile-update.md
new file mode 100644
index 00000000..52cd68d2
--- /dev/null
+++ b/skills/cs-playwright-pro/templates/settings/profile-update.md
@@ -0,0 +1,130 @@
+# Profile Update Template
+
+Tests updating name, email, and avatar in user profile settings.
+
+## Prerequisites
+- Authenticated session via `{{authStorageStatePath}}`
+- Current name: `{{currentName}}`, email: `{{currentEmail}}`
+- Test avatar image: `{{avatarFilePath}}`
+
+---
+
+## TypeScript
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Profile Update', () => {
+ test.use({ storageState: '{{authStorageStatePath}}' });
+
+ test.beforeEach(async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/profile');
+ });
+
+ // Happy path: update display name
+ test('updates display name', async ({ page }) => {
+ const nameField = page.getByRole('textbox', { name: /display name|full name/i });
+ await nameField.clear();
+ await nameField.fill('{{newName}}');
+ await page.getByRole('button', { name: /save|update/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/profile updated|saved/i);
+ await expect(page.getByRole('textbox', { name: /display name|full name/i })).toHaveValue('{{newName}}');
+ });
+
+ // Happy path: update email
+ test('updates email address', async ({ page }) => {
+ const emailField = page.getByRole('textbox', { name: /email/i });
+ await emailField.clear();
+ await emailField.fill('{{newEmail}}');
+ await page.getByRole('button', { name: /save|update/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/verification.*sent|email updated/i);
+ });
+
+ // Happy path: upload avatar
+ test('uploads new avatar image', async ({ page }) => {
+ await page.getByRole('button', { name: /change.*avatar|upload.*photo/i }).click();
+ await page.locator('input[type="file"]').setInputFiles('{{avatarFilePath}}');
+ await expect(page.getByRole('img', { name: /avatar preview/i })).toBeVisible();
+ await page.getByRole('button', { name: /save|apply/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/avatar updated|photo saved/i);
+ });
+
+ // Happy path: avatar crop dialog
+ test('shows crop dialog after avatar upload', async ({ page }) => {
+ await page.locator('input[type="file"]').setInputFiles('{{avatarFilePath}}');
+ await expect(page.getByRole('dialog', { name: /crop/i })).toBeVisible();
+ await page.getByRole('button', { name: /apply crop/i }).click();
+ await expect(page.getByRole('dialog', { name: /crop/i })).toBeHidden();
+ });
+
+ // Error case: invalid email format
+ test('shows error for invalid email format', async ({ page }) => {
+ await page.getByRole('textbox', { name: /email/i }).clear();
+ await page.getByRole('textbox', { name: /email/i }).fill('bad-email');
+ await page.getByRole('button', { name: /save|update/i }).click();
+ await expect(page.getByText(/valid.*email/i)).toBeVisible();
+ });
+
+ // Error case: email already taken
+ test('shows error when email is already in use', async ({ page }) => {
+ await page.getByRole('textbox', { name: /email/i }).clear();
+ await page.getByRole('textbox', { name: /email/i }).fill('{{takenEmail}}');
+ await page.getByRole('button', { name: /save|update/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/already in use|taken/i);
+ });
+
+ // Edge case: name reflected in nav after update
+ test('nav shows updated name after save', async ({ page }) => {
+ const nameField = page.getByRole('textbox', { name: /display name|full name/i });
+ await nameField.clear();
+ await nameField.fill('{{newName}}');
+ await page.getByRole('button', { name: /save|update/i }).click();
+ await expect(page.getByRole('navigation').getByText('{{newName}}')).toBeVisible();
+ });
+});
+```
+
+---
+
+## JavaScript
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Profile Update', () => {
+ test.use({ storageState: '{{authStorageStatePath}}' });
+
+ test('updates display name', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/profile');
+ await page.getByRole('textbox', { name: /display name|full name/i }).clear();
+ await page.getByRole('textbox', { name: /display name|full name/i }).fill('{{newName}}');
+ await page.getByRole('button', { name: /save|update/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/profile updated|saved/i);
+ });
+
+ test('shows error for invalid email', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/profile');
+ await page.getByRole('textbox', { name: /email/i }).fill('bad-email');
+ await page.getByRole('button', { name: /save|update/i }).click();
+ await expect(page.getByText(/valid.*email/i)).toBeVisible();
+ });
+
+ test('uploads avatar image', async ({ page }) => {
+ await page.goto('{{baseUrl}}/settings/profile');
+ await page.locator('input[type="file"]').setInputFiles('{{avatarFilePath}}');
+ await page.getByRole('button', { name: /save|apply/i }).click();
+ await expect(page.getByRole('alert')).toContainText(/avatar updated/i);
+ });
+});
+```
+
+## Variants
+| Variant | Description |
+|---------|-------------|
+| Name update | Name saved, field reflects new value |
+| Email update | Email saved, verification notice shown |
+| Avatar upload | Image uploaded, success alert |
+| Crop dialog | Cropper shown, apply saves |
+| Invalid email | Format error shown |
+| Taken email | Duplicate error shown |
+| Nav update | Navigation reflects new name |
diff --git a/skills/cs-pricing-strategy/SKILL.md b/skills/cs-pricing-strategy/SKILL.md
new file mode 100644
index 00000000..21d644bb
--- /dev/null
+++ b/skills/cs-pricing-strategy/SKILL.md
@@ -0,0 +1,323 @@
+---
+name: "pricing-strategy"
+description: "Design, optimize, and communicate SaaS pricing — tier structure, value metrics, pricing pages, and price increase strategy. Use when building a pricing model from scratch, redesigning existing pricing, planning a price increase, or improving a pricing page. Trigger keywords: pricing tiers, pricing page, price increase, packaging, value metric, per seat pricing, usage-based pricing, freemium, good-better-best, pricing strategy, monetization, pricing page conversion, Van Westendorp. NOT for broader product strategy — use product-strategist for that. NOT for customer success or renewals — use customer-success-manager for expansion revenue."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: marketing
+ updated: 2026-03-06
+---
+
+# Pricing Strategy
+
+You are an expert in SaaS pricing and monetization. Your goal is to design pricing that captures the value you deliver, converts at a healthy rate, and scales with your customers.
+
+Pricing is not math — it's positioning. The right price isn't the one that covers costs + margin. It's the one that sits between what your next-best alternative costs and what your customers believe they get in return. Most SaaS products are underpriced. This skill is about fixing that, clearly and defensibly.
+
+## Before Starting
+
+**Check for context first:**
+If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing.
+
+Gather this context:
+
+### 1. Current State
+- Do you have pricing today? If so: what plans, what price points, what's the billing model?
+- What's your conversion rate from trial/free to paid? (If known)
+- What's your average revenue per customer?
+- What's your monthly churn rate?
+
+### 2. Business Context
+- Product type: B2B or B2C? Self-serve or sales-assisted?
+- Customer segments: who are your best customers vs. casual users?
+- Competitors: who do customers compare you to, and what do those cost?
+- Cost structure: what does serving one customer cost you per month?
+
+### 3. Goals
+- Are you designing, optimizing, or planning a price increase?
+- Any constraints? (e.g., grandfathered customers, contractual limits, channel partner margins)
+
+## How This Skill Works
+
+### Mode 1: Design Pricing From Scratch
+Starting without a pricing model, or rebuilding entirely. We'll work through value metric selection, tier structure, price point research, and pricing page design.
+
+### Mode 2: Optimize Existing Pricing
+Pricing exists but conversion is low, expansion is flat, or customers feel mispriced. We'll audit what's there, benchmark, and identify specific improvements.
+
+### Mode 3: Plan a Price Increase
+Prices need to go up — because of inflation, value improvements, or market repositioning. We'll design a strategy that increases revenue without burning customers.
+
+---
+
+## The Three Pricing Axes
+
+Every pricing decision lives across three axes. Get all three right.
+
+```
+ ┌─────────────────┐
+ │ PACKAGING │ What's in each tier?
+ │ (what you get) │
+ └────────┬────────┘
+ │
+ ┌────────┴────────┐
+ │ VALUE METRIC │ What do you charge for?
+ │ (how it scales) │
+ └────────┬────────┘
+ │
+ ┌────────┴────────┐
+ │ PRICE POINT │ How much?
+ │ (the number) │
+ └─────────────────┘
+```
+
+Most teams skip straight to price point. That's backwards. Lock in the metric first, then packaging, then test the number.
+
+---
+
+## Value Metric Selection
+
+Your value metric determines how pricing scales with customer value. Choose wrong and you either leave money on the table or create friction that kills growth.
+
+### Common Value Metrics for SaaS
+
+| Metric | Best For | Example |
+|--------|---------|---------|
+| **Per seat / user** | Collaboration tools, CRMs | Salesforce, Notion, Linear |
+| **Per usage** | API tools, infrastructure, AI | Stripe, Twilio, OpenAI |
+| **Per feature** | Platform plays, add-ons | Intercom, HubSpot |
+| **Flat fee** | Unlimited-feel, SMB tools | Basecamp, Calendly Basic |
+| **Per outcome** | High-value, measurable ROI | Commission-based tools |
+| **Hybrid** | Mix of above | Most mature SaaS |
+
+### How to Choose
+
+Answer these questions:
+
+1. **What makes a customer willing to pay more?** → That's your value metric
+2. **Does the metric scale with their success?** → If they grow, you grow
+3. **Is it easy to understand?** → Complexity kills conversion
+4. **Is it hard to game?** → Customers shouldn't be able to work around it
+
+**Red flags:**
+- "Per seat" in a tool where one power user does all the work → seats don't scale with value
+- "Flat fee" when some customers derive 10x the value of others → you're subsidizing heavy users
+- "Per API call" when call count varies wildly week to week → unpredictable bills = churn
+
+---
+
+## Good-Better-Best Tier Structure
+
+Three tiers is the standard. Not because of tradition — because it anchors perception.
+
+### Tier Design Principles
+
+**Entry tier (Good):**
+- Captures the segment that will churn if priced higher
+- Limited — either by features, usage, or support
+- NOT free. Free is a separate strategy (freemium), not a tier.
+- Should cover your costs at minimum
+
+**Middle tier (Better) — your default:**
+- This is where you push most customers
+- Price: 2-3x the entry tier
+- Features: everything a growing company needs
+- Call it out visually as recommended
+
+**Top tier (Best):**
+- For high-value customers with enterprise needs
+- May be "Contact us" or custom pricing
+- Unlocks: SSO, audit logs, SLA, dedicated support, custom contracts
+- If you have enterprise deals >$1k MRR, this tier exists to capture them
+
+### What Goes in Each Tier
+
+| Feature Category | Entry | Better | Best |
+|----------------|-------|--------|------|
+| Core product | ✅ (limited) | ✅ (full) | ✅ (full) |
+| Usage limits | Low | Medium | High / unlimited |
+| Users/seats | 1-3 | 5-unlimited | Unlimited |
+| Integrations | Basic | Full | Full + custom |
+| Reporting | Basic | Advanced | Custom |
+| Support | Email | Priority | Dedicated CSM |
+| Admin features | — | — | SSO, audit log, SCIM |
+| SLA | — | — | ✅ |
+
+See [references/pricing-models.md](references/pricing-models.md) for model deep dives and SaaS examples.
+
+---
+
+## Value-Based Pricing
+
+Price between the next-best alternative and your perceived value.
+
+```
+[Cost of doing nothing] ... [Next-best alternative] ... [YOUR PRICE] ... [Perceived value delivered]
+```
+
+**Step 1: Define the next-best alternative**
+- What would the customer do if your product didn't exist?
+- A competitor? A spreadsheet? Manual process? Hiring someone?
+- What does that cost them?
+
+**Step 2: Estimate value delivered**
+- Time saved × hourly rate of the person using it
+- Revenue generated or protected
+- Cost of error/risk avoided
+- Ask your best customers: "What would you lose if you stopped using us tomorrow?"
+
+**Step 3: Price in the middle**
+- A rough heuristic: price at 10-20% of documented value delivered
+- Don't price at 50% of value — customers feel they're overpaying
+- Don't price below the next-best alternative — signals you don't believe in your own product
+
+**Conversion rate as a signal:**
+- >40% trial-to-paid: likely underpriced — test a price increase
+- 15-30%: healthy for most SaaS
+- <10%: pricing may be high, or trial-to-paid funnel has friction
+
+---
+
+## Pricing Research Methods
+
+### Van Westendorp Price Sensitivity Meter
+
+Four questions, asked to current customers or target segment:
+
+1. At what price would this product be so cheap you'd question its quality?
+2. At what price would this product be a bargain — great deal?
+3. At what price would this product start to feel expensive — still acceptable?
+4. At what price would this product be too expensive to consider?
+
+**Interpret the results:** Plot the four curves. The intersection of "too cheap" and "too expensive" gives your acceptable price range. The intersection of "bargain" and "expensive" gives the optimal price point.
+
+**When to use:** B2B SaaS, n≥30 respondents, existing customers or qualified prospects.
+
+### MaxDiff Analysis
+
+Show respondents sets of features/prices and ask which they value most and least. Statistical analysis reveals relative value of each feature — informs packaging more than price point.
+
+**When to use:** When deciding which features to put in which tier.
+
+### Competitor Benchmarking
+
+| Step | What to Do |
+|------|-----------|
+| 1 | List direct competitors and alternatives customers consider |
+| 2 | Record their published pricing (plan names, prices, value metrics) |
+| 3 | Note what's included at each price point |
+| 4 | Identify where your product over- and under-delivers vs. each |
+| 5 | Price relative to positioning: premium = 20-40% above market, value = at or below |
+
+**Don't just copy competitor prices** — their pricing reflects their cost structure and positioning, not yours.
+
+---
+
+## Price Increase Strategies
+
+Raising prices is one of the highest-ROI moves available to SaaS companies. Most wait too long.
+
+### Strategy Selection
+
+| Strategy | Use When | Risk |
+|---------|---------|------|
+| **New customers only** | Significant pushback expected | Low — doesn't touch existing base |
+| **Grandfather + delayed** | Loyal customer base, contract risk | Medium — existing customers feel respected |
+| **Tied to value delivery** | Clear new features/improvement | Low — justifiable |
+| **Plan restructure** | Significant packaging change | Medium — complexity for customers |
+| **Uniform increase** | Confident in value, price is clearly below market | Medium-High |
+
+### Execution Checklist
+
+1. **Quantify the move:** Calculate new MRR at 100%, 80%, 70% retention of existing customers
+2. **Segment by risk:** Annual contracts, champions vs. detractors, usage-based at-risk accounts
+3. **Set the date:** 60-90 days notice for existing customers. 30 days minimum.
+4. **Communicate the reason:** New features, rising costs, investment in [X] — be specific
+5. **Offer a path:** Lock in current price for annual commitment, or give a 3-month window
+6. **Arm your CS team:** FAQ, talking points, approved offer authority
+7. **Monitor for 60 days:** Churn rate, downgrade rate, support ticket volume
+
+**Expected churn from a 20-30% price increase:** 5-15%. If your net revenue impact is positive, proceed.
+
+---
+
+## Pricing Page Design
+
+The pricing page converts intent to purchase. Design it with that job in mind.
+
+### Above the Fold
+
+Must have:
+- Plan names (simple: Starter / Pro / Enterprise, or named after customer segment)
+- Price with billing toggle (monthly/annual — annual should show savings)
+- 3-5 bullet differentiators per plan
+- CTA button per plan
+- "Most popular" badge on recommended tier
+
+### Below the Fold
+
+- **Full feature comparison table** — comprehensive, scannable, uses ✅ and ❌ not walls of text
+- **FAQ section** — address the 5 objections that stop people from buying:
+ - "Can I cancel anytime?"
+ - "What happens when I hit limits?"
+ - "Do you offer refunds?"
+ - "Is my data secure?"
+ - "What if I need to upgrade/downgrade?"
+- **Social proof** — logos, quotes, or case studies relevant to each tier
+- **Security badges** if B2B enterprise (SOC2, ISO 27001, GDPR)
+
+### Annual vs. Monthly Toggle
+
+- Show annual pricing by default (or highlight it) — it improves LTV
+- Show savings explicitly: "Save 20%" or "2 months free"
+- Don't hide the monthly price — hiding it builds distrust
+
+See [references/pricing-page-playbook.md](references/pricing-page-playbook.md) for design specs and copy templates.
+
+---
+
+## Proactive Triggers
+
+Surface these without being asked:
+
+- **Conversion rate >40% trial-to-paid** → Strong signal of underpricing. Flag: test 20-30% price increase.
+- **All customers on the middle tier** → No upsell path. Flag: enterprise tier needed or feature lock-in missing.
+- **Customer asked for features that aren't in their tier** → Expansion revenue being left on the table. Flag: feature gatekeeping review.
+- **Churn rate >5% monthly** → Before raising prices, fix churn. Price increases accelerate churners.
+- **Price hasn't changed in 2+ years** → Inflation alone justifies 10-15% increase. Flag for strategic review.
+- **Only one pricing option** → No anchoring, no upsell. Flag: add a third tier even if rarely purchased.
+
+---
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|--------------------|-----------|
+| "Design pricing" | Three-tier structure with value metric, feature grid, price points, and rationale |
+| "Audit my pricing" | Pricing scorecard (0-100), conversion rate benchmarks, gap analysis, quick wins |
+| "Plan a price increase" | Increase strategy selection, communication templates, risk model, 90-day rollout plan |
+| "Design a pricing page" | Above-fold layout spec, feature comparison table structure, CTA copy, FAQ copy |
+| "Research pricing" | Van Westendorp survey questions + MaxDiff framework for your specific product |
+| "Model pricing scenarios" | Run `scripts/pricing_modeler.py` with your inputs |
+
+---
+
+## Communication
+
+All output follows the structured communication standard:
+- **Bottom line first** — recommendation before justification
+- **What + Why + How** — every recommendation has all three
+- **Actions have owners and deadlines** — no vague "consider"
+- **Confidence tagging** — 🟢 verified benchmark / 🟡 estimated / 🔴 assumed
+
+---
+
+## Related Skills
+
+- **product-strategist**: Use for product roadmap and broader monetization strategy. NOT for pricing page or price increase execution.
+- **copywriting**: Use for pricing page copy polish. NOT for pricing structure or tier design.
+- **churn-prevention**: Use when churn is the underlying issue — fix retention before raising prices.
+- **ab-test-setup**: Use to A/B test price points or pricing page layouts after initial design.
+- **customer-success-manager**: Use for expansion revenue through upselling. NOT for pricing design or packaging.
+- **competitor-alternatives**: Use for competitive comparison pages that complement pricing pages.
diff --git a/skills/cs-pricing-strategy/_meta.json b/skills/cs-pricing-strategy/_meta.json
new file mode 100644
index 00000000..8b96b5a6
--- /dev/null
+++ b/skills/cs-pricing-strategy/_meta.json
@@ -0,0 +1,17 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "cs-pricing-strategy",
+ "displayName": "pricing-strategy",
+ "latest": {
+ "version": "1.0.0",
+ "publishedAt": 1773244219303,
+ "commit": "https://github.com/openclaw/skills/commit/1290e843950bc94914c28a275d39bc02c226d18b"
+ },
+ "history": [
+ {
+ "version": "2.1.2",
+ "publishedAt": 1773166589272,
+ "commit": "https://github.com/openclaw/skills/commit/4a2c964f7d6271c04b1f419aa462520f6a452c17"
+ }
+ ]
+}
diff --git a/skills/cs-pricing-strategy/references/pricing-models.md b/skills/cs-pricing-strategy/references/pricing-models.md
new file mode 100644
index 00000000..00fdc56a
--- /dev/null
+++ b/skills/cs-pricing-strategy/references/pricing-models.md
@@ -0,0 +1,194 @@
+# Pricing Models — Deep Dive
+
+Comprehensive reference for SaaS pricing models with real-world examples and when to use each.
+
+---
+
+## Model 1: Per-Seat / Per-User
+
+**How it works:** Price is multiplied by the number of users who access the product.
+
+**Best for:**
+- Collaboration tools where more users = more value
+- CRMs where every sales rep needs access
+- Tools where the organization is the buyer and seats map to headcount
+
+**Examples:** Salesforce ($25-300/seat/mo), Linear ($8/seat/mo), Figma ($12/seat/mo), Notion ($8/seat/mo)
+
+**Expansion mechanics:** Automatic as companies hire. No upsell conversation needed — new hire gets a seat, revenue grows.
+
+**Failure modes:**
+- Single-power-user tools (one person does all the work, team just views results) → seat pricing punishes the customer for your product's design
+- Tools used by contractors or external stakeholders → billing becomes a negotiation
+- Products where sharing credentials is easy and enforcement is hard
+
+**Seat pricing variants:**
+
+| Variant | Description | Example |
+|---------|-------------|---------|
+| Named seat | Specific user assigned to each license | Salesforce |
+| Concurrent seat | N users can be logged in simultaneously | Legacy enterprise software |
+| Creator/viewer split | Creators pay, viewers free or low-cost | Figma, Miro |
+| Minimum seat count | Plan requires minimum X seats | Most enterprise deals |
+
+**Tip:** Creator/viewer pricing is powerful for B2B tools where one team creates and dozens consume. It drives virality (free viewers) while capturing revenue from actual users.
+
+---
+
+## Model 2: Usage-Based (Consumption)
+
+**How it works:** Customer pays for what they use — API calls, storage, compute, messages sent, emails delivered.
+
+**Best for:**
+- Infrastructure and developer tools
+- AI/ML tools where compute cost scales with usage
+- Communication platforms (email, SMS, video)
+- Products where usage is highly variable across customers
+
+**Examples:** Stripe (2.9% + $0.30/transaction), Twilio ($0.0075/SMS), AWS (varies), OpenAI ($0.002-0.06/1K tokens)
+
+**Expansion mechanics:** Natural — as customer grows, their usage grows, revenue grows without any action. Best CAC:LTV dynamics in SaaS.
+
+**Failure modes:**
+- Unpredictable bills → customers cap usage to avoid overages → you've engineered your own ceiling
+- High churn during market downturns → when usage drops, revenue drops
+- Hard to forecast for both you and the customer
+
+**Usage pricing variants:**
+
+| Variant | Description | Example |
+|---------|-------------|---------|
+| Pure consumption | Pay only for what you use | AWS Lambda |
+| Prepaid credits | Buy credits, consume at your pace | OpenAI, Resend |
+| Committed use + overage | Flat fee with usage ceiling, then per-unit | Stripe, Twilio volume |
+| Tiered usage | Lower per-unit price at higher volumes | Mailchimp email tiers |
+
+**Hybrid approach:** Most mature usage-based companies add a platform fee (small flat monthly charge) to ensure revenue floor and reduce churn from low-usage months.
+
+---
+
+## Model 3: Feature-Based (Tiered Flat Fee)
+
+**How it works:** Different bundles of features at different flat price points. The Good-Better-Best model.
+
+**Best for:**
+- Products with clear feature differentiation between customer segments
+- Markets where predictable spend matters (CFOs love this)
+- SMB-to-enterprise products where enterprise features are genuinely different
+
+**Examples:** HubSpot (Starter/Professional/Enterprise), Intercom (Starter/Pro/Premium), most SaaS
+
+**Expansion mechanics:** Requires upsell motion — customer has to outgrow a tier and move up. Less automatic than usage-based but more predictable.
+
+**Failure modes:**
+- Feature tiers that don't match actual customer needs → customers cluster in one tier, none move
+- Enterprise features that aren't compelling enough to justify the jump → stuck mid-market
+- Too many tiers → analysis paralysis
+
+---
+
+## Model 4: Flat Fee
+
+**How it works:** One price, everything included, unlimited use.
+
+**Best for:**
+- Small tools with predictable cost structure
+- Markets where simplicity is the differentiator
+- Products where usage genuinely doesn't vary much
+
+**Examples:** Basecamp ($99/mo flat), Transistor.fm (by podcast, not listeners), Calendly Basic
+
+**Expansion mechanics:** None. You need a premium tier or add-ons, or you're relying purely on new customer acquisition.
+
+**Failure modes:**
+- Heavy users subsidized by light users → heavy users stay forever, light users churn → adverse selection
+- No path to grow revenue with existing customers → stuck unless you add tiers or raise prices
+
+**When flat fee works:** When your cost to serve is genuinely flat, or when market positioning around simplicity is worth more than the revenue you'd capture with usage-based pricing.
+
+---
+
+## Model 5: Freemium
+
+**Note:** Freemium is an acquisition strategy, not a pricing model. It's compatible with any of the above.
+
+**How it works:** Free tier with limited functionality, paid tiers above.
+
+**Best for:**
+- Developer tools (PLG)
+- Collaboration tools that spread virally
+- Products where network effects increase value with more users
+
+**Examples:** Slack, Notion, Figma, GitHub, Airtable
+
+**The freemium math:**
+- Free users cost money to serve
+- You need paid conversion rate high enough to cover free users
+- Rule of thumb: 2-5% free-to-paid conversion is viable at scale, 1-2% usually isn't
+
+**Free vs. trial vs. freemium:**
+
+| Model | Description | Best For |
+|-------|-------------|---------|
+| Free forever tier | Permanently limited free plan | PLG, viral loops |
+| Time-limited trial | Full access for 14-30 days | Sales-assisted, complex products |
+| Usage-limited trial | Full access until limit hit | Developer tools, AI |
+| Freemium | Permanently limited, upsell to paid | Bottoms-up enterprise |
+
+---
+
+## Model 6: Hybrid Pricing
+
+Most mature SaaS companies end up with hybrid pricing. Common combinations:
+
+| Combination | Example |
+|------------|---------|
+| Platform fee + per seat | Base access + user licenses |
+| Platform fee + usage | Monthly minimum + overage |
+| Feature tiers + usage | Plan determines included usage, overage above |
+| Per seat + usage | Seat license + volume pricing for heavy users |
+
+**When to go hybrid:**
+- You have both fixed infrastructure costs and variable serving costs
+- You want revenue floors (platform fee) + upside (usage)
+- Different customer segments have very different value profiles
+
+---
+
+## Pricing Model Selection Framework
+
+Answer these questions to identify the right model:
+
+**1. Does value scale with users?**
+- Yes, linearly → per-seat
+- Yes, but not linearly → creator/viewer or per-seat with role tiers
+
+**2. Does value scale with usage?**
+- Yes, measurably → usage-based
+- Yes, but usage is hard to measure → feature tiers with usage caps
+
+**3. Is your customer a small business wanting simplicity?**
+- Yes → flat fee or simple 2-3 tier feature pricing
+- No → skip flat fee, go feature or usage-based
+
+**4. Do you have enterprise customers with governance/compliance needs?**
+- Yes → enterprise tier required (even if "Contact us")
+- No → three tiers max
+
+**5. Is this a developer/technical product?**
+- Yes → usage-based or consumption with free tier is the market norm
+- No → feature tiers with flat fee is more accessible
+
+---
+
+## Pricing Model Benchmarks
+
+| Metric | Early Stage | Growth | Scale |
+|--------|------------|--------|-------|
+| **Trial-to-paid rate** | 15-25% | 20-35% | 25-40% |
+| **Annual vs monthly mix** | 30-50% annual | 40-60% annual | 50-70% annual |
+| **Expansion revenue** | 0-10% of MRR | 10-20% | 20-40% |
+| **Price increase frequency** | Ad hoc | Annually | Annually |
+| **Churn rate (monthly)** | 2-8% | 1-4% | 0.5-2% |
+
+**The LTV:CAC rule:** LTV should be ≥3x CAC. If it's below 3x, pricing or retention (or both) needs fixing.
diff --git a/skills/cs-pricing-strategy/references/pricing-page-playbook.md b/skills/cs-pricing-strategy/references/pricing-page-playbook.md
new file mode 100644
index 00000000..ee6d99ce
--- /dev/null
+++ b/skills/cs-pricing-strategy/references/pricing-page-playbook.md
@@ -0,0 +1,221 @@
+# Pricing Page Playbook
+
+Design specs, copy frameworks, and conversion tactics for SaaS pricing pages.
+
+---
+
+## What a Pricing Page Actually Has to Do
+
+One job: get the right customer to click the right plan's CTA. Everything on the page should serve that job or get removed.
+
+The visitor landing on your pricing page has already decided they're interested. They're now asking:
+1. "Which plan is for me?"
+2. "Is it worth the price?"
+3. "What's the catch?"
+
+Your page answers those three questions, in that order.
+
+---
+
+## Page Structure (Scroll Order)
+
+### Above the Fold
+
+**Billing toggle (monthly/annual)**
+- Default to annual if annual is your preference (most conversions happen here)
+- Show savings clearly: "Save 20%" badge, not just the math
+- Position toggle at the top, before plan cards
+
+**Plan cards (3-column)**
+```
+┌─────────────┬─────────────┬─────────────┐
+│ Starter │ Pro │ Enterprise │
+│ │ ★ Popular │ │
+│ $29/mo │ $99/mo │ Custom │
+│ │ │ │
+│ For small │ For growing │ For teams │
+│ teams │ teams │ needing │
+│ │ │ control │
+│ • Feature │ • Feature │ • Feature │
+│ • Feature │ • Feature │ • Feature │
+│ • Feature │ • Feature │ • Feature │
+│ │ │ │
+│ [Start free]│[Start free] │[Contact us] │
+└─────────────┴─────────────┴─────────────┘
+```
+
+**Each plan card must include:**
+- Plan name (customer-segment-oriented, not just "Basic/Pro")
+- Price (with billing period and per-seat notation if applicable)
+- 1-line positioning sentence ("For growing teams who need X")
+- 4-6 bullet differentiators (what they get at this tier)
+- CTA button (clear, action-oriented — not just "Sign Up")
+- "Most popular" / "Recommended" badge on middle tier
+
+### Below the Fold
+
+**Full Feature Comparison Table**
+- Exhaustive list of all features
+- Group by category: Core, Collaboration, Analytics, Admin, Support
+- Use ✅ / ❌ or checkmarks/dashes — no conditional language
+- Sticky header so plan names stay visible while scrolling
+- Make this scannable, not a wall of text
+
+**Social Proof Section**
+- 3 customer quotes relevant to each tier if possible
+- Company logos of recognizable customers
+- Stats if they're real: "Trusted by 10,000+ teams"
+
+**FAQ Section (5-7 questions)**
+
+Non-negotiable FAQs:
+1. "Can I cancel anytime?" → Yes. Cancel from settings. No calls required.
+2. "What happens at the end of my trial?" → We'll ask if you want to continue.
+3. "Can I switch plans?" → Yes, upgrade or downgrade anytime. Prorated billing.
+4. "What payment methods do you accept?" → Credit card, invoice for annual enterprise.
+5. "Is my data secure?" → SOC 2 Type II / ISO 27001 / brief security statement.
+6. "What if I need more than the top plan offers?" → Talk to us: [link to enterprise form].
+
+**Enterprise Call-to-Action**
+- Separate row or section below cards
+- "Need custom pricing or a demo?" → [Talk to Sales] button
+- Who it's for: teams over X seats, specific compliance needs, custom contracts
+
+---
+
+## Copy Frameworks
+
+### Plan Names
+
+Avoid generic names if possible. Named plans anchor to identity, not just price.
+
+| Generic | Better | Why |
+|---------|--------|-----|
+| Free / Basic / Pro | Solo / Studio / Agency | Maps to customer segment |
+| Starter / Growth / Enterprise | Developer / Team / Business | Maps to use case |
+| Individual / Team / Organization | Creator / Collaborator / Company | Maps to role |
+
+If your categories are genuinely vague, stick with simple names. Don't force creative names that confuse.
+
+### CTA Copy
+
+Match the CTA to the ask:
+
+| Context | CTA |
+|---------|-----|
+| Has a free trial | "Start free trial" |
+| Freemium | "Get started free" |
+| No trial, direct purchase | "Get [Plan Name]" |
+| Enterprise / contact sales | "Talk to us" or "Get a demo" |
+| Annual commitment, high price | "Schedule a call" |
+
+Avoid:
+- "Sign Up" — generic, no value
+- "Subscribe" — sounds like a newsletter
+- "Buy Now" — transactional, not benefit-oriented
+- "Learn More" — on a pricing page, this is a dead end
+
+### Pricing Display
+
+| Scenario | How to Show It |
+|----------|---------------|
+| Monthly pricing | "$99/month" |
+| Annual pricing, billed monthly | "$83/month, billed annually" |
+| Annual pricing, billed upfront | "$996/year" with "/mo equivalent" note |
+| Per-seat | "$15/user/month" |
+| Usage-based | "From $0.002 per call" |
+| Enterprise | "Custom" or "Starting at $X" |
+
+Always show annual savings as a percentage OR dollar amount (whichever is larger visually).
+
+---
+
+## Conversion Tactics
+
+### Anchoring
+
+**Price anchoring:** The first number shown sets the reference frame. If you show a $500/month plan first, $99 feels cheap.
+
+If you want to push the middle tier:
+- Show plans left-to-right: Premium → Pro (recommended) → Starter
+- OR highlight the middle tier with visual treatment (larger card, border, color)
+- The eye goes to the visually differentiated option
+
+### The "Recommended" Badge
+
+Don't just label the middle tier. Make it visually obvious:
+- Darker background or brand color
+- Slightly taller card
+- "Most Popular" or "Recommended for Most Teams" label
+- First CTA in the tab order
+
+### Annual Toggle Default
+
+Research consistently shows defaulting to annual pricing increases annual plan take rate. Show the toggle, but default to annual.
+
+If you want more monthly customers (for cash flow testing, or lower commitment products), default to monthly.
+
+### Pricing Page SEO Consideration
+
+Pricing pages often rank for "[Company] pricing" queries. This matters because:
+- Competitors may be running ads on your brand pricing keywords
+- The page needs to load fast and be well-structured
+- Include your pricing in structured data (JSON-LD Schema: PriceSpecification)
+
+---
+
+## Pricing Page Audit Checklist
+
+Score each item 0-2 (0 = missing, 1 = exists but weak, 2 = done well):
+
+**Above the Fold**
+- [ ] Billing toggle visible
+- [ ] Annual savings shown clearly
+- [ ] Three plan cards with clear differentiation
+- [ ] "Most popular" / recommended tier highlighted
+- [ ] CTA per plan
+
+**Content**
+- [ ] Full feature comparison table
+- [ ] FAQ section (5+ questions)
+- [ ] Social proof / logos
+- [ ] Enterprise CTA
+
+**Copy**
+- [ ] Plan names are meaningful (not just Basic/Pro)
+- [ ] Price is unambiguous (per user? per month? billed how?)
+- [ ] CTAs are action-oriented
+- [ ] Positioning line per plan
+
+**Trust**
+- [ ] Security badges (if B2B)
+- [ ] Money-back guarantee or cancellation policy visible
+- [ ] "Cancel anytime" stated explicitly
+
+**Score interpretation:**
+- 22-24: Strong page. Test specific elements.
+- 16-21: Good foundation. Fix weak sections.
+- <16: Material gaps. Rebuild using this playbook.
+
+---
+
+## Pricing Page A/B Test Ideas
+
+**High impact, easier to test:**
+1. Default billing toggle (annual vs. monthly)
+2. "Most popular" badge placement
+3. CTA copy (Start free trial vs. Get Pro)
+4. Price display ($/mo vs. $/year)
+
+**Medium impact, more setup:**
+5. Plan name messaging (segment-based vs. feature-based)
+6. Number of features shown in above-fold cards (3 vs. 6)
+7. Social proof placement (above vs. below fold)
+8. FAQ accordion vs. expanded
+
+**High impact, harder to execute:**
+9. Actual price points (statistical significance takes longer)
+10. Three tiers vs. two tiers
+11. Adding vs. removing free tier
+
+**Minimum traffic for pricing tests:** 500+ visitors per variant per week. Below that, results won't be statistically meaningful.
diff --git a/skills/cs-pricing-strategy/scripts/pricing_modeler.py b/skills/cs-pricing-strategy/scripts/pricing_modeler.py
new file mode 100644
index 00000000..ece1342f
--- /dev/null
+++ b/skills/cs-pricing-strategy/scripts/pricing_modeler.py
@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""Pricing modeler — projects revenue at different price points and recommends tier structure."""
+
+import json
+import sys
+import math
+
+SAMPLE_INPUT = {
+ "current_mrr": 45000,
+ "current_customers": 300,
+ "monthly_new_customers": 25,
+ "monthly_churn_rate_pct": 3.5,
+ "trial_to_paid_rate_pct": 18,
+ "current_plans": [
+ {"name": "Starter", "price": 29, "customer_count": 180},
+ {"name": "Pro", "price": 79, "customer_count": 100},
+ {"name": "Enterprise", "price": 199, "customer_count": 20}
+ ],
+ "competitor_prices": [49, 89, 249],
+ "cogs_per_customer_monthly": 8,
+ "target_gross_margin_pct": 75
+}
+
+
+def calculate_arpu(plans):
+ total_rev = sum(p["price"] * p["customer_count"] for p in plans)
+ total_cust = sum(p["customer_count"] for p in plans)
+ return total_rev / total_cust if total_cust > 0 else 0
+
+
+def project_revenue_at_price(base_customers, base_arpu, new_arpu,
+ new_customers_monthly, churn_rate, months=12):
+ """Project MRR over N months at a new ARPU, assuming some churn from price change."""
+ price_increase_pct = (new_arpu - base_arpu) / base_arpu if base_arpu > 0 else 0
+
+ # Estimate churn uplift from price increase
+ # Empirical: each 10% price increase causes ~2-4% additional one-time churn
+ if price_increase_pct > 0:
+ price_churn_hit = price_increase_pct * 0.25 # 25% of increase leaks as churn
+ else:
+ price_churn_hit = 0
+
+ monthly_churn = churn_rate / 100
+
+ mrr_series = []
+ customers = base_customers * (1 - price_churn_hit) # initial price churn hit
+ mrr = customers * new_arpu
+
+ for month in range(1, months + 1):
+ mrr_series.append(round(mrr, 0))
+ customers = customers * (1 - monthly_churn) + new_customers_monthly
+ mrr = customers * new_arpu
+
+ return {
+ "month_1_mrr": mrr_series[0],
+ "month_6_mrr": mrr_series[5],
+ "month_12_mrr": mrr_series[11],
+ "total_12mo_revenue": sum(mrr_series),
+ "customers_after_price_churn": round(base_customers * (1 - price_churn_hit), 0)
+ }
+
+
+def recommend_tier_structure(plans, competitor_prices, cogs, target_margin_pct):
+ """Recommend Good-Better-Best tier structure based on current state and competitors."""
+ current_arpu = calculate_arpu(plans)
+ comp_avg = sum(competitor_prices) / len(competitor_prices) if competitor_prices else current_arpu
+ comp_min = min(competitor_prices) if competitor_prices else current_arpu * 0.7
+ comp_max = max(competitor_prices) if competitor_prices else current_arpu * 1.5
+
+ # Minimum price based on cost structure
+ min_viable_price = cogs / (1 - target_margin_pct / 100)
+
+ # Recommended tier anchors
+ entry_price = max(min_viable_price, comp_min * 0.9)
+ mid_price = entry_price * 2.5
+ premium_price = mid_price * 2.5
+
+ # Round to psychologically clean prices
+ def clean_price(p):
+ if p < 30:
+ return round(p / 5) * 5 - 1 # e.g., 19, 29
+ elif p < 100:
+ return round(p / 10) * 10 - 1 # e.g., 49, 79, 99
+ elif p < 500:
+ return round(p / 25) * 25 - 1 # e.g., 149, 199, 299
+ else:
+ return round(p / 100) * 100 - 1 # e.g., 499, 999
+
+ return {
+ "entry": {
+ "name": "Starter",
+ "recommended_price": clean_price(entry_price),
+ "positioning": "For individuals and small teams getting started"
+ },
+ "mid": {
+ "name": "Professional",
+ "recommended_price": clean_price(mid_price),
+ "positioning": "For growing teams that need the full feature set — recommended for most"
+ },
+ "premium": {
+ "name": "Enterprise",
+ "recommended_price": clean_price(premium_price),
+ "positioning": "For larger organizations needing security, compliance, and dedicated support"
+ },
+ "rationale": {
+ "current_arpu": round(current_arpu, 2),
+ "competitor_range": f"${comp_min}-${comp_max}",
+ "min_viable_price": round(min_viable_price, 2),
+ "pricing_vs_market": "at-market" if abs(current_arpu - comp_avg) / comp_avg < 0.15 else
+ "below-market" if current_arpu < comp_avg else "above-market"
+ }
+ }
+
+
+def elasticity_estimate(trial_to_paid_pct, current_arpu):
+ """Rough price elasticity signal based on conversion rate."""
+ if trial_to_paid_pct > 40:
+ signal = "strong-underpricing"
+ note = "Conversion >40% — strong signal of underpricing. Test 20-30% increase."
+ headroom = 0.30
+ elif trial_to_paid_pct > 25:
+ signal = "possible-underpricing"
+ note = "Conversion 25-40% — healthy, but may have room for modest price increase."
+ headroom = 0.15
+ elif trial_to_paid_pct > 15:
+ signal = "market-priced"
+ note = "Conversion 15-25% — likely market-priced. Focus on tier structure and packaging."
+ headroom = 0.05
+ elif trial_to_paid_pct > 8:
+ signal = "possible-overpricing"
+ note = "Conversion 8-15% — possible price friction. Audit trial experience before reducing price."
+ headroom = -0.05
+ else:
+ signal = "high-friction"
+ note = "Conversion <8% — significant friction. May be pricing, trial experience, or ICP fit."
+ headroom = -0.15
+
+ return {
+ "signal": signal,
+ "note": note,
+ "estimated_price_headroom_pct": round(headroom * 100, 0),
+ "suggested_test_price": round(current_arpu * (1 + headroom), 2)
+ }
+
+
+def print_report(result, inputs):
+ cur = result["current_state"]
+ elast = result["elasticity"]
+ tiers = result["tier_recommendation"]
+ scenarios = result["price_scenarios"]
+
+ print("\n" + "="*65)
+ print(" PRICING MODELER")
+ print("="*65)
+
+ print(f"\n📊 CURRENT STATE")
+ print(f" MRR: ${cur['current_mrr']:,.0f}")
+ print(f" Customers: {cur['customers']}")
+ print(f" ARPU: ${cur['arpu']:.2f}/mo")
+ print(f" Trial-to-paid rate: {inputs['trial_to_paid_rate_pct']}%")
+ print(f" Monthly churn rate: {inputs['monthly_churn_rate_pct']}%")
+ print(f" Gross margin (est.): {cur['gross_margin_pct']:.1f}%")
+
+ print(f"\n💡 PRICE ELASTICITY SIGNAL")
+ print(f" Signal: {elast['signal'].replace('-', ' ').upper()}")
+ print(f" Note: {elast['note']}")
+ print(f" Headroom: {'+' if elast['estimated_price_headroom_pct'] >= 0 else ''}"
+ f"{elast['estimated_price_headroom_pct']:.0f}%")
+ print(f" Test at: ${elast['suggested_test_price']:.2f}/mo ARPU")
+
+ print(f"\n📐 RECOMMENDED TIER STRUCTURE")
+ tier_rat = tiers['rationale']
+ print(f" Market position: {tier_rat['pricing_vs_market'].replace('-', ' ').title()}")
+ print(f" Competitor range: {tier_rat['competitor_range']}")
+ print(f" Min viable price: ${tier_rat['min_viable_price']:.2f}/mo")
+ print(f"\n ┌─────────────────┬────────────┬────────────────────────────────────┐")
+ print(f" │ Tier │ Price │ Positioning │")
+ print(f" ├─────────────────┼────────────┼────────────────────────────────────┤")
+ for key in ["entry", "mid", "premium"]:
+ t = tiers[key]
+ name = t["name"].ljust(15)
+ price = f"${t['recommended_price']}/mo".ljust(10)
+ pos = t["positioning"][:34].ljust(34)
+ print(f" │ {name} │ {price} │ {pos} │")
+ print(f" └─────────────────┴────────────┴────────────────────────────────────┘")
+
+ print(f"\n📈 REVENUE SCENARIOS (12-month projection)")
+ print(f" {'Scenario':<25} {'Mo 1 MRR':>10} {'Mo 6 MRR':>10} {'Mo 12 MRR':>10} {'12mo Total':>12}")
+ print(f" {'-'*67}")
+ for s in scenarios:
+ print(f" {s['scenario']:<25} "
+ f"${s['month_1_mrr']:>9,.0f} "
+ f"${s['month_6_mrr']:>9,.0f} "
+ f"${s['month_12_mrr']:>9,.0f} "
+ f"${s['total_12mo_revenue']:>11,.0f}")
+
+ print(f"\n🎯 RECOMMENDATION")
+ best = max(scenarios, key=lambda s: s['total_12mo_revenue'])
+ current = next((s for s in scenarios if s['scenario'] == 'Current pricing'), scenarios[0])
+ uplift = best['total_12mo_revenue'] - current['total_12mo_revenue']
+ print(f" Best scenario: {best['scenario']}")
+ print(f" 12-month uplift: ${uplift:,.0f} vs. current")
+ print(f" Note: Projections assume trial volume and churn hold constant.")
+ print(f" Test price increases on new customers first.")
+
+ print("\n" + "="*65 + "\n")
+
+
+def main():
+ import argparse
+
+ parser = argparse.ArgumentParser(
+ description="Pricing modeler — projects revenue at different price points and recommends tier structure."
+ )
+ parser.add_argument(
+ "input_file", nargs="?", default=None,
+ help="JSON file with pricing data (default: run with sample data)"
+ )
+ parser.add_argument(
+ "--json", action="store_true",
+ help="Output results as JSON"
+ )
+ args = parser.parse_args()
+
+ if args.input_file:
+ with open(args.input_file) as f:
+ inputs = json.load(f)
+ else:
+ if not args.json:
+ print("No input file provided. Running with sample data...\n")
+ inputs = SAMPLE_INPUT
+
+ current_arpu = calculate_arpu(inputs["current_plans"])
+ total_customers = inputs["current_customers"]
+ cogs = inputs["cogs_per_customer_monthly"]
+ target_margin = inputs["target_gross_margin_pct"]
+
+ gross_margin = ((current_arpu - cogs) / current_arpu * 100) if current_arpu > 0 else 0
+
+ tier_rec = recommend_tier_structure(
+ inputs["current_plans"],
+ inputs.get("competitor_prices", []),
+ cogs,
+ target_margin
+ )
+
+ elast = elasticity_estimate(inputs["trial_to_paid_rate_pct"], current_arpu)
+
+ # Model multiple scenarios
+ churn = inputs["monthly_churn_rate_pct"]
+ new_mo = inputs["monthly_new_customers"]
+
+ scenarios = []
+ for label, arpu in [
+ ("Current pricing", current_arpu),
+ ("5% price increase", current_arpu * 1.05),
+ ("15% price increase", current_arpu * 1.15),
+ ("25% price increase", current_arpu * 1.25),
+ ("Recommended tiers", tier_rec["mid"]["recommended_price"])
+ ]:
+ proj = project_revenue_at_price(total_customers, current_arpu, arpu, new_mo, churn)
+ scenarios.append({"scenario": label, "arpu": round(arpu, 2), **proj})
+
+ result = {
+ "current_state": {
+ "current_mrr": inputs["current_mrr"],
+ "customers": total_customers,
+ "arpu": round(current_arpu, 2),
+ "gross_margin_pct": round(gross_margin, 1)
+ },
+ "elasticity": elast,
+ "tier_recommendation": tier_rec,
+ "price_scenarios": scenarios
+ }
+
+ print_report(result, inputs)
+
+ if args.json:
+ print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/cs-pw/SKILL.md b/skills/cs-pw/SKILL.md
new file mode 100644
index 00000000..7b771107
--- /dev/null
+++ b/skills/cs-pw/SKILL.md
@@ -0,0 +1,124 @@
+---
+name: "playwright-pro"
+description: "Production-grade Playwright testing toolkit. Use when the user mentions Playwright tests, end-to-end testing, browser automation, fixing flaky tests, test migration, CI/CD testing, or test suites. Generate tests, fix flaky failures, migrate from Cypress/Selenium, sync with TestRail, run on BrowserStack. 55 templates, 3 agents, smart reporting."
+---
+
+# Playwright Pro
+
+Production-grade Playwright testing toolkit for AI coding agents.
+
+## Available Commands
+
+When installed as a Claude Code plugin, these are available as `/pw:` commands:
+
+| Command | What it does |
+|---|---|
+| `/pw:init` | Set up Playwright — detects framework, generates config, CI, first test |
+| `/pw:generate ` | Generate tests from user story, URL, or component |
+| `/pw:review` | Review tests for anti-patterns and coverage gaps |
+| `/pw:fix ` | Diagnose and fix failing or flaky tests |
+| `/pw:migrate` | Migrate from Cypress or Selenium to Playwright |
+| `/pw:coverage` | Analyze what's tested vs. what's missing |
+| `/pw:testrail` | Sync with TestRail — read cases, push results |
+| `/pw:browserstack` | Run on BrowserStack, pull cross-browser reports |
+| `/pw:report` | Generate test report in your preferred format |
+
+## Quick Start Workflow
+
+The recommended sequence for most projects:
+
+```
+1. /pw:init → scaffolds config, CI pipeline, and a first smoke test
+2. /pw:generate → generates tests from your spec or URL
+3. /pw:review → validates quality and flags anti-patterns ← always run after generate
+4. /pw:fix → diagnoses and repairs any failing/flaky tests ← run when CI turns red
+```
+
+**Validation checkpoints:**
+- After `/pw:generate` — always run `/pw:review` before committing; it catches locator anti-patterns and missing assertions automatically.
+- After `/pw:fix` — re-run the full suite locally (`npx playwright test`) to confirm the fix doesn't introduce regressions.
+- After `/pw:migrate` — run `/pw:coverage` to confirm parity with the old suite before decommissioning Cypress/Selenium tests.
+
+### Example: Generate → Review → Fix
+
+```bash
+# 1. Generate tests from a user story
+/pw:generate "As a user I can log in with email and password"
+
+# Generated: tests/auth/login.spec.ts
+# → Playwright Pro creates the file using the auth template.
+
+# 2. Review the generated tests
+/pw:review tests/auth/login.spec.ts
+
+# → Flags: one test used page.locator('input[type=password]') — suggests getByLabel('Password')
+# → Fix applied automatically.
+
+# 3. Run locally to confirm
+npx playwright test tests/auth/login.spec.ts --headed
+
+# 4. If a test is flaky in CI, diagnose it
+/pw:fix tests/auth/login.spec.ts
+# → Identifies missing web-first assertion; replaces waitForTimeout(2000) with expect(locator).toBeVisible()
+```
+
+## Golden Rules
+
+1. `getByRole()` over CSS/XPath — resilient to markup changes
+2. Never `page.waitForTimeout()` — use web-first assertions
+3. `expect(locator)` auto-retries; `expect(await locator.textContent())` does not
+4. Isolate every test — no shared state between tests
+5. `baseURL` in config — zero hardcoded URLs
+6. Retries: `2` in CI, `0` locally
+7. Traces: `'on-first-retry'` — rich debugging without slowdown
+8. Fixtures over globals — `test.extend()` for shared state
+9. One behavior per test — multiple related assertions are fine
+10. Mock external services only — never mock your own app
+
+## Locator Priority
+
+```
+1. getByRole() — buttons, links, headings, form elements
+2. getByLabel() — form fields with labels
+3. getByText() — non-interactive text
+4. getByPlaceholder() — inputs with placeholder
+5. getByTestId() — when no semantic option exists
+6. page.locator() — CSS/XPath as last resort
+```
+
+## What's Included
+
+- **9 skills** with detailed step-by-step instructions
+- **3 specialized agents**: test-architect, test-debugger, migration-planner
+- **55 test templates**: auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility
+- **2 MCP servers** (TypeScript): TestRail and BrowserStack integrations
+- **Smart hooks**: auto-validate test quality, auto-detect Playwright projects
+- **6 reference docs**: golden rules, locators, assertions, fixtures, pitfalls, flaky tests
+- **Migration guides**: Cypress and Selenium mapping tables
+
+## Integration Setup
+
+### TestRail (Optional)
+```bash
+export TESTRAIL_URL="https://your-instance.testrail.io"
+export TESTRAIL_USER="your@email.com"
+export TESTRAIL_API_KEY="your-api-key"
+```
+
+### BrowserStack (Optional)
+```bash
+export BROWSERSTACK_USERNAME="your-username"
+export BROWSERSTACK_ACCESS_KEY="your-access-key"
+```
+
+## Quick Reference
+
+See `reference/` directory for:
+- `golden-rules.md` — The 10 non-negotiable rules
+- `locators.md` — Complete locator priority with cheat sheet
+- `assertions.md` — Web-first assertions reference
+- `fixtures.md` — Custom fixtures and storageState patterns
+- `common-pitfalls.md` — Top 10 mistakes and fixes
+- `flaky-tests.md` — Diagnosis commands and quick fixes
+
+See `templates/README.md` for the full template index.
diff --git a/skills/cs-pw/_meta.json b/skills/cs-pw/_meta.json
new file mode 100644
index 00000000..d21234ca
--- /dev/null
+++ b/skills/cs-pw/_meta.json
@@ -0,0 +1,11 @@
+{
+ "owner": "alirezarezvani",
+ "slug": "cs-pw",
+ "displayName": "Tmp.SpQgKzelJa",
+ "latest": {
+ "version": "2.1.3",
+ "publishedAt": 1773166517207,
+ "commit": "https://github.com/openclaw/skills/commit/1e3db60509994c45795b1750b4e9819f44c07d6b"
+ },
+ "history": []
+}
diff --git a/skills/cs-schema-markup/SKILL.md b/skills/cs-schema-markup/SKILL.md
new file mode 100644
index 00000000..e3bc009f
--- /dev/null
+++ b/skills/cs-schema-markup/SKILL.md
@@ -0,0 +1,233 @@
+---
+name: "schema-markup"
+description: "When the user wants to implement, audit, or validate structured data (schema markup) on their website. Use when the user mentions 'structured data,' 'schema.org,' 'JSON-LD,' 'rich results,' 'rich snippets,' 'schema markup,' 'FAQ schema,' 'Product schema,' 'HowTo schema,' or 'structured data errors in Search Console.' Also use when someone asks why their content isn't showing rich results or wants to improve AI search visibility. NOT for general SEO audits (use seo-audit) or technical SEO crawl issues (use site-architecture)."
+license: MIT
+metadata:
+ version: 1.0.0
+ author: Alireza Rezvani
+ category: marketing
+ updated: 2026-03-06
+---
+
+# Schema Markup Implementation
+
+You are an expert in structured data and schema.org markup. Your goal is to help implement, audit, and validate JSON-LD schema that earns rich results in Google, improves click-through rates, and makes content legible to AI search systems.
+
+## Before Starting
+
+**Check for context first:**
+If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing.
+
+Gather this context:
+
+### 1. Current State
+- Do they have any existing schema markup? (Check source, GSC Coverage report, or run the validator script)
+- Any rich results currently showing in Google?
+- Any structured data errors in Search Console?
+
+### 2. Site Details
+- CMS platform (WordPress, Webflow, custom, etc.)
+- Page types that need markup (homepage, articles, products, FAQ, local business)
+- Can they edit `` tags, or do they need a plugin/GTM?
+
+### 3. Goals
+- Rich results target (FAQ dropdowns, star ratings, breadcrumbs, HowTo steps, etc.)
+- AI search visibility (getting cited in AI Overviews, Perplexity, etc.)
+- Fix existing errors vs implement net new
+
+---
+
+## How This Skill Works
+
+### Mode 1: Audit Existing Markup
+When they have a site and want to know what schema exists and what's broken.
+
+1. Run `scripts/schema_validator.py` on the page HTML (or paste URL for manual check)
+2. Review Google Search Console → Enhancements → check all schema error reports
+3. Cross-reference against `references/schema-types-guide.md` for required fields
+4. Deliver audit report: what's present, what's broken, what's missing, priority order
+
+### Mode 2: Implement New Schema
+When they need to add structured data to pages — from scratch or to a new page type.
+
+1. Identify the page type and the right schema types (see schema selection table below)
+2. Pull the JSON-LD pattern from `references/implementation-patterns.md`
+3. Populate with real page content
+4. Advise on placement (inline `
+
+```
+
+Multiple schema blocks per page are fine — use separate `
+
+
+```
+
+Or combine into a single `@graph` array:
+
+```html
+
+```
+
+Both approaches are valid. `@graph` is cleaner for sites with many schema types per page.
+
+---
+
+## WebSite (Homepage Only)
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "WebSite",
+ "url": "https://YOURDOMAIN.COM",
+ "name": "SITE_NAME",
+ "potentialAction": {
+ "@type": "SearchAction",
+ "target": {
+ "@type": "EntryPoint",
+ "urlTemplate": "https://YOURDOMAIN.COM/search?q={search_term_string}"
+ },
+ "query-input": "required name=search_term_string"
+ }
+}
+```
+
+**Note:** Only add this if you have a working internal search at the URL template path.
+
+---
+
+## Duration Format Reference (ISO 8601)
+
+| Duration | ISO 8601 |
+|----------|----------|
+| 30 minutes | `PT30M` |
+| 1 hour | `PT1H` |
+| 1 hour 30 minutes | `PT1H30M` |
+| 2 hours 15 minutes | `PT2H15M` |
+| 5 minutes 30 seconds | `PT5M30S` |
+| 12 minutes 30 seconds | `PT12M30S` |
+
+## Availability Values Reference
+
+Always use the full schema.org URL — not just the word.
+
+| Status | Value |
+|--------|-------|
+| In stock | `https://schema.org/InStock` |
+| Out of stock | `https://schema.org/OutOfStock` |
+| Pre-order | `https://schema.org/PreOrder` |
+| Back order | `https://schema.org/BackOrder` |
+| Limited availability | `https://schema.org/LimitedAvailability` |
+| Discontinued | `https://schema.org/Discontinued` |
diff --git a/skills/cs-schema-markup/references/schema-types-guide.md b/skills/cs-schema-markup/references/schema-types-guide.md
new file mode 100644
index 00000000..dfafb476
--- /dev/null
+++ b/skills/cs-schema-markup/references/schema-types-guide.md
@@ -0,0 +1,285 @@
+# Schema Types Guide
+
+A practitioner's reference for schema.org types — what they do, what fields matter, and what Google actually uses for rich results.
+
+---
+
+## How to Read This Guide
+
+Each type lists:
+- **Purpose** — what it tells search engines
+- **Rich result** — what you can earn in Google (if anything)
+- **Required fields** — missing these = no rich result
+- **Recommended fields** — fill these to maximize eligibility
+- **Gotchas** — the field mistakes that waste everyone's time
+
+---
+
+## Article
+
+**Purpose:** Marks editorial content — news, blog posts, opinion pieces.
+
+**Rich result:** Article rich result (expanded card in Google News, Discover, and some search results). Also influences AI Overview citation likelihood.
+
+**Required fields:**
+- `headline` — the article title (max 110 characters for display)
+- `image` — at least one image, minimum 1200px wide for rich results
+- `datePublished` — ISO 8601 format
+- `author` — Person or Organization type
+
+**Recommended fields:**
+- `dateModified` — keep current; freshness signal
+- `publisher` — Organization type with `logo`
+- `description` — 150-300 char summary
+- `url` — canonical URL of the article
+
+**Subtypes:** Use `NewsArticle` for news content, `BlogPosting` for blog posts. Both inherit from Article. Google treats them similarly.
+
+**Gotchas:**
+- `image` must be absolute URL. Relative URLs fail silently.
+- `headline` should match the visible `
` on the page. Google cross-validates.
+- Multiple `author` values are valid — use an array: `"author": [{"@type": "Person", "name": "..."}, ...]`
+
+---
+
+## HowTo
+
+**Purpose:** Step-by-step instructions for completing a task.
+
+**Rich result:** HowTo steps appear directly in Google search results as expandable steps (desktop and mobile).
+
+**Required fields:**
+- `name` — title of the how-to (e.g., "How to change a bike tire")
+- `step` — array of HowToStep objects, each with:
+ - `name` — step title
+ - `text` — step instructions
+
+**Recommended fields:**
+- `image` — overall how-to image
+- `totalTime` — ISO 8601 duration (e.g., `"PT30M"` = 30 minutes)
+- `tool` — list of tools needed (HowToTool type)
+- `supply` — list of materials (HowToSupply type)
+- `estimatedCost` — MonetaryAmount type
+
+**Gotchas:**
+- Steps must appear on the page in readable form — hidden steps fail Google's content matching.
+- HowToStep `image` is different from the main `image` — each step can have its own.
+- Don't use HowTo for recipe content — use Recipe type instead.
+
+---
+
+## FAQPage
+
+**Purpose:** A page containing a list of frequently asked questions and their answers.
+
+**Rich result:** FAQ accordion dropdowns directly in Google search results. High-value visibility — shows your Q&A without clicking.
+
+**Required fields:**
+- `mainEntity` — array of Question objects, each with:
+ - `name` — the question text
+ - `acceptedAnswer` — Answer type with `text` field containing the answer
+
+**Recommended fields:**
+- No additional fields required — this type is simple by design.
+
+**Gotchas:**
+- Both the question AND the answer must be visible on the page. Google explicitly checks.
+- Answers with HTML tags (links, bold) may or may not render — keep answers as clean text.
+- Google limits FAQ rich results to 3-5 Q&A pairs visible in search, even if you have more.
+- Don't use FAQPage for Q&A that requires a login to view — Google can't verify it.
+
+---
+
+## Product
+
+**Purpose:** Describes a product for sale, including pricing, availability, and reviews.
+
+**Rich result:** Product rich results with price, availability, rating stars. Eligible for Google Shopping surfaces.
+
+**Required fields (for rich results):**
+- `name` — product name
+- `offers` — Offer type with:
+ - `price` — numeric price (not formatted with currency symbol)
+ - `priceCurrency` — ISO 4217 currency code (e.g., `"USD"`, `"EUR"`)
+ - `availability` — schema.org availability URL (e.g., `"https://schema.org/InStock"`)
+
+**Recommended fields:**
+- `image` — product image(s), absolute URLs
+- `description` — product description
+- `sku` — stock-keeping unit
+- `brand` — Brand or Organization type
+- `aggregateRating` — AggregateRating type (required for star ratings)
+- `review` — individual Review objects
+
+**AggregateRating required fields:**
+- `ratingValue` — average rating
+- `reviewCount` — number of reviews (or `ratingCount`)
+- `bestRating` — maximum rating value (default: 5)
+
+**Gotchas:**
+- Price must be a number, not a string: `"price": 29.99` not `"price": "$29.99"`
+- `availability` must use the full schema.org URL, not just "InStock"
+- If you show ratings, you must have real reviews — fabricated ratings violate Google's policies
+- Price shown in schema must match the price visible on the page
+
+---
+
+## Organization
+
+**Purpose:** Identifies your company/organization as an entity to search engines and knowledge graphs.
+
+**Rich result:** Knowledge panel information, logo in search results, organization entity recognition.
+
+**Required fields:**
+- `name` — official organization name
+- `url` — organization website
+
+**Recommended fields:**
+- `logo` — ImageObject with absolute URL to logo
+- `sameAs` — array of URLs to your organization's profiles elsewhere (LinkedIn, Twitter/X, Facebook, Crunchbase, Wikidata, Wikipedia)
+- `contactPoint` — ContactPoint type with `telephone` and `contactType`
+- `address` — PostalAddress type
+- `foundingDate` — year or ISO date
+- `numberOfEmployees` — QuantitativeValue type
+- `description` — brief company description
+
+**Gotchas:**
+- `sameAs` is the most important field for entity establishment — the more authoritative sources you include, the stronger the entity signal.
+- Use `https://www.wikidata.org/wiki/Q[ID]` in `sameAs` if your company has a Wikidata entry.
+- Only one Organization schema per domain — put it on every page if you want, but keep it consistent.
+
+---
+
+## LocalBusiness
+
+**Purpose:** Extends Organization for businesses with a physical location. Used for local search results and map listings.
+
+**Rich result:** Local knowledge panel, map pin details, opening hours, star ratings in local results.
+
+**Required fields:**
+- `name` — business name
+- `address` — PostalAddress with `streetAddress`, `addressLocality`, `postalCode`, `addressCountry`
+
+**Recommended fields:**
+- `telephone` — with country code (e.g., `"+1-800-555-1234"`)
+- `openingHoursSpecification` — array by day with opens/closes times
+- `geo` — GeoCoordinates with `latitude` and `longitude`
+- `priceRange` — string like `"$$"` or `"€€"` or `"$10-$50"`
+- `image` — photos of the business
+- `url` — website URL
+- `aggregateRating` — if you have reviews
+
+**Subtypes:** Use the most specific subtype available. `Restaurant`, `MedicalClinic`, `LegalService`, `Hotel` all extend LocalBusiness and unlock additional rich result fields.
+
+**Gotchas:**
+- Address must exactly match what's in Google Business Profile for local SEO to connect.
+- Hours must use 24-hour format in `openingHoursSpecification`.
+- If closed on a day, omit that day rather than using `"00:00"`.
+
+---
+
+## BreadcrumbList
+
+**Purpose:** Represents the breadcrumb trail shown on a page — the hierarchy from homepage to current page.
+
+**Rich result:** Breadcrumb path shown in Google search results instead of the raw URL. Cleaner appearance, more clicks.
+
+**Required fields:**
+- `itemListElement` — array of ListItem objects, each with:
+ - `position` — integer starting at 1
+ - `name` — breadcrumb label
+ - `item` — absolute URL of that breadcrumb level
+
+**Recommended fields:**
+None required beyond the above.
+
+**Gotchas:**
+- Positions must be sequential integers starting at 1. Gaps or non-integers fail validation.
+- The last breadcrumb (current page) may omit `item` since it's the current URL — but including it is safer.
+- Breadcrumb schema must match the visible breadcrumbs on the page.
+- Use on every non-homepage if you have visible breadcrumbs.
+
+---
+
+## VideoObject
+
+**Purpose:** Describes an embedded or hosted video.
+
+**Rich result:** Video carousels, video badges on search results, timestamp markers that appear in results.
+
+**Required fields:**
+- `name` — video title
+- `description` — video description
+- `thumbnailUrl` — absolute URL to thumbnail image
+- `uploadDate` — ISO 8601 date
+
+**Recommended fields:**
+- `duration` — ISO 8601 duration (e.g., `"PT12M30S"` = 12 min 30 sec)
+- `contentUrl` — direct URL to the video file
+- `embedUrl` — URL of the embeddable player
+- `hasPart` — array of Clip objects with start/end times for key moments
+- `interactionStatistic` — view count (InteractionCounter type)
+
+**Key moments (Clip type for timestamp markers):**
+```json
+"hasPart": [
+ {
+ "@type": "Clip",
+ "name": "Introduction",
+ "startOffset": 0,
+ "endOffset": 60,
+ "url": "https://example.com/video#t=0"
+ }
+]
+```
+
+**Gotchas:**
+- `thumbnailUrl` must resolve to an actual image — Google checks it.
+- Without `contentUrl` or `embedUrl`, Google may not index the video.
+- Videos behind login/paywall are not eligible for video rich results.
+
+---
+
+## WebSite
+
+**Purpose:** Identifies your website and enables the sitelinks search box in Google results.
+
+**Rich result:** Sitelinks search box — a search field that appears under your domain in branded searches.
+
+**Required fields:**
+- `url` — homepage URL
+- `potentialAction` — SearchAction type for sitelinks search box:
+ ```json
+ "potentialAction": {
+ "@type": "SearchAction",
+ "target": {
+ "@type": "EntryPoint",
+ "urlTemplate": "https://example.com/search?q={search_term_string}"
+ },
+ "query-input": "required name=search_term_string"
+ }
+ ```
+
+**Gotchas:**
+- Only put WebSite schema on the homepage.
+- The `urlTemplate` must point to a working search endpoint.
+- Sitelinks search box only appears for branded queries — this won't help you rank for generic terms.
+
+---
+
+## Schema Eligibility Summary
+
+Quick-reference: what actually earns a rich result vs what's just entity data.
+
+| Schema Type | Rich Result Available | Rich Result Type |
+|-------------|----------------------|-----------------|
+| Article | ✅ | Top stories card, article rich result |
+| HowTo | ✅ | Step-by-step in SERP |
+| FAQPage | ✅ | Accordion Q&A in SERP |
+| Product + Offer | ✅ | Price/availability badge |
+| Product + AggregateRating | ✅ | Star ratings |
+| LocalBusiness | ✅ | Local knowledge panel |
+| BreadcrumbList | ✅ | Breadcrumb path in SERP |
+| VideoObject | ✅ | Video carousel, key moments |
+| Organization | ⚠️ | Knowledge panel (not guaranteed) |
+| WebSite | ⚠️ | Sitelinks search box (not guaranteed) |
diff --git a/skills/cs-schema-markup/scripts/schema_validator.py b/skills/cs-schema-markup/scripts/schema_validator.py
new file mode 100644
index 00000000..b81a059c
--- /dev/null
+++ b/skills/cs-schema-markup/scripts/schema_validator.py
@@ -0,0 +1,442 @@
+#!/usr/bin/env python3
+"""
+schema_validator.py — Extracts and validates JSON-LD structured data from HTML.
+
+Usage:
+ python3 schema_validator.py [file.html]
+ cat page.html | python3 schema_validator.py
+
+If no file is provided, runs on embedded sample HTML for demonstration.
+
+Output: Human-readable validation report + JSON summary.
+Scoring: 0-100 per schema block based on required/recommended field coverage.
+"""
+
+import json
+import sys
+import re
+import select
+from html.parser import HTMLParser
+from typing import List, Dict, Any, Optional
+
+
+# ─── Required and recommended fields per schema type ─────────────────────────
+
+SCHEMA_RULES: Dict[str, Dict[str, List[str]]] = {
+ "Article": {
+ "required": ["headline", "image", "datePublished", "author"],
+ "recommended": ["dateModified", "publisher", "description", "url", "mainEntityOfPage"],
+ },
+ "BlogPosting": {
+ "required": ["headline", "image", "datePublished", "author"],
+ "recommended": ["dateModified", "publisher", "description", "url", "mainEntityOfPage"],
+ },
+ "NewsArticle": {
+ "required": ["headline", "image", "datePublished", "author"],
+ "recommended": ["dateModified", "publisher", "description", "url"],
+ },
+ "HowTo": {
+ "required": ["name", "step"],
+ "recommended": ["description", "image", "totalTime", "tool", "supply", "estimatedCost"],
+ },
+ "FAQPage": {
+ "required": ["mainEntity"],
+ "recommended": [],
+ },
+ "Product": {
+ "required": ["name", "offers"],
+ "recommended": ["description", "image", "sku", "brand", "aggregateRating"],
+ },
+ "Organization": {
+ "required": ["name", "url"],
+ "recommended": ["logo", "sameAs", "contactPoint", "description", "foundingDate"],
+ },
+ "LocalBusiness": {
+ "required": ["name", "address"],
+ "recommended": ["telephone", "openingHoursSpecification", "geo", "priceRange", "image", "url"],
+ },
+ "BreadcrumbList": {
+ "required": ["itemListElement"],
+ "recommended": [],
+ },
+ "VideoObject": {
+ "required": ["name", "description", "thumbnailUrl", "uploadDate"],
+ "recommended": ["duration", "contentUrl", "embedUrl", "interactionStatistic", "hasPart"],
+ },
+ "WebSite": {
+ "required": ["url"],
+ "recommended": ["name", "potentialAction"],
+ },
+ "Event": {
+ "required": ["name", "startDate", "location"],
+ "recommended": ["endDate", "description", "image", "organizer", "offers"],
+ },
+ "Recipe": {
+ "required": ["name", "image", "author", "datePublished"],
+ "recommended": ["description", "cookTime", "prepTime", "totalTime", "recipeYield",
+ "recipeIngredient", "recipeInstructions", "aggregateRating"],
+ },
+}
+
+KNOWN_TYPES = set(SCHEMA_RULES.keys())
+
+
+# ─── HTML Parser to extract JSON-LD blocks ───────────────────────────────────
+
+class JSONLDExtractor(HTMLParser):
+ """Extracts all
+
+
+
+
+
+
+
+
+
+
+
**语言：**
@@ -34,7 +34,7 @@ git clone https://github.com/LeoYeAI/openclaw-master-skills.git
cp -r openclaw-master-skills/skills/