From 6cf5ec35587959621435f0553eac9e279106d7cc Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Thu, 7 May 2026 04:40:16 +0000
Subject: [PATCH 1/3] feat: add general-themes narrative content for Devin
 positioning and value

---
 shared/general-themes/README.md               |  14 ++
 .../general-themes/architecture-strengths.md  |  50 +++++++
 shared/general-themes/collaboration-model.md  | 110 ++++++++++++++++
 .../design-patterns-for-devin.md              | 124 ++++++++++++++++++
 .../general-themes/platform-capabilities.md   |  86 ++++++++++++
 shared/general-themes/value-narratives.md     |  97 ++++++++++++++
 shared/general-themes/when-to-use-devin.md    |  61 +++++++++
 7 files changed, 542 insertions(+)
 create mode 100644 shared/general-themes/README.md
 create mode 100644 shared/general-themes/architecture-strengths.md
 create mode 100644 shared/general-themes/collaboration-model.md
 create mode 100644 shared/general-themes/design-patterns-for-devin.md
 create mode 100644 shared/general-themes/platform-capabilities.md
 create mode 100644 shared/general-themes/value-narratives.md
 create mode 100644 shared/general-themes/when-to-use-devin.md

diff --git a/shared/general-themes/README.md b/shared/general-themes/README.md
new file mode 100644
index 0000000..db65206
--- /dev/null
+++ b/shared/general-themes/README.md
@@ -0,0 +1,14 @@
+# General Themes
+
+Core narratives and guidance for positioning Devin in workshops, customer engagements, and enablement materials. These documents describe **when**, **why**, and **how** to use Devin effectively — independent of any specific technology stack or industry.
+
+Reference these themes in workshop introductions, solution briefs, and talk tracks to set consistent expectations.
+
+| Document | Summary |
+|----------|---------|
+| [When to Use Devin](when-to-use-devin.md) | Trigger types (event-driven, large-scale, capacity-constrained) and the sweet spot for AI-assisted engineering |
+| [Architecture Strengths](architecture-strengths.md) | How Devin's clean-room execution, context retrieval, and shell access create unique value |
+| [Design Patterns](design-patterns-for-devin.md) | Proven patterns for structuring work so Devin succeeds: locally testable code, toolchain-agnostic stubs, divide-and-conquer |
+| [Platform Capabilities](platform-capabilities.md) | Scheduled sessions, playbooks, child agents, team-based operation, and Devin Review |
+| [Collaboration Model](collaboration-model.md) | The PR feedback loop, multi-user interaction, CI monitoring, and hibernation/resume behavior |
+| [Value Narratives](value-narratives.md) | How to frame Devin's impact: capacity unlocking, velocity, quality, risk reduction, and cost optimization |
diff --git a/shared/general-themes/architecture-strengths.md b/shared/general-themes/architecture-strengths.md
new file mode 100644
index 0000000..618dd25
--- /dev/null
+++ b/shared/general-themes/architecture-strengths.md
@@ -0,0 +1,50 @@
+# Devin's Architecture Strengths
+
+## Clean-Room Execution
+
+Devin starts every session with access to nothing. Each session runs on its own isolated VM with a fresh environment. This is a feature, not a limitation:
+
+- **Security by default** — Devin cannot access resources you have not explicitly granted. No ambient credentials, no inherited permissions, no lateral movement risk
+- **Service account friendly** — Organizations provision scoped credentials (API keys, PATs, cloud IAM roles) that Devin uses to access exactly the systems it needs. This mirrors how you would onboard any new team member — with least-privilege access
+- **Ephemeral testing environments** — Devin can deploy into throwaway environments (containers, cloud sandboxes) for integration testing, then tear them down. No persistent state leaks between sessions
+- **Reproducible from scratch** — Every session starts from the same base. No "works on my machine" drift. Environment configuration is codified and versioned
+
+## Context Retrieval
+
+Devin does not guess. It retrieves context programmatically before acting:
+
+| Source | How Devin Uses It |
+|--------|-------------------|
+| **Git repositories** | Clones repos, reads code, understands project structure, examines history |
+| **DeepWiki** | Auto-generated architectural documentation for any indexed repo — Devin reads this to understand systems it has never seen before |
+| **MCP servers** | Model Context Protocol lets Devin call external tools as if they were local: query Jira tickets, read Datadog logs, search Confluence, browse Azure DevOps boards |
+| **Shell access** | Devin has a full Linux shell. It can `curl` APIs, query databases, run CLI tools, install packages, and execute arbitrary commands |
+| **Browser** | Devin can navigate web pages, interact with UIs, and extract information from web-based tools |
+| **Knowledge notes** | Persistent, human-curated context (coding standards, architecture decisions, team conventions) that Devin retrieves automatically based on the task at hand |
+
+## Shell and Tool Access
+
+Devin's VM is a real Linux machine. This means:
+
+- **Build locally** — `npm install && npm test`, `mvn clean verify`, `dotnet build`, `cargo test` — Devin runs your project's build and test suite exactly as a developer would
+- **Run infrastructure tools** — `terraform plan`, `aws cloudformation deploy`, `kubectl apply`, `docker compose up` — Devin provisions and validates infrastructure
+- **Connect to remote systems** — SSH tunnels, VPN connections, database clients, API calls — Devin reaches private resources when given the right credentials
+- **Install what it needs** — Devin installs language runtimes, CLI tools, and dependencies on the fly. No pre-configured toolchain required (though you can configure persistent environments for faster startup)
+
+## Verification Model
+
+Devin is designed to verify its own work:
+
+1. **Local testing** — Devin runs unit tests, integration tests, linting, and type checking on its VM before opening a PR
+2. **CI monitoring** — After pushing, Devin watches CI checks and iterates if they fail. It reads CI logs, diagnoses failures, pushes fixes, and re-checks — up to multiple iterations
+3. **PR as the review gate** — Devin never merges its own work. It opens a PR, and humans (or Devin Review) inspect the diff before merging. The PR is the handoff point
+4. **External system validation** — Devin can connect to runners, staging environments, or external test systems to validate integration-level outcomes
+
+## Team Integration
+
+Devin operates as a team member, not a black box:
+
+- **Shared configuration** — Environment setup, knowledge notes, playbooks, and automations are shared across all sessions in an organization. Configure once, benefit everywhere
+- **PR-based communication** — Multiple team members can comment on the same Devin PR. Devin reads all comments and responds to feedback from any reviewer
+- **Session continuity** — Devin hibernates its VM after inactivity and resumes from the hibernated state when new feedback arrives. Context is preserved across the full lifecycle of a task
+- **Audit trail** — Every session has a full log of actions, decisions, and outputs. Nothing is opaque
diff --git a/shared/general-themes/collaboration-model.md b/shared/general-themes/collaboration-model.md
new file mode 100644
index 0000000..900616e
--- /dev/null
+++ b/shared/general-themes/collaboration-model.md
@@ -0,0 +1,110 @@
+# Collaboration Model
+
+Devin integrates into existing engineering workflows through pull requests, CI/CD pipelines, and team communication channels. It does not require new processes — it participates in the ones your team already uses.
+
+## The PR Feedback Loop
+
+The pull request is Devin's primary interface with human engineers. Every Devin implementation results in a PR that follows your team's existing review process.
+
+```
+Devin opens PR
+    ↓
+CI checks run automatically
+    ├── Pass → PR is ready for human review
+    └── Fail → Devin reads logs, pushes fix, CI re-runs
+          ↓
+Human reviewers inspect the diff
+    ├── Approve → Merge (human decision)
+    └── Request changes → Devin reads comments, iterates
+          ↓
+Devin pushes new commits addressing feedback
+    ↓
+CI re-runs → Review cycle repeats until approved
+```
+
+**Key properties:**
+- Devin **never merges its own PRs**. The merge decision is always human
+- CI serves as an automated quality gate. Devin iterates until CI passes or escalates if it cannot resolve the failure
+- PR comments are the communication channel. No special tools or interfaces required
+- The PR provides a complete audit trail of what Devin proposed and how it evolved through review
+
+## Multi-User Communication
+
+Multiple team members can interact with the same Devin session through PR comments:
+
+- **Reviewer A** comments: "This function should handle the null case"
+- **Reviewer B** comments: "Please add a test for the edge case in line 42"
+- Devin reads both comments, addresses both requests in subsequent commits
+- Both reviewers see Devin's response and can continue the conversation
+
+This works because Devin monitors its PRs for new comments. When any comment arrives, Devin resumes from its hibernated state, reads the full context, and responds.
+
+## CI Check Monitoring
+
+Devin actively monitors CI pipeline results after pushing code:
+
+1. **Watches for completion** — Devin polls CI status checks until all jobs complete
+2. **Reads failure logs** — When a check fails, Devin downloads and analyzes the CI job logs
+3. **Diagnoses the issue** — Devin identifies whether the failure is in its code, in the test environment, or in infrastructure
+4. **Pushes a fix** — For code-level failures, Devin commits a fix and waits for CI to re-run
+5. **Escalates if stuck** — After multiple failed attempts, Devin asks the user for help rather than looping indefinitely
+
+This creates a tight feedback loop where Devin iterates toward a green build without human intervention for straightforward failures.
+
+## Hibernation and Resume
+
+Devin sessions manage compute resources efficiently:
+
+- **Active work** — Devin is running on its VM, executing tasks, building code, running tests
+- **Waiting for feedback** — After opening a PR or asking a question, Devin enters a monitoring state
+- **Hibernation** — After inactivity, Devin snapshots its VM state and releases compute. The session appears idle but all context is preserved
+- **Resume** — When new input arrives (PR comment, CI result, user message), Devin restores its VM from the snapshot and continues exactly where it left off
+
+**What this means for users:**
+- You do not need to respond immediately. Devin waits patiently and resumes when you are ready
+- Sessions do not consume resources while waiting. Cost is proportional to active work time
+- Long-running tasks (multi-day code reviews, back-and-forth iterations) are natural. The session persists across the entire lifecycle
+
+## Working with Existing Tools
+
+Devin connects to your team's existing toolchain through MCP servers and API integrations:
+
+| Tool Category | Examples | How Devin Uses It |
+|---------------|----------|-------------------|
+| **Issue Trackers** | Jira, Linear, Azure DevOps | Read ticket details, update status, link PRs |
+| **Observability** | Datadog, New Relic, Azure Monitor | Query logs, traces, and metrics during incident investigation |
+| **Documentation** | Confluence, Notion | Read existing docs for context, update docs as part of implementation |
+| **Communication** | Slack, Microsoft Teams | Receive trigger messages, post status updates |
+| **Cloud Platforms** | AWS, Azure, GCP | Deploy resources, query infrastructure state, manage environments |
+| **Databases** | PostgreSQL, MySQL, MongoDB | Query schemas, run migrations, validate data integrity |
+
+These integrations are configured once at the organization level and are available to every session automatically.
+
+## Continuous Improvement Cycle
+
+Devin's effectiveness compounds over time as the team invests in configuration:
+
+```
+Initial Setup
+    ├── Connect repos
+    ├── Configure environment (runtimes, tools)
+    ├── Add knowledge notes (standards, conventions)
+    └── Set up MCP servers (Jira, Datadog, etc.)
+        ↓
+First Sessions
+    ├── Devin learns the codebase through context retrieval
+    ├── Team refines prompts based on results
+    └── Playbooks are created for recurring tasks
+        ↓
+Mature Operation
+    ├── Scheduled sessions handle routine O&M automatically
+    ├── Event-driven triggers respond to incidents and findings in real time
+    ├── Playbooks encode institutional knowledge for consistent execution
+    └── Child agents parallelize large-scale campaigns
+        ↓
+Compounding Value
+    ├── Less manual O&M overhead → engineers focus on architecture and product
+    ├── Faster incident response → reduced MTTR
+    ├── Consistent quality enforcement → fewer regressions
+    └── Scalable capacity → handle work surges without hiring
+```
diff --git a/shared/general-themes/design-patterns-for-devin.md b/shared/general-themes/design-patterns-for-devin.md
new file mode 100644
index 0000000..2799015
--- /dev/null
+++ b/shared/general-themes/design-patterns-for-devin.md
@@ -0,0 +1,124 @@
+# Design Patterns for Devin
+
+Proven patterns for structuring work, codebases, and processes so that Devin delivers high-quality results consistently.
+
+## Pattern 1: Locally Buildable and Testable Code
+
+**Principle:** If a human developer can clone the repo and run `make test` (or equivalent) with no external dependencies, Devin can too.
+
+**Why it matters:** Devin verifies its own changes by running your build and test suite. If the build requires a VPN, a licensed IDE, a proprietary database, or manual setup steps, Devin cannot complete the feedback loop.
+
+**How to apply:**
+- Containerize dependencies (Docker Compose for databases, message brokers, caches)
+- Use in-memory or file-based databases for tests (SQLite, H2, Testcontainers)
+- Provide seed data scripts that create a working test environment from scratch
+- Document the build/test command in the README (`npm test`, `./gradlew check`, `dotnet test`)
+- Use environment variables for configuration — Devin can inject these via secrets management
+
+## Pattern 2: Event-Driven Triggers
+
+**Principle:** Connect Devin to your existing event sources so it responds to signals automatically — no human has to remember to invoke it.
+
+**Architecture:**
+```
+Event Source (CI, alerting, issue tracker)
+    ↓ webhook / API call
+Trigger Layer (GitHub Actions, Azure Function, Lambda)
+    ↓ Devin API: POST /sessions
+Devin Session (autonomous execution)
+    ↓ PR / comment / status update
+Review Gate (human approval, CI checks)
+```
+
+**Common triggers:**
+- CI pipeline failure → Devin reads logs, pushes fix
+- SAST finding above threshold → Devin remediates
+- Work item tagged → Devin implements
+- Alert fires → Devin investigates and triages
+- Schedule (cron) → Devin performs routine maintenance
+
+**Key safeguards:**
+- Filter out Devin's own events to prevent infinite loops (check PR author, skip `devin-ai-integration[bot]`)
+- Set a maximum retry count per trigger to avoid runaway sessions
+- Use idempotency keys to prevent duplicate sessions from the same event
+
+## Pattern 3: Divide and Conquer with Child Agents
+
+**Principle:** For large-scale work, a parent agent breaks the problem into independent units and spawns a child agent for each one.
+
+**When to use:**
+- Migrating N modules/services/jobs (each is independent)
+- Remediating N security findings across M repos
+- Generating tests for N uncovered files
+- Applying the same refactoring pattern across many codebases
+
+**Architecture:**
+```
+Parent Agent
+├── Analyzes scope (list of targets)
+├── Creates playbook (reusable methodology)
+├── Spawns Child Agent 1 → target A → PR
+├── Spawns Child Agent 2 → target B → PR
+├── ...
+├── Spawns Child Agent N → target N → PR
+└── Monitors progress, handles failures
+```
+
+**Best practices:**
+- Define a clear, repeatable unit of work for each child
+- Use playbooks to encode the methodology so every child follows the same process
+- Set a maximum concurrency to avoid overwhelming CI or API rate limits
+- Have the parent agent check child results and escalate failures
+
+## Pattern 4: Human-in-the-Loop via PR Feedback
+
+**Principle:** Devin proposes changes via pull requests. Humans review, comment, and approve. Devin iterates based on feedback.
+
+**The loop:**
+1. Devin opens a PR with its implementation
+2. Reviewers (human or Devin Review) inspect the diff
+3. Reviewers leave comments requesting changes
+4. Devin reads the comments, makes changes, pushes new commits
+5. CI re-runs, Devin monitors results
+6. Repeat until approved and merged
+
+**Why this works:**
+- The PR is a familiar, auditable artifact that fits existing workflows
+- Multiple team members can contribute feedback to the same session
+- Devin hibernates between interactions — no wasted compute while waiting for review
+- The merge decision always belongs to a human
+
+## Pattern 5: Toolchain-Agnostic Stubs
+
+**Principle:** Design integration architectures with replaceable tool slots. The pattern stays the same; the specific tool is pluggable.
+
+**Example — Security Scanning Pipeline:**
+```
+[SAST Tool] → webhook → [Trigger Layer] → Devin API → [Remediation Session]
+```
+
+The `[SAST Tool]` slot can be filled by:
+- SonarQube / SonarCloud
+- Checkmarx
+- Fortify
+- Snyk
+- Trivy
+- Any tool that produces findings in a parseable format
+
+**How to apply:**
+- Document the interface contract (webhook payload shape, findings format)
+- Provide reference implementations for 2-3 popular tools
+- Include a "bring your own tool" guide showing how to adapt the pattern
+
+## Pattern 6: Context Layer Configuration
+
+**Principle:** Invest in configuring Devin's persistent context layer once to benefit every future session.
+
+**Components:**
+- **Knowledge notes** — Coding standards, architecture decisions, team conventions, domain glossary. Devin retrieves these automatically when relevant
+- **Environment configuration** — Pre-installed tools, language runtimes, environment variables, startup scripts. Sessions start ready to build
+- **Playbooks** — Step-by-step procedures for recurring tasks (deploy, migrate, audit). Devin follows playbooks precisely
+- **MCP servers** — External tool connections (Jira, Datadog, Confluence) that persist across sessions. Configure once, use everywhere
+- **Git connections** — Repository access that applies to all sessions in the organization
+
+**ROI:** The upfront investment in context configuration pays dividends across every subsequent session. A well-configured Devin organization starts every task with the right tools, knowledge, and access — no per-session setup friction.
diff --git a/shared/general-themes/platform-capabilities.md b/shared/general-themes/platform-capabilities.md
new file mode 100644
index 0000000..9976918
--- /dev/null
+++ b/shared/general-themes/platform-capabilities.md
@@ -0,0 +1,86 @@
+# Platform Capabilities
+
+Devin is more than a single-session code generator. It is a team-based engineering platform with scheduling, orchestration, review, and collaboration features that compound in value over time.
+
+## Scheduled Sessions
+
+Devin sessions can run on a recurring schedule — daily, weekly, or custom cron expressions — to perform proactive operations and maintenance without human initiation.
+
+**Use cases:**
+- **Dependency version bumps** — Weekly scan for outdated packages, open PRs with bumped versions and passing tests
+- **License compliance audits** — Monthly check that all dependencies meet organizational license policies
+- **Dead code detection** — Periodic analysis to identify unused imports, unreachable functions, and deprecated API usage
+- **Documentation freshness** — After code merges, update READMEs, API docs, and changelogs automatically
+- **Security scanning** — Scheduled SAST/SCA runs that remediate findings before they accumulate
+- **Test coverage monitoring** — Weekly reports on coverage trends, with auto-generated tests for newly uncovered code
+
+**Configuration:** Scheduled sessions are configured in the Devin UI or via the API. Each schedule specifies the prompt, target repository, and recurrence pattern.
+
+## Playbooks
+
+Playbooks are reusable, step-by-step procedures that encode a proven methodology. When Devin follows a playbook, every session applies the same process — regardless of which team member triggers it.
+
+**Characteristics:**
+- **Repeatable** — The same playbook produces consistent results across different repos and teams
+- **Versionable** — Playbooks evolve over time as the team refines the methodology
+- **Shareable** — One engineer writes the playbook; the entire team benefits
+- **Composable** — Playbooks can reference other playbooks for multi-phase workflows
+
+**Examples:**
+- Framework upgrade playbook: check compatibility → update dependencies → fix breaking changes → run tests → update docs
+- Incident response playbook: query logs → identify root cause → implement fix → verify → update runbook
+- Microservice extraction playbook: identify bounded context → extract interfaces → create new service → migrate data → set up CI/CD
+
+## Child Agents (Divide and Conquer)
+
+Devin can create child sessions to parallelize work. A parent agent breaks a large task into independent units and spawns a child agent for each one.
+
+**How it works:**
+1. Parent agent analyzes the scope (e.g., "50 microservices need Spring Boot 3 upgrade")
+2. Parent creates a playbook encoding the upgrade procedure
+3. Parent spawns child agents — one per microservice — each following the same playbook
+4. Children work in parallel on their own VMs, each opening a PR
+5. Parent monitors progress and handles failures or escalations
+
+**Scale:** This pattern enables work that would otherwise require a dedicated team. Each child agent is independent — its own VM, its own branch, its own PR. Failures in one child do not affect others.
+
+## Team-Based Operation
+
+Devin is not a per-user tool. It operates as a shared team resource with organizational context.
+
+**Shared configuration:**
+- **Context layer** — Knowledge notes, environment setup, and MCP connections apply to all sessions in the organization. Configure once, benefit everywhere
+- **Automations** — Webhooks, scheduled sessions, and trigger rules are organization-wide. Every team member's events route through the same automation layer
+- **Git connections** — Repository access is configured at the org level. All sessions can clone and push to connected repos
+
+**Multi-user collaboration:**
+- Multiple team members can comment on the same Devin-created PR
+- Devin reads and responds to feedback from any reviewer — not just the session creator
+- Teams can share playbooks, knowledge notes, and session templates
+
+## Devin Review
+
+Devin Review is a proactive code review capability that analyzes new pull requests for bugs, security issues, and quality problems.
+
+**Capabilities:**
+- **Bug detection** — Finds logic errors, null pointer risks, race conditions, and edge cases in new diffs
+- **PR digestion** — Summarizes large PRs into readable overviews, highlighting the most important changes and potential risks
+- **Proactive remediation** — When Devin Review finds a bug, it can automatically open a fix PR rather than just commenting
+- **Configurable rules** — Teams can customize what Devin Review checks for, adjusting sensitivity and focus areas
+
+**Workflow integration:**
+- Devin Review runs automatically on new PRs (configurable per repo or org)
+- Findings appear as PR comments, indistinguishable from human review feedback
+- Developers respond to Devin Review comments just as they would to any reviewer
+- Critical findings can block merge via required status checks
+
+## Session Lifecycle
+
+Devin sessions have a deliberate lifecycle optimized for efficiency:
+
+1. **Active** — Devin is executing tasks, running builds, writing code
+2. **Waiting for feedback** — Devin has opened a PR or asked a question. It monitors for PR comments and CI check results
+3. **Hibernated** — After a period of inactivity, Devin hibernates its VM. The session state is preserved but compute resources are released
+4. **Resumed** — When new feedback arrives (PR comment, CI result, user message), Devin resumes from the hibernated state with full context. No work is lost
+
+This lifecycle means Devin does not waste compute while waiting for human review. It acts immediately when feedback arrives and sleeps efficiently in between.
diff --git a/shared/general-themes/value-narratives.md b/shared/general-themes/value-narratives.md
new file mode 100644
index 0000000..3654d5f
--- /dev/null
+++ b/shared/general-themes/value-narratives.md
@@ -0,0 +1,97 @@
+# Value Narratives
+
+Frameworks for articulating Devin's impact across different audiences and decision-making contexts.
+
+## Capacity Unlocking
+
+**For: Engineering Management, Delivery Leadership**
+
+Every engineering team has a backlog of "should-do" work that gets deferred indefinitely: dependency updates, test coverage gaps, documentation debt, accessibility fixes, security finding remediation. This work is valuable but never urgent enough to displace feature development.
+
+Devin unlocks this capacity by executing well-defined tasks autonomously:
+- Engineers review PRs (minutes of effort) instead of doing the implementation (hours of effort)
+- Routine maintenance runs on schedule without consuming sprint capacity
+- Surge capacity is available on demand — spin up child agents for a migration campaign without pulling engineers off their current work
+
+**Metric framing:** "How many story points per sprint are consumed by maintenance tasks? Devin can reclaim those points for product development."
+
+## Engineering Focus Elevation
+
+**For: Engineering Leadership, Product Management**
+
+Engineers are most valuable when they are designing systems, solving novel problems, and making architectural decisions. They are least valuable — and least engaged — when they are doing repetitive, well-defined tasks at scale.
+
+Devin shifts the distribution of engineering effort:
+- **Before:** 60% implementation, 20% design, 20% review → engineers spend most of their time on tasks Devin could do
+- **After:** 30% implementation (complex/novel), 30% design, 30% review, 10% Devin-output review → engineers focus on what only humans can do
+
+**Narrative:** "Devin does the implementation work so your engineers can focus on architecture, design, and the decisions that require human judgment."
+
+## Velocity Multiplication
+
+**For: Delivery, Program Management**
+
+Devin multiplies throughput without multiplying headcount. For large-scale campaigns (migrations, upgrades, compliance remediation), Devin's child agent model processes N targets in parallel:
+
+- **Sequential (human only):** 50 microservices × 4 hours each = 200 engineer-hours (5 weeks at 40 hrs/week)
+- **Parallel (Devin + human review):** 50 child agents × 1 hour each + human review = 50 ACU-hours + 25 review-hours (completed in days, not weeks)
+
+**Narrative:** "The timeline for this migration drops from 5 weeks to 5 days because Devin parallelizes the implementation and engineers review the PRs."
+
+## Quality Improvement
+
+**For: QA Leadership, Security, Compliance**
+
+Devin applies checks consistently and tirelessly:
+- **Devin Review** catches bugs in every PR — not just the ones a reviewer happens to notice
+- **Scheduled SAST** finds and remediates vulnerabilities before they reach production
+- **Test generation** fills coverage gaps systematically, not opportunistically
+- **Compliance audits** run on every dependency change, not just before release
+
+**Narrative:** "Devin does not forget to run the security scan. It does not skip the accessibility check because the sprint is tight. It applies the same rigor to every change, every time."
+
+## Risk Reduction
+
+**For: CISO, CTO, Risk Management**
+
+Devin reduces operational risk through consistency and speed:
+- **Mean Time to Remediate (MTTR)** drops when Devin responds to incidents automatically — no waiting for an engineer to be available
+- **Vulnerability exposure window** shrinks when SAST findings are remediated in hours instead of sprint cycles
+- **Change risk** decreases when every PR gets automated review for logic errors, security issues, and regressions
+- **Knowledge bus factor** decreases when institutional knowledge is encoded in playbooks and knowledge notes rather than residing in individual engineers' heads
+
+**Narrative:** "Your vulnerability exposure window goes from 'next sprint' to 'next CI run' because Devin remediates findings as soon as they are detected."
+
+## Cost Optimization
+
+**For: FinOps, Finance, Executive Leadership**
+
+Devin's cost model is consumption-based (ACU — Agent Compute Units):
+- **Pay for active work** — Devin hibernates during idle time. You pay for compute only when Devin is executing
+- **Predictable budgeting** — ACU budgets can be set at the organization, team, or user level with hard enforcement
+- **ROI measurement** — Each session produces measurable output (PRs merged, findings remediated, tests added). ROI is directly attributable
+- **Licensing cost avoidance** — Migration from expensive proprietary tools/languages (COBOL, SAS, Oracle Forms, Informatica) to open-source alternatives reduces ongoing license costs. Devin accelerates the migration that unlocks those savings
+
+**Narrative:** "The ACU cost for this migration campaign is a fraction of the engineering salary cost, and it delivers the licensing savings months earlier than a manual approach."
+
+## Audience-Specific Talking Points
+
+### For Sales Engineering
+- Lead with **capacity unlocking** and **velocity multiplication** — these resonate with engineering leaders who feel understaffed
+- Show **event-driven patterns** (incident response, security remediation) as "set it and forget it" value
+- Use the **divide-and-conquer** pattern to demonstrate scale that is impossible with manual approaches
+
+### For Solution Delivery
+- Lead with **playbooks** and **design patterns** — these map directly to engagement deliverables
+- Emphasize **toolchain-agnostic stubs** — customers do not need to change their tool stack
+- Show **scheduled sessions** as ongoing value that extends beyond the initial engagement
+
+### For Training & Enablement
+- Lead with the **collaboration model** — Devin works the way engineers already work (PRs, CI, code review)
+- Use **hands-on labs** from the partner workshops to demonstrate capabilities in a safe environment
+- Emphasize the **continuous improvement cycle** — Devin gets more effective as the team invests in configuration
+
+### For Leadership
+- Lead with **risk reduction** and **cost optimization** — these are the decision-making factors
+- Frame Devin as **team augmentation**, not replacement — the engineering team becomes more effective, not smaller
+- Show the **compounding value** model — initial setup investment yields growing returns over time
diff --git a/shared/general-themes/when-to-use-devin.md b/shared/general-themes/when-to-use-devin.md
new file mode 100644
index 0000000..e263825
--- /dev/null
+++ b/shared/general-themes/when-to-use-devin.md
@@ -0,0 +1,61 @@
+# When to Use Devin
+
+## Overview
+
+Devin is an autonomous software engineering agent. It excels at well-defined engineering tasks that would otherwise not get done — because of constrained capacity, prohibitive volume, insufficient priority, or sheer difficulty. The key insight is not "replace engineers" but "unlock work that is currently blocked or deferred."
+
+## Trigger Categories
+
+### Event-Driven (Reactive)
+
+Devin responds to signals from your existing toolchain. A webhook, alert, or tag transition fires and Devin begins working immediately — no human has to context-switch.
+
+| Trigger | Example | Why Devin? |
+|---------|---------|-----------|
+| **Incident alert** | PagerDuty/OpsGenie/Azure Monitor fires on 5xx spike | Devin queries logs via MCP, identifies root cause, opens a fix PR — all before the on-call engineer finishes reading the alert |
+| **Security finding** | SAST scan (SonarQube, Snyk, Checkmarx) detects HIGH/CRITICAL CVEs | Devin reads the scan report, remediates findings, pushes a fix, and the re-scan verifies the fix — closed-loop |
+| **Ticket assignment** | Jira/Linear/ADO work item tagged `Devin:Implementation` | Devin reads the acceptance criteria, implements, opens a PR, and links it back to the ticket |
+| **PR event** | PR opened by a developer triggers Devin Review | Devin reviews the diff for bugs, style issues, and test gaps — proactively opening remediation PRs for discovered issues |
+| **CI failure** | Build or test fails on a branch | Devin reads the failure logs, diagnoses the issue, and pushes a fix commit to the same branch |
+
+### Large-Scale (Proactive Campaigns)
+
+Devin divides and conquers work that would take a team of engineers weeks. A parent agent plans the campaign, then spawns child agents — each handling one unit of work (one repo, one module, one migration target).
+
+| Campaign | Example | Why Devin? |
+|----------|---------|-----------|
+| **Codebase modernization** | Translate COBOL → Java across 200 copybooks | Each child agent handles one copybook. Humans review the PRs. Volume that would take months becomes weeks |
+| **Framework migration** | Upgrade Spring Boot 2.x → 3.x across 50 microservices | Each service gets its own agent. Jakarta namespace migration, dependency bumps, and test verification — all parallelized |
+| **Language translation** | Migrate SAS → Python/Snowflake for 300 ETL jobs | Devin translates each job, generates equivalence tests, and validates output parity |
+| **Dependency hygiene** | Bump all transitive dependencies across an org's repos | Scheduled weekly. Devin opens PRs, CI validates, humans merge |
+| **Security backlog** | Remediate 500 open Snyk findings across 80 repos | Each finding gets its own agent session. Devin reads the advisory, applies the fix, runs tests |
+| **Test coverage** | Generate unit tests for 200 uncovered modules | Devin analyzes each module, writes tests following existing conventions, achieves target coverage |
+
+### Capacity-Constrained (Ongoing O&M)
+
+Work that engineers know should be done but deprioritize because higher-value tasks demand their attention. Devin runs on a schedule or is triggered by routine events, handling the hygiene so engineers can focus on architecture, product features, and complex debugging.
+
+| Task | Frequency | Why Devin? |
+|------|-----------|-----------|
+| **Dependency updates** | Weekly | Devin bumps versions, runs tests, opens PRs. Engineers merge if green |
+| **Dead code cleanup** | Monthly | Devin identifies unused imports, unreachable code, and deprecated APIs. Opens cleanup PRs |
+| **Documentation refresh** | On code change | Devin updates inline docs, READMEs, and API docs when code changes land |
+| **License compliance** | Quarterly | Devin audits all dependencies for license compatibility, flags violations |
+| **Accessibility audits** | Sprint boundary | Devin runs axe/Lighthouse, remediates findings, opens PRs |
+
+## The Sweet Spot
+
+Give Devin work that is:
+
+1. **Well-defined** — clear acceptance criteria, verifiable outcomes (tests pass, scan is clean, PR is merged)
+2. **Repetitive at scale** — the same pattern applied to many targets (repos, modules, findings)
+3. **Lower priority but valuable** — work humans would do if they had unlimited time
+4. **Automatable end-to-end** — Devin can fetch context, implement, test, and submit for review without manual intervention
+5. **Safe to iterate** — Devin works on branches, never pushes to main, and humans always approve the merge
+
+## What Devin Needs to Succeed
+
+- **Indexed codebases** — Devin retrieves context from code repositories it has access to. Connect your repos via Git integrations
+- **Programmatic access to remote resources** — MCP servers, API keys, and service account credentials let Devin interact with your toolchain (Jira, Datadog, Azure DevOps, databases, etc.)
+- **Locally buildable and testable code** — Devin runs builds and tests on its own VM. If your code requires a locally reproducible build, Devin can verify its own work
+- **Clear prompts** — The more specific the instructions, the better the outcome. Include repo names, file paths, acceptance criteria, and examples when possible

From 3d7dafe950237459dc30fae29403af571f135d6c Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 8 May 2026 18:17:55 +0000
Subject: [PATCH 2/3] improve general-themes: add shared context layer, soften
 overstatements, strengthen licensing narrative

- architecture-strengths: add Shared Context Layer subsection under Clean-Room Execution covering VM blueprints, knowledge, playbooks, MCP, secrets, Git connections
- architecture-strengths: replace 'Devin does not guess' with nuanced phrasing about programmatic context retrieval
- architecture-strengths: update Team Integration to reference shared context layer
- when-to-use-devin: strengthen licensing cost motivation in large-scale campaigns, add cost-motivated criterion to sweet spot
- platform-capabilities: expand Team-Based Operation with full shared config layer enumeration
- platform-capabilities: add session persistence note to lifecycle section
- collaboration-model: add session persistence to multi-user section, reference shared context layer
- collaboration-model: add secrets to continuous improvement cycle
- design-patterns: strengthen locally testable code rationale, reference secrets management in env vars guidance
- design-patterns: expand Pattern 6 with secrets, cross-reference to architecture-strengths
- value-narratives: strengthen licensing cost avoidance narrative
- README: update architecture-strengths summary
---
 shared/general-themes/README.md               |  2 +-
 .../general-themes/architecture-strengths.md  | 21 +++++++++++++++----
 shared/general-themes/collaboration-model.md  | 17 ++++++++-------
 .../design-patterns-for-devin.md              | 17 ++++++++-------
 .../general-themes/platform-capabilities.md   | 14 +++++++++----
 shared/general-themes/value-narratives.md     |  2 +-
 shared/general-themes/when-to-use-devin.md    |  7 ++++---
 7 files changed, 51 insertions(+), 29 deletions(-)

diff --git a/shared/general-themes/README.md b/shared/general-themes/README.md
index db65206..4f8e04a 100644
--- a/shared/general-themes/README.md
+++ b/shared/general-themes/README.md
@@ -7,7 +7,7 @@ Reference these themes in workshop introductions, solution briefs, and talk trac
 | Document | Summary |
 |----------|---------|
 | [When to Use Devin](when-to-use-devin.md) | Trigger types (event-driven, large-scale, capacity-constrained) and the sweet spot for AI-assisted engineering |
-| [Architecture Strengths](architecture-strengths.md) | How Devin's clean-room execution, context retrieval, and shell access create unique value |
+| [Architecture Strengths](architecture-strengths.md) | Clean-room execution with shared context layer, context retrieval, shell access, and verification model |
 | [Design Patterns](design-patterns-for-devin.md) | Proven patterns for structuring work so Devin succeeds: locally testable code, toolchain-agnostic stubs, divide-and-conquer |
 | [Platform Capabilities](platform-capabilities.md) | Scheduled sessions, playbooks, child agents, team-based operation, and Devin Review |
 | [Collaboration Model](collaboration-model.md) | The PR feedback loop, multi-user interaction, CI monitoring, and hibernation/resume behavior |
diff --git a/shared/general-themes/architecture-strengths.md b/shared/general-themes/architecture-strengths.md
index 618dd25..da8a479 100644
--- a/shared/general-themes/architecture-strengths.md
+++ b/shared/general-themes/architecture-strengths.md
@@ -2,16 +2,29 @@
 
 ## Clean-Room Execution
 
-Devin starts every session with access to nothing. Each session runs on its own isolated VM with a fresh environment. This is a feature, not a limitation:
+Each Devin session runs on its own isolated VM. By default, a session has access to nothing — no ambient credentials, no inherited permissions. This isolation is a security feature, not a limitation.
 
-- **Security by default** — Devin cannot access resources you have not explicitly granted. No ambient credentials, no inherited permissions, no lateral movement risk
+- **Security by default** — Devin cannot access resources you have not explicitly granted. No lateral movement risk between sessions or systems
 - **Service account friendly** — Organizations provision scoped credentials (API keys, PATs, cloud IAM roles) that Devin uses to access exactly the systems it needs. This mirrors how you would onboard any new team member — with least-privilege access
 - **Ephemeral testing environments** — Devin can deploy into throwaway environments (containers, cloud sandboxes) for integration testing, then tear them down. No persistent state leaks between sessions
 - **Reproducible from scratch** — Every session starts from the same base. No "works on my machine" drift. Environment configuration is codified and versioned
 
+### Shared Context Layer
+
+While each session's runtime is isolated, Devin does not start from scratch. A shared context and configuration layer persists across every session in an organization:
+
+- **Environment configurations (VM blueprints)** — Pre-built machine images with dependencies, language runtimes, tools, and startup scripts baked in. Sessions boot ready to build, not waiting for `npm install`
+- **Knowledge notes** — Persistent, human-curated context (coding standards, architecture decisions, team conventions, domain glossary) that Devin retrieves automatically based on the task at hand
+- **Playbooks** — Repeatable procedures that encode institutional methodology. Every session that invokes a playbook follows the same proven steps
+- **MCP servers** — Pre-configured integrations (Jira, Datadog, Confluence, Azure DevOps) available to every session in the org without per-session setup
+- **Secrets** — Scoped credentials injected into the environment at session start. No credentials embedded in prompts or code — they flow through the platform's secrets management layer
+- **Git connections** — Repository access configured at the org level. All sessions can clone and push to connected repos immediately
+
+This design gives you both: **clean-room isolation for security** and a **shared context layer for productivity**. Each worker VM is sandboxed, but the organization's accumulated knowledge and configuration flow into every session automatically.
+
 ## Context Retrieval
 
-Devin does not guess. It retrieves context programmatically before acting:
+Devin retrieves context programmatically before acting — it pulls from indexed codebases, configured integrations, and remote resources rather than relying on assumptions:
 
 | Source | How Devin Uses It |
 |--------|-------------------|
@@ -44,7 +57,7 @@ Devin is designed to verify its own work:
 
 Devin operates as a team member, not a black box:
 
-- **Shared configuration** — Environment setup, knowledge notes, playbooks, and automations are shared across all sessions in an organization. Configure once, benefit everywhere
+- **Organizational configuration** — The shared context layer (environment configs, knowledge, playbooks, MCP servers, secrets, Git connections) applies to every session in the organization. One engineer configures it; every subsequent session benefits. See [Clean-Room Execution → Shared Context Layer](#shared-context-layer) above
 - **PR-based communication** — Multiple team members can comment on the same Devin PR. Devin reads all comments and responds to feedback from any reviewer
 - **Session continuity** — Devin hibernates its VM after inactivity and resumes from the hibernated state when new feedback arrives. Context is preserved across the full lifecycle of a task
 - **Audit trail** — Every session has a full log of actions, decisions, and outputs. Nothing is opaque
diff --git a/shared/general-themes/collaboration-model.md b/shared/general-themes/collaboration-model.md
index 900616e..0a332da 100644
--- a/shared/general-themes/collaboration-model.md
+++ b/shared/general-themes/collaboration-model.md
@@ -1,6 +1,6 @@
 # Collaboration Model
 
-Devin integrates into existing engineering workflows through pull requests, CI/CD pipelines, and team communication channels. It does not require new processes — it participates in the ones your team already uses.
+Devin integrates into existing engineering workflows through pull requests, CI/CD pipelines, and team communication channels. It participates in the processes your team already uses — no new tools or workflows required.
 
 ## The PR Feedback Loop
 
@@ -37,7 +37,7 @@ Multiple team members can interact with the same Devin session through PR commen
 - Devin reads both comments, addresses both requests in subsequent commits
 - Both reviewers see Devin's response and can continue the conversation
 
-This works because Devin monitors its PRs for new comments. When any comment arrives, Devin resumes from its hibernated state, reads the full context, and responds.
+This works because Devin monitors its PRs for new comments. When any comment arrives, Devin resumes from its hibernated state, reads the full conversation context, and responds. The session persists across the entire lifecycle of the task — there is no context loss between interactions.
 
 ## CI Check Monitoring
 
@@ -78,18 +78,19 @@ Devin connects to your team's existing toolchain through MCP servers and API int
 | **Cloud Platforms** | AWS, Azure, GCP | Deploy resources, query infrastructure state, manage environments |
 | **Databases** | PostgreSQL, MySQL, MongoDB | Query schemas, run migrations, validate data integrity |
 
-These integrations are configured once at the organization level and are available to every session automatically.
+These integrations are configured once at the organization level as part of Devin's shared context layer (see [Architecture Strengths → Shared Context Layer](architecture-strengths.md#shared-context-layer)) and are available to every session automatically.
 
 ## Continuous Improvement Cycle
 
-Devin's effectiveness compounds over time as the team invests in configuration:
+Devin's effectiveness compounds over time as the team invests in the shared context layer:
 
 ```
 Initial Setup
-    ├── Connect repos
-    ├── Configure environment (runtimes, tools)
-    ├── Add knowledge notes (standards, conventions)
-    └── Set up MCP servers (Jira, Datadog, etc.)
+    ├── Connect repos (Git connections)
+    ├── Configure environment (VM blueprints with runtimes, tools)
+    ├── Add knowledge notes (standards, conventions, domain glossary)
+    ├── Provision secrets (API keys, service account credentials)
+    └── Set up MCP servers (Jira, Datadog, Confluence, etc.)
         ↓
 First Sessions
     ├── Devin learns the codebase through context retrieval
diff --git a/shared/general-themes/design-patterns-for-devin.md b/shared/general-themes/design-patterns-for-devin.md
index 2799015..e3832e5 100644
--- a/shared/general-themes/design-patterns-for-devin.md
+++ b/shared/general-themes/design-patterns-for-devin.md
@@ -6,14 +6,14 @@ Proven patterns for structuring work, codebases, and processes so that Devin del
 
 **Principle:** If a human developer can clone the repo and run `make test` (or equivalent) with no external dependencies, Devin can too.
 
-**Why it matters:** Devin verifies its own changes by running your build and test suite. If the build requires a VPN, a licensed IDE, a proprietary database, or manual setup steps, Devin cannot complete the feedback loop.
+**Why it matters:** Devin verifies its own changes by running your build and test suite on its VM. If the build requires a VPN, a licensed IDE, a proprietary database, or manual setup steps that cannot be automated, Devin cannot complete the feedback loop. The more self-contained your build is, the tighter Devin's verify-and-iterate cycle becomes.
 
 **How to apply:**
 - Containerize dependencies (Docker Compose for databases, message brokers, caches)
 - Use in-memory or file-based databases for tests (SQLite, H2, Testcontainers)
 - Provide seed data scripts that create a working test environment from scratch
 - Document the build/test command in the README (`npm test`, `./gradlew check`, `dotnet test`)
-- Use environment variables for configuration — Devin can inject these via secrets management
+- Use environment variables for configuration — Devin injects these via the platform's secrets management layer (configured once at the org level, available to every session)
 
 ## Pattern 2: Event-Driven Triggers
 
@@ -112,13 +112,14 @@ The `[SAST Tool]` slot can be filled by:
 
 ## Pattern 6: Context Layer Configuration
 
-**Principle:** Invest in configuring Devin's persistent context layer once to benefit every future session.
+**Principle:** Invest in configuring Devin's shared context layer once to benefit every future session.
 
 **Components:**
-- **Knowledge notes** — Coding standards, architecture decisions, team conventions, domain glossary. Devin retrieves these automatically when relevant
-- **Environment configuration** — Pre-installed tools, language runtimes, environment variables, startup scripts. Sessions start ready to build
-- **Playbooks** — Step-by-step procedures for recurring tasks (deploy, migrate, audit). Devin follows playbooks precisely
-- **MCP servers** — External tool connections (Jira, Datadog, Confluence) that persist across sessions. Configure once, use everywhere
+- **Environment configurations (VM blueprints)** — Pre-built machine images with dependencies, language runtimes, tools, and startup scripts baked in. Sessions boot ready to build, not waiting for installation
+- **Knowledge notes** — Coding standards, architecture decisions, team conventions, domain glossary. Devin retrieves these automatically when relevant to the task
+- **Playbooks** — Step-by-step procedures for recurring tasks (deploy, migrate, audit). Devin follows playbooks precisely, ensuring consistent execution across team members
+- **MCP servers** — External tool connections (Jira, Datadog, Confluence, Azure DevOps) that persist across sessions. Configure once, use everywhere
+- **Secrets** — Scoped credentials (API keys, service account tokens, database passwords) injected at session start. No credentials in prompts or code
 - **Git connections** — Repository access that applies to all sessions in the organization
 
-**ROI:** The upfront investment in context configuration pays dividends across every subsequent session. A well-configured Devin organization starts every task with the right tools, knowledge, and access — no per-session setup friction.
+**ROI:** The upfront investment in context configuration pays dividends across every subsequent session. A well-configured Devin organization starts every task with the right tools, knowledge, credentials, and access — no per-session setup friction. This is the mechanism behind the [clean-room + shared context](architecture-strengths.md#shared-context-layer) design: runtime isolation for security, persistent configuration for productivity.
diff --git a/shared/general-themes/platform-capabilities.md b/shared/general-themes/platform-capabilities.md
index 9976918..ac8b699 100644
--- a/shared/general-themes/platform-capabilities.md
+++ b/shared/general-themes/platform-capabilities.md
@@ -48,10 +48,16 @@ Devin can create child sessions to parallelize work. A parent agent breaks a lar
 
 Devin is not a per-user tool. It operates as a shared team resource with organizational context.
 
-**Shared configuration:**
-- **Context layer** — Knowledge notes, environment setup, and MCP connections apply to all sessions in the organization. Configure once, benefit everywhere
+**Shared configuration (the context layer):**
+- **Environment configurations (VM blueprints)** — Pre-built machine images with dependencies, runtimes, and tools baked in. Sessions boot ready to build
+- **Knowledge notes** — Persistent, human-curated context (coding standards, architecture decisions, conventions) retrieved automatically based on the task
+- **Playbooks** — Repeatable procedures encoding institutional methodology, shared across the org
+- **MCP servers** — Pre-configured integrations (Jira, Datadog, Confluence, Azure DevOps) available to every session without per-session setup
+- **Secrets** — Scoped credentials injected into the environment at session start via the platform's secrets management layer
+- **Git connections** — Repository access configured at the org level. All sessions can clone and push to connected repos
 - **Automations** — Webhooks, scheduled sessions, and trigger rules are organization-wide. Every team member's events route through the same automation layer
-- **Git connections** — Repository access is configured at the org level. All sessions can clone and push to connected repos
+
+This shared context layer means that configuring Devin is a one-time investment: one engineer sets up the environment, knowledge, and integrations, and every subsequent session — from any team member — inherits that configuration automatically.
 
 **Multi-user collaboration:**
 - Multiple team members can comment on the same Devin-created PR
@@ -83,4 +89,4 @@ Devin sessions have a deliberate lifecycle optimized for efficiency:
 3. **Hibernated** — After a period of inactivity, Devin hibernates its VM. The session state is preserved but compute resources are released
 4. **Resumed** — When new feedback arrives (PR comment, CI result, user message), Devin resumes from the hibernated state with full context. No work is lost
 
-This lifecycle means Devin does not waste compute while waiting for human review. It acts immediately when feedback arrives and sleeps efficiently in between.
+This lifecycle means Devin does not waste compute while waiting for human review. It acts immediately when feedback arrives and sleeps efficiently in between. Long-running tasks — multi-day code reviews, back-and-forth iterations, waiting on a blocked dependency — are natural. The session persists across the entire lifecycle of a task.
diff --git a/shared/general-themes/value-narratives.md b/shared/general-themes/value-narratives.md
index 3654d5f..59ac1ce 100644
--- a/shared/general-themes/value-narratives.md
+++ b/shared/general-themes/value-narratives.md
@@ -70,7 +70,7 @@ Devin's cost model is consumption-based (ACU — Agent Compute Units):
 - **Pay for active work** — Devin hibernates during idle time. You pay for compute only when Devin is executing
 - **Predictable budgeting** — ACU budgets can be set at the organization, team, or user level with hard enforcement
 - **ROI measurement** — Each session produces measurable output (PRs merged, findings remediated, tests added). ROI is directly attributable
-- **Licensing cost avoidance** — Migration from expensive proprietary tools/languages (COBOL, SAS, Oracle Forms, Informatica) to open-source alternatives reduces ongoing license costs. Devin accelerates the migration that unlocks those savings
+- **Licensing cost avoidance** — Migration from expensive proprietary platforms (COBOL/mainframe, SAS, Oracle Forms, Informatica) to open-source or cloud-native alternatives eliminates ongoing per-seat, per-CPU, or per-transaction licensing. The business case for migration is often already approved — the blocker is engineering capacity to execute. Devin removes that blocker
 
 **Narrative:** "The ACU cost for this migration campaign is a fraction of the engineering salary cost, and it delivers the licensing savings months earlier than a manual approach."
 
diff --git a/shared/general-themes/when-to-use-devin.md b/shared/general-themes/when-to-use-devin.md
index e263825..ca9dcdf 100644
--- a/shared/general-themes/when-to-use-devin.md
+++ b/shared/general-themes/when-to-use-devin.md
@@ -24,9 +24,9 @@ Devin divides and conquers work that would take a team of engineers weeks. A par
 
 | Campaign | Example | Why Devin? |
 |----------|---------|-----------|
-| **Codebase modernization** | Translate COBOL → Java across 200 copybooks | Each child agent handles one copybook. Humans review the PRs. Volume that would take months becomes weeks |
+| **Codebase modernization** | Translate COBOL → Java across 200 copybooks | Each child agent handles one copybook. Humans review the PRs. Volume that would take months becomes weeks. Reduces ongoing mainframe licensing costs |
 | **Framework migration** | Upgrade Spring Boot 2.x → 3.x across 50 microservices | Each service gets its own agent. Jakarta namespace migration, dependency bumps, and test verification — all parallelized |
-| **Language translation** | Migrate SAS → Python/Snowflake for 300 ETL jobs | Devin translates each job, generates equivalence tests, and validates output parity |
+| **Language/framework translation** | Migrate SAS → Python/Snowflake for 300 ETL jobs, or Oracle Forms → modern web frameworks | Devin translates each job, generates equivalence tests, and validates output parity. Eliminates expensive per-seat or per-CPU licensing |
 | **Dependency hygiene** | Bump all transitive dependencies across an org's repos | Scheduled weekly. Devin opens PRs, CI validates, humans merge |
 | **Security backlog** | Remediate 500 open Snyk findings across 80 repos | Each finding gets its own agent session. Devin reads the advisory, applies the fix, runs tests |
 | **Test coverage** | Generate unit tests for 200 uncovered modules | Devin analyzes each module, writes tests following existing conventions, achieves target coverage |
@@ -45,13 +45,14 @@ Work that engineers know should be done but deprioritize because higher-value ta
 
 ## The Sweet Spot
 
-Give Devin work that is:
+Give Devin work that you would otherwise not have done — because of constrained engineering capacity, prohibitive volume, insufficient priority, or because engineers had higher-value tasks to focus on:
 
 1. **Well-defined** — clear acceptance criteria, verifiable outcomes (tests pass, scan is clean, PR is merged)
 2. **Repetitive at scale** — the same pattern applied to many targets (repos, modules, findings)
 3. **Lower priority but valuable** — work humans would do if they had unlimited time
 4. **Automatable end-to-end** — Devin can fetch context, implement, test, and submit for review without manual intervention
 5. **Safe to iterate** — Devin works on branches, never pushes to main, and humans always approve the merge
+6. **Cost-motivated** — migrations away from expensive proprietary platforms (COBOL, SAS, Informatica, Oracle Forms) where the engineering effort to migrate has been the blocker, not the business case
 
 ## What Devin Needs to Succeed
 

From 9ee02953e1960c446f8c33bbcc006b799bd23b70 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 13 May 2026 21:55:38 +0000
Subject: [PATCH 3/3] address PR review feedback: reframe isolation, service
 accounts, urgency, off-machine runners

- architecture-strengths: reframe clean-room as worker isolation in controlled environment, not 'missing access'
- architecture-strengths: security by default now references existing access control and governance mechanisms
- architecture-strengths: playbooks bullet adds scaling workers narrative
- architecture-strengths: secrets bullet clarifies service account identity vs user identity
- collaboration-model: clarify Devin retains conversation context (no re-reading)
- when-to-use-devin: language translation row uses 'pathway away from burdensome licensing'
- when-to-use-devin: rename 'Cost-motivated' to 'Urgency-oriented' with broader drivers
- design-patterns: add off-machine runners as alternative verification path
- platform-capabilities: frame team-based operation as coworker agent vs individual AI assistant
---
 shared/general-themes/architecture-strengths.md    | 8 ++++----
 shared/general-themes/collaboration-model.md       | 2 +-
 shared/general-themes/design-patterns-for-devin.md | 2 +-
 shared/general-themes/platform-capabilities.md     | 2 +-
 shared/general-themes/when-to-use-devin.md         | 4 ++--
 5 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/shared/general-themes/architecture-strengths.md b/shared/general-themes/architecture-strengths.md
index da8a479..ef1755a 100644
--- a/shared/general-themes/architecture-strengths.md
+++ b/shared/general-themes/architecture-strengths.md
@@ -2,9 +2,9 @@
 
 ## Clean-Room Execution
 
-Each Devin session runs on its own isolated VM. By default, a session has access to nothing — no ambient credentials, no inherited permissions. This isolation is a security feature, not a limitation.
+Each Devin session runs on its own isolated VM — a controlled environment where workers are separated from each other and from systems they have not been granted access to. This isolation model preserves your existing security posture while adding autonomous engineering capacity.
 
-- **Security by default** — Devin cannot access resources you have not explicitly granted. No lateral movement risk between sessions or systems
+- **Security by default** — Devin operates within your existing access control and governance mechanisms. No lateral movement risk between sessions or systems — each worker is scoped to exactly the resources you provision
 - **Service account friendly** — Organizations provision scoped credentials (API keys, PATs, cloud IAM roles) that Devin uses to access exactly the systems it needs. This mirrors how you would onboard any new team member — with least-privilege access
 - **Ephemeral testing environments** — Devin can deploy into throwaway environments (containers, cloud sandboxes) for integration testing, then tear them down. No persistent state leaks between sessions
 - **Reproducible from scratch** — Every session starts from the same base. No "works on my machine" drift. Environment configuration is codified and versioned
@@ -15,9 +15,9 @@ While each session's runtime is isolated, Devin does not start from scratch. A s
 
 - **Environment configurations (VM blueprints)** — Pre-built machine images with dependencies, language runtimes, tools, and startup scripts baked in. Sessions boot ready to build, not waiting for `npm install`
 - **Knowledge notes** — Persistent, human-curated context (coding standards, architecture decisions, team conventions, domain glossary) that Devin retrieves automatically based on the task at hand
-- **Playbooks** — Repeatable procedures that encode institutional methodology. Every session that invokes a playbook follows the same proven steps
+- **Playbooks** — Repeatable procedures that encode institutional methodology. Every session that invokes a playbook follows the same proven steps — this is what enables you to scale how many workers you kick off, because each one executes the same validated process
 - **MCP servers** — Pre-configured integrations (Jira, Datadog, Confluence, Azure DevOps) available to every session in the org without per-session setup
-- **Secrets** — Scoped credentials injected into the environment at session start. No credentials embedded in prompts or code — they flow through the platform's secrets management layer
+- **Secrets** — Scoped credentials tied to a service account identity, not individual user permissions. This separates who the agent is and what it can access from any specific user's identity — credentials flow through the platform's secrets management layer, never embedded in prompts or code
 - **Git connections** — Repository access configured at the org level. All sessions can clone and push to connected repos immediately
 
 This design gives you both: **clean-room isolation for security** and a **shared context layer for productivity**. Each worker VM is sandboxed, but the organization's accumulated knowledge and configuration flow into every session automatically.
diff --git a/shared/general-themes/collaboration-model.md b/shared/general-themes/collaboration-model.md
index 0a332da..593bbc6 100644
--- a/shared/general-themes/collaboration-model.md
+++ b/shared/general-themes/collaboration-model.md
@@ -37,7 +37,7 @@ Multiple team members can interact with the same Devin session through PR commen
 - Devin reads both comments, addresses both requests in subsequent commits
 - Both reviewers see Devin's response and can continue the conversation
 
-This works because Devin monitors its PRs for new comments. When any comment arrives, Devin resumes from its hibernated state, reads the full conversation context, and responds. The session persists across the entire lifecycle of the task — there is no context loss between interactions.
+This works because Devin monitors its PRs for new comments. When any comment arrives, Devin resumes from its hibernated state and responds with its full conversation context retained — no re-reading from scratch. The session persists across the entire lifecycle of the task with no context loss between interactions.
 
 ## CI Check Monitoring
 
diff --git a/shared/general-themes/design-patterns-for-devin.md b/shared/general-themes/design-patterns-for-devin.md
index e3832e5..e93255c 100644
--- a/shared/general-themes/design-patterns-for-devin.md
+++ b/shared/general-themes/design-patterns-for-devin.md
@@ -6,7 +6,7 @@ Proven patterns for structuring work, codebases, and processes so that Devin del
 
 **Principle:** If a human developer can clone the repo and run `make test` (or equivalent) with no external dependencies, Devin can too.
 
-**Why it matters:** Devin verifies its own changes by running your build and test suite on its VM. If the build requires a VPN, a licensed IDE, a proprietary database, or manual setup steps that cannot be automated, Devin cannot complete the feedback loop. The more self-contained your build is, the tighter Devin's verify-and-iterate cycle becomes.
+**Why it matters:** Devin verifies its own changes by running your build and test suite on its VM. The more self-contained your build is, the tighter Devin's verify-and-iterate cycle becomes. Even when local execution is not fully possible, Devin can delegate verification to off-machine runners — CI pipelines, external test systems, or cloud-hosted build environments — that still close the feedback loop.
 
 **How to apply:**
 - Containerize dependencies (Docker Compose for databases, message brokers, caches)
diff --git a/shared/general-themes/platform-capabilities.md b/shared/general-themes/platform-capabilities.md
index ac8b699..d333504 100644
--- a/shared/general-themes/platform-capabilities.md
+++ b/shared/general-themes/platform-capabilities.md
@@ -46,7 +46,7 @@ Devin can create child sessions to parallelize work. A parent agent breaks a lar
 
 ## Team-Based Operation
 
-Devin is not a per-user tool. It operates as a shared team resource with organizational context.
+Devin is not an individual user's AI assistant — it is a team-based coworker agent that operates as a shared resource with organizational context. This distinction matters: configuration, knowledge, and integrations belong to the team, not to any single user's session.
 
 **Shared configuration (the context layer):**
 - **Environment configurations (VM blueprints)** — Pre-built machine images with dependencies, runtimes, and tools baked in. Sessions boot ready to build
diff --git a/shared/general-themes/when-to-use-devin.md b/shared/general-themes/when-to-use-devin.md
index ca9dcdf..3fddc4e 100644
--- a/shared/general-themes/when-to-use-devin.md
+++ b/shared/general-themes/when-to-use-devin.md
@@ -26,7 +26,7 @@ Devin divides and conquers work that would take a team of engineers weeks. A par
 |----------|---------|-----------|
 | **Codebase modernization** | Translate COBOL → Java across 200 copybooks | Each child agent handles one copybook. Humans review the PRs. Volume that would take months becomes weeks. Reduces ongoing mainframe licensing costs |
 | **Framework migration** | Upgrade Spring Boot 2.x → 3.x across 50 microservices | Each service gets its own agent. Jakarta namespace migration, dependency bumps, and test verification — all parallelized |
-| **Language/framework translation** | Migrate SAS → Python/Snowflake for 300 ETL jobs, or Oracle Forms → modern web frameworks | Devin translates each job, generates equivalence tests, and validates output parity. Eliminates expensive per-seat or per-CPU licensing |
+| **Language/framework translation** | Migrate SAS → Python/Snowflake for 300 ETL jobs, or Oracle Forms → modern web frameworks | Devin translates each job, generates equivalence tests, and validates output parity. Offers a pathway away from products with burdensome licensing models |
 | **Dependency hygiene** | Bump all transitive dependencies across an org's repos | Scheduled weekly. Devin opens PRs, CI validates, humans merge |
 | **Security backlog** | Remediate 500 open Snyk findings across 80 repos | Each finding gets its own agent session. Devin reads the advisory, applies the fix, runs tests |
 | **Test coverage** | Generate unit tests for 200 uncovered modules | Devin analyzes each module, writes tests following existing conventions, achieves target coverage |
@@ -52,7 +52,7 @@ Give Devin work that you would otherwise not have done — because of constraine
 3. **Lower priority but valuable** — work humans would do if they had unlimited time
 4. **Automatable end-to-end** — Devin can fetch context, implement, test, and submit for review without manual intervention
 5. **Safe to iterate** — Devin works on branches, never pushes to main, and humans always approve the merge
-6. **Cost-motivated** — migrations away from expensive proprietary platforms (COBOL, SAS, Informatica, Oracle Forms) where the engineering effort to migrate has been the blocker, not the business case
+6. **Urgency-oriented** — work driven by deadlines: license sunset timelines, compliance mandates, platform end-of-life, or cost pressure from burdensome licensing models (COBOL, SAS, Informatica, Oracle Forms). The business case is already approved — you need the extra engineering capacity to execute
 
 ## What Devin Needs to Succeed