agentleFS
oleg-vasilyevoleg-vasilyev/FoolProof/.claude/skills/add-repository-method/SKILL.md

add-repository-method

Skill2 starsChanged 52 days agoMITView on GitHub

Add a query or write to the FoolProof repository layer. Stage 1 work, while the interfaces are still being frozen — use whenever a feature needs data it cannot currently get — new SQL, a new domain method, a new column read. Covers the files that must change together and the two rules that make the layer worth having.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add the method to the Repository interface, and any row type it returns.

    line 19
  2. Distinctive:

    No knowledge of column names may leak out of this file.

    line 33
  3. Very specific:

    Keep this file to SQL. A row reaches its record shape through row-records.ts, and a column value reaches its type through column-values.ts …

    line 36
  4. Very specific:

    If the method returns a record shape that has no mapper yet, add one here (toGame, toSeat, toPlayerColumn are the pattern) and give it a …

    line 42
  5. Very specific:

    Add a <method>Spy field with a sensible default in the constructor, and a method that delegates to it.

    line 54
  6. Very specific:

    Do not add an npm script for a one-off query.

    line 71

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Adding a repository method

Stage 1 of how a change becomes a release.

Features never touch the database. They depend on the interface and call named domain methods, so adding a query means adding a method — never a query built at the call site.

Four files change together, and a fifth if the method returns a new shape. Skipping one is what breaks the layer.

1. src/shared/repository/repository-contract.ts

Add the method to the Repository interface, and any row type it returns.

The name is a domain phrase, not a SQL one: liveCardInChat, rosterInChat, seriesChronology. A caller should not be able to guess the table from the name.

2. src/shared/repository/sqlite-repository.ts

The only file allowed to contain SQL or to import the connection. Implement the method here.

  • Timestamps are TEXT in datetime('now') form, always UTC — the columns are sorted and compared directly, so never store or accept a locale format.
  • Anything that writes more than one table goes inside a transaction, so a failure leaves nothing partial behind.
  • No knowledge of column names may leak out of this file. Map rows to the shape the interface promised before returning them.

Keep this file to SQL. A row reaches its record shape through row-records.ts, and a column value reaches its type through column-values.ts — nothing here reads typeof or picks a fallback.

2a. src/shared/repository/row-records.ts — only for a new shape

If the method returns a record shape that has no mapper yet, add one here (toGame, toSeat, toPlayerColumn are the pattern) and give it a case in row-records.spec.ts, which mocks column-values.ts so the assertion is which coercion each column got.

This split is the reason the layer is testable at all: anything importing the connection can only be exercised against a real SQLite, and a real SQLite never returns the wrong type for a column — so a defensive branch written in the SQL file is unreachable from its own spec, and the mutation score will say so.

3. src/shared/repository/repository-contract.stub.ts

Add a <method>Spy field with a sensible default in the constructor, and a method that delegates to it. Every spec that mocks the repository gets the new method for free; without this step they fail to compile.

4. src/shared/repository/sqlite-repository.integration.spec.ts

One of the project's integration specs, and it runs against a real temporary SQLite file — its whole job is the SQL, and a mocked database would assert nothing.

process.env.DB_PATH is set before the import, because sqlite-connection.ts opens the connection at module load. Assert the behaviour the method promises, including what happens with no rows, and — where the schema is doing the work — that the constraint actually rejects the bad case.

What not to do

Do not add an npm script for a one-off query. Occasional work (backfills, merging duplicate players) goes behind scripts/tools/tools.ts, which writes its own list to reports/tools/tools.log when run with no argument; adding a tool is one line in its table.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.