---
name: reason
description: Comprehensive reasoning session with full introspection lifecycle and persistent state management
---

# /reason

A structured reasoning session with mandatory note-keeping, working memory management, and reflection throughout the entire process.

## Execution Protocol

When this command is invoked, you follow this protocol precisely.

### Initialize

**Session Naming**: Propose a natural, descriptive session name based on the problem (e.g., "auth-architecture-decision", "performance-root-cause"). Announce this name to the user - it unifies all artifacts created during the session.

**Check Prior Sessions**: Ask the user whether they want to reference prior sessions for context. If they confirm, invoke `Skill("introspect-reference-notes")` to list recent sessions and search for related work. If a relevant prior session exists, offer to continue from it. When continuing, use the `--continue` flag when saving notes to create a new session that builds on the prior content. If the user declines, proceed directly to context setup.

**Context Setup**: Invoke `Skill("introspect-working-memory")` to externalize the initial problem context. This establishes what you're holding in active focus as the session begins.

### Frame Phase

Apply `Skill("analysis-decompose")` and `Skill("metacognitive-knowledge-check")` to understand the problem space.

After framing, invoke `Skill("introspect-keep-notes")` to record key insights from decomposition, what is known vs unknown, and initial constraints and goals.

### Explore Phase

Apply generative skills as appropriate: `Skill("exploration-wonder")`, `Skill("exploration-branch")`, `Skill("analysis-alternatives")`.

After exploring, invoke `Skill("introspect-keep-notes")` to record options generated, branches identified, and creative possibilities worth considering.

### Analyze Phase

Apply analytical skills: `Skill("analysis-evidence-check")`, `Skill("techniques-systems-thinking")`, `Skill("analysis-logic-trace")`, `Skill("decision-premortem")` as the problem warrants.

After analysis, invoke `Skill("introspect-keep-notes")` to record evaluation of each option, risks and failure modes identified, and dependencies or interactions discovered.

### Decide Phase

Apply decision skills: `Skill("decision-weigh-options")`, `Skill("decision-priority-matrix")`.

After deciding, invoke `Skill("introspect-keep-notes")` to record the decision and its rationale, alternatives considered and why rejected, and conditions that would warrant revisiting.

### Reflect Phase

Invoke `Skill("introspect-session-reflect")` to evaluate the reasoning process itself. Persist the reflection with the session name.

Invoke `Skill("introspect-self-observation")` to log which skills were used during the session, building the usage analytics.

Invoke `Skill("introspect-working-memory")` to save final context state.

### Complete

Report to the user:

- The session name for future reference
- A summary of the decision or conclusion reached
- Location of persistent artifacts: `.claude/.thinkies/.notes/` and `.claude/.thinkies/.reflections/`

These directories are automatically gitignored. The user can reference this session later or continue from it in a future `/reason` invocation.

## When to Use This Command

Use `/reason` for significant decisions or complex problems where you want full traceability. The command creates a complete record of the reasoning process that persists beyond the session.

For lighter reasoning needs where full instrumentation isn't necessary, use `/reason-session` instead.