1e6d7e3737
Backport production-learned brain-operations patterns: - Iron Law of Back-Linking (mandatory bidirectional linking) - Brain filing rules (file by primary subject, not format) - Enrichment protocol (7-step pipeline, 3-tier system, person/company templates) - Media ingest workflows (articles, videos, podcasts, PDFs, screenshots) - Citation requirements (mandatory [Source: ...] on every fact) - Test Before Bulk operating principle - Voice recipe: unicode crash fix, PII scrub, identity-first prompt, DIY STT+LLM+TTS - X-to-Brain recipe: image OCR, Filtered Stream, tweet rating rubric, cron stagger
3.5 KiB
Brain Filing Rules -- MANDATORY for all skills that write to the brain
The Rule
The PRIMARY SUBJECT of the content determines where it goes. Not the format, not the source, not the skill that's running.
Decision Protocol
- Identify the primary subject (a person? company? concept? policy issue?)
- File in the directory that matches the subject
- Cross-link from related directories
- When in doubt: what would you search for to find this page again?
Common Misfiling Patterns -- DO NOT DO THESE
| Wrong | Right | Why |
|---|---|---|
Analysis of a topic -> sources/ |
-> appropriate subject directory | sources/ is for raw data only |
Article about a person -> sources/ |
-> people/ |
Primary subject is a person |
Meeting-derived company info -> meetings/ only |
-> ALSO update companies/ |
Entity propagation is mandatory |
Research about a company -> sources/ |
-> companies/ |
Primary subject is a company |
Reusable framework/thesis -> sources/ |
-> concepts/ |
It's a mental model |
Tweet thread about policy -> media/ |
-> civic/ or concepts/ |
media/ is for content ops |
What sources/ Is Actually For
sources/ is ONLY for:
- Bulk data imports (API dumps, CSV exports, snapshots)
- Raw data that feeds multiple brain pages (e.g., a guest export, contact sync)
- Periodic captures (quarterly snapshots, sync exports)
If the content has a clear primary subject (a person, company, concept, policy issue), it does NOT go in sources/. Period.
Notability Gate
Not everything deserves a brain page. Before creating a new entity page:
- People: Will you interact with them again? Are they relevant to your work?
- Companies: Are they relevant to your work or interests?
- Concepts: Is this a reusable mental model worth referencing later?
- When in doubt, DON'T create. A missing page can be created later. A junk page wastes attention and degrades search quality.
Iron Law: Back-Linking (MANDATORY)
Every mention of a person or company with a brain page MUST create a back-link FROM that entity's page TO the page mentioning them. This is bidirectional: the new page links to the entity, AND the entity's page links back.
Format for back-links (append to Timeline or See Also):
- **YYYY-MM-DD** | Referenced in [page title](path/to/page.md) -- brief context
An unlinked mention is a broken brain. The graph is the intelligence.
Citation Requirements (MANDATORY)
Every fact written to a brain page must carry an inline [Source: ...] citation.
Three formats:
- Direct attribution:
[Source: User, {context}, YYYY-MM-DD] - API/external:
[Source: {provider}, YYYY-MM-DD]or[Source: {publication}, {URL}] - Synthesis:
[Source: compiled from {list of sources}]
Source precedence (highest to lowest):
- User's direct statements (highest authority)
- Compiled truth (pre-existing brain synthesis)
- Timeline entries (raw evidence)
- External sources (API enrichment, web search -- lowest)
When sources conflict, note the contradiction with both citations. Don't silently pick one.
Raw Source Preservation
Every ingested item should have its raw source preserved for provenance:
- < 100 MB (text, PDFs, transcripts): store in the brain repo (git-tracked)
in a
.raw/sidecar directory alongside the brain page - >= 100 MB (video, audio, large datasets): upload to cloud storage and
store a
.redirect.yamlpointer in the brain repo
This ensures any derived brain page can be traced back to its original source.