Merge branch 'main' into issue_360-iv_summary_method

Author: anevolbap

.github/skills/github-issues/reference/issue-evaluation.md

@@ -10,10 +10,26 @@ description: Analyze an issue, check current relevance, and propose next steps o
 gh issue view <issue_number> --json number,title,body,state,labels,comments,assignees
 ```
 
+## Check for sub-issues (native hierarchy)
+
+Always check whether an issue has native sub-issues. The `trackedIssues` / `trackedInIssues` GraphQL fields only cover older markdown task-list tracking and will miss native sub-issues.
+
+```bash
+gh api graphql -f query='query {
+  repository(owner:"<owner>", name:"<repo>") {
+    issue(number: <issue_number>) {
+      subIssues(first: 50) { nodes { number title state url } }
+      parent { number title state url }
+    }
+  }
+}'
+```
+
 ## Analyze context
 - Extract the problem statement and acceptance criteria
 - Summarize discussion history and blockers
 - Identify affected files/modules
+- Review sub-issues (if any) for work breakdown and progress
 
 ## Assess relevance
 - Search codebase for mentioned APIs or modules

.github/skills/github-issues/reference/parent-child-issues.md

@@ -91,7 +91,24 @@ gh api graphql \
   -f sub='<CHILD_NODE_ID>'
 ```
 
-## 6) Verify links rendered correctly
+## 6) Discover existing sub-issues
+
+When evaluating an issue that may already have sub-issues, always use the `subIssues` GraphQL field. Do **not** use `trackedIssues` / `trackedInIssues` -- those only cover older markdown task-list tracking and will miss native sub-issues.
+
+```bash
+gh api graphql -f query='query {
+  repository(owner:"<owner>", name:"<repo>") {
+    issue(number: <issue_number>) {
+      subIssues(first: 50) {
+        nodes { number title state url }
+      }
+      parent { number title state url }
+    }
+  }
+}'
+```
+
+## 7) Verify links rendered correctly
 
 ```bash
 gh api graphql -f query='query {

.github/skills/python-environment/SKILL.md

@@ -1,12 +1,32 @@
 ---
 name: python-environment
-description: Detect and configure a conda-compatible tool, create the CausalPy environment, and run commands inside it. Use before any task that requires Python execution.
+description: Detect, configure, and use a conda-compatible tool. Use before tasks that need the project environment, such as importing project code, running tests, building docs, or invoking repo tooling.
 ---
 
 # Python Environment
 
 Set up and run commands inside the CausalPy conda environment.
 
+## Decide whether the env is required
+
+Use the `CausalPy` env when the command:
+
+- imports project code (for example `import causalpy` or project modules)
+- runs tests
+- builds docs
+- invokes repo tooling such as `make`, `prek`, or notebook execution
+
+For simple inspection helpers that only read local text/JSON or use the Python standard library, any Python on `PATH` is acceptable.
+
+## Reuse before creating
+
+Do the least work that will get the task done:
+
+1. Reuse an existing `CausalPy` env if one is already available.
+2. If `run -n CausalPy` cannot resolve the env, check whether it exists under a different prefix and use `run -p`.
+3. Only create the env if no suitable existing env is available.
+4. Only update the env or rerun `make setup` when dependencies changed, the editable install is stale, or the current checkout has not been installed into that env yet.
+
 ## Detect the conda tool
 
 Use whichever of `mamba`, `micromamba`, or `conda` is available (checked in that order):
@@ -24,21 +44,25 @@ If `CONDA_EXE` is empty, no conda-compatible tool was found. Propose installing
 
 After installation, set `CONDA_EXE=micromamba`.
 
-## Create the environment
+## Create the environment only if needed
+
+If no suitable existing env can be reused, create it:
 
 ```bash
 $CONDA_EXE env create -f environment.yml
 ```
 
-## Install the package (required after creating or updating the environment)
+## Install the package only when needed
+
+Run `make setup` after creating or updating the env. Also rerun it when using a different git worktree if that env has not been installed against the current checkout yet.
 
 ```bash
 $CONDA_EXE run -n CausalPy make setup
 ```
 
 ## Run commands
 
-Always use `run -n` instead of `activate`:
+Never use `$CONDA_EXE activate`, instead use `$CONDA_EXE run -n CausalPy <command>`.
 
 ```bash
 $CONDA_EXE run -n CausalPy <command>
@@ -54,6 +78,25 @@ $CONDA_EXE env update --file environment.yml --prune
 
 ## Troubleshooting
 
+### Named env cannot be resolved
+
+If `$CONDA_EXE run -n CausalPy ...` fails with errors such as `The given prefix does not exist`:
+
+```bash
+$CONDA_EXE env list
+$CONDA_EXE run -p "/full/path/to/CausalPy" <command>
+```
+
+Keep using `run -p` with that full prefix for the rest of the session.
+
+### Git worktrees and remote machines
+
+Git worktrees do not require a fresh env per agent session. Prefer reusing an existing env to save time. The main caveat is that this repo uses editable installs, so one shared env can point at whichever checkout most recently ran `make setup`.
+
+- For ordinary local work on one checkout, reuse the existing env.
+- For long-lived parallel worktrees, one env per worktree is the safest option, but do not create one unless needed.
+- On a fresh remote machine or ephemeral container, create the env once. On a persistent remote machine with an existing env, reuse it.
+
 If you hit issues with an outdated tool, update it:
 
 - **mamba / micromamba**: `$CONDA_EXE self-update`

.github/workflows/ci.yml

@@ -26,12 +26,12 @@ jobs:
           python-version: "3.12"
       - name: Run prek on changed files in PRs
         if: github.event_name == 'pull_request'
-        uses: j178/prek-action@53276d8b0d10f8b6672aa85b4588c6921d0370cc # v2.0.1
+        uses: j178/prek-action@cbc2f23eb5539cf20d82d1aabd0d0ecbcc56f4e3 # v2.0.2
         with:
           extra-args: --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.event.pull_request.head.sha }}
       - name: Run prek on all files on pushes
         if: github.event_name != 'pull_request'
-        uses: j178/prek-action@53276d8b0d10f8b6672aa85b4588c6921d0370cc # v2.0.1
+        uses: j178/prek-action@cbc2f23eb5539cf20d82d1aabd0d0ecbcc56f4e3 # v2.0.2
         with:
           extra-args: --all-files