pathfind

Pathfinding — Symptom-to-Direction Discovery

Pathfind always produces a ranked direction list and hands off to /preplan. This is the defining contract.

Step 1 — Intake

Parse the user's problem descriptions from args.

• Clarification guardrail: If fewer than 2 concrete symptoms are identified, ask clarifying questions. Max 2 clarification rounds, then proceed with caveats noted in the artifact.

• Derive {topic} from the user's input as English kebab-case (e.g. "API slow, DB limits, user complaints" -> api-performance)

• Create artifact file: CORAL_PROJECT/plans/pathfind-{topic}.md with header:

  # Pathfind: {topic}
  
  ## Problems
  [User's original problem descriptions]
  

Step 2 — Triage

Cluster related problems by shared patterns, systems, or root cause indicators.

• Group symptoms that likely share a common cause
• Identify cross-cutting symptoms that appear in multiple clusters
• Single-symptom input: treat as one cluster, note limited clustering in artifact

Write to artifact:

## Problem Clusters
| Cluster | Symptoms | Pattern |
|---------|----------|---------|
| {name}  | {list}   | {shared pattern or system} |

Step 3 — Investigate

Bug detection: Before investigation, check for bug-type symptoms:

• Detection: symptoms containing error output, stack traces, or "X crashes/fails when Y"
• If bug-type symptoms found:
  • Suggest: "These symptoms look like code bugs — consider /analyze or /bugfix for: {bug symptoms}"
  • If all symptoms are bugs: exit with delegation suggestion
  • If mixed: continue pathfind with remaining non-bug symptoms

Investigation path — choose based on whether relevant code exists:

A. Codebase exists (clusters reference existing systems, files, or modules):

Agent({ subagent_type: "coral:scanner",
  prompt: "Investigate these problem clusters using Approach B (Process Investigation).
    Scope: systems and modules related to these clusters only — do NOT perform a full project scan.
    Clusters: {cluster list with symptoms}
    Work dir: {work_dir}
    Output: root cause candidates per cluster with file:line evidence." })

If scanner fails: retry once, then proceed with direct codebase reads.

B. No codebase / process-only problems (clusters are about workflow, team, tooling, or greenfield): Skip scanner. Pathfind derives root causes directly from triage clusters through reasoning. Use web search for prior art if the problem domain is unfamiliar.

Map findings to problem clusters — derive root causes:

• Each root cause must trace back to one or more clusters
• Each root cause must have evidence (file:line, observation, or reasoning chain)

Write to artifact:

## Root Causes
| # | Root Cause | Source Cluster | Evidence |
|---|-----------|----------------|----------|

Step 4 — Prescribe

Generate directions through orthogonal lanes — one direction per lane, not multiple per root cause. Lanes guarantee divergence because each forces a different mechanism.

Derive lanes from the problem domain. Each lane must represent a fundamentally different mechanism — not a variation. Aim for 3-5 lanes.

Examples by domain:

Code/architecture problems:

Lane	Perspective
local_repair	Minimal in-place fix, no architectural change
boundary_redesign	Move responsibility across interfaces or ownership lines
representation_change	Change state, data model, or information shape
probe_first	Add instrumentation or experiments before committing to a fix
workflow_guardrail	Solve via tests, process, tooling, or validation