| 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
