change-safety

Files (1)

• SKILL.md

SKILL.md (first lines)

# Change-safety (blast radius)

Ship gates catch **red tests**. This skill catches **“fixed A, broke B.”**

Run this **before** multi-file work (and again before commit/ship).

## When to use

- Implement / fix / refactor / “don't break X”
- Desktop shell, messengers, browser embed, settings, concurrent chat
- Any monorepo or multi-surface app (desktop + web, agent + gateway)

## Steps (always)

### 1. Name the change

One sentence: what **user- or API-visible** behavior changes?

### 2. Classify the surface

Pick primary (+ secondary): chat/ReAct · messengers/gateway · desktop chrome ·
workspace rails (browser/terminal) · settings/secrets · docs-only · release/packaging.

### 3. Blast-radius questions

1. **Same SPA / shared frontend?** UI change may need rebuild + server restart for WebUI.  
2. **Two processes?** Sidecar + UI, dual pollers, dual port owners — avoid fights.  
3. **Cross-path?** Desktop stream vs messenger vs legacy chat — session provider/model.  
4. **OS / Windows-only?** Paths, secrets, WebView2, installers — reason about those.  
5. **Hard to unit-test?** Title bar, tray, embedded browser, live bots → **manual smoke**.  
6. **Known failure class?** Prefer architecture that removes the class (e.g. OS window
   decorations for min/max/close; exclusive poll lock for Telegram) over another patch.

### 4. Paired checks

| If you touch… | Also verify… |
|---------------|--------------|
| Gateway / Telegram | Single poller; inbound + outbound; no 409 thrash |
| Session stream / LLM | Provider switch isolation; messenger uses session LLM |
| SSE / messages UI | No force-reload mid-stream |
| Window chrome | OS min/max/close; tray; close-to-tray; quit |
| Browser rail | Load works; popout chrome clickable; external open |
| Settings / secrets | Save + reconnect; no secrets in plain config |
| Docs | Sync/check scripts the project uses |
| Version / release | All version surfaces aligned |

### 5. Manual smoke (when chrome / messengers / browser touched)

One clean instance: launch → short chat → window controls → browser rail →
messenger round-trip (if enabled) → full quit → relaunch (no dual serve).

### 6. Neighbor rule before commit

List **files you did not edit** that couple to this change and confirm tested or
safe. If unsure: targeted test or commit note `Risk: … / Smoke: …`.

### 7. What CI does not prove

CI does not click title bars, drive Telegram, or exercise multiwebview on a real
GPU. Green CI is **necessary, not sufficient** for those zones.

### 8. Local CI before every push

Remote CI is not a surprise. Run the **same commands** `.github/workflows/ci.yml`
runs (ruff, mypy, docs, pytest, desktop npm test+build — see root `AGENTS.md`
**Local CI**). Pytest-only is not enough.

If remote CI fails: run **that failed step locally**, fix until green, **then**
push. Do not push a guess.

## After implementation

- Targeted tests for behavior you changed  
- Full suite when shipping or when user asked “test everything”  
- Local CI commands green **before** `git push`  
- For **ship/release**, also activate **project-etiquette** (gate chain)

## Anti-patterns

- “Tests pass” without smoke for the surface you changed  
- Pushing after pytest-only when CI also runs ruff / mypy / docs  
- Pushing a CI-fix without re-running the failed step locally  
- Patching a recurring class of bug without changing architecture  
- Shipping desktop UI without WebUI rebuild/restart when SPA is shared  
- Dual processes fighting a single bot token or port

From AhmiDarrow/RemedyAI, Apache-2.0.

More from AhmiDarrow/RemedyAI