Skip to main content

The Guide-and-Sensor pair (detour: /grill-me)

In Guides and Sensors we said "important standards are protected with a Guide-and-Sensor pair." This chapter looks at the canonical example concretely, all the way through, using /grill-me.

Subject: don't write questions in plain prose​

/grill-me is a skill that grills the ambiguities of requirements before implementation. Naturally, it throws many questions at the user. Here, a certain standard of this environment takes effect.

Questions, confirmations, and option presentations to the user are structured with the AskUserQuestion tool, not in plain prose.

Why avoid plain prose? Rather than writing "which do you want, A or B?" in the running text, presenting options, a recommendation, and the trade-offs in a structured way lets the user choose on the merits. This standard is protected with both a Guide and a Sensor. Note that the AskUserQuestion tool itself is Claude Code built-in (📦), while the rule and hook we are about to see are the author's custom work (🔧).

The Guide side: rules/ask-user-question.md​

What directs before the action is rules/ask-user-question.md (an Inferential Guide). It states in prose, with prohibited patterns and the correct behavior, "don't ask in plain prose; use the dedicated tool."

ask-user-question.md (the gist of the standard)
Use the AskUserQuestion tool for all questions, confirmations, and option presentations.
Prohibited: "What should we do? A or B", "Is this OK?",
            plain-prose confirmations like "Good so far?"

This is effective, but being prose, it is probabilistic. In the flow of an involved explanation, there are moments where you inadvertently write "is it OK to proceed in this direction?" in the running text. With the Guide alone, that one time cannot be fully stopped.

The Sensor side: check-plain-question.sh​

So what catches what is missed after the action is check-plain-question.sh (a Computational Sensor, the Stop hook that appeared in the Stop hook). At the moment the response is finalized, it mechanically detects plain-prose question patterns.

check-plain-question.sh (part of the detection patterns)
EXPLICIT_PATTERNS='どうしますか|...|進めますか|続けますか|...'
CONFIRMATION_PATTERN='(ここまで|これで|この方向で|それで|この内容で|この方針で)?[[:space:]]*(OK|ok|オッケー|おっけー)[[:space:]]*(です|でしょう)?(か)?[?？]|...|合っ(て(る|ます)?|って(る|ます)?|てい(る|ます))[[:space:]]*(か)?[?？]|...'
# when detected
echo "Action: undo the previous response and re-ask with the AskUserQuestion tool..." >&2
exit 2

On detection, it sends the response back with exit 2 and makes it re-ask with AskUserQuestion. The one time that slipped through the prose standard is caught deterministically by the machine. This is the diagonal of the cross-classification in action — the pair of an Inferential Guide and a Computational Sensor.

A third element: the SessionStart hook that sets up the prerequisite​

In fact, there is one more mechanism that supports this standard: ensure-askuserquestion-loaded.sh (a SessionStart hook).

Even with the Guide and the Sensor in place, one loophole remained. Because the AskUserQuestion tool has a specification where its schema is lazily loaded, calling it while unloaded fails with an error. Then, "because the tool is unusable," it escapes to a plain-prose question — a recurrence where trying to follow the standard caused a slip-through actually happened. So we added a hook that deterministically injects, at session start, the guidance "load the schema first." This is a three-stage setup of Guide (rule) × Sensor (Stop hook) × prerequisite setup (SessionStart hook). The path by which a standard slips through is not only a misread of the prose; it also lies on the structural side, as "the means of compliance is unusable." Plugging that, too, is the harness's job.

A Sensor also accounts for false positives

Mechanical detection risks catching even legitimate sentences. So check-plain-question.sh has fine-grained exclusions built in. To avoid falsely detecting status reports ("Build OK"), it makes a trailing ?/？ mandatory, and if AskUserQuestion was used just before, it lets it pass through. On the other hand, exceptions that cannot be judged mechanically (such as continuing work the user has already explicitly instructed) are let off by guiding them to a bypass in the message shown on detection. A "too-noisy Sensor" stops being used, so a design that suppresses false positives is also part of the quality.

This pair is the backbone of the harness​

/debug's "avoid symptomatic treatment × check-suppression.sh" and /grill-me's "avoid plain-prose questions × check-plain-question.sh" have the same structure.

Steer in advance with prose (Guide), and catch the slip-throughs mechanically (Sensor).

When Guides and Sensors said "protect important standards with both," it meant this accumulation. The more you add pairs one by one, the more the room for slip-throughs narrows.

Summary of this chapter

The key points are as follows.

  • Protect the "structure questions" standard with a pair of a Guide (ask-user-question.md) and a Sensor (check-plain-question.sh)
  • The Guide steers before the action but is probabilistic, and the Sensor deterministically catches what is missed after the action
  • The structural loophole of "the means of compliance is unusable" is plugged by the prerequisite setup of the SessionStart hook (a three-stage setup)
  • A Sensor is designed together with exclusion conditions that suppress false positives
  • This Guide+Sensor pair is the very backbone common to the harness as a whole

Finally, in the summary, we look back over the journey so far and show the first step in growing your own harness.