@jetrabbits/agentic 0.3.3 → 0.5.0

package/areas/devops/ci-cd/workflows/onboard-repo.md

@@ -69,5 +69,34 @@ quality-gates:
 - Write `docs/ci-cd.md`: stages, how to run locally, how to add a new secret
 - **Done when:** documentation committed
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /onboard-repo"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Assess & Plan"]
+  step_2["2. Secrets & Environments Setup"]
+  step_3["3. Write Pipeline Config"]
+  step_4["4. First Run & Debug"]
+  step_5["5. Document"]
+  exit(["Green pipeline + staging deploy + documentation = repo onboarded."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_2 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Green pipeline + staging deploy + documentation = repo onboarded.

package/areas/devops/ci-cd/workflows/pipeline-debug.md

@@ -62,5 +62,31 @@ quality-gates:
 - Merge fix; confirm pipeline green on main
 - If flaky test: add to quarantine list; file follow-up ticket with `flaky-test` label
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /pipeline-debug"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Classify Failure"]
+  step_2["2. Diagnose by Category"]
+  step_3["3. Fix & Verify"]
+  step_4["4. Merge & Monitor"]
+  exit(["Pipeline green + root cause documented in ticket = debug complete."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Pipeline green + root cause documented in ticket = debug complete.

package/areas/devops/ci-cd/workflows/release-pipeline.md

@@ -110,6 +110,59 @@ helm upgrade --install order-service charts/order-service \
 - Verify business KPIs (conversion, checkout success, error funnel).
 - Publish deployment report with links to metrics, logs, and release artifact metadata.
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /release-pipeline"])
+  role_1["team-lead"]
+  role_2["pm"]
+  role_3["developer"]
+  role_4["devops-engineer"]
+  role_5["qa"]
+  step_1["1. Release Readiness and Freeze Check"]
+  step_2["2. Database Compatibility Gate"]
+  step_3["3. Tag Release"]
+  step_4["4. CI Release Pipeline (automated) — CI system"]
+  step_5["5. Deploy Staging"]
+  step_6["6. Production Gate"]
+  step_7["7. Canary Deployment"]
+  step_8["8. Feature Flag Progression"]
+  step_9["9. Post-Deploy Validation"]
+  exit(["Release is complete when 100% traffic is healthy, post-deploy checks pass,..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> step_7
+  step_7 --> step_8
+  step_8 --> step_9
+  step_9 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_1
+  role_3 -. owns .-> step_2
+  role_4 -. owns .-> step_2
+  role_3 -. owns .-> step_3
+  role_3 -. owns .-> step_4
+  role_4 -. owns .-> step_4
+  role_1 -. owns .-> step_4
+  role_2 -. owns .-> step_4
+  role_5 -. owns .-> step_4
+  role_4 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+  role_5 -. owns .-> step_6
+  role_4 -. owns .-> step_7
+  role_3 -. owns .-> step_8
+  role_5 -. owns .-> step_8
+  role_5 -. owns .-> step_9
+  role_2 -. owns .-> step_9
+  step_9 -. iterate if blocked .-> step_1
+```
+<!-- agent-diagram:end -->
+
 ## Rollback
 
 ```bash

package/areas/devops/database-ops/workflows/backup-verify.md

@@ -103,5 +103,32 @@ curl -X POST $SLACK_WEBHOOK \
 ```
 - **If any step fails:** post failure to Slack + page on-call → P1 incident
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /backup-verify"])
+  role_1["devops-engineer"]
+  step_1["1. Pre-Check: Backup Catalog"]
+  step_2["2. Provision Test Environment"]
+  step_3["3. Restore Latest Backup"]
+  step_4["4. Row Count Validation"]
+  step_5["5. Report + Cleanup"]
+  exit(["Restore successful + row counts validated + test env destroyed + report pos..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Restore successful + row counts validated + test env destroyed + report posted = backup verified.

package/areas/devops/database-ops/workflows/db-incident.md

@@ -82,5 +82,35 @@ SELECT pg_terminate_backend(<pid>); -- forceful
 - Root cause + fix in incident ticket
 - If query regression: create optimization ticket for development team
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /db-incident"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Triage"]
+  step_2["2. Immediate Mitigation by Type"]
+  step_3["3. Root Cause"]
+  step_4["4. Fix & Verify"]
+  step_5["5. Document"]
+  exit(["Metrics normal + root cause documented = db incident resolved."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Metrics normal + root cause documented = db incident resolved.

package/areas/devops/devsecops/workflows/policy-onboard.md

@@ -100,5 +100,39 @@ kubectl get constraint ${POLICY} -o jsonpath='{.status.byPod}'
 # metric: gatekeeper_violations_total{enforcement_action="deny"}
 ```
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /policy-onboard"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  role_3["team-lead"]
+  step_1["1. Design Policy"]
+  step_2["2. Unit Test"]
+  step_3["3. Dryrun in Staging"]
+  step_4["4. Fix Existing Violations"]
+  step_5["5. Switch to Enforce"]
+  step_6["6. Monitor Policy Health"]
+  exit(["Policy tested + existing violations resolved + enforce mode active + monito..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_4
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_3 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Policy tested + existing violations resolved + enforce mode active + monitoring in place = policy onboarded.

package/areas/devops/devsecops/workflows/security-scan-pipeline.md

@@ -151,5 +151,38 @@ echo "IaC:          $(cat iac-scan.sarif | jq '.runs[0].results | length') findi
 echo "SBOM:         attached to registry"
 ```
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /security-scan-pipeline"])
+  role_1["devops-engineer"]
+  step_1["1. Secrets Scan"]
+  step_2["2. SAST (Static Analysis)"]
+  step_3["3. Dependency CVE Scan"]
+  step_4["4. Container Image Scan"]
+  step_5["5. IaC Security Scan"]
+  step_6["6. Generate SBOM"]
+  step_7["7. Collate Report"]
+  exit(["Zero unresolved Critical/High + SBOM attached + scan report filed = securit..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> step_7
+  step_7 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+  role_1 -. owns .-> step_7
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Zero unresolved Critical/High + SBOM attached + scan report filed = security scan complete.

package/areas/devops/infrastructure/workflows/destroy-environment.md

@@ -92,5 +92,36 @@ aws dynamodb delete-item \
 ### 6. Document — `@devops-engineer`
 - Record in decommission log: environment, date, approver, reason, data disposition
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /destroy-environment"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  step_1["1. Confirm Scope"]
+  step_2["2. Approval"]
+  step_3["3. Pre-Destroy Backup"]
+  step_4["4. Ordered Teardown"]
+  step_5["5. Verify & Cleanup"]
+  step_6["6. Document"]
+  exit(["Terraform state empty + cloud console clean + documentation filed = environ..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Terraform state empty + cloud console clean + documentation filed = environment destroyed.

package/areas/devops/infrastructure/workflows/drift-remediation.md

@@ -62,5 +62,34 @@ terraform apply remediation.plan
 ### 5. Report — `@devops-engineer`
 - Update `drift-log.md` with date, resources affected, classification, action taken
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /drift-remediation"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  step_1["1. Detect Drift"]
+  step_2["2. Classify Findings"]
+  step_3["3. Remediate (if REMEDIATE class)"]
+  step_4["4. Investigate (if INVESTIGATE class)"]
+  step_5["5. Report"]
+  exit(["All drift classified + REMEDIATE resolved + INVESTIGATE escalated = drift c..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 All drift classified + REMEDIATE resolved + INVESTIGATE escalated = drift cycle complete.

package/areas/devops/infrastructure/workflows/module-development.md

@@ -97,5 +97,37 @@ git push origin modules/<module-name>/v1.0.0
 # Reference in other modules: ?ref=v1.0.0 (never ?ref=main)
 ```
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /module-development"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  step_1["1. Design Interface"]
+  step_2["2. Implement Module"]
+  step_3["3. Write Examples"]
+  step_4["4. Test"]
+  step_5["5. Code Review"]
+  step_6["6. Release"]
+  exit(["Module published + examples tested + documentation complete = module released."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_2 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Module published + examples tested + documentation complete = module released.

package/areas/devops/infrastructure/workflows/provision-environment.md

@@ -92,5 +92,34 @@ quality-gates:
 - Write `provision_report.md`: environment, resources created, cost estimate, next steps
 - **Done when:** report committed; outputs stored
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /provision-environment"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  step_1["1. Plan & Review"]
+  step_2["2. Apply Infrastructure"]
+  step_3["3. Configure Nodes (Ansible)"]
+  step_4["4. Smoke Tests"]
+  step_5["5. Document & Store Outputs"]
+  exit(["Terraform apply clean + Ansible 0 failures + smoke tests pass = environment..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Terraform apply clean + Ansible 0 failures + smoke tests pass = environment provisioned.

package/areas/devops/kubernetes/workflows/cluster-bootstrap.md

@@ -190,5 +190,41 @@ quality-gates:
   - Set up `kube-prometheus-stack` for cluster monitoring
 - **Output:** `bootstrap_report.md` — cluster version, node IPs, installed components, kubeconfig location
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /cluster-bootstrap"])
+  role_1["devops-engineer"]
+  step_1["1. Node Pre-Flight"]
+  step_2["2. Bootstrap First Control Plane"]
+  step_3["3. Install CNI (Cilium)"]
+  step_4["4. Join Remaining Control Plane Nodes"]
+  step_5["5. Join Worker Nodes"]
+  step_6["6. etcd Encryption at Rest"]
+  step_7["7. Core Platform Components"]
+  step_8["8. Apply Security Baselines"]
+  exit(["All nodes Ready + core components Running + etcd encrypted + monitoring liv..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> step_7
+  step_7 --> step_8
+  step_8 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+  role_1 -. owns .-> step_7
+  role_1 -. owns .-> step_8
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 All nodes Ready + core components Running + etcd encrypted + monitoring live = cluster bootstrapped.

package/areas/devops/kubernetes/workflows/debug-workload.md

@@ -104,5 +104,34 @@ quality-gates:
 - **Output:** `docs/incidents/<date>-<workload>-root-cause.md`
 - **Done when:** document committed; alert/runbook created if pattern is recurring
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /debug-workload"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Classify Symptom"]
+  step_2["2. Deep Diagnosis"]
+  step_3["3. Apply Fix"]
+  step_4["4. Verify & Monitor"]
+  step_5["5. Document"]
+  exit(["Pod Running + metrics stable + root cause documented = workload debug compl..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_2 -. owns .-> step_3
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Pod Running + metrics stable + root cause documented = workload debug complete.

package/areas/devops/kubernetes/workflows/onboard-service.md

@@ -120,5 +120,40 @@ quality-gates:
 - **Output:** metrics visible in Grafana; alerts configured
 - **Done when:** Grafana dashboard shows service metrics
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /onboard-service"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Namespace Setup"]
+  step_2["2. RBAC Setup"]
+  step_3["3. Network Policies"]
+  step_4["4. Helm Chart"]
+  step_5["5. ArgoCD Application"]
+  step_6["6. Validate & Smoke Test"]
+  step_7["7. Monitoring"]
+  exit(["Pod Running + health check passing + ArgoCD Healthy + metrics visible = ser..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> step_7
+  step_7 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_4
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_2 -. owns .-> step_6
+  role_1 -. owns .-> step_7
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Pod Running + health check passing + ArgoCD Healthy + metrics visible = service onboarded.

package/areas/devops/kubernetes/workflows/upgrade-cluster.md

@@ -146,6 +146,36 @@ kubectl get pdb -A
 - **Output:** `upgrade_report.md` — versions before/after, issues found, time taken
 - **Done when:** all Tier 1 services healthy; no unexpected pod restarts
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /upgrade-cluster"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  step_1["1. etcd Backup"]
+  step_2["2. Upgrade Control Plane (kubeadm)"]
+  step_3["3. Validate Control Plane"]
+  step_4["4. Upgrade Worker Nodes (rolling)"]
+  step_5["5. Post-Upgrade Validation"]
+  exit(["All nodes on target version + Tier 1 services healthy + upgrade report comm..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_2 -. owns .-> step_5
+  step_5 -. iterate if blocked .-> step_1
+```
+<!-- agent-diagram:end -->
+
 ## Rollback Plan
 
 ```bash

package/areas/devops/networking/workflows/onboard-ingress.md

@@ -60,5 +60,32 @@ done | sort | uniq -c
 - Point hostname to MetalLB external IP: `kubectl get svc -n ingress-nginx`
 - Add A record in DNS provider or internal CoreDNS
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /onboard-ingress"])
+  role_1["devops-engineer"]
+  step_1["1. Write Ingress Manifest"]
+  step_2["2. Apply & Wait for Certificate"]
+  step_3["3. Verify HTTPS"]
+  step_4["4. Verify Rate Limiting"]
+  step_5["5. DNS (if needed)"]
+  exit(["HTTPS accessible + cert issued + security headers present + rate limit veri..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 HTTPS accessible + cert issued + security headers present + rate limit verified = ingress onboarded.

package/areas/devops/networking/workflows/service-mesh-onboard.md

@@ -118,5 +118,32 @@ kubectl -n istio-system port-forward svc/kiali 20001:20001 &
 ```
 - **Done when:** service visible in mesh dashboard; no unmeshed traffic warnings
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /service-mesh-onboard"])
+  role_1["devops-engineer"]
+  step_1["1. Pre-Check Mesh Health"]
+  step_2["2. Enable Injection"]
+  step_3["3. Verify mTLS"]
+  step_4["4. Apply Traffic Policies"]
+  step_5["5. Validate in Mesh Dashboard"]
+  exit(["Sidecar injected + mTLS verified + policies applied + dashboard shows servi..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Sidecar injected + mTLS verified + policies applied + dashboard shows service = onboarded.

package/areas/devops/observability/workflows/alert-investigation.md

@@ -94,5 +94,34 @@ Saturation?
 - Is the alert threshold correct? (too sensitive = toil; too loose = misses real issues)
 - Create ticket if: runbook needs update, threshold needs tuning, or root cause needs a code fix
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /alert-investigation"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Acknowledge & Classify"]
+  step_2["2. Correlate Signals"]
+  step_3["3. Identify Root Cause"]
+  step_4["4. Mitigate"]
+  step_5["5. Post-Investigation Notes"]
+  exit(["Alert resolved or escalated + root cause noted + runbook quality assessed =..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Alert resolved or escalated + root cause noted + runbook quality assessed = investigation complete.