sacco-cross-team-collaboration

Cross-Team Collaboration

When to Collaborate

When you hit a boundary — security, ownership, or expertise — that isn't yours to cross, don't try to solve it yourself. Communicate what you need and let the owning team decide how.

Writing an Effective Brief (GitHub Issue)

A well-researched proposal gets fast buy-in. Invest in the quality of the ask.

Structure

## Context
Why this matters. What problem you're solving. What you've already done.

## Proposal
The specific approach you recommend, with enough detail for the other team
to evaluate without needing a meeting.

## Alternatives Considered
Table of approaches you evaluated and why each was rejected.
Shows you've done the work and respects the other team's time.

| Approach | Problem |
|----------|---------|
| Option A | Why it doesn't work |
| Option B | Why it doesn't work |

## What We Need
Specific, actionable items. Not "help us with schemas" but:
1. Define artifact convention
2. Add publish step to CI
3. Tag strategy so consumers can pin

## Consumption Side
Show how you'll use what they provide. Defines the contract.

## Timeline
Are you blocked? Can you ship with a workaround? Be honest.

Principles

• Respect ownership — Describe what you need, not how they should implement it.
• Show your work — List alternatives considered and rejected. Proves you've thought it through.
• Be specific — "Publish CRD schemas as OCI artifacts" not "help with validation."
• Include the consumer side — Show the exact code/config you'll use. Defines the contract.
• State timeline honestly — "Not blocking, shipping with a workaround" beats false urgency.

Tracking Dependencies

• Reference cross-repo issues in commit messages: pending infra (Org/infra#15)
• When shipping with a workaround, add a code comment linking to the issue.
• Follow up — check for responses and adapt based on their timeline.

Creating Issues

Use gh issue create with the full brief structure:

gh issue create --repo <org>/<repo> \
  --title "Short, actionable title" \
  --body "$(cat <<'EOF'
## Context
...
## Proposal
...
## Alternatives Considered
...
## What We Need
...
## Consumption Side
...
## Timeline
...
EOF
)"

Anti-Patterns

• Solving other teams' problems — Don't write their CI pipeline. Write a clear brief.
• Crossing security boundaries — Don't request cross-repo tokens to avoid talking to the other team.
• Vague asks — "Can you help with schemas?" gets deprioritized. Specific asks get fast action.
• Skipping the research — If you haven't evaluated alternatives, you haven't earned the right to ask another team for work.