h-reason

What this skill does

# Haft Reasoning — Think Before You Build

Haft helps with 5 engineering jobs: **Understand, Explore, Choose, Execute, Verify.** Plus **Note** for quick micro-decisions. This skill activates structured engineering reasoning powered by these modes.

**When to use**: any non-trivial engineering question. Architecture choices, library selection, API design, data model changes, infrastructure decisions, process changes. Also: "think about", "reason about", "evaluate", or "compare" anything significant.

**When NOT to use**: obvious bug fixes, formatting, tiny refactors with clear acceptance.

---

## Context-aware entry — how much the agent drives

**Before doing anything, assess the user's intent.** The 5 engineering modes (Understand/Explore/Choose/Execute/Verify) describe WHAT you're doing. The 4 interaction modes below describe HOW MUCH the agent drives. They're orthogonal.

### Direct response / direct action
**Trigger:** "think about X", "what do you think about X", "analyze X", "is this the right approach?", "what are our options?", "save this as md", "make this a ranked list", "turn this into a checklist", "move this to .context", "summarize what you found"

Reason through the problem or do the direct artifact work with normal tools. **Do not call Haft MCP tools** unless the user explicitly asks to persist something. "Use FPF in your thinking" means reasoning discipline, not artifact workflow.

### Research / prepare-and-wait
**Trigger:** "/h-reason [topic], prepare for framing", "let's think about X before deciding", "I want to reason through X"

Gather context (read code, search existing decisions, research). Present findings. **Stop and wait** for the user to decide the next step.

### Delegated reasoning
**Trigger:** "/h-reason [topic], go ahead", "work through the options and bring me a recommendation", natural-language delegation like "do it" / "go ahead"

Drive frame → explore → compare in one pass. **Do not stop after frame. Do not require a manual `/h-explore` or `/h-compare` step.** Stop after compare, show the Pareto front, and ask the human to choose. The Transformer Mandate applies at the Choose → Execute boundary: the agent may frame/explore/compare when delegated, but the human still chooses before `/h-decide`.

### Autonomous execution
**Trigger:** "/h-reason [topic] and implement" ONLY when autonomous mode is already enabled for the session (Ctrl+Q / interaction=autonomous).

Full cycle including decide + implement without pauses. If autonomous mode is OFF, phrases like "figure out the best approach and do it" or "fix everything" are NOT enough to skip the compare → decide pause. Treat them as delegated reasoning.

**If unclear:** default to research / prepare-and-wait. Never default to autonomous execution.

---

## What you have

### Haft tools (MCP) — persist reasoning as artifacts

| Tool | What it does | Slash command |
|------|-------------|---------------|
| `haft_note` | Record micro-decisions with rationale validation | `/h-note` |
| `haft_problem` | Frame problems and persist characterization dimensions on the ProblemCard | `/h-frame`, `/h-char` |
| `haft_solution` | Explore variants, compare and identify Pareto front | `/h-explore`, `/h-compare` |
| `haft_decision` | Decide with formal rationale; record measurement results | `/h-decide` |
| `haft_commission` | Create/list/claim WorkCommissions for execution harnesses | `/h-commission` |
| `haft_refresh` | Detect stale decisions, manage lifecycle | `/h-verify` |
| `haft_query` | Search, status dashboard, file-to-decision lookup, FPF spec lookup, deterministic audience projections | `/h-search`, `/h-status`, `/h-view` |

### FPF spec lookup — prefer MCP when available

```text
haft_query(action="fpf", query="A.6")
haft_query(action="fpf", query="How do I route boundary statements?", limit=3, explain=true)
haft_query(action="fpf", query="Boundary Norm Square", full=true)
```

In shell-only environments: `haft fpf search "<query>"` with optional `--full`.

---

## Feature maturity

**Computed:** Pareto front (non-dominated set from comparison data), Refresh (valid_until expiry detection).
**Tracked (persisted but not computed):** problem framing, characterization dimensions, WLNK label on variants, stepping-stone flag, CL on evidence, measurement records.
**Textual (stored as rules, not enforced):** parity plan — you ensure it yourself.

**Key rule:** don't describe textual features as if they compute something. "WLNK bounds quality" means the user identified what bounds quality, not that the system calculated it. These skill instructions are **L1 — detection and questions**; the tools (L2) persist and enforce. Don't treat a prompt-based check as verified evidence.

---

## The 5 engineering modes

### Understand — "What's actually going on?"

Frame before solving. Problem quality dominates solution speed in outcome.

**Framing protocol — ask these questions before recording:**

1. **"What observation doesn't fit?"** — the signal, not the assumed cause. "Webhook retries hit 15%" not "we need a new queue."
2. **"What have you already tried?"** — avoids re-treading dead ends.
3. **"Who owns this problem?"** — a specific person with authority, not "the team."
4. **"What would solved look like?"** — measurable acceptance, not "it should be better."
5. **"What constraints are non-negotiable?"** — hard limits no variant can violate.
6. **"How reversible is this? What's the blast radius?"** — determines depth (tactical vs standard vs deep).
7. **"What should we watch but NOT optimize?"** — Anti-Goodhart indicators.

**Problem typing:** Before exploring, classify:
- **Optimization** — working system, want it better on a known dimension
- **Diagnosis** — something's broken, don't know why
- **Search** — need to find something that doesn't exist yet
- **Synthesis** — need to combine existing elements into something new

Each type suggests different exploration strategies and ceremony levels.

**Language precision triggers:**
- If the signal uses ambiguous terms (service, process, function, quality, component), **unpack to precise meaning before recording.** "Which service — the OAuth provider, the token endpoint, or the session store?"
- If the user says "it should do X," clarify: **hard constraint, preference, or observation?**
- If two stakeholders use the same word differently, resolve before framing.

**Characterization:** Define the **characteristic space** before evaluating options.
- State the **selection policy BEFORE seeing results**
- Ensure **parity** — same inputs, same scope, same budget across all options
- Keep it **multi-dimensional** — never collapse to a single score unless the fold is explicit

**Persist with:** `haft_problem(action="frame")`, `haft_problem(action="characterize")`
**Commands:** `/h-frame`, `/h-char`
**Goldilocks check:** When multiple problems are active, use `haft_problem(action="select")` to pick the one in the growth zone.

### Explore — "What are the real options?"

- **>=2 variants** that differ in **kind**, not degree (3+ preferred)
- Each variant gets a **weakest link** label — what bounds its quality
- Mark **stepping stones** — options that open future possibilities even if not optimal now

**Diversity self-check:** Before submitting variants, verify they aren't disguised copies of the same approach. If all variants are cache-based, at least one should explore a genuinely different direction (e.g., restructure data flow to eliminate caching need).

**Hypothesis discipline:** When investigating during exploration, separate what you observe from what you hypothesize. State hypotheses explicitly. "I observe high latency on the /auth endpoint. Hypothesis: the bottleneck is the token validation call, not the database query."

**Past solutions:** Use `haft_solution(action="similar")` to search for relevant precedents from past or cross-project work.

**Persist with:** `haft_solution(action="explore")`
**Command:** `/h-explore`

### Choose —