@su-record/vibe 2.9.23 → 2.9.24

package/skills/claude-md-guide/rubrics/anti-patterns.md

@@ -1,88 +1,88 @@
-# CLAUDE.md Anti-Patterns
-
-## Anti-pattern 1: Discoverable Content
-
-**Symptom**: Listing things the agent can find by reading the repo.
-
-```markdown
-# Bad
-- Components are in src/components/
-- Uses React 18 with TypeScript
-- Run tests with npm test
-```
-
-```markdown
-# Good
-(delete these — they're in package.json and the repo structure)
-```
-
-## Anti-pattern 2: Instruction Overload
-
-**Symptom**: 300+ line CLAUDE.md full of best practices.
-
-LLM compliance drops to ~5% after 15+ instructions. Every line competes for attention.
-
-Fix: Keep under 150 lines. Move feature-specific rules to SPEC files.
-
-## Anti-pattern 3: Emphasis Inflation
-
-**Symptom**: IMPORTANT, CRITICAL, MUST on every other line.
-
-When everything is critical, nothing is. Reserve emphasis words for P1 rules only.
-
-## Anti-pattern 4: Past-Tense History
-
-**Symptom**: Phase tables, progress logs, "we decided to..." narratives.
-
-```markdown
-# Bad
-## Progress
-- Phase 1 ✅ Auth
-- Phase 2 ✅ Dashboard
-- Phase 3 🚧 Payments
-```
-
-This is context noise, not guidance. Delete it.
-
-## Anti-pattern 5: Technology Anchoring
-
-**Symptom**: Listing what you use instead of what to avoid.
-
-```markdown
-# Bad
-We use Zod for validation, Prisma for ORM, Tailwind for styling.
-```
-
-```markdown
-# Good
-Never use joi or yup — Zod is the only validation library.
-```
-
-Naming a technology biases the agent toward it. Only name tech in prohibitions.
-
-## Anti-pattern 6: Vague Prohibitions
-
-**Symptom**: Rules without specific triggers.
-
-```markdown
-# Bad
-- Write clean, readable code
-- Follow best practices
-- Keep functions small
-```
-
-The agent already knows these. They consume tokens and provide no new signal.
-
-## Anti-pattern 7: Missing Boundaries
-
-**Symptom**: No section on what the agent should never touch.
-
-Without explicit boundaries, agents will "helpfully" refactor generated files, edit lock files, or push to main.
-
-Always include: what's off-limits, what requires human approval first.
-
-## Anti-pattern 8: Stale Secrets/Keys
-
-**Symptom**: API keys or connection strings in CLAUDE.md.
-
-These belong in `.env` only. CLAUDE.md is committed to version control.
+# CLAUDE.md Anti-Patterns
+
+## Anti-pattern 1: Discoverable Content
+
+**Symptom**: Listing things the agent can find by reading the repo.
+
+```markdown
+# Bad
+- Components are in src/components/
+- Uses React 18 with TypeScript
+- Run tests with npm test
+```
+
+```markdown
+# Good
+(delete these — they're in package.json and the repo structure)
+```
+
+## Anti-pattern 2: Instruction Overload
+
+**Symptom**: 300+ line CLAUDE.md full of best practices.
+
+LLM compliance drops to ~5% after 15+ instructions. Every line competes for attention.
+
+Fix: Keep under 150 lines. Move feature-specific rules to SPEC files.
+
+## Anti-pattern 3: Emphasis Inflation
+
+**Symptom**: IMPORTANT, CRITICAL, MUST on every other line.
+
+When everything is critical, nothing is. Reserve emphasis words for P1 rules only.
+
+## Anti-pattern 4: Past-Tense History
+
+**Symptom**: Phase tables, progress logs, "we decided to..." narratives.
+
+```markdown
+# Bad
+## Progress
+- Phase 1 ✅ Auth
+- Phase 2 ✅ Dashboard
+- Phase 3 🚧 Payments
+```
+
+This is context noise, not guidance. Delete it.
+
+## Anti-pattern 5: Technology Anchoring
+
+**Symptom**: Listing what you use instead of what to avoid.
+
+```markdown
+# Bad
+We use Zod for validation, Prisma for ORM, Tailwind for styling.
+```
+
+```markdown
+# Good
+Never use joi or yup — Zod is the only validation library.
+```
+
+Naming a technology biases the agent toward it. Only name tech in prohibitions.
+
+## Anti-pattern 6: Vague Prohibitions
+
+**Symptom**: Rules without specific triggers.
+
+```markdown
+# Bad
+- Write clean, readable code
+- Follow best practices
+- Keep functions small
+```
+
+The agent already knows these. They consume tokens and provide no new signal.
+
+## Anti-pattern 7: Missing Boundaries
+
+**Symptom**: No section on what the agent should never touch.
+
+Without explicit boundaries, agents will "helpfully" refactor generated files, edit lock files, or push to main.
+
+Always include: what's off-limits, what requires human approval first.
+
+## Anti-pattern 8: Stale Secrets/Keys
+
+**Symptom**: API keys or connection strings in CLAUDE.md.
+
+These belong in `.env` only. CLAUDE.md is committed to version control.

package/skills/claude-md-guide/templates/claude-md.md

@@ -1,54 +1,54 @@
-# {{PROJECT_NAME}}
-
-{{OPTIONAL: 1-2 sentence description. Only if project purpose is unclear from reading the code.}}
-
-## Commands
-
-{{Only non-obvious commands. Delete commands already in package.json scripts.}}
-
-- `{{COMMAND}}` — {{WHY_ORDER_MATTERS_OR_SPECIAL_FLAGS}}
-
-## Conventions
-
-{{Only what linters/formatters don't enforce automatically.}}
-
-- {{CONVENTION}} — {{e.g., "ESM only — imports need .js extension"}}
-
-## Gotchas
-
-{{Non-discoverable traps an agent will hit without being told.}}
-
-- **{{TRAP_TITLE}}.** {{Specific do/don't description.}}
-- **{{TRAP_TITLE}}.** {{Specific do/don't description.}}
-
-## Boundaries
-
-{{What the agent should never touch or always ask about first.}}
-
-Always: {{ALWAYS_DO}}
-Ask first: {{ASK_BEFORE_DOING}}
-Never: {{ABSOLUTE_PROHIBITION}}
-
----
-
-<!--
-FILLING INSTRUCTIONS
-
-Size targets:
-- Small project (< 10 files): 20-30 lines
-- Medium project (10-50 files): 60-150 lines
-- Large project / monorepo: 100 lines root + 30 lines per package
-
-Placement priority (LLM attention is highest at top and bottom):
-- Top: most critical rules (security, never-do)
-- Middle: background context
-- Bottom: frequently violated rules
-
-For each line ask:
-1. Would the agent make a mistake without this? No → delete
-2. Does every session need this? No → move to SPEC or plan file
-3. Does a linter/hook enforce this? Yes → delete
-4. Is this discoverable from code? Yes → delete
-
-Delete this comment block before committing.
--->
+# {{PROJECT_NAME}}
+
+{{OPTIONAL: 1-2 sentence description. Only if project purpose is unclear from reading the code.}}
+
+## Commands
+
+{{Only non-obvious commands. Delete commands already in package.json scripts.}}
+
+- `{{COMMAND}}` — {{WHY_ORDER_MATTERS_OR_SPECIAL_FLAGS}}
+
+## Conventions
+
+{{Only what linters/formatters don't enforce automatically.}}
+
+- {{CONVENTION}} — {{e.g., "ESM only — imports need .js extension"}}
+
+## Gotchas
+
+{{Non-discoverable traps an agent will hit without being told.}}
+
+- **{{TRAP_TITLE}}.** {{Specific do/don't description.}}
+- **{{TRAP_TITLE}}.** {{Specific do/don't description.}}
+
+## Boundaries
+
+{{What the agent should never touch or always ask about first.}}
+
+Always: {{ALWAYS_DO}}
+Ask first: {{ASK_BEFORE_DOING}}
+Never: {{ABSOLUTE_PROHIBITION}}
+
+---
+
+<!--
+FILLING INSTRUCTIONS
+
+Size targets:
+- Small project (< 10 files): 20-30 lines
+- Medium project (10-50 files): 60-150 lines
+- Large project / monorepo: 100 lines root + 30 lines per package
+
+Placement priority (LLM attention is highest at top and bottom):
+- Top: most critical rules (security, never-do)
+- Middle: background context
+- Bottom: frequently violated rules
+
+For each line ask:
+1. Would the agent make a mistake without this? No → delete
+2. Does every session need this? No → move to SPEC or plan file
+3. Does a linter/hook enforce this? Yes → delete
+4. Is this discoverable from code? Yes → delete
+
+Delete this comment block before committing.
+-->

package/skills/commerce-patterns/SKILL.md

@@ -1,64 +1,64 @@
----
-name: commerce-patterns
-tier: core
-description: "E-commerce domain patterns — cart management, payment processing (Toss/Stripe/PG), inventory tracking, and order state machines with transaction safety. Use when implementing any shopping cart, checkout flow, payment integration, stock management, or order lifecycle. Covers idempotency keys, double-charge prevention, stock reservation, and refund flows. Must use this skill when the codebase involves e-commerce — even for seemingly simple 'add to cart' features."
-triggers: [commerce, ecommerce, cart, payment, checkout, inventory, stock, order, pg, toss, stripe]
-priority: 70
----
-
-# Commerce Patterns
-
-## Pre-check (K1)
-
-> Is this an e-commerce transaction flow? If building simple CRUD without payment/stock management, this skill is not needed.
-
-## Gotchas & Traps
-
-These are the non-obvious failure modes LLMs typically miss:
-
-### Payment
-
-| Trap | Consequence | Prevention |
-|------|-------------|------------|
-| No idempotency key | User double-clicks → charged twice | `idempotencyKey: order_${orderId}_${timestamp}` on every payment request |
-| Webhook not idempotent | Retry delivers duplicate events | Check `eventId` before processing, store processed events |
-| Missing webhook signature verification | Attacker forges payment confirmation | Always verify HMAC signature before processing |
-| No payment state machine | Order stuck in limbo | `PENDING → PROCESSING → AUTHORIZED → CAPTURED → COMPLETED` (+ FAILED, CANCELED, REFUNDED) |
-
-### Inventory
-
-| Trap | Consequence | Prevention |
-|------|-------------|------------|
-| Non-atomic stock decrement | Race condition → negative stock | `UPDATE SET stock = stock - $1 WHERE stock >= $1` (atomic with check) |
-| No reservation TTL | Stock locked forever on abandoned checkout | 15-min reservation + scheduled cleanup job |
-| Commit without reservation | Stock sold twice | Two-phase: RESERVE (checkout start) → COMMIT (payment success) / RELEASE (failure) |
-| Optimistic lock without retry | Fails silently under contention | Use `version` column or `FOR UPDATE` for high-contention products |
-
-### Cart & Pricing
-
-| Trap | Consequence | Prevention |
-|------|-------------|------------|
-| No price snapshot | Price changes between add and checkout | Store `price` at add time, revalidate at checkout entry |
-| No guest→user cart merge | Guest loses cart on login | Merge by `sessionId` on login, user cart takes priority for duplicates |
-| No cart expiration | Abandoned carts accumulate forever | TTL-based cleanup (e.g., 7 days) |
-
-## Checkout Flow (Reference)
-
-```
-Cart Validation → Order Creation (PENDING) → Stock Reservation (15min) → Payment
-  ├─ Success → Order PAID, Stock COMMIT, Send Confirmation
-  └─ Failure → Order FAILED, Stock RELEASE
-```
-
-## Related
-
-See `e2e-commerce` skill for test scenarios covering these patterns (P0 duplicate payment, stock release on failure, etc.).
-
-## Done Criteria (K4)
-
-- [ ] Idempotency key on all payment requests
-- [ ] Webhook handler is idempotent (dedup by eventId)
-- [ ] Stock updates are atomic (SQL-level check)
-- [ ] Two-phase reservation implemented with TTL
-- [ ] Prices snapshot at cart add, revalidated at checkout
-- [ ] Payment state machine covers all transitions
+---
+name: commerce-patterns
+tier: core
+description: "E-commerce domain patterns — cart management, payment processing (Toss/Stripe/PG), inventory tracking, and order state machines with transaction safety. Use when implementing any shopping cart, checkout flow, payment integration, stock management, or order lifecycle. Covers idempotency keys, double-charge prevention, stock reservation, and refund flows. Must use this skill when the codebase involves e-commerce — even for seemingly simple 'add to cart' features."
+triggers: [commerce, ecommerce, cart, payment, checkout, inventory, stock, order, pg, toss, stripe]
+priority: 70
+---
+
+# Commerce Patterns
+
+## Pre-check (K1)
+
+> Is this an e-commerce transaction flow? If building simple CRUD without payment/stock management, this skill is not needed.
+
+## Gotchas & Traps
+
+These are the non-obvious failure modes LLMs typically miss:
+
+### Payment
+
+| Trap | Consequence | Prevention |
+|------|-------------|------------|
+| No idempotency key | User double-clicks → charged twice | `idempotencyKey: order_${orderId}_${timestamp}` on every payment request |
+| Webhook not idempotent | Retry delivers duplicate events | Check `eventId` before processing, store processed events |
+| Missing webhook signature verification | Attacker forges payment confirmation | Always verify HMAC signature before processing |
+| No payment state machine | Order stuck in limbo | `PENDING → PROCESSING → AUTHORIZED → CAPTURED → COMPLETED` (+ FAILED, CANCELED, REFUNDED) |
+
+### Inventory
+
+| Trap | Consequence | Prevention |
+|------|-------------|------------|
+| Non-atomic stock decrement | Race condition → negative stock | `UPDATE SET stock = stock - $1 WHERE stock >= $1` (atomic with check) |
+| No reservation TTL | Stock locked forever on abandoned checkout | 15-min reservation + scheduled cleanup job |
+| Commit without reservation | Stock sold twice | Two-phase: RESERVE (checkout start) → COMMIT (payment success) / RELEASE (failure) |
+| Optimistic lock without retry | Fails silently under contention | Use `version` column or `FOR UPDATE` for high-contention products |
+
+### Cart & Pricing
+
+| Trap | Consequence | Prevention |
+|------|-------------|------------|
+| No price snapshot | Price changes between add and checkout | Store `price` at add time, revalidate at checkout entry |
+| No guest→user cart merge | Guest loses cart on login | Merge by `sessionId` on login, user cart takes priority for duplicates |
+| No cart expiration | Abandoned carts accumulate forever | TTL-based cleanup (e.g., 7 days) |
+
+## Checkout Flow (Reference)
+
+```
+Cart Validation → Order Creation (PENDING) → Stock Reservation (15min) → Payment
+  ├─ Success → Order PAID, Stock COMMIT, Send Confirmation
+  └─ Failure → Order FAILED, Stock RELEASE
+```
+
+## Related
+
+See `e2e-commerce` skill for test scenarios covering these patterns (P0 duplicate payment, stock release on failure, etc.).
+
+## Done Criteria (K4)
+
+- [ ] Idempotency key on all payment requests
+- [ ] Webhook handler is idempotent (dedup by eventId)
+- [ ] Stock updates are atomic (SQL-level check)
+- [ ] Two-phase reservation implemented with TTL
+- [ ] Prices snapshot at cart add, revalidated at checkout
+- [ ] Payment state machine covers all transitions

package/skills/commerce-patterns/rubrics/checkout-flow.md

@@ -1,48 +1,48 @@
-# Checkout UX Best Practices Checklist
-
-## Cart Review Step
-
-- [ ] Cart items show current price, quantity, and subtotal per line
-- [ ] Price change warning shown if item price changed since add-to-cart
-- [ ] Out-of-stock items flagged before user proceeds
-- [ ] Clear "Continue to Checkout" CTA — one primary action per step
-- [ ] Guest checkout option visible (no forced registration)
-
-## Shipping & Address Step
-
-- [ ] Address autocomplete reduces input friction
-- [ ] Saved addresses surfaced first for logged-in users
-- [ ] Shipping cost displayed before payment (no surprise at confirmation)
-- [ ] Estimated delivery date shown per shipping method
-- [ ] Address validation feedback inline, not on submit
-
-## Payment Step
-
-- [ ] Supported payment methods visible upfront (icons, labels)
-- [ ] Payment form uses browser autofill attributes (`autocomplete`)
-- [ ] Idempotency key bound to order ID — double-click safe
-- [ ] Loading state on submit button prevents double submission
-- [ ] Clear error messages distinguish user error from system error
-- [ ] PG redirect handles back-button recovery gracefully
-
-## Order Confirmation Step
-
-- [ ] Order ID prominently displayed (user can reference for support)
-- [ ] Confirmation email sent within 30 seconds of payment success
-- [ ] Summary includes: items, total, shipping address, estimated delivery
-- [ ] Clear next step (track order / continue shopping)
-- [ ] No personal payment data displayed (mask card number)
-
-## Error & Edge Cases
-
-- [ ] Stock exhausted mid-checkout: clear message, return to cart
-- [ ] Payment timeout: inform user, preserve order state for retry
-- [ ] Session expiry during checkout: preserve cart, redirect to login
-- [ ] Network failure on submit: prevent duplicate submission, show retry CTA
-
-## Accessibility & Performance
-
-- [ ] Checkout steps announced to screen readers (step X of Y)
-- [ ] Tab order logical through form fields
-- [ ] Core checkout flow works without JavaScript (progressive enhancement)
-- [ ] Page weight under 200 KB per step (no unnecessary third-party scripts)
+# Checkout UX Best Practices Checklist
+
+## Cart Review Step
+
+- [ ] Cart items show current price, quantity, and subtotal per line
+- [ ] Price change warning shown if item price changed since add-to-cart
+- [ ] Out-of-stock items flagged before user proceeds
+- [ ] Clear "Continue to Checkout" CTA — one primary action per step
+- [ ] Guest checkout option visible (no forced registration)
+
+## Shipping & Address Step
+
+- [ ] Address autocomplete reduces input friction
+- [ ] Saved addresses surfaced first for logged-in users
+- [ ] Shipping cost displayed before payment (no surprise at confirmation)
+- [ ] Estimated delivery date shown per shipping method
+- [ ] Address validation feedback inline, not on submit
+
+## Payment Step
+
+- [ ] Supported payment methods visible upfront (icons, labels)
+- [ ] Payment form uses browser autofill attributes (`autocomplete`)
+- [ ] Idempotency key bound to order ID — double-click safe
+- [ ] Loading state on submit button prevents double submission
+- [ ] Clear error messages distinguish user error from system error
+- [ ] PG redirect handles back-button recovery gracefully
+
+## Order Confirmation Step
+
+- [ ] Order ID prominently displayed (user can reference for support)
+- [ ] Confirmation email sent within 30 seconds of payment success
+- [ ] Summary includes: items, total, shipping address, estimated delivery
+- [ ] Clear next step (track order / continue shopping)
+- [ ] No personal payment data displayed (mask card number)
+
+## Error & Edge Cases
+
+- [ ] Stock exhausted mid-checkout: clear message, return to cart
+- [ ] Payment timeout: inform user, preserve order state for retry
+- [ ] Session expiry during checkout: preserve cart, redirect to login
+- [ ] Network failure on submit: prevent duplicate submission, show retry CTA
+
+## Accessibility & Performance
+
+- [ ] Checkout steps announced to screen readers (step X of Y)
+- [ ] Tab order logical through form fields
+- [ ] Core checkout flow works without JavaScript (progressive enhancement)
+- [ ] Page weight under 200 KB per step (no unnecessary third-party scripts)