new-pattern

Create a New Pattern

You are creating a new pattern for battle-tested-patterns. Follow each step in order. Do NOT skip source verification. Reference SOP 01 for the full checklist.

Step 1: Topic Validation

Ask these questions before proceeding:

1. What is the pattern name?
2. Can you name ≥ 2 production projects that use it (with source links)?
3. Is it cross-language (not specific to one language/framework)?
4. Is it a code-level technique (not purely architectural)?
5. Does it NOT duplicate an existing pattern in docs/patterns/?

If any answer is "no", stop and explain why this pattern doesn't fit.

Step 2: Source Code Location

For each production project:

1. Search the project repo for the exact usage
2. Get the GitHub URL with line numbers: https://github.com/{org}/{repo}/blob/main/{path}#L{start}-L{end}
3. Verify with curl -sI <url> | head -1 — must return HTTP 200
4. Read the code to confirm your understanding
5. Write a Production Proof description specific enough to learn WITHOUT clicking the link

CRITICAL: Never fabricate a URL. If you cannot verify a link, write <!-- TODO: verify source link --> instead.

Step 3: Write the Document

Create docs/patterns/<pattern-name>/index.md with ALL required sections:

# Pattern: [Name]
## One Liner          ← ≤ 30 English words, capture WHY not just WHAT
## Core Idea          ← concept + diagram (choose best representation for this pattern)
## Production Proof   ← table with ≥ 2 verified URLs, descriptions show HOW not just WHAT
## Implementation     ← TypeScript (required) + ≥ 1 other language in ::: code-group
## Exercises          ← table with basic + intermediate exercise links
## When to Use        ← ≥ 3 concrete scenarios
## When NOT to Use    ← ≥ 2 concrete alternatives
## More Production Uses ← bullet list with repo links
## Challenge Questions ← 3-4 scenario Q&A using ::: details syntax

Diagram Guidelines

• Choose the representation that best matches the pattern's nature:
  • Ring/circular → for hash rings, ring buffers
  • Timeline → for temporal patterns (WAL, MVCC, retry)
  • State diagram → for state machines, circuit breakers (use mermaid)
  • Tree → for tries, heaps, B-trees
  • Box-and-arrow → for data structures (LRU, skip list)
• ASCII text blocks: every box border must be vertically aligned
• ZH docs: CJK characters = 2 display columns; compensate with fewer spaces
• Verify alignment in a monospace font before committing