Skip to main content

Scenario 03: Create source-backed documentation

Draft instructions from current CodeGraph source: explain a command, its options, and error recovery, then review the draft for publication.

User Guides

Use this scenario to draft a user guide from current source. Define the reader’s goal, the command or workflow to explain, an accepted task, and the relevant source files. Treat the response as a draft: verify every claim and example before publication.

Before invoking the scenario

Define these inputs first:

  • the reader and the decision or task the page must support;
  • the exact API, CLI, MCP, UI, configuration, or workflow in scope;
  • the accepted task identifier;
  • current source and test references;
  • facts that remain unknown or require a live check;
  • the destination locale and public/private boundary.

If the task is only “document the system”, narrow it to one user outcome. Broad prompts tend to produce duplicated architecture summaries rather than usable instructions.

Typed invocation

This example is for an integration developer using a CodeGraph source checkout. Install dependencies using the prerequisites in the CLI guide and configure the runtime using the Programmatic Guide. Prepare the CPG for the required project revision using Prepare the project. The call retrieves project context and sends the request to the configured LLM provider. To run it, use a registered project with available source data, a current CPG, and an accepted task. Confirm the source owner’s permission before sending private code to a provider. Save the code as documentation_request.py in the repository root and run python documentation_request.py after replacing the context values with your task’s scope. Set namespace to the value bound to the task; default is only an example.

Create the request with RoleBoundScenarioInvocationRequest and pass it to invoke_role_bound_scenario_request:

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

request = RoleBoundScenarioInvocationRequest(
    query="Draft a user guide for the current import command and its failure modes.",
    employee_id="codegraph_docs",
    scenario_id="scenario_03",
    event_type="docs_memory_sync_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": [
            "src/cli/core_commands/import_commands.py",
            "tests/unit/cli/test_import_commands.py",
        ],
    },
)

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

Replace the example source_refs with files and tests for your task. The role-bound contract requires non-empty values for project_key, namespace, and task_id. If a value is missing, the call returns role_bound_scenario_contract_missing.

A successful call prints scenario_03 first, then the scenario answer. Check error and metadata.role_bound_scenario_invocation, which connects the answer to the role-bound invocation. Then compare commands, options, and error recovery with the supplied sources and executable help. If CodeGraph cannot retrieve a referenced source, check the project binding and CPG revision, then refresh project data before requesting the source again.

Turn the result into a useful page

  1. Check that the returned scenario_id is scenario_03 and that the role-bound invocation evidence is present.
  2. Follow every important claim to current source or executable help. If source and old documentation disagree, current behavior wins.
  3. Lead with the reader’s outcome and the shortest successful procedure.
  4. Describe prerequisites, permission boundaries, side effects, outputs, failure modes, and recovery.
  5. Verify the new page’s commands and examples against current source and execution results. Record which checks were completed and which remain pending.
  6. Run the focused docs validator, link checker, catalog check, and site build for the changed pages.

Expected evidence

A reviewable documentation result should include:

  • the accepted task and locale;
  • maintained source and test references;
  • commands or requests copied from the current interface;
  • explicit unknowns and degraded-mode behavior;
  • a validation command and its result;
  • links to deeper reference material instead of copying internal implementation inventories.

For metrics, state the supported version and the source of each value. Add a check that detects changes after a product update.

Boundary and recovery

The scenario returns analysis and a draft. After reviewing it, edit the page, save it in the repository, and prepare it for publication within the accepted task.

Use employee_id="codegraph_docs" with scenario_id="scenario_03", as in the example. If project evidence is missing, mark the claim as unknown and request the exact source or a live-interface check.

For the full request contract and errors, see Programmatic Guide.

Report a documentation issue