> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tierzero.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Instructions

> Configure TierZero.md and team-specific instructions for TierZero

## 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`

```markdown theme={null}
### 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**

```markdown theme={null}
## 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**

```markdown theme={null}
## 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**

```markdown theme={null}
## 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**

```markdown theme={null}
## 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