Commit a7b6ae
2026-03-13 01:51:46 Claude (Dev): [mcp] Port original PRD note schema section to wiki| /dev/null .. design/original prd note schema.md | |
| @@ 0,0 1,248 @@ | |
| + | --- |
| + | category: reference |
| + | tags: [meta, design, prd, schema] |
| + | last_updated: 2026-03-12 |
| + | confidence: high |
| + | --- |
| + | |
| + | # Original PRD Note Schema |
| + | |
| + | > This page is part of the original single-tenant PRD, split across five wiki pages: |
| + | > [[Design/Original PRD Overview]] | [[Design/Original PRD API]] | [[Design/Original PRD Semantic Search]] | [[Design/Original PRD MCP]] | [[Design/Original PRD Note Schema]] |
| + | |
| + | --- |
| + | |
| + | ## Note Schema |
| + | |
| + | All wiki pages should use YAML frontmatter. This is a convention, not enforced by the system, but the Chroma plugin extracts metadata from it for filtering. |
| + | |
| + | ```yaml |
| + | --- |
| + | category: actor | variable | trend | proposition | event | reference | index |
| + | tags: [tag1, tag2] |
| + | last_updated: 2026-03-09 |
| + | confidence: high | medium | low | speculative |
| + | --- |
| + | ``` |
| + | |
| + | ### Field definitions |
| + | |
| + | - **category**: What kind of note this is. Maps to the analytical framework: |
| + | - `actor` — a state, organization, leader, or entity (e.g., "Iran", "Trump", "IRGC") |
| + | - `variable` — a tracked parameter or measurable quantity (e.g., "WTI Oil Price", "Interceptor Stockpiles") |
| + | - `trend` — an ongoing dynamic or trajectory (e.g., "Desalination Targeting Ratchet") |
| + | - `proposition` — a testable analytical claim with observable indicators (e.g., "Iran is rationing ballistic missiles") |
| + | - `event` — a specific dated occurrence (e.g., "Israel Strikes Tehran Oil Depots") |
| + | - `reference` — an external source, report, or dataset (e.g., "USDA Prospective Plantings Report") |
| + | - `index` — a hub or overview page that links to related notes |
| + | - **tags**: Freeform tags for filtering. Examples: `military`, `economic`, `food-security`, `p1-third-clock`, `p2-interceptor-race`, `p3-infrastructure`, `p4-economic-transmission` |
| + | - **last_updated**: Date of last substantive update (ISO 8601 date, e.g., `2026-03-09`). |
| + | - **confidence**: Epistemic status of the note's core claims. |
| + | |
| + | ### Cross-references: WikiLinks are the single source of truth |
| + | |
| + | Related notes are expressed **only** as `[[WikiLinks]]` in the body text, NOT in frontmatter. There is no `related` frontmatter field. The link graph is derived entirely by parsing WikiLinks in page content. This avoids the divergence problem where a frontmatter list and inline links get out of sync. |
| + | |
| + | ### Page organization |
| + | |
| + | Pages are organized in subdirectories by category: |
| + | |
| + | ``` |
| + | Actors/ |
| + | Iran.md |
| + | Trump.md |
| + | China.md |
| + | Russia.md |
| + | Gulf States.md |
| + | Variables/ |
| + | WTI Oil Price.md |
| + | Interceptor Stockpiles.md |
| + | US Gas Prices.md |
| + | Iranian Civilian Casualties.md |
| + | Trends/ |
| + | Desalination Targeting Ratchet.md |
| + | Iran Attrition Strategy.md |
| + | Economic Double Wave.md |
| + | Propositions/ |
| + | Iran Rationing Ballistic Missiles.md |
| + | Fertilizer Supply Chain Disruption.md |
| + | Events/ |
| + | 2026-03-01 US Strikes Begin.md |
| + | 2026-03-07 Israel Strikes Tehran Oil Depots.md |
| + | References/ |
| + | USDA Prospective Plantings.md |
| + | FAO Food Price Index.md |
| + | ``` |
| + | |
| + | ### Cross-referencing |
| + | |
| + | Use Otterwiki's native `[[WikiLink]]` syntax. Examples: |
| + | |
| + | ```markdown |
| + | The [[Actors/Iran|Iran]] [[Trends/Iran Attrition Strategy|attrition strategy]] |
| + | involves a multi-phase approach: cheap drones to drain |
| + | [[Variables/Interceptor Stockpiles|interceptor stockpiles]], followed by |
| + | ballistic missiles against high-value targets. |
| + | ``` |
| + | |
| + | ### Page size guidance |
| + | |
| + | Notes should be **250–800 words** (roughly 400–1200 tokens). This is a soft target, not a hard limit. The rationale is context window efficiency: the AI assistant pulls multiple notes per session. If individual notes are 3,000+ words, pulling five of them consumes most of the context window. Short, atomic notes let the AI pull 10–20 relevant notes and still have room for conversation, analysis, and system prompts. |
| + | |
| + | If a note grows beyond ~1000 words, it should probably be split into multiple notes linked together. For example, a long "Iran" actor note should be decomposed into "Iran — Military Doctrine", "Iran — Political Leadership", "Iran — Nuclear Program", etc., with an "Iran" index page linking them. |
| + | |
| + | That said, longer notes are not a system-level problem. The Chroma plugin chunks pages for embedding (see Component 2), so semantic search quality is unaffected by page length. The guidance is about keeping individual notes focused and context-window-friendly, not a technical constraint. |
| + | |
| + | ### Complete example page |
| + | |
| + | Here is what `Trends/Iran Attrition Strategy.md` looks like on disk: |
| + | |
| + | ```markdown |
| + | --- |
| + | category: trend |
| + | tags: [military, p2-interceptor-race, p3-infrastructure] |
| + | last_updated: 2026-03-08 |
| + | confidence: high |
| + | --- |
| + | |
| + | # Iran Attrition Strategy |
| + | |
| + | Iran is executing a multi-phase attrition campaign designed to degrade |
| + | Gulf state and US defensive capacity before committing high-value |
| + | ballistic missile assets. |
| + | |
| + | ## Phase structure |
| + | |
| + | **Phase 1 — Drone saturation.** Cheap Shahed-series drones launched in |
| + | large salvos to force expenditure of expensive interceptor missiles. |
| + | The cost asymmetry is extreme: a $20,000 drone forces the use of a |
| + | $1–3M interceptor. See [[Variables/Interceptor Stockpiles]]. |
| + | |
| + | **Phase 2 — Radar blinding.** Anti-radiation missiles and electronic |
| + | warfare to degrade air defense radar networks, creating gaps in |
| + | defensive coverage. |
| + | |
| + | **Phase 3 — Ballistic strikes on high-value targets.** Once interceptor |
| + | stockpiles are depleted and radar coverage is degraded, Iran commits |
| + | ballistic missiles against infrastructure targets. The 86% drop in |
| + | ballistic missile launch rates in the first week reflects deliberate |
| + | rationing, not destroyed capability. See |
| + | [[Propositions/Iran Rationing Ballistic Missiles]]. |
| + | |
| + | ## Evidence |
| + | |
| + | - Ballistic missile launch rate dropped ~86% after initial salvos |
| + | (Days 1–3 vs Days 4–9), while drone launch rates remained constant |
| + | or increased. |
| + | - [[Actors/Iran|IRGC]] messaging emphasizes "patience" and |
| + | "strategic depth." |
| + | - Historical precedent: Iran used similar phased approach in late |
| + | stages of Iran-Iraq War. |
| + | |
| + | ## Implications |
| + | |
| + | This strategy means the most dangerous phase of the conflict for |
| + | Gulf infrastructure is still ahead, not behind. The current period |
| + | of relatively low ballistic missile activity is the preparation |
| + | phase, not the resolution. See [[Trends/Desalination Targeting Ratchet]] |
| + | for emerging target categories. |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## Master Index Convention |
| + | |
| + | ### Purpose |
| + | |
| + | The master index solves the "you don't know what you don't know" problem. At session start, the AI assistant reads one page and gets a complete map of the wiki's contents. This replaces the current protocol of reading all project PDFs. |
| + | |
| + | ### Structure |
| + | |
| + | `Index/Master.md` is a single page listing every note in the wiki, organized by category, with a one-line description per note. It is maintained by both the human and the AI. When either party creates a new note, they should add it to the master index. |
| + | |
| + | ### Example |
| + | |
| + | ```markdown |
| + | --- |
| + | category: index |
| + | tags: [meta] |
| + | last_updated: 2026-03-09 |
| + | confidence: high |
| + | --- |
| + | |
| + | # Master Index |
| + | |
| + | ## Actors |
| + | - [[Actors/Iran]] — military doctrine, IRGC command, attrition strategy, nuclear posture |
| + | - [[Actors/Trump]] — surrender framing, "no time limits" rhetoric, Third Clock dynamics |
| + | - [[Actors/China]] — hedging calculus, summit positioning, semiconductor leverage |
| + | - [[Actors/Russia]] — targeting intelligence provision, diplomatic posture |
| + | - [[Actors/Gulf States]] — defensive capacity, desalination vulnerability, alliance strain |
| + | |
| + | ## Variables (P1–P4) |
| + | - [[Variables/Third Clock]] — P1: Trump tolerance timeline ⚠️ STALLED as of Day 9 |
| + | - [[Variables/Interceptor Stockpiles]] — P2: Gulf-wide Patriot/THAAD depletion tracking |
| + | - [[Variables/Iran Strike Intent]] — P3: ballistic/drone ratio, targeting pattern evolution |
| + | - [[Variables/WTI Oil Price]] — P4: $90.90 as of Day 9, record weekly gain |
| + | - [[Variables/US Gas Prices]] — P4: $3.45 as of Day 9 |
| + | - [[Variables/Iranian Civilian Casualties]] — 1,200+ as of Day 9 |
| + | |
| + | ## Trends |
| + | - [[Trends/Iran Attrition Strategy]] — multi-phase: drones → radar blinding → ballistic strikes |
| + | - [[Trends/Desalination Targeting Ratchet]] — confirmed both sides, precedent difficult to walk back |
| + | - [[Trends/Economic Double Wave]] — immediate oil shock + delayed harvest-time food prices (Q3–Q4) |
| + | |
| + | ## Propositions |
| + | - [[Propositions/Iran Rationing Ballistic Missiles]] — 86% launch rate drop = rationing, not destruction |
| + | - [[Propositions/Fertilizer Supply Chain Disruption]] — no strategic reserve, spring window biologically fixed |
| + | |
| + | ## Events (recent) |
| + | - [[Events/2026-03-07 Israel Strikes Tehran Oil Depots]] — first Israeli strike on Tehran |
| + | - [[Events/2026-03-08 New Iranian Supreme Leader Selected]] — unnamed successor |
| + | - [[Events/2026-03-08 Russia Providing Targeting Intelligence]] — confirmed |
| + | |
| + | ## References |
| + | - [[References/USDA Prospective Plantings]] — March 31 report, anchors food security monitoring |
| + | - [[References/FAO Food Price Index]] — April 3 update |
| + | ``` |
| + | |
| + | ### Size budget |
| + | |
| + | At ~15 words per entry, 200 notes ≈ 3,000 words ≈ 4,500 tokens. This fits comfortably in a single tool call. The master index only needs to be fragmented into sub-indexes if the wiki exceeds ~500 pages. |
| + | |
| + | ### Orphan detection |
| + | |
| + | The `find_orphaned_notes` MCP tool compares the full page list against pages referenced in all `category: index` pages. Pages that exist but aren't linked from any index are "orphans." This is used during periodic gardening sessions (see below), not at every session start. |
| + | |
| + | ### Session start protocol |
| + | |
| + | When beginning a research session, the AI assistant should: |
| + | |
| + | 1. `read_note("Index/Master")` — load the full map |
| + | 2. `list_notes(updated_since=<last_session_date>)` — see what changed since last check-in |
| + | 3. Based on the day's research question, `read_note` the 5–15 most relevant pages |
| + | 4. Proceed with web search for new developments, as per existing protocol |
| + | |
| + | ### Gardening sessions |
| + | |
| + | Periodically (likely automated), a dedicated session focuses solely on wiki maintenance: |
| + | |
| + | - `find_orphaned_notes()` — add orphans to the appropriate index or flag for review |
| + | - Review notes with stale `last_updated` dates |
| + | - Check for broken WikiLinks (Otterwiki also has built-in housekeeping for this) |
| + | - Update confidence levels on propositions based on accumulated evidence |
| + | - Identify notes that have grown too long and should be split |
| + | - Ensure tag consistency (catch typos like `p2-interceptor_race` vs `p2-interceptor-race`) |
| + | - Update the master index |
| + | |
| + | The gardening protocol will be refined once the system is running and we understand the actual maintenance patterns. |
| + | |
| + | --- |
| + | |
| + | ## Open Questions |
| + | |
| + | 1. **Plugin blueprint support** — This is the critical unknown. Phase 1 resolves it. Read `otterwiki/plugins.py` and `docs/plugin_examples/` before writing any code. |
| + | 2. **Chroma embedding model** — `all-MiniLM-L6-v2` is the pragmatic default (runs locally, no API key). The chunking strategy sizes chunks to fit within the model's input window, so the exact max sequence length matters for tuning `target_tokens` in the chunker. Verify the actual limit at implementation time and adjust accordingly. Could upgrade to a larger model later if retrieval quality is poor. |
| + | 3. **Frontmatter parsing** — Otterwiki has a community-contributed YAML frontmatter renderer plugin (noted in v2.10 changelog). Investigate whether it already handles frontmatter parsing that can be reused. If not, use PyYAML to parse the `---` delimited block at the top of page content. |
| + | 4. **Concurrent edit safety** — The API should check the page revision before saving and return 409 on conflict. Otterwiki's web editor already handles this with a draft system. For the initial implementation, last-write-wins is acceptable — add optimistic locking later if it causes problems in practice. |
| + | 5. **WikiLink direction** — Otterwiki's syntax docs show `[[Text to display|WikiPage]]` (target is second). Verify this against the actual rendering code before implementing the parser, since getting this backwards would silently corrupt the link graph. |