Cige Test Authoring

CIGE: Agentic Test Case Authoring

Use this skill when writing, reviewing, or refactoring AI agent test cases. It enforces the CIGE standard — a structured format that separates stable test intent from adaptive execution, enabling self-healing agentic tests.

When to invoke

• Authoring a new agentic test case from scratch
• Reviewing an existing test for brittleness or missing structure
• Designing test guardrails for a new agent workflow

For a completed run — pass or fail — do not decide repairs here. Invoke cige-failure-classification first; it classifies the outcome and names which skill (if any) should act.

The CIGE Format

Every agentic test case must be expressed in this structure:

{
  "Context": {
    "system": "<app or service under test, version if relevant>",
    "environment": "<staging | dev | ephemeral | ...>",
    "tools": ["<tool 1>", "<tool 2>"],
    "preconditions": ["<seed data>", "<auth state>", "<feature flags>"],
    "specRef": "<path or URL to the BRD / product spec that defines expected behavior>",
    "buildRef": "<pointer to the build/version under test and its release documentation — changelog, release notes, or build manifest>"
  },
  "Intent": "<single outcome-based objective — what success looks like>",
  "Guardrails": [
    "<constraint the agent must never violate>",
    "<scope boundary or irreversibility limit>"
  ],
  "Execution": [
    "<adaptive step 1 — guidance, not script>",
    "<adaptive step 2>",
    "<verification: confirm intent was achieved>"
  ]
}

specRef is required. It is the ground truth that self-healing agents use to distinguish a product defect from an intentional product change. Without it, failure classification cannot be completed.

buildRef is required for the same reason: specRef alone can tell you what the product should do, but not whether the build under test actually contains that behavior yet. Without buildRef, a product-defect classification can't safely conclude "intentional change" — see cige-product-defect-escalation.

How to apply each field

Context

Answer these before writing any execution:

• What system is being tested? (app, service, version, environment)
• What is the agent's starting state? (logged in, seeded data, feature flags)
• What tools does the agent have access to?
• What external dependencies must be available?
• Where is the product specification or BRD for this system? (specRef)
• What build/version is under test, and where is its release documentation? (buildRef)

Context can also carry reusable prompts — fragments (login notes, environment setup, common preconditions) that apply across multiple tests in different combinations, rather than being re-authored per test.

specRef can be a file path, a URL, a Notion/Confluence page ID, or any resolvable pointer to the document that defines expected system behavior. It must be kept up to date as the product evolves — it is what self-healing agents read to determine whether a failure is a bug or an intentional change.

buildRef is a pointer to the build/version under test and its release documentation — a changelog, release notes, or build manifest. It answers a different question than specRef: not "what should the system do" but "did this build actually ship the change the spec describes." Like specRef, it's a pointer required upfront, not content to fetch now — cige-product-defect-escalation fetches its contents later, only when it needs to confirm a build actually shipped a spec change before concluding the change was intentional rather than a bug.

Rule: If context is ambiguous, ask — do not assume defaults. If specRef or buildRef is missing, ask the user to provide them before writing execution steps.

Tool Discovery within Context

When a test's Execution spans many tools or multiple agents, don't enumerate every tool definition inside Context — load them progressively, the same way Execution steps are progressively disclosed:

• Tool search: put a tool-search capability in Context so the agent discovers and loads the precise tool contract it needs on demand, instead of loading every tool definition up front.
• Skills file: a lightweight, per-agent capability index — one entry per tool, with a short description — that routes intent to the right agent or tool domain. It is a index, not a contract: it tells the agent where to look, not how to call the tool.

These two are complementary, not redundant: the skills file routes ("which agent/domain handles this"), tool-search retrieves ("the exact contract for this one tool, right now"). To avoid loading both a routing index and full contracts at once:

Rule: Skills files hold only high-level capability metadata (name + one-line description). Detailed tool schemas and invocation contracts stay federated to their owning agent's context and load only at execution time, via tool-search.

Intent

Write one sentence that answers: "What outcome must be true for this test to pass?"

• Use outcome language, not procedural language
• Intent must survive: UI redesigns, API refactors, workflow changes
• Bad: "Click checkout, fill address, submit order"
• Good: "User can successfully place an order and receive a confirmation"

Intent as metadata. Every test case is uniquely identified by its Intent, and Intent changes far less often than the rest of the test. Treat it like a database record's metadata pointing at a blob: a large video file lives in blob storage, but its metadata (title, duration, tags) lives in a fast-to-scan index — systems learn what the file is about without loading it. Intent plays the same role for a test case: agents filtering a large pool of tests, grouping related tests, or authoring new ones should be able to reason from Intent alone, without loading the full Context/Guardrails/Execution body.

Rule: Intent is the anchor. If execution changes but the intent sentence still holds, the test is still valid.

Guardrails (Runtime)

Declare explicit constraints before execution begins:

• No mutations to production data
• No exposure of PII or secrets
• No irreversible operations (deletions, payments, emails) without scoped test doubles
• No execution outside the designated test environment

Guardrails reduce false positives, not just prevent damage: they stop shortcuts that make the final state look correct without actually validating the feature (e.g., accepting a UI success message without checking the backend record it should have created).

Individual agents may keep local guardrails of their own, but guardrails declared here are enforced at runtime as a shared, runtime-agnostic control layer — the same constraints apply regardless of which agent or runtime executes the test, which matters once multiple agents (planner, executor, validator) touch the same test case.

Rule: If a guardrail would be violated by any execution path, surface it and halt — do not route around it. Guardrails may later be strengthened (never loosened) through a narrow, human-gated exception — see cige-failure-classification and cige-stale-execution-repair for when and how.

Execution

Write steps as adaptive guidance, not rigid assertions:

• Steps are starting points; the agent adapts when the system changes
• End every execution block with an intent verification step
• Use progressive context disclosure: load steps on demand, not all upfront

Rule: A passing test means intent was confirmed safely. A failing test — or a suspiciously easy pass — requires classification before any fix; see cige-failure-classification.

Progressive Context Disclosure

Never load the full CIGE test case into an agent's context at once. Load fields in stages, in order, stopping at each layer until the current layer's work is complete before loading the next.

This follows the same principle as efficient memory retrieval systems: filter before fetching. Loading all execution steps upfront dilutes attention, increases token cost, and allows agents to "look ahead" and take shortcuts that bypass guardrail checks.

The 3-Layer Loading Protocol

Layer 1 — ORIENT    →  Load: Intent only
Layer 2 — BOUND     →  Load: Context + Guardrails
Layer 3 — EXECUTE   →  Load: Execution[], one step at a time

Layer 1 — Orient (Intent only) Load just the Intent field first. At ~1-2 sentences, this costs almost nothing. The agent uses it to:

• Confirm this test is relevant to the current task
• Establish the goal before seeing any constraints or steps
• Decide whether to proceed at all

Do not load Context or Execution until Intent is confirmed and the test is selected for running.

Layer 2 — Bound (Context + Guardrails) Once Intent is confirmed, load Context and Guardrails together. The agent now knows:

• What environment to set up and what tools are available (Context)
• What it must never do before taking a single action (Guardrails)

Guardrails must be loaded before any Execution step. An agent that begins executing before seeing its Guardrails is operating without safety bounds.

specRef is part of Context but its contents are not fetched at this layer. The pointer is loaded; the document is not. The spec is fetched lazily — only when a self-healing agent needs it for failure classification. Normal test execution never reads the BRD.

Layer 3 — Execute (Execution steps, one at a time) Load execution steps individually, on demand, as the agent progresses. Do not surface step 4 while the agent is working on step 2.

Each step should carry a short stable ID so failure reports can reference it precisely without repeating full step text:

"Execution": [
  { "id": "e1", "step": "Navigate to cart with at least one item" },
  { "id": "e2", "step": "Proceed through checkout to order summary" },
  { "id": "e3", "step": "Submit using test payment credentials" },
  { "id": "e4", "step": "Verify: order confirmation page shows a valid order ID" }
]

When a step fails, a self-healing agent references the failure as e3 failed and loads the N steps before it for diagnostic context — not the entire test.

specRef and buildRef: Lazy Fetch on Demand

Normal execution:    Context loads → specRef and buildRef pointers are known, contents NOT fetched
Failure occurs:      Self-healing agent fetches specRef contents for classification
Product Defect path: cige-product-defect-escalation also fetches buildRef contents,
                      only to evaluate Case B (confirming a spec change actually shipped)
Classification done: specRef and buildRef contents discarded from context

This is the same pattern as a citation system: you know the reference exists from the moment Context loads, but you only pull the full document when you actually need to reason about it. In most test runs, neither specRef nor buildRef is ever fetched at all. buildRef is fetched even less often than specRef — only when a Product Defect classification is being evaluated for Case B, not on every failure.

Run Summaries

After each test run, compress the execution trace into a short summary observation:

{
  "testId": "checkout-happy-path",
  "runDate": "2026-04-16",
  "result": "pass | fail | self-healed",
  "failedStep": "e3",
  "failureType": "outdated-test-logic | product-defect | infrastructure | false-positive",
  "recoveryAction": "StaleExecutionAgent updated e2, e3 — approved by human",
  "intentUnchanged": true
}

Future agents can load this summary (a few lines) before deciding whether to run a full test or to first check whether recent runs suggest a pattern. This is progressive disclosure applied across sessions, not just within a single run. cige-failure-classification owns the authoritative version of this format.

Domain Patterns

CIGE is domain-agnostic, but the same field-separation plays out differently by vertical:

Retail / E-commerce. Checkout, pricing, promotions, and search evolve continuously; seasonal release cycles amplify the cost of brittle suites. Keep Intent stable at the outcome level (e.g. "the user completes checkout with a valid discount and correct tax") and let Execution absorb UI churn. Guardrails should block real orders and payment processing, and require backend order-service validation rather than accepting UI confirmation alone.

Banking and Financial Services. The controlled-repair model matters most in regulated environments. Guardrails should encode compliance constraints directly (protect customer data, preserve audit records), and the human-approval gate on Intent changes doubles as a governance boundary — the evidence and approval history is itself an audit trail.

Healthcare. Guardrails should enforce PHI protection and block unintended modification of patient records. Prefer evidence-based validation against authoritative backend services (claims systems, clinical records) over trusting UI behavior alone.

Quality Check

A well-formed CIGE test satisfies all of these:

• Context answers: what system, what environment, what tools, what state
• Context includes a resolvable specRef pointer
• Context includes a resolvable buildRef pointer to the build/version's release documentation (needed for product-defect classification)
• If the test spans multiple tools/agents, Context declares a tool-search mechanism and/or a skills-file capability index — with detailed tool contracts kept out of the skills file
• Intent is one outcome-focused sentence, free of procedural language
• Guardrails enumerate at least the irreversibility and scope boundaries
• Execution steps each carry a stable short ID
• Execution ends with an explicit intent verification step
• Test can be read by a human and understood without looking at the system

If any box is unchecked, the test is not ready to run.