Skip to main content

​
Overview

Instructions tell TierZero how to reason about your systems, ownership model, and operating conventions. TierZero supports two instruction scopes:
  • Organization-wide instructions: Global guidance that applies across the organization
  • Team instructions: Team-specific guidance that applies when TierZero is working in that team’s context
Together, these give TierZero the baseline context it should always follow plus the local nuances that matter for a specific team.

​
TierZero.md

Organization-wide instructions are stored in TierZero.md. This is the main instruction file TierZero should follow when handling requests across your organization.

​
What to Include

A well-structured TierZero.md should include sections like: Company High-level description of what your company does and the products you offer. This helps TierZero understand the business context of issues. Customer Blast Radius How to correlate logs, traces, metrics, and other observability data with:
  • The set of customers affected by an issue
  • The subset of environments affected, such as sharded infrastructure by region or cell
Environment How to identify the production environment in logs, tags, traces, and infrastructure naming. Include a brief description of your deployment setup. Infrastructure as Code Whether infrastructure is deployed as code, where it is defined, and whether there are important production resources not defined in code. Code Release and Deployment How services are released, how infrastructure changes roll out, and whether non-deployment feature releases such as feature flags are used.

​
Sample TierZero.md

### Company
Acme Corp is a SaaS platform that provides project management and collaboration tools for distributed teams. Our core products are:
- **Acme Projects**: Task and project management
- **Acme Docs**: Real-time collaborative documents
- **Acme Chat**: Team messaging and video calls

### Customer Blast Radius
Customers are identified by `org_id` in logs and traces. We use regional sharding:

| Tag/Attribute | Data Source | Description |
|---------------|-------------|-------------|
| `org_id` | Logs, Traces | Customer organization identifier |
| `region` | Logs, Metrics | Geographic region (us-east, eu-west, ap-south) |
| `cell_id` | Logs, Traces | Infrastructure cell within a region |
| `tier` | Logs | Customer tier (free, pro, enterprise) |

Enterprise customers (tier=enterprise) are on dedicated cells. Free/Pro customers share multi-tenant cells.

### Environment
Production runs on AWS EKS across three regions:
- `us-east-1` (primary)
- `eu-west-1` (EU customers)
- `ap-south-1` (APAC customers)

Identify production in observability data:
- Logs: `env:prod*` or `environment:production`
- Kubernetes namespace: `prod-*`
- Database instances: `prod-aurora-*`

### Infrastructure as Code
All infrastructure is defined in Terraform:
- Repository: `acme/infrastructure`
- Directory: `terraform/environments/prod/`

Exceptions not in IaC:
- DNS records managed in Cloudflare UI
- Some legacy Lambda functions in `acme/legacy-functions`

### Code Release and Deployment
- Services deploy via GitHub Actions -> ArgoCD
- Deployments roll out via canary (10% -> 50% -> 100%)
- Feature flags managed in LaunchDarkly
  - Flag naming: `feature.<team>.<feature-name>`
  - Query flags: `source:launchdarkly @flag.key:*`

​
Team Instructions

Team instructions let you tailor TierZero’s behavior for individual teams. Use them when different teams have:
  • Different services and ownership boundaries
  • Different escalation paths
  • Different runbook conventions
  • Different tool preferences

​
How to Set Up Team Instructions

  1. Open Instructions from the left navigation
  2. In the sidebar, click <your_team_name>.md
  3. Edit the markdown for that team
  4. 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

​
Organization vs Team Instructions

Organization InstructionsTeam 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
  • Avoid duplicating the same material in both places
  • Put global conventions in TierZero.md and local nuance in team instructions
2. Include Real Examples
  • Mention specific service names, dashboard URLs, Slack channels, and identifiers
  • Real references help TierZero navigate your systems accurately
3. Update After Incidents
  • After a significant incident, add new debugging learnings and escalation notes
  • This builds institutional knowledge over time
4. Keep It Focused
  • Include the most important instructions and identifiers
  • Reference long runbooks or dashboards instead of copying them wholesale