project-etiquette

Files (1)

• SKILL.md

SKILL.md (first lines)

# Project etiquette (ship sequence)

## Why this exists

Shipping is a **pipeline of gates**, not a single “push and hope.”  
The same sequence works for **almost any project** (Python, Node, Rust, monorepos):

**Blast radius → Fix → Test → Update project → Update docs → Build → Commit → CI green → Publish**

Skip a gate only when the user **explicitly** says so (e.g. “docs later”, “no publish”).

## When to use

- User asks to finish / ship / release a change.
- Phrases like: “test everything, if it passes update everything, build, commit
  to CI, if it passes publish to PyPI.”
- Multi-hour builds where you must not leave the tree half-shipped.

## Portable gate chain

Execute **in order**. After any failure, stop advancement until that gate is green.

### 0. Blast radius (before large edits)

- Activate **change-safety** (`skill_activate(name=change-safety)`) when available.
- Name the surface, list coupled neighbors, plan paired checks + manual smoke for
  UI/chrome/messengers that unit tests miss.
- Prefer durable architecture over patch loops for known failure classes.

### 1. Fix / implement

- Complete the requested behavior.
- Prefer small, verifiable steps; keep the tree runnable.
- Note risks (migrations, breaking APIs, signing, secrets).

### 2. Test (hard gate)

- Discover how *this* repo tests (pytest, npm test, cargo test, `make check`, …).
- Open `.github/workflows/` (or equivalent) and run **those commands locally**
  before push. Pytest-only is not CI.
- Run the **full** suite when the user asked for “everything”; otherwise run
  the subset that covers the change **plus** the project CI lint/type/docs steps.
- Add or update tests when behavior changed.
- **Do not commit known-failing tests** unless the user wants a WIP commit.
- **Do not push** until the local CI commands are green.

### 3. Update the project

- Bump version **only when shipping a real release** (semver: patch for fixes, minor for features).
- **Do not bump version for docs-only fixes** (manuals, What's new catch-up, README typos, help sync).
  Commit as `docs:` on the current version; users get the notes on the next real release or from git/F1 after rebuild.
- Align version surfaces if the repo has more than one (package.json, Cargo.toml, …) **when you do bump**.
- Keep assets/config consistent with the change.

### 4. Update documentation

- User-visible change → CHANGELOG / release notes / help docs.
- Developer-facing change → README / architecture notes as the repo expects.
- Run any **docs sync/check** scripts the project provides.
- Docs should describe **what the user does**, not only internal renames.
- Docs-only → no version bump / PyPI / release tag unless the user explicitly asks.

### 5. Build

- Produce what CI/release expects (wheels, bundles, desktop artifacts).
- A green unit suite with a broken package build is **not** done.

### 6. Commit

- Stage only intentional files (no secrets, no local noise).
- Message: complete sentences; conventional prefix when it fits
  (`fix:`, `feat:`, `docs:`, `release:`).
- One logical theme per commit when practical.
- Note `Risk:` / `Smoke:` when fragile zones were involved.

### 7. Push and wait for CI

- Push to the integration branch the project uses (`main` / `master`) **only
  after the local CI commands are green.**
- **Wait for remote CI to finish.** Report the run URL when available.
- Red CI → run the **failed step locally**, fix until it is green, then push.
  Do not push a guess. **No publish while red.**

### 8. Publish (only if asked and CI is green)

- Tag release if the project uses tags for installers/changelogs.
- Publish packages (PyPI, npm, crates.io, …) only with existing credentials
  and project conventions.
- Confirm the published version is reachable (e.g. PyPI JSON, `npm view`).

## Response format (report back to the user)

After a ship sequence, summarize with a short table:

| Gate | Result |
|------|--------|
| Blast radius | surfaces + smokes run |
| Tests | pass / fail (+ command) |
| Docs | updated / n/a |
| Build | pass / fail |
| Commit | hash + subject |
| CI | green / red + URL |
| Publish | version + registry / skipped |

If blocked, state **which gate** and the **smallest next action**.

## Anti-patterns

- “It works on my machine” without running the project’s test command.
- Pushing after pytest-only when CI also runs ruff / mypy / docs.
- Pushing a CI-fix commit without re-running the **failed CI step** locally.
- Committing version bumps without changelog/docs.
- Publishing before CI finishes (or ignoring a red run).
- Force-pushing shared mainline branches.
- Leaving half a release without telling the user.
- Treating green CI as proof that title bar / live bots / WebView embeds work.

## Adapting to a new repo

From AhmiDarrow/RemedyAI, Apache-2.0.

More from AhmiDarrow/RemedyAI