@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-rollback/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: fluent-rollback
+description: Roll back workflow and module deployments in Fluent Commerce. Supports workflow version revert, module redeploy of prior versions, and settings restore from audit trail. Triggers on "rollback", "revert deployment", "undo deploy", "roll back workflow", "restore previous version".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <workflow|module|settings> <name> [--profile PROFILE] [--retailer RETAILER_REF] [--to-version VERSION] [--dry-run]
+---
+
+# Deployment Rollback
+
+Roll back workflow, module, or settings deployments to a prior known-good state. This skill complements the forward deployment chain (`/fluent-module-deploy`, `/fluent-workflow-deploy`) by providing a safe, audited path backward when deployments cause issues.
+
+## Ownership Boundary
+
+This skill owns: rollback planning, pre-rollback backup, rollback execution, post-rollback verification, and rollback report generation.
+
+Other skills own: forward deployments (`/fluent-module-deploy`, `/fluent-workflow-deploy`), session tracking (`/fluent-session-summary`), E2E verification (`/fluent-e2e-test`).
+
+## When to Use
+
+- A workflow deployment introduced a regression (orders stuck, events failing)
+- A module deployment broke existing functionality
+- Settings changes caused unexpected behavior (webhooks failing, wrong thresholds)
+- E2E tests fail post-deployment and the change must be undone
+- Rolling back to a known-good state while investigating root cause
+
+## Planning Gate
+
+**YES -- mandatory.** Rollback is a high-impact write operation. The rollback plan MUST be presented to the user and explicitly approved before any changes are made.
+
+### Approval Flow
+
+```
+1. Pre-flight assessment (read-only)
+2. Build rollback plan
+3. Present plan to user -> WAIT FOR APPROVAL
+4. User says "approved" / "go ahead" / "roll back"
+5. Execute rollback steps in order
+6. Verify each step
+7. Generate rollback report
+```
+
+**NEVER auto-execute a rollback without explicit user confirmation.**
+
+## Inputs
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `<type>` | Yes | -- | Artifact type: `workflow`, `module`, or `settings` |
+| `<name>` | Yes | -- | Artifact name (e.g., `ORDER::HD`, `fc-module-extensions`, `webhook.order.url`) |
+| `--profile` | No | Active CLI profile | Fluent CLI profile |
+| `--retailer` | No | Profile default | Target retailer ref |
+| `--to-version` | No | Previous version | Target rollback version |
+| `--dry-run` | No | `false` | Show rollback plan without executing |
+
+## Pre-flight Checks
+
+Before building the rollback plan:
+
+### Step 1: Identify What Was Deployed
+
+Check these locations for deployment evidence:
+
+1. **Pre-deploy report:** `accounts/<PROFILE>/reports/pre-deploy/` -- most recent check output
+2. **Build report:** `accounts/<PROFILE>/reports/build/` -- module version and artifacts
+3. **Session log:** Current session change tracking for `workflow.upload`, `module-deploy`, `setting.upsert`
+4. **Feature status:** `accounts/<PROFILE>/features/*/status.json` for IN_PROGRESS features
+
+If no deployment evidence found:
+```
+-> BLOCKED: No recent deployment evidence found.
+  Please specify what was deployed:
+  - Workflow name and retailer
+  - Module name and version
+  - Settings that were changed
+```
+
+### Step 2: Locate Previous Versions
+
+**Workflows:**
+- Local cache: `accounts/<PROFILE>/workflows/<RETAILER>/<NAME>.json` (if predates deployment)
+- Pre-deploy backup: `accounts/<PROFILE>/workflows/<RETAILER>/<NAME>.pre-deploy.json`
+- Git history: `git log --oneline -- <workflow-file>`
+
+**Modules:**
+- Local dist: `accounts/<PROFILE>/SOURCE/<repo>/dist/<module>.zip`
+- Git tags: `git tag --list 'v*'`
+- Previous commit: check out and rebuild if needed
+
+**Settings:**
+- Session audit trail: `accounts/<PROFILE>/sessions/*.json` -- search for setting.upsert with old values
+- Settings audit: `accounts/<PROFILE>/analysis/settings/` -- snapshots from /fluent-settings
+- Pre-deploy report: `accounts/<PROFILE>/reports/pre-deploy/` -- captures values before deploy
+
+### Step 3: Assess Irreversibility
+
+| Change Type | Reversible? | Notes |
+|-------------|-------------|-------|
+| Workflow version upload | YES | Re-upload previous content as new version |
+| Setting value change | YES | If previous value is known |
+| Module deployment | YES | If previous JAR/ZIP is available |
+| Entity state changes | **NO** | Orders moved to new statuses cannot be reverted |
+| Events sent | **NO** | Side effects already occurred |
+| Batch ingestion data | **NO** | Entities already created/updated |
+| GraphQL create mutations | **NO** | Entities already exist |
+| Webhook deliveries | **NO** | External systems already received payload |
+
+## Artifact Type: Workflow Rollback
+
+Fluent maintains workflow version history. Each upload creates a new version. Rollback re-uploads prior version content as a new version.
+
+### Source Resolution Order
+
+1. **Pre-deploy backup** -- `<NAME>.pre-deploy.json` (created by /fluent-workflow-deploy)
+2. **Local cache** -- `<NAME>.json` (if predates deployment)
+3. **Git history** -- prior commit version of the workflow file
+4. **Environment download** -- current live version (backup only, not rollback source)
+
+### Execution
+
+```
+1. Identify current workflow version (via GraphQL or workflow.transitions)
+2. Locate prior content (see Source Resolution)
+3. Backup CURRENT state: <NAME>.pre-rollback.json
+4. Upload prior content as new version: workflow.upload MCP tool
+5. Verify: download live version, confirm content matches target
+```
+
+User-action contract note:
+- `workflow.transitions` here is used for version/context verification only.
+- If rollback validation includes user-action visibility, enforce explicit `eventName` + documented `context`/`attributes` only, and compare `module` vs `module: "all"` before concluding misconfiguration.
+- Canonical references: `/fluent-workflow-builder` and `/fluent-transition-api`.
+
+## Artifact Type: Module Rollback
+
+Module rollback redeploys a prior module ZIP. Modules are replaced on install.
+
+### Source Resolution Order
+
+1. **Local dist** -- `SOURCE/<repo>/dist/<module>.zip` (prior build)
+2. **Git tag** -- check out prior tag, rebuild with /fluent-build
+3. **Artifact repository** -- fetch from Nexus/Artifactory if available
+
+### Execution
+
+```
+1. Identify current deployed rules (via plugin.list)
+2. Locate prior module ZIP (see Source Resolution)
+3. Log current rule versions for comparison
+4. Redeploy prior ZIP: fluent module deploy CLI
+5. Verify: plugin.list shows expected rule versions
+```
+
+## Artifact Type: Settings Rollback
+
+Settings have NO built-in version history in Fluent. Rollback depends on audit trail.
+
+### Source Resolution Order
+
+1. **Session audit trail** -- `sessions/*.json` with setting.upsert entries containing old values
+2. **Settings audit** -- `analysis/settings/` snapshots
+3. **Pre-deploy report** -- `reports/pre-deploy/` with captured current values
+
+### Execution
+
+```
+1. Search audit trail for prior value
+2. Show current vs proposed rollback value
+3. Restore via setting.upsert MCP tool
+4. Re-read setting to verify
+```
+
+If no prior value found:
+```
+-> BLOCKED: No prior value found for setting "webhook.order.url".
+  Settings have no built-in version history in Fluent.
+  Recovery: check session exports, analysis/settings/, or provide value manually.
+```
+
+## Dry Run (--dry-run)
+
+Show the rollback plan without executing:
+
+```
+=== Rollback Plan (DRY RUN) ===
+
+Type:      Workflow
+Artifact:  ORDER::HD
+Retailer:  HM_TEST
+Profile:   HMDEV
+
+Current:   v12 (deployed 2026-02-25 14:30)
+Target:    v11 content (from pre-deploy backup)
+Source:    accounts/HMDEV/workflows/HM_TEST/ORDER__HD.pre-deploy.json
+
+Changes that will be reverted:
+  + Ruleset "CancelOrderItems" (added in v12, will be REMOVED)
+  ~ Ruleset "ProcessOrder" trigger: BOOKED -> CREATED (will revert)
+  - Ruleset "LegacyRoute" (removed in v12, will be RESTORED)
+
+Risk: MEDIUM
+  - Removing "CancelOrderItems" may affect in-flight cancellation orders
+  - Restoring "LegacyRoute" may conflict with new routing logic
+
+Backup will be saved to:
+  accounts/HMDEV/workflows/HM_TEST/ORDER__HD.pre-rollback.json
+
+=== DRY RUN COMPLETE -- No changes made ===
+```
+
+## Irreversible Operations
+
+The skill refuses to attempt these and suggests alternatives:
+
+### Entity Mutations
+```
+-> BLOCKED: Entity mutations are irreversible.
+  Order HD-001 status changed CREATED -> COMPLETE cannot be reverted via API.
+  Alternatives:
+  1. Check /fluent-transition-api for available actions from current status
+  2. Send a compensating event if the workflow supports it (e.g., CANCEL)
+  3. Contact Fluent Support for database-level intervention
+```
+
+### Batch Ingestion
+```
+-> BLOCKED: Batch ingestion cannot be un-ingested.
+  1,500 inventory positions created by batch job "inv-load-2026-02-25".
+  Alternatives:
+  1. Create a compensating batch to zero-out quantities
+  2. Use entity.update to modify individual records
+  3. Contact Fluent Support for bulk data cleanup
+```
+
+### Events Sent
+```
+-> BLOCKED: Sent events cannot be unsent.
+  Event "OrderConfirmed" sent to 50 orders.
+  Alternatives:
+  1. Send compensating events if workflow supports reversal
+  2. Use /fluent-trace to identify affected entities
+  3. Process corrections through the normal workflow
+```
+
+## Rollback Plan Format
+
+Present to user before execution:
+
+```
+## Rollback Plan
+
+Profile: HMDEV | Retailer: HM_TEST
+Reason: Orders stuck in BOOKED status after workflow v12 deployment
+
+### Reversible Actions (will be executed)
+
+| # | Artifact | Current | Rollback To | Method |
+|---|----------|---------|-------------|--------|
+| 1 | Workflow ORDER__HD | v12 | v11 content | workflow.upload |
+| 2 | Setting webhook.order.url | new-url | old-url | setting.upsert |
+
+### Irreversible Changes (documented only)
+
+| # | Change | Impact | Mitigation |
+|---|--------|--------|------------|
+| 1 | 15 orders moved to BOOKED | Orders remain in BOOKED | Manual correction if needed |
+
+### Execution Order
+
+1. Settings (lowest risk, no dependencies)
+2. Workflows (stops new orders from using broken flow)
+3. Modules (restores previous rule behavior)
+
+Awaiting approval to proceed.
+```
+
+## Safety Guards
+
+1. **ALWAYS create a backup** before executing any rollback
+2. **ALWAYS show the rollback plan** and get explicit user approval
+3. **ALWAYS recommend --dry-run first** for production environments
+4. **NEVER attempt irreversible operations** (entity mutations, events, batch)
+5. **NEVER rollback without identifying prior state** -- refuse rather than guess
+6. **WARN if target version is >5 versions behind** -- large gaps are risky
+7. **WARN if target is production** -- require extra confirmation
+8. **LOG everything** to session tracking
+
+## Post-Rollback Actions
+
+1. **Generate rollback report** at `accounts/<PROFILE>/reports/rollback/<type>-<name>-<timestamp>.md`
+2. **Log to session tracking**
+3. **Recommend verification** -- /fluent-e2e-test to confirm rollback worked
+4. **Update feature status** if rollback invalidates VERIFIED:
+   - VERIFIED -> IN_PROGRESS (needs re-verification)
+   - Agent updates status.json: `"status": "IN_PROGRESS"`, `"updated": "<today>"`, `"next": "/fluent-e2e-test"`
+
+## Rollback Report
+
+```
+# Rollback Report
+
+| Field | Value |
+|-------|-------|
+| Type | Workflow |
+| Artifact | ORDER__HD |
+| Retailer | HM_TEST |
+| Executed | 2026-02-25T15:00:00Z |
+| From | v12 |
+| To | v11 (content) |
+| Reason | Regression -- orders stuck in BOOKED status |
+
+## Backup
+- Pre-rollback: accounts/HMDEV/workflows/HM_TEST/ORDER__HD.pre-rollback.json
+
+## Changes Reverted
+- Ruleset "CancelOrderItems" removed
+- Ruleset "ProcessOrder" trigger reverted
+
+## Verification
+- Status: PENDING -- run /fluent-e2e-test to verify
+```
+
+## Handoff Protocol
+
+### Emitted Signals
+- `-> READY: accounts/<PROFILE>/reports/rollback/<report>` -- Rollback complete
+- `-> BLOCKED: <reason>` -- Cannot rollback (irreversible, no prior version)
+- `-> NEXT: /fluent-e2e-test` -- Verify after rollback
+- `-> NEXT: /fluent-trace` -- Diagnose root cause
+
+### Consumed Signals
+- Reads deployment logs from `/fluent-session-summary`
+- Reads pre-deploy backups from `/fluent-workflow-deploy`
+- Reads build reports from `/fluent-build`
+
+## Error Reporting
+
+| Severity | Code | Scenario | Recovery |
+|----------|------|----------|----------|
+| CRITICAL | `ROLLBACK_FAILED` | Upload/deploy failed during rollback | Manual intervention; backup exists |
+| HIGH | `NO_PRIOR_VERSION` | No prior version found anywhere | Rebuild from git history |
+| HIGH | `IRREVERSIBLE` | Attempted rollback of entity/event/batch | Use alternatives in BLOCKED message |
+| MEDIUM | `PARTIAL_ROLLBACK` | Some artifacts succeeded, others failed | Complete manually |
+| MEDIUM | `LARGE_VERSION_GAP` | Target >5 versions behind | Confirm intent, consider incremental |
+| LOW | `AUDIT_MISSING` | No audit trail for settings | Settings rollback unavailable |
+
+## Session Tracking
+
+```
+SKILL: /fluent-rollback
+  args: <type> <name> --profile <PROFILE> --retailer <RETAILER> [--dry-run]
+  outcome: completed | failed | blocked | dry-run
+  artifact_type: workflow | module | settings
+  artifact_name: <name>
+  from_version: <current>
+  to_version: <target>
+  backup_path: <path>
+  report_path: <path>
+  feature_status_regressed: true | false
+```
+
+## Integration with Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `/fluent-module-deploy` | Forward deployment -- this skill reverses it |
+| `/fluent-workflow-deploy` | Forward deployment -- reads pre-deploy backups |
+| `/fluent-settings` | Settings changes -- restores prior values |
+| `/fluent-e2e-test` | Post-rollback verification |
+| `/fluent-trace` | Diagnose what went wrong |
+| `/fluent-feature-status` | Shows features affected by rollback |
+| `/fluent-session-summary` | Audit trail for deployment history |
+| `/fluent-pre-deploy-check` | Should have caught the issue -- review gates |
+| `/fluent-workflow-analyzer` | Validate restored workflow structure |
+
+## Tips
+
+- **Always run --dry-run first** -- see exactly what will change
+- **Workflow rollback is safest** -- Fluent maintains version history
+- **Module rollback requires a prior ZIP** -- keep your dist/ directory
+- **Settings rollback depends on audit trail** -- run /fluent-session-summary regularly
+- **Check /fluent-feature-status before rollback** -- understand affected features
+- **After rollback, run /fluent-e2e-test** -- verify the reverted state
+- **For production, double-confirm** -- the skill warns for good reason
+- **Rollback is not a fix** -- it buys time. Use /fluent-trace for root cause
+- **Partial rollbacks are possible** -- roll back workflow but keep module
+- **Document the reason** -- rollback report captures it for future reference