Instructions

Overview

Instructions tell TierZero how to reason about your systems, ownership model, and operating conventions. TierZero supports two instruction scopes:

TierZero.md: 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

TierZero.md is the main instruction file TierZero follows 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

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

TierZero.md vs Team Instructions

	TierZero.md	Team Instructions
Scope	Entire organization	Single team
Content	Architecture overview, global conventions, org-wide context	Team-specific services, escalation paths, debugging tips
When applied	Every investigation	Requests that pertain to the team’s ownership, services, or domain — TierZero determines relevance based on the team’s description
Who edits	Admins	Team members

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

Getting Started

Features

Knowledge & Tuning

Prompt Library

Integrations

Administration

References

Overview

TierZero.md

What to Include

Sample `TierZero.md`

Team Instructions

How to Set Up Team Instructions

What to Include

TierZero.md vs Team Instructions

Best Practices

​Overview

​TierZero.md

​What to Include

​Sample TierZero.md

​Team Instructions

​How to Set Up Team Instructions

​What to Include

​TierZero.md vs Team Instructions

​Best Practices

Overview

TierZero.md

What to Include

Sample `TierZero.md`

Team Instructions

How to Set Up Team Instructions

What to Include

TierZero.md vs Team Instructions

Best Practices