mindmap-mcts

name	mindmap-mcts
description	Run a visible reasoning-tree workflow with lightweight MCTS for complex Codex or Claude Code tasks. Use when a task has multiple plausible hypotheses or designs, needs systematic debugging, requires option tradeoff exploration, involves repeated trial-and-error, or the user asks for a mindmap, reasoning tree, MCTS, visible exploration, branch evaluation, or evidence-backed problem solving.

MindMap-MCTS

Use this skill to keep complex work on a visible, evidence-backed reasoning tree. The bundled CLI owns the JSON truth source, UCB selection, backpropagation, markdown rendering, static HTML rendering, and interactive Markmap HTML rendering; the agent owns expansion, real probes, and judgment.

Command Prefix

Choose the command form that matches the current shell. First set the skill directory for the host that loaded this skill.

Codex on Unix shells:

export MINDMAP_MCTS_SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/mindmap-mcts"

Claude Code on Unix shells:

export MINDMAP_MCTS_SKILL_DIR="${CLAUDE_HOME:-$HOME/.claude}/skills/mindmap-mcts"

Default install locations are $HOME/.codex/skills/mindmap-mcts for Codex and $HOME/.claude/skills/mindmap-mcts for Claude Code.

Linux, macOS, WSL, or Git Bash:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" --help

Cross-platform Python launcher:

python "$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap.py" --help

Windows PowerShell:

# Claude Code:
$env:MINDMAP_MCTS_SKILL_DIR = "$env:USERPROFILE\.claude\skills\mindmap-mcts"

# Codex:
# $env:MINDMAP_MCTS_SKILL_DIR = "$env:USERPROFILE\.codex\skills\mindmap-mcts"

& "$env:MINDMAP_MCTS_SKILL_DIR\scripts\mindmap.ps1" --help

If PowerShell execution policy blocks .ps1 scripts, run the Python module directly after setting PYTHONPATH:

$env:PYTHONPATH = "$env:MINDMAP_MCTS_SKILL_DIR\scripts;$env:PYTHONPATH"
$env:PYTHONIOENCODING = "utf-8"
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
python -m mindmap_mcts.cli --help

For repeated commands in one shell session, define:

alias mindmap='"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap"'

If aliases are not preserved by the current shell call, use the explicit launcher form for the current shell.

On Windows, set UTF-8 output before rendering or showing trees that contain Chinese text:

$env:PYTHONIOENCODING = "utf-8"
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

Never hand-edit rendered markdown as the truth source. The .tree.json file is the truth source; .tree.md is only a view.

Startup

1. Decide whether this skill applies. Skip it for one-step commands, obvious one-file edits, or direct factual lookups.
2. If no tree exists, create one:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" init --title "<task title>" --out <task-name>.tree.json

The root node created by init is n1; use --parent n1 for the first child. Do not use root unless a specific tree file already contains a node with that id.

3. If a tree exists, inspect it:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" show <task-name>.tree.json

4. Render the readable view:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" render <task-name>.tree.json --out <task-name>.tree.md
"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" render-markmap <task-name>.tree.json --out <task-name>.markmap.html

Use render-markmap when the user wants a browser-based visual tree. It produces interactive HTML through Markmap's browser autoloader. The map starts with an Exploration status branch that shows best path, selected frontier, state counts, open frontier nodes, verified nodes, and pruned nodes. In the reasoning tree, completed exploration uses a green ✓, partial exploration uses a yellow ◐, and unopened frontier nodes use a gray ○; no red cross is used. Node titles are bold black, and status stays immediately after the title, for example **n11 事实性与幻觉** (V=0.90 N=1 verified). Use render-html only when a static offline fallback is preferable.

Per-Round Loop

1. Ask the CLI for the next recommended action:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" next <task-name>.tree.json

Use this to orient before making new changes to the tree.

2. Select the next frontier directly when you need only the node id:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" select <task-name>.tree.json

3. Expand the selected node with 2 or 3 child nodes. Children must be mutually exclusive, concrete, and verifiable.

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" add <task-name>.tree.json --parent <node-id> --type hypothesis --content "<specific hypothesis>"

4. Evaluate each new child using the cheapest real probe available: read code, grep a symbol, run a focused test, inspect a log, or check a config.

5. Record value and evidence:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" eval <task-name>.tree.json --id <node-id> --value <0-to-1> --evidence "<short evidence>" --probe-type <test|grep|log|paper|code-read|user-input> --source "<source pointer>" --confidence <low|medium|high>

Use --probe-type, --source, and --confidence when a score is backed by a concrete probe. Omit them only when there is no useful structured metadata.

6. Prune disproven branches instead of deleting them:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" prune <task-name>.tree.json --id <node-id> --evidence "<why this branch is ruled out>" --probe-type <test|grep|log|paper|code-read|user-input> --source "<source pointer>" --confidence <low|medium|high>

7. Backpropagate from evaluated nodes:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" backprop <task-name>.tree.json --from <node-id>

8. Render and show the updated state:

"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" render <task-name>.tree.json --out <task-name>.tree.md
"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" render-html <task-name>.tree.json --out <task-name>.tree.html
"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" render-markmap <task-name>.tree.json --out <task-name>.markmap.html
"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" show <task-name>.tree.json
"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" path <task-name>.tree.json
"$MINDMAP_MCTS_SKILL_DIR/scripts/mindmap" doctor <task-name>.tree.json

Evaluation Scale

• 0.90 to 1.00: real evidence verifies this path reaches the target.
• 0.60 to 0.80: strong signal, still needs confirmation.
• 0.30 to 0.50: uncertain or neutral signal.
• 0.10 to 0.20: evidence mostly rules this out.
• 0.00: confirmed dead branch; prune it.

Prefer real probes over model self-estimates. Evidence such as focused tests, logs, source reads, grep results, or config checks should be recorded directly on the node.

Stop Conditions

Stop exploring and write an execution plan when one of these is true:

• A root-to-leaf path has value at least 0.85 and key nodes have real evidence.
• The iteration budget is exhausted.
• Several paths remain close in value and no cheap probe can separate them.

When multiple paths remain close, stop and ask the user to choose. Show the best path, close alternatives, and evidence for each.

Reporting

When reporting progress, include:

• Current selected frontier.
• New child nodes and why they are distinct.
• Probe evidence for each evaluated node.
• Pruned branches and why they should not be retried.
• Updated best path.
• doctor output if the tree was edited by hand or imported from another run.

Forward Testing

This repository includes evaluation prompts in evals/evals.json. Use them when checking whether the skill actually improves agent behavior on debugging, architecture tradeoff, and research synthesis tasks.