DRAFT PROPOSAL — awaiting Peter's review 2026-05-17 · Claude · A plain-English plan for reorganizing the doc set

LDD Rebuild Proposal

One-line intent: reorganize the LDD documentation so it's easier to navigate today and portable to a real wiki tomorrow — without renumbering anything, without breaking anything, and without throwing away the work already done.

The 30-second version

TL;DR

Right now we have 30 LDDs numbered 01 through 30. The numbers worked when we had 6 LDDs — but they've stopped being useful at 30. The numbers reflect the order they were written, not what kind of thing each one describes.

The fix isn't to renumber them. The fix is to add categories on top of the numbers and reorganize the left navigation around those categories. The numbers stay (history, URLs, Peter's emails all keep working) — but the primary way you find a doc becomes "what kind of thing am I looking for?" instead of "what number was it?"

Side benefit: this reorganization turns each LDD into a uniform record. When the project eventually outgrows a static website and we want to move to a real wiki (Notion, Confluence, etc.), the migration becomes a port — not a rewrite.

The problem, in plain language

Imagine a library where the books were shelved in the order they arrived. Cookbooks next to engineering textbooks next to children's picture books, all sorted by acquisition date. That's our current LDD set.

LDD-01 was the first one written; LDD-30 is the most recent. The numbers don't tell you anything about what's inside. If Peter wants to find everything that affects the gym, he has to either remember the right numbers (04, 22, 25, 26, 27, 29) or scroll through all 30. If we want to send a structural engineer just the docs they need to review, there's no way to extract that subset cleanly.

Underneath, the LDDs are not all the same kind of thing. They mix together at least six distinct categories:

Category	What it is	Examples
🎯 Master strategies	Big synthesis docs that govern a bunch of smaller LDDs. They set the rule the focused LDDs are tested against during value engineering.	LDD-29 Gym Systems, LDD-30 Mech Core. (Future ones likely.)
🏗️ Building systems	Engineering subsystems that cross the whole building — the horizontal layers.	Structural, HVAC, Electrical, Plumbing, Envelope, Lighting, Ceilings, Radiant.
🏠 Zones	Specific rooms or regions of the building.	Mech room, Laundry, Workshop, South bay, Spine wall.
🧩 Elements	Smaller features that live inside a zone or strategy.	Gym hero wall, Basketball, Ballet wall, Cooking + vent, Social counter, Soffit.
🎨 Materials & finishes	Cross-cutting palette + finish language.	Interior materials.
📋 Process	How we actually build it — construction sequence and rules.	Build rules.

These are six different concerns and six different audiences. Treating them all as a flat list of 30 numbered docs is the source of the navigation friction.

What I'm proposing — three changes

1. Reorganize the left nav by category, not by number

Replace the flat 30-item list with six categories. Each LDD lives in exactly one category. The LDD numbers stay (still useful for history and Peter's "LDD-09" labels), but the primary nav axis becomes the category, not the number.

What you'd see in the sidebar (sketch):

LDD BIBLE
─ 🎯 Master Strategies
  ├ 29 Gym Architectural Systems
  └ 30 Mech Core Master Strategy

─ 🏗️ Building Systems
  ├ 01 Structural
  ├ 02 Radiant slab
  ├ 05 HVAC overview
  ├ 06 Living-wing HVAC
  ├ 08 Lighting framework
  ├ 09 Electrical
  ├ 10 Plumbing
  ├ 11 Envelope (IMP)
  ├ 12 Exposed ceilings
  └ 16 Exterior lighting

─ 🏠 Zones
  ├ 03 Spine wall (gym/living divide)
  ├ 13 South bay
  ├ 14 Workshop + equip
  ├ 15 Mech room
  ├ 21 Laundry / ops
  └ 24 Flooring (cross-zone)

─ 🧩 Elements
  ├ 04 Gym hero wall
  ├ 07 Cooking + vent
  ├ 17 Soffit system
  ├ 19 Doors + stairs
  ├ 20 Social counter
  ├ 22 Basketball hoop
  ├ 25 Ballet wall
  ├ 26 Rebound wall
  ├ 27 Acoustic clouds
  └ 28 Kitchen MUA

─ 🎨 Materials & Finishes
  └ 18 Interior materials

─ 📋 Process
  └ 23 Build rules

The status dots (the green/yellow/amber lifecycle indicators we just added) stay exactly as they are. They work the same way regardless of grouping.

2. Standardize what each LDD looks like

LDD-29 and LDD-30 follow a strict template now:

Status banner (locked / pending / etc.)
One-line intent
Why this matters
AI render (FPO image)
Locked decisions (numbered cards)
Open items / engineer review
Cross-references
Cost drivers
Air-gap concerns
Diagram (plan view)
Status footer

The older LDDs (01–28) are more loose. Some have cost drivers, some don't. Some have air-gap concerns, some don't. The order varies. The proposal is to bring every LDD up to the same template, so each one is a uniform "data block." This is mechanical work — mostly cut-and-paste reorganization with some gaps filled in (and asking Peter to weigh in where he wants).

3. Add quiet machine-readable metadata to each LDD

At the very top of each LDD's source file, add a small block of structured data that's invisible to readers but readable by tools and automated checks:

id: LDD-30
title: Central Mechanical Core Master Strategy
category: master-strategy
audience: [mep, structural-eng, gc, owner]
status: pending
version: v6.0
adopted: 2026-05-17
source: Peter Shin
unifies: [LDD-01, LDD-02, LDD-05, LDD-10, LDD-13, LDD-15, LDD-21, LDD-23]
supersedes: [LDD-15 § east-wall-zones]

This block is the secret weapon. Once the metadata is on every LDD, we can ask the doc set questions that are essentially impossible today:

"Show me everything pending engineer review."
"Show me what an MEP engineer needs to read."
"What LDDs are affected if we change the gym floor spec?"
"Which LDDs has Peter touched in the last 30 days?"

Each of those is a one-line query against the metadata. Right now each one takes a human's eyeballs and memory.

Why this matters for the future

The current site is hand-built static HTML. That's working beautifully for now: it's fast, it's predictable, it's hosted on Cloudflare for almost nothing, and it has no moving parts that can break.

But there will come a moment where we want things a static site can't do well:

Real search across the whole set.
Filtering by audience, status, or category.
Automatic backlinks ("what links to LDD-15?").
Version history per LDD that's readable without git.
Comments and redlines from contractors or engineers without emailing PDFs around.

When that moment arrives, the natural next step is to move to a real wiki — Notion, Confluence, Obsidian Publish, MediaWiki, or a small custom database. The good news: if we do the refactor now, that migration becomes a port. If we don't, it becomes a rewrite.

Why? Because databases and wikis want uniform records. Right now the LDDs are uniform in spirit (same idea, same intent) but not in implementation (different sections, different metadata, different structure). Making them uniform in implementation is exactly the work proposed above. Once it's done, every LDD is a record with the same shape, and an export-to-wiki script can ingest the whole set in one pass.

What this proposal is NOT doing

Things we're keeping exactly as they are

LDD numbers stay. URLs work, history works, Peter's "LDD-09" labels stay mappable. Renumbering would break too much for too little gain.
The Cloudflare site keeps working. No backend migration today.
All existing content stays. Nothing gets deleted.
Status dots stay. The lifecycle indicator system we just built keeps doing its job.
Cross-references stay. The master-strategy synthesis pattern is preserved.

While we're at it — the other navigation sections

This is partially independent of the LDD refactor, but since we're rethinking the navigation: the other sidebar sections could be tightened too. The current names are functional but could tell a clearer story.

Today's name	Proposed	Why
Home	Start here	"Home" is generic; "Start here" tells a visitor what to do first.
Project command	Operations	"Operations" is closer to what's actually inside — day-to-day project running: budget, to-do, decisions, contractors. "Command" sounds military.
Reviews + debate	Audits & debate	The AI audits are the core; "Reviews" is too soft for what they do.
Design library	Assets	Disambiguates from the LDD Bible and matches what is actually there: sketches, site photos, plans, renders, and CAD exports.
LDD Bible	(unchanged)	Already clear.
(new)	Developers Focus	Where this proposal lives. The "how does the doc set itself work" admin section.

These are name tweaks; the contents inside each section don't move. The point is to make the section names self-explanatory at a glance.

Cost and timeline

About four days of focused work, broken into phases. Each phase is independently useful — we can stop after Phase 1 and still get most of the value.

Phase	Time	What you get
Phase 1 — Categorize	1 day	Add category metadata to all 30 LDDs. Reorganize sidebar by category. Doc set becomes 10× more navigable.
Phase 2 — Standardize	2 days	Bring older LDDs up to the LDD-29/30 template. Each LDD becomes a uniform data block.
Phase 3 — Bidirectional cross-refs	1 day	Every LDD automatically shows "what links here." No more one-way references.
Phase 4 — Wiki migration	Only when needed	Port the metadata-tagged corpus to a real wiki. Roughly a week, but deferred until the project demands it.

The one thing I would NOT recommend

Don't renumber

The LDD numbers are arbitrary in origin but they're stable references that everyone uses now — Peter's emails, git history, cross-references between LDDs, URLs on the Cloudflare site. Renumbering would break all of that for marginal benefit.

Treat the numbers as historical IDs — useful for tracking creation order, useful for citing in conversation, useful for git archaeology. Let the new category system do the real organizational work. The two coexist peacefully.

Where we'd start (if you agree)

The smallest useful experiment: pick a single LDD (probably LDD-29 since it's already cleanest), add the proposed metadata block to it, and see how it feels. If the model holds up, we batch the other 29 over the following days. If it doesn't, we've spent 30 minutes and learned something.

The phases above don't have to be done in one go. Each phase is independently shippable. Phase 1 alone — just the category-based sidebar — would already make the difference Peter is likely to feel most strongly.

What I'd love your input on

Does the six-category taxonomy match how you actually think about the building? Specifically: are "Zones" and "Elements" the right split, or do you think about them differently?
Are there categories I'm missing? For example, should "Exterior" be its own category alongside Zones? Should "Codes & AHJ" be a category?
What's your appetite for migrating to a real wiki eventually? Is this something you'd value, or are you happy with the static site for the duration?
Do the proposed name changes to the other nav sections (Start here / Operations / Audits & debate / Visual library) ring true, or do the current names work better for you?

None of this needs to be decided today — but knowing your direction on these four questions sharpens the plan.