İstinad vərəqi

Read this repository and draft a rules file for AI agents:

- the stack, and how to run, build and check it
- the folder structure and what belongs where
- the invariants (who owns auth and identity, where authorization happens)
- conventions visible in the existing code (naming, comments, i18n)
- a «never do» list drawn from past bugs in the git history

Keep it under 150 lines. Only include what isn't obvious from the code.

Audit my agent setup before we start working.

- Read the rules file. Which lines are generic advice that changes nothing?
  Propose cuts, and say what is missing that only this project knows.
- List every tool and MCP server available to you, and what each one could
  reach at worst. Flag any that can write outside this repository.
- List the commands allowed to run without asking me. Flag anything that
  deploys, deletes, or sends data anywhere.
- Propose a smaller set that still lets us work, and say what we lose.

I will describe a problem in plain words. Before fixing anything:

1. Restate it as a precise technical hypothesis:
   which component, which state, what mismatch.
2. Name the class of problem (the terms engineers use for it).
3. Tell me how to confirm or rule out the hypothesis
   (a log, a query, a request) — then do that and show me the result.

Only after the hypothesis is confirmed, propose a fix.

Problem: <...>

Write a technical spec for <feature>. Include:

- Goal and non-goals
- Data model changes; for every nullable field, what null means
- API endpoints: method, path, who may call it, what it returns on error
- Edge cases and failure modes
- Acceptance criteria I can check by hand
- An implementation plan in steps; each step independently verifiable

Ask me any question the spec cannot answer on its own. Do not write code.

Summarise the uncommitted changes:
- group them by purpose
- flag anything unrelated to <task>
- flag anything that looks mechanical but changes behaviour
  (encoding, escapes, whitespace in strings, generated files)
- propose how to split them into small commits, with messages
  that say why, not what.

We have a conflict between two branches that were each written
with an AI from different prompts.

- Summarise what each side was trying to do, in one sentence per side.
- List the places where the two intents contradict, not just where the lines
  collide — including files that merge cleanly but assume different things.
- Propose which intent survives and why, and what the merged code must do
  that neither side does today.
- After the merge, name the check that would have caught this contradiction.

Review this diff as a sceptical senior engineer. Rank findings by severity.

Check: trust boundaries, where identity comes from, error paths,
new state and who owns it, N+1 queries, unnecessary re-renders,
leaked resources (listeners, timers, subscriptions), and comments
that don't match the code.

For each finding give a concrete failure scenario:
inputs or state -> what goes wrong. Skip style.

Explain <concept> to me using code from THIS repository, not a generic example.

- Show where it matters here (file:line).
- Show one bug it could cause here.
- Show how I would spot that bug in a diff.

Then ask me three questions to check I understood, and wait for my answers.

Act as a security reviewer. For every API endpoint in <path>:

- Who is allowed to call it? Where is that checked (file:line)?
  If it is only checked in the UI, flag it.
- Where does the caller's identity come from? Flag any id, key, role
  or owner taken from the body, the query string, or any header other
  than the verified session. Include fallback paths.
- For endpoints that take a resource id: is ownership or membership
  checked on the server?

Output a table: endpoint | authn | authz | identity source | verdict.

Review the auth flow end to end: sign-up, login, logout,
password reset, email verification.

For each step:
- What is rate limited, and what exactly is counted (success or failure)?
  Is the counter written, not just read?
- Could an attacker learn whether an account exists?
- Where is PII (email, IP) stored, shown or logged, and for how long?
- How is the session sent (cookie attributes, header), and does that
  work across the domains we actually deploy to?

List concrete failure scenarios, not general advice.

Before writing any code, produce an architecture note for <feature>.

1. Components: list each module/file and its single responsibility.
2. Data ownership: for every piece of state (tokens, ids, user data, cache),
   name the ONE module that owns it. Everything else reads through that owner.
3. Data flow: show the direction (client -> API -> DB, and back).
   Mark every trust boundary.
4. Out of scope: what this feature will not do.

Do not write implementation yet. Stop and wait for my approval.

Audit this codebase for duplicated sources of truth.

For each of: auth token, user id, user profile, permissions,
server data cached on the client:
- list every place it is stored or computed (file:line)
- say which one is authoritative
- flag any function that is defined but never called
- flag any comment that describes behaviour the code does not perform

Report only; do not change code.

For <component>, list every network call. For each one, show
what the user sees on:
  success | 401/403 | 4xx validation error | 5xx | timeout | offline

Where state is updated optimistically, show the rollback path
and the message the user gets.
Where a request is retried, is the operation idempotent?
Where the UI claims something happened, is that claim true in every branch?

Then implement the missing cases.

Review the data layer:

- List every query executed per page load and per API call.
  Flag loops that query once per item (N+1).
- For each WHERE and ORDER BY, is there an index?
- Which values can two requests change at once? Show how each stays
  correct (transaction, constraint, atomic update).
- Which states should be impossible (negative counts, duplicate votes)?
  Does the database refuse them, or only the code?
- Which tables grow without bound? Propose a retention rule.
- Compare the heaviest operation with the platform's CPU and memory limits.

Before choosing a library for <task>, check it against the platform.

- Platform: <e.g. Cloudflare Workers, free plan, 10 ms CPU per request>.
- Write a micro-benchmark for the heaviest operation and report CPU time
  per call (not wall time), on the real runtime if possible.
- If it doesn't fit, list the options in order: a cheaper algorithm,
  a native platform API (Web Crypto, streams), WASM, moving the work
  to the client, a queue or a scheduled job. For each, say what it costs
  in security or user experience.

Never choose a Node-only library for an edge runtime without saying so.

Profile <page or endpoint> before optimising anything.

- Record a performance trace of <interaction>; list every long task
  (over 50 ms) with the function it comes from.
- Take a heap snapshot, repeat <action> ten times, take another;
  list what grew and what still references it.
- For each finding, propose one fix (a Web Worker, chunking, memoizing,
  removing a listener, bounding a cache) and the measurement that will
  prove it worked.

Don't change code until I've seen the numbers.

Model <feature> as a finite state machine before writing any UI.

- List every state by name, and the data that exists only in that state.
- List every event and the transition it causes; anything not listed is forbidden.
- Mark guards (conditions on a transition) and side effects (what runs on entry).
- Express it in TypeScript as a discriminated union plus a pure
  transition function.
- Write a table test that walks every allowed transition and asserts
  that at least one forbidden one is refused.

Build <simulation> with the model separate from the drawing.

- First state the law(s) as equations, with units, and the sign conventions.
- Model: a pure function step(state, dt) -> state, with a fixed timestep
  and a named integration method (say why that one).
- Randomness only through a seeded RNG, so any run can be replayed.
- View: draws the state and never changes it.
- Checks: compare the model against at least two known answers
  (a closed-form case, a conservation law) within a stated tolerance,
  and show the result with dt halved.

Before you fix <bug>:
1. Write a check that reproduces it, run it, and show me it fails.
2. Fix it.
3. Run the same check and show me it passes.
4. List every other code path that could produce the same bug —
   fallbacks, other endpoints, other callers — and check those too.

Do not tell me it is fixed until step 3 has output I can read.

Write a check script for this invariant: <rule>.

- It must exit non-zero on a violation and print the file:line that broke it.
- Add it to the aggregate check command.
- Then deliberately break the rule once, show me the check catching it,
  and revert the break.

<feature> depends on a model's output. Bind it to a contract.

- Define the schema the output must satisfy: fields, types, ranges,
  and what is optional. Validate it at the boundary, before use.
- Write contract tests: a valid output passes; a renamed field, a missing
  field, an extra explanation and an empty answer each fail loudly.
- Show the fallback path for a failed contract, and what the user sees.
- Say where the model version is pinned, and what we run before changing it.

Write a deployment runbook for this project:

- how to deploy each part, and how to verify it is live
- how to roll back, and roughly how long that takes
- which secrets exist and where each one is set (never their values)
- what to check in the logs after a deploy
- everything that differs between local and production
  (domains, cookies, CPU and memory limits, environment variables)
- every AI API call the app makes: which model, how often,
  and an estimated monthly cost

We will audit this project in passes. This pass: <architecture | security | data | failure modes | tests>.

- Produce findings with file:line, severity, and a concrete failure scenario.
- Verify each finding against the code before reporting it;
  drop anything you cannot confirm.
- Then propose a remediation plan ordered by severity,
  in small, independently verifiable steps.