Scenario 06: Investigate a performance problem

Use this scenario when you have a measured latency, throughput, CPU, memory, I/O, or contention problem and need to narrow the responsible code. CodeGraph ranks structural candidates and shows their callers; this static analysis creates a static hypothesis, while runtime measurements establish the performance verdict.

Define the measurement first

Record the workload, input data, warm-up, concurrency, sample count, percentile or throughput metric, hardware, runtime and configuration. Keep the same conditions before and after the change.

{
  "measurement_environment": "<hardware, runtime, config, dataset>",
  "baseline_measurement": "<metric, value, sample count>",
  "candidate_measurement": "<same metric after the change>"
}

Without a stable baseline, a lower complexity score or shorter call chain is only an engineering preference.

Typed investigation request

Use the role-bound developer scenario with an accepted task:

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

request = RoleBoundScenarioInvocationRequest(
    query="Rank code paths that could explain the measured request-latency regression.",
    employee_id="codegraph_developer",
    scenario_id="scenario_06",
    event_type="implementation_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<profile-or-trace-ref>", "<benchmark-ref>"],
        "file_paths": ["<bounded-source-path>"],
    },
)

result = invoke_role_bound_scenario_request(request)

Missing project_key, namespace, or task_id fails closed with role_bound_scenario_contract_missing. The scenario is conditional for codegraph_developer; the request should name a real performance symptom.

Inspect the blast radius

For a candidate symbol, use the current impact command:

python -m src.cli impact <symbol> --db PATH --format json

Treat callers, affected methods, depth and impact score as navigation evidence. An empty result means the symbol was not resolved in the selected graph. Confirm a change with the bound revision, tests, and performance measurements.

Tests-first optimization loop

Reproduce the problem with the recorded workload and save baseline_measurement.
Use profiles, traces or counters to connect the symptom to one bounded code path.
Use CodeGraph to inspect callers, dependencies and risk around that path.
Add a correctness regression test and, when stable enough, a performance threshold or comparison test.
Make one small change without mixing unrelated cleanup.
Run correctness tests, the same benchmark and the same profiler configuration.
Save candidate_measurement, variance and any regressions; keep the change only when the improvement is repeatable.

Compare distributions or several runs. State uncertainty when the difference is within normal noise.

Stop conditions

Proceed after reproducing the measurement in the same environment and data, keeping the candidate within the approved API, authorization, and persistence boundaries and preserving correctness and security. Return the hypothesis and missing evidence until the required checks pass.

Maintained source contracts

Impact CLI: src/cli/analysis_commands/impact_commands.py
Typed scenario routing: src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py
Developer performance policy: src/digital_employees/runtime/scenarios/employee_scenario_invocation.py

Use Feature Development for the implementation carrier and Code Review for revision-bound review evidence.