Debug Session Documentation

调试会话文档

I'll create structured documentation for your debugging session to build a knowledge base and track your investigation process.

Based on session management patterns:

Create structured debug logs in
```
.claude/debugging/
```
Hypothesis tracking with test results
Solution documentation
Timeline of investigation
Knowledge base building for future reference

Arguments:

$ARGUMENTS

- session name or issue description

我将为你的调试会话创建结构化文档，用于构建知识库并追踪你的调查过程。

基于会话管理模式：

在
```
.claude/debugging/
```
中创建结构化调试日志
附带测试结果的假设追踪
解决方案文档
调查时间线
构建知识库以供未来参考

参数：

$ARGUMENTS

- 会话名称或问题描述

Token Optimization

Token优化

This skill uses efficient patterns to minimize token consumption while maintaining comprehensive debugging session documentation.

该技能采用高效模式，在保持调试会话文档完整性的同时最小化Token消耗。

Optimization Strategies

优化策略

1. Session State Caching (Saves 600 tokens per invocation)

1. 会话状态缓存（每次调用节省600个Token）

Cache current session metadata to avoid repeated file operations:

bash

CACHE_FILE=".claude/cache/debug-session/current.json"
CACHE_TTL=3600  # 1 hour

mkdir -p .claude/cache/debug-session

if [ -f "$CACHE_FILE" ]; then
    CACHE_AGE=$(($(date +%s) - $(stat -c %Y "$CACHE_FILE" 2>/dev/null || stat -f %m "$CACHE_FILE" 2>/dev/null)))

    if [ $CACHE_AGE -lt $CACHE_TTL ]; then
        # Use cached session info
        SESSION_NAME=$(jq -r '.name' "$CACHE_FILE")
        SESSION_FILE=$(jq -r '.file' "$CACHE_FILE")
        SESSION_STATUS=$(jq -r '.status' "$CACHE_FILE")

        echo "Using cached session: $SESSION_NAME (status: $SESSION_STATUS)"
        SKIP_FULL_INIT="true"
    fi
fi

Savings: 600 tokens when cache valid (no directory scanning, no file reads)

缓存当前会话元数据以避免重复文件操作：

bash

CACHE_FILE=".claude/cache/debug-session/current.json"
CACHE_TTL=3600  # 1 hour

mkdir -p .claude/cache/debug-session

if [ -f "$CACHE_FILE" ]; then
    CACHE_AGE=$(($(date +%s) - $(stat -c %Y "$CACHE_FILE" 2>/dev/null || stat -f %m "$CACHE_FILE" 2>/dev/null)))

    if [ $CACHE_AGE -lt $CACHE_TTL ]; then
        # Use cached session info
        SESSION_NAME=$(jq -r '.name' "$CACHE_FILE")
        SESSION_FILE=$(jq -r '.file' "$CACHE_FILE")
        SESSION_STATUS=$(jq -r '.status' "$CACHE_FILE")

        echo "Using cached session: $SESSION_NAME (status: $SESSION_STATUS)"
        SKIP_FULL_INIT="true"
    fi
fi

节省效果： 缓存有效时节省600个Token（无需目录扫描和文件读取）

2. Early Exit for Session Updates (Saves 85% tokens)

2. 会话更新提前退出（减少85%的Token消耗）

For resume operations, skip full initialization:

bash

OPERATION="${1:-new}"

case "$OPERATION" in
    resume|update|note|close)
        # Quick path: just append to existing session
        if [ -f "$CACHE_FILE" ]; then
            SESSION_FILE=$(jq -r '.file' "$CACHE_FILE")

            # Append update and exit
            echo "" >> "$SESSION_FILE"
            echo "### $(date +"%Y-%m-%d %H:%M:%S") - Session Update" >> "$SESSION_FILE"
            echo "" >> "$SESSION_FILE"
            echo "$UPDATE_TEXT" >> "$SESSION_FILE"

            echo "✓ Updated session: $(basename $SESSION_FILE)"
            exit 0
        fi
        ;;
esac

Savings: 85% reduction for update operations (1,500 → 225 tokens)

对于恢复操作，跳过完整初始化：

bash

OPERATION="${1:-new}"

case "$OPERATION" in
    resume|update|note|close)
        # Quick path: just append to existing session
        if [ -f "$CACHE_FILE" ]; then
            SESSION_FILE=$(jq -r '.file' "$CACHE_FILE")

            # Append update and exit
            echo "" >> "$SESSION_FILE"
            echo "### $(date +"%Y-%m-%d %H:%M:%S") - Session Update" >> "$SESSION_FILE"
            echo "" >> "$SESSION_FILE"
            echo "$UPDATE_TEXT" >> "$SESSION_FILE"

            echo "✓ Updated session: $(basename $SESSION_FILE)"
            exit 0
        fi
        ;;
esac

节省效果： 更新操作减少85%的Token消耗（从1500降至225个Token）

3. Template Generation on Demand (Saves 70%)

3. 按需生成模板（节省70%的Token消耗）

Only create templates when explicitly requested:

bash

undefined

仅在明确请求时创建模板：

bash

undefined

Default: Don't generate templates

CREATE_TEMPLATES="${CREATE_TEMPLATES:-false}"

if [ "$CREATE_TEMPLATES" = "true" ]; then # Generate all templates (expensive) create_debugging_templates else # Just create session file (cheap) echo "Templates skipped. Use --with-templates to generate." fi


**Savings:** 70% on first run (skip 1,200 tokens of template generation)

CREATE_TEMPLATES="${CREATE_TEMPLATES:-false}"

if [ "$CREATE_TEMPLATES" = "true" ]; then # Generate all templates (expensive) create_debugging_templates else # Just create session file (cheap) echo "Templates skipped. Use --with-templates to generate." fi


**节省效果：** 首次运行时节省70%（跳过1200个Token的模板生成操作）

4. Session List Pagination (Saves 80% for large histories)

4. 会话列表分页（针对大量历史记录节省80%的Token消耗）

Show only recent sessions by default:

bash

if [ "$OPERATION" = "list" ]; then
    # Default: show last 10 sessions
    LIMIT="${LIMIT:-10}"

    echo "Recent debug sessions (last $LIMIT):"
    ls -t .claude/debugging/sessions/*.md 2>/dev/null | head -n $LIMIT | while read session; do
        STATUS=$(grep "^**Status:**" "$session" | head -1 | cut -d' ' -f2-)
        CREATED=$(grep "^**Created:**" "$session" | head -1 | cut -d' ' -f2-)
        echo "  - $(basename $session .md) [$STATUS] - $CREATED"
    done

    echo ""
    echo "Use --all to show all sessions"
    exit 0
fi

Savings: 80% for users with many sessions (only process first 10)

默认仅显示最近的会话：

bash

if [ "$OPERATION" = "list" ]; then
    # Default: show last 10 sessions
    LIMIT="${LIMIT:-10}"

    echo "Recent debug sessions (last $LIMIT):"
    ls -t .claude/debugging/sessions/*.md 2>/dev/null | head -n $LIMIT | while read session; do
        STATUS=$(grep "^**Status:**" "$session" | head -1 | cut -d' ' -f2-)
        CREATED=$(grep "^**Created:**" "$session" | head -1 | cut -d' ' -f2-)
        echo "  - $(basename $session .md) [$STATUS] - $CREATED"
    done

    echo ""
    echo "Use --all to show all sessions"
    exit 0
fi

节省效果： 对于有大量会话的用户节省80%（仅处理前10个会话）

5. Minimal Session Reads (Saves 400 tokens)

5. 最小化会话读取（节省400个Token）

Use

head

to read only essential session info:

bash

undefined

使用

head

仅读取必要的会话信息：

bash

undefined

Read only header info (first 20 lines)

SESSION_HEADER=$(head -20 "$SESSION_FILE")

Extract key info without full read

STATUS=$(echo "$SESSION_HEADER" | grep "^Status:" | cut -d' ' -f2-) CREATED=$(echo "$SESSION_HEADER" | grep "^Created:" | cut -d' ' -f2-)

echo "Session: $SESSION_NAME" echo "Status: $STATUS" echo "Created: $CREATED"


**Savings:** 400 tokens (read 20 lines vs full 300+ line session file)

STATUS=$(echo "$SESSION_HEADER" | grep "^Status:" | cut -d' ' -f2-) CREATED=$(echo "$SESSION_HEADER" | grep "^Created:" | cut -d' ' -f2-)

echo "Session: $SESSION_NAME" echo "Status: $STATUS" echo "Created: $CREATED"


**节省效果：** 节省400个Token（读取20行而非300+行的完整会话文件）

6. Knowledge Base Search Optimization (Saves 90%)

6. 知识库搜索优化（节省90%的Token消耗）

Use Grep for KB searches instead of reading all files:

bash

if [ "$OPERATION" = "search-kb" ]; then
    QUERY="$2"

    # Grep across KB (efficient)
    echo "Searching knowledge base for: $QUERY"
    grep -r -l "$QUERY" .claude/debugging/knowledge-base/*.md 2>/dev/null | head -5 | while read file; do
        # Show only filename and first matching line
        MATCH=$(grep -m 1 "$QUERY" "$file")
        echo "  - $(basename $file): $MATCH"
    done

    exit 0
fi

Savings: 90% vs reading all KB files (Grep returns only matches)

使用Grep进行知识库搜索而非读取所有文件：

bash

if [ "$OPERATION" = "search-kb" ]; then
    QUERY="$2"

    # Grep across KB (efficient)
    echo "Searching knowledge base for: $QUERY"
    grep -r -l "$QUERY" .claude/debugging/knowledge-base/*.md 2>/dev/null | head -5 | while read file; do
        # Show only filename and first matching line
        MATCH=$(grep -m 1 "$QUERY" "$file")
        echo "  - $(basename $file): $MATCH"
    done

    exit 0
fi

节省效果： 与读取所有知识库文件相比节省90%（Grep仅返回匹配结果）

7. Incremental Documentation (Saves 60%)

7. 增量式文档（节省60%的Token消耗）

Append updates instead of regenerating full session:

bash

undefined

追加更新内容而非重新生成完整会话：

bash

undefined

Efficient update function

append_session_note() { local note_type="$1" local content="$2"

cat >> "$SESSION_FILE" << EOF

append_session_note() { local note_type="$1" local content="$2"

cat >> "$SESSION_FILE" << EOF

$(date +"%Y-%m-%d %H:%M") - $note_type

$content

EOF }

$content

EOF }

Usage: No read, just append

append_session_note "Hypothesis" "Redis connection timing out" append_session_note "Finding" "Missing timeout config in redis client" append_session_note "Solution" "Added REDIS_TIMEOUT=5000 to .env"


**Savings:** 60% (no full file read/rewrite, just append)

append_session_note "Hypothesis" "Redis connection timing out" append_session_note "Finding" "Missing timeout config in redis client" append_session_note "Solution" "Added REDIS_TIMEOUT=5000 to .env"


**节省效果：** 节省60%（无需读取/重写完整文件，仅追加内容）

8. Bash-Based Session Management (Saves 70%)

8. 基于Bash的会话管理（节省70%的Token消耗）

All session operations use pure bash (no Task agent, no Read/Edit tools):

bash

undefined

所有会话操作均使用纯bash（无Task agent，无Read/Edit工具）：

bash

undefined

All operations in bash

case "$OPERATION" in new) create_new_session ;; resume) resume_session ;; update) update_session ;; close) close_session ;; list) list_sessions ;; search-kb) search_knowledge_base ;; esac


**Savings:** 70% vs using Task agents for each operation

case "$OPERATION" in new) create_new_session ;; resume) resume_session ;; update) update_session ;; close) close_session ;; list) list_sessions ;; search-kb) search_knowledge_base ;; esac


**节省效果：** 与为每个操作使用Task agent相比节省70%

Cache Invalidation

缓存失效

Caches are invalidated when:

Session closed (manual invalidation)
1 hour elapsed (time-based for session state)
New session created (automatic reset)
User runs
```
--clear-cache
```
flag

在以下情况缓存会失效：

会话关闭（手动失效）
已过去1小时（会话状态的基于时间的失效）
创建新会话（自动重置）
用户运行
```
--clear-cache
```
标志

Real-World Token Usage

实际Token使用情况

Typical session lifecycle:

New session creation: 800-1,200 tokens
- No templates: 800 tokens (50% faster)
- With templates: 1,200 tokens
Session resume/update: 150-300 tokens
- Cached session: 150 tokens (85% savings)
- Cold start: 300 tokens
Add hypothesis/note: 100-200 tokens
- Append operation only (no full read)
List sessions: 100-400 tokens
- Last 10: 100 tokens
- All sessions: 400 tokens (with --all)
Search knowledge base: 150-300 tokens
- Grep-based search: 150 tokens
- Full text results: 300 tokens (with --verbose)
Close session: 200-400 tokens
- Update status + KB export: 400 tokens
- Status update only: 200 tokens

Average usage distribution:

65% of runs: Updates/resumes (150-300 tokens) ✅ Most common
25% of runs: New sessions (800-1,200 tokens)
10% of runs: List/search operations (100-400 tokens)

Expected token range: 150-1,200 tokens (50% reduction from 300-2,400 baseline)

典型会话生命周期：

创建新会话： 800-1200个Token
- 无模板：800个Token（速度提升50%）
- 带模板：1200个Token
恢复/更新会话： 150-300个Token
- 缓存会话：150个Token（节省85%）
- 冷启动：300个Token
添加假设/笔记： 100-200个Token
- 仅追加操作（无需完整读取）
列出会话： 100-400个Token
- 最近10个：100个Token
- 所有会话：400个Token（使用--all）
搜索知识库： 150-300个Token
- 基于Grep的搜索：150个Token
- 完整文本结果：300个Token（使用--verbose）
关闭会话： 200-400个Token
- 更新状态+导出知识库：400个Token
- 仅更新状态：200个Token

平均使用分布：

65%的运行：更新/恢复操作（150-300个Token）✅ 最常见
25%的运行：创建新会话（800-1200个Token）
10%的运行：列出/搜索操作（100-400个Token）

预期Token范围： 150-1200个Token（相比基线300-2400个Token减少50%）

Progressive Disclosure

渐进式披露

Three levels of detail:

Default (summary): Session status and recent activity

bash

claude "/debug-session"
# Shows: current session name, status, last update time
# Tokens: 150-200

Verbose (detailed): Full session timeline

bash

claude "/debug-session --verbose"
# Shows: all hypotheses, attempts, findings
# Tokens: 400-800

Full (exhaustive): Complete session + templates + KB

bash

claude "/debug-session --full"
# Shows: everything including all templates and KB entries
# Tokens: 1,000-1,500

三个细节级别：

默认（摘要）： 会话状态和最近活动

bash

claude "/debug-session"
# 显示：当前会话名称、状态、最后更新时间
# Token消耗：150-200个

详细模式： 完整会话时间线

bash

claude "/debug-session --verbose"
# 显示：所有假设、尝试、发现
# Token消耗：400-800个

完整模式： 完整会话+模板+知识库

bash

claude "/debug-session --full"
# 显示：所有内容，包括模板和知识库条目
# Token消耗：1000-1500个

Implementation Notes

实现说明

Key patterns applied:

✅ Session state caching (600 token savings)
✅ Early exit for updates (85% reduction)
✅ Template generation on demand (70% savings)
✅ Minimal session reads (400 token savings)
✅ Bash-based operations (70% savings)
✅ Incremental documentation (60% savings)
✅ Progressive disclosure (3 levels)

Cache locations:

.claude/cache/debug-session/current.json

- Current session metadata

.claude/cache/debug-session/templates-generated

- Template creation flag

Flags:

```
--with-templates
```
- Generate all templates on first run
```
--verbose
```
- Show full session timeline
```
--full
```
- Include templates and knowledge base
```
--all
```
- Show all sessions (no pagination)
```
--clear-cache
```
- Force cache invalidation

应用的关键模式：

✅ 会话状态缓存（节省600个Token）
✅ 更新操作提前退出（减少85%）
✅ 按需生成模板（节省70%）
✅ 最小化会话读取（节省400个Token）
✅ 基于Bash的操作（节省70%）
✅ 增量式文档（节省60%）
✅ 渐进式披露（3个级别）

缓存位置：

.claude/cache/debug-session/current.json

- 当前会话元数据

.claude/cache/debug-session/templates-generated

- 模板创建标志

标志：

```
--with-templates
```
- 首次运行时生成所有模板
```
--verbose
```
- 显示完整会话时间线
```
--full
```
- 包含模板和知识库
```
--all
```
- 显示所有会话（不分页）
```
--clear-cache
```
- 强制缓存失效

Phase 1: Session Initialization

阶段1：会话初始化

I'll set up a new debugging session or resume an existing one:

bash

#!/bin/bash

我将设置新的调试会话或恢复现有会话：

bash

#!/bin/bash

Debug Session Documentation

echo "=== Debug Session Management ===" echo ""

Create debugging directory structure

mkdir -p .claude/debugging/sessions mkdir -p .claude/debugging/knowledge-base

SESSION_DIR=".claude/debugging/sessions" KB_DIR=".claude/debugging/knowledge-base"

mkdir -p .claude/debugging/sessions mkdir -p .claude/debugging/knowledge-base

SESSION_DIR=".claude/debugging/sessions" KB_DIR=".claude/debugging/knowledge-base"

Determine session name

if [ -n "$ARGUMENTS" ]; then # Clean session name (remove spaces, special chars) SESSION_NAME=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | tr -s ' ' '-' | tr -cd '[:alnum:]-') else SESSION_NAME="debug-$(date +%Y%m%d-%H%M%S)" fi

SESSION_FILE="$SESSION_DIR/$SESSION_NAME.md" CURRENT_SESSION_FILE="$SESSION_DIR/.current-session"

if [ -n "$ARGUMENTS" ]; then # Clean session name (remove spaces, special chars) SESSION_NAME=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | tr -s ' ' '-' | tr -cd '[:alnum:]-') else SESSION_NAME="debug-$(date +%Y%m%d-%H%M%S)" fi

SESSION_FILE="$SESSION_DIR/$SESSION_NAME.md" CURRENT_SESSION_FILE="$SESSION_DIR/.current-session"

Check if session already exists

if [ -f "$SESSION_FILE" ]; then echo "📂 Resuming existing debug session: $SESSION_NAME" echo "" echo "Current session contents:" head -30 "$SESSION_FILE" echo "" echo "---" echo "" RESUME_MODE="true" else echo "🆕 Creating new debug session: $SESSION_NAME" RESUME_MODE="false" fi

Track current session

echo "$SESSION_NAME" > "$CURRENT_SESSION_FILE"

undefined

echo "$SESSION_NAME" > "$CURRENT_SESSION_FILE"

undefined

Phase 2: Session Structure Creation

阶段2：会话结构创建

I'll create or update the structured debugging session document:

bash

echo ""
echo "=== Initializing Debug Session ==="

if [ "$RESUME_MODE" = "false" ]; then
    # Create new session document
    cat > "$SESSION_FILE" << EOF

我将创建或更新结构化调试会话文档：

bash

echo ""
echo "=== Initializing Debug Session ==="

if [ "$RESUME_MODE" = "false" ]; then
    # Create new session document
    cat > "$SESSION_FILE" << EOF

Debug Session: $SESSION_NAME

Created: $(date) Status: 🔍 In Progress Issue: $ARGUMENTS

Issue Description

Problem Statement

[Describe the issue you're investigating]

Observed Behavior

What's happening:
Expected behavior:
Frequency: Always | Intermittent | Rare
Environment: Development | Staging | Production
First observed:

What's happening:
Expected behavior:
Frequency: Always | Intermittent | Rare
Environment: Development | Staging | Production
First observed:

Error Messages

``` [Paste error messages, stack traces here] ```

Reproduction Steps

Investigation Timeline

$(date +"%Y-%m-%d %H:%M:%S") - Session Started

Initial observations and context gathering.

Context:

Project: $(basename $(pwd))
Branch: $(git branch --show-current 2>/dev/null || echo "N/A")
Last commit: $(git log -1 --oneline 2>/dev/null || echo "N/A")

Initial observations and context gathering.

Context:

Project: $(basename $(pwd))
Branch: $(git branch --show-current 2>/dev/null || echo "N/A")
Last commit: $(git log -1 --oneline 2>/dev/null || echo "N/A")

Hypotheses

Hypothesis 1: [Primary Theory]

Status: ⏳ Pending Priority: High | Medium | Low Created: $(date +"%Y-%m-%d %H:%M")

Theory: [What you think might be causing the issue]

Evidence:

Test Plan: 1. 2.

Expected Result: [What should happen if hypothesis is correct]

Actual Result: [Will be filled after testing]

Conclusion: [ ] Confirmed | [ ] Disproved | [ ] Inconclusive

Status: ⏳ Pending Priority: High | Medium | Low Created: $(date +"%Y-%m-%d %H:%M")

Theory: [What you think might be causing the issue]

Evidence:

Test Plan: 1. 2.

Expected Result: [What should happen if hypothesis is correct]

Actual Result: [Will be filled after testing]

Conclusion: [ ] Confirmed | [ ] Disproved | [ ] Inconclusive

Hypothesis 2: [Alternative Theory]

Status: ⏳ Pending Priority: High | Medium | Low Created: $(date +"%Y-%m-%d %H:%M")

Theory: [Alternative explanation]

Evidence:

Test Plan: 1.

Expected Result:

Actual Result:

Conclusion: [ ] Confirmed | [ ] Disproved | [ ] Inconclusive

Status: ⏳ Pending Priority: High | Medium | Low Created: $(date +"%Y-%m-%d %H:%M")

Theory: [Alternative explanation]

Evidence:

Test Plan: 1.

Expected Result:

Actual Result:

Conclusion: [ ] Confirmed | [ ] Disproved | [ ] Inconclusive

Investigation Notes

Code Analysis

Files Examined:

Key Findings:

Files Examined:

Key Findings:

Configuration Review

Config Files Checked:

Issues Found:

Config Files Checked:

Issues Found:

Dependency Analysis

Packages Investigated:

Version Conflicts:

Packages Investigated:

Version Conflicts:

Attempted Solutions

Attempt 1: [Solution Description]

Timestamp: $(date +"%Y-%m-%d %H:%M") Approach:

Steps Taken: 1. 2.

Result: ✅ Success | ❌ Failed | ⚠️ Partial Notes:

Timestamp: $(date +"%Y-%m-%d %H:%M") Approach:

Steps Taken: 1. 2.

Result: ✅ Success | ❌ Failed | ⚠️ Partial Notes:

Solution

Status: 🔍 Investigating | ✅ Resolved | ❌ Blocked

Root Cause

[Will be filled when identified]

Fix Applied

[Will be filled when resolved]

Implementation: ``` [Code changes or configuration updates] ```

[Will be filled when resolved]

Implementation: ``` [Code changes or configuration updates] ```

Verification

Original issue resolved
Tests passing
No regressions introduced
Documented for future reference

Original issue resolved
Tests passing
No regressions introduced
Documented for future reference

Lessons Learned

What Worked

What Didn't Work

Prevention Strategy

[How to prevent this issue in the future]

Resources

Documentation Consulted

Related Issues

Helpful Commands

```bash

Add useful commands discovered during debugging

```

Next Session Actions

[ ]
[ ]

Session Statistics:

Time Spent: [Track your time]
Hypotheses Tested: 0
Solutions Attempted: 0
Status: In Progress EOF

echo "✓ Created debug session: $SESSION_FILE" else

Update existing session

cat >> "$SESSION_FILE" << EOF

[ ]
[ ]

Session Statistics:

Time Spent: [Track your time]
Hypotheses Tested: 0
Solutions Attempted: 0
Status: In Progress EOF

echo "✓ Created debug session: $SESSION_FILE" else

Update existing session

cat >> "$SESSION_FILE" << EOF

$(date +"%Y-%m-%d %H:%M:%S") - Session Resumed

Continuing investigation...

EOF

echo "✓ Updated debug session: $SESSION_FILE"

fi

undefined

Continuing investigation...

EOF

echo "✓ Updated debug session: $SESSION_FILE"

fi

undefined

Phase 3: Quick Update Helpers

阶段3：快速更新助手

I'll provide quick commands to update the session:

bash

echo ""
echo "=== Session Update Helpers ==="

cat > "$SESSION_DIR/update-session.sh" << 'UPDATESCRIPT'
#!/bin/bash

我将提供快速命令来更新会话：

bash

echo ""
echo "=== Session Update Helpers ==="

cat > "$SESSION_DIR/update-session.sh" << 'UPDATESCRIPT'
#!/bin/bash

Quick session update helpers

CURRENT_SESSION=$(cat .claude/debugging/sessions/.current-session 2>/dev/null) SESSION_FILE=".claude/debugging/sessions/$CURRENT_SESSION.md"

if [ ! -f "$SESSION_FILE" ]; then echo "❌ No active debug session" echo "Start one with: claude '/debug-session <issue-name>'" exit 1 fi

update_type="${1:-note}" message="${2:-}"

case "$update_type" in note) cat >> "$SESSION_FILE" << EOF

CURRENT_SESSION=$(cat .claude/debugging/sessions/.current-session 2>/dev/null) SESSION_FILE=".claude/debugging/sessions/$CURRENT_SESSION.md"

if [ ! -f "$SESSION_FILE" ]; then echo "❌ No active debug session" echo "Start one with: claude '/debug-session <issue-name>'" exit 1 fi

update_type="${1:-note}" message="${2:-}"

case "$update_type" in note) cat >> "$SESSION_FILE" << EOF

$(date +"%Y-%m-%d %H:%M") - Note

$message

EOF echo "✓ Added note to session" ;;

hypothesis)
    hypothesis_num=$(grep -c "### Hypothesis" "$SESSION_FILE")
    hypothesis_num=$((hypothesis_num + 1))

    cat >> "$SESSION_FILE" << EOF

$message

EOF echo "✓ Added note to session" ;;

hypothesis)
    hypothesis_num=$(grep -c "### Hypothesis" "$SESSION_FILE")
    hypothesis_num=$((hypothesis_num + 1))

    cat >> "$SESSION_FILE" << EOF

Hypothesis $hypothesis_num: $message

Status: ⏳ Pending Priority: Medium Created: $(date +"%Y-%m-%d %H:%M")

Theory: [Fill in theory]

Test Plan: 1.

Expected Result:

Actual Result:

Conclusion: [ ] Confirmed | [ ] Disproved | [ ] Inconclusive

EOF echo "✓ Added hypothesis $hypothesis_num" ;;

solution)
    sed -i "s/^**Status:** 🔍 Investigating.*/**Status:** ✅ Resolved/" "$SESSION_FILE"

    cat >> "$SESSION_FILE" << EOF

Status: ⏳ Pending Priority: Medium Created: $(date +"%Y-%m-%d %H:%M")

Theory: [Fill in theory]

Test Plan: 1.

Expected Result:

Actual Result:

Conclusion: [ ] Confirmed | [ ] Disproved | [ ] Inconclusive

EOF echo "✓ Added hypothesis $hypothesis_num" ;;

solution)
    sed -i "s/^**Status:** 🔍 Investigating.*/**Status:** ✅ Resolved/" "$SESSION_FILE"

    cat >> "$SESSION_FILE" << EOF

✅ Solution Found

Timestamp: $(date +"%Y-%m-%d %H:%M") Description: $message

EOF echo "✓ Marked session as resolved" ;;

close)
    sed -i "s/^**Status:** 🔍 In Progress.*/**Status:** ✅ Closed/" "$SESSION_FILE"

    cat >> "$SESSION_FILE" << EOF

Timestamp: $(date +"%Y-%m-%d %H:%M") Description: $message

EOF echo "✓ Marked session as resolved" ;;

close)
    sed -i "s/^**Status:** 🔍 In Progress.*/**Status:** ✅ Closed/" "$SESSION_FILE"

    cat >> "$SESSION_FILE" << EOF

Session Summary

Closed: $(date) Total Time: $message Outcome: Issue resolved

EOF echo "✓ Closed debug session" # Remove current session tracking rm -f .claude/debugging/sessions/.current-session ;;

*)
    echo "Usage: ./update-session.sh <type> <message>"
    echo "Types: note, hypothesis, solution, close"
    ;;

esac UPDATESCRIPT

chmod +x "$SESSION_DIR/update-session.sh"

echo "✓ Created session update helper script" echo "" echo "Quick update commands:" echo " ./update-session.sh note "Found interesting pattern in logs"" echo " ./update-session.sh hypothesis "Missing environment variable"" echo " ./update-session.sh solution "Added missing REDIS_URL to .env"" echo " ./update-session.sh close "2 hours""

undefined

Closed: $(date) Total Time: $message Outcome: Issue resolved

EOF echo "✓ Closed debug session" # Remove current session tracking rm -f .claude/debugging/sessions/.current-session ;;

*)
    echo "Usage: ./update-session.sh <type> <message>"
    echo "Types: note, hypothesis, solution, close"
    ;;

esac UPDATESCRIPT

chmod +x "$SESSION_DIR/update-session.sh"

echo "✓ Created session update helper script" echo "" echo "快速更新命令：" echo " ./update-session.sh note "在日志中发现有趣的模式"" echo " ./update-session.sh hypothesis "缺少环境变量"" echo " ./update-session.sh solution "在.env中添加了缺失的REDIS_URL"" echo " ./update-session.sh close "2小时""

undefined

Phase 4: Knowledge Base Integration

阶段4：知识库集成

I'll prepare knowledge base entries for solved issues:

bash

echo ""
echo "=== Knowledge Base Integration ==="

cat > "$KB_DIR/README.md" << 'EOF'

我将为已解决的问题准备知识库条目：

bash

echo ""
echo "=== 知识库集成 ==="

cat > "$KB_DIR/README.md" << 'EOF'

Debugging Knowledge Base

调试知识库

This directory contains documented solutions to issues encountered during development.

此目录包含开发过程中遇到的问题的已记录解决方案。

Organization

组织方式

Each solved issue is documented in a separate file following this template:

每个已解决的问题都记录在单独的文件中，遵循以下模板：

Filename Format

文件名格式

<category>-<short-description>.md

Examples:

```
env-missing-redis-url.md
```
```
deps-version-conflict-react.md
```
```
config-cors-policy-error.md
```

<category>-<short-description>.md

示例：

```
env-missing-redis-url.md
```
```
deps-version-conflict-react.md
```
```
config-cors-policy-error.md
```

```
env
```
- 环境变量问题
```
deps
```
- 依赖问题
```
config
```
- 配置错误
```
api
```
- API集成问题
```
db
```
- 数据库问题
```
perf
```
- 性能问题
```
security
```
- 安全问题
```
build
```
- 构建/编译错误

Creating Knowledge Base Entries

创建知识库条目

When you solve an issue:

Copy from debug session to knowledge base:
bash
```
claude "/debug-session export-kb"
```
Or manually create entry following template
Tag with relevant keywords for searchability

当你解决问题后：

从调试会话复制到知识库：
bash
```
claude "/debug-session export-kb"
```
或手动按照模板创建条目
添加相关关键词以提高可搜索性

Searching Knowledge Base

搜索知识库

bash

undefined

bash

undefined

Search by keyword

按关键词搜索

grep -r "redis" .claude/debugging/knowledge-base/

Search by category

按分类搜索

ls .claude/debugging/knowledge-base/env-*.md

Find solutions by error message

按错误消息查找解决方案

grep -r "ECONNREFUSED" .claude/debugging/knowledge-base/

undefined

grep -r "ECONNREFUSED" .claude/debugging/knowledge-base/

undefined

Contributing

贡献

Document all solved issues to build team knowledge and speed up future debugging. EOF

echo "✓ Created knowledge base README"

undefined

记录所有已解决的问题，以构建团队知识并加快未来的调试速度。 EOF

echo "✓ 创建了知识库README"

undefined

Phase 5: Session Templates

阶段5：会话模板

I'll create templates for common debugging scenarios:

bash

echo ""
echo "=== Creating Debugging Templates ==="

mkdir -p "$SESSION_DIR/templates"

我将为常见调试场景创建模板：

bash

echo ""
echo "=== 创建调试模板 ==="

mkdir -p "$SESSION_DIR/templates"

Template 1: API Error

模板1：API错误

cat > "$SESSION_DIR/templates/api-error.md" << 'EOF'

API Error Debugging Template

API错误调试模板

Issue Description

问题描述

API Endpoint:
HTTP Method:
Status Code:
Error Message:

API端点：
HTTP方法：
状态码：
错误消息：

Request Details

请求详情

Headers:

undefined

Body:

undefined

请求头：

undefined

请求体：

undefined

Response

响应

undefined

undefined

Common Causes

常见原因

Investigation Checklist

调查清单

Template 2: Build Error

模板2：构建错误

cat > "$SESSION_DIR/templates/build-error.md" << 'EOF'

Build Error Debugging Template

构建错误调试模板

Issue Description

问题描述

Build Tool: webpack | vite | rollup | esbuild
Error Type:
Failed Stage:

构建工具： webpack | vite | rollup | esbuild
错误类型：
失败阶段：

Error Output

错误输出

undefined

undefined

Common Causes

常见原因

Investigation Checklist

调查清单

Template 3: Database Error

模板3：数据库错误

cat > "$SESSION_DIR/templates/database-error.md" << 'EOF'

Database Error Debugging Template

数据库错误调试模板

Issue Description

问题描述

Database: PostgreSQL | MySQL | MongoDB | Redis
Error Code:
Operation: SELECT | INSERT | UPDATE | DELETE

数据库： PostgreSQL | MySQL | MongoDB | Redis
错误代码：
操作： SELECT | INSERT | UPDATE | DELETE

Error Details

错误详情

undefined

undefined

Query

查询语句

sql

undefined

sql

undefined

Common Causes

常见原因

Investigation Checklist

调查清单

Verify database connection
Check database status
Review migration status
Test query in database client
Check database logs
Verify schema matches ORM models EOF

echo "✓ Created debugging templates" echo "" echo "Templates available in: $SESSION_DIR/templates/" ls "$SESSION_DIR/templates/"

undefined

验证数据库连接
检查数据库状态
审查迁移状态
在数据库客户端中测试查询
检查数据库日志
验证模式与ORM模型匹配 EOF

echo "✓ 创建了调试模板" echo "" echo "模板位于：$SESSION_DIR/templates/" ls "$SESSION_DIR/templates/"

undefined

Summary

总结

bash

echo ""
echo "=== ✓ Debug Session Initialized ==="
echo ""
echo "📂 Session Details:"
echo "  Name: $SESSION_NAME"
echo "  File: $SESSION_FILE"
echo "  Status: $(if [ "$RESUME_MODE" = "true" ]; then echo "Resumed"; else echo "New"; fi)"
echo ""
echo "📁 Created files:"
echo "  - $SESSION_FILE"
echo "  - $SESSION_DIR/update-session.sh"
echo "  - $KB_DIR/README.md"
echo "  - Templates in $SESSION_DIR/templates/"
echo ""
echo "✏️ Edit session document:"
echo "  code $SESSION_FILE"
echo "  vim $SESSION_FILE"
echo ""
echo "🔄 Quick updates:"
echo "  $SESSION_DIR/update-session.sh note \"Your note here\""
echo "  $SESSION_DIR/update-session.sh hypothesis \"Your theory\""
echo "  $SESSION_DIR/update-session.sh solution \"How you fixed it\""
echo "  $SESSION_DIR/update-session.sh close \"Total time: 2h\""
echo ""
echo "📚 Debugging workflow:"
echo ""
echo "1. Document the issue in session file"
echo "2. Form and test hypotheses systematically"
echo "3. Record all attempts and findings"
echo "4. Document the solution when found"
echo "5. Close session and export to knowledge base"
echo ""
echo "🔗 Integration Points:"
echo "  - /debug-root-cause - Analyze root cause"
echo "  - /debug-systematic - Systematic debugging"
echo "  - /test - Verify fixes"
echo "  - /commit - Commit solution"
echo ""
echo "💡 Best Practices:"
echo "  - Update session as you investigate"
echo "  - Record failed attempts (learning opportunities)"
echo "  - Document reasoning for hypotheses"
echo "  - Include timestamps for timeline tracking"
echo "  - Export solved issues to knowledge base"
echo ""
echo "Current session: $SESSION_NAME"
echo "View anytime: cat $SESSION_FILE"

bash

echo ""
echo "=== ✓ 调试会话已初始化 ==="
echo ""
echo "📂 会话详情："
echo "  名称：$SESSION_NAME"
echo "  文件：$SESSION_FILE"
echo "  状态：$(if [ "$RESUME_MODE" = "true" ]; then echo "已恢复"; else echo "新建"; fi)"
echo ""
echo "📁 创建的文件："
echo "  - $SESSION_FILE"
echo "  - $SESSION_DIR/update-session.sh"
echo "  - $KB_DIR/README.md"
echo "  - 模板位于 $SESSION_DIR/templates/"
echo ""
echo "✏️ 编辑会话文档："
echo "  code $SESSION_FILE"
echo "  vim $SESSION_FILE"
echo ""
echo "🔄 快速更新："
echo "  $SESSION_DIR/update-session.sh note \"你的笔记内容\""
echo "  $SESSION_DIR/update-session.sh hypothesis \"你的理论\""
echo "  $SESSION_DIR/update-session.sh solution \"你的修复方法\""
echo "  $SESSION_DIR/update-session.sh close \"总耗时：2小时\""
echo ""
echo "📚 调试工作流："
echo ""
echo "1. 在会话文件中记录问题"
echo "2. 系统地提出并测试假设"
echo "3. 记录所有尝试和发现"
echo "4. 找到解决方案后进行记录"
echo "5. 关闭会话并导出到知识库"
echo ""
echo "🔗 集成点："
echo "  - /debug-root-cause - 分析根本原因"
echo "  - /debug-systematic - 系统化调试"
echo "  - /test - 验证修复"
echo "  - /commit - 提交解决方案"
echo ""
echo "💡 最佳实践："
echo "  - 在调查过程中更新会话"
echo "  - 记录失败的尝试（学习机会）"
echo "  - 记录假设的推理过程"
echo "  - 包含时间戳以追踪时间线"
echo "  - 将已解决的问题导出到知识库"
echo ""
echo "当前会话：$SESSION_NAME"
echo "随时查看：cat $SESSION_FILE"

Session Management Commands

会话管理命令

I can help you manage debug sessions with these operations:

Session Operations:

```
/debug-session <issue-name>
```
- Start new session
```
/debug-session resume
```
- Resume current session
```
/debug-session list
```
- List all sessions
```
/debug-session export-kb
```
- Export to knowledge base
```
/debug-session close
```
- Close current session

Session Structure:

Issue description and context
Investigation timeline
Hypothesis tracking
Solution documentation
Lessons learned
Prevention strategies

Knowledge Base:

Searchable repository of solved issues
Organized by category
Tagged for easy discovery
Templates for common scenarios

Credits: Debug session documentation methodology based on session management patterns from claude-sessions, incident response practices from SRE, and knowledge management principles for effective debugging.

我可以通过以下操作帮助你管理调试会话：

会话操作：

```
/debug-session <issue-name>
```
- 启动新会话
```
/debug-session resume
```
- 恢复当前会话
```
/debug-session list
```
- 列出所有会话
```
/debug-session export-kb
```
- 导出到知识库
```
/debug-session close
```
- 关闭当前会话

会话结构：

问题描述和上下文
调查时间线
假设追踪
解决方案文档
经验教训
预防策略

知识库：

可搜索的已解决问题库
按分类组织
添加标签以便于查找
常见场景模板

致谢： 调试会话文档方法基于claude-sessions的会话管理模式、SRE的事件响应实践以及有效调试的知识管理原则。

debug-session

Original

Translation

Debug Session Documentation

调试会话文档

Token Optimization

Token优化

Optimization Strategies

优化策略

1. Session State Caching (Saves 600 tokens per invocation)

1. 会话状态缓存（每次调用节省600个Token）

2. Early Exit for Session Updates (Saves 85% tokens)

2. 会话更新提前退出（减少85%的Token消耗）

3. Template Generation on Demand (Saves 70%)

3. 按需生成模板（节省70%的Token消耗）

Default: Don't generate templates

Default: Don't generate templates

4. Session List Pagination (Saves 80% for large histories)

4. 会话列表分页（针对大量历史记录节省80%的Token消耗）

5. Minimal Session Reads (Saves 400 tokens)

5. 最小化会话读取（节省400个Token）

Read only header info (first 20 lines)

Read only header info (first 20 lines)

Extract key info without full read

Extract key info without full read

6. Knowledge Base Search Optimization (Saves 90%)

6. 知识库搜索优化（节省90%的Token消耗）

7. Incremental Documentation (Saves 60%)

7. 增量式文档（节省60%的Token消耗）

Efficient update function

Efficient update function

$(date +"%Y-%m-%d %H:%M") - $note_type

$(date +"%Y-%m-%d %H:%M") - $note_type

Usage: No read, just append

Usage: No read, just append

8. Bash-Based Session Management (Saves 70%)

8. 基于Bash的会话管理（节省70%的Token消耗）

All operations in bash

All operations in bash

Cache Invalidation

缓存失效

Real-World Token Usage

实际Token使用情况

Progressive Disclosure

渐进式披露

Implementation Notes

实现说明

Phase 1: Session Initialization

阶段1：会话初始化

Debug Session Documentation

Debug Session Documentation

Create debugging directory structure

Create debugging directory structure

Determine session name

Determine session name

Check if session already exists

Check if session already exists

Track current session

Track current session

Phase 2: Session Structure Creation

阶段2：会话结构创建

Debug Session: $SESSION_NAME

Debug Session: $SESSION_NAME

Issue Description

Issue Description

Problem Statement

Problem Statement

Observed Behavior

Observed Behavior

Error Messages

Error Messages

Reproduction Steps

Reproduction Steps

Investigation Timeline

Investigation Timeline

$(date +"%Y-%m-%d %H:%M:%S") - Session Started

$(date +"%Y-%m-%d %H:%M:%S") - Session Started

Hypotheses

Hypotheses

Hypothesis 1: [Primary Theory]