docyrus-api-doctor

Original：🇺🇸 English

Translated

Run after making Docyrus API changes to catch bugs, performance issues, and code quality problems. Use when implementing or modifying code that uses Docyrus collection hooks (.list, .get, .create, .update, .delete), direct RestApiClient calls, query payloads with filters/calculations/formulas/childQueries/pivots, or TanStack Query integration with Docyrus data sources. Triggers on tasks involving Docyrus API logic, data fetching, mutations, or query payload construction.

2installs

Sourcedocyrus/agent-skills

Added on2026-03-02

NPX Install

npx skill4agent add docyrus/agent-skills docyrus-api-doctor

SKILL.md Content

View Translation Comparison →

Docyrus API Doctor

Post-implementation checklist for Docyrus API code. Run through each applicable check after writing or modifying API logic. Fix every issue found before considering the task complete.

How to use: After implementing API logic, scan the changed code against each check below. Skip checks that don't apply to the code at hand. For detailed explanations and fix examples, read

references/checklist-details.md

.

BUG — Will Cause Errors

#	Check	What to look for
B1	Missing `columns` parameter	Any `.list()` or `.get()` call without a `columns` property. Without it, only `id` is returned.
B2	`limit: 0` in query payload	`limit` set to `0` causes an API error. Remove `limit` entirely or set a positive integer.
B3	Child query key not in `columns`	If `childQueries` defines key `orders` , the string `orders` must also appear in `columns` .
B4	Formula key not in `columns`	If `formulas` defines key `total` , the string `total` must also appear in `columns` .
B5	Aggregation via `@` column syntax	Using `count@field` or `sum@field` in columns. Use the `calculations` parameter instead.
B6	`distinctColumns` with `calculations`	These are mutually exclusive. Use `calculations` for aggregation.
B7	Formula `extract` input count	`extract` blocks must have exactly 1 input.
B8	Formula `not` operand count	`not` blocks must have exactly 1 operand.
B9	Formula `and` / `or` operand count	`and` / `or` blocks must have at least 2 operands.
B10	Formula math operand count	Math operations ( `+` , `-` , `*` , `/` , `%` ) must have at least 2 operands.
B11	Formula `case` without `when`	`case` expressions must have at least 1 `when` clause.
B12	Uncast literal in `jsonb_build_object`	String literals inside `jsonb_build_object` need explicit `"cast": "text"` — auto-cast only works inside `concat` / `concat_ws` .

PERFORMANCE — Degrades Speed or Wastes Resources

#	Check	What to look for
P1	Unnecessary `limit` on aggregation queries	When using `calculations` without needing raw rows, don't send `limit` . Aggregation returns a single grouped result naturally.
P2	`fullCount` just to get a total count	If you only need the count (not the rows), use `calculations: [{ func: 'count', field: 'id', name: 'total' }]` instead of `fullCount: true` with row fetching.
P3	Unnecessary `columns` on calculation-only queries	When using `calculations` and only reading aggregated values, don't send `columns` . The calculation result is returned without needing column selection.
P4	Over-fetching columns	Columns selected in `columns` but never read in the consuming code. Only select what you render or process.
P5	Large `limit` without pagination	`limit` > 200 without `offset` / `fullCount` pagination risks slow responses and high memory usage.
P6	Missing `expand` causing N+1	Rendering relation/enum/user field `.name` but not including that field in `expand` . Without `expand` , you get only the ID.
P7	Fetching rows for existence checks	Fetching records just to check if any exist. Use `calculations` count instead.
P8	Redundant overlapping queries	Multiple queries on the same data source fetching overlapping columns that could be combined into one.

CODE QUALITY — Causes Maintenance Pain

#	Check	What to look for
Q1	Heavy `as` type assertions on responses	Casting API responses with `as Array<...>` without runtime validation. Prefer typed collection return types or add validation.
Q2	Missing `enabled` on dependent queries	`useQuery` that depends on a runtime value (e.g., `recordId` ) but lacks `enabled: !!recordId` . The query fires with `undefined` .
Q3	No error handling on mutations	`.create()` , `.update()` , `.delete()` calls without try/catch or error feedback to the user.
Q4	Missing query invalidation after mutations	After create/update/delete, related query keys must be invalidated so lists refresh.
Q5	Serial cache invalidations	Multiple `await queryClient.invalidateQueries(...)` in sequence. Use `Promise.all()` for independent invalidations.
Q6	Using deprecated `expandTypes`	Replace with the `expand` parameter.
Q7	Hardcoded data source paths	Raw `client.get('/v1/apps/base/data-sources/project/items')` instead of using generated collection hooks.
Q8	`distinctColumns` without `orderBy`	`distinctColumns` requires `orderBy` to define which row wins per group.

How to Run

Identify all files changed in this task that contain Docyrus API calls

For each file, scan for

.list(

,

.get(

,

.create(

,

.update(

,

.delete(

,

client.get(

,

client.post(

,

client.patch(

,

client.delete(

Check each call site against the BUG checks (B1-B12)
Check query payloads against PERFORMANCE checks (P1-P8)
Check surrounding code (hooks, error handling, invalidation) against CODE QUALITY checks (Q1-Q8)
Fix all issues found, starting with BUG category

References

references/checklist-details.md
— Detailed explanation, detection pattern, and before/after fix example for every check item