10-Minute Onboarding

// 01a · team-identity.md — mission, ICP, what we say no to

Read first because every other file presumes you know who the team is and what game it's playing. A new hire who hasn't read this can't tell whether a customer request is on-mission or a distraction. Anchors all other context.

// template

# Team Identity — [team name]

**Mission:** [one sentence. Concrete enough that you could reject a feature using it.]
**ICP:** [who we sell to. Title, company size, what they're trying to accomplish.]
**Positioning:** [what we are. What we are NOT. What we replace.]
**What we say no to:** [3–5 specific asks we routinely decline + why.]
**Operating tenets:** [the 3–5 things we won't compromise on.]

// example lines (real shape)

**Mission:** Cut IT pros' incident-response time from hours to minutes by piping
runbooks straight into Copilot.

**ICP:** IT Ops leads at 200–2000-person companies running M365 + Azure, with
≥ 1 active incident per week and Copilot rolled out to at least half the team.

**Positioning:** We are a runbook layer that lives inside Copilot — not a SIEM,
not a Datadog, not an ITSM. We replace tribal knowledge living in 4 people's heads.

**What we say no to:**
- Mobile apps. We are desktop-only by design; field techs use the Copilot mobile app.
- Real-time alerting. PagerDuty is good at that; we don't need to be.
- Anyone whose Copilot rollout is < 6 months out. They aren't ready.

**Operating tenets:**
- Customer call ≥ user research call ≥ survey. Always.
- We don't ship anything that requires a vendor demo to understand.
- Friday-afternoon deploys are fine; the brain has the rollback runbook.

// without this, the new hire can't tell a good customer call from a bad one. Day-1 read.

// 01b · customer-context.md — the language customers actually use

Top 5 customer segments, the top 3 jobs each is hiring you to do, and the literal phrasing they use when talking to support. The new hire's first outbound email reads like the customer's last inbound one before they've talked to a single customer.

// template

# Customer Context

## Segment 01 — [name + 1-line description]
- **Job-to-be-done 01:** [outcome they want, in their words]
- **Job-to-be-done 02:** [...]
- **Job-to-be-done 03:** [...]
- **Their language:** [verbatim phrases pulled from calls/tickets]
- **What they DON'T say:** [our internal jargon they don't recognize]

[repeat for segments 02–05]

// example lines (real shape)

## Segment 02 — Healthcare IT directors at 500–1500-bed systems

- **JTBD 01:** "Stop the 3am pager going off because someone's Epic integration died."
- **JTBD 02:** "Show the CISO we have an actual incident process, not a Slack channel."
- **JTBD 03:** "Onboard the new analyst without burning two weeks on shadowing."

- **Their language:** "EHR downtime", "Epic outage", "downtime procedures",
  "the analyst can't repro", "we need an audit trail", "Joint Commission asked…"

- **What they DON'T say:** "incident response", "MTTR", "runbook automation",
  "AI agent". Don't lead with those terms. They land flat.

// without this, every new-hire email goes out in the team's jargon, not the customer's. Day-1 read.

// 01c · stack-map.md — every system, owner, runbook, and "don't touch" flag

The infra census. Every service the team owns or depends on, who knows it, where the runbook lives, and what's actively being deprecated. The "don't touch X yet, we're killing it next sprint" list is the single highest-value section — the new hire's instinct is to refactor whatever they hit first, and this saves them.

// template

# Stack Map

## Owned services
- **[service]** · owner: [person] · runbook: [path] · state: [live/EOL/migrating]

## Dependencies (third-party)
- **[vendor]** · what we use it for · contact · SLA

## Don't touch (yet)
- **[service]** · why · killing it by [date] · who's leading the migration

## Patterns
- [the 3–5 architectural patterns the team uses, with a "see also" file]

// example lines (real shape)

## Owned services
- **rb-ingest** · owner: Priya · runbook: runbooks/rb-ingest.md · state: live
- **rb-router** · owner: Marcus · runbook: runbooks/rb-router.md · state: live
- **rb-legacy-router** · owner: Marcus · state: migrating — EOL 2026-07

## Don't touch (yet)
- **rb-legacy-router** — we're cutting it out by July. Any PR against it gets
  bounced. New routing logic goes in rb-router only. See ADR-038.
- **auth-rewrite branch** — paused since Feb when the OIDC vendor pivot landed.
  Don't rebase it on main. Don't ship from it. Ask Priya if you think you need to.

## Patterns
- Idempotent ingest with at-least-once delivery → see patterns/idempotent-ingest.md
- Outbox + relay for webhook fanout → see patterns/outbox.md
- Feature flags via LaunchDarkly only — never .env booleans → see patterns/flags.md

// without this, the new hire spends day 4 refactoring a service we're killing in week 8. Day-3 read.

// 01d · recent-decisions.md — last 90 days of ADRs

Pulled from the T02 Decision Archive: every architecture / strategy / tooling decision the team made in the last 90 days, reverse-chronological, with the alternatives that lost. Stops the new hire from re-litigating settled debates in their first PR.

// template (matches T02 ADR format)

# Recent Decisions (last 90 days)

## ADR-[NNN] · [YYYY-MM-DD] · [title]
**Decision:** [what we chose, one sentence]
**Context:** [2–3 lines on the situation]
**Alternatives we rejected:** [each, one line, with WHY it lost]
**Revisit when:** [the trigger condition that would re-open this]

// example lines (real shape)

## ADR-041 · 2026-04-12 · Don't migrate to MongoDB
**Decision:** Postgres + JSONB columns for the flexible-schema use case.
**Context:** Sales-eng kept asking for Mongo because Atlas has the connectors
they want. We benchmarked both for our actual query shapes.
**Alternatives rejected:**
- MongoDB Atlas — lost on join-heavy reporting queries (3x slower at our scale).
- DynamoDB — lost on transactional consistency for the billing path.
**Revisit when:** if reporting queries grow past 50/sec and we can't make them fast.

## ADR-038 · 2026-03-28 · Auth rewrite paused
**Decision:** Pause the OIDC-rewrite branch indefinitely. Ship feature work
against the existing SAML implementation.
**Context:** Our OIDC vendor pivoted away from B2B. Continuing the rewrite means
re-shopping vendors, and we have 8 weeks of customer roadmap that doesn't need it.
**Alternatives rejected:**
- Finish the rewrite anyway — lost on opportunity cost.
- Self-host an OIDC provider — lost on maintenance burden vs. value.
**Revisit when:** Q4 planning, or if a customer blocks renewal on OIDC support.

// without this, the new hire's first design proposal reopens a debate we settled in March. Day-3 read.

// 01e · who-is-who.md — relationship map, not org chart

One row per teammate. What they own. What they're allergic to. Async vs. sync preference. Timezone. Vacation week. This is not the org chart on the wiki — it's the texture you'd pass to a friend joining the team. Saved for Week-2 because relationships only matter after you've worked with people; reading it on day one is just names.

// template

# Who is Who

## [name] · [role]
- **Owns:** [systems, decisions, customer accounts]
- **Allergic to:** [the things they push back on hard, with one-line why]
- **Async / sync:** [preference + when they're heads-down]
- **Timezone:** [tz + working hours]
- **Out:** [planned vacation / leave windows in next 90 days]
- **Best way to ask:** [Slack DM / async thread / scheduled 1:1]

// example row (real shape)

## Priya Iyer · Staff Engineer, ingest + storage

- **Owns:** rb-ingest, the Postgres tier, the data-retention policy,
  every Joint Commission audit response since 2024.
- **Allergic to:** Mongo proposals (see ADR-041), "let's just add a queue",
  surprise schema migrations on Fridays. Push back nicely — she's usually right.
- **Async / sync:** Strong async. Mornings are heads-down 9–noon PT, do not
  Slack-DM with anything urgent in that window unless prod is on fire.
- **Timezone:** PT (Seattle). 9–5 PT.
- **Out:** 2026-06-14 to 2026-06-21 (out of office, no laptop).
- **Best way to ask:** Async thread in #ingest with the question + what you've
  already tried. She'll respond same-day. Schedule a 1:1 only after the thread.

// without this, the new hire DMs Priya at 10am with a "quick question" and burns her flow state. Week-2 read.

// prompt 1 · the codebase tour

// paste verbatim

You have read team-identity.md, customer-context.md, and stack-map.md.

What's the simplest path through our codebase from a customer click to
a database write? Walk me through the layers, naming the file each one
lives in. Where multiple files apply, pick the canonical example.

Cite stack-map.md for service boundaries; if a file isn't in stack-map.md,
say "not in the stack map" rather than guessing.

Good answer: 5–7 layers, each with a real filename from stack-map.md. Acknowledges any layer it can't find rather than fabricating it.

Bad answer: Generic MVC walkthrough with invented filenames (controllers/UserController.ts) that don't exist. Failure mode = the AI defaults to internet-average architecture instead of yours. Mitigation: re-prompt with "I don't have those files. Re-answer using only the services listed in stack-map.md."

// prompt 2 · who do I ask

// paste verbatim, with $X replaced

You have read who-is-who.md.

Who do I ask about $X? Match my question to the right teammate using
who-is-who.md. If you can't find a clear match, say so — don't guess
a name. If two teammates could plausibly own this, recommend the async
thread location instead of picking one.

Also tell me HOW to ask them: async thread / Slack DM / scheduled 1:1,
and whether now is a bad time (e.g. heads-down window or out-of-office).

Good answer: Names one teammate, cites the row in who-is-who.md, picks the right channel and flags any timing issue ("she's heads-down until noon PT — thread it, don't DM").

Bad answer: Hallucinates a name not in the file. This is the most common failure of the whole module. Mitigation: every who-is-who.md row should include the exact role string the AI can match on. If the AI returns a name you didn't recognise, treat it as a red flag and re-prompt: "Show me the row in who-is-who.md you used. If there isn't one, say 'no clear owner' and suggest where to post the question."

// prompt 3 · what would a senior reviewer push back on

// paste verbatim, with $task replaced

You have read recent-decisions.md.

What would a senior reviewer push back on if I shipped a PR doing $task?
Use recent-decisions.md to ground the answer in actual team history —
cite the ADR number for each pushback. If the task doesn't touch any
recent decision, say so honestly rather than inventing concerns.

Rank the pushbacks by likelihood, not severity.

Good answer: 2–4 concrete pushbacks, each citing an ADR ("ADR-041 — you're proposing a NoSQL store; this team explicitly chose Postgres+JSONB on 2026-04-12"). The new hire walks into the PR pre-aware.

Bad answer: Generic code-review checklist (tests! comments! naming!) instead of team-specific concerns. Failure mode = the AI fell back on training-data priors. Mitigation: the prompt explicitly demands ADR citations; if none appear, the answer is invalid.

// day 1 · ~45 min total

• 15 min: Read team-identity.md and customer-context.md end to end.
• 10 min: Load both files into the new hire's AI session. Run Day-1 prompts 1 and 2 (codebase tour + who-do-I-ask, with a sample $X = "billing webhooks").
• 30 min (concurrent / after): 1:1 with the onboarding buddy. Q+A only — no demo, no tour, no slide deck. The new hire drives the questions; the buddy fills the gaps the brain didn't.

// artifact: the new hire posts a 3-bullet "what I learned about our ICP today" in #onboarding. The buddy reacts with green check. Onboarding lead sees both and knows day 1 worked.

// day 3 · ~1 hour total

• 20 min: Read stack-map.md and recent-decisions.md.
• 10 min: Run Day-1 prompt 3 against a candidate first-PR task ("what would a senior reviewer push back on?").
• 15 min: Pick a "first PR" candidate from the backlog — ideally a tagged good-first-issue or a known small fix. The brain's Section 4 prompt (below) shapes how the new hire approaches it.
• 15 min: Async thread with the owner of the area you're touching. Format: "I'm picking up $task. From recent-decisions.md I read ADR-038 about $relevant. Two questions before I start: ..." — this proves the brain was read and respects the owner's time.

// artifact: the async thread itself. The owner's response is the green light. If the new hire asks a question the brain already answered, the onboarding owner notes the gap for Section 5.

// week 2 · ~30 min

• 15 min: Read who-is-who.md in full. Saved for now because relationships only register after you've actually worked with people; reading it cold on day 1 is just memorising names.
• 15 min: Run the contribute-back prompt (Section 5) and ship its output to the onboarding owner.

// artifact: the 5-item gap list goes to the onboarding owner. Their job is to fold it into the kit before the next hire reads it. Onboarding becomes a versioned read.

// the prompt — paste verbatim, fill $task

I'm a new hire on day 3. Here's the task: $task.

You have read team-identity.md, customer-context.md, stack-map.md,
recent-decisions.md, and who-is-who.md.

Walk me through:

(a) Which files I'll touch. Cite stack-map.md; flag anything on the
    "don't touch (yet)" list.
(b) What recent-decisions.md says about this area. Quote the relevant
    ADR(s) verbatim — don't paraphrase.
(c) Which patterns from stack-map.md apply. Name the pattern file.
(d) Which teammate (from who-is-who.md) is most likely the senior
    reviewer on this PR, and what they specifically care about
    (allergies + ownership).

Then ask me 3 clarifying questions before I start writing code.
Make them questions whose answers would change the design, not
the implementation.

Why it works: the new hire arrives at the first PR pre-armed with team context, ADR citations, and an awareness of who reviews. The reviewer's job becomes actual code review, not orientation. The 3 clarifying questions also surface ambiguity early — before 200 lines of doomed code.

Anti-pattern: "Just get something open as a PR and we'll review it." The new hire makes design calls in isolation; the senior reviewer ambushes them at PR time with "we don't do it this way, see ADR-038." The new hire learns that decisions live in people, not in the team. The brain breaks that loop.

// the prompt — paste verbatim at end of week 2

I'm finishing week 2. Help me audit our team brain.

List 5 things I had to ask a teammate that I wish the team brain
had told me. For each, categorize as one of:

- missing-from-existing-file — should have been in one of the 5 files
- needs-new-file — doesn't fit any existing file; the kit has a gap
- only-makes-sense-once-you've-been-here — tribal knowledge that
  resists documentation; flag for the buddy script instead

For each, draft one sentence of how it would have appeared in the brain.

Why: the new-hire perspective is the most honest audit your team brain ever gets — they notice gaps experienced teammates have stopped seeing. Their context-window is small, recent, and unfiltered by familiarity.

The receiver: output goes to the onboarding owner — a rotating role, typically the most recent prior hire (they remember the gaps; they have the lowest cost to merge them in). They have one week to fold the additions into the bootstrap kit before the next hire reads it.

// the kit gets better every hire. Onboarding becomes versioned, not vibes.

// path A · filesystem clone on day 1

How: the team-brain lives in a Git repo (or a synced Drive folder). The new hire clones it on day 1; their filesystem agent (Claude Code, Cursor, Copilot Agent, Codex CLI) reads the files locally via repo-root CLAUDE.md / AGENTS.md wrappers. Setup is one git clone.

// pros

• Fast. Local file reads, no network round-trip per prompt.
• Private. Files never leave the laptop's filesystem.
• Works offline. Useful for new hires onboarding from planes / cafés.
• Versioned via Git — the contribute-back loop is just a PR.

// cons

• Setup friction. New hire must have a filesystem agent installed before day 1.
• CLI literacy required. Bad fit for roles whose tooling is browser-only (sales, support, ops).

// path B · shared Project they're added to

How: the five files live in a shared ChatGPT / Claude / NotebookLM Project. The onboarding owner adds the new hire to the Project on day 0; their AI loads the files automatically every session, no upload step. New hire opens the browser and starts asking.

// pros

• Zero setup. No git, no install — just an invite.
• Works for non-technical roles. Browser-only.
• Central source of truth — updates propagate to everyone in the Project.

// cons

• Requires team-tier subscription on whichever provider you pick.
• Lock-in: the Project's owned by one vendor. Migrating means re-uploading.
• The contribute-back loop is manual (edit-in-Project) rather than versioned.

// path C · hosted onboarding portal

How: a small internal web-app wraps the five files plus the Day-1/3/Week-2 prompts in a guided UI. New hire logs in, clicks through the ritual cards, runs prompts via an embedded chat. Never sees the underlying markdown.

// pros

• Lowest friction for the new hire — the kit is a guided walkthrough, not a homework assignment.
• Observable: portal logs which prompts ran, which weren't. Onboarding owner sees blockers in real time.
• Easy to add gates (acknowledge ADR-041, mark customer-context as read) for compliance-heavy teams.

// cons

• Most build effort. Realistically only worth it past 50 hires/year.
• Another internal tool to maintain. Stalls the moment the engineer who built it leaves.
• The portal becomes the source of truth, then drifts from the markdown — pick one home and stick to it.

// decision matrix — which path

Pick by intersection of (team size) × (existing tooling) × (new-hire technical fluency).

Team < 10 + engineering-heavy + Git native
  → Path A. The wrapper-file approach is free.

Team 10–50 + mixed roles + already on Claude/ChatGPT Team
  → Path B. The Project lock-in is worth the zero-setup win.

Team > 50 + compliance-adjacent industry + > 20 hires/year
  → Path C. The portal's build cost amortises.

Engineering team + non-eng new hire (e.g. sales joining)
  → Path B even if rest of team is on Path A. Mix paths
       by role — the kit is portable.

// most teams should start Path A or B. Path C is a "we've onboarded 50 people and it's a real cost" answer, not a "let's build it because it's cool" answer.

// the new hire who's productive by Friday

• The 5 files — team-identity, customer-context, stack-map, recent-decisions, who-is-who — are the bootstrap kit. Read them in that order. Each presumes the one before.
• The three Day-1 prompts ground the AI in your files, not its training data. If an answer doesn't cite a file, the answer is invalid — re-prompt.
• Day-1 / Day-3 / Week-2 rituals turn the read into a contribution. Each milestone ships an observable artifact, so onboarding is measurable instead of vibes.
• The first-PR prompt prevents ambush reviews. The new hire arrives pre-armed with ADR citations. The reviewer's job becomes code review, not orientation.
• The Week-2 contribute-back prompt is the highest-leverage edit the brain ever gets. Fold every gap before the next hire reads — onboarding becomes versioned.