---
name: document-learnings
description: Guidelines for documenting reusable patterns discovered during work. Use when completing tasks that reveal non-obvious workflows or project conventions.
---

## Purpose

Capture reusable knowledge so future sessions avoid repeated debugging and rediscovery.

## When to Document

- After discovering a required workflow with multiple mandatory steps
- After fixing a non-obvious bug or uncovering a subtle constraint
- After establishing a new pattern or convention
- After the user corrects the model's approach — this reveals the user's preferred way of working
- When the user asks to document learnings

## When NOT to Document

- Obvious or standard practices
- One-off debugging that won't recur
- Information already well-covered in existing docs

## Where to Put Documentation

| Scope | Location |
|-------|----------|
| Public user documentation | `Documentation/src/` |
| Architecture decisions | `docs/adr/NNNN-*.md` and `docs/adr/README.md` |
| Durable intent, specification, and plan | `intent/<work-item>/{intent,spec,plan}.md` |
| Project-specific agent workflows | `.opencode/skills/<name>/SKILL.md` |
| Short reference needed every invocation | `AGENTS.md` |
| Reproducible agent regression | `evals/cases/<name>/` |

## Skill File Format

```
---
name: skill-name
description: Short description. Use when ...
---

## Purpose
What this skill covers.

## Instructions
### 1. Step One
Specific, actionable steps with code examples.

## Common Pitfalls
| Pitfall | Fix |
|---------|-----|
| ... | ... |
```

## Tips

- Keep skill descriptions actionable
- Include code examples and common pitfalls tables
- Commit skills to the repo so the whole team benefits
- Pay special attention when the user corrects or refines the model's output — that feedback encodes the user's standards and preferences for this project
- Document the "why" behind conventions, not just the "what" — e.g., why a checklist exists, what goes wrong if a step is skipped