Research Storage Path Convention

Contract

Enforces the exact directory name and file path for cached research results. Apply whenever you produce a path under which a section's or the project's research is stored. The values below are fixed — derive them, do not invent a new layout.

Rules

R1 — Everything lives under .research/

The cache root is the dotfile directory .research/. There are exactly two sub-trees:

• .research/sections/… — per-section research.
• .research/init/… — project-wide (init) research, not tied to any one section.

Never use research/ (no dot), docs/, cache/, a top-level chapter-N/ folder, or any nesting by chapter. The root is always .research/.

R2 — Section directory name is {chapter}-{section}-{slug}

A section's directory is .research/sections/{chapter}-{section}-{slug}/. The name has exactly three components joined by a single hyphen -, in this order: chapter, section, slug. No other separators, no dots, no underscores between components.

R3 — chapter: zero-pad to EXACTLY 2 digits

Parse the chapter as an integer (strip any leading zeros), then left-pad with 0 to a minimum width of 2.

• 1 → 01, 3 → 03, 9 → 09.
• 10 → 10, 12 → 12 (already 2 digits).
• A chapter ≥ 100 keeps all its digits: 100 → 100 (pad is a minimum width of 2,

never a truncation). Never produce a 1-digit chapter and never produce 010.

R4 — section: single integer, NO padding

Parse the section as an integer (strip leading zeros), then write the digits as-is with no leading zero.

• 1 → 1, 2 → 2, 03 → 3, 07 → 7.
• A section ≥ 10 keeps its digits: 10 → 10 (stripping leading zeros never

removes significant ones). Never zero-pad the section: 01, 02, 005 are all wrong.

This is the asymmetry that trips models up: chapter pads, section does not.

R5 — slug: normalize the title, in this exact order

Apply these five steps to the title, in order:

1. Lowercase the whole string.
2. Replace each run of whitespace with a single -.
3. Delete every character that is not a-z, 0-9, or -.
4. Collapse any run of consecutive - into a single -.
5. Strip a leading or trailing -.

Digits are kept (HTTP 2 → http-2). Letters are lowercased. Everything else — ?, &, :, !, +, ., /, (, ) — is removed, not transliterated.

R6 — Section files: exactly research.md and sources.md

Inside a section directory there are exactly two files, named precisely:

• research.md — the section's research results.
• sources.md — the section's source registry.

No summary.md, index.md, notes.md, README.md, or .txt variants in a section directory.

R7 — Init files: summary.md and sources.md

Project-wide research lives directly in .research/init/:

• .research/init/summary.md — the init research summary.
• .research/init/sources.md — the init source registry.

The init summary is named summary.md, not research.md. The section research file is named research.md, not summary.md. Both trees use sources.md for sources.

Worked examples

Each shows the base model's plausible-but-wrong default (BEFORE) → the conforming result (AFTER).

R1 — root

• BEFORE: research/sections/01-2-core-concepts/research.md
• AFTER: .research/sections/01-2-core-concepts/research.md
• (the root is the dotfile .research/, not research/.)

R2 — separators / ordering

• BEFORE: .research/sections/01_2_core-concepts/ or .research/sections/ch01/s2/core-concepts/
• AFTER: .research/sections/01-2-core-concepts/
• (three components, single-hyphen joined, no underscores, no extra nesting.)

R3 — chapter padding

• BEFORE: .research/sections/1-2-core-concepts/ (chapter not padded)
• AFTER: .research/sections/01-2-core-concepts/
• BEFORE: .research/sections/010-3-advanced-patterns/ (over-padded chapter 10)
• AFTER: .research/sections/10-3-advanced-patterns/

R4 — section NOT padded

• BEFORE: .research/sections/02-03-data-models/ (section zero-padded)
• AFTER: .research/sections/02-3-data-models/
• (chapter 02 padded, section 3 left bare.)

R5 — slug normalization

• BEFORE: Core-Concepts (case preserved) → AFTER: core-concepts
• BEFORE: what-is-react? (punctuation kept) → AFTER: what-is-react
• BEFORE: setup-&-installation or setup--installation → AFTER: setup-installation
• BEFORE: c++-programming → AFTER: c-programming
• BEFORE: -multiple-spaces- (untrimmed) → AFTER: multiple-spaces
• BEFORE: http_2_basics (underscores, digit dropped) → AFTER: http-2-basics

R6 — section files

• BEFORE: .research/sections/04-2-routing/summary.md
• AFTER: .research/sections/04-2-routing/sources.md (and research.md)

R7 — init summary name

• BEFORE: .research/init/research.md
• AFTER: .research/init/summary.md

Edge cases & exceptions

• Section already zero-padded in the input (03): normalize by parsing to an

integer first → 3. The input format is irrelevant; the output is always the bare integer.

• Chapter ≥ 100 / section ≥ 10: padding is a minimum width, never a max.

100 → 100, section 10 → 10. Don't chop digits to hit a width.

• Title with only punctuation between words (Setup & Installation): the &

is deleted and the surrounding spaces collapse, so you get a single hyphen (setup-installation), never a double (setup--installation).

• Leading/trailing whitespace or symbols ( Best Practices! ): trimmed and

stripped → best-practices, with no trailing hyphen from the removed !.

• Digits in the title (HTTP 2 Basics): digits survive normalization →

http-2-basics. Don't drop them as "non-letters".

• Init research has no chapter/section: it is not a section, so it never gets a

{chapter}-{section}-{slug} directory. It lives flat in .research/init/.

Do / Don't

• DO pad the chapter to 2 digits. DON'T pad the section — ever.
• DO root under .research/ (with the dot). DON'T use research/ or docs/.
• DO name the section file research.md. DON'T name it summary.md.
• DO name the init summary summary.md. DON'T name it research.md.
• DO lowercase the slug and delete stray punctuation. DON'T keep ?, &, :,

!, or +, and DON'T transliterate + to plus.

• DO join components with a single -. DON'T use _, ., or extra directory

nesting.

Common mistakes

1. Zero-padding the section to match the chapter (02-03-… instead of 02-3-…).
2. Leaving the chapter unpadded (1-2-… instead of 01-2-…).
3. Dropping the leading dot — writing research/ instead of .research/.
4. Naming the section's file summary.md, or the init file research.md — the two

are swapped relative to intuition.

1. Preserving title case or punctuation in the slug (What-is-React?).
2. Producing a double hyphen from removed punctuation (setup--installation).
3. Using underscores or dots between the three components.

Quick checklist

• ] Path rooted at .research/ (with the dot).
• ] Section dir = {chapter}-{section}-{slug}, single-hyphen joined.
• ] Chapter zero-padded to 2 digits; section NOT padded.
• ] Slug lowercase, kebab-case, punctuation removed, no leading/trailing/double -.
• ] Section files: research.md + sources.md. Init files: summary.md + sources.md.