swe-workflow-skills 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +144 -0
- package/VERSION +1 -0
- package/bin/cli.mjs +44 -0
- package/catalog.json +225 -0
- package/commands/role.md +34 -0
- package/hooks/session-start.mjs +118 -0
- package/install.mjs +318 -0
- package/package.json +47 -0
- package/roles.json +194 -0
- package/scripts/resolve.mjs +296 -0
- package/skills/accessibility-design/SKILL.md +128 -0
- package/skills/accessibility-design/evals/evals.json +51 -0
- package/skills/accessibility-design/references/accessibility-patterns.md +321 -0
- package/skills/api-design/SKILL.md +144 -0
- package/skills/api-design/evals/evals.json +48 -0
- package/skills/api-design/references/rest-conventions.md +147 -0
- package/skills/api-design/templates/api-spec.md +156 -0
- package/skills/architecture-design/SKILL.md +86 -0
- package/skills/architecture-design/evals/evals.json +44 -0
- package/skills/architecture-design/references/clean-architecture.md +147 -0
- package/skills/architecture-design/references/component-principles.md +129 -0
- package/skills/architecture-design/references/principles.md +81 -0
- package/skills/architecture-design/references/solid-principles.md +106 -0
- package/skills/architecture-design/templates/adr.md +63 -0
- package/skills/architecture-documentation/SKILL.md +126 -0
- package/skills/architecture-documentation/evals/evals.json +44 -0
- package/skills/architecture-documentation/references/abstraction-levels.md +91 -0
- package/skills/architecture-documentation/references/diagram-tooling.md +141 -0
- package/skills/architecture-documentation/templates/architecture-doc.md +171 -0
- package/skills/bug-investigating/SKILL.md +133 -0
- package/skills/bug-investigating/evals/evals.json +56 -0
- package/skills/bug-investigating/references/common-bugs.md +62 -0
- package/skills/bug-investigating/references/debugging-patterns.md +94 -0
- package/skills/cicd-pipeline/SKILL.md +87 -0
- package/skills/cicd-pipeline/evals/evals.json +34 -0
- package/skills/cicd-pipeline/references/pipeline-patterns.md +206 -0
- package/skills/cicd-pipeline/templates/github-actions.md +206 -0
- package/skills/code-reviewing/SKILL.md +92 -0
- package/skills/code-reviewing/evals/evals.json +62 -0
- package/skills/code-reviewing/references/error-handling.md +108 -0
- package/skills/code-reviewing/references/review-checklist.md +144 -0
- package/skills/configuration-strategy/SKILL.md +109 -0
- package/skills/configuration-strategy/evals/evals.json +41 -0
- package/skills/configuration-strategy/references/config-patterns.md +161 -0
- package/skills/containerization/SKILL.md +90 -0
- package/skills/containerization/evals/evals.json +36 -0
- package/skills/containerization/references/dockerfile-patterns.md +168 -0
- package/skills/containerization/templates/dockerfile.md +154 -0
- package/skills/data-modeling/SKILL.md +83 -0
- package/skills/data-modeling/evals/evals.json +43 -0
- package/skills/data-modeling/references/conventions.md +57 -0
- package/skills/data-modeling/templates/schema.md +120 -0
- package/skills/dependency-impact-analysis/SKILL.md +113 -0
- package/skills/dependency-impact-analysis/evals/evals.json +41 -0
- package/skills/dependency-impact-analysis/references/impact-patterns.md +150 -0
- package/skills/dependency-management/SKILL.md +161 -0
- package/skills/dependency-management/evals/evals.json +48 -0
- package/skills/dependency-management/references/evaluation-checklist.md +127 -0
- package/skills/deployment-checklist/SKILL.md +132 -0
- package/skills/deployment-checklist/evals/evals.json +58 -0
- package/skills/deployment-checklist/references/pre-deploy-gates.md +91 -0
- package/skills/deployment-repo/SKILL.md +190 -0
- package/skills/deployment-repo/evals/evals.json +44 -0
- package/skills/deployment-repo/references/deployment-repo-patterns.md +258 -0
- package/skills/deployment-repo/references/version-compatibility.md +227 -0
- package/skills/deployment-repo/templates/deployment-repo-structure.md +226 -0
- package/skills/effort-estimation/SKILL.md +95 -0
- package/skills/effort-estimation/evals/evals.json +32 -0
- package/skills/effort-estimation/references/estimation-methods.md +154 -0
- package/skills/feature-planning/SKILL.md +84 -0
- package/skills/feature-planning/evals/evals.json +44 -0
- package/skills/feature-planning/templates/plan.md +55 -0
- package/skills/feature-planning/templates/task.md +26 -0
- package/skills/frontend-architecture/SKILL.md +154 -0
- package/skills/frontend-architecture/evals/evals.json +34 -0
- package/skills/frontend-architecture/references/component-patterns.md +264 -0
- package/skills/frontend-architecture/templates/folder-structure.md +203 -0
- package/skills/git-workflow/SKILL.md +127 -0
- package/skills/git-workflow/evals/evals.json +44 -0
- package/skills/git-workflow/references/conventions.md +142 -0
- package/skills/git-workflow/templates/pull-request.md +57 -0
- package/skills/gitops-delivery/SKILL.md +319 -0
- package/skills/gitops-delivery/evals/evals.json +44 -0
- package/skills/gitops-delivery/references/gitops-patterns.md +478 -0
- package/skills/gitops-delivery/templates/gitops-config.md +196 -0
- package/skills/incident-response/SKILL.md +130 -0
- package/skills/incident-response/evals/evals.json +55 -0
- package/skills/incident-response/references/communication-templates.md +134 -0
- package/skills/incident-response/references/severity-levels.md +77 -0
- package/skills/incident-response/templates/incident-timeline.md +57 -0
- package/skills/infrastructure-as-code/SKILL.md +86 -0
- package/skills/infrastructure-as-code/evals/evals.json +33 -0
- package/skills/infrastructure-as-code/references/iac-patterns.md +179 -0
- package/skills/infrastructure-as-code/templates/terraform-module.md +158 -0
- package/skills/metrics-and-okrs/SKILL.md +113 -0
- package/skills/metrics-and-okrs/evals/evals.json +33 -0
- package/skills/metrics-and-okrs/references/metric-catalog.md +90 -0
- package/skills/metrics-and-okrs/templates/okr-document.md +61 -0
- package/skills/ml-experiment-tracking/SKILL.md +96 -0
- package/skills/ml-experiment-tracking/evals/evals.json +32 -0
- package/skills/ml-experiment-tracking/references/tracking-tools.md +127 -0
- package/skills/ml-model-deployment/SKILL.md +106 -0
- package/skills/ml-model-deployment/evals/evals.json +34 -0
- package/skills/ml-model-deployment/references/serving-patterns.md +162 -0
- package/skills/ml-pipeline-design/SKILL.md +162 -0
- package/skills/ml-pipeline-design/evals/evals.json +34 -0
- package/skills/ml-pipeline-design/references/pipeline-components.md +174 -0
- package/skills/observability-design/SKILL.md +162 -0
- package/skills/observability-design/evals/evals.json +52 -0
- package/skills/observability-design/references/logging-patterns.md +229 -0
- package/skills/observability-design/references/slo-framework.md +151 -0
- package/skills/observability-design/templates/slo-document.md +80 -0
- package/skills/performance-optimization/SKILL.md +83 -0
- package/skills/performance-optimization/evals/evals.json +47 -0
- package/skills/performance-optimization/references/bottleneck-patterns.md +256 -0
- package/skills/performance-optimization/references/concurrency.md +101 -0
- package/skills/prd-writing/SKILL.md +109 -0
- package/skills/prd-writing/evals/evals.json +33 -0
- package/skills/prd-writing/references/prd-examples.md +132 -0
- package/skills/prd-writing/templates/prd.md +71 -0
- package/skills/prd-writing/templates/rfc.md +79 -0
- package/skills/project-documentation/SKILL.md +104 -0
- package/skills/project-documentation/evals/evals.json +48 -0
- package/skills/project-documentation/references/contributing-guide.md +100 -0
- package/skills/project-documentation/templates/changelog.md +59 -0
- package/skills/project-documentation/templates/readme.md +121 -0
- package/skills/project-proposal/SKILL.md +90 -0
- package/skills/project-proposal/evals/evals.json +31 -0
- package/skills/project-proposal/references/proposal-examples.md +140 -0
- package/skills/project-proposal/templates/proposal.md +76 -0
- package/skills/project-review/SKILL.md +111 -0
- package/skills/project-review/evals/evals.json +42 -0
- package/skills/refactoring/SKILL.md +90 -0
- package/skills/refactoring/evals/evals.json +44 -0
- package/skills/refactoring/references/transformations.md +132 -0
- package/skills/retrospective/SKILL.md +157 -0
- package/skills/retrospective/evals/evals.json +34 -0
- package/skills/retrospective/references/facilitation-guide.md +130 -0
- package/skills/retrospective/templates/post-mortem.md +121 -0
- package/skills/rollback-strategy/SKILL.md +116 -0
- package/skills/rollback-strategy/evals/evals.json +55 -0
- package/skills/rollback-strategy/references/rollback-patterns.md +125 -0
- package/skills/rollback-strategy/templates/rollback-plan.md +69 -0
- package/skills/security-audit/SKILL.md +146 -0
- package/skills/security-audit/evals/evals.json +66 -0
- package/skills/security-audit/references/owasp-top-10.md +167 -0
- package/skills/security-audit/templates/security-report.md +79 -0
- package/skills/skill-router/SKILL.md +171 -0
- package/skills/skill-router/evals/evals.json +39 -0
- package/skills/strategic-review/SKILL.md +106 -0
- package/skills/strategic-review/evals/evals.json +42 -0
- package/skills/strategic-review/templates/full-review-prompt.md +84 -0
- package/skills/tdd-workflow/SKILL.md +147 -0
- package/skills/tdd-workflow/evals/evals.json +58 -0
- package/skills/tdd-workflow/references/test-quality.md +71 -0
- package/skills/technical-debt-review/SKILL.md +113 -0
- package/skills/technical-debt-review/evals/evals.json +41 -0
- package/skills/technical-debt-review/references/debt-taxonomy.md +124 -0
- package/skills/technical-debt-review/templates/debt-audit.md +85 -0
- package/skills/test-data-strategy/SKILL.md +129 -0
- package/skills/test-data-strategy/evals/evals.json +49 -0
- package/skills/test-data-strategy/references/data-generation-patterns.md +341 -0
- package/skills/test-suite-design/SKILL.md +137 -0
- package/skills/test-suite-design/evals/evals.json +69 -0
- package/skills/test-suite-design/references/test-infrastructure.md +175 -0
- package/skills/test-suite-design/references/testing-pyramid.md +140 -0
- package/skills/ui-ux-design/SKILL.md +117 -0
- package/skills/ui-ux-design/evals/evals.json +35 -0
- package/skills/ui-ux-design/references/interaction-patterns.md +145 -0
- package/skills/ui-ux-design/templates/screen-spec.md +97 -0
- package/skills/verification-before-completion/SKILL.md +85 -0
- package/skills/verification-before-completion/evals/evals.json +53 -0
- package/skills/writing-skills/SKILL.md +87 -0
- package/skills/writing-skills/evals/evals.json +41 -0
- package/skills/writing-skills/references/pressure-testing.md +69 -0
- package/uninstall.mjs +182 -0
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: rollback-strategy
|
|
3
|
+
description: "Design safe rollback plans before deploying — identify irreversible changes, classify rollback complexity, create tested undo procedures. Triggers: rollback plan, rollback strategy, how do I undo this, can we revert, what if the deploy fails, safe to deploy, feature flag rollout, blue-green, database migration rollback, irreversible change."
|
|
4
|
+
model: haiku
|
|
5
|
+
allowed-tools: Read, Grep, Glob, Write, Edit
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Rollback Strategy
|
|
9
|
+
|
|
10
|
+
Design the undo plan before deploying — not during a production incident. A deployment without a rollback plan is a bet that nothing will go wrong.
|
|
11
|
+
|
|
12
|
+
## ⛔ The Iron Law
|
|
13
|
+
|
|
14
|
+
**If you can't undo it, don't ship it yet.**
|
|
15
|
+
|
|
16
|
+
Every change is classified by rollback complexity before deploy, and every non-Simple change has a written rollback procedure that has been *tested* — not just imagined. Decide rollback before the incident, never during it: the minutes you'd spend designing an undo mid-incident are the minutes users are down.
|
|
17
|
+
|
|
18
|
+
## Step 1: Analyze the Deployment
|
|
19
|
+
|
|
20
|
+
List every change being deployed:
|
|
21
|
+
|
|
22
|
+
- **Code changes**: Which services, which endpoints, what behavior changes?
|
|
23
|
+
- **Schema changes**: New tables, columns, indexes, constraints, dropped columns?
|
|
24
|
+
- **Data migrations**: Backfills, transformations, deletes?
|
|
25
|
+
- **Configuration changes**: New env vars, feature flag states, infrastructure config?
|
|
26
|
+
- **Dependency updates**: Library upgrades, external service version changes?
|
|
27
|
+
|
|
28
|
+
For each change, ask: **If this change caused a production incident 30 minutes after deploy, what would rollback look like?**
|
|
29
|
+
|
|
30
|
+
## Step 2: Classify by Rollback Complexity
|
|
31
|
+
|
|
32
|
+
Assign each change a rollback complexity:
|
|
33
|
+
|
|
34
|
+
| Complexity | Definition | Examples |
|
|
35
|
+
|-----------|-----------|---------|
|
|
36
|
+
| **Simple** | Revert the code deploy, no other steps | Logic change, UI change, new feature behind a flag |
|
|
37
|
+
| **Coordinated** | Code revert + one other step | New env var (remove it), new index (drop it), additive column (leave it, no harm) |
|
|
38
|
+
| **Complex** | Requires data migration reversal or multi-step coordination | Column rename (requires data migration), data backfill (must un-backfill) |
|
|
39
|
+
| **Irreversible** | Cannot be fully undone | Destructive data operations, sent emails/notifications, external API calls with side effects |
|
|
40
|
+
|
|
41
|
+
**If any change is Irreversible**: explicitly document what partial rollback looks like and get sign-off before deploying.
|
|
42
|
+
|
|
43
|
+
See [references/rollback-patterns.md](references/rollback-patterns.md) for detailed patterns per component type.
|
|
44
|
+
|
|
45
|
+
## Step 3: Design the Rollback Procedure
|
|
46
|
+
|
|
47
|
+
For each non-Simple change, write the explicit rollback steps:
|
|
48
|
+
|
|
49
|
+
**Database schema rollback:**
|
|
50
|
+
- Additive columns (new nullable column): safe to leave after rollback — old code ignores them
|
|
51
|
+
- Non-additive changes (rename, type change, NOT NULL constraint): require a reverse migration
|
|
52
|
+
- Dropped columns: need to be re-added and re-populated (use `git bisect` to find the data state)
|
|
53
|
+
|
|
54
|
+
**Feature flag rollback:**
|
|
55
|
+
- Define the "off" state before deploying
|
|
56
|
+
- Test the "off" state in staging before deploying to production
|
|
57
|
+
- Know which percentage to roll back to if doing a canary rollout
|
|
58
|
+
|
|
59
|
+
**Data migration rollback:**
|
|
60
|
+
- Write the reverse migration before deploying the forward migration
|
|
61
|
+
- Test both on a copy of production data
|
|
62
|
+
- If the migration is too large to reverse quickly, plan for an emergency read-only mode instead
|
|
63
|
+
|
|
64
|
+
**Configuration rollback:**
|
|
65
|
+
- Document the previous value of every env var being changed
|
|
66
|
+
- For secrets rotation: keep the old secret valid for 24 hours after switching
|
|
67
|
+
|
|
68
|
+
## Step 4: Document and Test the Plan
|
|
69
|
+
|
|
70
|
+
Write the rollback plan in the deployment PR or deployment runbook:
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
Rollback Plan:
|
|
74
|
+
1. [Step]: [Command or action]
|
|
75
|
+
2. [Step]: [Command or action]
|
|
76
|
+
3. Verify: [How to confirm rollback succeeded]
|
|
77
|
+
Estimated rollback time: [X minutes]
|
|
78
|
+
Rollback owner: [Who executes this during an incident]
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**Test it before you need it:**
|
|
82
|
+
- Run the rollback steps in staging before production deploy
|
|
83
|
+
- Confirm the rollback takes the expected time (important during incidents)
|
|
84
|
+
- Verify application health after rollback completes
|
|
85
|
+
|
|
86
|
+
Use [templates/rollback-plan.md](templates/rollback-plan.md) for the full plan format.
|
|
87
|
+
|
|
88
|
+
## Principles Applied
|
|
89
|
+
|
|
90
|
+
- **KISS**: Prefer feature flags over complex rollback procedures. The simplest rollback is turning a flag off.
|
|
91
|
+
- **YAGNI**: Don't deploy a change you can't roll back without a documented, tested plan. If you can't undo it, don't ship it yet.
|
|
92
|
+
- **Defense in depth**: Multiple rollback options (flag → revert → data migration reversal) provide fallbacks when the first option isn't enough.
|
|
93
|
+
- **Fail fast**: Define rollback triggers before deploying (see `deployment-checklist`). Waiting until an incident to decide when to rollback wastes critical time.
|
|
94
|
+
|
|
95
|
+
## Rationalizations to reject
|
|
96
|
+
|
|
97
|
+
| Excuse | Reality |
|
|
98
|
+
|--------|---------|
|
|
99
|
+
| "We'll figure out rollback if it breaks" | Designing rollback mid-incident wastes the minutes that matter most. |
|
|
100
|
+
| "The migration is reversible, trust me" | Reversible in theory ≠ tested. Run the reverse on production-sized data first. |
|
|
101
|
+
| "It's behind a flag, that's enough" | Only if the off-state was defined and tested before deploy. |
|
|
102
|
+
| "Rollback is unlikely, skip the plan" | A rollback plan is insurance — you write it before you need it, not after. |
|
|
103
|
+
| "Additive column, no rollback needed" | Confirm old code ignores it and document the no-op explicitly. |
|
|
104
|
+
|
|
105
|
+
## Red flags — stop and correct course
|
|
106
|
+
|
|
107
|
+
- An Irreversible change with no documented partial-rollback and no sign-off.
|
|
108
|
+
- A reverse migration that has never actually been executed.
|
|
109
|
+
- A feature flag whose off-state was never tested in staging.
|
|
110
|
+
- The estimated rollback time is unknown.
|
|
111
|
+
|
|
112
|
+
## Cross-Skill References
|
|
113
|
+
|
|
114
|
+
- `deployment-checklist` — run before every deploy; rollback plan is a required gate
|
|
115
|
+
- `incident-response` — execute the rollback plan when an incident occurs
|
|
116
|
+
- `configuration-strategy` — design feature flags as part of config strategy (reduces rollback complexity)
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
{
|
|
2
|
+
"skill_name": "rollback-strategy",
|
|
3
|
+
"evals": [
|
|
4
|
+
{
|
|
5
|
+
"id": 1,
|
|
6
|
+
"prompt": "I'm about to deploy a feature that adds a new 'subscription_tier' column to the users table and backfills it based on existing billing data. How do I make sure I can roll back safely?",
|
|
7
|
+
"expected_output": "Structured rollback analysis covering the schema change (additive column = simple) and the backfill (data migration = complex), with a phased deploy recommendation and explicit reverse migration guidance",
|
|
8
|
+
"assertions": [
|
|
9
|
+
"Identifies the additive column as safe/simple for rollback",
|
|
10
|
+
"Identifies the backfill as the complex part requiring a reverse transformation",
|
|
11
|
+
"Recommends writing and testing the reverse backfill before deploying",
|
|
12
|
+
"Suggests testing migration timing on production-sized data",
|
|
13
|
+
"Recommends making a database backup before the backfill runs",
|
|
14
|
+
"Produces or outlines a written rollback plan"
|
|
15
|
+
]
|
|
16
|
+
},
|
|
17
|
+
{
|
|
18
|
+
"id": 2,
|
|
19
|
+
"prompt": "We need to rename the 'email' column to 'email_address' in our users table. What's the safest way to do this and be able to roll back?",
|
|
20
|
+
"expected_output": "Recommends the expand-contract pattern (4-step phased approach) rather than a single rename, explaining why a direct rename is a breaking change that cannot be safely rolled back",
|
|
21
|
+
"assertions": [
|
|
22
|
+
"Warns that a direct column rename is a breaking change for any running application code",
|
|
23
|
+
"Recommends the expand-contract pattern: add new column → backfill → migrate reads/writes → drop old column",
|
|
24
|
+
"Explains that each step is independently rollback-safe",
|
|
25
|
+
"Notes that the old column should not be dropped until all references to it are confirmed removed"
|
|
26
|
+
]
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"id": 3,
|
|
30
|
+
"prompt": "Help me roll back the deploy I just did — users are getting 500 errors.",
|
|
31
|
+
"expected_output": "Recognizes this is an active incident execution context, not a planning context — redirects to incident-response skill for immediate action while potentially providing the rollback steps if a rollback plan exists",
|
|
32
|
+
"assertions": [
|
|
33
|
+
"Recognizes this is an active incident, not a pre-deploy planning session",
|
|
34
|
+
"Prioritizes speed and clear action over comprehensive planning",
|
|
35
|
+
"Mentions incident-response skill for the overall incident workflow",
|
|
36
|
+
"Asks for or uses the rollback plan if one was previously created",
|
|
37
|
+
"Does not spend time on rollback planning when immediate action is needed"
|
|
38
|
+
]
|
|
39
|
+
}
|
|
40
|
+
],
|
|
41
|
+
"pressure_tests": [
|
|
42
|
+
{
|
|
43
|
+
"id": 1,
|
|
44
|
+
"prompt": "We're behind schedule. The migration renames a column but it's probably reversible. Skip the rollback plan — we'll deal with it if it breaks.",
|
|
45
|
+
"pressure": ["time"],
|
|
46
|
+
"expected_behavior": "Holds the Iron Law: if you can't undo it, don't ship it yet. Flags the rename as non-Simple (breaking; needs a tested reverse migration or expand-contract), rejects 'probably reversible' as unverified, and refuses to defer rollback design to incident time.",
|
|
47
|
+
"assertions": [
|
|
48
|
+
"Flags the column rename as non-Simple / breaking",
|
|
49
|
+
"Rejects 'probably reversible' as unverified",
|
|
50
|
+
"Refuses to skip the rollback plan despite the schedule pressure",
|
|
51
|
+
"Explains that designing rollback mid-incident wastes the critical minutes"
|
|
52
|
+
]
|
|
53
|
+
}
|
|
54
|
+
]
|
|
55
|
+
}
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# Rollback Patterns by Component
|
|
2
|
+
|
|
3
|
+
## Database Schema Changes
|
|
4
|
+
|
|
5
|
+
### Safe to deploy without a rollback plan
|
|
6
|
+
- **New nullable column**: Old code ignores it. If you roll back the code, the column sits unused — no harm.
|
|
7
|
+
- **New table**: Old code doesn't know about it. Drop it if truly unnecessary after rollback.
|
|
8
|
+
- **New index**: Can be dropped. Concurrent index creation avoids locking.
|
|
9
|
+
|
|
10
|
+
### Requires a rollback migration
|
|
11
|
+
- **NOT NULL constraint added to existing column**: Old code may insert nulls; rollback requires removing the constraint.
|
|
12
|
+
- **Column type change**: Data may be lost in conversion. Write a reverse migration and test it.
|
|
13
|
+
- **Column rename**: Requires the reverse rename. The safest approach: add new column → backfill → switch reads/writes → remove old column (4 deploys, fully reversible at each step).
|
|
14
|
+
|
|
15
|
+
### Requires careful coordination or is irreversible
|
|
16
|
+
- **Column dropped**: Must add back and re-populate from backups or recalculate. Avoid dropping columns in the same deploy as removing references to them — deploy the code change first, verify the column is unused, then drop in a separate deploy.
|
|
17
|
+
- **Data deleted**: If rows are deleted, rollback means restoring from backup. Always make a point-in-time backup before destructive migrations.
|
|
18
|
+
- **Data backfilled or transformed**: Write the reverse transformation before deploying. Test on a copy of production data.
|
|
19
|
+
|
|
20
|
+
### Schema migration rollback pattern
|
|
21
|
+
```sql
|
|
22
|
+
-- Forward migration: add_status_to_orders
|
|
23
|
+
ALTER TABLE orders ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT 'pending';
|
|
24
|
+
|
|
25
|
+
-- Reverse migration (write before deploying forward):
|
|
26
|
+
ALTER TABLE orders DROP COLUMN status;
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
For long-running migrations on large tables, test timing on production data size before deploying.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Feature Flags
|
|
34
|
+
|
|
35
|
+
Feature flags are the simplest rollback mechanism. They decouple deployment from release.
|
|
36
|
+
|
|
37
|
+
### Rollback with feature flags
|
|
38
|
+
1. Disable the flag (turn off the feature)
|
|
39
|
+
2. Verify the application is in the expected "off" state
|
|
40
|
+
3. No code revert needed — old behavior is restored immediately
|
|
41
|
+
|
|
42
|
+
### Canary rollout and rollback
|
|
43
|
+
```
|
|
44
|
+
0% → 5% → 25% → 100%
|
|
45
|
+
↑
|
|
46
|
+
Monitor here: error rate, latency, conversion metrics
|
|
47
|
+
If metrics degrade: roll back to 0% before proceeding
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### What to test before deploying a flagged feature
|
|
51
|
+
- The "flag off" state works correctly (not just "flag on")
|
|
52
|
+
- Flag state changes propagate in under 1 minute
|
|
53
|
+
- The feature works correctly when the flag is enabled mid-session for a user
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## API Changes
|
|
58
|
+
|
|
59
|
+
### Backwards-compatible (rollback-safe)
|
|
60
|
+
- Adding new optional fields to response
|
|
61
|
+
- Adding new endpoints
|
|
62
|
+
- Adding new optional request parameters with documented defaults
|
|
63
|
+
- Deprecating fields (keep returning them, add deprecation notice)
|
|
64
|
+
|
|
65
|
+
### Breaking changes (require versioning or coordination)
|
|
66
|
+
- Removing fields from response
|
|
67
|
+
- Changing field types or semantics
|
|
68
|
+
- Removing endpoints
|
|
69
|
+
- Making optional fields required
|
|
70
|
+
|
|
71
|
+
### Breaking change rollback strategy: API versioning
|
|
72
|
+
Deploy v2 alongside v1. Route clients to v2 incrementally. If v2 has issues, route back to v1. Remove v1 once v2 is stable and all clients have migrated.
|
|
73
|
+
|
|
74
|
+
### Breaking change rollback strategy: Expand-contract
|
|
75
|
+
1. **Expand**: Add new behavior alongside old (both old and new work)
|
|
76
|
+
2. **Migrate**: Move clients to new behavior
|
|
77
|
+
3. **Contract**: Remove old behavior once all clients have migrated
|
|
78
|
+
|
|
79
|
+
Rollback is possible at every step of expand-contract. Skip to step 3 without step 2 and rollback becomes risky.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Cache Invalidation
|
|
84
|
+
|
|
85
|
+
If a rollback changes what valid cached data looks like:
|
|
86
|
+
|
|
87
|
+
- **Application-level cache**: Clear the cache as part of rollback
|
|
88
|
+
- **CDN cache**: Purge or set a short TTL before deploying so stale content expires quickly
|
|
89
|
+
- **Client-side cache**: Use cache-busting keys (content hash in asset filenames) so old clients don't cache new assets across deploys
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Event-Driven / Message Queue Changes
|
|
94
|
+
|
|
95
|
+
### Message schema changes
|
|
96
|
+
- **Additive fields**: Consumers ignore unknown fields in most message formats (protobuf, JSON with lenient parsers)
|
|
97
|
+
- **Removing fields**: Deploy consumers that handle missing fields before deploying producers that omit them
|
|
98
|
+
- **Consumer-first pattern**: For breaking changes, always deploy the consumer change first, then the producer change
|
|
99
|
+
|
|
100
|
+
### Message replay
|
|
101
|
+
If a bad deploy produced bad messages in a queue, rollback may require:
|
|
102
|
+
- Stopping consumers
|
|
103
|
+
- Dead-lettering or discarding the bad messages
|
|
104
|
+
- Rolling back code
|
|
105
|
+
- Replaying from a known-good point in the event log
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Infrastructure Changes
|
|
110
|
+
|
|
111
|
+
### Rollback for infrastructure-as-code
|
|
112
|
+
Always use version control for IaC. Rollback = apply the previous version of the Terraform/CloudFormation/Pulumi code.
|
|
113
|
+
|
|
114
|
+
**Before destructive infrastructure changes:**
|
|
115
|
+
- `terraform plan` and review what will be destroyed
|
|
116
|
+
- For stateful resources (databases, queues), add lifecycle rules: `prevent_destroy = true`
|
|
117
|
+
- Take a snapshot of stateful resources before making changes
|
|
118
|
+
|
|
119
|
+
### Blue-green deployment rollback
|
|
120
|
+
Maintain the previous environment ("blue") until the new environment ("green") is verified stable. Rollback = switch traffic back to blue.
|
|
121
|
+
|
|
122
|
+
**Prerequisites:**
|
|
123
|
+
- Load balancer or DNS supports instant traffic switching
|
|
124
|
+
- "Blue" environment remains live and healthy during deployment (don't recycle it immediately)
|
|
125
|
+
- Both environments can connect to the same database (or database is compatible with both)
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Rollback Plan
|
|
2
|
+
|
|
3
|
+
**Deployment**: [PR/ticket/description]
|
|
4
|
+
**Date**: [DATE]
|
|
5
|
+
**Author**: [Name]
|
|
6
|
+
**Rollback owner**: [Who executes this if needed]
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Changes Being Deployed
|
|
11
|
+
|
|
12
|
+
| Component | Change | Rollback complexity |
|
|
13
|
+
|-----------|--------|---------------------|
|
|
14
|
+
| [Service/component] | [Description] | Simple / Coordinated / Complex / Irreversible |
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Rollback Triggers
|
|
19
|
+
|
|
20
|
+
Roll back immediately if any of the following occur within [30/60] minutes of deployment:
|
|
21
|
+
|
|
22
|
+
- Error rate exceeds [X%]
|
|
23
|
+
- [Specific metric] drops below [threshold]
|
|
24
|
+
- [Specific alert fires]
|
|
25
|
+
- [Other trigger]
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Rollback Procedure
|
|
30
|
+
|
|
31
|
+
**Estimated rollback time**: [X minutes]
|
|
32
|
+
|
|
33
|
+
### Step 1: [First action]
|
|
34
|
+
```
|
|
35
|
+
[Command or instructions]
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Step 2: [Second action]
|
|
39
|
+
```
|
|
40
|
+
[Command or instructions]
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Step 3: Verify rollback succeeded
|
|
44
|
+
- [ ] [Check 1]: [How to verify]
|
|
45
|
+
- [ ] [Check 2]: [How to verify]
|
|
46
|
+
- [ ] Error rate returned to baseline
|
|
47
|
+
- [ ] Application health checks passing
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Irreversible Changes
|
|
52
|
+
|
|
53
|
+
*If any changes above are marked Irreversible, document them here and what partial rollback looks like:*
|
|
54
|
+
|
|
55
|
+
[Description of what cannot be undone and how to mitigate]
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Rollback Test Results
|
|
60
|
+
|
|
61
|
+
- [ ] Rollback procedure tested in staging on [DATE]
|
|
62
|
+
- [ ] Rollback completed in [X minutes] during test
|
|
63
|
+
- [ ] Application was healthy after test rollback
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Notes
|
|
68
|
+
|
|
69
|
+
[Any additional context, warnings, or dependencies for the rollback executor]
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: security-audit
|
|
3
|
+
description: "Comprehensive security analysis — OWASP Top 10, auth/authz flows, injection vulnerabilities, data exposure, secrets detection, dependency CVEs, hardening recommendations. Triggers: security audit, vulnerability, is this secure, security review, pentest prep, OWASP, harden this, check for vulnerabilities, injection, XSS, CSRF, auth security."
|
|
4
|
+
model: opus
|
|
5
|
+
allowed-tools: Read, Grep, Glob, Write, Edit, WebFetch, WebSearch
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Security Audit
|
|
9
|
+
|
|
10
|
+
Perform a structured security assessment of an application. This skill goes far deeper than the security checklist in code-reviewing — it's a dedicated, systematic analysis covering the OWASP Top 10 and beyond.
|
|
11
|
+
|
|
12
|
+
## Scope Boundary
|
|
13
|
+
|
|
14
|
+
This skill analyzes code, configuration, and architecture for security vulnerabilities through static analysis and design review. It does not replace penetration testing, but it prepares code for one by catching the issues a pentester would find.
|
|
15
|
+
|
|
16
|
+
## ⛔ The Iron Law
|
|
17
|
+
|
|
18
|
+
**"No obvious problems" is not a pass.**
|
|
19
|
+
|
|
20
|
+
Absence of evidence is not evidence of security. Every clearance is backed by evidence — the specific control you read and where it's enforced — and every finding cites the exact code path plus a concrete exploit scenario. If you can't write the exploit, you haven't assessed the risk; if you can, it isn't theoretical.
|
|
21
|
+
|
|
22
|
+
## Workflow
|
|
23
|
+
|
|
24
|
+
### Step 1: Define the Attack Surface
|
|
25
|
+
|
|
26
|
+
Before reviewing code line by line, map what's exposed:
|
|
27
|
+
|
|
28
|
+
- **Entry points**: HTTP endpoints, WebSocket connections, GraphQL resolvers, CLI inputs, file uploads, webhooks, cron jobs
|
|
29
|
+
- **Authentication boundaries**: What's public vs authenticated vs admin-only?
|
|
30
|
+
- **Data flows**: Where does sensitive data enter, travel, and get stored?
|
|
31
|
+
- **External integrations**: Third-party APIs, OAuth providers, payment processors
|
|
32
|
+
- **Infrastructure**: Cloud services, databases, caches, queues
|
|
33
|
+
|
|
34
|
+
Present the attack surface map to the user. Gaps in understanding here mean gaps in the audit.
|
|
35
|
+
|
|
36
|
+
### Step 2: Assess by OWASP Top 10
|
|
37
|
+
|
|
38
|
+
Walk through each category systematically. See [references/owasp-top-10.md](references/owasp-top-10.md) for the detailed checklist.
|
|
39
|
+
|
|
40
|
+
For each finding:
|
|
41
|
+
|
|
42
|
+
- **Severity**: Critical / High / Medium / Low
|
|
43
|
+
- **Location**: File, line, endpoint
|
|
44
|
+
- **Vulnerability**: What the issue is
|
|
45
|
+
- **Exploit scenario**: How an attacker would use this (concrete, not theoretical)
|
|
46
|
+
- **Remediation**: Specific code change or configuration fix
|
|
47
|
+
|
|
48
|
+
### Step 3: Authentication & Authorization Deep Dive
|
|
49
|
+
|
|
50
|
+
Auth is where the highest-impact vulnerabilities live. Review:
|
|
51
|
+
|
|
52
|
+
**Authentication:**
|
|
53
|
+
- How are credentials stored? (bcrypt/argon2 with sufficient rounds, never MD5/SHA)
|
|
54
|
+
- Session management: secure flags, httpOnly, sameSite, expiration
|
|
55
|
+
- Token handling: JWT validation (algorithm, expiry, issuer), refresh token rotation
|
|
56
|
+
- Password policy: minimum complexity, breached password checking
|
|
57
|
+
- MFA implementation (if present): bypass resistance, recovery flow security
|
|
58
|
+
- Rate limiting on login: brute force protection
|
|
59
|
+
|
|
60
|
+
**Authorization:**
|
|
61
|
+
- Is authorization checked on every protected endpoint (not just the UI)?
|
|
62
|
+
- Are there IDOR vulnerabilities? (Can user A access user B's resources by changing an ID?)
|
|
63
|
+
- Is the authorization model consistent? (role-based, attribute-based, or ad-hoc?)
|
|
64
|
+
- Are there privilege escalation paths? (Can a regular user reach admin functionality?)
|
|
65
|
+
- Are API endpoints and UI permissions in sync?
|
|
66
|
+
|
|
67
|
+
### Step 4: Data Security Review
|
|
68
|
+
|
|
69
|
+
- **At rest**: Is sensitive data encrypted in the database? (PII, payment data, health data)
|
|
70
|
+
- **In transit**: Is TLS enforced everywhere? Any HTTP-only endpoints?
|
|
71
|
+
- **In logs**: Are passwords, tokens, SSNs, or credit card numbers logged?
|
|
72
|
+
- **In errors**: Do error messages leak internal details (stack traces, SQL queries, file paths)?
|
|
73
|
+
- **In responses**: Do API responses include fields the client shouldn't see?
|
|
74
|
+
- **Retention**: Is data deleted when it should be? GDPR/CCPA compliance?
|
|
75
|
+
|
|
76
|
+
### Step 5: Dependency Audit
|
|
77
|
+
|
|
78
|
+
Run dependency vulnerability scanners and review results:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
# JavaScript/TypeScript
|
|
82
|
+
npm audit
|
|
83
|
+
npx better-npm-audit audit
|
|
84
|
+
|
|
85
|
+
# Python
|
|
86
|
+
pip audit
|
|
87
|
+
safety check
|
|
88
|
+
|
|
89
|
+
# Go
|
|
90
|
+
govulncheck ./...
|
|
91
|
+
|
|
92
|
+
# Ruby
|
|
93
|
+
bundle audit check --update
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
For each vulnerability found:
|
|
97
|
+
- What is the CVE and its severity?
|
|
98
|
+
- Is the vulnerable code path actually used in this project?
|
|
99
|
+
- Is there a patched version available?
|
|
100
|
+
- If no patch exists, what's the mitigation?
|
|
101
|
+
|
|
102
|
+
Suggest using the `dependency-management` skill for remediation planning.
|
|
103
|
+
|
|
104
|
+
### Step 6: Secrets and Configuration
|
|
105
|
+
|
|
106
|
+
- Scan for hardcoded secrets: API keys, passwords, tokens, private keys
|
|
107
|
+
- Check `.gitignore` covers sensitive files (`.env`, key files, certificates)
|
|
108
|
+
- Review git history for accidentally committed secrets: `git log --all -p | grep -i "password\|secret\|api_key\|token"`
|
|
109
|
+
- Verify environment variable usage for all secrets
|
|
110
|
+
- Check that different environments use different credentials
|
|
111
|
+
|
|
112
|
+
### Step 7: Produce the Report
|
|
113
|
+
|
|
114
|
+
Output the audit report using the template at [templates/security-report.md](templates/security-report.md). Organize findings by severity, with Critical and High items first.
|
|
115
|
+
|
|
116
|
+
## What This Skill Does NOT Cover
|
|
117
|
+
|
|
118
|
+
- Runtime penetration testing (requires running the application)
|
|
119
|
+
- Network-level security (firewall rules, VPN configuration)
|
|
120
|
+
- Physical security or social engineering
|
|
121
|
+
- Compliance certification (SOC 2, HIPAA, PCI DSS — though findings may relate)
|
|
122
|
+
|
|
123
|
+
## Principles Applied
|
|
124
|
+
|
|
125
|
+
- **Defense in depth**: Don't rely on a single security control. Layer protections.
|
|
126
|
+
- **Least privilege**: Every component should have the minimum permissions it needs.
|
|
127
|
+
- **Fail secure**: When something goes wrong, it should deny access, not grant it.
|
|
128
|
+
- **KISS**: Simpler security is more auditable security. Complex auth flows breed bugs.
|
|
129
|
+
|
|
130
|
+
## Rationalizations to reject
|
|
131
|
+
|
|
132
|
+
| Excuse | Reality |
|
|
133
|
+
|--------|---------|
|
|
134
|
+
| "I didn't see anything obviously wrong" | You audited the absence of obvious bugs, not the presence of security. Trace each control. |
|
|
135
|
+
| "The framework handles that" | Verify the control is actually enabled and configured correctly — don't assume. |
|
|
136
|
+
| "Auth is checked in the UI" | UI checks are not authorization. Confirm server-side enforcement on every protected endpoint. |
|
|
137
|
+
| "This input is internal/trusted" | Trust boundaries shift. Validate anyway — defense in depth. |
|
|
138
|
+
| "That CVE doesn't apply to us" | Confirm the vulnerable code path is unused before dismissing it. |
|
|
139
|
+
| "It's only a theoretical risk" | If you can't write the exploit scenario, you haven't assessed it. |
|
|
140
|
+
|
|
141
|
+
## Red flags — stop and correct course
|
|
142
|
+
|
|
143
|
+
- Signing off a category without naming the file/endpoint you verified.
|
|
144
|
+
- A finding with no concrete exploit path.
|
|
145
|
+
- Concluding "secure" because nothing jumped out.
|
|
146
|
+
- Trusting that a control exists without reading where it's enforced.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
{
|
|
2
|
+
"skill_name": "security-audit",
|
|
3
|
+
"evals": [
|
|
4
|
+
{
|
|
5
|
+
"id": 1,
|
|
6
|
+
"prompt": "Run a security audit on my Express.js API. It handles user registration, login, payments via Stripe, and file uploads. We store user data in PostgreSQL and use JWT for authentication.",
|
|
7
|
+
"expected_output": "Should map the attack surface first (endpoints, auth boundaries, data flows), then systematically walk through OWASP categories with focus on auth, injection, and file upload. Should produce a severity-classified report.",
|
|
8
|
+
"assertions": [
|
|
9
|
+
"Maps the attack surface before diving into code",
|
|
10
|
+
"Reviews authentication implementation (JWT validation, password hashing)",
|
|
11
|
+
"Checks for IDOR vulnerabilities on user/payment endpoints",
|
|
12
|
+
"Reviews file upload for type/size/content validation",
|
|
13
|
+
"Checks Stripe webhook signature verification",
|
|
14
|
+
"Scans for SQL injection in database queries",
|
|
15
|
+
"Checks for hardcoded secrets",
|
|
16
|
+
"Runs or suggests npm audit for dependency vulnerabilities",
|
|
17
|
+
"Produces findings with severity, exploit scenario, and remediation",
|
|
18
|
+
"Goes deeper than code-reviewing's 8-item security checklist"
|
|
19
|
+
]
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
"id": 2,
|
|
23
|
+
"prompt": "Check if this login endpoint is secure:\n\napp.post('/login', async (req, res) => {\n const { email, password } = req.body;\n const user = await db.query(`SELECT * FROM users WHERE email = '${email}'`);\n if (!user) return res.status(401).json({ error: 'User not found' });\n if (user.password !== md5(password)) return res.status(401).json({ error: 'Wrong password' });\n const token = jwt.sign({ id: user.id, role: user.role }, 'my-secret-key');\n res.json({ token });\n});",
|
|
24
|
+
"expected_output": "Should identify ALL major issues: SQL injection, MD5 hashing, hardcoded JWT secret, information leakage in error messages, no rate limiting, no input validation, token never expires.",
|
|
25
|
+
"assertions": [
|
|
26
|
+
"Identifies SQL injection (string interpolation in query) as Critical",
|
|
27
|
+
"Identifies MD5 password hashing as Critical (must use bcrypt/argon2)",
|
|
28
|
+
"Identifies hardcoded JWT secret as High",
|
|
29
|
+
"Identifies JWT with no expiration as High",
|
|
30
|
+
"Identifies information leakage (different errors for user-not-found vs wrong-password)",
|
|
31
|
+
"Identifies no rate limiting as Medium",
|
|
32
|
+
"Identifies no input validation on email/password as Medium",
|
|
33
|
+
"Provides concrete exploit scenarios for at least the top 3",
|
|
34
|
+
"Provides remediated code for each finding"
|
|
35
|
+
]
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"id": 3,
|
|
39
|
+
"prompt": "We're about to launch our SaaS product and our CTO wants a security review before the launch. We don't know where to start. Can you help?",
|
|
40
|
+
"expected_output": "Should provide a structured approach: map attack surface, prioritize by risk, start with auth and data handling, then systematic OWASP walkthrough. Should not overwhelm with a 100-item checklist on first interaction.",
|
|
41
|
+
"assertions": [
|
|
42
|
+
"Asks about the tech stack and architecture before starting",
|
|
43
|
+
"Prioritizes the audit areas by risk (auth, payments, data handling first)",
|
|
44
|
+
"Explains the audit approach before diving in",
|
|
45
|
+
"Does not dump the entire OWASP checklist as step 1",
|
|
46
|
+
"Suggests dependency audit as a quick early win",
|
|
47
|
+
"Mentions that this doesn't replace penetration testing",
|
|
48
|
+
"Offers to produce a formal security report"
|
|
49
|
+
]
|
|
50
|
+
}
|
|
51
|
+
],
|
|
52
|
+
"pressure_tests": [
|
|
53
|
+
{
|
|
54
|
+
"id": 1,
|
|
55
|
+
"prompt": "We launch tomorrow. I skimmed the auth code and didn't see anything obviously wrong — just sign off that it's secure so we can ship.",
|
|
56
|
+
"pressure": ["time"],
|
|
57
|
+
"expected_behavior": "Holds the Iron Law: 'no obvious problems' is not a pass. Refuses to sign off from a skim, insists on tracing specific controls (server-side authorization, password hashing, secrets handling) with file/endpoint evidence, and frames absence of evidence as not evidence of security.",
|
|
58
|
+
"assertions": [
|
|
59
|
+
"Refuses to sign off based on 'nothing obviously wrong'",
|
|
60
|
+
"Insists on verifying specific controls with file/endpoint evidence",
|
|
61
|
+
"Will not declare secure without confirming server-side authorization is enforced",
|
|
62
|
+
"Frames absence of evidence as not evidence of security"
|
|
63
|
+
]
|
|
64
|
+
}
|
|
65
|
+
]
|
|
66
|
+
}
|