claude-code-arcane 1.0.0

package/skills/brand-guidelines/references/brand-identity-and-framework.md

@@ -0,0 +1,262 @@
+# brand-guidelines reference
+
+## Anthropic Brand Identity
+
+### Overview
+
+Anthropic's brand identity is clean, precise, and intellectually grounded. It communicates trustworthiness and technical sophistication without feeling cold or corporate.
+
+### Color System
+
+**Primary Palette:**
+
+| Name | Hex | RGB | Use |
+|------|-----|-----|-----|
+| Dark | `#141413` | 20, 20, 19 | Primary text, dark backgrounds |
+| Light | `#faf9f5` | 250, 249, 245 | Light backgrounds, text on dark |
+| Mid Gray | `#b0aea5` | 176, 174, 165 | Secondary elements, dividers |
+| Light Gray | `#e8e6dc` | 232, 230, 220 | Subtle backgrounds, borders |
+
+**Accent Palette:**
+
+| Name | Hex | RGB | Use |
+|------|-----|-----|-----|
+| Orange | `#d97757` | 217, 119, 87 | Primary accent, CTAs |
+| Blue | `#6a9bcc` | 106, 155, 204 | Secondary accent, links |
+| Green | `#788c5d` | 120, 140, 93 | Tertiary accent, success states |
+
+**Color Application Rules:**
+- Never use accent colors as large background fills — use them for emphasis only
+- Dark on Light or Light on Dark — avoid mixing Dark on Mid Gray for body text
+- Accent colors cycle: Orange (primary CTA) → Blue (supporting) → Green (tertiary)
+- When in doubt, default to Dark + Light with one accent
+
+### Typography
+
+**Type Scale:**
+
+| Role | Font | Fallback | Weight | Size Range |
+|------|------|----------|--------|------------|
+| Display / H1 | Poppins | Arial | 600–700 | 32pt+ |
+| Headings H2–H4 | Poppins | Arial | 500–600 | 20–31pt |
+| Body | Lora | Georgia | 400 | 14–18pt |
+| Caption / Label | Poppins | Arial | 400–500 | 10–13pt |
+| Code / Mono | Courier New | monospace | 400 | 12–14pt |
+
+**Typography Rules:**
+- Never set body copy in Poppins — it's a display/heading font
+- Minimum body size: 14pt for print, 16px for web
+- Line height: 1.5–1.6 for body, 1.1–1.2 for headings
+- Letter spacing: -0.5px to -1px for large headings; 0 for body
+
+**Font Installation:**
+- Poppins: Available on Google Fonts (`fonts.google.com/specimen/Poppins`)
+- Lora: Available on Google Fonts (`fonts.google.com/specimen/Lora`)
+- Both should be pre-installed in design environments for best results
+
+### Logo Usage
+
+**Clear Space:**
+Maintain minimum clear space equal to the cap-height of the wordmark on all sides. No other elements should intrude on this zone.
+
+**Minimum Size:**
+- Digital: 120px wide minimum
+- Print: 25mm wide minimum
+
+**Approved Variations:**
+- Dark logo on Light background (primary)
+- Light logo on Dark background (inverted)
+- Single-color Dark on any light neutral
+- Single-color Light on any dark surface
+
+**Prohibited Uses:**
+- Do not stretch or distort the logo
+- Do not apply drop shadows, gradients, or outlines
+- Do not place on busy photographic backgrounds without a color block
+- Do not use accent colors as the logo fill
+- Do not rotate the logo
+
+### Imagery Guidelines
+
+**Photography Style:**
+- Clean, well-lit, minimal post-processing
+- Subjects: people at work, abstract technical concepts, precise objects
+- Avoid: stock photo clichés, overly emotive poses, heavy filters
+- Color treatment: neutral tones preferred; desaturate if needed to match palette
+
+**Illustration Style:**
+- Geometric, precise line work
+- Limited palette: use brand colors only
+- Avoid: cartoonish characters, heavy gradients, 3D renders
+
+**Iconography:**
+- Stroke-based, consistent weight (2px at 24px size)
+- Rounded caps preferred; sharp corners acceptable for technical contexts
+- Use Mid Gray or Dark; accent color only for active/selected states
+
+---
+
+## Universal Brand Guidelines Framework
+
+Use this section when building or auditing guidelines for *any* brand (not Anthropic-specific).
+
+### 1. Brand Foundation
+
+Before any visual decisions, the brand foundation must exist:
+
+| Element | Definition |
+|---------|-----------|
+| **Mission** | Why the company exists beyond making money |
+| **Vision** | The future state the brand is working toward |
+| **Values** | 3–5 core principles that drive decisions |
+| **Positioning** | What you are, for whom, against what alternative |
+| **Personality** | How the brand behaves — adjectives that guide tone |
+
+A visual identity without a foundation is decoration. The foundation drives every downstream decision.
+
+---
+
+### 2. Color System
+
+#### Primary Palette (2–3 colors)
+- One dominant neutral (background or text)
+- One strong brand color (most recognition, hero elements)
+- One supporting color (secondary backgrounds, dividers)
+
+#### Accent Palette (2–4 colors)
+- Used sparingly for emphasis, CTAs, states
+- Must pass WCAG AA contrast against backgrounds they appear on
+
+#### Color Rules to Document:
+- Which color for CTAs vs. informational links
+- Background color combinations that are approved
+- Colors that should never appear together
+- Dark mode equivalents
+
+#### Accessibility Requirements:
+- Normal text (< 18pt): minimum 4.5:1 contrast ratio (WCAG AA)
+- Large text (≥ 18pt): minimum 3:1 contrast ratio
+- UI components: minimum 3:1 against adjacent colors
+- Test: `webaim.org/resources/contrastchecker`
+
+---
+
+### 3. Typography System
+
+#### Type Roles to Define:
+
+| Role | Font | Size Range | Weight | Line Height |
+|------|------|-----------|--------|-------------|
+| Display | — | 40pt+ | Bold | 1.1 |
+| H1 | — | 28–40pt | SemiBold | 1.15 |
+| H2 | — | 22–28pt | SemiBold | 1.2 |
+| H3 | — | 18–22pt | Medium | 1.25 |
+| Body | — | 15–18pt | Regular | 1.5–1.6 |
+| Small / Caption | — | 12–14pt | Regular | 1.4 |
+| Label / UI | — | 11–13pt | Medium | 1.2 |
+
+#### Font Selection Criteria:
+- Max 2 typeface families (one serif or slab, one sans-serif)
+- Both must be available in all required weights
+- Must render well at small sizes on screen
+- Licensing must cover all intended uses (web, print, app)
+
+---
+
+### 4. Logo System
+
+#### Variations Required:
+- **Primary**: full color on white/light
+- **Inverted**: light version on dark backgrounds
+- **Monochrome**: single color for single-color applications
+- **Mark only**: icon/symbol without wordmark (for small sizes)
+- **Horizontal + Stacked**: where layout demands both
+
+#### Usage Rules to Document:
+- Minimum size (px for digital, mm for print)
+- Clear space formula
+- Approved background colors
+- Prohibited modifications (distortion, recoloring, shadows)
+- Co-branding rules (partner logo sizing, spacing)
+
+---
+
+### 5. Imagery Guidelines
+
+#### Photography Criteria:
+| Dimension | Guideline |
+|-----------|-----------|
+| **People** | Authentic, diverse, action-oriented — not posed stock |
+| **Lighting** | Clean and directional; avoid heavy shadows or blown highlights |
+| **Color treatment** | Align to brand palette; desaturate or tint if necessary |
+| **Subjects** | Match brand values — avoid anything that conflicts with positioning |
+
+#### Illustration Style:
+- Define: flat vs. 3D, line vs. filled, abstract vs. representational
+- Set a palette limit: brand colors only, or approved expanded set
+- Define stroke weight and corner radius standards
+
+#### Do / Don't Matrix (customize per brand):
+
+| ✅ Do | ❌ Don't |
+|-------|---------|
+| Show real customers and use cases | Use generic multicultural stock |
+| Use natural lighting | Use heavy vignettes or HDR |
+| Keep backgrounds clean | Place subjects on clashing colors |
+| Match brand palette tones | Use heavy Instagram-style filters |
+
+---
+
+### 6. Tone of Voice & Tone Matrix
+
+Brand voice is consistent; tone adapts to context.
+
+#### Voice Attributes (define 4–6):
+
+| Attribute | What It Means | What It's Not |
+|-----------|---------------|---------------|
+| Example: **Direct** | Say what you mean; no filler | Blunt or dismissive |
+| Example: **Curious** | Ask questions, show genuine interest | Condescending or know-it-all |
+| Example: **Precise** | Specific language, no vague claims | Technical jargon that excludes |
+| Example: **Warm** | Human and approachable | Overly casual or unprofessional |
+
+#### Tone Matrix by Context:
+
+| Context | Tone Dial | Example Shift |
+|---------|-----------|--------------|
+| Error messages | Calm, helpful, matter-of-fact | Less formal than marketing |
+| Marketing headlines | Confident, energetic | More punchy than support |
+| Legal / compliance | Precise, neutral | Less personality |
+| Support / help content | Patient, empathetic | More warmth than ads |
+| Social media | Conversational, light | More informal than web |
+| Executive communications | Authoritative, measured | More formal than blog |
+
+#### Words to Use / Avoid (document per brand):
+
+| ✅ Use | ❌ Avoid |
+|-------|---------|
+| "We" (inclusive) | "Leverage" (jargon) |
+| Specific numbers | "Best-in-class" (vague) |
+| Active voice | Passive constructions |
+| Short sentences | Run-on complexity |
+
+---
+
+### 7. Application Examples
+
+#### Digital
+- **Web**: Primary palette for backgrounds; accent for CTAs; Poppins/brand heading font for H1–H3
+- **Email**: Inline styles only; web-safe font fallbacks always specified; logo as linked image
+- **Social**: Platform-specific safe zones; brand colors dominant; minimal text on images
+
+#### Print
+- Always use CMYK values for print production (never RGB or hex)
+- Bleed: 3mm on all sides; keep critical content 5mm from trim
+- Proof against Pantone reference before bulk print runs
+
+#### Presentations
+- Cover slide: brand dark + brand light with single accent
+- Body slides: white backgrounds with brand accent headers
+- No custom fonts in share files — embed or substitute
+
+---

package/skills/bug-report/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: bug-report
+description: "Creates a structured bug report from a description, or analyzes code to identify potential bugs. Ensures every bug report has full reproduction steps, severity assessment, and context."
+category: "agile"
+argument-hint: "[description] | analyze [path-to-file]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write
+---
+
+## Phase 1: Parse Arguments
+
+| Mode | Trigger | Action |
+|------|---------|--------|
+| Description | no keyword | Generate bug report from description |
+| Analyze | `analyze [path]` | Read files, identify potential bugs |
+| Verify | `verify [BUG-ID]` | Confirm fix resolved the bug |
+| Close | `close [BUG-ID]` | Mark verified bug as closed |
+
+No argument → ask user for bug description.
+
+## Phase 2A: Description Mode
+
+Parse description for: what broke, when, repro steps, expected behavior. Search codebase for related files. Draft report with: summary (title, ID, severity S1-S4, priority P1-P4, status), classification (category, system, frequency, regression), environment (build, platform, scene, state), reproduction steps (preconditions, steps, expected/actual), technical context (affected files, related systems, root cause), evidence, related issues.
+
+## Phase 2B: Analyze Mode
+
+Read target files. Identify: null references, off-by-one, race conditions, unhandled edge cases, resource leaks, incorrect state transitions. Generate bug report per finding.
+
+## Phase 2C: Verify Mode
+
+Read `production/qa/bugs/[BUG-ID].md`. Re-run repro steps via Grep/Glob (check if root cause path still exists). Run related tests. Check for regression (grep for original pattern).
+
+| Verdict | Meaning |
+|---------|---------|
+| VERIFIED FIXED | Repro fails, tests pass |
+| STILL PRESENT | Bug reproduces as described |
+| CANNOT VERIFY | Automated checks inconclusive, needs manual playtest |
+
+Ask to update bug file status. If STILL PRESENT → reopen, suggest `/hotfix`.
+
+## Phase 2D: Close Mode
+
+Confirm status is `Verified Fixed` — otherwise stop, require verify first. Append closure record (date, resolution, commit/PR, verified by, regression test). Update status to Closed. Check triage reports for references.
+
+## Phase 3: Save Report
+
+Ask: "May I write this to `production/qa/bugs/BUG-[NNNN].md`?"
+
+## Phase 4: Next Steps
+
+- **After filing**: `/bug-triage` to prioritize; if S1/S2 → `/hotfix [BUG-ID]`
+- **After fix**: `/bug-report verify [BUG-ID]` — never close without verification
+- **After VERIFIED FIXED**: `/bug-report close [BUG-ID]` → `/bug-triage` to refresh

package/skills/bug-triage/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: bug-triage
+description: "Triage open bugs: re-evaluate priority/severity, assign to sprints, surface trends, produce triage report."
+category: "agile"
+argument-hint: "[sprint | full | trend]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# Bug Triage
+
+Processes open bug backlog into prioritized, sprint-assigned action list. Output: `production/qa/bug-triage-[date].md`.
+
+## Arguments
+
+| Mode | Behavior |
+|------|----------|
+| `sprint` | Triage against current sprint, assign fixable bugs |
+| `full` | All bugs regardless of sprint |
+| `trend` | Read-only trend analysis |
+| No arg | Sprint if exists, else full |
+
+## Load Bug Backlog
+
+Sources (priority order): `production/qa/bugs/*.md` → `production/qa/bugs.md` → qa-plan "Bugs Found" tables. No bugs → stop. Load sprint context from `production/sprints/` (most recent). Load severity reference from `.claude/docs/coding-standards.md` if exists.
+
+## Classification
+
+### Severity (impact)
+
+| Level | Definition |
+|-------|-----------|
+| S1 Critical | Crash, data loss, complete feature failure |
+| S2 High | Major feature broken, game playable |
+| S3 Medium | Degraded with workaround |
+| S4 Low | Cosmetic, no gameplay impact |
+
+### Priority (urgency)
+
+| Level | Definition |
+|-------|-----------|
+| P1 Fix this sprint | Blocks QA/release, regression |
+| P2 Fix soon | Before next major milestone |
+| P3 Backlog | No active blocking impact |
+| P4 Won't fix | Accepted risk / out of scope |
+
+### Assignment
+
+Sprint mode: P1/P2 → assign to sprint if capacity, else flag overflow. Full mode: P1 → current sprint, P2 → next sprint, P3+ → backlog.
+
+### Systemic Flags
+
+- 3+ bugs same system same sprint → design/implementation quality issue
+- 2+ S1/S2 same story → story needs reopen/re-review
+- Bug against Complete story → regression, reopen in tracking
+
+## Trend Analysis
+
+- Volume: total open, opened/closed this sprint, net change
+- Hot spots: most bugs by system, highest S1/S2 ratio
+- Age: bugs >2 sprints old, unassigned S1/S2
+- Regressions: bugs against completed stories
+
+## Report
+
+Triage summary table (P1-P4 counts) + P1 bugs table (ID/system/severity/summary/assigned/story) + P2 table + P3/P4 table + systemic issues + trend analysis + recommended actions (top 3).
+
+Present report → ask write approval → `production/qa/bug-triage-[date].md`.
+
+## Protocol
+
+- Never close/Won't Fix without user approval — surface as P4 candidates
+- Never auto-assign to sprint at capacity — flag overflow
+- Severity is objective; priority is team decision — present as recommendations
+- Trend data is informational — don't block work on trends alone

package/skills/business-investment-advisor/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: business-investment-advisor
+description: "Evaluate capital allocation decisions with ROI, NPV, IRR, and payback analysis. Covers equipment, hiring, technology, real estate, build-vs-buy, and budget allocation."
+argument-hint: ""
+category: "finance"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Business Investment Advisor
+
+Senior business investment analyst for capital allocation decisions. Evaluates every dollar going out the door -- equipment, hiring, technology, real estate, vendor contracts, new business opportunities. Shows the math, states assumptions, gives a clear recommendation, and flags what could go wrong.
+
+Does NOT give personal stock market or securities advice. This skill is for business capital allocation decisions.
+
+---
+
+## Before Starting
+
+**Check for context first:** If `company-context.md` exists, read it before asking questions.
+
+Gather conversationally (not all at once):
+1. **Investment details** -- what, total cost, useful life or contract term
+2. **Financial projections** -- revenue increase or cost savings, ongoing costs, confidence level
+3. **Context** -- alternative capital uses, cost of capital, other options being compared
+
+Work with partial data. State assumptions and flag them clearly.
+
+---
+
+## Modes
+
+### Mode 1: Single Investment Evaluation
+Analyze one decision: calculate ROI, payback, NPV, IRR, run scenarios, produce recommendation.
+
+### Mode 2: Compare Multiple Options
+Rank options against a fixed budget with scoring rubric and priority order.
+
+### Mode 3: Build vs Buy / Lease vs Buy / Hire vs Automate
+Framework-driven comparison for specific trade-off scenarios.
+
+Full formulas, scoring rubrics, decision frameworks, and output templates: `references/analysis-frameworks.md`
+
+---
+
+## Proactive Triggers
+
+Surface these without being asked:
+- **Payback > useful life** -- investment never pays back; recommend against
+- **Optimistic revenue projections** -- run downside case at 50% of projected revenue
+- **Single customer as assumed revenue** -- flag concentration risk
+- **Debt-financed investment** -- factor full interest cost into NPV
+- **No alternative use considered** -- prompt opportunity cost analysis
+- **Sunk cost reasoning detected** -- past spend is irrelevant to go-forward decision
+
+---
+
+## Communication
+
+- Bottom line first -- recommendation before explanation
+- Show all math -- every formula with actual numbers
+- State every assumption -- never hide them
+- Conservative by default -- use base case, not optimistic projections
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Better Approach |
+|---|---|
+| ROI alone without time value of money | Always calculate NPV and IRR for >$25K or >12 months |
+| Optimistic revenue projections | Run downside case at 50% of projected revenue |
+| Ignoring opportunity cost | Compare proposed IRR against best alternative |
+| Sunk cost reasoning | Evaluate only incremental investment vs incremental returns |
+| Comparing different time horizons | Normalize to same period using annualized metrics |
+| Skipping sensitivity analysis | Run base, upside +20%, downside -40% scenarios |
+
+---
+
+## Related Skills
+
+- **financial-analyst**: DCF valuation of entire companies, ratio analysis. Not for single capex decisions.
+- **saas-metrics-coach**: SaaS unit economics (CAC, LTV, churn). Not for equipment or real estate.

package/skills/business-investment-advisor/references/analysis-frameworks.md

@@ -0,0 +1,113 @@
+# Investment Analysis Frameworks
+
+## Core Analysis Methods
+
+### ROI (Return on Investment)
+`ROI = (Net Gain from Investment / Cost of Investment) x 100`
+- Net Gain = Total Returns - Total Costs over the analysis period
+- Use for quick comparisons. Limitation: ignores time value of money.
+
+### Payback Period
+`Payback = Total Investment / Annual Net Cash Flow`
+- Target: <3 years for most small/medium business investments
+- Equipment: if payback = 80%+ of useful life, marginal at best
+- Hiring: payback = (loaded salary + onboarding) / annual revenue attributable to that hire
+
+### NPV (Net Present Value)
+`NPV = Sum of [Cash Flow_t / (1 + r)^t] - Initial Investment`
+- r = cost of capital (typically 8-15% for small/medium business)
+- NPV > 0 = investment creates value. NPV < 0 = destroys value.
+- Always run NPV for investments >$25K or >12-month horizon.
+
+### IRR (Internal Rate of Return)
+- The discount rate at which NPV = 0
+- If IRR > hurdle rate, investment passes
+- Hurdle rates: 10-15% stable business / 20-25% growth investment / 30%+ high-risk
+
+### Opportunity Cost
+Always ask: what else could this capital do?
+- Compare IRR of proposed investment vs best alternative
+- Include debt paydown as alternative (guaranteed return = your interest rate)
+
+---
+
+## Decision Frameworks
+
+### Build vs Buy
+| Factor | Build | Buy |
+|--------|-------|-----|
+| Upfront cost | Higher | Lower |
+| Ongoing cost | Lower long-term | Recurring fee |
+| Control | Full | Vendor-dependent |
+| Speed | Slower | Faster |
+| Risk | Execution risk | Vendor dependency |
+
+**Rule:** Buy if vendor does it >=80% as well at <50% of the build cost.
+
+### Lease vs Buy
+- **Buy when:** use >60% of useful life, asset retains value, depreciation advantage
+- **Lease when:** technology changes fast, cash preservation matters, maintenance included
+- Always compare Total Cost of Ownership (TCO) over same period
+
+### Hire vs Automate vs Outsource
+- **Hire:** work requires judgment, relationships, grows with business
+- **Automate:** task is repetitive, rule-based, high volume
+- **Outsource:** need is variable, specialized, or non-core
+- Rule: automate or outsource first; hire when you've proven need and can't keep up
+
+---
+
+## Investment Scoring Rubric
+
+Score 1-5 on each dimension:
+
+| Dimension | 1 (Poor) | 5 (Excellent) |
+|-----------|----------|---------------|
+| ROI | <10% | >50% |
+| Payback period | >5 years | <1 year |
+| Strategic fit | Unrelated | Core to mission |
+| Risk level | High/uncertain | Low/proven |
+| Reversibility | Sunk cost | Easy to exit |
+| Cash flow impact | Major drain | Self-funding quickly |
+
+**Score:** 6-12 = Don't do it / 13-20 = Needs more analysis / 21-30 = Strong investment
+
+---
+
+## Budget Allocation Framework
+
+When allocating a fixed budget across multiple options:
+1. Rank all options by IRR (highest first)
+2. Fund in order until budget is exhausted
+3. Exception: fund anything with payback <6 months first (quick wins)
+4. Never fund negative NPV unless strategic reason -- name it explicitly
+
+---
+
+## Output Template
+
+For every investment analysis:
+
+**RECOMMENDATION:** [Proceed / Proceed with conditions / Do not proceed]
+
+**THE NUMBERS:**
+| Metric | Value |
+|--------|-------|
+| Total Investment | $ |
+| Annual Net Cash Flow | $ |
+| Payback Period | X months/years |
+| 3-Year ROI | X% |
+| NPV (at X% discount rate) | $ |
+| IRR | X% |
+| Investment Score | X/30 |
+
+**KEY ASSUMPTIONS:** [Every assumption used -- flag low-confidence ones]
+
+**UPSIDE CASE:** [Projections beat plan by 20%]
+**DOWNSIDE CASE:** [Projections miss by 40%]
+
+**RISKS TO WATCH:**
+1. [Risk + mitigation]
+2. [Risk + mitigation]
+
+**NEXT STEP:** [One specific action before committing capital]

package/skills/caching-strategy/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: caching-strategy
+description: "Multi-layer caching: HTTP, CDN, Redis, in-memory, browser. Invalidation, TTLs, stampede protection."
+category: "backend"
+argument-hint: "[layer: http|cdn|redis|memory|browser]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, Task
+---
+# caching-strategy — Multi-Layer Caching
+
+**Regla 0:** antes de cachear, medí. Cachear sin profiling esconde problemas.
+
+## Cuándo usar / NO usar
+
+| Usar | NO usar |
+|------|---------|
+| Hot path lectura >> escritura | Write-heavy con lectura impredecible |
+| Query cara sin índices posibles | Info financiera/regulatoria (staleness = daño legal) |
+| Respuesta inmutable o slow-changing | Parche de query mal diseñada (arreglá la query) |
+| Alivio DB bajo carga | Prematuramente (primero índices) |
+
+## Capas
+
+```
+Browser/RN → CDN → API Gateway → App in-memory (LRU) → Redis → Database
+```
+
+Cada capa: TTL distinto, invalidation distinta. Más cerca del usuario = más caché pero más difícil invalidar.
+
+## Qué cachear dónde
+
+| Dato | Cache |
+|------|-------|
+| Assets estáticos (JS, CSS, img) | CDN + browser (immutable + versioned URLs) |
+| API responses públicas | CDN + Redis |
+| API responses por-user | Redis + cliente |
+| Session/token, rate limit counters | Redis |
+| Traducciones / config | In-memory warm on boot |
+| DB query resultado | Redis (cache-aside) |
+
+## HTTP Caching Headers
+
+> → Read references/http-headers.md for header values and ETag usage
+
+## Patterns, Invalidation & Stampede Protection
+
+> → Read references/patterns-and-invalidation.md for cache-aside/write-through/read-through patterns, invalidation strategies, and stampede protection
+
+## TTL Defaults
+
+> → Read references/ttl-defaults.md for recommended TTLs by data type
+
+## Redis & Client-Side
+
+> → Read references/redis-and-client.md for Redis cluster config, key naming, and React/RN client caching
+
+## Anti-patterns
+
+- Cachear sin medir, TTL infinito sin invalidation, cachear PII sin `no-store`
+- Cachear errores (404/500), cache que falla → app cae (cache debe ser opcional)
+- `KEYS *` en Redis prod (usar SCAN), cache sin namespace, per-user en CDN sin Vary
+- Sin métricas de hit rate
+
+## Observabilidad
+
+- Métricas: `cache_hits/misses_total`, `cache_latency_seconds`, `cache_evictions_total`
+- Hit rate target: hot >90%, warm >70%. Hit rate <50% sostenido = cache no vale
+- Alertas: evictions creciente, latency p99 >10ms, hit rate cae súbitamente
+
+## Checklist
+
+- [ ] Profiling justifica el cache
+- [ ] Capa correcta elegida (browser/CDN/Redis/memoria)
+- [ ] TTL razonado con trade-off staleness vs carga
+- [ ] Invalidation strategy clara
+- [ ] Stampede protection si hot path
+- [ ] Cache opcional — app funciona si Redis down
+- [ ] Headers HTTP correctos (`private` para PII, `Vary`)
+- [ ] Key naming consistente + namespace
+- [ ] Métricas: hits/misses/latency/evictions
+- [ ] No cacheamos errores

package/skills/caching-strategy/references/http-headers.md

@@ -0,0 +1,9 @@
+# HTTP Caching Headers
+
+| Header | Uso |
+|--------|-----|
+| `public, max-age=31536000, immutable` | Assets versionados (hash en URL) |
+| `public, s-maxage=300, stale-while-revalidate=3600` | API listado semi-estatico |
+| `private, no-store` | Response con PII |
+
+- ETag + `If-None-Match` -> 304 Not Modified. `Vary: Accept-Encoding, Authorization`