The troubleshoot pattern

Shared troubleshoot infrastructure: one red-gate repair pass, the shared plan-change review route, and the engine-stop handover hook used by bundled patterns.

troubleshoot — shared repair and stop infrastructure

Included by bundled patterns that need a red-gate repair pass, a plan-change review handler, or the engine-stop handover hook. It is also runnable by name for a single troubleshoot pass.

troubleshoot

[header]
pattern_language_compatibility = "3"
entry = "troubleshoot"
on_stop = "write_handover"
description = """
Shared troubleshoot infrastructure: one red-gate repair pass, the shared plan-change review route,
and the engine-stop handover hook used by bundled patterns.
"""

[patterns.troubleshoot]

[[patterns.troubleshoot.parameters]]
name = "troubleshoot_prompt"
kind = "prompt-id"
default = "troubleshoot"
description = "The troubleshoot pass's prompt, named in full by the caller."

[[patterns.troubleshoot.parameters]]
name = "position"
kind = "text"
default = "Run one troubleshoot pass against the current failure and write the declared outputs."
description = "The troubleshoot pass's own briefing: which red gate it is repairing and what it may do."

[[patterns.troubleshoot.parameters]]
name = "declared_gate_command"
kind = "path"
default = "bin/gate"
description = "The gate command that judges the troubleshoot pass."

[[patterns.troubleshoot.parameters]]
name = "protected_check"
kind = "path"
default = ".gantry/no-protected-check"
description = "An optional record-path check an enclosing recursive goal run freezes."

[[patterns.troubleshoot.steps]]
name = "troubleshoot"
title = "Repair Red Gate"
type = "agent"
stage = "troubleshoot"
prompt = "{{troubleshoot_prompt}}"
judging_gate = "{{declared_gate_command}}"
diff = "iteration-start"
protected = ["PROGRESS.md", ".preamble.sys.md", "bin", "{{protected_check}}"]
confine = true
on_plan_change = "review_plan_change"
outputs = [
  { name = "troubleshoot_verdict", path = "state/troubleshoot-verdict.txt", values = ["retry", "handover"] },
  { name = "troubleshoot_revert", path = "state/troubleshoot-revert.txt", values = ["revert"] },
  { name = "troubleshoot_note", path = "state/troubleshoot-note.md" },
  { name = "handover_document", path = "state/handover.md" },
]

[patterns.troubleshoot.steps.text]
POSITION_CLAUSE = "{{position}}"

Plan changes

Agent steps name this pattern in on_plan_change. The engine watches the declared plan files across the step, runs this handler on an observed diff, and re-observes until the observation is clean.

troubleshoot

[patterns.review_plan_change]

[[patterns.review_plan_change.steps]]
name = "review_plan_change"
title = "Review Plan File Change"
type = "agent"
stage = "review"
summarize = true
prompt = "review-plan-change"
outputs = [
  { name = "plan_change_review", path = "state/plan-change-review.txt", values = ["accepted", "rejected"] },
]

nothing is the engine-provided identity pattern; no file defines it.

troubleshoot

[[patterns.review_plan_change.steps]]
if = "plan_change_review"
then = { accepted = "nothing", rejected = "examine_plan_change_rejected" }
else = "stop_plan_change_review_absent"

[[patterns.examine_plan_change_rejected.steps]]
name = "plan_change_rejected_handover"
title = "Write Plan Change Rejection Handover"
type = "agent"
stage = "troubleshoot"
prompt = "troubleshoot"
protected = ["PROGRESS.md", ".preamble.sys.md", "bin"]
confine = true
outputs = [
  { name = "plan_change_rejected_handover_document", path = "state/plan-change-rejected-handover.md" },
]

[patterns.examine_plan_change_rejected.steps.text]
POSITION_CLAUSE = """
The plan-change review rejected an agent's edit to declared plan files. Examine the rejected diff and
the plan_change_review evidence, write the handover document, and do not attempt a repair in this
session.
"""

[[patterns.examine_plan_change_rejected.steps]]
type = "call"
pattern = "stop_plan_change_rejected"

[[patterns.stop_plan_change_rejected.steps]]
type = "stop"
note = "An agent edited a declared plan file and the plan-change review rejected the edit."

[[patterns.stop_plan_change_review_absent.steps]]
type = "stop"
note = "The plan-change review did not write plan_change_review, so the run cannot accept the changed plan files."

The stop hook

Named by bundled entry headers as on_stop: one last troubleshooter whose whole deliverable is the handover document, then the stop.

troubleshoot

[patterns.write_handover]

[[patterns.write_handover.parameters]]
name = "protected_check"
kind = "path"
default = ".gantry/no-protected-check"
description = "An optional record-path check an enclosing recursive goal run freezes."

[[patterns.write_handover.steps]]
name = "final_handover"
title = "Write Handover"
type = "agent"
stage = "troubleshoot"
prompt = "troubleshoot"
protected = ["PROGRESS.md", ".preamble.sys.md", "bin", "{{protected_check}}"]
confine = true
outputs = [
  { name = "engine_stop_handover_document", path = "state/engine-stop-handover.md" },
]

[patterns.write_handover.steps.text]
POSITION_CLAUSE = """
This task is ending when this session finishes and no further repair will be attempted. The whole
deliverable is the handover document. Gantry stopped for this reason: {{STOP_REASON}}
"""

[[patterns.write_handover.steps]]
type = "stop"
note = "The task ended on an engine-forced stop."