Frontmatter
| id | 10050 |
| title | Concept Description Enrichment: Source-Grounded Semantic Anchors |
| state | Closed |
| labels | documentationenhancementaiarchitectureneeds-re-triage |
| assignees | [] |
| createdAt | Apr 17, 2026, 3:44 PM |
| updatedAt | Jun 3, 2026, 7:51 AM |
| githubUrl | https://github.com/neomjs/neo/issues/10050 |
| author | tobiu |
| commentsCount | 3 |
| parentIssue | 10030 |
| subIssues | [] |
| subIssuesCompleted | 0 |
| subIssuesTotal | 0 |
| blockedBy | [] |
| blocking | [x] 10049 Concept Schema Enrichment: Aliases, Analogous Edges & Rich Descriptions |
| closedAt | Jun 3, 2026, 7:51 AM |
Concept Description Enrichment: Source-Grounded Semantic Anchors
Input from Claude Opus 4.6 (Antigravity):
❋ ## ⚠️ Human-in-the-Loop Required: Architectural Decision History
This ticket requires the framework architect's direct input for each concept description. Agent-generated descriptions based on source code or guides will produce wrong results due to missing decision history.
Case Study: Data Worker
The ArchitectureOverview guide (line 84) states the Data Worker handles "stores, models, sorting, filtering, and grouping". An agent reading this would write:
❌ "The Data Worker moves sorting and filtering operations off the App Worker thread to prevent blocking component rendering."
This is the abandoned design. The actual architectural history:
- Original hypothesis: Move stores into the Data Worker — sorting/filtering runs off the App Worker thread.
- Why it was dropped: Serialization cost kills the idea. A ComboBox with 10 items:
JSON.stringify→postMessage→JSON.parse→ sort → reverse the entire chain. The overhead dwarfs the compute savings for reasonable dataset sizes.- What the Data Worker actually does: Backend data mutation — incoming XML → JSON transformation, structural normalization. The heavy work isn't sorting, it's I/O format conversion.
- This spawned
data-pipelines: The Connection → Parser → Normalizer pipeline, deployable in either the App Worker or Data Worker depending on workload.This decision history exists only in the creator's memory — it cannot be derived from source code, guides, or training data. The ArchitectureOverview guide itself is partially misleading on this point and may need correction.
Implication for This Ticket
Every tier-1 and tier-2 concept description needs the same treatment: validate against the architect's actual design intent, not against what the code or guides superficially suggest. This ticket should be executed as a collaborative session with
@tobiudriving the architectural rationale.
Objective
Rewrite all concept node descriptions in
.neo-ai-data/concepts/nodes.jsonlto be source-grounded, framework-accurate semantic anchors — 3-5 sentences per concept derived from actual source code andlearn/guides, not from training data approximations.Context
The current 1-2 sentence descriptions were seeded during #10031 and contain approximations that don't accurately reflect Neo.mjs architecture. Example failure:
This is wrong. Neo.mjs does not "re-render" components. State Providers use
bind: {}declarations on reactive configs. When a provider data key changes, it triggersafterSethooks on bound config properties, which surgically update specific VDOM nodes. The delta engine then calculates minimal DOM mutations.These descriptions will become the input for ChromaDB vector embeddings (#10037). Inaccurate descriptions produce misleading vectors. Each concept must be grounded in the actual implementation.
Methodology
For each concept node:
IMPLEMENTED_BYedgesEXPLAINED_BYedgesScope
Acceptance Criteria
Architectural Note
This is a content-quality prerequisite for #10049 (Schema Enrichment) and #10037 (ChromaDB Embedding). Description quality directly determines vector quality. This ticket requires a dedicated research session — it cannot be rushed.
Origin Session ID: c9bf0d61-a58d-42ba-a030-6426dc5fe270