{"id":"31d5e23d-e127-4dde-afb8-41552f264517","shortId":"wseXsX","kind":"skill","title":"smalltalk-debugger","tagline":"Systematic debugging guide for Pharo Smalltalk development. Provides expertise in error diagnosis (MessageNotUnderstood, KeyNotFound, SubscriptOutOfBounds, AssertionFailure), incremental code execution with eval tool, intermediate value inspection, error handling patterns (`on:do","description":"# Smalltalk Debugger\n\nSystematic debugging techniques for Pharo Smalltalk development using AI editors.\n\n## Core Debugging Workflow\n\nWhen tests fail or errors occur, follow this systematic approach:\n\n### 1. Identify Error Location\n\nFrom error message, confirm:\n- **Error type** (MessageNotUnderstood, KeyNotFound, etc.)\n- **Stack trace** - where error occurred\n- **Expected vs Actual** - what went wrong\n\n### 2. Verify with Partial Execution\n\nUse `/st-eval` tool to execute relevant code incrementally.\n\n**Basic error capture pattern:**\n```smalltalk\n| result |\nresult := Array new: 2.\n[ | ret |\n  ret := objA doSomething.\n  result at: 1 put: ret printString.\n] on: Error do: [:ex | result at: 2 put: ex description].\n^ result\n```\n\n**Interpreting results:**\n- `result at: 1` - Normal result (success case)\n- `result at: 2` - Error description (failure case)\n\n### 3. Check Intermediate Values\n\nInspect state at each step:\n\n```smalltalk\n| step1 step2 |\nstep1 := self getData.\nstep2 := step1 select: [:each | each isValid].\n{\n    'step1 count' -> step1 size.\n    'step2 count' -> step2 size.\n    'step2 result' -> step2 printString\n} asDictionary printString\n```\n\n### 4. Fix and Re-test\n\n1. **Fix in Tonel file** (never in Pharo)\n2. **Re-import** with `import_package`\n3. **Re-test** with `run_class_test`\n\n## When Operations Stop Responding\n\nWhen an MCP call times out, follow this escalation sequence:\n\n### Step 1: Health Check\n\nRun a quick eval to verify Pharo is still responsive:\n\n```\nmcp__smalltalk-interop__eval: 'Smalltalk version'\n```\n\nIf this succeeds, Pharo is alive — a **debugger window may have opened** (see below).\n\n### Step 2: Try `read_screen`\n\nIf eval also times out, check the UI state:\n\n```\nmcp__smalltalk-interop__read_screen: target_type='world'\n```\n\nIf `read_screen` responds, inspect the output for debugger windows (see \"Detecting Hidden Debuggers\" below).\n\n### Step 3: Process Hang — Ask User to Restart\n\nIf `read_screen` itself times out, **Pharo has hung at the process level**. MCP tools cannot recover from this state.\n\nAsk the user to:\n1. Kill the Pharo process (or Docker container) and restart it\n2. After restart, re-import all packages before continuing\n3. Re-run tests to confirm state before making further claims\n\n### Detecting Hidden Debuggers\n\nUse the `read_screen` tool to capture the Pharo UI state:\n\n```\nmcp__smalltalk-interop__read_screen: target_type='world'\n```\n\nThis captures all morphs including debugger windows. Look for:\n- Window titles containing \"Debugger\", \"Error\", or \"Exception\"\n- UI hierarchy showing debugger-related components\n- Error messages or stack traces in window content\n\n### Resolution Steps\n\n1. **Notify the user**: Inform them that a debugger window appears to be open in Pharo\n2. **Request manual intervention**: Ask the user to:\n   - Check their Pharo image for open debugger windows\n   - Close any debugger windows\n   - Review the error shown in the debugger to understand the root cause\n3. **Address root cause**: Once the debugger is closed, investigate and fix the underlying error using standard debugging techniques\n4. **Retry operation**: Re-run the failed MCP operation\n\n**Note**: The Pharo debugger cannot be controlled remotely through MCP tools. User intervention in the Pharo image is required.\n\nFor complete UI debugging guidance, see [UI Debugging Reference](references/ui-debugging.md).\n\n## Common Error Types Quick Reference\n\n### MessageNotUnderstood\n**Cause**: Method doesn't exist or typo in method name\n**Debug**: Check spelling, search implementors\n```\nmcp__smalltalk-interop__search_implementors: 'methodName'\n```\n\n### KeyNotFound\n**Cause**: Accessing non-existent Dictionary key\n**Debug**: List keys, use at:ifAbsent:\n```smalltalk\ndict keys printString\ndict at: #key ifAbsent: ['default']\n```\n\n### SubscriptOutOfBounds\n**Cause**: Collection index out of range\n**Debug**: Check size, use at:ifAbsent:\n```smalltalk\ncollection size printString\ncollection at: index ifAbsent: [nil]\n```\n\n### ZeroDivide\n**Cause**: Division by zero\n**Debug**: Check denominator before dividing\n```smalltalk\ncount = 0 ifTrue: [0] ifFalse: [sum / count]\n```\n\n### AssertionFailure (in tests)\n**Cause**: Test expectation doesn't match actual\n**Debug**: Execute test code with `/st-eval`, check if package imported\n\nFor complete error patterns and solutions, see [Error Patterns Reference](references/error-patterns.md).\n\n## Object Inspection Quick Guide\n\n### Basic Inspection\n```smalltalk\n\" Object class \"\nobj class printString\n\n\" Instance variables \"\nobj instVarNames\n\n\" Check method exists \"\nobj respondsTo: #methodName\n```\n\n### Collection Inspection\n```smalltalk\n\" Size and elements \"\ncollection size\ncollection printString\n\n\" Safe first/last \"\ncollection ifEmpty: [nil] ifNotEmpty: [:col | col first]\n```\n\n### Dictionary Inspection\n```smalltalk\n\" Keys and values \"\ndict keys\ndict values\n\n\" Safe access \"\ndict at: #key ifAbsent: ['default']\n```\n\nFor comprehensive inspection techniques, see [Inspection Techniques Reference](references/inspection-techniques.md).\n\n## Debugging Best Practices\n\n### 1. Divide into Small Steps\nBreak problems into incremental steps and verify each with `/st-eval`:\n\n```smalltalk\nobj := MyClass new.\nobj printString  \" Step 1: verify creation \"\n\nresult := obj doSomething.\nresult printString  \" Step 2: verify method call \"\n```\n\n### 2. Check Intermediate Values\nNever assume - verify at each step:\n\n```smalltalk\nintermediate := obj step1.\n\" Check here before proceeding \"\nresult := intermediate step2.\n```\n\n### 4. Always Use printString\nWhen returning objects via JSON/MCP:\n\n```smalltalk\n✅ obj printString\n✅ collection printString\n\n❌ obj  \" Don't return raw objects \"\n```\n\n### 5. Use Error Handling\nAlways capture errors with `on:do:`:\n\n```smalltalk\n[\n    risky operation\n] on: Error do: [:ex |\n    ex description\n]\n```\n\n### 6. Fix in Tonel, Not Pharo\n- ✅ Edit `.st` file → Import → Test\n- ❌ Edit in Pharo → Export → Commit\n\n## Debugging Tools\n\n### Primary Tool: `/st-eval`\n\n```\nmcp__smalltalk-interop__eval: 'Smalltalk version'\nmcp__smalltalk-interop__eval: 'MyClass new doSomething printString'\n```\n\n### Code Inspection Tools\n\n```\nmcp__smalltalk-interop__get_class_source: 'ClassName'\nmcp__smalltalk-interop__get_method_source: class: 'ClassName' method: 'methodName'\nmcp__smalltalk-interop__search_implementors: 'methodName'\nmcp__smalltalk-interop__search_references: 'methodName'\n```\n\n## Practical Example\n\n### Test Failure: AssertionFailure\n\n**Error**: `Expected 'John Doe' but got 'John nil'`\n\n1. Execute test code with `/st-eval` to reproduce\n2. Inspect intermediate values (was lastName set?)\n3. Check setter implementation: was `^ self` missing?\n4. Fix in Tonel file, re-import, re-test\n\nFor complete debugging scenarios, see [Debug Scenarios Examples](examples/debug-scenarios.md).\n\n## Troubleshooting Checklist\n\nWhen debugging, systematically check:\n\n- [ ] Read complete error message\n- [ ] Use `/st-eval` to test incrementally\n- [ ] Inspect all intermediate values\n- [ ] Check method implementation\n- [ ] Verify package was imported\n- [ ] Edit Tonel file (not Pharo)\n- [ ] Re-import after fixing\n- [ ] Re-run tests\n\n## Complete Documentation\n\nThis skill provides focused debugging guidance. For comprehensive information:\n\n- **[Error Patterns Reference](references/error-patterns.md)** - All error types with solutions\n- **[Inspection Techniques](references/inspection-techniques.md)** - Complete object inspection guide\n- **[Debug Scenarios](examples/debug-scenarios.md)** - Real-world debugging examples\n\n## Summary\n\n**Core debugging cycle:**\n\n```\nError occurs → Identify error type → /st-eval incrementally\n    → Inspect intermediate values → Identify root cause\n    → Fix in Tonel → Re-import → Re-test → Success or repeat\n```\n\n**Remember**: Systematic approach, incremental testing, fix in Tonel, always re-import.","tags":["smalltalk","debugger","dev","plugin","mumez","agent-skills","agents","claude-code","marketplace","mcp","pharo-smalltalk","skills"],"capabilities":["skill","source-mumez","skill-smalltalk-debugger","topic-agent-skills","topic-agents","topic-claude-code","topic-marketplace","topic-mcp","topic-pharo-smalltalk","topic-plugin","topic-skills","topic-smalltalk"],"categories":["smalltalk-dev-plugin"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/mumez/smalltalk-dev-plugin/smalltalk-debugger","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add mumez/smalltalk-dev-plugin","source_repo":"https://github.com/mumez/smalltalk-dev-plugin","install_from":"skills.sh"}},"qualityScore":"0.456","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 13 github stars · SKILL.md body (7,826 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:06:59.765Z","embedding":null,"createdAt":"2026-04-23T13:04:03.280Z","updatedAt":"2026-05-18T19:06:59.765Z","lastSeenAt":"2026-05-18T19:06:59.765Z","tsv":"'/st-eval':89,627,727,828,899,947,1020 '0':606,608 '1':59,112,131,184,222,326,415,713,735,894 '2':83,105,122,138,192,257,337,431,744,748,902 '3':143,199,295,347,463,909 '4':178,482,769,916 '5':789 '6':808 'access':551,695 'actual':79,621 'address':464 'ai':44 'aliv':247 'also':263 'alway':770,793,1048 'appear':425 'approach':58,1042 'array':103 'asdictionari':176 'ask':298,322,435 'assertionfailur':19,612,885 'assum':753 'basic':96,647 'best':711 'break':718 'call':214,747 'cannot':317,496 'captur':98,368,383,794 'case':135,142 'caus':462,466,527,550,573,595,615,1027 'check':144,224,266,439,538,580,600,628,659,749,762,910,941,955 'checklist':937 'claim':358 'class':205,651,653,853,863 'classnam':855,864 'close':447,471 'code':21,94,625,845,897 'col':681,682 'collect':574,586,589,665,671,673,677,781 'commit':823 'common':521 'complet':512,633,928,943,976,999 'compon':404 'comprehens':702,985 'confirm':66,353 'contain':333,393 'content':412 'continu':346 'control':498 'core':46,1012 'count':165,169,605,611 'creation':737 'cycl':1014 'debug':5,37,47,480,514,518,537,557,579,599,622,710,824,929,932,939,982,1003,1009,1013 'debugg':3,35,249,287,292,361,387,394,402,423,445,449,457,469,495 'debugger-rel':401 'default':571,700 'denomin':601 'descript':125,140,807 'detect':290,359 'develop':10,42 'diagnosi':15 'dict':564,567,690,692,696 'dictionari':555,684 'divid':603,714 'divis':596 'docker':332 'document':977 'doe':889 'doesn':529,618 'dosometh':109,740,843 'edit':814,819,962 'editor':45 'element':670 'error':14,29,53,61,64,67,75,97,117,139,395,405,453,477,522,634,639,791,795,803,886,944,987,992,1015,1018 'escal':219 'etc':71 'eval':24,228,239,262,833,840 'ex':119,124,805,806 'exampl':882,934,1010 'examples/debug-scenarios.md':935,1005 'except':397 'execut':22,87,92,623,895 'exist':531,554,661 'expect':77,617,887 'expertis':12 'export':822 'fail':51,489 'failur':141,884 'file':188,816,920,964 'first':683 'first/last':676 'fix':179,185,474,809,917,971,1028,1045 'focus':981 'follow':55,217 'get':852,860 'getdata':157 'got':891 'guid':6,646,1002 'guidanc':515,983 'handl':30,792 'hang':297 'health':223 'hidden':291,360 'hierarchi':399 'hung':310 'identifi':60,1017,1025 'ifabs':562,570,584,592,699 'ifempti':678 'iffals':609 'ifnotempti':680 'iftru':607 'imag':442,508 'implement':912,957 'implementor':541,547,872 'import':195,197,342,631,817,923,961,969,1033,1051 'includ':386 'increment':20,95,721,950,1021,1043 'index':575,591 'inform':419,986 'inspect':28,147,283,644,648,666,685,703,706,846,903,951,996,1001,1022 'instanc':655 'instvarnam':658 'intermedi':26,145,750,759,767,904,953,1023 'interop':238,273,376,545,832,839,851,859,870,877 'interpret':127 'intervent':434,504 'investig':472 'isvalid':163 'john':888,892 'json/mcp':777 'key':556,559,565,569,687,691,698 'keynotfound':17,70,549 'kill':327 'lastnam':907 'level':314 'list':558 'locat':62 'look':389 'make':356 'manual':433 'match':620 'may':251 'mcp':213,235,270,315,373,490,501,542,829,836,848,856,867,874 'messag':65,406,945 'messagenotunderstood':16,69,526 'method':528,535,660,746,861,865,956 'methodnam':548,664,866,873,880 'miss':915 'morph':385 'myclass':730,841 'name':536 'never':189,752 'new':104,731,842 'nil':593,679,893 'non':553 'non-exist':552 'normal':132 'note':492 'notifi':416 'obj':652,657,662,729,732,739,760,779,783 'obja':108 'object':643,650,775,788,1000 'occur':54,76,1016 'open':253,428,444 'oper':208,484,491,801 'output':285 'packag':198,344,630,959 'partial':86 'pattern':31,99,635,640,988 'pharo':8,40,191,231,245,308,329,370,430,441,494,507,813,821,966 'practic':712,881 'primari':826 'printstr':115,175,177,566,588,654,674,733,742,772,780,782,844 'problem':719 'proceed':765 'process':296,313,330 'provid':11,980 'put':113,123 'quick':227,524,645 'rang':578 'raw':787 're':182,194,201,341,349,486,922,925,968,973,1032,1035,1050 're-import':193,340,921,967,1031,1049 're-run':348,485,972 're-test':181,200,924,1034 'read':259,274,280,303,364,377,942 'real':1007 'real-world':1006 'recov':318 'refer':519,525,641,708,879,989 'references/error-patterns.md':642,990 'references/inspection-techniques.md':709,998 'references/ui-debugging.md':520 'relat':403 'relev':93 'rememb':1040 'remot':499 'repeat':1039 'reproduc':901 'request':432 'requir':510 'resolut':413 'respond':210,282 'respondsto':663 'respons':234 'restart':301,335,339 'result':101,102,110,120,126,128,129,133,136,173,738,741,766 'ret':106,107,114 'retri':483 'return':774,786 'review':451 'riski':800 'root':461,465,1026 'run':204,225,350,487,974 'safe':675,694 'scenario':930,933,1004 'screen':260,275,281,304,365,378 'search':540,546,871,878 'see':254,289,516,638,705,931 'select':160 'self':156,914 'sequenc':220 'set':908 'setter':911 'show':400 'shown':454 'size':167,171,581,587,668,672 'skill':979 'skill-smalltalk-debugger' 'small':716 'smalltalk':2,9,34,41,100,152,237,240,272,375,544,563,585,604,649,667,686,728,758,778,799,831,834,838,850,858,869,876 'smalltalk-debugg':1 'smalltalk-interop':236,271,374,543,830,837,849,857,868,875 'solut':637,995 'sourc':854,862 'source-mumez' 'spell':539 'st':815 'stack':72,408 'standard':479 'state':148,269,321,354,372 'step':151,221,256,294,414,717,722,734,743,757 'step1':153,155,159,164,166,761 'step2':154,158,168,170,172,174,768 'still':233 'stop':209 'subscriptoutofbound':18,572 'succeed':244 'success':134,1037 'sum':610 'summari':1011 'systemat':4,36,57,940,1041 'target':276,379 'techniqu':38,481,704,707,997 'test':50,183,202,206,351,614,616,624,818,883,896,926,949,975,1036,1044 'time':215,264,306 'titl':392 'tonel':187,811,919,963,1030,1047 'tool':25,90,316,366,502,825,827,847 'topic-agent-skills' 'topic-agents' 'topic-claude-code' 'topic-marketplace' 'topic-mcp' 'topic-pharo-smalltalk' 'topic-plugin' 'topic-skills' 'topic-smalltalk' 'trace':73,409 'tri':258 'troubleshoot':936 'type':68,277,380,523,993,1019 'typo':533 'ui':268,371,398,513,517 'under':476 'understand':459 'use':43,88,362,478,560,582,771,790,946 'user':299,324,418,437,503 'valu':27,146,689,693,751,905,954,1024 'variabl':656 'verifi':84,230,724,736,745,754,958 'version':241,835 'via':776 'vs':78 'went':81 'window':250,288,388,391,411,424,446,450 'workflow':48 'world':278,381,1008 'wrong':82 'zero':598 'zerodivid':594","prices":[{"id":"3bc9c7c8-1d33-4c63-a69a-1f85e02027f5","listingId":"31d5e23d-e127-4dde-afb8-41552f264517","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"mumez","category":"smalltalk-dev-plugin","install_from":"skills.sh"},"createdAt":"2026-04-23T13:04:03.280Z"}],"sources":[{"listingId":"31d5e23d-e127-4dde-afb8-41552f264517","source":"github","sourceId":"mumez/smalltalk-dev-plugin/smalltalk-debugger","sourceUrl":"https://github.com/mumez/smalltalk-dev-plugin/tree/develop/skills/smalltalk-debugger","isPrimary":false,"firstSeenAt":"2026-04-23T13:04:03.280Z","lastSeenAt":"2026-05-18T19:06:59.765Z"}],"details":{"listingId":"31d5e23d-e127-4dde-afb8-41552f264517","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"mumez","slug":"smalltalk-debugger","github":{"repo":"mumez/smalltalk-dev-plugin","stars":13,"topics":["agent-skills","agents","claude-code","marketplace","mcp","pharo-smalltalk","plugin","skills","smalltalk"],"license":"mit","html_url":"https://github.com/mumez/smalltalk-dev-plugin","pushed_at":"2026-05-12T05:53:28Z","description":"Claude Code plugin for AI-driven Smalltalk (Pharo) development","skill_md_sha":"440087908a4971590a2e86575878f9792a8f3f54","skill_md_path":"skills/smalltalk-debugger/SKILL.md","default_branch":"develop","skill_tree_url":"https://github.com/mumez/smalltalk-dev-plugin/tree/develop/skills/smalltalk-debugger"},"layout":"multi","source":"github","category":"smalltalk-dev-plugin","frontmatter":{"name":"smalltalk-debugger","description":"Systematic debugging guide for Pharo Smalltalk development. Provides expertise in error diagnosis (MessageNotUnderstood, KeyNotFound, SubscriptOutOfBounds, AssertionFailure), incremental code execution with eval tool, intermediate value inspection, error handling patterns (`on:do:` blocks), stack trace analysis, UI debugger window detection (read_screen for hung operations), and debug-fix-reimport workflow. Use when encountering Pharo test failures, Smalltalk exceptions, unexpected behavior, timeout or non-responsive operations, need to verify intermediate values, execute code incrementally for diagnosis, or troubleshoot Tonel import errors."},"skills_sh_url":"https://skills.sh/mumez/smalltalk-dev-plugin/smalltalk-debugger"},"updatedAt":"2026-05-18T19:06:59.765Z"}}