Bound AI Guidance With Playbooks, Budgets, and Read-Only Checks

Flow

Build and test the guide in layers

1. 1Registry⌄

   Typed playbooks, remedies, rules, caps, and stable IDs.

2. 2Renderer⌄

   Pure bounded text with tests for every entry.

3. 3Read-only check⌄

   One transaction, pure evaluation, safe status and next step.

4. 4CLI boundary⌄

   Small queries and no automatic mutation.

5. 5Operator⌄

   Answers decisions, runs approved actions, and verifies outcomes.

If you are building an operational guide, begin with a registry rather than a general-purpose prompt. Define typed entries for playbooks, error remedies, and ground rules. A playbook can have an ID, summary, applicability condition, required inputs, steps, operator questions, stop conditions, and verification statements. An error remedy can have a normalized code, kind, meaning, fixes, and an optional playbook plus step number.

Keep rendering pure. The renderer should accept one registry entry and return lines. It should not read the database, run a command, fetch a provider, or decide whether the operator has permission. This makes output caps easy to test and keeps the guide from acquiring hidden side effects. Index rendering can list all playbook IDs and summaries. Detail rendering can show one playbook. Error rendering can show one remedy. Unknown-topic rendering can list safe alternatives without inventing content.

Choose budgets that are meaningful to the user interface. For example, the index can have a line and character cap, a playbook can have a larger but still bounded cap, and an error remedy can be shorter. The exact numbers are product decisions; the invariant is that every entry is tested. Include long summaries, many steps, and unusually large error fixes in the test fixtures. Truncation should be rejected or made explicit, not silently cut a stop condition from the output.

The CLI or API should expose a small query surface: guide for the index, guide task for one playbook, guide error for one code, and guide vendor for one read-only readiness check. Let the command output carry a machine-readable guide pointer after a failed JSON result. That pointer is useful only if the code is stable and the referenced remedy is safe. Keep the pointer generated by trusted code, not copied from arbitrary provider text.

Implement the readiness check as a separate module. Run all database reads inside one read-only transaction. Resolve an identifier by ID first, then by exact or unambiguous name. If there are multiple matches, return the IDs and ask the user to choose. Load the applied setup head, latest onboarding run, evidence buckets, and open review-required drafts. Evaluate the snapshot with a pure function that returns ready, not ready, the next command, a playbook, a reason, and notes. An unavailable external coverage check should remain unavailable, not become complete.

Make the report useful without making it authoritative. It can say “coverage incomplete,” “setup not applied,” “an open review-required draft exists,” or “database checks pass but the live gateway was not checked.” It should not execute the next command automatically. If the next command writes a file or changes configuration, show it as a recommendation and ask the operator to run it through the normal permissioned path.

Test more than the happy path. Test unknown topics and codes, code normalization, long output, ambiguous names, inactive targets, missing setup, incomplete coverage, unresolved mappings, open drafts, unavailable gateways, and successful readiness. Use a database double that throws on any write and assert that the entire check succeeds without mutation. Capture the output and confirm that a secret, provider error, or private diagnostic payload cannot be rendered.

The final practical rule is one answer, one next action. If a playbook has ten possible branches, ask the operator the question that selects one. If no branch is safe, stop. The guide is not a replacement for a runbook or authorization layer; it is a compact interface that helps a person navigate both.