gemba-ask

Documentation

Overview

gemba-ask is the skill-authoring sentinel for surfacing operator attention from inside a dispatched session (gm-97w7.1). A Coach or Manager skill instructs the agent to call this binary whenever it wants to raise a question or a blocker:

gemba-ask --kind question --role coach   --text "Default to test key or fail hard?"
gemba-ask --kind blocker  --role manager --text "Need STRIPE_SECRET_KEY in env."

The binary writes one Hook="GembaAsk" Frame to ~/.gemba/sessions/<session_id>.jsonl. The bridge tailer reads it, the translator emits an escalation_opened event with the kind / channel / urgency already stamped, and the native OrchestrationPlane's escalation index surfaces it on /api/escalations.

Why a CLI (not transcript scraping, not an MCP tool):

• Mirrors the gemba-state pattern already proven in this codebase. Same frame layout, same tailer, same one-file-write-per-invocation simplicity.
• Structured capture at emit time — no markdown parsing, no format drift risk.
• Works for any coding agent with shell access; not bound to Claude's transcript.jsonl layout.
• MCP tool variant (in-process Agent SDK server) is a natural follow-up using the same kind/channel/urgency shape.

Design invariants (mirrors gemba-state / gemba-bridge):

• Zero state, zero network, one file write per invocation.
• Any failure goes to stderr + exit 1 so the operator sees the problem directly (this binary is user-facing, not in a hook chain).
• Frame shape MUST stay in lock-step with internal/adapter/native/bridge/frame.go Frame.