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.
package/docs/CODE_RULES.md
CHANGED
|
@@ -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
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 =
|
|
39
|
-
MAXIMUM_ALWAYS_ON_BYTES =
|
|
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(
|