Knowledge transfer between contractors and in-house teams

A contractor finishes a 6-month engagement. The in-house team takes over. Three months later, they're rediscovering decisions the contractor made on day 12, hitting bugs the contractor knew about, and reverse-engineering the integration with a third-party API the contractor configured.

Knowledge transfer is usually a checkbox: "contractor produced documentation." The output: a 30-page Confluence page nobody reads, sketches of architecture diagrams, and a 90-minute recorded walkthrough.

That's not transfer. It's documentation theater. Real transfer needs structure.

What to transfer

Four categories, each handled differently:

1. Code itself. Already in the repo. Self-documenting if written well.
2. Decisions and tradeoffs. Why X over Y. Not in the code; lost without documentation.
3. External dependencies and credentials. Service accounts, API keys, third-party contacts, vendor relationships.
4. Operational knowledge. What breaks, what to monitor, how to recover.

Decisions — ADRs are the right format

Architecture Decision Records (ADRs) are short documents explaining each significant choice:

## ADR-007: Use ClickHouse for event analytics

### Context
Need sub-second analytics queries on 50M events/month.
Postgres at this scale required complex indexing.

### Decision
ClickHouse with 30-day retention, replicated to S3 for archive.

### Alternatives considered
- BigQuery: too expensive at this volume.
- Druid: too operationally complex for our team size.
- Postgres + TimescaleDB: insufficient query speed.

### Consequences
+ Sub-100ms p95 query times.
- Adds operational complexity.
- Team must learn ClickHouse SQL dialect.

Each ADR is 1-2 pages. The whole project should have 10-30 ADRs covering all non-trivial decisions.

External dependencies — runbooks

Every external integration needs a runbook:

• Service name, what it does, why we chose it.
• Vendor contact (account manager, support contact).
• Where credentials live (vault, name of secret).
• How to rotate credentials.
• Common failures and recovery steps.
• SLA and escalation path.

Runbooks live in the repo, not in Confluence. They're version-controlled and discoverable by the next engineer.

Operational knowledge — the chaos book

What breaks in production, what to do when it does. Each entry:

## Stripe webhook signing failures

### Symptom
Receiving 502s in webhook logs, no events processed.

### Common cause
Webhook signing key rotation in Stripe Dashboard
not synced to STRIPE_WEBHOOK_SECRET in production.

### Resolution
1. Copy current key from Stripe Dashboard → Webhooks.
2. Update vault secret stripe-webhook-secret.
3. Restart webhook-handler service.
4. Replay failed events from last hour via Stripe Dashboard.

### Prevention
Monthly key rotation calendar reminder.

This is the document the on-call engineer reads at 3 AM. Make it skimmable.

Live transfer — not just documents

Documents aren't enough. Schedule 4-8 sessions where the contractor pairs with the in-house engineer on real work:

• Session 1-2: code walkthrough of the most important modules.
• Session 3-4: deployment and infrastructure setup.
• Session 5-6: handle a real incident together (simulated if needed).
• Session 7-8: review pending work and roadmap.

Each session 60-90 minutes. Record them for future reference, but the real value is hands-on.

Onboarding the inheritor before contractor leaves

Best transfer: contractor's last 4 weeks overlap with new engineer's first 4 weeks.

• Week 1: new engineer reads documentation, shadows.
• Week 2: new engineer starts taking small tickets with contractor reviewing.
• Week 3: new engineer takes mid-size work, contractor consults.
• Week 4: new engineer leads, contractor on standby for questions.

By the end of week 4, the new engineer owns the system in practice, not just theory.

Post-transfer retainer

Build a 1-3 month support retainer into the original contract. Low monthly commitment (10-30 hours), available for questions and emergencies. Both sides win:

• Contractor gets predictable revenue beyond the build.
• In-house team has a safety net while ramping up.
• Knowledge gaps surface and get patched in real time.

What doesn't work

• "Write up everything you know." Produces unreadable manifestos.
• One handoff meeting at the end. Information overload.
• Contractor disappears the day after launch. Guarantees regressions.
• Confluence as the only deliverable. Drowns and rots.

Verdict

Real knowledge transfer needs ADRs for decisions, runbooks for dependencies, chaos books for operations, and 4-8 paired sessions of live transfer. Best done with 4 weeks overlap and a follow-up retainer. Cost: 5-10% of project. Avoids 30-50% rediscovery cost in the first year.