y2-mindmap-evolve

star 0

Extract insights from conversations and place them in ExecutableGraph mindmaps using knowledge_document_tools. Auto-evolves through deduplication, confidence boosting, and relationship discovery.

Clockwork-Pilot By Clockwork-Pilot schedule Updated 6/14/2026
play_arrow Run Skill in Manus View GitHub

name: y2:mindmap_evolve description: Extract insights from conversations and place them in ExecutableGraph mindmaps using knowledge_document_tools. Auto-evolves through deduplication, confidence boosting, and relationship discovery.

Y2 Skill: MindMap Evolution

Extract valuable insights from conversations (both user statements and agent reasoning) and add them to the ExecutableGraph's /mindmaps knowledge graphs in $PROJECT_ROOT/executable_graph.k.json. The MindMap captures learnings, patterns, decisions, risks, and opportunities — fundamentally different from DecisionGraph which captures work to be done.

When to Trigger

Automatically capture insights when:

  • User makes a significant statement or decision
  • You (agent) provide reasoning or make an observation
  • A decision is made → decision insight
  • A pattern emerges → pattern insight
  • A risk or opportunity identified → risk/opportunity insight
  • Assumptions questioned → assumption insight
  • Design tradeoff articulated → tradeoff insight
  • Work completed and validated → boost confidence of supporting insights

Core Concepts

📍 MindMap File Location

All mindmaps are stored in: $PROJECT_ROOT/executable_graph.k.json under the /mindmaps field.

This is the primary ExecutableGraph knowledge document containing:

  • /graph — DecisionGraph with current state
  • /tasks — Task list for agent work
  • /mindmaps — Knowledge graphs capturing conversation learnings (organized by domain)

Where Insights Live

ExecutableGraph ($PROJECT_ROOT/executable_graphs.k.json)
  └── /mindmaps (dict of MindMaps by domain)
      ├── /architecture/
      │   ├── nodes/        (dict[str, MindMapNode])
      │   ├── edges/        (dict[str, MindMapEdge])
      │   └── deduplication_log/
      ├── /security/
      ├── /database/
      └── /... (other domains)

InsightType (Choose Correctly)

  • fact — Concrete, verified information ("Our DB is PostgreSQL 14")
  • pattern — Recurring behaviors ("We always validate at API boundary")
  • principle — Design guideline ("Prefer stateless services for scalability")
  • tradeoff — Design decision with pros/cons ("JWT: fast but complex revocation")
  • assumption — Unverified belief ("Users prefer email for 2FA")
  • question — Open question ("MySQL or PostgreSQL?")
  • decision — Explicit choice made ("We chose JWT + Redis for auth")
  • risk — Potential problem ("JWT revocation requires Redis")
  • opportunity — Exploitable advantage ("Can optimize with HTTP headers")

RelationshipType (11 Semantic Types)

  • refines — Clarifies/improves
  • contradicts — Conflicts with
  • supports — Provides evidence for
  • derives_from — Follows logically from
  • informs — Influences decision
  • blocks — Prevents action on
  • amplifies — Strengthens
  • enables — Makes possible
  • depends_on — Requires
  • explains — Provides reasoning
  • relates_to — Generic (weakest)

Workflow: Extract & Place Insights

Step 1: Recognize Valuable Input

From user:

  • "We should use JWT instead of sessions"
  • "Database latency is our bottleneck"
  • "OAuth adds complexity but solves multi-provider auth"

From you (agent):

  • "JWT is stateless and doesn't require database lookups"
  • "JWT revocation is hard—requires Redis blacklist"
  • "The risk with this approach is..."
  • "Based on tests, this approach works..."

Step 2: Decide Domain & Insight Type

What domain? architecture, security, database, infrastructure, api-design, ux, performance

What type? fact, pattern, principle, tradeoff, assumption, question, decision, risk, opportunity

Step 3: Extract only the meaning

Emit just the parts a model alone can produce — the rest is mechanical and must NOT be hand-authored:

  • type: an InsightType (fact, decision, risk, …)
  • label: short title (5–10 words)
  • description: one tight sentence — the claim
  • edges (optional): how it relates to existing insights — rel:to_id

Do not author id, proposed_at, default confidence, scaffolding, or dedup — bin/add-insights fills all of that. (Hand-authoring full nodes is the slow path: ~13s/insight of model output. The CLI is ~20× faster.)

Step 4: Capture via bin/add-insights (fast path)

The CLI does the mechanical work — id/slug, timestamps, default confidence, MinHash dedup (near-duplicate → merge + confidence boost), contradiction decay (a contradicts edge decays both endpoints), one batched patch, one render. You emit only terse deltas.

Terse form — one type|label|description|edges line per insight (edges is comma-separated rel:to_id or rel:to_id:strength; blank/# lines skipped):

printf 'decision|JWT + Redis for auth|Stateless tokens with a Redis blacklist for revocation|
risk|JWT revocation needs Redis|Native JWT cannot be revoked; needs external state|contradicts:insight_jwt_redis_for_auth:0.9\n' \
  | bin/add-insights executable_graph.k.json architecture --domain architecture --source "conversation"

Rich form — pipe a JSON array of delta dicts with --json when you need tags, an explicit confidence, related_decision_graph_ids (membership), or decision_stances ({node_id: "supports"|"contradicts"}, which drives option scoring):

echo '[{"type":"decision","label":"JWT + Redis for auth","description":"...",
  "confidence":0.85,"tags":["auth"],"related_decision_graph_ids":["topic_auth_strategy"],
  "decision_stances":{"opt_jwt_redis":"supports"}}]' \
  | bin/add-insights executable_graph.k.json architecture --json --domain architecture

Flags: --dry-run (validate only), --no-render, --threshold (dedup), --confidence (default). Prints a JSON summary (inserted / merged / edges / contradictions).

Use the raw patch-knowledge-document patches below only for edits the CLI doesn't cover (manual merges, confidence re-scoring, edits to existing nodes). For adding insights, always prefer bin/add-insights.

Examples: Add Insights Using patch-knowledge-document

Example 1: Add a Decision Insight

User: "We've decided to use JWT + Redis for authentication"

patch-knowledge-document executable_graphs.k.json '[
  {
    "op": "add",
    "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision",
    "value": {
      "kind": "insight",
      "id": "insight_jwt_redis_decision",
      "label": "Authentication: JWT + Redis revocation",
      "description": "Chose JWT tokens with Redis blacklist for revocation. Provides stateless benefits of JWT with ability to revoke sessions. Reduces server storage vs pure sessions while maintaining revocation capability.",
      "insight_type": "decision",
      "confidence": 0.85,
      "domain": "architecture",
      "tags": ["auth", "infrastructure", "scalability"],
      "source": "user decision at conversation turn 15",
      "proposed_at": "2026-06-04T18:00:00Z",
      "related_decision_graph_ids": ["topic_auth_strategy", "option_jwt_redis"]
    }
  }
]'

Example 2: Add a Risk Insight & Link It

Agent: "JWT revocation is hard—requires Redis blacklist, losing stateless benefit"

patch-knowledge-document executable_graphs.k.json '[
  {
    "op": "add",
    "path": "/mindmaps/architecture/nodes/insight_jwt_revocation_risk",
    "value": {
      "kind": "insight",
      "id": "insight_jwt_revocation_risk",
      "label": "JWT revocation requires external state",
      "description": "Native JWT doesn't support revocation; logout requires Redis/cache blacklist to mark tokens invalid. This introduces stateful infrastructure, losing one of JWT's primary benefits.",
      "insight_type": "risk",
      "confidence": 0.9,
      "domain": "architecture",
      "tags": ["auth", "infrastructure"],
      "source": "agent observation at turn 10, work_jwt_design",
      "proposed_at": "2026-06-04T18:15:00Z"
    }
  },
  {
    "op": "add",
    "path": "/mindmaps/architecture/edges/edge_jwt_contradicts_revocation",
    "value": {
      "id": "edge_jwt_contradicts_revocation",
      "from_node_id": "insight_jwt_principle",
      "to_node_id": "insight_jwt_revocation_risk",
      "relationship": "contradicts",
      "strength": 0.9,
      "reasoning": "Stateless JWT benefit is lost if revocation requires stateful blacklist",
      "created_at": "2026-06-04T18:15:00Z"
    }
  }
]'

Auto-reduce confidences due to contradiction:

patch-knowledge-document executable_graphs.k.json '[
  {"op": "replace", "path": "/mindmaps/architecture/nodes/insight_jwt_principle/confidence", "value": 0.49},
  {"op": "replace", "path": "/mindmaps/architecture/nodes/insight_jwt_revocation_risk/confidence", "value": 0.49}
]'

Example 3: Merge Similar Insights (Deduplication)

Two insights about the same concept exist; merge them:

patch-knowledge-document executable_graphs.k.json '[
  {
    "op": "replace",
    "path": "/mindmaps/architecture/nodes/insight_auth_sessions/description",
    "value": "Server-side session storage approach: user state stored in Redis/cache, session ID in cookie. Provides revocation capability by deleting session. Heavier than JWT due to lookup overhead per request. Combined from both 'session storage' and 'stateful sessions' perspectives."
  },
  {
    "op": "replace",
    "path": "/mindmaps/architecture/nodes/insight_auth_sessions/confidence",
    "value": 0.85
  },
  {
    "op": "add",
    "path": "/mindmaps/architecture/deduplication_log/-",
    "value": {
      "merged_at": "2026-06-04T18:30:00Z",
      "merged_node_id": "insight_session_storage",
      "into_node_id": "insight_auth_sessions",
      "reason": "Both describe stateful session approach; merged to consolidate viewpoints"
    }
  },
  {
    "op": "remove",
    "path": "/mindmaps/architecture/nodes/insight_session_storage"
  },
  {
    "op": "replace",
    "path": "/mindmaps/architecture/edges/edge_sessions_vs_jwt/from_node_id",
    "value": "insight_auth_sessions"
  }
]'

Example 4: Boost Confidence Based on Validation

Work is completed and tests validate a previous assumption:

patch-knowledge-document executable_graphs.k.json '[
  {
    "op": "replace",
    "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision/confidence",
    "value": 0.95
  },
  {
    "op": "replace",
    "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision/description",
    "value": "Chose JWT tokens with Redis blacklist for revocation. VALIDATED: Production tests show 95% latency improvement vs pure session approach. Successfully deployed and monitoring token revocation latency <50ms."
  },
  {
    "op": "add",
    "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision/evidence_refs/-",
    "value": "work_jwt_perf_validation"
  },
  {
    "op": "replace",
    "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision/updated_at",
    "value": "2026-06-04T19:00:00Z"
  },
  {
    "op": "replace",
    "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision/last_referenced_at",
    "value": "2026-06-04T19:00:00Z"
  }
]'

Example 5: Create New MindMap for Domain

If insights are about a new domain (security) but MindMap doesn't exist:

patch-knowledge-document executable_graphs.k.json '[
  {
    "op": "add",
    "path": "/mindmaps/security",
    "value": {
      "type": "MindMap",
      "model_version": 1,
      "id": "mindmap_security",
      "label": "Security Knowledge Graph",
      "description": "Insights about security practices, authentication, authorization, encryption",
      "nodes": {},
      "edges": {},
      "total_conversations": 0
    }
  }
]'

Then add insights to it:

patch-knowledge-document executable_graphs.k.json '[
  {
    "op": "add",
    "path": "/mindmaps/security/nodes/insight_oauth_complexity",
    "value": {
      "kind": "insight",
      "id": "insight_oauth_complexity",
      "label": "OAuth adds complexity for multi-provider auth",
      "description": "OAuth2/OpenID Connect enables authentication via Google, GitHub, etc. Adds provider complexity but eliminates password storage burden.",
      "insight_type": "tradeoff",
      "confidence": 0.8,
      "domain": "security",
      "tags": ["auth", "oauth"],
      "source": "user consideration at turn 20",
      "proposed_at": "2026-06-04T18:45:00Z"
    }
  }
]'

Auto-Evolution Rules

Rule 1: Deduplication

When you add an insight and >70% semantic match exists:

  1. Combine descriptions
  2. Merge tags (union)
  3. Boost confidence: max(old, new) * 1.1 (capped at 1.0)
  4. Redirect edges
  5. Remove old node
  6. Log merge

Rule 2: Confidence Boosting

When insight is referenced/validated in new context:

  • Increase: 0.5 → 0.7 → 0.85 → 1.0
  • Stop at 1.0
  • Update last_referenced_at
  • Add evidence if applicable

Rule 3: Contradiction Detection

When linking with contradicts:

  • Create edge
  • Auto-reduce both: confidence * 0.7 (min 0.1)
  • Surfaces conflict for human review

Rule 4: Cross-Link to HTN

When insight informs a DecisionGraph decision:

  • Add DecisionGraph node ID to related_decision_graph_ids
  • Links insights to Topics, Features, Work items

Complete Workflow Example: Auth Strategy

Turn 1: User Question

User: "How should we handle authentication—JWT or sessions?"

Add question insight:

patch-knowledge-document executable_graphs.k.json '[
  {"op": "add", "path": "/mindmaps/architecture/nodes/insight_auth_question", 
    "value": {...question insight...}}
]'

Turn 5: Agent Reasoning

You: "JWT tokens are stateless and don't require server-side storage..."

Add principle insight (your reasoning):

patch-knowledge-document executable_graphs.k.json '[
  {"op": "add", "path": "/mindmaps/architecture/nodes/insight_jwt_principle",
    "value": {...principle insight from your reasoning...}},
  {"op": "add", "path": "/mindmaps/architecture/edges/edge_jwt_informs_q",
    "value": {...link to question...}}
]'

Turn 10: Risk Discovered

You: "JWT revocation requires Redis blacklist"

Add risk and link with contradicts:

patch-knowledge-document executable_graphs.k.json '[
  {"op": "add", "path": "/mindmaps/architecture/nodes/insight_jwt_revocation_risk",
    "value": {...risk insight...}},
  {"op": "add", "path": "/mindmaps/architecture/edges/edge_jwt_contradicts",
    "value": {...contradicts edge...}},
  {"op": "replace", "path": "/mindmaps/architecture/nodes/insight_jwt_principle/confidence", "value": 0.49},
  {"op": "replace", "path": "/mindmaps/architecture/nodes/insight_jwt_revocation_risk/confidence", "value": 0.49}
]'

Turn 15: Decision Made

You: "We'll use JWT + Redis for revocation"

Add decision and link to DecisionGraph:

patch-knowledge-document executable_graphs.k.json '[
  {"op": "add", "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision",
    "value": {...decision insight, related_decision_graph_ids: ["topic_auth_strategy"]...}},
  {"op": "add", "path": "/mindmaps/architecture/edges/edge_jwt_informs_dec",
    "value": {...}},
  {"op": "add", "path": "/mindmaps/architecture/edges/edge_risk_informs_dec",
    "value": {...}}
]'

Turn 20: Implementation Validates

You: "Tests show 95% latency improvement"

Boost decision confidence:

patch-knowledge-document executable_graphs.k.json '[
  {"op": "replace", "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision/confidence", "value": 0.95},
  {"op": "add", "path": "/mindmaps/architecture/nodes/insight_jwt_redis_decision/evidence_refs/-", "value": "work_jwt_perf_test"}
]'

Best Practices

  1. Extract actively — Understand context, don't just keyword match
  2. Think semantically — "JWT avoids session storage" = "stateless tokens"
  3. Reason about links — Explain WHY insights connect
  4. Use schema first — Always run --schema-paths before patching
  5. Validate before applying — Use --dry-run to check patches
  6. Preserve history — Log merges and contradictions
  7. Cross-link early — Connect to DecisionGraph when decisions made
  8. Boost conservatively — Only on validated evidence (tests, production)
  9. Capture your reasoning — Add insights when YOU propose/observe something
  10. Complete learning record — MindMap should reflect both user input AND agent reasoning

Decision Tree: Where to Place Insight

Valuable insight identified
  ├─ About system/architecture decision?
  │  └─ /mindmaps/architecture
  ├─ About security/auth/encryption?
  │  └─ /mindmaps/security
  ├─ About database/queries/performance?
  │  └─ /mindmaps/database
  ├─ About deployment/scaling/operations?
  │  └─ /mindmaps/infrastructure
  ├─ About API design/contracts?
  │  └─ /mindmaps/api-design
  ├─ About UX/accessibility/workflow?
  │  └─ /mindmaps/ux
  └─ About performance/optimization?
     └─ /mindmaps/performance

Tips for Success

  • MindMap captures what we've learned (insights, decisions, patterns)
  • DecisionGraph captures what we must do (work, tasks, implementation)
  • Use both together: MindMap informs DecisionGraph decisions via related_decision_graph_ids
  • Extract from both user input and your own reasoning/observations
  • Every turn can generate insights — don't wait for major statements
  • Use patch-knowledge-document for all interactions with MindMap
  • Confidence grows through validation, not repetition
  • Contradictions are valuable — they surface competing considerations for human review
Install via CLI
npx skills add https://github.com/Clockwork-Pilot/y2-claude-plugin --skill y2-mindmap-evolve
Repository Details
star Stars 0
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
Clockwork-Pilot
Clockwork-Pilot Explore all skills →