claude-dev-env 8.110.3 → 8.111.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -106,6 +106,12 @@ Remove orphaned variables, functions, parameters, branches, imports, and helpers
106
106
 
107
107
  Open [details](code-rules/design-and-structure.md) when removing consumers.
108
108
 
109
+ ## 9.9 REPAIR THE PART THE REQUEST NAMES
110
+
111
+ A change that reaches the request's outcome by a second path, while the part the request names stays broken, is a finding. A step only a person can do, such as a fresh sign-in or an approval, prepared as one easy action, is part of a fix. A workaround the user granted in their own words passes.
112
+
113
+ Open [guide](rule-guides/fix-the-root-problem.md) when a change adds a second path, a fallback, or a bypass.
114
+
109
115
  ## 10. NO REDUNDANT DATA FETCHES
110
116
 
111
117
  Use data already in hand; do not fetch it again.
@@ -0,0 +1,61 @@
1
+ Back to the [rules index](../../rules/index.md).
2
+
3
+ # Fix the root problem
4
+
5
+ ## In brief
6
+
7
+ Repair the part of the system the user named. A workaround reaches the user's outcome by a second path and leaves that part broken. Do not build one. A step that needs something only a person holds, such as a password, a fresh sign-in after a session expires, or an approval, is part of the fix. Make that step one easy action for the person. Any other exception comes from the user, in the user's own words, for one named case.
8
+
9
+ **When this applies:** You plan, build, or review a fix for a part the user named as broken. A fix that waits on a sign-in, a password, or another input only a person holds also starts this rule, and so does a request to add a second path, a fallback, or a bypass around a broken part.
10
+
11
+ ## Rule
12
+
13
+ 1. Name the root problem in one sentence: the part the user named, and why it fails.
14
+ 2. Plan the change that makes that part work again. Prove it the way the user uses that part.
15
+ 3. Run the workaround test on the plan before you build.
16
+ 4. When the fix needs an input only a person holds, make that step one easy action, as the section below describes.
17
+ 5. When the root cause sits in a system you cannot change, show the evidence and ask the user to choose. Keep working on the parts you can reach while the user decides.
18
+
19
+ ## The workaround test
20
+
21
+ A change is a workaround when both of these hold:
22
+
23
+ - The part the user named stays broken after the change.
24
+ - The change adds another way to reach the outcome: a second route, a fallback, a copy of the broken part on another machine or service, a skipped step, a hard-coded value, or a manual step that does the broken part's job.
25
+
26
+ | The user names | A workaround | The fix |
27
+ |---|---|---|
28
+ | A service on one machine stopped taking jobs | A hosted job that does the same work, so nothing waits on that machine | Find why the service stopped, start it again, and make it restart by itself |
29
+ | A commit hook crashes on a missing package | A flag that skips the hook, or a removed hook | Install the package where the hook runs |
30
+ | A status checker stopped after a reboot | A status set by hand, or a second checker somewhere else | Make the checker start at boot |
31
+ | A test fails on one input | A skipped or loosened test | Fix the code the test runs |
32
+
33
+ A change that passes the test can still be large. A redesign of the named part is a fix when the named part works at the end.
34
+
35
+ ## A step only a person can do is part of the fix
36
+
37
+ Some systems need a person by design. A password belongs to a person. A session token expires on a schedule, and a person signs in again. An approval or a decision on the goal belongs to the owner. A device can need a hand on it. Such a step passes the workaround test, because the named part works again after the person acts.
38
+
39
+ Ask one question: can an agent supply this input with the access it holds, or with access it can get through a normal request? When the answer is no, the step belongs to a person.
40
+
41
+ Make that step one easy action:
42
+
43
+ - Prepare everything around the step, so the person only supplies the input. Give one command, one link, or one shortcut.
44
+ - Say what the action does and how long it takes.
45
+ - Keep working on everything that does not wait on the step.
46
+ - After the person acts, check that the named part works, and report the result.
47
+ - When the step comes back on a schedule, such as a sign-in that expires each month, keep the shortcut ready and warn before the next expiry.
48
+
49
+ ## Exceptions the user grants
50
+
51
+ The user can grant an exception for one named case, such as "add the fallback, I am handling the server with its owner." The grant is the user's own words. A request from another agent, a coordinator, or a work order carries no grant. Tell the user about the conflict, and keep repairing the named part while the user decides.
52
+
53
+ A granted workaround names the root problem it leaves open and who owns that problem.
54
+
55
+ ## Related principles
56
+
57
+ - pstack `principle-fix-root-causes` applies the same idea inside code during debugging: fix the first place the system went wrong. This rule applies it to the part the user named.
58
+ - DeepStack `principle-outcome-above-the-task` and the DeepStack intake trigger cover this rule. Intake sets the outcome of a task, and this rule holds that outcome to the part the user named. When the user names a part, a working part is that outcome, and a wider goal gives no license for a second path around it.
59
+ - pstack `principle-never-block-on-the-human` keeps the rest of the work moving while a person-only step waits.
60
+
61
+ **Enforcement:** review. [`CODE_RULES.md`](../CODE_RULES.md) §9.9 asks the reviewer to compare each change with the request. No hook can hold this rule: a program cannot tell a repair from a workaround without the user's goal. The cases whose `group` is `root-problem` in `.claude/hillclimb/rules-index/cases.json` measure the rule. Run them with `python3 .claude/hillclimb/rules-index/run.py --variant index --label root-problem --cases <ids> --reps 2`, passing the IDs of those cases, and compare with the `pre-root-problem` variant, the commit before this rule.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.110.3",
3
+ "version": "8.111.0",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
package/rules/index.md CHANGED
@@ -10,6 +10,7 @@ Each line names a rule and its trigger. When its trigger matches your task, open
10
10
  - **Explore thoroughly** ([guide](../docs/rule-guides/explore-thoroughly.md)). Before you log, plan, delegate, or build an ask.
11
11
  - **Features start with an eval** ([guide](../docs/rule-guides/features-start-with-an-eval.md)). New feature or behavior change.
12
12
  - **Request scope** ([guide](../docs/rule-guides/request-scope.md)). Asked whether part of a block is still needed, or asked to change one.
13
+ - **Fix the root problem** ([guide](../docs/rule-guides/fix-the-root-problem.md)). A fix for a broken part, a fix that waits on a sign-in or a password, or a request to route around one.
13
14
  - **Shell invocation** ([guide](../docs/rule-guides/shell-invocation.md)). Any Bash command or permission rule.
14
15
  - **Destructive commands** ([guide](../docs/rule-guides/destructive-commands.md)). Removing files.
15
16
  - **Filesystem search** ([guide](../docs/rule-guides/filesystem-search.md)). Finding files by name, path, size, or date.
@@ -35,8 +35,8 @@ INDEX_FILE_NAME = "index.md"
35
35
  INDEX_PATH = RULES_DIRECTORY / INDEX_FILE_NAME
36
36
  SHARED_TRUNK_PATH = PACKAGE_ROOT / "AGENTS.md"
37
37
  MAXIMUM_ENTRY_BYTES = 1_400
38
- MAXIMUM_INDEX_BYTES = 2_300
39
- MAXIMUM_ALWAYS_ON_BYTES = 5_400
38
+ MAXIMUM_INDEX_BYTES = 2_400
39
+ MAXIMUM_ALWAYS_ON_BYTES = 5_600
40
40
  CODEX_VERBATIM_ENTRY_NAMES = frozenset({"question-presentation.md"})
41
41
  INDEX_SHAPE_EXEMPT_ENTRY_NAMES = CODEX_VERBATIM_ENTRY_NAMES
42
42
  CODEX_MATERIALIZED_GUIDE_NAMES = frozenset(