Thinking Log

---
name: thinking-log
description: |
  Automatically creates and maintains a THINKING_LOG.md file that documents Claude's reasoning process, decisions, and problem-solving approach during implementation tasks. Use this skill when: (1) User requests documentation of thinking/reasoning process, (2) Working on complex multi-step implementations, (3) User wants to understand decision-making methodology, (4) Creating audit trails for code changes, (5) User mentions "thinking log", "reasoning log", "decision log", or similar terms.
---

# Thinking Log Skill

This skill creates structured documentation of Claude's thinking process during implementation tasks, using visual diagrams and organized entries.

## Purpose

- Document reasoning and decision-making process
- Create visual flows using Mermaid diagrams
- Provide audit trail for implementation decisions
- Help users understand the "why" behind code changes
- Enable knowledge transfer and learning

## File Location

Default: `~/.claude/projects/{project-name}/docs/THINKING_LOG.md`

If user prefers project-local storage: `{project-root}/docs/THINKING_LOG.md`

Always ask user preference on first use if not specified.

## Document Structure

```markdown
# Thinking Log - {Project/Feature Name}

> Brief description of what this log documents.

---

## Visual Overview

### Workflow Diagram
[Main workflow Mermaid diagram]

---

## Session: {DATE}

### {Timestamp} - {Task Title}

**Flow:**
```mermaid
flowchart LR
    A[Input] --> B[Process] --> C[Output]
```

**Thinking:**
```
[Raw thinking content - what was analyzed, considered, decided]
```

**Decision:** [What was decided and why]
**Action:** [What was done]
**Result:** [Outcome - success/failure/partial]

---

## Methodology Summary

[Mindmap or summary of patterns used]

---

## Lessons Learned

[Key insights from this implementation]
```

## Entry Types

### 1. Analysis Entry
For understanding existing code or requirements.

```mermaid
flowchart TD
    A[Read/Analyze] --> B{Findings}
    B --> C[Key Insight 1]
    B --> D[Key Insight 2]
    C --> E[Next Action]
    D --> E
```

### 2. Decision Entry
For choosing between alternatives.

```mermaid
flowchart TD
    A[Problem/Choice] --> B{Options}
    B --> C[Option A]
    B --> D[Option B]
    C --> E{Evaluation}
    D --> E
    E --> F[Selected: Option X]
    F --> G[Rationale]
```

### 3. Implementation Entry
For tracking implementation steps.

```mermaid
flowchart LR
    A[Task] --> B[Step 1] --> C[Step 2] --> D[Verify] --> E{OK?}
    E -->|Yes| F[Complete]
    E -->|No| G[Fix] --> D
```

### 4. Error Resolution Entry
For documenting troubleshooting.

```mermaid
flowchart TD
    A[Error Detected] --> B[Analyze]
    B --> C[Root Cause]
    C --> D[Fix Applied]
    D --> E[Verify]
    E --> F[Resolved]
```

### 5. Branch/Merge Entry
For git operations and conflict resolution.

```mermaid
flowchart TD
    A[Git Operation] --> B{Conflicts?}
    B -->|Yes| C[Analyze Ownership]
    B -->|No| D[Success]
    C --> E[Resolution Strategy]
    E --> F[Apply Fix]
    F --> G[Verify Build]
```

## Mermaid Diagram Types

Use appropriate diagram types:

| Situation | Diagram Type | Example |
|-----------|--------------|---------|
| Sequential process | `flowchart LR` | Build steps |
| Decision tree | `flowchart TD` | Error handling |
| Timeline/interactions | `sequenceDiagram` | API calls |
| Concepts/categories | `mindmap` | Lessons learned |
| Git history | `gitGraph` | Branch strategy |

## Writing Guidelines

1. **Be Concise**: Focus on key decisions, not every detail
2. **Use Visuals**: Prefer diagrams over long text explanations
3. **Capture "Why"**: Document reasoning, not just actions
4. **Real-time Updates**: Add entries as work progresses, not at end
5. **Include Failures**: Document what didn't work and why

## Automatic Triggers

Add thinking log entries when:

- Starting a new implementation task
- Making architectural decisions
- Encountering and resolving errors
- Completing significant milestones
- Resolving merge conflicts
- Changing approach mid-implementation

## Example Entry

```markdown
### 2026-01-15 14:30 - Fix Shopping Cart Total Calculation

**Flow:**
```mermaid
flowchart TD
    A[Bug Report: Cart total wrong] --> B[Read cart code]
    B --> C{Found issue}
    C --> D[Discount not applied]
    C --> E[Tax calculated incorrectly]
    D --> F[Fix: Apply discount before tax]
    E --> F
    F --> G[Test] --> H[Verified]
```

**Thinking:**
```
User reported cart total showing incorrect amount.
Checked CartService - found discount was applied after tax.
Expected: discount first, then calculate tax on discounted price.
Root cause: Order of operations was wrong in calculateTotal().
```

**Decision:** Reorder calculations: subtotal → discount → tax → total
**Action:** Edit CartService.calculateTotal() to apply discount before tax
**Result:** Cart now shows correct total, verified with unit tests
```

## Integration with Workflow

1. At session start: Check if THINKING_LOG.md exists, create if needed
2. During work: Add entries for significant decisions/actions
3. At session end: Add summary if substantial work was done
4. On errors: Document troubleshooting process

## Privacy Note

THINKING_LOG.md may contain:
- File paths and code snippets
- Decision rationale
- Error messages

Recommend storing outside project source if privacy is a concern:
`~/.claude/projects/{project-name}/docs/THINKING_LOG.md`