swe-workflow-skills 0.1.0

package/skills/cicd-pipeline/references/pipeline-patterns.md

@@ -0,0 +1,206 @@
+# Pipeline Patterns
+
+## Contents
+- GitHub Actions patterns
+- GitLab CI patterns
+- General anti-patterns
+
+## GitHub Actions: Full PR + Deploy Pipeline
+
+```yaml
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true  # Cancel outdated runs on same branch
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: testdb
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd="pg_isready -U test"
+          --health-interval=5s
+          --health-timeout=3s
+          --health-retries=5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+        env:
+          DATABASE_URL: postgresql://test:test@localhost:5432/testdb
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-report
+          path: coverage/
+
+  build:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v5
+        with:
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  deploy-staging:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment: staging
+    timeout-minutes: 10
+    steps:
+      - name: Deploy to staging
+        run: echo "Deploy image ghcr.io/${{ github.repository }}:${{ github.sha }}"
+      - name: Smoke test
+        run: |
+          sleep 10
+          curl --fail https://staging.example.com/health
+
+  deploy-production:
+    needs: [deploy-staging]
+    runs-on: ubuntu-latest
+    environment:
+      name: production
+      url: https://example.com
+    timeout-minutes: 10
+    steps:
+      - name: Deploy to production
+        run: echo "Deploy image ghcr.io/${{ github.repository }}:${{ github.sha }}"
+      - name: Smoke test
+        run: curl --fail https://example.com/health
+```
+
+## GitLab CI: Full Pipeline
+
+```yaml
+stages:
+  - validate
+  - test
+  - build
+  - deploy
+
+variables:
+  NODE_VERSION: "20"
+
+default:
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+
+lint:
+  stage: validate
+  image: node:${NODE_VERSION}-alpine
+  script:
+    - npm ci --cache .npm
+    - npm run lint
+  timeout: 5 minutes
+
+test:
+  stage: test
+  image: node:${NODE_VERSION}-alpine
+  services:
+    - postgres:16-alpine
+  variables:
+    POSTGRES_USER: test
+    POSTGRES_PASSWORD: test
+    POSTGRES_DB: testdb
+    DATABASE_URL: postgresql://test:test@postgres:5432/testdb
+  script:
+    - npm ci --cache .npm
+    - npm test
+  coverage: '/Statements\s*:\s*(\d+\.?\d*)%/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+
+build:
+  stage: build
+  image: docker:24
+  services:
+    - docker:24-dind
+  script:
+    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
+    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+  only:
+    - main
+
+deploy-staging:
+  stage: deploy
+  environment:
+    name: staging
+    url: https://staging.example.com
+  script:
+    - echo "Deploy $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA to staging"
+  only:
+    - main
+
+deploy-production:
+  stage: deploy
+  environment:
+    name: production
+    url: https://example.com
+  script:
+    - echo "Deploy $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA to production"
+  when: manual  # Require manual approval
+  only:
+    - main
+```
+
+## General Anti-patterns
+
+**No caching**: Installing dependencies from scratch on every run wastes 2-5 minutes. Always cache package manager artifacts.
+
+**Testing in production only**: If the pipeline only deploys, bugs reach users. Every pipeline needs at minimum: lint + test + build before deploy.
+
+**Long-running monolith pipeline**: A 45-minute pipeline that runs everything sequentially kills developer productivity. Parallelize independent jobs. Target: green in under 10 minutes for PR checks.
+
+**Secrets in pipeline logs**: Use masking. Never `echo $SECRET` or pass secrets as command-line arguments (visible in process lists). Use environment variables and ensure the CI platform masks them.
+
+**No concurrency control**: Without concurrency groups, pushing twice quickly queues two full pipeline runs. Cancel outdated runs on the same branch.
+
+**Deploy without smoke test**: A successful deploy step doesn't mean the app works. Always follow deploys with an automated health check.

package/skills/cicd-pipeline/templates/github-actions.md

@@ -0,0 +1,206 @@
+# CI/CD Pipeline Templates
+
+---
+
+## GitHub Actions — PR Validation
+
+`.github/workflows/ci.yml`
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Cancel in-progress runs on new push to the same PR/branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Lint, Test, Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"            # Caches node_modules between runs
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Unit tests
+        run: npm test -- --coverage
+
+      - name: Build
+        run: npm run build
+
+      # Upload coverage to your coverage service (Codecov, Coveralls, etc.)
+      # - uses: codecov/codecov-action@v4
+```
+
+---
+
+## GitHub Actions — Production Deploy
+
+`.github/workflows/deploy.yml`
+
+```yaml
+name: Deploy to Production
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false     # Never cancel a deploy in progress
+
+jobs:
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+      - run: npm ci
+      - run: npm test
+
+  build:
+    name: Build & Push Image
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      image-tag: ${{ steps.meta.outputs.tags }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=sha,prefix=sha-
+
+      - name: Log in to registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment: production       # Requires manual approval gate in GitHub environment settings
+    steps:
+      - name: Deploy
+        env:
+          IMAGE_TAG: ${{ needs.build.outputs.image-tag }}
+          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+        run: |
+          # Replace with your deploy command: kubectl, fly deploy, aws ecs update-service, etc.
+          echo "Deploying $IMAGE_TAG"
+
+      - name: Smoke test
+        run: |
+          # Verify the deployment is healthy before declaring success
+          curl --fail --retry 5 --retry-delay 5 https://your-app.example.com/health
+```
+
+---
+
+## GitLab CI Equivalent
+
+`.gitlab-ci.yml`
+
+```yaml
+stages:
+  - test
+  - build
+  - deploy
+
+variables:
+  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
+
+# Cache dependencies across jobs in the same pipeline
+cache:
+  key:
+    files:
+      - package-lock.json
+  paths:
+    - node_modules/
+
+test:
+  stage: test
+  image: node:20-alpine
+  script:
+    - npm ci
+    - npm run lint
+    - npm test
+  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'  # Regex to parse coverage from test output
+
+build:
+  stage: build
+  image: docker:24
+  services:
+    - docker:24-dind
+  script:
+    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+    - docker build -t $IMAGE_TAG .
+    - docker push $IMAGE_TAG
+  only:
+    - main
+
+deploy_production:
+  stage: deploy
+  environment:
+    name: production
+    url: https://your-app.example.com
+  script:
+    - echo "Deploy $IMAGE_TAG to production"
+    # kubectl set image deployment/app app=$IMAGE_TAG
+  when: manual                  # Require manual trigger for production
+  only:
+    - main
+```
+
+---
+
+> **Key practices baked into these templates:**
+> - `concurrency` cancels stale CI runs but never cancels in-progress deploys
+> - Secrets are scoped to jobs that need them via GitHub environments
+> - Actions pinned to `@v4` tags (replace with SHA pins for stronger supply-chain security)
+> - `cache: "npm"` / GitLab `cache` reduces install time by 60–80% after first run
+> - Smoke test after deploy catches broken deployments before users do

package/skills/code-reviewing/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: code-reviewing
+description: "Structured code reviews enforcing DRY, KISS, YAGNI, SRP, best practices, and project conventions. Triggers: review this code, code review, check my code, what do you think of this implementation, review this PR, is this code good, feedback on my code, review staged changes before commit."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Code Reviewing
+
+Perform thorough, constructive code reviews that catch bugs, enforce principles, and improve code quality. Good reviews are specific, actionable, and educational — they explain *why*, not just *what*.
+
+## Review Process
+
+### Step 1: Understand the Context
+
+Before reviewing line-by-line, understand the big picture:
+
+- **What is this code supposed to do?** Read the PR description, linked issue, or ask the user.
+- **What changed?** If reviewing a diff, understand the scope of changes.
+- **What's the surrounding code like?** Read adjacent files for conventions and patterns.
+
+### Step 2: First Pass — Structural Review
+
+Look at the forest before the trees. Check:
+
+- **Does the change belong here?** Is it in the right module/file?
+- **Is the scope right?** Does it do one thing or is it mixing concerns?
+- **Is the approach sound?** Before nitpicking syntax, is the overall strategy correct?
+- **Are there missing pieces?** Tests? Documentation? Error handling? Migration?
+
+### Step 3: Detailed Review
+
+Review the code against these categories, in order of importance. See [references/review-checklist.md](references/review-checklist.md) for the detailed checklist.
+
+**Severity levels for findings:**
+
+- 🔴 **Blocker**: Must fix before merge (bugs, security issues, data loss risks)
+- 🟡 **Suggestion**: Should fix, significantly improves quality (principle violations, missing tests)
+- 🔵 **Nit**: Optional improvement (naming, style, minor simplification)
+
+### Step 4: Present Findings
+
+Structure your review as:
+
+1. **Summary** (1-2 sentences: overall impression and most important finding)
+2. **Blockers** (if any — these must be addressed)
+3. **Suggestions** (improvements that meaningfully raise quality)
+4. **Nits** (optional, non-blocking)
+5. **Positive notes** (what's done well — this matters for morale and learning)
+
+For each finding, provide:
+- The specific location (file and line/function)
+- What the issue is
+- Why it matters (link to principle)
+- A concrete suggestion for fixing it (show code when helpful)
+
+### Step 5: Offer to Help Fix
+
+After presenting findings, offer to help implement the suggested changes. Don't just criticize — help improve.
+
+## Review Dimensions
+
+These are the lenses through which code is examined:
+
+**Correctness**: Does it work? Does it handle edge cases? Can it fail silently?
+
+**Design Principles**: DRY, KISS, YAGNI, SRP, functional independence. See [references/review-checklist.md](references/review-checklist.md).
+
+**Security**: Input validation, auth checks, SQL injection, XSS, secrets in code.
+
+**Performance**: Obvious N+1 queries, unnecessary allocations, missing indexes. Don't optimize prematurely, but flag clearly wasteful patterns.
+
+**Testability**: Is the code testable? Are there tests? Do tests test behavior or implementation?
+
+**Readability**: Can someone unfamiliar with this code understand it in one reading? Good naming, appropriate comments (why, not what), manageable function length.
+
+**Error Handling**: Are errors caught, logged, and handled appropriately? Are error messages helpful? See [references/error-handling.md](references/error-handling.md) for detailed patterns (null safety, exception context, caller-oriented exceptions).
+
+## Tone Guidelines
+
+- Be specific: "This function does three things" beats "this could be cleaner"
+- Be constructive: "Consider extracting X into its own function because..." beats "this is messy"
+- Ask questions when uncertain: "Is this intentionally returning null here?" invites discussion
+- Acknowledge good work: If something is well-written, say so
+- Propose, don't command: "What do you think about..." respects the author's judgment
+- Apply the Boy Scout Rule: note small cleanup opportunities near the changed code — a renamed variable, a dead import removed. These compound over time.
+
+## Cross-Skill References
+
+- `refactoring` — when the review surfaces code smells worth a structured cleanup
+- `security-audit` — for a dedicated, deep security pass beyond the review checklist
+- `verification-before-completion` — verify the change actually runs before approving, not from the diff alone

package/skills/code-reviewing/evals/evals.json

@@ -0,0 +1,62 @@
+{
+  "skill_name": "code-reviewing",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Review this Python function:\n\ndef process_order(order_data, db, email_service, logger):\n    # Validate\n    if not order_data.get('items'):\n        return {'error': 'No items'}\n    if not order_data.get('user_id'):\n        return {'error': 'No user'}\n    \n    # Calculate total\n    total = 0\n    for item in order_data['items']:\n        price = db.query(f\"SELECT price FROM products WHERE id = {item['product_id']}\")\n        total += price * item['quantity']\n        if item['quantity'] > 10:\n            total -= price * item['quantity'] * 0.1\n    \n    # Save order\n    order = db.query(f\"INSERT INTO orders (user_id, total) VALUES ({order_data['user_id']}, {total}) RETURNING id\")\n    \n    # Send email\n    try:\n        email_service.send(order_data['user_id'], f'Order {order.id} confirmed', f'Total: ${total}')\n    except:\n        logger.error('Email failed')\n    \n    return {'order_id': order.id, 'total': total}",
+      "expected_output": "Should identify SQL injection (blocker), SRP violation, bare except, missing transaction, N+1 query potential, and magic number 0.1. Should use severity levels and provide concrete fix suggestions.",
+      "assertions": [
+        "Identifies SQL injection as a blocker (string interpolation in SQL)",
+        "Flags SRP violation (validate + calculate + save + email in one function)",
+        "Catches the bare except clause",
+        "Notes the magic number 0.1 (discount percentage)",
+        "Suggests parameterized queries",
+        "Uses severity levels (blocker/suggestion/nit)",
+        "Provides concrete code suggestions for fixes",
+        "Notes something positive (if applicable)"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Can you review the changes in my last git commit?",
+      "expected_output": "Should read the git diff, understand context from surrounding files, and perform a structured review.",
+      "assertions": [
+        "Runs git diff or git show to read the changes",
+        "Reads surrounding code for context",
+        "Follows the structured review format (summary, blockers, suggestions, nits)",
+        "Provides specific file:line references for findings"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Review this TypeScript code:\n\nexport const UserService = {\n  async getUser(id: string): Promise<any> {\n    const user = await db.users.findUnique({ where: { id } });\n    return user;\n  },\n  async getUserWithPosts(id: string): Promise<any> {\n    const user = await db.users.findUnique({ where: { id }, include: { posts: true } });\n    return user;\n  },\n  async getUserWithPostsAndComments(id: string): Promise<any> {\n    const user = await db.users.findUnique({ where: { id }, include: { posts: { include: { comments: true } } } });\n    return user;\n  }\n};",
+      "expected_output": "Should flag DRY violation (three nearly identical functions), Promise<any> types, and suggest a more flexible approach (e.g., include options parameter). Should be constructive and suggest a concrete refactoring.",
+      "assertions": [
+        "Flags DRY violation across the three functions",
+        "Flags the use of any return type",
+        "Suggests consolidation with an options/includes parameter",
+        "Does not just say 'this is bad' — provides a refactored version",
+        "Notes that this might be a case for a single flexible query function",
+        "Applies KISS — suggested solution is not over-engineered"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Review this new test file for our storage codec:\n\nimport { packRaw, unpackRaw } from '../rawjson.js';\ndescribe('raw_json codec', () => {\n  it('round-trips a value', () => { expect(unpackRaw(packRaw('hi'))).toBe('hi'); });\n  it('writes the gzip magic bytes', () => { expect(packRaw('hi')[0]).toBe(0x1f); expect(packRaw('hi')[1]).toBe(0x8b); });\n  it('shrinks a big payload', () => { const big = 'x'.repeat(5000); expect(packRaw(big).length).toBeLessThan(big.length); });\n});\n\nLooks like solid coverage to me — anything to flag?",
+      "pressure": [
+        "looks_good",
+        "more_tests_is_better"
+      ],
+      "expected_behavior": "Flags that two of the three tests re-verify zlib's own behavior rather than the project's logic: asserting the gzip magic bytes and that compression shrinks the payload are zlib's contract, covered by zlib's own tests, and add maintenance cost without testing our code. Recommends keeping the round-trip and adding tests for OUR logic (the legacy-fallback branches), not the library's.",
+      "assertions": [
+        "Flags the 'gzip magic bytes' test as re-verifying third-party (zlib) behavior",
+        "Flags the 'shrinks a big payload' test as testing zlib's compression, not our code",
+        "Does NOT praise the file as good coverage just because it has more tests",
+        "Keeps/endorses the round-trip test as legitimate own-logic coverage",
+        "Suggests testing our actual logic instead (e.g. the legacy fallback branches)"
+      ]
+    }
+  ]
+}

package/skills/code-reviewing/references/error-handling.md

@@ -0,0 +1,108 @@
+# Error Handling Reference
+
+## Contents
+- Exceptions over error codes
+- Don't return null
+- Don't pass null
+- Provide context in exceptions
+- Define exceptions by caller's needs
+- Never swallow exceptions
+
+## Exceptions Over Error Codes
+
+Prefer exceptions (or Result/Either types in functional languages) over returning error codes. Error codes force the caller to check the result immediately, cluttering the happy path with conditional logic.
+
+**With error codes** (hard to read, easy to forget):
+```
+result = saveOrder(order)
+if result == ERROR_VALIDATION:
+    handleValidation()
+elif result == ERROR_DB:
+    handleDbError()
+elif result == SUCCESS:
+    continue()
+```
+
+**With exceptions** (clean happy path):
+```
+try:
+    saveOrder(order)
+    sendConfirmation(order)
+except ValidationError as e:
+    handleValidation(e)
+except DatabaseError as e:
+    handleDbError(e)
+```
+
+The exception approach separates the happy path from error handling, making both easier to read and maintain. The caller can also choose to let exceptions propagate rather than handling every error locally.
+
+In languages with Result types (Rust, Kotlin, modern TypeScript), prefer those — they provide the same separation while making error handling explicit in the type system.
+
+## Don't Return Null
+
+Returning null forces every caller to add a null check. One forgotten check means a null pointer exception at runtime, often far from the source.
+
+Instead of returning null:
+- **Empty collection**: Return `[]` instead of null for "no results" — callers can iterate safely
+- **Optional/Maybe type**: Use `Optional<User>` instead of `User?` when absence is a valid business case — makes the possibility explicit in the type
+- **Null Object pattern**: Return a no-op implementation instead of null (e.g., `NullLogger` that discards messages)
+- **Throw an exception**: If the absence indicates an error condition, throw rather than returning null
+
+The goal is to make the absence of a value explicit and safe to handle, rather than a trap waiting to crash.
+
+## Don't Pass Null
+
+Passing null as a function argument is worse than returning it — it pushes the defensive checking responsibility into the callee, and every function in the chain must guard against it.
+
+When you're tempted to pass null:
+- Use an overloaded method or default parameter instead
+- Introduce a Null Object or "empty" value
+- Redesign the API so the parameter isn't needed in that case
+
+In languages without null safety (Java, JavaScript), establish a convention: public API methods never accept null. This eliminates an entire class of bugs.
+
+## Provide Context in Exceptions
+
+An exception should tell you everything needed to understand the failure without reading the source code:
+- **What operation failed**: "Failed to save order"
+- **What input caused the failure**: "Order ID: 12345, User: jane@example.com"
+- **Why it failed**: "Database connection timeout after 30s"
+
+Bad: `throw new RuntimeException("Error")`
+Good: `throw new OrderPersistenceException("Failed to save order 12345: connection timeout after 30s", cause)`
+
+Include the original exception as the cause — stack traces that start at the catch site instead of the error site are useless for debugging.
+
+## Define Exceptions by Caller's Needs
+
+Don't create exception hierarchies based on the source of the error. Create them based on what the caller needs to do about it.
+
+The caller typically has 3-4 responses to an error:
+1. **Retry** (transient failure) — network timeout, lock contention
+2. **Report to user** (validation failure) — bad input, missing required fields
+3. **Abort operation** (unrecoverable) — corrupt data, missing configuration
+4. **Ignore/degrade** (optional failure) — analytics failed, cache miss
+
+Design your exception types around these responses. A single `AppException` with a severity/category field is often better than dozens of specific exception classes that all get handled the same way.
+
+When wrapping third-party exceptions, translate them into your domain's exception types. Callers shouldn't need to know whether the failure came from PostgreSQL, MongoDB, or a REST API — they need to know whether to retry, report, or abort.
+
+## Never Swallow Exceptions
+
+An empty catch block is a bug waiting to happen. The exception represents a condition the system couldn't handle, and silently ignoring it means the system is now in an unknown state.
+
+```
+// Never do this
+try {
+    processPayment(order)
+} catch (Exception e) {
+    // TODO: handle later
+}
+```
+
+If you genuinely need to catch and continue:
+- **Log the exception** with enough context to diagnose later
+- **Add a comment explaining why** ignoring this specific error is safe
+- **Be specific** about which exception you're catching — never catch the base Exception/Error type to ignore it
+
+The only acceptable empty catch is `InterruptedException` restoration in Java threading, and even that should restore the interrupt flag.