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