swe-workflow-skills 0.1.0

package/skills/architecture-documentation/templates/architecture-doc.md

@@ -0,0 +1,171 @@
+# Architecture Documentation — Repository Structure Template
+
+## Recommended Directory Layout
+
+```
+docs/
+  architecture/
+    README.md                              # Index: what's here, how to navigate, conventions used
+    glossary.md                            # Shared vocabulary — authoritative names for all systems
+
+    canonical/                             # Source-of-truth structural diagrams (C4 model)
+      system-context.{puml|dsl|mmd}        # Level 1: system + users + external dependencies
+      container-{system-name}.{ext}        # Level 2: services, data stores, message brokers
+      component-{service-name}.{ext}       # Level 3: internal structure (only if needed)
+
+    runtime/                               # Operational behavior diagrams
+      flows/                               # Data and request flows
+        {flow-name}.{d2|mmd|puml}          # e.g., checkout-flow.d2, rag-pipeline.d2
+      infra/                               # Deployment and infrastructure topology
+        {environment}-topology.{d2|mmd}    # e.g., production-topology.d2
+      sequences/                           # Sequence diagrams for key interactions
+        {interaction-name}.{ext}           # e.g., auth-handshake.puml
+
+    conceptual/                            # Communication and onboarding diagrams
+      overview-{audience}.md               # e.g., overview-new-hires.md (with Mermaid)
+      {topic}.md                           # e.g., data-flow-simplified.md
+
+  decisions/                               # ADRs (managed by architecture-design skill)
+    ADR-001-{title}.md
+    ADR-002-{title}.md
+```
+
+### Multi-Repo Variant
+
+For systems spanning multiple repositories, either:
+
+**A) Central docs repo** — One repo holds all architecture docs. Services reference it.
+```
+architecture-docs/           # Dedicated repo
+  canonical/                 # Cross-system C4 diagrams
+  runtime/                   # Cross-service flows
+  decisions/                 # Cross-cutting ADRs
+```
+
+**B) Co-located per service** — Each repo has its own `docs/architecture/` with service-scoped diagrams. A top-level repo or wiki holds the system context and cross-service views.
+
+Choose A when: a single team owns architecture docs, or the system context is the primary audience.
+Choose B when: teams own their services end-to-end and update docs alongside code.
+
+---
+
+## Glossary Template
+
+The glossary is the single source of truth for system element names. Every diagram must use these names exactly.
+
+```yaml
+# docs/architecture/glossary.md (or glossary.yaml)
+
+systems:
+  payments-platform:
+    description: Processes payments and manages billing
+    owner: team-payments
+    repo: github.com/org/payments
+
+services:
+  payments-api:
+    system: payments-platform
+    description: REST API for payment operations
+    tech: Node.js / Express
+
+  payment-worker:
+    system: payments-platform
+    description: Async payment processing
+    tech: Node.js
+
+data-stores:
+  payments-db:
+    system: payments-platform
+    description: Transaction and billing storage
+    tech: PostgreSQL
+
+  payment-queue:
+    system: payments-platform
+    description: Job queue for async payment processing
+    tech: Redis
+
+external-systems:
+  stripe:
+    description: Payment gateway provider
+    integration: REST API
+
+  bank-api:
+    description: Account verification service
+    integration: REST API
+```
+
+**Rules:**
+- Same names used in C4, runtime, and conceptual diagrams — no aliasing
+- New services must be added to the glossary before appearing in any diagram
+- The glossary is the authority — if a name isn't here, it shouldn't be in a diagram
+
+---
+
+## Architecture README Template
+
+```markdown
+# Architecture Documentation
+
+## How to Read These Docs
+
+This directory contains architecture documentation at three abstraction levels:
+
+- **`canonical/`** — Source of truth for system structure (C4 model). Start here.
+- **`runtime/`** — How the system behaves: data flows, deployment topology, key interactions.
+- **`conceptual/`** — Simplified overviews for onboarding and communication. Not authoritative.
+- **`../decisions/`** — Architecture Decision Records (ADRs) explaining why the architecture looks this way.
+
+## Conventions
+
+- **Naming**: All diagrams use names from `glossary.md`. No aliases or renames.
+- **Tools**: [List your chosen tools, e.g., "C4-PlantUML for canonical, D2 for runtime, Mermaid for conceptual"]
+- **Rendering**: [How to render diagrams, e.g., "Mermaid renders in GitHub. Run `make diagrams` for PlantUML/D2."]
+
+## Diagram Index
+
+| Diagram | Level | Description | Last Updated |
+|---------|-------|-------------|--------------|
+| [System Context](canonical/system-context.puml) | Canonical | Top-level system view | YYYY-MM-DD |
+| [Containers](canonical/container-payments.puml) | Canonical | Services and data stores | YYYY-MM-DD |
+| [Checkout Flow](runtime/flows/checkout-flow.d2) | Runtime | End-to-end checkout sequence | YYYY-MM-DD |
+| [Production Topology](runtime/infra/production-topology.d2) | Runtime | K8s cluster layout | YYYY-MM-DD |
+| [New Hire Overview](conceptual/overview-new-hires.md) | Conceptual | Simplified system map | YYYY-MM-DD |
+```
+
+---
+
+## Validation Checklist
+
+Use this checklist when reviewing architecture documentation for completeness:
+
+### Structure
+- [ ] `docs/architecture/` directory exists with canonical/, runtime/, and conceptual/ subdirectories (as needed)
+- [ ] `glossary.md` exists with all system element names
+- [ ] `README.md` exists with navigation guide and diagram index
+
+### Canonical Diagrams
+- [ ] System context diagram exists showing users and external dependencies
+- [ ] Container diagram exists for each system with multiple services
+- [ ] All services and data stores in the codebase appear in canonical diagrams
+- [ ] Each canonical diagram has a title and last-updated date
+
+### Runtime Diagrams (if applicable)
+- [ ] Runtime diagrams reference only elements from canonical diagrams (infrastructure-only components excepted)
+- [ ] Key data flows and interactions are documented
+- [ ] Deployment topology matches actual infrastructure
+
+### Naming Consistency
+- [ ] All element names match the glossary exactly
+- [ ] No diagram introduces new system names not in the glossary
+- [ ] File names follow the established convention
+
+### Traceability
+- [ ] ADRs that changed architecture reference affected diagrams
+- [ ] Canonical diagrams link to relevant ADRs in annotations or comments
+- [ ] Runtime diagrams are traceable to canonical elements
+
+### Maintenance
+- [ ] Diagrams are version-controlled as text files
+- [ ] Diagrams render correctly (manually verified or CI-checked)
+- [ ] Conceptual diagrams are labeled as non-canonical
+- [ ] Review cadence is documented (e.g., quarterly for canonical)

package/skills/bug-investigating/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: bug-investigating
+description: "Systematic debugging and root cause analysis using structured methodology — reproduce, isolate, hypothesize, verify. Triggers: this doesn't work, I'm getting an error, something is broken, bug, debug this, why is this happening, unexpected behavior, regression, root cause, stack trace, error message."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Bug Investigating
+
+Guide systematic debugging to find root causes, not just symptoms. Good debugging is methodical — form hypotheses, test them, narrow down, and verify the fix.
+
+## ⛔ The Iron Law
+
+**No fix without a confirmed root cause and a failing test that reproduces the bug.**
+
+A change that makes the symptom disappear without an explanation of *why* it worked is a guess, not a fix — and guesses regress. If you can't articulate the mechanism that produced the wrong behavior, you have not found the root cause yet.
+
+## Workflow
+
+### Step 1: Gather Evidence
+
+Before guessing at causes, collect information:
+
+- **What is the expected behavior?** What should happen?
+- **What is the actual behavior?** What happens instead?
+- **When did it start?** Did it work before? What changed?
+- **Is it reproducible?** Always, sometimes, only under certain conditions?
+- **Error messages and stack traces?** Read them carefully — they usually point to the right area.
+
+If the user provides a vague report ("it's broken"), ask these questions before investigating. A well-defined bug is half-solved.
+
+### Step 2: Reproduce the Bug
+
+Reproduction is the most important step. If you can't reproduce it, you can't verify the fix.
+
+1. Follow the user's steps to trigger the bug
+2. Identify the minimum reproduction case — strip away everything irrelevant
+3. Document the exact steps to reproduce
+
+If it's intermittent, look for:
+- Race conditions (timing-dependent)
+- State-dependent bugs (order of operations)
+- Environment-dependent bugs (config, versions, OS)
+
+### Step 3: Form Hypotheses
+
+Based on the evidence, list 2-5 likely causes, ordered by probability. For each hypothesis:
+
+- What would be true if this hypothesis is correct?
+- What quick test can confirm or eliminate it?
+
+Good hypotheses come from:
+- Reading the error message and stack trace carefully
+- Checking what changed recently (`git log`, `git diff`)
+- Examining the code path the failing scenario exercises
+- Looking at similar past bugs
+
+### Step 4: Binary Search for the Cause
+
+Narrow down systematically:
+
+**In code**: Add logging/breakpoints at the midpoint of the suspected code path. Is the state correct at that point? If yes, the bug is in the second half. If no, the first half.
+
+**In time**: If it worked before, use `git bisect` to find the commit that introduced the regression:
+```bash
+git bisect start
+git bisect bad          # current state is broken
+git bisect good <hash>  # this commit was working
+# Git checks out the midpoint — test and report good/bad
+```
+
+**In data**: If the bug depends on input, narrow down which input triggers it. Test boundary values, null/empty cases, and special characters.
+
+### Step 5: Verify the Root Cause
+
+Before fixing, confirm you've found the actual root cause, not a symptom:
+
+- Can you explain *why* this code produces the wrong behavior?
+- Does the explanation account for all observed symptoms?
+- If you remove/change the suspected cause, does the bug disappear?
+
+If you can't explain why, you haven't found the root cause yet.
+
+### Step 6: Fix and Verify
+
+1. **Write a failing test** that reproduces the bug (this is your regression test)
+2. **Apply the minimal fix** — change as little as possible
+3. **Run the test** — it should now pass
+4. **Run the full test suite** — the fix shouldn't break anything else
+5. **Document** what caused the bug and why the fix works
+
+See [references/common-bugs.md](references/common-bugs.md) for patterns of frequently encountered bugs by language/framework.
+
+## Principles Applied
+
+- **Methodical over intuition**: Resist the urge to guess and change things. Every action is a test of a hypothesis.
+- **Binary search mindset**: Always cut the problem space in half. Don't narrow from the edges — bisect from the middle.
+- **Root cause vs. symptom**: A null check that masks a null isn't a fix. Understand *why* the unexpected state exists.
+- **Reproducibility before fixes**: If you can't reproduce the bug reliably, you can't verify the fix. Spend time here first.
+- **Minimal fix**: Change the least amount of code that fixes the root cause. Broad changes introduce new bugs.
+
+## Anti-patterns in Debugging
+
+- **Shotgun debugging**: Changing random things and hoping. Always have a hypothesis.
+- **Blame debugging**: Assuming the bug is in someone else's code (library, framework, OS). Start with your code.
+- **Printf-only debugging**: Print statements are fine, but use a debugger for complex state issues.
+- **Fix the symptom**: Adding a null check instead of understanding why the value is null.
+- **Fixing without a test**: You'll be back here in a month.
+
+See [references/debugging-patterns.md](references/debugging-patterns.md) for hypothesis-driven debugging technique and language-specific tips.
+
+## Rationalizations to reject
+
+| Excuse | Reality |
+|--------|---------|
+| "This null check will probably fix it" | If you can't explain why the value is null, you're masking a symptom — it will resurface elsewhere. |
+| "It's probably flaky / the library's fault" | Start in your own code. Blame is not a diagnosis. |
+| "I can't reproduce it, but this should help" | Unreproduced means unverifiable — you won't know if the change actually worked. |
+| "Let me just try a few things" | Shotgun debugging. Every change must test a stated hypothesis. |
+| "The fix is obvious, no need for a test" | Without a regression test, the bug comes back and nobody notices. |
+
+## Red flags — stop and correct course
+
+- Changing code without a written hypothesis.
+- Proposing a fix before you've reproduced the bug.
+- The fix works but you can't explain the mechanism.
+- Adding defensive checks at the symptom instead of the source.
+
+## Cross-Skill References
+
+- `incident-response` — use instead when production is actively down and users are impacted (time-pressured response)
+- `tdd-workflow` — write the regression test (Step 6) using the TDD workflow
+- `verification-before-completion` — confirm the reproducing test passes before claiming the fix

package/skills/bug-investigating/evals/evals.json

@@ -0,0 +1,56 @@
+{
+  "skill_name": "bug-investigating",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "My API endpoint returns 200 but the data is wrong. The user's email shows as null even though it's in the database. Here's the endpoint:\n\napp.get('/users/:id', async (req, res) => {\n  const user = await db.users.findUnique({\n    where: { id: req.params.id },\n    select: { name: true, createdAt: true }\n  });\n  res.json(user);\n});",
+      "expected_output": "Should identify the root cause: the select clause explicitly omits email. Should not suggest database fixes or complex debugging when the code clearly shows the issue.",
+      "assertions": [
+        "Identifies the root cause: select clause doesn't include email",
+        "Does not suggest database investigation as first step",
+        "Explains why the bug manifests as null (field not selected)",
+        "Suggests adding email to the select clause or removing select to return all fields",
+        "Recommends writing a regression test"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "something broke in production, users are complaining about slow loading. it was fine yesterday. help!",
+      "expected_output": "Should systematically gather evidence before jumping to conclusions. Ask what changed, check recent deployments, look at metrics.",
+      "assertions": [
+        "Asks clarifying questions (what changed, recent deploys, error messages)",
+        "Suggests checking recent git commits/deploys",
+        "Recommends looking at metrics/monitoring before code",
+        "Does not immediately suggest code fixes without evidence",
+        "Suggests checking for N+1 queries or new external calls as common causes of sudden slowness"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I'm getting this error intermittently: 'SequelizeConnectionError: Connection pool exhausted'. It happens about 10 times a day, always during peak hours. Restarting the server fixes it temporarily.",
+      "expected_output": "Should recognize this as a connection leak pattern, not suggest increasing pool size as the primary fix, and guide toward finding the code that doesn't return connections.",
+      "assertions": [
+        "Identifies this as a connection leak (not just a pool size issue)",
+        "Does NOT primarily recommend just increasing pool size",
+        "Suggests searching for database calls that might not close connections (missing finally blocks, unhandled promise rejections)",
+        "Recommends checking for transactions that aren't committed/rolled back",
+        "Explains why restart temporarily fixes it (pool is recreated)",
+        "Suggests adding connection pool monitoring"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Production throws a NullPointerException sometimes. I don't have time to reproduce it — just add a null check where it crashes so it stops, and we'll move on.",
+      "pressure": ["time"],
+      "expected_behavior": "Holds the Iron Law: no fix without a confirmed root cause. Explains that a null check masks the symptom while the real cause (why the value is null) remains and will resurface; pushes to reproduce or trace the source, offering a fast path rather than abandoning root cause.",
+      "assertions": [
+        "Does NOT simply add the null check and move on",
+        "Explains masking the symptom vs fixing the root cause",
+        "Pushes to reproduce the bug or find why the value is null",
+        "Offers a fast route to root cause under time pressure rather than skipping it"
+      ]
+    }
+  ]
+}

package/skills/bug-investigating/references/common-bugs.md

@@ -0,0 +1,62 @@
+# Common Bug Patterns
+
+## Contents
+- Universal patterns
+- Async and concurrency bugs
+- Data and state bugs
+- Integration bugs
+- Environment bugs
+
+## Universal Patterns
+
+**Off-by-one errors**: Loops that iterate one too many or too few times. Check `<` vs `<=`, `0` vs `1` starting indexes, and fence-post problems.
+
+**Null/undefined reference**: Accessing a property of something that doesn't exist. Check: is the variable initialized? Could the query return no results? Is the API response missing a field?
+
+**Type coercion**: Implicit conversions producing unexpected results. JavaScript `"5" + 3 === "53"`, Python `"5" * 3 === "555"`. Use strict equality and explicit conversions.
+
+**Operator precedence**: `a || b && c` doesn't evaluate left-to-right in most languages. When in doubt, use parentheses.
+
+**Mutable default arguments**: In Python, `def fn(items=[])` shares the same list across all calls. Use `None` as default and create inside the function.
+
+## Async and Concurrency Bugs
+
+**Unhandled promise rejection**: An async function throws, but nothing catches it. In Node.js, this can crash the process. Always add `.catch()` or use try/catch with await.
+
+**Race condition**: Two operations depend on shared state, and the result varies based on timing. Signs: intermittent failures, works in debugger but fails at full speed. Fix: use locks, queues, or redesign to eliminate shared mutable state.
+
+**Deadlock**: Two processes each wait for a resource the other holds. Signs: system hangs, no errors, no progress. Fix: consistent lock ordering, timeouts.
+
+**Stale closure**: A callback captures a variable that changes before the callback runs. Common in loops with async operations. Fix: use block scoping (`let` in JS) or pass the value explicitly.
+
+**N+1 query**: A loop makes one database query per item instead of a batch query. Signs: slow page load that scales with data size. Fix: eager loading, batch queries.
+
+## Data and State Bugs
+
+**State mutation side effect**: A function modifies an object that the caller didn't expect to change. Signs: object has wrong values "mysteriously". Fix: clone inputs or use immutable data structures.
+
+**Timezone confusion**: Storing or comparing dates without consistent timezone handling. Signs: off-by-one-day errors, times shifted by a few hours. Fix: store everything in UTC, convert only for display.
+
+**Encoding issues**: Characters display as garbage or question marks. Signs: works with ASCII, breaks with accented or CJK characters. Fix: use UTF-8 everywhere, specify encoding explicitly.
+
+**Floating point precision**: `0.1 + 0.2 !== 0.3` in most languages. Fix: use integer arithmetic (cents instead of dollars), decimal libraries, or epsilon comparison.
+
+**Cache staleness**: Application shows outdated data because a cache wasn't invalidated. Signs: data updates "eventually" or "after restart". Fix: explicit cache invalidation on writes.
+
+## Integration Bugs
+
+**API contract mismatch**: The client sends/expects data in a different format than the server provides. Signs: null fields, 400 errors, missing data. Fix: check the actual request/response (not the docs — they may be wrong).
+
+**Connection pooling exhaustion**: Database connections aren't returned to the pool. Signs: app works fine, then suddenly can't connect to DB after running for a while. Fix: ensure connections are closed in finally blocks.
+
+**Retry without idempotency**: A failed request is retried, but the original request actually succeeded. Signs: duplicate records, double charges. Fix: use idempotency keys.
+
+**CORS**: Browser blocks a cross-origin request. Signs: works in Postman/curl, fails in browser. Fix: configure CORS headers on the server, not by disabling browser security.
+
+## Environment Bugs
+
+**Works on my machine**: Code behaves differently across environments. Common causes: different dependency versions, environment variable differences, OS-specific behavior (file paths, line endings).
+
+**Missing environment variable**: App crashes or behaves unexpectedly because a config value isn't set. Fix: fail fast at startup with clear error messages for required config.
+
+**Dependency version conflict**: Two packages require incompatible versions of a shared dependency. Signs: strange runtime errors that don't match the code. Fix: use lockfiles, check `node_modules` or `site-packages` for unexpected versions.

package/skills/bug-investigating/references/debugging-patterns.md

@@ -0,0 +1,94 @@
+# Debugging Patterns
+
+## Hypothesis-Driven Debugging
+
+The scientific method applied to bugs:
+
+1. **Observe**: Collect all available evidence (error messages, logs, stack traces, reproduction steps)
+2. **Hypothesize**: Form a falsifiable explanation — "I think X is happening because Y"
+3. **Predict**: "If my hypothesis is correct, then when I do Z, I should see W"
+4. **Test**: Run the experiment — add a log, check a value, change an input
+5. **Conclude**: If the prediction was wrong, update or discard the hypothesis
+
+Never skip step 3. A test without a prediction teaches you nothing useful — you don't know what result would confirm or deny the hypothesis.
+
+## Narrowing Techniques
+
+### Binary search in code
+Add an assertion or log at the midpoint of the suspected code path. If state is correct there, the bug is downstream. If wrong, upstream. Repeat until the exact line is isolated.
+
+### Git bisect (regression bugs)
+```bash
+git bisect start
+git bisect bad              # current commit is broken
+git bisect good <hash>      # this commit was known-good
+# git checks out midpoint — test it, then:
+git bisect good             # or: git bisect bad
+# Repeat until git identifies the culprit commit
+git bisect reset            # return to HEAD
+```
+
+### Input reduction (data-dependent bugs)
+Start with the full failing input. Remove half of it. Still fails? Remove another half. When it passes, the removed part was essential. Binary search until you have the minimum failing case.
+
+## Bug Categories and Where to Look
+
+### Off-by-one errors
+- Loop bounds: `< len` vs `<= len`, `0` vs `1` as starting index
+- String/array slicing: `[0:n]` vs `[0:n+1]`
+- Fence-post problems: n items need n-1 gaps, or n+1 fences
+- Symptom: Wrong count, missing last element, processing one extra item
+
+### Null / undefined reference
+- Cause: Assuming a value exists when it can be absent
+- Check: Where does this value come from? Can that source ever return null?
+- Fix: Validate at the boundary where data enters, not at every use site
+
+### Type coercion / comparison bugs
+- JavaScript `==` vs `===`, Python `is` vs `==`
+- Integer vs float comparison (`0.1 + 0.2 != 0.3`)
+- String-to-number coercion in dynamic languages
+
+### Race conditions
+- Symptom: Intermittent failure, passes when you add logging (logging adds timing)
+- Look for: Shared mutable state accessed from multiple threads/async contexts
+- Tools: Thread sanitizers, sleep injection to exaggerate timing windows
+
+### State mutation bugs
+- Symptom: Correct result first call, wrong result on second call
+- Look for: Global state, cached values that aren't invalidated, objects mutated in place
+
+### N+1 query bugs
+- Symptom: Slow with many records, fast with few
+- Look for: Database queries inside loops
+- Tool: Query logging (`EXPLAIN ANALYZE`, ORM query counting in tests)
+
+### Async / Promise bugs (JavaScript/TypeScript)
+- Unhandled promise rejection: Missing `await` or `.catch()`
+- Stale closure: `async` callback captures variable value at creation time, not call time
+- Fire-and-forget: `async` function called without `await`, caller proceeds before it completes
+
+## Language-Specific Tips
+
+### JavaScript / TypeScript
+- `console.dir(obj, {depth: null})` — print nested objects fully
+- `debugger` statement + Chrome DevTools or Node `--inspect`
+- `JSON.stringify(obj, null, 2)` for serializable objects
+- TypeScript: Read the type error message carefully — it tells you exactly what's wrong
+
+### Python
+- `import pdb; pdb.set_trace()` — interactive debugger
+- `breakpoint()` — Python 3.7+ shorthand
+- `print(repr(value))` — shows exact type and value, including whitespace
+- `traceback.print_exc()` — print exception from except block
+
+### Go
+- `fmt.Printf("%+v\n", struct)` — print struct with field names
+- `fmt.Printf("%T\n", value)` — print type
+- Delve debugger: `dlv debug ./cmd/myapp`
+- Race detector: `go test -race ./...`
+
+### SQL
+- `EXPLAIN ANALYZE <query>` — shows actual execution plan and row counts
+- Check for sequential scans on large tables (missing index)
+- Check for `N+1` by counting queries in test logs

package/skills/cicd-pipeline/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: cicd-pipeline
+description: "Design CI/CD pipelines for automated build, test, deploy — GitHub Actions, GitLab CI, quality gates. Triggers: CI/CD, pipeline, GitHub Actions, GitLab CI, workflow, automated deployment, build pipeline, continuous integration, continuous deployment, automate tests on PR, deploy automatically, quality gate."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# CI/CD Pipeline Design
+
+Design and write CI/CD pipelines that automate build, test, and deployment with appropriate quality gates. Good pipelines are fast, reliable, and catch problems before they reach production.
+
+## Workflow
+
+### Step 1: Understand the Requirements
+
+Before writing pipeline configuration, establish:
+
+- **Platform**: GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.
+- **Triggers**: On push, on PR, on tag, on schedule, manual?
+- **Stages needed**: Lint → Test → Build → Deploy? Security scan? Performance test?
+- **Environments**: Staging, production? Approval gates between them?
+- **Artifacts**: Docker images, npm packages, binaries? Where do they go?
+- **Secrets**: What credentials are needed and how are they managed?
+
+### Step 2: Design the Pipeline Stages
+
+Follow the "fail fast" principle — cheapest and fastest checks run first:
+
+```
+1. Lint & Format    (seconds)     → Catch style issues immediately
+2. Unit Tests       (seconds)     → Catch logic errors
+3. Build            (minutes)     → Confirm it compiles/bundles
+4. Integration Tests (minutes)    → Catch wiring issues
+5. Security Scan    (minutes)     → Catch vulnerabilities
+6. Deploy to Staging (minutes)    → Validate in real environment
+7. Deploy to Prod   (minutes)     → With approval gate
+```
+
+Parallelize independent stages. Lint, unit tests, and security scans can run simultaneously.
+
+**Multi-repo / deployment repo pattern:** If this service is part of a polyrepo with a deployment repo, the pipeline's deploy stages may update version pins in the deployment repo (via PR or `repository_dispatch`) rather than deploying directly to infrastructure. The deployment repo's own CI handles validation and promotion across environments. See `deployment-repo` for the orchestration pattern and `gitops-delivery` for automated cross-repo triggers.
+
+### Step 3: Write the Configuration
+
+Write the pipeline config for the target platform. Use [templates/github-actions.md](templates/github-actions.md) as a starting point for GitHub Actions PR validation and production deploy workflows, plus a GitLab CI equivalent.
+
+Key best practices:
+- **Cache dependencies** — Cache node_modules, pip packages, Go modules between runs
+- **Pin action/image versions** — Use SHA hashes or exact tags, not `@latest` or `@main`
+- **Minimize secrets scope** — Only expose secrets to the jobs that need them
+- **Use matrix builds** — Test across Node versions, OS variants, or Python versions when applicable
+- **Set timeouts** — Prevent stuck jobs from consuming runner minutes indefinitely
+- **Reusable workflows** — Extract common patterns into shared workflow files
+
+### Step 4: Add Quality Gates
+
+Quality gates prevent bad code from advancing:
+
+- **Required checks** — Tests and lint must pass before PR merge
+- **Coverage thresholds** — Fail if coverage drops below the floor
+- **Security scan** — Block deploys with critical vulnerabilities
+- **Approval gates** — Require manual approval for production deploys
+- **Smoke tests** — Automated health checks after deployment
+
+### Step 5: Validate
+
+- [ ] Pipeline triggers correctly on the intended events
+- [ ] Failing tests actually block the pipeline (not just warnings)
+- [ ] Secrets are not exposed in logs
+- [ ] Cache is working (second run is faster)
+- [ ] Deploy steps have appropriate environment protections
+- [ ] Rollback mechanism exists
+
+## Principles Applied
+
+- **KISS**: Start with a single-file pipeline. Split into reusable workflows only when duplication appears.
+- **DRY**: Extract repeated steps into composite actions or shared workflows.
+- **Fail fast**: Order stages by speed and likelihood of failure.
+- **YAGNI**: Don't add matrix builds across 5 Node versions if you only support one.
+
+## Cross-Skill References
+
+- `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
+- `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/cicd-pipeline/evals/evals.json

@@ -0,0 +1,34 @@
+{
+  "skill_name": "cicd-pipeline",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Set up a GitHub Actions CI/CD pipeline for our TypeScript Express API. We use PostgreSQL, run tests with Jest, build a Docker image, and deploy to AWS ECS. We want PR checks and auto-deploy to staging on merge to main, with manual approval for production.",
+      "expected_output": "Should produce a complete GitHub Actions workflow with lint, test (with Postgres service), build Docker image, deploy to staging, and gated production deploy.",
+      "assertions": [
+        "Lint and test run in parallel",
+        "PostgreSQL service container configured with health check",
+        "Dependencies are cached",
+        "Docker build uses multi-stage and caching",
+        "Staging deploys automatically on main push",
+        "Production deploy requires manual approval (environment protection)",
+        "Smoke test after each deployment",
+        "All jobs have timeouts",
+        "Action versions are pinned"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our CI pipeline takes 35 minutes. It runs lint, unit tests, integration tests, e2e tests, security scan, build, and deploy all sequentially. How can we speed it up?",
+      "expected_output": "Should identify parallelization opportunities, caching improvements, and suggest restructuring. Should not suggest skipping tests.",
+      "assertions": [
+        "Identifies that lint, unit tests, and security scan can run in parallel",
+        "Recommends dependency caching",
+        "Suggests splitting integration and e2e tests from unit tests",
+        "Does NOT suggest removing or skipping tests",
+        "Recommends concurrency control to cancel outdated runs",
+        "Provides a restructured pipeline diagram"
+      ]
+    }
+  ]
+}