@vibe-interviewing/scenarios 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-interviewing/scenarios",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Built-in interview scenarios for vibe-interviewing",
   "type": "module",
   "main": "./index.js",

package/patch-data-loss/scenario.yaml

@@ -124,4 +124,38 @@ evaluation:
     - 'Used AI effectively as a debugging partner'
   expected_fix: 'Restore the ternary in #updateOrPatchById: isPatch ? { ...item, ...body, id } : { ...body, id }'
 
+interviewer_guide:
+  overview: |
+    This scenario evaluates systematic debugging skills and HTTP semantics understanding.
+    The bug is subtle — PATCH was changed to behave like PUT, dropping fields not included
+    in the request body. Strong candidates reproduce first, read the source, and understand
+    the merge vs replace distinction. This also tests how candidates use AI as a debugging
+    partner rather than just asking it to find the bug.
+  key_signals:
+    - signal: 'Reproduces before fixing'
+      positive: 'Starts by sending curl requests to reproduce the data loss'
+      negative: 'Jumps straight into reading code or asks AI to find the bug'
+    - signal: 'Reads source code'
+      positive: 'Traces the request path through the codebase to find where updates happen'
+      negative: 'Relies entirely on AI to explain the code without reading it'
+    - signal: 'Understands HTTP semantics'
+      positive: 'Recognizes that PATCH should merge and PUT should replace'
+      negative: 'Treats PATCH and PUT as interchangeable or does not know the difference'
+    - signal: 'Critical evaluation of AI'
+      positive: 'Questions AI suggestions, verifies them against the actual code'
+      negative: 'Accepts the first AI suggestion without testing or reviewing'
+    - signal: 'Verifies the fix'
+      positive: 'Re-runs the reproduction steps to confirm the fix works'
+      negative: 'Applies a fix and considers it done without testing'
+  common_pitfalls:
+    - 'Asking AI to "find the bug" without investigating — shows over-reliance on AI'
+    - 'Fixing symptoms (e.g., adding a workaround in the route handler) instead of the root cause'
+    - 'Not understanding that the non-array #updateOrPatch method is NOT affected'
+    - 'Confusing the spread operator behavior — the fix is about restoring the existing item spread'
+  debrief_questions:
+    - 'Walk me through how you reproduced the issue. What requests did you try?'
+    - 'Can you explain the difference between how PATCH and PUT should behave?'
+    - 'How did you use AI during the debugging process? What worked well?'
+    - 'If you were reviewing a PR that introduced this bug, what would you look for?'
+
 license: MIT

package/storage-adapter-refactor/scenario.yaml

@@ -81,4 +81,38 @@ evaluation:
     - 'Made thoughtful design decisions about abstraction level'
     - 'Used AI effectively as an architecture partner'
 
+interviewer_guide:
+  overview: |
+    This scenario evaluates architectural thinking and incremental refactoring skills.
+    The candidate must decouple a tightly-coupled storage layer (lowdb) from the Service
+    class by introducing a clean interface. There is no single right answer — multiple
+    valid approaches exist. Focus on how the candidate reasons about abstraction boundaries,
+    makes trade-offs, and refactors incrementally without breaking existing behavior.
+  key_signals:
+    - signal: 'Identifies coupling points first'
+      positive: 'Maps out all places Service touches lowdb before writing any code'
+      negative: 'Starts coding the interface without understanding the existing dependencies'
+    - signal: 'Designs a minimal interface'
+      positive: 'Creates an interface with only the methods Service actually needs'
+      negative: 'Over-engineers with many generic methods, complex generics, or framework-like abstractions'
+    - signal: 'Refactors incrementally'
+      positive: 'Makes one change at a time and verifies the server still works after each step'
+      negative: 'Attempts a big-bang rewrite — changes everything at once and debugs the result'
+    - signal: 'Handles helper functions'
+      positive: 'Notices that embed/nullifyForeignKey/deleteDependents also access db.data and has a plan for them'
+      negative: 'Misses the helper functions entirely, leaving them broken after refactoring'
+    - signal: 'Uses AI as architecture partner'
+      positive: 'Discusses design trade-offs with AI, considers alternatives before committing'
+      negative: 'Asks AI to generate the entire refactoring without engaging in design decisions'
+  common_pitfalls:
+    - 'Over-engineering the interface with methods that are not needed (YAGNI violation)'
+    - 'Forgetting the helper functions (embed, nullifyForeignKey, deleteDependents) that also access db.data directly'
+    - 'Not verifying the server still works after refactoring — the server must pass the same curl tests'
+    - 'Creating a leaky abstraction where lowdb internals bleed through the interface'
+  debrief_questions:
+    - 'How did you decide what methods to put on the storage interface?'
+    - 'What trade-offs did you consider when designing the abstraction?'
+    - 'How did you handle the helper functions that also access the database directly?'
+    - 'If you had more time, what would you improve about your design?'
+
 license: MIT

package/webhook-notifications/scenario.yaml

@@ -125,4 +125,39 @@ evaluation:
     - 'Tested end-to-end with a webhook listener'
     - 'Used AI effectively as a development partner'
 
+interviewer_guide:
+  overview: |
+    This scenario evaluates feature design and integration skills. The candidate must build
+    a webhook notification system on top of an existing REST API. A key insight is that
+    json-server already handles CRUD for any resource in db.json — so the "webhooks" array
+    gives them registration for free. Strong candidates discover this quickly and focus their
+    effort on the notification delivery logic rather than rebuilding CRUD.
+  key_signals:
+    - signal: 'Discovers the free CRUD'
+      positive: 'Realizes json-server already handles /webhooks CRUD via the seeded array in db.json'
+      negative: 'Builds custom webhook registration routes from scratch, duplicating existing functionality'
+    - signal: 'Starts with core functionality'
+      positive: 'Gets basic webhook delivery working first, then adds filtering and error handling'
+      negative: 'Gets bogged down in edge cases (retries, backoff, ordering) before core delivery works'
+    - signal: 'Handles errors gracefully'
+      positive: 'Webhook delivery failures are caught and do not crash the server or block API responses'
+      negative: 'Unhandled promise rejections or synchronous delivery that blocks the response'
+    - signal: 'Tests end-to-end'
+      positive: 'Sets up a listener to verify webhook delivery, tests the full flow'
+      negative: 'Only tests registration without verifying actual delivery'
+    - signal: 'Clean integration'
+      positive: 'Hooks into existing codebase patterns (middleware, service methods) rather than bolting on'
+      negative: 'Adds webhook logic in awkward places that break separation of concerns'
+  common_pitfalls:
+    - "Building custom CRUD for webhooks instead of leveraging json-server's built-in resource handling"
+    - 'Making webhook delivery synchronous, which blocks the API response'
+    - 'Over-engineering retry logic and backoff strategies before basic delivery works'
+    - 'Not filtering notifications by resource — sending every event to every webhook'
+    - 'Forgetting to exclude the "webhooks" resource from triggering webhook notifications'
+  debrief_questions:
+    - 'How did you decide where to hook into the codebase for notification delivery?'
+    - 'Did you notice that json-server handles /webhooks CRUD automatically? How did that affect your approach?'
+    - 'How would you handle webhook delivery at scale if this were a production system?'
+    - 'What would you add if you had another 30 minutes?'
+
 license: MIT