---
name: reason-session
description: Guide you through a structured multi-skill reasoning process with explicit orchestration and note-keeping
---

# /reason-session

Conduct a systematic, multi-step reasoning session that explicitly applies appropriate thinking skills and maintains context throughout the process.

## Execution Protocol

When this command is invoked, you establish a session and maintain notes throughout.

**Session Naming**: Propose a natural, descriptive session name based on the problem (e.g., "auth-refactoring-decision", "performance-investigation"). Announce this name to the user.

**Check Prior Sessions**: Before starting, 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 rather than starting fresh.

**Phase Checkpoints**: After completing each reasoning phase (Frame, Explore, Analyze, Decide), invoke `Skill("introspect-keep-notes")` and follow its instructions to persist your working notes. Pass your session name to the save script so all entries accumulate in the same session file.

**Session Conclusion**: After the Reflect phase, invoke `Skill("introspect-session-reflect")` and persist the reflection using the same session name.

**Continuation**: If continuing from a prior session, use the `--continue` flag when saving notes. This creates a new session file with copied content while preserving the original.

Notes are stored at `.claude/.thinkies/.notes/` (automatically gitignored) and can be referenced if context is lost or the session spans multiple turns.

## What This Command Does

This command orchestrates a complete reasoning workflow, applying multiple thinking skills in a logical sequence while maintaining notes and context. It makes the reasoning process visible, structured, and comprehensive.

## How It Works

When you use `/reason-session [your problem or goal]`, Claude will:

1. **Frame the problem**: Use `analysis-decompose` and `metacognitive-knowledge-check` to understand the problem space and identify what's known versus unknown

2. **Explore options**: Apply `exploration-wonder`, `exploration-branch`, or `analysis-alternatives` to generate possibilities and expand the solution space

3. **Analyze implications**: Use skills like `analysis-evidence-check`, `analysis-logic-trace`, `techniques-systems-thinking`, or domain-specific skills to evaluate options and understand consequences

4. **Make decisions**: Apply `decision-weigh-options`, `decision-priority-matrix`, or other decision-making skills to choose the best path forward

5. **Maintain context**: Use `introspect-keep-notes` throughout to track insights, decisions, assumptions, and open questions

6. **Reflect on process**: Conclude with `introspect-session-reflect` to evaluate the effectiveness of the reasoning approach

## When to Use This Command

Use `/reason-session` when you want:
- Structured guidance through complex problem-solving
- Explicit application of multiple thinking skills
- Context maintained across multi-step reasoning
- Visibility into the reasoning process
- A systematic approach to challenging decisions or designs
- Help orchestrating different thinking skills effectively

## Example Usage

```
User: /reason-session How should we approach refactoring this authentication system?

Claude: Starting a structured reasoning session on authentication system refactoring.

**FRAME: Understanding the Problem**

Using decompose to break down the authentication system:
- Current state: Monolithic auth service handling login, sessions, and permissions
- Pain points: Slow tests, hard to modify, security updates require full redeploy
- Constraints: Must maintain backward compatibility, zero-downtime migration

Using knowledge-check:
✓ Know: Current architecture, pain points, constraints
? Unknown: Team capacity, timeline flexibility, acceptable risk tolerance

Let me capture this in working notes...

**WORKING NOTES**:
Key Facts:
• Monolithic service with 3 concerns mixed together
• Main pain: Coupling makes changes risky

Constraints:
• Backward compatible
• Zero downtime

Open Questions:
• What's our timeline?
• Risk tolerance for this migration?

---

**EXPLORE: Generate Approaches**

Using alternatives to generate refactoring options:

Option A: Extract permissions service first (smallest, clearest boundary)
Option B: Strangler fig pattern (gradual migration)
Option C: Rebuild auth from scratch (clean slate)
Option D: Improve boundaries in place (minimal disruption)

---

**ANALYZE: Evaluate Options**

Using systems-thinking to understand dependencies:
- Permissions is called by auth AND by resource services
- Sessions tightly coupled to login logic
- Splitting permissions affects multiple systems

Using premortem on each option:
- Option A failure mode: Distributed calls create latency issues
- Option B failure mode: Running both systems doubles operational load
- Option C failure mode: Big rewrite takes too long, falls behind
- Option D failure mode: Improvements insufficient, pain continues

**NOTES UPDATE**:
Insights:
• Permissions has most external dependencies
• Option A (permissions first) might not be "easiest" given dependencies

---

**DECIDE: Choose Path**

Using weigh-options:

| Option | Risk | Value | Time | Verdict |
|--------|------|-------|------|---------|
| A | Med | High | 2mo | Concerns about dependencies |
| B | Low | High | 4mo | Best risk/reward |
| C | High | High | 8mo | Too risky |
| D | Low | Low | 2wk | Doesn't solve problem |

Recommendation: Option B (Strangler Fig)
- Lowest risk with high value
- Allows incremental validation
- Can adjust approach based on learnings

---

**REFLECT: Session Review**

Using session-reflect:
The progression decompose → alternatives → systems-thinking → premortem → weigh-options worked well. Systems-thinking after generating alternatives revealed that my initial "easiest option" wasn't actually easiest. Premortem before final decision prevented choosing option A without considering dependencies.

Pattern identified: For architecture decisions, always map system dependencies before evaluating options. Generated options often look different after understanding the dependency graph.
```