Skip to main content

​
What are Per-Team Instructions?

Per-team instructions let you tailor TierZero’s behavior for individual teams. While TierZero.md provides organization-wide context, per-team instructions add team-specific knowledge that makes investigations more relevant and accurate.

​
When to Use Per-Team Instructions

Use per-team instructions when different teams have:
  • Different services and ownership boundaries, such as the Payments team owning different services than the Platform team
  • Different escalation paths, including who to page and what channels to use
  • Different runbook conventions, reflecting how each team prefers incidents to be handled
  • Different tool preferences, such as one team using Datadog dashboards while another uses Grafana

​
How to Set Up

  1. Navigate to Settings → Teams
  2. Select the team you want to configure (or create a new team)
  3. Click Edit Instructions
  4. Write team-specific context in markdown
  5. Click Save
The instructions take effect immediately for all agents associated with that team.

​
What to Include

​
Service Ownership

## Services We Own
- **payment-service**: Handles all payment processing (Go, deployed on EKS)
- **billing-api**: Subscription management and invoicing (Python, deployed on EKS)
- **payment-gateway**: External payment provider integration (Go)

## Key Dependencies
- PostgreSQL (RDS) for transaction data
- Redis for idempotency keys
- Stripe API for payment processing

​
Escalation Procedures

## Escalation
- SEV1: Page @payments-oncall immediately, notify #payments-incidents
- SEV2: Post in #payments-alerts, oncall will triage within 15 minutes
- SEV3: Create a Jira ticket in the PAYMENTS project

​
Team-Specific Debugging

## Common Issues
- Payment timeouts are usually caused by Stripe API latency — check Stripe status page first
- If billing-api returns 500s, check the subscription_events table for stuck records
- Redis connection errors usually resolve with a pod restart — check if the Redis cluster is healthy first

​
Dashboard and Runbook References

## Key Dashboards
- Payment Processing: https://app.datadoghq.com/dashboard/abc-123
- Stripe Integration Health: https://app.datadoghq.com/dashboard/def-456

## Runbooks
- Payment Failover: https://notion.so/team/payment-failover-runbook
- Stripe Outage Response: https://notion.so/team/stripe-outage-playbook

​
Per-Team vs TierZero.md

TierZero.mdPer-Team Instructions
ScopeEntire organizationSingle team
ContentArchitecture overview, global conventions, org-wide contextTeam-specific services, escalation paths, debugging tips
When appliedEvery investigationOnly for that team’s agents and investigations
Who editsAdminsTeam leads or admins

​
Best Practices

1. Keep It Complementary
  • Don’t duplicate content from TierZero.md; reference it instead
  • Focus on what makes this team’s context unique
2. Include Real Examples
  • Mention specific service names, dashboard URLs, and Slack channels
  • Real references help TierZero navigate your systems accurately
3. Update After Incidents
  • After a significant incident, add debugging learnings to the team’s instructions
  • This builds institutional knowledge over time
4. Review Quarterly
  • Services change, teams restructure, and conventions evolve
  • Schedule a quarterly review to keep instructions current