Level
Style

Hyperbrief

A rulebook for the moment when AI asks you to decide.

A decision-delegation gating discipline — trigger rubric + schema-enforced JSON IR + deterministic Node renderer.

A decision-delegation gating discipline distilled from a 6-axis deep-research synthesis.

v0.6.0 9-section IR + BlockedStub v0.6 4 slots: lenses + methodology + maturity_anchor + term_pairing 26 anti-patterns 4 dogfood + 2 adopter reports v1.0 readiness rubric (§11.5) 4 MCP tools + hooks Apache-2.0

The problem Hyperbrief solves

What Hyperbrief is

Overview

When the AI says "you decide" but doesn't give you what you need to decide — that's the gap. Hyperbrief is the rule that fixes it.

A decision-delegation gating discipline. Trigger rubric → schema-validated JSON IR → deterministic renderer → 9-section MD + interactive HTML. 3-axis × 5-level tone profile with floor-fallback.

A decision-delegation gating discipline distilled from a 6-axis synthesis. 5-stage pipeline + schema-enforced JSON IR + deterministic renderer separation as the reproducibility anchor.

The core idea

Central thesis

Central thesis

An AI agent's job is to block the manufacture of decisions, not to manufacture them for you.

The principal failure mode is the sycophantic over-delegation loop. Hyperbrief is a two-sided gate blocking both unnecessary and unstructured delegation.

The principal failure mode is the sycophantic over-delegation loop. Hyperbrief is the structural defence — a two-sided gate.

The five steps inside

The 5-stage pipeline

The five formally specified stages

§2 stage 1

Should we even ask?

Trigger rubric

Trigger rubric (4-score + MUST-triggers)

A quick check decides if the decision is worth asking about. Small and reversible? AI decides and tells you. Serious? Full brief.

4-score escalation + 5 MUST-trigger conditions. Routes to AUTONOMOUS_DECIDE or FULL_HYPERBRIEF.

4-score escalation rubric + 5 MUST-triggers. Two-sided gate routing function.

§5 stage 2

Telling the truth about what you don't know

Epistemic honesty

Epistemic-honesty surface (4-tier tags + falsification)

Every factual statement carries a tag: verified / inferred / assumed / unknown. Every recommendation comes with a falsifier.

4-tier epistemic tags inline on every fact assertion + falsification trigger on every recommendation.

Inline 4-tier epistemic tags + falsification trigger as mandatory triple. Unfalsifiable claims weighted at zero.

§5.6 + §7 stage 3

A layout that helps you actually think

Cognitive debiasing

Cognitive-debiasing layout (framing balance + active choice)

A layout that defends against common thinking mistakes. Both sides of every choice + explicit confidence + always an option to reject the question itself.

Structural debiasing at multiple layers: framing matrix (§5a), meta-branch (§7), numerical CI (§8), active-choice gate, and a 3-axis × 5-level tone profile.

Structural debiasing across IR layers — framing matrix, 4-option meta-branch, numerical CI, active-choice gate, 3-axis Likert tone profile, tone-floor fallback affordance.

§0 + §8 stage 4

Can you take it back if it's wrong?

Reversibility-first governance

Reversibility-first governance (RAPID + Cynefin + lexicographic priority)

Before details, you see if the decision is reversible. Green = easy. Yellow = costly. Red = one-way (requires an explicit acceptance checkbox).

§0 Decision Header declares reversibility class + badge colour + RAPID + Cynefin before content. Irreversibility-acceptance checkbox for one_way decisions.

§0 declares reversibility class + RAPID + Cynefin before content. Active-choice gate for one_way decisions.

§9 stage 5

Learning from how it actually played out

Post-decision learning loop

Post-decision learning loop (lineage + revisit + Brier loop)

Every decision saved with a revisit date and a full archive (brief + your follow-up questions + decision). Months later you can audit the prediction.

§9 registers revisit_date + ledger_pointer at emit time. archive_config (default ON) bundles 5 elements as a load-bearing development record.

§9 registers revisit_date + ledger_pointer at emit. archive_config bundles 5 load-bearing elements. Brier-score increments recorded against original confidence.

Empirical validation — applied to itself

Self-applied dogfood — two entries

Empirical validation by self-application

The discipline has been applied to its own design decisions. Two entries: ship the module + ship the converter. Both surfaced spec gaps, both folded back in.

2 entries archived. Entry 01 = v0.1 ship decision (5 patches folded back into v0.1.1). Entry 02 = Phase 2 renderer (shipped at v0.4.0, MCP deferred to v0.4.1).

2 self-applied entries. Entry 01 = v0.1 ship (5 patches into v0.1.1). Entry 02 = Phase 2 renderer (mini-engine + ajv + CLI at v0.4.0, MCP deferred). 3 v0.5 schema candidates surfaced.

Determinism is the key invariant

Determinism — load-bearing invariant

Determinism as load-bearing invariant

Same input → same output. The smoke test confirms byte-identical output every run.

Same IR + same options → byte-identical output. Canonical IR hash via stable JSON with sorted keys at every depth. Smoke-test verified.

Determinism is constitutive of §7. Canonical IR hash via depth-uniform sorted-key JSON. Smoke-harness verified. drift-log enables Phase 1 ↔ Phase 2 cross-validation.

Try it yourself

Install the plugin

Plugin deployment

Add Hyperbrief as a Claude Code plug-in. Two commands. Bundle: 3 helpers + renderer + small tool-connection server (4 tools).

Hyperbrief ships as a Claude Code plugin with embedded MCP server. v0.5.2 needs single npm dep (ajv) + 0 mandatory env. 4 MCP tools exposed.

Hyperbrief ships as a Claude Code plugin with embedded MCP server. v0.5.2 install-ready.

# Add the EstreGenesis plug-in marketplace (the catalog the plug-in comes from):
/plugin marketplace add SoliEstre/EstreGenesis

# Install the Hyperbrief plug-in:
/plugin install hyperbrief@estregenesis-plugins

# Optional setting — where the decision log file is kept (default: .agent/_decisions/hyperbrief-ledger.jsonl):
HYPERBRIEF_LEDGER_PATH=/path/to/hyperbrief-ledger.jsonl

No outside real-time server (WebSocket) needed. Optional combinations: Constellation (decision cards on live dashboard) + Superscalar (parallel lanes auto-checked at finish).

v0.5.3 adds advise-mode PreToolUse + Stop hooks with a 4-way review-queue routing tree (Constellation board / standalone placeholder / setup-ask / silent). Adds silent-skip detection on top of model-invoked SKILL.md; does NOT replace it.

Use cases — five situations where Hyperbrief steps in

Use cases — five trigger scenarios

Use cases — five canonical trigger scenarios across the 4-score escalation spectrum

When Hyperbrief checks a decision, which commands are used, and what the person sees.

Five trigger-routing scenarios spanning score 1 (AUTONOMOUS_DECIDE) to score 12 + must-trigger (mandatory FULL).

Five canonical scenarios spanning the 4-score escalation tree + must-trigger override family. Each card maps to a specific routing outcome: standard FULL, mandatory FULL with §0 banner, Hyrum-flagged FULL, §3-gated FULL with tentative-downgrade, and AUTONOMOUS_DECIDE with MINIMAL_BRIEF exception.

Reshaping how separate services connect to each other

Cross-service refactor (microservice boundary change)

Cross-service architectural refactor (sum=7, standard FULL routing)

When this happens: A change touches connection points between several services.

When this happens: Inter-service contract change; blast radius exceeds single service.

When this happens: Inter-service contract mutation, cross-module dependency, or out-of-blast-radius sign-off requirement. Typical 4-score sum=7; must-trigger #1 may fire orthogonally.

  1. Suggest the change.
  2. Run trigger check. Total score = 7 → full brief.
  3. Full sheet with hidden assumptions + pre-mortem.
  4. Decision tree, undo question first.
  5. User accepts. Decision saved with lineage.
  1. Propose the refactor (AuthModule extraction).
  2. Trigger check (sum=7) → FULL_HYPERBRIEF routing.
  3. §4 assumptions + §5d pre-mortem + §2 blast-radius enumerated.
  4. §7 decision tree: strangler / feature flag / big bang.
  5. decision_ledger_append stores decision_id + parent link + branch.
  1. Propose architectural refactor at boundary (AuthModule extraction).
  2. Trigger check yields (2,2,2,1) sum=7 ≥ threshold=4 → FULL_HYPERBRIEF routing; oneOf discriminator → FullBrief variant.
  3. §4/§5d/§2 populated per anti-pattern #7 (unknown vs checked-empty discipline).
  4. §7 tree: rollback-question root + reversibility-class annotations + big-bang requires §3 incremental-path justification.
  5. §6 acceptance → decision_ledger_append persists §9 capture (cross-seed namespace + lineage back-link + review_at).

Outcome: stakeholders + dependencies + rollback costs all in one place. Reject-framing option always available.

Outcome: stakeholders/dependencies/rollback canonicalized; §6 reject-framing meta-branch always available.

Outcome: schema-validated IR canonicalizes stakeholders/dependencies/rollback. §6 reject-framing structurally preserved per anti-pattern #14. §9 capture enables hyperbrief-revisit rehydration.

Switching the live database the product runs on

Production database migration (irreversible infra swap)

Production data-layer migration (sum=12 + must-trigger #4, mandatory FULL with §0 reversibility banner)

When this happens: A change to the core data layer that is hard to undo.

When this happens: One-way persisted-state swap; must-trigger #4 fires.

When this happens: Fundamentally one-way persisted-state mutation with post-cutover reconciliation cost + Hyrum-law coupling to new transactional semantics. must-trigger #4 forces FULL unconditionally.

  1. Suggest migration plan.
  2. Trigger check: max score + must-trigger fires.
  3. §0 shows "one-way" in red. Acceptance checkbox required.
  4. §5b: undo window, cost breakdown, what to watch for.
  5. §5c table compares 4 paths across cost + capacity + risk.
  6. §8: conditional recommendation, confidence 0.72.
  7. §9: review at day 30, full archive saved.
  1. Propose PostgreSQL → Aurora migration.
  2. Trigger check: sum=12 + must-trigger #4 → mandatory FULL.
  3. §0 one-way banner + §6 hard checkbox gate.
  4. §5b rollback panel + §5c MCDA (4 paths × 4 criteria).
  5. §8 conditional, confidence 0.72.
  6. §9 review_at=+30d + hyperbrief-revisit auto-rehydration.
  1. Propose migration with explicit logical-replication cutover plan.
  2. Trigger check saturates at (3,3,3,3) sum=12 + must-trigger #4 doubly mandates FULL; §0 reversibility-banner activates.
  3. §0 banner + §6 hard-checkbox enforced at template layer per anti-pattern #11 (no implicit one-way consent).
  4. §5b panel + §5c MCDA enforces cell.reason per anti-pattern #6 (no scored-without-justification).
  5. §8 conditional + confidence 0.72; §4 documents dominant uncertainty (vendor_response_history_slow).
  6. §9 review_at=+30d + hyperbrief-revisit rehydration + Constellation §13.16.9 Hyperbrief-card A2A event when co-deployed.

Outcome: explicit one-way gate, active acceptance, tracked at review.

Outcome: §0/§6 layered gate, no implicit consent path, 30d auto-rehydration.

Outcome: §0/§6 structurally enforced (anti-pattern #11). §9 + 30d rehydration closes the loop against §5b signals. §13.16.9 surfaces decision-card on Constellation board.

Bringing in an outside service the product will rely on

Third-party SaaS / API integration

External-party SaaS integration (must-trigger #2 + #3, Hyrum-flagged FULL routing)

When this happens: Adding an outside service with new dependencies and external promises.

When this happens: SaaS dependency with vendor-side failure modes + SLA obligations; must-trigger #2 + #3 fire.

When this happens: External-party dependency with vendor-side OPEX/SLA/incident-response + Hyrum surface area. must-trigger #2 + #3 fire orthogonally; §2 Hyrum-flag activates.

  1. Suggest the integration.
  2. Trigger check spots external-party + notification rules.
  3. §2 lists external parties + Hyrum flag set.
  4. §4d records rejected alternatives.
  5. §5d pre-mortem: outage + rate-limit scenarios.
  6. §7: SLA gate question routes the choice.
  7. §8 recommendation + SLA excerpt attached.
  1. Propose Stripe integration (webhook + idempotency-key flow).
  2. Trigger check: must-trigger #2 + #3 → FULL.
  3. §2 affected_parties + hyrum_flag=true.
  4. §4d rejected_alternatives with rejection_reason.
  5. §5d outage + rate-limit + detection_signal.
  6. §7 SLA gate prunes branches.
  7. §8 recommendation 0.86 + §10 SLA excerpt artifact.
  1. Propose Stripe integration with full transactional contract (idempotency + DLQ + backoff).
  2. must-trigger #2 + #3 fire orthogonally; trigger-rule disjunction mandates FULL per §1 routing contract.
  3. §2 affected_parties with type discrimination + checked_and_confirmed_empty discipline + hyrum_flag + hyrum_surface sub-field.
  4. §4d carries evidence_ref per rejection (anti-pattern #9 — no justification-chain-less rejection).
  5. §5d failure_modes with mandatory detection_signal + mitigation per schema.
  6. §7 domain-state gate (signed_sla_exists) sourced from §2; per §7 contract — domain-state gates required, not just generic axes.
  7. §8 recommendation 0.86 + §10 sla_excerpt artifact + Constellation §13.16.9 DECISION_REQUEST to legal-team agent when co-deployed.

Outcome: external parties named, SLA explicit, fallback plans clear, vendor notified automatically.

Outcome: type-discriminated externals + explicit SLA + detection-signal fallbacks + scheduled vendor notification.

Outcome: type+SLA-flag-discriminated externals, explicit §8 SLA tier, §5d detection+mitigation pairs, hyrum_flag-activated Hyrum-surface discipline. §9 schedules vendor notification; §13.16.9 auto-routes legal-team sign-off when Constellation co-deployed.

Planning how to change the shape of saved data

Schema migration (column split with rollout strategy choice)

Persisted-schema mutation (sum=8 + §3 incremental-path gate, tentative-downgrade discipline)

When this happens: A data-format change affecting already-saved data, with several rollout strategies to compare.

When this happens: Schema mutation with multiple rollout strategies; reader/writer must stay coordinated.

When this happens: Schema mutation on reversibility-vs-velocity Pareto frontier with rollback/capacity/consistency profiles. §3 incremental-path gate + anti-pattern #12 tentative-downgrade enforced.

  1. Suggest data-format change.
  2. Trigger check: total = 8 → full brief.
  3. §3 compares 4 rollout paths; big-bang requires justification.
  4. §5c table: 4 paths × 5 criteria with reasons.
  5. §7 tree: capacity question prunes options.
  6. §8: conditional recommendation, confidence 0.79.
  7. §9: review at day 10 + day 45.
  1. Propose column split with legacy-parse rule.
  2. Trigger check: sum=8 → FULL.
  3. §3 gate enforces big-bang justification or §8 tentative downgrade.
  4. §5c MCDA: 4 paths × 5 criteria.
  5. §7 capacity-gate root prunes branches.
  6. §8 conditional 0.79; capacity uncertainty noted.
  7. §9 review_at=[+10d, +45d] + archive captures incidents.
  1. Propose schema mutation with forward+backward compatibility + deterministic legacy-parse + rate-limited backfill.
  2. Trigger check yields (2,2,2,2) sum=8 ≥ threshold=4 → FULL_HYPERBRIEF; no must-trigger fires; oneOf → FullBrief.
  3. §3 incremental_path_gate enforces gradual_path_infeasibility_rationale (falsifiable) or template-time tentative-downgrade per anti-pattern #12.
  4. §5c MCDA: 4×5 with cell.reason + Pareto-tagging per anti-pattern #15.
  5. §7 capacity-gate root sourced from §2; gates reflect domain state per §7 contract; infeasible branches pruned pre-§8.
  6. §8 conditional 0.79; team_capacity dominant uncertainty per §4; capacity-check failure routes to §9 re-eval.
  7. §9 dual review_at=[+10d, +45d] + hyperbrief-revisit rehydration + Constellation §13.16.9 Hyperbrief-card events at both checkpoints when co-deployed.

Outcome: all 4 paths compared, tentative flag if big-bang unjustified, capacity check gates progress.

Outcome: §5c scores all 4 paths; §3-unjustified big-bang → §8 tentative; capacity hard-gate.

Outcome: §5c scores all 4 paths with Pareto-tagging; §3 + anti-pattern #12 enforce template-time tentative-downgrade; §7 prunes pre-§8; conditional §8 + dual §9 + §13.16.9 close the loop.

Pushing an emergency fix while a live problem is happening

Incident hotfix (revert + AUTONOMOUS_DECIDE routing)

Incident response hotfix (sum=1 → AUTONOMOUS_DECIDE, Hyrum-override exception → MINIMAL_BRIEF)

When this happens: Immediate action while a live problem is happening; long-term effects unclear.

When this happens: Live-incident hotfix in Cynefin chaotic; AUTONOMOUS_DECIDE + 24h auto-review.

When this happens: Cynefin chaotic-domain regime + structurally low-risk action → sum=1 ≪ threshold=4 → AUTONOMOUS_DECIDE bypasses §1 FullBrief; §6 24h-auto-review converts hindsight to record post-incident.

  1. Suggest undoing the recent change.
  2. Trigger check: total = 1 → AI decides on its own.
  3. AI applies + 1-line post. No ceremony.
  4. Exception: externally visible change → MINIMAL_BRIEF (essence + reversibility + 24h review only).
  5. hyperbrief-revisit helper reopens at 24h.
  6. If damage shows up, escalates to full decision tree for "undo the undo".
  1. Propose git revert abc123 + redeploy.
  2. Trigger check: sum=1 → AUTONOMOUS_DECIDE; no FULL.
  3. Agent applies + 1-line post + autonomous_record stored.
  4. Exception: must-trigger #2 overrides → MINIMAL_BRIEF (essence + reversibility + 24h-review).
  5. hyperbrief-revisit @+24h rehydrates with outcome prompt.
  6. Verified → close; damage → FULL escalation with parent_decision_id back-link.
  1. Propose canonical chaotic-domain action (git revert + redeploy to T-2h artifact) per Cynefin act→sense→respond.
  2. Trigger check yields (1,0,0,0) sum=1 ≪ threshold=4, no must-trigger → AUTONOMOUS_DECIDE per §1; §1 FullBrief structurally not emitted.
  3. Agent applies + 1-line emit; decision_ledger_append persists lightweight autonomous_record for parent_decision_id lineage.
  4. Hyrum-override (must-trigger #2 post-hoc) overrides AUTONOMOUS → MINIMAL_BRIEF per §5.7 chaotic template: {essence, reversibility_class, scheduled_review_at+24h} only.
  5. hyperbrief-revisit @+24h prompts outcome_observation; autonomous_record + outcome = §9-equivalent capture.
  6. Verified-no-impact → close; damage → FULL escalation with parent_decision_id back-link; anti-pattern #17 preserves hindsight despite chaos.

Outcome: incident unblocked, 24-hour review converts hindsight to a record.

Outcome: AUTONOMOUS keeps incident unblocked; Hyrum-override → MINIMAL gates without ceremony; 24h-revisit → §9-equivalent record; damage path → FULL escalation with lineage link.

Outcome: AUTONOMOUS keeps incident unblocked per Cynefin chaotic budget; Hyrum-override → MINIMAL gates externals per anti-pattern #18; 24h-revisit → §9-equivalent record; damage → FULL escalation with parent_decision_id lineage; anti-pattern #17 satisfied by autonomous_record + scheduled_review pairing.

Where the spec lives

Adoption

Adoption

Full rulebook in Hyperbrief.md. Plug-in bundles 3 helpers + data format + templates + renderer + external-tool server. The two other modules (Constellation + Superscalar) combine with it. Cross-project name-prefix rule keeps records separate.

SSoT at Hyperbrief.md (root, sibling to Constellation/Superscalar). Plugin bundles 3 skills + schema + 4 templates + renderer + 4-tool MCP + CLI. Constellation §13.16.9 + Superscalar §3.1 integrations both shipped. Cross-seed namespace discipline per §11.3.

SSoT at Hyperbrief.md. Plugin bundles all components. Constellation §13.16.9 + Superscalar §3.1 cross-module integrations fully shipped. EstreUF cross-seed adoption per §11.3. Bundle 008 = empirical validation.

Want to read more?

Read the full spec

Reference the full specification

The full Hyperbrief.md rulebook is in the EstreGenesis repository.

github.com/SoliEstre/EstreGenesis/blob/main/Hyperbrief.md →