111 lines
3.0 KiB
Markdown
111 lines
3.0 KiB
Markdown
|
# 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.
|