@nurix/etna 0.1.2 → 0.2.0

package/data/harnesses/code/skills/introspect/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: introspect
+description: Pre-implementation impact analyzer. Reads a plan in docs/history/plans/ and checks every Proposed Change against docs/operations/guardrails.md to surface cascading risks before coding starts. Produces a severity-ranked violation report with suggested plan additions. Read-only. Triggers on "introspect", "check this plan", "impact analysis", "/introspect", "what could break", "guardrail check before I start".
+---
+
+# Introspect Skill
+
+Pre-implementation impact analysis. Reads a plan, intersects every proposed change with documented guardrails, and surfaces cascading risk _before_ implementation. The complement to `contract-monitor`, which scans the live codebase _after_ changes land.
+
+The skill is read-only. It does not edit the plan, modify code, or write to memory. Output is a report the user reviews and acts on.
+
+---
+
+## When to Use
+
+Trigger this skill when:
+
+- The user types `/introspect`, "introspect", "check this plan", "impact analysis", "what could break"
+- A plan exists in `docs/history/plans/` and the user is about to start implementation
+- A plan was recently revised and the user wants to re-check guardrail impact
+
+Do not run it when:
+
+- No `docs/operations/guardrails.md` exists — tell the user to create guardrails first via the documentation skill (`add guardrail`)
+- No plan exists — tell the user to write a plan first (documentation skill, `create plan`)
+- The user wants post-implementation auditing — that's the `contract-monitor` agent
+
+---
+
+## Inputs
+
+- **Plan path**: user-provided. If unspecified, use the most recent file in `docs/history/plans/` (sorted by filename date).
+- **Guardrails**: `docs/operations/guardrails.md` is mandatory. Stop if missing.
+- **Source files**: read on demand to verify intersections — never guess from plan text alone.
+
+---
+
+## Workflow
+
+### Phase 1: Load
+
+1. Resolve the plan path. If the user named a feature, glob `docs/history/plans/*{feature}*.md` and pick the newest.
+2. Read the plan in full.
+3. Confirm it has a `Status:` field. If `Complete` or `Abandoned`, ask the user whether they want to introspect a frozen plan anyway — it's usually a mistake.
+4. Read `docs/operations/guardrails.md`. Parse each guardrail section into: name, canonical source location, consumer paths, violation description.
+
+### Phase 2: Parse Proposed Changes
+
+The plan template's **Proposed Changes** subsections are load-bearing — introspect relies on their exact structure. Extract content from each:
+
+| Subsection | What introspect uses it for |
+|------------|------------------------------|
+| **New Files** | New paths to check against ownership and guardrail consumer paths |
+| **Modified Files** | Existing paths to check against guardrails referencing them |
+| **New Entities / State** | Entity strings, state slices, schema additions — checked against entity-type and schema-mismatch guardrails |
+| **API Changes** | New or modified routes, contracts, request/response shapes — checked against documented contracts |
+| **Cross-Module Contracts Affected** | The plan author's own admission of contracts touched — start here, then verify |
+
+If a subsection is missing or empty, note it in the report (the plan may be incomplete) but continue with what's there.
+
+### Phase 3: Analyze
+
+For each guardrail × proposed change pair, check intersection:
+
+1. **Path overlap** — does the change touch any file in the guardrail's consumer-paths set?
+2. **Pattern overlap** — does the change introduce code shapes the guardrail prohibits (raw string literal where a shared constant is required, new entity type not in the canonical array, persisted field without selector fallback)?
+3. **Contract overlap** — does the change modify the canonical source of a guardrail (the `ENTITY_TYPES` array, the shared constants file, the persistence schema)?
+
+Whenever an intersection is plausible from plan text, **read the actual source files** to verify. Never guess from plan text alone.
+
+Assign severity:
+
+- **Critical** — silent data loss, corrupted persistence, broken cross-entity references
+- **High** — stale state, broken lookups, schema selectors without fallbacks
+- **Medium** — potential mismatch, string-coupling that's likely to drift
+- **Low** — unlikely issue, code smell, easily caught in review
+
+### Phase 4: Report
+
+Produce a markdown report:
+
+```
+# Introspect — {plan filename}
+
+Plan: {path}
+Guardrails: {N} sections evaluated
+Intersections found: {N} ({critical}/{high}/{medium}/{low})
+
+## Violations
+
+| # | Guardrail | Risk | Severity | Plan step |
+|---|-----------|------|----------|-----------|
+
+## Suggested Plan Additions
+
+For each violation, a specific recommendation:
+
+- **Violation #1**: Add step X to Implementation Steps — {one-line action}
+- **Violation #2**: Add to Done Criteria — {one-line check}
+- **Violation #3**: Update Cross-Module Contracts Affected — {missing entry}
+
+## Missing Subsections
+
+{If any Proposed Changes subsection was empty or absent, list it here}
+
+## New Cross-Module Contracts Detected
+
+{If the plan introduces a contract not yet in guardrails.md, show a diff-style proposed addition. Ask the user to approve adding it via the documentation skill — never write directly.}
+```
+
+The severity-ranked table is the load-bearing output. Suggestions are advisory — the user decides which to fold back into the plan.
+
+### Phase 5: Hand Off
+
+After producing the report:
+
+- If the user accepts a suggested plan addition, they edit the plan themselves (or invoke the documentation skill to do it). Introspect never edits plans.
+- If new contracts are detected, suggest invoking the documentation skill with `add guardrail` to formalize them — do not append to `guardrails.md` from this skill.
+
+---
+
+## Rules
+
+- **Read-only**. Never edit the plan, source code, guardrails, or memory.
+- **Verify against source**. Never report a violation purely from plan text — read the files the plan claims it will touch.
+- **Plan structure is load-bearing**. If a plan was not written using the documentation skill's plan template, the Proposed Changes subsections may be missing. Note this clearly rather than fabricating intersections.
+- **A clean report is valid**. Plans with no intersections produce an empty violations table — say so, don't pad.
+- **Be specific**. Cite file paths, plan-step numbers, guardrail names, and the exact code shape that breaks the contract.
+- **Don't replicate contract-monitor**. Introspect checks intent (plan text). Contract-monitor checks reality (code). If the user wants to scan live code, route them to contract-monitor.
+
+---
+
+## Output Location
+
+The report is returned in the chat — not written to disk. The user reviews it and folds insights back into the plan manually (or via the documentation skill).

package/data/harnesses/code/skills/workflow-mapper/SKILL.md

@@ -0,0 +1,430 @@
+---
+name: workflow-mapper
+description: Discover and document all major workflows in a codebase by tracing call chains from user action to database/external system. Produces mermaid sequence diagrams and markdown documentation. Use when the user asks to map workflows, trace flows, document sequences, understand how features work end-to-end, or generate architecture diagrams. Triggers on "map workflows", "trace workflows", "workflow diagram", "sequence diagram", "how does X work end-to-end", "document flows", "codebase workflows", "how does this feature work", "trace the request flow", "show me the call chain", "what happens when a user does X", "end-to-end flow".
+---
+
+# Workflow Mapper Skill
+
+Identify and document every major workflow in a codebase by tracing execution paths from trigger to terminal effect. Output is a single markdown file with mermaid sequence diagrams.
+
+---
+
+## Decision Tree
+
+```
+User request
+    │
+    ├─ "Map all workflows" ────────────▶ Full Discovery (all phases)
+    │
+    ├─ "Map workflow for {feature}" ───▶ Targeted Discovery (skip Phase 1 broad scan)
+    │
+    ├─ "Update workflow map" ──────────▶ Incremental (diff against existing map)
+    │
+    └─ "How does X work end-to-end" ──▶ Single Workflow Trace (Phase 2-4 only)
+```
+
+---
+
+## Phase 1: Entry Point Discovery
+
+Find all places where a multi-step process begins. Use parallel sub-agents — one per technique.
+
+### Technique 1: Route Harvesting
+
+Scan all API route definitions. These are the primary entry points for backend workflows.
+
+```
+Search patterns (adapt to framework):
+  Express:    router.(get|post|put|patch|delete)\(
+  Fastify:    fastify.(get|post|put|patch|delete)\(
+  Next.js:    export (async )?function (GET|POST|PUT|PATCH|DELETE)
+  Hono:       app.(get|post|put|patch|delete)\(
+  tRPC:       .query\(|.mutation\(
+```
+
+For each route, record: `{ method, path, handler_function, file }`.
+
+Filter out trivial CRUD (single DB call + response). Keep routes that:
+- Call `startWorkflow`, `addJob`, `enqueue`, `emit`, `publish` (async dispatch)
+- Call 2+ service functions sequentially
+- Have transaction blocks (`$transaction`, `BEGIN`, `withTransaction`)
+- Return a job/workflow ID for polling
+- Trigger WebSocket/SSE events
+
+### Technique 2: Background Job Discovery
+
+Find all registered background jobs, workflows, and queues.
+
+```
+Search patterns:
+  Temporal:   export async function .*Workflow|workflowModules|startChild\(
+  BullMQ:     new Queue\(|new Worker\(|.add\(|.process\(
+  Celery:     @app.task|@shared_task
+  Inngest:    createFunction\(|inngest.send\(
+  Cron:       cron.schedule\(|@Cron\(|node-cron
+  EventEmitter: .on\(|.emit\(|EventEmitter
+```
+
+For Temporal specifically, also check:
+- `temporal/config/workflowModules.js` — workflow registry with queues and dependencies
+- `temporal/config/activityModules.js` — activity aggregation
+
+### Technique 3: Frontend Action Tracing
+
+Find UI-initiated multi-step flows.
+
+```
+Search patterns:
+  Redux thunks:   createAsyncThunk\(|dispatch\(
+  API calls:      api\.(post|put|patch|delete)\(|axios\.(post|put|patch|delete)\(|fetch\(
+  Form submits:   onSubmit|handleSubmit
+  Custom hooks:   use[A-Z].*\(\) that contain API calls
+```
+
+Focus on actions that:
+- POST/PUT/PATCH/DELETE to backend (not just GETs)
+- Dispatch multiple Redux actions in sequence
+- Start polling loops (`setInterval`, recursive `setTimeout`, retry patterns)
+- Open WebSocket connections or listen for server-sent events
+
+### Technique 4: Event & Message Tracing
+
+Find event-driven workflows (WebSocket, pub/sub, SSE).
+
+```
+Search patterns:
+  WebSocket:  socket.on\(|io.on\(|ws.on\(
+  SSE:        EventSource|text/event-stream
+  Redis pub:  .publish\(|.subscribe\(
+  Message:    .sendMessage\(|.postMessage\(
+```
+
+### Technique 5: Scheduled & Lifecycle Workflows
+
+```
+Search patterns:
+  App startup:    app.listen|bootstrap|onModuleInit|main\(\)
+  Shutdown:       SIGTERM|SIGINT|gracefulShutdown|onModuleDestroy
+  Migrations:     migrate|seed|up\(\)|down\(\)
+  Health checks:  /health|/ping|/ready|/live
+```
+
+---
+
+## Phase 2: Call Chain Tracing
+
+For each discovered entry point, trace the full execution path. Use one sub-agent per workflow for parallelism.
+
+### Tracing Algorithm
+
+```
+1. Start at the entry point function
+2. Read the function body
+3. For each function call or await:
+   a. Is it a DB operation? → Record as "Database" participant action
+   b. Is it an external API call? → Record as "{ServiceName}" participant action
+   c. Is it a queue/workflow dispatch? → Record as "{QueueSystem}" participant, then recurse into the dispatched handler
+   d. Is it a Redux dispatch? → Record as "Redux" participant action
+   e. Is it an internal function in the same service? → Recurse (but cap depth at 4)
+   f. Is it a WebSocket emit? → Record as "WebSocket" participant action
+4. Record branching (if/else, try/catch, switch) as alt/opt blocks
+5. Record loops (polling, retry, pagination) as loop blocks
+6. Stop when you hit: a return to the caller, a terminal DB write, or an external system response
+7. If a workflow trace exceeds the configured depth cap, stop tracing and note the overflow point with a comment like "→ [continues deeper, capped at depth N]". Do not silently truncate.
+```
+
+### Participant Identification
+
+Map code actors to diagram participants using this hierarchy:
+
+| Code Pattern | Participant Name |
+|---|---|
+| React component, hook, event handler | `User` + `Frontend` |
+| Express/API route handler | `API` |
+| Temporal workflow | `Temporal` |
+| BullMQ worker/processor | `Queue` |
+| Prisma/Sequelize/Knex call | `Database` |
+| External HTTP call (axios, fetch to external URL) | `{ServiceName}` (derive from URL or config) |
+| Redis operation | `Cache` |
+| WebSocket emit/broadcast | `WebSocket` |
+| File system / S3 / storage | `Storage` |
+| Git API calls | `Git` |
+| Email/SMS send | `Notifications` |
+| Auth provider (Keycloak, Better Auth, Auth0) | `Auth` |
+
+### Branching Detection
+
+Look for conditional logic that represents meaningful workflow forks:
+
+```
+- Version conflicts (optimistic locking)     → alt block
+- Permission/auth checks                      → opt block
+- Feature flags                               → opt block
+- Error handling with different outcomes       → alt block
+- Retry with backoff                          → loop block
+- Polling for completion                      → loop block
+- Batch processing                            → loop block
+```
+
+---
+
+## Phase 3: Classification & Filtering
+
+Not every API route is a "workflow". Classify and filter.
+
+### Workflow Categories
+
+| Category | Criteria | Include? |
+|---|---|---|
+| **Orchestration** | Multi-step, multi-service, async handoffs (save, publish, deploy) | Always |
+| **Auth & Session** | Login, logout, token refresh, SSO flows | Always |
+| **Real-time** | WebSocket connections, live updates, presence | Always |
+| **Event-driven** | Pub/sub chains, webhook handlers, event sourcing | Always |
+| **Scheduled** | Cron jobs, recurring workflows, cleanup tasks | Always |
+| **Data Pipeline** | ETL, import/export, migration, sync between systems | Always |
+| **Simple CRUD** | Single DB call + response, no branching | Skip |
+| **Static Serving** | File serving, asset delivery | Skip |
+| **Health/Config** | Health checks, config endpoints | Skip |
+
+### Complexity Scoring
+
+Score each workflow to determine diagram detail level:
+
+- **Steps**: Count distinct operations (DB calls, API calls, dispatches). 1-2 = simple, 3-5 = moderate, 6+ = complex
+- **Participants**: Count distinct systems involved. 2 = simple, 3-4 = moderate, 5+ = complex
+- **Branching**: Count alt/opt blocks. 0 = linear, 1-2 = moderate, 3+ = complex
+- **Async**: Has polling, callbacks, child workflows? +1 complexity level
+
+Simple workflows get a compact diagram. Complex workflows get full detail with alt/opt/loop blocks.
+
+---
+
+## Phase 4: Mermaid Diagram Generation
+
+### Diagram Template
+
+````markdown
+### {Workflow Name}
+
+**Trigger:** {What initiates this — button click, API call, cron schedule, event}
+**Participants:** {List of systems involved}
+**Key files:** {3-5 most important files in the chain}
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Frontend
+    participant API
+    participant Database
+
+    User->>Frontend: {User action}
+    Frontend->>API: {HTTP method} {path}
+    API->>Database: {Operation}
+    Database-->>API: {Result}
+    API-->>Frontend: {Response}
+    Frontend-->>User: {UI update}
+```
+
+**Notes:**
+- {Important implementation detail not visible in diagram}
+- {Performance consideration, timeout, retry policy}
+- {Known edge cases or failure modes}
+````
+
+### Diagram Rules
+
+1. **Arrow types**: Solid (`->>`) for calls/requests, dashed (`-->>`) for returns/responses
+2. **Activation bars**: Use `activate`/`deactivate` only for long-running operations (Temporal workflows, polling loops)
+3. **Alt blocks**: Use for real workflow branching (conflict vs success), not for error handling
+4. **Loop blocks**: Use for polling, retry, batch processing — include the condition
+5. **Opt blocks**: Use for conditional steps (feature flags, optional integrations)
+6. **Notes**: Use `Note over` for context that doesn't fit in arrow labels
+7. **Participant order**: Left-to-right follows the data flow direction (User → Frontend → API → Backend → Database)
+8. **Label brevity**: Arrow labels should be ≤8 words. Use the action, not the implementation detail
+9. **Max participants**: 7 per diagram. If more, split into sub-diagrams or collapse internal services
+10. **Max steps**: 15 visible interactions per diagram. For longer workflows, group related steps or use `rect` blocks
+
+### Grouping Related Steps
+
+For workflows with many sequential same-type operations, collapse them:
+
+```mermaid
+sequenceDiagram
+    rect rgb(240, 240, 240)
+        Note over Temporal,Database: Save all entities (10 types)
+        Temporal->>Database: Upsert objects, attributes, pages...
+        Database-->>Temporal: Saved
+    end
+```
+
+---
+
+## Phase 5: Output Assembly
+
+### Output File Structure
+
+Write to the user-specified path, or default to `docs/architecture/workflows.md`. Before writing output files, ensure the target directory exists. Create it with `mkdir -p` if needed.
+
+````markdown
+---
+generated: {YYYY-MM-DD}
+scope: {full | feature-name}
+workflows_found: {count}
+---
+
+# Codebase Workflows
+
+Auto-generated workflow map. Traces execution paths from user action to terminal effect.
+
+## Table of Contents
+
+| Workflow | Category | Trigger | Participants | Complexity |
+|---|---|---|---|---|
+| [{Name}](#{anchor}) | {Category} | {Trigger} | {Count} | {Simple/Moderate/Complex} |
+
+---
+
+## Orchestration Workflows
+
+### {Workflow Name}
+{Diagram + metadata as defined in Phase 4}
+
+---
+
+## Authentication & Session Workflows
+
+### {Workflow Name}
+{...}
+
+---
+
+## Real-time Workflows
+
+### {Workflow Name}
+{...}
+
+---
+
+## Event-driven Workflows
+
+### {Workflow Name}
+{...}
+
+---
+
+## Scheduled Workflows
+
+### {Workflow Name}
+{...}
+
+---
+
+## Data Pipeline Workflows
+
+### {Workflow Name}
+{...}
+````
+
+### Section Ordering
+
+1. Orchestration (the core business logic — save, publish, deploy)
+2. Authentication & Session
+3. Real-time (WebSocket, SSE)
+4. Event-driven (pub/sub, webhooks)
+5. Scheduled (cron, recurring)
+6. Data Pipeline (import/export, sync, migration)
+
+Skip empty sections.
+
+---
+
+## Execution Strategy
+
+### Full Discovery (default)
+
+Launch 5 parallel sub-agents for Phase 1 (one per technique). Collect results, deduplicate entry points, then launch parallel sub-agents for Phase 2 (one per workflow, max 8 concurrent). Run Phase 3-5 sequentially in the main agent.
+
+### Targeted Discovery
+
+User specifies a feature name. Skip broad Phase 1 scan. Instead:
+1. Find the feature's directory/files (grep for feature name in routes, components, workflows)
+2. Trace from those entry points only
+3. Output a single-feature workflow document
+
+### Incremental Update
+
+Read the existing workflow map file. For each workflow listed, check if the key files have changed (git diff). Re-trace only changed workflows. Preserve unchanged sections.
+
+---
+
+## Advanced Techniques
+
+### Payload Storage Detection
+
+Look for patterns where large payloads are stored separately and referenced by ID:
+```
+storePayload|savePayload|workflow_payload|jobData
+→ then: retrievePayload|fetchPayload|getPayload (in the worker/activity)
+```
+Note this in the diagram as a "Store payload → reference by ID" pattern.
+
+### Optimistic Locking Detection
+
+Look for version comparison patterns:
+```
+version.*!==|version.*conflict|StaleObjectError|OptimisticLock
+if.*serverVersion.*localVersion|if.*version.*mismatch
+```
+These indicate conflict branching that should appear as `alt` blocks.
+
+### Polling Loop Detection
+
+Look for patterns where the frontend waits for async completion:
+```
+setInterval|setTimeout.*recursive|poll|retry.*status
+GET.*status\?.*workflowId|GET.*status\?.*jobId
+```
+Note the polling interval and timeout in the diagram.
+
+### Child Workflow / Sub-job Detection
+
+Look for spawned sub-processes:
+```
+startChild\(|spawnChild|fork\(|.add\(.*queue
+Promise\.all.*map.*startWorkflow
+```
+These should appear as nested sequences or separate linked diagrams.
+
+### Transaction Boundary Detection
+
+Look for explicit transaction markers:
+```
+\$transaction|\$executeRaw|BEGIN|COMMIT|ROLLBACK
+withTransaction|runInTransaction|atomic
+```
+Group operations within a transaction using `rect` blocks in the diagram.
+
+### Rate Limiting & Middleware Detection
+
+Look for middleware applied to route groups:
+```
+rateLimit|rateLimiter|throttle
+authenticate|authorize|requireAuth|requireRole
+validate|validateBody|validateParams
+```
+Note these as guards in the diagram using `opt` blocks or notes.
+
+---
+
+## Quality Checks
+
+Before outputting, verify:
+
+- [ ] Every diagram has ≥3 participants (otherwise it's probably too simple to document)
+- [ ] Every diagram has both request and response arrows (no dangling calls)
+- [ ] Participant names are consistent across all diagrams (same DB = same name everywhere)
+- [ ] Alt/opt/loop blocks have clear conditions written in the block label
+- [ ] Key files listed actually exist in the codebase (verify with glob)
+- [ ] No workflow is documented twice under different names
+- [ ] Mermaid syntax is valid (no unclosed blocks, balanced activate/deactivate)
+- [ ] Table of contents anchors match actual heading anchors