Skip to content

Documentation Reorganization & Cleanup — Session Report

Date: 2026-05-08 Branch: initial-draft Commit range: fe9a468 … 7ddc867 (11 commits) Trigger: Prior project review (project_review_2026-05.md, 2026-05-07) plus the strategic pivot to TuVaca commercial branding.

TL;DR. The repo went from a half-finished 859-file structure with 13 broken README links and a mesh-vs-star architectural contradiction to a 10-section taxonomy with a single source of truth per topic, all cross-links resolving, and the topology decision locked in ADR 0007. Five Critical, five High, three Medium, and four Low review items closed. The remaining open items are tracked in this report and the risk register, and need either domain expertise or team decisions — not more documentation passes.

1. The new organization

docs/
├── 00_business/      brand, strategy, briefs, market — external-facing positioning
├── 10_product/       use cases — what the product does
├── 20_technology/    architecture, components, stack, standards, terminology
├── 30_decisions/     ADRs — single source of truth for architecture decisions
├── 40_partners/      partnership matrix + per-vendor profiles
├── 50_regulatory/    ANII, SNIG, EUDR — centralized
├── 60_events/        time-bound event work
├── 70_internal/      team, financials, risk register, slide source
├── 80_reports/       snapshot reviews + this report
└── 99_assets/        decks, diagrams, binary assets

tools/slides/         slide build environment (was polluting docs/internal/)
proj/                 PM artefacts (roadmap, backlog, AI rules, …)

Naming convention reinforced

  • TuVaca — commercial brand. Lead with this in external-facing material under 00_business/.
  • FluxCow — internal/technical name. Stays in repo name, ADRs, engineering docs.
  • JAAB.tech — corporate umbrella. Use in institutional / contractual contexts.

Per-surface voice rules are in docs/00_business/brand/voice_es.md.

2. What was done — by commit

Commit Phase Summary
fe9a468 Structural reorg (Phase 1) 395 file moves into the new taxonomy; slide build env moved out of docs/; ANII content centralized; .gitignore updated.
882b720 Cross-link rewrites (Phase 2) README rewritten (13 broken links fixed); mkdocs.yml + mkdocs_web.yml nav rewritten; Makefile build targets repointed; 4 stale file:/// URIs converted to relative paths.
5f4e812 Cleanup pass 4 inferior ANII duplicates, parallel proj/decisions.md, 7 stale email drafts, empty placeholder folders, redundant introduction symlink — all removed (~800 lines, no editorial loss).
13e1380 Cleanup pass proj/connectivity_evaluation.md deleted (superseded by ADR 0005); banner added to proj/topology_comparison.md flagging the unresolved mesh-vs-star contradiction.
1073c4b Editorial FluxPets reframed as "Platform Extension" (sister vertical, not cattle); ADR 0006 renamed to 0006-tiered-service-pricing.md, ~120 lines of duplication with the strategic blueprint trimmed, corrupted [ABANDONED] mid-document header removed.
4e3c38b Seeds (Phase 4) Pipeline-at-a-glance summary added to top of partnership_matrix.md; risk_register.md seeded with 10 risks; voice_es.md created.
43be3eb Seeds (Phase A) go_to_market.md skeleton; compliance_matrix.md skeleton with hardware/software/per-country tables.
95a2a24 Architecture (Phase B) ADR 0007 — MVP topology = single-mode Star with mesh-capable hardware. ADR 0003 marked Superseded. R-01 in risk register rewritten.
a89a3c7 Status appendix (Phase C) Post-reorg status appendix added to project_review_2026-05.md, mapping each Critical/High/Medium/Low issue to its current state.
7ddc867 Roadmap reset (Phase D) proj/roadmap.md refreshed: Phase 0 confirmed active; Phase 1 (Innovar) and Phase 2 (World Agri-Tech) marked CANCELLED; Phase 3 deduplicate removed; downstream renumbered with explicit TBD/undated targets. R-11 added to risk register.

3. Issues closed (vs. project review 2026-05-07)

Critical (5/5): - C-1 README malformed header → fixed in 882b720 - C-2 inconsistent "$50" framing → reconciled across README, economics.md, ADR 0006 - C-3 duplicated Detection Accuracy row → fixed in 882b720 - C-4 13 broken README links → all rewritten; full link audit (59 links) now passes - C-5 mkdocs.yml broken nav (7 missing market/ entries) → full nav rewrite

High (5/8): - H-1 stale roadmap → reset in 7ddc867 - H-2 ADR cadence stopped in March → resumed (0006 cleaned, 0007 authored) - H-3 parallel decision logs → proj/decisions.md deleted - H-4 mesh-vs-star contradiction → resolved by ADR 0007 - H-5 no risk register → seeded with 11 risks (was 10, R-11 added in Phase D)

Medium (3/7): - M-2 marketing voice in ADRs → cleaned in ADR 0006 rewrite - M-4 empty placeholder folders → removed - M-7 no compliance matrix → skeleton seeded

Low (4/6): - L-1 node_modules/ in docs/ → moved to tools/slides/ - L-2 PDF location → moved to docs/99_assets/decks/ - L-3 alleged brief duplication → verified actually distinct, no merge needed - L-6 .DS_Store clutter → cleaned during moves

4. Issues still open — and where each is tracked

Item Where tracked Owner What unblocks it
H-6 — No validation evidence for >80% accuracy claims Risk register R-07; TODO markers added 2026-05-08 to each of the four use case files in docs/10_product/use_cases/ TBD Veterinary partner + labelled dataset
H-7 — Pipeline detail tables still mix Stage/Owner/Next Step in a single cell TODO in partnership_matrix.md TBD Tactical column restructure
H-8 — $4.0M gap vs $8.45M ladder unreconciled Risk register R-08; TODO markers added 2026-05-08 to co_founder_brief.md and strategic-economics-blueprint.md Founder One annotation sentence in both files
M-1 — GTM doc has only TBD placeholders TBD markers throughout go_to_market.md TBD (sales lead unfilled) Team decisions on ICP, channel, pilot subsidy
M-3 — Mesh body-shadowing measurement absent "Open Items" in ADR 0007; becomes a Phase 1-equivalent metric whenever the next pilot is committed TBD Field test
M-5 — Backlog has no owner / sprint / estimate columns TODO marker in proj/backlog.md TBD Tactical
M-6 — Two TBD equity placeholders Risk register R-10; existing TBDs in team-alignment-strategy.md Founders Pre-Seed close
M-7 — Compliance matrix has only TBDs TBD throughout compliance_matrix.md Engineering lead (unfilled) Per-component, per-country status calls
L-4 — proj/ai_rules.md is sparse (none — low priority) — Optional polish
L-5 — docs/index.md audience-count mismatch (says "three", lists four) (none — low priority) — Trivial fix
R-11 — Next-milestone vacuum (Phase 1 & 2 both cancelled) Risk register R-11 Founders + Anibal Highest-priority Phase 0 deliverable. Lock a target (event / private pilot / fundraise window) within ≤4 weeks.

5. Architectural decision made this session

ADR 0007 — MVP Topology Selection (commit 95a2a24)

For the MVP and through the next pilot, the Member-to-Leader topology is Mobile Star (Cluster). Hardware is selected to be mesh-capable but ships in single-mode Star firmware. Mesh becomes a recompile and OTA, not a board respin, when (a) measured Star battery budget validates and (b) measured stray-cow frequency justifies it.

Supersedes ADR 0003 — Hybrid Mesh Topology (which had decided Stateless Flooding Mesh in January and was contradicted by proj/topology_comparison.md in February). The contradiction sat unresolved for three months; now closed.

6. New artefacts in the repo

File Purpose
docs/30_decisions/0007-mvp-topology-selection.md The topology ADR.
docs/00_business/brand/voice_es.md EN↔ES glossary, voice pillars, per-surface voice rules. Anibal owns terminology calls.
docs/00_business/strategy/go_to_market.md GTM skeleton — ICP, channels, sales motion, unit economics, pilot strategy. Mostly TBD; the file is the question list, the team owns the answers.
docs/20_technology/standards/compliance_matrix.md Standards × component × per-country deployment-readiness matrix. Mostly TBD.
docs/70_internal/risk_register.md 11 active risks with likelihood / impact / mitigation. Owners are deliberately TBD — the file forces an assignment conversation.
docs/80_reports/reorg_2026-05-08.md This report.

7. How to use the new structure going forward

  1. External-facing material lives in 00_business/ and leads with TuVaca. Internal/engineering material lives in 20_technology/ and 70_internal/ and uses FluxCow.
  2. Every architectural decision becomes an ADR in docs/30_decisions/. When a decision is revisited, write a new ADR that supersedes the old one — don't edit the old one in place beyond the Status banner. (See ADR 0003 for the pattern.)
  3. Every meaningful state change updates the roadmap. Don't let "Current" markers outlive the work — Phase 0 was labelled Current for months past its real horizon, which was the trigger for H-1.
  4. Risks stay in risk_register.md until materially closed. Resolved risks move to "Archived" with a one-line resolution note — don't delete history.
  5. Partner pipeline updates live in partnership_matrix.md. The "Pipeline at a Glance" table at the top is the canonical view; per-event detail tables are the working notes.
  6. Cross-link liberally. This reorg's biggest pre-existing issue was that documents lived in silos and assumed local context. Where one doc references another concept, link the doc that owns it.
  7. Keep ADRs clinical. Marketing voice ("Bank-Grade Assurance", "Digital Bucket Brigade") belongs in 00_business/brand/ and pitch surfaces, not in ADRs or 20_technology/. ADR 0006 was rewritten in this session to enforce this.

8. Closing note

The repo is now in a state where a partner, investor, or new co-founder can read it cold without hitting a broken link, a contradictory decision, or a stale phase label. What's open is honest open: each remaining item has an owner field (often TBD), a tracked location, and a clear unblocking action.

The single highest-priority forward action — by a wide margin — is R-11: lock the next milestone. The longer Phase 0 runs without a concrete forward commitment, the more momentum erodes. Suggested ≤4-week deadline for that decision.

Addendum — Strategic Reset (added later 2026-05-08)

After the reorg landed, a reality-check found the Q1 2026 economic and investment-series planning rested on weak assumptions (BOM modelled before vendor quotes; adoption curves modelled without pilot data; team scale assumed not committed). The path was reset to a COTS-first MVP strategy captured in ADR 0008.

What this changes vs. the report above: - Headline economics on hold. The "<USD 50 / 3-yr all-in" target, the $6 / $12 / $18 tier prices in ADR 0006, the < $15 / < $80 BOM targets in ADR 0002, and the funding ladder in the strategic blueprint and co-founder brief — all banner-marked as on hold or aspirational pending real COTS-deployment data. - R-08 (funding-ladder reconciliation) closed as moot by the reset; the deeper risk shifted to R-12 (COTS dependency / margin compression / vendor lock-in), added to the risk register. - R-11 (next-milestone vacuum) sharpened. The next milestone is now scoped to COTS-based market validation (paying pilot or tightly-scoped commercial trial), not to a custom-hardware demo or an event slot. - Partnership matrix prioritization shifted — COTS-friendly vendors (Blues, RAK, GlobalSat, Mobiltrack as Globalstar VAR) up; custom-silicon and ODM paths (T2M, Racyics, direct Quectel) defer. - What survives: all architecture decisions (97/3 hierarchy, Star with mesh-capable hardware, hybrid connectivity, platform-as-OS framing), the brand and voice work, the regulatory and partner research, the documentation taxonomy.

The reset is firm but not eternal — if validation produces evidence the COTS path can't reach mass-adoption cost or power targets, a follow-up ADR will revisit.