How gstack Implements the Confusion Protocol to Prevent Architectural Ambiguity

The Confusion Protocol is a prompt-engineering safeguard that forces LLMs to stop and ask users when facing high-stakes architectural ambiguity, injected into Tier 2+ skills via generateConfusionProtocol() in the gstack preamble builder.

The garrytan/gstack repository implements the Confusion Protocol as a critical safety layer to prevent language models from making unchecked architectural decisions. Unlike runtime validators, this mechanism operates through static prompt injection, ensuring that AI agents surface uncertainty rather than silently guessing when encountering decisions about data models, destructive scope, or missing context.

Defining the Confusion Protocol Source

The literal protocol text originates in scripts/resolvers/preamble/generate-confusion-protocol.ts. The generateConfusionProtocol() function exports a Markdown block containing the hard instruction:

export function generateConfusionProtocol(): string {
  return `## Confusion Protocol

For high‑stakes ambiguity (architecture, data model, destructive scope, missing context), STOP. Name it in one sentence, present 2‑3 options with trade‑offs, and ask. Do not use for routine coding or obvious changes.`;
}

This function returns a concise directive that commands the model to halt execution and request clarification when detecting ambiguous architectural choices.

Injecting the Protocol into Tier 2+ Preambles

The preamble builder in scripts/resolvers/preamble.ts imports this utility and conditionally appends it based on skill tier. At line 54, the builder imports the generator:

import { generateConfusionProtocol } from './preamble/generate-confusion-protocol';

Within the generatePreamble function at lines 1014-1015, the protocol is appended only when the skill's tier is 2 or higher:

...(tier >= 2 ? [
  generateAskUserFormat(ctx),
  generateBrainSyncBlock(ctx),
  generateModelOverlay(ctx),
  generateVoiceDirective(tier),
  generateConfusionProtocol(),
  // ... other Tier-2 sections
] : []),

This tiered gating ensures that only skills requiring high-level architectural planning receive the ambiguity guardrail, while routine coding tasks remain unencumbered.

Architectural Execution Flow

The Confusion Protocol operates through a five-step prompt-driven pipeline:

1. Skill initialization — The skill's entry point invokes generatePreamble(ctx) to load the appropriate system instructions.

2. Tier-based assembly — The preamble builder checks ctx.preambleTier and includes the Confusion Protocol only for Tier 2 or higher skills.

3. Prompt transmission — The assembled Markdown preamble concatenates with skill-specific instructions and transmits to the LLM (Claude, OpenAI, etc.).

4. Behavioral enforcement — Because the protocol uses imperative language ("STOP. ... ask."), the model follows the stop-and-ask rule when detecting high-stakes ambiguity rather than inferring intent.

5. Human resolution — The model returns a structured response naming the ambiguity and presenting 2-3 concrete options with trade-offs, allowing the user to clarify before any code generation proceeds.

Practical Implementation Example

To generate a prompt containing the Confusion Protocol for a production skill like ship:

import { generatePreamble } from "./scripts/resolvers/preamble";
import { readTemplate } from "./utils/template";

async function buildPrompt(skillName: string, ctx: TemplateContext) {
  const preamble = generatePreamble({ ...ctx, skillName });
  const skillPrompt = await readTemplate(`skills/${skillName}/prompt.md`);
  return `${preamble}\n${skillPrompt}`;
}

// Usage for "ship" skill (Tier 4)
const prompt = await buildPrompt("ship", { preambleTier: 4 });
console.log(prompt);

The resulting output includes the protocol section as rendered in ship/SKILL.md at line 642. When the LLM receives this prompt, any request involving architectural decisions triggers the "stop and ask" behavior defined by the protocol.

Why Prompt-Based Guardrails Work

The Confusion Protocol functions as a static prompt injection rather than a runtime detector, providing specific technical advantages:

• Deterministic placement — The protocol appears early in the preamble sequence, after generateAskUserFormat and voice directives, ensuring it has precedence over downstream generation instructions.
• Explicit imperative language — The "STOP" command paired with specific option-counting requirements (2-3 options) leverages proven LLM obedience patterns documented in AI coding research.
• Centralized maintenance — Single-source definition in generate-confusion-protocol.ts guarantees consistency across all Tier 2+ skills and simplifies updates.
• Selective deployment — Only high-stakes skills receive the processing overhead, preserving execution speed for routine Tier 1 operations.

Summary

• The Confusion Protocol is defined in scripts/resolvers/preamble/generate-confusion-protocol.ts and returns a Markdown instruction block that commands the LLM to halt on architectural ambiguity.
• scripts/resolvers/preamble.ts imports and injects the protocol at lines 1014-1015 only for skills with preambleTier >= 2.
• The protocol forces LLMs to name the ambiguity in one sentence, present 2-3 options with trade-offs, and ask the user rather than guessing.
• Production skills like ship (documented in ship/SKILL.md at line 642) include this safeguard in their generated system prompts.
• This approach prevents the "wrong assumptions" failure mode common in AI coding by enforcing human-in-the-loop validation for high-stakes architectural decisions.

Frequently Asked Questions

What triggers the Confusion Protocol in gstack?

The protocol triggers when a language model encounters high-stakes ambiguity regarding architecture, data model selection, destructive scope, or missing context. According to the source instruction, the model must identify the uncertainty in one sentence, present 2-3 options with trade-offs, and ask the user for direction rather than proceeding with a silent assumption.

Is the Confusion Protocol a runtime check or a prompt instruction?

It is a prompt instruction, not a runtime detector. The protocol text is statically injected into the system prompt for Tier 2+ skills. When the LLM parses the prompt, the imperative "STOP" language modifies its behavior to pause and ask when it detects ambiguity matching the described criteria.

Which gstack skills use the Confusion Protocol?

Any skill configured with preambleTier 2 or higher receives the protocol. For example, the ship skill (Tier 4) includes the Confusion Protocol section at line 642 of its SKILL.md file. Tier 1 skills omit this section to maintain faster execution for routine coding tasks.

How does the Confusion Protocol prevent architectural errors?

By forcing the model to surface uncertainty explicitly and present multiple valid options with trade-offs, the protocol eliminates silent decision-making. This addresses the most common AI coding failure mode—incorrect assumptions—by ensuring human operators validate architectural choices before code generation begins, as implemented in the garrytan/gstack codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}