From 3d9f2221857e4df4d561c04d707f2a45d76ee85a Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Tue, 3 Jun 2025 18:25:45 +0000 Subject: [PATCH 1/4] Add comprehensive scope keys documentation - Created detailed explanation of how scope keys work across platforms - Added examples for Slack, Linear, GitHub, and API interactions - Explained why scope keys matter for context inheritance - Included best practices and troubleshooting guide - Updated docs navigation to include new architecture section --- docs/architecture/scope-keys.mdx | 156 ++++++++++++++++++++++++++ docs/docs.json | 184 +++++++++++++++++-------------- 2 files changed, 259 insertions(+), 81 deletions(-) create mode 100644 docs/architecture/scope-keys.mdx diff --git a/docs/architecture/scope-keys.mdx b/docs/architecture/scope-keys.mdx new file mode 100644 index 000000000..516bd853b --- /dev/null +++ b/docs/architecture/scope-keys.mdx @@ -0,0 +1,156 @@ +--- +title: "Scope Keys: How Context Inheritance Works" +description: "Understanding how Codegen groups related interactions and inherits context across conversations" +--- + +# Scope Keys: How Context Inheritance Works + +Scope keys are Codegen's way of grouping related agent runs together so that context can be inherited between interactions. Think of them as conversation threads that help Codegen understand when different requests are part of the same ongoing work. + +## What Are Scope Keys? + +A scope key is a unique identifier that groups related agent interactions. When you interact with Codegen multiple times in the same "scope," each new interaction can build on the context and work from previous interactions in that scope. + +This enables powerful workflows like: +- Continuing conversations in the same Slack thread +- Building on previous work in the same Linear ticket +- Adding commits to existing PRs instead of creating new ones +- Maintaining context across multiple requests + +## How Scope Keys Work by Platform + +### Slack Threads +**Scope Key Format:** `slack-{thread_timestamp}` + +When you mention Codegen in a Slack thread, all messages in that thread share the same scope key. This means: +- Codegen remembers the entire conversation history +- Follow-up requests build on previous work +- Context from earlier messages is automatically inherited + +``` +Thread: "Can you fix the login bug?" +├── Codegen creates PR #123 +└── "Please also add input validation" + └── Codegen adds commits to PR #123 (same scope!) +``` + +### Linear Issues +**Scope Key Format:** `linear-{issue_id}` + +All work on the same Linear issue shares a scope key. This enables: +- Building on previous implementations +- Maintaining context across multiple comments +- Continuing work where you left off + +``` +Linear Issue CG-456: "Improve test coverage" +├── Comment: "Add tests for auth module" +│ └── Codegen creates PR #789 +└── Comment: "Also need integration tests" + └── Codegen adds to PR #789 (same scope!) +``` + +### GitHub PRs +**Scope Key Format:** `github-pr-{pr_number}-{repo_id}` + +Work on the same PR is grouped together, allowing: +- Adding commits to existing PRs +- Responding to review feedback +- Iterating on the same feature branch + +``` +PR #123: "Add user authentication" +├── Initial PR created +├── Review comment: "Fix the validation logic" +│ └── Codegen adds fixing commit +└── Review comment: "Add error handling" + └── Codegen adds another commit (same PR!) +``` + +### API Calls +**Scope Key Format:** `api-{run_id}` or derived from task timeline + +API interactions can inherit scope from: +- The task timeline if provided +- Previous API calls in the same session +- Falls back to unique run ID if no context + +## Why This Matters + +### ✅ With Scope Keys (Good) +``` +Slack Thread: +You: "Create a PR to fix the login bug" +Codegen: Creates PR #123 + +You: "Please also add input validation" +Codegen: Adds commits to PR #123 ← Same PR! + +You: "The tests are failing" +Codegen: Fixes tests in PR #123 ← Still same PR! +``` + +### ❌ Without Scope Keys (Bad) +``` +You: "Create a PR to fix the login bug" +Codegen: Creates PR #123 + +You: "Please also add input validation" +Codegen: Creates PR #124 ← New PR! 😞 + +You: "The tests are failing" +Codegen: Creates PR #125 ← Another new PR! 😞 +``` + +## Best Practices + +### Do This ✅ +- **Continue conversations in the same thread/ticket** - This ensures context is inherited +- **Ask for changes in the same scope** - Codegen will update existing work +- **Reference previous work** - Codegen can build on what it already knows + +### Avoid This ❌ +- **Starting new threads for related work** - Context gets lost +- **Creating new tickets for follow-ups** - Breaks the scope chain +- **Asking for "new PRs" unnecessarily** - Usually you want to update existing work + +## Technical Implementation + +Scope keys are implemented in the agent runner system: + +```python +# Each platform implements scope key generation +class SlackRunner: + def agent_run_scope_key(self) -> str: + return f"slack-{self.slack_thread_ts}" + +class LinearRunner: + def agent_run_scope_key(self) -> str: + return f"linear-{self.linear_issue_id}" + +class GithubRunner: + def agent_run_scope_key(self) -> str: + return f"github-pr-{self.pr_number}-{self.repo_id}" +``` + +When a new agent run starts, the system: +1. Generates the appropriate scope key +2. Looks up previous runs with the same scope key +3. Inherits context from those previous runs +4. Continues the work in the same "conversation" + +## Troubleshooting + +**Problem:** Codegen keeps creating new PRs instead of updating existing ones +**Solution:** Make sure you're asking for changes in the same Slack thread, Linear issue, or PR where the original work was done. + +**Problem:** Codegen doesn't remember previous context +**Solution:** Check that you're interacting in the same scope (same thread/ticket/PR) as the previous interaction. + +**Problem:** Context seems to be inherited from unrelated work +**Solution:** This might indicate a scope key collision - check that you're working in the right thread/ticket/PR. + +--- + +Understanding scope keys helps you work more effectively with Codegen by ensuring your requests build on each other rather than starting from scratch each time. + diff --git a/docs/docs.json b/docs/docs.json index bcb781e65..4f6cbd638 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -8,88 +8,110 @@ "dark": "#a277ff" }, "favicon": "/favicon.svg", - "navigation": { - "tabs": [ - { - "tab": "Documentation", - "groups": [ - { - "group": "Overview", - "pages": [ - "introduction/overview", - "introduction/api", - "introduction/prompting", - "introduction/community", - "introduction/about", - "introduction/faq" - ] - }, - { - "group": "Capabilities", - "pages": ["capabilities/capabilities", "capabilities/wake-up"] - }, - { - "group": "Integrations", - "pages": [ - "integrations/github", - "integrations/slack", - "integrations/linear", - "integrations/notion", - "integrations/figma", - "integrations/circleci", - "integrations/web-search", - "integrations/postgres" - ] - }, - { - "group": "Sandboxes", - "pages": [ - "sandboxes/overview", - "sandboxes/setup-commands", - "sandboxes/environment-variables", - "sandboxes/secrets", - "sandboxes/editor", - "sandboxes/web-preview" - ] - }, - { - "group": "Settings", - "pages": ["settings/repo-rules", "settings/model-configuration"] - } - ] - }, - { - "tab": "API Reference", - "groups": [ - { - "group": "Endpoints", - "openapi": { - "source": "/api-reference/openapi3.json", - "directory": "api-reference" - } - } - ] - }, - { - "tab": "Blog", - "groups": [ - { - "group": "Blog", - "pages": ["blog/posts", "blog/devin", "blog/act-via-code"] - } - ] - }, - { - "tab": "Changelog", - "groups": [ - { - "group": "Changelog", - "pages": ["changelog/changelog"] + "navigation": [ + { + "group": "Get Started", + "pages": [ + "introduction", + "quickstart", + "development" + ] + }, + { + "group": "Essentials", + "pages": [ + "essentials/markdown", + "essentials/code", + "essentials/images", + "essentials/settings", + "essentials/navigation" + ] + }, + { + "group": "Architecture", + "pages": [ + "architecture/scope-keys" + ] + }, + { + "tab": "Documentation", + "groups": [ + { + "group": "Overview", + "pages": [ + "introduction/overview", + "introduction/api", + "introduction/prompting", + "introduction/community", + "introduction/about", + "introduction/faq" + ] + }, + { + "group": "Capabilities", + "pages": ["capabilities/capabilities", "capabilities/wake-up"] + }, + { + "group": "Integrations", + "pages": [ + "integrations/github", + "integrations/slack", + "integrations/linear", + "integrations/notion", + "integrations/figma", + "integrations/circleci", + "integrations/web-search", + "integrations/postgres" + ] + }, + { + "group": "Sandboxes", + "pages": [ + "sandboxes/overview", + "sandboxes/setup-commands", + "sandboxes/environment-variables", + "sandboxes/secrets", + "sandboxes/editor", + "sandboxes/web-preview" + ] + }, + { + "group": "Settings", + "pages": ["settings/repo-rules", "settings/model-configuration"] + } + ] + }, + { + "tab": "API Reference", + "groups": [ + { + "group": "Endpoints", + "openapi": { + "source": "/api-reference/openapi3.json", + "directory": "api-reference" } - ] - } - ] - }, + } + ] + }, + { + "tab": "Blog", + "groups": [ + { + "group": "Blog", + "pages": ["blog/posts", "blog/devin", "blog/act-via-code"] + } + ] + }, + { + "tab": "Changelog", + "groups": [ + { + "group": "Changelog", + "pages": ["changelog/changelog"] + } + ] + } + ], "logo": { "light": "https://cdn.prod.website-files.com/67070304751b9b01bf6a161c/679bcf45bf55446746125835_Codegen_Logomark_Light.svg", "dark": "https://cdn.prod.website-files.com/67070304751b9b01bf6a161c/679bcf45a3e32761c42b324b_Codegen_Logomark_Dark.svg" From 603f783b9b8dfc7bfaef92b437e0cd40e4acfd90 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Tue, 3 Jun 2025 18:26:51 +0000 Subject: [PATCH 2/4] Automated pre-commit update --- docs/docs.json | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 4f6cbd638..e4efbfc06 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -11,11 +11,7 @@ "navigation": [ { "group": "Get Started", - "pages": [ - "introduction", - "quickstart", - "development" - ] + "pages": ["introduction", "quickstart", "development"] }, { "group": "Essentials", @@ -29,9 +25,7 @@ }, { "group": "Architecture", - "pages": [ - "architecture/scope-keys" - ] + "pages": ["architecture/scope-keys"] }, { "tab": "Documentation", From fd8b9b1eb6477d7fe14f56412f50e2db3364d373 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Tue, 3 Jun 2025 18:32:51 +0000 Subject: [PATCH 3/4] Rewrite docs to be customer-friendly without technical jargon - Renamed from 'scope-keys' to 'context-inheritance' - Removed technical terms like 'scope key' throughout - Focused on when users should expect context vs fresh starts - Added clear examples of good vs bad interaction patterns - Emphasized practical scenarios and troubleshooting --- docs/architecture/context-inheritance.mdx | 139 +++++++++++++++++++ docs/architecture/scope-keys.mdx | 156 ---------------------- docs/docs.json | 4 +- 3 files changed, 142 insertions(+), 157 deletions(-) create mode 100644 docs/architecture/context-inheritance.mdx delete mode 100644 docs/architecture/scope-keys.mdx diff --git a/docs/architecture/context-inheritance.mdx b/docs/architecture/context-inheritance.mdx new file mode 100644 index 000000000..ae9fee4ab --- /dev/null +++ b/docs/architecture/context-inheritance.mdx @@ -0,0 +1,139 @@ +--- +title: "Context Inheritance: When Codegen Remembers Previous Work" +description: "Understanding when Codegen builds on previous conversations and when it starts fresh" +--- + +# Context Inheritance: When Codegen Remembers Previous Work + +Codegen is designed to build on previous work and maintain context across related interactions. Understanding when this happens helps you work more effectively and avoid frustrating experiences like getting multiple PRs when you wanted updates to an existing one. + +## When Codegen Remembers Context + +Codegen automatically inherits context and builds on previous work when you interact within the same "conversation scope." Here's when this happens: + +### Slack Threads +**Codegen remembers everything in the same thread** + +When you mention Codegen in a Slack thread, it can see and build on all previous messages in that thread. This means: +- Follow-up requests build on previous work +- Codegen remembers the entire conversation history +- Context from earlier messages is automatically available + +``` +Thread: "Can you fix the login bug?" +├── Codegen creates PR #123 +└── "Please also add input validation" + └── Codegen adds commits to PR #123 (same PR!) +``` + +### Linear Issues +**Codegen remembers all work on the same ticket** + +All interactions on the same Linear issue share context. This enables: +- Building on previous implementations +- Maintaining context across multiple comments +- Continuing work where you left off + +``` +Linear Issue CG-456: "Improve test coverage" +├── Comment: "Add tests for auth module" +│ └── Codegen creates PR #789 +└── Comment: "Also need integration tests" + └── Codegen adds to PR #789 (same PR!) +``` + +### GitHub PRs +**Codegen remembers all work on the same pull request** + +When you comment on a PR that Codegen created, it will: +- Add commits to the existing PR +- Respond to review feedback +- Continue iterating on the same feature branch + +``` +PR #123: "Add user authentication" +├── Initial PR created +├── Review comment: "Fix the validation logic" +│ └── Codegen adds fixing commit +└── Review comment: "Add error handling" + └── Codegen adds another commit (same PR!) +``` + +## When Codegen Starts Fresh + +Codegen will start a new conversation (and potentially create new PRs) when: + +- **New Slack threads** - Starting a new thread breaks the context +- **New Linear tickets** - Different tickets are treated as separate work +- **Different repositories** - Work in different repos doesn't share context +- **API calls without context** - Direct API calls start fresh unless context is provided + +## Why This Matters + +### ✅ Working With Context (Good Experience) +``` +Slack Thread: +You: "Create a PR to fix the login bug" +Codegen: Creates PR #123 + +You: "Please also add input validation" +Codegen: Adds commits to PR #123 ← Same PR! + +You: "The tests are failing" +Codegen: Fixes tests in PR #123 ← Still same PR! +``` + +### ❌ Breaking Context (Frustrating Experience) +``` +You: "Create a PR to fix the login bug" +Codegen: Creates PR #123 + +[You start a new Slack thread] +You: "Please also add input validation" +Codegen: Creates PR #124 ← New PR! 😞 + +[You create a new Linear ticket] +You: "The tests are failing" +Codegen: Creates PR #125 ← Another new PR! 😞 +``` + +## Best Practices + +### Do This ✅ +- **Continue conversations in the same thread/ticket** - This ensures context is inherited +- **Ask for changes in the same place** - Codegen will update existing work +- **Reference previous work** - Codegen can build on what it already knows +- **Use reply threads in Slack** - Keep related work together + +### Avoid This ❌ +- **Starting new threads for related work** - Context gets lost +- **Creating new tickets for follow-ups** - Breaks the context chain +- **Asking for "new PRs" unnecessarily** - Usually you want to update existing work +- **Switching between different communication channels** - Each channel has separate context + +## Common Scenarios + +**Scenario**: "I asked Codegen to create a PR, but now I want to add more features to it" +**Solution**: Ask for the changes in the same Slack thread or Linear ticket where you made the original request. + +**Scenario**: "Codegen created multiple PRs for what should be one feature" +**Solution**: Make sure all related requests happen in the same conversation thread. + +**Scenario**: "I want Codegen to start completely fresh on a similar but different task" +**Solution**: Start a new Slack thread or create a new Linear ticket to break context inheritance. + +## Troubleshooting + +**Problem**: Codegen keeps creating new PRs instead of updating existing ones +**Solution**: Make sure you're asking for changes in the same Slack thread or Linear issue where the original work was done. + +**Problem**: Codegen doesn't remember previous context +**Solution**: Check that you're interacting in the same conversation thread as the previous interaction. + +**Problem**: Codegen is building on unrelated previous work +**Solution**: You might be in a thread with previous unrelated work - consider starting a new thread for your task. + +--- + +Understanding when Codegen inherits context helps you work more effectively by ensuring your requests build on each other rather than starting from scratch each time. + diff --git a/docs/architecture/scope-keys.mdx b/docs/architecture/scope-keys.mdx deleted file mode 100644 index 516bd853b..000000000 --- a/docs/architecture/scope-keys.mdx +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Scope Keys: How Context Inheritance Works" -description: "Understanding how Codegen groups related interactions and inherits context across conversations" ---- - -# Scope Keys: How Context Inheritance Works - -Scope keys are Codegen's way of grouping related agent runs together so that context can be inherited between interactions. Think of them as conversation threads that help Codegen understand when different requests are part of the same ongoing work. - -## What Are Scope Keys? - -A scope key is a unique identifier that groups related agent interactions. When you interact with Codegen multiple times in the same "scope," each new interaction can build on the context and work from previous interactions in that scope. - -This enables powerful workflows like: -- Continuing conversations in the same Slack thread -- Building on previous work in the same Linear ticket -- Adding commits to existing PRs instead of creating new ones -- Maintaining context across multiple requests - -## How Scope Keys Work by Platform - -### Slack Threads -**Scope Key Format:** `slack-{thread_timestamp}` - -When you mention Codegen in a Slack thread, all messages in that thread share the same scope key. This means: -- Codegen remembers the entire conversation history -- Follow-up requests build on previous work -- Context from earlier messages is automatically inherited - -``` -Thread: "Can you fix the login bug?" -├── Codegen creates PR #123 -└── "Please also add input validation" - └── Codegen adds commits to PR #123 (same scope!) -``` - -### Linear Issues -**Scope Key Format:** `linear-{issue_id}` - -All work on the same Linear issue shares a scope key. This enables: -- Building on previous implementations -- Maintaining context across multiple comments -- Continuing work where you left off - -``` -Linear Issue CG-456: "Improve test coverage" -├── Comment: "Add tests for auth module" -│ └── Codegen creates PR #789 -└── Comment: "Also need integration tests" - └── Codegen adds to PR #789 (same scope!) -``` - -### GitHub PRs -**Scope Key Format:** `github-pr-{pr_number}-{repo_id}` - -Work on the same PR is grouped together, allowing: -- Adding commits to existing PRs -- Responding to review feedback -- Iterating on the same feature branch - -``` -PR #123: "Add user authentication" -├── Initial PR created -├── Review comment: "Fix the validation logic" -│ └── Codegen adds fixing commit -└── Review comment: "Add error handling" - └── Codegen adds another commit (same PR!) -``` - -### API Calls -**Scope Key Format:** `api-{run_id}` or derived from task timeline - -API interactions can inherit scope from: -- The task timeline if provided -- Previous API calls in the same session -- Falls back to unique run ID if no context - -## Why This Matters - -### ✅ With Scope Keys (Good) -``` -Slack Thread: -You: "Create a PR to fix the login bug" -Codegen: Creates PR #123 - -You: "Please also add input validation" -Codegen: Adds commits to PR #123 ← Same PR! - -You: "The tests are failing" -Codegen: Fixes tests in PR #123 ← Still same PR! -``` - -### ❌ Without Scope Keys (Bad) -``` -You: "Create a PR to fix the login bug" -Codegen: Creates PR #123 - -You: "Please also add input validation" -Codegen: Creates PR #124 ← New PR! 😞 - -You: "The tests are failing" -Codegen: Creates PR #125 ← Another new PR! 😞 -``` - -## Best Practices - -### Do This ✅ -- **Continue conversations in the same thread/ticket** - This ensures context is inherited -- **Ask for changes in the same scope** - Codegen will update existing work -- **Reference previous work** - Codegen can build on what it already knows - -### Avoid This ❌ -- **Starting new threads for related work** - Context gets lost -- **Creating new tickets for follow-ups** - Breaks the scope chain -- **Asking for "new PRs" unnecessarily** - Usually you want to update existing work - -## Technical Implementation - -Scope keys are implemented in the agent runner system: - -```python -# Each platform implements scope key generation -class SlackRunner: - def agent_run_scope_key(self) -> str: - return f"slack-{self.slack_thread_ts}" - -class LinearRunner: - def agent_run_scope_key(self) -> str: - return f"linear-{self.linear_issue_id}" - -class GithubRunner: - def agent_run_scope_key(self) -> str: - return f"github-pr-{self.pr_number}-{self.repo_id}" -``` - -When a new agent run starts, the system: -1. Generates the appropriate scope key -2. Looks up previous runs with the same scope key -3. Inherits context from those previous runs -4. Continues the work in the same "conversation" - -## Troubleshooting - -**Problem:** Codegen keeps creating new PRs instead of updating existing ones -**Solution:** Make sure you're asking for changes in the same Slack thread, Linear issue, or PR where the original work was done. - -**Problem:** Codegen doesn't remember previous context -**Solution:** Check that you're interacting in the same scope (same thread/ticket/PR) as the previous interaction. - -**Problem:** Context seems to be inherited from unrelated work -**Solution:** This might indicate a scope key collision - check that you're working in the right thread/ticket/PR. - ---- - -Understanding scope keys helps you work more effectively with Codegen by ensuring your requests build on each other rather than starting from scratch each time. - diff --git a/docs/docs.json b/docs/docs.json index e4efbfc06..9b6d606f7 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -25,7 +25,9 @@ }, { "group": "Architecture", - "pages": ["architecture/scope-keys"] + "pages": [ + "architecture/context-inheritance" + ] }, { "tab": "Documentation", From 474499088f657ba34a4f729b143bf05cbd7cd624 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Tue, 3 Jun 2025 18:33:44 +0000 Subject: [PATCH 4/4] Automated pre-commit update --- docs/docs.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 9b6d606f7..8d9e3dedb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -25,9 +25,7 @@ }, { "group": "Architecture", - "pages": [ - "architecture/context-inheritance" - ] + "pages": ["architecture/context-inheritance"] }, { "tab": "Documentation",