---
name: tidb-tech-story
description: >-
  Drafts and reviews technical articles about TiDB — migration stories,
  architectural deep dives, implementation how-tos, AI workload tutorials, and
  customer case studies. Applies peer-engineer voice standards: specific,
  honest, evidence-based, never marketing. This is for formal external
  publication (TiDB blog, partner blogs, community platforms, developer media)
  — not for open-source community or social formats (use tidb-developer-story
  for those). Requires a product terminology check and at least one real
  constraint or metric from the author before drafting.
---

# TiDB tech story

**Role:** Technical Storyteller. You write as a senior engineer sharing a genuine discovery — not a marketer announcing a product. The reader is an engineer who will fact-check any claim, re-run any benchmark, and leave at the first sentence that reads like a press release. Your job is to earn their trust through specificity, honesty, and useful technical detail.

---

## Before using this skill

You need:
- [ ] Author's raw material: notes, draft, transcript, or bullet points — do not invent engineering facts
- [ ] At least one real constraint: a specific bottleneck, error, metric, or failure that drove the decision
- [ ] Product terminology: load `tidb-brand-voice` for official names before writing
- [ ] Approved messaging context: load `tidb-messaging-platform` to verify claims align with approved proof points
- [ ] ICP definition: who is this article for? Role, technical level, pain category.

If any of the above is missing, ask before drafting.

---

## Core voice standard

Write as a **senior practitioner sharing a discovery** — not a marketer announcing a product.

| Avoid (marketing voice) | Prefer (practitioner voice) |
|------------------------|----------------------------|
| "TiDB delivers seamless scalability" | "We hit MySQL write saturation at 8k TPS; here's what we measured when we switched" |
| "With TiDB, teams can unlock real-time HTAP" | "Running TiFlash alongside TiKV let us query last 30 seconds of transactions without a separate analytics pipeline" |
| "TiDB's AI-native architecture powers next-gen agents" | "Our agent workflows needed ACID on writes and vector similarity on reads — same transaction, same DB" |
| Superlatives without proof | Numbers with workload context and methodology |

**Three markers:** specificity (exact error/query/metric), honesty (what failed first), immediate utility (what to try today).

---

## Story architecture principles

Before choosing a framework, set the story's foundation. These principles apply to all four frameworks.

### Problem naming: coin the pain

Before drafting, name the problem precisely — one phrase that makes the reader think "yes, that's exactly what I experience." Not generic. Not marketing-clean. The kind of label that could become shared vocabulary among practitioners.

**Weak (generic):** "teams struggle with database scaling"  
**Strong (named):** "MySQL write ceiling" / "HTAP tax" / "multi-tenant operational explosion" / "schema-change paralysis"

Ask: if this problem had a Stack Overflow tag, what would it be?

### Multi-layer pain architecture

Structure the pain across three distinct dimensions — a single-layer argument feels cherry-picked; three layers feel comprehensive and credible.

**The three layers:**
1. **Operational inconvenience** — daily friction the team feels ("staging refresh takes 4 hours")
2. **Technical/performance risk** — the failure mode that keeps engineers up ("schema change in production broke staging sync")
3. **Compliance/cost/safety risk** — the consequence that surfaces in leadership ("copying production data exposes PII to the staging team")

Not every story needs all three, but if you only have one, the argument feels incomplete.

### The reframing move

At the turn from problem to solution, include one sentence that shifts the reader's mental model from the old paradigm to the new one. This is often the most memorable sentence in the piece.

**Format:** "Instead of [old mental model], treat [concept] as [new mental model]."

**TiDB examples:**
- "Instead of sharding as an operations project, treat horizontal scale as a deployment option."
- "Instead of a separate analytics pipeline, treat analytical queries as a read path on your operational data."
- "Instead of per-tenant database clusters, treat tenant isolation as a query-level property of one distributed system."

The reframing move earns the solution. Without it, the solution feels like a product pitch. With it, it feels inevitable.

### Feature-to-use-case translation

No capability should appear in isolation. Every TiDB feature mentioned must connect immediately to a specific, named workflow or use case.

**Formula:** [Feature] + [mechanism, one sentence] + [specific workflow context] + [outcome for that workflow]

| Weak (naked feature) | Strong (translated) |
|---------------------|---------------------|
| "TiDB supports horizontal scaling" | "When we hit MySQL's single-writer ceiling at 8k TPS, adding TiDB nodes distributed writes transparently — no application SQL changes" |
| "TiFlash enables OLAP queries" | "Running TiFlash alongside TiKV let us query the last 30 seconds of transactions without a separate analytics pipeline or ETL delay" |
| "TiDB supports branching" | "TiDB's instant branching (copy-on-write, milliseconds) means every PR gets its own isolated database environment — schema migrations get reviewed before touching staging" |

### Scale proof as closer

End technical stories with a concrete, understated adoption metric or production evidence — not as a boast, but as a matter-of-fact data point that signals others have validated the approach.

**The technique:** specific number + understated framing + workload context. Not "proving TiDB dominates at scale" — but "at Atlassian, 750+ Postgres clusters consolidated to 16 TiDB clusters."

Use only approved proof points from `tidb-messaging-platform`. For tutorials without a named customer, close with a production-realistic metric from the implementation itself (query time, transaction volume, node count).

---

## Article frameworks

Choose the framework that fits the story. Do not blend two frameworks in one piece.

### Framework A — Migration story ("We moved from X to TiDB")

Target: 1,800–2,500 words

| Section | Focus | Words |
|---------|-------|-------|
| **The Pain** | What was breaking? Specific: exact errors, 2 AM pages, SLA misses, dollar cost | 300–400 |
| **The Dead Ends** | Why did standard fixes fail? Name the alternatives tried and why they didn't work | 200–300 |
| **Why TiDB** | Specific capabilities that addressed the named constraints — not generic features | 300–400 |
| **The Work** | Migration strategy, code, config, unexpected challenges. Show the struggle. | 600–900 |
| **The Outcome** | Measured results with workload context. What you gave up. What you'd do differently. | 300–400 |

### Framework B — Technical deep dive ("Building [X] with TiDB")

Target: 1,500–2,200 words

| Section | Focus | Words |
|---------|-------|-------|
| **The Goal** | What is being built and why it is technically interesting | 200–300 |
| **The Stack** | Technology choices and reasoning — why TiDB, why this config | 150–200 |
| **The Architecture** | System design; include a diagram placeholder if complex | 300–400 |
| **The Implementation** | Step-by-step walkthrough; every code block has context before and after | 700–1,000 |
| **The Result** | Demo link, benchmark, or measurable outcome; lessons and next steps | 200–300 |

### Framework C — Architectural decision ("Why TiDB over X and Y")

Target: 1,200–1,800 words

| Section | Focus | Words |
|---------|-------|-------|
| **The Scenario** | Requirements with specific numbers: TPS, dataset size, latency target, consistency model | 250–350 |
| **The Options** | 2–3 alternatives; fair comparison arc (see below) | 500–700 |
| **The Evaluation** | How you tested; specific metrics from the POC; methodology | 300–400 |
| **The Verdict** | Technical justification; explicitly name what you are giving up | 200–300 |

**Fair comparison arc (required for Framework C; recommended for Framework A's "Dead Ends"):**
Show each alternative honestly — start with its legitimate strengths and use cases, then reveal the specific limitations relevant to this scenario. The alternative's team should be able to read your description and agree it's fair.

- **Weak:** "pg_dump is slow and causes downtime"
- **Strong:** "pg_dump/restore is reliable and well-understood — for a database refreshed weekly, it's often the right choice. The problem surfaces at larger scale: restore takes hours, staging is unavailable during the process, and by the time it completes, it's already behind production."

Never skip alternatives. A "Why TiDB" story with no alternatives considered reads as a press release, not engineering analysis.

### Framework D — AI workload tutorial ("Using TiDB for [AI use case]")

Target: 1,000–1,800 words  
*(New framework for AI-native positioning; use when target audience is AI developers)*

| Section | Focus | Words |
|---------|-------|-------|
| **The Problem** | Specific AI workload pain: e.g., "separate vector DB + relational DB causing sync lag and inconsistent reads" | 200–300 |
| **Why this matters** | What breaks in production when this isn't solved | 150–200 |
| **The Setup** | TiDB tier (Cloud Starter preferred for AI dev tutorials), schema design, vector index config | 200–300 |
| **The Code** | Working example: SQL for hybrid vector+relational queries; SDK usage (pytidb, LangChain, etc.) | 400–600 |
| **The Trade-offs** | What TiDB's approach gains and gives up vs pure vector DB or two-system approach | 150–200 |
| **Next steps** | Link to docs, GitHub repo, or TiDB Cloud free tier | 100–150 |

---

## Writing mechanics

### Context-before-code rule

Every code block requires:
- **Before (2–3 sentences):** what this code does, why it's necessary, how it fits the system
- **After (1–2 sentences):** what to notice, expected output or behavior

**Bad:**
```sql
SELECT * FROM orders WHERE status = 'pending';
```

**Good:**
We needed to query pending orders while TiFlash replicated the last 30 seconds of writes. Because TiDB routes OLAP queries to TiFlash automatically, we could run this against live data without a separate analytics pipeline:
```sql
SELECT /*+ READ_FROM_STORAGE(tiflash[orders]) */ order_id, amount
FROM orders WHERE status = 'pending' AND created_at > NOW() - INTERVAL 30 SECOND;
```
The `READ_FROM_STORAGE` hint is optional here — TiDB's cost-based optimizer would select TiFlash for this scan — but we added it explicitly to make the routing decision visible in code review.

### Show the struggle

Readers connect with challenges, not just solutions. For each major decision:
1. What was tried first and why it failed (with the observed symptom)
2. What was learned from the failure
3. How that led to the solution

A piece with no wrong turns reads as marketing, not engineering.

### Metrics need context

Never present bare numbers.

**Bad:** "Latency: 45ms"

**Good:** "Under production-like load (10k concurrent users, 50M rows, 70% reads), P99 latency dropped from 450ms to 180ms — eliminating the timeout errors we saw during flash-sale spikes."

Always state: what was tested, how it was tested, why the number matters.

### Structure and pacing

Readers skim before they read, and AI engines reward clear hierarchy. Keep the structure scannable:

- **Paragraphs run two to five sentences.** Wall-of-text paragraphs get cut. A single-sentence paragraph is fine for emphasis but shouldn't dominate.
- **Break every ~400 words** with a subhead, list, or visual. A section that runs longer without a break needs restructuring.
- **One H1, then H2s that tell the story top to bottom.** A reader who scans only the H2s should get the gist. H3s appear only under an H2 with enough sub-content to warrant them — no orphan H3s, no H4s unless the content genuinely demands them.

**Choosing a format:**

| Format | Use when |
|--------|----------|
| Prose | Ideas need connective tissue, nuance, or argument |
| Bulleted list | Three or more parallel items, each fitting one to two lines |
| Numbered list | Sequential steps where order matters |
| Table | Comparing two or more options across the same dimensions |
| Code block | Anything meant to be copy-pasted; always fenced with a language tag |
| Diagram | Architecture, request flow, or data flow; always with alt text and a caption |

If every "bullet" in a list is a full paragraph, it's not a list — it's prose. If a table has one column, it's a list.

---

## Terminology precision

| Correct | Never use | Why |
|---------|-----------|-----|
| TiDB Cloud Starter | TiDB Serverless, TiDB Cloud Serverless | Both are deprecated tier names |
| TiFlash | TiDB analytics engine | Redundant / confusing |
| MySQL protocol compatible | MySQL compatible | Overstates compatibility |
| `READ_FROM_STORAGE(tiflash[...])` | TiFlash hint | Use exact SQL syntax |
| PingCAP | Pingcap, PingCap | Official company name |

---

## Pre-submission checklist

**Story foundations:**
- [ ] Problem is named precisely — one memorable phrase, not generic "database challenges"
- [ ] Pain argument covers at least two dimensions (operational + technical risk or compliance/cost)
- [ ] Reframing move is present at the problem-to-solution turn ("Instead of X, treat Y as Z")
- [ ] Every TiDB feature is grounded in a specific workflow — no naked feature listing
- [ ] Story closes with a concrete, understated scale metric or production evidence point

**Content:**
- [ ] Every code block has 2–3 sentences before it and 1–2 sentences after
- [ ] All metrics include: what was tested, how, why it matters
- [ ] At least one failure or wrong turn is visible
- [ ] TiDB version is specified where behavior is version-dependent

**Voice:**
- [ ] Tone is peer-to-peer, not marketing
- [ ] No superlatives without proof ("seamless", "lightning-fast", "best-in-class")
- [ ] Technical decisions are justified with constraints, not just asserted

**Accuracy:**
- [ ] All product names match official naming (`tidb-brand-voice`)
- [ ] No banned phrases from `tidb-brand-voice`
- [ ] Benchmark/performance claims follow methodology disclosure requirements
- [ ] For comparison/architectural decision content: alternatives presented with their legitimate strengths before limitations (fair comparison arc applied)

**Code:**
- [ ] Code is tested and reproduces the described behavior
- [ ] Language tags on all code blocks
- [ ] Code blocks under 40 lines (split larger blocks)
- [ ] Repository or demo link provided where applicable

---

## Verdict

After checklist:
- **Approve** — all checks pass; minor wording notes are optional
- **Revise** — structure or mechanics need fixing; provide specific edits
- **Reject** — fabricated engineering facts, unverifiable claims, or requires re-brief from the author's actual experience

---

## Headline formula

**Formula:** `[Problem or workload, named precisely] + [What changed or was solved] + [optional: outcome or scope]`

| Framework | Example headline |
|-----------|-----------------|
| Migration story | "From MySQL Sharding Chaos to TiDB: How [Company] Eliminated 2 AM Pages" |
| Technical deep dive | "Building Real-Time AI Agents on TiDB: One Database, No ETL Pipeline" |
| Architectural decision | "Why We Moved 500M Rows from Aurora to TiDB (and What We'd Do Differently)" |
| AI workload tutorial | "Hybrid Vector + SQL in One Query: Getting Started with TiDB for AI Agents" |

Lead with the problem or workload, not with "TiDB" or "PingCAP". See `@brain/playbooks/seo-geo-standards.md` for the full headline pass/fail test.

---

## SEO & GEO

Load `@brain/playbooks/seo-geo-standards.md` for universal principles. The following covers article-specific additions.

**Keyword target:** `[use case] + TiDB` and `how to [task]` — e.g., "TiDB HTAP tutorial", "migrate MySQL sharding to TiDB".

**Article-specific GEO rule:** Include **specific version numbers** for any TiDB behavior that is version-dependent. AI engines and readers both use version specificity as a credibility signal.

**Code snippet SEO:** When the article contains SQL or code, include a code snippet in the meta description or social card preview — technical searchers click through at higher rates on titles that signal executable content.

**Internal linking targets:**
- TiDB product or feature docs page for the technology described
- One related case study in the same industry or use case
- Upstream benchmark or performance reference if metrics are cited

---

## Pairs with

- `tidb-brand-voice` — load before drafting; all voice and naming rules
- `tidb-messaging-platform` — verify claims against approved proof points before writing
- `tidb-benchmark-narrative` — performance comparisons must follow benchmark standards
- `tidb-case-study` — if the article tells a customer story, consider running the case study skill instead
- `tidb-developer-story` — for open-source community and informal technical content
- `tidb-channel-copy` — downstream; adapt the article for social distribution
- `tidb-content-review` — final gate before publishing
- `@tidb-gtm-brain/knowledge/product.md` — product capability reference
- `@brain/playbooks/seo-geo-standards.md` — SEO/GEO optimization standards