feat: add /understand-knowledge skill for personal knowledge base analysis by Lum1104 · Pull Request #80 · Lum1104/Understand-Anything

Lum1104 · 2026-04-10T03:02:50Z

Summary

New /understand-knowledge skill that analyzes markdown knowledge bases (Obsidian, Logseq, Dendron, Foam, Karpathy-style LLM Wiki, Zettelkasten, or plain markdown) and produces interactive knowledge graphs
Extended core type system with 5 knowledge node types (article, entity, topic, claim, source) and 6 knowledge edge types (cites, contradicts, builds_on, exemplifies, categorized_under, authored_by)
Knowledge-aware dashboard with dedicated sidebar (KnowledgeInfo), article reading panel, knowledge edge styling, and knowledge-specific ProjectOverview stats
5-agent pipeline: knowledge-scanner → format-detector → article-analyzer → relationship-builder → graph-reviewer
7 research-backed format guides for auto-detecting and parsing different PKM formats
Incremental mode (--ingest) for adding new sources to an existing knowledge graph

Details

Core (packages/core)

types.ts: 5 new node types, 6 new edge types, KnowledgeMeta interface, kind field on KnowledgeGraph
schema.ts: Zod validation for knowledge types, KnowledgeMetaSchema, 30+ LLM-friendly aliases, kind preserved through validateGraph
8 new tests (398 total passing)

Dashboard (packages/dashboard)

KnowledgeInfo.tsx: Knowledge-specific sidebar with 5 node-type-specific views (backlinks, confidence bars, frontmatter display)
ReadingPanel.tsx: Slide-up article reader with backlinks sidebar (45vh/70vh toggle)
ProjectOverview.tsx: Knowledge stats (articles/entities/topics/claims/sources), detected format badge
GraphView.tsx: Knowledge edge styling (dashed for cites, red for contradicts, etc.)
CustomNode.tsx + NodeInfo.tsx: Colors, badges, and edge labels for all knowledge types
store.ts: Knowledge node/edge categories, view mode, filter state
index.css: 5 new CSS color variables

Agents (4 new)

knowledge-scanner.md: Finds all .md files, detects directory signatures
format-detector.md: Identifies PKM format with priority-based detection
article-analyzer.md: Extracts nodes (article/entity/claim/source) and explicit edges per batch
relationship-builder.md: Discovers implicit cross-file relationships, builds topic clusters, layers, tours

Skill

SKILL.md: 8-phase pipeline (scan → detect → analyze → relationships → assemble → review → save → dashboard)
7 format guides: Obsidian, Logseq, Dendron, Foam, Karpathy, Zettelkasten, Plain

Test plan

🤖 Generated with Claude Code

…se plugin New skill that takes markdown knowledge bases (Obsidian, Logseq, Dendron, Foam, Karpathy-style, Zettelkasten, plain) and produces interactive knowledge graphs with typed nodes/edges, auto-format detection, and dashboard visualization. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Detailed step-by-step plan covering core type extensions, schema validation, dashboard changes (CSS, store, sidebar, reading panel, edge styling, layout), agent definitions, format guides, and skill definition. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Move all design docs to docs/superpowers/specs/ and all implementation plans to docs/superpowers/plans/ for consistent organization. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add 5 knowledge node types (article, entity, topic, claim, source), 6 knowledge edge types (cites, contradicts, builds_on, exemplifies, categorized_under, authored_by), KnowledgeMeta interface, and kind field on KnowledgeGraph. Update schema validation, dashboard type maps, and filter categories for full compatibility. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…comments Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… add knowledge schema tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ent type maps Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…edge graphs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…wledge-aware ProjectOverview - Use graphKind-aware layout direction for knowledge graphs (TB) - Add KNOWLEDGE_EDGE_STYLES map with distinct visual styles for knowledge edge types (cites, contradicts, builds_on, etc.) - Show knowledge-specific stats (articles, entities, topics, claims, sources) and format badge in ProjectOverview - Hide Languages/Frameworks sections for knowledge graphs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…graphKind selector

…r, and relationship-builder agents Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…pipeline Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…arsing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dbc17d6399

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-10T03:06:55Z

understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx

  service: "infra", resource: "infra", pipeline: "infra",
  table: "data", endpoint: "data", schema: "data",
  domain: "domain", flow: "domain", step: "domain",
+  article: "knowledge", entity: "knowledge", topic: "knowledge", claim: "knowledge", source: "knowledge",


Add knowledge node types to layer visibility whitelist

This adds knowledge node categories here, but useLayerDetailTopology still gates rendering through an allVisibleTypes set that only contains code/domain node names; the subsequent if (!allVisibleTypes.has(n.type)) return false filter drops article/entity/topic/claim/source nodes entirely. In a kind: "knowledge" graph, drilling into a layer can therefore render an empty layer topology even though nodes exist.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-10T03:06:55Z

understand-anything-plugin/packages/core/src/schema.ts

  interacts_with: "cross_domain",
+  // Knowledge aliases
+  references: "cites",
+  cited_by: "cites",


Drop cited_by alias unless direction is reversed

Aliasing cited_by to cites rewrites only the type string and keeps source/target unchanged, so an extracted edge like A cited_by B becomes A cites B, which inverts the relationship semantics. This can silently corrupt knowledge graphs generated from natural-language edge labels, especially because no direction correction is applied during normalization.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-10T03:06:55Z

understand-anything-plugin/packages/core/src/schema.ts


  const graph = {
    version: typeof fixed.version === "string" ? fixed.version : "1.0.0",
+    kind: fixed.kind as "codebase" | "knowledge" | undefined,


Validate graph kind instead of type-asserting input

validateGraph now copies fixed.kind via a TypeScript cast without runtime validation, so invalid strings can pass through as data.kind. Since the dashboard switches behavior on graph.kind === "knowledge", malformed values silently disable knowledge-specific UI instead of being rejected or corrected.

Useful? React with 👍 / 👎.

Lum1104 · 2026-04-11T07:05:39Z

Code review

Reviewed by five expert personas: Anthropic Claude Code Plugin Architect, OpenAI Codex Senior Reviewer, Obsidian Core Team Engineer, Anthropic API Platform Engineer, and Senior Knowledge Graph Researcher. Found 7 issues:

cited_by alias silently inverts edge direction -- cited_by: "cites" rewrites only the type string without swapping source/target, so A cited_by B becomes A cites B (opposite meaning). The codebase already warns about this exact pattern: "implemented_by" is intentionally NOT aliased to "implements" -- it inverts edge direction (see commit fd0df15). Same applies to sourced_from: "cites".

Understand-Anything/understand-anything-plugin/packages/core/src/schema.ts

Lines 117 to 119 in dbc17d6

    
           references: "cites", 
        
           cited_by: "cites", 
        
           sourced_from: "cites",

Understand-Anything/understand-anything-plugin/packages/core/src/schema.ts

Lines 136 to 138 in dbc17d6

    
           // Note: "implemented_by" is intentionally NOT aliased to "implements" — 
        
           // it inverts edge direction (see commit fd0df15). The LLM should use 
        
           // "implements" with correct source/target instead.

allVisibleTypes missing knowledge node types -- The 5 knowledge types (article, entity, topic, claim, source) are added to NODE_TYPE_TO_CATEGORY but not to the allVisibleTypes whitelist in useLayerDetailTopology(). The filter at line 275 (if (!allVisibleTypes.has(n.type)) return false) will silently drop all knowledge nodes in layer detail view.

Understand-Anything/understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx

Lines 264 to 276 in dbc17d6

    
           const subFileTypes = new Set(["function", "class"]); 
        
           const allVisibleTypes = new Set([ 
        
             "file", "module", "concept", 
        
             "config", "document", "service", "table", 
        
             "endpoint", "pipeline", "schema", "resource", 
        
             "domain", "flow", "step", 
        
             "function", "class", 
        
           ]); 
        
           let filteredGraphNodes = graph.nodes.filter((n) => { 
        
             if (!expandedLayerNodeIds.has(n.id)) return false; 
        
             if (!allVisibleTypes.has(n.type)) return false; 
        
             if (persona === "non-technical" && subFileTypes.has(n.type)) return false;

Agent edge output uses wrong field names -- article-analyzer.md and relationship-builder.md instruct the LLM to output edgeType and label, but GraphEdge requires type and description. The normalize-graph code reads raw.type, so agent-produced edges will have undefined type fields.

Understand-Anything/understand-anything-plugin/agents/article-analyzer.md

Lines 107 to 111 in dbc17d6

    
           - `source` (string): Source node ID 
        
           - `target` (string): Target node ID 
        
           - `edgeType` (string): One of `related`, `categorized_under`, `cites`, `authored_by`, `contains` 
        
           - `label` (string): Human-readable label (e.g., `"links to"`, `"cites"`, `"authored by"`) 
        
           - `weight` (number): As specified in the table above

Agent uses invalid "trivial" complexity value -- article-analyzer.md instructs LLMs to produce complexity: "trivial" for short articles. The schema only allows z.enum(["simple", "moderate", "complex"]) and "trivial" is not in the complexity alias map. Nodes will fail validation.

Understand-Anything/understand-anything-plugin/agents/article-analyzer.md

Lines 41 to 43 in dbc17d6

    
           | `tags` | Array of tags extracted from frontmatter `tags` field, inline `#tag` syntax, or empty array | 
        
           | `complexity` | `trivial` if < 20 lines, `simple` if 20-100, `moderate` if 101-300, `complex` if > 300 | 
        
           | `knowledgeMeta` | `{ nodeType: "article" }` |

Agent layer output missing required description field -- relationship-builder.md layer JSON example (line 88-93) omits the description field required by LayerSchema. Layers will fail Zod validation and be silently dropped.

Understand-Anything/understand-anything-plugin/agents/relationship-builder.md

Lines 88 to 93 in dbc17d6

    
           ```json 
        
           { 
        
             "id": "layer-<topic-name>", 
        
             "name": "<Topic Name>", 
        
             "nodeIds": ["article:...", "entity:...", "claim:..."] 
        
           }

paper aliased to entity instead of source -- In PKM/academic contexts, a paper is a citable source. Other aliases (reference, citation, bibliography) correctly map to "source", but paper maps to "entity", which will misclassify papers alongside people/organizations.

Understand-Anything/understand-anything-plugin/packages/core/src/schema.ts

Lines 67 to 70 in dbc17d6

    
           tool: "entity", 
        
           paper: "entity", 
        
           organization: "entity", 
        
           org: "entity",

strokeDasharray guard breaks knowledge edge selection highlighting -- The guard at line 500 skips selection styling for any edge with strokeDasharray. Three knowledge edge types (cites, authored_by, exemplifies) use strokeDasharray in KNOWLEDGE_EDGE_STYLES, so they will never receive selection highlighting or fade-out dimming.

Understand-Anything/understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx

Lines 498 to 504 in dbc17d6

    
           const isSelectedEdge = edge.source === selectedNodeId || edge.target === selectedNodeId; 
        
           // Don't restyle diff-impacted or portal edges 
        
           if ((edge.style as Record<string, unknown>)?.strokeDasharray) return edge; 
        
           if (isSelectedEdge) { 
        
             return { ...edge, animated: true, style: { stroke: "rgba(212,165,116,0.8)", strokeWidth: 2.5 }, labelStyle: { fill: "#d4a574", fontSize: 11, fontWeight: 600 } }; 
        
           }

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

…d kind validation Remove cited_by/sourced_from aliases that silently invert edge semantics without swapping source/target. Reclassify paper from entity to source to match other academic aliases (reference, citation, bibliography). Replace bare type-assertion of graph.kind with runtime validation that rejects invalid values and logs an auto-corrected issue. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…dge selection guard Add article/entity/topic/claim/source to allVisibleTypes so knowledge nodes are not silently dropped in layer detail view. Replace the strokeDasharray guard with a portal-specific check so knowledge edges using dashed strokes still receive selection highlighting. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…nd TourStep types Rename edgeType→type and label→description to match GraphEdgeSchema. Replace invalid trivial complexity with simple. Add required description field to layer examples and required complexity to entity/claim/source/ topic node specs. Fix tour step format to use order + nodeIds array instead of singular nodeId. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-04-11T07:21:29Z

@codex review this

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f4878f3e18

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-11T07:27:53Z

understand-anything-plugin/packages/dashboard/src/App.tsx

+      {selectedNodeId && graph?.kind === "knowledge" && <KnowledgeInfo />}
+      {selectedNodeId && graph?.kind !== "knowledge" && <NodeInfo />}


Use active view to choose the node details sidebar

When a node is selected, this branch renders KnowledgeInfo solely from graph.kind === "knowledge", but KnowledgeInfo resolves nodes from graph only. In the domain view (when domainGraph is present), selected IDs come from the domain graph, so the sidebar can’t resolve the node and shows an empty state instead of details. This breaks node inspection for that view; the sidebar selection should also account for viewMode.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-11T07:27:53Z

understand-anything-plugin/packages/dashboard/src/components/KnowledgeInfo.tsx

+          .filter((e) => e.type === "categorized_under" && e.target === node.id)
+          .map((e) => graph?.nodes.find((n) => n.id === e.source))
+          .filter((n): n is GraphNode => n !== undefined);


Filter topic members to article nodes

The Articles section for topic nodes currently includes every categorized_under source node without validating its type. Because categorized_under can connect non-article nodes too, this view can count and display entities/other types as articles, which makes the sidebar labels and counts inaccurate. Restrict this list to n.type === "article" (or relabel it to a generic membership list).

Useful? React with 👍 / 👎.

…ode, filter topic articles - KnowledgeInfo now resolves nodes from activeGraph (respecting viewMode/ domainGraph) instead of graph directly, fixing empty sidebar in domain view - setGraph sets viewMode to "knowledge" when graph.kind is "knowledge" - Topic "Articles" section filters to type === "article" only Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 and others added 15 commits April 9, 2026 22:56

docs: reorganize docs/ into superpowers/specs/ and superpowers/plans/

b3acd5b

Move all design docs to docs/superpowers/specs/ and all implementation plans to docs/superpowers/plans/ for consistent organization. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(core): preserve kind field in validateGraph and restore EdgeType …

1bc9361

…comments Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(core): add KnowledgeMetaSchema validation, complete aliases, and…

7f779f2

… add knowledge schema tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(core): add missing tag_topic alias for topic node type

d86f5fc

test(core): add negative test for out-of-range confidence values

2803f58

feat(dashboard): add knowledge CSS variables, store types, and compon…

d82cd06

…ent type maps Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(dashboard): add KnowledgeInfo sidebar and ReadingPanel for knowl…

cad7e78

…edge graphs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(dashboard): remove dead-code layout direction ternary and unused …

6537cba

…graphKind selector

feat(agents): add knowledge-scanner, format-detector, article-analyze…

0a5c410

…r, and relationship-builder agents Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(skill): add /understand-knowledge skill definition with 8-phase …

ba5525d

…pipeline Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(skill): add 7 research-backed format guides for knowledge base p…

dbc17d6

…arsing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector bot reviewed Apr 10, 2026

View reviewed changes

Lum1104 and others added 3 commits April 11, 2026 15:20

chatgpt-codex-connector bot reviewed Apr 11, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add /understand-knowledge skill for personal knowledge base analysis#80

feat: add /understand-knowledge skill for personal knowledge base analysis#80
Lum1104 wants to merge 19 commits intomainfrom
feat/understand-knowledge

Lum1104 commented Apr 10, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Apr 10, 2026

Uh oh!

chatgpt-codex-connector bot Apr 10, 2026

Uh oh!

chatgpt-codex-connector bot Apr 10, 2026

Uh oh!

Lum1104 commented Apr 11, 2026

Uh oh!

Lum1104 commented Apr 11, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Apr 11, 2026

Uh oh!

chatgpt-codex-connector bot Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		{selectedNodeId && graph?.kind === "knowledge" && <KnowledgeInfo />}
		{selectedNodeId && graph?.kind !== "knowledge" && <NodeInfo />}

Uh oh!

Conversation

Lum1104 commented Apr 10, 2026

Summary

Details

Core (packages/core)

Dashboard (packages/dashboard)

Agents (4 new)

Skill

Test plan

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Lum1104 commented Apr 11, 2026

Code review

Uh oh!

Lum1104 commented Apr 11, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant