@vextlabs/theron-cli 0.3.0 → 0.4.0

package/skills/term-sheet.md

@@ -0,0 +1,298 @@
+---
+name: term-sheet
+description: Analyze a venture-capital or angel term sheet — decompose economics vs. control provisions, step-by-step dilution math (option-pool shuffle, SAFE conversion, liquidation waterfall, anti-dilution), flag founder-unfriendly deviations from NVCA/YC market standard, and surface negotiation priorities; outputs a structured red/yellow/green memo with a NOT LEGAL ADVICE footer.
+allowed-tools: Read, Bash, Write
+---
+
+KEY PRINCIPLE: Every dollar of economics and every vote of control is negotiable before signing. The founder who internalizes the waterfall math, the option-pool shuffle cost, and the board-composition arithmetic will always negotiate better than the one who reads only the headline valuation. Understand the instrument first; negotiate second.
+
+═══ HARD RULES ═══
+1. NEVER state a legal conclusion as fact ("this clause is unenforceable") — flag it as a risk and direct the founder to verify with qualified counsel.
+2. NEVER invent cap-table numbers, valuations, or market-standard percentages as if ground truth; show your arithmetic and label every assumption explicitly.
+3. Do not conflate pre-money and post-money valuation — one sentence must explicitly re-anchor which basis is in use before any math.
+4. Do not skip the option-pool-shuffle calculation; it is almost always present and almost always disadvantages founders silently.
+5. Do not summarize control provisions as "standard" without confirming against the specific NVCA model documents or stated investor standard.
+6. Flag every defined term that is used in economics without being defined in the term sheet itself (e.g., "Fully Diluted" without a definition, "Qualified Financing" without a dollar threshold).
+7. If the instrument is a SAFE or convertible note, complete Phase B-SAFE before Phase B — the conversion math must be resolved before any preferred-round dilution analysis.
+8. Close every analysis with the NOT LEGAL ADVICE disclaimer (Phase E7); never omit it.
+
+═══ PHASE A — INTAKE & DOCUMENT MAP ═══
+A1. Read the term sheet verbatim; build a term inventory table:
+    | Term | Section | Value/Text | Type (Econ / Control / Both / Admin) |
+
+A2. Identify the round structure:
+    - Series (Seed/A/B) or pre-money SAFE / post-money SAFE / convertible note
+    - Security type: convertible note, SAFE (pre-money vs. post-money), or priced preferred equity
+    - Lead investor, total raise, pro-rata reserved amount, and closing mechanics
+    - SAFEs or notes converting in this round — list each with: principal, discount rate, valuation cap, MFN clause, and interest accrued
+
+A3. Flag any undefined capitalized terms that carry economic or control weight.
+    Common offenders: "Fully Diluted," "Qualified Financing," "Qualified IPO," "Material Adverse Change."
+
+A4. Note which law firm authored it and which NVCA model version (if stated) — this sets
+    the baseline for "market" comparisons. Absence of a stated standard is itself a flag.
+
+═══ PHASE B-SAFE — SAFE / CONVERTIBLE NOTE CONVERSION (run before Phase B if applicable) ═══
+Skip this phase only if the round is a first-close priced equity with no converting instruments.
+
+S1. FOR EACH SAFE OR NOTE, compute conversion shares:
+    Post-money SAFE (YC standard post-2018):
+      Conversion shares = SAFE investment amount / conversion price
+      Conversion price  = MIN(valuation cap / post-money cap-table shares, price per share in round × (1 − discount%))
+      Post-money cap-table shares = all shares outstanding AFTER the new round closes INCLUDING the SAFE conversion pool
+
+    Pre-money SAFE (YC pre-2018) or convertible note:
+      Conversion price  = MIN(cap / pre-money fully-diluted shares, price per share × (1 − discount%))
+      Note: add accrued interest to principal before applying conversion formula for notes.
+
+S2. MFN CLAUSE: If a SAFE has MFN, confirm whether the current round terms trigger an amendment.
+    Flag if the MFN is uncapped (no floor on what terms the investor can claim).
+
+S3. Build a pre-round SAFE conversion table:
+    | Instrument | Principal + Interest | Cap | Discount | Conversion Price | Shares Issued | % FD Post |
+
+S4. Flag: post-money SAFEs issued on different caps stack against the SAME post-money denominator —
+    they do not dilute each other, they dilute founders and employees proportionally.
+    Show the aggregate SAFE dilution as a single % before the new money enters.
+
+═══ PHASE B — ECONOMICS DECOMPOSITION ═══
+B1. PRE-MONEY / POST-MONEY ANCHOR
+    - State explicitly: post-money = pre-money + new investment (NOT including converting SAFEs/notes
+      unless investor explicitly states they are included — this is a frequent source of disagreement).
+    - Identify whether the option pool is carved from pre-money (founder-dilutive — the shuffle) or
+      post-money (investor bears proportionate cost — rare but exists).
+
+B2. OPTION-POOL SHUFFLE — STEP-BY-STEP MATH
+    The "option-pool shuffle" occurs when an investor sets the pre-money valuation assuming the
+    option pool is already fully funded. Because the pool is created before money goes in, the
+    shares come from founders, not from the new investor's money.
+
+    Pool shares needed = target post-close FD shares × target pool %
+    NOTE: the denominator (post-close FD shares) must include SAFE conversion shares from Phase B-SAFE.
+
+    Populate this template with actual numbers:
+        Stated pre-money:                   $________
+        New investment:                     $________
+        Post-money:                         $________ (= pre + new)
+        Pool target (% of post-close FD):   ____%
+        Post-close FD shares (est):         ________  (founders + existing + SAFEs converted + new investors + new pool)
+        New pool shares created:            ________  (= post-close FD × pool %)
+        Existing unallocated pool:          ________
+        Incremental pool shares:            ________  (= new pool − existing unallocated)
+        Price per share:                    $________  (= pre-money / [pre-close FD shares INCLUDING incremental pool])
+        Dollar cost of shuffle to founders: $________  (= incremental pool shares × price per share)
+        Effective pre-money founders see:   $________  (= stated pre-money − shuffle cost)
+
+    Conclusion: explicitly state who bears the shuffle cost and by how many percentage points it
+    shifts effective ownership away from founders.
+
+B3. OWNERSHIP TABLE — FULLY DILUTED POST-CLOSE
+    Build the cap table post-close including: founders, existing investors (common + preferred),
+    SAFE/note holders (converted), new investors, and option pool (full target size).
+    Show % before and after the round on a fully-diluted basis.
+    | Holder | Pre-round shares | New / converted shares | Post-round shares | % FD |
+
+B4. PRICE PER SHARE & EFFECTIVE DILUTION PER FOUNDER
+    - Price per share = pre-money valuation / pre-close fully-diluted shares
+      CRITICAL: pre-close FD shares must include the incremental pool from B2 (post-shuffle denominator).
+      If you use pre-shuffle shares in the denominator, the price will be overstated.
+    - Each founder's dilution = new investor % + option shuffle % + SAFE conversion % allocated by ownership.
+
+B5. LIQUIDATION WATERFALL — STEP-BY-STEP
+    Model three scenarios: (1) exit at 1× the total raise, (2) exit at 2×, (3) exit at 5×.
+    For each scenario execute these steps in order:
+
+      Step 1 — Pay senior debt, transaction expenses, and any redemption obligations.
+      Step 2 — Apply liquidation preference in seniority order (most recent series first unless pari passu):
+        Non-participating preferred:
+          Investor receives preference (= 1× or stated multiple × invested capital) OR converts to common,
+          whichever produces the higher proceeds. Compute the crossover point explicitly.
+        Participating preferred (no cap):
+          Investor receives preference AND retains pro-rata common equivalent shares.
+          Participation amount = (investor common-equivalent % × remainder after preference).
+        Capped participating preferred:
+          Investor receives preference + participation up to cap (typically 2×–3× invested).
+          At the cap crossover, preferred converts to common automatically — compute this threshold:
+            Crossover proceeds = cap amount / investor fully-diluted %
+          Below crossover: participating preferred formula applies.
+          Above crossover: investor acts as common; recompute all distributions.
+      Step 3 — Distribute remainder to common (founders + vested option pool).
+      Step 4 — Build a proceeds table for each scenario:
+        | Scenario | Total Proceeds | Investor Preference | Investor Participation | Investor Total | Founder Total | Pool Total | Investor IRR |
+    - Flag any stacked preferences (multiple series) and model them in strict seniority order.
+    - Flag if any series carries a multiple > 1× (e.g., 2× non-participating) — highly investor-favorable.
+
+B6. ANTI-DILUTION PROVISION
+    - Identify: broad-based weighted-average (BBWA), narrow-based (NBWA), or full ratchet.
+    - BBWA is the current NVCA market standard for Series A+; full ratchet is heavily investor-favorable.
+    - BBWA adjusted conversion price formula:
+        CP2 = CP1 × (A + B) / (A + C)
+        where:
+          A = total common-equivalent shares outstanding immediately before the down round
+          B = aggregate consideration received in the down round / CP1  (i.e., shares that WOULD have been issued at original price)
+          C = actual new shares issued in the down round at the lower price
+    - Show the resulting new conversion price and recomputed ownership for a hypothetical 50% down-round.
+    - Flag if SAFEs or earlier notes reset their conversion price on anti-dilution — this compounds dilution.
+
+B7. DIVIDEND RIGHTS
+    - Cumulative vs. non-cumulative; simple vs. compounding.
+    - Non-cumulative non-participating = market (effectively a formality).
+    - If cumulative: compute accrual over 3 / 5 / 7 years at stated rate and show how it affects
+      the liquidation waterfall (accrued dividends typically add to the preference amount in Step 2).
+
+═══ PHASE C — CONTROL PROVISIONS ═══
+C1. BOARD COMPOSITION
+    - Map: current board → post-close board → any future trigger that shifts control.
+    - Flag: do founders retain majority at close? At Series B dilution levels?
+    - Identify the tie-breaking mechanism and who controls it.
+    - Market for Series A: 2 founder seats / 2 investor seats / 1 mutual independent.
+    - OBSERVER SEATS: flag any observer seat granted beyond formal director seats.
+      Observers receive board materials, attend meetings, and exert social pressure even without votes.
+      More than 1 observer seat per investor is founder-unfriendly; observer rights should expire on
+      IPO/acquisition and carry standard confidentiality obligations.
+
+C2. PROTECTIVE PROVISIONS (INVESTOR VETO RIGHTS)
+    - List every action requiring preferred-holder approval.
+    - NVCA market scope (flag anything beyond this list as potentially over-broad):
+        1. Amendments to charter or bylaws adversely affecting preferred
+        2. Issuance of securities senior or pari passu to preferred
+        3. Redemption or repurchase of common (other than standard repurchase rights)
+        4. Declaration of dividends
+        5. Liquidation, dissolution, or wind-down
+        6. Change of business materially outside the current scope
+        7. Sale, merger, or acquisition of the company
+    - Flag specifically: blocking acquisitions below a stated multiple (e.g., "below 3× invested"),
+      blocking new hires above a salary threshold, or requiring approval for budget variances >X%.
+      These are operational veto rights that go beyond standard protective provisions.
+
+C3. DRAG-ALONG
+    - Who triggers drag? (majority preferred alone = bad; majority preferred + majority common = market)
+    - Is there a minimum price floor? A fiduciary-duty carve-out for the board?
+    - Flag if drag can be triggered at a price below the liquidation preference (investor drags founders
+      to a zero-proceeds exit for founders while collecting their preference).
+
+C4. INFORMATION RIGHTS & INSPECTION
+    - Quarterly / annual financials, budget approval, inspection rights — standard.
+    - Flag: real-time system access, daily reporting obligations, or audit rights exercisable more than
+      once per year are operationally burdensome and unusual outside distressed situations.
+    - Flag if information rights do not terminate on IPO — they should.
+
+C5. RIGHT OF FIRST REFUSAL (ROFR) & CO-SALE (TAG-ALONG)
+    - ROFR on founder secondary sales: market.
+    - Company ROFR exercises before investor ROFR: market.
+    - Flag if ROFR applies to all common transfers generally (not just founders) — unusual scope.
+    - Co-sale: investor right to participate pro-rata in any founder secondary sale — market.
+    - Flag if co-sale right does not terminate on IPO.
+
+C6. PRO-RATA RIGHTS
+    - Right to participate in future rounds up to ownership % — market for "major investors" above
+      a defined threshold (e.g., $500K+ invested).
+    - Super pro-rata (right to invest MORE than ownership %) is investor-favorable; flag and quantify
+      the dilutive impact on founders if the investor exercises in a flat or down round.
+
+C7. PAY-TO-PLAY
+    - Does non-participation in future rounds cause automatic conversion of preferred to common
+      or shadow preferred? Flag if absent at Series B+ — pay-to-play actually benefits founders by
+      forcing investors to support the company or lose their preference.
+    - Flag if the pay-to-play threshold is set so high that only the lead can realistically meet it.
+
+C8. NO-SHOP & EXCLUSIVITY
+    - Duration: 30–45 days = market; 60+ days = flag; 90+ days = negotiate hard.
+    - Carve-outs for responding to unsolicited offers? For existing discussions already disclosed?
+    - Flag if no-shop binds the company's advisors (bankers, lawyers) in addition to the company.
+
+C9. FOUNDER VESTING & ACCELERATION
+    - Market: 4-year total / 1-year cliff / monthly vesting thereafter.
+    - Credit for time served pre-close: market to receive partial or full credit; flag if zero credit offered.
+    - Single-trigger acceleration (change of control alone): investor-unfriendly — acquirer can demand
+      clawback or discount purchase price.
+    - Double-trigger acceleration (change of control + termination without cause or constructive dismissal
+      within 12 months): market standard; flag if absent.
+    - Flag if investors are requesting reverse vesting on shares already fully vested — this is unusual
+      and represents a significant founder value transfer.
+
+C10. REDEMPTION RIGHTS
+    - Flag if present — redeemable preferred is rare in standard VC-backed startups.
+    - Signals: bridge financing at distressed terms, strategic investor with a put right, or
+      a structure designed to force an exit at the investor's preferred timing.
+    - If present, compute the redemption price at years 3, 5, and 7 (including accrued dividends)
+      and the cash burden on the company.
+
+C11. REPRESENTATIONS, WARRANTIES & DISCLOSURE
+    - Identify any founder representations (as distinct from company representations).
+    - Flag personal indemnification obligations that survive closing without a cap or survival limit.
+    - Flag if the term sheet requires disclosure schedules by a date earlier than 5 business days
+      before closing — inadequate time creates warranty breach exposure.
+
+═══ PHASE D — RED / YELLOW / GREEN SCORING ═══
+D1. For each provision in Phases B and C, assign:
+    RED    — materially founder-unfriendly vs. NVCA/YC market standard; negotiate hard before accepting.
+    YELLOW — present in some deals but worth pushing back; pick your battles based on leverage.
+    GREEN  — market standard; accept without friction and preserve goodwill for RED items.
+
+D2. Output a consolidated scorecard:
+    | Provision | Classification | Deviation from Market | Dollar/Vote Impact | Negotiation Priority |
+
+D3. Rank the top 3 non-economic terms the founder should prioritize in negotiation.
+    Typical hierarchy (context-dependent): board composition and tie-breaking > drag-along trigger and
+    price floor > founder vesting credit for time served > scope of protective provisions.
+
+D4. Identify the single highest-value economic improvement available. Quantify the dollar impact
+    at each exit scenario from Phase B5.
+    Typical candidates:
+    - Removing participation from participating preferred (converts to non-participating)
+    - Shrinking the option-pool shuffle by reducing post-close pool size or deferring creation
+    - Removing a liquidation preference multiple above 1×
+    - Converting full ratchet to BBWA anti-dilution
+
+D5. Identify one trade worth offering: a provision the founder is willing to concede that costs
+    the investor little to receive but preserves founder value where it matters most.
+    Example: concede quarterly reporting cadence in exchange for removing the participation right.
+
+═══ PHASE E — FINAL MEMO FORMAT ═══
+KEY PRINCIPLE BEFORE WRITING: Structure the memo for a founder who has 30 minutes before a call
+with the investor. Prioritize ruthlessly. Do not bury the RED items in section 4.
+
+E1. Executive Summary (3–5 bullets):
+    - Effective pre-money (after shuffle and SAFE conversion)
+    - Founder ownership % post-close (fully diluted)
+    - Liquidation preference stack and participation structure
+    - Control posture (board majority? veto scope?)
+    - Single top risk and single top opportunity
+
+E2. Economics section with all math shown (Phases B1–B7 and B-SAFE).
+
+E3. Control section, provision-by-provision (Phase C), in order of RED → YELLOW → GREEN.
+
+E4. Red/Yellow/Green scorecard (Phase D).
+
+E5. Negotiation playbook:
+    PUSH HARD (RED items — these are your opening positions):
+    - List each RED item with: what you ask for, the market standard you cite, and why it matters.
+    TRADE (YELLOW items — concede these to win the RED items):
+    - List each Yellow item you will concede and what you expect in return.
+    ACCEPT WITHOUT COMMENT (GREEN items):
+    - List Green items; accepting quickly signals reasonableness and builds goodwill.
+    INVESTOR RESPONSE PATTERNS TO ANTICIPATE:
+    - "This is our standard document" → response: "I understand; counsel has flagged [specific RED item]
+      as outside NVCA market — here is the market language."
+    - "Everyone accepts participating preferred at Series A" → response: "YC's Series A standard and the
+      NVCA model both use non-participating; here is the crossover math showing the founder impact."
+    - "The option pool size is non-negotiable" → response: "Understood on size; can we agree the pool
+      is created post-close rather than pre-close to eliminate the shuffle?"
+
+E6. Open questions for the investor / counsel before signing:
+    - List undefined capitalized terms from A3 requiring definition.
+    - List any math that requires the actual cap table to verify (e.g., exact SAFE conversion shares).
+    - List any representations or disclosure obligations requiring legal review.
+
+E7. Footer (mandatory, verbatim):
+
+    ─────────────────────────────────────────────────────────────────
+    NOT LEGAL ADVICE. This analysis is for informational and
+    illustrative purposes only. It does not constitute legal,
+    tax, or financial advice and does not create an attorney-client
+    relationship. All math is based on stated assumptions and should
+    be independently verified. Consult qualified legal counsel before
+    signing any financing document.
+    ─────────────────────────────────────────────────────────────────

package/skills/theory-of-change.md

@@ -0,0 +1,88 @@
+---
+name: theory-of-change
+description: Build a rigorous theory of change for a program, product, or initiative: map the long-term impact goal backward through causal preconditions to activities, make every causal arrow's assumptions explicit and testable, assign indicators per outcome, and cite the evidence base that validates each assumption — invoked when asked to develop, stress-test, or document a theory of change, logic model, impact pathway, or results framework.
+allowed-tools: Read, Write
+---
+
+═══ HARD RULES ═══
+1. NEVER state an assumption as a fact. Every causal arrow carries an explicit assumption; label it [ASSUMPTION].
+2. NEVER invent statistics, citations, or effect sizes to validate assumptions. State "evidence: weak / moderate / strong / empirical gap" with a one-line rationale; leave gaps visible so the team knows what to test.
+3. NEVER conflate outputs (what you produced) with outcomes (what changed in the world). Outputs are deliverables. Outcomes are behavioral or systemic shifts. Impact is long-run change at population, market, or system scale.
+4. NEVER skip the backward-mapping pass (Phase A). Building the forward chain first produces activity-driven rationalization, not a causal theory.
+5. NEVER omit a counterfactual check: for each outcome, ask what would have happened without the intervention. If the answer is "the same," the activity is not load-bearing.
+6. One theory of change per distinct target population, user segment, or causal mechanism. If two segments have different preconditions, write two chains.
+7. Indicators must be SMART (specific, measurable, attributable to this intervention, relevant to the outcome, time-bound). Reject vague proxies such as "increased awareness," "better engagement," or "improved outcomes."
+8. Stress-test every assumption in Phase D before declaring the theory complete. A theory with zero challenged assumptions has not been examined.
+9. At Phase A, identify the domain type and let it govern timeframes, actor vocabulary, and evidence standards throughout — do not impose social-sector framing on a product or policy context, nor product-cycle framing on a systems-change initiative.
+
+═══ PHASE A — ANCHOR THE LONG-TERM IMPACT GOAL ═══
+A1. State the impact goal in one sentence: WHO experiences WHAT change BY WHEN at WHAT SCALE.
+    Format: "By [year/horizon], [population / user segment / market] will experience [measurable systemic, behavioral, or market-structural change] at [scale/geography/scope]."
+A2. Identify the domain type. This governs all downstream vocabulary, timeframes, and evidence standards:
+    - SOCIAL/POLICY: target population, systemic change, 5–15 year horizon, RCT / quasi-experimental evidence standard, equity and exclusion checks mandatory.
+    - PRODUCT/MARKET: user segment, adoption and retention curves, 1–3 year horizon, A/B and cohort evidence standard, competitive displacement and switching-cost checks mandatory.
+    - ORGANIZATIONAL/INTERNAL: team or process, capability or culture shift, 1–2 year horizon, before/after operational metrics, dependency and change-fatigue checks mandatory.
+    If the initiative spans domains, state the primary domain and note where secondary-domain logic applies.
+A3. Identify the system this goal sits inside (economic, regulatory, ecological, social, competitive market, organizational). Name it explicitly — it defines what counts as a precondition versus a confound.
+A4. State the counterfactual: what does the system default to without this intervention? This is the baseline against which attribution is measured. For a product: what do users do today, and what alternatives exist? For a policy: what is the status quo trajectory?
+A5. Identify 2–4 alternative pathways that could also reach the same impact goal (competitor theories or approaches). State why yours is preferred — mechanism, feasibility, cost, evidence — or acknowledge it is not yet preferred and explain the bet.
+
+═══ PHASE B — BACKWARD-MAP THE CAUSAL PRECONDITIONS ═══
+B1. Starting from the impact goal, ask: "For this to be true, what must be true one step earlier?" Write that as an intermediate outcome. Repeat until you reach conditions your activities can directly influence. This is the theory's spine.
+B2. For each arrow between preconditions, write the [ASSUMPTION] explicitly:
+    "[Precondition N] leads to [Precondition N+1] ASSUMING [specific mechanism, behavioral pattern, market condition, or institutional context]."
+    Domain examples:
+    - Product: "Users who complete onboarding will return within 7 days ASSUMING the core action delivers perceived value on first use."
+    - Social program: "Skill training completion leads to wage gain ASSUMING local labor markets have unfilled demand at that skill level."
+    - Policy: "Regulatory change leads to market entry ASSUMING compliance costs drop below the profit threshold for new entrants."
+B3. Rate each assumption on two axes:
+    - Plausibility (low / medium / high) — based on mechanistic reasoning, not hope.
+    - Evidence base (empirical gap / weak / moderate / strong) — cite source type (RCT, quasi-experimental, cohort study, A/B test, case study, expert consensus, theoretical only). No invented citations.
+B4. Flag load-bearing assumptions: any assumption rated low plausibility OR empirical gap that sits on the critical path is a risk node. Mark [RISK NODE]. These require either evidence-gathering or design mitigation before launch.
+B5. Check for missing preconditions: for each arrow, ask whether additional enabling conditions must hold simultaneously (infrastructure access, regulatory permission, organizational capacity, market liquidity, user literacy, financing). If yes, add them as parallel preconditions feeding the same arrow.
+
+═══ PHASE C — BUILD THE FORWARD ACTIVITIES → OUTPUTS → OUTCOMES → IMPACT CHAIN ═══
+C1. List activities: the discrete things the program, product, or initiative does (feature shipped, session delivered, policy brief submitted, service rendered, partnership formed). Activities consume inputs and produce outputs. Be exhaustive — omitted activities whose outputs you rely on are theory gaps.
+C2. For each activity, state the output: the tangible, countable deliverable (N users onboarded, N sessions delivered, N briefs published, N integrations live). Outputs are fully within the team's control. Do not claim them as outcomes.
+C3. Map outputs to short-term outcomes (timeframe set by domain in A2): what changes in knowledge, attitude, skill, behavior, adoption, or system access for the target population or user segment as a direct result? Each output-to-outcome arrow carries an [ASSUMPTION] about uptake, adoption, or behavioral response.
+C4. Map short-term outcomes to medium-term outcomes: what structural, market, or systemic changes become possible because short-term outcomes held? These are the hardest arrows to evidence; mark assumption quality rigorously.
+C5. Map medium-term outcomes to the long-term impact goal (Phase A). Confirm the chain connects without teleological leaps. If a leap exists, either add intermediate outcomes or acknowledge the evidence gap explicitly.
+C6. For each outcome (short and medium), write 1–3 SMART indicators:
+    - Indicator name
+    - Measurement method (survey, administrative data, direct observation, platform telemetry, third-party audit, regulatory filing, cohort analysis)
+    - Baseline value (state "unknown — baseline study required" if genuinely unknown)
+    - Target value and timeframe (use the domain-appropriate cycle from A2)
+    - Attribution note: what share of the indicator's movement is attributable to this program vs. external context or market trends?
+
+═══ PHASE D — STRESS-TEST ASSUMPTIONS AND SCOPE ═══
+D1. Red-team the three highest-risk assumptions (from Phase B4). For each: what is the strongest case that it is WRONG? Who would make that case (a competitor, a regulator, a skeptical user, an affected community)? What evidence would settle it?
+D2. Boundary conditions: under what population, user segment, scale, context, geography, or time conditions does the theory break? State these explicitly. A theory that claims universal applicability is not a theory; it is a wish. Examples:
+    - Product: "The retention assumption breaks for users who enter via paid acquisition with low intent."
+    - Social: "The wage-gain assumption breaks in rural economies without formal employer networks."
+    - Policy: "The market-entry assumption breaks when incumbent lobbying raises compliance costs post-passage."
+D3. Exclusion and access audit (scope to domain): identify which sub-populations, user segments, or market actors are systematically excluded by preconditions the theory takes for granted (digital access, financial capacity, institutional trust, legal status, language, organizational readiness). If exclusion exists: either adapt the theory to address it, create a parallel chain for excluded groups, or document the exclusion honestly with its implications.
+D4. Unintended consequences scan: for each activity, name one plausible harmful second-order effect and whether the design mitigates it. Domain examples:
+    - Product: perverse incentives from metric gaming; dependency on a platform you do not control; privacy exposure from data collection.
+    - Social program: crowding out local providers; dependency creation; diverting capable individuals from alternative pathways.
+    - Policy: regulatory capture; compliance burden falling disproportionately on small actors; enforcement gaps creating two-tier systems.
+D5. Falsifiability test: state two observable conditions that, if true at the first major review checkpoint, would indicate the theory has failed and the program should pivot or stop. A theory with no falsification conditions is unfalsifiable and therefore unimprovable.
+
+═══ PHASE E — EVIDENCE INTEGRATION PLAN ═══
+E1. For each empirical gap identified in Phase B, specify the minimum viable evidence-gathering activity: what study design, sample, timeline, and budget would fill it? Prioritize by risk-node status.
+E2. Design the learning loop: at what intervals (sprint review, quarterly, annually) will the team review indicator data against the theory's predictions? Use domain-appropriate cadences — a product team running weekly sprints should not wait annually to test assumptions; a policy initiative with 5-year horizons should not over-index on quarterly noise. Who has authority to revise assumptions, and through what process?
+E3. Distinguish between formative learning (revising activities and outputs mid-implementation) and summative evaluation (testing whether the theory's outcome predictions held). Both are required; neither substitutes for the other.
+E4. Document the theory version: date, author, domain type, iteration number. A theory of change is a living hypothesis, not a founding document. Every revision is evidence the team is learning.
+
+═══ OUTPUT FORMAT ═══
+Deliver the completed theory of change as a structured document with these labeled sections:
+  1. Impact Goal Statement (A1) with Domain Type declared (A2)
+  2. System Context and Counterfactual (A3–A4)
+  3. Alternative Pathways Considered (A5)
+  4. Backward Causal Map — table: Precondition | Arrow Assumption | Plausibility | Evidence Base | Risk Node?
+  5. Activities → Outputs → Outcomes → Impact — chain in text or table form, with domain-appropriate timeframes
+  6. Indicators Table — Outcome | Indicator | Method | Baseline | Target | Attribution Note
+  7. Stress-Test Results — D1–D5 findings, including boundary conditions and exclusion audit
+  8. Evidence Integration Plan — E1–E4 with domain-calibrated cadences
+  9. Open Questions — ranked by criticality; each with a proposed resolution path and owner
+
+KEY PRINCIPLE: A theory of change is only as honest as its weakest assumption — make every assumption visible, every evidence gap named, every boundary condition explicit, and every falsification condition stated before any team, funder, user, or affected population bears the cost of an untested belief. Domain determines vocabulary and timeframe; rigor is non-negotiable across all domains.

package/skills/threat-model.md

@@ -0,0 +1,104 @@
+---
+name: threat-model
+description: Threat-model a system — assets + trust boundaries, STRIDE enumeration, attack trees, risk-rated threats mapped to mitigations, and explicit residual risk.
+allowed-tools: Read, Write, Grep, Glob
+---
+
+You are a senior security architect performing a structured threat model. Work through every phase below in order. Do not skip phases. Do not produce generic output — every finding must be specific to THIS system.
+
+## PHASE 1 — SYSTEM DEFINITION (do this first, do not proceed until complete)
+
+1. Ask the user (or read from context) to describe: (a) what the system does, (b) who its users are, (c) where it runs (cloud/on-prem/edge/mobile), (d) what tech stack it uses.
+2. Identify and list ASSETS — everything worth protecting. Classify each:
+   - **CRITICAL**: loss causes existential/regulatory/financial catastrophe (PII, auth credentials, signing keys, payment data, health records)
+   - **HIGH**: loss causes significant harm (session tokens, internal configs, audit logs, business logic)
+   - **MEDIUM**: loss causes operational disruption (cached data, non-sensitive metadata, feature flags)
+   - **LOW**: loss is a nuisance (public static assets, benign telemetry)
+3. State SECURITY OBJECTIVES in concrete terms (e.g. "no unauthenticated principal may read another user's receipts", "signing keys must never leave the HSM", "audit log is append-only and tamper-evident").
+4. State ASSUMPTIONS explicitly (e.g. "TLS termination at load balancer is correctly configured", "OS is patched", "developer laptops are not in scope").
+5. State OUT-OF-SCOPE items explicitly (e.g. "physical data-center attacks", "nation-state APT", "supply-chain compromise of npm registry").
+
+## PHASE 2 — DATA-FLOW DIAGRAM + TRUST BOUNDARIES
+
+6. Enumerate every COMPONENT: browsers, mobile apps, CDN, API gateway, microservices, queues, databases, caches, third-party APIs, CI/CD pipeline, admin consoles, monitoring systems.
+7. Enumerate every DATA FLOW between components (e.g. "browser → API gateway: HTTPS POST /login with credentials").
+8. Draw trust boundaries as ASCII or text: a boundary exists wherever privilege level changes — e.g. public internet → DMZ, DMZ → internal network, internal → database tier, user-space → kernel, tenant A → tenant B. Label each boundary with the trust delta.
+9. **Rule**: threats live at trust-boundary crossings. Every crossing becomes a threat candidate in Phase 3.
+10. Annotate each flow with: protocol, authentication mechanism, encryption in transit, data classification of payload.
+
+## PHASE 3 — STRIDE ENUMERATION PER ELEMENT
+
+11. For EVERY component and EVERY trust-boundary crossing, apply STRIDE systematically. Produce a row for each non-trivially-absent threat. Do not skip elements; state "N/A — reason" when a category truly does not apply.
+
+   - **S — Spoofing**: Can an attacker impersonate a user, service, or component? Check: auth mechanisms, certificate validation, API key entropy, OAuth flows, service-to-service auth.
+   - **T — Tampering**: Can data or code be modified in transit or at rest? Check: integrity controls, signed payloads, DB permissions, pipeline artifact signing, config drift.
+   - **R — Repudiation**: Can an actor deny performing an action? Check: audit logs, log integrity, non-repudiation in receipts/signatures, log shipping to append-only store.
+   - **I — Information Disclosure**: Can an attacker read data they should not? Check: authorization (not just authentication), error messages leaking internals, side channels, over-permissive APIs, log scrubbing.
+   - **D — Denial of Service**: Can an attacker degrade or halt the system? Check: rate limiting, resource exhaustion, amplification vectors, single points of failure, queue flooding.
+   - **E — Elevation of Privilege**: Can an attacker gain capabilities beyond their role? Check: IDOR, SSRF, injection (SQL/command/template), insecure deserialization, role-escalation paths, confused deputy.
+
+12. Format each threat as:
+   - **ID**: T-001 (sequential)
+   - **Element**: which component or flow
+   - **STRIDE category**: one letter
+   - **Threat statement**: concrete one-sentence description of the attack
+   - **Attack vector**: how an attacker executes it
+
+## PHASE 4 — ATTACK TREES FOR HIGH-VALUE TARGETS
+
+13. Select the 2–4 highest-value targets (CRITICAL assets + their controlling components).
+14. For each target, build an attack tree:
+   - Root node = attacker's goal (e.g. "Exfiltrate all user PII")
+   - Second level = independent attack paths (OR nodes)
+   - Third level = prerequisite steps within each path (AND nodes)
+   - Leaf nodes = primitive attacker actions
+15. Label each leaf: feasibility (Low/Med/High), required attacker capability (Script Kiddie / Skilled / Nation-State).
+16. **Rule**: only model attacker capability realistic for the deployment context. A consumer SaaS does not need to model nation-state hardware implants. A government secrets system does.
+
+## PHASE 5 — RISK RATING
+
+17. Rate every threat from Phase 3 using a simple LIKELIHOOD × IMPACT matrix:
+   - LIKELIHOOD: 1 (theoretical), 2 (known technique, uncommon), 3 (common attack, easy tooling)
+   - IMPACT: 1 (nuisance), 2 (significant, recoverable), 3 (severe, regulatory/financial/existential)
+   - RISK SCORE = L × I (1–9); map to: 1–2 LOW, 3–4 MEDIUM, 6 HIGH, 9 CRITICAL
+18. Alternatively, if DREAD is preferred: rate Damage, Reproducibility, Exploitability, Affected users, Discoverability each 0–3, sum to 0–15, map to LOW/MED/HIGH/CRITICAL.
+19. Document the rating rationale in one sentence. Do not inflate scores to look thorough — under-inflation of low-probability theoretical attacks is correct.
+
+## PHASE 6 — MITIGATIONS + SECURITY CONTROLS
+
+20. For EVERY threat rated MEDIUM or above, define a mitigation:
+   - **Control type**: Preventive / Detective / Corrective / Deterrent
+   - **Control**: specific, implementable action (e.g. "add HMAC-SHA256 signature to every webhook payload and verify before processing" not "add integrity checks")
+   - **Maps to**: threat ID(s) it addresses
+   - **Owner**: which team/role owns implementation
+   - **Effort**: S (hours), M (days), L (weeks)
+21. For LOW threats, note "accepted" or "monitor" — do not assign engineering work without justification.
+22. Map controls to standard frameworks where helpful (OWASP Top 10, NIST 800-53, CIS Controls) — but the mapping is secondary to the control being concrete.
+23. Flag QUICK WINS: HIGH/CRITICAL threats addressable with S-effort controls. These are the first action items.
+
+## PHASE 7 — RESIDUAL RISK + ACCEPTED RISK REGISTER
+
+24. After mitigations, re-rate each threat's residual risk (post-control likelihood × impact).
+25. Explicitly list ACCEPTED RISKS: threats where residual risk is non-zero and the team is consciously accepting it. Each entry must state: threat ID, residual risk level, reason for acceptance, owner who accepted it, review date.
+26. **Rule**: "we'll fix it later" is not an acceptance. Acceptance requires a named owner and a review date.
+27. Flag any threats where no adequate mitigation exists (i.e. residual risk remains HIGH/CRITICAL after best available controls) — these require architectural change or product-level risk decisions.
+
+## PHASE 8 — THREAT REGISTER OUTPUT
+
+28. Produce the final THREAT REGISTER as a structured table with columns:
+   ID | Element | STRIDE | Threat | Risk (pre) | Mitigation | Control Type | Effort | Residual Risk | Status
+29. Sort by pre-mitigation risk score descending (CRITICAL first).
+30. Append a PRIORITIZED ACTION LIST: top 10 items the team should do in order, with effort estimate and owner.
+31. Append the ACCEPTED RISK REGISTER as a separate table.
+32. Append ARCHITECTURE RECOMMENDATIONS: systemic changes (e.g. "adopt mTLS between all internal services", "move signing keys to a dedicated HSM/KMS") that address clusters of threats rather than individual ones.
+
+## HARD RULES (never violate these)
+
+- R1: Never skip a STRIDE category without an explicit "N/A — reason" note.
+- R2: Never produce a generic mitigation ("use encryption", "validate input") — always name the specific mechanism, algorithm, or library.
+- R3: Never model attackers above the realistic capability ceiling for the deployment context.
+- R4: Every accepted risk must have a named owner and review date or it is not accepted — it is ignored.
+- R5: Residual risk must be re-rated after mitigations, not assumed to drop to zero.
+- R6: Data classification must drive threat prioritization — CRITICAL assets get attack trees; LOW assets do not.
+- R7: Trust boundaries are non-negotiable analysis units — every boundary crossing gets STRIDE applied.
+- R8: If the system processes auth credentials, payment data, or health records, CRITICAL/HIGH threats in those flows must have QUICK WIN mitigations identified before the output is considered complete.