Skip to content

notque/vexjoy-agent / skills/analysis/data

Data analysis, reference enrichment, and data engineering: pipelines and warehouses, server database design and tuning, SQLite with Peewee.

references/reference-file-template.md

View on GitHub
# Reference File Template

Use this template when generating new reference files in Phase 3 COMPILE.
Replace `{{PLACEHOLDER}}` markers with actual content. Delete sections that don't apply
to the domain — a focused 80-line file beats a padded 300-line file.

---

# {{DOMAIN}} Reference

> **Scope**: {{ONE-SENTENCE description of what this file covers and what it doesn't}}
> **Version range**: {{e.g., "Go 1.18+", "Python 3.11+", "all versions"}}
> **Generated**: {{YYYY-MM-DD}} — verify version-specific content against current release notes

---

## Overview

{{2-4 sentences explaining the sub-domain: what problem it solves, why it matters for this
agent's work, and what the most common failure mode is. Be specific — mention the language,
framework, or tool by name.}}

---

## Pattern Table

| Pattern | Version | Use When | Prefer When |
|---------|---------|----------|------------|
| `{{function_or_construct}}` | `{{X.Y+}}` | {{condition}} | {{counter-condition}} |
| `{{function_or_construct}}` | `{{X.Y+}}` | {{condition}} | {{counter-condition}} |

*Delete this table if the domain has no version-specific API surface.*

---

## Correct Patterns

### {{Pattern Name}}

{{One sentence: what this pattern does and why it's correct.}}

```{{language}}
// {{comment explaining the key point}}
{{correct code example — copy-pasteable, not pseudocode}}
```

**Why**: {{Behavioral explanation — what breaks if you don't follow this.}}

---

### {{Pattern Name}}

```{{language}}
{{correct code example}}
```

**Why**: {{Explanation.}}

---

## Pattern Catalog: Detection and Fixes

### {{Pattern Name}}

**Detection**:
```bash
grep -rn '{{pattern}}' --include="*.{{ext}}"
rg '{{pattern}}' --type {{lang}}
```

**Signal**:
```{{language}}
{{bad code example — should be something grep above would find}}
```

**Why it matters**: {{Behavioral consequence — what actually breaks, not just "it's bad practice".
Mention the specific failure mode: data loss, silent error, performance degradation, etc.}}

**Preferred action**:
```{{language}}
{{corrected code example}}
```

**Version note**: {{If behavior changed in a specific version, state it here. Otherwise delete.}}

---

### {{Pattern Name}}

**Detection**:
```bash
grep -rn '{{pattern}}' --include="*.{{ext}}"
```

**Signal**:
```{{language}}
{{bad code}}
```

**Why it matters**: {{Consequence.}}

**Preferred action**:
```{{language}}
{{fix}}
```

---

## Error-Fix Mappings

| Error Message | Root Cause | Fix |
|---------------|------------|-----|
| `{{exact error text or regex}}` | {{why it occurs}} | {{what to change}} |
| `{{exact error text or regex}}` | {{why it occurs}} | {{what to change}} |

*Delete this table if the domain has no common error messages.*

---

## Version-Specific Notes

| Version | Change | Impact |
|---------|--------|--------|
| `{{X.Y}}` | {{What changed}} | {{How it affects code using this pattern}} |
| `{{X.Y}}` | {{What changed}} | {{How it affects code using this pattern}} |

*Delete this table if no significant version changes exist for this domain.*

---

## Detection Commands Reference

Quick collection of all grep/rg commands from this file:

```bash
# {{Pattern 1 name}}
grep -rn '{{pattern1}}' --include="*.{{ext}}"

# {{Pattern 2 name}}
rg '{{pattern2}}' --type {{lang}}
```

---

## See Also

- `{{other-reference.md}}` — {{what it covers}}
- {{Official docs URL if applicable}}

---

## Template Usage Notes

**Minimum for Level 2**: Overview + one correct pattern with code block + one failure mode entry.

**Minimum for Level 3**: All of the above + at least one detection command per failure mode +
error-fix mappings table (if the domain has common errors) + version notes (if API changed).

**Line count target**: 80-200 lines for a focused sub-domain. If you need more than 300 lines,
split into two files covering narrower sub-domains.

**What NOT to include**:
- Generic advice ("follow best practices", "be careful with...")
- Patterns that apply to every language (not domain-specific)
- Content that duplicates what's already in the agent body
- Aspirational content ("in the future, consider...")
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall