From 2b5f04e737c1bc4a623b8ed832f598d41d769488 Mon Sep 17 00:00:00 2001 From: "zackary.l.jackson" Date: Sun, 4 Oct 2026 15:16:25 +0000 Subject: [PATCH] fix(health): steer agents to the weakest dimension The tracedecay_health description told agents to maximize the composite quality signal, which hides which dimension failed. Point them at details=true and the lowest-scoring dimension instead, and correct the compute_composite_health doc comment: the coverage-discipline penalty is 2%, not 10%. Fixes #3010 Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- crates/tracedecay-graph-query/src/health.rs | 27 +++++++++++++-- .../src/definitions/analysis.rs | 2 +- .../src/definitions/tests.rs | 33 +++++++++++++++++++ 3 files changed, 59 insertions(+), 3 deletions(-) diff --git a/crates/tracedecay-graph-query/src/health.rs b/crates/tracedecay-graph-query/src/health.rs index a899a3ecf9..24ce2a2100 100644 --- a/crates/tracedecay-graph-query/src/health.rs +++ b/crates/tracedecay-graph-query/src/health.rs @@ -559,7 +559,7 @@ pub struct HealthDimensions { /// Formula: `(product of all 5).powf(1.0/5.0) * 10000.0`, rounded. /// Zero in any dimension → 0. /// A low-weight multiplicative penalty for `coverage_discipline` reduces -/// the score by up to 10% when skip-test-coverage is overused. +/// the score by up to 2% when skip-test-coverage is overused. pub fn compute_composite_health(dims: &HealthDimensions) -> u32 { let product = dims.acyclicity * dims.depth * dims.equality * dims.redundancy * dims.modularity; @@ -568,7 +568,6 @@ pub fn compute_composite_health(dims: &HealthDimensions) -> u32 { } let base = (product.powf(1.0 / 5.0) * 10_000.0).round(); - // Low-weight penalty: skip-test-coverage overuse reduces score by up to 2%. let penalized = base * (0.98 + 0.02 * dims.coverage_discipline); penalized.round() as u32 } @@ -654,6 +653,30 @@ mod tests { ); } + #[test] + fn skip_test_coverage_overuse_costs_at_most_two_percent_of_the_signal() { + let perfect = HealthDimensions { + acyclicity: 1.0, + depth: 1.0, + equality: 1.0, + redundancy: 1.0, + modularity: 1.0, + coverage_discipline: 1.0, + }; + let every_function_skipped = HealthDimensions { + coverage_discipline: 0.0, + ..perfect.clone() + }; + let half_skipped = HealthDimensions { + coverage_discipline: 0.5, + ..perfect.clone() + }; + + assert_eq!(compute_composite_health(&perfect), 10_000); + assert_eq!(compute_composite_health(&half_skipped), 9_900); + assert_eq!(compute_composite_health(&every_function_skipped), 9_800); + } + #[test] fn dependency_depth_limits_after_ranking_all_components() { let mut adjacency = diff --git a/crates/tracedecay-mcp-catalog/src/definitions/analysis.rs b/crates/tracedecay-mcp-catalog/src/definitions/analysis.rs index 9edf12f303..c2fec82c74 100644 --- a/crates/tracedecay-mcp-catalog/src/definitions/analysis.rs +++ b/crates/tracedecay-mcp-catalog/src/definitions/analysis.rs @@ -195,7 +195,7 @@ pub(super) fn def_health(input_schema: Value) -> ToolDefinition { def( "tracedecay_health", "Health Score", - "Get quality signal (0-10000) with root cause breakdown (acyclicity, depth, equality, redundancy, modularity). Quality signal = geometric mean of 5 dimensions, maximize this ONE number.", + "Get quality signal (0-10000): the geometric mean of acyclicity, depth, equality, redundancy, and modularity, reduced by up to 2% for skip-test-coverage overuse. One weak dimension drags the whole signal down (a zero zeroes it), so pass details=true for the per-dimension breakdown and fix the lowest-scoring dimension instead of chasing the composite.", input_schema, ) } diff --git a/crates/tracedecay-mcp-catalog/src/definitions/tests.rs b/crates/tracedecay-mcp-catalog/src/definitions/tests.rs index 6ec9aeb5b1..af2936bba4 100644 --- a/crates/tracedecay-mcp-catalog/src/definitions/tests.rs +++ b/crates/tracedecay-mcp-catalog/src/definitions/tests.rs @@ -107,6 +107,39 @@ fn health_read_accepts_the_empty_argument_object_on_every_surface() { assert!(request.matches(ApplicationSurfaceOperation::HealthRead)); } +/// Agents read tool descriptions as instructions. The health description +/// must steer them to the per-dimension breakdown it advertises, not to +/// maximizing the composite that hides which dimension failed. +#[test] +fn health_description_points_agents_at_the_weakest_dimension() { + let definition = get_tool_definitions() + .expect("tool definitions") + .into_iter() + .find(|definition| definition.name == "tracedecay_health") + .expect("health is advertised"); + let description = definition.description.to_lowercase(); + + assert!( + !description.contains("maximize"), + "health must not tell agents to maximize the composite: {description}" + ); + assert!( + description.contains("pass details=true") + && description.contains("fix the lowest-scoring dimension"), + "health must send agents to the per-dimension breakdown: {description}" + ); + assert_eq!( + definition.input_schema["properties"]["details"]["type"], + json!(["boolean", "null"]), + "the details flag the description names must be advertised: {}", + definition.input_schema + ); + assert!( + description.contains("up to 2%"), + "health must state the coverage-discipline penalty the score applies: {description}" + ); +} + #[test] fn handle_gated_feedback_reads_are_advertised_with_their_request_handle() { let definitions = get_tool_definitions().expect("tool definitions");