reasoning-trace

Persist analysis decisions and findings as git-tracked Markdown notes.

1|Updated Nov 20, 2025
One-click install
npx skills add https://github.com/tony-zhelonkin/scio --skill reasoning-trace-tony-zhelonkin
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: reasoning-trace
Source: https://github.com/tony-zhelonkin/scio/tree/main/skills/reasoning-trace
Command: npx skills add https://github.com/tony-zhelonkin/scio --skill reasoning-trace-tony-zhelonkin

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Decisions made in chat sessions and exploratory probes disappear when the session ends, leaving no reproducible record of why a method, parameter, or phase boundary was chosen. This Skill enforces a discipline of writing durable, git-tracked reasoning notes so every non-trivial choice in a computational analysis project survives handoffs and future sessions. ## Core Features & Use Cases - Structured decision notes: A fixed note format captures scope, sources, evidence, the decision made, and rejected alternatives for each choice. - Scope-based placement: Notes land in docs/_internal/<stage-stem>/ for stage-scoped work or docs/_internal/_project/ for cross-stage and research topics, with session.md as the live work-state record. - No-ephemeral discipline: Throwaway probes stay in _scratch/ or $TMPDIR; only the extracted answer is committed, and every 03_results/ artifact must trace back to a committed analysis stage. - Use Case: After choosing a clustering resolution in a single-cell RNA-seq analysis, write a trace note recording the evidence, the chosen resolution, and why alternatives were rejected before moving to annotation. ## Quick Start Write a reasoning trace note for the normalization method decision we just made, including the evidence and the alternatives we rejected.

Frequently Asked Questions about reasoning-trace

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document analysis decisions in a reproducible way?▼

Write a reasoning trace note in the scope that owns the decision using the fixed format: scope, sources, then one block per decision with evidence, the decision made, and rejected alternatives. Commit the note to git so it survives beyond the chat session.

When should I write a reasoning trace note?▼

Write one whenever a non-trivial method or parameter choice is made, a phase boundary is crossed, a surprising result appears, or a handoff occurs. Routine re-runs of a committed stage with no parameter changes do not require a trace.

Where should decision notes be stored in a project?▼

Stage-scoped decisions go in docs/_internal/<stage-stem>/<topic>.md, while cross-stage decisions and literature research go in docs/_internal/_project/<topic>.md. The live work state lives in session.md within the owning scope.

Can I reference temporary files or /tmp outputs in a decision note?▼

No. Write the actual number, table, or conclusion directly into the note instead of referencing a /tmp path. Exploratory probes belong in _scratch/ or $TMPDIR and are never committed; only the extracted answer is recorded.

What are the limitations of chat-based decision records?▼

Chat summaries are ephemeral and inaccessible to future sessions or collaborators, making decisions non-reproducible. A decision with no committed trace cannot be audited, so the note must land in the repository before work proceeds.