@event4u/agent-config 2.7.0 → 2.9.0

package/.agent-src/skills/market-entry-analysis/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: market-entry-analysis
+description: "Use when sequencing market entry — geo / segment / vertical, beachhead selection, regulatory-delta. Triggers on 'should we enter market X', 'which segment first'."
+status: active
+tier: senior
+source: package
+domain: process
+context_spine: [customer-segment, regulatory-regime, product]
+---
+
+# market-entry-analysis
+
+## When to use
+
+- A new market is on the table — geographic (EU, US, APAC), segment (SMB → mid-market → enterprise), or vertical (healthcare, fintech, manufacturing) — and the question is whether to enter, where to start, and in what sequence.
+- A current market is saturating and the question is which adjacent market unlocks the next growth window.
+- A regulatory shift opens or closes a market; the question is whether the new constraint changes the entry case.
+
+Do NOT use for build-vs-buy decisions on capability gaps (route to `build-buy-partner` (P1)), positioning narrative (route to `competitive-positioning` (P3); this skill composes P3), or per-customer economics within the entered market (route to `unit-economics-modeling` (O1)).
+
+## Cognition cluster
+
+- **Mental model 23 — Beachhead.** Pick a single segment / geo / vertical where the constraints favour winning, then expand from a position of strength. Trying to enter "the whole market" with no beachhead is the canonical failure pattern. See [`mental-models.md`](../../../docs/contracts/mental-models.md) § 23.
+- **Mental model 21 — Second-order thinking.** Entry costs (sales motion, regulatory compliance, segment-specific support) compound across markets. Reading entry as *"just open the door"* misses the second-order shape of multi-market operations. See `mental-models.md` § 21.
+- **Mental model 16 — Leading vs lagging.** Revenue from new market is lagging; **segment-specific pipeline coverage** + **win rates against incumbents in target segment** are leading. Reading only lagging signals = entering markets that already won't work. See `mental-models.md` § 16.
+- **Context-spine — customer-segment + regulatory-regime + product.** Read **customer-segment** for which buyer cohort the entry targets; **regulatory-regime** for the compliance delta (often the load-bearing cost in geo expansion); **product** for what's GA-shippable in the target market without re-platforming.
+
+## Procedure
+
+### Step 0: Frame the entry axis
+
+Pick **one** of three axes; do not mix:
+
+1. **Geo** — new region (US → EU, EU → APAC). Load-bearing constraint = regulatory-regime delta.
+2. **Segment** — new buyer cohort (SMB → mid-market → enterprise). Load-bearing constraint = sales-motion shift.
+3. **Vertical** — new industry (horizontal → healthcare). Load-bearing constraint = domain knowledge + segment-specific integrations.
+
+Mixing axes ("enter European healthcare enterprise") = three entries simultaneously. The correct framing is to pick one axis at a time and sequence the others.
+
+### Step 1: Select the beachhead
+
+Within the chosen axis, score 3–5 candidate beachheads on:
+
+1. **Constraint favourability** — does the segment / geo's constraint shape favour us? (e.g. for a self-serve product, SMB favours; enterprise penalises).
+2. **Reference-customer reachability** — can we land 3–5 named reference customers in the next two windows?
+3. **Regulatory delta** — compliance cost to operate (read `regulatory-regime` slot; e.g. EU + B2C + processing PII = GDPR-floor; EU + B2B + no PII = thin delta).
+4. **Expansion path** — does winning this beachhead unlock the adjacent ones, or is it a dead end?
+
+The beachhead is rarely the largest segment; it's the segment where we win cleanly and from which adjacent segments become accessible.
+
+### Step 2: Inspect the entry cost
+
+Three concrete cost categories — each named, not estimated:
+
+1. **Sales motion** — does the existing motion translate? (Self-serve → enterprise requires inside-sales + AE buildout; SMB → mid-market requires AE specialisation.)
+2. **Product delta** — what's missing for the target segment? (Compliance certs, SSO, audit logs, locale support, segment-specific integrations.)
+3. **Operating cost** — entity setup, tax, legal, segment-specific support. Geo entries add a 3–6 month operating-readiness window.
+
+Total entry cost = these three. Compare against `runway-frame.md` (O3) for whether the band has headroom.
+
+### Step 3: Inversion — name the failure mode
+
+For the chosen beachhead, write the 18-month failure mode:
+
+1. *"We entered and the incumbent's playbook neutralised us"* — incumbent's segment-specific advantage held.
+2. *"We entered and the sales motion didn't translate"* — assumed motion (self-serve) didn't work in the segment (enterprise).
+3. *"We entered and the regulatory cost ate the unit economics"* — compliance delta was load-bearing and under-estimated.
+
+If the failure mode has no mitigation, the entry is not ready. Sit with it.
+
+### Step 4: Sequence the expansion
+
+Beachhead = first move. Map the next 2–3 expansion moves explicitly:
+
+1. *"Win beachhead → unlock adjacent segment X (same motion, larger TAM) → unlock adjacent geo Y (same segment, regulatory delta manageable)."*
+2. *"Win beachhead → unlock co-sell with vendor Z → unlock vertical W."*
+
+Un-sequenced beachhead wins are dead-ends. The sequence is the long-game; the beachhead is just the first move.
+
+### Step 5: Validate the entry case before emitting
+
+Before emitting the entry plan, verify three things:
+
+1. **Beachhead defensibility** — confirm the chosen beachhead scores higher than the runner-up on at least two of the four Step-1 dimensions; if it ties or wins on one only, the choice is brittle and must be re-run.
+2. **Entry cost vs runway band** — check that the Step-2 entry cost lands inside the `runway-frame.md` (O3) band; if it doesn't, the entry is not yet financeable and must be deferred or staged.
+3. **Failure-mode mitigation** — assert that the Step-3 failure mode has a named mitigation; an un-mitigated failure mode means the analysis is incomplete.
+
+All three must pass. If any fails, the entry plan is not ready to emit; return to the failing step.
+
+### Step 6: Emit the entry plan
+
+Produce the entry plan artifact. P2 composes P3 (`competitive-positioning`) for the narrative against incumbents in the target segment.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Sequencing market entry across geo / segment / vertical axes.
+- Choosing the beachhead within a chosen entry axis.
+
+**WHEN NOT to use this**
+
+- Build-vs-buy capability decisions — route to [`build-buy-partner`](../build-buy-partner/SKILL.md) (P1).
+- Positioning narrative against incumbents — route to [`competitive-positioning`](../competitive-positioning/SKILL.md) (P3); this skill composes P3.
+- Per-customer economics in the target market — route to [`unit-economics-modeling`](../unit-economics-modeling/SKILL.md) (O1).
+- Channel / funnel design for the entry — route to Wing-3 [`funnel-analysis`](../funnel-analysis/SKILL.md) and [`content-funnel-design`](../content-funnel-design/SKILL.md).
+
+## When the agent should load this
+
+- "Should we enter the EU market?"
+- "Which segment do we go to next — mid-market or enterprise?"
+- "Pick the beachhead for our vertical expansion."
+- "Wo greifen wir als erstes an?"
+
+## Output
+
+1. **`entry-axis-frame.md`** — chosen axis (geo / segment / vertical), why this axis first, what's deferred.
+2. **`beachhead-scorecard.md`** — 3–5 candidate beachheads scored on the four Step-1 dimensions; named winner with reasoning.
+3. **`entry-cost-table.md`** — sales-motion delta, product delta, operating cost; compared against runway band.
+4. **`expansion-sequence.md`** — beachhead + next 2–3 moves, with the unlock-mechanism named per move.
+
+## Gotcha
+
+- "Enter the European enterprise healthcare market" mixes three axes. Pick one.
+- The largest segment is rarely the right beachhead; the segment where constraints favour us is.
+- Geo regulatory delta is the most under-estimated cost. Budget the high-end of the band for compliance.
+- Beachhead win without sequenced expansion = isolated revenue stream that never compounds.
+
+## Do NOT
+
+- Do NOT mix entry axes — sequence them.
+- Do NOT pick a beachhead without a named 18-month failure mode + mitigation.
+- Do NOT skip the expansion sequence — the beachhead's value is which next moves it unlocks.
+
+## Runnable example
+
+Horizontal SaaS, US-only, mid-market, considering EU expansion.
+
+- Step 0 — axis = geo (EU). Defer segment (stay mid-market) and vertical (stay horizontal).
+- Step 1 — candidate beachheads: DACH, Nordics, UK, Benelux. Scored: UK wins on constraint-favour (English-language sales motion translates, common-law contract familiarity), reference-reachability (5 mid-market UK customers reachable via existing channels), regulatory delta (UK-GDPR ≈ EU-GDPR floor with thinner data-residency requirement), expansion path (UK → Benelux → DACH).
+- Step 2 — Sales motion: existing AE motion translates to UK. Product delta: data-residency in EU (12 weeks). Operating cost: UK Ltd entity, VAT registration ≈ 3 months.
+- Step 3 — failure mode: "incumbent's UK channel partnerships locked us out of mid-market." Mitigation: direct-AE motion + content-led pipeline.
+- Step 4 — sequence: UK (beachhead) → Benelux (same motion, thin regulatory delta) → DACH (German-speaking sales hire required, larger TAM).
+- Step 5 — emit entry plan + compose P3 for UK-vs-incumbents positioning.

package/.agent-src/skills/messaging-architecture/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: messaging-architecture
+description: "Use when shaping the primary message, supporting proofs, and audience-by-message matrix from a locked positioning frame — before any copy or launch beat. Triggers on 'tighten the message stack'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product, customer-segment]
+---
+
+# messaging-architecture
+
+## When to use
+
+- Positioning is locked (four anchors + assumption ledger) and the next artefact — launch deck, homepage, sales narrative — needs a load-bearing message stack instead of one-off copy.
+- A team is shipping copy faster than it is shipping shared meaning; lines diverge across surfaces and the segment cannot recognise itself.
+- An audience-by-message matrix is missing and the same primary message is being shouted at three audiences who hear three different things.
+
+Do NOT use to write the copy itself (downstream of this skill),
+peer-vs-peer comparison (route to `competitive-positioning`), or
+launch sequencing (route to `gtm-launch`).
+
+## Cognition cluster
+
+- **Mental model 15 — Signal vs. noise.** Every message lands inside
+  an inbox that is already full. The primary message must clear the
+  segment's noise floor, not just be true. Estimate the noise before
+  drafting; without it, every line looks distinctive in the doc and
+  forgettable in market. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 15.
+- **Mental model 30 — Inversion.** Ask *"what is the strongest
+  message a credible alternative would land against us?"* The answer
+  exposes the proofs the message stack must carry, not the words.
+  See `mental-models.md` § 30.
+- **Context-spine — product + customer-segment.** Read the **product**
+  slot for the proofs the team can actually back; read the
+  **customer-segment** slot for the buyer's listening posture.
+  Architecture that exceeds the proofs available is fiction. See
+  [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### Step 0: Inherit the positioning frame
+
+Open the `positioning.md` artefact ([`positioning-strategy`](../positioning-strategy/SKILL.md)
+Step 1 output). If the four anchors are missing or contested, stop
+and route back. Messaging architecture without a locked positioning
+frame is decoration — it will be rewritten the next quarter.
+
+### Step 1: Identify the primary message
+
+Identify the **one** sentence — the load-bearing claim
+that, if the segment remembered nothing else, would still trigger
+the right switch event. Structure:
+
+*"For \<segment\>, \<category\> that \<load-bearing benefit\>,
+instead of \<alternative\>."*
+
+The benefit must be the **switch-event benefit** — what changes the
+day they buy — not a feature list and not a brand attribute.
+
+### Step 2: Stack the supporting proofs
+
+Three proofs, ranked. Each proof is a sentence the team can defend
+with evidence (data, demo, reference, contract clause). Proofs that
+need adjective amplification (*"truly seamless"*, *"radically
+simple"*) are not proofs — they are the gap a proof would fill.
+
+Rank the proofs by **closing weight**: how much each moves the
+buyer's decision from *no* to *yes*. The order is the order of
+appearance in every downstream surface.
+
+### Step 3: Build the audience-by-message matrix
+
+Audiences are not segments — they are roles inside the segment
+(economic buyer, champion, end-user, finance, security). For each
+audience, fill: **what they fear · what they hope · what proof
+clears each.** The matrix forces the team to confront the surfaces
+where the primary message lands wrong on a role even when right on
+the segment.
+
+### Step 4: Validate against the noise floor and the inversion test
+
+Validate the stack on three checks:
+
+1. **Noise floor.** For the primary message, name three lines a
+   credible peer says today. If the primary message would not be
+   distinguishable when read alongside them, it is below the noise
+   floor — sharpen or drop.
+2. **Inversion.** Write the strongest counter-message a credible
+   alternative would land against us. Confirm at least one supporting
+   proof neutralises it; if none does, the stack is missing a proof.
+3. **Proof-coverage.** For every fear / hope cell in the matrix,
+   verify a proof exists. Cells without a proof are explicit gaps,
+   not silent omissions.
+
+### Step 5: Hand back
+
+Hand the three artefacts (see `## Output`) to
+[`gtm-launch`](../gtm-launch/SKILL.md) for launch-wave sequencing,
+[`editorial-calendar`](../editorial-calendar/SKILL.md) for cadence
+mapping, or [`fundraising-narrative`](../fundraising-narrative/SKILL.md)
+for capital-raising framing. Do **not** write the copy here — copy
+production is a downstream artefact.
+
+## Related Skills
+
+**WHEN to use this**
+
+- The unit of work is the message stack (primary + proofs + matrix), not a copy block.
+- Positioning is locked and downstream surfaces need a shared anchor.
+- Cross-audience messaging has scattered and the team cannot name a primary.
+
+**WHEN NOT to use this**
+
+- Locking the four-anchor positioning frame — route to
+  [`positioning-strategy`](../positioning-strategy/SKILL.md).
+- Peer-vs-peer ours-vs-theirs verdict table — route to
+  [`competitive-positioning`](../competitive-positioning/SKILL.md).
+- Launch-wave audience sequencing — route to
+  [`gtm-launch`](../gtm-launch/SKILL.md).
+- Voice attribute selection or tone-by-context matrix — route to
+  [`voice-and-tone-design`](../voice-and-tone-design/SKILL.md).
+
+## When the agent should load this
+
+- "Lock the message stack before we draft the launch deck."
+- "Wir brauchen eine primary message, keine Tagline."
+- "Build the audience-by-message matrix for the security buyer."
+- "Are our three proofs distinguishable from \<incumbent\>'s lines?"
+- "Inversion-check our messaging against the alternative."
+- "Our message has scattered across landing pages — re-anchor it."
+
+## Output
+
+1. **`primary-message.md`** — one sentence in the segment / category
+   / benefit / alternative shape, plus the load-bearing word and
+   why it is load-bearing.
+2. **`supporting-proofs.md`** — three proofs ranked by closing
+   weight, each with the evidence the team can defend it with.
+3. **`audience-matrix.md`** — one row per audience: fear · hope ·
+   proof-that-clears-each · primary-message variant if reframing is
+   needed.
+
+## Gotcha
+
+- A primary message everyone in the room agrees with on first read
+  is usually below the noise floor — agreement is consensus, not
+  distinctiveness.
+- Proofs that need adjectives are signals of a missing proof; replace
+  the adjective with the evidence or remove the line.
+- The audience matrix tempts the team to multiply primary messages.
+  Resist: the segment receives one primary; the matrix shapes
+  emphasis, not substitution.
+
+## Do NOT
+
+- Do NOT write copy in this skill — copy lives downstream.
+- Do NOT inflate the stack beyond three proofs; a stack of seven is
+  a wishlist, not architecture.
+- Do NOT skip the noise-floor check; an internally distinctive
+  message is not the same as a market-distinctive one.
+
+## Runnable example
+
+Mid-market HR analytics tool, positioning locked (segment: HR leaders
+at 200–2000-person growing companies; alternative: spreadsheet +
+HRIS report; PoV: retention beats acquisition):
+
+- Primary message: *"For HR leaders at growing 200–2000-person
+  companies, the workforce-analytics layer that turns the
+  board-quarter retention conversation into a one-click roll-up,
+  instead of a spreadsheet rebuild every quarter."*
+- Proofs ranked by closing weight: (1) cohort attrition by tenure
+  band in < 5 clicks (demo); (2) plugs into the existing HRIS,
+  not a replacement (architecture diagram); (3) board-quarter
+  rebuild collapses from \~ 8 hours to \~ 1 hour (reference
+  customer, contractually quoted).
+- Audience matrix — *Champion (HR director):* fear = another tool
+  to maintain; hope = looks competent to CEO; proof = HRIS
+  plug-in. *Economic buyer (CFO / COO):* fear = soft ROI; hope =
+  retention saving; proof = reference quote with hours saved.
+- Hand-off → `gtm-launch` sequences launch waves around the
+  retention-conversation moment in board-quarter cadence.

package/.agent-src/skills/onboarding-design/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: onboarding-design
+description: "Use when designing customer onboarding — time-to-first-value, milestone design, friction audit, drop-off diagnosis. Triggers on 'fix onboarding', 'why do new accounts churn fast'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product, customer-segment, funnel-stage]
+---
+
+# onboarding-design
+
+## When to use
+
+- New accounts churn inside their first 30 days and the team cannot name which onboarding milestone they failed to reach — drop-off is treated as a single number, not a stage-by-stage signal.
+- A new segment is being onboarded against an onboarding flow built for a previous segment — the milestones likely do not match the new segment's switch-event shape.
+- Time-to-first-value is *"days, maybe weeks"* — the answer needs to be a number with a falsifiable definition, not a sentiment.
+
+Do NOT use to onboard employees (that is the Wing-4
+employee-onboarding program — different audience, different
+contract), diagnose long-cycle churn (route to
+`churn-prevention`), or run the full visitor → paid funnel (route
+to `funnel-analysis`).
+
+## Cognition cluster
+
+- **Mental model 14 — Meadows leverage points.** Onboarding is a
+  high-leverage system: a change in the milestone *definition*
+  reshapes retention more than a change in the welcome email. Pick
+  the leverage point — milestone definition over surface polish.
+  See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 14.
+- **Mental model 16 — Leading vs. lagging indicators.**
+  Time-to-first-value and milestone-completion are leading; D30
+  retention is lagging. Onboarding decisions built on lagging
+  signals can only confirm churn after it lands. See
+  `mental-models.md` § 16.
+- **Mental model 13 — Occam's razor.** When new accounts drop off,
+  the simpler explanation usually wins: *"the first milestone is
+  too far from the buyer's job to complete in one session"* beats
+  *"users do not understand our value proposition."* Pick the
+  simpler explanation; it changes the move. See
+  `mental-models.md` § 13.
+- **Context-spine — product + customer-segment + funnel-stage.**
+  Read the **product** slot for what the segment can actually
+  configure unattended, the **customer-segment** slot for the
+  segment's job and switch-event, and the **funnel-stage** slot for
+  where activation sits relative to signup and paid. See
+  [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### Step 0: Inspect — pull the current onboarding shape
+
+Inspect the actual funnel: signup → milestone-1 → milestone-2 →
+activation → D30. For each transition pull conversion rate (with
+band) and median time-to-transition for the last two cohorts.
+Inspect whether the activation event correlates with paid retention;
+if not, the activation event is mis-defined and Step 2 fixes it.
+
+### Step 1: Define time-to-first-value with a falsifiable definition
+
+Write the sentence: *"\<Segment\> reaches first value when
+\<observable buyer action\> happens, by \<target hours / days\>
+after signup."* The action must be observable in instrumentation,
+must correlate with paid retention (Step 0 inspection), and must be
+something the buyer accomplishes — not something the product
+displays.
+
+### Step 2: Design three milestones earning activation
+
+Each milestone is a buyer action with a definition, a friction
+audit, and a default outcome.
+
+1. **Milestone definition** — one sentence in buyer-action form
+   (*"buyer has imported one record"*, not *"buyer has seen the
+   import screen"*).
+2. **Friction audit** — name the three highest-friction steps the
+   buyer must clear; each gets a *cheapest-fix* hypothesis.
+3. **Default outcome** — if the buyer does nothing, what does the
+   product do for them? A milestone with no default is a milestone
+   the busy half of the segment will miss.
+
+### Step 3: Audit friction at each milestone
+
+For each milestone, time the buyer journey: clicks, fields, decision
+points, wait states. Tag each as *blocker* (cannot proceed without
+it), *toll* (proceed but slow), or *fog* (buyer unsure what to do
+next). Fog kills more onboarding than blockers — fog is silent.
+
+### Step 4: Diagnose drop-off by segment × milestone
+
+The drop-off is rarely uniform. Segment by segment × milestone;
+the cell with the steepest below-band drop is the binding fix.
+Two cells dropping at once usually means a shared upstream cause
+(account-provisioning failure, ICP mismatch) — fix upstream, not
+in the milestone.
+
+### Step 5: Hand back
+
+Hand the time-to-first-value definition, the three milestones with
+friction audits, and the segment × milestone drop-off table to the
+implementing team and to
+[`churn-prevention`](../churn-prevention/SKILL.md) for downstream
+health-score signal definition. Onboarding owns days 0–30;
+churn-prevention owns the signals after.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Designing or auditing days 0–30 of the customer lifecycle.
+- Defining time-to-first-value as a falsifiable event, not a sentiment.
+
+**WHEN NOT to use this**
+
+- Long-cycle churn diagnosis (D60+) — route to
+  [`churn-prevention`](../churn-prevention/SKILL.md).
+- Account expansion or upsell mechanics — route to
+  [`expansion-playbook`](../expansion-playbook/SKILL.md).
+- Full visitor → paid funnel diagnosis — route to
+  [`funnel-analysis`](../funnel-analysis/SKILL.md).
+- Activation-event redefinition or aha-moment selection — route to
+  [`activation-design`](../activation-design/SKILL.md).
+
+## When the agent should load this
+
+- "Fix our onboarding — new accounts churn fast."
+- "Why does cohort-9 drop at milestone-2?"
+- "Define time-to-first-value for the mid-market segment."
+- "Wie viele Klicks bis zum ersten Wert?"
+
+## Output
+
+1. **`time-to-first-value.md`** — falsifiable definition: segment × observable action × target time × correlation with paid retention.
+2. **`milestones.md`** — three milestones, each with definition · friction audit (blocker / toll / fog) · default outcome.
+3. **`dropoff-table.md`** — segment × milestone conversion rates with bands; binding-fix cell flagged.
+
+## Gotcha
+
+- An activation event that does not correlate with paid retention is a vanity event. The funnel will look healthy and D30 will keep dropping.
+- *"Onboarding emails"* is not onboarding design. Emails are a surface; milestones are the system. Designing emails before milestones is rearranging deck chairs.
+- A milestone without a default outcome assumes the buyer drives the journey. Half of every segment will not — design for the half that will not.
+
+## Do NOT
+
+- Do NOT use industry-average onboarding benchmarks as targets; segment shape and product complexity dominate them.
+- Do NOT confuse signup with activation; signup is consent, activation is value.
+- Do NOT redesign milestones one at a time mid-cycle without an A/B holdout — concurrent changes destroy the signal.
+
+## Runnable example
+
+B2B mid-market analytics tool, D30 retention sagging from 71 % to 58 % over two quarters.
+
+- Time-to-first-value — *"Mid-market: buyer reaches first value when one connected data source returns one rendered dashboard, within 24 hours of signup."* Correlation with D90 paid retention: r = 0.62.
+- Milestones — *(1)* connect data source (friction: OAuth scope confusion = fog; default: paste-CSV fallback). *(2)* save first query (friction: schema picker = toll; default: starter-template per segment). *(3)* share dashboard with one teammate (friction: invite-flow buried = blocker; default: auto-invite admin).
+- Drop-off table — Mid-Market × milestone-1: 41 % conv (band 35–47, vs trailing-cohort median 62 %). Binding fix: OAuth fog at milestone-1.
+- Hand-off — milestones + drop-off → eng team for OAuth-fog fix; `churn-prevention` picks up D30+ health-score signals.

package/.agent-src/skills/onboarding-program/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: onboarding-program
+description: "Use when shaping employee onboarding — time-to-productivity, role-by-role program, mentor pairing, 30/60/90 milestones. Triggers on 'design our onboarding', 'why are new hires ramping slow'."
+status: active
+tier: senior
+source: package
+domain: process
+context_spine: [org-stage, product, customer-segment]
+---
+
+# onboarding-program
+
+## When to use
+
+- A first onboarding program is needed because hires are arriving and ramping is ad-hoc, expensive, and slow.
+- An existing program is producing inconsistent ramp times across roles or cohorts and the question is *where the program leaks productivity*.
+- A new role family (first sales hire, first designer, first SRE) is being added and the question is *what role-shaped onboarding looks like for this function*.
+
+Do NOT use as a customer-onboarding surface (route to Wing-3 [`onboarding-design`](../onboarding-design/SKILL.md) (H11); this skill is internal-employee, that one is external-customer), as a performance-feedback skill (route to Q4 `perf-feedback-craft`), or for HRIS-onboarding-module configuration.
+
+## Cognition cluster
+
+- **Mental model 1 — First principles.** Strip onboarding to: *what does this person need to know, do, and decide alone before being net-positive?* Most onboarding programs over-index on what's easy to teach (history, slides) and under-index on what's hard (decision rights, who-knows-what, codebase / domain context). See [`mental-models.md`](../../../docs/contracts/mental-models.md) § 1.
+- **Mental model 21 — Second-order thinking.** Onboarding is paid for in mentor time. A 4-hour-per-week mentor commitment from a senior person costs more than people realise; mentor capacity is the binding constraint on hiring velocity. Read mentor cost as part of the program, not a free input.
+- **Mental model 28 — Inversion.** *"What would make this hire fail in their first 90 days?"* Inversion surfaces the load-bearing risks (unclear scope, no early win, missing tools, no peer relationship). Most onboarding failures trace to one of these four, not to skill gaps.
+- **Mental model 26 — Optionality.** A heavy template onboarding preserves *consistency* optionality but forecloses *role-specific* optionality. A pure free-form onboarding preserves customization but forecloses scalability. Pick the trade explicitly per role family.
+- **Context-spine — org-stage + product + customer-segment.** Read **org-stage** for what's affordable (10-person co: founder onboards; 50-person co: managers + buddies; 150+: dedicated onboarding owner). Read **product** for domain complexity (deep regulated domain = longer ramp). Read **customer-segment** for which roles need customer-context immersion early.
+
+## Cross-wing handoff
+
+- Composed downstream of Q1 `org-design` — onboarding shape follows team structure; onboarding without a clear team home is broken from day one.
+- Composed downstream of Q2 `comp-banding` — level + scope expectations from comp banding anchor the ramp expectations.
+- Hands off to Q4 `perf-feedback-craft` for the first 30 / 60 / 90 feedback checkpoint shape.
+- Distinct from Wing-3 H11 `onboarding-design` (customer onboarding) — different audience, different proof bar.
+
+## Procedure
+
+### Step 0: Identify role-family and ramp definition
+
+Before designing the program, name:
+
+1. *What role family is in scope?* (eng IC, eng manager, PM, design, sales AE, sales SDR, CS, ops, finance). Onboarding shape varies sharply by family.
+2. *What does "ramped" mean for this family?* — define net-positive in concrete behavior: an eng IC ships a PR alone by week 4 and owns a workstream by week 12; an AE books N qualified meetings by week 4 and closes a deal by quarter end. Adjective-only definitions ("getting up to speed") fail the bar.
+3. *What's the realistic time-to-ramp benchmark?* — typically 30 / 60 / 90 days for individual contributors; 6 months for managers; 6–12 months for senior leaders. Compare proposed program length to benchmark.
+
+A program with no concrete ramped-definition is unfalsifiable.
+
+### Step 1: Map what the role needs to know, do, decide alone
+
+For the role family, enumerate three buckets:
+
+1. **Know** — domain context (industry, regulation, product), system context (codebase tour, dataflow, ops), people context (who owns what, who decides what). Force concrete artifacts (which doc, which repo, which dashboard) — not abstract topics.
+2. **Do** — first owned task, first reviewed task, first solo task, first shipped task. Sequence from low-risk to medium-risk; arrange to produce one demonstrable early win in week 1–2.
+3. **Decide alone** — what kind of decision can this person make without consulting? Spell out the boundary; the absence of this is the #1 cause of slow ramp.
+
+Most onboarding programs cover Know well, Do partially, Decide-alone almost never. The last bucket is the leverage point.
+
+### Step 2: Design 30 / 60 / 90 milestones
+
+For each milestone, name:
+
+1. **30-day** — Know complete; first owned task shipped; named buddy and named manager 1:1 cadence locked.
+2. **60-day** — Owns a workstream segment; has produced one visible artifact for the team; has had at least one feedback checkpoint (composes Q4).
+3. **90-day** — Net-positive on standalone contribution; named scope for next quarter; has built one cross-team relationship.
+
+Each milestone needs an objective check (shipped artifact, behavior observed) — not "feels good" attestation.
+
+### Step 3: Pair the mentor / buddy / manager triad
+
+Three roles, distinct purposes:
+
+1. **Manager** — sets scope, removes blockers, runs 1:1 cadence (weekly first 90 days, biweekly after).
+2. **Buddy** — peer-level, week-1 to week-12, low-friction questions, social onboarding. Buddy is not a mentor; mixing the role overloads the buddy.
+3. **Mentor** *(optional, role-dependent)* — senior in the craft, monthly cadence, growth-focused. Reserved for higher-stakes hires (senior eng, manager, first-in-role).
+
+Mentor / buddy capacity is the binding constraint; if there are no available buddies, hiring should pause, not push through.
+
+### Step 4: Build the early-win path
+
+Inversion: *"what makes this hire feel they made the wrong choice in week 2?"* — usually: no tools, no clarity, no peer, no early demonstrable win.
+
+1. Pre-day-1: laptop / accounts / access provisioned. Verified by the manager before day 1, not assumed.
+2. Day 1–5: orientation, codebase / domain tour, 1:1s with named peers, manager 1:1 scheduled out for 90 days.
+3. Week 2–4: first owned task — selected to be shippable, visible, low-risk, but real. Not a synthetic onboarding-only task; a real one.
+4. Week 4–6: first feedback checkpoint; explicit acknowledgement of one thing going well + one thing to adjust.
+
+The early-win path is the #1 driver of 12-month retention for new hires.
+
+### Step 5: Validate the program before emitting
+
+Before producing the artifact, verify three things:
+
+1. **Ramp-definition concreteness** — confirm Step 0 named net-positive in concrete behavior; adjective-only definitions fail and must be re-run.
+2. **Decide-alone coverage** — assert Step 1's third bucket is non-empty; decide-alone gaps are the canonical ramp-slowing failure mode.
+3. **Mentor capacity check** — verify the buddy / mentor commitments fit within available mentor capacity for the cohort size; overbooked mentors collapse onboarding silently.
+
+All three must pass. If any fails, return to the failing step.
+
+### Step 6: Emit the onboarding program
+
+Produce the onboarding-program artifact for the role-family owner (engineering lead, sales lead, design lead) and people partner. The artifact frames the ramped definition, the Know/Do/Decide map, the 30/60/90 milestones, the triad assignments, and the early-win path.
+
+## Related Skills
+
+**WHEN to use this**
+
+- First-pass internal-employee onboarding program design.
+- Role-family-specific onboarding (first sales hire, first SRE, first designer).
+- Existing program audit when ramp times are inconsistent or long.
+
+**WHEN NOT to use this**
+
+- Customer onboarding — route to Wing-3 [`onboarding-design`](../onboarding-design/SKILL.md) (H11); different audience entirely.
+- Performance / feedback design — route to [`perf-feedback-craft`](../perf-feedback-craft/SKILL.md) (Q4); Q3 composes Q4 at milestone checkpoints, doesn't replace it.
+- Org structure decisions — route to [`org-design`](../org-design/SKILL.md) (Q1).
+- Compensation banding — route to [`comp-banding`](../comp-banding/SKILL.md) (Q2).
+
+## When the agent should load this
+
+- "Design our onboarding."
+- "Why are new hires ramping slow?"
+- "What does the first 90 days look like for a sales AE?"
+- "Set up a buddy program."
+- "Wie bauen wir das Onboarding für Engineering auf?"
+
+## Output
+
+1. **`ramp-definition.md`** — role-family × concrete ramped-definition × benchmark time-to-ramp.
+2. **`know-do-decide-map.md`** — three buckets with concrete artifacts and decide-alone boundary.
+3. **`milestones-30-60-90.md`** — milestone × objective check × feedback checkpoint.
+4. **`triad-assignment.md`** — manager / buddy / mentor mapping with capacity check.
+5. **`early-win-path.md`** — pre-day-1 through week-6 sequence with named first owned task pattern.
+
+## Gotcha
+
+- "Read these 40 docs" is a placebo onboarding. Force know-by-doing.
+- Buddy ≠ mentor. Overloading the buddy with growth conversations collapses the role.
+- Decide-alone boundaries unwritten = stalled ramps. The single biggest leverage point most programs miss.
+- Synthetic onboarding tasks teach less than real tasks selected for low risk. Resist the urge to manufacture training-only work.
+
+## Do NOT
+
+- Do NOT skip the ramped-definition step; un-defined ramp is unfalsifiable.
+- Do NOT assign onboarding to an already-overloaded buddy; the program looks great on paper and fails in week 3.
+- Do NOT confuse this with customer onboarding (H11); the two operate on different proof bars.
+
+## Runnable example
+
+Series-A SaaS hires its first dedicated SRE, no prior SRE onboarding shape.
+
+- Step 0 — Role family: senior SRE. Ramped means: on-call alone by week 12, owns one production reliability workstream by month 6, has shipped one runbook and one alert-quality improvement by month 3.
+- Step 1 — Know: prod architecture doc, incident-response runbooks, last 6 months of incidents. Do: shadow on-call weeks 1–2, secondary on-call weeks 3–6, primary on-call by week 12. Decide-alone: page severity, can declare incident, can deploy hotfix during business hours; cannot make architecture changes alone before month 4.
+- Step 2 — Milestones: 30-day Know complete + first runbook PR shipped; 60-day secondary on-call + alert-quality artifact produced; 90-day primary on-call + first standalone reliability initiative scoped.
+- Step 3 — Triad: manager = VP Eng (weekly 1:1); buddy = senior backend engineer (peer, week 1–12); mentor = none initially (no other SREs in-house; consider external mentor at month 6).
+- Step 4 — Early win: first runbook PR for a known-rough incident scenario; shippable in week 2, visible to whole eng team.
+- Step 5 — Validate: ramped definition concrete; decide-alone boundary explicit; buddy commitment is 2h/week which fits the backend engineer's current load. Pass.
+- Step 6 — Emit onboarding program for SRE role family; flag to revisit at month 6 once second SRE is hired (mentor capacity will exist then).