fathom

Fathom Mode

A planning session. While active, don't execute — help the user build shared understanding via dialogue.

Resolving the script path

This skill bundle ships Python scripts in the scripts/ subdirectory next to this SKILL.md. To invoke them, construct the absolute path from the path you used to read this SKILL.md: take the SKILL.md absolute path, drop SKILL.md, append scripts/<script-name>.py. Use that absolute path with Bash. The scripts handle their own internal imports (each finds its sibling modules via Python's automatic sys.path).

State lives at ~/.fathom-mode/active_session.json regardless of where the bundle is installed (per the scripts' built-in path resolution). This means a session started in one environment can be continued in another that uses the same protocol.

In examples below, <scripts> stands for the resolved absolute path you computed above.

Starting a session

On the first user message, you MUST call both scripts before responding:

Step 1 — Create the session (no score returned):

python3 <scripts>/init_session.py --task "<user's task>"

The output has session_id, task, next_target_dimension, etc. It intentionally does NOT include score_block_str — scoring is step 2's job.

Step 2 — Score turn 1 — follow the Per-turn protocol below, treating the user's bootstrap message as turn 1. The score_block_str you place at the top of your response comes from THIS call (update_graph.py), not step 1.

Do not skip step 2. Both scripts run for the first user message.

Per-turn protocol

For each subsequent user message during an active fathom session, BEFORE responding, invoke update_graph.py via Bash with the user's message + your extracted nodes:

python3 <scripts>/update_graph.py <<'FATHOM_TURN_END'
{"user_input": "<user's verbatim message>", "nodes": [<your extracted nodes as JSON array>]}
FATHOM_TURN_END

The closing FATHOM_TURN_END must be at column 0 with no leading whitespace. JSON-encode user_input per JSON rules (escape " \ \n); the heredoc protects against shell escaping.