---
name: research-storage-paths
source: https://app.decimal.ai/s/research-storage-paths@1/SKILL.md
source_sha256: 52a805f2980e
---

# 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.
5. Preserving title case or punctuation in the slug (`What-is-React?`).
6. Producing a double hyphen from removed punctuation (`setup--installation`).
7. 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`.