claude-code-kit 0.7.0__py3-none-any.whl

claude_kit/_payload/skills/incident-postmortem/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: incident-postmortem
+description: Write a blameless postmortem after a production incident. Use when an incident is resolved and needs a root-cause writeup, when conducting an RCA, or when the user says "postmortem", "RCA", "writeup the incident", or "what went wrong". Produces a timeline, 5-whys root cause, contributing factors, and tracked action items.
+---
+
+# Incident Postmortem (blameless)
+
+Turn a resolved incident into durable learning. **Blameless** means the writeup attacks the system and process, never a person — "the deploy lacked a migration gate," not "X forgot the migration." Blame kills the honest reporting that prevents the next outage.
+
+## When to Use
+
+- An incident (SEV1–SEV3) is resolved and needs a writeup.
+- A near-miss worth capturing.
+- The user asks for an RCA / postmortem / "what went wrong."
+
+Pairs with the `incident-responder` agent (it runs the incident; this documents it afterward).
+
+## Process
+
+1. **Reconstruct the timeline** from the incident log (`docs/incidents/...`), git history, deploy records, and the project's structured logs and error-tracking / monitoring tooling. Use UTC; include detection, each action, mitigation, and resolution.
+2. **Find the root cause with 5 Whys** — keep asking "why" past the proximate trigger to the systemic cause. Usually it lands on a missing guardrail/test/alert, not a typo.
+3. **Separate trigger from cause.** The trigger is what set it off; the root cause is why the system allowed it.
+4. **List contributing factors** — what made it worse or slower to detect/fix (no alert, noisy logs, unclear ownership).
+5. **Action items** — each concrete, owned, dated, and ideally a *systemic* fix (a test, an alert, a hook, a gate) so this class of incident can't recur silently. File them to the backlog.
+6. **Promote the lesson** — add a durable entry to `.claude/agent-memory/gotchas/` via `remember` if it's a reusable pitfall (e.g., "migrations must be a separate gated step in prod").
+
+## Template — `docs/incidents/{date}-{slug}-postmortem.md`
+
+```markdown
+# Postmortem: {title}
+**Date:** {date} · **Severity:** SEV{n} · **Duration:** {detect→resolve} · **Author:** {who}
+
+## Summary
+{2–3 sentences: what broke, who was affected, how it was fixed.}
+
+## Impact
+- Users/tenants affected: {scope} · Duration: {time} · Data: {none/at-risk/lost}
+- SLA/SLO breached: {which}
+
+## Timeline (UTC)
+| Time | Event |
+|------|-------|
+| {ts} | {detection — how we found out} |
+| {ts} | {mitigation} |
+| {ts} | {resolved} |
+
+## Root Cause (5 Whys)
+1. Why did it break? …
+2. Why? …  3. Why? …  4. Why? …  5. (systemic) …
+
+**Trigger:** {what set it off}  ·  **Root cause:** {why the system allowed it}
+
+## Contributing Factors
+- {slow detection / missing alert / unclear ownership / …}
+
+## What Went Well / Poorly
+- Well: {fast rollback, good logs}
+- Poorly: {no alert, noisy signal}
+
+## Action Items
+| # | Action (systemic fix preferred) | Owner | Due | Type |
+|---|---------------------------------|-------|-----|------|
+| 1 | Add alert for {symptom} | | | detect |
+| 2 | Add {test/hook/gate} so this can't recur silently | | | prevent |
+```
+
+## Rules
+
+1. **Blameless** — systems and processes, never individuals.
+2. **Every postmortem ends in tracked action items**; a writeup with no follow-ups is theater.
+3. Prefer **systemic** fixes (alert, test, hook, gate) over "be more careful."
+4. Keep it honest about detection/response gaps — that's where the value is.
+
+> Adapted from a portfolio project's incident skill; generalized to be stack-agnostic for claude-kit.

claude_kit/_payload/skills/incremental-implementation/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: incremental-implementation
+description: Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step.
+---
+
+# Incremental Implementation
+
+## Overview
+
+Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.
+
+## When to Use
+
+- Implementing any multi-file change
+- Building a new feature from a task breakdown
+- Refactoring existing code
+- Any time you're tempted to write more than ~100 lines before testing
+
+**When NOT to use:** Single-file, single-function changes where the scope is already minimal.
+
+## The Increment Cycle
+
+```
+┌──────────────────────────────────────┐
+│                                      │
+│   Implement ──→ Test ──→ Verify ──┐  │
+│       ▲                           │  │
+│       └───── Commit ◄─────────────┘  │
+│              │                       │
+│              ▼                       │
+│          Next slice                  │
+│                                      │
+└──────────────────────────────────────┘
+```
+
+For each slice:
+
+1. **Implement** the smallest complete piece of functionality
+2. **Test** — run the project's test suite (or write a test if none exists)
+3. **Verify** — confirm the slice works as expected (tests pass, build succeeds, manual check)
+4. **Commit** -- save your progress with a descriptive message (see `git-workflow-and-versioning` for atomic commit guidance)
+5. **Move to the next slice** — carry forward, don't restart
+
+## Slicing Strategies
+
+### Vertical Slices (Preferred)
+
+Build one complete path through the stack:
+
+```
+Slice 1: Create a task (DB + API + basic UI)
+    → Tests pass, user can create a task via the UI
+
+Slice 2: List tasks (query + API + UI)
+    → Tests pass, user can see their tasks
+
+Slice 3: Edit a task (update + API + UI)
+    → Tests pass, user can modify tasks
+
+Slice 4: Delete a task (delete + API + UI + confirmation)
+    → Tests pass, full CRUD complete
+```
+
+Each slice delivers working end-to-end functionality.
+
+### Contract-First Slicing
+
+When backend and frontend need to develop in parallel:
+
+```
+Slice 0: Define the API contract (types, interfaces, API spec)
+Slice 1a: Implement backend against the contract + API tests
+Slice 1b: Implement frontend against mock data matching the contract
+Slice 2: Integrate and test end-to-end
+```
+
+### Risk-First Slicing
+
+Tackle the riskiest or most uncertain piece first:
+
+```
+Slice 1: Prove the WebSocket connection works (highest risk)
+Slice 2: Build real-time task updates on the proven connection
+Slice 3: Add offline support and reconnection
+```
+
+If Slice 1 fails, you discover it before investing in Slices 2 and 3.
+
+## Implementation Rules
+
+### Rule 0: Simplicity First
+
+Before writing any code, ask: "What is the simplest thing that could work?"
+
+After writing code, review it against these checks:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+- Am I building for hypothetical future requirements, or the current task?
+
+```
+SIMPLICITY CHECK:
+✗ Generic EventBus with middleware pipeline for one notification
+✓ Simple function call
+
+✗ Abstract factory pattern for two similar components
+✓ Two straightforward components with shared utilities
+
+✗ Config-driven form builder for three forms
+✓ Three form components
+```
+
+Three similar lines of code is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests.
+
+### Rule 0.5: Scope Discipline
+
+Touch only what the task requires.
+
+Do NOT:
+- "Clean up" code adjacent to your change
+- Refactor imports in files you're not modifying
+- Remove comments you don't fully understand
+- Add features not in the spec because they "seem useful"
+- Modernize syntax in files you're only reading
+
+If you notice something worth improving outside your task scope, note it — don't fix it:
+
+```
+NOTICED BUT NOT TOUCHING:
+- src/utils/format.ts has an unused import (unrelated to this task)
+- The auth middleware could use better error messages (separate task)
+→ Want me to create tasks for these?
+```
+
+### Rule 1: One Thing at a Time
+
+Each increment changes one logical thing. Don't mix concerns:
+
+**Bad:** One commit that adds a new component, refactors an existing one, and updates the build config.
+
+**Good:** Three separate commits — one for each change.
+
+### Rule 2: Keep It Compilable
+
+After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.
+
+### Rule 3: Feature Flags for Incomplete Features
+
+If a feature isn't ready for users but you need to merge increments:
+
+```typescript
+// Feature flag for work-in-progress
+const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
+
+if (ENABLE_TASK_SHARING) {
+  // New sharing UI
+}
+```
+
+This lets you merge small increments to the main branch without exposing incomplete work.
+
+### Rule 4: Safe Defaults
+
+New code should default to safe, conservative behavior:
+
+```typescript
+// Safe: disabled by default, opt-in
+export function createTask(data: TaskInput, options?: { notify?: boolean }) {
+  const shouldNotify = options?.notify ?? false;
+  // ...
+}
+```
+
+### Rule 5: Rollback-Friendly
+
+Each increment should be independently revertable:
+
+- Additive changes (new files, new functions) are easy to revert
+- Modifications to existing code should be minimal and focused
+- Database migrations should have corresponding rollback migrations
+- Avoid deleting something in one commit and replacing it in the same commit — separate them
+
+## Working with Agents
+
+When directing an agent to implement incrementally:
+
+```
+"Let's implement Task 3 from the plan.
+
+Start with just the database schema change and the API endpoint.
+Don't touch the UI yet — we'll do that in the next increment.
+
+After implementing, run the project's tests and build to verify
+nothing is broken."
+```
+
+Be explicit about what's in scope and what's NOT in scope for each increment.
+
+## Increment Checklist
+
+After each increment, verify:
+
+- [ ] The change does one thing and does it completely
+- [ ] All existing tests still pass (run the project's test runner)
+- [ ] The build succeeds (run the project's build)
+- [ ] Type checking passes (run the project's type checker)
+- [ ] Linting passes (run the project's linter)
+- [ ] The new functionality works as expected
+- [ ] The change is committed with a descriptive message
+
+**Note:** Run each verification command after a change that could affect it. After a successful run, don't repeat the same command unless the code has changed since — re-running on unchanged code adds no information.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. |
+| "It's faster to do it all at once" | It *feels* faster until something breaks and you can't find which of 500 changed lines caused it. |
+| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. |
+| "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. |
+| "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. |
+| "Let me run the build command again just to be sure" | After a successful run, repeating the same command adds nothing unless the code has changed since. Run it again after subsequent edits, not as reassurance. |
+
+## Red Flags
+
+- More than 100 lines of code written without running tests
+- Multiple unrelated changes in a single increment
+- "Let me just quickly add this too" scope expansion
+- Skipping the test/verify step to move faster
+- Build or tests broken between increments
+- Large uncommitted changes accumulating
+- Building abstractions before the third use case demands it
+- Touching files outside the task scope "while I'm here"
+- Creating new utility files for one-time operations
+- Running the same build/test command twice in a row without any intervening code change
+
+## Verification
+
+After completing all increments for a task:
+
+- [ ] Each increment was individually tested and committed
+- [ ] The full test suite passes
+- [ ] The build is clean
+- [ ] The feature works end-to-end as specified
+- [ ] No uncommitted changes remain

claude_kit/_payload/skills/interview-me/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: interview-me
+description: Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists.
+---
+
+# Interview Me
+
+## Overview
+
+What people ask for and what they actually want are different things. They ask for "a dashboard" because that's what one asks for, not because a dashboard solves their problem. They say "make it faster" without a number to hit.
+
+The cheapest moment to find this gap is before any plan, spec, or code exists. Once you've started building, switching costs are real, and the user will rationalize the wrong thing into a "good enough" thing. The misfit gets locked in.
+
+This skill closes the gap before it costs anything. The other Define-phase skills assume you already know roughly what you want: `idea-refine` generates variations from an idea, `spec-driven-development` writes the requirements down, `doubt-driven-development` stress-tests a plan after you've drafted one. Interview-me is the part before all of those, where you ask one question at a time, with your best guess attached, until you can predict what the user is going to say before they say it.
+
+## When to Use
+
+Apply this skill when:
+
+- The ask is missing at least one of: **who** the user is, **why** they want it, what **success** looks like, what the binding **constraint** is
+- The request is conventional rather than specific ("build me X", "make it faster") and you can't unpack the convention without guessing
+- You're tempted to start with assumptions you haven't surfaced
+- The user hasn't said which value they're optimizing for when two reasonable ones are in tension (simplicity vs. flexibility, cost vs. speed)
+- The user explicitly invokes: "interview me", "grill me", "before we start, are we sure?", "stress-test my thinking"
+
+**When NOT to use:**
+
+- The ask is unambiguous and self-contained ("rename this variable", "fix this typo")
+- The user has explicitly asked for speed over verification
+- Pure information requests ("how does X work?", "what does this code do?")
+- Mechanical operations (renames, formats, file moves)
+- You already have ≥95% confidence; re-read the stop condition below before assuming you don't
+
+## Loading Constraints
+
+This skill needs a live, responsive user. **Do not invoke in non-interactive contexts** like CI pipelines, scheduled runs, `/loop`, or autonomous-loop. If you're in one of those and the ask is underspecified, flag that as a blocker for the user instead of guessing.
+
+## The Process
+
+### Step 1: Hypothesize, with a confidence number
+
+Before asking anything, write down your current best read of what the user wants in **one sentence**, plus an honest confidence number (0–100%):
+
+```
+HYPOTHESIS: You want a way to answer "how are we doing?" in standup, and "dashboard" was the convention that came to mind.
+CONFIDENCE: ~30%
+```
+
+The number forces honesty. If you wrote down a high number but can't actually predict the user's reactions to the next three questions you'd ask, the number is wrong. Start at the confidence level you can defend.
+
+### Step 2: Ask one question at a time, each with a guess attached
+
+Format:
+
+```
+Q: <one focused question>
+GUESS: <your hypothesis for the answer, with the reasoning that produced it>
+```
+
+Wait for the user to react before asking the next question.
+
+**Why one at a time, not a batch:**
+
+- The user can't react to your hypotheses if you bury them in a list
+- Batches encourage skim-reading and surface answers
+- The third question often depends on the answer to the first; asking them all at once locks in the wrong framing
+- The user's energy for thinking carefully is finite; spend it one question at a time
+
+**Why attach a guess:**
+
+- The user reacts faster to a wrong guess than they generate an answer from scratch
+- It commits you to a hypothesis you can be visibly wrong about, which keeps you honest
+- It surfaces *your* assumptions, which is what the interview is meant to expose
+
+The risk here is a polite user agreeing with your guess to be agreeable. Mitigate by being visibly willing to be wrong, and occasionally guess in a direction you expect the user to push back on.
+
+### Step 3: Listen for "want vs. should want"
+
+The most dangerous answers are the ones where the user says what a thoughtful answer *sounds like* rather than what they actually want. Watch for:
+
+- Answers that pattern-match best-practice talk ("I want it to be scalable", "clean architecture") without specifics
+- Answers that defer to convention ("the way most apps do it", "the standard approach")
+- Phrases like "I should probably…", "I think I'm supposed to…", "good engineering practice says…"
+- Buzzwords as goals — when "modern", "scalable", "robust" are the answer instead of a specific outcome
+
+When you hear these, the question to ask is:
+
+> *"If you didn't have to justify this to anyone, what would you actually want?"*
+
+That single question often does more work than the previous five.
+
+### Step 4: Restate intent in the user's own words
+
+When your confidence is high, write back what you now think the user wants. Keep it tight (5–8 lines), use their language where possible, and structure it so the user can confirm or correct line by line:
+
+```
+Here's what I now think you want:
+
+- Outcome:      <one line>
+- User:         <one line — who benefits>
+- Why now:      <one line — what changed>
+- Success:      <one line — how we know it worked>
+- Constraint:   <one line — the binding limit>
+- Out of scope: <one line — what we're explicitly not doing>
+
+Yes / no / refine?
+```
+
+Including "Out of scope" is non-negotiable. Half of misalignment is silent disagreement about what is *not* being built.
+
+### Step 5: Confirm — explicit yes, not "whatever you think"
+
+The gate is an explicit "yes." The following are **not** yes:
+
+- "Whatever you think is best." → The user is delegating, which means they don't have 95% confidence either. Re-ask with two concrete options framed as a choice.
+- "Sounds good." → Ambiguous. Ask: "Anything you'd refine?" Silence isn't confirmation.
+- "Sure, let's go." → Often a polite exit, not an endorsement. Same follow-up.
+- Silence followed by "okay let's start." → The user has given up on the interview, not converged. Stop and ask whether you've missed something.
+
+If they correct you, fold the correction in and restate. Loop until you get an explicit yes.
+
+### The 95% Confidence Stop
+
+You're done when you can answer yes to this:
+
+> *Can I predict the user's reaction to the next three questions I would ask?*
+
+If yes, you have shared understanding. Stop interviewing and produce the restate. If no, you're not done; ask the next question.
+
+This is a checkable test, not a vibe. It also has a floor: if you've gone several rounds and still can't predict, that's information about the ask, not a reason to keep grinding. Stop and tell the user: "I've asked X questions and I still can't predict your reactions. Something foundational is missing. Want to step back?"
+
+## Output
+
+The output of this skill is a **confirmed statement of intent**: the restate from Step 4, with an explicit yes from Step 5. That's the deliverable. Specs, plans, and task lists are downstream; they consume the intent this skill produces.
+
+If the user wants the intent to persist (a multi-session project, a handoff to another collaborator), offer to save it to `docs/intent/[topic].md`. Only save if they confirm.
+
+## Example
+
+A short before-and-after.
+
+**Without `interview-me`:**
+
+```
+User:  build me a dashboard for our metrics
+Agent: <starts proposing chart libraries and layouts>
+```
+
+The agent has assumed: who it's for, what metrics, what "for our team" means, what success looks like. None of these are stated. Every assumption is a place the user can later say "that's not what I meant."
+
+**With `interview-me`:**
+
+```
+User: build me a dashboard for our metrics
+
+Agent:
+HYPOTHESIS: You want a way to answer "how are we doing?" in standup, and "dashboard" came to mind because that's the conventional answer.
+CONFIDENCE: ~30%
+
+Q:     When you say "how are we doing?", who's asking — you alone, the engineering team in standup, or up the chain (e.g., your manager, an exec, a board)?
+GUESS: engineering team in standup, because "we" usually scopes that way and standups are where this question gets asked. If it's for execs the metrics and the framing change a lot.
+
+User: It's actually for me. I keep losing track of which experiments are running and what their early signal looks like.
+
+Agent:
+Updated read: not a team dashboard at all. It's a personal experiment tracker. Confidence: ~60%.
+
+Q:     Is the gap that you don't know which experiments exist, or that you can't see their results in one place?
+GUESS: the second one. You have a list of experiments somewhere, but their results live in five different tools, and reconciling them by hand is what you're tired of.
+
+User: First one actually. I literally don't have a list. They're spread across different docs.
+
+Agent: <continues>
+```
+
+Two questions in, the agent has discovered the actual ask isn't "a dashboard." It's "a list." Different artifact, different scope, different work. The dashboard would have been wrong.
+
+## Interaction with Other Skills
+
+- **`idea-refine`**: downstream. If the confirmed intent is "I want X but I don't know how to scope it," hand off to `idea-refine` to generate variations against the now-explicit intent.
+- **`spec-driven-development`**: downstream. If the confirmed intent is concrete ("I want X for Y users with Z success criteria"), hand off to `spec-driven-development` to write it down.
+- **`planning-and-task-breakdown`**: two hops downstream of this skill (after the spec).
+- **`doubt-driven-development`**: opposite end of the timeline. Interview-me is pre-decision intent extraction; doubt-driven is post-decision artifact review. Both catch divergence, but at different moments.
+- **`source-driven-development`**: orthogonal. Interview-me clarifies what the user wants; SDD verifies framework facts. They don't compete.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The ask is clear enough" | If you can't write the user's desired outcome in one sentence right now, the ask isn't clear. Run Step 1 before deciding. |
+| "Asking too many questions wastes their time" | Time wasted by 4–6 targeted questions is small. Time wasted by building the wrong thing is enormous, and the user is the one bearing that cost. |
+| "I'll figure it out as I build" | Switching costs after code exists are 10x what they are now. Discovery during implementation is rework. |
+| "They said 'whatever you think,' so I should just decide" | "Whatever you think" is delegation, not decision. Re-ask with two concrete options as a choice. |
+| "I should give them several options to pick from" | Options work when the user knows what they want and is choosing between trade-offs. They don't know what they want yet. Listing options widens the search; asking narrows it. |
+| "If I attach my guess, I'm leading them" | Leading is the point. Reacting is faster than generating from scratch. The risk is sycophancy, not leading; mitigate by being visibly willing to be wrong. |
+| "We've talked enough, I get it" | Test it: can you predict their reaction to the next three questions? If not, you don't get it yet. |
+| "The user said yes, we're done" | If the yes followed a vague restate or an open-ended "sounds good," the yes is hollow. Restate concretely and re-confirm. |
+
+## Red Flags
+
+- Three or more questions in a single message: that's batching, not interviewing
+- A question without your hypothesis attached: that's surveying, not committing
+- Accepting "whatever you think is best" as a terminal answer
+- Producing a spec, plan, or task list before the user has explicitly confirmed your restate
+- Questions framed as "what would be best practice?" instead of "what do you actually want?"
+- The user gives a sophistication-signaling answer ("scalable", "clean", "modern") and you accept it without probing whether it's what they actually want
+- Three or more rounds without your confidence visibly rising: you're asking the wrong questions, step back and reframe
+- Saving the intent doc before the user has confirmed (the doc itself implies a yes the user didn't give)
+- Skipping the "Out of scope" line in the restate (silent disagreement about non-goals is half of misalignment)
+
+## Verification
+
+After applying interview-me:
+
+- [ ] An explicit hypothesis with a confidence number was stated in the first turn
+- [ ] Questions were asked one at a time, each with the agent's guess attached
+- [ ] At least one "what would you actually want if you didn't have to justify it?" probe ran when the user gave a sophistication-signaling or convention-signaling answer
+- [ ] A concrete restate (Outcome / User / Why now / Success / Constraint / Out of scope) was written back to the user
+- [ ] The user confirmed the restate with an explicit yes (not "whatever you think," not "sounds good," not silence)
+- [ ] At the stop point, the agent could predict reactions to the next three questions it would ask
+- [ ] Any handoff to a downstream skill (`idea-refine`, `spec-driven-development`) was framed in terms of the confirmed intent, not the original underspecified ask

claude_kit/_payload/skills/load-testing/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: load-testing
+description: Load and stress test API endpoints under concurrency. Use when measuring throughput/latency under load, validating an SLO before launch, sizing the connection pool, or hunting a performance cliff. Covers ramp profiles, thresholds (p95/p99 latency, error rate), authenticated + rate-limited endpoints, and reading results. Distinct from frontend performance-optimization (web vitals/bundles).
+---
+
+# Load Testing
+
+Measure how a service behaves under concurrency — before users find the cliff. This is the missing
+half of the kit's performance story: `performance-optimization` covers the **frontend** (web vitals,
+bundles, rendering); this skill drives **concurrent load against an API** to validate the SLOs that
+`.claude/rules/devops-observability.md` and the `observability-engineer` define. Most cliffs are
+data-layer bound, so if your stack ships a DB-performance reviewer or rule, cross-check it.
+
+## When to Use
+
+- Before a launch, or after a change to a hot endpoint.
+- To validate an SLO ("p95 `POST /api/...` < 200ms at 50 rps").
+- To size the service's connection-pool and worker settings.
+- To reproduce a latency/timeout complaint under controlled load.
+
+## Tool
+
+Use whatever load tool the project standardizes on — **k6** (lightweight, scriptable, good
+thresholds) and **Locust** (scenarios in Python) are common choices. The methodology below is
+tool-agnostic; the example uses k6. Adapt the routes, auth, and tool to your stack.
+
+```javascript
+// example (k6):  k6 run load/login-and-list.js   — adapt routes/auth to your API
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+const BASE = __ENV.BASE || 'http://localhost:8000';
+
+export const options = {
+  scenarios: {
+    ramp: { executor: 'ramping-vus', startVUs: 0,
+      stages: [ { duration: '30s', target: 50 }, { duration: '2m', target: 50 }, { duration: '30s', target: 0 } ] },
+  },
+  thresholds: {
+    http_req_failed: ['rate<0.01'],                 // < 1% errors
+    'http_req_duration{name:list}': ['p(95)<200'],  // p95 < 200ms on the list call
+  },
+};
+
+export function setup() {
+  // If the API uses cookie/session or token auth, authenticate ONCE here and reuse per VU.
+  const res = http.post(`${BASE}/api/login`,
+    JSON.stringify({ email: __ENV.EMAIL, password: __ENV.PASSWORD }),
+    { headers: { 'Content-Type': 'application/json' } });
+  check(res, { 'login 200': (r) => r.status === 200 });
+  return { cookies: res.cookies };
+}
+
+export default function (data) {
+  const res = http.get(`${BASE}/api/items`, { jar: http.cookieJar(), tags: { name: 'list' } });
+  check(res, { 'list 200': (r) => r.status === 200 });
+  sleep(1);
+}
+```
+
+## Method
+
+1. **Pick the target + SLO.** One endpoint/flow per test; define the pass threshold up front (p95 latency, error rate, target rps).
+2. **Use realistic data + auth.** Authenticate once and reuse the session/token. Seed realistic data so any tenant-scoped or filtered queries hit realistic row counts.
+3. **Mind rate limits.** Throttled endpoints (e.g. auth) — either test below the limit, or test the limiter itself deliberately and expect 429s.
+4. **Ramp, don't spike** (unless spike is the test). Warm up, hold, ramp down.
+5. **Watch the service while it runs:** tail the service's logs, the database's active-connection count, and CPU. The bottleneck is usually the data layer (N+1, missing index, pool exhaustion) — cross-check your stack's DB-performance guidance.
+6. **Read results:** p95/p99 (not just avg), error rate, throughput plateau. A latency knee as concurrency climbs = saturation (pool/CPU/lock).
+
+## Thresholds to start from
+
+- Error rate < 1% under target load.
+- p95 within the endpoint's SLO; p99 no more than ~2–3× p95 (bigger gap = tail problems).
+- Throughput scales with concurrency until a plateau — find where it flattens.
+
+## Rules
+
+1. **Never load-test production** without explicit approval — test a staging/local stack. See `.claude/rules/human-in-the-loop.md`.
+2. Tie every run to an SLO; a load test without a pass/fail threshold is just noise.
+3. When you find a cliff, hand the specifics to the data-layer/dev lane — don't guess the fix here.
+4. Keep scripts in `load/`; record the run + result in `docs/performance/`.
+
+> Adapted from a portfolio project's load-testing skill; generalized to be stack- and tool-agnostic for claude-kit.