Skip to content

Commit dfd3596

Browse files
heyjoenashclaude
heyjoenash
and
claude
committed
docs: add docs/README.md as canonical folder structure guide
Locks in the docs/ folder convention so nothing ever gets misplaced. A fresh context window dropped into docs/ now sees this README first and knows exactly where every type of doc belongs. Folder structure (now formalized): - docs/specs/ — reference specifications (the textbook) - docs/handoffs/ — ready-to-execute session flight plans with atomic checklists - docs/plans/ — one-off implementation plans (not session patterns) - docs/research/ — bowling science source material from Bowling Buddy - docs/reference/— historical conversation logs and design references - docs/ root — living documents (STATUS, GLOSSARY, README, SESSION-KICKOFF) Includes: - Quick lookup table: "where does X go?" - Per-folder guide with current contents, naming convention, update frequency, and "don't put here" anti-rules - Decision tree: "I'm about to create a doc — where should it go?" - Naming conventions (numbered for sequenced folders, descriptive for unnumbered) - Full directory tree with every current file - The 5 discoverability anchors: this README + STATUS + spec INDEX + handoff README + PRD Resolves the question "where is handoff 02?" — the answer is docs/handoffs/02-LANE-ASSET-BUILD.md (it was always there, just not visible in a top-level docs/ listing because handoffs/ is a folder). The new README makes the folder tree explicit so this can't happen again. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 11f1cf9 commit dfd3596

File tree

1 file changed

+288
-0
lines changed

1 file changed

+288
-0
lines changed

‎docs/README.md‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
# Roll Model — Docs Folder Structure
2+
3+
> **Last Updated**: 2026-04-13
4+
> **Purpose**: This file is the canonical guide for what goes where in `docs/`. If you're about to create a new doc, find its category below FIRST. Nothing should ever be in the wrong folder.
5+
6+
---
7+
8+
## Quick Lookup: "Where does X go?"
9+
10+
| If you're creating... | Put it in... | Example |
11+
|----------------------|-------------|---------|
12+
| A reference spec (architecture, rendering, deployment) | `docs/specs/` | `04-3D-RENDERING.md` |
13+
| A self-contained session handoff with atomic checklists | `docs/handoffs/` | `02-LANE-ASSET-BUILD.md` |
14+
| An implementation plan for a specific feature | `docs/plans/` | `03-RESIZABLE-PANELS-IMPLEMENTATION.md` |
15+
| Bowling science source material | `docs/research/` | `ball-physics-and-equipment-science.md` |
16+
| Historical conversation logs / past references | `docs/reference/` | `convoprior.md` |
17+
| Living dashboard updated every session | `docs/` (root) | `STATUS.md` |
18+
| Canonical bowling terminology | `docs/` (root) | `GLOSSARY.md` |
19+
| The original project vision brief | `docs/` (root) | `SESSION-KICKOFF.md` |
20+
21+
If you don't know which category something belongs in, **read this entire README** before creating the file. If it still doesn't fit, ASK before creating — don't invent a new folder.
22+
23+
---
24+
25+
## Folder-by-Folder
26+
27+
### `docs/specs/` — Reference Specifications
28+
29+
**Purpose**: The textbook. Generic, stable documents describing how the system works and how to do things in general.
30+
31+
**Naming convention**: `{number}-{KEBAB-CASE-NAME}.md` (numbers assigned at creation, never renumbered)
32+
33+
**Current contents**:
34+
- `00-INDEX.md` — master index of all specs
35+
- `01-ARCHITECTURE.md` — tech stack, project structure, data flow
36+
- `02-LAYOUT-AND-SCENE-CUES.md` — split layout + SceneCue system
37+
- `03-3D-ARTIST-BRIEF.md` — GLB model specs for external 3D team
38+
- `04-3D-RENDERING.md` — lighting, materials, post-processing
39+
- `05-CONTENT-ARCHITECTURE.md` — MDX pipeline, full chapter/section map
40+
- `06-DEPLOYMENT-CICD.md` — Vercel + GitHub Actions
41+
- `07-INTERACTION-BLUEPRINTS.md` — interaction design for all 53 sections
42+
- `08-CONTENT-BATCHING-HANDOFF.md` — generic content-writing playbook
43+
- `09-ASSET-ARCHITECTURE.md` — Lane/Figure/Pins prototype options + swappable interface pattern
44+
- `10-SESSION-LANE-ASSET.md` — generic lane-build playbook
45+
- `11-SESSION-FIGURE-ASSET.md` — generic figure-build playbook
46+
- `12-SESSION-OIL-DATA.md` — generic oil-data playbook
47+
- `13-SESSION-SCENE-BUILDING.md` — generic scene-building playbook
48+
- `14-PRD.md` — Product Requirements Document (the north star)
49+
50+
**Update frequency**: Rarely. Once a spec is CANONICAL, it's stable. Updates require justification.
51+
52+
**Don't put here**: Specific session flight plans (those go in `handoffs/`), implementation plans for one-off features (those go in `plans/`), living state (that goes at `docs/` root).
53+
54+
---
55+
56+
### `docs/handoffs/` — Session Flight Plans
57+
58+
**Purpose**: Concrete, ready-to-execute handoff documents with atomic task checklists. Each file is a complete flight plan for ONE specific session that a fresh Claude Code context window can execute end-to-end.
59+
60+
**Naming convention**: `{number}-{KEBAB-CASE-NAME}.md`. Numbers reflect the **suggested execution order**, not the creation order. Numbers don't change once assigned.
61+
62+
**Current contents**:
63+
- `README.md` — folder index + parallel-safety matrix + execution order
64+
- `01-CONTENT-BATCH-1-CUSTOM-BALL-OWNER.md` — 5 MDX sections (Ch 2 + Ch 5)
65+
- `02-LANE-ASSET-BUILD.md` — Lane reusable asset (textured plane)
66+
- `03-OIL-PATTERN-DATA.md` — Oil pattern data library (half-session)
67+
- `04-SCENE-BUILDING-CHAPTER-2.md` — Chapter 2 scene components
68+
- `05-FIGURE-ASSET-BUILD.md` — Bowler figure (primitive scientific-diagram)
69+
- `06-CONTENT-BATCH-2-FOUNDATION.md` — Chapter 1 MDX content (4 sections)
70+
71+
**Update frequency**: Each file is mostly write-once. After the session runs, the handoff stays as historical record. Don't edit a handoff that's already been executed.
72+
73+
**The relationship to `specs/`**: A handoff in `handoffs/` is the SPECIFIC application of a generic playbook in `specs/`. Example:
74+
- `specs/10-SESSION-LANE-ASSET.md` is the generic lane-build playbook
75+
- `handoffs/02-LANE-ASSET-BUILD.md` is the specific atomic flight plan for the next lane build
76+
77+
When you create a new handoff, derive it from a spec playbook. Don't duplicate spec content into the handoff — reference it.
78+
79+
**Don't put here**: Generic playbooks (those go in `specs/`), implementation plans for non-session work (those go in `plans/`).
80+
81+
---
82+
83+
### `docs/plans/` — Implementation Plans
84+
85+
**Purpose**: One-off implementation plans for specific features that aren't session handoffs. Used when a piece of work is too small for a full session handoff but too detailed to capture in a commit message.
86+
87+
**Naming convention**: `{number}-{KEBAB-CASE-NAME}.md`
88+
89+
**Current contents**:
90+
- `03-RESIZABLE-PANELS-IMPLEMENTATION.md` — react-resizable-panels integration (already shipped)
91+
92+
**Update frequency**: Write once when planning, leave as historical record after shipping.
93+
94+
**When to use plans/ instead of handoffs/**:
95+
- The work is too small to need atomic task checklists
96+
- The work doesn't follow a repeating session pattern
97+
- It's a one-off architectural decision implementation
98+
- It's a refactor with a specific plan but no need for a full handoff
99+
100+
**When to use handoffs/ instead of plans/**:
101+
- It's a session that follows a repeating pattern (content batch, asset build, scene build, etc.)
102+
- It needs atomic task checklists to execute
103+
- It needs a master prompt for a fresh context window
104+
- The work is substantial (~3+ hours)
105+
106+
**Don't put here**: Session handoffs, generic playbooks, living state docs.
107+
108+
---
109+
110+
### `docs/research/` — Bowling Science Source Material
111+
112+
**Purpose**: 11,908 lines of dense, citation-heavy bowling science research from the Bowling Buddy parent project. This is the SOURCE material that gets transformed into MDX content by content batching sessions.
113+
114+
**Naming convention**: descriptive names (no numbering convention)
115+
116+
**Current contents**:
117+
- `01-bowling-science-reference.md` (3,869 lines — comprehensive superset)
118+
- `02-existing-tools-gap-analysis.md` (2,958 lines — competitive analysis)
119+
- `08-coaching-pedagogy-and-feedback.md` (1,342 lines — coaching methodology)
120+
- `ball-physics-and-equipment-science.md` (673 lines)
121+
- `biomechanics-and-form.md` (644 lines)
122+
- `lane-science-and-oil-patterns.md` (743 lines)
123+
- `performance-metrics-and-ml-classification.md` (931 lines)
124+
- `strike-physics-and-scoring-science.md` (748 lines)
125+
126+
**Update frequency**: NEVER. This is source material from an upstream project. If new research is needed, add new files but DO NOT modify existing ones.
127+
128+
**How to read these**: They're large. Use Grep to find the section you need, then Read with offset/limit. Don't try to read whole files.
129+
130+
**Don't put here**: Original content for Roll Model (that goes in `content/` at the project root, not in `docs/`). Notes about the research (those should be cited from MDX content directly).
131+
132+
---
133+
134+
### `docs/reference/` — Historical Reference
135+
136+
**Purpose**: Historical documents, conversation logs, design references, and other things that aren't actively maintained but are worth keeping for context.
137+
138+
**Current contents**:
139+
- `convoprior.md` — log of an earlier conversation that informed the project's direction
140+
141+
**Update frequency**: Append-only. Don't edit existing files.
142+
143+
**Don't put here**: Active living docs (those go at `docs/` root), specs (those go in `specs/`).
144+
145+
---
146+
147+
### `docs/` (root) — Living Documents
148+
149+
**Purpose**: Documents that are updated frequently and need to be discoverable at the top level.
150+
151+
**Current contents**:
152+
- `README.md` (this file) — the folder structure guide
153+
- `STATUS.md` — current state dashboard, **updated every session**
154+
- `GLOSSARY.md` — canonical bowling terminology, updated when new terms appear
155+
- `SESSION-KICKOFF.md` — the original project vision brief (kept here, not moved to specs, because it's the historical "where it all started" doc)
156+
157+
**Update frequency**: STATUS.md every session. GLOSSARY.md when new terms enter content. README.md when the folder structure changes. SESSION-KICKOFF.md never (preserved as the original vision).
158+
159+
**Don't put here**: Specs (those go in `specs/`), session handoffs (those go in `handoffs/`), implementation plans (those go in `plans/`).
160+
161+
---
162+
163+
## Decision Tree: "I'm about to create a doc — where should it go?"
164+
165+
```
166+
Is the doc...
167+
168+
├─ ...the original vision or kickoff?
169+
│ └─ docs/SESSION-KICKOFF.md (already exists; don't add more)
170+
│
171+
├─ ...a current state dashboard or living tracker?
172+
│ └─ docs/ root (STATUS.md, GLOSSARY.md, README.md)
173+
│
174+
├─ ...source research material (bowling science from Bowling Buddy)?
175+
│ └─ docs/research/
176+
│
177+
├─ ...a historical conversation log or design reference?
178+
│ └─ docs/reference/
179+
│
180+
├─ ...a stable reference spec (architecture, rendering, deployment, content pipeline)?
181+
│ └─ docs/specs/
182+
│
183+
├─ ...a generic playbook for a recurring session type (write any content batch, build any asset)?
184+
│ └─ docs/specs/ (e.g. specs/08, 10, 11, 12, 13)
185+
│
186+
├─ ...a self-contained flight plan for ONE specific upcoming session with atomic checklists?
187+
│ └─ docs/handoffs/
188+
│
189+
├─ ...an implementation plan for a one-off feature (not a recurring session pattern)?
190+
│ └─ docs/plans/
191+
│
192+
└─ ...something else entirely?
193+
└─ STOP. Ask. Don't invent a new folder.
194+
```
195+
196+
---
197+
198+
## Naming Conventions
199+
200+
### Numbered files (specs/, handoffs/, plans/)
201+
```
202+
{number}-{KEBAB-CASE-NAME}.md
203+
```
204+
205+
Examples:
206+
- `01-ARCHITECTURE.md`
207+
- `02-LANE-ASSET-BUILD.md`
208+
- `14-PRD.md`
209+
210+
Numbers are assigned at creation time and **never renumbered**. If a doc is deprecated, its number stays reserved (don't reuse).
211+
212+
### Unnumbered files (research/, reference/, root)
213+
Descriptive lowercase or PascalCase, choose what fits the context. No strict pattern because these aren't sequenced.
214+
215+
Examples:
216+
- `STATUS.md`
217+
- `GLOSSARY.md`
218+
- `ball-physics-and-equipment-science.md`
219+
- `convoprior.md`
220+
221+
---
222+
223+
## What "Nothing Gets Lost" Means
224+
225+
Every doc lives in exactly ONE folder. There are no duplicates. There is no "I think this might be in two places."
226+
227+
Discoverability is guaranteed by:
228+
229+
1. **`docs/README.md`** (this file) — the folder structure guide
230+
2. **`docs/STATUS.md`** — the current state dashboard, always up to date
231+
3. **`docs/specs/00-INDEX.md`** — the master spec index
232+
4. **`docs/handoffs/README.md`** — the handoff index with parallel-safety matrix
233+
5. **`docs/specs/14-PRD.md`** — the PRD that everything else references
234+
235+
A fresh context window dropped into the project can read README → STATUS → PRD → relevant handoff or spec, and have full context in under 30 minutes.
236+
237+
If you ever can't find a doc, the answer is in one of these 5 files. If it isn't, the doc doesn't exist — create it in the right folder per the decision tree above.
238+
239+
---
240+
241+
## What's Currently in `docs/`
242+
243+
```
244+
docs/
245+
├── README.md # this file — folder structure guide
246+
├── STATUS.md # current state dashboard
247+
├── GLOSSARY.md # bowling terminology
248+
├── SESSION-KICKOFF.md # original project vision
249+
├── specs/ # reference specifications
250+
│ ├── 00-INDEX.md
251+
│ ├── 01-ARCHITECTURE.md
252+
│ ├── 02-LAYOUT-AND-SCENE-CUES.md
253+
│ ├── 03-3D-ARTIST-BRIEF.md
254+
│ ├── 04-3D-RENDERING.md
255+
│ ├── 05-CONTENT-ARCHITECTURE.md
256+
│ ├── 06-DEPLOYMENT-CICD.md
257+
│ ├── 07-INTERACTION-BLUEPRINTS.md
258+
│ ├── 08-CONTENT-BATCHING-HANDOFF.md
259+
│ ├── 09-ASSET-ARCHITECTURE.md
260+
│ ├── 10-SESSION-LANE-ASSET.md
261+
│ ├── 11-SESSION-FIGURE-ASSET.md
262+
│ ├── 12-SESSION-OIL-DATA.md
263+
│ ├── 13-SESSION-SCENE-BUILDING.md
264+
│ └── 14-PRD.md
265+
├── handoffs/ # ready-to-execute session flight plans
266+
│ ├── README.md
267+
│ ├── 01-CONTENT-BATCH-1-CUSTOM-BALL-OWNER.md
268+
│ ├── 02-LANE-ASSET-BUILD.md
269+
│ ├── 03-OIL-PATTERN-DATA.md
270+
│ ├── 04-SCENE-BUILDING-CHAPTER-2.md
271+
│ ├── 05-FIGURE-ASSET-BUILD.md
272+
│ └── 06-CONTENT-BATCH-2-FOUNDATION.md
273+
├── plans/ # one-off implementation plans
274+
│ └── 03-RESIZABLE-PANELS-IMPLEMENTATION.md
275+
├── research/ # bowling science source material (from Bowling Buddy)
276+
│ ├── 01-bowling-science-reference.md
277+
│ ├── 02-existing-tools-gap-analysis.md
278+
│ ├── 08-coaching-pedagogy-and-feedback.md
279+
│ ├── ball-physics-and-equipment-science.md
280+
│ ├── biomechanics-and-form.md
281+
│ ├── lane-science-and-oil-patterns.md
282+
│ ├── performance-metrics-and-ml-classification.md
283+
│ └── strike-physics-and-scoring-science.md
284+
└── reference/ # historical conversation logs / design references
285+
└── convoprior.md
286+
```
287+
288+
That's the entire `docs/` tree. If you create a new file, it goes in one of the existing folders. Don't create new top-level folders without a strong justification — ask first.

0 commit comments

Comments
 (0)