Plan: Note Decomposition
Vision
Evolve the knowledge system from monolithic HTML blobs to composable, structured notes. Plans become composed of independent phase records that can be read, updated, and queried individually. Token waste from surgical HTML editing is eliminated.
Status
COMPLETED — 2026-03-02. All 5 phases delivered. 4 active plans decomposed into 19 child phases. 98-99% token savings proven.
Phases
See child phase notes:
list_notes(parent_slug="plan-2026-03-01-note-decomposition")Key Decisions
- Phases are notes with parent_note_id, not a separate table
- Composition rendering is server-side (Jinja2)
- Backward compatible — monolithic plans render as-is
- Issues live in Forgejo only, not pal-e-docs
- MCP param names match model instincts (content not html_content)
Results
| Story | Before | After | Savings |
|---|---|---|---|
| Update phase status | 39KB, 2 calls | 0.5KB, 1 call | 98.7% |
| Query in-progress phases | 193KB, 12 calls | 1KB, 1 call | 99.5% |
| Read plan summary | 15KB | 2KB | 86.7% |
Incident
Phase 2 deployment caused ~10 min outage (SQLite DDL auto-commit). See
incident-2026-03-02-sqlite-migration-crash-pr61.Next Plan Seeds
- Issues table — structured entity with repo FK, number, priority
- Session start hook optimization — read phase summaries not full plans
- Backfill note_type/status on existing notes
- Tag retirement — strip type/lifecycle tags once columns exist
Related
plan-2026-02-28-knowledge-system-consolidation— parent plannote-conventions— the spectodo-pal-e-docs-deployment-reliability— deployment hardening