swe-workflow-skills 0.1.0 → 0.3.0

package/skills/browser-verification/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "browser-verification",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just finished implementing the new signup form (client validation + POST to /api/users + success toast). Unit tests pass. Can you verify it actually works in the browser before I open the PR?",
+      "expected_output": "Defines the proving flow (fill form → submit → 201 → toast → user exists), runs the real stack with seeded/realistic state, drives the flow interactively (typing, submitting — not just loading the page), watches console errors, network requests (endpoint, payload, status), and UI state, exercises validation errors and double-submit, and reports with evidence (screenshots, zero-console-errors statement, observed network results) rather than 'looks good'",
+      "assertions": [
+        "Defines the user-visible flow that proves the change (form fill → submit → success), not just that the page loads",
+        "Runs the actual app stack with realistic state and drives the flow interactively — typing into fields and submitting, via automation or manual clicking",
+        "Checks all three evidence channels: console errors, network requests (endpoint/payload/status), and the rendered UI outcome",
+        "Exercises non-happy paths relevant to the change, such as validation errors and double-submit or backend failure",
+        "Reports in evidence terms — screenshots and observed results (e.g. 'POST /api/users returned 201, toast rendered, zero console errors') — before declaring it works"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "QA says the orders dashboard 'sometimes shows nothing' but every time I open it, it looks fine and there are no errors in our logs. Verify whether the page is actually broken.",
+      "expected_output": "Recognizes 'works on my visit' isn't verification of the failure condition: reproduces the states where lists show nothing — empty data, slow API (throttled loading state), failed request (5xx/CORS with the error swallowed client-side), auth/role differences, race on refresh/back — while watching the browser console and network tab (server logs won't show client-side failures), and either reproduces it with evidence or reports precisely which states were exercised and ruled out",
+      "assertions": [
+        "Recognizes that the page rendering fine on one visit does not rule out state-dependent failure, and enumerates candidate states: empty data, slow/failed API responses, auth/role differences, or refresh/back races",
+        "Uses browser-side evidence (console, network tab) explicitly noting that server logs miss client-side failures like swallowed errors or CORS",
+        "Manipulates state to reproduce — seeding empty data, throttling, or forcing API failure — rather than only reloading the page",
+        "Checks the loading and empty states specifically (infinite spinner or blank-on-empty are classic 'shows nothing' causes)",
+        "Concludes with evidence: either a reproduced failure with its trigger, or a precise list of exercised-and-passing states — not 'seems fine'"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We need proper automated e2e coverage for our whole checkout funnel — browse, cart, payment, confirmation — running in CI on every PR. Set up the test strategy.",
+      "expected_output": "Recognizes this as designing a persistent automated test suite — refers to test-suite-design for the e2e strategy/infrastructure (and cicd-pipeline for the CI wiring), stating the boundary: browser-verification is the one-off evidence pass on the change in front of you; persistent suites are test-suite-design's domain",
+      "assertions": [
+        "Recognizes the request as persistent automated e2e suite design, not a one-off verification pass",
+        "Refers to the test-suite-design skill for the suite strategy (optionally cicd-pipeline for CI integration)",
+        "Does not respond with a single manual/ad-hoc browser verification session as the answer",
+        "States or implies the boundary: browser-verification verifies the change at hand; test-suite-design builds the lasting coverage"
+      ]
+    }
+  ]
+}

package/skills/build-vs-buy/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: build-vs-buy
+description: "Decide whether to build in-house, buy a vendor/SaaS product, or adopt OSS — core-vs-commodity framing, multi-year total cost of ownership, integration and maintenance burden, vendor viability, lock-in and exit costs. Triggers: build vs buy, build or buy, vendor evaluation, SaaS vs in-house, should we adopt this open source, TCO, total cost of ownership, lock-in, exit cost, make or buy, off the shelf. Internal-structure decisions (patterns, service boundaries, ADRs for your own code) → architecture-design."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit, WebFetch, WebSearch
+---
+
+# Build vs Buy
+
+Make the build/buy/adopt decision on total cost and strategic fit, not on
+whichever option the room already favors. The two systematic errors this skill
+exists to counter: engineers underestimate the *ongoing* cost of building
+(maintenance routinely exceeds the initial build within a few years), and
+everyone underestimates the *exit* cost of buying (discovered only when
+leaving). Boundary: this skill decides whether the capability comes from
+outside; how you structure your own code is `architecture-design`'s ADR
+territory, and vetting an individual library is `dependency-management`.
+
+## Workflow
+
+### Step 1: Frame the Capability — Core or Commodity?
+
+Name the capability precisely, then ask the question that dominates the whole
+decision: **does doing this better than anyone else win you customers?** If yes
+(core differentiator), building earns strategic control; if it's commodity
+plumbing (auth, feature flags, payments, analytics infra, CRUD admin), every
+engineer-month spent building it is a month not spent on what differentiates
+you. Then split requirements into *must-have* and *nice-to-have* — a vendor
+covering 90% of must-haves usually beats a build covering 100% of a wishlist.
+
+### Step 2: Inventory the Real Options
+
+There are usually more than two:
+
+- **Build** in-house
+- **Buy** a vendor/SaaS product
+- **Adopt** OSS self-hosted (you're not buying — you're taking an operations job)
+- **Hybrid** — buy/adopt the commodity core, build the thin differentiating layer
+- **Defer** — do nothing yet; a legitimate option when the need is unproven
+
+Verify current facts (pricing, licensing, maintenance status) with live sources
+— vendor pricing pages and OSS repos, not memory.
+
+### Step 3: TCO Over 3 Years — Not the Sticker Price
+
+Cost each finalist over a 3-year horizon; year-1 comparisons systematically
+favor building (the build cost is visible, the ownership cost isn't):
+
+- **Build**: initial engineering + **ongoing ownership** (maintenance, on-call,
+  security patching, feature parity as needs grow — commonly comparable to the
+  initial build per year for actively-used systems) + **opportunity cost** (what
+  those engineers would otherwise ship — usually the largest and least-counted line).
+- **Buy**: subscription *at projected usage*, not today's (model the pricing
+  curve at 3× growth — usage-based pricing is where vendors recover their
+  discounts) + integration + admin.
+- **Adopt (OSS)**: hosting + operations + upgrades + security response + the
+  expertise to run it; "free" describes the license, not the ownership.
+- **Everyone forgets**: migration of existing data/flows, training, compliance
+  and security review, vendor management overhead.
+
+### Step 4: Risk — Lock-in, Exit, and Viability
+
+Write the **exit plan now**, while you have leverage — the exit cost you can't
+estimate is the one that traps you:
+
+- What does leaving take? Data export (format? completeness? egress fees?),
+  proprietary APIs/features you'd re-implement, contract terms (lock-in period,
+  auto-renewal, price-increase caps).
+- **Vendor viability**: funding/profitability, roadmap alignment, acquisition
+  risk, what happens to your data if they fold.
+- **OSS health**: maintainer bus factor, release cadence, CVE responsiveness,
+  license (copyleft implications, and watch relicensing-to-source-available
+  history in the space) — delegate a deep package-level check to `dependency-management`.
+- **Build risk** is real too: key-person dependency, and the "internal vendor"
+  failure mode — a team obligated to maintain a product nobody funds.
+
+### Step 5: Decide and Record
+
+Score the finalists in a weighted matrix — criteria and weights fixed *before*
+scoring (after, the matrix just rationalizes the favorite). State a clear
+recommendation with the dominant reasons, name the runner-up and what would
+have flipped the decision, and set a **revisit trigger** ("revisit if usage
+exceeds X / pricing changes >Y% / the maintainer goes dark"). Record it like an
+ADR — decision, context, alternatives, consequences — so the next team
+understands *why*, not just *what*.
+
+### Step 6: De-risk Before Committing
+
+For close calls or large commitments, run a time-boxed pilot against your top
+must-haves and your real data volumes before signing multi-year terms or
+staffing a build. A two-week PoC is the cheapest insurance in this workflow —
+and pilot the *exit* too (run the data export once and look at what comes out).
+
+## Principles Applied
+
+- **Commodity → buy bias; differentiator → build bias** — most wrong decisions
+  invert this because building is more fun than integrating.
+- **Compare TCO, not sticker price** — the build's cost is mostly after launch;
+  the vendor's is mostly at renewal and exit.
+- **A decision without a revisit trigger is dogma** — pricing, vendors, and
+  your scale all change.
+
+## Cross-Skill References
+
+- `architecture-design` — internal-structure decisions and the ADR format
+- `dependency-management` — deep evaluation of a specific library/package
+- `project-proposal` — wrap the decision in a business case for approval
+- `effort-estimation` — sizing the build option honestly
+- `strategic-review` — when the decision touches positioning or the moat

package/skills/build-vs-buy/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "build-vs-buy",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We need feature flags for our product (SaaS, ~15 engineers, growing fast). Should we build our own flag service, buy LaunchDarkly, or self-host an open-source option like Unleash? Help me decide.",
+      "expected_output": "Frames feature flags as commodity infrastructure (core-vs-differentiator test), compares all three options on a multi-year TCO including ongoing ownership for build, projected-usage pricing for buy, and operations burden for self-hosted OSS, examines lock-in and exit costs plus vendor/OSS health, and lands on a clear recommendation recorded like an ADR with a revisit trigger",
+      "assertions": [
+        "Applies the core-vs-commodity framing — asks or determines whether feature flags differentiate this product (they don't) and lets that bias the decision",
+        "Compares build, buy, and OSS-adopt on total cost of ownership over a multi-year horizon, including ongoing maintenance/ownership for build and operations burden for self-hosted OSS — not just sticker price",
+        "Models the buy option at projected usage/growth, not only today's seat or flag count",
+        "Addresses lock-in and exit costs (data/config export, proprietary features, contract terms) and vendor or OSS project health",
+        "Concludes with a clear recommendation, the runner-up and what would flip it, and a revisit trigger — recorded in an ADR-like decision format"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our data team already spent two quarters building about 60% of an in-house analytics pipeline (ingestion works, transformation layer is half done). Meanwhile Fivetran + Snowflake + dbt Cloud would cover everything we planned for roughly $8k/month. Do we finish the build or switch? Leadership hates the idea of throwing away six months of work.",
+      "expected_output": "Treats the six months as sunk cost and evaluates only forward-looking costs: remaining build effort plus perpetual ownership (maintenance, on-call, feature parity) and the team's opportunity cost, versus migration effort plus the subscription at projected data volumes — including the vendor stack's lock-in/exit profile — and gives a clear recommendation with reasoning rather than an 'it depends' hedge",
+      "assertions": [
+        "Explicitly identifies the completed 60% as sunk cost and excludes it from the forward-looking comparison",
+        "Compares remaining-build-plus-ongoing-ownership cost (maintenance, on-call, opportunity cost of the data team) against migration-plus-subscription cost",
+        "Models the managed stack's subscription at projected data growth and examines its lock-in and exit costs, not just the $8k/month figure",
+        "Considers what the team would work on instead (opportunity cost) as a first-class factor in the decision",
+        "Delivers a clear, justified recommendation with a revisit trigger instead of an evasive 'it depends'"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Should our order service use event sourcing or a plain CRUD model, and is it time to split it out of the monolith into its own microservice?",
+      "expected_output": "Recognizes these as internal-structure architectural decisions about the team's own code — pattern choice and service boundaries — and refers to architecture-design for an ADR-driven trade-off analysis, without running a vendor/TCO evaluation",
+      "assertions": [
+        "Recognizes the request as internal architecture (pattern choice, service boundaries), not a build/buy/adopt sourcing decision",
+        "Refers to the architecture-design skill and its ADR workflow for the decision",
+        "Does not produce a vendor evaluation, TCO analysis, or lock-in assessment for this request",
+        "States or implies the boundary: build-vs-buy decides where a capability comes from; architecture-design decides how your own system is structured"
+      ]
+    }
+  ]
+}

package/skills/cicd-pipeline/SKILL.md

@@ -83,5 +83,6 @@ Quality gates prevent bad code from advancing:
 - `deployment-repo` — for multi-service systems, the deployment repo handles system-level CI (contract tests, E2E, promotion)
 - `gitops-delivery` — pull-based delivery as an alternative to CI-driven `kubectl apply` / `helm upgrade`
 - `deployment-checklist` — pre-deployment verification gates to incorporate into the pipeline
+- `release-management` — the release stage itself: version bumps, changelog, tagging, publish gates, registry publishing (the pipeline automates what that skill decides)
 - `security-audit` — security scanning stages and SAST/DAST integration
 - `verification-before-completion` — run the proving commands locally before relying on the pipeline to catch failures

package/skills/code-archaeology/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: code-archaeology
+description: "Understand unfamiliar or legacy code before changing it — map entry points, mine git history (blame, churn, log -S), trace data flow, recover the why behind odd code, pin current behavior with characterization tests, find seams for safe change. Triggers: understand this codebase, legacy code, inherited this project, what does this code do, why is it written this way, nobody knows how this works, onboard to this repo, is it safe to change this. Prioritizing debt → technical-debt-review; improving code you already understand → refactoring."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Code Archaeology
+
+Build a working model of code nobody fully understands — *before* changing it.
+The cardinal rule: **the code is the way it is for reasons; find them before
+overriding them.** Chesterton's fence applies — weird code is usually a bug fix
+whose bug report is lost, and "cleaning it up" reintroduces the bug. Boundary
+with siblings: `technical-debt-review` assesses and prioritizes what to fix;
+`refactoring` improves code you already understand; this skill produces the
+understanding both depend on.
+
+## Workflow
+
+### Step 1: Survey Before Digging
+
+Get the shape of the territory without reading line-by-line: entry points
+(main, routes, handlers, cron, consumers), the dependency skeleton (what are
+the load-bearing modules — imported by everything), build/run/test commands
+(does the test suite even pass? that's data), and the directory map with sizes.
+Resist starting at file one and reading forward — comprehension follows the
+call graph, not the alphabet.
+
+### Step 2: Mine the History — the Code's Memory
+
+Git knows what the docs forgot. The high-yield digs:
+
+- `git log --follow -p -- <file>` — a file's life story; the commit that
+  introduced the odd code usually says why (and links a ticket).
+- `git log -S '<string>'` (pickaxe) — when a magic value or weird guard
+  appeared, and what else changed with it.
+- **Churn analysis** — files with the most commits are the active organs
+  (`git log --format= --name-only | sort | uniq -c | sort -rn | head`);
+  high-churn + large = where understanding pays most (same hotspot logic as
+  `technical-debt-review`).
+- `git blame -w -C` (ignore whitespace, follow copies) — who last touched this
+  line *and in what commit context*; blame the commit, then read its message
+  and siblings.
+- Merge/PR references in messages — the review thread often holds the design
+  discussion that never made it into the code.
+
+### Step 3: Trace, Don't Guess
+
+For the specific behavior you need to understand, follow the data: pick one
+concrete input (a request, an event, a row) and trace it end to end — through
+handlers, transformations, side effects, and persistence. Use the debugger or
+strategic log statements over static reading when the control flow is dynamic
+(dispatch tables, DI containers, metaprogramming). Write the trace down as you
+go; a data-flow narrative ("the order enters here, gets enriched here, forks
+here") is worth ten class diagrams.
+
+### Step 4: Interrogate the Oddities
+
+For each "why on earth" you hit, run the checklist before concluding it's
+senseless: What does history say (Step 2)? Does a test encode it as intended
+behavior? Do comments/tickets/ADRs reference it? Does production data depend on
+it (that dead-looking branch may handle the 2019 records)? Only after all four
+come up empty may you *suspect* it's vestigial — and even then you prove it
+(logging/telemetry on the branch) rather than assume it.
+
+### Step 5: Pin Behavior with Characterization Tests
+
+Before changing anything you don't fully understand, write tests that capture
+what the code **currently does** — not what it should do. Feed it
+representative inputs (including the weird ones from production), assert the
+observed outputs, and lock in today's behavior as the baseline. These tests
+are your tripwire: if a "safe cleanup" changes an output, you learn it in CI,
+not in production. Golden-master/snapshot testing works well when outputs are
+large or numerous. (For designing the suite around them long-term:
+`test-suite-design`.)
+
+### Step 6: Leave the Map Better Than You Found It
+
+Record what you learned where the next archaeologist will find it: a short
+architecture note or README-in-the-directory (the data-flow narrative from
+Step 3, the load-bearing oddities from Step 4 and *why they exist*), backfilled
+ADRs for the big recovered decisions (`architecture-design`), and comments only
+on the genuinely non-obvious constraints. Then, with understanding and
+characterization tests in place, changes proceed via `refactoring` (seams,
+safe transformations) or `dependency-impact-analysis` (blast radius) as normal.
+
+## Principles Applied
+
+- **Chesterton's fence**: understand why the fence is there before removing
+  it; lost context is not absent context.
+- **Evidence over inference**: history, traces, and tests beat reading-and-
+  guessing — the code's actual behavior outranks anyone's model of it.
+- **Capture as you go**: understanding that lives in one head (or one session)
+  is re-excavated at full cost next time.
+
+## Cross-Skill References
+
+- `technical-debt-review` — assess and prioritize what to fix once understood
+- `refactoring` — the safe-change patterns applied after comprehension
+- `test-suite-design` — growing characterization tests into a real suite
+- `dependency-impact-analysis` — blast radius before changing a shared piece
+- `architecture-documentation` — recording the recovered architecture (C4, flows)
+- `bug-investigating` — when the goal narrows to one specific misbehavior

package/skills/code-archaeology/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "code-archaeology",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just inherited a 8-year-old Django billing service. The original team is gone, there are no docs, and I need to change how proration is calculated. Help me understand it before I touch anything.",
+      "expected_output": "Surveys structure first (entry points, load-bearing modules, does the test suite pass), mines git history for the proration code specifically (log --follow, pickaxe for magic values, blame with commit context, churn hotspots), traces one concrete billing case end to end, interrogates oddities against history/tests/production data before judging them, writes characterization tests pinning current proration outputs before any change, and records the recovered understanding",
+      "assertions": [
+        "Surveys the codebase shape first (entry points, dependency skeleton, whether tests run) instead of reading files linearly",
+        "Uses git history as a primary source — git log --follow, pickaxe (log -S), or blame with commit context — to recover why the proration code is the way it is",
+        "Traces at least one concrete billing input end to end through the code rather than only reading statically",
+        "Writes characterization tests that pin the CURRENT proration behavior (including odd cases) before making any change",
+        "Treats odd code as potentially load-bearing (Chesterton's fence) — checks history, tests, and production data before deeming anything vestigial",
+        "Records the recovered understanding (data-flow narrative, architecture note, or backfilled ADR) for the next person"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "There's a bizarre guard clause in our payment processor: `if amount == 999999: amount = amount - 1`. No comment, no test, git blame just shows a 'fixes' commit from 2019 by someone who left. Everyone's afraid to delete it. Should I?",
+      "expected_output": "Does not say 'yes, delete it' outright: digs into the 2019 commit's full context (message, sibling changes, linked ticket, the PR discussion), searches for related production data or downstream systems that might depend on the cap, and if all sources come up empty, proposes proving it's dead (logging/telemetry on the branch for a period) plus a characterization test — removal only with evidence and a safety net, not on vibes",
+      "assertions": [
+        "Investigates the 2019 commit's full context (message, other files in the same commit, linked ticket/PR discussion) rather than accepting blame's surface result",
+        "Considers that production data or a downstream system may depend on the behavior before judging it vestigial",
+        "Proposes gathering runtime evidence (logging/telemetry on the branch) to prove the code path is dead rather than assuming it",
+        "Recommends a characterization test or equivalent safety net around the behavior before/when removing it",
+        "Does not recommend immediate deletion based on the code looking senseless"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our codebase is a mess of tech debt — give me a prioritized assessment of what we should fix first and a remediation roadmap for the quarter.",
+      "expected_output": "Recognizes this as a debt assessment/prioritization request — refers to technical-debt-review for the hotspot analysis and remediation roadmap, noting the boundary: code-archaeology builds understanding of unfamiliar code; technical-debt-review assesses health and prioritizes fixes",
+      "assertions": [
+        "Recognizes the request as debt assessment and prioritization, not comprehension of unfamiliar code",
+        "Refers to the technical-debt-review skill for the hotspot analysis and roadmap",
+        "Does not produce an archaeology workflow (history mining, characterization tests) as the primary answer",
+        "States or implies the boundary: code-archaeology produces understanding; technical-debt-review assesses and prioritizes what to fix"
+      ]
+    }
+  ]
+}

package/skills/code-reviewing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: code-reviewing
-description: "Structured code reviews enforcing DRY, KISS, YAGNI, SRP, best practices, and project conventions. Triggers: review this code, code review, check my code, what do you think of this implementation, review this PR, is this code good, feedback on my code, review staged changes before commit."
+description: "Structured code reviews enforcing DRY, KISS, YAGNI, SRP, best practices, and project conventions."
+when_to_use: "Triggers: review this code, code review, check my code, what do you think of this implementation, review this PR, is this code good, feedback on my code, review staged changes before commit."
 model: sonnet
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
@@ -13,10 +14,19 @@ Perform thorough, constructive code reviews that catch bugs, enforce principles,
 
 ### Step 1: Understand the Context
 
-Before reviewing line-by-line, understand the big picture:
+Working-tree changes right now (live at skill load; empty when the tree is clean,
+this isn't a git repo, or the review targets something else — e.g. pasted code or
+a PR):
+
+!`git diff --stat 2>/dev/null || true`
+
+If the summary above is empty or irrelevant to what you were asked to review,
+proceed with the code as provided. Before reviewing line-by-line, understand the
+big picture:
 
 - **What is this code supposed to do?** Read the PR description, linked issue, or ask the user.
-- **What changed?** If reviewing a diff, understand the scope of changes.
+- **What changed?** If reviewing a diff, understand the scope of changes — run the
+  full `git diff` (or `git diff --staged`) when the stat summary isn't enough.
 - **What's the surrounding code like?** Read adjacent files for conventions and patterns.
 
 ### Step 2: First Pass — Structural Review

package/skills/compliance-privacy/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: compliance-privacy
+description: "Engineer for regulatory and privacy obligations — GDPR/CCPA privacy-by-design, PII data mapping and minimization, retention and deletion (right to erasure), data subject requests, consent, SOC 2 controls (access, change management, audit logging). Triggers: GDPR, CCPA, SOC 2, HIPAA, compliance, privacy review, PII, personal data, data retention, right to be forgotten, DSR, audit requirements, are we compliant. Vulnerabilities in code → security-audit; attack analysis of a design → threat-modeling."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit, WebFetch, WebSearch
+---
+
+# Compliance & Privacy Engineering
+
+Turn regulatory obligations into engineering requirements — before an auditor,
+a regulator, or a deletion request does it for you. This skill covers the
+*engineering* of compliance (what to build and how); it is not legal advice, and
+material decisions (lawful basis, DPAs, breach notification) need counsel —
+flag them explicitly rather than silently deciding. Boundary with its siblings:
+`security-audit` finds technical vulnerabilities, `threat-modeling` analyzes
+attacker paths in a design; this skill handles what regulations *oblige* you to
+do with data regardless of attackers.
+
+## Workflow
+
+### Step 1: Map the Data — You Can't Comply with What You Can't Find
+
+Build the data inventory first; every obligation hangs off it:
+
+- **What personal data exists** — direct identifiers (name, email, phone),
+  indirect (IP, device IDs, location), sensitive categories (health, biometrics,
+  children's data — these carry stricter rules).
+- **Where it lives** — every store, including the ones people forget: logs,
+  analytics, backups, data warehouses, third-party processors, caches, error
+  trackers.
+- **Where it flows** — which services touch it, which vendors receive it
+  (each is a processor needing a DPA), and whether it crosses borders.
+
+Grep the codebase and schemas for it; the inventory that only reflects the
+architecture diagram misses the PII in logs and analytics events.
+
+### Step 2: Determine What Applies
+
+Which regimes govern you follows from the data and the users, not the company's
+location: EU/UK users → GDPR/UK-GDPR; California residents → CCPA/CPRA; health
+data in the US → HIPAA; card data → PCI-DSS; enterprise customers asking for
+audits → SOC 2. Verify specifics against current official sources — regulations
+and thresholds change; don't answer from memory. Then extract the engineering
+obligations (see [references/obligations-map.md](references/obligations-map.md)
+for the regulation → engineering-requirement mapping).
+
+### Step 3: Design for Minimization and Purpose
+
+The cheapest data to protect is data you don't have:
+
+- **Collect less**: challenge every field — what breaks if we don't collect it?
+- **Retain less**: every data class gets a retention period and an *automated*
+  deletion path; "keep forever by default" is a finding, not a policy.
+- **Expose less**: pseudonymize/tokenize where full identity isn't needed
+  (analytics, testing — see `test-data-strategy` for GDPR-safe test data);
+  scope access per purpose.
+- **Log less**: PII in logs inherits none of your database's controls and all
+  of its obligations — scrub at the logging layer, not in post-processing.
+
+### Step 4: Build the Rights Machinery
+
+Data-subject rights are engineering features with deadlines (typically ~30
+days), not support tickets to improvise:
+
+- **Access/export**: produce all of a person's data across every Step-1 store.
+- **Deletion**: erase or anonymize across primary stores, caches, search
+  indexes, analytics, and a documented stance on backups (usually: excluded
+  from immediate erasure, purged on backup expiry — state it in the policy).
+  Deletion that misses a store the inventory forgot is the classic failure.
+- **Consent**: record what was consented to, when, and which version; make
+  withdrawal as easy as granting; gate the relevant processing on it.
+
+Test the deletion path like a feature — run it against a seeded user and verify
+every store — because the first real request is a terrible time to discover it
+doesn't work.
+
+### Step 5: Implement the Control Layer (SOC 2 lens)
+
+The controls auditors verify are mostly good engineering hygiene made
+demonstrable: least-privilege access with a review cadence, change management
+(PRs + reviews + CI — which you likely have; the gap is usually *evidence*),
+append-only audit logging of sensitive-data access and admin actions
+(overlaps `threat-modeling`'s repudiation counters), encryption in transit and
+at rest, offboarding that provably revokes access, and vendor review for every
+processor in the Step-1 flow map. Wire evidence collection into the systems
+themselves — screenshots gathered the week before an audit don't scale.
+
+### Step 6: Make It Continuous
+
+Compliance decays with every feature that adds a data flow. Add a lightweight
+privacy check to the definition of done for features touching personal data
+(new data collected? new vendor? retention set? deletion path covers it?), keep
+the data inventory in version control next to the code, and re-run the Step-1
+mapping when architecture changes — same living-document discipline as a threat
+model.
+
+## Principles Applied
+
+- **Minimization is the master control**: every other obligation scales with
+  how much data you hold.
+- **Rights are features**: access, deletion, and consent need designs, tests,
+  and deadlines — not runbooks of manual SQL.
+- **Evidence or it didn't happen**: an undocumented control fails the audit
+  even when it works.
+
+## Cross-Skill References
+
+- `security-audit` — technical vulnerability review (confidentiality controls overlap)
+- `threat-modeling` — design-time attack analysis; shares the data-classification step
+- `data-modeling` — schema-level retention, soft-delete vs erasure, PII isolation
+- `test-data-strategy` — GDPR-safe test data, anonymization
+- `configuration-strategy` — secrets and access to production data
+- `observability-design` — keeping PII out of logs, traces, and metrics

package/skills/compliance-privacy/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "compliance-privacy",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We're a B2B SaaS with EU customers and we just got our first GDPR deletion request. We honestly don't know where all the user data lives. What do we need to build to handle this properly?",
+      "expected_output": "Starts with a data inventory across ALL stores (databases, logs, analytics, backups, third-party processors, caches), then designs deletion machinery: erasure/anonymization across every store, a documented stance on backups, the ~30-day deadline, and testing the deletion path against a seeded user; frames rights handling as an engineered feature and adds minimization/retention so the problem shrinks over time",
+      "assertions": [
+        "Begins with a data inventory/mapping across all stores — explicitly including the commonly-missed ones (logs, analytics, backups, third-party processors, caches)",
+        "Designs deletion as an engineered, testable feature spanning every store, not a manual SQL runbook against the primary database",
+        "Addresses backups explicitly with a documented stance (e.g. excluded from immediate erasure, purged on backup expiry)",
+        "Mentions the response deadline for data subject requests (about 30 days) and/or verifying the deletion path against a seeded test user before a real request",
+        "Recommends minimization and retention policies (automated deletion, collect less, PII out of logs) so future obligations shrink",
+        "Flags that material legal decisions (lawful basis, DPAs, breach specifics) need counsel rather than deciding them itself"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "An enterprise prospect just sent us a security questionnaire asking if we're SOC 2 compliant. We're a 10-person startup with decent engineering hygiene (PRs, CI, SSO) but zero formal compliance work. What does getting there actually involve on the engineering side?",
+      "expected_output": "Explains SOC 2 as an audit of controls operating over time (Type I vs II), maps their existing hygiene (PR review, CI, SSO) onto trust-criteria controls and identifies the real gap as demonstrable evidence — access reviews, offboarding proof, audit logging, vendor review — recommending evidence automation over screenshot scrambles, scoping to the Security criterion first, and being realistic about timeline/audit-window",
+      "assertions": [
+        "Explains that SOC 2 audits controls operating over time (Type II observation window), not a one-time checklist",
+        "Maps existing engineering hygiene (PR reviews, CI, SSO) onto SOC 2 controls and identifies evidence/demonstrability as the actual gap",
+        "Covers the core control areas: logical access (least privilege, access reviews, offboarding), change management, audit logging, and vendor management",
+        "Recommends starting with the Security criterion and adding other trust criteria only when customers demand them",
+        "Recommends automating evidence collection rather than gathering screenshots before the audit"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Can you review our Express API code for injection vulnerabilities and check whether our JWT auth implementation is secure?",
+      "expected_output": "Recognizes this as a technical vulnerability review of existing code — refers to security-audit for the injection/auth analysis, stating the boundary: compliance-privacy handles regulatory and privacy obligations (GDPR/SOC 2, data rights, retention); security-audit finds technical vulnerabilities",
+      "assertions": [
+        "Recognizes the request as a technical security review of code, not a regulatory/privacy obligation question",
+        "Refers to the security-audit skill for the injection and auth review",
+        "Does not produce a compliance workflow (data mapping, DSR machinery, SOC 2 controls) as the answer",
+        "States the boundary: compliance-privacy covers regulatory/privacy obligations; security-audit covers technical vulnerabilities"
+      ]
+    }
+  ]
+}

package/skills/compliance-privacy/references/obligations-map.md

@@ -0,0 +1,69 @@
+# Regulation → Engineering Obligation Map
+
+What each regime actually demands from the engineering side. Verify thresholds
+and details against current official sources before relying on them — this map
+orients; it doesn't replace the regulation text or counsel.
+
+## GDPR / UK-GDPR (EU/UK personal data)
+
+| Obligation | Engineering requirement |
+|---|---|
+| Lawful basis per processing purpose (Art. 6) | Record which basis covers each data flow; consent flows need capture + withdrawal machinery |
+| Data minimization & purpose limitation (Art. 5) | Field-level justification; no reuse of data for new purposes without a new basis |
+| Right of access / portability (Art. 15, 20) | Export of all of a subject's data, machine-readable, across every store |
+| Right to erasure (Art. 17) | Deletion/anonymization across primary stores, caches, indexes, analytics; documented backup stance |
+| Privacy by design & default (Art. 25) | Privacy review in the feature workflow; most-protective defaults |
+| Records of processing (Art. 30) | The data inventory (SKILL.md Step 1), kept current |
+| Security of processing (Art. 32) | Encryption in transit/at rest, access control, pseudonymization where feasible |
+| Breach notification (Art. 33) | Detection + escalation path that can meet 72-hour notification — needs `observability-design`-grade alerting |
+| Processors & transfers (Art. 28, Ch. V) | DPA with every vendor receiving personal data; transfer mechanism (SCCs/adequacy) for cross-border flows |
+| DPIA for high-risk processing (Art. 35) | Formal assessment before launching high-risk features (large-scale profiling, sensitive categories) — pairs with `threat-modeling` |
+
+## CCPA / CPRA (California residents)
+
+Similar rights machinery to GDPR (know/access, delete, correct) plus two deltas
+worth engineering attention: **opt-out of sale/sharing** (honor Global Privacy
+Control signals; maintain a "Do Not Sell or Share" path) and **service-provider
+contracts** (the CCPA analog of DPAs). Thresholds determine applicability
+(revenue / volume of consumers' data / share of revenue from selling data) —
+check current numbers.
+
+## SOC 2 (Trust Services Criteria — what enterprise customers ask for)
+
+SOC 2 is an audit of *your controls operating over time* (Type II), not a
+checklist you pass once. The Security criterion (always in scope):
+
+| Control area | Typical evidence engineering owns |
+|---|---|
+| Logical access | SSO/MFA, least-privilege roles, quarterly access reviews, provably-executed offboarding |
+| Change management | PR review required on protected branches, CI gates, deploy audit trail |
+| System operations | Monitoring/alerting, incident-response process with records (`incident-response`, `observability-design`) |
+| Risk & vendor management | Vendor list with security review per processor; risk assessment cadence |
+| Data handling | Encryption at rest/in transit, backup + restore testing (`resilience-engineering`), retention/disposal execution |
+
+Availability, Confidentiality, Processing Integrity, and Privacy criteria are
+opt-in scope — add them when customers demand them, not preemptively.
+
+## HIPAA (US health data)
+
+Applies to covered entities and their **business associates** (a BAA makes you
+one). Engineering core: PHI inventory and isolation, access controls + audit
+logs on every PHI touch, encryption, minimum-necessary access, breach
+notification machinery. PHI in logs/analytics is the recurring violation.
+
+## PCI-DSS (card data)
+
+The dominant engineering decision is **scope reduction**: use a tokenizing
+payment processor (Stripe/Adyen-style) so raw PANs never transit your systems —
+this collapses most requirements to the lowest self-assessment tier. Storing
+raw card data puts your whole environment in scope; treat that as a
+`build-vs-buy` decision with a strong buy bias.
+
+## Choosing what to tackle first
+
+1. Data inventory (everything depends on it).
+2. Kill the involuntary violations: PII in logs, forever-retention, missing
+   deletion path.
+3. Rights machinery (access + deletion) — deadline-bound once requests arrive.
+4. Evidence automation for the controls you already operate.
+5. Formal frameworks (SOC 2 audit, DPIAs) when customers or scale demand.