Think Shit Through

A CLI thinking tool for Claude Code that helps you explore, challenge, and crystallize problem spaces before jumping to solutions.

TST occupies the space before implementation — where you have scattered context, a fuzzy hunch, and unexamined assumptions, and need to arrive at a clear, defensible problem framing with documented reasoning.

npx think-shit-through

What It Does

TST gives you 11 slash commands in Claude Code that guide you through a structured thinking process:

Explore your problem space through conversation. Challenge your assumptions with adversarial analysis. Check whether your thinking has converged. Generate team-readable artifacts. Hand off to implementation.

Everything you think through is persisted to disk as a Living Map — a graph of nodes, edges, and confidence scores that survives context window resets. You can /clear and /tst:resume without losing anything.

Commands

Exploration

| Command | What it does | |---------|-------------| | /tst:explore | Start or continue problem exploration through conversation | | /tst:map | View your Living Map — narrative summary, Mermaid diagram, confidence heatmap | | /tst:zoom <nodeId> | Deep-dive into a specific node with children, edges, and local context | | /tst:resume | Restore full exploration context after /clear |

Analysis

| Command | What it does | |---------|-------------| | /tst:challenge <nodeId> | Run adversarial analysis — challenges, counter-evidence, blind spots | | /tst:converge | Check convergence readiness — convictions vs uncertainties |

Research

| Command | What it does | |---------|-------------| | /tst:codebase [path] | Map a codebase as constraint-focused analysis (constraints, capabilities, boundaries, risks) | | /tst:research <mode> <topic> | Investigate a domain or topic (modes: domain, competitive, feasibility, evidence) |

Output

| Command | What it does | |---------|-------------| | /tst:generate <type> | Generate artifacts: prd, problem-space, decision-log, risk-register | | /tst:handoff | Generate SHAPE.md for implementation handoff (with readiness gate) | | /tst:ready | Check handoff readiness without generating anything |

For detailed usage examples and parameters, see the User Guide.

Install

# Interactive — prompts for runtime and location
npx think-shit-through

# Claude Code, global install
npx think-shit-through --claude --global

# Claude Code, current project only
npx think-shit-through --claude --local

This installs the 11 slash commands to your Claude Code config and creates a .planning/ directory in your project.

Requirements

• Node.js >= 18
• Claude Code (or another supported AI coding environment)

How the Thinking Flow Works

                    codebase ─┐
                    research ─┤
                              ↓
explore → map → challenge → converge → generate → handoff
   ↑                                        |
   └────────────────────────────────────────┘
         (loop until thinking converges)

1. Explore — Start with a hunch. Claude asks questions, decomposes sub-problems, and builds a graph of your thinking.
2. Map — See where you are. The Living Map shows explored vs unexplored areas, confidence levels, and open questions.
3. Challenge — Stress-test your thinking. Adversarial analysis surfaces assumptions, counter-evidence, and blind spots.
4. Converge — Check if you're done. Convergence assessment shows what you're confident about vs what's still uncertain.
5. Generate — Produce team-readable artifacts (PRDs, problem space docs, decision logs, risk registers) with audience selection.
6. Handoff — Generate a SHAPE.md that hands off your thinking to an implementation tool.

The flow is non-linear. You can challenge at any point, zoom into any node, explore new threads, and resume after breaks. The Living Map keeps everything coherent.

How State Works

TST creates a .tst/ directory in your project:

.tst/
  MAP.md          # Living Map (graph + frontmatter)
  trail/          # Thinking trail (conversation history)
  snapshot.json   # Convergence snapshots
  codebase/       # Codebase constraint analysis (from /tst:codebase)
  research/       # Domain research findings (from /tst:research)

State is written after every mutation. If Claude crashes mid-conversation, you lose at most one exchange. Run /tst:resume to pick up where you left off.

Who This Is For

Product people, founders, and anyone who needs to think through a problem before building. TST is for when you have:

• A problem you can feel but can't articulate
• Scattered context across tools and conversations
• Assumptions you haven't examined
• A team that needs to understand your reasoning

TST is not for implementation planning — that's what builder tools do. TST stops at "what and why," not "how."

License

MIT