Skip to content

Findings Directory Conventions

Format conventions for ~/garmin-warehouse/findings/. See systems/findings.md for the high-level overview of what findings are.

Top-level files

File Purpose Edited by
README.md Index of all findings, organized by topic cluster Casey, manually
_active.md Current workstream state (in flight, recently shipped, open questions) Casey + agents (training-data-coach reads on session start, may append)
_todo.md Casey's per-week checklist, surfaced in UI at /active Casey only
_followups_summary.md Auto-generated PubMed cited-by summary over warehouse's primary sources ~/data-ingestion/scripts/build_followups_summary.py
_archive/YYYY-MM.md Closed workstreams trimmed from _active.md Casey, when _active.md exceeds ~600 lines

_active.md format

Living document. Header is the date stamp + tonight's wins block; below that is structured by workstream (W0, W1, W2, ...) with status tags.

# Active Workstreams

_Updated: YYYY-MM-DD — <one-line context for what's hot right now>.
**Tonight's wins (YYYY-MM-DD)**: ✅ <thing>. ✅ <thing>. ✅ <thing>._

The training-data-coach subagent reads this file on every session
start to know what's currently in flight. Update it when starting,
finishing, or pausing a workstream.

## In flight

### W0 — <workstream name>
<paragraph or two: what + why + status + next step>

### W1 — ...

## Recently shipped
- YYYY-MM-DD: <thing> — <one-line>

## Open questions
- <question>
- <question>

Trim convention (per feedback memory): when _active.md grows past ~600 lines, move closed workstreams to _archive/YYYY-MM.md (per-month files). The "Recently shipped" section is the natural source for archive entries.

_todo.md format

Per-week checklist Casey actually does. Surfaced in the warehouse UI at /active. NOT for agent state — that's _active.md.

# TODO — Casey's checklist

_The single source of truth for what Casey actually needs to *do*. Agent
workstream tracking lives in `_active.md`._

## Phase 0 — week N action items (Mon YYYY-MM-DD → Sun YYYY-MM-DD)

### Training (calendar already pushed to intervals.icu)

- [ ] **Mon X/X** — Easy 6.0mi (Z2, HR 137-152, ~7:45-8:30/mi)
- [ ] **Tue X/X 6pm** — Strength Day A — `otq_accelerators.md §3`
...

### One-time setup tasks (do before/during wk N)

- [ ] Order X. Source: `<finding>.md §X`.
- [ ] Schedule Y test.
...

### Nutrition + recovery

- [ ] X
...

## Phase 0 weekly carryforward

What changes each week as Phase 0 progresses. Reset/update Sunday
night before next week's items get carried forward.

Mark [x] when done. Items NOT done at week-end either roll forward or get explicitly dropped (with a one-line "why dropped" note).

Per-finding .md format

# <Finding Title>           <!-- H1 = title in kb, graph, summary -->

<!-- topics: iron, ferritin, fatigue -->   <!-- chips for /topic/<name> -->

<!-- Status: stable | exploratory | superseded by <other.md> -->
<!-- Last reviewed: YYYY-MM-DD -->

## TL;DR
<3-5 bullet recommendations Casey actually follows>

## Context
<why this matters for OTQ-2028, what triggered the investigation>

## What the corpus says
<synthesis of relevant claims, with PMID citations>
- [PMID 12345678](https://pubmed.ncbi.nlm.nih.gov/12345678/) — <claim>
- [SWAP ep-167 b047](path/to/digest) — <host stance>
- See also [other_finding](other_finding.md)

## What my data says
<personal n=1 patterns from the warehouse, with query.py refs>

## Protocol
<concrete actions: what + how often + how to monitor>

## Honest caveats
<what would break this conclusion, what hasn't been tested on me,
what's contested in the corpus>

## Open questions
- ...

## Changelog
- YYYY-MM-DD: shipped v1
- YYYY-MM-DD: added strides protocol after re-reading SWAP ep-201

The "Honest caveats" section is mandatory — every finding has one. This is what separates a finding from a half-baked recommendation.

Naming convention

  • Lowercase + underscores: bloodwork_baseline.md, not Bloodwork-Baseline.md
  • Topic-first: iron_protocol.md, not protocol_for_iron.md
  • No dates in filenames: dates go in front matter / changelog

Filename = stem = findings.id in the kb DuckDB = morning summary's recent_findings[].id. Renaming a finding requires updating watches.yaml and any cross-references.

Cross-references

  • To another finding: [bloodwork_baseline](bloodwork_baseline.md) → kb/load.py picks up via xref table with dst_kind='finding'
  • To a study: [PMID 12345678](https://pubmed.ncbi.nlm.nih.gov/12345678/) → kb/load.py picks up via xref table with dst_kind='study', also feeds _followups_summary.md builder

What NOT to put in findings/

  • Daily journaling (use the morning summary corrections flow, see ADR 003)
  • Code or scripts (those go in analyses/)
  • Configuration (those go in kb/watches.yaml etc.)
  • Raw research notes (those live in ~/Documents/Remote Knowledge/ or as imported Remote Knowledge finding entries)
  • Auto-generated content other than _followups_summary.md