Skip to main content

Scenario 04: Develop a bounded feature

Find integration points for an accepted feature, verify the investigation result, and implement the scoped change with tests first.

User Guides

Before adding a feature, find where it connects to the existing code and inspect similar implementations. This scenario helps a developer trace callers and select integration points for an accepted task. Use the findings to plan the change and its regression tests. Agree on the user outcome, scope, and acceptance criteria before invoking the scenario.

How the scenario finds integration points

The scenario connects a feature request to existing code. It first checks for a matching built-in answer. For other requests, it searches project extension points and the CPG, or code property graph.

The search uses the change category, query keywords, and function names. Call graph analysis identifies possible integration points and related functions. When the workflow searches the graph, it sends these findings to the LLM as context; the answer suggests where to inspect the source before planning the change.

For example, before adding an export format, ask: “Find the export handler, format registration, and callers. Show where to connect a new format and which tests the change would affect.” Put the existing handler and test files in file_paths, and the new format contract in source_refs. This is an example task description; use the names and paths from your project.

Read the result alongside the source: locate the proposed function, trace its callers, and compare its interface with the acceptance criterion. Once you select the integration point, continue with the tests-first implementation loop.

Required task context

The accepted task records the scope, owner, acceptance criteria, and evidence. Before editing code, make sure it identifies:

  • the user outcome and exclusions;
  • testable acceptance_criteria;
  • the current revision and bounded file_paths;
  • relevant source_refs, tests, and interface contracts;
  • the reviews and release checks required for the change;
  • rollback or recovery expectations for risky behavior.

If these inputs are missing, continue planning and investigation without editing production code.

Typed investigation request

Prepare the local environment using the CLI guide. Configure the project, graph, and LLM provider using the programmatic guide. Run Python from the CodeGraph repository root in that environment. Prepare the CPG for the required revision using Prepare the project.

The example is a request template for an existing task. Replace codegraph, default, and <task-id> with its exact scope. Replace <criterion> with an accepted criterion and <implementation-path> and <test-path> with existing paths relative to the project root. Replace source_refs with an accessible task contract. These values do not create a task or authorize code changes.

Create the request with RoleBoundScenarioInvocationRequest and call invoke_role_bound_scenario_request:

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Find integration points and regression risks for the accepted feature slice.",
    employee_id="codegraph_developer",
    scenario_id="scenario_04",
    event_type="implementation_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "acceptance_criteria": ["<criterion>"],
        "file_paths": ["<implementation-path>", "<test-path>"],
        "source_refs": ["openspec/changes/<change-id>/specs/<capability>/spec.md"],
    },
)

result = invoke_role_bound_scenario_request(request)
if result.get("error"):
    raise RuntimeError(result["error"])
print(result["scenario_id"])
print(result.get("answer") or "")

The request needs non-empty values for project_key, namespace, and task_id. If a value is missing, the call raises RuntimeError with role_bound_scenario_contract_missing. The call returns investigation context and metadata for the role-bound invocation. It does not edit files; use a separate implementation workflow for code changes.

Expect scenario_04 and an answer about the selected feature. Verify it against metadata.role_bound_scenario_invocation, the source references, and the current revision. If the result contains an error or does not answer the request, keep the message and resolve the cause before acceptance. Prepare the CPG for the current revision before relying on the answer.

For a negative check, pass context={}. The call must raise RuntimeError containing role_bound_scenario_contract_missing before investigation. Restore the exact task scope before retrying.

Tests-first implementation loop

  1. Verify the task revision and inspect the smallest relevant source, tests, and callers.
  2. Map the intended behavior to one or more acceptance criteria.
  3. Add a focused test that reproduces the missing behavior or defect and observe RED for the intended reason.
  4. Make the smallest implementation or configuration change that produces GREEN.
  5. Run the focused test, nearby regression tests, and lint/type checks for the touched surface.
  6. Review changed symbols, callers, persistence and API contracts, authorization boundaries, and public documentation impact.
  7. Record revision-bound commands, results, and evidence references for each acceptance criterion.

Keep the patch within the accepted scope when the graph exposes adjacent debt. Record unrelated findings separately.

What a useful investigation returns

The result should distinguish:

  • confirmed integration points from ranked candidates;
  • current callers and how data or calls move between components;
  • similar implementations that may be useful to reuse;
  • files that are in scope from files that are merely affected;
  • unanswered questions, freshness limitations, and missing permissions;
  • focused tests and reviews still required.

Graph centrality or similarity points to code to inspect; it does not approve an architecture change. Verify the proposal in current source and tests before implementing it.

Stop conditions

Return to the task owner when the accepted behavior is ambiguous, the change requires a new API or user-facing interface, the revision changed concurrently, the necessary path is outside the task scope, or the change affects an unapproved access boundary. Clarify the behavior, file scope, or required approval before continuing.

For request details, see Programmatic Guide. For a new repository, complete Onboarding before selecting an implementation slice.

Report a documentation issue