> ## Documentation Index
> Fetch the complete documentation index at: https://hibi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows: When to Run Which Hibi Command

> Eight moments, each with the one command that answers it: trust-check, post-change check, blast radius, grounding audit, plan gating, triage, document consolidation, orphan recovery.

Each section is a moment, the command for it, and what to do with the result. The same flows appear as an agent playbook with raw JSON in the [skill cookbook](https://github.com/npupko/hibi/blob/main/plugins/hibi-cli/skills/hibi/references/cookbook.md).

Running example: `src/retry.ts` (`MAX_ATTEMPTS = 5`), `src/auth.ts` (`TOKEN_TTL_MIN = 30`), a `README.md`, and a `CLAUDE.md` that says "Auth tokens expire after 30 minutes."

## 1. Trust-check before following an instruction file

```sh theme={null}
hibi check --doc CLAUDE.md
```

Exit 2 means a sentence in the file no longer matches the code. `doc: unchanged`, `code: changed` means the sentence is intact and the code moved. Do not act on that sentence as written. The verdict's `remediation.recommended` is `update-claim`: rewrite the sentence if it is now wrong, then run `hibi reanchor <id>`.

## 2. Keep docs honest in the same PR as the code change

```sh theme={null}
hibi check --since origin/main
```

Only claims touching a file changed since the ref are evaluated. `changedFiles` lists the files; `documents` names the docs whose sentences the edit invalidated. Fix the prose in the same PR. `--explain` adds `evidence.changedEvidence` when the one-line `changed` field is not enough. An unknown ref exits 1.

## 3. See the blast radius before you refactor

```sh theme={null}
hibi list --path src/auth.ts
```

One row per claim anchored to that path on either side, with `claimId`, `text`, `documentPath`, `codePath`, `status`, `severity`, `enforcement`, `recommended`, and `side`. Keep the ids: after the edit you `reanchor` the claims still true and `retire` the ones now wrong.

## 4. Go from zero to protected on an existing repo

```sh theme={null}
hibi init
hibi coverage --doc README.md
```

`coverage` splits the document into sentence-level regions and reports each as covered or uncovered, with a `coverageRatio`. Hibi does not extract claims from prose. For each uncovered region, either record a claim (a code span backs the sentence) or remove the sentence (nothing does). Record the grounded set in one batch:

```sh theme={null}
echo '[{"doc":"README.md","docQuote":"Requests are retried up to 5 times before failing.",
        "codeFile":"src/retry.ts","codeQuote":"MAX_ATTEMPTS = 5","verified":true}]' \
  | hibi record --from-file -
```

The batch is validated before any write; a bad item fails the whole batch. New claims are enforced by default; pass `"suggest": true` for an advisory claim. Re-run `coverage` to confirm the ratio rose, then `hibi check`.

## 5. Verify built code against a plan

```sh theme={null}
hibi coverage --doc plan.md --fail-uncovered
```

Exit 2 while any region of the plan is uncovered, 0 once every region is backed by a claim. A sentence you cannot anchor to code is an unimplemented plan item. Give behavioral promises a `--verifier command:"…"` and prove them with `hibi check --run-verifiers`.

## 6. Triage

```sh theme={null}
hibi list --state gating
```

One row per gating claim, most severe first. Act on each row's `claimId`: `hibi reanchor <id>` if the sentence still holds, `hibi retire <id>` if it is obsolete. Other filters: `warning`, `clean`, `orphaned`, `suggested`, `stranded` (live on a superseded or archived doc), `duplicate` (a sentence claimed more than once). `--ids-only` prints bare ids for a shell loop.

## 7. Consolidate a document and bring its claims along

```sh theme={null}
hibi supersede --from docs/old.md --to docs/merged.md
```

Authors the `supersedes` edge, flips the old document to `superseded`, and relocates every live claim whose sentence appears verbatim in the new document. Claims whose sentence was reworded or cut come back in `misses`; `strandedClaims` lists what is still on the old document. Resolve each miss with `hibi reanchor <id> --doc docs/merged.md --doc-quote "…"` or `hibi retire <id>`. When `strandedClaims` is empty, delete or `archive` the old file. Add `--dry-run` to preview.

## 8. Recover an orphaned claim

```sh theme={null}
hibi reanchor asrt_1a2b3c --suggest
hibi reanchor asrt_1a2b3c --doc docs/retry.md --doc-quote "Retries are capped at 5 attempts"
```

`--suggest` is read-only. It ranks candidate locations for the stored doc quote across every registered document and for each code quote across files in the same language; each candidate has `side`, `file`, `start`, `end`, `similarity`, `snippet`. Reanchor to the one you pick with an explicit span. `reanchor` refuses to proceed on a side that was not found unless you pass a new span for it. If no candidate fits, `hibi retire asrt_1a2b3c`.

## How to respond to a flag

Every suspect verdict carries a [remediation menu](/verdicts#the-remediation-menu). Read `recommended`, run its `command`, or do the prose work its `title` names. Do not rewrite a sentence to make a banner go away; re-verify, then act.