Skill: jackkuo666/debugging-r-environment-and-dependencies (version 0.1.0)

--- name: debugging-r-environment-and-dependencies description: Diagnose and fix R environment issues, including package installation failures, dependency conflicts, system library problems, renv errors, and Bioconductor version mismatches. --- # Debugging R Environment and Dependencies This skill focuses on resolving problems related to R environments rather than analysis logic. It helps restore a working setup so that R scripts and projects can run successfully. Use this skill when the user encounters: - Package installation failures - Version conflicts between packages - renv or packrat environment issues - Bioconductor version mismatches - System dependency errors (e.g., missing compilers or libraries) - R failing to start or load packages --- ## What This Skill Does When activated, this skill will: 1. **Diagnose the environment** - Check R version - Check installed packages and versions - Inspect `renv.lock` or project library - Identify Bioconductor version compatibility 2. **Resolve package installation issues** - Suggest correct CRAN/Bioconductor repositories - Install missing system dependencies (e.g., `libxml2`, `curl`, `openssl`) - Handle compilation failures on Linux/macOS/Windows 3. **Fix dependency conflicts** - Align package versions - Reinstall broken packages - Clean corrupted package libraries 4. **Repair project environments** - Restore with `renv::restore()` - Rebuild `renv.lock` - Reinitialize project library if needed 5. **Bioconductor troubleshooting** - Match Bioconductor version to R version - Use `BiocManager::install()` correctly - Resolve common bioinformatics package errors 6. **System-level troubleshooting** - Install missing compilers (e.g., `gcc`, `gfortran`) - Install development libraries required for R packages - Fix PATH or permission issues --- ## Example User Requests That Should Trigger This Skill - "I can't install tidyverse" - "This package fails with a compilation error" - "renv restore is broken" - "Bioconductor says my version is incompatible" - "library() fails even though the package is installed" - "R says shared object cannot be loaded" --- ## Example Workflow **User:** I get an error when installing `sf`. **Skill actions:** - Detect missing system libraries (GEOS, GDAL, PROJ) - Provide OS-specific install commands - Retry R package installation - Confirm successful library loading --- ## Common Problem Categories | Category | Examples | |---------|----------| | Missing system libs | xml2, curl, openssl, sf, rJava | | Compiler issues | gfortran missing, Xcode tools missing | | Version mismatch | old R vs new package | | Bioconductor mismatch | wrong Bioc version for R | | renv problems | corrupted cache, lockfile mismatch | | Permission issues | cannot write to library path | --- ## Notes - Do not modify analysis code unless necessary - Prefer fixing the environment over rewriting scripts - Always aim to make the project reproducible - Recommend `renv` for future environment stability

path: README.md
content: # Debugging R Environment and Dependencies

An AI skill for diagnosing and fixing R environment issues, including package installation failures, dependency conflicts, system library problems, renv errors, and Bioconductor version mismatches.

## Overview

This skill focuses on resolving **environment problems** rather than analysis logic. It helps restore a working R setup so that scripts and projects can run successfully.

## When to Use This Skill

Activate this skill when you encounter:

| Problem Type | Examples |
|--------------|----------|
| Package installation failures | `ERROR: dependency 'xyz' is not available` |
| Version conflicts | Package A requires version X, but version Y is installed |
| System dependency errors | Missing `libxml2`, `curl`, `openssl`, GEOS, GDAL |
| Compiler issues | `gfortran not found`, Xcode tools missing |
| renv problems | `renv::restore()` fails, corrupted cache |
| Bioconductor mismatches | "Bioc version 3.18 requires R 4.4.0" |
| Permission issues | Cannot write to library path |

## What This Skill Does

### 1. Diagnose the Environment
- Check R version and platform
- List installed packages and versions
- Inspect `renv.lock` or project library
- Identify Bioconductor version compatibility

### 2. Resolve Package Installation Issues
- Suggest correct CRAN/Bioconductor repositories
- Provide OS-specific system dependency commands
- Handle compilation failures on Linux/macOS/Windows

### 3. Fix Dependency Conflicts
- Align package versions to resolve conflicts
- Reinstall broken or corrupted packages
- Clean up corrupted package libraries

### 4. Repair Project Environments
- Restore with `renv::restore()`
- Rebuild `renv.lock` when needed
- Reinitialize project library if necessary

### 5. Bioconductor Troubleshooting
- Match Bioconductor version to R version
- Properly use `BiocManager::install()`
- Resolve bioinformatics package errors

### 6. System-Level Troubleshooting
- Install missing compilers (`gcc`, `gfortran`)
- Install development libraries for R packages
- Fix PATH or permission issues

## Example Usage

```
User: "I can't install sf package"

Skill actions:
- Detects missing system libraries (GEOS, GDAL, PROJ)
- Provides Ubuntu/Debian: sudo apt install libudunits2-dev libgdal-dev libgeos-dev libproj-dev
- Provides macOS: brew install pkg-config gdal geos proj udunits
- Retries R package installation
- Confirms successful library loading
```

## Common Problem Categories

| Category | Common Packages Affected |
|----------|--------------------------|
| Missing system libs | xml2, curl, openssl, sf, rJava |
| Compiler issues | Packages with C/C++/Fortran code |
| Version mismatch | Old R vs new packages |
| Bioconductor mismatch | Bioconductor 3.18+ requires R 4.4+ |
| renv problems | Cache corruption, lockfile issues |
| Permission issues | Cannot write to `/usr/lib/R/library` |

## See Also

- [running-r-analysis-in-existing-projects](../running-r-analysis-in-existing-projects/) - For actual analysis work within R projects


path: examples/README.md
content: # Examples for Debugging R Environment and Dependencies

This directory contains example scenarios that demonstrate how the skill diagnoses and fixes R environment issues.

## Demo Scenarios

Each demo project represents a common R environment problem with a broken setup that needs to be diagnosed and fixed.

### Package Installation Failures

Projects that demonstrate:
- Missing system dependencies (e.g., `sf`, `xml2`, `curl`)
- Compilation failures
- Repository configuration issues

### Dependency Conflicts

Projects that demonstrate:
- Version mismatches between packages
- Incompatible package combinations
- Broken renv environments

### Bioconductor Issues

Projects that demonstrate:
- Bioconductor version mismatch with R version
- BiocManager installation problems
- Bioinformatics package dependencies

---

## Usage

Navigate to any demo project directory and invoke the skill to see how it diagnoses and fixes the environment issues.


path: examples/bioc-version-mismatch/README.md
content: # Bioconductor Version Mismatch Demo

This project demonstrates Bioconductor and R version compatibility issues.

## The Problem

Bioconductor has a specific release schedule tied to R versions:

| Bioconductor | R Version |
|--------------|-----------|
| 3.18 | 4.3.0 - 4.3.3 |
| 3.19 | 4.4.0 - 4.4.2 |
| 3.20 | 4.5.0+ |

If you try to install Bioconductor 3.19 packages on R 4.3.x, you'll get errors.

## Common Error Messages

```
Error in BiocManager::install("DESeq2") :
  Package 'DESeq2' is not available in this Bioconductor version
```

```
Warning: 'BiocManager::install("DESeq2")' failed with message:
  The 'BiocVersion' package is outdated.
```

## What the Skill Should Do

1. Check R version: `R.version$version.string`
2. Check current Bioconductor version
3. Determine correct Bioconductor version for current R
4. Update BiocManager if needed:
   ```r
   install.packages("BiocManager")
   BiocManager::install(version = "3.19")
   ```
5. Retry package installation

## Test the Skill

From this directory, try:

```
"Bioconductor says my version is incompatible"
```

or

```
"I can't install DESeq2 from Bioconductor"
```


path: examples/broken-renv-project/README.md
content: # Broken renv Project Demo

This project demonstrates a broken `renv` environment that needs repair.

## The Problem

The `renv.lock` file was created with R 4.3.0, but you might be running a different version of R. This causes `renv::restore()` to fail with version mismatch errors.

## Expected Behavior

When you run:

```r
renv::restore()
```

You may encounter errors like:
- "Package version mismatch detected"
- "Cannot install package [package] - available version is [version] but locked version is [version]"
- "The lockfile is incompatible with your version of R"

## What the Skill Should Do

1. Check current R version vs lockfile R version
2. Decide whether to update lockfile or downgrade R
3. Run `renv::restore()` or `renv::update()` accordingly
4. Verify packages load correctly

## Test the Skill

From this directory, try:

```
"renv restore is broken, please fix it"
```


path: examples/missing-system-deps/README.md
content: # Missing System Dependencies Demo

This project demonstrates R package installation failures due to missing system libraries.

## The Problem

The `script.R` file tries to load packages that require system-level libraries that may not be installed.

## Packages That Commonly Fail

| Package | System Dependencies Required |
|---------|------------------------------|
| `sf` | GEOS, GDAL, PROJ, UDUNITS |
| `xml2` | libxml2 |
| `curl` | libcurl |
| `openssl` | openssl |
| `rJava` | Java JDK |
| `terra` | GDAL, GEOS, PROJ |

## Common Error Messages

```
Error: package or namespace load failed for 'sf' in dyn.load(file, DLLpath = DLLpath, ...):
 unable to load shared object '/usr/lib/R/library/00LOCK-sf/00new/sf/libs/sf.so':
  libgdal.so.30: cannot open shared object file: No such file or directory
```

```
Configuration error: could not find the gdal-config config script.
```

## What the Skill Should Do

1. Identify which system library is missing
2. Detect the operating system
3. Provide the correct installation command:

**Ubuntu/Debian:**
```bash
sudo apt install libudunits2-dev libgdal-dev libgeos-dev libproj-dev
```

**macOS:**
```bash
brew install pkg-config gdal geos proj udunits
```

**Fedora/RHEL:**
```bash
sudo dnf install gdal-devel geos-devel proj-devel udunits2-devel
```

4. Retry the R package installation
5. Confirm the package loads successfully

## Test the Skill

From this directory, try:

```
"I can't install the sf package"
```

or

```
"sf fails with a compilation error"
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)