# Retentioneering Contributing

Help the user turn their Retentioneering ideas, friction reports, bug findings, or...

- Repository: https://github.com/retentioneering/retentioneering-tools (943 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add retentioneering/retentioneering-tools --skill retentioneering-contributing -g -a claude-code -y`
Codex: `npx skills add retentioneering/retentioneering-tools --skill retentioneering-contributing -g -a codex -y`
Cursor: `npx skills add retentioneering/retentioneering-tools --skill retentioneering-contributing -g -a cursor -y`
Gemini CLI: `npx skills add retentioneering/retentioneering-tools --skill retentioneering-contributing -g -a gemini-cli -y`

## Description

Help the user turn their Retentioneering ideas, friction reports, bug findings, or feature needs into high-quality upstream contributions: from capturing and validating the idea, through minimal reproductions and issue drafts, to preparing, testing, and submitting a pull request that follows this repository's conventions. Use when the user says they found a bug, wants a feature, wrote a workaround worth upstreaming, or asks how to contribute, open an issue, or make a PR to retentioneering-tools.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Contributing to retentioneering-tools

## Objective

Convert a user's observation, a bug, a paper cut, a missing capability, a workaround
they keep re-writing, into the smallest upstream change that would have prevented it,
packaged so maintainers can accept it quickly.

## Bundled references

| File | Read it when |
|---|---|
| `references/repo-conventions.md` | before touching code, build/test/docs commands, architecture rules, naming, sync obligations |
| `references/proposal-templates.md` | when drafting, issue/feature/PR templates with worked examples |

## The full route: idea → merged PR

### Stage 1, Capture the observation properly (do this even for "small" ideas)

Record four things while they are fresh:
1. **Expectation**, what the user believed would happen (quote the docstring/docs page
   that created the expectation, if any).
2. **Reality**, what actually happened (exact error text or wrong output).
3. **Cost**, time lost, wrong conclusion nearly shipped, workaround written.
4. **Environment**, `retentioneering.__version__`, Python, OS, install source
   (pip wheel vs source checkout).

Field lesson: reports formatted as expectation/reality/cost/repro get acted on;
"X is broken" reports stall.

### Stage 2, Validate against the CURRENT version

Many pain points are already fixed on `v5-migration`, verify before drafting:

1. `git log --oneline -30` and `CHANGELOG.md`, search keywords from the observation.
2. Search existing issues/PRs: `gh issue list --search "<keywords>"`, `gh pr list ...`.
3. Reproduce on the current checkout (see Stage 3). If it no longer reproduces, the
   contribution may become a docs clarification or a regression test instead, both welcome.

### Stage 3, Minimal reproduction (the heart of a bug report)

Build the smallest toy that shows the gap, e.g.:

The rest: https://github.com/retentioneering/retentioneering-tools/blob/HEAD/.agents/skills/retentioneering-contributing/SKILL.md