René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"agent: trace all registry consumers when adding a new tool","articleBody":"## What happened\n\nWhen adding `ZensicalTool` to the project, the tool was registered in `ALL_TOOLS` and `use_tool()`, but `ZensicalToolSpec` was not added to `ALL_TOOL_SPECS`. Additionally, multiple test files contained hardcoded expected values (usage table rows, CLI output strings, dependency assertions) that referenced the old documentation framework instead of the new one. These omissions caused 8 test failures in CI that were not caught before pushing.\n\n## Root cause\n\nAdding a new tool requires coordinated updates across multiple registries (`ALL_TOOLS`, `ALL_TOOL_SPECS`, `use_tool()`) and multiple test files with hardcoded expected values that enumerate all tools or reference toolset outputs. The spec registry and test expectations were overlooked because the focus was on the core implementation and dispatch registration.\n\n## Generalised principle\n\nWhen adding a new entry to any registry or canonical list, always trace **all consumers** of that registry — including parallel registries that must stay in sync and test files with hardcoded expected values that enumerate registry contents. A useful heuristic: search the codebase for the name of the most recently added entry (the one just before yours) to find every place that lists tools, and update each one. Grepping for the sibling entry is more reliable than trying to remember all the registration points from memory.\n\n## Resolution\n\nAdded `ZensicalToolSpec` to `ALL_TOOL_SPECS` in `src/usethis/_tool/impl/spec/all_.py`. Updated hardcoded expected values in `tests/usethis/_core/test_list.py` (3 usage table tests), `tests/usethis/_ui/interface/test_doc.py` (dependency assertion), and `tests/usethis/_ui/interface/test_init.py` (3 CLI output strings). See commit 2d8bca6.\n\n## Follow-up\n\nNone — the `test_in_sync_with_all_tools` test already enforces that `ALL_TOOL_SPECS` and `ALL_TOOLS` stay in sync, which is what surfaced part of this issue. The remaining test failures (hardcoded output strings) are inherently manual to maintain.","author":{"url":"https://github.com/nathanjmcdougall","@type":"Person","name":"nathanjmcdougall"},"datePublished":"2026-04-07T07:25:28.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/1850/usethis-python/issues/1850"}