# 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

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

## Template

```markdown
# 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

```markdown
# 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.
