6.2 KiB
name, description
| name | description |
|---|---|
| reason-session | 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:
-
Frame the problem: Use
analysis-decomposeandmetacognitive-knowledge-checkto understand the problem space and identify what's known versus unknown -
Explore options: Apply
exploration-wonder,exploration-branch, oranalysis-alternativesto generate possibilities and expand the solution space -
Analyze implications: Use skills like
analysis-evidence-check,analysis-logic-trace,techniques-systems-thinking, or domain-specific skills to evaluate options and understand consequences -
Make decisions: Apply
decision-weigh-options,decision-priority-matrix, or other decision-making skills to choose the best path forward -
Maintain context: Use
introspect-keep-notesthroughout to track insights, decisions, assumptions, and open questions -
Reflect on process: Conclude with
introspect-session-reflectto 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.