3.0 KiB

Raw Blame History

Golden Example Template

Use this template to document canonical examples that define correct tool behavior. Golden examples serve as regression tests for tool identity.

How to Use

Create one golden example per critical use case
Document actual behavior, not theoretical ideals
Run golden examples after any tool modification
If behavior changes, either fix the tool or update the example with justification

Template

# Golden Example: [scenario name]

## Input

[What the user provides - be specific about context, phrasing, and state]

## Expected Behavior

[What the tool should do - step by step if complex]

## Expected Output

[What the tool produces - include format, structure, key content]

## Why This Matters

[What would break if this changed - user impact, downstream effects]

Field Definitions

scenario name: Short identifier for this example. Should be memorable and searchable.

Input: The exact trigger for this behavior. Include user message, context state, any relevant conditions.

Expected Behavior: What the tool does internally. Focus on observable actions and decision points.

Expected Output: The artifact produced. Be specific enough to verify but not so rigid that cosmetic changes cause false failures.

Why This Matters: The user-facing impact of this behavior. Explains why this is a golden example rather than just an example.

Example: Filled-in Template

# Golden Example: Simple skill creation

## Input

User says: "Create a skill that formats JSON files"

Current directory contains an existing plugin with skills/ folder.

## Expected Behavior

1. Spawn subagent with skill-architect instructions
2. Subagent reads existing skills in plugin for patterns
3. Subagent creates SKILL.md with:
   - Clear frontmatter description
   - Input/output specification
   - Usage examples
4. Subagent runs description-architect for frontmatter
5. Subagent runs audit workflow
6. Returns to main agent with summary

## Expected Output

- `skills/json-formatter/SKILL.md` created
- Frontmatter passes escape-hatch test
- Audit workflow passes or documents issues
- Summary includes file path and usage instructions

## Why This Matters

This is the minimal happy path. If this breaks:
- Users can't create basic skills
- Pattern adherence fails at the most common use case
- Trust in the tool degrades

Guidelines for Good Golden Examples

Choose scenarios that:

Represent common use cases
Exercise critical decision points
Have clear success criteria
Would cause visible user impact if broken

Avoid scenarios that:

Test implementation details
Depend on external state
Have ambiguous success criteria
Overlap significantly with other golden examples

Organizing Golden Examples

Store golden examples in a golden-examples/ directory alongside the tool:

my-tool/
  SKILL.md
  golden-examples/
    simple-creation.md
    error-handling.md
    edge-case-empty-input.md

Reference them in the tool's invariants documentation.

3.0 KiB Raw Blame History