⸻
0. Intent This PRD defines MICL Sheets: a dual-layer representation for concepts that:We explicitly abandon the prior circular “Concept Glyph” dashboard as the primary UX. It can survive as an internal engineering visualization, but MICL Sheets are the new, user-facing standard.
⸻
1. Scope 1.1 In-Scope• MICL Sheet: a single image/canvas that represents one requirement-level concept.
• Two orthogonal layers:
• Sheets must:
• Be interpretable by a human engineer without any tools.
• Be scannable by a model to recover the concept vector even from sub-optimal photos/screenshots (via FEC).
1.2 Out-of-Scope (v1.0)• Encoding implementation-specific details (exact PAS wiring, deployment configs) into the vector or barcode. Those are separate concepts and get their own sheets.
• Multi-concept “scene” sheets (composite views) – v1.0 is strictly one concept per MICL Sheet.
• Live/animated layouts. v1.0 is static; animations or multi-frame GIFs are a future extension.
⸻
2. Terminology• Concept Vector: High-dimensional embedding v \in \mathbb{R}^D for a requirement-level concept.
• MICL Sheet: The whole artifact (image + barcode + human sections).
• Section: A distinct human-readable panel on the sheet (summary, UML diagram, etc.).
• Section Type: Schema label for a section, e.g. summary, uml_diagram, table, scenario_icons.
• Renderer: Any system that turns a MICL JSON spec into pixels (or reads pixels back into structure).
⸻
3. High-Level Requirements 3.1 Vector Layer Requirements• A scanner can reconstruct v with acceptable fidelity even if:
• Up to X% of tiles are corrupted/occluded (X configurable; v1.0 target ≈ 10–20%).
• Image resolution is reduced (e.g., phone photo) or slightly blurred.
• Plain-language summary text,
• UML-style diagrams and flowcharts,
• Tables of properties/interfaces,
• Icon-based scenarios / cartoons.
• Each section is typed and optional.
• Unknown section types MUST be safely ignored by renderers without breaking layout.
• Work on portrait (phone) and landscape (desktop/tablet).
• Reflow sections (stack vs grid) based on aspect ratio and available space.
• A valid barcode frame + a single summary section.
• All other sections are additive.
⸻
4. Vector Barcode Frame Specification (v1.0) 4.1 Geometry• MICL Sheet canvas can be any resolution; recommended baselines:
• Phone: ~1080×1920 (portrait)
• Desktop: ~2160×3840 or 4K
• Around the interior content area sits a white frame:
• Outer frame background: pure white.
• Just inside the outer edge: a 1–2 tile thick band of small black tiles forming a continuous “data strip” around all four sides.
Visually: a white picture frame with a thin, high-density black barcode ring hugging the content.
4.2 Dimension Mapping Vector dimensionality: D = 768 (v1.0 default). We map dimensions to tiles along edges:• Top edge: dims 0–255
• Right edge: dims 256–383
• Bottom edge: dims 384–639
• Left edge: dims 640–767
Each dimension is represented by one or more tiles, depending on chosen encoding.
4.3 Payload + FEC Each dimension v_i is:Abstract constraints (implementation-flexible):
• The barcode encoding MUST:
• Use a standard FEC scheme (e.g., Reed–Solomon, LDPC, or similar).
• Provide enough parity bits to correct:
• Random bit flips from noise/compression.
• Erasures from occluded or unreadable tiles.
• The FEC parameters (block size, parity rate) MUST be recorded in the metadata (Section 8).
Visually, tiles appear as black/gray micro-squares; humans don’t read them, but a decoder can treat the full ring as a linear codeword.
⸻
5. Human Sheet Schema (Logical) MICL Sheets are described in a JSON-like schema that is agnostic to rendering technology. 5.1 Top-Level Logical Schema{
"concept_id": "string",
"schema_version": "micl_v1.0",
"vector_ref": {
"vector_id": "string",
"dim": 768,
"barcode_encoding": "v1_fec_rs"
},
"layout": {
"priority": ["summary", "scenario_icons", "uml_activity", "uml_sequence"],
"orientation_hint": "auto" // "portrait" | "landscape" | "auto"
},
"sections": [
{ "type": "...", "...": "..." }
]
}
5.2 Core Section Types (v1.0) All sections share:• type: required.
• Additional fields determined by subtype.
5.2.1 summaryPlain text overview for humans. Can come directly from vec2text then post-edited by an LLM for concision/clarity.
{
"type": "summary",
"title": "Taxation",
"body": "Taxation is a system in which a governing body collects a portion of private income or value to fund shared public goods and services."
}
5.2.2 scenario_iconsCartoon/icon explanation for non-technical readers.
{
"type": "scenario_icons",
"panels": [
{ "icons": ["person", "money"], "label": "Gross income" },
{ "icons": ["arrow", "percent"], "label": "Tax taken" },
{ "icons": ["road", "hospital", "school"], "label": "Public services" }
]
}
The icon set is a fixed vocabulary (extensible), but renderers are free to skin it. 5.2.3 uml_diagramGeneral UML-like diagram.
{
"type": "uml_diagram",
"subtype": "sequence", // "activity", "state", "class", "component", etc.
"actors": ["Taxpayer", "Tax Authority"],
"messages": [
["Taxpayer", "Tax Authority", "report income"],
["Tax Authority", "Taxpayer", "issue tax notice"],
["Taxpayer", "Tax Authority", "pay tax"]
]
}
Other subtypes (activity/state/etc.) define their own minimal node/edge schemas. 5.2.4 tableStructured tabular data.
{
"type": "table",
"subtype": "features", // "interfaces", "params", "hazards", etc.
"columns": ["Property", "Value"],
"rows": [
["Mandatory", "Yes"],
["Regulated", "Yes"],
["Progressive", "Often"]
]
}
5.2.5 free_textArbitrary additional notes.
{
"type": "free_text",
"body": "Notes about edge cases, political variation, or limitations..."
}
5.3 Extensibility• Any new section type can be introduced with a new type string (e.g., timeline, map_overlay, etc.).
• Renderers MUST:
• Render types they know.
• Skip types they do not know, without breaking other sections.
• This makes MICL forward-compatible like XML/JSON: unknown = safely ignored.
⸻
6. Layout & Responsiveness 6.1 Concept• The sheet’s content area is all pixels inside the barcode frame.
• A layout engine:
• Reads layout.priority to know which section types are most important.
• Chooses a grid or stack depending on aspect ratio and complexity.
6.2 Portrait (Phone) Example• Sections are stacked vertically as cards:
• Long diagrams/tables can be scrollable or zoomable.
• User can pinch-zoom into any panel; barcode remains around the edge.
6.3 Landscape (Desktop / Tablet) Example• Use a 2×3 or 3×3 grid similar to the UML sheet you posted:
Row 1:
• Summary | Activity Diagram | Sequence Diagram
Row 2:
• Component/Class Diagram | Feature Table | Interfaces Table
Row 3 (optional):
• Scenario icons | Additional tables/notes | (empty or future section)
The renderer is free to pick a fit, but the semantics of each section are fixed by their type.
⸻
7. MICL vs Old Concept Glyph• Old Concept Glyph:
• Circular, 64×64 macro/residual image.
• Useful as an engineering visualization; not ideal for broad human interpretability.
• New MICL Sheet:
• Canonical human-facing representation using text + diagrams + icons.
• Barcode frame encodes concept vector with FEC.
• Internally, a MICL renderer could still generate a Concept Glyph as one more uml_diagram-like panel for engineers if we ever want it.
We treat MICL as a new line, not a minor revision.
⸻
8. Metadata & VersioningEach sheet carries metadata (internally or in a sidecar file):
{
"concept_id": "lnsp_core_platform",
"micl_version": "1.0",
"vector_ref": {
"vector_id": "vec_lnsp_core_001",
"dim": 768,
"encoding": "barcode_v1_fec_rs_0.2", // RS with 20% parity, for example
"checksum": "sha256:..."
},
"generated_by": {
"vec_source": "LNSP-embed-v4",
"vec2text_model": "vec2text-jxe-2025-11",
"llm_postedit": "GPT-5.1-DirEng"
}
}
⸻
9. Naming / Branding Notes Working name for this spec:• MICL Sheet – _Mechanistic Interpretability Concept Layout_
• Short, pronounceable (“Michael”).
• Emphasizes layout and interpretability.
Alternative label for the actual artifact if you want it more product-y:
• MIC Card – _Mechanistic Interpretability Concept Card_
• MICC – _Mechanistic Interpretability Concept Card_ (internal acronym).
You can have:
• Technology name in docs: MICL v1.0
• UX/marketing name: MIC Cards (“Every concept gets a MIC Card”).
⸻
Sample Card Got it—let’s do a clean, production-style MIC Card for “Taxation” in portrait, with everything spelled out so a designer or image model could render it 1:1.⸻
MIC Card – “Taxation” (Portrait Layout) Note: Outer border is the white 768-D barcode frame with FEC. I’ll just call it out, not expand the encoding. 0. Frame (always present)• Outer border: pure white.
• Inner rim: 1–2 tile tall band of tiny black squares all the way around → this is the 768-D concept barcode with FEC.
• Inside that rim is the content area described below.
⸻
1. Top Block – Title + Summary (full width) Title: TAXATION Summary text (2–3 sentences):Taxation is a system in which a governing body collects a portion of private income or value to fund shared public goods and services.
It converts individual resources into collective capabilities such as infrastructure, security, and social programs.
Visually: rounded rectangle, light background, bold title at top, body text below.
⸻
2. Scenario Icons (full width, under summary) A simple strip with 3 cartoon panels:• Icon: person with briefcase or laptop, coins or paycheck symbol.
• Label under icon: Gross income
• Icon: arrow from coins → government building + percent symbol.
• Label: Taxes collected
• Icons: road, hospital cross, school.
• Label: Public services
These three panels sit side-by-side in a single box titled SCENARIO (INTUITIVE VIEW).
⸻
3. Middle Row – Activity & Sequence Diagrams (2 columns) 3.1 Left: Activity / Flow DiagramBox title: ACTIVITY / FLOW
Simple top-down flow (UML-ish):
[Earn income]
|
v
[Calculate tax]
|
v
[Pay tax]
|
v
[Allocate budget to services]
Maybe drawn as rounded UML action boxes with arrows. 3.2 Right: Sequence Diagram Box title: SEQUENCE (INTERACTION OVER TIME) Two lifelines:• Taxpayer | Tax Authority
Messages:
Taxpayer → Tax Authority : report income
Tax Authority → Taxpayer : issue tax notice
Taxpayer → Tax Authority : pay tax
Tax Authority → Public Budget : update revenue
Drawn as classic UML sequence: vertical dashed lines, horizontal arrows with labels.⸻
4. Bottom Row – Tables (2 columns) 4.1 Left: Feature TableBox title: FEATURES
Property Value NotesMandatory Yes Required by law
Regulated Yes Defined in legal/tax code
Progressive Often Higher incomes taxed at higher %
Systemicity High Touches nearly every transaction
Purpose Public goods Infrastructure, services, welfare
4.2 Right: Interfaces TableBox title: INTERFACES & ACTORS
Actor Interface PayloadCitizen Tax portal / forms Income details
Employer Payroll system Withheld tax data
Tax Authority Gov. budget sys Revenue totals
⸻
Same Card as MICL JSON Spec (for your pipeline)Here’s the same thing in our MICL schema form:
{
"concept_id": "taxation",
"schema_version": "micl_v1.0",
"vector_ref": {
"vector_id": "vec_taxation_001",
"dim": 768,
"barcode_encoding": "barcode_v1_fec_rs_0.2"
},
"layout": {
"priority": [
"summary",
"scenario_icons",
"uml_activity",
"uml_sequence",
"table_features",
"table_interfaces"
],
"orientation_hint": "portrait"
},
"sections": [
{
"type": "summary",
"title": "Taxation",
"body": "Taxation is a system in which a governing body collects a portion of private income or value to fund shared public goods and services. It converts individual resources into collective capabilities such as infrastructure, security, and social programs."
},
{
"type": "scenario_icons",
"panels": [
{ "icons": ["person", "money"], "label": "Gross income" },
{ "icons": ["arrow", "percent", "gov_building"], "label": "Taxes collected" },
{ "icons": ["road", "hospital", "school"], "label": "Public services" }
]
},
{
"type": "uml_diagram",
"subtype": "activity",
"nodes": [
"Earn income",
"Calculate tax",
"Pay tax",
"Allocate budget to services"
],
"edges": [
["Earn income", "Calculate tax"],
["Calculate tax", "Pay tax"],
["Pay tax", "Allocate budget to services"]
]
},
{
"type": "uml_diagram",
"subtype": "sequence",
"actors": ["Taxpayer", "Tax Authority", "Public Budget"],
"messages": [
["Taxpayer", "Tax Authority", "report income"],
["Tax Authority", "Taxpayer", "issue tax notice"],
["Taxpayer", "Tax Authority", "pay tax"],
["Tax Authority", "Public Budget", "update revenue"]
]
},
{
"type": "table",
"subtype": "features",
"columns": ["Property", "Value", "Notes"],
"rows": [
["Mandatory", "Yes", "Required by law"],
["Regulated", "Yes", "Defined in legal/tax code"],
["Progressive", "Often", "Higher incomes taxed at higher %"],
["Systemicity", "High", "Touches nearly every transaction"],
["Purpose", "Public goods", "Infrastructure, services, welfare"]
]
},
{
"type": "table",
"subtype": "interfaces",
"columns": ["Actor", "Interface", "Payload"],
"rows": [
["Citizen", "Tax portal / forms", "Income details"],
["Employer", "Payroll system", "Withheld tax data"],
["Tax Authority", "Gov. budget system", "Revenue totals"]
]
}
]
}
This is a fully fleshed example MIC Card: you can hand the textual description to a designer or plug the JSON into a renderer. Next logical step, if you want, is to do the same for LNSP core so we see how this scales to something gnarly.