Managing Cross-Team Dependencies — When Your Feature Needs Three Other Teams to Ship

Common dependency failure patterns:

1. Assumed alignment that never existed
   → "Platform said they'd have it ready by week 3"
   → Platform said "we'll look at it" — heard as a commitment
   → No ticket, no deadline, no owner on their side

2. Late discovery
   → Dependency discovered in week 4 of a 6-week project
   → Not enough time to negotiate timeline or find alternative

3. Spec mismatch
   → Platform built what they thought you needed
   → Not what you actually need
   → 3 weeks to fix vs 3 days if caught in week 1

4. Priority conflict
   → Your dependency is low priority for the other team
   → They have three P1 items; your request is P3
   → You didn't escalate until it was too late to escalate

5. No interface contract
   → Built against informally agreed API
   → API changed between agreement and delivery
   → No way to detect the change until integration

// Before writing a line of code: map all dependencies
interface Dependency {
  type: 'api' | 'schema' | 'data' | 'infrastructure' | 'design' | 'legal'
  provider: string  // Team name
  deliverable: string
  neededBy: Date
  blocksUs: boolean  // Can we progress without it?
  contactOwner: string
  status: 'not started' | 'in design' | 'in progress' | 'ready' | 'at risk' | 'blocked'
  ticket?: string
  alternativeIfBlocked?: string
}

const projectDependencies: Dependency[] = [
  {
    type: 'api',
    provider: 'Platform Team',
    deliverable: 'User preference API endpoints',
    neededBy: new Date('2026-03-28'),
    blocksUs: true,
    contactOwner: '@alice',
    status: 'in design',
    ticket: 'PLAT-1234',
    alternativeIfBlocked: 'Mock the API with our own implementation, migrate later',
  },
  {
    type: 'schema',
    provider: 'Data Team',
    deliverable: 'Add user_preferences table to data warehouse',
    neededBy: new Date('2026-04-04'),
    blocksUs: false,  // We can ship without this — analytics is non-blocking
    contactOwner: '@bob',
    status: 'not started',
    ticket: undefined,  // ← No ticket yet! Action needed.
    alternativeIfBlocked: 'Skip analytics for V1, add in V2',
  },
]

// Before kickoff: every dependency has a ticket, an owner, and a status
// Any without tickets: create them immediately

// Don't wait for the dependency — define the interface together, build in parallel

// Step 1: Define the API contract (OpenAPI / TypeScript interface)
// Done jointly with the providing team in week 1

// user-preferences-api.ts — interface contract agreed upfront
export interface UserPreferencesAPI {
  getPreferences(userId: string): Promise<UserPreferences>
  updatePreferences(userId: string, preferences: Partial<UserPreferences>): Promise<UserPreferences>
  resetPreferences(userId: string): Promise<void>
}

export interface UserPreferences {
  theme: 'light' | 'dark' | 'system'
  emailNotifications: boolean
  language: string
  timezone: string
}

// Step 2: Build a mock implementation immediately
// Your team can proceed; Platform team builds the real thing in parallel

class MockUserPreferencesAPI implements UserPreferencesAPI {
  private store = new Map<string, UserPreferences>()

  async getPreferences(userId: string): Promise<UserPreferences> {
    return this.store.get(userId) ?? {
      theme: 'system',
      emailNotifications: true,
      language: 'en',
      timezone: 'UTC',
    }
  }

  async updatePreferences(userId: string, prefs: Partial<UserPreferences>): Promise<UserPreferences> {
    const current = await this.getPreferences(userId)
    const updated = { ...current, ...prefs }
    this.store.set(userId, updated)
    return updated
  }

  async resetPreferences(userId: string): Promise<void> {
    this.store.delete(userId)
  }
}

// Step 3: Swap mock for real when the Platform team delivers
// If they're late, the mock continues to work — no project impact
const userPreferencesAPI: UserPreferencesAPI = process.env.USE_REAL_PREFERENCES_API
  ? new RealUserPreferencesAPI()
  : new MockUserPreferencesAPI()

// Don't assume dependencies are on track — track them explicitly
// A dependency that's "fine" in week 2 might be "at risk" in week 3

// dependency-tracker.ts — review every Monday
async function weeklyDependencyReview(projectId: string): Promise<DependencyReport> {
  const deps = await getDependencies(projectId)
  const atRisk: Dependency[] = []
  const blocked: Dependency[] = []

  for (const dep of deps) {
    const weeksUntilNeeded = Math.ceil(
      (dep.neededBy.getTime() - Date.now()) / (7 * 24 * 60 * 60 * 1000)
    )

    // Flag if dependency won't be ready in time
    if (dep.status === 'not started' && weeksUntilNeeded < 3) {
      atRisk.push(dep)
    }

    if (dep.status === 'blocked') {
      blocked.push(dep)
    }
  }

  // Post to project channel every Monday
  await notify.projectChannel({
    message: `📊 Weekly Dependency Check`,
    blocked: blocked.map(d => `🔴 ${d.provider}: ${d.deliverable}`),
    atRisk: atRisk.map(d => `🟡 ${d.provider}: ${d.deliverable} needed in ${getWeeksUntil(d.neededBy)}wk`),
    onTrack: deps.filter(d => !atRisk.includes(d) && !blocked.includes(d)).length,
  })

  return { atRisk, blocked }
}

When a dependency is at risk: escalate early and gracefully

Week 3 (3 weeks before you need it):
→ Direct message to your contact: "Hey @alice, just checking in on PLAT-1234.
   We need it by March 28 — are you still on track?"
→ Low pressure, information gathering

Week 5 (1 week before you need it, not on track):
→ Private message to both your contact and their manager:
   "Hi, I want to flag that PLAT-1234 is needed by March 28 for our feature launch.
   Current status shows not started. Can we sync today to either confirm the timeline
   or discuss an alternative? Happy to help scope it down if that helps."

If still blocked:
→ Escalate to your own manager: "I need help unblocking this dependency.
   Here's the situation, here's the impact if we don't have it, here's what I've tried."
→ Let your manager engage their counterpart — manager-to-manager conversations
   can move things that engineer-to-engineer conversations can't

Frame: "Help me understand the constraints so we can find a path"
Never: "You're blocking us and we're going to miss our deadline because of you"

// The best way to manage dependencies is to need fewer of them
// Architectural patterns that reduce cross-team coupling:

// 1. API contracts in a shared repository
// Both teams can work against the contract without coordination
// Changes require review from both teams (via CODEOWNERS)

// 2. Event-driven loose coupling
// Instead of team A calling team B:
// Team A emits events, team B consumes them
// Decoupled timelines: team B can process events whenever they're ready

// 3. Internal SDKs (libraries, not services)
// Instead of platform team owning an API:
// Platform team publishes a library that your team uses
// Your team ships when you're ready, without waiting for a deploy

// 4. Backend for Frontend (BFF)
// Your team owns your own API layer
// You aggregate from multiple services, but own the contract
// Reduces dependency on platform teams for API shape changes

// 5. Feature flags for progressive rollout
// Instead of waiting for another team's feature to be complete:
// Ship your feature behind a flag
// Enable it when their dependency is ready
// You're not blocked from deploying