mikeclaw007

---
name: capacity
description: "Forecasting load, headroom, and scaling plans. Use before big launches or cost reviews."
---

# Capacity

Structured guidance for **capacity planning** (load, headroom, scaling): confirm triggers, propose the stages below, and adapt if the user wants a lighter pass.

## When to Offer This Workflow

**Trigger conditions:**
- User mentions **capacity**, **headroom**, **scaling plans**, or closely related work
- They want a structured workflow rather than ad-hoc tips
- They are preparing a review, rollout, or stakeholder communication

**Initial offer:**
Explain the four stages briefly and ask whether to follow this workflow or work freeform. If they decline, continue in their preferred style.

## Workflow Stages

### Stage 1: Clarify context & goals

Anchor on **growth assumptions and seasonality**. Ask what success looks like, constraints, and what must not break. Capture unknowns early.

### Stage 2: Design or plan the approach

Translate goals into a concrete plan around **headroom and bottlenecks**. Compare alternatives and explicit trade-offs; avoid implicit assumptions.

### Stage 3: Implement, validate, and harden

Execute with verification loops tied to **cost vs performance trade-offs**. Prefer small steps, measurable checks, and rollback points where risk is high.

### Stage 4: Operate, communicate, and iterate

Close the loop with **load tests and forecasts**: monitoring, documentation, stakeholder updates, and lessons learned for the next cycle.

## Checklist Before Completion

- Goals and constraints are explicit for **capacity** planning
- Risks and trade-offs are stated, not hand-waved
- Verification steps match the change’s impact (tests, canary, peer review)
- Operational follow-through is covered (monitoring, docs, owners)

## Tips for Effective Guidance

- Be procedural: stage-by-stage, with clear exit criteria
- Ask for missing context (environment, scale, deadlines) before prescribing
- Prefer checklists and concrete examples over generic platitudes
- If the user declines the workflow, switch to freeform help without lecturing

## Handling Deviations

- If the user wants to skip a stage: confirm and continue with what they need.
- If context is missing: ask targeted questions before strong recommendations.
- Prefer concrete examples, trade-offs, and verification steps over generic advice.

## Quality Bar

- Each recommendation should be **actionable** (what to do next).
- Call out **failure modes** relevant to capacity (security, scale, UX, or ops).
- Keep tone direct and respectful of the user’s time.

---
name: design-systems
description: Deep design systems workflow—tokens, components, accessibility, documentation, governance, and adoption. Use when scaling UI consistency across teams or evolving a component library (Figma + code parity).
---

# Design Systems (Deep Workflow)

A design system is **shared UI infrastructure**: tokens, components, patterns, and governance so products feel cohesive without freezing innovation.

## When to Offer This Workflow

**Trigger conditions:**

- Multiple apps diverging visually; mounting accessibility debt
- Launching or rebooting a component library; token refresh
- Figma and production code drifting apart

**Initial offer:**

Use **six stages**: (1) strategy & principles, (2) design tokens, (3) components & API, (4) accessibility & content, (5) docs & tooling, (6) governance & adoption). Confirm framework (React/Vue/Svelte) and design tooling.

---

## Stage 1: Strategy & Principles

**Goal:** Why the system exists (speed, a11y, brand); explicit non-goals (not every pixel must be centralized).

**Exit condition:** One-page principles: density, tone, motion philosophy.

---

## Stage 2: Design Tokens

**Goal:** Semantic color, type, space, radius, motion—names like `surface.default` instead of raw hex everywhere.

### Practices

- Plan light/dark and density themes early

---

## Stage 3: Components & API

**Goal:** Composable primitives vs bloated “kitchen sink” widgets; stable props API with semver discipline.

### Practices

- Prefer composition / slots over prop explosion

---

## Stage 4: Accessibility & Content

**Goal:** WCAG baseline per component: focus rings, labels, error patterns, live regions where needed.

---

## Stage 5: Docs & Tooling

**Goal:** Storybook or equivalent; usage guidelines; code snippets; do/don’t examples.

---

## Stage 6: Governance & Adoption

**Goal:** Contribution guide; deprecation policy; champions or office hours per product line.

---

## Final Review Checklist

- [ ] Strategy and principles agreed
- [ ] Token layer semantic and themeable
- [ ] Component APIs stable and composable
- [ ] Accessibility baseline per component
- [ ] Documentation and live examples
- [ ] Contribution and deprecation governance

## Tips for Effective Guidance

- Figma ↔ code parity needs owners and a sync cadence.
- Do not ship a component without keyboard and screen-reader checks.

## Handling Deviations

- Small teams: start with tokens + a few primitives—defer full catalog.

---
name: docker-eng
description: Deep Docker workflow—image design, multi-stage builds, security, runtime config, health checks, and operations. Use when containerizing apps, hardening images, or debugging container behavior in CI and production.
---

# Docker Eng — Deep Workflow

Containers package applications with their dependencies. Optimize for **small**, **reproducible** images and **clear** runtime contracts—not “SSH into a mini VM.”

## When to Offer This Workflow

**Trigger conditions:**

- Authoring Dockerfiles for apps or CI
- CVEs in base images; accidental secrets in layers
- Slow builds or oversized images pushing registry costs

**Initial offer:**

Use **six stages**: (1) base image & supply chain, (2) Dockerfile structure, (3) runtime config & secrets, (4) security hardening, (5) health & observability, (6) ops & debugging). Confirm registry and orchestrator (Kubernetes, ECS, etc.).

---

## Stage 1: Base Image & Supply Chain

**Goal:** Pin tags or digests; prefer minimal bases (distroless, slim) when compatible.

### Practices

- Scan images regularly (Trivy, Grype); track SBOM where required

---

## Stage 2: Dockerfile Structure

**Goal:** Multi-stage builds: compile in builder, copy only artifacts to runtime; order layers for cache hits (dependency manifests before source).

### Practices

- Maintain a robust `.dockerignore` (exclude secrets, build artifacts, VCS noise)

---

## Stage 3: Runtime Config & Secrets

**Goal:** Configuration via environment variables; secrets injected at runtime (K8s secrets, IAM, vault)—never `COPY` real secrets into the image.

---

## Stage 4: Security Hardening

**Goal:** Run as non-root; read-only filesystem where possible; minimal packages in final image; avoid leaking build tools in production.

---

## Stage 5: Health & Observability

**Goal:** `HEALTHCHECK` or orchestrator probes match real readiness (dependencies up); logs to stdout/stderr in structured form.

---

## Stage 6: Ops & Debugging

**Goal:** Tag images with git SHA; document how to exec/debug (or use debug sidecars for distroless).

---

## Final Review Checklist

- [ ] Base image pinned and scanned
- [ ] Multi-stage build; minimal runtime layer
- [ ] No secrets in layers
- [ ] Non-root and least privilege
- [ ] Health/readiness aligned with app
- [ ] .dockerignore and reproducible builds

## Tips for Effective Guidance

- Explain layer caching order—why `COPY package.json` before `COPY .` matters.
- Distroless images: no shell—use ephemeral debug containers or sidecars.

## Handling Deviations

- Windows containers: different paths and base images—validate separately.

---
name: strategy-backtest
description: |
  Quantitative strategy backtesting—implement, run, and tune trading rules on historical data; performance metrics (CAGR, max drawdown, Sharpe, win rate) and simple parameter sweeps. Keywords: backtest, algorithmic trading, Backtrader, moving average, MACD, RSI, walk-forward, risk.
---

# Strategy Backtest — Historical Performance & Optimization

## Overview

Supports **systematic trading strategy** workflows: **backtest** rules on history, **optimize** parameters (e.g. grid search), and **report** results. Typical building blocks include **moving-average crosses**, **MACD**, **RSI**, and custom signals—implemented with libraries such as **Backtrader** or similar.

**Trigger keywords:** backtest, trading strategy, quant, algorithmic trading, Sharpe, drawdown, optimize parameters, walk-forward

## Prerequisites

```bash
pip install pandas numpy backtrader matplotlib
```

## Capabilities

1. **Backtest engine** — run strategies on historical OHLCV (or vendor-specific) data.  
2. **Performance analytics** — annualized return, max drawdown, Sharpe-like ratios, win rate (definitions must match your implementation).  
3. **Parameter search** — grid or bounded search over strategy parameters with **out-of-sample** caution (see `references/strategy_backtest_guide.md`).

## Commands

| Command | Description | Example |
|---------|-------------|---------|
| `backtest` | Run a backtest | `python3 scripts/skills/strategy-backtest/scripts/strategy_backtest_tool.py backtest [args]` |
| `optimize` | Parameter optimization | `python3 scripts/skills/strategy-backtest/scripts/strategy_backtest_tool.py optimize [args]` |
| `report` | Emit a backtest report | `python3 scripts/skills/strategy-backtest/scripts/strategy_backtest_tool.py report [args]` |

## Usage (from repository root)

```bash
python3 scripts/skills/strategy-backtest/scripts/strategy_backtest_tool.py backtest --strategy ma_cross --symbol SPY --period 3y
python3 scripts/skills/strategy-backtest/scripts/strategy_backtest_tool.py optimize --strategy ma_cross --fast 5-20 --slow 20-60
python3 scripts/skills/strategy-backtest/scripts/strategy_backtest_tool.py report --format markdown
```

Use **symbols and venues** appropriate to your data feed (e.g. `SPY`, `QQQ`, or local indices)—the examples above are illustrative.

## Output format (for the agent’s report)

```markdown
# Strategy backtest report

**Generated**: YYYY-MM-DD HH:MM

## Key findings
1. [Finding 1]
2. [Finding 2]
3. [Finding 3]

## Metrics snapshot
| Metric | Value | Notes |
|--------|-------|-------|
| CAGR | X% | … |
| Max drawdown | Y% | … |
| Sharpe (if defined) | Z | window & rf assumption |

## Analysis
[Grounded in actual run outputs—no fabricated fills or equity curves.]

## Risks & limitations
- Past performance ≠ future results; costs, slippage, and survivorship bias matter.
```

## References

### Core
- [Backtrader documentation](https://www.backtrader.com/docu/)
- [Backtrader on GitHub](https://github.com/mementum/backtrader)

### Community & critique
- [Hacker News — backtesting pitfalls](https://news.ycombinator.com/item?id=39462946)
- [Reddit r/algotrading](https://www.reddit.com/r/algotrading/comments/1073140yyz/quant_backtest_ai/)

## Notes

- Base all numbers on **script or notebook output**—never invent trades or metrics.  
- Mark missing fields as **unavailable** instead of guessing.  
- **Not investment advice**; comply with local regulations for research vs advisory.  
- Prefer stating **assumptions** (fees, spread, leverage, timezone, corporate actions).


FILE:data/strategy_backtest_data.json
{
  "records": [
    {
      "timestamp": "2026-03-25T16:10:16.456636",
      "command": "backtest",
      "input": "",
      "status": "completed"
    }
  ],
  "created": "2026-03-25T16:10:16.456623",
  "tool": "strategy-backtest"
}
FILE:references/strategy_backtest_guide.md
# Strategy Backtest — Framework & Guide

## Tool summary

- **Name**: Strategy Backtest  
- **Commands**: `backtest`, `optimize`, `report`  
- **Typical deps**: `pip install pandas numpy backtrader matplotlib`

## Analysis dimensions

- **Signal design** — rules, indicators, position sizing, risk limits  
- **Data quality** — splits, adjustments, missing bars, survivorship  
- **Performance** — return, drawdown, risk-adjusted metrics, turnover  
- **Robustness** — train/test split, walk-forward, parameter stability  

## Framework

### Phase 1 — Specification
- Universe, frequency, costs, and constraints (long-only, margin, etc.)  
- Reproducible random seeds if any stochastic element exists  

### Phase 2 — Execution & metrics
- Run backtests; log equity curve and trades  
- Align metric definitions (annualization, risk-free for Sharpe)  

### Phase 3 — Optimization (careful)
- Grid or search over parameters **on in-sample** only; validate **out-of-sample**  
- Watch for **overfitting** when many parameters are tried  

## Scoring rubric (strategy quality — qualitative)

| Score | Level | Meaning | Suggested action |
|-------|-------|---------|-------------------|
| 5 | Strong | Stable OOS, sensible economics | Document and paper-trade |
| 4 | Good | Decent metrics; minor sensitivity | More stress tests |
| 3 | OK | Marginal; parameter-sensitive | Redesign features |
| 2 | Weak | Likely curve-fit | Simplify or abort |
| 1 | Poor | Implausible or unstable | Stop |

## Output template

```markdown
# Backtest analysis

## Hypothesis
- …

## Results (from run)
| Metric | Value |
|--------|-------|

## Overfitting / robustness notes
- …

## Next steps
- …
```

## Reference links

- [Backtrader documentation](https://www.backtrader.com/docu/)  
- [Backtrader on GitHub](https://github.com/mementum/backtrader)  
- [Hacker News — pitfalls](https://news.ycombinator.com/item?id=39462946)  
- [Reddit r/algotrading](https://www.reddit.com/r/algotrading/comments/1073140yyz/quant_backtest_ai/)  

## Tips

1. Always report **assumptions** for fees and slippage.  
2. Prefer **simple** strategies with fewer knobs before large parameter grids.  
3. Treat **live trading** as a different system (latency, fills, regime change).  

FILE:scripts/strategy_backtest_tool.py
#!/usr/bin/env python3
"""
Strategy backtest — CLI stub for backtest / optimize / report flows.

Usage:
    python3 strategy_backtest_tool.py backtest [args]
    python3 strategy_backtest_tool.py optimize [args]
    python3 strategy_backtest_tool.py report [args]
"""

import json
import os
import sys
from datetime import datetime

DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "data")
DATA_FILE = os.path.join(DATA_DIR, "strategy_backtest_data.json")
LEGACY_DATA_FILE = os.path.join(DATA_DIR, "quant_backtest_data.json")

REF_URLS = [
    "https://www.backtrader.com/docu/",
    "https://github.com/mementum/backtrader",
    "https://news.ycombinator.com/item?id=39462946",
]


def ensure_data_dir():
    os.makedirs(DATA_DIR, exist_ok=True)


def load_data():
    if os.path.exists(DATA_FILE):
        with open(DATA_FILE, "r", encoding="utf-8") as f:
            return json.load(f)
    if os.path.exists(LEGACY_DATA_FILE):
        with open(LEGACY_DATA_FILE, "r", encoding="utf-8") as f:
            data = json.load(f)
        data["tool"] = "strategy-backtest"
        save_data(data)
        return data
    return {"records": [], "created": datetime.now().isoformat(), "tool": "strategy-backtest"}


def save_data(data):
    ensure_data_dir()
    with open(DATA_FILE, "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False, indent=2)


def backtest(args):
    """Run a strategy backtest."""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "backtest",
        "input": " ".join(args) if args else "",
        "status": "completed",
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "backtest",
        "message": "Backtest step completed",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3],
    }


def optimize(args):
    """Optimize strategy parameters."""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "optimize",
        "input": " ".join(args) if args else "",
        "status": "completed",
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "optimize",
        "message": "Optimization step completed",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3],
    }


def report(args):
    """Generate a backtest report."""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "report",
        "input": " ".join(args) if args else "",
        "status": "completed",
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "report",
        "message": "Report step completed",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3],
    }


def main():
    cmds = ["backtest", "optimize", "report"]
    if len(sys.argv) < 2 or sys.argv[1] not in cmds:
        print(
            json.dumps(
                {
                    "error": f"Usage: strategy_backtest_tool.py <{','.join(cmds)}> [args]",
                    "available_commands": {c: "" for c in cmds},
                    "tool": "strategy-backtest",
                },
                ensure_ascii=False,
                indent=2,
            )
        )
        sys.exit(1)

    cmd = sys.argv[1]
    args = sys.argv[2:]

    if cmd == "backtest":
        result = backtest(args)
    elif cmd == "optimize":
        result = optimize(args)
    elif cmd == "report":
        result = report(args)
    else:
        result = {"error": f"Unknown command: {cmd}"}

    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))


if __name__ == "__main__":
    main()

---
name: privacy-gdpr
description: Deep privacy/GDPR-oriented workflow—lawful basis, data inventory, minimization, DSAR process, DPIA triggers, subprocessors, and breach notification mindset. Use when designing data practices, vendor review, or user rights operations. Not legal advice.
---

# Privacy & GDPR (Deep Workflow)

This skill supports **structured thinking** about personal data. **Legal and compliance teams** must approve binding interpretations—this is **not** legal advice.

## When to Offer This Workflow

**Trigger conditions:**

- New collection of PII; analytics or ML on user data
- Vendor processing agreements; international transfers
- DSAR volume; breach response planning

**Initial offer:**

Use **six stages**: (1) scope & roles, (2) inventory & purposes, (3) lawful basis & notices, (4) rights & DSAR, (5) security & subprocessors, (6) DPIA & transfers). Confirm jurisdiction (EU/UK vs broader).

---

## Stage 1: Scope & Roles

**Goal:** Identify controller vs processor roles and whose data is involved (employees, customers, minors).

### Output

Simple RACI for privacy decisions.

**Exit condition:** Data subjects and systems in scope are listed.

---

## Stage 2: Inventory & Purposes

**Goal:** Record of processing activities (ROPA-style): what data, why, where stored, retention, who accesses.

### Practices

- Data minimization: collect and retain only what is needed

---

## Stage 3: Lawful Basis & Notices

**Goal:** Map processing to lawful basis (consent, contract, legitimate interests, etc.)—**lawyers validate** per jurisdiction.

### UX

- Consent granular and withdrawable where required

---

## Stage 4: Rights & DSAR

**Goal:** Operational playbook for access, erasure, portability, restriction—with SLAs and identity verification.

### Practices

- Log requests and responses for audit
- Plan how erasure interacts with backups and logs

---

## Stage 5: Security & Subprocessors

**Goal:** DPAs, SCCs or adequacy for transfers; subprocessor list public where required.

### Security

- Encryption, access controls, and logging aligned with risk

---

## Stage 6: DPIA & Transfers

**Goal:** Recognize when DPIA is likely required (high-risk processing)—escalate to DPO/legal.

### Transfers

- Document mechanisms for non-adequate countries

---

## Final Review Checklist

- [ ] Roles (controller/processor) and scope clear
- [ ] RoPA or equivalent inventory maintained
- [ ] Lawful basis and notices reviewed by legal where needed
- [ ] DSAR process with SLAs and verification
- [ ] Subprocessors and transfers documented

## Tips for Effective Guidance

- Engineering detail (backups, logs) is where GDPR meets reality.
- Privacy by design is cheaper than retrofit.
- Never invent legal conclusions—flag for professional review.

## Handling Deviations

- US-only: still map PII and consider state laws (e.g., CPRA).
- B2B vs B2C: different notice and rights patterns.

---
name: performance-tuning
description: Deep performance tuning workflow—goals and measurement, profiling, hotspots, caching and concurrency trade-offs, system-specific tuning (DB, GC, network), and verification. Use when fixing latency, throughput, or resource saturation.
---

# Performance Tuning (Deep Workflow)

Performance work is **measurement-driven**. **Profile** before optimizing; **verify** after changes; **guard** against regressions with benchmarks or production metrics.

## When to Offer This Workflow

**Trigger conditions:**

- High **CPU**, **memory**, **p99** latency, **GC** pauses
- **Cost** reduction via efficiency
- **Premature** optimization requests—need **evidence** first

**Initial offer:**

Use **six stages**: (1) frame goals & SLOs, (2) measure baseline, (3) profile & hypothesize, (4) implement changes, (5) verify & compare, (6) prevent regression). Confirm **language/runtime** and **environment** (prod-like data volume).

---

## Stage 1: Frame Goals & SLOs

**Goal:** **Numeric** targets: p95 latency, throughput, max memory—**not** “faster.”

### Questions

1. Which **workloads** matter most (batch vs interactive)?
2. **Correctness** constraints (approximation allowed or not)?
3. **Cost** budget for hardware vs engineering time?

**Exit condition:** One-page success criteria and out-of-scope areas.

---

## Stage 2: Measure Baseline

**Goal:** **Reproducible** benchmark or **RUM** segment—same inputs, same conditions.

### Practices

- **Warm** caches when prod is always warm
- **Statistical** repeat (multiple runs, discard outliers methodology)

**Exit condition:** Baseline numbers + environment fingerprint (versions, flags).

---

## Stage 3: Profile & Hypothesize

**Goal:** Find **dominant cost**: CPU bound, I/O bound, lock contention, allocation rate.

### Tools (examples)

- **CPU** flame graphs; **async** wait profiling
- **Alloc** profiling for GC pressure
- **DB** query plans and lock waits

**Exit condition:** Hypothesis tied to evidence (e.g., “40% time in JSON parse”).

---

## Stage 4: Implement Changes

**Goal:** **Smallest** change that addresses the hotspot; **avoid** **clever** without proof.

### Levers

- **Algorithm** / data structure
- **Caching** with **invalidation** discipline
- **Batching** I/O; **connection** pooling
- **Parallelism** where safe—watch **locks**

---

## Stage 5: Verify & Compare

**Goal:** **A/B** or before/after with **same** workload; **watch** **tail** latency **not** only mean.

### Production

- **Canary** with **error** rate and **latency** gates

---

## Stage 6: Prevent Regression

**Goal:** **Micro-benchmarks** in CI (optional), **budgets**, or **synthetic** checks.

---

## Final Review Checklist

- [ ] Goals and baseline documented
- [ ] Root cause supported by profiler/trace evidence
- [ ] Change scoped; trade-offs explicit
- [ ] Verification on realistic load
- [ ] Regression guard where feasible

## Tips for Effective Guidance

- **Little’s Law** intuition: queues blow **latency**—often **fix** **concurrency** **before** **micro-opts**.
- **Avoid** optimizing **cold** paths **first**.
- **GC** languages: **allocation** **rate** often **is** the **enemy**.

## Handling Deviations

- **Embedded** / **mobile**: **battery** and **thermal** **constraints** **matter** **too**.
- **Distributed** systems: **local** **opt** **may** **hurt** **system** **(see** **load-testing**).

---
name: observability-slos
description: Deep SLO/SLI workflow—user-centric SLIs, SLO targets and windows, error budgets, multi-window burn alerts, and policy when budget is exhausted. Use when defining reliability targets or aligning eng and product on trade-offs.
---

# Observability & SLOs (Deep Workflow)

SLOs connect **engineering work** to **user-perceived reliability**. SLIs must be **measurable from systems** but **grounded in user journeys**.

## When to Offer This Workflow

**Trigger conditions:**

- Defining **99.9%** without defining **for what**
- Too many pages or none; need **error budget** discipline
- **Product** wants features while **stability** degrades

**Initial offer:**

Use **six stages**: (1) pick user journeys, (2) define SLIs, (3) set SLO targets & windows, (4) error budget policy, (5) alerting on budget burn, (6) review & iterate). Confirm **metric** stack and **dependency** SLOs from vendors.

---

## Stage 1: User Journeys

**Goal:** **Critical paths** that matter if broken—checkout, login, API sync, not “CPU low”.

### Output

3–10 journeys ranked by **business impact** and **frequency**.

**Exit condition:** One paragraph per journey: user intent + failure symptom.

---

## Stage 2: Define SLIs

**Goal:** **Ratio** of good events over total over a window—**implementation** explicit.

### Examples

- **Availability**: successful requests / valid requests (define “valid”)
- **Latency**: proportion of requests faster than **T** ms

### Good SLIs

- **Objective**, **low-cardinality** enough to measure reliably

**Exit condition:** SLI formula + data source (metrics, logs, probes).

---

## Stage 3: SLO Targets & Windows

**Goal:** **Target** (e.g., 99.9% monthly) implies **allowed** bad minutes—make it explicit.

### Practices

- **Rolling** 30d common; align with **release** cadence
- **Tier** services: not everything needs same SLO

**Exit condition:** Published table: journey → SLI → target → window.

---

## Stage 4: Error Budget Policy

**Goal:** **What we do** when budget is healthy vs exhausted.

### Policy ideas

- Budget healthy → ship features; low → freeze risky changes, focus on reliability
- **Escalation** when budget burns fast (multi-window alerts)

**Exit condition:** Written policy with product sign-off.

---

## Stage 5: Alerting on Burn

**Goal:** Page on **budget burn rate**, not every blip—**multi-window** **multi-burn-rate** pattern when using Google-style SLO alerting.

### Practices

- **Fast burn** = page soon; **slow burn** = ticket/track

**Exit condition:** Alert rules linked to runbooks.

---

## Stage 6: Review & Iterate

**Goal:** SLOs **drift** with architecture—**quarterly** review; adjust targets with data.

---

## Final Review Checklist

- [ ] Journeys and SLIs tied to real user pain
- [ ] Targets realistic vs dependencies and cost
- [ ] Error budget policy agreed with product
- [ ] Alerts on burn, not noisy symptom spam
- [ ] Review cadence scheduled

## Tips for Effective Guidance

- Translate **99.9%** to **minutes/month** of allowed badness.
- **SLA** (contract) vs **SLO** (internal)—don’t confuse.
- Dependency SLO caps what you can promise—surface that early.

## Handling Deviations

- **No metrics yet**: start with **proxy SLI** (synthetic probes) and improve instrumentation.
- **Batch systems**: event processing lag as SLI instead of HTTP.

---
name: nextjs-app-router
description: Deep Next.js App Router workflow—layouts, routing, Server vs Client Components, data fetching and caching, revalidation, streaming, and deployment (Node, serverless, edge). Use when building or debugging Next.js 13+ apps.
---

# Next.js App Router (Deep Workflow)

App Router **changes** **mental** **models**: **where** **code** **runs**, **what** **is** **cached**, **and** **how** **HTML** **streams**. **Defaults** **differ** **from** **Pages** **Router**—**call** **that** **out** **explicitly**.

## When to Offer This Workflow

**Trigger conditions:**

- **New** **App** **Router** **project** **or** **migration** **from** **pages/**
- **Confusion** **Server** **vs** **Client** **Components**; **hooks** **errors**
- **Stale** **data**, **wrong** **cache**, **need** **ISR** **semantics**

**Initial offer:**

Use **six stages**: (1) route & layout model, (2) Server vs Client boundaries, (3) data fetching & cache, (4) revalidation & tags, (5) streaming & UX, (6) deployment & runtime. Confirm **Next** **version** **and** **hosting** **(Vercel** **self**, **etc.)**.

---

## Stage 1: Route & Layout Model

**Goal:** **`app/`** **directory** **=** **nested** **layouts** **+** **col** **ocated** **routes**.

### Practices

- **`layout.tsx`** **for** **shared** **UI** **and** **providers** **(client** **where** **needed)**
- **`page.tsx`** **is** **leaf** **UI** **per** **segment**
- **`loading.tsx`**, **`error.tsx`**, **`not-found`** **for** **UX** **boundaries**

**Exit condition:** **URL** **tree** **matches** **folder** **tree** **mental** **model**.

---

## Stage 2: Server vs Client Components

**Goal:** **Default** **Server** **Components**; **`use client`** **only** **where** **interactivity** **needs** **browser** **APIs** **or** **state**.

### Rules of thumb

- **Data** **fetch** **on** **server** **by** **default** **(async** **components)**
- **Leaf** **interactive** **islands** **as** **client** **components**
- **Prop** **serialization**: **only** **JSON-serializable** **props** **across** **boundary**

**Exit condition:** **List** **of** **client** **components** **and** **why**.

---

## Stage 3: Data Fetching & Cache

**Goal:** `fetch` **cache** **semantics** **(force-cache** **vs** **no-store** **vs** **revalidate)** **explicit** **per** **call**.

### Practices

- **Align** **with** **auth**: **no-store** **or** **request** **memoization** **patterns** **for** **user-specific** **data**
- **Parallel** **fetch** **where** **possible** **to** **avoid** **waterfalls**

**Exit condition:** **Per-route** **data** **dependency** **graph** **(simple** **diagram)**.

---

## Stage 4: Revalidation & Tags

**Goal:** **Fresh** **when** **needed** **without** **DDOS** **origin**.

### Practices

- **`revalidatePath`** / **`revalidateTag`** **from** **server** **actions** **or** **route** **handlers**
- **Webhook-triggered** **revalidation** **for** **CMS**

**Exit condition:** **Invalidation** **owner** **and** **trigger** **documented**.

---

## Stage 5: Streaming & UX

**Goal:** **`Suspense`** **boundaries** **with** **meaningful** **fallbacks**; **a11y** **for** **loading**.

### Practices

- **Avoid** **waterfall** **inside** **suspense** **trees** **(sequential** **awaits)**

---

## Stage 6: Deployment & Runtime

**Goal:** **Node** **vs** **edge** **runtime** **per** **route** **segment** **when** **using** **edge**.

### Practices

- **Edge** **cannot** **use** **all** **Node** **APIs**—**verify** **compat**
- **ISR** **on** **serverless** **may** **need** **warming** **or** **cron** **revalidate**

---

## Final Review Checklist

- [ ] Layouts and route segments match product IA
- [ ] Server/Client split justified; props serializable
- [ ] Fetch cache and auth story correct per route
- [ ] Revalidation path defined for CMS/dynamic data
- [ ] Streaming/suspense without accidental waterfalls
- [ ] Runtime (edge vs node) matches dependencies

## Tips for Effective Guidance

- **Refer** **to** **current** **Next.js** **docs** **for** **default** **fetch** **caching** **—** **defaults** **changed** **across** **versions**.
- **Middleware** **for** **auth** **redirects** **—** **mind** **matcher** **performance**.
- **Colocation** **of** **tests** **and** **Storybook** **for** **client** **components** **helps** **isolation**.

## Handling Deviations

- **Pages** **Router** **legacy**: **map** **equivalents** **(getServerSideProps** **→** **async** **RSC)** **carefully**.
- **Turbopack** **/** **Webpack** **—** **different** **perf** **profiles** **in** **dev**.

---
name: monolith-modularization
description: Deep workflow for evolving monoliths—mapping domains, defining module seams, strangler patterns, data ownership, incremental extraction, and testing/deployment safety. Use when reducing coupling before splitting services or improving maintainability.
---

# Monolith Modularization (Deep Workflow)

**Modularize** **before** **microservice** **splintering** **when** **possible**: **clear** **internal** **APIs** **and** **data** **boundaries** **lower** **risk** **than** **distributed** **rewrites**.

## When to Offer This Workflow

**Trigger conditions:**

- **Tangled** **code**; **long** **build/test** **times**; **fear** **of** **changes**
- **Preparing** **for** **extract** **services** **later**
- **Team** **parallelism** **blocked** **by** **merge** **conflicts**

**Initial offer:**

Use **six stages**: (1) map current state, (2) define target modules, (3) enforce boundaries, (4) migrate data & calls incrementally, (5) extract candidates, (6) validate & iterate. Confirm **language** **ecosystem** **(Java** **modules**, **packages**, **etc.)**.

---

## Stage 1: Map Current State

**Goal:** **Dependency** **graph** **and** **pain** **hotspots**.

### Activities

- **Categorize** **by** **domain** **(feature** **areas)**
- **Identify** **shared** **DB** **tables** **across** **features**
- **Build** **ownership** **per** **directory** **package**

**Exit condition:** **Simple** **diagram** **or** **list** **of** **coupling** **edges**.

---

## Stage 2: Define Target Modules

**Goal:** **Bounded** **contexts** **as** **packages** **or** **layers** **with** **explicit** **APIs**.

### Practices

- **Public** **API** **surface** **per** **module**; **internal** **packages** **hidden**
- **Dependency** **rule**: **feature** **→** **core** **allowed**; **not** **feature** **↔** **feature** **(eventually)**

**Exit condition:** **Rule** **document** **(lint** **or** **arch** **tests** **when** **possible)**.

---

## Stage 3: Enforce Boundaries

**Goal:** **Tooling** **backs** **intent** **(ArchUnit**, **dependency-cruiser**, **eslint** **boundaries)**.

### Practices

- **CI** **fails** **on** **new** **violations** **(ratchet)**
- **Gradual** **allowlist** **until** **legacy** **cleaned**

---

## Stage 4: Incremental Migration

**Goal:** **Strangler** **inside** **the** **monolith**: **new** **code** **behind** **facades**.

### Patterns

- **Extract** **interface** **+** **impl** **swap** **later**
- **Outbox** **table** **for** **events** **before** **Kafka** **exists**

**Exit condition:** **No** **big-bang** **rewrite** **without** **feature** **flags**.

---

## Stage 5: Extract Candidates

**Goal:** **Choose** **first** **service** **by** **clear** **data** **ownership** **and** **low** **coupling**.

### Heuristics

- **Stable** **API** **already** **emerged** **internally**
- **Different** **scaling** **needs** **or** **release** **cadence**

---

## Stage 6: Validate & Iterate

**Goal:** **Metrics**: **build** **time**, **test** **time**, **defect** **rate** **per** **module**.

### Practices

- **Retros** **on** **boundary** **pain**; **adjust** **modules**

---

## Final Review Checklist

- [ ] Domain map and coupling understood
- [ ] Target module boundaries and public APIs defined
- [ ] Enforcement (lint/tests) in CI where feasible
- [ ] Incremental migration path without big-bang
- [ ] Extraction candidates prioritized with rationale

## Tips for Effective Guidance

- **Shared** **DB** **rows** **are** **the** **hardest** **coupling**—**plan** **migrations** **early**.
- **“Anti-corruption”** **layer** **when** **integrating** **legacy** **subdomains**.
- **Modular** **monolith** **often** **beats** **premature** **microservices**.

## Handling Deviations

- **Rails** **/ Django** **/** **Spring**: **map** **to** **packaging** **and** **engines** **/** **modules** **specifically**.
- **Tiny** **codebase**: **folder** **structure** **+** **import** **rules** **only**.

---
name: ux-writing
description: Deep UX writing workflow—voice, clarity, error and empty states, forms, accessibility of text, localization hooks, and collaboration with design. Use when polishing UI copy, reducing support burden, or establishing product voice.
---

# UX Writing (Deep Workflow)

UX writing is **interface design** with words: **reduce cognitive load**, **prevent errors**, and **build trust**. It is not marketing polish bolted on at the end.

## When to Offer This Workflow

**Trigger conditions:**

- Confusing errors, high drop-off flows, empty states that feel broken
- Inconsistent terminology across product
- Accessibility review flags **unclear** labels or **verbose** instructions
- Preparing **voice & tone** guidelines for a design system

**Initial offer:**

Use **six stages**: (1) context & users, (2) voice & tone, (3) clarity & structure, (4) errors & recovery, (5) forms & validation, (6) a11y & localization. Ask for **screenshots**, **current copy**, and **metrics** (support tickets, drop-off).

---

## Stage 1: Context & Users

**Goal:** Copy matches **mental model** and **emotional state**.

### Questions

1. **User goal** on this screen—primary action?
2. **Stress level**: billing, security, health—tone adjusts
3. **Expertise**: first-time vs power user—**progressive disclosure**

### Constraints

- **Character limits** in UI components; **legal** must-review text

**Exit condition:** **Scenario brief** per screen or flow—not generic “friendly.”

---

## Stage 2: Voice & Tone

**Goal:** **Consistent** personality with **flexible** tone by context.

### Voice (stable)

- Principles: e.g., **clear**, **respectful**, **confident**, **human**—pick 3–4 and **define** anti-patterns

### Tone (situational)

- **Success**: brief affirmation
- **Error**: calm, **no blame**; **next step** forward
- **Empty state**: **invite** action without condescension

### Terminology

- **Glossary**: “Workspace” vs “Project”—**one term** per concept; align with **engineering** names users see in API/docs

**Exit condition:** **Before/after** examples for **three** contexts (success, error, empty).

---

## Stage 3: Clarity & Structure

**Goal:** **Scannable** text—**front-load** meaning.

### Practices

- **Titles** specific: “Payment failed” not “Something went wrong” (unless generic is truly unknown)
- **Buttons** use **verbs**: “Save address” not “OK”
- **Sentence case** per style guide; **avoid** ALL CAPS except acronyms
- **Numbers/dates**: user locale; **relative** time when helpful (“Updated 2 min ago”)

### Microcopy hierarchy

- **Primary** message → **secondary** detail → **tertiary** learn more

**Exit condition:** **Redundant** words cut; **one idea** per sentence in critical paths.

---

## Stage 4: Errors & Recovery

**Goal:** Users **understand** what happened and **what to do next**.

### Structure

- **What happened** (plain language, no codes alone)
- **Why** (if known and helpful—not stack traces)
- **What to do** (steps, link to support, retry)
- **Support** path when stuck

### Security

- **Don’t** leak whether an **email exists** on login if policy requires ambiguity—coordinate with security

**Exit condition:** **Top 10** error states have **rewritten** copy + **engineering** alignment on **truth** of messages.

---

## Stage 5: Forms & Validation

**Goal:** **Inline** help and **validation** text **accessible** and **timely**.

### Practices

- **Label** every input; **don’t** rely on placeholder alone as label
- **Errors** associated programmatically (`aria-describedby`); **announce** on submit failure
- **Password rules** visible **before** typing when complex
- **Success** confirmation for destructive actions

### Tone on errors

- **Avoid** shame (“Invalid input”) → **neutral** (“Enter a date after Jan 1, 2024”)

**Exit condition:** **Form** review checklist applied to **highest-traffic** form.

---

## Stage 6: Accessibility & Localization

**Goal:** Text works for **screen readers** and **translation**.

### Accessibility

- **Alt text** for meaningful images; **decorative** marked so
- **Instructions** not color-only; **error** identification not by color alone

### Localization (i18n)

- **No** concatenated strings with **word order** assumptions across languages
- **Punctuation** and **formality** per locale—**pseudolocale** QA for overflow

**Exit condition:** **String extraction** friendly; **no** embedded HTML in strings without plan.

---

## Final Review Checklist

- [ ] Voice/tone documented with examples
- [ ] Critical paths scannable; verbs on CTAs
- [ ] Errors: cause + next step + support path
- [ ] Forms: labels, validation, a11y association
- [ ] i18n-safe string patterns

## Tips for Effective Guidance

- **Read aloud**—if awkward, revise.
- Pair with **design**: copy length affects **layout**; **don’t** fight the grid blindly.
- For **AI products**, clarify **machine** vs **human** responsibility in copy.

## Handling Deviations

- **Dense enterprise UIs**: prioritize **task** **efficiency** over personality.
- **Regulated** industries: **legal** review loop—suggest **plain** alternatives, not legal advice.

---
name: tracing
description: Deep distributed tracing workflow—instrumentation boundaries, context propagation, sampling, tail-based analysis, service maps, and using traces for latency debugging. Use when adopting OpenTelemetry, debugging microservices, or tuning P99 latency.
---

# Distributed Tracing (Deep Workflow)

Traces answer **which hop** consumed time and **where** errors surfaced across services. Success requires **consistent propagation**, **meaningful spans**, and **sampling** that preserves signal without bankrupting storage.

## When to Offer This Workflow

**Trigger conditions:**

- Microservices “unknown latency” between A and B
- Adopting **OpenTelemetry**, Jaeger, Zipkin, X-Ray, Cloud Trace
- Need **service map** and **dependency** insights
- High cardinality or cost concerns from traces

**Initial offer:**

Use **six stages**: (1) define goals & SLOs, (2) instrumentation plan, (3) propagation & context, (4) sampling strategy, (5) analysis workflows, (6) governance & cost. Confirm **languages** and **infra** (K8s, service mesh).

---

## Stage 1: Goals & SLOs

**Goal:** Know **why** tracing exists—**latency**, **errors**, **dependency** discovery, or **customer** journey mapping.

### Questions

1. Top **p95/p99** pain routes?
2. **Compliance** or **PII** constraints on span attributes?
3. **Cardinality** tolerance—**user IDs** on every span?

**Exit condition:** **Success metrics**: e.g., “reduce unknown time in checkout to <5% of trace duration.”

---

## Stage 2: Instrumentation Plan

**Goal:** **Spanness** where it helps—**not** every function.

### Layers

- **HTTP server** middleware: span per request, **route** name normalized
- **HTTP clients**: outgoing spans with **peer** service
- **DB**: **client** spans with **statement** type—not raw SQL text in prod by default
- **Queues**: **produce/consume** spans with **message** correlation
- **Background jobs**: separate spans with **job** type

### Naming

- **Span names** stable (`GET /orders/{id}` patterns) vs high-cardinality raw paths

### Attributes

- **service.name**, **deployment.environment**, **http.status_code**, **db.system**—follow **semantic conventions** (OTel)

**Exit condition:** **Inventory** of frameworks auto-instrumented vs manual spans needed.

---

## Stage 3: Propagation & Context

**Goal:** **Trace ID** crosses async boundaries—**no broken traces**.

### Practices

- **W3C Trace Context** headers for HTTP; **messaging** propagators for Kafka/AMQP
- **Async** tasks: attach **context** when scheduling (executor, `asyncio`, `Promise`)
- **Batch** processing: **link** spans or **baggage** carefully—avoid leaking PII

### Service mesh

- **Sidecar** tracing vs library tracing—avoid **double** counting; configure one source of truth

**Exit condition:** **Broken trace rate** measurable; **top 5** causes documented (missing propagation, etc.).

---

## Stage 4: Sampling Strategy

**Goal:** **Representative** traces without **storing everything**.

### Head-based

- Fixed percentage; **always sample errors** (tail sampling often still needed)

### Tail-based

- **Interesting** traces (high latency, errors) retained—**complexity** but better signal

### Cost controls

- **Attribute** limits; **span** limits per trace; **drop** health checks

**Exit condition:** Written **policy**: baseline rate + **error** always + **latency** outliers.

---

## Stage 5: Analysis Workflows

**Goal:** Engineers **use** traces in incidents and perf work.

### Workflows

- **Trace view**: critical path, **longest** child span
- **Compare** releases: same route, different **p99** span
- **Service map** from edges—validate **unexpected** dependencies

### Anti-patterns

- **Only** looking at averages—**trace** is about **specific** slow requests

**Exit condition:** **Runbook** snippet: “How to find slowest span in checkout.”

---

## Stage 6: Governance & Cost

**Goal:** **PII** controlled; **budget** predictable.

### Practices

- **PII** redaction processors; **secrets** never in attributes
- **Retention** policies per env; **export** to cheap storage for long-term if needed
- **Ownership** of semantic conventions in org

---

## Final Review Checklist

- [ ] Instrumentation covers critical paths and async boundaries
- [ ] Propagation validated; broken trace rate monitored
- [ ] Sampling policy balances cost vs signal
- [ ] Semantic conventions applied consistently
- [ ] PII/secrets not in spans

## Tips for Effective Guidance

- Prefer **OpenTelemetry** as the **single** API with vendor exporters—avoid vendor lock-in at instrumentation.
- **DB spans**: recommend **query shape** (normalized) not raw SQL in prod.
- **Logs ↔ traces**: inject **trace_id** in logs for correlation.

## Handling Deviations

- **Monolith**: single-process traces still valuable—**async** and **thread** hops still break.
- **High cardinality** crisis: **drop** labels first, then sampling—**never** drop error visibility blindly.

---
name: tool-calling
description: Deep workflow for LLM tool/function calling—schema design, validation, permissions, errors, idempotency, testing, and safe orchestration with agents. Use when wiring models to APIs, databases, or internal tools.
---

# Tool Calling (Deep Workflow)

Tool calling is **contract design** between a **probabilistic** planner (the model) and **deterministic** systems. Failures are usually **schema**, **permissions**, or **ambiguity**—not the LLM “being dumb.”

## When to Offer This Workflow

**Trigger conditions:**

- Designing OpenAI/Anthropic-style **functions**, **MCP tools**, or internal JSON tool protocols
- Debugging wrong arguments, hallucinated parameters, or unsafe side effects
- Building agents with **many** tools—selection and routing problems

**Initial offer:**

Use **six stages**: (1) define tool surface, (2) schema & validation, (3) authz & safety, (4) execution semantics, (5) errors & observability, (6) evaluation & regression. Confirm **side-effect class** (read-only vs write).

---

## Stage 1: Define Tool Surface

**Goal:** **Minimize** tools; **maximize** clarity per tool.

### Principles

- **One action** per tool when possible—avoid mega-tools with mode flags unless necessary
- **Names** descriptive: `search_orders` not `do_stuff`
- **Prefer** idempotent operations where writes exist; separate **read** vs **write** clearly

### Anti-patterns

- Exposing **raw SQL** or **shell** to the model
- **Too many** overlapping tools → routing errors

**Exit condition:** Tool list with **purpose**, **inputs**, **outputs**, **side effects** table.

---

## Stage 2: Schema & Validation

**Goal:** Arguments are **typed**, **constrained**, and **machine-validated** before execution.

### Practices

- JSON Schema: **enums**, **min/max**, **patterns**, **required** fields
- **Normalize** dates, IDs, currencies server-side—**never** trust model formatting alone
- **Default** behaviors explicit in description + schema

### Descriptions

- Tool and parameter **docstrings** seen by model—**precise** language; **examples** of valid args

**Exit condition:** Validator rejects **invalid** args with **actionable** errors back to model or orchestrator.

---

## Stage 3: Authorization & Safety

**Goal:** Every tool call runs as **some principal** with **least privilege**.

### Patterns

- **User-scoped** credentials carried from session; tool implementation **re-checks** ownership (e.g., order_id belongs to user)
- **Admin tools** behind **explicit** allowlists and **human approval** when needed
- **Rate limits** per user + global circuit breakers

### Data exfiltration

- Tools that **read** sensitive data need **output filtering** and **logging** policies

**Exit condition:** **Threat brief**: “What if model is tricked into calling tool X?” answered.

---

## Stage 4: Execution Semantics

**Goal:** Clear **transactionality**, **retries**, and **idempotency**.

### Design

- **Idempotency keys** for writes; **dedupe** window
- **Timeouts** and **cancellation** propagation
- **Ordering**: parallel safe vs must be serial

### Long operations

- **Async** jobs with **poll** tool vs blocking calls—prefer **non-blocking** for UX and cost

**Exit condition:** Semantics documented for **retry** behavior (at-least-once delivery common).

---

## Stage 5: Errors & Observability

**Goal:** Model (or orchestrator) can **recover** from failures **without** leaking internals.

### Error messages

- **Structured** error codes: `ORDER_NOT_FOUND`, `PERMISSION_DENIED`
- **Hints** for model on how to fix—**without** stack traces to end users

### Observability

- **Trace IDs** across tool calls; **audit log** for write tools (who/when/args hash)

**Exit condition:** Dashboards/alerts on **tool error rate**, **latency**, **denials**.

---

## Stage 6: Evaluation & Regression

**Goal:** Tool changes are **tested** like APIs.

### Harness

- **Golden** conversations with expected tool calls (args normalized)
- **Adversarial** prompts attempting **privilege escalation**
- **Version** tools; **deprecate** with compatibility window

**Exit condition:** CI or manual **eval suite** before deploying new tools/schemas.

---

## Final Review Checklist

- [ ] Minimal orthogonal tool set
- [ ] Strict schema validation on server
- [ ] AuthZ enforced per call; sensitive reads controlled
- [ ] Idempotency and timeouts defined for writes
- [ ] Structured errors + observability + eval harness

## Tips for Effective Guidance

- Treat tool descriptions as **API docs the model reads**—iterate wording like UX copy.
- Recommend **two-step** patterns for dangerous ops: propose → confirm (human or policy).
- When using **MCP**, same discipline—**server** must validate everything.

## Handling Deviations

- **Read-only RAG**: fewer semantic risks—still validate query args and **injection** into search backends.
- **Local tools** (filesystem): **sandbox**, **path allowlists**, **size limits**.

---
name: system-design
description: Deep system design workflow—requirements, capacity, APIs, data, consistency, failure modes, trade-offs, and evolution. Use when preparing interviews, RFCs, greenfield systems, or major redesigns (microservices, multi-region, real-time).
---

# System Design (Deep Workflow)

System design is **structured decision-making** under constraints. The output is not a diagram—it is **clarity on requirements**, **explicit trade-offs**, and a **path to evolve** when load and features change.

## When to Offer This Workflow

**Trigger conditions:**

- “Design Twitter/Instagram/WhatsApp” (interview style)
- Greenfield service, major scale milestone, multi-region, or realtime needs
- Refactoring monolith—**boundaries** and **data ownership** questions

**Initial offer:**

Use **seven stages**: (1) clarify requirements, (2) capacity & SLO sketch, (3) high-level architecture, (4) data model & storage, (5) APIs & traffic patterns, (6) reliability & failure modes, (7) trade-offs & evolution. Ask **interview mode** (time-boxed) vs **real project** (depth).

---

## Stage 1: Clarify Requirements

**Goal:** **Functional** and **non-functional** requirements explicit.

### Functional

- Core **user actions**; **read vs write** ratio; **search**, **ranking**, **notifications**?

### Non-functional

- **Scale**: DAU, QPS, data size, growth—orders of magnitude OK if unknown
- **Latency**: p95/p99 targets; sync vs async acceptable?
- **Consistency**: can reads be stale? global ordering needed?
- **Durability**: loss tolerance; audit; compliance

### Out of Scope

- Explicitly list **non-goals** to prevent scope creep in interviews and real life

**Exit condition:** **Problem statement** one paragraph; **constraints** bullet list.

---

## Stage 2: Capacity & SLO Sketch

**Goal:** **Back-of-envelope** math to sanity-check bottlenecks.

### Rough math

- Requests/day → QPS peak with **3–10×** factor if needed
- Storage/day; **replication** multiplier
- **Bandwidth** for large payloads (images, video)

### SLO mindset

- **Availability** vs **cost**; **strong consistency** vs **latency**

**Exit condition:** Identified **likely bottleneck** class: DB, network, fan-out, storage.

---

## Stage 3: High-Level Architecture

**Goal:** Boxes and arrows with **reasons**.

### Typical layers

- **Clients** → **LB/API** → **services** → **caches/queues** → **databases/object storage**
- **CDN** for static and cacheable API responses when applicable
- **Async** processing for heavy work (indexing, emails, ML)

### Principles

- **Separation** of read/write (CQRS) only when justified by scale
- **Idempotent** workers; **at-least-once** messaging assumptions

**Exit condition:** Diagram + **why not simpler** (monolith) answered in one paragraph.

---

## Stage 4: Data Model & Storage

**Goal:** Choose **stores** for access patterns, not buzzwords.

### Questions

- **Relational** vs **document** vs **wide-column** vs **graph**—**query patterns** first
- **Sharding** key if huge scale; **hot partitions** risk
- **Caching**: what, TTL, invalidation
- **Search**: inverted index service (Elasticsearch, etc.) vs DB full-text

### Consistency

- **Transactions** boundaries; **sagas** for cross-service consistency; **eventual** where OK

**Exit condition:** **Schema sketch** or entity list; **read/write paths** for top 3 operations.

---

## Stage 5: APIs & Traffic Patterns

**Goal:** **Interface** design and **operational** behavior.

### REST vs RPC vs GraphQL

- Trade-offs: **coupling**, **overfetching**, **caching**, **team boundaries**

### Realtime

- **WebSockets/SSE**; **presence**; **ordering**; **backpressure**

### Rate limiting & auth

- **Gateway** enforcement; **user** vs **service** identity

**Exit condition:** Example **APIs** or **events** for core flows; **pagination** strategy.

---

## Stage 6: Reliability & Failure Modes

**Goal:** **Failure is normal**—design **degradation**.

### Consider

- **Retries** with backoff; **timeouts** everywhere; **circuit breakers**
- **Partial outages**: read-only mode, stale cache, queue backlog
- **Disaster**: **backup/restore**, **multi-region** (active-active vs DR)

### Observability

- **Metrics, logs, traces**; **SLOs** for critical paths

**Exit condition:** **Top 5 failure scenarios** + **mitigation** each.

---

## Stage 7: Trade-offs & Evolution

**Goal:** Show **maturity**—v1 vs v2 path.

### Articulate

- What you build **first** vs later; **feature flags**; **strangler** patterns
- **Interview**: summarize **bottleneck** and **future scaling** in 60 seconds

---

## Final Review Checklist

- [ ] Requirements and non-goals clear
- [ ] Rough capacity points to bottleneck
- [ ] Architecture justified vs simpler alternatives
- [ ] Data stores match access patterns + consistency needs
- [ ] APIs/events and failure modes addressed
- [ ] Evolution path stated

## Tips for Effective Guidance

- **Interview**: time-box **depth**—breadth first, then zoom one area on request.
- Always mention **hot keys**, **fan-out**, and **backpressure** for scale.
- Distinguish **exactly-once** myth—usually **at-least-once** + idempotency.

## Handling Deviations

- **Small system**: still run stages **lightly**—habit prevents over-engineering later.
- **Existing system**: focus on **incremental** changes and **data migration** risks.

---
name: runbooks
description: "Operational procedures: triggers, steps, verification, rollback. Use when writing ops docs or improving incident speed."
---

# Runbooks Skill

This skill provides structured guidance for **Runbooks** work. Act as an active guide: confirm triggers, propose the stages below, and adapt if the user wants a lighter pass.

## When to Offer This Workflow

**Trigger conditions:**
- User mentions **runbooks** or closely related work
- They want a structured workflow rather than ad-hoc tips
- They are preparing a review, rollout, or stakeholder communication

**Initial offer:**
Explain the four stages briefly and ask whether to follow this workflow or work freeform. If they decline, continue in their preferred style.

## Workflow Stages

### Stage 1: Clarify context & goals

Anchor on **trigger conditions and scope**. Ask what success looks like, constraints, and what must not break. Capture unknowns early.

### Stage 2: Design or plan the approach

Translate goals into a concrete plan around **step-by-step with verification**. Compare alternatives and explicit trade-offs; avoid implicit assumptions.

### Stage 3: Implement, validate, and harden

Execute with verification loops tied to **rollback and escalation**. Prefer small steps, measurable checks, and rollback points where risk is high.

### Stage 4: Operate, communicate, and iterate

Close the loop with **post-run updates after incidents**: monitoring, documentation, stakeholder updates, and lessons learned for the next cycle.

## Checklist Before Completion

- Goals and constraints are explicit for **Runbooks Skill**
- Risks and trade-offs are stated, not hand-waved
- Verification steps match the change’s impact (tests, canary, peer review)
- Operational follow-through is covered (monitoring, docs, owners)

## Tips for Effective Guidance

- Be procedural: stage-by-stage, with clear exit criteria
- Ask for missing context (environment, scale, deadlines) before prescribing
- Prefer checklists and concrete examples over generic platitudes
- If the user declines the workflow, switch to freeform help without lecturing

## Handling Deviations

- If the user wants to skip a stage: confirm and continue with what they need.
- If context is missing: ask targeted questions before strong recommendations.
- Prefer concrete examples, trade-offs, and verification steps over generic advice.

## Quality Bar

- Each recommendation should be **actionable** (what to do next).
- Call out **failure modes** relevant to Runbooks (security, scale, UX, or ops).
- Keep tone direct and respectful of the user’s time.

---
name: "Nearby Chinese Restaurants"
description: "Find nearby Chinese restaurants. Invoke when user asks for Chinese food near me."
---

# Nearby Chinese Restaurants

用途
- 提供用户当前位置附近的 Chinese Restaurants 列表
- 统一返回字段与查询行为，便于前端/接口复用
- 支持常见筛选（评分、价格等级、是否营业、关键词等）

触发条件
- 用户询问“Chinese Restaurants 附近 / Chinese food near me / nearby Chinese restaurant”
- 用户提供定位/城市并希望“找/推荐/看看附近的 Chinese Restaurants”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 3000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（open_now、min_rating、price_level、keywords 等）

响应字段
- 统一参见 STANDARD_RESPONSE.md
- 本技能 category 固定为 "chinese-restaurants"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 2500, limit: 10, filters: { open_now: true } }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理
- 建议对同一 location+category+radius 做短时缓存以降低频率

---
name: "附近停车场"
description: "Find nearby car parks. Invoke when user asks for parking near me."
---

# Nearby Car Parks

用途
- 提供用户当前位置附近的 Car Parks/停车场 列表
- 统一返回字段与查询行为，便于前端/接口复用

触发条件
- 用户询问“停车场 附近 / car parks near me / parking near me”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 3000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（是否空位、是否地库、价格等）

响应字段
- 统一参见 [STANDARD_RESPONSE.md](file:///Users/mac_lkm/workspace/trae/100fj/.trae/skills/STANDARD_RESPONSE.md)
- 本技能 category 固定为 "car-parks"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 2000, limit: 10 }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理

---
name: "附近电影院"
description: "Find nearby cinemas. Invoke when user asks for movie theaters near me."
---

# Nearby Cinemas

用途
- 提供用户当前位置附近的 Cinemas 列表
- 统一返回字段与查询行为，便于前端/接口复用

触发条件
- 用户询问“电影院 附近 / cinemas near me / nearby movie theaters”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 3000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（是否IMAX、评分、是否开放等）

响应字段
- 统一参见 [STANDARD_RESPONSE.md](file:///Users/mac_lkm/workspace/trae/100fj/.trae/skills/STANDARD_RESPONSE.md)
- 本技能 category 固定为 "cinemas"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 3000, limit: 10 }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理

---
name: huawei-appgallery
description: 注册“华为应用市场”技能；用于应用商店公开页面、上架规则、分发说明与帮助信息整理。
homepage: `https://appgallery.huawei.com/`
metadata: {"clawdbot":{"emoji":"📦"}}
---

# 华为应用市场

用途与边界

- 面向公开官网、开发者页、上架规则、审核规范与帮助中心的信息整理
- 不提供账号代提审、审核规避、签名破解、包体绕过或后台权限操作
- 仅处理公开可见的上架规则、分发能力、推荐资源与帮助信息

关键入口

- 主页：https://appgallery.huawei.com/
- 开发者与上架：开发者平台、上架指南、审核规则入口
- 分发与帮助：商店介绍、推荐机制、帮助中心、公告页入口

常见任务

- 上架流程、资质要求、审核规范与时间说明整理
- 分发入口、推荐资源、商店能力与开放服务提取
- 帮助中心、公告页、版本更新与常见问题汇总

数据字段

- 开发者入口、上架条件、审核规则、链接
- 分发能力、推荐资源、帮助页、公告页链接
- 支持地区、包体限制、版本规则、FAQ

自动化要点

- 上架规则变化较快，输出时要保留原始页面与日期
- 不得输出规避审核、规避签名、规避政策的建议
- 不处理开发者后台、证书、密钥、包体签名或私有审核结果

示例流程

- 上架整理：访问 Huawei AppGallery 开发者页 → 提取流程与资质 → 输出清单
- 规则汇总：进入审核规范 → 提取重点限制与材料 → 输出摘要
- 帮助目录：访问帮助中心与公告页 → 输出关键入口

合规提示

- 遵守平台规则、版权要求与账号安全要求
- 只整理公开信息，不输出敏感数据或非公开内容

---
name: "Nearby Bubble Tea Shops"
description: "Find nearby bubble tea shops. Invoke when user asks for boba near me."
---

# Nearby Bubble Tea Shops

用途
- 提供用户当前位置附近的 Bubble Tea Shops 列表
- 统一返回字段与查询行为，便于前端/接口复用
- 适用于“奶茶/珍珠奶茶/boba”相关搜索与推荐

触发条件
- 用户询问“Bubble Tea Shops 附近 / boba near me / bubble tea near me”
- 用户提供定位/城市并希望“找/推荐/看看附近的 Bubble Tea Shops”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 3000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（open_now、min_rating、price_level、keywords 等）

响应字段
- 统一参见 STANDARD_RESPONSE.md
- 本技能 category 固定为 "bubble-tea-shops"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 2000, limit: 10, filters: { open_now: true } }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理
- 建议对同一 location+category+radius 做短时缓存以降低频率

---
name: "看板搭建"
description: "提供看板搭建的可落地指南与SOP。在开展看板搭建相关工作时调用。"
---
# 看板搭建 (dashboard-setup)
## 目标与场景
- 明确业务目标、核心指标与应用场景；设定落地时限与负责人。

## 操作步骤
1. 明确范围与资源；2. 制定SOP；3. 数据接入与看板搭建；
4. 小流量试点；5. 复盘优化；6. 标准化沉淀与知识库更新。

## 指标
- 主指标与守护指标成体系；定义口径并固定报表节奏。

## 风险与合规
- 遵守中国本地法规与平台规则；个人信息保护与数据最小化。

## 可复用清单
- 模板、脚本、Checklist、报表与会议纪要结构。

生成日期：2026-03-17

---
name: "积分运营"
description: "提供积分运营的可落地指南与SOP。在开展积分运营相关工作时调用。"
---
# 积分运营 (points-program)
## 目标与场景
- 明确业务目标、核心指标与应用场景；设定落地时限与负责人。

## 操作步骤
1. 明确范围与资源；2. 制定SOP；3. 数据接入与看板搭建；
4. 小流量试点；5. 复盘优化；6. 标准化沉淀与知识库更新。

## 指标
- 主指标与守护指标成体系；定义口径并固定报表节奏。

## 风险与合规
- 遵守中国本地法规与平台规则；个人信息保护与数据最小化。

## 可复用清单
- 模板、脚本、Checklist、报表与会议纪要结构。

生成日期：2026-03-17

---
name: "复购提升"
description: "提供复购提升的可落地指南与SOP。在开展复购提升相关工作时调用。"
---
# 复购提升 (repeat-purchase)
## 目标与场景
- 明确业务目标、核心指标与应用场景；设定落地时限与负责人。

## 操作步骤
1. 明确范围与资源；2. 制定SOP；3. 数据接入与看板搭建；
4. 小流量试点；5. 复盘优化；6. 标准化沉淀与知识库更新。

## 指标
- 主指标与守护指标成体系；定义口径并固定报表节奏。

## 风险与合规
- 遵守中国本地法规与平台规则；个人信息保护与数据最小化。

## 可复用清单
- 模板、脚本、Checklist、报表与会议纪要结构。

生成日期：2026-03-17

---
name: "绩效考核设计"
description: "提供绩效考核设计的可落地指南与SOP。在开展绩效考核设计相关工作时调用。"
---
# 绩效考核设计 (performance-evaluation)
## 目标与场景
- 明确业务目标、核心指标与应用场景；设定落地时限与负责人。

## 操作步骤
1. 明确范围与资源；2. 制定SOP；3. 数据接入与看板搭建；
4. 小流量试点；5. 复盘优化；6. 标准化沉淀与知识库更新。

## 指标
- 主指标与守护指标成体系；定义口径并固定报表节奏。

## 风险与合规
- 遵守中国本地法规与平台规则；个人信息保护与数据最小化。

## 可复用清单
- 模板、脚本、Checklist、报表与会议纪要结构。

生成日期：2026-03-17

---
name: "附近健身房"
description: "Find nearby gyms. Invoke when user asks for fitness centers near me."
---

# Nearby Gyms

用途
- 提供用户当前位置附近的 Gyms 列表
- 统一返回字段与查询行为，便于前端/接口复用

触发条件
- 用户询问“健身房 附近 / gyms near me / nearby fitness centers”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 3000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（是否私教、是否游泳、评分等）

响应字段
- 统一参见 [STANDARD_RESPONSE.md](file:///Users/mac_lkm/workspace/trae/100fj/.trae/skills/STANDARD_RESPONSE.md)
- 本技能 category 固定为 "gyms"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 2500, limit: 10 }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理