@fluentcommerce/ai-skills 0.1.0

package/content/dev/skills/fluent-session-summary/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: fluent-session-summary
+description: Track and summarize all code and Fluent environment changes made during a session. Maintains a running change log and produces a structured audit report (Text or JSON). Triggers on "session summary", "what did we change", "change summary", "show changes", "export audit".
+user-invocable: true
+allowed-tools: Bash, Read, Write
+argument-hint: [show|reset|export --json]
+---
+
+# Session Change Tracking
+
+Track ALL changes made during a session — both code modifications and Fluent Commerce environment mutations — and produce a structured audit summary on demand.
+
+## Behaviour
+
+This is a **cross-cutting concern**, not a phase-specific skill. It applies alongside every other skill.
+
+### What to Track
+
+**Fluent environment changes (live account):**
+- GraphQL mutations executed (entity type, ref/id, fields changed)
+- Workflows deployed or uploaded (name, version, retailer)
+- Settings created or updated (key, context, value summary)
+- Events sent via `event.send` (name, entity type, entity ref, sync/async, outcome)
+- Modules deployed via CLI (name, version, retailer)
+- Batch jobs created and sent (job name, entity type, record count, outcome)
+- Entities created or updated (locations, networks, catalogues, carriers, users, orders, fulfilments, inventory positions, products, virtual catalogues, etc.)
+
+**Code changes (local workspace):**
+- Files created, modified, or deleted (path + brief description)
+- Workflow JSON edits (ruleset added/removed, trigger changed, state added)
+- Rule classes scaffolded or modified
+- Git commits made (hash, message, repo)
+- Git pushes (repo, branch, remote)
+
+**Read-only operations are NOT tracked** — queries, downloads, analysis, introspection, event listing, and diagnostics are informational and do not change state.
+
+### When to Present
+
+- When the user asks: "what did we change?", "summary", "show changes", "wrap up", or invokes `/fluent-session-summary`
+- Proactively before ending a session that involved significant changes (3+ write operations)
+- After completing a multi-step task (e.g., build-deploy-test cycle)
+
+### Text Summary Format (Default)
+
+```markdown
+## Session Change Summary
+
+**Profile:** <PROFILE> | **Account:** <account> | **Retailer:** <RETAILER_REF> (ID <N>)
+**Duration:** <first change time> - <last change time>
+
+### Environment Changes
+| # | Action | Type | Ref / Key | Details |
+|---|--------|------|-----------|---------|
+| 1 | Created | Setting | WEBHOOK_ORDER_URL | context=RETAILER:5, value=https://... |
+| 2 | Created | Order | HD_TEST_20260222_1 | type=HD, status=CREATED |
+| 3 | Sent Event | CreateOrder | ORDER/HD_TEST_20260222_1 | async, SUCCESS |
+| 4 | Mutation | Order | HD_TEST_20260222_1 | status CREATED -> BOOKED |
+| 5 | Deployed | Workflow | ORDER::HD | v12 -> retailer HM_TEST |
+| 6 | Deployed | Module | hm-extensions | v1.2.3 -> retailer HM_TEST |
+| 7 | Batch | Product | job-12345 | 50 records, COMPLETE |
+
+### Code Changes
+| # | Action | Path | Details |
+|---|--------|------|---------|
+| 1 | Modified | workflows/ORDER__HD.json | Added ruleset HandleCancellation |
+| 2 | Created | src/.../CancelOrderRule.java | New rule class + test |
+| 3 | Modified | resources/module.json | Registered CancelOrderRule |
+| 4 | Committed | fluent-mcp-extn | abc1234 - feat: add cancel support |
+| 5 | Pushed | fluent-mcp-extn | main -> origin/main |
+
+### Totals
+| Category | Count |
+|----------|-------|
+| GraphQL mutations | N |
+| Events sent | N |
+| Settings changed | N |
+| Workflows deployed | N |
+| Modules deployed | N |
+| Batch jobs | N |
+| Files modified | N |
+| Git commits | N |
+
+### Irreversible Actions
+> List any destructive or hard-to-reverse changes here (entity deletions, workflow version overwrites, forced re-deploys). Flag prominently so the user is aware.
+```
+
+### JSON Export Format (`export --json`)
+
+> **For compliance-grade exports** with traceability matrices, rollback commands, and external system mapping, use `/fluent-session-audit-export`. This quick JSON export is a lightweight alternative for simple session records.
+
+When the user asks to "export audit" or runs with `export --json`, generate a JSON file (e.g., `session-audit-<TIMESTAMP>.json`) with this structure:
+
+<!-- Validate Mermaid blocks per /fluent-mermaid-validate rules -->
+```mermaid
+classDiagram
+    class SessionAudit {
+        String session_id
+        String timestamp
+        Target target
+        Changes changes
+        String summary
+    }
+    class Target {
+        String profile
+        String retailer
+        String account
+    }
+    class Changes {
+        CodeChange[] code
+        EnvChange[] environment
+    }
+    class CodeChange {
+        String timestamp
+        String action
+        String file
+        String description
+    }
+    class EnvChange {
+        String timestamp
+        String action
+        String type
+        String ref
+        String details
+        String outcome
+    }
+    
+    SessionAudit *-- Target
+    SessionAudit *-- Changes
+    Changes *-- CodeChange
+    Changes *-- EnvChange
+```
+
+```json
+{
+  "session_id": "UUID",
+  "timestamp": "ISO-8601",
+  "target": {
+    "profile": "PROFILE_NAME",
+    "retailer": "RETAILER_REF",
+    "account": "ACCOUNT_NAME"
+  },
+  "changes": {
+    "code": [
+      { "timestamp": "ISO", "action": "modified", "file": "path/to/file", "description": "Added ruleset" },
+      { "timestamp": "ISO", "action": "created", "file": "path/to/file", "description": "New rule class" }
+    ],
+    "environment": [
+      { "timestamp": "ISO", "action": "mutation", "type": "ORDER", "ref": "ORD-123", "details": "status -> BOOKED" },
+      { "timestamp": "ISO", "action": "event", "name": "ConfirmPick", "entity": "FULFILMENT", "ref": "FUL-123", "outcome": "SUCCESS" }
+    ]
+  },
+  "summary": "Brief text summary of the session goals and outcomes."
+}
+```
+
+### Tracking Protocol
+
+1. **As changes happen:** After each write operation (mutation, event send, deploy, file edit, commit), mentally append it to the running log. Do not wait until the end to reconstruct.
+2. **On `/fluent-session-summary show`:** Present the full text table.
+3. **On `/fluent-session-summary export --json`:** Write the JSON artifact to the workspace root.
+4. **On `/fluent-session-summary reset`:** Clear the running log (start fresh, e.g., when switching accounts mid-session).
+5. **Group by account/retailer** if the session spans multiple profiles or retailers.
+6. **Include outcome** where known (SUCCESS, FAILED, NO_MATCH) — especially for events.
+7. **For mutations**, note the key fields changed rather than full payloads.
+8. **For workflow deploys**, note the version number deployed.
+
+### Integration with Other Skills
+
+Every skill that performs write operations should contribute to this log:
+
+| Skill | Tracked actions |
+|-------|----------------|
+| `fluent-workflow-builder` | Workflow JSON edits (local file changes) |
+| `fluent-build` | Version bumps, module packaging |
+| `fluent-module-deploy` | Module installs to retailers |
+| `fluent-workflow-deploy` | Workflow uploads to retailers |
+| `fluent-settings` | Setting create/update mutations |
+| `fluent-retailer-config` | Entity creation (locations, networks, catalogues, etc.) |
+| `fluent-test-data` | Test entity creation |
+| `fluent-e2e-test` | Events sent, entities created during test |
+| `fluent-rule-scaffold` | New Java classes and module.json changes |
+| `fluent-job-batch` | Batch job creation, record sends |
+| `fluent-trace` | Events sent during diagnostic re-fires |
+| `fluent-custom-code` | Source code edits |
+| `fluent-module-scaffold` | Module skeleton creation |
+| `fluent-version-manage` | Version bumps, CHANGELOG updates, git tags |
+| `fluent-pre-deploy-check` | Pre-deploy gate results |
+| `fluent-session-audit-export` | Consumes same tracking data for compliance JSON |
+
+### Edge Cases
+
+- **Dry runs:** `event.send` with `dryRun: true` and `graphql.introspect` are NOT tracked (no state change).
+- **Failed writes:** Track with outcome=FAILED so the user knows what was attempted.
+- **Multi-retailer sessions:** Group changes under separate retailer headers.
+- **No changes made:** Report "No environment or code changes were made in this session."