file-chat-tracer

name	file-chat-tracer
description	Aligns Pi conversation-tree exploration with git file-state checkpoints. Use when starting risky experiments, designing skills/extensions, returning with /tree, or deciding whether to merge, cherry-pick, reset, or keep only distilled lessons.

File-Chat Tracer

Use this skill for AI exploration where both chat context and files may diverge.

Mental model

• /tree controls conversation state.
• git controls file state.
• tracer records bind Pi leaf id ↔ git branch/commit.
• brain/notes keep distilled lessons.
• skills/extensions should be promoted only after the experiment proves useful.

Start a risky exploration

Prefer a user-visible checkpoint first:

/trace-explore <idea>

This creates exp/<idea> and an empty start commit linked to the current chat leaf.

During exploration

Use checkpoints sparingly at meaningful milestones:

/trace-checkpoint name | why this state is valuable

or, if you are the agent and the milestone is clearly valuable, call tracer_checkpoint with a specific reason.

Do not checkpoint every turn. Do not reset or switch branches without user approval.

Returning with /tree

When the user uses /tree, tracer injects recent git anchors into the tree summary and records the new leaf id. After returning:

• if files are good: keep git as-is, continue from the older chat with less context;
• if files are bad: restore manually with /trace-restore <commit> or git reset;
• if only some files are useful: cherry-pick files from the exploration branch;
• if only lessons are useful: write distilled notes, discard code.

End-of-exploration classification

Always classify the branch:

A. keep code and lessons  -> merge/promote
B. keep only some files   -> cherry-pick
C. keep only lessons      -> write brain/memo, reset/delete branch
D. discard all            -> delete branch

Ask the user before destructive actions.

Useful commands

/trace-status
/trace-explore <idea>
/trace-checkpoint <name> | <reason>
/trace-restore <commit>

Tools exposed to the agent:

tracer_status
tracer_checkpoint