skilldrop-cli 0.2.0

package/skills/design-doc/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: design-doc
+description: Generate a Google-style engineering design doc (problem, goals/non-goals, options considered, recommended approach, risks, rollout) from a feature brief or short description. Use when the user wants to draft a design doc, technical proposal, or one-pager for an engineering review.
+---
+
+# design-doc
+
+You help the user turn a feature brief into a structured design doc that an engineering team can review and approve.
+
+## How to respond
+
+1. **Understand the brief.** Make sure you know:
+   - **What we're building** (one sentence)
+   - **Who's affected** (users, callers, teams)
+   - **Why now** (the forcing function — outage, regulatory, competitor, scaling cliff)
+
+   If any of these are missing, ask. Don't draft a design doc without a *why now*.
+
+2. **Default to the standard structure** in [`templates/design-doc.md`](templates/design-doc.md):
+   1. Title + status (Draft / In Review / Approved) + author + date
+   2. **TL;DR** — three bullets, readable in 30 seconds
+   3. **Context** — why is this being proposed
+   4. **Goals / Non-goals** — explicit non-goals matter as much as goals
+   5. **Proposal** — the actual design (this is the longest section)
+   6. **Alternatives considered** — at least 2 alternatives with why-not
+   7. **Risks & mitigations**
+   8. **Rollout plan** — staged rollout, feature flag, rollback criteria
+   9. **Open questions**
+
+3. **Length discipline.** A good design doc is **2–5 pages** rendered. If you blow past that, you're either solving too many problems in one doc or writing reference material that belongs elsewhere.
+
+4. **Show, don't tell.** Where the design is structural, embed a Mermaid diagram (use the `architecture-diagrams` skill if needed). Where it's about flows, embed a sequence diagram. Where it's about API shape, embed a small example request/response.
+
+5. **End with explicit asks.** The "Open questions" section is where the doc earns its keep — list the *real* unresolved questions, with the names of people who should answer them.
+
+## Quality bar
+
+- **Non-goals are real, not throat-clearing.** If your non-goals list reads "we're not solving world hunger", delete it. Good non-goals are things a reasonable reader might assume you *are* doing ("not migrating existing customers in v1").
+- **Alternatives have a why-not, not just a description.** Two sentences each: what is it, why didn't we pick it.
+- **Risks have mitigations.** A bare list of "things that could go wrong" is anxiety, not engineering.
+- **Rollout criteria are concrete.** "We'll monitor closely" is not a criterion. "Roll forward to 100% if p99 < 80ms for 48h after 10% rollout" is.
+
+## Anti-patterns to avoid
+
+- ❌ Starting with implementation detail before establishing the problem.
+- ❌ "Future work" sections that double the doc length with hypotheticals.
+- ❌ Using passive voice to avoid naming who owns what ("it will be deployed" — by whom?).
+- ❌ Skipping the alternatives section because "we already know what to do" — this is *exactly* when a design review catches blind spots.
+- ❌ More than ~5 pages. Cut, link out, or split into multiple docs.

package/skills/design-doc/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "design-doc",
+  "version": "0.1.0",
+  "description": "Generate a Google-style engineering design doc (problem, goals/non-goals, options considered, recommended approach, risks, rollout) from a feature brief or short description. Use when the user wants to draft a design doc, technical proposal, or one-pager for an engineering review.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["architecture-diagrams"],
+  "tags": ["design-doc", "documentation", "engineering", "review"],
+  "model": { "tier": "standard", "rationale": "Synthesizes a design doc from a brief. Escalates to opus on big or genuinely contested inputs." }
+}

package/skills/design-doc/templates/design-doc.md

@@ -0,0 +1,98 @@
+# {Title — what we're building, as a noun phrase}
+
+| Field | Value |
+|---|---|
+| Status | {Draft / In Review / Approved / Implemented} |
+| Author(s) | {Names} |
+| Reviewers | {Names — list the people whose approval you need} |
+| Date | {YYYY-MM-DD} |
+| Related | {Links to ADRs, prior design docs, tickets} |
+
+## TL;DR
+
+- {One bullet — what we're doing}
+- {One bullet — why now}
+- {One bullet — what changes for callers / users}
+
+## Context
+
+{Two or three paragraphs. What's the current state? What's the forcing function? Why is this design doc happening *now* rather than 6 months ago or in 6 months?}
+
+## Goals
+
+- {Goal — measurable where possible: "p99 latency under 100ms"}
+- {Goal}
+- {Goal}
+
+## Non-goals
+
+- {Non-goal — something a reasonable reader might assume is in scope but isn't, e.g. "migrating existing customers' historical data"}
+- {Non-goal}
+
+## Proposal
+
+{The actual design. This is the largest section. Cover:}
+
+### High-level architecture
+
+{Embed a Mermaid or PlantUML diagram showing the major components and data flow. Keep it under 15 nodes.}
+
+```mermaid
+flowchart LR
+    A[Component A] --> B[Component B]
+    B --> C[(Store)]
+```
+
+### Key design decisions
+
+- **{Decision 1}:** {What we chose and the one-line why.}
+- **{Decision 2}:** {What we chose and the one-line why.}
+- **{Decision 3}:** {What we chose and the one-line why.}
+
+### API / interface
+
+{For each new or changed endpoint, show a small example. Don't dump the OpenAPI spec — point to it instead.}
+
+### Data model changes
+
+{Schema changes, migrations needed, backfill plan.}
+
+## Alternatives considered
+
+### {Alternative 1}
+
+{2–3 sentences: what it is, why we didn't pick it.}
+
+### {Alternative 2}
+
+{2–3 sentences.}
+
+## Risks & mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| {Risk — e.g. "migration script takes longer than the maintenance window"} | M | H | {Mitigation — e.g. "rehearse on prod-shape staging; have a no-op rollback path"} |
+| {Risk} | L | H | {Mitigation} |
+
+## Rollout plan
+
+1. **{Phase} — {behind feature flag, internal only}:** {Concrete criteria for advancing to next phase, e.g., "no new errors in error budget for 48h"}
+2. **{Phase} — {1% of traffic}:** {Criteria}
+3. **{Phase} — {10% / 50% / 100%}:** {Criteria}
+
+**Rollback criteria:** {When do we revert? Be specific.}
+
+## Observability
+
+- **New metrics:** {what we'll instrument}
+- **New alerts:** {pages on what conditions}
+- **Dashboard:** {link, or "TBD before launch"}
+
+## Open questions
+
+- **{Question}** — owner: {name}, due: {date}
+- **{Question}** — owner: {name}, due: {date}
+
+## Appendix
+
+{Optional — link out to longer materials. Don't inline. Common contents: benchmarks, full schema diffs, security review notes.}

package/skills/devils-advocate/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: devils-advocate
+description: Adversarial review of just-generated code, run *after* an agent (or human) declares a feature done. Challenges the implementation through four lenses — edge cases the first pass missed, baked-in assumptions that won't survive future requirements, what a staff engineer would push back on in code review, and test-coverage gaps for the new code paths. Produces severity-tagged findings (blocker / major / minor / nit) with file:line evidence and concrete fixes or missing test cases. Use immediately after a feature implementation or generation pass — before merging, before declaring "done", before moving to the next ticket.
+---
+
+# devils-advocate
+
+You play the role of a **senior engineer in code review who is trying to find what the implementation missed**. Code that "works on the happy path" is the default state of newly-generated code — your job is to challenge it through four lenses and surface what the first pass didn't think about.
+
+This skill is the **code counterpart to [`doc-critique`](../doc-critique/SKILL.md)** — same adversarial framing, applied to code instead of artifacts.
+
+## When this skill runs
+
+The trigger is **right after an agent (or human) has declared a feature done**. The implementation exists, the happy path likely works, tests may even pass — and that's exactly the moment the skill is most useful, because that's the moment everyone stops looking.
+
+Specifically:
+- ✅ After AI code generation for a feature ("here's the implementation")
+- ✅ Before opening a PR / before requesting human review
+- ✅ Before merging
+- ✅ When the user asks "anything I might have missed?" or "is this ready to ship?"
+- ❌ For a one-line fix or trivial change — overkill
+- ❌ For greenfield exploration / spikes — adversarial review wastes effort on code that will be thrown away
+- ❌ As a substitute for actual code review by a human — this is a *pre-pass*, not a replacement
+
+## How to respond
+
+1. **Identify the change under review.** In order of preference:
+   - The agent / user has just shown you a diff — review that diff.
+   - Git working tree has unstaged changes — `git diff` is the scope.
+   - User points to specific files / a PR / a recent commit — that's the scope.
+   - User says "the feature I just built" with no diff — ask which files, or run `git diff HEAD~1` if a commit was just made.
+
+   **Don't review the whole repo.** The scope is the *just-generated* code. Touched files only.
+
+2. **Classify the code shape.** What you challenge depends on what was built. Map to one or more:
+
+   | Shape | Lens emphasis |
+   |---|---|
+   | HTTP / RPC endpoint, API handler | edge-cases (input validation, auth), adversarial (rate limit, error mapping) |
+   | Async handler / queue consumer | edge-cases (retries, idempotency, poison messages), future-proofing (ordering) |
+   | DB migration / schema change | future-proofing (rollback, online-safe), adversarial (locking, big-table risk) |
+   | State machine / workflow | edge-cases (impossible transitions, concurrent updates) |
+   | Parser / data transformation | edge-cases (malformed, encoding, huge inputs) |
+   | CLI tool / script | edge-cases (missing flags, env, partial runs) |
+   | UI component | edge-cases (loading/empty/error states, a11y) |
+   | Background job / cron | edge-cases (overlap, missed runs, partial completion) |
+   | Library / pure function | edge-cases (boundary inputs), future-proofing (API stability) |
+   | Config / infra change | adversarial (blast radius), future-proofing (drift) |
+
+   Multiple shapes is common — a PR can be "endpoint + migration + UI." Apply each lens to the right slice.
+
+3. **Sweep the four lenses in order.** Each lens has its own checklist — read it, apply it, write findings. Don't merge lenses; each surfaces a different category of risk.
+
+   | Lens | File | Asks |
+   |---|---|---|
+   | 1. Edge cases | [`lenses/edge-cases.md`](lenses/edge-cases.md) | What inputs / states / timings break this? |
+   | 2. Future-proofing | [`lenses/future-proofing.md`](lenses/future-proofing.md) | What assumptions won't survive the next 6 months? |
+   | 3. Adversarial review | [`lenses/adversarial-review.md`](lenses/adversarial-review.md) | What would a staff engineer push back on in review? |
+   | 4. Test coverage | [`lenses/test-coverage.md`](lenses/test-coverage.md) | Which new code paths have no test, and which scenarios are missing tests? |
+
+4. **Categorize every finding by severity:**
+
+   | Severity | Meaning |
+   |---|---|
+   | 🟥 **Blocker** | This will ship a bug or a security issue. Examples: SQL injection, unhandled `null`, race condition on shared state, migration that locks a 10M-row table, missing auth check, infinite retry loop. |
+   | 🟧 **Major** | This will hurt within months. Examples: hard-coded limits that 2× growth will hit, no idempotency on a retryable operation, error swallowed silently, no observability for a load-bearing path, magic constants. |
+   | 🟨 **Minor** | Good craft. Examples: missing edge-case test, suboptimal log level, naming that won't age well, a comment that explains *what* instead of *why*. |
+   | ⚪ **Nit** | Style, formatting, micro-preference. Optional. |
+
+   When in doubt between two severities, **downgrade**. Inflated severity makes the report unreadable. If your output has more blockers than major findings, you're inflating.
+
+5. **For every finding, write four parts:**
+
+   - **Where:** `file:line` (e.g. `src/api/checkout.ts:47`) — and quote 5–15 chars of the offending line.
+   - **What's wrong:** one sentence — which lens fired and why.
+   - **Concrete scenario:** ✅ "When `discount=null` reaches line 47, `applyDiscount` throws `TypeError`." — ❌ "Doesn't handle null." A scenario the first pass can reproduce.
+   - **Fix:** ✅ "Add `if (discount == null) return 0;` at the top of `applyDiscount` — or thread the null through to skip the line item entirely (preferred — see how `applyTax` handles it at line 102)." — ❌ "Add null handling."
+
+6. **Open with a verdict, not the findings.** First thing the user sees:
+
+   ```
+   Verdict: SHIP WITH FIXES — 2 blockers, 5 major, 4 minor, 3 nits.
+
+   The endpoint validates auth and the happy path but doesn't bound the request body (blocker — DoS via 1GB payload), and the new migration adds a NOT NULL column without a default on a table the migration script doesn't backfill (blocker — will fail on first deploy). Of the 5 major findings, 3 are around idempotency on the retry path. Test coverage misses the new error branches at api/checkout.ts:71–88 entirely.
+   ```
+
+   Verdicts: `SHIP IT` · `SHIP WITH FIXES` · `DO NOT MERGE` · `RECONSIDER APPROACH`. The last is for when the implementation works but solved the wrong problem (e.g. building a custom retry queue when the framework already has one).
+
+7. **Output structure** — use [`templates/challenge.md`](templates/challenge.md):
+
+   ```markdown
+   # Devil's advocate: {feature name / PR title}
+   _Scope: {N files, M lines changed} · Reviewed: {YYYY-MM-DD}_
+
+   ## Verdict
+   {one-liner} — {N} blocker · {N} major · {N} minor · {N} nit
+   {3-sentence summary, lead with the worst}
+
+   ## Findings by lens
+
+   ### 1. Edge cases
+   ### 2. Future-proofing
+   ### 3. Adversarial review
+   ### 4. Test coverage
+
+   ## What's solid
+   - {2–4 things the implementation got right — not flattery, real patterns to preserve}
+
+   ## Suggested order to address
+   1. Fix blockers
+   2. Add the missing tests in §4 (they double as regression catches)
+   3. Major findings in priority order
+   ```
+
+8. **End with "what's solid"**, not more criticism. The user (or the next agent) often needs to know what to *keep* and what *patterns to reuse* elsewhere in the change.
+
+## Quality bar
+
+- **Every finding has a reproducible scenario.** A senior engineer reading the finding should be able to reproduce the bug or violation in their head. "Doesn't handle null" is not a finding; "When `discount=null` reaches line 47, …" is.
+- **Severity is calibrated.** More blockers than major ⇒ inflating ⇒ demote.
+- **Findings cite `file:line`.** Reviewers must be able to jump to the spot. Section names aren't enough for code.
+- **Fixes are concrete and paste-able where possible.** When you can suggest a one-line patch, do; when you can't, suggest the *approach* in one sentence — not "improve error handling."
+- **Don't redesign.** This isn't your chance to push a different architecture. Stay in the lane of "given this approach, what's missing." If the approach itself is wrong, that's a single `RECONSIDER APPROACH` verdict, not a wholesale rewrite suggestion.
+- **Test-coverage findings reference scenarios, not files.** ❌ "No test for `applyDiscount`." ✅ "No test covers `applyDiscount(null)` — add a case that asserts the function returns 0 (or skips) without throwing."
+
+## When NOT to use this skill
+
+- ❌ For greenfield prototype / spike code that's about to be thrown away.
+- ❌ For one-line / trivial changes — overkill, and the noise drowns out real signal.
+- ❌ As a substitute for human code review — it's a pre-pass, not a replacement.
+- ❌ For *evaluating the choice of approach* before code exists. That's a design conversation, not a code challenge. Use `design-doc` + `doc-critique` for that loop.
+- ❌ For generated code in a language you can't reason about line-by-line. Better to refuse than fabricate findings.
+
+## Anti-patterns to avoid
+
+- ❌ **Severity inflation.** If everything is a blocker, the report is unreadable. Most findings are major or minor.
+- ❌ **Vague findings.** "Handle errors better" / "Consider edge cases" — the whole point of this skill is to *name* the missed cases. If you can't name a specific scenario, drop the finding.
+- ❌ **Restating the lens.** ❌ "Code should be future-proof." ✅ "Hard-coded 100ms timeout on line 53 won't survive p99 growth — make it configurable."
+- ❌ **Lecturing on style** when there's a real bug to flag. Style notes go in the Nits section, not on top.
+- ❌ **Reviewing untouched code.** Out-of-scope. The skill challenges the *change*, not the codebase.
+- ❌ **Demanding tests for *everything* the change touches.** Only the new logic and new error paths. Don't insist on backfilling tests for previously-untested neighbouring code.
+- ❌ **Skipping "what's solid".** Trains the user (or downstream agent) to dread the skill. End on signal that's actionable in the other direction.

package/skills/devils-advocate/lenses/adversarial-review.md

@@ -0,0 +1,88 @@
+# Lens 3: Adversarial — what would a staff engineer push back on?
+
+The question this lens asks: **if a senior engineer who didn't write this code reviewed it cold, what would they object to — even if it works today?**
+
+This is the lens for the things that don't fail tests but fail in practice. Concurrency, error handling, security, observability, blast radius.
+
+---
+
+## Concurrency & ordering
+
+- **Read-modify-write without a lock or compare-and-swap.** Two callers, both read X, both increment, both write — one update is lost.
+- **Critical section that spans an `await` / I/O.** Lock not held across the await, or lock held *during* a slow I/O call (blocks everyone else).
+- **Shared mutable state in a request-handler scope** (e.g. a module-level dict that handlers mutate).
+- **Ordering assumption between async operations** with no explicit synchronization. "It works in my testing" because the race window is small.
+- **Cancellation not propagated.** Context cancelled but downstream call still runs to completion, holding resources.
+- **Goroutine / task leak.** Spawned, never awaited, never cancelled.
+
+## Error handling
+
+- **Caught and swallowed.** `try { … } catch {}` with no log, no rethrow. Errors disappear into the void.
+- **Logged and continued** when the operation should have failed. The user sees success; the system did nothing.
+- **Generic catch hiding specific errors.** Catching `Exception` / `error` when only one specific case is recoverable.
+- **Error message leaks internals** to the user (stack trace, SQL, file paths).
+- **Wrong abstraction in the error.** Internal `RecordNotFound` surfaces as 500 instead of 404. Or vice versa.
+- **No distinction between retriable and terminal errors.** Caller can't tell whether to back off and retry, or to give up.
+- **Cleanup not in `finally`.** Resource leaked when an exception fires partway through.
+
+## Security
+
+- **Input concatenated into SQL / shell / URL** instead of parameterized. Even if the input "shouldn't be untrusted."
+- **Authorization check missing or in the wrong layer.** Authn ≠ Authz. A logged-in user accessing another user's resource by changing an ID.
+- **Insecure direct object reference.** IDs in URLs / payloads accepted at face value with no ownership check.
+- **Secrets in code, in config, in logs.** Including ones that look "innocent" — internal hostnames, employee names.
+- **TLS verification disabled** (`rejectUnauthorized: false`, `verify=False`) — usually a copy-paste from a debug session.
+- **Cryptographic primitives used wrong.** MD5/SHA1 for password hashing, ECB mode, IV reused, randomness from a non-CSPRNG.
+- **Open redirect.** User-controlled URL passed to a redirect with no allowlist.
+- **No CSRF protection** on a state-changing endpoint, in a session-cookie-auth app.
+- **Logging PII / secrets.** Email, name, token, API key, full request body in an info-level log.
+
+## Observability
+
+- **Load-bearing path with no log.** When this fails in prod, nothing in the logs will explain why.
+- **Log without correlation.** No request ID, no trace ID, no tenant ID — can't tie events together.
+- **Wrong log level.** Recoverable error at `error` (alerts), or unrecoverable at `info` (lost in noise).
+- **No metric on the new operation.** Latency, count, error rate. If you can't measure it, you can't run it.
+- **Span / trace doesn't cover the new code.** Distributed tracing has a hole.
+- **Alert without a runbook entry.** When this fires, the on-caller has no documented response.
+
+## Blast radius
+
+- **Change touches a shared utility** without considering all callers.
+- **Migration / change applies to all rows / tenants** when it should be gated by feature flag.
+- **No feature flag** when the change is risky and a rollback would otherwise require a redeploy.
+- **Big bang deploy** of a multi-system change instead of staged.
+- **Backwards-incompatible event / API change** with no consumer coordination.
+
+## Build, dependency, and supply chain
+
+- **New dependency added.** Is it maintained? License compatible? Subdependency tree audited? Pinned to a major version?
+- **Pinned to a vulnerable version** of an existing dependency.
+- **`postinstall` script** in a new dependency that runs arbitrary code.
+- **`curl | bash` install steps** in a Dockerfile or CI config.
+
+## Test smells
+
+- **Test that doesn't actually assert.** Calls the function and checks nothing.
+- **Test that mocks the thing under test.** Mocks itself out of any real verification.
+- **Test that's coupled to the implementation** rather than the behaviour — fragile and slows down refactoring.
+- **Test that's flaky** — passes locally, fails in CI 1 in 10 runs. Disable + ticket, don't ignore.
+- **Test data with hard-coded "today"** — fails on a specific future date.
+
+## Naming, comments, and structure
+
+- **Name that lies.** `getUser` that also creates one if missing. `parse` that also mutates the input. `validate` that also sanitizes.
+- **Comment that explains what the code does** (the code already does that) instead of *why*.
+- **Comment that's now wrong** because the code changed but the comment didn't.
+- **Dead code committed.** `// TODO: remove this` from 2022.
+- **Function that's doing two unrelated things** stitched together by a flag parameter.
+
+## Reconsider-approach signals
+
+When you see *several* of these together, the verdict isn't "fix these findings" — it's `RECONSIDER APPROACH`:
+
+- Reimplementing a primitive the framework / language provides (custom retry, custom cache, custom thread pool).
+- Manual concurrency primitives where a higher-level abstraction exists (raw goroutines + channels when the language has `errgroup`; `setTimeout` polling when a proper queue would do).
+- Several `if (env === 'X')` branches in business logic.
+- Rolling your own auth / crypto / parsing for a well-known format.
+- Code that essentially re-implements what a vendor library already does.

package/skills/devils-advocate/lenses/edge-cases.md

@@ -0,0 +1,95 @@
+# Lens 1: Edge cases the first pass missed
+
+The question this lens asks: **what inputs, states, or timings break this code?**
+
+Apply the relevant subsection based on what the change is. Don't enumerate every check — pick the ones that *match the change shape* and have a real chance of biting.
+
+---
+
+## Universal (always check)
+
+- **Null / undefined / missing.** For each parameter and field accessed: what happens when it's missing, null, undefined, `None`, `nil`, empty string, empty array, empty object, zero, `NaN`?
+- **Boundary values.** Min, max, min−1, max+1, 0, −1, exactly-the-limit. For collections: empty, one, max-size, max-size+1.
+- **Type confusion.** Number as string, string as number, ISO date as Unix timestamp, array as object. If the language is dynamically typed, this matters more.
+- **Encoding.** Unicode (emoji, RTL, combining chars), URL-encoded vs decoded, base64, escaped vs raw, BOM in input files, mixed line endings.
+- **Locale.** Comma vs period for decimals, timezone-naive dates, day-of-week assumptions, ordering by locale-aware sort.
+- **Concurrency.** Two calls at once, the same call twice (idempotency), read-modify-write without a lock, optimistic locking ignored.
+- **Time.** DST transitions, leap seconds (rare), clock skew, monotonic vs wall clock, "now()" called twice in same operation giving different values, expiry that crosses a boundary.
+- **Partial failure.** What if the first half of the operation succeeds and the second fails? Where's the rollback / retry / dead-letter?
+
+## HTTP / RPC endpoint
+
+- **Auth.** Missing token, expired token, valid-but-wrong-user token, malformed header, token for a different tenant.
+- **Authorization.** User authenticated but not authorized (different question from "logged in").
+- **Input validation.** Body too large, body empty, body with extra fields, missing required field, wrong content-type, malformed JSON, deeply nested JSON, JSON with `__proto__` / prototype pollution.
+- **Method / route.** What if called with GET when POST expected? Trailing slash. Path traversal in path params.
+- **Concurrency.** Same user makes 10 identical requests in parallel.
+- **Idempotency.** If this can be retried by a client or proxy, is the second call safe?
+- **Rate-limit / DoS.** Unbounded loop on user input, unbounded recursion, unbounded resource allocation tied to a request param.
+
+## Async handler / queue consumer
+
+- **At-least-once semantics.** Same message twice. Is the operation idempotent on a key?
+- **Out-of-order delivery.** Message B arrives before message A. Does logic still hold?
+- **Poison messages.** Malformed payload that throws inside the handler — does the system DLQ it or retry forever?
+- **Retry storms.** Failure causes immediate retry causes cascading retries causes thundering herd.
+- **Backpressure.** Slow downstream. Queue grows unbounded. Does the handler shed load?
+
+## Database / migration
+
+- **Locking.** `ALTER TABLE` on a large table without `CONCURRENTLY` (Postgres) or equivalent — locks reads/writes during deploy.
+- **Backfill.** `ADD COLUMN NOT NULL` without a default on an existing populated table — fails or locks.
+- **Rollback.** Is the migration reversible? If not, is that explicit and documented?
+- **Online-safety.** Will old app code break against the new schema during the rolling deploy? (Add column → backfill → switch reads → drop old column — multi-step migrations.)
+- **Index creation.** Without `CONCURRENTLY` — locks writes.
+- **FK constraints added after data exists.** Will scan the whole table.
+
+## Parser / data transformation
+
+- **Huge inputs.** 1GB file, 1M-row CSV, deeply nested JSON, malicious zip (zip bomb).
+- **Malformed inputs.** Truncated, corrupted, wrong encoding, mixed encodings within one file.
+- **Untrusted inputs.** Input is from a user — what if it's hostile? Path traversal, command injection, format-string attacks.
+- **Streaming vs batch.** Does the code load everything into memory? Should it stream?
+- **Numeric precision.** Float arithmetic on money, large integers in JSON (JavaScript loses precision past 2^53), trailing zeros stripped.
+
+## State machine / workflow
+
+- **Impossible transitions.** Can the state graph reach state X from state Y in a single hop? Should it? What if it does?
+- **Concurrent updates to the same entity.** Two callers move it from A → B and A → C simultaneously.
+- **Skipped intermediate states.** Cleanup hooks that depend on visiting state Z get skipped.
+- **Terminal states.** Once in `cancelled` / `failed`, can the entity be re-opened? Should it?
+- **Replay.** What happens if the workflow is re-triggered from the beginning?
+
+## UI component
+
+- **Loading state.** Is there one, and does it appear before the data?
+- **Empty state.** Zero items — does the UI break or show something useful?
+- **Error state.** API call fails — does the user see a message or a blank page?
+- **Slow state.** API takes 8 seconds — does the UI lock up, or stay responsive?
+- **Long content.** Names with 80 characters, descriptions with 5,000. Does layout break?
+- **Internationalization.** RTL languages flipping the layout, longer translations overflowing buttons.
+- **Accessibility.** Keyboard nav, screen reader labels, focus traps, contrast.
+- **Mobile / small viewport.** Below 320px wide.
+
+## Background job / cron
+
+- **Overlap.** Job takes longer than its interval — does it overlap with the next run?
+- **Missed runs.** System down at scheduled time — does the next run catch up, or skip?
+- **Partial completion.** Crash halfway through — is the next run idempotent?
+- **Time zone.** "Run at midnight" — whose midnight?
+- **Drift.** Long-running periodic that takes longer over time as data grows.
+
+## CLI tool / script
+
+- **Missing args.** Required flag not passed.
+- **Stdin not a TTY** (running in CI, piped from another command).
+- **Env var missing or empty string.**
+- **Partial run interrupted by Ctrl-C.** Is the file half-written? Is there a cleanup?
+- **Non-zero exit codes** for each error path (CI scripts depend on these).
+
+## Library / pure function
+
+- **API stability.** Public surface change — does it break callers?
+- **Default values.** Sensible? Or surprising?
+- **Side effects.** Pure function actually pure? Or does it mutate inputs / hit the network / read the clock?
+- **Thread safety.** If callable from multiple threads, is shared state protected?

package/skills/devils-advocate/lenses/future-proofing.md

@@ -0,0 +1,75 @@
+# Lens 2: Future-proofing — assumptions that won't survive 6 months
+
+The question this lens asks: **what assumptions are baked into this code that will hurt when something predictable changes?**
+
+This is not "design for every hypothetical." It's "the obvious next requirements will break this." Flag only assumptions whose violation is *likely* within a year — not theoretical.
+
+---
+
+## Scale assumptions
+
+- **Hard-coded limits.** `LIMIT 100`, `for (i = 0; i < 1000; i++)`, `maxResults = 50`. What happens at 2× current scale? 10×?
+- **In-memory accumulation.** Loading the whole result set into a list, holding it, then processing. Will it OOM at next year's data volume?
+- **Unbounded growth.** A list / map / queue with no eviction. Will memory grow forever?
+- **N+1 queries.** Loop calls the DB per iteration. Fine at 10 items, dead at 10,000.
+- **Synchronous calls in a hot path.** Add three more downstream services and the latency stacks.
+
+## Tenancy assumptions
+
+- **Single-tenant baked in.** No `tenant_id` / `org_id` / `workspace_id` threaded through. Will be a multi-week refactor when multi-tenancy lands.
+- **Global state.** Caches keyed only by user/id, no tenant scope.
+- **Per-user limits where per-tenant is needed** (or vice versa).
+- **Email / username uniqueness assumed globally** rather than per-tenant.
+
+## Identity / ownership assumptions
+
+- **Hard-coded user / account / org IDs.** `if (orgId === 'acme-corp')`. Will rot the moment Acme renames.
+- **"Admin" as a single role** when next year wants RBAC with custom roles.
+- **API keys with no rotation path.** What's the story when one leaks?
+- **Auth provider baked into business logic.** Migrating providers means rewriting business code.
+
+## Data / schema assumptions
+
+- **Enum hard-coded in code** when next year wants user-configurable values.
+- **Boolean flag** that becomes a tri-state (`yes / no / pending`) or n-state.
+- **JSONB blob** with no versioning — when its shape evolves, old rows can't be read or written without compat shims.
+- **Foreign key to a "single source of truth"** that's about to become federated.
+- **Timestamps without timezone** (`TIMESTAMP` instead of `TIMESTAMPTZ`).
+- **Money as float** instead of integer cents or arbitrary-precision decimal.
+- **Strings where structured data belongs** (comma-separated IDs in a single column).
+
+## Integration assumptions
+
+- **Sync calls to an external API** that has a documented async option (webhooks, batch).
+- **No retry / no circuit breaker** around external calls.
+- **No timeout** on external calls (default is "wait forever").
+- **Tight coupling to a vendor's response shape** with no anti-corruption layer.
+- **Tight coupling to a vendor's identifier scheme** (using Stripe customer ID as primary key).
+
+## Configurability / observability
+
+- **Magic constants** that should be configurable (`100ms timeout`, `5 retries`, `7 days expiry`). At minimum, named constants; better, env-driven.
+- **Hard-coded environment** (`if (process.env.NODE_ENV === 'production')` scattered in business logic).
+- **No structured logging** on the new path — when this code misbehaves in prod, how will you debug?
+- **No metric / no trace** for a load-bearing operation. Future you will be flying blind.
+- **Errors logged but not categorized** — can't alert on the dangerous ones without alerting on every error.
+
+## Compatibility / migration
+
+- **Breaking change to a public API** without a deprecation path.
+- **No versioning** on an external interface (REST endpoint, event schema, gRPC service).
+- **Removed field still referenced by callers** — coordinate with consumers or stage the change.
+- **Migration that's not safe to run on both old and new app code** during a rolling deploy.
+
+## Lifecycle / cleanup
+
+- **Resource created without a cleanup path.** New S3 bucket, new DB record, new background job — what removes them?
+- **TTL not set on cache entries.** They live forever, including stale data.
+- **Soft-delete column added but no compaction strategy.** Table grows forever.
+- **Cron job with no off-switch.** Disabling requires a deploy.
+
+## What this lens is NOT for
+
+- ❌ "Design for 100M users when we have 100." Flag what's *likely* to change, not what's *possible* to change.
+- ❌ "Add an interface in case we want to swap implementations." YAGNI applies; only flag if the swap is on the roadmap.
+- ❌ Aesthetic refactors. If it's not going to break under foreseeable load / change, it's not in scope here.

package/skills/devils-advocate/lenses/test-coverage.md

@@ -0,0 +1,90 @@
+# Lens 4: Test-coverage gap analysis
+
+The question this lens asks: **for the code paths just introduced, which scenarios have no test?**
+
+This is not about hitting a coverage percentage. It's about which *new* branches, error paths, and edge cases ship with no automated check that future changes don't regress them.
+
+---
+
+## Scope rule
+
+- Test the **new code paths only.** Don't demand tests for previously-untested neighbouring code.
+- Test the **error and edge branches**, not just the happy path. The happy path is usually the one already tested.
+- Test the **boundaries**, not the interior. (Empty list and one-item list catch more than 5-item list.)
+
+## How to read the change
+
+1. **Identify the new branches.** Every `if`, `switch`, `try`, `?.`, default param, conditional return introduced in the diff is a branch. Each one is a coverage candidate.
+2. **Identify the new error paths.** Every `throw`, `return Err(…)`, `panic`, every `catch` block. Each is a candidate.
+3. **Identify the new public surface.** New function exported, new endpoint, new event handler, new CLI flag. Each public entry point needs at least one test from outside.
+4. **Identify the new integration points.** New external API call, new DB query, new file I/O. Each needs either an integration test or a mocked unit test with realistic responses (including failure responses).
+
+## What to flag as a missing test
+
+For each missed scenario, write a finding like:
+
+> **Missing test:** `applyDiscount(null)` — assert returns 0 (or skips) without throwing.
+> **Suggested location:** `src/checkout/__tests__/applyDiscount.test.ts` (same dir pattern as siblings).
+> **Severity:** 🟧 major — null input is reachable from the public endpoint (`api/checkout.ts:47`).
+
+### Default checklist of "must-have" scenarios
+
+For every new function with parameters:
+
+- **Happy path** — at least one test exists. (Usually it does. If not, that's a blocker.)
+- **Empty input** — empty string, empty list, empty object, null, undefined.
+- **Boundary** — min, max, off-by-one.
+- **Error path** — explicit error / exception cases, each.
+
+For every new endpoint:
+
+- 200 happy path.
+- 4xx for missing required field.
+- 4xx for invalid auth (if endpoint requires auth).
+- 4xx for valid auth + wrong user (authorization).
+- 5xx response shape if downstream fails (or graceful degradation, whichever the design specifies).
+
+For every new async handler / queue consumer:
+
+- Successful processing of a valid message.
+- Idempotency — same message processed twice produces same outcome.
+- Malformed message — DLQ'd, not retried infinitely.
+
+For every new migration:
+
+- Forward migration applied on a non-empty seed DB.
+- Backward migration restores schema (if reversible).
+- Behaviour against *both* old and new app code if doing a multi-stage migration.
+
+For every new state-machine transition:
+
+- The valid transition itself.
+- The invalid-transition rejection (state A → state Z when not allowed).
+
+For every new UI component:
+
+- Renders with realistic props.
+- Renders with empty data.
+- Renders with error state.
+- Renders with loading state.
+- (Interaction tests where the component has interactive behaviour.)
+
+## What to flag as a test SMELL (not missing — wrong)
+
+- **Asserts nothing.** Calls the function but doesn't check the return value or side effect.
+- **Mocks itself out of the test.** All collaborators mocked including the unit under test, or the mock makes the test pass trivially.
+- **Tautological assertion.** `expect(x).toEqual(x)` — happens when an agent fabricates a test.
+- **Asserts the implementation, not the behaviour.** Test reads private fields or counts internal calls; brittle to refactor.
+- **Hard-codes a date that will fail in the future.** `expect(date).toEqual('2025-12-31')` baked into a test that runs every day.
+- **Flaky due to timing / ordering.** `setTimeout(…, 0)` to "let the event loop settle" — works locally, flakes in CI.
+- **Snapshot test on a noisy structure.** Snapshot includes timestamps, random IDs, or auto-generated keys — fails on every run.
+
+Flag a smelly test the same way you flag a missing one — note that the test exists but doesn't earn its keep, and suggest what it should actually assert.
+
+## What this lens is NOT for
+
+- ❌ Demanding tests for refactor-only changes that didn't add new behaviour.
+- ❌ Demanding tests in code that already lacks them (out of scope — only the diff).
+- ❌ Requiring 100% line coverage. Branches and edges matter; uncovered straightforward lines don't.
+- ❌ Insisting on a specific test framework / style.
+- ❌ Generating tests yourself. This lens *flags gaps* — the user (or the next agent in the loop) writes the tests, possibly by feeding the gap list back into a code-gen step.