beckmann-knowledge-graph-self-optimizer

Iterative self-optimization for knowledge graphs in 5 phases with 3 review gates

matthiasbeckmann987-spec@matthiasbeckmann987-spec

Install

openclaw skills install @matthiasbeckmann987-spec/beckmann-knowledge-graph-self-optimizer

Purpose

This skill orchestrates the iterative self-optimization of a knowledge graph (graph.json) across 5 phases with 3 mandatory review gates and a final merge + cleanup cycle.

The user installs one skill on ClawHub: beckmann-knowledge-graph-self-optimizer.
This skill reads the current state from the Results-and-Resources folder, determines which phase was last completed, and guides the user through the next step.

Requirements

Modern browser (Chrome/Edge/Firefox) for HTML-Tools — offline, no upload
graph.json valid JSON, tested with 2k-15k nodes, can be found in the ClawHub skill "beckmann-knowledge-graph"
AI model with large context for Sub-Skills (Claude, GPT-4o, etc.)

Quickstart

Place graph.json into Results-and-Resources/
Activate skill -> Phase 1a
Follow phases until graph_vNEXT_optimized.json
Post-Merge Protocol -> new graph.json

Folder Structure (Required)

text

beckmann-knowledge-graph-self-optimizer/
├── SKILL.md                  ← this file (global orchestrator)
├── README.md
├── package.json
├── CHANGELOG.md              ← full version history lives here, not in SKILL.md
├── Sub-Skills/
│   ├── Step1-Understanding-Prompt-Template-V3.md
│   ├── Step2-Breadth-Topic-Suggester-Prompt-Template-V1.md
│   ├── Step2-Depth-Topic-Suggester-Prompt-Template-V1.md
│   ├── Step3-Subgraph-Builder-Prompt-Template-V1.md
│   ├── Step4-Relation-Builder-Prompt-Template-V3.md
│   └── Step5-Graph-Merger-Prompt-Template-V1.md
├── HTML-Tools/
│   ├── Knowledge-Graph-Splitter.html
│   ├── Graph-Overview-Generator.html
│   └── Step5-Graph-Merger-V1.html
└── Results-and-Resources/    ← STATUS FOLDER — skill reads this on every start
    └── (variable content — see below)

Results-and-Resources — All Possible Files

The following files may be present in Results-and-Resources/ at various points during the workflow. The skill uses their presence or absence to determine the current cycle state.

File	Created in	Notes
`graph.json`	Placed by user before Phase 1	Base graph — input for every cycle
`graph_overview.json`	Phase 1 — Step 1a	Generated by `Graph-Overview-Generator.html`
`graph_Part_1_of_4.json`	Phase 1 — Step 1b	Generated by `Knowledge-Graph-Splitter.html`
`graph_Part_2_of_4.json`	Phase 1 — Step 1b	Generated by `Knowledge-Graph-Splitter.html`
`graph_Part_3_of_4.json`	Phase 1 — Step 1b	Generated by `Knowledge-Graph-Splitter.html`
`graph_Part_4_of_4.json`	Phase 1 — Step 1b	Generated by `Knowledge-Graph-Splitter.html`
`UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md`	Phase 1 — Step 1c	Output of Sub-Skill Step1
`Topic_Selection_Report_Breadth.txt`	Phase 2	Breadth track selected
`Topic_Selection_Report_Depth.txt`	Phase 2	Depth track selected
`subgraph_breadth_new.json`	Phase 3	Frozen subgraph, breadth track
`subgraph_depth_new.json`	Phase 3	Frozen subgraph, depth track
`subgraph_breadth_new_information_for_Relation_Builder.json`	Phase 3	Transient — breadth track
`subgraph_depth_new_information_for_Relation_Builder.json`	Phase 3	Transient — depth track
`subgraph_breadth_new_relations.json`	Phase 4	Bridge relations, breadth track
`subgraph_depth_new_relations.json`	Phase 4	Bridge relations, depth track
`graph_vNEXT_optimized.json`	Phase 5	Final merged output — rename to `graph.json` after cycle

Operating Policies

HTML Tools — User-Operated Only

The HTML tools in HTML-Tools/ are client-side, offline, user-operated. No data is sent externally. The agent must not try to execute them programmatically — it only instructs and then waits for the expected output file presence.

Whenever an HTML tool is required, the agent must:

Name the exact HTML tool to use.
State exactly which input files the user should load.
State exactly which output files the user should save and where.
Tell the user when the operation is complete and ask the user to confirm completion.
Continue only after the user confirms that the operation has been completed.

This rule applies to all three HTML tools, including the Phase 5 merger.

Pause, Resume, and Continuation

The skill supports both continuous execution and pause/resume execution.

A user may stop at any phase or review gate and return later.
When the skill is activated again, it reads Results-and-Resources/ and resumes from the state represented by the files that are present.
A restart after a completed phase is therefore optional, not mandatory. If the current AI session can continue safely after the required user action or confirmation, it should continue without requiring the user to restart the skill.
The user may nevertheless explicitly restart or reactivate the skill at any time, including after a long pause.
The agent must never assume that a phase was completed merely because the user says they intended to do it; the expected output file(s) must be present before the corresponding state is treated as complete.

Review Gates — Explicit Confirmation Required

The three review gates are hard control points for the workflow.

The agent must present the complete review block and explicitly wait for the user's decision.
Only an explicit (A) confirmation permits progression to the next phase.
(B) means stop at the current gate and work on the requested revision; do not proceed automatically.
(C) means stop the optimization cycle.
The agent must not infer approval from silence, unrelated messages, vague agreement, or statements such as "looks good" unless the user clearly indicates the equivalent of (A).
If the user's response is ambiguous, ask them to choose A, B, or C rather than guessing.
After a user-selected revision, the gate must be shown again and a new explicit (A) is required before proceeding.

Sub-Skills — Safe Loading

Sub-Skill prompt templates are loaded by exact filename from the Sub-Skills/ folder.

For every phase that uses a Sub-Skill, the agent must:

Confirm that the required template exists.
Load the exact template named by this skill.
Use that template as the authoritative prompt for the phase; do not silently substitute another template or an outdated version.
Confirm that all required input files listed for the phase are present before instructing the user to run the prompt.
If the required template or an input file is missing, stop and tell the user exactly what is missing instead of improvising a replacement.
After the user reports that the AI session produced the required output, verify that the expected output filename is present before treating the phase as complete.

Startup Behavior — State Detection

Every time this skill is activated, it first reads the contents of Results-and-Resources/.
Based on which files are present, it determines the current cycle state and instructs the user accordingly.

State Detection Logic (priority top → bottom)

Files present in `Results-and-Resources/`	Detected State	Action
`graph_vNEXT_optimized.json` present	Cycle COMPLETE	→ See: Post-Merge Protocol
`subgraph_*_new_relations.json` present (breadth or depth)	Phase 4 done → Gate 4→5	→ Show Gate 4→5 prompt
`subgraph__new.json` present but NO `_relations.json`	Phase 3 done → Gate 3→4	→ Show Gate 3→4 prompt
`Topic_Selection_Report_*.txt` present but NO subgraph files	Phase 2 done → Gate 2→3	→ Show Gate 2→3 prompt
`UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md` present but NO Topic Report	Phase 1 done	→ Start Phase 2
`graph_Part_1_of_4.json` present but NO Understanding Report	Phase 1 partial — split done, overview needed or report pending	→ Resume Phase 1: check whether `graph_overview.json` is also present; if yes, proceed to Step 1c (Sub-Skill); if no, ask user to run `Graph-Overview-Generator.html` first
`graph_overview.json` present but NO `graph_Part_*.json` and NO Understanding Report	Phase 1 partial — overview done, split pending	→ Ask user to run `Knowledge-Graph-Splitter.html`
`graph.json` present but NO `graph_overview.json` and NO part files	Fresh start — graph placed	→ Ask user to run `Graph-Overview-Generator.html` (Phase 1 — Step 1a)
`Results-and-Resources/` is empty	No base graph	→ Ask user to place `graph.json` in `Results-and-Resources/`

Rule: If both breadth and depth track files exist simultaneously (e.g. both Topic_Selection_Report_Breadth.txt and Topic_Selection_Report_Depth.txt), ask the user which track to continue.

Phase 1 — Understanding

Goal: Generate an overview of the graph, split graph.json into parts, and create an understanding report via Sub-Skill.

Phase 1 consists of three sequential steps, each of which must be confirmed by the user before the next begins.

Phase 1 — Step 1a: Generate Graph Overview

Tool: HTML-Tools/Graph-Overview-Generator.html
Input: graph.json
Output: graph_overview.json → save into Results-and-Resources/

Instruction to user:

text

Phase 1 — Step 1a: Generate Graph Overview

1. Open HTML-Tools/Graph-Overview-Generator.html in your browser.
   Load graph.json.
   Save the output as graph_overview.json into Results-and-Resources/.

Please confirm when graph_overview.json has been saved.

Continue to Step 1b only after the user confirms that graph_overview.json is present.

Phase 1 — Step 1b: Split Graph into Parts

Tool: HTML-Tools/Knowledge-Graph-Splitter.html
Input: graph.json
Output: graph_Part_1_of_4.json … graph_Part_4_of_4.json → save into Results-and-Resources/

Instruction to user:

text

Phase 1 — Step 1b: Split Graph into Parts

1. Open HTML-Tools/Knowledge-Graph-Splitter.html in your browser.
   Load graph.json.
   Split into 4 parts.
   Save all 4 files (graph_Part_1_of_4.json … graph_Part_4_of_4.json)
   into Results-and-Resources/.

Please confirm when all 4 part files have been saved.

Continue to Step 1c only after the user confirms that all 4 part files are present.

Phase 1 — Step 1c: Run Understanding Sub-Skill (AUTONOMOUS)

Prompt Template: Sub-Skills/Step1-Understanding-Prompt-Template-V3.md Inputs:

graph_Part_1_of_4.json … graph_Part_4_of_4.json
graph_overview.json

Output: UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md → saved autonomously into Results-and-Resources/

Execution Mode: AUTONOMOUS — no user action required in this step.

The agent executes this step independently:

Verify that all required input files are present in Results-and-Resources/:
- graph_overview.json ✓
- graph_Part_1_of_4.json ✓
- graph_Part_2_of_4.json ✓
- graph_Part_3_of_4.json ✓
- graph_Part_4_of_4.json ✓
If any file is missing: STOP and inform the user exactly which file is missing. Do NOT proceed and do NOT improvise.
Load the exact prompt template from: Sub-Skills/Step1-Understanding-Prompt-Template-V3.md
Read all 5 input files directly from Results-and-Resources/ using the available filesystem tools (read_text_file / read_multiple_files).
Execute the full prompt from the template autonomously:
- Process all 4 parts sequentially.
- Perform all 4 phases as defined in the template (Format & Data Structure, Subgraph Mapping & Clusters, Logic & Patterns, Validation & Protocol).
- Generate ONE consolidated UNDERSTANDING REPORT — not 4 partial reports.
- Fill all placeholders: [[GRAPH-VERSION]] → from graph_overview.json _meta or "current main" [[CURRENT DATE]] → current date (e.g. 2026-09-22) [[AI MODEL NAME AND VERSION]] → self-identify (e.g. "Claude Sonnet 4.6") [[NEW TEST NODE]] → use "External Reality Check 2.0" [[TOTAL]] → actual counts from files [[LIST]] → actual type list from files [[AVG ENTITIES]] → calculated from actual counts
Save the output directly to: Results-and-Resources/UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md using the available filesystem write tool (write_file).
Verify that the file was saved successfully by reading back its first few lines.
Inform the user with a short confirmation message:
- File saved: yes/no
- Entity count processed
- Relation count processed
- Any issues encountered

Phase 1 is complete when UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md is confirmed present in Results-and-Resources/. Continue to Phase 2 now, or pause here and reactivate the skill later.

Design Notes (for SKILL.md maintainer):

This autonomous execution mode requires that the agent running the skill has:

Filesystem read access to Results-and-Resources/ and Sub-Skills/
Filesystem write access to Results-and-Resources/
Sufficient context window for 5 input files simultaneously (graph_overview.json + 4 part files — tested with 2k–15k total nodes)

If the agent does NOT have filesystem write access, it must:

Produce the full report text in the current session.
Ask the user to save it manually as UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md into Results-and-Resources/.
Continue only after the user confirms the file is saved.

This fallback restores the original (V1) behavior and must be stated explicitly so the user understands why autonomous execution was not possible.

Phase 2 — Topic Selection

Goal: Select a topic for the next optimization cycle (Breadth or Depth track).

Prompt Templates:

Breadth: Sub-Skills/Step2-Breadth-Topic-Suggester-Prompt-Template-V1.md
Depth: Sub-Skills/Step2-Depth-Topic-Suggester-Prompt-Template-V1.md

Inputs:

UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md
graph_overview.json

Output: Topic_Selection_Report_Breadth.txt OR Topic_Selection_Report_Depth.txt → saved autonomously into Results-and-Resources/

Step 2a — User Track Selection (interactive — minimal)

Instruction to user:

text

Phase 2 — Topic Selection

Choose your track:
  (A) Breadth — explore new topic areas
  (B) Depth   — deepen an existing topic cluster

Wait for user input. Accept: A, B, Breadth, Depth (case-insensitive). If input is ambiguous or missing, ask once to clarify. Do NOT proceed to Step 2b until track is confirmed.

Step 2b — Autonomous Execution (no further user action required)

Once the user has chosen the track, the agent executes autonomously:

1. Verify that all required input files are present in Results-and-Resources/:

graph_overview.json ✓
UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md ✓

If any file is missing: STOP and inform the user exactly which file is missing. Do NOT proceed and do NOT improvise.

2. Load the correct prompt template from Sub-Skills/:

Track A → Step2-Breadth-Topic-Suggester-Prompt-Template-V1.md
Track B → Step2-Depth-Topic-Suggester-Prompt-Template-V1.md

3. Read both input files directly from Results-and-Resources/ using the available filesystem tools (read_text_file / read_multiple_files).

4. Execute the full prompt from the loaded template autonomously:

Replace all placeholders before generating output: [[INSERT FULL graph_overview.json HERE]] → full content of graph_overview.json [[INSERT FULL UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md HERE]] → full content of the understanding report [[GRAPH_VERSION]] → from graph_overview.json _meta (e.g., "708 entities, 1179 relations") [[DATE]] → current date (e.g., 2026-09-22) [[MODEL NAME]] → self-identify (e.g., "Claude Sonnet 4.6")
Perform all sub-steps as defined in the template: Track A (Breadth): B1 → B2 → B3 → SELF-CHECK → OUTPUT Track B (Depth): D1 → D2 → D3 → SELF-CHECK → OUTPUT
Generate ONE complete report — no partial outputs.

5. Save the output directly to Results-and-Resources/:

Track A → Topic_Selection_Report_Breadth.txt
Track B → Topic_Selection_Report_Depth.txt Using the available filesystem write tool (write_file).

6. Verify that the file was saved successfully by reading back its first few lines.

7. Inform the user with a short confirmation message:

File saved: yes/no
Track executed: Breadth / Depth
Selected theme title
Estimated entity count for new subgraph
Any issues encountered

Phase 2 is complete when the corresponding Topic Selection Report is confirmed present in Results-and-Resources/. Continue to Gate 2→3 now, or pause here and reactivate the skill later.

Design Notes (for SKILL.md maintainer):

This autonomous execution mode requires that the agent running the skill has:

Filesystem read access to Results-and-Resources/ and Sub-Skills/
Filesystem write access to Results-and-Resources/
Sufficient context window for graph_overview.json + UNDERSTANDING-REPORT simultaneously

If the agent does NOT have filesystem write access, it must:

Produce the full report text in the current session.
Ask the user to save it manually as Topic_Selection_Report_Breadth.txt or Topic_Selection_Report_Depth.txt into Results-and-Resources/.
Continue only after the user confirms the file is saved.

This fallback restores the original (V1) behavior and must be stated explicitly so the user understands why autonomous execution was not possible.

User interaction in Phase 2 is intentionally limited to ONE decision (A or B). All analytical and generative work is performed autonomously by the agent.

Gate 2→3 — Topic Review (MANDATORY STOP)

The skill displays the following block and waits for user confirmation before proceeding to Phase 3.

text

=== TOPIC SELECTION — REVIEW ===

Track: [Breadth|Depth]
Candidates evaluated: 3
Selected: [Title] — Justification: [4-6 sentences]

Anchors:
- [id] ([type]) — [reason]
- [id] ([type]) — [reason]
- [id] ([type]) — [reason]

Planned new Type Cluster: [New or Existing + Deepening Focus]
Planned Relations: >=5 Breadth / >=8 Depth

Question: (A) Yes, continue to Phase 3 / (B) Revise topics / (C) Abort

Only proceed to Phase 3 when user selects (A).

Phase 3 — Subgraph Builder

Goal: Build a new subgraph (10–20 entities, frozen) for the selected topic.

Prompt Template: Sub-Skills/Step3-Subgraph-Builder-Prompt-Template-V1.md (Unified Breadth + Depth)

Inputs:

Topic_Selection_Report_{Breadth|Depth}.txt (after Gate 2→3 approval)
graph_overview.json
UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md

Outputs (both saved autonomously into Results-and-Resources/):

subgraph_{breadth|depth}_new.json — frozen, 10–20 entities, internal relations K1–K4 ✓
subgraph_{breadth|depth}_new_information_for_Relation_Builder.json — transient, ≥3 anchors

Validation: J1 ✓ J2 ✓ J3 ✓ J4 ✓ D1 ✓ B1 ✓ K1 ✓ K2 ✓ K3 ✓ K4 ✓

Execution Mode: FULLY AUTONOMOUS — no user action required in this phase.

The agent executes all steps independently, from file reading through JSON generation to file saving. Gate 2→3 and Gate 3→4 are defined in SKILL.md and remain as the sole stop points.

1. Verify that all required input files are present in Results-and-Resources/:

graph_overview.json ✓
UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md ✓
Topic_Selection_Report_Breadth.txt OR Topic_Selection_Report_Depth.txt ✓ (Gate 2→3 must already be passed — file must be present)

If any file is missing: STOP and inform the user exactly which file is missing. Do NOT proceed and do NOT improvise.

2. Determine track by reading the Topic Selection Report:

Detect THEME — BREADTH → Track = breadth
Detect THEME — DEPTH → Track = depth

3. Load the prompt template from: Sub-Skills/Step3-Subgraph-Builder-Prompt-Template-V1.md

4. Read all 3 input files directly from Results-and-Resources/ using the available filesystem tools (read_text_file / read_multiple_files).

5. Execute the full prompt from the template autonomously — all sub-steps in sequence:

S1 — Parse Topic Selection Report (internal) Extract: Track, Title, Type Cluster / Deepening Focus, Proposed types (3-7), Anchor Points (≥3 Breadth / ≥5 Depth), Justification, Estimated Counts, Self-Check. Verify each Anchor ID in graph_overview.json entityIndex. Document replacements.

S2 — Planning Sketch (mandatory, plain text, before any JSON) Output the planning sketch to the current session before generating JSON: Core Node, Main Clusters (3-4), Connections, Rationale. For Depth: note which main-graph clusters are connected more deeply.

S3 — Generate 10–20 Entities IDs: snake_case, unique, not in entityIndex. Types: from Proposed types list of Topic Selection Report only. Descriptions: ≥20 words, English, concrete, core-logic anchored. Forbidden fields: scientific_status, label, connection_to_base_graph.

S4 — Generate Internal Relations (File 1 only) K2: no isolated nodes. K3: fully connected. K4: only new-to-new relations. Quantity: ≥5 Breadth / ≥8 Depth. Forbidden predicate: related_to. No external IDs.

S5 — Integrated Validation (J1–J4, D1, B1, K1–K4) Perform ALL checks internally before emitting any output. If any check fails: repair internally, then re-validate. Emit VALIDATION JSON block as defined in the template.

S6 — Dual-Output Generation + Final Protocol Emit in order: Planning Sketch → Validation Block → File 1 JSON → File 2 JSON → Final Protocol + STOP POINT.

6. Save both output files directly to Results-and-Resources/ using the available filesystem write tool (write_file):

subgraph_breadth_new.json OR subgraph_depth_new.json
subgraph_breadth_new_information_for_Relation_Builder.json OR subgraph_depth_new_information_for_Relation_Builder.json

7. Verify both files were saved successfully (read back first few lines of each).

8. Inform the user with a short confirmation message:

Both files saved: yes/no
Track: Breadth / Depth
Topic title
Entity count (K1)
Internal relation count (K2–K4)
Bridge relation count (B1)
All validation checks: J1–J4, D1, B1, K1–K4 — pass/fail summary
Any issues encountered

Phase 3 is complete when both output files are confirmed present in Results-and-Resources/. Gate 3→4 (defined in SKILL.md) follows — human review and approval required before Phase 4 may begin.

Design Notes (for SKILL.md maintainer):

This autonomous execution mode requires that the agent running the skill has:

Filesystem read access to Results-and-Resources/ and Sub-Skills/
Filesystem write access to Results-and-Resources/
Sufficient context window for 3 input files simultaneously (Topic Report + graph_overview.json + UNDERSTANDING-REPORT)
Note: full graph.json must NOT be read in Phase 3 — only graph_overview.json

If the agent does NOT have filesystem write access, it must:

Produce the full Planning Sketch, Validation Block, File 1 JSON, File 2 JSON and Final Protocol in the current session.
Ask the user to save both JSON files manually into Results-and-Resources/.
Continue only after the user confirms both files are saved.

This fallback restores the original (V1) behavior and must be stated explicitly so the user understands why autonomous execution was not possible.

Gate 2→3 and Gate 3→4 remain mandatory stop points as defined in SKILL.md. Phase 3 itself contains no stop points — it runs fully autonomously between the gates.

Gate 3→4 — Subgraph Review (MANDATORY STOP)

text

=== SUBGRAPH — REVIEW ===

Track: [breadth|depth]
Title: [from Report]
File1: subgraph_{breadth|depth}_new.json — [n] nodes frozen, [m] internal relations K1-K4 ✓, isolated displayable ✓
File2: subgraph_{breadth|depth}_new_information_for_Relation_Builder.json — [k] anchors, B1 >=3 ✓
Planning Sketch: present (English, Connects to... format)
Validation: J1 ✓ J2 ✓ J3 ✓ J4 ✓ D1 ✓ B1 ✓ K1 ✓ K2 ✓ K3 ✓ K4 ✓
Final Protocol: present

Question: (A) Yes, continue to Phase 4 / (B) Revise subgraph / (C) Abort

Only proceed to Phase 4 when user selects (A).

Phase 4 — Relation Builder

Goal: Build bridge relations between the new subgraph and the existing main graph.

Prompt Template: Sub-Skills/Step4-Relation-Builder-Prompt-Template-V3.md (Unified EN, rationale-free 4 fields, LANGUAGE POLICY: ENGLISH ONLY)

Inputs:

subgraph_{breadth|depth}_new.json (frozen from Phase 3)
subgraph_{breadth|depth}_new_information_for_Relation_Builder.json (transient)
graph_overview.json
Topic_Selection_Report_{Breadth|Depth}.txt
UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md

Output (saved autonomously into Results-and-Resources/):

subgraph_{breadth|depth}_new_relations.json Schema: 4 fields — subject, predicate, object, description NO rationale field. English only. Directly mergeable. Count: 3–5 (Breadth) / 5–10 (Depth)

Validation: J1 ✓ J2 V3 ✓ J3 ✓ J4 ✓ D1 V3 EN only ✓ B1b/B1d ✓ R1 ✓ R2 ✓ R3 ✓ R4 ✓ Tier ✓ English-Only ✓

Execution Mode: FULLY AUTONOMOUS — no user action required in this phase.

The agent executes all steps independently, from file reading through JSON generation to file saving. Gate 3→4 and Gate 4→5 are defined in SKILL.md and remain as the sole stop points.

1. Verify that all required input files are present in Results-and-Resources/:

graph_overview.json ✓
UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md ✓
Topic_Selection_Report_Breadth.txt OR Topic_Selection_Report_Depth.txt ✓
subgraph_breadth_new.json OR subgraph_depth_new.json ✓ (frozen)
subgraph_breadth_new_information_for_Relation_Builder.json OR subgraph_depth_new_information_for_Relation_Builder.json ✓ (transient) (Gate 3→4 must already be passed — all files must be present)

If any file is missing: STOP and inform the user exactly which file is missing. Do NOT proceed and do NOT improvise.

2. Determine track by reading the Topic Selection Report:

Detect THEME — BREADTH → Track = breadth
Detect THEME — DEPTH → Track = depth

3. Load the prompt template from: Sub-Skills/Step4-Relation-Builder-Prompt-Template-V3.md

4. Read all 5 input files directly from Results-and-Resources/ using the available filesystem tools (read_text_file / read_multiple_files). Note: File1 (frozen subgraph) MUST NOT be modified — read-only input.

5. Execute the full prompt from the template autonomously — all sub-steps in sequence:

S1 — Parse + Verify (internal) Parse File1: extract new_entity_ids, verify 10–20 entities, K1–K4 ok. Parse File2: extract anchor_points_verified, proposed_bridge_relations with rationale. Parse graph_overview: entityIndex — verify all anchor_points_verified exist. Mark invalid anchors (not in entityIndex) for discard (R3). Document replacements. Read Topic Report: extract Track, Title, Justification.

S2 — Planning Sketch Bridges (mandatory, plain text, before any JSON) Output the track-specific planning sketch to the current session before generating JSON. Format per template:

Breadth: Core Bridge + 2 Context Bridges + Discarded list + Sparsity justification
Depth: Target Cluster Bridges (≥3 same cluster) + Inter-Cluster Bridge(s) + Discarded list All English. Rationale in format: "Connects to '[Label]' (id) through [mechanism]..."

S3 — JSON Generation (final bridge relations) Generate subgraph_{track}_new_relations.json:

Exactly 4 fields per relation: subject, predicate, object, description
NO rationale field in JSON (rationale only in planning sketch)
subject: from File1 new_entity_ids only (frozen)
object: from entityIndex AND anchor_points_verified (Depth: max 2 justified extras)
predicate: Tier1/Tier2 only — Tier0 strictly forbidden (Tier0 forbidden: connects_to, related_to, associated_with, similar_to, relates_to)
description: English, 1–2 sentences, no IDs
Count: 3–5 relations (Breadth, target 3, max 1 per anchor) / 5–10 relations (Depth, target 5–8, ≥3 same cluster + 1 inter-cluster)

S4 — Integrated Validation (J1–J4, D1, B1b/B1d, R1–R4, Tier) Perform ALL checks internally before emitting any output. If any check fails: repair internally, then re-validate. Emit Validation Block as defined in the template.

S5 — Final Protocol + STOP POINT Emit in order: Planning Sketch → Validation Block → File JSON → Final Protocol + STOP POINT. Final Protocol includes:

File2 comparison (proposed / adopted / discarded with reasons / extra anchors)
Predicate Tier balance (Tier0=0 confirmed)
All validation checks listed individually
Confirmation: File1 frozen respected ✓ / Format directly mergeable ✓

6. Save the output file directly to Results-and-Resources/ using the available filesystem write tool (write_file):

subgraph_breadth_new_relations.json OR subgraph_depth_new_relations.json

7. Verify the file was saved successfully (read back first few lines).

8. Inform the user with a short confirmation message:

File saved: yes/no
Track: Breadth / Depth
Topic title
Bridge relation count generated
Predicate Tier balance (Tier0=0 confirmed / any violations)
All validation checks: J1–J4, D1, B1b/B1d, R1–R4, Tier — pass/fail summary
Discarded anchors from File2 (if any) with reasons
Any issues encountered

Phase 4 is complete when subgraph_{breadth|depth}_new_relations.json is confirmed present in Results-and-Resources/. Gate 4→5 (defined in SKILL.md) follows — human review and approval required before Phase 5 may begin.

Design Notes (for SKILL.md maintainer):

This autonomous execution mode requires that the agent running the skill has:

Filesystem read access to Results-and-Resources/ and Sub-Skills/
Filesystem write access to Results-and-Resources/
Sufficient context window for all 5 input files simultaneously (File1 frozen + File2 transient + graph_overview + Topic Report + Understanding Report)
Critical: File1 (frozen subgraph) must never be written or modified — the agent reads it as source for valid subject IDs only

If the agent does NOT have filesystem write access, it must:

Produce the full Planning Sketch, Validation Block, JSON output and Final Protocol in the current session.
Ask the user to save the JSON file manually as subgraph_{breadth|depth}_new_relations.json into Results-and-Resources/.
Continue only after the user confirms the file is saved.

This fallback restores the original (V1) behavior and must be stated explicitly so the user understands why autonomous execution was not possible.

Gate 3→4 and Gate 4→5 remain mandatory stop points as defined in SKILL.md. Phase 4 itself contains no stop points — it runs fully autonomously between the gates.

Gate 4→5 — Relations Review (MANDATORY STOP)

text

=== RELATIONS — REVIEW — V3 ===

Track: [breadth|depth]
Title: [from Topic Report]
Subgraph File: subgraph_{breadth|depth}_new.json — [n] nodes frozen, [m] internal relations K1-K4 ✓
Relations File: subgraph_{breadth|depth}_new_relations.json — [k] relations external, 4 fields (subject, predicate, object, description), NO rationale, EN description, directly mergeable ✓
Planning Sketch: present (English, Connects to 'Label' (id) through... with rationale, differentiated per track)
Validation: J1 ✓ J2 V3 (4 fields, no rationale) ✓ J3 ✓ J4 ✓ D1 V3 (English only) ✓ B1b 3-5 / B1d 5-10 ✓ R1 ✓ R2 ✓ R3 ✓ R4 (Connects to... + Tier0=0) ✓ Tier Balance ✓ English-Only ✓
File2 Comparison: proposed [k] → adopted [t] / discarded [d] / extra [e]
Tier Balance: Tier0=0, Tier1=[n], Tier2=[m], core predicate [operationalizes|refines] present
Final Protocol: present

Question: (A) Yes, final merge + cleanup / (B) Revise relations / (C) Abort

Only proceed to Phase 5 when user selects (A).

Phase 5 — Graph Assembly

Gate 4→5 has passed. All validations from Phase 3 and Phase 4 are complete.

Phase 5 consists of two sequential steps:

Step 5a: the agent reads the Sub-Skill and outputs the merge instructions to the user (autonomous)
Step 5b: the user operates the HTML merger tool and performs cleanup (user-operated by design)

Phase 5 — Step 5a: Display Merge Instructions (AUTONOMOUS)

Execution Mode: AUTONOMOUS — no user action required in this step.

1. Verify that all required merge input files are present in Results-and-Resources/:

graph.json (base graph) ✓
subgraph_breadth_new.json OR subgraph_depth_new.json (frozen from Phase 3) ✓
subgraph_breadth_new_relations.json OR subgraph_depth_new_relations.json (frozen from Phase 4 — 4 fields, English, rationale-free) ✓

If any file is missing: STOP and inform the user exactly which file is missing. Do NOT proceed and do NOT improvise.

2. Load the Sub-Skill: Sub-Skills/Step5-Graph-Merger-Prompt-Template-V1.md

3. Extract and output the full text block defined in the Sub-Skill under "THE PROMPT — What the Global Skill Must Output (English Only)". Output it verbatim to the user — no paraphrasing, no shortening.

4. Wait for user confirmation that they have read and understood the instructions.

Do NOT proceed to Step 5b until the user confirms readiness.

Phase 5 — Step 5b: Run HTML Merger Tool (USER-OPERATED)

Execution Mode: USER-OPERATED BY DESIGN. The HTML merger tool is client-side and offline. The agent does not operate it.

Instruction to user:

The merge instructions are shown above (from Step 5a). Summary:

text

1. Open HTML-Tools/Step5-Graph-Merger-V1.html in your browser.
2. Load all 3 files via the tool buttons (green check ✓ after each).
3. Click [Generate Merged Graph] → confirm dialog → download graph_vNEXT_optimized.json.
4. Save graph_vNEXT_optimized.json into Results-and-Resources/.

Then: Rename → Verify → Cleanup as shown in the merge instructions.

Please confirm when the merge, rename and cleanup are complete.

Phase 5 is complete when the user confirms that:

graph_vNEXT_optimized.json has been generated and saved

Rename to graph.json is done

Old cycle files in Results-and-Resources/ have been deleted

The skill cycle is then complete. A new cycle can be started at any time by reactivating the skill with the new graph.json as base graph.

Design Notes (for SKILL.md maintainer):

Step 5a is autonomous: the agent reads the Sub-Skill and outputs the verbatim text block to the user. The full merge instructions (HOW TO USE THE TOOL, RENAME FOR NEXT CYCLE, VERIFY, CLEANUP) are defined once in Sub-Skills/Step5-Graph-Merger-Prompt-Template-V1.md and must not be duplicated in SKILL.md.

Step 5b is user-operated by design — not a limitation of the agent. The HTML merger tool runs client-side and offline in the user's browser. No autonomous file writing occurs in Step 5b.

Post-Merge Protocol {#post-merge-protocol}

Triggered when: graph_vNEXT_optimized.json is detected in Results-and-Resources/ on activation.

All backup, rename, verification, deletion, and cleanup actions below are performed by the user. The AI agent must not rename, move, delete, overwrite, or otherwise modify these files.

text

=== CYCLE COMPLETE — POST-MERGE PROTOCOL ===

graph_vNEXT_optimized.json detected. The optimization cycle is finished.

Please follow these steps in order:

STEP 1 — BACKUP (recommended)
  Copy graph_vNEXT_optimized.json to a safe location outside this folder
  before proceeding with rename and cleanup.

STEP 2 — RENAME (USER ACTION)
  Rename: graph.json -> old_graph.json
  Rename: graph_vNEXT_optimized.json → graph.json
  Command (Windows):   ren graph.json old_graph.json
  Command (Windows):   ren graph_vNEXT_optimized.json graph.json
  Command (Mac/Linux): mv graph.json old_graph.json
  Command (Mac/Linux): mv graph_vNEXT_optimized.json graph.json
  This renamed file is your new base graph for the next cycle.
  Note: After renaming, graph_vNEXT_optimized.json no longer exists as a separate file.

STEP 3 — VERIFY
  Open the new graph.json and confirm:
  - File opens without errors
  - New entities from this cycle are present

STEP 4 — CLEANUP (MANDATORY USER ACTION)
  Delete ALL of the following from Results-and-Resources/:

  - old_graph.json (the previous version — only AFTER verifying the new one)
  - graph_Part_1_of_4.json
  - graph_Part_2_of_4.json
  - graph_Part_3_of_4.json
  - graph_Part_4_of_4.json
  - graph_overview.json
  - UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md
  - Topic_Selection_Report_Breadth.txt / Topic_Selection_Report_Depth.txt
  - subgraph_breadth_new.json / subgraph_depth_new.json
  - subgraph_breadth_new_information_for_Relation_Builder.json
  - subgraph_depth_new_information_for_Relation_Builder.json
  - subgraph_breadth_new_relations.json / subgraph_depth_new_relations.json

KEEP in Results-and-Resources/:
  - new graph.json (renamed from graph_vNEXT_optimized.json) ✓

KEEP everywhere else:
  - All HTML-Tools/ files
  - All Sub-Skills/ templates
  - SKILL.md, README.md, CHANGELOG.md, package.json

STEP 5 — CONTINUE OR PAUSE
  If you want to continue immediately, tell the AI agent that the cleanup is complete.
  The agent can then continue to the next cycle without requiring a restart.

  If you want to pause, simply stop here. When you later reactivate the skill,
  it will read Results-and-Resources/ and resume from the detected state.

Question: (A) I have completed all steps above → continue to next cycle
          (B) I need help with one of the steps above

File Registry (Source of Truth)

Active Files

Role	Exact Filename
Tool Phase 1a	`Graph-Overview-Generator.html`
Tool Phase 1b	`Knowledge-Graph-Splitter.html`
Tool Phase 5b	`Step5-Graph-Merger-V1.html`
Prompt Phase 1	`Step1-Understanding-Prompt-Template-V3.md`
Prompt Phase 2 Breadth	`Step2-Breadth-Topic-Suggester-Prompt-Template-V1.md`
Prompt Phase 2 Depth	`Step2-Depth-Topic-Suggester-Prompt-Template-V1.md`
Prompt Phase 3	`Step3-Subgraph-Builder-Prompt-Template-V1.md`
Prompt Phase 4	`Step4-Relation-Builder-Prompt-Template-V3.md`
Prompt Phase 5a	`Step5-Graph-Merger-Prompt-Template-V1.md`
Base graph	`graph.json`
Phase 5 output	`graph_vNEXT_optimized.json`

Archived / Deprecated

Filename	Reason
`JSON-Merge-Tool V5 universell.html`	Engine reference — logic preserved 1:1 in Step5-Graph-Merger-V1.html, UI deprecated
`Subgraph-Builder.html`	Deprecated since V3 — replaced by prompt template
`Format-Validator.html`	Deprecated since V3 — validation integrated in prompt
`Relation-Builder.html`	Deprecated since V3 — replaced by prompt template
`Relation-Validator.html`	Deprecated since V5 — validation integrated in prompt V3
`merged_graph.json` / `graph_vNEXT.json` (variable)	Deprecated since V4 — only `graph_vNEXT_optimized.json`
Relations schema with 5 fields (incl. `rationale`)	Deprecated since V2 — now 4 fields, rationale-free
`KnowledgeGraph-Splitter.html`	Renamed in V1.0.1 to `Knowledge-Graph-Splitter.html` (kebab-case consistent)

Language Policy

All prompt templates (Steps 1–5): English only
All gate review blocks in this skill: English
All relation content (predicate, description): English only — no German, no mixed language
Internal development documentation: not published to ClawHub
This SKILL.md: English (ClawHub publication)

Cycle Overview

text

START: Results-and-Resources/ is empty
  → User places graph.json in Results-and-Resources/
  ↓
Phase 1a: Graph-Overview-Generator.html → graph_overview.json
  ↓
Phase 1b: Knowledge-Graph-Splitter.html → graph_Part_1_of_4.json … graph_Part_4_of_4.json
  ↓
Phase 1c: Step1-Understanding-Prompt-Template-V3.md → UNDERSTANDING-REPORT-V3-From-Parts-And-Overview.md
  ↓
Phase 2: Topic Selection (Breadth or Depth track) → Topic_Selection_Report_*.txt
  ↓
Gate 2→3: MANDATORY STOP — user reviews topic choice
  ↓ (A) Yes
Phase 3: Subgraph Builder (10–20 entities, frozen) → subgraph_*_new.json + *_information_for_Relation_Builder.json
  ↓
Gate 3→4: MANDATORY STOP — user reviews subgraph
  ↓ (A) Yes
Phase 4: Relation Builder (3–10 bridge relations, 4 fields, EN) → subgraph_*_new_relations.json
  ↓
Gate 4→5: MANDATORY STOP — user reviews relations
  ↓ (A) Yes
Phase 5a: Step5-Graph-Merger-Prompt-Template-V1.md → user reads merge instructions
  ↓
Phase 5b: Step5-Graph-Merger-V1.html → graph_vNEXT_optimized.json
  ↓
Post-Merge: User Backup → User Rename → User Verify → User Cleanup
  → new graph.json (basis for next cycle)
  ↓
START next cycle

beckmann-knowledge-graph-self-optimizer

Install

Purpose

Requirements

Quickstart

Folder Structure (Required)

Results-and-Resources — All Possible Files

Operating Policies

HTML Tools — User-Operated Only

Pause, Resume, and Continuation

Review Gates — Explicit Confirmation Required

Sub-Skills — Safe Loading

Startup Behavior — State Detection

State Detection Logic (priority top → bottom)

Phase 1 — Understanding

Phase 1 — Step 1a: Generate Graph Overview

Phase 1 — Step 1b: Split Graph into Parts

Phase 1 — Step 1c: Run Understanding Sub-Skill (AUTONOMOUS)

Phase 2 — Topic Selection

Step 2a — User Track Selection (interactive — minimal)

Step 2b — Autonomous Execution (no further user action required)

Gate 2→3 — Topic Review (MANDATORY STOP)

Phase 3 — Subgraph Builder

Execution Mode: FULLY AUTONOMOUS — no user action required in this phase.

Gate 3→4 — Subgraph Review (MANDATORY STOP)

Phase 4 — Relation Builder

Execution Mode: FULLY AUTONOMOUS — no user action required in this phase.

Gate 4→5 — Relations Review (MANDATORY STOP)

Phase 5 — Graph Assembly

Phase 5 — Step 5a: Display Merge Instructions (AUTONOMOUS)

Phase 5 — Step 5b: Run HTML Merger Tool (USER-OPERATED)

Post-Merge Protocol {#post-merge-protocol}

File Registry (Source of Truth)

Active Files

Archived / Deprecated

Language Policy

Cycle Overview

Related skills