Skip to content

docs(skills): design defaults and a quality checklist #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
smith-xyz merged 2 commits into from
Oct 21, 2026
Merged

docs(skills): design defaults and a quality checklist #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
26eb883
docs(skills): convention over configuration; fallbacks only when they…
smith-xyz Oct 21, 2026
c24b854
docs(skills): quality checklist in the patterns skill and PR template
smith-xyz Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .agents/skills/traust-core-patterns/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,21 @@ outside the process? → provider
SQL rule several readers share? → a view in traust-contracts
```

## Two defaults

- **Convention over configuration.** Copy the worked example's shape (names, verbs, layout); don't add a setting or flag to choose between behaviours. Config is for what truly differs per deployment, read once in `Context`.
- **Fallbacks are a decision, not a default.** No silent `except: return default` or "if missing, use X". Missing or malformed input raises a typed `traust_core.v1.errors` error, logged once where handled. A fallback is fine only when the domain defines it as behaviour (a degraded outcome with a reason), and then it's explicit and tested.

## Quality checklist (every PR)

1. Comments only for a non-obvious *why*; nothing that restates the code.
2. Docstrings: one or two lines on public API where name and types don't say it; none on private helpers or tests.
3. Don't reinvent: search `src/` for an existing function first and extend it.
4. Generic logic used in more than one place is one helper where its kind lives (`models/values.py`, a provider, the owning repository).
5. Tests cover edges: empty, not found, re-runs, invalid values, boundaries, each typed error, rollback.
6. Integration tests run the real path on SQLite and Postgres with sanitized copies of real data under `tests/fixtures/<domain>/` (people, hosts, org/repo names, tokens replaced). Never live systems.
7. Minimal code: shrink the diff (inline one-use helpers, merge near-duplicates, drop dead code and unused parameters).

## No duplicated responsibility

- One query, one place: the owning table's repository. Filtering rows in Python that SQL could filter → a named query.
Expand Down
4 changes: 4 additions & 0 deletions .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,8 @@
- [ ] Duplicated responsibility touched by this change moved to its owner, copy deleted
- [ ] Tests: behaviour on SQLite (+ Postgres for new queries) via `uow` / `seed`
- [ ] Legacy code deleted only with a parity diff attached
- [ ] Comments only for non-obvious whys; docstrings one or two lines, none on private helpers
- [ ] No reinvented functions (searched `src/`); shared logic is one helper
- [ ] Tests cover edge cases; integration tests use sanitized copies of real data
- [ ] Diff is as small as it can be
- [ ] `make lint-fix && make test` green
Loading