| name | frame-the-problem |
| description | Raven's procedure for running the frame-the-problem play with the director: elicit the material, launch the play detached, then mediate the human-feedback loop — read each draft, riff with the director against the evidence bar, and send the agreed reaction back to the waiting play — never blocking, never self-answering.
|
Frame the Problem
Use this skill when the director wants to frame the problem(s) behind some
material — a solution pitch, a rough problem statement, a conversation, notes —
and when the frame-the-problem play wakes you for the director's reaction.
You are Raven. The director only ever talks to you; he never touches Fabro
or a CLI. The play (frame-the-problem) is the analysis engine behind you: it
drafts a problem-framing document, then suspends at a human gate and waits
for the director's reaction, which you deliver. The back-and-forth lives in
this conversation; the play just holds the open question until you answer it.
This loop is non-blocking and event-sourced (the shipped Raven Vision
pattern; studio/plays/PROJECTION.md §7). You launch the play and end your
turn. A wake brings you back when the play needs the director. You riff, send
one answer, and end your turn again. Never sit blocking on the play, and
never use --interactive — that deadlocks a detached run.
Triggers
Wake into this skill for these events or their conversational equivalents:
play.requested for frame-the-problem: the director clicked Frame a
Problem on the coin. Greet, confirm you're connected, and elicit the material.- The director asks you in Claude Code to frame a problem (no event needed).
play.human_input_requested: the play reached its review gate and needs the
director's reaction. Read the draft and riff.play.human_input_resolved: an open ask was answered (by you or elsewhere).
Clear it from your tracked set; do not re-answer it.play.completed: the play finished. Present the final document to ratify or loop.
Each wake payload carries the event object. Read event.type and
event.payload first; the human-input events carry fabroRunId, questionId,
prompt, and choices — you need fabroRunId and questionId to answer.
Connection Safeguard (do this first, every kickoff)
The whole loop depends on wakes reaching you. Before launching a play, confirm
you're connected:
ax inspect connections list --json
Your session's connection (${ALEXANDRIA_CLAUDE_CONNECTION_ID}, default
host:claude-code:default) must be present with active: true. If it is not,
tell the director plainly that you need to reconnect, (re)establish the
connection by launching the monitor:
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-monitor.sh" &
then re-check and tell the director you're connected again. Speak in
"connected" terms — never say "monitor process." If you cannot get connected, do
not silently run the play: you would miss the review and completion wakes.
Warn the director and stop.
Eliciting The Material
When the director asks (or the coin fires), get the one thing the play needs:
the material to frame. Ask for it conversationally — the pitch, the rough
problem statement, the conversation, the notes. One short ask; don't interrogate.
When you have it, write it to a file with your file-writing tool, then launch the
play detached (the default — fire-and-forget):
ax run frame-the-problem --input transcript=/abs/path/to/material.md --json
Writing the material to a file and passing its path is the robust path: real
material has apostrophes, quotes, and newlines that do not survive a command
line. For short, simple material you may instead pass it inline, which writes it
to a temp file for you:
ax run frame-the-problem --input-text "transcript=the director's short note" --json
The run returns immediately with a fabroRunId. Tell the director you're
framing it and end your turn. Do not pass --interactive, --wait, or
--auto-approve: --auto-approve would skip his reaction silently, and the
others block.
The Review Riff (on play.human_input_requested)
The play drafted a framing and is now waiting for the director. Two files were
written by the play under the Alexandria workspace's runtime/ directory:
runtime/problem-framing.md — the current draft (the one co-edited document).runtime/for-the-director.md — your marching orders: what to put in front
of him, and the one or two thin spots to draw out, each with the evidence bar.
Read both (event.payload.draftArtifactPath points at the draft when present;
otherwise read runtime/problem-framing.md from the workspace). Then riff with
the director in your own voice, executing for-the-director.md:
- Put the framing in front of him plainly. Surface the thin spots it names.
- Hold the evidence bar: a claim is earned by a specific, recent instance
("last Tuesday I sat fifteen minutes poking the agent…"), not hand-wavey
generality ("it happens all the time," "I waste tokens"). When he gives the
hand-wavey version, the follow-up is simply: "Can you tell me about a specific
time that happened recently?" He doesn't need the date — he needs one real
instance.
- Frame in service of facts and logic, not the solution. The framing may support,
complicate, or undercut his solution; say which, and only grant support a
specific instance earns.
When you and the director have agreed on his reaction, send exactly that one
reaction back to the waiting gate:
ax raven answer --run <fabroRunId> --question <questionId> --select <approve-key>
ax raven answer --run <fabroRunId> --question <questionId> --text "<the agreed reaction>"
event.payload.choices lists the gate's option keys; prompt is the gate's
question. Approve is the choice that finishes; revise carries his feedback as
freeform text. (If the gate is a simple yes/no, --yes approves.) Confirm to the
director: "Sent your feedback back to the play." Then end your turn — a new
wake arrives when the play has the next draft or completes.
Tracking open asks (never cross-wire)
Several asks can be open at once — parallel branches in one run, or several runs.
Treat them as a set, keyed by (fabroRunId, questionId):
- Route each decision to its own
(fabroRunId, questionId). Never answer one
gate with another gate's decision.
- After each answer, the command tells you
answered or already_resolved. On
play.human_input_resolved, drop that ask from your set; do not re-answer it.
ax raven answer is idempotent: answering an already-resolved gate is a no-op
success, so a duplicate wake is safe.
Ratify Or Loop (on play.completed)
The play finished. Present runtime/problem-framing.md to the director and let
him ratify it or put it back in the loop:
- Ratify → the document is his framing. It goes to you as product context.
Do not auto-bank it. Bank it into the Library only if and when the director
explicitly directs you to.
- Loop → he wants more work. Frame his new reaction as fresh material and
launch another
frame-the-problem run, or continue an open gate if one remains.
Never Self-Answer
The director owns every reaction and the ratify decision. Do not infer approval
from silence, positive tone, or your own confidence. Send an answer to the play
only when the director has agreed to it. You facilitate and relay; he decides.
What This Skill Does Not Do
- Does not block on the play or use
--interactive / --auto-approve /
--wait for the live loop. Launch detached, end your turn, resume on a wake.
- Does not self-answer a gate or ratify on the director's behalf.
- Does not auto-bank the finished framing. Banking is a separate, director-directed step.
- Does not edit
events.jsonl, runtime/problem-framing.md, or the play's prompts directly.
- Does not start a second play off a
play.started / _completed echo; only a
play.requested (or the director's ask) starts a run.
