DevCheats

.agents/skills/code-review/SKILL.md

---
name: code-review
description: Review a pull request or diff like a senior engineer. Use when asked to review code changes, a PR, or a branch before merge.
---

# Code Review

Review the change for correctness first, style last. Never approve code you have not actually read.

## Inputs to gather

- The diff: `git diff main...HEAD` (or the PR diff the user pasted)
- Commit messages: `git log --oneline main..HEAD`
- The stated intent of the change — ask if it is not clear

## Review procedure

1. **Understand intent.** Restate in one sentence what the change is supposed to do. If the diff does not match the intent, that is the first finding.
2. **Read every changed file in full**, not just the hunks. Check how the changed code interacts with its surroundings.
3. **Hunt for real bugs:**
   - Broken edge cases: empty input, null/undefined, zero, boundary values
   - Async hazards: unhandled rejections, race conditions, missing await
   - Error handling: swallowed errors, wrong status codes, missing rollback
   - Logic inversions and off-by-one errors
   - State that can go stale or desync
4. **Check blast radius.** Search for other callers of changed functions (`rg "functionName"`). Flag changed public APIs and behavior changes that callers may rely on.
5. **Check tests.** Every behavior change should have a test. Name the exact missing cases.
6. **Security pass.** Injection, authz checks on new endpoints, secrets in code, unsafe deserialization. See the security-review skill for the full checklist.

## Output format

## Verdict
Approve / Request changes / Comment — with one sentence of rationale.

## Blocking issues
Each as: [file:line] problem → why it matters → suggested fix. Only real, evidence-backed issues.

## Suggestions (non-blocking)
Improvements the author may take or leave.

## Missing tests
Concrete test cases to add.

## Rules

- Every finding cites a file and line. No vague "this looks risky".
- Do not review style the linter already covers.
- Do not request changes for personal preference — label opinions as opinions.
- If the diff is too large to review well, say so and propose a split.

.agents/skills/systematic-debugging/SKILL.md

---
name: systematic-debugging
description: Debug a reported bug or failing behavior methodically. Use when the user reports something broken, an error, or unexpected behavior and wants it fixed.
---

# Systematic Debugging

Fix causes, not symptoms. Never edit code before you can reproduce the failure.

## Procedure

1. **Reproduce.** Get a reliable repro: exact steps, input, or failing test. If you cannot reproduce it, say so and gather what is missing (logs, environment, input data) instead of guessing.
2. **State the contract.** Write down expected vs actual behavior in one sentence each.
3. **Read the error fully.** Full stack trace, not the first line. The deepest frame in project code is usually closer to the cause than the top.
4. **Localize.** Narrow to the smallest unit that fails:
   - Add temporary logging or a debugger breakpoint at the suspected boundary
   - Comment out / stub downstream calls to isolate
   - For regressions: `git bisect start && git bisect bad && git bisect good <sha>`, then run the repro at each step
5. **Form one hypothesis at a time.** Write it down: "X is null because Y returns early when Z". Test it with the smallest possible experiment. If wrong, discard it fully before forming the next.
6. **Fix minimally.** The smallest change that removes the root cause. No drive-by refactors in the same commit.
7. **Add a regression test** that fails on the old code and passes on the new code. Name it after the bug.
8. **Verify broadly.** Run the repro, the new test, then the surrounding test suite.

## Anti-patterns to avoid

- Shotgun debugging: changing several things at once "to see if it helps"
- Catching and swallowing the error instead of fixing why it happens
- Fixing the repro case only (special-casing the reported input)
- Declaring victory without re-running the original repro

## Output

- Root cause (one paragraph, with evidence)
- The fix and why it is minimal
- The regression test added
- Anything still unexplained

.agents/skills/writing-tests/SKILL.md

---
name: writing-tests
description: Write tests that match the repo's existing conventions. Use when asked to add, fix, or improve test coverage for a module, function, or bug.
---

# Writing Tests

Tests must look like they were written by the team, not generated.

## Before writing anything

1. Find the existing tests: `rg --files -g '*test*' -g '*spec*'`
2. Read 2–3 of them. Note the framework, file naming, describe/it style, fixture factories, and assertion helpers in use.
3. Find how tests are run (package.json scripts, Makefile, CI config). Use exactly that command.
4. Never introduce a new framework, assertion library, or directory layout without asking.

## What to test

- **Behavior, not implementation.** Assert on inputs and outputs, not internal calls, unless the internal call IS the contract (e.g. "does not hit the database").
- **The branches that matter:** happy path, each error path, boundary values (empty, 0, max, off-by-one), invalid input.
- **Regression first:** if this work comes from a bug report, write the failing test that reproduces the bug before anything else.

## Writing rules

- One behavior per test; the test name states the expected behavior ("returns null when user is missing", not "test getUser").
- Arrange / Act / Assert, visibly separated.
- Deterministic: no real time, randomness, network, or wall-clock sleeps. Mock the boundary, inject the clock.
- Independent: tests pass in any order and in isolation (`--runInBand` or shuffle mode too).
- Mock sparingly. Prefer fakes/in-memory implementations over deep mock chains; if you mock everything you test nothing.
- Cover error messages and status codes, not just "it throws".

## Finishing

1. Run the new tests — watch them pass.
2. Mutate the source (break it on purpose) — watch the tests fail. Revert.
3. Run the full suite to check for interference.
4. Report: files added, cases covered, and any behavior you could not test and why.

.agents/skills/safe-refactoring/SKILL.md

---
name: safe-refactoring
description: Restructure code without changing behavior. Use when asked to clean up, simplify, deduplicate, rename, or reorganize existing working code.
---

# Safe Refactoring

Refactoring changes structure, never behavior. If behavior must change too, that is a separate commit.

## Ground rules

1. **Tests before moves.** If the code you are touching has no tests, write characterization tests first (lock in current behavior, including quirks). Do not refactor untested code blind.
2. **One transformation at a time.** Extract function, rename, move module, inline — each as its own step with tests run in between. Never stack five rewrites into one edit.
3. **Preserve public APIs** unless the task explicitly says otherwise. Check all call sites with `rg` before changing a signature.
4. **No scope creep.** Do not fix unrelated formatting, upgrade dependencies, or rename adjacent things. Note them, mention them, leave them.

## Procedure

1. Run the relevant test suite — it must be green before you start.
2. State the target structure in 2–3 sentences so the user can stop you if it is wrong.
3. Apply one transformation.
4. Run tests. Red? Undo that step, understand why, redo smaller.
5. Repeat until done, then run the full suite plus lint/typecheck.
6. Review the final diff yourself: `git diff` should show movement and renaming, not logic edits.

## Common safe transformations

- Extract function/component from a long body (copy the code verbatim, pass in what it uses)
- Rename with editor-wide rename or `rg -l old | xargs sed -i 's/old/new/g'` followed by import checks
- Move a module and update every import in the same commit
- Replace a conditional with a lookup table or early returns — only when branches map 1:1

## Report

- What was restructured and why it is more maintainable
- Proof behavior is unchanged: tests green before/after, diff summary
- Deliberately untouched issues you noticed

.agents/skills/security-review/SKILL.md

---
name: security-review
description: Audit code or a diff for exploitable security issues. Use when asked to check code for vulnerabilities, review auth, or assess security before shipping.
---

# Security Review

Report only issues you can explain how to exploit. Severity without an attack path is noise.

## Checklist by area

**Injection**
- SQL: string-built queries anywhere? Require parameterized queries/ORM bindings.
- Shell: user input reaching `exec`, `spawn`, `system()`? Require arg arrays, never string interpolation.
- Template/HTML: unescaped output → XSS. Check dangerously-set-html equivalents.

**AuthN / AuthZ**
- Every new route/handler: who may call it, and where is that enforced? Client-side checks do not count.
- Object-level access: can user A fetch user B's resource by changing an ID? (IDOR)
- JWT/session: signature verified, expiry enforced, secret not hardcoded?

**Data exposure**
- Secrets in code, config, logs, or error messages — run `gitleaks detect` if available.
- API responses leaking fields the UI never shows (password hashes, internal IDs).
- Stack traces or debug endpoints reachable in production.

**Web classics**
- CSRF on state-changing GETs or cookie-auth POSTs without tokens.
- SSRF: user-controlled URLs fetched server-side — check allowlists.
- Path traversal: user input joined into file paths.
- Open redirects via unvalidated `next`/`returnTo` params.

**Dependencies & config**
- `npm audit` / `pip-audit` for known CVEs in actually-shipped deps.
- Insecure defaults: debug mode, permissive CORS (`*` with credentials), default credentials.

## Output format

For each finding:
- **Title + severity** (Critical/High/Medium/Low) **+ confidence** (Confirmed/Likely/Needs verification)
- **Location:** file:line
- **Attack path:** concrete steps an attacker would take
- **Fix:** specific remediation, not "sanitize input"
- **Verify:** how to confirm the fix works

End with a short list of areas checked and found clean, so silence is not ambiguous.

.agents/skills/dependency-upgrade/SKILL.md

---
name: dependency-upgrade
description: Upgrade dependencies with breaking-change review and verification. Use when asked to update, bump, or migrate packages or framework versions.
---

# Dependency Upgrade

An upgrade is not done when the version number changes — it is done when the app still works.

## Procedure

1. **Inventory.** `npm outdated` (or `pnpm outdated` / `poetry show --outdated`). Record current → target for each package.
2. **Read the release notes for every major bump.** Check CHANGELOG, GitHub releases, and migration guides. List breaking changes that could touch this codebase.
3. **Grep for the breaking APIs** before upgrading: `rg "removedFunctionName"`. If the code uses them, plan the codemod.
4. **Upgrade in stages:**
   - Patch/minor updates in one batch
   - Each major version in its own commit, riskiest package first
   - Never upgrade 10 majors at once
5. **After each stage, run the gates:** install, typecheck, lint, tests, build. All must pass before the next.
6. **Inspect the lockfile diff** (`git diff package-lock.json | head -200`): watch for unexpected transitive major bumps or duplicate versions of the same package.
7. **Check for deprecations** in the output of the test/build run — migrate them now while context is fresh.

## Migration edits

- Follow the official migration guide exactly; do not improvise new APIs.
- Search for every usage site; a missed call site compiles fine and breaks at runtime.
- For config format changes, migrate the config file and verify the tool actually starts.

## Report

- Table: package, old → new, risk level, breaking changes relevant to us
- Validation results (tests/build/lint)
- Residual risks and how to roll back (`git revert` of the stage commit, or pin to previous version)