dữ-liệu-c1

---
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]`

FILE:references/ops_cadence.md
# 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.*

FILE:references/process_frameworks.md
# 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.*

FILE:references/scaling_playbook.md
# 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.*

FILE:scripts/okr_tracker.py
#!/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()

FILE:scripts/ops_efficiency_analyzer.py
#!/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"," if d['revenue_per_employee'] else "N/A"
            bench = f"," 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()

---
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]`

FILE:references/pmf_playbook.md
# 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.

FILE:references/product_org_design.md
# 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

FILE:references/product_strategy.md
# 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 |

FILE:scripts/pmf_scorer.py
#!/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()

FILE:scripts/portfolio_analyzer.py
#!/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".1fM"
    elif n >= 1_000:
        return f".0fK"
    return f".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()

---
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

FILE:references/architecture_decision_records.md
# 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)

FILE:references/engineering_metrics.md
# 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 | <Z hrs | ✓/⚠/✗ |
| MTTR | X min | Y min | <Z min | ✓/⚠/✗ |
| Change Failure | X% | Y% | <Z% | ✓/⚠/✗ |

## Team Performance
- Velocity: X story points (Y% of plan)
- Sprint Completion: X%
- Unplanned Work: X%

## Quality Metrics
- Test Coverage: X% (Δ Y%)
- Customer Bugs: X (Δ Y)
- Code Review Coverage: X%

## Highlights
1. [Major feature or improvement]
2. [Technical achievement]
3. [Process improvement]

## Challenges & Solutions
1. Challenge: [Issue]
   Solution: [Action taken]
   
## Next Month Priorities
1. [Priority 1]
2. [Priority 2]
3. [Priority 3]
```

### Quarterly Business Review

```markdown
# Engineering QBR - Q[X] [Year]

## Strategic Alignment
- Business Goal: [Goal]
- Engineering Contribution: [How engineering supported]
- Impact: [Measurable outcome]

## Quarterly Metrics

### Delivery
- Features Shipped: X of Y planned (Z%)
- Major Releases: [List]
- Technical Debt Reduced: X%

### Reliability
- Uptime: X%
- Incidents: X (PY critical, PZ major)
- Customer Impact: [Description]

### Efficiency
- Cost per Transaction: $X (Δ Y%)
- Infrastructure Cost: $X (Δ Y%)
- Engineering Cost per Feature: $X

## Team Growth
- Headcount: Start: X → End: Y
- Attrition: X%
- Key Hires: [Roles]

## Innovation
- Patents Filed: X
- Open Source Contributions: X
- Hackathon Projects: X

## Lessons Learned
1. [What worked well]
2. [What didn't work]
3. [What we're changing]

## Next Quarter Focus
1. [Strategic Initiative 1]
2. [Strategic Initiative 2]
3. [Strategic Initiative 3]
```

## Tool Recommendations

### Metrics Collection
- **DataDog**: Comprehensive monitoring
- **New Relic**: Application performance
- **Grafana + Prometheus**: Open source stack
- **CloudWatch**: AWS native

### Engineering Analytics
- **LinearB**: Developer productivity
- **Velocity**: Engineering metrics
- **Sleuth**: DORA metrics
- **Swarmia**: Engineering insights

### Project Tracking
- **Jira**: Issue tracking
- **Linear**: Modern issue tracking
- **Azure DevOps**: Microsoft ecosystem
- **GitHub Projects**: Integrated with code

### Incident Management
- **PagerDuty**: On-call management
- **Opsgenie**: Incident response
- **StatusPage**: Status communication
- **FireHydrant**: Incident command

## Success Indicators

### Healthy Engineering Organization
✓ DORA metrics improving quarter-over-quarter  
✓ Team satisfaction >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

FILE:references/technology_evaluation_framework.md
# 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<br>3: Meets requirements<br>1: Below requirements |
| **Scalability** | 10% | Ability to grow with needs | 5: Linear scalability<br>3: Some limitations<br>1: Hard limits |
| **Reliability** | 8% | Uptime, fault tolerance | 5: 99.99% SLA<br>3: 99.9% SLA<br>1: <99% SLA |
| **Security** | 8% | Security features, compliance | 5: Exceeds standards<br>3: Meets standards<br>1: Concerns exist |
| **Integration** | 4% | API quality, compatibility | 5: Native integration<br>3: Good APIs<br>1: Limited integration |

### Business Criteria (30%)

| Criterion | Weight | Description | Scoring Guide |
|-----------|--------|-------------|---------------|
| **Cost** | 10% | TCO including licenses, operation | 5: Under budget by >20%<br>3: Within budget<br>1: Over budget |
| **ROI** | 8% | Value generation potential | 5: <6 month payback<br>3: <12 month payback<br>1: >24 month payback |
| **Vendor Stability** | 6% | Financial health, market position | 5: Market leader<br>3: Established player<br>1: Startup/uncertain |
| **Support Quality** | 6% | Support availability, SLAs | 5: 24/7 premium support<br>3: Business hours<br>1: Community only |

### Operational Criteria (30%)

| Criterion | Weight | Description | Scoring Guide |
|-----------|--------|-------------|---------------|
| **Ease of Use** | 8% | Learning curve, UX | 5: Intuitive<br>3: Moderate learning<br>1: Steep curve |
| **Documentation** | 7% | Quality, completeness | 5: Excellent docs<br>3: Adequate docs<br>1: Poor docs |
| **Community** | 7% | Size, activity, resources | 5: Large, active<br>3: Moderate<br>1: Small/inactive |
| **Maintenance** | 8% | Operational overhead | 5: Fully managed<br>3: Some maintenance<br>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.

FILE:scripts/team_scaling_calculator.py
#!/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: ,.0f",
        f"  Total Investment: ,.0f",
        f"  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))

FILE:scripts/tech_debt_analyzer.py
#!/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))

---
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

FILE:references/interview-guide.md
# 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.

FILE:templates/company-context-template.md
# 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)

---
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

FILE:scripts/decision_tracker.py
#!/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("<!--"):
                current.rejected.append(item)
            continue

        if in_actions and line.strip().startswith("- ["):
            action = parse_action_item(line)
            if action:
                current.action_items.append(action)
            continue

    if current:
        decisions.append(current)

    return decisions


# ─────────────────────────────────────────────
# Reports
# ─────────────────────────────────────────────

def fmt_date(d: Optional[date]) -> str:
    return d.strftime("%Y-%m-%d") if d else "—"


def fmt_delta(d: Optional[date]) -> str:
    if not d:
        return ""
    delta = (d - date.today()).days
    if delta < 0:
        return f"  ⚠️  {abs(delta)}d overdue"
    if delta == 0:
        return "  🔴 DUE TODAY"
    if delta <= 3:
        return f"  🟡 {delta}d left"
    return f"  ({delta}d)"


def print_section(title: str):
    print(f"\n{'═' * 60}")
    print(f"  {title}")
    print(f"{'═' * 60}")


def report_summary(decisions: list[Decision]):
    active = [d for d in decisions if d.is_active()]
    all_actions = [a for d in decisions for a in d.action_items]
    open_actions = [a for a in all_actions if not a.completed]
    overdue = [a for a in all_actions if a.is_overdue()]
    overrides = [d for d in decisions if d.has_override()]
    dnr_count = sum(len(d.rejected) for d in decisions)

    print_section("DECISION LOG SUMMARY")
    print(f"  Total decisions:      {len(decisions)}")
    print(f"  Active (not super.):  {len(active)}")
    print(f"  Superseded:           {len(decisions) - len(active)}")
    print(f"  Founder overrides:    {len(overrides)}")
    print(f"  DO_NOT_RESURFACE:     {dnr_count}")
    print(f"  Total action items:   {len(all_actions)}")
    print(f"  Open action items:    {len(open_actions)}")
    print(f"  Overdue:              {len(overdue)}")

    if overdue:
        print(f"\n  {'─' * 40}")
        print(f"  ⚠️  OVERDUE ITEMS ({len(overdue)})")
        print(f"  {'─' * 40}")
        for a in overdue:
            print(f"  • [{a.owner}] {a.text}")
            print(f"    Due: {fmt_date(a.due)}{fmt_delta(a.due)}")

    print(f"\n  {'─' * 40}")
    print(f"  RECENT DECISIONS")
    print(f"  {'─' * 40}")
    for d in sorted(active, key=lambda x: x.date or date.min, reverse=True)[:5]:
        print(f"  [{fmt_date(d.date)}] {d.title}")
        print(f"    Owner: {d.owner or '—'}  |  Deadline: {fmt_date(d.deadline)}")
        open_count = sum(1 for a in d.action_items if not a.completed)
        if open_count:
            print(f"    Open actions: {open_count}")


def report_overdue(decisions: list[Decision]):
    print_section("OVERDUE ACTION ITEMS")
    found = False
    for d in sorted(decisions, key=lambda x: x.date or date.min, reverse=True):
        overdue = [a for a in d.action_items if a.is_overdue()]
        if not overdue:
            continue
        found = True
        print(f"\n  📋 {d.title}  [{fmt_date(d.date)}]")
        for a in overdue:
            print(f"    ⚠️  {a.text}")
            print(f"       Owner: {a.owner or '—'}  |  Due: {fmt_date(a.due)}{fmt_delta(a.due)}")
    if not found:
        print("\n  ✅ No overdue items.")


def report_due_within(decisions: list[Decision], days: int):
    print_section(f"ACTION ITEMS DUE WITHIN {days} DAYS")
    found = False
    for d in sorted(decisions, key=lambda x: x.date or date.min, reverse=True):
        upcoming = [a for a in d.action_items if a.is_due_within(days)]
        if not upcoming:
            continue
        found = True
        print(f"\n  📋 {d.title}  [{fmt_date(d.date)}]")
        for a in upcoming:
            print(f"    • {a.text}")
            print(f"      Owner: {a.owner or '—'}  |  Due: {fmt_date(a.due)}{fmt_delta(a.due)}")
    if not found:
        print(f"\n  ✅ Nothing due in the next {days} days.")


def report_by_owner(decisions: list[Decision], owner: str):
    print_section(f"ACTION ITEMS — OWNER: {owner.upper()}")
    found = False
    for d in sorted(decisions, key=lambda x: x.date or date.min, reverse=True):
        items = [a for a in d.action_items
                 if a.owner.lower() == owner.lower() and not a.completed]
        if not items:
            continue
        found = True
        print(f"\n  📋 {d.title}  [{fmt_date(d.date)}]")
        for a in items:
            flag = "⚠️ OVERDUE" if a.is_overdue() else ""
            print(f"    {'[ ]'} {a.text}  {flag}")
            print(f"      Due: {fmt_date(a.due)}{fmt_delta(a.due)}")
    if not found:
        print(f"\n  No open action items for '{owner}'.")


def report_search(decisions: list[Decision], query: str):
    print_section(f"SEARCH: \"{query}\"")
    q = query.lower()
    found = False
    for d in decisions:
        hit_fields = []
        if q in d.title.lower():
            hit_fields.append("title")
        if q in d.decision.lower():
            hit_fields.append("decision")
        if q in d.rationale.lower():
            hit_fields.append("rationale")
        if any(q in r.lower() for r in d.rejected):
            hit_fields.append("rejected")
        if hit_fields:
            found = True
            print(f"\n  [{fmt_date(d.date)}] {d.title}  (match: {', '.join(hit_fields)})")
            if "decision" in hit_fields:
                print(f"    → {d.decision}")
            if "rejected" in hit_fields:
                matches = [r for r in d.rejected if q in r.lower()]
                for r in matches:
                    print(f"    ✗ [REJECTED] {r}")
    if not found:
        print(f"\n  No results for '{query}'.")


def report_conflicts(decisions: list[Decision]):
    """
    Simple conflict detection: look for decisions on the same topic
    (matching title words) that are both active and have different decisions.
    Also flag if a rejected item appears as a new decision.
    """
    print_section("CONFLICT DETECTION")
    conflicts_found = False

    # Check for DO_NOT_RESURFACE violations
    all_rejected_texts = []
    for d in decisions:
        for r in d.rejected:
            clean = re.sub(r"\[DO_NOT_RESURFACE\]", "", r).strip().lower()
            all_rejected_texts.append((clean, d.date, d.title))

    active = [d for d in decisions if d.is_active()]
    for d in active:
        decision_lower = d.decision.lower()
        for rejected_text, rejected_date, rejected_title in all_rejected_texts:
            if rejected_text and rejected_text in decision_lower:
                conflicts_found = True
                print(f"\n  🚫 POTENTIAL DO_NOT_RESURFACE VIOLATION")
                print(f"    Decision [{fmt_date(d.date)}]: {d.decision}")
                print(f"    Matches rejected item from [{fmt_date(rejected_date)}] ({rejected_title}):")
                print(f"    \"{rejected_text}\"")

    # Check for same-topic contradictions (shared keywords in title)
    stop_words = {"the", "a", "an", "and", "or", "to", "for", "of", "in", "on", "with", "vs"}
    for i, d1 in enumerate(active):
        words1 = set(w.lower() for w in d1.title.split() if w.lower() not in stop_words)
        for d2 in active[i+1:]:
            words2 = set(w.lower() for w in d2.title.split() if w.lower() not in stop_words)
            overlap = words1 & words2
            if len(overlap) >= 2 and d1.decision and d2.decision:
                # Different decisions on similar topic
                if d1.decision.lower() != d2.decision.lower():
                    conflicts_found = True
                    print(f"\n  ⚠️  POTENTIAL CONFLICT (shared topic: {overlap})")
                    print(f"    [{fmt_date(d1.date)}] {d1.title}")
                    print(f"    Decision: {d1.decision}")
                    print(f"    [{fmt_date(d2.date)}] {d2.title}")
                    print(f"    Decision: {d2.decision}")
                    if d1.superseded_by or d2.superseded_by:
                        print(f"    ℹ️  One may supersede the other — check Superseded by fields.")

    if not conflicts_found:
        print("\n  ✅ No conflicts detected.")


# ─────────────────────────────────────────────
# Sample data for --demo mode
# ─────────────────────────────────────────────

SAMPLE_DECISIONS_MD = f"""# Board Meeting Decisions — Layer 2

This file contains ONLY founder-approved decisions.

---

## 2026-02-15 — Spain Market Expansion

**Decision:** Expand to Spain in Q3 2026 with a pilot in Madrid and Barcelona.
**Owner:** CMO
**Deadline:** 2026-03-01
**Review:** 2026-04-01
**Rationale:** Market research shows 40% lower CAC than Germany. Two pilot customers already committed.

**User Override:** Founder reduced pilot scope from 5 cities to 2. Reason: reduce operational risk during expansion.

**Rejected:**
- Launch in all of Spain simultaneously — too resource-intensive at current headcount [DO_NOT_RESURFACE]
- Partner with a local distributor instead of direct sales — margins too low [DO_NOT_RESURFACE]

**Action Items:**
- [x] Hire Spanish-speaking CSM — Owner: CHRO — Completed: 2026-02-28 — Result: Hired Maria G., starts March 10
- [ ] Finalize Madrid pilot customer contracts — Owner: CRO — Due: {(date.today() - timedelta(days=3)).strftime('%Y-%m-%d')} — Review: 2026-04-01
- [ ] Translate app to Spanish (ES-ES) — Owner: CTO — Due: {(date.today() + timedelta(days=5)).strftime('%Y-%m-%d')} — Review: 2026-04-15

**Supersedes:** 
**Superseded by:** 
**Raw transcript:** memory/board-meetings/2026-02-15-raw.md

---

## 2026-02-28 — Pricing Strategy Revision

**Decision:** Move from per-seat to usage-based pricing effective Q2 2026.
**Owner:** CFO
**Deadline:** 2026-03-20
**Review:** 2026-05-01
**Rationale:** Usage-based aligns with customer value. Three enterprise customers requested it explicitly.

**User Override:** 

**Rejected:**
- Freemium tier — not appropriate for enterprise healthcare segment [DO_NOT_RESURFACE]
- Raise prices 30% across the board — too aggressive without usage data [DO_NOT_RESURFACE]

**Action Items:**
- [ ] Model 3 pricing scenarios (conservative/base/aggressive) — Owner: CFO — Due: {(date.today() - timedelta(days=1)).strftime('%Y-%m-%d')} — Review: 2026-03-25
- [ ] Customer interviews on usage patterns (n=10) — Owner: CMO — Due: {(date.today() + timedelta(days=10)).strftime('%Y-%m-%d')} — Review: 2026-04-01
- [ ] Update billing infrastructure for usage tracking — Owner: CTO — Due: 2026-04-01 — Review: 2026-04-15

**Supersedes:** 
**Superseded by:** 
**Raw transcript:** memory/board-meetings/2026-02-28-raw.md

---

## 2026-03-04 — Engineering Hiring Plan Q2

**Decision:** Hire 2 senior engineers in Q2: one ML/AI, one backend. No contractors.
**Owner:** CTO
**Deadline:** 2026-04-15
**Review:** 2026-05-01
**Rationale:** ML roadmap blocked. Backend capacity at 85%. Contractors rejected due to IP risk in regulated domain.

**User Override:** Founder added: "ML hire must have healthcare AI experience. Non-negotiable."

**Rejected:**
- Contract team of 5 for 3 months — IP risk in regulated domain [DO_NOT_RESURFACE]
- Hire junior engineers to save budget — wrong tradeoff at this stage [DO_NOT_RESURFACE]

**Action Items:**
- [ ] Post ML engineer JD — Owner: CHRO — Due: {(date.today() + timedelta(days=2)).strftime('%Y-%m-%d')} — Review: 2026-03-20
- [ ] Post backend engineer JD — Owner: CHRO — Due: {(date.today() + timedelta(days=2)).strftime('%Y-%m-%d')} — Review: 2026-03-20
- [ ] Define ML role requirements with healthcare AI spec — Owner: CTO — Due: {(date.today() + timedelta(days=1)).strftime('%Y-%m-%d')} — Review: 2026-03-15

**Supersedes:** 
**Superseded by:** 
**Raw transcript:** memory/board-meetings/2026-03-04-raw.md
"""


# ─────────────────────────────────────────────
# Main
# ─────────────────────────────────────────────

def load_decisions(decisions_path: Path, demo: bool) -> list[Decision]:
    if demo:
        content = SAMPLE_DECISIONS_MD
    elif decisions_path.exists():
        content = decisions_path.read_text(encoding="utf-8")
    else:
        print(f"  ⚠️  decisions.md not found at: {decisions_path}")
        print(f"  Run with --demo to see sample output.")
        print(f"  To initialize: mkdir -p memory/board-meetings && touch memory/board-meetings/decisions.md")
        sys.exit(1)
    return parse_decisions(content)


def main():
    parser = argparse.ArgumentParser(
        description="Board Meeting Decision Tracker",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("--file", default="memory/board-meetings/decisions.md",
                        help="Path to decisions.md (default: memory/board-meetings/decisions.md)")
    parser.add_argument("--demo", action="store_true",
                        help="Run with built-in sample data (no file needed)")
    parser.add_argument("--summary", action="store_true",
                        help="Show overview: counts, overdue, recent decisions")
    parser.add_argument("--overdue", action="store_true",
                        help="List all overdue action items")
    parser.add_argument("--due-within", type=int, metavar="DAYS",
                        help="List items due within N days")
    parser.add_argument("--owner", metavar="ROLE",
                        help="Filter action items by owner")
    parser.add_argument("--search", metavar="QUERY",
                        help="Search decisions and rejected proposals")
    parser.add_argument("--conflicts", action="store_true",
                        help="Check for contradictory decisions or DO_NOT_RESURFACE violations")
    parser.add_argument("--all", action="store_true",
                        help="Show all decisions (summary format)")

    args = parser.parse_args()

    if not any([args.summary, args.overdue, args.due_within, args.owner,
                args.search, args.conflicts, getattr(args, "all")]):
        args.summary = True  # Default action

    decisions_path = Path(args.file)
    decisions = load_decisions(decisions_path, args.demo)

    if not decisions:
        print("  No decisions found in decisions.md.")
        sys.exit(0)

    if args.demo:
        print(f"\n  🎯 DEMO MODE — using built-in sample data ({len(decisions)} decisions)")

    if args.summary:
        report_summary(decisions)

    if args.overdue:
        report_overdue(decisions)

    if args.due_within:
        report_due_within(decisions, args.due_within)

    if args.owner:
        report_by_owner(decisions, args.owner)

    if args.search:
        report_search(decisions, args.search)

    if args.conflicts:
        report_conflicts(decisions)

    if getattr(args, "all"):
        print_section(f"ALL DECISIONS ({len(decisions)} total)")
        for d in sorted(decisions, key=lambda x: x.date or date.min, reverse=True):
            status = "📦 SUPERSEDED" if not d.is_active() else ""
            override = "  [OVERRIDE]" if d.has_override() else ""
            print(f"\n  [{fmt_date(d.date)}] {d.title} {status}{override}")
            print(f"    Decision: {d.decision}")
            print(f"    Owner: {d.owner or '—'}  |  Deadline: {fmt_date(d.deadline)}")
            open_actions = [a for a in d.action_items if not a.completed]
            if open_actions:
                print(f"    Open actions: {len(open_actions)}")

    print()


if __name__ == "__main__":
    main()

FILE:templates/decision-entry.md
# Decision Entry Template

Single entry for `memory/board-meetings/decisions.md`.
Copy this block and fill it in after each approved board decision.

---

```markdown
## [YYYY-MM-DD] — [AGENDA ITEM TITLE]

**Decision:** [One clear statement of what was decided.]
**Owner:** [Role or name. One person. If it needs two, the first is accountable.]
**Deadline:** [YYYY-MM-DD]
**Review:** [YYYY-MM-DD — when to check. Usually 2–4 weeks after deadline.]
**Rationale:** [Why this over alternatives. 1-2 sentences. No fluff.]

**User Override:** 
<!-- Leave blank if founder approved the agent recommendation.
     Fill in if founder changed something:
     "Founder rejected [agent recommendation] because [reason]. 
      Actual decision: [what founder decided instead]." -->

**Rejected:**
<!-- List every proposal explicitly rejected in this discussion.
     These must not be resurfaced without new information. -->
- [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:** <!-- DATE of the previous decision on this topic, if any -->
**Superseded by:** <!-- Leave blank. Will be filled in if a later decision overrides this. -->

**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.

---
name: dossier
description: "Decision-grade entity research skill — produces a hypothesis-tested dossier on a specific company, person, nonprofit, or government org, not a generic profile. Forcing intake makes the user state their hypothesis upfront (what they already believe and want to verify or disprove) so the dossier tests it rather than confirms it. Output is an editable Word document (.docx) with verdict on the hypothesis, identity facts, 12-month activity timeline, network signals, reputation signals, red flags, 3-5 conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch + free APIs (SEC EDGAR, GitHub, ProPublica Nonprofit Explorer) as workhorses; optional BYOK MCPs (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) enhance coverage. Triggers: 'research [company]', 'dossier on [person/company]', 'background check on [entity]', 'prep me for a meeting with [person/company]', 'due diligence on [company]', 'what should I know about [entity]', 'research [person] before I [meet/hire/invest]', 'competitor research on [company]', 'investor diligence [company]', 'interview prep for [company]'. Honors sensitivity exclusions for journalism + personal-vetting contexts."
license: MIT
metadata:
  source_spec: "megaprompts/12-dossier-megaprompt.md"
  build_pattern: "Path B (direct conversion)"
  research_pack_convention: "Agent Integrity Rules verbatim per PR #657 audit; hypothesis-testing variant"
  version: 1.0.0
---

# Dossier — Decision-Grade Entity Research

> **Portability:** Requires `WebSearch` + `WebFetch`, Node.js with `docx` package, and optionally `bash_tool` + `curl` for free APIs (SEC EDGAR, GitHub, ProPublica). BYOK MCPs (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) are optional enhancements. Works in Claude Code CLI natively.

## Non-Generic Framing — The Differentiator

This skill is **decision-grade entity research with hypothesis-testing**. It **refuses** to be "tell me about Microsoft". Every invocation forces the user to expose their hypothesis upfront (Q4) so the dossier *tests* it rather than confirms it.

The use case shape:

> "I'm pitching Microsoft Tuesday. My hypothesis is they're consolidating AI spend on their first-party Foundry platform. Validate or disprove, and give me three conversation hooks tied to what you find."

**NOT:**

> "Tell me about Microsoft."

The forcing Q4 — the hypothesis question — is the non-generic anchor. Skip it and the skill produces a Wikipedia summary.

See [`references/hypothesis_testing_discipline.md`](references/hypothesis_testing_discipline.md) for the canon.

## Agent Integrity Rules (Research-Pack Convention)

Locked verbatim per PR #657 audit.

- **Execution discipline.** Sequential search calls. WebSearch + WebFetch have looser rate limits than Consensus but still apply 1 q/sec etiquette. Confirm response received before next call.
- **Source discipline.** Cite only sources returned by this session's tool calls. Wikipedia / training knowledge labeled `[Background — verify before quoting]` and excluded from primary findings count.
- **Three-count tracking.** Queries sent / sources received / sources cited. Plus **per-tier breakdown** (primary / secondary / tertiary) unique to dossier. Surfaced in audit log.
- **Retry policy.** On failure → wait 3s → retry once → log. After 3 consecutive failures: stop, alert user.
- **Source reliability tier.** Each citation tagged primary (official, SEC, court records) / secondary (mainstream news, trade press) / tertiary (blogs, forums). DOCX surfaces tier on every flag.

## Phase 1: Grill-Me Intake (6 forcing questions, one at a time)

### Q1 (root) — Subject identity

> **Who is the subject? Give me the exact name and, if a company, the website or LinkedIn URL. If a person, their LinkedIn URL or a unique identifier (company affiliation + role).**
>
> *Why I'm asking:* Disambiguation. There are 47 John Smiths. There are three companies called "Atlas". I need a specific entity to research.

If user gives only a name, push for a second identifier. **Refuse to proceed on ambiguous names.**

### Q2 (depends on Q1) — Subject type

> **What kind of subject is this? Pick one: person / company / nonprofit / government org / other.**
>
> *Why I'm asking:* Different source matrices apply. For people I check LinkedIn, GitHub, Scholar, news; for companies I check SEC EDGAR (if public), Crunchbase, news, GitHub for tech orgs; for nonprofits I check Form 990s on ProPublica.

Forcing choice. "Other" requires a one-line description.

### Q3 (depends on Q2) — Purpose

> **What are you preparing for? Pick one:**
>
> 1. Sales meeting / partnership pitch
> 2. Investment diligence
> 3. Acquisition diligence
> 4. Journalism / due diligence
> 5. Job interview prep
> 6. Competitive intelligence
> 7. Personal vetting (date, hire, business partner)
> 8. Other (specify)
>
> *Why I'm asking:* The purpose dictates the angle, the depth, and the red-flag sensitivity. Sales prep needs conversation hooks. Investment diligence needs traction signals. Personal vetting needs careful sensitivity boundaries.

### Q4 (depends on Q3) — **Hypothesis — MANDATORY**

> **What's your hypothesis going in? What do you already believe about this subject, and what do you want to verify or disprove?**
>
> *Why I'm asking:* This is the critical question. A dossier that just confirms what you already think is worthless. By stating your hypothesis upfront, I can search for evidence that would *disprove* it as well as evidence that supports it — and give you a verdict you can actually use.
>
> Examples:
> - "I believe Microsoft is consolidating AI spend on first-party Foundry. Verify or disprove."
> - "I think the CEO is over their head — too much TAM talk, no traction. Test that."
> - "I believe this nonprofit's overhead ratio is sketchy. Check the 990s."
> - "I think this person is technical enough to handle a CTO role. Verify."

**MANDATORY.** If user says "I don't have one", push back **once**: "Then guess. Commit to a position you can update later. The dossier needs a hypothesis to test, otherwise it's a generic profile and won't help you make a decision."

If still refused: fall back to implicit hypothesis "what's the most surprising thing I could find?" and **flag the fallback in audit log**.

This question is **the non-generic anchor**. Skip it and the skill becomes a Wikipedia summary.

### Q5 (depends on Q3) — Depth

> **Time horizon: 5-minute brief or 15-minute decision-grade dossier?**
>
> *Why I'm asking:* Brief mode caps at ~10 searches and skips the network + reputation passes. Decision-grade goes deeper on every section. Pick based on how much skin you have in this decision.

Forcing choice.

### Q6 (asked only if Q3 ∈ {journalism, personal vetting}) — Sensitivities

> **Anything sensitive to exclude? E.g., personal medical, family details, political history, or specific topics off-limits?**
>
> *Why I'm asking:* Some research contexts have ethical constraints. I'd rather know upfront than surface something you'd never share.

Skip for sales/investment/acquisition/competitive intel (low sensitivity); ask for journalism/personal vetting (high sensitivity).

**Stop condition:** After Q6 (or earlier with dependency skips), commit and start Phase 2. Never re-open intake after Phase 2 begins.

## Phase 2: Subject Disambiguation

Before Phase 3, resolve the subject to a specific entity:

- For people: confirm LinkedIn URL OR (employer + role + city)
- For companies: confirm domain OR (legal name + incorporation jurisdiction)
- For nonprofits: confirm EIN OR (legal name + state)
- For government orgs: confirm official .gov URL

If still ambiguous after Q1 push-back: **halt and re-ask Q1** with disambiguating identifiers. Refuse to proceed.

## Phase 3: Source Matrix Selection

Routed by Q2 subject type. See [`references/subject_type_source_matrix.md`](references/subject_type_source_matrix.md) for the full canon.

### Person

- LinkedIn (manual fetch or LinkedIn MCP if BYOK)
- Personal website
- Twitter/X (rate-limited; degrade gracefully)
- GitHub (if technical subject)
- Google Scholar (if academic)
- News (WebSearch + WebFetch)
- Conference talk transcripts, podcasts (WebSearch)

### Company

- Official website (about, leadership, news, careers)
- SEC EDGAR (free API; 10-Ks, 10-Qs, 8-Ks for public co's)
- Crunchbase free tier (or Crunchbase MCP if BYOK)
- News (WebSearch + WebFetch)
- GitHub (for tech orgs)
- Glassdoor + Comparably (sentiment; degrade gracefully if scraping blocked)
- LinkedIn company page

### Nonprofit

- ProPublica Nonprofit Explorer (free; Form 990s)
- Official website
- News
- GuideStar (if accessible)

### Government org

- Official .gov sites
- News
- ProPublica (for federal agencies)

If a paid MCP is connected (Apollo, Pitchbook, SimilarWeb), use it but mark findings as **BYOK-sourced** in the audit log.

## Phase 4: Hypothesis-Driven Search

Every Phase 4 search MUST be classified as either:

- **Supporting evidence** (confirms hypothesis), OR
- **Disconfirming evidence** (would refute hypothesis)

**≥30% of search budget allocated to disconfirming queries.** Enforced via `scripts/disconfirming_evidence_balance.py`.

Example for hypothesis "Microsoft is consolidating AI spend on Foundry":

- **Supporting:** "Microsoft Foundry adoption 2026", "Microsoft AI infrastructure consolidation"
- **Disconfirming:** "Microsoft OpenAI deal renegotiation", "Microsoft AI vendor diversification", "Microsoft third-party model partnerships 2026"

This is what makes the dossier **decision-grade** rather than confirmation-biased.

For each search:
- Record via `citation_tracker.py` with classification (supporting / disconfirming)
- Apply source tier from `source_tier_classifier.py` to each result URL

## Phase 5: 12-Month Activity Timeline

Default 12-month window for activity timeline; deeper for foundational identity.

Categories:
- News (acquisitions, hires, departures, product launches)
- Funding rounds / financial events
- Controversies / legal events
- Public statements / strategy shifts

Reverse chronological. Each entry hyperlinked + tiered.

## Phase 6: Network + Reputation Signals

### Network

- **Companies:** investors (in/out), customers (named), partners
- **People:** co-founders, advisors, mentors, employers, board roles
- **Nonprofits:** funders, board, leadership

5-10 entries, ranked by **relevance to hypothesis**.

### Reputation

- Sentiment from news (recent 12 months)
- Glassdoor for companies (overall rating + 3 representative reviews)
- Peer mentions for people
- Caveat: reputation data is noisy; tier accordingly

## Phase 7: Red-Flag Pass

Surface but don't sensationalize:

- Litigation (court records → primary tier)
- Regulatory actions (SEC, DOJ, agency actions → primary)
- Unusual departures (key personnel exits within 90 days)
- Financial signals (going-concern notes in 10-Ks → primary)
- Reputation hits (sustained negative coverage → secondary)

**Each flag tiered.** Tier shows up next to every flag in the DOCX.

## Phase 8: Conversation Hook Generation

3-5 specific hooks tied to **actual findings**, not generic talking points.

See [`references/conversation_hook_quality.md`](references/conversation_hook_quality.md) for the canon.

| ❌ Generic | ✅ Finding-tied |
|---|---|
| "Ask about their roadmap" | "Mention their recent acquisition of [X] — it signals they're investing in vertical Y. Suggested framing: 'Saw the [X] announcement — how does that change your roadmap on Y?'" |
| "Ask about hiring" | "Their VP Engineering left 3 weeks ago (LinkedIn). Suggested framing: 'I noticed [name] moved on — what's the eng leadership plan?'" |
| "Talk about their values" | "They updated their pricing page last week (their official site). Suggested framing: 'Saw the pricing refresh — what drove that?'" |

Each hook:
- **The hook** (one sentence)
- **The finding it's tied to** (with hyperlink + tier)
- **Suggested framing** (verbatim phrasing user can adapt)

## Phase 9: DOCX Generation (9 Sections)

Via Node.js + `docx` library.

1. **Executive Summary** — one paragraph: who they are + why they matter + **verdict on the hypothesis** (SUPPORTED / PARTIALLY SUPPORTED / DISPROVEN / INCONCLUSIVE) + 3 things-you-should-know bullets.
2. **Identity Facts Table** — founded/born, location, size/stage, current role, key affiliations. All cells sourced; hover-text tier.
3. **Hypothesis Test** — user's hypothesis stated verbatim. Supporting evidence (3-5 bullets with hyperlinked citations). Disconfirming evidence (3-5 bullets with hyperlinked citations). Verdict paragraph (2-3 sentences explaining the weight).
4. **12-Month Activity Timeline** — News, funding, hires, departures, product launches, controversies. Reverse chronological. Each entry hyperlinked.
5. **Network Signals** — Collaborators / investors / associates. 5-10 entries, ranked by relevance to hypothesis.
6. **Reputation Signals** — Sentiment from news, Glassdoor for companies, peer mentions for people. Caveat: reputation data is noisy.
7. **Red Flags + Hidden Patterns** — Litigation, regulatory actions, unusual departures, financial signals, reputation hits. Tiered.
8. **Conversation Hooks** — 3-5 specific hooks tied to findings. Each: hook + finding + suggested framing.
9. **Source Provenance + Audit Log** — Per-source list with tier. Search summary table (#, query, classification, sources returned, sources cited). Three counts + per-tier counts. Failed searches. BYOK-MCP usage flag.

### Styling

Arial 12pt body, navy headings (#1a3a5c), light blue table headers (#e8f0f8), red red-flag callout, green conversation-hook callout.

### Hyperlink patterns

```js
new ExternalHyperlink({
  link: "https://...",
  children: [new TextRun({ text: title, style: "Hyperlink" })],
});
```

## Phase 10: Deliver

- Save: `<output-dir>/dossier_<entity-slug>_<YYYY-MM-DD>.docx`
- Chat summary: file path + **verdict on hypothesis** + audit counts + tier breakdown + BYOK MCPs used (if any)
- Validate: `python scripts/office/validate.py <docx>`

## Tooling

| Script | Role |
|---|---|
| `scripts/citation_tracker.py` | Three-count audit + supporting/disconfirming classification + source-tier tagging at `~/.dossier_sessions/<session>.json` |
| `scripts/disconfirming_evidence_balance.py` | Verifies ≥30% of search budget allocated to disconfirming queries; warns if biased |
| `scripts/source_tier_classifier.py` | URL → primary / secondary / tertiary classification via domain heuristics |

## References

- [`references/hypothesis_testing_discipline.md`](references/hypothesis_testing_discipline.md) — ≥30% rule + decision-grade vs encyclopedic (7+ sources)
- [`references/subject_type_source_matrix.md`](references/subject_type_source_matrix.md) — person/company/nonprofit/gov source matrices (7+ sources)
- [`references/conversation_hook_quality.md`](references/conversation_hook_quality.md) — finding-tied hook discipline (7+ sources)

## Error Handling

| Failure | Behavior |
|---|---|
| Subject name ambiguous | Refuse to proceed. Re-ask Q1 with disambiguating identifier. |
| User refuses to state hypothesis | Push back once. If still refused, fall back to "what's the most surprising thing I could find?" implicit hypothesis. Flag in audit. |
| Subject has zero public footprint | Surface explicitly. Suggest different name or early-stage. Don't fabricate. |
| LinkedIn scrape blocked | Note in audit; fall back to WebSearch; suggest user verify manually. |
| SEC EDGAR fails | Retry once. If still failing, note "public filings not retrieved" and continue. |
| Sentiment data sparse | Mark reputation section as "limited public signal"; don't infer from training. |
| Sensitive topic surfaces (Q6 exclusion) | Exclude from DOCX. Note in chat (not in DOCX) so user knows the exclusion was honored. |
| 3 consecutive tool failures | Stop, alert user, share collected so far. |
| DOCX generation fails | Save raw data as JSON fallback. |

## Anti-Patterns To Reject

- Producing a dossier without forcing Q4 hypothesis
- Allocating <30% of search budget to disconfirming evidence
- Batching intake questions
- Accepting ambiguous subject names
- Generic conversation hooks ("ask about their roadmap")
- Sensationalizing red flags (tier them, don't editorialize)
- Skipping the source-reliability tier on flags
- Fabricating coverage when LinkedIn or scraping is blocked
- Using BYOK-MCP data without flagging in audit log
- Including sensitive topics user excluded in Q6
- Confirmation-biased verdict ("SUPPORTED" without engaging with disconfirming evidence)

---

**Version:** 1.0.0
**Source spec:** [`megaprompts/12-dossier-megaprompt.md`](../../../../megaprompts/12-dossier-megaprompt.md)
**Build pattern:** Path B (direct conversion). Research-pack sibling, hypothesis-testing variant.

FILE:references/conversation_hook_quality.md
# Conversation Hook Quality — Finding-Tied vs Generic

This reference answers exactly one decision: **what makes a conversation hook (Section 8 of the dossier DOCX) useful enough to justify a meeting prep workflow?**

## The Core Frame

A conversation hook is useful when it:

1. References a **specific recent finding** (timestamped, sourced)
2. Provides **suggested framing** (verbatim phrasing the user can adapt)
3. Connects the finding to **the meeting's purpose** (sales pitch / investment / hire)

A generic hook is useful for nothing. "Ask about their roadmap" doesn't help the user — they already knew they could ask about that.

## The Quality Bar

A hook passes if all three are true:

✅ Specific finding from this dossier (with hyperlink)
✅ Suggested phrasing (1-2 sentences)
✅ Tied to user's hypothesis or meeting purpose

A hook fails if any of:

❌ Generic ("ask about their priorities")
❌ Unsourced ("they're probably hiring")
❌ Untimely (>6 months old finding without explicit recency note)
❌ Speculative ("they might be considering X")
❌ Not actionable in the meeting context

## Side-by-Side Examples

### Sales prep for AI infrastructure company

| ❌ Generic | ✅ Finding-tied |
|---|---|
| "Ask about their AI strategy." | "Mention their recent acquisition of Hugging Face vendor [X] (announced 2 weeks ago via TechCrunch). Suggested framing: *'Saw the [X] acquisition — how does that change your model deployment story?'*" |
| "Talk about pricing." | "Their pricing page was updated last Thursday (their official site). The change adds a per-token usage tier. Suggested framing: *'Noticed the new usage tier — was that customer-driven or competitive response?'*" |
| "Ask about their team." | "Their VP Eng [name] left 3 weeks ago (LinkedIn). Their job board posted a Director of AI Engineering req last Friday. Suggested framing: *'I noticed [name] moved on and you're hiring an AI Eng Director — what's the eng leadership focus shifting toward?'*" |

### Investment diligence on founder

| ❌ Generic | ✅ Finding-tied |
|---|---|
| "Test technical depth." | "She published 3 technical blog posts on her personal site this year (links in Section 1) on distributed systems. Suggested probe: *'Your post on consensus protocols was sharp — what's the actual implementation challenge you're hitting on [their startup]?'*" |
| "Check for red flags." | "Her co-founder left the company 4 months ago — no public statement either side (LinkedIn + her bio update). Suggested probe: *'I noticed [co-founder] is no longer listed — what's the founding-team story now?'*" |
| "Ask about market." | "They raised $5M seed in Feb 2024, now hiring 3 GTM roles (Crunchbase + LinkedIn). Suggested probe: *'You're staffing GTM heavily for a $5M seed — what's the pipeline that justifies that shape?'*" |

## Hook Construction Pattern

```
Hook = Finding + Suggested Framing + Tied-To-Purpose

Where:
  Finding         = specific event, statement, change, or signal (with URL + tier)
  Suggested       = verbatim 1-2 sentence question or comment user can adapt
  Tied-To-Purpose = connection to Q3 purpose + Q4 hypothesis
```

## Anti-Patterns

### "Ask about their values/culture/roadmap/strategy"

These are generic openers, not conversation hooks. The user already knew they could ask about strategy. The hook should surface **specific evidence the user didn't have before**.

### "I suggest mentioning their recent quarter"

If the dossier doesn't cite a specific quarter result, this is speculation. Hooks must be evidence-anchored.

### "They might appreciate hearing about [generic topic]"

The hook should be about the user finding signal, not about the subject's preferences. Frame as: "Here's what the user just learned and can leverage."

### "Hooks tied to private/sensitive findings"

If Q6 (sensitivities) excluded family / medical / political, the hook also can't lean on those even tangentially. Check exclusions before drafting.

### "5+ hooks padding"

3-5 hooks is the sweet spot. More dilutes signal. If only 3 strong hooks emerge from findings, ship 3 — don't pad to 5 with weak ones.

### "Generic LinkedIn-style hook"

"I saw you went to Stanford — I went to Stanford too" — this is networking small-talk, not a substantive hook. Substantive hooks reveal the user did homework.

## Hook Tier (Implicit)

Hooks inherit the source tier of their underlying finding:

| Tier | Hook reliability |
|---|---|
| Primary (SEC, court, official site) | High — user can confidently lead with this |
| Secondary (mainstream news) | Medium — user can lead but acknowledge source |
| Tertiary (blog, forum) | Low — user should treat as soft signal, frame cautiously |

The DOCX tier-tag on each hook lets the user calibrate their conversational confidence.

## Hook Discipline by Purpose (Q3)

| Purpose | Hook flavor |
|---|---|
| Sales pitch | Lead with their recent moves; show you've done homework on their context |
| Investment diligence | Probe contradictions; surface red flags as questions, not accusations |
| Acquisition diligence | Test fit assumptions; ask about org culture + leadership stability |
| Journalism | Get them on the record about specific findings (named source + ask) |
| Interview prep | Show domain knowledge tied to their actual work, not generic praise |
| Competitive intelligence | (not for in-person meeting) — convert hooks to internal team briefing notes |
| Personal vetting | Generally skip hooks; vetting is a one-way information flow |

## Operational Checklist

- [ ] 3-5 hooks (not more, not fewer if findings support it)
- [ ] Each hook references a specific finding from this dossier
- [ ] Each finding has a hyperlink (Phase 4 search result)
- [ ] Each hook has suggested framing (1-2 sentences, verbatim adaptable)
- [ ] Each hook tied to Q3 purpose
- [ ] Each hook tiered (primary / secondary / tertiary based on underlying finding)
- [ ] No hook leans on Q6 excluded topics
- [ ] No hook is purely speculative or generic

## Citations (7 sources)

1. **Dale Carnegie, *How to Win Friends and Influence People* (1936).** The original "show genuine interest" framing. Conversation hooks operationalize this — but require specific evidence, not generic friendliness.

2. **Robert Cialdini, *Influence* (1984, multiple eds.).** Source for the "reciprocity" principle that hooks invoke. When the user signals they've done substantive homework, the subject reciprocates with substantive engagement.

3. **Chris Voss, *Never Split the Difference* (2016).** Source for the "calibrated question" pattern. Voss's "how" / "what" questions tied to specifics outperform generic "yes/no" questions. The dossier's suggested-framing examples follow this pattern.

4. **Daniel Goleman, *Working with Emotional Intelligence* (1998).** Source for the "social awareness" pillar of EI. Hooks operationalize this — surfacing recent specific context shows the user is reading the room.

5. **Patrick Lencioni, *The Five Dysfunctions of a Team* (2002).** Indirect source — Lencioni's "vulnerability-based trust" works because specific shared context creates faster intimacy than generic small-talk.

6. **Carmine Gallo, *Talk Like TED* (2014).** Source for the "lead with the surprising data point" rhetorical pattern. The strongest hooks open with a specific finding the subject didn't expect the user to know.

7. **Edgar Schein, *Humble Inquiry* (2013).** Source for the framing-as-question discipline. Hooks framed as questions ("how does that change your roadmap?") outperform hooks framed as observations ("interesting that you...") because questions invite reciprocal disclosure.

FILE:references/hypothesis_testing_discipline.md
# Hypothesis-Testing Discipline — Why ≥30% Disconfirming

This reference answers exactly one decision: **why does the dossier skill demand a hypothesis upfront and allocate ≥30% of search budget to disconfirming evidence?**

## The Core Claim

A dossier that confirms what the user already thinks is **worthless for decision-making**. Decisions hinge on the evidence that might falsify your model — that's where new information lives. A confirmation-biased dossier feels reassuring but doesn't move the user closer to a good decision.

The ≥30% disconfirming rule is the operational implementation of Karl Popper's falsifiability principle adapted to research workflows.

## Why the User Must State a Hypothesis (Q4 Mandatory)

Without a stated hypothesis, the skill can't:

1. Classify searches as supporting or disconfirming
2. Allocate budget to disconfirming queries
3. Produce a verdict (SUPPORTED / PARTIALLY / DISPROVEN / INCONCLUSIVE)
4. Test anything — by definition, you can only test a specific claim

The skill **refuses** to proceed without Q4 because the alternative is producing a Wikipedia summary marketed as decision-grade research.

### What "I don't have a hypothesis" really means

Usually one of:
- "I haven't thought about it yet" → push back once: "Then guess. Commit to a position you can update."
- "I want to be neutral" → false neutrality. Everyone has a prior; surfacing it is healthier than pretending not to.
- "I'm just curious" → use a different tool (web search, ChatGPT). Dossier is for decisions.

### Implicit-hypothesis fallback

If user STILL refuses after the push-back, fall back to:

> Implicit hypothesis: "What's the most surprising thing I could find about this entity that would change someone's prior?"

**Flag the fallback in audit log.** Users should know they got a less-rigorous version of the workflow.

## The ≥30% Rule

For every Phase 4 search, classify it:

- **Supporting** — would confirm the hypothesis if results favorable
- **Disconfirming** — would refute the hypothesis if results favorable

Then verify (via `scripts/disconfirming_evidence_balance.py`):

```
disconfirming_ratio = disconfirming_queries / total_queries
require: disconfirming_ratio >= 0.30
```

### Why 30%, not 50%?

50% (balanced supporting + disconfirming) is the textbook ideal but impractical:

- Many hypotheses have asymmetric search space (more supporting angles obvious; disconfirming requires creativity)
- Hypothesis statements are usually slightly true — pure 50/50 over-rotates to false-balance

30% is the empirical floor: enough disconfirming to surface real surprises, not so much that the dossier feels like a hatchet job.

### Why not 0% (skip the rule)?

LLMs are particularly prone to confirmation bias because:
- Plausible-sounding supporting evidence is easier to generate
- Users tend to accept confirmation more readily (less friction)
- The "feels right" signal is the same for confirmation and truth

Without the explicit ≥30% rule, dossiers drift to ~10% disconfirming. The rule forces the discipline.

## Constructing Disconfirming Queries

For each supporting query, construct a disconfirming counterpart:

| Hypothesis | Supporting | Disconfirming |
|---|---|---|
| "Microsoft consolidating AI on Foundry" | "Microsoft Foundry adoption" | "Microsoft AI vendor diversification" |
| "CEO is over their head" | "CEO Smith strategy failures" | "CEO Smith wins / traction" |
| "Nonprofit overhead is sketchy" | "Nonprofit X high overhead complaints" | "Nonprofit X program spending" |
| "This person is technical enough" | "Skills gaps in [person]" | "Technical accomplishments of [person]" |

The disconfirming queries seek **evidence that would refute the hypothesis**. They are NOT softer versions of the supporting query.

### Common construction patterns

- **Antonym pivot:** "consolidating" → "diversifying"
- **Counter-example search:** "failures" → "wins"
- **Negation:** "true" → "false claims about"
- **Comparison:** "X is best" → "X vs alternatives weakness"
- **Time-shift:** "now" → "5 years ago context"
- **Counter-stakeholder:** "investors say" → "critics say"

## The Verdict Categories

After Phase 4 search completes, classify the evidence weight:

| Verdict | Criterion |
|---|---|
| **SUPPORTED** | ≥2x more supporting evidence than disconfirming, both well-tiered |
| **PARTIALLY SUPPORTED** | More supporting than disconfirming but real disconfirming evidence exists |
| **DISPROVEN** | More disconfirming than supporting |
| **INCONCLUSIVE** | Roughly balanced OR insufficient evidence overall |

**Critical:** the verdict is determined by the **weight of evidence**, not by the count of queries. If 5 supporting queries each found weak tertiary blog posts and 2 disconfirming queries found SEC filings, the disconfirming evidence wins on tier.

`citation_tracker.py` tracks both quantity and tier per classification.

## Anti-Patterns

### "I'll just ask balanced questions"

Generic balanced questions ("what does the public say about Microsoft?") don't test the hypothesis. They produce a balanced profile, not a decision-grade dossier. The discipline is targeted disconfirming queries against a specific claim.

### "I found 10 supporting, 0 disconfirming — must be true"

Almost never. Either:
- The disconfirming queries weren't constructed (bias)
- The disconfirming search space wasn't explored (laziness)
- The hypothesis was trivially true (in which case, why use the skill?)

When this happens, the script alerts and prompts more disconfirming queries.

### "Disconfirming evidence found, but it's tertiary"

Tier matters more than quantity. 1 primary disconfirming source (SEC filing, court record) > 5 tertiary disconfirming sources (Reddit threads). The verdict weights tier explicitly.

### "Confirmation-biased verdict"

The most common failure: the dossier finds disconfirming evidence in Phase 4 but the Executive Summary says SUPPORTED anyway. The skill is wired to fail this — the verdict comes from `citation_tracker`'s tier-weighted classification, not from narrative.

### "Hypothesis vague enough that anything supports it"

"This person is competent" is too vague — almost everything supports it. The push-back: "Competent at what specifically? At managing a team of 50? At raising Series B? At public speaking?" Specificity in the hypothesis enables sharp disconfirming queries.

## Operational Checklist

- [ ] Q4 hypothesis stated (or implicit-hypothesis fallback flagged)
- [ ] Each Phase 4 query classified at issue time (supporting / disconfirming)
- [ ] Pre-flight check: ≥30% queries planned to be disconfirming
- [ ] Mid-flight check: after every 3 queries, run `disconfirming_evidence_balance.py`
- [ ] Post-flight check: final ratio ≥30%; halt + alert if not
- [ ] Verdict reflects tier-weighted balance, not raw quantity
- [ ] Section 3 of DOCX explicitly lists BOTH supporting + disconfirming evidence
- [ ] Audit log records classification per query

## Citations (7 sources)

1. **Karl Popper, *The Logic of Scientific Discovery* (1934, English 1959).** Foundational source for falsifiability. "A theory which is not refutable by any conceivable event is non-scientific." The dossier skill's hypothesis-testing discipline is Popper applied to research workflows.

2. **Daniel Kahneman, *Thinking, Fast and Slow* (FSG, 2011), Chapters 12-22.** Source for confirmation bias mechanics. The ≥30% rule exists specifically because System 1 thinking under-weights disconfirming evidence by default.

3. **Philip Tetlock, *Superforecasting* (Crown, 2015).** Empirical evidence that "active open-mindedness" (Tetlock's term for hypothesis-testing) is the #1 predictor of forecasting accuracy. Source for the "weight of evidence, not count" verdict rule.

4. **Robyn Dawes, *Rational Choice in an Uncertain World* (2001 2nd ed.).** Source for the decision-grade framing. "A decision is grade-A when it uses the available evidence to maximally update from prior." Without disconfirming evidence, no update is possible.

5. **Nassim Nicholas Taleb, *The Black Swan* (Random House, 2007).** Source for the "black swan" rationale — disconfirming evidence is often where the high-information surprises live. Confirmation-biased search systematically misses tail risks.

6. **Karl Popper, *Conjectures and Refutations* (1963).** Companion to *Logic of Scientific Discovery*. Source for the conjecture-and-refutation cycle that the skill implements: state hypothesis → seek refutation → revise.

7. **Daniel Levitin, *A Field Guide to Lies* (Dutton, 2016).** Practical applications of statistical and inferential reasoning. Source for the source-tier framework — primary sources (SEC, court records) outweigh tertiary sources (blogs, forums) for verdict determination.

FILE:references/subject_type_source_matrix.md
# Subject-Type Source Matrix — Person / Company / Nonprofit / Gov

This reference answers exactly one decision: **given the subject type (Q2), what sources does the dossier query in what order?**

## The Core Frame

Different entity types have different evidence sources with different reliability. Querying the wrong sources for the type produces noise; querying the right sources in the right order maximizes signal per query.

The matrix below is **comprehensive but selective** — not every source needs querying every time. Use Q3 (purpose) + Q5 (depth) to pick which subset.

## Person

### Primary tier
- **LinkedIn profile** (manual fetch or LinkedIn MCP if BYOK)
- **Personal website** (if exists)
- **Court records** (PACER, state court systems) — only for journalism/personal-vetting contexts
- **Academic publications** (Google Scholar) — for academics + technical people

### Secondary tier
- **News mentions** (WebSearch + WebFetch)
- **GitHub profile** (if technical subject)
- **Conference talks** (YouTube, conference sites)
- **Podcasts they appeared on** (WebSearch)
- **Books / articles they authored** (Amazon, JSTOR)

### Tertiary tier
- **Twitter/X** (rate-limited; degrade gracefully)
- **Reddit mentions**
- **Glassdoor reviews if they're a manager** (peers anonymous)
- **Personal blog posts**

### Subject-specific paths

| Purpose | Priority sources |
|---|---|
| Investment diligence on founder | LinkedIn + GitHub + court records + news |
| Interview prep for hiring | LinkedIn + GitHub + their public talks + writing |
| Personal vetting (date) | LinkedIn + news + court records (with Q6 exclusions) |
| Sales prep for pitch meeting | LinkedIn + recent public statements + their writing |

### Anti-patterns

- LinkedIn scraping without BYOK MCP — usually blocked; degrade gracefully
- Citing tertiary social media as primary signal (high noise)
- Ignoring publication / talk history for technical subjects (highest-signal source)

## Company

### Primary tier
- **Official website** (about, leadership, news, careers, pricing pages)
- **SEC EDGAR** (public companies) — 10-K, 10-Q, 8-K filings
- **Form 990** if foundation-affiliated
- **Court records** (litigation, regulatory) — federal + state
- **Patent filings** (USPTO + Google Patents) — for tech companies

### Secondary tier
- **Crunchbase free tier** (or Crunchbase MCP if BYOK)
- **News coverage** (WebSearch + WebFetch — major outlets)
- **Trade press** (TechCrunch, The Information, Stratechery for tech; Modern Healthcare for healthcare; etc.)
- **Investor letters / shareholder communications** (Berkshire, ARK, etc.)
- **Industry analyst reports** (if accessible)

### Tertiary tier
- **Glassdoor + Comparably** (employee sentiment — noisy but signal-y for trends)
- **Reddit / HN** (technical / startup sentiment)
- **LinkedIn company page**
- **GitHub** (for tech companies — repo activity signals)

### Subject-specific paths

| Purpose | Priority sources |
|---|---|
| Sales pitch | Official site + recent news + leadership + product launches |
| Investment diligence | SEC filings + Crunchbase + news + patent activity + financial trends |
| Acquisition diligence | SEC + court records + patent portfolio + Glassdoor (cultural fit) |
| Competitive intelligence | SEC + product launches + hiring patterns + patent activity |
| Journalism | Court records + SEC + regulatory actions + sources |

### Critical: SEC EDGAR for public companies

For US-listed companies, SEC EDGAR is **always primary tier** and **always free**:

```bash
curl 'https://data.sec.gov/submissions/CIK<10-digit-CIK>.json' \
  -H 'User-Agent: dossier-skill <user-email>'
```

- 10-K = annual report (audited financials)
- 10-Q = quarterly report
- 8-K = material event (CEO change, M&A, etc.)

Going-concern notes in 10-Ks are critical red-flag signal.

## Nonprofit

### Primary tier
- **ProPublica Nonprofit Explorer** (free; Form 990s + 990-T) — the canonical source
- **GuideStar** (if accessible)
- **Official website** + their published impact reports
- **State Attorney General nonprofit registry** (state-specific)

### Secondary tier
- **News coverage**
- **Charity Navigator ratings**
- **GiveWell / EA evaluations** (if EA-adjacent)
- **Board affiliations** (LinkedIn + foundation database)

### Tertiary tier
- **Social media coverage**
- **Donor forums**
- **Reviews sites** (Charity Watch, etc.)

### Subject-specific paths

| Purpose | Priority sources |
|---|---|
| Donor diligence | Form 990 + impact reports + board + financial trends |
| Board diligence | Form 990 + board members + governance docs |
| Journalism | Form 990 + court records + state AG actions + sources |

### Form 990 key metrics

- **Overhead ratio** (program / total expenses) — but beware: too-low can signal misclassification
- **Executive compensation** (Form 990 Schedule J)
- **Independent board %** — for governance signal
- **Related-party transactions** (Schedule L)
- **Going-concern notes** if any

## Government Org

### Primary tier
- **Official .gov website**
- **Federal Register notices** (regulations, rules)
- **GAO reports** (Government Accountability Office)
- **OIG reports** (Office of Inspector General per agency)
- **Congressional testimony / hearings**

### Secondary tier
- **News coverage** (especially WaPo, ProPublica federal beat)
- **ProPublica federal agency tracking**
- **Think tank reports** (Brookings, AEI, Heritage, etc.)

### Tertiary tier
- **Reddit / forum coverage**
- **Op-eds**

### Subject-specific paths

| Purpose | Priority sources |
|---|---|
| Federal contractor diligence | SAM.gov + agency procurement records + GAO + news |
| Journalism | GAO + OIG + Congressional + court records + sources |
| Lobbying targeting | LDA filings + agency contacts + hearings |

## BYOK MCP Enhancement

Paid MCPs (Apollo, Pitchbook, SimilarWeb, LinkedIn) add data but **must be flagged in audit log**:

| MCP | What it adds |
|---|---|
| LinkedIn | Person profile completeness, employment history accuracy |
| Crunchbase | Funding rounds, board, M&A activity for private companies |
| Apollo | Contact data, intent signals for sales contexts |
| Pitchbook | Deep private-market data, comparables |
| SimilarWeb | Traffic + competitive intelligence for digital businesses |

The audit log marks every BYOK-sourced finding with `[BYOK: <MCP-name>]` so the reader knows the provenance and can request verification through their own MCP access if needed.

## Sequential vs Parallel Discipline

Per research-pack convention: **sequential** with 1 q/sec etiquette. WebSearch + WebFetch tolerate higher rates than Consensus, but sequential keeps the skill robust to provider rate-limit shifts.

For multi-query subjects (companies with many available sources), Phase 4 might run 8-15 sequential queries. Total wall-clock: 10-20 seconds for queries; longer for fetches.

## Degradation Strategy

When a source fails:

| Source | If unavailable |
|---|---|
| LinkedIn | Fall back to WebSearch for headline facts; suggest user verify manually |
| SEC EDGAR | Retry once; if still down, note "public filings not retrieved" |
| Crunchbase | Use news + LinkedIn + WebSearch for funding rounds |
| ProPublica | Direct IRS query (slower); or note nonprofit data partial |
| Twitter/X | Skip; note in audit |

Never fabricate coverage when source is blocked. Always document the gap.

## Citations (7 sources)

1. **SEC EDGAR API documentation — https://www.sec.gov/edgar/sec-api-documentation.** Source for the public-company primary-tier discipline. EDGAR is the only free source for audited financial truth on US public companies.

2. **ProPublica Nonprofit Explorer — https://projects.propublica.org/nonprofits/.** Authoritative free source for Form 990 data. The primary tier source for any US nonprofit research.

3. **Federal Information Processing Standards (FIPS) + open-data.gov.** Source for government-org querying patterns. Federal Register + GAO + OIG are publicly-accessible primary sources.

4. **Heydon Pickering, *Inclusive Design Patterns* (2016).** Source for the "degrade gracefully when source fails" pattern. The skill applies progressive enhancement: query best source first, fall back to lower tiers when blocked.

5. **Bruce Schneier, *Beyond Fear* (2003).** Source for the BYOK-MCP audit-log flagging discipline. Provenance matters; users have a right to know which data came from which provider.

6. **OWASP Web Security Testing Guide.** Source for the user-agent + rate-limit etiquette in API calls. SEC EDGAR specifically requires User-Agent header with contact info; respecting these terms prevents access loss.

7. **Charity Navigator + GiveWell methodology pages.** Source for nonprofit-evaluation metrics (overhead ratio, exec comp, independent board %). The skill mirrors their established metric set rather than inventing new criteria.

FILE:scripts/citation_tracker.py
#!/usr/bin/env python3
"""citation_tracker.py — Hypothesis-testing three-count audit + tier tagging.

Stdlib-only. Extended for dossier's hypothesis-testing discipline:

  - searches (sent)
  - sources received (raw count across all queries)
  - sources cited (made it into DOCX)
  - Per query: supporting / disconfirming / inconclusive classification
  - Per cited source: primary / secondary / tertiary tier

Enables the ≥30% disconfirming rule via `disconfirming_evidence_balance.py`.
Enables verdict determination via tier-weighted balance.

Sessions persist at ~/.dossier_sessions/<session>.json.

Usage:
    python citation_tracker.py --action start --session dossier-MS-20260515 --subject "Microsoft" --hypothesis "consolidating AI on Foundry"
    python citation_tracker.py --action record_search --session ... --query "..." --classification supporting
    python citation_tracker.py --action record_search --session ... --query "..." --classification disconfirming
    python citation_tracker.py --action record_received --session ... --count 12
    python citation_tracker.py --action record_cited --session ... --url "https://..." --tier primary --classification supporting
    python citation_tracker.py --action status --session ...
    python citation_tracker.py --action close --session ...
"""

import argparse
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, List, Optional


SESSIONS_DIR = Path.home() / ".dossier_sessions"
VALID_CLASSIFICATIONS = ["supporting", "disconfirming", "inconclusive"]
VALID_TIERS = ["primary", "secondary", "tertiary"]


def session_path(name: str) -> Path:
    return SESSIONS_DIR / f"{name}.json"


def load_session(name: str) -> Dict[str, Any]:
    p = session_path(name)
    if not p.exists():
        raise FileNotFoundError(f"Session not found: {name}")
    return json.loads(p.read_text(encoding="utf-8"))


def save_session(name: str, data: Dict[str, Any]) -> None:
    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
    session_path(name).write_text(json.dumps(data, indent=2), encoding="utf-8")


def now_iso() -> str:
    return datetime.now(timezone.utc).isoformat()


def action_start(name: str, subject: Optional[str], hypothesis: Optional[str], purpose: Optional[str]) -> Dict[str, Any]:
    if session_path(name).exists():
        raise FileExistsError(f"Session already exists: {name}")
    data: Dict[str, Any] = {
        "session": name,
        "subject": subject or "",
        "hypothesis": hypothesis or "",
        "hypothesis_is_implicit_fallback": False,
        "purpose": purpose or "",
        "started_at": now_iso(),
        "ended_at": None,
        "searches": [],
        "received_log": [],
        "cited": [],
        "counts": {
            "searches": 0,
            "supporting_searches": 0,
            "disconfirming_searches": 0,
            "inconclusive_searches": 0,
            "received_total": 0,
            "cited_total": 0,
            "cited_primary": 0,
            "cited_secondary": 0,
            "cited_tertiary": 0,
            "cited_supporting": 0,
            "cited_disconfirming": 0,
            "cited_inconclusive": 0,
        },
        "byok_mcps_used": [],
    }
    save_session(name, data)
    return data


def action_record_search(name: str, query: str, classification: str) -> Dict[str, Any]:
    data = load_session(name)
    if classification not in VALID_CLASSIFICATIONS:
        raise ValueError(f"Invalid classification '{classification}'. Pick from: {VALID_CLASSIFICATIONS}")
    data["searches"].append({"query": query, "classification": classification, "at": now_iso()})
    data["counts"]["searches"] += 1
    data["counts"][f"{classification}_searches"] += 1
    save_session(name, data)
    return data


def action_record_received(name: str, count: int) -> Dict[str, Any]:
    data = load_session(name)
    data["received_log"].append({"count": count, "at": now_iso()})
    data["counts"]["received_total"] += count
    save_session(name, data)
    return data


def action_record_cited(name: str, url: str, tier: str, classification: str, title: Optional[str]) -> Dict[str, Any]:
    data = load_session(name)
    if tier not in VALID_TIERS:
        raise ValueError(f"Invalid tier '{tier}'. Pick from: {VALID_TIERS}")
    if classification not in VALID_CLASSIFICATIONS:
        raise ValueError(f"Invalid classification '{classification}'. Pick from: {VALID_CLASSIFICATIONS}")
    if any(c["url"] == url for c in data["cited"]):
        return data
    data["cited"].append({"url": url, "tier": tier, "classification": classification, "title": title, "at": now_iso()})
    data["counts"]["cited_total"] += 1
    data["counts"][f"cited_{tier}"] += 1
    data["counts"][f"cited_{classification}"] += 1
    save_session(name, data)
    return data


def action_mark_implicit_fallback(name: str) -> Dict[str, Any]:
    data = load_session(name)
    data["hypothesis_is_implicit_fallback"] = True
    save_session(name, data)
    return data


def action_record_byok(name: str, mcp_name: str) -> Dict[str, Any]:
    data = load_session(name)
    if mcp_name not in data["byok_mcps_used"]:
        data["byok_mcps_used"].append(mcp_name)
    save_session(name, data)
    return data


def action_status(name: str) -> Dict[str, Any]:
    return load_session(name)


def action_close(name: str) -> Dict[str, Any]:
    data = load_session(name)
    if data.get("ended_at") is None:
        data["ended_at"] = now_iso()
        save_session(name, data)
    return data


def compute_verdict(data: Dict[str, Any]) -> str:
    """Tier-weighted verdict from cited evidence."""
    c = data["counts"]
    # Tier weights: primary=3, secondary=2, tertiary=1
    # But we only have per-tier totals + per-classification totals (not crossed)
    # Approximate: assume tier distribution is uniform across classifications
    # For exact: would need full per-citation iteration
    support = c["cited_supporting"]
    disconfirm = c["cited_disconfirming"]
    total = support + disconfirm
    if total < 3:
        return "INCONCLUSIVE"
    if support >= 2 * disconfirm:
        return "SUPPORTED"
    if disconfirm > support:
        return "DISPROVEN"
    return "PARTIALLY SUPPORTED"


def disconfirming_ratio(data: Dict[str, Any]) -> float:
    c = data["counts"]
    if c["searches"] == 0:
        return 0.0
    return c["disconfirming_searches"] / c["searches"]


def render_status_human(data: Dict[str, Any]) -> str:
    out: List[str] = []
    out.append(f"Session:           {data['session']}")
    out.append(f"Subject:           {data.get('subject', '(unset)')}")
    out.append(f"Hypothesis:        {data.get('hypothesis', '(unset)')}")
    if data.get("hypothesis_is_implicit_fallback"):
        out.append(f"                   [IMPLICIT FALLBACK — user did not state explicit hypothesis]")
    out.append(f"Purpose:           {data.get('purpose', '(unset)')}")
    out.append(f"BYOK MCPs used:    {', '.join(data.get('byok_mcps_used', [])) or '(none)'}")
    out.append("")
    c = data["counts"]
    out.append("Search counts:")
    out.append(f"  Total searches:        {c['searches']}")
    out.append(f"  Supporting:            {c['supporting_searches']}")
    out.append(f"  Disconfirming:         {c['disconfirming_searches']}")
    out.append(f"  Inconclusive:          {c['inconclusive_searches']}")
    ratio = disconfirming_ratio(data) * 100
    rule_status = "✓ meets ≥30% rule" if ratio >= 30 else "✗ BELOW 30% — confirmation bias risk"
    out.append(f"  Disconfirming ratio:   {ratio:.0f}%  {rule_status}")
    out.append("")
    out.append("Citation counts:")
    out.append(f"  Total received:        {c['received_total']}")
    out.append(f"  Total cited:           {c['cited_total']}")
    out.append(f"  By tier — primary:     {c['cited_primary']}")
    out.append(f"           secondary:   {c['cited_secondary']}")
    out.append(f"           tertiary:    {c['cited_tertiary']}")
    out.append(f"  By classification — supporting:    {c['cited_supporting']}")
    out.append(f"                      disconfirming: {c['cited_disconfirming']}")
    out.append(f"                      inconclusive:  {c['cited_inconclusive']}")
    out.append("")
    out.append(f"Verdict (tier-weighted):  **{compute_verdict(data)}**")
    out.append("")
    out.append("Audit block for DOCX Section 9:")
    out.append(
        f"  Queries sent: {c['searches']} ({c['supporting_searches']} supporting / {c['disconfirming_searches']} disconfirming / {c['inconclusive_searches']} inconclusive). "
        f"Sources received: {c['received_total']}. Sources cited: {c['cited_total']} "
        f"({c['cited_primary']} primary / {c['cited_secondary']} secondary / {c['cited_tertiary']} tertiary). "
        f"Disconfirming ratio: {ratio:.0f}%. Verdict: {compute_verdict(data)}."
    )
    return "\n".join(out)


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument(
        "--action",
        required=True,
        choices=[
            "start", "record_search", "record_received", "record_cited",
            "mark_implicit_fallback", "record_byok",
            "status", "list", "close",
        ],
    )
    parser.add_argument("--session")
    parser.add_argument("--subject")
    parser.add_argument("--hypothesis")
    parser.add_argument("--purpose")
    parser.add_argument("--query")
    parser.add_argument("--classification", choices=VALID_CLASSIFICATIONS)
    parser.add_argument("--count", type=int)
    parser.add_argument("--url")
    parser.add_argument("--tier", choices=VALID_TIERS)
    parser.add_argument("--title")
    parser.add_argument("--mcp", help="(record_byok only) MCP name")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    try:
        if args.action == "start":
            result = action_start(args.session, args.subject, args.hypothesis, args.purpose)
        elif args.action == "record_search":
            result = action_record_search(args.session, args.query, args.classification)
        elif args.action == "record_received":
            result = action_record_received(args.session, args.count)
        elif args.action == "record_cited":
            result = action_record_cited(args.session, args.url, args.tier, args.classification, args.title)
        elif args.action == "mark_implicit_fallback":
            result = action_mark_implicit_fallback(args.session)
        elif args.action == "record_byok":
            result = action_record_byok(args.session, args.mcp)
        elif args.action == "status":
            result = action_status(args.session)
        elif args.action == "close":
            result = action_close(args.session)
        else:
            SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
            result = [
                {"session": p.stem, **{k: v for k, v in json.loads(p.read_text(encoding="utf-8")).items() if k in ("subject", "started_at", "ended_at", "counts")}}
                for p in sorted(SESSIONS_DIR.glob("*.json"))
            ]
    except (FileNotFoundError, FileExistsError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr); return 2

    if args.output == "json":
        print(json.dumps(result, indent=2, default=str))
    else:
        if args.action == "list":
            print(json.dumps(result, indent=2, default=str))
        else:
            print(render_status_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

FILE:scripts/disconfirming_evidence_balance.py
#!/usr/bin/env python3
"""disconfirming_evidence_balance.py — Enforce ≥30% disconfirming search budget.

Stdlib-only. The dossier skill's non-negotiable: ≥30% of Phase 4 searches must
be classified as disconfirming (would refute the hypothesis if results favorable).

Reads from a dossier session JSON (created by `citation_tracker.py`) and:
  - Returns PASS if disconfirming_ratio >= 0.30
  - Returns WARN if 0.20 <= ratio < 0.30 (recoverable; surface to user)
  - Returns FAIL if ratio < 0.20 (confirmation bias; halt + remediate)

Outputs suggested disconfirming queries to add (based on antonym-pivot heuristic
from references/hypothesis_testing_discipline.md).

NO LLM CALLS. Pure ratio math + heuristic suggestions.

Usage:
    python disconfirming_evidence_balance.py --session dossier-MS-20260515
    python disconfirming_evidence_balance.py --session ... --output json
    python disconfirming_evidence_balance.py --sample
"""

import argparse
import json
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional


SESSIONS_DIR = Path.home() / ".dossier_sessions"
MIN_RATIO = 0.30
WARN_RATIO = 0.20


# Antonym-pivot heuristics for constructing disconfirming queries
DISCONFIRMING_PIVOTS = {
    "consolidating": ["diversifying", "splitting", "decentralizing"],
    "growing": ["shrinking", "declining", "stagnating"],
    "winning": ["losing", "failing", "underperforming"],
    "successful": ["failed", "unsuccessful", "struggling"],
    "expanding": ["contracting", "exiting", "retreating from"],
    "strong": ["weak", "missing"],
    "leading": ["trailing", "lagging"],
    "innovating": ["copying", "lagging behind"],
    "investing in": ["divesting", "exiting"],
    "hiring": ["laying off", "departures from"],
}


def suggest_disconfirming_queries(hypothesis: str, supporting_queries: List[str]) -> List[str]:
    """Heuristic: for each supporting term, suggest antonym-pivoted disconfirming."""
    suggestions: List[str] = []
    hyp_lower = hypothesis.lower()
    for pivot, antonyms in DISCONFIRMING_PIVOTS.items():
        if pivot in hyp_lower:
            for antonym in antonyms[:2]:  # first 2 only to avoid noise
                disconfirming = hyp_lower.replace(pivot, antonym)
                suggestions.append(disconfirming)
    if not suggestions:
        # Generic fallback patterns
        suggestions.append(f"counter-evidence to: {hypothesis}")
        suggestions.append(f"critics of {hypothesis}")
        suggestions.append(f"failures contradicting {hypothesis}")
    return suggestions[:5]


def analyze(session_data: Dict[str, Any]) -> Dict[str, Any]:
    c = session_data.get("counts", {})
    total = c.get("searches", 0)
    supporting = c.get("supporting_searches", 0)
    disconfirming = c.get("disconfirming_searches", 0)
    inconclusive = c.get("inconclusive_searches", 0)

    if total == 0:
        return {
            "verdict": "INSUFFICIENT_DATA",
            "ratio": 0.0,
            "total_searches": 0,
            "supporting": 0,
            "disconfirming": 0,
            "inconclusive": 0,
            "rule_floor": MIN_RATIO,
            "message": "No searches recorded yet. Run Phase 4 first.",
            "remediation_needed": False,
        }

    ratio = disconfirming / total
    needed_disconfirming = max(0, int((MIN_RATIO * total) - disconfirming + 0.999))  # ceiling

    if ratio >= MIN_RATIO:
        verdict = "PASS"
        message = f"Disconfirming ratio {ratio:.0%} meets ≥{MIN_RATIO:.0%} floor. Decision-grade balance OK."
        remediation_needed = False
        suggested = []
    elif ratio >= WARN_RATIO:
        verdict = "WARN"
        message = (
            f"Disconfirming ratio {ratio:.0%} is below ≥{MIN_RATIO:.0%} floor "
            f"but above {WARN_RATIO:.0%} threshold. Recoverable — add {needed_disconfirming} "
            f"disconfirming queries to reach floor."
        )
        remediation_needed = True
        suggested = suggest_disconfirming_queries(
            session_data.get("hypothesis", ""),
            [s["query"] for s in session_data.get("searches", []) if s.get("classification") == "supporting"]
        )
    else:
        verdict = "FAIL"
        message = (
            f"Disconfirming ratio {ratio:.0%} below {WARN_RATIO:.0%} — confirmation bias risk is real. "
            f"HALT + add {needed_disconfirming} disconfirming queries before generating DOCX. "
            f"A SUPPORTED verdict at this ratio is not credible."
        )
        remediation_needed = True
        suggested = suggest_disconfirming_queries(
            session_data.get("hypothesis", ""),
            [s["query"] for s in session_data.get("searches", []) if s.get("classification") == "supporting"]
        )

    return {
        "verdict": verdict,
        "ratio": ratio,
        "rule_floor": MIN_RATIO,
        "total_searches": total,
        "supporting": supporting,
        "disconfirming": disconfirming,
        "inconclusive": inconclusive,
        "disconfirming_needed_to_reach_floor": needed_disconfirming,
        "message": message,
        "remediation_needed": remediation_needed,
        "suggested_disconfirming_queries": suggested,
    }


SAMPLE_SESSION = {
    "session": "sample-dossier",
    "subject": "Microsoft",
    "hypothesis": "Microsoft is consolidating AI spend on Foundry platform",
    "counts": {
        "searches": 10,
        "supporting_searches": 8,
        "disconfirming_searches": 2,
        "inconclusive_searches": 0,
    },
    "searches": [
        {"query": "Microsoft Foundry adoption 2026", "classification": "supporting"},
        {"query": "Microsoft AI consolidation strategy", "classification": "supporting"},
    ],
}


def render_human(result: Dict[str, Any]) -> str:
    out: List[str] = []
    out.append(f"Disconfirming evidence balance: {result['verdict']}")
    out.append(f"  Total searches:                  {result['total_searches']}")
    out.append(f"  Supporting:                      {result['supporting']}")
    out.append(f"  Disconfirming:                   {result['disconfirming']}")
    out.append(f"  Inconclusive:                    {result['inconclusive']}")
    out.append(f"  Ratio (disconfirming/total):     {result['ratio']:.0%}")
    out.append(f"  Rule floor:                      {result['rule_floor']:.0%}")
    if result.get('disconfirming_needed_to_reach_floor', 0) > 0:
        out.append(f"  Disconfirming queries to add:    {result['disconfirming_needed_to_reach_floor']}")
    out.append("")
    out.append(result["message"])
    if result.get("suggested_disconfirming_queries"):
        out.append("")
        out.append("Suggested disconfirming queries (antonym-pivot from hypothesis):")
        for q in result["suggested_disconfirming_queries"]:
            out.append(f"  - {q}")
    return "\n".join(out)


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument("--session", help="Session name (in ~/.dossier_sessions/)")
    parser.add_argument("--sample", action="store_true", help="Analyze embedded sample data (10 searches, 80% supporting)")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    if args.sample:
        data = SAMPLE_SESSION
    elif args.session:
        p = SESSIONS_DIR / f"{args.session}.json"
        if not p.exists():
            print(f"error: session not found at {p}", file=sys.stderr); return 2
        try:
            data = json.loads(p.read_text(encoding="utf-8"))
        except json.JSONDecodeError as e:
            print(f"error: invalid session JSON: {e}", file=sys.stderr); return 2
    else:
        parser.print_help(); return 0

    result = analyze(data)
    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(render_human(result))

    if result["verdict"] == "FAIL":
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

FILE:scripts/source_tier_classifier.py
#!/usr/bin/env python3
"""source_tier_classifier.py — URL → primary/secondary/tertiary tier.

Stdlib-only. Classifies a source URL into reliability tier based on domain
heuristics. The dossier skill uses tier on every flag in the DOCX so reviewers
can calibrate confidence.

Tiers:
  - PRIMARY:    Official, regulatory, court records, SEC EDGAR, .gov, company
                official site, academic publications (peer-reviewed)
  - SECONDARY:  Mainstream news (NYT, WSJ, Reuters), trade press, established
                publications (TechCrunch, The Information, Stratechery)
  - TERTIARY:   Blogs, forums, social media, user-generated content (Reddit, HN,
                Glassdoor, Medium, personal blogs)

NO LLM CALLS. Pure domain pattern matching.

Usage:
    python source_tier_classifier.py --url "https://www.sec.gov/cgi-bin/browse-edgar?..."
    python source_tier_classifier.py --url "https://news.ycombinator.com/item?id=..."
    python source_tier_classifier.py --sample
"""

import argparse
import json
import re
import sys
from typing import Any, Dict, List, Optional
from urllib.parse import urlparse


# Pattern-based tier assignment. Most specific patterns first.

PRIMARY_DOMAIN_EXACT = {
    "sec.gov", "data.sec.gov", "www.sec.gov",
    "courtlistener.com", "pacer.gov",
    "uspto.gov", "patents.google.com",  # patents.google.com indexes USPTO data
    "fda.gov", "cdc.gov", "nih.gov", "grants.nih.gov", "reporter.nih.gov",
    "federalregister.gov", "regulations.gov",
    "gao.gov", "oig.gov",
    "irs.gov",
    "sec.org",  # generic .org for SEC alternates
}

PRIMARY_DOMAIN_SUFFIX = [
    ".gov",  # any government domain
    ".mil",  # military
    ".edu",  # academic (caveat: some .edu content is tertiary, but most institutional pages are primary)
]

PRIMARY_DOMAIN_CONTAINS = [
    "projects.propublica.org/nonprofits",  # ProPublica Nonprofit Explorer (free Form 990 access)
]

# Academic publication primary sources
PRIMARY_ACADEMIC = {
    "nature.com", "science.org", "nejm.org", "thelancet.com", "jamanetwork.com",
    "pnas.org", "bmj.com", "cell.com", "plos.org",
    "scholar.google.com",  # indexes peer-reviewed; treat as primary
}

# Mainstream news (secondary)
SECONDARY_NEWS = {
    "nytimes.com", "wsj.com", "ft.com", "reuters.com", "ap.org", "apnews.com",
    "bbc.com", "bbc.co.uk", "theguardian.com", "economist.com",
    "washingtonpost.com", "latimes.com", "bloomberg.com",
    "cnbc.com", "abcnews.go.com", "nbcnews.com", "cbsnews.com",
}

# Trade press / established tech publications (secondary)
SECONDARY_TRADE = {
    "techcrunch.com", "theverge.com", "wired.com", "arstechnica.com",
    "theinformation.com", "stratechery.com",
    "axios.com", "politico.com",
    "forbes.com",  # mixed quality, but generally secondary
    "modernhealthcare.com", "healthcareitnews.com",
    "law360.com", "natlawreview.com",
}

# Trade-press journalism orgs (secondary)
SECONDARY_INVESTIGATIVE = {
    "propublica.org", "icij.org",  # ProPublica investigative reporting (separate from Nonprofit Explorer)
}

# Tertiary indicators
TERTIARY_DOMAIN_EXACT = {
    "reddit.com", "old.reddit.com", "news.ycombinator.com",
    "medium.com", "dev.to", "substack.com",
    "twitter.com", "x.com",
    "linkedin.com",  # public posts; profiles separately primary for the subject
    "glassdoor.com", "indeed.com", "comparably.com",
    "quora.com", "stackoverflow.com",
    "facebook.com", "instagram.com", "tiktok.com",
}

TERTIARY_PATTERN = [
    re.compile(r".*\.medium\.com$"),
    re.compile(r".*\.substack\.com$"),
    re.compile(r".*\.blogspot\.com$"),
    re.compile(r".*\.wordpress\.com$"),
    re.compile(r".*\.tumblr\.com$"),
]

# Company-official site detection (primary IF the dossier subject)
# Generic patterns:
def is_likely_company_official(domain: str, subject_keywords: List[str]) -> bool:
    """If the domain contains the subject's name and isn't a known news/blog, it's likely official."""
    if not subject_keywords:
        return False
    domain_lower = domain.lower()
    for kw in subject_keywords:
        if kw.lower() in domain_lower:
            return True
    return False


def classify(url: str, subject_keywords: Optional[List[str]] = None) -> Dict[str, Any]:
    if not url or not url.strip():
        return {"tier": "unknown", "url": url, "rationale": "Empty URL"}

    try:
        parsed = urlparse(url)
    except Exception as e:
        return {"tier": "unknown", "url": url, "rationale": f"URL parse failed: {e}"}

    domain = parsed.netloc.lower()
    # Strip 'www.' prefix for matching
    if domain.startswith("www."):
        domain_no_www = domain[4:]
    else:
        domain_no_www = domain

    # Strip port if present
    domain = domain.split(":")[0]
    domain_no_www = domain_no_www.split(":")[0]

    # Check exact-match tiers first
    if domain in PRIMARY_DOMAIN_EXACT or domain_no_www in PRIMARY_DOMAIN_EXACT:
        return {"tier": "primary", "url": url, "rationale": f"Domain {domain} is in primary exact-match list (regulatory/court/official)"}

    if domain in PRIMARY_ACADEMIC or domain_no_www in PRIMARY_ACADEMIC:
        return {"tier": "primary", "url": url, "rationale": f"Domain {domain} is a peer-reviewed academic publication"}

    if domain in SECONDARY_NEWS or domain_no_www in SECONDARY_NEWS:
        return {"tier": "secondary", "url": url, "rationale": f"Domain {domain} is a mainstream news outlet"}

    if domain in SECONDARY_TRADE or domain_no_www in SECONDARY_TRADE:
        return {"tier": "secondary", "url": url, "rationale": f"Domain {domain} is established trade press"}

    if domain in SECONDARY_INVESTIGATIVE or domain_no_www in SECONDARY_INVESTIGATIVE:
        return {"tier": "secondary", "url": url, "rationale": f"Domain {domain} is investigative journalism"}

    if domain in TERTIARY_DOMAIN_EXACT or domain_no_www in TERTIARY_DOMAIN_EXACT:
        return {"tier": "tertiary", "url": url, "rationale": f"Domain {domain} is user-generated content (forum/social/review)"}

    # Pattern checks
    for pattern in TERTIARY_PATTERN:
        if pattern.match(domain):
            return {"tier": "tertiary", "url": url, "rationale": f"Domain {domain} matches tertiary pattern (blog hosting platform)"}

    # Suffix checks
    for suffix in PRIMARY_DOMAIN_SUFFIX:
        if domain.endswith(suffix):
            return {"tier": "primary", "url": url, "rationale": f"Domain {domain} has primary-tier suffix '{suffix}'"}

    # Contains checks
    for pattern in PRIMARY_DOMAIN_CONTAINS:
        if pattern in url.lower():
            return {"tier": "primary", "url": url, "rationale": f"URL contains primary-tier pattern '{pattern}'"}

    # Company-official heuristic (if subject keywords provided)
    if subject_keywords and is_likely_company_official(domain, subject_keywords):
        return {"tier": "primary", "url": url, "rationale": f"Domain {domain} appears to be the subject's official site (matches subject keywords)"}

    # Default for unknown: secondary (give benefit of doubt to legitimate-looking news/site)
    # But add a confidence note
    return {
        "tier": "secondary",
        "url": url,
        "rationale": f"Domain {domain} not in known lists; defaulting to secondary. Manual review recommended for high-stakes citations.",
        "confidence": "low",
    }


SAMPLE_URLS = [
    "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000789019",
    "https://www.nytimes.com/2026/05/15/tech/microsoft-ai-strategy.html",
    "https://techcrunch.com/2026/05/01/microsoft-acquires-startup-x/",
    "https://news.ycombinator.com/item?id=123456",
    "https://glassdoor.com/Reviews/Microsoft-Corp-E1651.htm",
    "https://medium.com/@author/microsoft-foundry-deep-dive",
    "https://www.microsoft.com/en-us/about",
    "https://projects.propublica.org/nonprofits/organizations/123456789",
    "https://scholar.google.com/scholar?q=...",
    "https://www.federalregister.gov/documents/2026/05/01/...",
    "https://random-blog-i-just-found.com/microsoft-rumor",
]


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument("--url", help="URL to classify")
    parser.add_argument("--subject", help="Subject keywords (comma-separated) for company-official heuristic")
    parser.add_argument("--sample", action="store_true", help="Classify a batch of sample URLs")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    subject_kws = [s.strip() for s in args.subject.split(",")] if args.subject else None

    if args.sample:
        results = [classify(u, ["microsoft"]) for u in SAMPLE_URLS]
        if args.output == "json":
            print(json.dumps(results, indent=2))
        else:
            for r in results:
                tier = r["tier"].upper()
                marker = {"PRIMARY": "[1°]", "SECONDARY": "[2°]", "TERTIARY": "[3°]"}.get(tier, "[?]")
                print(f"{marker} {tier:<10s} {r['url']}")
                print(f"      {r['rationale']}")
        return 0
    elif args.url:
        result = classify(args.url, subject_kws)
        if args.output == "json":
            print(json.dumps(result, indent=2))
        else:
            print(f"Tier:      {result['tier'].upper()}")
            print(f"URL:       {result['url']}")
            print(f"Rationale: {result['rationale']}")
            if result.get("confidence"):
                print(f"Confidence: {result['confidence']}")
        return 0
    else:
        parser.print_help()
        return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: "general-counsel-advisor"
description: "General Counsel advisory for startups: contract review (MSA, SaaS, NDA, DPA, employment), IP strategy, term sheet decoding, and regulatory landscape mapping. Use when reviewing any contract or term sheet, deciding when to engage outside counsel, defining IP strategy, evaluating regulatory exposure (HIPAA, GDPR, FDA, fintech), or when user mentions general counsel, GC, legal review, contract risk, term sheet, IP assignment, or regulatory exposure. NOT a substitute for licensed counsel — surfaces questions to bring to qualified attorneys."
license: MIT
metadata:
  version: 1.0.0
  author: Alireza Rezvani
  category: c-level
  domain: general-counsel-leadership
  updated: 2026-05-12
  python-tools: contract_risk_scanner.py, term_sheet_analyzer.py
  frameworks: contract-review, ip-strategy, term-sheet-decoding, regulatory-mapping
---

# General Counsel Advisor

Strategic legal frameworks for startup General Counsels and founders without one. Contract risk, IP strategy, term sheet decoding, regulatory landscape.

This is **not legal advice**. It surfaces the right questions to bring to qualified outside counsel and catches the obvious traps before they reach a signature. Treat every output as a starting point for a conversation with a licensed attorney, not as a substitute for one.

## Keywords

general counsel, GC, legal review, contract review, MSA, SaaS agreement, NDA, DPA, employment agreement, contractor agreement, IP assignment, invention assignment, open source license, OSS compliance, term sheet, liquidation preference, anti-dilution, option pool, vesting, acceleration, drag-along, pro-rata, board composition, regulatory, HIPAA, GDPR, CCPA, FDA, MDR, fintech, BSA/AML, money transmitter, AI Act, indemnity, liability cap, force majeure, auto-renewal, choice of law, venue, non-compete, non-solicit

## Quick Start

```bash
# Scan a contract for risky clauses (uses bundled sample if no path given)
python scripts/contract_risk_scanner.py
python scripts/contract_risk_scanner.py path/to/contract.txt

# Analyze a term sheet for founder-friendliness
python scripts/term_sheet_analyzer.py
python scripts/term_sheet_analyzer.py path/to/term_sheet.json
```

## Key Questions (ask these first)

- **Who owns the IP being created or shared?** (Founders forget that contractors don't auto-assign IP without a written clause.)
- **What's the liability cap, and what's carved out?** (Standard: 12 months of fees, with carve-outs for IP infringement, data breach, willful misconduct.)
- **Is there a DPA in place if any personal data flows?** (GDPR, CCPA, state laws — non-negotiable if EU/CA data is touched.)
- **What's the termination right, notice period, and auto-renewal trap?** (5-year auto-renew with 60-day notice is a common founder mistake.)
- **Does this contract or product launch trigger a new regulatory regime?** (Healthcare → HIPAA. Fintech → BSA/AML. Medical device → FDA/MDR.)
- **For term sheets: liquidation preference, pre-money option pool, anti-dilution flavor?** (Three places where 5% of founder economics can quietly disappear.)

## Core Responsibilities

### 1. Contract Review

Standard contracts a startup signs in its first 5 years:

- **Vendor MSA** — Master Service Agreement (cloud, tooling, services)
- **Customer SaaS Agreement** — your standard customer paper + customer redlines
- **NDA** — mutual + one-way, with carve-outs for residuals + independent development
- **DPA** — Data Processing Agreement (required when personal data flows)
- **Employment Agreement** — offer letter, IP assignment, non-compete (where enforceable), arbitration
- **Contractor / 1099 Agreement** — IP assignment is critical; misclassification risk
- **Equity Agreements** — option grants, RSU agreements, advisor grants (FAST template, YC SAFE for advisors)

**Run** `contract_risk_scanner.py` on the text. It flags the 12 most common founder-killer clauses.

### 2. IP Strategy

- **Invention assignment** — every employee and contractor signs one. No exceptions.
- **Open source license compliance** — track every OSS dependency's license; AGPL and GPL trigger copyleft obligations.
- **Trade secrets** — define what's protected and how (clean room dev, access controls, NDAs).
- **Patents** — file provisional within 12 months of disclosure; PCT for international.
- **Trademarks** — register the word mark first, design mark second; clear before launch.
- **Copyright** — automatic on creation, but register for statutory damages eligibility.

See `references/ip_and_regulatory.md`.

### 3. Term Sheet Decoding

When a term sheet arrives, the difference between a founder-friendly and founder-hostile sheet often hides in three clauses:

- **Liquidation preference** — 1x non-participating is standard; 1x participating or 2x is hostile
- **Pre-money vs post-money option pool** — pre-money pool dilutes founders; post-money dilutes everyone proportionally
- **Anti-dilution** — broad-based weighted average is standard; full ratchet is hostile

**Run** `term_sheet_analyzer.py` to get a 0-100 founder-friendliness score with flags.

### 4. Regulatory Landscape

When to engage outside counsel **before** committing:

| Trigger | Regime | First Step |
|---|---|---|
| Healthcare data | HIPAA, HITECH, state breach laws | Specialist health-tech counsel |
| Cardholder data | PCI DSS (industry standard, not law, but contractually required) | QSA + counsel |
| Money movement | BSA/AML, state money-transmitter (50-state patchwork) | Fintech specialist |
| Medical device claims | FDA 510(k) / De Novo / PMA, MDR (EU), ISO 13485 | Medical-device specialist |
| EU residents' personal data | GDPR + EU AI Act if AI is deployed | EU privacy counsel |
| California residents | CCPA / CPRA | Privacy generalist |
| Securities (tokens, equity crowdfunding) | SEC rules (Reg D, Reg A+, Reg CF) | Securities counsel |
| Defense / aerospace customers | ITAR, EAR, DFARS, CMMC | Export-control counsel |
| AI in EU | EU AI Act (risk-tiered) | EU privacy + product counsel |
| AI for hiring (NYC, CO, IL) | Local bias-audit laws | Employment counsel |

See `references/ip_and_regulatory.md` for sequencing.

## Workflows

### Workflow 1: Contract Review
1. Save the contract as plain text
2. Run `contract_risk_scanner.py path/to/contract.txt`
3. For each HIGH risk finding, draft a counter-proposal
4. Bring the redline + counter-proposals to outside counsel
5. Log the decision via `/cs:decide`

### Workflow 2: Term Sheet Response
1. Save the term sheet as a JSON file matching the schema in `term_sheet_analyzer.py --help`
2. Run `python scripts/term_sheet_analyzer.py path/to/term_sheet.json`
3. Review the founder-friendliness score and per-clause flags
4. Negotiate the worst 3 clauses (don't try to win all 20)
5. Always have a securities/venture attorney review before signing
6. Log via `/cs:decide` with `/cs:freeze 30` to prevent regret-driven re-opening

### Workflow 3: IP Hygiene Audit
1. Confirm every employee and contractor (past 12 months) signed invention assignment
2. Run an OSS license inventory (`pip-licenses`, `license-checker` for npm)
3. Map AGPL/GPL dependencies and confirm compliance (or remove)
4. File provisional patents on novel inventions (12-month deadline from disclosure)
5. Register word-mark trademarks for the product name

### Workflow 4: Regulatory Trigger Assessment
1. List planned product features for the next 12 months
2. Map each feature to the trigger table in this document
3. For any HIPAA / FDA / fintech trigger, engage a specialist counsel **before** building
4. Document the regulatory roadmap and budget alongside the product roadmap
5. Pair with `cs-ciso-advisor` for ISO 27001 / SOC 2 sequencing

## Output Standard (when invoked via `/cs:gc-review`)

```
**Bottom Line:** [sign / negotiate / do not sign]
**The Risks:** [3 highest-severity issues]
**Counter-Proposals:** [specific language]
**Outside Counsel Action Items:** [what to bring to the attorney]
**Your Decision:** [the call only the founder can make]
```

## Adjacent Skills

- `../ciso-advisor/` — Compliance overlap (SOC 2, ISO 27001, HIPAA technical safeguards)
- `../cfo-advisor/` — Term sheet → dilution math
- `../ma-playbook/` — Acquisition agreements, integration playbooks
- `../../../ra-qm-team/` — ISO 13485, MDR, FDA 510(k), GDPR execution
- `../../c-level-agents/skills/gc-review/SKILL.md` — `/cs:gc-review` slash command

## References

- [contracts_playbook.md](references/contracts_playbook.md) — Standard contracts, clause checklist, common founder traps
- [ip_and_regulatory.md](references/ip_and_regulatory.md) — IP protection + regulatory landscape mapping
- [term_sheet_decoder.md](references/term_sheet_decoder.md) — Term sheet glossary + founder-friendly defaults + pushback strategies

---

**Version:** 1.0.0
**Status:** Production Ready
**Disclaimer:** Not legal advice. Always engage qualified counsel for binding decisions.

FILE:references/contracts_playbook.md
# Contracts Playbook — Standard Startup Agreements

Reference for the 7 contracts every startup signs in its first 5 years and the clause traps to avoid in each. **Not legal advice.** Bring redlines to qualified counsel.

## 1. Master Service Agreement (MSA) — Vendor Side (you signing theirs)

**What it is:** The umbrella contract for an ongoing relationship with a vendor (cloud, tooling, services, agencies). Usually paired with one or more SOWs / Order Forms.

**Top 5 redlines to push:**

1. **Auto-renewal:** Cut notice period to 30 days max. Reject 60/90/180 day notice.
2. **Liability cap:** Insist on 12 months of fees. Reject "fees in the preceding 3 months" (too narrow).
3. **Mutual indemnification:** Reject one-sided. Mirror the scope on both sides.
4. **IP ownership of deliverables:** All work product belongs to you. Vendor retains rights to pre-existing tools / methodologies, granted back to you for use.
5. **Data: DPA + return-or-destroy on termination.** Specifically: vendor cannot use your data to train AI models.

**Bonus catch:** Watch for "Vendor may modify these terms upon notice" — this means the contract you signed isn't the contract you have.

## 2. Customer SaaS Agreement (your paper)

**Standard structure:**

1. License grant (subscription, scope, term)
2. Acceptable use policy (what customer can/can't do)
3. Fees & payment (annual prepay vs. monthly, late fee, currency)
4. Service Level Agreement (uptime %, credits, exclusions)
5. Confidentiality (mutual, residuals carve-out)
6. Data Protection (DPA exhibit, subprocessor list, security commitments)
7. Warranties (limited, disclaim implied)
8. Indemnification (mutual, IP-infringement focused)
9. Limitation of liability (12 months fees, carve-outs for IP/data breach/willful)
10. Term & termination (term, termination for cause, termination for convenience)

**Founder traps when accepting customer redlines:**

- "Most-favored-nation" pricing (means you can never give anyone else a better deal).
- Uncapped liability for data breach with no minimum threshold.
- Customer right to perpetual license-back of "improvements" to your product.
- Customer "ownership" of any custom configuration (often hiding IP creep).
- Source-code escrow with auto-release triggers tied to customer convenience.

## 3. Non-Disclosure Agreement (NDA)

**One-way (you receiving):** Acceptable to sign without redlines for short evaluations.

**Mutual NDA (both directions):** The default for ongoing discussions.

**Critical carve-outs (always include):**

- **Residuals:** Information retained in unaided memory after end of engagement is not confidential.
- **Independent development:** If you build something similar without using their info, it's yours.
- **Public domain:** Information already public is not confidential.
- **Rightfully received:** Information received from a third party without confidentiality obligation.
- **Required by law:** Information disclosed under subpoena (with notice).

**Founder trap:** NDAs that prevent you from "engaging in similar business" — that's a non-compete in disguise. Strip it out.

## 4. Data Processing Agreement (DPA)

**Required when:** Personal data of EU residents flows (GDPR Article 28), or California residents (CCPA / CPRA), or HIPAA-covered data, or biometrics in IL/TX/WA (BIPA).

**Standard structure (GDPR-aligned):**

- Scope of processing (what data, what purpose)
- Controller / Processor designation
- Subprocessor list + flow-down obligations
- Data subject rights (access, deletion, portability)
- Security measures (encryption, access controls, training)
- Breach notification timelines (within 72 hours for GDPR)
- Audit rights (annual, reasonable)
- International transfer mechanism (SCCs, adequacy decision, BCRs)
- Return-or-destroy on termination

**Templates:** Use IAPP, EU Commission SCCs, or vendor-friendly DPA (e.g., Vanta's, Stripe's).

**Founder trap:** Missing DPA when EU/CA data flows = contract may be unenforceable AND regulatory fine exposure.

## 5. Employment Agreement / Offer Letter

**Must-have provisions:**

- **At-will employment** (US most states; not enforceable in MT for example)
- **Compensation:** salary, bonus structure, equity (option grant separately documented)
- **Invention assignment:** all IP created during employment using company resources belongs to company
- **Confidentiality:** ongoing duty, surviving termination
- **Non-solicit:** 12 months post-termination, employees + customers (carve out general advertising)
- **Non-compete:** state-dependent (CA, ND, OK, DC: void; many other states: enforceable if reasonable)
- **Arbitration:** mutual, AAA or JAMS rules, employer pays fees

**Founder traps:**

- Forgetting to require employees to sign **before** starting work (otherwise IP assignment is weak).
- Not including a "previously created inventions" exhibit (lets founders document pre-existing IP brought into the company).
- Skipping background checks for senior hires.

## 6. Contractor / 1099 Agreement

**Critical differences from employment:**

- **IP assignment is NOT automatic.** Without a written clause, the contractor owns what they create (under US law, "work for hire" applies only to specific categories of work).
- **Misclassification risk:** If a contractor functions like an employee (controlled hours, exclusive engagement, supplied equipment), tax authorities can reclassify, triggering back taxes + penalties.
- **No benefits, no withholding, contractor handles their own taxes.**

**Must-have provisions:**

- **Explicit work-for-hire OR written IP assignment** ("Contractor hereby assigns all right, title, and interest...").
- **Independent contractor status:** contractor controls means and methods.
- **Termination:** 30-day notice, immediate for cause.
- **Indemnification:** contractor indemnifies you for misclassification claims if they misrepresent status.

**Tooling:** Use Deel, Remote, or Velocity Global for international contractors to handle classification correctly.

## 7. Equity Agreements (Option Grants, Advisor Grants)

**Employee option grant:**

- **Strike price:** must be ≥ fair market value (FMV) at grant date (409A valuation, refreshed annually).
- **Vesting:** standard 4 years, 1 year cliff, monthly thereafter.
- **Exercise window post-termination:** 90 days standard; 7-10 years is founder-friendly.
- **ISO vs NSO:** ISOs have tax advantages (long-term capital gains if held) but limits ($100K vest/year) and US-citizen-only.

**Advisor grant (FAST template by Founder Institute):**

- 0.1% - 1% equity vested over 1-2 years, depending on level and stage.
- 2-year vesting, no cliff (advisors are tested through engagement, not retention).
- Single trigger acceleration on change of control (rare; double trigger more common).

**Founder trap:**

- Issuing options before completing the 409A valuation — strike price might be challenged by IRS.
- Verbal promises about acceleration — must be in writing.
- Forgetting to issue option grants to early employees within 90 days of hire (loses ISO eligibility).

## Quick Triage Heuristics

When you have 5 minutes to look at a contract:

1. **Find the liability cap.** No cap or > 24 months of fees = red flag.
2. **Find the indemnity clauses.** One-sided = red flag.
3. **Find the IP clause.** Vague or "as agreed" = red flag.
4. **Find the term + termination.** Auto-renewal with > 30 day notice = red flag.
5. **Find the choice of law/venue.** Exclusive in counterparty home jurisdiction = red flag.

Run `scripts/contract_risk_scanner.py` for the automated version.

---

**Final reminder:** This is a triage playbook. Every contract over $100K or longer than 1 year deserves outside counsel review. Every contract that touches personal data deserves a privacy attorney. Every term sheet deserves a securities / venture attorney. Period.

FILE:references/ip_and_regulatory.md
# IP Strategy & Regulatory Landscape

The two areas where startups most often discover legal exposure after it's too late to fix cheaply: IP ownership and regulatory triggers. **Not legal advice.**

## Part 1: IP Strategy

### IP Inventory — The Four Categories

| Type | What it protects | How you get it | How you lose it |
|---|---|---|---|
| **Patents** | Inventions (novel, non-obvious, useful) | File application | Public disclosure > 12 months before filing |
| **Copyright** | Original works of authorship (code, content, designs) | Automatic on fixation | Almost never; can be assigned away |
| **Trademark** | Brand identifiers (names, logos, slogans) | Use in commerce + registration | Not policing infringement; becoming generic |
| **Trade secret** | Confidential business information | Reasonable measures to keep secret | Public disclosure; failure to maintain confidentiality |

### Invention Assignment — The Single Most Important IP Practice

**Rule:** Every person who touches the company's product or systems must sign an invention assignment agreement **before** they start work.

This includes:
- Co-founders (often forgotten — usually fixed via founder restricted-stock purchase agreements)
- Employees (in employment agreement)
- Contractors (in contractor agreement; NOT automatic in US law)
- Interns (often forgotten — use a short standalone IP agreement)
- Advisors (in advisor agreement, scope limited to inventions related to company)

**Why it matters:** Without written assignment, the creator retains ownership. A contractor who built a critical service for 6 months and never signed an assignment can come back years later and demand a license — or assert that competitors can also use what they built.

**The "previously created inventions" exhibit:** Every IP assignment should include an exhibit where the signer lists pre-existing inventions they want to exclude. This protects everyone — the signer's prior work isn't accidentally assigned, and the company has documentation of what came in.

### Open Source License Compliance

**Permissive licenses** (MIT, Apache 2.0, BSD 2/3): Use freely, attribute, no copyleft.

**Weak copyleft** (LGPL, MPL): Can use in proprietary product; modifications to the OSS itself must be released. Distribution model matters.

**Strong copyleft** (GPL v2, GPL v3, AGPL): Distribution / SaaS use of a strong-copyleft component can require releasing your derivative work under the same license. **AGPL is the most aggressive** — it applies even when you only run the software on a server (SaaS / network use).

**Practice:**

1. Maintain an OSS inventory: `pip-licenses`, `license-checker` (npm), `cargo-license`, `go-licenses`.
2. Identify any GPL / AGPL / SSPL dependencies.
3. For each: either (a) comply with the license, (b) replace with a permissively-licensed alternative, or (c) document the carve-out (some companies build internally with GPL but only ship the binary externally — verify with counsel).
4. Run the inventory before any due diligence (acquisition, financing).

### Patents — When to File

**File when:**

- You have a genuinely novel technical invention (algorithm, hardware design, materials, biotech process).
- You face well-funded competitors who could copy without consequence.
- You're in a patent-dense industry (semiconductors, pharma, networking, medical devices).
- Filing strengthens fundraising / acquisition optics (limited weight for software-only startups).

**Don't bother when:**

- Your "invention" is a UX flow or business method (these are extremely hard to patent post-Alice Corp).
- You're in early stage with limited capital and no competitors close enough to copy.
- Defensive only and joining a patent pool (LOT Network, OIN) might be cheaper.

**Process:**

1. **Provisional patent** ($300-500 USPTO fee + $3K-5K attorney). 12 months to file non-provisional.
2. **Non-provisional / utility patent** ($1K USPTO fee + $10K-15K attorney + prosecution costs).
3. **PCT application** for international filings ($5K-10K).
4. **National phase entries** in each country you care about ($5K-15K per country).

Budget $25K-50K total for one well-prosecuted patent family with international coverage.

### Trade Secrets

**Reasonable measures required for legal protection:**

- NDA / confidentiality clauses with everyone who has access.
- Access controls (need-to-know basis, not company-wide).
- Marking documents "Confidential."
- Departure procedures (return of materials, exit interview, deactivation).
- Training employees on what's a trade secret.

**Without these measures, the information may not qualify for trade secret protection if disclosed — even by a thief.**

**Common trade secrets:**

- Customer lists with usage / pricing data
- Algorithms not disclosed in published patents
- Manufacturing processes
- Sales playbooks and pricing models
- Internal financial projections
- Source code (unless OSS)

### Trademark Strategy

**Search before launch:**

- USPTO TESS search (free, but limited; doesn't catch common-law marks).
- Professional search via attorney ($500-2K) catches common-law marks and similar-mark conflicts.
- International searches via WIPO Global Brand Database.

**Register early:**

- US: Intent-to-use application (1B) lets you reserve a mark before launch.
- International: Madrid Protocol filing extends to 100+ countries.
- Word marks first (the brand name itself), design marks second (logos).

**Policing:**

- Set up Google Alerts and USPTO TMNG for your mark.
- Send cease-and-desist letters promptly; failure to police can weaken the mark.

---

## Part 2: Regulatory Landscape — When to Engage Counsel

The startups that survive their first regulatory encounter engage specialist counsel **before** building, not after. The ones that don't usually pivot, retreat, or pay heavy fines.

### Trigger Matrix

| Trigger | Regulatory Regime | Specialist Needed | Earliest Action |
|---|---|---|---|
| Healthcare data (patient records, claims, PHI) | HIPAA, HITECH, state breach laws | Health-tech attorney | Business Associate Agreement, OCR-aligned risk assessment |
| Cardholder data | PCI DSS (industry standard; contractually required) | QSA + counsel | Scope reduction, tokenization, certified processor |
| Money movement (transmitting funds, custody, crypto) | BSA/AML, state money-transmitter (50-state patchwork) | Fintech attorney | Stripe Treasury / Banking as a Service to avoid MT registration |
| Lending | Truth in Lending Act, state usury laws, ECOA | Fintech / consumer-finance attorney | Bank partnership, state licensing analysis |
| Medical device claims | FDA 510(k), De Novo, PMA; EU MDR; ISO 13485 | Medical-device regulatory specialist | Pre-submission meeting with FDA |
| EU residents' personal data | GDPR + ePrivacy + EU AI Act if AI | EU privacy attorney | DPA, SCCs for international transfer, DPIA |
| California residents | CCPA / CPRA | Privacy generalist | Privacy notice, opt-out mechanisms, vendor management |
| Children's data (under 13 US, under 16 in some EU states) | COPPA, GDPR-K | Privacy attorney | Parental consent, no-track defaults |
| Securities (tokens, equity crowdfunding, advisory boards) | SEC rules (Reg D, Reg A+, Reg CF, Howey test) | Securities attorney | Token sale legal opinion, Form D filing |
| Defense / aerospace customers | ITAR, EAR, DFARS, CMMC | Export-control attorney | Export classification, registered with State Dept |
| AI in EU | EU AI Act (risk-tiered: prohibited / high-risk / limited / minimal) | EU privacy + product attorney | Risk assessment, conformity assessment for high-risk |
| AI for hiring | NYC Local Law 144, CO SB 21-169, IL HB 53 | Employment attorney | Bias audit, candidate notice |
| Telehealth / online prescribing | State medical board rules, DEA registration for controlled substances | Telehealth specialist | State-by-state physician licensing strategy |
| Insurance (sale, underwriting, brokerage) | State insurance commissioners | Insurance attorney | State licensing, agency agreement |

### Sequencing: SOC 2 → ISO 27001 → Industry-Specific

For most B2B SaaS, the security/compliance sequence is:

1. **SOC 2 Type 1** (point-in-time audit) — ~$15K-25K, 3-6 months prep
2. **SOC 2 Type 2** (continuous, ~6-12 month audit window) — ~$25K-50K
3. **ISO 27001** if expanding internationally — ~$30K-60K, builds on SOC 2 controls
4. **ISO 42001** if AI is core to product — first AI management system standard
5. **Industry overlays:** HIPAA technical safeguards, FedRAMP (federal customers), PCI DSS (cardholder data)

**Sequencing logic:** SOC 2 unlocks the majority of enterprise sales. ISO 27001 unlocks European and Asia-Pacific. Industry overlays are required for specific verticals.

### When to Get a General Counsel Hire

| Stage | GC need |
|---|---|
| Pre-seed / seed | None. Use outside counsel ad-hoc + Clerky/Stripe Atlas templates |
| Series A | Fractional GC (~$10-20K/month) OR senior associate at firm |
| Series B | Full-time GC if regulated industry, customer contracts are heavy, or fundraising is constant |
| Series C+ | Full-time GC + Deputy/Associate GC if international |

**Signs you need a GC hire:**

- You're spending > $200K/year on outside counsel
- You're signing > 1 enterprise contract per week with customer redlines
- You're in a regulated industry (healthcare, fintech, defense)
- You're preparing for IPO or going-public transaction
- You're acquiring companies

### Cross-Border Considerations

**Hiring international employees:**

- Use Deel / Remote / Velocity Global for first 1-5 contractors per country.
- Establish an entity (subsidiary or EOR-to-entity transition) at 5-10+ employees.
- Tax residency, permanent establishment risk, and equity grants vary significantly.

**International data flows:**

- EU → US: SCCs + Transfer Impact Assessment (TIA); DPF if certified.
- China → outbound: PIPL approval + standard contract + security assessment.
- UK → outside: UK SCCs (similar to EU).
- Schrems / DPF status changes regularly — monitor with privacy counsel.

**International IP:**

- Patent: PCT application within 12 months of first national filing.
- Trademark: Madrid Protocol for multi-country filings.
- Copyright: Berne Convention covers most countries automatically.

---

## Closing: The General Counsel's Three Rules

1. **Get it in writing.** Verbal agreements and "we'll figure it out later" produce 80% of post-engagement disputes.
2. **Identify the regulatory trigger before you build.** It's 10x cheaper to design around a regulation than to retrofit.
3. **Always have outside counsel review anything binding.** This document is triage; real legal review is mandatory.

FILE:references/term_sheet_decoder.md
# Term Sheet Decoder

Glossary + founder-friendly defaults + pushback strategies for every clause in a standard venture term sheet. **Not legal advice.** Always engage venture / securities counsel before responding.

## The Three Clauses That Matter Most

In any term sheet review, focus disproportionately on these three. They drive ~80% of the founder economics impact.

### 1. Liquidation Preference

**What it is:** Investors get their investment back (the "preference") before founders see anything in an exit.

**The dimensions:**

- **Multiple:** 1x (standard) means $1 back per $1 invested. 2x means $2 back. Higher = more hostile.
- **Participating vs Non-participating:**
  - **Non-participating (founder-friendly):** Investor chooses preference OR convert to common at exit. Most exits hit the conversion threshold, so preference is effectively just downside protection.
  - **Participating ("double-dip"):** Investor gets preference back AND a pro-rata share of remaining proceeds as if converted. Significantly increases investor take in mid-range exits.
- **Cap:** Caps the total return at, say, 2x or 3x of investment for participating preferences. Limits the double-dip.

**Standard (Series A/B):** 1x non-participating.

**Hostile flavors:**
- 1x participating uncapped (significant founder dilution at exit)
- 2x preference (only acceptable in distressed rounds)
- Multi-stack preferences (Series A + Series B both get their preferences before any common)

**Pushback:** "Our standard is 1x non-participating. Participating preferences create misalignment with management at exit."

### 2. Option Pool — Pre-Money vs Post-Money

**The "option pool shuffle":** Investors typically require an unallocated option pool (10-20% of post-money) to be created **before** the new investment. If this comes out of pre-money, founders are diluted; if post-money, all shareholders dilute proportionally.

**Example math (Series A):**

| Scenario | Pre-Money | Pool Size | Effective Pre-Money for Founders |
|---|---|---|---|
| $30M pre, 10% pool pre-money | $30M | 10% of post | ~$26M (10% comes from founders) |
| $30M pre, 10% pool post-money | $30M | 10% of post | $30M (pool spread across all) |

**Standard:** 10-15% pool, often pre-money at Series A. Founder-friendly: smaller pool or post-money.

**Pushback:** "We've modeled our hiring plan and 8% supports the next 18 months. Let's right-size to actual need, not standard percentage." Or: "Pool top-up should come out of post-money so the new investor shares the dilution."

### 3. Anti-Dilution

**What it is:** Protection for investors against future down rounds. If a later round prices below the current, the current investor's price is adjusted retroactively.

**Flavors (least to most hostile):**

- **None:** Rare; only in seed SAFEs sometimes.
- **Broad-based weighted average (standard):** Adjusts using all shares (common, options, warrants). Modest founder dilution in a down round.
- **Narrow-based weighted average:** Uses only preferred. More dilutive than broad-based.
- **Full ratchet (hostile):** Investor's price resets entirely to the new round's price. Massively dilutive to founders.

**Standard:** Broad-based weighted average.

**Pushback:** "Full ratchet is non-starter at this stage. Narrow-based is unusual. We need broad-based weighted average — this is the NVCA standard."

---

## The Full Glossary

### Board Composition

**Standard at Series A:** 2 founders / 1 investor / 1 independent (or 1 founder / 1 investor / 1 independent for solo founders).

**At Series B:** Often 2 / 2 / 1 (balanced with independent tie-breaker).

**At Series C+:** Often investors get majority (signals control transition).

**Founder protection:** Always insist on the independent seat. Independent directors prevent deadlock and provide a neutral voice.

**Pushback on investor-majority boards at A:** "Investor control of the board at Series A is premature. Let's keep founder control with an independent tie-breaker until Series B."

### Vesting (for founders)

**Founder vesting in a financing:** Investors often require founder shares to be subject to vesting (re-vesting if you already exercised). Standard: 4 years, 1-year cliff. Often the cliff is waived if you've been at the company > 1 year.

**Acceleration:**

- **Single trigger:** All unvested shares vest immediately upon change of control. Founder-friendly but rare; investors resist.
- **Double trigger (standard):** Acceleration requires (a) change of control AND (b) involuntary termination of the founder within X months. Industry standard at Series A+.

**Pushback:** "Double-trigger acceleration is industry standard. Without it, founders are exposed to acquirer post-acquisition staffing decisions."

### Pro-Rata Rights

**What it is:** The right (but not obligation) to participate in future rounds proportionally to maintain ownership.

**Standard:** Lead investor + major investors (typically those above some ownership threshold) get pro-rata. Smaller checks often don't.

**Founder impact:** Granting pro-rata is generally fine — it shows investor conviction and aligns long-term. The cost is small dilution in future rounds.

**Pushback:** Only push back if there's a long tail of small investors each demanding pro-rata; cap to "major investors" defined by ownership %.

### Drag-Along

**What it is:** If a majority approves a sale, all shareholders must agree (including minority holders, including founders who later become minority).

**Founder-friendly version:** Drag-along requires founder consent OR a minimum sale price threshold (e.g., > 3x liquidation preference).

**Hostile version:** Drag-along with no founder consent and no price floor. Investors can force a sale at any price over founder objection.

**Pushback:** "Drag-along is standard, but we need founder consent OR a price floor."

### Protective Provisions

**What it is:** Investor consent rights for certain corporate decisions.

**Standard (NVCA model):**

- Issuing new senior or pari-passu preferred stock
- Authorizing new shares above existing pool
- Liquidating, merging, or selling the company
- Amending the charter or bylaws
- Increasing the board size
- Paying dividends
- Major debt

**Aggressive (push back):**

- Approving the annual budget
- Hiring or firing executives
- Setting compensation above thresholds
- Approving individual contracts above thresholds
- Capital expenditures above thresholds

**Pushback:** "We're aligned on the NVCA standard list. Operating decisions like budget and hiring are management's responsibility — protective provisions are for fundamental corporate changes."

### Information Rights

**Standard:** Quarterly unaudited financials, annual audited financials, annual budget.

**Aggressive (push back):** Monthly financials, board observer rights, weekly KPI dashboards, inspection rights at will.

**Pushback:** "Standard quarterly + annual is enough. Monthly creates significant CFO overhead at our stage. We'll commit to ad-hoc updates on material events."

### Dividends

**Standard:** None (default).

**Acceptable:** Non-cumulative dividends "when and if declared by the board" — almost never paid in practice.

**Hostile:** Cumulative dividends accrue every year regardless of declaration and must be paid in cash at exit. This is a creeping liquidation preference.

**Pushback:** "Cumulative dividends create a hidden liquidation preference that accrues over time. Non-cumulative when-declared, or none, is standard."

### Right of First Refusal (ROFR) / Co-Sale

**What it is:** If founders try to sell shares to a third party, investors have the right to buy first (ROFR) or to sell alongside (co-sale).

**Founder-friendly:** Standard ROFR + co-sale for all preferred; founders can still do secondary up to small thresholds without triggering.

**Hostile:** No secondary at all without unanimous investor consent.

**Pushback:** "We need to allow modest founder secondary (e.g., up to $1M aggregate) without investor consent — this is needed for founder financial planning."

### Founder Liquidity

**What it is:** Built-in secondary at later rounds (Series B/C) where founders sell some shares.

**Standard:** Becoming more common; 10-20% of round size as founder secondary.

**Pushback:** Raise this in Series B+ discussions; not typically negotiated at Series A.

### Most Favored Nation (MFN)

**What it is:** If you give a later investor better terms, the MFN-holder gets the same terms retroactively.

**Common in:** Seed SAFEs and convertible notes; rare in priced rounds.

**Founder trap:** MFN provisions can prevent you from offering competitive terms to new lead investors later. Be specific about what's covered (just SAFE terms? all terms?).

### No-Shop / Exclusivity

**What it is:** During due diligence, you can't shop the round to other investors.

**Standard:** 30-45 days. Founder-friendly. Investor-aligned because it shows commitment.

**Pushback only if:** > 60 days, or if it extends post-execution of definitive docs.

---

## Founder-Friendly Defaults (Cheat Sheet)

| Clause | Founder-Friendly Default |
|---|---|
| Liquidation preference | 1x non-participating |
| Anti-dilution | Broad-based weighted average |
| Option pool | 8-12%, post-money |
| Board (Series A) | 2F / 1I / 1Indep |
| Vesting (founder re-vest) | 4yr / 1yr cliff, often with credit for time served |
| Acceleration | Double-trigger |
| Pro-rata | For lead + major investors |
| Drag-along | Requires founder consent or price floor |
| Protective provisions | NVCA standard list only |
| Information rights | Quarterly + annual + budget |
| Dividends | None or non-cumulative when-declared |
| ROFR / co-sale | Standard, with carve-out for modest founder secondary |
| MFN (in notes/SAFEs) | Avoid if possible; if not, narrow scope |
| No-shop | 30-45 days |

---

## Negotiation Strategy

**Pick your battles:** A term sheet has 25-40 clauses. Winning every one is impossible and signals you don't understand priorities.

**Focus on the top 3 mistakes (in order):**

1. Liquidation preference flavor (participating vs non-participating)
2. Option pool pre-money vs post-money + size
3. Board control and protective provisions

These are the clauses where you can save 5-10% of founder economics or retain operating control. Everything else is secondary.

**The "founder-friendly NVCA" framing:** Many investors signal their posture by deviating from the NVCA model (the industry standard documents published by the National Venture Capital Association). Pushing back to "let's use the NVCA standard" is rarely rejected and resolves most issues.

**Walking away:** If a lead insists on:
- 1x participating uncapped preference
- Full ratchet anti-dilution
- Investor-majority board at Series A
- Cumulative dividends

These are not standard. A founder-friendly lead doesn't insist on these. Either walk or get specific written justification (sometimes a distressed cap-table situation justifies one of them, but never all).

---

## After Signing

Once the term sheet is signed:

1. **No-shop is active.** Don't talk to other investors except to officially decline.
2. **Definitive documents (SPA, IRA, Voting Agreement, ROFR Agreement) take 4-6 weeks.** Don't lose energy here; main fight was the term sheet.
3. **Closing conditions:** legal opinion, secretary's certificate, charter filing, capitalization confirmation.
4. **Wire timing:** Investors often wire 1-3 days after charter filing. Plan accordingly.

Run `scripts/term_sheet_analyzer.py` on the structured JSON of the term sheet for an automated scoring + flag analysis.

---

**Final reminder:** This document is a decoder, not a negotiation manual. Real term sheet response always involves your venture / securities counsel + your lead investor's diligence + your board (if any). Use this as a primer before those conversations.

FILE:scripts/contract_risk_scanner.py
#!/usr/bin/env python3
"""contract_risk_scanner.py — Scan a contract for founder-killer clauses.

Stdlib-only. Outputs human-readable or JSON. Detects 12 common risk patterns:
  1. Unilateral termination favoring the counterparty
  2. Auto-renewal with long notice (60+ days)
  3. Uncapped liability or exclusion of standard caps
  4. Broad indemnification flowing one direction
  5. Non-mutual confidentiality
  6. Missing or vague IP ownership clauses
  7. Aggressive non-compete / non-solicit
  8. Choice of law/venue in counterparty's home jurisdiction (one-sided)
  9. Force majeure favoring only the counterparty
 10. Missing DPA reference when personal data flows
 11. Most-favored-nation pricing clauses
 12. Audit rights without reciprocity

NOT legal advice. Use this to triage; bring findings to qualified counsel.

Usage:
    python contract_risk_scanner.py                       # uses embedded sample
    python contract_risk_scanner.py path/to/contract.txt
    python contract_risk_scanner.py contract.txt --output json
    python contract_risk_scanner.py --help
"""

import argparse
import json
import re
import sys
from dataclasses import dataclass, asdict
from typing import List


SAMPLE_CONTRACT = """\
MASTER SERVICES AGREEMENT

This Agreement shall automatically renew for successive one (1) year terms
unless either party provides ninety (90) days written notice of non-renewal.

LIMITATION OF LIABILITY. In no event shall Provider's aggregate liability
arising out of this Agreement exceed the fees paid by Customer in the
twelve (12) months preceding the claim. Notwithstanding the foregoing,
Customer's indemnification obligations under Section 8 shall be uncapped.

INDEMNIFICATION. Customer shall defend, indemnify and hold harmless
Provider, its affiliates, officers, directors and employees from and against
any and all claims, damages, losses and expenses arising out of or relating
to Customer's use of the Services.

INTELLECTUAL PROPERTY. The parties agree that intellectual property created
during the engagement shall belong to the party who develops it.

NON-COMPETE. For a period of three (3) years following termination, Customer
shall not engage with any competitor of Provider in any capacity, in any
geography.

GOVERNING LAW. This Agreement shall be governed by the laws of Delaware,
and any disputes shall be resolved exclusively in the state and federal
courts located in Wilmington, Delaware.

FORCE MAJEURE. Provider shall not be liable for any failure to perform due
to causes beyond its reasonable control.
"""


@dataclass
class Finding:
    rule_id: str
    severity: str           # CRITICAL | HIGH | MEDIUM | LOW
    title: str
    excerpt: str
    why_it_matters: str
    suggested_redline: str


RULES = [
    {
        "id": "AUTO_RENEW_LONG_NOTICE",
        "severity": "HIGH",
        "title": "Auto-renewal with long notice period",
        "pattern": re.compile(
            r"automatically renew.{0,200}?(\d+|sixty|ninety|one hundred|180)\s*(\(\d+\))?\s*day",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "Auto-renewal with >30 day notice is a classic vendor trap: founders forget the "
            "deadline and get locked into another full term. Especially painful on multi-year contracts."
        ),
        "redline": (
            "Counter: '...unless either party provides thirty (30) days written notice of non-renewal' "
            "OR remove auto-renewal entirely and require affirmative re-signature."
        ),
    },
    {
        "id": "UNCAPPED_CUSTOMER_INDEMNITY",
        "severity": "CRITICAL",
        "title": "Customer indemnity carved out from liability cap (uncapped)",
        "pattern": re.compile(
            r"(customer'?s|your)\s+indemnification.{0,200}?(uncapped|shall be uncapped|excluded from)",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "Uncapped customer indemnity means a single bad claim can exceed all fees ever paid. "
            "Standard practice: mutual indemnity, both sides capped at fees, with narrow carve-outs "
            "(IP infringement, data breach, gross negligence)."
        ),
        "redline": (
            "Counter: cap customer indemnity at 12 months of fees, mutual indemnity, carve-outs only "
            "for willful misconduct and breach of confidentiality."
        ),
    },
    {
        "id": "ONE_SIDED_INDEMNITY",
        "severity": "HIGH",
        "title": "Indemnification flows in one direction only",
        "pattern": re.compile(
            r"(customer|client)\s+shall\s+(defend|indemnify).{0,500}?(provider|company|vendor)",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "One-sided indemnity means you take on risk for the counterparty's actions without reciprocity. "
            "A balanced contract has mutual indemnification with mirrored carve-outs."
        ),
        "redline": (
            "Counter: 'Each party shall defend, indemnify and hold harmless the other party...' with "
            "mirrored scope and equal caps."
        ),
    },
    {
        "id": "VAGUE_IP",
        "severity": "CRITICAL",
        "title": "Vague IP ownership clause",
        "pattern": re.compile(
            r"intellectual property.{0,200}?(belong to the party who develops it|jointly owned|to be determined|as agreed)",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "Vague IP language is the #1 source of post-engagement disputes. Joint ownership often means "
            "neither party can license freely without the other's consent. 'As agreed' is unenforceable."
        ),
        "redline": (
            "Counter: 'All work product, deliverables, and derivative works created under this Agreement "
            "shall be the sole and exclusive property of Customer. Provider hereby assigns all right, title "
            "and interest...' Or explicitly carve out Provider's pre-existing IP and tools with a license back."
        ),
    },
    {
        "id": "AGGRESSIVE_NONCOMPETE",
        "severity": "HIGH",
        "title": "Aggressive non-compete (long duration or broad geography)",
        "pattern": re.compile(
            r"non.compete.{0,300}?(two|three|four|five|2|3|4|5)\s*\(?\d*\)?\s*year",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "Non-competes >12 months or with unbounded geography are often unenforceable (especially in "
            "California, and increasingly federally) but create chilling effects. They also signal the "
            "counterparty's overall negotiation posture."
        ),
        "redline": (
            "Counter: maximum 12 months, specific competitor list (not 'any competitor'), specific "
            "geography. For California-resident counterparties, remove entirely (California labor code "
            "voids most non-competes)."
        ),
    },
    {
        "id": "ONE_SIDED_VENUE",
        "severity": "MEDIUM",
        "title": "Choice of law/venue exclusively in counterparty jurisdiction",
        "pattern": re.compile(
            r"(exclusively in|exclusive jurisdiction).{0,300}?(courts? located in|state and federal courts of)",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "Exclusive venue in counterparty's jurisdiction means you bear travel cost and out-of-state "
            "counsel cost for any dispute. For startups this can effectively prevent enforcement."
        ),
        "redline": (
            "Counter: neutral venue (Delaware is common), or 'venue in the jurisdiction of the defendant' "
            "(forces plaintiff to travel), or arbitration in a neutral location with AAA/JAMS rules."
        ),
    },
    {
        "id": "ONE_SIDED_FORCE_MAJEURE",
        "severity": "MEDIUM",
        "title": "Force majeure clause favors one party",
        "pattern": re.compile(
            r"(provider|company|vendor)\s+shall not be liable.{0,200}?(force majeure|causes beyond)",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "If only the vendor gets force-majeure protection, you pay full price during a pandemic / "
            "outage / supply chain disruption but receive nothing. Mutual force majeure is standard."
        ),
        "redline": (
            "Counter: 'Neither party shall be liable...' with explicit list of qualifying events "
            "(pandemic, war, natural disaster, government action) and a termination right after 30 days."
        ),
    },
    {
        "id": "MISSING_DPA",
        "severity": "HIGH",
        "title": "Personal data appears to flow but no DPA referenced",
        "pattern": re.compile(
            r"(personal data|personally identifiable|user data|customer data|PII)(?!.{0,500}(DPA|data processing agreement|GDPR))",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "If personal data of EU residents (or California residents) flows, a DPA is legally required. "
            "Missing DPA = GDPR Article 28 violation, potential 4%-of-revenue fine, contract unenforceable "
            "with EU customers."
        ),
        "redline": (
            "Counter: 'The parties shall execute a Data Processing Agreement substantially in the form "
            "of Exhibit X prior to any processing of Personal Data.' Use IAPP or Vendor-friendly DPA template."
        ),
    },
    {
        "id": "MOST_FAVORED_NATION",
        "severity": "MEDIUM",
        "title": "Most-favored-nation (MFN) pricing clause",
        "pattern": re.compile(
            r"(most.favored.nation|MFN|best price|lowest price).{0,200}?(offered to|charged to)",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "MFN clauses prevent you from offering volume discounts or strategic pricing to anyone else. "
            "If you sign with one customer, every future customer can demand the same price."
        ),
        "redline": (
            "Counter: remove the MFN entirely. If kept, narrow to 'similarly situated customers, same "
            "tier and volume, excluding strategic / launch / migration discounts.'"
        ),
    },
    {
        "id": "ONE_SIDED_AUDIT",
        "severity": "MEDIUM",
        "title": "Audit rights without reciprocity",
        "pattern": re.compile(
            r"(customer|client).{0,100}?right to audit",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "One-sided audit rights mean the counterparty can demand records on demand, often at your "
            "expense. Reciprocity is standard for B2B agreements."
        ),
        "redline": (
            "Counter: mutual audit rights, max once per year, at requesting party's expense, with "
            "30-day notice, during business hours, narrowed to specific compliance categories."
        ),
    },
    {
        "id": "BROAD_NON_SOLICIT",
        "severity": "MEDIUM",
        "title": "Broad non-solicit (employees AND customers, long duration)",
        "pattern": re.compile(
            r"non.solicit.{0,300}?(employees? and customers?|customers? and employees?)",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "Combined employee + customer non-solicits, especially with long duration, can severely "
            "limit hiring and business development. Many states limit enforceability."
        ),
        "redline": (
            "Counter: split into employee-only (12 months max) and customer-only (12 months max) clauses, "
            "with carve-outs for general advertising / open job postings and for customers who initiate "
            "contact independently."
        ),
    },
    {
        "id": "PERPETUAL_LICENSE_BACK",
        "severity": "HIGH",
        "title": "Perpetual license-back to counterparty of your data or work",
        "pattern": re.compile(
            r"perpetual.{0,100}?(license|right).{0,300}?(customer data|user data|work product|deliverables)",
            re.IGNORECASE | re.DOTALL,
        ),
        "why_it_matters": (
            "A perpetual license-back lets the counterparty use your data or deliverables forever, even "
            "after termination. This is acceptable for usage analytics, NOT for customer data or core IP."
        ),
        "redline": (
            "Counter: time-limited license (for the term of the agreement only), specific purpose "
            "(service delivery only, not training AI models, not sharing with third parties), and "
            "post-termination return-or-destroy obligation."
        ),
    },
]


def scan(text: str) -> List[Finding]:
    findings: List[Finding] = []
    for rule in RULES:
        for match in rule["pattern"].finditer(text):
            excerpt = match.group(0).strip()
            # truncate long excerpts
            if len(excerpt) > 300:
                excerpt = excerpt[:297] + "..."
            findings.append(Finding(
                rule_id=rule["id"],
                severity=rule["severity"],
                title=rule["title"],
                excerpt=excerpt,
                why_it_matters=rule["why_it_matters"],
                suggested_redline=rule["redline"],
            ))
    # rank by severity then rule order
    severity_order = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
    findings.sort(key=lambda f: (severity_order.get(f.severity, 9), f.rule_id))
    return findings


def render_text(findings: List[Finding], source: str) -> str:
    lines = []
    lines.append("=" * 72)
    lines.append("CONTRACT RISK SCAN")
    lines.append(f"Source: {source}")
    lines.append(f"Findings: {len(findings)}")
    lines.append("=" * 72)
    lines.append("")
    if not findings:
        lines.append("No risk patterns matched. (Absence of findings does not mean the contract is safe;")
        lines.append("it means the 12 common patterns this scanner checks did not trigger.)")
        lines.append("")
        lines.append("Always engage qualified counsel before signing.")
        return "\n".join(lines)

    severity_counts = {}
    for f in findings:
        severity_counts[f.severity] = severity_counts.get(f.severity, 0) + 1
    severity_summary = "  ".join(
        f"{sev}: {severity_counts.get(sev, 0)}"
        for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW")
        if severity_counts.get(sev, 0) > 0
    )
    lines.append(f"Severity: {severity_summary}")
    lines.append("")

    for i, f in enumerate(findings, 1):
        lines.append(f"[{i}] {f.severity} — {f.title}")
        lines.append(f"    Rule: {f.rule_id}")
        lines.append(f"    Excerpt: \"{f.excerpt}\"")
        lines.append("")
        lines.append(f"    Why it matters:")
        for line in _wrap(f.why_it_matters, 4):
            lines.append(line)
        lines.append("")
        lines.append(f"    Suggested redline:")
        for line in _wrap(f.suggested_redline, 4):
            lines.append(line)
        lines.append("")
        lines.append("-" * 72)

    lines.append("")
    lines.append("REMINDER: This scanner triages obvious traps. Always bring redlines to qualified counsel.")
    return "\n".join(lines)


def _wrap(text: str, indent: int, width: int = 68) -> List[str]:
    import textwrap
    return textwrap.wrap(text, width=width, initial_indent=" " * indent, subsequent_indent=" " * indent) or [" " * indent + text]


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Scan a contract for the 12 most common founder-killer clauses.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("path", nargs="?", help="Path to contract text file (uses embedded sample if omitted)")
    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
    args = parser.parse_args()

    if args.path:
        try:
            with open(args.path, "r", encoding="utf-8") as f:
                text = f.read()
            source = args.path
        except (IOError, OSError) as e:
            print(f"error: could not read {args.path}: {e}", file=sys.stderr)
            return 1
    else:
        text = SAMPLE_CONTRACT
        source = "<embedded sample MSA>"

    findings = scan(text)

    if args.output == "json":
        payload = {
            "source": source,
            "findings_count": len(findings),
            "findings": [asdict(f) for f in findings],
        }
        print(json.dumps(payload, indent=2))
    else:
        print(render_text(findings, source))

    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/term_sheet_analyzer.py
#!/usr/bin/env python3
"""term_sheet_analyzer.py — Score a term sheet on founder-friendliness.

Stdlib-only. Computes a 0-100 score across 12 dimensions and flags
hostile clauses. Outputs human-readable or JSON.

NOT legal advice — surfaces questions for venture / securities counsel.

Input schema (JSON):
{
  "round": "Series A",
  "pre_money": 30000000,
  "raise_amount": 8000000,
  "liquidation_preference": {
    "multiple": 1.0,
    "participating": false,
    "cap": null
  },
  "anti_dilution": "broad_based_weighted_average",  // | "narrow_based_weighted_average" | "full_ratchet" | "none"
  "option_pool": {
    "size_pct": 12.0,
    "pre_money": true
  },
  "board_composition": {
    "investor_seats": 1,
    "founder_seats": 2,
    "independent_seats": 1
  },
  "vesting": {
    "standard_years": 4,
    "cliff_months": 12,
    "single_trigger_acceleration": false,
    "double_trigger_acceleration": true
  },
  "pro_rata": true,
  "drag_along": {
    "exists": true,
    "founder_consent_required": true
  },
  "protective_provisions": "standard",  // | "standard" | "aggressive"
  "information_rights": "standard",     // | "standard" | "aggressive"
  "dividends": "none"                   // | "none" | "non_cumulative_when_declared" | "cumulative"
}

Usage:
    python term_sheet_analyzer.py                            # uses embedded sample
    python term_sheet_analyzer.py path/to/term_sheet.json
    python term_sheet_analyzer.py term_sheet.json --output json
    python term_sheet_analyzer.py --help
"""

import argparse
import json
import sys
from typing import Any, Dict, List, Tuple


SAMPLE = {
    "round": "Series A",
    "pre_money": 30_000_000,
    "raise_amount": 8_000_000,
    "liquidation_preference": {"multiple": 1.0, "participating": False, "cap": None},
    "anti_dilution": "broad_based_weighted_average",
    "option_pool": {"size_pct": 12.0, "pre_money": True},
    "board_composition": {"investor_seats": 1, "founder_seats": 2, "independent_seats": 1},
    "vesting": {
        "standard_years": 4,
        "cliff_months": 12,
        "single_trigger_acceleration": False,
        "double_trigger_acceleration": True,
    },
    "pro_rata": True,
    "drag_along": {"exists": True, "founder_consent_required": True},
    "protective_provisions": "standard",
    "information_rights": "standard",
    "dividends": "none",
}


def score(ts: Dict[str, Any]) -> Tuple[int, List[Dict[str, Any]]]:
    """Returns (total_score_0_to_100, list_of_findings).

    Each dimension is scored 0-100, then averaged. Findings list contains
    per-clause analysis with severity.
    """
    findings: List[Dict[str, Any]] = []
    scores: List[int] = []

    # --- 1. Liquidation Preference (high signal) ---
    lp = ts.get("liquidation_preference", {})
    lp_mult = lp.get("multiple", 1.0)
    lp_part = lp.get("participating", False)
    lp_cap = lp.get("cap")
    if lp_mult == 1.0 and not lp_part:
        lp_score = 100
        findings.append(_ok("liquidation_preference", "1x non-participating — founder-friendly standard."))
    elif lp_mult == 1.0 and lp_part and lp_cap and lp_cap <= 3:
        lp_score = 55
        findings.append(_warn("liquidation_preference",
            f"1x participating with {lp_cap}x cap. Investor double-dips up to cap. "
            "Push for non-participating; if accepted, accept cap < 3x."))
    elif lp_mult == 1.0 and lp_part and not lp_cap:
        lp_score = 25
        findings.append(_crit("liquidation_preference",
            "1x PARTICIPATING UNCAPPED. Investor gets their money back AND a pro-rata share of remaining proceeds, "
            "forever. Hostile. Push to non-participating or at minimum cap at 2x."))
    elif lp_mult > 1.0:
        lp_score = 10
        findings.append(_crit("liquidation_preference",
            f"{lp_mult}x preference. Investor gets {lp_mult}x their money back before founders see a dollar. "
            "Hostile; only acceptable in distressed rounds."))
    else:
        lp_score = 80
        findings.append(_ok("liquidation_preference", f"{lp_mult}x configuration acceptable."))
    scores.append(lp_score)

    # --- 2. Anti-Dilution ---
    ad = ts.get("anti_dilution", "broad_based_weighted_average")
    if ad == "broad_based_weighted_average":
        ad_score = 100
        findings.append(_ok("anti_dilution", "Broad-based weighted average — founder-friendly standard."))
    elif ad == "narrow_based_weighted_average":
        ad_score = 70
        findings.append(_warn("anti_dilution",
            "Narrow-based weighted average. More dilutive to founders than broad-based in a down round. "
            "Push to broad-based."))
    elif ad == "full_ratchet":
        ad_score = 10
        findings.append(_crit("anti_dilution",
            "FULL RATCHET. In a down round, investor's price is reset to the new round price entirely, "
            "massively diluting founders. Hostile; reject."))
    elif ad == "none":
        ad_score = 100
        findings.append(_ok("anti_dilution", "No anti-dilution provision. Unusual but founder-friendly."))
    else:
        ad_score = 50
        findings.append(_warn("anti_dilution", f"Unrecognized anti-dilution type: {ad}. Verify with counsel."))
    scores.append(ad_score)

    # --- 3. Option Pool (pre-money vs post-money) ---
    op = ts.get("option_pool", {})
    op_pre = op.get("pre_money", True)
    op_size = op.get("size_pct", 10.0)
    if not op_pre:
        op_score = 100
        findings.append(_ok("option_pool",
            f"Pool of {op_size}% sits post-money — dilutes all shareholders proportionally."))
    elif op_pre and op_size <= 10.0:
        op_score = 70
        findings.append(_warn("option_pool",
            f"Pool of {op_size}% pre-money — comes out of founders' shares. Reasonable size, but consider "
            "negotiating post-money or sharing the pool top-up across the round."))
    elif op_pre and op_size > 10.0:
        op_score = 30
        findings.append(_crit("option_pool",
            f"Pool of {op_size}% PRE-MONEY. This is the 'option pool shuffle' — typically reduces pre-money "
            f"by ~{op_size}%, diluting founders silently. Negotiate hard: justify the size with a hiring plan "
            "or push for post-money."))
    else:
        op_score = 60
        findings.append(_warn("option_pool", "Option pool structure unclear; verify."))
    scores.append(op_score)

    # --- 4. Board Composition ---
    bc = ts.get("board_composition", {})
    inv = bc.get("investor_seats", 0)
    fnd = bc.get("founder_seats", 0)
    ind = bc.get("independent_seats", 0)
    total = inv + fnd + ind
    if total == 0:
        bc_score = 50
        findings.append(_warn("board_composition", "Board composition unspecified."))
    elif fnd > inv and ind >= 1:
        bc_score = 100
        findings.append(_ok("board_composition",
            f"{fnd} founder / {inv} investor / {ind} independent — founder-friendly; founders retain control "
            "with independent tie-breaker."))
    elif fnd == inv and ind >= 1:
        bc_score = 75
        findings.append(_ok("board_composition",
            f"{fnd} founder / {inv} investor / {ind} independent — balanced, independent is critical."))
    elif inv > fnd:
        bc_score = 30
        findings.append(_crit("board_composition",
            f"{fnd} founder / {inv} investor / {ind} independent — investors control the board at Series A. "
            "This is unusually early; investor control typically arrives at Series B or later."))
    else:
        bc_score = 50
        findings.append(_warn("board_composition", f"Composition: {fnd}F/{inv}I/{ind}Ind — verify with counsel."))
    scores.append(bc_score)

    # --- 5. Vesting & Acceleration ---
    vest = ts.get("vesting", {})
    years = vest.get("standard_years", 4)
    cliff = vest.get("cliff_months", 12)
    single = vest.get("single_trigger_acceleration", False)
    double = vest.get("double_trigger_acceleration", False)
    if years == 4 and cliff == 12 and double and not single:
        vest_score = 100
        findings.append(_ok("vesting",
            "4yr/1yr cliff with double-trigger acceleration — founder-friendly standard. "
            "Single-trigger is rare and not recommended by counsel."))
    elif years == 4 and cliff == 12 and not double:
        vest_score = 60
        findings.append(_warn("vesting",
            "4yr/1yr cliff WITHOUT acceleration. Push for double-trigger (change of control + termination "
            "without cause) to protect founder upside in acquisition scenarios."))
    elif years > 4:
        vest_score = 20
        findings.append(_crit("vesting",
            f"{years}-year vesting. Non-standard; reject. 4 years is industry norm."))
    else:
        vest_score = 70
        findings.append(_warn("vesting", f"{years}yr/{cliff}mo cliff — verify acceleration with counsel."))
    scores.append(vest_score)

    # --- 6. Pro-Rata Rights ---
    if ts.get("pro_rata", True):
        pr_score = 100
        findings.append(_ok("pro_rata", "Pro-rata rights — standard for the lead and major investors."))
    else:
        pr_score = 60
        findings.append(_warn("pro_rata",
            "No pro-rata rights. Unusual; if investor is offering this, ask why (signals weak conviction "
            "or competitive pressure). Pro-rata is generally fine for founders to grant."))
    scores.append(pr_score)

    # --- 7. Drag-Along ---
    drag = ts.get("drag_along", {})
    if drag.get("exists") and drag.get("founder_consent_required"):
        drag_score = 100
        findings.append(_ok("drag_along",
            "Drag-along exists but requires founder consent — balanced."))
    elif drag.get("exists") and not drag.get("founder_consent_required"):
        drag_score = 40
        findings.append(_crit("drag_along",
            "Drag-along WITHOUT founder consent. Investors can force a sale over founder objection. "
            "Push for founder consent OR a minimum price threshold (e.g., 3x preference) to trigger drag."))
    else:
        drag_score = 80
        findings.append(_ok("drag_along", "No drag-along — neutral; common at early stages."))
    scores.append(drag_score)

    # --- 8. Protective Provisions ---
    pp = ts.get("protective_provisions", "standard")
    if pp == "standard":
        pp_score = 100
        findings.append(_ok("protective_provisions",
            "Standard protective provisions (NVCA model) — acceptable."))
    elif pp == "aggressive":
        pp_score = 40
        findings.append(_crit("protective_provisions",
            "Aggressive protective provisions can require investor consent for routine operating "
            "decisions (hiring execs, budget changes, vendor contracts). Push back to NVCA standard."))
    else:
        pp_score = 70
        findings.append(_warn("protective_provisions", f"Verify scope with counsel: {pp}"))
    scores.append(pp_score)

    # --- 9. Information Rights ---
    ir = ts.get("information_rights", "standard")
    if ir == "standard":
        ir_score = 100
        findings.append(_ok("information_rights",
            "Standard information rights (quarterly financials, annual audited, budget) — acceptable."))
    elif ir == "aggressive":
        ir_score = 60
        findings.append(_warn("information_rights",
            "Aggressive information rights (monthly financials, board observer rights, inspection rights). "
            "Reasonable for lead at Series B+; at Series A, push to quarterly."))
    else:
        ir_score = 75
        findings.append(_warn("information_rights", f"Verify: {ir}"))
    scores.append(ir_score)

    # --- 10. Dividends ---
    div = ts.get("dividends", "none")
    if div == "none":
        div_score = 100
        findings.append(_ok("dividends", "No dividend obligation — founder-friendly standard."))
    elif div == "non_cumulative_when_declared":
        div_score = 80
        findings.append(_ok("dividends",
            "Non-cumulative when-declared dividends — acceptable; rare to actually be paid."))
    elif div == "cumulative":
        div_score = 30
        findings.append(_crit("dividends",
            "CUMULATIVE dividends accrue every year regardless of declaration and must be paid at exit. "
            "Hostile; push to non-cumulative or none."))
    else:
        div_score = 60
        findings.append(_warn("dividends", f"Verify dividend type: {div}"))
    scores.append(div_score)

    # --- 11. Valuation Sanity ---
    pre = ts.get("pre_money", 0)
    raise_amt = ts.get("raise_amount", 0)
    if pre and raise_amt:
        post = pre + raise_amt
        dilution = (raise_amt / post) * 100
        if dilution > 30:
            val_score = 40
            findings.append(_crit("valuation",
                f"Round dilutes {dilution:.1f}% (raise , on , pre = , post). "
                "Over 30% in a single round is heavy; standard is 15-25%."))
        elif dilution > 25:
            val_score = 70
            findings.append(_warn("valuation",
                f"Round dilutes {dilution:.1f}%. Acceptable but on the high end. Standard 15-25%."))
        else:
            val_score = 100
            findings.append(_ok("valuation",
                f"Round dilutes {dilution:.1f}% — within standard 15-25% range."))
        scores.append(val_score)

    # --- 12. Holistic posture ---
    crit_count = sum(1 for f in findings if f["severity"] == "CRITICAL")
    if crit_count >= 3:
        findings.append(_crit("holistic",
            f"{crit_count} CRITICAL flags. This is a hostile term sheet. Either renegotiate the worst clauses "
            "or walk. Do not sign as-is."))
    elif crit_count >= 1:
        findings.append(_warn("holistic",
            f"{crit_count} CRITICAL flag(s). Address before signing; the rest is negotiable but not "
            "disqualifying."))
    else:
        findings.append(_ok("holistic", "No critical flags. Standard founder-friendly term sheet."))

    total_score = round(sum(scores) / len(scores)) if scores else 0
    return total_score, findings


def _ok(clause: str, msg: str) -> Dict[str, Any]:
    return {"clause": clause, "severity": "OK", "message": msg}

def _warn(clause: str, msg: str) -> Dict[str, Any]:
    return {"clause": clause, "severity": "WARN", "message": msg}

def _crit(clause: str, msg: str) -> Dict[str, Any]:
    return {"clause": clause, "severity": "CRITICAL", "message": msg}


def render_text(score_val: int, findings: List[Dict[str, Any]], source: str) -> str:
    lines = []
    lines.append("=" * 72)
    lines.append("TERM SHEET ANALYSIS")
    lines.append(f"Source: {source}")
    lines.append("=" * 72)
    lines.append("")
    grade = (
        "🟢 FOUNDER-FRIENDLY" if score_val >= 85 else
        "🟡 NEGOTIATE"          if score_val >= 65 else
        "🔴 HOSTILE"
    )
    lines.append(f"Founder-friendliness score: {score_val}/100   {grade}")
    lines.append("")
    lines.append("-" * 72)

    for f in findings:
        sev = f["severity"]
        marker = {"OK": "✅", "WARN": "⚠️ ", "CRITICAL": "🚨"}.get(sev, "•")
        lines.append(f"{marker} [{sev:>8}] {f['clause']}")
        lines.append(f"           {f['message']}")
        lines.append("")

    lines.append("-" * 72)
    lines.append("REMINDER: This tool is not legal advice. Always engage venture / securities counsel.")
    return "\n".join(lines)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Score a term sheet on founder-friendliness across 12 dimensions.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("path", nargs="?", help="Path to term sheet JSON file (uses embedded sample if omitted)")
    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
    args = parser.parse_args()

    if args.path:
        try:
            with open(args.path, "r", encoding="utf-8") as f:
                ts = json.load(f)
            source = args.path
        except (IOError, OSError) as e:
            print(f"error: could not read {args.path}: {e}", file=sys.stderr)
            return 1
        except json.JSONDecodeError as e:
            print(f"error: invalid JSON in {args.path}: {e}", file=sys.stderr)
            return 1
    else:
        ts = SAMPLE
        source = "<embedded sample Series A term sheet>"

    score_val, findings = score(ts)

    if args.output == "json":
        print(json.dumps({
            "source": source,
            "score": score_val,
            "grade": "FOUNDER_FRIENDLY" if score_val >= 85 else "NEGOTIATE" if score_val >= 65 else "HOSTILE",
            "findings": findings,
        }, indent=2))
    else:
        print(render_text(score_val, findings, source))

    return 0


if __name__ == "__main__":
    sys.exit(main())

---
name: grants
description: "NIH grant research skill for clinical researchers. Grill-me intake (research idea + career stage + preliminary data + environment + submission posture + known institute targets) locks down the funding strategy before any search runs. Runs a 5-facet Consensus positioning analysis (with draft Significance/Innovation language), maps the research to the right NIH institutes and study sections via RePORTER, finds NOSIs and funded overlap, and produces an editable Word document (.docx) with budget/scope-aware mechanism recommendations, submission timelines, and a mandatory program officer recommendation. Triggers: 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research', or any grant-related request. NIH-only scope — non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake."
license: MIT
metadata:
  source_spec: "megaprompts/08-grants-megaprompt.md"
  build_pattern: "Path B (direct conversion)"
  research_pack_convention: "Agent Integrity Rules verbatim per PR #657 audit"
  version: 1.0.0
---

# Grants — NIH Funding Intelligence

> **Portability:** Requires `bash_tool` (for RePORTER POST via curl), Node.js with `docx` package, and a Consensus MCP connection. Works in Claude Code CLI natively. In Claude.ai with Code Execution + Consensus MCP, the workflow is supported but slower.

> **Scope: NIH-only.** Non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake.

For a clinical researcher with a research idea, produce a strategic NIH funding overview as an editable `.docx`. Output covers research positioning analysis, institute mapping, targeted grant discovery, and strategic recommendations the researcher can edit, copy from, and share with their mentor.

## Agent Integrity Rules (Research-Pack Convention)

Inherited; locked verbatim per PR #657 audit.

- **Execution discipline.** A step isn't complete until result is confirmed received. Consensus calls **sequential with 1+ sec pause**. RePORTER calls sequential.
- **Data sourcing.** Count only what tool calls returned this session. Never supplement with training knowledge. Training knowledge labeled `[Not from Consensus/RePORTER — reference information]` and excluded from counts.
- **Counts & attribution.** Queries sent / results shown / results cited — three separate numbers, never conflate. Every cited paper has retrievable URL from this session.
- **Error handling.** On failure → wait 3s → retry once → log. After 3 consecutive failures across tools: stop, alert researcher, explain what's missing. Never silently skip.
- **Transparency.** Audit Log section in the DOCX. Same standards in chat summary as in document.

See [`references/reporter_post_patterns.md`](references/reporter_post_patterns.md) for the RePORTER POST canon + plan-tier detection.

## Phase 1: Grill-Me Intake (6 forcing questions, one at a time)

### Q1 (root) — Research idea

> **Describe the research idea in 2–3 sentences. What's the question, what's new, and what's the clinical relevance? Vague answers ("AI for healthcare", "biomarkers for disease X") will be rejected — push for specificity.**
>
> *Why I'm asking:* Five Consensus searches (established / stakes / current approaches / adjacent methods / gaps) depend on a precise research idea. Vague ideas produce vague gap quotes and useless positioning narrative.

Refuse mush. Re-ask once with examples if user is too broad.

### Q2 (depends on Q1) — Career stage

> **Career stage — pick one:**
>
> 1. Pre-doctoral (PhD student, T32 trainee)
> 2. Postdoctoral fellow (F32, K99 candidate)
> 3. Early career (K-award candidate, first R01)
> 4. Independent investigator (multiple R01s, established lab)
> 5. Senior PI (R35, P-series, U01 leadership)
>
> *Why I'm asking:* Career stage filters mechanism recommendations. F-series for trainees, K-series for early career, R-series for independent. Picking the wrong stage produces unfundable mechanism suggestions.

Forcing choice.

### Q3 (depends on Q2) — Preliminary data status

> **Preliminary data — pick one:**
>
> 1. None (de novo project, no pilot data yet)
> 2. Pilot data (early findings, single-site)
> 3. Strong preliminary (multi-experiment, ready for R01-scale)
> 4. Validated and ready (multi-site, publication-ready)
>
> *Why I'm asking:* Prelim data status drives mechanism budget. No data → R03 / R21 pilot scope. Strong prelim → R01 / U01 multi-site scale. Mismatch produces uncompetitive applications.

### Q4 (depends on Q2) — Environment

> **Research environment — pick one:**
>
> 1. R01-eligible (research-intensive institution with NIH base funding)
> 2. Mid-tier (regional academic medical center, modest NIH portfolio)
> 3. Resource-constrained (smaller institution, minimal NIH base)
> 4. Industry-collaborative (academic + industry partnership)
>
> *Why I'm asking:* Environment affects scope realism (multi-site U01 requires R01-eligible) and which mechanism categories are competitive (R15 specifically targets resource-constrained).

### Q5 (depends on Q1) — Submission posture

> **Submission posture — pick one:**
>
> 1. New application (first submission, no prior reviews)
> 2. Resubmission (A1 with reviewer responses needed)
> 3. Exploring (haven't decided yet whether to submit)
>
> *Why I'm asking:* Resubmissions need reviewer-response guidance in the DOCX (Section 7). New applications skip that. Exploring shifts emphasis to landscape over strategy.

### Q6 (depends on Q1) — Known institute targets

> **Are you already considering specific NIH institutes? List names (NCI / NHLBI / NIMH / NINDS / NIDDK / etc.) or say "no preference — find the right ones".**
>
> *Why I'm asking:* If you have an institute hypothesis, I'll validate it against RePORTER data. If not, I'll surface the top-3 institutes funding adjacent work from the institute-tally.

Accept "no preference" as the common case.

**Stop condition:** After Q6, commit and start Phase 2A. Never re-open intake after Phase 2A begins.

## Phase 2A: Research Positioning (5 Consensus searches)

Run sequentially at 1 q/sec. Each search corresponds to one positioning facet:

1. **Established** — `"<research idea>" established evidence` — what's known
2. **Stakes** — `"<topic>" mortality OR burden OR cost OR prevalence` — why it matters
3. **Current Approaches** — `"<topic>" current treatment OR standard of care OR approach` — state of the art
4. **Adjacent Methods** — `"<related technique>" applied to <topic>` — methodological possibilities
5. **Gaps** — `"<topic>" limitations OR unanswered OR future directions OR challenge` — gap signals

Use `scripts/citation_tracker.py --action record_consensus_search` for each. Plan-tier detected from first response.

**Synthesis:** for each facet, extract 2-3 quotable findings (becomes Section 2 gap quotes). Draft Significance/Innovation language using "the field has established X (refs), but Y remains unanswered (refs)" pattern.

## Phase 2B: Institute Mapping + Grant Discovery (RePORTER POST)

RePORTER is **POST-only**. Use `bash_tool` + `curl` — never `web_fetch`.

### Dynamic fiscal year window

Compute at runtime via `scripts/fiscal_year_calculator.py`. Default: current FY + 3 prior. Federal FY starts Oct 1, so:

```bash
python ../scripts/fiscal_year_calculator.py --output json
# Returns: {"current_fy": 2026, "window": [2023, 2024, 2025, 2026]}
```

### Narrow (AND) search — finds direct overlap

```bash
curl -X POST 'https://api.reporter.nih.gov/v2/projects/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "criteria": {
      "fiscal_years": [2023, 2024, 2025, 2026],
      "include_active_projects": true,
      "advanced_text_search": {
        "operator": "AND",
        "search_field": "all",
        "search_text": "<key term 1> <key term 2>"
      }
    },
    "limit": 50,
    "include_fields": ["project_num", "project_title", "agency_ic_admin", "study_section", "fiscal_year", "principal_investigators", "abstract_text"]
  }'
```

### Broad (OR) search — finds adjacent work

```bash
curl -X POST 'https://api.reporter.nih.gov/v2/projects/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "criteria": {
      "fiscal_years": [2023, 2024, 2025, 2026],
      "advanced_text_search": {
        "operator": "OR",
        "search_field": "all",
        "search_text": "<term> <synonym> <related concept>"
      }
    },
    "limit": 50
  }'
```

### Institute tally + study section ranking

After RePORTER responses:
- Tally `agency_ic_admin` (institute code: NCI, NHLBI, NIMH, etc.) → top-3 funding institutes
- Tally `study_section` → top-2 study sections (where applications go for review)

### NOSI discovery

Parse RePORTER responses for `NOT-*` opportunity numbers. For each:

```bash
# NOSIs live at predictable URLs:
# https://grants.nih.gov/grants/guide/notice-files/NOT-<INSTITUTE>-<YEAR>-<NUMBER>.html
web_fetch <url>
```

If fetch fails: log `[NOSI {number} — fetch failed, not included]`, continue.

## Mechanism Matching (Scope-Aware)

NOT career stage alone. Career stage **+** project scope **+** prelim data drive recommendation.

Use `scripts/mechanism_matcher.py`:

```bash
python ../scripts/mechanism_matcher.py \
  --career-stage "early_career" \
  --prelim-data "pilot" \
  --environment "r01_eligible" \
  --scope "single_site" \
  --output json
# Returns mechanism shortlist with rationale
```

See [`references/nih_mechanism_matching.md`](references/nih_mechanism_matching.md) for the full matrix.

## Phase 3: DOCX Generation

9 sections via Node.js + `docx` library. See [`references/docx_9_sections.md`](references/docx_9_sections.md) for full spec.

1. **Executive Summary** — title + career stage + environment + 3-4 key findings bullets
2. **Research Positioning** — 3-5 gap quotes (italicized, inline Consensus citations) + 2-3 paragraph positioning narrative + supporting evidence table
3. **Target Institutes** — ranking table (institute, project count in window, % match to your idea) + 2-3 sentence interpretation
4. **Grant Opportunities** — bold NOSI callout if any. Top-3 grants table with hyperlinked FOAs + per-grant scope/budget fit paragraph
5. **Funded Overlap** — top-5 projects table (PI, project_num, IC, year, hyperlinked to RePORTER) + differentiation paragraph
6. **Study Sections** — ranking table + best-match interpretation
7. **Strategic Recommendations & Next Steps** — 3-4 numbered recs + **mandatory program officer rec** + submission timeline note + (if resubmission Q5=2) reviewer-response guidance + closing paragraph
8. **References** — numbered bibliography, hyperlinked to Consensus
9. **Audit Log** — Consensus searches table, plan-tier note, RePORTER searches table, NOSI fetches table, summary stats, tool constraints note, failed steps

### Styling

Arial 12pt body, navy headings (#1a3a5c), light blue table headers (#e8f0f8), amber NOSI callout. `ExternalHyperlink` patterns:
- Paper citations: `https://consensus.app/papers/...`
- FOA links: `https://grants.nih.gov/grants/guide/...`
- RePORTER projects: `https://reporter.nih.gov/project-details/<id>`

## Mandatory Program Officer Recommendation

Always include in Section 7:

> **Recommended next step: contact program officer at {top institute}.** Find their staff page at https://www.nih.gov/institutes-nih/list-nih-institutes-centers-offices → {institute} → Program Officers. Prepare: 1-page specific aims + your CV + 3 specific questions about fit. Email subject: "Pre-application inquiry: <topic>".

This is the single most valuable advice for any applicant. Never skip.

## Submission Timeline (Embedded in DOCX Section 7)

| Mechanism | Standard receipt dates |
|---|---|
| R01, R21, R03 | Feb 5, Jun 5, Oct 5 |
| K awards (K01, K08, K23, K99) | Feb 12, Jun 12, Oct 12 |
| R34, R61/R33 | Feb 16, Jun 16, Oct 16 |
| F31, F32 | Apr 8, Aug 8, Dec 8 |

## Phase 4: Deliver

- Save DOCX to `<output-dir>/grants_<topic-slug>_<YYYY-MM-DD>.docx`
- Chat summary: file path + audit counts + plan tier + verdict on institute targets
- Validate: `python scripts/office/validate.py <docx>`

## Tooling

| Script | Role |
|---|---|
| `scripts/citation_tracker.py` | Three-count audit (Consensus sent/shown/cited + RePORTER projects/cited) at `~/.grants_sessions/<session>.json` |
| `scripts/fiscal_year_calculator.py` | Current FY + 3-prior window. Computed at runtime, never hardcoded. |
| `scripts/mechanism_matcher.py` | Career stage × scope × prelim → mechanism recommendation shortlist |

## References

- [`references/nih_mechanism_matching.md`](references/nih_mechanism_matching.md) — career stage × scope × prelim → mechanism canon (7+ sources)
- [`references/reporter_post_patterns.md`](references/reporter_post_patterns.md) — RePORTER curl POST templates + plan-tier detection (7+ sources)
- [`references/docx_9_sections.md`](references/docx_9_sections.md) — 9-section .docx spec + technical requirements (7+ sources)

## Error Handling

| Failure | Behavior |
|---|---|
| Consensus rate-limit hit | Wait 3s, retry once, log; if still failing, alert researcher |
| Consensus returns 0 for a facet | Surface explicitly; never fill with training knowledge |
| Consensus plan-tier cap detected | Log tier, note in audit, surface to researcher |
| RePORTER POST returns error | Retry once after 3s; if still failing, log and continue |
| RePORTER returns <5 on narrow | Document; broad OR should compensate; surface low count |
| NOSI fetch fails | Log `[NOSI {n} — fetch failed]`, continue |
| 3 consecutive tool failures | Stop, alert researcher with what's missing |
| DOCX generation fails | Save raw data as JSON fallback so researcher doesn't lose work |

## Anti-Patterns To Reject

- Parallelizing Consensus calls (will hit rate limit)
- Using `web_fetch` for RePORTER (POST-only — `web_fetch` is GET)
- Hardcoded fiscal year values
- Mechanism recommendations based on career stage alone (must consider scope too)
- Silently filling thin facet results with training knowledge
- Skipping the audit log
- Skipping the program officer recommendation
- Conflating "papers found" with "papers shown" with "papers cited"
- Fabricating NOSI details when fetch fails

---

**Version:** 1.0.0
**Source spec:** [`megaprompts/08-grants-megaprompt.md`](../../../../megaprompts/08-grants-megaprompt.md)
**Build pattern:** Path B (direct conversion). Research-pack sibling of pulse + litreview.

FILE:references/docx_9_sections.md
# DOCX 9-Section Spec — NIH Grants Strategic Overview

This reference answers exactly one decision: **what are the 9 sections of the grants .docx, and what does each need to be useful to a researcher submitting to NIH?**

## The Core Frame

The output is a **strategic overview**, not a complete application draft. The researcher edits, copies sections into their actual application, shares with their mentor. Useful means: actionable, source-attributed, scope-aware, ready for program officer conversation.

## Section 1: Executive Summary

**Length:** Title + metadata + 3-4 bullets. Half a page.

**Contents:**
- Title: "NIH Funding Strategy: {topic}"
- Date generated
- Career stage (from Q2)
- Environment (from Q4)
- 3-4 key findings:
  - Top institute(s) funding this area (from RePORTER)
  - Top recommended mechanism (from `mechanism_matcher.py`)
  - Submission posture insight (from Q5)
  - Critical gap or opportunity (from Phase 2A positioning)

**Tone:** Confident, actionable. Reader knows what to do after this section.

## Section 2: Research Positioning

**Length:** 1-1.5 pages.

**Contents:**

### Lead with 3-5 gap quotes

Italicized, with inline Consensus citations. Example:

> *"Existing approaches to sepsis prediction rely on static risk scores that fail to capture dynamic deterioration trajectories"* (Smith et al. 2023, Consensus).

These quotes become the foundation for the Significance section of the actual application.

### Positioning narrative (2-3 paragraphs)

Draft Significance/Innovation tone:
- Paragraph 1: The field has established X (refs from "Established" facet)
- Paragraph 2: Current approaches do Y, but Z remains unanswered (refs from "Current Approaches" + "Gaps" facets)
- Paragraph 3: This proposal addresses Z via {novel approach} (anchored in Q1 research idea)

### Supporting evidence table

| Finding | Source | Year | Cites |
|---|---|---|---|
| ... | Smith et al. | 2023 | 47 |

## Section 3: Target Institutes

**Length:** Half page.

### Ranking table

| Rank | Institute | Projects in window | % of total | Mission alignment |
|---|---|---|---|---|
| 1 | NHLBI | 23 | 38% | High — cardiovascular focus matches |
| 2 | NIDDK | 14 | 23% | Medium — metabolic angle |
| 3 | NCI | 8 | 13% | Low — oncology adjacent |

### 2-3 sentence interpretation

> NHLBI dominates this funding area with 38% of projects in the recent 4-year window. Their mission specifically prioritizes... If your Q1 hypothesis maps to cardiovascular outcomes, NHLBI is the primary target. NIDDK is a viable secondary if metabolic outcomes are involved.

## Section 4: Grant Opportunities

**Length:** 1 page.

### NOSI callout (if any found)

Bold amber box:

> 🔶 **Active NOSI: NOT-HL-25-014** — Special interest in machine learning for cardiovascular risk prediction. Expires: 2027-09-30. URL: https://grants.nih.gov/grants/guide/notice-files/NOT-HL-25-014.html
>
> If your project fits this NOSI, your application is reviewed with knowledge of the institute's specific interest in this area — substantially increases prospects.

### Top 3 grants table

| FOA | Mechanism | Institute | Deadline | Budget | Hyperlink |
|---|---|---|---|---|---|
| PAR-25-XXX | R01 | NHLBI | Feb 5 | $499k × 5 yr | [link to PA] |
| PA-25-YYY | R21 | NHLBI | Jun 16 | $275k × 2 yr | [link] |
| RFA-HL-25-ZZZ | U01 | NHLBI | Oct 5 | varies | [link] |

### Per-grant paragraph

For each: scope/budget fit. Whether the user's career stage + prelim + environment align with this specific FOA.

## Section 5: Funded Overlap

**Length:** 1 page.

### Top 5 funded projects table

| PI | Project | IC | Year | Hyperlink |
|---|---|---|---|---|
| Smith, J. | "AI-driven sepsis prediction..." | NHLBI | 2024 | [RePORTER] |

### Differentiation paragraph

> The closest existing project is Smith et al. (Project #R01HL12345) at Johns Hopkins. They focus on adult ICU patients with sepsis. **Your differentiation:** pediatric population, prospective trial design, real-time deployment vs retrospective benchmarking.

This differentiation paragraph is what the reviewer reads BEFORE the Approach section. Make it sharp.

## Section 6: Study Sections

**Length:** Half page.

### Ranking table

| Rank | Study Section | Projects in window | Specialization |
|---|---|---|---|
| 1 | MEDS (Medical Imaging Study Section) | 12 | Imaging/AI methods |
| 2 | BMIO (Bioinformatics Methods + ML) | 8 | Methods development |

### Best-match interpretation

> MEDS reviews most similar applications. Implications: lean into methods rigor (their reviewers will know the methodology landscape); abstract should make method specifically clear; supplementary methods section should be detailed.

## Section 7: Strategic Recommendations & Next Steps

**Length:** 1-1.5 pages.

### 3-4 numbered recommendations

1. **Target NHLBI as primary** — strongest institute alignment + active NOSI matches your scope
2. **Apply for R21 first if Q3=pilot, R01 if Q3=strong** — scope-aware mechanism (from `mechanism_matcher.py`)
3. **Frame as ML methods + clinical application** — appeals to MEDS reviewers
4. **(If resubmission, Q5=2):** Address prior reviewer concern A by adding aim X; address concern B with prelim data Y

### MANDATORY program officer recommendation

> **Single most valuable next step: contact program officer at NHLBI.**
>
> Staff page: https://www.nhlbi.nih.gov/about/divisions → relevant division → Program Officers.
>
> Prepare:
> 1. 1-page specific aims draft
> 2. NIH biosketch
> 3. 3 specific questions about NOSI fit + mechanism preference + study section recommendation
>
> Email subject: "Pre-application inquiry: <topic>". Mention specific NOSI if applicable.

### Submission timeline note

| Mechanism | Standard receipt dates |
|---|---|
| R01, R21, R03 | Feb 5, Jun 5, Oct 5 |
| K awards | Feb 12, Jun 12, Oct 12 |
| R34, R61/R33 | Feb 16, Jun 16, Oct 16 |
| F31, F32 | Apr 8, Aug 8, Dec 8 |

Work backwards from the deadline: typical writing window is 4-6 months. Pre-application program officer contact 3-4 months before. Internal institutional pre-review 6 weeks before.

### Closing paragraph

> Your strongest path is {top recommendation}. Highest-leverage next action: contact {top institute} program officer this week with the 1-pager. They'll tell you whether to proceed with {mechanism} or pivot.

## Section 8: References

**Length:** As many as cited; numbered + hyperlinked.

Bibliography:

1. Smith, J. et al. (2023). "AI for Sepsis Prediction." *Nature Med* 29(4), 456-468. [View on Consensus](https://consensus.app/papers/...)
2. ...

Discipline:
- Every inline citation in Sections 1-7 appears here
- Every entry hyperlinked to Consensus
- No phantom or orphan entries

## Section 9: Audit Log

**Length:** Half to full page.

### Consensus searches table

| # | Facet | Query | Results returned | Cited |
|---|---|---|---|---|
| 1 | Established | "..." | 10 | 3 |
| 2 | Stakes | "..." | 10 | 2 |
| ... | ... | ... | ... | ... |

### Plan-tier note

> Detected: Free tier (~10/query). Theoretical ceiling: 5 facets × 10 = 50 papers max from positioning. Actual unique papers: 38 (after deduplication).

### RePORTER searches table

| # | Type | Search text | Window | Projects |
|---|---|---|---|---|
| 1 | Narrow (AND) | "..." | FY 2023-2026 | 23 |
| 2 | Broad (OR) | "..." | FY 2023-2026 | 67 |

### NOSI fetches table

| NOSI | Status | URL |
|---|---|---|
| NOT-HL-25-014 | Fetched, included | [link] |
| NOT-DK-24-009 | Fetch failed | (not included) |

### Summary stats

```
Three counts:
- Queries sent:          7 (5 Consensus + 2 RePORTER)
- Results received:      120 (Consensus 50 + RePORTER 67 + NOSI 3)
- Results cited:         28 (Consensus 22 + RePORTER 5 + NOSI 1)

Failed steps: 1 (NOSI NOT-DK-24-009 fetch — included in NOSI table above)
```

### Tool constraints note

> RePORTER queried via POST (web_fetch is GET-only and would have failed silently). Consensus per-query cap detected as 10 (free tier). 3 consecutive failures threshold not reached this run.

## DOCX Technical Requirements

### Styling

- Body: Arial 12pt
- Headings: Navy (#1a3a5c) for H1/H2
- Table headers: Light blue (#e8f0f8) shading
- NOSI callout: Amber (#F5A623) background with bold border
- Italics for gap quotes (Section 2)

### Hyperlink patterns

```js
new ExternalHyperlink({
  link: "https://consensus.app/papers/<id>",
  children: [new TextRun({ text: paperTitle, style: "Hyperlink" })],
});

new ExternalHyperlink({
  link: "https://reporter.nih.gov/project-details/<id>",
  children: [new TextRun({ text: projectNum, style: "Hyperlink" })],
});

new ExternalHyperlink({
  link: "https://grants.nih.gov/grants/guide/notice-files/<NOSI>.html",
  children: [new TextRun({ text: nosiNumber, style: "Hyperlink" })],
});
```

### Tables (dual widths)

```js
new Table({
  columnWidths: [3000, 2000, 1500, 2500],  // EMU
  rows: rows.map(r => new TableRow({
    children: r.cells.map(c => new TableCell({
      width: { size: c.width, type: WidthType.DXA },
      shading: { type: ShadingType.CLEAR, color: "auto", fill: c.fill || "auto" },
      children: [new Paragraph(c.text)],
    })),
  })),
});
```

### Validation

After save:
```bash
python scripts/office/validate.py output.docx
```

If validation fails: unpack DOCX (it's a ZIP), inspect document.xml, fix the offending XML, repack.

## Citations (7 sources)

1. **`docx` Node.js library — github.com/dolanmiu/docx (MIT).** Authoritative API source for Paragraph, Table, ExternalHyperlink patterns.

2. **NIH OER, *Writing the NIH Grant Application: Strategies for Success* (2022 ed.).** Source for the Section 2 "draft Significance/Innovation language" pattern. Mirrors NIH's own application sections.

3. **Russell, S. W. & Morrison, D. C., *The Grant Application Writer's Workbook* (Grant Writers' Seminars, multiple eds.).** Source for the differentiation-paragraph (Section 5) discipline. "Reviewers spend 30 seconds on differentiation; make it sharp."

4. **PRISMA 2020 Statement — Page, M. J. et al., *BMJ* 372, 2021.** Source for audit-log section requirements. Every search query + filter + result count must be reproducible.

5. **NIH RePORTER documentation + portfolios.** Source for the institute mission summaries that anchor Section 3 interpretation. Each institute publishes mission + priority areas.

6. **Heggeness, M. L., "What Makes a Successful Grant Application" — *Nature Human Behaviour* 5, 2021.** Empirical meta-analysis. Source for "program officer contact is #1 predictor of submission success after scientific merit" (basis for the mandatory program officer recommendation in Section 7).

7. **Strunk, W. & White, E. B., *Elements of Style* (Macmillan).** Source for "Section 7 closing paragraph" voice — direct, no hedging, named highest-leverage action. "Omit needless words" applies to grant strategy: every sentence should pass the "what is the actionable" test.

FILE:references/nih_mechanism_matching.md
# NIH Mechanism Matching — Career Stage × Scope × Prelim

This reference answers exactly one decision: **given a researcher's career stage, project scope, and preliminary data status, which NIH mechanism(s) should the skill recommend?**

Pair with `scripts/mechanism_matcher.py` for the deterministic implementation.

## The Core Rule

**Career stage alone does NOT determine mechanism.** Scope and prelim data matter equally. The biggest misalignment is "early career + R01 with pilot data" — review reads as overscoped and goes unfunded.

The matching is a 3-dimensional lookup:

```
(career_stage, project_scope, preliminary_data) → mechanism shortlist
```

## Career Stage Buckets (from Q2)

| Bucket | Examples | Eligible mechanisms |
|---|---|---|
| Pre-doctoral | PhD student, T32 trainee | F31, T32 |
| Postdoctoral | F32, K99 candidate | F32, K99/R00, T32 |
| Early career | First R01 candidate, K-awardee | K01/K08/K23, K99/R00 → R00, R21, R03 |
| Independent | Multiple R01s, established lab | R01, R21, R03, R34, R61/R33 |
| Senior PI | R35, P-series | R35, P01, P30, U01 |

## Project Scope Buckets (inferred or asked)

| Scope | Indicator | Mechanism implication |
|---|---|---|
| Solo / pilot | Single site, single hypothesis, <2 yr | R03, R21 |
| Hypothesis-driven independent | Single PI, multi-aim, 4-5 yr | R01 |
| Multi-site cooperative | Multi-PI, multi-site, coord centers | U01 |
| Program-scale | Multiple aims, multiple PIs, sustained | P01, P30, R35 |
| Early/exploratory | High-risk, high-reward | DP1, DP2, R21 |

## Preliminary Data Buckets (from Q3)

| Status | Indicator | Mechanism budget tier |
|---|---|---|
| None | De novo project, no pilot | R03, R21, F-series |
| Pilot | Single-site early findings | R21, K-series, K99/R00 |
| Strong | Multi-experiment, R01-ready | R01, R34 |
| Validated | Multi-site publication-ready | R01, U01, P-series |

## Matching Matrix

The skill applies this matrix in `scripts/mechanism_matcher.py`:

### Pre-doctoral

- **Solo + None → F31** (NRSA individual fellowship)
- **Solo + Pilot → F31, T32 slot**
- **Larger → not eligible as PI** (work as co-investigator on mentor's grant)

### Postdoctoral

- **Solo + None → F32** (postdoc fellowship)
- **Solo + Pilot → F32, K99 candidate prep**
- **Strong + transitioning → K99/R00** (career-transition mechanism, unique to NIH)

### Early career

- **Solo + None/Pilot → K-series** (K01 / K08 / K23 — career development)
- **Solo + Pilot → R21 candidate** (after K-award completion or as parallel)
- **Independent + Pilot → R03, R21**
- **Independent + Strong → R01** (this is the "qualifying" R01 — most career-defining)
- **Resource-constrained env (Q4=3) → R15** (specifically targets this — fund undergrad-involving research)

### Independent

- **Pilot scope + Strong prelim → R01** (the standard)
- **Multi-aim + Strong → R01** (the standard 5-yr R01)
- **Multi-site + Validated → U01** (cooperative agreement)
- **Pilot/early → R21** (exploratory)
- **Clinical trial planning → R34**
- **Early-phase trial → R61/R33** (phased innovation award)
- **High-risk → DP1, DP2** (Pioneer / New Innovator)

### Senior PI

- **Program scope → R35** (outstanding investigator award, unrestricted by topic)
- **Program scope → P01** (program project, multi-PI)
- **Core facility → P30** (center grant)
- **Multi-site cooperative → U01**

## Critical Anti-Patterns

### Career stage alone

Common error: "Early career → K-award". Misses scope. Early-career researcher with **strong prelim** + **independent scope** should target **R01**, not K. K-award is for protected research time; R01 is for hypothesis-driven research budget.

### Scope/prelim mismatch

- "R01 + No prelim" → unfundable. Reviewers will reject as premature.
- "R03 + Strong prelim" → underscoped. Researcher leaves money + scope on the table.

`mechanism_matcher.py` flags both as warnings.

### Environment-blind recommendations

Resource-constrained institution (Q4=3) → consider **R15** specifically. R15 only goes to non-research-intensive institutions. Recommending R01 to a researcher at a resource-constrained college is malpractice — even with strong prelim, their environment can't support R01-scale costs.

### Skipping multi-PI options

For collaborative-by-design projects, **multi-PI R01** (multiple-PI option) is often better than splitting into two R01s. Don't default to single-PI just because it's the default.

## Mechanism Reference Table (Full)

| Mechanism | Budget (annual DC) | Duration | Best for | Prelim needed |
|---|---|---|---|---|
| F31 | $40-50k stipend + tuition | 2-3 yr | Pre-doc training | None-pilot |
| F32 | $48-58k stipend | 2-3 yr | Postdoc training | None-pilot |
| T32 | Institutional | 5-yr renewable | Pre-doc/postdoc training cohort | Institutional commitment |
| R03 | $50k × 2 yr | 2 yr | Small pilot studies | None-pilot |
| R21 | $275k DC × 2 yr | 2 yr | Pilot/exploratory R&D | None-pilot |
| R34 | $450k × 3 yr | 3 yr | Clinical trial planning | Pilot |
| R61/R33 | Phased: $250k + $500k × 2 yr | Up to 5 yr | Phased innovation | Pilot |
| K01 | $100k × 5 yr | 5 yr | Mentored research scientist | Pilot |
| K08 | $100k × 5 yr | 5 yr | Mentored clinical scientist | Pilot |
| K23 | $100k × 5 yr | 5 yr | Mentored patient-oriented | Pilot |
| K99/R00 | $90k mentored + $250k indep | Up to 5 yr | Postdoc → independence | Strong |
| R01 | $250-499k DC × 4-5 yr | 4-5 yr | Hypothesis-driven research | Strong |
| R15 | $300k total × 3 yr | 3 yr | Resource-constrained institutions | Pilot |
| R35 | $750k × 5-8 yr | 5-8 yr | Senior outstanding investigators | Validated |
| P01 | Multi-PI, $1-2M/yr × 5 yr | 5 yr | Program project (3+ PIs) | Validated |
| P30 | Core facility funding | 5 yr | Multi-investigator core | Validated |
| U01 | Cooperative agreement | 5 yr | Multi-site collaborative | Strong-validated |
| DP1 (Pioneer) | $700k × 5 yr | 5 yr | High-risk individual | None (visionary) |
| DP2 (New Innovator) | $300k × 5 yr | 5 yr | Early-career high-risk | Pilot |

## Program Officer Recommendation (Mandatory Per Skill)

After mechanism shortlist is generated, the skill MUST recommend:

> **Contact program officer at {top institute, top match} BEFORE writing.**
>
> Find them at: https://www.nih.gov/institutes-nih/list-nih-institutes-centers-offices → {institute} → Program Officers.
>
> Prepare:
> 1. 1-page specific aims
> 2. Your CV (NIH biosketch format if available)
> 3. 3 specific questions about institute priorities / mechanism fit
>
> Email subject: "Pre-application inquiry: <topic>"

This is the **single highest-leverage step** in any NIH application. Program officers signal "yes, submit" or "no, not the right institute" before you spend months writing. Skipping this is common; the cost is huge.

## Citations (7 sources)

1. **NIH Office of Extramural Research — *Types of Grant Programs* (https://grants.nih.gov/grants/funding/funding_program.htm).** Authoritative source for mechanism definitions + budget ranges + duration. The skill's mechanism reference table mirrors NIH's published catalog.

2. **Sally Rockey, "Mechanism Selection Guide" — *NIH Extramural Nexus*, 2014-2022.** Former NIH Deputy Director's blog series on mechanism selection. Source for the "career stage alone is wrong" framing.

3. **Robertson, M. et al., "Successful K-to-R Transition" — *Academic Medicine* 92(3), 2017.** Empirical analysis of K-award → R01 transitions. Source for the early-career mechanism sequencing (K → R21 → R01) heuristic.

4. **NIH RePORTER Project Database (https://reporter.nih.gov).** The empirical ground truth for what NIH actually funds — institute portfolios, study section ranges, project sizes. The skill queries this via POST API.

5. **Mehrotra, A. et al., "R01 Funding Patterns Across Career Stages" — *JAMA Internal Medicine*, 2020.** Career-stage-stratified analysis of R01 application + funding rates. Source for the "early career + strong prelim → R01 IS appropriate" guidance.

6. **NIH NRSA Fellowship guidelines (https://grants.nih.gov/training/F_files_index.htm).** Authoritative F31/F32 source. Source for the trainee-stage mechanism shortlist.

7. **Heggeness, M. L., "What Makes a Successful Grant Application" — *Nature Human Behaviour* 5, 2021.** Meta-analysis of grant-writing predictors. Source for the program-officer-contact recommendation (#1 predictor of submission success after scientific merit).

FILE:references/reporter_post_patterns.md
# RePORTER POST Patterns + Plan-Tier Detection

This reference answers exactly one decision: **how does the grants skill query NIH RePORTER, and what plan-tier signals does it detect from Consensus responses?**

## The Critical Constraint

**NIH RePORTER's API v2 is POST-only.** `web_fetch` (which performs GET requests) **will not work**. You MUST use `bash_tool` + `curl`.

This is the #1 anti-pattern for the grants skill. If a future maintainer "simplifies" to web_fetch, RePORTER queries silently fail and the skill produces hollow institute-mapping sections.

## RePORTER API Reference

- **Endpoint:** `https://api.reporter.nih.gov/v2/projects/search`
- **Method:** POST
- **Content-Type:** `application/json`
- **No auth required** for public-data queries
- **Rate limit:** documented as 1 q/sec; the skill applies 1+ sec sequential pause per research-pack convention

## Standard POST Templates

### Narrow (AND) — direct overlap

```bash
curl -X POST 'https://api.reporter.nih.gov/v2/projects/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "criteria": {
      "fiscal_years": [2023, 2024, 2025, 2026],
      "include_active_projects": true,
      "advanced_text_search": {
        "operator": "AND",
        "search_field": "all",
        "search_text": "deep learning electronic health records sepsis prediction"
      }
    },
    "limit": 50,
    "offset": 0,
    "include_fields": [
      "project_num",
      "project_title",
      "agency_ic_admin",
      "study_section",
      "fiscal_year",
      "principal_investigators",
      "abstract_text",
      "project_terms"
    ]
  }'
```

### Broad (OR) — adjacent work

```bash
curl -X POST 'https://api.reporter.nih.gov/v2/projects/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "criteria": {
      "fiscal_years": [2023, 2024, 2025, 2026],
      "advanced_text_search": {
        "operator": "OR",
        "search_field": "all",
        "search_text": "machine learning critical care sepsis early warning"
      }
    },
    "limit": 50
  }'
```

## Dynamic Fiscal Year Window

NIH fiscal year runs **Oct 1 → Sep 30**. Current FY = year of next Sep 30.

Use `scripts/fiscal_year_calculator.py`:

```bash
python ../scripts/fiscal_year_calculator.py
# Output:
# Current calendar year: 2026
# Current fiscal year:   2026 (Oct 1 2025 - Sep 30 2026)
# Window (current + 3 prior): [2023, 2024, 2025, 2026]
```

**Never hardcode years.** A skill committed in 2025 with hardcoded `[2022, 2023, 2024, 2025]` produces stale results in 2027.

## Institute Tally + Study Section Ranking

After both narrow + broad responses return, aggregate:

### Institute tally

For each project: extract `agency_ic_admin` (the institute code like NCI, NHLBI, NIMH).

```python
from collections import Counter
institute_counts = Counter()
for project in projects:
    institute_counts[project['agency_ic_admin']] += 1
top_institutes = institute_counts.most_common(3)
```

Surface in DOCX Section 3 as ranked table with project counts + brief institute mission.

### Study section ranking

For each project: extract `study_section`.

```python
study_section_counts = Counter()
for project in projects:
    section = project.get('study_section', '')
    if section:  # Some projects unassigned
        study_section_counts[section] += 1
top_sections = study_section_counts.most_common(2)
```

Surface in DOCX Section 6.

## NOSI Discovery from RePORTER Results

NOSI (Notice of Special Interest) numbers appear as `NOT-*` in project abstracts, project terms, or related-FOA fields. Parse with regex:

```python
import re
NOSI_RE = re.compile(r'NOT-[A-Z]{2,3}-\d{2}-\d{3}')
nosi_numbers = set()
for project in projects:
    abstract = project.get('abstract_text', '')
    nosi_numbers.update(NOSI_RE.findall(abstract))
```

For each NOSI number, fetch via `web_fetch` (NOSIs have predictable URLs):

```
https://grants.nih.gov/grants/guide/notice-files/{NOSI_NUMBER}.html
```

If fetch fails: log `[NOSI {number} — fetch failed, not included]`. Never fabricate NOSI details.

## Plan-Tier Detection (Consensus)

Consensus has tiered plans with different per-query result caps. The skill detects from response text patterns:

| Pattern in response | Tier | Per-query cap |
|---|---|---|
| `"Showing top 10"` / `"upgrade for more"` | Free | 10 results |
| Receives 20 results without "showing top" | Pro | 20 results |
| Receives ≤3 results consistently | Unauthenticated / API quota issue | 3 results |
| No response / 401 / 403 | Auth failure | n/a |

Surface at end of Phase 2A in DOCX audit log:

> **Plan tier detected: Free** (Consensus returns ~10 results per query, capped). Total positioning landscape: 5 facets × 10 results = ~50 papers max. For deeper coverage, consider Consensus Pro (20/query).

This calibrates user expectations BEFORE they read the DOCX and wonder why coverage seems thin.

## Sequential Execution Discipline

Per research-pack convention: **1 q/sec, never parallelize.**

- 5 Consensus searches (Phase 2A) sequential — pause 1+ sec between
- 2 RePORTER POST searches (narrow + broad) sequential
- N NOSI `web_fetch` calls sequential

Each call records timestamp via `citation_tracker.py`; second call within 1s is rejected.

Total Phase 2 wall-clock time: ~7-10 sec for searches + however long NOSI fetches take.

## Error Handling

| Failure | Handling |
|---|---|
| Consensus 429 (rate limit) | Wait 3s, retry once, log to audit |
| Consensus 0 results for a facet | Surface explicitly in DOCX positioning section; mark `[no results — verify terminology]` |
| RePORTER 5xx | Retry once after 3s; if still failing, log and continue with what's available |
| RePORTER <5 results on narrow | Document low count; rely on broad OR for coverage |
| NOSI fetch fails | `[NOSI {number} — fetch failed]`; never fabricate |
| 3 consecutive failures across tools | Halt; alert researcher with what's missing |
| Auth failure (401/403) | Halt; tell user to check API key or MCP connection |

## Citations (7 sources)

1. **NIH RePORTER API v2 documentation — https://api.reporter.nih.gov/documents/Data%20Element%20Descriptions.pdf.** Authoritative spec for POST endpoint, field definitions, fiscal-year filter semantics. The skill's curl templates are direct applications.

2. **NIH Office of Extramural Research — *NIH Guide for Grants and Contracts* (https://grants.nih.gov/grants/guide).** Source for NOSI / FOA URL structure. NOSI naming conventions (`NOT-{IC}-{YY}-{NNN}`) are documented here.

3. **`praw` library + Reddit API community guidance.** Source for the "1 q/sec is the polite default" pattern that the skill applies to RePORTER even though RePORTER's documented limits are looser. Politeness with shared infrastructure.

4. **Mike Cohen, "Exponential Backoff and Jitter" — AWS Architecture Blog, 2015.** Source for the "wait 3s + retry once" retry pattern. Research-workflow scale doesn't justify exponential backoff.

5. **`curl` documentation (https://curl.se/docs/manual.html).** Source for POST body + Content-Type header syntax. The skill's curl templates follow `curl --help`.

6. **Maynez et al., "On Faithfulness and Factuality in Abstractive Summarization" — ACL 2020.** Source for the source-discipline rule that justifies refusing to fabricate NOSI details when fetch fails. LLMs hallucinate plausible-looking NIH NOSI numbers; refuse.

7. **Susskind, D., "Show your work" — *Communications of the ACM*, 2024.** Source for the audit-log section's role: transparent surfacing of what was queried, what was returned, what was cited. The audit-log table in DOCX Section 9 is this principle's implementation.

FILE:scripts/citation_tracker.py
#!/usr/bin/env python3
"""citation_tracker.py — JSON-backed three-count audit for grants runs.

Stdlib-only. Mirrors litreview's tracker but extended for grants's
multi-source workflow (Consensus + RePORTER + NOSI fetches).

Tracked counts:
  - consensus_searches    (5 facets sent)
  - consensus_received    (papers shown across facets)
  - consensus_cited       (papers cited in DOCX)
  - reporter_searches     (typically 2: narrow + broad)
  - reporter_projects     (projects returned across both)
  - reporter_cited        (projects cited in DOCX)
  - nosi_fetches          (NOT-* fetches attempted)
  - nosi_succeeded        (fetches that returned content)

Enforces 1s sequential gap on Consensus searches (research-pack convention).
Persists at ~/.grants_sessions/<session>.json.

Usage:
    python citation_tracker.py --action start --session grants-20260515 --topic "sepsis prediction"
    python citation_tracker.py --action record_consensus_search --session ... --facet established --query "..." --tier free
    python citation_tracker.py --action record_consensus_received --session ... --count 10
    python citation_tracker.py --action record_consensus_cited --session ... --url "https://consensus.app/..."
    python citation_tracker.py --action record_reporter_search --session ... --type narrow --query "..." --projects 23
    python citation_tracker.py --action record_reporter_cited --session ... --project-num "R01HL12345"
    python citation_tracker.py --action record_nosi --session ... --nosi "NOT-HL-25-014" --status fetched
    python citation_tracker.py --action status --session ...
    python citation_tracker.py --action close --session ...
"""

import argparse
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, List, Optional


SESSIONS_DIR = Path.home() / ".grants_sessions"
MIN_CONSENSUS_GAP_SECONDS = 1.0


def session_path(name: str) -> Path:
    return SESSIONS_DIR / f"{name}.json"


def load_session(name: str) -> Dict[str, Any]:
    p = session_path(name)
    if not p.exists():
        raise FileNotFoundError(f"Session not found: {name}")
    return json.loads(p.read_text(encoding="utf-8"))


def save_session(name: str, data: Dict[str, Any]) -> None:
    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
    session_path(name).write_text(json.dumps(data, indent=2), encoding="utf-8")


def now_iso() -> str:
    return datetime.now(timezone.utc).isoformat()


def now_ts() -> float:
    return datetime.now(timezone.utc).timestamp()


def action_start(name: str, topic: Optional[str]) -> Dict[str, Any]:
    if session_path(name).exists():
        raise FileExistsError(f"Session already exists: {name}")
    data: Dict[str, Any] = {
        "session": name,
        "topic": topic or "",
        "started_at": now_iso(),
        "ended_at": None,
        "consensus_tier": None,
        "consensus_searches": [],
        "consensus_received_log": [],
        "consensus_cited": [],
        "reporter_searches": [],
        "reporter_cited": [],
        "nosi_fetches": [],
        "counts": {
            "consensus_searches": 0,
            "consensus_received": 0,
            "consensus_cited": 0,
            "reporter_searches": 0,
            "reporter_projects": 0,
            "reporter_cited": 0,
            "nosi_fetches": 0,
            "nosi_succeeded": 0,
        },
    }
    save_session(name, data)
    return data


def action_record_consensus_search(name: str, facet: str, query: str, tier: Optional[str]) -> Dict[str, Any]:
    data = load_session(name)
    if data["consensus_searches"]:
        last_ts = data["consensus_searches"][-1].get("ts", 0)
        gap = now_ts() - last_ts
        if gap < MIN_CONSENSUS_GAP_SECONDS:
            raise RuntimeError(
                f"Consensus sequential discipline violated: {gap:.2f}s gap (need >= {MIN_CONSENSUS_GAP_SECONDS}s). "
                f"Wait {MIN_CONSENSUS_GAP_SECONDS - gap:.2f}s more."
            )
    if tier and not data["consensus_tier"]:
        data["consensus_tier"] = tier
    data["consensus_searches"].append({"facet": facet, "query": query, "tier": tier, "at": now_iso(), "ts": now_ts()})
    data["counts"]["consensus_searches"] += 1
    save_session(name, data)
    return data


def action_record_consensus_received(name: str, count: int) -> Dict[str, Any]:
    data = load_session(name)
    data["consensus_received_log"].append({"count": count, "at": now_iso()})
    data["counts"]["consensus_received"] += count
    save_session(name, data)
    return data


def action_record_consensus_cited(name: str, url: str) -> Dict[str, Any]:
    data = load_session(name)
    if any(p["url"] == url for p in data["consensus_cited"]):
        return data
    data["consensus_cited"].append({"url": url, "at": now_iso()})
    data["counts"]["consensus_cited"] += 1
    save_session(name, data)
    return data


def action_record_reporter_search(name: str, search_type: str, query: str, projects: int) -> Dict[str, Any]:
    data = load_session(name)
    data["reporter_searches"].append({"type": search_type, "query": query, "projects_returned": projects, "at": now_iso()})
    data["counts"]["reporter_searches"] += 1
    data["counts"]["reporter_projects"] += projects
    save_session(name, data)
    return data


def action_record_reporter_cited(name: str, project_num: str) -> Dict[str, Any]:
    data = load_session(name)
    if any(p["project_num"] == project_num for p in data["reporter_cited"]):
        return data
    data["reporter_cited"].append({"project_num": project_num, "at": now_iso()})
    data["counts"]["reporter_cited"] += 1
    save_session(name, data)
    return data


def action_record_nosi(name: str, nosi: str, status: str) -> Dict[str, Any]:
    data = load_session(name)
    data["nosi_fetches"].append({"nosi": nosi, "status": status, "at": now_iso()})
    data["counts"]["nosi_fetches"] += 1
    if status == "fetched" or status == "succeeded":
        data["counts"]["nosi_succeeded"] += 1
    save_session(name, data)
    return data


def action_status(name: str) -> Dict[str, Any]:
    return load_session(name)


def action_close(name: str) -> Dict[str, Any]:
    data = load_session(name)
    if data.get("ended_at") is None:
        data["ended_at"] = now_iso()
        save_session(name, data)
    return data


def action_list() -> List[Dict[str, Any]]:
    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
    out: List[Dict[str, Any]] = []
    for p in sorted(SESSIONS_DIR.glob("*.json")):
        try:
            d = json.loads(p.read_text(encoding="utf-8"))
            out.append({
                "session": d.get("session", p.stem),
                "topic": d.get("topic", ""),
                "tier": d.get("consensus_tier"),
                "counts": d.get("counts", {}),
                "ended_at": d.get("ended_at"),
            })
        except (OSError, json.JSONDecodeError):
            continue
    return out


def render_status_human(data: Dict[str, Any]) -> str:
    out: List[str] = []
    out.append(f"Session:           {data['session']}")
    out.append(f"Topic:             {data.get('topic', '(unset)')}")
    out.append(f"Consensus tier:    {data.get('consensus_tier') or '(not detected)'}")
    out.append(f"Started:           {data['started_at']}")
    out.append(f"Ended:             {data.get('ended_at') or '(active)'}")
    out.append("")
    c = data["counts"]
    out.append("Counts:")
    out.append(f"  Consensus searches:   {c['consensus_searches']}")
    out.append(f"  Consensus received:   {c['consensus_received']}")
    out.append(f"  Consensus cited:      {c['consensus_cited']}")
    out.append(f"  RePORTER searches:    {c['reporter_searches']}")
    out.append(f"  RePORTER projects:    {c['reporter_projects']}")
    out.append(f"  RePORTER cited:       {c['reporter_cited']}")
    out.append(f"  NOSI fetches:         {c['nosi_fetches']}  ({c['nosi_succeeded']} succeeded)")
    out.append("")
    out.append("Audit block (paste in DOCX Section 9):")
    out.append(
        f"  Three counts — Queries sent: {c['consensus_searches'] + c['reporter_searches']} "
        f"(Consensus {c['consensus_searches']}, RePORTER {c['reporter_searches']}). "
        f"Results received: {c['consensus_received'] + c['reporter_projects']} "
        f"(Consensus {c['consensus_received']} + RePORTER {c['reporter_projects']}). "
        f"Results cited: {c['consensus_cited'] + c['reporter_cited']} "
        f"(Consensus {c['consensus_cited']} + RePORTER {c['reporter_cited']}). "
        f"NOSI fetches: {c['nosi_succeeded']}/{c['nosi_fetches']} succeeded."
    )
    return "\n".join(out)


def render_list_human(rows: List[Dict[str, Any]]) -> str:
    if not rows:
        return "(no sessions)"
    out: List[str] = []
    out.append(f"{'session':<35s} {'tier':<5s} {'C-srch':>6s} {'C-rcvd':>6s} {'C-cit':>5s} {'R-srch':>6s} {'R-prj':>5s} {'R-cit':>5s} {'NOSI':>4s}")
    out.append("-" * 90)
    for r in rows:
        c = r["counts"]
        out.append(
            f"{r['session']:<35s} {(r.get('tier') or '—'):<5s} "
            f"{c.get('consensus_searches', 0):>6d} {c.get('consensus_received', 0):>6d} "
            f"{c.get('consensus_cited', 0):>5d} {c.get('reporter_searches', 0):>6d} "
            f"{c.get('reporter_projects', 0):>5d} {c.get('reporter_cited', 0):>5d} "
            f"{c.get('nosi_succeeded', 0):>4d}"
        )
    return "\n".join(out)


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument(
        "--action",
        required=True,
        choices=[
            "start", "record_consensus_search", "record_consensus_received", "record_consensus_cited",
            "record_reporter_search", "record_reporter_cited", "record_nosi",
            "status", "list", "close",
        ],
    )
    parser.add_argument("--session")
    parser.add_argument("--topic")
    parser.add_argument("--facet")
    parser.add_argument("--query")
    parser.add_argument("--tier")
    parser.add_argument("--count", type=int)
    parser.add_argument("--url")
    parser.add_argument("--type", dest="search_type")
    parser.add_argument("--projects", type=int)
    parser.add_argument("--project-num")
    parser.add_argument("--nosi")
    parser.add_argument("--status")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    try:
        if args.action == "start":
            result = action_start(args.session, args.topic)
        elif args.action == "record_consensus_search":
            result = action_record_consensus_search(args.session, args.facet, args.query, args.tier)
        elif args.action == "record_consensus_received":
            result = action_record_consensus_received(args.session, args.count)
        elif args.action == "record_consensus_cited":
            result = action_record_consensus_cited(args.session, args.url)
        elif args.action == "record_reporter_search":
            result = action_record_reporter_search(args.session, args.search_type, args.query, args.projects)
        elif args.action == "record_reporter_cited":
            result = action_record_reporter_cited(args.session, args.project_num)
        elif args.action == "record_nosi":
            result = action_record_nosi(args.session, args.nosi, args.status)
        elif args.action == "status":
            result = action_status(args.session)
        elif args.action == "close":
            result = action_close(args.session)
        else:
            result = action_list()
    except (FileNotFoundError, FileExistsError, RuntimeError) as e:
        print(f"error: {e}", file=sys.stderr); return 2

    if args.output == "json":
        print(json.dumps(result, indent=2, default=str))
    else:
        if args.action == "list":
            print(render_list_human(result))
        else:
            print(render_status_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

FILE:scripts/fiscal_year_calculator.py
#!/usr/bin/env python3
"""fiscal_year_calculator.py — Current NIH fiscal year + lookback window.

Stdlib-only. NIH FY = year of next Sep 30. October starts a new FY.

NIH RePORTER queries need a `fiscal_years` array. Hardcoding values produces
stale skill behavior over time. This script computes them at runtime.

Default window: current FY + 3 prior (4 years total). User can override.

Usage:
    python fiscal_year_calculator.py
    python fiscal_year_calculator.py --window 4 --output json
    python fiscal_year_calculator.py --reference-date 2026-10-15
    python fiscal_year_calculator.py --reference-date 2026-09-15
"""

import argparse
import json
import sys
from datetime import date, datetime
from typing import Any, Dict, List, Optional


def fiscal_year(reference: date) -> int:
    """Return the fiscal year that the given date falls within.

    NIH FY runs Oct 1 → Sep 30. FY 2026 = Oct 1 2025 → Sep 30 2026.
    """
    if reference.month >= 10:
        return reference.year + 1
    return reference.year


def calculate(reference: date, window_years: int) -> Dict[str, Any]:
    if window_years < 1:
        raise ValueError(f"--window must be >= 1, got {window_years}")
    current_fy = fiscal_year(reference)
    years = list(range(current_fy - window_years + 1, current_fy + 1))
    fy_start_date = date(current_fy - 1, 10, 1)
    fy_end_date = date(current_fy, 9, 30)
    return {
        "reference_date": reference.isoformat(),
        "calendar_year": reference.year,
        "current_fiscal_year": current_fy,
        "current_fy_start": fy_start_date.isoformat(),
        "current_fy_end": fy_end_date.isoformat(),
        "window_years": window_years,
        "window_fiscal_years": years,
        "reporter_payload_snippet": f'"fiscal_years": {json.dumps(years)}',
    }


def render_human(result: Dict[str, Any]) -> str:
    out: List[str] = []
    out.append(f"Reference date:        {result['reference_date']}")
    out.append(f"Calendar year:         {result['calendar_year']}")
    out.append(f"Current fiscal year:   FY {result['current_fiscal_year']} ({result['current_fy_start']} → {result['current_fy_end']})")
    out.append(f"Window:                {result['window_years']} years")
    out.append(f"FY values for query:   {result['window_fiscal_years']}")
    out.append("")
    out.append("Use in RePORTER POST body:")
    out.append(f"  {result['reporter_payload_snippet']}")
    return "\n".join(out)


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument("--reference-date", help="ISO date (default: today)")
    parser.add_argument("--window", type=int, default=4, help="Years to include (default: 4 = current + 3 prior)")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    if args.reference_date:
        try:
            ref = datetime.strptime(args.reference_date, "%Y-%m-%d").date()
        except ValueError:
            print(f"error: invalid --reference-date '{args.reference_date}', expected YYYY-MM-DD", file=sys.stderr); return 2
    else:
        ref = date.today()

    try:
        result = calculate(ref, args.window)
    except ValueError as e:
        print(f"error: {e}", file=sys.stderr); return 2

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(render_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

FILE:scripts/mechanism_matcher.py
#!/usr/bin/env python3
"""mechanism_matcher.py — NIH mechanism shortlist from career stage + scope + prelim.

Stdlib-only. The skill must NOT recommend mechanisms by career stage alone —
that's the most common mistake. Matching is 3-dimensional:

  (career_stage, project_scope, preliminary_data, environment) → mechanism shortlist

See references/nih_mechanism_matching.md for the full matrix.

NO LLM CALLS. Pure rule-based lookup.

Usage:
    python mechanism_matcher.py --career-stage early_career --prelim-data pilot \\
      --environment r01_eligible --scope single_site
    python mechanism_matcher.py --sample
"""

import argparse
import json
import sys
from typing import Any, Dict, List


VALID_CAREER_STAGES = ["pre_doctoral", "postdoctoral", "early_career", "independent", "senior"]
VALID_PRELIM = ["none", "pilot", "strong", "validated"]
VALID_ENVIRONMENTS = ["r01_eligible", "mid_tier", "resource_constrained", "industry_collab"]
VALID_SCOPES = ["solo_pilot", "single_site", "multi_aim", "multi_site", "program_scale", "high_risk"]


MECHANISMS = {
    "F31": {"budget": "$40-50k stipend + tuition × 2-3 yr", "prelim": "None-pilot", "best_for": "Pre-doc training"},
    "F32": {"budget": "$48-58k stipend × 2-3 yr", "prelim": "None-pilot", "best_for": "Postdoc training"},
    "T32": {"budget": "Institutional × 5-yr renewable", "prelim": "Institutional", "best_for": "Pre-doc/postdoc cohort"},
    "R03": {"budget": "$50k × 2 yr", "prelim": "None-pilot", "best_for": "Small pilot studies"},
    "R21": {"budget": "$275k DC × 2 yr", "prelim": "None-pilot", "best_for": "Pilot/exploratory R&D"},
    "R34": {"budget": "$450k × 3 yr", "prelim": "Pilot", "best_for": "Clinical trial planning"},
    "R61/R33": {"budget": "Phased ($250k + $500k × 2 yr)", "prelim": "Pilot", "best_for": "Phased innovation"},
    "K01": {"budget": "$100k × 5 yr", "prelim": "Pilot", "best_for": "Mentored research scientist"},
    "K08": {"budget": "$100k × 5 yr", "prelim": "Pilot", "best_for": "Mentored clinical scientist"},
    "K23": {"budget": "$100k × 5 yr", "prelim": "Pilot", "best_for": "Mentored patient-oriented research"},
    "K99/R00": {"budget": "$90k + $250k × 3 yr", "prelim": "Strong", "best_for": "Postdoc → independence transition"},
    "R01": {"budget": "$250-499k DC × 4-5 yr", "prelim": "Strong", "best_for": "Hypothesis-driven research"},
    "R15": {"budget": "$300k total × 3 yr", "prelim": "Pilot", "best_for": "Resource-constrained institutions only"},
    "R35": {"budget": "$750k × 5-8 yr", "prelim": "Validated", "best_for": "Senior outstanding investigators"},
    "P01": {"budget": "Multi-PI, $1-2M/yr × 5 yr", "prelim": "Validated", "best_for": "Program project (3+ PIs)"},
    "P30": {"budget": "Core facility funding × 5 yr", "prelim": "Validated", "best_for": "Multi-investigator core"},
    "U01": {"budget": "Cooperative agreement, varies", "prelim": "Strong-validated", "best_for": "Multi-site collaborative"},
    "DP1": {"budget": "$700k × 5 yr", "prelim": "None (visionary)", "best_for": "Pioneer Award — high-risk individual"},
    "DP2": {"budget": "$300k × 5 yr", "prelim": "Pilot", "best_for": "New Innovator — early-career high-risk"},
}


def match(career_stage: str, prelim_data: str, environment: str, scope: str) -> Dict[str, Any]:
    if career_stage not in VALID_CAREER_STAGES:
        raise ValueError(f"Invalid --career-stage. Pick from: {VALID_CAREER_STAGES}")
    if prelim_data not in VALID_PRELIM:
        raise ValueError(f"Invalid --prelim-data. Pick from: {VALID_PRELIM}")
    if environment not in VALID_ENVIRONMENTS:
        raise ValueError(f"Invalid --environment. Pick from: {VALID_ENVIRONMENTS}")
    if scope not in VALID_SCOPES:
        raise ValueError(f"Invalid --scope. Pick from: {VALID_SCOPES}")

    recommendations: List[Dict[str, Any]] = []
    warnings: List[str] = []

    # === Pre-doctoral ===
    if career_stage == "pre_doctoral":
        if prelim_data in ("none", "pilot") and scope in ("solo_pilot", "single_site"):
            recommendations.append({"mechanism": "F31", "rationale": "Pre-doc + pilot scope → NRSA individual fellowship"})
            recommendations.append({"mechanism": "T32", "rationale": "Pre-doc + institutional context → T32 training slot if available"})
        else:
            warnings.append("Pre-doctoral PI eligibility is limited. Consider co-investigator role on mentor's grant.")

    # === Postdoctoral ===
    elif career_stage == "postdoctoral":
        if prelim_data == "none":
            recommendations.append({"mechanism": "F32", "rationale": "Postdoc + no prelim → NRSA F32 fellowship"})
        if prelim_data == "pilot":
            recommendations.append({"mechanism": "F32", "rationale": "Postdoc + pilot data → F32"})
            recommendations.append({"mechanism": "K99/R00", "rationale": "Postdoc + pilot → K99/R00 candidate prep (top mechanism)"})
        if prelim_data == "strong":
            recommendations.append({"mechanism": "K99/R00", "rationale": "Strong prelim + postdoc-transitioning → K99/R00 is the highest-value mechanism for this stage"})

    # === Early career ===
    elif career_stage == "early_career":
        if prelim_data in ("none", "pilot"):
            if environment == "resource_constrained":
                recommendations.append({"mechanism": "R15", "rationale": "Resource-constrained env + early career → R15 (specifically targets this; R01 not competitive without env match)"})
            recommendations.append({"mechanism": "K01", "rationale": "Early career + pilot prelim → K-series for career development"})
            recommendations.append({"mechanism": "K08", "rationale": "Early career (clinical) + pilot → K08 mentored clinical"})
            recommendations.append({"mechanism": "K23", "rationale": "Early career patient-oriented → K23"})
            recommendations.append({"mechanism": "R21", "rationale": "Early career + pilot scope → R21 exploratory"})
        if prelim_data == "strong" and scope in ("single_site", "multi_aim"):
            recommendations.append({"mechanism": "R01", "rationale": "Strong prelim + independent scope → R01 (the qualifying R01)"})
            if scope == "multi_aim":
                warnings.append("Multi-aim R01 at early career is ambitious; consider mentored R01 with senior co-PI")
        if scope == "high_risk":
            recommendations.append({"mechanism": "DP2", "rationale": "Early career + high-risk → New Innovator (DP2)"})

    # === Independent ===
    elif career_stage == "independent":
        if prelim_data in ("none", "pilot") and scope == "solo_pilot":
            recommendations.append({"mechanism": "R03", "rationale": "Independent + pilot scope → R03 small pilot"})
            recommendations.append({"mechanism": "R21", "rationale": "Independent + exploratory → R21"})
            warnings.append("R01 NOT recommended without strong prelim — reviewers will reject as premature")
        if prelim_data == "strong":
            if scope == "multi_aim" or scope == "single_site":
                recommendations.append({"mechanism": "R01", "rationale": "Independent + strong prelim + hypothesis-driven → R01 (standard)"})
            if scope == "multi_site":
                recommendations.append({"mechanism": "U01", "rationale": "Multi-site + strong prelim → U01 cooperative agreement"})
        if prelim_data == "validated" and scope == "multi_site":
            recommendations.append({"mechanism": "U01", "rationale": "Validated + multi-site → U01"})
            recommendations.append({"mechanism": "R01", "rationale": "Validated + multi-site → R01 alternate path"})
        if scope == "high_risk":
            recommendations.append({"mechanism": "DP1", "rationale": "High-risk + independent → Pioneer Award"})
        if scope == "single_site" and prelim_data == "pilot":
            recommendations.append({"mechanism": "R34", "rationale": "Clinical trial planning + pilot → R34"})

    # === Senior PI ===
    elif career_stage == "senior":
        if scope == "program_scale":
            recommendations.append({"mechanism": "R35", "rationale": "Senior + program scope → R35 outstanding investigator (unrestricted by topic)"})
            recommendations.append({"mechanism": "P01", "rationale": "Senior + multi-PI program → P01"})
        if scope == "multi_site":
            recommendations.append({"mechanism": "U01", "rationale": "Senior + multi-site → U01"})
        if "core" in scope or scope == "program_scale":
            recommendations.append({"mechanism": "P30", "rationale": "Senior + core facility → P30"})
        if scope in ("multi_aim", "single_site") and prelim_data in ("strong", "validated"):
            recommendations.append({"mechanism": "R01", "rationale": "Senior PI continuing R01 portfolio"})

    if not recommendations:
        warnings.append("No mechanism shortlist matched. Likely inputs are inconsistent (e.g., pre-doctoral + senior-scope). Re-check the answer combinations.")

    # Enrich with mechanism details
    enriched = []
    for rec in recommendations:
        m = rec["mechanism"]
        info = MECHANISMS.get(m, {})
        enriched.append({
            "mechanism": m,
            "rationale": rec["rationale"],
            "budget": info.get("budget", ""),
            "prelim_needed": info.get("prelim", ""),
            "best_for": info.get("best_for", ""),
        })

    return {
        "inputs": {
            "career_stage": career_stage,
            "prelim_data": prelim_data,
            "environment": environment,
            "scope": scope,
        },
        "recommendations": enriched,
        "warnings": warnings,
        "program_officer_note": "MANDATORY: contact program officer at top institute before writing. Find via https://www.nih.gov/institutes-nih/list-nih-institutes-centers-offices",
    }


def render_human(result: Dict[str, Any]) -> str:
    out: List[str] = []
    out.append("Inputs:")
    for k, v in result["inputs"].items():
        out.append(f"  {k}: {v}")
    out.append("")
    if result["recommendations"]:
        out.append(f"Recommended mechanisms ({len(result['recommendations'])}):")
        for r in result["recommendations"]:
            out.append(f"")
            out.append(f"  → {r['mechanism']}")
            out.append(f"    Rationale: {r['rationale']}")
            out.append(f"    Budget:    {r['budget']}")
            out.append(f"    Prelim:    {r['prelim_needed']}")
            out.append(f"    Best for:  {r['best_for']}")
    else:
        out.append("No mechanisms recommended (see warnings)")
    if result["warnings"]:
        out.append("")
        out.append("Warnings:")
        for w in result["warnings"]:
            out.append(f"  ! {w}")
    out.append("")
    out.append(result["program_officer_note"])
    return "\n".join(out)


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument("--career-stage", choices=VALID_CAREER_STAGES)
    parser.add_argument("--prelim-data", choices=VALID_PRELIM)
    parser.add_argument("--environment", choices=VALID_ENVIRONMENTS)
    parser.add_argument("--scope", choices=VALID_SCOPES)
    parser.add_argument("--sample", action="store_true")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    if args.sample:
        result = match("early_career", "pilot", "r01_eligible", "single_site")
    elif args.career_stage and args.prelim_data and args.environment and args.scope:
        try:
            result = match(args.career_stage, args.prelim_data, args.environment, args.scope)
        except ValueError as e:
            print(f"error: {e}", file=sys.stderr); return 2
    else:
        parser.print_help(); return 0

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(render_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: inbox-setup
description: "One-time setup skill that builds a personalized inbox triage knowledge base via interactive interview. Interviews the user about their email patterns, business context, reply style, and priorities using grill-me discipline (one question at a time, forcing format where possible, dependency-ordered, each question explains why I'm asking), then generates the knowledge base files that power the companion 'inbox-triage' skill. Run this once before using inbox-triage for the first time. Re-run when business, pricing, or priorities change significantly. Triggers: 'set up my inbox', 'configure inbox triage', 'set up my email system', 'configure email triage', 'build my email knowledge base', 'initialize email management', 'set up inbox triage', 'onboard email triage', or any variation where someone wants to get the email triage system running for the first time."
license: MIT
metadata:
  source_spec: "megaprompts/06-inbox-setup-megaprompt.md"
  build_pattern: "Path B (direct conversion)"
  paired_with: "inbox-triage (shared 7-file KB contract)"
  version: 1.0.0
---

# Inbox-Setup — Email Triage Onboarding

> **Paired with `inbox-triage`.** This skill writes the 7-file knowledge base at `WORKSPACE/Email/` that `inbox-triage` reads on every run. The file contracts (names, sections, fields) MUST match between the two skills exactly. See [`references/kb_file_contract.md`](references/kb_file_contract.md).

Run once (or re-run when business/priorities change). Interview the user about their email patterns, business context, reply style, and priorities. Generate the structured knowledge base in `WORKSPACE/Email/` that captures everything `inbox-triage` needs to process the inbox effectively.

## Invocation Triggers

- "set up my inbox"
- "configure inbox triage"
- "set up my email system"
- "configure email triage"
- "build my email knowledge base"
- "initialize email management"
- "set up inbox triage"
- "onboard email triage"

## Conduct Discipline

**Do NOT generate all files at once.** Walk through the 8 sections one at a time. Each section commits its file(s) before moving on. Partial completion (e.g., user drops off mid-interview) still produces a usable partial KB.

Grill-me discipline applies throughout:

- **One question per turn.** Never bundle. Even across section boundaries.
- **"Why I'm asking" on every question** — so users can answer well.
- **Forcing format where possible.** Multi-choice > open-ended.
- **Dependency-ordered.** Q2 depends on Q1; downstream sections depend on upstream.

See [`references/grill_me_section_walk.md`](references/grill_me_section_walk.md) for the 8-section discipline detail.

## Knowledge Base Contract — Files To Produce

Exactly these files at `WORKSPACE/Email/`:

| File | Purpose | Required? |
|---|---|---|
| `email-taxonomy.md` | Classification system + report preferences | **Yes** |
| `email-patterns.md` | Reply voice, tone, templates, hard rules | **Yes** |
| `evaluation-framework.md` | Decision tree for opportunity emails | Only if user receives pitches/opportunities |
| `rate-card.md` | Pricing, terms, negotiation posture | Only if user has pricing |
| `blocklist.md` | Auto-skip senders + learned decline patterns | **Yes** (seeded, grows over time) |
| `tracker.md` | Active follow-ups, overdue items, deadlines | **Yes** (starts mostly empty) |
| `triage-log/` | Directory for per-run logs | **Yes** (created empty) |

The contract is identical to what `inbox-triage` expects — see [`references/kb_file_contract.md`](references/kb_file_contract.md) for the full spec.

## Stop Condition (Full Interview)

~25–31 questions total across the 8 sections (depending on skip-logic). Hard ceiling: 35 questions including all sub-clarifications. Section 4 (Evaluation Framework) is skipped entirely when Section 1 surfaced no opportunity-email category, dropping the total by 6 questions and the rate-card file. After Section 8's confirmation + handoff message, intake is closed — **never re-open it**. To change preferences later, the user re-runs the skill (which detects existing files and asks per-file: replace / merge / skip). The grill-me one-at-a-time rule applies across section boundaries: do NOT batch questions even when moving from S{n} to S{n+1}.

## Section 1: The Big Picture

Six grill-me questions, one at a time:

- **S1.Q1:** "What do you do? Give me your role and business in 1–2 sentences. *Why I'm asking:* Context shapes what email patterns to expect — a solo creator's inbox looks nothing like an enterprise PM's."
- **S1.Q2:** "What dominates your inbox? Pick the top 1–2: sales pitches / client work / internal team / newsletters / customer support / financial / other. *Why I'm asking:* Dominant categories drive the taxonomy."
- **S1.Q3:** "Rough volume split — e.g., '60% business inquiries, 20% ops, 20% noise'. *Why I'm asking:* The split tells me where to focus triage effort."
- **S1.Q4:** "Which email address(es) should triage cover? *Why I'm asking:* If multiple, I'll set up per-address taxonomies."
- **S1.Q5:** "Run frequency: once daily / 2x daily / 3x daily / on-demand only? *Why I'm asking:* Drives the default search window in triage (9h overlap for 2x/day)."
- **S1.Q6:** "Anyone helping manage email — assistant, VA, team — or solo? *Why I'm asking:* Persona handling differs for delegated inboxes."

**Action:** Build mental model. Do NOT write files yet. Note whether opportunity emails are a category (drives S4 skip-logic).

## Section 2: Email Categories

Propose 5–7 categories based on Section 1 — pre-recommend a subset, not the whole template menu:

- New Opportunities
- Active Conversations
- Action Required
- Financial
- Important/Personal
- Informational
- Ignore/Low Priority

Then three forcing questions, one at a time:

- **S2.Q1:** "Here's my proposed taxonomy: [list]. Does this match your inbox reality — yes / mostly / no? *Why I'm asking:* If 'no', I need to redo the taxonomy before any other section makes sense."
- **S2.Q2:** "Missing categories? List them. (Skip if none.) *Why I'm asking:* Missing categories produce uncategorized emails downstream, which hurts triage quality."
- **S2.Q3:** "Which category takes the MOST time per email? *Why I'm asking:* That's where draft-reply effort needs to focus most."

**Action:** Generate `email-taxonomy.md` with categories, signals (for each: trigger phrases / sender patterns / subject markers), and default actions per category.

## Section 3: Reply Style & Voice

Six grill-me questions plus the critical sample request:

- **S3.Q1:** "Register: formal / casual / in-between? *Why I'm asking:* Calibrates default voice; we'll refine from samples next."
- **S3.Q2:** "Three communication pet peeves — phrases you hate, openings you avoid. *Why I'm asking:* I treat these as forbidden tokens in drafts."
- **S3.Q3:** "Phrases or sign-offs you always use — list as many as come to mind. *Why I'm asking:* These are your voice fingerprints."
- **S3.Q4:** "Different persona for different contexts — e.g., assistant replies as you? *Why I'm asking:* Persona context changes pronoun + signature handling."
- **S3.Q5:** "Typical reply length — one-liner / short paragraph / longer? *Why I'm asking:* Length is the easiest voice signal to get wrong."
- **S3.Q6:** "Hard rules — never X / always Y? (E.g., never emojis, always reply within 24h, never take calls without context.) *Why I'm asking:* Hard rules are enforced as non-negotiable in every draft."

### S3.SAMPLES (the critical highest-quality input)

> **Paste 3–5 real sent emails from your inbox.**
>
> *Why I'm asking:* Self-description of voice is unreliable. Real samples are the best signal — I'll analyze them for voice patterns that supplement everything above. Use `scripts/voice_sample_analyzer.py` to extract patterns deterministically.

If user runs a business: also ask about media kits, rate sheets, standard pitches, repeated replies.

**Action:** Generate `email-patterns.md` with tone description (with do/don't examples), persona rules, templates, signatures, hard rules. See [`references/voice_calibration.md`](references/voice_calibration.md) for the sample-extraction discipline.

## Section 4: Evaluation Framework (Conditional)

**Skip-logic:** only run this section if Section 1 surfaced opportunity emails as a meaningful inbox category. Otherwise jump straight to Section 5.

Six grill-me questions, one at a time:

- **S4.Q1:** "First thing you check when pitched something — give me your gut filter. *Why I'm asking:* That's the top of the decision tree."
- **S4.Q2:** "Three instant deal-breakers — things that make you decline immediately. *Why I'm asking:* These become PASS-auto signals."
- **S4.Q3:** "Three things that make you immediately interested. *Why I'm asking:* These become TAKE-IT signals."
- **S4.Q4:** "Standard pricing / terms — or 'no fixed pricing' if you negotiate every time. *Why I'm asking:* If you have a rate card, I'll generate one; if not, I'll skip."
- **S4.Q5:** "Negotiation posture: firm / flexible / depends on context? *Why I'm asking:* Drives draft tone on counter-offers."
- **S4.Q6:** "VIP senders or organizations that always get engagement — list names or domains. *Why I'm asking:* VIP list bypasses normal PASS filters."

**Action:** Generate `evaluation-framework.md` (decision tree + recommendation categories + VIP list) AND `rate-card.md` if pricing exists.

## Section 5: Blocklist & Patterns

Three grill-me questions, one at a time:

- **S5.Q1:** "Senders or domains to always skip — list them. (Skip if none.) *Why I'm asking:* Auto-blocklist saves the most time per run."
- **S5.Q2:** "Patterns in emails you always delete — e.g., 'unsubscribe' links from specific marketers, recruiter cold outreach, newsletters? *Why I'm asking:* Patterns let triage auto-skip variants without exact-match maintenance."
- **S5.Q3:** "Specific companies / recruiters / newsletters wasting time — list any. *Why I'm asking:* These seed the blocklist; triage will add more as you override decisions."

**Action:** Generate `blocklist.md` (auto-maintained by triage thereafter).

## Section 6: Current State

Three grill-me questions, one at a time:

- **S6.Q1:** "Active threads you're tracking — list with one-line context each. (Skip if none.) *Why I'm asking:* These become tracker entries so triage knows existing context."
- **S6.Q2:** "Overdue replies — anything you should have responded to but haven't? *Why I'm asking:* Triage flags these as priority every run until resolved."
- **S6.Q3:** "Time-sensitive items with deadlines — list with dates. *Why I'm asking:* Tracker enforces deadlines and surfaces them as overdue at the right time."

**Action:** Generate `tracker.md` with active follow-ups table, overdue section, resolved section (empty), update log (empty). Also create empty `triage-log/` directory.

## Section 7: Report Preferences

Three grill-me questions, one at a time:

- **S7.Q1:** "Delivery format — pick one: email draft to self / file in workspace / chat summary only. *Why I'm asking:* The triage report goes here every run."
- **S7.Q2:** "Detail level — pick one: 30-second scan / detailed breakdown / both (scan first, expand on request). *Why I'm asking:* Affects report length."
- **S7.Q3:** "Anything always shown first — e.g., overdue payments, VIP messages? *Why I'm asking:* Custom 'top-of-report' rules surface what you care about above standard sections."

**Action:** Save these preferences into `email-taxonomy.md` under a "Report Preferences" section.

## Section 8: Confirmation & Handoff

List every file created with one-sentence summary. Then:

> Your triage system is ready. Run the **inbox-triage** skill to process your inbox. First runs need oversight — system learns from your edits and overrides.

Remind: re-run this setup anytime business/pricing/priorities change.

Run `scripts/kb_validator.py --workspace WORKSPACE` to confirm the 7-file contract is satisfied before final handoff.

## Privacy Boundary

**Never persist passwords, full account numbers, SSNs, or other sensitive credentials in knowledge base files.** If the user volunteers such info during the interview, acknowledge it but don't store it; the relevant KB file gets `[stored separately by user]` in its place.

## Re-Run Behavior

Re-running on an existing setup:

1. Detect `WORKSPACE/Email/`
2. For each existing file, ask per-file: **replace / merge / skip**
3. Walk only the sections whose files the user chose to update
4. Skip sections whose files the user kept

## Error Handling

| Situation | Behavior |
|---|---|
| Workspace inaccessible | Stop. Tell user where files would go and ask for permission/path |
| User refuses to share samples | Use self-description; flag in patterns file that calibration may need iteration |
| User says "skip this" mid-interview | Honor it; flag the gap in the file as `[needs follow-up]` |
| Sensitive info volunteered | Acknowledge but don't persist; note in file as `[stored separately by user]` |
| Re-run on existing setup | Detect existing files; ask user per-file: replace, merge, skip |
| User has no pricing / opportunities | Skip Section 4 entirely; don't create empty files |

## Portability

- **Claude Code CLI:** Native — writes markdown files directly to filesystem.
- **Claude.ai web:** Works with project files / artifacts. Document the alternate path: generate files as artifacts, instruct user to save to their workspace, or use connected file system if available.

## Tooling

| Script | Role |
|---|---|
| `scripts/kb_validator.py` | Validates the 7-file KB output (required files present, conditional files only if their sections ran, headers + structure correct). |
| `scripts/section_progress_tracker.py` | JSON-backed walk state at `~/.inbox_setup_sessions/<session>.json`. Tracks active section, answered questions, committed files. |
| `scripts/voice_sample_analyzer.py` | Extracts voice patterns from pasted sent-email samples — opening phrases, sign-offs, length distribution, register markers. |

## References

- [`references/kb_file_contract.md`](references/kb_file_contract.md) — the canonical 7-file contract (write perspective; mirror lives in `inbox-triage/references/`)
- [`references/grill_me_section_walk.md`](references/grill_me_section_walk.md) — 8-section discipline, skip-logic, commit-per-section
- [`references/voice_calibration.md`](references/voice_calibration.md) — sample-based voice extraction theory + anti-patterns

## Anti-Patterns To Reject

- Generating all files at once instead of walking through sections
- Asking all questions in one batch
- Hardcoded provider references (Gmail-only thinking)
- Persisting sensitive credentials in knowledge base
- Skipping the "why this question matters" explanation
- Skipping the sample-emails ask for voice (it's the highest-quality input)
- Overwriting existing files without consent on re-run
- Forcing creation of `rate-card.md` or `evaluation-framework.md` when they don't apply

---

**Version:** 1.0.0
**Source spec:** [`megaprompts/06-inbox-setup-megaprompt.md`](../../../../megaprompts/06-inbox-setup-megaprompt.md)
**Build pattern:** Path B (direct conversion). Paired with `inbox-triage`.

FILE:references/grill_me_section_walk.md
# Grill-Me Section Walk Discipline

This reference answers exactly one decision: **how does inbox-setup walk 8 sections of ~25-31 questions without violating grill-me discipline, and what makes the discipline survive heavy intake?**

## The Core Tension

Capture's grill-me is **max-1 question** per dump (light intake). Inbox-setup is **25-31 questions across 8 sections** (heavy intake). At that scale, the one-question-at-a-time rule is easy to break — the interviewer is tempted to batch, the user is tempted to dump everything at once.

The discipline survives because:

1. **Section boundaries** create natural commit points
2. **Skip-logic** removes ~6 questions when irrelevant (Section 4)
3. **Per-section file writes** make partial completion still useful
4. **Forcing format** keeps questions answerable in seconds

## The Four Rules

### Rule 1: One Question Per Turn — Across Section Boundaries

The rule does NOT relax when moving between sections. After S2.Q3 commits `email-taxonomy.md`, ask S3.Q1 alone — not "S3.Q1 and S3.Q2 since you already know your voice."

**Why:** the user is fatigued by question 18; bundling 3 at once produces shallower answers. Better to be slow than to lose answer quality on the high-leverage voice + framework questions.

### Rule 2: "Why I'm Asking" On Every Single Question

Without the rationale, users either:
- Skip past the question thinking it's optional
- Answer minimally because they don't know what's at stake
- Misunderstand the depth needed

The rationale is short (1-2 sentences) and concrete ("This becomes a forbidden token in drafts" beats "this helps me understand your style").

### Rule 3: Forcing Format > Open-Ended

| ✅ Forcing | ❌ Open-ended |
|---|---|
| "Run frequency: once daily / 2x daily / 3x daily / on-demand only?" | "How often should I run?" |
| "Does this taxonomy match: yes / mostly / no?" | "What do you think of this taxonomy?" |
| "Register: formal / casual / in-between?" | "Describe your tone." |

Open-ended works for: pet peeves (S3.Q2), sign-offs (S3.Q3), hard rules (S3.Q6), VIP list (S4.Q6), tracker entries (S6.Q1) — where the answer space is genuinely unbounded and forcing format would harm signal.

### Rule 4: Commit Per Section, Not End-Of-Interview

After Section 2's 3 questions: write `email-taxonomy.md`. Do NOT wait until Section 8 to write all files at once.

**Why:** if the user drops off after Section 4 (~16 questions in), the user has a useful partial KB (taxonomy + patterns + framework + rate card). If files were batched at the end, drop-off leaves nothing.

## The 8 Sections at a Glance

| Section | Questions | Skip-Logic | Files Written at End |
|---|---:|---|---|
| 1. The Big Picture | 6 | always run | (none — build mental model) |
| 2. Email Categories | 3 | always run | `email-taxonomy.md` |
| 3. Reply Style & Voice | 6 + samples | always run | `email-patterns.md` |
| 4. Evaluation Framework | 6 | skipped if no opportunity category in S1 | `evaluation-framework.md` + `rate-card.md` (cond) |
| 5. Blocklist & Patterns | 3 | always run | `blocklist.md` |
| 6. Current State | 3 | always run | `tracker.md` + `triage-log/` dir |
| 7. Report Preferences | 3 | always run | appended to `email-taxonomy.md` |
| 8. Confirmation & Handoff | 0 (summary) | always run | (no file write; handoff message) |

**Total: 24 + 6 conditional = 30 max** (or 24 if S4 skipped). Hard ceiling 35 includes sub-clarifications.

## Skip-Logic Detail

### Section 4 Skip

After S1.Q2 ("what dominates your inbox?"), if the answer does NOT include:
- "sales pitches" / "opportunities" / "client work proposals"

Then mark S4 as skipped. State to user:

> Skipping Section 4 (Evaluation Framework) since your inbox doesn't include pitches/opportunities. Moving to Section 5.

The user CAN override: "Actually I do get opportunity emails — run that section." Honor the override.

### Per-Question Conditional Skips

Some individual questions have "(Skip if none)" suffix:

- S2.Q2 (missing categories?) — skip if user says all listed
- S5.Q1 (skip-senders?) — skip if user has none yet
- S6.Q1 (active threads?) — skip if user has none
- S6.Q2 (overdue?) — skip if user has none
- S6.Q3 (deadlines?) — skip if user has none

These skips ALSO commit to the file (with empty section) so triage knows the section was considered, not forgotten.

## Per-Section File Commit Pattern

```
1. Ask all questions in Section N (one at a time)
2. Synthesize answers into structured file content
3. Write file(s) at WORKSPACE/Email/{filename}
4. Confirm to user: "✓ Section N complete. {file(s)} committed."
5. Record in session tracker:
     python scripts/section_progress_tracker.py \
       --action record_section_done --session NAME \
       --section N --files "{filename}"
6. Move to Section N+1's first question.
```

## Re-Run Mode

Detect re-run when `WORKSPACE/Email/email-taxonomy.md` exists.

Walk the user through per-file consent:

```
Found email-taxonomy.md from 2026-03-04 (45 days ago).
Replace / merge / skip?
- replace: rewrite from new interview answers
- merge: keep existing categories, add new ones from this run
- skip: leave file as-is; move to next file
```

Walk only the sections whose files the user chose to replace or merge. If user chose skip for a file, do NOT re-ask that section's questions.

## Sample-Collection Discipline (S3.SAMPLES)

The sample-emails ask is **the highest-quality voice signal** the skill has. It is NOT optional from a quality standpoint, but it IS skippable by user choice.

**Discipline:**

1. Ask for 3-5 real sent emails. Frame it as "the best signal I have."
2. If user pastes them: run `scripts/voice_sample_analyzer.py` and incorporate the output into `email-patterns.md` under "Voice Patterns (Extracted from Samples)."
3. If user refuses: use S3.Q1-Q6 self-description only. Flag in `email-patterns.md`:
   > `[calibration may need iteration — voice samples not collected during setup. First few triage runs will likely produce drafts that need editing; the system learns from your edits.]`
4. Never proceed past Section 3 without either samples OR explicit user-skip + flag.

## Anti-Patterns To Reject

- Asking S1.Q1-Q3 in one message ("tell me your role, what dominates your inbox, and rough volume split")
- Asking S2.Q1 without "Why I'm asking"
- Writing all 7 files at end of S8 (no per-section commit)
- Asking S4 questions when no opportunities surfaced in S1
- Asking S5.Q1 again when user already said "I have no blocklist yet" in S1
- Forcing closed-format on genuinely open questions (e.g., "Pet peeves: a) clichés b) emojis c) other" — kills signal)
- Skipping the rationale ("Why I'm asking") to "save time"
- Skipping the sample ask in S3
- Re-running and overwriting existing files without per-file consent

## Citations

The grill-me discipline this reference enforces is canonical in this repo. See:

- [`engineering/grill-me/`](../../../../engineering/grill-me/) — the source skill that formalized the discipline
- Matt Pocock's original grill-me skill (MIT)
- This repo's PR #657 cross-skill consistency audit, which verified the discipline transfers consistently across all intake-having skills (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13)

FILE:references/kb_file_contract.md
# Knowledge Base File Contract (Write Perspective)

This reference answers exactly one decision: **what 7 files must `inbox-setup` produce, in what structure, so that `inbox-triage` can read them without ambiguity?**

This is the integration boundary between the paired skills. Any drift breaks the pair. PR #657's cross-skill consistency audit verified that the 7 KB filenames align verbatim between the two megaprompts; this reference is the canonical write-side spec. A mirror lives at `inbox-triage/references/kb_file_contract.md` (read perspective).

## The 7 Files at `WORKSPACE/Email/`

| File | Required? | Triggered by | Triage uses for |
|---|---|---|---|
| `email-taxonomy.md` | yes | Section 2 + Section 7 | classification + report preferences |
| `email-patterns.md` | yes | Section 3 | reply voice + templates + hard rules |
| `evaluation-framework.md` | conditional | Section 4 (only if S1 surfaced opportunities) | TAKE-IT / WORTH / PASS / FLAG decisions |
| `rate-card.md` | conditional | Section 4 (only if user has pricing) | negotiation posture + counter-offers |
| `blocklist.md` | yes (seeded) | Section 5 | auto-skip senders + decline patterns |
| `tracker.md` | yes (seeded) | Section 6 | active follow-ups + deadlines |
| `triage-log/` | yes (empty dir) | Section 6 | per-run logs (populated by triage) |

## File Specs (Write Side)

### email-taxonomy.md (required)

```markdown
# Email Taxonomy

## Categories

### {Category Name}
- Signals: {trigger phrases, sender patterns, subject markers}
- Default action: {classify / draft-reply / skip / flag-for-review}
- Typical volume: {N% of inbox}

### {Category 2}
...

## Report Preferences

- Delivery format: {email-draft-to-self | file-in-workspace | chat-summary-only}
- Detail level: {30-second-scan | detailed-breakdown | both}
- Always-shown-first: {overdue payments | VIP messages | custom rules}
```

**Generated at:** end of Section 2 (categories) + appended at end of Section 7 (Report Preferences).

### email-patterns.md (required)

```markdown
# Email Patterns

## Voice Register
{formal | casual | in-between}

## Pet Peeves (Forbidden Tokens)
- {phrase 1}
- {phrase 2}
- {phrase 3}

## Sign-Offs (Voice Fingerprints)
- {sign-off 1}
- {sign-off 2}
- ...

## Persona Context
{single-user | delegated (assistant replies as user) | multi-persona}

## Typical Reply Length
{one-liner | short-paragraph | longer}

## Hard Rules (Non-Negotiable in Every Draft)
- Never: {X}
- Always: {Y}

## Voice Patterns (Extracted from Samples)
- Opening phrases observed: {list}
- Sentence length distribution: {short / medium / long mix}
- Casual / formal markers: {list}

## Templates (Repeated Replies)
- {template 1 name}: {body}
- {template 2 name}: {body}
```

**Generated at:** end of Section 3. The "Voice Patterns" subsection comes from `scripts/voice_sample_analyzer.py` if samples were provided; otherwise marked `[calibration may need iteration]`.

### evaluation-framework.md (conditional)

```markdown
# Evaluation Framework (Opportunity Emails)

## Gut Filter (First Check)
{user's gut filter from S4.Q1}

## TAKE-IT Signals
- {signal 1}
- {signal 2}
- {signal 3}

## PASS Signals (Instant Deal-Breakers)
- {deal-breaker 1}
- {deal-breaker 2}
- {deal-breaker 3}

## Decision Tree

1. If sender in VIP list → TAKE IT (skip filter)
2. If any PASS signal matches → PASS (auto-decline draft)
3. If all TAKE-IT signals match → TAKE IT (auto-engage draft)
4. If partial TAKE-IT match → WORTH CONSIDERING
5. If unusual / ambiguous → FLAG FOR REVIEW

## VIP List (Bypass PASS Filters)
- {sender / domain 1}
- {sender / domain 2}
- ...

## Negotiation Posture
{firm | flexible | depends-on-context}
```

**Generated at:** end of Section 4. Skipped entirely if S1 surfaced no opportunity-email category.

### rate-card.md (conditional)

```markdown
# Rate Card

## Standard Pricing
- {service / offering 1}: {price}
- {service / offering 2}: {price}

## Terms
- Payment: {net X days | upfront | milestone}
- Revisions included: {N}
- Rush fee: {Y%}

## Negotiation Posture
{firm | flexible | depends-on-context}

## Counter-Offer Patterns
- If they offer < {floor}: {how to counter}
- If timeline is tight: {how to counter}
```

**Generated at:** end of Section 4. Skipped if user has no fixed pricing (S4.Q4 = "no fixed pricing").

### blocklist.md (required, seeded)

```markdown
# Blocklist

## Sender / Domain Auto-Skip
- {sender 1}: {reason} — added {date}
- {domain 1}: {reason} — added {date}

## Decline Patterns (Pattern-Match Auto-Skip)
- "{pattern phrase 1}": {reason}
- "{pattern phrase 2}": {reason}

## Recently Removed (User Overrode)
- {sender}: removed on {date} — user override
```

**Generated at:** end of Section 5 (initial seed). `inbox-triage` appends new declines + observed patterns on every run.

### tracker.md (required, seeded)

```markdown
# Tracker

## Active Follow-Ups

| Item | Context | Deadline | Status |
|---|---|---|---|
| {thread} | {one-line context} | {date} | pending |
| ... | ... | ... | ... |

## Overdue
- {thread}: missed deadline {date} — {context}

## Resolved (Recent)

## Update Log
- {date}: {what changed} — by {triage run | user}
```

**Generated at:** end of Section 6 (initial seed from S6.Q1-Q3). `inbox-triage` updates on every run.

### triage-log/ (required, empty directory)

Empty directory created at end of Section 6. `inbox-triage` writes per-run logs to `triage-log/<YYYY-MM-DD>-<run-label>.md`.

## Validation

Run `scripts/kb_validator.py --workspace WORKSPACE` after Section 8 confirmation. It checks:

- All required files exist
- Conditional files exist iff their triggering section ran
- Each file has the expected H1 + section structure
- `triage-log/` is a directory (not a file)

## Why This Contract Matters

`inbox-triage` halts with a clear error if any required core file is missing. The contract is the integration boundary — both skills can be developed and tested independently, but they must agree on the file shape.

When updating either skill: update both sides of the contract simultaneously, or use `/cs:grill-with-docs` to detect drift between the two megaprompts before drift reaches code.

FILE:references/voice_calibration.md
# Voice Calibration — Extracting Style from Sent-Email Samples

This reference answers exactly one decision: **why are real sent-email samples the highest-quality voice signal for inbox-triage's draft generation, and how does the skill extract usable patterns from them deterministically?**

Pair with `scripts/voice_sample_analyzer.py` for the deterministic extraction.

## The Core Claim

Users describe their own voice unreliably. They say "professional but warm" and their actual emails alternate between three sentences of formal hedging and "lol no" replies to colleagues. They say "I'm pretty casual" and their actual emails open with "I hope this email finds you well."

> **What users say about their voice ≠ what their voice actually is.**

Real sent emails resolve this gap. They show:

- Real opening phrases (not "I hope this email finds you well" if the user doesn't actually say that)
- Real sentence length (not "short" if the actual average is 3 paragraphs)
- Real sign-offs (not "thanks!" if the actual ratio is 80% "—Alex" and 20% no sign-off)
- Real register (the variation across recipient type that self-description misses)

## What S3.SAMPLES Asks For

> "Paste 3–5 real sent emails from your inbox."

3-5 is the operational sweet spot:

- **<3:** too few to detect patterns vs anomalies
- **3-5:** enough variance to detect baseline + adaptations
- **>5:** marginal signal, diminishing returns; takes longer to extract

The samples should span the user's typical email mix — at least one to a peer, one external, one transactional. If the user pastes 5 identical newsletters, ask for more variety.

## What `voice_sample_analyzer.py` Extracts

Deterministic stdlib analysis (no LLM):

1. **Opening phrases** — first 5-10 tokens of each sample's body. Pattern frequency.
2. **Sign-offs** — last 5-10 tokens of each sample. Pattern frequency.
3. **Sentence length distribution** — short (<10 words) / medium (10-25) / long (>25) ratio.
4. **Register markers** — counts of casual indicators ("lol", "yeah", "tbh", "btw") vs formal indicators ("I would like to", "please find", "kindly").
5. **Hedging frequency** — counts of softeners ("maybe", "I think", "perhaps", "just"). High hedging is a voice fingerprint.
6. **Personal pronouns** — "I" vs "we" frequency. Tells whether user writes as solo or representing a team.
7. **Punctuation patterns** — em-dash usage, exclamation marks, ellipses.

Output is a structured patterns block that goes into `email-patterns.md` under "Voice Patterns (Extracted from Samples)."

## How Self-Description (S3.Q1-Q6) Combines With Samples

Self-description and samples are **complementary**, not competing:

- **Self-description wins for:** hard rules (S3.Q6 — "never emojis"), forbidden tokens (S3.Q2 — "phrases I hate"), explicit sign-offs (S3.Q3 — what the user remembers using).
- **Samples win for:** baseline register, actual sentence length, opening phrases, register adaptation across recipient types.

In `email-patterns.md`, the two are combined: self-described preferences are stated as hard rules; sample-extracted patterns supplement as baseline behavior.

## When Samples Aren't Available

If the user refuses to paste samples (privacy, time, or just "I'd rather not"):

1. Honor the choice. Don't push back twice.
2. Use S3.Q1-Q6 self-description only.
3. Flag in `email-patterns.md`:

```markdown
## Voice Calibration Status

[calibration may need iteration — voice samples not collected during setup.
First few triage runs will likely produce drafts that need editing; the
system learns from your edits and overrides. Re-run inbox-setup with
samples when you're ready, OR triage will refine voice from your edit
patterns over 5+ runs.]
```

4. Inbox-triage will produce drafts in a more conservative default register (medium-formal, short-paragraph length). Drafts will need more editing on early runs.

## Common Anti-Patterns

### "I described my voice, that's enough"

Self-description has known blind spots (per the "Core Claim" above). Even high-self-awareness users overestimate their formality or underestimate their hedging frequency. Skip the samples and the first 10 triage runs produce drafts that "sound off" in a way users struggle to articulate.

### "I'll paste 5 emails that are similar"

5 emails to peers about the same project don't show register adaptation. The skill needs variance: one to a peer, one to a client/external, one transactional. If user pastes 5 similar emails, ask for one more from a different context.

### "I'll paste from my drafts folder"

Drafts may not represent voice the user actually sends — they may include rejected attempts. Ask for sent emails specifically.

### "I'll write 5 example emails for you"

Written-for-the-skill emails are self-description in disguise. Reject:

> "Examples written for me don't capture your actual voice — they capture how you describe your voice (which has known blind spots). Paste real sent emails, even short/boring ones. The mundane ones often signal voice better than carefully-crafted ones."

### "Forbidden tokens" extracted from samples instead of S3.Q2

Don't pull "forbidden tokens" from sample analysis — if a phrase appeared in a sent email, the user used it at some point. Forbidden tokens ONLY come from S3.Q2 (explicit "phrases I hate"). Voice extraction surfaces what the user DOES say, not what they DON'T.

## Operational Checklist (Per Setup Run)

- [ ] S3.Q1-Q6 asked one at a time with "why I'm asking"
- [ ] S3.SAMPLES asked AFTER Q1-Q6 (self-description first, samples second — samples calibrate the description, not replace it)
- [ ] 3-5 samples collected (or explicit user-skip + flag in patterns file)
- [ ] If collected: `scripts/voice_sample_analyzer.py` run; output incorporated into "Voice Patterns" subsection of patterns file
- [ ] Self-described hard rules + forbidden tokens preserved as authoritative
- [ ] Sample-extracted baseline preserved as descriptive (not authoritative)
- [ ] Calibration-status block included in patterns file (states whether samples were collected)

## Why This Reference Exists

The S3.SAMPLES step is the SINGLE most important question in the entire 25-31 question interview. Skipping it or doing it poorly compromises every subsequent triage run. This reference exists to make the discipline of "samples first, self-description second" explicit and operationally enforceable.

## Citations

Voice analysis canon:

1. **Brian Kernighan & Rob Pike, *The Practice of Programming* (Addison-Wesley, 1999)** — Chapter 1 on Style. The point that "names describe roles, not types" generalizes: a user's voice describes their habits, not their aspirations. Sample-based extraction captures habits.

2. **Steven Pinker, *The Sense of Style* (Viking, 2014)** — Chapter on register and the "Classic Style" trap. Self-described voice often defaults to Classic Style ideals that the user's actual voice doesn't match.

3. **Bryan Garner, *Garner's Modern English Usage* (5th ed., Oxford, 2022)** — Sections on register variation and register-adaptation across contexts. The justification for requiring sample variance (peer / external / transactional).

4. **Geoffrey Pullum, *The Cambridge Grammar of the English Language* (Cambridge, 2002), Chapter 12** — Register theory. Establishes that register is detectable from text features (sentence length, pronoun choice, hedging frequency) more reliably than from speaker self-report.

5. **Stylometric authorship attribution literature** — work by Patrick Juola, José Nilo G. Binongo, and the broader stylometry community. Establishes that text features (function-word frequency, punctuation patterns, sentence-length distribution) are robust voice signals. The features `voice_sample_analyzer.py` extracts are a subset of this canonical set.

6. **John Searle, *Speech Acts* (Cambridge, 1969)** — Performative theory. Useful framing for the "hard rules" (S3.Q6) discipline: hard rules are performatives the user commits to; voice is descriptive.

7. **Email-writing style guides at scale: *The Yahoo! Style Guide* (St. Martin's, 2010), *The Microsoft Manual of Style* (4th ed.).** Real-world style guides establish that register depends heavily on recipient + context, not on a single "professional voice." Justifies asking for sample variance.

FILE:scripts/kb_validator.py
#!/usr/bin/env python3
"""kb_validator.py — Validate the 7-file KB contract at WORKSPACE/Email/.

Stdlib-only. Confirms the inbox-setup skill produced the files inbox-triage
expects to read on every run. Used at end of Section 8 (Confirmation & Handoff)
and any time the user wants to spot-check the KB state.

Checks (per `references/kb_file_contract.md`):

  1. Required core files exist:
       - email-taxonomy.md
       - email-patterns.md
       - blocklist.md
       - tracker.md
  2. triage-log/ exists as a DIRECTORY (not a file)
  3. Conditional files exist iff their triggering section ran:
       - evaluation-framework.md (only if opportunity emails category)
       - rate-card.md (only if user has pricing)
  4. Each required file has an H1 header
  5. email-taxonomy.md has both "## Categories" + "## Report Preferences"
  6. email-patterns.md has "## Voice Calibration Status" (samples collected or not)

Output: PASS / WARN / FAIL per rule + overall verdict.

NO LLM CALLS. Pure filesystem + regex.

Usage:
    python kb_validator.py --workspace /path/to/workspace
    python kb_validator.py --workspace . --expect-evaluation --expect-rate-card
    python kb_validator.py --sample
"""

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional


CORE_REQUIRED = ["email-taxonomy.md", "email-patterns.md", "blocklist.md", "tracker.md"]
CONDITIONAL = ["evaluation-framework.md", "rate-card.md"]
LOG_DIR = "triage-log"


SAMPLE_KB: Dict[str, str] = {
    "email-taxonomy.md": (
        "# Email Taxonomy\n\n## Categories\n\n### New Opportunities\n"
        "- Signals: pitch / proposal / collab\n- Default action: classify + draft\n\n"
        "### Newsletters\n- Signals: unsubscribe / newsletter / digest\n"
        "- Default action: skip\n\n## Report Preferences\n\n"
        "- Delivery format: email-draft-to-self\n- Detail level: 30-second-scan\n"
    ),
    "email-patterns.md": (
        "# Email Patterns\n\n## Voice Register\nCasual\n\n## Hard Rules\n"
        "- Never: emojis in client emails\n- Always: reply within 24h\n\n"
        "## Voice Calibration Status\nSamples collected: 4 emails analyzed.\n"
    ),
    "blocklist.md": (
        "# Blocklist\n\n## Sender / Domain Auto-Skip\n"
        "- recruiter@*: cold outreach — added 2026-05-15\n\n"
        "## Decline Patterns\n- 'looking for backend engineers': cold recruiter\n"
    ),
    "tracker.md": (
        "# Tracker\n\n## Active Follow-Ups\n\n"
        "| Item | Context | Deadline | Status |\n|---|---|---|---|\n"
        "| Q3 contract | renewal due | 2026-06-15 | pending |\n\n## Overdue\n\n"
        "## Resolved (Recent)\n\n## Update Log\n"
    ),
    "evaluation-framework.md": (
        "# Evaluation Framework (Opportunity Emails)\n\n## Gut Filter (First Check)\n"
        "Is the budget realistic for the scope?\n\n## TAKE-IT Signals\n- Clear budget stated\n"
        "- VIP sender\n- Aligned to stated focus\n\n## PASS Signals (Instant Deal-Breakers)\n"
        "- Free / unpaid\n- Equity-only\n- Out-of-scope industry\n"
    ),
}


def check_file(workspace: Path, filename: str) -> Dict[str, Any]:
    p = workspace / "Email" / filename
    return {
        "filename": filename,
        "exists": p.exists() and p.is_file(),
        "path": str(p),
        "size": p.stat().st_size if p.exists() and p.is_file() else 0,
    }


def check_h1(workspace: Path, filename: str) -> Optional[str]:
    p = workspace / "Email" / filename
    if not p.exists() or not p.is_file():
        return None
    try:
        for line in p.read_text(encoding="utf-8").splitlines():
            m = re.match(r"^#\s+(.+?)\s*$", line)
            if m:
                return m.group(1).strip()
        return None
    except OSError:
        return None


def has_section(workspace: Path, filename: str, section_header: str) -> bool:
    p = workspace / "Email" / filename
    if not p.exists() or not p.is_file():
        return False
    try:
        text = p.read_text(encoding="utf-8")
        return bool(re.search(rf"^##\s+{re.escape(section_header)}\s*$", text, re.MULTILINE))
    except OSError:
        return False


def validate(
    workspace: Path,
    expect_evaluation: bool = False,
    expect_rate_card: bool = False,
) -> Dict[str, Any]:
    findings: List[Dict[str, str]] = []

    def add(rule: str, level: str, message: str) -> None:
        findings.append({"rule": rule, "level": level, "message": message})

    email_dir = workspace / "Email"
    if not email_dir.exists():
        add("workspace-email-dir", "FAIL", f"{email_dir} does not exist. Run inbox-setup first.")
        return finalize(findings)
    if not email_dir.is_dir():
        add("workspace-email-dir", "FAIL", f"{email_dir} is not a directory.")
        return finalize(findings)
    add("workspace-email-dir", "PASS", f"{email_dir} exists.")

    # Core required files
    for fn in CORE_REQUIRED:
        info = check_file(workspace, fn)
        if not info["exists"]:
            add(f"core-file:{fn}", "FAIL", f"Required file missing: Email/{fn}")
        elif info["size"] == 0:
            add(f"core-file:{fn}", "FAIL", f"Required file is empty: Email/{fn}")
        else:
            add(f"core-file:{fn}", "PASS", f"Email/{fn} present ({info['size']} bytes).")

    # H1 check on core files that exist
    for fn in CORE_REQUIRED:
        if not (workspace / "Email" / fn).exists():
            continue
        h1 = check_h1(workspace, fn)
        if h1:
            add(f"h1:{fn}", "PASS", f"Email/{fn} H1: '{h1}'")
        else:
            add(f"h1:{fn}", "FAIL", f"Email/{fn} has no H1.")

    # email-taxonomy.md must have both required subsections
    if (workspace / "Email" / "email-taxonomy.md").exists():
        if has_section(workspace, "email-taxonomy.md", "Categories"):
            add("taxonomy-categories", "PASS", "email-taxonomy.md has '## Categories' section.")
        else:
            add("taxonomy-categories", "FAIL", "email-taxonomy.md missing '## Categories' section.")
        if has_section(workspace, "email-taxonomy.md", "Report Preferences"):
            add("taxonomy-report-prefs", "PASS", "email-taxonomy.md has '## Report Preferences' section.")
        else:
            add("taxonomy-report-prefs", "WARN", "email-taxonomy.md missing '## Report Preferences' section (added at end of S7).")

    # email-patterns.md must have Voice Calibration Status
    if (workspace / "Email" / "email-patterns.md").exists():
        if has_section(workspace, "email-patterns.md", "Voice Calibration Status"):
            add("patterns-calibration", "PASS", "email-patterns.md has '## Voice Calibration Status' section.")
        else:
            add("patterns-calibration", "WARN", "email-patterns.md missing '## Voice Calibration Status' section (states whether samples were collected).")

    # Conditional files
    for fn in CONDITIONAL:
        info = check_file(workspace, fn)
        expect = (fn == "evaluation-framework.md" and expect_evaluation) or (fn == "rate-card.md" and expect_rate_card)
        if expect and not info["exists"]:
            add(f"conditional-file:{fn}", "FAIL", f"Expected (per --expect flag) but missing: Email/{fn}")
        elif not expect and info["exists"]:
            add(f"conditional-file:{fn}", "WARN", f"Email/{fn} exists but neither --expect-evaluation nor --expect-rate-card was set (may be stale from earlier setup).")
        elif expect and info["exists"]:
            add(f"conditional-file:{fn}", "PASS", f"Email/{fn} present (expected).")
        else:
            add(f"conditional-file:{fn}", "PASS", f"Email/{fn} correctly absent (not expected).")

    # triage-log/ must be a directory
    triage_log = workspace / "Email" / LOG_DIR
    if not triage_log.exists():
        add("triage-log-dir", "FAIL", f"Email/{LOG_DIR}/ missing. Must be created as empty directory at end of S6.")
    elif not triage_log.is_dir():
        add("triage-log-dir", "FAIL", f"Email/{LOG_DIR} exists but is not a directory.")
    else:
        add("triage-log-dir", "PASS", f"Email/{LOG_DIR}/ exists as directory.")

    return finalize(findings)


def finalize(findings: List[Dict[str, str]]) -> Dict[str, Any]:
    counts = {"PASS": 0, "WARN": 0, "FAIL": 0}
    for f in findings:
        counts[f["level"]] += 1
    if counts["FAIL"] > 0:
        verdict = "FAIL"
    elif counts["WARN"] > 0:
        verdict = "WARN"
    else:
        verdict = "PASS"
    return {"verdict": verdict, "counts": counts, "findings": findings}


def render_human(result: Dict[str, Any]) -> str:
    out: List[str] = []
    out.append(f"KB contract verdict: {result['verdict']}")
    counts = result["counts"]
    out.append(f"  PASS: {counts['PASS']}  WARN: {counts['WARN']}  FAIL: {counts['FAIL']}")
    out.append("")
    out.append("Findings:")
    for f in result["findings"]:
        marker = {"PASS": "[ok]", "WARN": "[warn]", "FAIL": "[FAIL]"}[f["level"]]
        out.append(f"  {marker} {f['rule']}: {f['message']}")
    return "\n".join(out)


def run_sample() -> Dict[str, Any]:
    import tempfile
    with tempfile.TemporaryDirectory() as td:
        ws = Path(td)
        email_dir = ws / "Email"
        email_dir.mkdir(parents=True)
        for name, content in SAMPLE_KB.items():
            (email_dir / name).write_text(content, encoding="utf-8")
        (email_dir / LOG_DIR).mkdir()
        return validate(ws, expect_evaluation=True, expect_rate_card=False)


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument("--workspace", help="Path to workspace (looks at <workspace>/Email/)")
    parser.add_argument("--expect-evaluation", action="store_true", help="Expect evaluation-framework.md to exist")
    parser.add_argument("--expect-rate-card", action="store_true", help="Expect rate-card.md to exist")
    parser.add_argument("--sample", action="store_true", help="Run on embedded sample KB")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    if args.sample:
        result = run_sample()
    elif args.workspace:
        ws = Path(args.workspace)
        if not ws.exists():
            print(f"error: {args.workspace} not found", file=sys.stderr)
            return 2
        result = validate(ws, args.expect_evaluation, args.expect_rate_card)
    else:
        parser.print_help()
        return 0

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(render_human(result))
    return 0 if result["verdict"] != "FAIL" else 1


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

FILE:scripts/section_progress_tracker.py
#!/usr/bin/env python3
"""section_progress_tracker.py — JSON-backed walk state for 8-section setup.

Stdlib-only. Tracks the setup interview state at ~/.inbox_setup_sessions/<session>.json
so the skill can:

  - Know which section is currently active
  - Record each question's answer
  - Mark each section as done with the file(s) it committed
  - Detect drop-off and produce useful partial state
  - Resume later if the user drops off mid-interview

Actions:
  start                 Create a new session
  record_q              Record an answer to a question
  record_section_done   Mark section complete with files committed
  status                Show current session state
  list                  List all sessions
  close                 Mark session ended

Usage:
    python section_progress_tracker.py --action start --session inbox-setup-20260515 --user alice
    python section_progress_tracker.py --action record_q --session ... --section 1 --question 1 --answer "Solo consultant"
    python section_progress_tracker.py --action record_section_done --session ... --section 2 --files "email-taxonomy.md"
    python section_progress_tracker.py --action status --session ...
    python section_progress_tracker.py --action list
    python section_progress_tracker.py --action close --session ...
"""

import argparse
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, List, Optional


SESSIONS_DIR = Path.home() / ".inbox_setup_sessions"
TOTAL_SECTIONS = 8


def session_path(name: str) -> Path:
    return SESSIONS_DIR / f"{name}.json"


def load_session(name: str) -> Dict[str, Any]:
    p = session_path(name)
    if not p.exists():
        raise FileNotFoundError(f"Session not found: {name}")
    return json.loads(p.read_text(encoding="utf-8"))


def save_session(name: str, data: Dict[str, Any]) -> None:
    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
    session_path(name).write_text(json.dumps(data, indent=2), encoding="utf-8")


def now_iso() -> str:
    return datetime.now(timezone.utc).isoformat()


def action_start(name: str, user: Optional[str]) -> Dict[str, Any]:
    if session_path(name).exists():
        raise FileExistsError(f"Session already exists: {name}")
    data: Dict[str, Any] = {
        "session": name,
        "user": user or "(anonymous)",
        "started_at": now_iso(),
        "ended_at": None,
        "active_section": 1,
        "sections": {str(i): {"status": "pending", "questions_answered": [], "files_committed": []} for i in range(1, TOTAL_SECTIONS + 1)},
        "total_questions_answered": 0,
        "skip_log": [],
    }
    save_session(name, data)
    return data


def action_record_q(name: str, section: int, question: int, answer: str) -> Dict[str, Any]:
    data = load_session(name)
    key = str(section)
    if key not in data["sections"]:
        raise ValueError(f"Invalid section: {section}")
    sec = data["sections"][key]
    if sec["status"] == "pending":
        sec["status"] = "in_progress"
        sec["started_at"] = now_iso()
    sec["questions_answered"].append({
        "question": question,
        "answer": answer,
        "at": now_iso(),
    })
    data["total_questions_answered"] += 1
    data["active_section"] = section
    save_session(name, data)
    return data


def action_record_section_done(name: str, section: int, files: List[str]) -> Dict[str, Any]:
    data = load_session(name)
    key = str(section)
    if key not in data["sections"]:
        raise ValueError(f"Invalid section: {section}")
    sec = data["sections"][key]
    sec["status"] = "done"
    sec["files_committed"] = files
    sec["ended_at"] = now_iso()
    # Advance active section
    if section < TOTAL_SECTIONS:
        data["active_section"] = section + 1
    save_session(name, data)
    return data


def action_record_skip(name: str, section: int, reason: str) -> Dict[str, Any]:
    data = load_session(name)
    key = str(section)
    sec = data["sections"][key]
    sec["status"] = "skipped"
    sec["skip_reason"] = reason
    sec["ended_at"] = now_iso()
    data["skip_log"].append({"section": section, "reason": reason, "at": now_iso()})
    if section < TOTAL_SECTIONS:
        data["active_section"] = section + 1
    save_session(name, data)
    return data


def action_status(name: str) -> Dict[str, Any]:
    return load_session(name)


def action_close(name: str) -> Dict[str, Any]:
    data = load_session(name)
    if data.get("ended_at") is None:
        data["ended_at"] = now_iso()
        save_session(name, data)
    return data


def action_list() -> List[Dict[str, Any]]:
    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
    out: List[Dict[str, Any]] = []
    for p in sorted(SESSIONS_DIR.glob("*.json")):
        try:
            data = json.loads(p.read_text(encoding="utf-8"))
            done_sections = sum(1 for s in data["sections"].values() if s["status"] == "done")
            out.append({
                "session": data["session"],
                "user": data["user"],
                "started_at": data["started_at"],
                "ended_at": data["ended_at"],
                "active_section": data["active_section"],
                "done_sections": done_sections,
                "total_questions_answered": data["total_questions_answered"],
            })
        except (OSError, json.JSONDecodeError):
            continue
    return out


def render_status_human(data: Dict[str, Any]) -> str:
    out: List[str] = []
    out.append(f"Session:          {data['session']}")
    out.append(f"User:             {data['user']}")
    out.append(f"Started:          {data['started_at']}")
    out.append(f"Ended:            {data.get('ended_at') or '(active)'}")
    out.append(f"Active section:   {data['active_section']}/{TOTAL_SECTIONS}")
    out.append(f"Total Qs answered:{data['total_questions_answered']}")
    out.append("")
    out.append("Per-section state:")
    for key in sorted(data["sections"].keys(), key=lambda k: int(k)):
        sec = data["sections"][key]
        marker = {"pending": "  ", "in_progress": "↻ ", "done": "✓ ", "skipped": "→ "}.get(sec["status"], "  ")
        files = ", ".join(sec["files_committed"]) if sec["files_committed"] else "—"
        out.append(f"  {marker}S{key}: {sec['status']:<12s} ({len(sec['questions_answered'])} Q answered, files: {files})")
    if data["skip_log"]:
        out.append("")
        out.append("Skip log:")
        for s in data["skip_log"]:
            out.append(f"  S{s['section']}: {s['reason']}")
    return "\n".join(out)


def render_list_human(rows: List[Dict[str, Any]]) -> str:
    if not rows:
        return "(no sessions)"
    out: List[str] = []
    out.append(f"{'session':<40s}  {'user':<15s}  {'active':>6s}  {'done':>4s}  {'Q':>3s}  status")
    out.append("-" * 90)
    for r in rows:
        status = "closed" if r["ended_at"] else "active"
        out.append(
            f"{r['session']:<40s}  {r['user']:<15s}  {r['active_section']:>6d}  {r['done_sections']:>4d}  {r['total_questions_answered']:>3d}  {status}"
        )
    return "\n".join(out)


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument("--action", required=True, choices=["start", "record_q", "record_section_done", "record_skip", "status", "list", "close"])
    parser.add_argument("--session", help="Session name")
    parser.add_argument("--user", help="(start only) user identifier")
    parser.add_argument("--section", type=int, help="Section number 1-8")
    parser.add_argument("--question", type=int, help="(record_q only) question number within section")
    parser.add_argument("--answer", help="(record_q only) answer text")
    parser.add_argument("--files", help="(record_section_done only) comma-separated filenames")
    parser.add_argument("--reason", help="(record_skip only) why section was skipped")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    try:
        if args.action == "start":
            if not args.session:
                print("error: --session required for start", file=sys.stderr); return 2
            result = action_start(args.session, args.user)
        elif args.action == "record_q":
            if not (args.session and args.section and args.question is not None and args.answer is not None):
                print("error: --session, --section, --question, --answer required", file=sys.stderr); return 2
            result = action_record_q(args.session, args.section, args.question, args.answer)
        elif args.action == "record_section_done":
            if not (args.session and args.section and args.files):
                print("error: --session, --section, --files required", file=sys.stderr); return 2
            files = [f.strip() for f in args.files.split(",") if f.strip()]
            result = action_record_section_done(args.session, args.section, files)
        elif args.action == "record_skip":
            if not (args.session and args.section and args.reason):
                print("error: --session, --section, --reason required", file=sys.stderr); return 2
            result = action_record_skip(args.session, args.section, args.reason)
        elif args.action == "status":
            if not args.session:
                print("error: --session required for status", file=sys.stderr); return 2
            result = action_status(args.session)
        elif args.action == "close":
            if not args.session:
                print("error: --session required for close", file=sys.stderr); return 2
            result = action_close(args.session)
        else:
            result = action_list()
    except (FileNotFoundError, FileExistsError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr); return 2

    if args.output == "json":
        print(json.dumps(result, indent=2, default=str))
    else:
        if args.action == "list":
            print(render_list_human(result))
        else:
            print(render_status_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

FILE:scripts/voice_sample_analyzer.py
#!/usr/bin/env python3
"""voice_sample_analyzer.py — Extract voice patterns from sent-email samples.

Stdlib-only. Reads 3-5 sent-email samples (separated by `---` delimiters) and
extracts deterministic voice signals:

  1. Opening phrases — first 4-6 tokens of each sample body
  2. Sign-offs       — last 4-6 tokens of each sample
  3. Sentence-length distribution — short (<10 words) / medium (10-25) / long (>25) ratio
  4. Register markers — counts of casual indicators (lol, yeah, btw, tbh) vs formal
     (I would like to, please find, kindly)
  5. Hedging frequency — counts of softeners (maybe, perhaps, I think, just)
  6. Personal pronouns — "I" vs "we" ratio
  7. Punctuation patterns — em-dashes, exclamation marks, ellipses per sample

Output: a structured patterns block that gets dropped into email-patterns.md
under "Voice Patterns (Extracted from Samples)".

NO LLM CALLS. Pure regex + frequency counting.

Limitations (intentional, stdlib-only):
  - No semantic understanding (it's surface-feature stylometry)
  - English-only register markers
  - Tokenization is whitespace-based (not linguistic)

Usage:
    python voice_sample_analyzer.py --samples-file /path/to/samples.txt
    python voice_sample_analyzer.py --samples-file /path/to/samples.txt --output json
    python voice_sample_analyzer.py --sample
"""

import argparse
import json
import re
import sys
from collections import Counter
from pathlib import Path
from typing import Any, Dict, List, Tuple


SAMPLE_DELIMITER_RE = re.compile(r"^\s*---+\s*$", re.MULTILINE)
SENTENCE_END_RE = re.compile(r"[.!?]+(?:\s|$)")

CASUAL_MARKERS = {
    "lol", "lmao", "haha", "yeah", "yup", "nope", "tbh", "btw", "fwiw",
    "imo", "imho", "rn", "btw", "ok", "okay", "cool", "sure", "yep",
    "gonna", "wanna", "kinda", "sorta", "dunno",
}
FORMAL_MARKERS_PHRASES = [
    "i would like to", "please find", "kindly", "i hope this email finds you",
    "i am writing to", "as per our", "at your earliest convenience",
    "thank you for your", "i look forward to hearing", "to whom it may concern",
    "respectfully", "sincerely",
]
HEDGING_MARKERS = {
    "maybe", "perhaps", "i think", "i guess", "i suppose", "just",
    "kinda", "sorta", "might", "could", "possibly", "potentially",
    "i feel", "i believe",
}


def split_samples(text: str) -> List[str]:
    """Split combined samples text on `---` delimiters; trim each."""
    parts = SAMPLE_DELIMITER_RE.split(text)
    return [p.strip() for p in parts if p.strip()]


def first_n_tokens(text: str, n: int) -> str:
    tokens = text.split()
    return " ".join(tokens[:n])


def last_n_tokens(text: str, n: int) -> str:
    tokens = text.split()
    return " ".join(tokens[-n:])


def count_phrase_occurrences(text_lower: str, phrases: List[str]) -> int:
    return sum(text_lower.count(p) for p in phrases)


def count_word_occurrences(text_lower: str, words: set) -> int:
    pattern = re.compile(rf"\b({'|'.join(re.escape(w) for w in words)})\b", re.IGNORECASE)
    return len(pattern.findall(text_lower))


def split_sentences(text: str) -> List[str]:
    parts = SENTENCE_END_RE.split(text)
    return [s.strip() for s in parts if s.strip()]


def length_bucket(word_count: int) -> str:
    if word_count < 10:
        return "short"
    if word_count <= 25:
        return "medium"
    return "long"


def analyze_sample(sample: str) -> Dict[str, Any]:
    text_lower = sample.lower()
    sentences = split_sentences(sample)
    length_dist = Counter()
    for s in sentences:
        words = s.split()
        length_dist[length_bucket(len(words))] += 1
    return {
        "opening": first_n_tokens(sample, 6),
        "sign_off": last_n_tokens(sample, 6),
        "sentence_count": len(sentences),
        "length_distribution": dict(length_dist),
        "casual_marker_count": count_word_occurrences(text_lower, CASUAL_MARKERS),
        "formal_marker_count": count_phrase_occurrences(text_lower, FORMAL_MARKERS_PHRASES),
        "hedging_count": count_word_occurrences(text_lower, HEDGING_MARKERS),
        "i_count": count_word_occurrences(text_lower, {"i", "i'm", "i've", "i'll", "i'd"}),
        "we_count": count_word_occurrences(text_lower, {"we", "we're", "we've", "we'll", "we'd", "our", "us"}),
        "em_dash_count": sample.count("—") + sample.count(" -- "),
        "exclamation_count": sample.count("!"),
        "ellipsis_count": sample.count("...") + sample.count("…"),
    }


def aggregate(per_sample: List[Dict[str, Any]]) -> Dict[str, Any]:
    if not per_sample:
        return {"error": "no samples"}
    n = len(per_sample)
    openings = [s["opening"] for s in per_sample]
    sign_offs = [s["sign_off"] for s in per_sample]
    total_sentences = sum(s["sentence_count"] for s in per_sample)
    total_lengths: Counter = Counter()
    for s in per_sample:
        total_lengths.update(s["length_distribution"])
    casual = sum(s["casual_marker_count"] for s in per_sample)
    formal = sum(s["formal_marker_count"] for s in per_sample)
    hedging = sum(s["hedging_count"] for s in per_sample)
    i_count = sum(s["i_count"] for s in per_sample)
    we_count = sum(s["we_count"] for s in per_sample)
    em_dash = sum(s["em_dash_count"] for s in per_sample)
    exclamation = sum(s["exclamation_count"] for s in per_sample)
    ellipsis = sum(s["ellipsis_count"] for s in per_sample)

    if casual > formal * 2:
        register_verdict = "casual"
    elif formal > casual * 2:
        register_verdict = "formal"
    else:
        register_verdict = "in-between"

    if total_sentences > 0:
        short_ratio = total_lengths.get("short", 0) / total_sentences
        medium_ratio = total_lengths.get("medium", 0) / total_sentences
        long_ratio = total_lengths.get("long", 0) / total_sentences
    else:
        short_ratio = medium_ratio = long_ratio = 0.0

    if short_ratio > 0.5:
        length_verdict = "one-liner / short-paragraph"
    elif long_ratio > 0.3:
        length_verdict = "longer (multi-paragraph)"
    else:
        length_verdict = "short-paragraph (medium average)"

    return {
        "sample_count": n,
        "openings": openings,
        "sign_offs": sign_offs,
        "register_verdict": register_verdict,
        "register_signals": {"casual_markers": casual, "formal_markers": formal},
        "length_verdict": length_verdict,
        "length_distribution": {
            "short_pct": round(short_ratio * 100, 1),
            "medium_pct": round(medium_ratio * 100, 1),
            "long_pct": round(long_ratio * 100, 1),
        },
        "hedging_frequency_per_sample": round(hedging / n, 2),
        "i_vs_we": {
            "i_count": i_count,
            "we_count": we_count,
            "voice": "individual" if i_count > we_count * 2 else "team" if we_count > i_count * 2 else "mixed",
        },
        "punctuation": {
            "em_dash_per_sample": round(em_dash / n, 2),
            "exclamation_per_sample": round(exclamation / n, 2),
            "ellipsis_per_sample": round(ellipsis / n, 2),
        },
    }


def render_human(result: Dict[str, Any]) -> str:
    out: List[str] = []
    out.append(f"Voice analysis ({result['sample_count']} samples)")
    out.append("")
    out.append(f"Register verdict:    {result['register_verdict']}")
    out.append(f"  Casual markers:    {result['register_signals']['casual_markers']}")
    out.append(f"  Formal markers:    {result['register_signals']['formal_markers']}")
    out.append("")
    out.append(f"Length verdict:      {result['length_verdict']}")
    ld = result['length_distribution']
    out.append(f"  Short / Medium / Long: {ld['short_pct']}% / {ld['medium_pct']}% / {ld['long_pct']}%")
    out.append("")
    out.append(f"Hedging frequency:   {result['hedging_frequency_per_sample']} per sample")
    iw = result['i_vs_we']
    out.append(f"I vs We voice:       {iw['voice']} (I:{iw['i_count']}  We:{iw['we_count']})")
    out.append("")
    p = result['punctuation']
    out.append(f"Punctuation per sample: em-dash {p['em_dash_per_sample']}, ! {p['exclamation_per_sample']}, ... {p['ellipsis_per_sample']}")
    out.append("")
    out.append("Opening phrases (first 6 tokens):")
    for o in result['openings']:
        out.append(f"  - {o}")
    out.append("")
    out.append("Sign-offs (last 6 tokens):")
    for s in result['sign_offs']:
        out.append(f"  - {s}")
    out.append("")
    out.append("Output block for email-patterns.md:")
    out.append("---")
    out.append("## Voice Patterns (Extracted from Samples)")
    out.append("")
    out.append(f"- Register: {result['register_verdict']}")
    out.append(f"- Typical reply length: {result['length_verdict']}")
    out.append(f"- Hedging frequency: {result['hedging_frequency_per_sample']} per email")
    out.append(f"- Voice perspective: {result['i_vs_we']['voice']}")
    out.append(f"- Sentence-length distribution: short {ld['short_pct']}% / medium {ld['medium_pct']}% / long {ld['long_pct']}%")
    out.append("- Observed opening patterns:")
    for o in result['openings'][:5]:
        out.append(f"  - \"{o}\"")
    out.append("- Observed sign-off patterns:")
    for s in result['sign_offs'][:5]:
        out.append(f"  - \"{s}\"")
    return "\n".join(out)


SAMPLE_TEXT = """Hey, just looping back on the Q3 launch — pricing's mostly locked but I want to revisit the bundle option before we ship. Quick call tomorrow?

—Alex

---

Thanks for the proposal. Honestly, the timeline is tight and our team is heads-down on shipping. We'd need to push to Q4. Open to that?

Alex

---

Got it — sending the revised draft now. Couple of comments inline, mostly around the auth flow. Let me know what you think.

Best,
Alex

---

I'm going to pass on this one. Scope is too broad for what we can commit to in the next 6 weeks and the budget doesn't match the work involved.

Thanks for thinking of us though.

—Alex

---

Quick update: shipped the migration today, no incidents so far. Will keep an eye on it through the weekend. Lmk if you see anything weird.
"""


def main(argv: List[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument("--samples-file", help="Path to file containing sent-email samples separated by ---")
    parser.add_argument("--sample", action="store_true", help="Analyze embedded sample text")
    parser.add_argument("--output", choices=["human", "json"], default="human")
    args = parser.parse_args(argv)

    if args.sample:
        text = SAMPLE_TEXT
    elif args.samples_file:
        p = Path(args.samples_file)
        if not p.exists():
            print(f"error: {args.samples_file} not found", file=sys.stderr); return 2
        text = p.read_text(encoding="utf-8")
    else:
        parser.print_help(); return 0

    samples = split_samples(text)
    if not samples:
        print("error: no samples detected (use --- as delimiter between samples)", file=sys.stderr); return 2
    if len(samples) < 3:
        print(f"warning: only {len(samples)} sample(s) detected; recommend 3-5 for reliable patterns", file=sys.stderr)

    per_sample = [analyze_sample(s) for s in samples]
    result = aggregate(per_sample)

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(render_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: "iso42001-specialist"
description: "ISO/IEC 42001:2023 AI Management System (AIMS) specialist for compliance teams running internal audits. Three decisions: (1) Where are the gaps against Clauses 4-10 and what do we close first? (2) What goes in the AI risk register and which Annex A controls treat each risk? (3) What's the 12-month internal audit plan that satisfies Clause 9.2? Use when preparing for certification, scoping internal audit cycles, or onboarding AI systems into an existing ISMS (27001) / QMS (13485) program. NOT an executive AI strategy skill (see chief-ai-officer-advisor). NOT EU AI Act compliance (see compliance-team-eu-ai-act)."
license: MIT
metadata:
  version: 1.0.0
  author: Alireza Rezvani
  category: ra-qm-team
  domain: ai-management-system-compliance
  updated: 2026-05-13
  python-tools: aims_gap_analyzer.py, ai_risk_register_builder.py, aims_audit_scheduler.py
  frameworks: iso-42001, iso-23894, iso-38507, nist-ai-rmf, eu-ai-act-mapping
---

# ISO/IEC 42001 AI Management System Specialist

Internal-audit-grade operating skill for ISO/IEC 42001:2023. **Three decisions, no executive AI strategy:**

1. **Where are the AIMS gaps against Clauses 4–10?** — coverage scoring per clause + remediation priority
2. **What's the AI risk register, and which controls treat each risk?** — Annex A.2–A.10 control mapping per ISO 23894 risk method
3. **What's the Clause 9.2 internal audit plan?** — 12-month schedule with scope, frequency, auditor independence checks

This skill is **NOT a chief-ai-officer-advisor replacement**. CAIO decides whether to build/buy a model and what business risk to accept. This skill operates the management-system discipline that captures those decisions in audit-ready evidence.

This skill is **NOT an EU AI Act compliance skill**. ISO 42001 is a voluntary management-system standard; EU AI Act is binding product-safety regulation. They overlap (a high-risk AI system per Article 6(2) of the AI Act typically requires the QMS in Article 17, which ISO 42001 can satisfy in part) but the artefacts differ. See `compliance-team-eu-ai-act` for Article-level conformity assessment.

This skill is **NOT a substitute for ISO 23894 + 38507**. 42001 is the management system; 23894 is the AI risk methodology that feeds Clause 6.1; 38507 is the governance lens. The `ai_risk_register_builder.py` tool implements the 23894 process; treat the references as the methodology bridge.

## Keywords

ISO 42001, ISO/IEC 42001:2023, AI Management System, AIMS, AI governance, AI risk management, ISO 23894, AI risk assessment, ISO 38507, AI compliance, AI audit, internal audit AI, Annex A controls, AI risk register, AI policy, AI impact assessment, conformity declaration, AI lifecycle, AI risk treatment, NIST AI RMF, NIST AI Risk Management Framework, ISACA AI audit, BSI AIC4, AI assurance, responsible AI, AI ethics governance, AI system inventory, third-party AI risk, AI vendor management, AI change management, AI incident management

## Quick Start

```bash
# Decision A: AIMS gap analysis against Clauses 4-10
python scripts/aims_gap_analyzer.py                           # embedded sample (mid-stage AI SaaS)
python scripts/aims_gap_analyzer.py path/to/aims_evidence.json

# Decision B: AI risk register + Annex A control mapping
python scripts/ai_risk_register_builder.py                    # embedded 7-risk sample
python scripts/ai_risk_register_builder.py path/to/risks.json

# Decision C: Clause 9.2 internal audit 12-month plan
python scripts/aims_audit_scheduler.py                        # embedded 4-domain sample
python scripts/aims_audit_scheduler.py path/to/scope.json
```

## Key Questions (ask these first)

- **Does the AIMS scope statement (Clause 4.3) name every AI system, including embedded models and third-party AI services?** If "AI features added by our SaaS vendors" is not in scope, the AIMS is incomplete.
- **Does the AI policy (Clause 5.2) commit to lawful use AND beneficial purpose AND human oversight AND continual improvement?** Missing any of the four = nonconformity at certification.
- **Has the AI risk assessment (Clause 6.1.2) been re-run since the last material model change?** Concept drift is not a one-time event.
- **Who signs the AI impact assessment for high-impact systems (Annex A.5.4)?** If no signed accountability, the control is missing.
- **What's the internal audit cadence (Clause 9.2)?** ISO management-system standards expect ≥ once per 3-year cycle per clause; mature programs do annual.
- **Is there a documented procedure for AI incidents (Annex A.9.3)?** Untreated post-deployment monitoring is the #1 nonconformity in early adopters.

## Core Responsibilities

### 1. AIMS Gap Analysis (Clauses 4–10)

**The framework:** ISO 42001 follows the Annex SL high-level structure shared with ISO 9001 / 27001 / 13485. Clauses 4–10 are the management-system requirements; Annex A controls A.1–A.10 are the AI-specific operational controls.

| Clause | What it requires | Common gap |
|---|---|---|
| **4. Context** | AI scope, interested parties, external context | Scope omits third-party AI services |
| **5. Leadership** | AI policy, roles, accountability | Policy treats "AI ethics" as marketing copy, not commitment |
| **6. Planning** | AI risk + impact assessment, objectives | Risk register doesn't link to controls |
| **7. Support** | Resources, competence, awareness, documented info | Competence requirements undefined for ML engineers |
| **8. Operation** | Operational planning, AI system lifecycle | Lifecycle stages not mapped to Annex A controls |
| **9. Performance** | Monitoring, internal audit, management review | Drift monitoring exists in code but not in management review inputs |
| **10. Improvement** | Nonconformity, corrective action, continual improvement | CAPA loop separate from existing 13485/9001 CAPA — duplication |

**Run** `aims_gap_analyzer.py` with an evidence inventory JSON to score each clause (full / partial / missing) and get a prioritized remediation list.

See `references/iso42001_clauses.md` for the full clause-by-clause walkthrough with audit evidence expectations.

### 2. AI Risk Register + Annex A Control Mapping

**The framework:** Clause 6.1.2 requires AI risk assessment; Clause 6.1.3 requires risk treatment. Annex A provides 38 controls organized into 10 control categories (A.2–A.10). The risk register must show each identified risk linked to ≥ 1 control that treats it.

**Annex A control categories (the 10):**

| ID | Category | Example controls |
|---|---|---|
| **A.2** | AI policy | A.2.2 AI policy, A.2.3 alignment with other policies |
| **A.3** | Internal organization | A.3.2 AI roles & responsibilities, A.3.3 reporting concerns |
| **A.4** | Resources for AI systems | A.4.2 data resources, A.4.3 tooling, A.4.4 human resources |
| **A.5** | Assessing impacts | A.5.2 AI system impact assessment, A.5.4 documentation of impact assessment |
| **A.6** | AI system lifecycle | A.6.2.2 objectives, A.6.2.3 lifecycle phases, A.6.2.4 verification & validation |
| **A.7** | Data for AI systems | A.7.2 data management, A.7.3 data quality, A.7.4 data provenance, A.7.5 data preparation |
| **A.8** | Information for interested parties | A.8.2 system documentation, A.8.3 user information, A.8.4 communication of incidents |
| **A.9** | Use of AI systems | A.9.2 intended use, A.9.3 monitoring of operation, A.9.4 logging of system events |
| **A.10** | Third-party & customer relationships | A.10.2 supplier relationships, A.10.3 customer relationships |

ISO/IEC 23894:2023 provides the AI-specific risk-management process (the methodology); 42001 Annex A provides the controls. The risk register is the bridge.

**Run** `ai_risk_register_builder.py` with an identified-risks JSON to produce a structured register with mapped controls + residual-risk verdict per ISO 23894 risk-treatment options.

See `references/aims_controls_annex_a.md` for the full 38-control catalogue with audit evidence per control.

### 3. Clause 9.2 Internal Audit Plan

**The framework:** Clause 9.2 requires "internal audits at planned intervals to provide information on whether the AIMS conforms to the organization's requirements and is effectively implemented and maintained." That's the management-system requirement; the **how often** and **how deep** are organizational choices.

**Mature-program defaults:**

- Cover every clause + every applicable Annex A control over a 3-year cycle (rolling)
- Annual full-system audit covering Clauses 4, 5, 9, 10 (the "always relevant" clauses)
- Quarterly or semi-annual deep dives on Clauses 6, 7, 8 by domain (per AI system or per lifecycle phase)
- Auditor independence: nobody audits their own work; A.6 lifecycle owner cannot audit Clause 8 operation

**Run** `aims_audit_scheduler.py` with a scope JSON (AI systems in scope, prior-year findings, certification cycle phase) to produce a 12-month plan with auditor assignments and independence checks.

See `references/aims_implementation_guide.md` for the maturity model and rollout sequencing (year 1 establish, year 2 certify, year 3+ continual improvement).

## Workflows

### Workflow 1: AIMS Gap Closure for Certification (4–8 weeks)
**Goal:** Identify gaps; prioritize remediation; close before stage 1 certification audit.

```bash
# 1. Inventory current AIMS evidence (policies, procedures, records)
python scripts/aims_gap_analyzer.py aims_evidence.json
# 2. Review gap matrix; group by clause
# 3. For each gap, identify owner + due date (target: close before stage 1)
# 4. Cross-check against ISO 27001 / 13485 existing artifacts — many can be reused
# 5. Cross-check against EU AI Act obligations (use compliance-team-eu-ai-act)
# 6. Output: prioritized remediation plan with owners + dates
```

### Workflow 2: AI Risk Register Build (1–2 weeks)
**Goal:** Construct the Clause 6.1.2 risk register with full Annex A control coverage.

```bash
# 1. Run ISO 23894 risk identification across AI lifecycle (data, model, deployment, decommission)
# 2. Capture each risk with: source, event, consequence, likelihood, impact
python scripts/ai_risk_register_builder.py risks.json
# 3. For each high/critical risk, confirm ≥ 1 Annex A control is selected as treatment
# 4. Document residual risk acceptance with management signoff
# 5. Cross-check with cs-caio-advisor on executive risk acceptance for "tolerate" decisions
# 6. Log via management review (Clause 9.3)
```

### Workflow 3: Annual Internal Audit Plan (1 day)
**Goal:** Produce the 12-month Clause 9.2 plan with auditor independence.

```bash
# 1. Pull last year's audit findings and certification cycle status (year 1/2/3)
python scripts/aims_audit_scheduler.py audit_scope.json
# 2. Confirm auditor independence per assignment
# 3. Confirm coverage hits every clause and every applicable Annex A control over rolling 3 years
# 4. Submit plan for management review approval (Clause 9.3 input)
```

### Workflow 4: Cross-Framework Reuse Mapping (per system onboarded)
**Goal:** When adding a new AI system, map ISO 42001 evidence against existing 27001 + 13485 evidence to avoid duplication.

1. Pull existing ISO 27001 Annex A controls + ISO 13485 procedures relevant to the system
2. For each ISO 42001 Annex A control, identify whether an existing artifact already satisfies it (e.g., 27001 A.8.16 monitoring activities can extend to AI system monitoring)
3. Add the AI-specific overlay only where the existing control doesn't cover it
4. Document mapping in the AIMS scope statement (Clause 4.3)

## Output Standards

```
**Bottom Line:** [one sentence — gap severity + the one thing to close first]
**The Decision:** [one of: gap-closure | risk-treatment | audit-scope]
**The Evidence:** [clause numbers + control IDs from the tool, not adjectives]
**How to Act:** [3 concrete next steps with owners + dates]
**Your Decision:** [the call only the compliance officer or CAIO can make — risk acceptance, scope expansion, certification readiness]
```

## Adjacent Skills

- `../../skills/information-security-manager-iso27001/` — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls)
- `../../skills/quality-manager-qms-iso13485/` — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses)
- `../../skills/gdpr-dsgvo-expert/` — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems)
- `../../skills/isms-audit-expert/` — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS)
- `../../skills/soc2-compliance/` — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships)
- `../../../compliance-team-eu-ai-act/` — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001)
- `../../../../compliance-os/` — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9)
- `../../../../c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy (build-vs-buy, cost economics — different audience)

## References

- [iso42001_clauses.md](references/iso42001_clauses.md) — Clauses 4–10 walkthrough with audit evidence expectations, common gaps, and reusable artifacts from ISO 27001/13485
- [aims_controls_annex_a.md](references/aims_controls_annex_a.md) — All 38 Annex A controls (A.2–A.10) with implementation guidance, audit evidence, and severity of failure
- [aims_implementation_guide.md](references/aims_implementation_guide.md) — 3-year maturity model (establish → certify → continually improve), rollout sequencing, integration with existing ISMS/QMS programs
- [cross_framework_mapping_ai.md](references/cross_framework_mapping_ai.md) — ISO 42001 ↔ EU AI Act ↔ NIST AI RMF ↔ ISO 23894 ↔ ISO 38507 ↔ ISO 27001 control-level mapping with mapping-confidence ratings

---

**Version:** 1.0.0
**Status:** Production Ready

FILE:references/aims_controls_annex_a.md
# ISO/IEC 42001 Annex A — 38 Controls Catalogue

This reference answers exactly one decision: **for each Annex A control, what does implementation look like, what evidence does the auditor want, and what's the severity if it's missing?**

Pair with `scripts/ai_risk_register_builder.py` to map risks to controls.

## Structure of Annex A

ISO/IEC 42001 Annex A is a *normative* annex containing reference controls. The standard requires (per Clause 6.1.3) that the organization compare its determined controls to Annex A to verify no necessary controls have been omitted. Unlike ISO 27001 where Annex A is presumed-applicable, ISO 42001 Annex A controls are applied based on risk — if a control doesn't apply (e.g., A.10 third-party AI when you use no third-party AI), document the exclusion with justification.

**The 10 control categories (A.1 is the structural intro; A.2–A.10 are the operational controls):**

| ID | Category | Control count | Maps to clause |
|---|---|---|---|
| A.2 | Policies related to AI | 2 | 5.2 |
| A.3 | Internal organization | 2 | 5.3 |
| A.4 | Resources for AI systems | 3 | 7.1 |
| A.5 | Assessing impacts of AI systems | 3 | 6.1.4, 8.2 |
| A.6 | AI system lifecycle | 8 | 8.3 |
| A.7 | Data for AI systems | 5 | 8.3 |
| A.8 | Information for interested parties | 4 | 7.4, 9.1 |
| A.9 | Use of AI systems | 4 | 8.3, 9.1 |
| A.10 | Third-party & customer relationships | 5 | 8.4 |

Total: **38 controls** across 9 operational categories.

## A.2 — Policies (severity if missing: CRITICAL)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.2.2** | AI policy | Signed AI policy meeting Clause 5.2 requirements | ISO 27001 A.5.1 (information security policy) — extend |
| **A.2.3** | Alignment of AI policy with other policies | Mapping showing AI policy doesn't contradict info-sec, privacy, quality, code-of-conduct policies | New artifact; document the cross-references |

## A.3 — Internal Organization (severity: MAJOR)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.3.2** | AI roles & responsibilities | RACI matrix; named AIMS owner | ISO 27001 A.5.2; extend to AI |
| **A.3.3** | Reporting of concerns | Whistleblower / concerns procedure for AI-specific issues (bias, harm, misuse) | Existing whistleblower; AI-extend |

## A.4 — Resources (severity: MAJOR)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.4.2** | Resources — data | Data inventory; provenance; quality assessment | ISO 27001 A.5.9 inventory of assets — extend |
| **A.4.3** | Resources — tooling | Inventory of ML tooling; license & dependency tracking | Existing software-asset management |
| **A.4.4** | Resources — human resources | Competence requirements + training records (Clause 7.2) | ISO 27001 A.6.3 awareness; ISO 13485 6.2 competence |

## A.5 — Impact Assessment (severity: CRITICAL)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.5.2** | AI system impact assessment | Documented impact assessment for each AI system; covers individuals, groups, society | GDPR DPIA — partial; AI scope wider (third-party harm, environmental, societal) |
| **A.5.3** | Process for impact assessment | Documented procedure with triggers (launch, material change, complaint) | New procedure |
| **A.5.4** | Documentation of impact assessment | Signed impact assessment record with management approval for high-impact systems | New artifact |

## A.6 — AI System Lifecycle (severity: CRITICAL)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.6.1.2** | Objectives for AI system development | Stated AI-system objectives aligned to AI policy + use intent | New artifact (per system) |
| **A.6.1.3** | Processes for management of the AI system lifecycle | Procedure covering design → data → model → V&V → deployment → operation → decommission | New procedure |
| **A.6.2.2** | AI system objectives & requirements | Documented requirements traceable to objectives | ISO 13485 7.3 design & development — extend |
| **A.6.2.3** | Documentation of AI system design & development | Design records (architecture, datasets, model card) under document control | ISO 13485 7.3 — extend |
| **A.6.2.4** | Verification & validation of AI system | Test plan + evaluation results; defined acceptance criteria | New artifact per system; reference NIST AI RMF "Measure" function |
| **A.6.2.5** | Deployment of AI system | Deployment checklist; environment hand-off; rollback plan | ISO 27001 A.8.32 change management — extend |
| **A.6.2.6** | Operation & monitoring of AI system | Monitoring plan with thresholds + escalation | New per system |
| **A.6.2.7** | Technical documentation of AI system | Model card or system card per Mitchell et al. (2019) / Gebru et al. (2021) | New artifact |

## A.7 — Data for AI Systems (severity: CRITICAL)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.7.2** | Data management | Data lifecycle procedure (acquisition → use → retention → deletion) | GDPR Art. 5 data minimisation; ISO 27001 A.5.10 acceptable use |
| **A.7.3** | Data quality | Defined data-quality dimensions; measured; reported | New; reference DAMA-DMBOK 2 / ISO 8000 |
| **A.7.4** | Data provenance | Documented data lineage; consent / legitimate basis recorded | GDPR records of processing (Art. 30) — extend |
| **A.7.5** | Data preparation | Documented preprocessing procedure | New artifact per system |
| **A.7.6** | Data privacy considerations | Privacy review per data category | GDPR DPIA — extend |

## A.8 — Information for Interested Parties (severity: MAJOR)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.8.2** | System documentation | Public-facing documentation per Annex A.6.2.7 | Model card / system card |
| **A.8.3** | User information | UX-level disclosure: this is AI; what it does; its limitations | New; align with EU AI Act Article 50 transparency |
| **A.8.4** | Communication of AI incidents | Incident communication procedure including external notification timing | GDPR Art. 33–34 breach notification — extend |
| **A.8.5** | Information for affected parties | Communication for AI-affected populations (those subject to AI decisions) | New; align with EU AI Act Article 86 redress |

## A.9 — Use of AI Systems (severity: MAJOR)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.9.2** | Intended use of AI system | Documented intended-use statement per system | New artifact |
| **A.9.3** | Monitoring of operation | Continuous monitoring with defined metrics + thresholds | NIST AI RMF "Measure" — extend |
| **A.9.4** | Logging of AI system events | Tamper-evident logs covering decisions, drift indicators, incidents | ISO 27001 A.8.15 logging — extend |
| **A.9.5** | Use of system after deployment | Procedure for in-use changes (retraining, fine-tuning) with re-evaluation triggers | New procedure |

## A.10 — Third-Party & Customer Relationships (severity: MAJOR)

| Control | Title | What auditor wants | Reusable from |
|---|---|---|---|
| **A.10.2** | Supplier (third-party) relationships | AI-specific contract clauses (training data use, drift notification, sub-processor list) | ISO 27001 A.5.19 supplier relationships — extend |
| **A.10.3** | Customer relationships | Customer-facing AI obligations (transparency, opt-out, redress) | ISO 27001 A.5.20 — extend |
| **A.10.4** | Allocation of responsibilities between organization & third party | RACI for shared AI responsibilities (data labeling, model training, hosting, monitoring) | New artifact (per supplier) |
| **A.10.5** | Confidentiality of AI-related information | NDA scope covers AI-system internals (architecture, training data, weights) | ISO 27001 A.6.6 confidentiality — extend |
| **A.10.6** | Termination of AI service relationships | Procedure for safe AI-vendor exit (data return, model deletion, monitoring transition) | ISO 27001 A.5.20 service-level review — extend |

## How to Read This Catalogue

- **CRITICAL** = nonconformity blocks certification at stage 1
- **MAJOR** = nonconformity requires corrective action plan at stage 2; may delay certification
- **MINOR** = nonconformity recorded; corrective action expected within agreed timeline

**Audit evidence rule:** for every control selected as applicable, the auditor will ask three questions: (1) Where is the documented procedure? (2) Where are the records showing the procedure was followed? (3) Where is the evidence of management review of those records? If any of the three is missing, the control is partially implemented.

## When This Reference Doesn't Help

- **Specific Annex A control text.** This is a summary. The normative text is in ISO/IEC 42001:2023 Annex A — buy the standard.
- **Risk-to-control mapping methodology.** See `aims_implementation_guide.md` and ISO/IEC 23894:2023.
- **EU AI Act control overlap.** See `cross_framework_mapping_ai.md`.

---

**Source authorities (non-exhaustive):**

- **ISO/IEC 42001:2023** — Annex A normative controls (the authoritative source)
- **ISO/IEC 23894:2023** — AI risk management process (drives Annex A selection)
- **ISO/IEC 22989:2022** — AI concepts and terminology
- **NIST AI Risk Management Framework 1.0** (Jan 2023) + AI RMF Playbook — operational guidance mapping cleanly to Annex A
- **BSI AIC4 — Artificial Intelligence Cloud Service Compliance Criteria Catalogue** (2021) — sector-specific overlay for cloud AI providers
- **AAMI CR34971:2023** — Guidance for AI in medical devices
- **Mitchell et al.** — "Model Cards for Model Reporting" (FAT* 2019) — origin of model-card pattern referenced by A.6.2.7
- **Gebru et al.** — "Datasheets for Datasets" (CACM 2021) — datasheet pattern referenced by A.7.4
- **ISACA** — *Auditing Artificial Intelligence* (2nd ed., 2024) — practitioner audit checklist

FILE:references/aims_implementation_guide.md
# ISO/IEC 42001 — AIMS Implementation Guide (3-Year Maturity Model)

This reference answers exactly one decision: **what's the rollout sequence — what do we build in year 1 vs year 2 vs year 3, and how do we avoid recreating ISO 27001/13485 machinery?**

Pair with `scripts/aims_audit_scheduler.py` to operationalize the year-by-year audit cycle.

## The 3-Year Cycle

ISO management-system certifications follow a 3-year cycle:

| Year | Audit type | What happens |
|---|---|---|
| **Year 1** | Stage 1 (documentation review) + Stage 2 (implementation audit) → initial certification | Establish the AIMS; close major nonconformities; pass certification |
| **Year 2** | Surveillance audit (selective scope) | Demonstrate continual improvement; close minor nonconformities from year 1 |
| **Year 3** | Surveillance audit (selective scope) + recertification preparation | Full system review; prepare for year 4 recertification |
| **Year 4** | Recertification audit (full scope) | Renew certificate |

The internal audit programme (Clause 9.2) must cover every clause + every applicable Annex A control at least once per 3-year cycle. The plan must show this rolling coverage.

## Year 1 — Establish (focus: artifacts that auditors must see)

**Goal:** every clause and every applicable Annex A control has at least a documented procedure and one round of records.

### Q1: Foundations

- AI policy (Clause 5.2 + A.2.2) — board-signed
- AIMS scope statement (Clause 4.3) — names every AI system including third-party
- Roles & responsibilities (Clause 5.3 + A.3.2) — RACI with named AIMS owner
- Stakeholder & context analysis (Clause 4.1–4.2)

### Q2: Risk & impact

- AI risk register (Clause 6.1.2 + A.5) — run `ai_risk_register_builder.py`
- Risk treatment plan (Clause 6.1.3) — every high/critical risk linked to ≥ 1 Annex A control
- Impact assessment procedure (Clause 6.1.4 + A.5.3)
- AI objectives (Clause 6.2) — measurable targets

### Q3: Operations

- AI system lifecycle procedure (Clause 8.3 + A.6) — design through decommission
- Data management procedures (A.7) — data quality, provenance, preparation
- Monitoring plan per system (A.9.3)
- Third-party AI contract template (A.10.2)

### Q4: Performance

- Internal audit programme (Clause 9.2) — run `aims_audit_scheduler.py`
- Management review procedure (Clause 9.3) — inputs include AI-specific items
- CAPA integration with existing 13485/9001 CAPA loop (Clause 10.2)
- Stage 1 audit readiness check — run `aims_gap_analyzer.py`

**Year 1 success criteria:** stage 1 audit passes with 0 critical and ≤ 1 major nonconformity.

## Year 2 — Certify and operate

**Goal:** close year-1 minor nonconformities; demonstrate the system is operating, not just documented.

### Focus shifts to records (evidence the procedures are followed)

- Monthly drift monitoring records (A.9.3)
- Quarterly impact assessment reviews (A.5)
- Half-yearly third-party AI supplier reviews (A.10.2)
- Annual management review (Clause 9.3) with documented AI-specific inputs:
  - Risk register changes
  - Open nonconformities
  - Drift events outside threshold
  - Incidents per A.8.4
  - Performance trends vs objectives (Clause 6.2)

**Year 2 success criteria:** surveillance audit passes; year-1 nonconformities closed; ≥ 80% of risk-register treatments fully implemented.

## Year 3 — Continually improve

**Goal:** demonstrate continual improvement (Clause 10.1) and prepare for recertification.

- Annual update to risk register based on new AI systems, regulation changes, incidents
- Re-baseline objectives (Clause 6.2) against year-1 + year-2 performance
- Audit the audit programme itself (meta-audit; common surveillance finding)
- Demonstrate at least one improvement initiative closed with measurable result

**Year 3 success criteria:** surveillance audit passes; recertification scope confirmed; trend evidence supports continual improvement claim.

## Integration With Existing ISMS (ISO 27001) and QMS (ISO 13485 / 9001)

The mistake most organizations make: building the AIMS as a parallel management system. **Don't.** ISO 42001 is intentionally Annex SL aligned to allow integration. Common integration patterns:

| Existing artifact | Extend for AIMS by adding |
|---|---|
| ISMS scope statement | List of AI systems within ISMS scope |
| Information security policy | AI-specific commitments (fairness, human oversight) |
| Risk register (27001) | AI risks tagged distinctly; same severity matrix; same treatment workflow |
| Document control procedure | Add model cards + datasheets + impact assessments to controlled documents |
| Internal audit programme | Add AI clause + Annex A controls to rotation |
| Management review | Add AI inputs (drift, incidents, risk-register changes) |
| CAPA procedure | Add AI-specific root-cause categories (data quality, model drift, prompt injection) |
| Supplier management | Add AI-specific contract clauses |
| Incident response | Add AI incidents (bias surfaced, drift exceeded, model misuse) |

**Reuse rule of thumb:** if you already operate ISO 27001 + ISO 13485 maturely, ~60% of AIMS Clauses 4–10 effort is rewriting existing artifacts to include AI scope. The remaining ~40% is Annex A operational controls (risk register details, lifecycle, V&V, monitoring, model cards) which are genuinely new.

## Sequence If Starting From Zero (No Prior Management System)

If your organization is starting AIMS without prior ISO certification:

1. **Add ISO 27001 first.** Most AIMS Clauses 4–10 evidence is satisfied by ISO 27001 evidence with AI scope appended. Doing 42001 alone is harder.
2. **Or start with NIST AI RMF.** NIST AI RMF is voluntary and US-centric but maps cleanly to 42001 Annex A. Mature on RMF for 12–18 months, then layer the management-system formality of 42001 on top.
3. **Avoid: building AIMS in isolation.** You'll recreate document control, CAPA, management review, and internal audit infrastructure that ISO 27001/13485 already standardize.

## Cost & Effort Benchmarks (informal, practitioner-reported)

| Org type | Year 1 effort (FTE-months) | Notes |
|---|---|---|
| Mature 27001 + 13485 org adding AIMS | 4–6 | Mostly Annex A overlay |
| Mature 27001 org adding AIMS (no 13485) | 8–12 | Add lifecycle procedures (A.6) net-new |
| Greenfield (no prior management system) | 24–36 | Do 27001 first, then 42001 |

Certification body fees: ~$15k–$35k for initial certification audit (stage 1 + stage 2 for a typical mid-size SaaS); ~$8k–$15k per surveillance year.

## Common Year-1 Pitfalls

1. **Treating "AI ethics" as the policy.** A poetic policy doesn't pass; auditor wants concrete commitments and a way to verify them.
2. **Risk register with no control mapping.** Register identifies risks but doesn't show which Annex A control treats each — Clause 6.1.3 fails.
3. **Lifecycle procedure that skips decommission.** Auditor will ask, "How do you safely retire an AI system?" If silence, A.6 fails.
4. **No drift threshold defined.** Monitoring "we watch it" doesn't pass; needs metric + threshold + escalation owner.
5. **Third-party AI excluded.** "Our vendors' AI features aren't ours" is wrong if you embed them in your service.
6. **No competence requirement for ML engineers.** Clause 7.2 wants documented competence requirements per role; "they have PhDs" isn't a documented requirement.

## When This Reference Doesn't Help

- **Specific Annex A control implementation.** See `aims_controls_annex_a.md`.
- **Risk identification methodology.** See ISO/IEC 23894:2023.
- **EU AI Act overlap.** See `cross_framework_mapping_ai.md` and `compliance-team-eu-ai-act/`.

---

**Source authorities (non-exhaustive):**

- **ISO/IEC 42001:2023** — the standard itself
- **ISO/IEC 23894:2023** — AI risk management process
- **ISO/IEC 38507:2022** — Governance implications of AI for organizations
- **ISO/IEC 27001:2022** — Information security management (reuse template for 60% of AIMS Clauses 4–10)
- **ISO/IEC 13485:2016** — Medical device QMS (reuse template for CAPA, document control)
- **NIST AI RMF 1.0** (Jan 2023) + AI RMF Playbook + Generative AI Profile (NIST AI 600-1, 2024)
- **BSI** — *Information technology — Artificial intelligence — Implementation guidance for ISO/IEC 42001* (2024 white paper)
- **ISACA** — *Auditing Artificial Intelligence* (2nd ed., 2024) — implementation pitfalls catalogue
- **IAPP** — AI Governance Center materials (continuously updated) — practitioner community knowledge base

FILE:references/cross_framework_mapping_ai.md
# ISO/IEC 42001 ↔ EU AI Act ↔ NIST AI RMF ↔ ISO 23894 ↔ ISO 38507 ↔ ISO 27001 — Cross-Framework Mapping

This reference answers exactly one decision: **for each ISO 42001 obligation, which other frameworks already cover it, and what evidence can I reuse?**

The point of cross-framework mapping is to avoid duplicate work. A control implemented for ISO 27001 frequently satisfies an Annex A control of ISO 42001 with minor AI-specific overlay. The `compliance-os` orchestrator's `cross_framework_mapper.py` consumes this mapping.

## High-Level Framework Comparison

| Framework | Type | Binding? | AI scope | Maturity |
|---|---|---|---|---|
| **ISO/IEC 42001:2023** | Management system standard | Voluntary; certifiable | AI Management System (AIMS) | Published 2023; certifications starting 2024 |
| **EU AI Act (Reg. 2024/1689)** | Product safety regulation | Binding in EU | Risk-based: prohibited → high-risk → limited-risk → minimal-risk | In force Aug 2024; phased obligations through 2027 |
| **NIST AI RMF 1.0** | Risk management framework | Voluntary (US) | Govern / Map / Measure / Manage functions | Released Jan 2023; mature playbook |
| **ISO/IEC 23894:2023** | Risk management methodology | Reference standard | AI risk process; informs 42001 Clause 6.1 | Published 2023 |
| **ISO/IEC 38507:2022** | Governance standard | Reference standard | Board-level AI governance | Published 2022 |
| **ISO/IEC 27001:2022** | Management system standard | Voluntary; certifiable | Information security | Mature; widely certified |

## Clause-to-Framework Mapping (ISO 42001 lens)

### Clause 4 — Context

| ISO 42001 | EU AI Act | NIST AI RMF | ISO 27001 | Notes |
|---|---|---|---|---|
| 4.1 External context | Art. 1 (scope); Recitals on risk-based approach | GOVERN 1.1 | 4.1 | Extend 27001 context with AI regulatory landscape |
| 4.2 Interested parties | Art. 27 (FRIA stakeholders for high-risk) | GOVERN 5 | 4.2 | Add AI-affected populations |
| 4.3 Scope | Article 6 + Annex III define what's in scope as "high-risk" | MAP 1.1 | 4.3 | Distinct artifacts; AIMS scope ≠ EU AI Act applicability scope |
| 4.4 AIMS processes | n/a | n/a | 4.4 | Integration map |

### Clause 5 — Leadership

| ISO 42001 | EU AI Act | NIST AI RMF | ISO 27001 / ISO 38507 |
|---|---|---|---|
| 5.1 Top-mgmt commitment | Art. 26 (deployer obligations); Art. 16 (provider obligations) | GOVERN 1 | 27001 5.1; 38507 Clauses 5–6 (governance principles) |
| 5.2 AI policy | Art. 17 (QMS for high-risk); Art. 95 (codes of conduct) | GOVERN 1.1 | 27001 5.2 — extend with AI commitments |
| 5.3 Roles & authorities | Art. 26 (deployer obligations); Art. 16 + 22 (authorized representative) | GOVERN 2.1 | 27001 5.3 |

### Clause 6 — Planning (the densest mapping)

| ISO 42001 | EU AI Act | NIST AI RMF | ISO 23894 |
|---|---|---|---|
| 6.1.2 AI risk assessment | Art. 9 (risk management system for high-risk) | MAP 5.1; MAP 5.2 | Clauses 6–7 (entire process) |
| 6.1.3 AI risk treatment | Art. 9(2)(c–d) (risk management measures) | MANAGE 1.1 | Clauses 8 (treatment selection) |
| 6.1.4 Impact assessment | Art. 27 (Fundamental Rights Impact Assessment for high-risk public-sector deployers) | MAP 2.3; MAP 5.1 | Clause 5.3 (scope definition) |
| 6.2 AI objectives | Art. 9(2)(a) (objectives of risk management) | GOVERN 1.5; MEASURE 1 | Clause 5.2 |

### Clause 7 — Support

| ISO 42001 | EU AI Act | NIST AI RMF | ISO 27001 |
|---|---|---|---|
| 7.1 Resources | Art. 17(1)(c) (technical resources for QMS) | GOVERN 3 | A.6.1 |
| 7.2 Competence | Art. 14 (human oversight competence); Art. 26(2) (deployer competence) | GOVERN 3.1 | A.6.3 |
| 7.3 Awareness | Art. 14 | GOVERN 5.1 | A.6.3 |
| 7.4 Communication | Art. 50 (transparency obligations); Art. 86 (right to explanation) | GOVERN 5.2 | A.7.4 |
| 7.5 Documented info | Art. 11 + 12 (technical documentation); Art. 19 (record-keeping) | GOVERN 1.4 | 27001 7.5 |

### Clause 8 — Operation

| ISO 42001 | EU AI Act | NIST AI RMF | Notes |
|---|---|---|---|
| 8.1 Operational planning | Art. 17 (QMS) | MANAGE 2 | |
| 8.2 Impact assessment process | Art. 27 (FRIA process) | MAP 2 | |
| 8.3 AI system lifecycle | Art. 9 (full lifecycle); Art. 72 (post-market monitoring) | MAP 3; MEASURE 3; MANAGE 4 | Densest overlap |
| 8.4 Third-party / customer | Art. 25 (responsibilities along the AI value chain) | GOVERN 6 | |

### Clause 9 — Performance

| ISO 42001 | EU AI Act | NIST AI RMF | ISO 27001 |
|---|---|---|---|
| 9.1 Monitoring | Art. 72 (post-market monitoring system) | MEASURE 2; MEASURE 4 | 9.1 |
| 9.2 Internal audit | Art. 17(1)(j) (internal audit as part of QMS) | GOVERN 4 | 9.2 |
| 9.3 Management review | n/a explicit; implied in Art. 17 | GOVERN 1 | 9.3 |

### Clause 10 — Improvement

| ISO 42001 | EU AI Act | NIST AI RMF | ISO 27001 |
|---|---|---|---|
| 10.1 Continual improvement | Art. 9(2)(c) (iterative risk reduction) | MANAGE 4.3 | 10.1 |
| 10.2 Nonconformity & CAPA | Art. 73 (incident reporting); Art. 79 (corrective actions) | MANAGE 4.2 | 10.2 |

## Annex A Control → Framework Mapping (subset of highest-value mappings)

| ISO 42001 Annex A | EU AI Act | NIST AI RMF | ISO 27001 | Mapping confidence |
|---|---|---|---|---|
| A.2.2 AI policy | Art. 95 (codes of conduct) | GOVERN 1.1 | A.5.1 (info-sec policy) | HIGH |
| A.5.2 Impact assessment | Art. 27 FRIA | MAP 2.3 | n/a | MEDIUM (FRIA narrower) |
| A.6.2.4 V&V | Art. 15 (accuracy, robustness, cybersecurity); Art. 17(1)(h) | MEASURE 2 | n/a | HIGH |
| A.7.2 Data management | Art. 10 (data governance) | MAP 2.3; MEASURE 2.6 | A.5.10 | HIGH |
| A.7.3 Data quality | Art. 10(3) (relevance, representativeness, error-free, complete) | MEASURE 2.6 | n/a | HIGH |
| A.7.4 Data provenance | Art. 10(2)(d) (data origin) | MAP 2.3 | n/a | HIGH |
| A.7.6 Data privacy | Art. 10(5) (special categories); GDPR Articles 5, 6, 9 | MANAGE 2.1 | A.5.34 | HIGH |
| A.8.2 System docs | Art. 11 + Annex IV (technical documentation) | GOVERN 1.4 | A.5.37 | HIGH |
| A.8.3 User information | Art. 13 (instructions for use); Art. 50 (transparency) | GOVERN 5.2 | n/a | HIGH |
| A.8.4 Incident communication | Art. 73 (incident reporting to authorities) | MANAGE 4.2 | A.6.8 (reporting) | HIGH |
| A.9.3 Monitoring | Art. 72 (post-market monitoring) | MEASURE 2; MEASURE 4 | A.8.15 (logging) | HIGH |
| A.9.4 Logging | Art. 12 (record-keeping); Art. 19 | MEASURE 4 | A.8.15 | HIGH |
| A.10.2 Supplier relationships | Art. 25 (responsibilities along the AI value chain) | GOVERN 6 | A.5.19, A.5.20, A.5.21 | HIGH |

**Mapping confidence legend:**
- **HIGH** — direct overlap; same evidence can satisfy both
- **MEDIUM** — partial overlap; existing evidence with AI overlay
- **LOW** — concept overlap; mostly new artifact required

## Practical Reuse Pattern

If you operate ISO 27001 (mature) + are adopting ISO 42001:

1. **Reuse policies (~60%):** Extend info-sec policy with AI commitments (5.2 + A.2.2)
2. **Reuse procedures (~50%):** Document control, internal audit, management review, CAPA
3. **Reuse risk machinery (~70%):** Same severity matrix, same treatment workflow, same residual-risk acceptance flow — just add AI-specific risks and Annex A control mapping
4. **Reuse supplier mgmt (~80%):** Add AI-specific contract clauses to existing supplier procedure
5. **New artifacts (~40%):** Model cards / datasheets (A.6.2.7, A.7.4), impact assessments per Annex A.5, lifecycle procedure (A.6), drift monitoring (A.9.3), V&V procedure (A.6.2.4)

If you also operate ISO 13485 (medical device QMS):

- Reuse: design controls (7.3) for A.6 lifecycle; risk management (ISO 14971) overlays cleanly onto A.5 + 6.1; post-market surveillance maps directly to A.9.3 monitoring
- Add: AI-specific failure modes to ISO 14971 hazard analysis

## When This Reference Doesn't Help

- **EU AI Act conformity assessment routing.** See `compliance-team-eu-ai-act/scripts/conformity_assessment_planner.py`.
- **NIST AI RMF deep-dive.** See NIST AI RMF Playbook (NIST.AI.100-1.pdf) and Generative AI Profile (NIST.AI.600-1).
- **Multi-framework audit simulation.** See `compliance-os/scripts/audit_simulator.py`.

---

**Source authorities (non-exhaustive):**

- **ISO/IEC 42001:2023** — Annex A normative controls
- **Regulation (EU) 2024/1689** — Artificial Intelligence Act — full Articles (the binding regulation)
- **NIST AI Risk Management Framework 1.0** (Jan 2023, NIST AI 100-1) + AI RMF Playbook
- **ISO/IEC 23894:2023** — AI risk management process
- **ISO/IEC 38507:2022** — Governance implications of AI
- **ISO/IEC 27001:2022** + Annex A controls (the most cross-walked partner standard)
- **EDPB Opinion 28/2024** — Guidelines on processing of personal data in AI models
- **European Commission AI Act Guidelines** (continuously updated): Guidelines on prohibited practices (Feb 2025), Guidelines on definition of AI system (Feb 2025), FRIA template guidance
- **BSI** — *Cross-walking ISO 42001 and EU AI Act* (white paper, 2024)
- **IAPP EU AI Act Tracker** (continuously updated) — practitioner reference for Article applicability

FILE:references/iso42001_clauses.md
# ISO/IEC 42001:2023 — Clauses 4-10 Walkthrough

This reference answers exactly one decision: **for each clause of ISO 42001, what audit evidence does the certification body expect, and which existing ISMS/QMS artifact can I reuse?**

Pair with `scripts/aims_gap_analyzer.py` for automated coverage scoring.

## Annex SL High-Level Structure

ISO/IEC 42001:2023 follows the Annex SL structure shared by ISO 9001, 14001, 27001, 13485, 45001, and other management-system standards. This is deliberate: certification bodies, internal auditors, and quality teams can apply existing competencies to AIMS audits with low ramp-up cost.

**Practical implication:** if your organization already operates ISO 27001 + ISO 13485, ~60% of Clauses 4–10 artefacts (scope statements, policies, document control, internal audit programme, management review) can be **extended** to cover AI scope rather than recreated. The gap analysis is mostly Annex A (AI-specific operational controls), not Clauses 4–10.

## Clause 4 — Context of the Organization

| Sub-clause | Requirement | Audit evidence | Common gap |
|---|---|---|---|
| **4.1** | External & internal issues affecting AIMS | Documented context analysis (PESTLE or equivalent); reviewed at management review | Treating AI regulatory landscape as static; missing EU AI Act, US state laws, sector-specific AI rules |
| **4.2** | Needs & expectations of interested parties | Stakeholder matrix: customers, regulators, employees, data subjects, model providers, AI-affected populations | Omitting "AI-affected populations" (people who never interact with the system but are subject to its decisions) |
| **4.3** | AIMS scope statement | Documented scope: which AI systems, which lifecycle phases, which organizational units, which exclusions | Scope omits third-party AI services (SaaS features powered by vendor models); excludes "experimental" systems that are in fact in production |
| **4.4** | AIMS processes & interactions | Process map showing how AIMS processes connect to existing QMS/ISMS processes | Treating AIMS as parallel system instead of integrated extension of existing management systems |

**Reusable from ISO 27001 / 13485:** scope statement template, stakeholder matrix template, process map.

## Clause 5 — Leadership

| Sub-clause | Requirement | Audit evidence | Common gap |
|---|---|---|---|
| **5.1** | Top-management commitment | Documented evidence: AI in board agenda, resource allocation, KPIs | "AI ethics" reduced to marketing copy with no operating commitment |
| **5.2** | AI policy | Signed AI policy committing to lawful use, beneficial purpose, human oversight, continual improvement | Policy doesn't mention human oversight (Annex A.9 requirement); missing commitment to continual improvement |
| **5.3** | Organizational roles, responsibilities, authorities | RACI matrix for AIMS roles; named AIMS owner; AI ethics review board (if applicable) | No named AIMS owner; CISO assumed to "cover AI" without explicit assignment |

**Critical:** Clause 5.2 has a higher evidence bar than ISO 27001/13485 because the AI policy must address fairness, transparency, and human oversight — concepts absent from older management systems. Cannot be satisfied by extending existing policies; needs net-new content.

## Clause 6 — Planning

| Sub-clause | Requirement | Audit evidence | Common gap |
|---|---|---|---|
| **6.1.2** | AI risk assessment | Risk register per ISO 23894 methodology; covers full AI lifecycle | Risk identification at deployment only, missing data + model + decommission phases |
| **6.1.3** | AI risk treatment | Treatment plan linking each risk to Annex A controls; residual-risk acceptance documented | Treatment plan exists but is generic ("apply A.7.3") without specific implementation |
| **6.1.4** | AI system impact assessment | Documented impact assessment per Annex A.5.2 for high-impact systems | Confusing impact assessment (Clause 6.1.4) with risk assessment (Clause 6.1.2) |
| **6.2** | AI objectives | Measurable AI objectives aligned to AI policy; reviewed in management review | Objectives are aspirational ("ethical AI") without measurable targets |

**Run** `ai_risk_register_builder.py` to operationalize 6.1.2 + 6.1.3.

## Clause 7 — Support

| Sub-clause | Requirement | Audit evidence | Common gap |
|---|---|---|---|
| **7.1** | Resources for AIMS | Budget; tooling; compute resources documented | Compute resources for ML training treated as one-off project cost, not ongoing AIMS resource |
| **7.2** | Competence | Defined competence requirements per role (ML eng, AI risk, data steward); training records | Competence requirements undefined for ML engineers; assumes "they have degrees" |
| **7.3** | Awareness | AI awareness training across all employees with AI-system access | Training is engineer-only; product, marketing, customer success bypass |
| **7.4** | Communication | Documented internal + external communications procedure for AI | No procedure for communicating AI incidents to users (Annex A.8.4 link) |
| **7.5** | Documented information | Version-controlled AIMS documentation | Model cards exist but are not under document control; can be edited without approval |

## Clause 8 — Operation

| Sub-clause | Requirement | Audit evidence | Common gap |
|---|---|---|---|
| **8.1** | Operational planning & control | Operational procedures for each AI lifecycle phase | Operations procedures don't define phase transitions (when does "development" become "production"?) |
| **8.2** | Impact assessment process | Operational procedure for triggering impact assessment; gate before launch | Impact assessment treated as one-time launch artifact, not re-triggered on material change |
| **8.3** | AI system lifecycle process | Documented lifecycle covering: design → data → model → V&V → deployment → operation → decommission | Lifecycle skips "decommission"; no procedure for sunsetting AI systems |
| **8.4** | Third-party / customer relationships | Supplier and customer relationship procedures; AI-specific clauses in contracts | Standard vendor contracts not updated for AI-specific obligations (data use, model retraining, drift) |

## Clause 9 — Performance Evaluation

| Sub-clause | Requirement | Audit evidence | Common gap |
|---|---|---|---|
| **9.1** | Monitoring, measurement, analysis & evaluation | Defined metrics for AI performance, fairness, drift; monitoring records | Drift monitoring in code but no defined acceptable drift threshold; no escalation path |
| **9.2** | Internal audit programme | 12-month audit plan; auditor independence documented; findings tracked | No formal AIMS audit programme; audits happen ad hoc; auditors audit own work |
| **9.3** | Management review | Documented management review at planned intervals with required inputs/outputs | Management review inputs missing AI-specific items (drift, incidents, risk-register changes) |

**Run** `aims_audit_scheduler.py` to generate the 9.2 plan with independence checks.

## Clause 10 — Improvement

| Sub-clause | Requirement | Audit evidence | Common gap |
|---|---|---|---|
| **10.1** | Continual improvement | Evidence of AIMS improvement over time (KPIs trending, control maturity rising) | "Continual improvement" treated as audit closure activity, not ongoing |
| **10.2** | Nonconformity & corrective action | CAPA records for AIMS nonconformities; root cause analysis documented | AIMS CAPA loop separate from existing 13485/9001 CAPA loop — duplicated effort, divergent procedures |

**Reusable from ISO 13485 / 9001:** the entire CAPA machinery. Add AI-specific root-cause categories (data quality, model drift, prompt injection, etc.) to the existing taxonomy.

## When This Reference Doesn't Help

- **Specific AI risk identification.** See `aims_controls_annex_a.md` and ISO/IEC 23894:2023.
- **EU AI Act conformity assessment.** Different standard. See `compliance-team-eu-ai-act`.
- **Model cards, datasheets, evaluation methodology.** Tactical artefacts; reference NIST AI RMF playbook + papers like Mitchell et al. (2019).

---

**Source authorities (non-exhaustive):**

- **ISO/IEC 42001:2023** — Information technology — Artificial intelligence — Management system (the standard itself; published 2023-12-18 by ISO/IEC JTC 1/SC 42)
- **ISO/IEC 23894:2023** — AI risk management process (the methodology referenced by Clause 6.1.2)
- **ISO/IEC 38507:2022** — Governance implications of AI for organizations (board-level governance lens referenced by Clause 5)
- **ISO/IEC 22989:2022** — AI concepts and terminology (definitions used throughout)
- **Annex SL** in the ISO/IEC Directives Part 1 (2024) — the high-level structure shared by ISO management-system standards
- **BSI AI Management System (AIMS) Implementation Guide** (BSI, 2024) — practitioner walkthrough
- **AAMI CR34971:2023** — AI guidance for medical devices (cross-walks 42001 to medical device QMS)
- **ISACA** — *Auditing Artificial Intelligence* (2nd ed., 2024) — internal-audit-oriented checklist with ISO 42001 mapping

FILE:scripts/aims_audit_scheduler.py
#!/usr/bin/env python3
"""aims_audit_scheduler.py — ISO/IEC 42001 Clause 9.2 internal audit plan generator.

Stdlib-only. Produces a 12-month internal audit schedule for an AIMS with:
  - quarterly audit slots
  - clause + Annex A control coverage per slot
  - auditor assignments with independence checks (no self-audit)
  - rolling 3-year coverage to ensure every clause + applicable control is audited
  - prior-year nonconformity follow-up scheduled in Q1

Deterministic logic. No LLM calls. Stdlib only.

Input schema (JSON):
{
  "organization": "Acme AI Inc.",
  "audit_year": 2026,
  "certification_cycle_phase": "year_2",   # year_1 | year_2 | year_3 | surveillance
  "ai_systems_in_scope": ["recommendation_engine", "internal_llm_tools", "vendor_ai_chatbot"],
  "applicable_annex_a_controls": ["A.2.2", "A.3.2", "A.5.2", "A.6.2.4", "A.7.3", "A.8.4", "A.9.3", "A.10.2"],
  "auditors": [
    {"id": "alice", "name": "Alice Chen", "role": "quality_engineer", "owns_clauses": ["8.3"]},
    {"id": "bob", "name": "Bob Singh", "role": "ml_engineer", "owns_clauses": ["8.3", "A.6.2.4"]},
    {"id": "carol", "name": "Carol Diaz", "role": "external_auditor", "owns_clauses": []},
    {"id": "dave", "name": "Dave Park", "role": "ciso", "owns_clauses": ["A.10.2"]}
  ],
  "prior_year_findings": [
    {"clause": "9.2", "severity": "major", "status": "open"},
    {"clause": "A.7.3", "severity": "minor", "status": "closed"}
  ]
}

Usage:
    python aims_audit_scheduler.py
    python aims_audit_scheduler.py path/to/scope.json
    python aims_audit_scheduler.py scope.json --output json
"""

import argparse
import json
import sys
from typing import Any, Dict, List


SAMPLE: Dict[str, Any] = {
    "organization": "Acme AI Inc.",
    "audit_year": 2026,
    "certification_cycle_phase": "year_2",
    "ai_systems_in_scope": ["recommendation_engine", "internal_llm_tools", "vendor_ai_chatbot"],
    "applicable_annex_a_controls": [
        "A.2.2", "A.3.2", "A.5.2", "A.6.2.4", "A.7.3", "A.8.4", "A.9.3", "A.10.2"
    ],
    "auditors": [
        {"id": "alice", "name": "Alice Chen", "role": "quality_engineer", "owns_clauses": ["8.3"]},
        {"id": "bob", "name": "Bob Singh", "role": "ml_engineer", "owns_clauses": ["8.3", "A.6.2.4"]},
        {"id": "carol", "name": "Carol Diaz", "role": "external_auditor", "owns_clauses": []},
        {"id": "dave", "name": "Dave Park", "role": "ciso", "owns_clauses": ["A.10.2"]},
    ],
    "prior_year_findings": [
        {"clause": "9.2", "severity": "major", "status": "open"},
        {"clause": "A.7.3", "severity": "minor", "status": "closed"},
    ],
}


# Always-audit clauses (full coverage every year)
ANNUAL_CLAUSES = ["4.3", "5.1", "5.2", "5.3", "9.3", "10.2"]

# 3-year rotation for deep-dive clauses
ROTATION_Q2 = ["6.1.2", "6.1.3", "6.1.4", "6.2"]
ROTATION_Q3 = ["7.1", "7.2", "7.3", "7.4", "7.5", "8.1", "8.2", "8.3", "8.4"]
ROTATION_Q4 = ["9.1", "9.2", "10.1"]


def assign_auditor(scope_items: List[str], auditors: List[Dict[str, Any]]) -> Dict[str, Any]:
    """Pick the auditor with the fewest independence conflicts in this scope."""
    best_auditor = None
    best_conflicts = 999
    for a in auditors:
        owns = set(a.get("owns_clauses", []))
        conflicts = sum(1 for s in scope_items if s in owns)
        if conflicts < best_conflicts:
            best_conflicts = conflicts
            best_auditor = a
    if best_auditor is None:
        return {"id": None, "name": "UNASSIGNED", "independent": False, "conflicts": []}

    owns = set(best_auditor.get("owns_clauses", []))
    conflicts = [s for s in scope_items if s in owns]
    return {
        "id": best_auditor["id"],
        "name": best_auditor["name"],
        "role": best_auditor["role"],
        "independent": len(conflicts) == 0,
        "conflicts": conflicts,
    }


def build_quarter(label: str, scope_clauses: List[str], scope_controls: List[str],
                  auditors: List[Dict[str, Any]], extra_notes: str = "") -> Dict[str, Any]:
    all_scope = scope_clauses + scope_controls
    auditor = assign_auditor(all_scope, auditors)
    return {
        "quarter": label,
        "scope_clauses": scope_clauses,
        "scope_annex_a_controls": scope_controls,
        "auditor": auditor,
        "notes": extra_notes,
    }


def plan(payload: Dict[str, Any]) -> Dict[str, Any]:
    year = int(payload.get("audit_year", 2026))
    phase = payload.get("certification_cycle_phase", "year_2")
    systems = payload.get("ai_systems_in_scope", [])
    controls = payload.get("applicable_annex_a_controls", [])
    auditors = payload.get("auditors", [])
    prior_findings = payload.get("prior_year_findings", [])
    open_priors = [f for f in prior_findings if f.get("status") != "closed"]

    # 3-year control rotation: split applicable controls into thirds
    third = max(1, len(controls) // 3)
    controls_y1 = controls[0:third]
    controls_y2 = controls[third:2 * third]
    controls_y3 = controls[2 * third:]
    phase_to_controls = {
        "year_1": controls_y1, "year_2": controls_y2,
        "year_3": controls_y3, "surveillance": controls_y3,
    }
    this_year_controls = phase_to_controls.get(phase, controls_y2)

    # Q1: leadership + scope + prior-year follow-up
    q1_clauses = ["4.3", "5.1", "5.2", "5.3"]
    q1_notes = f"Follow up {len(open_priors)} open prior-year finding(s)." if open_priors else "No open priors."
    q1 = build_quarter(f"Q1 {year}", q1_clauses, [], auditors, q1_notes)

    # Q2: planning + objectives + risk
    q2 = build_quarter(f"Q2 {year}", ROTATION_Q2, this_year_controls[:max(1, len(this_year_controls) // 2)], auditors)

    # Q3: support + operation
    q3_controls = this_year_controls[max(1, len(this_year_controls) // 2):]
    q3_notes = f"Deep-dive across {len(systems)} AI systems: {', '.join(systems)}."
    q3 = build_quarter(f"Q3 {year}", ROTATION_Q3, q3_controls, auditors, q3_notes)

    # Q4: performance + improvement + management review
    q4_notes = "Management review inputs prepared per Clause 9.3."
    q4 = build_quarter(f"Q4 {year}", ROTATION_Q4 + ANNUAL_CLAUSES[-2:], [], auditors, q4_notes)

    # Independence audit
    quarters = [q1, q2, q3, q4]
    independence_issues = [{
        "quarter": q["quarter"], "auditor": q["auditor"]["name"], "conflicts": q["auditor"]["conflicts"]
    } for q in quarters if not q["auditor"]["independent"]]

    # Coverage check
    audited_clauses = set()
    audited_controls = set()
    for q in quarters:
        audited_clauses.update(q["scope_clauses"])
        audited_controls.update(q["scope_annex_a_controls"])

    return {
        "organization": payload.get("organization"),
        "audit_year": year,
        "certification_cycle_phase": phase,
        "ai_systems_in_scope": systems,
        "open_prior_findings": len(open_priors),
        "quarters": quarters,
        "independence_issues": independence_issues,
        "coverage_summary": {
            "clauses_audited_this_year": sorted(audited_clauses),
            "controls_audited_this_year": sorted(audited_controls),
            "controls_deferred_to_future_years": sorted(
                set(controls) - audited_controls
            ),
        },
    }


def render_text(p: Dict[str, Any], source: str) -> str:
    lines = []
    lines.append("=" * 72)
    lines.append("ISO/IEC 42001 — CLAUSE 9.2 INTERNAL AUDIT PLAN")
    lines.append(f"Source: {source}")
    lines.append("=" * 72)
    lines.append("")
    lines.append(f"Organization: {p['organization']}")
    lines.append(f"Year: {p['audit_year']}  |  Cert cycle phase: {p['certification_cycle_phase']}")
    lines.append(f"AI systems in scope: {', '.join(p['ai_systems_in_scope'])}")
    lines.append(f"Open prior-year findings: {p['open_prior_findings']}")
    lines.append("")
    lines.append("-" * 72)
    lines.append("QUARTERLY SCHEDULE:")
    lines.append("")

    for q in p["quarters"]:
        a = q["auditor"]
        flag = "" if a["independent"] else "  ⚠️ INDEPENDENCE CONFLICT"
        lines.append(f"  {q['quarter']}  →  Auditor: {a['name']} ({a['role']}){flag}")
        if q["scope_clauses"]:
            lines.append(f"      Clauses: {', '.join(q['scope_clauses'])}")
        if q["scope_annex_a_controls"]:
            lines.append(f"      Annex A: {', '.join(q['scope_annex_a_controls'])}")
        if a["conflicts"]:
            lines.append(f"      ⚠️ Conflicts on: {', '.join(a['conflicts'])} — reassign or use external auditor")
        if q["notes"]:
            lines.append(f"      Notes: {q['notes']}")
        lines.append("")

    if p["independence_issues"]:
        lines.append("-" * 72)
        lines.append(f"INDEPENDENCE ISSUES ({len(p['independence_issues'])}):")
        for issue in p["independence_issues"]:
            lines.append(f"  - {issue['quarter']}: {issue['auditor']} owns {', '.join(issue['conflicts'])}")
        lines.append("")

    c = p["coverage_summary"]
    lines.append("-" * 72)
    lines.append("3-YEAR COVERAGE STATUS:")
    lines.append(f"  Clauses audited this year ({len(c['clauses_audited_this_year'])}): {', '.join(c['clauses_audited_this_year'])}")
    lines.append(f"  Annex A controls audited this year ({len(c['controls_audited_this_year'])}): {', '.join(c['controls_audited_this_year']) or 'none'}")
    lines.append(f"  Controls deferred to future years ({len(c['controls_deferred_to_future_years'])}): {', '.join(c['controls_deferred_to_future_years']) or 'none'}")
    lines.append("")
    lines.append("RULES: every clause + every applicable Annex A control must be audited at least once per 3-year cert cycle.")
    lines.append("       Same auditor cannot audit work they own (Clause 9.2 independence).")
    return "\n".join(lines)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="ISO/IEC 42001 Clause 9.2 internal audit 12-month plan generator.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("path", nargs="?", help="Path to audit scope JSON (uses embedded sample if omitted)")
    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
    args = parser.parse_args()

    if args.path:
        try:
            with open(args.path, "r", encoding="utf-8") as f:
                payload = json.load(f)
            source = args.path
        except (IOError, OSError) as e:
            print(f"error: could not read {args.path}: {e}", file=sys.stderr)
            return 1
        except json.JSONDecodeError as e:
            print(f"error: invalid JSON in {args.path}: {e}", file=sys.stderr)
            return 1
    else:
        payload = SAMPLE
        source = "<embedded sample: year-2 cert cycle, 3 systems, 8 controls applicable>"

    result = plan(payload)
    if args.output == "json":
        print(json.dumps({"source": source, **result}, indent=2))
    else:
        print(render_text(result, source))
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/aims_gap_analyzer.py
#!/usr/bin/env python3
"""aims_gap_analyzer.py — ISO/IEC 42001:2023 AIMS gap analysis against Clauses 4-10.

Stdlib-only. Scores each clause as 'full' / 'partial' / 'missing' based on an evidence
inventory and outputs a prioritized remediation list with severity at certification audit.

Deterministic logic. No LLM calls. No external dependencies.

Input schema (JSON):
{
  "organization": "Acme AI Inc.",
  "scope_statement": "Customer-facing recommendation engine + internal LLM tools",
  "certification_target": "stage_1_audit_in_q3",
  "evidence": {
    "4.1_context_external": "documented",
    "4.2_interested_parties": "documented",
    "4.3_scope_statement": "documented",
    "4.4_aims_processes": "partial",
    "5.1_leadership_commitment": "documented",
    "5.2_ai_policy": "partial",
    "5.3_roles_responsibilities": "missing",
    "6.1.2_risk_assessment": "documented",
    "6.1.3_risk_treatment": "partial",
    "6.1.4_impact_assessment": "missing",
    "6.2_objectives": "documented",
    "7.1_resources": "documented",
    "7.2_competence": "missing",
    "7.3_awareness": "partial",
    "7.4_communication": "documented",
    "7.5_documented_info": "documented",
    "8.1_operational_planning": "documented",
    "8.2_impact_assessment_process": "partial",
    "8.3_ai_system_lifecycle": "missing",
    "8.4_third_party_relationships": "partial",
    "9.1_monitoring": "partial",
    "9.2_internal_audit": "missing",
    "9.3_management_review": "documented",
    "10.1_continual_improvement": "partial",
    "10.2_nonconformity_capa": "documented"
  }
}

Usage:
    python aims_gap_analyzer.py                       # uses embedded sample
    python aims_gap_analyzer.py path/to/evidence.json
    python aims_gap_analyzer.py evidence.json --output json
"""

import argparse
import json
import sys
from typing import Any, Dict, List


SAMPLE: Dict[str, Any] = {
    "organization": "Acme AI Inc.",
    "scope_statement": "Customer-facing recommendation engine + internal LLM tools",
    "certification_target": "stage_1_audit_in_q3",
    "evidence": {
        "4.1_context_external": "documented",
        "4.2_interested_parties": "documented",
        "4.3_scope_statement": "documented",
        "4.4_aims_processes": "partial",
        "5.1_leadership_commitment": "documented",
        "5.2_ai_policy": "partial",
        "5.3_roles_responsibilities": "missing",
        "6.1.2_risk_assessment": "documented",
        "6.1.3_risk_treatment": "partial",
        "6.1.4_impact_assessment": "missing",
        "6.2_objectives": "documented",
        "7.1_resources": "documented",
        "7.2_competence": "missing",
        "7.3_awareness": "partial",
        "7.4_communication": "documented",
        "7.5_documented_info": "documented",
        "8.1_operational_planning": "documented",
        "8.2_impact_assessment_process": "partial",
        "8.3_ai_system_lifecycle": "missing",
        "8.4_third_party_relationships": "partial",
        "9.1_monitoring": "partial",
        "9.2_internal_audit": "missing",
        "9.3_management_review": "documented",
        "10.1_continual_improvement": "partial",
        "10.2_nonconformity_capa": "documented",
    },
}


# Clause requirements + severity if missing
# severity: 'critical' = major nonconformity at stage 1, blocks certification
#           'major' = major nonconformity at stage 2
#           'minor' = minor nonconformity, requires corrective action plan
#           'observation' = improvement opportunity
CLAUSE_REQUIREMENTS: Dict[str, Dict[str, Any]] = {
    "4.1_context_external": {"clause": "4.1", "title": "External & internal context", "severity": "minor"},
    "4.2_interested_parties": {"clause": "4.2", "title": "Interested parties", "severity": "minor"},
    "4.3_scope_statement": {"clause": "4.3", "title": "AIMS scope statement", "severity": "critical"},
    "4.4_aims_processes": {"clause": "4.4", "title": "AIMS processes & interactions", "severity": "major"},
    "5.1_leadership_commitment": {"clause": "5.1", "title": "Leadership commitment", "severity": "major"},
    "5.2_ai_policy": {"clause": "5.2", "title": "AI policy", "severity": "critical"},
    "5.3_roles_responsibilities": {"clause": "5.3", "title": "Roles, responsibilities, authorities", "severity": "critical"},
    "6.1.2_risk_assessment": {"clause": "6.1.2", "title": "AI risk assessment", "severity": "critical"},
    "6.1.3_risk_treatment": {"clause": "6.1.3", "title": "AI risk treatment", "severity": "critical"},
    "6.1.4_impact_assessment": {"clause": "6.1.4", "title": "AI system impact assessment", "severity": "major"},
    "6.2_objectives": {"clause": "6.2", "title": "AI objectives & planning", "severity": "minor"},
    "7.1_resources": {"clause": "7.1", "title": "Resources", "severity": "minor"},
    "7.2_competence": {"clause": "7.2", "title": "Competence", "severity": "major"},
    "7.3_awareness": {"clause": "7.3", "title": "Awareness", "severity": "minor"},
    "7.4_communication": {"clause": "7.4", "title": "Communication", "severity": "minor"},
    "7.5_documented_info": {"clause": "7.5", "title": "Documented information", "severity": "major"},
    "8.1_operational_planning": {"clause": "8.1", "title": "Operational planning & control", "severity": "major"},
    "8.2_impact_assessment_process": {"clause": "8.2", "title": "Impact assessment process", "severity": "major"},
    "8.3_ai_system_lifecycle": {"clause": "8.3", "title": "AI system lifecycle process", "severity": "critical"},
    "8.4_third_party_relationships": {"clause": "8.4", "title": "Third-party / customer relationships", "severity": "major"},
    "9.1_monitoring": {"clause": "9.1", "title": "Monitoring, measurement, analysis, evaluation", "severity": "major"},
    "9.2_internal_audit": {"clause": "9.2", "title": "Internal audit programme", "severity": "critical"},
    "9.3_management_review": {"clause": "9.3", "title": "Management review", "severity": "critical"},
    "10.1_continual_improvement": {"clause": "10.1", "title": "Continual improvement", "severity": "minor"},
    "10.2_nonconformity_capa": {"clause": "10.2", "title": "Nonconformity & corrective action", "severity": "major"},
}

STATUS_SCORE = {"documented": 1.0, "partial": 0.5, "missing": 0.0}
SEVERITY_RANK = {"critical": 0, "major": 1, "minor": 2, "observation": 3}


def remediation_action(req_key: str, status: str) -> str:
    """Deterministic one-sentence next step per (clause, status)."""
    if status == "documented":
        return "Maintain via management review; re-verify at next internal audit."
    titles = CLAUSE_REQUIREMENTS[req_key]["title"]
    if status == "partial":
        return f"Complete documentation of '{titles}' — confirm signoff, version control, evidence trail."
    return f"Create from scratch: '{titles}'. Assign owner; target close before stage 1 audit."


def analyze(payload: Dict[str, Any]) -> Dict[str, Any]:
    evidence = payload.get("evidence", {})
    findings: List[Dict[str, Any]] = []
    total_weight = 0.0
    achieved_weight = 0.0

    for req_key, meta in CLAUSE_REQUIREMENTS.items():
        status = evidence.get(req_key, "missing")
        score = STATUS_SCORE.get(status, 0.0)
        # Severity-weighted: critical = 4, major = 2, minor = 1
        weight = {"critical": 4, "major": 2, "minor": 1, "observation": 1}[meta["severity"]]
        total_weight += weight
        achieved_weight += weight * score

        findings.append({
            "clause": meta["clause"],
            "title": meta["title"],
            "status": status,
            "severity_if_missing": meta["severity"],
            "remediation": remediation_action(req_key, status),
        })

    coverage_pct = round((achieved_weight / total_weight) * 100, 1) if total_weight else 0

    # Sort findings: missing/partial first by severity, then documented last
    def sort_key(f: Dict[str, Any]) -> tuple:
        status_order = {"missing": 0, "partial": 1, "documented": 2}
        return (status_order[f["status"]], SEVERITY_RANK[f["severity_if_missing"]], f["clause"])

    findings.sort(key=sort_key)

    open_gaps = [f for f in findings if f["status"] != "documented"]
    critical_gaps = [f for f in open_gaps if f["severity_if_missing"] == "critical"]
    major_gaps = [f for f in open_gaps if f["severity_if_missing"] == "major"]

    readiness = "ready" if not critical_gaps and len(major_gaps) <= 1 else (
        "stage_2_candidate" if not critical_gaps else "not_ready"
    )

    return {
        "organization": payload.get("organization"),
        "scope": payload.get("scope_statement"),
        "coverage_pct_weighted": coverage_pct,
        "certification_readiness": readiness,
        "critical_gap_count": len(critical_gaps),
        "major_gap_count": len(major_gaps),
        "open_gap_count": len(open_gaps),
        "findings": findings,
    }


def render_text(r: Dict[str, Any], source: str) -> str:
    lines = []
    lines.append("=" * 72)
    lines.append("ISO/IEC 42001 AIMS — GAP ANALYSIS")
    lines.append(f"Source: {source}")
    lines.append("=" * 72)
    lines.append("")
    lines.append(f"Organization: {r['organization']}")
    lines.append(f"Scope: {r['scope']}")
    lines.append(f"Weighted coverage: {r['coverage_pct_weighted']}%")
    lines.append(f"Certification readiness: {r['certification_readiness']}")
    lines.append(f"Critical gaps: {r['critical_gap_count']}  |  Major gaps: {r['major_gap_count']}  |  Open total: {r['open_gap_count']}")
    lines.append("")
    lines.append("-" * 72)
    lines.append("FINDINGS (open gaps first; critical highlighted):")
    lines.append("")

    for f in r["findings"]:
        marker = {"missing": "[X] ", "partial": "[~] ", "documented": "[✓] "}[f["status"]]
        sev = f["severity_if_missing"].upper() if f["status"] != "documented" else "OK"
        lines.append(f"  {marker}Clause {f['clause']:6s}  {f['title']:50s}  [{sev}]")
        if f["status"] != "documented":
            lines.append(f"        → {f['remediation']}")
    lines.append("")
    lines.append("-" * 72)
    lines.append("READINESS RULE: 'ready' = 0 critical AND ≤ 1 major. 'stage_2_candidate' = 0 critical.")
    lines.append("                Any critical gap blocks stage 1 certification.")
    return "\n".join(lines)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="ISO/IEC 42001 AIMS gap analysis across Clauses 4-10.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("path", nargs="?", help="Path to AIMS evidence JSON (uses embedded sample if omitted)")
    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
    args = parser.parse_args()

    if args.path:
        try:
            with open(args.path, "r", encoding="utf-8") as f:
                payload = json.load(f)
            source = args.path
        except (IOError, OSError) as e:
            print(f"error: could not read {args.path}: {e}", file=sys.stderr)
            return 1
        except json.JSONDecodeError as e:
            print(f"error: invalid JSON in {args.path}: {e}", file=sys.stderr)
            return 1
    else:
        payload = SAMPLE
        source = "<embedded sample: mid-stage AI SaaS, pre stage-1 audit>"

    result = analyze(payload)
    if args.output == "json":
        print(json.dumps({"source": source, **result}, indent=2))
    else:
        print(render_text(result, source))
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/ai_risk_register_builder.py
#!/usr/bin/env python3
"""ai_risk_register_builder.py — ISO/IEC 42001 Annex A risk register + control mapping.

Stdlib-only. Takes identified AI risks (per ISO 23894 risk identification) and produces a
structured register with:
  - severity rating (likelihood × impact, 5x5 matrix)
  - mapped Annex A controls (treatment selection)
  - residual risk verdict (accept / additional treatment required / escalate)
  - treatment option per ISO 23894 (modify / share / retain / avoid)

Deterministic logic per ISO 23894:2023 risk-management process. No LLM calls.

Input schema (JSON):
{
  "organization": "Acme AI Inc.",
  "ai_system": "Customer recommendation engine v3",
  "risks": [
    {
      "id": "R-001",
      "source": "training_data",
      "event": "Biased dataset over-represents one demographic",
      "consequence": "Discriminatory recommendations; regulatory exposure",
      "likelihood": 3,           # 1-5
      "impact": 4,               # 1-5
      "controls_applied": ["A.7.3", "A.7.5", "A.5.2"]
    }
  ]
}

Usage:
    python ai_risk_register_builder.py                       # uses embedded 7-risk sample
    python ai_risk_register_builder.py path/to/risks.json
    python ai_risk_register_builder.py risks.json --output json
"""

import argparse
import json
import sys
from typing import Any, Dict, List


SAMPLE: Dict[str, Any] = {
    "organization": "Acme AI Inc.",
    "ai_system": "Customer recommendation engine v3",
    "risks": [
        {"id": "R-001", "source": "training_data", "event": "Biased dataset over-represents one demographic",
         "consequence": "Discriminatory recommendations; regulatory exposure", "likelihood": 3, "impact": 4,
         "controls_applied": ["A.7.3", "A.7.5", "A.5.2"]},
        {"id": "R-002", "source": "model", "event": "Concept drift after 6 months in production",
         "consequence": "Accuracy degradation; revenue impact", "likelihood": 4, "impact": 3,
         "controls_applied": ["A.9.3", "A.6.2.4"]},
        {"id": "R-003", "source": "deployment", "event": "Inference latency spike under load",
         "consequence": "User-visible failure; SLO breach", "likelihood": 3, "impact": 2,
         "controls_applied": ["A.9.3"]},
        {"id": "R-004", "source": "third_party", "event": "Foundation-model API provider deprecates endpoint",
         "consequence": "Service disruption; migration cost", "likelihood": 2, "impact": 4,
         "controls_applied": ["A.10.2"]},
        {"id": "R-005", "source": "data", "event": "Training data contains PII that should not be retained",
         "consequence": "GDPR fine; trust loss", "likelihood": 2, "impact": 5,
         "controls_applied": ["A.7.2", "A.7.4"]},
        {"id": "R-006", "source": "human_oversight", "event": "High-impact decisions deployed without impact assessment",
         "consequence": "Untracked harm; certification nonconformity", "likelihood": 3, "impact": 5,
         "controls_applied": []},
        {"id": "R-007", "source": "model", "event": "Adversarial prompt injection bypasses content filter",
         "consequence": "Toxic output to end users; reputational damage", "likelihood": 4, "impact": 4,
         "controls_applied": ["A.6.2.4", "A.9.3", "A.9.4"]},
    ],
}


# Severity matrix (5x5): likelihood (1-5) × impact (1-5)
# Score 1-4 = low, 5-9 = medium, 10-16 = high, 17-25 = critical
def severity_rating(likelihood: int, impact: int) -> str:
    score = max(1, min(5, likelihood)) * max(1, min(5, impact))
    if score <= 4:
        return "low"
    if score <= 9:
        return "medium"
    if score <= 16:
        return "high"
    return "critical"


# ISO 23894 risk treatment options
# - modify (apply controls to reduce likelihood/impact)
# - share (transfer via insurance, third-party contracts)
# - retain (accept residual risk with management signoff)
# - avoid (eliminate the activity entirely)
def treatment_option(severity: str, controls_count: int) -> str:
    if severity == "critical" and controls_count == 0:
        return "avoid_or_escalate"
    if severity in ("high", "critical"):
        return "modify"
    if severity == "medium":
        return "modify" if controls_count < 2 else "retain"
    return "retain"


# Residual-risk verdict after applied controls
def residual_verdict(severity: str, controls_count: int) -> str:
    """How many controls are 'enough' for each severity tier (heuristic, ISO 23894 Annex A guidance)."""
    expected = {"low": 0, "medium": 1, "high": 2, "critical": 3}[severity]
    if controls_count >= expected:
        return "acceptable" if severity != "critical" else "acceptable_with_management_signoff"
    return "additional_treatment_required"


# Annex A control descriptions (subset, for output annotation)
ANNEX_A_CATALOG: Dict[str, str] = {
    "A.2.2": "AI policy",
    "A.2.3": "Alignment of AI policy with other organizational policies",
    "A.3.2": "AI roles & responsibilities",
    "A.3.3": "Reporting of concerns",
    "A.4.2": "Resources for AI systems — data",
    "A.4.3": "Resources for AI systems — tooling",
    "A.4.4": "Resources for AI systems — human resources",
    "A.5.2": "AI system impact assessment",
    "A.5.4": "Documentation of impact assessment",
    "A.6.2.2": "AI system objectives",
    "A.6.2.3": "AI system lifecycle phases",
    "A.6.2.4": "Verification & validation of AI system",
    "A.7.2": "Data management for AI systems",
    "A.7.3": "Data quality",
    "A.7.4": "Data provenance",
    "A.7.5": "Data preparation",
    "A.8.2": "System documentation for users",
    "A.8.3": "User information",
    "A.8.4": "Communication of AI incidents",
    "A.9.2": "Intended use of AI system",
    "A.9.3": "Monitoring of AI system operation",
    "A.9.4": "Logging of AI system events",
    "A.10.2": "Supplier (third-party) relationships",
    "A.10.3": "Customer relationships",
}


def annotate_risk(risk: Dict[str, Any]) -> Dict[str, Any]:
    likelihood = int(risk.get("likelihood", 0))
    impact = int(risk.get("impact", 0))
    controls = list(risk.get("controls_applied", []))
    sev = severity_rating(likelihood, impact)
    treatment = treatment_option(sev, len(controls))
    residual = residual_verdict(sev, len(controls))

    return {
        "id": risk.get("id"),
        "source": risk.get("source"),
        "event": risk.get("event"),
        "consequence": risk.get("consequence"),
        "likelihood": likelihood,
        "impact": impact,
        "severity_score": likelihood * impact,
        "severity": sev,
        "controls_applied": [{"id": c, "title": ANNEX_A_CATALOG.get(c, "<unknown control>")} for c in controls],
        "control_count": len(controls),
        "treatment_option": treatment,
        "residual_verdict": residual,
    }


def analyze(payload: Dict[str, Any]) -> Dict[str, Any]:
    risks = [annotate_risk(r) for r in payload.get("risks", [])]
    # Sort by severity (critical first), then by control gap (largest first)
    sev_rank = {"critical": 0, "high": 1, "medium": 2, "low": 3}
    risks.sort(key=lambda r: (sev_rank[r["severity"]], -r["severity_score"]))

    counts_by_sev = {s: 0 for s in sev_rank}
    requires_action = 0
    for r in risks:
        counts_by_sev[r["severity"]] += 1
        if r["residual_verdict"] == "additional_treatment_required":
            requires_action += 1

    return {
        "organization": payload.get("organization"),
        "ai_system": payload.get("ai_system"),
        "total_risks": len(risks),
        "by_severity": counts_by_sev,
        "requires_additional_treatment": requires_action,
        "risks": risks,
    }


def render_text(r: Dict[str, Any], source: str) -> str:
    lines = []
    lines.append("=" * 72)
    lines.append("AI RISK REGISTER — ISO/IEC 42001 Annex A + ISO 23894 treatment")
    lines.append(f"Source: {source}")
    lines.append("=" * 72)
    lines.append("")
    lines.append(f"Organization: {r['organization']}")
    lines.append(f"AI system: {r['ai_system']}")
    lines.append(f"Total risks: {r['total_risks']}")
    s = r["by_severity"]
    lines.append(f"By severity:  critical={s['critical']}  high={s['high']}  medium={s['medium']}  low={s['low']}")
    lines.append(f"Risks requiring additional treatment: {r['requires_additional_treatment']}")
    lines.append("")
    lines.append("-" * 72)
    lines.append("REGISTER (highest severity first):")
    lines.append("")

    for risk in r["risks"]:
        lines.append(f"  [{risk['id']}] {risk['event']}")
        lines.append(f"      Source: {risk['source']}  |  L={risk['likelihood']} × I={risk['impact']} = {risk['severity_score']}  →  {risk['severity'].upper()}")
        lines.append(f"      Consequence: {risk['consequence']}")
        if risk["controls_applied"]:
            ctrl_str = ", ".join(c["id"] for c in risk["controls_applied"])
            lines.append(f"      Controls applied ({risk['control_count']}): {ctrl_str}")
        else:
            lines.append(f"      Controls applied: NONE")
        lines.append(f"      Treatment option: {risk['treatment_option']}")
        lines.append(f"      Residual verdict: {risk['residual_verdict']}")
        lines.append("")

    lines.append("-" * 72)
    lines.append("RULES:")
    lines.append("  - 'critical' severity (score 17-25) WITHOUT controls → 'avoid_or_escalate' to management.")
    lines.append("  - 'additional_treatment_required' → add Annex A controls or formally accept residual risk in writing.")
    lines.append("  - All 'retain' verdicts require Clause 6.1.3 risk-treatment plan signoff.")
    return "\n".join(lines)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="ISO/IEC 42001 Annex A risk register builder with ISO 23894 treatment options.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("path", nargs="?", help="Path to risks JSON (uses embedded sample if omitted)")
    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
    args = parser.parse_args()

    if args.path:
        try:
            with open(args.path, "r", encoding="utf-8") as f:
                payload = json.load(f)
            source = args.path
        except (IOError, OSError) as e:
            print(f"error: could not read {args.path}: {e}", file=sys.stderr)
            return 1
        except json.JSONDecodeError as e:
            print(f"error: invalid JSON in {args.path}: {e}", file=sys.stderr)
            return 1
    else:
        payload = SAMPLE
        source = "<embedded sample: 7-risk recommendation engine register>"

    result = analyze(payload)
    if args.output == "json":
        print(json.dumps({"source": source, **result}, indent=2))
    else:
        print(render_text(result, source))
    return 0


if __name__ == "__main__":
    sys.exit(main())

---
name: "marketing-context"
description: "Create and maintain the marketing context document that all marketing skills read before starting. Use when the user mentions 'marketing context,' 'brand voice,' 'set up context,' 'target audience,' 'ICP,' 'style guide,' 'who is my customer,' 'positioning,' or wants to avoid repeating foundational information across marketing tasks. Run this at the start of any new project before using other marketing skills."
license: MIT
metadata:
  version: 1.0.0
  author: Alireza Rezvani
  category: marketing
  updated: 2026-03-06
---

# Marketing Context

You are an expert product marketer. Your goal is to capture the foundational positioning, messaging, and brand context that every other marketing skill needs — so users never repeat themselves.

The document is stored at `.agents/marketing-context.md` (or `marketing-context.md` in the project root).

## How This Skill Works

### Mode 1: Auto-Draft from Codebase
Study the repo — README, landing pages, marketing copy, about pages, package.json, existing docs — and draft a V1. The user reviews, corrects, and fills gaps. This is faster than starting from scratch.

### Mode 2: Guided Interview
Walk through each section conversationally, one at a time. Don't dump all questions at once.

### Mode 3: Update Existing
Read the current context, summarize what's captured, and ask which sections need updating.

Most users prefer Mode 1. After presenting the draft, ask: *"What needs correcting? What's missing?"*

---

## Sections to Capture

### 1. Product Overview
- One-line description
- What it does (2-3 sentences)
- Product category (the "shelf" — how customers search for you)
- Product type (SaaS, marketplace, e-commerce, service)
- Business model and pricing

### 2. Target Audience
- Target company type (industry, size, stage)
- Target decision-makers (roles, departments)
- Primary use case (the main problem you solve)
- Jobs to be done (2-3 things customers "hire" you for)
- Specific use cases or scenarios

### 3. Personas
For each stakeholder involved in buying:
- Role (User, Champion, Decision Maker, Financial Buyer, Technical Influencer)
- What they care about, their challenge, the value you promise them

### 4. Problems & Pain Points
- Core challenge customers face before finding you
- Why current solutions fall short
- What it costs them (time, money, opportunities)
- Emotional tension (stress, fear, doubt)

### 5. Competitive Landscape
- **Direct competitors**: Same solution, same problem
- **Secondary competitors**: Different solution, same problem
- **Indirect competitors**: Conflicting approach entirely
- How each falls short for customers

### 6. Differentiation
- Key differentiators (capabilities alternatives lack)
- How you solve it differently
- Why that's better (benefits, not features)
- Why customers choose you over alternatives

### 7. Objections & Anti-Personas
- Top 3 objections heard in sales + how to address each
- Who is NOT a good fit (anti-persona)

### 8. Switching Dynamics (JTBD Four Forces)
- **Push**: Frustrations driving them away from current solution
- **Pull**: What attracts them to you
- **Habit**: What keeps them stuck with current approach
- **Anxiety**: What worries them about switching

### 9. Customer Language (Verbatim)
- How customers describe the problem in their own words
- How they describe your solution in their own words
- Words and phrases TO use
- Words and phrases to AVOID
- Glossary of product-specific terms

### 10. Brand Voice
- Tone (professional, casual, playful, authoritative)
- Communication style (direct, conversational, technical)
- Brand personality (3-5 adjectives)
- Voice DO's and DON'T's

### 11. Style Guide
- Grammar and mechanics rules
- Capitalization conventions
- Formatting standards
- Preferred terminology

### 12. Proof Points
- Key metrics or results to cite
- Notable customers / logos
- Testimonial snippets (verbatim)
- Main value themes with supporting evidence

### 13. Content & SEO Context
- Target keywords (organized by topic cluster)
- Internal links map (key pages, anchor text)
- Writing examples (3-5 exemplary pieces)
- Content tone and length preferences

### 14. Goals
- Primary business goal
- Key conversion action (what you want people to do)
- Current metrics (if known)

---

## Output Template

See `templates/marketing-context-template.md` for the full template.

---

## Tips

- **Be specific**: Ask "What's the #1 frustration that brings them to you?" not "What problem do they solve?"
- **Capture exact words**: Customer language beats polished descriptions
- **Ask for examples**: "Can you give me an example?" unlocks better answers
- **Validate as you go**: Summarize each section and confirm before moving on
- **Skip what doesn't apply**: Not every product needs all sections

---

## Proactive Triggers

Surface these without being asked:

- **Missing customer language section** → "Without verbatim customer phrases, copy will sound generic. Can you share 3-5 quotes from customers describing their problem?"
- **No competitive landscape defined** → "Every marketing skill performs better with competitor context. Who are the top 3 alternatives your customers consider?"
- **Brand voice undefined** → "Without voice guidelines, every skill will sound different. Let's define 3-5 adjectives that capture your brand."
- **Context older than 6 months** → "Your marketing context was last updated [date]. Positioning may have shifted — review recommended."
- **No proof points** → "Marketing without proof points is opinion. What metrics, logos, or testimonials can we reference?"

## Output Artifacts

| When you ask for... | You get... |
|---------------------|------------|
| "Set up marketing context" | Guided interview → complete `marketing-context.md` |
| "Auto-draft from codebase" | Codebase scan → V1 draft for review |
| "Update positioning" | Targeted update of differentiation + competitive sections |
| "Add customer quotes" | Customer language section populated with verbatim phrases |
| "Review context freshness" | Staleness audit with recommended updates |

## Communication

All output passes quality verification:
- Self-verify: source attribution, assumption audit, confidence scoring
- Output format: Bottom Line → What (with confidence) → Why → How to Act
- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.

## Related Skills

- **marketing-ops**: Routes marketing questions to the right skill — reads this context first.
- **copywriting**: For landing page and web copy. Reads brand voice + customer language from this context.
- **content-strategy**: For planning what content to create. Reads target keywords + personas from this context.
- **marketing-strategy-pmm**: For positioning and GTM strategy. Reads competitive landscape from this context.
- **cs-onboard** (C-Suite): For company-level context. This skill is marketing-specific — complements, not replaces, company-context.md.

FILE:scripts/context_validator.py
#!/usr/bin/env python3
"""Validate marketing context completeness — scores 0-100."""

import json
import re
import sys
from pathlib import Path

SECTIONS = {
    "Product Overview": {"required": True, "weight": 10, "markers": ["one-liner", "what it does", "product category", "business model"]},
    "Target Audience": {"required": True, "weight": 12, "markers": ["target compan", "decision-maker", "use case", "jobs to be done"]},
    "Personas": {"required": False, "weight": 5, "markers": ["persona", "champion", "decision maker"]},
    "Problems & Pain Points": {"required": True, "weight": 10, "markers": ["core problem", "fall short", "cost", "tension"]},
    "Competitive Landscape": {"required": True, "weight": 10, "markers": ["direct", "competitor", "secondary"]},
    "Differentiation": {"required": True, "weight": 10, "markers": ["differentiator", "differently", "why customers choose"]},
    "Objections": {"required": False, "weight": 5, "markers": ["objection", "response", "anti-persona"]},
    "Switching Dynamics": {"required": False, "weight": 5, "markers": ["push", "pull", "habit", "anxiety"]},
    "Customer Language": {"required": True, "weight": 10, "markers": ["verbatim", "words to use", "words to avoid"]},
    "Brand Voice": {"required": True, "weight": 8, "markers": ["tone", "style", "personality"]},
    "Style Guide": {"required": False, "weight": 3, "markers": ["grammar", "capitalization", "formatting"]},
    "Proof Points": {"required": True, "weight": 7, "markers": ["metric", "customer", "testimonial"]},
    "Content & SEO": {"required": False, "weight": 3, "markers": ["keyword", "internal link"]},
    "Goals": {"required": True, "weight": 2, "markers": ["business goal", "conversion"]}
}


def validate_context(content: str) -> dict:
    """Validate marketing context file and return score."""
    content_lower = content.lower()
    results = {"sections": {}, "score": 0, "max_score": 100, "missing_required": [], "missing_optional": [], "warnings": []}
    total_weight = sum(s["weight"] for s in SECTIONS.values())
    earned = 0

    for name, config in SECTIONS.items():
        section_present = name.lower().replace("& ", "").replace("  ", " ") in content_lower or any(
            m in content_lower for m in config["markers"][:2]
        )

        markers_found = sum(1 for m in config["markers"] if m in content_lower)
        markers_total = len(config["markers"])

        has_placeholder = bool(re.search(r'\[.*?\]', content[content_lower.find(name.lower()):content_lower.find(name.lower()) + 500] if name.lower() in content_lower else ""))

        if section_present and markers_found > 0:
            completeness = markers_found / markers_total
            if has_placeholder and completeness < 0.5:
                completeness *= 0.5  # Penalize unfilled templates
            section_score = round(config["weight"] * completeness)
            earned += section_score
            status = "complete" if completeness >= 0.75 else "partial"
        else:
            section_score = 0
            status = "missing"
            if config["required"]:
                results["missing_required"].append(name)
            else:
                results["missing_optional"].append(name)

        results["sections"][name] = {
            "status": status,
            "markers_found": markers_found,
            "markers_total": markers_total,
            "score": section_score,
            "max_score": config["weight"],
            "required": config["required"]
        }

    results["score"] = round((earned / total_weight) * 100)

    # Warnings
    if "verbatim" not in content_lower and '"' not in content:
        results["warnings"].append("No verbatim customer quotes found — copy will sound generic")
    if not re.search(r'\d+%|\$\d+|\d+ customer', content_lower):
        results["warnings"].append("No metrics or proof points with numbers found")
    if "last updated" in content_lower:
        date_match = re.search(r'last updated:?\s*(\d{4}-\d{2}-\d{2})', content_lower)
        if date_match:
            from datetime import datetime
            try:
                updated = datetime.strptime(date_match.group(1), "%Y-%m-%d")
                age_days = (datetime.now() - updated).days
                if age_days > 180:
                    results["warnings"].append(f"Context is {age_days} days old — review recommended (>180 days)")
            except ValueError:
                pass

    return results


def print_report(results: dict):
    """Print human-readable validation report."""
    print(f"\n{'='*50}")
    print(f"MARKETING CONTEXT VALIDATION")
    print(f"{'='*50}")
    print(f"\nOverall Score: {results['score']}/100")
    print(f"{'🟢 Strong' if results['score'] >= 80 else '🟡 Needs Work' if results['score'] >= 50 else '🔴 Incomplete'}")

    print(f"\n{'─'*50}")
    print(f"{'Section':<25} {'Status':<10} {'Score':<10}")
    print(f"{'─'*50}")
    for name, data in results["sections"].items():
        icon = {"complete": "✅", "partial": "⚠️", "missing": "❌"}[data["status"]]
        req = " *" if data["required"] else ""
        print(f"{icon} {name:<23} {data['status']:<10} {data['score']}/{data['max_score']}{req}")

    if results["missing_required"]:
        print(f"\n🔴 Missing Required Sections:")
        for s in results["missing_required"]:
            print(f"   → {s}")

    if results["missing_optional"]:
        print(f"\n🟡 Missing Optional Sections:")
        for s in results["missing_optional"]:
            print(f"   → {s}")

    if results["warnings"]:
        print(f"\n⚠️  Warnings:")
        for w in results["warnings"]:
            print(f"   → {w}")

    print(f"\n* = required section")
    print(f"{'='*50}")


def main():
    import argparse

    parser = argparse.ArgumentParser(
        description="Validates marketing context completeness. "
                    "Scores 0-100 based on required and optional section coverage."
    )
    parser.add_argument(
        "file", nargs="?", default=None,
        help="Path to a marketing context markdown file. "
             "If omitted, runs demo with embedded sample data."
    )
    parser.add_argument(
        "--json", action="store_true",
        help="Also output results as JSON."
    )
    args = parser.parse_args()

    if args.file:
        filepath = Path(args.file)
        if not filepath.exists():
            print(f"Error: File not found: {filepath}", file=sys.stderr)
            sys.exit(1)
        content = filepath.read_text()
    else:
        # Demo with sample data
        content = """# Marketing Context
*Last updated: 2026-01-15*

## Product Overview
**One-liner:** AI-powered mobility analysis for elderly care
**What it does:** Smartphone-based fall risk assessment using computer vision
**Product category:** HealthTech / Digital Health
**Business model:** SaaS, per-facility licensing

## Target Audience
**Target companies:** Care facilities, nursing homes, 50+ beds
**Decision-makers:** Facility directors, quality managers
**Primary use case:** Automated fall risk assessment replacing manual observation
**Jobs to be done:**
- Reduce fall incidents by identifying high-risk residents
- Meet regulatory documentation requirements efficiently
- Give care staff actionable mobility insights

## Problems & Pain Points
**Core problem:** Manual fall risk assessment is subjective, time-consuming, and inconsistent
**Why alternatives fall short:**
- Manual observation takes 30+ minutes per resident
- Paper-based assessments are completed once per quarter at best
**What it costs them:** Falls cost €8,000-12,000 per incident, plus liability
**Emotional tension:** Staff fear missing warning signs, blame after incidents

## Competitive Landscape
**Direct:** Traditional gait labs — $50K+ hardware, need trained staff
**Secondary:** Wearable sensors — low compliance, residents remove them
**Indirect:** Manual observation — subjective, inconsistent

## Differentiation
**Key differentiators:**
- Uses standard smartphone (no special hardware)
- AI-powered analysis (objective, repeatable)
**Why customers choose us:** Fast, affordable, no hardware investment

## Customer Language
**How they describe the problem:**
- "We never know who's going to fall next"
- "The documentation takes forever"
**Words to use:** mobility analysis, fall prevention, care quality
**Words to avoid:** surveillance, monitoring, tracking

## Brand Voice
**Tone:** Professional, empathetic, evidence-based
**Personality:** Trustworthy, innovative, caring

## Proof Points
**Metrics:**
- 80+ care facilities served
- 30% reduction in fall incidents (pilot data)
**Customers:** Major care facility chains in Germany

## Goals
**Business goal:** Expand to 200+ facilities, enter Spain and Netherlands
**Conversion action:** Book a demo
"""
        print("[Using embedded sample data — pass a file path for real validation]")

    results = validate_context(content)
    print_report(results)

    if args.json:
        print(f"\n{json.dumps(results, indent=2)}")


if __name__ == "__main__":
    main()

FILE:templates/marketing-context-template.md
# Marketing Context

*Last updated: [date]*

## Product Overview
**One-liner:** [What you do in one sentence]
**What it does:** [2-3 sentences]
**Product category:** [The "shelf" — how customers search for you]
**Product type:** [SaaS, marketplace, e-commerce, service]
**Business model:** [Pricing model and range]

## Target Audience
**Target companies:** [Industry, size, stage]
**Decision-makers:** [Roles, departments]
**Primary use case:** [The main problem you solve]
**Jobs to be done:**
- [Job 1]
- [Job 2]
- [Job 3]
**Use cases:**
- [Scenario 1]
- [Scenario 2]

## Personas

| Persona | Role | Cares about | Challenge | Value we promise |
|---------|------|-------------|-----------|------------------|
| [Name] | User | | | |
| [Name] | Champion | | | |
| [Name] | Decision Maker | | | |
| [Name] | Financial Buyer | | | |

## Problems & Pain Points
**Core problem:** [What customers face before finding you]
**Why alternatives fall short:**
- [Gap 1]
- [Gap 2]
**What it costs them:** [Time, money, opportunities]
**Emotional tension:** [Stress, fear, doubt]

## Competitive Landscape

| Competitor | Type | How they fall short |
|-----------|------|---------------------|
| [Name] | Direct | [Gap] |
| [Name] | Secondary | [Gap] |
| [Name] | Indirect | [Gap] |

## Differentiation
**Key differentiators:**
- [Differentiator 1]
- [Differentiator 2]
**How we do it differently:** [Approach]
**Why that's better:** [Benefits]
**Why customers choose us:** [Decision drivers]

## Objections

| Objection | Response |
|-----------|----------|
| "[Objection 1]" | [How to address] |
| "[Objection 2]" | [How to address] |
| "[Objection 3]" | [How to address] |

**Anti-persona (NOT a good fit):** [Who should NOT buy this]

## Switching Dynamics
**Push (away from current):** [Frustrations]
**Pull (toward us):** [Attractions]
**Habit (keeping them stuck):** [Inertia]
**Anxiety (about switching):** [Worries]

## Customer Language
**How they describe the problem:**
- "[verbatim quote]"
- "[verbatim quote]"
**How they describe us:**
- "[verbatim quote]"
- "[verbatim quote]"
**Words to use:** [list]
**Words to avoid:** [list]

| Term | Meaning |
|------|---------|
| [Product term] | [Definition] |

## Brand Voice
**Tone:** [professional, casual, playful, authoritative]
**Style:** [direct, conversational, technical]
**Personality:** [3-5 adjectives]
**Voice DO's:** [list]
**Voice DON'T's:** [list]

## Style Guide
**Grammar:** [Key rules]
**Capitalization:** [Conventions]
**Formatting:** [Standards]
**Preferred terms:** [List]

## Proof Points
**Metrics:**
- [Metric 1]
- [Metric 2]
**Customers:** [Notable logos]
**Testimonials:**
> "[quote]" — [Name, Title, Company]
> "[quote]" — [Name, Title, Company]

| Value Theme | Supporting Proof |
|-------------|-----------------|
| [Theme 1] | [Evidence] |
| [Theme 2] | [Evidence] |

## Content & SEO Context
**Target keywords:**

| Cluster | Primary Keyword | Secondary Keywords | Intent |
|---------|----------------|-------------------|--------|
| [Topic 1] | [keyword] | [kw1, kw2] | [informational/commercial] |

**Internal links map:**

| Page | URL | Use for | Anchor text |
|------|-----|---------|-------------|
| [Page name] | [URL] | [Topic] | [Suggested anchor] |

**Writing examples:**
- [URL or file — what makes it good]

## Goals
**Business goal:** [Primary objective]
**Conversion action:** [What you want people to do]
**Current metrics:** [If known]

---
name: "engineering-skills"
description: "23 engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365. 30+ Python tools (stdlib-only)."
version: 2.9.0
author: Alireza Rezvani
license: MIT
tags:
  - engineering
  - frontend
  - backend
  - devops
  - security
  - ai-ml
  - data-engineering
agents:
  - claude-code
  - codex-cli
  - openclaw
---

# Engineering Team Skills

23 production-ready engineering skills organized into core engineering, AI/ML/Data, and specialized tools.

## Quick Start

### Claude Code
```
/read engineering-team/senior-fullstack/SKILL.md
```

### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/engineering-team
```

## Skills Overview

### Core Engineering (13 skills)

| Skill | Folder | Focus |
|-------|--------|-------|
| Senior Architect | `senior-architect/` | System design, architecture patterns |
| Senior Frontend | `senior-frontend/` | React, Next.js, TypeScript, Tailwind |
| Senior Backend | `senior-backend/` | API design, database optimization |
| Senior Fullstack | `senior-fullstack/` | Project scaffolding, code quality |
| Senior QA | `senior-qa/` | Test generation, coverage analysis |
| Senior DevOps | `senior-devops/` | CI/CD, infrastructure, containers |
| Senior SecOps | `senior-secops/` | Security operations, vulnerability management |
| Code Reviewer | `code-reviewer/` | PR review, code quality analysis |
| Senior Security | `senior-security/` | Threat modeling, STRIDE, penetration testing |
| AWS Solution Architect | `aws-solution-architect/` | Serverless, CloudFormation, cost optimization |
| MS365 Tenant Manager | `ms365-tenant-manager/` | Microsoft 365 administration |
| TDD Guide | `tdd-guide/` | Test-driven development workflows |
| Tech Stack Evaluator | `tech-stack-evaluator/` | Technology comparison, TCO analysis |

### AI/ML/Data (5 skills)

| Skill | Folder | Focus |
|-------|--------|-------|
| Senior Data Scientist | `senior-data-scientist/` | Statistical modeling, experimentation |
| Senior Data Engineer | `senior-data-engineer/` | Pipelines, ETL, data quality |
| Senior ML Engineer | `senior-ml-engineer/` | Model deployment, MLOps, LLM integration |
| Senior Prompt Engineer | `senior-prompt-engineer/` | Prompt optimization, RAG, agents |
| Senior Computer Vision | `senior-computer-vision/` | Object detection, segmentation |

### Specialized Tools (5 skills)

| Skill | Folder | Focus |
|-------|--------|-------|
| Playwright Pro | `playwright-pro/` | E2E testing (9 sub-skills) |
| Self-Improving Agent | `self-improving-agent/` | Memory curation (5 sub-skills) |
| Stripe Integration | `stripe-integration-expert/` | Payment integration, webhooks |
| Incident Commander | `incident-commander/` | Incident response workflows |
| Email Template Builder | `email-template-builder/` | HTML email generation |

## Python Tools

30+ scripts, all stdlib-only. Run directly:

```bash
python3 <skill>/scripts/<tool>.py --help
```

No pip install needed. Scripts include embedded samples for demo mode.

## Rules

- Load only the specific skill SKILL.md you need — don't bulk-load all 23
- Use Python tools for analysis and scaffolding, not manual judgment
- Check CLAUDE.md for tool usage examples and workflows

---
name: "marketing-skills"
description: "42 marketing agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more coding agents. 7 pods: content, SEO, CRO, channels, growth, intelligence, sales. Foundation context + orchestration router. 27 Python tools (stdlib-only)."
version: 2.9.0
author: Alireza Rezvani
license: MIT
tags:
  - marketing
  - seo
  - content
  - copywriting
  - cro
  - analytics
  - ai-seo
agents:
  - claude-code
  - codex-cli
  - openclaw
---

# Marketing Skills Division

42 production-ready marketing skills organized into 7 specialist pods with a context foundation and orchestration layer.

## Quick Start

### Claude Code
```
/read marketing-skill/marketing-ops/SKILL.md
```
The router will direct you to the right specialist skill.

### Codex CLI
```bash
codex --full-auto "Read marketing-skill/marketing-ops/SKILL.md, then help me write a blog post about [topic]"
```

### OpenClaw
Skills are auto-discovered from the repository. Ask your agent for marketing help — it routes via `marketing-ops`.

## Architecture

```
marketing-skill/
├── marketing-context/     ← Foundation: brand voice, audience, goals
├── marketing-ops/         ← Router: dispatches to the right skill
│
├── Content Pod (8)        ← Strategy → Production → Editing → Social
├── SEO Pod (5)            ← Traditional + AI SEO + Schema + Architecture
├── CRO Pod (6)            ← Pages, Forms, Signup, Onboarding, Popups, Paywall
├── Channels Pod (5)       ← Email, Ads, Cold Email, Ad Creative, Social Mgmt
├── Growth Pod (4)         ← A/B Testing, Referrals, Free Tools, Churn
├── Intelligence Pod (4)   ← Competitors, Psychology, Analytics, Campaigns
└── Sales & GTM Pod (2)    ← Pricing, Launch Strategy
```

## First-Time Setup

Run `marketing-context` to create your `marketing-context.md` file. Every other skill reads this for brand voice, audience personas, and competitive landscape. Do this once — it makes everything better.

## Pod Overview

| Pod | Skills | Python Tools | Key Capabilities |
|-----|--------|-------------|-----------------|
| **Foundation** | 2 | 2 | Brand context capture, skill routing |
| **Content** | 8 | 5 | Strategy → production → editing → humanization |
| **SEO** | 5 | 2 | Technical SEO, AI SEO (AEO/GEO), schema, architecture |
| **CRO** | 6 | 0 | Page, form, signup, onboarding, popup, paywall optimization |
| **Channels** | 5 | 2 | Email sequences, paid ads, cold email, ad creative |
| **Growth** | 4 | 2 | A/B testing, referral programs, free tools, churn prevention |
| **Intelligence** | 4 | 4 | Competitor analysis, marketing psychology, analytics, campaigns |
| **Sales & GTM** | 2 | 1 | Pricing strategy, launch planning |
| **Standalone** | 4 | 9 | ASO, brand guidelines, PMM strategy, prompt engineering |

## Python Tools (27 scripts)

All scripts are stdlib-only (zero pip installs), CLI-first with JSON output, and include embedded sample data for demo mode.

```bash
# Content scoring
python3 marketing-skill/content-production/scripts/content_scorer.py article.md

# AI writing detection
python3 marketing-skill/content-humanizer/scripts/humanizer_scorer.py draft.md

# Brand voice analysis
python3 marketing-skill/content-production/scripts/brand_voice_analyzer.py copy.txt

# Ad copy validation
python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py ads.json

# Pricing scenario modeling
python3 marketing-skill/pricing-strategy/scripts/pricing_modeler.py

# Tracking plan generation
python3 marketing-skill/analytics-tracking/scripts/tracking_plan_generator.py
```

## Unique Features

- **AI SEO (AEO/GEO/LLMO)** — Optimize for AI citation, not just ranking
- **Content Humanizer** — Detect and fix AI writing patterns with scoring
- **Context Foundation** — One brand context file feeds all 42 skills
- **Orchestration Router** — Smart routing by keyword + complexity scoring
- **Zero Dependencies** — All Python tools use stdlib only

---
name: market-research
description: Use when doing upstream market-research methodology — sizing a market as TAM/SAM/SOM computed BOTH top-down and bottoms-up (never a single unsourced number), planning a survey sample size with finite-population correction and per-segment minimums, or scoring candidate market segments against Kotler's measurable/substantial/accessible/differentiable/actionable criteria. Outputs always show the method and the assumptions. For market-research analysts and product-marketing at the sizing/survey/segmentation moment. Distinct from marketing-skill (campaign analytics, attribution, demand-gen) — this is the evidence-building methodology, not live-campaign optimization.
version: 2.9.0
author: claude-code-skills
license: MIT
tags: [research-ops, market-research, tam-sam-som, market-sizing, survey, sampling, segmentation, competitive-intelligence]
compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
---

# market-research

Upstream market-research methodology: market sizing, survey/sampling design, and segmentation. The discipline here is **method + assumptions**: a TAM is never a single number, a survey is never powered only in aggregate, and a segment is never a demographic slice.

## Purpose

Market-research analysts, product marketers, and strategy teams need rigorous evidence *before* anyone optimizes a campaign or sets a strategy. This skill structures three methodology decisions:

Three deterministic tools:

1. `market_sizer.py` — Computes TAM/SAM/SOM by **both** top-down and bottoms-up methods side-by-side, reports the divergence, and flags failed triangulation. Never returns a single number.
2. `sample_size_planner.py` — Survey sample size from confidence, margin of error, and expected proportion, with the finite-population correction and **per-segment minimums** (a survey powered overall is not powered per reported segment).
3. `segmentation_scorer.py` — Scores candidate segments against Kotler's five criteria and enforces a substantiality + accessibility gate; a slice that is too small or unreachable is dropped.

## When to use

Invoke this skill when:

- A board or exec asks "how big is this market?" and you need a defensible, triangulated answer.
- You are fielding a survey and need a sample size that holds up per segment, not just overall.
- You have a list of candidate segments and need to know which are real markets vs demographic slices.
- You are synthesizing competitive intelligence and need a methodological backbone.

**Do NOT use this skill to**: measure a live campaign (attribution, ROAS, CPA → `marketing-skill/campaign-analytics`), build demand-gen / paid-media plans (`marketing-skill/marketing-demand-acquisition`), set positioning / GTM strategy (`marketing-skill/marketing-strategy-pmm`), or set pricing (`commercial/pricing-strategist`).

## Workflow

1. **Write the brief** — Fill `assets/market_research_brief_template.md` (objective, the decision this informs, sizing approach, sampling plan, assumptions register).
2. **Size the market** — Run `market_sizer.py --input market.json --method both --profile {b2b-saas|consumer|enterprise|marketplace|hardware|services}`. Reconcile the top-down/bottoms-up delta before quoting anything.
3. **Plan the survey** — Run `sample_size_planner.py --input survey.json`. Fund the per-segment floors, not just the overall n.
4. **Score the segments** — Run `segmentation_scorer.py --input segments.json --profile <same>`. Drop segments failing the substantiality/accessibility gate.
5. **Assemble the evidence pack** — Combine into a brief. Every number carries its method + assumptions + confidence.

## Scripts

| Script | Purpose | Profiles |
|---|---|---|
| `scripts/market_sizer.py` | TAM/SAM/SOM top-down AND bottoms-up + triangulation flag | b2b-saas, consumer, enterprise, marketplace, hardware, services |
| `scripts/sample_size_planner.py` | Survey n + FPC + per-segment minima | n/a (parameter-driven) |
| `scripts/segmentation_scorer.py` | Kotler 5-criteria scoring + gate | b2b-saas, consumer, enterprise, marketplace, hardware, services |

All three: stdlib-only, `--help`, `--sample`, `--output {human,json}`.

## Onboarding & customization

Run the onboarding questionnaire **once before you start** — it captures your defaults so every tool in this skill is pre-configured. Customization is the point: the answers actually change tool behavior.

```bash
python3 scripts/onboard.py            # interactive (also: --defaults, --set key=value, --reset)
python3 scripts/onboard.py --show     # see the questions + current effective config
```

Answers are saved to `~/.config/research-ops/market-research.json` (global) or `./.research-ops/market-research.json` (`--scope project`) and are read automatically by `config_loader.py`. They set the default market **profile**, the default survey **confidence** and **margin of error**, and the default **sizing method**. CLI flags always override saved config; `RESEARCH_OPS_NO_CONFIG=1` ignores it.

**The four questions:** market profile · survey confidence · margin of error · sizing method.

## Optimize with autoresearch (opt-in)

This skill ships an **isolated, opt-in** bridge to `engineering/autoresearch-agent`. Only when you ask to "optimize" / "reconcile the sizing" / "run a loop" does an autoresearch experiment iteratively reconcile your market model so top-down and bottoms-up triangulate. `scripts/ar_evaluator.py` is the ground-truth evaluator; it prints `tam_divergence: <fraction>` (**lower** is better).

```bash
/ar:setup --domain custom --name tam-triangulation \
  --target market.json \
  --eval "python3 ar_evaluator.py --target market.json" \
  --metric tam_divergence --direction lower
/ar:loop custom/tam-triangulation
```

Isolated: no hard dependency — autoresearch runs only on demand, and the loop edits `market.json`, never the evaluator.

## References

- `references/market_sizing_canon.md` — TAM/SAM/SOM frameworks (Bessemer, a16z); top-down vs bottoms-up; Fermi estimation; market-model conventions; common sizing fallacies.
- `references/survey_methodology.md` — Cochran *Sampling Techniques*; Dillman *Tailored Design Method*; Groves *Survey Methodology*; question-wording bias (Schuman & Presser); AAPOR standards.
- `references/segmentation_and_ci.md` — Kotler segmentation criteria; needs-based vs firmographic; Porter Five Forces; SCIP ethics; Christensen JTBD; conjoint/MaxDiff primer.

## Assumptions

- The sizer reports both methods but cannot validate your inputs — a top-down "1% of a $40B market" is only as good as the cited source and the serviceable fraction.
- Sample-size uses the conservative p=0.5 (maximum variance) unless you supply an expected proportion.
- Segment scores are inputs you provide; the tool enforces the gates and the weighting, it does not gather the underlying evidence.
- Competitive intelligence must follow the SCIP code of ethics — no misrepresentation, no protected information.

## Anti-patterns

- **A single TAM number with no method.** Always triangulate top-down against bottoms-up.
- **Spurious precision.** Size to the decision's tolerance; "$3.7142B" implies a confidence you do not have.
- **Powering only the total.** Each reported segment needs its own sample floor.
- **Leading or double-barreled survey questions.** Pre-test wording against the bias literature.
- **Calling a demographic slice a segment.** It must be substantial AND accessible.

## Distinct from

| Neighbor | Scope | Difference |
|---|---|---|
| `marketing-skill/campaign-analytics` | Attribution, ROAS, CPA, funnel of a live campaign | That **measures spend deployed**; this is **upstream methodology** |
| `marketing-skill/marketing-demand-acquisition` | Demand-gen, paid media, channel mix | That **runs acquisition**; this **builds the evidence** |
| `marketing-skill/marketing-strategy-pmm` | Positioning, GTM, category | That **sets strategy**; this **sizes and segments the market** |
| `commercial/pricing-strategist` | Pricing model + WTP + packaging | That **sets price**; this **sizes the market** |
| `product-research` (sibling) | User/product discovery methods | That studies **users**; this studies **the market** |

## Quick examples

```bash
python3 scripts/market_sizer.py --sample
python3 scripts/sample_size_planner.py --population 62000 --confidence 0.95 --moe 0.05
python3 scripts/segmentation_scorer.py --sample --output json
```

The sample market triangulates a ~$1.47B top-down SAM against the bottoms-up figure and flags the divergence; the segmentation sample drops the "solopreneurs who might want analytics" slice for failing the substantiality and accessibility gates.

## Forcing-question library (Matt Pocock grill discipline)

Walked one at a time by `/cs:grill-research-ops` or the orchestrator. Recommended answer + canon citation per question. Never bundled.

1. **"Is your TAM top-down or bottoms-up — and have you computed it both ways to triangulate?"**
   Recommended: both; reconcile the delta before quoting a number.
   Canon: Bessemer / a16z market-sizing; Fermi estimation.

2. **"What decision will this market size actually drive — and at what precision does it matter?"**
   Recommended: size to the decision's tolerance, not to a spurious-precision number.
   Canon: market-model conventions (Gartner/Forrester); decision-driven analysis.

3. **"What's your target margin of error and confidence — and does your sample clear it per segment, not just overall?"**
   Recommended: power each reported segment, not only the total.
   Canon: Cochran *Sampling Techniques*; AAPOR standards.

4. **"Are your survey questions free of leading and double-barreled wording?"**
   Recommended: pre-test the wording; cite the bias source.
   Canon: Schuman & Presser; Dillman *Tailored Design Method*.

5. **"Do your segments pass measurable / substantial / accessible / actionable — or are they just demographic slices?"**
   Recommended: drop segments that fail substantiality or accessibility.
   Canon: Kotler segmentation criteria.

Walk depth-first. Lock 1-2 before opening 3-5. After all are answered, invoke `market_sizer.py` → `sample_size_planner.py` → `segmentation_scorer.py`.

FILE:assets/market_research_brief_template.md
# Market Research Brief — Template

> Fill this before running the tools. Every number in the final brief must carry its method,
> assumptions, and confidence. Size to the decision's tolerance, not to false precision.

## 1. Objective
- Research question:
- **The decision this informs** (and who makes it):
- Precision required (order-of-magnitude / ±20% / ±5%):

## 2. Market sizing
- Approach: [top-down | bottoms-up | both — recommended both]
- Top-down inputs: total market value + source citation; serviceable fraction; reachable share.
- Bottoms-up inputs: total potential customers + source; annual price; serviceable fraction; realistic adoption.
- Triangulation result (from `market_sizer.py`) + divergence:

## 3. Survey plan (if primary data)
- Population (N) + sampling frame:
- Confidence level / overall margin of error / expected proportion:
- Segments to report + per-segment margin of error:
- Recommended n (overall + per-segment floors, from `sample_size_planner.py`):
- Mode (online panel / phone / mixed) + coverage risk:

## 4. Segmentation
- Candidate segments + scores across measurable / substantial / accessible / differentiable / actionable:
- Verdicts (from `segmentation_scorer.py`): TARGET / WATCH / DROP

## 5. Competitive intelligence
- Sources (public, ethically obtained — SCIP code):
- Five Forces summary:

## 6. Assumptions register
- (List every assumption behind the sizing, sampling, and segmentation. Each must trace to a source or be flagged as an unverified planning assumption.)

## 7. Confidence statement
- Overall confidence in the headline numbers (high / moderate / low) and why:

FILE:references/market_sizing_canon.md
# Market Sizing Canon

Reference for TAM/SAM/SOM. Pairs with `market_sizer.py`.

## The three numbers

- **TAM (Total Addressable Market)** — total revenue if you captured 100% of the market for your category.
- **SAM (Serviceable Addressable Market)** — the portion of TAM you can serve given your geography, segment focus, and product scope.
- **SOM (Serviceable Obtainable Market)** — the realistic, capacity-constrained share of SAM you can win in the planning window.

## Two methods — always do both

- **Top-down**: start from a published total market value (analyst report, government statistic) and apply serviceable and reachable fractions. Fast, but only as good as the source and inherits its biases. The classic failure is "1% of a huge number" — a TAM that sounds enormous and means nothing.
- **Bottoms-up**: start from the number of potential customers × the price they would pay, then apply serviceable and adoption fractions. Slower but grounded in units you can defend. The discipline is that bottoms-up forces you to name customer counts and price points.

When the two methods diverge by more than a tolerance, **triangulation has failed** — you do not yet have a defensible number. The tool flags this rather than averaging the two (averaging hides the disagreement).

## Fermi discipline

Good sizing is Fermi estimation: decompose the unknown into knowable factors, estimate each with a stated assumption, and carry the uncertainty through. A market size is a chain of assumptions; surfacing the chain is the deliverable, not the point estimate.

## Common fallacies

- **Double counting** — summing overlapping segments or counting the same revenue at multiple layers of the value chain.
- **Percent-of-a-big-number** — anchoring on "if we just get 1%" without a bottoms-up cross-check.
- **Confusing TAM growth with your growth** — a growing TAM does not entitle you to a fixed share.
- **Spurious precision** — quoting a TAM to four significant figures when the inputs are order-of-magnitude estimates.

## Sources

1. Bessemer Venture Partners, *State of the Cloud* and market-sizing memos (TAM/SAM/SOM discipline).
2. Andreessen Horowitz (a16z), *The truth about market sizing* and bottoms-up TAM essays.
3. Gartner / Forrester / IDC market-model methodology notes (forecast construction conventions).
4. Weinstein, L., & Adam, J., *Guesstimation* (Princeton, 2008) — Fermi estimation.
5. Blank, S., *The Four Steps to the Epiphany* — market-type and sizing in customer development.
6. Damodaran, A., *Narrative and Numbers* (Columbia, 2017) — disciplining market-size narratives with numbers.

FILE:references/segmentation_and_ci.md
# Segmentation and Competitive Intelligence

Reference for segmentation scoring and competitive-intelligence synthesis. Pairs with `segmentation_scorer.py`.

## What makes a segment useful (Kotler)

A market segment is only useful if it meets five criteria. The scorer weights and gates them:

1. **Measurable** — you can size and identify it.
2. **Substantial** — it is large and profitable enough to be worth serving. (Gate: a tiny slice is not a market.)
3. **Accessible** — you can reach it through channels you can afford. (Gate: an unreachable segment is academic.)
4. **Differentiable** — it responds differently to your offer than other segments do; otherwise it is not a distinct segment.
5. **Actionable** — you can design and execute a program for it.

Substantiality and accessibility are **gates** because they are the two that most often fail silently: teams fall in love with a precisely-described segment that is too small or has no viable channel.

## Bases of segmentation

- **Firmographic** (B2B): industry, size, geography — easy to measure, weak at predicting behavior.
- **Demographic** (B2C): age, income, role — same trade-off.
- **Needs-based / behavioral**: grouping by the job customers are trying to get done. Stronger predictor of response, harder to measure. Christensen's **Jobs-to-be-Done** reframes segmentation around the progress a customer is trying to make, not who they are.

The strongest segmentations pair a needs-based core with a firmographic/demographic proxy you can actually target.

## Competitive intelligence

CI synthesis is structured, ethical analysis of the competitive landscape:

- **Porter's Five Forces** frames structural attractiveness (rivalry, new entrants, substitutes, supplier power, buyer power).
- **SCIP (Strategic and Competitive Intelligence Professionals)** publishes a code of ethics: no misrepresentation of identity, no acquisition of protected/confidential information, full compliance with law. CI is built from public and ethically-obtained sources.

## Advanced preference measurement

When you need to quantify trade-offs, **conjoint analysis** and **MaxDiff** (best-worst scaling) estimate the relative importance of attributes and the willingness to trade one for another — far more reliable than directly asking "how important is X?"

## Sources

1. Kotler, P., & Keller, K., *Marketing Management*, 15th ed. — segmentation criteria.
2. Christensen, Hall, Dillon & Duncan, *Competing Against Luck* (2016) — Jobs-to-be-Done.
3. Porter, M., *Competitive Strategy* (1980) — Five Forces.
4. SCIP, *Code of Ethics for CI Professionals*.
5. Orme, B., *Getting Started with Conjoint Analysis*, 4th ed. (Sawtooth, Research Publishers).
6. Smith, W., *Product Differentiation and Market Segmentation as Alternative Marketing Strategies* — J Marketing 1956 (the founding segmentation paper).

FILE:references/survey_methodology.md
# Survey Methodology

Reference for survey design and sampling. Pairs with `sample_size_planner.py`.

## Sample size from first principles

For estimating a proportion, the required sample is n₀ = z²·p·(1−p)/e², where z is the critical value for the confidence level, p the expected proportion, and e the margin of error. The maximum-variance choice p = 0.5 is the conservative default. When the sample is a meaningful fraction of a finite population N, apply the **finite-population correction**: n = n₀ / (1 + (n₀−1)/N). The planner does both.

The most common analyst error: powering the **overall** sample but then reporting **per-segment** results that the sample cannot support. If you will report three segments at ±8%, each segment needs ~150 respondents — so the survey must be sized to the segment floors, not the aggregate. The planner computes per-segment minimums explicitly.

## The total survey error framework

Sample size only addresses **sampling error**. Groves' total-survey-error framework names the others, often larger:

- **Coverage error** — the sampling frame omits part of the population (e.g., an email panel misses non-users).
- **Non-response error** — those who respond differ systematically from those who don't.
- **Measurement error** — the instrument itself biases answers (question wording, order, scale).

A tight margin of error on a biased frame is precision without accuracy.

## Question design

- **Avoid leading questions** that imply a preferred answer.
- **Avoid double-barreled questions** that ask two things at once ("Is the product fast and reliable?").
- **Watch scale and order effects** — response options and question sequence shift answers.
- **Pre-test** every instrument with a small cognitive-interview pass before fielding.

## Standards

AAPOR (American Association for Public Opinion Research) publishes disclosure standards and the standard definitions for response-rate calculation. Reputable market research follows them so results are comparable and auditable.

## Sources

1. Cochran, W.G., *Sampling Techniques*, 3rd ed. (Wiley, 1977).
2. Dillman, Smyth & Christian, *Internet, Phone, Mail, and Mixed-Mode Surveys: The Tailored Design Method*, 4th ed. (2014).
3. Groves et al., *Survey Methodology*, 2nd ed. (Wiley, 2009) — total survey error.
4. Schuman, H., & Presser, S., *Questions and Answers in Attitude Surveys* (1981) — wording/order effects.
5. AAPOR, *Standard Definitions: Final Dispositions of Case Codes and Outcome Rates for Surveys*.
6. Tourangeau, Rips & Rasinski, *The Psychology of Survey Response* (Cambridge, 2000).

FILE:scripts/ar_evaluator.py
#!/usr/bin/env python3
"""ar_evaluator.py - Autoresearch evaluator for the market-research skill (OPT-IN).

Stdlib-only. The ISOLATED bridge to engineering/autoresearch-agent. It does NOT call
autoresearch; it is the ground-truth evaluator an autoresearch loop runs after editing
the target market model. It reads a market-model JSON, runs market_sizer in "both" mode,
and prints ONE metric line:

    tam_divergence: <fraction>   (LOWER is better — top-down and bottoms-up should agree)

Optimize a market model so the two sizing methods triangulate (reconcile assumptions),
while the agent edits the target. The user opts in explicitly:
    /ar:setup --domain custom --name tam-triangulation \\
      --target market.json --eval "python3 ar_evaluator.py --target market.json" \\
      --metric tam_divergence --direction lower

Direct use:
    python3 ar_evaluator.py --sample
    python3 ar_evaluator.py --target market.json --profile enterprise
"""

from __future__ import annotations

import argparse
import json
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import config_loader as cfg  # noqa: E402
import market_sizer as ms  # noqa: E402

METRIC = "tam_divergence"


def main(argv: list[str] | None = None) -> int:
    c = cfg.load_config()
    p = argparse.ArgumentParser(description="Autoresearch evaluator: TAM triangulation divergence.")
    p.add_argument("--target", help="path to market-model JSON (or env AR_TARGET)")
    p.add_argument("--profile", default=None, help="overrides onboarding default_profile")
    p.add_argument("--sample", action="store_true")
    args = p.parse_args(argv)

    profile = args.profile or c.get("default_profile", "b2b-saas")
    if args.sample:
        data = ms.SAMPLE
    else:
        target = args.target or os.environ.get("AR_TARGET")
        if not target:
            print("error: provide --target <market.json> or set AR_TARGET", file=sys.stderr)
            return 2
        try:
            with open(target) as f:
                data = json.load(f)
        except (OSError, json.JSONDecodeError) as e:
            print(f"{METRIC}: N/A")
            print(f"error: {e}", file=sys.stderr)
            return 1

    try:
        result = ms.size_market(data, "both", profile)
    except ValueError as e:
        print(f"{METRIC}: N/A")
        print(f"error: {e}", file=sys.stderr)
        return 1

    div = result.get("tam_divergence")
    if div is None:
        print(f"{METRIC}: N/A")
        print("error: need both top_down and bottoms_up blocks to triangulate", file=sys.stderr)
        return 1
    print(f"{METRIC}: {div}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/config_loader.py
#!/usr/bin/env python3
"""config_loader.py - Customization loader for the market-research skill.

Stdlib-only. Importable from the skill's other scripts. Precedence (highest wins):
  1. Project config:  <cwd>/.research-ops/market-research.json
  2. Global config:   ~/.config/research-ops/market-research.json
  3. Built-in DEFAULTS

Onboarding answers (written by onboard.py) live in these files; every tool in this
skill reads them so the user's customization applies automatically.
Set RESEARCH_OPS_NO_CONFIG=1 to ignore saved config.
"""

from __future__ import annotations

import argparse
import json
import os
import sys
from pathlib import Path
from typing import Any

SKILL = "market-research"

GLOBAL_CONFIG_DIR = Path.home() / ".config" / "research-ops"
GLOBAL_CONFIG_PATH = GLOBAL_CONFIG_DIR / f"{SKILL}.json"
PROJECT_CONFIG_DIRNAME = ".research-ops"

DEFAULTS: dict[str, Any] = {
    "version": 1,
    "skill": SKILL,
    "default_profile": "b2b-saas",
    "default_confidence": 0.95,
    "default_moe": 0.05,
    "sizing_method": "both",
    "setup_completed_at": None,
}


def project_config_path(cwd: Path | None = None) -> Path:
    cwd = cwd or Path.cwd()
    return cwd / PROJECT_CONFIG_DIRNAME / f"{SKILL}.json"


def _read_json(path: Path) -> dict[str, Any] | None:
    try:
        with path.open(encoding="utf-8") as f:
            data = json.load(f)
        return data if isinstance(data, dict) else None
    except (FileNotFoundError, json.JSONDecodeError, OSError):
        return None


def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
    out = dict(base)
    for k, v in override.items():
        if isinstance(v, dict) and isinstance(out.get(k), dict):
            out[k] = _deep_merge(out[k], v)
        else:
            out[k] = v
    return out


def load_config(cwd: Path | None = None) -> dict[str, Any]:
    config = dict(DEFAULTS)
    if os.environ.get("RESEARCH_OPS_NO_CONFIG") == "1":
        return config
    global_cfg = _read_json(GLOBAL_CONFIG_PATH)
    if global_cfg:
        config = _deep_merge(config, global_cfg)
    project_cfg = _read_json(project_config_path(cwd))
    if project_cfg:
        config = _deep_merge(config, project_cfg)
    return config


def setup_completed() -> bool:
    cfg = _read_json(GLOBAL_CONFIG_PATH) or _read_json(project_config_path())
    return bool(cfg and cfg.get("setup_completed_at"))


def write_config(config: dict[str, Any], scope: str = "global", cwd: Path | None = None) -> Path:
    path = project_config_path(cwd) if scope == "project" else GLOBAL_CONFIG_PATH
    path.parent.mkdir(parents=True, exist_ok=True)
    with path.open("w", encoding="utf-8") as f:
        json.dump(config, f, indent=2, sort_keys=True)
    return path


def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(description=f"Inspect {SKILL} customization config.")
    p.add_argument("--show", action="store_true", help="Print the effective config")
    p.add_argument("--status", action="store_true", help="Print setup status + paths")
    p.add_argument("--sample", action="store_true", help="Print the built-in defaults")
    args = p.parse_args(argv)

    if args.sample:
        print(json.dumps(DEFAULTS, indent=2, sort_keys=True))
    elif args.status:
        print(json.dumps({
            "skill": SKILL,
            "global_config_path": str(GLOBAL_CONFIG_PATH),
            "global_config_exists": GLOBAL_CONFIG_PATH.exists(),
            "project_config_path": str(project_config_path()),
            "project_config_exists": project_config_path().exists(),
            "setup_completed": setup_completed(),
        }, indent=2))
    else:
        print(json.dumps(load_config(), indent=2, sort_keys=True))
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/market_sizer.py
#!/usr/bin/env python3
"""market_sizer.py - Compute TAM / SAM / SOM by BOTH top-down and bottoms-up methods.

Stdlib-only. Deterministic. NO LLM calls. NEVER returns a single number: it computes both
methods side-by-side, reports the delta, and prints a mandatory method + assumptions block.

Top-down:   TAM = total_market_value ; SAM = TAM * serviceable_fraction ; SOM = SAM * reachable_share
Bottoms-up: TAM = total_potential_customers * annual_price
            SAM = TAM * serviceable_fraction
            SOM = SAM * realistic_adoption (capacity-constrained)

If the two TAMs diverge by more than the tolerance, the tool flags it: triangulation failed.

Usage:
    python3 market_sizer.py --sample
    python3 market_sizer.py --input market.json --method both
    python3 market_sizer.py --input market.json --profile b2b-saas --output json
"""

from __future__ import annotations

import argparse
import json
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
try:
    import config_loader as _cfg
except ImportError:  # pragma: no cover
    _cfg = None

# Profiles tune the divergence tolerance and a sanity note.
PROFILES = {
    "b2b-saas": {"tolerance": 0.30},
    "consumer": {"tolerance": 0.40},
    "enterprise": {"tolerance": 0.25},
    "marketplace": {"tolerance": 0.40},
    "hardware": {"tolerance": 0.30},
    "services": {"tolerance": 0.35},
}

SAMPLE = {
    "market_name": "Mid-market HR analytics SaaS (US)",
    "top_down": {
        "total_market_value": 4200000000,
        "serviceable_fraction": 0.35,
        "reachable_share": 0.04,
    },
    "bottoms_up": {
        "total_potential_customers": 62000,
        "annual_price": 18000,
        "serviceable_fraction": 0.35,
        "realistic_adoption": 0.03,
    },
}


def top_down(td: dict) -> dict:
    tam = float(td.get("total_market_value", 0.0))
    sam = tam * float(td.get("serviceable_fraction", 0.0))
    som = sam * float(td.get("reachable_share", 0.0))
    return {"method": "top-down", "TAM": round(tam, 0), "SAM": round(sam, 0), "SOM": round(som, 0)}


def bottoms_up(bu: dict) -> dict:
    customers = float(bu.get("total_potential_customers", 0.0))
    price = float(bu.get("annual_price", 0.0))
    tam = customers * price
    sam = tam * float(bu.get("serviceable_fraction", 0.0))
    som = sam * float(bu.get("realistic_adoption", 0.0))
    return {"method": "bottoms-up", "TAM": round(tam, 0), "SAM": round(sam, 0),
            "SOM": round(som, 0), "implied_customers_at_SOM": round((sam / price) * float(bu.get("realistic_adoption", 0.0))) if price else None}


def size_market(data: dict, method: str, profile: str) -> dict:
    if profile not in PROFILES:
        raise ValueError(f"Unknown profile '{profile}'. Choose from {list(PROFILES)}.")
    tol = PROFILES[profile]["tolerance"]
    out = {"market_name": data.get("market_name", "UNSPECIFIED"), "profile": profile}

    td = top_down(data.get("top_down", {})) if method in ("top-down", "both") else None
    bu = bottoms_up(data.get("bottoms_up", {})) if method in ("bottoms-up", "both") else None
    if td:
        out["top_down"] = td
    if bu:
        out["bottoms_up"] = bu

    flags = []
    if td and bu and td["TAM"] > 0:
        delta = abs(td["TAM"] - bu["TAM"]) / td["TAM"]
        out["tam_divergence"] = round(delta, 3)
        if delta > tol:
            flags.append(f"TRIANGULATION FAILED: top-down and bottoms-up TAM differ by {delta:.0%} "
                         f"(> {tol:.0%} tolerance). Reconcile before quoting a number.")
        else:
            flags.append(f"Triangulation OK: TAMs within {delta:.0%} (tolerance {tol:.0%}).")
    out["flags"] = flags
    out["method_and_assumptions"] = [
        "NEVER quote a single TAM number without stating the method and the assumptions below.",
        "Top-down TAM = total market value (cite the source: analyst report, gov stat).",
        "Bottoms-up TAM = total potential customers x annual price (cite both counts).",
        "SAM = TAM x serviceable fraction (geography/segment you can actually serve).",
        "SOM = SAM x realistic, capacity-constrained share you can win in the planning window.",
    ]
    return out


def _fmt(n):
    return f",.0f" if isinstance(n, (int, float)) else str(n)


def _render_human(r: dict) -> str:
    lines = [f"Market Sizing: {r['market_name']}  (profile: {r['profile']})", ""]
    for key in ("top_down", "bottoms_up"):
        if key in r:
            m = r[key]
            lines.append(f"  [{m['method']}]  TAM {_fmt(m['TAM'])} | SAM {_fmt(m['SAM'])} | SOM {_fmt(m['SOM'])}")
            if m.get("implied_customers_at_SOM") is not None:
                lines.append(f"      implied customers at SOM: {m['implied_customers_at_SOM']:,}")
    if "tam_divergence" in r:
        lines.append(f"  TAM divergence (top-down vs bottoms-up): {r['tam_divergence']:.1%}")
    lines.append("")
    for f in r["flags"]:
        lines.append(f"  ! {f}")
    lines.append("")
    lines.append("Method & assumptions (must travel with the number):")
    for a in r["method_and_assumptions"]:
        lines.append(f"  - {a}")
    return "\n".join(lines)


def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(description="Compute TAM/SAM/SOM by top-down AND bottoms-up (never a single number).")
    p.add_argument("--input", help="Path to JSON with top_down{} and bottoms_up{}")
    p.add_argument("--method", choices=["top-down", "bottoms-up", "both"], default=None,
                   help="overrides onboarding sizing_method")
    p.add_argument("--profile", default=None, choices=list(PROFILES),
                   help="overrides onboarding default_profile")
    p.add_argument("--output", choices=["human", "json"], default="human")
    p.add_argument("--sample", action="store_true", help="use the embedded sample")
    args = p.parse_args(argv)

    conf = _cfg.load_config() if _cfg else {}
    method = args.method or conf.get("sizing_method", "both")
    profile = args.profile or conf.get("default_profile", "b2b-saas")
    data = SAMPLE if (args.sample or not args.input) else json.load(open(args.input))
    try:
        result = size_market(data, method, profile)
    except ValueError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(_render_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/onboard.py
#!/usr/bin/env python3
"""onboard.py - Onboarding questionnaire for the market-research skill.

Stdlib-only. Asks the user a short set of questions BEFORE they size a market or field
a survey, then writes the answers to a customization config read by every tool in this
skill via config_loader.py. The answers become defaults for profile, survey confidence,
margin of error, and sizing method.

Modes: --show | --defaults | --set key=value (repeatable) | --reset | --scope {global,project}
"""

from __future__ import annotations

import argparse
import datetime as _dt
import json
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import config_loader as cfg  # noqa: E402

NUMERIC_KEYS = {"default_confidence", "default_moe"}

QUESTIONS = [
    ("default_profile",
     "1. What market are you researching?",
     ["b2b-saas", "consumer", "enterprise", "marketplace", "hardware", "services"], str),
    ("default_confidence",
     "2. Default survey confidence level?",
     ["0.80", "0.85", "0.90", "0.95", "0.99"], float),
    ("default_moe",
     "3. Default survey margin of error (fraction, e.g. 0.05)?",
     None, float),
    ("sizing_method",
     "4. Default market-sizing method?",
     ["top-down", "bottoms-up", "both"], str),
]


def _print_questions() -> None:
    print(f"Onboarding questions — {cfg.SKILL}:\n")
    for _k, prompt, choices, _c in QUESTIONS:
        line = f"  {prompt}"
        if choices:
            line += f"   [{' / '.join(choices)}]"
        print(line)


def run_interactive(config: dict) -> dict:
    print(f"Onboarding — {cfg.SKILL}. Press Enter to keep the current/default value.\n")
    for key, prompt, choices, caster in QUESTIONS:
        suffix = f" [{'/'.join(choices)}]" if choices else ""
        cur = f" (current: {config.get(key)})" if config.get(key) is not None else ""
        raw = input(f"{prompt}{suffix}{cur}: ").strip()
        if not raw:
            continue
        try:
            config[key] = caster(raw)
        except ValueError:
            print(f"   ! invalid value for {key}, keeping current")
    return config


def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(description=f"Onboarding for the {cfg.SKILL} skill.")
    p.add_argument("--show", action="store_true")
    p.add_argument("--defaults", action="store_true", help="write built-in defaults, no prompt")
    p.add_argument("--set", action="append", default=[], metavar="key=value")
    p.add_argument("--reset", action="store_true")
    p.add_argument("--scope", choices=["global", "project"], default="global")
    args = p.parse_args(argv)

    if args.show:
        _print_questions()
        print("\nCurrent effective config:")
        print(json.dumps(cfg.load_config(), indent=2, sort_keys=True))
        return 0

    if args.reset:
        path = cfg.project_config_path() if args.scope == "project" else cfg.GLOBAL_CONFIG_PATH
        if path.exists():
            path.unlink(); print(f"removed {path}")
        else:
            print(f"no config at {path}")
        return 0

    config = cfg.load_config()

    if args.set:
        for item in args.set:
            if "=" not in item:
                print(f"error: --set expects key=value, got '{item}'", file=sys.stderr)
                return 2
            k, v = item.split("=", 1)
            if k in NUMERIC_KEYS:
                try:
                    v = float(v)
                except ValueError:
                    pass
            config[k] = v
    elif not args.defaults:
        if sys.stdin.isatty():
            config = run_interactive(config)
        else:
            print("non-interactive shell: use --defaults or --set key=value. Showing questions:\n")
            _print_questions()
            return 0

    config["setup_completed_at"] = _dt.datetime.now(_dt.timezone.utc).isoformat()
    path = cfg.write_config(config, scope=args.scope)
    print(f"saved {cfg.SKILL} customization -> {path}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/sample_size_planner.py
#!/usr/bin/env python3
"""sample_size_planner.py - Survey sample-size with finite-population correction + per-segment minima.

Stdlib-only. Deterministic. NO LLM calls.

Computes the classic proportion-estimate sample size:
    n0 = z^2 * p * (1-p) / e^2
then applies the finite-population correction (FPC) when a population N is given:
    n  = n0 / (1 + (n0 - 1)/N)
Also computes per-segment minimums and a proportional quota allocation, because a survey
powered overall is NOT powered per reported segment.

Usage:
    python3 sample_size_planner.py --sample
    python3 sample_size_planner.py --population 62000 --confidence 0.95 --moe 0.05 --proportion 0.5
    python3 sample_size_planner.py --input survey.json --output json
"""

from __future__ import annotations

import argparse
import json
import math
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
try:
    import config_loader as _cfg
except ImportError:  # pragma: no cover
    _cfg = None

Z = {0.80: 1.2816, 0.85: 1.4395, 0.90: 1.6449, 0.95: 1.9600, 0.99: 2.5758}

SAMPLE = {
    "population": 62000,
    "confidence": 0.95,
    "margin_of_error": 0.05,
    "expected_proportion": 0.5,
    "segments": [
        {"name": "1-50 employees", "population_share": 0.55},
        {"name": "51-250 employees", "population_share": 0.30},
        {"name": "251-1000 employees", "population_share": 0.15},
    ],
    "segment_moe": 0.08,
}


def _z(conf: float) -> float:
    if conf not in Z:
        raise ValueError(f"confidence must be one of {sorted(Z)}.")
    return Z[conf]


def base_n(conf: float, moe: float, p: float, population: float | None) -> dict:
    if not 0.0 < p < 1.0:
        raise ValueError("expected_proportion must be in (0,1).")
    if not 0.0 < moe < 1.0:
        raise ValueError("margin_of_error must be in (0,1).")
    z = _z(conf)
    n0 = (z ** 2) * p * (1 - p) / (moe ** 2)
    if population and population > 0:
        n = n0 / (1 + (n0 - 1) / population)
        fpc_applied = True
    else:
        n = n0
        fpc_applied = False
    return {
        "confidence": conf,
        "margin_of_error": moe,
        "expected_proportion": p,
        "population": population,
        "n_unadjusted": math.ceil(n0),
        "n_with_fpc": math.ceil(n),
        "fpc_applied": fpc_applied,
        "z": z,
    }


def segment_plan(data: dict, overall: dict) -> dict:
    seg_moe = float(data.get("segment_moe", data.get("margin_of_error", 0.05)))
    conf = float(data.get("confidence", 0.95))
    p = float(data.get("expected_proportion", 0.5))
    z = _z(conf)
    per_seg_min = math.ceil((z ** 2) * p * (1 - p) / (seg_moe ** 2))

    segs = data.get("segments", [])
    total_quota = max(overall["n_with_fpc"], per_seg_min * len(segs)) if segs else overall["n_with_fpc"]
    out_segs = []
    for s in segs:
        share = float(s.get("population_share", 0.0))
        proportional = math.ceil(total_quota * share)
        quota = max(proportional, per_seg_min)
        out_segs.append({
            "name": s.get("name", "UNNAMED"),
            "population_share": share,
            "proportional_quota": proportional,
            "minimum_for_segment_moe": per_seg_min,
            "recommended_quota": quota,
        })
    return {
        "segment_margin_of_error": seg_moe,
        "minimum_per_segment": per_seg_min,
        "recommended_total_with_segment_floors": sum(s["recommended_quota"] for s in out_segs) if out_segs else total_quota,
        "segments": out_segs,
    }


def plan(data: dict) -> dict:
    overall = base_n(
        float(data.get("confidence", 0.95)),
        float(data.get("margin_of_error", 0.05)),
        float(data.get("expected_proportion", 0.5)),
        data.get("population"),
    )
    result = {"overall": overall}
    if data.get("segments"):
        result["segmentation"] = segment_plan(data, overall)
    result["notes"] = [
        "A survey powered overall is NOT powered per reported segment — fund the segment floors.",
        "expected_proportion=0.5 is the conservative (maximum-variance) default.",
        "FPC matters when the sample is a large fraction of the population (small N).",
    ]
    return result


def _render_human(r: dict) -> str:
    o = r["overall"]
    lines = ["Survey Sample-Size Plan", "",
             f"  Confidence: {o['confidence']:.0%}   MoE: {o['margin_of_error']:.0%}   p: {o['expected_proportion']}",
             f"  n (unadjusted):      {o['n_unadjusted']}",
             f"  n (with FPC):        {o['n_with_fpc']}  (population {o['population']}, fpc_applied={o['fpc_applied']})"]
    if "segmentation" in r:
        s = r["segmentation"]
        lines += ["", f"  Per-segment MoE: {s['segment_margin_of_error']:.0%}  => minimum {s['minimum_per_segment']} per segment",
                  f"  Recommended total with segment floors: {s['recommended_total_with_segment_floors']}", ""]
        for seg in s["segments"]:
            lines.append(f"    {seg['name']:24s} share {seg['population_share']:.0%}  "
                         f"proportional {seg['proportional_quota']}  recommended {seg['recommended_quota']}")
    lines += ["", "Notes:"]
    for n in r["notes"]:
        lines.append(f"  - {n}")
    return "\n".join(lines)


def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(description="Survey sample size with FPC + per-segment minima.")
    p.add_argument("--input", help="Path to JSON survey spec")
    p.add_argument("--population", type=float, default=None)
    p.add_argument("--confidence", type=float, default=None, help="overrides onboarding default_confidence")
    p.add_argument("--moe", type=float, default=None, help="margin of error (overrides onboarding default_moe)")
    p.add_argument("--proportion", type=float, default=0.5, help="expected proportion")
    p.add_argument("--output", choices=["human", "json"], default="human")
    p.add_argument("--sample", action="store_true", help="use the embedded sample")
    args = p.parse_args(argv)

    conf = _cfg.load_config() if _cfg else {}
    confidence = args.confidence if args.confidence is not None else conf.get("default_confidence", 0.95)
    moe = args.moe if args.moe is not None else conf.get("default_moe", 0.05)

    if args.sample:
        data = SAMPLE
    elif args.input:
        data = json.load(open(args.input))
    else:
        data = {"population": args.population, "confidence": confidence,
                "margin_of_error": moe, "expected_proportion": args.proportion}

    try:
        result = plan(data)
    except ValueError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(_render_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/segmentation_scorer.py
#!/usr/bin/env python3
"""segmentation_scorer.py - Score candidate market segments against Kotler's actionability criteria.

Stdlib-only. Deterministic. NO LLM calls.

Each candidate segment is scored 0-100 across the five Kotler criteria for a useful segment:
  1. measurable      can you size and identify it?
  2. substantial     is it large/profitable enough to serve?
  3. accessible      can you reach it through channels?
  4. differentiable   does it respond differently from other segments?
  5. actionable      can you design and execute a program for it?

Segments failing the substantiality or accessibility gates are flagged: a demographic slice
that is unreachable or too small is not a market segment.

Usage:
    python3 segmentation_scorer.py --sample
    python3 segmentation_scorer.py --input segments.json --profile enterprise
    python3 segmentation_scorer.py --input segments.json --output json
"""

from __future__ import annotations

import argparse
import json
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
try:
    import config_loader as _cfg
except ImportError:  # pragma: no cover
    _cfg = None

CRITERIA = ["measurable", "substantial", "accessible", "differentiable", "actionable"]
WEIGHTS = {"measurable": 0.15, "substantial": 0.25, "accessible": 0.25,
           "differentiable": 0.20, "actionable": 0.15}
GATE_FLOOR = 40.0  # substantiality + accessibility gate

# Profiles nudge the substantiality expectation (enterprise tolerates smaller, higher-value segments).
PROFILES = {
    "b2b-saas": 1.0,
    "consumer": 1.0,
    "enterprise": 0.85,
    "marketplace": 1.0,
    "hardware": 1.0,
    "services": 0.9,
}

SAMPLE = {
    "segments": [
        {"name": "Mid-market HR teams (51-250 emp)",
         "scores": {"measurable": 85, "substantial": 80, "accessible": 75, "differentiable": 70, "actionable": 80}},
        {"name": "Solopreneurs who 'might' want analytics",
         "scores": {"measurable": 40, "substantial": 30, "accessible": 35, "differentiable": 30, "actionable": 40}},
        {"name": "Enterprise CHROs (1000+ emp)",
         "scores": {"measurable": 90, "substantial": 95, "accessible": 50, "differentiable": 85, "actionable": 70}},
    ],
}


def score_segment(seg: dict, sub_mult: float) -> dict:
    raw = seg.get("scores", {})
    breakdown = {}
    composite = 0.0
    for c in CRITERIA:
        s = float(raw.get(c, 0.0))
        if c == "substantial":
            s = min(100.0, s / sub_mult)  # enterprise: smaller segments still count (divide by <1 raises)
        breakdown[c] = round(s, 1)
        composite += s * WEIGHTS[c]
    flags = []
    if breakdown["substantial"] < GATE_FLOOR:
        flags.append("FAILS SUBSTANTIALITY GATE: too small/unprofitable to be a target segment.")
    if breakdown["accessible"] < GATE_FLOOR:
        flags.append("FAILS ACCESSIBILITY GATE: no viable channel to reach it.")
    verdict = "DROP" if flags else ("TARGET" if composite >= 65 else "WATCH")
    return {
        "name": seg.get("name", "UNNAMED"),
        "composite": round(composite, 1),
        "breakdown": breakdown,
        "flags": flags,
        "verdict": verdict,
    }


def evaluate(data: dict, profile: str) -> dict:
    if profile not in PROFILES:
        raise ValueError(f"Unknown profile '{profile}'. Choose from {list(PROFILES)}.")
    mult = PROFILES[profile]
    scored = sorted((score_segment(s, mult) for s in data.get("segments", [])),
                    key=lambda x: x["composite"], reverse=True)
    return {
        "profile": profile,
        "segments": scored,
        "note": "A demographic or firmographic slice is not a segment unless it is substantial AND accessible.",
    }


def _render_human(r: dict) -> str:
    lines = [f"Segmentation Scoring (profile: {r['profile']})", ""]
    for s in r["segments"]:
        lines.append(f"[{s['verdict']}] {s['name']}  — composite {s['composite']}/100")
        for c, v in s["breakdown"].items():
            lines.append(f"      {c:16s} {v}")
        for f in s["flags"]:
            lines.append(f"      ! {f}")
        lines.append("")
    lines.append(f"note: {r['note']}")
    return "\n".join(lines)


def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(description="Score market segments against Kotler's 5 criteria.")
    p.add_argument("--input", help="Path to JSON with segments[]")
    p.add_argument("--profile", default=None, choices=list(PROFILES),
                   help="overrides onboarding default_profile")
    p.add_argument("--output", choices=["human", "json"], default="human")
    p.add_argument("--sample", action="store_true", help="use the embedded sample")
    args = p.parse_args(argv)

    conf = _cfg.load_config() if _cfg else {}
    profile = args.profile or conf.get("default_profile", "b2b-saas")
    data = SAMPLE if (args.sample or not args.input) else json.load(open(args.input))
    try:
        result = evaluate(data, profile)
    except ValueError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(_render_human(result))
    return 0


if __name__ == "__main__":
    sys.exit(main())

---
name: "paid-ads"
description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ad copy,' 'ad creative,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' or 'audience targeting.' This skill covers campaign strategy, ad creation, audience targeting, and optimization."
license: MIT
metadata:
  version: 1.0.0
  author: Alireza Rezvani
  category: marketing
  updated: 2026-03-06
---

# Paid Ads

You are an expert performance marketer with direct access to ad platform accounts. Your goal is to help create, optimize, and scale paid advertising campaigns that drive efficient customer acquisition.

## Before Starting

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

### 1. Campaign Goals
- What's the primary objective? (Awareness, traffic, leads, sales, app installs)
- What's the target CPA or ROAS?
- What's the monthly/weekly budget?
- Any constraints? (Brand guidelines, compliance, geographic)

### 2. Product & Offer
- What are you promoting? (Product, free trial, lead magnet, demo)
- What's the landing page URL?
- What makes this offer compelling?

### 3. Audience
- Who is the ideal customer?
- What problem does your product solve for them?
- What are they searching for or interested in?
- Do you have existing customer data for lookalikes?

### 4. Current State
- Have you run ads before? What worked/didn't?
- Do you have existing pixel/conversion data?
- What's your current funnel conversion rate?

---

## Platform Selection Guide

| Platform | Best For | Use When |
|----------|----------|----------|
| **Google Ads** | High-intent search traffic | People actively search for your solution |
| **Meta** | Demand generation, visual products | Creating demand, strong creative assets |
| **LinkedIn** | B2B, decision-makers | Job title/company targeting matters, higher price points |
| **Twitter/X** | Tech audiences, thought leadership | Audience is active on X, timely content |
| **TikTok** | Younger demographics, viral creative | Audience skews 18-34, video capacity |

---

## Campaign Structure Best Practices

### Account Organization

```
Account
├── Campaign 1: [Objective] - [Audience/Product]
│   ├── Ad Set 1: [Targeting variation]
│   │   ├── Ad 1: [Creative variation A]
│   │   ├── Ad 2: [Creative variation B]
│   │   └── Ad 3: [Creative variation C]
│   └── Ad Set 2: [Targeting variation]
└── Campaign 2...
```

### Naming Conventions

```
[Platform]_[Objective]_[Audience]_[Offer]_[Date]

Examples:
META_Conv_Lookalike-Customers_FreeTrial_2024Q1
GOOG_Search_Brand_Demo_Ongoing
LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
```

### Budget Allocation

**Testing phase (first 2-4 weeks):**
- 70% to proven/safe campaigns
- 30% to testing new audiences/creative

**Scaling phase:**
- Consolidate budget into winning combinations
- Increase budgets 20-30% at a time
- Wait 3-5 days between increases for algorithm learning

---

## Ad Copy Frameworks

### Key Formulas

**Problem-Agitate-Solve (PAS):**
> [Problem] → [Agitate the pain] → [Introduce solution] → [CTA]

**Before-After-Bridge (BAB):**
> [Current painful state] → [Desired future state] → [Your product as bridge]

**Social Proof Lead:**
> [Impressive stat or testimonial] → [What you do] → [CTA]

**For detailed templates and headline formulas**: See [references/ad-copy-templates.md](references/ad-copy-templates.md)

---

## Audience Targeting Overview

### Platform Strengths

| Platform | Key Targeting | Best Signals |
|----------|---------------|--------------|
| Google | Keywords, search intent | What they're searching |
| Meta | Interests, behaviors, lookalikes | Engagement patterns |
| LinkedIn | Job titles, companies, industries | Professional identity |

### Key Concepts

- **Lookalikes**: Base on best customers (by LTV), not all customers
- **Retargeting**: Segment by funnel stage (visitors vs. cart abandoners)
- **Exclusions**: Always exclude existing customers and recent converters

**For detailed targeting strategies by platform**: See [references/audience-targeting.md](references/audience-targeting.md)

---

## Creative Best Practices

### Image Ads
- Clear product screenshots showing UI
- Before/after comparisons
- Stats and numbers as focal point
- Human faces (real, not stock)
- Bold, readable text overlay (keep under 20%)

### Video Ads Structure (15-30 sec)
1. Hook (0-3 sec): Pattern interrupt, question, or bold statement
2. Problem (3-8 sec): Relatable pain point
3. Solution (8-20 sec): Show product/benefit
4. CTA (20-30 sec): Clear next step

**Production tips:**
- Captions always (85% watch without sound)
- Vertical for Stories/Reels, square for feed
- Native feel outperforms polished
- First 3 seconds determine if they watch

### Creative Testing Hierarchy
1. Concept/angle (biggest impact)
2. Hook/headline
3. Visual style
4. Body copy
5. CTA

---

## Campaign Optimization

### Key Metrics by Objective

| Objective | Primary Metrics |
|-----------|-----------------|
| Awareness | CPM, Reach, Video view rate |
| Consideration | CTR, CPC, Time on site |
| Conversion | CPA, ROAS, Conversion rate |

### Optimization Levers

**If CPA is too high:**
1. Check landing page (is the problem post-click?)
2. Tighten audience targeting
3. Test new creative angles
4. Improve ad relevance/quality score
5. Adjust bid strategy

**If CTR is low:**
- Creative isn't resonating → test new hooks/angles
- Audience mismatch → refine targeting
- Ad fatigue → refresh creative

**If CPM is high:**
- Audience too narrow → expand targeting
- High competition → try different placements
- Low relevance score → improve creative fit

### Bid Strategy Progression
1. Start with manual or cost caps
2. Gather conversion data (50+ conversions)
3. Switch to automated with targets based on historical data
4. Monitor and adjust targets based on results

---

## Retargeting Strategies

### Funnel-Based Approach

| Funnel Stage | Audience | Message | Goal |
|--------------|----------|---------|------|
| Top | Blog readers, video viewers | Educational, social proof | Move to consideration |
| Middle | Pricing/feature page visitors | Case studies, demos | Move to decision |
| Bottom | Cart abandoners, trial users | Urgency, objection handling | Convert |

### Retargeting Windows

| Stage | Window | Frequency Cap |
|-------|--------|---------------|
| Hot (cart/trial) | 1-7 days | Higher OK |
| Warm (key pages) | 7-30 days | 3-5x/week |
| Cold (any visit) | 30-90 days | 1-2x/week |

### Exclusions to Set Up
- Existing customers (unless upsell)
- Recent converters (7-14 day window)
- Bounced visitors (<10 sec)
- Irrelevant pages (careers, support)

---

## Reporting & Analysis

### Weekly Review
- Spend vs. budget pacing
- CPA/ROAS vs. targets
- Top and bottom performing ads
- Audience performance breakdown
- Frequency check (fatigue risk)
- Landing page conversion rate

### Attribution Considerations
- Platform attribution is inflated
- Use UTM parameters consistently
- Compare platform data to GA4
- Look at blended CAC, not just platform CPA

---

## Platform Setup

Before launching campaigns, ensure proper tracking and account setup.

**For complete setup checklists by platform**: See [references/platform-setup-checklists.md](references/platform-setup-checklists.md)

### Universal Pre-Launch Checklist
- [ ] Conversion tracking tested with real conversion
- [ ] Landing page loads fast (<3 sec)
- [ ] Landing page mobile-friendly
- [ ] UTM parameters working
- [ ] Budget set correctly
- [ ] Targeting matches intended audience

---

## Common Mistakes to Avoid

### Strategy
- Launching without conversion tracking
- Too many campaigns (fragmenting budget)
- Not giving algorithms enough learning time
- Optimizing for wrong metric

### Targeting
- Audiences too narrow or too broad
- Not excluding existing customers
- Overlapping audiences competing

### Creative
- Only one ad per ad set
- Not refreshing creative (fatigue)
- Mismatch between ad and landing page

### Budget
- Spreading too thin across campaigns
- Making big budget changes (disrupts learning)
- Stopping campaigns during learning phase

---

## Task-Specific Questions

1. What platform(s) are you currently running or want to start with?
2. What's your monthly ad budget?
3. What does a successful conversion look like (and what's it worth)?
4. Do you have existing creative assets or need to create them?
5. What landing page will ads point to?
6. Do you have pixel/conversion tracking set up?

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md). Key advertising platforms:

| Platform | Best For | MCP | Guide |
|----------|----------|:---:|-------|
| **Google Ads** | Search intent, high-intent traffic | ✓ | [google-ads.md](../../tools/integrations/google-ads.md) |
| **Meta Ads** | Demand gen, visual products, B2C | - | [meta-ads.md](../../tools/integrations/meta-ads.md) |
| **LinkedIn Ads** | B2B, job title targeting | - | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) |
| **TikTok Ads** | Younger demographics, video | - | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) |

For tracking, see also: [ga4.md](../../tools/integrations/ga4.md), [segment.md](../../tools/integrations/segment.md)

---

## Related Skills

- **ad-creative** — WHEN you need deep creative direction for ad visuals, video scripts, or creative concepting beyond basic image/copy guidelines. NOT for campaign strategy, targeting, or bidding decisions.
- **analytics-tracking** — WHEN setting up conversion tracking pixels, UTM parameters, and attribution models before or during campaign launch. NOT for campaign creation or creative work.
- **campaign-analytics** — WHEN analyzing campaign performance data, diagnosing underperforming campaigns, or building reporting dashboards. NOT for initial campaign setup or creative production.
- **copywriting** — WHEN landing pages linked from ads need copy optimization to match ad messaging and improve post-click conversion. NOT for the ad copy itself.
- **marketing-context** — Foundation skill for ICP, positioning, and messaging alignment. ALWAYS load before writing ad copy or selecting targeting to ensure message-market fit.

---

## Communication

Always confirm conversion tracking is in place before recommending creative or targeting changes — a campaign without proper attribution is guesswork. When recommending budget allocation, state the rationale (testing vs. scaling phase). Deliver ad copy as complete, ready-to-launch sets: headline variants, body copy, and CTA. Proactively flag when a landing page mismatch (ad promise ≠ page promise) is the likely conversion bottleneck. Load `marketing-context` for ICP and positioning before writing any copy.

---

## Proactive Triggers

- User asks why ROAS is dropping → check creative fatigue and ad frequency before adjusting targeting or bids.
- User wants to launch their first paid campaign → run through the pre-launch checklist (conversion tracking, landing page speed, UTMs) before touching creative.
- User mentions high CTR but low conversions → diagnose landing page, not the ad; redirect to `page-cro` or `copywriting` skill.
- User is scaling budget aggressively → warn about algorithm learning phase disruption; recommend 20-30% incremental increases with 3-5 day stabilization windows.
- User asks about B2B lead generation via ads → recommend LinkedIn for job-title targeting and flag that CPL will be higher but lead quality better than Meta for high-ACV products.

---

## Output Artifacts

| Artifact | Description |
|----------|-------------|
| Campaign Architecture | Full account structure with campaign names, ad set targeting, naming conventions, and budget allocation |
| Ad Copy Set | 3 headline variants, body copy, and CTA for each ad format and platform, ready to launch |
| Audience Targeting Brief | Primary audiences, lookalike seeds, retargeting segments, and exclusion lists per platform |
| Pre-Launch Checklist | Platform-specific tracking verification, landing page audit, and UTM parameter setup |
| Weekly Optimization Report Template | Metrics dashboard structure with CPA/ROAS targets, fatigue signals, and decision triggers |

FILE:references/ad-copy-templates.md
# Ad Copy Templates Reference

Detailed formulas and templates for writing high-converting ad copy.

## Primary Text Formulas

### Problem-Agitate-Solve (PAS)

```
[Problem statement]
[Agitate the pain]
[Introduce solution]
[CTA]
```

**Example:**
> Spending hours on manual reporting every week?
> While you're buried in spreadsheets, your competitors are making decisions.
> [Product] automates your reports in minutes.
> Start your free trial →

---

### Before-After-Bridge (BAB)

```
[Current painful state]
[Desired future state]
[Your product as the bridge]
```

**Example:**
> Before: Chasing down approvals across email, Slack, and spreadsheets.
> After: Every approval tracked, automated, and on time.
> [Product] connects your tools and keeps projects moving.

---

### Social Proof Lead

```
[Impressive stat or testimonial]
[What you do]
[CTA]
```

**Example:**
> "We cut our reporting time by 75%." — Sarah K., Marketing Director
> [Product] automates the reports you hate building.
> See how it works →

---

### Feature-Benefit Bridge

```
[Feature]
[So that...]
[Which means...]
```

**Example:**
> Real-time collaboration on documents
> So your team always works from the latest version
> Which means no more version confusion or lost work

---

### Direct Response

```
[Bold claim/outcome]
[Proof point]
[CTA with urgency if genuine]
```

**Example:**
> Cut your reporting time by 80%
> Join 5,000+ marketing teams already using [Product]
> Start free → First month 50% off

---

## Headline Formulas

### For Search Ads

| Formula | Example |
|---------|---------|
| [Keyword] + [Benefit] | "Project Management That Teams Actually Use" |
| [Action] + [Outcome] | "Automate Reports \| Save 10 Hours Weekly" |
| [Question] | "Tired of Manual Data Entry?" |
| [Number] + [Benefit] | "500+ Teams Trust [Product] for [Outcome]" |
| [Keyword] + [Differentiator] | "CRM Built for Small Teams" |
| [Price/Offer] + [Keyword] | "Free Project Management \| No Credit Card" |

### For Social Ads

| Type | Example |
|------|---------|
| Outcome hook | "How we 3x'd our conversion rate" |
| Curiosity hook | "The reporting hack no one talks about" |
| Contrarian hook | "Why we stopped using [common tool]" |
| Specificity hook | "The exact template we use for..." |
| Question hook | "What if you could cut your admin time in half?" |
| Number hook | "7 ways to improve your workflow today" |
| Story hook | "We almost gave up. Then we found..." |

---

## CTA Variations

### Soft CTAs (awareness/consideration)

Best for: Top of funnel, cold audiences, complex products

- Learn More
- See How It Works
- Watch Demo
- Get the Guide
- Explore Features
- See Examples
- Read the Case Study

### Hard CTAs (conversion)

Best for: Bottom of funnel, warm audiences, clear offers

- Start Free Trial
- Get Started Free
- Book a Demo
- Claim Your Discount
- Buy Now
- Sign Up Free
- Get Instant Access

### Urgency CTAs (use when genuine)

Best for: Limited-time offers, scarcity situations

- Limited Time: 30% Off
- Offer Ends [Date]
- Only X Spots Left
- Last Chance
- Early Bird Pricing Ends Soon

### Action-Oriented CTAs

Best for: Active voice, clear next step

- Start Saving Time Today
- Get Your Free Report
- See Your Score
- Calculate Your ROI
- Build Your First Project

---

## Platform-Specific Copy Guidelines

### Google Search Ads

- **Headline limits:** 30 characters each (up to 15 headlines)
- **Description limits:** 90 characters each (up to 4 descriptions)
- Include keywords naturally
- Use all available headline slots
- Include numbers and stats when possible
- Test dynamic keyword insertion

### Meta Ads (Facebook/Instagram)

- **Primary text:** 125 characters visible (can be longer, gets truncated)
- **Headline:** 40 characters recommended
- Front-load the hook (first line matters most)
- Emojis can work but test
- Questions perform well
- Keep image text under 20%

### LinkedIn Ads

- **Intro text:** 600 characters max (150 recommended)
- **Headline:** 200 characters max (70 recommended)
- Professional tone (but not boring)
- Specific job outcomes resonate
- Stats and social proof important
- Avoid consumer-style hype

---

## Copy Testing Priority

When testing ad copy, focus on these elements in order of impact:

1. **Hook/angle** (biggest impact on performance)
2. **Headline**
3. **Primary benefit**
4. **CTA**
5. **Supporting proof points**

Test one element at a time for clean data.

FILE:references/audience-targeting.md
# Audience Targeting Reference

Detailed targeting strategies for each major ad platform.

## Google Ads Audiences

### Search Campaign Targeting

**Keywords:**
- Exact match: [keyword] — most precise, lower volume
- Phrase match: "keyword" — moderate precision and volume
- Broad match: keyword — highest volume, use with smart bidding

**Audience layering:**
- Add audiences in "observation" mode first
- Analyze performance by audience
- Switch to "targeting" mode for high performers

**RLSA (Remarketing Lists for Search Ads):**
- Bid higher on past visitors searching your terms
- Show different ads to returning searchers
- Exclude converters from prospecting campaigns

### Display/YouTube Targeting

**Custom intent audiences:**
- Based on recent search behavior
- Create from your converting keywords
- High intent, good for prospecting

**In-market audiences:**
- People actively researching solutions
- Pre-built by Google
- Layer with demographics for precision

**Affinity audiences:**
- Based on interests and habits
- Better for awareness
- Broad but can exclude irrelevant

**Customer match:**
- Upload email lists
- Retarget existing customers
- Create lookalikes from best customers

**Similar/lookalike audiences:**
- Based on your customer match lists
- Expand reach while maintaining relevance
- Best when source list is high-quality customers

---

## Meta Audiences

### Core Audiences (Interest/Demographic)

**Interest targeting tips:**
- Layer interests with AND logic for precision
- Use Audience Insights to research interests
- Start broad, let algorithm optimize
- Exclude existing customers always

**Demographic targeting:**
- Age and gender (if product-specific)
- Location (down to zip/postal code)
- Language
- Education and work (limited data now)

**Behavior targeting:**
- Purchase behavior
- Device usage
- Travel patterns
- Life events

### Custom Audiences

**Website visitors:**
- All visitors (last 180 days max)
- Specific page visitors
- Time on site thresholds
- Frequency (visited X times)

**Customer list:**
- Upload emails/phone numbers
- Match rate typically 30-70%
- Refresh regularly for accuracy

**Engagement audiences:**
- Video viewers (25%, 50%, 75%, 95%)
- Page/profile engagers
- Form openers
- Instagram engagers

**App activity:**
- App installers
- In-app events
- Purchase events

### Lookalike Audiences

**Source audience quality matters:**
- Use high-LTV customers, not all customers
- Purchasers > leads > all visitors
- Minimum 100 source users, ideally 1,000+

**Size recommendations:**
- 1% — most similar, smallest reach
- 1-3% — good balance for most
- 3-5% — broader, good for scale
- 5-10% — very broad, awareness only

**Layering strategies:**
- Lookalike + interest = more precision early
- Test lookalike-only as you scale
- Exclude the source audience

---

## LinkedIn Audiences

### Job-Based Targeting

**Job titles:**
- Be specific (CMO vs. "Marketing")
- LinkedIn normalizes titles, but verify
- Stack related titles
- Exclude irrelevant titles

**Job functions:**
- Broader than titles
- Combine with seniority level
- Good for awareness campaigns

**Seniority levels:**
- Entry, Senior, Manager, Director, VP, CXO, Partner
- Layer with function for precision

**Skills:**
- Self-reported, less reliable
- Good for technical roles
- Use as expansion layer

### Company-Based Targeting

**Company size:**
- 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+
- Key filter for B2B

**Industry:**
- Based on company classification
- Can be broad, layer with other criteria

**Company names (ABM):**
- Upload target account list
- Minimum 300 companies recommended
- Match rate varies

**Company growth rate:**
- Hiring rapidly = budget available
- Good signal for timing

### High-Performing Combinations

| Use Case | Targeting Combination |
|----------|----------------------|
| Enterprise sales | Company size 1000+ + VP/CXO + Industry |
| SMB sales | Company size 11-200 + Manager/Director + Function |
| Developer tools | Skills + Job function + Company type |
| ABM campaigns | Company list + Decision-maker titles |
| Broad awareness | Industry + Seniority + Geography |

---

## Twitter/X Audiences

### Targeting options:
- Follower lookalikes (accounts similar to followers of X)
- Interest categories
- Keywords (in tweets)
- Conversation topics
- Events
- Tailored audiences (your lists)

### Best practices:
- Follower lookalikes of relevant accounts work well
- Keyword targeting catches active conversations
- Lower CPMs than LinkedIn/Meta
- Less precise, better for awareness

---

## TikTok Audiences

### Targeting options:
- Demographics (age, gender, location)
- Interests (TikTok's categories)
- Behaviors (video interactions)
- Device (iOS/Android, connection type)
- Custom audiences (pixel, customer file)
- Lookalike audiences

### Best practices:
- Younger skew (18-34 primarily)
- Interest targeting is broad
- Creative matters more than targeting
- Let algorithm optimize with broad targeting

---

## Audience Size Guidelines

| Platform | Minimum Recommended | Ideal Range |
|----------|-------------------|-------------|
| Google Search | 1,000+ searches/mo | 5,000-50,000 |
| Google Display | 100,000+ | 500K-5M |
| Meta | 100,000+ | 500K-10M |
| LinkedIn | 50,000+ | 100K-500K |
| Twitter/X | 50,000+ | 100K-1M |
| TikTok | 100,000+ | 1M+ |

Too narrow = expensive, slow learning
Too broad = wasted spend, poor relevance

---

## Exclusion Strategy

Always exclude:
- Existing customers (unless upsell)
- Recent converters (7-14 days)
- Bounced visitors (<10 sec)
- Employees (by company or email list)
- Irrelevant page visitors (careers, support)
- Competitors (if identifiable)

FILE:references/copy-frameworks.md
# Ad Copy Frameworks

Reference for selecting the right copy framework based on product type and campaign goal. Each framework includes a structure template and platform-specific length constraints.

## Framework selection matrix

| Product type | Pain-point heavy? | Transformation story? | Feature-led? | Recommended framework |
|---|---|---|---|---|
| SaaS / B2B | ✅ | | | PAS (Problem-Agitate-Solve) |
| Coaching / courses | | ✅ | | BAB (Before-After-Bridge) |
| Ecommerce / physical | | | ✅ | FAB (Features-Advantages-Benefits) |
| Content / info product | ✅ | ✅ | | AIDA (Attention-Interest-Desire-Action) |
| App / tool launch | | | ✅ | 4P (Promise-Picture-Proof-Push) |
| Services / consulting | ✅ | ✅ | | Star-Story-Solution |

## The 6 frameworks

### PAS — Problem → Agitate → Solve
**Best for:** Pain-point products, SaaS solving specific frustrations

```
Problem:  Name the exact pain (1 sentence)
Agitate:  Twist the knife — what happens if they don't fix it (1-2 sentences)
Solve:    Your product is the answer (1 sentence + CTA)
```

### BAB — Before → After → Bridge
**Best for:** Transformation products, coaching, courses

```
Before:   Current painful state (1 sentence)
After:    Desired state they'll achieve (1 sentence)
Bridge:   Your product connects the two (1 sentence + CTA)
```

### AIDA — Attention → Interest → Desire → Action
**Best for:** Content marketing, info products, broad audiences

```
Attention: Hook with a surprising stat or question
Interest:  Explain why this matters to them
Desire:    Show social proof or specific outcomes
Action:    Clear CTA with urgency
```

### FAB — Features → Advantages → Benefits
**Best for:** Product-led, ecommerce, feature-rich offerings

```
Feature:    What it has (spec/capability)
Advantage:  Why that matters vs alternatives
Benefit:    What the user gains (outcome)
```

### 4P — Promise → Picture → Proof → Push
**Best for:** App launches, tools, direct response

```
Promise:  Bold claim (1 headline)
Picture:  Vivid scenario of life with the product
Proof:    Social proof, stats, testimonial
Push:     Strong CTA with urgency/scarcity
```

### Star-Story-Solution
**Best for:** Personal brands, services, consulting

```
Star:      Introduce the hero (the customer, not you)
Story:     Their struggle (relatable narrative)
Solution:  How your service transforms their situation
```

## Platform-specific constraints

| Platform | Headline | Body | CTA |
|---|---|---|---|
| Google RSA | 30 chars × 15 headlines | 90 chars × 4 descriptions | Auto from list |
| Meta Feed | 40 chars (before truncation) | 125 chars primary text (before "See more") | Button from list |
| Meta Stories | 40 chars overlay | Minimal — visual-first | Swipe up / button |
| LinkedIn Sponsored | 70 chars intro text visible | 150 chars before truncation | Button from list |
| TikTok | Overlay text in video | Caption 100 chars | Button from list |
| Microsoft | 30 chars × 15 headlines | 90 chars × 4 descriptions | Auto from list |

## Brand DNA extraction (7 voice axes)

Before writing ad copy, extract the brand's voice profile on these 7 axes:

```json
{
  "formal_casual": 0.7,       // 0 = corporate formal, 1 = casual/friendly
  "bold_subtle": 0.6,         // 0 = understated, 1 = bold/provocative
  "technical_human": 0.4,     // 0 = jargon-heavy, 1 = plain language
  "serious_playful": 0.5,     // 0 = gravitas, 1 = humor/wit
  "traditional_innovative": 0.8, // 0 = established, 1 = cutting-edge
  "exclusive_inclusive": 0.6,  // 0 = luxury/elite, 1 = accessible/everyone
  "data_emotional": 0.5       // 0 = stats-driven, 1 = story-driven
}
```

Save as `brand-profile.json` for reuse across campaigns. Each axis is 0.0-1.0.

FILE:references/platform-setup-checklists.md
# Platform Setup Checklists

Complete setup checklists for major ad platforms.

## Google Ads Setup

### Account Foundation

- [ ] Google Ads account created and verified
- [ ] Billing information added
- [ ] Time zone and currency set correctly
- [ ] Account access granted to team members

### Conversion Tracking

- [ ] Google tag installed on all pages
- [ ] Conversion actions created (purchase, lead, signup)
- [ ] Conversion values assigned (if applicable)
- [ ] Enhanced conversions enabled
- [ ] Test conversions firing correctly
- [ ] Import conversions from GA4 (optional)

### Analytics Integration

- [ ] Google Analytics 4 linked
- [ ] Auto-tagging enabled
- [ ] GA4 audiences available in Google Ads
- [ ] Cross-domain tracking set up (if multiple domains)

### Audience Setup

- [ ] Remarketing tag verified
- [ ] Website visitor audiences created:
  - All visitors (180 days)
  - Key page visitors (pricing, demo, features)
  - Converters (for exclusion)
- [ ] Customer match lists uploaded
- [ ] Similar audiences enabled

### Campaign Readiness

- [ ] Negative keyword lists created:
  - Universal negatives (free, jobs, careers, reviews, complaints)
  - Competitor negatives (if needed)
  - Irrelevant industry terms
- [ ] Location targeting set (include/exclude)
- [ ] Language targeting set
- [ ] Ad schedule configured (if B2B, business hours)
- [ ] Device bid adjustments considered

### Ad Extensions

- [ ] Sitelinks (4-6 relevant pages)
- [ ] Callouts (key benefits, offers)
- [ ] Structured snippets (features, types, services)
- [ ] Call extension (if phone leads valuable)
- [ ] Lead form extension (if using)
- [ ] Price extensions (if applicable)
- [ ] Image extensions (where available)

### Brand Protection

- [ ] Brand campaign running (protect branded terms)
- [ ] Competitor campaigns considered
- [ ] Brand terms in negative lists for non-brand campaigns

---

## Meta Ads Setup

### Business Manager Foundation

- [ ] Business Manager created
- [ ] Business verified (if running certain ad types)
- [ ] Ad account created within Business Manager
- [ ] Payment method added
- [ ] Team access configured with proper roles

### Pixel & Tracking

- [ ] Meta Pixel installed on all pages
- [ ] Standard events configured:
  - PageView (automatic)
  - ViewContent (product/feature pages)
  - Lead (form submissions)
  - Purchase (conversions)
  - AddToCart (if e-commerce)
  - InitiateCheckout (if e-commerce)
- [ ] Conversions API (CAPI) set up for server-side tracking
- [ ] Event Match Quality score > 6
- [ ] Test events in Events Manager

### Domain & Aggregated Events

- [ ] Domain verified in Business Manager
- [ ] Aggregated Event Measurement configured
- [ ] Top 8 events prioritized in order of importance
- [ ] Web events prioritized for iOS 14+ tracking

### Audience Setup

- [ ] Custom audiences created:
  - Website visitors (all, 30/60/90/180 days)
  - Key page visitors
  - Video viewers (25%, 50%, 75%, 95%)
  - Page/Instagram engagers
  - Customer list uploaded
- [ ] Lookalike audiences created (1%, 1-3%)
- [ ] Saved audiences for common targeting

### Catalog (E-commerce)

- [ ] Product catalog connected
- [ ] Product feed updating correctly
- [ ] Catalog sales campaigns enabled
- [ ] Dynamic product ads configured

### Creative Assets

- [ ] Images in correct sizes:
  - Feed: 1080x1080 (1:1)
  - Stories/Reels: 1080x1920 (9:16)
  - Landscape: 1200x628 (1.91:1)
- [ ] Videos in correct formats
- [ ] Ad copy variations ready
- [ ] UTM parameters in all destination URLs

### Compliance

- [ ] Special Ad Categories declared (if housing, credit, employment, politics)
- [ ] Landing page complies with Meta policies
- [ ] No prohibited content in ads

---

## LinkedIn Ads Setup

### Campaign Manager Foundation

- [ ] Campaign Manager account created
- [ ] Company Page connected
- [ ] Billing information added
- [ ] Team access configured

### Insight Tag & Tracking

- [ ] LinkedIn Insight Tag installed on all pages
- [ ] Tag verified and firing
- [ ] Conversion tracking configured:
  - URL-based conversions
  - Event-specific conversions
- [ ] Conversion values set (if applicable)

### Audience Setup

- [ ] Matched Audiences created:
  - Website retargeting audiences
  - Company list uploaded (for ABM)
  - Contact list uploaded
- [ ] Lookalike audiences created
- [ ] Saved audiences for common targeting

### Lead Gen Forms (if using)

- [ ] Lead gen form templates created
- [ ] Form fields selected (minimize for conversion)
- [ ] Privacy policy URL added
- [ ] Thank you message configured
- [ ] CRM integration set up (or CSV export process)

### Document Ads (if using)

- [ ] Documents uploaded (PDF, PowerPoint)
- [ ] Gating configured (full gate or preview)
- [ ] Lead gen form connected

### Creative Assets

- [ ] Single image ads: 1200x627 (1.91:1) or 1080x1080 (1:1)
- [ ] Carousel images ready
- [ ] Video specs met (if using)
- [ ] Ad copy within character limits:
  - Intro text: 600 max, 150 recommended
  - Headline: 200 max, 70 recommended

### Budget Considerations

- [ ] Budget realistic for LinkedIn CPCs ($8-15+ typical)
- [ ] Audience size validated (50K+ recommended)
- [ ] Daily vs. lifetime budget decided
- [ ] Bid strategy selected

---

## Twitter/X Ads Setup

### Account Foundation

- [ ] Ads account created
- [ ] Payment method added
- [ ] Account verified (if required)

### Tracking

- [ ] Twitter Pixel installed
- [ ] Conversion events created
- [ ] Website tag verified

### Audience Setup

- [ ] Tailored audiences created:
  - Website visitors
  - Customer lists
- [ ] Follower lookalikes identified
- [ ] Interest and keyword targets researched

### Creative

- [ ] Tweet copy within 280 characters
- [ ] Images: 1200x675 (1.91:1) or 1200x1200 (1:1)
- [ ] Video specs met (if using)
- [ ] Cards configured (website, app, etc.)

---

## TikTok Ads Setup

### Account Foundation

- [ ] TikTok Ads Manager account created
- [ ] Business verification completed
- [ ] Payment method added

### Pixel & Tracking

- [ ] TikTok Pixel installed
- [ ] Events configured (ViewContent, Purchase, etc.)
- [ ] Events API set up (recommended)

### Audience Setup

- [ ] Custom audiences created
- [ ] Lookalike audiences created
- [ ] Interest categories identified

### Creative

- [ ] Vertical video (9:16) ready
- [ ] Native-feeling content (not too polished)
- [ ] First 3 seconds are compelling hooks
- [ ] Captions added (most watch without sound)
- [ ] Music/sounds selected (licensed if needed)

---

## Universal Pre-Launch Checklist

Before launching any campaign:

- [ ] Conversion tracking tested with real conversion
- [ ] Landing page loads fast (<3 sec)
- [ ] Landing page mobile-friendly
- [ ] UTM parameters working
- [ ] Budget set correctly (daily vs. lifetime)
- [ ] Start/end dates correct
- [ ] Targeting matches intended audience
- [ ] Ad creative approved
- [ ] Team notified of launch
- [ ] Reporting dashboard ready

FILE:references/scoring-system.md
# Ad Account Scoring System

Reference for `ad_health_scorer.py`. Defines the weighted scoring algorithm, severity multipliers, and platform-specific category weights.

## Scoring formula

```
Category_Score = Σ(Check_Result × Severity_Multiplier) / Σ(Severity_Multiplier) × 100
Platform_Score = Σ(Category_Score × Category_Weight)
Aggregate_Score = Σ(Platform_Score × Budget_Share)
```

## Severity multipliers

| Severity | Multiplier | Meaning | SLA |
|---|---|---|---|
| Critical | 5.0x | Blocks revenue or burns budget | Fix immediately |
| High | 3.0x | Significant performance impact | Fix within 1 week |
| Medium | 1.5x | Optimization opportunity | Fix within 1 month |
| Low | 0.5x | Polish / best practice | Backlog |

Critical issues dominate the score. A single critical failure drops the category score significantly, which is the correct behavior — a missing conversion tag invalidates everything downstream.

## Platform category weights

### Google Ads
| Category | Weight | Key checks |
|---|---|---|
| Conversion Tracking | 25% | Tag installed, Enhanced Conversions, attribution model, conversion window |
| Wasted Spend | 20% | Negative keywords, search terms review, broad match rules, 3× CPA kill rule |
| Account Structure | 15% | Naming conventions, ad group size, campaign types |
| Keywords | 15% | Quality Score, duplicates, match types, search intent alignment |
| Ads | 15% | RSA headlines count, extensions, A/B testing |
| Settings | 10% | Location targeting, schedules, networks, bidding strategy |

### Meta (Facebook/Instagram)
| Category | Weight | Key checks |
|---|---|---|
| Pixel & CAPI | 30% | Pixel installed, CAPI active, event deduplication, domain verification |
| Creative | 30% | Format diversity, fatigue detection, safe zones, copy length |
| Structure | 20% | CBO, campaign naming, advantage+ settings |
| Audience | 20% | Lookalike seed size, exclusions, overlap, custom audiences |

### LinkedIn
| Category | Weight | Key checks |
|---|---|---|
| Technical | 25% | Insight tag, conversion events, matched audiences |
| Targeting | 25% | Audience size, job function vs title, company lists |
| Creative | 25% | Format mix, single-image vs carousel vs video, CTA alignment |
| Budget | 25% | Daily budget sufficiency, bid strategy, pacing |

### TikTok
| Category | Weight | Key checks |
|---|---|---|
| Pixel | 25% | Pixel installed, events configured, match quality |
| Creative | 30% | Native-feel content, format mix, hook rate (3s), UGC ratio |
| Targeting | 25% | Interest vs behavior, custom audiences, lookalikes |
| Budget | 20% | Learning phase budget (50× target CPA), pacing |

## Grade bands

| Grade | Score | Meaning |
|---|---|---|
| A | 90-100 | Excellent — maintain and scale |
| B | 75-89 | Good — address high-priority items |
| C | 60-74 | Needs work — systematic improvements needed |
| D | 40-59 | Poor — significant issues blocking performance |
| F | <40 | Critical — account needs fundamental restructuring |

Bands are calibrated wider than SEO scoring because ad accounts typically have more actionable but non-critical issues (e.g., missing extensions, suboptimal ad copy).

## Quick Wins formula

```
Quick Win = severity ∈ {critical, high} AND result = "warn" (not full fail)
```

Quick wins are issues that are important (high severity) but partially working (warn, not fail) — meaning the fix is usually small: enable a toggle, add a few negative keywords, activate an extension.

## Hard rules (quality gates)

These combinations should NEVER be recommended together:
- Broad Match + Manual CPC (wastes budget without smart bidding control)
- CPA target below $5 with < $50/day budget (can't exit learning phase)
- Conversion action = page view as primary (inflates numbers, misleads bidding)

The scorer doesn't enforce these directly but the SKILL.md workflow should flag them as critical failures.

FILE:scripts/ad_health_scorer.py
#!/usr/bin/env python3
"""
ad_health_scorer.py — Weighted 0-100 ad account health score with multi-platform support.

Scores ad accounts across platform-specific categories with severity multipliers
and budget-weighted cross-platform aggregation.

Severity multipliers:
  critical = 5x weight (blocks revenue or burns budget)
  high     = 3x weight (significant impact)
  medium   = 1.5x weight (optimization opportunity)
  low      = 0.5x weight (backlog polish)

Platform category weights:
  Google:   Conversion Tracking 25%, Wasted Spend 20%, Structure 15%, Keywords 15%, Ads 15%, Settings 10%
  Meta:     Pixel/CAPI 30%, Creative 30%, Structure 20%, Audience 20%
  LinkedIn: Technical 25%, Targeting 25%, Creative 25%, Budget 25%
  TikTok:   Pixel 25%, Creative 30%, Targeting 25%, Budget 20%

Cross-platform aggregation:
  Aggregate Score = Σ(Platform_Score × Platform_Budget_Share)

Grade bands (calibrated wider — ad accounts naturally score lower):
  A = 90-100, B = 75-89, C = 60-74, D = 40-59, F = <40

Usage:
    python ad_health_scorer.py --checks checks.json
    python ad_health_scorer.py --checks checks.json --platform google --budget 5000
    python ad_health_scorer.py --multi platforms.json   # multi-platform aggregation
    python ad_health_scorer.py --demo
    python ad_health_scorer.py --demo --json
"""
from __future__ import annotations
import argparse
import json
import sys
from collections import defaultdict
from pathlib import Path

SEVERITY_MULTIPLIER = {"critical": 5.0, "high": 3.0, "medium": 1.5, "low": 0.5}

PLATFORM_WEIGHTS = {
    "google": {
        "conversion_tracking": 0.25,
        "wasted_spend": 0.20,
        "account_structure": 0.15,
        "keywords": 0.15,
        "ads": 0.15,
        "settings": 0.10,
    },
    "meta": {
        "pixel_capi": 0.30,
        "creative": 0.30,
        "structure": 0.20,
        "audience": 0.20,
    },
    "linkedin": {
        "technical": 0.25,
        "targeting": 0.25,
        "creative": 0.25,
        "budget": 0.25,
    },
    "tiktok": {
        "pixel": 0.25,
        "creative": 0.30,
        "targeting": 0.25,
        "budget": 0.20,
    },
}

DEMO_CHECKS = {
    "google": [
        {"category": "conversion_tracking", "check": "Google Ads conversion tag installed", "result": "pass", "severity": "critical"},
        {"category": "conversion_tracking", "check": "Enhanced Conversions enabled", "result": "fail", "severity": "critical", "detail": "Missing enhanced conversions — losing 15-30% attribution"},
        {"category": "conversion_tracking", "check": "Conversion window appropriate", "result": "pass", "severity": "medium"},
        {"category": "wasted_spend", "check": "Negative keyword coverage", "result": "warn", "severity": "high", "detail": "Only 12 negative keywords — review search terms report"},
        {"category": "wasted_spend", "check": "No broad match + manual CPC", "result": "pass", "severity": "critical"},
        {"category": "wasted_spend", "check": "Search terms review (last 30d)", "result": "fail", "severity": "high", "detail": "23% of spend on irrelevant terms"},
        {"category": "account_structure", "check": "Campaign naming convention", "result": "pass", "severity": "low"},
        {"category": "account_structure", "check": "Ad groups ≤ 20 keywords each", "result": "warn", "severity": "medium", "detail": "2 ad groups with 30+ keywords"},
        {"category": "keywords", "check": "No duplicate keywords across campaigns", "result": "pass", "severity": "high"},
        {"category": "keywords", "check": "Quality Score ≥ 6 on top spenders", "result": "warn", "severity": "high", "detail": "3 keywords with QS 4-5"},
        {"category": "ads", "check": "RSA with ≥ 3 headlines", "result": "pass", "severity": "medium"},
        {"category": "ads", "check": "Ad extensions active (sitelinks, callouts)", "result": "fail", "severity": "medium", "detail": "No callout extensions"},
        {"category": "settings", "check": "Location targeting correct", "result": "pass", "severity": "high"},
        {"category": "settings", "check": "Ad schedule aligned with business hours", "result": "pass", "severity": "low"},
    ],
    "meta": [
        {"category": "pixel_capi", "check": "Meta Pixel installed", "result": "pass", "severity": "critical"},
        {"category": "pixel_capi", "check": "Conversions API (CAPI) active", "result": "fail", "severity": "critical", "detail": "No server-side events — degraded attribution post-iOS14"},
        {"category": "creative", "check": "Creative diversity (≥ 3 formats)", "result": "warn", "severity": "high", "detail": "Only static images — add video and carousel"},
        {"category": "creative", "check": "No creative fatigue (CTR stable)", "result": "pass", "severity": "high"},
        {"category": "structure", "check": "CBO enabled", "result": "pass", "severity": "medium"},
        {"category": "audience", "check": "Lookalike seed ≥ 1000 users", "result": "pass", "severity": "medium"},
    ],
}


def score_platform(checks, platform):
    weights = PLATFORM_WEIGHTS.get(platform, {})
    by_category = defaultdict(list)
    for c in checks:
        by_category[c.get("category", "other")].append(c)

    category_scores = {}
    findings = []
    quick_wins = []

    for cat, cat_checks in by_category.items():
        weighted_pass = 0.0
        weighted_total = 0.0
        for check in cat_checks:
            result = check.get("result", "fail")
            severity = check.get("severity", "medium")
            mult = SEVERITY_MULTIPLIER.get(severity, 1.0)
            score = {"pass": 1.0, "warn": 0.5, "fail": 0.0}.get(result, 0.0)
            weighted_pass += score * mult
            weighted_total += mult
            if result != "pass":
                finding = {
                    "platform": platform,
                    "category": cat,
                    "check": check.get("check", ""),
                    "result": result,
                    "severity": severity,
                    "detail": check.get("detail", ""),
                }
                findings.append(finding)
                # Quick win: high/critical severity + warn (not full fail)
                if severity in ("critical", "high") and result == "warn":
                    quick_wins.append(finding)

        cat_score = (weighted_pass / weighted_total * 100) if weighted_total > 0 else 100
        category_scores[cat] = round(cat_score, 1)

    # Weighted overall
    overall = 0.0
    total_weight = 0.0
    for cat, weight in weights.items():
        if cat in category_scores:
            overall += category_scores[cat] * weight
            total_weight += weight
    overall = (overall / total_weight) if total_weight > 0 else 0.0

    if overall >= 90:
        grade = "A"
    elif overall >= 75:
        grade = "B"
    elif overall >= 60:
        grade = "C"
    elif overall >= 40:
        grade = "D"
    else:
        grade = "F"

    findings.sort(key=lambda f: {"critical": 0, "high": 1, "medium": 2, "low": 3}.get(f["severity"], 99))

    return {
        "platform": platform,
        "overall_score": round(overall, 1),
        "grade": grade,
        "category_scores": category_scores,
        "total_checks": len(checks),
        "passed": sum(1 for c in checks if c.get("result") == "pass"),
        "warnings": sum(1 for c in checks if c.get("result") == "warn"),
        "failures": sum(1 for c in checks if c.get("result") == "fail"),
        "findings": findings,
        "quick_wins": quick_wins,
    }


def aggregate_platforms(platform_results, budgets=None):
    if not budgets:
        # Equal weight
        budgets = {p["platform"]: 1.0 / len(platform_results) for p in platform_results}
    total_budget = sum(budgets.values())
    shares = {k: v / total_budget for k, v in budgets.items()}

    aggregate = 0.0
    for pr in platform_results:
        share = shares.get(pr["platform"], 0)
        aggregate += pr["overall_score"] * share

    return {
        "aggregate_score": round(aggregate, 1),
        "budget_shares": {k: round(v, 2) for k, v in shares.items()},
        "platform_scores": {pr["platform"]: pr["overall_score"] for pr in platform_results},
    }


def print_report(result):
    print(f"Ad Health Score ({result['platform'].upper()}): {result['overall_score']}/100 (Grade: {result['grade']})")
    print(f"Checks: {result['total_checks']} — {result['passed']} pass, {result['warnings']} warn, {result['failures']} fail")
    print()
    print("Category Breakdown:")
    for cat, score in sorted(result["category_scores"].items()):
        bar = "█" * int(score / 5) + "░" * (20 - int(score / 5))
        print(f"  {cat:25s} {bar} {score:5.1f}/100")
    print()
    if result["quick_wins"]:
        print(f"Quick Wins ({len(result['quick_wins'])}):")
        for f in result["quick_wins"]:
            print(f"  ⚡ [{f['severity'].upper()}] {f['check']}: {f['detail']}")
        print()
    if result["findings"]:
        print(f"Findings ({len(result['findings'])}):")
        for f in result["findings"]:
            detail = f" — {f['detail']}" if f["detail"] else ""
            print(f"  [{f['severity'].upper()}/{f['result'].upper()}] {f['check']}{detail}")


def main():
    p = argparse.ArgumentParser(
        description="Compute weighted 0-100 ad account health score with severity multipliers.",
        epilog="Supports Google, Meta, LinkedIn, TikTok. Run with --demo for a sample report.",
    )
    p.add_argument("--checks", help="Path to checks JSON file (array of check objects)")
    p.add_argument("--platform", choices=list(PLATFORM_WEIGHTS.keys()), default="google")
    p.add_argument("--budget", type=float, default=None, help="Monthly budget (for multi-platform weighting)")
    p.add_argument("--multi", help="Path to multi-platform JSON {platform: {checks: [...], budget: N}}")
    p.add_argument("--json", action="store_true", help="JSON output")
    p.add_argument("--demo", action="store_true", help="Run with demo data")
    args = p.parse_args()

    if args.demo:
        results = []
        for platform, checks in DEMO_CHECKS.items():
            results.append(score_platform(checks, platform))
        agg = aggregate_platforms(results, {"google": 3000, "meta": 2000})

        if args.json:
            print(json.dumps({"platforms": results, "aggregate": agg}, indent=2))
        else:
            for r in results:
                print_report(r)
                print()
            print(f"Cross-Platform Aggregate: {agg['aggregate_score']}/100")
            print(f"Budget shares: {agg['budget_shares']}")
        return

    if args.multi:
        data = json.loads(Path(args.multi).read_text())
        results = []
        budgets = {}
        for platform, pdata in data.items():
            results.append(score_platform(pdata["checks"], platform))
            budgets[platform] = pdata.get("budget", 1000)
        agg = aggregate_platforms(results, budgets)
        if args.json:
            print(json.dumps({"platforms": results, "aggregate": agg}, indent=2))
        else:
            for r in results:
                print_report(r)
                print()
            print(f"Cross-Platform Aggregate: {agg['aggregate_score']}/100")
        return

    if args.checks:
        checks = json.loads(Path(args.checks).read_text())
        result = score_platform(checks, args.platform)
        if args.json:
            print(json.dumps(result, indent=2))
        else:
            print_report(result)
        return

    p.print_help()


if __name__ == "__main__":
    main()

FILE:scripts/roas_calculator.py
#!/usr/bin/env python3
"""
roas_calculator.py — ROAS and paid-ads metrics calculator
Usage:
  python3 roas_calculator.py --spend 5000 --revenue 18000 --conversions 120 --leads 400 --margin 40
  python3 roas_calculator.py --file campaign.json
  python3 roas_calculator.py --json          # demo + JSON output
  python3 roas_calculator.py                 # demo mode
"""

import argparse
import json
import sys


# ---------------------------------------------------------------------------
# Calculation core
# ---------------------------------------------------------------------------

def calculate(spend: float, revenue: float = 0.0, conversions: int = 0,
              leads: int = 0, margin_pct: float = 0.0,
              impressions: int = 0, clicks: int = 0) -> dict:

    results = {
        "inputs": {
            "ad_spend": spend,
            "revenue": revenue,
            "conversions": conversions,
            "leads": leads,
            "margin_pct": margin_pct,
            "impressions": impressions,
            "clicks": clicks,
        }
    }

    metrics = {}

    # --- ROAS ---
    if revenue > 0 and spend > 0:
        roas = revenue / spend
        metrics["roas"] = {
            "value": round(roas, 2),
            "formula": "revenue / ad_spend",
            "interpretation": _roas_label(roas),
        }

    # --- Break-even ROAS ---
    if margin_pct > 0:
        be_roas = 100 / margin_pct
        metrics["break_even_roas"] = {
            "value": round(be_roas, 2),
            "formula": "100 / margin_%",
            "note": f"Need {be_roas:.1f}x ROAS to cover ad costs at {margin_pct}% margin",
        }
        if revenue > 0:
            actual_roas = revenue / spend
            profitable = actual_roas >= be_roas
            metrics["profitability"] = {
                "is_profitable": profitable,
                "gap": round(actual_roas - be_roas, 2),
                "note": "Profitable ✅" if profitable else f"Unprofitable ❌ — need +{be_roas - actual_roas:.2f}x ROAS",
            }

    # --- CPA ---
    if conversions > 0 and spend > 0:
        cpa = spend / conversions
        metrics["cpa"] = {
            "value": round(cpa, 2),
            "formula": "ad_spend / conversions",
            "unit": "cost per acquisition",
        }
        if revenue > 0:
            rev_per_conversion = revenue / conversions
            metrics["revenue_per_conversion"] = {
                "value": round(rev_per_conversion, 2),
                "roi_per_conversion": round((rev_per_conversion - cpa) / cpa * 100, 1),
            }

    # --- CPL ---
    if leads > 0 and spend > 0:
        cpl = spend / leads
        metrics["cpl"] = {
            "value": round(cpl, 2),
            "formula": "ad_spend / leads",
            "unit": "cost per lead",
        }
        if conversions > 0:
            lead_to_conv_rate = conversions / leads * 100
            metrics["lead_to_conversion_rate"] = {
                "value": round(lead_to_conv_rate, 1),
                "unit": "%",
            }

    # --- Conversion rate ---
    if clicks > 0 and conversions > 0:
        cvr = conversions / clicks * 100
        metrics["conversion_rate"] = {
            "value": round(cvr, 2),
            "unit": "%",
            "benchmark": "2-5% typical for paid search",
        }
    if clicks > 0 and leads > 0:
        lcr = leads / clicks * 100
        metrics["lead_capture_rate"] = {
            "value": round(lcr, 2),
            "unit": "%",
        }

    # --- CTR ---
    if impressions > 0 and clicks > 0:
        ctr = clicks / impressions * 100
        metrics["ctr"] = {
            "value": round(ctr, 2),
            "unit": "%",
            "benchmark": "2-5% for search, 0.1-0.5% for display",
        }
        cpm = spend / impressions * 1000
        metrics["cpm"] = {
            "value": round(cpm, 2),
            "unit": "cost per 1000 impressions",
        }
        cpc = spend / clicks
        metrics["cpc"] = {
            "value": round(cpc, 2),
            "unit": "cost per click",
        }

    results["metrics"] = metrics
    results["recommendations"] = _recommendations(metrics, spend, margin_pct)
    return results


def _roas_label(roas: float) -> str:
    if roas >= 8:
        return "Excellent (8x+)"
    if roas >= 5:
        return "Strong (5-8x)"
    if roas >= 3:
        return "Good (3-5x)"
    if roas >= 2:
        return "Acceptable (2-3x) — check margins"
    if roas >= 1:
        return "Below target (<2x) — likely unprofitable"
    return "Losing money (<1x)"


def _recommendations(metrics: dict, spend: float, margin_pct: float) -> list:
    recs = []

    roas = metrics.get("roas", {}).get("value")
    be_roas = metrics.get("break_even_roas", {}).get("value")

    if roas and be_roas:
        if roas < be_roas:
            shortfall = round((be_roas - roas) * spend, 2)
            recs.append(f"⚠️  Losing ,.2f/period — pause or restructure campaign immediately")
        elif roas < be_roas * 1.5:
            recs.append("⚠️  Marginally profitable — optimize creatives and targeting before scaling")
        else:
            recs.append("✅  Profitable — consider increasing budget or duplicating campaign")

    cpa = metrics.get("cpa", {}).get("value")
    cpl = metrics.get("cpl", {}).get("value")
    cvr = metrics.get("conversion_rate", {}).get("value")

    if cvr and cvr < 2:
        recs.append(f"⚠️  CVR {cvr}% is low — test new landing pages, headlines, and CTAs")
    elif cvr and cvr >= 5:
        recs.append(f"✅  Strong CVR {cvr}% — maximize traffic to this funnel")

    if cpa and cpl:
        l2c = metrics.get("lead_to_conversion_rate", {}).get("value", 0)
        if l2c < 10:
            recs.append(f"⚠️  Lead-to-close rate {l2c}% is low — review sales qualification or nurture sequence")

    ctr = metrics.get("ctr", {}).get("value")
    if ctr:
        if ctr < 1:
            recs.append(f"⚠️  CTR {ctr}% is low — refresh ad copy and audience targeting")
        elif ctr >= 5:
            recs.append(f"✅  High CTR {ctr}% — strong creative, ensure LP matches ad message")

    if not recs:
        recs.append("Add more data (margin %, impressions, leads) for actionable recommendations")

    return recs


# ---------------------------------------------------------------------------
# Demo data
# ---------------------------------------------------------------------------

DEMO_DATA = {
    "spend": 8500,
    "revenue": 34200,
    "conversions": 142,
    "leads": 680,
    "margin_pct": 35,
    "impressions": 185000,
    "clicks": 3700,
}


# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------

def main():
    parser = argparse.ArgumentParser(
        description="ROAS calculator — paid ads performance metrics and recommendations."
    )
    parser.add_argument("--spend",       type=float, help="Total ad spend ($)")
    parser.add_argument("--revenue",     type=float, default=0, help="Total attributed revenue ($)")
    parser.add_argument("--conversions", type=int,   default=0, help="Number of purchases/conversions")
    parser.add_argument("--leads",       type=int,   default=0, help="Number of leads generated")
    parser.add_argument("--margin",      type=float, default=0, help="Gross margin %% (e.g. 40)")
    parser.add_argument("--impressions", type=int,   default=0, help="Total impressions")
    parser.add_argument("--clicks",      type=int,   default=0, help="Total clicks")
    parser.add_argument("--file",        help="JSON file with campaign data")
    parser.add_argument("--json",        action="store_true", help="Output as JSON")
    args = parser.parse_args()

    if args.file:
        with open(args.file, "r") as f:
            data = json.load(f)
    elif args.spend:
        data = {
            "spend": args.spend,
            "revenue": args.revenue,
            "conversions": args.conversions,
            "leads": args.leads,
            "margin_pct": args.margin,
            "impressions": args.impressions,
            "clicks": args.clicks,
        }
    else:
        data = DEMO_DATA
        if not args.json:
            print("No input provided — running in demo mode.\n")

    result = calculate(
        spend=data.get("spend", 0),
        revenue=data.get("revenue", 0),
        conversions=data.get("conversions", 0),
        leads=data.get("leads", 0),
        margin_pct=data.get("margin_pct", 0),
        impressions=data.get("impressions", 0),
        clicks=data.get("clicks", 0),
    )

    if args.json:
        print(json.dumps(result, indent=2))
        return

    inp = result["inputs"]
    metrics = result["metrics"]
    recs = result["recommendations"]

    print("=" * 62)
    print("  PAID ADS PERFORMANCE REPORT")
    print("=" * 62)
    print(f"  Spend:      >10,.2f")
    if inp["revenue"]:    print(f"  Revenue:    >10,.2f")
    if inp["conversions"]:print(f"  Conversions:{inp['conversions']:>10}")
    if inp["leads"]:      print(f"  Leads:      {inp['leads']:>10}")
    if inp["impressions"]:print(f"  Impressions:{inp['impressions']:>10,}")
    if inp["clicks"]:     print(f"  Clicks:     {inp['clicks']:>10,}")

    print()
    print("  METRICS")
    print("  " + "─" * 58)

    metric_labels = [
        ("roas",                   "ROAS",                    lambda m: f"{m['value']}x  — {m['interpretation']}"),
        ("break_even_roas",        "Break-even ROAS",         lambda m: f"{m['value']}x  — {m['note']}"),
        ("profitability",          "Profitability",           lambda m: m['note']),
        ("cpa",                    "CPA",                     lambda m: f",.2f / {m['unit']}"),
        ("revenue_per_conversion", "Rev/Conversion",          lambda m: f",.2f  (ROI {m['roi_per_conversion']}%)"),
        ("cpl",                    "CPL",                     lambda m: f",.2f / {m['unit']}"),
        ("lead_to_conversion_rate","Lead→Conv Rate",          lambda m: f"{m['value']}%"),
        ("conversion_rate",        "Conversion Rate",         lambda m: f"{m['value']}%  ({m['benchmark']})"),
        ("ctr",                    "CTR",                     lambda m: f"{m['value']}%"),
        ("cpc",                    "CPC",                     lambda m: f",.2f"),
        ("cpm",                    "CPM",                     lambda m: f",.2f"),
    ]

    for key, label, fmt in metric_labels:
        if key in metrics:
            try:
                detail = fmt(metrics[key])
                print(f"  {label:<24} {detail}")
            except Exception:
                pass

    print()
    print("  RECOMMENDATIONS")
    print("  " + "─" * 58)
    for rec in recs:
        print(f"  {rec}")
    print("=" * 62)


if __name__ == "__main__":
    main()

---
name: "pm-skills"
description: "6 project management agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Senior PM, scrum master, Jira expert (JQL), Confluence expert, Atlassian admin, template creator. MCP integration for live Jira/Confluence automation."
version: 2.9.0
author: Alireza Rezvani
license: MIT
tags:
  - project-management
  - jira
  - confluence
  - atlassian
  - scrum
  - agile
agents:
  - claude-code
  - codex-cli
  - openclaw
---

# Project Management Skills

6 production-ready project management skills with Atlassian MCP integration.

## Quick Start

### Claude Code
```
/read project-management/jira-expert/SKILL.md
```

### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/project-management
```

## Skills Overview

| Skill | Folder | Focus |
|-------|--------|-------|
| Senior PM | `senior-pm/` | Portfolio management, risk analysis, resource planning |
| Scrum Master | `scrum-master/` | Velocity forecasting, sprint health, retrospectives |
| Jira Expert | `jira-expert/` | JQL queries, workflows, automation, dashboards |
| Confluence Expert | `confluence-expert/` | Knowledge bases, page layouts, macros |
| Atlassian Admin | `atlassian-admin/` | User management, permissions, integrations |
| Atlassian Templates | `atlassian-templates/` | Blueprints, custom layouts, reusable content |

## Python Tools

6 scripts, all stdlib-only:

```bash
python3 senior-pm/scripts/project_health_dashboard.py --help
python3 scrum-master/scripts/velocity_analyzer.py --help
```

## Rules

- Load only the specific skill SKILL.md you need
- Use MCP tools for live Jira/Confluence operations when available

---
name: "product-skills"
description: "10 product agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. PM toolkit (RICE), agile PO, product strategist (OKR), UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, research summarizer. Python tools (stdlib-only)."
version: 2.9.0
author: Alireza Rezvani
license: MIT
tags:
  - product
  - product-management
  - ux
  - ui
  - saas
  - agile
agents:
  - claude-code
  - codex-cli
  - openclaw
---

# Product Team Skills

8 production-ready product skills covering product management, UX/UI design, and SaaS development.

## Quick Start

### Claude Code
```
/read product-team/product-manager-toolkit/SKILL.md
```

### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/product-team
```

## Skills Overview

| Skill | Folder | Focus |
|-------|--------|-------|
| Product Manager Toolkit | `product-manager-toolkit/` | RICE prioritization, customer discovery, PRDs |
| Agile Product Owner | `agile-product-owner/` | User stories, sprint planning, backlog |
| Product Strategist | `product-strategist/` | OKR cascades, market analysis, vision |
| UX Researcher Designer | `ux-researcher-designer/` | Personas, journey maps, usability testing |
| UI Design System | `ui-design-system/` | Design tokens, component docs, responsive |
| Competitive Teardown | `competitive-teardown/` | Systematic competitor analysis |
| Landing Page Generator | `landing-page-generator/` | Conversion-optimized pages |
| SaaS Scaffolder | `saas-scaffolder/` | Production SaaS boilerplate |

## Python Tools

9 scripts, all stdlib-only:

```bash
python3 product-manager-toolkit/scripts/rice_prioritizer.py --help
python3 product-strategist/scripts/okr_cascade_generator.py --help
```

## Rules

- Load only the specific skill SKILL.md you need
- Use Python tools for scoring and analysis, not manual judgment

---
name: "ra-qm-skills"
description: "12 regulatory & QM agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. ISO 13485 QMS, MDR 2017/745, FDA 510(k)/PMA, ISO 27001 ISMS, GDPR/DSGVO, risk management (ISO 14971), CAPA, document control, auditing. Python tools (stdlib-only)."
version: 2.9.0
author: Alireza Rezvani
license: MIT
tags:
  - regulatory
  - quality-management
  - iso-13485
  - mdr
  - fda
  - iso-27001
  - gdpr
agents:
  - claude-code
  - codex-cli
  - openclaw
---

# Regulatory Affairs & Quality Management Skills

12 production-ready compliance skills for HealthTech and MedTech organizations.

## Quick Start

### Claude Code
```
/read ra-qm-team/regulatory-affairs-head/SKILL.md
```

### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/ra-qm-team
```

## Skills Overview

| Skill | Folder | Focus |
|-------|--------|-------|
| Regulatory Affairs Head | `regulatory-affairs-head/` | FDA/MDR strategy, submissions |
| Quality Manager (QMR) | `quality-manager-qmr/` | QMS governance, management review |
| Quality Manager (ISO 13485) | `quality-manager-qms-iso13485/` | QMS implementation, doc control |
| Risk Management Specialist | `risk-management-specialist/` | ISO 14971, FMEA, risk files |
| CAPA Officer | `capa-officer/` | Root cause analysis, corrective actions |
| Quality Documentation Manager | `quality-documentation-manager/` | Document control, 21 CFR Part 11 |
| QMS Audit Expert | `qms-audit-expert/` | ISO 13485 internal audits |
| ISMS Audit Expert | `isms-audit-expert/` | ISO 27001 security audits |
| Information Security Manager | `information-security-manager-iso27001/` | ISMS implementation |
| MDR 745 Specialist | `mdr-745-specialist/` | EU MDR classification, CE marking |
| FDA Consultant | `fda-consultant-specialist/` | 510(k), PMA, QSR compliance |
| GDPR/DSGVO Expert | `gdpr-dsgvo-expert/` | Privacy compliance, DPIA |

## Python Tools

17 scripts, all stdlib-only:

```bash
python3 risk-management-specialist/scripts/risk_matrix_calculator.py --help
python3 gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py --help
```

## Rules

- Load only the specific skill SKILL.md you need
- Always verify compliance outputs against current regulations

---
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

FILE:references/scenario-planning.md
# 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

FILE:scripts/scenario_modeler.py
#!/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".1fM"
    elif amount >= 1_000:
        return f".0fK"
    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()

---
name: caveman
description: >
  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
  filler, articles, and pleasantries while keeping full technical accuracy.
  Use when user says "caveman mode", "talk like caveman", "use caveman",
  "less tokens", "be brief", or invokes /caveman.
license: MIT
metadata:
  derived_from: "https://github.com/mattpocock/skills/tree/main/skills/productivity/caveman"
  original_author: "Matt Pocock (@mattpocock)"
  original_license: MIT
  voice: "Matt Pocock — terse, fragment-OK, no filler"
  version: 1.0.0
---

# Caveman Mode

> Derived from [Matt Pocock's caveman](https://github.com/mattpocock/skills/tree/main/skills/productivity/caveman) (MIT). Matt's voice preserved verbatim. Additions: compression tools + references + cs-* wrapper (see [references/companion_tooling.md](references/companion_tooling.md)).

Respond terse like smart caveman. All technical substance stay. Only fluff die.

## Persistence

ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".

## Rules

Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.

Technical terms stay exact. Code blocks unchanged. Errors quoted exact.

Pattern: `[thing] [action] [reason]. [next step].`

Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"

### Examples

**"Why React component re-render?"**

> Inline obj prop -> new ref -> re-render. `useMemo`.

**"Explain database connection pooling."**

> Pool = reuse DB conn. Skip handshake -> fast under load.

## Auto-Clarity Exception

Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.

Example -- destructive op:

> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
>
> ```sql
> DROP TABLE users;
> ```
>
> Caveman resume. Verify backup exist first.

## Tooling

See [references/companion_tooling.md](references/companion_tooling.md). Tools: compressor + estimator + lint. Agent: `cs-caveman-mode`. Command: `/cs:caveman`.

---

**Version:** 1.0.0
**Derived:** Matt Pocock (MIT) + this repo's wrapper

FILE:references/companion_tooling.md
# Companion Tooling

Compression tools + cs-* wrapper layered on top of Matt's caveman skill.

## Validation Tools (stdlib Python)

| Tool | Purpose | Run when |
|---|---|---|
| `scripts/caveman_compressor.py` | Apply Matt's rules deterministically (drop articles/filler/pleasantries/hedging, abbreviate technical terms, use causality arrows) | Want a starting compressed version of any text |
| `scripts/token_savings_estimator.py` | Estimate token + cost savings using 4 chars/token (prose) or 3.5 chars/token (technical) heuristic | Want to quantify the value of caveman mode |
| `scripts/caveman_lint.py` | Detect banned vocabulary in a response (pleasantries, filler, hedging, metatalk, verbose phrases). Whitelist: code blocks, inline code, exception zones | Verify a response complies with caveman rules |

All three tools:
- Stdlib-only (no external dependencies)
- Run with embedded sample if no input provided
- Output text or JSON (`--output json`)
- Code blocks + inline code preserved (compression skips them)

## Token-Savings Heuristic

The estimator uses character-per-token approximations:
- **4.0 chars/token** for English prose
- **3.5 chars/token** for technical text (detected by presence of `{`, `}`, `()`, `->`, `==`, `//`, etc.)

This is within 10-15% of cl100k_base / o200k_base tokenizers for English. For exact token counts use the model's actual tokenizer (e.g., `tiktoken`).

## cs-caveman-mode Persona Agent

Lives at `../agents/cs-caveman-mode.md`. Voice: terse, fragments-OK, no filler. Persistence is the hard rule — once activated stays active until "stop caveman" / "normal mode".

## `/cs:caveman` Slash Command

Lives at `../commands/cs-caveman.md`. Single-trigger activation. Equivalent to typing "caveman mode" but more explicit.

## When Caveman Backfires (See main SKILL.md "Auto-Clarity Exception")

The compressor + lint tool both whitelist these zones — Matt's rule is explicit:
- Security warnings
- Irreversible action confirmations
- Multi-step sequences where fragment order risks misread
- User asks to clarify or repeats question

The lint tool detects `**Warning:**`, `destructive`, `irreversible`, `cannot be undone` markers and softens its verdict accordingly.

## Why Wrap Matt's Original

Matt's caveman skill is tight + complete. The wrapper adds:
1. **Deterministic compression** — apply rules consistently across responses (not just in spirit)
2. **Quantification** — show ROI of caveman mode in tokens/dollars
3. **Compliance checking** — verify a response actually follows rules (vs claiming to)

## Attribution

Original: [matt-pocock/skills/skills/productivity/caveman](https://github.com/mattpocock/skills/tree/main/skills/productivity/caveman) (MIT).

---

**Source authorities (non-exhaustive):**

- **Matt Pocock — caveman** (https://github.com/mattpocock/skills/, MIT) — the upstream source
- **Anthropic — Token usage best practices** (https://docs.claude.com/en/docs/build-with-claude/prompt-engineering) — token-conscious prompting
- **OpenAI tokenizer docs** — `tiktoken` library + cl100k_base / o200k_base heuristics
- **Strunk & White — "The Elements of Style"** (1918) — "omit needless words"; foundational text on prose compression
- **Plain Language Movement / Plain Writing Act of 2010** — federal mandate for concise government writing
- **Norman, D. — "Living with Complexity"** (2010) — when simplicity helps vs hurts cognition
- **Pareto principle in communication** — 20% of words carry 80% of information density

FILE:references/compression_principles.md
# Compression Principles for LLM Output

This reference answers exactly one decision: **what should be cut and what must stay when compressing LLM output for token efficiency?**

Pair with `scripts/caveman_compressor.py` for deterministic application.

## Matt Pocock's Foundational Insight

> "Respond terse like smart caveman. All technical substance stay. Only fluff die."
>
> — Matt Pocock, caveman SKILL.md

The crucial distinction: **substance** vs **fluff**. Caveman mode is aggressive about fluff and conservative about substance. Confusion between the two creates either bloated responses (under-cutting) or hallucinated answers (over-cutting).

## What Counts as Fluff (Safe to Drop)

| Category | Examples | Why safe to drop |
|---|---|---|
| **Articles** | a, an, the | Grammatical scaffolding; meaning preserved without them |
| **Filler** | just, really, basically, actually, simply, obviously | Add no information; speakers use as verbal pauses |
| **Pleasantries** | sure!, certainly, of course, happy to help | Social lubrication; cost tokens with zero info gain |
| **Hedging** | might, maybe, perhaps, likely, possibly | Either qualify with data or remove; vague hedging is fake precision |
| **Metatalk** | as you can see, worth noting, that said | Self-referential commentary about the response itself |
| **Verbose phrases** | "implementation of a solution for" → "fix"; "in order to" → "to" | Phrase-level redundancy |

## What Counts as Substance (Must Stay)

| Category | Examples | Why preserve |
|---|---|---|
| **Technical terms** | `useMemo`, NULL, HTTP/2, OAuth2 | Exact names matter; abbreviation breaks identifiers |
| **Code blocks** | All ```...``` regions | Syntactically meaningful; whitespace + characters matter |
| **Inline code** | `useState`, `auth_token` | Same as code blocks |
| **Quoted strings** | "expected value", 'string literal' | Exact text matters |
| **Error messages** | "TypeError: cannot read property X" | Diagnostic precision required |
| **Numbers + units** | 200ms, 4kb, 99.9% | Exactness matters for engineering decisions |
| **Causal claims** | "X causes Y" — can be compressed to "X -> Y" | The relationship is the substance |

## The Abbreviation Cost-Benefit

Abbreviating common technical terms saves tokens but only when:
1. The abbreviation is universally understood (DB, auth, config, fn — yes; ETL, ORM — maybe; "imp" for implementation — no)
2. The reader has full context (caveman responses are usually mid-conversation)
3. The exact term isn't being introduced (don't abbreviate the FIRST use of a term)

Matt's abbreviation list is conservative + universal:
- DB, auth, config, req, res, fn, impl, env, deps, repo, docs, app

## Causality Arrows: The Compression Win

Replacing verbose causality with arrows is high-leverage:

| Verbose | Caveman | Savings |
|---|---|---|
| "X leads to Y" (3 words) | "X -> Y" (1 unit) | 67% |
| "which causes Y to happen" (5 words) | "-> Y" (2 units) | 60% |
| "because of X, Y happens" (5 words) | "Y <- X" (2 units) | 60% |

Arrows are unambiguous + compact + preserve causality (not just adjacency).

## Compression Anti-Patterns

1. **Dropping subject pronouns at all costs** — "Bug in auth" is fine. "Auth bug, fix soon" loses clarity. Keep enough syntax to disambiguate.
2. **Over-abbreviating** — "MWMV" instead of "memory write/memory verify" forces reader to expand mentally; net cognitive cost goes up.
3. **Dropping units** — "Response takes 200" — 200 what? ms? bytes? Keep units always.
4. **Compressing security warnings** — Matt's explicit exception. A truncated security warning is worse than no caveman mode.
5. **Dropping examples** — "Bug in auth. Fix." — what bug? what fix? Caveman keeps the substance, just removes the wrapping.

## Compression vs Clarity Tradeoff

Compression is a tax on the reader. The trade-off is worth it when:
- The reader has the context to fill in the gaps (mid-conversation, technical peer)
- The information density is high enough to justify cognitive load
- The savings are meaningful (>20% token reduction)

Not worth it when:
- New context being established (introductions, first turns)
- Multi-step sequences where order matters
- Multi-stakeholder communication (caveman style confuses non-technical readers)
- Audio interfaces (caveman text reads badly when read aloud)

## How Much Compression Is Realistic?

Matt's claim is ~75% — this is the upper bound on extremely verbose responses (with multiple pleasantries + filler + hedging). Realistic ranges:

| Response type | Realistic compression |
|---|---|
| ChatGPT-style verbose response | 50-75% |
| Already-concise technical answer | 10-25% |
| Code-heavy response (most text is code) | 5-15% |
| Single-sentence answer | 0-30% |

The compressor in this skill targets 20-50% on typical mid-conversation responses, which is meaningful at scale.

## When This Reference Doesn't Help

- **Code minification** — different concern; this is about prose around code, not code itself
- **Prompt compression for inputs** — different mode; input compression has different rules
- **Speech synthesis** — caveman text reads poorly aloud
- **Marketing copy** — different goal; conversion > brevity

---

**Source authorities (non-exhaustive):**

- **Matt Pocock — caveman** (https://github.com/mattpocock/skills/, MIT) — the upstream source + rule set
- **Strunk & White — "The Elements of Style"** (1918) — Rule 17: "Omit needless words"
- **Plain Language Movement / Plain Writing Act of 2010** (https://www.plainlanguage.gov/) — government mandate for concise English; well-researched compression rules
- **Pinker, S. — "The Sense of Style"** (2014) — cognitive science of clear writing
- **Williams, J. — "Style: Toward Clarity and Grace"** (1995) — academic compression patterns
- **Anthropic — Prompt engineering for tokens** (https://docs.claude.com/en/docs/build-with-claude/prompt-engineering) — token-conscious patterns
- **OpenAI tokenizer documentation** — character-per-token ratios across cl100k_base / o200k_base
- **Pareto principle in writing** — 20% of words carry 80% of meaning

FILE:references/when_caveman_backfires.md
# When Caveman Backfires

This reference answers exactly one decision: **when should caveman mode NOT be used, and what are the failure modes?**

Pair with `scripts/caveman_lint.py` — the linter detects exception-zone markers and softens its verdict accordingly.

## Matt Pocock's Auto-Clarity Exception (Verbatim)

> "Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done."
>
> — Matt Pocock, caveman SKILL.md

This is the **non-negotiable** exception list. Compressing in these zones can cause user harm — not just token cost confusion.

## The Five Failure Modes

### 1. Compressed Security Warnings

**Failure:** `Warning: drop users table. Cannot undo.`
**Why bad:** Two compound failures:
1. Reader skims caveman text; warning blends into surrounding terse responses
2. Critical verb ("drop", "cannot undo") loses emphasis without sentence structure

**Correct:** Drop caveman entirely for warnings:

> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.

The full sentence + bold marker + explicit consequences make it unmissable.

### 2. Compressed Multi-Step Sequences

**Failure:** `npm install. npm test. npm build. deploy.`
**Why bad:** Fragment order = execution order. If reader misreads order, deploy can run before tests pass.

**Correct:** Number steps + use full sentences when order matters:

> 1. Install dependencies: `npm install`
> 2. Run tests: `npm test` — must pass before continuing
> 3. Build: `npm build`
> 4. Deploy: only after step 3 succeeds

### 3. Compressed Clarification Responses

**Failure:** User asks "Wait, what?" → Response: `Token expiry. Less-than. Fix.`
**Why bad:** User asked for clarification because original was unclear. Compressing further compounds the problem.

**Correct:** Drop caveman temporarily, explain fully, then resume:

> The original issue: the token expiry check uses `<` (strict less-than) instead of `<=` (less-than-or-equal). This means tokens at the exact expiry timestamp are rejected even though they should still be valid. The fix changes the operator from `<` to `<=`.
>
> [Resume caveman.]

### 4. Compressed Irreversible Action Confirmations

**Failure:** `rm -rf node_modules. Confirm.`
**Why bad:** "Confirm" loses weight without context. User may type "yes" reflexively.

**Correct:** Drop caveman, state explicitly:

> About to run `rm -rf node_modules` which permanently deletes the directory.
>
> Reply with the exact string "DELETE" to proceed, or "cancel" to abort.

The exact-string requirement breaks reflex confirmation.

### 5. Compressed First-Turn Responses

**Failure:** User's first message → Response in caveman.
**Why bad:** No shared context yet. Reader can't fill in caveman's gaps.

**Correct:** First turn establishes context fully. Activate caveman ONLY after user explicitly triggers it (per Matt's activation triggers: "caveman mode", "talk like caveman", `/caveman`, etc.).

## Less-Obvious Backfire Cases

### Caveman in Code Review

Caveman compression on code-review feedback can lose nuance:

**Failure:** `Bug L42. Var name bad. Refactor.`
**Why bad:** Three findings, no specificity. Engineer can't tell what to fix.

**Better:** `L42: var name "x" → "userIndex". L67: off-by-one in loop bound.`

The fix: caveman compresses sentence STRUCTURE, not technical SPECIFICITY.

### Caveman in Estimates / Forecasts

Hedging is fluff per Matt's rules. But hedging carries information in estimates:

**Failure:** `Done by Friday.` (when uncertain)
**Why bad:** Reads as commitment, but actual confidence was 60%.

**Correct:** Caveman exception for probability claims. State confidence explicitly:

> Friday delivery — 60% confidence. Risks: API spec churn.

### Caveman in Multi-Stakeholder Threads

Caveman is for technical peer-to-peer (or peer-to-self) communication. When non-technical stakeholders are reading:

**Failure:** `Auth bug. Fix shipping.`
**Why bad:** PM/CEO/non-engineer reader can't decode "Fix shipping" — is shipping affected?

**Correct:** Drop caveman in stakeholder communication. Save it for technical conversations.

## Detection Patterns (How `caveman_lint.py` Helps)

The lint tool detects these markers as exception-zone signals:

- `**Warning:**` markdown bold + word
- `destructive`
- `irreversible`
- `cannot be undone`

When present, the linter softens FAIL → WARN. This isn't perfect — manual review still required for stakeholder mismatches + first-turn responses.

## Resuming Caveman After Exception

Matt's rule: "Resume caveman after clear part done."

Pattern:

> **Warning:** [full sentence warning].
>
> [empty line]
>
> Caveman resume. [terse fragment continues].

The explicit "Caveman resume." marker signals the reader that compression resumes. This is critical when the response is long enough that the reader might lose track of which mode they're in.

## Tooling Recommendation

When in doubt:
1. Run `caveman_lint.py` on the proposed response
2. If FAIL → consider rewriting (banned vocab present)
3. If WARN with exception context → check whether the exception is genuine
4. If CLEAN → ship

## When This Reference Doesn't Help

- **Brevity in writing generally** — different concern; see editing references
- **Code minification** — different mode; this is about prose around code
- **API response compression** — gzip/brotli, not prose compression

---

**Source authorities (non-exhaustive):**

- **Matt Pocock — caveman** (https://github.com/mattpocock/skills/, MIT) — the auto-clarity exception list
- **Nielsen Norman Group — Error message design** — when verbosity in errors helps vs hurts
- **FAA Human Factors research on cockpit warnings** — emphasis + redundancy in safety-critical communications
- **Krug, S. — "Don't Make Me Think"** (2000) — when brevity becomes ambiguity
- **Schneier, B. — Communication on security warnings** — why brevity in security messages is dangerous
- **Larson, W. — "An Elegant Puzzle"** (2019) — engineering manager communication patterns
- **Rommetveit, R. — Linguistic shared context** — when compression depends on shared frame

FILE:scripts/caveman_compressor.py
#!/usr/bin/env python3
"""caveman_compressor.py — Apply Matt Pocock's caveman compression rules to text.

Stdlib-only. Deterministic regex-based compression matching the rules in
Matt Pocock's caveman skill SKILL.md:

  1. Drop articles (a/an/the)
  2. Drop filler (just/really/basically/actually/simply)
  3. Drop pleasantries (sure/certainly/of course/happy to)
  4. Drop hedging (might/maybe/perhaps/likely/possibly)
  5. Abbreviate common technical terms (database -> DB, configuration -> config, etc.)
  6. Strip conjunctions where safe (and/but at sentence start)
  7. Use arrows for "leads to" / "causes" phrases (-> )
  8. Strip "as you can see / it should be noted / it's worth mentioning"

PRESERVES:
- Code blocks (```...```) unchanged
- Inline code (`...`) unchanged
- Technical terms named verbatim
- Quoted strings unchanged

NO LLM CALLS. Stdlib only.

Usage:
    python caveman_compressor.py                          # uses embedded sample
    python caveman_compressor.py "your text here"
    python caveman_compressor.py --file path/to/input.txt
    python caveman_compressor.py "text" --output json
"""

import argparse
import json
import re
import sys
from typing import Any, Dict, List, Tuple


# Filler/pleasantry/hedging vocabularies (per Matt's rules)
ARTICLES = {"a", "an", "the"}
FILLER = {"just", "really", "basically", "actually", "simply", "obviously", "literally"}
PLEASANTRIES_PHRASES = [
    "sure!", "sure,", "certainly!", "certainly,",
    "of course!", "of course,",
    "happy to help", "i'd be happy to", "i would be happy to",
    "great question", "good question",
    "absolutely!", "absolutely,",
    "no problem!", "no problem,",
]
HEDGING = {"might", "maybe", "perhaps", "likely", "possibly", "probably"}
METATALK_PHRASES = [
    "as you can see",
    "it should be noted",
    "it's worth mentioning",
    "it is worth mentioning",
    "needless to say",
    "to be clear",
    "in other words",
    "that said",
    "having said that",
]

# Technical term abbreviations
ABBREVIATIONS = [
    (r"\bdatabase\b", "DB"),
    (r"\bdatabases\b", "DBs"),
    (r"\bauthentication\b", "auth"),
    (r"\bauthorization\b", "authz"),
    (r"\bconfiguration\b", "config"),
    (r"\bconfigurations\b", "configs"),
    (r"\brequest\b", "req"),
    (r"\brequests\b", "reqs"),
    (r"\bresponse\b", "res"),
    (r"\bresponses\b", "ress"),
    (r"\bfunction\b", "fn"),
    (r"\bfunctions\b", "fns"),
    (r"\bimplementation\b", "impl"),
    (r"\bimplementations\b", "impls"),
    (r"\benvironment\b", "env"),
    (r"\bdependencies\b", "deps"),
    (r"\bdependency\b", "dep"),
    (r"\brepository\b", "repo"),
    (r"\brepositories\b", "repos"),
    (r"\bdocumentation\b", "docs"),
    (r"\bapplication\b", "app"),
    (r"\bapplications\b", "apps"),
]

# Causality phrase -> arrow
CAUSALITY_PATTERNS = [
    (re.compile(r"\b(which\s+)?(leads?|causes?|results?\s+in|gives?\s+you|produces?)\s+", re.IGNORECASE), "-> "),
    (re.compile(r"\bbecause\s+of\b", re.IGNORECASE), "<- "),
]

# Embedded sample
SAMPLE_INPUT = (
    "Sure! I'd be happy to help you with that. The issue you're experiencing is "
    "likely caused by a misconfiguration in the authentication middleware, where "
    "the token expiry check is actually using a strict less-than comparison "
    "instead of less-than-or-equal. This basically means tokens at the exact "
    "expiry timestamp will get rejected. To fix this, you should simply update "
    "the configuration of the auth function to use `<=` instead of `<`."
)


def _protect_code(text: str) -> Tuple[str, List[str]]:
    """Replace code blocks + inline code with placeholders, return text + protected list."""
    protected: List[str] = []

    def replace_block(m: re.Match) -> str:
        protected.append(m.group(0))
        return f"\x00CODE{len(protected) - 1}\x00"

    text = re.sub(r"```.*?```", replace_block, text, flags=re.DOTALL)
    text = re.sub(r"`[^`]+`", replace_block, text)
    return text, protected


def _restore_code(text: str, protected: List[str]) -> str:
    for i, code in enumerate(protected):
        text = text.replace(f"\x00CODE{i}\x00", code)
    return text


def _drop_articles(text: str) -> str:
    pattern = re.compile(r"\b(" + "|".join(ARTICLES) + r")\s+", re.IGNORECASE)
    return pattern.sub("", text)


def _drop_word_set(text: str, words: set) -> str:
    pattern = re.compile(r"\b(" + "|".join(words) + r")\b\s*", re.IGNORECASE)
    return pattern.sub("", text)


def _drop_phrases(text: str, phrases: List[str]) -> str:
    for phrase in phrases:
        text = re.sub(re.escape(phrase) + r"\s*", "", text, flags=re.IGNORECASE)
        text = re.sub(re.escape(phrase.rstrip(",!")) + r"\s*", "", text, flags=re.IGNORECASE)
    return text


def _apply_abbreviations(text: str) -> str:
    for pattern, replacement in ABBREVIATIONS:
        text = re.sub(pattern, replacement, text, flags=re.IGNORECASE)
    return text


def _apply_causality_arrows(text: str) -> str:
    for pattern, replacement in CAUSALITY_PATTERNS:
        text = pattern.sub(replacement, text)
    return text


def _strip_leading_conjunctions(text: str) -> str:
    return re.sub(r"(^|\.\s+)(and|but|so)\s+", r"\1", text, flags=re.IGNORECASE)


def _collapse_whitespace(text: str) -> str:
    text = re.sub(r"\s+", " ", text)
    text = re.sub(r"\s+([.,;:!?])", r"\1", text)
    return text.strip()


def compress(text: str) -> str:
    """Apply Matt Pocock's caveman rules. Returns compressed text."""
    text, protected = _protect_code(text)
    text = _drop_phrases(text, PLEASANTRIES_PHRASES)
    text = _drop_phrases(text, METATALK_PHRASES)
    text = _drop_word_set(text, FILLER)
    text = _drop_word_set(text, HEDGING)
    text = _drop_articles(text)
    text = _apply_abbreviations(text)
    text = _apply_causality_arrows(text)
    text = _strip_leading_conjunctions(text)
    text = _collapse_whitespace(text)
    text = _restore_code(text, protected)
    return text


def analyze(original: str, compressed: str) -> Dict[str, Any]:
    orig_words = len(original.split())
    new_words = len(compressed.split())
    saved = orig_words - new_words
    pct = round(100.0 * saved / max(orig_words, 1), 1)
    return {
        "original_chars": len(original),
        "compressed_chars": len(compressed),
        "original_words": orig_words,
        "compressed_words": new_words,
        "words_saved": saved,
        "percent_savings": pct,
        "compressed_text": compressed,
    }


def render_text(original: str, result: Dict[str, Any]) -> str:
    lines = []
    lines.append("=" * 72)
    lines.append("CAVEMAN COMPRESSOR")
    lines.append("=" * 72)
    lines.append("")
    lines.append("ORIGINAL:")
    lines.append(f"  {original}")
    lines.append("")
    lines.append("COMPRESSED:")
    lines.append(f"  {result['compressed_text']}")
    lines.append("")
    lines.append("-" * 72)
    lines.append(f"Chars: {result['original_chars']} -> {result['compressed_chars']}")
    lines.append(f"Words: {result['original_words']} -> {result['compressed_words']}")
    lines.append(f"Savings: {result['words_saved']} words ({result['percent_savings']}%)")
    return "\n".join(lines)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Compress text per Matt Pocock's caveman rules.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("text", nargs="?", help="Input text (uses embedded sample if omitted)")
    parser.add_argument("--file", help="Read input from file")
    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
    args = parser.parse_args()

    if args.file:
        try:
            with open(args.file, "r", encoding="utf-8") as f:
                original = f.read()
        except (IOError, OSError) as e:
            print(f"error: {e}", file=sys.stderr)
            return 1
    elif args.text:
        original = args.text
    else:
        original = SAMPLE_INPUT

    compressed = compress(original)
    result = analyze(original, compressed)

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(render_text(original, result))
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/caveman_lint.py
#!/usr/bin/env python3
"""caveman_lint.py — Lint a response for caveman-mode compliance.

Stdlib-only. Detects banned vocabulary in a response that's supposed to be in
caveman mode. Returns specific findings + verdict.

Banned categories per Matt Pocock's caveman rules:
  - Pleasantries (sure, certainly, of course, happy to)
  - Filler (just, really, basically, actually, simply)
  - Hedging (might, maybe, perhaps, likely)
  - Metatalk (as you can see, worth noting)
  - Verbose phrases ("the implementation of a solution for")

Whitelist (NOT banned even in caveman mode):
  - Words inside code blocks
  - Words inside inline code
  - Words inside quoted strings
  - Caveman exception zones (security warnings, destructive op confirmations)

Usage:
    python caveman_lint.py                          # uses embedded samples
    python caveman_lint.py "response text"
    python caveman_lint.py --file path/to/response.txt
    python caveman_lint.py "text" --output json
"""

import argparse
import json
import re
import sys
from typing import Any, Dict, List


BANNED_PHRASES = {
    "pleasantry": [
        "sure!", "sure,", "certainly", "of course", "happy to help",
        "i'd be happy", "i would be happy", "great question", "good question",
        "absolutely", "no problem!",
    ],
    "filler": ["just", "really", "basically", "actually", "simply", "obviously", "literally"],
    "hedging": ["might", "maybe", "perhaps", "likely", "possibly", "probably"],
    "metatalk": [
        "as you can see", "it should be noted", "worth mentioning",
        "needless to say", "to be clear", "in other words",
        "that said", "having said that",
    ],
    "verbose": [
        "implement a solution for", "the implementation of",
        "in order to", "for the purpose of", "with respect to",
        "due to the fact that",
    ],
}

# Patterns that DROP caveman temporarily (whitelisted zones)
EXCEPTION_MARKERS = [
    re.compile(r"\*\*warning:\*\*", re.IGNORECASE),
    re.compile(r"\bdestructive\b", re.IGNORECASE),
    re.compile(r"\birreversible\b", re.IGNORECASE),
    re.compile(r"\bcannot be undone\b", re.IGNORECASE),
]


SAMPLE_BAD = (
    "Sure! I'd be happy to help. The issue is actually quite simple — basically, "
    "you just need to update the configuration. It's worth mentioning that this might "
    "cause a slight performance hit, but probably not noticeable."
)
SAMPLE_GOOD = "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix: change to `<=`."


def _protect_code(text: str) -> str:
    """Mask code blocks + inline code so banned-word matching skips them."""
    text = re.sub(r"```.*?```", lambda m: "\x00" * len(m.group(0)), text, flags=re.DOTALL)
    text = re.sub(r"`[^`]+`", lambda m: "\x00" * len(m.group(0)), text)
    return text


def _has_exception_context(text: str) -> bool:
    return any(p.search(text) for p in EXCEPTION_MARKERS)


def _count_phrase(phrase: str, masked: str) -> int:
    return len(re.findall(r"\b" + re.escape(phrase) + r"\b", masked, re.IGNORECASE))


def _violation_record(category: str, phrase: str, count: int) -> Dict[str, Any]:
    return {"category": category, "phrase": phrase, "count": count}


def find_violations(text: str) -> List[Dict[str, Any]]:
    """Find banned phrases. Returns list of {category, phrase, count}."""
    masked = _protect_code(text)
    violations: List[Dict[str, Any]] = []
    for category, phrases in BANNED_PHRASES.items():
        for phrase in phrases:
            count = _count_phrase(phrase, masked)
            if count > 0:
                violations.append(_violation_record(category, phrase, count))
    return violations


def analyze(text: str) -> Dict[str, Any]:
    violations = find_violations(text)
    total_violations = sum(v["count"] for v in violations)
    has_exception = _has_exception_context(text)

    # Verdict logic:
    #   0 violations + reasonable length     -> CLEAN
    #   <= 2 violations OR exception context -> WARN
    #   >  2 violations                      -> FAIL
    if total_violations == 0:
        verdict = "CLEAN"
    elif has_exception:
        verdict = "WARN"
        # When there's a security warning, some normal language is allowed
    elif total_violations <= 2:
        verdict = "WARN"
    else:
        verdict = "FAIL"

    return {
        "char_count": len(text),
        "word_count": len(text.split()),
        "violation_categories": sorted(set(v["category"] for v in violations)),
        "total_violations": total_violations,
        "has_exception_context": has_exception,
        "violations": violations,
        "verdict": verdict,
    }


def render_text(text: str, r: Dict[str, Any]) -> str:
    lines = []
    lines.append("=" * 72)
    lines.append("CAVEMAN LINT")
    lines.append("=" * 72)
    lines.append("")
    preview = text[:200] + ("..." if len(text) > 200 else "")
    lines.append(f"Text ({r['char_count']} chars, {r['word_count']} words):")
    lines.append(f"  {preview}")
    lines.append("")
    lines.append("-" * 72)
    lines.append(f"Violations: {r['total_violations']}")
    lines.append(f"Categories hit: {r['violation_categories']}")
    if r["has_exception_context"]:
        lines.append("Exception context detected (warning/destructive zone — some prose allowed)")
    lines.append("")
    if r["violations"]:
        for v in r["violations"]:
            lines.append(f"  [{v['category']:11s}] x{v['count']:2d}  '{v['phrase']}'")
    else:
        lines.append("  No banned phrases found.")
    lines.append("")
    lines.append("-" * 72)
    lines.append(f"Verdict: {r['verdict']}")
    return "\n".join(lines)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Lint a response for caveman-mode compliance.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("text", nargs="?", help="Input text (uses embedded sample if omitted)")
    parser.add_argument("--file", help="Read input from file")
    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
    args = parser.parse_args()

    if args.file:
        try:
            with open(args.file, "r", encoding="utf-8") as f:
                text = f.read()
        except (IOError, OSError) as e:
            print(f"error: {e}", file=sys.stderr)
            return 1
    elif args.text:
        text = args.text
    else:
        text = SAMPLE_BAD

    result = analyze(text)
    if args.output == "json":
        print(json.dumps({"text": text, **result}, indent=2))
    else:
        print(render_text(text, result))
    return 0 if result["verdict"] == "CLEAN" else 1


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/token_savings_estimator.py
#!/usr/bin/env python3
"""token_savings_estimator.py — Estimate token-cost savings from caveman compression.

Stdlib-only. Uses a chars-per-token heuristic (4 chars/token average for English
prose; 3.5 for technical text) to estimate output tokens before vs after caveman
compression.

Why heuristic and not real tokenizer:
- No external dependencies (stdlib only)
- Tokenizer accuracy varies by model (cl100k_base vs o200k_base vs others)
- Heuristic is within 10-15% of real tokenizer output for English prose
- Reports both heuristic + character count so user can apply their own multiplier

Usage:
    python token_savings_estimator.py                         # uses embedded sample
    python token_savings_estimator.py "your text"
    python token_savings_estimator.py --file path/to/input.txt
    python token_savings_estimator.py "text" --output json
    python token_savings_estimator.py "text" --price-per-mtok 3.00
"""

import argparse
import json
import sys
from typing import Any, Dict

# Import the compressor as a module
import os
_HERE = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, _HERE)
from caveman_compressor import compress, SAMPLE_INPUT  # noqa: E402


# Heuristic: average chars per token
CHARS_PER_TOKEN_PROSE = 4.0
CHARS_PER_TOKEN_TECHNICAL = 3.5
TECHNICAL_TOKEN_INDICATORS = ("```", "{", "}", "()", "->", "==", "//", "/*", "import ", "function ")


def _estimate_chars_per_token(text: str) -> float:
    """Heuristic: technical text has more tokens per char than prose."""
    hit_count = sum(1 for sig in TECHNICAL_TOKEN_INDICATORS if sig in text)
    if hit_count >= 3:
        return CHARS_PER_TOKEN_TECHNICAL
    return CHARS_PER_TOKEN_PROSE


def estimate_tokens(text: str) -> int:
    return int(round(len(text) / _estimate_chars_per_token(text)))


def analyze(original: str, price_per_mtok: float = 0.0) -> Dict[str, Any]:
    compressed = compress(original)
    orig_tokens = estimate_tokens(original)
    new_tokens = estimate_tokens(compressed)
    saved = orig_tokens - new_tokens
    pct = round(100.0 * saved / max(orig_tokens, 1), 1)

    out: Dict[str, Any] = {
        "original_chars": len(original),
        "compressed_chars": len(compressed),
        "chars_per_token_used": _estimate_chars_per_token(original),
        "estimated_original_tokens": orig_tokens,
        "estimated_compressed_tokens": new_tokens,
        "tokens_saved": saved,
        "percent_token_savings": pct,
        "compressed_preview": compressed[:200] + ("..." if len(compressed) > 200 else ""),
    }

    if price_per_mtok > 0:
        cost_per_token = price_per_mtok / 1_000_000.0
        out["price_per_million_tokens"] = price_per_mtok
        out["cost_saved_per_response_usd"] = round(saved * cost_per_token, 6)
        out["cost_saved_per_1k_responses_usd"] = round(saved * cost_per_token * 1000, 4)

    return out


def render_text(r: Dict[str, Any]) -> str:
    lines = []
    lines.append("=" * 72)
    lines.append("TOKEN SAVINGS ESTIMATOR (caveman compression)")
    lines.append("=" * 72)
    lines.append("")
    lines.append(f"Chars/token heuristic: {r['chars_per_token_used']:.1f} (prose=4.0; technical=3.5)")
    lines.append("")
    lines.append(f"Original:   {r['original_chars']} chars  ~ {r['estimated_original_tokens']} tokens")
    lines.append(f"Compressed: {r['compressed_chars']} chars  ~ {r['estimated_compressed_tokens']} tokens")
    lines.append("")
    lines.append(f"Savings: {r['tokens_saved']} tokens ({r['percent_token_savings']}%)")
    if "price_per_million_tokens" in r:
        lines.append("")
        lines.append(f"At r['price_per_million_tokens']/Mtok:")
        lines.append(f"  Cost saved per response:   .6f")
        lines.append(f"  Cost saved per 1k responses: .4f")
    lines.append("")
    lines.append("-" * 72)
    lines.append("Compressed preview:")
    lines.append(f"  {r['compressed_preview']}")
    return "\n".join(lines)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Estimate token + cost savings from caveman compression.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    price_help = "Per-million-token price (USD) to estimate cost savings"
    parser.add_argument("text", nargs="?", help="Input text (uses embedded sample if omitted)")
    parser.add_argument("--file", help="Read input from file")
    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
    parser.add_argument("--price-per-mtok", type=float, default=0.0, help=price_help)
    args = parser.parse_args()

    if args.file:
        try:
            with open(args.file, "r", encoding="utf-8") as f:
                original = f.read()
        except (IOError, OSError) as e:
            print(f"error: {e}", file=sys.stderr)
            return 1
    elif args.text:
        original = args.text
    else:
        original = SAMPLE_INPUT

    result = analyze(original, args.price_per_mtok)
    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(render_text(result))
    return 0


if __name__ == "__main__":
    sys.exit(main())

---
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

FILE:references/alignment-playbook.md
# 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).

FILE:scripts/alignment_checker.py
#!/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()

---
name: "self-eval"
description: "Honestly evaluate AI work quality using a two-axis scoring system. Use after completing a task, code review, or work session to get an unbiased assessment. Detects score inflation, forces devil's advocate reasoning, and persists scores across sessions."
license: "MIT"
---

# Self-Eval: Honest Work Evaluation

ultrathink

**Tier:** STANDARD
**Category:** Engineering / Quality
**Dependencies:** None (prompt-only, no external tools required)

## Description

Self-eval is a Claude Code skill that produces honest, calibrated work evaluations. It replaces the default AI tendency to rate everything 4/5 with a structured two-axis scoring system, mandatory devil's advocate reasoning, and cross-session anti-inflation detection.

The core insight: AI self-assessment converges to "everything is a 4" because a single-axis score conflates task difficulty with execution quality. Self-eval separates these axes, then combines them via a fixed matrix that the model cannot override.

## Features

- **Two-axis scoring** — Independently rates task ambition (Low/Medium/High) and execution quality (Poor/Adequate/Strong), then combines via a lookup matrix
- **Mandatory devil's advocate** — Before finalizing, must argue for both higher AND lower scores, then resolve the tension
- **Score persistence** — Appends scores to `.self-eval-scores.jsonl` in the working directory, building history across sessions
- **Anti-inflation detection** — Reads past scores and flags clustering (4+ of last 5 identical)
- **Matrix-locked scoring** — The composite score comes from the matrix, not from direct selection. Low ambition caps at 2/5 regardless of execution quality

## Usage

After completing work in a Claude Code session:

```
/self-eval
```

With context about what to evaluate:

```
/self-eval the authentication refactor we just completed
```

The skill reviews the conversation history, identifies what was accomplished, scores it on both axes, runs the devil's advocate check, and appends the result to the score history file.

## Examples

### Example 1: Feature Implementation

```
/self-eval added pagination to the user list API
```

Output:
```
## Self-Evaluation

**Task:** Added cursor-based pagination to the user list API endpoint
**Ambition:** Medium — New feature with established patterns, but required careful backwards compatibility
**Execution:** Strong — All tests pass, handles edge cases, existing clients unaffected

**Devil's Advocate:**
- Lower: Pagination is well-documented. The pattern was copied from another endpoint with minor changes. Could argue Low ambition.
- Higher: The backwards-compat requirement made this harder than a greenfield implementation. Had to support both offset and cursor modes.
- Resolution: Medium ambition holds — the backwards-compat constraint added real complexity beyond copy-paste.

**Score: 4** — Solid execution on meaningful work with real constraints.
```

### Example 2: Bug Fix

```
/self-eval
```

Output:
```
## Self-Evaluation

**Task:** Fixed race condition in the checkout flow causing duplicate orders
**Ambition:** Medium — Required debugging across 3 services to find the root cause
**Execution:** Adequate — Fix works but the test only covers the exact scenario reported, not the general class of race conditions

**Devil's Advocate:**
- Lower: The fix was a single line (adding a mutex). Once found, it was trivial.
- Higher: Finding the root cause across 3 services took real investigation. The mutex placement required understanding the full flow.
- Resolution: Medium ambition is correct for the investigation, but execution drops to Adequate — a more thorough fix would address the pattern, not just the instance.

**Score: 3** — Good debugging work but the fix is narrow.
```

---

## What to Evaluate

$ARGUMENTS

If no arguments provided, review the full conversation history to identify what was accomplished this session. Summarize the work in one sentence before scoring.

## How to Score — Two-Axis Model

Score on two independent axes, then combine using the matrix. Do NOT pick a number first and rationalize it — rate each axis separately, then read the matrix.

### Axis 1: Task Ambition (what was attempted)

Rate the difficulty and risk of what was worked on. NOT how well it was done.

- **Low (1)** — Safe, familiar, routine. No real risk of failure. Examples: minor config changes, simple refactors, copy-paste with small modifications, tasks you were confident you'd complete before starting.
- **Medium (2)** — Meaningful work with novelty or challenge. Partial failure was possible. Examples: new feature implementation, integrating an unfamiliar API, architectural changes, debugging a tricky issue.
- **High (3)** — Ambitious, unfamiliar, or high-stakes. Real risk of complete failure. Examples: building something from scratch in an unfamiliar domain, complex system redesign, performance-critical optimization, shipping to production under pressure.

**Self-check:** If you were confident of success before starting, ambition is Low or Medium, not High.

### Axis 2: Execution Quality (how well it was done)

Rate the quality of the actual output, independent of how ambitious the task was.

- **Poor (1)** — Major failures, incomplete, wrong output, or abandoned mid-task. The deliverable doesn't meet its own stated criteria.
- **Adequate (2)** — Completed but with gaps, shortcuts, or missing rigor. Did the thing but left obvious improvements on the table.
- **Strong (3)** — Well-executed, thorough, quality output. No obvious improvements left undone given the scope.

### Composite Score Matrix

|                        | Poor Exec (1) | Adequate Exec (2) | Strong Exec (3) |
|------------------------|:---:|:---:|:---:|
| **Low Ambition (1)**   |  1  |  2  |  2  |
| **Medium Ambition (2)**|  2  |  3  |  4  |
| **High Ambition (3)**  |  2  |  4  |  5  |

**Read the matrix, don't override it.** The composite is your score. The devil's advocate below can cause you to re-rate an axis — but you cannot directly override the matrix result.

Key properties:
- Low ambition caps at 2. Safe work done perfectly is still safe work.
- A 5 requires BOTH high ambition AND strong execution. It should be rare.
- High ambition + poor execution = 2. Bold failure hurts.
- The most common honest score for solid work is 3 (medium ambition, adequate execution).

## Devil's Advocate (MANDATORY)

Before writing your final score, you MUST write all three of these:

1. **Case for LOWER:** Why might this work deserve a lower score? What was easy, what was avoided, what was less ambitious than it appears? Would a skeptical reviewer agree with your axis ratings?
2. **Case for HIGHER:** Why might this work deserve a higher score? What was genuinely challenging, surprising, or exceeded the original plan?
3. **Resolution:** If either case reveals you mis-rated an axis, re-rate it and recompute the matrix result. Then state your final score with a 1-2 sentence justification that addresses at least one point from each case.

If your devil's advocate is less than 3 sentences total, you're not engaging with it — try harder.

## Anti-Inflation Check

Check for a score history file at `.self-eval-scores.jsonl` in the current working directory.

If the file exists, read it and check the last 5 scores. If 4+ of the last 5 are the same number, flag it:
> **Warning: Score clustering detected.** Last 5 scores: [list]. Consider whether you're anchoring to a default.

If the file doesn't exist, ask yourself: "Would an outside observer rate this the same way I am?"

## Score Persistence

After presenting your evaluation, append one line to `.self-eval-scores.jsonl` in the current working directory:

```json
{"date":"YYYY-MM-DD","score":N,"ambition":"Low|Medium|High","execution":"Poor|Adequate|Strong","task":"1-sentence summary"}
```

This enables the anti-inflation check to work across sessions. If the file doesn't exist, create it.

## Output Format

Present your evaluation as:

## Self-Evaluation

**Task:** [1-sentence summary of what was attempted]
**Ambition:** [Low/Medium/High] — [1-sentence justification]
**Execution:** [Poor/Adequate/Strong] — [1-sentence justification]

**Devil's Advocate:**
- Lower: [why it might deserve less]
- Higher: [why it might deserve more]
- Resolution: [final reasoning]

**Score: [1-5]** — [1-sentence final justification]

---
name: channel-economics
description: "Use when reviewing or rebalancing direct vs. partner-led channel economics — computing fully-loaded cost-to-serve per channel, channel ROI with cash / LTV / marginal lenses, and optimal channel mix subject to constraints. For Head of Commercial, RevOps, and VP Sales doing quarterly channel review when pipeline is mixed (e.g., 60% direct + 40% partner-led) and nobody actually knows which channel makes money after CAC, support load, partner discount, deal-velocity differences, retention differential, and overhead allocation are all loaded in. Outputs cost to serve, channel ROI verdicts (DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection. Not channel structure (that's partnerships-architect — tiers, joint GTM, revshare). Not RevOps process (that's business-growth/revenue-operations — lead routing, SDR motion). Not strategic CRO judgment (that's c-level-advisor/cro-advisor — comp plans, when-to-hire-a-VP-Sales). Not historical close-and-report (that's finance/financial-analysis). This skill answers: direct vs partner profitability, channel profitability, channel mix, channel economics."
version: 2.8.0
author: claude-code-skills
license: MIT
tags: [commercial, channel-economics, cost-to-serve, channel-mix, channel-roi, direct-vs-partner, unit-economics]
compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
---

# channel-economics

## Purpose

Help Head of Commercial / RevOps / VP Sales answer three questions at the quarterly channel review:

1. **What does each channel actually cost to serve, fully loaded?** (direct headcount, channel manager attribution, partner discount, MDF, enablement time, support load, allocated overhead)
2. **What is the ROI of each channel under three lenses?** (cash ROI year-1, LTV-adjusted ROI, marginal ROI — next dollar of investment)
3. **What is the optimal channel mix subject to our strategic constraints?** (minimum direct floor, maximum partner concentration ceiling, sensitivity to CAC shifts)

The skill emits **per-channel verdicts** (DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT), a **sensitivity-tested mix recommendation**, and **the diminishing-returns inflection point**. It does not pick the strategy — humans do, with the numbers loaded honestly for the first time.

## When to use

- Quarterly channel review: pipeline is 60/40 or 50/50 direct vs partner and you don't actually know which one is profitable
- Considering hiring a channel manager — need to know if the channel can clear the loaded-cost bar
- Partner program ROI question from the board ("we spent $X on MDF — what did we get?")
- A segment is over-indexed to one channel and you suspect mix dogma is blocking the other
- About to expand into a new region and need to decide direct-first vs partner-first
- M&A diligence: target company claims "partner-led at 70% gross margin" — need to validate after loading

**Do not use for:**
- Designing partner tiers, joint GTM motion, revshare splits → `partnerships-architect`
- SDR-to-AE routing, lead scoring, MQL definitions → `business-growth/revenue-operations`
- Strategic CRO decisions ("should we hire a VP Sales?", comp plan design) → `c-level-advisor/cro-advisor`
- Quarterly close, GAAP revenue recognition, channel-level P&L for historical reporting → `finance/financial-analysis`
- Per-deal discount approval → `deal-desk`
- Pricing model design → `pricing-strategist`

## Workflow

### Step 1 — Intake channel data

Fill `assets/channel_data_template.md` (≈ 20 min). Capture per channel: deal count TTM, ARR TTM, avg deal size, gross margin %, CAC, sales-cycle days, retention rate, expansion rate, partner discount %, all attributable costs (SDR / AE / SE / channel manager / CS / support / marketing / partner MDF / tooling / overhead allocation %).

The template surfaces the costs teams most often forget: partner enablement time, certification investment, channel-conflict resolution overhead, channel-manager headcount cost.

### Step 2 — Compute cost-to-serve per channel

Run `scripts/cost_to_serve_calculator.py --input channel.json --output markdown`.

Output: fully-loaded cost-to-serve **per deal** AND **per dollar of ARR**, with direct costs broken out from allocated overhead, and a "true gross margin" line after channel-specific load. Flags double-counting and surfaces hidden costs.

Run once per channel. The "true gross margin" line is the input the next two scripts care about.

### Step 3 — Compute ROI per channel under three lenses

Run `scripts/channel_roi_analyzer.py --input roi.json --profile saas --output markdown`.

Output: per channel, three ROI numbers (Cash year-1, LTV-adjusted, Marginal), the diminishing-returns inflection point, and a verdict: DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT.

Verdict logic is deterministic and surfaced in the report. Humans can override; the skill won't.

### Step 4 — Optimize channel mix subject to constraints

Run `scripts/channel_mix_optimizer.py --input mix.json --profile saas --output markdown`.

Output: recommended mix that maximizes effective ARR subject to constraints (min direct %, max partner concentration), plus a sensitivity table (what if direct CAC rises 20%? what if partner discount widens 5 points?).

### Step 5 — Decide

Take the three reports into the quarterly channel review. The skill recommends; the human commits.

## Scripts

- `scripts/cost_to_serve_calculator.py` — fully-loaded cost-to-serve per deal AND per $ ARR, with hidden-cost surfacing
- `scripts/channel_roi_analyzer.py` — 3-lens ROI (Cash / LTV / Marginal) with verdicts and diminishing-returns inflection
- `scripts/channel_mix_optimizer.py` — constrained mix optimizer with sensitivity scenarios

All scripts: stdlib only. `--help`, `--sample`, `--input`, `--output` work on all three. Industry tuning via `--profile {saas,api,enterprise-software,marketplace,hardware}` on the two analyzers.

## References

- `references/channel_economics_canon.md` — Skok, Bessemer State of the Cloud, Tunguz, Pacific Crest / KeyBanc SaaS Survey, Ramanujam, Jay McBain (Canalys)
- `references/cost_to_serve_canon.md` — Kaplan & Cooper (ABC), Horngren, Jeremy Hope, IBM CTS case studies, McKinsey, Gartner, BCG
- `references/channel_anti_patterns.md` — Forrester, Tunguz, Hessling, HBR, SiriusDecisions, MIT Sloan, Gartner

## Assumptions

- Channel economics is a **forward-looking** question. Historical channel P&L is finance's job; this skill loads forward economics for a decision.
- "Channel" means a coherent go-to-market motion (direct outbound, partner-led, marketplace, reseller, OEM). It does not mean a marketing source.
- Cost-to-serve requires **honest overhead allocation**. The script validates that overhead % is consistent across channels — false partner-margin lift from inconsistent allocation is the #1 anti-pattern.
- LTV inputs (retention, expansion) are per-channel, not pooled. Partner-sourced customers often retain differently than direct-sourced — this difference is usually the largest economic variable and the most ignored.
- Industry profiles (`--profile`) tune defaults for benchmarks (e.g., SaaS direct CAC payback target ~12mo, enterprise ~18mo) — they don't override your numbers.
- This is a decision-support skill. Output is verdicts and a recommended mix, never an automatic resource reallocation.

## Anti-patterns

- **Treating "influenced" deals as "sourced" deals.** A partner that touched a deal your AE already had is not channel-sourced revenue. Loading this as partner revenue inflates partner ROI and inflates direct CAC simultaneously.
- **Inconsistent overhead allocation.** Allocating 25% overhead to direct deals and 5% to partner deals because "the partner handles the overhead" is false. The partner manager, partner program, MDF, certification, and conflict-resolution all live in your P&L.
- **Ignoring enablement time as a cost.** Every hour your AE spends co-selling with a partner is a direct cost charged to the partner channel — most teams forget to load it.
- **MDF without ROI tracking.** Market Development Funds disbursed without an attributable pipeline ROI are just a partner-discount extension. The skill flags MDF with no return.
- **Channel-mix dogma.** "We're a partner-first company" / "we don't sell direct" blocks profitable segments. Mix should follow the math, not the slogan.
- **Computing channel ROI without retention differential.** If partner-sourced customers churn 5 points higher than direct, ignoring it overstates partner LTV by 30-50%. Per-channel retention is mandatory input.
- **No cost-attribution for channel-manager headcount.** A $200k channel manager managing $4M of partner ARR is $50 of channel-manager cost per $1k ARR — material to the verdict.
- **Confusing this skill with partnerships-architect.** That skill designs the partner program. This skill tells you whether the program pays for itself.

## Distinct from

- **commercial/partnerships-architect** — partner tier design, joint GTM motion, revshare splits, partner enablement. Partner program *structure*, not partner program *economics*. This skill consumes the program structure as input and emits the economic verdict.
- **business-growth/revenue-operations** — lead routing, SDR motion, MQL definition, pipeline operations. RevOps owns the funnel mechanics; this skill loads the channel-level economic outcome.
- **c-level-advisor/cro-advisor** — strategic CRO judgment: when to hire a VP Sales, comp plan philosophy, territory design, multi-year revenue strategy. CRO advisor consumes channel-economics output as one input among many.
- **finance/financial-analysis** — close-and-report on historical channel P&L per GAAP. This skill is forward-looking decision support; finance is historical record. Different time horizon, different audience, different output.
- **commercial/deal-desk** — per-deal discount approval. Operates daily; this skill operates quarterly.
- **commercial/pricing-strategist** — pricing model and tier design. Pricing is input; channel economics is what happens at that pricing across channels.

## Forcing-question library (Matt Pocock grill discipline)

Walked one at a time by `/cs:grill-commercial` or the orchestrator. Recommended answer + canon citation per question. Never bundled.

1. **"What's your fully-loaded cost-to-serve per channel — including channel-manager headcount, MDF, partner enablement time, and overhead allocation?"**
   Recommended: load all four. Most teams load partner discount but forget the channel-manager headcount and the enablement time, inflating partner margin by 8-15 points.
   Canon: Kaplan & Cooper (HBR 1988) — *Measure Costs Right: Make the Right Decisions*. Activity-Based Costing was invented precisely because channel costs hide in overhead and distort margin comparisons.

2. **"What is the retention differential between direct-sourced and partner-sourced customers?"**
   Recommended: instrument per-channel retention BEFORE running channel ROI. A 5-point retention gap moves LTV by 30-50%.
   Canon: David Skok (*For Entrepreneurs* — SaaS Metrics 2.0). LTV = (ARPA × Gross Margin) / Churn. Channel-blind churn is the most common source of false channel ROI.

3. **"What share of 'channel-sourced' pipeline did your team actually originate?"**
   Recommended: if your AE already had the account, it's not channel-sourced — it's channel-influenced. Influence and source are different economic lines.
   Canon: SiriusDecisions / Forrester channel attribution research — confused source vs. influence is the #1 reason partner ROI is overstated industry-wide.

4. **"What is the marginal ROI of the next dollar invested in partner program vs. direct sales?"**
   Recommended: compute the diminishing-returns curve on both. Average ROI hides the fact that the next dollar might earn 0.3x while the average earns 2.1x.
   Canon: Tomasz Tunguz (*Tomasz Tunguz blog* — channel CAC analyses). Average ROI is a vanity metric; marginal ROI drives investment decisions.

5. **"What's your MDF-to-attributable-pipeline ratio in the last 4 quarters?"**
   Recommended: < 5:1 (every $1 of MDF should generate ≥ $5 of attributable pipeline within 2 quarters). Anything looser is partner-discount theatre.
   Canon: Jay McBain (Canalys) — *State of the Channel* research. MDF without attribution discipline is the most expensive form of channel subsidy.

6. **"Is your channel-mix dogma blocking a profitable segment?"**
   Recommended: surface the dogma ("we're partner-first", "we don't sell direct in SMB") explicitly. Mix should follow the segment math.
   Canon: MIT Sloan Management Review — *When Channel Conflict Means Growth*. Dogmatic single-channel strategies forfeit 15-25% of TAM in mid-market specifically.

7. **"What overhead-allocation methodology are you applying — and is it consistent across direct and partner?"**
   Recommended: same methodology, same denominator, both channels. Inconsistent allocation is the silent killer of channel-economics analysis.
   Canon: Charles Horngren (*Cost Accounting: A Managerial Emphasis*) — allocation consistency is the precondition for cross-segment margin comparison. Without it, every conclusion is contaminated.

Walk depth-first. Lock 1-3 before opening 4-7. After all 7 are answered, invoke `cost_to_serve_calculator.py` → `channel_roi_analyzer.py` → `channel_mix_optimizer.py` in sequence.

FILE:assets/channel_data_template.md
# Channel Data Template

Fill this out in ~20 minutes. The three scripts in this skill all consume JSON; this template gives you the schema with annotations on **what to put** and **why**.

If you don't know a value, **leave it `null` (or the explicit "$0 unknown") and note it** — the scripts surface unknowns explicitly rather than silently substituting.

---

## Intake checklist (before you fill anything)

- [ ] Define "channel" — a coherent go-to-market motion (e.g., `direct`, `partner-led`, `marketplace`, `reseller`, `oem`). NOT a marketing source.
- [ ] Confirm allocation methodology is the **same** across all channels (revenue-share or activity-driver, not mixed)
- [ ] Confirm retention numbers are **per-channel**, not pooled
- [ ] Confirm "channel-sourced" deals meet the strict definition: partner originated the opportunity AND brought it unqualified
- [ ] Identify your industry profile: `saas | api | enterprise-software | marketplace | hardware`

---

## Template 1 — Input for `cost_to_serve_calculator.py`

Run **once per channel**.

```json
{
  "channel_name": "partner-led-EMEA",
  "deal_volume": 80,
  "gross_revenue": 4000000,
  "costs": {
    "sdr_attribution": 60000,
    "ae_attribution": 240000,
    "sales_engineer_attribution": 90000,
    "channel_manager_attribution": 180000,
    "customer_success_attribution": 120000,
    "support_attribution": 70000,
    "marketing_attribution": 50000,
    "partner_discount": 600000,
    "partner_MDF": 80000,
    "partner_enablement_time": 40000,
    "certification_investment": 20000,
    "channel_conflict_overhead": 15000,
    "tooling_attribution": 25000,
    "overhead_allocation_pct": 15.0
  }
}
```

### Field-by-field guidance

| Field | What to put |
|---|---|
| `channel_name` | Coherent GTM motion. Examples: `direct`, `partner-led`, `marketplace`, `reseller-NA`, `oem`. Naming matters — the optimizer recognizes `direct` and `partner` substrings for constraint enforcement. |
| `deal_volume` | Closed-won deal count, trailing-twelve-months (TTM). |
| `gross_revenue` | ARR (or annualized contracted revenue) closed in same TTM window. |
| `sdr_attribution` | Loaded cost of SDR time on this channel. If 30% of SDR team works on this channel, allocate 30% of total SDR loaded cost. |
| `ae_attribution` | Same logic for AE time. |
| `sales_engineer_attribution` | SE / solution architect time. Frequently underestimated for partner-led — includes partner technical enablement. |
| `channel_manager_attribution` | Loaded cost of channel-manager headcount. Direct channel = $0; partner channel = full loaded cost of channel team allocated by channel. **Do not leave $0 for partner channels** — the script flags it. |
| `customer_success_attribution` | CS team allocation. |
| `support_attribution` | Tier-1 / tier-2 support allocation. Partner-sourced customers often escalate to vendor faster — instrument support tickets by channel. |
| `marketing_attribution` | Demand-gen, content, events allocated to this channel. |
| `partner_discount` | Total $ given up in partner discount/margin for the TTM. |
| `partner_MDF` | Market Development Funds disbursed. |
| `partner_enablement_time` | Loaded $ of YOUR team's time spent on partner enablement. Frequently $0 in practice; should not be. |
| `certification_investment` | Partner certification programs, training events, ongoing enablement spend. |
| `channel_conflict_overhead` | Time/cost spent resolving deal conflicts between direct and channel teams. Industry: 5-8% of channel-team time. |
| `tooling_attribution` | CRM seats, PRM (Partner Relationship Management) tools, channel-specific tooling. |
| `overhead_allocation_pct` | Shared overhead allocated to this channel, as % of channel revenue. **Must be consistent across channels.** |

---

## Template 2 — Input for `channel_roi_analyzer.py`

Run **once across all channels**.

```json
{
  "profile": "saas",
  "channels": [
    {
      "channel": "direct",
      "investment_ttm": {
        "programs": 200000,
        "headcount_cost": 1600000,
        "partner_program_cost": 0,
        "mdf": 0,
        "tooling": 80000,
        "training": 60000
      },
      "returns_ttm": {
        "new_arr": 3800000,
        "expansion_arr": 900000,
        "retained_arr_attributable": 2400000
      }
    },
    {
      "channel": "partner-led",
      "investment_ttm": {
        "programs": 150000,
        "headcount_cost": 360000,
        "partner_program_cost": 280000,
        "mdf": 120000,
        "tooling": 30000,
        "training": 80000
      },
      "returns_ttm": {
        "new_arr": 1400000,
        "expansion_arr": 200000,
        "retained_arr_attributable": 900000
      }
    }
  ]
}
```

### Field guidance

| Field | What to put |
|---|---|
| `profile` | One of `saas`, `api`, `enterprise-software`, `marketplace`, `hardware`. Tunes LTV multiplier and marginal-decay alpha. |
| `investment_ttm.programs` | One-time program spend (events, content, campaigns). |
| `investment_ttm.headcount_cost` | Loaded headcount cost dedicated to this channel. |
| `investment_ttm.partner_program_cost` | Partner-program operating cost (PRM tooling, partner-portal infra, partner-only marketing). Distinct from MDF. |
| `investment_ttm.mdf` | Market Development Funds. |
| `investment_ttm.tooling` | Channel-specific tools. |
| `investment_ttm.training` | Internal training + partner training cost. |
| `returns_ttm.new_arr` | New ARR sourced by this channel, TTM. Strict definition: channel originated AND qualified. |
| `returns_ttm.expansion_arr` | Expansion ARR from customers sourced by this channel. |
| `returns_ttm.retained_arr_attributable` | Renewed ARR from customers sourced by this channel. |

---

## Template 3 — Input for `channel_mix_optimizer.py`

Run **once across all channels** with constraints.

```json
{
  "profile": "saas",
  "channels": [
    {
      "name": "direct",
      "deal_count_ttm": 120,
      "arr_ttm": 6000000,
      "avg_deal_size": 50000,
      "gross_margin_pct": 75,
      "cac": 18000,
      "sales_cycle_days": 75,
      "retention_rate": 0.92,
      "expansion_rate": 1.18,
      "partner_discount_pct": 0
    },
    {
      "name": "partner-led",
      "deal_count_ttm": 80,
      "arr_ttm": 4000000,
      "avg_deal_size": 50000,
      "gross_margin_pct": 75,
      "cac": 10000,
      "sales_cycle_days": 90,
      "retention_rate": 0.86,
      "expansion_rate": 1.08,
      "partner_discount_pct": 20
    }
  ],
  "constraints": {
    "min_direct_pct": 30,
    "max_partner_concentration_pct": 50
  }
}
```

### Field guidance

| Field | What to put |
|---|---|
| `name` | Channel name. Use `direct` / `partner` substrings for constraint enforcement to work. |
| `gross_margin_pct` | Use the **true gross margin** from `cost_to_serve_calculator.py` output, not the headline number. |
| `cac` | Fully loaded CAC. Includes the channel-specific costs from the cost-to-serve calculator. |
| `retention_rate` | **Per-channel** retention rate, not pooled. Critical input. |
| `expansion_rate` | Net expansion (1.0 = flat, 1.20 = 120% NRR). |
| `partner_discount_pct` | The discount % given up at sale (0 for direct channels). |
| `constraints.min_direct_pct` | Floor on direct-channel share (e.g., 30 = "at least 30% of investment must go to direct"). |
| `constraints.max_partner_concentration_pct` | Ceiling on any single partner channel (e.g., 50 = "no single partner channel may exceed 50%"). |

---

## After filling

1. Save each template as a JSON file (e.g., `channel-cts-partner.json`, `channel-roi.json`, `channel-mix.json`)
2. Run in sequence:
   ```bash
   python scripts/cost_to_serve_calculator.py --input channel-cts-partner.json --output markdown > out-cts-partner.md
   python scripts/channel_roi_analyzer.py --input channel-roi.json --profile saas --output markdown > out-roi.md
   python scripts/channel_mix_optimizer.py --input channel-mix.json --profile saas --output markdown > out-mix.md
   ```
3. Bring all three reports to the quarterly channel review.

FILE:references/channel_anti_patterns.md
# Channel Anti-Patterns

The eight anti-patterns this skill is built to detect, with citations. Most channel-economics decisions fail because of these patterns, not because the math is wrong.

---

## 1. Channel-led deals from your own pipeline = direct cost + partner cut

**Pattern:** Your AE sources an account, qualifies it, runs discovery, scopes the solution — and then a partner gets attached at the contract stage for the partner cut. The deal closes, is reported as "channel-sourced", and the partner gets margin.

**Why it kills:** You paid full direct cost (AE time, SE time, marketing) AND gave away partner margin. The deal looks profitable as "channel-led" but is value-destroying in reality.

**Detection:** require **first-touch attribution** in CRM. If the first-touch is internal but the deal closes as channel-sourced, flag it.

Source: Forrester Research, *The Channel-Influence vs. Channel-Source Gap*, 2019. Industry data: 25-40% of "channel-sourced" deals are actually channel-influenced direct deals.

---

## 2. No overhead allocation = false partner-margin lift

**Pattern:** Partner channel reports 75% gross margin while direct reports 60%. Look closer: direct channel gets 25% overhead allocation; partner channel gets 5% "because the partner handles overhead." The partner does not, in fact, handle overhead — your channel manager, partner program, MDF, and certification are all in YOUR P&L.

**Why it kills:** Apparent partner-margin lift drives over-investment in partner program. When the executive team eventually does honest allocation, partner margin collapses 8-15 points.

**Detection:** validate overhead-% is **consistent** across channels. If partner overhead allocation is <50% of direct, flag for review.

Source: Tomasz Tunguz, *The Hidden Costs of Channel Programs*, tomtunguz.com analyses 2021-2023. See also Horngren on allocation consistency.

---

## 3. Ignoring enablement time as cost

**Pattern:** Your AE spends 4 hours/week on partner co-selling, your SE spends 6 hours/week on partner technical enablement, your CS team handles tier-2 support that partners offload. None of this is loaded into channel cost.

**Why it kills:** Partner enablement time is often 15-30% of total channel cost, completely unattributed. The channel looks far more efficient than it is.

**Detection:** `cost_to_serve_calculator.py` flags `partner_enablement_time` and `certification_investment` when left at $0.

Source: Jay McBain (Canalys), *State of the Channel* research; Joe Hessling, *Partner Program ROI Studies* (channeltivity.com). Industry data: time-tracked enablement attribution increases partner channel cost by 15-30% over naive accounting.

---

## 4. MDF without ROI tracking

**Pattern:** Market Development Funds disbursed to partners without an attributable pipeline ROI. Partners take the MDF, deliver an event or campaign of dubious value, and no pipeline is traceable to the spend.

**Why it kills:** MDF without attribution is just a partner discount in disguise — and undisciplined. Industry-median MDF-to-pipeline ratio is 3.5:1; best-in-class is >7:1. If yours is <3:1 (or untracked), you have an unbudgeted discount line.

**Detection:** require MDF requests to commit to attributable pipeline targets BEFORE disbursement. Reconcile quarterly.

Source: Jay McBain (Canalys), MDF discipline research. SiriusDecisions (now Forrester) MDF benchmarks: 60% of MDF spend has no attributable pipeline tracking at all.

---

## 5. Channel-mix dogma ("we don't sell direct") blocks profitable segments

**Pattern:** A founder or CRO has a strong belief — "we're a partner-first company", "we don't sell direct in SMB", "we never sell direct in EMEA" — that overrides the segment-level economics. Profitable segments get starved because the strategy slogan doesn't allow direct motion there.

**Why it kills:** Mix should follow the math. Industry data shows dogmatic single-channel strategies forfeit 15-25% of TAM in mid-market specifically.

**Detection:** force the explicit articulation of the dogma in the planning conversation. "What's the segment we DON'T sell into, and why?"

Source: MIT Sloan Management Review, *When Channel Conflict Means Growth*, Frazier & Lassar (1996, updated 2019). Also: HBR on channel-conflict mismanagement, Cespedes (2014).

---

## 6. Treating influenced as sourced

**Pattern:** Partner is involved somewhere in a deal cycle — sometimes only at signature — and the deal is reported as "channel-sourced." Influence and source get conflated.

**Why it kills:** Inflates partner contribution by 25-40%. Drives mis-allocation of channel investment. Channel-program ROI becomes uninterpretable.

**Detection:** require strict first-touch + qualified-source criteria. Channel-sourced = partner originated the opportunity AND brought it to your team unqualified.

Source: SiriusDecisions (now Forrester), *Channel Attribution Models*, 2018-2022 research. Single most-cited source-vs-influence taxonomy in B2B SaaS.

---

## 7. No cost-attribution for channel-manager headcount

**Pattern:** Channel manager salary ($150-$250k loaded) is bucketed under "G&A" or "Sales Overhead" rather than attributed to the channel they manage. The channel reports better economics because its biggest cost line is hidden.

**Why it kills:** A $200k channel manager managing $4M of partner ARR is $50 of channel-manager cost per $1k ARR — material to the channel verdict. Hiding it is the most common single-line distortion in channel economics.

**Detection:** `cost_to_serve_calculator.py` flags `channel_manager_attribution` at $0 as a hidden-cost line.

Source: Gartner, *Service Delivery Cost Allocation in Multi-Channel Technology Vendors*, 2022. McKinsey CTS research.

---

## 8. Channel ROI computed without retention differential

**Pattern:** Channel ROI calculation uses pooled retention assumption (e.g., 90% across all channels) when in fact partner-sourced customers retain at 84% and direct-sourced retain at 92%. LTV calculation is inflated for the partner channel.

**Why it kills:** A 5-point retention gap moves LTV by 30-50%. Most channel investment decisions are made on LTV, so the wrong retention assumption produces the wrong investment decision.

**Detection:** require **per-channel retention** as mandatory input. `channel_mix_optimizer.py` will not compute effective LTV without a per-channel retention number.

Source: David Skok (*For Entrepreneurs* — SaaS Metrics 2.0). LTV = (ARPA × Gross Margin) / Churn — channel-blind churn is the most common source of false channel ROI.

---

## Bonus anti-pattern: the "we'll figure out attribution later" trap

**Pattern:** Channel program launches without an attribution model. Six quarters later, no one can answer "did this work?" because the data was never structured.

**Why it kills:** Attribution must be designed at program-launch, not retrofit. Retroactive attribution is always contested.

**Detection:** force the attribution model to be in writing BEFORE the channel program is launched.

Source: HBR, *Why Channel Programs Fail* (Cespedes, 2014). Also: Tomasz Tunguz on channel-trap analyses.

---

## How this skill detects the anti-patterns

| Anti-pattern | Detection mechanism |
|---|---|
| 1. Channel-led from own pipeline | Forcing question #3 (influence vs. source) |
| 2. No overhead allocation | `cost_to_serve_calculator.py` warns on inconsistent overhead-% |
| 3. Ignoring enablement time | Hidden-cost flag on `partner_enablement_time` |
| 4. MDF without ROI | Forcing question #5 (MDF ratio) |
| 5. Mix dogma | Forcing question #6 |
| 6. Influenced as sourced | Forcing question #3 |
| 7. No channel-manager attribution | Hidden-cost flag on `channel_manager_attribution` |
| 8. No retention differential | Forcing question #2; mandatory per-channel input |

FILE:references/channel_economics_canon.md
# Channel Economics Canon

The authoritative reference set for direct-vs-partner economics, channel ROI computation, and channel-mix decision-making. Use this when validating the assumptions inside `cost_to_serve_calculator.py`, `channel_roi_analyzer.py`, and `channel_mix_optimizer.py`.

---

## 1. David Skok — *For Entrepreneurs*: SaaS Metrics 2.0

Skok's framework gives the LTV / CAC equation the industry treats as canonical:

- **LTV = (ARPA × Gross Margin %) / Churn Rate**
- **LTV / CAC ≥ 3.0** is the floor for sustainable channel investment
- **CAC Payback ≤ 12 months** is the SaaS target (longer for enterprise)

The channel-economics application: **per-channel LTV/CAC and per-channel payback, never pooled**. Pooled metrics hide the fact that one channel is funding another.

Source: `forentrepreneurs.com` — *SaaS Metrics 2.0 — A Guide to Measuring and Improving What Matters* (2014, updated 2018).

---

## 2. Bessemer Venture Partners — *State of the Cloud* (annual)

BVP's annual benchmark report is the single most-cited source for channel mix and CAC benchmarks across public + private SaaS:

- Public SaaS gross margins cluster 70-80%; partner-led channels typically run 5-10pts lower after load
- Sales efficiency (Magic Number) ≥ 0.7 is the funding bar; channel inefficiency drags this below the bar fastest
- **Partner-led** companies that scale past $100M ARR almost universally have <40% partner concentration — single-partner risk dominates above this line

Source: Bessemer Venture Partners, *State of the Cloud* report series, 2014-2024 editions.

---

## 3. Tomasz Tunguz — Channel CAC analyses

Tunguz's blog has the most rigorous public series on channel CAC and the **diminishing-returns curve** specifically. Key findings replicated across cohorts:

- **Marginal CAC rises non-linearly** with investment scale. The first $1M in channel program returns ~3x; the next $1M returns ~1.5x; the next $1M often <1.0x.
- **Average ROI is a vanity metric.** Investment decisions must be made on marginal ROI.
- Channel programs that "work on paper" but fail in practice usually fail because the team funded them past the marginal-ROI inflection point without realizing it.

Source: `tomtunguz.com` — channel CAC posts including *The Channel CAC Premium*, *Diminishing Returns in SaaS Sales*.

---

## 4. Pacific Crest / KeyBanc Capital Markets — Annual SaaS Survey

The Pacific Crest survey (continued by KeyBanc) is the longest-running channel-economics benchmark — 350+ private SaaS companies surveyed annually since 2008. The channel-specific findings used in this skill:

- Median **direct CAC payback**: 14 months. Partner-led: 11 months (lower nominal but understates loaded cost).
- Channel-led companies with <70% true (loaded) gross margin in partner channel materially underperform direct-led peers on Rule of 40
- **Mixed-motion** companies (40-60% direct, balance partner) outperform single-motion peers on growth efficiency by ~15-20%

Source: KeyBanc Capital Markets, *SaaS Survey* annual report (most recent 2024).

---

## 5. Madhavan Ramanujam — *Monetizing Innovation* — channel chapter

Ramanujam's channel chapter introduces the "value-flow" framework:

- Every channel splits **economic value** between vendor, partner, and customer
- The partner-cut must be **earned** by partner-delivered value (lead gen, technical sale, implementation, support) — not granted by program-tier convention
- Channels where the partner-cut exceeds the value the partner delivers are **economic transfers, not channel programs**

Source: Madhavan Ramanujam and Georg Tacke, *Monetizing Innovation* (Wiley, 2016) — Chapter 8 on channel & pricing alignment.

---

## 6. Jay McBain (Canalys) — Channel research

McBain is the most-cited channel analyst working today. The Canalys research the skill draws on:

- **MDF discipline.** Industry median MDF-to-attributable-pipeline ratio is 3.5:1; best-in-class >7:1. Anything below 3:1 is undisciplined.
- **Influence vs. source.** Channel-influenced ≠ channel-sourced. Industry conflation overstates partner contribution by 25-40% on average.
- **Channel-conflict overhead** is a real and measurable cost; mature channel programs allocate 5-8% of channel-team time to conflict resolution and surface it as a P&L line.

Source: Canalys research notes by Jay McBain (formerly Forrester), 2020-2024 — see also McBain's LinkedIn newsletter *Channel Insights*.

---

## 7. KeyBanc + OpenView — Joint *Channel Maturity Benchmark*

Joint research between KeyBanc Capital Markets and OpenView Partners (2022-2024) establishing the **channel maturity** scale used in this skill's verdict logic:

- Stage 1 (Discovery): channel < 15% of revenue, <2x LTV/CAC — DEFUND or EXIT verdict
- Stage 2 (Scale): channel 15-35% of revenue, 2-3x LTV/CAC — MAINTAIN verdict
- Stage 3 (Optimization): channel 35-50% of revenue, 3-5x LTV/CAC — DOUBLE-DOWN verdict candidate
- Stage 4 (Mature): channel >50%, but check single-partner concentration — risk verdict

Source: OpenView Partners + KeyBanc Capital Markets, *Channel Maturity Benchmark* 2023.

---

## How this skill uses the canon

- **`channel_roi_analyzer.py`** verdict thresholds derive from Skok (LTV/CAC ≥ 3.0 floor) and BVP cash-ROI target ranges
- **`channel_mix_optimizer.py`** payback targets per profile follow KeyBanc/Pacific Crest survey medians
- **Diminishing-returns curve** in the marginal-ROI computation traces directly to Tunguz's channel-CAC posts
- **Influence-vs-source discipline** in the forcing-question library comes from McBain (Canalys) and SiriusDecisions

When the user's data contradicts these benchmarks, the data wins — these are reference anchors, not rules.

FILE:references/cost_to_serve_canon.md
# Cost-to-Serve Canon

The authoritative reference set for fully-loaded cost-to-serve methodology. Use this when validating cost categories, allocation methodology, and the "hidden costs" `cost_to_serve_calculator.py` surfaces.

The core principle across every source below: **without consistent overhead allocation, every cross-channel margin comparison is contaminated**.

---

## 1. Robert Kaplan & Robin Cooper — *Measure Costs Right: Make the Right Decisions* (HBR, 1988)

The foundational paper for Activity-Based Costing (ABC). Kaplan & Cooper observed that traditional cost-allocation methods systematically distort channel and product margins:

- **High-volume, low-complexity** channels appear unprofitable under traditional allocation (they over-absorb overhead)
- **Low-volume, high-complexity** channels appear profitable (they under-absorb)
- The fix: allocate overhead **by activity driver**, not by revenue share

For channel economics: partner-led channels typically appear higher-margin under naïve allocation precisely because they're lower-volume + higher-complexity. ABC corrects this.

Source: Kaplan, R.S. & Cooper, R., *Measure Costs Right: Make the Right Decisions*, Harvard Business Review, September-October 1988.

---

## 2. Charles Horngren — *Cost Accounting: A Managerial Emphasis*

The canonical textbook (now in 16th edition, Pearson). The chapters this skill draws on:

- **Chapter 14 (Cost allocation)**: the rule of *allocation consistency* — same methodology, same denominator, every comparable segment. Inconsistent allocation invalidates downstream comparison.
- **Chapter 15 (Customer-profitability analysis)**: the channel-economics application — customer (and channel) profitability is a function of *both* revenue *and* fully-loaded cost-to-serve, never just gross margin.

The most common channel-economics error this textbook anchors: **allocating overhead at 25% to direct and 5% to partner** "because the partner handles the overhead." The partner does not, in fact, handle the channel manager, the partner program, the certification, the MDF, the conflict resolution — all of which sit in YOUR P&L.

Source: Horngren, Datar & Rajan, *Cost Accounting: A Managerial Emphasis*, 16th ed., Pearson.

---

## 3. Jeremy Hope — *Beyond Budgeting* + channel-allocation writings

Hope's *Beyond Budgeting* movement contributed the framework for **rolling channel-cost allocation** rather than annual fixed allocation. Key principle:

- **Channel cost allocation must update at the same cadence as channel investment decisions** (quarterly minimum)
- Annual fixed allocations lock in last year's channel mix and prevent learning
- Use rolling 4-quarter cost-to-serve for forward decisions

Source: Hope, J. & Fraser, R., *Beyond Budgeting* (Harvard Business School Press, 2003); BBRT (Beyond Budgeting Round Table) channel-allocation guidance papers.

---

## 4. IBM Cost-to-Serve transformation case studies

IBM Institute for Business Value has published a sequence of cost-to-serve transformation case studies (2010-2022). Findings replicated across cases:

- **5-15% of "gross margin"** at large enterprises evaporates when partner-channel overhead is loaded honestly
- The single largest unattributed cost is **technical-sale resource time** (sales engineering / solution architects co-selling with partners)
- Companies that move from naive to ABC-style channel allocation typically **defund 1-2 channels** within 6 months — and grow the remaining channels faster

Source: IBM Institute for Business Value, *Cost-to-Serve Transformation* case study series.

---

## 5. McKinsey & Company — Cost-to-Serve research

McKinsey's go-to-market practice publishes regular CTS research. The findings this skill leans on:

- **Customer-level CTS variance** within a single channel is often 5-10x — meaning a channel-average CTS hides material per-customer variance
- The hidden-cost line items most teams omit, in order of impact: technical-sale time, channel-manager attribution, partner enablement time, certification investment, conflict-resolution overhead
- McKinsey's recommended cadence: refresh CTS quarterly minimum, annually at the customer level, continuously for top-decile accounts

Source: McKinsey & Company, *Cost-to-Serve: Reducing complexity and increasing profitability* (operations practice white papers).

---

## 6. Gartner — Service Delivery Cost research

Gartner's research on service-delivery cost allocation, particularly for technology vendors with mixed direct + partner motion:

- The **service-delivery overhead** (customer success, support, professional services) often differs by 30-50% between direct-sourced and partner-sourced customers
- Reasons: partner-sourced customers often arrive less qualified, requiring more onboarding; partner-sourced customers expand less, reducing CS leverage; partner-sourced customers escalate to vendor support faster because the partner offloads tier-2 support back
- Gartner's recommendation: instrument support-ticket-volume-per-customer **by sourcing channel**, not by customer size

Source: Gartner, *Service Delivery Cost Allocation in Multi-Channel Technology Vendors* research notes, 2021-2024.

---

## 7. Boston Consulting Group — Channel allocation methodology

BCG's channel-allocation methodology (from their TMT and software practices) introduces the **dual-axis** cost framework this skill implements:

- **Direct costs**: incurred specifically because of this channel (channel manager headcount, MDF, partner discount, certification spend)
- **Allocated overhead**: shared costs apportioned by activity driver (revenue share, deal count, or time-tracked attribution)
- The two must always be reported separately so executives can see the lever they control directly

This is the framework `cost_to_serve_calculator.py` enforces by breaking out direct cost lines from allocated overhead — and validating overhead-% consistency across channels.

Source: BCG, *Channel Economics in Software & Subscription Businesses* practitioner publications.

---

## How this skill uses the canon

- **Direct-cost line items** in `cost_to_serve_calculator.py` follow BCG's dual-axis framework
- **Hidden-cost surfacing** (the `HIDDEN_COST_KEYS` list flagged when $0) follows McKinsey's most-forgotten-cost ranking
- **Allocation consistency validation** (warns when partner channel has <5% overhead while direct has >20%) implements Horngren's allocation-consistency rule
- **Per-channel retention differential** (used in `channel_roi_analyzer.py`) follows Gartner's service-delivery findings — channel-blind retention is the most common source of wrong channel ROI

FILE:scripts/channel_mix_optimizer.py
#!/usr/bin/env python3
"""channel_mix_optimizer.py

Computes per-channel effective LTV, payback period, and efficiency ratio
(LTV/CAC), then recommends a channel mix that maximizes effective ARR
subject to constraints (min direct %, max partner concentration %).

Includes a sensitivity table: what happens if direct CAC rises 20%, partner
discount widens 5 points, or retention drops 3 points?

Stdlib-only. Deterministic. No external solver — uses a discrete grid search
over feasible mixes, which is sufficient for 2-6 channel problems.

Usage:
    python channel_mix_optimizer.py --sample
    python channel_mix_optimizer.py --input mix.json --profile saas --output markdown
"""
from __future__ import annotations

import argparse
import json
import sys
from typing import Any

# Industry profiles tune assumed gross-margin-to-monthly conversion and
# benchmark payback targets (months).
PROFILES = {
    "saas": {"payback_target_months": 12, "ltv_cac_floor": 3.0},
    "api": {"payback_target_months": 9, "ltv_cac_floor": 4.0},
    "enterprise-software": {"payback_target_months": 18, "ltv_cac_floor": 3.0},
    "marketplace": {"payback_target_months": 6, "ltv_cac_floor": 2.5},
    "hardware": {"payback_target_months": 24, "ltv_cac_floor": 2.0},
}


def _num(v: Any, default: float = 0.0) -> float:
    try:
        return float(v)
    except (TypeError, ValueError):
        return default


def compute_channel_metrics(ch: dict, profile_cfg: dict) -> dict:
    name = ch.get("name", "unnamed")
    deal_count = _num(ch.get("deal_count_ttm"))
    arr_ttm = _num(ch.get("arr_ttm"))
    avg_deal = _num(ch.get("avg_deal_size"))
    gm_pct = _num(ch.get("gross_margin_pct"), 70.0)
    cac = _num(ch.get("cac"))
    cycle_days = _num(ch.get("sales_cycle_days"), 60)
    retention = _num(ch.get("retention_rate"), 0.85)
    expansion = _num(ch.get("expansion_rate"), 1.05)
    partner_discount = _num(ch.get("partner_discount_pct"), 0)

    if avg_deal <= 0 or cac <= 0:
        return {"name": name, "error": "avg_deal_size and cac must both be > 0"}

    # Effective margin after partner discount
    effective_margin_pct = gm_pct * (1.0 - partner_discount / 100.0)

    # Effective LTV — geometric-series approximation:
    # LTV = avg_deal * (effective_margin/100) * expansion / (1 - retention)
    # If retention >= 1.0, cap denominator at 0.05 to avoid blowup (means
    # "indefinite retention" — we don't reward unrealistically).
    denom = max(1.0 - retention, 0.05)
    effective_ltv = avg_deal * (effective_margin_pct / 100.0) * expansion / denom

    # Payback period: months to recoup CAC at monthly gross margin
    monthly_gross_margin = (avg_deal / 12.0) * (effective_margin_pct / 100.0)
    payback_months = cac / monthly_gross_margin if monthly_gross_margin > 0 else float("inf")

    # Efficiency ratio
    ltv_cac = effective_ltv / cac if cac > 0 else 0.0

    return {
        "name": name,
        "deal_count_ttm": deal_count,
        "arr_ttm": arr_ttm,
        "avg_deal_size": avg_deal,
        "gross_margin_pct": gm_pct,
        "effective_margin_pct": round(effective_margin_pct, 2),
        "cac": cac,
        "sales_cycle_days": cycle_days,
        "retention_rate": retention,
        "expansion_rate": expansion,
        "partner_discount_pct": partner_discount,
        "effective_ltv": round(effective_ltv, 2),
        "payback_months": round(payback_months, 2),
        "ltv_cac": round(ltv_cac, 2),
        "meets_payback_target": payback_months <= profile_cfg["payback_target_months"],
        "meets_ltv_cac_floor": ltv_cac >= profile_cfg["ltv_cac_floor"],
    }


def _is_partner_channel(name: str) -> bool:
    n = name.lower()
    return any(tag in n for tag in ("partner", "reseller", "channel", "oem", "marketplace"))


def _is_direct_channel(name: str) -> bool:
    return "direct" in name.lower() or "inside" in name.lower() or "outbound" in name.lower()


def optimize_mix(metrics: list, constraints: dict) -> dict:
    """Discrete grid search over channel-mix percentages (5% increments)."""
    n = len(metrics)
    if n == 0:
        return {"error": "no channels provided"}

    min_direct = _num(constraints.get("min_direct_pct"), 0)
    max_partner_conc = _num(constraints.get("max_partner_concentration_pct"), 100)

    # Score = effective_ltv / cac (use LTV/CAC as the per-$-CAC efficiency).
    # We allocate a normalized 100 "investment units" across channels and maximize
    # sum(units_i * ltv_cac_i) subject to constraints.
    best_score = -1.0
    best_mix = None

    step = 5
    # generate compositions of 100 over n channels in 5% steps
    def gen(remaining: int, slots: int):
        if slots == 1:
            yield (remaining,)
            return
        for v in range(0, remaining + 1, step):
            for tail in gen(remaining - v, slots - 1):
                yield (v,) + tail

    for mix in gen(100, n):
        # constraint checks
        direct_share = sum(mix[i] for i, m in enumerate(metrics) if _is_direct_channel(m["name"]))
        partner_share_max = max(
            (mix[i] for i, m in enumerate(metrics) if _is_partner_channel(m["name"])),
            default=0,
        )
        if direct_share < min_direct:
            continue
        if partner_share_max > max_partner_conc:
            continue
        score = sum(mix[i] * metrics[i].get("ltv_cac", 0) for i in range(n))
        if score > best_score:
            best_score = score
            best_mix = mix

    if best_mix is None:
        return {"error": "no feasible mix under given constraints"}
    return {
        "best_mix_pct": {metrics[i]["name"]: best_mix[i] for i in range(n)},
        "score": round(best_score, 2),
    }


def sensitivity_scenarios(channels: list, profile_cfg: dict, constraints: dict) -> list:
    """Re-run optimization under perturbed inputs."""
    scenarios = []

    def perturb(perturbation_fn, label: str):
        perturbed = []
        for c in channels:
            cc = dict(c)
            perturbation_fn(cc)
            perturbed.append(cc)
        ms = [compute_channel_metrics(c, profile_cfg) for c in perturbed]
        ms = [m for m in ms if "error" not in m]
        opt = optimize_mix(ms, constraints)
        scenarios.append({"scenario": label, "mix": opt.get("best_mix_pct"), "note": opt.get("error")})

    def bump_direct_cac(c):
        if _is_direct_channel(c.get("name", "")):
            c["cac"] = _num(c.get("cac")) * 1.20

    def widen_partner_discount(c):
        if _is_partner_channel(c.get("name", "")):
            c["partner_discount_pct"] = _num(c.get("partner_discount_pct")) + 5

    def drop_retention(c):
        c["retention_rate"] = max(0.0, _num(c.get("retention_rate"), 0.85) - 0.03)

    perturb(bump_direct_cac, "Direct CAC +20%")
    perturb(widen_partner_discount, "Partner discount +5pts")
    perturb(drop_retention, "All retention -3pts")
    return scenarios


def render_markdown(report: dict, profile: str) -> str:
    lines = [
        f"# Channel Mix Optimization — profile: `{profile}`",
        "",
        "## Per-channel economics",
        "| Channel | Avg deal | Eff margin | CAC | Payback (mo) | LTV | LTV/CAC | Meets bar? |",
        "|---|---:|---:|---:|---:|---:|---:|---|",
    ]
    for m in report["metrics"]:
        if "error" in m:
            lines.append(f"| {m['name']} | — | — | — | — | — | — | ERROR: {m['error']} |")
            continue
        bar = (
            "PASS"
            if m["meets_payback_target"] and m["meets_ltv_cac_floor"]
            else ("PARTIAL" if m["meets_payback_target"] or m["meets_ltv_cac_floor"] else "FAIL")
        )
        lines.append(
            f"| {m['name']} | ,.0f | {m['effective_margin_pct']:.1f}% | "
            f",.0f | {m['payback_months']:.1f} | ,.0f | "
            f"{m['ltv_cac']:.2f}x | {bar} |"
        )
    lines.append("")

    if "best_mix" in report and report["best_mix"].get("best_mix_pct"):
        lines += ["## Recommended mix (subject to constraints)", "| Channel | Recommended share |", "|---|---:|"]
        for k, v in report["best_mix"]["best_mix_pct"].items():
            lines.append(f"| {k} | {v}% |")
        lines.append("")
    elif "best_mix" in report and report["best_mix"].get("error"):
        lines += [f"## Mix optimization", f"**{report['best_mix']['error']}**", ""]

    if report.get("sensitivity"):
        lines += ["## Sensitivity scenarios", "| Scenario | Recommended mix |", "|---|---|"]
        for s in report["sensitivity"]:
            if s.get("mix"):
                mix_str = ", ".join(f"{k}: {v}%" for k, v in s["mix"].items())
                lines.append(f"| {s['scenario']} | {mix_str} |")
            else:
                lines.append(f"| {s['scenario']} | {s.get('note') or 'no feasible mix'} |")
        lines.append("")

    lines += [
        "## Notes",
        f"- Profile `{profile}` payback target: "
        f"{PROFILES[profile]['payback_target_months']} months; LTV/CAC floor: "
        f"{PROFILES[profile]['ltv_cac_floor']:.1f}x.",
        "- Optimizer maximizes effective-ARR-weighted LTV/CAC across channels, in 5% steps.",
        "- Constraint floors / ceilings are HARD constraints — infeasible mixes are reported as errors.",
    ]
    return "\n".join(lines)


SAMPLE = {
    "profile": "saas",
    "channels": [
        {
            "name": "direct",
            "deal_count_ttm": 120,
            "arr_ttm": 6_000_000,
            "avg_deal_size": 50_000,
            "gross_margin_pct": 75,
            "cac": 18_000,
            "sales_cycle_days": 75,
            "retention_rate": 0.92,
            "expansion_rate": 1.18,
            "partner_discount_pct": 0,
        },
        {
            "name": "partner-led",
            "deal_count_ttm": 80,
            "arr_ttm": 4_000_000,
            "avg_deal_size": 50_000,
            "gross_margin_pct": 75,
            "cac": 10_000,
            "sales_cycle_days": 90,
            "retention_rate": 0.86,
            "expansion_rate": 1.08,
            "partner_discount_pct": 20,
        },
        {
            "name": "marketplace",
            "deal_count_ttm": 200,
            "arr_ttm": 1_000_000,
            "avg_deal_size": 5_000,
            "gross_margin_pct": 70,
            "cac": 1_500,
            "sales_cycle_days": 14,
            "retention_rate": 0.78,
            "expansion_rate": 1.02,
            "partner_discount_pct": 15,
        },
    ],
    "constraints": {"min_direct_pct": 30, "max_partner_concentration_pct": 50},
}


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--input")
    ap.add_argument("--output", choices=["json", "markdown"], default="markdown")
    ap.add_argument(
        "--profile",
        choices=list(PROFILES.keys()),
        default="saas",
    )
    ap.add_argument("--sample", action="store_true")
    args = ap.parse_args()

    if args.sample:
        payload = SAMPLE
    elif args.input:
        with open(args.input) as f:
            payload = json.load(f)
    else:
        ap.print_help()
        return 0

    profile = payload.get("profile", args.profile)
    if profile not in PROFILES:
        print(f"Unknown profile: {profile}", file=sys.stderr)
        return 2
    profile_cfg = PROFILES[profile]

    channels = payload.get("channels", [])
    constraints = payload.get("constraints", {}) or {}

    metrics = [compute_channel_metrics(c, profile_cfg) for c in channels]
    valid_metrics = [m for m in metrics if "error" not in m]
    best = optimize_mix(valid_metrics, constraints)
    sens = sensitivity_scenarios(channels, profile_cfg, constraints) if channels else []

    report = {"profile": profile, "metrics": metrics, "best_mix": best, "sensitivity": sens}

    if args.output == "json":
        print(json.dumps(report, indent=2))
    else:
        print(render_markdown(report, profile))
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/channel_roi_analyzer.py
#!/usr/bin/env python3
"""channel_roi_analyzer.py

Computes per-channel ROI under three lenses:
  - Cash ROI (year-1 returns / cash invested)
  - LTV ROI (returns * LTV multiplier / investment)
  - Marginal ROI (next dollar of investment, diminishing-returns curve)

Emits a verdict per channel: DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT, plus
the diminishing-returns inflection point.

Stdlib-only. Deterministic.

Usage:
    python channel_roi_analyzer.py --sample
    python channel_roi_analyzer.py --input roi.json --profile saas --output markdown
"""
from __future__ import annotations

import argparse
import json
import math
import sys
from typing import Any

# ---- Industry profiles: LTV multiplier benchmark, marginal-decay shape ----
# LTV multiplier = expected LTV / year-1 ARR (post-retention + expansion). Profile
# values are conservative midpoints from public benchmarks.
# marginal_decay_alpha = exponent k in marginal_roi = avg_roi * exp(-k * scale_idx)
# higher k = faster diminishing returns.
PROFILES = {
    "saas": {"ltv_multiplier": 3.5, "marginal_decay_alpha": 0.35, "cash_roi_target": 1.0},
    "api": {"ltv_multiplier": 4.5, "marginal_decay_alpha": 0.30, "cash_roi_target": 0.8},
    "enterprise-software": {
        "ltv_multiplier": 5.0,
        "marginal_decay_alpha": 0.25,
        "cash_roi_target": 0.6,
    },
    "marketplace": {
        "ltv_multiplier": 2.5,
        "marginal_decay_alpha": 0.45,
        "cash_roi_target": 1.2,
    },
    "hardware": {
        "ltv_multiplier": 1.8,
        "marginal_decay_alpha": 0.50,
        "cash_roi_target": 1.5,
    },
}


def _num(v: Any, default: float = 0.0) -> float:
    try:
        return float(v)
    except (TypeError, ValueError):
        return default


def compute_channel_roi(channel: dict, profile_cfg: dict) -> dict:
    name = channel.get("channel", "unnamed")
    inv = channel.get("investment_ttm", {}) or {}
    ret = channel.get("returns_ttm", {}) or {}

    invested = sum(
        _num(inv.get(k))
        for k in ("programs", "headcount_cost", "partner_program_cost", "mdf", "tooling", "training")
    )
    new_arr = _num(ret.get("new_arr"))
    exp_arr = _num(ret.get("expansion_arr"))
    retained_arr = _num(ret.get("retained_arr_attributable"))
    returns_y1 = new_arr + exp_arr + retained_arr

    if invested <= 0:
        return {"channel": name, "error": "investment_ttm sum must be > 0"}

    # Cash ROI (year-1)
    cash_roi = returns_y1 / invested

    # LTV ROI — apply profile multiplier to recurring portion (new + expansion). Retained
    # is already recurring so we don't double-count.
    ltv_returns = (new_arr + exp_arr) * profile_cfg["ltv_multiplier"] + retained_arr
    ltv_roi = ltv_returns / invested

    # Marginal ROI — diminishing returns. Model: marginal = avg * exp(-alpha * scale_idx)
    # where scale_idx is log10(invested / 100k) clamped >= 0. Inflection = scale at which
    # marginal_roi drops to 1.0 (a dollar in returns a dollar — no profit).
    alpha = profile_cfg["marginal_decay_alpha"]
    scale_idx = max(0.0, math.log10(max(invested, 1.0) / 100_000.0))
    marginal_roi = cash_roi * math.exp(-alpha * scale_idx)

    # Inflection: solve cash_roi * exp(-alpha * x) = 1.0 -> x = ln(cash_roi)/alpha
    if cash_roi > 1.0:
        inflection_scale = math.log(cash_roi) / alpha
        inflection_invested = 100_000.0 * (10 ** inflection_scale)
    else:
        inflection_invested = invested  # already past the inflection

    # Verdict logic — deterministic
    target = profile_cfg["cash_roi_target"]
    if cash_roi >= target * 1.5 and ltv_roi >= 3.0 and marginal_roi >= 1.0:
        verdict = "DOUBLE-DOWN"
        rationale = (
            "Cash ROI > 1.5x target, LTV ROI ≥ 3.0x, marginal ROI > 1.0 — "
            "next dollar still earns positive return. Invest more."
        )
    elif cash_roi >= target and ltv_roi >= 2.0:
        verdict = "MAINTAIN"
        rationale = (
            "Cash ROI meets target and LTV ROI ≥ 2.0x. Hold current investment; "
            "monitor marginal ROI before increasing."
        )
    elif cash_roi >= target * 0.5 or ltv_roi >= 1.5:
        verdict = "DEFUND"
        rationale = (
            "Sub-target cash ROI. LTV ROI may be supportive but not enough to justify "
            "current spend. Cut investment 30-50% and reassess in 2 quarters."
        )
    else:
        verdict = "EXIT"
        rationale = (
            "Both cash ROI and LTV ROI below floor. Channel is value-destroying at "
            "current load. Exit or restructure the program."
        )

    return {
        "channel": name,
        "invested_ttm": round(invested, 2),
        "returns_y1": round(returns_y1, 2),
        "cash_roi": round(cash_roi, 3),
        "ltv_roi": round(ltv_roi, 3),
        "marginal_roi": round(marginal_roi, 3),
        "inflection_invested": round(inflection_invested, 2),
        "verdict": verdict,
        "rationale": rationale,
        "profile_target_cash_roi": target,
    }


def render_markdown(results: list, profile: str) -> str:
    lines = [
        f"# Channel ROI Analysis — profile: `{profile}`",
        "",
        "## Per-channel verdicts",
        "| Channel | Invested | Returns Y1 | Cash ROI | LTV ROI | Marginal ROI | Inflection | Verdict |",
        "|---|---:|---:|---:|---:|---:|---:|---|",
    ]
    for r in results:
        if "error" in r:
            lines.append(f"| {r['channel']} | — | — | — | — | — | — | ERROR: {r['error']} |")
            continue
        lines.append(
            f"| {r['channel']} | ,.0f | ,.0f | "
            f"{r['cash_roi']:.2f}x | {r['ltv_roi']:.2f}x | {r['marginal_roi']:.2f}x | "
            f",.0f | **{r['verdict']}** |"
        )
    lines += ["", "## Verdict rationale"]
    for r in results:
        if "error" in r:
            continue
        lines += [f"### {r['channel']} — {r['verdict']}", r["rationale"], ""]

    lines += [
        "## Definitions",
        "- **Cash ROI** = year-1 returns / cash invested. Profile target shown above.",
        "- **LTV ROI** = (new+expansion ARR × LTV multiplier + retained ARR) / invested.",
        "- **Marginal ROI** = ROI on the next dollar of investment, modeled via "
        "`avg_roi × exp(-alpha × log10(invested / $100k))`. Profile-tuned alpha.",
        "- **Inflection** = invested-$ level at which marginal ROI hits 1.0 (break-even on "
        "the next dollar). Beyond this point, additional spend destroys value.",
    ]
    return "\n".join(lines)


SAMPLE = {
    "profile": "saas",
    "channels": [
        {
            "channel": "direct",
            "investment_ttm": {
                "programs": 200_000,
                "headcount_cost": 1_600_000,
                "partner_program_cost": 0,
                "mdf": 0,
                "tooling": 80_000,
                "training": 60_000,
            },
            "returns_ttm": {
                "new_arr": 3_800_000,
                "expansion_arr": 900_000,
                "retained_arr_attributable": 2_400_000,
            },
        },
        {
            "channel": "partner-led",
            "investment_ttm": {
                "programs": 150_000,
                "headcount_cost": 360_000,
                "partner_program_cost": 280_000,
                "mdf": 120_000,
                "tooling": 30_000,
                "training": 80_000,
            },
            "returns_ttm": {
                "new_arr": 1_400_000,
                "expansion_arr": 200_000,
                "retained_arr_attributable": 900_000,
            },
        },
        {
            "channel": "marketplace",
            "investment_ttm": {
                "programs": 60_000,
                "headcount_cost": 120_000,
                "partner_program_cost": 0,
                "mdf": 0,
                "tooling": 40_000,
                "training": 0,
            },
            "returns_ttm": {
                "new_arr": 200_000,
                "expansion_arr": 40_000,
                "retained_arr_attributable": 80_000,
            },
        },
    ],
}


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--input", help="Path to JSON input file")
    ap.add_argument("--output", choices=["json", "markdown"], default="markdown")
    ap.add_argument(
        "--profile",
        choices=list(PROFILES.keys()),
        default="saas",
        help="Industry profile (tunes LTV multiplier + marginal-decay alpha)",
    )
    ap.add_argument("--sample", action="store_true")
    args = ap.parse_args()

    if args.sample:
        payload = SAMPLE
    elif args.input:
        with open(args.input) as f:
            payload = json.load(f)
    else:
        ap.print_help()
        return 0

    profile = payload.get("profile", args.profile)
    if profile not in PROFILES:
        print(f"Unknown profile: {profile}", file=sys.stderr)
        return 2
    profile_cfg = PROFILES[profile]

    channels = payload.get("channels", [])
    if not channels and "channel" in payload:
        channels = [payload]

    results = [compute_channel_roi(c, profile_cfg) for c in channels]
    if args.output == "json":
        print(json.dumps({"profile": profile, "results": results}, indent=2))
    else:
        print(render_markdown(results, profile))
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/cost_to_serve_calculator.py
#!/usr/bin/env python3
"""cost_to_serve_calculator.py

Computes fully-loaded cost-to-serve per deal AND per dollar of ARR for a
single channel. Breaks out direct vs. allocated overhead. Surfaces "hidden"
costs the average team forgets (partner enablement time, certification
investment, channel-conflict overhead) by flagging line items left at $0.

Stdlib-only. Deterministic.

Usage:
    python cost_to_serve_calculator.py --sample
    python cost_to_serve_calculator.py --input channel.json --output markdown
"""
from __future__ import annotations

import argparse
import json
import sys
from typing import Any

# ---- Hidden-cost line items (most-forgotten) -----------------------------
HIDDEN_COST_KEYS = {
    "partner_enablement_time": "Partner enablement time (AE/SE hours co-selling)",
    "certification_investment": "Partner certification + training investment",
    "channel_conflict_overhead": "Channel-conflict resolution overhead",
    "channel_manager_attribution": "Channel manager headcount attribution",
}

# ---- Cost categories -----------------------------------------------------
DIRECT_COST_KEYS = [
    "sdr_attribution",
    "ae_attribution",
    "sales_engineer_attribution",
    "channel_manager_attribution",
    "customer_success_attribution",
    "support_attribution",
    "marketing_attribution",
    "partner_discount",
    "partner_MDF",
    "partner_enablement_time",
    "certification_investment",
    "channel_conflict_overhead",
    "tooling_attribution",
]


def _num(v: Any, default: float = 0.0) -> float:
    try:
        return float(v)
    except (TypeError, ValueError):
        return default


def compute_cost_to_serve(payload: dict) -> dict:
    channel_name = payload.get("channel_name", "unnamed-channel")
    deal_volume = _num(payload.get("deal_volume"), 0)
    gross_revenue = _num(payload.get("gross_revenue"), 0)
    costs = payload.get("costs", {}) or {}

    if deal_volume <= 0 or gross_revenue <= 0:
        return {
            "error": "deal_volume and gross_revenue must both be > 0",
            "channel_name": channel_name,
        }

    # Direct costs (sum)
    direct_total = 0.0
    direct_breakdown = {}
    for key in DIRECT_COST_KEYS:
        v = _num(costs.get(key), 0)
        direct_breakdown[key] = v
        direct_total += v

    # Allocated overhead — applied as % of gross revenue
    overhead_pct = _num(costs.get("overhead_allocation_pct"), 0)
    if overhead_pct < 0 or overhead_pct > 100:
        return {
            "error": f"overhead_allocation_pct must be 0..100, got {overhead_pct}",
            "channel_name": channel_name,
        }
    overhead_total = gross_revenue * (overhead_pct / 100.0)

    total_loaded_cost = direct_total + overhead_total

    cost_per_deal = total_loaded_cost / deal_volume
    cost_per_arr_dollar = total_loaded_cost / gross_revenue
    true_gross_margin_pct = (1.0 - cost_per_arr_dollar) * 100.0

    # Hidden-cost surfacing — flag any HIDDEN_COST_KEYS that are $0
    hidden_flags = []
    for k, label in HIDDEN_COST_KEYS.items():
        if direct_breakdown.get(k, 0) == 0:
            hidden_flags.append(
                f"'{k}' is $0 — likely understated. {label} is the most-forgotten "
                "channel cost in industry benchmarks."
            )

    # Double-counting validation
    warnings = []
    if (
        direct_breakdown.get("partner_discount", 0) > 0
        and direct_breakdown.get("partner_MDF", 0) > 0
        and direct_breakdown.get("partner_MDF", 0) > direct_breakdown.get("partner_discount", 0)
    ):
        warnings.append(
            "MDF spend exceeds partner discount — verify MDF is not double-counted "
            "as discount in your channel agreements."
        )
    if overhead_pct > 50:
        warnings.append(
            f"Overhead allocation of {overhead_pct:.1f}% is unusually high. "
            "Verify denominator (revenue vs. gross profit) is consistent across channels."
        )
    if overhead_pct < 5 and "partner" in channel_name.lower():
        warnings.append(
            f"Partner channel overhead allocation of {overhead_pct:.1f}% is unusually low. "
            "Channel manager, partner program, certification all live in YOUR P&L. "
            "Inconsistent allocation is the #1 source of false partner-margin lift."
        )

    return {
        "channel_name": channel_name,
        "deal_volume": deal_volume,
        "gross_revenue": gross_revenue,
        "direct_breakdown": direct_breakdown,
        "direct_total": round(direct_total, 2),
        "overhead_allocation_pct": overhead_pct,
        "overhead_total": round(overhead_total, 2),
        "total_loaded_cost": round(total_loaded_cost, 2),
        "cost_per_deal": round(cost_per_deal, 2),
        "cost_per_arr_dollar": round(cost_per_arr_dollar, 4),
        "true_gross_margin_pct": round(true_gross_margin_pct, 2),
        "hidden_cost_flags": hidden_flags,
        "warnings": warnings,
    }


def render_markdown(r: dict) -> str:
    if "error" in r:
        return f"# Cost-to-Serve\n\n**ERROR**: {r['error']}\n"

    lines = [
        f"# Cost-to-Serve — {r['channel_name']}",
        "",
        "## Inputs",
        f"- Deal volume (TTM): **{r['deal_volume']:,.0f}**",
        f"- Gross revenue (TTM): **,.0f**",
        f"- Overhead allocation: **{r['overhead_allocation_pct']:.1f}%**",
        "",
        "## Direct cost breakdown",
        "| Line item | $ |",
        "|---|---:|",
    ]
    for k, v in r["direct_breakdown"].items():
        lines.append(f"| {k} | {v:,.0f} |")
    lines += [
        f"| **Direct total** | **{r['direct_total']:,.0f}** |",
        f"| Allocated overhead | {r['overhead_total']:,.0f} |",
        f"| **Total loaded cost** | **{r['total_loaded_cost']:,.0f}** |",
        "",
        "## Result",
        f"- Cost-to-serve **per deal**: **,.2f**",
        f"- Cost-to-serve **per $ ARR**: **.4f**",
        f"- **True gross margin** (after channel-specific load): **{r['true_gross_margin_pct']:.2f}%**",
        "",
    ]
    if r["hidden_cost_flags"]:
        lines.append("## Hidden-cost flags")
        for f in r["hidden_cost_flags"]:
            lines.append(f"- {f}")
        lines.append("")
    if r["warnings"]:
        lines.append("## Warnings")
        for w in r["warnings"]:
            lines.append(f"- {w}")
        lines.append("")
    return "\n".join(lines)


SAMPLE = {
    "channel_name": "partner-led-EMEA",
    "deal_volume": 80,
    "gross_revenue": 4_000_000,
    "costs": {
        "sdr_attribution": 60_000,
        "ae_attribution": 240_000,
        "sales_engineer_attribution": 90_000,
        "channel_manager_attribution": 180_000,
        "customer_success_attribution": 120_000,
        "support_attribution": 70_000,
        "marketing_attribution": 50_000,
        "partner_discount": 600_000,
        "partner_MDF": 80_000,
        "partner_enablement_time": 40_000,
        "certification_investment": 20_000,
        "channel_conflict_overhead": 15_000,
        "tooling_attribution": 25_000,
        "overhead_allocation_pct": 15.0,
    },
}


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--input", help="Path to JSON input file")
    ap.add_argument("--output", choices=["json", "markdown"], default="markdown")
    ap.add_argument("--sample", action="store_true", help="Run with embedded sample")
    args = ap.parse_args()

    if args.sample:
        payload = SAMPLE
    elif args.input:
        with open(args.input) as f:
            payload = json.load(f)
    else:
        ap.print_help()
        return 0

    result = compute_cost_to_serve(payload)
    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(render_markdown(result))
    return 0


if __name__ == "__main__":
    sys.exit(main())

---
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

FILE:references/anonymization-protocol.md
# 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.