Hyperbrief
Full spec (AI-readable): Hyperbrief.md →
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.
The problem Hyperbrief solves
What Hyperbrief is
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.
The core idea
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 five steps inside
The 5-stage pipeline
Should we even ask?
Trigger rubric
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.
Telling the truth about what you don't know
Epistemic honesty
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.
A layout that helps you actually think
Cognitive debiasing
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.
Can you take it back if it's wrong?
Reversibility-first governance
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.
Learning from how it actually played out
Post-decision learning 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.
Empirical validation — applied to itself
Self-applied dogfood — two entries
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).
Determinism is the key invariant
Determinism — 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.
Install
Add the EstreGenesis marketplace to Claude Code. You only need to do this once per machine.
/plugin marketplace add SoliEstre/EstreGenesisInstall the Hyperbrief plugin from the marketplace.
/plugin install hyperbrief@estregenesis-pluginsExample prompts
When you are losing track of what is being decided, ask for a Hyperbrief at the simplest tone (L1.1.1 — general audience, full sentences, no jargon). The 9-section brief lays out situation, options, recommendation, and risks cleanly.
I'm having trouble following this — give me a Hyperbrief at L1.1.1 (the simplest tone profile).Use cases — five situations where Hyperbrief steps in
Use cases — five trigger scenarios
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).
Reshaping how separate services connect to each other
Cross-service refactor (microservice boundary change)
When this happens: A change touches connection points between several services.
When this happens: Inter-service contract change; blast radius exceeds single service.
- Suggest the change.
- Run trigger check. Total score = 7 → full brief.
- Full sheet with hidden assumptions + pre-mortem.
- Decision tree, undo question first.
- User accepts. Decision saved with lineage.
- Propose the refactor (AuthModule extraction).
- Trigger check (sum=7) → FULL_HYPERBRIEF routing.
- §4 assumptions + §5d pre-mortem + §2 blast-radius enumerated.
- §7 decision tree: strangler / feature flag / big bang.
- decision_ledger_append stores decision_id + parent link + branch.
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.
Switching the live database the product runs on
Production database migration (irreversible infra swap)
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.
- Suggest migration plan.
- Trigger check: max score + must-trigger fires.
- §0 shows "one-way" in red. Acceptance checkbox required.
- §5b: undo window, cost breakdown, what to watch for.
- §5c table compares 4 paths across cost + capacity + risk.
- §8: conditional recommendation, confidence 0.72.
- §9: review at day 30, full archive saved.
- Propose PostgreSQL → Aurora migration.
- Trigger check: sum=12 + must-trigger #4 → mandatory FULL.
- §0 one-way banner + §6 hard checkbox gate.
- §5b rollback panel + §5c MCDA (4 paths × 4 criteria).
- §8 conditional, confidence 0.72.
- §9 review_at=+30d + hyperbrief-revisit auto-rehydration.
Outcome: explicit one-way gate, active acceptance, tracked at review.
Outcome: §0/§6 layered gate, no implicit consent path, 30d auto-rehydration.
Bringing in an outside service the product will rely on
Third-party SaaS / API integration
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.
- Suggest the integration.
- Trigger check spots external-party + notification rules.
- §2 lists external parties + Hyrum flag set.
- §4d records rejected alternatives.
- §5d pre-mortem: outage + rate-limit scenarios.
- §7: SLA gate question routes the choice.
- §8 recommendation + SLA excerpt attached.
- Propose Stripe integration (webhook + idempotency-key flow).
- Trigger check: must-trigger #2 + #3 → FULL.
- §2 affected_parties + hyrum_flag=true.
- §4d rejected_alternatives with rejection_reason.
- §5d outage + rate-limit + detection_signal.
- §7 SLA gate prunes branches.
- §8 recommendation 0.86 + §10 SLA excerpt artifact.
Outcome: external parties named, SLA explicit, fallback plans clear, vendor notified automatically.
Outcome: type-discriminated externals + explicit SLA + detection-signal fallbacks + scheduled vendor notification.
Planning how to change the shape of saved data
Schema migration (column split with rollout strategy choice)
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.
- Suggest data-format change.
- Trigger check: total = 8 → full brief.
- §3 compares 4 rollout paths; big-bang requires justification.
- §5c table: 4 paths × 5 criteria with reasons.
- §7 tree: capacity question prunes options.
- §8: conditional recommendation, confidence 0.79.
- §9: review at day 10 + day 45.
- Propose column split with legacy-parse rule.
- Trigger check: sum=8 → FULL.
- §3 gate enforces big-bang justification or §8 tentative downgrade.
- §5c MCDA: 4 paths × 5 criteria.
- §7 capacity-gate root prunes branches.
- §8 conditional 0.79; capacity uncertainty noted.
- §9 review_at=[+10d, +45d] + archive captures incidents.
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.
Pushing an emergency fix while a live problem is happening
Incident hotfix (revert + AUTONOMOUS_DECIDE routing)
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.
- Suggest undoing the recent change.
- Trigger check: total = 1 → AI decides on its own.
- AI applies + 1-line post. No ceremony.
- Exception: externally visible change → MINIMAL_BRIEF (essence + reversibility + 24h review only).
- hyperbrief-revisit helper reopens at 24h.
- If damage shows up, escalates to full decision tree for "undo the undo".
- Propose git revert abc123 + redeploy.
- Trigger check: sum=1 → AUTONOMOUS_DECIDE; no FULL.
- Agent applies + 1-line post + autonomous_record stored.
- Exception: must-trigger #2 overrides → MINIMAL_BRIEF (essence + reversibility + 24h-review).
- hyperbrief-revisit @+24h rehydrates with outcome prompt.
- Verified → close; damage → FULL escalation with parent_decision_id back-link.
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.
Where the spec lives
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.
Want to read more?
Read the full spec
The full Hyperbrief.md rulebook is in the EstreGenesis repository.