Merge pull request #9 from DojoCodingLabs/daniel/doj-2434-debugging-skill

feat: add debugging skill with error detection (DOJ-2434)

Author: bitfalt

data/concept-tree.json

@@ -358,8 +358,36 @@
           "triggers": ["cache", "redis", "CDN", "load balancer"]
         }
       }
+    },
+    "debugging": {
+      "name": "Debugging",
+      "icon": "🐛",
+      "belt_requirement": "white",
+      "concepts": {
+        "error-reading": {
+          "name": "Error Reading",
+          "xp_to_master": 15,
+          "prerequisites": [],
+          "description": "Understanding error messages and stack traces",
+          "triggers": ["error", "Error:", "Traceback", "ENOENT", "stack trace"]
+        },
+        "debugging-mindset": {
+          "name": "Debugging Mindset",
+          "xp_to_master": 20,
+          "prerequisites": ["error-reading"],
+          "description": "Systematic approach to finding and fixing bugs",
+          "triggers": ["debug", "breakpoint", "console.log", "print("]
+        },
+        "common-errors": {
+          "name": "Common Errors",
+          "xp_to_master": 25,
+          "prerequisites": ["error-reading", "debugging-mindset"],
+          "description": "Recognizing and fixing common programming errors",
+          "triggers": ["TypeError", "ReferenceError", "SyntaxError", "undefined", "null"]
+        }
+      }
     }
   },
-  "total_concepts": 42,
+  "total_concepts": 45,
   "mastery_quiz_threshold": 3
 }

data/quiz-bank.json

@@ -215,6 +215,51 @@
         "expected_understanding": "Docker packages an app with all its dependencies so it runs the same everywhere. Solves 'works on my machine' problems by creating consistent environments.",
         "hint": "Think about shipping a complete kitchen vs. just a recipe."
       }
+    ],
+    "error-reading": [
+      {
+        "belt": "white",
+        "question": "What does a stack trace show you?",
+        "options": ["The list of files in your project", "The sequence of function calls that led to the error", "All the variables currently in memory"],
+        "correct": 1,
+        "explanation": "A stack trace is like a breadcrumb trail — it shows every function that was called, in order, up until the crash. Reading it from bottom to top tells you where the error originated and how the code got there.",
+        "hint": "Think of it as a history of every step the program took before it fell over."
+      },
+      {
+        "belt": "white",
+        "question": "What is the first thing you should read in an error message?",
+        "options": ["The line number at the very bottom", "The error type and the first line of the message", "The full stack trace from top to bottom"],
+        "correct": 1,
+        "explanation": "The error type (like `TypeError` or `SyntaxError`) and the first descriptive line tell you WHAT went wrong. Once you know what, you can use the line number and stack trace to figure out WHERE. Start at the top, not the bottom.",
+        "hint": "Skimming a news article — you read the headline first, then the details."
+      }
+    ],
+    "debugging-mindset": [
+      {
+        "belt": "yellow",
+        "question": "What is the most effective first step when debugging?",
+        "options": ["Delete the code and rewrite it from scratch", "Reproduce the error reliably, then read the error message carefully", "Ask someone else to fix it"],
+        "correct": 1,
+        "explanation": "You can't fix what you can't consistently reproduce. Once you can make the bug happen on demand, read the error message carefully — it usually tells you exactly what went wrong and where. Only after understanding the error should you start changing code.",
+        "hint": "A doctor diagnoses before prescribing. What's the equivalent first step for a bug?"
+      }
+    ],
+    "common-errors": [
+      {
+        "belt": "orange",
+        "question": "What typically causes a ReferenceError in JavaScript?",
+        "options": ["Using the wrong data type in a calculation", "Trying to use a variable that hasn't been declared or is out of scope", "A typo in an HTML tag"],
+        "correct": 1,
+        "explanation": "A `ReferenceError` means JavaScript looked for a variable name and couldn't find it anywhere in scope. Common causes: misspelling the variable name, using it before declaring it, or accessing it outside the block where it was defined.",
+        "hint": "The error name says 'reference' — what does it mean when a reference points to nothing?"
+      },
+      {
+        "belt": "orange",
+        "format": "free_response",
+        "question": "What's the difference between a syntax error and a runtime error? Give an example of each.",
+        "expected_understanding": "A syntax error is caught before the code runs — it's a grammar mistake the interpreter can't parse (e.g., missing closing bracket). A runtime error happens while the code is running, when an operation fails on valid-looking code (e.g., calling a method on null).",
+        "hint": "Think about the difference between a grammatically incorrect sentence and a sentence that makes sense but describes something impossible."
+      }
     ]
   }
 }

scripts/track-command.sh

@@ -33,6 +33,44 @@ else
   check_jq() { command -v jq &>/dev/null; }
 fi
 
+record_profile_concept() {
+  local concept="$1"
+  local first_flag_var="$2"
+  local already_in_session
+  local already_in_lifetime
+
+  if [ -z "$concept" ] || [ ! -f "$PROFILE_FILE" ]; then
+    return
+  fi
+
+  already_in_session=$(jq --arg c "$concept" '.session_concepts | index($c)' "$PROFILE_FILE" 2>&1)
+  if [ $? -ne 0 ]; then
+    log_error "$SCRIPT_NAME" "jq failed checking session_concepts for $concept: $already_in_session"
+    already_in_session="0"
+  fi
+
+  already_in_lifetime=$(jq --arg c "$concept" '.concepts_seen | index($c)' "$PROFILE_FILE" 2>&1)
+  if [ $? -ne 0 ]; then
+    log_error "$SCRIPT_NAME" "jq failed checking concepts_seen for $concept: $already_in_lifetime"
+    already_in_lifetime="0"
+  fi
+
+  if [ "$already_in_lifetime" = "null" ]; then
+    if update_profile --arg c "$concept" '
+      .session_concepts += (if (.session_concepts | index($c)) == null then [$c] else [] end) |
+      .concepts_seen += (if (.concepts_seen | index($c)) == null then [$c] else [] end)
+    '; then
+      printf -v "$first_flag_var" '%s' "true"
+    else
+      log_error "$SCRIPT_NAME" "Failed updating profile for first-time concept: $concept"
+    fi
+  elif [ "$already_in_session" = "null" ]; then
+    if ! update_profile --arg c "$concept" '.session_concepts += [$c]'; then
+      log_error "$SCRIPT_NAME" "Failed updating session_concepts for concept: $concept"
+    fi
+  fi
+}
+
 INPUT=$(cat)
 
 ensure_profile_dir
@@ -104,40 +142,51 @@ then
   log_error "$SCRIPT_NAME" "Failed to write to commands log: $COMMANDS_LOG"
 fi
 
-if [ -z "$CONCEPT" ]; then
+SAFE_CMD=$(printf '%s' "$COMMAND" | head -c 80 | tr '"' "'" | tr '\\' '/')
+
+IS_TEST_RUNNER="false"
+case "$COMMAND" in
+  jest\ *|"jest"|\
+  pytest\ *|"pytest"|\
+  vitest\ *|"vitest"|\
+  bats\ *|"bats"|\
+  mocha\ *|"mocha"|\
+  "npm test"*|"npm run test"*|\
+  "yarn test"*|"yarn run test"*|\
+  "pnpm test"*|"pnpm run test"*|"pnpm vitest"*|\
+  "npx jest"*|"npx vitest"*|"pnpm exec jest"*|"pnpm exec vitest"*)
+    IS_TEST_RUNNER="true"
+    ;;
+esac
+
+ERROR_CONCEPT=""
+if [ "$IS_TEST_RUNNER" = "false" ]; then
+  TOOL_RESPONSE=$(printf '%s' "$INPUT" | jq -r '.tool_response // ""' 2>/dev/null || echo "")
+  STDOUT=$(printf '%s' "$INPUT" | jq -r '.tool_response.stdout // ""' 2>/dev/null || echo "")
+  STDERR=$(printf '%s' "$INPUT" | jq -r '.tool_response.stderr // ""' 2>/dev/null || echo "")
+  OUTPUT="${STDOUT}${STDERR}${TOOL_RESPONSE}"
+
+  case "$OUTPUT" in
+    *"Traceback (most recent call last):"*) ERROR_CONCEPT="error-reading" ;;
+    *"TypeError"*|*"ReferenceError"*|*"SyntaxError"*) ERROR_CONCEPT="common-errors" ;;
+    *"Error:"*|*"ERROR:"*|*"error:"*) ERROR_CONCEPT="error-reading" ;;
+    *"ENOENT"*|*"EACCES"*|*"EPERM"*) ERROR_CONCEPT="error-reading" ;;
+    *"command not found"*) ERROR_CONCEPT="error-reading" ;;
+    *"ModuleNotFoundError"*|*"ImportError"*) ERROR_CONCEPT="error-reading" ;;
+    *"fatal:"*) ERROR_CONCEPT="error-reading" ;;
+  esac
+fi
+
+if [ -z "$CONCEPT" ] && [ -z "$ERROR_CONCEPT" ]; then
   printf '{}\n'
   exit 0
 fi
 
 IS_FIRST_EVER="false"
-if [ -f "$PROFILE_FILE" ]; then
-  ALREADY_IN_SESSION=$(jq --arg c "$CONCEPT" '.session_concepts | index($c)' "$PROFILE_FILE" 2>&1)
-  if [ $? -ne 0 ]; then
-    log_error "$SCRIPT_NAME" "jq failed checking session_concepts for $CONCEPT: $ALREADY_IN_SESSION"
-    ALREADY_IN_SESSION="0"
-  fi
-
-  ALREADY_IN_LIFETIME=$(jq --arg c "$CONCEPT" '.concepts_seen | index($c)' "$PROFILE_FILE" 2>&1)
-  if [ $? -ne 0 ]; then
-    log_error "$SCRIPT_NAME" "jq failed checking concepts_seen for $CONCEPT: $ALREADY_IN_LIFETIME"
-    ALREADY_IN_LIFETIME="0"
-  fi
+record_profile_concept "$CONCEPT" IS_FIRST_EVER
 
-  if [ "$ALREADY_IN_LIFETIME" = "null" ]; then
-    IS_FIRST_EVER="true"
-    if ! update_profile --arg c "$CONCEPT" '
-      .session_concepts += (if (.session_concepts | index($c)) == null then [$c] else [] end) |
-      .concepts_seen += (if (.concepts_seen | index($c)) == null then [$c] else [] end)
-    '; then
-      log_error "$SCRIPT_NAME" "Failed updating profile for first-time concept: $CONCEPT"
-      IS_FIRST_EVER="false"
-    fi
-  elif [ "$ALREADY_IN_SESSION" = "null" ]; then
-    if ! update_profile --arg c "$CONCEPT" '.session_concepts += [$c]'; then
-      log_error "$SCRIPT_NAME" "Failed updating session_concepts for concept: $CONCEPT"
-    fi
-  fi
-fi
+ERROR_IS_FIRST_EVER="false"
+record_profile_concept "$ERROR_CONCEPT" ERROR_IS_FIRST_EVER
 
 NOW=$(date +%s)
 if [ -f "$SESSION_STATE" ]; then
@@ -154,7 +203,7 @@ if [ "$TRIGGER_COUNT" -ge "$SESSION_CAP" ]; then
 fi
 
 ELAPSED=$((NOW - LAST_TRIGGER))
-if [ "$ELAPSED" -lt "$RATE_LIMIT_INTERVAL" ] && [ "$IS_FIRST_EVER" != "true" ]; then
+if [ "$ELAPSED" -lt "$RATE_LIMIT_INTERVAL" ] && [ "$IS_FIRST_EVER" != "true" ] && [ "$ERROR_IS_FIRST_EVER" != "true" ]; then
   printf '{}\n'
   exit 0
 fi
@@ -185,9 +234,11 @@ if [ $? -ne 0 ]; then
   BELT="white"
 fi
 
-SAFE_CMD=$(printf '%s' "$COMMAND" | head -c 80 | tr '"' "'" | tr '\\' '/')
-
-if [ "$IS_FIRST_EVER" = "true" ]; then
+if [ "$ERROR_IS_FIRST_EVER" = "true" ] && [ -n "$ERROR_CONCEPT" ]; then
+  CONTEXT="🥋 CodeSensei micro-lesson trigger: The user just encountered '$ERROR_CONCEPT' for the FIRST TIME while reading command output ($SAFE_CMD). Their belt level is '$BELT'. Provide a brief 2-sentence explanation of how to read this kind of error and why it matters. Adapt language to their belt level. Keep it supportive and practical."
+elif [ -n "$ERROR_CONCEPT" ]; then
+  CONTEXT="🥋 CodeSensei inline insight: An error appeared in the command output ($SAFE_CMD). The user's belt level is '$BELT'. This is a great moment to teach '$ERROR_CONCEPT' -- briefly explain how to read and interpret this type of error in 1-2 sentences, adapted to their belt level. Keep it supportive and practical."
+elif [ "$IS_FIRST_EVER" = "true" ]; then
   CONTEXT="🥋 CodeSensei micro-lesson trigger: The user just encountered '$CONCEPT' for the FIRST TIME (command: $SAFE_CMD). Their belt level is '$BELT'. Provide a brief 2-sentence explanation of what $CONCEPT means and why it matters. Adapt language to their belt level. Keep it concise and non-intrusive."
 else
   CONTEXT="🥋 CodeSensei inline insight: Claude just ran a '$CONCEPT' command ($SAFE_CMD). The user's belt level is '$BELT'. Provide a brief 1-sentence explanation of what this command does, adapted to their belt level. Keep it natural and non-intrusive."