Skip to content

Source Tier System

Every Mandatory item in vibecodingisold must cite at least 2 Tier-1 primary sources. Tier-2 may supplement but never replace. Tier-3 is forbidden.

The canonical tier index is at .planning/worker-briefings/_shared/source-tier-index.md. When proposing a new source for a tier classification, that's the file to update.

Tier 1 — Primary Operator Sources (always acceptable)

Sources written by senior engineers who solved the problem in production at scale. These are the only sources that can stand alone as the primary citation for a Mandatory item.

Engineering organizations

  • AWS Builders Library — primary patterns: timeouts, retries, backoff, caching, distributed locks, queue design, health checks. https://aws.amazon.com/builders-library/
  • Google SRE Book + SRE Workbook — primary patterns: SLOs, error budgets, incident response, observability, on-call. https://sre.google/books/
  • Stripe Engineering Blog — primary patterns: API design, idempotency, payment systems, webhooks, observability. https://stripe.com/blog/engineering
  • GitHub Engineering Blog — primary patterns: Git infrastructure, MySQL at scale, API rate limiting, DDoS, deploy systems. https://github.blog/category/engineering/
  • Discord Engineering Blog — primary patterns: real-time messaging, Cassandra/ScyllaDB, Elixir patterns, voice/video infra.
  • Cloudflare Blog — primary patterns: DDoS, edge computing, TLS, DNS, security incidents. https://blog.cloudflare.com/
  • Netflix TechBlog — primary patterns: chaos engineering, microservices, fault tolerance, A/B testing infra.
  • Uber Engineering — primary patterns: geo systems, Cadence/Temporal, distributed systems.
  • Airbnb, Meta, Shopify, Notion, Figma, Linear, Spotify — see the canonical index for the per-org primary patterns.

Standards & specifications

  • OWASP ASVS (Application Security Verification Standard) — current version 4.0+.
  • OWASP MASVS (Mobile Application Security Verification Standard).
  • OWASP API Security Top 10 — current version.
  • CIS Benchmarks — for AWS, Azure, GCP, Kubernetes, Docker, Linux distros.
  • NIST 800-53 (security controls), NIST 800-63B (digital identity), NIST 800-57 (key management).
  • RFC documents (HTTP semantics, OAuth 2.1, JWT BCP, Problem Details, Webhook standards).
  • PostgreSQL official documentation.
  • CNCF Project documentation for Kubernetes, Prometheus, Envoy, etcd.

Senior-engineer reference texts (chapter-citable)

  • Kleppmann "Designing Data-Intensive Applications" (2017, with errata) — cite as "DDIA Ch. N, Section X".
  • Site Reliability Engineering (Beyer et al., 2016) — citable chapters.
  • The Site Reliability Workbook (Beyer et al., 2018).
  • Database Internals (Petrov, 2019) — for storage internals.
  • The Twelve-Factor App — https://12factor.net/.

Primary postmortems & incident retrospectives

Tier 2 — Supplementary (may add to Tier 1, not replace)

Useful for context, secondary citations, framing — but cannot stand alone as the primary citation for a Mandatory item.

Tier-2 sources include:

  • High-quality individual engineering blogs by named senior engineers (e.g., Brandur Leach, Marc Brooker, Martin Kleppmann's blog posts outside DDIA).
  • Conference talks from named engineering events (KubeCon, SREcon, QCon, Strange Loop) by named operators.
  • Vendor documentation that's well-written but isn't a standards document (e.g., vendor-specific SDK docs, ORM documentation, framework guides).
  • Well-known open-source projects' README + ARCHITECTURE files (Kubernetes, Prometheus, Linkerd, Envoy, Postgres extensions).

A Tier-2 source can pair with a Tier-1 source to provide implementation detail. It cannot substitute for a Tier-1 source as the primary citation for a Mandatory item.

Tier 3 — Forbidden

These are sources that must not appear as citations in any Mandatory item. They appear here as the explicit exclude-list:

  • Stack Overflow answers. Useful for debugging, not for canonical-knowledge citation. (Exception: an SO answer that links to a Tier-1 source can be cited via that source — the citation is the underlying source, not the SO post.)
  • Medium posts by individuals without engineering-org backing (unless the individual is a named senior engineer and the post is on a Tier-2 surface like their personal engineering blog).
  • Tutorials on personal blogs without named-author senior-engineer backing.
  • AI-generated content (LLM-written articles, summaries, etc.) — even when factually correct, the citation chain is broken.
  • Vendor marketing pages (as opposed to vendor documentation). Marketing makes claims; documentation provides the contract.
  • Wikipedia. Useful for orientation, not for canonical-knowledge citation. (Wikipedia citations point at primary sources; cite those directly.)
  • Anonymous or pseudonymous sources without a verified track record.
  • Outdated documentation (e.g., Postgres 9.x docs for items targeting Postgres 14+).

Why this discipline matters

Two reasons:

  1. Authority chain. When vibecodingisold claims "idempotency on state-changing routes is Mandatory because Stripe's 2017 blog post documented the failure mode + the production fix," that claim is auditable. A reader can follow the citation, read the original, and challenge the item if the citation doesn't actually say what we claim. Tier-3 sources break this chain — they're not authoritative, often anonymous, often outdated.
  2. AI-tool resistance. AI-coding tools rapidly absorb Tier-3 content (Stack Overflow answers, tutorial blog posts) and produce confident-sounding code based on it. The whole point of vibecodingisold is to inject senior-engineer judgment that the AI tool wouldn't reach for on its own. If our items cited the same Tier-3 sources the AI was trained on, we'd add no signal.

The discipline is not academic. It's the operational moat that makes the items worth more than what the AI tool would generate from its own training.

How sources are validated

Three layers:

  1. Worker-side, at item-write time. Workers producing items must cite >=2 Tier-1 sources from the index. The Worker-self-verification step (every role file has a <role>.md_sources.md companion file listing every cited URL with tier) catches accidental Tier-2-replacing-Tier-1 errors before they reach Brain review.
  2. Brain-side, at quality-gate time. Phase 2 review checks every item's citations against the tier index. Items with <2 Tier-1 sources are rejected back to the Worker.
  3. CI-side, at merge time. The validate-items.py validator at .github/scripts/ checks every Mandatory item's citation count and tier compliance. PRs that introduce sub-spec items fail the gate.

You can run the validator locally:

python .github/scripts/validate-items.py

How to propose a new Tier-1 source

If you find a high-quality source not yet in the canonical index:

  1. Open a GitHub issue titled Tier-1 source proposal: <source name>.
  2. Include: the source URL, the org/individual behind it, the primary patterns it covers, sample posts/articles to evaluate.
  3. The maintainer reviews and either adds to the canonical index (.planning/worker-briefings/_shared/source-tier-index.md) or explains why it's better classified as Tier-2.

Bias for adding sources, not against. The Tier-1 list is intentionally broad — most named senior-engineering blogs at known engineering orgs qualify.

How to challenge a Tier-1 source classification

If you believe a current Tier-1 source has degraded (org dissolved, blog abandoned, content quality dropped, post turned out to be wrong in a way relevant to a cited item):

  1. Open a GitHub issue titled Tier-1 source challenge: <source name>.
  2. Include: the specific source post(s) being challenged, the items currently citing them, and the concrete reason the source is no longer authoritative.
  3. The maintainer reviews and either re-tiers the source or defends the existing classification.

This process keeps the citation chain robust over time. Sources don't stay good forever; the discipline has to be maintainable.