feat: populate ExampleDoc.output for robot examples endpoint (F3.3) #30

New Issue

2026-04-25T06:02:44+02:00

root commented

2026-04-25 06:02:44 +02:00

Problem Statement

Spec F3.3 (terraphim-agent-session-search-spec.md, lines 270-274) defines the robot examples [command] endpoint as "runnable examples with expected outputs." The data structure already supports this:

pub struct ExampleDoc {
    pub description: String,
    pub command: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub output: Option<String>,
}

However, all 22 ExampleDoc { .. } instances in crates/terraphim_agent/src/robot/docs.rs omit the output field. Verification:

rg "ExampleDoc \{" crates/terraphim_agent/src/robot/docs.rs | wc -l   -> 22
rg "output: Some\(" crates/terraphim_agent/src/robot/docs.rs | wc -l  -> 0

The user-facing failure mode: an LLM running terraphim-agent robot examples search --format json sees only description and command fields. It cannot learn the expected response shape without separately invoking the example -- defeating the purpose of self-documentation.

Acceptance Criteria

Every ExampleDoc for the user-facing commands (search, sessions, config, role, graph, vm, autocomplete, extract, find, replace, chat, summarize, robot) populates output: Some(<representative JSON>).
Representative outputs are syntactically valid JSON (or exact stdout for non-JSON commands), use the spec envelope (success, meta, data, errors) where applicable, and reflect the canonical robot-mode response shape from F1.1 lines 64-93.
Outputs are kept short (<= 12 lines each) so the JSON envelope stays under typical 4-8K token budgets when listing examples for a command.
Unit test crates/terraphim_agent/src/robot/docs.rs::tests::test_examples_have_output asserts that for every command, every ExampleDoc has output.is_some().
cargo test -p terraphim_agent --lib robot::docs passes.
cargo clippy -p terraphim_agent -- -D warnings passes.

Proposed Approach

In build_command_docs() (crates/terraphim_agent/src/robot/docs.rs), for each ExampleDoc { description, command, output: None } construct a representative JSON string matching the spec envelope. Recommended: extract a small helper fn ex(desc: &str, cmd: &str, output: &str) -> ExampleDoc to reduce verbosity.
For each command, derive the example output from the existing RobotResponse<T> types in robot/schema.rs so the example shape stays in sync with the actual code path.
Add a single unit test in the existing mod tests block:

#[test]
fn test_examples_have_output() {
    let docs = SelfDocumentation::new();
    for cmd in docs.all_schemas() {
        for (i, ex) in cmd.examples.iter().enumerate() {
            assert!(
                ex.output.is_some(),
                "command={} example #{} ({:?}) missing expected output",
                cmd.name, i, ex.description
            );
        }
    }
}

Affected crates: terraphim_agent only.
Key types modified: ExampleDoc instances inside SelfDocumentation::build_command_docs() (no struct changes).

Dependencies

None. Pure additive change; touches a single file.

Verification

cargo test -p terraphim_agent --lib robot::docs::tests::test_examples_have_output
cargo test -p terraphim_agent --lib robot::docs
cargo clippy -p terraphim_agent -- -D warnings
./target/debug/terraphim-agent robot examples search --format json | jq '.data.examples[].output' # all non-null

Scope

Single-file change in crates/terraphim_agent/src/robot/docs.rs. Estimated 200-280 lines added (22 outputs averaging 8-10 lines each + helper + test). Implementable in one PR.

## Problem Statement Spec F3.3 (terraphim-agent-session-search-spec.md, lines 270-274) defines the `robot examples [command]` endpoint as "runnable examples with expected outputs." The data structure already supports this: ```rust pub struct ExampleDoc { pub description: String, pub command: String, #[serde(skip_serializing_if = "Option::is_none")] pub output: Option<String>, } ``` However, all 22 `ExampleDoc { .. }` instances in `crates/terraphim_agent/src/robot/docs.rs` omit the `output` field. Verification: ``` rg "ExampleDoc \{" crates/terraphim_agent/src/robot/docs.rs | wc -l -> 22 rg "output: Some\(" crates/terraphim_agent/src/robot/docs.rs | wc -l -> 0 ``` The user-facing failure mode: an LLM running `terraphim-agent robot examples search --format json` sees only `description` and `command` fields. It cannot learn the expected response shape without separately invoking the example -- defeating the purpose of self-documentation. ## Acceptance Criteria - [ ] Every `ExampleDoc` for the user-facing commands (`search`, `sessions`, `config`, `role`, `graph`, `vm`, `autocomplete`, `extract`, `find`, `replace`, `chat`, `summarize`, `robot`) populates `output: Some(<representative JSON>)`. - [ ] Representative outputs are syntactically valid JSON (or exact stdout for non-JSON commands), use the spec envelope (`success`, `meta`, `data`, `errors`) where applicable, and reflect the canonical robot-mode response shape from F1.1 lines 64-93. - [ ] Outputs are kept short (<= 12 lines each) so the JSON envelope stays under typical 4-8K token budgets when listing examples for a command. - [ ] Unit test `crates/terraphim_agent/src/robot/docs.rs::tests::test_examples_have_output` asserts that for every command, every `ExampleDoc` has `output.is_some()`. - [ ] `cargo test -p terraphim_agent --lib robot::docs` passes. - [ ] `cargo clippy -p terraphim_agent -- -D warnings` passes. ## Proposed Approach 1. In `build_command_docs()` (crates/terraphim_agent/src/robot/docs.rs), for each `ExampleDoc { description, command, output: None }` construct a representative JSON string matching the spec envelope. Recommended: extract a small helper `fn ex(desc: &str, cmd: &str, output: &str) -> ExampleDoc` to reduce verbosity. 2. For each command, derive the example output from the existing `RobotResponse<T>` types in `robot/schema.rs` so the example shape stays in sync with the actual code path. 3. Add a single unit test in the existing `mod tests` block: ```rust #[test] fn test_examples_have_output() { let docs = SelfDocumentation::new(); for cmd in docs.all_schemas() { for (i, ex) in cmd.examples.iter().enumerate() { assert!( ex.output.is_some(), "command={} example #{} ({:?}) missing expected output", cmd.name, i, ex.description ); } } } ``` Affected crates: `terraphim_agent` only. Key types modified: `ExampleDoc` instances inside `SelfDocumentation::build_command_docs()` (no struct changes). ## Dependencies None. Pure additive change; touches a single file. ## Verification ```bash cargo test -p terraphim_agent --lib robot::docs::tests::test_examples_have_output cargo test -p terraphim_agent --lib robot::docs cargo clippy -p terraphim_agent -- -D warnings ./target/debug/terraphim-agent robot examples search --format json | jq '.data.examples[].output' # all non-null ``` ## Scope Single-file change in `crates/terraphim_agent/src/robot/docs.rs`. Estimated 200-280 lines added (22 outputs averaging 8-10 lines each + helper + test). Implementable in one PR.

product-owner referenced this issue

2026-04-25 08:02:02 +02:00

feat: add robot subcommand surface for capabilities schemas examples (f3.1 f3.2 f3.3 task 1.3.4) #36

product-owner referenced this issue

2026-04-25 11:09:06 +02:00

feat: criterion benchmark suite for G1 performance targets #43

product-owner referenced this issue

2026-04-27 07:00:23 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35

product-owner added a new dependency 2026-04-27 11:03:37 +02:00

#36 feat: add robot subcommand surface for capabilities schemas examples (f3.1 f3.2 f3.3 task 1.3.4)

product-owner referenced this issue