Use Scenario 12 to investigate technical debt in a selected component and prepare a repayment plan. Choose the data source for your task: the scenario proposes work slices, the dashboard summarizes the project, and configuration checks find unused settings.
Choose an analysis method
| Need | Analysis method | Result |
|---|---|---|
| Explain and sequence debt work for an accepted task | typed Scenario 12 | analysis and proposed plan |
| Read the current project summary | codegraph_quality_tech_debt_report_get() |
dead-method candidates, complexity hotspots, graph counts |
| Detect orphaned or ineffective configuration | python -m src.cli dogfood config-check |
configuration-hygiene findings |
The dashboard MCP accepts an empty argument object and resolves the active project from runtime context. It returns graph counts and complexity hotspots. config-check examines configuration usage. Run Scenario 12 to prepare a repayment plan with work slices.
Prerequisites and scope
Prepare the Python environment and local configuration using the CLI guide and programmatic guide. Scenario 12 requires an accepted developer task, current project CPG, reachable graph services and a configured LLM. Run Python examples in that environment. Replace every context placeholder with the accepted project, namespace, task, evidence reference and source path.
Name the affected component, decision horizon, revision, and acceptance constraints. Attach current tests or production evidence when the debt claim depends on behavior, latency, incidents, or operating cost.
To set priorities, compare complexity and dead-code candidates with product impact, change frequency, remediation cost, and risk. Assign an owner to each selected area and attach the data behind its priority.
Choose the first work slice
In this illustrative example, the summary identifies two methods: repository loading with complexity 18 and a legacy-format conversion with complexity 32. The team frequently changes repository loading, and its failures delay onboarding new projects. The conversion runs rarely and has stable test coverage.
Start with repository loading if change and incident history supports that impact. In the first slice, extract error handling into a separate function, preserve retry behavior, and check successful loading, network failure, and a repeated run. Attach the original report and these check results to the task.
After the change, collect a new summary and compare the method against the same
baseline revision. Lower complexity shows a structural change; behavior checks
show that loading and recovery work. The plan now connects a finding to a
verifiable user outcome. These numbers and methods are illustrative; use your
project’s complexity_hotspots and the team’s work history for the actual decision.
Run the typed scenario
from src.digital_employees.runtime.scenarios import (
RoleBoundScenarioInvocationRequest,
invoke_role_bound_scenario_request,
)
request = RoleBoundScenarioInvocationRequest(
query="Rank debt in the import pipeline and propose bounded repayment slices.",
employee_id="codegraph_developer",
scenario_id="scenario_12",
event_type="implementation_start",
context={
"project_key": "codegraph",
"namespace": "default",
"task_id": "<task-id>",
"source_refs": ["<revision-ref>", "<quality-evidence-ref>"],
"file_paths": ["<bounded-source-path>"],
},
)
result = invoke_role_bound_scenario_request(request)
if result.get("error"):
raise RuntimeError(result["error"])
if not result.get("scenario_id") or not result.get("answer"):
raise RuntimeError("Scenario returned no scenario identity or answer")
print(result["answer"])
Run the dashboard MCP separately when you need a current aggregate:
codegraph_quality_tech_debt_report_get()
Get a technical-debt summary through MCP
- Connect to CodeGraph using the reviewer read connection with profile
codex:role:codegraph_reviewer:read. Follow the MCP operator guide to configure the connection. - Select a project with a current CPG.
- Find
codegraph_quality_tech_debt_report_getin the client tool catalog and invoke it with an empty argument object{}. - Read the JSON summary. Save it with the project revision and request time.
- Open the source locations in
complexity_hotspots, compare them with tests, and select areas for the repayment plan.
| Field | How to use it |
|---|---|
total_methods |
Number of methods in the selected graph. |
dead_methods |
Number of internal methods without incoming calls, excluding test methods. Review these candidates for actual usage. |
dead_method_ratio |
dead_methods divided by max(total_methods, 1), rounded to three decimal places. |
total_files |
Number of distinct file paths represented by methods. |
complexity_hotspots |
Functions above the configured cyclomatic-complexity threshold, ordered by decreasing complexity. |
processing_time_ms |
Time spent collecting the summary, in milliseconds. |
The dead_method_ratio is a number between 0 and 1. For example, with total_methods=102570 and dead_methods=6223, the summary returns dead_method_ratio=0.061: after rounding, this is 6.1% of the graph methods. Multiply the ratio by 100 to display a percentage. Use the original dead_methods count to estimate the number of candidates to review.
Each complexity_hotspots item contains name, full_name, file, line,
and complexity. Open the indicated file and line to inspect the function’s branches
and prepare tests before changing it.
If the JSON contains error, restore graph access and repeat the request:
collection failures fill the counters with zeros. Project-context failures return
Error: ... as text; select an accessible project and repeat the call.
Check configuration usage
Run python -m src.cli dogfood config-check from the CodeGraph checkout root
in the prepared CLI environment. The command reads config.yaml, the configuration
schema, and source files. Each text finding includes its severity, parameter name,
and description; source findings also identify a file and line. The final Summary
line reports errors, warnings, and informational findings.
Exit code 2 means errors were found, 1 means warnings without errors,
and 0 means neither errors nor warnings. A report with exit code 0 can still
contain informational findings. Open the reported locations and check parameter
usage before adding configuration changes to the plan. See the dogfooding guide
for JSON/CSV formats, severity filtering, and saving the report.
Read the result
For Scenario 12, retain the proposed slices, source evidence, assumptions, risks, and scenario invocation metadata. For the dashboard summary, retain the observation time and project revision. For config-check, retain the exact configuration revision and command output.
Reproduce decision-relevant findings in source or a focused test before scheduling work. Treat a synthesized plan as the starting proposal and record the confirmed debt severity with its evidence.
Scenario metadata includes estimated effort, debt severity and proposed repayment duration. These are analysis estimates, not measured delivery time or an approved budget. The dashboard tool can return Error: ... as text instead of a JSON summary. Check the returned content before parsing or interpreting its numbers.
From planning to implementation
The scenario, dashboard summary, and configuration check return analysis results and preserve source files. The accountable human approves scope, the plan, and product priority. Create an implementation task for each accepted slice with tests-first changes, acceptance criteria, focused validation, and structural, AppSec, and QA review where applicable.
Keep results from different revisions separate. When dashboard data is missing, inspect the source and task evidence before recording the debt status.
Failure and recovery
- MCP error text: verify active project context and CPG availability, then repeat the summary request.
- Generic Scenario 12 output: narrow the component, evidence refs, and decision question.
- Config-check finding: confirm the key is truly unused before deleting configuration.
- Disputed priority: record the product and operational evidence separately, then rerun the decision review.