feat: add why investigation workflows

Author: quangdang46

.beads/issues.jsonl

@@ -4,7 +4,7 @@
 {"id":"why-29z","title":"Benchmark coupling and outage performance","status":"closed","priority":3,"issue_type":"task","created_at":"2026-03-31T15:04:47.074853587Z","created_by":"quangdang","updated_at":"2026-03-31T15:12:53.200972486Z","closed_at":"2026-03-31T15:12:53.200930041Z","close_reason":"Completed","source_repo":".","compaction_level":0,"original_size":0}
 {"id":"why-2ky","title":"Adopt Claude Code investigation-runtime patterns in why","description":"Adopt Claude Code's strongest multi-surface investigation patterns in why: shared question-engine ownership, markdown-defined investigation workflows, and bounded result/policy handling for expensive git + LLM operations.","design":"Keep this epic focused on multi-surface investigation quality: a shared question engine, named investigation workflows, and bounded policy-aware handling for expensive git plus model operations.","acceptance_criteria":"Child beads cover engine extraction, workflow loading, and bounded or policy-aware output behavior. The epic stays tightly tied to history-investigation use cases.","notes":"Copy the runtime discipline, not the product-specific surface area.","status":"open","priority":1,"issue_type":"epic","created_at":"2026-03-31T16:34:21.250561562Z","created_by":"Codex","updated_at":"2026-03-31T16:42:07.575816255Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["architecture","claude-code-port","investigation"]}
 {"id":"why-2ky.1","title":"Extract a shared question engine for why","description":"Extract a shared why question engine that owns history-target normalization, evidence gathering, prompt assembly, model invocation, and result shaping so CLI and future MCP/web surfaces share one investigative core.","design":"Extract a shared question engine that owns target normalization, git evidence collection policy, prompt assembly, model invocation, and bounded result shaping so CLI and future MCP or web surfaces share one investigative core.","acceptance_criteria":"At least two why-facing surfaces can share the question engine boundary, or the engine is clearly transport-neutral and covered by tests. Evidence and result shaping no longer live only in the CLI path. Tests cover engine behavior directly.","notes":"This bead is high leverage because the product thesis already separates evidence gathering from presentation.","status":"closed","priority":1,"issue_type":"task","created_at":"2026-03-31T16:34:21.928038332Z","created_by":"Codex","updated_at":"2026-04-01T06:22:19.556317528Z","closed_at":"2026-04-01T06:22:19.556153427Z","close_reason":"Extracted why-question-engine for shared target normalization, archaeology, evidence, and report synthesis; rewired CLI default query and LSP hover to consume the shared engine with direct tests.","source_repo":".","compaction_level":0,"original_size":0,"labels":["architecture","claude-code-port","provider-runtime"],"dependencies":[{"issue_id":"why-2ky.1","depends_on_id":"why-2ky","type":"parent-child","created_at":"2026-03-31T16:34:21.928038332Z","created_by":"Codex","metadata":"{}","thread_id":""}]}
-{"id":"why-2ky.2","title":"Load markdown-defined investigation workflows in why","description":"Load markdown-defined investigation workflows for common why jobs such as root-cause archaeology, design-intent lookup, regression context gathering, and blame-to-commit narrative assembly.","design":"Load markdown-defined investigation workflows for jobs like root-cause archaeology, design-intent lookup, regression context gathering, and blame-to-commit narrative assembly so agents can call named investigation recipes instead of improvising every prompt.","acceptance_criteria":"Why can discover and load investigation workflows from markdown on disk. At least one named workflow is usable by an agent client or local scripted flow. Parsing, loading, and reload behavior are tested.","notes":"Package investigative intent rather than hardcoding prompt strings inside Rust match arms.","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-31T16:34:22.519107188Z","created_by":"Codex","updated_at":"2026-03-31T16:42:39.502855636Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["agent-integration","claude-code-port","workflow"],"dependencies":[{"issue_id":"why-2ky.2","depends_on_id":"why-2ky","type":"parent-child","created_at":"2026-03-31T16:34:22.519107188Z","created_by":"Codex","metadata":"{}","thread_id":""},{"issue_id":"why-2ky.2","depends_on_id":"why-2ky.1","type":"blocks","created_at":"2026-03-31T16:34:23.070264679Z","created_by":"quangdang","metadata":"{}","thread_id":""}]}
+{"id":"why-2ky.2","title":"Load markdown-defined investigation workflows in why","description":"Load markdown-defined investigation workflows for common why jobs such as root-cause archaeology, design-intent lookup, regression context gathering, and blame-to-commit narrative assembly.","design":"Load markdown-defined investigation workflows for jobs like root-cause archaeology, design-intent lookup, regression context gathering, and blame-to-commit narrative assembly so agents can call named investigation recipes instead of improvising every prompt.","acceptance_criteria":"Why can discover and load investigation workflows from markdown on disk. At least one named workflow is usable by an agent client or local scripted flow. Parsing, loading, and reload behavior are tested.","notes":"Package investigative intent rather than hardcoding prompt strings inside Rust match arms.","status":"closed","priority":2,"issue_type":"task","created_at":"2026-03-31T16:34:22.519107188Z","created_by":"Codex","updated_at":"2026-04-01T06:43:21.014208166Z","closed_at":"2026-04-01T06:43:21.013754766Z","close_reason":"Added markdown workflow files, a dedicated loader crate with reload tests, and MCP list/get workflow tools so agents can consume named why investigation recipes from disk.","source_repo":".","compaction_level":0,"original_size":0,"labels":["agent-integration","claude-code-port","workflow"],"dependencies":[{"issue_id":"why-2ky.2","depends_on_id":"why-2ky","type":"parent-child","created_at":"2026-03-31T16:34:22.519107188Z","created_by":"Codex","metadata":"{}","thread_id":""},{"issue_id":"why-2ky.2","depends_on_id":"why-2ky.1","type":"blocks","created_at":"2026-03-31T16:34:23.070264679Z","created_by":"quangdang","metadata":"{}","thread_id":""}]}
 {"id":"why-2ky.3","title":"Add bounded evidence budgeting and policy gating in why","description":"Add bounded result budgeting, provider-aware policy checks, and operator-readable gate reasons for expensive why operations so deep git walks, large evidence sets, and costly model calls are explicit and controllable.","design":"Add bounded evidence budgeting, provider-aware policy checks, and operator-readable gate reasons for expensive why operations so deep git walks, large evidence sets, and costly model calls are explicit and controllable.","acceptance_criteria":"Why exposes bounded output and evidence policies for expensive investigations. Gate or truncation reasons appear in structured output or diagnostics. Tests cover representative budgeted and gated scenarios.","notes":"This bead should make why safer for agent automation and long-running usage, not merely stricter for humans.","status":"closed","priority":1,"issue_type":"task","created_at":"2026-03-31T16:34:23.694266474Z","created_by":"Codex","updated_at":"2026-04-01T06:36:06.543249511Z","closed_at":"2026-04-01T06:36:06.542516911Z","close_reason":"Added bounded evidence commit budgets, provider-aware LLM gating, and structured policy/truncation reasons surfaced through why reports and shared question-engine tests.","source_repo":".","compaction_level":0,"original_size":0,"labels":["budgeting","claude-code-port","policy"],"dependencies":[{"issue_id":"why-2ky.3","depends_on_id":"why-2ky","type":"parent-child","created_at":"2026-03-31T16:34:23.694266474Z","created_by":"Codex","metadata":"{}","thread_id":""},{"issue_id":"why-2ky.3","depends_on_id":"why-2ky.1","type":"blocks","created_at":"2026-03-31T16:34:24.310467531Z","created_by":"quangdang","metadata":"{}","thread_id":""}]}
 {"id":"why-2x9","title":"Reconcile docs with implemented symbol-query support","description":"Update README/POC/spec-style docs to match the actual Rust implementation, which already supports symbol queries across Rust, JavaScript, TypeScript, and Python. Clarify that symbol support is implemented even if richer synthesis/reporting phases remain future work, and align placeholder locator spec text accordingly.","status":"closed","priority":2,"issue_type":"task","created_at":"2026-03-11T05:27:36.932742629Z","created_by":"quangdang","updated_at":"2026-03-11T05:29:32.161445314Z","closed_at":"2026-03-11T05:29:32.160132720Z","close_reason":"Completed","source_repo":".","compaction_level":0,"original_size":0,"labels":["docs","phase:2","product"]}
 {"id":"why-2xa","title":"temp parent blocked repro child","status":"closed","priority":4,"issue_type":"task","created_at":"2026-03-11T11:45:14.052458353Z","created_by":"quangdang","updated_at":"2026-03-11T11:46:16.492127341Z","closed_at":"2026-03-11T11:46:16.492091260Z","close_reason":"Repro child closes after parent unblocked","source_repo":".","compaction_level":0,"original_size":0,"dependencies":[{"issue_id":"why-2xa","depends_on_id":"why-1hf","type":"parent-child","created_at":"2026-03-11T11:45:26.788940915Z","created_by":"quangdang","metadata":"{}","thread_id":""}]}

Cargo.lock

@@ -16,6 +16,7 @@ members = [
     "crates/hooks",
     "crates/cache",
     "crates/question-engine",
+    "crates/workflows",
     "crates/test-support",
 ]
 resolver = "2"

Cargo.toml

@@ -15,3 +15,4 @@ why-archaeologist = { path = "../archaeologist" }
 why-locator = { path = "../locator" }
 why-scanner = { path = "../scanner" }
 why-splitter = { path = "../splitter" }
+why-workflows = { path = "../workflows" }

crates/mcp/Cargo.toml

@@ -6,6 +6,7 @@ use why_archaeologist::analyze_target;
 use why_locator::parse_target;
 use why_scanner::{scan_coupling, scan_hotspots, scan_rename_safe, scan_time_bombs};
 use why_splitter::suggest_split;
+use why_workflows::{load_builtin_workflow, load_builtin_workflows};
 
 const JSONRPC_VERSION: &str = "2.0";
 const DEFAULT_TIME_BOMB_AGE_DAYS: i64 = 30;
@@ -156,6 +157,27 @@ fn tools_list_result() -> Value {
                     "required": ["target"],
                     "additionalProperties": false
                 })
+            ),
+            tool_definition(
+                "why_list_workflows",
+                "List builtin why investigation workflows loaded from markdown on disk.",
+                json!({
+                    "type": "object",
+                    "properties": {},
+                    "additionalProperties": false
+                })
+            ),
+            tool_definition(
+                "why_get_workflow",
+                "Load a named builtin why investigation workflow from markdown on disk.",
+                json!({
+                    "type": "object",
+                    "properties": {
+                        "id": { "type": "string" }
+                    },
+                    "required": ["id"],
+                    "additionalProperties": false
+                })
             )
         ]
     })
@@ -294,6 +316,32 @@ fn call_tool(params: Option<Value>) -> std::result::Result<Value, McpError> {
                 )
             })?
         }
+        "why_list_workflows" => serde_json::to_value(
+            load_builtin_workflows().map_err(|error| McpError::tool_error(error.to_string()))?,
+        )
+        .map_err(|error| {
+            McpError::new(
+                ErrorCode::InternalError,
+                format!("failed to serialize why_list_workflows result: {error}"),
+            )
+        })?,
+        "why_get_workflow" => {
+            let args: WhyGetWorkflowArgs = deserialize_arguments(request.arguments)?;
+            let workflow = load_builtin_workflow(&args.id)
+                .map_err(|error| McpError::tool_error(error.to_string()))?
+                .ok_or_else(|| {
+                    McpError::new(
+                        ErrorCode::InvalidParams,
+                        format!("unknown workflow: {}", args.id),
+                    )
+                })?;
+            serde_json::to_value(workflow).map_err(|error| {
+                McpError::new(
+                    ErrorCode::InternalError,
+                    format!("failed to serialize why_get_workflow result: {error}"),
+                )
+            })?
+        }
         other => {
             return Err(McpError::new(
                 ErrorCode::InvalidParams,
@@ -360,6 +408,11 @@ struct WhyRenameSafeArgs {
     since_days: Option<u64>,
 }
 
+#[derive(Debug, Clone, Deserialize)]
+struct WhyGetWorkflowArgs {
+    id: String,
+}
+
 #[derive(Debug, Clone, Deserialize)]
 struct ToolCallRequest {
     name: String,
@@ -496,13 +549,15 @@ mod tests {
         assert!(result["tools"].is_array(), "tools should be array");
         let empty_tools = Vec::new();
         let tools = result["tools"].as_array().unwrap_or(&empty_tools);
-        assert_eq!(tools.len(), 6);
+        assert_eq!(tools.len(), 8);
         assert_eq!(tools[0]["name"], "why_symbol");
         assert_eq!(tools[1]["name"], "why_split");
         assert_eq!(tools[2]["name"], "why_time_bombs");
         assert_eq!(tools[3]["name"], "why_hotspots");
         assert_eq!(tools[4]["name"], "why_coupling");
         assert_eq!(tools[5]["name"], "why_rename_safe");
+        assert_eq!(tools[6]["name"], "why_list_workflows");
+        assert_eq!(tools[7]["name"], "why_get_workflow");
     }
 
     #[test]
@@ -596,4 +651,41 @@ mod tests {
         assert_eq!(error.code, ErrorCode::InvalidParams.as_i32());
         assert!(error.message.contains("limit must be greater than zero"));
     }
+
+    #[test]
+    fn workflow_tools_return_builtin_markdown_workflows() {
+        let list_response = handle_request(request(
+            "tools/call",
+            json!({
+                "name": "why_list_workflows",
+                "arguments": {}
+            }),
+        ));
+        assert!(list_response.error.is_none());
+        let list_payload = &list_response.result.unwrap_or(Value::Null)["content"][0]["json"];
+        let workflows = list_payload
+            .as_array()
+            .expect("workflow list should be array");
+        assert!(
+            workflows
+                .iter()
+                .any(|workflow| workflow["id"] == "root-cause-archaeology")
+        );
+
+        let get_response = handle_request(request(
+            "tools/call",
+            json!({
+                "name": "why_get_workflow",
+                "arguments": { "id": "root-cause-archaeology" }
+            }),
+        ));
+        assert!(get_response.error.is_none());
+        let workflow = &get_response.result.unwrap_or(Value::Null)["content"][0]["json"];
+        assert_eq!(workflow["id"], "root-cause-archaeology");
+        assert!(
+            workflow["body"]
+                .as_str()
+                .is_some_and(|body| body.contains("Run the default `why` report first"))
+        );
+    }
 }

crates/mcp/src/lib.rs

@@ -0,0 +1,15 @@
+[package]
+name = "why-workflows"
+version = "0.1.0"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+publish = false
+
+[dependencies]
+anyhow.workspace = true
+serde.workspace = true
+
+[dev-dependencies]
+tempfile = "3"