# Design: mem:reason fail-fast on insufficient graph depth

## Problem

When mem:reason is called on a topic with insufficient knowledge graph coverage, it runs the full pipeline and returns UNCERTAIN with irrelevant evidence. The user wastes a reason call and gets nothing actionable.

Example: asking about GitHub account migration when the graph only has VPS deploy beliefs. The reason command returned 10 seed beliefs, 0 paths, and 4 impasses -- all about deploy paths, none about GitHub accounts.

## Desired behavior

1. **Early detection**: Before running full reason pipeline, check if the graph has sufficient coverage for the query topic. Metrics to check: seed relevance scores, topic overlap, path count from initial probe.

2. **Fail-fast protocol**: If coverage is insufficient, abort early with a structured signal:
   - What was searched for
   - What the graph actually contains in that area
   - Which specific gaps were identified
   - Suggested actions (run wonder, ingest docs, observe more)

3. **Auto-route to wonder**: Option to automatically route a quick-failed reason into a wonder call that expands the knowledge graph in the direction needed to fill the identified gaps. The wonder output gets ingested, then reason retries with the expanded graph.

## Open questions

- What threshold defines "insufficient"? Seed relevance scores below X? Zero paths? All impasses?
- Should the fail-fast be a separate pre-check or integrated into the reason pipeline?
- How to prevent wonder-then-reason loops (wonder expands graph, reason still insufficient, wonder again...)?
- Should this be opt-in (--auto-expand) or default behavior?

## Real-world precedent

In the GitHub migration case, the user's workaround was orthogonal: they ingested comprehensive git documentation directly into the knowledge graph. This wasn't specifically to fill the "GitHub account management" gap -- it was also because the agent was struggling with the multi-remote git setup generally. But it's exactly the kind of lateral move a failed reason should pivot into: the graph doesn't know about X, so expand the graph in the direction of X (or the broader domain containing X) and try again.

The challenge is designing this pivot reliably. The user's intuition guided it here (ingest git docs to help with git problems). Automating that requires the system to: (1) identify the domain of the gap, (2) find or generate content that fills it, (3) ingest without polluting the graph with noise, (4) retry reason with the expanded graph. Steps 2 and 3 are where it gets hard -- wonder can research, but the quality gate for "is this worth ingesting?" is nontrivial.

## Status

Design phase. No implementation yet. Needs research (wonder) before planning.
