Interactive Pipeline Failure Investigation Assistant

[github-actions]

Strategic Improvement

Build a CLI command shipwright investigate [pipeline-id] that launches an interactive Claude Code session pre-loaded with failure context (error logs, stage state, file changes, memory patterns) and offers guided debugging — suggest root cause hypotheses, propose fixes, allow user to replay stages or test fixes interactively. Complements #596 (replay) with human-in-the-loop exploration.

Acceptance Criteria

• Command shipwright investigate <pipeline-id> launches Claude Code session with failure context injected
• Context includes: error-log.jsonl, pipeline-state.md, file diffs from failed stage, similar past failures from memory
• Interactive prompt offers: root cause hypotheses (top 3), proposed fix commands, ability to replay stage with modifications
• User can apply suggested fixes and re-run validation without full pipeline restart
• Session transcript saved to .claude/investigations// for future reference
• Test suite validates context assembly, prompt construction, and session launch

Context

• Priority: P1
• Complexity: fast
• Generated by: Strategic Intelligence Agent
• Strategy alignment: P1: Developer Experience

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	standard
Max Iterations	20
Triage	Improves pipeline observability with interactive failure investigation; well-scoped DX feature using existing error logs and memory system; complements replay functionality.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	26988181230

The autonomous pipeline is processing this issue. Updates will be posted as stages complete.

[github-actions]

[github-actions]

[github-actions]

📋 Implementation Plan

Click to expand full plan (307 lines)

Implementation Plan — Interactive Pipeline Failure Investigation Assistant

Issue: #607 · Command: shipwright investigate <pipeline-id> · Complexity: fast

Summary

Add a new bash script scripts/sw-investigate.sh that assembles failure context
(error log, pipeline state, file diffs, similar memory patterns, root-cause
classification) for a given pipeline/issue id, builds an investigation prompt,
and launches an interactive Claude Code session pre-loaded with that context.
The session transcript, assembled context, and prompt are persisted under
.claude/investigations/<pipeline-id>/ for later reference. A test suite
validates context assembly, prompt construction, and (mocked) session launch.

This complements sw-replay.sh (#596): replay is read-only DVR playback;
investigate is human-in-the-loop debugging with fix-and-re-validate.

---

Socratic Design Refinement (reasoning recorded)

Minimum viable change. A single self-contained script sw-investigate.sh
that (1) gathers the failure context artifacts, (2) composes one prompt, (3)
launches claude interactively with that prompt, (4) saves a transcript. One
router line in scripts/sw, one help entry, one test file, one package.json
registration, doc rows. No changes to pipeline stages or scripts/lib/ are
required — investigation is an out-of-band tool, not a pipeline stage.

Implicit requirements (inferred, not stated): must degrade gracefully when an
artifact is missing (failures often occur before build produces a diff); must work
with NO_GITHUB=true / offline (no GitHub calls at all in this feature); pipeline-id
is the GitHub issue number used elsewhere (#607) but should also resolve from
pipeline-state.md when omitted.

Reuse over new infrastructure: reuse memory_ranked_search (sw-memory.sh) for
similar-failure retrieval, rootcause_analyze_error_log / rootcause_classify
(lib/root-cause.sh) for hypotheses, the claude launch idiom from sw-loop.sh, the
header/boilerplate + fallback-function pattern from sw-replay.sh, and the
lib/test-helpers.sh harness used by sw-replay-test.sh. Net new logic is only the
context bundler + prompt composer + transcript persistence.

---

Files to Modify

File	Action	Purpose
scripts/sw-investigate.sh	create	Main command: context assembly, prompt build, session launch, transcript save
scripts/sw-investigate-test.sh	create	Unit/integration tests (assembly, prompt, mock launch, persistence, degradation)
scripts/sw	modify	Add investigate) dispatch case + help/menu entry (Observability group)

✅ Task Checklist

• Task 1: Create sw-investigate.sh header, VERSION, lib sourcing, fallback guards, check_jq
• Task 2: Defensive source of lib/root-cause.sh + sw-memory.sh with type -t guards
• Task 3: resolve_pipeline_id() (arg → pipeline-state issue: → latest, strip #)
• Task 4: gather_pipeline_state() — capped read, absence marker
• Task 5: gather_error_log() — jq last-20 entries, pipefail-safe empty
• Task 6: gather_diffs() — git-guarded, subshell cd, size-capped
• Task 7: gather_memory() — memory_ranked_search top-3 similar failures
• Task 8: gather_hypotheses() — root-cause top-3, heuristic fallback
• Task 9: compose_context() — atomic context.md + meta.json (jq --arg)
• Task 10: compose_prompt() — guided-debugging prompt → prompt.txt
• Task 11: launch_session() + cmd_investigate() — orchestrate, launch/stub, tee transcript, emit events
• Task 12: cmd_context(), cmd_help(), main() dispatch + default subcommand
• Task 13: Add investigate) case + help entry in scripts/sw
• Task 14: Write sw-investigate-test.sh (assembly, prompt, mock launch, transcript, degradation)
• Task 15: Register test in package.json; update .claude/CLAUDE.md; docs sync
• shipwright investigate <id> assembles context and launches an interactive
• Context bundle includes error-log.jsonl, pipeline-state.md, failed-stage diffs,
• Prompt offers top-3 root-cause hypotheses, proposed fix commands, and
• Session transcript + context + prompt saved under .claude/investigations/<pipeline-id>/
• User can apply suggested fixes and re-run validation without full pipeline restart

---

Generated by shipwright pipeline at 2026-06-05T00:48:00Z

[github-actions]

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (511 lines)

Architecture Decision Record: Interactive Pipeline Failure Investigation Assistant

Context

When a pipeline stage fails, developers need rapid, interactive debugging. Currently, Shipwright offers:

• sw-replay.sh (Pipeline Execution Trace Capture with Interactive Replay Debugger #596): Read-only DVR playback—useful for understanding what happened, but not for fixing it
• Manual investigation: Developers manually sift through logs, diffs, and error signatures—time-consuming and error-prone

The investigation assistant bridges this gap: gather failure context (error log, pipeline state, changed files, similar past failures, root-cause hypotheses), compose a guided debugging prompt, and launch an interactive Claude Code session pre-loaded with that context. The developer can then apply suggested fixes and re-validate without a full pipeline restart.

Key Constraints & Implicit Requirements:

1. Must degrade gracefully when artifacts are missing (failures often occur before build produces a diff)
2. Must work offline (NO_GITHUB=true) — no GitHub API calls
3. Must be testable in headless/CI environments (no hard requirement for interactive TTY)
4. Must be self-contained and not modify pipeline stages or shared libraries (low blast radius)
5. Must reuse existing Shipwright infrastructure (memory system, root-cause analysis, event bus)

Decision

Implement a single, self-contained bash script scripts/sw-investigate.sh that:

1. Context Assembly via Defensive Gather Functions

Each artifact source is gathered independently with existence checks and absence markers:

Source	Function	Behavior
Pipeline state	gather_pipeline_state()	head -c 4000 of .claude/pipeline-state.md, or _(no pipeline state found)_
Error log	gather_error_log()	Last 20 entries from error-log.jsonl → ts · stage · signature lines; `
File diffs	gather_diffs()	Subshell ( cd repo && git diff --stat && git diff | head -c 8000 ); gated by command -v git
Similar failures	gather_memory()	memory_ranked_search "$top_error_sig" "" 3 → bullet list; empty array → "no similar past failures"
Root-cause hypotheses	gather_hypotheses()	rootcause_analyze_error_log / rootcause_classify → top-3 ranked; heuristic fallback if lib unavailable

Critical Design: Every gather function uses || true + ${var:-} to remain pipefail-safe when an artifact is missing. This is the most likely real-world condition (failures often occur before build completes), and it's validated by edge tests.

2. Atomic Context & Prompt Composition

• compose_context() — concatenates all sections → .claude/investigations/<id>/context.md (atomic tmp+mv) + meta.json (with jq --arg, never string interpolation)
• compose_prompt() — embeds the context blocks into a role-framed prompt with guided-debugging contract, proposed fix commands, and re-validation guidance

Layout:

.claude/investigations/<pipeline-id>/
  context.md                 # assembled failure context bundle
  prompt.txt                 # exact prompt → Claude
  transcript-<ISO8601>.md    # session transcript (or stub in headless)
  meta.json                  # {id, started_at, model, sources_present[], truncated}

3. Interactive Session Launch with Graceful Degradation

• Interactive mode (default): claude "$prompt" <flags> tee'd to transcript; honors SW_FALLBACK_MODEL + --effort
• Headless mode (tests/CI): SW_INVESTIGATE_NONINTERACTIVE=1 or non-TTY → skip launch, write stub transcript, exit 0
• Tool unavailable (no claude binary): print actionable error, leave context.md/prompt.txt on disk, non-zero exit

4. Reuse of Existing Infrastructure

• Memory system (sw-memory.sh / memory_ranked_search) for retrieving similar past failures
• Root-cause analysis (lib/root-cause.sh / rootcause_analyze_error_log) for hypothesis generation
• Event bus (emit_event) for observability
• CLI conventions from sw-replay.sh (error trap, fallback guards, header boilerplate)

5. CLI & Dispatch

</details>

---
_Generated by `shipwright pipeline` design stage at 2026-06-05T00:50:29Z_

[github-actions]

[github-actions]

🔨 Build started — shipwright loop with 20 max iterations, 1 agent(s), model: haiku

[github-actions]

[github-actions]