From ae48a5ce59a3b2c5864de192374e6f03e212c51b Mon Sep 17 00:00:00 2001 From: PEZ Date: Fri, 3 Oct 2025 17:23:17 +0200 Subject: [PATCH 1/3] Tweak Clojure instructions about missing repl --- instructions/clojure.instructions.md | 83 ++++++++++++++++++++++------ 1 file changed, 67 insertions(+), 16 deletions(-) diff --git a/instructions/clojure.instructions.md b/instructions/clojure.instructions.md index 52cdb908..1e38718d 100644 --- a/instructions/clojure.instructions.md +++ b/instructions/clojure.instructions.md @@ -36,6 +36,72 @@ Docstrings belong immediately after the function name and before the argument ve - Define functions before they are used—prefer ordering over `declare` except when truly necessary. +## Interactive Programming (a.k.a. REPL Drivern Development) + +### Align Data Structure Elements for Bracket Balancing +**Always align multi-line elements vertically in all data structures (vectors, maps, lists, sets, all code). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms. + +```clojure +;; ❌ Wrong - misaligned vector elements +(select-keys m [:key-a + :key-b + :key-c]) ; Misalignment → incorrect ] placement + +;; ✅ Correct - aligned vector elements +(select-keys m [:key-a + :key-b + :key-c]) ; Proper alignment → correct ] placement + +;; ❌ Wrong - misaligned map entries +{:name "Alice" + :age 30 +:city "Oslo"} ; Misalignment → incorrect } placement + +;; ✅ Correct - aligned map entries +{:name "Alice" + :age 30 + :city "Oslo"} ; Proper alignment → correct } placement +``` + +**Critical**: The bracket balancer relies on consistent indentation to determine structure. + +### REPL Dependency Management +Use `clojure.repl.deps/add-libs` for dynamic dependency loading during REPL sessions. + +```clojure +(require '[clojure.repl.deps :refer [add-libs]]) +(add-libs '{dk.ative/docjure {:mvn/version "1.15.0"}}) +``` + +- Requires Clojure 1.12 or later +- Perfect for library exploration and prototyping + +### Checking Clojure Version + +```clojure +*clojure-version* +;; => {:major 1, :minor 12, :incremental 1, :qualifier nil} +``` + +### REPL Availability Discipline + +**Never edit code files when the REPL is unavailable.** When REPL evaluation returns errors like "No available JS runtime", stop immediately and inform the user: + +``` +The REPL is currently unavailable. I cannot verify changes without REPL access. Please ensure the REPL is connected before proceeding with code modifications. +``` + +#### Why This Matters +- **Interactive Programming requires working REPL** - Cannot verify behavior without evaluation +- **Guessing creates bugs** - Code changes without testing introduce errors +- **User wastes time** - Undoing speculative changes is frustrating +- **Trust erosion** - Making changes without verification undermines confidence + +#### When REPL Is Unavailable +1. **Stop immediately** - Do not proceed with code changes +2. **Inform the user** - Clearly state REPL is unreachable +3. **Wait for reconnection** - Let user restore REPL before continuing + ## Structural Editing and REPL-First Habit - Develop changes in the REPL before touching files. - When editing Clojure files, always use structural editing tools such as **Insert Top Level Form**, **Replace Top Level Form**, **Create Clojure File**, and **Append Code**, and always read their instructions first. @@ -51,22 +117,6 @@ After editing files, reload the edited namespace in the REPL so updated definiti (require 'my.namespace :reload) ``` -### Keeping Brackets Balanced -If tools or the compiler signal bracket imbalance, stop and ask for help rather than guessing—use the human-input tool. - -## Interactive Programming with REPL - -When evaluating code during development, always show the complete code being evaluated in a code block before using evaluation tools. The code block should start with the appropriate `(in-ns ...)` form and contain the exact code being evaluated, so the human can run the same code in their REPL. - -Example: -```clojure -(in-ns 'my.namespace) -(let [test-data {:name "example"}] - (process-data test-data)) -``` - -This applies to all REPL-driven development, whether using Calva, Joyride, or other Clojure evaluation tools. - ## Code Indentation Before Evaluation Consistent indentation is crucial to help the bracket balancer. @@ -307,3 +357,4 @@ Guidelines: ## Happy Interactive Programming Remember to prefer the REPL in your work. Keep in mind that the user does not see what you evaluate. Nor the results. Communicate with the user in the chat about what you evaluate and what you get back. + From af8e31c4a7b9f6f47f28af2d4402ce146c46be50 Mon Sep 17 00:00:00 2001 From: PEZ Date: Fri, 3 Oct 2025 17:25:15 +0200 Subject: [PATCH 2/3] typos --- instructions/clojure.instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/instructions/clojure.instructions.md b/instructions/clojure.instructions.md index 1e38718d..483c4d39 100644 --- a/instructions/clojure.instructions.md +++ b/instructions/clojure.instructions.md @@ -36,10 +36,10 @@ Docstrings belong immediately after the function name and before the argument ve - Define functions before they are used—prefer ordering over `declare` except when truly necessary. -## Interactive Programming (a.k.a. REPL Drivern Development) +## Interactive Programming (a.k.a. REPL Driven Development) ### Align Data Structure Elements for Bracket Balancing -**Always align multi-line elements vertically in all data structures (vectors, maps, lists, sets, all code). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms. +**Always align multi-line elements vertically in all data structures (vectors, maps, lists, sets, all code). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms.** ```clojure ;; ❌ Wrong - misaligned vector elements From 158df66a8c9d91d168e331bb16b953881fae720b Mon Sep 17 00:00:00 2001 From: PEZ Date: Fri, 3 Oct 2025 18:22:29 +0200 Subject: [PATCH 3/3] Tidy up --- instructions/clojure.instructions.md | 29 +++++++++------------------- 1 file changed, 9 insertions(+), 20 deletions(-) diff --git a/instructions/clojure.instructions.md b/instructions/clojure.instructions.md index 483c4d39..b29fbbc2 100644 --- a/instructions/clojure.instructions.md +++ b/instructions/clojure.instructions.md @@ -7,7 +7,7 @@ applyTo: '**/*.{clj,cljs,cljc,bb,edn.mdx?}' ## Code Evaluation Tool usage -“Use the repl” means to use the **Evaluate Clojure Code** tool from Calva Backseat Driver. It connects you to the the same REPL as the user is connected to via Calva. +“Use the repl” means to use the **Evaluate Clojure Code** tool from Calva Backseat Driver. It connects you to the same REPL as the user is connected to via Calva. - Always stay inside Calva's REPL instead of launching a second one from the terminal. - If there is no REPL connection, ask the user to connect the REPL instead of trying to start and connect it yourself. @@ -39,7 +39,7 @@ Docstrings belong immediately after the function name and before the argument ve ## Interactive Programming (a.k.a. REPL Driven Development) ### Align Data Structure Elements for Bracket Balancing -**Always align multi-line elements vertically in all data structures (vectors, maps, lists, sets, all code). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms.** +**Always align multi-line elements vertically in all data structures: vectors, maps, lists, sets, all code (since Clojure code is data). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms.** ```clojure ;; ❌ Wrong - misaligned vector elements @@ -73,7 +73,7 @@ Use `clojure.repl.deps/add-libs` for dynamic dependency loading during REPL sess (add-libs '{dk.ative/docjure {:mvn/version "1.15.0"}}) ``` -- Requires Clojure 1.12 or later +- Dynamic dependency loading requires Clojure 1.12 or later - Perfect for library exploration and prototyping ### Checking Clojure Version @@ -85,29 +85,18 @@ Use `clojure.repl.deps/add-libs` for dynamic dependency loading during REPL sess ### REPL Availability Discipline -**Never edit code files when the REPL is unavailable.** When REPL evaluation returns errors like "No available JS runtime", stop immediately and inform the user: - -``` -The REPL is currently unavailable. I cannot verify changes without REPL access. Please ensure the REPL is connected before proceeding with code modifications. -``` +**Never edit code files when the REPL is unavailable.** When REPL evaluation returns errors indicating that the REPL is unavailable, stop immediately and inform the user. Let the user restore REPL before continuing. #### Why This Matters -- **Interactive Programming requires working REPL** - Cannot verify behavior without evaluation +- **Interactive Programming requires a working REPL** - You cannot verify behavior without evaluation - **Guessing creates bugs** - Code changes without testing introduce errors -- **User wastes time** - Undoing speculative changes is frustrating -- **Trust erosion** - Making changes without verification undermines confidence - -#### When REPL Is Unavailable -1. **Stop immediately** - Do not proceed with code changes -2. **Inform the user** - Clearly state REPL is unreachable -3. **Wait for reconnection** - Let user restore REPL before continuing ## Structural Editing and REPL-First Habit - Develop changes in the REPL before touching files. - When editing Clojure files, always use structural editing tools such as **Insert Top Level Form**, **Replace Top Level Form**, **Create Clojure File**, and **Append Code**, and always read their instructions first. ### Creating New Files -- Use the **Create Clojure File** tool, with initial content +- Use the **Create Clojure File** tool with initial content - Follow Clojure naming rules: namespaces in kebab-case, file paths in matching snake_case (e.g., `my.project.ns` → `my/project/ns.clj`). ### Reloading Namespaces @@ -171,7 +160,7 @@ You can also use "inline def" when showing the user code in the chat, to make it ## Return values > print side effects -Prefer using the repl and return values from your evaluations, over printing things to stdout. +Prefer using the REPL and return values from your evaluations, over printing things to stdout. ## Reading from `stdin` - When Clojure code uses `(read-line)`, it will prompt the user through VS Code. @@ -322,9 +311,9 @@ Iterate with real data before editing files. ``` #### Benefits -- Verified behaviour before committing changes +- Verified behavior before committing changes - Incremental development with immediate feedback -- Tests that capture known-good behaviour +- Tests that capture known-good behavior - Start new work with failing tests to lock in intent ### Test Naming and Messaging