haft

Reasoning with /h-reason

/h-reason is the single entry point for structured engineering reasoning. Describe your problem in plain language. The agent reads your intent from context and picks the right behavior — most questions don't need a full decision cycle.

Three interaction modes

The agent assesses what you actually want before doing anything. How much it drives depends on the mode:

1. Direct response

You want structured thinking, not artifacts. The agent reasons through the problem using FPF principles and responds. Nothing is persisted — no tool calls, no decision records. 

/h-reason what are the trade-offs of gRPC vs REST
for our internal services?
/h-reason is our current auth approach sound?
what's the weakest link?

2. Research / prepare-and-wait

You want to drive the decision yourself. The agent gathers context — reads relevant code, searches existing decisions, researches the topic — and presents findings. Then it stops. You call /h-frame, /h-char, etc. when ready. 

/h-reason I want to think through our caching
strategy. Gather context and prepare for framing.
/h-reason let's reason about the database
migration before deciding anything

This is the default when intent is ambiguous. The agent never assumes you want it to drive the full cycle.

3. Delegated reasoning

You explicitly delegate. The agent runs through the five modes — Understand, Explore, Choose — and stops at Choose for the human decision. The agent generates options and compares them, but you pick. This is the Transformer Mandate: agents document, humans decide. 

/h-reason figure out the best caching approach
for our API. Run the full cycle, I'll decide.
/h-reason analyze the auth architecture problem,
go through frame/explore/compare

The agent asks for confirmation at the Choose step. After you select a variant, it records the decision and proceeds to Execute.

Why three modes: If the agent always drove the whole cycle, you'd end up rubber-stamping outputs instead of thinking. Direct response augments your reasoning. Prepare-and-wait gives you the research without the autopilot. Delegated reasoning handles the mechanical parts while preserving human judgment at the decision point.

Depth modes

When the agent enters the decision cycle (modes 2 or 3), it auto-selects a depth:

Depth When What happens
Tactical Reversible, low risk, obvious approach Understand → Explore → Execute (skip characterization, skip formal comparison)
Standard Multiple viable approaches, moderate blast radius Full 5-mode cycle: Understand → Explore → Choose → Execute → Verify
Deep Hard to reverse, security implications, cross-team impact Full cycle + rich parity rules, rollback runbook, refresh triggers

Override the depth explicitly: /h-reason deep: should we change our database?

The diagnostic conversation

Before generating options, the agent drives a diagnostic conversation in the Understand mode. Problem quality determines solution quality. The agent asks:

  1. "What observation doesn't fit?" — the signal, not the assumed cause
  2. "What have you already tried?" — avoids re-treading dead ends
  3. "What would solved look like?" — measurable acceptance criteria
  4. "What constraints are non-negotiable?" — hard limits
  5. "How reversible is this?" — determines depth mode
  6. "What should we watch but NOT optimize?" — Anti-Goodhart indicators

Answer these honestly. The better the framing, the better the variants. If you skip the diagnostic, you get generic options.

Decision record structure

A decision record (.haft/decisions/dec-XXXXXXXX-XXX.md) has four sections:

  1. Problem Frame — what triggered the decision, signal, constraints, acceptance criteria
  2. Decision — selected variant, invariants (what must always be true), pre/post conditions, DO/DON'T rules
  3. Rationale — why this and not the alternatives, comparison table, weakest link identification
  4. Consequences — rollback plan, refresh triggers, affected files, claims with verify_after dates

This file is designed for code review. Commit it alongside the code it governs. Full-cycle decisions contain enough structure to serve as test specifications — any agent can generate property-based tests from the invariants and post-conditions.

After the decision

After implementing a decision, the agent:

  1. Snapshots affected file hashes (baseline) — so drift detection can track changes later
  2. Records claims with verify_after dates — "latency stays under 100ms" verified in 2 weeks
  3. Runs measurement — records whether acceptance criteria were met

Without measurement, the decision stays in "Pending Implementation" on /h-status and on the board. Claims with passed verify_after dates surface in /h-verify scan until they're measured or waived.

When not to use it

  • Obvious bug fixes with clear solutions
  • Formatting, import ordering, variable naming
  • Anything that takes less than 5 minutes and is trivially reversible

For these, just code. If the agent notices a decision worth recording during conversation, it'll create a note automatically.

Next