Skip to content
LBZF Design Docs

Conventions

File status

Section titled “File status”

Every design doc has a frontmatter header:

---
status: draft | reviewed | accepted | built | superseded
owner: <name>
last-updated: YYYY-MM-DD
---

OPEN questions

Section titled “OPEN questions”

Filed as one file per question, nested into a topic folder under 20-questions/<topic>/Q-NNN-slug.md. The canonical topic folders are listed below in urgency order — most time-pressured first, post-Phase-I polish last. The folder ordering itself is a convention (used in 20-questions/README.md and 20-questions/INDEX.md); it is driven by which gate the bucket primarily blocks:

  1. 01-itba/ — ITBA authorship, customs paperwork, twin hardware, SSH keys, language register. Driver: Thu 2026-05-15 flight + BA handoff.
  2. 02-legal-and-consent/ — Colombian counsel, Ley 1581, consent, posted notice, complaint channel, retention. Driver: G2 by 2026-06-30.
  3. 03-hardware-and-install/ — power, dust, mounting, FoV, BoM, spares, JetPack fallbacks, install logistics, on-floor caretaker, ISP, Sunday access, Zona Franca. Merged 2026-05-12 from the former hardware-and-install/ + pereira-deployment/ buckets (the split between hardware product decisions and Pereira install logistics was creating cross-references on almost every Q). Driver: G1 + Pereira install.
  4. 04-customer-requirements/ — LBZF customer requirements voiced through Ronald (Head IE) and Mariana (CEO): Spanish UI copy, dashboard UX, INDICADORES.xlsx parity, device/login prefs, Excel export contract, communication cadence. Renamed 2026-05-12 from ronald-and-mariana/ so the bucket reflects what it tracks rather than the two named people delivering it. Driver: Phase I July go-live.
  5. 05-paper-and-ethics/ — Castilleja policy, InspiritAI IRB-equivalent, COI, venue, authorship order. Driver: G2 / G7 + paper submission.
  6. 06-dashboard-and-app/ — render location, Universal Login Spanish, 4xx localization, English mode, post-login landing, users.json → D1 migration, reverse-proxy routing, multi-tenant pivot. Split 2026-05-12 from the former auth-and-access/ bucket — the post-Phase-I frontend / UX / app-architecture half. Driver: post-Phase-I app polish.
  7. 07-auth-and-identity/ — Auth0 roles, Tailscale tier, SSH, JWT, SMTP, RBAC. Split 2026-05-12 from the former auth-and-access/ bucket — the G1-blocking identity / RBAC / network-access half. Driver: G1 blockers.
  8. 08-tooling-and-process/ — extraction script, Makefile, weekly sync slot, AWS, secret scanner. Driver: engineering backlog.

Within each topic folder, numbering uses multiples of 10 (Q-010, Q-020, …) so future inserts don’t renumber: a new “this is even more urgent” question becomes Q-005; one between two existing items becomes Q-015 or Q-025. Lower number = higher urgency within topic. Numbering urgency drivers are due-date proximity and what the question blocks: G1 (Argentina demo) > July go-live > paper submission > Phase II.

When a folder is merged into another (as pereira-deployment/ was into hardware-and-install/), moved active Qs are renumbered into clean gaps in the destination’s Q-NNN space; if no clean gap exists, they continue from highest existing + 10. Closed files keep their original Q-NNN from the pre-triage flat list — they never renumber.

The filename slug must be a 4–8-word human-readable noun phrase — a stranger should be able to guess the question from the filename without opening the file. Stopword-stripped word-soup slugs (e.g. Q-027-castilleja-been-informed-castilleja-student-conducting) are the anti-pattern.

Frontmatter (active)

Section titled “Frontmatter (active)”
---
question: <one sentence — the actual question>
owner: <name>          # or 'TBD'
due: YYYY-MM-DD        # or 'no-deadline' if not time-bound
topic: <folder name>
priority: high | medium | low
blocks: [list of doc paths or gate IDs like 'G1', 'G2']
source: [worktree paths where this OPEN was originally found]
state: open
---

Frontmatter (closed)

Section titled “Frontmatter (closed)”

Closed files move from <topic>/ to closed/<topic>/ and add three fields:

state: closed | obsolete | "duplicate-of-Q-NNN-<canonical-slug>"
resolved-by: ADR-NNN | <free-text source>
resolved-date: YYYY-MM-DD
  • closed — answered by an ADR or a recent decision (cite which one in resolved-by).
  • obsolete — the question’s premise no longer holds (e.g., the Dahua-specific items retired by ADR-001).
  • duplicate-of-Q-NNN-<slug> — the same substance is tracked elsewhere; the canonical is named in resolved-by.

Closed files keep their pre-triage Q-NNN number and are never renumbered after closure.

Closing a question

Section titled “Closing a question”
  1. Set state to closed / obsolete / duplicate-of-....
  2. Fill in resolved-by and resolved-date.
  3. Move the file from <topic>/ to closed/<topic>/.
  4. If a new ADR was the trigger, the ADR’s frontmatter resolves: list should name this Q-file.

Dashboard

Section titled “Dashboard”

20-questions/INDEX.md is the priority-sorted list of every active question, grouped by topic. It leads with an “ITBA-blocking — fly Thursday 2026-05-15” section, followed by three cross-cutting views that slice the same Qs along different axes:

  1. By deadline band: This week (≤ 2026-05-14) / Pre-G1 (5/15–5/19) / Pre-go-live (5/20–7/31) / Pre-paper (8/1–2027-05-31) / No deadline.
  2. By primary owner: Sophia-solo, Sophia + Andrew, Sophia + Armando, Armando, Mariana, Ronald, ITBA, Andrew-solo, Castilleja-routed, Colombian counsel, other.
  3. Quick wins: active Qs where priority: high AND owner contains “Sophia” AND no obvious external dependency.

Below those, the per-topic listings are sorted by priority then due-date, in the same urgency-driven folder order as the top-level README.md. Regenerate after every batch of Q-file changes — there’s no auto-generation yet.

One fact, one place

Section titled “One fact, one place”

A fact (role name, schema field, IP plan, network setting) lives in exactly one doc. Every other reference is a markdown link, not a restatement. This prevents the cross-bucket contradictions we found in round-2 (e.g., exec vs executive).

Phase II isolation

Section titled “Phase II isolation”

Anything not shipping by July 2026 lives in 60-parking/. A pre-commit check (when implemented) should fail if a 40-prototype/ doc cites a path under 60-parking/.

Languages

Section titled “Languages”

Spanish translations (.es.md siblings) are not currently a structural requirement — translate per audience as needed.