Scenario 03: Create source-backed documentation

Use this scenario when a documentation task has a named audience, bounded subject, accepted task identifier, and current source evidence. Its job is to turn verified code and interface facts into a reviewable draft. It does not publish files or certify that the documentation is complete.

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

The supported Python surface is RoleBoundScenarioInvocationRequest followed by 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/project_suite/import_commands.py",
            "tests/unit/cli/test_import_commands.py",
        ],
    },
)

result = invoke_role_bound_scenario_request(request)

Replace the example source_refs with files and tests for your task. The role-bound contract requires non-empty project_key, namespace, and task_id. Missing fields fail closed with role_bound_scenario_contract_missing.

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. Separate generated or advisory information from authoritative status and accountable lane decisions.
6. Add or update a source-bound documentation test before replacing the old page.
7. Run the focused docs validator, link checker, catalog check, and site build required by the changed surface.

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.

Do not present counts of handlers, classes, rules, or supported items unless the count is a maintained public contract and a test will detect drift.

Boundary and recovery

The scenario returns analysis and a draftable answer; it does not edit, commit, publish, or approve documentation. Repository mutations still require the normal documentation lane and task carrier.

If invocation policy rejects the employee/scenario pair, use the accountable codegraph_docs policy for scenario_03. If evidence is stale or missing, keep the claim unknown and request a targeted source or live-interface check.

Maintained source contracts

• Public typed exports: src/digital_employees/runtime/scenarios/__init__.py
• Invocation and required context: src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py
• Documentation employee policy: src/digital_employees/runtime/scenarios/employee_scenario_invocation.py

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